deepdebug-local-agent 1.0.22 → 1.1.0

package/test/root-recovery.test.js

@@ -0,0 +1,274 @@
+// test/root-recovery.test.js
+// ROOT-RECOVERY (transversal): a dead persisted X-Workspace-Root
+// ("/mnt/workspaces/<tenant>/<repo>") must resolve to the LIVE clone this
+// agent actually made ("/tmp/workspaces/<owner>_<repo>") - and a root that
+// exists on disk must NEVER be overridden. Proves the QA 2026-07-19 failure
+// mode (v2 loop: prepare clones to one path, reads hit another, 40
+// iterations burned) is fixed at the single resolution point.
+
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  recoverLiveRoot,
+  resolveEffectiveHeaderRoot,
+  tenantOfNfsRoot,
+  tenantGateAllows,
+} from '../src/utils/root-recovery.js';
+
+// Silence gate-denial warns in tests (still assertable via a collector).
+const quiet = { warn: () => {} };
+
+let mount, liveOwnerRepo, liveExact, headerAlive;
+
+before(() => {
+  mount = fs.mkdtempSync(path.join(os.tmpdir(), 'root-rec-'));
+  // cloud-clone layout: <owner>_<repo>
+  liveOwnerRepo = path.join(mount, 'VISIONHAMMER_visionhammer-agents');
+  // exact-name layout (NFS-style clone under the mount)
+  liveExact = path.join(mount, 'simple-api');
+  headerAlive = fs.mkdtempSync(path.join(os.tmpdir(), 'root-alive-'));
+  for (const d of [liveOwnerRepo, liveExact]) fs.mkdirSync(d, { recursive: true });
+});
+
+after(() => {
+  for (const d of [mount, headerAlive]) {
+    try { fs.rmSync(d, { recursive: true, force: true }); } catch (_) {}
+  }
+});
+
+describe('resolveEffectiveHeaderRoot', () => {
+  test('an existing header root is returned unchanged (never overridden)', () => {
+    const eff = resolveEffectiveHeaderRoot(headerAlive, {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo }],
+      mountDir: mount,
+    });
+    assert.equal(eff.root, headerAlive);
+    assert.equal(eff.recovered, false);
+  });
+
+  test('dead NFS-era root recovers the owner_repo clone by basename (same tenant)', () => {
+    // TENANT GATE: basename recovery now requires the clone to be registered
+    // for the SAME tenant as the dead root's first path segment.
+    const dead = '/mnt/workspaces/532e03b3-7ab6/visionhammer-agents';
+    const eff = resolveEffectiveHeaderRoot(dead, {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: '532e03b3-7ab6' }],
+      mountDir: mount,
+      ...quiet,
+    });
+    assert.equal(eff.root, liveOwnerRepo);
+    assert.equal(eff.recovered, true);
+  });
+
+  test('dead root with no recoverable clone stays unchanged (behavior preserved)', () => {
+    const dead = '/mnt/workspaces/532e03b3-7ab6/totally-unknown-repo';
+    const eff = resolveEffectiveHeaderRoot(dead, { registry: [], mountDir: mount });
+    assert.equal(eff.root, dead);
+    assert.equal(eff.recovered, false);
+  });
+
+  test('blank header root resolves to null', () => {
+    const eff = resolveEffectiveHeaderRoot('   ', { registry: [], mountDir: mount });
+    assert.equal(eff.root, null);
+    assert.equal(eff.recovered, false);
+  });
+});
+
+describe('recoverLiveRoot', () => {
+  test('workspace-id hint wins when the registry has a live root', () => {
+    const other = path.join(mount, 'OTHER_visionhammer-agents');
+    fs.mkdirSync(other, { recursive: true });
+    const live = recoverLiveRoot('/mnt/dead/visionhammer-agents', {
+      wsIdHint: 'ws-77',
+      registry: [
+        { id: 'ws-77', root: liveOwnerRepo },
+        { id: 'ws-88', root: other },
+      ],
+      mountDir: mount,
+    });
+    assert.equal(live, liveOwnerRepo);
+  });
+
+  test('registry basename match works without an id hint (same tenant)', () => {
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: 'tenant-a' }],
+      mountDir: '/nonexistent-mount',
+      ...quiet,
+    });
+    assert.equal(live, liveOwnerRepo);
+  });
+
+  test('disk scan finds exact-name clones when the tenant matches the registered one', () => {
+    // Force step 3: the registry knows the tenant for this root, but its
+    // recorded root string (trailing slash) is made to fail the step-2
+    // exists check; the scan then matches the on-disk dir and the tenant
+    // gate passes via the normalized root -> tenant mapping.
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-x/simple-api', {
+      registry: [{ id: 'ws-1', root: liveExact + path.sep, tenantId: 'tenant-x' }],
+      mountDir: mount,
+      existsSync: (p) => (p.endsWith(path.sep) ? false : fs.existsSync(p)),
+      ...quiet,
+    });
+    assert.equal(live, liveExact);
+  });
+
+  test('conservative matching: a different repo name never matches', () => {
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-x/visionhammer', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo }],
+      mountDir: mount,
+    });
+    // "visionhammer" is NOT the basename ("visionhammer-agents") nor a
+    // "_visionhammer" suffix match of the clones present.
+    assert.equal(live, null);
+  });
+
+  test('degenerate roots never recover', () => {
+    for (const dead of ['/', '.', '', null, undefined]) {
+      assert.equal(recoverLiveRoot(dead, { registry: [], mountDir: mount }), null);
+    }
+  });
+
+  test('never throws on broken injections', () => {
+    assert.equal(recoverLiveRoot('/mnt/x/y', {
+      registry: [{ id: 'a', root: liveOwnerRepo }],
+      mountDir: mount,
+      existsSync: () => { throw new Error('boom'); },
+    }), null);
+  });
+});
+
+// TENANT GATE: on a shared multi-tenant agent, a dead root of tenant A must
+// NEVER recover to a clone hydrated for tenant B just because the repo
+// basenames collide. Unknown tenant on either side fails closed into the
+// structured workspace_root_not_hydrated fail-fast.
+describe('tenant gate', () => {
+  test('happy path: same-tenant basename recovery still works (QA-proven E2E scenario)', () => {
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: 'tenant-a' }],
+      mountDir: mount,
+      ...quiet,
+    });
+    assert.equal(live, liveOwnerRepo);
+  });
+
+  test('basename collision across tenants: NEVER recovers', () => {
+    const warns = [];
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: 'tenant-b' }],
+      mountDir: '/nonexistent-mount',
+      warn: (m) => warns.push(m),
+    });
+    assert.equal(live, null);
+    assert.equal(warns.length, 1);
+    assert.match(warns[0], /TENANT GATE/);
+    // Decision logs carry tenant ids + basenames only - never URLs/tokens.
+    assert.doesNotMatch(warns[0], /https?:\/\//);
+  });
+
+  test('unknown candidate tenant (clone registered without tenantId): no basename recovery', () => {
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo }],
+      mountDir: '/nonexistent-mount',
+      ...quiet,
+    });
+    assert.equal(live, null);
+  });
+
+  test('unknown dead-root tenant (non-NFS path, no hint): no basename/scan recovery', () => {
+    const live = recoverLiveRoot('/opt/legacy/visionhammer-agents', {
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: 'tenant-a' }],
+      mountDir: mount,
+      ...quiet,
+    });
+    assert.equal(live, null);
+  });
+
+  test('tenantHint fallback unlocks recovery for non-NFS dead roots of the SAME tenant', () => {
+    const live = recoverLiveRoot('/opt/legacy/visionhammer-agents', {
+      tenantHint: 'tenant-a',
+      registry: [{ id: 'ws-1', root: liveOwnerRepo, tenantId: 'tenant-a' }],
+      mountDir: '/nonexistent-mount',
+      ...quiet,
+    });
+    assert.equal(live, liveOwnerRepo);
+  });
+
+  test('workspace-id match with DIVERGENT known tenants: no recovery (fail-fast)', () => {
+    const warns = [];
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      wsIdHint: 'ws-77',
+      registry: [{ id: 'ws-77', root: liveOwnerRepo, tenantId: 'tenant-b' }],
+      mountDir: '/nonexistent-mount',
+      warn: (m) => warns.push(m),
+    });
+    assert.equal(live, null);
+    assert.equal(warns.length, 1);
+    assert.match(warns[0], /TENANT GATE.*id match denied/);
+  });
+
+  test('workspace-id match with unknown tenant on either side still recovers (id is strong)', () => {
+    // Candidate tenant unknown:
+    assert.equal(recoverLiveRoot('/mnt/workspaces/tenant-a/visionhammer-agents', {
+      wsIdHint: 'ws-77',
+      registry: [{ id: 'ws-77', root: liveOwnerRepo }],
+      mountDir: '/nonexistent-mount',
+      ...quiet,
+    }), liveOwnerRepo);
+    // Dead-root tenant unknown:
+    assert.equal(recoverLiveRoot('/opt/legacy/anything', {
+      wsIdHint: 'ws-77',
+      registry: [{ id: 'ws-77', root: liveOwnerRepo, tenantId: 'tenant-b' }],
+      mountDir: '/nonexistent-mount',
+      ...quiet,
+    }), liveOwnerRepo);
+  });
+
+  test('disk scan: unregistered clone dir (unknown tenant) is DENIED', () => {
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-x/simple-api', {
+      registry: [],
+      mountDir: mount,
+      ...quiet,
+    });
+    assert.equal(live, null);
+  });
+
+  test('disk scan: clone registered for ANOTHER tenant is DENIED', () => {
+    const warns = [];
+    const live = recoverLiveRoot('/mnt/workspaces/tenant-x/simple-api', {
+      registry: [{ id: 'ws-1', root: liveExact + path.sep, tenantId: 'tenant-y' }],
+      mountDir: mount,
+      existsSync: (p) => (p.endsWith(path.sep) ? false : fs.existsSync(p)),
+      warn: (m) => warns.push(m),
+    });
+    assert.equal(live, null);
+    assert.ok(warns.some((m) => /TENANT GATE/.test(m)));
+  });
+});
+
+describe('tenantOfNfsRoot', () => {
+  test('extracts the first segment after /mnt/workspaces/', () => {
+    assert.equal(tenantOfNfsRoot('/mnt/workspaces/2f99f61f-0a72/pure-core-ms'), '2f99f61f-0a72');
+    assert.equal(tenantOfNfsRoot('/mnt/workspaces/t1/repo/sub/dir'), 't1');
+  });
+
+  test('non-NFS or degenerate paths stay unknown (null)', () => {
+    assert.equal(tenantOfNfsRoot('/tmp/workspaces/OWNER_repo'), null);
+    assert.equal(tenantOfNfsRoot('/mnt/workspaces/only-tenant'), null);
+    assert.equal(tenantOfNfsRoot(''), null);
+    assert.equal(tenantOfNfsRoot(null), null);
+    assert.equal(tenantOfNfsRoot(undefined), null);
+  });
+});
+
+describe('tenantGateAllows', () => {
+  test('allows only known AND equal tenants', () => {
+    assert.equal(tenantGateAllows('a', 'a'), true);
+    assert.equal(tenantGateAllows('a', 'b'), false);
+    assert.equal(tenantGateAllows(null, 'a'), false);
+    assert.equal(tenantGateAllows('a', null), false);
+    assert.equal(tenantGateAllows(null, null), false);
+    assert.equal(tenantGateAllows('', ''), false);
+  });
+});

