arkgate 4.8.23 → 4.8.25

package/bin/lib/invariant-probe-runner.mjs

@@ -0,0 +1,268 @@
+/**
+ * Runner adapters for the invariant probe — Tooling (ADR 0039).
+ *
+ * Detects the project's own runner (vitest, jest, node:test) from the nearest
+ * package.json, resolves its binary from the project, and runs it with
+ * `process.execPath`, an argv array and no shell. A timeout kills the whole
+ * process group. The environment is an allowlist: no tokens, no cloud
+ * credentials, proxies pointed at a dead port, HOME and TMPDIR inside the
+ * probe workspace. Best effort — not a sandbox.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const PROBE_RUNNERS = ['vitest', 'jest', 'node'];
+const TS_TEST = /\.[cm]?tsx?$/;
+const MAX_CAPTURE = 4 * 1024 * 1024;
+const PROBE_TIMEOUT_FLOOR_MS = 10_000;
+export const PROBE_TIMEOUT_CEILING_MS = 120_000;
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Nearest directory at or above `fromDir` (inside `root`) holding a package.json. */
+function nearestPackageRoot(root, fromDir) {
+  let dir = path.resolve(fromDir);
+  const top = path.resolve(root);
+  while (dir.startsWith(top)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    if (dir === top) break;
+    dir = path.dirname(dir);
+  }
+  return top;
+}
+
+function hasConfig(pkgRoot, stem) {
+  try {
+    return fs.readdirSync(pkgRoot).some((name) => name.startsWith(`${stem}.config.`));
+  } catch {
+    return false;
+  }
+}
+
+/** Runner ids the package declares, from `scripts.test` first, then dependency + config. */
+function runnerEvidence(pkgRoot) {
+  const pkg = readJson(path.join(pkgRoot, 'package.json')) ?? {};
+  const script = typeof pkg.scripts?.test === 'string' ? pkg.scripts.test : '';
+  const fromScript = [];
+  if (/\bvitest\b/.test(script)) fromScript.push('vitest');
+  if (/\bjest\b/.test(script)) fromScript.push('jest');
+  if (/\bnode\b[^&|;]*\s--test\b/.test(script)) fromScript.push('node');
+  if (fromScript.length > 0) return fromScript;
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  const fromDeps = [];
+  if (deps.vitest && hasConfig(pkgRoot, 'vitest')) fromDeps.push('vitest');
+  if (deps.jest && hasConfig(pkgRoot, 'jest')) fromDeps.push('jest');
+  return fromDeps;
+}
+
+function resolveBin(pkgRoot, id) {
+  if (id === 'node') return { bin: null, version: process.versions.node };
+  try {
+    const require = createRequire(path.join(pkgRoot, 'package.json'));
+    const manifestPath = require.resolve(`${id}/package.json`);
+    const manifest = readJson(manifestPath) ?? {};
+    const binField = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[id];
+    if (typeof binField !== 'string') return null;
+    return { bin: path.resolve(path.dirname(manifestPath), binField), version: manifest.version ?? null };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick the runner for a set of covering tests.
+ * @param {{ root: string, tests: string[], override?: string }} input tests are root-relative
+ */
+export function detectRunner({ root, tests, override }) {
+  const first = tests[0];
+  const pkgRoot = nearestPackageRoot(root, path.dirname(path.join(root, first ?? '.')));
+  const evidence = runnerEvidence(pkgRoot);
+  let id;
+  if (evidence.length === 1) {
+    id = evidence[0];
+    if (override && override !== id) {
+      return {
+        ok: false,
+        reasonCode: 'PROBE_RUNNER_UNKNOWN',
+        reason: `--runner ${override} does not match the runner this package declares (${id}). --runner only settles an unclear detection.`,
+      };
+    }
+  } else if (override && PROBE_RUNNERS.includes(override)) {
+    id = override;
+  } else {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNKNOWN',
+      reason:
+        evidence.length > 1
+          ? `The package declares more than one test runner (${evidence.join(', ')}). Next: pass --runner ${evidence.join('|')}.`
+          : 'No test runner was found in package.json (scripts.test, or a vitest / jest dependency with its config file). Next: pass --runner vitest|jest|node.',
+    };
+  }
+  if (id === 'node' && tests.some((test) => TS_TEST.test(test))) {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNSUPPORTED',
+      reason: 'node:test cannot run TypeScript test files without a loader, so the probe does not run them.',
+    };
+  }
+  const resolved = resolveBin(pkgRoot, id);
+  if (!resolved) {
+    return {
+      ok: false,
+      reasonCode: 'PROBE_RUNNER_UNKNOWN',
+      reason: `${id} is not installed in ${path.relative(root, pkgRoot) || '.'}, so the probe cannot run it.`,
+    };
+  }
+  return { ok: true, id, bin: resolved.bin, version: resolved.version, pkgRoot };
+}
+
+/** Allowlisted environment for the runner. Nothing else from the parent passes. */
+export function buildProbeEnv({ home, tmp, parentEnv = process.env }) {
+  const env = {
+    PATH: parentEnv.PATH ?? parentEnv.Path ?? '',
+    LANG: parentEnv.LANG ?? 'C.UTF-8',
+    TZ: 'UTC',
+    CI: '1',
+    NODE_ENV: 'test',
+    FORCE_COLOR: '0',
+    NO_COLOR: '1',
+    HOME: home,
+    USERPROFILE: home,
+    TMPDIR: tmp,
+    TMP: tmp,
+    TEMP: tmp,
+    HTTP_PROXY: 'http://127.0.0.1:9',
+    HTTPS_PROXY: 'http://127.0.0.1:9',
+    http_proxy: 'http://127.0.0.1:9',
+    https_proxy: 'http://127.0.0.1:9',
+    NO_PROXY: '',
+    no_proxy: '',
+    npm_config_offline: 'true',
+  };
+  if (process.platform === 'win32' && parentEnv.SystemRoot) env.SystemRoot = parentEnv.SystemRoot;
+  return env;
+}
+
+/** argv for one run. `files` are relative to the package root in the copy. */
+export function runnerArgv(runner, files, { outputFile, cacheDir }) {
+  switch (runner.id) {
+    case 'vitest':
+      return [runner.bin, 'run', '--no-coverage', '--reporter=json', `--outputFile=${outputFile}`, ...files];
+    case 'jest':
+      return [
+        runner.bin,
+        '--ci',
+        '--json',
+        `--outputFile=${outputFile}`,
+        '--coverage=false',
+        '--watchman=false',
+        `--cacheDirectory=${cacheDir}`,
+        '--runTestsByPath',
+        ...files,
+      ];
+    case 'node':
+      return ['--test', '--test-reporter=tap', ...files];
+    default:
+      throw new Error(`unknown runner ${runner.id}`);
+  }
+}
+
+/** clamp(3 × baseline + 5 s, 10 s, 120 s). */
+export function probeTimeoutMs(baselineMs) {
+  const wanted = 3 * Math.max(0, baselineMs) + 5000;
+  return Math.min(PROBE_TIMEOUT_CEILING_MS, Math.max(PROBE_TIMEOUT_FLOOR_MS, wanted));
+}
+
+function killGroup(child) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    } else {
+      process.kill(-child.pid, 'SIGKILL');
+    }
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** Failure counts from the runner's own report. Null: no report to read. */
+function readFailures(runner, outputFile, stdout) {
+  if (runner.id === 'node') {
+    const fail = /^# fail (\d+)/m.exec(stdout);
+    const tests = /^# tests (\d+)/m.exec(stdout);
+    if (!fail) return null;
+    return { failed: Number(fail[1]), total: tests ? Number(tests[1]) : null };
+  }
+  const report = readJson(outputFile);
+  if (!report || typeof report !== 'object') return null;
+  const failed = (Number(report.numFailedTests) || 0) + (Number(report.numFailedTestSuites) || 0);
+  return { failed, total: Number(report.numTotalTests) || 0 };
+}
+
+/**
+ * Run the covering tests once.
+ * @returns {Promise<{ outcome: 'passed' | 'failed' | 'timeout' | 'runtime-error', durationMs: number, detail?: string }>}
+ */
+export function runCoveringTests({ runner, cwd, files, timeoutMs, env, scratch }) {
+  const outputFile = path.join(scratch, `runner-report-${process.hrtime.bigint()}.json`);
+  const argv = runnerArgv(runner, files, { outputFile, cacheDir: path.join(scratch, 'jest-cache') });
+  const started = process.hrtime.bigint();
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      env,
+      shell: false,
+      detached: process.platform !== 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    child.stdout.on('data', (chunk) => {
+      stdout = stdout.length < MAX_CAPTURE ? stdout + chunk.toString('utf8') : stdout;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = stderr.length < MAX_CAPTURE ? stderr + chunk.toString('utf8') : stderr;
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup(child);
+    }, timeoutMs);
+    let done = false;
+    const finish = (code, spawnError) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      const durationMs = Math.round(Number(process.hrtime.bigint() - started) / 1e6);
+      if (timedOut) return resolve({ outcome: 'timeout', durationMs });
+      if (spawnError) return resolve({ outcome: 'runtime-error', durationMs, detail: spawnError.message });
+      const failures = readFailures(runner, outputFile, stdout);
+      try {
+        fs.rmSync(outputFile, { force: true });
+      } catch {
+        /* scratch is removed with the workspace */
+      }
+      if (failures && failures.failed > 0) return resolve({ outcome: 'failed', durationMs });
+      if (code === 0) return resolve({ outcome: 'passed', durationMs });
+      // A non-zero exit with no reported failure is a crash, never a caught change.
+      return resolve({ outcome: 'runtime-error', durationMs, detail: stderr.slice(-2000) });
+    };
+    child.on('error', (error) => finish(null, error));
+    child.on('close', (code) => finish(code, null));
+  });
+}

