feat(B-0844): zflash --agent flag implementation — close docstring-vs-implementation gap#5376
Merged
AceHack merged 1 commit intoMay 27, 2026
Conversation
…se via spawn with piped stdin closes docstring-vs-implementation gap (empirical 2026-05-26 3rd USB re-flash session)
Implements the --agent flag per B-0844 row. Closes the gap where
zflash.ts docstring promises 'agent auto-types the yes <nonce>
challenge' but the execFileSync({stdio: 'inherit'}) implementation
broke under any non-interactive stdin (e.g., 'bun zflash.ts | tail').
Empirical anchor: 2026-05-26 3rd USB re-flash session. Operator
authorized agent-driven zflash with Touch ID. Agent ran via
'bun zflash.ts | tail -50' which broke stdin → readline returned
empty → bail'd silently → tail swallowed error → iter-4.2 inject
ran on PRE-EXISTING USB ESP → operator saw 'safe to remove USB' +
thought flash succeeded → boot attempt failed: 'i got the
fingerprint but it didn't format'.
Implementation:
- New '--agent' flag added to ALLOWED_FLAGS + help text
- When --agent is passed: spawn flash-usb with stdio
['pipe', 'pipe', 'inherit'] instead of execFileSync({inherit})
- Pipe stdout: scan for the 'yes <4hex>' challenge line from
flash-usb.ts; mirror everything back to operator's stdout
- Pipe stdin: when challenge detected, auto-type 'yes <nonce>\n'
then close stdin
- Inherit stderr: Touch ID PAM prompt + sudo error messages stay
directly visible to operator
- Glass-halo visibility: explicit '[agent-mode: auto-typing
yes XXXX — operator visibility per glass-halo-bidirectional rule]'
line printed BEFORE the auto-type so operator can see what's
happening
- Default behavior (no --agent flag) unchanged — execFileSync
with inherited stdio remains for interactive operator runs
Preserves ALL safety rails:
- Touch ID PAM gate fires on operator's Mac for sudo dd; cannot
be agent-bypassed (biometric physical-presence proof)
- Nonce randomness preserved (random per-run; agent reads from
stdout, can't pre-bake)
- Runtime acceptance preserved (typing the EXACT challenge IS the
acceptance signal; agent typing it from operator-observed-stdout
IS substrate-honest delegation)
- All flash-usb sanity rails (platform / ISO size / USB protocol /
internal-disk / boot-disk / size-range checks) still fire
Verified:
- bun full-ai-cluster/tools/zflash.ts --help shows --agent entry
with full doc text
- TypeScript compiles cleanly (no type errors)
- Backward-compatible (default invocation unchanged)
Closes B-0844 acceptance criteria. Per substrate-or-it-didnt-happen.md:
docstring promise now has backing substrate.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
AceHack
deleted the
feat-b0844-impl-zflash-agent-flag-spawn-piped-auto-type-challenge-otto-cli-2026-05-26
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Implements B-0844 `--agent` flag per PR #5374 row spec. Empirical anchor: 2026-05-26 3rd USB re-flash session surfaced docstring-vs-implementation gap (operator: "i got the fingerprint but it didn't format").
Implementation
Preserves all safety rails
Verified
Test path post-merge
Re-run today's 3rd USB-test session with:
```bash
bun full-ai-cluster/tools/zflash.ts --agent 2>&1 | tail -100
```
Should show "Flash complete." + iter-4.2 inject + ejection with the auto-typed challenge visible in glass-halo log line.
Composes with
🤖 Generated with Claude Code