@sabaiway/agent-workflow-kit 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.1.0 — parallel feature worktrees v1: provision · list · land --prepare · cleanup (AD-060)
+
+New `worktrees` mode + `tools/worktrees.mjs` — 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 — the printed
+isolated install is the isolation lane), unambiguous ownership. One thin dependency-free tool over git: every verification datum is recomputed live
+from git, never read from stored metadata (the ONE exception: the PREPARED OID in the handoff,
+read back only for recovery). Git >= 2.36 floor (NUL-terminated worktree porcelain); typed STOPs,
+never a guess.
+
+- **`provision <slug> --plan <path>`** — visible sibling worktree + `aw/<slug>` branch: the
+  registry-derived footprint copy-if-missing (a tracked file is NEVER overwritten), exactly one
+  seeded feature plan, the `handoff-<slug>.md` stub, shared-`node_modules` symlink advice
+  (`--install` only PRINTS the isolated install — zero spawn, zero write). `--resume` completes a
+  half-done provision behind fail-closed identity: at most one handoff, slug AND branch must
+  match, the section-required `## Provision record` (a duplicated field or section is a STOP,
+  never last-wins), user content preserved byte-exact.
+- **`list`** — read-only and honest: any read failure renders `handoff: (unreadable)` — a silent
+  "no" never appears.
+- **`land <slug> --prepare`** — the transient common-git-dir lock (shared with cleanup),
+  dirty-main / graph-divergence / docs-ai-drift / red-review-state refusals, the satellite
+  working-tree diff versus its base — staged AND unstaged inspected, every unstaged or
+  untracked-not-ignored leftover listed and refused (ignored content is outside observation by
+  design) — binary-safe transfer excluding exactly `docs/ai` + `docs/plans`, the optional
+  porcelain-visible sync adapter, the main gate matrix, and an OID report (main HEAD · TRANSFER ·
+  PREPARED · sync delta). The commit is NEVER run by the tool — it stays a dialogue ask. A second
+  prepare is reset-only against the recorded PREPARED OID; transfer-apply and post-launch sync
+  failures attempt a byte-clean rollback (rollback failures are composed without losing the
+  primary error), while a red gate matrix that leaves the snapshot unchanged intentionally KEEPS
+  the prepared tree and names both recovery lanes.
+- **`cleanup <slug>`** — live landed-verification against main HEAD (exact land-exclusion
+  parity), typed-EXACT ownership of ignored content (file/glob roots own only files), literal
+  pathspecs, branch `-d`, prune; foreign content stops it. `--abandon` is the ONE destructive arm
+  (`-D`; requires the handoff identity).
+- **Hardening:** every content read and regular-file copy goes through two no-follow descriptor
+  doors (identity-bound source · exclusive destination · descriptor-mode update), pinned as the
+  only paths by tripwire tests; strict parsers everywhere (NUL porcelain fields,
+  scan-before-parse JSON with any-depth duplicate-key refusal, atomic section surgery).
+- **release-scan:** the reviewer-round-identity rung — an `agy` or `codex` name followed by an
+  R-number reference is refused; shippable finding IDs use neutral
+  `review-<scope>-rNN-<severity>-NN` IDs; the clean line now reads "no AI attribution or
+  reviewer-round identity found".
+- **recommendations:** the worktrees parent-dir item — write access stays "not confirmed" without
+  a trusted host-capability signal; HAND-APPLY lines are host-qualified.
+- **Docs:** the `references/modes/worktrees.md` contract — the MAIN/SATELLITE ownership matrix
+  (shared git state included), satellite forbidden verbs (the v1 docs-only bar), the
+  host-specific consent lane, and the other-harnesses PROVEN/ASSUMED split.
+
 ## 3.0.0 — strip-the-kit: the hardened computed core replaces the ledger machinery (AD-059)
 
 > ### ⚠ BREAKING — the review loop is now computed, not recorded
