@voybio/ace-swarm 2.4.8 → 2.4.10

package/scripts/dev/run-tests-isolated.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Run the whole test process outside the developer's workspace, including fallbacks.
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, statSync, symlinkSync, writeFileSync, realpathSync, renameSync, unlinkSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { spawn, spawnSync, execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { testSourceFiles, findTestDependencies } from './test-source-inventory.mjs';
+
+const source = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+// Darwin sockaddr_un paths are short. Keep every allocated fixture beneath a
+// canonical short base so native control sockets fit without moving outside it.
+const sandbox = mkdtempSync(join(process.platform === 'darwin' ? '/private/tmp' : tmpdir(), 'at-'));
+const checkout = join(sandbox, "checkout");
+mkdirSync(checkout);
+const fixtures = join(sandbox, 'fixtures'); const registry = join(sandbox, 'owned-node-processes');
+mkdirSync(fixtures); mkdirSync(registry);
+
+function stateHashes(root) {
+  const values = {};
+  function visit(path) {
+    if (!existsSync(path)) return;
+    if (statSync(path).isDirectory()) {
+      for (const child of readdirSync(path)) visit(join(path, child));
+    } else values[relative(root, path)] = createHash("sha256").update(readFileSync(path)).digest("hex");
+  }
+  for (const name of ["agent-state", ".agents/ACE"]) visit(join(root, name));
+  return values;
+}
+
+const protectedBefore = stateHashes(source);
+// Include current edits and new tests, but never copy a live store or host state.
+const files = testSourceFiles(source);
+for (const name of new Set(files)) {
+  if (/^(?:agent-state|\.agents|\.git|node_modules|dist)(?:\/|$)/.test(name)) continue;
+  const from = join(source, name);
+  if (!existsSync(from) || !statSync(from).isFile()) continue;
+  mkdirSync(dirname(join(checkout, name)), { recursive: true });
+  cpSync(from, join(checkout, name));
+}
+cpSync(join(source, "dist"), join(checkout, "dist"), { recursive: true });
+symlinkSync(findTestDependencies(source), join(checkout, "node_modules"), "dir");
+writeFileSync(join(checkout, '.ace-test-source-files.json'), JSON.stringify(files));
+
+const runId = randomUUID(); const leaseFile = join(sandbox, 'lease.json'); const sessionFile = join(sandbox, 'session.json');
+const sentinel = join(checkout, '.ace-test-protected-sentinel'); writeFileSync(sentinel, 'Protected disposable source sentinel\n');
+const sentinelBefore = readFileSync(sentinel);
+const nativeSentinel = join(sandbox, 'outside-fixture-sentinel');
+writeFileSync(nativeSentinel, 'Protected disposable non-source sentinel\n');
+const nativeSentinelBefore = readFileSync(nativeSentinel);
+const lease = status => writeFileSync(leaseFile, JSON.stringify({ version: 1, run_id: runId, status }));
+lease('active');
+writeFileSync(sessionFile, JSON.stringify({ run_id: runId, lease_file: leaseFile, fixtures_root: realpathSync(fixtures), registry_root: registry, sentinel }));
+const preload = join(checkout, 'scripts', 'dev', 'test-preload.mjs');
+// On macOS, a verified Seatbelt profile also covers shell/native descendants.
+// Availability varies under an outer sandbox, so never infer enforcement from
+// the executable merely existing. The self-test touches a disposable sentinel.
+let osBoundary = { mode: process.platform === 'darwin' ? 'unavailable' : 'not_supported' };
+let command = process.execPath; let prefix = [];
+const processRequests = join(sandbox, 'process-info-requests'); const processResponses = join(sandbox, 'process-info-responses');
+mkdirSync(processRequests); mkdirSync(processResponses);
+if (process.platform === 'darwin' && existsSync('/usr/bin/sandbox-exec')) {
+  const writable = [fixtures, registry, processRequests, processResponses].map(path => `(subpath ${JSON.stringify(realpathSync.native(path))})`).join(' ');
+  const seatbelt = `(version 1) (allow default) (deny file-write*) (allow file-write* ${writable} (literal "/dev/null") (literal "/dev/tty") (literal "/dev/stdout") (literal "/dev/stderr") (subpath "/dev/fd"))`;
+  const probePath = join(checkout, '.ace-test-os-sentinel'); const original = 'Protected native sentinel\n'; writeFileSync(probePath, original);
+  const result = spawnSync('/usr/bin/sandbox-exec', ['-p', seatbelt, '/bin/sh', '-c', 'printf mutation > "$1"', 'isolation-probe', probePath], { encoding: 'utf8' });
+  const preserved = readFileSync(probePath, 'utf8') === original;
+  if (!preserved) { lease('quarantined'); throw new Error('OS isolation self-test failed: a disposable protected sentinel was writable'); }
+  if (result.status === 1 && /Operation not permitted|Permission denied/.test(result.stderr)) {
+    osBoundary = { mode: 'seatbelt', self_test: 'native write refused' }; command = '/usr/bin/sandbox-exec'; prefix = ['-p', seatbelt, process.execPath];
+  } else osBoundary = { mode: 'unavailable', reason: (result.stderr || result.error?.message || `probe exit ${result.status}`).trim() };
+}
+if (process.env.ACE_TEST_REQUIRE_OS_BOUNDARY === '1' && osBoundary.mode !== 'seatbelt') { lease('quarantined'); throw new Error(`Required OS test boundary unavailable: ${JSON.stringify(osBoundary)}`); }
+// Seatbelt can restrict Darwin process inspection even though file reads work.
+// Broker only fixed, read-only ps fields through the unsandboxed owning runner.
+// Responses are fresh OS output, never inferred from a heartbeat or PID alone.
+const session = JSON.parse(readFileSync(sessionFile, 'utf8'));
+session.process_info_broker = osBoundary.mode === 'seatbelt';
+session.process_info_requests = processRequests; session.process_info_responses = processResponses;
+writeFileSync(sessionFile, JSON.stringify(session));
+const brokerStats = { requests: 0, failed: 0 };
+function serveProcessInfo() {
+  for (const name of readdirSync(processRequests).slice(0, 64)) {
+    if (!/^[a-f0-9-]+\.json$/.test(name)) continue;
+    let request;
+    try { request = JSON.parse(readFileSync(join(processRequests, name), 'utf8')); } catch { continue; }
+    if (request.run_id !== runId || !Number.isSafeInteger(request.pid) || request.pid <= 1 || !['start', 'stat', 'both'].includes(request.fields)) { unlinkSync(join(processRequests, name)); continue; }
+    const psArgs = ['-p', String(request.pid), ...(request.fields === 'stat' ? [] : ['-o', 'lstart=']), ...(request.fields === 'start' ? [] : ['-o', 'stat='])];
+    let response;
+    try { response = { ok: true, stdout: execFileSync('ps', psArgs, { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'pipe'] }) }; }
+    catch (error) { brokerStats.failed++; response = { ok: false, stdout: String(error.stdout ?? ''), stderr: String(error.stderr ?? ''), status: error.status ?? null, code: error.code ?? 'PROCESS_INFO_UNAVAILABLE' }; }
+    brokerStats.requests++;
+    const path = join(processResponses, name); writeFileSync(`${path}.tmp`, JSON.stringify({ ...response, pid: request.pid, run_id: runId, checked_at: Date.now() })); renameSync(`${path}.tmp`, path); unlinkSync(join(processRequests, name));
+  }
+}
+const broker = session.process_info_broker ? setInterval(serveProcessInfo, 5) : undefined;
+console.error(`[test isolation] OS source boundary: ${osBoundary.mode}`);
+const requested = process.argv.slice(2);
+const probe = requested[0] === '--probe'; if (probe) requested.shift();
+if (probe && !requested.length) throw new Error('Usage: run-tests-isolated.mjs --probe <probe.mjs> [arguments]');
+const args = requested.length ? requested : ["test/*.test.mjs", "test/**/*.test.mjs"];
+console.error(`[test isolation] Disposable checkout: ${checkout}`);
+const childEnv = { ...process.env, ACE_WORKSPACE_ROOT: fixtures, INIT_CWD: checkout, PWD: checkout, ACE_TEST_SESSION_FILE: sessionFile,
+  ACE_TEST_ISOLATION: '1', ACE_TEST_RUN_ID: runId, ACE_TEST_LEASE_FILE: leaseFile,
+  ACE_TEST_NATIVE_SENTINEL_PATH: nativeSentinel,
+  ACE_TEST_PROBE: probe ? '1' : '0',
+  NODE_OPTIONS: [process.env.NODE_OPTIONS ?? '', `--import=${pathToFileURL(preload).href}`].join(' ').trim() };
+delete childEnv.ACE_TUI_WORKSPACE_ROOT;
+delete childEnv.ACE_TEST_WORKER_ROOT;
+const child = spawn(command, [...prefix, ...(probe ? args : ["--test", ...args])], {
+  cwd: checkout,
+  env: childEnv,
+  stdio: "inherit",
+});
+const outcome = await new Promise((resolveExit, reject) => {
+  child.on("error", reject);
+  child.on("close", (code, signal) => resolveExit({ code, signal }));
+});
+function ownedProcesses() {
+  return readdirSync(registry).flatMap(name => {
+    try {
+      const record = JSON.parse(readFileSync(join(registry, name), 'utf8'));
+      try { process.kill(record.pid, 0); } catch (error) { if (error.code === 'ESRCH') return []; return [{ ...record, state: 'uncertain' }]; }
+      try {
+        const actual = execFileSync('ps', ['-p', String(record.pid), '-o', 'lstart=', '-o', 'stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        const match = actual.match(/^(.*?)\s+([A-Za-z+<>NsLslWEIXZ-]+)$/);
+        if (match?.[2].includes('Z')) return [];
+        if (record.identity && match && match[1].replace(/\s+/g, ' ') !== record.identity) return [];
+        return [{ ...record, state: record.identity && match ? 'alive' : 'uncertain' }];
+      } catch { return [{ ...record, state: 'uncertain' }]; }
+    } catch { return []; }
+  });
+}
+const configuredWait = Number(process.env.ACE_TEST_CHILD_WAIT_MS ?? 15000);
+const waitUntil = Date.now() + (Number.isFinite(configuredWait) && configuredWait >= 0 ? configuredWait : 15000);
+let retained = ownedProcesses();
+while (retained.length && Date.now() < waitUntil) {
+  await new Promise(resolveWait => setTimeout(resolveWait, 100)); retained = ownedProcesses();
+}
+// Closing the allocation is an instruction to test writers, not a total-runtime
+// kill of healthy work. Unfinished/uncertain descendants quarantine this run.
+lease(retained.length ? 'quarantined' : 'closed');
+if (broker) clearInterval(broker);
+// close fires after the test runner and its workers have finished, not when an
+// alphabetically-last test happens to run. The copy's source root is a sentinel:
+// fixtures must use their disposable workspace, including in spawned children.
+const unexpected = Object.keys(stateHashes(checkout));
+const protectedAfter = stateHashes(source);
+const changed = [...new Set([...Object.keys(protectedBefore), ...Object.keys(protectedAfter)])]
+  .filter((name) => protectedBefore[name] !== protectedAfter[name]);
+const sentinelChanged = !readFileSync(sentinel).equals(sentinelBefore);
+const nativeSentinelChanged = !existsSync(nativeSentinel) || !readFileSync(nativeSentinel).equals(nativeSentinelBefore);
+const quarantined = Boolean(retained.length || unexpected.length || changed.length || sentinelChanged || nativeSentinelChanged);
+if (quarantined) lease('quarantined');
+writeFileSync(join(sandbox, "isolation.json"), JSON.stringify({ checkout, outcome, unexpected, protected_source_changes: changed, sentinel_changed: sentinelChanged, native_sentinel_changed: nativeSentinelChanged, retained_owned_node_processes: retained, allocation: quarantined ? 'quarantined' : 'closed', os_boundary: osBoundary, process_info_broker: { enabled: session.process_info_broker, ...brokerStats } }, null, 2));
+if (quarantined) {
+  console.error(`[test isolation] Unauthorized fixture writes: ${unexpected.join(", ") || "none"}; source changes: ${changed.join(", ") || "none"}`);
+  if (nativeSentinelChanged) console.error('[test isolation] Native write outside allocated fixtures changed a disposable sentinel.');
+  if (retained.length) console.error(`[test isolation] Allocation quarantined; ${retained.length} owned Node descendants remain alive or uncertain. Lease closed; no claim of finished child work.`);
+  process.exitCode = 1;
+} else {
+  console.error("[test isolation] No source-state changes or fallback writes into the disposable source root.");
+  process.exitCode = outcome.code ?? 1;
+}

package/scripts/dev/run_hermes_crispr_live.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import './test-isolation-guard.mjs';
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";

package/scripts/dev/test-isolation-guard.mjs

@@ -0,0 +1,20 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+
+const denied = detail => { throw new Error(`ACE test isolation required: ${detail}. Use node scripts/dev/run-tests-isolated.mjs.`); };
+export function assertTestIsolation() {
+  if (process.env.ACE_TEST_ISOLATION !== '1' || !globalThis[Symbol.for('ace.test.preload')]) denied('the isolation preloader must run before test imports');
+  let roots, lease;
+  try {
+    roots = JSON.parse(process.env.ACE_TEST_ALLOWED_ROOTS ?? 'null');
+    lease = JSON.parse(readFileSync(process.env.ACE_TEST_LEASE_FILE, 'utf8'));
+  } catch { denied('missing fixture allocation or lease'); }
+  if (!Array.isArray(roots) || !roots.length || roots.some(root => typeof root !== 'string' || !isAbsolute(root))) denied('invalid fixture roots');
+  if (lease.status !== 'active' || lease.run_id !== process.env.ACE_TEST_RUN_ID) denied('the fixture lease is no longer active');
+  let workspace;
+  try { workspace = realpathSync.native(process.env.ACE_TEST_WORKER_ROOT); } catch { denied('missing worker allocation'); }
+  if (!roots.some(root => {
+    try { const base = realpathSync.native(root); const path = relative(base, workspace); return statSync(base).isDirectory() && path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path); } catch { return false; }
+  })) denied('worker root is outside the fixture allocation');
+}
+assertTestIsolation();

package/scripts/dev/test-preload.mjs

@@ -0,0 +1,153 @@
+// Test-only Node boundary. It is not an OS sandbox for arbitrary native code.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import cp from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+
+const raw = Object.fromEntries(Object.entries(fs).filter(([, value]) => typeof value === 'function').map(([key, value]) => [key, value.bind(fs)]));
+const rawExecFileSync = cp.execFileSync.bind(cp);
+const rawRealpathNative = fs.realpathSync.native.bind(fs);
+const sessionFile = process.env.ACE_TEST_SESSION_FILE;
+if (!sessionFile) throw new Error('ACE test isolation required: missing session file');
+const session = JSON.parse(raw.readFileSync(sessionFile, 'utf8'));
+const lease = () => JSON.parse(raw.readFileSync(session.lease_file, 'utf8'));
+if (lease().status !== 'active' || lease().run_id !== session.run_id) throw new Error('ACE test isolation required: inactive session');
+if ((process.env.NODE_TEST_CONTEXT || process.env.ACE_TEST_PROBE === '1') && !process.env.ACE_TEST_WORKER_ROOT) {
+  const allocation = raw.mkdtempSync(join(session.fixtures_root, 'worker-'));
+  const workspace = join(allocation, 'workspace'); const temporary = join(allocation, 'tmp');
+  raw.mkdirSync(workspace); raw.mkdirSync(temporary);
+  process.env.ACE_TEST_WORKER_ROOT = workspace;
+  process.env.ACE_WORKSPACE_ROOT = workspace;
+  process.env.ACE_TEST_ALLOWED_ROOTS = JSON.stringify([allocation]);
+  process.env.TMPDIR = temporary; process.env.TMP = temporary; process.env.TEMP = temporary;
+}
+process.env.ACE_TEST_ISOLATION = '1';
+process.env.ACE_TEST_RUN_ID = session.run_id;
+process.env.ACE_TEST_LEASE_FILE = session.lease_file;
+process.env.ACE_TEST_SENTINEL_PATH = session.sentinel;
+
+function processFields(args) {
+  if (!Array.isArray(args) || args[0] !== '-p' || !/^\d+$/.test(args[1] ?? '')) return undefined;
+  const rest = args.slice(2).join(' ');
+  return rest === '-o lstart=' ? 'start' : rest === '-o stat=' ? 'stat' : rest === '-o lstart= -o stat=' ? 'both' : undefined;
+}
+function inspectProcess(args, opts = {}) {
+  const fields = processFields(args);
+  if (!session.process_info_broker || !fields) return rawExecFileSync('ps', args, opts);
+  const id = randomUUID(); const name = `${id}.json`; const request = join(session.process_info_requests, name); const response = join(session.process_info_responses, name);
+  raw.writeFileSync(`${request}.tmp`, JSON.stringify({ run_id: session.run_id, pid: Number(args[1]), fields })); raw.renameSync(`${request}.tmp`, request);
+  const end = Date.now() + (Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : 10000);
+  const wait = new Int32Array(new SharedArrayBuffer(4));
+  while (Date.now() < end) {
+    if (raw.existsSync(response)) {
+      const result = JSON.parse(raw.readFileSync(response, 'utf8')); raw.unlinkSync(response);
+      if (result.run_id !== session.run_id || result.pid !== Number(args[1])) throw new Error('Invalid owned process-info response');
+      if (!result.ok) throw Object.assign(new Error(result.stderr || 'OS process information unavailable'), { code: result.code, status: result.status, stdout: result.stdout, stderr: result.stderr });
+      return opts.encoding && opts.encoding !== 'buffer' ? result.stdout : Buffer.from(result.stdout);
+    }
+    Atomics.wait(wait, 0, 0, 5);
+  }
+  throw Object.assign(new Error('Owned process-info request timed out'), { code: 'ETIMEDOUT' });
+}
+
+// Every Node descendant inherits this import, including detached verification.
+const registration = join(session.registry_root, `${process.pid}.json`);
+let identity;
+try { identity = inspectProcess(['-p', String(process.pid), '-o', 'lstart='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().replace(/\s+/g, ' '); } catch { identity = null; }
+raw.writeFileSync(registration, JSON.stringify({ pid: process.pid, parent: process.ppid, identity, registered_at: Date.now() }));
+process.once('exit', () => { try { raw.unlinkSync(registration); } catch {} });
+
+if (process.env.ACE_TEST_WORKER_ROOT) {
+  const { captureTestWriteBoundary, currentTestWriteAnchors } = await import(new URL('../../dist/store/test-write-boundary.js', import.meta.url));
+  const check = path => {
+    if (typeof path === 'number') {
+      if (path === 1 || path === 2) return () => {};
+      const pinned = descriptors.get(path); if (!pinned) throw new Error('ace_test_write_boundary: untracked file descriptor'); pinned(); return pinned;
+    }
+    const pin = captureTestWriteBoundary(path instanceof URL ? fileURLToPath(path) : Buffer.isBuffer(path) ? path.toString() : path); pin(); return pin;
+  };
+  const descriptors = new Map();
+  const paths = { appendFile: [0], writeFile: [0], mkdir: [0], mkdtemp: [0], rm: [0], rmdir: [0], unlink: [0], rename: [0, 1], copyFile: [1], cp: [1], link: [0, 1], symlink: [1], chmod: [0], chown: [0], lchown: [0], lchmod: [0], truncate: [0], utimes: [0], lutimes: [0], createWriteStream: [0] };
+  for (const [name, indices] of Object.entries(paths)) {
+    for (const method of [name, `${name}Sync`]) if (typeof fs[method] === 'function') {
+      const original = fs[method].bind(fs);
+      fs[method] = (...args) => { indices.forEach(index => check(args[index])); return original(...args); };
+    }
+    if (typeof fsp[name] === 'function') {
+      const original = fsp[name].bind(fsp);
+      fsp[name] = async (...args) => { indices.forEach(index => check(args[index])); return original(...args); };
+    }
+  }
+  const writable = flags => typeof flags === 'number' ? Boolean(flags & (fs.constants.O_WRONLY | fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_APPEND)) : /[wa+]/.test(flags ?? 'r');
+  const openSync = fs.openSync.bind(fs);
+  fs.openSync = (path, flags, ...rest) => { const pin = writable(flags) ? check(path) : undefined; const fd = openSync(path, flags, ...rest); if (pin) descriptors.set(fd, pin); return fd; };
+  const open = fs.open.bind(fs);
+  fs.open = (path, flags, ...rest) => {
+    const pin = writable(flags) ? check(path) : undefined; const callback = rest.pop();
+    return open(path, flags, ...rest, (error, fd) => { if (!error && pin) descriptors.set(fd, pin); callback(error, fd); });
+  };
+  const promiseOpen = fsp.open.bind(fsp);
+  fsp.open = async (path, flags, ...rest) => {
+    const pin = writable(flags) ? check(path) : undefined; const handle = await promiseOpen(path, flags, ...rest);
+    if (pin) {
+      descriptors.set(handle.fd, pin);
+      for (const key of ['write', 'writev', 'writeFile', 'appendFile', 'truncate', 'chmod', 'chown', 'utimes', 'createWriteStream']) if (typeof handle[key] === 'function') {
+        const operation = handle[key].bind(handle); handle[key] = (...args) => { pin(); return operation(...args); };
+      }
+    }
+    return handle;
+  };
+  for (const method of ['write', 'writeSync', 'writev', 'writevSync', 'ftruncate', 'ftruncateSync', 'fchmod', 'fchmodSync', 'fchown', 'fchownSync', 'futimes', 'futimesSync']) if (typeof fs[method] === 'function') {
+    const operation = fs[method].bind(fs); fs[method] = (fd, ...args) => { check(fd); return operation(fd, ...args); };
+  }
+  const inside = (path, base) => { const tail = relative(base, path); return tail !== '..' && !tail.startsWith(`..${sep}`) && !isAbsolute(tail); };
+  const inherited = Object.fromEntries(['ACE_TEST_ISOLATION', 'ACE_TEST_SESSION_FILE', 'ACE_TEST_RUN_ID', 'ACE_TEST_LEASE_FILE', 'ACE_TEST_ALLOWED_ROOTS', 'ACE_TEST_WORKER_ROOT', 'ACE_TEST_SENTINEL_PATH', 'NODE_OPTIONS'].map(key => [key, process.env[key]]));
+  function options(given = {}) {
+    // An explicit environment may intentionally omit credentials. Preserve that
+    // boundary and reattach only the isolation identity below.
+    const env = { ...(given.env ?? process.env) };
+    let requested;
+    try { requested = JSON.parse(env.ACE_TEST_ALLOWED_ROOTS); } catch {}
+    const parentRoots = JSON.parse(inherited.ACE_TEST_ALLOWED_ROOTS);
+    const narrow = Array.isArray(requested) && requested.length && requested.every(path => typeof path === 'string' && isAbsolute(path) && parentRoots.some(base => inside(rawRealpathNative(path), rawRealpathNative(base))));
+    const anchors = [...currentTestWriteAnchors()];
+    const workspace = env.ACE_WORKSPACE_ROOT;
+    if (workspace && raw.existsSync(workspace)) { const path = rawRealpathNative(workspace); const st = raw.statSync(path, { bigint: true }); anchors.push({ path, dev: String(st.dev), ino: String(st.ino) }); }
+    Object.assign(env, inherited);
+    if (narrow) env.ACE_TEST_ALLOWED_ROOTS = JSON.stringify(requested);
+    env.ACE_TEST_WRITE_ANCHORS = JSON.stringify(anchors);
+    return { ...given, env };
+  }
+  function registerOwned(child) {
+    if (!child?.pid) return child;
+    const file = join(session.registry_root, `${child.pid}.json`); let childIdentity;
+    try { childIdentity = inspectProcess(['-p', String(child.pid), '-o', 'lstart='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().replace(/\s+/g, ' '); } catch { childIdentity = null; }
+    raw.writeFileSync(file, JSON.stringify({ pid: child.pid, parent: process.pid, identity: childIdentity, registered_at: Date.now() }));
+    child.once('exit', () => { try { raw.unlinkSync(file); } catch {} }); return child;
+  }
+  for (const name of ['spawn', 'spawnSync', 'execFile', 'execFileSync', 'fork']) {
+    const original = cp[name].bind(cp);
+    cp[name] = (command, args, opts, callback) => {
+      if (!Array.isArray(args)) { callback = opts; opts = args; args = []; }
+      if (typeof opts === 'function') { callback = opts; opts = {}; }
+      if (name === 'execFileSync' && (command === 'ps' || command === '/bin/ps') && session.process_info_broker && processFields(args)) return inspectProcess(args, opts);
+      const child = callback ? original(command, args, options(opts), callback) : original(command, args, options(opts));
+      return name.endsWith('Sync') ? child : registerOwned(child);
+    };
+  }
+  for (const name of ['exec', 'execSync']) {
+    const original = cp[name].bind(cp);
+    cp[name] = (command, opts, callback) => { if (typeof opts === 'function') { callback = opts; opts = {}; } const child = callback ? original(command, options(opts), callback) : original(command, options(opts)); return name.endsWith('Sync') ? child : registerOwned(child); };
+  }
+  for (const name of ['exec', 'execFile']) cp[name][promisify.custom] = (...args) => {
+    let child;
+    const result = new Promise((resolvePromise, reject) => { child = cp[name](...args, (error, stdout, stderr) => error ? reject(Object.assign(error, { stdout, stderr })) : resolvePromise({ stdout, stderr })); });
+    result.child = child; return result;
+  };
+  syncBuiltinESMExports();
+  globalThis[Symbol.for('ace.test.preload')] = true;
+}

package/scripts/dev/test-source-inventory.mjs

@@ -0,0 +1,31 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+const safe = name => typeof name === 'string' && name && !isAbsolute(name) && !name.split(/[\\/]/).includes('..') && !/^(?:agent-state|\.agents|\.git|node_modules)(?:[\\/]|$)/.test(name);
+
+/** An installed package has no Git checkout. Inventory only its declared files. */
+export function testSourceFiles(source) {
+  const manifest = join(source, '.ace-test-source-files.json');
+  if (existsSync(manifest)) return JSON.parse(readFileSync(manifest, 'utf8')).filter(safe);
+  if (existsSync(join(source, '.git'))) return execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: source, encoding: 'utf8' }).split('\0').filter(safe);
+  const pkg = JSON.parse(readFileSync(join(source, 'package.json'), 'utf8'));
+  const roots = ['package.json', 'package-lock.json', 'README.md', 'CHANGELOG.md', 'LICENSE', ...(pkg.files ?? [])].map(name => typeof name === 'string' ? name.split(/[*?[]/, 1)[0].replace(/[\\/]$/, '') : '').filter(safe);
+  const files = new Set();
+  function visit(name) {
+    if (!safe(name) || !existsSync(join(source, name))) return;
+    const stat = lstatSync(join(source, name));
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) for (const child of readdirSync(join(source, name))) visit(join(name, child));
+    else if (stat.isFile()) files.add(name);
+  }
+  roots.forEach(visit); return [...files].sort();
+}
+
+export function findTestDependencies(source) {
+  let cursor = resolve(source);
+  for (;;) {
+    const candidate = join(cursor, 'node_modules'); if (existsSync(candidate)) return candidate;
+    const parent = dirname(cursor); if (parent === cursor) throw new Error('Installed ACE dependencies are unavailable; use the package installation containing node_modules'); cursor = parent;
+  }
+}

package/docs/development.md

@@ -1,46 +0,0 @@
-# Development
-
-> Companion to the [README](../README.md).
-
-```bash
-cd ace-mcp-server
-npm install
-npm run build
-npm test
-npm run start
-```
-
-Run the Hermes live driver from a source checkout. The script is included in the npm package as of 2.4.6, but it imports the checkout/package `dist/` tree and is a diagnostic, not a supported production command. It exits nonzero if setup, protocol, or artifact checks fail.
-
-```bash
-npm run build
-# with a local llama.cpp or Ollama runtime running:
-ACE_WORKSPACE_ROOT=$PWD \
-  ACE_HERMES_ROOT=/path/to/hermes-agent \
-  HERMES_PYTHON=/path/to/hermes-python \
-  ACE_LIVE_PROVIDERS=llama.cpp \
-  ACE_LIVE_LLAMA_CPP_BASE_URL=http://127.0.0.1:8080/v1 \
-  ACE_LIVE_LLAMA_CPP_MODEL=gemma-3-4b-it \
-  ACE_LIVE_HERMES_MAX_TURNS=3 \
-  node scripts/dev/run_hermes_crispr_live.mjs
-```
-
-`ACE_LIVE_OUTPUT_ONLY=1` deliberately bypasses tool writing and is only for inspecting raw model output; it cannot satisfy the driver’s evidence-gated job check.
-
-## Key source files
-
-| File | Role |
-|---|---|
-| `src/index.ts` | Package entry point |
-| `src/cli.ts` | CLI command dispatch |
-| `src/server.ts` | MCP server setup and stdio transport |
-| `src/tools.ts` | Tool registration hub (delegates to domain modules) |
-| `src/hermes/session-manager.ts` | `HermesSubprocessExecutor` — Hermes subprocess lifecycle |
-| `src/hermes/bridge-protocol.ts` | Frame decoder for the Hermes bridge protocol |
-| `src/model-bridge.ts` | Model bridge interface and process orchestration |
-| `src/goal-engine.ts` | Goal engine — self-paced, evidence-gated objective loop |
-| `src/job-worker.ts` | In-process job worker for the scheduler execution loop |
-| `src/public-surface.ts` | Public surface audit and schema-bound entry map |
-| `src/store/ace-packed-store.ts` | ACEPACK binary store read/write |
-| `src/local-model-policy.ts` | Operator allow/block policy for local models |
-| `scripts/hermes_bridge_worker.py` | Packaged Python worker for the Hermes bridge |