docs(clone): one-directional insteadOf rationale, unverified --env version floor, and an undocumented host-fetch residual risk #469

Post-merge follow-ups to #455 / #457. None of these is a code defect.

D1. insteadOf rationale is one-directional

acq.backends/msb.sh:2449-2452 and docs/adr/0027-neutral-clone-option.md:134-137
justify copying raw URLs with "an https->ssh rewrite would hand the guest a
transport it has no key for". The mirror case breaks identically: a host
url.https://....insteadOf ssh:// rewrite (common for token auth) means the raw
value IS the ssh form, so the guest gets exactly the unusable transport the raw
choice was meant to avoid. Only user.* reaches the guest's global tier, so
nothing corrects it there.

Raw is still the right default. Suggest the docs say a host rewrite in EITHER
direction leaves the guest with a transport it cannot use.

D2. --env used unconditionally, verified only above the declared floors

MIN_MSB_VERSION=0.6.9 / MIN_SBX_VERSION=0.38.0, but PR #457 verified --env
on msb 0.6.17 and sbx 0.42.1. (Reviewer confirmed -e, --env exists on msb 0.6.15
and sbx 0.42.1; could not check msb 0.6.9 or sbx 0.38.0.)

The repo's own precedent is to gate — MIN_MSB_VSOCK_VERSION exists for exactly
this reason. Unlike vsock, an unknown flag here does not degrade a feature, it
fails the WHOLE create for a floor-compliant user. Either state that --env
exists at both declared floors, or gate it.

D3. For docs/KNOWN_FAILURE_MODES.md — residual risk, NOT a vulnerability

acq correctly never runs git inside the guest-writable msb scratch. Verified by
reading merged main: only msb.sh:2422 (clone) and :2468 (config) touch it, both
strictly before msb create at :3017; _acq_msb_clone_warn_unfetched reads ref
FILES via find/cat/awk (:2494, :2498) and runs cat-file against the REAL repo
(:2505), with guest-supplied SHAs hex-filtered at :2504. The invariant holds.

However, the recovery command the code itself advertises (msb.sh:2436
git fetch sandbox-<name>; remote registered at :2431) DOES spawn git upload-pack inside the guest-writable scratch and DOES read its config. Proved
locally with plain git: a scratch-local uploadpack.hideRefs changed what the
host's ls-remote advertised.

Probed and NOT exploitable on git 2.50.1:

• core.alternateRefsCommand + objects/info/alternates — did NOT execute (tried
  both an object-transferring fetch and a bare ls-remote)
• uploadpack.packObjectsHook — did NOT execute (protected-scope only)
  Control: --upload-pack confirms upload-pack IS spawned for a local-path remote.

So this is documented residual risk, not a demonstrated vuln. Worth one honest
paragraph beside :2436, because git's own man page says "the surface area for
attack against upload-pack is large, so this does carry some risk", and
safe.directory offers no protection here — the scratch is owned by the invoking
user.

D4. Already tracked elsewhere — do not file separately

The two new bare tracker refs (msb.sh:2963, sbx.sh:467) are in scope for the
existing open issue #414 (repo-wide sweep of ephemeral refs in code comments).

D5. Vestigial, pre-dating these PRs

Two defined-but-uncalled functions, zero callers repo-wide, both from fbd57be:

• strip_backend_flag / STRIPPED_ARGS (common.sh:809-824) — the dead half of
  --backend handling, and the reason a post-subcommand --backend is never
  stripped from the backend argv
• _acq_sbx_exec_retry (sbx.sh:366-377)

(The #455 rename was clean: _acq_msb_clone_copy_identity has zero references.)

Withdrawn after live verification

An earlier draft of this issue claimed the sbx --clone marker path was
unverified and possibly wrong. It is correct. Verified against sbx 0.42.1:
sbx create --clone mounts the in-container clone AT the original host path (the
clone is the cwd; .git/config device:inode differs from /run/sandbox/source,
guest writes stay in the guest, the ro source refuses writes). And on a symlinked
path (/tmp -> /private/tmp) the guest's WORKSPACE_DIR is the LOGICAL
/tmp/..., matching acq's cd && pwd idiom exactly — so the deliberate choice of
pwd over pwd -P at sbx.sh:476 is right, and the comment at :469-473 is
accurate. No action.

Attribution

Found during an AI-assisted (OpenCode) adversarial post-merge review of PRs
#455 and #457. Advisory — confirm before acting.