@@ -502,7 +550,7 @@ was blocked on an honest degrade.
 
 Contract surfaces moved in lockstep (the tool header, `--help`, the human render, the `--await`
 comment, `references/modes/review-state.md`). Council-converged both segments (S1 codex + agy SHIP; S2
-codex R1 revise → allPresent fold → R2 both SHIP), the two-gate agreement dogfooded live + pinned by a
+review round 1 revise → allPresent fold → review round 2 both SHIP), the two-gate agreement dogfooded live + pinned by a
 detector-independent `two-gate-agreement.test.mjs` + a 17-case matrix; full suite 2969 green.
 
 ## 1.40.0 — Universal verification profile + session-loop economics (a)–(h) (BUGFREE-3, AD-049)

package/README.md

@@ -243,6 +243,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
 | `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (sandbox-lane only) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit worktrees` | any time | **parallel feature worktrees** — run several features in DIFFERENT agent sessions on one repo, zero interference on working-tree files (the ONE exception is the dependency cache, below): `provision <slug> --plan <file>` creates a sibling git worktree on branch `aw/<slug>` and populates it (registry-derived footprint copy-if-missing — a tracked file is never overwritten; EXACTLY ONE seeded feature plan; the `handoff-<slug>.md` record from minute zero; `node_modules` symlinked where the link stays ignored — a shared MUTABLE dependency cache: writes through it hit MAIN's node_modules; for isolation run the printed isolated-install command (`--install` only PRINTS it; on `--resume` run the printed unlink-first recovery first); absolute root-pinned gate commands rebased on untracked copies only, and only while their bytes equal the MAIN source or its rebased form — user-modified copies stay untouched); `list` is read-only (slug, branch, base, dirty, handoff); `land <slug> --prepare` locks the common git dir, fail-closes on divergence or incomplete satellite state, transfers the complete accepted satellite diff onto a CLEAN main, runs sync plus the declared gates, and reports HEAD/TRANSFER/PREPARED OIDs — the commit ALWAYS stays a dialogue ask; `cleanup <slug>` takes the same lock and removes a LANDED worktree only after live landed-verification against main HEAD, while `--abandon` is the ONE destructive arm (destroys unlanded work; **no preview step** on any writer). The parent dir is the `docs/ai/worktrees.json` `parentDir` setting (default: the repo's sibling parent); an unwritable parent degrades to printed maintainer-pasted commands, and the one-time host consent that makes it promptless surfaces via `recommendations`. Never commits, never pushes, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.0.0'
+  version: '3.1.0'
 ---
 
 # agent-workflow-kit
@@ -187,6 +187,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/commit-guard.md` before
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/doc-parity.md` before acting.
 
