harness-everything 0.31.2 → 0.31.3

package/ci/mechanism-2au-codex-runtime-safety.test.js

@@ -0,0 +1,340 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const compat = require('../scripts/codex-hooks-compat');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-323-'));
+let failures = 0;
+function test(name, run) {
+  try { run(); console.log('PASS ' + name); }
+  catch (error) { failures++; console.error('FAIL ' + name + ': ' + error.message); }
+}
+// Git for Windows rejects the NUL device as a config file; use real empty paths.
+const gitConfig = path.join(root, 'empty.gitconfig');
+const gitHooks = path.join(root, 'no-git-hooks');
+fs.writeFileSync(gitConfig, '');
+fs.mkdirSync(gitHooks);
+function samePathOf(left, right) {
+  const normalize = value => path.resolve(value).toLowerCase();
+  return Boolean(left && right) && normalize(left) === normalize(right);
+}
+function git(cwd, args) {
+  const result = spawnSync('git', ['-c', 'core.hooksPath=' + gitHooks, ...args], {
+    cwd, encoding: 'utf8', env: { ...process.env, GIT_CONFIG_GLOBAL: gitConfig, GIT_CONFIG_NOSYSTEM: '1' },
+  });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return result.stdout.trim();
+}
+try {
+  test('A survives B; C collects A; repeat C retains B; uninstall removes retained runtimes', () => {
+    const source = path.join(root, 'cache', 'plugin');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, source, { recursive: true });
+    const codexHome = path.join(root, 'retention-home');
+    const install = () => compat.install({ codexHome, sourcePluginRoot: source });
+    const a = install();
+    fs.writeFileSync(path.join(source, 'revision.txt'), 'B');
+    const b = install();
+    const oldScript = path.join(a.runtimeDir, 'hooks', 'scripts', 'codex-action-gate-pre.js');
+    assert(fs.existsSync(oldScript), 'A hook script must still resolve after B');
+    // Resolve the retained script without executing a hook against any user state.
+    assert.strictEqual(require.resolve(oldScript), fs.realpathSync(oldScript));
+    fs.writeFileSync(path.join(source, 'revision.txt'), 'C');
+    const c = install();
+    assert(!fs.existsSync(a.runtimeDir), 'third distinct install must collect A');
+    assert(fs.existsSync(b.runtimeDir));
+    install();
+    assert(fs.existsSync(b.runtimeDir), 'same-fingerprint update must retain B');
+    assert.deepStrictEqual(fs.readdirSync(path.dirname(c.runtimeDir)).sort(),
+      [path.basename(b.runtimeDir), path.basename(c.runtimeDir)].sort());
+    compat.uninstall({ codexHome });
+    assert(!fs.existsSync(path.dirname(c.runtimeDir)), 'uninstall removes every retained runtime');
+  });
+
+  test('status reports a lost previous runtime; same-fingerprint reinstall resets it', () => {
+    const source = path.join(root, 'cache', 'plugin-health');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, source, { recursive: true });
+    const codexHome = path.join(root, 'health-home');
+    const install = () => compat.install({ codexHome, sourcePluginRoot: source });
+    const a = install();
+    fs.writeFileSync(path.join(source, 'revision.txt'), 'B');
+    const b = install();
+    let report = compat.status({ codexHome });
+    assert.strictEqual(report.healthy, true);
+    assert.strictEqual(report.runtimes.previous.status, 'present');
+    assert(report.runtimes.previous.runtimeDir === a.runtimeDir);
+    fs.writeFileSync(path.join(a.runtimeDir, 'tampered.txt'), 'x');
+    report = compat.status({ codexHome });
+    assert.strictEqual(report.healthy, false);
+    assert.strictEqual(report.runtimes.previous.status, 'modified');
+    fs.rmSync(a.runtimeDir, { recursive: true, force: true });
+    report = compat.status({ codexHome });
+    assert.strictEqual(report.healthy, false, 'missing previous runtime must not report healthy');
+    assert.strictEqual(report.runtimes.current.healthy, true);
+    assert.strictEqual(report.runtimes.previous.status, 'missing');
+    assert.strictEqual(report.observationCapture.status, 'configured-unverified');
+    assert.strictEqual(report.observationCapture.reason, 'previous-runtime-missing');
+    const cli = spawnSync(process.execPath, [path.resolve(__dirname, '../scripts/codex-hooks-compat.js'),
+      'status', '--codex-home', codexHome], { encoding: 'utf8' });
+    assert.strictEqual(cli.status, 1, 'CLI status must fail when the previous runtime is lost');
+    const again = install();
+    assert.strictEqual(again.runtimeDir, b.runtimeDir);
+    report = compat.status({ codexHome });
+    assert.strictEqual(report.healthy, true);
+    assert.strictEqual(report.runtimes.previous.status, 'none');
+    compat.uninstall({ codexHome });
+  });
+
+  test('overlapping installs serialize; neither collects the other current runtime', () => {
+    const codexHome = path.join(root, 'concurrent-home');
+    const base = path.join(root, 'cache', 'plugin-concurrent');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, base, { recursive: true });
+    const a = compat.install({ codexHome, sourcePluginRoot: base });
+    const sources = {};
+    for (const id of ['B', 'C']) {
+      sources[id] = path.join(root, 'cache', 'plugin-concurrent-' + id);
+      fs.cpSync(base, sources[id], { recursive: true });
+      fs.writeFileSync(path.join(sources[id], 'revision.txt'), id);
+    }
+    const barrier = path.join(root, 'barrier');
+    fs.mkdirSync(barrier);
+    // Each child waits after preparing its runtime until the peer has also prepared one,
+    // forcing the reviewer's interleaving. A serialized peer never arrives, so the wait
+    // is bounded and the first holder proceeds alone.
+    const child = path.join(root, 'concurrent-child.js');
+    fs.writeFileSync(child, `
+      const fs = require('fs');
+      const path = require('path');
+      const [compatPath, codexHome, source, barrier, id, peer] = process.argv.slice(2);
+      const compat = require(compatPath);
+      const result = compat.install({ codexHome, sourcePluginRoot: source, onRuntimeReady() {
+        fs.writeFileSync(path.join(barrier, id), '');
+        const deadline = Date.now() + 1500;
+        while (!fs.existsSync(path.join(barrier, peer)) && Date.now() < deadline) {
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+        }
+      } });
+      process.stdout.write(JSON.stringify(result));
+    `);
+    const driver = path.join(root, 'concurrent-driver.js');
+    fs.writeFileSync(driver, `
+      const { spawn } = require('child_process');
+      const [child, compatPath, codexHome, barrier, sourceB, sourceC] = process.argv.slice(2);
+      const runs = [['B', 'C', sourceB], ['C', 'B', sourceC]].map(([id, peer, source]) => new Promise(resolve => {
+        const proc = spawn(process.execPath, [child, compatPath, codexHome, source, barrier, id, peer]);
+        let out = '', err = '';
+        proc.stdout.on('data', chunk => { out += chunk; });
+        proc.stderr.on('data', chunk => { err += chunk; });
+        proc.on('close', code => resolve({ id, code, out, err }));
+      }));
+      Promise.all(runs).then(results => process.stdout.write(JSON.stringify(results)));
+    `);
+    const compatPath = path.resolve(__dirname, '../scripts/codex-hooks-compat.js');
+    const run = spawnSync(process.execPath, [driver, child, compatPath, codexHome, barrier, sources.B, sources.C],
+      { encoding: 'utf8', timeout: 120000 });
+    assert.strictEqual(run.status, 0, run.stderr);
+    const results = JSON.parse(run.stdout);
+    for (const result of results) assert.strictEqual(result.code, 0, result.id + ': ' + result.err);
+    const installed = Object.fromEntries(results.map(result => [result.id, JSON.parse(result.out).runtimeDir]));
+
+    const manifest = JSON.parse(fs.readFileSync(compat.pathsFor(codexHome).manifestFile, 'utf8'));
+    assert(fs.existsSync(manifest.runtimeDir), 'final current runtime must exist');
+    assert.strictEqual(compat.treeHash(manifest.runtimeDir), manifest.sourcePluginSha256);
+    const other = samePathOf(manifest.runtimeDir, installed.B) ? installed.C : installed.B;
+    assert(samePathOf(manifest.previousRuntimeDir, other), 'serialized peer becomes the previous runtime');
+    assert(fs.existsSync(other), 'no installer may collect the peer runtime it just committed');
+    assert(!fs.existsSync(a.runtimeDir), 'only the oldest runtime is collected');
+    const hooks = fs.readFileSync(path.join(codexHome, 'hooks.json'), 'utf8').replace(/\\\\/g, '/');
+    const runtime = manifest.runtimeDir.replace(/\\/g, '/');
+    const referenced = hooks.match(new RegExp(runtime.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/[^"\\s]+\\.js', 'g')) || [];
+    assert(referenced.length > 0, 'hooks.json must reference the current runtime');
+    for (const file of referenced) assert(fs.existsSync(file), 'configured command must resolve: ' + file);
+    assert.strictEqual(compat.status({ codexHome }).healthy, true);
+    assert(!fs.existsSync(compat.pathsFor(codexHome).ownerRoot + '.lock'), 'lock must be released');
+    compat.uninstall({ codexHome });
+  });
+
+  test('stale lock from a dead process is broken; a live lock times out before writes', () => {
+    const source = path.join(root, 'cache', 'plugin-lock');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, source, { recursive: true });
+    const codexHome = path.join(root, 'lock-home');
+    const lockDir = compat.pathsFor(codexHome).ownerRoot + '.lock';
+    const dead = spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' });
+    for (const dir of [lockDir, lockDir + '.guard']) {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'owner.json'),
+        JSON.stringify({ pid: Number(dead.stdout), hostname: os.hostname(), token: 'crashed' }));
+    }
+    compat.install({ codexHome, sourcePluginRoot: source, lockTimeoutMs: 5000 });
+    assert(!fs.existsSync(lockDir), 'stale lock must be replaced and released');
+    assert(!fs.existsSync(lockDir + '.guard'), 'guard left by a crashed process must be reclaimed');
+
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, 'owner.json'), JSON.stringify({ pid: process.pid, hostname: os.hostname() }));
+    const before = fs.readFileSync(path.join(codexHome, 'hooks.json'));
+    fs.writeFileSync(path.join(source, 'revision.txt'), 'locked');
+    assert.throws(() => compat.install({ codexHome, sourcePluginRoot: source, lockTimeoutMs: 200 }), /timed out.*lock/i);
+    assert.throws(() => compat.uninstall({ codexHome, lockTimeoutMs: 200 }), /timed out.*lock/i);
+    assert.deepStrictEqual(fs.readFileSync(path.join(codexHome, 'hooks.json')), before);
+    assert.strictEqual(fs.readdirSync(compat.pathsFor(codexHome).runtimeRoot).length, 1, 'no runtime created while locked');
+    fs.rmSync(lockDir, { recursive: true });
+    compat.uninstall({ codexHome });
+    assert(!fs.existsSync(path.join(codexHome, 'harness-everything')), 'uninstall leaves no owner or lock directories');
+  });
+
+  test('three-contender stale-lock recovery admits at most one holder', () => {
+    const codexHome = path.join(root, 'stale-race-home');
+    const base = path.join(root, 'cache', 'plugin-stale-race');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, base, { recursive: true });
+    compat.install({ codexHome, sourcePluginRoot: base });
+    const sources = {};
+    for (const id of ['A', 'B', 'C']) {
+      sources[id] = path.join(root, 'cache', 'plugin-stale-race-' + id);
+      fs.cpSync(base, sources[id], { recursive: true });
+      fs.writeFileSync(path.join(sources[id], 'revision.txt'), id);
+    }
+    // Leave a lock owned by a dead local process.
+    const lockDir = compat.pathsFor(codexHome).ownerRoot + '.lock';
+    const dead = spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' });
+    fs.mkdirSync(lockDir);
+    fs.writeFileSync(path.join(lockDir, 'owner.json'),
+      JSON.stringify({ pid: Number(dead.stdout), hostname: os.hostname(), token: 'dead' }));
+    const barrier = path.join(root, 'stale-barrier');
+    fs.mkdirSync(barrier);
+    // Reviewer interleaving: A and B both observe the stale owner; A reclaims and holds;
+    // B then reclaims late and pauses after its rename, so C can take the vacated path.
+    // Each holder claims an exclusive marker for 1.5 s inside its critical section.
+    const child = path.join(root, 'stale-race-child.js');
+    fs.writeFileSync(child, `
+      const fs = require('fs');
+      const path = require('path');
+      const [compatPath, codexHome, source, barrier, id] = process.argv.slice(2);
+      const compat = require(compatPath);
+      const sleep = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+      const waitFor = (names, ms) => {
+        const deadline = Date.now() + ms;
+        while (!names.every(name => fs.existsSync(path.join(barrier, name))) && Date.now() < deadline) sleep(10);
+      };
+      if (id === 'C') waitFor(['A-stale', 'B-stale'], 3000);
+      let overlap = false;
+      const result = compat.install({
+        codexHome, sourcePluginRoot: source,
+        onLockEvent(event) {
+          if (event === 'stale-observed' && id !== 'C') {
+            fs.writeFileSync(path.join(barrier, id + '-stale'), '');
+            waitFor(['A-stale', 'B-stale'], 1500);
+            if (id === 'B') sleep(400);
+          }
+          if (event === 'reclaim-renamed' && id === 'B') sleep(800);
+        },
+        onRuntimeReady() {
+          const marker = path.join(barrier, 'holder');
+          try { fs.writeFileSync(marker, id, { flag: 'wx' }); }
+          catch (_) { overlap = true; return; }
+          sleep(1500);
+          fs.rmSync(marker);
+        },
+      });
+      if (overlap) { process.stderr.write(id + ' entered the critical section concurrently'); process.exit(3); }
+      process.stdout.write(JSON.stringify(result));
+    `);
+    const driver = path.join(root, 'stale-race-driver.js');
+    fs.writeFileSync(driver, `
+      const { spawn } = require('child_process');
+      const [child, compatPath, codexHome, barrier, ...sources] = process.argv.slice(2);
+      const runs = ['A', 'B', 'C'].map((id, index) => new Promise(resolve => {
+        const proc = spawn(process.execPath, [child, compatPath, codexHome, sources[index], barrier, id]);
+        let out = '', err = '';
+        proc.stdout.on('data', chunk => { out += chunk; });
+        proc.stderr.on('data', chunk => { err += chunk; });
+        proc.on('close', code => resolve({ id, code, out, err }));
+      }));
+      Promise.all(runs).then(results => process.stdout.write(JSON.stringify(results)));
+    `);
+    const compatPath = path.resolve(__dirname, '../scripts/codex-hooks-compat.js');
+    const run = spawnSync(process.execPath,
+      [driver, child, compatPath, codexHome, barrier, sources.A, sources.B, sources.C],
+      { encoding: 'utf8', timeout: 180000 });
+    assert.strictEqual(run.status, 0, run.stderr);
+    const failed = JSON.parse(run.stdout).filter(result => result.code !== 0)
+      .map(result => result.id + ' exit ' + result.code + ': ' +
+        (result.err.split('\n').find(line => /Error|concurrently/.test(line)) || result.err.trim()));
+    assert.deepStrictEqual(failed, [], 'every contender must succeed exclusively');
+    const manifest = JSON.parse(fs.readFileSync(compat.pathsFor(codexHome).manifestFile, 'utf8'));
+    assert(fs.existsSync(manifest.runtimeDir), 'final current runtime must exist');
+    assert.strictEqual(compat.treeHash(manifest.runtimeDir), manifest.sourcePluginSha256);
+    assert(manifest.previousRuntimeDir && fs.existsSync(manifest.previousRuntimeDir), 'previous runtime must exist');
+    assert.strictEqual(compat.status({ codexHome }).healthy, true);
+    assert(!fs.existsSync(lockDir), 'lock must be released');
+    const leftovers = fs.readdirSync(path.dirname(lockDir)).filter(name => name !== 'compat-hooks');
+    assert.deepStrictEqual(leftovers, [], 'no stale tombs or guards may remain');
+    compat.uninstall({ codexHome });
+  });
+
+  const repo = path.join(root, 'repo');
+  const source = path.join(repo, 'plugins', 'harness-everything');
+  fs.cpSync(compat.SOURCE_PLUGIN_ROOT, source, { recursive: true });
+  git(repo, ['init']);
+  git(repo, ['add', '.']);
+  git(repo, ['-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-m', 'fixture']);
+  test('tracked plugin in ordinary checkout allows unrelated untracked files', () => {
+    fs.writeFileSync(path.join(repo, 'unrelated.txt'), 'unrelated');
+    compat.install({ codexHome: path.join(root, 'unrelated-home'), sourcePluginRoot: source });
+  });
+  test('packaged source inside unrelated dirty repository is allowed', () => {
+    const packaged = path.join(repo, 'node_modules', 'harness', 'plugins', 'harness-everything');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, packaged, { recursive: true });
+    compat.install({ codexHome: path.join(root, 'packaged-home'), sourcePluginRoot: packaged });
+  });
+  test('ignored files inside plugin subtree are excluded from the runtime, not refused', () => {
+    fs.writeFileSync(path.join(repo, '.gitignore'), '*.ignored\n.DS_Store\n');
+    git(repo, ['add', '.gitignore']);
+    git(repo, ['-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-m', 'ignore']);
+    const codexHome = path.join(root, 'ignored-home');
+    const baseline = compat.install({ codexHome, sourcePluginRoot: source });
+    const ignored = [path.join(source, 'hooks', 'scripts', 'payload.ignored'), path.join(source, '.DS_Store')];
+    for (const file of ignored) fs.writeFileSync(file, 'ignored content');
+    try {
+      const result = compat.install({ codexHome, sourcePluginRoot: source });
+      assert.strictEqual(result.runtimeDir, baseline.runtimeDir, 'ignored files must not change the fingerprint');
+      assert(!fs.existsSync(path.join(result.runtimeDir, 'hooks', 'scripts', 'payload.ignored')));
+      assert(!fs.existsSync(path.join(result.runtimeDir, '.DS_Store')));
+      assert.strictEqual(compat.status({ codexHome }).healthy, true);
+    } finally {
+      for (const file of ignored) fs.rmSync(file);
+    }
+  });
+  test('clean ordinary checkout installs; dirty checkout refuses before writes; explicit opt-in works', () => {
+    const codexHome = path.join(root, 'dirty-home');
+    compat.install({ codexHome, sourcePluginRoot: source });
+    fs.writeFileSync(path.join(source, 'unreleased.txt'), 'dirty');
+    const before = fs.readFileSync(path.join(codexHome, 'hooks.json'));
+    assert.throws(() => compat.install({ codexHome, sourcePluginRoot: source }), /unreleased|dirty/i);
+    assert.deepStrictEqual(fs.readFileSync(path.join(codexHome, 'hooks.json')), before);
+    compat.install({ codexHome, sourcePluginRoot: source, allowUnreleasedSource: true });
+    fs.rmSync(path.join(source, 'unreleased.txt'));
+  });
+  test('linked worktree refuses even when clean; explicit opt-in works', () => {
+    const linked = path.join(root, 'linked');
+    git(repo, ['worktree', 'add', '-b', 'fixture-linked', linked]);
+    const codexHome = path.join(root, 'linked-home');
+    const sourcePluginRoot = path.join(linked, 'plugins', 'harness-everything');
+    assert.throws(() => compat.install({ codexHome, sourcePluginRoot }), /unreleased|worktree/i);
+    assert(!fs.existsSync(codexHome), 'source refusal must happen before writes');
+    compat.install({ codexHome, sourcePluginRoot, allowUnreleasedSource: true });
+    const packaged = path.join(linked, 'cache', 'harness');
+    fs.cpSync(compat.SOURCE_PLUGIN_ROOT, packaged, { recursive: true });
+    compat.install({ codexHome: path.join(root, 'linked-cache-home'), sourcePluginRoot: packaged });
+  });
+  test('CLI forwards explicit unreleased-source opt-in', () => {
+    const codexHome = path.join(root, 'cli-home');
+    const script = path.resolve(__dirname, '../scripts/codex-hooks-compat.js');
+    const result = spawnSync(process.execPath, [script, 'install', '--codex-home', codexHome, '--allow-unreleased-source'], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  });
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+process.exitCode = failures ? 1 : 0;

package/ci/mechanism-2av-test-home-isolation.test.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-runner-isolation-'));
+try {
+  const repo = path.join(root, 'fixture');
+  const ci = path.join(repo, 'ci');
+  fs.mkdirSync(path.join(ci, 'lib'), { recursive: true });
+  fs.copyFileSync(path.join(__dirname, 'mechanism-test.js'), path.join(ci, 'mechanism-test.js'));
+  const helper = path.join(__dirname, 'lib', 'isolated-test-process.js');
+  if (fs.existsSync(helper)) fs.copyFileSync(helper, path.join(ci, 'lib', 'isolated-test-process.js'));
+  const report = path.join(root, 'child.json');
+  fs.writeFileSync(path.join(ci, 'mechanism-fixture.test.js'), `
+    const fs = require('fs');
+    const assert = require('assert');
+    const os = require('os');
+    const path = require('path');
+    assert.notStrictEqual(process.env.CODEX_HOME, process.env.PARENT_CODEX_HOME);
+    assert.notStrictEqual(process.env.HOME, process.env.PARENT_HOME);
+    assert.strictEqual(process.env.CODEX_HOME, path.join(process.env.HOME, '.codex'));
+    assert.strictEqual(os.homedir(), process.env.HOME);
+    fs.mkdirSync(process.env.CODEX_HOME, { recursive: true });
+    fs.writeFileSync(path.join(process.env.CODEX_HOME, 'child-proof'), 'isolated');
+    fs.writeFileSync(process.env.ISOLATION_REPORT, JSON.stringify({home: process.env.HOME}));
+  `);
+  const parentHome = path.join(root, 'parent-home');
+  const parentCodex = path.join(parentHome, '.codex');
+  const result = spawnSync(process.execPath, [path.join(ci, 'mechanism-test.js')], {
+    encoding: 'utf8', env: { ...process.env, HOME: parentHome, USERPROFILE: parentHome,
+      CODEX_HOME: parentCodex, PARENT_HOME: parentHome, PARENT_CODEX_HOME: parentCodex,
+      ISOLATION_REPORT: report },
+  });
+  assert.strictEqual(result.status, 0, result.stdout + result.stderr);
+  const child = JSON.parse(fs.readFileSync(report, 'utf8'));
+  assert(!fs.existsSync(child.home), 'runner must clean its temporary home');
+  assert(!fs.existsSync(parentHome), 'runner must not write into inherited home');
+  // Both entry points must use the same isolated spawn implementation.
+  const regression = fs.readFileSync(path.join(__dirname, '../self-evolve/scripts/self-regression.js'), 'utf8');
+  assert(regression.includes('spawnTestNode('));
+  assert(!regression.includes("spawnSync('node'"));
+  console.log('PASS mechanism child receives a temporary CODEX_HOME/HOME; shared self-regression isolation and cleanup verified');
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}

package/ci/mechanism-test.js

@@ -7,7 +7,7 @@
  * keeps the test code highly decoupled, and simplifies debugging and adding new test suites.
  */
 
-const { spawnSync } = require('child_process');
+const { spawnTestNode } = require('./lib/isolated-test-process');
 const fs = require('fs');
 const path = require('path');
 
@@ -35,7 +35,7 @@ files.forEach(file => {
   const filePath = path.join(evalDir, file);
   console.log(`\n▶️  Running test suite: ${file}`);
   
-  const testRun = spawnSync('node', [filePath], {
+  const testRun = spawnTestNode([filePath], {
     stdio: 'inherit',
     cwd: projectRoot,
     env: { ...process.env, CLAUDE: '1' }

package/docs/platform-capabilities.md

@@ -116,6 +116,10 @@ harness codex-hooks uninstall
 
 The installer copies the current packaged runtime into `$CODEX_HOME/harness-everything/compat-hooks/` and merges absolute-path entries into `$CODEX_HOME/hooks.json`. harness codex-hooks status reports `inactive` when the compatibility hooks are absent, or `configured-unverified` when their files are healthy; it cannot read Codex trust state. A successful Codex run of plugin-sync.js installs or refreshes this copy automatically. The installer does **not** modify `config.toml`, trust hashes, approval policy, or hook enablement. Codex must still show/review/trust the resulting non-managed hooks through its normal `/hooks` flow.
 
+Updates retain at most two fingerprinted runtimes: the current runtime and the immediately previous distinct runtime. A third distinct install collects the oldest; sessions older than one update must restart. Reinstalling the same fingerprint preserves an intact previous runtime and drops a missing or modified one. `status` reports current and previous runtime file integrity separately and is unhealthy while a recorded previous runtime is missing or modified; this is filesystem health, not Codex hook trust or dispatch. Install, update, and uninstall hold an exclusive `compat-hooks.lock` directory for the whole manifest-read → runtime → hooks/manifest commit → collection transaction, so concurrent installers serialize instead of collecting each other's runtime. Each lock directory is created atomically together with its owner token. Acquisition and stale reclaim run under a short-lived `compat-hooks.lock.guard`, stale ownership is revalidated inside it, and a lock is removed only when it still carries the exact token judged stale; release likewise removes only the releasing holder's token. A lock or guard left by a dead local process is reclaimed, and a live lock times out (60 s) before any write. Uninstall removes all retained Harness-owned runtimes. Command paths remain fingerprinted: updates may require normal Codex hook review again; Harness does not bypass that security decision.
+
+Installs of a plugin source tracked by a linked Git worktree refuse before writing. For an ordinary checkout, only modified or untracked files inside the plugin source subtree cause refusal. The runtime is built from the subtree's Git-tracked files, so `.gitignore`-excluded files (for example `.DS_Store` or `__pycache__`) are neither copied nor fingerprinted and do not block installation. The operator can explicitly pass `--allow-unreleased-source`. Packaged copies whose plugin manifest is not tracked by an enclosing repository remain supported, including copies inside an unrelated dirty repository. The mechanism and self-regression runners give child processes temporary HOME/USERPROFILE and CODEX_HOME directories. Tests must pass temporary Codex homes or mock the hook installer; mocking host commands alone does not isolate filesystem writes.
+
 Ownership is deliberately strict: update/uninstall removes only exact entries recorded in the Harness compatibility manifest. If an installed Harness entry was edited after installation, the operation fails closed rather than overwriting or deleting that user-modified entry. Unrelated pre-existing and later-added user hooks are preserved.
 
 The compatibility path registers hook commands in Codex user configuration and covers the missing plugin-mount route where user hooks dispatch. It does not repair a Codex carrier that fails to dispatch `PreToolUse` at all; those host-level execution-path limitations remain a live compatibility boundary.

package/docs/platform-compatibility.json

@@ -114,7 +114,7 @@
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
         "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "General Harness installer ownership is mechanism-tested. The optional codex-hooks compatibility fallback separately has exact-entry update/uninstall ownership tests and preserves unrelated user hooks. Live evidence confirms trusted dispatch for the two observation handlers on one Windows Codex CLI host; native plugin mounting and other scopes remain unverified."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
-        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; after successful install/update verification it refreshes the local codex-hooks compatibility runtime and hooks.json entries. Unsupported CLI options are dropped and retried, and a Codex build without codex plugin list/add is reported as an actionable capability-boundary skip. Live marketplace source reporting and plugin-sync refresh remain unverified; the separate compatibility fallback dispatch is live-verified as recorded in the evidence artifact."},
+        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; after successful install/update verification it refreshes the local codex-hooks compatibility runtime and hooks.json entries, retaining current plus previous distinct runtime. Tracked linked-worktree sources or dirty plugin subtrees require explicit unreleased-source opt-in; untracked packaged sources remain supported even inside unrelated dirty repositories. Unsupported CLI options are dropped and retried, and a Codex build without codex plugin list/add is reported as an actionable capability-boundary skip. Live marketplace source reporting and plugin-sync refresh remain unverified; the separate compatibility fallback dispatch is live-verified as recorded in the evidence artifact."},
         "liveHostVerification": {"status": "Partial", "evidence": "benchmarks/results/live-host/codex-2026-10-13/README.md", "notes": "The preserved artifact verifies two consecutive observation captures through the user-hook compatibility fallback on Codex CLI 0.162.1 for Windows, including current-turn labels. Native plugin mounting, marketplace source reporting, other lifecycle events, and other host/version combinations remain unverified."}
       }
     },

package/fable-mode/SKILL.md

@@ -4,7 +4,7 @@ description: "Stage large tasks through plans, named fable agents, failable chec
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode

package/fable-mode/execution-guardrails/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference guardrails for verified warnings and safe replacements;
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Execution Guardrails

package/fable-mode/fable-haiku/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference mechanical behavior profile (legacy alias haiku) for bul
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Haiku

package/fable-mode/fable-opus/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference orchestrator behavior profile (legacy alias opus) for st
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Opus

package/fable-mode/fable-sonnet/SKILL.md

@@ -4,7 +4,7 @@ description: "Reference reasoning behavior profile (legacy alias sonnet/sonnect)
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.31.0
+  version: 0.31.3
 ---
 
 # Fable Mode — Sonnet

package/fable-mode/references/execution-phases.md

@@ -2,37 +2,105 @@
 
 ```mermaid
 flowchart TD
-  Start[Qualifying Tier 3 task] --> Discover[Discover sources, runtime, and authorized scope]
-  Discover --> Plan[Write stage map and pass conditions]
-  Plan --> Select[Resolve requested model and write audit record]
-  Select --> Delegate[Delegate to named agent or visible inline fallback]
-  Delegate --> Contract[Write stage contract]
-  Contract --> Verify[Run the named failable check]
-  Verify --> Review[Cold-review high-stakes deliverables]
-  Review --> Done[Record result or escalate blocker]
+  Start[Qualifying Tier 3 task] --> Discover[Discover runtime and authorized scope]
+  Discover --> Profile[Resolve behavior profile and runtime choice]
+  Profile --> Plan[Write dependency-aware stage map and checks]
+  Plan --> Register[Write workflow-stages.json in session state]
+  Register --> Execute[Start workflow-disposition and execute ready stages]
+  Execute --> Check[Run exact check and record correlated evidence]
+  Check --> Review[Cold-review when the selected plan requires it]
+  Review --> Done[Record result or blocker]
 ```
 
 ## Discovery and planning
 
-Read the relevant files and sources before producing an artifact. Lock the
-authorized write scope in the handoff. Number the stages, assign one artifact
-and one pass condition to each. Replan counts are advisory and never a hard
-stop; three same-signature failures still require Rule-of-3 `zoom-out`.
+Read relevant files and sources before producing an artifact. Record the
+authorized write scope. Give each stage an objective, dependencies, write set,
+expected output, exact check command, and pass condition. Required and optional
+bindings belong on the stage that needs them. Replan counts are advisory; after
+three same-signature failures, use Rule-of-3 `zoom-out`.
 
-## Delegation
+## Profiles and delegation
 
-Use `fable-orchestrator` for Opus macro work, `fable-worker-sonnet` for
-reasoning and synthesis, and `fable-worker-haiku` for mechanical work. Brief
-each worker with its exact output path, context, audit record, and check.
-Workers do not spawn workers. If the named agent is unavailable, choose the
-explicit inline fallback or stop and escalate; do not silently change models.
+Resolve a requested behavior profile with Fable's profile selector and record
+it separately from the runtime choice. `fable-orchestrator`,
+`fable-worker-sonnet`, and `fable-worker-haiku` name coordination,
+reasoning/synthesis, and mechanical-work roles. These are behavior-profile
+aliases; they do not switch the runtime model. Preserve an explicit user or
+host runtime choice. Workers do not spawn workers. If a named worker is
+unavailable, use a declared inline fallback or report the gap.
 
-## Verification and handoff
+## Active workflow
+
+For an active mandatory workflow, use the router-displayed session path for
+`workflow-stages.json` and the router-displayed `workflow-disposition.js`
+controller. Do not register active stages in a repository-local contracts
+directory. Every required stage needs `dependsOn`, `writeSet`, `checkCommand`,
+and `passCondition`; an independent plan also needs a read-only `fable-verifier`
+stage that depends on all implementation stages.
+
+Start the selected run with the controller path and session id from the router:
+
+```bash
+node "<workflow-disposition.js path from the router>" start --session-id "<session-id>"
+```
+
+The controller creates correlated run-scoped contracts. Load only bindings on
+dependency-ready stages. Record each disposition with evidence:
+
+```bash
+node "<workflow-disposition.js path from the router>" stage-binding \
+  --session-id "<session-id>" --stage-id "<stage-id>" \
+  --binding-id "<binding-id>" --disposition loaded \
+  --evidence "Read the resolved required reference for this stage."
+```
+
+Run the exact `checkCommand`; the post-tool `contract-test.js` records the
+session, run, stage, worker identity, numeric exit code, and check evidence. If
+bindings are unresolved, resolve them and rerun the exact check before passing
+the stage. Keep results under the run's `contracts/<stageId>.json` and
+`evidence/<stageId>.json` records. Stage checks, required bindings, and selected
+independent verification remain semantic MUSTs. The controller and lifecycle
+hooks are reminder-only: unresolved evidence stays visible without locking
+ordinary tools or Stop. See [`../CONTRACT-FORMAT.md`](../CONTRACT-FORMAT.md) for
+the schema and correlation rules.
+
+## Blocked recovery
 
-Before each spot-check, create `.claude/harness-everything/state/contracts/<stage>.json`
-using `CONTRACT-FORMAT.md`, then run the exact command in that contract. A
-stage is not complete until the command passes and the audit record contains
-the verifier result. Use `fable-verifier` with only the spec and artifact for
-high-stakes or unsupervised delivery. Review scope-guard output before merging.
+If `start` is called while the workflow is running, it exits 2 with
+`workflow already running; record a blocker before replanning`. From that
+running state, record evidence with `block`:
+
+```bash
+node "<workflow-disposition.js path from the router>" block \
+  --session-id "<session-id>" \
+  --evidence "The current stage map needs a bounded recovery update."
+```
+
+Update the same session's `workflow-stages.json`, retaining the approved
+requirements, workflow selection, dependencies, and required bindings. Then
+start the revised stage map:
+
+```bash
+node "<workflow-disposition.js path from the router>" start --session-id "<session-id>"
+```
+
+This starts a new run and clears the recorded block reason. If the session is
+already `blocked`, update its stage map and run `start` directly. Do not call
+`plan` from `blocked`: planning is accepted only while the workflow is pending
+or active. When an explicitly authorized scope change requires new requirement
+composition, route a new session instead of replacing approved requirements.
+
+## Legacy/manual fallback
+
+The path `.claude/harness-everything/state/contracts/<stage>.json` belongs only
+to an explicitly selected legacy/manual workflow without an active mandatory
+run. It does not register stages or correlated evidence for the current
+workflow controller. Do not use it for an active Fable workflow.
+
+## Verification and handoff
 
-When macro scaffolding ends, transition to `tdd` for focused implementation.
+Run each named check and review scope-guard evidence before delivery. When the
+selected plan requires independent verification, the verifier is read-only and
+uses a distinct worker identity after all other stages pass. Record a blocker
+or an evidence-backed result; do not discard unresolved requirements.

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.31.2",
+  "version": "0.31.3",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"