From 43cdaf7a666df76617ad121e253eae09fd0cb9fd Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:03:30 -0700
Subject: [PATCH 01/28] docs(plan): Branch 2 test hermeticity code-level plan

---
 .../2026-09-27-branch-2-test-hermeticity.md   | 1723 +++++++++++++++++
 1 file changed, 1723 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-27-branch-2-test-hermeticity.md

diff --git a/docs/superpowers/plans/2026-09-27-branch-2-test-hermeticity.md b/docs/superpowers/plans/2026-09-27-branch-2-test-hermeticity.md
new file mode 100644
index 00000000..070ea2ef
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-27-branch-2-test-hermeticity.md
@@ -0,0 +1,1723 @@
+# Branch 2: Test Hermeticity Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make it impossible for `pnpm test` and `pnpm run test:ui` to change real user state without failing, and remove every known way the suite does it today.
+
+**Architecture:** A cross-platform fingerprint library and a suite runner (both in `scripts/`) snapshot the real state directories before and after the existing test commands and fail, naming each changed path, when anything changed. The dashboard server refuses its real-state-writing defaults when a caller injected fakes. Shared test helpers give every spawned child and every in-process spawn a sandboxed environment and self-cleaning temporary folders; three UI checks become deterministic.
+
+**Tech Stack:** Node 22.13+ ESM (`node:test`, `node:child_process`, `node:crypto`), Playwright (`tests/ui`), pnpm in CI (never in this worktree).
+
+**Spec:** [Remediation program, Branch 2](2026-09-26-remediation-program.md#branch-2-fixtest-hermeticity); [audit record](../../audits/2026-09-26-issues-237-238-239-verification-and-decisions.md) Open items ("Needs the maintainer's action": the dashboard server's hermeticity guard gap; "Carried from the earlier stages": spawn tests inheriting `XDG_*`, UI suite outside `test:ui`; "Not run": the memory-routing live test uses the real home folder); SDD ledger deferred minors `hermeticity-suite-writes-enclosing-repo`, `hermeticity-temp-dir-leaks`, the `host-readiness.mjs` flake and the MNT-UX-007 flake.
+
+## Global Constraints
+
+- Commits carry no `Co-Authored-By` or other attribution trailer, and no trailer-like last line.
+- Nothing is pushed, opened as a pull request, merged or posted without the maintainer's explicit go-ahead.
+- Never run `pnpm` in this worktree (`node_modules` is a symlink). Use `node --test`, `npx tsc -p tsconfig.json`, `npx eslint`, `npx markdownlint-cli2`, `node scripts/build-check.mjs`.
+- Stage files by name; never `git add -A`/`git add .`; never commit `.harness/`, `.swarm/`, `.claude-flow/`, `.agentic-qe/`.
+- Disposable environments use `env -u XDG_CONFIG_HOME -u XDG_DATA_HOME -u XDG_CACHE_HOME -u XDG_STATE_HOME` (or `env -i`) and a `mktemp -d <template>` inside the scratch area; assert every created path lies inside it.
+- Tests never write real user state: not the repository's `.claude`/`.swarm`, not `~/.config/agentic-kit`, not `~/.local/state/agentic-kit`, not any real memory store.
+- Runtime assets live under `src/`; test tooling lives in `scripts/` or `tests/` (neither ships; `scripts/**/*.mjs` is type-checked by `tsconfig.json`).
+- CI runs `pnpm test` on ubuntu, macOS and windows-latest with Node 22/24/26 and `pnpm run test:ui` on ubuntu Node 22 (`.github/workflows/ci.yml`). Everything here must work on Node 22.13 (no `--test-global-setup`: absent from `node --help` on 22.22.3) and on Windows paths.
+- User-facing docs describe the current state only; an ADR a change alters gets Status, an `Updated` date and a one-line note.
+
+## Verification of the scope against the code (done while writing this plan, at `be1c1d47`)
+
+| # | Program-plan item | Verdict and evidence |
+|---|---|---|
+| 1 | Suite-wide real-state tripwire | **Confirmed missing.** Only per-file guards exist: `guardRealRepository()` watches seven repo files (`tests/kit/helpers/project-isolation.mjs:28-36`) and `assertUnchanged()` snapshots one tree. Nothing watches `~/.config/agentic-kit`, `~/.local/state/agentic-kit`, `%APPDATA%`/`%LOCALAPPDATA%` or the repo's `.swarm`/`.agentic-qe`/`.claude-flow`/`.harness`. `node --test` runs files in parallel child processes, so a "first/last test file" cannot order around the others; `--test-global-setup` is missing on Node 22.22.3. A wrapper runner is the only design that works on 22.13+. |
+| 2 | Dashboard refuses defaults when fakes are injected | **Confirmed.** `managementProvider` (`src/lib/dashboard-server.mjs:992-1015`) throws only when `maintenance` is injected without a control root. With only `system` (or `fetchStatus`, `usage`, …) injected, `provideMaintenance` (`:1121-1128`) builds the default service over the real control root, and `refreshMaintenanceAfterSystem` (`:1172-1187`) runs it after every successful `?refresh=deep`. Commit `259f075` fixed the test that did this, not the product. `refreshMaintenanceAfterSystem` swallows errors (`.catch(() => null)`), so a refusal on that path must be logged to be visible. The real command (`src/commands/x/dashboard.mjs:90-94`) passes only `port`, `cwd`, `liveOptions`, so a guard keyed on injected collectors never touches it. |
+| 3 | Spawn tests inherit the developer's `XDG_*` | **Confirmed.** The maintainer's shell exports all four `XDG_*` bases. `provider-cli`, `usage-cli`, `host-cli-migration`, `provider-refresh-cli`, `dry-run-nudge`, `prompts-mainline-boundary`, `hook-audit`, `cli-help` and others spread `...process.env` and pin only `HOME`/`XDG_CONFIG_HOME`/`APPDATA` (some also `XDG_DATA_HOME`); `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `LOCALAPPDATA` and `TMPDIR` pass through. 22 `...process.env` sites in `tests/kit` and `tests/*.cjs`. |
+| 4 | Six tests create `$XDG_STATE_HOME/opencode` | **Confirmed, and wider.** Per-file probe (each of the 338 `tests/kit` files alone, with `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`, `LOCALAPPDATA`, `TMPDIR` redirected): exactly six files create `state/opencode`, **and** `cache/opencode/bin`, `data/opencode/{repos,log}` and `$TMPDIR/opencode` — the real OpenCode's own directories on a developer machine. Direct spawns: `opencode-stock-ruflo-gateway`, `provider-cli`, `provider-refresh-cli`. In-process (the test calls `src/lib/providers.mjs`/`adapters/lifecycle.mjs`, which spawn `opencode` with `process.env`): `integration-command-facts`, `opencode`, `provider-credentials`. |
+| 5 | "Create temporary folders from a template — macOS `mktemp -d` ignores `TMPDIR`" | **Wrong as stated for the tests.** No test, script or template shells out to `mktemp` (`grep -rn mktemp tests scripts src/templates .github` is empty); all 188 test files that make temp folders use `fs.mkdtempSync(path.join(os.tmpdir(), prefix))`, which honours `TMPDIR`. The `mktemp` gotcha applies to shell sessions (the brief's disposable-env line), not the suite. The real defect behind it is the temp-folder leak: reframed below as "the suite runs inside its own templated temp root and fails on leftovers". |
+| 5b | Deferred minor `hermeticity-temp-dir-leaks` (~20 files) | **Confirmed, 59 files, not ~20** (table below). |
+| 5c | Deferred minor `hermeticity-suite-writes-enclosing-repo` | **Confirmed by the Branch 0 review** (reports `review-hermeticity.md:122-132`, `refute-hermeticity.md:184-202`): `aqe-embedding-projection.test.mjs:200-222` deletes the fixture's `.git`, so `repoRoot()` (`src/lib/paths.mjs:206-215`) climbs to an enclosing repository; `status-aqe-drift.test.mjs:98` does the same with a `.git`-less temp dir; `opencode-stock-ruflo-gateway.test.mjs` runs real OpenCode from a `.git`-less workspace and OpenCode edited the enclosing repo's `package.json`, created `package-lock.json` and replaced the `node_modules` symlink. Only happens when `TMPDIR` is inside a git repository. |
+| 6 | `tests/ui/maintenance-focus.mjs` "polyglot cards…" fails | **Test is stale; product is right.** Two causes, reproduced in headless Chrome: (a) the harness stubs `mntKindLabel`, `mntFacetValueLabel`, `mntIcon`, `mntAvailableTo` but not `mntProjectKindBadge`, which moved to `src/lib/dashboard/client/maintenance-cards.mjs:31`; the page throws `mntProjectKindBadge is not defined` and renders nothing (0 icons); (b) the test expects three icons plus a "+2 more languages" disclosure, which DDD-09 removed: `docs/LANGUAGE-LOGOS.md:11-12` ("there is no three-icon cap or additional-language disclosure"), `docs/MAINTENANCE.md:766`, and the unit test `tests/kit/maintenance-focus-client.test.mjs:44-46` (asserts all icons and no `mnt-language-more`). The file's other test passes; `tests/ui/maintenance-guidance.mjs` (also outside `test:ui`) passes. Both write screenshots to `/tmp`. |
+| 7 | Memory-routing live test uses the real home | **Confirmed.** `tests/live/ruflo-memory-routing.test.mjs:24-30` makes a `.git`-less temp project and runs `ruflo` through `run()`, which merges `process.env` (`src/lib/exec.mjs:211`): real `HOME` and `XDG_*`; `rufloMcpLaunch` reads the real `kit.json` and `paths.home`. `tests/live/disposable-memory-project.mjs` already provides a `git init`-ed, daemon-off disposable project. |
+| F1 | `host-readiness.mjs` dialog-title flake | **Mechanism found.** The dialog's `close` event is a queued task; its handler (`src/lib/dashboard/client/host-readiness.mjs:169`) focuses the badge of the *current* `HEALTH_HOST`. The test presses Escape, focuses the next badge, presses Enter; if the queued `close` runs after the new focus, focus jumps back to the previous badge and Enter reopens it: "Claude Code health" where "Codex health" was expected (`fix-wave-2.md:171`). |
+| F2 | MNT-UX-007 flake | **Mechanism found.** After "Clear all" the test waits only for the chips to vanish (`tests/ui/dashboard-ui.mjs:2397-2398`), which happens synchronously, while the inventory query is still in flight (`mntRunInventoryQuery`, `src/lib/dashboard/client/maintenance-inventory.mjs:47-78`). When the response lands after the test focused row 0, `renderMntInventory()` replaces the list: tabindexes reset, focus is lost, and the before/after arrays are equal. `#mnt-results` carries no busy marker (`mntBusy` sets `aria-busy` on `#sys-maintenance` only). |
+
+### Temp-folder leak table (per-file probe, each file alone with a fresh `TMPDIR`; `node-compile-cache` ignored)
+
+about-install-edits 1 · adapter-grants 35 · agentdb-retirement 2 · blocks-drift-parity 2 · brain-held-refresh 1 · claude-window-ledger 12 · codex-mcp-convergence 2 · codex-plugins 1 (`outside-*`) · codex-state 7 · conformance-tiers 34 · dashboard-intel-integration 5 · drift-freshness 2 · heal-natives 2 · helper-stamp 25 · host-adapters-cli 75 · host-alignment 3 · host-cli-migration 30 · hosts 1 · integration-command-facts 1 (`opencode`) · intel-history 39 · intelligence-watch 10 · live-core 11 · live-qe-contract 1 · live-service 25 · live-tailer 3 · live-transcript 9 · maintenance-host-alignment 2 · maintenance-management-activity 1 · nudge 5 · opencode-stock-ruflo-gateway 1 (`opencode`) · opencode 1 (`opencode`) · project-census 13 · provider-cli 1 (`opencode`) · provider-credentials 1 (`opencode`) · provider-refresh-cli 1 (`opencode`) · providers-drift-parity 2 · quota 36 · reverse-bridge 8 · routing-retirement-convergence 1 · ruflo-components-convergence 1 · ruvnet-brain 7 · status-aqe-drift 9 · status-golden 2 · status-repair-contract 2 · statusline-config-dir-parity 1 · statusline 12 + `ruflo-daemon-count.json` + `ruvnet-brain-kb-size.json` · sync-host-repair 1 · sync-needs-your-action 2 · sync-self-freshness 1 · system-summary 2 · usage-claude-dedup 1 · usage-cli 2 · usage-codex-attribution 8 · usage-codex-large-rollout 13 · usage-deps-contract 1 · usage-index-v6 9 · usage-index 72 · usage-truncation 7 · verify-memory-routes 2.
+
+`statusline`'s two JSON files are the live statusline's shared 30-second caches (`src/lib/daemons.mjs:276`, `src/templates/statusline-footer.cjs:423,501`): a test run poisons the developer's real footer.
+
+### Probe side findings the implementers must respect
+
+- `aqe-lifecycle-migration.test.mjs` fails ("owner or parent drift", `src/lib/hook-remediation/engine.mjs:344`) when `TMPDIR` is under `/private/tmp` (group `wheel`), and passes under the default `/var/folders/…/T` and under a user-owned sibling folder. Keep every temp root under `os.tmpdir()`; never relocate it to `/tmp`.
+- `footprint-projects.test.mjs` fails when `TMPDIR`'s path contains a Claude-encoded-directory look-alike (`-Users-…`); it passes under `/var/folders/…/T/ak-suite-XXXXXX`-style paths. The suite temp root name must not contain such a segment.
+- The fingerprint diff for this probe (brief's `fingerprint.sh`, before/after) was empty; the worktree's `git status --ignored` shows only `node_modules`.
+
+## Review Focus
+
+- **The maintainer's live sessions write the watched folders during a run.** The Claude Code statusline tee rewrites `claude-rate-limits.json` and `claude-context-windows/` in `~/.config/agentic-kit` on every render (`src/templates/statusline-footer.cjs:52-131`); Ruflo/AQE hooks churn the main checkout's `.swarm`, `.agentic-qe`, `.claude-flow`. Expected: a developer run does not fail on those, but still prints them under a separate heading; CI (no live session) is strict. Pinned in Task 1.1 (exclusion tests) and Task 1.2 (CI-strict test).
+- **Windows.** `%APPDATA%\agentic-kit`, `%LOCALAPPDATA%\agentic-kit`, `~\AppData\…` fall-backs, case-insensitive duplicates, and a file locked by another process (`EBUSY`). Expected: roots resolve with `path.win32`, duplicates collapse, a locked file is recorded, not thrown. Pinned in Task 1.1 (win32 root tests, unreadable-file test).
+- **A suite that fails before the tripwire compares.** Expected: the runner still takes the after-snapshot and prints changed paths even when a test command fails, and the exit code reflects the test failure. Pinned in Task 1.2.
+- **A new spawn test that copies `...process.env`.** Expected: the static guard fails naming the file and line. Pinned in Task 2.1.
+- **A temp root that sits inside a git repository.** Expected: the runner refuses to start with a message naming the enclosing repository, and "outside a git repository" tests skip with a reason instead of writing into it. Pinned in Tasks 2.4 and 2.5.
+
+## Slices and interfaces
+
+Three implementers run in sequence; each sees only its own slice. The names below are the contract between slices.
+
+**Slice 1 produces:**
+
+- `scripts/real-state-tripwire.mjs`
+  - `export const REPO_STATE_DIRS: string[]` = `['.claude', '.swarm', '.agentic-qe', '.claude-flow', '.harness']`
+  - `export function realStateRoots({ env, platform, homedir, repoRoot }): Array<{ kind: 'config'|'state'|'repo'|'user-file', dir: string, label: string }>`
+  - `export function snapshotRoots(roots): Map<string, Entry>` where `Entry = { root: Root, rel: string, type: 'file'|'dir'|'link'|'absent-root'|'unreadable', size?: number, sha256?: string, target?: string, code?: string }`
+  - `export function compareSnapshots(before, after, { strict }): { failing: Change[], concurrent: Change[] }` where `Change = { op: '+'|'-'|'~', path: string, rel: string, kind: string, before?: Entry, after?: Entry, writer?: string }`
+  - `export function isStrict(env): boolean`
+  - `export function formatReport(result): string`
+  - CLI: `node scripts/real-state-tripwire.mjs snapshot <out.json> [--repo <dir>]` and `node scripts/real-state-tripwire.mjs compare <before.json> [--repo <dir>]` (exit 3 on a failing change).
+- `scripts/run-tests.mjs`
+  - `export const SUITES: { unit: string[][], ui: string[][] }` (argument vectors for `process.execPath`)
+  - `export function runGuarded(commands, { env, repoRoot, platform, homedir, log }?): number` (exit code)
+  - CLI: `node scripts/run-tests.mjs unit|ui` and `node scripts/run-tests.mjs exec [--repo <dir>] -- <node args…>`
+  - `package.json`: `"test": "node scripts/run-tests.mjs unit"`, `"test:ui": "node scripts/run-tests.mjs ui"`.
+
+**Slice 2 consumes** `runGuarded`/`SUITES` (adds the suite temp root to `runGuarded`) and **produces**, in `tests/kit/helpers/home-sandbox.mjs` (builtins only):
+
+- `export const INHERITED_STATE_KEYS: string[]`
+- `export function sandboxEnvFor(home): Record<string, string>`
+- `export function spawnEnv(home, extra = {}): Record<string, string|undefined>`
+- `export function redirectToolState(prefix): { base: string, restore: () => void }`
+
+and `tests/kit/helpers/temp-dir.mjs`: `export function tempDir(prefix, t?): string`.
+
+**Slice 3 consumes** `SUITES.ui` (adds two files) and changes product client code only in `host-readiness.mjs` and `maintenance-inventory.mjs`.
+
+---
+
+## Slice 1 — tripwire and dashboard guard
+
+### Task 1.1: Cross-platform real-state fingerprint library
+
+**Files:**
+
+- Create: `scripts/real-state-tripwire.mjs`
+- Test: `tests/kit/real-state-tripwire.test.mjs`
+
+**Interfaces:**
+
+- Consumes: nothing (must not import anything from `src/`; `src/lib/paths.mjs` snapshots `os.homedir()` at module scope).
+- Produces: `REPO_STATE_DIRS`, `realStateRoots`, `snapshotRoots`, `compareSnapshots`, `isStrict`, `formatReport`, `CONCURRENT_WRITERS`, and the CLI above.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/kit/real-state-tripwire.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  REPO_STATE_DIRS, realStateRoots, snapshotRoots, compareSnapshots, isStrict, formatReport,
+} from '../../scripts/real-state-tripwire.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'real-state-tripwire.mjs');
+const tmp = (t, prefix) => {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`)));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+};
+
+test('POSIX roots: XDG bases, their defaults, the repo state folders and ak-owned user files', () => {
+  const roots = realStateRoots({
+    platform: 'linux', homedir: '/home/dev', repoRoot: '/src/kit',
+    env: { XDG_CONFIG_HOME: '/x/cfg', XDG_STATE_HOME: '/x/state' },
+  });
+  const dirs = roots.map((r) => `${r.kind}:${r.dir}`);
+  for (const want of [
+    'config:/x/cfg/agentic-kit', 'config:/home/dev/.config/agentic-kit',
+    'state:/x/state/agentic-kit', 'state:/home/dev/.local/state/agentic-kit',
+    ...REPO_STATE_DIRS.map((d) => `repo:/src/kit/${d}`),
+    'user-file:/home/dev/.claude/CLAUDE.md', 'user-file:/home/dev/.codex/AGENTS.md',
+    'user-file:/x/cfg/opencode/AGENTS.md',
+  ]) assert.ok(dirs.includes(want), `missing ${want} in ${dirs.join(', ')}`);
+});
+
+test('Windows roots use APPDATA/LOCALAPPDATA and collapse case-insensitive duplicates', () => {
+  const roots = realStateRoots({
+    platform: 'win32', homedir: 'C:\\Users\\dev', repoRoot: 'C:\\src\\kit',
+    env: { APPDATA: 'C:\\Users\\dev\\AppData\\Roaming', LOCALAPPDATA: 'c:\\users\\DEV\\appdata\\local' },
+  });
+  const dirs = roots.map((r) => `${r.kind}:${r.dir}`);
+  assert.ok(dirs.includes('config:C:\\Users\\dev\\AppData\\Roaming\\agentic-kit'));
+  assert.ok(dirs.includes('state:c:\\users\\DEV\\appdata\\local\\agentic-kit'));
+  assert.equal(dirs.filter((d) => d.toLowerCase() === 'state:c:\\users\\dev\\appdata\\local\\agentic-kit').length, 1,
+    'the LOCALAPPDATA root and the ~\\AppData\\Local fallback are one folder on Windows');
+  assert.ok(dirs.includes('repo:C:\\src\\kit\\.claude'));
+});
+
+test('a created, removed or rewritten file is failing; an mtime-only touch is not', (t) => {
+  const home = tmp(t, 'ak-trip');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(cfg, { recursive: true });
+  fs.writeFileSync(path.join(cfg, 'kit.json'), '{}');
+  fs.writeFileSync(path.join(cfg, 'gone.json'), '1');
+  fs.writeFileSync(path.join(cfg, 'touched.json'), 'same');
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const before = snapshotRoots(roots);
+  fs.writeFileSync(path.join(cfg, 'kit.json'), '{"changed":true}');
+  fs.rmSync(path.join(cfg, 'gone.json'));
+  fs.writeFileSync(path.join(cfg, 'new.json'), 'x');
+  const future = new Date(Date.now() + 60_000);
+  fs.utimesSync(path.join(cfg, 'touched.json'), future, future);
+  const { failing } = compareSnapshots(before, snapshotRoots(roots), { strict: true });
+  assert.deepEqual(failing.map((c) => `${c.op} ${c.rel}`).sort(), ['+ new.json', '- gone.json', '~ kit.json']);
+  const report = formatReport({ failing, concurrent: [] });
+  assert.match(report, /3 path\(s\) changed/);
+  assert.ok(report.includes(path.join(cfg, 'kit.json')), 'the report names the absolute path');
+});
+
+test('an empty folder a tool creates is a change (the opencode/ case)', (t) => {
+  const home = tmp(t, 'ak-trip-dir');
+  const state = path.join(home, '.local', 'state', 'agentic-kit');
+  fs.mkdirSync(state, { recursive: true });
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const before = snapshotRoots(roots);
+  fs.mkdirSync(path.join(state, 'maintenance'));
+  const { failing } = compareSnapshots(before, snapshotRoots(roots), { strict: true });
+  assert.deepEqual(failing.map((c) => `${c.op} ${c.rel}`), ['+ maintenance/']);
+});
+
+test('developer mode moves live-session writers to "concurrent"; strict mode fails them', (t) => {
+  const home = tmp(t, 'ak-trip-conc');
+  const repo = path.join(home, 'repo');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(path.join(cfg, 'claude-context-windows'), { recursive: true });
+  fs.mkdirSync(path.join(repo, '.swarm'), { recursive: true });
+  fs.mkdirSync(path.join(repo, '.agentic-qe'), { recursive: true });
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: repo, env: {} });
+  const before = snapshotRoots(roots);
+  fs.writeFileSync(path.join(cfg, 'claude-rate-limits.json'), '{}');
+  fs.writeFileSync(path.join(cfg, 'claude-context-windows', 's1.json'), '[]');
+  fs.writeFileSync(path.join(repo, '.swarm', 'memory.db-wal'), 'x');
+  fs.writeFileSync(path.join(repo, '.agentic-qe', 'llm-config.json'), '{}');
+  const after = snapshotRoots(roots);
+  const dev = compareSnapshots(before, after, { strict: false });
+  assert.deepEqual(dev.failing.map((c) => c.rel), ['.agentic-qe/llm-config.json'],
+    'ak-owned files inside hook-churned folders stay failing');
+  assert.deepEqual(dev.concurrent.map((c) => c.rel).sort(),
+    ['.swarm/memory.db-wal', 'claude-context-windows/s1.json', 'claude-rate-limits.json']);
+  const strict = compareSnapshots(before, after, { strict: true });
+  assert.equal(strict.concurrent.length, 0);
+  assert.ok(strict.failing.some((c) => c.rel === 'claude-rate-limits.json'));
+  assert.match(formatReport(dev), /concurrent writers \(not failing\)/);
+});
+
+test('CI and AK_TRIPWIRE_STRICT make the comparison strict', () => {
+  assert.equal(isStrict({ CI: 'true' }), true);
+  assert.equal(isStrict({ CI: '1' }), true);
+  assert.equal(isStrict({ AK_TRIPWIRE_STRICT: '1' }), true);
+  assert.equal(isStrict({}), false);
+  assert.equal(isStrict({ CI: 'false' }), false);
+});
+
+test('an unreadable file is recorded, never thrown, and compares equal to itself', { skip: process.platform === 'win32' && 'chmod 000 does not deny reads on Windows' }, (t) => {
+  const home = tmp(t, 'ak-trip-unread');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(cfg, { recursive: true });
+  const locked = path.join(cfg, 'locked.json');
+  fs.writeFileSync(locked, 'secret');
+  fs.chmodSync(locked, 0o000); // the folder stays writable, so the tmp cleanup still removes it
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const a = snapshotRoots(roots);
+  const entry = [...a.values()].find((e) => e.rel === 'locked.json');
+  if (process.getuid && process.getuid() === 0) return; // root reads anything
+  assert.equal(entry.type, 'unreadable');
+  assert.deepEqual(compareSnapshots(a, snapshotRoots(roots), { strict: true }).failing, []);
+});
+
+test('the CLI snapshot/compare pair exits 3 and names the changed path', (t) => {
+  const home = tmp(t, 'ak-trip-cli');
+  const repo = path.join(home, 'repo');
+  fs.mkdirSync(repo);
+  const env = { ...process.env, HOME: home, USERPROFILE: home, CI: 'true',
+    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local') };
+  const out = path.join(home, 'before.json');
+  const snap = spawnSync(process.execPath, [CLI, 'snapshot', out, '--repo', repo], { env, encoding: 'utf8' });
+  assert.equal(snap.status, 0, snap.stderr);
+  fs.mkdirSync(path.join(home, '.local', 'state', 'agentic-kit'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.local', 'state', 'agentic-kit', 'install-edits.json'), '{}');
+  const cmp = spawnSync(process.execPath, [CLI, 'compare', out, '--repo', repo], { env, encoding: 'utf8' });
+  assert.equal(cmp.status, 3, cmp.stdout + cmp.stderr);
+  assert.match(cmp.stderr, /install-edits\.json/);
+});
+```
+
+The developer-mode case has three concurrent changes because `claude-context-windows/` and `.swarm/` existed before the snapshot; only the new files appear.
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `node --test tests/kit/real-state-tripwire.test.mjs`
+Expected: FAIL — `Cannot find module …/scripts/real-state-tripwire.mjs`.
+
+- [ ] **Step 3: Write the implementation**
+
+```js
+#!/usr/bin/env node
+// scripts/real-state-tripwire.mjs
+// Real-state tripwire: fingerprints every folder a test could write on the
+// developer's machine and names each path that changed. Four incidents wrote
+// real state (statusline version + env pins in the repo's .claude, the
+// maintenance state, a heal receipt); this turns the next one into a failure.
+// Imports only builtins: src/lib/paths.mjs snapshots os.homedir() at module
+// scope and must never be loaded here. Node 22.13+.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const REPO_STATE_DIRS = ['.claude', '.swarm', '.agentic-qe', '.claude-flow', '.harness'];
+
+/** Writers a live Claude Code / Ruflo / AQE session runs concurrently with a
+ *  developer's test run. Excluded from failure only outside strict mode, and
+ *  always printed. Each entry names the source that proves the writer. */
+export const CONCURRENT_WRITERS = [
+  { kind: 'config', pattern: /^claude-rate-limits\.json(\.[^/]*)?$/, writer: 'Claude Code statusline tee (src/templates/statusline-footer.cjs:52-66)' },
+  { kind: 'config', pattern: /^claude-context-windows(\/|$)/, writer: 'Claude Code statusline context ledger (src/templates/statusline-footer.cjs:77-131)' },
+  { kind: 'state', pattern: /^statusline-debug\.log$/, writer: 'statusline debug log (src/templates/statusline-footer.cjs:2-15)' },
+  { kind: 'repo', pattern: /^\.swarm(\/|$)/, writer: 'Ruflo hooks and daemon of a live session' },
+  { kind: 'repo', pattern: /^\.agentic-qe\/(?!llm-config\.json)/, writer: 'AQE hooks of a live session' },
+  { kind: 'repo', pattern: /^\.claude-flow\/(?!config\.json$)/, writer: 'Ruflo hooks and statusline caches of a live session' },
+];
+
+export function isStrict(env = process.env) {
+  return env.CI === 'true' || env.CI === '1' || env.AK_TRIPWIRE_STRICT === '1';
+}
+
+/**
+ * Every real-state location a test could write, for the given platform.
+ * @param {{ env?: Record<string, string|undefined>, platform?: string, homedir?: string, repoRoot: string }} o
+ */
+export function realStateRoots({ env = process.env, platform = process.platform, homedir = os.homedir(), repoRoot }) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const configBases = [env.XDG_CONFIG_HOME, p.join(homedir, '.config'), env.APPDATA, p.join(homedir, 'AppData', 'Roaming')];
+  const stateBases = [env.XDG_STATE_HOME, p.join(homedir, '.local', 'state'), env.LOCALAPPDATA, p.join(homedir, 'AppData', 'Local')];
+  const primaryConfig = platform === 'win32'
+    ? env.APPDATA || p.join(homedir, 'AppData', 'Roaming')
+    : env.XDG_CONFIG_HOME || p.join(homedir, '.config');
+  const roots = [
+    ...configBases.filter(Boolean).map((base) => ({ kind: 'config', dir: p.join(base, 'agentic-kit') })),
+    ...stateBases.filter(Boolean).map((base) => ({ kind: 'state', dir: p.join(base, 'agentic-kit') })),
+    ...REPO_STATE_DIRS.map((name) => ({ kind: 'repo', dir: p.join(repoRoot, name), prefix: name })),
+    // ak-managed guidance files in other tools' homes (sync/setup write them).
+    { kind: 'user-file', dir: p.join(env.CLAUDE_CONFIG_DIR || p.join(homedir, '.claude'), 'CLAUDE.md') },
+    { kind: 'user-file', dir: p.join(env.CODEX_HOME || p.join(homedir, '.codex'), 'AGENTS.md') },
+    { kind: 'user-file', dir: p.join(primaryConfig, 'opencode', 'AGENTS.md') },
+  ];
+  const seen = new Set();
+  return roots.filter((root) => {
+    const key = platform === 'win32' ? p.normalize(root.dir).toLowerCase() : p.normalize(root.dir);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).map((root) => ({ ...root, label: `${root.kind}:${root.dir}` }));
+}
+
+const toRel = (...parts) => parts.filter(Boolean).join('/');
+
+function hashFile(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+function record(out, root, rel, abs) {
+  let st;
+  try { st = fs.lstatSync(abs); } catch (error) {
+    if (error.code === 'ENOENT') return; // vanished between readdir and lstat
+    out.set(abs, { root, rel, type: 'unreadable', code: error.code });
+    return;
+  }
+  if (st.isSymbolicLink()) {
+    let target = '';
+    try { target = fs.readlinkSync(abs); } catch { /* recorded as empty */ }
+    out.set(abs, { root, rel, type: 'link', target });
+  } else if (st.isDirectory()) {
+    out.set(abs, { root, rel: `${rel}/`, type: 'dir' });
+    let names;
+    try { names = fs.readdirSync(abs); } catch (error) {
+      out.set(abs, { root, rel: `${rel}/`, type: 'unreadable', code: error.code });
+      return;
+    }
+    for (const name of names.sort()) record(out, root, toRel(rel, name), path.join(abs, name));
+  } else {
+    try { out.set(abs, { root, rel, type: 'file', size: st.size, sha256: hashFile(abs) }); } catch (error) {
+      out.set(abs, { root, rel, type: 'unreadable', code: error.code });
+    }
+  }
+}
+
+/** Content-addressed snapshot of every root. Directory mtimes are ignored. */
+export function snapshotRoots(roots) {
+  const out = new Map();
+  for (const root of roots) {
+    if (!fs.existsSync(root.dir)) { out.set(`absent:${root.dir}`, { root, rel: '', type: 'absent-root' }); continue; }
+    if (root.kind === 'user-file') { record(out, root, path.basename(root.dir), root.dir); continue; }
+    // The root itself is an entry, so a run that CREATES ~/.local/state/agentic-kit
+    // (even empty) is reported as `+ <root>/`.
+    out.set(root.dir, { root, rel: root.prefix ? `${root.prefix}/` : './', type: 'dir' });
+    let names;
+    try { names = fs.readdirSync(root.dir); } catch (error) {
+      out.set(root.dir, { root, rel: root.prefix ? `${root.prefix}/` : './', type: 'unreadable', code: error.code });
+      continue;
+    }
+    for (const name of names.sort()) record(out, root, toRel(root.prefix, name), path.join(root.dir, name));
+  }
+  return out;
+}
+
+const same = (a, b) => a.type === b.type && a.sha256 === b.sha256 && a.target === b.target && a.code === b.code;
+
+function writerFor(entry) {
+  return CONCURRENT_WRITERS.find((w) => w.kind === entry.root.kind && w.pattern.test(entry.rel.replace(/\/$/, '')))?.writer;
+}
+
+export function compareSnapshots(before, after, { strict = isStrict() } = {}) {
+  const changes = [];
+  for (const [key, now] of after) {
+    const was = before.get(key);
+    if (now.type === 'absent-root') continue;
+    if (!was) changes.push({ op: '+', path: key, rel: now.rel, kind: now.root.kind, after: now });
+    else if (!same(was, now)) changes.push({ op: '~', path: key, rel: now.rel, kind: now.root.kind, before: was, after: now });
+  }
+  for (const [key, was] of before) {
+    if (was.type === 'absent-root' || after.has(key)) continue;
+    changes.push({ op: '-', path: key, rel: was.rel, kind: was.root.kind, before: was });
+  }
+  const failing = [];
+  const concurrent = [];
+  for (const change of changes) {
+    const writer = writerFor(change.after || change.before);
+    if (!strict && writer) concurrent.push({ ...change, writer });
+    else failing.push(change);
+  }
+  const byPath = (a, b) => a.path.localeCompare(b.path);
+  return { failing: failing.sort(byPath), concurrent: concurrent.sort(byPath) };
+}
+
+const size = (e) => (e && e.type === 'file' ? `${e.size} bytes` : e ? e.type : 'absent');
+
+export function formatReport({ failing, concurrent }) {
+  const lines = [];
+  if (failing.length) {
+    lines.push(`real-state tripwire: ${failing.length} path(s) changed during the run`);
+    for (const c of failing) lines.push(`  ${c.op} ${c.path} (${size(c.before)} -> ${size(c.after)})`);
+    lines.push('A test wrote real user state. If you ran ak, the dashboard or `ak sync` yourself during the run, '
+      + 'check whether the listed file holds your data or fixture data, and re-run with nothing else running.');
+  }
+  if (concurrent.length) {
+    lines.push(`real-state tripwire: ${concurrent.length} path(s) changed by concurrent writers (not failing)`);
+    for (const c of concurrent) lines.push(`  ${c.op} ${c.path} — ${c.writer}`);
+  }
+  return lines.join('\n');
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+function repoArg(argv) {
+  const i = argv.indexOf('--repo');
+  return i >= 0 ? path.resolve(argv[i + 1]) : process.cwd();
+}
+
+function serialize(map) {
+  return JSON.stringify([...map].map(([key, e]) => [key, { ...e, root: e.root.label }]));
+}
+
+function deserialize(text, roots) {
+  const byLabel = new Map(roots.map((r) => [r.label, r]));
+  return new Map(JSON.parse(text).map(([key, e]) => [key, { ...e, root: byLabel.get(e.root) ?? { kind: 'unknown', label: e.root } }]));
+}
+
+function main(argv) {
+  const [command, file] = argv;
+  const roots = realStateRoots({ repoRoot: repoArg(argv) });
+  if (command === 'snapshot' && file) {
+    fs.writeFileSync(file, serialize(snapshotRoots(roots)));
+    return 0;
+  }
+  if (command === 'compare' && file) {
+    const result = compareSnapshots(deserialize(fs.readFileSync(file, 'utf8'), roots), snapshotRoots(roots));
+    const report = formatReport(result);
+    if (report) console.error(report);
+    return result.failing.length ? 3 : 0;
+  }
+  console.error('usage: real-state-tripwire.mjs snapshot|compare <file> [--repo <dir>]');
+  return 2;
+}
+
+// Compare real paths (drive-letter case differs on Windows): a missed match would
+// make `pnpm test` exit 0 having run nothing.
+const isMain = () => {
+  if (!process.argv[1]) return false;
+  const a = fs.realpathSync.native(path.resolve(process.argv[1]));
+  const b = fs.realpathSync.native(fileURLToPath(import.meta.url));
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+if (isMain()) {
+  process.exitCode = main(process.argv.slice(2));
+}
+```
+
+On POSIX `realStateRoots` also lists the `AppData` fall-backs; they are absent and cost one `existsSync` each.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test tests/kit/real-state-tripwire.test.mjs && mise exec node@22.22.3 -- node --test tests/kit/real-state-tripwire.test.mjs`
+Expected: PASS on both Node versions.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `npx eslint scripts/real-state-tripwire.mjs tests/kit/real-state-tripwire.test.mjs && npx tsc -p tsconfig.json`
+Expected: 0 errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/real-state-tripwire.mjs tests/kit/real-state-tripwire.test.mjs
+git commit -m "test(guard): fingerprint real user state on every platform"
+```
+
+### Task 1.2: The suite runner fails when real state changed
+
+**Files:**
+
+- Create: `scripts/run-tests.mjs`
+- Modify: `package.json` (`scripts.test`, `scripts["test:ui"]`)
+- Modify: `AGENTS.md` (Testing → Running Tests: say that `pnpm test`/`pnpm run test:ui` run through the tripwire, what "concurrent writers" means, and `AK_TRIPWIRE_STRICT=1`)
+- Test: `tests/kit/run-tests-runner.test.mjs`
+
+**Interfaces:**
+
+- Consumes: Task 1.1's `realStateRoots`, `snapshotRoots`, `compareSnapshots`, `isStrict`, `formatReport`.
+- Produces: `SUITES`, `runGuarded(commands, opts) → number`, CLI `unit|ui|exec`.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/kit/run-tests-runner.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const RUNNER = path.join(ROOT, 'scripts', 'run-tests.mjs');
+
+function sandbox(t) {
+  const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-runner-')));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const repo = path.join(home, 'repo');
+  fs.mkdirSync(path.join(repo, '.git'), { recursive: true });
+  const env = { ...process.env, HOME: home, USERPROFILE: home,
+    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    XDG_DATA_HOME: path.join(home, '.local', 'share'), XDG_CACHE_HOME: path.join(home, '.cache'),
+    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local'), CI: 'true' };
+  for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'AK_TRIPWIRE_STRICT']) delete env[key];
+  return { home, repo, env };
+}
+
+const stub = (dir, name, body) => { const f = path.join(dir, name); fs.writeFileSync(f, body); return f; };
+
+test('a command that writes real state fails the run and the path is named', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leak = stub(home, 'leak.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    const d = path.join(process.env.XDG_STATE_HOME, 'agentic-kit', 'maintenance');
+    fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, 'latest-scan.json'), '{}');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leak], { env, encoding: 'utf8' });
+  assert.equal(r.status, 3, r.stdout + r.stderr);
+  assert.match(r.stderr, /real-state tripwire: watching \d+ roots \(strict\)/);
+  assert.match(r.stderr, /latest-scan\.json/);
+  assert.match(r.stderr, /maintenance\//);
+});
+
+test('a write into the repository .claude fails the run', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leak = stub(home, 'leak-repo.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    fs.mkdirSync(path.join(process.argv[2], '.claude', 'helpers'), { recursive: true });
+    fs.writeFileSync(path.join(process.argv[2], '.claude', 'helpers', 'statusline.cjs'), '9.9.9');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leak, repo], { env, encoding: 'utf8' });
+  assert.equal(r.status, 3, r.stderr);
+  assert.match(r.stderr, /statusline\.cjs/);
+});
+
+test('a failing test command keeps its exit code and the tripwire still reports', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const both = stub(home, 'both.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    fs.mkdirSync(path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit'), { recursive: true });
+    fs.writeFileSync(path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit', 'kit.json'), '{}');
+    process.exit(7);`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', both], { env, encoding: 'utf8' });
+  assert.equal(r.status, 7);
+  assert.match(r.stderr, /kit\.json/);
+});
+
+test('a clean command passes; concurrent-writer churn does not fail a developer run', (t) => {
+  const { home, repo, env } = sandbox(t);
+  delete env.CI;
+  // The folder exists on any machine with a live statusline; creating it would be a real leak.
+  fs.mkdirSync(path.join(home, '.config', 'agentic-kit'), { recursive: true });
+  const tee = stub(home, 'tee.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    const d = path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit');
+    fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, 'claude-rate-limits.json'), '{}');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', tee], { env, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stderr, /concurrent writers \(not failing\)/);
+});
+
+test('SUITES keeps the exact commands package.json ran before', async () => {
+  const { SUITES } = await import('../../scripts/run-tests.mjs');
+  assert.deepEqual(SUITES.unit[0], ['--test', '--experimental-test-coverage', '--test-coverage-lines=70',
+    '--test-coverage-branches=70', '--test-coverage-functions=70', 'tests/kit/*.test.mjs']);
+  assert.deepEqual(SUITES.unit.slice(1).map((a) => a[0]), ['statusline-segments', 'statusline-window-ledger',
+    'statusline-brain', 'health-history', 'dashboard', 'admin-model', 'admin'].map((f) => `tests/${f}.test.cjs`));
+  assert.equal(SUITES.ui[0][0], 'tests/ui/dashboard-ui.mjs');
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  assert.equal(pkg.scripts.test, 'node scripts/run-tests.mjs unit');
+  assert.equal(pkg.scripts['test:ui'], 'node scripts/run-tests.mjs ui');
+});
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `node --test tests/kit/run-tests-runner.test.mjs`
+Expected: FAIL — runner missing (exit 1 with `Cannot find module`), `SUITES` import fails.
+
+- [ ] **Step 3: Write the runner**
+
+```js
+#!/usr/bin/env node
+// scripts/run-tests.mjs — runs a test suite between two real-state snapshots.
+// `pnpm test` and `pnpm run test:ui` call this. Commands run in order and stop
+// at the first failure (the old `&&` chain); the after-snapshot is taken either
+// way. No shell: argument vectors for process.execPath, so it behaves the same
+// on Windows; `node --test` expands the glob itself.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { realStateRoots, snapshotRoots, compareSnapshots, isStrict, formatReport } from './real-state-tripwire.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const COVERAGE = ['--experimental-test-coverage', '--test-coverage-lines=70',
+  '--test-coverage-branches=70', '--test-coverage-functions=70'];
+
+export const SUITES = {
+  unit: [
+    ['--test', ...COVERAGE, 'tests/kit/*.test.mjs'],
+    ...['statusline-segments', 'statusline-window-ledger', 'statusline-brain', 'health-history',
+      'dashboard', 'admin-model', 'admin'].map((name) => [`tests/${name}.test.cjs`]),
+  ],
+  ui: [
+    ['tests/ui/dashboard-ui.mjs'],
+    ['--test', 'tests/ui/dashboard-project-context.mjs', 'tests/ui/maintenance-projects.mjs',
+      'tests/ui/maintenance-host-alignment.mjs', 'tests/ui/intelligence-picker.mjs',
+      'tests/ui/usage-project-groups.mjs', 'tests/ui/context-coverage.mjs', 'tests/ui/host-readiness.mjs'],
+  ],
+};
+
+/**
+ * @param {string[][]} commands argument vectors for process.execPath
+ * @param {{ env?: NodeJS.ProcessEnv, repoRoot?: string, platform?: string, homedir?: string, log?: (s: string) => void }} [o]
+ * @returns {number} exit code: the first failing command's, else 3 on a real-state change, else 0
+ */
+export function runGuarded(commands, {
+  env = process.env, repoRoot = REPO, platform = process.platform, homedir = os.homedir(), log = console.error,
+} = {}) {
+  const roots = realStateRoots({ env, platform, homedir, repoRoot });
+  const before = snapshotRoots(roots);
+  // One line before anything runs, so a CI log proves the tripwire executed.
+  log(`real-state tripwire: watching ${roots.length} roots (${isStrict(env) ? 'strict' : 'developer'})`);
+  let code = 0;
+  for (const args of commands) {
+    const r = spawnSync(process.execPath, args, { cwd: repoRoot, env, stdio: 'inherit' });
+    if (r.error) { log(`could not run node ${args.join(' ')}: ${r.error.message}`); code = 1; break; }
+    if (r.status !== 0) { code = r.status ?? 1; break; }
+  }
+  const result = compareSnapshots(before, snapshotRoots(roots), { strict: isStrict(env) });
+  const report = formatReport(result);
+  if (report) log(report);
+  return code || (result.failing.length ? 3 : 0);
+}
+
+function main(argv) {
+  const [mode] = argv;
+  if (mode === 'unit' || mode === 'ui') return runGuarded(SUITES[mode]);
+  if (mode === 'exec') {
+    const sep = argv.indexOf('--');
+    const repoAt = argv.indexOf('--repo');
+    if (sep < 0 || sep === argv.length - 1) { console.error('usage: run-tests.mjs exec [--repo <dir>] -- <node args…>'); return 2; }
+    const repoRoot = repoAt >= 0 && repoAt < sep ? path.resolve(argv[repoAt + 1]) : REPO;
+    return runGuarded([argv.slice(sep + 1)], { repoRoot });
+  }
+  console.error('usage: run-tests.mjs unit|ui|exec');
+  return 2;
+}
+
+// Compare real paths (drive-letter case differs on Windows): a missed match would
+// make `pnpm test` exit 0 having run nothing.
+const isMain = () => {
+  if (!process.argv[1]) return false;
+  const a = fs.realpathSync.native(path.resolve(process.argv[1]));
+  const b = fs.realpathSync.native(fileURLToPath(import.meta.url));
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+if (isMain()) {
+  process.exitCode = main(process.argv.slice(2));
+}
+```
+
+`os.homedir()` honours `HOME` on POSIX and `USERPROFILE` on Windows, which is how the runner test points `exec` at a sandbox home.
+
+- [ ] **Step 4: Rewire `package.json`**
+
+Replace the two script values exactly:
+
+```json
+"test": "node scripts/run-tests.mjs unit",
+"test:ui": "node scripts/run-tests.mjs ui",
+```
+
+- [ ] **Step 5: Run the runner test, then the real suite through the runner**
+
+Run: `node --test tests/kit/run-tests-runner.test.mjs`
+Expected: PASS (5/5).
+
+Run (disposable state for the run itself; the tripwire still watches your real folders):
+
+```bash
+S=$(mktemp -d "$PWD/../ak-b2.XXXXXX")
+env XDG_STATE_HOME="$S/state" LOCALAPPDATA="$S/localappdata" node scripts/run-tests.mjs unit; echo "exit=$?"
+```
+
+Expected: the same pass counts as `node --test … "tests/kit/*.test.mjs"` plus the seven `.cjs` suites, and `exit=0`. `realStateRoots` watches both the redirected `XDG_STATE_HOME` and the default `~/.local/state/agentic-kit` (and the real config folder), so your real folders stay watched; any failing report line names a real leak — stop and record it before continuing. Then `rm -rf "$S"`.
+
+- [ ] **Step 6: Update `AGENTS.md` Testing**
+
+Under "Running Tests", replace the plain `pnpm test` description with:
+
+```markdown
+`pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`, which fingerprints
+`~/.config/agentic-kit`, `~/.local/state/agentic-kit` (or `%APPDATA%`/`%LOCALAPPDATA%` on
+Windows), the Claude/Codex/OpenCode guidance files ak manages, and this repository's `.claude`,
+`.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` before and after the run. Any change fails
+the run and is listed by path. Files a live Claude Code, Ruflo or AQE session writes during the
+run are listed as "concurrent writers" and do not fail a local run; CI (or
+`AK_TRIPWIRE_STRICT=1`) fails on them too. `node scripts/run-tests.mjs exec -- <node args>`
+guards any single command the same way.
+```
+
+Run: `npx markdownlint-cli2 AGENTS.md`
+Expected: 0 errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/run-tests.mjs tests/kit/run-tests-runner.test.mjs package.json AGENTS.md
+git commit -m "test(guard): fail the suite when real user state changes"
+```
+
+### Task 1.3: The dashboard refuses its real-state defaults when fakes are injected
+
+**Files:**
+
+- Modify: `src/lib/dashboard-server.mjs` (`managementProvider` `:992-1015`, `startDashboard` destructuring `:1054-1062`, `provideMaintenance` `:1121-1128`)
+- Test: `tests/kit/dashboard-hermetic-defaults.test.mjs`
+- Modify: `docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md` (Open items → "The dashboard server's hermeticity guard has a gap": add "Fixed in Branch 2 (`<sha>`)")
+
+**Interfaces:**
+
+- Consumes: `sandboxHome`, `assertSandboxed` from `tests/kit/helpers/home-sandbox.mjs`; `waitUntil` from `tests/kit/helpers/wait-until.mjs`.
+- Produces: `startDashboard` rule — when any of `fetchStatus, usage, limits, hooks, live, transcripts, intelWatch, discoverProjects, machineWideIntel, models, system, hostReadiness` is passed and neither `maintenance` nor `maintenanceOptions.controlRoot` is, the default maintenance service is refused (503 on its routes, one `console.error` naming `maintenanceOptions.controlRoot`), and the default management facade is refused unless `management` or `managementOptions.controlRoot` is passed.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/kit/dashboard-hermetic-defaults.test.mjs
+// Audit Open item: the guard fired only for an injected maintenance service; a
+// caller that injected only a System collector still got the default
+// maintenance service and facade over the REAL control root (the
+// system-summary incident, 259f075). The home is sandboxed so a regression
+// writes the sandbox, and the test reads the sandbox to prove it did not.
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { sandboxHome, assertSandboxed, rmrf } from './helpers/home-sandbox.mjs';
+import { waitUntil } from './helpers/wait-until.mjs';
+
+const home = sandboxHome('ak-dash-hermetic');
+after(() => rmrf(home));
+const paths = await import('../../src/lib/paths.mjs');
+assertSandboxed(paths, home);
+const { startDashboard } = await import('../../src/lib/dashboard-server.mjs');
+
+function get(server, route) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(new URL(route, server.url), { headers: { 'x-dash-token': server.token } }, (res) => {
+      let body = ''; res.on('data', (c) => { body += c; }); res.on('end', () => resolve({ status: res.statusCode, body }));
+    });
+    req.on('error', reject); req.end();
+  });
+}
+
+const collector = () => ({
+  async read() { return { runtime: {}, knownFiles: [], storage: {}, projects: [], snapshot: null, scan: { running: false } }; },
+  async refreshDeep() { return { ok: true, persisted: { ok: true } }; },
+  scanState() { return { running: true, phase: 'catalog' }; },
+});
+
+test('an injected System collector alone never builds the default maintenance service', async (t) => {
+  const errors = [];
+  const realError = console.error;
+  console.error = (...a) => errors.push(a.map(String).join(' '));
+  t.after(() => { console.error = realError; });
+  const server = await startDashboard({ port: 0, cwd: home, system: collector(), usage: {} });
+  t.after(() => server.close());
+
+  const deep = await get(server, 'api/system?refresh=deep');
+  assert.equal(deep.status, 200);
+  await waitUntil(() => errors.some((e) => /maintenanceOptions\.controlRoot/.test(e)),
+    'the refused default maintenance service must be logged', { timeout: 5000 });
+  const maintenance = await get(server, 'api/maintenance');
+  assert.equal(maintenance.status, 503);
+  assert.equal(fs.existsSync(path.join(paths.maintenanceControlDir())), false,
+    `nothing may be written under ${paths.maintenanceControlDir()}`);
+  assert.equal(errors.filter((e) => /maintenanceOptions\.controlRoot/.test(e)).length, 1, 'logged once, not per request');
+});
+
+test('an explicit control root keeps the default maintenance service available to fakes', async (t) => {
+  const controlRoot = fs.mkdtempSync(path.join(home, 'control-'));
+  const server = await startDashboard({ port: 0, cwd: home, system: collector(), usage: {},
+    maintenanceOptions: { controlRoot } });
+  t.after(() => server.close());
+  const maintenance = await get(server, 'api/maintenance');
+  assert.notEqual(maintenance.status, 503, maintenance.body);
+  assert.equal(fs.existsSync(paths.maintenanceControlDir()), false);
+});
+
+test('a server with no injected collector keeps its defaults (the real command)', async (t) => {
+  const { __test } = await import('../../src/lib/dashboard-server.mjs');
+  assert.equal(__test.refusesDefaultState({}), false);
+  assert.equal(__test.refusesDefaultState({ liveOptions: {} }), false);
+  assert.equal(__test.refusesDefaultState({ system: {} }), true);
+  assert.equal(__test.refusesDefaultState({ fetchStatus: async () => ({}) }), true);
+  assert.equal(__test.refusesDefaultState({ system: {}, maintenanceOptions: { controlRoot: '/x' } }), false);
+  assert.equal(__test.refusesDefaultState({ system: {}, maintenance: {} }), false);
+});
+```
+
+If the injected `usage: {}` or the fake `read()` shape trips another route first, copy `fullPayload(3)` from `tests/kit/system-summary.test.mjs` into the fake instead of guessing; the assertions stay as written. The second test builds the real maintenance service over the thin fake collector; if that service needs collector methods the fake lacks (it then answers 503 for a different reason), give it the collector fixture `tests/kit/maintenance-dashboard-e2e.test.mjs` uses. Do not delete the case: it is the proof that the escape hatch still works.
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `node --test tests/kit/dashboard-hermetic-defaults.test.mjs`
+Expected: FAIL — the first test times out waiting for the log (the default service is built), and `maintenanceControlDir()` exists inside the sandbox; the third fails on `__test` being undefined.
+
+- [ ] **Step 3: Implement the refusal**
+
+In `src/lib/dashboard-server.mjs`, above `managementProvider`:
+
+```js
+/** Collectors a caller injects instead of the real ones. A server given any of
+ *  them is a test or an embedder with fakes; its DEFAULT maintenance service and
+ *  management facade would still write the user's real control root
+ *  (~/.local/state/agentic-kit/maintenance), which is how the system-summary
+ *  test overwrote real state (audit 2026-09-26, Open items). */
+const INJECTABLE_COLLECTORS = ['fetchStatus', 'usage', 'limits', 'hooks', 'live', 'transcripts', 'intelWatch',
+  'discoverProjects', 'machineWideIntel', 'models', 'system', 'hostReadiness'];
+
+function refusesDefaultState(opts) {
+  if (opts.maintenance !== undefined) return false;
+  if (opts.maintenanceOptions?.controlRoot !== undefined) return false;
+  return INJECTABLE_COLLECTORS.some((key) => opts[key] !== undefined);
+}
+
+const HERMETIC_REFUSAL = 'dashboard: refusing the default maintenance service — collectors were injected, so it would '
+  + 'write the real state directory; inject `maintenance` or pass maintenanceOptions.controlRoot';
+
+export const __test = { refusesDefaultState };
+```
+
+In `managementProvider`, add a `refused` parameter and, after the two `management` lines:
+
+```js
+  if (refused && managementOptions.controlRoot === undefined) return async () => null;
+```
+
+In `startDashboard`, keep the destructuring as is and compute, right after it:
+
+```js
+  const refused = refusesDefaultState({
+    fetchStatus, usage, limits, hooks, live, transcripts, intelWatch, discoverProjects, machineWideIntel,
+    models, system, hostReadiness, maintenance, maintenanceOptions,
+  });
+  let refusalLogged = false;
+```
+
+Replace the default branch of `provideMaintenance`:
+
+```js
+    ? maintenance : maintenance ? async () => maintenance : async () => {
+      if (refused) {
+        if (!refusalLogged) { refusalLogged = true; console.error(HERMETIC_REFUSAL); }
+        throw new TypeError(HERMETIC_REFUSAL);
+      }
+      const [{ createMaintenanceService }, collector] = await Promise.all([
+        import('./maintenance/service.mjs'), getSystem(),
+      ]);
+      return createMaintenanceService({ collector, ...maintenanceOptions });
+    };
+```
+
+and pass `refused` into `managementProvider({ …, refused })`. `getMaintenance` memoizes the rejected promise, so the refusal is logged once and every maintenance route answers its existing 503.
+
+- [ ] **Step 4: Run the new test, then every dashboard caller**
+
+Run: `node --test tests/kit/dashboard-hermetic-defaults.test.mjs`
+Expected: PASS (3/3).
+
+Run: `node --test tests/kit/system-summary.test.mjs tests/kit/maintenance-dashboard-e2e.test.mjs tests/kit/maintenance-dashboard-api.test.mjs tests/kit/dashboard-context-hooks.test.mjs tests/kit/host-health-api.test.mjs tests/kit/dashboard-intel-integration.test.mjs tests/kit/model-dashboard-read-model.test.mjs && node tests/dashboard.test.cjs && node tests/ui/dashboard-ui.mjs`
+Expected: all pass. A caller that now gets 503 where it expected maintenance data was relying on the real control root: give it an injected `maintenance` or a temp `maintenanceOptions.controlRoot`, and list it in the commit body.
+
+- [ ] **Step 5: Record it in the audit record**
+
+Append to the Open-items bullet "The dashboard server's hermeticity guard has a gap" the sentence: "Fixed on `fix/test-hermeticity`: a server given any injected collector refuses the default maintenance service and facade unless a control root is passed." Run `npx markdownlint-cli2 docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/lib/dashboard-server.mjs tests/kit/dashboard-hermetic-defaults.test.mjs docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+git commit -m "fix(dashboard): refuse default maintenance and management services in injected test servers"
+```
+
+### Slice 1 exit
+
+- [ ] Run the gate set from the brief (`common.md`), with `node scripts/run-tests.mjs unit` in place of the raw `node --test` line once, and the brief's `fingerprint.sh` before/after. Record counts and both fingerprint diffs in the slice report.
+
+---
+
+## Slice 2 — environment and temporary folders
+
+### Task 2.1: One sandboxed environment for every spawned child
+
+**Files:**
+
+- Modify: `tests/kit/helpers/home-sandbox.mjs` (add `INHERITED_STATE_KEYS`, `sandboxEnvFor`, `spawnEnv`, `redirectToolState`; make `sandboxHome` use `sandboxEnvFor`)
+- Create: `tests/kit/spawn-env-guard.test.mjs`
+- Modify: every file the guard names. Today: `tests/kit/provider-cli.test.mjs:75`, `usage-cli.test.mjs:183`, `host-cli-migration.test.mjs:19`, `provider-refresh-cli.test.mjs:55`, `dry-run-nudge.test.mjs:54`, `prompts-mainline-boundary.test.mjs:18`, `hook-audit.test.mjs:351,418,435`, `cli-help.test.mjs:11`, `host-health-connected.test.mjs:221`, and the remaining `...process.env` sites the guard prints (22 in total across `tests/kit` and `tests/*.cjs`).
+
+**Interfaces:**
+
+- Consumes: nothing.
+- Produces:
+
+```js
+/** Environment keys that point a child at real per-user state. */
+export const INHERITED_STATE_KEYS = ['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_DATA_HOME',
+  'XDG_CACHE_HOME', 'APPDATA', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME',
+  'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH', 'npm_config_cache'];
+/** Overrides that place every per-user base inside `home`. */
+export function sandboxEnvFor(home) → Record<string, string>
+/** process.env minus INHERITED_STATE_KEYS, plus sandboxEnvFor(home), plus `extra` (last wins). PATH is kept. */
+export function spawnEnv(home, extra = {}) → Record<string, string|undefined>
+/** For in-process tests whose code under test spawns tools: point XDG state/data/cache, LOCALAPPDATA and
+ *  TMPDIR/TEMP/TMP at a fresh folder under os.tmpdir(); restore() puts the old values back and removes it. */
+export function redirectToolState(prefix) → { base: string, restore: () => void }
+```
+
+- [ ] **Step 1: Write the failing guard**
+
+```js
+// tests/kit/spawn-env-guard.test.mjs
+// A spawned child that inherits the developer's XDG_*/LOCALAPPDATA/TMPDIR writes
+// that developer's real tool state (six files created ~/.local/state/opencode,
+// ~/.cache/opencode and ~/.local/share/opencode this way). Every child env in
+// tests/ is built by spawnEnv()/sandboxEnvFor(); a deliberate exception carries
+// the marker comment `spawn-env: inherits (<reason>)` on the same line.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { spawnEnv, sandboxEnvFor, INHERITED_STATE_KEYS } from './helpers/home-sandbox.mjs';
+
+const TESTS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SELF = fileURLToPath(import.meta.url);
+const HELPER = path.join(TESTS, 'kit', 'helpers', 'home-sandbox.mjs');
+const INHERIT = /\.\.\.\s*process\.env\b|env:\s*process\.env\b/;
+
+function files(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) { if (e.name !== 'fixtures') files(full, out); } else if (/\.(mjs|cjs|js)$/.test(e.name)) out.push(full);
+  }
+  return out;
+}
+
+test('no test builds a child environment from process.env outside the sandbox helper', () => {
+  const offenders = [];
+  for (const file of files(TESTS)) {
+    if (file === SELF || file === HELPER) continue;
+    fs.readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+      if (INHERIT.test(line) && !/spawn-env: inherits \(.+\)/.test(line)) offenders.push(`${path.relative(TESTS, file)}:${i + 1}`);
+    });
+  }
+  assert.deepEqual(offenders, [], `use spawnEnv(home, extra) from tests/kit/helpers/home-sandbox.mjs:\n  ${offenders.join('\n  ')}`);
+});
+
+const tempHome = (t) => {
+  const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-spawn-env-')));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+};
+
+test('spawnEnv pins every per-user base inside the sandbox, whatever the parent exported', (t) => {
+  const home = tempHome(t);
+  const env = spawnEnv(home, { EXTRA: '1' });
+  for (const key of ['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME',
+    'APPDATA', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP', 'npm_config_cache']) {
+    assert.ok(env[key] && env[key].startsWith(home), `${key}=${env[key]} escapes ${home}`);
+  }
+  for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH']) {
+    assert.equal(env[key], undefined, `${key} must not be inherited`);
+  }
+  assert.equal(env.PATH, process.env.PATH);
+  assert.equal(env.EXTRA, '1');
+  assert.deepEqual(Object.keys(sandboxEnvFor(home)).sort(),
+    INHERITED_STATE_KEYS.filter((k) => !['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH'].includes(k)).sort());
+});
+
+test('a real child sees the sandboxed state base, not the parent one', (t) => {
+  const home = tempHome(t);
+  const r = spawnSync(process.execPath, ['-e', 'console.log(JSON.stringify([process.env.XDG_STATE_HOME, require("os").tmpdir()]))'],
+    { env: spawnEnv(home), encoding: 'utf8' });
+  const [state, tmp] = JSON.parse(r.stdout);
+  assert.ok(state.startsWith(home));
+  assert.ok(tmp.startsWith(home));
+});
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `node --test tests/kit/spawn-env-guard.test.mjs`
+Expected: FAIL — `spawnEnv` is not exported; after adding it, the first test lists the 22 offending lines.
+
+- [ ] **Step 3: Implement the helpers in `tests/kit/helpers/home-sandbox.mjs`**
+
+```js
+export const INHERITED_STATE_KEYS = ['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_DATA_HOME',
+  'XDG_CACHE_HOME', 'APPDATA', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME',
+  'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH', 'npm_config_cache'];
+
+export function sandboxEnvFor(home) {
+  const cfg = path.join(home, '.config');
+  const tmp = path.join(home, 'tmp');
+  return {
+    HOME: home, USERPROFILE: home,
+    XDG_CONFIG_HOME: cfg, APPDATA: cfg,
+    XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    XDG_DATA_HOME: path.join(home, '.local', 'share'),
+    XDG_CACHE_HOME: path.join(home, '.cache'),
+    LOCALAPPDATA: path.join(home, 'AppData', 'Local'),
+    TMPDIR: tmp, TEMP: tmp, TMP: tmp,
+    npm_config_cache: path.join(home, '.npm'),
+  };
+}
+
+export function spawnEnv(home, extra = {}) {
+  const base = { ...process.env }; // spawn-env: inherits (the one sanctioned copy; state keys are removed below)
+  for (const key of INHERITED_STATE_KEYS) delete base[key];
+  fs.mkdirSync(path.join(home, 'tmp'), { recursive: true });
+  return { ...base, ...sandboxEnvFor(home), ...extra };
+}
+
+export function redirectToolState(prefix) {
+  const base = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-tools-`)));
+  const keys = ['XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP'];
+  const previous = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+  const tmp = path.join(base, 'tmp');
+  fs.mkdirSync(tmp);
+  Object.assign(process.env, {
+    XDG_STATE_HOME: path.join(base, 'state'), XDG_DATA_HOME: path.join(base, 'data'),
+    XDG_CACHE_HOME: path.join(base, 'cache'), LOCALAPPDATA: path.join(base, 'localappdata'),
+    TMPDIR: tmp, TEMP: tmp, TMP: tmp,
+  });
+  return {
+    base,
+    restore() {
+      for (const [key, value] of Object.entries(previous)) {
+        if (value === undefined) delete process.env[key]; else process.env[key] = value;
+      }
+      fs.rmSync(base, { recursive: true, force: true, maxRetries: 3 });
+    },
+  };
+}
+```
+
+Make `sandboxHome(prefix)` call `Object.assign(process.env, sandboxEnvFor(home))` for the keys it sets today and keep its extra lines (`PATH`, `NO_COLOR`, the three deletes). Do not set `TMPDIR` inside `sandboxHome` in this task (in-process `os.tmpdir()` changes would move every later `mkdtempSync` of that file into the sandbox home; that is Task 2.3's decision, file by file).
+
+- [ ] **Step 4: Convert each offender**
+
+Pattern for a CLI helper (example `tests/kit/provider-cli.test.mjs:70-85`):
+
+```js
+function ak(args, { cwd, home, env = {} }) {
+  return spawnSync(process.execPath, [BIN, ...args], {
+    encoding: 'utf8',
+    cwd,
+    env: spawnEnv(home, { NO_COLOR: '1', ...env }),
+  });
+}
+```
+
+Keep each file's own extra keys (`PATH`, cleared credentials, `OPENROUTER_MANAGEMENT_KEY: ''`) in `extra`. For `provider-refresh-cli.test.mjs:55-59`, strip `ALL_CREDENTIAL_ENV` from the result of `spawnEnv` before returning. For `cli-help.test.mjs:11` (no home today), create one `sandboxProject`-style home at module scope with `after(() => rmrf(home))`. `home-sandbox.mjs` is ESM: a `.cjs` suite cannot `require` it; load it with `const { spawnEnv } = await import(pathToFileURL(…).href)` inside the suite's async `main()`, the pattern `tests/dashboard.test.cjs:139` already uses. Where a file genuinely needs the parent environment (for example `tests/live/*` that must reach the real `ruflo`), add the marker comment with the reason instead.
+
+- [ ] **Step 5: Run the guard and every converted file**
+
+Run: `node --test tests/kit/spawn-env-guard.test.mjs` then `node --test` on each converted file, then `node tests/<name>.test.cjs` for converted `.cjs` suites.
+Expected: PASS everywhere, the guard reports no offenders.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/kit/helpers/home-sandbox.mjs tests/kit/spawn-env-guard.test.mjs <each converted file by name>
+git commit -m "test(env): stop spawn tests inheriting the developer's XDG_* variables"
+```
+
+### Task 2.2: Six tests stop creating OpenCode's real state, data, cache and temp folders
+
+**Files:**
+
+- Modify: `tests/kit/integration-command-facts.test.mjs`, `tests/kit/opencode.test.mjs`, `tests/kit/provider-credentials.test.mjs` (in-process: `redirectToolState`)
+- Modify: `tests/kit/opencode-stock-ruflo-gateway.test.mjs`, `tests/kit/provider-cli.test.mjs`, `tests/kit/provider-refresh-cli.test.mjs` (direct spawns: must already use `spawnEnv` after Task 2.1; verify the OpenCode spawn at `opencode-stock-ruflo-gateway.test.mjs:391` passes `spawnEnv(…)`)
+- Create: `tests/kit/opencode-state-hermeticity.test.mjs`
+
+**Interfaces:**
+
+- Consumes: `redirectToolState(prefix)`, `spawnEnv(home, extra)` from Task 2.1.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/kit/opencode-state-hermeticity.test.mjs
+// Six test files created OpenCode's own folders under the developer's
+// XDG_STATE_HOME/XDG_CACHE_HOME/XDG_DATA_HOME and TMPDIR (per-file probe,
+// Branch 2 plan). Runs the three in-process ones with those bases pointed at a
+// watched folder and requires the folder to stay empty. The three direct-spawn
+// files are covered by spawn-env-guard.test.mjs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const KIT = path.dirname(fileURLToPath(import.meta.url));
+const IN_PROCESS = ['integration-command-facts', 'opencode', 'provider-credentials'];
+
+for (const name of IN_PROCESS) {
+  test(`${name}.test.mjs leaves the inherited tool-state bases untouched`, { timeout: 300_000 }, (t) => {
+    const watched = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-oc-watch-')));
+    t.after(() => fs.rmSync(watched, { recursive: true, force: true }));
+    for (const d of ['state', 'data', 'cache', 'tmp']) fs.mkdirSync(path.join(watched, d));
+    const r = spawnSync(process.execPath, ['--test', path.join(KIT, `${name}.test.mjs`)], {
+      encoding: 'utf8',
+      env: { ...process.env, // spawn-env: inherits (this test measures exactly what an inheriting run leaks)
+        XDG_STATE_HOME: path.join(watched, 'state'), XDG_DATA_HOME: path.join(watched, 'data'),
+        XDG_CACHE_HOME: path.join(watched, 'cache'), TMPDIR: path.join(watched, 'tmp'),
+        TEMP: path.join(watched, 'tmp'), TMP: path.join(watched, 'tmp') },
+    });
+    assert.equal(r.status, 0, r.stdout + r.stderr);
+    const leaked = ['state', 'data', 'cache', 'tmp'].flatMap((d) => fs.readdirSync(path.join(watched, d))
+      .filter((n) => n !== 'node-compile-cache').map((n) => `${d}/${n}`));
+    assert.deepEqual(leaked, []);
+  });
+}
+```
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `node --test tests/kit/opencode-state-hermeticity.test.mjs`
+Expected: FAIL for all three with `leaked` containing `state/opencode`, `data/opencode`, `cache/opencode`, `tmp/opencode`.
+
+- [ ] **Step 3: Fix the three in-process files**
+
+At module scope in each (after the imports; `paths.mjs` reads these variables lazily, so static imports are fine):
+
+```js
+import { after } from 'node:test';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
+
+// Code under test spawns the real `opencode` with process.env; keep its
+// state/data/cache/temp folders out of the developer's real ones.
+const toolState = redirectToolState('ak-<file-name>');
+after(() => toolState.restore());
+```
+
+If a test in these files asserts on `os.tmpdir()`-relative paths created before the redirect, move the redirect above those module-scope `mkdtempSync` calls.
+
+- [ ] **Step 4: Prove the direct-spawn three with the per-file probe**
+
+Run for each of `opencode-stock-ruflo-gateway`, `provider-cli`, `provider-refresh-cli`:
+
+```bash
+W=$(mktemp -d "$PWD/../ak-oc.XXXXXX"); mkdir -p "$W"/{state,data,cache,tmp}
+env XDG_STATE_HOME="$W/state" XDG_DATA_HOME="$W/data" XDG_CACHE_HOME="$W/cache" TMPDIR="$W/tmp" node --test tests/kit/<name>.test.mjs
+find "$W" -mindepth 2 -maxdepth 2 ! -name node-compile-cache; rm -rf "$W"
+```
+
+Expected: the `find` prints nothing. If one prints `opencode`, that file still has a spawn without `spawnEnv`: fix it, and extend `spawn-env-guard` if its pattern missed the form.
+
+- [ ] **Step 5: Run the new test and the six files**
+
+Run: `node --test tests/kit/opencode-state-hermeticity.test.mjs tests/kit/integration-command-facts.test.mjs tests/kit/opencode.test.mjs tests/kit/provider-credentials.test.mjs tests/kit/opencode-stock-ruflo-gateway.test.mjs tests/kit/provider-cli.test.mjs tests/kit/provider-refresh-cli.test.mjs`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add tests/kit/opencode-state-hermeticity.test.mjs tests/kit/integration-command-facts.test.mjs tests/kit/opencode.test.mjs tests/kit/provider-credentials.test.mjs <any direct-spawn file changed in Step 4>
+git commit -m "test(opencode): stop six tests creating \$XDG_STATE_HOME/opencode"
+```
+
+### Task 2.3: Every test removes the temporary folders it creates
+
+**Files:**
+
+- Create: `tests/kit/helpers/temp-dir.mjs`
+- Modify: the 59 files in the leak table (use `tempDir(prefix, t)` or an `after()` removal; statusline: its two shared cache files)
+- Test: `tests/kit/temp-dir-helper.test.mjs`
+
+**Interfaces:**
+
+- Produces: `export function tempDir(prefix, t)` — `fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix + '-')))`, removed by `t.after` (or the file-level `after` when `t` is omitted), with `maxRetries: 3` for Windows `EBUSY`; the caller must `process.chdir` out of it first if it chdir-ed in.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// tests/kit/temp-dir-helper.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import { tempDir } from './helpers/temp-dir.mjs';
+
+let fromTest;
+test('a per-test temp folder exists during the test', (t) => {
+  fromTest = tempDir('ak-tempdir-probe', t);
+  assert.ok(fs.statSync(fromTest).isDirectory());
+  assert.ok(fromTest.startsWith(fs.realpathSync(os.tmpdir())));
+});
+test('and is gone after it', () => {
+  assert.equal(fs.existsSync(fromTest), false);
+});
+```
+
+- [ ] **Step 2: Run it to verify it fails** — `node --test tests/kit/temp-dir-helper.test.mjs` → FAIL (module missing).
+
+- [ ] **Step 3: Implement the helper**
+
+```js
+// tests/kit/helpers/temp-dir.mjs
+// A temp folder that removes itself. 59 test files left 700+ folders behind per
+// run (Branch 2 probe); this is the one way to make one.
+import { after } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function tempDir(prefix, t) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`)));
+  const remove = () => fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  if (t) t.after(remove); else after(remove);
+  return dir;
+}
+```
+
+- [ ] **Step 4: Fix the leakers, file by file**
+
+For each file in the leak table replace `fs.mkdtempSync(path.join(os.tmpdir(), 'ak-x-'))` with `tempDir('ak-x', t)` inside tests, or `tempDir('ak-x')` at module scope. Where a helper returns a temp dir without a `t` (e.g. `quota.test.mjs:17` `tmp()`, `live-service.test.mjs:9`), thread `t` through or register with the file-level `after`. `sandboxHome()` homes: add `after(() => rmrf(home))` beside each call that lacks it (`about-install-edits`, `brain-held-refresh`, `routing-retirement-convergence`, `sync-self-freshness`, `ruflo-components-convergence`, `sync-host-repair`, `statusline-config-dir-parity`, …). For `statusline.test.mjs`, run the rendering under `redirectToolState('ak-sl')` so `ruflo-daemon-count.json` and `ruvnet-brain-kb-size.json` (`src/lib/daemons.mjs:276`, `src/templates/statusline-footer.cjs:423,501`) land in its own temp folder and never in the live footer's cache.
+
+After each batch of about ten files, re-run the probe for that batch:
+
+```bash
+P=$(mktemp -d "$PWD/../ak-leak.XXXXXX")
+for f in <batch>; do D=$(mktemp -d "$P/$f.XXXXXX"); env TMPDIR="$D" node --test "tests/kit/$f.test.mjs" >/dev/null 2>&1 || echo "FAIL $f"; n=$(ls -A "$D" | grep -v '^node-compile-cache$' | wc -l); [ "$n" -eq 0 ] || echo "LEAK $f: $(ls -A "$D" | grep -v node-compile-cache | tr '\n' ' ')"; done
+rm -rf "$P"
+```
+
+Expected: no `FAIL`, no `LEAK` lines. Keep `P` under the worktree's parent (user-owned, not inside a git repository, not under `/private/tmp`; see "Probe side findings").
+
+- [ ] **Step 5: Commit** (one commit for the helper plus all files; list the file count in the body)
+
+```bash
+git add tests/kit/helpers/temp-dir.mjs tests/kit/temp-dir-helper.test.mjs <each changed file by name>
+git commit -m "test(temp): remove every temporary folder a test creates"
+```
+
+### Task 2.4: The suite runs in its own templated temp root and fails on leftovers
+
+Replaces program-plan item 5 ("create temporary folders from a template"): the suite, not a shell, is where a template belongs.
+
+**Files:**
+
+- Modify: `scripts/run-tests.mjs` (`runGuarded`)
+- Modify: `tests/kit/run-tests-runner.test.mjs` (two tests)
+- Modify: `AGENTS.md` (one sentence in the Testing paragraph from Task 1.2)
+
+**Interfaces:**
+
+- Consumes: `runGuarded` from Task 1.2.
+- Produces: `runGuarded(commands, opts)` (same signature) — creates `fs.mkdtempSync(path.join(os.tmpdir(), "ak-suite-"))`, passes it as `TMPDIR`/`TEMP`/`TMP` to every command, refuses to start (exit 2) when it lies inside a git repository, and after the commands fails with exit 4 naming every leftover entry except `node-compile-cache`; it always removes the root.
+
+- [ ] **Step 1: Write the failing tests** (append to `tests/kit/run-tests-runner.test.mjs`)
+
+```js
+test('a leftover temp folder fails the run and is named', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leaky = stub(home, 'leaky.mjs', `import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path';
+    fs.mkdtempSync(path.join(os.tmpdir(), 'ak-leaky-'));`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leaky], { env, encoding: 'utf8' });
+  assert.equal(r.status, 4, r.stderr);
+  assert.match(r.stderr, /ak-leaky-/);
+});
+
+test('the runner refuses a temp root inside a git repository', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const inside = path.join(repo, 'tmp');
+  fs.mkdirSync(inside);
+  const ok = stub(home, 'ok.mjs', '');
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', ok], { env: { ...env, TMPDIR: inside, TEMP: inside, TMP: inside }, encoding: 'utf8' });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /inside the git repository/);
+});
+```
+
+- [ ] **Step 2: Run** — `node --test tests/kit/run-tests-runner.test.mjs` → the two new tests FAIL (exit 0).
+
+- [ ] **Step 3: Implement** in `runGuarded` before the snapshot (`fs` is already imported since Task 1.2):
+
+```js
+  const tempRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-suite-')));
+  const enclosing = enclosingRepository(tempRoot);
+  if (enclosing) {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+    log(`the suite temp root ${tempRoot} is inside the git repository ${enclosing}; tests that probe "outside a `
+      + 'git repository" would write into it. Point TMPDIR outside any repository.');
+    return 2;
+  }
+  const childEnv = { ...env, TMPDIR: tempRoot, TEMP: tempRoot, TMP: tempRoot };
+```
+
+use `childEnv` for the spawns, and after the commands (before the real-state compare):
+
+```js
+  const leftovers = fs.readdirSync(tempRoot).filter((name) => name !== 'node-compile-cache');
+  fs.rmSync(tempRoot, { recursive: true, force: true, maxRetries: 3 });
+  if (leftovers.length) log(`temp folders left behind by the run (${leftovers.length}):\n  ${leftovers.join('\n  ')}`);
+```
+
+and return `code || (result.failing.length ? 3 : 0) || (leftovers.length ? 4 : 0)`. Add:
+
+```js
+function enclosingRepository(dir) {
+  for (let cur = dir, i = 0; i < 64; i++) {
+    if (fs.existsSync(path.join(cur, '.git'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
+}
+```
+
+- [ ] **Step 4: Run the runner tests, then the whole unit suite through the runner** (disposable state as in Task 1.2 Step 5).
+Expected: PASS; the full run reports no leftovers (Task 2.3 fixed them) and exits 0. Any leftover it lists is fixed in its file, in this task.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/run-tests.mjs tests/kit/run-tests-runner.test.mjs AGENTS.md
+git commit -m "test(runner): run the suite in its own temporary folder and fail on leftovers"
+```
+
+### Task 2.5: No test writes into an enclosing repository
+
+**Files:**
+
+- Modify: `tests/kit/aqe-embedding-projection.test.mjs:200-222`, `tests/kit/status-aqe-drift.test.mjs:98-100` (and every other "outside a git repository" test the probe below finds)
+- Modify: `tests/kit/opencode-stock-ruflo-gateway.test.mjs` (the workspace OpenCode runs in gets its own `.git`)
+- Test: the probe command below plus an in-file precondition
+
+**Interfaces:**
+
+- Consumes: `repoRoot` from `src/lib/paths.mjs` (read-only use in the precondition).
+
+- [ ] **Step 1: Reproduce (the failing check)**
+
+```bash
+F=$(mktemp -d "$PWD/../ak-encl.XXXXXX"); mkdir "$F/.git" "$F/tmp"
+for f in aqe-embedding-projection status-aqe-drift; do env TMPDIR="$F/tmp" node --test "tests/kit/$f.test.mjs" >/dev/null 2>&1; done
+find "$F" -mindepth 1 -maxdepth 2 ! -path "$F/tmp*" ! -path "$F/.git"; rm -rf "$F"
+```
+
+Expected before the fix: `.claude/settings.local.json`, `.claude/settings.local.json.agentic-kit-aqe-embedding.json`, `.agentic-qe/llm-config.json` appear in `$F` (the fake enclosing repository). Also run `grep -rln "rmSync(path.join(.*'.git')" tests/kit` and `grep -rn "noproj\|outside a git" tests/kit` to find every sibling case; include them.
+
+- [ ] **Step 2: Add a precondition to each "outside a git repository" test**
+
+```js
+import { repoRoot } from '../../src/lib/paths.mjs';
+// …inside the test, right after the fixture's .git is removed (or the no-project dir is made):
+const enclosing = repoRoot(cwd);
+if (enclosing) { t.skip(`TMPDIR is inside the git repository ${enclosing}; this case would write into it`); return; }
+```
+
+(`status-aqe-drift.test.mjs` imports kit modules dynamically after `sandboxHome`; import `repoRoot` the same way there.)
+
+- [ ] **Step 3: Give OpenCode's workspace its own repository** — in `opencode-stock-ruflo-gateway.test.mjs`, right after the workspace temp folder is created, `fs.mkdirSync(path.join(workspace, '.git'))` with a comment citing `review-hermeticity.md` (OpenCode edited the enclosing `package.json`, created `package-lock.json` and replaced `node_modules`).
+
+- [ ] **Step 4: Re-run Step 1's probe** — Expected: `find` prints nothing; the two files report the precondition skips; with the default `TMPDIR` they pass with no skips (`node --test tests/kit/aqe-embedding-projection.test.mjs tests/kit/status-aqe-drift.test.mjs tests/kit/opencode-stock-ruflo-gateway.test.mjs`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/kit/aqe-embedding-projection.test.mjs tests/kit/status-aqe-drift.test.mjs tests/kit/opencode-stock-ruflo-gateway.test.mjs <siblings found>
+git commit -m "test(isolation): never write an enclosing repository from a temp project"
+```
+
+### Task 2.6: The memory-routing live test runs in a disposable home
+
+**Files:**
+
+- Modify: `tests/live/ruflo-memory-routing.test.mjs`
+- Modify: `docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md` ("Not run" → memory-routing bullet: runs in a disposable home now; the qe-court live test stays manual because it is paid)
+
+**Interfaces:**
+
+- Consumes: `sandboxHome` (home-sandbox.mjs), `createDisposableMemoryProject` (`tests/live/disposable-memory-project.mjs`).
+
+- [ ] **Step 1: Write the failing assertion first** — add to the test, before `ruflo memory init`, an assertion that the home the probe uses is disposable:
+
+```js
+assert.ok(paths.home.startsWith(fs.realpathSync(os.tmpdir())), `the live probe must run in a disposable home, not ${paths.home}`);
+```
+
+with `paths` imported dynamically. Run `node --test tests/live/ruflo-memory-routing.test.mjs` → FAIL (real home) when `ruflo` is on PATH; if it is not, the test skips — say so in the report and prove the change with Step 4's fingerprint instead.
+
+- [ ] **Step 2: Rewrite the module head**
+
+```js
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { sandboxHome, rmrf } from '../kit/helpers/home-sandbox.mjs';
+
+const hasRuflo = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['ruflo'], { stdio: 'ignore' }).status === 0;
+// Disposable home: sandboxHome() redirects HOME/XDG_*/APPDATA/LOCALAPPDATA and
+// blanks PATH; the real `ruflo` is still needed, so PATH is restored.
+const realPath = process.env.PATH;
+const home = sandboxHome('ak-live-routing');
+process.env.PATH = realPath;
+after(() => rmrf(home));
+const paths = await import('../../src/lib/paths.mjs');
+const { probeProjectMemoryRoutes } = await import('../../src/commands/x/verify.mjs');
+const { installedRoutingVersion, memoryRoutingObserved } = await import('../../src/lib/ruflo-memory-contract.mjs');
+const { createDisposableMemoryProject } = await import('./disposable-memory-project.mjs');
+```
+
+and in the test replace the temp-folder + `ruflo memory init` lines with:
+
+```js
+  const project = await createDisposableMemoryProject({ prefix: 'ak-live-routing-' });
+  t.after(() => project.remove());
+  const observation = await probeProjectMemoryRoutes(project.root, project.env, `live-${process.pid}`);
+```
+
+Read `disposable-memory-project.mjs` for the exact returned field names (`root`, `env`, and the removal function) and use them as they are; do not add a second removal path. If `installedRoutingVersion()` reads the global npm root through `HOME`-relative paths, check it still finds the installed Ruflo (mise installs live under the real `~/.local/share/mise`, reached through `PATH`, not `HOME`); if it does not, pass the real global root explicitly and note it in the commit body.
+
+- [ ] **Step 3: Run it** — `env -u XDG_CONFIG_HOME -u XDG_DATA_HOME -u XDG_CACHE_HOME -u XDG_STATE_HOME node --test tests/live/ruflo-memory-routing.test.mjs` with the brief's `fingerprint.sh` before/after plus `ls -la ~/.claude-flow ~/.swarm 2>/dev/null` before/after.
+Expected: PASS (or skip without `ruflo`); fingerprint diff empty; no new entries in `~/.claude-flow`/`~/.swarm`.
+
+- [ ] **Step 4: Update the audit record's "Not run" bullet**, then `npx markdownlint-cli2` on it.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/live/ruflo-memory-routing.test.mjs docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+git commit -m "test(live): run the memory-routing live test in a disposable home"
+```
+
+### Slice 2 exit
+
+- [ ] Gate set from the brief, plus `node scripts/run-tests.mjs unit` once without any `XDG_*` redirect (the tripwire is now the guard) and the brief's fingerprint before/after. Record counts, the runner's report (it must be empty or list only concurrent writers), and the fingerprint diff.
+
+---
+
+## Slice 3 — UI checks
+
+### Task 3.1: The polyglot card check matches all-language wrapping, and both Maintenance UI specs join `test:ui`
+
+**Files:**
+
+- Modify: `tests/ui/maintenance-focus.mjs:84-100` (and its `/tmp` screenshots at `:71,80,96,99`)
+- Modify: `tests/ui/maintenance-guidance.mjs:50` (`/tmp` screenshot)
+- Modify: `scripts/run-tests.mjs` (`SUITES.ui[1]`: add `tests/ui/maintenance-focus.mjs`, `tests/ui/maintenance-guidance.mjs`)
+- Modify: `tests/kit/run-tests-runner.test.mjs` (the `SUITES` test lists the two files)
+- Modify: `docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md` ("UI suite outside `test:ui`" bullet: resolved, with the cause)
+
+- [ ] **Step 1: Confirm the failure and its cause** — `node --test tests/ui/maintenance-focus.mjs` → "polyglot cards…" fails `0 !== 3`. Add `page.on('pageerror', e => errors.push(e.message))` before `addScriptTag` and assert `errors` is empty: it now fails with `mntProjectKindBadge is not defined` — the evidence for the commit body.
+
+- [ ] **Step 2: Rewrite the test to the product contract (DDD-09, `docs/LANGUAGE-LOGOS.md:11-12`)**
+
+```js
+test('polyglot cards show every language as a labelled, wrapping icon with no disclosure', async (t) => {
+  const browser = await chromium.launch({ channel: 'chrome', headless: true }); t.after(() => browser.close());
+  const page = await browser.newPage({ viewport: { width: 1100, height: 650 } });
+  const errors = []; page.on('pageerror', (e) => errors.push(e.message));
+  const languages = [['rust','Rust'],['typescript','TypeScript'],['javascript','JavaScript'],['python','Python'],['java','Java']]
+    .map(([id, name]) => ({ id, name, evidence: 'source' }));
+  const state = { facets: {}, query: { navigation: { level: 'project', nodes: [{ value: 'prj_example', label: 'billing-service', count: 24, projectKind: 'git', languages }] }, groups: [] } };
+  await page.setContent('<!doctype html><html data-theme="dark"><head><style>' + CSS + '</style></head><body><main style="padding:32px"><h2>Projects</h2><div id="cards"></div></main></body></html>');
+  await page.addScriptTag({ content: 'var MNT=' + JSON.stringify(state) + ';var MNT_SCOPE_LABELS={};function esc(s){return String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;");}function mntKindLabel(s){return s;}function mntFacetValueLabel(_,s){return s;}function mntIcon(){return "";}function mntAvailableTo(){return "";}\n'
+    + source('maintenance-language-logos') + '\n' + source('maintenance-cards') + '\n' + source('maintenance-focus')
+    + '\ndocument.getElementById("cards").innerHTML=renderMntFocusResults(false);' });
+  assert.deepEqual(errors, []);
+  assert.equal(await page.locator('.mnt-language-icon:visible').count(), 5);
+  assert.equal(await page.locator('.mnt-language-more').count(), 0);
+  assert.equal(await page.getByText(/more languages/).count(), 0);
+  assert.equal(await page.getByRole('img', { name: 'Python — Source language detected', exact: true }).isVisible(), true);
+  await page.setViewportSize({ width: 390, height: 844 });
+  assert.equal(await page.evaluate(() => document.documentElement.scrollWidth > innerWidth), false, 'icons wrap instead of overflowing');
+  fs.mkdirSync(SHOTS, { recursive: true });
+  await page.screenshot({ path: path.join(SHOTS, 'polyglot-projects.png') });
+});
+```
+
+If loading `maintenance-cards` whole pulls in more undefined helpers (check `errors`), stub `mntProjectKindBadge` alone instead (`function mntProjectKindBadge(k){return '<span class="mnt-project-kind">'+esc(k)+'</span>';}`) and say which in the commit body. Define at the top of the file `const SHOTS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.ui-artifacts');` (add the `path`/`fileURLToPath` imports) and point every other `/tmp/ak-…png` in this file and in `maintenance-guidance.mjs` at `path.join(SHOTS, '<same-name-without-ak->.png')`.
+
+- [ ] **Step 3: Run** — `node --test tests/ui/maintenance-focus.mjs tests/ui/maintenance-guidance.mjs` → PASS (3/3). Then add both files to `SUITES.ui[1]` and to the runner test's expectation; `node --test tests/kit/run-tests-runner.test.mjs` → PASS; `node scripts/run-tests.mjs ui` (disposable `XDG_STATE_HOME`) → PASS.
+
+- [ ] **Step 4: Audit record** — mark "UI suite outside `test:ui`" resolved: stale harness stub plus the DDD-09 contract; both specs now in `test:ui`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/ui/maintenance-focus.mjs tests/ui/maintenance-guidance.mjs scripts/run-tests.mjs tests/kit/run-tests-runner.test.mjs docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+git commit -m "test(ui): check polyglot cards against all-language wrapping and run both Maintenance specs in test:ui"
+```
+
+### Task 3.2: A closing health dialog never pulls focus off the next badge
+
+**Files:**
+
+- Modify: `src/lib/dashboard/client/host-readiness.mjs:169` (the `close` handler)
+- Modify: `tests/ui/host-readiness.mjs` (new deterministic test; `/tmp` screenshots at `:67,70,184` → `.ui-artifacts/`)
+- Modify: `src/lib/dashboard/page.mjs` only if the embedded client copy is generated from the module (check how `renderPage` embeds `host-readiness.mjs`; the UI spec reads the module file directly)
+
+- [ ] **Step 1: Write the deterministic failing test** (append to `tests/ui/host-readiness.mjs`, reusing its `report()`, `source()`, route setup)
+
+```js
+test('a dialog close that lands after the user moved on does not steal focus back', async t => {
+  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  t.after(() => browser.close());
+  const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
+  await page.route('http://health.test/**', route => route.fulfill({ contentType: 'text/html',
+    body: renderPage({ name: 'Health fixture', version: 'test' }).replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '') }));
+  await page.goto('http://health.test/');
+  await page.addScriptTag({ content: `${esc.toString()}\nfunction authHeaders(){return {};}\n${source('usage')}\n${source('host-readiness')}\nwireHostHealth();` });
+  await page.evaluate(data => globalThis.renderHostReadiness(data), report());
+  await page.locator('[data-health-host="claude"]').click();
+  // The race, made deterministic: close the dialog and move focus in the SAME
+  // task, then let the queued `close` event run.
+  const focused = await page.evaluate(async () => {
+    const dialog = document.getElementById('host-health-dialog');
+    const next = document.querySelector('[data-health-host="codex"]');
+    dialog.close();
+    next.focus();
+    await new Promise(resolve => setTimeout(resolve, 0)); // one task: the queued close event runs first
+    return document.activeElement && document.activeElement.getAttribute('data-health-host');
+  });
+  assert.equal(focused, 'codex');
+});
+```
+
+The `setTimeout(…, 0)` here is a task-queue flush that orders the queued `close` event before the read, not a wait for time; it is the reproduction, not the fix.
+
+- [ ] **Step 2: Run** — `node --test tests/ui/host-readiness.mjs` → the new test FAILS (`'claude' !== 'codex'`), proving the mechanism behind `fix-wave-2.md:171`.
+
+- [ ] **Step 3: Fix the product**
+
+```js
+  // Return focus to the badge that opened the dialog — but only when focus is
+  // still in the dialog or nowhere. The `close` event is a queued task; a user
+  // (or a fast keyboard sequence) may already have moved on to another badge.
+  dialog.addEventListener('close', function () {
+    var active = document.activeElement;
+    if (active && active !== document.body && !dialog.contains(active)) return;
+    var button = region.querySelector('[data-health-host="' + HEALTH_HOST + '"]');
+    if (button) button.focus();
+  });
+```
+
+- [ ] **Step 4: Harden the existing loop without sleeps** — in the first test's per-host loop, after `page.keyboard.press('Escape')`, wait for the dialog to be closed and the badge focused as a condition:
+
+```js
+    await page.waitForFunction(h => !document.getElementById('host-health-dialog').open
+      && document.activeElement === document.querySelector('[data-health-host="' + h + '"]'), host);
+```
+
+and after `Enter`, wait for the title instead of reading it once:
+
+```js
+    await page.waitForFunction(n => document.getElementById('host-health-dialog').open
+      && document.getElementById('host-health-title').textContent === n + ' health', name);
+```
+
+Replace the three `/tmp/ak-health-*.png` paths with `.ui-artifacts/` paths as in Task 3.1.
+
+- [ ] **Step 5: Run it repeatedly** — `for i in $(seq 1 20); do node --test tests/ui/host-readiness.mjs >/dev/null 2>&1 || echo "FAIL run $i"; done` → no `FAIL` lines; also run `node --test tests/kit/*host-readiness*.test.mjs tests/kit/dashboard-*.test.mjs` if any unit test covers the client.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/lib/dashboard/client/host-readiness.mjs tests/ui/host-readiness.mjs
+git commit -m "fix(dashboard): keep a closing health dialog from pulling focus off the next badge"
+```
+
+### Task 3.3: The results list says when it is busy, and MNT-UX-007 waits for it
+
+**Files:**
+
+- Modify: `src/lib/dashboard/client/maintenance-inventory.mjs:47-78` (`mntRunInventoryQuery`)
+- Modify: `tests/ui/dashboard-ui.mjs` (the `/api/maintenance/v2/` route mock at `:1468`, and the MNT-UX-007 block at `:2397-2413`)
+
+- [ ] **Step 1: Make the race permanent and deterministic in the test (the failing test)**
+
+In `tests/ui/dashboard-ui.mjs`, next to `let activeMaintenanceInventory = …` (`:1407`), add:
+
+```js
+  // Holds the NEXT inventory response until released, so a check can order
+  // "focus a row" before "the list re-renders" on every run instead of by luck.
+  let holdNextInventory = null;
+```
+
+In the route mock's `GET /api/maintenance/v2/inventory` branch, first line:
+
+```js
+      if (holdNextInventory) { const gate = holdNextInventory; holdNextInventory = null; await gate; }
+```
+
+Replace the MNT-UX-007 lead-in (`:2397-2409`) with:
+
+```js
+    const requestsBefore = maintenanceInventoryRequests.length;
+    let releaseInventory;
+    holdNextInventory = new Promise((resolve) => { releaseInventory = resolve; });
+    await page.click('#mnt-clear-all');
+    await page.waitForFunction(() => document.querySelectorAll('#mnt-chips .mnt-chip').length === 0);
+    check('MNT-UX-007a: the results list is marked busy while its query is in flight',
+      await page.getAttribute('#mnt-results', 'aria-busy') === 'true',
+      `aria-busy read ${JSON.stringify(await page.getAttribute('#mnt-results', 'aria-busy'))}`);
+    releaseInventory();
+    await page.waitForFunction(() => document.getElementById('mnt-results')?.getAttribute('aria-busy') === 'false');
+    // The gate holds only the NEXT request; if Clear all ever issues two, the
+    // unheld one could render first and make this check meaningless.
+    check('MNT-UX-007b: Clear all issues exactly one inventory query',
+      maintenanceInventoryRequests.length === requestsBefore + 1,
+      `inventory requests grew by ${maintenanceInventoryRequests.length - requestsBefore}`);
+    check('MNT-UX-002: Clear all removes every active facet at once',
+      (await page.evaluate(() => location.hash)).indexOf('facet.') < 0,
+      'Clear all left a facet value in the URL');
+
+    // ── Roving tab stop + keyboard navigation over the results list ──
+    await page.locator('#mnt-results [data-mnt-plc]').first().focus();
+    const rovingBefore = await page.$$eval('#mnt-results [data-mnt-plc]',
+      (rows) => rows.map((row) => row.tabIndex));
+    await page.keyboard.press('ArrowDown');
+    await page.waitForFunction(() => {
+      const rows = [...document.querySelectorAll('#mnt-results [data-mnt-plc]')];
+      return rows.length > 1 && document.activeElement === rows[1];
+    });
+    const rovingAfter = await page.$$eval('#mnt-results [data-mnt-plc]',
+      (rows) => rows.map((row) => row.tabIndex));
+```
+
+Keep the existing `check('MNT-UX-007: …')` call after it unchanged.
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `env XDG_STATE_HOME="$S/state" node tests/ui/dashboard-ui.mjs` (with `S=$(mktemp -d "$PWD/../ak-ui.XXXXXX")`)
+Expected: FAIL on MNT-UX-007a (`aria-busy read null`), and the run then times out in the `aria-busy === 'false'` wait — the product has no busy marker on `#mnt-results`. Record the output.
+
+- [ ] **Step 3: Implement the busy marker**
+
+In `src/lib/dashboard/client/maintenance-inventory.mjs`, beside `mntRunInventoryQuery`:
+
+```js
+  function mntResultsBusy(value){
+    var results=document.getElementById("mnt-results");
+    if(results)results.setAttribute("aria-busy",value?"true":"false");
+  }
+```
+
+Call `mntResultsBusy(true)` where the query sets `mntInventoryBusy=true`, and `mntResultsBusy(false)` wherever it sets `mntInventoryBusy=false` (success branch, error branch, and the `INVENTORY_GENERATION_MISMATCH` branch just before it re-queries — the re-query sets it back to `true`). Call it AFTER `renderMntInventory()` in each branch, in case that render replaces `#mnt-results` itself; if it does replace the element, set the attribute from inside the render instead, from `mntInventoryBusy`. This is also the right accessibility signal: assistive technology does not announce a list that is about to be replaced.
+
+- [ ] **Step 4: Run it repeatedly**
+
+Run: `for i in $(seq 1 10); do env XDG_STATE_HOME="$S/state" node tests/ui/dashboard-ui.mjs >/dev/null 2>&1 || echo "FAIL run $i"; done; rm -rf "$S"`
+Expected: no `FAIL` lines. Also `node --test tests/kit/maintenance-*.test.mjs` for any client unit test touching `mntRunInventoryQuery`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/lib/dashboard/client/maintenance-inventory.mjs tests/ui/dashboard-ui.mjs
+git commit -m "fix(maintenance): mark the results list busy while an inventory query runs"
+```
+
+### Task 3.4: Branch exit — two clean runs and the docs gate
+
+- [ ] **Step 1: Two full runs in a row with nothing else running** (the program plan's exit criterion):
+
+```bash
+FP=/Users/cphillipson/Development/active/ai/agentic-kit/.superpowers/sdd/2026-09-26-remediation-program/briefs/fingerprint.sh
+S=$(mktemp -d "$PWD/../ak-exit.XXXXXX"); $FP "$PWD" > "$S/fp0.txt"
+for i in 1 2; do node scripts/run-tests.mjs unit && node scripts/run-tests.mjs ui; echo "run $i exit=$?"; $FP "$PWD" > "$S/fp$i.txt"; done
+diff "$S/fp0.txt" "$S/fp1.txt"; diff "$S/fp1.txt" "$S/fp2.txt"; rm -rf "$S"
+```
+
+Expected: both runs `exit=0`, the runner prints no failing paths and no leftovers, both diffs empty (or only explained concurrent-writer lines, with the file content shown).
+
+- [ ] **Step 2: Rest of the gate set** from the brief (tsc, eslint, complexity, markdownlint, build-check, doc-citations, ga-surface-guard, Node 22 run).
+
+- [ ] **Step 3: Docs gate (six classes)** — ADR: none changed (see decisions); DDD: none (`docs/ddd/machine-footprint.md` mentions hermeticity only for product code — re-read to confirm); supplemental: `AGENTS.md` Testing (Tasks 1.2, 2.4); audit: the three Open-items bullets (Tasks 1.3, 2.6, 3.1) plus "Other spawn tests still inherit the developer's `XDG_*` variables" (Task 2.1) marked fixed; research: none; user-facing: none (no CLI behaviour changed). Commit any remaining audit-record edits as `docs(audit): record Branch 2 hermeticity fixes`.
+
+---
+
+## Decisions this plan makes provisionally (flagged for the maintainer)
+
+1. **Concurrent writers on a developer machine.** The tripwire lists the Claude Code statusline tee files and the repo's `.swarm`/`.agentic-qe`/`.claude-flow` hook churn (except ak's own `llm-config.json` and `.claude-flow/config.json`) as "concurrent writers" that do not fail a local run; CI and `AK_TRIPWIRE_STRICT=1` fail on them. Alternative: strict everywhere (reliable only with no Claude Code session open during `pnpm test`).
+2. **`pnpm test` itself runs through the tripwire** (not a separate `test:guarded` script), so every contributor and CI get it.
+3. **The runner also watches ak's guidance files in other tools' homes** (`~/.claude/CLAUDE.md`, the Codex `AGENTS.md`, the OpenCode `AGENTS.md`), beyond the program plan's list.
+4. **Host-readiness focus: product fix** (the `close` handler no longer pulls focus from an element outside the dialog) plus condition waits in the test; alternative: test-only waits.
+5. **`tests/ui/maintenance-guidance.mjs` joins `test:ui`** with `maintenance-focus.mjs` (it passes today and is equally outside the suite).
+6. **No new ADR.** Test tooling is documented in `AGENTS.md` and the audit record; alternative: a short ADR for the tripwire policy (what is watched, concurrent-writer rule, CI strictness).
+7. **Program-plan item 5 is reframed** from "`mktemp` template" (no test uses `mktemp`) to "the suite runs in its own templated temp root and fails on leftovers".

From bff6a25a4eea9e13a6290142f5dd02912c5e8b73 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:09:26 -0700
Subject: [PATCH 02/28] test(guard): fingerprint real user state on every
 platform

Adds scripts/real-state-tripwire.mjs: a builtins-only library and CLI that
snapshots ~/.config/agentic-kit, ~/.local/state/agentic-kit, the
APPDATA/LOCALAPPDATA equivalents, the repo's .claude/.swarm/.agentic-qe/
.claude-flow/.harness and the ak-managed guidance files, then names each
created, removed or rewritten path. Live-session writers are reported as
concurrent (not failing) outside CI/AK_TRIPWIRE_STRICT.
---
 scripts/real-state-tripwire.mjs        | 201 +++++++++++++++++++++++++
 tests/kit/real-state-tripwire.test.mjs | 143 ++++++++++++++++++
 2 files changed, 344 insertions(+)
 create mode 100644 scripts/real-state-tripwire.mjs
 create mode 100644 tests/kit/real-state-tripwire.test.mjs

diff --git a/scripts/real-state-tripwire.mjs b/scripts/real-state-tripwire.mjs
new file mode 100644
index 00000000..18da9e46
--- /dev/null
+++ b/scripts/real-state-tripwire.mjs
@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// scripts/real-state-tripwire.mjs
+// Real-state tripwire: fingerprints every folder a test could write on the
+// developer's machine and names each path that changed. Four incidents wrote
+// real state (statusline version + env pins in the repo's .claude, the
+// maintenance state, a heal receipt); this turns the next one into a failure.
+// Imports only builtins: src/lib/paths.mjs snapshots os.homedir() at module
+// scope and must never be loaded here. Node 22.13+.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const REPO_STATE_DIRS = ['.claude', '.swarm', '.agentic-qe', '.claude-flow', '.harness'];
+
+/** Writers a live Claude Code / Ruflo / AQE session runs concurrently with a
+ *  developer's test run. Excluded from failure only outside strict mode, and
+ *  always printed. Each entry names the source that proves the writer. */
+export const CONCURRENT_WRITERS = [
+  { kind: 'config', pattern: /^claude-rate-limits\.json(\.[^/]*)?$/, writer: 'Claude Code statusline tee (src/templates/statusline-footer.cjs:52-66)' },
+  { kind: 'config', pattern: /^claude-context-windows(\/|$)/, writer: 'Claude Code statusline context ledger (src/templates/statusline-footer.cjs:77-131)' },
+  { kind: 'state', pattern: /^statusline-debug\.log$/, writer: 'statusline debug log (src/templates/statusline-footer.cjs:2-15)' },
+  { kind: 'repo', pattern: /^\.swarm(\/|$)/, writer: 'Ruflo hooks and daemon of a live session' },
+  { kind: 'repo', pattern: /^\.agentic-qe\/(?!llm-config\.json)/, writer: 'AQE hooks of a live session' },
+  { kind: 'repo', pattern: /^\.claude-flow\/(?!config\.json$)/, writer: 'Ruflo hooks and statusline caches of a live session' },
+];
+
+export function isStrict(env = process.env) {
+  return env.CI === 'true' || env.CI === '1' || env.AK_TRIPWIRE_STRICT === '1';
+}
+
+/**
+ * Every real-state location a test could write, for the given platform.
+ * @param {{ env?: Record<string, string|undefined>, platform?: string, homedir?: string, repoRoot: string }} o
+ */
+export function realStateRoots({ env = process.env, platform = process.platform, homedir = os.homedir(), repoRoot }) {
+  const p = platform === 'win32' ? path.win32 : path.posix;
+  const configBases = [env.XDG_CONFIG_HOME, p.join(homedir, '.config'), env.APPDATA, p.join(homedir, 'AppData', 'Roaming')];
+  const stateBases = [env.XDG_STATE_HOME, p.join(homedir, '.local', 'state'), env.LOCALAPPDATA, p.join(homedir, 'AppData', 'Local')];
+  const primaryConfig = platform === 'win32'
+    ? env.APPDATA || p.join(homedir, 'AppData', 'Roaming')
+    : env.XDG_CONFIG_HOME || p.join(homedir, '.config');
+  const roots = [
+    ...configBases.filter(Boolean).map((base) => ({ kind: 'config', dir: p.join(base, 'agentic-kit') })),
+    ...stateBases.filter(Boolean).map((base) => ({ kind: 'state', dir: p.join(base, 'agentic-kit') })),
+    ...REPO_STATE_DIRS.map((name) => ({ kind: 'repo', dir: p.join(repoRoot, name), prefix: name })),
+    // ak-managed guidance files in other tools' homes (sync/setup write them).
+    { kind: 'user-file', dir: p.join(env.CLAUDE_CONFIG_DIR || p.join(homedir, '.claude'), 'CLAUDE.md') },
+    { kind: 'user-file', dir: p.join(env.CODEX_HOME || p.join(homedir, '.codex'), 'AGENTS.md') },
+    { kind: 'user-file', dir: p.join(primaryConfig, 'opencode', 'AGENTS.md') },
+  ];
+  const seen = new Set();
+  return roots.filter((root) => {
+    const key = platform === 'win32' ? p.normalize(root.dir).toLowerCase() : p.normalize(root.dir);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).map((root) => ({ ...root, label: `${root.kind}:${root.dir}` }));
+}
+
+const toRel = (...parts) => parts.filter(Boolean).join('/');
+
+function hashFile(abs) {
+  return crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+}
+
+function record(out, root, rel, abs) {
+  let st;
+  try { st = fs.lstatSync(abs); } catch (error) {
+    if (error.code === 'ENOENT') return; // vanished between readdir and lstat
+    out.set(abs, { root, rel, type: 'unreadable', code: error.code });
+    return;
+  }
+  if (st.isSymbolicLink()) {
+    let target = '';
+    try { target = fs.readlinkSync(abs); } catch { /* recorded as empty */ }
+    out.set(abs, { root, rel, type: 'link', target });
+  } else if (st.isDirectory()) {
+    out.set(abs, { root, rel: `${rel}/`, type: 'dir' });
+    let names;
+    try { names = fs.readdirSync(abs); } catch (error) {
+      out.set(abs, { root, rel: `${rel}/`, type: 'unreadable', code: error.code });
+      return;
+    }
+    for (const name of names.sort()) record(out, root, toRel(rel, name), path.join(abs, name));
+  } else {
+    try { out.set(abs, { root, rel, type: 'file', size: st.size, sha256: hashFile(abs) }); } catch (error) {
+      out.set(abs, { root, rel, type: 'unreadable', code: error.code });
+    }
+  }
+}
+
+/** Content-addressed snapshot of every root. Directory mtimes are ignored. */
+export function snapshotRoots(roots) {
+  const out = new Map();
+  for (const root of roots) {
+    if (!fs.existsSync(root.dir)) { out.set(`absent:${root.dir}`, { root, rel: '', type: 'absent-root' }); continue; }
+    if (root.kind === 'user-file') { record(out, root, path.basename(root.dir), root.dir); continue; }
+    // The root itself is an entry, so a run that CREATES ~/.local/state/agentic-kit
+    // (even empty) is reported as `+ <root>/`.
+    out.set(root.dir, { root, rel: root.prefix ? `${root.prefix}/` : './', type: 'dir' });
+    let names;
+    try { names = fs.readdirSync(root.dir); } catch (error) {
+      out.set(root.dir, { root, rel: root.prefix ? `${root.prefix}/` : './', type: 'unreadable', code: error.code });
+      continue;
+    }
+    for (const name of names.sort()) record(out, root, toRel(root.prefix, name), path.join(root.dir, name));
+  }
+  return out;
+}
+
+const same = (a, b) => a.type === b.type && a.sha256 === b.sha256 && a.target === b.target && a.code === b.code;
+
+function writerFor(entry) {
+  return CONCURRENT_WRITERS.find((w) => w.kind === entry.root.kind && w.pattern.test(entry.rel.replace(/\/$/, '')))?.writer;
+}
+
+export function compareSnapshots(before, after, { strict = isStrict() } = {}) {
+  const changes = [];
+  for (const [key, now] of after) {
+    const was = before.get(key);
+    if (now.type === 'absent-root') continue;
+    if (!was) changes.push({ op: '+', path: key, rel: now.rel, kind: now.root.kind, after: now });
+    else if (!same(was, now)) changes.push({ op: '~', path: key, rel: now.rel, kind: now.root.kind, before: was, after: now });
+  }
+  for (const [key, was] of before) {
+    if (was.type === 'absent-root' || after.has(key)) continue;
+    changes.push({ op: '-', path: key, rel: was.rel, kind: was.root.kind, before: was });
+  }
+  const failing = [];
+  const concurrent = [];
+  for (const change of changes) {
+    const writer = writerFor(change.after || change.before);
+    if (!strict && writer) concurrent.push({ ...change, writer });
+    else failing.push(change);
+  }
+  const byPath = (a, b) => a.path.localeCompare(b.path);
+  return { failing: failing.sort(byPath), concurrent: concurrent.sort(byPath) };
+}
+
+const size = (e) => (e && e.type === 'file' ? `${e.size} bytes` : e ? e.type : 'absent');
+
+export function formatReport({ failing, concurrent }) {
+  const lines = [];
+  if (failing.length) {
+    lines.push(`real-state tripwire: ${failing.length} path(s) changed during the run`);
+    for (const c of failing) lines.push(`  ${c.op} ${c.path} (${size(c.before)} -> ${size(c.after)})`);
+    lines.push('A test wrote real user state. If you ran ak, the dashboard or `ak sync` yourself during the run, '
+      + 'check whether the listed file holds your data or fixture data, and re-run with nothing else running.');
+  }
+  if (concurrent.length) {
+    lines.push(`real-state tripwire: ${concurrent.length} path(s) changed by concurrent writers (not failing)`);
+    for (const c of concurrent) lines.push(`  ${c.op} ${c.path} — ${c.writer}`);
+  }
+  return lines.join('\n');
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+function repoArg(argv) {
+  const i = argv.indexOf('--repo');
+  return i >= 0 ? path.resolve(argv[i + 1]) : process.cwd();
+}
+
+function serialize(map) {
+  return JSON.stringify([...map].map(([key, e]) => [key, { ...e, root: e.root.label }]));
+}
+
+function deserialize(text, roots) {
+  const byLabel = new Map(roots.map((r) => [r.label, r]));
+  return new Map(JSON.parse(text).map(([key, e]) => [key, { ...e, root: byLabel.get(e.root) ?? { kind: 'unknown', label: e.root } }]));
+}
+
+function main(argv) {
+  const [command, file] = argv;
+  const roots = realStateRoots({ repoRoot: repoArg(argv) });
+  if (command === 'snapshot' && file) {
+    fs.writeFileSync(file, serialize(snapshotRoots(roots)));
+    return 0;
+  }
+  if (command === 'compare' && file) {
+    const result = compareSnapshots(deserialize(fs.readFileSync(file, 'utf8'), roots), snapshotRoots(roots));
+    const report = formatReport(result);
+    if (report) console.error(report);
+    return result.failing.length ? 3 : 0;
+  }
+  console.error('usage: real-state-tripwire.mjs snapshot|compare <file> [--repo <dir>]');
+  return 2;
+}
+
+// Compare real paths (drive-letter case differs on Windows): a missed match would
+// make `pnpm test` exit 0 having run nothing.
+const isMain = () => {
+  if (!process.argv[1]) return false;
+  const a = fs.realpathSync.native(path.resolve(process.argv[1]));
+  const b = fs.realpathSync.native(fileURLToPath(import.meta.url));
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+if (isMain()) {
+  process.exitCode = main(process.argv.slice(2));
+}
diff --git a/tests/kit/real-state-tripwire.test.mjs b/tests/kit/real-state-tripwire.test.mjs
new file mode 100644
index 00000000..7bf2313d
--- /dev/null
+++ b/tests/kit/real-state-tripwire.test.mjs
@@ -0,0 +1,143 @@
+// tests/kit/real-state-tripwire.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  REPO_STATE_DIRS, realStateRoots, snapshotRoots, compareSnapshots, isStrict, formatReport,
+} from '../../scripts/real-state-tripwire.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'real-state-tripwire.mjs');
+const tmp = (t, prefix) => {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`)));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+};
+
+test('POSIX roots: XDG bases, their defaults, the repo state folders and ak-owned user files', () => {
+  const roots = realStateRoots({
+    platform: 'linux', homedir: '/home/dev', repoRoot: '/src/kit',
+    env: { XDG_CONFIG_HOME: '/x/cfg', XDG_STATE_HOME: '/x/state' },
+  });
+  const dirs = roots.map((r) => `${r.kind}:${r.dir}`);
+  for (const want of [
+    'config:/x/cfg/agentic-kit', 'config:/home/dev/.config/agentic-kit',
+    'state:/x/state/agentic-kit', 'state:/home/dev/.local/state/agentic-kit',
+    ...REPO_STATE_DIRS.map((d) => `repo:/src/kit/${d}`),
+    'user-file:/home/dev/.claude/CLAUDE.md', 'user-file:/home/dev/.codex/AGENTS.md',
+    'user-file:/x/cfg/opencode/AGENTS.md',
+  ]) assert.ok(dirs.includes(want), `missing ${want} in ${dirs.join(', ')}`);
+});
+
+test('Windows roots use APPDATA/LOCALAPPDATA and collapse case-insensitive duplicates', () => {
+  const roots = realStateRoots({
+    platform: 'win32', homedir: 'C:\\Users\\dev', repoRoot: 'C:\\src\\kit',
+    env: { APPDATA: 'C:\\Users\\dev\\AppData\\Roaming', LOCALAPPDATA: 'c:\\users\\DEV\\appdata\\local' },
+  });
+  const dirs = roots.map((r) => `${r.kind}:${r.dir}`);
+  assert.ok(dirs.includes('config:C:\\Users\\dev\\AppData\\Roaming\\agentic-kit'));
+  assert.ok(dirs.includes('state:c:\\users\\DEV\\appdata\\local\\agentic-kit'));
+  assert.equal(dirs.filter((d) => d.toLowerCase() === 'state:c:\\users\\dev\\appdata\\local\\agentic-kit').length, 1,
+    'the LOCALAPPDATA root and the ~\\AppData\\Local fallback are one folder on Windows');
+  assert.ok(dirs.includes('repo:C:\\src\\kit\\.claude'));
+});
+
+test('a created, removed or rewritten file is failing; an mtime-only touch is not', (t) => {
+  const home = tmp(t, 'ak-trip');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(cfg, { recursive: true });
+  fs.writeFileSync(path.join(cfg, 'kit.json'), '{}');
+  fs.writeFileSync(path.join(cfg, 'gone.json'), '1');
+  fs.writeFileSync(path.join(cfg, 'touched.json'), 'same');
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const before = snapshotRoots(roots);
+  fs.writeFileSync(path.join(cfg, 'kit.json'), '{"changed":true}');
+  fs.rmSync(path.join(cfg, 'gone.json'));
+  fs.writeFileSync(path.join(cfg, 'new.json'), 'x');
+  const future = new Date(Date.now() + 60_000);
+  fs.utimesSync(path.join(cfg, 'touched.json'), future, future);
+  const { failing } = compareSnapshots(before, snapshotRoots(roots), { strict: true });
+  assert.deepEqual(failing.map((c) => `${c.op} ${c.rel}`).sort(), ['+ new.json', '- gone.json', '~ kit.json']);
+  const report = formatReport({ failing, concurrent: [] });
+  assert.match(report, /3 path\(s\) changed/);
+  assert.ok(report.includes(path.join(cfg, 'kit.json')), 'the report names the absolute path');
+});
+
+test('an empty folder a tool creates is a change (the opencode/ case)', (t) => {
+  const home = tmp(t, 'ak-trip-dir');
+  const state = path.join(home, '.local', 'state', 'agentic-kit');
+  fs.mkdirSync(state, { recursive: true });
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const before = snapshotRoots(roots);
+  fs.mkdirSync(path.join(state, 'maintenance'));
+  const { failing } = compareSnapshots(before, snapshotRoots(roots), { strict: true });
+  assert.deepEqual(failing.map((c) => `${c.op} ${c.rel}`), ['+ maintenance/']);
+});
+
+test('developer mode moves live-session writers to "concurrent"; strict mode fails them', (t) => {
+  const home = tmp(t, 'ak-trip-conc');
+  const repo = path.join(home, 'repo');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(path.join(cfg, 'claude-context-windows'), { recursive: true });
+  fs.mkdirSync(path.join(repo, '.swarm'), { recursive: true });
+  fs.mkdirSync(path.join(repo, '.agentic-qe'), { recursive: true });
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: repo, env: {} });
+  const before = snapshotRoots(roots);
+  fs.writeFileSync(path.join(cfg, 'claude-rate-limits.json'), '{}');
+  fs.writeFileSync(path.join(cfg, 'claude-context-windows', 's1.json'), '[]');
+  fs.writeFileSync(path.join(repo, '.swarm', 'memory.db-wal'), 'x');
+  fs.writeFileSync(path.join(repo, '.agentic-qe', 'llm-config.json'), '{}');
+  const after = snapshotRoots(roots);
+  const dev = compareSnapshots(before, after, { strict: false });
+  assert.deepEqual(dev.failing.map((c) => c.rel), ['.agentic-qe/llm-config.json'],
+    'ak-owned files inside hook-churned folders stay failing');
+  assert.deepEqual(dev.concurrent.map((c) => c.rel).sort(),
+    ['.swarm/memory.db-wal', 'claude-context-windows/s1.json', 'claude-rate-limits.json']);
+  const strict = compareSnapshots(before, after, { strict: true });
+  assert.equal(strict.concurrent.length, 0);
+  assert.ok(strict.failing.some((c) => c.rel === 'claude-rate-limits.json'));
+  assert.match(formatReport(dev), /concurrent writers \(not failing\)/);
+});
+
+test('CI and AK_TRIPWIRE_STRICT make the comparison strict', () => {
+  assert.equal(isStrict({ CI: 'true' }), true);
+  assert.equal(isStrict({ CI: '1' }), true);
+  assert.equal(isStrict({ AK_TRIPWIRE_STRICT: '1' }), true);
+  assert.equal(isStrict({}), false);
+  assert.equal(isStrict({ CI: 'false' }), false);
+});
+
+test('an unreadable file is recorded, never thrown, and compares equal to itself', { skip: process.platform === 'win32' && 'chmod 000 does not deny reads on Windows' }, (t) => {
+  const home = tmp(t, 'ak-trip-unread');
+  const cfg = path.join(home, '.config', 'agentic-kit');
+  fs.mkdirSync(cfg, { recursive: true });
+  const locked = path.join(cfg, 'locked.json');
+  fs.writeFileSync(locked, 'secret');
+  fs.chmodSync(locked, 0o000); // the folder stays writable, so the tmp cleanup still removes it
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: path.join(home, 'repo'), env: {} });
+  const a = snapshotRoots(roots);
+  const entry = [...a.values()].find((e) => e.rel === 'locked.json');
+  if (process.getuid && process.getuid() === 0) return; // root reads anything
+  assert.equal(entry.type, 'unreadable');
+  assert.deepEqual(compareSnapshots(a, snapshotRoots(roots), { strict: true }).failing, []);
+});
+
+test('the CLI snapshot/compare pair exits 3 and names the changed path', (t) => {
+  const home = tmp(t, 'ak-trip-cli');
+  const repo = path.join(home, 'repo');
+  fs.mkdirSync(repo);
+  const env = { ...process.env, HOME: home, USERPROFILE: home, CI: 'true',
+    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local') };
+  const out = path.join(home, 'before.json');
+  const snap = spawnSync(process.execPath, [CLI, 'snapshot', out, '--repo', repo], { env, encoding: 'utf8' });
+  assert.equal(snap.status, 0, snap.stderr);
+  fs.mkdirSync(path.join(home, '.local', 'state', 'agentic-kit'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.local', 'state', 'agentic-kit', 'install-edits.json'), '{}');
+  const cmp = spawnSync(process.execPath, [CLI, 'compare', out, '--repo', repo], { env, encoding: 'utf8' });
+  assert.equal(cmp.status, 3, cmp.stdout + cmp.stderr);
+  assert.match(cmp.stderr, /install-edits\.json/);
+});

From 718c5ddf2f66635d2b7ff80799c8e13ea0c68e6f Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:10:17 -0700
Subject: [PATCH 03/28] test(guard): fail the suite when real user state
 changes

pnpm test and pnpm run test:ui now run through scripts/run-tests.mjs, which
snapshots the real-state roots before and after the same commands the old
&& chain ran, keeps the first failing command's exit code, and exits 3 when
a test wrote real user state. AGENTS.md documents the tripwire, concurrent
writers and AK_TRIPWIRE_STRICT=1.
---
 AGENTS.md                           |  9 ++++
 package.json                        |  4 +-
 scripts/run-tests.mjs               | 80 +++++++++++++++++++++++++++
 tests/kit/run-tests-runner.test.mjs | 84 +++++++++++++++++++++++++++++
 4 files changed, 175 insertions(+), 2 deletions(-)
 create mode 100644 scripts/run-tests.mjs
 create mode 100644 tests/kit/run-tests-runner.test.mjs

diff --git a/AGENTS.md b/AGENTS.md
index f19fa899..73e21c7f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -281,6 +281,15 @@ pnpm run lint:md
 pnpm run build
 ```
 
+`pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`, which fingerprints
+`~/.config/agentic-kit`, `~/.local/state/agentic-kit` (or `%APPDATA%`/`%LOCALAPPDATA%` on
+Windows), the Claude/Codex/OpenCode guidance files ak manages, and this repository's `.claude`,
+`.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` before and after the run. Any change fails
+the run and is listed by path. Files a live Claude Code, Ruflo or AQE session writes during the
+run are listed as "concurrent writers" and do not fail a local run; CI (or
+`AK_TRIPWIRE_STRICT=1`) fails on them too. `node scripts/run-tests.mjs exec -- <node args>`
+guards any single command the same way.
+
 ### Test Philosophy
 
 - TDD London School (mock-first)
diff --git a/package.json b/package.json
index 7a8bd90f..15b8c7e9 100644
--- a/package.json
+++ b/package.json
@@ -51,8 +51,8 @@
     "docs/ddd/model-lifecycle-intelligence.md"
   ],
   "scripts": {
-    "test": "node --test --experimental-test-coverage --test-coverage-lines=70 --test-coverage-branches=70 --test-coverage-functions=70 \"tests/kit/*.test.mjs\" && node tests/statusline-segments.test.cjs && node tests/statusline-window-ledger.test.cjs && node tests/statusline-brain.test.cjs && node tests/health-history.test.cjs && node tests/dashboard.test.cjs && node tests/admin-model.test.cjs && node tests/admin.test.cjs",
-    "test:ui": "node tests/ui/dashboard-ui.mjs && node --test tests/ui/dashboard-project-context.mjs tests/ui/maintenance-projects.mjs tests/ui/maintenance-host-alignment.mjs tests/ui/intelligence-picker.mjs tests/ui/usage-project-groups.mjs tests/ui/context-coverage.mjs tests/ui/host-readiness.mjs",
+    "test": "node scripts/run-tests.mjs unit",
+    "test:ui": "node scripts/run-tests.mjs ui",
     "test:surface": "node --test tests/kit/dispatch-surface.test.mjs",
     "test:aqe-external-provider-live": "node --test tests/live/aqe-external-provider-transport.test.mjs",
     "test:qe-court-live": "node --test tests/live/qe-court-participant-transport.test.mjs",
diff --git a/scripts/run-tests.mjs b/scripts/run-tests.mjs
new file mode 100644
index 00000000..16b5c18b
--- /dev/null
+++ b/scripts/run-tests.mjs
@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// scripts/run-tests.mjs — runs a test suite between two real-state snapshots.
+// `pnpm test` and `pnpm run test:ui` call this. Commands run in order and stop
+// at the first failure (the old `&&` chain); the after-snapshot is taken either
+// way. No shell: argument vectors for process.execPath, so it behaves the same
+// on Windows; `node --test` expands the glob itself.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { realStateRoots, snapshotRoots, compareSnapshots, isStrict, formatReport } from './real-state-tripwire.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const COVERAGE = ['--experimental-test-coverage', '--test-coverage-lines=70',
+  '--test-coverage-branches=70', '--test-coverage-functions=70'];
+
+export const SUITES = {
+  unit: [
+    ['--test', ...COVERAGE, 'tests/kit/*.test.mjs'],
+    ...['statusline-segments', 'statusline-window-ledger', 'statusline-brain', 'health-history',
+      'dashboard', 'admin-model', 'admin'].map((name) => [`tests/${name}.test.cjs`]),
+  ],
+  ui: [
+    ['tests/ui/dashboard-ui.mjs'],
+    ['--test', 'tests/ui/dashboard-project-context.mjs', 'tests/ui/maintenance-projects.mjs',
+      'tests/ui/maintenance-host-alignment.mjs', 'tests/ui/intelligence-picker.mjs',
+      'tests/ui/usage-project-groups.mjs', 'tests/ui/context-coverage.mjs', 'tests/ui/host-readiness.mjs'],
+  ],
+};
+
+/**
+ * @param {string[][]} commands argument vectors for process.execPath
+ * @param {{ env?: NodeJS.ProcessEnv, repoRoot?: string, platform?: string, homedir?: string, log?: (s: string) => void }} [o]
+ * @returns {number} exit code: the first failing command's, else 3 on a real-state change, else 0
+ */
+export function runGuarded(commands, {
+  env = process.env, repoRoot = REPO, platform = process.platform, homedir = os.homedir(), log = console.error,
+} = {}) {
+  const roots = realStateRoots({ env, platform, homedir, repoRoot });
+  const before = snapshotRoots(roots);
+  // One line before anything runs, so a CI log proves the tripwire executed.
+  log(`real-state tripwire: watching ${roots.length} roots (${isStrict(env) ? 'strict' : 'developer'})`);
+  let code = 0;
+  for (const args of commands) {
+    const r = spawnSync(process.execPath, args, { cwd: repoRoot, env, stdio: 'inherit' });
+    if (r.error) { log(`could not run node ${args.join(' ')}: ${r.error.message}`); code = 1; break; }
+    if (r.status !== 0) { code = r.status ?? 1; break; }
+  }
+  const result = compareSnapshots(before, snapshotRoots(roots), { strict: isStrict(env) });
+  const report = formatReport(result);
+  if (report) log(report);
+  return code || (result.failing.length ? 3 : 0);
+}
+
+function main(argv) {
+  const [mode] = argv;
+  if (mode === 'unit' || mode === 'ui') return runGuarded(SUITES[mode]);
+  if (mode === 'exec') {
+    const sep = argv.indexOf('--');
+    const repoAt = argv.indexOf('--repo');
+    if (sep < 0 || sep === argv.length - 1) { console.error('usage: run-tests.mjs exec [--repo <dir>] -- <node args…>'); return 2; }
+    const repoRoot = repoAt >= 0 && repoAt < sep ? path.resolve(argv[repoAt + 1]) : REPO;
+    return runGuarded([argv.slice(sep + 1)], { repoRoot });
+  }
+  console.error('usage: run-tests.mjs unit|ui|exec');
+  return 2;
+}
+
+// Compare real paths (drive-letter case differs on Windows): a missed match would
+// make `pnpm test` exit 0 having run nothing.
+const isMain = () => {
+  if (!process.argv[1]) return false;
+  const a = fs.realpathSync.native(path.resolve(process.argv[1]));
+  const b = fs.realpathSync.native(fileURLToPath(import.meta.url));
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+};
+if (isMain()) {
+  process.exitCode = main(process.argv.slice(2));
+}
diff --git a/tests/kit/run-tests-runner.test.mjs b/tests/kit/run-tests-runner.test.mjs
new file mode 100644
index 00000000..734fe916
--- /dev/null
+++ b/tests/kit/run-tests-runner.test.mjs
@@ -0,0 +1,84 @@
+// tests/kit/run-tests-runner.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const RUNNER = path.join(ROOT, 'scripts', 'run-tests.mjs');
+
+function sandbox(t) {
+  const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-runner-')));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  const repo = path.join(home, 'repo');
+  fs.mkdirSync(path.join(repo, '.git'), { recursive: true });
+  const env = { ...process.env, HOME: home, USERPROFILE: home,
+    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    XDG_DATA_HOME: path.join(home, '.local', 'share'), XDG_CACHE_HOME: path.join(home, '.cache'),
+    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local'), CI: 'true' };
+  for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'AK_TRIPWIRE_STRICT']) delete env[key];
+  return { home, repo, env };
+}
+
+const stub = (dir, name, body) => { const f = path.join(dir, name); fs.writeFileSync(f, body); return f; };
+
+test('a command that writes real state fails the run and the path is named', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leak = stub(home, 'leak.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    const d = path.join(process.env.XDG_STATE_HOME, 'agentic-kit', 'maintenance');
+    fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, 'latest-scan.json'), '{}');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leak], { env, encoding: 'utf8' });
+  assert.equal(r.status, 3, r.stdout + r.stderr);
+  assert.match(r.stderr, /real-state tripwire: watching \d+ roots \(strict\)/);
+  assert.match(r.stderr, /latest-scan\.json/);
+  assert.match(r.stderr, /maintenance\//);
+});
+
+test('a write into the repository .claude fails the run', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leak = stub(home, 'leak-repo.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    fs.mkdirSync(path.join(process.argv[2], '.claude', 'helpers'), { recursive: true });
+    fs.writeFileSync(path.join(process.argv[2], '.claude', 'helpers', 'statusline.cjs'), '9.9.9');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leak, repo], { env, encoding: 'utf8' });
+  assert.equal(r.status, 3, r.stderr);
+  assert.match(r.stderr, /statusline\.cjs/);
+});
+
+test('a failing test command keeps its exit code and the tripwire still reports', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const both = stub(home, 'both.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    fs.mkdirSync(path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit'), { recursive: true });
+    fs.writeFileSync(path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit', 'kit.json'), '{}');
+    process.exit(7);`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', both], { env, encoding: 'utf8' });
+  assert.equal(r.status, 7);
+  assert.match(r.stderr, /kit\.json/);
+});
+
+test('a clean command passes; concurrent-writer churn does not fail a developer run', (t) => {
+  const { home, repo, env } = sandbox(t);
+  delete env.CI;
+  // The folder exists on any machine with a live statusline; creating it would be a real leak.
+  fs.mkdirSync(path.join(home, '.config', 'agentic-kit'), { recursive: true });
+  const tee = stub(home, 'tee.mjs', `import fs from 'node:fs'; import path from 'node:path';
+    const d = path.join(process.env.XDG_CONFIG_HOME, 'agentic-kit');
+    fs.mkdirSync(d, { recursive: true }); fs.writeFileSync(path.join(d, 'claude-rate-limits.json'), '{}');`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', tee], { env, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stderr, /concurrent writers \(not failing\)/);
+});
+
+test('SUITES keeps the exact commands package.json ran before', async () => {
+  const { SUITES } = await import('../../scripts/run-tests.mjs');
+  assert.deepEqual(SUITES.unit[0], ['--test', '--experimental-test-coverage', '--test-coverage-lines=70',
+    '--test-coverage-branches=70', '--test-coverage-functions=70', 'tests/kit/*.test.mjs']);
+  assert.deepEqual(SUITES.unit.slice(1).map((a) => a[0]), ['statusline-segments', 'statusline-window-ledger',
+    'statusline-brain', 'health-history', 'dashboard', 'admin-model', 'admin'].map((f) => `tests/${f}.test.cjs`));
+  assert.equal(SUITES.ui[0][0], 'tests/ui/dashboard-ui.mjs');
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  assert.equal(pkg.scripts.test, 'node scripts/run-tests.mjs unit');
+  assert.equal(pkg.scripts['test:ui'], 'node scripts/run-tests.mjs ui');
+});

From bc76bfc6b03a2b7fbf9bc517824c07e903060b1f Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:13:33 -0700
Subject: [PATCH 04/28] fix(dashboard): refuse default maintenance and
 management services in injected test servers

A server given any injected collector (fetchStatus, usage, limits, hooks,
live, transcripts, intelWatch, discoverProjects, machineWideIntel, models,
system, hostReadiness) and neither an injected maintenance service nor
maintenanceOptions.controlRoot now refuses the default maintenance service
(logged once, 503 on its routes) and the default management facade, so a
deep System refresh can no longer write the real control root. The real
ak dashboard command injects none of them and is unaffected. No existing
dashboard caller relied on the real control root.

The lookbackDays citation in docs/USAGE-SCORECARD-METRICS.md moves with the
25 added lines (1824 -> 1849).
---
 docs/USAGE-SCORECARD-METRICS.md               |  2 +-
 ...-237-238-239-verification-and-decisions.md |  3 +-
 src/lib/dashboard-server.mjs                  | 38 +++++++++-
 .../kit/dashboard-hermetic-defaults.test.mjs  | 73 +++++++++++++++++++
 4 files changed, 112 insertions(+), 4 deletions(-)
 create mode 100644 tests/kit/dashboard-hermetic-defaults.test.mjs

diff --git a/docs/USAGE-SCORECARD-METRICS.md b/docs/USAGE-SCORECARD-METRICS.md
index 3963f95d..113ffcc1 100644
--- a/docs/USAGE-SCORECARD-METRICS.md
+++ b/docs/USAGE-SCORECARD-METRICS.md
@@ -1941,7 +1941,7 @@ aggregated here, and deriving the baseline from a widened bound would silently
 stretch it to whatever lookback the caller happened to pass. The dashboard route widens it to
 the depth the personal tap-share baseline needs rather than to the previous
 window alone: `days + BASELINE_TRAILING_DAYS` (`lookbackDays`,
-`src/lib/dashboard-server.mjs:1824`); `ak usage score` applies the same rule
+`src/lib/dashboard-server.mjs:1849`); `ak usage score` applies the same rule
 (`src/commands/usage.mjs:316`). One extra window would be a strict
 subset — too shallow for `promptBaselines`, which needs
 BASELINE_MIN_ACTIVE_DAYS of history BEFORE the displayed window and returns
diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 38faf328..c86fb720 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1175,7 +1175,8 @@ Behavior that differs from, or goes beyond, the plan text.
 - **The dashboard server's hermeticity guard has a gap.** It fires only when a maintenance service
   is injected without a control root. A caller that injects only a System collector still gets the
   default maintenance service and management facade, and both write real state. This product-side
-  follow-up is not fixed here.
+  follow-up is not fixed here. Fixed on `fix/test-hermeticity`: a server given any injected
+  collector refuses the default maintenance service and facade unless a control root is passed.
 
 #### From Stage 5
 
diff --git a/src/lib/dashboard-server.mjs b/src/lib/dashboard-server.mjs
index 9b68ed32..0b6794e7 100644
--- a/src/lib/dashboard-server.mjs
+++ b/src/lib/dashboard-server.mjs
@@ -974,6 +974,25 @@ function sendTranscriptJson(res, status, payload) {
   res.end(JSON.stringify(payload));
 }
 
+/** Collectors a caller injects instead of the real ones. A server given any of
+ *  them is a test or an embedder with fakes; its DEFAULT maintenance service and
+ *  management facade would still write the user's real control root
+ *  (~/.local/state/agentic-kit/maintenance), which is how the system-summary
+ *  test overwrote real state (audit 2026-09-26, Open items). */
+const INJECTABLE_COLLECTORS = ['fetchStatus', 'usage', 'limits', 'hooks', 'live', 'transcripts', 'intelWatch',
+  'discoverProjects', 'machineWideIntel', 'models', 'system', 'hostReadiness'];
+
+function refusesDefaultState(opts) {
+  if (opts.maintenance !== undefined) return false;
+  if (opts.maintenanceOptions?.controlRoot !== undefined) return false;
+  return INJECTABLE_COLLECTORS.some((key) => opts[key] !== undefined);
+}
+
+const HERMETIC_REFUSAL = 'dashboard: refusing the default maintenance service — collectors were injected, so it would '
+  + 'write the real state directory; inject `maintenance` or pass maintenanceOptions.controlRoot';
+
+export const __test = { refusesDefaultState };
+
 /** Lazily bind the machine-footprint collector (ADR-0025), for the same reason
  *  lazyUsage is lazy: the System area pulls in five walkers plus the runtime
  *  survey, and a panel that never opens that tab must not pay for them. One
@@ -988,10 +1007,15 @@ function sendTranscriptJson(res, status, payload) {
  *  injected facade means the caller owns that composition; the server never
  *  wraps an owner-private facade (real control root, real kit.json) around
  *  it on its own — such a server answers 503 on every v2 route. */
-function managementProvider({ management, maintenance, managementOptions, maintenanceOptions, getMaintenance, getSystem }) {
+function managementProvider({
+  management, maintenance, managementOptions, maintenanceOptions, getMaintenance, getSystem, refused = false,
+}) {
   if (typeof management === 'function') return management;
   if (management) return async () => management;
   if (maintenance && Object.keys(managementOptions).length === 0) return async () => null;
+  // Injected collectors without a control root: the default facade would write
+  // the user's real state directory, so the v2 routes answer 503 instead.
+  if (refused && managementOptions.controlRoot === undefined) return async () => null;
   // The facade shares the maintenance service's private root and clock unless
   // managementOptions says otherwise, so both read and write one control dir.
   const shared = Object.fromEntries(['controlRoot', 'fsImpl', 'now']
@@ -1064,6 +1088,11 @@ export function startDashboard({
   discoverProjects, machineWideIntel, models, modelScopeKey, system, systemOptions = {},
   maintenance, maintenanceOptions = {}, management, managementOptions = {}, hostReadiness,
 } = {}) {
+  const refused = refusesDefaultState({
+    fetchStatus, usage, limits, hooks, live, transcripts, intelWatch, discoverProjects, machineWideIntel,
+    models, system, hostReadiness, maintenance, maintenanceOptions,
+  });
+  let refusalLogged = false;
   const provide = fetchStatus || shellOutStatus(cwd);
   const getHostReadiness = hostReadiness ?? (fetchStatus ? async () => null : createHostReadinessReader({ cwd }));
   const usageApi = usage || lazyUsage();
@@ -1121,6 +1150,11 @@ export function startDashboard({
   // machine. Like every expensive panel, construction remains lazy.
   const provideMaintenance = typeof maintenance === 'function'
     ? maintenance : maintenance ? async () => maintenance : async () => {
+      if (refused) {
+        // Logged here because refreshMaintenanceAfterSystem swallows errors.
+        if (!refusalLogged) { refusalLogged = true; console.error(HERMETIC_REFUSAL); }
+        throw new TypeError(HERMETIC_REFUSAL);
+      }
       const [{ createMaintenanceService }, collector] = await Promise.all([
         import('./maintenance/service.mjs'), getSystem(),
       ]);
@@ -1141,7 +1175,7 @@ export function startDashboard({
   // opening the dashboard never touches owner-private management stores. When
   // it cannot be built, every v2 route answers 503 and v1 keeps working.
   const provideManagement = managementProvider({
-    management, maintenance, managementOptions, maintenanceOptions, getMaintenance, getSystem,
+    management, maintenance, managementOptions, maintenanceOptions, getMaintenance, getSystem, refused,
   });
   // ONE facade instance for the whole server: the API's v2 routes and the
   // post-scan inventory refresh below must share in-memory state (preview
diff --git a/tests/kit/dashboard-hermetic-defaults.test.mjs b/tests/kit/dashboard-hermetic-defaults.test.mjs
new file mode 100644
index 00000000..20d8bd12
--- /dev/null
+++ b/tests/kit/dashboard-hermetic-defaults.test.mjs
@@ -0,0 +1,73 @@
+// tests/kit/dashboard-hermetic-defaults.test.mjs
+// Audit Open item: the guard fired only for an injected maintenance service; a
+// caller that injected only a System collector still got the default
+// maintenance service and facade over the REAL control root (the
+// system-summary incident, 259f075). The home is sandboxed so a regression
+// writes the sandbox, and the test reads the sandbox to prove it did not.
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { sandboxHome, assertSandboxed, rmrf } from './helpers/home-sandbox.mjs';
+import { waitUntil } from './helpers/wait-until.mjs';
+
+const home = sandboxHome('ak-dash-hermetic');
+after(() => rmrf(home));
+const paths = await import('../../src/lib/paths.mjs');
+assertSandboxed(paths, home);
+const { startDashboard } = await import('../../src/lib/dashboard-server.mjs');
+
+function get(server, route) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(new URL(route, server.url), { headers: { 'x-dash-token': server.token } }, (res) => {
+      let body = ''; res.on('data', (c) => { body += c; }); res.on('end', () => resolve({ status: res.statusCode, body }));
+    });
+    req.on('error', reject); req.end();
+  });
+}
+
+const collector = () => ({
+  async read() { return { runtime: {}, knownFiles: [], storage: {}, projects: [], snapshot: null, scan: { running: false } }; },
+  async refreshDeep() { return { ok: true, persisted: { ok: true } }; },
+  scanState() { return { running: true, phase: 'catalog' }; },
+});
+
+test('an injected System collector alone never builds the default maintenance service', async (t) => {
+  const errors = [];
+  const realError = console.error;
+  console.error = (...a) => errors.push(a.map(String).join(' '));
+  t.after(() => { console.error = realError; });
+  const server = await startDashboard({ port: 0, cwd: home, system: collector(), usage: {} });
+  t.after(() => server.close());
+
+  const deep = await get(server, 'api/system?refresh=deep');
+  assert.equal(deep.status, 200);
+  await waitUntil(() => errors.some((e) => /maintenanceOptions\.controlRoot/.test(e)),
+    'the refused default maintenance service must be logged', { timeout: 5000 });
+  const maintenance = await get(server, 'api/maintenance');
+  assert.equal(maintenance.status, 503);
+  assert.equal(fs.existsSync(path.join(paths.maintenanceControlDir())), false,
+    `nothing may be written under ${paths.maintenanceControlDir()}`);
+  assert.equal(errors.filter((e) => /maintenanceOptions\.controlRoot/.test(e)).length, 1, 'logged once, not per request');
+});
+
+test('an explicit control root keeps the default maintenance service available to fakes', async (t) => {
+  const controlRoot = fs.mkdtempSync(path.join(home, 'control-'));
+  const server = await startDashboard({ port: 0, cwd: home, system: collector(), usage: {},
+    maintenanceOptions: { controlRoot } });
+  t.after(() => server.close());
+  const maintenance = await get(server, 'api/maintenance');
+  assert.equal(maintenance.status, 200, maintenance.body);
+  assert.equal(fs.existsSync(paths.maintenanceControlDir()), false);
+});
+
+test('a server with no injected collector keeps its defaults (the real command)', async () => {
+  const { __test } = await import('../../src/lib/dashboard-server.mjs');
+  assert.equal(__test.refusesDefaultState({}), false);
+  assert.equal(__test.refusesDefaultState({ liveOptions: {} }), false);
+  assert.equal(__test.refusesDefaultState({ system: {} }), true);
+  assert.equal(__test.refusesDefaultState({ fetchStatus: async () => ({}) }), true);
+  assert.equal(__test.refusesDefaultState({ system: {}, maintenanceOptions: { controlRoot: '/x' } }), false);
+  assert.equal(__test.refusesDefaultState({ system: {}, maintenance: {} }), false);
+});

From 8f02ab25204c8ba65f823fbca246768b5cb0151e Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:24:22 -0700
Subject: [PATCH 05/28] test(env): stop spawn tests inheriting the developer's
 XDG_* variables

Adds spawnEnv/sandboxEnvFor/INHERITED_STATE_KEYS/redirectToolState to
tests/kit/helpers/home-sandbox.mjs (sandboxHome now builds on sandboxEnvFor,
leaving the temp keys alone) and a static guard, spawn-env-guard.test.mjs,
that fails on any `...process.env` / `env: process.env` in tests/ without a
`spawn-env: inherits (<reason>)` marker.

The guard found 30 sites (the plan estimated 22; none are in tests/*.cjs).
24 now build their child env with spawnEnv(home, extra); 6 carry the marker:
the hostile-env sandbox tripwire, the npm install in the stock-OpenCode test
(needs ~/.npmrc; cache pinned), two paid live AQE release-proof sites and the
two live disposable-memory-project spawns (the caller sandboxes process.env).

adapter-aqe-provider's hidden-transport test overrode only HOME, so its child
read the developer's XDG_CONFIG_HOME kit.json; it still reports "not active"
inside the sandbox. opencode-stock-ruflo-gateway's `opencode --version` probe
passed no env at all (a form the guard cannot see) and created OpenCode's
state/data/cache/temp folders under the inherited bases; it now runs in the
test's sandbox home too.
---
 tests/kit/adapter-aqe-provider.test.mjs       |  4 +-
 tests/kit/clean-machine-setup.test.mjs        | 28 +++---
 tests/kit/cli-help.test.mjs                   |  8 +-
 tests/kit/dry-run-nudge.test.mjs              | 10 +-
 tests/kit/helpers/home-sandbox.mjs            | 92 ++++++++++++++++---
 tests/kit/home-sandbox-tripwire.test.mjs      |  2 +-
 tests/kit/hook-audit.test.mjs                 |  7 +-
 tests/kit/host-cli-migration.test.mjs         |  8 +-
 tests/kit/host-health-connected.test.mjs      |  3 +-
 .../kit/opencode-stock-ruflo-gateway.test.mjs | 15 +--
 tests/kit/prompts-mainline-boundary.test.mjs  | 10 +-
 tests/kit/provider-cli.test.mjs               | 17 +---
 tests/kit/provider-refresh-cli.test.mjs       |  5 +-
 tests/kit/real-state-tripwire.test.mjs        |  5 +-
 tests/kit/run-tests-runner.test.mjs           |  8 +-
 tests/kit/spawn-env-guard.test.mjs            | 69 ++++++++++++++
 .../kit/statusline-config-dir-parity.test.mjs | 12 ++-
 tests/kit/sync-command.test.mjs               |  6 +-
 tests/kit/sync-needs-your-action.test.mjs     |  4 +-
 tests/kit/telemetry-cli.test.mjs              | 14 +--
 tests/kit/usage-cli.test.mjs                  |  8 +-
 .../aqe-external-provider-transport.test.mjs  |  4 +-
 tests/live/disposable-memory-project.mjs      |  4 +-
 23 files changed, 229 insertions(+), 114 deletions(-)
 create mode 100644 tests/kit/spawn-env-guard.test.mjs

diff --git a/tests/kit/adapter-aqe-provider.test.mjs b/tests/kit/adapter-aqe-provider.test.mjs
index a528ea41..51db4b6f 100644
--- a/tests/kit/adapter-aqe-provider.test.mjs
+++ b/tests/kit/adapter-aqe-provider.test.mjs
@@ -21,7 +21,7 @@ import {
   runAdmittedAqeProvider,
   runAdmittedAqeProviderProbe,
 } from '../../src/lib/adapters/aqe-provider.mjs';
-import { sandboxConfigBase } from './helpers/home-sandbox.mjs';
+import { sandboxConfigBase, spawnEnv } from './helpers/home-sandbox.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
@@ -502,7 +502,7 @@ test('hidden CLI transport never emits failure or drift diagnostics on stdout',
       '--expect-hash', 'a'.repeat(64), '--project-root', ROOT,
     ], {
       cwd: ROOT,
-      env: { ...process.env, HOME: home, AK_EXPERIMENTAL_HOST_ADAPTERS: '1' },
+      env: spawnEnv(home, { AK_EXPERIMENTAL_HOST_ADAPTERS: '1' }),
       input: 'prompt',
       encoding: 'utf8',
       timeout: 10_000,
diff --git a/tests/kit/clean-machine-setup.test.mjs b/tests/kit/clean-machine-setup.test.mjs
index 6be5d195..174a2455 100644
--- a/tests/kit/clean-machine-setup.test.mjs
+++ b/tests/kit/clean-machine-setup.test.mjs
@@ -5,7 +5,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { snapshot } from './helpers/home-sandbox.mjs';
+import { snapshot, spawnEnv } from './helpers/home-sandbox.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const BIN = path.join(ROOT, 'bin', 'agentic-kit.mjs');
@@ -18,13 +18,8 @@ test('clean-machine setup preview is hermetic and discloses every auto-approve r
   const noBin = path.join(root, 'no-such-bin');
   fs.mkdirSync(path.join(home, '.config'), { recursive: true });
   fs.mkdirSync(path.join(project, '.git'), { recursive: true });
-  const beforeHome = snapshot(home);
-  const beforeProject = snapshot(project);
-  const env = {
-    ...process.env,
-    HOME: home, USERPROFILE: home,
-    XDG_CONFIG_HOME: path.join(home, '.config'),
-    XDG_STATE_HOME: path.join(home, '.local', 'state'),
+  // spawnEnv creates home/tmp, so the env is built before the snapshots.
+  const env = spawnEnv(home, {
     APPDATA: path.join(home, 'AppData', 'Roaming'),
     npm_config_prefix: prefix,
     npm_config_cache: path.join(root, 'npm-cache'),
@@ -32,7 +27,9 @@ test('clean-machine setup preview is hermetic and discloses every auto-approve r
     PATH: noBin,
     NO_COLOR: '1',
     AQE_EMBEDDER_ENDPOINT: '', AQE_EMBEDDER_TOKEN: '',
-  };
+  });
+  const beforeHome = snapshot(home);
+  const beforeProject = snapshot(project);
   const run = spawnSync(process.execPath, [BIN, 'setup', '--project', '--dry-run', '--yes'], {
     cwd: project, env, encoding: 'utf8', timeout: 30_000,
   });
@@ -55,13 +52,8 @@ test('clean-machine noninteractive trust requires --yes and declines without mut
   const project = path.join(root, 'project');
   fs.mkdirSync(path.join(home, '.config'), { recursive: true });
   fs.mkdirSync(path.join(project, '.git'), { recursive: true });
-  const beforeHome = snapshot(home);
-  const beforeProject = snapshot(project);
-  const env = {
-    ...process.env,
-    HOME: home, USERPROFILE: home,
-    XDG_CONFIG_HOME: path.join(home, '.config'),
-    XDG_STATE_HOME: path.join(home, '.local', 'state'),
+  // spawnEnv creates home/tmp, so the env is built before the snapshots.
+  const env = spawnEnv(home, {
     APPDATA: path.join(home, 'AppData', 'Roaming'),
     npm_config_prefix: path.join(root, 'npm-prefix'),
     npm_config_cache: path.join(root, 'npm-cache'),
@@ -69,7 +61,9 @@ test('clean-machine noninteractive trust requires --yes and declines without mut
     PATH: path.join(root, 'no-such-bin'),
     NO_COLOR: '1',
     AQE_EMBEDDER_ENDPOINT: '', AQE_EMBEDDER_TOKEN: '',
-  };
+  });
+  const beforeHome = snapshot(home);
+  const beforeProject = snapshot(project);
   const run = spawnSync(process.execPath, [BIN, 'setup', '--project'], {
     cwd: project, env, encoding: 'utf8', timeout: 30_000,
   });
diff --git a/tests/kit/cli-help.test.mjs b/tests/kit/cli-help.test.mjs
index 1b8e3504..90fdc30b 100644
--- a/tests/kit/cli-help.test.mjs
+++ b/tests/kit/cli-help.test.mjs
@@ -1,14 +1,18 @@
 // CLI help + dispatch — spawns the real bin. The load-bearing guarantee here
 // is that `--help` is intercepted BEFORE run(), so mutating commands
 // (setup, sync, uninstall) never fire on `ak <cmd> --help`.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { spawnEnv, sandboxProject, rmrf } from './helpers/home-sandbox.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
-const ak = (...args) => spawnSync(process.execPath, [BIN, ...args], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+// A throwaway home: `--help` must never reach the developer's real config or state.
+const HOME = sandboxProject('ak-cli-help');
+after(() => rmrf(HOME));
+const ak = (...args) => spawnSync(process.execPath, [BIN, ...args], { encoding: 'utf8', env: spawnEnv(HOME, { NO_COLOR: '1' }) });
 
 test('setup --help shows help and does NOT run setup', () => {
   const r = ak('setup', '--help');
diff --git a/tests/kit/dry-run-nudge.test.mjs b/tests/kit/dry-run-nudge.test.mjs
index a659e6ba..b6cd25a1 100644
--- a/tests/kit/dry-run-nudge.test.mjs
+++ b/tests/kit/dry-run-nudge.test.mjs
@@ -13,6 +13,7 @@
 // directory happened not to change.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
@@ -51,16 +52,11 @@ test('ak setup --dry-run never invokes npm (the drift nudge is skipped)', { skip
     const r = spawnSync(process.execPath, [BIN, 'setup', '--dry-run', '--project'], {
       encoding: 'utf8',
       cwd: project,
-      env: {
-        ...process.env,
+      env: spawnEnv(home, {
         NO_COLOR: '1',
-        HOME: home,
-        USERPROFILE: home,
-        XDG_CONFIG_HOME: path.join(home, '.config'),
-        APPDATA: path.join(home, '.config'),
         // The fake shim first so it wins over any real npm already on PATH.
         PATH: `${fakeBinDir}${path.delimiter}${process.env.PATH}`,
-      },
+      }),
     });
     assert.equal(r.status, 0, `expected a clean dry-run exit, got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
     assert.match(r.stdout, /dry-run/, 'must reach the dry-run path, not fail before it');
diff --git a/tests/kit/helpers/home-sandbox.mjs b/tests/kit/helpers/home-sandbox.mjs
index 62a3b5a5..e964c160 100644
--- a/tests/kit/helpers/home-sandbox.mjs
+++ b/tests/kit/helpers/home-sandbox.mjs
@@ -22,6 +22,78 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+/** Environment keys that point a child at real per-user state. */
+export const INHERITED_STATE_KEYS = ['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_DATA_HOME',
+  'XDG_CACHE_HOME', 'APPDATA', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME',
+  'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH', 'npm_config_cache'];
+
+/**
+ * Overrides that place every per-user base inside `home`.
+ * @param {string} home
+ * @returns {Record<string, string>}
+ */
+export function sandboxEnvFor(home) {
+  const cfg = path.join(home, '.config');
+  const tmp = path.join(home, 'tmp');
+  return {
+    HOME: home, USERPROFILE: home,
+    XDG_CONFIG_HOME: cfg, APPDATA: cfg,
+    XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    XDG_DATA_HOME: path.join(home, '.local', 'share'),
+    XDG_CACHE_HOME: path.join(home, '.cache'),
+    LOCALAPPDATA: path.join(home, 'AppData', 'Local'),
+    TMPDIR: tmp, TEMP: tmp, TMP: tmp,
+    // npm injects its resolved cache path into lifecycle scripts. Without this
+    // override, otherwise-isolated status/setup runs inspect the developer's
+    // real `_npx` cache and vary with host upgrade cruft.
+    npm_config_cache: path.join(home, '.npm'),
+  };
+}
+
+/**
+ * The environment for a spawned child: process.env minus INHERITED_STATE_KEYS,
+ * plus sandboxEnvFor(home), plus `extra` (last wins). PATH is kept. Creates
+ * `home/tmp` so the child's os.tmpdir() exists.
+ * @param {string} home
+ * @param {Record<string, string|undefined>} [extra]
+ * @returns {Record<string, string|undefined>}
+ */
+export function spawnEnv(home, extra = {}) {
+  const base = { ...process.env }; // spawn-env: inherits (the one sanctioned copy; state keys are removed below)
+  for (const key of INHERITED_STATE_KEYS) delete base[key];
+  fs.mkdirSync(path.join(home, 'tmp'), { recursive: true });
+  return { ...base, ...sandboxEnvFor(home), ...extra };
+}
+
+/**
+ * For in-process tests whose code under test spawns tools with process.env:
+ * point XDG state/data/cache, LOCALAPPDATA and TMPDIR/TEMP/TMP at a fresh folder
+ * under os.tmpdir(); restore() puts the old values back and removes it.
+ * @param {string} prefix
+ * @returns {{ base: string, restore: () => void }}
+ */
+export function redirectToolState(prefix) {
+  const base = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-tools-`)));
+  const keys = ['XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP'];
+  const previous = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+  const tmp = path.join(base, 'tmp');
+  fs.mkdirSync(tmp);
+  Object.assign(process.env, {
+    XDG_STATE_HOME: path.join(base, 'state'), XDG_DATA_HOME: path.join(base, 'data'),
+    XDG_CACHE_HOME: path.join(base, 'cache'), LOCALAPPDATA: path.join(base, 'localappdata'),
+    TMPDIR: tmp, TEMP: tmp, TMP: tmp,
+  });
+  return {
+    base,
+    restore() {
+      for (const [key, value] of Object.entries(previous)) {
+        if (value === undefined) delete process.env[key]; else process.env[key] = value;
+      }
+      fs.rmSync(base, { recursive: true, force: true, maxRetries: 3 });
+    },
+  };
+}
+
 /**
  * Redirect every home-relative kit path at a throwaway directory.
  * @param {string} prefix mkdtemp prefix, for readable leftovers on failure
@@ -29,25 +101,17 @@ import path from 'node:path';
  */
 export function sandboxHome(prefix) {
   const home = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-home-`));
-  const cfg = path.join(home, '.config');
-  fs.mkdirSync(cfg, { recursive: true });
-  process.env.HOME = home;
-  process.env.USERPROFILE = home;
-  process.env.XDG_CONFIG_HOME = cfg;
-  process.env.APPDATA = cfg;
+  fs.mkdirSync(path.join(home, '.config'), { recursive: true });
   // A developer shell may export the other XDG bases (and the host-home overrides)
   // to REAL directories; paths.mjs prefers them over HOME, so each one is pinned
   // inside the sandbox or removed. The state base holds ak's evidence cache and
   // maintenance journal, so leaving it inherited writes the real machine.
-  process.env.XDG_STATE_HOME = path.join(home, '.local', 'state');
-  process.env.XDG_DATA_HOME = path.join(home, '.local', 'share');
-  process.env.XDG_CACHE_HOME = path.join(home, '.cache');
-  process.env.LOCALAPPDATA = path.join(home, 'AppData', 'Local');
+  // The temp keys are left alone: moving os.tmpdir() here would move every later
+  // mkdtempSync of the calling file into this home.
+  const bases = sandboxEnvFor(home);
+  for (const key of ['TMPDIR', 'TEMP', 'TMP']) delete bases[key];
+  Object.assign(process.env, bases);
   for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME']) delete process.env[key];
-  // npm injects its resolved cache path into lifecycle scripts. Without
-  // overriding it here, `npm test` lets otherwise-isolated status/setup tests
-  // inspect the developer's real `_npx` cache and vary with host upgrade cruft.
-  process.env.npm_config_cache = path.join(home, '.npm');
   process.env.NO_COLOR = '1';
   // Nothing invokable on PATH: every exec.run() spawn ENOENTs immediately, so
   // these tests never launch a real claude/npm/ruflo/aqe and never depend on
diff --git a/tests/kit/home-sandbox-tripwire.test.mjs b/tests/kit/home-sandbox-tripwire.test.mjs
index 78e34e75..b400c46a 100644
--- a/tests/kit/home-sandbox-tripwire.test.mjs
+++ b/tests/kit/home-sandbox-tripwire.test.mjs
@@ -30,7 +30,7 @@ function runChild(t, body) {
     ${body}
   `;
   const r = spawnSync(process.execPath, ['--input-type=module', '-e', script], {
-    env: { ...process.env, ...hostile }, encoding: 'utf8',
+    env: { ...process.env, ...hostile }, encoding: 'utf8', // spawn-env: inherits (the hostile inherited env is what this test exercises)
   });
   return { ...r, outside };
 }
diff --git a/tests/kit/hook-audit.test.mjs b/tests/kit/hook-audit.test.mjs
index 16c35cc4..27100ff3 100644
--- a/tests/kit/hook-audit.test.mjs
+++ b/tests/kit/hook-audit.test.mjs
@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 import { auditCodexHooks } from '../../src/lib/hook-audit/index.mjs';
 
@@ -348,7 +349,7 @@ test('enabled-plugin discovery failures are counted and make CLI JSON exit nonze
 
     const result = spawnSync(process.execPath, [path.join(repoRoot, 'bin', 'agentic-kit.mjs'), 'audit', 'hooks', '--json'], {
       cwd: fx.project,
-      env: { ...process.env, CODEX_HOME: fx.codexHome },
+      env: spawnEnv(path.join(fx.root, 'home'), { CODEX_HOME: fx.codexHome }),
       encoding: 'utf8',
     });
     assert.equal(result.status, 1, result.stderr || result.stdout);
@@ -415,7 +416,7 @@ test('ak audit hooks exposes the read-only audit as a porcelain command', () =>
   try {
     const result = spawnSync(process.execPath, [path.join(repoRoot, 'bin', 'agentic-kit.mjs'), 'audit', 'hooks', '--json'], {
       cwd: fx.project,
-      env: { ...process.env, CODEX_HOME: fx.codexHome },
+      env: spawnEnv(path.join(fx.root, 'home'), { CODEX_HOME: fx.codexHome }),
       encoding: 'utf8',
     });
     assert.equal(result.status, 0, result.stderr || result.stdout);
@@ -432,7 +433,7 @@ test('ak audit hooks human output is not followed by the generic network drift n
   try {
     const result = spawnSync(process.execPath, [path.join(repoRoot, 'bin', 'agentic-kit.mjs'), 'audit', 'hooks'], {
       cwd: fx.project,
-      env: { ...process.env, CODEX_HOME: fx.codexHome },
+      env: spawnEnv(path.join(fx.root, 'home'), { CODEX_HOME: fx.codexHome }),
       encoding: 'utf8',
       timeout: 3_000,
     });
diff --git a/tests/kit/host-cli-migration.test.mjs b/tests/kit/host-cli-migration.test.mjs
index 1f6bd159..3209999d 100644
--- a/tests/kit/host-cli-migration.test.mjs
+++ b/tests/kit/host-cli-migration.test.mjs
@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
 
@@ -16,15 +17,12 @@ function sandbox() {
   return {
     home,
     project,
-    env: {
-      ...process.env,
+    env: spawnEnv(home, {
       NO_COLOR: '1',
-      HOME: home,
-      USERPROFILE: home,
       XDG_CONFIG_HOME: config,
       APPDATA: config,
       PATH: path.join(home, 'no-such-bin'),
-    },
+    }),
   };
 }
 
diff --git a/tests/kit/host-health-connected.test.mjs b/tests/kit/host-health-connected.test.mjs
index 3137338f..8b116021 100644
--- a/tests/kit/host-health-connected.test.mjs
+++ b/tests/kit/host-health-connected.test.mjs
@@ -1,6 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { checkHostConnection } from '../../src/lib/host-health-connected.mjs';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const help = '--safe-mode --print --output-format --tools --strict-mcp-config --mcp-config --settings --no-session-persistence --disable-slash-commands --permission-mode --json --sandbox --ephemeral --disable --pure --agent --format';
 const features = ['plugins', 'remote_plugin', 'hooks', 'apps', 'shell_tool', 'unified_exec', 'multi_agent', 'skill_mcp_dependency_install', 'browser_use', 'computer_use', 'code_mode', 'code_mode_host', 'image_generation', 'workspace_dependencies'].map(x => `${x} stable true`).join('\n');
@@ -213,7 +214,7 @@ let input='';process.stdin.on('data',chunk=>input+=chunk);process.stdin.on('end'
  console.log(JSON.stringify({type:'result',subtype:'success',is_error:false,result}));
 });
 `, { mode: 0o700 });
-  const env = { ...process.env, PATH: dir + path.delimiter + process.env.PATH };
+  const env = spawnEnv(dir, { PATH: dir + path.delimiter + process.env.PATH });
   const success = await checkHostConnection({ ...base, cwd: dir, host: 'claude', env });
   assert.equal(success.state, 'pass');
   const pidFile = path.join(dir, 'child.pid');
diff --git a/tests/kit/opencode-stock-ruflo-gateway.test.mjs b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
index f30c48b8..bd00913d 100644
--- a/tests/kit/opencode-stock-ruflo-gateway.test.mjs
+++ b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
@@ -13,6 +13,7 @@ import {
   isSupportedStockOpenCodeVersion,
   STOCK_OPENCODE_VERSION_RANGE,
 } from './helpers/opencode-version-policy.mjs';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const harnessRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const pkgRoot = process.env.AK_STOCK_PACKAGE_ROOT
@@ -125,7 +126,7 @@ function seedStockPluginRuntime(configDir, cacheDir, version) {
     `@opencode-ai/plugin@${version}`,
   ], {
     cwd: configDir,
-    env: { ...process.env, npm_config_cache: cacheDir },
+    env: { ...process.env, npm_config_cache: cacheDir }, // spawn-env: inherits (npm needs the developer's registry config in ~/.npmrc; its cache is pinned)
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     timeout: 45_000,
@@ -298,7 +299,11 @@ test(`stock OpenCode keeps Ruflo and Agentic QE connected with ${compactProjecti
     fs.rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
   });
 
-  const reportedVersion = execFileSync(opencode, ['--version'], { encoding: 'utf8' }).trim();
+  // Even `--version` creates OpenCode's state/data/cache/temp folders under the
+  // inherited XDG_* bases, so the probe runs in the sandbox too.
+  const reportedVersion = execFileSync(opencode, ['--version'], {
+    encoding: 'utf8', env: spawnEnv(path.join(root, 'home')),
+  }).trim();
   const binarySha256 = createHash('sha256').update(fs.readFileSync(opencode)).digest('hex');
   const version = extractStockOpenCodeVersion(reportedVersion);
   assert.equal(
@@ -390,9 +395,7 @@ test(`stock OpenCode keeps Ruflo and Agentic QE connected with ${compactProjecti
   const port = await freePort();
   processes.opencode = spawn(opencode, ['serve', '--hostname', '127.0.0.1', '--port', String(port), '--print-logs', '--log-level', 'DEBUG'], {
     cwd: workspace,
-    env: {
-      ...process.env,
-      HOME: path.join(root, 'home'),
+    env: spawnEnv(path.join(root, 'home'), {
       XDG_CONFIG_HOME: configHome,
       XDG_CACHE_HOME: path.join(root, 'cache'),
       XDG_DATA_HOME: path.join(root, 'data'),
@@ -401,7 +404,7 @@ test(`stock OpenCode keeps Ruflo and Agentic QE connected with ${compactProjecti
       PATH: `${fakeBin}${path.delimiter}${process.env.PATH}`,
       AK_STOCK_GATEWAY_MCP_LOG: mcpLog,
       OPENCODE_DISABLE_LSP_DOWNLOAD: '1',
-    },
+    }),
     stdio: ['ignore', 'pipe', 'pipe'],
   });
   processes.opencode.stdout.on('data', (chunk) => output.push(String(chunk)));
diff --git a/tests/kit/prompts-mainline-boundary.test.mjs b/tests/kit/prompts-mainline-boundary.test.mjs
index a0635962..f1269ace 100644
--- a/tests/kit/prompts-mainline-boundary.test.mjs
+++ b/tests/kit/prompts-mainline-boundary.test.mjs
@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
@@ -15,14 +16,7 @@ function runUsage(args) {
     return spawnSync(process.execPath, [BIN, 'usage', ...args], {
       cwd: home,
       encoding: 'utf8',
-      env: {
-        ...process.env,
-        HOME: home,
-        USERPROFILE: home,
-        XDG_CONFIG_HOME: path.join(home, '.config'),
-        XDG_DATA_HOME: path.join(home, '.local', 'share'),
-        NO_COLOR: '1',
-      },
+      env: spawnEnv(home, { NO_COLOR: '1' }),
     });
   } finally {
     fs.rmSync(home, { recursive: true, force: true });
diff --git a/tests/kit/provider-cli.test.mjs b/tests/kit/provider-cli.test.mjs
index 85debc41..a82a3e60 100644
--- a/tests/kit/provider-cli.test.mjs
+++ b/tests/kit/provider-cli.test.mjs
@@ -6,6 +6,7 @@
 // reads APPDATA (not XDG_CONFIG_HOME) on win32, so both must be set or the
 // sandbox is silently bypassed there.
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -72,15 +73,12 @@ function ak(args, { cwd, home, env = {} }) {
   return spawnSync(process.execPath, [BIN, ...args], {
     encoding: 'utf8',
     cwd,
-    env: {
-      ...process.env,
+    env: spawnEnv(home, {
       NO_COLOR: '1',
-      HOME: home,
-      USERPROFILE: home, // Windows os.homedir() reads USERPROFILE, not HOME
       XDG_CONFIG_HOME: cfgDir,
       APPDATA: cfgDir, // Windows configBase() reads APPDATA, not XDG_CONFIG_HOME
       ...env,
-    },
+    }),
   });
 }
 
@@ -229,20 +227,15 @@ function akPick(args, { cwd, project, home, binDir, catalog }, { input, env = {}
     // (settings.local.json, llm-config.json) would land there.
     cwd: cwd ?? project,
     input,
-    env: {
-      ...process.env,
+    env: spawnEnv(home, {
       NO_COLOR: '1',
-      HOME: home,
-      USERPROFILE: home,
-      XDG_CONFIG_HOME: path.join(home, '.config'),
-      APPDATA: path.join(home, '.config'),
       // FULLY controlled PATH: only the fixture shims + the system dirs the
       // `which` probe needs. Real CLIs/npm on the developer's machine can
       // never leak in and make detection non-deterministic.
       PATH: [binDir, '/usr/bin', '/bin'].join(path.delimiter),
       RUFLO_REPO: catalog,
       ...env,
-    },
+    }),
   });
 }
 
diff --git a/tests/kit/provider-refresh-cli.test.mjs b/tests/kit/provider-refresh-cli.test.mjs
index 468d1fd1..3b4730ae 100644
--- a/tests/kit/provider-refresh-cli.test.mjs
+++ b/tests/kit/provider-refresh-cli.test.mjs
@@ -5,6 +5,7 @@
 // (unlike `pick`, which can trigger installs). Everything is redirected at a
 // throwaway HOME — see provider-cli.test.mjs for why all four env vars matter.
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -51,12 +52,12 @@ const readKit = (home) =>
 
 function ak(args, { cwd, home, env = {} }) {
   const cfgDir = path.join(home, '.config');
-  const clean = { ...process.env };
+  const clean = spawnEnv(home, { NO_COLOR: '1', XDG_CONFIG_HOME: cfgDir, APPDATA: cfgDir });
   for (const k of ALL_CREDENTIAL_ENV) delete clean[k];
   const r = spawnSync(process.execPath, [BIN, ...args], {
     encoding: 'utf8',
     cwd,
-    env: { ...clean, NO_COLOR: '1', HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: cfgDir, APPDATA: cfgDir, ...env },
+    env: { ...clean, ...env },
   });
   return { ...r, all: `${r.stdout}${r.stderr}` };
 }
diff --git a/tests/kit/real-state-tripwire.test.mjs b/tests/kit/real-state-tripwire.test.mjs
index 7bf2313d..3fd2ada1 100644
--- a/tests/kit/real-state-tripwire.test.mjs
+++ b/tests/kit/real-state-tripwire.test.mjs
@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 import {
   REPO_STATE_DIRS, realStateRoots, snapshotRoots, compareSnapshots, isStrict, formatReport,
 } from '../../scripts/real-state-tripwire.mjs';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'real-state-tripwire.mjs');
 const tmp = (t, prefix) => {
@@ -129,9 +130,7 @@ test('the CLI snapshot/compare pair exits 3 and names the changed path', (t) =>
   const home = tmp(t, 'ak-trip-cli');
   const repo = path.join(home, 'repo');
   fs.mkdirSync(repo);
-  const env = { ...process.env, HOME: home, USERPROFILE: home, CI: 'true',
-    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
-    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local') };
+  const env = spawnEnv(home, { CI: 'true', APPDATA: path.join(home, 'AppData', 'Roaming') });
   const out = path.join(home, 'before.json');
   const snap = spawnSync(process.execPath, [CLI, 'snapshot', out, '--repo', repo], { env, encoding: 'utf8' });
   assert.equal(snap.status, 0, snap.stderr);
diff --git a/tests/kit/run-tests-runner.test.mjs b/tests/kit/run-tests-runner.test.mjs
index 734fe916..28dbc968 100644
--- a/tests/kit/run-tests-runner.test.mjs
+++ b/tests/kit/run-tests-runner.test.mjs
@@ -6,6 +6,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const RUNNER = path.join(ROOT, 'scripts', 'run-tests.mjs');
@@ -15,11 +16,8 @@ function sandbox(t) {
   t.after(() => fs.rmSync(home, { recursive: true, force: true }));
   const repo = path.join(home, 'repo');
   fs.mkdirSync(path.join(repo, '.git'), { recursive: true });
-  const env = { ...process.env, HOME: home, USERPROFILE: home,
-    XDG_CONFIG_HOME: path.join(home, '.config'), XDG_STATE_HOME: path.join(home, '.local', 'state'),
-    XDG_DATA_HOME: path.join(home, '.local', 'share'), XDG_CACHE_HOME: path.join(home, '.cache'),
-    APPDATA: path.join(home, 'AppData', 'Roaming'), LOCALAPPDATA: path.join(home, 'AppData', 'Local'), CI: 'true' };
-  for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'AK_TRIPWIRE_STRICT']) delete env[key];
+  const env = spawnEnv(home, { APPDATA: path.join(home, 'AppData', 'Roaming'), CI: 'true' });
+  delete env.AK_TRIPWIRE_STRICT;
   return { home, repo, env };
 }
 
diff --git a/tests/kit/spawn-env-guard.test.mjs b/tests/kit/spawn-env-guard.test.mjs
new file mode 100644
index 00000000..29efd6ef
--- /dev/null
+++ b/tests/kit/spawn-env-guard.test.mjs
@@ -0,0 +1,69 @@
+// tests/kit/spawn-env-guard.test.mjs
+// A spawned child that inherits the developer's XDG_*/LOCALAPPDATA/TMPDIR writes
+// that developer's real tool state (six files created ~/.local/state/opencode,
+// ~/.cache/opencode and ~/.local/share/opencode this way). Every child env in
+// tests/ is built by spawnEnv()/sandboxEnvFor(); a deliberate exception carries
+// the marker comment `spawn-env: inherits (<reason>)` on the same line.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { spawnEnv, sandboxEnvFor, INHERITED_STATE_KEYS } from './helpers/home-sandbox.mjs';
+
+const TESTS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SELF = fileURLToPath(import.meta.url);
+const HELPER = path.join(TESTS, 'kit', 'helpers', 'home-sandbox.mjs');
+const INHERIT = /\.\.\.\s*process\.env\b|env:\s*process\.env\b/;
+
+function files(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) { if (e.name !== 'fixtures') files(full, out); } else if (/\.(mjs|cjs|js)$/.test(e.name)) out.push(full);
+  }
+  return out;
+}
+
+test('no test builds a child environment from process.env outside the sandbox helper', () => {
+  const offenders = [];
+  for (const file of files(TESTS)) {
+    if (file === SELF || file === HELPER) continue;
+    fs.readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+      if (INHERIT.test(line) && !/spawn-env: inherits \(.+\)/.test(line)) offenders.push(`${path.relative(TESTS, file)}:${i + 1}`);
+    });
+  }
+  assert.deepEqual(offenders, [], `use spawnEnv(home, extra) from tests/kit/helpers/home-sandbox.mjs:\n  ${offenders.join('\n  ')}`);
+});
+
+const tempHome = (t) => {
+  const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-spawn-env-')));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+};
+
+test('spawnEnv pins every per-user base inside the sandbox, whatever the parent exported', (t) => {
+  const home = tempHome(t);
+  const env = spawnEnv(home, { EXTRA: '1' });
+  for (const key of ['HOME', 'USERPROFILE', 'XDG_CONFIG_HOME', 'XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME',
+    'APPDATA', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP', 'npm_config_cache']) {
+    assert.ok(env[key] && env[key].startsWith(home), `${key}=${env[key]} escapes ${home}`);
+  }
+  for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH']) {
+    assert.equal(env[key], undefined, `${key} must not be inherited`);
+  }
+  assert.equal(env.PATH, process.env.PATH);
+  assert.equal(env.EXTRA, '1');
+  assert.deepEqual(Object.keys(sandboxEnvFor(home)).sort(),
+    INHERITED_STATE_KEYS.filter((k) => !['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH'].includes(k)).sort());
+});
+
+test('a real child sees the sandboxed state base, not the parent one', (t) => {
+  const home = tempHome(t);
+  const r = spawnSync(process.execPath, ['-e', 'console.log(JSON.stringify([process.env.XDG_STATE_HOME, require("os").tmpdir()]))'],
+    { env: spawnEnv(home), encoding: 'utf8' });
+  const [state, tmp] = JSON.parse(r.stdout);
+  assert.ok(state.startsWith(home));
+  assert.ok(tmp.startsWith(home));
+});
diff --git a/tests/kit/statusline-config-dir-parity.test.mjs b/tests/kit/statusline-config-dir-parity.test.mjs
index d801743e..46522c5e 100644
--- a/tests/kit/statusline-config-dir-parity.test.mjs
+++ b/tests/kit/statusline-config-dir-parity.test.mjs
@@ -11,6 +11,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 // A bare absolute path is not a valid ESM specifier on Windows (`D:` parses as a URL
@@ -21,18 +22,19 @@ const block = fs.readFileSync(path.join(ROOT, 'src', 'templates', 'statusline-fo
 // First-party template source, the same extraction the statusline suites use.
 const templateConfigDir = new Function(`${block}\nreturn rufloKitConfigDir;`)();
 
-function cleanEnv() {
-  const out = { ...process.env };
+// The sandboxed child env (Windows needs SystemRoot etc.) minus the variables under
+// test, unless the case sets them.
+function caseEnv(home, env) {
+  const out = spawnEnv(home);
   for (const key of Object.keys(out)) if (/^(XDG_CONFIG_HOME|APPDATA)$/i.test(key)) delete out[key];
-  return out;
+  return { ...out, ...env };
 }
 
 function realConfigDir(platform, env, home) {
   const script = `Object.defineProperty(process,'platform',{value:${JSON.stringify(platform)}});`
     + `const {configDir}=await import(${JSON.stringify(PATHS_URL)});process.stdout.write(configDir());`;
   return execFileSync(process.execPath, ['--input-type=module', '-e', script], {
-    // Inherit the runner's env (Windows needs SystemRoot etc.) minus the variables under test.
-    env: { ...cleanEnv(), HOME: home, USERPROFILE: home, ...env }, encoding: 'utf8',
+    env: caseEnv(home, env), encoding: 'utf8',
   });
 }
 
diff --git a/tests/kit/sync-command.test.mjs b/tests/kit/sync-command.test.mjs
index f1914bb2..4b37fd51 100644
--- a/tests/kit/sync-command.test.mjs
+++ b/tests/kit/sync-command.test.mjs
@@ -13,7 +13,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   sandboxHome, assertSandboxed, snapshot, assertUnchanged, captureLog, rmrf,
-  sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot,
+  sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot, spawnEnv,
 } from './helpers/home-sandbox.mjs';
 import { isolateProject } from './helpers/project-isolation.mjs';
 
@@ -816,7 +816,7 @@ function syncChild({ first = [], after = [], flags = {}, throws = false }) {
       pkgRoot: ${JSON.stringify(PKG_ROOT)}, collectFn }));
   `;
   return spawnSync(process.execPath, ['--input-type=module', '-e', script], {
-    cwd: PROJECT, env: process.env, encoding: 'utf8', timeout: 120_000,
+    cwd: PROJECT, env: spawnEnv(HOME), encoding: 'utf8', timeout: 120_000,
   });
 }
 
@@ -825,7 +825,7 @@ function akSync(args) {
   const root = fakeGlobalRoot(HOME, { ruflo: '9.9.9', 'agentic-qe': '9.9.9' });
   return spawnSync(process.execPath, [BIN, 'sync', ...args], {
     cwd: PROJECT, encoding: 'utf8', timeout: 120_000,
-    env: { ...process.env, npm_config_prefix: path.dirname(root) },
+    env: spawnEnv(HOME, { npm_config_prefix: path.dirname(root) }),
   });
 }
 
diff --git a/tests/kit/sync-needs-your-action.test.mjs b/tests/kit/sync-needs-your-action.test.mjs
index 77582209..d483b119 100644
--- a/tests/kit/sync-needs-your-action.test.mjs
+++ b/tests/kit/sync-needs-your-action.test.mjs
@@ -18,7 +18,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
-  sandboxHome, assertSandboxed, captureLog, rmrf, sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot,
+  sandboxHome, assertSandboxed, captureLog, rmrf, sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot, spawnEnv,
 } from './helpers/home-sandbox.mjs';
 import { isolateProject } from './helpers/project-isolation.mjs';
 
@@ -95,7 +95,7 @@ function syncJson({ first = [], after = first, flags = {}, throws = false }) {
       pkgRoot: ${JSON.stringify(PKG_ROOT)}, collectFn }));
   `;
   const child = spawnSync(process.execPath, ['--input-type=module', '-e', script], {
-    cwd: PROJECT, env: process.env, encoding: 'utf8', timeout: 120_000,
+    cwd: PROJECT, env: spawnEnv(HOME), encoding: 'utf8', timeout: 120_000,
   });
   assert.ok(child.stdout.trim().startsWith('{'), `stdout is not a JSON object:\n${child.stdout}\n--- stderr:\n${child.stderr}`);
   return { child, out: JSON.parse(child.stdout) };
diff --git a/tests/kit/telemetry-cli.test.mjs b/tests/kit/telemetry-cli.test.mjs
index a62321c1..c39fbfa5 100644
--- a/tests/kit/telemetry-cli.test.mjs
+++ b/tests/kit/telemetry-cli.test.mjs
@@ -7,6 +7,7 @@ import { spawnSync } from 'node:child_process';
 import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { fixture, identity, now } from './helpers/telemetry.mjs';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 const storePath = '../../src/lib/telemetry/store.mjs';
 const bin = new URL('../../bin/agentic-kit.mjs', import.meta.url);
 function temporary(t) {
@@ -103,12 +104,11 @@ test('should_exportHermeticLocalEvidence_when_invokingRealCli', t => {
   // must override it, or the export absorbs them (same class as usage-cli).
   const outside = temporary(t);
   writeOpencodeStore(outside);
-  const shell = { ...process.env, XDG_DATA_HOME: outside };
-  // Pin every XDG base and drop the host-home overrides, as sandboxHome() does.
-  const env = { ...shell, HOME: dir, USERPROFILE: dir, XDG_CONFIG_HOME: path.join(dir, 'config'),
+  // spawnEnv drops the inherited XDG_DATA_HOME (and every other per-user base)
+  // and pins each one inside the sandbox; the decoy store proves it.
+  const env = spawnEnv(dir, { XDG_CONFIG_HOME: path.join(dir, 'config'),
     XDG_STATE_HOME: path.join(dir, 'state'), XDG_DATA_HOME: path.join(dir, 'data'), XDG_CACHE_HOME: path.join(dir, 'cache'),
-    APPDATA: path.join(dir, 'config'), LOCALAPPDATA: path.join(dir, 'state'), CLAUDE_CONFIG_DIR: path.join(dir, '.claude') };
-  for (const key of ['CODEX_HOME', 'HERMES_HOME']) delete env[key];
+    APPDATA: path.join(dir, 'config'), LOCALAPPDATA: path.join(dir, 'state'), CLAUDE_CONFIG_DIR: path.join(dir, '.claude') });
   const invoke = args => spawnSync(process.execPath, [fileURLToPath(bin), 'telemetry', ...args], { encoding: 'utf8', env });
   const first = invoke(['export']);
   assert.equal(first.status, 0, first.stderr);
@@ -181,8 +181,8 @@ test('should_readRetainedMaintenance_when_exportingOffline', t => {
   const root = path.join(state, 'agentic-kit', 'maintenance', 'transactions');
   fs.mkdirSync(path.join(root, 'mnt-corrupt'), { recursive: true, mode: 0o700 });
   const result = spawnSync(process.execPath, [fileURLToPath(bin), 'telemetry', 'export'], { encoding: 'utf8',
-    env: { ...process.env, HOME: dir, USERPROFILE: dir, XDG_CONFIG_HOME: path.join(dir, 'config'),
-      XDG_STATE_HOME: state, LOCALAPPDATA: state, APPDATA: path.join(dir, 'config'), CLAUDE_CONFIG_DIR: path.join(dir, '.claude') } });
+    env: spawnEnv(dir, { XDG_CONFIG_HOME: path.join(dir, 'config'),
+      XDG_STATE_HOME: state, LOCALAPPDATA: state, APPDATA: path.join(dir, 'config'), CLAUDE_CONFIG_DIR: path.join(dir, '.claude') }) });
   assert.equal(result.status, 0, result.stderr);
   assert.equal(JSON.parse(result.stdout).maintenance.receipts[0].status, 'unknown-recovery-required');
 });
diff --git a/tests/kit/usage-cli.test.mjs b/tests/kit/usage-cli.test.mjs
index fe740f48..208417db 100644
--- a/tests/kit/usage-cli.test.mjs
+++ b/tests/kit/usage-cli.test.mjs
@@ -8,6 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { MODES } from '../../src/lib/usage-modes.mjs';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
 
@@ -180,11 +181,8 @@ function ak(args, sb, extra = {}) {
     encoding: 'utf8',
     // Keep every CLI run hermetic from the repository that launched the test.
     cwd: sb.cwd ?? sb.home,
-    env: {
-      ...process.env,
+    env: spawnEnv(sb.home, {
       NO_COLOR: '1',
-      HOME: sb.home,
-      USERPROFILE: sb.home,
       XDG_CONFIG_HOME: sb.cfg,
       APPDATA: sb.cfg,
       // The opencode transcript store is found at `$XDG_DATA_HOME/opencode/`
@@ -197,7 +195,7 @@ function ak(args, sb, extra = {}) {
       PATH: `${sb.bin}${path.delimiter}${process.env.PATH ?? ''}`,
       OPENROUTER_MANAGEMENT_KEY: '',
       ...extra,
-    },
+    }),
   });
 }
 
diff --git a/tests/live/aqe-external-provider-transport.test.mjs b/tests/live/aqe-external-provider-transport.test.mjs
index 7ac657b4..7056d6e1 100644
--- a/tests/live/aqe-external-provider-transport.test.mjs
+++ b/tests/live/aqe-external-provider-transport.test.mjs
@@ -289,7 +289,7 @@ test('Agentic-QE 3.14.1+ serves advisors without fallback and generation with ex
   process.env.APPDATA = xdg;
   const bootstrap = await bootstrapHostAdapters({
     cfg,
-    env: { ...process.env, AK_EXPERIMENTAL_HOST_ADAPTERS: '1' },
+    env: { ...process.env, AK_EXPERIMENTAL_HOST_ADAPTERS: '1' }, // spawn-env: inherits (paid live release proof; config bases pinned just above)
   });
   assert.equal(bootstrap.warnings.length, 0, JSON.stringify(bootstrap.warnings));
   assert.equal(bootstrap.admitted.length, 1);
@@ -303,7 +303,7 @@ test('Agentic-QE 3.14.1+ serves advisors without fallback and generation with ex
   assert.ok(!(projectedConfig.fallbackChain?.entries ?? []).some((entry) => entry.provider === PROVIDER_ID));
 
   const env = {
-    ...process.env,
+    ...process.env, // spawn-env: inherits (paid live release proof against the installed aqe; HOME/config pinned below)
     HOME: home,
     XDG_CONFIG_HOME: xdg,
     APPDATA: xdg,
diff --git a/tests/live/disposable-memory-project.mjs b/tests/live/disposable-memory-project.mjs
index aea92e93..24b7fd8b 100644
--- a/tests/live/disposable-memory-project.mjs
+++ b/tests/live/disposable-memory-project.mjs
@@ -50,9 +50,9 @@ export async function createDisposableMemoryProject({
   const env = disposableMemoryEnv(root);
   try {
     fs.writeFileSync(path.join(root, 'claude-flow.config.json'), `${JSON.stringify({ daemon: { autostart: false } }, null, 2)}\n`);
-    const git = await runner('git', ['init', '-q'], { cwd: root, env: process.env, timeout: 30_000 });
+    const git = await runner('git', ['init', '-q'], { cwd: root, env: process.env, timeout: 30_000 }); // spawn-env: inherits (live: real git; the caller sandboxes process.env)
     if (git.code !== 0) throw new Error(`git init failed: ${git.stderr}`);
-    const init = await runner('ruflo', ['memory', 'init'], { cwd: root, env: { ...process.env, ...env }, timeout: 120_000 });
+    const init = await runner('ruflo', ['memory', 'init'], { cwd: root, env: { ...process.env, ...env }, timeout: 120_000 }); // spawn-env: inherits (live: the real ruflo on PATH; the caller sandboxes process.env)
     if (init.code !== 0) throw new Error(`ruflo memory init failed: ${String(init.stderr).trim().slice(-400)}`);
   } catch (error) {
     removeProject(root);

From 12f01f1abd2eb42979975ca4eb26b551ad15c7f6 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:25:52 -0700
Subject: [PATCH 06/28] test(opencode): stop six tests creating
 $XDG_STATE_HOME/opencode

integration-command-facts, opencode and provider-credentials call code that
spawns the real `opencode` with process.env; each now runs under
redirectToolState(), so OpenCode's state/data/cache/temp folders land in a
per-file temp base that is removed afterwards. The three direct-spawn files
(opencode-stock-ruflo-gateway, provider-cli, provider-refresh-cli) were fixed
by the spawnEnv conversion in the previous commit; a per-file probe with the
XDG bases and TMPDIR redirected shows no leftovers for any of the six.

opencode-state-hermeticity.test.mjs runs the three in-process files in a
nested `node --test` and requires the watched bases to stay empty. The
nested run must not inherit NODE_TEST_CONTEXT: with it, the child runs no
test and the check passes vacuously (observed), so the variable is dropped
and the child's TAP output must report at least one pass.
---
 tests/kit/integration-command-facts.test.mjs  |  8 +++-
 tests/kit/opencode-state-hermeticity.test.mjs | 38 +++++++++++++++++++
 tests/kit/opencode.test.mjs                   |  8 +++-
 tests/kit/provider-credentials.test.mjs       |  8 +++-
 4 files changed, 59 insertions(+), 3 deletions(-)
 create mode 100644 tests/kit/opencode-state-hermeticity.test.mjs

diff --git a/tests/kit/integration-command-facts.test.mjs b/tests/kit/integration-command-facts.test.mjs
index ea9e383b..cdce91be 100644
--- a/tests/kit/integration-command-facts.test.mjs
+++ b/tests/kit/integration-command-facts.test.mjs
@@ -1,7 +1,13 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { collectIntegrationFacts, commandHosts } from '../../src/lib/providers.mjs';
 import { HOST_REGISTRY } from '../../src/lib/adapters/index.mjs';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
+
+// Code under test spawns the real `opencode` with process.env; keep its
+// state/data/cache/temp folders out of the developer's real ones.
+const toolState = redirectToolState('ak-integration-command-facts');
+after(() => toolState.restore());
 
 test('commands share one immutable normalized integration snapshot', async () => {
   const cfg = {
diff --git a/tests/kit/opencode-state-hermeticity.test.mjs b/tests/kit/opencode-state-hermeticity.test.mjs
new file mode 100644
index 00000000..3e5f2df3
--- /dev/null
+++ b/tests/kit/opencode-state-hermeticity.test.mjs
@@ -0,0 +1,38 @@
+// tests/kit/opencode-state-hermeticity.test.mjs
+// Six test files created OpenCode's own folders under the developer's
+// XDG_STATE_HOME/XDG_CACHE_HOME/XDG_DATA_HOME and TMPDIR (per-file probe,
+// Branch 2 plan). Runs the three in-process ones with those bases pointed at a
+// watched folder and requires the folder to stay empty. The three direct-spawn
+// files are covered by spawn-env-guard.test.mjs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const KIT = path.dirname(fileURLToPath(import.meta.url));
+const IN_PROCESS = ['integration-command-facts', 'opencode', 'provider-credentials'];
+
+for (const name of IN_PROCESS) {
+  test(`${name}.test.mjs leaves the inherited tool-state bases untouched`, { timeout: 300_000 }, (t) => {
+    const watched = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-oc-watch-')));
+    t.after(() => fs.rmSync(watched, { recursive: true, force: true }));
+    for (const d of ['state', 'data', 'cache', 'tmp']) fs.mkdirSync(path.join(watched, d));
+    const env = { ...process.env, // spawn-env: inherits (this test measures exactly what an inheriting run leaks)
+      XDG_STATE_HOME: path.join(watched, 'state'), XDG_DATA_HOME: path.join(watched, 'data'),
+      XDG_CACHE_HOME: path.join(watched, 'cache'), TMPDIR: path.join(watched, 'tmp'),
+      TEMP: path.join(watched, 'tmp'), TMP: path.join(watched, 'tmp') };
+    // Inherited from the outer runner, it turns the nested `node --test` into a
+    // reporting child that runs nothing, and this check would pass vacuously.
+    delete env.NODE_TEST_CONTEXT;
+    const r = spawnSync(process.execPath, ['--test', '--test-reporter=tap', path.join(KIT, `${name}.test.mjs`)],
+      { encoding: 'utf8', env });
+    assert.equal(r.status, 0, r.stdout + r.stderr);
+    assert.match(r.stdout, /^# pass [1-9]/m, `the nested run executed no test:\n${r.stdout}`);
+    const leaked = ['state', 'data', 'cache', 'tmp'].flatMap((d) => fs.readdirSync(path.join(watched, d))
+      .filter((n) => n !== 'node-compile-cache').map((n) => `${d}/${n}`));
+    assert.deepEqual(leaked, []);
+  });
+}
diff --git a/tests/kit/opencode.test.mjs b/tests/kit/opencode.test.mjs
index 6aedd3cb..4b68e4f4 100644
--- a/tests/kit/opencode.test.mjs
+++ b/tests/kit/opencode.test.mjs
@@ -1,4 +1,4 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -13,6 +13,12 @@ import {
 import { runLifecycle } from '../../src/lib/adapters/lifecycle.mjs';
 import { detectHosts } from '../../src/lib/providers.mjs';
 import { guidanceTargets, BUILTIN_BLOCKS } from '../../src/lib/blocks.mjs';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
+
+// Code under test spawns the real `opencode` with process.env; keep its
+// state/data/cache/temp folders out of the developer's real ones.
+const toolState = redirectToolState('ak-opencode');
+after(() => toolState.restore());
 
 const tmp = (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix));
 const rm = (d) => fs.rmSync(d, { recursive: true, force: true });
diff --git a/tests/kit/provider-credentials.test.mjs b/tests/kit/provider-credentials.test.mjs
index 78a5adc2..2243d271 100644
--- a/tests/kit/provider-credentials.test.mjs
+++ b/tests/kit/provider-credentials.test.mjs
@@ -5,7 +5,7 @@
 // whose second rung had no API key was written, reported `ok`, and only failed
 // at QE-run time — far from the config that caused it. These tests pin the
 // credential layer and the write-time warning that consumes it.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -17,6 +17,12 @@ import {
   credentialGaps, detectAqeProviders, fallbackSource,
   applyAqeRouter, aqeRouterFile, collectIntegrationFacts,
 } from '../../src/lib/providers.mjs';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
+
+// Code under test spawns the real `opencode` with process.env; keep its
+// state/data/cache/temp folders out of the developer's real ones.
+const toolState = redirectToolState('ak-provider-credentials');
+after(() => toolState.restore());
 
 // An env with NO provider credentials at all — the baseline every "absent" case
 // is measured against, so a key that happens to be exported on the developer's

From d1f0233b548d0eaef186f5e9d60cd2958f7bd59b Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:30:40 -0700
Subject: [PATCH 07/28] test(temp): remove every temporary folder a test
 creates

Adds tests/kit/helpers/temp-dir.mjs: tempDir(prefix, t?) makes a real-path
folder under os.tmpdir() and removes it when the test (or, without t, the
file or the calling test) ends, with maxRetries for Windows EBUSY.

A per-file probe (each tests/kit file alone with its own TMPDIR and XDG
bases) found 53 leaking files at this branch's head (the plan's table had 59;
the six OpenCode files were fixed by the previous two commits). 52 test files
plus tests/kit/helpers/codex-rollout.mjs change:
- inline fs.mkdtempSync(path.join(os.tmpdir(), ...)) sites become tempDir();
  conformance-tiers imports it as makeTempDir (its locals are named tempDir);
- every sandboxHome()/sandboxProject() folder without a removal gets
  after(() => rmrf(...));
- codex-plugins nests its root one level down: its traversal case resolves
  cache/../../outside-market, which landed in os.tmpdir() itself;
- statusline runs under redirectToolState('ak-sl'), so the rendered footer's
  30 s caches ruflo-daemon-count.json and ruvnet-brain-kb-size.json stop
  landing in the os.tmpdir() the developer's live footer reads.

After: the same probe over those files reports no leftovers and no failures.
---
 tests/kit/about-install-edits.test.mjs        |  5 ++--
 tests/kit/adapter-grants.test.mjs             |  6 ++--
 tests/kit/agentdb-retirement.test.mjs         |  4 ++-
 tests/kit/blocks-drift-parity.test.mjs        |  4 ++-
 tests/kit/brain-held-refresh.test.mjs         |  3 +-
 tests/kit/claude-window-ledger.test.mjs       |  4 +--
 tests/kit/codex-mcp-convergence.test.mjs      |  6 ++--
 tests/kit/codex-plugins.test.mjs              |  7 +++--
 tests/kit/codex-state.test.mjs                |  4 +--
 tests/kit/conformance-tiers.test.mjs          | 16 +++++------
 .../kit/dashboard-intel-integration.test.mjs  |  4 +--
 tests/kit/drift-freshness.test.mjs            |  4 ++-
 tests/kit/heal-natives.test.mjs               | 28 +++++++++----------
 tests/kit/helper-stamp.test.mjs               |  4 +--
 tests/kit/helpers/codex-rollout.mjs           |  4 +--
 tests/kit/helpers/temp-dir.mjs                | 21 ++++++++++++++
 tests/kit/host-adapters-cli.test.mjs          |  6 ++--
 tests/kit/host-alignment.test.mjs             |  7 +++--
 tests/kit/host-cli-migration.test.mjs         |  6 ++--
 tests/kit/hosts.test.mjs                      |  6 ++--
 tests/kit/intel-history.test.mjs              |  4 +--
 tests/kit/intelligence-watch.test.mjs         |  4 +--
 tests/kit/live-core.test.mjs                  | 24 ++++++++--------
 tests/kit/live-qe-contract.test.mjs           |  4 +--
 tests/kit/live-service.test.mjs               |  4 +--
 tests/kit/live-tailer.test.mjs                |  6 ++--
 tests/kit/live-transcript.test.mjs            |  4 +--
 tests/kit/maintenance-host-alignment.test.mjs |  6 ++--
 .../maintenance-management-activity.test.mjs  |  7 ++---
 tests/kit/nudge.test.mjs                      |  4 +--
 tests/kit/project-census.test.mjs             |  4 +--
 tests/kit/providers-drift-parity.test.mjs     |  4 ++-
 tests/kit/quota.test.mjs                      |  4 +--
 tests/kit/reverse-bridge.test.mjs             |  6 ++--
 .../routing-retirement-convergence.test.mjs   |  6 +++-
 .../kit/ruflo-components-convergence.test.mjs |  5 ++--
 tests/kit/ruvnet-brain.test.mjs               | 17 +++++------
 tests/kit/status-aqe-drift.test.mjs           | 14 ++++++++--
 tests/kit/status-golden.test.mjs              |  4 ++-
 tests/kit/status-repair-contract.test.mjs     |  4 ++-
 .../kit/statusline-config-dir-parity.test.mjs |  3 +-
 tests/kit/statusline.test.mjs                 | 13 +++++++--
 tests/kit/sync-host-repair.test.mjs           |  7 +++--
 tests/kit/sync-needs-your-action.test.mjs     |  4 ++-
 tests/kit/sync-self-freshness.test.mjs        |  5 ++--
 tests/kit/system-summary.test.mjs             |  6 ++--
 tests/kit/temp-dir-helper.test.mjs            | 16 +++++++++++
 tests/kit/usage-claude-dedup.test.mjs         |  4 +--
 tests/kit/usage-cli.test.mjs                  |  4 +--
 tests/kit/usage-codex-large-rollout.test.mjs  |  3 +-
 tests/kit/usage-deps-contract.test.mjs        |  4 +--
 tests/kit/usage-index-v6.test.mjs             |  4 +--
 tests/kit/usage-index.test.mjs                | 10 +++----
 tests/kit/usage-truncation.test.mjs           |  4 +--
 tests/kit/verify-memory-routes.test.mjs       |  9 ++++--
 55 files changed, 234 insertions(+), 146 deletions(-)
 create mode 100644 tests/kit/helpers/temp-dir.mjs
 create mode 100644 tests/kit/temp-dir-helper.test.mjs

diff --git a/tests/kit/about-install-edits.test.mjs b/tests/kit/about-install-edits.test.mjs
index f7b57a0f..25a76ed1 100644
--- a/tests/kit/about-install-edits.test.mjs
+++ b/tests/kit/about-install-edits.test.mjs
@@ -2,13 +2,14 @@
 // ruflo chip (audit 2026-09-26 Addendum 2, problem 3): the native SQLite pin
 // Ruflo itself intends (ruvnet/ruflo#2219). The chip stays the install fact;
 // the edit is a separate line and a separate JSON field.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { fakeGlobalRoot, sandboxHome } from './helpers/home-sandbox.mjs';
+import { fakeGlobalRoot, sandboxHome, rmrf } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-about-edits');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const about = await import('../../src/commands/about.mjs');
 
diff --git a/tests/kit/adapter-grants.test.mjs b/tests/kit/adapter-grants.test.mjs
index 85b7e92b..f17338f4 100644
--- a/tests/kit/adapter-grants.test.mjs
+++ b/tests/kit/adapter-grants.test.mjs
@@ -4,16 +4,16 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   CONFORMANCE_TIERS, TIER_GRANTS,
   recordTierResult, recordTierGate, recordTierFailure, grantCapability, revokeGrants, revokeCapability,
   grantsFor, grantedCapabilitiesFor, gatedTiersFor,
 } from '../../src/lib/adapters/grants.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 function tempFile() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-adapter-grants-'));
+  const dir = tempDir('ak-adapter-grants');
   return path.join(dir, 'adapter-grants.json');
 }
 
@@ -166,7 +166,7 @@ test("revokeGrants on prototype-chain names ('constructor', '__proto__', 'toStri
 });
 
 test('corrupt or missing file tolerance: grantsFor null, grantedCapabilitiesFor {}, gatedTiersFor []', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-adapter-grants-corrupt-'));
+  const dir = tempDir('ak-adapter-grants-corrupt');
   const missing = path.join(dir, 'does-not-exist.json');
   assert.equal(grantsFor('acme', { file: missing }), null);
   assert.deepEqual(grantedCapabilitiesFor('acme', HASH_A, { file: missing }), {});
diff --git a/tests/kit/agentdb-retirement.test.mjs b/tests/kit/agentdb-retirement.test.mjs
index 373c1b48..fe64405d 100644
--- a/tests/kit/agentdb-retirement.test.mjs
+++ b/tests/kit/agentdb-retirement.test.mjs
@@ -13,7 +13,7 @@
 //   · `ak x verify harvest` never seeds an AgentDB store and keeps every memory
 //     path inside its temporary directory;
 //   · About reports the agentdb copy Ruflo bundles, never the standalone global.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -24,6 +24,7 @@ import {
 } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-agentdb-retired');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const status = await import('../../src/commands/status.mjs');
 const heal = await import('../../src/lib/heal.mjs');
@@ -37,6 +38,7 @@ assertSandboxed(paths, HOME);
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-agentdb-retired');
+after(() => rmrf(PROJECT));
 
 /** A global root where the standalone agentdb (alpha.17) and Ruflo's bundled
  *  copy (alpha.20) disagree — the exact shape H-agentdb-lifecycle observed. */
diff --git a/tests/kit/blocks-drift-parity.test.mjs b/tests/kit/blocks-drift-parity.test.mjs
index 8ae842c0..28449c9a 100644
--- a/tests/kit/blocks-drift-parity.test.mjs
+++ b/tests/kit/blocks-drift-parity.test.mjs
@@ -7,7 +7,7 @@
 // back to PATH/dir/always probes and reported drift sync would never act on —
 // in both directions. Each scenario converges CLAUDE.md with sync's exact call,
 // then asks all three readers.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -17,6 +17,7 @@ import {
 } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-blocks-parity');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const { reconcileGuidance, upsertBlock, stripBlock, BEGIN } = await import('../../src/lib/blocks.mjs');
 const blocksSection = (await import('../../src/commands/status/sections/blocks.mjs')).default;
@@ -27,6 +28,7 @@ assertSandboxed(paths, HOME);
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-blocks-parity');
+after(() => rmrf(PROJECT));
 const SANDBOX_PATH = process.env.PATH;
 
 /** Fresh machine guidance + kit.json, then sync's exact (writing) reconcile. */
diff --git a/tests/kit/brain-held-refresh.test.mjs b/tests/kit/brain-held-refresh.test.mjs
index b03d3146..f2962b08 100644
--- a/tests/kit/brain-held-refresh.test.mjs
+++ b/tests/kit/brain-held-refresh.test.mjs
@@ -4,13 +4,14 @@
 // re-ran the refused refresh and failed again. A refused refresh is held as
 // blocked — visible, with its cause and the user's options, but not planned —
 // until the (installed, latest) release pair changes.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { sandboxHome, assertSandboxed, writeKitConfig, rmrf } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-brain-held');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const { installRuvnetBrain } = await import('../../src/lib/heal.mjs');
 const brain = await import('../../src/lib/ruvnet-brain.mjs');
diff --git a/tests/kit/claude-window-ledger.test.mjs b/tests/kit/claude-window-ledger.test.mjs
index 2008ed84..9e12bd85 100644
--- a/tests/kit/claude-window-ledger.test.mjs
+++ b/tests/kit/claude-window-ledger.test.mjs
@@ -1,17 +1,17 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   readClaudeWindowLog, statClaudeWindowLedger, windowAt, claudeWindowLedgerPath,
   WINDOW_LEAD_TOLERANCE_MS, MAX_LEDGER_BYTES,
 } from '../../src/lib/claude-window-ledger.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const SID = '0f8fad5b-d9cb-469f-a165-70867728950e';
 
 function configDirWith(sessionId, content) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-window-reader-'));
+  const dir = tempDir('ak-window-reader');
   const ledger = path.join(dir, 'claude-context-windows');
   fs.mkdirSync(ledger, { recursive: true });
   if (content !== undefined) {
diff --git a/tests/kit/codex-mcp-convergence.test.mjs b/tests/kit/codex-mcp-convergence.test.mjs
index c02be66b..1ed7ae32 100644
--- a/tests/kit/codex-mcp-convergence.test.mjs
+++ b/tests/kit/codex-mcp-convergence.test.mjs
@@ -1,14 +1,15 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import {
   sandboxHome, assertSandboxed, sandboxProject, writeKitConfig,
-  offlineKitConfig, fakeGlobalRoot, captureLog, snapshot, assertUnchanged,
+  offlineKitConfig, fakeGlobalRoot, captureLog, snapshot, assertUnchanged, rmrf,
 } from './helpers/home-sandbox.mjs';
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const sandbox = sandboxHome('ak-mcp-convergence');
+after(() => rmrf(sandbox));
 const paths = await import('../../src/lib/paths.mjs');
 assertSandboxed(paths, sandbox);
 isolateProject('ak-codex-mcp-convergence');
@@ -20,6 +21,7 @@ const { managedAgentBrowserEnv } = await import('../../src/lib/agent-browser.mjs
 const { ensureRufloMcpInCodex } = await import('../../src/lib/providers.mjs');
 const { reconcileCodexMcp } = await import('../../src/lib/codex-mcp-reconcile.mjs');
 const project = sandboxProject('ak-mcp-convergence');
+after(() => rmrf(project));
 const pkgRoot = path.resolve(import.meta.dirname, '../..');
 const canonical = '[mcp_servers.ruflo]\ncommand = "ak"\nargs = ["x", "ruflo-mcp"]\n';
 const legacy = '[mcp_servers.claude-flow]\ncommand = "ruflo"\nargs = ["mcp", "start"]\n';
diff --git a/tests/kit/codex-plugins.test.mjs b/tests/kit/codex-plugins.test.mjs
index ae383010..64f6d60c 100644
--- a/tests/kit/codex-plugins.test.mjs
+++ b/tests/kit/codex-plugins.test.mjs
@@ -5,7 +5,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { enabledPluginRefs, inspectCodexPlugins } from '../../src/lib/codex-plugins.mjs';
 
-const ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-codex-plugins-'));
+// One level below the temp folder: the traversal test resolves `cache/../../outside-market`,
+// which must land inside this test's own folder, never in os.tmpdir() itself.
+const ROOT = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-codex-plugins-')), 'codex');
+fs.mkdirSync(ROOT);
 const configFile = path.join(ROOT, 'config.toml');
 const cacheDir = path.join(ROOT, 'cache');
 
@@ -263,7 +266,7 @@ test('known Codex runtime-output incompatibilities are version-bounded advisorie
   assert.deepEqual(inspect().issues, [], 'a later release is not presumed broken');
 });
 
-test.after(() => fs.rmSync(ROOT, { recursive: true, force: true }));
+test.after(() => fs.rmSync(path.dirname(ROOT), { recursive: true, force: true }));
 
 test('Codex skill display names may contain capitals and differ from directory names', () => {
   fs.rmSync(cacheDir, { recursive: true, force: true });
diff --git a/tests/kit/codex-state.test.mjs b/tests/kit/codex-state.test.mjs
index b1e911f0..5411a67b 100644
--- a/tests/kit/codex-state.test.mjs
+++ b/tests/kit/codex-state.test.mjs
@@ -4,13 +4,13 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { codexStateDb, readCodexState } from '../../src/lib/codex-state.mjs';
 import { applyCodexLedger } from '../../src/lib/usage-index.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
-const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ak-codex-state-'));
+const tmp = () => tempDir('ak-codex-state');
 
 /** Build a fixture ledger shaped like the real state_5.sqlite (verified live
  *  2026-07-31: threads has id/thread_source/source/model/git_branch/tokens_used
diff --git a/tests/kit/conformance-tiers.test.mjs b/tests/kit/conformance-tiers.test.mjs
index 4d002f06..4f8b05a9 100644
--- a/tests/kit/conformance-tiers.test.mjs
+++ b/tests/kit/conformance-tiers.test.mjs
@@ -8,7 +8,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runTieredConformance, CONFORMANCE_TIERS } from '../../src/lib/adapters/conformance.mjs';
@@ -16,12 +15,13 @@ import {
   grantsFor, grantCapability, grantedCapabilitiesFor, recordTierResult,
 } from '../../src/lib/adapters/grants.mjs';
 import { lifecycleAdapterFor } from '../../src/lib/adapters/lifecycle-registry.mjs';
+import { tempDir as makeTempDir } from './helpers/temp-dir.mjs';
 
 const FIXTURE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../fixtures/adapters/acme');
 const VALID_MANIFEST_PATH = path.join(FIXTURE_ROOT, 'manifest.json');
 
 function tempGrantsFile() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-tiers-grants-'));
+  const dir = makeTempDir('ak-conformance-tiers-grants');
   return path.join(dir, 'adapter-grants.json');
 }
 
@@ -257,7 +257,7 @@ test('activity-routing tier is honestly skipped when the manifest declares neith
 
 test("activity-routing sends a bounded, directive probe prompt and runs the worker in a throwaway scratch cwd, never the caller's process.cwd()", async () => {
   const grantsFile = tempGrantsFile();
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-probe-'));
+  const tempDir = makeTempDir('ak-conformance-probe');
   const runHookSource = `
 import fs from 'node:fs';
 import path from 'node:path';
@@ -295,7 +295,7 @@ process.stdin.on('end', () => {
 
 test('an explicit timeoutMs option reaches the real worker: a hook that outlives it fails the tier as a genuine timeout, not a 120s wait', async () => {
   const grantsFile = tempGrantsFile();
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-timeout-override-'));
+  const tempDir = makeTempDir('ak-conformance-timeout-override');
   const runHookSource = "setTimeout(() => { process.stdout.write(JSON.stringify({ summary: 'too slow', provider: 'probe' })); }, 3000);\n";
   const manifestSource = writeProbeAdapter(tempDir, { runHookSource, hookTimeoutMs: 5000 });
 
@@ -314,7 +314,7 @@ test('an explicit timeoutMs option reaches the real worker: a hook that outlives
 
 test("with no explicit override, the outer runner honors the manifest's own declared execution.run.hook.timeoutMs instead of the runner's 120s default", async () => {
   const grantsFile = tempGrantsFile();
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-declared-timeout-'));
+  const tempDir = makeTempDir('ak-conformance-declared-timeout');
   const runHookSource = "setTimeout(() => { process.stdout.write(JSON.stringify({ summary: 'too slow', provider: 'probe' })); }, 3000);\n";
   const manifestSource = writeProbeAdapter(tempDir, { runHookSource, hookTimeoutMs: 300 });
 
@@ -352,7 +352,7 @@ test('aqe-provider is skipped when no candidate is declared, even though its act
 
 test('aqe-provider genuinely passes a non-injectable public-runtime stdin/stdout probe before its explicit grant', async () => {
   const grantsFile = tempGrantsFile();
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-aqe-provider-'));
+  const tempDir = makeTempDir('ak-conformance-aqe-provider');
   const manifestSource = writeProbeAdapter(tempDir, {
     runHookSource: 'process.stdin.resume(); process.stdin.on(\'end\', () => process.stdout.write(JSON.stringify({ summary: \'activity OK\', provider: \'probe\' })));\n',
     aqeHookSource: 'let input = \'\'; process.stdin.setEncoding(\'utf8\'); process.stdin.on(\'data\', (chunk) => { input += chunk; }); process.stdin.on(\'end\', () => { if (input !== \'Reply with exactly: OK\' || process.env.AK_AQE_PROVIDER !== \'probe\' || process.env.AK_AQE_MODEL !== \'probe-model\' || !process.env.AK_AQE_PROJECT_CWD) { process.stderr.write(\'bad AQE provider probe contract\'); process.exit(3); return; } process.stdout.write(\'OK\'); });\n',
@@ -386,7 +386,7 @@ test('aqe-provider genuinely passes a non-injectable public-runtime stdin/stdout
 
 test('aqe-provider fails honestly and records no pass when the real hook violates the stdout protocol', async () => {
   const grantsFile = tempGrantsFile();
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-aqe-provider-bad-output-'));
+  const tempDir = makeTempDir('ak-conformance-aqe-provider-bad-output');
   const manifestSource = writeProbeAdapter(tempDir, {
     runHookSource: 'process.stdin.resume(); process.stdin.on(\'end\', () => process.stdout.write(JSON.stringify({ summary: \'activity OK\', provider: \'probe\' })));\n',
     aqeHookSource: 'process.stdin.resume(); process.stdin.on(\'end\', () => process.stdout.write(\'WRONG\'));\n',
@@ -670,7 +670,7 @@ function flakyPrimaryEligibleManifest(flagPath) {
 
 test('N-1: a grant-bearing tier that RE-FAILS at the SAME hash voids the stored tier and the live capability, leaving an unrelated grant untouched', async () => {
   const grantsFile = tempGrantsFile();
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-conformance-tiers-refail-'));
+  const dir = makeTempDir('ak-conformance-tiers-refail');
   const flagPath = path.join(dir, 'fail-after-here');
   const manifestSource = 'mem://acme-flaky-primary-eligible';
   const readManifest = async () => flakyPrimaryEligibleManifest(flagPath);
diff --git a/tests/kit/dashboard-intel-integration.test.mjs b/tests/kit/dashboard-intel-integration.test.mjs
index de945824..525857f9 100644
--- a/tests/kit/dashboard-intel-integration.test.mjs
+++ b/tests/kit/dashboard-intel-integration.test.mjs
@@ -32,12 +32,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import http from 'node:http';
 import { startDashboard as realStartDashboard } from '../../src/lib/dashboard-server.mjs';
 import { readMachineWideIntel } from '../../src/lib/dashboard/intel-history.mjs';
 import { resolveProjectIdentity } from '../../src/lib/live/project-label.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const STUB_STATUS = { overall: 'ok', rows: [], drift: [] };
 
@@ -126,7 +126,7 @@ function fixtureProject(root, name, {
   return { path: dir, label: name, source: 'registry', learningScope: 'repository' };
 }
 
-const tempRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ak-dash-intel-'));
+const tempRoot = () => tempDir('ak-dash-intel');
 
 test('picker metadata survives the cached API catalog without changing selection or learning history', async (t) => {
   const root = tempRoot();
diff --git a/tests/kit/drift-freshness.test.mjs b/tests/kit/drift-freshness.test.mjs
index 2b6fde2a..4fb86807 100644
--- a/tests/kit/drift-freshness.test.mjs
+++ b/tests/kit/drift-freshness.test.mjs
@@ -2,7 +2,7 @@
 // upgrade, and a failed forced fetch must never clobber good cached data.
 // #135's solver contract lives in heal-natives.test.mjs; this file owns the
 // drift-report resilience contract and the sync plan-freshness contract.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -14,6 +14,7 @@ import {
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const HOME = sandboxHome('ak-drift-fresh');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const { driftReport, KIT_PKG } = await import('../../src/lib/versions.mjs');
 const sync = await import('../../src/commands/sync.mjs');
@@ -23,6 +24,7 @@ isolateProject('ak-drift-freshness');
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-drift-fresh');
+after(() => rmrf(PROJECT));
 const FLAGS = (over = {}) => ({ 'dry-run': false, 'no-upgrade': false, json: false, ...over });
 
 /** kit.json with an explicit versionCheck state; global root has ruflo+aqe fixtures. */
diff --git a/tests/kit/heal-natives.test.mjs b/tests/kit/heal-natives.test.mjs
index 06361a54..686579cf 100644
--- a/tests/kit/heal-natives.test.mjs
+++ b/tests/kit/heal-natives.test.mjs
@@ -11,13 +11,13 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   brainInstallFailure, ensureNativeBsq3, healAqeSolver, healNatives, installRuvnetBrain,
 } from '../../src/lib/heal.mjs';
 import { bsq3IsNative } from '../../src/lib/natives.mjs';
 import { _setGlobalRootForTest } from '../../src/lib/paths.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const BINDING = path.join('build', 'Release', 'better_sqlite3.node');
 
@@ -25,11 +25,11 @@ const BINDING = path.join('build', 'Release', 'better_sqlite3.node');
 // Brain: kbDir() honors RUVNET_BRAIN_KB at call time, so point it at an empty
 // directory for the whole file (a real KB has forge-update.mjs and SOURCE.json,
 // which would silently switch these tests onto the updater path).
-process.env.RUVNET_BRAIN_KB = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-brain-kb-'));
+process.env.RUVNET_BRAIN_KB = tempDir('ak-heal-brain-kb');
 // The natives heal receipts every manifest edit in ak's state folder
 // (install-edits.mjs), resolved at call time: keep this file's heals out of the
 // real one.
-process.env.XDG_STATE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-state-'));
+process.env.XDG_STATE_HOME = tempDir('ak-heal-state');
 process.env.LOCALAPPDATA = process.env.XDG_STATE_HOME;
 
 function writePkg(dir, { withBinding = false } = {}) {
@@ -47,7 +47,7 @@ function addBinding(pkgDir) {
 /** ruflo/node_modules/{agentdb, better-sqlite3} — better-sqlite3 hoisted and
  *  declared, but unbuilt: the state a `ruflo@latest` upgrade leaves behind. */
 function makeTree() {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-'));
+  const root = tempDir('ak-heal');
   const agentdb = path.join(root, 'node_modules', 'agentdb');
   const shared = path.join(root, 'node_modules', 'better-sqlite3');
   fs.mkdirSync(agentdb, { recursive: true });
@@ -109,7 +109,7 @@ test('heal builds the resolved copy in place, planting no extraneous copy', asyn
 });
 
 test('heal installs a copy only when better-sqlite3 is not resolvable at all', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-bare-'));
+  const root = tempDir('ak-heal-bare');
   const agentdb = path.join(root, 'node_modules', 'agentdb');
   fs.mkdirSync(agentdb, { recursive: true });
   const { runner, calls } = fakeNpm();
@@ -134,7 +134,7 @@ test('heal reports failure honestly when no rung produces a binding', async () =
 });
 
 test('heal reports failure when better-sqlite3 stays unresolvable', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-noop-'));
+  const root = tempDir('ak-heal-noop');
   const runner = async () => ({ code: 0, stdout: '', stderr: '' }); // install produces nothing
 
   const r = await ensureNativeBsq3(root, { runner });
@@ -145,7 +145,7 @@ test('heal reports failure when better-sqlite3 stays unresolvable', async () =>
 });
 
 test('heal reports the npm install error when the package stays unresolvable', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-install-fail-'));
+  const root = tempDir('ak-heal-install-fail');
   const runner = async () => ({ code: 1, stdout: '', stderr: 'npm error native build failed\n' });
 
   const r = await ensureNativeBsq3(root, { runner });
@@ -161,7 +161,7 @@ test('heal reports the npm install error when the package stays unresolvable', a
  *  `overrides` for it — the npm-12 state where a direct `@^12` install is
  *  EOVERRIDE-rejected but the declared `^12.9.0` succeeds. */
 function overrideDir(pin) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-override-'));
+  const dir = tempDir('ak-heal-override');
   fs.writeFileSync(path.join(dir, 'package.json'),
     JSON.stringify({ name: '@claude-flow/cli', overrides: { 'better-sqlite3': pin } }));
   return dir;
@@ -209,7 +209,7 @@ test('ensureNativeBsq3 reconciles a self-declared optionalDependencies pin befor
   // package's self-declared fields for the same dependency to agree, so the
   // stale optionalDependencies entry alone triggered EOVERRIDE even though the
   // derived install spec matched `overrides`.
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-selfconflict-'));
+  const dir = tempDir('ak-heal-selfconflict');
   fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
     name: '@claude-flow/cli',
     overrides: { 'better-sqlite3': '^12.10.0' },
@@ -249,7 +249,7 @@ test('ensureNativeBsq3 reconciles a self-declared optionalDependencies pin befor
 test('healNatives heals @claude-flow/memory + /cli with each tree\'s derived spec (AC-1)', async () => {
   // Fake global tree: ruflo/node_modules/@claude-flow/{memory,cli}, each pinning
   // better-sqlite3 via overrides, none resolvable — the npm-12 WASM-only state.
-  const g = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-global-'));
+  const g = tempDir('ak-heal-global');
   const nm = path.join(g, 'ruflo', 'node_modules');
   for (const c of ['memory', 'cli']) {
     const dir = path.join(nm, '@claude-flow', c);
@@ -272,7 +272,7 @@ test('healNatives heals @claude-flow/memory + /cli with each tree\'s derived spe
 });
 
 test('healNatives skips a ruflo tree with no @claude-flow packages, without crashing (EC-2)', async () => {
-  const g = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-bare-global-'));
+  const g = tempDir('ak-heal-bare-global');
   fs.mkdirSync(path.join(g, 'ruflo', 'node_modules'), { recursive: true });
   _setGlobalRootForTest(g);
   let installed = false;
@@ -292,7 +292,7 @@ test('healNatives skips a ruflo tree with no @claude-flow packages, without cras
  *  build/Release binding file is PRESENT — the state a Node major upgrade leaves:
  *  the file exists, so the old file-exists check called it native. */
 function presentBindingTree() {
-  const g = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-heal-unloadable-'));
+  const g = tempDir('ak-heal-unloadable');
   const cli = path.join(g, 'ruflo', 'node_modules', '@claude-flow', 'cli');
   fs.mkdirSync(cli, { recursive: true });
   fs.writeFileSync(path.join(cli, 'package.json'), JSON.stringify({ name: '@claude-flow/cli' }));
@@ -594,7 +594,7 @@ test('brain failures drop ANSI color and keep the installer remediation hint', (
 });
 
 test('AQE solver: the unpublished native is never install-attempted and the TS fallback is reported as the implementation (#135)', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-solver-'));
+  const root = tempDir('ak-solver');
   fs.mkdirSync(path.join(root, 'agentic-qe'), { recursive: true });
   _setGlobalRootForTest(root);
   try {
@@ -615,7 +615,7 @@ test('AQE solver: the unpublished native is never install-attempted and the TS f
 });
 
 test('AQE solver: a native already present on disk is still detected and reported', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-solver-present-'));
+  const root = tempDir('ak-solver-present');
   const probe = path.join(root, 'agentic-qe', 'node_modules', '@ruvector', 'solver-node');
   fs.mkdirSync(probe, { recursive: true });
   fs.writeFileSync(path.join(probe, 'package.json'), '{"name":"@ruvector/solver-node"}');
diff --git a/tests/kit/helper-stamp.test.mjs b/tests/kit/helper-stamp.test.mjs
index a5050d14..f12d6326 100644
--- a/tests/kit/helper-stamp.test.mjs
+++ b/tests/kit/helper-stamp.test.mjs
@@ -20,10 +20,10 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { _setGlobalRootForTest } from '../../src/lib/paths.mjs';
 import { helperStampStale, refreshRufloHelpers, runHelperRefresh, fixStatusline } from '../../src/lib/statusline.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // Minimal host: just the shapes fixStatusline keys off, runnable post-injection.
 const HOST = `#!/usr/bin/env node
@@ -82,7 +82,7 @@ const REFRESH_BODIES = { faithful: FAKE_REFRESH, throws: THROWING_REFRESH, hangs
   blocked: BLOCKED_REFRESH, noop: NOOP_REFRESH, global: GLOBAL_REFRESH };
 
 function fixture({ cliVersion = '3.32.7', stamp, refreshModule } = {}) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-stamp-'));
+  const dir = tempDir('ak-stamp');
   const proj = path.join(dir, 'proj');
   const helpers = path.join(proj, '.claude', 'helpers');
   fs.mkdirSync(helpers, { recursive: true });
diff --git a/tests/kit/helpers/codex-rollout.mjs b/tests/kit/helpers/codex-rollout.mjs
index 831735c5..ff357ff2 100644
--- a/tests/kit/helpers/codex-rollout.mjs
+++ b/tests/kit/helpers/codex-rollout.mjs
@@ -3,8 +3,8 @@
 // `turn_context`, cumulative `token_count`, `external-import-turn-N` ids).
 // Pure string builders: nothing here touches ~/.codex, ~/.claude or ~/.config.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { tempDir } from './temp-dir.mjs';
 
 /** A cumulative usage snapshot, `gross` input INCLUDING `cached`. */
 export function usage({ input = 0, cached = 0, output = 0, reasoning = 0 } = {}) {
@@ -127,7 +127,7 @@ export function forkedSubagent({ id = 'child', parent, own, start, meta = {} })
 
 /** A temp sandbox with claude/ and codex/YYYY/MM/DD rollout dirs. */
 export function codexSandbox(files, { day = ['2026', '07', '24'] } = {}) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-codex-attr-'));
+  const dir = tempDir('ak-codex-attr'); // removed when the calling test (or file) ends
   const dayDir = path.join(dir, 'codex', ...day);
   fs.mkdirSync(dayDir, { recursive: true });
   fs.mkdirSync(path.join(dir, 'claude'), { recursive: true });
diff --git a/tests/kit/helpers/temp-dir.mjs b/tests/kit/helpers/temp-dir.mjs
new file mode 100644
index 00000000..817b4a67
--- /dev/null
+++ b/tests/kit/helpers/temp-dir.mjs
@@ -0,0 +1,21 @@
+// tests/kit/helpers/temp-dir.mjs
+// A temp folder that removes itself. 59 test files left 700+ folders behind per
+// run (Branch 2 probe); this is the one way to make one.
+import { after } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Create `<os.tmpdir()>/<prefix>-XXXXXX` and remove it when the test (or, without
+ * `t`, the file) finishes. A caller that chdir-ed into it must chdir out first.
+ * @param {string} prefix
+ * @param {import('node:test').TestContext} [t]
+ * @returns {string} the real path of the new folder
+ */
+export function tempDir(prefix, t) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`)));
+  const remove = () => fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  if (t) t.after(remove); else after(remove);
+  return dir;
+}
diff --git a/tests/kit/host-adapters-cli.test.mjs b/tests/kit/host-adapters-cli.test.mjs
index 41379252..8dbed253 100644
--- a/tests/kit/host-adapters-cli.test.mjs
+++ b/tests/kit/host-adapters-cli.test.mjs
@@ -18,7 +18,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { run } from '../../src/commands/x/host-adapters.mjs';
@@ -32,6 +31,7 @@ import {
   grantsFor, recordTierResult, recordTierGate, grantCapability, grantedCapabilitiesFor,
 } from '../../src/lib/adapters/grants.mjs';
 import { runTieredConformance } from '../../src/lib/adapters/conformance.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const ON_ENV = { AK_EXPERIMENTAL_HOST_ADAPTERS: '1' };
 const OFF_ENV = {};
@@ -74,7 +74,7 @@ function validManifest(overrides = {}) {
 }
 
 function tmpConsentFile() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-adapter-consent-'));
+  const dir = tempDir('ak-adapter-consent');
   return path.join(dir, 'adapter-consent.json');
 }
 
@@ -751,7 +751,7 @@ async function acmeReader(source) {
 }
 
 function tmpGrantsFile() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-adapter-conformance-cli-'));
+  const dir = tempDir('ak-adapter-conformance-cli');
   return path.join(dir, 'adapter-grants.json');
 }
 
diff --git a/tests/kit/host-alignment.test.mjs b/tests/kit/host-alignment.test.mjs
index 4c336dad..56ff7c77 100644
--- a/tests/kit/host-alignment.test.mjs
+++ b/tests/kit/host-alignment.test.mjs
@@ -1,12 +1,15 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { sandboxHome, sandboxProject, snapshot, assertUnchanged, captureLog } from './helpers/home-sandbox.mjs';
+import { sandboxHome, sandboxProject, snapshot, assertUnchanged, captureLog, rmrf } from './helpers/home-sandbox.mjs';
 
 const sandbox = sandboxHome('ak-host-alignment');
+after(() => rmrf(sandbox));
 const project = sandboxProject('ak-host-alignment');
+after(() => rmrf(project));
 const other = sandboxProject('ak-host-alignment-other');
+after(() => rmrf(other));
 const { run } = await import('../../src/commands/run.mjs');
 const legacy = { command: 'codex', args: ['mcp-server'] };
 const modern = { type: 'http', url: 'https://example.com/mcp' };
diff --git a/tests/kit/host-cli-migration.test.mjs b/tests/kit/host-cli-migration.test.mjs
index 3209999d..f13337b4 100644
--- a/tests/kit/host-cli-migration.test.mjs
+++ b/tests/kit/host-cli-migration.test.mjs
@@ -3,15 +3,15 @@ import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
 
 function sandbox() {
-  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-host-cli-'));
-  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-host-project-'));
+  const home = tempDir('ak-host-cli');
+  const project = tempDir('ak-host-project');
   fs.mkdirSync(path.join(project, '.git'));
   const config = path.join(home, '.config');
   return {
diff --git a/tests/kit/hosts.test.mjs b/tests/kit/hosts.test.mjs
index e4d0e2a4..36f61b70 100644
--- a/tests/kit/hosts.test.mjs
+++ b/tests/kit/hosts.test.mjs
@@ -1,12 +1,10 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { HOST_IDS, adapterFor, drivingHost, hostTierLabel, hostAsymmetryNote } from '../../src/lib/hosts.mjs';
 import { hostAuthState } from '../../src/lib/providers.mjs';
 import { managedHostIds } from '../../src/lib/adapters/registries.mjs';
 import { applyAdmitted, resetAdmitted, effectivePrimaryHostIds } from '../../src/lib/adapters/admitted.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // ── HOST_ADAPTERS descriptors ────────────────────────────────────────────────
 // HOST_IDS is HOST_ADAPTERS' key order (hosts.mjs filters HOST_REGISTRY by
@@ -151,7 +149,7 @@ test('hostAuthState reports none for an absent claude with no key', () => {
   // home must point at an EMPTY dir: on a real machine with file-based claude
   // credentials (~/.claude/.credentials.json present, e.g. Linux installs), the
   // login-file probe legitimately wins and this test flaked 'oauth'.
-  const a = hostAuthState('claude', { env: {}, present: false, home: fs.mkdtempSync(path.join(os.tmpdir(), 'ak-nohome-')) });
+  const a = hostAuthState('claude', { env: {}, present: false, home: tempDir('ak-nohome') });
   assert.equal(a.mode, 'none');
 });
 
diff --git a/tests/kit/intel-history.test.mjs b/tests/kit/intel-history.test.mjs
index 0f9e3e97..4a7bc844 100644
--- a/tests/kit/intel-history.test.mjs
+++ b/tests/kit/intel-history.test.mjs
@@ -6,7 +6,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   readNeuralPatternStoreHistory,
@@ -17,8 +16,9 @@ import {
   readIntelHistory,
   readMachineWideIntel,
 } from '../../src/lib/dashboard/intel-history.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
-const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ak-intel-history-'));
+const tmp = () => tempDir('ak-intel-history');
 
 /** Write `content` (object → JSON.stringify'd, string → written verbatim so
  *  malformed-JSON fixtures are easy to express) at cwd-relative `relPath`,
diff --git a/tests/kit/intelligence-watch.test.mjs b/tests/kit/intelligence-watch.test.mjs
index e07cbe0e..dc082c55 100644
--- a/tests/kit/intelligence-watch.test.mjs
+++ b/tests/kit/intelligence-watch.test.mjs
@@ -1,11 +1,11 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { IntelligenceWatch } from '../../src/lib/live/intelligence-watch.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
-const sandbox = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ak-intel-watch-'));
+const sandbox = () => tempDir('ak-intel-watch');
 
 /** A controllable fake clock: `now()` returns the current fake ms, `advance`
  *  moves it forward without any real wall-clock wait. */
diff --git a/tests/kit/live-core.test.mjs b/tests/kit/live-core.test.mjs
index d18c019a..df85ecb7 100644
--- a/tests/kit/live-core.test.mjs
+++ b/tests/kit/live-core.test.mjs
@@ -2,7 +2,6 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   createLiveEvent, LiveReplayStream, emptyLiveProjection,
@@ -10,6 +9,7 @@ import {
   reduceLiveEvent, resolveHost, resolveProjectIdentity, resolveProjectLabel,
   serializeLiveProjection, sweepLiveProjection, stableProjectKey, WorkspaceSnapshotStore,
 } from '../../src/lib/live/index.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const base = (over = {}) => ({
   sessionId: 's1', observedAt: '2026-07-27T12:00:00Z',
@@ -146,7 +146,7 @@ test('Git workspace inspection reports tracked state without filenames or attrib
   assert.deepEqual(parseGitNumstat('4\t2\tsrc/private.mjs\n-\t-\tasset.bin\n'), {
     additions: 4, deletions: 2, files: 2, binaryFiles: 1,
   });
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-workspace-'));
+  const root = tempDir('ak-live-workspace');
   fs.mkdirSync(path.join(root, 'backend'), { recursive: true });
   // Exercise the real Git boundary in a disposable repository.
   execFileSync('git', ['init', '-q', '-b', 'feature/workspace', root]);
@@ -175,7 +175,7 @@ test('Git workspace inspection reports tracked state without filenames or attrib
 });
 
 test('workspace snapshot store retains only safe last-recorded metadata', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-store-'));
+  const dir = tempDir('ak-live-store');
   const file = path.join(dir, 'observability-workspaces.json');
   const store = new WorkspaceSnapshotStore(file);
   assert.equal(store.remember({
@@ -199,7 +199,7 @@ test('workspace snapshot store retains only safe last-recorded metadata', () =>
 });
 
 test('workspace store re-sanitizes records and does not expose mutable internals', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-store-mutation-'));
+  const dir = tempDir('ak-live-store-mutation');
   const file = path.join(dir, 'observability-workspaces.json');
   const store = new WorkspaceSnapshotStore(file);
   const baseRecord = {
@@ -223,7 +223,7 @@ test('workspace store re-sanitizes records and does not expose mutable internals
 });
 
 test('Git workspace inspection ignores inherited repository-routing variables', async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-git-env-'));
+  const root = tempDir('ak-live-git-env');
   const expected = path.join(root, 'expected');
   const redirected = path.join(root, 'redirected');
   for (const repository of [expected, redirected]) {
@@ -245,7 +245,7 @@ test('Git workspace inspection ignores inherited repository-routing variables',
 });
 
 test('project identity resolves linked and retained worktrees to their owning repository', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-project-'));
+  const root = tempDir('ak-live-project');
   const repository = path.join(root, 'agentic-kit');
   const worktree = path.join(root, 'm3-multi-provider-persona-grounding');
   fs.mkdirSync(worktree, { recursive: true });
@@ -260,7 +260,7 @@ test('project identity resolves linked and retained worktrees to their owning re
 });
 
 test('project identity resolves repository subdirectories to the repository root', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-project-'));
+  const root = tempDir('ak-live-project');
   const repository = path.join(root, 'tub-vault');
   fs.mkdirSync(path.join(repository, '.git'), { recursive: true });
   fs.mkdirSync(path.join(repository, 'scripts', 'lib'), { recursive: true });
@@ -271,8 +271,8 @@ test('project identity resolves repository subdirectories to the repository root
 });
 
 test('canonical project keys distinguish unrelated same-named repositories', () => {
-  const left = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-left-'));
-  const right = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-right-'));
+  const left = tempDir('ak-live-left');
+  const right = tempDir('ak-live-right');
   const leftRepo = path.join(left, 'api');
   const rightRepo = path.join(right, 'api');
   fs.mkdirSync(path.join(leftRepo, '.git'), { recursive: true });
@@ -285,7 +285,7 @@ test('canonical project keys distinguish unrelated same-named repositories', ()
 });
 
 test('project identity prefers a real nested repository over worktree path heuristics', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-project-'));
+  const root = tempDir('ak-live-project');
   const outer = path.join(root, 'outer');
   const nested = path.join(outer, '.claude', 'worktrees', 'nested');
   fs.mkdirSync(path.join(outer, '.git'), { recursive: true });
@@ -296,7 +296,7 @@ test('project identity prefers a real nested repository over worktree path heuri
 });
 
 test('project identity distinguishes unresolved paths and a repository literally named unknown', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-project-'));
+  const root = tempDir('ak-live-project');
   const repository = path.join(root, 'unknown');
   fs.mkdirSync(path.join(repository, '.git'), { recursive: true });
   assert.deepEqual(resolveProjectIdentity(path.join(root, 'scratch')).canonical, false);
@@ -306,7 +306,7 @@ test('project identity distinguishes unresolved paths and a repository literally
 });
 
 test('project identity resolves subdirectories of a linked worktree to the owning repository', () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-project-'));
+  const root = tempDir('ak-live-project');
   const repository = path.join(root, 'agentic-kit');
   const worktree = path.join(root, 'm3-persona-grounding');
   fs.mkdirSync(path.join(worktree, 'scripts'), { recursive: true });
diff --git a/tests/kit/live-qe-contract.test.mjs b/tests/kit/live-qe-contract.test.mjs
index 87ad21ce..8a34fba4 100644
--- a/tests/kit/live-qe-contract.test.mjs
+++ b/tests/kit/live-qe-contract.test.mjs
@@ -1,13 +1,13 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   createLiveEvent, JsonlTailer, emptyLiveProjection, reduceLiveEvent,
 } from '../../src/lib/live/index.mjs';
 import { LIVE_CSS, LIVE_HTML, LIVE_JS } from '../../src/lib/dashboard/live-view.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const observedAt = '2026-07-27T12:00:00Z';
 const PAGE_HTML = renderPage({ name: 'agentic-kit', version: 'test' });
@@ -37,7 +37,7 @@ test('canonical event serialization is a closed allowlist under arbitrary extra
 });
 
 test('JSONL tailing preserves a UTF-8 record split across byte-level appends', () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-utf8-'));
+  const dir = tempDir('ak-live-utf8');
   const file = path.join(dir, 'events.jsonl');
   const bytes = Buffer.from(`${JSON.stringify({ label: 'agent 🐝' })}\n`);
   const split = bytes.indexOf(Buffer.from('🐝')) + 2;
diff --git a/tests/kit/live-service.test.mjs b/tests/kit/live-service.test.mjs
index d16248fb..b5cb6528 100644
--- a/tests/kit/live-service.test.mjs
+++ b/tests/kit/live-service.test.mjs
@@ -1,12 +1,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { LiveSessionsService, stableProjectKey } from '../../src/lib/live/index.mjs';
 import { waitUntil } from './helpers/wait-until.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 const sandbox = () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-service-'));
+  const dir = tempDir('ak-live-service');
   const claude = path.join(dir, 'claude', 'project');
   const codex = path.join(dir, 'codex', '2026', '07', '27');
   fs.mkdirSync(claude, { recursive: true });
diff --git a/tests/kit/live-tailer.test.mjs b/tests/kit/live-tailer.test.mjs
index 8ef9b27d..e858ce5b 100644
--- a/tests/kit/live-tailer.test.mjs
+++ b/tests/kit/live-tailer.test.mjs
@@ -1,12 +1,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { JsonlTailer } from '../../src/lib/live/index.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const tempFile = () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-'));
+  const dir = tempDir('ak-live');
   return path.join(dir, 'events.jsonl');
 };
 
@@ -147,7 +147,7 @@ test('an unreadable file is reported once, even when it has no new bytes', { ski
 });
 
 test('a path that is not a regular file is unreadable, never opened', (t) => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-'));
+  const dir = tempDir('ak-live');
   t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
   const errors = [];
   const tailer = new JsonlTailer(dir, { onRecord: () => {}, onError: (error) => errors.push(error.code) });
diff --git a/tests/kit/live-transcript.test.mjs b/tests/kit/live-transcript.test.mjs
index 450d0552..8f475c08 100644
--- a/tests/kit/live-transcript.test.mjs
+++ b/tests/kit/live-transcript.test.mjs
@@ -1,7 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   adaptClaudeTranscriptRecord,
@@ -9,10 +8,11 @@ import {
   TranscriptStreams,
 } from '../../src/lib/live/index.mjs';
 import { waitUntil } from './helpers/wait-until.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const line = (value) => `${JSON.stringify(value)}\n`;
 const sandbox = () => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-transcript-'));
+  const dir = tempDir('ak-transcript');
   const claude = path.join(dir, 'claude', 'project');
   const codex = path.join(dir, 'codex', '2026', '07', '27');
   fs.mkdirSync(claude, { recursive: true });
diff --git a/tests/kit/maintenance-host-alignment.test.mjs b/tests/kit/maintenance-host-alignment.test.mjs
index c94cdab3..cbd333fc 100644
--- a/tests/kit/maintenance-host-alignment.test.mjs
+++ b/tests/kit/maintenance-host-alignment.test.mjs
@@ -1,10 +1,12 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { sandboxHome, sandboxProject } from './helpers/home-sandbox.mjs';
+import { sandboxHome, sandboxProject, rmrf } from './helpers/home-sandbox.mjs';
 const sandbox = sandboxHome('ak-maintenance-alignment');
+after(() => rmrf(sandbox));
 const project = sandboxProject('ak-maintenance-alignment');
+after(() => rmrf(project));
 const { buildManagementInventory } = await import('../../src/lib/maintenance/management/projection.mjs');
 const { runInventoryQuery } = await import('../../src/lib/maintenance/management/query.mjs');
 const KEY = 'host-alignment-ui-test-key';
diff --git a/tests/kit/maintenance-management-activity.test.mjs b/tests/kit/maintenance-management-activity.test.mjs
index 8967203b..b24aa4c4 100644
--- a/tests/kit/maintenance-management-activity.test.mjs
+++ b/tests/kit/maintenance-management-activity.test.mjs
@@ -3,17 +3,16 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 
 import { isProhibitedLabel } from '../../src/lib/maintenance/management/model.mjs';
 import { buildActivity, exportReceipt, receiptDetail } from '../../src/lib/maintenance/management/activity.mjs';
 import { createDispositionStore } from '../../src/lib/maintenance/management/dispositions.mjs';
 import { createPreferencesStore, resolveViewState } from '../../src/lib/maintenance/management/preferences.mjs';
 import { INTERRUPTED_RECEIPT, FIXTURE_NOW } from '../fixtures/maintenance/management-fixtures.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 function tempRoot(t) {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-mgmt-activity-'));
+  const root = tempDir('ak-mgmt-activity');
   t.after(() => fs.rmSync(root, { recursive: true, force: true }));
   return root;
 }
@@ -147,7 +146,7 @@ test('recordDisposition returns the confirmation explanation and persists the re
 });
 
 test('snoozed requires a future ISO `until`; other kinds reject an `until`', () => {
-  const store = createDispositionStore({ root: fs.mkdtempSync(path.join(os.tmpdir(), 'ak-disp-')), now: () => new Date(FIXTURE_NOW) });
+  const store = createDispositionStore({ root: tempDir('ak-disp'), now: () => new Date(FIXTURE_NOW) });
   assert.throws(() => store.recordDisposition({ guidanceId: 'g', dispositionIdentity: 'p:x', kind: 'snoozed' }), TypeError);
   assert.throws(() => store.recordDisposition({ guidanceId: 'g', dispositionIdentity: 'p:x', kind: 'acknowledged', until: FIXTURE_NOW }), TypeError);
   assert.throws(() => store.recordDisposition({ guidanceId: 'g', dispositionIdentity: 'p:x', kind: 'not-a-kind' }), TypeError);
diff --git a/tests/kit/nudge.test.mjs b/tests/kit/nudge.test.mjs
index a1f9e08f..83251739 100644
--- a/tests/kit/nudge.test.mjs
+++ b/tests/kit/nudge.test.mjs
@@ -1,10 +1,10 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { localDrift } from '../../src/lib/nudge.mjs';
 import { upsertBlock } from '../../src/lib/blocks.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // Fixtures inject everything machine-specific: a fake pkgRoot (so built-in
 // templates resolve to nothing → 'missing-template', never drift), an explicit
@@ -12,7 +12,7 @@ import { upsertBlock } from '../../src/lib/blocks.mjs';
 // statusline → that probe stays quiet), and explicit guidance targets. What
 // remains under test is exactly the blocks-drift phrasing the bin nudge prints.
 
-const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'nudge-test-'));
+const tmp = () => tempDir('nudge-test');
 const block = (slug, body) => `<!-- BEGIN ${slug} -->\n${body}\n<!-- END ${slug} -->\n`;
 
 function fixture() {
diff --git a/tests/kit/project-census.test.mjs b/tests/kit/project-census.test.mjs
index 03ba41d1..abab75e9 100644
--- a/tests/kit/project-census.test.mjs
+++ b/tests/kit/project-census.test.mjs
@@ -15,16 +15,16 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import {
   projectCensus, projectsInScope, describeScope,
   hasLearningState, learningStateOf, LEARNING_MARKERS, CENSUS_SCOPES,
 } from '../../src/lib/project-census.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 /** A temp tree; every test builds its own so none can observe another. */
 function tmp() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'ak-census-'));
+  return tempDir('ak-census');
 }
 
 /** A directory that looks like a git repo root to resolveProjectIdentity. */
diff --git a/tests/kit/providers-drift-parity.test.mjs b/tests/kit/providers-drift-parity.test.mjs
index de09f8fb..beb67172 100644
--- a/tests/kit/providers-drift-parity.test.mjs
+++ b/tests/kit/providers-drift-parity.test.mjs
@@ -9,7 +9,7 @@
 // and comparing them directly, for a fixture with INDUCED drift — so a
 // future edit that reintroduces a second, independently-derived comparison
 // fails here immediately rather than shipping a silent divergence.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -60,6 +60,7 @@ const providerDriftRow = (rows) => rows
 
 test('#129 parity: an induced chain-order edit is reported as drift, identically, on both paths', async () => {
   const project = sandboxProject('ak-drift-parity-induced');
+  after(() => rmrf(project));
   seedHome(CHAIN_CFG());
   const cfg = loadKitConfig();
   applyAqeRouter(cfg, project); // converge once, exactly what `ak sync` runs
@@ -93,6 +94,7 @@ test('#129 parity: an induced chain-order edit is reported as drift, identically
 
 test('#129 parity: a freshly converged chain is reported as clean, identically, on both paths', async () => {
   const project = sandboxProject('ak-drift-parity-clean');
+  after(() => rmrf(project));
   seedHome(CHAIN_CFG());
   const cfg = loadKitConfig();
   applyAqeRouter(cfg, project);
diff --git a/tests/kit/quota.test.mjs b/tests/kit/quota.test.mjs
index b7a4ef38..75b13565 100644
--- a/tests/kit/quota.test.mjs
+++ b/tests/kit/quota.test.mjs
@@ -4,7 +4,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { EventEmitter } from 'node:events';
 import {
@@ -13,8 +12,9 @@ import {
   classifyClaudeTeeChannel, CLAUDE_TEE_CHANNELS,
   collectCodexLimitsDetailed, CODEX_UNAVAILABLE_REASONS,
 } from '../../src/lib/quota.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
-const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'ak-quota-'));
+const tmp = () => tempDir('ak-quota');
 
 // ── windowLabel — duration-derived, never slot-derived ───────────────────────
 
diff --git a/tests/kit/reverse-bridge.test.mjs b/tests/kit/reverse-bridge.test.mjs
index 2e3c962f..6c14df9a 100644
--- a/tests/kit/reverse-bridge.test.mjs
+++ b/tests/kit/reverse-bridge.test.mjs
@@ -1,13 +1,13 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { rufloCodexMcpStatus, codexMcpTopology } from '../../src/lib/mcp.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 /** Build a temp $HOME containing (or not) ~/.codex/config.toml with given body. */
 function tempHome(configBody) {
-  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-rev-'));
+  const home = tempDir('ak-rev');
   if (configBody != null) {
     fs.mkdirSync(path.join(home, '.codex'), { recursive: true });
     fs.writeFileSync(path.join(home, '.codex', 'config.toml'), configBody);
@@ -64,7 +64,7 @@ test('rufloCodexMcpStatus reads the multi-line args array codex writes', () => {
 
 test('codexMcpTopology reads multi-line args and still classifies exact repair tables', () => {
   const home = tempHome('[mcp_servers.claude-flow]\ncommand = "ruflo"\nargs = [\n    "mcp",\n    "start",\n]\n\n[mcp_servers.codex]\ncommand = "codex"\nargs = [\n    "mcp-server",\n]\n');
-  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-rev-cwd-'));
+  const cwd = tempDir('ak-rev-cwd');
   const topology = codexMcpTopology({ cwd, home });
   const byName = Object.fromEntries(topology.registrations.map((entry) => [entry.name, entry]));
   assert.deepEqual(byName['claude-flow'].args, ['mcp', 'start']);
diff --git a/tests/kit/routing-retirement-convergence.test.mjs b/tests/kit/routing-retirement-convergence.test.mjs
index 45be2626..950d3859 100644
--- a/tests/kit/routing-retirement-convergence.test.mjs
+++ b/tests/kit/routing-retirement-convergence.test.mjs
@@ -17,7 +17,7 @@
 // In-process against the sandboxed HOME (see helpers/home-sandbox.mjs) —
 // `pick()` must NEVER touch the real HOME (the historic #137 trap: a spawned
 // pick() with an undefined cwd wrote into the real repository).
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -27,6 +27,7 @@ import {
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const HOME = sandboxHome('ak-routing-retirement');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const host = await import('../../src/commands/x/host.mjs');
 const setup = await import('../../src/commands/setup.mjs');
@@ -106,6 +107,7 @@ function seedKitConfig(cfg) {
 
 test('ak host pick heals a retired seeded route instead of leaving it for the next sync', async () => {
   const project = sandboxProject('ak-pick-retirement');
+  after(() => rmrf(project));
   seedKitConfig(baseCfg({ testing: { host: 'claude', model: 'retired-model-x', provenance: 'seeded' } }));
   const { migrate, calls } = fakeMigrateThatRetires('testing', 'retired-model-x', 'replacement-model');
 
@@ -124,6 +126,7 @@ test('ak host pick heals a retired seeded route instead of leaving it for the ne
 
 test('ak host pick reports (but never rewrites) a user pin on a retired model', async () => {
   const project = sandboxProject('ak-pick-retirement-user-pin');
+  after(() => rmrf(project));
   seedKitConfig(baseCfg({ testing: { host: 'claude', model: 'retired-model-x', provenance: 'user' } }));
   const calls = [];
   const migrate = (cfg) => {
@@ -160,6 +163,7 @@ const withProjectCli = (fn) => withFakePath(['ruflo', 'claude'], fn);
 
 test('ak setup --project heals a retired seeded route instead of leaving it for the next sync', async () => {
   const project = sandboxProject('ak-setup-retirement');
+  after(() => rmrf(project));
   const cwd = process.cwd();
   process.chdir(project);
   const { migrate, calls } = fakeMigrateThatRetires('testing', 'retired-model-x', 'replacement-model');
diff --git a/tests/kit/ruflo-components-convergence.test.mjs b/tests/kit/ruflo-components-convergence.test.mjs
index 78e01765..cfeb3f34 100644
--- a/tests/kit/ruflo-components-convergence.test.mjs
+++ b/tests/kit/ruflo-components-convergence.test.mjs
@@ -3,13 +3,14 @@
 // driven through the same read-only path `ak status` and the dashboard use:
 // rufloComponentRows(rufloComponentsPayload(...)). Every path is injected into a
 // throwaway directory; the home sandbox guards anything that falls back to paths.mjs.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { sandboxHome, assertSandboxed } from './helpers/home-sandbox.mjs';
+import { sandboxHome, assertSandboxed, rmrf } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-rc-convergence');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const { rufloComponentsPayload } = await import('../../src/lib/ruflo-components/snapshot.mjs');
 const { rufloComponentRows } = await import('../../src/commands/status/sections/ruflo-components.mjs');
diff --git a/tests/kit/ruvnet-brain.test.mjs b/tests/kit/ruvnet-brain.test.mjs
index 68019724..1849cf35 100644
--- a/tests/kit/ruvnet-brain.test.mjs
+++ b/tests/kit/ruvnet-brain.test.mjs
@@ -11,6 +11,7 @@ import {
 import { brainReleaseRow } from '../../src/commands/status/sections/ruvnet-brain.mjs';
 import { BUILTIN_BLOCKS, detect } from '../../src/lib/blocks.mjs';
 import { loadKitConfig, saveKitConfig } from '../../src/lib/config.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const withEnv = (key, value, fn) => {
   const prev = process.env[key];
@@ -83,7 +84,7 @@ test('an announced release without a bundle stays visible but is not an ak sync
 
 test('installedReleaseOnDisk reads SOURCE.json releaseTag — validated, v-stripped, null-safe', () => {
   const writeSource = (body) => {
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-src-'));
+    const tmp = tempDir('rb-src');
     if (body !== null) fs.writeFileSync(path.join(tmp, 'SOURCE.json'), body);
     return tmp;
   };
@@ -114,7 +115,7 @@ test('nightly self-updater detection: label/plist fixed, present() is darwin-gat
 });
 
 test('present() is true when the KB entrypoint exists (forge-mcp-all.mjs)', () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-kb-'));
+  const tmp = tempDir('rb-kb');
   fs.writeFileSync(path.join(tmp, 'forge-mcp-all.mjs'), '// stub');
   withEnv('RUVNET_BRAIN_KB', tmp, () => {
     assert.equal(present(), true);
@@ -177,7 +178,7 @@ test('BUILTIN_BLOCKS prefers managed Brain intent and keeps the KB probe as fall
     flags: { claudeEnabled: true, ruvnetBrainEnabled: false },
   }), false, 'persisted opt-out wins over filesystem presence');
   // dir detector: true when the target exists, false when absent
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-det-'));
+  const tmp = tempDir('rb-det');
   assert.equal(await detect({ type: 'dir', target: tmp }), true);
   assert.equal(await detect({ type: 'dir', target: path.join(tmp, 'nope') }), false);
   fs.rmSync(tmp, { recursive: true, force: true });
@@ -192,7 +193,7 @@ test('the ruvnet-brain-reference template ships and is self-sentineled', () => {
 });
 
 test('kit config: ruvnetBrain defaults true and round-trips a false override', () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-cfg-'));
+  const tmp = tempDir('rb-cfg');
   const f = path.join(tmp, 'kit.json');
   assert.equal(loadKitConfig(f).ruvnetBrain, true, 'default is on');
   const cfg = loadKitConfig(f);
@@ -209,7 +210,7 @@ test('legacySnapshotBytes: no cache root → count 0, bytes null, never throws',
 });
 
 test('legacySnapshotBytes: ignores kb/ itself and anything not matching the legacy prefixes', () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-legacy-none-'));
+  const tmp = tempDir('rb-legacy-none');
   fs.mkdirSync(path.join(tmp, 'kb'));
   fs.writeFileSync(path.join(tmp, 'kb', 'forge-mcp-all.mjs'), 'x'.repeat(1000));
   fs.mkdirSync(path.join(tmp, 'versions'));
@@ -218,7 +219,7 @@ test('legacySnapshotBytes: ignores kb/ itself and anything not matching the lega
 });
 
 test('legacySnapshotBytes: sums bytes recursively across every kb.bak-*/kb.install-preserved-* dir', () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-legacy-sum-'));
+  const tmp = tempDir('rb-legacy-sum');
   fs.mkdirSync(path.join(tmp, 'kb.bak-2026-07-13T10-00-00-000Z', 'nested'), { recursive: true });
   fs.writeFileSync(path.join(tmp, 'kb.bak-2026-07-13T10-00-00-000Z', 'a.rvf'), 'x'.repeat(500));
   fs.writeFileSync(path.join(tmp, 'kb.bak-2026-07-13T10-00-00-000Z', 'nested', 'b.rvf'), 'x'.repeat(250));
@@ -234,7 +235,7 @@ test('legacySnapshotBytes: sums bytes recursively across every kb.bak-*/kb.insta
 });
 
 test('legacySnapshotBytes: a file cap hit still reports a count and a lower-bound sum', () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-legacy-cap-'));
+  const tmp = tempDir('rb-legacy-cap');
   const dir = path.join(tmp, 'kb.install-preserved-zzz');
   fs.mkdirSync(dir);
   for (let i = 0; i < 5; i += 1) fs.writeFileSync(path.join(dir, `f${i}.rvf`), 'x'.repeat(100));
@@ -253,7 +254,7 @@ test('legacySnapshotBytes: a file cap hit still reports a count and a lower-boun
 test('legacySnapshotBytes: an unreadable snapshot dir keeps bytes honestly null, not a false zero', {
   skip: process.platform === 'win32' || process.getuid?.() === 0,
 }, () => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rb-legacy-unreadable-'));
+  const tmp = tempDir('rb-legacy-unreadable');
   const dir = path.join(tmp, 'kb.bak-2026-07-01T00-00-00-000Z');
   fs.mkdirSync(dir);
   fs.writeFileSync(path.join(dir, 'a.rvf'), 'x'.repeat(100));
diff --git a/tests/kit/status-aqe-drift.test.mjs b/tests/kit/status-aqe-drift.test.mjs
index b9b79588..a4aa9ecb 100644
--- a/tests/kit/status-aqe-drift.test.mjs
+++ b/tests/kit/status-aqe-drift.test.mjs
@@ -3,18 +3,19 @@
 // scope gate `ak sync` writes with (applyAqeRouter): a freshly synced state is
 // never drift, and a location sync refuses to manage is never drift either.
 // Anything else is a permanent warning whose own `fix` command cannot clear it.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   sandboxHome, assertSandboxed, rmrf,
   sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot,
 } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const HOME = sandboxHome('ak-status-drift');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const status = await import('../../src/commands/status.mjs');
 const { loadKitConfig } = await import('../../src/lib/config.mjs');
@@ -54,6 +55,7 @@ const routingRow = (rows) => rowsFor(rows, 'routing').find((r) => r.message.incl
 
 test('a freshly synced PARTIAL policy reports no routing drift (writer projection is the contract)', async () => {
   const project = sandboxProject('ak-drift-partial');
+  after(() => rmrf(project));
   seedHome(dualHostCfg({ routes: {
     review: { host: 'claude', model: 'claude-sonnet-5', provenance: 'user' },
   } }));
@@ -66,6 +68,7 @@ test('a freshly synced PARTIAL policy reports no routing drift (writer projectio
 
 test('a user pin on a RETIRED model reports no routing drift after sync honors the pin', async () => {
   const project = sandboxProject('ak-drift-retired');
+  after(() => rmrf(project));
   seedHome(dualHostCfg({ routes: {
     'security-scan': { host: 'codex', model: 'gpt-5.4', provenance: 'user' },
   } }));
@@ -77,6 +80,7 @@ test('a user pin on a RETIRED model reports no routing drift after sync honors t
 
 test('foreign agentOverrides entries and key order are the writer\'s merge domain, not drift', async () => {
   const project = sandboxProject('ak-drift-foreign');
+  after(() => rmrf(project));
   seedHome(dualHostCfg({ routes: seedActivityRoutes() }));
   // Pre-existing file: a managed key first (so merge order differs from a fresh
   // projection) plus a hand-added foreign agent applyAqeRouter must preserve.
@@ -95,7 +99,7 @@ test('foreign agentOverrides entries and key order are the writer\'s merge domai
 });
 
 test('outside a git project, status never reports router drift sync refuses to manage', async () => {
-  const nowhere = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-drift-noproj-')));
+  const nowhere = tempDir('ak-drift-noproj');
   seedHome(dualHostCfg({
     routes: seedActivityRoutes(),
     aqeFallback: [{ provider: 'claude-code', models: ['claude-opus-4-8'] }],
@@ -116,6 +120,7 @@ test('outside a git project, status never reports router drift sync refuses to m
 
 test('from a SUBDIRECTORY of a project, the chain check reads the repo root, not cwd', async () => {
   const project = sandboxProject('ak-drift-subdir');
+  after(() => rmrf(project));
   const subdir = path.join(project, 'src', 'deep');
   fs.mkdirSync(subdir, { recursive: true });
   seedHome(dualHostCfg({
@@ -133,6 +138,7 @@ test('from a SUBDIRECTORY of a project, the chain check reads the repo root, not
 
 test('REAL drift is still caught: a hand-edited managed override warns with a sync fix', async () => {
   const project = sandboxProject('ak-drift-real');
+  after(() => rmrf(project));
   seedHome(dualHostCfg({ routes: seedActivityRoutes() }));
   applyAqeRouter(loadKitConfig(), project);
   const disk = JSON.parse(fs.readFileSync(aqeRouterFile(project), 'utf8'));
@@ -147,6 +153,7 @@ test('REAL drift is still caught: a hand-edited managed override warns with a sy
 
 test('REAL drift is still caught: a configured policy with no file yet warns', async () => {
   const project = sandboxProject('ak-drift-nofile');
+  after(() => rmrf(project));
   seedHome(dualHostCfg({ routes: seedActivityRoutes() }));
   // no applyAqeRouter — the file a first sync would create is absent
 
@@ -157,6 +164,7 @@ test('REAL drift is still caught: a configured policy with no file yet warns', a
 
 test('unavailable external intent names a manual remedy instead of an impossible sync loop', async () => {
   const project = sandboxProject('ak-drift-revoked-external');
+  after(() => rmrf(project));
   seedHome(offlineKitConfig({
     // Deliberately mismatched/stale entry name: the external host id in
     // integration intent remains the actionable cleanup identity.
diff --git a/tests/kit/status-golden.test.mjs b/tests/kit/status-golden.test.mjs
index cabec3bd..a1655be1 100644
--- a/tests/kit/status-golden.test.mjs
+++ b/tests/kit/status-golden.test.mjs
@@ -7,7 +7,7 @@
 //
 // Regenerate deliberately, never casually:
 //   STATUS_GOLDEN_UPDATE=1 node --test tests/kit/status-golden.test.mjs
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import { normalizeStatusObservations } from './helpers/status-observations.mjs';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
@@ -19,6 +19,7 @@ import {
 } from './helpers/home-sandbox.mjs';
 
 const HOME = sandboxHome('ak-status-golden');
+after(() => rmrf(HOME));
 delete process.env.AQE_EMBEDDER_ENDPOINT;
 const paths = await import('../../src/lib/paths.mjs');
 const status = await import('../../src/commands/status.mjs');
@@ -26,6 +27,7 @@ assertSandboxed(paths, HOME);
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-status-golden');
+after(() => rmrf(PROJECT));
 const GOLDEN = path.join(PKG_ROOT, 'tests', 'kit', 'fixtures', 'status-golden.json');
 
 paths._setGlobalRootForTest(fakeGlobalRoot(HOME, { ruflo: '9.9.9', 'agentic-qe': '9.9.9' }));
diff --git a/tests/kit/status-repair-contract.test.mjs b/tests/kit/status-repair-contract.test.mjs
index 3611889c..8d8c2097 100644
--- a/tests/kit/status-repair-contract.test.mjs
+++ b/tests/kit/status-repair-contract.test.mjs
@@ -3,7 +3,7 @@
 // does it) or 'manual' (a human must). `ak sync` plans only 'sync' fixes, so a
 // row sync cannot act on never enters its plan, and the census below proves
 // every subsystem that can emit a 'sync' fix has a sync step that runs for it.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -15,6 +15,7 @@ import {
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const HOME = sandboxHome('ak-repair-contract');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const { row } = await import('../../src/commands/status/row.mjs');
 const sync = await import('../../src/commands/sync.mjs');
@@ -27,6 +28,7 @@ isolateProject('ak-repair-contract-cwd');
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-repair-contract');
+after(() => rmrf(PROJECT));
 paths._setGlobalRootForTest(fakeGlobalRoot(HOME, { ruflo: '9.9.9', 'agentic-qe': '9.9.9' }));
 
 function seedHome(cfg = offlineKitConfig()) {
diff --git a/tests/kit/statusline-config-dir-parity.test.mjs b/tests/kit/statusline-config-dir-parity.test.mjs
index 46522c5e..eeceacfa 100644
--- a/tests/kit/statusline-config-dir-parity.test.mjs
+++ b/tests/kit/statusline-config-dir-parity.test.mjs
@@ -12,6 +12,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 // A bare absolute path is not a valid ESM specifier on Windows (`D:` parses as a URL
@@ -38,7 +39,7 @@ function realConfigDir(platform, env, home) {
   });
 }
 
-const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-parity-home-'));
+const home = tempDir('ak-parity-home');
 const CASES = [
   ['win32 with APPDATA', 'win32', { APPDATA: '/w/AppData', XDG_CONFIG_HOME: '/x' }],
   ['win32 without APPDATA', 'win32', {}],
diff --git a/tests/kit/statusline.test.mjs b/tests/kit/statusline.test.mjs
index 4bdf668f..ac91a5ed 100644
--- a/tests/kit/statusline.test.mjs
+++ b/tests/kit/statusline.test.mjs
@@ -7,14 +7,21 @@
 //
 // The retirement test is the important one: the kit must STOP patching the moment
 // upstream ships a fix, without anyone editing a pinned version number here.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { _setGlobalRootForTest } from '../../src/lib/paths.mjs';
 import { fixStatusline, upstreamCveCounterFabricated } from '../../src/lib/statusline.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
+
+// The rendered footer caches ruflo-daemon-count.json and ruvnet-brain-kb-size.json
+// in os.tmpdir() for 30 s (src/lib/daemons.mjs, statusline-footer.cjs), shared with
+// the developer's live footer; a test render must never poison those caches.
+const toolState = redirectToolState('ak-sl');
+after(() => toolState.restore());
 
 // Minimal stand-in for ruflo's real statusline: only the shapes fixStatusline keys
 // off. resolveCliBinCandidates models the upstream defect — candidates that never
@@ -35,7 +42,7 @@ const signalsSrc = (buggy) => (buggy
   : 'export function getSecurityStatus(cwd) {\n  const findings = readScan(cwd);\n  return { status: findings.length ? "ISSUES" : "CLEAN" };\n}\n');
 
 function fixture({ buggyUpstream, rufloVersion }) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-sl-'));
+  const dir = tempDir('ak-sl');
   const proj = path.join(dir, 'proj');
   fs.mkdirSync(path.join(proj, '.claude', 'helpers'), { recursive: true });
   fs.writeFileSync(path.join(proj, '.claude', 'helpers', 'statusline.cjs'), HOST);
diff --git a/tests/kit/sync-host-repair.test.mjs b/tests/kit/sync-host-repair.test.mjs
index faf81391..fa4cdd12 100644
--- a/tests/kit/sync-host-repair.test.mjs
+++ b/tests/kit/sync-host-repair.test.mjs
@@ -1,8 +1,9 @@
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { sandboxHome } from './helpers/home-sandbox.mjs';
+import { sandboxHome, rmrf } from './helpers/home-sandbox.mjs';
 
-sandboxHome('ak-sync-host-repair');
+const SANDBOX_HOME = sandboxHome('ak-sync-host-repair');
+after(() => rmrf(SANDBOX_HOME));
 const sync = await import('../../src/commands/sync.mjs');
 
 const hostsStep = sync.SYNC_STEPS.find((s) => s.id === 'hosts');
diff --git a/tests/kit/sync-needs-your-action.test.mjs b/tests/kit/sync-needs-your-action.test.mjs
index d483b119..774fa4c9 100644
--- a/tests/kit/sync-needs-your-action.test.mjs
+++ b/tests/kit/sync-needs-your-action.test.mjs
@@ -11,7 +11,7 @@
 // project's missing .agentic-qe directory. --json runs spawn a child so its
 // real stdout and stderr can be read apart (sync swaps process.stdout.write
 // under --json, which must not happen inside the test runner's own process).
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -23,6 +23,7 @@ import {
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const HOME = sandboxHome('ak-sync-needs-action');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const sync = await import('../../src/commands/sync.mjs');
 const { row } = await import('../../src/commands/status/row.mjs');
@@ -32,6 +33,7 @@ isolateProject('ak-sync-needs-action');
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const PROJECT = sandboxProject('ak-sync-needs-action');
+after(() => rmrf(PROJECT));
 const FLAGS = (over = {}) => ({ 'dry-run': false, 'no-upgrade': true, yes: false, json: false, ...over });
 const HEADING = /needs your action/g;
 
diff --git a/tests/kit/sync-self-freshness.test.mjs b/tests/kit/sync-self-freshness.test.mjs
index 2ee11ce3..98c36566 100644
--- a/tests/kit/sync-self-freshness.test.mjs
+++ b/tests/kit/sync-self-freshness.test.mjs
@@ -1,13 +1,14 @@
 // Exercise the real self-status collector and sync planner against isolated
 // cache/package files; replace only registry I/O and the package install step.
-import test from 'node:test';
+import test, { after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { sandboxHome, assertSandboxed, writeKitConfig, offlineKitConfig, captureLog } from './helpers/home-sandbox.mjs';
+import { sandboxHome, assertSandboxed, writeKitConfig, offlineKitConfig, captureLog, rmrf } from './helpers/home-sandbox.mjs';
 import { isolateProject } from './helpers/project-isolation.mjs';
 
 const home = sandboxHome('ak-sync-self');
+after(() => rmrf(home));
 const paths = await import('../../src/lib/paths.mjs');
 const { loadKitConfig } = await import('../../src/lib/config.mjs');
 const sync = await import('../../src/commands/sync.mjs');
diff --git a/tests/kit/system-summary.test.mjs b/tests/kit/system-summary.test.mjs
index 5b76ea72..da3fb08a 100644
--- a/tests/kit/system-summary.test.mjs
+++ b/tests/kit/system-summary.test.mjs
@@ -9,12 +9,12 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
 import vm from 'node:vm';
 
 import { startDashboard } from '../../src/lib/dashboard-server.mjs';
 import { systemSummaryPayload, SUMMARY_CATALOG_KEYS } from '../../src/lib/dashboard/system-summary.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // ── A catalog in the persisted CatalogInventory v4 shape ────────────────────
 
@@ -305,7 +305,7 @@ function hermeticMaintenance() {
 
 test('GET /api/system/summary serves the projection; GET /api/system stays complete', async (t) => {
   const collector = fakeCollector();
-  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-system-summary-'));
+  const cwd = tempDir('ak-system-summary');
   const server = await startDashboard({ port: 0, cwd, system: collector, usage: {}, ...hermeticMaintenance() });
   t.after(() => server.close());
 
@@ -327,7 +327,7 @@ test('GET /api/system/summary serves the projection; GET /api/system stays compl
 
 test('GET /api/system/summary?refresh=deep starts the scan and answers with its running state', async (t) => {
   const collector = fakeCollector();
-  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-system-summary-'));
+  const cwd = tempDir('ak-system-summary');
   const server = await startDashboard({ port: 0, cwd, system: collector, usage: {}, ...hermeticMaintenance() });
   t.after(() => server.close());
   const r = await request(server, '/api/system/summary?refresh=deep&trees=0');
diff --git a/tests/kit/temp-dir-helper.test.mjs b/tests/kit/temp-dir-helper.test.mjs
new file mode 100644
index 00000000..e63c131d
--- /dev/null
+++ b/tests/kit/temp-dir-helper.test.mjs
@@ -0,0 +1,16 @@
+// tests/kit/temp-dir-helper.test.mjs
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import { tempDir } from './helpers/temp-dir.mjs';
+
+let fromTest;
+test('a per-test temp folder exists during the test', (t) => {
+  fromTest = tempDir('ak-tempdir-probe', t);
+  assert.ok(fs.statSync(fromTest).isDirectory());
+  assert.ok(fromTest.startsWith(fs.realpathSync(os.tmpdir())));
+});
+test('and is gone after it', () => {
+  assert.equal(fs.existsSync(fromTest), false);
+});
diff --git a/tests/kit/usage-claude-dedup.test.mjs b/tests/kit/usage-claude-dedup.test.mjs
index 0bf6ff75..36a861d9 100644
--- a/tests/kit/usage-claude-dedup.test.mjs
+++ b/tests/kit/usage-claude-dedup.test.mjs
@@ -7,12 +7,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { parseClaude } from '../../src/lib/usage-parsers.mjs';
 import { decodeClaudeRecord } from '../../src/lib/telemetry-records.mjs';
 import { buildIndex, SCHEMA_VERSION, _resetForTest } from '../../src/lib/usage-index.mjs';
 import { costOf, priceFor } from '../../src/lib/pricing.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const T0 = Date.parse('2026-08-20T10:00:00.000Z');
 const at = (s) => new Date(T0 + s * 1000).toISOString();
@@ -190,7 +190,7 @@ test('turn rows (reader path) are still emitted per transcript line', () => {
 test('SCHEMA_VERSION is at least 22 and a v21 cache is discarded and re-parsed de-duplicated', async () => {
   assert.ok(SCHEMA_VERSION >= 22, 'the de-dup correction changes every cached Claude record');
   _resetForTest();
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-dedup-'));
+  const dir = tempDir('ak-dedup');
   const proj = path.join(dir, 'claude', '-Users-me-proj');
   fs.mkdirSync(proj, { recursive: true });
   const base = Date.parse('2026-07-24T10:00:00.000Z');
diff --git a/tests/kit/usage-cli.test.mjs b/tests/kit/usage-cli.test.mjs
index 208417db..52e6f77b 100644
--- a/tests/kit/usage-cli.test.mjs
+++ b/tests/kit/usage-cli.test.mjs
@@ -4,16 +4,16 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { MODES } from '../../src/lib/usage-modes.mjs';
 import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const BIN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin/agentic-kit.mjs');
 
 function sandbox() {
-  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-cli-'));
+  const home = tempDir('ak-usage-cli');
   const cfg = path.join(home, '.config');
   const bin = path.join(home, 'bin');
   const sentinel = path.join(home, 'npm-was-called');
diff --git a/tests/kit/usage-codex-large-rollout.test.mjs b/tests/kit/usage-codex-large-rollout.test.mjs
index 04657ca0..b43b888b 100644
--- a/tests/kit/usage-codex-large-rollout.test.mjs
+++ b/tests/kit/usage-codex-large-rollout.test.mjs
@@ -11,6 +11,7 @@ import { buildIndex, _resetForTest } from '../../src/lib/usage-index.mjs';
 import { parseCodex } from '../../src/lib/usage-parsers.mjs';
 import { openCodexRollout } from '../../src/lib/codex-rollout-reader.mjs';
 import { Rollout, usage, codexSandbox, stubDeps, forkedSubagent } from './helpers/codex-rollout.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const NOW = Date.parse('2026-07-25T12:00:00.000Z');
 const opts = (sb, extra = {}) => ({
@@ -18,7 +19,7 @@ const opts = (sb, extra = {}) => ({
 });
 
 function tmpFile(body, name = 'rollout.jsonl') {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-codex-reader-'));
+  const dir = tempDir('ak-codex-reader');
   const file = path.join(dir, name);
   fs.writeFileSync(file, body);
   return file;
diff --git a/tests/kit/usage-deps-contract.test.mjs b/tests/kit/usage-deps-contract.test.mjs
index 2e0d44ac..4ccf0352 100644
--- a/tests/kit/usage-deps-contract.test.mjs
+++ b/tests/kit/usage-deps-contract.test.mjs
@@ -1,13 +1,13 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildIndex, _resetForTest } from '../../src/lib/usage-index.mjs';
 import { costOf, priceFor, PRICES_AS_OF } from '../../src/lib/pricing.mjs';
 import { classify } from '../../src/lib/usage-classify.mjs';
 import { detectInsights } from '../../src/lib/usage-insights.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // ADR-0009 follow-up decision 4 — the `deps` seam, executed for real.
 //
@@ -39,7 +39,7 @@ const SEVERITIES = new Set(['warn', 'info', 'ok']);
  * $-free, which would leave the `impact` contract's number branch untested.
  */
 function corpus() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-deps-'));
+  const dir = tempDir('ak-deps');
   fs.cpSync(FIXTURES, path.join(dir, 'corpus'), { recursive: true });
   const proj = path.join(dir, 'corpus', 'claude', '-Users-me-proj');
 
diff --git a/tests/kit/usage-index-v6.test.mjs b/tests/kit/usage-index-v6.test.mjs
index b7d6fe84..ab71807d 100644
--- a/tests/kit/usage-index-v6.test.mjs
+++ b/tests/kit/usage-index-v6.test.mjs
@@ -5,12 +5,12 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { buildIndex, readSession, _resetForTest } from '../../src/lib/usage-index.mjs';
 import {
   parseClaude, parseCodex, promptFingerprint, promptSemantics,
 } from '../../src/lib/usage-parsers.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const NOW = Date.parse('2026-07-25T12:00:00.000Z');
 const T0 = '2026-07-24T09:00:00.000Z';
@@ -84,7 +84,7 @@ function rolloutItemCompleted(id, { mixed = false } = {}) {
 }
 
 function sandbox(files) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-v6-'));
+  const dir = tempDir('ak-usage-v6');
   const day = path.join(dir, 'codex', '2026', '07', '24');
   fs.mkdirSync(day, { recursive: true });
   fs.mkdirSync(path.join(dir, 'claude'), { recursive: true });
diff --git a/tests/kit/usage-index.test.mjs b/tests/kit/usage-index.test.mjs
index 5a2cb275..9ee2c8a3 100644
--- a/tests/kit/usage-index.test.mjs
+++ b/tests/kit/usage-index.test.mjs
@@ -2,7 +2,6 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -18,6 +17,7 @@ import {
   aggregate, percentileFromBuckets, modelFamily,
   LAT_BUCKET_EDGES as AGG_LAT_EDGES, LEN_BUCKET_EDGES as AGG_LEN_EDGES,
 } from '../../src/lib/usage-aggregate.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const FIXTURES = path.join(HERE, '..', 'fixtures', 'usage');
@@ -30,7 +30,7 @@ const NOW = Date.parse('2026-07-25T12:00:00.000Z');
 /** Copy the fixture corpus into a throwaway tmpdir; return injectable roots +
  *  a cache path. Nothing here ever touches ~/.claude, ~/.codex or ~/.config. */
 function sandbox() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-'));
+  const dir = tempDir('ak-usage');
   fs.cpSync(FIXTURES, path.join(dir, 'corpus'), { recursive: true });
   return {
     dir,
@@ -63,7 +63,7 @@ const byId = (agg, id) => agg.sessions.find((s) => s.id === id);
 /** A sandbox with NO fixture corpus — for engaged-time tests that need a single
  *  session's arithmetic to be the whole of the answer. */
 function soloSandbox() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-solo-'));
+  const dir = tempDir('ak-usage-solo');
   const claude = path.join(dir, 'claude', '-Users-me-proj');
   fs.mkdirSync(claude, { recursive: true });
   return {
@@ -926,7 +926,7 @@ test('the window excludes sessions older than `days`', async () => {
 
 test('an empty corpus yields a zeroed Aggregate rather than throwing', async () => {
   _resetForTest();
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-empty-'));
+  const dir = tempDir('ak-usage-empty');
   const agg = await buildIndex({
     days: 14, now: NOW, deps: deps(),
     roots: { claude: path.join(dir, 'nope'), codex: path.join(dir, 'also-nope') },
@@ -967,7 +967,7 @@ test('buildIndex reports ok claude/codex root health when the transcript roots e
 
 test('an unreadable Claude root degrades rather than silently reading as zero sessions', async () => {
   _resetForTest();
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-usage-unreadable-'));
+  const dir = tempDir('ak-usage-unreadable');
   const claudeRoot = path.join(dir, 'claude-is-a-file');
   fs.writeFileSync(claudeRoot, 'not a directory'); // readdirSync on this throws ENOTDIR, not ENOENT
   const agg = await buildIndex({
diff --git a/tests/kit/usage-truncation.test.mjs b/tests/kit/usage-truncation.test.mjs
index f9af1339..e7b4ec46 100644
--- a/tests/kit/usage-truncation.test.mjs
+++ b/tests/kit/usage-truncation.test.mjs
@@ -1,9 +1,9 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { readSession, maskSecrets, MAX_TURN_CHARS, _resetForTest } from '../../src/lib/usage-index.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 // ADR-0009 §8 / design decision 2 — "turn truncation is announced, with both
 // figures". A truncated turn must say HOW MUCH was withheld, not merely that
@@ -40,7 +40,7 @@ test('MAX_TURN_CHARS is the 40,000 the spec states', () => {
 
 /** A sandbox with no fixture corpus: one hand-written session is the whole answer. */
 function soloSandbox() {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-trunc-'));
+  const dir = tempDir('ak-trunc');
   const claude = path.join(dir, 'claude', '-Users-me-proj');
   fs.mkdirSync(claude, { recursive: true });
   return {
diff --git a/tests/kit/verify-memory-routes.test.mjs b/tests/kit/verify-memory-routes.test.mjs
index e2dc3390..faaee7b0 100644
--- a/tests/kit/verify-memory-routes.test.mjs
+++ b/tests/kit/verify-memory-routes.test.mjs
@@ -6,7 +6,7 @@
 // project with this suite's environment): a CLI store is mirrored into
 // memory.db AND agentdb-memory.db, an MCP store lands in agentdb-memory.db only,
 // and a default `memory purge` clears memory.db only while reporting success.
-import { test } from 'node:test';
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -15,6 +15,7 @@ import {
   sandboxHome, assertSandboxed, captureLog, rmrf,
   sandboxProject, writeKitConfig, offlineKitConfig, fakeGlobalRoot,
 } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 
 const FAKE_RUFLO = `#!/usr/bin/env node
 const fs = require('node:fs');
@@ -87,10 +88,12 @@ if (argv[0] === 'mcp') {
 `;
 
 const HOME = sandboxHome('ak-verify-routes');
+after(() => rmrf(HOME));
 const paths = await import('../../src/lib/paths.mjs');
 const verify = await import('../../src/commands/x/verify.mjs');
 assertSandboxed(paths, HOME);
 const PROJECT = sandboxProject('ak-verify-routes');
+after(() => rmrf(PROJECT));
 paths._setGlobalRootForTest(fakeGlobalRoot(HOME, { ruflo: '9.9.9' }));
 
 const posix = { skip: process.platform === 'win32' ? 'fake ruflo is a POSIX shebang script' : false };
@@ -99,7 +102,7 @@ const posix = { skip: process.platform === 'win32' ? 'fake ruflo is a POSIX sheb
 async function withFakeRuflo(mode, fn) {
   rmrf(paths.configDir());
   writeKitConfig(HOME, offlineKitConfig());
-  const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-fake-ruflo-'));
+  const bin = tempDir('ak-fake-ruflo');
   const log = path.join(bin, 'calls.log');
   fs.writeFileSync(path.join(bin, 'ruflo'), FAKE_RUFLO, { mode: 0o755 });
   const saved = { PATH: process.env.PATH, FAKE_RUFLO_MODE: process.env.FAKE_RUFLO_MODE, FAKE_RUFLO_LOG: process.env.FAKE_RUFLO_LOG, cwd: process.cwd() };
@@ -150,7 +153,7 @@ test('an unusable MCP server is "not observed" and does not fail the suite', pos
 });
 
 test('the isolated proof never writes into a user-set memory root', posix, async () => {
-  const decoy = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-decoy-store-'));
+  const decoy = tempDir('ak-decoy-store');
   const saved = process.env.CLAUDE_FLOW_MEMORY_PATH;
   process.env.CLAUDE_FLOW_MEMORY_PATH = decoy;
   try {

From ee9dcd1229c8d323da8c4e802f9cf5a57f0527a7 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:35:02 -0700
Subject: [PATCH 08/28] test(runner): run the suite in its own temporary folder
 and fail on leftovers

runGuarded now makes an ak-suite-* folder under os.tmpdir(), passes it to
every command as TMPDIR/TEMP/TMP, lists and fails (exit 4) on anything left in
it except node-compile-cache, and always removes it. It refuses to start
(exit 2) when that folder sits inside a git repository, because the "outside
a git repository" tests would then write into the enclosing one.

Running the seven .cjs suites through `run-tests.mjs exec` found leftovers the
tests/kit probe could not see (statusline-segments 46, statusline-brain 21,
statusline-window-ledger 12, dashboard 2, including the footer's
ruflo-daemon-count.json / ruvnet-brain-kb-size.json caches). Those plain-script
suites now call usePrivateTmpdir() from tests/kit/helpers/private-tmpdir.cjs,
which points os.tmpdir() at a private folder removed on exit. The UI suite
gets the same in dashboard-ui.mjs, and maintenance-host-alignment.mjs writes
its screenshot to .ui-artifacts/ (as dashboard-project-context does) instead
of the temp folder. After: all seven .cjs suites and `run-tests.mjs ui` exit 0
with no leftovers.

AGENTS.md (Running Tests) describes the temp root, the refusal, tempDir() and
spawnEnv().
---
 AGENTS.md                               |  9 +++++--
 scripts/run-tests.mjs                   | 33 ++++++++++++++++++++++---
 tests/dashboard.test.cjs                |  2 ++
 tests/kit/helpers/private-tmpdir.cjs    | 20 +++++++++++++++
 tests/kit/run-tests-runner.test.mjs     | 19 ++++++++++++++
 tests/statusline-brain.test.cjs         |  2 ++
 tests/statusline-segments.test.cjs      |  2 ++
 tests/statusline-window-ledger.test.cjs |  2 ++
 tests/ui/dashboard-ui.mjs               |  4 +++
 tests/ui/maintenance-host-alignment.mjs |  6 +++--
 10 files changed, 92 insertions(+), 7 deletions(-)
 create mode 100644 tests/kit/helpers/private-tmpdir.cjs

diff --git a/AGENTS.md b/AGENTS.md
index 73e21c7f..46b9cbf3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -287,8 +287,13 @@ Windows), the Claude/Codex/OpenCode guidance files ak manages, and this reposito
 `.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` before and after the run. Any change fails
 the run and is listed by path. Files a live Claude Code, Ruflo or AQE session writes during the
 run are listed as "concurrent writers" and do not fail a local run; CI (or
-`AK_TRIPWIRE_STRICT=1`) fails on them too. `node scripts/run-tests.mjs exec -- <node args>`
-guards any single command the same way.
+`AK_TRIPWIRE_STRICT=1`) fails on them too. Every command also runs with `TMPDIR`/`TEMP`/`TMP`
+pointed at a fresh `ak-suite-*` folder: anything left in it afterwards fails the run and is
+listed, and the runner refuses to start when that folder sits inside a git repository (point
+`TMPDIR` elsewhere). Tests make temporary folders with `tempDir()` from
+`tests/kit/helpers/temp-dir.mjs`, and spawned children get their environment from `spawnEnv()` in
+`tests/kit/helpers/home-sandbox.mjs`. `node scripts/run-tests.mjs exec -- <node args>` guards any
+single command the same way.
 
 ### Test Philosophy
 
diff --git a/scripts/run-tests.mjs b/scripts/run-tests.mjs
index 16b5c18b..381775aa 100644
--- a/scripts/run-tests.mjs
+++ b/scripts/run-tests.mjs
@@ -32,25 +32,52 @@ export const SUITES = {
 /**
  * @param {string[][]} commands argument vectors for process.execPath
  * @param {{ env?: NodeJS.ProcessEnv, repoRoot?: string, platform?: string, homedir?: string, log?: (s: string) => void }} [o]
- * @returns {number} exit code: the first failing command's, else 3 on a real-state change, else 0
+ * @returns {number} exit code: 2 when the suite temp root sits inside a git repository,
+ *   else the first failing command's, else 3 on a real-state change, else 4 on leftover
+ *   temp folders, else 0
  */
 export function runGuarded(commands, {
   env = process.env, repoRoot = REPO, platform = process.platform, homedir = os.homedir(), log = console.error,
 } = {}) {
+  // Every command runs with this run's own templated temp root: leftovers are then
+  // attributable to the run, and they fail it.
+  const tempRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-suite-')));
+  const enclosing = enclosingRepository(tempRoot);
+  if (enclosing) {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+    log(`the suite temp root ${tempRoot} is inside the git repository ${enclosing}; tests that probe "outside a `
+      + 'git repository" would write into it. Point TMPDIR outside any repository.');
+    return 2;
+  }
+  const childEnv = { ...env, TMPDIR: tempRoot, TEMP: tempRoot, TMP: tempRoot };
   const roots = realStateRoots({ env, platform, homedir, repoRoot });
   const before = snapshotRoots(roots);
   // One line before anything runs, so a CI log proves the tripwire executed.
   log(`real-state tripwire: watching ${roots.length} roots (${isStrict(env) ? 'strict' : 'developer'})`);
   let code = 0;
   for (const args of commands) {
-    const r = spawnSync(process.execPath, args, { cwd: repoRoot, env, stdio: 'inherit' });
+    const r = spawnSync(process.execPath, args, { cwd: repoRoot, env: childEnv, stdio: 'inherit' });
     if (r.error) { log(`could not run node ${args.join(' ')}: ${r.error.message}`); code = 1; break; }
     if (r.status !== 0) { code = r.status ?? 1; break; }
   }
+  const leftovers = fs.readdirSync(tempRoot).filter((name) => name !== 'node-compile-cache');
+  fs.rmSync(tempRoot, { recursive: true, force: true, maxRetries: 3 });
+  if (leftovers.length) log(`temp folders left behind by the run (${leftovers.length}):\n  ${leftovers.join('\n  ')}`);
   const result = compareSnapshots(before, snapshotRoots(roots), { strict: isStrict(env) });
   const report = formatReport(result);
   if (report) log(report);
-  return code || (result.failing.length ? 3 : 0);
+  return code || (result.failing.length ? 3 : 0) || (leftovers.length ? 4 : 0);
+}
+
+/** The nearest folder at or above `dir` that holds a `.git` entry, or null. */
+function enclosingRepository(dir) {
+  for (let cur = dir, i = 0; i < 64; i++) {
+    if (fs.existsSync(path.join(cur, '.git'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
 }
 
 function main(argv) {
diff --git a/tests/dashboard.test.cjs b/tests/dashboard.test.cjs
index cceda4fa..016c3d18 100644
--- a/tests/dashboard.test.cjs
+++ b/tests/dashboard.test.cjs
@@ -15,6 +15,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// Every temp folder and footer cache this suite makes lands here and is removed on exit.
+require('./kit/helpers/private-tmpdir.cjs').usePrivateTmpdir('ak-dashboard');
 const http = require('http');
 
 const ROOT = path.resolve(__dirname, '..');
diff --git a/tests/kit/helpers/private-tmpdir.cjs b/tests/kit/helpers/private-tmpdir.cjs
new file mode 100644
index 00000000..e7dcc21d
--- /dev/null
+++ b/tests/kit/helpers/private-tmpdir.cjs
@@ -0,0 +1,20 @@
+// Point this process's os.tmpdir() (and every child it spawns) at a private
+// folder that is removed on exit. For the plain-script .cjs suites, which have
+// no node:test hooks: they make many temp folders, and the statusline renders
+// they run drop ruflo-daemon-count.json / ruvnet-brain-kb-size.json into
+// os.tmpdir(). Call it before anything reads os.tmpdir().
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function usePrivateTmpdir(prefix) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`)));
+  process.env.TMPDIR = dir;
+  process.env.TEMP = dir;
+  process.env.TMP = dir;
+  process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 }));
+  return dir;
+}
+
+module.exports = { usePrivateTmpdir };
diff --git a/tests/kit/run-tests-runner.test.mjs b/tests/kit/run-tests-runner.test.mjs
index 28dbc968..e954f3db 100644
--- a/tests/kit/run-tests-runner.test.mjs
+++ b/tests/kit/run-tests-runner.test.mjs
@@ -80,3 +80,22 @@ test('SUITES keeps the exact commands package.json ran before', async () => {
   assert.equal(pkg.scripts.test, 'node scripts/run-tests.mjs unit');
   assert.equal(pkg.scripts['test:ui'], 'node scripts/run-tests.mjs ui');
 });
+
+test('a leftover temp folder fails the run and is named', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const leaky = stub(home, 'leaky.mjs', `import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path';
+    fs.mkdtempSync(path.join(os.tmpdir(), 'ak-leaky-'));`);
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leaky], { env, encoding: 'utf8' });
+  assert.equal(r.status, 4, r.stderr);
+  assert.match(r.stderr, /ak-leaky-/);
+});
+
+test('the runner refuses a temp root inside a git repository', (t) => {
+  const { home, repo, env } = sandbox(t);
+  const inside = path.join(repo, 'tmp');
+  fs.mkdirSync(inside);
+  const ok = stub(home, 'ok.mjs', '');
+  const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', ok], { env: { ...env, TMPDIR: inside, TEMP: inside, TMP: inside }, encoding: 'utf8' });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /inside the git repository/);
+});
diff --git a/tests/statusline-brain.test.cjs b/tests/statusline-brain.test.cjs
index f5df1627..a809f081 100644
--- a/tests/statusline-brain.test.cjs
+++ b/tests/statusline-brain.test.cjs
@@ -14,6 +14,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// Every temp folder and footer cache this suite makes lands here and is removed on exit.
+require('./kit/helpers/private-tmpdir.cjs').usePrivateTmpdir('ak-statusline-brain');
 
 const ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(ROOT, 'src', 'templates', 'statusline-footer.cjs');
diff --git a/tests/statusline-segments.test.cjs b/tests/statusline-segments.test.cjs
index fd691087..931c2f5c 100644
--- a/tests/statusline-segments.test.cjs
+++ b/tests/statusline-segments.test.cjs
@@ -15,6 +15,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// Every temp folder and footer cache this suite makes lands here and is removed on exit.
+require('./kit/helpers/private-tmpdir.cjs').usePrivateTmpdir('ak-statusline-segments');
 
 const ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(ROOT, 'src', 'templates', 'statusline-footer.cjs');
diff --git a/tests/statusline-window-ledger.test.cjs b/tests/statusline-window-ledger.test.cjs
index bd139a2c..161c8bc4 100644
--- a/tests/statusline-window-ledger.test.cjs
+++ b/tests/statusline-window-ledger.test.cjs
@@ -17,6 +17,8 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// Every temp folder and footer cache this suite makes lands here and is removed on exit.
+require('./kit/helpers/private-tmpdir.cjs').usePrivateTmpdir('ak-statusline-window-ledger');
 
 const ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(ROOT, 'src', 'templates', 'statusline-footer.cjs');
diff --git a/tests/ui/dashboard-ui.mjs b/tests/ui/dashboard-ui.mjs
index f637847c..5001744a 100644
--- a/tests/ui/dashboard-ui.mjs
+++ b/tests/ui/dashboard-ui.mjs
@@ -32,6 +32,7 @@ import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
+import privateTmpdir from '../kit/helpers/private-tmpdir.cjs';
 import { chromium } from 'playwright';
 import { startDashboard } from '../../src/lib/dashboard-server.mjs';
 import { readIndex, readSession, maskSecrets } from '../../src/lib/usage-index.mjs';
@@ -62,6 +63,9 @@ import {
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(HERE, '..', '..');
+// Fixture corpora, caches and the browser's own temp files land in a private
+// os.tmpdir() that is removed on exit (the suite runner fails on leftovers).
+privateTmpdir.usePrivateTmpdir('ak-dashboard-ui');
 const SHOTS = path.join(ROOT, '.ui-artifacts');
 
 const REAL = process.argv.includes('--real');
diff --git a/tests/ui/maintenance-host-alignment.mjs b/tests/ui/maintenance-host-alignment.mjs
index 2192a156..7cf031df 100644
--- a/tests/ui/maintenance-host-alignment.mjs
+++ b/tests/ui/maintenance-host-alignment.mjs
@@ -3,7 +3,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { chromium } from 'playwright';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
@@ -72,5 +71,8 @@ test('Host alignment view filters User and Project rows and offers exact registr
   assert.match(await page.locator('#mnt-results').innerText(), /project-peer/);
   assert.doesNotMatch(await page.locator('#mnt-results').innerText(), /user-peer/);
   assert.equal(errors.length, 0, errors.join('\n'));
-  await page.screenshot({ path: path.join(os.tmpdir(), 'maintenance-host-alignment.png'), fullPage: true });
+  // Evidence for human review goes to the gitignored .ui-artifacts/, never the temp folder.
+  const shots = path.resolve(process.env.AK_DASHBOARD_EVIDENCE_DIR || '.ui-artifacts');
+  fs.mkdirSync(shots, { recursive: true });
+  await page.screenshot({ path: path.join(shots, 'maintenance-host-alignment.png'), fullPage: true });
 });

From 60c0ac7c842dc61a69ac1c84b3381c667132ae29 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:36:56 -0700
Subject: [PATCH 09/28] test(isolation): never write an enclosing repository
 from a temp project

Probe: every tests/kit file run alone with TMPDIR inside a fake enclosing git
repository. Two files wrote into it: aqe-embedding-projection (the two
"outside a git repository" cases: .claude/settings.local.json and its
ownership sidecar) and status-aqe-drift (the no-project case: .claude and
.agentic-qe/llm-config.json). Both cases now skip with the enclosing
repository named when repoRoot() of their fixture is not null; with the
default TMPDIR they run as before (28/28 pass, 0 skipped).

opencode-stock-ruflo-gateway gives the workspace OpenCode runs in its own
.git, so OpenCode can never climb to an enclosing package.json/node_modules.

Eleven other files fail (without writing) when TMPDIR is inside a
repository; the suite runner refuses to start in that layout, so they are
recorded in the slice report rather than changed here.
---
 tests/kit/aqe-embedding-projection.test.mjs     | 9 +++++++++
 tests/kit/opencode-stock-ruflo-gateway.test.mjs | 4 ++++
 tests/kit/status-aqe-drift.test.mjs             | 7 ++++++-
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/tests/kit/aqe-embedding-projection.test.mjs b/tests/kit/aqe-embedding-projection.test.mjs
index cb2fc813..34d9b43a 100644
--- a/tests/kit/aqe-embedding-projection.test.mjs
+++ b/tests/kit/aqe-embedding-projection.test.mjs
@@ -6,6 +6,7 @@ import path from 'node:path';
 import { inspectAqeEmbeddingProjections as inspect, reconcileAqeEmbeddingProjections as reconcile,
   prepareAqeEmbeddingInitialization } from '../../src/lib/aqe-embedding-projection.mjs';
 import { applyOpencode, opencodeConverged } from '../../src/lib/opencode-core.mjs';
+import { repoRoot } from '../../src/lib/paths.mjs';
 const inspectAqeEmbeddingProjections = (cfg, cwd, opts = {}) => inspect(cfg, cwd, { claudeUserFile: path.join(cwd, 'claude-user.json'), ...opts });
 const reconcileAqeEmbeddingProjections = (cfg, cwd, opts = {}) => reconcile(cfg, cwd, { claudeUserFile: path.join(cwd, 'claude-user.json'), ...opts });
 
@@ -200,6 +201,10 @@ test('reports explicit user scope conflict and refuses malformed precedence evid
 test('outside a git repository no project target is required or written', t => {
   const { cwd, cfg } = fixture(t);
   fs.rmSync(path.join(cwd, '.git'), { recursive: true });
+  // With TMPDIR inside a git repository the fixture is not 'outside' one, and the
+  // reconcile would write that enclosing repository's .claude/.agentic-qe.
+  const enclosing = repoRoot(cwd);
+  if (enclosing) { t.skip(`TMPDIR is inside the git repository ${enclosing}; this case would write into it`); return; }
   cfg.integrations.hosts = { claude: true, codex: true };
   const codexHome = path.join(cwd, 'codex-home');
   fs.mkdirSync(codexHome);
@@ -215,6 +220,10 @@ test('outside a git repository no project target is required or written', t => {
 test('outside a git repository a previously owned stray value is relinquished', t => {
   const { cwd, write, cfg } = fixture(t);
   fs.rmSync(path.join(cwd, '.git'), { recursive: true });
+  // With TMPDIR inside a git repository the fixture is not 'outside' one, and the
+  // reconcile would write that enclosing repository's .claude/.agentic-qe.
+  const enclosing = repoRoot(cwd);
+  if (enclosing) { t.skip(`TMPDIR is inside the git repository ${enclosing}; this case would write into it`); return; }
   const file = write('.claude/settings.local.json', { env: { AQE_EMBEDDER_ENDPOINT: cfg.aqeEmbedding.endpoint } });
   write('.claude/settings.local.json.agentic-kit-aqe-embedding.json', {
     version: 1, before: { present: false }, after: { present: true, value: cfg.aqeEmbedding.endpoint }, pending: false,
diff --git a/tests/kit/opencode-stock-ruflo-gateway.test.mjs b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
index bd00913d..6a3fe8a2 100644
--- a/tests/kit/opencode-stock-ruflo-gateway.test.mjs
+++ b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
@@ -325,6 +325,10 @@ test(`stock OpenCode keeps Ruflo and Agentic QE connected with ${compactProjecti
   fs.mkdirSync(fakeBin, { recursive: true });
   fs.mkdirSync(configDir, { recursive: true });
   fs.mkdirSync(workspace, { recursive: true });
+  // Its own repository: from a .git-less workspace under a TMPDIR inside a git
+  // repository, OpenCode edited the enclosing package.json, created
+  // package-lock.json and replaced node_modules (Branch 0 review-hermeticity.md).
+  fs.mkdirSync(path.join(workspace, '.git'));
   if (!installedRuv) {
     writeFakeMcp(path.join(fakeBin, 'claude-flow-mcp'));
     writeFakeMcp(path.join(fakeBin, 'aqe-mcp'));
diff --git a/tests/kit/status-aqe-drift.test.mjs b/tests/kit/status-aqe-drift.test.mjs
index a4aa9ecb..642c4629 100644
--- a/tests/kit/status-aqe-drift.test.mjs
+++ b/tests/kit/status-aqe-drift.test.mjs
@@ -21,6 +21,7 @@ const status = await import('../../src/commands/status.mjs');
 const { loadKitConfig } = await import('../../src/lib/config.mjs');
 const { applyAqeRouter, aqeRouterFile, managedEnv, settingsTarget } = await import('../../src/lib/providers.mjs');
 const { seedActivityRoutes } = await import('../../src/lib/routing.mjs');
+const { repoRoot } = paths;
 assertSandboxed(paths, HOME);
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
@@ -98,8 +99,12 @@ test('foreign agentOverrides entries and key order are the writer\'s merge domai
   assert.equal(row.level, 'ok', `preserved foreign entry / merge order is not drift: ${row.message}`);
 });
 
-test('outside a git project, status never reports router drift sync refuses to manage', async () => {
+test('outside a git project, status never reports router drift sync refuses to manage', async (t) => {
   const nowhere = tempDir('ak-drift-noproj');
+  // With TMPDIR inside a git repository this folder is not 'outside' one, and the
+  // status/sync paths would write that enclosing repository's .claude/.agentic-qe.
+  const enclosing = repoRoot(nowhere);
+  if (enclosing) { t.skip(`TMPDIR is inside the git repository ${enclosing}; this case would write into it`); return; }
   seedHome(dualHostCfg({
     routes: seedActivityRoutes(),
     aqeFallback: [{ provider: 'claude-code', models: ['claude-opus-4-8'] }],

From dbb0c046dea2624481790eee6f5abd8e5fb4d2b1 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:38:48 -0700
Subject: [PATCH 10/28] test(live): run the memory-routing live test in a
 disposable home

tests/live/ruflo-memory-routing.test.mjs now calls sandboxHome() before any
kit module loads (restoring PATH so the real ruflo, git and npm are found),
imports the kit modules dynamically, and runs the probe in
createDisposableMemoryProject()'s git-initialised, daemon-off project, removed
by its cleanup(). A new first assertion requires paths.home to lie under
os.tmpdir(); it failed against the old module head ("not /Users/...").

The test also drops inherited RUFLO_* and CLAUDE_FLOW_* variables: a shell or
Claude Code session in an ak-managed project exports CLAUDE_FLOW_DB_PATH at
the real store and RUFLO_MCP_ENFORCE_POLICY=1, which made Ruflo 3.46.1 fail
closed ("RUFLO_MCP_ENFORCE_POLICY is set but .harness/mcp-policy.json is
missing") in the disposable project.

Run on macOS with Ruflo 3.46.1 (XDG_* unset): 1/1 pass, observed routing
cliToMcp=visible, mcpToCli=not-visible, mcpStore=agentdb-memory.db; the
brief's fingerprint and `ls -la ~/.claude-flow ~/.swarm` identical before
and after; no leftover temp folder or process. The paid qe-court live test
stays manual. installedRoutingVersion() still finds the installed Ruflo
(npm's prefix comes from the Node install, not HOME).
---
 ...-237-238-239-verification-and-decisions.md |  7 +++-
 tests/live/ruflo-memory-routing.test.mjs      | 41 ++++++++++++-------
 2 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index c86fb720..e9e91707 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1253,8 +1253,11 @@ Behavior that differs from, or goes beyond, the plan text.
   - `taskkill` process-tree kills;
   - the `%APPDATA%`, `%LOCALAPPDATA%` and `AppData` tool-folder branch.
 - `tests/live/*`.
-  - The memory-routing test uses the real home folder.
-  - The qe-court test is paid.
+  - The memory-routing test used the real home folder. On `fix/test-hermeticity` it runs in a
+    disposable home and a disposable Git-initialised project, without the caller's inherited
+    Ruflo variables; it passed there on macOS with Ruflo 3.46.1 and left the real state unchanged
+    (brief fingerprint before and after identical).
+  - The qe-court test is paid, so it stays manual.
 - Per-lane browser checks against real data:
   - Live source health and the zero-operations note;
   - host badges and About chips;
diff --git a/tests/live/ruflo-memory-routing.test.mjs b/tests/live/ruflo-memory-routing.test.mjs
index 03e1d4f7..e5113d24 100644
--- a/tests/live/ruflo-memory-routing.test.mjs
+++ b/tests/live/ruflo-memory-routing.test.mjs
@@ -7,29 +7,42 @@
 // so an upgrade that fixes (or changes) the split fails here and forces a human
 // to update the claim. Elsewhere it only reports what was observed and requires
 // that the MCP round trip worked, which is the evidence needed to add a pair.
-import { test } from 'node:test';
+//
+// It runs in a disposable home: sandboxHome() redirects HOME/XDG_*/APPDATA/
+// LOCALAPPDATA before any kit module loads (paths.mjs snapshots the home at
+// module scope), so neither the probe nor the Ruflo it launches reads the real
+// kit.json or writes the real ~/.claude-flow, ~/.swarm or memory stores. The
+// project is createDisposableMemoryProject()'s git-initialised, daemon-off folder.
+import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { probeProjectMemoryRoutes } from '../../src/commands/x/verify.mjs';
-import { projectMemoryEnv } from '../../src/lib/ruflo-memory.mjs';
-import { installedRoutingVersion, memoryRoutingObserved } from '../../src/lib/ruflo-memory-contract.mjs';
-import { run } from '../../src/lib/exec.mjs';
+import { sandboxHome, rmrf } from '../kit/helpers/home-sandbox.mjs';
 
 const hasRuflo = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['ruflo'], { stdio: 'ignore' }).status === 0;
+// sandboxHome() also blanks PATH; the real `ruflo`, `git` and `npm` are needed, so PATH is restored.
+const realPath = process.env.PATH;
+const home = sandboxHome('ak-live-routing');
+process.env.PATH = realPath;
+after(() => rmrf(home));
+// A shell or Claude Code session inside an ak-managed project exports that project's
+// Ruflo settings (CLAUDE_FLOW_DB_PATH at its real store, RUFLO_MCP_ENFORCE_POLICY=1,
+// which makes Ruflo 3.46.1 fail closed without the project's .harness/mcp-policy.json).
+// The disposable project sets its own; nothing is inherited.
+for (const key of Object.keys(process.env)) if (/^(RUFLO_|CLAUDE_FLOW_)/.test(key)) delete process.env[key];
+const paths = await import('../../src/lib/paths.mjs');
+const { probeProjectMemoryRoutes } = await import('../../src/commands/x/verify.mjs');
+const { installedRoutingVersion, memoryRoutingObserved } = await import('../../src/lib/ruflo-memory-contract.mjs');
+const { createDisposableMemoryProject } = await import('./disposable-memory-project.mjs');
 
 test('the real Ruflo CLI and MCP interfaces route project memory as the kit claims', { skip: !hasRuflo && 'ruflo is not on PATH', timeout: 600_000 }, async (t) => {
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-live-routing-'));
-  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
-  const env = projectMemoryEnv(tmp, {
-    RUFLO_DAEMON_AUTOSTART: '0',
-    CLAUDE_FLOW_MEMORY_PATH: path.join(fs.realpathSync(tmp), '.swarm'),
-  });
-  assert.equal((await run('ruflo', ['memory', 'init'], { cwd: tmp, env, timeout: 120_000 })).code, 0, 'ruflo memory init');
+  assert.ok(fs.realpathSync(paths.home).startsWith(fs.realpathSync(os.tmpdir())),
+    `the live probe must run in a disposable home, not ${paths.home}`);
+  const project = await createDisposableMemoryProject({ prefix: 'ak-live-routing-' });
+  t.after(() => project.cleanup());
 
-  const observation = await probeProjectMemoryRoutes(tmp, env, `live-${process.pid}`);
+  const observation = await probeProjectMemoryRoutes(project.root, project.env, `live-${process.pid}`);
   const version = installedRoutingVersion();
   console.log(JSON.stringify({ version, platform: process.platform, observation }));
 

From 7a521b1b5ca7a977ed8f1c39f1fd2979f19727b4 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:46:17 -0700
Subject: [PATCH 11/28] test(ui): check polyglot cards against all-language
 wrapping and run both Maintenance specs in test:ui

The polyglot check failed "0 !== 3" because its harness did not load
maintenance-cards: with a pageerror listener the render throws
"mntProjectKindBadge is not defined" and no card appears. It also still
asserted the retired three-icon cap and "+2 more languages" disclosure
(DDD-09, docs/LANGUAGE-LOGOS.md). The check now loads maintenance-cards
whole (no further stubs needed), fails on any page error, and asserts all
five icons inline, no disclosure, and no horizontal overflow at 390px.

Screenshots from both specs go to .ui-artifacts/ instead of /tmp.
maintenance-focus.mjs and maintenance-guidance.mjs join SUITES.ui; the
runner test pins the full list.
---
 ...-237-238-239-verification-and-decisions.md |  9 ++++--
 scripts/run-tests.mjs                         |  3 +-
 tests/kit/run-tests-runner.test.mjs           |  4 +++
 tests/ui/maintenance-focus.mjs                | 32 ++++++++++++-------
 tests/ui/maintenance-guidance.mjs             |  7 +++-
 5 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index e9e91707..398e1574 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1241,8 +1241,13 @@ Behavior that differs from, or goes beyond, the plan text.
   - M1b is still open.
 - **ADR index.** In `docs/adr/README.md` the index table ends at ADR-0052; later ADRs appear only as
   bullets or sections. This predates the branch.
-- **UI suite outside `test:ui`.** `tests/ui/maintenance-focus.mjs` fails "polyglot cards expose
-  labelled language badges" at `3505a29` too. That file is not part of `test:ui`.
+- **UI suite outside `test:ui`.** Resolved on `fix/test-hermeticity`. The polyglot-card check's
+  harness did not load `maintenance-cards`, so rendering threw `mntProjectKindBadge is not
+  defined` and no card appeared. It also still expected a three-icon cap and a "+2 more languages"
+  disclosure, which DDD-09 (`docs/audits/211-ddd-matrix.md`) and `docs/LANGUAGE-LOGOS.md` removed.
+  The check now loads the module, fails on any page error, and asserts every language icon inline,
+  no disclosure and no horizontal overflow at phone width. `maintenance-focus.mjs` and
+  `maintenance-guidance.mjs` now run in `test:ui`.
 
 #### Not run
 
diff --git a/scripts/run-tests.mjs b/scripts/run-tests.mjs
index 381775aa..43eb888e 100644
--- a/scripts/run-tests.mjs
+++ b/scripts/run-tests.mjs
@@ -25,7 +25,8 @@ export const SUITES = {
     ['tests/ui/dashboard-ui.mjs'],
     ['--test', 'tests/ui/dashboard-project-context.mjs', 'tests/ui/maintenance-projects.mjs',
       'tests/ui/maintenance-host-alignment.mjs', 'tests/ui/intelligence-picker.mjs',
-      'tests/ui/usage-project-groups.mjs', 'tests/ui/context-coverage.mjs', 'tests/ui/host-readiness.mjs'],
+      'tests/ui/usage-project-groups.mjs', 'tests/ui/context-coverage.mjs', 'tests/ui/host-readiness.mjs',
+      'tests/ui/maintenance-focus.mjs', 'tests/ui/maintenance-guidance.mjs'],
   ],
 };
 
diff --git a/tests/kit/run-tests-runner.test.mjs b/tests/kit/run-tests-runner.test.mjs
index e954f3db..21fbeba3 100644
--- a/tests/kit/run-tests-runner.test.mjs
+++ b/tests/kit/run-tests-runner.test.mjs
@@ -76,6 +76,10 @@ test('SUITES keeps the exact commands package.json ran before', async () => {
   assert.deepEqual(SUITES.unit.slice(1).map((a) => a[0]), ['statusline-segments', 'statusline-window-ledger',
     'statusline-brain', 'health-history', 'dashboard', 'admin-model', 'admin'].map((f) => `tests/${f}.test.cjs`));
   assert.equal(SUITES.ui[0][0], 'tests/ui/dashboard-ui.mjs');
+  assert.deepEqual(SUITES.ui[1], ['--test', 'tests/ui/dashboard-project-context.mjs', 'tests/ui/maintenance-projects.mjs',
+    'tests/ui/maintenance-host-alignment.mjs', 'tests/ui/intelligence-picker.mjs', 'tests/ui/usage-project-groups.mjs',
+    'tests/ui/context-coverage.mjs', 'tests/ui/host-readiness.mjs', 'tests/ui/maintenance-focus.mjs',
+    'tests/ui/maintenance-guidance.mjs']);
   const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
   assert.equal(pkg.scripts.test, 'node scripts/run-tests.mjs unit');
   assert.equal(pkg.scripts['test:ui'], 'node scripts/run-tests.mjs ui');
diff --git a/tests/ui/maintenance-focus.mjs b/tests/ui/maintenance-focus.mjs
index 0fcdf981..384ef044 100644
--- a/tests/ui/maintenance-focus.mjs
+++ b/tests/ui/maintenance-focus.mjs
@@ -2,6 +2,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
@@ -9,6 +11,7 @@ import { baseInventory } from '../fixtures/maintenance/management-fixtures.mjs';
 import { runInventoryQuery } from '../../src/lib/maintenance/management/query.mjs';
 import { inspectorFor } from '../../src/lib/maintenance/management/guidance.mjs';
 import { publicInventoryPage, publicInspector } from '../../src/lib/dashboard/maintenance-api.mjs';
+const SHOTS=path.join(path.dirname(fileURLToPath(import.meta.url)),'..','..','.ui-artifacts');
 function source(name){return fs.readFileSync(new URL('../../src/lib/dashboard/client/'+name+'.mjs',import.meta.url),'utf8').replace(/^import\s[\s\S]*?from ['"][^'"]+['"];\s*$/gm,'').replace(/\bexport (?=(?:function|var)\b)/g,'');}
 test('focus browser progressively narrows to exact installations and preserves filters through relationships',async(t)=>{
  const inventory=structuredClone(baseInventory()),requests=[],errors=[];
@@ -68,7 +71,8 @@ test('focus browser progressively narrows to exact installations and preserves f
  assert.equal(await page.evaluate(()=>globalThis.MNT.scope),'user');
  await page.locator('#mnt-related-back').click();
  await page.locator('#mnt-inspector-title').waitFor();
- await page.screenshot({path:'/tmp/ak-focus-implemented-desktop.png',fullPage:true});
+ fs.mkdirSync(SHOTS,{recursive:true});
+ await page.screenshot({path:path.join(SHOTS,'focus-implemented-desktop.png'),fullPage:true});
  await page.setViewportSize({width:390,height:844});
  assert.equal(await page.locator('#mnt-inspector').evaluate(el=>globalThis.getComputedStyle(el).position),'static');
  assert.equal(await page.evaluate(()=>globalThis.document.documentElement.scrollWidth<=globalThis.innerWidth),true);
@@ -77,24 +81,30 @@ test('focus browser progressively narrows to exact installations and preserves f
  await page.locator('[data-mnt-focus="user"]').waitFor();
  await page.locator('[data-mnt-focus="system"]').focus();await page.keyboard.press('ArrowDown');
  assert.equal(await page.locator('[data-mnt-focus="machine"]').evaluate(el=>el===globalThis.document.activeElement),true);
- await page.screenshot({path:'/tmp/ak-focus-implemented-mobile.png',fullPage:true});
+ await page.screenshot({path:path.join(SHOTS,'focus-implemented-mobile.png'),fullPage:true});
  assert.deepEqual(errors,[]);
 });
 
-test('polyglot cards expose labelled language badges and an accessible disclosure',async(t)=>{
+test('polyglot cards show every language as a labelled, wrapping icon with no disclosure',async(t)=>{
  const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1100,height:650}});
- const languages=[['rust','Rust','Rs'],['typescript','TypeScript','TS'],['javascript','JavaScript','JS'],['python','Python','Py'],['java','Java','Jv']].map(([id,name,icon])=>({id,name,icon,evidence:'source'}));
+ const errors=[];page.on('pageerror',e=>errors.push(e.message));
+ const languages=[['rust','Rust'],['typescript','TypeScript'],['javascript','JavaScript'],['python','Python'],['java','Java']].map(([id,name])=>({id,name,evidence:'source'}));
  const state={facets:{},query:{navigation:{level:'project',nodes:[{value:'prj_example',label:'billing-service',count:24,projectKind:'git',languages}]},groups:[]}};
  await page.setContent('<!doctype html><html data-theme="dark"><head><style>'+CSS+'</style></head><body><main style="padding:32px"><h2>Projects</h2><div id="cards"></div></main></body></html>');
- await page.addScriptTag({content:'var MNT='+JSON.stringify(state)+';var MNT_SCOPE_LABELS={};function esc(s){return String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;");}function mntKindLabel(s){return s;}function mntFacetValueLabel(_,s){return s;}function mntIcon(){return "";}function mntAvailableTo(){return "";}\n'+source('maintenance-language-logos')+'\n'+source('maintenance-focus')+'\ndocument.getElementById("cards").innerHTML=renderMntFocusResults(false);'});
- assert.equal(await page.locator('.mnt-language-icon:visible').count(),3);
- await page.getByText('+2 more languages',{exact:true}).focus();
- await page.keyboard.press('Enter');
+ await page.addScriptTag({content:'var MNT='+JSON.stringify(state)+';var MNT_SCOPE_LABELS={};function esc(s){return String(s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;");}function mntKindLabel(s){return s;}function mntFacetValueLabel(_,s){return s;}function mntIcon(){return "";}function mntAvailableTo(){return "";}\n'
+  +source('maintenance-language-logos')+'\n'+source('maintenance-cards')+'\n'+source('maintenance-focus')
+  +'\ndocument.getElementById("cards").innerHTML=renderMntFocusResults(false);'});
+ assert.deepEqual(errors,[]);
  assert.equal(await page.locator('.mnt-language-icon:visible').count(),5);
- assert.equal(await page.getByRole('img', { name: 'Python — Source language detected', exact: true }).isVisible(),true);
- await page.screenshot({path:'/tmp/ak-polyglot-projects-svg.png'});
+ assert.equal(await page.locator('.mnt-language-more').count(),0);
+ assert.equal(await page.getByText(/more languages/).count(),0);
+ assert.equal(await page.getByRole('img',{name:'Python — Source language detected',exact:true}).isVisible(),true);
+ fs.mkdirSync(SHOTS,{recursive:true});
+ await page.screenshot({path:path.join(SHOTS,'polyglot-projects-svg.png')});
  await page.emulateMedia({colorScheme:'light'});
  await page.locator('html').evaluate(el=>el.setAttribute('data-theme','light'));
- await page.screenshot({path:'/tmp/ak-polyglot-projects-svg-light.png'});
+ await page.screenshot({path:path.join(SHOTS,'polyglot-projects-svg-light.png')});
+ await page.setViewportSize({width:390,height:844});
+ assert.equal(await page.evaluate(()=>globalThis.document.documentElement.scrollWidth>globalThis.innerWidth),false,'icons wrap instead of overflowing');
 });
diff --git a/tests/ui/maintenance-guidance.mjs b/tests/ui/maintenance-guidance.mjs
index 63cdffbb..2c0357be 100644
--- a/tests/ui/maintenance-guidance.mjs
+++ b/tests/ui/maintenance-guidance.mjs
@@ -2,10 +2,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
 
+const SHOTS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.ui-artifacts');
+
 function source(name) {
   return fs.readFileSync(new URL('../../src/lib/dashboard/client/'+name+'.mjs', import.meta.url), 'utf8')
     .replace(/^import\s[\s\S]*?from ['"][^'"]+['"];\s*$/gm, '')
@@ -47,6 +51,7 @@ test('guidance has exclusive pills, host context, and no resource selector or op
   assert.match(await page.locator('#optional-test').innerText(), /Optional actions/);
   assert.equal(await page.locator('#optional-test [data-mnt-plan-gid="optional"]').count(), 1);
   assert.equal(await page.locator('#optional-test .mnt-dispositions').count(), 0);
-  await page.screenshot({ path: '/tmp/ak-guidance-current.png' });
+  fs.mkdirSync(SHOTS, { recursive: true });
+  await page.screenshot({ path: path.join(SHOTS, 'guidance-current.png') });
   assert.deepEqual(errors, []);
 });

From 3a6dcf28d8d05e1b9ebb8a88cec753643dd6a73f Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 09:51:00 -0700
Subject: [PATCH 12/28] fix(dashboard): keep a closing health dialog from
 pulling focus off the next badge

The dialog's `close` event is a queued task. Its handler focused the badge
that opened the dialog unconditionally, so when focus had already moved on
(the UI spec's Escape, then focus the next badge, then Enter), a late
close event pulled focus back and Enter reopened the previous host. That
is the host-readiness flake: under 8-way parallel load the unchanged spec
failed 3 of 32 runs with the previous host's title, e.g.
'Claude Code health' !== 'Codex health'.

The handler now returns focus only when focus is still in the dialog or
on the body. A new check closes the dialog and focuses another badge in
one task, then awaits the close event itself (no timer): it failed
'claude' !== 'codex' before the fix and passes after. The per-host loop
now waits for the open dialog's title and for the closed dialog with the
badge focused, as conditions. Screenshots go to .ui-artifacts/.

After: 20/20 serial runs and 24/24 runs under 8-way parallel load pass.
---
 src/lib/dashboard/client/host-readiness.mjs |  9 ++++-
 tests/ui/host-readiness.mjs                 | 45 ++++++++++++++++++---
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/src/lib/dashboard/client/host-readiness.mjs b/src/lib/dashboard/client/host-readiness.mjs
index 6e2d5501..c05aef0b 100644
--- a/src/lib/dashboard/client/host-readiness.mjs
+++ b/src/lib/dashboard/client/host-readiness.mjs
@@ -166,7 +166,14 @@ export function wireHostHealth(){
     document.getElementById('host-health-message').textContent='';renderHealthDialog();dialog.showModal();
   });
   document.getElementById('host-health-close').addEventListener('click',function(){dialog.close();});
-  dialog.addEventListener('close',function(){var button=region.querySelector('[data-health-host="'+HEALTH_HOST+'"]');if(button)button.focus();});
+  // Return focus to the badge that opened the dialog, but only while focus is
+  // still in the dialog or nowhere. `close` is a queued task: a fast keyboard
+  // sequence may already have moved focus to another badge.
+  dialog.addEventListener('close',function(){
+    var active=document.activeElement;
+    if(active&&active!==document.body&&!dialog.contains(active))return;
+    var button=region.querySelector('[data-health-host="'+HEALTH_HOST+'"]');if(button)button.focus();
+  });
   document.getElementById('host-health-consent').addEventListener('change',function(event){HEALTH_ACK=event.target.checked&&healthRow()?healthRow().evidenceKey:null;renderHealthDialog();});
   document.getElementById('host-health-refresh').addEventListener('click',function(){runHealthCheck(false);});
   document.getElementById('host-health-connect').addEventListener('click',function(){runHealthCheck(true);});
diff --git a/tests/ui/host-readiness.mjs b/tests/ui/host-readiness.mjs
index 896f36c4..10c600aa 100644
--- a/tests/ui/host-readiness.mjs
+++ b/tests/ui/host-readiness.mjs
@@ -1,10 +1,14 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { chromium } from 'playwright';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { esc } from '../../src/lib/dashboard/groups.mjs';
 
+const SHOTS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.ui-artifacts');
+fs.mkdirSync(SHOTS, { recursive: true });
 const source = name => fs.readFileSync(new URL('../../src/lib/dashboard/client/'+name+'.mjs', import.meta.url), 'utf8')
   .replace(/^import\s[\s\S]*?from ['"][^'"]+['"];\s*$/gm, '')
   .replace(/\bexport (?=(?:function|var)\b)/g, '');
@@ -45,12 +49,14 @@ test('all hosts have qualified OK, accessible details and explicitly confirmed c
     const badge=page.locator('[data-health-host="'+host+'"]');
     assert.equal(await badge.innerText(),'OK');
     await badge.focus();await page.keyboard.press('Enter');
-    assert.equal(await page.locator('#host-health-title').innerText(),name+' health');
+    await page.waitForFunction(n=>globalThis.document.getElementById('host-health-dialog').open
+      &&globalThis.document.getElementById('host-health-title').textContent===n+' health',name);
     assert.match(await page.locator('#host-health-summary').innerText(),/OK · Local checks/);
     assert.equal(await page.locator('#host-health-checks li').count(),5);
     assert.equal(await page.locator('#host-health-connect').isDisabled(),true);
     await page.keyboard.press('Escape');
-    assert.equal(await badge.evaluate(el=>el===globalThis.document.activeElement),true);
+    await page.waitForFunction(h=>!globalThis.document.getElementById('host-health-dialog').open
+      &&globalThis.document.activeElement===globalThis.document.querySelector('[data-health-host="'+h+'"]'),host);
   }
   assert.equal(requests.length,0);
   await page.locator('[data-health-host="opencode"]').click();
@@ -64,10 +70,10 @@ test('all hosts have qualified OK, accessible details and explicitly confirmed c
   assert.deepEqual(requests[0].body,{host:'opencode',confirm:true,evidenceKey:'a'.repeat(64)});
   assert.equal(await page.locator('#host-health-consent').isChecked(),false);
   assert.match(await page.locator('#host-health-integrations').innerText(),/Optional MCP tool connections are not tested/);
-  await page.screenshot({path:'/tmp/ak-health-details-desktop.png',animations:'disabled'});
+  await page.screenshot({path:path.join(SHOTS,'health-details-desktop.png'),animations:'disabled'});
   await page.setViewportSize({width:390,height:844});
   assert.equal(await page.evaluate(()=>globalThis.document.documentElement.scrollWidth>globalThis.innerWidth),false);
-  await page.screenshot({path:'/tmp/ak-health-details-mobile.png',animations:'disabled'});
+  await page.screenshot({path:path.join(SHOTS,'health-details-mobile.png'),animations:'disabled'});
   await page.keyboard.press('Escape');
   await page.evaluate(()=>{
     globalThis.renderSourceHealth({codex:{status:'degraded',reason:'parse-yield-partial'},codexLedger:{status:'ok'}});
@@ -181,6 +187,35 @@ test('unmanaged hosts read their management state everywhere, with information-o
   await page.setViewportSize({width:390,height:844});
   await page.evaluate(data=>globalThis.renderHostReadiness(data),unmanagedReport());
   assert.equal(await page.evaluate(()=>globalThis.document.documentElement.scrollWidth>globalThis.innerWidth),false);
-  await page.screenshot({path:'/tmp/ak-health-unmanaged-mobile.png',animations:'disabled'});
+  await page.screenshot({path:path.join(SHOTS,'health-unmanaged-mobile.png'),animations:'disabled'});
   assert.equal(errors.length,0,errors.join('\n'));
 });
+
+test('a dialog close that lands after the user moved on does not steal focus back', async t => {
+  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  t.after(() => browser.close());
+  const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
+  const errors = [];
+  page.on('pageerror', error => errors.push(error.message));
+  await page.route('http://health.test/**', route => route.fulfill({ contentType: 'text/html',
+    body: renderPage({ name: 'Health fixture', version: 'test' }).replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '') }));
+  await page.goto('http://health.test/');
+  await page.addScriptTag({ content: `${esc.toString()}\nfunction authHeaders(){return {};}\n${source('usage')}\n${source('host-readiness')}\nwireHostHealth();` });
+  await page.evaluate(data => globalThis.renderHostReadiness(data), report());
+  await page.locator('[data-health-host="claude"]').click();
+  // The race, made deterministic: close the dialog and move focus in the SAME
+  // task, then wait for the queued `close` event itself. This listener is added
+  // after wireHostHealth's, so it runs after the product handler has acted.
+  const focused = await page.evaluate(async () => {
+    const dialog = globalThis.document.getElementById('host-health-dialog');
+    const next = globalThis.document.querySelector('[data-health-host="codex"]');
+    const closeEvent = new Promise(resolve => dialog.addEventListener('close', resolve, { once: true }));
+    dialog.close();
+    next.focus();
+    await closeEvent;
+    const active = globalThis.document.activeElement;
+    return active && active.getAttribute('data-health-host');
+  });
+  assert.equal(focused, 'codex');
+  assert.deepEqual(errors, []);
+});

From d072444513e99e0a8f39f9a811d2be05468f698e Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:13:01 -0700
Subject: [PATCH 13/28] fix(maintenance): mark the results list busy while an
 inventory query runs

MNT-UX-007 failed once on CI ("arrow keys did not move the roving tab
stop"): after Clear all, the check focused a row and pressed ArrowDown
while the Clear all query could still be in flight, so its response could
re-render the rows between the key press and the tabindex read.

#mnt-results now carries aria-busy from mntInventoryBusy, set in
renderMntResults (the element is never replaced, and every busy
transition renders). The UI spec holds the next inventory response,
checks aria-busy="true" while held (MNT-UX-007a), releases it, waits for
aria-busy="false", checks Clear all issued exactly one query
(MNT-UX-007b), and waits for the second row to take focus before reading
tab indexes.

Before: "MNT-UX-007a ... aria-busy read null", then a 30 s wait timeout.
After: 495 passed, 0 failed; 10/10 serial runs pass.
---
 .../client/maintenance-inventory.mjs          |  3 +++
 tests/ui/dashboard-ui.mjs                     | 21 +++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/src/lib/dashboard/client/maintenance-inventory.mjs b/src/lib/dashboard/client/maintenance-inventory.mjs
index c7dc7477..3b34ae03 100644
--- a/src/lib/dashboard/client/maintenance-inventory.mjs
+++ b/src/lib/dashboard/client/maintenance-inventory.mjs
@@ -128,6 +128,9 @@ import { mntOpenInspector, mntCloseInspector } from './maintenance-inspector.mjs
 
   function renderMntResults(){
     var el=document.getElementById("mnt-results");if(!el)return;
+    // Busy while a query is in flight: assistive technology (and a test) can
+    // tell the rows on screen are about to be replaced.
+    el.setAttribute("aria-busy",mntInventoryBusy?"true":"false");
     if(mntInventoryError){
       el.innerHTML='<div class="mnt-empty">Inventory could not be read. <button type="button" class="mt-action" id="mnt-retry">Retry</button></div>';
       return;
diff --git a/tests/ui/dashboard-ui.mjs b/tests/ui/dashboard-ui.mjs
index 5001744a..827192b3 100644
--- a/tests/ui/dashboard-ui.mjs
+++ b/tests/ui/dashboard-ui.mjs
@@ -1409,6 +1409,9 @@ async function main() {
   // incomplete-source fixture) so later requests see the new fixture without
   // a full page reload. ──
   let activeMaintenanceInventory = SENTINEL_FIXTURES.base();
+  // Holds the NEXT inventory response until released, so a check can order
+  // "focus a row" before "the list re-renders" on every run instead of by luck.
+  let holdNextInventory = null;
   // Simulates dashboard-server.mjs's refreshInventoryAfterProviderScan: the
   // server builds the inventory once Refresh evidence settles (MNT-DSC's
   // scanRequired contract), not only after a System full scan.
@@ -1479,6 +1482,7 @@ async function main() {
     const body = request.method() === 'POST' ? request.postDataJSON() : null;
 
     if (request.method() === 'GET' && pathname === '/api/maintenance/v2/inventory') {
+      if (holdNextInventory) { const gate = holdNextInventory; holdNextInventory = null; await gate; }
       const facets = {};
       for (const [key, value] of url.searchParams.entries()) {
         if (key.startsWith('facet.')) facets[key.slice(6)] = [...(facets[key.slice(6)] ?? []), value];
@@ -2398,8 +2402,21 @@ async function main() {
     await page.waitForFunction(() => document.querySelectorAll('#mnt-chips .mnt-chip').length === 0);
     await page.check('#mnt-facets input[data-mnt-facet="kind"][value="skill"]');
     await page.waitForSelector('#mnt-chips .mnt-chip');
+    const requestsBefore = maintenanceInventoryRequests.length;
+    let releaseInventory;
+    holdNextInventory = new Promise((resolve) => { releaseInventory = resolve; });
     await page.click('#mnt-clear-all');
     await page.waitForFunction(() => document.querySelectorAll('#mnt-chips .mnt-chip').length === 0);
+    const busyWhileHeld = await page.getAttribute('#mnt-results', 'aria-busy');
+    check('MNT-UX-007a: the results list is marked busy while its query is in flight',
+      busyWhileHeld === 'true', `aria-busy read ${JSON.stringify(busyWhileHeld)}`);
+    releaseInventory();
+    await page.waitForFunction(() => document.getElementById('mnt-results')?.getAttribute('aria-busy') === 'false');
+    // The gate holds only the NEXT request; if Clear all ever issues two, the
+    // unheld one could render first and make this check meaningless.
+    check('MNT-UX-007b: Clear all issues exactly one inventory query',
+      maintenanceInventoryRequests.length === requestsBefore + 1,
+      `inventory requests grew by ${maintenanceInventoryRequests.length - requestsBefore}`);
     check('MNT-UX-002: Clear all removes every active facet at once',
       (await page.evaluate(() => location.hash)).indexOf('facet.') < 0,
       'Clear all left a facet value in the URL');
@@ -2409,6 +2426,10 @@ async function main() {
     const rovingBefore = await page.$$eval('#mnt-results [data-mnt-plc]',
       (rows) => rows.map((row) => row.tabIndex));
     await page.keyboard.press('ArrowDown');
+    await page.waitForFunction(() => {
+      const rows = [...document.querySelectorAll('#mnt-results [data-mnt-plc]')];
+      return rows.length > 1 && document.activeElement === rows[1];
+    });
     const rovingAfter = await page.$$eval('#mnt-results [data-mnt-plc]',
       (rows) => rows.map((row) => row.tabIndex));
     check('MNT-UX-007: arrow keys move the roving tab stop without adding every row to the Tab order',

From fdbdefddec0bc6e0b6061cf9454b41a8fdd8a3ff Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:13:06 -0700
Subject: [PATCH 14/28] docs(audit): record Branch 2 hermeticity fixes

Mark the spawn-test XDG_* inheritance (Task 2.1) and the review-deferred temp-folder and enclosing-repository writes (Tasks 2.3-2.5) as fixed on fix/test-hermeticity.
---
 ...09-26-issues-237-238-239-verification-and-decisions.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 398e1574..93c008a7 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -920,7 +920,9 @@ changed in this wave:
 - Stopping the whole process tree on an abort. It needs Windows CI to prove; only the comment was
   corrected.
 - Tests that leave temporary folders behind, and pre-existing tests that write into an enclosing
-  repository when `TMPDIR` is inside one. Both belong to the test-hermeticity branch.
+  repository when `TMPDIR` is inside one. Both belong to the test-hermeticity branch. Fixed there:
+  tests remove their temporary folders, the suite runner fails on leftovers and refuses a temp root
+  inside a repository, and the two writers skip when they cannot leave a repository.
 - A worktree `.claude` modification time that changed during the review. It came from concurrent
   runs, and no user state changed.
 
@@ -1237,7 +1239,9 @@ Behavior that differs from, or goes beyond, the plan text.
 - **Usage.**
   - The Claude statusLine classifier does not read managed settings.
   - A shell wrapper around the footer helper is classed as `custom`.
-  - Other spawn tests still inherit the developer's `XDG_*` variables.
+  - Other spawn tests inherited the developer's `XDG_*` variables. Fixed on `fix/test-hermeticity`:
+    spawned children get `spawnEnv(home)`, and a guard test fails on any spawn that neither uses it
+    nor states why it inherits.
   - M1b is still open.
 - **ADR index.** In `docs/adr/README.md` the index table ends at ADR-0052; later ADRs appear only as
   bullets or sections. This predates the branch.

From 8b17dd07ae1109f19eb665dbcd4994048fbd788b Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:23:21 -0700
Subject: [PATCH 15/28] test(opencode): keep the three in-process tests out of
 the real config base

integration-command-facts, opencode and provider-credentials still started the
real `opencode` with the developer's XDG_CONFIG_HOME (APPDATA on Windows), and
each run created <config>/opencode there. redirectToolState() now moves the
config base into its temporary folder along with state, data, cache and temp.

opencode-state-hermeticity.test.mjs watches a config folder as well, and a new
deterministic check asserts that redirectToolState() places every tool base,
config included, inside its base and restores them all, so the fix holds on a
machine without opencode installed.
---
 tests/kit/helpers/home-sandbox.mjs            | 11 ++++--
 tests/kit/opencode-state-hermeticity.test.mjs | 36 +++++++++++++++----
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/tests/kit/helpers/home-sandbox.mjs b/tests/kit/helpers/home-sandbox.mjs
index e964c160..86e55e37 100644
--- a/tests/kit/helpers/home-sandbox.mjs
+++ b/tests/kit/helpers/home-sandbox.mjs
@@ -67,18 +67,23 @@ export function spawnEnv(home, extra = {}) {
 
 /**
  * For in-process tests whose code under test spawns tools with process.env:
- * point XDG state/data/cache, LOCALAPPDATA and TMPDIR/TEMP/TMP at a fresh folder
- * under os.tmpdir(); restore() puts the old values back and removes it.
+ * point the config base (XDG_CONFIG_HOME, and APPDATA on Windows), XDG
+ * state/data/cache, LOCALAPPDATA and TMPDIR/TEMP/TMP at a fresh folder under
+ * os.tmpdir(); restore() puts the old values back and removes it. OpenCode
+ * creates <config>/opencode on start, so the config base must move too.
  * @param {string} prefix
  * @returns {{ base: string, restore: () => void }}
  */
 export function redirectToolState(prefix) {
   const base = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-tools-`)));
-  const keys = ['XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP'];
+  const keys = ['XDG_CONFIG_HOME', 'APPDATA', 'XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'LOCALAPPDATA',
+    'TMPDIR', 'TEMP', 'TMP'];
   const previous = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
   const tmp = path.join(base, 'tmp');
   fs.mkdirSync(tmp);
+  const cfg = path.join(base, 'config');
   Object.assign(process.env, {
+    XDG_CONFIG_HOME: cfg, APPDATA: cfg,
     XDG_STATE_HOME: path.join(base, 'state'), XDG_DATA_HOME: path.join(base, 'data'),
     XDG_CACHE_HOME: path.join(base, 'cache'), LOCALAPPDATA: path.join(base, 'localappdata'),
     TMPDIR: tmp, TEMP: tmp, TMP: tmp,
diff --git a/tests/kit/opencode-state-hermeticity.test.mjs b/tests/kit/opencode-state-hermeticity.test.mjs
index 3e5f2df3..2e522fda 100644
--- a/tests/kit/opencode-state-hermeticity.test.mjs
+++ b/tests/kit/opencode-state-hermeticity.test.mjs
@@ -1,9 +1,10 @@
 // tests/kit/opencode-state-hermeticity.test.mjs
 // Six test files created OpenCode's own folders under the developer's
-// XDG_STATE_HOME/XDG_CACHE_HOME/XDG_DATA_HOME and TMPDIR (per-file probe,
-// Branch 2 plan). Runs the three in-process ones with those bases pointed at a
-// watched folder and requires the folder to stay empty. The three direct-spawn
-// files are covered by spawn-env-guard.test.mjs.
+// XDG_CONFIG_HOME/XDG_STATE_HOME/XDG_CACHE_HOME/XDG_DATA_HOME and TMPDIR
+// (per-file probe, Branch 2 plan). Runs the three in-process ones with those
+// bases (and APPDATA, the Windows config base) pointed at a watched folder and
+// requires the folder to stay empty. The three direct-spawn files are covered
+// by spawn-env-guard.test.mjs.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
@@ -11,16 +12,39 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { redirectToolState } from './helpers/home-sandbox.mjs';
 
 const KIT = path.dirname(fileURLToPath(import.meta.url));
 const IN_PROCESS = ['integration-command-facts', 'opencode', 'provider-credentials'];
+const WATCHED = ['cfg', 'state', 'data', 'cache', 'tmp'];
+const TOOL_BASES = ['XDG_CONFIG_HOME', 'APPDATA', 'XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME',
+  'LOCALAPPDATA', 'TMPDIR', 'TEMP', 'TMP'];
+
+// Deterministic half: holds without opencode installed. OpenCode creates
+// <config>/opencode on start, so the config bases must move with the others.
+test('redirectToolState points every tool base, config included, inside its base', () => {
+  const previous = Object.fromEntries(TOOL_BASES.map((key) => [key, process.env[key]]));
+  const toolState = redirectToolState('ak-oc-keys');
+  let seen;
+  try {
+    seen = Object.fromEntries(TOOL_BASES.map((key) => [key, process.env[key]]));
+  } finally {
+    toolState.restore();
+  }
+  for (const key of TOOL_BASES) {
+    assert.ok(seen[key]?.startsWith(toolState.base + path.sep), `${key}=${seen[key]} is outside ${toolState.base}`);
+    assert.equal(process.env[key], previous[key], `${key} was not restored`);
+  }
+  assert.equal(fs.existsSync(toolState.base), false);
+});
 
 for (const name of IN_PROCESS) {
   test(`${name}.test.mjs leaves the inherited tool-state bases untouched`, { timeout: 300_000 }, (t) => {
     const watched = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-oc-watch-')));
     t.after(() => fs.rmSync(watched, { recursive: true, force: true }));
-    for (const d of ['state', 'data', 'cache', 'tmp']) fs.mkdirSync(path.join(watched, d));
+    for (const d of WATCHED) fs.mkdirSync(path.join(watched, d));
     const env = { ...process.env, // spawn-env: inherits (this test measures exactly what an inheriting run leaks)
+      XDG_CONFIG_HOME: path.join(watched, 'cfg'), APPDATA: path.join(watched, 'cfg'),
       XDG_STATE_HOME: path.join(watched, 'state'), XDG_DATA_HOME: path.join(watched, 'data'),
       XDG_CACHE_HOME: path.join(watched, 'cache'), TMPDIR: path.join(watched, 'tmp'),
       TEMP: path.join(watched, 'tmp'), TMP: path.join(watched, 'tmp') };
@@ -31,7 +55,7 @@ for (const name of IN_PROCESS) {
       { encoding: 'utf8', env });
     assert.equal(r.status, 0, r.stdout + r.stderr);
     assert.match(r.stdout, /^# pass [1-9]/m, `the nested run executed no test:\n${r.stdout}`);
-    const leaked = ['state', 'data', 'cache', 'tmp'].flatMap((d) => fs.readdirSync(path.join(watched, d))
+    const leaked = WATCHED.flatMap((d) => fs.readdirSync(path.join(watched, d))
       .filter((n) => n !== 'node-compile-cache').map((n) => `${d}/${n}`));
     assert.deepEqual(leaked, []);
   });

From 5befab065fcf7f394a243d80102a56c1fc2018ad Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:23:58 -0700
Subject: [PATCH 16/28] docs(maintainer): describe the guarded test runner and
 isolation helpers

MAINTAINER.md section 4 still described test isolation as two halves. It now
covers scripts/run-tests.mjs (real-state fingerprint, the ak-suite temp root,
exit codes 2/3/4, concurrent writers and AK_TRIPWIRE_STRICT, the exec mode) and
the helpers tests use: sandboxHome(), spawnEnv(), redirectToolState(), tempDir()
and isolateProject(). AGENTS.md keeps the exact list of watched paths.
---
 MAINTAINER.md | 48 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/MAINTAINER.md b/MAINTAINER.md
index 111f3868..291fa999 100644
--- a/MAINTAINER.md
+++ b/MAINTAINER.md
@@ -244,16 +244,44 @@ pnpm run lint:links:internal # requires lychee
 
 Run one suite while iterating: `node --test tests/kit/versions.test.mjs`.
 
-Test isolation has two halves. `sandboxHome()` (`tests/kit/helpers/home-sandbox.mjs`)
-redirects every home-relative path. Commands also write relative to the current
-directory, so any test file that calls `sync.run`, `setup.run*` or `uninstall.run` must
-call `isolateProject()` (`tests/kit/helpers/project-isolation.mjs`) once at module scope.
-It moves the file into a throwaway project and fails the file if the real repository's
-`.claude/settings.local.json`, `.claude/helpers/statusline.cjs`, `CLAUDE.md`, `AGENTS.md`
-(and a few other project files, or their `.ak-*`/`.agentic-kit-*` siblings) change.
-`tests/kit/project-isolation.test.mjs` fails when a new test file skips it. A live Claude
-Code or Ruflo session that edits those files in the same checkout during `pnpm test`
-also trips the guard; rerun with the session idle.
+`pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`, a guard around the
+suite. It fingerprints real user state (ak's config and state folders, the host guidance files
+ak manages, and this repository's `.claude`, `.swarm`, `.agentic-qe`, `.claude-flow` and
+`.harness`) before and after the run, and points `TMPDIR`/`TEMP`/`TMP` at a fresh
+`ak-suite-*` folder. Its exit code tells you what went wrong:
+
+| Exit | Meaning |
+| ---- | ------- |
+| the failing command's code | a test command failed (the after-check still runs) |
+| 2 | the `ak-suite-*` folder is inside a git repository; point `TMPDIR` elsewhere |
+| 3 | real user state changed; the changed paths are listed |
+| 4 | the run left temporary folders behind; they are listed |
+
+Files a live Claude Code, Ruflo or AQE session writes during the run are listed as
+concurrent writers and do not fail a local run; CI, or `AK_TRIPWIRE_STRICT=1`, fails on
+them too. Guard a single command the same way with
+`node scripts/run-tests.mjs exec -- <node args>`.
+
+Inside the suite, isolation comes from shared helpers:
+
+- `sandboxHome()` (`tests/kit/helpers/home-sandbox.mjs`) redirects every home-relative
+  path for tests that run machine-mutating commands in process.
+- `spawnEnv()` (same file) builds the environment for every spawned child, with all
+  per-user bases inside a sandbox home. `tests/kit/spawn-env-guard.test.mjs` fails on a
+  spawn that inherits `process.env` without a marked reason.
+- `redirectToolState()` (same file) moves the config, state, data, cache and temp bases for
+  in-process tests whose code under test spawns real tools such as OpenCode.
+- `tempDir()` (`tests/kit/helpers/temp-dir.mjs`) makes temporary folders that are removed
+  when the test (or the file) finishes.
+- `isolateProject()` (`tests/kit/helpers/project-isolation.mjs`) covers commands that write
+  relative to the current directory: any test file that calls `sync.run`, `setup.run*` or
+  `uninstall.run` calls it once at module scope. It moves the file into a throwaway project
+  and fails the file if the real repository's project files change.
+  `tests/kit/project-isolation.test.mjs` fails when a new test file skips it. A live Claude
+  Code or Ruflo session that edits those files in the same checkout also trips this guard;
+  rerun with the session idle.
+
+[AGENTS.md](AGENTS.md#testing) has the exact list of watched paths.
 
 CI additionally runs a **CLI smoke** against a sandboxed `HOME` (see `ci.yml`):
 `--version`, `--help --all`, `status --json` (asserts valid JSON + `overall`),

From 6bbf2db99cbc9e960a6d99f9ea00ffc26d649fb8 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:26:32 -0700
Subject: [PATCH 17/28] test(opencode): say the tool-state redirect covers the
 config base too

The comment above each redirectToolState() call listed state/data/cache/temp only; the helper now also moves XDG_CONFIG_HOME and APPDATA.
---
 tests/kit/integration-command-facts.test.mjs | 2 +-
 tests/kit/opencode.test.mjs                  | 2 +-
 tests/kit/provider-credentials.test.mjs      | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/kit/integration-command-facts.test.mjs b/tests/kit/integration-command-facts.test.mjs
index cdce91be..366284bd 100644
--- a/tests/kit/integration-command-facts.test.mjs
+++ b/tests/kit/integration-command-facts.test.mjs
@@ -5,7 +5,7 @@ import { HOST_REGISTRY } from '../../src/lib/adapters/index.mjs';
 import { redirectToolState } from './helpers/home-sandbox.mjs';
 
 // Code under test spawns the real `opencode` with process.env; keep its
-// state/data/cache/temp folders out of the developer's real ones.
+// config/state/data/cache/temp folders out of the developer's real ones.
 const toolState = redirectToolState('ak-integration-command-facts');
 after(() => toolState.restore());
 
diff --git a/tests/kit/opencode.test.mjs b/tests/kit/opencode.test.mjs
index 4b68e4f4..c32b642e 100644
--- a/tests/kit/opencode.test.mjs
+++ b/tests/kit/opencode.test.mjs
@@ -16,7 +16,7 @@ import { guidanceTargets, BUILTIN_BLOCKS } from '../../src/lib/blocks.mjs';
 import { redirectToolState } from './helpers/home-sandbox.mjs';
 
 // Code under test spawns the real `opencode` with process.env; keep its
-// state/data/cache/temp folders out of the developer's real ones.
+// config/state/data/cache/temp folders out of the developer's real ones.
 const toolState = redirectToolState('ak-opencode');
 after(() => toolState.restore());
 
diff --git a/tests/kit/provider-credentials.test.mjs b/tests/kit/provider-credentials.test.mjs
index 2243d271..619d45f3 100644
--- a/tests/kit/provider-credentials.test.mjs
+++ b/tests/kit/provider-credentials.test.mjs
@@ -20,7 +20,7 @@ import {
 import { redirectToolState } from './helpers/home-sandbox.mjs';
 
 // Code under test spawns the real `opencode` with process.env; keep its
-// state/data/cache/temp folders out of the developer's real ones.
+// config/state/data/cache/temp folders out of the developer's real ones.
 const toolState = redirectToolState('ak-provider-credentials');
 after(() => toolState.restore());
 

From 55b92c8d84149be935343c629f29ec19bfd56a2d Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:47:34 -0700
Subject: [PATCH 18/28] fix(tripwire): watch the host and repo-root files ak
 writes and say what stays unwatched

The tripwire now fingerprints ~/.claude/settings.json, ~/.claude.json,
~/.codex/config.toml and the repository's root CLAUDE.md, AGENTS.md and
.mcp.json alongside the guidance files it already covered. ~/.claude.json is
a developer-mode concurrent writer because Claude Code rewrites it during
every session; strict mode still fails on it. The header, AGENTS.md and
MAINTAINER.md now list the watched paths and name the tool paths left to
spawnEnv().
---
 AGENTS.md                              | 16 +++++++-----
 MAINTAINER.md                          |  7 ++---
 scripts/real-state-tripwire.mjs        | 35 +++++++++++++++++++------
 tests/kit/real-state-tripwire.test.mjs | 36 +++++++++++++++++++++++---
 4 files changed, 74 insertions(+), 20 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 46b9cbf3..3bfc0386 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -283,12 +283,16 @@ pnpm run build
 
 `pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`, which fingerprints
 `~/.config/agentic-kit`, `~/.local/state/agentic-kit` (or `%APPDATA%`/`%LOCALAPPDATA%` on
-Windows), the Claude/Codex/OpenCode guidance files ak manages, and this repository's `.claude`,
-`.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` before and after the run. Any change fails
-the run and is listed by path. Files a live Claude Code, Ruflo or AQE session writes during the
-run are listed as "concurrent writers" and do not fail a local run; CI (or
-`AK_TRIPWIRE_STRICT=1`) fails on them too. Every command also runs with `TMPDIR`/`TEMP`/`TMP`
-pointed at a fresh `ak-suite-*` folder: anything left in it afterwards fails the run and is
+Windows), `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude.json`,
+`~/.codex/AGENTS.md`, `~/.codex/config.toml`, the OpenCode `AGENTS.md`, this repository's root
+`CLAUDE.md`, `AGENTS.md` and `.mcp.json`, and its `.claude`, `.swarm`, `.agentic-qe`,
+`.claude-flow` and `.harness` before and after the run. Any change fails the run and is listed
+by path. Other tool paths (skills, agents and plugin folders, `opencode.json`, the Hermes home,
+`~/.claude-flow/memory`) are not fingerprinted; `spawnEnv()` keeps spawned children away from
+them. Files a live Claude Code, Ruflo or AQE session writes during the run (including Claude
+Code's own `~/.claude.json`) are listed as "concurrent writers" and do not fail a local run; CI
+(or `AK_TRIPWIRE_STRICT=1`) fails on them too. Every command also runs with
+`TMPDIR`/`TEMP`/`TMP` pointed at a fresh `ak-suite-*` folder: anything left in it afterwards fails the run and is
 listed, and the runner refuses to start when that folder sits inside a git repository (point
 `TMPDIR` elsewhere). Tests make temporary folders with `tempDir()` from
 `tests/kit/helpers/temp-dir.mjs`, and spawned children get their environment from `spawnEnv()` in
diff --git a/MAINTAINER.md b/MAINTAINER.md
index 291fa999..b8223014 100644
--- a/MAINTAINER.md
+++ b/MAINTAINER.md
@@ -245,9 +245,10 @@ pnpm run lint:links:internal # requires lychee
 Run one suite while iterating: `node --test tests/kit/versions.test.mjs`.
 
 `pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`, a guard around the
-suite. It fingerprints real user state (ak's config and state folders, the host guidance files
-ak manages, and this repository's `.claude`, `.swarm`, `.agentic-qe`, `.claude-flow` and
-`.harness`) before and after the run, and points `TMPDIR`/`TEMP`/`TMP` at a fresh
+suite. It fingerprints real user state (ak's config and state folders, the Claude Code, Codex
+CLI and OpenCode files ak writes in their homes, this repository's root `CLAUDE.md`, `AGENTS.md`
+and `.mcp.json`, and its `.claude`, `.swarm`, `.agentic-qe`, `.claude-flow` and `.harness`)
+before and after the run, and points `TMPDIR`/`TEMP`/`TMP` at a fresh
 `ak-suite-*` folder. Its exit code tells you what went wrong:
 
 | Exit | Meaning |
diff --git a/scripts/real-state-tripwire.mjs b/scripts/real-state-tripwire.mjs
index 18da9e46..4eb951e0 100644
--- a/scripts/real-state-tripwire.mjs
+++ b/scripts/real-state-tripwire.mjs
@@ -1,9 +1,17 @@
 #!/usr/bin/env node
 // scripts/real-state-tripwire.mjs
-// Real-state tripwire: fingerprints every folder a test could write on the
-// developer's machine and names each path that changed. Four incidents wrote
-// real state (statusline version + env pins in the repo's .claude, the
-// maintenance state, a heal receipt); this turns the next one into a failure.
+// Real-state tripwire: fingerprints the real-state locations ak writes on the
+// developer's machine and names each path that changed. Watched: ak's config
+// and state folders; the files ak sync/setup write in other tools' homes
+// (~/.claude/CLAUDE.md and settings.json, ~/.claude.json, ~/.codex/AGENTS.md and
+// config.toml, the OpenCode AGENTS.md); the repository's root CLAUDE.md,
+// AGENTS.md and .mcp.json; and its .claude/.swarm/.agentic-qe/.claude-flow/
+// .harness folders. Not watched: skills, agents and plugin folders in those
+// homes, opencode.json, the Hermes home, ~/.claude-flow/memory and every other
+// tool path; spawnEnv() (tests/kit/helpers/home-sandbox.mjs) is what keeps
+// spawned children away from those. Four incidents wrote real state
+// (statusline version + env pins in the repo's .claude, the maintenance state,
+// a heal receipt); this turns the next one into a failure.
 // Imports only builtins: src/lib/paths.mjs snapshots os.homedir() at module
 // scope and must never be loaded here. Node 22.13+.
 import crypto from 'node:crypto';
@@ -13,6 +21,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const REPO_STATE_DIRS = ['.claude', '.swarm', '.agentic-qe', '.claude-flow', '.harness'];
+export const REPO_ROOT_FILES = ['CLAUDE.md', 'AGENTS.md', '.mcp.json'];
+const SINGLE_FILE_KINDS = new Set(['user-file', 'repo-file']);
 
 /** Writers a live Claude Code / Ruflo / AQE session runs concurrently with a
  *  developer's test run. Excluded from failure only outside strict mode, and
@@ -24,6 +34,7 @@ export const CONCURRENT_WRITERS = [
   { kind: 'repo', pattern: /^\.swarm(\/|$)/, writer: 'Ruflo hooks and daemon of a live session' },
   { kind: 'repo', pattern: /^\.agentic-qe\/(?!llm-config\.json)/, writer: 'AQE hooks of a live session' },
   { kind: 'repo', pattern: /^\.claude-flow\/(?!config\.json$)/, writer: 'Ruflo hooks and statusline caches of a live session' },
+  { kind: 'user-file', pattern: /^\.claude\.json$/, writer: 'Claude Code session state in ~/.claude.json (https://code.claude.com/docs/en/settings)' },
 ];
 
 export function isStrict(env = process.env) {
@@ -41,14 +52,22 @@ export function realStateRoots({ env = process.env, platform = process.platform,
   const primaryConfig = platform === 'win32'
     ? env.APPDATA || p.join(homedir, 'AppData', 'Roaming')
     : env.XDG_CONFIG_HOME || p.join(homedir, '.config');
+  const claudeHome = env.CLAUDE_CONFIG_DIR || p.join(homedir, '.claude');
+  const codexHome = env.CODEX_HOME || p.join(homedir, '.codex');
   const roots = [
     ...configBases.filter(Boolean).map((base) => ({ kind: 'config', dir: p.join(base, 'agentic-kit') })),
     ...stateBases.filter(Boolean).map((base) => ({ kind: 'state', dir: p.join(base, 'agentic-kit') })),
     ...REPO_STATE_DIRS.map((name) => ({ kind: 'repo', dir: p.join(repoRoot, name), prefix: name })),
-    // ak-managed guidance files in other tools' homes (sync/setup write them).
-    { kind: 'user-file', dir: p.join(env.CLAUDE_CONFIG_DIR || p.join(homedir, '.claude'), 'CLAUDE.md') },
-    { kind: 'user-file', dir: p.join(env.CODEX_HOME || p.join(homedir, '.codex'), 'AGENTS.md') },
+    // Files ak sync/setup write in other tools' homes (src/lib/paths.mjs:39-60).
+    { kind: 'user-file', dir: p.join(claudeHome, 'CLAUDE.md') },
+    { kind: 'user-file', dir: p.join(claudeHome, 'settings.json') },
+    { kind: 'user-file', dir: p.join(homedir, '.claude.json') },
+    { kind: 'user-file', dir: p.join(codexHome, 'AGENTS.md') },
+    { kind: 'user-file', dir: p.join(codexHome, 'config.toml') },
     { kind: 'user-file', dir: p.join(primaryConfig, 'opencode', 'AGENTS.md') },
+    // Project files ak writes at the repository root (src/lib/project-guidance.mjs,
+    // the Codex AGENTS.md target in src/lib/blocks.mjs, .mcp.json in src/commands/setup.mjs).
+    ...REPO_ROOT_FILES.map((name) => ({ kind: 'repo-file', dir: p.join(repoRoot, name) })),
   ];
   const seen = new Set();
   return roots.filter((root) => {
@@ -96,7 +115,7 @@ export function snapshotRoots(roots) {
   const out = new Map();
   for (const root of roots) {
     if (!fs.existsSync(root.dir)) { out.set(`absent:${root.dir}`, { root, rel: '', type: 'absent-root' }); continue; }
-    if (root.kind === 'user-file') { record(out, root, path.basename(root.dir), root.dir); continue; }
+    if (SINGLE_FILE_KINDS.has(root.kind)) { record(out, root, path.basename(root.dir), root.dir); continue; }
     // The root itself is an entry, so a run that CREATES ~/.local/state/agentic-kit
     // (even empty) is reported as `+ <root>/`.
     out.set(root.dir, { root, rel: root.prefix ? `${root.prefix}/` : './', type: 'dir' });
diff --git a/tests/kit/real-state-tripwire.test.mjs b/tests/kit/real-state-tripwire.test.mjs
index 3fd2ada1..604bd237 100644
--- a/tests/kit/real-state-tripwire.test.mjs
+++ b/tests/kit/real-state-tripwire.test.mjs
@@ -30,6 +30,9 @@ test('POSIX roots: XDG bases, their defaults, the repo state folders and ak-owne
     ...REPO_STATE_DIRS.map((d) => `repo:/src/kit/${d}`),
     'user-file:/home/dev/.claude/CLAUDE.md', 'user-file:/home/dev/.codex/AGENTS.md',
     'user-file:/x/cfg/opencode/AGENTS.md',
+    'user-file:/home/dev/.claude/settings.json', 'user-file:/home/dev/.claude.json',
+    'user-file:/home/dev/.codex/config.toml',
+    'repo-file:/src/kit/CLAUDE.md', 'repo-file:/src/kit/AGENTS.md', 'repo-file:/src/kit/.mcp.json',
   ]) assert.ok(dirs.includes(want), `missing ${want} in ${dirs.join(', ')}`);
 });
 
@@ -46,6 +49,29 @@ test('Windows roots use APPDATA/LOCALAPPDATA and collapse case-insensitive dupli
   assert.ok(dirs.includes('repo:C:\\src\\kit\\.claude'));
 });
 
+test('CLAUDE_CONFIG_DIR moves settings.json but not ~/.claude.json, which Claude Code keeps in the home folder', () => {
+  const dirs = realStateRoots({
+    platform: 'linux', homedir: '/home/dev', repoRoot: '/src/kit', env: { CLAUDE_CONFIG_DIR: '/cc' },
+  }).map((r) => `${r.kind}:${r.dir}`);
+  assert.ok(dirs.includes('user-file:/cc/settings.json'));
+  assert.ok(dirs.includes('user-file:/home/dev/.claude.json'));
+  assert.ok(!dirs.includes('user-file:/home/dev/.claude/settings.json'));
+});
+
+test('a rewritten repo-root guidance or MCP file is failing, even outside strict mode', (t) => {
+  const home = tmp(t, 'ak-trip-repofile');
+  const repo = path.join(home, 'repo');
+  fs.mkdirSync(repo, { recursive: true });
+  fs.writeFileSync(path.join(repo, 'AGENTS.md'), '# guidance\n');
+  const roots = realStateRoots({ platform: process.platform, homedir: home, repoRoot: repo, env: {} });
+  const before = snapshotRoots(roots);
+  fs.writeFileSync(path.join(repo, 'AGENTS.md'), '# guidance\n<!-- injected block -->\n');
+  fs.writeFileSync(path.join(repo, '.mcp.json'), '{}');
+  const { failing, concurrent } = compareSnapshots(before, snapshotRoots(roots), { strict: false });
+  assert.deepEqual(failing.map((c) => `${c.op} ${c.kind} ${c.rel}`).sort(), ['+ repo-file .mcp.json', '~ repo-file AGENTS.md']);
+  assert.deepEqual(concurrent, []);
+});
+
 test('a created, removed or rewritten file is failing; an mtime-only touch is not', (t) => {
   const home = tmp(t, 'ak-trip');
   const cfg = path.join(home, '.config', 'agentic-kit');
@@ -91,15 +117,19 @@ test('developer mode moves live-session writers to "concurrent"; strict mode fai
   fs.writeFileSync(path.join(cfg, 'claude-context-windows', 's1.json'), '[]');
   fs.writeFileSync(path.join(repo, '.swarm', 'memory.db-wal'), 'x');
   fs.writeFileSync(path.join(repo, '.agentic-qe', 'llm-config.json'), '{}');
+  fs.writeFileSync(path.join(home, '.claude.json'), '{"numStartups":2}');
+  fs.mkdirSync(path.join(home, '.claude'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.claude', 'settings.json'), '{}');
   const after = snapshotRoots(roots);
   const dev = compareSnapshots(before, after, { strict: false });
-  assert.deepEqual(dev.failing.map((c) => c.rel), ['.agentic-qe/llm-config.json'],
-    'ak-owned files inside hook-churned folders stay failing');
+  assert.deepEqual(dev.failing.map((c) => c.rel).sort(), ['.agentic-qe/llm-config.json', 'settings.json'],
+    'ak-owned files inside hook-churned folders, and Claude settings, stay failing');
   assert.deepEqual(dev.concurrent.map((c) => c.rel).sort(),
-    ['.swarm/memory.db-wal', 'claude-context-windows/s1.json', 'claude-rate-limits.json']);
+    ['.claude.json', '.swarm/memory.db-wal', 'claude-context-windows/s1.json', 'claude-rate-limits.json']);
   const strict = compareSnapshots(before, after, { strict: true });
   assert.equal(strict.concurrent.length, 0);
   assert.ok(strict.failing.some((c) => c.rel === 'claude-rate-limits.json'));
+  assert.ok(strict.failing.some((c) => c.rel === '.claude.json'));
   assert.match(formatReport(dev), /concurrent writers \(not failing\)/);
 });
 

From 488dfc3fcf4647fa490791c66b24119c9c6811c0 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:50:38 -0700
Subject: [PATCH 19/28] test(spawn-env): fail on child_process calls that
 inherit process.env implicitly

The guard only matched lines that spread process.env, so a spawn with no env
option passed it while inheriting everything. It now scans each child_process
call (code only, strings and comments blanked) and fails when the call passes
no env option and its first line carries no spawn-env marker. The thirteen calls
that ran kit code (the CLI binary, the statusline, the diagnostic script and
module imports) now get spawnEnv(home); git in throwaway repositories, inert
node sleepers, PATH probes and the opt-in live tests carry a stated reason.
MAINTAINER.md and the audit record describe what the guard checks and what it
cannot see.
---
 MAINTAINER.md                                 |   5 +-
 ...-237-238-239-verification-and-decisions.md |   6 +-
 tests/kit/adapter-registries.test.mjs         |   4 +-
 tests/kit/codex-usage-diagnostic.test.mjs     |   3 +-
 tests/kit/daemons.test.mjs                    |   2 +-
 tests/kit/dispatch-surface.test.mjs           |   8 +-
 tests/kit/disposable-memory-project.test.mjs  |   2 +-
 tests/kit/exec-kill-tree.test.mjs             |   4 +-
 tests/kit/execution-runner.test.mjs           |   4 +-
 tests/kit/live-core.test.mjs                  |  12 +-
 tests/kit/maintenance-cli.test.mjs            |   8 +-
 .../maintenance-git-project-patch.test.mjs    |  20 +--
 tests/kit/node-runtime.test.mjs               |   4 +-
 .../kit/opencode-stock-ruflo-gateway.test.mjs |   4 +-
 tests/kit/output-progress.test.mjs            |   8 +-
 tests/kit/process-tree.test.mjs               |   4 +-
 tests/kit/spawn-env-guard.test.mjs            | 116 ++++++++++++++++++
 tests/kit/statusline.test.mjs                 |   8 +-
 tests/kit/telemetry-cli.test.mjs              |   5 +-
 tests/kit/upstream-watch-skill.test.mjs       |   4 +-
 tests/live/codex-context-contract.test.mjs    |   4 +-
 .../qe-court-participant-transport.test.mjs   |   2 +-
 tests/live/qe-court-public-contract.test.mjs  |   2 +-
 tests/live/ruflo-memory-routing.test.mjs      |   2 +-
 24 files changed, 192 insertions(+), 49 deletions(-)

diff --git a/MAINTAINER.md b/MAINTAINER.md
index b8223014..b38d0c0f 100644
--- a/MAINTAINER.md
+++ b/MAINTAINER.md
@@ -269,7 +269,10 @@ Inside the suite, isolation comes from shared helpers:
   path for tests that run machine-mutating commands in process.
 - `spawnEnv()` (same file) builds the environment for every spawned child, with all
   per-user bases inside a sandbox home. `tests/kit/spawn-env-guard.test.mjs` fails on a
-  spawn that inherits `process.env` without a marked reason.
+  line that spreads `process.env` and on a `child_process` call with no `env` option (an
+  implicit inherit), unless the line carries `spawn-env: inherits (<reason>)`. It reads
+  source text: a call whose options object is built elsewhere needs the marker, and a call
+  through a local wrapper function is not seen.
 - `redirectToolState()` (same file) moves the config, state, data, cache and temp bases for
   in-process tests whose code under test spawns real tools such as OpenCode.
 - `tempDir()` (`tests/kit/helpers/temp-dir.mjs`) makes temporary folders that are removed
diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 93c008a7..542bad0c 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1240,8 +1240,10 @@ Behavior that differs from, or goes beyond, the plan text.
   - The Claude statusLine classifier does not read managed settings.
   - A shell wrapper around the footer helper is classed as `custom`.
   - Other spawn tests inherited the developer's `XDG_*` variables. Fixed on `fix/test-hermeticity`:
-    spawned children get `spawnEnv(home)`, and a guard test fails on any spawn that neither uses it
-    nor states why it inherits.
+    spawned children that run kit code get `spawnEnv(home)`. A guard test fails on a line that
+    spreads `process.env`, and on a `child_process` call that passes no `env` option (so inherits
+    implicitly), unless the line states why it inherits. It reads source text: a call whose options
+    object is built elsewhere needs the marker, and a call through a local wrapper is not seen.
   - M1b is still open.
 - **ADR index.** In `docs/adr/README.md` the index table ends at ADR-0052; later ADRs appear only as
   bullets or sections. This predates the branch.
diff --git a/tests/kit/adapter-registries.test.mjs b/tests/kit/adapter-registries.test.mjs
index 22891a82..9d760676 100644
--- a/tests/kit/adapter-registries.test.mjs
+++ b/tests/kit/adapter-registries.test.mjs
@@ -1,4 +1,6 @@
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import {
   HOST_REGISTRY,
@@ -69,7 +71,7 @@ test('model discovery descriptor validation rejects ambiguous owners and unsafe
 test('the shipped registries cannot fail construction-time validation (import cannot throw)', () => {
   const r = spawnSync(process.execPath, ['-e',
     "import('./src/lib/adapters/registries.mjs').then(() => console.log('construction-valid'))",
-  ], { encoding: 'utf8', cwd: REPO });
+  ], { encoding: 'utf8', cwd: REPO, env: spawnEnv(tempDir('ak-registries-home')) });
   assert.equal(r.status, 0, `registries module must import cleanly:\n${r.stderr}`);
   assert.match(r.stdout, /construction-valid/);
 });
diff --git a/tests/kit/codex-usage-diagnostic.test.mjs b/tests/kit/codex-usage-diagnostic.test.mjs
index e341e458..b8642363 100644
--- a/tests/kit/codex-usage-diagnostic.test.mjs
+++ b/tests/kit/codex-usage-diagnostic.test.mjs
@@ -1,4 +1,5 @@
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -14,7 +15,7 @@ function run(t, records, json = true) {
   const dir = path.join(root, '2026', '09', '09');
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(path.join(dir, 'rollout-private-session.jsonl'), records.map(JSON.stringify).join('\n'));
-  const result = spawnSync(process.execPath, [script, '--root', root, ...(json ? ['--json'] : [])], { encoding: 'utf8' });
+  const result = spawnSync(process.execPath, [script, '--root', root, ...(json ? ['--json'] : [])], { encoding: 'utf8', env: spawnEnv(path.join(root, 'home')) });
   assert.equal(result.status, 0, result.stderr);
   assert.ok(!result.stdout.includes('PRIVATE-DIAGNOSTIC-ROOT'));
   return json ? JSON.parse(result.stdout) : result.stdout;
diff --git a/tests/kit/daemons.test.mjs b/tests/kit/daemons.test.mjs
index c3feb541..9e12efa3 100644
--- a/tests/kit/daemons.test.mjs
+++ b/tests/kit/daemons.test.mjs
@@ -62,7 +62,7 @@ test('a real child whose argv matches "daemon start" IS reaped', async (t) => {
   if (process.platform === 'win32') { t.skip('kill-true path exercised on POSIX only (CI timing)'); return; }
   // Spawn a keep-alive child whose ps args contain "daemon start" (extra argv
   // after -e lands in the command line), so the identity guard matches it.
-  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)', 'daemon', 'start'], { stdio: 'ignore' });
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)', 'daemon', 'start'], { stdio: 'ignore' }); // spawn-env: inherits (inert node sleeper, runs no kit code)
   t.after(() => { try { child.kill('SIGKILL'); } catch { /* already dead */ } });
   await new Promise((r) => setTimeout(r, 200)); // let it register in the ps table
   const [r] = reap([{ pid: child.pid, workspace: '/x' }]);
diff --git a/tests/kit/dispatch-surface.test.mjs b/tests/kit/dispatch-surface.test.mjs
index 6e3fce48..12145bfb 100644
--- a/tests/kit/dispatch-surface.test.mjs
+++ b/tests/kit/dispatch-surface.test.mjs
@@ -9,6 +9,8 @@
 // process.exit) during the test. The individual command modules, by contrast,
 // have no top-level side effects, so importing each one is safe.
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -73,16 +75,18 @@ for (const [name, modPath] of dispatchTable()) {
 // tools' failures. These spawn the REAL CLI (not an in-process import) because
 // the bug lived in bin/agentic-kit.mjs's own dispatch, not in any command module.
 const BIN_ARGV = [BIN];
+// A throwaway home: the child must never reach the developer's real config or state.
+const HOME = tempDir('ak-dispatch-home');
 for (const hostile of ['toString', '__proto__', 'constructor', 'hasOwnProperty']) {
   test(`"ak ${hostile}" is an unknown command, not a prototype-chain hit`, () => {
-    const r = spawnSync(process.execPath, [...BIN_ARGV, hostile], { encoding: 'utf8' });
+    const r = spawnSync(process.execPath, [...BIN_ARGV, hostile], { encoding: 'utf8', env: spawnEnv(HOME) });
     assert.equal(r.status, 2, `expected exit 2 (unknown command), got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
     assert.match(r.stdout, /unknown command/, 'must print the normal "unknown command" message');
     assert.equal(r.stderr, '', `must never leak a stack trace to stderr for a typo'd command name, got: ${r.stderr}`);
   });
 
   test(`"ak x ${hostile}" is an unknown plumbing command, not a prototype-chain hit`, () => {
-    const r = spawnSync(process.execPath, [...BIN_ARGV, 'x', hostile], { encoding: 'utf8' });
+    const r = spawnSync(process.execPath, [...BIN_ARGV, 'x', hostile], { encoding: 'utf8', env: spawnEnv(HOME) });
     assert.equal(r.status, 2, `expected exit 2 (unknown plumbing command), got ${r.status}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
     assert.match(r.stdout, /unknown plumbing command/, 'must print the normal "unknown plumbing command" message');
     assert.equal(r.stderr, '', `must never leak a stack trace to stderr for a typo'd plumbing command name, got: ${r.stderr}`);
diff --git a/tests/kit/disposable-memory-project.test.mjs b/tests/kit/disposable-memory-project.test.mjs
index 2660d48b..123f9af9 100644
--- a/tests/kit/disposable-memory-project.test.mjs
+++ b/tests/kit/disposable-memory-project.test.mjs
@@ -92,7 +92,7 @@ test('cleanup removes the whole project, and stops a daemon that holds its pidfi
   if (process.platform !== 'win32') {
     // A keep-alive child whose command line reads like a Ruflo daemon, so the
     // pid-reuse guard in daemons.mjs reap() lets cleanup stop it.
-    child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)', 'daemon', 'start'], { stdio: 'ignore' });
+    child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)', 'daemon', 'start'], { stdio: 'ignore' }); // spawn-env: inherits (inert node sleeper, runs no kit code)
     t.after(() => { try { child.kill('SIGKILL'); } catch { /* already gone */ } });
     await new Promise((resolve) => setTimeout(resolve, 200));
     fs.mkdirSync(path.join(project.root, '.claude-flow'));
diff --git a/tests/kit/exec-kill-tree.test.mjs b/tests/kit/exec-kill-tree.test.mjs
index e5956b8d..3e7ef67b 100644
--- a/tests/kit/exec-kill-tree.test.mjs
+++ b/tests/kit/exec-kill-tree.test.mjs
@@ -27,7 +27,7 @@ function parentWithGrandchild(t, { detached }) {
     const gc = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 60000)'], { stdio: 'ignore' });
     require('node:fs').writeFileSync(${JSON.stringify(pidFile)}, String(gc.pid));
     setTimeout(() => {}, 60000);`;
-  const child = spawn(process.execPath, ['-e', script], { detached, stdio: 'ignore' });
+  const child = spawn(process.execPath, ['-e', script], { detached, stdio: 'ignore' }); // spawn-env: inherits (inert node process tree, runs no kit code)
   return { child, pidFile };
 }
 
@@ -72,7 +72,7 @@ test('a child that does not lead its own group is still killed directly', posix,
 });
 
 test('killing an already-dead process group is not an error', posix, async () => {
-  const child = spawn(process.execPath, ['-e', ''], { detached: true, stdio: 'ignore' });
+  const child = spawn(process.execPath, ['-e', ''], { detached: true, stdio: 'ignore' }); // spawn-env: inherits (inert node child, runs no kit code)
   await once(child, 'close');
   assert.doesNotThrow(() => killProcessTree(child));
 });
diff --git a/tests/kit/execution-runner.test.mjs b/tests/kit/execution-runner.test.mjs
index 8cca879b..3de53238 100644
--- a/tests/kit/execution-runner.test.mjs
+++ b/tests/kit/execution-runner.test.mjs
@@ -1,4 +1,6 @@
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import { EXECUTION_ADAPTERS, assertBuiltinAdaptersRoutable, executionAdapterFor } from '../../src/lib/execution/adapters.mjs';
 import { applyAdmitted, resetAdmitted } from '../../src/lib/adapters/admitted.mjs';
@@ -465,7 +467,7 @@ test('a fresh process imports the real execution adapters registry cleanly (cons
   const repo = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
   const r = spawnSync(process.execPath, ['-e',
     "import('./src/lib/execution/adapters.mjs').then(() => console.log('in-sync'))",
-  ], { encoding: 'utf8', cwd: repo });
+  ], { encoding: 'utf8', cwd: repo, env: spawnEnv(tempDir('ak-exec-adapters-home')) });
   assert.equal(r.status, 0, `execution adapters module must import cleanly:\n${r.stderr}`);
   assert.match(r.stdout, /in-sync/);
 });
diff --git a/tests/kit/live-core.test.mjs b/tests/kit/live-core.test.mjs
index df85ecb7..7ec52b18 100644
--- a/tests/kit/live-core.test.mjs
+++ b/tests/kit/live-core.test.mjs
@@ -149,12 +149,12 @@ test('Git workspace inspection reports tracked state without filenames or attrib
   const root = tempDir('ak-live-workspace');
   fs.mkdirSync(path.join(root, 'backend'), { recursive: true });
   // Exercise the real Git boundary in a disposable repository.
-  execFileSync('git', ['init', '-q', '-b', 'feature/workspace', root]);
-  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@example.invalid']);
-  execFileSync('git', ['-C', root, 'config', 'user.name', 'Test']);
+  execFileSync('git', ['init', '-q', '-b', 'feature/workspace', root]); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@example.invalid']); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'Test']); // spawn-env: inherits (git in a throwaway repository)
   fs.writeFileSync(path.join(root, 'tracked.txt'), 'one\ntwo\n');
-  execFileSync('git', ['-C', root, 'add', 'tracked.txt']);
-  execFileSync('git', ['-C', root, 'commit', '-qm', 'fixture']);
+  execFileSync('git', ['-C', root, 'add', 'tracked.txt']); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'commit', '-qm', 'fixture']); // spawn-env: inherits (git in a throwaway repository)
   fs.writeFileSync(path.join(root, 'tracked.txt'), 'one\nthree\nfour\n');
   fs.writeFileSync(path.join(root, 'untracked-secret.txt'), 'not counted\n');
   const workspace = await inspectGitWorkspace(path.join(root, 'backend'), {
@@ -228,7 +228,7 @@ test('Git workspace inspection ignores inherited repository-routing variables',
   const redirected = path.join(root, 'redirected');
   for (const repository of [expected, redirected]) {
     fs.mkdirSync(repository);
-    execFileSync('git', ['init', '-q', '-b', path.basename(repository), repository]);
+    execFileSync('git', ['init', '-q', '-b', path.basename(repository), repository]); // spawn-env: inherits (git in a throwaway repository)
   }
   const priorDir = process.env.GIT_DIR;
   const priorTree = process.env.GIT_WORK_TREE;
diff --git a/tests/kit/maintenance-cli.test.mjs b/tests/kit/maintenance-cli.test.mjs
index 58391b00..5d6dcbe3 100644
--- a/tests/kit/maintenance-cli.test.mjs
+++ b/tests/kit/maintenance-cli.test.mjs
@@ -1,4 +1,6 @@
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +11,8 @@ import { isProhibitedLabel } from '../../src/lib/maintenance/management/model.mj
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const BIN = path.join(ROOT, 'bin', 'agentic-kit.mjs');
+// A throwaway home: the child must never reach the developer's real config or state.
+const HOME = tempDir('ak-maintain-cli-home');
 
 async function captureLogs(fn) {
   const lines = [];
@@ -264,14 +268,14 @@ function buildService(overrides = {}) {
 // ── Help surface ─────────────────────────────────────────────────────────────
 
 test('maintain is porcelain and its help advertises exact guarded actions', () => {
-  const help = spawnSync(process.execPath, [BIN, 'maintain', '--help'], { encoding: 'utf8' });
+  const help = spawnSync(process.execPath, [BIN, 'maintain', '--help'], { encoding: 'utf8', env: spawnEnv(HOME) });
   assert.equal(help.status, 0, help.stderr);
   assert.match(help.stdout, /ak maintain scan/);
   assert.match(help.stdout, /apply.*--plan.*--digest.*--actions.*--yes/i);
   assert.match(help.stdout, /ak maintain recover --receipt/i);
   assert.match(help.stdout, /recover is a read-only alias for audit/i);
   assert.match(help.stdout, /exactly one exact action id/i);
-  const rootHelp = spawnSync(process.execPath, [BIN, '--help'], { encoding: 'utf8' });
+  const rootHelp = spawnSync(process.execPath, [BIN, '--help'], { encoding: 'utf8', env: spawnEnv(HOME) });
   assert.match(rootHelp.stdout, /ak maintain/);
 });
 
diff --git a/tests/kit/maintenance-git-project-patch.test.mjs b/tests/kit/maintenance-git-project-patch.test.mjs
index 21e97da9..ffeb1fc5 100644
--- a/tests/kit/maintenance-git-project-patch.test.mjs
+++ b/tests/kit/maintenance-git-project-patch.test.mjs
@@ -16,7 +16,7 @@ import { runNativeCommand } from '../../src/lib/maintenance/native-command.mjs';
 const FORBIDDEN_VERBS = new Set(['stash', 'commit', 'branch', 'checkout', 'push', 'merge']);
 
 let gitAvailable = true;
-try { execFileSync('git', ['--version'], { stdio: 'ignore' }); } catch { gitAvailable = false; }
+try { execFileSync('git', ['--version'], { stdio: 'ignore' }); } catch { gitAvailable = false; } // spawn-env: inherits (git --version probe)
 
 function digestOf(content) {
   return createHash('sha256').update(content).digest('hex');
@@ -25,16 +25,16 @@ function digestOf(content) {
 function gitRepo(t) {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-maint-patch-repo-'));
   t.after(() => fs.rmSync(root, { recursive: true, force: true }));
-  execFileSync('git', ['init', '-q', root]);
-  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@example.com']);
-  execFileSync('git', ['-C', root, 'config', 'user.name', 'Test']);
+  execFileSync('git', ['init', '-q', root]); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@example.com']); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'Test']); // spawn-env: inherits (git in a throwaway repository)
   return root;
 }
 
 function commitFile(root, relPath, content) {
   fs.writeFileSync(path.join(root, relPath), content);
-  execFileSync('git', ['-C', root, 'add', relPath]);
-  execFileSync('git', ['-C', root, 'commit', '-q', '-m', `add ${relPath}`]);
+  execFileSync('git', ['-C', root, 'add', relPath]); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', `add ${relPath}`]); // spawn-env: inherits (git in a throwaway repository)
 }
 
 function preimageRoot(t) {
@@ -137,9 +137,9 @@ test('index drift on the exact target path refuses before apply, even though the
   // Touch and re-stage the file so the index shows a pending change for this
   // exact path even though the working-tree bytes are unchanged.
   fs.writeFileSync(path.join(root, 'staged.json'), '{"y":1}\n');
-  execFileSync('git', ['-C', root, 'add', 'staged.json']);
+  execFileSync('git', ['-C', root, 'add', 'staged.json']); // spawn-env: inherits (git in a throwaway repository)
   fs.appendFileSync(path.join(root, 'staged.json'), '');
-  execFileSync('git', ['-C', root, 'rm', '--cached', '-q', 'staged.json']);
+  execFileSync('git', ['-C', root, 'rm', '--cached', '-q', 'staged.json']); // spawn-env: inherits (git in a throwaway repository)
   const provider = createGitProjectPatchProvider({
     fsImpl: fs, projectRoots: () => [root], preimageRoot: preimageRoot(t),
     patches: [{
@@ -158,8 +158,8 @@ test('a submodule target is refused and no git command touches it beyond status/
   fs.mkdirSync(path.join(root, 'vendor', 'lib'), { recursive: true });
   fs.writeFileSync(path.join(root, '.gitmodules'), '[submodule "lib"]\n\tpath = vendor/lib\n\turl = https://example.invalid/lib.git\n');
   fs.writeFileSync(path.join(root, 'vendor', 'lib', 'inner.json'), '{"z":1}\n');
-  execFileSync('git', ['-C', root, 'add', '.gitmodules']);
-  execFileSync('git', ['-C', root, 'commit', '-q', '-m', 'add gitmodules']);
+  execFileSync('git', ['-C', root, 'add', '.gitmodules']); // spawn-env: inherits (git in a throwaway repository)
+  execFileSync('git', ['-C', root, 'commit', '-q', '-m', 'add gitmodules']); // spawn-env: inherits (git in a throwaway repository)
   const provider = createGitProjectPatchProvider({
     fsImpl: fs, projectRoots: () => [root], preimageRoot: preimageRoot(t),
     patches: [{
diff --git a/tests/kit/node-runtime.test.mjs b/tests/kit/node-runtime.test.mjs
index b43bd4af..7ac51099 100644
--- a/tests/kit/node-runtime.test.mjs
+++ b/tests/kit/node-runtime.test.mjs
@@ -1,4 +1,6 @@
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -18,7 +20,7 @@ for (const version of ['22.13.0', '22.13.1', '22.99.0', '23.4.0', '24.0.0', '26.
 }
 test('CLI rejects early Node before dispatching SQLite commands', () => {
   const cli = fileURLToPath(new URL('../../bin/agentic-kit.mjs', import.meta.url));
-  const result = spawnSync(process.execPath, ['--input-type=module', '-e', `Object.defineProperty(process.versions, 'node', { value: '22.12.0' }); process.argv = ['node', ${JSON.stringify(cli)}, 'status', '--json']; await import(${JSON.stringify(new URL('../../bin/agentic-kit.mjs', import.meta.url).href)});`], { encoding: 'utf8' });
+  const result = spawnSync(process.execPath, ['--input-type=module', '-e', `Object.defineProperty(process.versions, 'node', { value: '22.12.0' }); process.argv = ['node', ${JSON.stringify(cli)}, 'status', '--json']; await import(${JSON.stringify(new URL('../../bin/agentic-kit.mjs', import.meta.url).href)});`], { encoding: 'utf8', env: spawnEnv(tempDir('ak-node-runtime-home')) });
   assert.equal(result.status, 1);
   assert.match(result.stderr, /22\.13\.0/);
   assert.doesNotMatch(result.stderr, /ERR_UNKNOWN_BUILTIN_MODULE|at file:/);
diff --git a/tests/kit/opencode-stock-ruflo-gateway.test.mjs b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
index 6a3fe8a2..11d1e454 100644
--- a/tests/kit/opencode-stock-ruflo-gateway.test.mjs
+++ b/tests/kit/opencode-stock-ruflo-gateway.test.mjs
@@ -36,7 +36,7 @@ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function stockOpenCode() {
   if (process.env.AK_STOCK_OPENCODE_BIN) return process.env.AK_STOCK_OPENCODE_BIN;
   try {
-    return execFileSync('sh', ['-c', 'command -v opencode'], {
+    return execFileSync('sh', ['-c', 'command -v opencode'], { // spawn-env: inherits (PATH probe for an installed opencode)
       encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
   } catch {
@@ -46,7 +46,7 @@ function stockOpenCode() {
 
 function installedCommand(name) {
   try {
-    return execFileSync('sh', ['-c', `command -v ${name}`], {
+    return execFileSync('sh', ['-c', `command -v ${name}`], { // spawn-env: inherits (PATH probe for an installed tool)
       encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
   } catch {
diff --git a/tests/kit/output-progress.test.mjs b/tests/kit/output-progress.test.mjs
index beac2c84..17df35a4 100644
--- a/tests/kit/output-progress.test.mjs
+++ b/tests/kit/output-progress.test.mjs
@@ -6,6 +6,8 @@
 // the caller's ok/fail prints. Hermetic via the injectable {tty, out} seam —
 // never touches the real stdout, so results don't depend on how tests are run.
 import { test } from 'node:test';
+import { spawnEnv } from './helpers/home-sandbox.mjs';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import {
   reportOutcome, withProgress, sanitizeForTerminal, dim, bold,
@@ -113,12 +115,14 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const OUTPUT_MJS = fileURLToPath(new URL('../../src/lib/output.mjs', import.meta.url));
 const PAYLOAD = 200 * 1024;
+// A throwaway home: the child must never reach the developer's real config or state.
+const HOME = tempDir('ak-output-progress-home');
 
 const runChild = (tailJs) => spawnSync(process.execPath, ['--input-type=module', '-e',
   `import { exitWhenFlushed } from ${JSON.stringify(pathToFileURL(OUTPUT_MJS).href)};
    process.stdout.write('x'.repeat(${PAYLOAD}));
    ${tailJs}`,
-], { encoding: 'utf8', maxBuffer: 4 * PAYLOAD });
+], { encoding: 'utf8', maxBuffer: 4 * PAYLOAD, env: spawnEnv(HOME) });
 
 test('exitWhenFlushed delivers the full piped payload past the 64KB pipe buffer', () => {
   const r = runChild('exitWhenFlushed(0);');
@@ -165,7 +169,7 @@ test('SEC-5: a consumer that opens the pipe and never reads it still exits, boun
     `import { exitWhenFlushed } from ${JSON.stringify(pathToFileURL(OUTPUT_MJS).href)};
      process.stdout.write('x'.repeat(${PAYLOAD}));
      exitWhenFlushed(7);`,
-  ], { stdio: ['ignore', 'pipe', 'ignore'] });
+  ], { stdio: ['ignore', 'pipe', 'ignore'], env: spawnEnv(HOME) });
   child.stdout.pause(); // open, never read — the stalled-consumer case
 
   const started = Date.now();
diff --git a/tests/kit/process-tree.test.mjs b/tests/kit/process-tree.test.mjs
index 3b64049b..25689c54 100644
--- a/tests/kit/process-tree.test.mjs
+++ b/tests/kit/process-tree.test.mjs
@@ -43,7 +43,7 @@ test('POSIX tree signaling falls back to the direct child when no group exists',
 test('POSIX tree signaling terminates a detached wrapper and its descendant', {
   skip: process.platform === 'win32',
 }, async () => {
-  const wrapper = spawn(process.execPath, ['-e', [
+  const wrapper = spawn(process.execPath, ['-e', [ // spawn-env: inherits (inert node process tree, runs no kit code)
     "const {spawn}=require('node:child_process')",
     "const child=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{stdio:'ignore'})",
     'console.log(child.pid)',
@@ -71,7 +71,7 @@ test('POSIX tree signaling terminates a detached wrapper and its descendant', {
 test('Windows tree signaling terminates a wrapper and its live descendant', {
   skip: process.platform !== 'win32',
 }, async () => {
-  const wrapper = spawn(process.execPath, ['-e', [
+  const wrapper = spawn(process.execPath, ['-e', [ // spawn-env: inherits (inert node process tree, runs no kit code)
     "const {spawn}=require('node:child_process')",
     "const child=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{stdio:'ignore'})",
     'console.log(child.pid)',
diff --git a/tests/kit/spawn-env-guard.test.mjs b/tests/kit/spawn-env-guard.test.mjs
index 29efd6ef..7b394204 100644
--- a/tests/kit/spawn-env-guard.test.mjs
+++ b/tests/kit/spawn-env-guard.test.mjs
@@ -4,6 +4,14 @@
 // ~/.cache/opencode and ~/.local/share/opencode this way). Every child env in
 // tests/ is built by spawnEnv()/sandboxEnvFor(); a deliberate exception carries
 // the marker comment `spawn-env: inherits (<reason>)` on the same line.
+// Two checks: no line spreads process.env, and every child_process call names an
+// `env` option (a call without one inherits process.env implicitly). The second
+// check reads source text: it sees calls to names bound from child_process and
+// `require('node:child_process').x(`. A call whose options object is built
+// elsewhere shows no `env`, so it needs the marker; a call through a local
+// wrapper function is not seen at all. A call nested inside another
+// call's arguments, or inside a string (a grandchild script), runs with the
+// outer call's environment and is not checked separately.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
@@ -37,6 +45,114 @@ test('no test builds a child environment from process.env outside the sandbox he
   assert.deepEqual(offenders, [], `use spawnEnv(home, extra) from tests/kit/helpers/home-sandbox.mjs:\n  ${offenders.join('\n  ')}`);
 });
 
+const CP_FNS = new Set(['spawn', 'spawnSync', 'exec', 'execSync', 'execFile', 'execFileSync', 'fork']);
+const MARKER = /spawn-env: inherits \(.+\)/;
+
+/** Replace string, template and comment contents with spaces (offsets and
+ *  newlines are kept), so a scan sees code only. */
+function codeOnly(src) {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    const two = src.slice(i, i + 2);
+    if (two === '//' || two === '/*') {
+      const end = two === '//' ? src.indexOf('\n', i) : src.indexOf('*/', i + 2) + 2;
+      const stop = end <= 1 || end === -1 ? src.length : end;
+      out += src.slice(i, stop).replace(/[^\n]/g, ' ');
+      i = stop;
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1;
+      while (j < src.length && src[j] !== c) j += src[j] === '\\' ? 2 : 1;
+      out += c + src.slice(i + 1, j).replace(/[^\n]/g, ' ') + c;
+      i = j + 1;
+    } else { out += c; i += 1; }
+  }
+  return out;
+}
+
+/** Names this file binds from node:child_process, and its namespace aliases. */
+function childProcessBindings(src) {
+  const names = new Set();
+  const namespaces = new Set();
+  const from = String.raw`['"](?:node:)?child_process['"]`;
+  for (const m of src.matchAll(new RegExp(String.raw`import\s*\{([^{}]*)\}\s*from\s*${from}`, 'g'))) {
+    for (const part of m[1].split(',')) {
+      const [orig, alias] = part.trim().split(/\s+as\s+/);
+      if (CP_FNS.has(orig)) names.add((alias || orig).trim());
+    }
+  }
+  for (const m of src.matchAll(new RegExp(String.raw`import\s+(?:\*\s+as\s+)?(\w+)\s+from\s*${from}`, 'g'))) namespaces.add(m[1]);
+  for (const m of src.matchAll(new RegExp(String.raw`\{([^{}]*)\}\s*=\s*(?:await\s+import|require)\(\s*${from}\s*\)`, 'g'))) {
+    for (const part of m[1].split(',')) {
+      const [orig, alias] = part.trim().split(/\s*:\s*/);
+      if (CP_FNS.has(orig)) names.add((alias || orig).trim());
+    }
+  }
+  return { names, namespaces };
+}
+
+/** First lines of child_process calls in `src` that pass no `env` option. */
+export function implicitInheritCalls(src) {
+  const { names, namespaces } = childProcessBindings(src);
+  const code = codeOnly(src);
+  const found = [];
+  let coveredUntil = -1;
+  const call = /(\w+)\s*\(/g;
+  for (let m = call.exec(code); m; m = call.exec(code)) {
+    const start = m.index;
+    if (start < coveredUntil) continue;
+    const before = code.slice(0, start);
+    const viaRequire = /require\(\s*'\s*'\s*\)\s*\.\s*$/.test(before) && /child_process/.test(src.slice(Math.max(0, start - 40), start));
+    const viaNamespace = [...namespaces].some((ns) => new RegExp(String.raw`\b${ns}\s*\.\s*$`).test(before));
+    const direct = names.has(m[1]) && !/[.\w$]\s*$/.test(before.slice(-1)) && !/function\s*$/.test(before);
+    if (!(CP_FNS.has(m[1]) && (viaRequire || viaNamespace)) && !direct) continue;
+    let depth = 1;
+    let i = start + m[0].length;
+    while (i < code.length && depth > 0) {
+      if ('([{'.includes(code[i])) depth += 1;
+      else if (')]}'.includes(code[i])) depth -= 1;
+      i += 1;
+    }
+    coveredUntil = i;
+    if (/[{,]\s*env\s*[:,}]/.test(code.slice(start, i))) continue;
+    const line = before.split('\n').length;
+    if (MARKER.test(src.split('\n')[line - 1])) continue;
+    found.push(line);
+  }
+  return found;
+}
+
+test('every child_process call in tests/ passes an env option or carries the marker', () => {
+  const offenders = [];
+  for (const file of files(TESTS)) {
+    if (file === SELF || file === HELPER) continue;
+    for (const line of implicitInheritCalls(fs.readFileSync(file, 'utf8'))) offenders.push(`${path.relative(TESTS, file)}:${line}`);
+  }
+  assert.deepEqual(offenders, [], `pass env: spawnEnv(home) from tests/kit/helpers/home-sandbox.mjs, or mark a deliberate exception:\n  ${offenders.join('\n  ')}`);
+});
+
+test('the implicit-inheritance scan sees bare, aliased and required calls and skips strings and nested calls', () => {
+  const src = [
+    "import { spawnSync, execFileSync as run } from 'node:child_process';",
+    "spawnSync('git', ['status']);",
+    "run(process.execPath, ['x'], { cwd: '/tmp' });",
+    "spawnSync('git', ['log'], { env: spawnEnv(home) });",
+    "spawnSync('git', ['log'], { ...opts, env });",
+    "spawnSync('ls'); // spawn-env: inherits (probe)",
+    "const script = \"spawnSync('inner')\";",
+    "spawnSync(process.execPath, ['-e', script, String(spawnSync('x'))], {",
+    "  env: spawnEnv(home),",
+    '});',
+    "require('node:child_process').spawn(process.execPath, ['-e', '']);",
+    'obj.spawnSync(1);',
+    "async function f() { const { execFileSync: ef } = await import('node:child_process'); ef('x'); }",
+    'function exec(x) { return x; }',
+    "exec('not child_process');",
+  ].join('\n');
+  assert.deepEqual(implicitInheritCalls(src), [2, 3, 11, 13]);
+});
+
 const tempHome = (t) => {
   const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-spawn-env-')));
   t.after(() => fs.rmSync(home, { recursive: true, force: true }));
diff --git a/tests/kit/statusline.test.mjs b/tests/kit/statusline.test.mjs
index ac91a5ed..5fce8a59 100644
--- a/tests/kit/statusline.test.mjs
+++ b/tests/kit/statusline.test.mjs
@@ -15,7 +15,7 @@ import { execFileSync } from 'node:child_process';
 import { _setGlobalRootForTest } from '../../src/lib/paths.mjs';
 import { fixStatusline, upstreamCveCounterFabricated } from '../../src/lib/statusline.mjs';
 import { tempDir } from './helpers/temp-dir.mjs';
-import { redirectToolState } from './helpers/home-sandbox.mjs';
+import { redirectToolState, spawnEnv } from './helpers/home-sandbox.mjs';
 
 // The rendered footer caches ruflo-daemon-count.json and ruvnet-brain-kb-size.json
 // in os.tmpdir() for 30 s (src/lib/daemons.mjs, statusline-footer.cjs), shared with
@@ -84,7 +84,7 @@ test('overlay is injected while the upstream defect is present', () => {
 test('injected statusline is syntactically valid', () => {
   const { proj, sl } = fixture({ buggyUpstream: true });
   fixStatusline(proj);
-  execFileSync(process.execPath, ['--check', sl], { stdio: 'ignore' });   // throws on bad syntax
+  execFileSync(process.execPath, ['--check', sl], { stdio: 'ignore' }); // throws on bad syntax; spawn-env: inherits (syntax check only, runs nothing)
 });
 
 test('injection is idempotent — repeated syncs never stack blocks', () => {
@@ -123,7 +123,7 @@ test('bin wrapper prepends real bins ahead of upstream candidates at run time',
   fs.mkdirSync(rufloBin, { recursive: true });
   fs.writeFileSync(path.join(rufloBin, 'ruflo.js'), '');
   fixStatusline(proj);
-  const stdout = execFileSync(process.execPath, [sl], { cwd: proj, encoding: 'utf8' });
+  const stdout = execFileSync(process.execPath, [sl], { cwd: proj, encoding: 'utf8', env: spawnEnv(path.join(path.dirname(proj), 'home')) });
   const real = stdout.indexOf(path.join(rufloBin, 'ruflo.js'));
   const orig = stdout.indexOf('/orig');
   assert.notEqual(real, -1, 'the on-disk bin upstream can never find must be a candidate');
@@ -135,7 +135,7 @@ test('bin wrapper is inert on a template without resolveCliBinCandidates', () =>
   const { proj, sl } = fixture({ buggyUpstream: false });
   fs.writeFileSync(sl, '#!/usr/bin/env node\nlet ver = "3.0.0";\nconsole.log("x")\n');
   fixStatusline(proj);
-  const stdout = execFileSync(process.execPath, [sl], { cwd: proj, encoding: 'utf8' });
+  const stdout = execFileSync(process.execPath, [sl], { cwd: proj, encoding: 'utf8', env: spawnEnv(path.join(path.dirname(proj), 'home')) });
   assert.match(stdout, /^x/, 'typeof guard: the wrapper must not break a template it does not fit');
 });
 
diff --git a/tests/kit/telemetry-cli.test.mjs b/tests/kit/telemetry-cli.test.mjs
index c39fbfa5..2de93560 100644
--- a/tests/kit/telemetry-cli.test.mjs
+++ b/tests/kit/telemetry-cli.test.mjs
@@ -1,4 +1,5 @@
 import { test } from 'node:test';
+import { tempDir } from './helpers/temp-dir.mjs';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -14,7 +15,9 @@ function temporary(t) {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-telemetry-'));
   t.after(() => fs.rmSync(dir, { recursive: true, force: true })); return dir;
 }
-function cli(args) { return spawnSync(process.execPath, [fileURLToPath(bin), 'telemetry', ...args], { encoding: 'utf8' }); }
+// A throwaway home: `ak telemetry` must never reach the developer's real config or state.
+const HOME = tempDir('ak-telemetry-cli-home');
+function cli(args) { return spawnSync(process.execPath, [fileURLToPath(bin), 'telemetry', ...args], { encoding: 'utf8', env: spawnEnv(HOME) }); }
 
 test('should_advertiseTelemetry_when_requestingCommandHelp', () => {
   assert.match(cli(['--help']).stdout, /ak telemetry export/);
diff --git a/tests/kit/upstream-watch-skill.test.mjs b/tests/kit/upstream-watch-skill.test.mjs
index a281c91e..6ad1ee5b 100644
--- a/tests/kit/upstream-watch-skill.test.mjs
+++ b/tests/kit/upstream-watch-skill.test.mjs
@@ -11,7 +11,7 @@ const SKILLS = ['.claude/skills/upstream-status/SKILL.md', '.agents/skills/upstr
 // .gitattributes checks both copies out with LF everywhere; reading them as
 // LF keeps these content checks independent of a clone made without it.
 const readText = (file) => fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
-const ignored = (file) => spawnSync('git', ['check-ignore', '-q', '--no-index', file]).status === 0;
+const ignored = (file) => spawnSync('git', ['check-ignore', '-q', '--no-index', file]).status === 0; // spawn-env: inherits (read-only git query on this checkout)
 
 test('Claude and Codex get the same upstream-status skill', () => {
   const [claude, codex] = SKILLS.map(readText);
@@ -24,7 +24,7 @@ test('Claude and Codex get the same upstream-status skill', () => {
 
 test('both skill copies check out with LF line endings on every platform', () => {
   for (const file of SKILLS) {
-    const out = spawnSync('git', ['check-attr', 'eol', '--', file], { encoding: 'utf8' });
+    const out = spawnSync('git', ['check-attr', 'eol', '--', file], { encoding: 'utf8' }); // spawn-env: inherits (read-only git query on this checkout)
     assert.match(out.stdout, /: eol: lf$/m, `${file} must be pinned to LF in .gitattributes`);
   }
 });
diff --git a/tests/live/codex-context-contract.test.mjs b/tests/live/codex-context-contract.test.mjs
index 8797fbb4..50e59a31 100644
--- a/tests/live/codex-context-contract.test.mjs
+++ b/tests/live/codex-context-contract.test.mjs
@@ -12,10 +12,10 @@ const enabled = process.env.AK_CODEX_CONTEXT_CONFORMANCE === '1';
 const clientVersion = process.env.AK_CODEX_CONTEXT_CLIENT_VERSION ?? '0.154.0';
 for (const [model, expected] of [['gpt-6-astra', 828400], ['gpt-5.6-sol', 828400], ['gpt-5.5', 258400]]) {
   test(`Codex ${clientVersion} native per-model clamp: ${model}`, { skip: !enabled, timeout: 65000 }, t => {
-    assert.equal(spawnSync('codex', ['--version'], { encoding: 'utf8', timeout: 5000 }).stdout.trim(), `codex-cli ${clientVersion}`);
+    assert.equal(spawnSync('codex', ['--version'], { encoding: 'utf8', timeout: 5000 }).stdout.trim(), `codex-cli ${clientVersion}`); // spawn-env: inherits (live: version probe of the installed Codex CLI)
     const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'ak-context-contract-'));
     t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
-    const result = spawnSync('codex', ['exec', '--skip-git-repo-check', '-C', cwd, '-s', 'read-only',
+    const result = spawnSync('codex', ['exec', '--skip-git-repo-check', '-C', cwd, '-s', 'read-only', // spawn-env: inherits (live, opt-in: needs the developer's Codex login and writes a Codex session)
       '-m', model, ...(process.env.AK_CODEX_CONTEXT_USE_CONFIG === '1' ? [] : ['-c', 'model_context_window=1050000']), '-c', 'model_reasoning_effort="low"',
       '--json', 'Reply exactly AK_CAPACITY_OK. Do not call any tools.'], { encoding: 'utf8', timeout: 55000, maxBuffer: 4 * 1024 * 1024 });
     assert.equal(result.status, 0, 'native smoke request must complete');
diff --git a/tests/live/qe-court-participant-transport.test.mjs b/tests/live/qe-court-participant-transport.test.mjs
index c4484c14..ac2122c0 100644
--- a/tests/live/qe-court-participant-transport.test.mjs
+++ b/tests/live/qe-court-participant-transport.test.mjs
@@ -40,7 +40,7 @@ checkedPositiveInteger(timeoutMs, 'AK_QE_COURT_SEAT_TIMEOUT_MS');
 checkedPositiveInteger(trials, 'AK_QE_COURT_TRIALS');
 
 function fingerprint(dir) {
-  const result = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], { cwd: dir, encoding: 'utf8' });
+  const result = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], { cwd: dir, encoding: 'utf8' }); // spawn-env: inherits (read-only git status of a throwaway folder)
   assert.equal(result.status, 0, result.stderr);
   return result.stdout;
 }
diff --git a/tests/live/qe-court-public-contract.test.mjs b/tests/live/qe-court-public-contract.test.mjs
index d7137fe0..46a351fd 100644
--- a/tests/live/qe-court-public-contract.test.mjs
+++ b/tests/live/qe-court-public-contract.test.mjs
@@ -7,7 +7,7 @@ import { globalRoot } from '../../src/lib/paths.mjs';
 
 const bin = process.env.AQE_COURT_BIN ?? 'aqe-court-referee';
 function run(args) {
-  const result = spawnSync(bin, args, { encoding: 'utf8', timeout: 10_000 });
+  const result = spawnSync(bin, args, { encoding: 'utf8', timeout: 10_000 }); // spawn-env: inherits (live, opt-in: runs the installed referee as a user would)
   assert.equal(result.status, 0, result.stderr || result.error?.message);
   return JSON.parse(result.stdout);
 }
diff --git a/tests/live/ruflo-memory-routing.test.mjs b/tests/live/ruflo-memory-routing.test.mjs
index e5113d24..6bccc78c 100644
--- a/tests/live/ruflo-memory-routing.test.mjs
+++ b/tests/live/ruflo-memory-routing.test.mjs
@@ -20,7 +20,7 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { sandboxHome, rmrf } from '../kit/helpers/home-sandbox.mjs';
 
-const hasRuflo = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['ruflo'], { stdio: 'ignore' }).status === 0;
+const hasRuflo = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['ruflo'], { stdio: 'ignore' }).status === 0; // spawn-env: inherits (PATH probe for an installed ruflo)
 // sandboxHome() also blanks PATH; the real `ruflo`, `git` and `npm` are needed, so PATH is restored.
 const realPath = process.env.PATH;
 const home = sandboxHome('ak-live-routing');

From 4429faea8ce28c5fff029208bbd9f85a718713d3 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:52:17 -0700
Subject: [PATCH 20/28] docs(audit): add the Branch 2 implementation status

The audit record carried Branch 2 only as inline notes under Open items. A
new section records the guarded runner and tripwire, the watched paths, the
isolation helpers, the plan-item-5 replacement, the commits, the gate-1,
adversarial and post-fix runner results with their fingerprint evidence, and
what stays unproven.
---
 ...-237-238-239-verification-and-decisions.md | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 542bad0c..5833f492 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1281,6 +1281,99 @@ Behavior that differs from, or goes beyond, the plan text.
 - The end gates from "Gates" above: AQE coverage-gap analysis and an adversarial review of the full
   diff.
 
+## Implementation status (fix/test-hermeticity)
+
+This section records Branch 2 of the remediation program
+(`docs/superpowers/plans/2026-09-26-remediation-program.md`, "Branch 2: fix/test-hermeticity") on
+the local branch `fix/test-hermeticity`, built from `be1c1d47`. The code-level plan is
+`docs/superpowers/plans/2026-09-27-branch-2-test-hermeticity.md`. The branch is not merged, and
+nothing was pushed, released or posted. The inline "Fixed on `fix/test-hermeticity`" notes under
+"Open items" above point here.
+
+### What it built
+
+- **Guarded runner.** `pnpm test` and `pnpm run test:ui` run through `scripts/run-tests.mjs`. It
+  snapshots real user state before and after the run with `scripts/real-state-tripwire.mjs`, runs
+  every command with `TMPDIR`/`TEMP`/`TMP` pointed at a fresh `ak-suite-*` folder, and exits 3 on a
+  changed path, 4 on a leftover temporary folder and 2 when that folder is inside a git repository.
+  `node scripts/run-tests.mjs exec -- <node args>` guards a single command.
+- **Watched paths.** ak's config and state folders (XDG and Windows bases); `~/.claude/CLAUDE.md`,
+  `~/.claude/settings.json`, `~/.claude.json`, `~/.codex/AGENTS.md`, `~/.codex/config.toml` and the
+  OpenCode `AGENTS.md`; the repository's root `CLAUDE.md`, `AGENTS.md` and `.mcp.json`; and its
+  `.claude`, `.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` folders. Skills, agents and
+  plugin folders, `opencode.json`, the Hermes home and `~/.claude-flow/memory` are not watched.
+  Writers a live Claude Code, Ruflo or AQE session runs (including `~/.claude.json`) are listed but
+  do not fail a local run; CI and `AK_TRIPWIRE_STRICT=1` fail on them.
+- **Isolation helpers.** `spawnEnv(home)` builds every spawned child's environment with all
+  per-user bases inside a sandbox home; `redirectToolState()` does the same for in-process tests
+  whose code spawns OpenCode; `tempDir()` makes temporary folders that remove themselves.
+  `tests/kit/spawn-env-guard.test.mjs` fails on a spread of `process.env` and on a
+  `child_process` call with no `env` option unless the line states why it inherits.
+- **Product fixes found on the way.** The dashboard server refuses its default maintenance service
+  and management facade when a test injects any collector without a control root. A closing health
+  dialog no longer pulls focus off the next badge. The Maintenance results list is marked busy
+  while an inventory query runs.
+
+### Plan item 5 replaced
+
+Plan item 5 ("create temporary folders from a template", because macOS `mktemp -d` ignores
+`TMPDIR`) did not apply: no test uses shell `mktemp`, and Node's `fs.mkdtempSync(os.tmpdir())`
+honours `TMPDIR`. The branch replaced it with the runner's own `ak-suite-*` temporary root and the
+leftover failure (`7608295c`), plus `tempDir()` for the 59 test files that left more than 700
+folders behind per run (`1fa55698`).
+
+### Commits
+
+| SHA | Title |
+| --- | --- |
+| `5821f233` | docs(plan): Branch 2 test hermeticity code-level plan |
+| `6a7f87e8` | test(guard): fingerprint real user state on every platform |
+| `9782be1e` | test(guard): fail the suite when real user state changes |
+| `a67d2842` | fix(dashboard): refuse default maintenance and management services in injected test servers |
+| `35371328` | test(env): stop spawn tests inheriting the developer's XDG_* variables |
+| `43f235fc` | test(opencode): stop six tests creating $XDG_STATE_HOME/opencode |
+| `1fa55698` | test(temp): remove every temporary folder a test creates |
+| `7608295c` | test(runner): run the suite in its own temporary folder and fail on leftovers |
+| `23f947b5` | test(isolation): never write an enclosing repository from a temp project |
+| `6841f5b9` | test(live): run the memory-routing live test in a disposable home |
+| `4cfb7dbe` | test(ui): check polyglot cards against all-language wrapping and run both Maintenance specs in test:ui |
+| `da94a5ea` | fix(dashboard): keep a closing health dialog from pulling focus off the next badge |
+| `3fac1601` | fix(maintenance): mark the results list busy while an inventory query runs |
+| `b98f18d7` | docs(audit): record Branch 2 hermeticity fixes |
+| `35761c1b` | test(opencode): keep the three in-process tests out of the real config base |
+| `3fea2b1c` | docs(maintainer): describe the guarded test runner and isolation helpers |
+| `7d68c608` | test(opencode): say the tool-state redirect covers the config base too |
+| `6816b674` | fix(tripwire): watch the host and repo-root files ak writes and say what stays unwatched |
+| `916cf571` | test(spawn-env): fail on child_process calls that inherit process.env implicitly |
+
+### Results
+
+- **Gate 1 at `7d68c608` (2026-09-27), plain `node --test` as the program gate set runs it.** Kit
+  suite on Node 26.4.0, twice: 5141 tests, 5135 pass, 0 fail, 6 skipped (Windows-only tests). Node
+  22.22.3: 5134 pass, 0 fail, 7 skipped (the seventh is the stock-OpenCode test, which finds no
+  OpenCode under `mise exec`). Coverage 93.82 lines, 82.44 branches, 93.02 functions (threshold
+  70). The seven `.cjs` suites, `tsc`, both ESLint runs (0 errors), markdownlint (0 issues in 167
+  files), `build-check`, `dashboard-ui` (495 passed) and the seven UI specs all passed.
+- **Through the runner at `7d68c608` (adversarial review).** `node scripts/run-tests.mjs unit` exited
+  0 on Node 26.4.0, 24.20.0 and 22.22.3 with no changed path and no leftover folder;
+  `node scripts/run-tests.mjs ui` exited 0 with `dashboard-ui` 495 passed and 14 UI tests passed. A
+  probe that wrote into a watched root failed the run with exit 3 and named both paths.
+- **Through the runner after the review fixes (`916cf571`).** `node scripts/run-tests.mjs unit` on
+  Node 26.4.0 exited 0: 5145 tests, 5139 pass, 0 fail, 6 skipped; coverage 93.81 / 82.43 / 93.02;
+  the seven `.cjs` suites passed. It watched 20 roots and listed one concurrent writer,
+  `~/.claude.json`, rewritten by the Claude Code session running alongside it.
+- **Fingerprint.** The program's `fingerprint.sh` output was identical before and after each gate-1
+  pass, across both passes and across the whole gate set; identical across all four adversarial
+  runner runs; and identical before and after the post-fix runner run above.
+
+### Not proven
+
+- Windows: the `%APPDATA%`/`%LOCALAPPDATA%` roots and the case-insensitive root merge have unit
+  tests only.
+- The leftover check for `test:ui` on Linux and Windows, where Chromium may leave profile folders.
+- A test that rewrites `~/.claude.json` is reported, not failed, in a developer run; only a strict
+  run (CI) fails it.
+
 ## Addendum 3 — daemon, stray stores, verification, upstream watch and product names (same day)
 
 The implementation lanes returned seven further findings, and the maintainer asked two new

From 1022502c3748a1bab989b2cbc3dbd55ff40a2023 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 10:56:08 -0700
Subject: [PATCH 21/28] fix(tripwire): watch ~/.codex as well as CODEX_HOME and
 name the in-process helpers

ak writes ~/.codex/AGENTS.md and config.toml whatever CODEX_HOME says
(src/lib/paths.mjs:58-60), so the tripwire watched the wrong files when a
developer exported CODEX_HOME. It now watches both homes; the dedupe keeps
one when they match. The header, AGENTS.md and the audit record also name
sandboxHome() and redirectToolState(), which keep in-process tests away from
the unwatched tool paths.
---
 AGENTS.md                                        |  2 +-
 ...ues-237-238-239-verification-and-decisions.md |  6 +++++-
 scripts/real-state-tripwire.mjs                  | 16 +++++++++-------
 tests/kit/real-state-tripwire.test.mjs           | 10 ++++++++++
 4 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3bfc0386..42dbb7d4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -289,7 +289,7 @@ Windows), `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude.json`,
 `.claude-flow` and `.harness` before and after the run. Any change fails the run and is listed
 by path. Other tool paths (skills, agents and plugin folders, `opencode.json`, the Hermes home,
 `~/.claude-flow/memory`) are not fingerprinted; `spawnEnv()` keeps spawned children away from
-them. Files a live Claude Code, Ruflo or AQE session writes during the run (including Claude
+them, and `sandboxHome()` and `redirectToolState()` do the same for in-process code. Files a live Claude Code, Ruflo or AQE session writes during the run (including Claude
 Code's own `~/.claude.json`) are listed as "concurrent writers" and do not fail a local run; CI
 (or `AK_TRIPWIRE_STRICT=1`) fails on them too. Every command also runs with
 `TMPDIR`/`TEMP`/`TMP` pointed at a fresh `ak-suite-*` folder: anything left in it afterwards fails the run and is
diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 5833f492..55eb1a7b 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1301,7 +1301,9 @@ nothing was pushed, released or posted. The inline "Fixed on `fix/test-hermetici
   `~/.claude/settings.json`, `~/.claude.json`, `~/.codex/AGENTS.md`, `~/.codex/config.toml` and the
   OpenCode `AGENTS.md`; the repository's root `CLAUDE.md`, `AGENTS.md` and `.mcp.json`; and its
   `.claude`, `.swarm`, `.agentic-qe`, `.claude-flow` and `.harness` folders. Skills, agents and
-  plugin folders, `opencode.json`, the Hermes home and `~/.claude-flow/memory` are not watched.
+  plugin folders, `opencode.json`, the Hermes home and `~/.claude-flow/memory` are not watched;
+  the isolation helpers below keep tests away from them. When `CODEX_HOME` is set, its
+  `AGENTS.md` and `config.toml` are watched as well as `~/.codex`.
   Writers a live Claude Code, Ruflo or AQE session runs (including `~/.claude.json`) are listed but
   do not fail a local run; CI and `AK_TRIPWIRE_STRICT=1` fail on them.
 - **Isolation helpers.** `spawnEnv(home)` builds every spawned child's environment with all
@@ -1345,6 +1347,8 @@ folders behind per run (`1fa55698`).
 | `7d68c608` | test(opencode): say the tool-state redirect covers the config base too |
 | `6816b674` | fix(tripwire): watch the host and repo-root files ak writes and say what stays unwatched |
 | `916cf571` | test(spawn-env): fail on child_process calls that inherit process.env implicitly |
+| `520de5ac` | docs(audit): add the Branch 2 implementation status |
+| (this commit) | fix(tripwire): watch ~/.codex as well as CODEX_HOME and name the in-process helpers |
 
 ### Results
 
diff --git a/scripts/real-state-tripwire.mjs b/scripts/real-state-tripwire.mjs
index 4eb951e0..a78d8ed0 100644
--- a/scripts/real-state-tripwire.mjs
+++ b/scripts/real-state-tripwire.mjs
@@ -8,10 +8,11 @@
 // AGENTS.md and .mcp.json; and its .claude/.swarm/.agentic-qe/.claude-flow/
 // .harness folders. Not watched: skills, agents and plugin folders in those
 // homes, opencode.json, the Hermes home, ~/.claude-flow/memory and every other
-// tool path; spawnEnv() (tests/kit/helpers/home-sandbox.mjs) is what keeps
-// spawned children away from those. Four incidents wrote real state
-// (statusline version + env pins in the repo's .claude, the maintenance state,
-// a heal receipt); this turns the next one into a failure.
+// tool path. Tests are kept away from those by the helpers in
+// tests/kit/helpers/home-sandbox.mjs: spawnEnv() for spawned children,
+// sandboxHome() and redirectToolState() for in-process code. Four incidents
+// wrote real state (statusline version + env pins in the repo's .claude, the
+// maintenance state, a heal receipt); this turns the next one into a failure.
 // Imports only builtins: src/lib/paths.mjs snapshots os.homedir() at module
 // scope and must never be loaded here. Node 22.13+.
 import crypto from 'node:crypto';
@@ -53,7 +54,9 @@ export function realStateRoots({ env = process.env, platform = process.platform,
     ? env.APPDATA || p.join(homedir, 'AppData', 'Roaming')
     : env.XDG_CONFIG_HOME || p.join(homedir, '.config');
   const claudeHome = env.CLAUDE_CONFIG_DIR || p.join(homedir, '.claude');
-  const codexHome = env.CODEX_HOME || p.join(homedir, '.codex');
+  // ak writes ~/.codex (src/lib/paths.mjs:58-60); Codex itself honours CODEX_HOME.
+  // Watch both; the dedupe below collapses them when they are the same folder.
+  const codexHomes = [p.join(homedir, '.codex'), env.CODEX_HOME].filter(Boolean);
   const roots = [
     ...configBases.filter(Boolean).map((base) => ({ kind: 'config', dir: p.join(base, 'agentic-kit') })),
     ...stateBases.filter(Boolean).map((base) => ({ kind: 'state', dir: p.join(base, 'agentic-kit') })),
@@ -62,8 +65,7 @@ export function realStateRoots({ env = process.env, platform = process.platform,
     { kind: 'user-file', dir: p.join(claudeHome, 'CLAUDE.md') },
     { kind: 'user-file', dir: p.join(claudeHome, 'settings.json') },
     { kind: 'user-file', dir: p.join(homedir, '.claude.json') },
-    { kind: 'user-file', dir: p.join(codexHome, 'AGENTS.md') },
-    { kind: 'user-file', dir: p.join(codexHome, 'config.toml') },
+    ...codexHomes.flatMap((dir) => ['AGENTS.md', 'config.toml'].map((name) => ({ kind: 'user-file', dir: p.join(dir, name) }))),
     { kind: 'user-file', dir: p.join(primaryConfig, 'opencode', 'AGENTS.md') },
     // Project files ak writes at the repository root (src/lib/project-guidance.mjs,
     // the Codex AGENTS.md target in src/lib/blocks.mjs, .mcp.json in src/commands/setup.mjs).
diff --git a/tests/kit/real-state-tripwire.test.mjs b/tests/kit/real-state-tripwire.test.mjs
index 604bd237..68504627 100644
--- a/tests/kit/real-state-tripwire.test.mjs
+++ b/tests/kit/real-state-tripwire.test.mjs
@@ -58,6 +58,16 @@ test('CLAUDE_CONFIG_DIR moves settings.json but not ~/.claude.json, which Claude
   assert.ok(!dirs.includes('user-file:/home/dev/.claude/settings.json'));
 });
 
+test('CODEX_HOME adds its files without dropping ~/.codex, which is where ak writes (src/lib/paths.mjs:58-60)', () => {
+  const dirs = realStateRoots({
+    platform: 'linux', homedir: '/home/dev', repoRoot: '/src/kit', env: { CODEX_HOME: '/cx' },
+  }).map((r) => `${r.kind}:${r.dir}`);
+  for (const want of ['user-file:/cx/AGENTS.md', 'user-file:/cx/config.toml',
+    'user-file:/home/dev/.codex/AGENTS.md', 'user-file:/home/dev/.codex/config.toml']) {
+    assert.ok(dirs.includes(want), `missing ${want}`);
+  }
+});
+
 test('a rewritten repo-root guidance or MCP file is failing, even outside strict mode', (t) => {
   const home = tmp(t, 'ak-trip-repofile');
   const repo = path.join(home, 'repo');

From 3201916e50778c8a611d7e1dfa474bdeb2aa1e4e Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:24:44 -0700
Subject: [PATCH 22/28] test(runner): accept either path separator in the
 tripwire report assertion

The report names native absolute paths, so on Windows the changed file reads
...\maintenance\latest-scan.json and /maintenance\// never matched.
---
 tests/kit/run-tests-runner.test.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/kit/run-tests-runner.test.mjs b/tests/kit/run-tests-runner.test.mjs
index 21fbeba3..5b8f1c63 100644
--- a/tests/kit/run-tests-runner.test.mjs
+++ b/tests/kit/run-tests-runner.test.mjs
@@ -31,8 +31,8 @@ test('a command that writes real state fails the run and the path is named', (t)
   const r = spawnSync(process.execPath, [RUNNER, 'exec', '--repo', repo, '--', leak], { env, encoding: 'utf8' });
   assert.equal(r.status, 3, r.stdout + r.stderr);
   assert.match(r.stderr, /real-state tripwire: watching \d+ roots \(strict\)/);
-  assert.match(r.stderr, /latest-scan\.json/);
-  assert.match(r.stderr, /maintenance\//);
+  // The report prints native absolute paths: backslashes on Windows.
+  assert.match(r.stderr, /[\\/]maintenance[\\/]latest-scan\.json/);
 });
 
 test('a write into the repository .claude fails the run', (t) => {

From 1aced47035396fbec38a4c16edec592384435562 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:26:05 -0700
Subject: [PATCH 23/28] test(spawn-env): match variable names
 case-insensitively on Windows

A copy of process.env keeps Windows spellings (Path, SystemRoot, sometimes
Temp), so spawnEnv's exact-name delete and override could leave the parent
value beside a second spelling, and env.PATH read undefined on the copy.
spawnEnv now folds names on win32, keeps the parent spelling of a replaced
key, and takes an injectable env and platform; envValue() reads a name the
way the platform does.
---
 tests/kit/helpers/home-sandbox.mjs | 42 ++++++++++++++++++++++++++----
 tests/kit/spawn-env-guard.test.mjs | 34 ++++++++++++++++++++++--
 2 files changed, 69 insertions(+), 7 deletions(-)

diff --git a/tests/kit/helpers/home-sandbox.mjs b/tests/kit/helpers/home-sandbox.mjs
index 86e55e37..22959b7c 100644
--- a/tests/kit/helpers/home-sandbox.mjs
+++ b/tests/kit/helpers/home-sandbox.mjs
@@ -51,18 +51,50 @@ export function sandboxEnvFor(home) {
 }
 
 /**
- * The environment for a spawned child: process.env minus INHERITED_STATE_KEYS,
+ * Read `key` from a plain env object the way the platform does: Windows
+ * variable names are case-insensitive (the search path is usually `Path`).
+ * @param {Record<string, string|undefined>} env
+ * @param {string} key
+ * @param {string} [platform]
+ * @returns {string|undefined}
+ */
+export function envValue(env, key, platform = process.platform) {
+  if (platform !== 'win32') return env[key];
+  const upper = key.toUpperCase();
+  const name = Object.keys(env).find((k) => k.toUpperCase() === upper);
+  return name === undefined ? undefined : env[name];
+}
+
+/**
+ * The environment for a spawned child: the parent env minus INHERITED_STATE_KEYS,
  * plus sandboxEnvFor(home), plus `extra` (last wins). PATH is kept. Creates
  * `home/tmp` so the child's os.tmpdir() exists.
+ * On Windows names are matched case-insensitively: a copy of process.env keeps
+ * the stored spelling (`Path`, `SystemRoot`, sometimes `Temp`), so an exact-name
+ * delete or override would leave the parent's value beside a second spelling.
+ * A key that replaces a parent key keeps the parent's spelling; read one with
+ * envValue().
  * @param {string} home
  * @param {Record<string, string|undefined>} [extra]
+ * @param {{ env?: Record<string, string|undefined>, platform?: string }} [o] injectable for tests
  * @returns {Record<string, string|undefined>}
  */
-export function spawnEnv(home, extra = {}) {
-  const base = { ...process.env }; // spawn-env: inherits (the one sanctioned copy; state keys are removed below)
-  for (const key of INHERITED_STATE_KEYS) delete base[key];
+export function spawnEnv(home, extra = {}, { env = process.env, platform = process.platform } = {}) {
+  const fold = platform === 'win32' ? (key) => key.toUpperCase() : (key) => key;
+  const state = new Set(INHERITED_STATE_KEYS.map(fold));
+  const out = {};
+  const names = new Map(); // folded name -> the spelling stored in `out`
+  const put = (key, value) => {
+    const name = names.get(fold(key)) ?? key;
+    if (value === undefined) { delete out[name]; names.delete(fold(key)); return; }
+    out[name] = value;
+    names.set(fold(key), name);
+  };
+  // The one sanctioned copy of the parent env; per-user state keys are dropped.
+  for (const [key, value] of Object.entries(env)) if (!state.has(fold(key))) put(key, value);
+  for (const [key, value] of Object.entries({ ...sandboxEnvFor(home), ...extra })) put(key, value);
   fs.mkdirSync(path.join(home, 'tmp'), { recursive: true });
-  return { ...base, ...sandboxEnvFor(home), ...extra };
+  return out;
 }
 
 /**
diff --git a/tests/kit/spawn-env-guard.test.mjs b/tests/kit/spawn-env-guard.test.mjs
index 7b394204..04012292 100644
--- a/tests/kit/spawn-env-guard.test.mjs
+++ b/tests/kit/spawn-env-guard.test.mjs
@@ -19,7 +19,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { spawnEnv, sandboxEnvFor, INHERITED_STATE_KEYS } from './helpers/home-sandbox.mjs';
+import { spawnEnv, sandboxEnvFor, envValue, INHERITED_STATE_KEYS } from './helpers/home-sandbox.mjs';
 
 const TESTS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SELF = fileURLToPath(import.meta.url);
@@ -169,12 +169,42 @@ test('spawnEnv pins every per-user base inside the sandbox, whatever the parent
   for (const key of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH']) {
     assert.equal(env[key], undefined, `${key} must not be inherited`);
   }
-  assert.equal(env.PATH, process.env.PATH);
+  // Windows stores the search path as `Path`; a plain-object copy keeps that spelling.
+  assert.equal(envValue(env, 'PATH'), process.env.PATH);
   assert.equal(env.EXTRA, '1');
   assert.deepEqual(Object.keys(sandboxEnvFor(home)).sort(),
     INHERITED_STATE_KEYS.filter((k) => !['CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'HERMES_HOME', 'CLAUDE_FLOW_DB_PATH', 'CLAUDE_FLOW_MEMORY_PATH'].includes(k)).sort());
 });
 
+test('on Windows spawnEnv keeps the parent spelling of each variable and never doubles one by case', (t) => {
+  const home = tempHome(t);
+  const parent = { Path: 'C:\\bin', PATHEXT: '.COM;.EXE', SystemRoot: 'C:\\Windows', ComSpec: 'C:\\Windows\\cmd.exe',
+    Temp: 'C:\\real\\tmp', tmp: 'C:\\real\\tmp', LocalAppData: 'C:\\real\\local', xdg_state_home: 'C:\\real\\state',
+    Codex_Home: 'C:\\real\\codex' };
+  const env = spawnEnv(home, { PATH: 'C:\\fake;C:\\bin', SYSTEMROOT: 'C:\\Win' }, { env: parent, platform: 'win32' });
+  const folded = Object.keys(env).map((k) => k.toUpperCase());
+  assert.deepEqual(folded.filter((k, i) => folded.indexOf(k) !== i), [], `duplicate keys: ${Object.keys(env).join(', ')}`);
+  assert.equal(env.Path, 'C:\\fake;C:\\bin', 'extra PATH replaces the parent Path under its spelling');
+  assert.equal(env.SystemRoot, 'C:\\Win');
+  assert.equal(env.PATHEXT, '.COM;.EXE');
+  assert.equal(env.ComSpec, 'C:\\Windows\\cmd.exe');
+  for (const key of ['TEMP', 'TMP', 'LOCALAPPDATA', 'XDG_STATE_HOME']) {
+    assert.ok(envValue(env, key, 'win32').startsWith(home), `${key}=${envValue(env, key, 'win32')} escapes ${home}`);
+  }
+  assert.equal(envValue(env, 'CODEX_HOME', 'win32'), undefined);
+  assert.equal(envValue(env, 'path', 'win32'), 'C:\\fake;C:\\bin');
+  assert.equal(envValue(env, 'path', 'linux'), undefined, 'POSIX names are case-sensitive');
+});
+
+test('on POSIX spawnEnv treats names that differ by case as different variables', (t) => {
+  const home = tempHome(t);
+  const env = spawnEnv(home, {}, { env: { PATH: '/usr/bin', Path: 'other', tmpdir: 'kept' }, platform: 'linux' });
+  assert.equal(env.PATH, '/usr/bin');
+  assert.equal(env.Path, 'other');
+  assert.equal(env.tmpdir, 'kept');
+  assert.ok(env.TMPDIR.startsWith(home));
+});
+
 test('a real child sees the sandboxed state base, not the parent one', (t) => {
   const home = tempHome(t);
   const r = spawnSync(process.execPath, ['-e', 'console.log(JSON.stringify([process.env.XDG_STATE_HOME, require("os").tmpdir()]))'],

From 93a2c7303718d1b3219657b30160f12a76728174 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:26:40 -0700
Subject: [PATCH 24/28] fix(telemetry): compare file identity as BigInt so
 Windows file IDs stay exact

NTFS file IDs put a sequence number in the top 16 bits and exceed 2^53 once it
reaches 32. As Numbers, two files one record apart can read as the same inode,
so the replaced-file check could pass a swapped file; the test's stat.ino++ mock
is a no-op for the same reason, the only mechanism consistent with the Windows
Node 26 failure.
---
 src/lib/telemetry/store.mjs      | 13 ++++++++-----
 tests/kit/telemetry-cli.test.mjs | 13 +++++++++++++
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/src/lib/telemetry/store.mjs b/src/lib/telemetry/store.mjs
index e042200d..487b590c 100644
--- a/src/lib/telemetry/store.mjs
+++ b/src/lib/telemetry/store.mjs
@@ -3,25 +3,28 @@ import path from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { MAX_FILE_BYTES } from './schema.mjs';
 
-/** Read only bounded regular files; refuse final-component links and detect replacement races. */
+/** Read only bounded regular files; refuse final-component links and detect replacement races.
+ *  Identity is compared as BigInt: Windows file IDs can exceed 2^53, where two
+ *  different files can read as the same Number inode. */
 export function readJsonDocument(file, maxBytes = MAX_FILE_BYTES) {
   const absolute = path.resolve(file);
-  const before = fs.lstatSync(absolute);
+  const before = fs.lstatSync(absolute, { bigint: true });
   if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) throw new Error('Telemetry file exceeds safe bounds');
   const fd = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
-    const stat = fs.fstatSync(fd);
+    const stat = fs.fstatSync(fd, { bigint: true });
     if (!stat.isFile() || stat.ino !== before.ino || stat.dev !== before.dev || stat.size > maxBytes) {
       throw new Error('Telemetry file exceeds safe bounds');
     }
-    const buffer = Buffer.alloc(Math.min(stat.size + 1, maxBytes + 1));
+    const statSize = Number(stat.size); // bounded by maxBytes above
+    const buffer = Buffer.alloc(Math.min(statSize + 1, maxBytes + 1));
     let size = 0;
     while (size < buffer.length) {
       const n = fs.readSync(fd, buffer, size, buffer.length - size, null);
       if (!n) break;
       size += n;
     }
-    if (size > maxBytes || size > stat.size) throw new Error('Telemetry file exceeds safe bounds');
+    if (size > maxBytes || size > statSize) throw new Error('Telemetry file exceeds safe bounds');
     try { return { value: JSON.parse(buffer.subarray(0, size).toString('utf8')), bytes: size }; }
     catch { throw new Error('Invalid telemetry JSON'); }
   } finally { fs.closeSync(fd); }
diff --git a/tests/kit/telemetry-cli.test.mjs b/tests/kit/telemetry-cli.test.mjs
index 2de93560..f7f2ad7b 100644
--- a/tests/kit/telemetry-cli.test.mjs
+++ b/tests/kit/telemetry-cli.test.mjs
@@ -158,6 +158,19 @@ test('should_rejectReplacedFiles_when_openedInodeDiffers', async t => {
   t.mock.method(fs, 'fstatSync', (...args) => { const stat = original(...args); stat.ino++; return stat; });
   assert.throws(() => readJsonFile(file), /bounds/);
 });
+// NTFS file IDs carry a sequence number in the top 16 bits, so they can exceed
+// 2^53: as Numbers, two files one record apart read as the same inode.
+test('should_rejectReplacedFiles_when_fileIdsExceedDoublePrecision', async t => {
+  const { readJsonFile } = await import(storePath); const file = path.join(temporary(t), 'data.json');
+  fs.writeFileSync(file, '{}');
+  const ntfsId = (index) => (64n << 48n) + index;
+  const withIno = (stat, ino, opts) => { stat.ino = opts?.bigint ? ino : Number(ino); return stat; };
+  const lstat = fs.lstatSync; const fstat = fs.fstatSync;
+  t.mock.method(fs, 'lstatSync', (p, opts) => withIno(lstat(p, opts), ntfsId(12344n), opts));
+  t.mock.method(fs, 'fstatSync', (fd, opts) => withIno(fstat(fd, opts), ntfsId(12345n), opts));
+  assert.equal(Number(ntfsId(12344n)), Number(ntfsId(12345n)), 'the two IDs collide as Numbers');
+  assert.throws(() => readJsonFile(file), /bounds/);
+});
 test('should_rejectPublicIdentityDirectory_when_permissionsAreLoose', { skip: process.platform === 'win32' }, async t => {
   const { readOrCreateIdentity } = await import(storePath); const dir = temporary(t); fs.chmodSync(dir, 0o755);
   assert.throws(() => readOrCreateIdentity(dir), /private/);

From 93040851760cb207477ed5514a4e6c21ef547996 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:30:07 -0700
Subject: [PATCH 25/28] test(ui): give each Chrome its own temp folder and
 remove it on close

System Chrome leaves com.google.Chrome.chrome_chrome_url_fetcher_.* folders in
its temp dir. On Linux that is TMPDIR, the runner's suite temp root, so the
leftover check failed the ui job on 14 of them. launchChrome() points TMPDIR,
TEMP, TMP and MAC_CHROMIUM_TMPDIR (macOS Chrome ignores TMPDIR) at a folder it
removes on browser.close(); every UI test launches through it, and a unit test
keeps it that way. The runner's leftover check stays strict.
---
 tests/kit/ui-chrome-launch.test.mjs     | 62 +++++++++++++++++++++++++
 tests/ui/context-coverage.mjs           |  6 +--
 tests/ui/dashboard-project-context.mjs  |  4 +-
 tests/ui/dashboard-ui.mjs               |  4 +-
 tests/ui/helpers/launch-chrome.mjs      | 33 +++++++++++++
 tests/ui/host-readiness.mjs             |  8 ++--
 tests/ui/intelligence-picker.mjs        |  6 +--
 tests/ui/maintenance-focus.mjs          |  6 +--
 tests/ui/maintenance-guidance.mjs       |  4 +-
 tests/ui/maintenance-host-alignment.mjs |  4 +-
 tests/ui/maintenance-projects.mjs       |  4 +-
 tests/ui/usage-project-groups.mjs       |  4 +-
 12 files changed, 120 insertions(+), 25 deletions(-)
 create mode 100644 tests/kit/ui-chrome-launch.test.mjs
 create mode 100644 tests/ui/helpers/launch-chrome.mjs

diff --git a/tests/kit/ui-chrome-launch.test.mjs b/tests/kit/ui-chrome-launch.test.mjs
new file mode 100644
index 00000000..f2ee237d
--- /dev/null
+++ b/tests/kit/ui-chrome-launch.test.mjs
@@ -0,0 +1,62 @@
+// tests/kit/ui-chrome-launch.test.mjs
+// System Chrome leaves com.google.Chrome.chrome_chrome_url_fetcher_.* folders in
+// its temp dir; on Linux that is the runner's suite temp root, whose leftover
+// check then fails the UI run. tests/ui/helpers/launch-chrome.mjs gives each
+// browser its own temp folder and removes it on close; this keeps every UI test
+// on that path.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'ui');
+const HELPER = path.join(UI, 'helpers', 'launch-chrome.mjs');
+
+function files(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) files(full, out); else if (/\.(mjs|cjs|js)$/.test(e.name)) out.push(full);
+  }
+  return out;
+}
+
+test('every UI test launches Chrome through launchChrome()', () => {
+  const offenders = [];
+  for (const file of files(UI)) {
+    if (file === HELPER) continue;
+    fs.readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+      if (/\bchromium\s*\.\s*launch\w*\s*\(/.test(line)) offenders.push(`${path.relative(UI, file)}:${i + 1}`);
+    });
+  }
+  assert.deepEqual(offenders, [], `use launchChrome() from tests/ui/helpers/launch-chrome.mjs:\n  ${offenders.join('\n  ')}`);
+});
+
+test('launchChrome gives Chrome its own temp folder and removes it, fetcher leftovers included, on close', async (t) => {
+  const { chromium } = await import('playwright');
+  const { launchChrome } = await import('../ui/helpers/launch-chrome.mjs');
+  let seen;
+  let closed = 0;
+  t.mock.method(chromium, 'launch', async (options) => { seen = options; return { close: async () => { closed += 1; } }; });
+  const browser = await launchChrome({ headless: false });
+  assert.equal(seen.channel, 'chrome');
+  assert.equal(seen.headless, false, 'caller options win');
+  const dir = seen.env.TMPDIR;
+  for (const key of ['TEMP', 'TMP', 'MAC_CHROMIUM_TMPDIR']) assert.equal(seen.env[key], dir, key);
+  assert.equal(path.dirname(dir), fs.realpathSync(os.tmpdir()));
+  assert.ok(Object.keys(seen.env).some((k) => k.toUpperCase() === 'PATH'), 'the browser keeps its search path');
+  fs.mkdirSync(path.join(dir, 'com.google.Chrome.chrome_chrome_url_fetcher_.AbC123'));
+  await browser.close();
+  assert.equal(closed, 1);
+  assert.equal(fs.existsSync(dir), false, `${dir} survived browser.close()`);
+});
+
+test('launchChrome removes its temp folder when Chrome fails to start', async (t) => {
+  const { chromium } = await import('playwright');
+  const { launchChrome } = await import('../ui/helpers/launch-chrome.mjs');
+  let dir;
+  t.mock.method(chromium, 'launch', async (options) => { dir = options.env.TMPDIR; throw new Error('no chrome'); });
+  await assert.rejects(launchChrome(), /no chrome/);
+  assert.equal(fs.existsSync(dir), false);
+});
diff --git a/tests/ui/context-coverage.mjs b/tests/ui/context-coverage.mjs
index 13dcdd17..abbe8ff6 100644
--- a/tests/ui/context-coverage.mjs
+++ b/tests/ui/context-coverage.mjs
@@ -2,7 +2,7 @@ import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import {chromium} from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import {renderPage} from '../../src/lib/dashboard/page.mjs';
 import {buildContextProjection} from '../../src/lib/usage-context.mjs';
 import {blankSession,noteContextSample} from '../../src/lib/usage-parsers.mjs';
@@ -11,7 +11,7 @@ const claudeSub=blankSession('cs','claude');claudeSub.sidechain=true;
 noteContextSample(claude,326000);noteContextSample(codex,90000,100000);noteContextSample(older,50000);noteContextSample(claudeSub,180000);
 
 test('Context distinguishes input-only, partial paired coverage and no sessions without zero windows',async t=>{
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1440,height:1000}}),errors=[];
  page.on('pageerror',error=>errors.push(error.message));
  const projection=buildContextProjection([claude,codex,older,claudeSub],{windowDays:30});
@@ -49,7 +49,7 @@ test('Context distinguishes input-only, partial paired coverage and no sessions
 });
 
 test('Context pressure tooltips are focusable and state each host formula; empty state follows source health',async t=>{
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1440,height:1000}}),errors=[];
  page.on('pageerror',error=>errors.push(error.message));
  let health={claude:{status:'ok'},codex:{status:'ok'},opencode:{status:'absent',reason:'absent'}};
diff --git a/tests/ui/dashboard-project-context.mjs b/tests/ui/dashboard-project-context.mjs
index 804c83b1..fe969cf5 100644
--- a/tests/ui/dashboard-project-context.mjs
+++ b/tests/ui/dashboard-project-context.mjs
@@ -2,7 +2,7 @@ import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import {chromium} from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import {renderPage} from '../../src/lib/dashboard/page.mjs';
 import {buildContextReport} from '../../src/lib/context-report.mjs';
 
@@ -22,7 +22,7 @@ const report=buildContextReport({integrations:{hosts:{claude:true,codex:true,ope
  cacheFetchedAt:'2026-09-09T14:00:00Z',models:Array.from({length:12},(_,i)=>({model:'model-'+i,nativeWindow:200000,maximumWindow:1000000,effectiveWindow:950000}))},{now:Date.parse(capturedAt),modelSnapshot});
 
 test('context and project grouping stay readable, keyboard operable and evidence-aware',async t=>{
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1440,height:1050}}),errors=[];
  page.on('pageerror',e=>errors.push(e.message));
  let projects={projects:[main],discoveryProjects:[main,work,other],everSeen:measured(3),onDisk:measured(2),count:measured(3)};
diff --git a/tests/ui/dashboard-ui.mjs b/tests/ui/dashboard-ui.mjs
index 827192b3..5fff42c7 100644
--- a/tests/ui/dashboard-ui.mjs
+++ b/tests/ui/dashboard-ui.mjs
@@ -33,7 +33,7 @@ import { fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
 import privateTmpdir from '../kit/helpers/private-tmpdir.cjs';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { startDashboard } from '../../src/lib/dashboard-server.mjs';
 import { readIndex, readSession, maskSecrets } from '../../src/lib/usage-index.mjs';
 import { modelIdentityKey } from '../../src/lib/model-inventory/contracts.mjs';
@@ -1155,7 +1155,7 @@ async function main() {
     + `&sort=lifecycle&direction=asc&relevance=relevant&snapshotId=${encodeURIComponent(modelSnapshotId)}`,
   { headers: modelHeaders }).then((response) => response.json());
 
-  const browser = await chromium.launch({ channel: 'chrome', headless: !HEADED });
+  const browser = await launchChrome({ headless: !HEADED });
 
   // A running full scan carries a long phase/count/elapsed sentence. Wide
   // screens have room for it beside the content-width menu; narrow screens
diff --git a/tests/ui/helpers/launch-chrome.mjs b/tests/ui/helpers/launch-chrome.mjs
new file mode 100644
index 00000000..bb38d9bb
--- /dev/null
+++ b/tests/ui/helpers/launch-chrome.mjs
@@ -0,0 +1,33 @@
+// tests/ui/helpers/launch-chrome.mjs
+// Launch the system Chrome with its own temp folder, removed on browser.close().
+// Chrome's network fetchers create com.google.Chrome.chrome_chrome_url_fetcher_.*
+// folders in its temp dir and never remove them. On Linux that dir is $TMPDIR,
+// which the test runner points at its own suite temp root and checks for
+// leftovers (CI run 36339702575 failed on 14 of them); on macOS Chrome ignores
+// TMPDIR and reads MAC_CHROMIUM_TMPDIR, else the per-user temp dir
+// (Chromium base/files/file_util_mac.mm GetTempDir). Every UI test launches
+// through here so the runner's leftover check stays strict for tests.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { chromium } from 'playwright';
+
+/**
+ * @param {import('playwright').LaunchOptions} [options] merged over { channel: 'chrome', headless: true }
+ * @returns {Promise<import('playwright').Browser>} a browser whose close() also removes Chrome's temp folder
+ */
+export async function launchChrome(options = {}) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'ak-ui-chrome-')));
+  const remove = () => fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  const temp = { TMPDIR: dir, TEMP: dir, TMP: dir, MAC_CHROMIUM_TMPDIR: dir };
+  let browser;
+  try {
+    browser = await chromium.launch({
+      channel: 'chrome', headless: true, ...options,
+      env: { ...process.env, ...temp }, // spawn-env: inherits (the browser needs the display and PATH; only its temp dir moves)
+    });
+  } catch (error) { remove(); throw error; }
+  const close = browser.close.bind(browser);
+  browser.close = async (...args) => { try { await close(...args); } finally { remove(); } };
+  return browser;
+}
diff --git a/tests/ui/host-readiness.mjs b/tests/ui/host-readiness.mjs
index 10c600aa..d8d8f491 100644
--- a/tests/ui/host-readiness.mjs
+++ b/tests/ui/host-readiness.mjs
@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { esc } from '../../src/lib/dashboard/groups.mjs';
 
@@ -21,7 +21,7 @@ const report = () => ({ checkedAt: '2026-09-20T10:00:00Z', scope: 'Dashboard lau
   }])) });
 
 test('all hosts have qualified OK, accessible details and explicitly confirmed connection checks', async t => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
   const errors = [], requests = [];
@@ -107,7 +107,7 @@ const unmanagedReport = () => {
 };
 
 test('unmanaged hosts read their management state everywhere, with information-only checks and a complete enable hint', async t => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
   const errors = [], requests = [];
@@ -192,7 +192,7 @@ test('unmanaged hosts read their management state everywhere, with information-o
 });
 
 test('a dialog close that lands after the user moved on does not steal focus back', async t => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
   const errors = [];
diff --git a/tests/ui/intelligence-picker.mjs b/tests/ui/intelligence-picker.mjs
index 1b407bc9..719670d1 100644
--- a/tests/ui/intelligence-picker.mjs
+++ b/tests/ui/intelligence-picker.mjs
@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 
 // Optional source checkout supports isolated implementation/test workers.
 const pageModule = process.env.AK_UI_SOURCE_ROOT
@@ -23,7 +23,7 @@ const projects = [
 ];
 
 test('Intelligence picker labels every learning location with the inventory designation', async t => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1360, height: 980 } });
   const errors = [], requests = [];
@@ -88,7 +88,7 @@ test('Intelligence picker labels every learning location with the inventory desi
 });
 
 test('Intelligence table keeps every learning location in one filterable inventory with stable KPIs', async t => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1360, height: 980 } });
   const errors = [];
diff --git a/tests/ui/maintenance-focus.mjs b/tests/ui/maintenance-focus.mjs
index 384ef044..42bbe142 100644
--- a/tests/ui/maintenance-focus.mjs
+++ b/tests/ui/maintenance-focus.mjs
@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
 import { baseInventory } from '../fixtures/maintenance/management-fixtures.mjs';
@@ -17,7 +17,7 @@ test('focus browser progressively narrows to exact installations and preserves f
  const inventory=structuredClone(baseInventory()),requests=[],errors=[];
  const skillResources=inventory.resources.filter(r=>r.kind==='skill');
  for(const resource of skillResources)resource.presentationFamilyId=skillResources[0].resourceId;
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1440,height:1050}});page.on('pageerror',e=>errors.push(e.message));
  const markup=renderPage({name:'Fixture',version:'test'}).match(/<section class="mnt-panel mnt-inventory"[\s\S]*?<\/section>/)[0];
  await page.route('http://maintenance.test/**',async route=>{
@@ -86,7 +86,7 @@ test('focus browser progressively narrows to exact installations and preserves f
 });
 
 test('polyglot cards show every language as a labelled, wrapping icon with no disclosure',async(t)=>{
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1100,height:650}});
  const errors=[];page.on('pageerror',e=>errors.push(e.message));
  const languages=[['rust','Rust'],['typescript','TypeScript'],['javascript','JavaScript'],['python','Python'],['java','Java']].map(([id,name])=>({id,name,evidence:'source'}));
diff --git a/tests/ui/maintenance-guidance.mjs b/tests/ui/maintenance-guidance.mjs
index 2c0357be..451bc76b 100644
--- a/tests/ui/maintenance-guidance.mjs
+++ b/tests/ui/maintenance-guidance.mjs
@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
 
@@ -16,7 +16,7 @@ function source(name) {
     .replace(/\bexport (?=(?:function|var)\b)/g, '');
 }
 test('guidance has exclusive pills, host context, and no resource selector or optional removal advice', async (t) => {
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1360, height: 1000 } });
   const errors = [];
diff --git a/tests/ui/maintenance-host-alignment.mjs b/tests/ui/maintenance-host-alignment.mjs
index 7cf031df..e64d7002 100644
--- a/tests/ui/maintenance-host-alignment.mjs
+++ b/tests/ui/maintenance-host-alignment.mjs
@@ -4,7 +4,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
 import { buildManagementInventory } from '../../src/lib/maintenance/management/projection.mjs';
@@ -31,7 +31,7 @@ test('Host alignment view filters User and Project rows and offers exact registr
     detections: new Map([['host-alignment', facts]]) }).inventory;
   assert.ok(inventory.guidanceEntries.some(entry => entry.lane === 'apply'), JSON.stringify(inventory.guidanceEntries));
   const markup = renderPage({ name: 'Fixture', version: 'test' }).match(/<section class="mnt-panel mnt-inventory"[\s\S]*?<\/section>/)[0];
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1360, height: 1000 } });
   const errors = [];
diff --git a/tests/ui/maintenance-projects.mjs b/tests/ui/maintenance-projects.mjs
index 1bf88ec6..c7a1ffa5 100644
--- a/tests/ui/maintenance-projects.mjs
+++ b/tests/ui/maintenance-projects.mjs
@@ -4,7 +4,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 import { CSS } from '../../src/lib/dashboard/styles.mjs';
 import { buildManagementInventory } from '../../src/lib/maintenance/management/projection.mjs';
@@ -42,7 +42,7 @@ test('project worktree visibility and all-installations navigation work on deskt
   const inventory = fixture();
   const requests = [];
   const markup = renderPage({ name: 'Fixture', version: 'test' }).match(/<section class="mnt-panel mnt-inventory"[\s\S]*?<\/section>/)[0];
-  const browser = await chromium.launch({ channel: 'chrome', headless: true });
+  const browser = await launchChrome();
   t.after(() => browser.close());
   const page = await browser.newPage({ viewport: { width: 1360, height: 1000 } });
   const errors = [];
diff --git a/tests/ui/usage-project-groups.mjs b/tests/ui/usage-project-groups.mjs
index 5f198182..580b1696 100644
--- a/tests/ui/usage-project-groups.mjs
+++ b/tests/ui/usage-project-groups.mjs
@@ -3,7 +3,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import { chromium } from 'playwright';
+import { launchChrome } from './helpers/launch-chrome.mjs';
 import { renderPage } from '../../src/lib/dashboard/page.mjs';
 
 const gitProjects = Array.from({length:12},(_,index)=>({key:'repo-'+index,label:'Git project '+index,
@@ -11,7 +11,7 @@ const gitProjects = Array.from({length:12},(_,index)=>({key:'repo-'+index,label:
 const totals={cost:1000,sessions:40,spanMinutes:500,tokens:12000};
 
 test('Usage Projects shows top ten Git projects and follows the timeframe without changing overall totals',async t=>{
- const browser=await chromium.launch({channel:'chrome',headless:true});t.after(()=>browser.close());
+ const browser=await launchChrome();t.after(()=>browser.close());
  const page=await browser.newPage({viewport:{width:1440,height:1050}}),errors=[],windows=[];
  page.on('pageerror',error=>errors.push(error.message));
  let legacy=false;

From ad8ea97efbbf10f31789a2e54cfc10744c89f7e6 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:31:05 -0700
Subject: [PATCH 26/28] docs(maintainer): describe launchChrome and
 Windows-aware spawnEnv, record the CI fixes

---
 AGENTS.md                                     |  5 +++--
 MAINTAINER.md                                 | 10 +++++++++-
 ...-237-238-239-verification-and-decisions.md | 19 +++++++++++++++++--
 3 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 42dbb7d4..5acbbef2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -296,8 +296,9 @@ Code's own `~/.claude.json`) are listed as "concurrent writers" and do not fail
 listed, and the runner refuses to start when that folder sits inside a git repository (point
 `TMPDIR` elsewhere). Tests make temporary folders with `tempDir()` from
 `tests/kit/helpers/temp-dir.mjs`, and spawned children get their environment from `spawnEnv()` in
-`tests/kit/helpers/home-sandbox.mjs`. `node scripts/run-tests.mjs exec -- <node args>` guards any
-single command the same way.
+`tests/kit/helpers/home-sandbox.mjs`. UI tests launch Chrome with `launchChrome()` from
+`tests/ui/helpers/launch-chrome.mjs`, which gives the browser its own temp folder and removes it on
+close. `node scripts/run-tests.mjs exec -- <node args>` guards any single command the same way.
 
 ### Test Philosophy
 
diff --git a/MAINTAINER.md b/MAINTAINER.md
index b38d0c0f..7b933a66 100644
--- a/MAINTAINER.md
+++ b/MAINTAINER.md
@@ -272,7 +272,15 @@ Inside the suite, isolation comes from shared helpers:
   line that spreads `process.env` and on a `child_process` call with no `env` option (an
   implicit inherit), unless the line carries `spawn-env: inherits (<reason>)`. It reads
   source text: a call whose options object is built elsewhere needs the marker, and a call
-  through a local wrapper function is not seen.
+  through a local wrapper function is not seen. On Windows `spawnEnv()` matches variable
+  names case-insensitively and keeps the parent's spelling (the search path is usually
+  `Path`), so read a value from its result with `envValue()`.
+- `launchChrome()` (`tests/ui/helpers/launch-chrome.mjs`) starts the system Chrome for UI
+  tests with `TMPDIR`, `TEMP`, `TMP` and `MAC_CHROMIUM_TMPDIR` pointed at its own folder, and
+  removes that folder on `browser.close()`. Chrome leaves
+  `com.google.Chrome.chrome_chrome_url_fetcher_.*` folders in its temp dir, which on Linux
+  would otherwise fail the runner's leftover check. `tests/kit/ui-chrome-launch.test.mjs`
+  fails on a UI test that calls `chromium.launch` directly.
 - `redirectToolState()` (same file) moves the config, state, data, cache and temp bases for
   in-process tests whose code under test spawns real tools such as OpenCode.
 - `tempDir()` (`tests/kit/helpers/temp-dir.mjs`) makes temporary folders that are removed
diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 55eb1a7b..9ce25f43 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1310,7 +1310,10 @@ nothing was pushed, released or posted. The inline "Fixed on `fix/test-hermetici
   per-user bases inside a sandbox home; `redirectToolState()` does the same for in-process tests
   whose code spawns OpenCode; `tempDir()` makes temporary folders that remove themselves.
   `tests/kit/spawn-env-guard.test.mjs` fails on a spread of `process.env` and on a
-  `child_process` call with no `env` option unless the line states why it inherits.
+  `child_process` call with no `env` option unless the line states why it inherits. On Windows
+  `spawnEnv` matches variable names case-insensitively and keeps the parent's spelling (`Path`).
+  UI tests start Chrome through `launchChrome()`, which gives the browser its own temp folder and
+  removes it on close.
 - **Product fixes found on the way.** The dashboard server refuses its default maintenance service
   and management facade when a test injects any collector without a control root. A closing health
   dialog no longer pulls focus off the next badge. The Maintenance results list is marked busy
@@ -1374,7 +1377,19 @@ folders behind per run (`1fa55698`).
 
 - Windows: the `%APPDATA%`/`%LOCALAPPDATA%` roots and the case-insensitive root merge have unit
   tests only.
-- The leftover check for `test:ui` on Linux and Windows, where Chromium may leave profile folders.
+- The leftover check for `test:ui` on Linux: the first CI run (36339702575) failed on 14
+  `com.google.Chrome.chrome_chrome_url_fetcher_.*` folders Chrome left in the suite temp root.
+  `launchChrome()` now moves Chrome's temp dir into a folder it removes; a green Linux `ui` job is
+  still to be seen. On macOS, Chrome reads `MAC_CHROMIUM_TMPDIR` rather than `TMPDIR` and
+  otherwise uses the per-user temp folder, where 681 such folders had built up; that is why local
+  runs never saw them. A local UI run without the helper exited 0 and added 11 folders there; with
+  it, none.
+- The first CI run also failed three tests on Windows: a POSIX-only separator in a runner
+  assertion, a read of `env.PATH` on a copy of the Windows environment (stored as `Path`), and
+  the telemetry replaced-file test, whose `ino++` mock leaves a Number file ID unchanged at or
+  above 2^54 (and about half the time between 2^53 and 2^54). The
+  telemetry reader now compares file identity as BigInt. These fixes are proven on macOS with
+  simulated Windows inputs only.
 - A test that rewrites `~/.claude.json` is reported, not failed, in a developer run; only a strict
   run (CI) fails it.
 

From 43cb0c2cbcd67cebc2cb06fe12fca9560a2d9862 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:38:20 -0700
Subject: [PATCH 27/28] test(ui): compare the Chrome temp folder's parent
 case-insensitively on Windows

---
 tests/kit/ui-chrome-launch.test.mjs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/kit/ui-chrome-launch.test.mjs b/tests/kit/ui-chrome-launch.test.mjs
index f2ee237d..e279710a 100644
--- a/tests/kit/ui-chrome-launch.test.mjs
+++ b/tests/kit/ui-chrome-launch.test.mjs
@@ -44,7 +44,8 @@ test('launchChrome gives Chrome its own temp folder and removes it, fetcher left
   assert.equal(seen.headless, false, 'caller options win');
   const dir = seen.env.TMPDIR;
   for (const key of ['TEMP', 'TMP', 'MAC_CHROMIUM_TMPDIR']) assert.equal(seen.env[key], dir, key);
-  assert.equal(path.dirname(dir), fs.realpathSync(os.tmpdir()));
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p); // drive-letter case varies on Windows
+  assert.equal(fold(path.dirname(dir)), fold(fs.realpathSync(os.tmpdir())));
   assert.ok(Object.keys(seen.env).some((k) => k.toUpperCase() === 'PATH'), 'the browser keeps its search path');
   fs.mkdirSync(path.join(dir, 'com.google.Chrome.chrome_chrome_url_fetcher_.AbC123'));
   await browser.close();

From ec8210e0a2843333e8c26f15e7eee12fde894c22 Mon Sep 17 00:00:00 2001
From: Chris Phillipson <christopher.a.phillipson@gmail.com>
Date: Sun, 27 Sep 2026 11:53:56 -0700
Subject: [PATCH 28/28] fix(fs): compare file identity as BigInt in every
 open-and-verify read

Windows file IDs can exceed 2^53, where two different files read as the
same Number inode. CI run 36341703517 (Windows Node 22) let a source
replaced between inspection and open pass readBoundedFile for this reason.
The hook-audit, hook-remediation receipt and target, adapter hook-file and
maintenance inventory readers now stat with { bigint: true } on both sides
of each in-process identity check and convert size only after the bounds
check. inspectHookTarget keeps its Number fstat for the persisted image and
adds a BigInt fstat for the identity compare; the adapter post-read check
compares mtimeNs instead of whole-millisecond mtimeMs. Recorded identities
(receipt parent dev/ino, discovery partitions) are unchanged.
---
 ...-237-238-239-verification-and-decisions.md |   6 +-
 src/lib/adapters/integrity.mjs                |  10 +-
 src/lib/hook-audit/common.mjs                 |  10 +-
 src/lib/hook-remediation/fs-port.mjs          |   6 +-
 src/lib/hook-remediation/store.mjs            |  17 +-
 .../maintenance/management/service-store.mjs  |  12 +-
 tests/kit/file-identity-bigint.test.mjs       | 152 ++++++++++++++++++
 7 files changed, 187 insertions(+), 26 deletions(-)
 create mode 100644 tests/kit/file-identity-bigint.test.mjs

diff --git a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
index 9ce25f43..7bedeee1 100644
--- a/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
+++ b/docs/audits/2026-09-26-issues-237-238-239-verification-and-decisions.md
@@ -1388,8 +1388,10 @@ folders behind per run (`1fa55698`).
   assertion, a read of `env.PATH` on a copy of the Windows environment (stored as `Path`), and
   the telemetry replaced-file test, whose `ino++` mock leaves a Number file ID unchanged at or
   above 2^54 (and about half the time between 2^53 and 2^54). The
-  telemetry reader now compares file identity as BigInt. These fixes are proven on macOS with
-  simulated Windows inputs only.
+  telemetry reader now compares file identity as BigInt. Run 36341703517 then failed the
+  hook-audit replaced-source test on Windows Node 22 the same way, so every in-process
+  open-and-verify read now does too. These fixes are proven on macOS with simulated Windows
+  inputs only.
 - A test that rewrites `~/.claude.json` is reported, not failed, in a developer run; only a strict
   run (CI) fails it.
 
diff --git a/src/lib/adapters/integrity.mjs b/src/lib/adapters/integrity.mjs
index 314439bd..01df8e18 100644
--- a/src/lib/adapters/integrity.mjs
+++ b/src/lib/adapters/integrity.mjs
@@ -164,7 +164,7 @@ function digestFile(baseDir, relative, { fsImpl, maxFileBytes }) {
   let realRoot;
   let realFile;
   try {
-    stat = fsImpl.lstatSync(filename);
+    stat = fsImpl.lstatSync(filename, { bigint: true }); // BigInt identity: Windows file IDs can exceed 2^53
     realRoot = fsImpl.realpathSync(baseDir);
     realFile = fsImpl.realpathSync(filename);
   } catch (error) {
@@ -182,7 +182,7 @@ function digestFile(baseDir, relative, { fsImpl, maxFileBytes }) {
   let descriptor;
   try {
     descriptor = fsImpl.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
-    const opened = fsImpl.fstatSync(descriptor);
+    const opened = fsImpl.fstatSync(descriptor, { bigint: true });
     if (!opened.isFile() || opened.size > maxFileBytes) {
       throw new AdapterIntegrityError('hook-file-not-regular', `'${relative}' is not a bounded regular file`);
     }
@@ -192,16 +192,16 @@ function digestFile(baseDir, relative, { fsImpl, maxFileBytes }) {
     if (fsImpl.realpathSync(filename) !== realFile) {
       throw new AdapterIntegrityError('hook-file-changed', `'${relative}' changed path between inspection and open`);
     }
-    const bytes = Buffer.alloc(opened.size);
+    const bytes = Buffer.alloc(Number(opened.size)); // bounded by maxFileBytes above
     let offset = 0;
     while (offset < bytes.length) {
       const count = fsImpl.readSync(descriptor, bytes, offset, bytes.length - offset, offset);
       if (count === 0) break;
       offset += count;
     }
-    const after = fsImpl.fstatSync(descriptor);
+    const after = fsImpl.fstatSync(descriptor, { bigint: true });
     if (offset !== bytes.length || after.size !== opened.size || after.dev !== opened.dev
-        || after.ino !== opened.ino || after.mtimeMs !== opened.mtimeMs) {
+        || after.ino !== opened.ino || after.mtimeNs !== opened.mtimeNs) {
       throw new AdapterIntegrityError('hook-file-changed', `'${relative}' changed while it was read`);
     }
     return { sha256: createHash('sha256').update(bytes).digest('hex'), size: bytes.length };
diff --git a/src/lib/hook-audit/common.mjs b/src/lib/hook-audit/common.mjs
index 5169da4c..869f18b0 100644
--- a/src/lib/hook-audit/common.mjs
+++ b/src/lib/hook-audit/common.mjs
@@ -18,12 +18,14 @@ function contained(realRoot, realFile) {
   return realFile === realRoot || realFile.startsWith(`${realRoot}${path.sep}`);
 }
 
-/** Read a bounded regular file without following a final symlink. */
+/** Read a bounded regular file without following a final symlink. Identity is
+ *  compared as BigInt: Windows file IDs can exceed 2^53, where two different
+ *  files can read as the same Number inode. */
 /** @returns {any} */
 export function readBoundedFile(file, containmentRoot, maxBytes = MAX_AUDIT_SOURCE_BYTES) {
   let descriptor;
   try {
-    const stat = fs.lstatSync(file);
+    const stat = fs.lstatSync(file, { bigint: true });
     if (!stat.isFile() || stat.isSymbolicLink()) {
       return { status: 'refused', error: 'source must be a regular non-symlink file' };
     }
@@ -35,7 +37,7 @@ export function readBoundedFile(file, containmentRoot, maxBytes = MAX_AUDIT_SOUR
     }
     const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
     descriptor = fs.openSync(file, flags);
-    const opened = fs.fstatSync(descriptor);
+    const opened = fs.fstatSync(descriptor, { bigint: true });
     if (!opened.isFile() || opened.size > maxBytes) {
       return { status: 'refused', error: 'opened source is not a bounded regular file' };
     }
@@ -46,7 +48,7 @@ export function readBoundedFile(file, containmentRoot, maxBytes = MAX_AUDIT_SOUR
     if (reopenedRealFile !== realFile || !contained(realRoot, reopenedRealFile)) {
       return { status: 'refused', error: 'source path changed between inspection and open' };
     }
-    const bytes = Buffer.alloc(opened.size);
+    const bytes = Buffer.alloc(Number(opened.size)); // bounded by maxBytes above
     let offset = 0;
     while (offset < bytes.length) {
       const count = fs.readSync(descriptor, bytes, offset, bytes.length - offset, offset);
diff --git a/src/lib/hook-remediation/fs-port.mjs b/src/lib/hook-remediation/fs-port.mjs
index e6d94fbd..90a6ad9f 100644
--- a/src/lib/hook-remediation/fs-port.mjs
+++ b/src/lib/hook-remediation/fs-port.mjs
@@ -37,7 +37,7 @@ export function inspectHookTarget(file, containmentRoot, {
   }
   let descriptor;
   try {
-    const stat = fsImpl.lstatSync(file);
+    const stat = fsImpl.lstatSync(file, { bigint: true });
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('target must be a regular non-symlink file');
     if (stat.size > maxBytes) throw new Error(`target exceeds ${maxBytes} byte limit`);
     const realRoot = fsImpl.realpathSync(containmentRoot);
@@ -46,7 +46,9 @@ export function inspectHookTarget(file, containmentRoot, {
     descriptor = fsImpl.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
     const opened = fsImpl.fstatSync(descriptor);
     if (!opened.isFile() || opened.size > maxBytes) throw new Error('opened target is not a bounded regular file');
-    if (opened.dev !== stat.dev || opened.ino !== stat.ino) {
+    // BigInt identity: Windows file IDs can exceed 2^53; `opened` stays Number for the image.
+    const openedId = fsImpl.fstatSync(descriptor, { bigint: true });
+    if (openedId.dev !== stat.dev || openedId.ino !== stat.ino) {
       throw new Error('target identity changed between inspection and open');
     }
     const reopened = fsImpl.realpathSync(file);
diff --git a/src/lib/hook-remediation/store.mjs b/src/lib/hook-remediation/store.mjs
index 3bb12dcd..32a91cf7 100644
--- a/src/lib/hook-remediation/store.mjs
+++ b/src/lib/hook-remediation/store.mjs
@@ -123,9 +123,10 @@ function writeReceiptAtomic(receiptFile, bytes, fsImpl) {
   const directory = path.dirname(receiptFile);
   const id = path.basename(directory);
   if (!RECEIPT_ID.test(id)) throw new Error('receipt transaction directory name is invalid');
-  const directoryStat = fsImpl.lstatSync(directory);
+  // BigInt identity: Windows file IDs can exceed 2^53, where Numbers collide.
+  const directoryStat = fsImpl.lstatSync(directory, { bigint: true });
   if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) throw new Error('receipt transaction directory is unsafe');
-  if (process.platform !== 'win32' && (directoryStat.mode & 0o077) !== 0) throw new Error('receipt transaction directory is not private');
+  if (process.platform !== 'win32' && (Number(directoryStat.mode) & 0o077) !== 0) throw new Error('receipt transaction directory is not private');
   const realDirectory = fsImpl.realpathSync(directory);
   const realRoot = fsImpl.realpathSync(path.dirname(directory));
   if (path.dirname(realDirectory) !== realRoot || path.basename(realDirectory) !== id) {
@@ -133,7 +134,7 @@ function writeReceiptAtomic(receiptFile, bytes, fsImpl) {
   }
   let prior = null;
   try {
-    prior = fsImpl.lstatSync(receiptFile);
+    prior = fsImpl.lstatSync(receiptFile, { bigint: true });
     if (!prior.isFile() || prior.isSymbolicLink()) throw new Error('existing receipt is unsafe');
   } catch (error) {
     if (error?.code !== 'ENOENT') throw error;
@@ -148,12 +149,12 @@ function writeReceiptAtomic(receiptFile, bytes, fsImpl) {
     fsImpl.fsyncSync(descriptor);
     fsImpl.closeSync(descriptor);
     descriptor = undefined;
-    const currentDirectory = fsImpl.lstatSync(directory);
+    const currentDirectory = fsImpl.lstatSync(directory, { bigint: true });
     if (currentDirectory.dev !== directoryStat.dev || currentDirectory.ino !== directoryStat.ino) {
       throw new Error('receipt transaction directory changed before commit');
     }
     if (prior) {
-      const currentReceipt = fsImpl.lstatSync(receiptFile);
+      const currentReceipt = fsImpl.lstatSync(receiptFile, { bigint: true });
       if (!currentReceipt.isFile() || currentReceipt.isSymbolicLink()
           || currentReceipt.dev !== prior.dev || currentReceipt.ino !== prior.ino) {
         throw new Error('receipt changed before commit');
@@ -242,17 +243,17 @@ function validateReceipt(receipt, receiptId, transactionDir) {
 }
 
 function readReceiptDescriptor(file, realRoot, fsImpl) {
-  const before = fsImpl.lstatSync(file);
+  const before = fsImpl.lstatSync(file, { bigint: true });
   if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_AUDIT_SOURCE_BYTES) throw new Error('receipt must be a bounded regular non-symlink file');
   const realFile = fsImpl.realpathSync(file);
   if (!contained(realRoot, realFile)) throw new Error('receipt escapes its transaction root');
   let descriptor;
   try {
     descriptor = fsImpl.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
-    const opened = fsImpl.fstatSync(descriptor);
+    const opened = fsImpl.fstatSync(descriptor, { bigint: true });
     if (!opened.isFile() || opened.size > MAX_AUDIT_SOURCE_BYTES || opened.dev !== before.dev || opened.ino !== before.ino) throw new Error('receipt identity changed while opening');
     if (fsImpl.realpathSync(file) !== realFile) throw new Error('receipt path changed while opening');
-    const bytes = Buffer.alloc(opened.size);
+    const bytes = Buffer.alloc(Number(opened.size)); // bounded above
     let offset = 0;
     while (offset < bytes.length) {
       const count = fsImpl.readSync(descriptor, bytes, offset, bytes.length - offset, offset);
diff --git a/src/lib/maintenance/management/service-store.mjs b/src/lib/maintenance/management/service-store.mjs
index 64d7d4ec..7fe789cb 100644
--- a/src/lib/maintenance/management/service-store.mjs
+++ b/src/lib/maintenance/management/service-store.mjs
@@ -47,22 +47,24 @@ function sealedEnvelope(schema, payloadKey, payload) {
   return { ...base, integrity: { algorithm: 'sha256', digest: sha256(base) } };
 }
 
-/** Bound retained input before allocation and also reject growth/replacement while opening. */
+/** Bound retained input before allocation and also reject growth/replacement while opening.
+ *  Identity is compared as BigInt: Windows file IDs can exceed 2^53. */
 function readInventoryBytes(file, maxBytes, fsImpl) {
-  const before = fsImpl.lstatSync(file);
+  const before = fsImpl.lstatSync(file, { bigint: true });
   if (!before.isFile() || before.isSymbolicLink() || before.size > maxBytes) throw new Error('inventory input exceeds bounds');
   const fd = fsImpl.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
   try {
-    const stat = fsImpl.fstatSync(fd);
+    const stat = fsImpl.fstatSync(fd, { bigint: true });
     if (!stat.isFile() || stat.ino !== before.ino || stat.dev !== before.dev || stat.size > maxBytes) throw new Error('inventory input changed');
-    const buffer = Buffer.alloc(stat.size + 1);
+    const statSize = Number(stat.size); // bounded by maxBytes above
+    const buffer = Buffer.alloc(statSize + 1);
     let size = 0;
     while (size < buffer.length) {
       const bytes = fsImpl.readSync(fd, buffer, size, buffer.length - size, null);
       if (!bytes) break;
       size += bytes;
     }
-    if (size > stat.size) throw new Error('inventory input grew');
+    if (size > statSize) throw new Error('inventory input grew');
     return buffer.subarray(0, size);
   } finally { fsImpl.closeSync(fd); }
 }
diff --git a/tests/kit/file-identity-bigint.test.mjs b/tests/kit/file-identity-bigint.test.mjs
new file mode 100644
index 00000000..2e424bda
--- /dev/null
+++ b/tests/kit/file-identity-bigint.test.mjs
@@ -0,0 +1,152 @@
+// Every in-process open-and-verify read must compare file identity exactly.
+// NTFS file IDs carry a sequence number in the top 16 bits, so they can exceed
+// 2^53: as Numbers, two different files can read as the same inode (CI run
+// 36341703517, Windows Node 22). Each case hands the reader two IDs that are
+// exact when it asks for { bigint: true } and collide when it does not.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { tempDir } from './helpers/temp-dir.mjs';
+import { readBoundedFile } from '../../src/lib/hook-audit/common.mjs';
+import { inspectHookTarget } from '../../src/lib/hook-remediation/fs-port.mjs';
+import { readHookReceipt, writeHookReceipt } from '../../src/lib/hook-remediation/store.mjs';
+import { hashAdapterContent } from '../../src/lib/adapters/integrity.mjs';
+import { validateAdapterManifest } from '../../src/lib/adapters/manifest.mjs';
+import { createInventorySnapshotStore } from '../../src/lib/maintenance/management/service-store.mjs';
+
+const ID_A = 2n ** 53n;
+const ID_B = 2n ** 53n + 1n;
+const RECEIPT_ID = 'tx-2026-09-27T00-00-00.000Z-0123456789abcdef';
+
+function withIno(stat, id, options) {
+  if (id !== undefined) stat.ino = options?.bigint ? id : Number(id);
+  return stat;
+}
+
+/** A real fs whose lstat of `file` and whose fstat calls report the listed IDs, in call order. */
+function collidingFs(file, { lstat = [], fstat = [] }) {
+  let lstats = 0;
+  let fstats = 0;
+  return {
+    ...fs,
+    lstatSync: (target, options) => withIno(fs.lstatSync(target, options), target === file ? lstat[lstats++] : undefined, options),
+    fstatSync: (fd, options) => withIno(fs.fstatSync(fd, options), fstat[fstats++], options),
+  };
+}
+
+function privateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dir, 0o700);
+  return dir;
+}
+
+function hookManifest() {
+  return validateAdapterManifest({
+    name: 'hermes', version: '1.0.0', contract: 1,
+    host: {
+      id: 'hermes', label: 'Hermes',
+      install: { bin: 'hermes', externalInstallPolicy: 'detect-never-overwrite' },
+      capabilities: {
+        canDriveSession: false, canBePrimary: false, canRouteActivities: true,
+        commandStatusline: false, transcripts: false, usage: false,
+        nativeMcpConfig: false, nativeGuidance: false,
+      },
+      trust: { approvalPolicy: 'unchanged', changes: [] },
+      enabledByDefault: false, configProjection: 'ruflo', observability: [],
+    },
+    detection: { bin: 'hermes' },
+    driving: { surfaces: ['cli-subprocess'] },
+    lifecycle: { detect: { hook: { command: [process.execPath, 'detect-hook.mjs'], files: ['detect-hook.mjs'] } } },
+    trust: { changes: [] },
+  });
+}
+
+const CASES = [
+  {
+    site: 'hook-audit readBoundedFile: lstat vs fstat',
+    run(t, root) {
+      const file = path.join(root, 'hooks.json');
+      fs.writeFileSync(file, '{}');
+      const lstat = fs.lstatSync;
+      const fstat = fs.fstatSync;
+      t.mock.method(fs, 'lstatSync', (target, options) => withIno(lstat(target, options), target === file ? ID_A : undefined, options));
+      t.mock.method(fs, 'fstatSync', (fd, options) => withIno(fstat(fd, options), ID_B, options));
+      assert.equal(readBoundedFile(file, root).status, 'refused');
+    },
+  },
+  {
+    site: 'hook-remediation inspectHookTarget: lstat vs fstat',
+    run(t, root) {
+      const file = path.join(root, 'hooks.json');
+      fs.writeFileSync(file, '{}');
+      const fsImpl = collidingFs(file, { lstat: [ID_A], fstat: [ID_B] });
+      assert.throws(() => inspectHookTarget(file, root, { fsImpl }), /identity changed between inspection and open/);
+    },
+  },
+  {
+    site: 'hook-remediation writeHookReceipt: transaction directory before vs at commit',
+    run(t, root) {
+      const dir = privateDir(path.join(root, RECEIPT_ID));
+      const fsImpl = collidingFs(dir, { lstat: [ID_A, ID_B] });
+      assert.throws(() => writeHookReceipt(path.join(dir, 'receipt.json'), { id: RECEIPT_ID }, { fsImpl }),
+        /transaction directory changed before commit/);
+    },
+  },
+  {
+    site: 'hook-remediation writeHookReceipt: prior receipt before vs at commit',
+    run(t, root) {
+      const dir = privateDir(path.join(root, RECEIPT_ID));
+      const receiptFile = path.join(dir, 'receipt.json');
+      fs.writeFileSync(receiptFile, '{}', { mode: 0o600 });
+      const fsImpl = collidingFs(receiptFile, { lstat: [ID_A, ID_B] });
+      assert.throws(() => writeHookReceipt(receiptFile, { id: RECEIPT_ID }, { fsImpl }), /receipt changed before commit/);
+    },
+  },
+  {
+    site: 'hook-remediation readHookReceipt: lstat vs fstat',
+    run(t, root) {
+      const transactions = privateDir(path.join(root, 'transactions'));
+      const receiptFile = path.join(privateDir(path.join(transactions, RECEIPT_ID)), 'receipt.json');
+      fs.writeFileSync(receiptFile, '{}', { mode: 0o600 });
+      const fsImpl = collidingFs(receiptFile, { lstat: [ID_A], fstat: [ID_B] });
+      assert.throws(() => readHookReceipt(transactions, RECEIPT_ID, { fsImpl }), /identity changed while opening/);
+    },
+  },
+  {
+    site: 'adapters digestFile: lstat vs fstat',
+    run(t, root) {
+      const file = path.join(root, 'detect-hook.mjs');
+      fs.writeFileSync(file, 'process.stdout.write("one");\n');
+      const fsImpl = collidingFs(file, { lstat: [ID_A], fstat: [ID_B, ID_B] });
+      assert.throws(() => hashAdapterContent(hookManifest(), { baseDir: root, fsImpl }), /changed between inspection and open/);
+    },
+  },
+  {
+    site: 'adapters digestFile: fstat before vs after the read',
+    run(t, root) {
+      const file = path.join(root, 'detect-hook.mjs');
+      fs.writeFileSync(file, 'process.stdout.write("one");\n');
+      const fsImpl = collidingFs(file, { lstat: [ID_A], fstat: [ID_A, ID_B] });
+      assert.throws(() => hashAdapterContent(hookManifest(), { baseDir: root, fsImpl }), /changed while it was read/);
+    },
+  },
+  {
+    site: 'maintenance inventory snapshot read: lstat vs fstat',
+    run(t, root) {
+      createInventorySnapshotStore(root, { fsImpl: fs }).write({ probe: true });
+      const fsImpl = collidingFs(path.join(root, 'inventory-latest.json.gz'), { lstat: [ID_A], fstat: [ID_B] });
+      assert.equal(createInventorySnapshotStore(root, { fsImpl }).read(), null);
+    },
+  },
+];
+
+test('the simulated Windows file IDs are distinct but collide as Numbers', () => {
+  assert.notEqual(ID_A, ID_B);
+  assert.equal(Number(ID_A), Number(ID_B));
+});
+
+for (const { site, run } of CASES) {
+  test(`${site} refuses a different file whose ID exceeds 2^53`, (t) => run(t, tempDir('ak-file-identity', t)));
+}