@sabaiway/agent-workflow-kit 1.43.0 → 1.44.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.44.0 — Autonomy provisioner: the consent-gated sandbox doctor (AD-044 Plan 2)
+
+A **feature** release (kit-only; memory/engine/bridges unchanged, lineage head stays `2.0.0`). New
+routable GUARDED mode **`autonomy-doctor`** — the cross-platform system provisioner that makes the
+AD-044 sandbox actually initializable on consumer hosts: detect → consent-gated install → verify →
+loud degrade, over the locked matrix (macOS Seatbelt built-in / Linux + WSL2 `bwrap` + `socat` /
+native Windows → WSL2 redirect). This is the kit's FIRST tool that can run a privileged command,
+so the consent and honesty contract is the release:
+
+- **Three explicit lanes.** Flagless = FS-only preview (ZERO subprocesses): the diagnosis, the
+  exact install command it WOULD run, and the exact `--apply <pm>:<pkg,…>` consent line — never a
+  "ready" claim (Linux flagless is `present-unverified`, exit 3, by design). `--verify` = the only
+  source of a Linux "ready (verified)": a pinned bwrap user-namespace smoke + `socat -V`.
+  `--apply <pm>:<pkgs>` = consent bound to the previewed tuple — any mismatch vs the re-derived
+  plan refuses (exit 2) and runs nothing; a successful install auto-verifies.
+- **Privileged execution, closed world.** Every executed token — package manager, sudo, and the
+  binary `env` execs — resolves to an ABSOLUTE path inside the fixed trusted-dir allowlist
+  `/usr/bin:/bin:/usr/sbin:/sbin` (`/usr/local/bin` deliberately excluded); a PATH-shadowed
+  binary triggers a loud advisory, never execution. Frozen 4-family map: apt via the
+  env-trampoline (`sudo /usr/bin/env DEBIAN_FRONTEND=noninteractive apt-get install -y …`, so
+  non-interactivity survives sudo `env_reset`) · dnf `-y` · pacman `--needed --noconfirm` ·
+  apk `add`; package names come from a frozen internal map — no repo/config/user input ever
+  enters the command line. Unknown PM or untrusted location → stated degrade (exit 6), never a
+  guess.
+- **Sudo boundary, honestly.** `sudo -n true` preflight; passwordless success is LOUDLY stated;
+  no TTY + a password required → the ENFORCED print-handoff (the doctor runs NOTHING and prints
+  the exact command to run in your own terminal) — the designed primary path under an agent
+  harness. Root callers (`euid 0` / `SUDO_UID`) are refused a "verified" claim — a green smoke
+  under root can't prove unprivileged user namespaces (`root-unproven`, exit 5).
+- **Frozen output contract.** Exported EXIT/status table (Linux exit 0 ONLY via the verify
+  oracle) + a machine-parseable summary LAST line in every diagnosis outcome (`--help` prints the
+  help text alone); `doc-parity` bindings pin the contract to the mode doc. The docs/ai
+  deployment gate runs after arg parsing, ahead of every diagnosis/verify/apply lane; the
+  `.workflow-version` stamp gate is a stated EXEMPTION (the doctor mutates the OS, never
+  lineage-bound repo content).
+- **Host-proven where it counts.** The bwrap smoke fixture and the apt env-trampoline descriptor
+  are host-proven (the trampoline crossed a real sudo boundary with zero apt prompts); a fresh
+  Claude Code session on the newly-ready host shows the series payoff — an ad-hoc command's
+  prompt-delta drops 1 → 0 while the commit/push/publish red-lines still ask (content-scoped
+  `ask` rules pierce `autoAllowBashIfSandboxed`; the render's exact rule form is load-bearing)
+  and network egress still prompts. The sandbox is picked up at session START — the doctor's
+  success output always states the restart step.
+- **Registration + guards.** The GUARDED legend now reads "consent-gated destructive/privileged
+  actions (dry-run-first)"; the velocity render's sandbox-unavailable degrade message points at
+  the doctor; the doctor stays OUTSIDE every velocity auto-approve tier; tarball sentinel
+  143 → 145 (`tools/autonomy-doctor.mjs` + `references/modes/autonomy-doctor.md`).
+
 ## 1.43.0 — Closed-world gate seeding: lifecycle hooks die by construction (AD-052)
 
 A **feature** release (kit-only; memory/engine/bridges unchanged, lineage head stays `2.0.0`). The

package/README.md

@@ -239,12 +239,13 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--ledger-summary` (AD-049) appends a COMPUTED review-ledger digest for the single in-flight segment (rounds · origins · classifications · verdicts · overrides — unrelated loops excluded), so the reviewer sees the loop's own history without hand-copying. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit review-ledger` | any time | **review-round ledger** — turns the review-loop stop rule into a **computed** signal: record each plan-execution review round, its triage, and any recorded **overrides** (`oracle-change` lifts named tampered test files; `red-proof` waives the observed-red proof for exactly one `testId`; v4 adds **`size-cap`** — the exact sanctioned magnitude for a surface over the diff cap, segment-scoped — all loud, durable, auditable waivers, never silent) into a JSONL ledger inside the git dir (never committable), and read the stop decision (`converged > resolved-residual > triage-required > continue`) from the records — never from a remembered rule. **Since v4 every record carries `base` = the HEAD commit and the whole loop is SEGMENT-scoped (AD-048):** round numbering, the caps, and every tooth reset ONLY at a gated commit — a multiphase plan records fully while round 4 within one segment stays refused; `gate-run` records (minted by `gates --record`) make gates-before-review a computed precondition; the triage class **`refuted`** is the honest phantom-finding lane (grounds mandatory); `--telemetry` renders counts-only gate-efficacy data across all loops and both ledgers. `--status` replaces the hand-composed per-round tally; `record --from-receipts` (AD-049) DRAFTS the `backends[]` from the current-fingerprint receipts (verdict per backend, counts from the supplied findings) instead of hand-composing them — a recipe-named backend with no receipt is a loud stop; `--check` is a fail-closed gate exit code for `docs/ai/gates.json` (by hand or via the consent-gated seeder). A `fixable-bug` triage **requires its red→green `testId`** (v1..v3 records stay valid on read — old records never enter a segment). The writer refuses a round (past the hard-max, while a triage is pending, or lacking a grounded review receipt) and refuses an override outside its single in-flight loop. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit fold-completeness` | any time | **fold-completeness gate** — attests the review loop's folded fixes were proven the HONEST way (no fix theater): the runner executes your suite ONCE under `NODE_V8_COVERAGE`, checks every changed executable line is **executed**, probes every bound `testId` N times (`AW_FOLD_RERUNS`), records content hashes, and scans the test surface for tamper; the `--red` verb observes a test FAILING on the pre-fold tree — **BEFORE the fix** — and mints an **observed-red receipt**. The read-only checker (`--status` / `--check`) then requires, per bound test: the receipt, receipt-precedes-run order, N/N-green probes, and content **custody** (the green test is byte-identical to the one seen failing) — the receipt+custody half waivable for exactly one `testId` by a recorded `red-proof` override; mixed/timed-out probes are QUARANTINE (never converted, no override); **v3 records carry `base` and the proof is segment-scoped (AD-048)** — a committed phase's custody obligations close with its commit, and a receipt never crosses a commit boundary; tampered pre-existing test files fail closed unless covered by a recorded `oracle-change` override. Honest residuals: coverage proves **execution, not assertion**, and records are forgeable — self-discipline, not a security boundary. v1 scope is JS/V8 (pluggable via `AW_FOLD_BOUND_CMD`): changed TS/JSX fails closed, docs/config changes are listed but never block, and **no mutation testing ships**. Wire the gate by hand — the consent-gated seeder deliberately does not offer it yet (JS-only hold). Never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, and the ledger's own class/scope vocabulary) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
 | `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. Preview by default; never writes `settings.local.json`; never commits. |
 | `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the review byte cap, the oversized-review add-dir toggle. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit autonomy-doctor` | opt-in, any time | **guarded sandbox provisioner "doctor"** — can this machine run the Claude sandbox, and (only with your consent) fix it: macOS Seatbelt built-in / Linux+WSL2 needs `bwrap`+`socat` / native Windows → WSL2. Flagless = **FS-only preview** (the diagnosis, the exact absolute-path command it WOULD run, the exact `--apply <pm>:<pkgs>` consent tuple — runs nothing, never claims ready); `--verify` runs the unprivileged proof (a `bwrap` user-namespace smoke + `socat -V`) — the **only** source of a Linux "ready (verified)" claim; `--apply <pm>:<pkgs>` is the consent-gated privileged install (the tuple must equal the previewed plan; everything executed resolves to absolute paths inside `/usr/bin:/bin:/usr/sbin:/sbin`; the exact command is re-printed immediately before execution), then verifies. Honest loud degrades (unknown PM, untrusted location, nested-sandbox INDETERMINATE, root-unproven) and a stated restart step. Sits **outside every velocity auto-approve tier**; never auto-runs, never writes repo files, never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.43.0'
+  version: '1.44.0'
 ---
 
 # agent-workflow-kit
@@ -20,8 +20,7 @@ This kit is the **composition root** of the `agent-workflow` family. The memory
 (`docs/ai/`, the entry-point doc, caps / archive / index, the setup contracts) is owned by
 **`agent-workflow-memory`**. The kit **prefers to delegate** substrate deployment to that skill
 when it is present and healthy, and otherwise uses its **own bundled copy** (`references/`,
-`migrations/`) — so the existing one-command install keeps working with **no new dependency on the
-memory substrate**. (The methodology slot is a separate axis: its fragment is read **live from the
+`migrations/`) — the one-command install stays **dependency-free**. (The methodology slot is a separate axis: its fragment is read **live from the
 installed `agent-workflow-engine`**, which `npx @sabaiway/agent-workflow-kit@latest init` installs;
 see `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md`.)
 `init` also **refreshes the installed memory substrate** (best-effort — a miss is a loud DEGRADED
@@ -50,7 +49,7 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 > [`tools/delegation.mjs`](${CLAUDE_SKILL_DIR}/tools/delegation.mjs): `detectMemory(<memory-dir>)` runs the validator +
 > the required-asset check and returns `delegate` / fallback with a reason; `handoffPlan(delegate)`
 > returns who writes what, which stamps end up present, and that the commit gate is kit-only. Both
-> are unit-tested, so the contract below is pinned by code, not agent interpretation.
+> are unit-tested — the contract below is pinned by code.
 
 **Hand-off contract & bounded pointer reconciliation** — `${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md` (read at the bootstrap/upgrade point of use).
 
@@ -63,25 +62,26 @@ ever deleted.
 
 ## Modes
 
-Pick the mode from the user's invocation — the mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested; safe-routing rule below). An existing `docs/ai/` guards against bootstrapping over a live system — the user makes the final call.
+Pick the mode from the user's invocation — the mapping is pinned by `tools/commands.mjs` `routeInvocation` (safe-routing rule below). An existing `docs/ai/` guards against bootstrapping over a live system.
 
 ### Version status & the two axes — the internal routing check
 
-**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can). The mapping is unit-tested, so it is not left to interpretation.
+**Safe-routing rule (which mode did the user invoke?).** Map the invocation token with `tools/commands.mjs` `routeInvocation`: a **known** subcommand → its mode; the **bare/empty** invocation → `bootstrap` — the one writer reachable without a token, and only on an undeployed project (if `docs/ai/` already exists, **ask upgrade-vs-bootstrap**, never overwrite); **any unrecognized/ambiguous** token → `help`, which is **read-only**. The invariant: **no unrecognized/garbage invocation ever triggers a write** (only an explicit known token or the acknowledged bare-bootstrap exception can).
 
-Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide the route — this is an **internal** routing decision, **not** a line you print to the user (the number itself is shown only per *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Route:
+Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide the route — an **internal** routing decision, **not** a line you print (version display: *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Route:
 
 - **absent** → bootstrap (a fresh deployment).
 - **stamp < `2.0.0`** (the deployment-lineage head) → `upgrade`.
 - **stamp == `2.0.0`** → already current; only the stamp-independent reconciles may run — the FULL set lives in `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 3; run step 3 (never enumerate the reconciles from memory).
 - **stamp > head / unparseable** → STOP — never-downgrade gate (see `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md` step 2).
+- **Exempt:** `autonomy-doctor` provisions the OS, not the deployment — stamp-independent (stated in its mode file).
 
 **Two independent version axes — never conflate them:**
 
 1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`2.0.0`). This is the **only** axis this skill compares.
 2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version is **not** the lineage head.
 
-**Refreshed the kit but nothing changed?** After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
+**Refreshed the kit but nothing changed?** After the npx installer updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
 
 ### Mode: help
 
@@ -127,6 +127,10 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md` before acti
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/set-autonomy.md` before acting.
 
+### Mode: autonomy-doctor
+
+guarded — read `${CLAUDE_SKILL_DIR}/references/modes/autonomy-doctor.md` before acting.
+
 ### Mode: uninstall
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/uninstall.md` before acting.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/autonomy-doctor.md

@@ -0,0 +1,21 @@
+### Mode: autonomy-doctor
+
+The **sandbox provisioner "doctor"** — the answer to *"can this machine run the Claude sandbox, and can you fix it?"* (AD-044: macOS Seatbelt built-in / Linux+WSL2 `bwrap`+`socat` / native Windows → WSL2). **Division of labor:** YOU narrate the diagnosis and relay the consent question; the KIT does the deterministic detect → consent-gated install → verify. It is **guarded**: the privileged lane runs ONLY with the per-run consent tuple, always faces the harness permission prompt (the mode sits outside every velocity auto-approve tier), **never auto-runs, never writes repo files, and never commits**.
+
+Run **`node ${CLAUDE_SKILL_DIR}/tools/autonomy-doctor.mjs [--verify | --apply <pm>:<pkg[,pkg...]>]`**:
+
+1. **Flagless = FS-only preview** (the default; runs NO subprocesses): the diagnosis, the exact absolute-path command the doctor WOULD run, and the exact `--apply <pm>:<pkgs>` consent line. It **never claims "ready"** — binaries present without proof render `present-unverified`, never exit `0`.
+2. **`--verify`** — the unprivileged diagnostic: a `bwrap` user-namespace smoke plus `socat -V` (captured stdio). This is the ONLY source of a Linux **ready-verified** claim. Honesty split: a green verify proves the **OS primitives, not Claude-init** — the output always states the restart step. Under root/`SUDO_UID` the verified claim is REFUSED (`root-unproven`); a namespace-denied smoke with present binaries reports a loud `indeterminate` (nested sandboxing / already inside a container — re-run from an unsandboxed shell).
+3. **`--apply <pm>:<pkgs>`** — the consent-gated privileged install: the tuple must EQUAL the re-derived plan (consent binds to the previewed plan; a mismatch or a bare `--apply` refuses with `2` usage and runs NOTHING), the exact resolved command is re-printed immediately before execution, then the verify lane runs automatically. Sudo boundary: root drops sudo; a passwordless sudo proceeds with a LOUD note; a password-needing sudo without a controlling terminal runs NOTHING and prints the exact command to run in the USER's terminal (`handoff-required`).
+
+**Trust gate:** everything executed resolves to an ABSOLUTE path inside the fixed trusted dirs `/usr/bin:/bin:/usr/sbin:/sbin` (`/usr/local/bin` deliberately excluded); a binary or package manager found only outside is a loud `untrusted-path` / `unknown-pm` degrade, never executed. The privileged child gets a minimal scrubbed env (trusted-dir PATH + LANG), an argv array, no shell. Package names come from a frozen internal map (`bubblewrap`, `socat`); apt runs through the env trampoline (`env DEBIAN_FRONTEND=noninteractive …`) so non-interactivity survives sudo's `env_reset`.
+
+**Exit codes (frozen):** `0` ready (`ready-verified` / `ready-assumed`; Linux only via the verify oracle) · `1` precondition STOP (`no-deployment`) · `2` usage (bare `--apply`, tuple mismatch, unknown flag) · `3` not-ready diagnosis (`missing-binaries` offer / `present-unverified` / `handoff-required`) · `4` install failed (`install-failed`) · `5` verify failed (`verify-failed` / `indeterminate` / `root-unproven`) · `6` unsupported / untrusted (`unsupported-platform` win32 / `unknown-pm` / `untrusted-path`). The machine summary line prints LAST in every diagnosis outcome (`--help` prints the help text alone): `[autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>`.
+
+**Stamp EXEMPTION (stated, deliberate):** the doctor runs behind the docs/ai presence gate ahead of every lane (`--help` and parse-time usage errors return earlier) but has **NO `.workflow-version` stamp gate** — it provisions the OS, never lineage-bound repo content, so the global stale-deployment→upgrade routing does not apply to this mode.
+
+**Residuals (disclosed in the preview):** a root-owned hostile binary inside the trusted dirs is out of the threat model; Claude itself resolves `bwrap`/`socat` via PATH at session init (the doctor warns on a PATH shadow, never fixes PATH); the harness permission prompt shows the `--apply` tuple, not the absolute-path command — bridged by the apply-time re-print.
+
+Output is **English/structured** — **localize it to the user's conversational language** when you narrate.
+
+**Invariants:** guarded (the MUTATING lane only via `--apply` with the matching tuple, exactly once) · preview-first · never auto-runs · outside every velocity auto-approve tier · never writes repo files · never commits · loud degrades, never silent.

package/references/modes/doc-parity.md

@@ -9,7 +9,8 @@ The DOC-PARITY lint (BUGFREE-3 / AD-049, session-economics item (b)) — the det
 
 **What it checks (the closed registry).** The numeric/version tokens are IMPORTED live from the tools — never re-typed in the lint — so the registry itself can never go stale:
 - `references/modes/review-ledger.md` carries `SCHEMA_VERSION` (schema v4), `HARD_MAX` (the hard-max ceiling of 3), `DEFAULT_DIFF_CAP` (the default 400 diff cap), `REVIEW_CAP` (cap ≤2), and the ledger vocabulary sourced from the schema's own `V4_CLASSES` / `V4_OVERRIDE_SCOPES` Sets plus the `gate-run` kind (`size-cap`, `refuted`, `gate-run`, `red-proof`, `oracle-change`, `fixable-bug`, `inherent-layer-residual`, `escalate`);
-- `references/modes/fold-completeness.md` carries `RESULT_SCHEMA_VERSION` (fold RESULT schema v4).
+- `references/modes/fold-completeness.md` carries `RESULT_SCHEMA_VERSION` (fold RESULT schema v4);
+- `references/modes/autonomy-doctor.md` carries the doctor's frozen D7 contract (AD-044 Plan 2): every live EXIT-table phrase (`` `0` ready `` … `` `6` unsupported / untrusted ``), every status token (sourced from the exported `STATUS`), and the trusted-dir allowlist (`TRUSTED_DIRS`).
 
 **Why the modes/*.md docs and NOT the tool HELP strings.** Every tool's HELP INTERPOLATES the same constant (`the ${DEFAULT_DIFF_CAP}-line diff cap`), so it can never drift from the code — there is nothing to check there. The hand-authored contract prose in `references/modes/*.md` is the surface that DOES drift, so that is exactly what this lint pins. Change a constant and the current-value token stops appearing in the lagging doc → the gate fails, forcing the doc update **in the same edit as the code** (the §2.6 "contract docs change in the same edit as code" rule, mechanized).
 

package/tools/autonomy-doctor.mjs

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+// autonomy-doctor.mjs — the cross-platform sandbox provisioner "doctor" (AD-044 Plan 2; mode:
+// autonomy-doctor, GUARDED). Detect → consent-gated install → verify → loud degrade, for the
+// AD-044 sandbox matrix: macOS Seatbelt built-in / Linux+WSL2 bwrap+socat / native Windows → WSL2.
+//
+// THREE lanes:
+//   (flagless)          FS-only preview: diagnosis + the exact command it WOULD run + the exact
+//                       --apply consent tuple. ZERO subprocesses. Never claims "ready".
+//   --verify            unprivileged diagnostic: bwrap userns smoke + `socat -V` (captured stdio,
+//                       DIAGNOSTIC runner). The ONLY source of a Linux "ready (verified)" claim.
+//   --apply <pm>:<pkgs> consent-gated privileged install. The tuple must EQUAL the re-derived
+//                       plan (consent binds to the previewed plan; mismatch → refuse, runs
+//                       NOTHING), then the verify lane runs automatically.
+//
+// Trust gate (D2/D3): everything the doctor EXECUTES resolves to an ABSOLUTE path inside the
+// FIXED trusted dirs /usr/bin:/bin:/usr/sbin:/sbin (isExecutableFile — statSync follows an
+// in-dir symlink; /usr/local/bin deliberately excluded). A binary found only outside → loud
+// degrade naming its location, never executed. The privileged child gets a minimal SCRUBBED env
+// (trusted-dir PATH + LANG), argv array, no shell, stdio ['ignore','inherit','inherit'].
+//
+// Gating (D8): docs/ai deployment presence on EVERY run. NO .workflow-version stamp gate — the
+// doctor mutates the OS, never lineage-bound repo content (the stated stamp EXEMPTION).
+//
+// Exit codes (D7, frozen): 0 ready (ready-verified / ready-assumed; Linux only via the verify
+// oracle) · 1 precondition STOP (no-deployment) · 2 usage (bare --apply, tuple mismatch, unknown
+// flag) · 3 not-ready diagnosis (missing-binaries offer / present-unverified / handoff-required)
+// · 4 install failed · 5 verify failed / indeterminate / root-unproven · 6 unsupported/untrusted
+// (win32 / unknown PM / found-only-outside-trusted-dirs). The machine summary line prints LAST in
+// every diagnosis outcome (--help prints the help text alone):
+// [autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>.
+//
+// Residual disclosure (D9, shipped in the preview): (i) a root-owned hostile binary inside the
+// trusted dirs = the host is already lost (out of threat model); (ii) Claude itself resolves
+// bwrap/socat via PATH at session init — the doctor verifies the trusted-dir copies and WARNS on
+// a PATH shadow, never fixes it; (iii) the harness permission prompt shows the --apply tuple, not
+// the absolute-path command — bridged by the apply-time re-print of the exact resolved command.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { spawnSync } from 'node:child_process';
+import { closeSync, lstatSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isExecutableFile, probeSandboxAvailability } from './velocity-profile.mjs';
+import { assertDocsAiDeployment } from './atomic-write.mjs';
+
+// ── the frozen contract tables (fixtures the tests copy) ────────────────────────────
+
+export const TRUSTED_DIRS = Object.freeze(['/usr/bin', '/bin', '/usr/sbin', '/sbin']);
+const TRUSTED_PATH = TRUSTED_DIRS.join(':');
+
+// The closed world of sandbox binaries → package names. Keys double as the binary list (the
+// probe's SANDBOX_LINUX_BINARIES mirror); no repo/config/user input ever enters a command line.
+export const PACKAGE_FOR = Object.freeze({ bwrap: 'bubblewrap', socat: 'socat' });
+
+export const EXIT = Object.freeze({
+  ready: 0,
+  stop: 1,
+  usage: 2,
+  notReady: 3,
+  installFailed: 4,
+  verifyFailed: 5,
+  unsupported: 6,
+});
+
+export const STATUS = Object.freeze({
+  readyVerified: 'ready-verified',
+  readyAssumed: 'ready-assumed',
+  noDeployment: 'no-deployment',
+  usage: 'usage',
+  missingBinaries: 'missing-binaries',
+  presentUnverified: 'present-unverified',
+  handoffRequired: 'handoff-required',
+  installFailed: 'install-failed',
+  verifyFailed: 'verify-failed',
+  indeterminate: 'indeterminate',
+  rootUnproven: 'root-unproven',
+  unsupportedPlatform: 'unsupported-platform',
+  unknownPm: 'unknown-pm',
+  untrustedPath: 'untrusted-path',
+});
+
+export const EXIT_FOR_STATUS = Object.freeze({
+  [STATUS.readyVerified]: EXIT.ready,
+  [STATUS.readyAssumed]: EXIT.ready,
+  [STATUS.noDeployment]: EXIT.stop,
+  [STATUS.usage]: EXIT.usage,
+  [STATUS.missingBinaries]: EXIT.notReady,
+  [STATUS.presentUnverified]: EXIT.notReady,
+  [STATUS.handoffRequired]: EXIT.notReady,
+  [STATUS.installFailed]: EXIT.installFailed,
+  [STATUS.verifyFailed]: EXIT.verifyFailed,
+  [STATUS.indeterminate]: EXIT.verifyFailed,
+  [STATUS.rootUnproven]: EXIT.verifyFailed,
+  [STATUS.unsupportedPlatform]: EXIT.unsupported,
+  [STATUS.unknownPm]: EXIT.unsupported,
+  [STATUS.untrustedPath]: EXIT.unsupported,
+});
+
+// The MUTATING stdio contract: sudo prompts on /dev/tty (never stdin), no PM can block on stdin.
+export const MUTATING_STDIO = Object.freeze(['ignore', 'inherit', 'inherit']);
+
+// The frozen 4-family install map (D3, closed world). First-present in the trusted dirs wins.
+// Every executable token in the built argv is a D2-resolved ABSOLUTE trusted-dir path — apt's
+// non-interactivity rides the env TRAMPOLINE (env is the command sudo runs, so sudo env_reset
+// cannot strip DEBIAN_FRONTEND; a bare `apt-get` after env would hand resolution back to PATH).
+const PM_FAMILIES = Object.freeze([
+  Object.freeze({ name: 'apt-get', needsEnvTrampoline: true }),
+  Object.freeze({ name: 'dnf', needsEnvTrampoline: false }),
+  Object.freeze({ name: 'pacman', needsEnvTrampoline: false }),
+  Object.freeze({ name: 'apk', needsEnvTrampoline: false }),
+]);
+
+const buildFamilyArgv = (family, pmPath, envPath, packages) => {
+  if (family.name === 'apt-get') return [envPath, 'DEBIAN_FRONTEND=noninteractive', pmPath, 'install', '-y', ...packages];
+  if (family.name === 'dnf') return [pmPath, 'install', '-y', ...packages];
+  if (family.name === 'pacman') return [pmPath, '-S', '--needed', '--noconfirm', ...packages];
+  return [pmPath, 'add', ...packages];
+};
+
+// The bwrap userns smoke (D5) — HOST-PROVEN fixture 2026-07-10 (WSL2, bwrap 0.9.0): the payload is
+// process.execPath (injectable; `--ro-bind / /` makes it reachable — no /bin/true assumption).
+export const buildSmokeArgv = (bwrapPath, execPath) =>
+  Object.freeze([bwrapPath, '--unshare-all', '--die-with-parent', '--ro-bind', '/', '/', execPath, '--version']);
+
+// A smoke stderr that matches this WITH present binaries is the namespace-denied signature —
+// LOUD INDETERMINATE (nested sandboxing / already inside a container), never an install offer.
+const NAMESPACE_DENIED_RE = /operation not permitted|permission denied|no permissions to creat/i;
+
+const D9_DISCLOSURE = [
+  'Residual disclosure (D9):',
+  '  (i)  a root-owned hostile binary inside the trusted dirs means the host is already lost — out of this doctor\'s threat model.',
+  `  (ii) Claude itself resolves bwrap/socat via PATH at session init — the doctor verifies the trusted-dir copies (${TRUSTED_PATH}) and WARNS on a PATH shadow; it never fixes PATH.`,
+  '  (iii) the harness permission prompt shows the --apply <pm>:<pkgs> tuple, not the absolute-path command — bridged by the apply-time re-print of the exact resolved command.',
+];
+
+const RESTART_NOTE =
+  'Restart Claude Code now — the sandbox is detected only at session start; a fresh session is the behavioral proof.';
+const VERIFY_HONESTY =
+  'Honesty: a green verify proves the OS sandbox primitives (bwrap user namespaces + socat), NOT that Claude initialized its sandbox.';
+const WSL2_REDIRECT =
+  'native Windows is unsupported — run Claude Code inside WSL2 (Ubuntu) and re-run the doctor there.';
+const SEATBELT_NOTE = 'macOS: Seatbelt assumed built-in — not smoke-tested by this doctor.';
+
+const USAGE_HINT =
+  'usage: autonomy-doctor.mjs [--verify | --apply <pm>:<pkg[,pkg...]>]  (flagless = FS-only preview)';
+
+const HELP = `autonomy-doctor — sandbox provisioner doctor (detect → consent-gated install → verify).
+
+Usage:
+  node autonomy-doctor.mjs                      FS-only preview (diagnosis + the exact plan; runs NOTHING)
+  node autonomy-doctor.mjs --verify             unprivileged diagnostic: bwrap userns smoke + socat -V
+  node autonomy-doctor.mjs --apply <pm>:<pkgs>  consent-gated install (tuple must equal the previewed plan),
+                                                then the verify lane runs automatically
+  --help, -h                                    this help
+
+Consent contract: --apply REQUIRES the <pm>:<pkg,...> tuple the preview printed — a mismatch vs the
+re-derived plan refuses (exit 2) and runs NOTHING. Everything executed resolves to an absolute path
+inside the trusted dirs ${TRUSTED_PATH}; the exact resolved command is re-printed immediately
+before execution. The doctor never writes repo files and never commits.
+
+Exit codes: 0 ready (ready-verified / ready-assumed) · 1 precondition STOP (no docs/ai deployment) ·
+2 usage · 3 not-ready diagnosis · 4 install failed · 5 verify failed/indeterminate/root-unproven ·
+6 unsupported/untrusted. The last line of every diagnosis outcome is the machine summary:
+[autonomy-doctor] status=<token> platform=<p> missing=<csv> pm=<name|none>
+(--help prints this help text alone — no summary line.)`;
+
+// ── small pure helpers ───────────────────────────────────────────────────────────────
+
+const NO_MISSING = '-';
+export const composeSummaryLine = ({ status, platform, missing = [], pm = null }) =>
+  `[autonomy-doctor] status=${status} platform=${platform} missing=${missing.length > 0 ? missing.join(',') : NO_MISSING} pm=${pm ?? 'none'}`;
+
+const resolveTrusted = (name, isExec) => TRUSTED_DIRS.map((dir) => join(dir, name)).find((p) => isExec(p)) ?? null;
+
+const findFirstPathHit = (name, env, isExec) =>
+  ((env && env.PATH) || '').split(':').filter(Boolean).map((dir) => join(dir, name)).find((p) => isExec(p)) ?? null;
+
+export const hasControllingTerminal = () => {
+  try {
+    closeSync(openSync('/dev/tty', 'r'));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// ── the pure planner core (diagnosis + plan + tuple as DATA; no subprocesses) ─────────
+
+export const deriveDoctorPlan = ({ probeResult, env, isExec }) => {
+  const missing = probeResult.missing ?? [];
+  const packages = missing.map((binary) => PACKAGE_FOR[binary]);
+  const resolutions = Object.keys(PACKAGE_FOR).map((name) => {
+    const trusted = resolveTrusted(name, isExec);
+    const pathHit = findFirstPathHit(name, env, isExec);
+    return { name, trusted, pathHit, missing: missing.includes(name) };
+  });
+  const shadows = resolutions.filter((r) => !r.missing && r.trusted !== null && r.pathHit !== null && r.pathHit !== r.trusted);
+  const untrusted = resolutions.filter((r) => !r.missing && r.trusted === null);
+  const family = PM_FAMILIES.map((f) => ({ family: f, path: resolveTrusted(f.name, isExec) })).find((f) => f.path !== null) ?? null;
+  const envPath = resolveTrusted('env', isExec);
+  const pm = family === null ? null : { name: family.family.name, path: family.path };
+  const envMissing = family !== null && family.family.needsEnvTrampoline && envPath === null;
+  const tuple = pm !== null && missing.length > 0 ? `${pm.name}:${packages.join(',')}` : null;
+  const rootArgv = pm === null || missing.length === 0 || envMissing
+    ? null
+    : buildFamilyArgv(family.family, pm.path, envPath, packages);
+  return { missing, packages, resolutions, shadows, untrusted, pm, envMissing, tuple, rootArgv };
+};
+
+// ── argv parsing (usage errors carry exitCode 2 via the shared idiom) ─────────────────
+
+const usageFail = (message) => Object.assign(new Error(message), { exitCode: EXIT.usage });
+
+export const parseDoctorArgs = (argv) => {
+  let lane = 'preview';
+  let tuple = null;
+  const setLane = (next) => {
+    if (lane !== 'preview') throw usageFail('pass at most ONE of --verify / --apply');
+    lane = next;
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') return { lane: 'help', tuple: null };
+    if (arg === '--verify') setLane('verify');
+    else if (arg === '--apply' || arg.startsWith('--apply=')) {
+      const raw = arg === '--apply' ? argv[(i += 1)] : arg.slice('--apply='.length);
+      if (raw === undefined || raw === '' || raw.startsWith('--')) {
+        throw usageFail('--apply requires the consent tuple <pm>:<pkg[,pkg...]> the preview printed (a bare --apply is refused)');
+      }
+      if (!/^[^:\s]+:[^:\s]+$/.test(raw)) throw usageFail(`--apply tuple "${raw}" is not <pm>:<pkg[,pkg...]>`);
+      setLane('apply');
+      tuple = raw;
+    } else throw usageFail(`unknown flag: ${arg}`);
+  }
+  return { lane, tuple };
+};
+
+// ── rendering ─────────────────────────────────────────────────────────────────────────
+
+const renderDiagnosis = ({ plan, probeResult, log }) => {
+  log('autonomy-doctor — Linux sandbox diagnosis (bwrap + socat)');
+  log(`  probe: ${probeResult.reason}`);
+  for (const r of plan.resolutions) {
+    if (r.missing && r.trusted !== null) {
+      log(`  ${r.name}: NOT on PATH (the probe follows Claude's own PATH resolution) but present at ${r.trusted} — fix your PATH rather than re-installing.`);
+    } else if (r.missing) log(`  ${r.name}: MISSING`);
+    else if (r.trusted === null) {
+      log(`  ${r.name}: found ONLY at ${r.pathHit} — NOT in the trusted dirs (${TRUSTED_PATH}); the doctor will never execute it`);
+    } else log(`  ${r.name}: ${r.trusted}`);
+  }
+  for (const s of plan.shadows) {
+    log(`  PATH-SHADOW WARNING: ${s.name} first resolves on PATH at ${s.pathHit}, not the trusted ${s.trusted} — Claude will resolve the PATH one at session init (the D9 residual); the doctor verifies only the trusted copy.`);
+  }
+};
+
+// The untrusted degrade every lane runs FIRST (codex R1): while any sandbox binary resolves only
+// outside the trusted dirs, no offer, no consent invitation, and no privileged path may proceed —
+// an install cannot make such a host verify-ready.
+const refuseUntrusted = ({ plan, log }) => {
+  for (const r of plan.untrusted) {
+    log(`${r.name} found ONLY at ${r.pathHit} — NOT in the trusted dirs (${TRUSTED_PATH}); refusing every install/verify path until a trusted copy exists (loud degrade, D2).`);
+  }
+  return STATUS.untrustedPath;
+};
+
+// The install offer (flagless + --verify share it). Returns the status token for the missing case.
+const renderOffer = ({ plan, euid, isExec, env, log }) => {
+  if (plan.untrusted.length > 0) return refuseUntrusted({ plan, log });
+  if (plan.pm === null) {
+    const packages = plan.packages.join(' + ');
+    const outside = PM_FAMILIES
+      .map((f) => ({ name: f.name, hit: findFirstPathHit(f.name, env, isExec) }))
+      .filter((f) => f.hit !== null);
+    if (outside.length > 0) {
+      log(`package manager found ONLY outside the trusted dirs (${outside.map((f) => `${f.name} at ${f.hit}`).join('; ')}) — refusing to execute it (loud degrade, D3); install ${packages} manually, then re-run --verify.`);
+      return STATUS.untrustedPath;
+    }
+    log(`no supported package manager found in the trusted dirs (supported: ${PM_FAMILIES.map((f) => f.name).join(', ')}) — install ${packages} manually with your PM, then re-run --verify. (zypper et al. are deliberate omissions — a stated degrade, never a guess.)`);
+    return STATUS.unknownPm;
+  }
+  if (plan.envMissing) {
+    log(`env not found in the trusted dirs (${TRUSTED_PATH}) — the apt non-interactivity trampoline cannot be built; install ${plan.packages.join(' + ')} manually, then re-run --verify.`);
+    return STATUS.untrustedPath;
+  }
+  log(`  missing: ${plan.missing.join(', ')} → package(s): ${plan.packages.join(', ')} (via ${plan.pm.name})`);
+  const sudoTrusted = resolveTrusted('sudo', isExec);
+  const printedArgv = euid === 0 || sudoTrusted === null ? plan.rootArgv : [sudoTrusted, ...plan.rootArgv];
+  log('  with your consent the doctor WOULD run exactly:');
+  log(`    ${printedArgv.join(' ')}`);
+  if (euid !== 0 && sudoTrusted === null) {
+    const sudoOnPath = findFirstPathHit('sudo', env, isExec);
+    log(sudoOnPath === null
+      ? '  (no sudo in the trusted dirs — the command above is the ROOT form; run it as root)'
+      : `  (sudo found only at ${sudoOnPath} — NOT in the trusted dirs; the command above is the ROOT form)`);
+  }
+  log(`  consent: re-run with  --apply ${plan.tuple}   (the tuple binds consent to exactly this plan)`);
+  return STATUS.missingBinaries;
+};
+
+// ── the verify lane (D5 — the ONE ready predicate; shared by --verify and post-apply) ──
+
+const runVerifyLane = ({ plan, ctx }) => {
+  const { log, isExec, env, euid, execPath, diagnosticRunner, scrubbedEnv } = ctx;
+  if (plan.untrusted.length > 0) return refuseUntrusted({ plan, log });
+  if (plan.missing.length > 0) return renderOffer({ plan, euid, isExec, env, log });
+  if (euid === 0 || (env && env.SUDO_UID)) {
+    log('refusing the "verified" claim: running as root (euid 0 / SUDO_UID set) — a green smoke under root does NOT prove UNPRIVILEGED user namespaces. Re-run --verify as your normal user.');
+    return STATUS.rootUnproven;
+  }
+  const bwrapPath = plan.resolutions.find((r) => r.name === 'bwrap').trusted;
+  const socatPath = plan.resolutions.find((r) => r.name === 'socat').trusted;
+  const smoke = diagnosticRunner({ argv: [...buildSmokeArgv(bwrapPath, execPath)], env: scrubbedEnv, stdio: 'pipe' });
+  if (smoke.error) {
+    log(`bwrap smoke could not SPAWN (${smoke.error.code ?? smoke.error.message}) — the binary resolved but did not execute.`);
+    return STATUS.verifyFailed;
+  }
+  if (smoke.status !== 0) {
+    const stderr = smoke.stderr ?? '';
+    if (stderr) log(stderr.replace(/\n$/, ''));
+    if (NAMESPACE_DENIED_RE.test(stderr)) {
+      log('verify INDETERMINATE: the userns smoke was DENIED while the binaries are present — likely cause: nested sandboxing / already inside a container (a green probe cannot distinguish this). Re-run --verify from an unsandboxed shell.');
+      return STATUS.indeterminate;
+    }
+    log(`bwrap userns smoke FAILED (exit ${smoke.status}). The binaries are PRESENT — this is NOT an install problem, so re-installing will not fix it: check unprivileged user namespaces (userns sysctl / AppArmor restrictions) and that this host is WSL2, not WSL1.`);
+    return STATUS.verifyFailed;
+  }
+  const socat = diagnosticRunner({ argv: [socatPath, '-V'], env: scrubbedEnv, stdio: 'pipe' });
+  if (socat.error || socat.status !== 0) {
+    if (socat.stderr) log(socat.stderr.replace(/\n$/, ''));
+    log(socat.error
+      ? `socat -V could not SPAWN (${socat.error.code ?? socat.error.message}).`
+      : `socat -V FAILED (exit ${socat.status}) — the binary is present but not functional; not an install-missing problem.`);
+    return STATUS.verifyFailed;
+  }
+  log('ready (verified): probe green + bwrap userns smoke green + socat -V green — nothing to install.');
+  log(VERIFY_HONESTY);
+  log(RESTART_NOTE);
+  return STATUS.readyVerified;
+};
+
+// ── the apply lane (the ONE place the MUTATING runner may be invoked, exactly once) ───
+
+const runApplyLane = ({ plan, tuple, ctx }) => {
+  const { log, isExec, env, euid, diagnosticRunner, mutatingRunner, scrubbedEnv, isTTYOf } = ctx;
+  if (plan.untrusted.length > 0) return { status: refuseUntrusted({ plan, log }), finalPlan: plan };
+  if (plan.missing.length === 0) {
+    log(`consent REFUSED: the re-derived plan is EMPTY (nothing missing) — the tuple "${tuple}" matches no plan. Nothing was run or installed; run --verify for the ready proof.`);
+    return { status: STATUS.usage, finalPlan: plan };
+  }
+  if (plan.pm === null || plan.envMissing) return { status: renderOffer({ plan, euid, isExec, env, log }), finalPlan: plan };
+  if (tuple !== plan.tuple) {
+    log(`consent REFUSED: tuple mismatch — given "${tuple}", the current diagnosis derives "${plan.tuple}". Nothing was run; re-run flagless to preview, then --apply with the derived tuple.`);
+    return { status: STATUS.usage, finalPlan: plan };
+  }
+  let execArgv = plan.rootArgv;
+  if (euid !== 0) {
+    const sudoTrusted = resolveTrusted('sudo', isExec);
+    if (sudoTrusted === null) {
+      const sudoOnPath = findFirstPathHit('sudo', env, isExec);
+      if (sudoOnPath !== null) {
+        log(`sudo found ONLY at ${sudoOnPath} — NOT in the trusted dirs (${TRUSTED_PATH}); refusing to execute it.`);
+        return { status: STATUS.untrustedPath, finalPlan: plan };
+      }
+      log('sudo is not available — run this as ROOT in your terminal, then re-run --verify:');
+      log(`  ${plan.rootArgv.join(' ')}`);
+      return { status: STATUS.handoffRequired, finalPlan: plan };
+    }
+    const preflight = diagnosticRunner({ argv: [sudoTrusted, '-n', 'true'], env: scrubbedEnv, stdio: 'pipe' });
+    const preflightGreen = !preflight.error && preflight.status === 0;
+    if (preflightGreen) {
+      log('sudo will run WITHOUT a password prompt (cached credentials or NOPASSWD) — the install proceeds non-interactively.');
+    } else if (!isTTYOf()) {
+      log('sudo needs a password and there is NO controlling terminal — running NOTHING. Run this in YOUR terminal, then re-run --verify:');
+      log(`  ${[sudoTrusted, ...plan.rootArgv].join(' ')}`);
+      return { status: STATUS.handoffRequired, finalPlan: plan };
+    } else {
+      log('sudo will prompt for your password on your terminal.');
+    }
+    execArgv = [sudoTrusted, ...plan.rootArgv];
+  }
+  log('executing EXACTLY (every token trusted-dir absolute):');
+  log(`  ${execArgv.join(' ')}`);
+  const res = mutatingRunner({ argv: execArgv, env: scrubbedEnv, stdio: [...MUTATING_STDIO] });
+  if (res.error || res.status !== 0) {
+    log(res.error
+      ? `install could not SPAWN (${res.error.code ?? res.error.message}).`
+      : `install FAILED (exit ${res.status}) — see the package manager output above (stderr was inherited). A stale package index is one possible cause (the doctor never refreshes indexes — run your PM's update by hand if so).`);
+    return { status: STATUS.installFailed, finalPlan: plan };
+  }
+  log('install completed — running the verify lane...');
+  const freshProbe = ctx.probe();
+  const freshPlan = deriveDoctorPlan({ probeResult: freshProbe, env, isExec });
+  return { status: runVerifyLane({ plan: freshPlan, ctx }), finalPlan: freshPlan };
+};
+
+// ── default runners (the ONE real-process boundary; injectable for hermetic tests) ────
+
+export const runDiagnosticSpawn = (descriptor) =>
+  spawnSync(descriptor.argv[0], descriptor.argv.slice(1), { env: descriptor.env, encoding: 'utf8', stdio: 'pipe' });
+export const runMutatingSpawn = (descriptor) =>
+  spawnSync(descriptor.argv[0], descriptor.argv.slice(1), { env: descriptor.env, stdio: descriptor.stdio });
+
+// ── main(argv, deps) → exit code ──────────────────────────────────────────────────────
+
+export const main = (argv, deps = {}) => {
+  const log = deps.log ?? console.log;
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  const cwd = deps.cwd ?? process.cwd();
+  const lstat = deps.lstat ?? lstatSync;
+  const isExec = deps.isExecutable ?? isExecutableFile;
+  const execPath = deps.execPath ?? process.execPath;
+  const diagnosticRunner = deps.diagnosticRunner ?? runDiagnosticSpawn;
+  const mutatingRunner = deps.mutatingRunner ?? runMutatingSpawn;
+  const probe = deps.probe ?? (() => probeSandboxAvailability({ platform, env, isExecutable: isExec }));
+  const euidOf = deps.euid ?? (() => process.geteuid?.());
+  const isTTYOf = () => deps.isTTY ?? hasControllingTerminal();
+
+  const finish = (status, plan = null) => {
+    log(composeSummaryLine({ status, platform, missing: plan?.missing ?? [], pm: plan?.pm?.name ?? null }));
+    return EXIT_FOR_STATUS[status];
+  };
+
+  let parsed;
+  try {
+    parsed = parseDoctorArgs(argv);
+  } catch (err) {
+    log(`autonomy-doctor: ${err.message}`);
+    log(USAGE_HINT);
+    return finish(STATUS.usage);
+  }
+  if (parsed.lane === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  try {
+    assertDocsAiDeployment(cwd, { lstat }, { noun: 'anything', rel: 'anything here' });
+  } catch (err) {
+    log(`precondition STOP — ${err.message}`);
+    return finish(STATUS.noDeployment);
+  }
+
+  if (platform === 'win32') {
+    log(WSL2_REDIRECT);
+    return finish(STATUS.unsupportedPlatform);
+  }
+  if (platform === 'darwin') {
+    if (parsed.lane === 'apply') {
+      log(`consent REFUSED: nothing to install on macOS (Seatbelt is built-in) — the tuple "${parsed.tuple}" matches no plan. Nothing was run.`);
+      return finish(STATUS.usage);
+    }
+    log(SEATBELT_NOTE);
+    return finish(STATUS.readyAssumed);
+  }
+  if (platform !== 'linux') {
+    log(`native ${platform} sandbox unsupported — use WSL2 on Windows.`);
+    return finish(STATUS.unsupportedPlatform);
+  }
+
+  // Linux from here; euid resolves LAZILY after the platform gate (process.geteuid is win32-absent).
+  const euid = euidOf();
+  const probeResult = probe();
+  const plan = deriveDoctorPlan({ probeResult, env, isExec });
+  const scrubbedEnv = { PATH: TRUSTED_PATH, ...(env && env.LANG ? { LANG: env.LANG } : {}) };
+  const ctx = { log, isExec, env, euid, execPath, diagnosticRunner, mutatingRunner, scrubbedEnv, isTTYOf, probe };
+
+  renderDiagnosis({ plan, probeResult, log });
+
+  if (parsed.lane === 'preview') {
+    let status;
+    if (plan.untrusted.length > 0) status = refuseUntrusted({ plan, log });
+    else if (plan.missing.length > 0) status = renderOffer({ plan, euid, isExec, env, log });
+    else {
+      log('  state: binaries present but UNVERIFIED — the flagless preview never claims ready; run --verify for the ready proof.');
+      status = STATUS.presentUnverified;
+    }
+    for (const line of D9_DISCLOSURE) log(line);
+    return finish(status, plan);
+  }
+  if (parsed.lane === 'verify') return finish(runVerifyLane({ plan, ctx }), plan);
+  const applied = runApplyLane({ plan, tuple: parsed.tuple, ctx });
+  return finish(applied.status, applied.finalPlan);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exit(main(process.argv.slice(2)));

package/tools/commands.mjs

@@ -28,7 +28,7 @@ const invocationOf = (token) => `${BARE_INVOCATION}${token ? ` ${token}` : ''}`;
 // ── kinds ────────────────────────────────────────────────────────────────────────
 // read-only    — never writes, never commits, never runs a subscription CLI.
 // writer       — writes files (a project deployment or a settings/skill placement).
-// guarded      — a destructive teardown gated behind a mandatory dry-run-first + explicit consent.
+// guarded      — consent-gated destructive/privileged actions (dry-run-first + explicit consent).
 // project-exec — the kit itself writes nothing, but the mode RUNS the project's own declared
 //                commands with the caller's privileges (the `gates` runner) — honest-tagged so a
 //                user never reads "read-only" on a surface that executes their gate matrix.
@@ -140,6 +140,13 @@ const CATALOG = [
     kind: GUARDED,
     oneLine: 'Read or change the host-level bridge settings (e.g. the codex Fast tier) — a KEY=VALUE file that survives kit upgrades; previews first, and the Fast tier carries its extra-cost caveat.',
   },
+  {
+    key: 'autonomy-doctor',
+    invocation: invocationOf('autonomy-doctor'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Check whether this machine can run the Claude sandbox and, only with your explicit consent, install what is missing — privileged, preview-first, consent-per-run; it never auto-runs and never commits.',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -274,7 +281,7 @@ export const formatHelp = () => {
   const lines = [
     `${SKILL_NAME} — command index (this list is read-only)`,
     '',
-    'Each command is tagged read-only · writer (makes changes) · guarded (destructive, previews first) · runs project cmds (executes your own declared commands).',
+    'Each command is tagged read-only · writer (makes changes) · guarded (consent-gated destructive/privileged actions, previews first) · runs project cmds (executes your own declared commands).',
   ];
   for (const group of GROUP_ORDER) {
     const inGroup = COMMANDS.filter((c) => c.group === group);

package/tools/doc-parity.mjs

@@ -26,11 +26,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './review-ledger.mjs';
 import { HARD_MAX, DEFAULT_DIFF_CAP } from './review-ledger-write.mjs';
 import { RESULT_SCHEMA_VERSION } from './fold-completeness.mjs';
+import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
 const REVIEW_LEDGER_DOC = 'references/modes/review-ledger.md';
 const FOLD_DOC = 'references/modes/fold-completeness.md';
+const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -45,6 +47,19 @@ const valueBinding = (constant, value, phrase, files) => ({ constant, value, tok
 // so the closed set can never disagree with the code. Every word must appear in the ledger contract.
 const LEDGER_VOCAB = [...V4_CLASSES, ...V4_OVERRIDE_SCOPES, 'gate-run'];
 
+// The autonomy-doctor D7 contract (AD-044 Plan 2): the live EXIT table + every status token must
+// render into the mode's contract doc. `usage` is skipped as a bare-word token (trivially present
+// everywhere) — its exit-code phrase below pins that outcome instead.
+const DOCTOR_EXIT_PHRASES = [
+  ['ready', `\`${DOCTOR_EXIT.ready}\` ready`],
+  ['stop', `\`${DOCTOR_EXIT.stop}\` precondition STOP`],
+  ['usage', `\`${DOCTOR_EXIT.usage}\` usage`],
+  ['notReady', `\`${DOCTOR_EXIT.notReady}\` not-ready diagnosis`],
+  ['installFailed', `\`${DOCTOR_EXIT.installFailed}\` install failed`],
+  ['verifyFailed', `\`${DOCTOR_EXIT.verifyFailed}\` verify failed`],
+  ['unsupported', `\`${DOCTOR_EXIT.unsupported}\` unsupported / untrusted`],
+];
+
 export const BINDINGS = Object.freeze([
   valueBinding('SCHEMA_VERSION', SCHEMA_VERSION, `schema v${SCHEMA_VERSION}`, [REVIEW_LEDGER_DOC]),
   valueBinding('HARD_MAX', HARD_MAX, `hard-max ceiling of ${HARD_MAX}`, [REVIEW_LEDGER_DOC]),
@@ -52,6 +67,11 @@ export const BINDINGS = Object.freeze([
   valueBinding('REVIEW_CAP', REVIEW_CAP, `cap ≤${REVIEW_CAP}`, [REVIEW_LEDGER_DOC]),
   valueBinding('RESULT_SCHEMA_VERSION', RESULT_SCHEMA_VERSION, `schema v${RESULT_SCHEMA_VERSION}`, [FOLD_DOC]),
   ...LEDGER_VOCAB.map((word) => valueBinding(`vocab:${word}`, word, word, [REVIEW_LEDGER_DOC])),
+  ...DOCTOR_EXIT_PHRASES.map(([key, phrase]) => valueBinding(`doctor-exit:${key}`, DOCTOR_EXIT[key], phrase, [AUTONOMY_DOCTOR_DOC])),
+  ...Object.values(DOCTOR_STATUS)
+    .filter((token) => token !== DOCTOR_STATUS.usage)
+    .map((token) => valueBinding(`doctor-status:${token}`, token, token, [AUTONOMY_DOCTOR_DOC])),
+  valueBinding('doctor-trusted-dirs', DOCTOR_TRUSTED_DIRS.join(':'), DOCTOR_TRUSTED_DIRS.join(':'), [AUTONOMY_DOCTOR_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -96,8 +116,9 @@ Usage:
   node doc-parity.mjs [--check | --json]
 
 A CLOSED, exported registry binds each live code constant (review-ledger SCHEMA_VERSION / REVIEW_CAP,
-review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION) and the
-ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run) to the exact token its
+review-ledger-write HARD_MAX / DEFAULT_DIFF_CAP, fold-completeness RESULT_SCHEMA_VERSION), the
+ledger vocabulary (V4_CLASSES / V4_OVERRIDE_SCOPES + gate-run), and the autonomy-doctor contract
+(the EXIT table, the status tokens, the trusted-dir allowlist) to the exact token its
 references/modes/*.md contract must carry, and asserts the CURRENT value renders into every bound
 file. A drifted doc, an unreadable bound file, or an absent token FAILS CLOSED.
 

package/tools/velocity-profile.mjs

@@ -838,7 +838,8 @@ const AUTONOMY_RESIDUAL_NOTICE =
 // isExecutableFile — true iff `p` is a REGULAR file with an execute bit (statSync FOLLOWS a symlink, so
 // a symlinked binary resolves to its target). A directory or a non-executable file NAMED bwrap/socat
 // must NOT count as the binary (else the loud sandbox-unavailable degrade would be wrongly suppressed).
-const isExecutableFile = (p) => {
+// Exported (AD-044 Plan 2): autonomy-doctor.mjs promotes this to its trusted-dir execution gate.
+export const isExecutableFile = (p) => {
   try {
     const st = statSync(p);
     return st.isFile() && (st.mode & 0o111) !== 0;
@@ -929,7 +930,7 @@ export const renderAutonomySettings = (resolved, probe) => {
   // sandbox availability (Step 3.3 probe) — a LOUD degrade where the OS can't sandbox; the red-lines +
   // defaultMode still land (they are permission rules, sandbox-independent).
   if (!probe.available) {
-    degrades.push(`sandbox UNAVAILABLE on this host (${probe.reason}) — claude renders the sandbox block but WARNS and runs UNSANDBOXED: ad-hoc scripts will still PROMPT and network/fs confinement is NOT enforced until it is available (Plan 2 offers to install the missing dependency). The red-lines + defaultMode still apply. failIfUnavailable is left UNSET so the session is never bricked.`);
+    degrades.push(`sandbox UNAVAILABLE on this host (${probe.reason}) — claude renders the sandbox block but WARNS and runs UNSANDBOXED: ad-hoc scripts will still PROMPT and network/fs confinement is NOT enforced until it is available (run /agent-workflow-kit autonomy-doctor to diagnose and, with your consent, install the missing dependency). The red-lines + defaultMode still apply. failIfUnavailable is left UNSET so the session is never bricked.`);
   }
   return { level, activities: resolved.activities, sandbox, defaultMode, ask, deny, notes, degrades };
 };