@sabaiway/agent-workflow-kit 3.0.0 → 3.1.0

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

@@ -1,13 +1,13 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, readFileSync,
-  existsSync, readdirSync, symlinkSync,
+  existsSync, readdirSync, symlinkSync, cpSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFile } from 'node:child_process';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WRAPPER = join(HERE, 'codex-exec.sh');
@@ -55,13 +55,16 @@ const FAKE_CODEX = [
   '',
 ].join('\n');
 
-const makeSandbox = () => {
-  const root = mkdtempSync(join(tmpdir(), 'codex-exec-test-'));
+// The sandbox base and the PATH farms are READ-ONLY per invocation, so both are built ONCE and
+// shared (a per-test `git init`+commit and a per-call farm rebuild dominate the wall otherwise).
+const SHARED_ROOT = mkdtempSync(join(tmpdir(), 'codex-exec-shared-'));
+after(() => rmSync(SHARED_ROOT, { recursive: true, force: true }));
+
+const TEMPLATE_ROOT = (() => {
+  const root = join(SHARED_ROOT, 'template-root');
   const bin = join(root, 'bin');
   mkdirSync(bin, { recursive: true });
-  const stub = join(bin, 'codex');
-  writeFileSync(stub, FAKE_CODEX, { mode: 0o755 });
-  chmodSync(stub, 0o755);
+  writeFileSync(join(bin, 'codex'), FAKE_CODEX, { mode: 0o755 });
   // A git work tree with a root AGENTS.md — the wrapper preflights both.
   const repo = join(root, 'repo');
   mkdirSync(repo);
@@ -72,7 +75,15 @@ const makeSandbox = () => {
   writeFileSync(join(repo, 'AGENTS.md'), '# AGENTS\n\nHard Constraints: none (test fixture).\n');
   g('add', '-A');
   g('commit', '-qm', 'base');
-  return { root, bin, repo };
+  return root;
+})();
+
+const makeSandbox = () => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-exec-test-'));
+  cpSync(TEMPLATE_ROOT, root, { recursive: true });
+  const bin = join(root, 'bin');
+  chmodSync(join(bin, 'codex'), 0o755);
+  return { root, bin, repo: join(root, 'repo') };
 };
 
 // A PATH dir mirroring the real one MINUS the named binaries, to exercise the
@@ -96,6 +107,13 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
+const farms = new Map();
+const farmFor = (exclude) => {
+  const key = exclude.join('|');
+  if (!farms.has(key)) farms.set(key, makePathWithout(SHARED_ROOT, exclude));
+  return farms.get(key);
+};
+
 const run = ({ repo, bin }, { args = ['-'], input = 'do the thing', env = {}, path, cwd } = {}) => {
   const argvFile = join(repo, '.cap-argv');
   const envFile = join(repo, '.cap-env');
@@ -121,6 +139,33 @@ const run = ({ repo, bin }, { args = ['-'], input = 'do the thing', env = {}, pa
   return { ...r, argv: readIf(argvFile), capEnv: readIf(envFile), capStdin: readIf(stdinFile) };
 };
 
+// Async twin of run() for the sleep-bound timeout tests: spawnSync blocks the event loop for
+// the whole deliberate wait, so a concurrent describe could not overlap them. Same contract.
+const runAsync = ({ repo, bin }, { args = ['-'], input = 'do the thing', env = {}, path, cwd } = {}) =>
+  new Promise((done) => {
+    const argvFile = join(repo, '.cap-argv');
+    const envFile = join(repo, '.cap-env');
+    const stdinFile = join(repo, '.cap-stdin');
+    const child = execFile('bash', [WRAPPER, ...args], {
+      cwd: cwd || repo,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: {
+        PATH: path || `${bin}:${process.env.PATH}`,
+        HOME: repo,
+        TMPDIR: process.env.TMPDIR ?? '/tmp',
+        CODEX_FAKE_ARGV: argvFile,
+        CODEX_FAKE_ENV: envFile,
+        CODEX_FAKE_STDIN: stdinFile,
+        ...env,
+      },
+    }, (error, stdout, stderr) => {
+      const readIf = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+      done({ status: error ? (error.code ?? 1) : 0, stdout, stderr, argv: readIf(argvFile), capEnv: readIf(envFile), capStdin: readIf(stdinFile) });
+    });
+    child.stdin.end(input);
+  });
+
 describe('codex-exec.sh — quality-first model/effort guard (1.1)', () => {
   it('refuses a non-default CODEX_MODEL and never spends a run', () => {
     const sb = makeSandbox();
@@ -344,11 +389,11 @@ describe('codex-exec.sh — leaner prompt (1.4)', () => {
   });
 });
 
-describe('codex-exec.sh — hard timeout (1.3)', () => {
-  it('kills a hung codex at CODEX_HARD_TIMEOUT and reports it', () => {
+describe('codex-exec.sh — hard timeout (1.3)', { concurrency: true }, () => {
+  it('kills a hung codex at CODEX_HARD_TIMEOUT and reports it', async () => {
     const sb = makeSandbox();
     const started = Date.now();
-    const r = run(sb, { env: { CODEX_FAKE_SLEEP: '30', CODEX_HARD_TIMEOUT: '2' } });
+    const r = await runAsync(sb, { env: { CODEX_FAKE_SLEEP: '30', CODEX_HARD_TIMEOUT: '2' } });
     const elapsed = Date.now() - started;
     rmSync(sb.root, { recursive: true, force: true });
     assert.ok(elapsed < 18000, `must return well under the kill-after window, took ${elapsed}ms`);
@@ -358,7 +403,7 @@ describe('codex-exec.sh — hard timeout (1.3)', () => {
 
   it('warns and runs uncapped when neither timeout nor gtimeout is on PATH', () => {
     const sb = makeSandbox();
-    const path = `${sb.bin}:${makePathWithout(sb.root, ['timeout', 'gtimeout'])}`;
+    const path = `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`;
     const r = run(sb, { path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
@@ -368,7 +413,7 @@ describe('codex-exec.sh — hard timeout (1.3)', () => {
 
   it('resume runs uncapped (and warns) when no timeout binary is on PATH', () => {
     const sb = makeSandbox();
-    const path = `${sb.bin}:${makePathWithout(sb.root, ['timeout', 'gtimeout'])}`;
+    const path = `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`;
     const r = run(sb, { args: ['--resume', 'sess-1', '-'], input: 'go', path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
@@ -545,7 +590,7 @@ describe('codex-exec.sh — environment preflight (fail fast, before a run)', ()
   it('STOPs with 127 when codex is not on PATH', () => {
     const sb = makeSandbox();
     // PATH WITHOUT the fake codex bin and without any real codex.
-    const path = makePathWithout(sb.root, ['codex']);
+    const path = farmFor(['codex']);
     const r = run(sb, { path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 127);
@@ -556,7 +601,7 @@ describe('codex-exec.sh — environment preflight (fail fast, before a run)', ()
   it('STOPs with 127 when git is not on PATH', () => {
     const sb = makeSandbox();
     // codex present (sb.bin) but git stripped — exercises the type -P git guard.
-    const path = `${sb.bin}:${makePathWithout(sb.root, ['git'])}`;
+    const path = `${sb.bin}:${farmFor(['git'])}`;
     const r = run(sb, { path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 127);
@@ -681,7 +726,7 @@ const runHelp = (arg) => {
   const root = mkdtempSync(join(tmpdir(), 'codex-exec-help-'));
   const nongit = join(root, 'nongit');
   mkdirSync(nongit, { recursive: true });
-  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const path = farmFor(['codex', 'agy', 'git']);
   const r = spawnSync('bash', [WRAPPER, arg], {
     cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
   });
@@ -1027,20 +1072,20 @@ describe('codex-exec.sh — service tier knob (bridges 2.3.0)', () => {
 
 });
 
-describe('codex-exec.sh — bridge settings file semantics (bridges 2.3.0)', () => {
-  it('env overrides file: CODEX_HARD_TIMEOUT env=2 file=9999 → killed at the env cap', () => {
+describe('codex-exec.sh — bridge settings file semantics (bridges 2.3.0)', { concurrency: true }, () => {
+  it('env overrides file: CODEX_HARD_TIMEOUT env=2 file=9999 → killed at the env cap', async () => {
     const sb = makeSandbox();
     writeSettings(sb, 'CODEX_HARD_TIMEOUT=9999\n');
-    const r = run(sb, { env: { CODEX_FAKE_SLEEP: '5', CODEX_HARD_TIMEOUT: '2' } });
+    const r = await runAsync(sb, { env: { CODEX_FAKE_SLEEP: '5', CODEX_HARD_TIMEOUT: '2' } });
     rmSync(sb.root, { recursive: true, force: true });
     assert.notEqual(r.status, 0, 'the env cap (2s) must win over the file cap (9999s)');
     assert.match(r.stderr, /exceeded the hard cap CODEX_HARD_TIMEOUT=2s/);
   });
 
-  it('a file-set CODEX_HARD_TIMEOUT is effective (killed at the file cap)', () => {
+  it('a file-set CODEX_HARD_TIMEOUT is effective (killed at the file cap)', async () => {
     const sb = makeSandbox();
     writeSettings(sb, 'CODEX_HARD_TIMEOUT=2\n');
-    const r = run(sb, { env: { CODEX_FAKE_SLEEP: '5' } });
+    const r = await runAsync(sb, { env: { CODEX_FAKE_SLEEP: '5' } });
     rmSync(sb.root, { recursive: true, force: true });
     assert.notEqual(r.status, 0, 'the file cap must apply when the env is unset');
     assert.match(r.stderr, /exceeded the hard cap CODEX_HARD_TIMEOUT=2s/);

package/bridges/codex-cli-bridge/bin/codex-review-honesty.test.mjs

@@ -5,9 +5,9 @@
 // CODEX_SERVICE_TIER BEFORE tier validation (no multiline warning echo, no silent standard-tier
 // run). Colocated separately — codex-review.test.mjs is red-proof-frozen; standalone harness.
 
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, symlinkSync, cpSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -46,12 +46,17 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
-const makeSandbox = () => {
-  const root = mkdtempSync(join(tmpdir(), 'codex-honesty-'));
+// Farm + sandbox base are READ-ONLY per invocation — built ONCE, shared (a per-run farm rebuild
+// plus a per-test `git init`+commit dominate the wall otherwise).
+const SHARED_ROOT = mkdtempSync(join(tmpdir(), 'codex-honesty-shared-'));
+after(() => rmSync(SHARED_ROOT, { recursive: true, force: true }));
+const FARM = makePathWithout(SHARED_ROOT, ['codex']);
+
+const TEMPLATE_ROOT = (() => {
+  const root = join(SHARED_ROOT, 'template-root');
   const bin = join(root, 'bin');
   mkdirSync(bin, { recursive: true });
   writeFileSync(join(bin, 'codex'), FAKE_CODEX, { mode: 0o755 });
-  chmodSync(join(bin, 'codex'), 0o755);
   const repo = join(root, 'repo');
   mkdirSync(repo);
   const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
@@ -62,7 +67,15 @@ const makeSandbox = () => {
   g('add', '-A');
   g('commit', '-qm', 'base');
   writeFileSync(join(repo, 'pending.txt'), 'PENDING\n');
-  return { root, bin, repo };
+  return root;
+})();
+
+const makeSandbox = () => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-honesty-'));
+  cpSync(TEMPLATE_ROOT, root, { recursive: true });
+  const bin = join(root, 'bin');
+  chmodSync(join(bin, 'codex'), 0o755);
+  return { root, bin, repo: join(root, 'repo') };
 };
 
 const run = (sb, { args = ['code'], env = {} } = {}) => {
@@ -73,7 +86,7 @@ const run = (sb, { args = ['code'], env = {} } = {}) => {
     timeout: 30000,
     env: {
       HOME: sb.repo,
-      PATH: `${sb.bin}:${makePathWithout(sb.root, ['codex'])}`,
+      PATH: `${sb.bin}:${FARM}`,
       TMPDIR: process.env.TMPDIR ?? '/tmp',
       CODEX_HOME: join(sb.root, 'codex-home'),
       CODEX_FAKE_SENTINEL: sentinel,

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

@@ -1,13 +1,13 @@
-import { describe, it } from 'node:test';
+import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   mkdtempSync, mkdirSync, writeFileSync, chmodSync, rmSync, readFileSync,
-  existsSync, readdirSync, symlinkSync,
+  existsSync, readdirSync, symlinkSync, cpSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -54,16 +54,23 @@ const FAKE_CODEX = [
   '',
 ].join('\n');
 
-// `clean: true` leaves a committed, pristine tree (for the no-diff preflight);
-// the default leaves one uncommitted untracked file so `code` mode has a diff to
-// review (otherwise the new no-diff preflight short-circuits before codex runs).
-const makeSandbox = ({ clean = false } = {}) => {
-  const root = mkdtempSync(join(tmpdir(), 'codex-review-test-'));
+// The PATH farms and the sandbox base are READ-ONLY per invocation, so both are built ONCE and
+// shared (a per-call farm rebuild is thousands of symlinks; a per-test `git init`+commit
+// dominates the sandbox cost).
+const SHARED_ROOT = mkdtempSync(join(tmpdir(), 'codex-review-shared-'));
+after(() => rmSync(SHARED_ROOT, { recursive: true, force: true }));
+const farms = new Map();
+const farmFor = (exclude) => {
+  const key = exclude.join('|');
+  if (!farms.has(key)) farms.set(key, makePathWithout(SHARED_ROOT, exclude));
+  return farms.get(key);
+};
+
+const TEMPLATE_ROOT = (() => {
+  const root = join(SHARED_ROOT, 'template-root');
   const bin = join(root, 'bin');
   mkdirSync(bin, { recursive: true });
-  const stub = join(bin, 'codex');
-  writeFileSync(stub, FAKE_CODEX, { mode: 0o755 });
-  chmodSync(stub, 0o755);
+  writeFileSync(join(bin, 'codex'), FAKE_CODEX, { mode: 0o755 });
   const repo = join(root, 'repo');
   mkdirSync(repo);
   const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
@@ -74,6 +81,18 @@ const makeSandbox = ({ clean = false } = {}) => {
   writeFileSync(join(repo, 'plan.md'), '# Plan\n\nDo a thing in two steps.\n');
   g('add', '-A');
   g('commit', '-qm', 'base');
+  return root;
+})();
+
+// `clean: true` leaves a committed, pristine tree (for the no-diff preflight);
+// the default leaves one uncommitted untracked file so `code` mode has a diff to
+// review (otherwise the new no-diff preflight short-circuits before codex runs).
+const makeSandbox = ({ clean = false } = {}) => {
+  const root = mkdtempSync(join(tmpdir(), 'codex-review-test-'));
+  cpSync(TEMPLATE_ROOT, root, { recursive: true });
+  const bin = join(root, 'bin');
+  chmodSync(join(bin, 'codex'), 0o755);
+  const repo = join(root, 'repo');
   if (!clean) writeFileSync(join(repo, 'pending.txt'), 'an uncommitted change to review\n');
   return { root, bin, repo };
 };
@@ -123,6 +142,35 @@ const run = ({ repo, bin }, { args = ['code'], env = {}, path, cwd } = {}) => {
   return { ...r, codexHome, argv: readIf(argvFile), capEnv: readIf(envFile), capStdin: readIf(stdinFile) };
 };
 
+// Async twin of run() for the sleep-bound timeout test: spawnSync blocks the event loop for
+// the whole deliberate wait, so a concurrent describe could not overlap it. Same contract.
+const runAsync = ({ repo, bin }, { args = ['code'], env = {}, path, cwd } = {}) =>
+  new Promise((done) => {
+    const argvFile = join(repo, '.cap-argv');
+    const envFile = join(repo, '.cap-env');
+    const stdinFile = join(repo, '.cap-stdin');
+    const codexHome = join(repo, '..', 'codex-home');
+    const child = execFile('bash', [WRAPPER, ...args], {
+      cwd: cwd || repo,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: {
+        PATH: path || `${bin}:${process.env.PATH}`,
+        HOME: repo,
+        TMPDIR: process.env.TMPDIR ?? '/tmp',
+        CODEX_HOME: codexHome,
+        CODEX_FAKE_ARGV: argvFile,
+        CODEX_FAKE_ENV: envFile,
+        CODEX_FAKE_STDIN: stdinFile,
+        ...env,
+      },
+    }, (error, stdout, stderr) => {
+      const readIf = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+      done({ status: error ? (error.code ?? 1) : 0, stdout, stderr, codexHome, argv: readIf(argvFile), capEnv: readIf(envFile), capStdin: readIf(stdinFile) });
+    });
+    child.stdin.end();
+  });
+
 describe('codex-review.sh — quality-first model/effort guard (1.1)', () => {
   it('refuses a non-default CODEX_MODEL', () => {
     const sb = makeSandbox();
@@ -255,11 +303,11 @@ describe('codex-review.sh — subscription / config isolation (invariant)', () =
   });
 });
 
-describe('codex-review.sh — hard timeout (1.3)', () => {
-  it('kills a hung review at CODEX_HARD_TIMEOUT and reports it', () => {
+describe('codex-review.sh — hard timeout (1.3)', { concurrency: true }, () => {
+  it('kills a hung review at CODEX_HARD_TIMEOUT and reports it', async () => {
     const sb = makeSandbox();
     const started = Date.now();
-    const r = run(sb, { env: { CODEX_FAKE_SLEEP: '30', CODEX_HARD_TIMEOUT: '2' } });
+    const r = await runAsync(sb, { env: { CODEX_FAKE_SLEEP: '30', CODEX_HARD_TIMEOUT: '2' } });
     const elapsed = Date.now() - started;
     rmSync(sb.root, { recursive: true, force: true });
     assert.ok(elapsed < 18000, `must return well under the kill-after window, took ${elapsed}ms`);
@@ -269,7 +317,7 @@ describe('codex-review.sh — hard timeout (1.3)', () => {
 
   it('warns and runs uncapped when neither timeout nor gtimeout is on PATH', () => {
     const sb = makeSandbox();
-    const path = `${sb.bin}:${makePathWithout(sb.root, ['timeout', 'gtimeout'])}`;
+    const path = `${sb.bin}:${farmFor(['timeout', 'gtimeout'])}`;
     const r = run(sb, { path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
@@ -414,7 +462,7 @@ describe('codex-review.sh — optional structured findings (2.2)', () => {
 describe('codex-review.sh — environment preflight (fail fast, before a run)', () => {
   it('STOPs with 127 when codex is not on PATH', () => {
     const sb = makeSandbox();
-    const path = makePathWithout(sb.root, ['codex']); // no fake codex, no real codex
+    const path = farmFor(['codex']); // no fake codex, no real codex
     const r = run(sb, { args: ['code'], path });
     rmSync(sb.root, { recursive: true, force: true });
     assert.equal(r.status, 127);
@@ -570,7 +618,7 @@ const runHelp = (arg) => {
   const root = mkdtempSync(join(tmpdir(), 'codex-review-help-'));
   const nongit = join(root, 'nongit');
   mkdirSync(nongit, { recursive: true });
-  const path = makePathWithout(root, ['codex', 'agy', 'git']);
+  const path = farmFor(['codex', 'agy', 'git']);
   const r = spawnSync('bash', [WRAPPER, arg], {
     cwd: nongit, encoding: 'utf8', timeout: 15000, env: { HOME: root, PATH: path },
   });

package/capability.json

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

package/package.json

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

package/references/modes/recommendations.md

@@ -24,6 +24,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - `sandbox-lane` — surface this note TOGETHER with the sandbox-lanes ladder below (the ladder IS the practical half of the note — inline, never a pointer). Pure DISCOVERABILITY: it surfaces the manifest-declared observed session-sandbox recipe (egress hosts ∪ resolved writable state dirs — `networkHosts` ∪ `writableDirs` of the wired bridges' `capability.json`, the single documentation source) and converges on a NEUTRAL fingerprint acknowledgement recorded by the consent-gated **ack writer** into the family-owned `docs/ai/acks.json` (`sandboxLaneAck`; a changed recipe re-fires the item). The store is family-owned so no host settings validator guards it (AD-055 relocated the ack off the Claude Code settings schema, which rejected the unknown key); the legacy `"agentWorkflow": { "sandboxLaneAck": … }` settings-scope key is still READ for one deprecation window (until the next kit MAJOR). It never claims the settings security keys take effect on any host class, never recommends writing them, and the kit never seeds `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` (bridge council 2026-07-11, both backends concur: a network pre-allow widens egress for EVERY sandboxed command; a write allowance on CLI state dirs would expose credential dirs). Posture history: an IDE-managed session sandbox was live-observed (2026-07-11/12) ignoring hand-applied settings security keys in BOTH scopes, and codex needs a writable HOME (EROFS `~/.codex` in-sandbox); whether a session's sandbox honors the settings keys is runtime-unknowable from the advisor (a denial-only signal) — which is exactly why the item states only detectable facts and no zero-prompt promise on any host class.
 
 - `read-lane` — enabling the opt-in read-only compound lane auto-approves *compounds* (and singles) of the seeded read-only core that carry ZERO shell metaprogramming: an UNATTENDED trust extension, bounded by the audited read-only core (never a command outside it; prompt-bypass only, never a sandbox bypass) and applied regardless of which of those core commands you seeded as individual settings rules. It is a PROJECT-PERSISTENT declaration in `docs/ai/lanes.json` — every future session, subagents' Bash too where the host fires hooks on subagent Bash, and (committed) every checkout. The apply depends on state: when the lane is OFF, it is the `gate-hook --read-lane` preview (whose own currency check refuses a stale hook — a pre-1.48 hook never reads `lanes.json`); when the placed hook is STALE (an enabled lane over an old hook) or MISSING, the item instead surfaces a **delete-to-reseed** / re-place recovery (a destructive `rm` + `--apply`, an attention item — never the safe preview). Risk profile: a bounded read-only trust-posture extension — no write/exec exposure beyond the audited core.
+- `worktrees-dir` — on a settings-native host that honors the key, the HAND-APPLY line widens the OS-sandbox WRITE surface to the whole worktrees parent dir: every sibling path under it (other repositories included) becomes agent-writable, and the widening persists for every later session. A harness-managed host may ignore that project setting; grant the narrow parent through host/session controls or use the provision terminal fallback instead. When that scope is wider than you want, narrow it FIRST: create a dedicated dir yourself (outside the agent's write surface), point `docs/ai/worktrees.json` `parentDir` at it, then re-run recommendations — the item re-renders with the narrowed dir. The kit never writes sandbox filesystem allowances itself; the line is always yours to paste. Risk profile: a real write-surface widening where honored — scope it deliberately.
 
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**
 

package/references/modes/worktrees.md

@@ -0,0 +1,120 @@
+### Mode: worktrees
+
+Parallel feature worktrees (v1) — several features implemented simultaneously in DIFFERENT agent
+sessions on one machine/repo, zero interference on working-tree files (the ONE exception: the
+default `node_modules` symlink is a shared MUTABLE dependency cache — see below), unambiguous
+ownership. One thin tool over git; every verification datum is recomputed live from git, never
+read from stored metadata.
+The ONE stored-metadata exception is the PREPARED OID recorded in the handoff: land and cleanup read it back only for recovery.
+
+**Run** — `node ${CLAUDE_SKILL_DIR}/tools/worktrees.mjs <subcommand> …`:
+
+Git ≥ 2.36 is required for NUL-terminated worktree porcelain; an older Git fails closed with its
+own verbatim error through the existing Git-error surface.
+
+- `provision <slug> --plan <path> [--as <name>.md] [--dir <path>] [--branch <name>] [--include <path>]... [--install] [--resume]`
+  — create a feature worktree (default: the visible sibling `<repoParent>/<repoName>--<slug>`,
+  branch `aw/<slug>`) and populate it: the registry-derived footprint copy-if-missing (a tracked
+  file is NEVER overwritten), EXACTLY ONE seeded feature plan, the `handoff-<slug>.md` stub
+  (written at provision — the tool's own record; `list` and `cleanup` read it), a
+  `node_modules` symlink when main has one and the link stays ignored — a SHARED MUTABLE cache:
+  writes through it hit MAIN's node_modules; for isolation RUN the printed isolated-install
+  command (`--install` only prints it), and on `--resume` an existing symlink is kept — run the
+  printed unlink-first recovery first. Absolute root-pinned gate commands are rebased on UNTRACKED copies only — and only
+  while their bytes still equal the MAIN source (or its rebased form); user-modified copies stay
+  byte-untouched. `--install` only PRINTS the install command — zero spawn, zero write.
+  `--resume <slug>` completes a half-done provision (identity fail-closed; handoff user sections,
+  the seeded plan, and edited copies are preserved byte-exact; the provision-record section is
+  refreshed atomically; copy-if-missing everywhere).
+  Resume identity also binds the EXISTING handoff: at most one `handoff-<slug>.md` may exist and
+  its recorded slug AND branch must match the live invocation — a second handoff, a name/record
+  mismatch, or a handoff that is not a regular file is a typed STOP before anything is written
+  (the writability probe itself runs only after these checks on a resume). The provision record
+  is read from exactly one REQUIRED `## Provision record` section (a decoy field elsewhere cannot
+  hijack identity); a missing or repeated section, or a duplicated single-valued field, is a typed
+  STOP, never last-wins.
+- `list` — read-only: every worktree of this repo with slug (from the handoff file; none →
+  "unknown (foreign)"), path, branch, base OID (the worktree HEAD — under the v1 no-commit bar
+  that IS the provision base; a manual satellite commit moves it, and land derives its own base
+  live), dirty flag, handoff presence, opener suggestion. Honest read errors: only a genuinely
+  ABSENT docs/plans under a symlink-free, present worktree dir reads as `handoff: no`; a
+  symlinked docs/plans (or ancestor), a handoff-named entry that is not a regular file, a
+  vanished worktree dir, or any other read failure renders `handoff: (unreadable)` — never a
+  silent "no".
+- `land <slug> --prepare` — stage the satellite's finished diff onto a CLEAN main; the commit is
+  NEVER run by the tool — it stays a dialogue ask at the primary session. Land takes the transient
+  common-git-dir lock, refuses a dirty main, graph divergence, visible `docs/ai` drift, excluded
+  staged paths, unstaged/untracked leftovers, an empty diff, or a red satellite review-state. The
+  complete satellite working-tree diff versus its base is inspected (staged and unstaged); every
+  unstaged/untracked path is listed and refused, so an accepted transfer cannot silently omit it.
+  The binary/no-ext-diff/no-textconv transfer excludes exactly `docs/ai` and `docs/plans`, applies
+  into the index, optionally runs the porcelain-visible sync adapter, then runs the main gate
+  matrix. It reports main HEAD, TRANSFER, PREPARED, and sync delta OIDs/data; the primary re-attests
+  that prepared tree and confirms main HEAD still equals the printed OID before the commit ask.
+- `cleanup <slug> [--branch <name>] [--abandon]` — take the same transient lock and remove a LANDED
+  worktree fail-closed after live landed-verification against main HEAD. Verification uses exactly
+  the land exclusions (`docs/ai`, `docs/plans`), then checks untracked and ignored content before a
+  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral;
+  `node_modules` of any kind is provision-derivable because provision explicitly advises installs.
+  Foreign content stops cleanup. `--abandon` is the ONE destructive arm: it DESTROYS unlanded work,
+  requires the handoff identity, and is the only path where `--force` may appear.
+
+**Honesty:** there is NO preview step on the writers — over-warned by design. The tool never
+commits, never pushes, never runs a subscription CLI. Every content read and regular-file copy
+goes through its one no-follow descriptor door (identity-bound source, exclusive destination,
+descriptor mode update), and tripwire tests keep them the only paths.
+
+**Settings:** the parent dir for new worktrees is the `docs/ai/worktrees.json` `{"parentDir": …}`
+project setting (hand-editable strict JSON; absent file → the sibling default; malformed → a
+typed STOP, never a guess). The file must be a REGULAR, non-symlink file reached through a
+symlink-free path — anything else is a typed STOP (the advisor renders the same shape as a
+stated skip), and the ancestor chain is verified even when the leaf is ABSENT (a symlinked
+`docs/` or `docs/ai` never reads as plain absence). `--dir` overrides per invocation.
+
+**Host-specific consent (zero-prompt only where the host honors it):** every sibling-dir mutation
+runs a REAL create+delete writability probe first. An unwritable parent prints both the
+settings-native line (`sandbox.filesystem.allowWrite` in `.claude/settings.json`) and the full
+terminal command. On a settings-native host that honors the key, adding the parent can make later
+provision/cleanup promptless. On a harness-managed host that ignores project settings, grant the
+narrow parent through the host/session controls; if that is unavailable, use the printed terminal
+command for each operation. The `recommendations` mode surfaces this lane but treats write access
+as unverified without a trusted host-capability signal.
+
+**Landing flow:** provision → work → handoff → land → re-attest → commit → cleanup. Satellite
+commits are outside v1: graph divergence stops land and prints cherry-pick/rebase recovery. A gate
+failure keeps the prepared main tree and names both recovery lanes. A second prepare is reset-only:
+the STOP prints the current staged write-tree, compares it with the PREPARED OID recorded in the
+handoff, distinguishes a converged re-run from foreign staged work, and lists removal commands for
+untracked crash residue before the reset-and-re-run lane. A killed process may leave
+`aw-prepare-lock`; after confirming no land/cleanup process owns it, remove that directory by hand.
+
+The optional `scripts/sync-mirrors.mjs` adapter runs as a child. Its contract is porcelain-visible
+output: tracked modifications/deletions or untracked-not-ignored creations. Ignored writes and
+changes inside an already-untracked file are outside observation and therefore out of contract.
+Cleanup reports EBUSY as likely lingering processes/open file descriptors (including a sandbox
+mount); close them and retry, outside the sandbox when needed. Hidden satellite `docs/ai` state is
+ephemeral by design; durable content belongs in the handoff before landing — the handoff carries a
+free-form session-records digest slot (every section outside `## Provision record` is user-owned
+and byte-preserved by the tool).
+
+**Ownership:** MAIN owns MAIN-tree files, commits, pushes, releases, the gate matrix, every
+docs/ai record, `docs/plans/queue.md`, and all shared git state — stash, hooks, repo config,
+`.git/info/exclude`, and every ref except the satellite's configured branch. The SATELLITE owns
+that one branch (`aw/<slug>` or the `--branch` override), its feature edits, its seeded plan, and
+the user-owned handoff sections; `## Provision record` remains tool-owned. Satellite forbidden
+verbs (the v1 docs-only bar): no `git commit`/`push`/`tag`/`git stash`/history rewrite — the ONE
+legal rewrite is the tool-printed `git reset --hard` recovery of the satellite's OWN configured
+branch (`aw/<slug>` or the `--branch` override) — no kit lifecycle writers
+(`init`/`upgrade`/`setup`/`hide-footprint`/`install-git-hooks`/`sandbox-masks`/`ack-write`), no
+queue.md writes, no version bumps or publishes, no edits to MAIN's files from the satellite
+session — divergence and the landed verification enforce the observable half; the rest is the
+stated contract. A symlinked `node_modules` under npm workspaces resolves
+workspace self-links to MAIN-tree sources — use the printed isolated install when that matters.
+
+**Other harnesses:** PROVEN — the host-installed codex/agy review wrappers run with a provisioned
+worktree as their cwd; the footprint carries the root `AGENTS.md` required by the codex wrappers
+and available to agy as its fallback project context. The host-level `bridge-settings.conf` under
+`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/` is per-host, shared by every worktree, and is not
+copied into the worktree. ASSUMED until probed per harness — each target harness's project-local
+settings and context pickup in a fresh worktree session; treat that as unverified until the target
+harness demonstrates it.

package/references/scripts/archive-decisions.mjs

@@ -649,7 +649,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   verifyConservation(oldItems, newItems);
   // Integrity over the FULL final store — existing records ∪ freshly-exploded — not just the new
   // writes: a pre-existing adr/ record whose id also stays RETAINED in HOT would otherwise leave the
-  // ADR in two places (codex R4). Same full-store pattern as runRotate.
+  // ADR in two places. Same full-store pattern as runRotate.
   const finalStoreById = new Map(existingStore.map((e) => [e.id, { id: e.id, idNum: e.idNum, fileName: e.fileName }]));
   for (const r of records) finalStoreById.set(r.id, { id: r.id, idNum: r.idNum, fileName: r.fileName });
   assertStoreIntegrity(retained, [...finalStoreById.values()]);
@@ -783,7 +783,7 @@ const runRotate = (root, flags, today, deps, log, logError) => {
   }
 
   const records = explode(toExplode, today);
-  // Crash-resume (fold-induced, codex R2): a record from a prior crashed rotate may already be on
+  // Crash-resume (fold-induced): a record from a prior crashed rotate may already be on
   // disk. A byte-identical one is done (deduped, not a duplicate-id error); a divergent-body one is
   // corrupt → FAIL. The FINAL store = existing ∪ freshly-exploded, deduped by id.
   const existingById = new Map(existingStore.map((e) => [e.id, e]));

package/references/scripts/archive-decisions.test.mjs

@@ -341,7 +341,7 @@ describe('1.3 --migrate --apply — records + snapshot + retire monoliths + HOT
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0, 'the resumed tree passes --check');
   });
 
-  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — codex R4)', () => {
+  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — review-adr-archive-r04-major-01)', () => {
     const root = makeRoot();
     seedLegacy(root, { hot: ['005', '006'], warm: ['003'], cold: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
@@ -452,7 +452,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /duplicate ADR id AD-002/);
   });
 
-  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — codex R4)', () => {
+  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — review-adr-archive-r04-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
     const noCapFm = '---\ntype: reference\nlastUpdated: 2026-01-01\nscope: permanent\nstaleAfter: never\nowner: none\n---\n';
@@ -514,7 +514,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /two records for AD-001/);
   });
 
-  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — codex R2)', () => {
+  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — review-adr-archive-r02-major-01)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL, 'nested'), { recursive: true });
@@ -561,7 +561,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(regenCalls.length, 0, 'a no-op never regenerates the index');
   });
 
-  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (codex R2)', () => {
+  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (review-adr-archive-r02-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
     const blocks = ['005', '006', '007', '008'].map((id) => adrBlock(id));
@@ -579,7 +579,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0);
   });
 
-  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (codex R2)', () => {
+  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (review-adr-archive-r02-major-03)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] }); // under cap
     const rec = explode(parseDecisionsText(tierText(999, '# T', [adrBlock('010')]), 'x').entries, '2026-07-09')[0];