package/test/safe-exec-args.test.js

@@ -0,0 +1,58 @@
+// test/safe-exec-args.test.js - H4: request text stays data, never shell syntax.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildGrepArgs, buildTarArgs, parseAuthCommand } from '../src/utils/safe-exec-args.js';
+
+const PAYLOADS = ['"; touch PWNED; echo "', '$(touch PWNED)', '`touch PWNED`', "'; touch PWNED; '", 'a\\', '--include=x -r /etc'];
+
+test('grep argv carries pattern and filter as single entries', () => {
+  const args = buildGrepArgs({ pattern: '"; id #', fileFilter: '*.js" -r / "', root: '/ws' });
+  assert.ok(args.includes('--include=*.js" -r / "'));
+  assert.deepEqual(args.slice(-4), ['-e', '"; id #', '--', '/ws']);
+});
+
+test('grep with injection payloads never executes them', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'h4-'));
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'hello world\n');
+  for (const p of PAYLOADS) {
+    for (const f of [undefined, p]) {
+      try { execFileSync('grep', buildGrepArgs({ pattern: p, fileFilter: f, root: dir }), { cwd: dir, encoding: 'utf8' }); }
+      catch { /* exit 1/2 is fine: no match / bad pattern */ }
+    }
+  }
+  assert.equal(fs.existsSync(path.join(dir, 'PWNED')), false);
+  assert.equal(fs.existsSync(path.join(process.cwd(), 'PWNED')), false);
+});
+
+test('a leading dash pattern is a pattern, not an option', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'h4-'));
+  fs.writeFileSync(path.join(dir, 'a.txt'), 'x -rf y\n');
+  const out = execFileSync('grep', buildGrepArgs({ pattern: '-rf', root: dir }), { encoding: 'utf8' });
+  assert.match(out, /-rf/);
+});
+
+test('grep args reject empty pattern/root', () => {
+  assert.throws(() => buildGrepArgs({ pattern: '', root: '/x' }));
+  assert.throws(() => buildGrepArgs({ pattern: 'a', root: '' }));
+});
+
+test('tar argv keeps paths as entries', () => {
+  const a = buildTarArgs({ tarPath: '/tmp/x";id;".tgz', wsPath: '/mnt/$(id)' });
+  assert.equal(a[1], '/tmp/x";id;".tgz');
+  assert.equal(a[a.indexOf('-C') + 1], '/mnt/$(id)');
+});
+
+test('auth commands: only interactive logins with safe args', () => {
+  assert.deepEqual(parseAuthCommand('gcloud auth login --no-launch-browser').argv, ['gcloud', 'auth', 'login', '--no-launch-browser']);
+  assert.equal(parseAuthCommand('az login').ok, true);
+  assert.equal(parseAuthCommand('aws sso login --profile prod-1').ok, true);
+  for (const bad of ['gcloud auth login; rm -rf /', 'gh auth login && id', 'gh auth login $(id)', 'gh auth login `id`',
+    'gh auth login | sh', 'rm -rf /', 'gcloud compute ssh x', '', 'az login\nid', 'gh auth login >out', 'gh auth login &']) {
+    assert.equal(parseAuthCommand(bad).ok, false, bad);
+  }
+  assert.equal(parseAuthCommand(undefined).ok, false);
+});

