Keep resumed /status JSON aligned with live status output

The resumed slash-command path built a reduced status JSON payload by hand, so it drifted from the fresh status schema and dropped metadata like model, permission mode, workspace counters, and sandbox details. Reuse a shared status JSON builder for both code paths and tighten the resume regression tests to lock parity in place.

Constraint: Resume mode does not carry an active runtime model, so restored sessions continue to report the existing restored-session sentinel value
Rejected: Copy the fresh status JSON shape into the resume path again | would recreate the same schema drift risk
Confidence: high
Scope-risk: narrow
Directive: Keep resumed and fresh /status JSON on the same helper so future schema changes stay in parity
Tested: Reproduced failure in temporary HEAD worktree with strengthened resumed_status_command_emits_structured_json_when_requested
Tested: cargo test -p rusty-claude-cli resumed_status_command_emits_structured_json_when_requested --test resume_slash_commands -- --exact --nocapture
Tested: cargo test -p rusty-claude-cli doctor_and_resume_status_emit_json_when_requested --test output_format_contract -- --exact --nocapture
Tested: cargo test --workspace
Tested: cargo fmt --check
Tested: cargo clippy --workspace --all-targets -- -D warnings

.github/FUNDING.yml

@@ -1 +1,3 @@
-github: instructkr
+github:
+  - ultraworkers
+  - Yeachan-Heo

.github/scripts/check_doc_source_of_truth.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import sys
+
+ROOT = Path(__file__).resolve().parents[2]
+FILES = [
+    ROOT / 'README.md',
+    ROOT / 'USAGE.md',
+    ROOT / 'PARITY.md',
+    ROOT / 'PHILOSOPHY.md',
+    ROOT / 'ROADMAP.md',
+    ROOT / '.github' / 'FUNDING.yml',
+]
+FILES.extend(sorted((ROOT / 'docs').rglob('*.md')) if (ROOT / 'docs').exists() else [])
+
+FORBIDDEN = {
+    r'github\.com/Yeachan-Heo/claw-code(?!-parity)': 'replace old claw-code GitHub links with ultraworkers/claw-code',
+    r'github\.com/code-yeongyu/claw-code': 'replace stale alternate claw-code GitHub links with ultraworkers/claw-code',
+    r'discord\.gg/6ztZB9jvWq': 'replace the stale UltraWorkers Discord invite with the current invite',
+    r'api\.star-history\.com/svg\?repos=Yeachan-Heo/claw-code': 'update star-history embeds to ultraworkers/claw-code',
+    r'star-history\.com/#Yeachan-Heo/claw-code': 'update star-history links to ultraworkers/claw-code',
+    r'assets/clawd-hero\.jpeg': 'rename stale hero asset references to assets/claw-hero.jpeg',
+    r'assets/instructkr\.png': 'remove stale instructkr image references',
+}
+
+errors: list[str] = []
+for path in FILES:
+    if not path.exists():
+        continue
+    text = path.read_text(encoding='utf-8')
+    for pattern, message in FORBIDDEN.items():
+        for match in re.finditer(pattern, text):
+            line = text.count('\n', 0, match.start()) + 1
+            errors.append(f'{path.relative_to(ROOT)}:{line}: {message}')
+
+if errors:
+    print('doc source-of-truth check failed:', file=sys.stderr)
+    for error in errors:
+        print(f'  - {error}', file=sys.stderr)
+    sys.exit(1)
+
+print('doc source-of-truth check passed')

