fix(cli): drop Bun SFE virtual argv[1] from detached re-invoke (#2248)

[bigboy1122]

Summary

• Problem: buildDetachedRunCmd assumed a compiled binary has no entry-script argv[1] and sliced user args from argv[1] in binary mode. Bun single-file executables do have an argv[1] — the virtual entry path (/$bunfs/root/<name>, or B:/~BUN/root/<name>.exe on Windows) — and report argv[0] as bun, not execPath. That virtual path leaked in as the detached child's first token.
• Why it matters: cli.ts parses process.argv.slice(2) unconditionally, so the child read the virtual path as its command and died with Unknown command: B:/~BUN/root/archon-windows-x64.exe — no run record, no worktree, no branch — while the parent still exited 0 with { ok: true, conversationId, logPath }. --detach is therefore broken on every compiled binary, which is the primary distribution channel (brew / curl install). Reported on Windows x64 and independently reproduced on Ubuntu 24.04 x64, so this is not platform-specific.
• What changed: user args are sliced from argv[2] in both modes; only the command prefix still branches on isBinary. The stale comment asserting "there is no entry-script argv[1]" is corrected. The existing binary-mode test fixture — which modelled a compiled argv with no argv[1] at all, and so certified the broken behaviour — is corrected to the real Bun SFE shape, plus a Windows-shaped regression test.
• What did not change (scope boundary): baseCmd still branches on isBinary (correct as-is). No change to spawn options, log-file handling, --cwd last-wins appending, or the --detach/--json filter. Windows reliability: verify the Modern Standby + --detach fixes on real hardware (code merged in #2063) #2080 (detached child not surviving launcher teardown) is a distinct Windows failure already addressed in v0.6.0 and is untouched here.

UX Journey

Before

  User                        archon (parent, compiled)          detached child
  ────                        ─────────────────────────          ──────────────
  archon workflow run X
    --detach --json ────────▶ builds child argv
                              [execPath, "B:/~BUN/root/          spawn ─────────▶ cli.ts: argv.slice(2)
                               archon.exe", "workflow", ...]                      → command = "B:/~BUN/
                                                                                     root/archon.exe"
                              prints {ok:true, ...}                               ✗ Unknown command
  sees success ◀────────────  exit 0                                              ✗ exits immediately

  archon workflow get <id> ─▶ "Workflow run not found"
  ✗ no run, no worktree, no branch — parent reported success

After

  User                        archon (parent, compiled)          detached child
  ────                        ─────────────────────────          ──────────────
  archon workflow run X
    --detach --json ────────▶ builds child argv
                              [execPath, *"workflow"*, ...]      spawn ─────────▶ cli.ts: argv.slice(2)
                              *virtual argv[1] dropped*                           → command = *"workflow"*
                              prints {ok:true, ...}                               ✓ run created
  sees success ◀────────────  exit 0                                              ✓ worktree + branch

  archon workflow get <id> ─▶ run record found, status streams
  ✓ parent's success report now matches reality

Architecture Diagram

Before

  packages/cli/src/commands/workflow.ts
  ┌──────────────────────────────────┐
  │ buildDetachedRunCmd()            │  isBinary ? argv.slice(1)   ← WRONG
  │   (pure argv builder)            │            : argv.slice(2)
  └───────────┬──────────────────────┘
              │ cmd[]
  ┌───────────▼──────────────────────┐
  │ spawnDetachedWorkflowRun()       │  spawn(cmd[0], cmd.slice(1), {detached})
  └───────────┬──────────────────────┘
              │ child process
  ┌───────────▼──────────────────────┐
  │ packages/cli/src/cli.ts          │  process.argv.slice(2)  ← contract mismatch
  │   main() arg parser              │  → "Unknown command"
  └──────────────────────────────────┘

After

  packages/cli/src/commands/workflow.ts
  ┌──────────────────────────────────┐
  │ [~] buildDetachedRunCmd()        │  argv.slice(2) in BOTH modes
  │     (pure argv builder)          │  baseCmd still branches on isBinary
  └───────────┬══════════════════════┘
              ║ cmd[]  (== corrected edge)
  ┌───────────▼──────────────────────┐
  │ spawnDetachedWorkflowRun()       │  unchanged
  └───────────┬──────────────────────┘
              │ child process
  ┌───────────▼──────────────────────┐
  │ packages/cli/src/cli.ts          │  process.argv.slice(2)
  │   main() arg parser              │  ✓ contract now honoured
  └──────────────────────────────────┘

Connection inventory:

From	To	Status	Notes
buildDetachedRunCmd	spawnDetachedWorkflowRun	modified	Emitted argv no longer carries the Bun SFE virtual entry path
spawnDetachedWorkflowRun	detached cli.ts main()	modified	Child's argv.slice(2) now yields the real command; previously the virtual path
workflow.test.ts	buildDetachedRunCmd	modified	Binary-mode fixture corrected to real SFE argv; Windows regression test added
cli.ts main()	—	unchanged	Parser untouched; it was already correct

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: cli
• Module: cli:workflow

Change Metadata

• Change type: bug
• Primary scope: cli

Linked Issue

• Closes bug(cli): Windows v0.6.0 --detach reinvokes Bun SFE virtual path as command #2248
• Related Windows reliability: verify the Modern Standby + --detach fixes on real hardware (code merged in #2063) #2080 (distinct Windows detach failure — child not surviving launcher teardown; already fixed in v0.6.0, untouched here)

Validation Evidence (required)

bun run validate     # → exit 0 (all nine gates: check:bundled, check:bundled-skill,
                     #   check:bundled-schema, check:pi-vendor-map,
                     #   check:capability-matrix, type-check, lint, format:check, test)

• Evidence provided:

  1. Empirical confirmation of Bun SFE argv shape. Built a throwaway artifact with bun build --compile (Bun 1.3.13, macOS arm64) and printed its argv:

  $ ./argvprobe workflow run foo
  { "execPath": "/…/argvprobe",
    "argv": [ "bun", "/$bunfs/root/argvprobe", "workflow", "run", "foo" ] }
  

  argv[0] is bun (not execPath) and argv[1] is the virtual entry path — directly contradicting the comment the old code relied on.

  2. Fix proven against that real argv:

  CURRENT (broken): [<archon>, "/$bunfs/root/fixprobe", "workflow", "run", "assist", "hello"]
  FIXED  slice(2) : [<archon>, "workflow", "run", "assist", "hello"]
  

  3. New tests fail against the previous implementation (reverted the one-line change and re-ran):

  (fail) binary mode: … drops the Bun SFE virtual argv[1]
         Expected: false  Received: true      ← $bunfs path present in cmd
  (fail) binary mode: drops the Windows Bun SFE virtual argv[1] (#2248 repro)
         Expected to not contain: "B:/~BUN/root/archon-windows-x64.exe"
         Received: [ "C:\\Users\\dev\\archon.exe", "B:/~BUN/root/archon-windows-x64.exe", …
  

  The received array reproduces the reported symptom token-for-token. With the fix applied: 3 pass, 0 fail; full @archon/cli suite 0 fail across all 6 batches.

• If any command is intentionally skipped: none skipped.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

Net effect is removing an unintended token from a spawned child's argv. The child is the same trusted execPath the parent is already running.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Database migration needed? No

Dev-mode (bun + entry script) behaviour is byte-for-byte identical: that branch already sliced from argv[2]. Only the compiled-binary branch changes, and only from broken to working.

Human Verification (required)

• Verified scenarios: Bun SFE argv shape confirmed against a real bun build --compile artifact rather than assumed from the report; fix output diffed against that same real argv; both new tests confirmed red against the old implementation and green against the new one; full bun run validate exit 0.
• Edge cases checked: dev-mode path unchanged (test still green with its original fixture); Windows-shaped B:/~BUN/… argv covered by a dedicated test; grepped the whole repo for other process.argv consumers — the only other one is cli.ts:239, which already uses slice(2) and is the contract this now matches.
• What was not verified: I did not run a released Windows x64 binary end-to-end (no Windows hardware). The Windows case is covered by unit test using the exact argv token from the report, and by the reporter's Linux reproduction of the identical root cause. A maintainer with a Windows box may want to confirm the end-to-end --detach run before release.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: only archon workflow run --detach on compiled binaries. Foreground runs never call this builder.
• Potential unintended effects: if any caller relied on the leaked virtual path reaching the child, it would break — but nothing can have, since the child rejected it as an unknown command and exited.
• Guardrails/monitoring for early detection: the detached child's stdout/stderr already land in ARCHON_HOME/logs/detached-run-<conversationId>.log; a regression reappears there immediately as Unknown command: …. The two new unit tests fail loudly on any reintroduction.

Rollback Plan (required)

• Fast rollback command/path: git revert <merge-sha> — the change is one expression plus tests in a single file pair, no migrations or state.
• Feature flags or config toggles: none (not warranted for a one-line argv correction).
• Observable failure symptoms: archon workflow run --detach returns { ok: true } but archon workflow get <conversationId> reports Workflow run not found, and the detached log contains Unknown command: <virtual path>.

Risks and Mitigations

• Risk: a future Bun release changes SFE argv shape again (e.g. drops the virtual argv[1]), making slice(2) wrong in the other direction.
  • Mitigation: slice(2) is now anchored to the same contract cli.ts:239 uses, so the two move together — a Bun change would break the CLI's own parser first and far more loudly than the detach path. The tests document the observed shape and the Bun version it was verified against.
• Risk: Windows end-to-end behaviour unverified on real hardware (see Human Verification).
  • Mitigation: root cause is argv construction, which is platform-independent and unit-tested with the exact Windows token from the report; the Linux reproduction confirms the mechanism is not OS-specific.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Fixed detached workflow commands for compiled Bun “single-file executable” mode by correctly stripping the virtual argv entry token before building the child command.
  • Ensured --detach/--json are consistently omitted, while --cwd and any additional flags are preserved.
  • Added a Windows regression coverage to prevent the virtual argv token from leaking into detached workflow arguments.

• Tests

  • Updated and extended unit tests for detached workflow argv construction, including the Windows scenario.

[coderabbitai]

📝 Walkthrough

Walkthrough

buildDetachedRunCmd now consistently excludes Bun SFE virtual entry paths from detached workflow arguments. Tests cover compiled-binary and Windows argv shapes while preserving supported flags and filtering --detach/--json.

Changes

Detached workflow argv

Layer / File(s)	Summary
Normalize detached command arguments packages/cli/src/commands/workflow.ts	Uses argv.slice(2) for user arguments in both modes while filtering --detach and --json.
Validate compiled argv shapes packages/cli/src/commands/workflow.test.ts	Tests removal of Bun virtual paths, preservation of --cwd and extra flags, and Windows child-command positions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• coleam00/Archon#2063: Both modify detached workflow command and argument construction.
• coleam00/Archon#2204: Both update detached workflow execution plumbing.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address #2248 by rebuilding detached argv from argv[2] in binary mode and adding regression tests for the Bun SFE/Windows token.
Out of Scope Changes check	✅ Passed	The diff stays focused on argv reconstruction and tests, with no unrelated functional or public-API changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the detached Bun SFE argv fix and matches the main change.
Description check	✅ Passed	The description covers the required template sections with detailed scope, validation, risks, and rollback information.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Wirasm]

---

pr: 2273
title: "fix(cli): drop Bun SFE virtual argv[1] from detached re-invoke (#2248)"
author: "bigboy1122"
reviewed: 2026-07-27
recommendation: approve

PR Review: #2273 — fix(cli): drop Bun SFE virtual argv[1] from detached re-invoke

Author: @bigboy1122
Branch: fix/2248-detach-bun-sfe-argv → dev (one commit on top of ace0a41a, current dev)
Files Changed: 2 (+48/-7)

---

Summary

Correct root cause, correct fix, minimal blast radius. I reproduced the bug and verified the fix end-to-end on real compiled Archon binaries (built with scripts/build-binaries.sh, Bun 1.3.11 — the version .github/workflows/release.yml pins), not just against a synthetic bun build --compile probe. Full bun run validate passes in a clean checkout of the branch. No critical or important issues in the diff; one important latent issue in the surrounding code that this narrow fix deliberately leaves in place, plus three suggestions.

Verdict: SHIP.

---

End-to-end verification (the part that was missing)

Two darwin-arm64 binaries built from this worktree via scripts/build-binaries.sh (TARGET=bun-darwin-arm64), one at PR HEAD and one with packages/cli/src/commands/workflow.ts reverted to HEAD~1. Both run against an isolated ARCHON_HOME and a single-bash-node probe workflow (no AI cost, deterministic).

Pre-fix binary — reproduces #2248 exactly

$ archon-prefix workflow run detach-probe --no-worktree --detach --json "hello-prefix"
{ "ok": true, "action": "run", "detached": true, "workflow": "detach-probe",
  "conversationId": "cli-1785138607744-bikb1j", "logPath": ".../detached-run-cli-...log" }
PARENT_EXIT=0

$ cat .../logs/detached-run-cli-1785138607744-bikb1j.log
Unknown command: /$bunfs/root/archon-prefix
<full usage dump>

$ archon-prefix workflow runs --json
{ "runs": [], "total": 0, "counts": { "all": 0, ... } }

Parent reports success and exits 0. Zero runs. No worktree, no branch, no run record.

Fixed binary — real run

$ archon-fixed workflow run detach-probe --no-worktree --detach --json "hello-fixed"
{ "ok": true, ..., "conversationId": "cli-1785138569260-s5biue" }

# detached log:
[probe] Started
[probe] Completed (6ms)
DETACH_PROBE_OK hello-fixed
Workflow completed successfully.

$ archon-fixed workflow runs --json
"id": "486ad22e716c3175a7f7542f9c06158c", "workflow_name": "detach-probe",
"status": "completed", "node_counts": { "completed": 1, "failed": 0, "total": 1 }

Dev mode — no regression

$ ARCHON_HOME=... bun run cli workflow run detach-probe --no-worktree --detach --json "hello-dev"
# → run created, status "completed", DETACH_PROBE_OK hello-dev

Dev mode was already slice(2); confirmed byte-for-byte behaviour is unchanged in practice.

Why the Windows case is correct without Windows hardware

Stronger than the PR body claims. The parent and the child are the same executable running under the same Bun runtime. Whatever offset cli.ts:239 (process.argv.slice(2)) uses to locate its command in the child is, by definition, the offset at which the parent's own user args begin. So slice(2) in the builder is correct on every platform on which the CLI works at all — if it were wrong, archon workflow list would be broken first and far more loudly. The B:/~BUN/… fixture is a useful regression pin, but the correctness argument does not depend on it.

---

Issues Found

Critical

None.

Important

• I1 — packages/cli/src/commands/workflow.ts:294-315 (latent, pre-existing, NOT introduced here): the detach ack is a false success for any child that starts and then dies.
  The parent prints { ok: true, ... } and exits 0 based solely on OS-level spawn success (child.pid !== undefined). Everything after that — unknown command, DB unreachable, workflow not resolvable in the child's cwd, provider binary missing — is invisible to the caller. This is precisely why bug(cli): Windows v0.6.0 --detach reinvokes Bun SFE virtual path as command #2248 survived a full release cycle: the failure mode is a silent one, and the only trail is a log file the user has no reason to open.
  • Why it matters: this is a "Fail Fast + Explicit Errors" violation at a process boundary. The narrow argv fix removes one cause; the detector gap remains and will hide the next one identically.
  • Recommendation: follow-up issue, not a blocker for this PR. A bounded liveness guard would close it cheaply — race child.on('exit') against a ~300–500 ms timer before printing the ack, and fail the ack if the child has already exited non-zero. That still "returns immediately" for every healthy run and would have turned bug(cli): Windows v0.6.0 --detach reinvokes Bun SFE virtual path as command #2248 into a first-use error instead of a release-long silent break.

Suggestions

• S1 — packages/cli/src/commands/workflow.test.ts:3242-3243: the toHaveLength(1) assertion is now vacuous, and its comment is stale.

  // The binary path must appear exactly once — never duplicated as argv[1].
  expect(cmd.filter(arg => arg === '/usr/local/bin/archon')).toHaveLength(1);

  Under the corrected fixture, argv[1] is /$bunfs/root/archon, not /usr/local/bin/archon — so the binary path can never appear twice regardless of implementation. Mutation-verified: forcing baseCmd = [execPath, argv[1]] unconditionally leaves this assertion green; only the new $bunfs check and expect(cmd[1]).toBe('workflow') catch it.

  • Fix: delete it, or keep it and rewrite the comment to what it now means (cmd[0] is the sole occurrence of the binary path). The old comment describes a scenario the fixture no longer models.

• S2 — packages/cli/src/commands/workflow.test.ts:3255: the "Windows" test exercises no Windows-specific path.
  buildDetachedRunCmd is platform-agnostic string manipulation — no process.platform branch, no path.sep handling. The test is a second data fixture carrying the exact token from the report. That is genuinely valuable (mutation-verified: it fails against the original argv.slice(1) implementation) but it is a regression pin / documentation artifact, not platform coverage. Suggest the test comment say so, so a future reader doesn't infer Windows behaviour is under test.

• S3 — packages/cli/src/commands/workflow.ts:278-279: detached log file appends without a run delimiter.
  openSync(join(logDir, \detached-run-${conversationId}.log`), 'a'). When the caller supplies an explicit --conversation-id(a documented feature forpersist_session continuity), every subsequent detached run appends to the same file with no separator and no rotation. Debuggability degrades exactly where it matters most given I1. A one-line header (=== run ===`) on open would fix it.

• S4 — optional, probably YAGNI: the cli.ts:239 ↔ workflow.ts:254 coupling is load-bearing but only documented in a comment.
  Two call sites, so Rule of Three says leave it. Noting it only because the comment is now the sole thing preventing a future drift from re-opening this exact bug class. A shared getUserArgs(argv) helper would make it a compile-time concern; I would not require it.

---

Interaction with #2204

Checked with git merge-tree --write-tree pr-2273 pr-2204 → clean, no conflicts (adjacent hunks in workflow.test.ts, but they merge). The merged tree keeps this fix intact and #2204's new call site inherits it:

2270:    const logPath = spawnDetachedWorkflowRun(process.cwd(), runId, []);

So #2204's --detach on workflow approve/reject/resume would be equally broken on every compiled binary without #2273. Recommend #2273 lands first, or at minimum that #2204 does not ship in a release without it. Note that I1 applies with more force to #2204's control verbs: an approve/reject that silently no-ops is worse than a run that silently doesn't start.

---

Validation Results

Run on a clean checkout of the PR branch after bun install.

Check	Status	Details
bun run validate	PASS	exit 0 (all nine gates)
check:bundled	PASS	up to date (36 commands, 21 workflows)
check:bundled-skill / check:bundled-schema / check:pi-vendor-map / check:capability-matrix	PASS	via validate exit 0
type-check	PASS	all 8 packages exited 0
lint	PASS	zero warnings (--max-warnings 0)
format:check	PASS	All matched files use Prettier code style!
@archon/cli tests	PASS	6 batches: 425 pass / 0 fail
Binary build	PASS	scripts/build-binaries.sh → 74,823,712 bytes, tree restored cleanly by the EXIT trap

---

Pattern Compliance

• Follows existing code structure (pure builder retained, isBinary still only gates the command prefix)
• Type safety maintained (no new any, no signature change)
• Naming conventions followed
• Tests added for the fix, and both new assertions are mutation-verified to fail on the old implementation
• Comment corrected rather than left stale — the previous comment was the actual defect carrier
• No docs change needed (reference/cli.md describes --detach behaviourally; nothing it says was wrong)
• No CHANGELOG.md edit needed (/release generates entries)

---

Strengths

• Root cause is identified precisely and the corrected comment now documents the real Bun SFE argv shape — the old comment was the thing that made the bug plausible to reviewers.
• Scope discipline is exemplary: baseCmd correctly left branching on isBinary, spawn options / log handling / --cwd last-wins untouched, Windows reliability: verify the Modern Standby + --detach fixes on real hardware (code merged in #2063) #2080 explicitly excluded.
• The corrected fixture is the important half of the change — the old fixture actively certified the broken behaviour.
• Both new assertions were confirmed (by me, via mutation) to fail against the pre-fix implementation. Not all "regression tests" survive that check; these do.

---

Historical note

git log -L on the function shows the argv.slice(1) branch was introduced by #1853, the commit that added --detach itself. So --detach has never worked on a compiled binary — i.e. it has never worked on brew/curl installs, the primary distribution channel. That is worth a "Fixed" line at the next release rather than being folded into a generic CLI bucket.

---

Recommendation

APPROVE / ship as-is. S1–S3 are optional polish and can land as a follow-up or be ignored. I1 deserves its own issue.

Reviewed by Claude — report: /Users/rasmus/.prp/archon-75601ef6/reviews/pr-2273-review.md