package/test/sandbox.test.js

@@ -0,0 +1,98 @@
+// test/sandbox.test.js
+// SEG-3 (P0): per-workspace filesystem/exec confinement. Proves the A3 escape
+// (reading a sibling workspace) is denied and multi-repo access is allowed.
+
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  confineToRoot,
+  isInsideRoot,
+  checkArgsWithinRoot,
+  scanRawCommand,
+  SandboxViolation,
+} from '../src/utils/sandbox.js';
+
+let base, wsA, wsA2, wsB;
+
+before(() => {
+  base = fs.mkdtempSync(path.join(os.tmpdir(), 'sbx-'));
+  wsA = path.join(base, 'ws-A');      // the workspace under test (2 repos)
+  wsA2 = path.join(base, 'ws-A-2');   // sibling with a prefix-colliding name
+  wsB = path.join(base, 'ws-B');      // another workspace of the same tenant
+  for (const d of [path.join(wsA, 'repo1/src'), path.join(wsA, 'repo2/src'), wsA2, path.join(wsB, 'repo1')]) {
+    fs.mkdirSync(d, { recursive: true });
+  }
+  fs.writeFileSync(path.join(wsA, 'repo1/src/a.txt'), 'A');
+  fs.writeFileSync(path.join(wsA, 'repo2/src/b.txt'), 'B');
+  fs.writeFileSync(path.join(wsA2, 'secret.txt'), 'SIBLING');
+  fs.writeFileSync(path.join(wsB, 'repo1/x.txt'), 'OTHER');
+});
+
+after(() => { try { fs.rmSync(base, { recursive: true, force: true }); } catch {} });
+
+describe('confineToRoot — multi-repo allowed, everything else denied', () => {
+  test('both repos of the workspace are readable (multi-repo)', () => {
+    assert.equal(confineToRoot(wsA, 'repo1/src/a.txt'), path.join(fs.realpathSync(wsA), 'repo1/src/a.txt'));
+    assert.equal(confineToRoot(wsA, 'repo2/src/b.txt'), path.join(fs.realpathSync(wsA), 'repo2/src/b.txt'));
+  });
+
+  test('A3 regression: `../` into a sibling workspace is denied', () => {
+    assert.throws(() => confineToRoot(wsA, '../ws-B/repo1/x.txt'), SandboxViolation);
+    assert.equal(isInsideRoot(wsA, '../ws-B/repo1/x.txt'), false);
+  });
+
+  test('prefix-collision sibling (ws-A-2) is denied', () => {
+    assert.equal(isInsideRoot(wsA, '../ws-A-2/secret.txt'), false);
+  });
+
+  test('absolute path into another workspace is denied', () => {
+    assert.equal(isInsideRoot(wsA, path.join(wsB, 'repo1/x.txt')), false);
+  });
+
+  test('absolute /etc/passwd is denied', () => {
+    assert.equal(isInsideRoot(wsA, '/etc/passwd'), false);
+  });
+});
+
+describe('run_command argument / raw-command confinement', () => {
+  test('tokenized args: `..` path arg denied, normal flags allowed', () => {
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', '../ws-B/repo1/x.txt']).ok, false);
+    assert.equal(checkArgsWithinRoot(wsA, ['mvn', 'test', '-Dtest=*.Foo']).ok, true);
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', 'repo1/src/a.txt']).ok, true);
+  });
+
+  test('tokenized args: absolute /etc/passwd denied (run escape regression)', () => {
+    // Before the fix, checkArgsWithinRoot stripped the leading slash and
+    // re-based /etc/passwd under the root -> ok:true, and /workspace/run then
+    // executed the real /etc/passwd. It must be DENIED as filesystem-absolute.
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', '/etc/passwd']).ok, false);
+  });
+
+  test('tokenized args: absolute path into another workspace denied', () => {
+    // The A3 cross-workspace escape, but via an ABSOLUTE arg to /workspace/run.
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', path.join(wsB, 'repo1/x.txt')]).ok, false);
+    // /tmp/workspaces/<other> shape is also denied even when the dir is absent.
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', '/tmp/workspaces/other-ws/x']).ok, false);
+  });
+
+  test('tokenized args: valid relative path INSIDE the root still passes', () => {
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', 'repo2/src/b.txt']).ok, true);
+    assert.equal(checkArgsWithinRoot(wsA, ['node', 'repo1/src/a.txt']).ok, true);
+  });
+
+  test('tokenized args: absolute path INSIDE the root passes; system binaries pass', () => {
+    assert.equal(checkArgsWithinRoot(wsA, ['cat', path.join(fs.realpathSync(wsA), 'repo1/src/a.txt')]).ok, true);
+    assert.equal(checkArgsWithinRoot(wsA, ['/usr/bin/node', '--version']).ok, true);
+    assert.equal(checkArgsWithinRoot(wsA, ['/bin/ls', '-la']).ok, true);
+  });
+
+  test('raw command: traversal / cd-out / absolute-into-sibling denied', () => {
+    assert.equal(scanRawCommand(wsA, 'cat ../ws-B/repo1/x.txt').ok, false);
+    assert.equal(scanRawCommand(wsA, 'cd /etc && cat passwd').ok, false);
+    assert.equal(scanRawCommand(wsA, 'cat ' + path.join(wsA2, 'secret.txt')).ok, false);
+    assert.equal(scanRawCommand(wsA, 'mvn -q -DskipTests package').ok, true);
+  });
+});

