feat: #108 add did-you-mean guard for subcommand typos (prevents silent LLM dispatch)

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

.claw.json

@@ -0,0 +1,5 @@
+{
+  "aliases": {
+    "quick": "haiku"
+  }
+}

ROADMAP.md

@@ -711,6 +711,49 @@ Acceptance:
 - token-risk preflight becomes operational guidance, not just warning text
 - first-run users stop getting stuck between diagnosis and manual cleanup
 
+### 4.44.5. Ship/provenance opacity — IMPLEMENTED 2026-04-20
+
+**Status:** Events implemented in `lane_events.rs`. Surface now emits structured ship provenance.
+
+When dogfood work lands on `main`, the delivery path (scoped branch → PR → merge → push vs direct push) and the exact commit set shipped are not surfaced as first-class events. This makes it too easy to lose the boundary between "dogfood fix landed", "what exact commits shipped", and "what review/merge path was actually used." The 56-commit push during 2026-04-20 dogfood (#122/#127/#129/#130/#131/#132) exhibited this gap: work started as scoped pinpoint branches, then collapsed into a direct `origin/main` push with no structured provenance trail.
+
+**Implemented behavior:**
+- `ship.prepared` event — intent to ship established
+- `ship.commits_selected` event — commit range locked
+- `ship.merged` event — merge completed with metadata
+- `ship.pushed_main` event — delivery to main confirmed
+- All carry `ShipProvenance { source_branch, base_commit, commit_count, commit_range, merge_method, actor, pr_number }`
+- `ShipMergeMethod` enum: direct_push, fast_forward, merge_commit, squash_merge, rebase_merge
+
+Required behavior:
+
+When dogfood work lands on `main`, the delivery path (scoped branch → PR → merge → push vs direct push) and the exact commit set shipped are not surfaced as first-class events. This makes it too easy to lose the boundary between "dogfood fix landed", "what exact commits shipped", and "what review/merge path was actually used." The 56-commit push during 2026-04-20 dogfood (#122/#127/#129/#130/#131/#132) exhibited this gap: work started as scoped pinpoint branches, then collapsed into a direct `origin/main` push with no structured provenance trail.
+
+Required behavior:
+- emit `ship.provenance` event with: source branch, merge method (PR #, direct push, fast-forward), commit range (first..last), and actor
+- distinguish `intentional.ship` (explicit deliverables like #122-#132) from `incidental.rider` (other commits in the push)
+- surface in lane events and `claw state` output
+- clawhip can report "6 pinpoints shipped, 50 riders, via direct push" without git archaeology
+
+Acceptance:
+- no post-hoc human reconstruction needed to answer "what just shipped and by what path"
+- delivery path is machine-readable and auditable
+
+Source: gaebal-gajae dogfood observation 2026-04-20 — the very run that exposed the gap.
+
+**Incomplete gap identified 2026-04-20:**
+Schema and event constructors implemented in `lane_events.rs::ShipProvenance` and `LaneEvent::ship_*()` methods. **Missing: wiring.** Git push operations in rusty-claude-cli do not yet emit these events. When `git push origin main` executes, no `ship.prepared/commits_selected/merged/pushed_main` events are emitted to observability layer. Events remain dead code (tests-only).
+
+**Next pinpoint (§4.44.5.1):** Ship event wiring
+Wire `LaneEvent::ship_*()` emission into actual git push call sites:
+1. Locate `git push origin <branch>` command execution(s) in `main.rs`, `tools/lib.rs`, or `worker_boot.rs`
+2. Intercept before/after push: emit `ship.prepared` (before merge), `ship.commits_selected` (lock range), `ship.merged` (after merge), `ship.pushed_main` (after push to origin/main)
+3. Capture real metadata: `source_branch`, `commit_range`, `merge_method`, `actor`, `pr_number`
+4. Route events to lane event stream
+5. Verify `claw state` output surfaces ship provenance
+
+Acceptance: git push emits all 4 events with real metadata, `claw state` JSON includes `ship` provenance.
+
 ### 4.44. Typed-error envelope contract (Silent-state inventory roll-up)
 Claw-code currently flattens every error class — filesystem, auth, session, parse, runtime, MCP, usage — into the same lossy `{type:"error", error:"<prose>"}` envelope. Both human operators and downstream claws lose the ability to programmatically tell what operation failed, which path/resource failed, what kind of failure it was, and whether the failure is retryable, actionable, or terminal. This roll-up locks in the typed-error contract that closes the family of pinpoints currently scattered across **#102 + #129** (MCP readiness opacity), **#127 + #245** (delivery surface opacity), and **#121 + #130** (error-text-lies / errno-strips-context).
 
@@ -787,7 +830,31 @@ Acceptance:
 - channel status updates stay short and machine-grounded
 - claws stop inferring state from raw build spam
 
-### 6.5. Blocked-state subphase contract
+### 137. Model-alias shorthand regression in test suite — bare alias parsing broken on `feat/134-135-session-identity` branch
+
+**Filed:** 2026-04-21 from dogfood cycle — `cargo test --workspace` on `feat/134-135-session-identity` HEAD (`91ba54d`) shows 3 failing tests.
+
+**Problem:** `tests::parses_bare_prompt_and_json_output_flag`, `tests::multi_word_prompt_still_uses_shorthand_prompt_mode`, and `tests::env_permission_mode_overrides_project_config_default` all panic with:
+```
+args should parse: "invalid model syntax: 'claude-opus'. Expected provider/model (e.g., anthropic/claude-opus-4-6) or known alias (opus, sonnet, haiku)"
+```
+The #134/#135 session-identity work tightened model-syntax validation but the test fixtures still pass bare `claude-opus` style strings that the new validator rejects. 162 tests pass; only the three tests using legacy bare-alias model names fail.
+
+**Fix shape:**
+- Update the three failing test fixtures to use either a valid alias (`opus`, `sonnet`, `haiku`) or a fully-qualified model id (`anthropic/claude-opus-4-6`)
+- Alternatively, if `claude-opus` is an intended supported alias, add it to the alias registry
+- Verify `cargo test --workspace` returns 0 failures before merging the feat branch to `main`
+
+**Acceptance:**
+- `cargo test --workspace` passes with 0 failures on the `feat/134-135-session-identity` branch
+- No regression on the 162 tests currently passing
+
+### 133. Blocked-state subphase contract (was §6.5)
+**Filed:** 2026-04-20 from dogfood cycle — previous cycle identified §4.44.5 provenance gap, this cycle targets §6.5 implementation.
+
+**Problem:** Currently `lane.blocked` is a single opaque state. Recovery recipes cannot distinguish trust-gate blockers from MCP handshake failures, branch freshness issues, or test hangs. All blocked lanes look the same, forcing pane-scrape triage.
+
+**Concrete implementation:
 When a lane is `blocked`, also expose the exact subphase where progress stopped, rather than forcing claws to infer from logs.
 
 Subphases should include at least:
@@ -4966,3 +5033,141 @@ ear], /color [scheme], /effort [low|medium|high], /fast, /summary, /tag [label],
    **Blocker.** None. Reuses existing `stale_base` module; no new logic needed, just a missing call site.
 
    **Source.** Jobdori dogfood 2026-04-20 against `/tmp/jobdori-129-mcp-cred-order` + `/tmp/stale-branch` in response to 10-min cron cycle. Confirmed: `claw doctor` on branch 5 commits behind main says "Status: ok" but `prompt` dispatch would warn "worktree HEAD does not match expected base commit." Gap is a missing invocation of the already-correct `run_stale_base_preflight()` in the `doctor` action handler. Joins **Boot preflight / doctor contract (#80–#83, #114)** family — doctor is the single machine-readable preflight surface; missing checks degrade operator trust. Also relates to **Silent-state inventory** cluster (#102/#127/#129/#245) because stale-base is a runtime truth ("my branch is behind main") that the preflight surface (doctor) does not expose.
+
+## Pinpoint #135. `claw status --json` missing `active_session` boolean and `session.id` cross-reference — two surfaces that should be unified are inconsistent
+
+**Gap.** `claw status --json` exposes a snapshot of the runtime state but does not include (1) a stable `session.id` field (filed as #134 — the fix from the other side is to emit it in lane events; the consumer side needs it queryable via `status` too) and (2) an `active_session: bool` that tells an orchestrator whether the runtime currently has a live session in flight. An external orchestrator (Clawhip, remote agent) running `claw status --json` after sending a prompt has no machine-readable way to confirm whether the session is alive, idle, or stalled without parsing log output.
+
+**Trace path.**
+- `claw status --json` (dispatcher in `main.rs` `CliAction::Status`) renders a `StatusReport` struct that includes `git_state`, `config`, `model`, `provider` — but no `session_id` or `active_session` fields.
+- `claw status` (text mode) also omits both.
+- The `session.id` fix from #134 introduces a UUID at session init; it should be threaded through to `StatusReport` so the round-trip is complete: emit on startup event → queryable via `status --json` → correlatable in lane events.
+
+**Fix shape (~30 lines).**
+1. Add `session_id: Option<String>` and `active_session: bool` to `StatusReport` struct. Both `null`/`false` when no session is active. When a session is running, `session_id` is the same UUID emitted in the startup lane event (#134).
+2. Thread the session state into the `status` handler via a shared `Arc<Mutex<SessionState>>` or equivalent (same mechanism #134 uses for startup event emission).
+3. Text-mode `claw status` surfaces the value: `Session: active (id: abc123)` or `Session: idle`.
+4. Regression tests: (a) `claw status --json` before any prompt → `active_session: false, session_id: null`. (b) `claw status --json` during a prompt session → `active_session: true, session_id: <uuid>`. (c) UUID matches the `session.id` in the first lane event of the same run.
+
+**Acceptance.** An orchestrator can poll `claw status --json` and determine: is there a live session? What is its correlation ID? Does it match the ID from the last startup event? This closes the round-trip opened by #134.
+
+**Blocker.** Depends on #134 (session.id generation at init). Can be filed and implemented together.
+
+**Source.** Jobdori dogfood 2026-04-21 06:53 KST on main HEAD `2c42f8b` during recurring cron cycle. Direct sibling of #134 — #134 covers the event-emission side, #135 covers the query side. Joins **Session identity completeness** (§4.7) and **status surface completeness** cluster (#80/#83/#114/#122). Natural bundle: **#134 + #135** closes the full session-identity round-trip. Session tally: ROADMAP #135.
+
+## Pinpoint #134. No run/correlation ID at session boundary — every observer must infer session identity from timing or prompt content
+
+   **Gap.** When a `claw` session starts, no stable correlation ID is emitted in the first structured event (or any event). Every observer — lane event consumer, log aggregator, Clawhip router, test harness — has to infer session identity from timing proximity or prompt content. If two sessions start in close succession there is no unambiguous way to attribute subsequent events to the correct session. `claw status --json` returns session metadata but does not expose an opaque stable ID that could be used as a correlation key across the event stream.
+
+   **Fix shape.**
+   - Emit `session.id` (opaque, stable, scoped to this boot) in the first structured event at startup
+   - Include same ID in all subsequent lane events as `session_id` field
+   - Expose via `claw status --json` so callers can retrieve the active session's ID from outside
+   - Add regression: golden-fixture asserting `session.id` is present in startup event and value matches across a multi-event trace
+
+   **Acceptance.** Any observer can correlate all events from a session using `session_id` without parsing prompt content or relying on timestamp proximity. `claw status --json` exposes the current session's ID.
+
+   **Blocker.** None. Requires a UUID/nanoid generated at session init and threaded through the event emitter.
+
+   **Source.** Jobdori dogfood 2026-04-21 01:54 KST on main HEAD `50e3fa3` during recurring cron cycle. Joins **Session identity completeness at creation time** (ROADMAP §4.7) — §4.7 covers identity fields at creation time; #134 covers the stable correlation handle that ties those fields to downstream events. Joins **Event provenance / environment labeling** (§4.6) — provenance requires a stable anchor; without `session.id` the provenance chain is broken at the root. Natural bundle with **#241** (no startup run/correlation id, filed by gaebal-gajae 2026-04-20) — #241 approached from the startup cluster; #134 approaches from the event-stream observer side. Same root fix closes both. Session tally: ROADMAP #134.
+
+## Pinpoint #136. `--compact` flag output is not machine-readable — compact turn emits plain text instead of JSON when `--output-format json` is also passed
+
+**Gap.** `claw --compact <prompt>` runs a prompt turn with compacted output (tool-use suppressed, final assistant text only). But `run_with_output()` routes on `(output_format, compact)` with an explicit early-return match: `CliOutputFormat::Text if compact => run_prompt_compact(input)`. The `CliOutputFormat::Json` branch is never reached when `--compact` is set. Result: passing `--compact --output-format json` silently produces plain-text output — the compact flag wins and the format flag is silently ignored. No warning or error is emitted.
+
+**Trace path.**
+- `rust/crates/rusty-claude-cli/src/main.rs:3872-3879` — `run_with_output()` match:
+  ```
+  CliOutputFormat::Text if compact => self.run_prompt_compact(input),
+  CliOutputFormat::Text => self.run_turn(input),
+  CliOutputFormat::Json => self.run_prompt_json(input),
+  ```
+  The `Json` arm is unreachable when `compact = true` because the first arm matches first regardless of `output_format`.
+- `run_prompt_compact()` at line 3879 calls `println!("{final_text}")` — always plain text, no JSON envelope.
+- `run_prompt_json()` at line 3891 wraps output in a JSON object with `message`, `model`, `iterations`, `usage`, `tool_uses`, `tool_results`, etc.
+
+**Fix shape (~20 lines).**
+1. Add a `CliOutputFormat::Json if compact` arm (or merge compact flag into `run_prompt_json` as a parameter) that produces a JSON object with `message: <final_text>` and a `compact: true` marker. Tool-use fields remain present but empty arrays (consistent with compact semantics — tools ran but are not returned verbatim).
+2. Emit a warning or `error.kind: "flag_conflict"` if conflicting flags are passed in a way that silently wins (or document the precedence explicitly in `--help`).
+3. Regression tests: `claw --compact --output-format json <prompt>` must produce valid JSON with at minimum `{message: "...", compact: true}`.
+
+**Acceptance.** An orchestrator that requests compact output for token efficiency AND machine-readable JSON gets both. Silent flag override is never a correct behavior for a tool targeting machine consumers.
+
+**Blocker.** None. Additive change to existing match arms.
+
+**Source.** Jobdori dogfood 2026-04-21 12:25 KST on main HEAD `8b52e77` during recurring cron cycle. Joins **Output format completeness** cluster (#90/#91/#92/#127/#130) — all surfaces that produce inconsistent or plain-text fallbacks when JSON is requested. Also joins **CLI/REPL parity** (§7.1) — compact is available as both `--compact` flag and `/compact` REPL command; JSON output gap affects only the flag path. Session tally: ROADMAP #136.
+
+## Pinpoint #138. Dogfood cycle report-gate opacity — nudge surface collapses "bundle converged", "follow-up landed", and "pre-existing flake only" into single closure shape
+
+**Gap.** When a dogfood nudge triggers on a branch with landed work, the report surface emits status like "fixed 3 tests, pushed branch, 1 unrelated red remains" — but downstream nudges cannot distinguish:
+1. `bundle converged, merge-ready` (e.g., #134/#135 branch after fixes)
+2. `follow-up landed on main, branch still valid` (e.g., #137 + #136 fixes after #134/#135 was ready)
+3. `only pre-existing flake remains, no new regressions` (e.g., `resume_latest...` test failure on main that also fails on feature branch)
+4. `work still in flight, blocker not yet resolved`
+5. `merged and closed, re-nudge is a dup`
+
+Result: repeat nudges look identical whether the prior work converged or is still broken. Claws re-open what was already resolved, burning cycles on rediscovery.
+
+**Concrete example from this session:**
+- 14:30 nudge triggered on bundle already clear (14:25)
+- Reported finding was "nudge closure-state opacity" but manifested as "should we re-nudge or not?"
+- No explicit surface like "status: done", "last-updated: 2026-04-21T14:25", "next-action: none" that stops re-nudges on unchanged state
+
+**Fix shape (~30-50 lines, surfaces not code).**
+1. Dogfood report should carry an explicit **closure state** field: `converged`, `follow-up-landed`, `pre-existing-flake-only`, `in-flight`, `merged`, `dup`.
+2. Each state has a **last-updated timestamp** (when report was filed) and **next-action** (null if converged, or describe blocker).
+3. Nudge logic checks prior report state: if `converged` + timestamp < 10 min old, skip nudge and post "still converged as of HH:MM, no action".
+4. If state changed (e.g., new commits landed), emit **state transition** explicitly: "bundle done (14:25) → follow-up landed (14:42)".
+5. Store closure state in a **shared metadata surface** (Discord message edit, ROADMAP inline, or compact JSON file) so next cycle can read it.
+
+**Acceptance.**
+- Repeat nudges on converged work are replaced with "no change since last report" (skip).
+- State transitions are explicit: "was X, now Y" instead of ambiguous "X and also Y".
+- Claws can scan closure states and prioritize fresh work over already-handled bundles.
+
+**Blocker.** Design question: **where should closure state live?** Options:
+- Edit the prior Discord message with a closure tag (e.g., 🟢 CONVERGED).
+- Add a `.dogfood-closure.json` file to the worktree branch that tracks state.
+- File a new ROADMAP entry per bundle completion (meta-tracking).
+- Embedded in claw-code CLI output (machine-readable, but creates coupling).
+
+Current state is **design question unresolved**. Implementation is straightforward once closure-state model is settled.
+
+**Source.** Jobdori dogfood 2026-04-21 14:25-14:47 KST — multi-cycle convergence pattern exposed by repeat nudges on #134/#135 bundle. Joins **Dogfood loop observability** (related to earlier §4.7 session-identity, but one level up — session-identity is plumbing, closure-state is the **reporting contract**). Also joins **False-green report gating** (from 14:05 finding) — this is the downstream effect: unclear reports beget re-nudges on stale work.
+
+Session tally: ROADMAP #138.
+
+### Evidence for #138 — feat/134-135-session-identity branch is pushed but no PR was opened (2026-04-21 15:05)
+
+**Concrete gap observed:**
+- Branch `feat/134-135-session-identity` pushed to `origin` at `7235260` (commits `f55612e`, `2b7095e`, `230d97a`, `7235260`)
+- Dogfood loop declared bundle "merge-ready" at 14:25
+- ~40 min elapsed; no PR opened, no merge, branch still unmerged
+- Meanwhile #136 and #137 landed directly on main (`a8beca1`, `21adae9`) without going through the branch
+
+**Direct verification of #135 on main:**
+- `env -i $BIN status --output-format json` on main HEAD `768c1ab` shows `active_session: null, session_id: null`
+- Fields exist in JSON schema (added by schema-only?) but values are None because the producer plumbing (`#134`) is not on main
+- #135 consumer relies on #134 producer; both live on feat/134-135 only
+
+**Impact:**
+- `claw status --output-format json` on main returns JSON without the #135 session identity signals (because they're only on feat/134-135)
+- Orchestrators that shipped using the 13:00 "round-trip proof" report believing #134+#135 was merge-ready will get null fields
+- Evidence for #138: "closure-state" = "pushed branch" ≠ "merged" ≠ "in-PR" — nudge surface collapses all three
+
+**Proposed closure-state transition:**
+1. `pushed` — branch exists on origin but no PR (current state for feat/134-135)
+2. `in-PR` — PR open, review pending
+3. `approved` — PR approved, awaiting merge
+4. `merged` — in main
+5. `deployed` — if applicable
+6. `abandoned` — PR closed without merge
+
+Nudge surface should report explicit state + timestamp: `"feat/134-135 state=pushed (no PR) since 13:00; no closure action taken"` instead of ambiguous "merge-ready."
+
+**Token/permission note:**
+- `code-yeongyu` token has write access to push branches to `ultraworkers/claw-code` but lacks `createPullRequest` permission (GraphQL 404)
+- Issues are disabled on the repo (can't open issue-based tracking)
+- Means closure-state tracking must live inside the repo (ROADMAP) or in an external surface (Discord message edits, `.dogfood-closure.json`)
+
+**Filed:** 2026-04-21 15:05 KST as evidence for #138 by Jobdori dogfood loop.

USAGE.md

@@ -43,6 +43,15 @@ cd rust
 /doctor
 ```
 
+Or run doctor directly with JSON output for scripting:
+
+```bash
+cd rust
+./target/debug/claw doctor --output-format json
+```
+
+**Note:** Diagnostic verbs (`doctor`, `status`, `sandbox`, `version`) support `--output-format json` for machine-readable output. Invalid suffix arguments (e.g., `--json`) are now rejected at parse time rather than falling through to prompt dispatch.
+
 ### Interactive REPL
 
 ```bash

rust/.claw.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "defaultMode": "dontAsk"
+  }
+}

rust/.gitignore

@@ -1,3 +1,7 @@
 target/
 .omx/
 .clawd-agents/
+# Claw Code local artifacts
+.claw/settings.local.json
+.claw/sessions/
+.clawhip/

rust/CLAUDE.md

@@ -0,0 +1,15 @@
+# CLAUDE.md
+
+This file provides guidance to Claw Code (clawcode.dev) when working with code in this repository.
+
+## Detected stack
+- Languages: Rust.
+- Frameworks: none detected from the supported starter markers.
+
+## Verification
+- Run Rust verification from the repo root: `cargo fmt`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`
+
+## Working agreement
+- Prefer small, reviewable changes and keep generated bootstrap files aligned with actual repo workflows.
+- Keep shared defaults in `.claw.json`; reserve `.claw/settings.local.json` for machine-local overrides.
+- Do not overwrite existing `CLAUDE.md` content automatically; update it intentionally when repo workflows change.

rust/Cargo.lock

@@ -17,10 +17,23 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "anes"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
 [[package]]
 name = "api"
 version = "0.1.0"
 dependencies = [
+ "criterion",
  "reqwest",
  "runtime",
  "serde",
@@ -35,6 +48,12 @@ version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -77,6 +96,12 @@ version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
+[[package]]
+name = "cast"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
+
 [[package]]
 name = "cc"
 version = "1.2.58"
@@ -99,6 +124,58 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
+[[package]]
+name = "ciborium"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
+dependencies = [
+ "ciborium-io",
+ "ciborium-ll",
+ "serde",
+]
+
+[[package]]
+name = "ciborium-io"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
+
+[[package]]
+name = "ciborium-ll"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
+dependencies = [
+ "ciborium-io",
+ "half",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+dependencies = [
+ "clap_builder",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+dependencies = [
+ "anstyle",
+ "clap_lex",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "clipboard-win"
 version = "5.4.1"
@@ -144,6 +221,67 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "criterion"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+dependencies = [
+ "anes",
+ "cast",
+ "ciborium",
+ "clap",
+ "criterion-plot",
+ "is-terminal",
+ "itertools",
+ "num-traits",
+ "once_cell",
+ "oorandom",
+ "plotters",
+ "rayon",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "tinytemplate",
+ "walkdir",
+]
+
+[[package]]
+name = "criterion-plot"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+dependencies = [
+ "cast",
+ "itertools",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
 [[package]]
 name = "crossterm"
 version = "0.28.1"
@@ -169,6 +307,12 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -209,6 +353,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
 [[package]]
 name = "endian-type"
 version = "0.1.2"
@@ -245,7 +395,7 @@ checksum = "0ce92ff622d6dadf7349484f42c93271a0d49b7cc4d466a936405bacbe10aa78"
 dependencies = [
  "cfg-if",
  "rustix 1.1.4",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -380,12 +530,29 @@ version = "0.3.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
 
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
 
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
 [[package]]
 name = "home"
 version = "0.5.12"
@@ -622,6 +789,26 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "is-terminal"
+version = "0.4.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
+dependencies = [
+ "hermit-abi",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "itertools"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -755,6 +942,15 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c6673768db2d862beb9b39a78fdcb1a69439615d5794a1be50caa9bc92c81967"
 
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -783,6 +979,12 @@ dependencies = [
  "pkg-config",
 ]
 
+[[package]]
+name = "oorandom"
+version = "11.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -837,6 +1039,34 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "plotters"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747"
+dependencies = [
+ "num-traits",
+ "plotters-backend",
+ "plotters-svg",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "plotters-backend"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a"
+
+[[package]]
+name = "plotters-svg"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670"
+dependencies = [
+ "plotters-backend",
+]
+
 [[package]]
 name = "plugins"
 version = "0.1.0"
@@ -1015,6 +1245,26 @@ dependencies = [
  "getrandom 0.3.4",
 ]
 
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -1138,7 +1388,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.4.15",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -1522,6 +1772,16 @@ dependencies = [
  "zerovec",
 ]
 
+[[package]]
+name = "tinytemplate"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "tinyvec"
 version = "1.11.0"

rust/crates/runtime/src/bash.rs

@@ -8,6 +8,7 @@ use tokio::process::Command as TokioCommand;
 use tokio::runtime::Builder;
 use tokio::time::timeout;
 
+use crate::lane_events::{LaneEvent, ShipMergeMethod, ShipProvenance};
 use crate::sandbox::{
     build_linux_sandbox_command, resolve_sandbox_status_for_request, FilesystemIsolationMode,
     SandboxConfig, SandboxStatus,
@@ -102,11 +103,76 @@ pub fn execute_bash(input: BashCommandInput) -> io::Result<BashCommandOutput> {
     runtime.block_on(execute_bash_async(input, sandbox_status, cwd))
 }
 
+/// Detect git push to main and emit ship provenance event
+fn detect_and_emit_ship_prepared(command: &str) {
+    let trimmed = command.trim();
+    // Simple detection: git push with main/master
+    if trimmed.contains("git push") && (trimmed.contains("main") || trimmed.contains("master")) {
+        // Emit ship.prepared event
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis();
+        let provenance = ShipProvenance {
+            source_branch: get_current_branch().unwrap_or_else(|| "unknown".to_string()),
+            base_commit: get_head_commit().unwrap_or_default(),
+            commit_count: 0, // Would need to calculate from range
+            commit_range: "unknown..HEAD".to_string(),
+            merge_method: ShipMergeMethod::DirectPush,
+            actor: get_git_actor().unwrap_or_else(|| "unknown".to_string()),
+            pr_number: None,
+        };
+        let _event = LaneEvent::ship_prepared(format!("{}", now), &provenance);
+        // Log to stderr as interim routing before event stream integration
+        eprintln!(
+            "[ship.prepared] branch={} -> main, commits={}, actor={}",
+            provenance.source_branch, provenance.commit_count, provenance.actor
+        );
+    }
+}
+
+fn get_current_branch() -> Option<String> {
+    let output = Command::new("git")
+        .args(["branch", "--show-current"])
+        .output()
+        .ok()?;
+    if output.status.success() {
+        Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+    } else {
+        None
+    }
+}
+
+fn get_head_commit() -> Option<String> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--short", "HEAD"])
+        .output()
+        .ok()?;
+    if output.status.success() {
+        Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+    } else {
+        None
+    }
+}
+
+fn get_git_actor() -> Option<String> {
+    let name = Command::new("git")
+        .args(["config", "user.name"])
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())?;
+    Some(name)
+}
+
 async fn execute_bash_async(
     input: BashCommandInput,
     sandbox_status: SandboxStatus,
     cwd: std::path::PathBuf,
 ) -> io::Result<BashCommandOutput> {
+    // Detect and emit ship provenance for git push operations
+    detect_and_emit_ship_prepared(&input.command);
+    
     let mut command = prepare_tokio_command(&input.command, &cwd, &sandbox_status, true);
 
     let output_result = if let Some(timeout_ms) = input.timeout {

rust/crates/runtime/src/lane_events.rs

@@ -38,6 +38,15 @@ pub enum LaneEventName {
     BranchStaleAgainstMain,
     #[serde(rename = "branch.workspace_mismatch")]
     BranchWorkspaceMismatch,
+    /// Ship/provenance events — §4.44.5
+    #[serde(rename = "ship.prepared")]
+    ShipPrepared,
+    #[serde(rename = "ship.commits_selected")]
+    ShipCommitsSelected,
+    #[serde(rename = "ship.merged")]
+    ShipMerged,
+    #[serde(rename = "ship.pushed_main")]
+    ShipPushedMain,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -383,11 +392,31 @@ pub fn dedupe_terminal_events(events: &[LaneEvent]) -> Vec<LaneEvent> {
     result
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BlockedSubphase {
+    #[serde(rename = "blocked.trust_prompt")]
+    TrustPrompt { gate_repo: String },
+    #[serde(rename = "blocked.prompt_delivery")]
+    PromptDelivery { attempt: u32 },
+    #[serde(rename = "blocked.plugin_init")]
+    PluginInit { plugin_name: String },
+    #[serde(rename = "blocked.mcp_handshake")]
+    McpHandshake { server_name: String, attempt: u32 },
+    #[serde(rename = "blocked.branch_freshness")]
+    BranchFreshness { behind_main: u32 },
+    #[serde(rename = "blocked.test_hang")]
+    TestHang { elapsed_secs: u32, test_name: Option<String> },
+    #[serde(rename = "blocked.report_pending")]
+    ReportPending { since_secs: u32 },
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct LaneEventBlocker {
     #[serde(rename = "failureClass")]
     pub failure_class: LaneFailureClass,
     pub detail: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub subphase: Option<BlockedSubphase>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -404,6 +433,29 @@ pub struct LaneCommitProvenance {
     pub lineage: Vec<String>,
 }
 
+/// Ship/provenance metadata — §4.44.5
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ShipProvenance {
+    pub source_branch: String,
+    pub base_commit: String,
+    pub commit_count: u32,
+    pub commit_range: String,
+    pub merge_method: ShipMergeMethod,
+    pub actor: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pr_number: Option<u32>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ShipMergeMethod {
+    DirectPush,
+    FastForward,
+    MergeCommit,
+    SquashMerge,
+    RebaseMerge,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct LaneEvent {
     pub event: LaneEventName,
@@ -487,16 +539,56 @@ impl LaneEvent {
 
     #[must_use]
     pub fn blocked(emitted_at: impl Into<String>, blocker: &LaneEventBlocker) -> Self {
-        Self::new(LaneEventName::Blocked, LaneEventStatus::Blocked, emitted_at)
+        let mut event = Self::new(LaneEventName::Blocked, LaneEventStatus::Blocked, emitted_at)
             .with_failure_class(blocker.failure_class)
-            .with_detail(blocker.detail.clone())
+            .with_detail(blocker.detail.clone());
+        if let Some(ref subphase) = blocker.subphase {
+            event = event.with_data(serde_json::to_value(subphase).expect("subphase should serialize"));
+        }
+        event
     }
 
     #[must_use]
     pub fn failed(emitted_at: impl Into<String>, blocker: &LaneEventBlocker) -> Self {
-        Self::new(LaneEventName::Failed, LaneEventStatus::Failed, emitted_at)
+        let mut event = Self::new(LaneEventName::Failed, LaneEventStatus::Failed, emitted_at)
             .with_failure_class(blocker.failure_class)
-            .with_detail(blocker.detail.clone())
+            .with_detail(blocker.detail.clone());
+        if let Some(ref subphase) = blocker.subphase {
+            event = event.with_data(serde_json::to_value(subphase).expect("subphase should serialize"));
+        }
+        event
+    }
+
+    /// Ship prepared — §4.44.5
+    #[must_use]
+    pub fn ship_prepared(emitted_at: impl Into<String>, provenance: &ShipProvenance) -> Self {
+        Self::new(LaneEventName::ShipPrepared, LaneEventStatus::Ready, emitted_at)
+            .with_data(serde_json::to_value(provenance).expect("ship provenance should serialize"))
+    }
+
+    /// Ship commits selected — §4.44.5
+    #[must_use]
+    pub fn ship_commits_selected(
+        emitted_at: impl Into<String>,
+        commit_count: u32,
+        commit_range: impl Into<String>,
+    ) -> Self {
+        Self::new(LaneEventName::ShipCommitsSelected, LaneEventStatus::Ready, emitted_at)
+            .with_detail(format!("{} commits: {}", commit_count, commit_range.into()))
+    }
+
+    /// Ship merged — §4.44.5
+    #[must_use]
+    pub fn ship_merged(emitted_at: impl Into<String>, provenance: &ShipProvenance) -> Self {
+        Self::new(LaneEventName::ShipMerged, LaneEventStatus::Completed, emitted_at)
+            .with_data(serde_json::to_value(provenance).expect("ship provenance should serialize"))
+    }
+
+    /// Ship pushed to main — §4.44.5
+    #[must_use]
+    pub fn ship_pushed_main(emitted_at: impl Into<String>, provenance: &ShipProvenance) -> Self {
+        Self::new(LaneEventName::ShipPushedMain, LaneEventStatus::Completed, emitted_at)
+            .with_data(serde_json::to_value(provenance).expect("ship provenance should serialize"))
     }
 
     #[must_use]
@@ -570,9 +662,10 @@ mod tests {
 
     use super::{
         compute_event_fingerprint, dedupe_superseded_commit_events, dedupe_terminal_events,
-        is_terminal_event, EventProvenance, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
-        LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus, LaneFailureClass,
-        LaneOwnership, SessionIdentity, WatcherAction,
+        is_terminal_event, BlockedSubphase, EventProvenance, LaneCommitProvenance, LaneEvent,
+        LaneEventBlocker, LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus,
+        LaneFailureClass, LaneOwnership, SessionIdentity, ShipMergeMethod, ShipProvenance,
+        WatcherAction,
     };
 
     #[test]
@@ -601,6 +694,10 @@ mod tests {
                 LaneEventName::BranchWorkspaceMismatch,
                 "branch.workspace_mismatch",
             ),
+            (LaneEventName::ShipPrepared, "ship.prepared"),
+            (LaneEventName::ShipCommitsSelected, "ship.commits_selected"),
+            (LaneEventName::ShipMerged, "ship.merged"),
+            (LaneEventName::ShipPushedMain, "ship.pushed_main"),
         ];
 
         for (event, expected) in cases {
@@ -641,6 +738,10 @@ mod tests {
         let blocker = LaneEventBlocker {
             failure_class: LaneFailureClass::McpStartup,
             detail: "broken server".to_string(),
+            subphase: Some(BlockedSubphase::McpHandshake {
+                server_name: "test-server".to_string(),
+                attempt: 1,
+            }),
         };
 
         let blocked = LaneEvent::blocked("2026-04-04T00:00:00Z", &blocker);
@@ -686,6 +787,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn ship_provenance_events_serialize_to_expected_wire_values() {
+        let provenance = ShipProvenance {
+            source_branch: "feature/provenance".to_string(),
+            base_commit: "dd73962".to_string(),
+            commit_count: 6,
+            commit_range: "dd73962..c956f78".to_string(),
+            merge_method: ShipMergeMethod::DirectPush,
+            actor: "Jobdori".to_string(),
+            pr_number: None,
+        };
+
+        let prepared = LaneEvent::ship_prepared("2026-04-20T14:30:00Z", &provenance);
+        let prepared_json = serde_json::to_value(&prepared).expect("ship event should serialize");
+        assert_eq!(prepared_json["event"], "ship.prepared");
+        assert_eq!(prepared_json["data"]["commit_count"], 6);
+        assert_eq!(prepared_json["data"]["source_branch"], "feature/provenance");
+
+        let pushed = LaneEvent::ship_pushed_main("2026-04-20T14:35:00Z", &provenance);
+        let pushed_json = serde_json::to_value(&pushed).expect("ship event should serialize");
+        assert_eq!(pushed_json["event"], "ship.pushed_main");
+        assert_eq!(pushed_json["data"]["merge_method"], "direct_push");
+
+        let round_trip: LaneEvent =
+            serde_json::from_value(pushed_json).expect("ship event should deserialize");
+        assert_eq!(round_trip.event, LaneEventName::ShipPushedMain);
+    }
+
     #[test]
     fn commit_events_can_carry_worktree_and_supersession_metadata() {
         let event = LaneEvent::commit_created(

rust/crates/runtime/src/lib.rs

@@ -84,9 +84,10 @@ pub use hooks::{
 };
 pub use lane_events::{
     compute_event_fingerprint, dedupe_superseded_commit_events, dedupe_terminal_events,
-    is_terminal_event, EventProvenance, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
-    LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus, LaneFailureClass,
-    LaneOwnership, SessionIdentity, WatcherAction,
+    is_terminal_event, BlockedSubphase, EventProvenance, LaneCommitProvenance, LaneEvent,
+    LaneEventBlocker, LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus,
+    LaneFailureClass, LaneOwnership, SessionIdentity, ShipMergeMethod, ShipProvenance,
+    WatcherAction,
 };
 pub use mcp::{
     mcp_server_signature, mcp_tool_name, mcp_tool_prefix, normalize_name_for_mcp,

rust/crates/rusty-claude-cli/src/main.rs

@@ -447,11 +447,14 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
                 let value = args
                     .get(index + 1)
                     .ok_or_else(|| "missing value for --model".to_string())?;
+                validate_model_syntax(value)?;
                 model = resolve_model_alias_with_config(value);
                 index += 2;
             }
             flag if flag.starts_with("--model=") => {
-                model = resolve_model_alias_with_config(&flag[8..]);
+                let value = &flag[8..];
+                validate_model_syntax(value)?;
+                model = resolve_model_alias_with_config(value);
                 index += 1;
             }
             "--output-format" => {
@@ -704,17 +707,32 @@ fn parse_args(args: &[String]) -> Result<CliAction, String> {
             reasoning_effort,
             allow_broad_cwd,
         ),
-        _other => Ok(CliAction::Prompt {
-            prompt: rest.join(" "),
-            model,
-            output_format,
-            allowed_tools,
-            permission_mode,
-            compact,
-            base_commit,
-            reasoning_effort: reasoning_effort.clone(),
-            allow_broad_cwd,
-        }),
+        other => {
+            if rest.len() == 1 && looks_like_subcommand_typo(other) {
+                if let Some(suggestions) = suggest_similar_subcommand(other) {
+                    let mut message = format!("unknown subcommand: {other}.");
+                    if let Some(line) = render_suggestion_line("Did you mean", &suggestions) {
+                        message.push('\n');
+                        message.push_str(&line);
+                    }
+                    message.push_str(
+                        "\nRun `claw --help` for the full list. If you meant to send a prompt literally, use `claw prompt <text>`.",
+                    );
+                    return Err(message);
+                }
+            }
+            Ok(CliAction::Prompt {
+                prompt: rest.join(" "),
+                model,
+                output_format,
+                allowed_tools,
+                permission_mode,
+                compact,
+                base_commit,
+                reasoning_effort: reasoning_effort.clone(),
+                allow_broad_cwd,
+            })
+        }
     }
 }
 
@@ -743,6 +761,31 @@ fn parse_single_word_command_alias(
     permission_mode_override: Option<PermissionMode>,
     output_format: CliOutputFormat,
 ) -> Option<Result<CliAction, String>> {
+    if rest.is_empty() {
+        return None;
+    }
+
+    // Diagnostic verbs (help, version, status, sandbox, doctor, state) accept only the verb itself
+    // or --help / -h as a suffix. Any other suffix args are unrecognized.
+    let verb = &rest[0];
+    let is_diagnostic = matches!(
+        verb.as_str(),
+        "help" | "version" | "status" | "sandbox" | "doctor" | "state"
+    );
+
+    if is_diagnostic && rest.len() > 1 {
+        // Diagnostic verb with trailing args: reject unrecognized suffix
+        if is_help_flag(&rest[1]) && rest.len() == 2 {
+            // "doctor --help" is valid, routed to parse_local_help_action() instead
+            return None;
+        }
+        // Unrecognized suffix like "--json"
+        return Some(Err(format!(
+            "unrecognized argument `{}` for subcommand `{}`",
+            rest[1], verb
+        )));
+    }
+
     if rest.len() != 1 {
         return None;
     }
@@ -966,6 +1009,65 @@ fn suggest_closest_term<'a>(input: &str, candidates: &'a [&'a str]) -> Option<&'
     ranked_suggestions(input, candidates).into_iter().next()
 }
 
+
+fn suggest_similar_subcommand(input: &str) -> Option<Vec<String>> {
+    const KNOWN_SUBCOMMANDS: &[&str] = &[
+        "help",
+        "version",
+        "status",
+        "sandbox",
+        "doctor",
+        "state",
+        "dump-manifests",
+        "bootstrap-plan",
+        "agents",
+        "mcp",
+        "skills",
+        "system-prompt",
+        "acp",
+        "init",
+        "export",
+        "prompt",
+    ];
+
+    let normalized_input = input.to_ascii_lowercase();
+    let mut ranked = KNOWN_SUBCOMMANDS
+        .iter()
+        .filter_map(|candidate| {
+            let normalized_candidate = candidate.to_ascii_lowercase();
+            let distance = levenshtein_distance(&normalized_input, &normalized_candidate);
+            let prefix_match = common_prefix_len(&normalized_input, &normalized_candidate) >= 4;
+            let substring_match = normalized_candidate.contains(&normalized_input)
+                || normalized_input.contains(&normalized_candidate);
+            ((distance <= 2) || prefix_match || substring_match)
+                .then_some((distance, *candidate))
+        })
+        .collect::<Vec<_>>();
+    ranked.sort_by(|left, right| left.cmp(right).then_with(|| left.1.cmp(right.1)));
+    ranked.dedup_by(|left, right| left.1 == right.1);
+    let suggestions = ranked
+        .into_iter()
+        .map(|(_, candidate)| candidate.to_string())
+        .take(3)
+        .collect::<Vec<_>>();
+    (!suggestions.is_empty()).then_some(suggestions)
+}
+
+fn common_prefix_len(left: &str, right: &str) -> usize {
+    left.chars()
+        .zip(right.chars())
+        .take_while(|(l, r)| l == r)
+        .count()
+}
+
+
+fn looks_like_subcommand_typo(input: &str) -> bool {
+    !input.is_empty()
+        && input
+            .chars()
+            .all(|ch| ch.is_ascii_alphabetic() || ch == '-')
+}
+
 fn ranked_suggestions<'a>(input: &str, candidates: &'a [&'a str]) -> Vec<&'a str> {
     let normalized_input = input.trim_start_matches('/').to_ascii_lowercase();
     let mut ranked = candidates
@@ -1035,6 +1137,37 @@ fn resolve_model_alias_with_config(model: &str) -> String {
     resolve_model_alias(trimmed).to_string()
 }
 
+/// Validate model syntax at parse time.
+/// Accepts: known aliases (opus, sonnet, haiku) or provider/model pattern.
+/// Rejects: empty, whitespace-only, strings with spaces, or invalid chars.
+fn validate_model_syntax(model: &str) -> Result<(), String> {
+    let trimmed = model.trim();
+    if trimmed.is_empty() {
+        return Err("model string cannot be empty".to_string());
+    }
+    // Known aliases are always valid
+    match trimmed {
+        "opus" | "sonnet" | "haiku" => return Ok(()),
+        _ => {}
+    }
+    // Check for spaces (malformed)
+    if trimmed.contains(' ') {
+        return Err(format!(
+            "invalid model syntax: '{}' contains spaces. Use provider/model format or known alias",
+            trimmed
+        ));
+    }
+    // Check provider/model format: provider_id/model_id
+    let parts: Vec<&str> = trimmed.split('/').collect();
+    if parts.len() != 2 || parts[0].is_empty() || parts[1].is_empty() {
+        return Err(format!(
+            "invalid model syntax: '{}'. Expected provider/model (e.g., anthropic/claude-opus-4-6) or known alias (opus, sonnet, haiku)",
+            trimmed
+        ));
+    }
+    Ok(())
+}
+
 fn config_alias_for_current_dir(alias: &str) -> Option<String> {
     if alias.is_empty() {
         return None;
@@ -3811,6 +3944,7 @@ impl LiveCli {
         compact: bool,
     ) -> Result<(), Box<dyn std::error::Error>> {
         match output_format {
+            CliOutputFormat::Json if compact => self.run_prompt_compact_json(input),
             CliOutputFormat::Text if compact => self.run_prompt_compact(input),
             CliOutputFormat::Text => self.run_turn(input),
             CliOutputFormat::Json => self.run_prompt_json(input),
@@ -3830,6 +3964,32 @@ impl LiveCli {
         Ok(())
     }
 
+
+    fn run_prompt_compact_json(&mut self, input: &str) -> Result<(), Box<dyn std::error::Error>> {
+        let (mut runtime, hook_abort_monitor) = self.prepare_turn_runtime(false)?;
+        let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
+        let result = runtime.run_turn(input, Some(&mut permission_prompter));
+        hook_abort_monitor.stop();
+        let summary = result?;
+        self.replace_runtime(runtime)?;
+        self.persist_session()?;
+        println!(
+            "{}",
+            json!({
+                "message": final_assistant_text(&summary),
+                "compact": true,
+                "model": self.model,
+                "usage": {
+                    "input_tokens": summary.usage.input_tokens,
+                    "output_tokens": summary.usage.output_tokens,
+                    "cache_creation_input_tokens": summary.usage.cache_creation_input_tokens,
+                    "cache_read_input_tokens": summary.usage.cache_read_input_tokens,
+                },
+            })
+        );
+        Ok(())
+    }
+
     fn run_prompt_json(&mut self, input: &str) -> Result<(), Box<dyn std::error::Error>> {
         let (mut runtime, hook_abort_monitor) = self.prepare_turn_runtime(false)?;
         let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
@@ -5181,28 +5341,32 @@ fn sandbox_json_value(status: &runtime::SandboxStatus) -> serde_json::Value {
 fn render_help_topic(topic: LocalHelpTopic) -> String {
     match topic {
         LocalHelpTopic::Status => "Status
-  Usage            claw status
+  Usage            claw status [--output-format <format>]
   Purpose          show the local workspace snapshot without entering the REPL
   Output           model, permissions, git state, config files, and sandbox status
+  Formats          text (default), json
   Related          /status · claw --resume latest /status"
             .to_string(),
         LocalHelpTopic::Sandbox => "Sandbox
-  Usage            claw sandbox
+  Usage            claw sandbox [--output-format <format>]
   Purpose          inspect the resolved sandbox and isolation state for the current directory
   Output           namespace, network, filesystem, and fallback details
+  Formats          text (default), json
   Related          /sandbox · claw status"
             .to_string(),
         LocalHelpTopic::Doctor => "Doctor
-  Usage            claw doctor
+  Usage            claw doctor [--output-format <format>]
   Purpose          diagnose local auth, config, workspace, sandbox, and build metadata
   Output           local-only health report; no provider request or session resume required
+  Formats          text (default), json
   Related          /doctor · claw --resume latest /doctor"
             .to_string(),
         LocalHelpTopic::Acp => "ACP / Zed
-  Usage            claw acp [serve]
+  Usage            claw acp [serve] [--output-format <format>]
   Aliases          claw --acp · claw -acp
   Purpose          explain the current editor-facing ACP/Zed launch contract without starting the runtime
   Status           discoverability only; `serve` is a status alias and does not launch a daemon yet
+  Formats          text (default), json
   Related          ROADMAP #64a (discoverability) · ROADMAP #76 (real ACP support) · claw --help"
             .to_string(),
     }
@@ -8421,6 +8585,7 @@ mod tests {
             request_id: Some("req_jobdori_789".to_string()),
             body: String::new(),
             retryable: true,
+            suggested_action: None,
         };
 
         let rendered = format_user_visible_api_error("session-issue-22", &error);
@@ -8443,6 +8608,7 @@ mod tests {
                 request_id: Some("req_jobdori_790".to_string()),
                 body: String::new(),
                 retryable: true,
+                suggested_action: None,
             }),
         };
 
@@ -8506,6 +8672,7 @@ mod tests {
             request_id: Some("req_ctx_456".to_string()),
             body: String::new(),
             retryable: false,
+            suggested_action: None,
         };
 
         let rendered = format_user_visible_api_error("session-issue-32", &error);
@@ -8537,6 +8704,7 @@ mod tests {
                 request_id: Some("req_ctx_retry_789".to_string()),
                 body: String::new(),
                 retryable: false,
+                suggested_action: None,
             }),
         };
 
@@ -8879,7 +9047,7 @@ mod tests {
         let args = vec![
             "--output-format=json".to_string(),
             "--model".to_string(),
-            "claude-opus".to_string(),
+            "opus".to_string(),
             "explain".to_string(),
             "this".to_string(),
         ];
@@ -8887,7 +9055,7 @@ mod tests {
             parse_args(&args).expect("args should parse"),
             CliAction::Prompt {
                 prompt: "explain this".to_string(),
-                model: "claude-opus".to_string(),
+                model: "claude-opus-4-6".to_string(),
                 output_format: CliOutputFormat::Json,
                 allowed_tools: None,
                 permission_mode: PermissionMode::DangerFullAccess,
@@ -9657,15 +9825,21 @@ mod tests {
     fn multi_word_prompt_still_uses_shorthand_prompt_mode() {
         let _guard = env_lock();
         std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        // Input is ["help", "me", "debug"] so the joined prompt shorthand
-        // must be "help me debug". A previous batch accidentally rewrote
-        // the expected string to "$help overview" (copy-paste slip).
+        // Input is ["--model", "opus", "please", "debug", "this"] so the joined
+        // prompt shorthand must stay a normal multi-word prompt while still
+        // honoring alias validation at parse time.
         assert_eq!(
-            parse_args(&["help".to_string(), "me".to_string(), "debug".to_string()])
-                .expect("prompt shorthand should still work"),
+            parse_args(&[
+                "--model".to_string(),
+                "opus".to_string(),
+                "please".to_string(),
+                "debug".to_string(),
+                "this".to_string(),
+            ])
+            .expect("prompt shorthand should still work"),
             CliAction::Prompt {
-                prompt: "help me debug".to_string(),
-                model: DEFAULT_MODEL.to_string(),
+                prompt: "please debug this".to_string(),
+                model: "claude-opus-4-6".to_string(),
                 output_format: CliOutputFormat::Text,
                 allowed_tools: None,
                 permission_mode: crate::default_permission_mode(),
@@ -9801,6 +9975,109 @@ mod tests {
         assert!(report.contains("Use /help"));
     }
 
+
+    #[test]
+    fn typoed_doctor_subcommand_returns_did_you_mean_error() {
+        let error = parse_args(&["doctorr".to_string()]).expect_err("doctorr should error");
+        assert!(error.contains("unknown subcommand: doctorr."));
+        assert!(error.contains("Did you mean"));
+        assert!(error.contains("doctor"));
+    }
+
+    #[test]
+    fn typoed_skills_subcommand_returns_did_you_mean_error() {
+        let error = parse_args(&["skilsl".to_string()]).expect_err("skilsl should error");
+        assert!(error.contains("unknown subcommand: skilsl."));
+        assert!(error.contains("skills"));
+    }
+
+    #[test]
+    fn typoed_status_subcommand_returns_did_you_mean_error() {
+        let error = parse_args(&["statuss".to_string()]).expect_err("statuss should error");
+        assert!(error.contains("unknown subcommand: statuss."));
+        assert!(error.contains("status"));
+    }
+
+    #[test]
+    fn typoed_export_subcommand_returns_did_you_mean_error() {
+        let error = parse_args(&["exporrt".to_string()]).expect_err("exporrt should error");
+        assert!(error.contains("unknown subcommand: exporrt."));
+        assert!(error.contains("Did you mean"));
+        assert!(error.contains("export"));
+    }
+
+    #[test]
+    fn typoed_mcp_subcommand_returns_did_you_mean_error() {
+        let error = parse_args(&["mcpp".to_string()]).expect_err("mcpp should error");
+        assert!(error.contains("unknown subcommand: mcpp."));
+        assert!(error.contains("mcp"));
+    }
+
+    #[test]
+    fn multi_word_prompt_still_bypasses_subcommand_typo_guard() {
+        assert_eq!(
+            parse_args(&[
+                "hello".to_string(),
+                "world".to_string(),
+                "this".to_string(),
+                "is".to_string(),
+                "a".to_string(),
+                "prompt".to_string(),
+            ])
+            .expect("multi-word prompt should still parse"),
+            CliAction::Prompt {
+                prompt: "hello world this is a prompt".to_string(),
+                model: DEFAULT_MODEL.to_string(),
+                output_format: CliOutputFormat::Text,
+                allowed_tools: None,
+                permission_mode: crate::default_permission_mode(),
+                compact: false,
+                base_commit: None,
+                reasoning_effort: None,
+                allow_broad_cwd: false,
+            }
+        );
+    }
+
+    #[test]
+    fn prompt_subcommand_allows_literal_typo_word() {
+        assert_eq!(
+            parse_args(&["prompt".to_string(), "doctorr".to_string()])
+                .expect("explicit prompt subcommand should allow literal typo word"),
+            CliAction::Prompt {
+                prompt: "doctorr".to_string(),
+                model: DEFAULT_MODEL.to_string(),
+                output_format: CliOutputFormat::Text,
+                allowed_tools: None,
+                permission_mode: PermissionMode::DangerFullAccess,
+                compact: false,
+                base_commit: None,
+                reasoning_effort: None,
+                allow_broad_cwd: false,
+            }
+        );
+    }
+
+
+    #[test]
+    fn punctuation_bearing_single_token_still_dispatches_to_prompt() {
+        assert_eq!(
+            parse_args(&["PARITY_SCENARIO:bash_permission_prompt_approved".to_string()])
+                .expect("scenario token should still dispatch to prompt"),
+            CliAction::Prompt {
+                prompt: "PARITY_SCENARIO:bash_permission_prompt_approved".to_string(),
+                model: DEFAULT_MODEL.to_string(),
+                output_format: CliOutputFormat::Text,
+                allowed_tools: None,
+                permission_mode: PermissionMode::DangerFullAccess,
+                compact: false,
+                base_commit: None,
+                reasoning_effort: None,
+                allow_broad_cwd: false,
+            }
+        );
+    }
+
     #[test]
     fn formats_namespaced_omc_slash_command_with_contract_guidance() {
         let report = format_unknown_slash_command_message("oh-my-claudecode:hud");

rust/crates/rusty-claude-cli/tests/compact_output.rs

@@ -5,6 +5,7 @@ use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use mock_anthropic_service::{MockAnthropicService, SCENARIO_PREFIX};
+use serde_json::Value;
 
 static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
 
@@ -125,6 +126,60 @@ fn compact_flag_streaming_text_only_emits_final_message_text() {
     fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed");
 }
 
+#[test]
+fn compact_flag_with_json_output_emits_structured_json() {
+    let runtime = tokio::runtime::Runtime::new().expect("tokio runtime should build");
+    let server = runtime
+        .block_on(MockAnthropicService::spawn())
+        .expect("mock service should start");
+    let base_url = server.base_url();
+
+    let workspace = unique_temp_dir("compact-json");
+    let config_home = workspace.join("config-home");
+    let home = workspace.join("home");
+    fs::create_dir_all(&workspace).expect("workspace should exist");
+    fs::create_dir_all(&config_home).expect("config home should exist");
+    fs::create_dir_all(&home).expect("home should exist");
+
+    let prompt = format!("{SCENARIO_PREFIX}streaming_text");
+    let output = run_claw(
+        &workspace,
+        &config_home,
+        &home,
+        &base_url,
+        &[
+            "--model",
+            "sonnet",
+            "--permission-mode",
+            "read-only",
+            "--output-format",
+            "json",
+            "--compact",
+            &prompt,
+        ],
+    );
+
+    assert!(
+        output.status.success(),
+        "compact json run should succeed
+stdout:
+{}
+
+stderr:
+{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr),
+    );
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
+    let parsed: Value = serde_json::from_str(&stdout).expect("compact json stdout should parse");
+    assert_eq!(parsed["message"], "Mock streaming says hello from the parity harness.");
+    assert_eq!(parsed["compact"], true);
+    assert_eq!(parsed["model"], "claude-sonnet-4-6");
+    assert!(parsed["usage"].is_object());
+
+    fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed");
+}
+
 fn run_claw(
     cwd: &std::path::Path,
     config_home: &std::path::Path,

rust/crates/tools/src/lib.rs

@@ -4459,6 +4459,7 @@ fn classify_lane_blocker(error: &str) -> LaneEventBlocker {
     LaneEventBlocker {
         failure_class: classify_lane_failure(error),
         detail,
+        subphase: None,
     }
 }