package/bin/lib/invariant-probe-sites.mjs

@@ -0,0 +1,174 @@
+/**
+ * Where the invariant probe may change code — Tooling (ADR 0039).
+ *
+ * Parses the symbol file with the TypeScript the CLI already loaded, locates
+ * the declaration `coverage.symbol` names (the same shapes coverage accepts:
+ * function, `const x = () => {}` / function expression / literal, class or
+ * object-literal method, `Class.member`), and emits the sites inside that
+ * declaration only. Which sites become mutants is decided in Domain
+ * (`planMutants` in invariant-probe.mjs).
+ */
+
+const COMPARISON_TOKENS = new Set(['<', '>', '<=', '>=', '===', '!==', '==', '!=']);
+const DECLARATION_ONLY = new Map([
+  ['ClassDeclaration', 'class'],
+  ['InterfaceDeclaration', 'interface'],
+  ['TypeAliasDeclaration', 'type'],
+  ['EnumDeclaration', 'enum'],
+]);
+
+function nameOf(ts, node) {
+  return node.name && (ts.isIdentifier(node.name) || ts.isPrivateIdentifier?.(node.name)) ? node.name.text : null;
+}
+
+function isFunctionLike(ts, node) {
+  return Boolean(node) && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+
+/** Body shape of a function-like node: a block to insert into, or an arrow expression. */
+function bodyOf(ts, sourceFile, fn) {
+  if (!fn.body) return null;
+  if (ts.isBlock(fn.body)) return { node: fn.body, body: { kind: 'block', insertAt: fn.body.getStart(sourceFile) + 1 } };
+  return {
+    node: fn.body,
+    body: { kind: 'expression', start: fn.body.getStart(sourceFile), end: fn.body.end },
+  };
+}
+
+/** Members of a class body or object literal named `member`. */
+function memberTarget(ts, sourceFile, members, member) {
+  for (const node of members) {
+    if (nameOf(ts, node) !== member) continue;
+    if ((ts.isMethodDeclaration(node) || ts.isGetAccessorDeclaration(node)) && node.body) {
+      return { shape: 'method', ...bodyOf(ts, sourceFile, node) };
+    }
+    const init = node.initializer;
+    if ((ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node)) && isFunctionLike(ts, init)) {
+      return { shape: 'method', ...bodyOf(ts, sourceFile, init) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the declaration for `symbol` (`name` or `Container.member`).
+ * @returns {{ found: true, shape: string, node: object, body: object } | { found: false, declarationOnly?: string }}
+ */
+function locate(ts, sourceFile, symbol) {
+  const parts = String(symbol).split('.');
+  const name = parts[parts.length - 1];
+  const container = parts.length > 1 ? parts[parts.length - 2] : null;
+  let found = null;
+  let declarationOnly = null;
+  const visit = (node) => {
+    if (found) return;
+    const kindName = ts.SyntaxKind[node.kind];
+    if (container === null) {
+      if (ts.isFunctionDeclaration(node) && nameOf(ts, node) === name && node.body) {
+        found = { shape: 'function', ...bodyOf(ts, sourceFile, node) };
+        return;
+      }
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name && node.initializer) {
+        const init = node.initializer;
+        found = isFunctionLike(ts, init)
+          ? { shape: 'const', ...bodyOf(ts, sourceFile, init) }
+          : {
+              shape: 'const',
+              node: init,
+              body: { kind: 'initializer', start: init.getStart(sourceFile), end: init.end },
+            };
+        return;
+      }
+      if (DECLARATION_ONLY.has(kindName) && nameOf(ts, node) === name) {
+        declarationOnly ??= DECLARATION_ONLY.get(kindName);
+      }
+    } else {
+      if ((ts.isClassDeclaration(node) || ts.isClassExpression(node)) && nameOf(ts, node) === container) {
+        found = memberTarget(ts, sourceFile, node.members, name);
+      } else if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === container &&
+        node.initializer
+      ) {
+        const init = node.initializer;
+        if (ts.isObjectLiteralExpression(init)) found = memberTarget(ts, sourceFile, init.properties, name);
+        else if (ts.isClassExpression(init)) found = memberTarget(ts, sourceFile, init.members, name);
+      } else if (ts.isModuleDeclaration(node) && nameOf(ts, node) === container && node.body) {
+        const fn = (node.body.statements ?? []).find(
+          (statement) => ts.isFunctionDeclaration(statement) && nameOf(ts, statement) === name && statement.body
+        );
+        if (fn) found = { shape: 'function', ...bodyOf(ts, sourceFile, fn) };
+      }
+      if (found && !found.node) found = null;
+    }
+    if (!found) ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  if (found) return { found: true, ...found };
+  return { found: false, ...(declarationOnly ? { declarationOnly } : {}) };
+}
+
+function thenExits(ts, statement) {
+  if (!statement) return false;
+  if (ts.isThrowStatement(statement) || ts.isReturnStatement(statement)) return true;
+  return ts.isBlock(statement) && statement.statements.some((s) => ts.isThrowStatement(s) || ts.isReturnStatement(s));
+}
+
+function siteAt(sourceFile, text, kind, start, end) {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(start);
+  return { kind, start, end, line: line + 1, column: character + 1, text: text.slice(start, end) };
+}
+
+/**
+ * Sites and body shape for the probe.
+ * @param {object} ts the loaded TypeScript module
+ * @param {string} fileName project-relative path (decides JS vs TS parsing)
+ * @param {string} text file contents
+ * @param {string} symbol `coverage.symbol`
+ * @returns {{ ok: true, shape: string, body: object, line: number, sites: object[] }
+ *          | { ok: false, reason: 'symbol-not-found' | 'declaration-only', shape?: string }}
+ */
+export function findProbeSites(ts, fileName, text, symbol) {
+  const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true);
+  const located = locate(ts, sourceFile, symbol);
+  if (!located.found) {
+    return located.declarationOnly
+      ? { ok: false, reason: 'declaration-only', shape: located.declarationOnly }
+      : { ok: false, reason: 'symbol-not-found' };
+  }
+  const sites = [];
+  const walk = (node) => {
+    if (ts.isIfStatement(node) && thenExits(ts, node.thenStatement)) {
+      sites.push(siteAt(sourceFile, text, 'guard', node.expression.getStart(sourceFile), node.expression.end));
+    } else if (ts.isThrowStatement(node)) {
+      sites.push(siteAt(sourceFile, text, 'throw', node.getStart(sourceFile), node.end));
+    } else if (ts.isBinaryExpression(node) && COMPARISON_TOKENS.has(node.operatorToken.getText(sourceFile))) {
+      sites.push(
+        siteAt(sourceFile, text, 'comparison', node.operatorToken.getStart(sourceFile), node.operatorToken.end)
+      );
+    } else if (ts.isNumericLiteral(node)) {
+      sites.push(siteAt(sourceFile, text, 'numeric', node.getStart(sourceFile), node.end));
+    } else if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) {
+      sites.push(siteAt(sourceFile, text, 'boolean', node.getStart(sourceFile), node.end));
+    }
+    ts.forEachChild(node, walk);
+  };
+  walk(located.node);
+  const { line } = sourceFile.getLineAndCharacterOfPosition(located.node.getStart(sourceFile));
+  return { ok: true, shape: located.shape, body: located.body, line: line + 1, sites };
+}
+
+/** True when `text` has no syntax errors (a mutant that does not parse is `invalid`). */
+export function parsesCleanly(ts, fileName, text) {
+  try {
+    const out = ts.transpileModule(text, {
+      fileName,
+      reportDiagnostics: true,
+      compilerOptions: { allowJs: true, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.Latest },
+    });
+    return (out.diagnostics ?? []).length === 0;
+  } catch {
+    return false;
+  }
+}

package/bin/lib/invariant-probe-workspace.mjs

@@ -0,0 +1,183 @@
+/**
+ * Temporary copy for the invariant probe — Tooling (ADR 0039).
+ *
+ * Every mutant is applied to a copy under the OS temp directory, never to the
+ * user's tree. Layout:
+ *
+ *   <tmp>/arkgate-probe-XXXXXX/
+ *     .arkgate-probe-owner   ownership marker (the stale sweep only touches these)
+ *     project/               the copy (node_modules is a real dir of links)
+ *     home/  tmp/            HOME and TMPDIR for the runner
+ *
+ * Cleanup runs in `finally` and on SIGINT / SIGTERM. The next run removes
+ * stale `arkgate-probe-*` directories older than 24 hours, but only when the
+ * owner marker is a regular file inside a real directory.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PROBE_DIR_PREFIX = 'arkgate-probe-';
+export const PROBE_OWNER_MARKER = '.arkgate-probe-owner';
+const PROBE_MAX_FILES = 20_000;
+const PROBE_MAX_BYTES = 256 * 1024 * 1024;
+const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+/** Never copied. `node_modules` is linked instead (see linkFarm). */
+const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.turbo', 'out']);
+const EXCLUDED_PATHS = new Set(['.ark/reports']);
+/** Runner caches inside node_modules: never linked, so a cache write lands in the copy. */
+const UNLINKED_MODULE_ENTRIES = new Set(['.vite', '.vitest', '.cache']);
+
+/** Walk the tree the copy would hold, without copying. */
+function planCopy(root, maxFiles, maxBytes) {
+  const entries = [];
+  let bytes = 0;
+  let files = 0;
+  const over = () => files > maxFiles || bytes > maxBytes;
+  const visit = (rel) => {
+    if (over()) return;
+    const abs = rel ? path.join(root, rel) : root;
+    let children;
+    try {
+      children = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    children.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const child of children) {
+      const childRel = rel ? `${rel}/${child.name}` : child.name;
+      if (EXCLUDED_PATHS.has(childRel)) continue;
+      if (child.isDirectory()) {
+        if (child.name === 'node_modules') {
+          entries.push({ rel: childRel, kind: 'modules' });
+          continue;
+        }
+        if (EXCLUDED_DIRS.has(child.name)) continue;
+        entries.push({ rel: childRel, kind: 'dir' });
+        visit(childRel);
+      } else if (child.isSymbolicLink()) {
+        if (child.name === 'node_modules') entries.push({ rel: childRel, kind: 'modules' });
+        else entries.push({ rel: childRel, kind: 'link' });
+      } else if (child.isFile()) {
+        files += 1;
+        try {
+          bytes += fs.statSync(path.join(root, childRel)).size;
+        } catch {
+          /* vanished mid-walk: not copied */
+        }
+        entries.push({ rel: childRel, kind: 'file' });
+      }
+      if (over()) return;
+    }
+  };
+  visit('');
+  return { entries, files, bytes };
+}
+
+/** `node_modules` in the copy: a real directory holding one link per top-level entry. */
+function linkFarm(sourceModules, targetModules) {
+  fs.mkdirSync(targetModules, { recursive: true });
+  let names = [];
+  try {
+    names = fs.readdirSync(sourceModules);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (UNLINKED_MODULE_ENTRIES.has(name)) continue;
+    let real;
+    try {
+      real = fs.realpathSync(path.join(sourceModules, name));
+    } catch {
+      continue;
+    }
+    try {
+      fs.symlinkSync(real, path.join(targetModules, name), process.platform === 'win32' ? 'junction' : undefined);
+    } catch {
+      /* a name that cannot be linked is left out; the runner reports what is missing */
+    }
+  }
+}
+
+/**
+ * Remove stale probe directories: older than 24 hours AND carrying the owner
+ * marker. Anything else under the temp root is never touched.
+ */
+export function sweepStaleProbeWorkspaces({ tmpRoot = os.tmpdir(), now = Date.now(), maxAgeMs = STALE_AFTER_MS } = {}) {
+  const removed = [];
+  let names = [];
+  try {
+    names = fs.readdirSync(tmpRoot);
+  } catch {
+    return { removed };
+  }
+  for (const name of names) {
+    if (!name.startsWith(PROBE_DIR_PREFIX)) continue;
+    const dir = path.join(tmpRoot, name);
+    try {
+      const dirStat = fs.lstatSync(dir);
+      if (!dirStat.isDirectory()) continue;
+      const markerStat = fs.lstatSync(path.join(dir, PROBE_OWNER_MARKER));
+      if (!markerStat.isFile()) continue;
+      if (now - markerStat.mtimeMs < maxAgeMs) continue;
+      fs.rmSync(dir, { recursive: true, force: true });
+      removed.push(dir);
+    } catch {
+      /* no marker, or unreadable: not ours to remove */
+    }
+  }
+  return { removed };
+}
+
+/**
+ * Copy `root` into a fresh marked workspace.
+ * @returns {{ ok: true, dir: string, project: string, home: string, tmp: string, cleanup: () => void,
+ *             files: number, bytes: number }
+ *          | { ok: false, reasonCode: 'PROBE_TREE_TOO_LARGE', files: number, bytes: number }}
+ */
+export function createProbeWorkspace(
+  root,
+  { tmpRoot = os.tmpdir(), onSignalCleanup, maxFiles = PROBE_MAX_FILES, maxBytes = PROBE_MAX_BYTES } = {}
+) {
+  const plan = planCopy(root, maxFiles, maxBytes);
+  if (plan.files > maxFiles || plan.bytes > maxBytes) {
+    return { ok: false, reasonCode: 'PROBE_TREE_TOO_LARGE', files: plan.files, bytes: plan.bytes };
+  }
+  const dir = fs.mkdtempSync(path.join(tmpRoot, PROBE_DIR_PREFIX));
+  fs.writeFileSync(
+    path.join(dir, PROBE_OWNER_MARKER),
+    `${JSON.stringify({ owner: 'arkgate-probe', pid: process.pid })}\n`
+  );
+  const project = path.join(dir, 'project');
+  const home = path.join(dir, 'home');
+  const tmp = path.join(dir, 'tmp');
+  for (const sub of [project, home, tmp]) fs.mkdirSync(sub);
+  let cleaned = false;
+  const signals = ['SIGINT', 'SIGTERM'];
+  const onSignal = (signal) => {
+    cleanup();
+    onSignalCleanup?.(signal);
+    process.kill(process.pid, signal);
+  };
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    for (const signal of signals) process.removeListener(signal, onSignal);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  for (const signal of signals) process.once(signal, onSignal);
+  try {
+    for (const entry of plan.entries) {
+      const source = path.join(root, entry.rel);
+      const target = path.join(project, entry.rel);
+      if (entry.kind === 'dir') fs.mkdirSync(target, { recursive: true });
+      else if (entry.kind === 'modules') linkFarm(source, target);
+      else if (entry.kind === 'link') fs.symlinkSync(fs.readlinkSync(source), target);
+      else fs.copyFileSync(source, target);
+    }
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  return { ok: true, dir, project, home, tmp, cleanup, files: plan.files, bytes: plan.bytes };
+}