+### Mode: worktrees
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/worktrees.md` before acting.
+
 ---
 
 ## References

package/bin/install.mjs

@@ -211,7 +211,16 @@ const spawnMember = ({ command, args, options }) => spawnSync(command, args, opt
 // npm/network blip (rate-limit, registry hiccup, momentary DNS) — an immediate retry tends to hit the
 // same blip, so wait briefly first. Atomics.wait is a dependency-free sync sleep (the install flow is
 // already synchronous here). Injected in tests as a 0ms no-op so the suite never actually sleeps.
-const RETRY_DELAY_MS = 1500;
+// AW_INSTALL_RETRY_DELAY_MS is a test seam (the subprocess cascade suite zeroes the wait; the
+// retry POLICY itself stays exercised). Unset, empty, malformed and negative all keep the shipped
+// default — `Number('')` is 0, so the raw value is screened BEFORE coercion (the R1 council bug).
+export const resolveRetryDelayMs = (env) => {
+  const raw = env.AW_INSTALL_RETRY_DELAY_MS;
+  if (typeof raw !== 'string' || raw.trim() === '') return 1500;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 1500;
+};
+const RETRY_DELAY_MS = resolveRetryDelayMs(process.env);
 const sleepSync = (ms) => {
   if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 };

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

@@ -5,9 +5,9 @@
 // posture.model null). Colocated separately from agy-review.test.mjs — that file is
 // red-proof-frozen; this one carries its own minimal standalone harness (the family idiom).
 
-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';
@@ -41,12 +41,17 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
-const makeSandbox = () => {
-  const home = mkdtempSync(join(tmpdir(), 'agy-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(), 'agy-honesty-shared-'));
+after(() => rmSync(SHARED_ROOT, { recursive: true, force: true }));
+const FARM = makePathWithout(SHARED_ROOT, ['agy', 'agy-run']);
+
+const TEMPLATE_HOME = (() => {
+  const home = join(SHARED_ROOT, 'template-home');
   const bin = join(home, '.local', 'bin');
   mkdirSync(bin, { recursive: true });
   writeFileSync(join(bin, 'agy'), FAKE_AGY, { mode: 0o755 });
-  chmodSync(join(bin, 'agy'), 0o755);
   const repo = join(home, 'repo');
   mkdirSync(repo);
   const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
@@ -58,7 +63,15 @@ const makeSandbox = () => {
   g('commit', '-qm', 'base');
   writeFileSync(join(repo, 'pending.txt'), 'PENDING\n');
   writeFileSync(join(repo, 'plan.md'), '# a plan artifact\n');
-  return { home, bin, repo };
+  return home;
+})();
+
+const makeSandbox = () => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-honesty-'));
+  cpSync(TEMPLATE_HOME, home, { recursive: true });
+  const bin = join(home, '.local', 'bin');
+  chmodSync(join(bin, 'agy'), 0o755);
+  return { home, bin, repo: join(home, 'repo') };
 };
 
 const run = (sb, { args, env = {} } = {}) => {
@@ -69,7 +82,7 @@ const run = (sb, { args, env = {} } = {}) => {
     timeout: 30000,
     env: {
       HOME: sb.home,
-      PATH: `${sb.bin}:${makePathWithout(sb.home, ['agy', 'agy-run'])}`,
+      PATH: `${sb.bin}:${FARM}`,
       TMPDIR: process.env.TMPDIR ?? '/tmp',
       AGY_FAKE_SENTINEL: sentinel,
       ...env,

package/bridges/antigravity-cli-bridge/bin/agy-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';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const WRAPPER = join(HERE, 'agy-review.sh');
@@ -65,15 +65,23 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
-// `clean: true` leaves a pristine committed tree (for the no-diff preflight); the default leaves one
-// untracked file so `code` mode has a diff to review.
-const makeSandbox = ({ clean = false } = {}) => {
-  const home = mkdtempSync(join(tmpdir(), 'agy-review-test-'));
+// The PATH farms and the sandbox base are READ-ONLY per invocation, so both are built ONCE and
+// shared: a per-run farm rebuild (thousands of symlinks) plus a per-test `git init`+commit were
+// the suite's dominant wall cost, not the wrapper under test.
+const SHARED_ROOT = mkdtempSync(join(tmpdir(), 'agy-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_HOME = (() => {
+  const home = join(SHARED_ROOT, 'template-home');
   const bin = join(home, '.local', 'bin');
   mkdirSync(bin, { recursive: true });
-  const stub = join(bin, 'agy');
-  writeFileSync(stub, FAKE_AGY, { mode: 0o755 });
-  chmodSync(stub, 0o755);
+  writeFileSync(join(bin, 'agy'), FAKE_AGY, { mode: 0o755 });
   const repo = join(home, 'repo');
   mkdirSync(repo);
   const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
@@ -83,13 +91,25 @@ const makeSandbox = ({ clean = false } = {}) => {
   writeFileSync(join(repo, 'base.txt'), 'committed base\n');
   g('add', '-A');
   g('commit', '-qm', 'base');
+  return home;
+})();
+
+// `clean: true` leaves a pristine committed tree (for the no-diff preflight); the default leaves one
+// untracked file so `code` mode has a diff to review.
+const makeSandbox = ({ clean = false } = {}) => {
+  const home = mkdtempSync(join(tmpdir(), 'agy-review-test-'));
+  cpSync(TEMPLATE_HOME, home, { recursive: true });
+  const bin = join(home, '.local', 'bin');
+  chmodSync(join(bin, 'agy'), 0o755);
+  const repo = join(home, 'repo');
+  const g = (...args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
   if (!clean) writeFileSync(join(repo, 'pending.txt'), 'PENDING_UNTRACKED_BODY\n');
   return { home, bin, repo, g };
 };
 
 const run = (sb, { args, env = {}, cwd } = {}) => {
   const { home, bin, repo } = sb;
-  const farm = makePathWithout(home, ['agy', 'agy-run']);
+  const farm = farmFor(['agy', 'agy-run']);
   const cap = {
     argv: join(home, 'cap-argv'), env: join(home, 'cap-env'), prompt: join(home, 'cap-prompt'),
     sentinel: join(home, 'cap-sentinel'), adddir: join(home, 'cap-adddir'),
@@ -122,6 +142,44 @@ const run = (sb, { args, env = {}, cwd } = {}) => {
   };
 };
 
+// Async twin of run() for the two sleep-bound timeout tests: spawnSync blocks the event loop
+// for the whole deliberate wait, so a concurrent describe could not overlap them. Same spawn
+// contract and captures.
+const runAsync = (sb, { args, env = {}, cwd } = {}) =>
+  new Promise((done) => {
+    const { home, bin, repo } = sb;
+    const cap = {
+      argv: join(home, 'cap-argv'), env: join(home, 'cap-env'), prompt: join(home, 'cap-prompt'),
+      sentinel: join(home, 'cap-sentinel'), adddir: join(home, 'cap-adddir'),
+      adddirMode: join(home, 'cap-adddir-mode'), artifactMode: join(home, 'cap-artifact-mode'),
+      artifactCopy: join(home, 'cap-artifact-copy'),
+    };
+    const child = execFile('bash', [WRAPPER, ...args], {
+      cwd: cwd || repo,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: {
+        HOME: home,
+        PATH: `${bin}:${farmFor(['agy', 'agy-run'])}`,
+        TMPDIR: process.env.TMPDIR ?? '/tmp',
+        AGY_FAKE_ARGV: cap.argv, AGY_FAKE_ENV: cap.env, AGY_FAKE_PROMPT: cap.prompt,
+        AGY_FAKE_SENTINEL: cap.sentinel, AGY_FAKE_ADDDIR: cap.adddir, AGY_FAKE_ADDDIR_MODE: cap.adddirMode,
+        AGY_FAKE_ARTIFACT_MODE: cap.artifactMode, AGY_FAKE_ARTIFACT_COPY: cap.artifactCopy,
+        ...env,
+      },
+    }, (error, stdout, stderr) => {
+      const readIf = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : '');
+      done({
+        status: error ? (error.code ?? 1) : 0, stdout, stderr,
+        invoked: existsSync(cap.sentinel),
+        argv: readIf(cap.argv), capEnv: readIf(cap.env), prompt: readIf(cap.prompt),
+        adddir: readIf(cap.adddir).trim(), adddirMode: readIf(cap.adddirMode).trim(),
+        artifactMode: readIf(cap.artifactMode).trim(), artifactCopy: readIf(cap.artifactCopy),
+      });
+    });
+    child.stdin.end();
+  });
+
 describe('agy-review.sh — model policy advisory (1)', () => {
   it('warns for a non-frontier model but still runs', () => {
     const sb = makeSandbox();
@@ -424,11 +482,11 @@ describe('agy-review.sh — resume / round-2 delta (7)', () => {
   });
 });
 
-describe('agy-review.sh — delegated guards inherited via agy-run (9, 10)', () => {
-  it('hard timeout: a sleeping stub is killed at AGY_HARD_TIMEOUT', () => {
+describe('agy-review.sh — delegated guards inherited via agy-run (9, 10)', { concurrency: true }, () => {
+  it('hard timeout: a sleeping stub is killed at AGY_HARD_TIMEOUT', async () => {
     const sb = makeSandbox();
     const started = Date.now();
-    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '30', AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s' } });
+    const r = await runAsync(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '30', AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s' } });
     const elapsed = Date.now() - started;
     rmSync(sb.home, { recursive: true, force: true });
     assert.ok(elapsed < 20000, `must return well under the kill-after window, took ${elapsed}ms`);
@@ -552,7 +610,7 @@ const runHelp = (arg) => {
   const root = mkdtempSync(join(tmpdir(), 'agy-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 },
   });
@@ -1078,7 +1136,7 @@ const writeSettings = (sb, text) => {
 };
 const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
 
-describe('agy-review.sh — bridge settings file (bridges 2.3.0)', () => {
+describe('agy-review.sh — bridge settings file (bridges 2.3.0)', { concurrency: true }, () => {
   it('a file-set AGY_REVIEW_ALLOW_ADDDIR=1 arms the oversized --add-dir escape', () => {
     const sb = makeSandbox();
     writeFileSync(join(sb.repo, 'unique.txt'), `OVERSIZE_UNIQUE_MARKER\n${'x'.repeat(8000)}\n`);
@@ -1123,10 +1181,10 @@ describe('agy-review.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.equal(r.invoked, false);
   });
 
-  it('a file-set AGY_HARD_TIMEOUT flows through the agy-run delegation (killed at the file cap)', () => {
+  it('a file-set AGY_HARD_TIMEOUT flows through the agy-run delegation (killed at the file cap)', async () => {
     const sb = makeSandbox();
     writeSettings(sb, 'AGY_HARD_TIMEOUT=2s\n');
-    const r = run(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '5' } });
+    const r = await runAsync(sb, { args: ['code', '--facts', 'f'], env: { AGY_FAKE_SLEEP: '5' } });
     rmSync(sb.home, { recursive: true, force: true });
     assert.notEqual(r.status, 0, 'the file cap must apply end-to-end (reader → agy-run → timeout)');
     assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);

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

@@ -1,10 +1,10 @@
-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, existsSync, readdirSync, symlinkSync, readFileSync } 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, 'agy.sh');
@@ -31,11 +31,23 @@ const runWrapper = (home, env, prompt = 'hello') =>
     timeout: 20000,
   });
 
-describe('agy.sh — hard wall-clock cap (timeout(1))', () => {
-  it('kills a hung agy at AGY_HARD_TIMEOUT and reports it (non-zero + actionable guidance)', () => {
+// Async twin of runWrapper for the sleep-bound suites below: spawnSync BLOCKS the event loop
+// and would serialize the deliberate timeout waits; the async form lets a concurrent describe
+// overlap them (the waiting children are idle, not CPU-bound). Same spawn contract.
+const runWrapperAsync = (home, env, prompt = 'hello') =>
+  new Promise((done) => {
+    execFile('bash', [WRAPPER, prompt], {
+      env: { HOME: home, PATH: `${join(home, '.local', 'bin')}:${process.env.PATH}`, TMPDIR: process.env.TMPDIR ?? '/tmp', ...env },
+      encoding: 'utf8',
+      timeout: 20000,
+    }, (error, stdout, stderr) => done({ status: error ? (error.code ?? 1) : 0, stdout, stderr }));
+  });
+
+describe('agy.sh — hard wall-clock cap (timeout(1))', { concurrency: true }, () => {
+  it('kills a hung agy at AGY_HARD_TIMEOUT and reports it (non-zero + actionable guidance)', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 30\n');
     const started = Date.now();
-    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
     const elapsed = Date.now() - started;
     rmSync(home, { recursive: true, force: true });
     assert.ok(elapsed < 13000, `wrapper must return well under the kill-after window, took ${elapsed}ms`);
@@ -43,17 +55,17 @@ describe('agy.sh — hard wall-clock cap (timeout(1))', () => {
     assert.match(r.stderr, /exceeded the hard cap/, 'must explain the hard-cap kill');
   });
 
-  it('passes a fast agy run through unchanged (exit 0, stdout preserved)', () => {
+  it('passes a fast agy run through unchanged (exit 0, stdout preserved)', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\necho "OK reply"\nexit 0\n');
-    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, `expected clean exit, got ${r.status}; stderr=${r.stderr}`);
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('propagates a non-timeout agy failure code verbatim (no false hard-cap message)', () => {
+  it('propagates a non-timeout agy failure code verbatim (no false hard-cap message)', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\necho "boom" >&2\nexit 3\n');
-    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_HARD_TIMEOUT: '10s', AGY_TIMEOUT: '10s', AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 3, 'a genuine agy failure code must pass through');
     assert.doesNotMatch(r.stderr, /exceeded the hard cap/, 'must not mislabel a non-timeout failure');
@@ -178,6 +190,12 @@ const makePathWithout = (root, exclude = []) => {
   return dir;
 };
 
+// The farm is READ-ONLY per invocation — built ONCE and shared (a per-call rebuild is thousands
+// of symlinks).
+const FARM_ROOT = mkdtempSync(join(tmpdir(), 'agy-farm-'));
+after(() => rmSync(FARM_ROOT, { recursive: true, force: true }));
+const FARM = makePathWithout(FARM_ROOT, ['agy', 'git']);
+
 describe('agy.sh — --help (pre-preflight, candidate C)', () => {
   it('--help and -h exit 0 with NO agy on PATH and name the documented usage', () => {
     for (const arg of ['--help', '-h']) {
@@ -185,7 +203,7 @@ describe('agy.sh — --help (pre-preflight, candidate C)', () => {
       // the help must not need the CLI even when the host has a real agy installed.
       const home = mkdtempSync(join(tmpdir(), 'agy-help-'));
       const r = spawnSync('bash', [WRAPPER, arg], {
-        env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+        env: { HOME: home, PATH: FARM },
         encoding: 'utf8',
         timeout: 15000,
       });
@@ -226,77 +244,77 @@ const writeSettings = (home, text) => {
 };
 const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
 
-describe('agy.sh — bridge settings file (bridges 2.3.0)', () => {
-  it('a file-set AGY_HARD_TIMEOUT is effective (killed at the file cap)', () => {
+describe('agy.sh — bridge settings file (bridges 2.3.0)', { concurrency: true }, () => {
+  it('a file-set AGY_HARD_TIMEOUT is effective (killed at the file cap)', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
     writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { 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 AGY_HARD_TIMEOUT=2s/);
   });
 
-  it('env overrides file: env=2s file=10m → killed at the env cap', () => {
+  it('env overrides file: env=2s file=10m → killed at the env cap', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
     writeSettings(home, 'AGY_HARD_TIMEOUT=10m\n');
-    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_HARD_TIMEOUT: '2s', AGY_TIMEOUT: '2s', AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.notEqual(r.status, 0, 'the env cap (2s) must win over the file cap (10m)');
     assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
   });
 
-  it('an EXPLICITLY EMPTY env (AGY_HARD_TIMEOUT=) disables the file knob for one run', () => {
+  it('an EXPLICITLY EMPTY env (AGY_HARD_TIMEOUT=) disables the file knob for one run', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 3\necho "OK reply"\n');
     writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
-    const r = runWrapper(home, { AGY_HARD_TIMEOUT: '', AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_HARD_TIMEOUT: '', AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, `built-in default must apply (not the 2s file cap): ${r.stderr}`);
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('duplicate key → the LAST occurrence wins (10m then 2s → killed at 2s)', () => {
+  it('duplicate key → the LAST occurrence wins (10m then 2s → killed at 2s)', async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 5\n');
     writeSettings(home, 'AGY_HARD_TIMEOUT=10m\nAGY_HARD_TIMEOUT=2s\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.notEqual(r.status, 0);
     assert.match(r.stderr, /exceeded the hard cap AGY_HARD_TIMEOUT=2s/);
   });
 
-  it('an invalid duration warns and falls back to the built-in default', () => {
+  it('an invalid duration warns and falls back to the built-in default', async () => {
     const home = makeSandbox(RECORDING_STUB);
     writeSettings(home, 'AGY_HARD_TIMEOUT=abc\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(r.stderr, /invalid value 'abc'/);
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('a bare-integer duration (no unit suffix) is invalid → warn + built-in default', () => {
+  it('a bare-integer duration (no unit suffix) is invalid → warn + built-in default', async () => {
     const home = makeSandbox(RECORDING_STUB);
     writeSettings(home, 'AGY_HARD_TIMEOUT=90\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(r.stderr, /invalid value '90'/, 'duration values require a unit suffix (5m/30m/90s)');
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('a ZERO duration is invalid — timeout 0 would silently DISABLE the hard cap', () => {
+  it('a ZERO duration is invalid — timeout 0 would silently DISABLE the hard cap', async () => {
     const home = makeSandbox(RECORDING_STUB);
     writeSettings(home, 'AGY_HARD_TIMEOUT=0s\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(r.stderr, /invalid value '0s'/, 'a persistent settings line must never remove the stall guard');
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('a DIRECTORY at the settings path warns loudly and falls back to built-ins (no crash)', () => {
+  it('a DIRECTORY at the settings path warns loudly and falls back to built-ins (no crash)', async () => {
     const home = makeSandbox(RECORDING_STUB);
     mkdirSync(join(home, '.config', 'agent-workflow', 'bridge-settings.conf'), { recursive: true });
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, `a directory must degrade honestly, not kill the run: ${r.stderr}`);
     assert.match(r.stderr, /unreadable or not a regular file/);
@@ -304,20 +322,20 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.match(r.stdout, /OK reply/);
   });
 
-  it("another bridge's valid key is skipped silently (and never applied)", () => {
+  it("another bridge's valid key is skipped silently (and never applied)", async () => {
     const home = makeSandbox('#!/usr/bin/env bash\nsleep 3\necho "OK reply"\n');
     writeSettings(home, 'CODEX_SERVICE_TIER=priority\nCODEX_HARD_TIMEOUT=2\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, `a codex key must not cap an agy run: ${r.stderr}`);
     assert.doesNotMatch(r.stderr, /bridge settings/, 'a recognized non-applied key earns NO warning');
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('a truly unknown key warns ONCE naming the file; the run is unaffected', () => {
+  it('a truly unknown key warns ONCE naming the file; the run is unaffected', async () => {
     const home = makeSandbox(RECORDING_STUB);
     writeSettings(home, 'TOTALLY_UNKNOWN=1\nTOTALLY_UNKNOWN=2\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     const warns = r.stderr.match(/unknown key 'TOTALLY_UNKNOWN'/g) ?? [];
@@ -326,10 +344,10 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('malformed lines warn and are ignored; comments and blank lines are silent', () => {
+  it('malformed lines warn and are ignored; comments and blank lines are silent', async () => {
     const home = makeSandbox(RECORDING_STUB);
     writeSettings(home, '# a comment\n\nNOT A KEY VALUE LINE\n');
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     const malformed = r.stderr.match(/malformed line/g) ?? [];
@@ -337,22 +355,22 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('an existing-but-unreadable file warns loudly and falls back to built-ins', { skip: isRoot }, () => {
+  it('an existing-but-unreadable file warns loudly and falls back to built-ins', { skip: isRoot }, async () => {
     const home = makeSandbox(RECORDING_STUB);
     const file = writeSettings(home, 'AGY_HARD_TIMEOUT=2s\n');
     chmodSync(file, 0o000);
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.match(r.stderr, /unreadable/);
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('a settings line can NEVER execute code (command-substitution payload inert)', () => {
+  it('a settings line can NEVER execute code (command-substitution payload inert)', async () => {
     const home = makeSandbox(RECORDING_STUB);
     const pwned = join(home, 'pwned');
     writeSettings(home, `AGY_HARD_TIMEOUT=$(touch ${pwned})\nEVIL_KEY=\`touch ${pwned}2\`\n`);
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     const executed = existsSync(pwned) || existsSync(`${pwned}2`);
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
@@ -360,9 +378,9 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', () => {
     assert.match(r.stdout, /OK reply/);
   });
 
