@sabaiway/agent-workflow-kit 1.43.0 → 1.45.0

package/references/shared/composition-handoff.md

@@ -3,40 +3,45 @@
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
-  `docs/ai/` + `AGENTS.md` (carrying the **two empty pointer pairs** — `workflow:methodology` and
-  `workflow:orchestration`) + **`.memory-version`**. The kit then **reconciles both bounded pointers**
-  (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
+  `docs/ai/` + `AGENTS.md` (carrying the **three empty pointer pairs** — `workflow:methodology`,
+  `workflow:orchestration` and `workflow:autonomy`) + **`.memory-version`**. The kit then **reconciles
+  the bounded pointers** (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
   hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (bootstrap step 9 — `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`), which **absorbs
   memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
   the external footprint — so there is **no machine-global write** at any step (a stale memory's
   residual global block is cleaned via the upgrade reconcile, below).
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) from its own
-  bundled assets — whose entry-point template now ships **two empty pointer pairs** (`workflow:methodology`
-  + `workflow:orchestration`) the kit reconciles + fills — and writes **`.workflow-version`** only.
+  bundled assets — whose entry-point template now ships **three empty pointer pairs** (`workflow:methodology`
+  + `workflow:orchestration` + `workflow:autonomy`) the kit reconciles + fills — and writes **`.workflow-version`** only.
   Softly suggest installing `agent-workflow-memory` — never a prerequisite.
 
 **Bounded pointer reconciliation (the kit is the ONLY writer of these slots).** After `AGENTS.md`
 exists, run ONE command — `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile
-<project>/AGENTS.md` — which reconciles **two** bounded pointers in a single atomic write: the
-**workflow-methodology** pointer (the plan → execute → review summary) **and**, right below it, the
+<project>/AGENTS.md` — which reconciles **three** bounded pointers in a single atomic write: the
+**workflow-methodology** pointer (the plan → execute → review summary), the
 **orchestration-recipes** pointer (the Solo / Reviewed / Council / Delegated vocabulary, routing to
-`/agent-workflow-kit recipes`). Each is **one atomic operation per slot**: **ensure the slot exists**
+`/agent-workflow-kit recipes`) right below it, and the **autonomy-policy** pointer (the
+`docs/ai/autonomy.json` read contract) below that. Each is **one atomic operation per slot**:
+**ensure the slot exists**
 (insert an empty marker pair at its anchor when a legacy entry point lacks one) → **inject the bounded
 fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved verbatim) →
-**cap-check** (the second pointer's check runs on the file *after* the first, so it guards the
-**combined** ≤100-line budget). Both fragments are short summary + pointer, read **live from the
-installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`,
+**cap-check** (each chained pointer's check runs on the file *after* the previous one, so it guards the
+**combined** ≤100-line budget). The fragments are short summary + pointer, read **live from the
+installed `agent-workflow-engine`** (`references/methodology-slot.md` + `references/orchestration-slot.md`
++ `references/autonomy-slot.md`,
 the family's one source of truth) — **not** a bundled mirror, and **not** the full references. The
 live read is **lazy + fail-loud**: the engine is consulted **only when a slot actually needs filling**,
-so a deployment whose pointers are already filled reconciles to a zero-diff no-op even on a host
-without the engine; but when a fill **is** needed and the engine is **absent/invalid**, reconcile
+so a deployment with **all three** pointers filled reconciles to a zero-diff no-op even on a host
+without the engine (one still missing the autonomy pair needs the engine to gain it); when a fill
+**is** needed and the engine is **absent/invalid**, reconcile
 **STOPs** — report it in plain language with the one-line install command
 `npx @sabaiway/agent-workflow-engine@latest init` (`npx @sabaiway/agent-workflow-kit@latest init`
 installs the engine for you; translate, never leak tool internals). Contract per slot: exactly one
 ordered `start → end` pair; a malformed slot (single, reversed, nested, duplicate) or a missing /
-duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). The
-**orchestration pointer is soft-skipped** (reported, never silent) when — and only when — adding it
-would exceed the 100-line cap: the methodology pointer still lands and the upgrade continues.
+duplicate anchor → **STOP with an error**, never edit (the file is left byte-for-byte unchanged). A
+**chained pointer is soft-skipped** (reported, never silent) when — and only when — adding it would
+exceed the 100-line cap, the engine is too old to ship its fragment, or (autonomy only) its anchor
+(the orchestration pair) is absent: every prior pointer still lands and the upgrade continues.
 
 **Agent-rules lens refresh (runs in BOTH paths).** Its precondition is its own target file — run it
 only after `<project>/docs/ai/agent_rules.md` exists: after the substrate deploy in the

package/references/shared/report-footer.md

@@ -9,7 +9,11 @@ The tool runs the backend detector and appends the recipe recommendation itself
 recipe clause of its own, ever.
 
 - **Placeholder template (structure only — never copy this example; paste the tool's line):**
-  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes`
+  `backends: <alias> <✓|✗> <readiness> · <alias> <✓|✗> <readiness> — run /agent-workflow-kit backends · recipes: <recommendation clause> — see /agent-workflow-kit recipes · autonomy: <per-activity levels> (<policy state>)`
+- The **`autonomy:` segment is appended by the composer itself** (`composeAutonomyFacts`, AD-044) —
+  per-activity levels + the policy state (computed defaults / declared / MALFORMED, loud) — the
+  agent never types it; the composer resolves the policy from the project root, so the line is
+  correct from any working directory inside the project.
 - The **`recipes:` clause is appended after** the `— run /agent-workflow-kit backends` pointer (never
   replacing it) and routes to the read-only `recipes` mode (`see /agent-workflow-kit recipes`). It is
   **never blank**: both backends ready → *"Council available, Reviewed the everyday default"*; one

package/references/templates/AGENTS.md

@@ -57,6 +57,8 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 <!-- workflow:methodology:end -->
 <!-- workflow:orchestration:start -->
 <!-- workflow:orchestration:end -->
+<!-- workflow:autonomy:start -->
+<!-- workflow:autonomy:end -->
 
 ---
 
@@ -68,7 +70,6 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 | No `any` / no unsafe casts | Linter / type-checker |
 | Functional style (no mutation in app code) | Linter |
 | Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
-| No hardcoded colors — design tokens only | Code review |
 | No business logic in components → hooks/services | Architecture review |
 | No changes without tests (TDD) | Required |
 | Check page docs before changes; update them after | Process |

package/references/templates/autonomy.json

@@ -0,0 +1,3 @@
+{
+  "_README": "Per-project autonomy policy: red-lines (always) + per-activity autonomy level. Hand-editable; or use the set-autonomy writer (previews, then writes valid JSON). Strict JSON — no comments."
+}

package/tools/autonomy-config.mjs

@@ -236,6 +236,15 @@ export const resolveAutonomy = (config) => {
   return { redlines, activities };
 };
 
+// isSparseSeedConfig(config) → true when the policy file is STRUCTURALLY the deploy seed: meta keys
+// only (`_README` today) — no red-lines section, no activity entry. Seed detection must be
+// structural, never resolved-equality: an EXPLICIT policy that declares exactly the default values
+// is a real DECLARATION (its render — the red-line ask rules included — must not be suppressed as
+// "just the seed"), while the seed declares nothing (codex, Segment B closing). Shared by every
+// autonomy read surface (advisor / recipes / procedures / grounding) so the four can never diverge.
+export const isSparseSeedConfig = (config) =>
+  isJsonObject(config) && Object.keys(config).every((k) => k.startsWith('_'));
+
 // ── pure merge + canonical serialization ────────────────────────────────────────────
 
 // A pure deep-equal over the JSON-ish policy shape (plain objects + string values). Used only for the
@@ -288,9 +297,10 @@ export const serializeAutonomy = (config) => {
 
 // ── the canonical seed (Decision 5) ──────────────────────────────────────────────────
 // AUTONOMY_README is the onboarding note; SEED_AUTONOMY is the Decision-5 fixture the set-autonomy
-// writer seeds and the config tests copy/validate verbatim. Plan 1 ships NO references/templates/
-// autonomy.json and NO template-parity test (both Plan 4) — SEED_AUTONOMY's Plan-1 consumers are the
-// autonomy-config tests and the render's "seed one first" guidance.
+// WRITER seeds (opinionated sandbox levels) and the config tests copy/validate verbatim. DISTINCT
+// from the Plan-4 deploy template `references/templates/autonomy.json` (bootstrap/upgrade ensure):
+// that seed is SPARSE — `_README` only, defaults-equivalent by the template-parity pin
+// (resolveAutonomy(template) ≡ resolveAutonomy(null)) — so deploying it never changes behavior.
 export const AUTONOMY_README =
   'Per-project autonomy policy: red-lines (always) + per-activity autonomy level. Hand-editable; or ' +
   'use the set-autonomy writer (previews, then writes valid JSON). Strict JSON — no comments.';

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)));