.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release binaries
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: build-${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-x64
+            os: ubuntu-latest
+            bin: claw
+            artifact_name: claw-linux-x64
+          - name: macos-arm64
+            os: macos-14
+            bin: claw
+            artifact_name: claw-macos-arm64
+    defaults:
+      run:
+        working-directory: rust
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust -> target
+
+      - name: Build release binary
+        run: cargo build --release -p rusty-claude-cli
+
+      - name: Package artifact
+        shell: bash
+        run: |
+          mkdir -p dist
+          cp "target/release/${{ matrix.bin }}" "dist/${{ matrix.artifact_name }}"
+          chmod +x "dist/${{ matrix.artifact_name }}"
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: rust/dist/${{ matrix.artifact_name }}
+
+      - name: Upload release asset
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: rust/dist/${{ matrix.artifact_name }}
+          fail_on_unmatched_files: true

.github/workflows/rust-ci.yml

@@ -8,12 +8,28 @@ on:
       - 'omx-issue-*'
     paths:
       - .github/workflows/rust-ci.yml
+      - .github/scripts/check_doc_source_of_truth.py
+      - .github/FUNDING.yml
+      - README.md
+      - USAGE.md
+      - PARITY.md
+      - PHILOSOPHY.md
+      - ROADMAP.md
+      - docs/**
       - rust/**
   pull_request:
     branches:
       - main
     paths:
       - .github/workflows/rust-ci.yml
+      - .github/scripts/check_doc_source_of_truth.py
+      - .github/FUNDING.yml
+      - README.md
+      - USAGE.md
+      - PARITY.md
+      - PHILOSOPHY.md
+      - ROADMAP.md
+      - docs/**
       - rust/**
   workflow_dispatch:
 
@@ -29,6 +45,20 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  doc-source-of-truth:
+    name: docs source-of-truth
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Check docs and metadata for stale branding
+        run: python .github/scripts/check_doc_source_of_truth.py
+
   fmt:
     name: cargo fmt
     runs-on: ubuntu-latest
@@ -43,8 +73,8 @@ jobs:
       - name: Check formatting
         run: cargo fmt --all --check
 
-  test-rusty-claude-cli:
-    name: cargo test -p rusty-claude-cli
+  test-workspace:
+    name: cargo test --workspace
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -52,5 +82,19 @@ jobs:
       - uses: Swatinem/rust-cache@v2
         with:
           workspaces: rust -> target
-      - name: Run crate tests
-        run: cargo test -p rusty-claude-cli
+      - name: Run workspace tests
+        run: cargo test --workspace
+
+  clippy-workspace:
+    name: cargo clippy --workspace
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust -> target
+      - name: Run workspace clippy
+        run: cargo clippy --workspace

Containerfile

@@ -0,0 +1,13 @@
+FROM rust:bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        git \
+        libssl-dev \
+        pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV CARGO_TERM_COLOR=always
+WORKDIR /workspace
+CMD ["bash"]

README.md

@@ -1,7 +1,17 @@
-# Rewriting Project Claw Code
+# Claw Code
 
 <p align="center">
-  <strong>⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐</strong>
+  <a href="https://github.com/ultraworkers/claw-code">ultraworkers/claw-code</a>
+  ·
+  <a href="./USAGE.md">Usage</a>
+  ·
+  <a href="./rust/README.md">Rust workspace</a>
+  ·
+  <a href="./PARITY.md">Parity</a>
+  ·
+  <a href="./ROADMAP.md">Roadmap</a>
+  ·
+  <a href="https://discord.gg/5TUQKqFWd">UltraWorkers Discord</a>
 </p>
 
 <p align="center">
@@ -9,177 +19,75 @@
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date&theme=dark" />
       <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" />
-      <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
+      <img alt="Star history for ultraworkers/claw-code" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
     </picture>
   </a>
 </p>
 
 <p align="center">
-  <img src="assets/clawd-hero.jpeg" alt="Claw" width="300" />
+  <img src="assets/claw-hero.jpeg" alt="Claw Code" width="300" />
 </p>
 
-<p align="center">
-  <strong>Autonomously maintained by lobsters/claws — not by human hands</strong>
-</p>
-
-<p align="center">
-  <a href="https://github.com/Yeachan-Heo/clawhip">clawhip</a> ·
-  <a href="https://github.com/code-yeongyu/oh-my-openagent">oh-my-openagent</a> ·
-  <a href="https://github.com/Yeachan-Heo/oh-my-claudecode">oh-my-claudecode</a> ·
-  <a href="https://github.com/Yeachan-Heo/oh-my-codex">oh-my-codex</a> ·
-  <a href="https://discord.gg/6ztZB9jvWq">UltraWorkers Discord</a>
-</p>
+Claw Code is the public Rust implementation of the `claw` CLI agent harness.
+The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**.
 
 > [!IMPORTANT]
-> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, then use [`rust/README.md`](./rust/README.md) for crate-level details.
+> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow.
 
-> Want the bigger idea behind this repo? Read [`PHILOSOPHY.md`](./PHILOSOPHY.md) and Sigrid Jin's public explanation: https://x.com/realsigridjin/status/2039472968624185713
+## Current repository shape
 
-> Shout-out to the UltraWorkers ecosystem powering this repo: [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), and the [UltraWorkers Discord](https://discord.gg/6ztZB9jvWq).
+- **`rust/`** — canonical Rust workspace and the `claw` CLI binary
+- **`USAGE.md`** — task-oriented usage guide for the current product surface
+- **`PARITY.md`** — Rust-port parity status and migration notes
+- **`ROADMAP.md`** — active roadmap and cleanup backlog
+- **`PHILOSOPHY.md`** — project intent and system-design framing
+- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface
 
----
-
-## Backstory
-
-This repo is maintained by **lobsters/claws**, not by a conventional human-only dev team.
-
-The people behind the system are [Bellman / Yeachan Heo](https://github.com/Yeachan-Heo) and friends like [Yeongyu](https://github.com/code-yeongyu), but the repo itself is being pushed forward by autonomous claw workflows: parallel coding sessions, event-driven orchestration, recovery loops, and machine-readable lane state.
-
-In practice, that means this project is not just *about* coding agents — it is being **actively built by them**. Features, tests, telemetry, docs, and workflow hardening are landed through claw-driven loops using [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), and [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex).
-
-This repository exists to prove that an open coding harness can be built **autonomously, in public, and at high velocity** — with humans setting direction and claws doing the grinding.
-
-See the public build story here:
-
-https://x.com/realsigridjin/status/2039472968624185713
-
-![Tweet screenshot](assets/tweet-screenshot.png)
-
----
-
-## Porting Status
-
-The main source tree is now Python-first.
-
-- `src/` contains the active Python porting workspace
-- `tests/` verifies the current Python workspace
-- the exposed snapshot is no longer part of the tracked repository state
-
-The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.
-
-## Why this rewrite exists
-
-I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.
-
-This repository now focuses on Python porting work instead.
-
-## Repository Layout
-
-```text
-.
-├── src/                                # Python porting workspace
-│   ├── __init__.py
-│   ├── commands.py
-│   ├── main.py
-│   ├── models.py
-│   ├── port_manifest.py
-│   ├── query_engine.py
-│   ├── task.py
-│   └── tools.py
-├── tests/                              # Python verification
-├── assets/omx/                         # OmX workflow screenshots
-├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
-└── README.md
-```
-
-## Python Workspace Overview
-
-The new Python `src/` tree currently provides:
-
-- **`port_manifest.py`** — summarizes the current Python workspace structure
-- **`models.py`** — dataclasses for subsystems, modules, and backlog state
-- **`commands.py`** — Python-side command port metadata
-- **`tools.py`** — Python-side tool port metadata
-- **`query_engine.py`** — renders a Python porting summary from the active workspace
-- **`main.py`** — a CLI entrypoint for manifest and summary output
-
-## Quickstart
-
-Render the Python porting summary:
+## Quick start
 
 ```bash
-python3 -m src.main summary
+cd rust
+cargo build --workspace
+./target/debug/claw --help
+./target/debug/claw prompt "summarize this repository"
 ```
 
-Print the current Python workspace manifest:
+Authenticate with either an API key or the built-in OAuth flow:
 
 ```bash
-python3 -m src.main manifest
+export ANTHROPIC_API_KEY="sk-ant-..."
+# or
+cd rust
+./target/debug/claw login
 ```
 
-List the current Python modules:
+Run the workspace test suite:
 
 ```bash
-python3 -m src.main subsystems --limit 16
+cd rust
+cargo test --workspace
 ```
 
-Run verification:
+## Documentation map
 
-```bash
-python3 -m unittest discover -s tests -v
-```
+- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness
+- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout
+- [`PARITY.md`](./PARITY.md) — parity status for the Rust port
+- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details
+- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work
+- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated
 
-Run the parity audit against the local ignored archive (when present):
+## Ecosystem
 
-```bash
-python3 -m src.main parity-audit
-```
+Claw Code is built in the open alongside the broader UltraWorkers toolchain:
 
-Inspect mirrored command/tool inventories:
+- [clawhip](https://github.com/Yeachan-Heo/clawhip)
+- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)
+- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
+- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
+- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd)
 
-```bash
-python3 -m src.main commands --limit 10
-python3 -m src.main tools --limit 10
-```
-
-## Current Parity Checkpoint
-
-The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.
-
-
-## Built with `oh-my-codex`
-
-The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.
-
-- **`$team` mode:** used for coordinated parallel review and architectural feedback
-- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
-- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace
-
-### OmX workflow screenshots
-
-![OmX workflow screenshot 1](assets/omx/omx-readme-review-1.png)
-
-*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*
-
-![OmX workflow screenshot 2](assets/omx/omx-readme-review-2.png)
-
-*Split-pane review and verification flow during the final README wording pass.*
-
-## Community
-
-<p align="center">
-  <a href="https://discord.gg/6ztZB9jvWq"><img src="https://img.shields.io/badge/UltraWorkers-Discord-5865F2?logo=discord&style=for-the-badge" alt="UltraWorkers Discord" /></a>
-</p>
-
-Join the [**UltraWorkers Discord**](https://discord.gg/6ztZB9jvWq) — the community around clawhip, oh-my-openagent, oh-my-claudecode, oh-my-codex, and claw-code. Come chat about LLMs, harness engineering, agent workflows, and autonomous software development.
-
-[![Discord](https://img.shields.io/badge/Join%20Discord-UltraWorkers-5865F2?logo=discord&style=for-the-badge)](https://discord.gg/6ztZB9jvWq)
-
-## Star History
-
-See the chart at the top of this README.
-
-## Ownership / Affiliation Disclaimer
+## Ownership / affiliation disclaimer
 
 - This repository does **not** claim ownership of the original Claude Code source material.
 - This repository is **not affiliated with, endorsed by, or maintained by Anthropic**.

ROADMAP.md

@@ -271,19 +271,18 @@ Acceptance:
 Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 = clawability hardening, P3 = swarm-efficiency improvements.
 
 **P0 — Fix first (CI reliability)**
-1. Isolate `render_diff_report` tests into tmpdir — flaky under `cargo test --workspace`; reads real working-tree state; breaks CI during active worktree ops
-2. Expand GitHub CI from single-crate coverage to workspace-grade verification — current `rust-ci.yml` runs `cargo fmt` and `cargo test -p rusty-claude-cli`, but misses broader `cargo test --workspace` coverage that already passes locally
-3. Add release-grade binary workflow — repo has a Rust CLI and release intent, but no GitHub Actions path that builds tagged artifacts / checks release packaging before a publish step
-4. Add container-first test/run docs — runtime detects Docker/Podman/container state, but docs do not show a canonical container workflow for `cargo test --workspace`, binary execution, or bind-mounted repo usage
-5. Surface `doctor` / preflight diagnostics in onboarding docs and help — the CLI already has setup-diagnosis commands and branch preflight machinery, but they are not prominent enough in README/USAGE, so new users still ask manual setup questions instead of running a built-in health check first
-6. Add branding/source-of-truth residue checks for docs — after repo migration, old org names can survive in badges, star-history URLs, and copied snippets; docs need a consistency pass or CI lint to catch stale branding automatically
-7. Reconcile README product narrative with current repo reality — top-level docs now say the active workspace is Rust, but later sections still describe the repo as Python-first; users should not have to infer which implementation is canonical
-8. Eliminate warning spam from first-run help/build path — `cargo run -p rusty-claude-cli -- --help` currently prints a wall of compile warnings before the actual help text, which pollutes the first-touch UX and hides the product surface behind unrelated noise
-9. Promote `doctor` from slash-only to top-level CLI entrypoint — users naturally try `claw doctor`, but today it errors and tells them to enter a REPL or resume path first; healthcheck flows should be callable directly from the shell
-10. Make machine-readable status commands actually machine-readable — `status` and `sandbox` accept the global `--output-format json` flag path, but currently still render prose tables, which breaks shell automation and agent-friendly health polling
-11. Unify legacy config/skill namespaces in user-facing output — `skills` currently surfaces mixed project roots like `.codex` and `.claude`, which leaks historical layers into the current product and makes it unclear which config namespace is canonical
-12. Honor JSON output on inventory commands like `skills` and `mcp` — these are exactly the commands agents and shell scripts want to inspect programmatically, but `--output-format json` still yields prose, forcing text scraping where structured inventory should exist
-13. Audit `--output-format` contract across the whole CLI surface — current behavior is inconsistent by subcommand, so agents cannot trust the global flag without command-by-command probing; the format contract itself needs to become deterministic
+1. Isolate `render_diff_report` tests into tmpdir — **done**: `render_diff_report_for()` tests run in temp git repos instead of the live working tree, and targeted `cargo test -p rusty-claude-cli render_diff_report -- --nocapture` now stays green during branch/worktree activity
+2. Expand GitHub CI from single-crate coverage to workspace-grade verification — **done**: `.github/workflows/rust-ci.yml` now runs `cargo test --workspace` plus fmt/clippy at the workspace level
+3. Add release-grade binary workflow — **done**: `.github/workflows/release.yml` now builds tagged Rust release artifacts for the CLI
+4. Add container-first test/run docs — **done**: `Containerfile` + `docs/container.md` document the canonical Docker/Podman workflow for build, bind-mount, and `cargo test --workspace` usage
+5. Surface `doctor` / preflight diagnostics in onboarding docs and help — **done**: README + USAGE now put `claw doctor` / `/doctor` in the first-run path and point at the built-in preflight report
+6. Automate branding/source-of-truth residue checks in CI — **done**: `.github/scripts/check_doc_source_of_truth.py` and the `doc-source-of-truth` CI job now block stale repo/org/invite residue in tracked docs and metadata
+7. Eliminate warning spam from first-run help/build path — **done**: current `cargo run -q -p rusty-claude-cli -- --help` renders clean help output without a warning wall before the product surface
+8. Promote `doctor` from slash-only to top-level CLI entrypoint — **done**: `claw doctor` is now a local shell entrypoint with regression coverage for direct help and health-report output
+9. Make machine-readable status commands actually machine-readable — **done**: `claw --output-format json status` and `claw --output-format json sandbox` now emit structured JSON snapshots instead of prose tables
+10. Unify legacy config/skill namespaces in user-facing output — **done**: skills/help JSON/text output now present `.claw` as the canonical namespace and collapse legacy roots behind `.claw`-shaped source ids/labels
+11. Honor JSON output on inventory commands like `skills` and `mcp` — **done**: direct CLI inventory commands now honor `--output-format json` with structured payloads for both skills and MCP inventory
+12. Audit `--output-format` contract across the whole CLI surface — **done**: direct CLI commands now honor deterministic JSON/text handling across help/version/status/sandbox/agents/mcp/skills/bootstrap-plan/system-prompt/init/doctor, with regression coverage in `output_format_contract.rs` and resumed `/status` JSON coverage
 
 **P1 — Next (integration wiring, unblocks verification)**
 2. Add cross-module integration tests — **done**: 12 integration tests covering worker→recovery→policy, stale_branch→policy, green_contract→policy, reconciliation flows
@@ -301,16 +300,19 @@ Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 =
 12. Lane board / machine-readable status API — **done**: Lane completion hardening + `LaneContext::completed` auto-detection + MCP degraded reporting surface machine-readable state
 13. **Session completion failure classification** — **done**: `WorkerFailureKind::Provider` + `observe_completion()` + recovery recipe bridge landed
 14. **Config merge validation gap** — **done**: `config.rs` hook validation before deep-merge (+56 lines), malformed entries fail with source-path context instead of merged parse errors
-15. **MCP manager discovery flaky test** — `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` has intermittent timing issues in CI; temporarily ignored, needs root cause fix
-
-16. **Commit provenance / worktree-aware push events** — clawhip build stream shows duplicate-looking commit messages and worktree-originated pushes without clear supersession indicators; add worktree/branch metadata to push events and de-dup superseded commits in build stream display
-17. **Orphaned module integration audit** — `session_control` is `pub mod` exported from `runtime` but has zero consumers across the entire workspace (no import, no call site outside its own file). `trust_resolver` types are re-exported from `lib.rs` but never instantiated outside unit tests. These modules implement core clawability contracts (session management, trust resolution) that are structurally dead — built but not wired into the CLI or tools crate. **Action:** audit all `pub mod` / `pub use` exports from `runtime` for actual call sites; either wire orphaned modules into the real execution path or demote to `pub(crate)` / `cfg(test)` to prevent false clawability surface.
-18. **Context-window preflight gap** — claw-code auto-compacts only after cumulative input crosses a static `100_000`-token threshold, while provider requests derive `max_tokens` from a naive model-name heuristic (`opus` => 32k, else 64k) and do not appear to preflight `estimated_prompt_tokens + requested_output_tokens` against the selected model’s actual context window. Result: giant sessions can be sent upstream and fail hard with provider-side `input_exceeds_context_by_*` errors instead of local preflight compaction/rejection. **Action:** add a model-context registry + request-size preflight before provider call; if projected request exceeds context, emit a structured `context_window_blocked` event and auto-compact or force `/compact` before retry.
-19. **Subcommand help falls through into runtime/API path** — direct dogfood shows `./target/debug/claw doctor --help` and `./target/debug/claw status --help` do not render local subcommand help. Instead they enter the request path, show `🦀 Thinking...`, then fail with `api returned 500 ... auth_unavailable: no auth available`. Help/usage surfaces must be pure local parsing and never require auth or provider reachability. **Action:** fix argv dispatch so `<subcommand> --help` is intercepted before runtime startup/API client initialization; add regression tests for `doctor --help`, `status --help`, and similar local-info commands.
+15. **MCP manager discovery flaky test** — **done**: `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` now runs as a normal workspace test again after repeated stable passes, so degraded-startup coverage is no longer hidden behind `#[ignore]`
 
+16. **Commit provenance / worktree-aware push events** — **done**: `LaneCommitProvenance` now carries branch/worktree/canonical-commit/supersession metadata in lane events, and `dedupe_superseded_commit_events()` is applied before agent manifests are written so superseded commit events collapse to the latest canonical lineage
+17. **Orphaned module integration audit** — **done**: `runtime` now keeps `session_control` and `trust_resolver` behind `#[cfg(test)]` until they are wired into a real non-test execution path, so normal builds no longer advertise dead clawability surface area.
+18. **Context-window preflight gap** — **done**: provider request sizing now emits `context_window_blocked` before oversized requests leave the process, using a model-context registry instead of the old naive max-token heuristic.
+19. **Subcommand help falls through into runtime/API path** — **done**: `claw doctor --help`, `claw status --help`, `claw sandbox --help`, and nested `mcp`/`skills` help are now intercepted locally without runtime/provider startup, with regression tests covering the direct CLI paths.
+20. **Session state classification gap (working vs blocked vs finished vs truly stale)** — **done**: agent manifests now derive machine states such as `working`, `blocked_background_job`, `blocked_merge_conflict`, `degraded_mcp`, `interrupted_transport`, `finished_pending_report`, and `finished_cleanable`, and terminal-state persistence records commit provenance plus derived state so downstream monitoring can distinguish quiet progress from truly idle sessions.
+21. **Resumed `/status` JSON parity gap** — dogfooding shows fresh `claw status --output-format json` now emits structured JSON, but resumed slash-command status still leaks through a text-shaped path in at least one dispatch path. Local CI-equivalent repro fails `rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs::resumed_status_command_emits_structured_json_when_requested` with `expected value at line 1 column 1`, so resumed automation can receive text where JSON was explicitly requested. **Action:** unify fresh vs resumed `/status` rendering through one output-format contract and add regression coverage so resumed JSON output is guaranteed valid.
+22. **Opaque failure surface for session/runtime crashes** — repeated dogfood-facing failures can currently collapse to generic wrappers like `Something went wrong while processing your request. Please try again, or use /new to start a fresh session.` without exposing whether the fault was provider auth, session corruption, slash-command dispatch, render failure, or transport/runtime panic. This blocks fast self-recovery and turns actionable clawability bugs into blind retries. **Action:** preserve a short user-safe failure class (`provider_auth`, `session_load`, `command_dispatch`, `render`, `runtime_panic`, etc.), attach a local trace/session id, and ensure operators can jump from the chat-visible error to the exact failure log quickly.
+23. **`doctor --output-format json` check-level structure gap** — direct dogfooding shows `claw doctor --output-format json` exposes `has_failures` at the top level, but individual check results (`auth`, `config`, `workspace`, `sandbox`, `system`) are buried inside flat prose fields like `message` / `report`. That forces claws to string-scrape human text instead of consuming stable machine-readable diagnostics. **Action:** emit structured per-check JSON (`name`, `status`, `summary`, `details`, and relevant typed fields such as sandbox fallback reason) while preserving the current human-readable report for text mode.
 **P3 — Swarm efficiency**
-13. Swarm branch-lock protocol — detect same-module/same-branch collision before parallel workers drift into duplicate implementation
-14. Commit provenance / worktree-aware push events — emit branch, worktree, superseded-by, and canonical commit lineage so parallel sessions stop producing duplicate-looking push summaries
+13. Swarm branch-lock protocol — **done**: `branch_lock::detect_branch_lock_collisions()` now detects same-branch/same-scope and nested-module collisions before parallel lanes drift into duplicate implementation
+14. Commit provenance / worktree-aware push events — **done**: lane event provenance now includes branch/worktree/superseded/canonical lineage metadata, and manifest persistence de-dupes superseded commit events before downstream consumers render them
 
 ## Suggested Session Split
 

USAGE.md

@@ -1,6 +1,20 @@
 # Claw Code Usage
 
-This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
+This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. If you are brand new, make the doctor health check your first run: start `claw`, then run `/doctor`.
+
+## Quick-start health check
+
+Run this before prompts, sessions, or automation:
+
+```bash
+cd rust
+cargo build --workspace
+./target/debug/claw
+# first command inside the REPL
+/doctor
+```
+
+`/doctor` is the built-in setup and preflight diagnostic. Once you have a saved session, you can rerun it with `./target/debug/claw --resume latest /doctor`.
 
 ## Prerequisites
 
@@ -10,17 +24,25 @@ This guide covers the current Rust workspace under `rust/` and the `claw` CLI bi
   - `claw login` for OAuth-based auth
 - Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service
 
-## Build the workspace
+## Install / build the workspace
 
 ```bash
 cd rust
 cargo build --workspace
 ```
 
-The CLI binary is available at `rust/target/debug/claw` after a debug build.
+The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step.
 
 ## Quick start
 
+### First-run doctor check
+
+```bash
+cd rust
+./target/debug/claw
+/doctor
+```
+
 ### Interactive REPL
 
 ```bash

docs/container.md

@@ -0,0 +1,132 @@
+# Container-first claw-code workflows
+
+This repo already had **container detection** in the Rust runtime before this document was added:
+
+- `rust/crates/runtime/src/sandbox.rs` detects Docker/Podman/container markers such as `/.dockerenv`, `/run/.containerenv`, matching env vars, and `/proc/1/cgroup` hints.
+- `rust/crates/rusty-claude-cli/src/main.rs` exposes that state through the `claw sandbox` / `cargo run -p rusty-claude-cli -- sandbox` report.
+- `.github/workflows/rust-ci.yml` runs on `ubuntu-latest`, but it does **not** define a Docker or Podman container job.
+- Before this change, the repo did **not** have a checked-in `Dockerfile`, `Containerfile`, or `.devcontainer/` config.
+
+This document adds a small checked-in `Containerfile` so Docker and Podman users have one canonical container workflow.
+
+## What the checked-in container image is for
+
+The root [`../Containerfile`](../Containerfile) gives you a reusable Rust build/test shell with the extra packages this workspace commonly needs (`git`, `pkg-config`, `libssl-dev`, certificates).
+
+It does **not** copy the repository into the image. Instead, the recommended flow is to bind-mount your checkout into `/workspace` so edits stay on the host.
+
+## Build the image
+
+From the repository root:
+
+### Docker
+
+```bash
+docker build -t claw-code-dev -f Containerfile .
+```
+
+### Podman
+
+```bash
+podman build -t claw-code-dev -f Containerfile .
+```
+
+## Run `cargo test --workspace` in the container
+
+These commands mount the repo, keep Cargo build artifacts out of the working tree, and run from the Rust workspace at `rust/`.
+
+### Docker
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/workspace \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev \
+  cargo test --workspace
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+  -v "$PWD":/workspace:Z \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev \
+  cargo test --workspace
+```
+
+If you want a fully clean rebuild, add `cargo clean &&` before `cargo test --workspace`.
+
+## Open a shell in the container
+
+### Docker
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/workspace \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+  -v "$PWD":/workspace:Z \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev
+```
+
+Inside the shell:
+
+```bash
+cargo build --workspace
+cargo test --workspace
+cargo run -p rusty-claude-cli -- --help
+cargo run -p rusty-claude-cli -- sandbox
+```
+
+The `sandbox` command is a useful sanity check: inside Docker or Podman it should report `In container true` and list the markers the runtime detected.
+
+## Bind-mount this repo and another repo at the same time
+
+If you want to run `claw` against a second checkout while keeping `claw-code` itself mounted read-write:
+
+### Docker
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/workspace \
+  -v "$HOME/src/other-repo":/repo \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev
+```
+
+### Podman
+
+```bash
+podman run --rm -it \
+  -v "$PWD":/workspace:Z \
+  -v "$HOME/src/other-repo":/repo:Z \
+  -e CARGO_TARGET_DIR=/tmp/claw-target \
+  -w /workspace/rust \
+  claw-code-dev
+```
+
+Then, for example:
+
+```bash
+cargo run -p rusty-claude-cli -- prompt "summarize /repo"
+```
+
+## Notes
+
+- Docker and Podman use the same checked-in `Containerfile`.
+- The `:Z` suffix in the Podman examples is for SELinux relabeling; keep it on Fedora/RHEL-class hosts.
+- Running with `CARGO_TARGET_DIR=/tmp/claw-target` avoids leaving container-owned `target/` artifacts in your bind-mounted checkout.
+- For non-container local development, keep using [`../USAGE.md`](../USAGE.md) and [`../rust/README.md`](../rust/README.md).

rust/.claw/sessions/session-1775386832313-0.jsonl

@@ -0,0 +1,2 @@
+{"created_at_ms":1775386832313,"session_id":"session-1775386832313-0","type":"session_meta","updated_at_ms":1775386832313,"version":1}
+{"message":{"blocks":[{"text":"status --help","type":"text"}],"role":"user"},"type":"message"}

rust/.claw/sessions/session-1775386842352-0.jsonl

@@ -0,0 +1,2 @@
+{"created_at_ms":1775386842352,"session_id":"session-1775386842352-0","type":"session_meta","updated_at_ms":1775386842352,"version":1}
+{"message":{"blocks":[{"text":"doctor --help","type":"text"}],"role":"user"},"type":"message"}

rust/.claw/sessions/session-1775386852257-0.jsonl

@@ -0,0 +1,2 @@
+{"created_at_ms":1775386852257,"session_id":"session-1775386852257-0","type":"session_meta","updated_at_ms":1775386852257,"version":1}
+{"message":{"blocks":[{"text":"doctor --help","type":"text"}],"role":"user"},"type":"message"}

rust/.claw/sessions/session-1775386853666-0.jsonl

@@ -0,0 +1,2 @@
+{"created_at_ms":1775386853666,"session_id":"session-1775386853666-0","type":"session_meta","updated_at_ms":1775386853666,"version":1}
+{"message":{"blocks":[{"text":"status --help","type":"text"}],"role":"user"},"type":"message"}

rust/README.md

@@ -79,28 +79,29 @@ Primary artifacts:
 
 | Feature | Status |
 |---------|--------|
-| Anthropic API + streaming | ✅ |
+| Anthropic / OpenAI-compatible provider flows + streaming | ✅ |
 | OAuth login/logout | ✅ |
 | Interactive REPL (rustyline) | ✅ |
 | Tool system (bash, read, write, edit, grep, glob) | ✅ |
 | Web tools (search, fetch) | ✅ |
-| Sub-agent orchestration | ✅ |
+| Sub-agent / agent surfaces | ✅ |
 | Todo tracking | ✅ |
 | Notebook editing | ✅ |
 | CLAUDE.md / project memory | ✅ |
-| Config file hierarchy (.claude.json) | ✅ |
+| Config file hierarchy (`.claw.json` + merged config sections) | ✅ |
 | Permission system | ✅ |
-| MCP server lifecycle | ✅ |
+| MCP server lifecycle + inspection | ✅ |
 | Session persistence + resume | ✅ |
-| Extended thinking (thinking blocks) | ✅ |
-| Cost tracking + usage display | ✅ |
+| Cost / usage / stats surfaces | ✅ |
 | Git integration | ✅ |
 | Markdown terminal rendering (ANSI) | ✅ |
 | Model aliases (opus/sonnet/haiku) | ✅ |
-| Slash commands (/status, /compact, /clear, etc.) | ✅ |
-| Hooks (PreToolUse/PostToolUse) | 🔧 Config only |
-| Plugin system | 📋 Planned |
-| Skills registry | 📋 Planned |
+| Direct CLI subcommands (`status`, `sandbox`, `agents`, `mcp`, `skills`, `doctor`) | ✅ |
+| Slash commands (including `/skills`, `/agents`, `/mcp`, `/doctor`, `/plugin`, `/subagent`) | ✅ |
+| Hooks (`/hooks`, config-backed lifecycle hooks) | ✅ |
+| Plugin management surfaces | ✅ |
+| Skills inventory / install surfaces | ✅ |
+| Machine-readable JSON output across core CLI surfaces | ✅ |
 
 ## Model Aliases
 
@@ -112,87 +113,96 @@ Short names resolve to the latest model versions:
 | `sonnet` | `claude-sonnet-4-6` |
 | `haiku` | `claude-haiku-4-5-20251213` |
 
-## CLI Flags
+## CLI Flags and Commands
 
-```
+Representative current surface:
+
+```text
 claw [OPTIONS] [COMMAND]
 
-Options:
-  --model MODEL                    Override the active model
-  --dangerously-skip-permissions   Skip all permission checks
-  --permission-mode MODE           Set read-only, workspace-write, or danger-full-access
-  --allowedTools TOOLS             Restrict enabled tools
-  --output-format FORMAT           Non-interactive output format (text or json)
-  --resume SESSION                 Re-open a saved session or inspect it with slash commands
-  --version, -V                    Print version and build information locally
+Flags:
+  --model MODEL
+  --output-format text|json
+  --permission-mode MODE
+  --dangerously-skip-permissions
+  --allowedTools TOOLS
+  --resume [SESSION.jsonl|session-id|latest]
+  --version, -V
 
-Commands:
-  prompt <text>      One-shot prompt (non-interactive)
-  login              Authenticate via OAuth
-  logout             Clear stored credentials
-  init               Initialize project config
-  status             Show the current workspace status snapshot
-  sandbox            Show the current sandbox isolation snapshot
-  agents             Inspect agent definitions
-  mcp                Inspect configured MCP servers
-  skills             Inspect installed skills
-  system-prompt      Render the assembled system prompt
+Top-level commands:
+  prompt <text>
+  help
+  version
+  status
+  sandbox
+  dump-manifests
+  bootstrap-plan
+  agents
+  mcp
+  skills
+  system-prompt
+  login
+  logout
+  init
 ```
 
-For the current canonical help text, run `cargo run -p rusty-claude-cli -- --help`.
+The command surface is moving quickly. For the canonical live help text, run:
+
+```bash
+cargo run -p rusty-claude-cli -- --help
+```
 
 ## Slash Commands (REPL)
 
 Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.
 
-| Command | Description |
-|---------|-------------|
-| `/help` | Show help |
-| `/status` | Show session status (model, tokens, cost) |
-| `/cost` | Show cost breakdown |
-| `/compact` | Compact conversation history |
-| `/clear` | Clear conversation |
-| `/model [name]` | Show or switch model |
-| `/permissions` | Show or switch permission mode |
-| `/config [section]` | Show config (env, hooks, model) |
-| `/memory` | Show CLAUDE.md contents |
-| `/diff` | Show git diff |
-| `/export [path]` | Export conversation |
-| `/resume [id]` | Resume a saved conversation |
-| `/session [id]` | Resume a previous session |
-| `/version` | Show version |
+The REPL now exposes a much broader surface than the original minimal shell:
 
-See [`../USAGE.md`](../USAGE.md) for examples covering interactive use, JSON automation, sessions, permissions, and the mock parity harness.
+- session / visibility: `/help`, `/status`, `/sandbox`, `/cost`, `/resume`, `/session`, `/version`, `/usage`, `/stats`
+- workspace / git: `/compact`, `/clear`, `/config`, `/memory`, `/init`, `/diff`, `/commit`, `/pr`, `/issue`, `/export`, `/hooks`, `/files`, `/branch`, `/release-notes`, `/add-dir`
+- discovery / debugging: `/mcp`, `/agents`, `/skills`, `/doctor`, `/tasks`, `/context`, `/desktop`, `/ide`
+- automation / analysis: `/review`, `/advisor`, `/insights`, `/security-review`, `/subagent`, `/team`, `/telemetry`, `/providers`, `/cron`, and more
+- plugin management: `/plugin` (with aliases `/plugins`, `/marketplace`)
+
+Notable claw-first surfaces now available directly in slash form:
+- `/skills [list|install <path>|help]`
+- `/agents [list|help]`
+- `/mcp [list|show <server>|help]`
+- `/doctor`
+- `/plugin [list|install <path>|enable <name>|disable <name>|uninstall <id>|update <id>]`
+- `/subagent [list|steer <target> <msg>|kill <id>]`
+
+See [`../USAGE.md`](../USAGE.md) for usage examples and run `cargo run -p rusty-claude-cli -- --help` for the live canonical command list.
 
 ## Workspace Layout
 
-```
+```text
 rust/
 ├── Cargo.toml              # Workspace root
 ├── Cargo.lock
 └── crates/
-    ├── api/                # Anthropic API client + SSE streaming
-    ├── commands/           # Shared slash-command registry
+    ├── api/                # Provider clients + streaming + request preflight
+    ├── commands/           # Shared slash-command registry + help rendering
     ├── compat-harness/     # TS manifest extraction harness
     ├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
-    ├── plugins/            # Plugin registry and hook wiring primitives
-    ├── runtime/            # Session, config, permissions, MCP, prompts
+    ├── plugins/            # Plugin metadata, manager, install/enable/disable surfaces
+    ├── runtime/            # Session, config, permissions, MCP, prompts, auth/runtime loop
     ├── rusty-claude-cli/   # Main CLI binary (`claw`)
     ├── telemetry/          # Session tracing and usage telemetry types
-    └── tools/              # Built-in tool implementations
+    └── tools/              # Built-in tools, skill resolution, tool search, agent runtime surfaces
 ```
 
 ### Crate Responsibilities
 
-- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer)
-- **commands** — Slash command definitions and help text generation
-- **compat-harness** — Extracts tool/prompt manifests from upstream TS source
-- **mock-anthropic-service** — Deterministic `/v1/messages` mock for CLI parity tests and local harness runs
-- **plugins** — Plugin metadata, registries, and hook integration surfaces
-- **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking
-- **rusty-claude-cli** — REPL, one-shot prompt, streaming display, tool call rendering, CLI argument parsing
-- **telemetry** — Session trace events and supporting telemetry payloads
-- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
+- **api** — provider clients, SSE streaming, request/response types, auth (API key + OAuth bearer), request-size/context-window preflight
+- **commands** — slash command definitions, parsing, help text generation, JSON/text command rendering
+- **compat-harness** — extracts tool/prompt manifests from upstream TS source
+- **mock-anthropic-service** — deterministic `/v1/messages` mock for CLI parity tests and local harness runs
+- **plugins** — plugin metadata, install/enable/disable/update flows, plugin tool definitions, hook integration surfaces
+- **runtime** — `ConversationRuntime`, config loading, session persistence, permission policy, MCP client lifecycle, system prompt assembly, usage tracking
+- **rusty-claude-cli** — REPL, one-shot prompt, direct CLI subcommands, streaming display, tool call rendering, CLI argument parsing
+- **telemetry** — session trace events and supporting telemetry payloads
+- **tools** — tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, and runtime-facing tool discovery
 
 ## Stats
 

rust/TUI-ENHANCEMENT-PLAN.md

@@ -20,12 +20,14 @@ This plan covers a comprehensive analysis of the current terminal user interface
 
 ### Current TUI Components
 
+> Note: The legacy prototype files `app.rs` and `args.rs` were removed on 2026-04-05.
+> References below describe future extraction targets, not current tracked source files.
+
 | Component | File | What It Does Today | Quality |
 |---|---|---|---|
 | **Input** | `input.rs` (269 lines) | `rustyline`-based line editor with slash-command tab completion, Shift+Enter newline, history | ✅ Solid |
 | **Rendering** | `render.rs` (641 lines) | Markdown→terminal rendering (headings, lists, tables, code blocks with syntect highlighting, blockquotes), spinner widget | ✅ Good |
 | **App/REPL loop** | `main.rs` (3,159 lines) | The monolithic `LiveCli` struct: REPL loop, all slash command handlers, streaming output, tool call display, permission prompting, session management | ⚠️ Monolithic |
-| **Alt App** | `app.rs` (398 lines) | An earlier `CliApp` prototype with `ConversationClient`, stream event handling, `TerminalRenderer`, output format support | ⚠️ Appears unused/legacy |
 
 ### Key Dependencies
 
@@ -56,7 +58,7 @@ This plan covers a comprehensive analysis of the current terminal user interface
 8. **Streaming is char-by-char with artificial delay** — `stream_markdown` sleeps 8ms per whitespace-delimited chunk
 9. **No color theme customization** — hardcoded `ColorTheme::default()`
 10. **No resize handling** — no terminal size awareness for wrapping, truncation, or layout
-11. **Dual app structs** — `app.rs` has a separate `CliApp` that duplicates `LiveCli` from `main.rs`
+11. **Historical dual app split** — the repo previously carried a separate `CliApp` prototype alongside `LiveCli`; the prototype is gone, but the monolithic `main.rs` still needs extraction
 12. **No pager for long outputs** — `/status`, `/config`, `/memory` can overflow the viewport
 13. **Tool results not collapsible** — large bash outputs flood the screen
 14. **No thinking/reasoning indicator** — when the model is in "thinking" mode, no visual distinction
@@ -73,8 +75,8 @@ This plan covers a comprehensive analysis of the current terminal user interface
 | Task | Description | Effort |
 |---|---|---|
 | 0.1 | **Extract `LiveCli` into `app.rs`** — Move the entire `LiveCli` struct, its impl, and helpers (`format_*`, `render_*`, session management) out of `main.rs` into focused modules: `app.rs` (core), `format.rs` (report formatting), `session_manager.rs` (session CRUD) | M |
-| 0.2 | **Remove or merge the legacy `CliApp`** — The existing `app.rs` has an unused `CliApp` with its own `ConversationClient`-based rendering. Either delete it or merge its unique features (stream event handler pattern) into the active `LiveCli` | S |
-| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is a hand-rolled parser that duplicates the clap-based `args.rs`. Consolidate on the hand-rolled parser (it's more feature-complete) and move it to `args.rs`, or adopt clap fully | S |
+| 0.2 | **Keep the legacy `CliApp` removed** — The old `CliApp` prototype has already been deleted; if any unique ideas remain valuable (for example stream event handler patterns), reintroduce them intentionally inside the active `LiveCli` extraction rather than restoring the old file wholesale | S |
+| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is still a hand-rolled parser in `main.rs`. If parsing is extracted later, do it into a newly-introduced module intentionally rather than reviving the removed prototype `args.rs` by accident | S |
 | 0.4 | **Create a `tui/` module** — Introduce `crates/rusty-claude-cli/src/tui/mod.rs` as the namespace for all new TUI components: `status_bar.rs`, `layout.rs`, `tool_panel.rs`, etc. | S |
 
 ### Phase 1: Status Bar & Live HUD
@@ -214,7 +216,7 @@ crates/rusty-claude-cli/src/
 | Terminal compatibility issues (tmux, SSH, Windows) | Rely on crossterm's abstraction; test in degraded environments |
 | Performance regression with rich rendering | Profile before/after; keep the fast path (raw streaming) always available |
 | Scope creep into Phase 6 | Ship Phases 0–3 as a coherent release before starting Phase 6 |
-| `app.rs` vs `main.rs` confusion | Phase 0.2 explicitly resolves this by removing the legacy `CliApp` |
+| Historical `app.rs` vs `main.rs` confusion | Keep the legacy prototype removed and avoid reintroducing a second app surface accidentally during extraction |
 
 ---
 

rust/crates/api/src/error.rs

@@ -8,6 +8,13 @@ pub enum ApiError {
         provider: &'static str,
         env_vars: &'static [&'static str],
     },
+    ContextWindowExceeded {
+        model: String,
+        estimated_input_tokens: u32,
+        requested_output_tokens: u32,
+        estimated_total_tokens: u32,
+        context_window_tokens: u32,
+    },
     ExpiredOAuthToken,
     Auth(String),
     InvalidApiKeyEnv(VarError),
@@ -48,6 +55,7 @@ impl ApiError {
             Self::Api { retryable, .. } => *retryable,
             Self::RetriesExhausted { last_error, .. } => last_error.is_retryable(),
             Self::MissingCredentials { .. }
+            | Self::ContextWindowExceeded { .. }
             | Self::ExpiredOAuthToken
             | Self::Auth(_)
             | Self::InvalidApiKeyEnv(_)
@@ -67,6 +75,16 @@ impl Display for ApiError {
                 "missing {provider} credentials; export {} before calling the {provider} API",
                 env_vars.join(" or ")
             ),
+            Self::ContextWindowExceeded {
+                model,
+                estimated_input_tokens,
+                requested_output_tokens,
+                estimated_total_tokens,
+                context_window_tokens,
+            } => write!(
+                f,
+                "context_window_blocked for {model}: estimated input {estimated_input_tokens} + requested output {requested_output_tokens} = {estimated_total_tokens} tokens exceeds the {context_window_tokens}-token context window; compact the session or reduce request size before retrying"
+            ),
             Self::ExpiredOAuthToken => {
                 write!(
                     f,

rust/crates/api/src/providers/anthropic.rs

@@ -14,7 +14,7 @@ use telemetry::{AnalyticsEvent, AnthropicRequestProfile, ClientIdentity, Session
 use crate::error::ApiError;
 use crate::prompt_cache::{PromptCache, PromptCacheRecord, PromptCacheStats};
 
-use super::{Provider, ProviderFuture};
+use super::{preflight_message_request, Provider, ProviderFuture};
 use crate::sse::SseParser;
 use crate::types::{MessageDeltaEvent, MessageRequest, MessageResponse, StreamEvent, Usage};
 
@@ -294,6 +294,8 @@ impl AnthropicClient {
             }
         }
 
+        preflight_message_request(&request)?;
+
         let response = self.send_with_retry(&request).await?;
         let request_id = request_id_from_headers(response.headers());
         let mut response = response
@@ -337,6 +339,7 @@ impl AnthropicClient {
         &self,
         request: &MessageRequest,
     ) -> Result<MessageStream, ApiError> {
+        preflight_message_request(request)?;
         let response = self
             .send_with_retry(&request.clone().with_streaming())
             .await?;

rust/crates/api/src/providers/mod.rs

@@ -1,6 +1,9 @@
+#![allow(clippy::cast_possible_truncation)]
 use std::future::Future;
 use std::pin::Pin;
 
+use serde::Serialize;
+
 use crate::error::ApiError;
 use crate::types::{MessageRequest, MessageResponse};
 
@@ -40,6 +43,12 @@ pub struct ProviderMetadata {
     pub default_base_url: &'static str,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ModelTokenLimit {
+    pub max_output_tokens: u32,
+    pub context_window_tokens: u32,
+}
+
 const MODEL_REGISTRY: &[(&str, ProviderMetadata)] = &[
     (
         "opus",
@@ -182,17 +191,86 @@ pub fn detect_provider_kind(model: &str) -> ProviderKind {
 
 #[must_use]
 pub fn max_tokens_for_model(model: &str) -> u32 {
+    model_token_limit(model).map_or_else(
+        || {
+            let canonical = resolve_model_alias(model);
+            if canonical.contains("opus") {
+                32_000
+            } else {
+                64_000
+            }
+        },
+        |limit| limit.max_output_tokens,
+    )
+}
+
+#[must_use]
+pub fn model_token_limit(model: &str) -> Option<ModelTokenLimit> {
     let canonical = resolve_model_alias(model);
-    if canonical.contains("opus") {
-        32_000
-    } else {
-        64_000
+    match canonical.as_str() {
+        "claude-opus-4-6" => Some(ModelTokenLimit {
+            max_output_tokens: 32_000,
+            context_window_tokens: 200_000,
+        }),
+        "claude-sonnet-4-6" | "claude-haiku-4-5-20251213" => Some(ModelTokenLimit {
+            max_output_tokens: 64_000,
+            context_window_tokens: 200_000,
+        }),
+        "grok-3" | "grok-3-mini" => Some(ModelTokenLimit {
+            max_output_tokens: 64_000,
+            context_window_tokens: 131_072,
+        }),
+        _ => None,
     }
 }
 
+pub fn preflight_message_request(request: &MessageRequest) -> Result<(), ApiError> {
+    let Some(limit) = model_token_limit(&request.model) else {
+        return Ok(());
+    };
+
+    let estimated_input_tokens = estimate_message_request_input_tokens(request);
+    let estimated_total_tokens = estimated_input_tokens.saturating_add(request.max_tokens);
+    if estimated_total_tokens > limit.context_window_tokens {
+        return Err(ApiError::ContextWindowExceeded {
+            model: resolve_model_alias(&request.model),
+            estimated_input_tokens,
+            requested_output_tokens: request.max_tokens,
+            estimated_total_tokens,
+            context_window_tokens: limit.context_window_tokens,
+        });
+    }
+
+    Ok(())
+}
+
+fn estimate_message_request_input_tokens(request: &MessageRequest) -> u32 {
+    let mut estimate = estimate_serialized_tokens(&request.messages);
+    estimate = estimate.saturating_add(estimate_serialized_tokens(&request.system));
+    estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tools));
+    estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tool_choice));
+    estimate
+}
+
+fn estimate_serialized_tokens<T: Serialize>(value: &T) -> u32 {
+    serde_json::to_vec(value)
+        .ok()
+        .map_or(0, |bytes| (bytes.len() / 4 + 1) as u32)
+}
+
 #[cfg(test)]
 mod tests {
-    use super::{detect_provider_kind, max_tokens_for_model, resolve_model_alias, ProviderKind};
+    use serde_json::json;
+
+    use crate::error::ApiError;
+    use crate::types::{
+        InputContentBlock, InputMessage, MessageRequest, ToolChoice, ToolDefinition,
+    };
+
+    use super::{
+        detect_provider_kind, max_tokens_for_model, model_token_limit, preflight_message_request,
+        resolve_model_alias, ProviderKind,
+    };
 
     #[test]
     fn resolves_grok_aliases() {
@@ -215,4 +293,86 @@ mod tests {
         assert_eq!(max_tokens_for_model("opus"), 32_000);
         assert_eq!(max_tokens_for_model("grok-3"), 64_000);
     }
+
+    #[test]
+    fn returns_context_window_metadata_for_supported_models() {
+        assert_eq!(
+            model_token_limit("claude-sonnet-4-6")
+                .expect("claude-sonnet-4-6 should be registered")
+                .context_window_tokens,
+            200_000
+        );
+        assert_eq!(
+            model_token_limit("grok-mini")
+                .expect("grok-mini should resolve to a registered model")
+                .context_window_tokens,
+            131_072
+        );
+    }
+
+    #[test]
+    fn preflight_blocks_requests_that_exceed_the_model_context_window() {
+        let request = MessageRequest {
+            model: "claude-sonnet-4-6".to_string(),
+            max_tokens: 64_000,
+            messages: vec![InputMessage {
+                role: "user".to_string(),
+                content: vec![InputContentBlock::Text {
+                    text: "x".repeat(600_000),
+                }],
+            }],
+            system: Some("Keep the answer short.".to_string()),
+            tools: Some(vec![ToolDefinition {
+                name: "weather".to_string(),
+                description: Some("Fetches weather".to_string()),
+                input_schema: json!({
+                    "type": "object",
+                    "properties": { "city": { "type": "string" } },
+                }),
+            }]),
+            tool_choice: Some(ToolChoice::Auto),
+            stream: true,
+        };
+
+        let error = preflight_message_request(&request)
+            .expect_err("oversized request should be rejected before the provider call");
+
+        match error {
+            ApiError::ContextWindowExceeded {
+                model,
+                estimated_input_tokens,
+                requested_output_tokens,
+                estimated_total_tokens,
+                context_window_tokens,
+            } => {
+                assert_eq!(model, "claude-sonnet-4-6");
+                assert!(estimated_input_tokens > 136_000);
+                assert_eq!(requested_output_tokens, 64_000);
+                assert!(estimated_total_tokens > context_window_tokens);
+                assert_eq!(context_window_tokens, 200_000);
+            }
+            other => panic!("expected context-window preflight failure, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn preflight_skips_unknown_models() {
+        let request = MessageRequest {
+            model: "unknown-model".to_string(),
+            max_tokens: 64_000,
+            messages: vec![InputMessage {
+                role: "user".to_string(),
+                content: vec![InputContentBlock::Text {
+                    text: "x".repeat(600_000),
+                }],
+            }],
+            system: None,
+            tools: None,
+            tool_choice: None,
+            stream: false,
+        };
+
+        preflight_message_request(&request)
+            .expect("models without context metadata should skip the guarded preflight");
+    }
 }

rust/crates/api/src/providers/openai_compat.rs

@@ -12,7 +12,7 @@ use crate::types::{
     ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
 };
 
-use super::{Provider, ProviderFuture};
+use super::{preflight_message_request, Provider, ProviderFuture};
 
 pub const DEFAULT_XAI_BASE_URL: &str = "https://api.x.ai/v1";
 pub const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
@@ -128,6 +128,7 @@ impl OpenAiCompatClient {
             stream: false,
             ..request.clone()
         };
+        preflight_message_request(&request)?;
         let response = self.send_with_retry(&request).await?;
         let request_id = request_id_from_headers(response.headers());
         let payload = response.json::<ChatCompletionResponse>().await?;
@@ -142,6 +143,7 @@ impl OpenAiCompatClient {
         &self,
         request: &MessageRequest,
     ) -> Result<MessageStream, ApiError> {
+        preflight_message_request(request)?;
         let response = self
             .send_with_retry(&request.clone().with_streaming())
             .await?;

rust/crates/api/tests/client_integration.rs

@@ -103,6 +103,41 @@ async fn send_message_posts_json_and_parses_response() {
     );
 }
 
+#[tokio::test]
+async fn send_message_blocks_oversized_requests_before_the_http_call() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response("200 OK", "application/json", "{}")],
+    )
+    .await;
+
+    let client = AnthropicClient::new("test-key").with_base_url(server.base_url());
+    let error = client
+        .send_message(&MessageRequest {
+            model: "claude-sonnet-4-6".to_string(),
+            max_tokens: 64_000,
+            messages: vec![InputMessage {
+                role: "user".to_string(),
+                content: vec![InputContentBlock::Text {
+                    text: "x".repeat(600_000),
+                }],
+            }],
+            system: Some("Keep the answer short.".to_string()),
+            tools: None,
+            tool_choice: None,
+            stream: false,
+        })
+        .await
+        .expect_err("oversized request should fail local context-window preflight");
+
+    assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
+    assert!(
+        state.lock().await.is_empty(),
+        "preflight failure should avoid any upstream HTTP request"
+    );
+}
+
 #[tokio::test]
 async fn send_message_applies_request_profile_and_records_telemetry() {
     let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));

rust/crates/api/tests/openai_compat_integration.rs

@@ -4,10 +4,10 @@ use std::sync::Arc;
 use std::sync::{Mutex as StdMutex, OnceLock};
 
 use api::{
-    ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
-    InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest, OpenAiCompatClient,
-    OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent, ToolChoice,
-    ToolDefinition,
+    ApiError, ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent,
+    ContentBlockStopEvent, InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest,
+    OpenAiCompatClient, OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent,
+    ToolChoice, ToolDefinition,
 };
 use serde_json::json;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
@@ -63,6 +63,42 @@ async fn send_message_uses_openai_compatible_endpoint_and_auth() {
     assert_eq!(body["tools"][0]["type"], json!("function"));
 }
 
+#[tokio::test]
+async fn send_message_blocks_oversized_xai_requests_before_the_http_call() {
+    let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
+    let server = spawn_server(
+        state.clone(),
+        vec![http_response("200 OK", "application/json", "{}")],
+    )
+    .await;
+
+    let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
+        .with_base_url(server.base_url());
+    let error = client
+        .send_message(&MessageRequest {
+            model: "grok-3".to_string(),
+            max_tokens: 64_000,
+            messages: vec![InputMessage {
+                role: "user".to_string(),
+                content: vec![InputContentBlock::Text {
+                    text: "x".repeat(300_000),
+                }],
+            }],
+            system: Some("Keep the answer short.".to_string()),
+            tools: None,
+            tool_choice: None,
+            stream: false,
+        })
+        .await
+        .expect_err("oversized request should fail local context-window preflight");
+
+    assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
+    assert!(
+        state.lock().await.is_empty(),
+        "preflight failure should avoid any upstream HTTP request"
+    );
+}
+
 #[tokio::test]
 async fn send_message_accepts_full_chat_completions_endpoint_override() {
     let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));

rust/crates/commands/src/lib.rs

@@ -9,6 +9,7 @@ use runtime::{
     compact_session, CompactionConfig, ConfigLoader, ConfigSource, McpOAuthConfig, McpServerConfig,
     ScopedMcpServerConfig, Session,
 };
+use serde_json::{json, Value};
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CommandManifestEntry {
@@ -1954,25 +1955,49 @@ pub struct PluginsCommandResult {
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 enum DefinitionSource {
+    ProjectClaw,
     ProjectCodex,
     ProjectClaude,
+    UserClawConfigHome,
     UserCodexHome,
+    UserClaw,
     UserCodex,
     UserClaude,
 }
 
-impl DefinitionSource {
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum DefinitionScope {
+    Project,
+    UserConfigHome,
+    UserHome,
+}
+
+impl DefinitionScope {
     fn label(self) -> &'static str {
         match self {
-            Self::ProjectCodex => "Project (.codex)",
-            Self::ProjectClaude => "Project (.claude)",
-            Self::UserCodexHome => "User ($CODEX_HOME)",
-            Self::UserCodex => "User (~/.codex)",
-            Self::UserClaude => "User (~/.claude)",
+            Self::Project => "Project (.claw)",
+            Self::UserConfigHome => "User ($CLAW_CONFIG_HOME)",
+            Self::UserHome => "User (~/.claw)",
         }
     }
 }
 
+impl DefinitionSource {
+    fn report_scope(self) -> DefinitionScope {
+        match self {
+            Self::ProjectClaw | Self::ProjectCodex | Self::ProjectClaude => {
+                DefinitionScope::Project
+            }
+            Self::UserClawConfigHome | Self::UserCodexHome => DefinitionScope::UserConfigHome,
+            Self::UserClaw | Self::UserCodex | Self::UserClaude => DefinitionScope::UserHome,
+        }
+    }
+
+    fn label(self) -> &'static str {
+        self.report_scope().label()
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct AgentSummary {
     name: String,
@@ -2142,13 +2167,22 @@ pub fn handle_plugins_slash_command(
 }
 
 pub fn handle_agents_slash_command(args: Option<&str>, cwd: &Path) -> std::io::Result<String> {
+    if let Some(args) = normalize_optional_args(args) {
+        if let Some(help_path) = help_path_from_args(args) {
+            return Ok(match help_path.as_slice() {
+                [] => render_agents_usage(None),
+                _ => render_agents_usage(Some(&help_path.join(" "))),
+            });
+        }
+    }
+
     match normalize_optional_args(args) {
         None | Some("list") => {
             let roots = discover_definition_roots(cwd, "agents");
             let agents = load_agents_from_roots(&roots)?;
             Ok(render_agents_report(&agents))
         }
-        Some("-h" | "--help" | "help") => Ok(render_agents_usage(None)),
+        Some(args) if is_help_arg(args) => Ok(render_agents_usage(None)),
         Some(args) => Ok(render_agents_usage(Some(args))),
     }
 }
@@ -2161,7 +2195,25 @@ pub fn handle_mcp_slash_command(
     render_mcp_report_for(&loader, cwd, args)
 }
 
+pub fn handle_mcp_slash_command_json(
+    args: Option<&str>,
+    cwd: &Path,
+) -> Result<Value, runtime::ConfigError> {
+    let loader = ConfigLoader::default_for(cwd);
+    render_mcp_report_json_for(&loader, cwd, args)
+}
+
 pub fn handle_skills_slash_command(args: Option<&str>, cwd: &Path) -> std::io::Result<String> {
+    if let Some(args) = normalize_optional_args(args) {
+        if let Some(help_path) = help_path_from_args(args) {
+            return Ok(match help_path.as_slice() {
+                [] => render_skills_usage(None),
+                ["install", ..] => render_skills_usage(Some("install")),
+                _ => render_skills_usage(Some(&help_path.join(" "))),
+            });
+        }
+    }
+
     match normalize_optional_args(args) {
         None | Some("list") => {
             let roots = discover_skill_roots(cwd);
@@ -2177,16 +2229,57 @@ pub fn handle_skills_slash_command(args: Option<&str>, cwd: &Path) -> std::io::R
             let install = install_skill(target, cwd)?;
             Ok(render_skill_install_report(&install))
         }
-        Some("-h" | "--help" | "help") => Ok(render_skills_usage(None)),
+        Some(args) if is_help_arg(args) => Ok(render_skills_usage(None)),
         Some(args) => Ok(render_skills_usage(Some(args))),
     }
 }
 
+pub fn handle_skills_slash_command_json(args: Option<&str>, cwd: &Path) -> std::io::Result<Value> {
+    if let Some(args) = normalize_optional_args(args) {
+        if let Some(help_path) = help_path_from_args(args) {
+            return Ok(match help_path.as_slice() {
+                [] => render_skills_usage_json(None),
+                ["install", ..] => render_skills_usage_json(Some("install")),
+                _ => render_skills_usage_json(Some(&help_path.join(" "))),
+            });
+        }
+    }
+
+    match normalize_optional_args(args) {
+        None | Some("list") => {
+            let roots = discover_skill_roots(cwd);
+            let skills = load_skills_from_roots(&roots)?;
+            Ok(render_skills_report_json(&skills))
+        }
+        Some("install") => Ok(render_skills_usage_json(Some("install"))),
+        Some(args) if args.starts_with("install ") => {
+            let target = args["install ".len()..].trim();
+            if target.is_empty() {
+                return Ok(render_skills_usage_json(Some("install")));
+            }
+            let install = install_skill(target, cwd)?;
+            Ok(render_skill_install_report_json(&install))
+        }
+        Some(args) if is_help_arg(args) => Ok(render_skills_usage_json(None)),
+        Some(args) => Ok(render_skills_usage_json(Some(args))),
+    }
+}
+
 fn render_mcp_report_for(
     loader: &ConfigLoader,
     cwd: &Path,
     args: Option<&str>,
 ) -> Result<String, runtime::ConfigError> {
+    if let Some(args) = normalize_optional_args(args) {
+        if let Some(help_path) = help_path_from_args(args) {
+            return Ok(match help_path.as_slice() {
+                [] => render_mcp_usage(None),
+                ["show", ..] => render_mcp_usage(Some("show")),
+                _ => render_mcp_usage(Some(&help_path.join(" "))),
+            });
+        }
+    }
+
     match normalize_optional_args(args) {
         None | Some("list") => {
             let runtime_config = loader.load()?;
@@ -2195,7 +2288,7 @@ fn render_mcp_report_for(
                 runtime_config.mcp().servers(),
             ))
         }
-        Some("-h" | "--help" | "help") => Ok(render_mcp_usage(None)),
+        Some(args) if is_help_arg(args) => Ok(render_mcp_usage(None)),
         Some("show") => Ok(render_mcp_usage(Some("show"))),
         Some(args) if args.split_whitespace().next() == Some("show") => {
             let mut parts = args.split_whitespace();
@@ -2217,6 +2310,51 @@ fn render_mcp_report_for(
     }
 }
 
+fn render_mcp_report_json_for(
+    loader: &ConfigLoader,
+    cwd: &Path,
+    args: Option<&str>,
+) -> Result<Value, runtime::ConfigError> {
+    if let Some(args) = normalize_optional_args(args) {
+        if let Some(help_path) = help_path_from_args(args) {
+            return Ok(match help_path.as_slice() {
+                [] => render_mcp_usage_json(None),
+                ["show", ..] => render_mcp_usage_json(Some("show")),
+                _ => render_mcp_usage_json(Some(&help_path.join(" "))),
+            });
+        }
+    }
+
+    match normalize_optional_args(args) {
+        None | Some("list") => {
+            let runtime_config = loader.load()?;
+            Ok(render_mcp_summary_report_json(
+                cwd,
+                runtime_config.mcp().servers(),
+            ))
+        }
+        Some(args) if is_help_arg(args) => Ok(render_mcp_usage_json(None)),
+        Some("show") => Ok(render_mcp_usage_json(Some("show"))),
+        Some(args) if args.split_whitespace().next() == Some("show") => {
+            let mut parts = args.split_whitespace();
+            let _ = parts.next();
+            let Some(server_name) = parts.next() else {
+                return Ok(render_mcp_usage_json(Some("show")));
+            };
+            if parts.next().is_some() {
+                return Ok(render_mcp_usage_json(Some(args)));
+            }
+            let runtime_config = loader.load()?;
+            Ok(render_mcp_server_report_json(
+                cwd,
+                server_name,
+                runtime_config.mcp().get(server_name),
+            ))
+        }
+        Some(args) => Ok(render_mcp_usage_json(Some(args))),
+    }
+}
+
 #[must_use]
 pub fn render_plugins_report(plugins: &[PluginSummary]) -> String {
     let mut lines = vec!["Plugins".to_string()];
@@ -2273,6 +2411,11 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
     let mut roots = Vec::new();
 
     for ancestor in cwd.ancestors() {
+        push_unique_root(
+            &mut roots,
+            DefinitionSource::ProjectClaw,
+            ancestor.join(".claw").join(leaf),
+        );
         push_unique_root(
             &mut roots,
             DefinitionSource::ProjectCodex,
@@ -2285,6 +2428,14 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
         );
     }
 
+    if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+        push_unique_root(
+            &mut roots,
+            DefinitionSource::UserClawConfigHome,
+            PathBuf::from(claw_config_home).join(leaf),
+        );
+    }
+
     if let Ok(codex_home) = env::var("CODEX_HOME") {
         push_unique_root(
             &mut roots,
@@ -2295,6 +2446,11 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
 
     if let Some(home) = env::var_os("HOME") {
         let home = PathBuf::from(home);
+        push_unique_root(
+            &mut roots,
+            DefinitionSource::UserClaw,
+            home.join(".claw").join(leaf),
+        );
         push_unique_root(
             &mut roots,
             DefinitionSource::UserCodex,
@@ -2310,10 +2466,17 @@ fn discover_definition_roots(cwd: &Path, leaf: &str) -> Vec<(DefinitionSource, P
     roots
 }
 
+#[allow(clippy::too_many_lines)]
 fn discover_skill_roots(cwd: &Path) -> Vec<SkillRoot> {
     let mut roots = Vec::new();
 
     for ancestor in cwd.ancestors() {
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::ProjectClaw,
+            ancestor.join(".claw").join("skills"),
+            SkillOrigin::SkillsDir,
+        );
         push_unique_skill_root(
             &mut roots,
             DefinitionSource::ProjectCodex,
@@ -2326,6 +2489,12 @@ fn discover_skill_roots(cwd: &Path) -> Vec<SkillRoot> {
             ancestor.join(".claude").join("skills"),
             SkillOrigin::SkillsDir,
         );
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::ProjectClaw,
+            ancestor.join(".claw").join("commands"),
+            SkillOrigin::LegacyCommandsDir,
+        );
         push_unique_skill_root(
             &mut roots,
             DefinitionSource::ProjectCodex,
@@ -2340,6 +2509,22 @@ fn discover_skill_roots(cwd: &Path) -> Vec<SkillRoot> {
         );
     }
 
+    if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+        let claw_config_home = PathBuf::from(claw_config_home);
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::UserClawConfigHome,
+            claw_config_home.join("skills"),
+            SkillOrigin::SkillsDir,
+        );
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::UserClawConfigHome,
+            claw_config_home.join("commands"),
+            SkillOrigin::LegacyCommandsDir,
+        );
+    }
+
     if let Ok(codex_home) = env::var("CODEX_HOME") {
         let codex_home = PathBuf::from(codex_home);
         push_unique_skill_root(
@@ -2358,6 +2543,18 @@ fn discover_skill_roots(cwd: &Path) -> Vec<SkillRoot> {
 
     if let Some(home) = env::var_os("HOME") {
         let home = PathBuf::from(home);
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::UserClaw,
+            home.join(".claw").join("skills"),
+            SkillOrigin::SkillsDir,
+        );
+        push_unique_skill_root(
+            &mut roots,
+            DefinitionSource::UserClaw,
+            home.join(".claw").join("commands"),
+            SkillOrigin::LegacyCommandsDir,
+        );
         push_unique_skill_root(
             &mut roots,
             DefinitionSource::UserCodex,
@@ -2438,15 +2635,18 @@ fn install_skill_into(
 }
 
 fn default_skill_install_root() -> std::io::Result<PathBuf> {
+    if let Ok(claw_config_home) = env::var("CLAW_CONFIG_HOME") {
+        return Ok(PathBuf::from(claw_config_home).join("skills"));
+    }
     if let Ok(codex_home) = env::var("CODEX_HOME") {
         return Ok(PathBuf::from(codex_home).join("skills"));
     }
     if let Some(home) = env::var_os("HOME") {
-        return Ok(PathBuf::from(home).join(".codex").join("skills"));
+        return Ok(PathBuf::from(home).join(".claw").join("skills"));
     }
     Err(std::io::Error::new(
         std::io::ErrorKind::NotFound,
-        "unable to resolve a skills install root; set CODEX_HOME or HOME",
+        "unable to resolve a skills install root; set CLAW_CONFIG_HOME or HOME",
     ))
 }
 
@@ -2812,22 +3012,20 @@ fn render_agents_report(agents: &[AgentSummary]) -> String {
         String::new(),
     ];
 
-    for source in [
-        DefinitionSource::ProjectCodex,
-        DefinitionSource::ProjectClaude,
-        DefinitionSource::UserCodexHome,
-        DefinitionSource::UserCodex,
-        DefinitionSource::UserClaude,
+    for scope in [
+        DefinitionScope::Project,
+        DefinitionScope::UserConfigHome,
+        DefinitionScope::UserHome,
     ] {
         let group = agents
             .iter()
-            .filter(|agent| agent.source == source)
+            .filter(|agent| agent.source.report_scope() == scope)
             .collect::<Vec<_>>();
         if group.is_empty() {
             continue;
         }
 
-        lines.push(format!("{}:", source.label()));
+        lines.push(format!("{}:", scope.label()));
         for agent in group {
             let detail = agent_detail(agent);
             match agent.shadowed_by {
@@ -2870,22 +3068,20 @@ fn render_skills_report(skills: &[SkillSummary]) -> String {
         String::new(),
     ];
 
-    for source in [
-        DefinitionSource::ProjectCodex,
-        DefinitionSource::ProjectClaude,
-        DefinitionSource::UserCodexHome,
-        DefinitionSource::UserCodex,
-        DefinitionSource::UserClaude,
+    for scope in [
+        DefinitionScope::Project,
+        DefinitionScope::UserConfigHome,
+        DefinitionScope::UserHome,
     ] {
         let group = skills
             .iter()
-            .filter(|skill| skill.source == source)
+            .filter(|skill| skill.source.report_scope() == scope)
             .collect::<Vec<_>>();
         if group.is_empty() {
             continue;
         }
 
-        lines.push(format!("{}:", source.label()));
+        lines.push(format!("{}:", scope.label()));
         for skill in group {
             let mut parts = vec![skill.name.clone()];
             if let Some(description) = &skill.description {
@@ -2906,6 +3102,23 @@ fn render_skills_report(skills: &[SkillSummary]) -> String {
     lines.join("\n").trim_end().to_string()
 }
 
+fn render_skills_report_json(skills: &[SkillSummary]) -> Value {
+    let active = skills
+        .iter()
+        .filter(|skill| skill.shadowed_by.is_none())
+        .count();
+    json!({
+        "kind": "skills",
+        "action": "list",
+        "summary": {
+            "total": skills.len(),
+            "active": active,
+            "shadowed": skills.len().saturating_sub(active),
+        },
+        "skills": skills.iter().map(skill_summary_json).collect::<Vec<_>>(),
+    })
+}
+
 fn render_skill_install_report(skill: &InstalledSkill) -> String {
     let mut lines = vec![
         "Skills".to_string(),
@@ -2927,6 +3140,20 @@ fn render_skill_install_report(skill: &InstalledSkill) -> String {
     lines.join("\n")
 }
 
+fn render_skill_install_report_json(skill: &InstalledSkill) -> Value {
+    json!({
+        "kind": "skills",
+        "action": "install",
+        "result": "installed",
+        "invocation_name": &skill.invocation_name,
+        "invoke_as": format!("${}", skill.invocation_name),
+        "display_name": &skill.display_name,
+        "source": skill.source.display().to_string(),
+        "registry_root": skill.registry_root.display().to_string(),
+        "installed_path": skill.installed_path.display().to_string(),
+    })
+}
+
 fn render_mcp_summary_report(
     cwd: &Path,
     servers: &BTreeMap<String, ScopedMcpServerConfig>,
@@ -2954,6 +3181,22 @@ fn render_mcp_summary_report(
     lines.join("\n")
 }
 
+fn render_mcp_summary_report_json(
+    cwd: &Path,
+    servers: &BTreeMap<String, ScopedMcpServerConfig>,
+) -> Value {
+    json!({
+        "kind": "mcp",
+        "action": "list",
+        "working_directory": cwd.display().to_string(),
+        "configured_servers": servers.len(),
+        "servers": servers
+            .iter()
+            .map(|(name, server)| mcp_server_json(name, server))
+            .collect::<Vec<_>>(),
+    })
+}
+
 fn render_mcp_server_report(
     cwd: &Path,
     server_name: &str,
@@ -3032,16 +3275,51 @@ fn render_mcp_server_report(
 
     lines.join("\n")
 }
+
+fn render_mcp_server_report_json(
+    cwd: &Path,
+    server_name: &str,
+    server: Option<&ScopedMcpServerConfig>,
+) -> Value {
+    match server {
+        Some(server) => json!({
+            "kind": "mcp",
+            "action": "show",
+            "working_directory": cwd.display().to_string(),
+            "found": true,
+            "server": mcp_server_json(server_name, server),
+        }),
+        None => json!({
+            "kind": "mcp",
+            "action": "show",
+            "working_directory": cwd.display().to_string(),
+            "found": false,
+            "server_name": server_name,
+            "message": format!("server `{server_name}` is not configured"),
+        }),
+    }
+}
+
 fn normalize_optional_args(args: Option<&str>) -> Option<&str> {
     args.map(str::trim).filter(|value| !value.is_empty())
 }
 
+fn is_help_arg(arg: &str) -> bool {
+    matches!(arg, "help" | "-h" | "--help")
+}
+
+fn help_path_from_args(args: &str) -> Option<Vec<&str>> {
+    let parts = args.split_whitespace().collect::<Vec<_>>();
+    let help_index = parts.iter().position(|part| is_help_arg(part))?;
+    Some(parts[..help_index].to_vec())
+}
+
 fn render_agents_usage(unexpected: Option<&str>) -> String {
     let mut lines = vec![
         "Agents".to_string(),
         "  Usage            /agents [list|help]".to_string(),
         "  Direct CLI       claw agents".to_string(),
-        "  Sources          .codex/agents, .claude/agents, $CODEX_HOME/agents".to_string(),
+        "  Sources          .claw/agents, ~/.claw/agents, $CLAW_CONFIG_HOME/agents".to_string(),
     ];
     if let Some(args) = unexpected {
         lines.push(format!("  Unexpected       {args}"));
@@ -3054,8 +3332,8 @@ fn render_skills_usage(unexpected: Option<&str>) -> String {
         "Skills".to_string(),
         "  Usage            /skills [list|install <path>|help]".to_string(),
         "  Direct CLI       claw skills [list|install <path>|help]".to_string(),
-        "  Install root     $CODEX_HOME/skills or ~/.codex/skills".to_string(),
-        "  Sources          .codex/skills, .claude/skills, legacy /commands".to_string(),
+        "  Install root     $CLAW_CONFIG_HOME/skills or ~/.claw/skills".to_string(),
+        "  Sources          .claw/skills, ~/.claw/skills, legacy /commands".to_string(),
     ];
     if let Some(args) = unexpected {
         lines.push(format!("  Unexpected       {args}"));
@@ -3063,6 +3341,20 @@ fn render_skills_usage(unexpected: Option<&str>) -> String {
     lines.join("\n")
 }
 
+fn render_skills_usage_json(unexpected: Option<&str>) -> Value {
+    json!({
+        "kind": "skills",
+        "action": "help",
+        "usage": {
+            "slash_command": "/skills [list|install <path>|help]",
+            "direct_cli": "claw skills [list|install <path>|help]",
+            "install_root": "$CLAW_CONFIG_HOME/skills or ~/.claw/skills",
+            "sources": [".claw/skills", "legacy /commands", "legacy fallback dirs still load automatically"],
+        },
+        "unexpected": unexpected,
+    })
+}
+
 fn render_mcp_usage(unexpected: Option<&str>) -> String {
     let mut lines = vec![
         "MCP".to_string(),
@@ -3076,6 +3368,19 @@ fn render_mcp_usage(unexpected: Option<&str>) -> String {
     lines.join("\n")
 }
 
+fn render_mcp_usage_json(unexpected: Option<&str>) -> Value {
+    json!({
+        "kind": "mcp",
+        "action": "help",
+        "usage": {
+            "slash_command": "/mcp [list|show <server>|help]",
+            "direct_cli": "claw mcp [list|show <server>|help]",
+            "sources": [".claw/settings.json", ".claw/settings.local.json"],
+        },
+        "unexpected": unexpected,
+    })
+}
+
 fn config_source_label(source: ConfigSource) -> &'static str {
     match source {
         ConfigSource::User => "user",
@@ -3152,6 +3457,126 @@ fn format_mcp_oauth(oauth: Option<&McpOAuthConfig>) -> String {
     }
 }
 
+fn definition_source_id(source: DefinitionSource) -> &'static str {
+    match source {
+        DefinitionSource::ProjectClaw
+        | DefinitionSource::ProjectCodex
+        | DefinitionSource::ProjectClaude => "project_claw",
+        DefinitionSource::UserClawConfigHome | DefinitionSource::UserCodexHome => {
+            "user_claw_config_home"
+        }
+        DefinitionSource::UserClaw | DefinitionSource::UserCodex | DefinitionSource::UserClaude => {
+            "user_claw"
+        }
+    }
+}
+
+fn definition_source_json(source: DefinitionSource) -> Value {
+    json!({
+        "id": definition_source_id(source),
+        "label": source.label(),
+    })
+}
+
+fn skill_origin_id(origin: SkillOrigin) -> &'static str {
+    match origin {
+        SkillOrigin::SkillsDir => "skills_dir",
+        SkillOrigin::LegacyCommandsDir => "legacy_commands_dir",
+    }
+}
+
+fn skill_origin_json(origin: SkillOrigin) -> Value {
+    json!({
+        "id": skill_origin_id(origin),
+        "detail_label": origin.detail_label(),
+    })
+}
+
+fn skill_summary_json(skill: &SkillSummary) -> Value {
+    json!({
+        "name": &skill.name,
+        "description": &skill.description,
+        "source": definition_source_json(skill.source),
+        "origin": skill_origin_json(skill.origin),
+        "active": skill.shadowed_by.is_none(),
+        "shadowed_by": skill.shadowed_by.map(definition_source_json),
+    })
+}
+
+fn config_source_id(source: ConfigSource) -> &'static str {
+    match source {
+        ConfigSource::User => "user",
+        ConfigSource::Project => "project",
+        ConfigSource::Local => "local",
+    }
+}
+
+fn config_source_json(source: ConfigSource) -> Value {
+    json!({
+        "id": config_source_id(source),
+        "label": config_source_label(source),
+    })
+}
+
+fn mcp_transport_json(config: &McpServerConfig) -> Value {
+    let label = mcp_transport_label(config);
+    json!({
+        "id": label,
+        "label": label,
+    })
+}
+
+fn mcp_oauth_json(oauth: Option<&McpOAuthConfig>) -> Value {
+    let Some(oauth) = oauth else {
+        return Value::Null;
+    };
+    json!({
+        "client_id": &oauth.client_id,
+        "callback_port": oauth.callback_port,
+        "auth_server_metadata_url": &oauth.auth_server_metadata_url,
+        "xaa": oauth.xaa,
+    })
+}
+
+fn mcp_server_details_json(config: &McpServerConfig) -> Value {
+    match config {
+        McpServerConfig::Stdio(config) => json!({
+            "command": &config.command,
+            "args": &config.args,
+            "env_keys": config.env.keys().cloned().collect::<Vec<_>>(),
+            "tool_call_timeout_ms": config.tool_call_timeout_ms,
+        }),
+        McpServerConfig::Sse(config) | McpServerConfig::Http(config) => json!({
+            "url": &config.url,
+            "header_keys": config.headers.keys().cloned().collect::<Vec<_>>(),
+            "headers_helper": &config.headers_helper,
+            "oauth": mcp_oauth_json(config.oauth.as_ref()),
+        }),
+        McpServerConfig::Ws(config) => json!({
+            "url": &config.url,
+            "header_keys": config.headers.keys().cloned().collect::<Vec<_>>(),
+            "headers_helper": &config.headers_helper,
+        }),
+        McpServerConfig::Sdk(config) => json!({
+            "name": &config.name,
+        }),
+        McpServerConfig::ManagedProxy(config) => json!({
+            "url": &config.url,
+            "id": &config.id,
+        }),
+    }
+}
+
+fn mcp_server_json(name: &str, server: &ScopedMcpServerConfig) -> Value {
+    json!({
+        "name": name,
+        "scope": config_source_json(server.scope),
+        "transport": mcp_transport_json(&server.config),
+        "summary": mcp_server_summary(&server.config),
+        "details": mcp_server_details_json(&server.config),
+    })
+}
+
 #[must_use]
 pub fn handle_slash_command(
     input: &str,
@@ -3261,8 +3686,9 @@ pub fn handle_slash_command(
 #[cfg(test)]
 mod tests {
     use super::{
-        handle_plugins_slash_command, handle_slash_command, load_agents_from_roots,
-        load_skills_from_roots, render_agents_report, render_plugins_report, render_skills_report,
+        handle_plugins_slash_command, handle_skills_slash_command_json, handle_slash_command,
+        load_agents_from_roots, load_skills_from_roots, render_agents_report,
+        render_mcp_report_json_for, render_plugins_report, render_skills_report,
         render_slash_command_help, render_slash_command_help_detail,
         resume_supported_slash_commands, slash_command_specs, suggest_slash_commands,
         validate_slash_command_input, DefinitionSource, SkillOrigin, SkillRoot, SlashCommand,
@@ -3894,7 +4320,7 @@ mod tests {
         let workspace = temp_dir("agents-workspace");
         let project_agents = workspace.join(".codex").join("agents");
         let user_home = temp_dir("agents-home");
-        let user_agents = user_home.join(".codex").join("agents");
+        let user_agents = user_home.join(".claude").join("agents");
 
         write_agent(
             &project_agents,
@@ -3927,10 +4353,10 @@ mod tests {
 
         assert!(report.contains("Agents"));
         assert!(report.contains("2 active agents"));
-        assert!(report.contains("Project (.codex):"));
+        assert!(report.contains("Project (.claw):"));
         assert!(report.contains("planner · Project planner · gpt-5.4 · medium"));
-        assert!(report.contains("User (~/.codex):"));
-        assert!(report.contains("(shadowed by Project (.codex)) planner · User planner"));
+        assert!(report.contains("User (~/.claw):"));
+        assert!(report.contains("(shadowed by Project (.claw)) planner · User planner"));
         assert!(report.contains("verifier · Verification agent · gpt-5.4-mini · high"));
 
         let _ = fs::remove_dir_all(workspace);
@@ -3972,18 +4398,72 @@ mod tests {
 
         assert!(report.contains("Skills"));
         assert!(report.contains("3 available skills"));
-        assert!(report.contains("Project (.codex):"));
+        assert!(report.contains("Project (.claw):"));
         assert!(report.contains("plan · Project planning guidance"));
-        assert!(report.contains("Project (.claude):"));
         assert!(report.contains("deploy · Legacy deployment guidance · legacy /commands"));
-        assert!(report.contains("User (~/.codex):"));
-        assert!(report.contains("(shadowed by Project (.codex)) plan · User planning guidance"));
+        assert!(report.contains("User (~/.claw):"));
+        assert!(report.contains("(shadowed by Project (.claw)) plan · User planning guidance"));
         assert!(report.contains("help · Help guidance"));
 
         let _ = fs::remove_dir_all(workspace);
         let _ = fs::remove_dir_all(user_home);
     }
 
+    #[test]
+    fn renders_skills_reports_as_json() {
+        let workspace = temp_dir("skills-json-workspace");
+        let project_skills = workspace.join(".codex").join("skills");
+        let project_commands = workspace.join(".claude").join("commands");
+        let user_home = temp_dir("skills-json-home");
+        let user_skills = user_home.join(".codex").join("skills");
+
+        write_skill(&project_skills, "plan", "Project planning guidance");
+        write_legacy_command(&project_commands, "deploy", "Legacy deployment guidance");
+        write_skill(&user_skills, "plan", "User planning guidance");
+        write_skill(&user_skills, "help", "Help guidance");
+
+        let roots = vec![
+            SkillRoot {
+                source: DefinitionSource::ProjectCodex,
+                path: project_skills,
+                origin: SkillOrigin::SkillsDir,
+            },
+            SkillRoot {
+                source: DefinitionSource::ProjectClaude,
+                path: project_commands,
+                origin: SkillOrigin::LegacyCommandsDir,
+            },
+            SkillRoot {
+                source: DefinitionSource::UserCodex,
+                path: user_skills,
+                origin: SkillOrigin::SkillsDir,
+            },
+        ];
+        let report = super::render_skills_report_json(
+            &load_skills_from_roots(&roots).expect("skills should load"),
+        );
+        assert_eq!(report["kind"], "skills");
+        assert_eq!(report["action"], "list");
+        assert_eq!(report["summary"]["active"], 3);
+        assert_eq!(report["summary"]["shadowed"], 1);
+        assert_eq!(report["skills"][0]["name"], "plan");
+        assert_eq!(report["skills"][0]["source"]["id"], "project_claw");
+        assert_eq!(report["skills"][1]["name"], "deploy");
+        assert_eq!(report["skills"][1]["origin"]["id"], "legacy_commands_dir");
+        assert_eq!(report["skills"][3]["shadowed_by"]["id"], "project_claw");
+
+        let help = handle_skills_slash_command_json(Some("help"), &workspace).expect("skills help");
+        assert_eq!(help["kind"], "skills");
+        assert_eq!(help["action"], "help");
+        assert_eq!(
+            help["usage"]["direct_cli"],
+            "claw skills [list|install <path>|help]"
+        );
+
+        let _ = fs::remove_dir_all(workspace);
+        let _ = fs::remove_dir_all(user_home);
+    }
+
     #[test]
     fn agents_and_skills_usage_support_help_and_unexpected_args() {
         let cwd = temp_dir("slash-usage");
@@ -3992,6 +4472,8 @@ mod tests {
             super::handle_agents_slash_command(Some("help"), &cwd).expect("agents help");
         assert!(agents_help.contains("Usage            /agents [list|help]"));
         assert!(agents_help.contains("Direct CLI       claw agents"));
+        assert!(agents_help
+            .contains("Sources          .claw/agents, ~/.claw/agents, $CLAW_CONFIG_HOME/agents"));
 
         let agents_unexpected =
             super::handle_agents_slash_command(Some("show planner"), &cwd).expect("agents usage");
@@ -4000,12 +4482,22 @@ mod tests {
         let skills_help =
             super::handle_skills_slash_command(Some("--help"), &cwd).expect("skills help");
         assert!(skills_help.contains("Usage            /skills [list|install <path>|help]"));
-        assert!(skills_help.contains("Install root     $CODEX_HOME/skills or ~/.codex/skills"));
+        assert!(skills_help.contains("Install root     $CLAW_CONFIG_HOME/skills or ~/.claw/skills"));
         assert!(skills_help.contains("legacy /commands"));
 
         let skills_unexpected =
             super::handle_skills_slash_command(Some("show help"), &cwd).expect("skills usage");
-        assert!(skills_unexpected.contains("Unexpected       show help"));
+        assert!(skills_unexpected.contains("Unexpected       show"));
+
+        let skills_install_help = super::handle_skills_slash_command(Some("install --help"), &cwd)
+            .expect("nested skills help");
+        assert!(skills_install_help.contains("Usage            /skills [list|install <path>|help]"));
+        assert!(skills_install_help.contains("Unexpected       install"));
+
+        let skills_unknown_help =
+            super::handle_skills_slash_command(Some("show --help"), &cwd).expect("skills help");
+        assert!(skills_unknown_help.contains("Usage            /skills [list|install <path>|help]"));
+        assert!(skills_unknown_help.contains("Unexpected       show"));
 
         let _ = fs::remove_dir_all(cwd);
     }
@@ -4022,6 +4514,16 @@ mod tests {
             super::handle_mcp_slash_command(Some("show alpha beta"), &cwd).expect("mcp usage");
         assert!(unexpected.contains("Unexpected       show alpha beta"));
 
+        let nested_help =
+            super::handle_mcp_slash_command(Some("show --help"), &cwd).expect("mcp help");
+        assert!(nested_help.contains("Usage            /mcp [list|show <server>|help]"));
+        assert!(nested_help.contains("Unexpected       show"));
+
+        let unknown_help =
+            super::handle_mcp_slash_command(Some("inspect --help"), &cwd).expect("mcp usage");
+        assert!(unknown_help.contains("Usage            /mcp [list|show <server>|help]"));
+        assert!(unknown_help.contains("Unexpected       inspect"));
+
         let _ = fs::remove_dir_all(cwd);
     }
 
@@ -4102,6 +4604,88 @@ mod tests {
         let _ = fs::remove_dir_all(config_home);
     }
 
+    #[test]
+    fn renders_mcp_reports_as_json() {
+        let workspace = temp_dir("mcp-json-workspace");
+        let config_home = temp_dir("mcp-json-home");
+        fs::create_dir_all(workspace.join(".claw")).expect("workspace config dir");
+        fs::create_dir_all(&config_home).expect("config home");
+        fs::write(
+            workspace.join(".claw").join("settings.json"),
+            r#"{
+              "mcpServers": {
+                "alpha": {
+                  "command": "uvx",
+                  "args": ["alpha-server"],
+                  "env": {"ALPHA_TOKEN": "secret"},
+                  "toolCallTimeoutMs": 1200
+                },
+                "remote": {
+                  "type": "http",
+                  "url": "https://remote.example/mcp",
+                  "headers": {"Authorization": "Bearer secret"},
+                  "headersHelper": "./bin/headers",
+                  "oauth": {
+                    "clientId": "remote-client",
+                    "callbackPort": 7878
+                  }
+                }
+              }
+            }"#,
+        )
+        .expect("write settings");
+        fs::write(
+            workspace.join(".claw").join("settings.local.json"),
+            r#"{
+              "mcpServers": {
+                "remote": {
+                  "type": "ws",
+                  "url": "wss://remote.example/mcp"
+                }
+              }
+            }"#,
+        )
+        .expect("write local settings");
+
+        let loader = ConfigLoader::new(&workspace, &config_home);
+        let list =
+            render_mcp_report_json_for(&loader, &workspace, None).expect("mcp list json render");
+        assert_eq!(list["kind"], "mcp");
+        assert_eq!(list["action"], "list");
+        assert_eq!(list["configured_servers"], 2);
+        assert_eq!(list["servers"][0]["name"], "alpha");
+        assert_eq!(list["servers"][0]["transport"]["id"], "stdio");
+        assert_eq!(list["servers"][0]["details"]["command"], "uvx");
+        assert_eq!(list["servers"][1]["name"], "remote");
+        assert_eq!(list["servers"][1]["scope"]["id"], "local");
+        assert_eq!(list["servers"][1]["transport"]["id"], "ws");
+        assert_eq!(
+            list["servers"][1]["details"]["url"],
+            "wss://remote.example/mcp"
+        );
+
+        let show = render_mcp_report_json_for(&loader, &workspace, Some("show alpha"))
+            .expect("mcp show json render");
+        assert_eq!(show["action"], "show");
+        assert_eq!(show["found"], true);
+        assert_eq!(show["server"]["name"], "alpha");
+        assert_eq!(show["server"]["details"]["env_keys"][0], "ALPHA_TOKEN");
+        assert_eq!(show["server"]["details"]["tool_call_timeout_ms"], 1200);
+
+        let missing = render_mcp_report_json_for(&loader, &workspace, Some("show missing"))
+            .expect("mcp missing json render");
+        assert_eq!(missing["found"], false);
+        assert_eq!(missing["server_name"], "missing");
+
+        let help =
+            render_mcp_report_json_for(&loader, &workspace, Some("help")).expect("mcp help json");
+        assert_eq!(help["action"], "help");
+        assert_eq!(help["usage"]["sources"][0], ".claw/settings.json");
+
+        let _ = fs::remove_dir_all(workspace);
+        let _ = fs::remove_dir_all(config_home);
+    }
+
     #[test]
     fn parses_quoted_skill_frontmatter_values() {
         let contents = "---\nname: \"hud\"\ndescription: 'Quoted description'\n---\n";
@@ -4154,7 +4738,7 @@ mod tests {
         let listed = render_skills_report(
             &load_skills_from_roots(&roots).expect("installed skills should load"),
         );
-        assert!(listed.contains("User ($CODEX_HOME):"));
+        assert!(listed.contains("User ($CLAW_CONFIG_HOME):"));
         assert!(listed.contains("help · Helpful skill"));
 
         let _ = fs::remove_dir_all(workspace);

rust/crates/runtime/src/branch_lock.rs

@@ -0,0 +1,144 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchLockIntent {
+    #[serde(rename = "laneId")]
+    pub lane_id: String,
+    pub branch: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub worktree: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub modules: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchLockCollision {
+    pub branch: String,
+    pub module: String,
+    #[serde(rename = "laneIds")]
+    pub lane_ids: Vec<String>,
+}
+
+#[must_use]
+pub fn detect_branch_lock_collisions(intents: &[BranchLockIntent]) -> Vec<BranchLockCollision> {
+    let mut collisions = Vec::new();
+
+    for (index, left) in intents.iter().enumerate() {
+        for right in &intents[index + 1..] {
+            if left.branch != right.branch {
+                continue;
+            }
+            for module in overlapping_modules(&left.modules, &right.modules) {
+                collisions.push(BranchLockCollision {
+                    branch: left.branch.clone(),
+                    module,
+                    lane_ids: vec![left.lane_id.clone(), right.lane_id.clone()],
+                });
+            }
+        }
+    }
+
+    collisions.sort_by(|a, b| {
+        a.branch
+            .cmp(&b.branch)
+            .then(a.module.cmp(&b.module))
+            .then(a.lane_ids.cmp(&b.lane_ids))
+    });
+    collisions.dedup();
+    collisions
+}
+
+fn overlapping_modules(left: &[String], right: &[String]) -> Vec<String> {
+    let mut overlaps = Vec::new();
+    for left_module in left {
+        for right_module in right {
+            if modules_overlap(left_module, right_module) {
+                overlaps.push(shared_scope(left_module, right_module));
+            }
+        }
+    }
+    overlaps.sort();
+    overlaps.dedup();
+    overlaps
+}
+
+fn modules_overlap(left: &str, right: &str) -> bool {
+    left == right
+        || left.starts_with(&format!("{right}/"))
+        || right.starts_with(&format!("{left}/"))
+}
+
+fn shared_scope(left: &str, right: &str) -> String {
+    if left.starts_with(&format!("{right}/")) || left == right {
+        right.to_string()
+    } else {
+        left.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{detect_branch_lock_collisions, BranchLockIntent};
+
+    #[test]
+    fn detects_same_branch_same_module_collisions() {
+        let collisions = detect_branch_lock_collisions(&[
+            BranchLockIntent {
+                lane_id: "lane-a".to_string(),
+                branch: "feature/lock".to_string(),
+                worktree: Some("wt-a".to_string()),
+                modules: vec!["runtime/mcp".to_string()],
+            },
+            BranchLockIntent {
+                lane_id: "lane-b".to_string(),
+                branch: "feature/lock".to_string(),
+                worktree: Some("wt-b".to_string()),
+                modules: vec!["runtime/mcp".to_string()],
+            },
+        ]);
+
+        assert_eq!(collisions.len(), 1);
+        assert_eq!(collisions[0].branch, "feature/lock");
+        assert_eq!(collisions[0].module, "runtime/mcp");
+    }
+
+    #[test]
+    fn detects_nested_module_scope_collisions() {
+        let collisions = detect_branch_lock_collisions(&[
+            BranchLockIntent {
+                lane_id: "lane-a".to_string(),
+                branch: "feature/lock".to_string(),
+                worktree: None,
+                modules: vec!["runtime".to_string()],
+            },
+            BranchLockIntent {
+                lane_id: "lane-b".to_string(),
+                branch: "feature/lock".to_string(),
+                worktree: None,
+                modules: vec!["runtime/mcp".to_string()],
+            },
+        ]);
+
+        assert_eq!(collisions[0].module, "runtime");
+    }
+
+    #[test]
+    fn ignores_different_branches() {
+        let collisions = detect_branch_lock_collisions(&[
+            BranchLockIntent {
+                lane_id: "lane-a".to_string(),
+                branch: "feature/a".to_string(),
+                worktree: None,
+                modules: vec!["runtime/mcp".to_string()],
+            },
+            BranchLockIntent {
+                lane_id: "lane-b".to_string(),
+                branch: "feature/b".to_string(),
+                worktree: None,
+                modules: vec!["runtime/mcp".to_string()],
+            },
+        ]);
+
+        assert!(collisions.is_empty());
+    }
+}

rust/crates/runtime/src/lane_events.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::similar_names)]
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
@@ -76,6 +77,20 @@ pub struct LaneEventBlocker {
     pub detail: String,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LaneCommitProvenance {
+    pub commit: String,
+    pub branch: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub worktree: Option<String>,
+    #[serde(rename = "canonicalCommit", skip_serializing_if = "Option::is_none")]
+    pub canonical_commit: Option<String>,
+    #[serde(rename = "supersededBy", skip_serializing_if = "Option::is_none")]
+    pub superseded_by: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub lineage: Vec<String>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct LaneEvent {
     pub event: LaneEventName,
@@ -114,8 +129,42 @@ impl LaneEvent {
 
     #[must_use]
     pub fn finished(emitted_at: impl Into<String>, detail: Option<String>) -> Self {
-        Self::new(LaneEventName::Finished, LaneEventStatus::Completed, emitted_at)
-            .with_optional_detail(detail)
+        Self::new(
+            LaneEventName::Finished,
+            LaneEventStatus::Completed,
+            emitted_at,
+        )
+        .with_optional_detail(detail)
+    }
+
+    #[must_use]
+    pub fn commit_created(
+        emitted_at: impl Into<String>,
+        detail: Option<String>,
+        provenance: LaneCommitProvenance,
+    ) -> Self {
+        Self::new(
+            LaneEventName::CommitCreated,
+            LaneEventStatus::Completed,
+            emitted_at,
+        )
+        .with_optional_detail(detail)
+        .with_data(serde_json::to_value(provenance).expect("commit provenance should serialize"))
+    }
+
+    #[must_use]
+    pub fn superseded(
+        emitted_at: impl Into<String>,
+        detail: Option<String>,
+        provenance: LaneCommitProvenance,
+    ) -> Self {
+        Self::new(
+            LaneEventName::Superseded,
+            LaneEventStatus::Superseded,
+            emitted_at,
+        )
+        .with_optional_detail(detail)
+        .with_data(serde_json::to_value(provenance).expect("commit provenance should serialize"))
     }
 
     #[must_use]
@@ -157,12 +206,53 @@ impl LaneEvent {
     }
 }
 
+#[must_use]
+pub fn dedupe_superseded_commit_events(events: &[LaneEvent]) -> Vec<LaneEvent> {
+    let mut keep = vec![true; events.len()];
+    let mut latest_by_key = std::collections::BTreeMap::<String, usize>::new();
+
+    for (index, event) in events.iter().enumerate() {
+        if event.event != LaneEventName::CommitCreated {
+            continue;
+        }
+        let Some(data) = event.data.as_ref() else {
+            continue;
+        };
+        let key = data
+            .get("canonicalCommit")
+            .or_else(|| data.get("commit"))
+            .and_then(serde_json::Value::as_str)
+            .map(str::to_string);
+        let superseded = data
+            .get("supersededBy")
+            .and_then(serde_json::Value::as_str)
+            .is_some();
+        if superseded {
+            keep[index] = false;
+            continue;
+        }
+        if let Some(key) = key {
+            if let Some(previous) = latest_by_key.insert(key, index) {
+                keep[previous] = false;
+            }
+        }
+    }
+
+    events
+        .iter()
+        .cloned()
+        .zip(keep)
+        .filter_map(|(event, retain)| retain.then_some(event))
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use serde_json::json;
 
     use super::{
-        LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus, LaneFailureClass,
+        dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
+        LaneEventName, LaneEventStatus, LaneFailureClass,
     };
 
     #[test]
@@ -170,10 +260,7 @@ mod tests {
         let cases = [
             (LaneEventName::Started, "lane.started"),
             (LaneEventName::Ready, "lane.ready"),
-            (
-                LaneEventName::PromptMisdelivery,
-                "lane.prompt_misdelivery",
-            ),
+            (LaneEventName::PromptMisdelivery, "lane.prompt_misdelivery"),
             (LaneEventName::Blocked, "lane.blocked"),
             (LaneEventName::Red, "lane.red"),
             (LaneEventName::Green, "lane.green"),
@@ -193,7 +280,10 @@ mod tests {
         ];
 
         for (event, expected) in cases {
-            assert_eq!(serde_json::to_value(event).expect("serialize event"), json!(expected));
+            assert_eq!(
+                serde_json::to_value(event).expect("serialize event"),
+                json!(expected)
+            );
         }
     }
 
@@ -238,4 +328,56 @@ mod tests {
         assert_eq!(failed.status, LaneEventStatus::Failed);
         assert_eq!(failed.detail.as_deref(), Some("broken server"));
     }
+
+    #[test]
+    fn commit_events_can_carry_worktree_and_supersession_metadata() {
+        let event = LaneEvent::commit_created(
+            "2026-04-04T00:00:00Z",
+            Some("commit created".to_string()),
+            LaneCommitProvenance {
+                commit: "abc123".to_string(),
+                branch: "feature/provenance".to_string(),
+                worktree: Some("wt-a".to_string()),
+                canonical_commit: Some("abc123".to_string()),
+                superseded_by: None,
+                lineage: vec!["abc123".to_string()],
+            },
+        );
+        let event_json = serde_json::to_value(&event).expect("lane event should serialize");
+        assert_eq!(event_json["event"], "lane.commit.created");
+        assert_eq!(event_json["data"]["branch"], "feature/provenance");
+        assert_eq!(event_json["data"]["worktree"], "wt-a");
+    }
+
+    #[test]
+    fn dedupes_superseded_commit_events_by_canonical_commit() {
+        let retained = dedupe_superseded_commit_events(&[
+            LaneEvent::commit_created(
+                "2026-04-04T00:00:00Z",
+                Some("old".to_string()),
+                LaneCommitProvenance {
+                    commit: "old123".to_string(),
+                    branch: "feature/provenance".to_string(),
+                    worktree: Some("wt-a".to_string()),
+                    canonical_commit: Some("canon123".to_string()),
+                    superseded_by: Some("new123".to_string()),
+                    lineage: vec!["old123".to_string(), "new123".to_string()],
+                },
+            ),
+            LaneEvent::commit_created(
+                "2026-04-04T00:00:01Z",
+                Some("new".to_string()),
+                LaneCommitProvenance {
+                    commit: "new123".to_string(),
+                    branch: "feature/provenance".to_string(),
+                    worktree: Some("wt-b".to_string()),
+                    canonical_commit: Some("canon123".to_string()),
+                    superseded_by: None,
+                    lineage: vec!["old123".to_string(), "new123".to_string()],
+                },
+            ),
+        ]);
+        assert_eq!(retained.len(), 1);
+        assert_eq!(retained[0].detail.as_deref(), Some("new"));
+    }
 }

rust/crates/runtime/src/lib.rs

@@ -7,6 +7,7 @@
 mod bash;
 pub mod bash_validation;
 mod bootstrap;
+pub mod branch_lock;
 mod compact;
 mod config;
 mod conversation;
@@ -31,19 +32,22 @@ pub mod recovery_recipes;
 mod remote;
 pub mod sandbox;
 mod session;
-pub mod session_control;
+#[cfg(test)]
+mod session_control;
 mod sse;
 pub mod stale_branch;
 pub mod summary_compression;
 pub mod task_packet;
 pub mod task_registry;
 pub mod team_cron_registry;
-pub mod trust_resolver;
+#[cfg(test)]
+mod trust_resolver;
 mod usage;
 pub mod worker_boot;
 
 pub use bash::{execute_bash, BashCommandInput, BashCommandOutput};
 pub use bootstrap::{BootstrapPhase, BootstrapPlan};
+pub use branch_lock::{detect_branch_lock_collisions, BranchLockCollision, BranchLockIntent};
 pub use compact::{
     compact_session, estimate_session_tokens, format_compact_summary,
     get_compact_continuation_message, should_compact, CompactionConfig, CompactionResult,
@@ -70,7 +74,8 @@ pub use hooks::{
     HookAbortSignal, HookEvent, HookProgressEvent, HookProgressReporter, HookRunResult, HookRunner,
 };
 pub use lane_events::{
-    LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus, LaneFailureClass,
+    dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
+    LaneEventName, LaneEventStatus, LaneFailureClass,
 };
 pub use mcp::{
     mcp_server_signature, mcp_tool_name, mcp_tool_prefix, normalize_name_for_mcp,
@@ -141,6 +146,7 @@ pub use stale_branch::{
     StaleBranchPolicy,
 };
 pub use task_packet::{validate_packet, TaskPacket, TaskPacketValidationError, ValidatedPacket};
+#[cfg(test)]
 pub use trust_resolver::{TrustConfig, TrustDecision, TrustEvent, TrustPolicy, TrustResolver};
 pub use usage::{
     format_usd, pricing_for_model, ModelPricing, TokenUsage, UsageCostEstimate, UsageTracker,

rust/crates/runtime/src/lsp_client.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::should_implement_trait, clippy::must_use_candidate)]
 //! LSP (Language Server Protocol) client registry for tool dispatch.
 
 use std::collections::HashMap;

rust/crates/runtime/src/mcp_lifecycle_hardened.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::unnested_or_patterns, clippy::map_unwrap_or)]
 use std::collections::{BTreeMap, BTreeSet};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
@@ -599,7 +600,10 @@ mod tests {
             ));
 
             match result {
-                McpPhaseResult::Failure { phase: failed_phase, error } => {
+                McpPhaseResult::Failure {
+                    phase: failed_phase,
+                    error,
+                } => {
                     assert_eq!(failed_phase, phase);
                     assert_eq!(error.phase, phase);
                     assert_eq!(

rust/crates/runtime/src/mcp_stdio.rs

@@ -360,8 +360,10 @@ impl McpServerManagerError {
     }
 
     fn recoverable(&self) -> bool {
-        !matches!(self.lifecycle_phase(), McpLifecyclePhase::InitializeHandshake)
-            && matches!(self, Self::Transport { .. } | Self::Timeout { .. })
+        !matches!(
+            self.lifecycle_phase(),
+            McpLifecyclePhase::InitializeHandshake
+        ) && matches!(self, Self::Transport { .. } | Self::Timeout { .. })
     }
 
     fn discovery_failure(&self, server_name: &str) -> McpDiscoveryFailure {
@@ -417,10 +419,9 @@ impl McpServerManagerError {
                 ("method".to_string(), (*method).to_string()),
                 ("timeout_ms".to_string(), timeout_ms.to_string()),
             ]),
-            Self::UnknownTool { qualified_name } => BTreeMap::from([(
-                "qualified_tool".to_string(),
-                qualified_name.clone(),
-            )]),
+            Self::UnknownTool { qualified_name } => {
+                BTreeMap::from([("qualified_tool".to_string(), qualified_name.clone())])
+            }
             Self::UnknownServer { server_name } => {
                 BTreeMap::from([("server".to_string(), server_name.clone())])
             }
@@ -1425,11 +1426,10 @@ mod tests {
     use crate::mcp_client::McpClientBootstrap;
 
     use super::{
-        spawn_mcp_stdio_process, JsonRpcId, JsonRpcRequest, JsonRpcResponse,
-        McpInitializeClientInfo, McpInitializeParams, McpInitializeResult, McpInitializeServerInfo,
-        McpListToolsResult, McpReadResourceParams, McpReadResourceResult, McpServerManager,
-        McpServerManagerError, McpStdioProcess, McpTool, McpToolCallParams,
-        unsupported_server_failed_server,
+        spawn_mcp_stdio_process, unsupported_server_failed_server, JsonRpcId, JsonRpcRequest,
+        JsonRpcResponse, McpInitializeClientInfo, McpInitializeParams, McpInitializeResult,
+        McpInitializeServerInfo, McpListToolsResult, McpReadResourceParams, McpReadResourceResult,
+        McpServerManager, McpServerManagerError, McpStdioProcess, McpTool, McpToolCallParams,
     };
     use crate::McpLifecyclePhase;
 
@@ -2652,8 +2652,37 @@ mod tests {
         });
     }
 
+    fn write_initialize_disconnect_script() -> PathBuf {
+        let root = temp_dir();
+        fs::create_dir_all(&root).expect("temp dir");
+        let script_path = root.join("initialize-disconnect.py");
+        let script = [
+            "#!/usr/bin/env python3",
+            "import sys",
+            "header = b''",
+            r"while not header.endswith(b'\r\n\r\n'):",
+            "    chunk = sys.stdin.buffer.read(1)",
+            "    if not chunk:",
+            "        raise SystemExit(1)",
+            "    header += chunk",
+            "length = 0",
+            r"for line in header.decode().split('\r\n'):",
+            r"    if line.lower().startswith('content-length:'):",
+            r"        length = int(line.split(':', 1)[1].strip())",
+            "if length:",
+            "    sys.stdin.buffer.read(length)",
+            "raise SystemExit(0)",
+            "",
+        ]
+        .join("\n");
+        fs::write(&script_path, script).expect("write script");
+        let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
+        permissions.set_mode(0o755);
+        fs::set_permissions(&script_path, permissions).expect("chmod");
+        script_path
+    }
+
     #[test]
-    #[ignore = "flaky: intermittent timing issues in CI, see ROADMAP P2.15"]
     fn manager_discovery_report_keeps_healthy_servers_when_one_server_fails() {
         let runtime = Builder::new_current_thread()
             .enable_all()
@@ -2663,6 +2692,7 @@ mod tests {
             let script_path = write_manager_mcp_server_script();
             let root = script_path.parent().expect("script parent");
             let alpha_log = root.join("alpha.log");
+            let broken_script_path = write_initialize_disconnect_script();
             let servers = BTreeMap::from([
                 (
                     "alpha".to_string(),
@@ -2673,8 +2703,8 @@ mod tests {
                     ScopedMcpServerConfig {
                         scope: ConfigSource::Local,
                         config: McpServerConfig::Stdio(McpStdioServerConfig {
-                            command: "python3".to_string(),
-                            args: vec!["-c".to_string(), "import sys; sys.exit(0)".to_string()],
+                            command: broken_script_path.display().to_string(),
+                            args: Vec::new(),
                             env: BTreeMap::new(),
                             tool_call_timeout_ms: None,
                         }),
@@ -2698,7 +2728,10 @@ mod tests {
             );
             assert!(!report.failed_servers[0].recoverable);
             assert_eq!(
-                report.failed_servers[0].context.get("method").map(String::as_str),
+                report.failed_servers[0]
+                    .context
+                    .get("method")
+                    .map(String::as_str),
                 Some("initialize")
             );
             assert!(report.failed_servers[0].error.contains("initialize"));
@@ -2734,6 +2767,7 @@ mod tests {
 
             manager.shutdown().await.expect("shutdown");
             cleanup_script(&script_path);
+            cleanup_script(&broken_script_path);
         });
     }
 

rust/crates/runtime/src/mcp_tool_bridge.rs

@@ -1,3 +1,11 @@
+#![allow(
+    clippy::await_holding_lock,
+    clippy::doc_markdown,
+    clippy::match_same_arms,
+    clippy::must_use_candidate,
+    clippy::uninlined_format_args,
+    clippy::unnested_or_patterns
+)]
 //! Bridge between MCP tool surface (ListMcpResources, ReadMcpResource, McpAuth, MCP)
 //! and the existing McpServerManager runtime.
 //!

rust/crates/runtime/src/permission_enforcer.rs

@@ -1,3 +1,8 @@
+#![allow(
+    clippy::match_wildcard_for_single_variants,
+    clippy::must_use_candidate,
+    clippy::uninlined_format_args
+)]
 //! Permission enforcement layer that gates tool execution based on the
 //! active `PermissionPolicy`.
 

rust/crates/runtime/src/plugin_lifecycle.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::redundant_closure_for_method_calls)]
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use serde::{Deserialize, Serialize};

rust/crates/runtime/src/recovery_recipes.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::cast_possible_truncation, clippy::uninlined_format_args)]
 //! Recovery recipes for common failure scenarios.
 //!
 //! Encodes known automatic recoveries for the six failure scenarios

rust/crates/runtime/src/session_control.rs

@@ -1,10 +1,10 @@
+#![allow(dead_code)]
 use std::env;
 use std::fmt::{Display, Formatter};
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::time::UNIX_EPOCH;
 
-
 use crate::session::{Session, SessionError};
 
 pub const PRIMARY_SESSION_EXTENSION: &str = "jsonl";

rust/crates/runtime/src/stale_branch.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::must_use_candidate)]
 use std::path::Path;
 use std::process::Command;
 

rust/crates/runtime/src/task_packet.rs

@@ -66,11 +66,7 @@ pub fn validate_packet(packet: TaskPacket) -> Result<ValidatedPacket, TaskPacket
         &packet.reporting_contract,
         &mut errors,
     );
-    validate_required(
-        "escalation_policy",
-        &packet.escalation_policy,
-        &mut errors,
-    );
+    validate_required("escalation_policy", &packet.escalation_policy, &mut errors);
 
     for (index, test) in packet.acceptance_tests.iter().enumerate() {
         if test.trim().is_empty() {
@@ -146,9 +142,9 @@ mod tests {
         assert!(error
             .errors()
             .contains(&"repo must not be empty".to_string()));
-        assert!(error.errors().contains(
-            &"acceptance_tests contains an empty value at index 1".to_string()
-        ));
+        assert!(error
+            .errors()
+            .contains(&"acceptance_tests contains an empty value at index 1".to_string()));
     }
 
     #[test]

rust/crates/runtime/src/task_registry.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::must_use_candidate, clippy::unnecessary_map_or)]
 //! In-memory task registry for sub-agent task lifecycle management.
 
 use std::collections::HashMap;
@@ -76,11 +77,7 @@ impl TaskRegistry {
     }
 
     pub fn create(&self, prompt: &str, description: Option<&str>) -> Task {
-        self.create_task(
-            prompt.to_owned(),
-            description.map(str::to_owned),
-            None,
-        )
+        self.create_task(prompt.to_owned(), description.map(str::to_owned), None)
     }
 
     pub fn create_from_packet(

rust/crates/runtime/src/team_cron_registry.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::must_use_candidate)]
 //! In-memory registries for Team and Cron lifecycle management.
 //!
 //! Provides TeamCreate/Delete and CronCreate/Delete/List runtime backing

rust/crates/runtime/src/worker_boot.rs

@@ -1,3 +1,10 @@
+#![allow(
+    clippy::struct_excessive_bools,
+    clippy::too_many_lines,
+    clippy::question_mark,
+    clippy::redundant_closure,
+    clippy::map_unwrap_or
+)]
 //! In-memory worker-boot state machine and control registry.
 //!
 //! This provides a foundational control plane for reliable worker startup:
@@ -257,7 +264,9 @@ impl WorkerRegistry {
             let prompt_preview = prompt_preview(worker.last_prompt.as_deref().unwrap_or_default());
             let message = match observation.target {
                 WorkerPromptTarget::Shell => {
-                    format!("worker prompt landed in shell instead of coding agent: {prompt_preview}")
+                    format!(
+                        "worker prompt landed in shell instead of coding agent: {prompt_preview}"
+                    )
                 }
                 WorkerPromptTarget::WrongTarget => format!(
                     "worker prompt landed in the wrong target instead of {}: {}",
@@ -312,7 +321,9 @@ impl WorkerRegistry {
             worker.last_error = None;
         }
 
-        if detect_ready_for_prompt(screen_text, &lowered) && worker.status != WorkerStatus::ReadyForPrompt {
+        if detect_ready_for_prompt(screen_text, &lowered)
+            && worker.status != WorkerStatus::ReadyForPrompt
+        {
             worker.status = WorkerStatus::ReadyForPrompt;
             worker.prompt_in_flight = false;
             if matches!(
@@ -412,7 +423,10 @@ impl WorkerRegistry {
             worker_id: worker.worker_id.clone(),
             status: worker.status,
             ready: worker.status == WorkerStatus::ReadyForPrompt,
-            blocked: matches!(worker.status, WorkerStatus::TrustRequired | WorkerStatus::Failed),
+            blocked: matches!(
+                worker.status,
+                WorkerStatus::TrustRequired | WorkerStatus::Failed
+            ),
             replay_prompt_ready: worker.replay_prompt.is_some(),
             last_error: worker.last_error.clone(),
         })

rust/crates/runtime/tests/integration_tests.rs

@@ -1,3 +1,4 @@
+#![allow(clippy::doc_markdown, clippy::uninlined_format_args, unused_imports)]
 //! Integration tests for cross-module wiring.
 //!
 //! These tests verify that adjacent modules in the runtime crate actually

rust/crates/rusty-claude-cli/Cargo.toml

@@ -31,3 +31,4 @@ workspace = true
 mock-anthropic-service = { path = "../mock-anthropic-service" }
 serde_json.workspace = true
 tokio = { version = "1", features = ["rt-multi-thread"] }
+

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

@@ -1,567 +0,0 @@
-use std::io::{self, Write};
-use std::path::PathBuf;
-
-use crate::args::{OutputFormat, PermissionMode};
-use crate::input::{LineEditor, ReadOutcome};
-use crate::render::{Spinner, TerminalRenderer};
-use runtime::{ConversationClient, ConversationMessage, RuntimeError, StreamEvent, UsageSummary};
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SessionConfig {
-    pub model: String,
-    pub permission_mode: PermissionMode,
-    pub config: Option<PathBuf>,
-    pub output_format: OutputFormat,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SessionState {
-    pub turns: usize,
-    pub compacted_messages: usize,
-    pub last_model: String,
-    pub last_usage: UsageSummary,
-}
-
-impl SessionState {
-    #[must_use]
-    pub fn new(model: impl Into<String>) -> Self {
-        Self {
-            turns: 0,
-            compacted_messages: 0,
-            last_model: model.into(),
-            last_usage: UsageSummary::default(),
-        }
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum CommandResult {
-    Continue,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum SlashCommand {
-    Help,
-    Status,
-    Compact,
-    Model { model: Option<String> },
-    Permissions { mode: Option<String> },
-    Config { section: Option<String> },
-    Memory,
-    Clear { confirm: bool },
-    Unknown(String),
-}
-
-impl SlashCommand {
-    #[must_use]
-    pub fn parse(input: &str) -> Option<Self> {
-        let trimmed = input.trim();
-        if !trimmed.starts_with('/') {
-            return None;
-        }
-
-        let mut parts = trimmed.trim_start_matches('/').split_whitespace();
-        let command = parts.next().unwrap_or_default();
-        Some(match command {
-            "help" => Self::Help,
-            "status" => Self::Status,
-            "compact" => Self::Compact,
-            "model" => Self::Model {
-                model: parts.next().map(ToOwned::to_owned),
-            },
-            "permissions" => Self::Permissions {
-                mode: parts.next().map(ToOwned::to_owned),
-            },
-            "config" => Self::Config {
-                section: parts.next().map(ToOwned::to_owned),
-            },
-            "memory" => Self::Memory,
-            "clear" => Self::Clear {
-                confirm: parts.next() == Some("--confirm"),
-            },
-            other => Self::Unknown(other.to_string()),
-        })
-    }
-}
-
-struct SlashCommandHandler {
-    command: SlashCommand,
-    summary: &'static str,
-}
-
-const SLASH_COMMAND_HANDLERS: &[SlashCommandHandler] = &[
-    SlashCommandHandler {
-        command: SlashCommand::Help,
-        summary: "Show command help",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Status,
-        summary: "Show current session status",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Compact,
-        summary: "Compact local session history",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Model { model: None },
-        summary: "Show or switch the active model",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Permissions { mode: None },
-        summary: "Show or switch the active permission mode",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Config { section: None },
-        summary: "Inspect current config path or section",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Memory,
-        summary: "Inspect loaded memory/instruction files",
-    },
-    SlashCommandHandler {
-        command: SlashCommand::Clear { confirm: false },
-        summary: "Start a fresh local session",
-    },
-];
-
-pub struct CliApp {
-    config: SessionConfig,
-    renderer: TerminalRenderer,
-    state: SessionState,
-    conversation_client: ConversationClient,
-    conversation_history: Vec<ConversationMessage>,
-}
-
-impl CliApp {
-    pub fn new(config: SessionConfig) -> Result<Self, RuntimeError> {
-        let state = SessionState::new(config.model.clone());
-        let conversation_client = ConversationClient::from_env(config.model.clone())?;
-        Ok(Self {
-            config,
-            renderer: TerminalRenderer::new(),
-            state,
-            conversation_client,
-            conversation_history: Vec::new(),
-        })
-    }
-
-    pub fn run_repl(&mut self) -> io::Result<()> {
-        let mut editor = LineEditor::new("› ", Vec::new());
-        println!("Rusty Claude CLI interactive mode");
-        println!("Type /help for commands. Shift+Enter or Ctrl+J inserts a newline.");
-
-        loop {
-            match editor.read_line()? {
-                ReadOutcome::Submit(input) => {
-                    if input.trim().is_empty() {
-                        continue;
-                    }
-                    self.handle_submission(&input, &mut io::stdout())?;
-                }
-                ReadOutcome::Cancel => continue,
-                ReadOutcome::Exit => break,
-            }
-        }
-
-        Ok(())
-    }
-
-    pub fn run_prompt(&mut self, prompt: &str, out: &mut impl Write) -> io::Result<()> {
-        self.render_response(prompt, out)
-    }
-
-    pub fn handle_submission(
-        &mut self,
-        input: &str,
-        out: &mut impl Write,
-    ) -> io::Result<CommandResult> {
-        if let Some(command) = SlashCommand::parse(input) {
-            return self.dispatch_slash_command(command, out);
-        }
-
-        self.state.turns += 1;
-        self.render_response(input, out)?;
-        Ok(CommandResult::Continue)
-    }
-
-    fn dispatch_slash_command(
-        &mut self,
-        command: SlashCommand,
-        out: &mut impl Write,
-    ) -> io::Result<CommandResult> {
-        match command {
-            SlashCommand::Help => Self::handle_help(out),
-            SlashCommand::Status => self.handle_status(out),
-            SlashCommand::Compact => self.handle_compact(out),
-            SlashCommand::Model { model } => self.handle_model(model.as_deref(), out),
-            SlashCommand::Permissions { mode } => self.handle_permissions(mode.as_deref(), out),
-            SlashCommand::Config { section } => self.handle_config(section.as_deref(), out),
-            SlashCommand::Memory => self.handle_memory(out),
-            SlashCommand::Clear { confirm } => self.handle_clear(confirm, out),
-            SlashCommand::Unknown(name) => {
-                writeln!(out, "Unknown slash command: /{name}")?;
-                Ok(CommandResult::Continue)
-            }
-        }
-    }
-
-    fn handle_help(out: &mut impl Write) -> io::Result<CommandResult> {
-        writeln!(out, "Available commands:")?;
-        for handler in SLASH_COMMAND_HANDLERS {
-            let name = match handler.command {
-                SlashCommand::Help => "/help",
-                SlashCommand::Status => "/status",
-                SlashCommand::Compact => "/compact",
-                SlashCommand::Model { .. } => "/model [model]",
-                SlashCommand::Permissions { .. } => "/permissions [mode]",
-                SlashCommand::Config { .. } => "/config [section]",
-                SlashCommand::Memory => "/memory",
-                SlashCommand::Clear { .. } => "/clear [--confirm]",
-                SlashCommand::Unknown(_) => continue,
-            };
-            writeln!(out, "  {name:<9} {}", handler.summary)?;
-        }
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_status(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
-        writeln!(
-            out,
-            "status: turns={} model={} permission-mode={:?} output-format={:?} last-usage={} in/{} out config={}",
-            self.state.turns,
-            self.state.last_model,
-            self.config.permission_mode,
-            self.config.output_format,
-            self.state.last_usage.input_tokens,
-            self.state.last_usage.output_tokens,
-            self.config
-                .config
-                .as_ref()
-                .map_or_else(|| String::from("<none>"), |path| path.display().to_string())
-        )?;
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_compact(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
-        self.state.compacted_messages += self.state.turns;
-        self.state.turns = 0;
-        self.conversation_history.clear();
-        writeln!(
-            out,
-            "Compacted session history into a local summary ({} messages total compacted).",
-            self.state.compacted_messages
-        )?;
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_model(
-        &mut self,
-        model: Option<&str>,
-        out: &mut impl Write,
-    ) -> io::Result<CommandResult> {
-        match model {
-            Some(model) => {
-                self.config.model = model.to_string();
-                self.state.last_model = model.to_string();
-                writeln!(out, "Active model set to {model}")?;
-            }
-            None => {
-                writeln!(out, "Active model: {}", self.config.model)?;
-            }
-        }
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_permissions(
-        &mut self,
-        mode: Option<&str>,
-        out: &mut impl Write,
-    ) -> io::Result<CommandResult> {
-        match mode {
-            None => writeln!(out, "Permission mode: {:?}", self.config.permission_mode)?,
-            Some("read-only") => {
-                self.config.permission_mode = PermissionMode::ReadOnly;
-                writeln!(out, "Permission mode set to read-only")?;
-            }
-            Some("workspace-write") => {
-                self.config.permission_mode = PermissionMode::WorkspaceWrite;
-                writeln!(out, "Permission mode set to workspace-write")?;
-            }
-            Some("danger-full-access") => {
-                self.config.permission_mode = PermissionMode::DangerFullAccess;
-                writeln!(out, "Permission mode set to danger-full-access")?;
-            }
-            Some(other) => {
-                writeln!(out, "Unknown permission mode: {other}")?;
-            }
-        }
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_config(
-        &mut self,
-        section: Option<&str>,
-        out: &mut impl Write,
-    ) -> io::Result<CommandResult> {
-        match section {
-            None => writeln!(
-                out,
-                "Config path: {}",
-                self.config
-                    .config
-                    .as_ref()
-                    .map_or_else(|| String::from("<none>"), |path| path.display().to_string())
-            )?,
-            Some(section) => writeln!(
-                out,
-                "Config section `{section}` is not fully implemented yet; current config path is {}",
-                self.config
-                    .config
-                    .as_ref()
-                    .map_or_else(|| String::from("<none>"), |path| path.display().to_string())
-            )?,
-        }
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_memory(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
-        writeln!(
-            out,
-            "Loaded memory/config file: {}",
-            self.config
-                .config
-                .as_ref()
-                .map_or_else(|| String::from("<none>"), |path| path.display().to_string())
-        )?;
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_clear(&mut self, confirm: bool, out: &mut impl Write) -> io::Result<CommandResult> {
-        if !confirm {
-            writeln!(out, "Refusing to clear without confirmation. Re-run as /clear --confirm")?;
-            return Ok(CommandResult::Continue);
-        }
-
-        self.state.turns = 0;
-        self.state.compacted_messages = 0;
-        self.state.last_usage = UsageSummary::default();
-        self.conversation_history.clear();
-        writeln!(out, "Started a fresh local session.")?;
-        Ok(CommandResult::Continue)
-    }
-
-    fn handle_stream_event(
-        renderer: &TerminalRenderer,
-        event: StreamEvent,
-        stream_spinner: &mut Spinner,
-        tool_spinner: &mut Spinner,
-        saw_text: &mut bool,
-        turn_usage: &mut UsageSummary,
-        out: &mut impl Write,
-    ) {
-        match event {
-            StreamEvent::TextDelta(delta) => {
-                if !*saw_text {
-                    let _ =
-                        stream_spinner.finish("Streaming response", renderer.color_theme(), out);
-                    *saw_text = true;
-                }
-                let _ = write!(out, "{delta}");
-                let _ = out.flush();
-            }
-            StreamEvent::ToolCallStart { name, input } => {
-                if *saw_text {
-                    let _ = writeln!(out);
-                }
-                let _ = tool_spinner.tick(
-                    &format!("Running tool `{name}` with {input}"),
-                    renderer.color_theme(),
-                    out,
-                );
-            }
-            StreamEvent::ToolCallResult {
-                name,
-                output,
-                is_error,
-            } => {
-                let label = if is_error {
-                    format!("Tool `{name}` failed")
-                } else {
-                    format!("Tool `{name}` completed")
-                };
-                let _ = tool_spinner.finish(&label, renderer.color_theme(), out);
-                let rendered_output = format!("### Tool `{name}`\n\n```text\n{output}\n```\n");
-                let _ = renderer.stream_markdown(&rendered_output, out);
-            }
-            StreamEvent::Usage(usage) => {
-                *turn_usage = usage;
-            }
-        }
-    }
-
-    fn write_turn_output(
-        &self,
-        summary: &runtime::TurnSummary,
-        out: &mut impl Write,
-    ) -> io::Result<()> {
-        match self.config.output_format {
-            OutputFormat::Text => {
-                writeln!(
-                    out,
-                    "\nToken usage: {} input / {} output",
-                    self.state.last_usage.input_tokens, self.state.last_usage.output_tokens
-                )?;
-            }
-            OutputFormat::Json => {
-                writeln!(
-                    out,
-                    "{}",
-                    serde_json::json!({
-                        "message": summary.assistant_text,
-                        "usage": {
-                            "input_tokens": self.state.last_usage.input_tokens,
-                            "output_tokens": self.state.last_usage.output_tokens,
-                        }
-                    })
-                )?;
-            }
-            OutputFormat::Ndjson => {
-                writeln!(
-                    out,
-                    "{}",
-                    serde_json::json!({
-                        "type": "message",
-                        "text": summary.assistant_text,
-                        "usage": {
-                            "input_tokens": self.state.last_usage.input_tokens,
-                            "output_tokens": self.state.last_usage.output_tokens,
-                        }
-                    })
-                )?;
-            }
-        }
-        Ok(())
-    }
-
-    fn render_response(&mut self, input: &str, out: &mut impl Write) -> io::Result<()> {
-        let mut stream_spinner = Spinner::new();
-        stream_spinner.tick(
-            "Opening conversation stream",
-            self.renderer.color_theme(),
-            out,
-        )?;
-
-        let mut turn_usage = UsageSummary::default();
-        let mut tool_spinner = Spinner::new();
-        let mut saw_text = false;
-        let renderer = &self.renderer;
-
-        let result =
-            self.conversation_client
-                .run_turn(&mut self.conversation_history, input, |event| {
-                    Self::handle_stream_event(
-                        renderer,
-                        event,
-                        &mut stream_spinner,
-                        &mut tool_spinner,
-                        &mut saw_text,
-                        &mut turn_usage,
-                        out,
-                    );
-                });
-
-        let summary = match result {
-            Ok(summary) => summary,
-            Err(error) => {
-                stream_spinner.fail(
-                    "Streaming response failed",
-                    self.renderer.color_theme(),
-                    out,
-                )?;
-                return Err(io::Error::other(error));
-            }
-        };
-        self.state.last_usage = summary.usage.clone();
-        if saw_text {
-            writeln!(out)?;
-        } else {
-            stream_spinner.finish("Streaming response", self.renderer.color_theme(), out)?;
-        }
-
-        self.write_turn_output(&summary, out)?;
-        let _ = turn_usage;
-        Ok(())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use std::path::PathBuf;
-
-    use crate::args::{OutputFormat, PermissionMode};
-
-    use super::{CommandResult, SessionConfig, SlashCommand};
-
-    #[test]
-    fn parses_required_slash_commands() {
-        assert_eq!(SlashCommand::parse("/help"), Some(SlashCommand::Help));
-        assert_eq!(SlashCommand::parse(" /status "), Some(SlashCommand::Status));
-        assert_eq!(
-            SlashCommand::parse("/compact now"),
-            Some(SlashCommand::Compact)
-        );
-        assert_eq!(
-            SlashCommand::parse("/model claude-sonnet"),
-            Some(SlashCommand::Model {
-                model: Some("claude-sonnet".into()),
-            })
-        );
-        assert_eq!(
-            SlashCommand::parse("/permissions workspace-write"),
-            Some(SlashCommand::Permissions {
-                mode: Some("workspace-write".into()),
-            })
-        );
-        assert_eq!(
-            SlashCommand::parse("/config hooks"),
-            Some(SlashCommand::Config {
-                section: Some("hooks".into()),
-            })
-        );
-        assert_eq!(SlashCommand::parse("/memory"), Some(SlashCommand::Memory));
-        assert_eq!(
-            SlashCommand::parse("/clear --confirm"),
-            Some(SlashCommand::Clear { confirm: true })
-        );
-    }
-
-    #[test]
-    fn help_output_lists_commands() {
-        let mut out = Vec::new();
-        let result = super::CliApp::handle_help(&mut out).expect("help succeeds");
-        assert_eq!(result, CommandResult::Continue);
-        let output = String::from_utf8_lossy(&out);
-        assert!(output.contains("/help"));
-        assert!(output.contains("/status"));
-        assert!(output.contains("/compact"));
-        assert!(output.contains("/model [model]"));
-        assert!(output.contains("/permissions [mode]"));
-        assert!(output.contains("/config [section]"));
-        assert!(output.contains("/memory"));
-        assert!(output.contains("/clear [--confirm]"));
-    }
-
-    #[test]
-    fn session_state_tracks_config_values() {
-        let config = SessionConfig {
-            model: "claude".into(),
-            permission_mode: PermissionMode::DangerFullAccess,
-            config: Some(PathBuf::from("settings.toml")),
-            output_format: OutputFormat::Text,
-        };
-
-        assert_eq!(config.model, "claude");
-        assert_eq!(config.permission_mode, PermissionMode::DangerFullAccess);
-        assert_eq!(config.config, Some(PathBuf::from("settings.toml")));
-    }
-}

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

@@ -1,108 +0,0 @@
-use std::path::PathBuf;
-
-use clap::{Parser, Subcommand, ValueEnum};
-
-#[derive(Debug, Clone, Parser, PartialEq, Eq)]
-#[command(
-    name = "rusty-claude-cli",
-    version,
-    about = "Rust Claude CLI prototype"
-)]
-pub struct Cli {
-    #[arg(long, default_value = "claude-opus-4-6")]
-    pub model: String,
-
-    #[arg(long, value_enum, default_value_t = PermissionMode::DangerFullAccess)]
-    pub permission_mode: PermissionMode,
-
-    #[arg(long)]
-    pub config: Option<PathBuf>,
-
-    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
-    pub output_format: OutputFormat,
-
-    #[command(subcommand)]
-    pub command: Option<Command>,
-}
-
-#[derive(Debug, Clone, Subcommand, PartialEq, Eq)]
-pub enum Command {
-    /// Read upstream TS sources and print extracted counts
-    DumpManifests,
-    /// Print the current bootstrap phase skeleton
-    BootstrapPlan,
-    /// Start the OAuth login flow
-    Login,
-    /// Clear saved OAuth credentials
-    Logout,
-    /// Run a non-interactive prompt and exit
-    Prompt { prompt: Vec<String> },
-}
-
-#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
-pub enum PermissionMode {
-    ReadOnly,
-    WorkspaceWrite,
-    DangerFullAccess,
-}
-
-#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
-pub enum OutputFormat {
-    Text,
-    Json,
-    Ndjson,
-}
-
-#[cfg(test)]
-mod tests {
-    use clap::Parser;
-
-    use super::{Cli, Command, OutputFormat, PermissionMode};
-
-    #[test]
-    fn parses_requested_flags() {
-        let cli = Cli::parse_from([
-            "rusty-claude-cli",
-            "--model",
-            "claude-3-5-haiku",
-            "--permission-mode",
-            "read-only",
-            "--config",
-            "/tmp/config.toml",
-            "--output-format",
-            "ndjson",
-            "prompt",
-            "hello",
-            "world",
-        ]);
-
-        assert_eq!(cli.model, "claude-3-5-haiku");
-        assert_eq!(cli.permission_mode, PermissionMode::ReadOnly);
-        assert_eq!(
-            cli.config.as_deref(),
-            Some(std::path::Path::new("/tmp/config.toml"))
-        );
-        assert_eq!(cli.output_format, OutputFormat::Ndjson);
-        assert_eq!(
-            cli.command,
-            Some(Command::Prompt {
-                prompt: vec!["hello".into(), "world".into()]
-            })
-        );
-    }
-
-    #[test]
-    fn parses_login_and_logout_commands() {
-        let login = Cli::parse_from(["rusty-claude-cli", "login"]);
-        assert_eq!(login.command, Some(Command::Login));
-
-        let logout = Cli::parse_from(["rusty-claude-cli", "logout"]);
-        assert_eq!(logout.command, Some(Command::Logout));
-    }
-
-    #[test]
-    fn defaults_to_danger_full_access_permission_mode() {
-        let cli = Cli::parse_from(["rusty-claude-cli"]);
-        assert_eq!(cli.permission_mode, PermissionMode::DangerFullAccess);
-    }
-}

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

@@ -1,7 +1,7 @@
 use std::fs;
 use std::path::{Path, PathBuf};
 
-const STARTER_CLAUDE_JSON: &str = concat!(
+const STARTER_CLAW_JSON: &str = concat!(
     "{\n",
     "  \"permissions\": {\n",
     "    \"defaultMode\": \"dontAsk\"\n",
@@ -9,7 +9,7 @@ const STARTER_CLAUDE_JSON: &str = concat!(
     "}\n",
 );
 const GITIGNORE_COMMENT: &str = "# Claw Code local artifacts";
-const GITIGNORE_ENTRIES: [&str; 2] = [".claude/settings.local.json", ".claude/sessions/"];
+const GITIGNORE_ENTRIES: [&str; 2] = [".claw/settings.local.json", ".claw/sessions/"];
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum InitStatus {
@@ -80,16 +80,16 @@ struct RepoDetection {
 pub(crate) fn initialize_repo(cwd: &Path) -> Result<InitReport, Box<dyn std::error::Error>> {
     let mut artifacts = Vec::new();
 
-    let claude_dir = cwd.join(".claude");
+    let claw_dir = cwd.join(".claw");
     artifacts.push(InitArtifact {
-        name: ".claude/",
-        status: ensure_dir(&claude_dir)?,
+        name: ".claw/",
+        status: ensure_dir(&claw_dir)?,
     });
 
-    let claude_json = cwd.join(".claude.json");
+    let claw_json = cwd.join(".claw.json");
     artifacts.push(InitArtifact {
-        name: ".claude.json",
-        status: write_file_if_missing(&claude_json, STARTER_CLAUDE_JSON)?,
+        name: ".claw.json",
+        status: write_file_if_missing(&claw_json, STARTER_CLAW_JSON)?,
     });
 
     let gitignore = cwd.join(".gitignore");
@@ -209,7 +209,7 @@ pub(crate) fn render_init_claude_md(cwd: &Path) -> String {
 
     lines.push("## Working agreement".to_string());
     lines.push("- Prefer small, reviewable changes and keep generated bootstrap files aligned with actual repo workflows.".to_string());
-    lines.push("- Keep shared defaults in `.claude.json`; reserve `.claude/settings.local.json` for machine-local overrides.".to_string());
+    lines.push("- Keep shared defaults in `.claw.json`; reserve `.claw/settings.local.json` for machine-local overrides.".to_string());
     lines.push("- Do not overwrite existing `CLAUDE.md` content automatically; update it intentionally when repo workflows change.".to_string());
     lines.push(String::new());
 
@@ -354,15 +354,16 @@ mod tests {
 
         let report = initialize_repo(&root).expect("init should succeed");
         let rendered = report.render();
-        assert!(rendered.contains(".claude/         created"));
-        assert!(rendered.contains(".claude.json     created"));
+        assert!(rendered.contains(".claw/"));
+        assert!(rendered.contains(".claw.json"));
+        assert!(rendered.contains("created"));
         assert!(rendered.contains(".gitignore       created"));
         assert!(rendered.contains("CLAUDE.md        created"));
-        assert!(root.join(".claude").is_dir());
-        assert!(root.join(".claude.json").is_file());
+        assert!(root.join(".claw").is_dir());
+        assert!(root.join(".claw.json").is_file());
         assert!(root.join("CLAUDE.md").is_file());
         assert_eq!(
-            fs::read_to_string(root.join(".claude.json")).expect("read claude json"),
+            fs::read_to_string(root.join(".claw.json")).expect("read claw json"),
             concat!(
                 "{\n",
                 "  \"permissions\": {\n",
@@ -372,8 +373,8 @@ mod tests {
             )
         );
         let gitignore = fs::read_to_string(root.join(".gitignore")).expect("read gitignore");
-        assert!(gitignore.contains(".claude/settings.local.json"));
-        assert!(gitignore.contains(".claude/sessions/"));
+        assert!(gitignore.contains(".claw/settings.local.json"));
+        assert!(gitignore.contains(".claw/sessions/"));
         let claude_md = fs::read_to_string(root.join("CLAUDE.md")).expect("read claude md");
         assert!(claude_md.contains("Languages: Rust."));
         assert!(claude_md.contains("cargo clippy --workspace --all-targets -- -D warnings"));
@@ -386,8 +387,7 @@ mod tests {
         let root = temp_dir();
         fs::create_dir_all(&root).expect("create root");
         fs::write(root.join("CLAUDE.md"), "custom guidance\n").expect("write existing claude md");
-        fs::write(root.join(".gitignore"), ".claude/settings.local.json\n")
-            .expect("write gitignore");
+        fs::write(root.join(".gitignore"), ".claw/settings.local.json\n").expect("write gitignore");
 
         let first = initialize_repo(&root).expect("first init should succeed");
         assert!(first
@@ -395,8 +395,9 @@ mod tests {
             .contains("CLAUDE.md        skipped (already exists)"));
         let second = initialize_repo(&root).expect("second init should succeed");
         let second_rendered = second.render();
-        assert!(second_rendered.contains(".claude/         skipped (already exists)"));
-        assert!(second_rendered.contains(".claude.json     skipped (already exists)"));
+        assert!(second_rendered.contains(".claw/"));
+        assert!(second_rendered.contains(".claw.json"));
+        assert!(second_rendered.contains("skipped (already exists)"));
         assert!(second_rendered.contains(".gitignore       skipped (already exists)"));
         assert!(second_rendered.contains("CLAUDE.md        skipped (already exists)"));
         assert_eq!(
@@ -404,8 +405,8 @@ mod tests {
             "custom guidance\n"
         );
         let gitignore = fs::read_to_string(root.join(".gitignore")).expect("read gitignore");
-        assert_eq!(gitignore.matches(".claude/settings.local.json").count(), 1);
-        assert_eq!(gitignore.matches(".claude/sessions/").count(), 1);
+        assert_eq!(gitignore.matches(".claw/settings.local.json").count(), 1);
+        assert_eq!(gitignore.matches(".claw/sessions/").count(), 1);
 
         fs::remove_dir_all(root).expect("cleanup temp dir");
     }

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

@@ -192,12 +192,10 @@ fn doctor_command_runs_as_a_local_shell_entrypoint() {
 
 #[test]
 fn local_subcommand_help_does_not_fall_through_to_runtime_or_provider_calls() {
-    // given
     let temp_dir = unique_temp_dir("subcommand-help");
     let config_home = temp_dir.join("home").join(".claw");
     fs::create_dir_all(&config_home).expect("config home should exist");
 
-    // when
     let doctor_help = command_in(&temp_dir)
         .env("CLAW_CONFIG_HOME", &config_home)
         .env_remove("ANTHROPIC_API_KEY")
@@ -215,7 +213,6 @@ fn local_subcommand_help_does_not_fall_through_to_runtime_or_provider_calls() {
         .output()
         .expect("status help should launch");
 
-    // then
     assert_success(&doctor_help);
     let doctor_stdout = String::from_utf8(doctor_help.stdout).expect("stdout should be utf8");
     assert!(doctor_stdout.contains("Usage            claw doctor"));

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

@@ -729,8 +729,7 @@ fn assert_token_cost_reporting(_: &HarnessWorkspace, run: &ScenarioRun) {
     assert!(
         run.response["estimated_cost"]
             .as_str()
-            .map(|cost| cost.starts_with('$'))
-            .unwrap_or(false),
+            .is_some_and(|cost| cost.starts_with('$')),
         "estimated_cost should be a dollar-prefixed string"
     );
 }

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

@@ -0,0 +1,196 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Output};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde_json::Value;
+
+static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+#[test]
+fn help_emits_json_when_requested() {
+    let root = unique_temp_dir("help-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let parsed = assert_json_command(&root, &["--output-format", "json", "help"]);
+    assert_eq!(parsed["kind"], "help");
+    assert!(parsed["message"]
+        .as_str()
+        .expect("help text")
+        .contains("Usage:"));
+}
+
+#[test]
+fn version_emits_json_when_requested() {
+    let root = unique_temp_dir("version-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let parsed = assert_json_command(&root, &["--output-format", "json", "version"]);
+    assert_eq!(parsed["kind"], "version");
+    assert_eq!(parsed["version"], env!("CARGO_PKG_VERSION"));
+}
+
+#[test]
+fn status_and_sandbox_emit_json_when_requested() {
+    let root = unique_temp_dir("status-sandbox-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let status = assert_json_command(&root, &["--output-format", "json", "status"]);
+    assert_eq!(status["kind"], "status");
+    assert!(status["workspace"]["cwd"].as_str().is_some());
+
+    let sandbox = assert_json_command(&root, &["--output-format", "json", "sandbox"]);
+    assert_eq!(sandbox["kind"], "sandbox");
+    assert!(sandbox["filesystem_mode"].as_str().is_some());
+}
+
+#[test]
+fn inventory_commands_emit_structured_json_when_requested() {
+    let root = unique_temp_dir("inventory-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let agents = assert_json_command(&root, &["--output-format", "json", "agents"]);
+    assert_eq!(agents["kind"], "agents");
+
+    let mcp = assert_json_command(&root, &["--output-format", "json", "mcp"]);
+    assert_eq!(mcp["kind"], "mcp");
+    assert_eq!(mcp["action"], "list");
+
+    let skills = assert_json_command(&root, &["--output-format", "json", "skills"]);
+    assert_eq!(skills["kind"], "skills");
+    assert_eq!(skills["action"], "list");
+}
+
+#[test]
+fn bootstrap_and_system_prompt_emit_json_when_requested() {
+    let root = unique_temp_dir("bootstrap-system-prompt-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let plan = assert_json_command(&root, &["--output-format", "json", "bootstrap-plan"]);
+    assert_eq!(plan["kind"], "bootstrap-plan");
+    assert!(plan["phases"].as_array().expect("phases").len() > 1);
+
+    let prompt = assert_json_command(&root, &["--output-format", "json", "system-prompt"]);
+    assert_eq!(prompt["kind"], "system-prompt");
+    assert!(prompt["message"]
+        .as_str()
+        .expect("prompt text")
+        .contains("interactive agent"));
+}
+
+#[test]
+fn dump_manifests_and_init_emit_json_when_requested() {
+    let root = unique_temp_dir("manifest-init-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let upstream = write_upstream_fixture(&root);
+    let manifests = assert_json_command_with_env(
+        &root,
+        &["--output-format", "json", "dump-manifests"],
+        &[(
+            "CLAUDE_CODE_UPSTREAM",
+            upstream.to_str().expect("utf8 upstream"),
+        )],
+    );
+    assert_eq!(manifests["kind"], "dump-manifests");
+    assert_eq!(manifests["commands"], 1);
+    assert_eq!(manifests["tools"], 1);
+
+    let workspace = root.join("workspace");
+    fs::create_dir_all(&workspace).expect("workspace should exist");
+    let init = assert_json_command(&workspace, &["--output-format", "json", "init"]);
+    assert_eq!(init["kind"], "init");
+    assert!(workspace.join("CLAUDE.md").exists());
+}
+
+#[test]
+fn doctor_and_resume_status_emit_json_when_requested() {
+    let root = unique_temp_dir("doctor-resume-json");
+    fs::create_dir_all(&root).expect("temp dir should exist");
+
+    let doctor = assert_json_command(&root, &["--output-format", "json", "doctor"]);
+    assert_eq!(doctor["kind"], "doctor");
+    assert!(doctor["message"].is_string());
+
+    let session_path = root.join("session.jsonl");
+    fs::write(
+        &session_path,
+        "{\"type\":\"session_meta\",\"version\":3,\"session_id\":\"resume-json\",\"created_at_ms\":0,\"updated_at_ms\":0}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",\"blocks\":[{\"type\":\"text\",\"text\":\"hello\"}]}}\n",
+    )
+    .expect("session should write");
+    let resumed = assert_json_command(
+        &root,
+        &[
+            "--output-format",
+            "json",
+            "--resume",
+            session_path.to_str().expect("utf8 session path"),
+            "/status",
+        ],
+    );
+    assert_eq!(resumed["kind"], "status");
+    assert_eq!(resumed["model"], "restored-session");
+    assert_eq!(resumed["usage"]["messages"], 1);
+    assert!(resumed["workspace"]["cwd"].as_str().is_some());
+    assert!(resumed["sandbox"]["filesystem_mode"].as_str().is_some());
+}
+
+fn assert_json_command(current_dir: &Path, args: &[&str]) -> Value {
+    assert_json_command_with_env(current_dir, args, &[])
+}
+
+fn assert_json_command_with_env(current_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Value {
+    let output = run_claw(current_dir, args, envs);
+    assert!(
+        output.status.success(),
+        "stdout:\n{}\n\nstderr:\n{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    serde_json::from_slice(&output.stdout).expect("stdout should be valid json")
+}
+
+fn run_claw(current_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Output {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_claw"));
+    command.current_dir(current_dir).args(args);
+    for (key, value) in envs {
+        command.env(key, value);
+    }
+    command.output().expect("claw should launch")
+}
+
+fn write_upstream_fixture(root: &Path) -> PathBuf {
+    let upstream = root.join("claw-code");
+    let src = upstream.join("src");
+    let entrypoints = src.join("entrypoints");
+    fs::create_dir_all(&entrypoints).expect("upstream entrypoints dir should exist");
+    fs::write(
+        src.join("commands.ts"),
+        "import FooCommand from './commands/foo'\n",
+    )
+    .expect("commands fixture should write");
+    fs::write(
+        src.join("tools.ts"),
+        "import ReadTool from './tools/read'\n",
+    )
+    .expect("tools fixture should write");
+    fs::write(
+        entrypoints.join("cli.tsx"),
+        "if (args[0] === '--version') {}\nstartupProfiler()\n",
+    )
+    .expect("cli fixture should write");
+    upstream
+}
+
+fn unique_temp_dir(label: &str) -> PathBuf {
+    let millis = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("clock should be after epoch")
+        .as_millis();
+    let counter = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
+    std::env::temp_dir().join(format!(
+        "claw-output-format-{label}-{}-{millis}-{counter}",
+        std::process::id()
+    ))
+}

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

@@ -7,6 +7,7 @@ use std::time::{SystemTime, UNIX_EPOCH};
 
 use runtime::ContentBlock;
 use runtime::Session;
+use serde_json::Value;
 
 static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
 
@@ -221,6 +222,59 @@ fn resume_latest_restores_the_most_recent_managed_session() {
     assert!(stdout.contains(newer_path.to_str().expect("utf8 path")));
 }
 
+#[test]
+fn resumed_status_command_emits_structured_json_when_requested() {
+    // given
+    let temp_dir = unique_temp_dir("resume-status-json");
+    fs::create_dir_all(&temp_dir).expect("temp dir should exist");
+    let session_path = temp_dir.join("session.jsonl");
+
+    let mut session = Session::new();
+    session
+        .push_user_text("resume status json fixture")
+        .expect("session write should succeed");
+    session
+        .save_to_path(&session_path)
+        .expect("session should persist");
+
+    // when
+    let output = run_claw(
+        &temp_dir,
+        &[
+            "--output-format",
+            "json",
+            "--resume",
+            session_path.to_str().expect("utf8 path"),
+            "/status",
+        ],
+    );
+
+    // then
+    assert!(
+        output.status.success(),
+        "stdout:\n{}\n\nstderr:\n{}",
+        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.trim()).expect("resume status output should be json");
+    assert_eq!(parsed["kind"], "status");
+    assert_eq!(parsed["model"], "restored-session");
+    assert_eq!(parsed["permission_mode"], "danger-full-access");
+    assert_eq!(parsed["usage"]["messages"], 1);
+    assert!(parsed["usage"]["turns"].is_number());
+    assert!(parsed["workspace"]["cwd"].as_str().is_some());
+    assert_eq!(
+        parsed["workspace"]["session"],
+        session_path.to_str().expect("utf8 path")
+    );
+    assert!(parsed["workspace"]["changed_files"].is_number());
+    assert_eq!(parsed["workspace"]["loaded_config_files"].as_u64(), Some(0));
+    assert!(parsed["sandbox"]["filesystem_mode"].as_str().is_some());
+}
+
 fn run_claw(current_dir: &Path, args: &[&str]) -> Output {
     run_claw_with_env(current_dir, args, &[])
 }

rust/crates/tools/src/lane_completion.rs

@@ -16,7 +16,7 @@ use runtime::{
 use crate::AgentOutput;
 
 /// Detects if a lane should be automatically marked as completed.
-/// 
+///
 /// Returns `Some(LaneContext)` with `completed = true` if all conditions met,
 /// `None` if lane should remain active.
 #[allow(dead_code)]
@@ -29,29 +29,29 @@ pub(crate) fn detect_lane_completion(
     if output.error.is_some() {
         return None;
     }
-    
+
     // Must have finished status
     if !output.status.eq_ignore_ascii_case("completed")
         && !output.status.eq_ignore_ascii_case("finished")
     {
         return None;
     }
-    
+
     // Must have no current blocker
     if output.current_blocker.is_some() {
         return None;
     }
-    
+
     // Must have green tests
     if !test_green {
         return None;
     }
-    
+
     // Must have pushed code
     if !has_pushed {
         return None;
     }
-    
+
     // All conditions met — create completed context
     Some(LaneContext {
         lane_id: output.agent_id.clone(),
@@ -67,9 +67,7 @@ pub(crate) fn detect_lane_completion(
 
 /// Evaluates policy actions for a completed lane.
 #[allow(dead_code)]
-pub(crate) fn evaluate_completed_lane(
-    context: &LaneContext,
-) -> Vec<PolicyAction> {
+pub(crate) fn evaluate_completed_lane(context: &LaneContext) -> Vec<PolicyAction> {
     let engine = PolicyEngine::new(vec![
         PolicyRule::new(
             "closeout-completed-lane",
@@ -87,7 +85,7 @@ pub(crate) fn evaluate_completed_lane(
             5,
         ),
     ]);
-    
+
     evaluate(&engine, context)
 }
 
@@ -110,57 +108,58 @@ mod tests {
             started_at: Some("2024-01-01T00:00:00Z".to_string()),
             completed_at: Some("2024-01-01T00:00:00Z".to_string()),
             lane_events: vec![],
+            derived_state: "working".to_string(),
             current_blocker: None,
             error: None,
         }
     }
-    
+
     #[test]
     fn detects_completion_when_all_conditions_met() {
         let output = test_output();
         let result = detect_lane_completion(&output, true, true);
-        
+
         assert!(result.is_some());
         let context = result.unwrap();
         assert!(context.completed);
         assert_eq!(context.green_level, 3);
         assert_eq!(context.blocker, LaneBlocker::None);
     }
-    
+
     #[test]
     fn no_completion_when_error_present() {
         let mut output = test_output();
         output.error = Some("Build failed".to_string());
-        
+
         let result = detect_lane_completion(&output, true, true);
         assert!(result.is_none());
     }
-    
+
     #[test]
     fn no_completion_when_not_finished() {
         let mut output = test_output();
         output.status = "Running".to_string();
-        
+
         let result = detect_lane_completion(&output, true, true);
         assert!(result.is_none());
     }
-    
+
     #[test]
     fn no_completion_when_tests_not_green() {
         let output = test_output();
-        
+
         let result = detect_lane_completion(&output, false, true);
         assert!(result.is_none());
     }
-    
+
     #[test]
     fn no_completion_when_not_pushed() {
         let output = test_output();
-        
+
         let result = detect_lane_completion(&output, true, false);
         assert!(result.is_none());
     }
-    
+
     #[test]
     fn evaluate_triggers_closeout_for_completed_lane() {
         let context = LaneContext {
@@ -173,9 +172,9 @@ mod tests {
             completed: true,
             reconciled: false,
         };
-        
+
         let actions = evaluate_completed_lane(&context);
-        
+
         assert!(actions.contains(&PolicyAction::CloseoutLane));
         assert!(actions.contains(&PolicyAction::CleanupSession));
     }

rust/crates/tools/src/lib.rs

@@ -11,21 +11,21 @@ use api::{
 use plugins::PluginTool;
 use reqwest::blocking::Client;
 use runtime::{
-    check_freshness, edit_file, execute_bash, glob_search, grep_search, load_system_prompt,
+    check_freshness, dedupe_superseded_commit_events, edit_file, execute_bash, glob_search,
+    grep_search, load_system_prompt,
     lsp_client::LspRegistry,
     mcp_tool_bridge::McpToolRegistry,
     permission_enforcer::{EnforcementResult, PermissionEnforcer},
     read_file,
     summary_compression::compress_summary_text,
-    TaskPacket,
     task_registry::TaskRegistry,
     team_cron_registry::{CronRegistry, TeamRegistry},
     worker_boot::{WorkerReadySnapshot, WorkerRegistry},
     write_file, ApiClient, ApiRequest, AssistantEvent, BashCommandInput, BashCommandOutput,
     BranchFreshness, ContentBlock, ConversationMessage, ConversationRuntime, GrepSearchInput,
-    LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus, LaneFailureClass,
-    McpDegradedReport, MessageRole, PermissionMode, PermissionPolicy, PromptCacheEvent,
-    RuntimeError, Session, ToolError, ToolExecutor,
+    LaneCommitProvenance, LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus,
+    LaneFailureClass, McpDegradedReport, MessageRole, PermissionMode, PermissionPolicy,
+    PromptCacheEvent, RuntimeError, Session, TaskPacket, ToolError, ToolExecutor,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
@@ -1705,7 +1705,7 @@ fn run_remote_trigger(input: RemoteTriggerInput) -> Result<String, String> {
                 "method": method,
                 "status_code": status,
                 "body": truncated_body,
-                "success": status >= 200 && status < 300
+                "success": (200..300).contains(&status)
             }))
         }
         Err(e) => to_pretty_json(json!({
@@ -1878,27 +1878,25 @@ fn branch_divergence_output(
         dangerously_disable_sandbox: None,
         return_code_interpretation: Some("preflight_blocked:branch_divergence".to_string()),
         no_output_expected: Some(false),
-        structured_content: Some(vec![
-            serde_json::to_value(
-                LaneEvent::new(
-                    LaneEventName::BranchStaleAgainstMain,
-                    LaneEventStatus::Blocked,
-                    iso8601_now(),
-                )
-                    .with_failure_class(LaneFailureClass::BranchDivergence)
-                    .with_detail(stderr.clone())
-                    .with_data(json!({
-                        "branch": branch,
-                        "mainRef": main_ref,
-                        "commitsBehind": commits_behind,
-                        "commitsAhead": commits_ahead,
-                        "missingCommits": missing_fixes,
-                        "blockedCommand": command,
-                        "recommendedAction": format!("merge or rebase {main_ref} before workspace tests")
-                    })),
+        structured_content: Some(vec![serde_json::to_value(
+            LaneEvent::new(
+                LaneEventName::BranchStaleAgainstMain,
+                LaneEventStatus::Blocked,
+                iso8601_now(),
             )
-            .expect("lane event should serialize"),
-        ]),
+            .with_failure_class(LaneFailureClass::BranchDivergence)
+            .with_detail(stderr.clone())
+            .with_data(json!({
+                "branch": branch,
+                "mainRef": main_ref,
+                "commitsBehind": commits_behind,
+                "commitsAhead": commits_ahead,
+                "missingCommits": missing_fixes,
+                "blockedCommand": command,
+                "recommendedAction": format!("merge or rebase {main_ref} before workspace tests")
+            })),
+        )
+        .expect("lane event should serialize")]),
         persisted_output_path: None,
         persisted_output_size: None,
         sandbox_status: None,
@@ -2368,6 +2366,8 @@ struct AgentOutput {
     lane_events: Vec<LaneEvent>,
     #[serde(rename = "currentBlocker", skip_serializing_if = "Option::is_none")]
     current_blocker: Option<LaneEventBlocker>,
+    #[serde(rename = "derivedState")]
+    derived_state: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     error: Option<String>,
 }
@@ -2979,15 +2979,21 @@ fn resolve_skill_path(skill: &str) -> Result<std::path::PathBuf, String> {
     }
 
     let mut candidates = Vec::new();
+    if let Ok(claw_config_home) = std::env::var("CLAW_CONFIG_HOME") {
+        candidates.push(std::path::PathBuf::from(claw_config_home).join("skills"));
+    }
     if let Ok(codex_home) = std::env::var("CODEX_HOME") {
         candidates.push(std::path::PathBuf::from(codex_home).join("skills"));
     }
     if let Ok(home) = std::env::var("HOME") {
         let home = std::path::PathBuf::from(home);
+        candidates.push(home.join(".claw").join("skills"));
         candidates.push(home.join(".agents").join("skills"));
         candidates.push(home.join(".config").join("opencode").join("skills"));
         candidates.push(home.join(".codex").join("skills"));
+        candidates.push(home.join(".claude").join("skills"));
     }
+    candidates.push(std::path::PathBuf::from("/home/bellman/.claw/skills"));
     candidates.push(std::path::PathBuf::from("/home/bellman/.codex/skills"));
 
     for root in candidates {
@@ -3083,6 +3089,7 @@ where
         completed_at: None,
         lane_events: vec![LaneEvent::started(iso8601_now())],
         current_blocker: None,
+        derived_state: String::from("working"),
         error: None,
     };
     write_agent_manifest(&manifest)?;
@@ -3273,9 +3280,11 @@ fn agent_permission_policy() -> PermissionPolicy {
 }
 
 fn write_agent_manifest(manifest: &AgentOutput) -> Result<(), String> {
+    let mut normalized = manifest.clone();
+    normalized.lane_events = dedupe_superseded_commit_events(&normalized.lane_events);
     std::fs::write(
-        &manifest.manifest_file,
-        serde_json::to_string_pretty(manifest).map_err(|error| error.to_string())?,
+        &normalized.manifest_file,
+        serde_json::to_string_pretty(&normalized).map_err(|error| error.to_string())?,
     )
     .map_err(|error| error.to_string())
 }
@@ -3294,15 +3303,17 @@ fn persist_agent_terminal_state(
     let mut next_manifest = manifest.clone();
     next_manifest.status = status.to_string();
     next_manifest.completed_at = Some(iso8601_now());
-    next_manifest.current_blocker = blocker.clone();
+    next_manifest.current_blocker.clone_from(&blocker);
+    next_manifest.derived_state =
+        derive_agent_state(status, result, error.as_deref(), blocker.as_ref()).to_string();
     next_manifest.error = error;
     if let Some(blocker) = blocker {
-        next_manifest.lane_events.push(
-            LaneEvent::blocked(iso8601_now(), &blocker),
-        );
-        next_manifest.lane_events.push(
-            LaneEvent::failed(iso8601_now(), &blocker),
-        );
+        next_manifest
+            .lane_events
+            .push(LaneEvent::blocked(iso8601_now(), &blocker));
+        next_manifest
+            .lane_events
+            .push(LaneEvent::failed(iso8601_now(), &blocker));
     } else {
         next_manifest.current_blocker = None;
         let compressed_detail = result
@@ -3311,10 +3322,92 @@ fn persist_agent_terminal_state(
         next_manifest
             .lane_events
             .push(LaneEvent::finished(iso8601_now(), compressed_detail));
+        if let Some(provenance) = maybe_commit_provenance(result) {
+            next_manifest.lane_events.push(LaneEvent::commit_created(
+                iso8601_now(),
+                Some(format!("commit {}", provenance.commit)),
+                provenance,
+            ));
+        }
     }
     write_agent_manifest(&next_manifest)
 }
 
+fn derive_agent_state(
+    status: &str,
+    result: Option<&str>,
+    error: Option<&str>,
+    blocker: Option<&LaneEventBlocker>,
+) -> &'static str {
+    let normalized_status = status.trim().to_ascii_lowercase();
+    let normalized_error = error.unwrap_or_default().to_ascii_lowercase();
+
+    if normalized_status == "running" {
+        return "working";
+    }
+    if normalized_status == "completed" {
+        return if result.is_some_and(|value| !value.trim().is_empty()) {
+            "finished_cleanable"
+        } else {
+            "finished_pending_report"
+        };
+    }
+    if normalized_error.contains("background") {
+        return "blocked_background_job";
+    }
+    if normalized_error.contains("merge conflict") || normalized_error.contains("cherry-pick") {
+        return "blocked_merge_conflict";
+    }
+    if normalized_error.contains("mcp") {
+        return "degraded_mcp";
+    }
+    if normalized_error.contains("transport")
+        || normalized_error.contains("broken pipe")
+        || normalized_error.contains("connection")
+        || normalized_error.contains("interrupted")
+    {
+        return "interrupted_transport";
+    }
+    if blocker.is_some() {
+        return "truly_idle";
+    }
+    "truly_idle"
+}
+
+fn maybe_commit_provenance(result: Option<&str>) -> Option<LaneCommitProvenance> {
+    let commit = extract_commit_sha(result?)?;
+    let branch = current_git_branch().unwrap_or_else(|| "unknown".to_string());
+    let worktree = std::env::current_dir()
+        .ok()
+        .map(|path| path.display().to_string());
+    Some(LaneCommitProvenance {
+        commit: commit.clone(),
+        branch,
+        worktree,
+        canonical_commit: Some(commit.clone()),
+        superseded_by: None,
+        lineage: vec![commit],
+    })
+}
+
+fn extract_commit_sha(result: &str) -> Option<String> {
+    result
+        .split(|c: char| !c.is_ascii_hexdigit())
+        .find(|token| token.len() >= 7 && token.len() <= 40)
+        .map(str::to_string)
+}
+
+fn current_git_branch() -> Option<String> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .output()
+        .ok()?;
+    output
+        .status
+        .success()
+        .then(|| String::from_utf8_lossy(&output.stdout).trim().to_string())
+}
+
 fn append_agent_output(path: &str, suffix: &str) -> Result<(), String> {
     use std::io::Write as _;
 
@@ -4950,10 +5043,10 @@ mod tests {
 
     use super::{
         agent_permission_policy, allowed_tools_for_subagent, classify_lane_failure,
-        execute_agent_with_spawn, execute_tool, final_assistant_text, mvp_tool_specs,
-        permission_mode_from_plugin, persist_agent_terminal_state, push_output_block,
-        run_task_packet, AgentInput, AgentJob, GlobalToolRegistry, LaneEventName,
-        LaneFailureClass, SubagentToolExecutor,
+        derive_agent_state, execute_agent_with_spawn, execute_tool, final_assistant_text,
+        maybe_commit_provenance, mvp_tool_specs, permission_mode_from_plugin,
+        persist_agent_terminal_state, push_output_block, run_task_packet, AgentInput, AgentJob,
+        GlobalToolRegistry, LaneEventName, LaneFailureClass, SubagentToolExecutor,
     };
     use api::OutputContentBlock;
     use runtime::{
@@ -5820,6 +5913,7 @@ mod tests {
     }
 
     #[test]
+    #[allow(clippy::too_many_lines)]
     fn agent_fake_runner_can_persist_completion_and_failure() {
         let _guard = env_lock()
             .lock()
@@ -5839,7 +5933,7 @@ mod tests {
                 persist_agent_terminal_state(
                     &job.manifest,
                     "completed",
-                    Some("Finished successfully"),
+                    Some("Finished successfully in commit abc1234"),
                     None,
                 )
             },
@@ -5862,7 +5956,19 @@ mod tests {
             completed_manifest_json["laneEvents"][1]["event"],
             "lane.finished"
         );
+        assert_eq!(
+            completed_manifest_json["laneEvents"][2]["event"],
+            "lane.commit.created"
+        );
+        assert_eq!(
+            completed_manifest_json["laneEvents"][2]["data"]["commit"],
+            "abc1234"
+        );
         assert!(completed_manifest_json["currentBlocker"].is_null());
+        assert_eq!(
+            completed_manifest_json["derivedState"],
+            "finished_cleanable"
+        );
 
         let failed = execute_agent_with_spawn(
             AgentInput {
@@ -5909,6 +6015,7 @@ mod tests {
             failed_manifest_json["laneEvents"][2]["failureClass"],
             "tool_runtime"
         );
+        assert_eq!(failed_manifest_json["derivedState"], "truly_idle");
 
         let spawn_error = execute_agent_with_spawn(
             AgentInput {
@@ -5942,11 +6049,59 @@ mod tests {
             spawn_error_manifest_json["currentBlocker"]["failureClass"],
             "infra"
         );
+        assert_eq!(spawn_error_manifest_json["derivedState"], "truly_idle");
 
         std::env::remove_var("CLAWD_AGENT_STORE");
         let _ = std::fs::remove_dir_all(dir);
     }
 
+    #[test]
+    fn agent_state_classification_covers_finished_and_specific_blockers() {
+        assert_eq!(derive_agent_state("running", None, None, None), "working");
+        assert_eq!(
+            derive_agent_state("completed", Some("done"), None, None),
+            "finished_cleanable"
+        );
+        assert_eq!(
+            derive_agent_state("completed", None, None, None),
+            "finished_pending_report"
+        );
+        assert_eq!(
+            derive_agent_state("failed", None, Some("mcp handshake timed out"), None),
+            "degraded_mcp"
+        );
+        assert_eq!(
+            derive_agent_state(
+                "failed",
+                None,
+                Some("background terminal still running"),
+                None
+            ),
+            "blocked_background_job"
+        );
+        assert_eq!(
+            derive_agent_state("failed", None, Some("merge conflict while rebasing"), None),
+            "blocked_merge_conflict"
+        );
+        assert_eq!(
+            derive_agent_state(
+                "failed",
+                None,
+                Some("transport interrupted after partial progress"),
+                None
+            ),
+            "interrupted_transport"
+        );
+    }
+
+    #[test]
+    fn commit_provenance_is_extracted_from_agent_results() {
+        let provenance = maybe_commit_provenance(Some("landed as commit deadbee with clean push"))
+            .expect("commit provenance");
+        assert_eq!(provenance.commit, "deadbee");
+        assert_eq!(provenance.canonical_commit.as_deref(), Some("deadbee"));
+        assert_eq!(provenance.lineage, vec!["deadbee".to_string()]);
+    }
     #[test]
     fn lane_failure_taxonomy_normalizes_common_blockers() {
         let cases = [
@@ -5977,7 +6132,10 @@ mod tests {
                 "gateway routing rejected the request",
                 LaneFailureClass::GatewayRouting,
             ),
-            ("tool failed: denied tool execution from hook", LaneFailureClass::ToolRuntime),
+            (
+                "tool failed: denied tool execution from hook",
+                LaneFailureClass::ToolRuntime,
+            ),
             ("thread creation failed", LaneFailureClass::Infra),
         ];
 
@@ -6000,11 +6158,17 @@ mod tests {
             (LaneEventName::MergeReady, "lane.merge.ready"),
             (LaneEventName::Finished, "lane.finished"),
             (LaneEventName::Failed, "lane.failed"),
-            (LaneEventName::BranchStaleAgainstMain, "branch.stale_against_main"),
+            (
+                LaneEventName::BranchStaleAgainstMain,
+                "branch.stale_against_main",
+            ),
         ];
 
         for (event, expected) in cases {
-            assert_eq!(serde_json::to_value(event).expect("serialize lane event"), json!(expected));
+            assert_eq!(
+                serde_json::to_value(event).expect("serialize lane event"),
+                json!(expected)
+            );
         }
     }