[roodboi]

Root cause

parseCliArgv parsed argv once against the union of every command's options, keyed by long name (buildUnionParseOptions). Two options shared a short flag: --path -p (project commands) and ssh --port -p. Bun's parseArgs resolved -p to whichever came last, which was ssh --port. So hack up -p <dir> (and init, down, ps, logs, env ..., config ..., setup ...) parsed as --port, and run.ts refused it with Option(s) not valid for "up": --port. The same union let one long name's type in one command change how every other command parsed it (#339 hit this with --rollback), which is why a guard test banned cross-command type conflicts.

Fix

src/cli/command.ts now parses in two passes:

1. scanInvocation resolves the command path, and the child-command boundary for passthrough positionals, from the leading positionals. It reads each option with the options of the command resolved so far, plus the global and built-in options, and skips that option's value token, including the omitted-value form of options with a default. An option placed before the command name falls back to the other declarations of that spelling. If those declarations disagree about taking a value, the option is read as a flag, so it never consumes the command name.
2. parseCliArgv then parses with that command's own options plus the global and built-in options, by long and short spelling. Options that only other commands declare are still parsed by long name, never by short flag. A misplaced option therefore keeps its existing Option(s) not valid for "<command>" refusal.

findPassthroughStart and hackOwnedArgv use the same scan, so #359's child-argv passthrough uses the resolved command's option types. That covers -- handling, flags after the child command, and the JSON envelope selected only by Hack's own --json. Default-value normalization is scoped the same way. run.ts is unchanged.

The only parse difference found by comparing old and new output on edge cases (--help --all, help --all, -- up, --json run web tool --json, --path /x up, logs --tail, up --tail, ssh --path /x, x ext cmd -p 1, --no-interactive up -p /x) is the intended one: up -p /x now sets path instead of port.

Tests

• New tests/cli-per-command-options.test.ts:
  • -p sets --path for every command that declares --path -p. The test walks the spec and asserts that it includes init/up/down/ps/logs/env list/config validate/setup migrate.
  • ssh -p sets --port.
  • -p before the command name follows that command.
  • A misplaced foreign long option is still refused as "not valid here", while an unknown short flag is unknown.
  • config adopt --rollback --json stays boolean, and setup migrate --rollback-manifest <file> takes a value.
  • A synthetic CLI where --rollback/-r is a flag in one command and takes a value in another parses correctly per command, before the command name, and at the passthrough boundary.
  • A source-CLI spawn under privateCliEnv checks that hack ps -p <dir> --json no longer reports --port.
• tests/cli-command.test.ts: the cross-tree "one value type per long option" guard is replaced by a per-scope guard. Within a command's scope (built-ins, globals and the command's own options), each long and short spelling must name exactly one option.
• The fix(cli): pass child flags through and print closed native refusals #359 passthrough tests in tests/cli-passthrough-argv.test.ts are unchanged and pass.

Each new test was checked by mutation:

• With the old command.ts, 11 of the new tests fail, including the spawn test. It printed Option(s) not valid for "ps": --port.
• Making disagreeing declarations keep the last type fails the before-command-name test.
• Removing other commands' long names from the parse table fails the "not valid here" test.
• Giving ssh --port the short flag -h fails the per-scope guard with hack ssh: -h names --help and --port.

Evidence

Bun 1.4.2 (mise x bun@1.4.2), base ace57ee. next has since moved to f2278c7; it only adds an unrelated run.ts hunk and merges cleanly.

• bun run --cwd packages/cli typecheck: 0 errors. bun run typecheck: passes.
• bun run --cwd packages/cli check and bun run check: 0 errors. The changed files lint clean, with no new warnings.
• Focused suites pass: 131/131 for the new test file, cli-passthrough-argv, cli-command, cli-spawn-env-isolation, cli-reference-docs, integration-ownership, mcp and mcp-inspect-tools. One run had a transient failure in an mcp.test.ts spawn test under load; it passed alone and in the rerun.
• bun run docs:cli-reference: no change to docs/reference/cli.md, because the help surface is unchanged.
• After bun run build, dist/hack ps -p <dir> --json and dist/hack up -p <dir> --json (private HOME) reach project discovery ("No .hack/ found") instead of the --port refusal.
• No native refusal codes or messages changed, so the native plan-CLI scripts were not rerun.
• gitleaks 8.30.1 over a git log -p origin/next..HEAD export: no leaks.

Remaining gaps

• Full bun run test ran on a heavily loaded host for 4253s and ended with 6824 pass and 640 fail across 105 files. Rerun serially with --timeout 60000, 89 of those files pass.
  • The 16 that still fail are native-compose/native-authored files. Rerun with origin/next's command.ts swapped in, they fail the same way or worse; for example, native-compose-adoption-generation fails 0/111 on both.
  • Two files with a single failure each (dependency-startup-progress, native-compose-adoption-probe) pass alone, and neither imports the CLI parser.
  • None of these failures is caused by this change. A green full run on a quiet runner or CI is still outstanding.
• Edge case, documented in scanInvocation: an option placed before the command name whose spelling is a flag in one command and takes a value in another is read as a flag. No such spelling exists in the current CLI.

Refs HACK-1293

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[linear-code]

HACK-1293

[blacksmith-sh]

Found 2 test failures on Blacksmith runners:

Failures

Test	View Logs
native-config-build (232.5s) — Native --profile must succeed/ native-config-build (232.5s) — Native --profile must succeed	View Logs
native-config-down-hooks (17.6s) — Each finite down mode starts a ready owned generatio n/ native-config-down-hooks (17.6s) — Each finite down mode starts a ready owned generatio n	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}