@sabaiway/agent-workflow-kit 1.43.0 → 1.45.0

package/CHANGELOG.md

@@ -4,6 +4,105 @@ 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.45.0 — Autonomy series close: upgrade Recommendations, bridge-wrappers tier, review-domain mask fix (AD-044 Plan 4)
+
+A **feature** release closing the AD-044 autonomy series (ships with memory 2.1.0, engine 1.15.0,
+bridges 2.4.0; the deployment lineage head stays `2.0.0` — the new seed is ensure-if-missing,
+stamp-independent). Three maintainer pains land as product:
+
+- **`recommendations` mode — the mandatory upgrade advisor.** Read-only `recommendations.mjs`
+  renders a frozen 12-item registry as `{what is sub-optimal · one-line fact-true benefit · exact
+  apply one-liner}`; every `upgrade` run now ENDS with the section on BOTH exits (equal-head and
+  re-stamp), present-even-when-empty ("no recommendations — flow optimal."), BEFORE the report
+  footer and commit ask. Apply lines are PURE executable commands, cwd-independent (absolute
+  paths, pinned `--cwd`); probes degrade to stated skipped-item lines — an unreadable bundled
+  manifest or an uncaveated unknown-freshness row is a stated skip, a stray bundle-root file is
+  ignored, a duplicate-carrying bridge-settings file renders fix-duplicates-first instead of the
+  writer command it would refuse. The network-allowlist item is HAND-APPLY by design: the kit
+  never seeds `sandbox.network.allowedDomains`; hosts derive from the bridges' manifest
+  `networkHosts`, the paste value is PROJECT scope ∪ missing (a local-scope allowance counts
+  toward coverage but never widens into the committed file), and the item renders only on the
+  full two-surface tier proof. Autonomy facts resolve from the PROJECT ROOT on every paste
+  surface, and seed detection is STRUCTURAL via the shared `isSparseSeedConfig` predicate on all
+  four surfaces (an explicit declared-defaults policy still gets its render nudge — the red-line
+  ask rules ride the render).
+- **`--bridge-tier` velocity lane — unattended council runs.** A frozen tier seeds, behind its own
+  consent flag, BOTH surfaces a promptless review run needs: `permissions.allow` prefix rules for
+  the review wrappers' CODE mode only (`Bash(codex-review code:*)`, `Bash(agy-review code:*)` —
+  plan/diff modes and the exec wrappers keep their human prompt) + the wrapper names in
+  `sandbox.excludedCommands` (the harness runs those outside the sandbox — no agent-side bypass).
+  The grounding pre-step rule seeds in the EXACT double-quoted byte-form the procedures advisor
+  renders (byte-parity pinned; derives only when agy-review is placed). Tier entries register at
+  all three audit points — the audit never flags an entry the tier itself seeded. The
+  exfiltration posture is INFORMED CONSENT, notice-pinned; the invocation-shape contract is
+  stated (prefix rules match only PLAIN invocations). `grounding --out` hardened: temp-only
+  outside-repo, create-only + exclusive fresh in-repo, non-regular-leaf refusals.
+- **Review-domain device-mask fix + `sandbox-masks` lane.** Never-committable stat classes
+  (char/block devices, FIFOs, sockets) are filtered out of the ENTIRE review domain in lockstep —
+  node fingerprint/isTreeClean + both bash twins' payload, diff assembly and preflights + parity —
+  so the sandbox-mask fingerprint-divergence class is dead BY CONSTRUCTION (untracked symlinks and
+  directories/gitlinks stay in the domain). The GUARDED `sandbox-masks` tool adds the cosmetic
+  lane: read-only probe (derives/revalidates, refuses every non-mask class) + consent-gated
+  `--apply` full-block REPLACE of its own fence in `git-path info/exclude` (a stale-real-only
+  fence renders the `--clear` form on every surface); `review-state --check` advises the exact
+  one-liner when masks are visible. Honest residual: REGULAR fake-file injection is a new design
+  round if it appears.
+- **Autonomy surfacing + seeds.** `recipes --status-line/--json/--active-line`, `set-recipe` echo
+  and `procedures` gained autonomy segments rendered from `resolveAutonomy` (MALFORMED-loud on
+  every paste surface; `procedures` also exits 1 on a malformed policy while still rendering);
+  the sparse defaults-equivalent `autonomy.json` template mirrors from memory; bootstrap seeds it,
+  upgrade ensures-if-missing. Manifests gained consult-locked `networkHosts` (observed-minimal
+  INCLUDING apex domains; validated by `--strict`; synthetic examples in schema.md); velocity.md
+  carries the honesty matrix (settings sandbox keys are INERT under harness-managed sandboxes —
+  live-observed). Tarball sentinel 145→150; router/read-set budgets took documented KB bumps.
+
+## 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

