teamshare-bridge 0.22.7 → 0.22.8

package/tools/workspace-arbitration-check.mjs

@@ -1,390 +1,390 @@
-#!/usr/bin/env node
-/**
- * Workspace arbitration E2E check (IMP-950).
- * Run from teamshare-bridge/ AFTER `npm run build`:
- *
- *   node tools/workspace-arbitration-check.mjs
- *
- * Exercises the stack in an ISOLATED state root (TS_WS_LOCK_ROOT /
- * TS_PRESENCE_ROOT point at a temp dir set before any dist module loads).
- * Multi-holder scenarios spawn CHILD processes - same-PID callers are one
- * owner by design (nested-call re-entrancy), so distinct holders must have
- * distinct pids.
- */
-import { spawn, spawnSync } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync, readdirSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
-
-const BRIDGE = resolve(fileURLToPath(new URL('../', import.meta.url)));
-const DIST = join(BRIDGE, 'dist');
-
-// Isolate BEFORE importing dist modules (they read env at import time).
-const stateRoot = mkdtempSync(join(tmpdir(), 'ts-ws-e2e-'));
-process.env.TS_WS_LOCK_ROOT = join(stateRoot, 'locks');
-process.env.TS_PRESENCE_ROOT = join(stateRoot, 'presence');
-
-const distUrl = (rel) => pathToFileURL(join(DIST, rel)).href;
-
-const { tryAcquireWsLock, acquireWsLock, releaseWsLock, readWsHolders, __writeForeignHolder } =
-  await import(distUrl('lib/workspace/repo-lock.js'));
-const { registerPresence, listPresent, unregisterPresence } =
-  await import(distUrl('lib/workspace/presence.js'));
-const { classifyCommand } = await import(distUrl('lib/workspace/classify.js'));
-const { startProbeServer } = await import(distUrl('bridge/local-server.js'));
-
-let pass = 0;
-let fail = 0;
-function check(name, cond, extra = '') {
-  if (cond) {
-    pass++;
-    console.log(`  ok    ${name}`);
-  } else {
-    fail++;
-    console.log(`  FAIL  ${name}${extra ? ` - ${extra}` : ''}`);
-  }
-}
-const section = (t) => console.log(`\n== ${t} ==`);
-
-const dirScope = (p) => ({ kind: 'dir', path: p });
-const workDir = mkdtempSync(join(tmpdir(), 'ts-ws-work-'));
-
-/** Child-process lock holder: acquires, prints HELD, releases after ms. */
-const HOLDER_SCRIPT = `
-const { tryAcquireWsLock, releaseWsLock } = await import(${JSON.stringify(distUrl('lib/workspace/repo-lock.js'))});
-const [dir, mode, ms] = process.argv.slice(2);
-const r = tryAcquireWsLock({ kind: 'dir', path: dir }, mode === 'shared' ? 'shared' : 'exclusive', { label: 'child-holder' });
-if (!r.ok) { console.log('NOLOCK:' + r.reason); process.exit(3); }
-console.log('HELD');
-setTimeout(() => { releaseWsLock(r.handle); }, Number(ms));
-`;
-
-function spawnHolder(dir, mode, ms) {
-  const script = join(stateRoot, `holder-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.mjs`);
-  writeFileSync(script, HOLDER_SCRIPT);
-  const child = spawn(process.execPath, [script, dir, mode, String(ms)], {
-    env: process.env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  let out = '';
-  child.stdout.on('data', (d) => (out += d.toString()));
-  const held = new Promise((res) => {
-    const iv = setInterval(() => {
-      if (out.includes('HELD') || out.includes('NOLOCK')) {
-        clearInterval(iv);
-        res(out.includes('HELD'));
-      }
-    }, 50);
-    child.on('exit', () => {
-      clearInterval(iv);
-      res(out.includes('HELD'));
-    });
-  });
-  return { child, held, output: () => out };
-}
-
-async function waitFor(condition, timeoutMs = 4000) {
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    if (condition()) return true;
-    if (Date.now() >= deadline) return false;
-    await new Promise((r) => setTimeout(r, 60));
-  }
-}
-
-// ?? 1-4: repo-lock (cross-pid semantics) ????????????????????????????????????
-section('repo-lock basics');
-{
-  const holder = spawnHolder(workDir, 'exclusive', 4000);
-  check('child holder acquired', await holder.held);
-  check('holder visible in readWsHolders',
-    await waitFor(() => readWsHolders(dirScope(workDir)).some((h) => !h.stale && h.holder.label === 'child-holder')));
-
-  const b = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-B' });
-  check('second exclusive (other pid) refused busy', !b.ok && b.reason === 'busy');
-  const c = tryAcquireWsLock(dirScope(workDir), 'shared', { label: 'parent-C' });
-  check('shared blocked while exclusive held', !c.ok && c.reason === 'busy');
-
-  // Timeout against the live foreign holder.
-  const t0 = Date.now();
-  const timedOut = await acquireWsLock(dirScope(workDir), 'exclusive', {}, { waitMs: 800, pollMs: 100 });
-  const elapsed = Date.now() - t0;
-  check('wait deadline returns null', timedOut === null);
-  check('deadline respected (~800ms)', elapsed >= 700 && elapsed < 3000, `${elapsed}ms`);
-
-  // Wait for the child to release, then acquire from the parent.
-  await new Promise((res) => holder.child.on('exit', res));
-  const after = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-after' });
-  check('acquire succeeds once holder exits', after.ok === true);
-  releaseWsLock(after.ok ? after.handle : null);
-
-  // Shared coexistence + exclusive blocked by readers (all cross-pid).
-  const s1 = spawnHolder(workDir, 'shared', 2500);
-  const s2 = spawnHolder(workDir, 'shared', 2500);
-  check('shared holder #1 acquired', await s1.held);
-  check('shared holder #2 acquired', await s2.held);
-  const excl = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-excl' });
-  check('exclusive blocked by shared readers', !excl.reason || excl.reason === 'busy' ? !excl.ok : !excl.ok, JSON.stringify(excl).slice(0, 80));
-  await new Promise((res) => s1.child.on('exit', res));
-  await new Promise((res) => s2.child.on('exit', res));
-}
-
-// Stale takeover (dead pid).
-{
-  const fakeDeadPid = 0x3ffffff0;
-  __writeForeignHolder(dirScope(workDir), 'exclusive', fakeDeadPid);
-  const holders = readWsHolders(dirScope(workDir));
-  check('dead-pid holder flagged stale', holders.length === 1 && holders[0].stale);
-  const g = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'takeover' });
-  check('stale exclusive taken over', g.ok === true);
-  releaseWsLock(g.ok ? g.handle : null);
-}
-
-// ?? 5: presence ?????????????????????????????????????????????????????????????
-section('presence registry');
-{
-  registerPresence(workDir, { agentId: 'agent-a', kind: 'task' });
-  const here = listPresent(workDir);
-  check('presence listed after register', here.length === 1 && here[0].agentId === 'agent-a');
-  unregisterPresence(workDir);
-  check('presence empty after unregister', listPresent(workDir).length === 0);
-}
-
-// ?? 6: classification ???????????????????????????????????????????????????????
-section('classification');
-{
-  const cases = [
-    ['npm install', 'exclusive'],
-    ['npm ci --silent', 'exclusive'],
-    ['pnpm add zod', 'exclusive'],
-    ['yarn remove left-pad', 'exclusive'],
-    ['npm run build', 'exclusive'],
-    ['npm run db:migrate', 'exclusive'],
-    ['npx prisma generate', 'exclusive'],
-    ['git checkout main', 'exclusive'],
-    ['git reset --hard HEAD~1', 'exclusive'],
-    ['git rebase origin/main', 'exclusive'],
-    ['npm run dev', 'long-shared'],
-    ['npm test', 'shared'],
-    ['npx eslint .', 'shared'],
-    ['git status', 'shared'],
-    ['git commit -m x', 'shared'],
-    ['git push -u origin HEAD', 'shared'],
-    ['node server.js', 'passthrough'],
-    ['python script.py', 'passthrough'],
-  ];
-  for (const [cmd, expected] of cases) {
-    check(`${cmd} -> ${expected}`, classifyCommand(cmd).cls === expected, classifyCommand(cmd).cls);
-  }
-  const prisma = classifyCommand('npx prisma migrate deploy');
-  check('prisma migrate needs global prisma-generate', (prisma.global ?? []).includes('prisma-generate'));
-}
-
-// ?? 7+8: arbiter HTTP endpoints + SSE ???????????????????????????????????????
-section('arbiter HTTP + SSE');
-{
-  const { server, port } = await startProbeServer(49777, () => ({
-    configPath: '', agents: [], registeredSchemes: false, projects: {},
-  }));
-  const base = `http://127.0.0.1:${port}`;
-  try {
-    const ping = await fetch(`${base}/ping`);
-    check('/ping alive', ping.ok);
-
-    // SSE subscriber first so granted/busy events below are observed.
-    const events = [];
-    const ac = new AbortController();
-    const sseDone = (async () => {
-      const res = await fetch(`${base}/arbitrate/events`, { signal: ac.signal });
-      const reader = res.body.getReader();
-      const dec = new TextDecoder();
-      let buf = '';
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += dec.decode(value, { stream: true });
-        let idx;
-        while ((idx = buf.indexOf('\n\n')) >= 0) {
-          const frame = buf.slice(0, idx);
-          buf = buf.slice(idx + 2);
-          const line = frame.split('\n').find((l) => l.startsWith('data: '));
-          if (line) events.push(JSON.parse(line.slice(6)));
-        }
-      }
-    })().catch(() => {});
-    await new Promise((r) => setTimeout(r, 150));
-
-    // Cross-pid busy over HTTP: child holds, endpoint must report busy...
-    const httpHolder = spawnHolder(workDir, 'exclusive', 6000);
-    await httpHolder.held;
-    const scope = { kind: 'dir', path: workDir };
-    const busyRes = await fetch(`${base}/arbitrate/acquire`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ scope, mode: 'exclusive', waitMs: 600 }),
-    });
-    const busyBody = await busyRes.json();
-    check('HTTP acquire reports busy vs foreign holder', busyBody.ok === false && busyBody.reason === 'busy');
-
-    // ...and grants once the foreign holder exits.
-    await new Promise((res) => httpHolder.child.on('exit', res));
-    const grantRes = await fetch(`${base}/arbitrate/acquire`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ scope, mode: 'exclusive', waitMs: 2000, holder: { label: 'http-A' } }),
-    });
-    const granted = await grantRes.json();
-    check('HTTP acquire grants after holder exits', granted.ok === true && typeof granted.file === 'string');
-
-    const rel = await fetch(`${base}/arbitrate/release`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ file: granted.file }),
-    });
-    check('HTTP release ok', rel.ok && (await rel.json()).ok === true);
-
-    // Release guard: paths outside the lock tree must be refused.
-    const evil = await fetch(`${base}/arbitrate/release`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ file: join(stateRoot, 'innocent.txt') }),
-    });
-    check('release refuses non-lock paths', (await evil.json()).ok === false);
-
-    const status = await (await fetch(`${base}/arbitrate/status`)).json();
-    check('status lists scopes', Array.isArray(status.scopes));
-
-    await fetch(`${base}/arbitrate/publish`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ event: { type: 'peer.ping', note: 'e2e-hello' } }),
-    });
-    await new Promise((r) => setTimeout(r, 400));
-    check('SSE receives lock.granted', events.some((e) => e.type === 'lock.granted'), JSON.stringify(events.slice(0, 2)));
-    check('SSE receives peer.ping', events.some((e) => e.type === 'peer.ping'));
-    ac.abort();
-    await sseDone;
-  } finally {
-    server.close();
-  }
-}
-
-// ?? 9-11: shim runner ???????????????????????????????????????????????????????
-section('shim runner');
-
-// Parent-held FS blocker helpers (distinct pid from the shim subprocess).
-let blockerHandle = null;
-function tryAcquireFsBlocker(dir) {
-  const r = tryAcquireWsLock(dirScope(dir), 'exclusive', { label: 'blocker' });
-  if (r.ok) blockerHandle = r.handle;
-  return r.ok;
-}
-function releaseFsBlocker() {
-  releaseWsLock(blockerHandle);
-  blockerHandle = null;
-}
-{
-  const runner = join(DIST, 'lib/workspace/shim-runner.js');
-  const env = {
-    ...process.env,
-    TS_AGENT_ID: 'e2e-agent',
-    TS_SESSION_KIND: 'task',
-    TS_SHIM_WAIT_MS: '1500',
-  };
-
-  // 9a: passthrough commands never touch locks.
-  const pt = spawnSync(process.execPath, [runner, 'node', '-e', 'console.log("passthrough-ok")'], {
-    cwd: workDir, encoding: 'utf8', env,
-  });
-  check('passthrough executes directly', pt.stdout.includes('passthrough-ok') && pt.status === 0);
-
-  // 9b: fail-open when the lock root is unusable (a file where a dir must be).
-  const badRootFile = join(stateRoot, 'not-a-dir');
-  writeFileSync(badRootFile, 'x');
-  const fo = spawnSync(
-    process.execPath,
-    [runner, 'npm', 'run', 'build'],
-    { cwd: workDir, encoding: 'utf8', env: { ...env, TS_WS_LOCK_ROOT: badRootFile }, timeout: 120_000 },
-  );
-  const reachedNpm =
-    (fo.stderr ?? '').includes('arbitration skipped') ||
-    (fo.stderr ?? '').includes('Missing script') ||
-    (fo.stdout ?? '').includes('Missing script');
-  check('broken lock root -> fail-open runs npm', reachedNpm, `exit=${fo.status}`);
-
-  // 10: exclusive hold blocks shim npm build (fail-closed exit 124)...
-  const held = tryAcquireFsBlocker(workDir);
-  check('test blocker acquired', held === true);
-  const dumpTree = () => {
-    const out = [];
-    const walk = (d, pfx) => {
-      for (const e of readdirSync(d, { withFileTypes: true })) {
-        const fp = join(d, e.name);
-        if (e.isDirectory()) walk(fp, `${pfx}${e.name}/`);
-        else out.push(pfx + e.name);
-      }
-    };
-    try {
-      walk(process.env.TS_WS_LOCK_ROOT, '');
-    } catch {
-      /* root missing */
-    }
-    return out;
-  };
-  console.log('    [diag] lock tree while blocked:', JSON.stringify(dumpTree()));
-  const blocked = spawnSync(
-    process.execPath,
-    [runner, 'npm', 'run', 'build'],
-    { cwd: workDir, encoding: 'utf8', env, timeout: 60_000 },
-  );
-  check('shim waits and exits 124 on busy workspace', blocked.status === 124, `exit=${blocked.status}`);
-  console.log('    [diag] blocked stderr head:', (blocked.stderr ?? '').slice(0, 500).replace(/\n/g, ' | '));
-  check('timeout note explains refusal', (blocked.stderr ?? '').includes('NOT running'), (blocked.stderr ?? '').slice(-160));
-  releaseFsBlocker();
-
-  // ...then proceeds to the REAL npm once released.
-  const freed = spawnSync(
-    process.execPath,
-    [runner, 'npm', 'run', 'build'],
-    { cwd: workDir, encoding: 'utf8', env, timeout: 120_000 },
-  );
-  const ranNpm =
-    (freed.stderr ?? '').includes('Missing script') ||
-    (freed.stdout ?? '').includes('Missing script') ||
-    (freed.stderr ?? '').includes('npm error');
-  check('after release shim reaches real npm', ranNpm && freed.status !== 124, `exit=${freed.status}`);
-}
-
-// Nested bypass: parent holds the scope; shim with TS_WS_HELD skips locking.
-section('nested TS_WS_HELD bypass');
-{
-  const { scopeKey } = await import(distUrl('lib/workspace/repo-lock.js'));
-  const key = scopeKey(dirScope(workDir));
-  const ok = tryAcquireFsBlocker(workDir);
-  check('parent holds scope', ok === true);
-  const nested = spawnSync(
-    process.execPath,
-    [join(DIST, 'lib/workspace/shim-runner.js'), 'npm', 'install', '--dry-run'],
-    {
-      cwd: workDir,
-      encoding: 'utf8',
-      timeout: 120_000,
-      env: { ...process.env, TS_WS_HELD: key },
-    },
-  );
-  check('nested shim bypasses parent hold (no 124)', nested.status !== 124, `exit=${nested.status}`);
-  releaseFsBlocker();
-}
-
-// ?? cleanup ?????????????????????????????????????????????????????????????????
-try {
-  rmSync(stateRoot, { recursive: true, force: true });
-  rmSync(workDir, { recursive: true, force: true });
-} catch {
-  /* best-effort */
-}
-
-console.log(`\n${pass} passed, ${fail} failed`);
-process.exit(fail > 0 ? 1 : 0);
+#!/usr/bin/env node
+/**
+ * Workspace arbitration E2E check (IMP-950).
+ * Run from teamshare-bridge/ AFTER `npm run build`:
+ *
+ *   node tools/workspace-arbitration-check.mjs
+ *
+ * Exercises the stack in an ISOLATED state root (TS_WS_LOCK_ROOT /
+ * TS_PRESENCE_ROOT point at a temp dir set before any dist module loads).
+ * Multi-holder scenarios spawn CHILD processes - same-PID callers are one
+ * owner by design (nested-call re-entrancy), so distinct holders must have
+ * distinct pids.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+const BRIDGE = resolve(fileURLToPath(new URL('../', import.meta.url)));
+const DIST = join(BRIDGE, 'dist');
+
+// Isolate BEFORE importing dist modules (they read env at import time).
+const stateRoot = mkdtempSync(join(tmpdir(), 'ts-ws-e2e-'));
+process.env.TS_WS_LOCK_ROOT = join(stateRoot, 'locks');
+process.env.TS_PRESENCE_ROOT = join(stateRoot, 'presence');
+
+const distUrl = (rel) => pathToFileURL(join(DIST, rel)).href;
+
+const { tryAcquireWsLock, acquireWsLock, releaseWsLock, readWsHolders, __writeForeignHolder } =
+  await import(distUrl('lib/workspace/repo-lock.js'));
+const { registerPresence, listPresent, unregisterPresence } =
+  await import(distUrl('lib/workspace/presence.js'));
+const { classifyCommand } = await import(distUrl('lib/workspace/classify.js'));
+const { startProbeServer } = await import(distUrl('bridge/local-server.js'));
+
+let pass = 0;
+let fail = 0;
+function check(name, cond, extra = '') {
+  if (cond) {
+    pass++;
+    console.log(`  ok    ${name}`);
+  } else {
+    fail++;
+    console.log(`  FAIL  ${name}${extra ? ` - ${extra}` : ''}`);
+  }
+}
+const section = (t) => console.log(`\n== ${t} ==`);
+
+const dirScope = (p) => ({ kind: 'dir', path: p });
+const workDir = mkdtempSync(join(tmpdir(), 'ts-ws-work-'));
+
+/** Child-process lock holder: acquires, prints HELD, releases after ms. */
+const HOLDER_SCRIPT = `
+const { tryAcquireWsLock, releaseWsLock } = await import(${JSON.stringify(distUrl('lib/workspace/repo-lock.js'))});
+const [dir, mode, ms] = process.argv.slice(2);
+const r = tryAcquireWsLock({ kind: 'dir', path: dir }, mode === 'shared' ? 'shared' : 'exclusive', { label: 'child-holder' });
+if (!r.ok) { console.log('NOLOCK:' + r.reason); process.exit(3); }
+console.log('HELD');
+setTimeout(() => { releaseWsLock(r.handle); }, Number(ms));
+`;
+
+function spawnHolder(dir, mode, ms) {
+  const script = join(stateRoot, `holder-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.mjs`);
+  writeFileSync(script, HOLDER_SCRIPT);
+  const child = spawn(process.execPath, [script, dir, mode, String(ms)], {
+    env: process.env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let out = '';
+  child.stdout.on('data', (d) => (out += d.toString()));
+  const held = new Promise((res) => {
+    const iv = setInterval(() => {
+      if (out.includes('HELD') || out.includes('NOLOCK')) {
+        clearInterval(iv);
+        res(out.includes('HELD'));
+      }
+    }, 50);
+    child.on('exit', () => {
+      clearInterval(iv);
+      res(out.includes('HELD'));
+    });
+  });
+  return { child, held, output: () => out };
+}
+
+async function waitFor(condition, timeoutMs = 4000) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (condition()) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((r) => setTimeout(r, 60));
+  }
+}
+
+// ?? 1-4: repo-lock (cross-pid semantics) ????????????????????????????????????
+section('repo-lock basics');
+{
+  const holder = spawnHolder(workDir, 'exclusive', 4000);
+  check('child holder acquired', await holder.held);
+  check('holder visible in readWsHolders',
+    await waitFor(() => readWsHolders(dirScope(workDir)).some((h) => !h.stale && h.holder.label === 'child-holder')));
+
+  const b = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-B' });
+  check('second exclusive (other pid) refused busy', !b.ok && b.reason === 'busy');
+  const c = tryAcquireWsLock(dirScope(workDir), 'shared', { label: 'parent-C' });
+  check('shared blocked while exclusive held', !c.ok && c.reason === 'busy');
+
+  // Timeout against the live foreign holder.
+  const t0 = Date.now();
+  const timedOut = await acquireWsLock(dirScope(workDir), 'exclusive', {}, { waitMs: 800, pollMs: 100 });
+  const elapsed = Date.now() - t0;
+  check('wait deadline returns null', timedOut === null);
+  check('deadline respected (~800ms)', elapsed >= 700 && elapsed < 3000, `${elapsed}ms`);
+
+  // Wait for the child to release, then acquire from the parent.
+  await new Promise((res) => holder.child.on('exit', res));
+  const after = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-after' });
+  check('acquire succeeds once holder exits', after.ok === true);
+  releaseWsLock(after.ok ? after.handle : null);
+
+  // Shared coexistence + exclusive blocked by readers (all cross-pid).
+  const s1 = spawnHolder(workDir, 'shared', 2500);
+  const s2 = spawnHolder(workDir, 'shared', 2500);
+  check('shared holder #1 acquired', await s1.held);
+  check('shared holder #2 acquired', await s2.held);
+  const excl = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'parent-excl' });
+  check('exclusive blocked by shared readers', !excl.reason || excl.reason === 'busy' ? !excl.ok : !excl.ok, JSON.stringify(excl).slice(0, 80));
+  await new Promise((res) => s1.child.on('exit', res));
+  await new Promise((res) => s2.child.on('exit', res));
+}
+
+// Stale takeover (dead pid).
+{
+  const fakeDeadPid = 0x3ffffff0;
+  __writeForeignHolder(dirScope(workDir), 'exclusive', fakeDeadPid);
+  const holders = readWsHolders(dirScope(workDir));
+  check('dead-pid holder flagged stale', holders.length === 1 && holders[0].stale);
+  const g = tryAcquireWsLock(dirScope(workDir), 'exclusive', { label: 'takeover' });
+  check('stale exclusive taken over', g.ok === true);
+  releaseWsLock(g.ok ? g.handle : null);
+}
+
+// ?? 5: presence ?????????????????????????????????????????????????????????????
+section('presence registry');
+{
+  registerPresence(workDir, { agentId: 'agent-a', kind: 'task' });
+  const here = listPresent(workDir);
+  check('presence listed after register', here.length === 1 && here[0].agentId === 'agent-a');
+  unregisterPresence(workDir);
+  check('presence empty after unregister', listPresent(workDir).length === 0);
+}
+
+// ?? 6: classification ???????????????????????????????????????????????????????
+section('classification');
+{
+  const cases = [
+    ['npm install', 'exclusive'],
+    ['npm ci --silent', 'exclusive'],
+    ['pnpm add zod', 'exclusive'],
+    ['yarn remove left-pad', 'exclusive'],
+    ['npm run build', 'exclusive'],
+    ['npm run db:migrate', 'exclusive'],
+    ['npx prisma generate', 'exclusive'],
+    ['git checkout main', 'exclusive'],
+    ['git reset --hard HEAD~1', 'exclusive'],
+    ['git rebase origin/main', 'exclusive'],
+    ['npm run dev', 'long-shared'],
+    ['npm test', 'shared'],
+    ['npx eslint .', 'shared'],
+    ['git status', 'shared'],
+    ['git commit -m x', 'shared'],
+    ['git push -u origin HEAD', 'shared'],
+    ['node server.js', 'passthrough'],
+    ['python script.py', 'passthrough'],
+  ];
+  for (const [cmd, expected] of cases) {
+    check(`${cmd} -> ${expected}`, classifyCommand(cmd).cls === expected, classifyCommand(cmd).cls);
+  }
+  const prisma = classifyCommand('npx prisma migrate deploy');
+  check('prisma migrate needs global prisma-generate', (prisma.global ?? []).includes('prisma-generate'));
+}
+
+// ?? 7+8: arbiter HTTP endpoints + SSE ???????????????????????????????????????
+section('arbiter HTTP + SSE');
+{
+  const { server, port } = await startProbeServer(49777, () => ({
+    configPath: '', agents: [], registeredSchemes: false, projects: {},
+  }));
+  const base = `http://127.0.0.1:${port}`;
+  try {
+    const ping = await fetch(`${base}/ping`);
+    check('/ping alive', ping.ok);
+
+    // SSE subscriber first so granted/busy events below are observed.
+    const events = [];
+    const ac = new AbortController();
+    const sseDone = (async () => {
+      const res = await fetch(`${base}/arbitrate/events`, { signal: ac.signal });
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      let buf = '';
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += dec.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf('\n\n')) >= 0) {
+          const frame = buf.slice(0, idx);
+          buf = buf.slice(idx + 2);
+          const line = frame.split('\n').find((l) => l.startsWith('data: '));
+          if (line) events.push(JSON.parse(line.slice(6)));
+        }
+      }
+    })().catch(() => {});
+    await new Promise((r) => setTimeout(r, 150));
+
+    // Cross-pid busy over HTTP: child holds, endpoint must report busy...
+    const httpHolder = spawnHolder(workDir, 'exclusive', 6000);
+    await httpHolder.held;
+    const scope = { kind: 'dir', path: workDir };
+    const busyRes = await fetch(`${base}/arbitrate/acquire`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ scope, mode: 'exclusive', waitMs: 600 }),
+    });
+    const busyBody = await busyRes.json();
+    check('HTTP acquire reports busy vs foreign holder', busyBody.ok === false && busyBody.reason === 'busy');
+
+    // ...and grants once the foreign holder exits.
+    await new Promise((res) => httpHolder.child.on('exit', res));
+    const grantRes = await fetch(`${base}/arbitrate/acquire`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ scope, mode: 'exclusive', waitMs: 2000, holder: { label: 'http-A' } }),
+    });
+    const granted = await grantRes.json();
+    check('HTTP acquire grants after holder exits', granted.ok === true && typeof granted.file === 'string');
+
+    const rel = await fetch(`${base}/arbitrate/release`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file: granted.file }),
+    });
+    check('HTTP release ok', rel.ok && (await rel.json()).ok === true);
+
+    // Release guard: paths outside the lock tree must be refused.
+    const evil = await fetch(`${base}/arbitrate/release`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file: join(stateRoot, 'innocent.txt') }),
+    });
+    check('release refuses non-lock paths', (await evil.json()).ok === false);
+
+    const status = await (await fetch(`${base}/arbitrate/status`)).json();
+    check('status lists scopes', Array.isArray(status.scopes));
+
+    await fetch(`${base}/arbitrate/publish`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event: { type: 'peer.ping', note: 'e2e-hello' } }),
+    });
+    await new Promise((r) => setTimeout(r, 400));
+    check('SSE receives lock.granted', events.some((e) => e.type === 'lock.granted'), JSON.stringify(events.slice(0, 2)));
+    check('SSE receives peer.ping', events.some((e) => e.type === 'peer.ping'));
+    ac.abort();
+    await sseDone;
+  } finally {
+    server.close();
+  }
+}
+
+// ?? 9-11: shim runner ???????????????????????????????????????????????????????
+section('shim runner');
+
+// Parent-held FS blocker helpers (distinct pid from the shim subprocess).
+let blockerHandle = null;
+function tryAcquireFsBlocker(dir) {
+  const r = tryAcquireWsLock(dirScope(dir), 'exclusive', { label: 'blocker' });
+  if (r.ok) blockerHandle = r.handle;
+  return r.ok;
+}
+function releaseFsBlocker() {
+  releaseWsLock(blockerHandle);
+  blockerHandle = null;
+}
+{
+  const runner = join(DIST, 'lib/workspace/shim-runner.js');
+  const env = {
+    ...process.env,
+    TS_AGENT_ID: 'e2e-agent',
+    TS_SESSION_KIND: 'task',
+    TS_SHIM_WAIT_MS: '1500',
+  };
+
+  // 9a: passthrough commands never touch locks.
+  const pt = spawnSync(process.execPath, [runner, 'node', '-e', 'console.log("passthrough-ok")'], {
+    cwd: workDir, encoding: 'utf8', env,
+  });
+  check('passthrough executes directly', pt.stdout.includes('passthrough-ok') && pt.status === 0);
+
+  // 9b: fail-open when the lock root is unusable (a file where a dir must be).
+  const badRootFile = join(stateRoot, 'not-a-dir');
+  writeFileSync(badRootFile, 'x');
+  const fo = spawnSync(
+    process.execPath,
+    [runner, 'npm', 'run', 'build'],
+    { cwd: workDir, encoding: 'utf8', env: { ...env, TS_WS_LOCK_ROOT: badRootFile }, timeout: 120_000 },
+  );
+  const reachedNpm =
+    (fo.stderr ?? '').includes('arbitration skipped') ||
+    (fo.stderr ?? '').includes('Missing script') ||
+    (fo.stdout ?? '').includes('Missing script');
+  check('broken lock root -> fail-open runs npm', reachedNpm, `exit=${fo.status}`);
+
+  // 10: exclusive hold blocks shim npm build (fail-closed exit 124)...
+  const held = tryAcquireFsBlocker(workDir);
+  check('test blocker acquired', held === true);
+  const dumpTree = () => {
+    const out = [];
+    const walk = (d, pfx) => {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        const fp = join(d, e.name);
+        if (e.isDirectory()) walk(fp, `${pfx}${e.name}/`);
+        else out.push(pfx + e.name);
+      }
+    };
+    try {
+      walk(process.env.TS_WS_LOCK_ROOT, '');
+    } catch {
+      /* root missing */
+    }
+    return out;
+  };
+  console.log('    [diag] lock tree while blocked:', JSON.stringify(dumpTree()));
+  const blocked = spawnSync(
+    process.execPath,
+    [runner, 'npm', 'run', 'build'],
+    { cwd: workDir, encoding: 'utf8', env, timeout: 60_000 },
+  );
+  check('shim waits and exits 124 on busy workspace', blocked.status === 124, `exit=${blocked.status}`);
+  console.log('    [diag] blocked stderr head:', (blocked.stderr ?? '').slice(0, 500).replace(/\n/g, ' | '));
+  check('timeout note explains refusal', (blocked.stderr ?? '').includes('NOT running'), (blocked.stderr ?? '').slice(-160));
+  releaseFsBlocker();
+
+  // ...then proceeds to the REAL npm once released.
+  const freed = spawnSync(
+    process.execPath,
+    [runner, 'npm', 'run', 'build'],
+    { cwd: workDir, encoding: 'utf8', env, timeout: 120_000 },
+  );
+  const ranNpm =
+    (freed.stderr ?? '').includes('Missing script') ||
+    (freed.stdout ?? '').includes('Missing script') ||
+    (freed.stderr ?? '').includes('npm error');
+  check('after release shim reaches real npm', ranNpm && freed.status !== 124, `exit=${freed.status}`);
+}
+
+// Nested bypass: parent holds the scope; shim with TS_WS_HELD skips locking.
+section('nested TS_WS_HELD bypass');
+{
+  const { scopeKey } = await import(distUrl('lib/workspace/repo-lock.js'));
+  const key = scopeKey(dirScope(workDir));
+  const ok = tryAcquireFsBlocker(workDir);
+  check('parent holds scope', ok === true);
+  const nested = spawnSync(
+    process.execPath,
+    [join(DIST, 'lib/workspace/shim-runner.js'), 'npm', 'install', '--dry-run'],
+    {
+      cwd: workDir,
+      encoding: 'utf8',
+      timeout: 120_000,
+      env: { ...process.env, TS_WS_HELD: key },
+    },
+  );
+  check('nested shim bypasses parent hold (no 124)', nested.status !== 124, `exit=${nested.status}`);
+  releaseFsBlocker();
+}
+
+// ?? cleanup ?????????????????????????????????????????????????????????????????
+try {
+  rmSync(stateRoot, { recursive: true, force: true });
+  rmSync(workDir, { recursive: true, force: true });
+} catch {
+  /* best-effort */
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail > 0 ? 1 : 0);