Tools transfer vs prebuilt images: shim-proof probe, per-tool payload, version drift

[blooop]

Question

How should ensure_tools (devlaunch/tools.py) behave when the container image already carries the lent tools — and how do we make that path trustworthy — so a prebuilt image genuinely skips the ~342MB transfer?

Current facts (verified on main at f03158b):

• The probe (_probe, tools.py:344-359) is one devpod ssh --command "bash -lc 'command -v gh && command -v claude'" — so an image with both tools on the login-shell PATH already skips the transfer today. That half of the candidate is done.
• But the probe cannot tell a real claude from claude-shim — and the repo's own devcontainer feature installs the shim (.devcontainer/claude-code/install.sh:107, "Claude binary will be downloaded on first run"). An image baking the shim passes the probe and the user pays the ~285MB GCS download at first run — exactly the cost the lending exists to avoid.
• The payload is all-or-nothing (host_payload, tools.py:256-274): an image with only gh still receives both binaries.
• No version awareness: an image with an ancient claude is left alone forever; no checksum/marker exists despite CHANGELOG.md:69 claiming "checksum-verified".
• When the transfer runs it prepends $HOME/.local/bin to PATH (tools.py:291-293), shadowing image-provided tools on later launches.
• Only opt-out is DEVLAUNCH_NO_TOOLS (machine-wide).

Decide, against the principles (maintainability > simplicity):

1. Should the probe distinguish a shim/stale tool from a usable one — and by what test (e.g. claude --version exit + output shape vs a marker file vs accepting the shim)?
2. Should the payload become per-tool instead of all-or-nothing?
3. Is version-drift (image has old tool, host has new) in scope, or explicitly accepted and documented?
4. What does the README/CHANGELOG say afterwards (README.md:294-299 is stale — still describes pixi-global install)?

The resolution must state how each accepted behavior will be tested (probe-script unit tests exist at test level today; extend the same seam). Any code change graduates as build ticket(s) on this map — this ticket only decides.

[blooop]

breadcrumb: grilling started — fresh subagent resolving against the principles; sweep confirmed the login-PATH probe already skips the transfer, so the open questions are shim detection, per-tool payload, version drift, docs.

[blooop]

agent-decided (maintainability): the probe becomes a three-state answer — provisioned / lendable / absent — where claude counts as provisioned only in the official install layout, the same definition _claude_source already applies on the host. Payload stays all-or-nothing; version drift is explicitly out of scope; README and the unreleased CHANGELOG claim get corrected. No markers, no checksums, no version RPC.

Claims verified (main @ f03158b)

Every factual claim in the ticket checks out, with two refinements:

• Probe is one bash -lc 'command -v gh && command -v claude' over devpod ssh — _probe, devlaunch/tools.py:344-359. ✓
• The repo's own devcontainer feature installs the shim and defers the real binary: .devcontainer/claude-code/install.sh:79-81 installs claude-shim, :84-100 puts it on the login PATH, and :102-107 deliberately verifies only the trampoline — "(Claude binary will be downloaded on first run)" is install.sh:107. So a shim image passes today's probe while still owing the ~285MB GCS download. ✓
• Transfer payload is all-or-nothing — host_payload, tools.py:256-274 returns None unless both tools resolve. ✓ Refinement: the network fallback is already per-tool — each install in provision_script is guarded by its own command -v (tools.py:110-117) — so "per-tool" only ever meant the transfer.
• No version awareness anywhere; the string checksum appears nowhere in devlaunch/. CHANGELOG's "checksum-verified" is at CHANGELOG.md:68 (not 69), and it sits under ## [Unreleased] (line 8; next release heading at 144) — correctable in place, no erratum entry needed. What the code actually does is stronger for the failure that matters: it executes both lent binaries in a staging dir before touching the container (tools.py:315-319).
• The transfer prepends $HOME/.local/bin to the login PATH — tools.py:288-294. ✓ (Reframed below: this shadowing is the mechanism that makes shim replacement stick, not a defect.)
• Only opt-out is machine-wide DEVLAUNCH_NO_TOOLS — tools.py:56-57. ✓
• README.md:294-299 describes only the pixi-global network install; the lending fast path and any image contract are undocumented. ✓
• One fact that shapes everything: ensure_tools runs only on devpod up — the fast-attach path skips it entirely (tools.py:34-37). Probe cost is never on the warm-attach path this map is trying to shrink.

