fix(shim): stop the shim claiming work it did not do (0.8.2, PR-2)

[temrjan]

Stacked on #86 — base retargets to main once that merges.

The one that matters: the purge gate ran after the teardown

uninstall --purge-keys through a pipe or an agent refused correctly — after deregistering the clients, stopping the wallets, deleting the secrets, removing the PATH block, deleting the shim itself and wiping the config dir.

The keys survived. The installation did not, and the user was left without the command that manages them. A gate that fires after the damage is not a gate.

The tty gate and the volume listing now run first, before a single mutation. Deletion itself stays last — the data-safe order is unchanged, only the gate moved. Acceptance is the tester's probe-03-purgekeys-order.sh: 4/4, was 1/4.

Teardown no longer reports work it failed to do

before	now
stop … || true + unconditional "stopped N running wallet(s)"	counts what actually stopped, names what did not — and a wallet still running is exactly what makes a later volume removal fail
volume rm … && echo — a refusal printed nothing and exited 0	each surviving volume named, command fails
docker password files claimed removal whether any existed or the removal worked	reports what actually happened

The RPC guarantee is stated as it is

--help promised a keyed URL "stays out of argv, agent configs and podman inspect". That holds only after connect has stored it as a secret. Before that — and on every docker run — the value is forwarded by name and the engine records it in container metadata, readable by anything running as the user.

All three cases are now spelled out, and start warns at the moment it takes the exposed road. Closing the leak in code is deferred to the next release by ratification; the text stops overclaiming today.

⚠️ Landmine worth a reviewer's eye: wallet_run_args emits argv on stdout, so the warning had to go to stderr — a say there would have become an argument to podman run. There is a test asserting both the warning text and that argv still carries only -e NAME.

Quoting, at the point the words are built

The password mount was a word-split fragment carrying a real filesystem path. A $HOME or $XDG_CONFIG_HOME containing a space tore it into three argv tokens — corrupting init, start, and permanently freezing a broken argv into the client's MCP config on connect. The helper is gone; the three call sites append quoted words.

The 101 byte-exact argv tests passed unchanged through this refactor, which is what made it safe to do at all.

Diagnostics stopped writing

doctor and status created the engine config as a side effect of being run. They no longer persist anything, and doctor no longer calls the engine "pinned" when nothing has pinned it. Both now distinguish "no wallet has ever been created" from "one exists but is not running" and point a fresh install at rustok init — previously six green ok: lines told a new user nothing about the next step.

--help also stops advertising a "leftovers" sweep; what doctor really checks is stray containers, so that is what it says.

update says what it is not doing

One stderr line at pull time: it pulls by mutable tag and does not re-verify the signature — the installer is the verified path. Same "tell the truth at the moment the guarantee drops" pattern as the start warning. Deep verify-on-update stays in the backlog.

Versions

0.8.2 across the six points, plus the SKILL.md body tags and the install-URL tag. The shim's own axis goes 0.3.0 → 0.3.1 — its commands changed behaviour, and that axis has no guard test, so it is called out explicitly.

Tests

13 new cases, each proven red first. Two pre-existing tests were updated because the contract deliberately changed, and I am flagging that rather than burying it:

• engine pinning is asserted through a state-changing command instead of status (diagnostics no longer pin);
• the empty-machine status text is the new wording.

Also fixed two of my own test defects mid-flight: an assertion that checked for a prefix already present in earlier output (it could not fail), and a --help grep that missed the overclaim because the promise is split across a line break.

Gates

All nine locally: ruff · mypy · pytest 188 · shellcheck ×2 · shim 114/114 · install 28/28 · bash -n + sh -n · hadolint.

Deferred and recorded in the spec with test locations: the RPC leak in code, per-subcommand --help (12 commands, plus connect swallowing --help as an agent name), and an early exit for update with no registrations — that last one needs the client-discovery loop duplicated before the pull, which is surgery, not a tweak.