[steipete]

Summary

A Peekaboo CLI binary invoked under any name that doesn't end in peekaboo rejected every command and treated its own path as the command:

$ cp peekaboo /tmp/peekaboo-before && /tmp/peekaboo-before --version
Error: Unknown command '/tmp/peekaboo-before'

The same happened through a symlink such as pb -> peekaboo, where argv[0] is pb. The entry point passes CommandLine.arguments (full argv), but CommanderRuntimeRouter.trimmedArguments dropped argv[0] only when it ended in peekaboo. The same heuristic also appeared in the agent default-subcommand normalization and in result-envelope classification.

The fix makes the contract explicit: these entry points take full argv and always drop exactly the first element. All three heuristics are removed, and agent normalization now operates on the trimmed tail. A caller audit found only two tail-only callers, both tests, and they now pass an executable name first. Commander and the daemon's own executable lookup are unchanged.

This PR also adds the changelog credits for #1006 and #1007, which landed without entries. Found while benchmarking #1005 with a renamed binary.

Tests

• New CommanderRuntimeArgvTests, plus expansions of the existing resolution and classification tests, cover absolute paths, pb, peekaboo-4.9, peekaboo-before, and the peekaboo and /usr/local/bin/peekaboo forms. They also cover agent task normalization and result-envelope classification. Against the old code they fail with 141 assertion issues.
• Focused swift test via the workspace helper: 78 tests in 7 suites pass.
• pnpm run build:cli, pnpm run format, and pnpm run lint pass, with no diagnostics in touched files. node scripts/docs-lint.mjs passes.
• Manual: a copied peekaboo-renamed binary and a real pb symlink both run --version and see --help (no capture or input).
• Codex autoreview (P0–P2): scoped-clean.

[cursor]

PR Summary

Medium Risk
Argv handling is centralized at every CLI dispatch path; behavior change is intentional but affects all command resolution, agent shorthand, and JSON envelope classification.

Overview
Fixes CLI routing when the binary is renamed, copied, or invoked via a symlink (e.g. pb, /tmp/peekaboo-before) by treating entry APIs as full argv and always dropping exactly argv[0], instead of stripping the executable only when its path ended in peekaboo.

That contract is applied consistently in CommanderRuntimeRouter (argument trimming and agent default-run normalization), result-envelope action classification, and documented on resolveAndRun / executePeekabooCLI. Tests now cover multiple executable spellings; docs note rename/symlink usage. The changelog also records unrelated fixes #1006 and #1007.

^{Reviewed by Cursor Bugbot for commit d372a82. Bugbot is set up for automated code reviews on this repo. Configure here.}

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

Treat CLI inputs consistently as full argv so renamed and symlinked executables resolve commands correctly.

Example: Run /tmp/peekaboo-before --version after copying the CLI binary.

• Before: The executable path is treated as a command and rejected.
• After: The executable path is removed and the version is printed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The focused repair is correct on source inspection and has useful regression coverage; observable process evidence is limited to the author's manual-check report.
Proof confidence	🦐 gold shrimp (3/6)	Collaborator authorship exempts this PR from the external-contributor proof gate; the body reports real copied-binary and symlink version/help checks, while supplied regression tests exercise routing, agent normalization, and classification in process.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: A copied, renamed, or symlinked CLI binary rejects commands because its executable name is parsed as a command.
Reason: The repair restores normal executable invocation semantics with less production code, and the area owner explicitly chose the contract in this collaborator-authored PR.

Merge readiness

✅ Ready for maintainer review

This PR fixes a source-confirmed bug still present on main, and review found no actionable introduced defect; collaborator authorship also prevents automatic closure.

Priority: P2
Reviewed head: d372a823ff6c1fcd0f3dad6c1a274b89a6976a21

Before merge

None.

Findings

None.

Tests

• Missing end-to-end proof: Supplied manual checks report renamed and symlinked version/help success, but include no terminal output demonstrating agent shorthand or JSON action classification through a renamed process.

Agent review details

How this fits together

The CLI entry point passes process arguments to routing and result classification, which select a command before parsing, runtime construction, and execution.