@@ -236,15 +236,18 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). `--await [--timeout <s>]` (AD-049) BLOCKS until every recipe-named backend has receipted the current tree — the durable completion signal is the receipt, never a process event — so you wait for the bridges instead of hand-polling. Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
-| `/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 sandbox-masks` | any time | **cosmetic exclude lane for sandbox device masks** — an OS sandbox (Claude Code) injects character-device masks into the work tree as untracked `git status` noise; the review domain already ignores them **by construction** (never-committable untracked classes — char/block devices, FIFOs, sockets — are excluded from the fingerprint, the assembled review payload, and the clean checks). This mode hides them from `git status` too: flagless = read-only probe (derives the CURRENT mask set from the unfiltered walk + lstat — never a frozen list — and revalidates fenced entries, loudly flagging one that became a real path); `--apply` = consent-gated FULL-BLOCK replace of its own fenced block in `git rev-parse --git-path info/exclude` (stale masks drop by construction; `--clear` always means REMOVE the block — it takes precedence over the derivation). Writes ONLY its fence — never `.gitignore`, never global config; symlinked/non-regular exclude paths and malformed fences fail closed. Watch note: a real file at an excluded path is silently skipped by bulk staging (`git add -A`/`git add .`) — delete the stale line first; the probe flags exactly this case. |
+| `/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. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). `--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** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all 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 recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter) and renders each item as **{what · one-line benefit · the exact consent-gated apply one-liner}**; the agent pastes the section **verbatim** and runs EXACTLY the rendered one-liners only on your yes. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Benefit lines are fact-true frozen data (the bridge-wrappers item claims velocity only; risk-bearing items state their risk inline); the network-allowlist item is **HAND-APPLY** — the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (the hosts are documented per bridge in `capability.json` `networkHosts`). `--cwd` is required (the target project is explicit); 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.
 
@@ -283,8 +286,9 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
 
 - **Delegates** substrate deployment to **`@sabaiway/agent-workflow-memory`** when a healthy
   standalone copy is present, else uses its **bundled fallback** — same `docs/ai/` either way.
-- **Injects** two bounded pointers into the deployed `AGENTS.md` — the workflow **methodology** and the
-  **orchestration recipes** (Solo / Reviewed / Council / Delegated) — read **live** from the installed
+- **Injects** three bounded pointers into the deployed `AGENTS.md` — the workflow **methodology**, the
+  **orchestration recipes** (Solo / Reviewed / Council / Delegated), and the **autonomy policy** (the
+  `docs/ai/autonomy.json` read contract) — read **live** from the installed
   **`agent-workflow-engine`** (the canonical narrative; a published member, never one of the shipped
   backends). `/agent-workflow-kit recipes` surfaces + plans a recipe for your environment, read-only.
 - **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm;

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.45.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
 
@@ -111,6 +111,10 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/setup.md` before acting.
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/status.md` before acting.
 