package/test/search-outcome.test.js

@@ -0,0 +1,50 @@
+// test/search-outcome.test.js
+// /workspace/search must never answer HTTP 500 to a grep timeout: QA raised an
+// incident on the agent itself and the AI lost the partial matches.
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyGrepFailure, partialSearchBody } from '../src/utils/search-outcome.js';
+
+describe('classifyGrepFailure', () => {
+  test('exit 1 is no match', () => {
+    assert.deepEqual(classifyGrepFailure({ status: 1 }), { kind: 'no_match' });
+  });
+
+  test('exit 2 is a bad pattern', () => {
+    assert.equal(classifyGrepFailure({ status: 2, message: 'grep: x' }).kind, 'bad_pattern');
+  });
+
+  test('execSync timeout (killed, SIGTERM, status null) is a partial answer, not a crash', () => {
+    const r = classifyGrepFailure(
+      { killed: true, signal: 'SIGTERM', status: null, stdout: '/root/a.js:1:x\n/root/b.js:2:y\n' },
+      { timeoutMs: 15000 });
+    assert.equal(r.kind, 'partial');
+    assert.equal(r.reason, 'search_timeout');
+    assert.ok(r.stdout.includes('b.js'));
+  });
+
+  test('ENOBUFS is a partial answer', () => {
+    assert.equal(classifyGrepFailure({ code: 'ENOBUFS', stdout: 'x' }).reason, 'output_cap');
+  });
+
+  test('anything else stays unknown (caller rethrows)', () => {
+    assert.equal(classifyGrepFailure({ status: 127 }).kind, 'unknown');
+    assert.equal(classifyGrepFailure(null).kind, 'unknown');
+  });
+});
+
+describe('partialSearchBody', () => {
+  test('200-shaped body with relativized partial matches and a narrowing hint', () => {
+    const body = partialSearchBody('foo',
+      { reason: 'search_timeout', stdout: '/root/a.js:1:foo\n\n/root/b.js:2:foo\n', timeoutMs: 15000 },
+      (l) => l.replace('/root/', ''));
+    assert.equal(body.ok, false);
+    assert.equal(body.error, 'search_timeout');
+    assert.equal(body.partial, true);
+    assert.equal(body.count, 2);
+    assert.equal(body.results, 'a.js:1:foo\nb.js:2:foo');
+    assert.match(body.hint, /15 s/);
+    assert.match(body.hint, /file_filter/);
+  });
+});

