Codex review: needs real behavior proof before merge. Reviewed June 14, 2026, 8:03 PM ET / 00:03 UTC.

Summary
Adds a Levenshtein/alias-based closest-command suggestion to Commander parse-error output and formatter tests for mistyped root commands.

PR surface: Source +95, Tests +68. Total +163 across 3 files.

Reproducibility: yes. for the PR defect: source inspection shows runCli() can throw from resolveUnownedCliPrimaryMessage() before Commander, and existing tests assert buildProgramMock is not called on that path. I did not run tests because this review was read-only.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/cli/program/error-output.test.ts, migration/backfill/repair: src/cli/program/error-output.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Wire the suggestion helper into resolveUnownedCliPrimaryMessage() while preserving plugin-policy diagnostics.
• [P1] Add run-main.exit.test.ts coverage for typo, explicit alias, and far-off unknown root behavior.
• [P1] Add redacted real CLI proof showing the after-fix command output from a source checkout or built CLI.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR supplies unit-test and lint terminal output only and explicitly says a live built/source CLI invocation was not tested; the contributor should add redacted terminal output, screenshot, recording, or logs showing the actual openclaw upate or alias flow, then update the PR body to trigger a fresh review or ask a maintainer for @clawsweeper re-review.

Risk before merge

• [P1] Merging as-is may leave the real openclaw upate / openclaw upgrade path unchanged because normal startup can reject unowned roots before Commander runs.
• [P1] The PR proof is only unit-test and lint output; it does not show redacted terminal output, screenshot, recording, or logs from an actual after-fix CLI invocation.
• [P1] A member comment says the branch needs to be updated against current main for the new required Dependency Guard check.

Maintainer options:

1. Decide the mitigation before merge
   Share one command-suggestion helper across Commander parse errors and resolveUnownedCliPrimaryMessage() after plugin-policy diagnostics, then add run-main.exit.test.ts coverage plus redacted real CLI output.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Needs author revision, rebase, and real CLI proof; ClawSweeper repair should not take over while contributor proof is missing and the author is waiting on maintainer direction.

Security
Cleared: The diff only changes CLI diagnostic formatting and tests; it adds no dependencies, workflows, install scripts, credential handling, or other supply-chain-sensitive surfaces.

Review findings

• [P1] Wire suggestions into the early root guard — src/cli/program/help.ts:108-117

@clawsweeper acknowledged on the missed runtime path — your read is correct, and I owe a transparent recap of where the patch lands today, where the real-environment gap is, and what direction would unblock without another back-and-forth.

The patch only wires the suggester into the Commander parse-error path

Today the suggester reaches the user only through formatCliParseErrorOptions (src/cli/program/error-output.ts:1) and the knownCommands plumbing in src/cli/program/help.ts:1. The other unknown-root surface — resolveUnownedCliPrimaryMessage at src/cli/run-main.ts:393 — still emits the bare:

Unknown command: openclaw <primary>. No built-in command or plugin CLI metadata owns "<primary>".

So openclaw upate from a normal launch where shouldStartProxyForCli(normalizedArgv) is true (most install shapes) hits run-main.ts:506 before Commander ever runs and never sees the suggester. The PR title + body promised "unknown subcommands" generally; in practice only the Commander error path is covered. Real gap, not a phrasing issue.

The vitest case at src/cli/program/error-output.test.ts:69 does drive suggestClosestCommand end-to-end against the parse-error formatter (Levenshtein + explicit alias map both fire), so the unit-level proof is real for the surface the patch actually touches. Local run:

$ node scripts/run-vitest.mjs src/cli/program/error-output.test.ts
✓ src/cli/program/error-output.test.ts (5 tests) 18ms
Test Files  1 passed (1)
     Tests  5 passed (5)

Two paths I'd take, but want your call before pushing

1. Extend this PR to also wire the suggester into resolveUnownedCliPrimaryMessage — preserve resolveMissingPluginCommandMessageFromPolicy as the primary diagnostic (plugin-policy still wins) and append a Did you mean this? block only when the policy resolver returns null. Adds a run-main.exit.test.ts covering typo / explicit alias / far-off-unknown for the runCli exit path. Same diff stays scoped to CLI text plumbing, no plugin-policy semantics moved.
2. Ship the Commander-side suggester as-is, split the run-main wiring into a follow-up — keeps this diff small and isolated to the parse-error formatter; trade-off is the marketing of the change vs. what it actually covers needs to be downgraded ("suggest closest command for Commander parse errors" rather than "for unknown subcommands"). Honest answer is path 1 is what the issue actually wants; path 2 is only attractive if you'd rather review two narrower changes.

Real-environment gap

run-main.exit.test.ts-style coverage for the runtime path requires either a built CLI (pnpm build + node dist/.../openclaw) or a real install:

• openclaw upate from a globally-installed package against the after-fix dist
• redacted shell capture showing the new Did you mean this? block + exit code

Neither is reachable from a contributor sandbox without crabbox/testbox. Happy to either:

• spawn-based exit test using node dist/cli/openclaw upate once the patch is in, run inside crabbox so the proof is the real built CLI not a vitest mock, or
• attach a built-from-source openclaw upate capture to the PR after pushing path 1.

Asks

• Pick path 1 or 2 (or tell me path 1 should be a separate PR over this).
• If path 1: I push the resolveUnownedCliPrimaryMessage wiring + run-main.exit.test.ts and crabbox the real built-CLI capture in the same revision.
• Per AGENTS.md maintainer-skip clause, the existing vitest source-reproducible coverage for the Commander surface is recorded above for the part the patch already handles.

No further code from my side until your call — pushing path-1 now without ack would just re-trip the review state.

Heads up: this PR needs to be updated against current main before the new required Dependency Guard check can pass.

Thanks @0xghost42 for putting together the first implementation for #83999. I am closing this PR as superseded by #91345 because both PRs track the same CLI closest-command suggestion, and #91345 is the surviving open canonical path: it wires the suggestion into both the Commander parse-error path and the early unowned-root path, while this branch's own recap notes it only reaches the Commander path.

Clownfish is keeping #91345 as the canonical thread so validation and maintainer follow-up stay in one place. Your work in #84036 helped establish the direction, and that source PR context and attribution are preserved in the cluster record. If this branch has a distinct reproduction path or #91345 does not cover the case after it lands, please reply and we can reopen or split it back out.