+### Mode: recommendations
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md` before acting.
+
 ### Mode: recipes
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/recipes.md` before acting.
@@ -127,6 +131,14 @@ 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: sandbox-masks
+
+guarded — read `${CLAUDE_SKILL_DIR}/references/modes/sandbox-masks.md` before acting.
+
 ### Mode: uninstall
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/uninstall.md` before acting.

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.3.0'
+  version: '2.4.0'
 ---
 
 # antigravity-cli-bridge

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -79,7 +79,9 @@ Receipt:
   <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside
   a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical
   uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the
-  review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict
+  review-payload domain; never-committable untracked paths — character/block devices, FIFOs,
+  sockets — are excluded from the domain entirely, untracked symlinks/directories ride as
+  name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict
   recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK);
   grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records
   grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts
@@ -192,7 +194,7 @@ DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="2.3.0"
+AW_BRIDGE_VERSION="2.4.0"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable warning.
@@ -306,11 +308,76 @@ sha256_stdin() {
   fi
 }
 
+# Never-committable untracked stat class (Decision 1, AD-044 Plan 4): character/block devices,
+# FIFOs, sockets — git content can never carry them, so they are excluded from the ENTIRE review
+# domain (fingerprint payload, assembled change set, status section, no-diff preflight). Symlinks
+# (checked first, never followed) and directories (an embedded repo lists as `dir/` — a committable
+# gitlink) STAY in the domain. The class surfaces where a sandbox injects device masks whose dirent
+# LIES to git's walk; the stat here sees the truth.
+is_never_committable_untracked() {
+  [[ ! -L "$1" && ( -p "$1" || -S "$1" || -c "$1" || -b "$1" ) ]]
+}
+
+# The ONE untracked-not-ignored walk every review-domain surface iterates (fingerprint payload,
+# assembled change set, no-diff preflight): NUL-delimited paths with the never-committable classes
+# filtered out.
+emit_untracked_paths_z() {
+  local path
+  while IFS= read -r -d '' path; do
+    if is_never_committable_untracked "$path"; then continue; fi
+    printf '%s\0' "$path"
+  done < <(git ls-files --others --exclude-standard -z)
+}
+
+# True when at least one untracked-not-ignored path survives the never-committable filter — the
+# no-diff preflight twin of the fingerprint walk (a tree whose ONLY untracked paths are
+# device/FIFO/socket masks reads clean).
+has_reviewable_untracked() {
+  [[ "$(emit_untracked_paths_z | wc -c)" -gt 0 ]]
+}
+
+# `git status --porcelain=v1` with never-committable untracked records dropped, so the assembled
+# review payload is byte-identical with and without a device mask (the fingerprint==payload domain
+# identity). Quote/space-safe: each filtered path's DISPLAYED line comes from git itself (never a
+# re-implemented C-quoting), then exact whole-line removal — only untracked (??) records can match
+# by construction. A mask nested in an otherwise-empty untracked directory leaves the collapsed
+# `?? dir/` record (a directory is not in the filtered class); the real sandbox masks land beside
+# tracked content, where status lists them individually.
+emit_status_porcelain_filtered() {
+  local path line drop=""
+  while IFS= read -r -d '' path; do
+    if is_never_committable_untracked "$path"; then
+      line="$(git status --porcelain=v1 -- ":(literal)$path")"
+      if [[ -n "$line" ]]; then drop+="$line"$'\n'; fi
+    fi
+  done < <(git ls-files --others --exclude-standard -z)
+  if [[ -z "$drop" ]]; then
+    git status --porcelain=v1
+  else
+    git status --porcelain=v1 | grep -Fvxf <(printf '%s' "$drop") || true
+  fi
+}
+
+# ONE non-failing advisory when the walk observes never-committable untracked paths: they are
+# ignored by the review domain BY CONSTRUCTION; the kit's sandbox-masks lane can hide them from
+# `git status` too. Never an error, never a detector.
+warn_never_committable_untracked() {
+  local path n=0
+  while IFS= read -r -d '' path; do
+    if is_never_committable_untracked "$path"; then n=$((n + 1)); fi
+  done < <(git ls-files --others --exclude-standard -z)
+  if (( n > 0 )); then
+    echo "notice: $n never-committable untracked path(s) (device/FIFO/socket) ignored by the review domain — for a clean 'git status' see the kit's sandbox-masks lane (/agent-workflow-kit sandbox-masks)." >&2
+  fi
+}
+
 # The canonical uncommitted-state fingerprint payload (code mode). Domain == the review payload:
-# tracked staged + unstaged changes + untracked-not-ignored file contents (binary/symlink/non-regular
-# untracked paths ride as name-only notes, mirroring the assembled change set). The prose definition
-# lives in capability.json roles.review.contract.receipt (both bridges, lockstep); the kit checker
-# (tools/review-state.mjs) implements the SAME serialization in node — cross-checked by the kit's
+# tracked staged + unstaged changes + untracked-not-ignored file contents (binary untracked files,
+# symlinks, and directories/gitlinks ride as name-only notes, mirroring the assembled change set;
+# never-committable untracked paths — devices/FIFOs/sockets — are EXCLUDED entirely, see
+# emit_untracked_paths_z). The prose definition lives in capability.json
+# roles.review.contract.receipt (both bridges, lockstep); the kit checker (tools/review-state.mjs)
+# implements the SAME serialization in node — cross-checked by the kit's
 # review-fingerprint-parity.test.mjs.
 emit_fingerprint_payload() {
   git diff --cached --no-ext-diff
@@ -327,7 +394,7 @@ emit_fingerprint_payload() {
       printf 'untracked:%s\n' "$path"
       cat -- "$path"
     fi
-  done < <(git ls-files --others --exclude-standard -z)
+  done < <(emit_untracked_paths_z)
 }
 
 # sha256 of the canonical payload, emitted from the work-tree ROOT (a subdir invocation hashes the
@@ -383,16 +450,18 @@ parse_agy_verdict() { # $1 = captured-output file
   esac
 }
 
-# Emit the full code-review surface: repo map, status, staged + unstaged diffs, and the CONTENTS of
-# every untracked REGULAR file (NUL-safe iteration). Symlinks are shown as their target (never
-# followed — no out-of-repo leak); other non-regular paths (FIFO/socket/device/dir) are skipped.
-# Ported verbatim from codex-cli-bridge/bin/codex-review.sh.
+# Emit the full review surface to stdout: repo map, status (never-committable untracked records
+# filtered), staged + unstaged diffs, and the CONTENTS of every untracked REGULAR file (NUL-safe
+# iteration over the SAME filtered walk as the fingerprint — the payload is byte-identical with
+# and without a device mask). Symlinks are shown as their target (never followed — no out-of-repo
+# leak); directories/vanished paths are noted, never read (a `cat` on a FIFO would hang BEFORE the
+# hard timeout applies — that class never reaches this loop).
 assemble_code_diff() {
   echo "=== repo file map (git ls-files) ==="
   git ls-files
   echo
   echo "=== git status (porcelain) ==="
-  git status --porcelain=v1
+  emit_status_porcelain_filtered
   echo
   echo "=== staged diff (git diff --cached) ==="
   git diff --cached --no-ext-diff
@@ -414,7 +483,7 @@ assemble_code_diff() {
       cat -- "$path"
       printf '\n'
     fi
-  done < <(git ls-files --others --exclude-standard -z)
+  done < <(emit_untracked_paths_z)
 }
 
 # --- Resume detection (must be the FIRST argument) ---------------------------
@@ -593,12 +662,14 @@ else
       exit 2
     fi
     cd "$(git rev-parse --show-toplevel)"
-    # No-diff preflight — never spend a run on a clean tree.
-    if git diff --quiet && git diff --cached --quiet \
-       && [[ -z "$(git ls-files --others --exclude-standard)" ]]; then
+    # No-diff preflight — never spend a run on a clean tree. Never-committable untracked masks do
+    # not count: the FILTERED domain is the review surface.
+    if git diff --quiet && git diff --cached --quiet && ! has_reviewable_untracked; then
       echo "agy-review: no uncommitted changes to review — the working tree is clean." >&2
+      warn_never_committable_untracked
       exit 0
     fi
+    warn_never_committable_untracked
     # The canonical fingerprint of the tree agy is about to review — computed at assembly time,
     # so the receipt attests exactly the reviewed state.
     REVIEW_ARTIFACT="code"

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -101,6 +101,9 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
     env: {
       HOME: home,
       PATH: `${bin}:${farm}`,
+      // Keep the wrapper's mktemp working when the suite runs inside an OS sandbox whose /tmp is
+      // read-only (only $TMPDIR is writable there).
+      TMPDIR: process.env.TMPDIR ?? '/tmp',
       AGY_FAKE_ARGV: cap.argv, AGY_FAKE_ENV: cap.env, AGY_FAKE_PROMPT: cap.prompt,
       AGY_FAKE_SENTINEL: cap.sentinel, AGY_FAKE_ADDDIR: cap.adddir, AGY_FAKE_ADDDIR_MODE: cap.adddirMode,
       AGY_FAKE_ARTIFACT_MODE: cap.artifactMode, AGY_FAKE_ARTIFACT_COPY: cap.artifactCopy,

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -24,7 +24,9 @@ const makeSandbox = (stubBody) => {
 
 const runWrapper = (home, env, prompt = 'hello') =>
   spawnSync('bash', [WRAPPER, prompt], {
-    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, ...env },
+    // TMPDIR rides along so the wrapper's mktemp keeps working when the suite itself runs inside
+    // an OS sandbox whose /tmp is read-only (only $TMPDIR is writable there).
+    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, TMPDIR: process.env.TMPDIR ?? '/tmp', ...env },
     encoding: 'utf8',
     timeout: 20000,
   });
@@ -73,7 +75,7 @@ const RECORDING_STUB = [
 // and optional stdin. AGY_MODEL='' drops --model so the stub argv stays clean.
 const runArgs = (home, { args, env = {}, input } = {}) =>
   spawnSync('bash', [WRAPPER, ...args], {
-    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, AGY_MODEL: '', ...env },
+    env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, TMPDIR: process.env.TMPDIR ?? '/tmp', AGY_MODEL: '', ...env },
     encoding: 'utf8',
     timeout: 20000,
     input,

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "provides": ["review", "probe"],
   "roles": {
     "review": {
@@ -28,7 +28,7 @@
           "agy-review --continue [--decided @f] [--focus \"…\"]",
           "agy-review --conversation <id> [--decided @f] [--focus \"…\"]"
         ],
-        "receipt": "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review"
+        "receipt": "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review"
       }
     },
     "probe": { "cmd": "agy-run", "source": "bin/agy.sh", "output": "advisory" }
@@ -49,6 +49,7 @@
       "effect": "1 ⇒ an oversized code review offloads the change set to a private --add-dir staging dir (re-enables the Issue-001 stall risk; the hard timeout bounds it). Default 0: an oversized prompt refuses instead."
     }
   ],
+  "networkHosts": ["*.googleapis.com", "accounts.google.com", "antigravity-unleash.goog", "lh3.googleusercontent.com"],
   "detect": {
     "installed": {
       "env": "ANTIGRAVITY_CLI_BRIDGE_DIR",

package/bridges/codex-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.3.0'
+  version: '2.4.0'
 ---
 
 # codex-cli-bridge

package/bridges/codex-cli-bridge/bin/codex-exec.test.mjs

@@ -107,6 +107,9 @@ const run = ({ repo, bin }, { args = ['-'], input = 'do the thing', env = {}, pa
     env: {
       PATH: path || `${bin}:${process.env.PATH}`,
       HOME: repo,
+      // Keep the wrapper's mktemp working when the suite runs inside an OS sandbox whose /tmp is
+      // read-only (only $TMPDIR is writable there).
+      TMPDIR: process.env.TMPDIR ?? '/tmp',
       CODEX_FAKE_ARGV: argvFile,
       CODEX_FAKE_ENV: envFile,
       CODEX_FAKE_STDIN: stdinFile,