package/test/workspace-root.test.js

@@ -0,0 +1,64 @@
+// test/workspace-root.test.js
+// SECURITY REVIEW 2026-10-11 (H4): X-Workspace-Root was used verbatim as the
+// sandbox root and is not covered by the request signature.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateHeaderRoot, workspaceBases, exactWorkspaceRoots } from '../src/utils/workspace-root.js';
+
+const BASES = ['/mnt/workspaces', '/tmp/workspaces'];
+const NOEXACT = [];
+const REG = [
+  { id: 'ws-a', root: '/srv/clones/acme_app', tenantId: 'tenant-a' },
+  { id: 'ws-b', root: '/mnt/workspaces/tenant-b/ws-b', tenantId: 'tenant-b' },
+];
+
+describe('validateHeaderRoot', () => {
+  test('a workspace under a base directory is accepted and normalised', () => {
+    const r = validateHeaderRoot('/mnt/workspaces/tenant-a/ws-1/', { bases: BASES, exact: NOEXACT, registry: [] });
+    assert.deepEqual(r, { ok: true, root: '/mnt/workspaces/tenant-a/ws-1' });
+  });
+  test('filesystem root, relative paths and the bare base are refused', () => {
+    assert.equal(validateHeaderRoot('/', { bases: BASES, exact: NOEXACT }).ok, false);
+    assert.equal(validateHeaderRoot('workspaces/x', { bases: BASES, exact: NOEXACT }).ok, false);
+    assert.equal(validateHeaderRoot('/mnt/workspaces', { bases: BASES, exact: NOEXACT }).ok, false);
+    assert.equal(validateHeaderRoot('', { bases: BASES, exact: NOEXACT }).ok, false);
+  });
+  test('traversal out of a base is refused', () => {
+    assert.equal(validateHeaderRoot('/mnt/workspaces/../../etc', { bases: BASES, exact: NOEXACT }).ok, false);
+    assert.equal(validateHeaderRoot('/mnt/workspaces-evil/x', { bases: BASES, exact: NOEXACT }).ok, false);
+  });
+  test('directories outside every base are refused (/etc, /app, /home)', () => {
+    for (const p of ['/etc', '/app/src', '/home/deepdebug/.deepdebug', '/proc/self']) {
+      assert.equal(validateHeaderRoot(p, { bases: BASES, exact: NOEXACT, registry: [] }).ok, false, p);
+    }
+  });
+  test('a registered workspace outside the bases is accepted (dev/local clones)', () => {
+    assert.equal(validateHeaderRoot('/srv/clones/acme_app/src', { bases: BASES, exact: NOEXACT, registry: REG }).ok, true);
+  });
+  test('a signed tenant cannot name another tenant\'s registered workspace', () => {
+    const r = validateHeaderRoot('/mnt/workspaces/tenant-b/ws-b', { bases: BASES, exact: NOEXACT, registry: REG, tenantId: 'tenant-a' });
+    assert.equal(r.ok, false);
+    assert.match(r.reason, /another tenant/);
+    assert.equal(validateHeaderRoot('/mnt/workspaces/tenant-b/ws-b', { bases: BASES, exact: NOEXACT, registry: REG, tenantId: 'tenant-b' }).ok, true);
+    // unsigned request: registry ownership is not asserted (signature mode warn)
+    assert.equal(validateHeaderRoot('/mnt/workspaces/tenant-b/ws-b', { bases: BASES, exact: NOEXACT, registry: REG }).ok, true);
+  });
+  test('NUL bytes are refused', () => {
+    assert.equal(validateHeaderRoot('/mnt/workspaces/a\0b', { bases: BASES, exact: NOEXACT }).ok, false);
+  });
+});
+
+describe('workspaceBases / exactWorkspaceRoots', () => {
+  test('defaults plus LOCAL_AGENT_WORKSPACE_BASES; root and relative entries dropped', () => {
+    const b = workspaceBases({ LOCAL_AGENT_WORKSPACE_BASES: '/data/ws, relative, /' });
+    assert.deepEqual(b, ['/mnt/workspaces', '/tmp/workspaces', '/data/ws']);
+  });
+  test('WORKSPACE_ROOT is a workspace itself: accepted exactly or below, never "/"', () => {
+    assert.deepEqual(exactWorkspaceRoots({ WORKSPACE_ROOT: '/workspace/' }), ['/workspace']);
+    assert.deepEqual(exactWorkspaceRoots({ WORKSPACE_ROOT: '/' }), []);
+    const exact = exactWorkspaceRoots({ WORKSPACE_ROOT: '/workspace' });
+    assert.equal(validateHeaderRoot('/workspace', { bases: BASES, exact }).ok, true);
+    assert.equal(validateHeaderRoot('/workspace/sub', { bases: BASES, exact }).ok, true);
+    assert.equal(validateHeaderRoot('/workspace2', { bases: BASES, exact }).ok, false);
+  });
+});

