docs(B-0844): zflash --agent flag — close docstring-vs-implementation gap on agent-driven mode

[AceHack]

What

Empirical anchor 2026-05-26: 3rd USB re-flash session surfaced a docstring-vs-implementation gap in zflash.ts.

Operator authorized agent-driven zflash with Touch ID. Agent ran `bun zflash.ts | tail -50` which:

1. Generated nonce + printed challenge
2. Touch ID PAM gate fired (operator approved)
3. `readline.question("> ")` returned empty string (stdin closed by `| tail`)
4. flash-usb.ts bail'd silently (error swallowed by tail filter)
5. zflash caught non-zero exit BUT iter-4.2 inject still ran on PRE-EXISTING USB ESP
6. Operator saw "safe to remove USB" — believed flash succeeded
7. Boot attempt failed: "i got the fingerprint but it didn't format"

Root cause

zflash.ts docstring (lines 56-63) promises:

"Agent-driven mode: When the runner is an authorized agent acting on the operator's behalf per the flash-usb.ts authorship contract, the agent auto-types the `yes ` challenge."

But the IMPLEMENTATION uses `execFileSync({stdio: "inherit"})` with NO actual auto-type mechanism. Per `substrate-or-it-didnt-happen.md`: the docstring promise was WEATHER not SUBSTRATE.

Target

Add `--agent` flag to zflash.ts that uses `spawn` with piped stdin/stdout — reads stdout for "yes " line, auto-types response back to stdin, passes everything through.

~30-line change. No new deps. Backward-compatible (default behavior unchanged).

Preserves all safety rails

• Touch ID PAM gate — fires on operator's Mac for `sudo dd`; cannot be agent-bypassed
• Nonce randomness — random per-run; agent reads from stdout, can't pre-bake
• Runtime acceptance — agent typing the EXACT challenge IS the acceptance signal
• Glass-halo transparency — operator sees `[agent-mode: auto-typing 'yes XXXX']` line so the auto-type action is visible

Workaround (used in session)

External `expect` wrapper worked end-to-end (Flash complete; 1.51 GiB in 80s; iter-4.2 inject clean). But external dep is fragile + agent-driven mode IS PROMISED in docstring — should be native.

Composes with

• B-0789 (iter-4.2 ssh-pubkey-injection substrate — same zflash codebase)
• `.claude/rules/substrate-or-it-didnt-happen.md` (docstring promises must have backing implementation)
• `.claude/rules/glass-halo-bidirectional.md` (operator-visibility of auto-type action)
• `.claude/rules/non-coercion-invariant.md` HC-8 (operator agency preserved via Touch ID)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

Adds a new P1 backlog row (B-0844) documenting a docstring-vs-implementation gap in zflash.ts around “agent-driven mode” and outlining an implementation plan for a native --agent flag, plus updates the generated backlog index to reference the new row.

Changes:

• Added docs/backlog/P1/B-0844-...md with problem statement, root cause, acceptance criteria, and an implementation sketch for zflash --agent.
• Updated docs/BACKLOG.md to include the new B-0844 entry under P1.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/backlog/P1/B-0844-zflash-agent-mode-native-implementation-close-doc-vs-implementation-gap-aaron-2026-05-26.md	New backlog row capturing the zflash agent-mode issue, workaround, and target implementation/acceptance criteria.
docs/BACKLOG.md	Adds the B-0844 link into the P1 index list.