Q1 — Shim-proof probe: yes, by layout, never by execution, never by marker

Decision (maintainability): the probe reports provisioned only when gh is on the login PATH and readlink -f "$(command -v claude)" resolves under $HOME/.local/share/claude/versions/. That is byte-for-byte the definition the host side already committed to in _claude_source (tools.py:211-228), with its rationale already written down: "Anything else on PATH answering to claude — the pixi shim, a wrapper script — is exactly the kind of downloader this transfer exists to skip." One definition of "usable claude", stated once per side of the pipe, sharing one module constant for the layout path. Whoever reads this in a year finds a single concept, not two probes with different opinions.

Alternatives weighed:

• Run claude --version in the probe — rejected. On the shim, any invocation triggers the ~285MB download: the probe would inflict the exact cost it exists to detect. It would also tax every cold up's first trip for all containers.
• Marker file written by devlaunch — rejected (constructive modeling, and it fails the map's own goal). A marker is parallel state that can drift from the filesystem truth it duplicates, and an image built with the official installer in its Dockerfile — the exact prebuilt image this map wants to reward — carries no marker and would be transferred over anyway.
• Accept the shim (status quo) — rejected; it is the headline problem.
• Stricter boolean (layout-or-nothing) — rejected, and this is the trap that forced the three-state design: a workspace the network fallback provisioned with the shim, or a musl container that rejects the lend, would fail a strict boolean probe on every subsequent up and re-pay a failing 342MB transfer each time. A perf map must not buy one image class a saving by charging another class per-launch.

So the probe prints one of three tokens (exit 0 in all three states — which also retires the red devpod fatal line the current probe's everyday failure paints, tools.py:347-351):

• provisioned — gh present, claude in the official layout → done, 1 trip. This is the prebuilt-image jackpot the map wants: bake gh on the login PATH and claude via the official installer layout, and dl does zero provisioning work.
• lendable — both present but claude is a shim/wrapper → transfer if host_payload() has something to lend (replacing the shim: the transfer's ~/.local/bin PATH prepend, tools.py:288-294, is exactly what makes the real binary win from then on — next up probes provisioned). If the transfer fails or the host has nothing to lend, accept and stop: a claude answers, gh answers, and the network fallback would early-exit on its own command -v guard anyway (tools.py:132-134, 168) — skipping it saves that trip.
• absent — today's cold flow, unchanged: transfer, else network fallback.

Python side: a ProbeResult sum type replacing the boolean (constructive modeling — three legal states, no bool+flag pair), parsed totally: an unrecognized or failed answer maps to absent, whose worst case is redundant idempotent work, never a wrong skip.

Accepted residual, to be written as a code comment: the intersection musl/old-glibc container × host with a payload × shim on PATH re-attempts a ~5s failing transfer per devpod up. It rides only the up path, which already "ran for seconds to minutes" (tools.py:30), never fast-attach; breaking the loop would need persisted per-container retry state — more machinery than the case is worth. Broken-but-real image-baked binaries stay out of scope: the probe never executes the candidate, and a binary the image author baked broken is the image author's bug (devlaunch's own installs are already execution-gated).

Q2 — Per-tool payload: no

Decision (simplicity): all-or-nothing stands, exactly as the code already argues (tools.py:259-261: no "matrix of half-lent states that the fallback script would then have to reason about") and as the suite already pins (test_the_payload_is_all_or_nothing, test/unit/test_tools.py:358-363). The network fallback is already per-tool, so nothing is ever double-installed on that path. The entire benefit of per-tool transfer is shaving the redundant slice of a 5.1s local copy, paid once per workspace — after a transfer the tools persist in $HOME and every later up probes provisioned. The map's goal — a prebuilt image reliably skipping the transfer — is met by baking both tools, and Q4 documents that contract. Per-tool would add per-tool probe answers, per-subset payload construction, and per-subset transfer scripts to a module whose docstring already priced that trade and declined it.

Q3 — Version drift: out of scope, explicitly accepted and documented

Decision (simplicity, bounded by the map's own scope line — "not a package manager"): a present-and-real tool is left alone regardless of version. Comparing versions turns "lend when missing" into "keep in sync", which drags in direction logic (image newer than host — downgrade?), a version story for gh (which carries none — no layout encodes it), and a re-transfer to every workspace on every host upgrade. Mitigations that already exist and cost nothing: the official claude binary self-updates in long-lived workspaces, and a workspace rebuild re-provisions from scratch. One deliberate side effect of Q1 is the only upgrade path this design ships: a shim is replaced by the host's real binary. A documented non-goal a reader can trust beats a half-built sync (maintainability).

Q4 — Docs

• README.md:286-314 ("Tools in every workspace") is rewritten around the three-trip flow, and states the prebuilt-image contract in one place: to skip all provisioning work, bake gh anywhere on the login PATH and claude in the official installer layout (~/.local/share/claude/versions/<v> + ~/.local/bin/claude symlink); a shim does not count and will be replaced by a lend of the host's real binary when the host has one. It names the two accepted costs from Q2/Q3 and notes the ~/.local/bin shadowing as intended behavior.
• CHANGELOG.md:68: "checksum-verified" → the truth: both lent binaries are executed in a staging directory and nothing lands in the container until they prove they run there (tools.py:315-319). Legal to amend in place — the entry is still under [Unreleased]. No checksum gets added: the stream is a local pipe over the ssh channel, and the execution gate catches the failure a checksum would (and the ones it wouldn't).

Test plan — seam: test/unit/test_tools.py, extended in kind

The module's seam is generated-script string assertions (TestProvisionScript, TestTransferScript), scratch-home layouts (TestHostPayload), and the Runner fake for the trip flow (TestEnsureTools). The probe joins it:

1. Extract a pure probe_script() beside provision_script/transfer_script. String tests: contains readlink -f and the shared versions-dir constant; contains no invocation of the candidate claude — shim-proofness is "never runs the candidate", assertable as a string property.
2. Behavioral bash runs against scratch $HOMEs (built exactly like TestHostPayload's layouts): official layout → provisioned; pixi-shim script on PATH → lendable; empty → absent; and the layout transfer_script itself creates → provisioned (convergence: a lend satisfies the next probe).
3. Flow tests via Runner: lendable + payload → exactly 2 trips, trip 2 streams the tar; lendable + transfer fails → 2 trips, returns True, no third trip; lendable + no payload → 1 trip, True; existing absent-flow tests stay green; test_a_provisioned_workspace_pays_one_probe_and_nothing_else (test_tools.py:188-197) updates to the token protocol and keeps pinning Q3's "present tools are left alone".
4. Decisions pinned by existing tests: test_the_payload_is_all_or_nothing (Q2) must stay green untouched.
5. Docs: a doc-guard test in the style of test/test_agents_doc.py (which already guards "statements a reader would act on") pinning the one actionable claim — README's tools section names the official layout path via the shared module constant — and that checksum no longer appears in the [Unreleased] CHANGELOG section.

Build tickets (2, sequential — B depends on A's constant)

Ticket A — Three-state tools probe: only the official claude layout counts as provisioned

Question

_probe (devlaunch/tools.py:344-359) answers "provisioned" to any claude on the login PATH, including the claude-shim downloader this repo's own devcontainer feature bakes (.devcontainer/claude-code/install.sh:107) — so a shim image skips the lend and pays the ~285MB GCS download at first run. Decided on #141: the probe becomes three-state, and only the official install layout counts as provisioned.

Behavior:

• New pure probe_script() beside provision_script/transfer_script, printing exactly one token and exiting 0 in every state (the red devpod fatal from the current probe's everyday cold failure disappears): provisioned — gh on PATH and readlink -f "$(command -v claude)" lands under $HOME/.local/share/claude/versions/; lendable — both on PATH but claude is not that layout; absent — otherwise.
• The probe must never execute the candidate claude: running the shim triggers the very download the probe exists to detect.
• Python side: a ProbeResult sum type (enum) replaces the boolean; parsing is total — any unrecognized or failed answer maps to absent (provisioning is idempotent, so the worst case is redundant work, never a wrong skip).
• ensure_tools flow: provisioned → done, 1 trip. absent → unchanged (transfer, else network fallback). lendable → transfer if host_payload() exists; on transfer failure or no payload, return True with no network-fallback trip (a claude already answers; the fallback would early-exit on its own command -v guard anyway). Accepted residual, comment it in the code: a container that keeps rejecting the lend (musl/old glibc) with a shim on PATH re-pays a ~5s failing transfer per devpod up — ensure_tools never runs on fast-attach, so this rides only the already-slow path.
• Extract the versions-dir relpath (.local/share/claude/versions) into one module constant shared by _claude_source, transfer_script, and probe_script — one definition of "official layout" on both sides of the pipe.
• CHANGELOG [Unreleased] entry for the behavior change.

Failing tests first (seam: test/unit/test_tools.py — script-string assertions, real-bash runs against scratch $HOMEs as in TestHostPayload, and the Runner fake):

• probe_script string tests: contains readlink -f and the versions constant; contains no invocation of the candidate claude.
• bash-behavioral: run probe_script with HOME=tmp_path — official layout → provisioned; pixi-shim script on PATH → lendable; empty → absent; the layout transfer_script creates → provisioned (a lend satisfies the next probe).
• ensure_tools flow: lendable + payload → exactly 2 trips, trip 2 streams the tar; lendable + transfer fails → 2 trips, returns True, no third trip; lendable + no payload → 1 trip, True; existing absent-flow tests stay green; test_a_provisioned_workspace_pays_one_probe_and_nothing_else updates to the token protocol.
• test_the_payload_is_all_or_nothing must stay green untouched — Tools transfer vs prebuilt images: shim-proof probe, per-tool payload, version drift #141 affirmed all-or-nothing.

Pointers: devlaunch/tools.py (:344-359 probe, :385-439 ensure_tools, :211-228 _claude_source, :277-329 transfer_script), test/unit/test_tools.py.

Ticket B — Document the lending contract; fix the unreleased "checksum-verified" claim

Question

README's "Tools in every workspace" (README.md:286-314) still describes the pixi-global network install as the only mechanism (README.md:294-299) — the host-lending fast path and the three-state probe (#141, previous ticket) are undocumented, so an image author cannot know what to bake to skip provisioning. CHANGELOG.md:68 claims the transfer is "checksum-verified"; no checksum exists — the gate is execution-verification in a staging dir (devlaunch/tools.py:315-319). The entry is under [Unreleased] (CHANGELOG.md:8), so it is corrected in place.

Behavior:

• Rewrite the README section around the three-trip flow (probe → host lend → network fallback) and state the prebuilt-image contract in one place: to make dl do zero provisioning work on up, bake gh anywhere on the login PATH and claude in the official installer layout (~/.local/share/claude/versions/<v> + ~/.local/bin/claude symlink). A shim does not count: it is detected and replaced by a lend of the host's real binary when the host has one. Note that this repo's own devcontainer feature (.devcontainer/claude-code/install.sh) installs a shim, so an image built from it does not meet the contract by itself.
• State the accepted non-goals from Tools transfer vs prebuilt images: shim-proof probe, per-tool payload, version drift #141: no per-tool transfer (a half-provisioned image pays the full ~5s lend once per workspace), no version sync (a present real claude is left alone whatever its version — claude self-updates, and a workspace rebuild resets it).
• Note the PATH consequence as intended: a lend prepends ~/.local/bin, which is what makes the lent real binary shadow a baked shim thereafter.
• CHANGELOG.md:68: replace "checksum-verified" with what the code does — both binaries proved to run in a staging directory before anything is moved into place.

Failing test first (seam: the doc-guard style of test/test_agents_doc.py — guard only the statements a reader acts on): assert README's tools section contains the official layout relpath via the module constant from the previous ticket, and that "checksum" no longer appears in the [Unreleased] CHANGELOG section.

Pointers: README.md:286-314, CHANGELOG.md:8 and :68, devlaunch/tools.py (shared constant), test/test_agents_doc.py (style).

Findings for the rest of the map

• ensure_tools never runs on fast-attach (tools.py:34-37): the warm dl <spec> -- <cmd> path this map targets does not touch tools.py at all. Probe micro-optimizations aim at the wrong place; attach-path latency work should look elsewhere.
• Any prebuilt-image ticket on this map must not bake .devcontainer/claude-code/install.sh as-is and expect zero transfer: it installs the shim, which by this decision probes lendable, not provisioned. A zero-work prebuilt image bakes the official installer layout instead.
• CHANGELOG's "checksum-verified" being under [Unreleased] means the correction ships silently with the next release — no erratum needed anywhere else.

[blooop]

breadcrumb: resolution recorded (agent-decided); graduated into build tickets #151 (three-state probe) and #152 (lending-contract docs, blocked by #151). Closing.