package/tools/graphify-validation/README.md

@@ -0,0 +1,92 @@
+# Graphify validation harness (T4-06, D8)
+
+Reproducible measurements for the Graphify go/no-go criteria G1-G10 of the Local Agent GA plan
+(`10 Library/Plans/Local Agent GA Plano 2026-10-28.md`, section 2) and for the pilot note
+(`10 Library/Recon & Reviews/Graphify Piloto 2026-10-27.md`). A human or an agent runs one command and
+gets `REPORT.md` plus the raw JSON/CSV behind every number.
+
+It is a **validation tool, not part of the agent runtime**: nothing in `src/`, `bin/`, `Dockerfile*`
+or `package.json` changes, no flag exists, and the Node agent never executes anything from here.
+
+## What it measures
+
+| Criterion | What the harness does | Needs outside this repo |
+|---|---|---|
+| G1 extraction | share of code files (java, ts, tsx, js, jsx, mjs, cjs, py, go, tf; no pom/SQL/markdown) with at least one symbol; lists files without symbols (syntax errors) | nothing |
+| G2 edges | INFERRED share per repo; seeded stratified sample of INFERRED `calls` edges (20 ambiguous + 40 other, non-test sources) judged by an **automatic oracle** (Java: receiver type declared in the file versus the class owning the target method); CSV for the manual two-person review | the human review (fill `manual_verdict`, rerun with `--manual-dir`) |
+| G3 Spring/DI | builds the graph of `fixtures/spring` (`@Bean`, `@Qualifier`, interface injection, Lombok) and checks `fixtures/spring/expected.json` by group | nothing |
+| G4 performance | wall time and peak RSS of the whole process tree (sampled every 250 ms) for a cold run and for an incremental run after a one-file change | a 2 vCPU / 4 GB machine for the real limit |
+| G5 recall | `graphify affected` (depth 1) versus `rg -w` per symbol; recall@8 of `graphify query` versus a keyword (ripgrep) baseline over `config/questions.json`; optional pgvector column | pgvector results (`--vector-results`, format below) |
+| G7 security | cold run with the network denied (macOS `sandbox-exec`, Linux `unshare -n`), a `sys.addaudithook` hook counting `socket.*` and exec events, proof that the block is effective, `pip-audit` of the pinned set | nothing |
+| G8 hygiene | two cold runs must give the same node/edge fingerprint; counts `graphify-out/` files versioned at the ref | nothing |
+| licenses | per-distribution license inventory of the installed set | legal review |
+| G6, G9, G10 | **not measured** (need LLM runs, Docker, the pilot repo); the report says so | see `docs/graphify-packaging-plan.md` |
+
+## Run it
+
+```bash
+# clones of the VisionHammer repos live in $REPOS (only `git archive <ref>` is used: read-only)
+RG=$(command -v rg) PYTHON=python3.12 \
+  tools/graphify-validation/run.sh --repos-dir "$REPOS" --out /some/scratch/dir --pip-audit
+# optional: --fetch (git fetch origin in each clone), --repo vh-api-gateway, --only cold,edges,
+#           --vector-results vectors.json, --manual-dir reviewed/
+python3 -m unittest discover -s tools/graphify-validation/tests   # harness self-tests, no graphify needed
+```
+
+Output: `OUT/REPORT.md`, `OUT/results/*.json`, `OUT/review/<repo>.csv`, `OUT/audit-<repo>.tsv`.
+`OUT` must be outside any git worktree and outside iCloud folders.
+
+Guarantees built in:
+
+- **Pinned and hashed install**: `requirements.lock` (Python 3.12) is installed with
+  `--require-hashes --no-deps --only-binary=:all:`; `requirements.in` is the single input
+  (`graphifyy[sql,terraform]==0.9.93`). The extras `mcp`, `leiden` and every LLM extra are **not** installed.
+  `requirements-py311.lock` is the same set resolved for Python 3.11 (Debian bookworm, `local-agent-full`).
+- **Only VisionHammer repos**: `config/repos.json` lists the allowed GitHub owner; the harness refuses a clone whose
+  `origin` is not under it. Customer repos are out of scope by construction.
+- **Clean environment**: graphify runs with only `HOME` (an empty dir), `PATH`, `LANG`, `PYTHONHASHSEED`, `NO_COLOR`.
+  No LLM keys, no cloud credentials, no proxies. `label`, `cluster-only`, `add`, `clone`, `prs` are never invoked.
+- **Snapshots, not worktrees**: each run extracts `git archive <ref>` into `OUT/work/<repo>` and removes any versioned
+  `graphify-out/`, so the checkout is never touched and results are reproducible per commit.
+- **Network**: the only network use is `git fetch origin` (opt-in `--fetch`), `pip install` from PyPI on the first run
+  and `pip-audit` (PyPI/OSV). Graphify itself runs offline in the blocked step.
+
+## Reading the report
+
+Verdicts: `PASSA` / `FALHA` against the proposed limits (G1 >= 95 %, G2 INFERRED <= 15 % and precision >= 85 %,
+G3 >= 90 %, G4 cold <= 60 s and <= 1 GB RSS for repos <= 2 000 files and incremental <= 30 s, G5 "who affects"
+recall >= 90 %); `PARCIAL` = measured, but a human or environment step is missing; `NAO MEDIDO`.
+
+Known limits of the measurements (also printed in the report):
+
+- The G2 precision is a **proxy**: the Java oracle checks the receiver's declared type, it does not read the code like
+  a reviewer. `unknown` rows (chained calls, `var`, lambda parameters, constructors) are excluded from the precision and
+  listed in the CSV. For non-Java files only a weak check (callee name on the line and target module imported) exists.
+- `peak_tree_rss_mb` is a sampled sum that can double-count shared pages; `max_child_rss_mb` is the kernel `ru_maxrss` of the largest child (fresh helper process per run).
+- The `affected` reference (`rg -w`) also matches comments, strings and same-named types, so "precision vs rg" is not
+  graph precision; "recall vs rg" is the number that matters for "who is affected".
+- The recall@8 question set is small and hand-written (`config/questions.json`); extend it per repo before relying
+  on it for a decision. Test files are removed from every ranking, as the loop context rule requires.
+- Determinism excludes community ids (they change with every edit, see the pilot note).
+
+`vector-results.json` format (to fill the pgvector column): `{"gw-1": ["src/main/.../PolicyGate.java", ...], ...}`,
+ranked, repo-relative paths, produced from the `RagEvalController` dataset with the same questions.
+
+## Layout
+
+```
+run.sh                       entry point (venv from the hashed lock, run, optional pip-audit, report)
+requirements.in / .lock      Graphify pin for Python 3.12 (harness venv)
+requirements-py311.lock      same pin resolved for Python 3.11 (image packaging plan)
+requirements-tools.*         pip-audit pin (tool venv, hashed)
+config/                      repos (allow-list + refs), symbols for affected-vs-rg, reference questions
+fixtures/spring/             synthetic Spring project + expected.json
+lib/                         run_all (orchestrator), run_graphify (time/RSS/network), graph_metrics, sample_edges,
+                             affected_vs_rg, recall, spring_fixture, licenses, report, audit_hook/
+tests/                       unittest self-tests for the harness logic
+```
+
+Upgrading Graphify: edit `requirements.in`, regenerate both locks
+(`uv pip compile requirements.in --python-version 3.12 --generate-hashes --no-header -o requirements.lock`, and the same with
+`--python-version 3.11 --python-platform x86_64-unknown-linux-gnu --only-binary :all: -o requirements-py311.lock`),
+rerun the harness, attach the new report to the PR. Policy: no version younger than 7 days.