flowchart TD
    A[Process arguments] --> B[CLI entry point]
    B --> C[Result classification]
    B --> D[Runtime router]
    D --> E[Commander argument parser]
    E --> F[Command executor]
    C --> G[Result envelope]
    F --> G

Loading

Technical review

Best possible solution:

Land the consistent full-argv repair once the existing checks finish successfully.

Do we have a high-confidence way to reproduce the issue?

Current-main source establishes the failure: /tmp/peekaboo-before remains the first routing token despite being argv zero; no target code was executed during this read-only review.

Is this the best way to solve the issue?

Dropping argv zero at Peekaboo's full-argv boundary fixes the cause, preserves Commander's argument-tail contract, and removes the same assumption from classification and agent normalization.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 81bce4043f53.

Provenance checked

• Executable trimming changes intended behavior with a stated reason (16697ee: Added help routing alongside the existing runtime router; no intentional restriction to executable names ending in peekaboo was recorded.)
• Agent default-subcommand normalization keeps the original intent (feat(cli)!: v4 phase 2 — subcommand restructures #339: Preserve natural-language agent shorthand during the v4 subcommand restructure; the later explicit-tail adaptation retained that goal.)
• Pre-dispatch result classification keeps the original intent (fix(cli): tag pre-dispatch action refusals #373: Classify actions before parsing so pre-dispatch refusals receive the correct result envelope; the later optimization preserved those semantics.)

Testing

Proof path: in-process harness.

Security

None.

Evidence

What I checked:

• Current-main failure: The production entry point supplies CommandLine.arguments, while main removes argv zero only when it ends in peekaboo; renamed executable paths consequently reach command resolution. (Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift:76, 81bce4043f53)
• Verified introduced repair: The pinned diff removes executable-name guessing from trimming, agent normalization, and result classification, and updates the two test locations that accepted argument tails. (Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift:77, d372a823ff6c)
• Dependency contract verified: The changed router imports Commander and calls Program.resolve(arguments:), establishing dependency relevance; the pinned implementation explicitly accepts an argument tail. Its complete root policy was read, and no dependency edit is needed. (Sources/Commander/Program.swift, d3212c6034e3)
• Feature history and original intent: Commit 16697ee introduced the suffix heuristic for help routing; the v4 restructure preserved agent shorthand, and fix: refresh submodules and harden native-only policy #420 subsequently adopted Commander's explicit tail API while intending to preserve full-argv behavior. History across the earlier entry-point paths consistently identifies Peter Steinberger as the central area contributor. (Apps/CLI/Sources/PeekabooCLI/CLI/CommanderRuntimeRouter.swift, 16697eeeec8c)
• Regression coverage: New tests exercise actual routing and the in-process entry point with renamed paths and short executable names; expanded tests cover agent normalization and every registered leaf's result classification. (Apps/CLI/Tests/CoreCLITests/CommanderRuntimeArgvTests.swift:8, d372a823ff6c)
• Maintainer direction and validation context: The collaborator-authored body explicitly chooses the full-argv contract and reports copied-binary and real-symlink version/help checks. Exact-head CI has no reported failure, with four checks still running. The additional changelog credits accurately describe the merged fixes at fix(capture): retain valid UTF8 output at the byte limit #1006 and fix(config): refuse mutation after an existing configuration read fails #1007. (d372a823ff6c)

Likely related people:

• Peter Steinberger: Raw commit e2c5c63 adds Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift:10 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: e2c5c63ca5c5; files: Apps/CLI/Sources/PeekabooCLI/CLI/PeekabooEntryPoint.swift)

Review metrics

Metric	Value	Why it matters
Patch size	Production +12/-23; tests +49/-10; documentation +5/-0	The repair reduces production code while adding focused coverage for the executable-name failure.

Labels

Label changes:

• add P2: Renamed and symlinked CLI invocations fail, while ordinary peekaboo invocations remain available.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P2: Renamed and symlinked CLI invocations fail, while ordinary peekaboo invocations remain available.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only; repair and merge need explicit maintainer commands such as @clawsweeper autofix or @clawsweeper automerge.

Reviewed October 10, 2026, 12:42 AM ET / 04:42 UTC.