-  it('no file → byte-identical behaviour to today (no settings chatter)', () => {
+  it('no file → byte-identical behaviour to today (no settings chatter)', async () => {
     const home = makeSandbox(RECORDING_STUB);
-    const r = runWrapper(home, { AGY_MODEL: '' });
+    const r = await runWrapperAsync(home, { AGY_MODEL: '' });
     rmSync(home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.doesNotMatch(r.stderr, /bridge settings/);
@@ -398,7 +416,7 @@ describe('agy.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () =>
   const runHelpText = () => {
     const home = mkdtempSync(join(tmpdir(), 'agy-settings-help-'));
     const r = spawnSync('bash', [WRAPPER, '--help'], {
-      env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+      env: { HOME: home, PATH: FARM },
       encoding: 'utf8',
       timeout: 15000,
     });
@@ -475,7 +493,7 @@ describe('agy.sh — mode catalog ⟷ wrapper reality (the contract-free raw mod
   const helpText = () => {
     const home = mkdtempSync(join(tmpdir(), 'agy-catalog-help-'));
     const r = spawnSync('bash', [WRAPPER, '--help'], {
-      env: { HOME: home, PATH: makePathWithout(home, ['agy', 'git']) },
+      env: { HOME: home, PATH: FARM },
       encoding: 'utf8',
       timeout: 15000,
     });