Track msb vsock/unix-socket forwarding (#1297) to unblock git-ssh-sign on the msb backend #303

What this tracks

Follow the upstream microsandbox (msb) work that unblocks host ssh-agent /
host unix-socket forwarding into a guest, and land the acq changes that make
the git-ssh-sign kit work on the msb backend — currently an sbx↔msb
parity gap.

On sbx, the host ssh-agent is forwarded into the sandbox by default, so
git-ssh-sign "just works": in-guest git/ssh sign and authenticate with the
developer's already-unlocked host keys, and no private key material ever enters
the sandbox. On msb there is no equivalent forwarding, so a guest connect()
to a forwarded socket cannot reach the host agent — leaving the signing kit
non-functional on msb.

This is the last behavioral piece needed for a git-ssh-sign kit to declare
backends: [sbx, msb] (see the parity epic, #234).

Upstream situation (why we were blocked)

We filed the request as
superradcompany/microsandbox#1290
("Expose libkrun vsock AF_UNIX socket forwarding as an msb flag"). We had
confirmed on msb 0.6.8 that every host-side approach was a dead end:

• bind-mount the socket (-v, --mount-file) — virtiofs shares the inode
  but the guest kernel's AF_UNIX stack services the connect() locally; it never
  reaches the host agent (and --mount-file rejects non-regular files);
• msb ssh connect native agent forwarding — guest reports
  Could not open a connection to your authentication agent;
• msb ssh serve + OpenSSH reverse/stream-local forward (ssh -R) — rejected
  by msb's SSH server (remote port forwarding failed for listen path …).

The primitive exists in bundled libkrun (virtio-vsock + TSI AF_UNIX) but was
unreachable from the msb CLI. Upstream closed #1290 in favor of the
longer-standing
superradcompany/microsandbox#663
("Allow creation of additional vsock/unix socket bridges from guest to host") and
committed to shipping the capability in the next release.

Upstream status to follow

• Expose libkrun vsock AF_UNIX socket forwarding as an msb flag (host ssh-agent / arbitrary host unix socket into guest) superradcompany/microsandbox#1290 — original request. CLOSED in
  favor of fix(msb): strip CR from jq output in acq ports (Windows) #663.
• Allow creation of additional vsock/unix socket bridges from guest to host superradcompany/microsandbox#663 — the accepted umbrella. CLOSED
  2026-08-11.
• feat(runtime): add scoped sockets and host vsock routes superradcompany/microsandbox#1297 — feat(runtime): add scoped sockets
  and host vsock routes. MERGED to main 2026-08-11 (merge commit
  e0c0f9ba7b3aace8061ed9171845cb9d92db4144). Adds guest→host virtio-vsock
  routes backed by Unix stream/datagram sockets, exposed as
  --vsock HOST_PATH:PORT[/stream|/dgram] (plus matching Rust/Python/TS/Go/Ruby
  SDK APIs), connecting directly through libkrun's typed vsock interfaces (no
  agentd proxy / TSI / guest IP networking).
• feat(vsock): expose host IPC routes across SDKs superradcompany/microsandbox#1304 — feat(vsock): expose host IPC routes
  across SDKs (was stacked on #1297). CLOSED / not merged separately — its
  content was folded into #1297; no residual SDK surface lands independently.
• A tagged msb release that contains #1297. v0.6.9 (2026-08-15)
  ships --vsock (merge e0c0f9ba is an ancestor of the v0.6.9 tag;
  confirmed live via msb --tree). The capability is now in a release.

Trigger to unblock our work

When a released msb (verified by msb --tree showing the --vsock flag, on a
tag ≥ the one containing #1297) is available, do the acq/kit work below.
Fired: msb v0.6.9 (2026-08-15).

Our follow-on work (blocked until the release lands)

• Confirm the released --vsock HOST_PATH:PORT[/stream|/dgram] surface against
  live msb --tree, and prove a host ssh-agent can be reached from inside a
  guest end-to-end (ssh-add -L in guest lists host identities; a signed
  commit verifies). Done: scripts/verify-backends (hermetic ephemeral
  agent) passed on a macOS/HVF host 2026-08-17 — the guest's forwarded agent
  exposed the exact ephemeral key (cryptographic identity match).
• Decide the neutral acq vocabulary for host-socket / ssh-agent forwarding
  (an ADR — sbx forwards implicitly, msb needs an explicit --vsock route +
  an in-guest shim / SSH_AUTH_SOCK export). Capture the widened host↔guest
  trust boundary and keep it opt-in. Done: ADR-0021
  (acq_host_socket_forwards neutral vocab + ACQ_FORWARD_HOST_SOCKETS;
  forwarding is opt-in, driven by the host SSH_AUTH_SOCK).
• Wire the msb adapter (acq.backends/msb.sh) to translate that neutral
  vocabulary to msb … --vsock $SSH_AUTH_SOCK:<port>/stream and export
  SSH_AUTH_SOCK in-guest so git-ssh-sign functions. Done: version-gated
  --vsock $SSH_AUTH_SOCK:3552/stream emission + in-guest socat bridge +
  SSH_AUTH_SOCK export on attach/exec/kit-exec.
• Let the git-ssh-sign kit declare backends: [sbx, msb] (kit lives in
  GSA-TTS/agentic-coding-patterns under integrations/isolation/acq-kits/).
  Done: the kit already declares backends: [sbx, msb];
  docs(git-ssh-sign): keep backend-parity prose backend-neutral agentic-coding-patterns#330 corrects its (previously inaccurate,
  now backend-neutral) parity prose.
• Bump the pinned msb version reference in docs and re-verify; update
  docs/BACKEND_GUIDE.md and docs/KNOWN_FAILURE_MODES.md (§22 signing +
  the msb-differences / limitations table). Done: BACKEND_GUIDE gains a
  git-signing/ssh-agent differences row + tunables + a >= 0.6.9 note (global
  MIN_MSB_VERSION floor intentionally stays 0.6.8; the feature is gated at
  0.6.9); KNOWN_FAILURE_MODES §22 flipped to "supported + verified" and new §34
  covers the socat/version failure mode.

Landed in #316 (acq + ADR-0021 + hermetic
verify-backends check) and GSA-TTS/agentic-coding-patterns#330 (kit prose).

Security note

Forwarding the host ssh-agent into a guest exposes every key the agent holds to
guest code. Our design keeps this opt-in (driven by the host SSH_AUTH_SOCK,
matching sbx's implicit signal; unset it to opt out), documents it as widening
the host↔microVM trust boundary (ADR-0021), and prefers agent-side confirmation /
constraints (ssh-add -c / -h) where available.

Links

• Parity epic: Epic: sbx↔msb backend parity #234
• Related msb port-publish follow-on: Post-hoc port publish on msb via ssh serve + ssh -L (gap K) #238
• Upstream: Expose libkrun vsock AF_UNIX socket forwarding as an msb flag (host ssh-agent / arbitrary host unix socket into guest) superradcompany/microsandbox#1290, fix(msb): strip CR from jq output in acq ports (Windows) #663, #1297, #1304