@bongos/core 1.19.836 → 1.19.838

package/tests/runner_drift.mjs

@@ -0,0 +1,173 @@
+// tests/runner_drift.mjs — the intent-runner drift gate (task 1002722).
+//
+// The incident: for weeks the prod intent runners ran core 1.19.2 from a retired clone while
+// the instance served a current core, so an owner's domain-attach click executed as a
+// TEARDOWN (task 1002716). The hotfix repointed the units with systemd drop-ins. These cases
+// pin the reading of a unit the way systemd reads it (a drop-in overrides the base file) and
+// the version comparison, against a fake filesystem shaped like the live box.
+//
+// Run:  node tests/runner_drift.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { effectiveUnit, runnerScriptPath, coreVersionFor, installedCoreVersion, assessRunnerUnit, parseUnitList, runnerBanner } from '../scripts/gds/runner-drift.js';
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The live selfhost unit as `systemctl cat` prints it (2026-09-17): base file + drop-in.
+const LIVE_CAT = `# /etc/systemd/system/selfhost-provision-intent-runner.service
+[Service]
+Type=oneshot
+WorkingDirectory=/home/lars/cloudbongos
+EnvironmentFile=/etc/cloudbongos/box.env
+ExecStart=/usr/bin/env bash infra/core-node.sh scripts/gds/provision.js run-intents --apply
+
+# /etc/systemd/system/selfhost-provision-intent-runner.service.d/override.conf
+[Service]
+WorkingDirectory=/home/lars/cloudbongos-instance
+ExecStart=
+ExecStart=/usr/bin/node node_modules/@bongos/core/scripts/gds/provision.js run-intents --apply
+`;
+
+// A fake fs: path → file body. Only readFileSync + existsSync are used.
+function fakeFs(files) {
+  return {
+    existsSync: (p) => Object.prototype.hasOwnProperty.call(files, p),
+    readFileSync: (p) => { if (!(p in files)) { const e = new Error(`ENOENT ${p}`); e.code = 'ENOENT'; throw e; } return files[p]; },
+  };
+}
+const pkg = (name, version) => JSON.stringify({ name, version });
+const INSTANCE = '/home/lars/cloudbongos-instance';
+const boxFs = (installed, runnerPkg = installed) => fakeFs({
+  [`${INSTANCE}/node_modules/@bongos/core/package.json`]: pkg('@bongos/core', installed),
+  [`${INSTANCE}/package.json`]: pkg('cloudbongos-instance', '0.0.1'),
+  ...(runnerPkg !== installed ? { '/opt/other/node_modules/@bongos/core/package.json': pkg('@bongos/core', runnerPkg) } : {}),
+  '/home/lars/cloudbongos/src/module-api.js': "const CORE_VERSION = '1.19.2'; // old clone\n",
+  '/home/lars/cloudbongos/package.json': pkg('cloud-bongos', '0.0.2'),
+});
+
+t('effectiveUnit: a drop-in WorkingDirectory wins, and an empty ExecStart= resets the base one', () => {
+  assert.deepEqual(effectiveUnit(LIVE_CAT), {
+    workingDirectory: INSTANCE,
+    execStarts: ['/usr/bin/node node_modules/@bongos/core/scripts/gds/provision.js run-intents --apply'],
+  });
+});
+
+t('effectiveUnit: with no drop-in the base file stands (the pre-hotfix shape)', () => {
+  const base = LIVE_CAT.split('# /etc/systemd/system/selfhost-provision-intent-runner.service.d')[0];
+  const u = effectiveUnit(base);
+  assert.equal(u.workingDirectory, '/home/lars/cloudbongos');
+  assert.equal(u.execStarts.length, 1);
+  assert.match(u.execStarts[0], /infra\/core-node\.sh/);
+});
+
+t('assessRunnerUnit: a drop-in that ADDS an ExecStart without clearing leaves the stale base command running — never ok', () => {
+  const cat = LIVE_CAT.replace('ExecStart=\nExecStart=/usr/bin/node', 'ExecStart=/usr/bin/node')
+    .replace('ExecStart=/usr/bin/env bash infra/core-node.sh scripts/gds/provision.js run-intents --apply', 'ExecStart=/usr/bin/node /home/lars/cloudbongos/scripts/gds/provision.js run-intents --apply');
+  assert.equal(effectiveUnit(cat).execStarts.length, 2);
+  const r = assessRunnerUnit({ name: 'x', catText: cat, instanceRoot: INSTANCE, fsImpl: boxFs('1.19.831') });
+  assert.equal(r.status, 'drift', r.reason);
+  assert.match(r.reason, /1\.19\.2/);
+});
+
+t('runnerScriptPath: node + a relative script resolves against WorkingDirectory; a wrapper resolves to null', () => {
+  assert.equal(runnerScriptPath({ workingDirectory: INSTANCE, execStart: '/usr/bin/node node_modules/@bongos/core/scripts/gds/provision.js run-intents --apply' }),
+    `${INSTANCE}/node_modules/@bongos/core/scripts/gds/provision.js`);
+  assert.equal(runnerScriptPath({ workingDirectory: '/w', execStart: '/usr/bin/env node /abs/core/scripts/gds/box.js run-intents' }), '/abs/core/scripts/gds/box.js');
+  assert.equal(runnerScriptPath({ workingDirectory: '/w', execStart: '-/usr/bin/node scripts/gds/box.js' }), '/w/scripts/gds/box.js', 'systemd exec prefixes are stripped');
+  assert.equal(runnerScriptPath({ workingDirectory: '/w', execStart: '/usr/bin/env NODE_ENV=production node --max-old-space-size=512 scripts/gds/box.js' }), '/w/scripts/gds/box.js', 'env assignments and node flags are skipped');
+  assert.equal(runnerScriptPath({ workingDirectory: '/w', execStart: '/usr/bin/env bash infra/core-node.sh scripts/gds/provision.js' }), null,
+    'a shell wrapper decides at runtime which core it loads — the gate must not guess');
+});
+
+t('coreVersionFor: an installed package reads its package.json; a source checkout reads CORE_VERSION', () => {
+  const fs = boxFs('1.19.831');
+  assert.equal(coreVersionFor(`${INSTANCE}/node_modules/@bongos/core/scripts/gds/provision.js`, { fsImpl: fs }), '1.19.831');
+  assert.equal(coreVersionFor('/home/lars/cloudbongos/scripts/gds/provision.js', { fsImpl: fs }), '1.19.2');
+  assert.equal(coreVersionFor('/nowhere/scripts/gds/provision.js', { fsImpl: fs }), null);
+});
+
+t('installedCoreVersion: reads <root>/node_modules/@bongos/core; null when absent', () => {
+  assert.equal(installedCoreVersion(INSTANCE, { fsImpl: boxFs('1.19.831') }), '1.19.831');
+  assert.equal(installedCoreVersion('/empty', { fsImpl: boxFs('1.19.831') }), null);
+});
+
+t('assessRunnerUnit: the live drop-in shape is ok', () => {
+  const r = assessRunnerUnit({ name: 'selfhost-provision-intent-runner.service', catText: LIVE_CAT, instanceRoot: INSTANCE, fsImpl: boxFs('1.19.831') });
+  assert.equal(r.status, 'ok', r.reason);
+  assert.equal(r.runnerVersion, '1.19.831');
+});
+
+t('assessRunnerUnit: a unit running a source clone on another core is DRIFT, naming both versions', () => {
+  const cat = LIVE_CAT.replace(/ExecStart=\/usr\/bin\/node node_modules[^\n]*/, 'ExecStart=/usr/bin/node /home/lars/cloudbongos/scripts/gds/provision.js run-intents --apply');
+  const r = assessRunnerUnit({ name: 'x.service', catText: cat, instanceRoot: INSTANCE, fsImpl: boxFs('1.19.831') });
+  assert.equal(r.status, 'drift');
+  assert.match(r.reason, /1\.19\.2/);
+  assert.match(r.reason, /1\.19\.831/);
+});
+
+t('assessRunnerUnit: a wrapper, or a version it cannot read, is UNRESOLVED — never reported as ok', () => {
+  const base = LIVE_CAT.split('# /etc/systemd/system/selfhost-provision-intent-runner.service.d')[0];
+  assert.equal(assessRunnerUnit({ name: 'x', catText: base, instanceRoot: INSTANCE, fsImpl: boxFs('1.19.831') }).status, 'unresolved');
+  assert.equal(assessRunnerUnit({ name: 'x', catText: LIVE_CAT, instanceRoot: '/empty', fsImpl: boxFs('1.19.831') }).status, 'unresolved');
+  assert.equal(assessRunnerUnit({ name: 'x', catText: '', instanceRoot: INSTANCE, fsImpl: boxFs('1.19.831') }).status, 'unresolved');
+});
+
+t('parseUnitList: plain list-units output → service names only', () => {
+  const out = 'cohost-provision-intent-runner.service loaded inactive dead Cloud Bongos — drain\nselfhost-provision-intent-runner.service loaded inactive dead x\n\n';
+  assert.deepEqual(parseUnitList(out), ['cohost-provision-intent-runner.service', 'selfhost-provision-intent-runner.service']);
+  assert.deepEqual(parseUnitList(''), []);
+});
+
+t('runnerBanner: names the runner core + path, and flags a differing instance core', () => {
+  assert.equal(runnerBanner({ runnerVersion: '1.19.831', runnerRoot: '/r', instanceVersion: '1.19.831', instanceRoot: '/i' }),
+    'runner core 1.19.831 from /r (instance core 1.19.831 at /i)');
+  assert.match(runnerBanner({ runnerVersion: '1.19.2', runnerRoot: '/r', instanceVersion: '1.19.831', instanceRoot: '/i' }), /^⚠ DRIFT: runner core 1\.19\.2 from \/r \(instance core 1\.19\.831 at \/i\)/);
+  assert.equal(runnerBanner({ runnerVersion: null, runnerRoot: '/r', instanceVersion: null, instanceRoot: '/i' }), 'runner core ? from /r (no installed core at /i)');
+});
+
+// box.js run-intents is the other runner the incident class covers — it opens with the same line.
+const { cmdRunIntents: boxRunIntents } = await import('../scripts/gds/box.js');
+{
+  const lines = [];
+  const origLog = console.log;
+  const origRoot = process.env.BONGOS_INSTANCE_ROOT;
+  process.env.BONGOS_INSTANCE_ROOT = '/no/such/instance';
+  console.log = (l) => lines.push(String(l));
+  try { await boxRunIntents({ query: async () => ({ rows: [] }) }, {}, null, { apply: false }); }
+  finally {
+    console.log = origLog;
+    if (origRoot === undefined) delete process.env.BONGOS_INSTANCE_ROOT; else process.env.BONGOS_INSTANCE_ROOT = origRoot;
+  }
+  t('box.js run-intents opens with the runner core version line', () => {
+    assert.match(lines[0], /^runner core \d+\.\d+\.\d+ from .+ \(no installed core at \/no\/such\/instance\)$/);
+  });
+}
+
+const { runnerDriftRows } = await import('../scripts/gds/doctor.js');
+
+t('doctor maps each verdict to a row: ok → ok, drift → FAIL with the fix, unresolved → warn', () => {
+  const rows = runnerDriftRows([
+    { name: 'a.service', status: 'ok', reason: 'runs core 1.19.831' },
+    { name: 'b.service', status: 'drift', reason: 'runs core 1.19.2 (/x) but the instance installed 1.19.831 at /i' },
+    { name: 'c.service', status: 'unresolved', reason: 'ExecStart does not run a .js script directly' },
+  ]);
+  assert.deepEqual(rows.map((r) => r.status), ['ok', 'fail', 'warn']);
+  assert.equal(rows[0].msg, 'a.service: runs core 1.19.831');
+  assert.match(rows[1].msg, /^b\.service: runs core 1\.19\.2 .* — repoint the unit's WorkingDirectory \+ ExecStart at the installed core/);
+  assert.equal(rows[2].msg, 'c.service: ExecStart does not run a .js script directly');
+  assert.deepEqual(runnerDriftRows(null), [], 'no systemd → no rows, so a laptop shows no section');
+  assert.deepEqual(runnerDriftRows([]), []);
+});
+
+t('doctor runs the runner-drift probe', () => {
+  const src = readFileSync(new URL('../scripts/gds/doctor.js', import.meta.url), 'utf8');
+  assert.match(src.slice(src.indexOf('require.main === module')), /checkRunnerDrift\(\)/);
+});
+
+console.log(`\nrunner_drift: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/stuck_detector.mjs

@@ -0,0 +1,233 @@
+// tests/stuck_detector.mjs — the stuck detector (task 1003990): a session that hits the
+// same wall three times is told, once per further hit, to stop retrying and diagnose or
+// ask. Three repeat kinds share one strike counter (.claude/hooks/stuck-strikes.js):
+//   - the same refused claim      → stuck-detector.js, keyed on the [otb-plain] card
+//   - the same red check          → stuck-detector.js, keyed on the card + the RED line
+//   - the same guard block        → git-guard.js / worktree-guard.js call the counter
+// The hooks are SPAWNED for the contract that matters to Claude Code (exit code, stdout
+// JSON, stderr); the pure parsing is called in-process.
+//
+// .claude/hooks/ is package-excluded, so a clean core checkout skips this file
+// (tests/host_topology_skips.mjs carries the allowlist entry).
+//
+// Run:  node tests/stuck_detector.mjs
+
+import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { requireHostModule } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const strikes = requireHostModule(require, '../.claude/hooks/stuck-strikes.js');
+const detector = require('../.claude/hooks/stuck-detector.js');
+const { plainCardLines, CARDS } = require('../scripts/gds/plain-cards.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// Every spawned hook counts into a throwaway dir, never the real os.tmpdir().
+const DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'stuck-detector-'));
+const ENV = { ...process.env, OTB_STUCK_DIR: DIR, BONGOS_STUCK_DETECTOR_OFF: '', BONGOS_GIT_GUARD_OFF: '', OTB_ALLOW_CROSS_TREE: '' };
+const hookPath = (name) => path.join(ROOT, '.claude', 'hooks', `${name}.js`);
+function run(name, payload, env = {}) {
+  const r = spawnSync(process.execPath, [hookPath(name)], { input: JSON.stringify(payload), encoding: 'utf8', timeout: 15000, env: { ...ENV, ...env } });
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+const injected = (r) => (r.stdout.trim() ? JSON.parse(r.stdout).hookSpecificOutput.additionalContext : '');
+const card = (code) => plainCardLines(code, {}).join('\n');
+const bash = (session, command, output, extra = {}) => ({ session_id: session, tool_name: 'Bash', tool_input: { command }, tool_response: { stdout: output, stderr: '' }, ...extra });
+
+// ---- pure: reading the card ------------------------------------------------
+t('parsePlainCards reads each card and whether it is a rule', () => {
+  const cards = detector.parsePlainCards(`engineer text\n${card('REBASE_REQUIRED')}\nmore\n${card('failing_check')}`);
+  assert.equal(cards.length, 2);
+  assert.equal(cards[0].happened, CARDS.REBASE_REQUIRED.happened);
+  assert.equal(cards[0].byDesign, true);
+  assert.equal(cards[1].byDesign, false);
+});
+
+t('a waiting card ("Nothing to do…") is not a wall — polling it is what its card says to do', () => {
+  const waiting = Object.keys(CARDS).filter((k) => detector.isWaitingCard({ next: CARDS[k].next }));
+  assert.deepEqual(waiting.sort(), ['blocked_required_review_or_pending_check', 'land_pending', 'mergeability_computing', 'non_required_check_pending', 'request_pending']);
+});
+
+t('the task id is the one the CLI was handed, not any number on the line', () => {
+  const id = (cmd) => detector.wallsIn(cmd, card('TASK_NOT_READY')).taskId;
+  assert.equal(id('node scripts/gds/claim.js 1003990 --worktree task-1003990'), '1003990');
+  assert.equal(id('node scripts/gds/claim.js --worktree task-1003990 1003990'), '1003990');
+  assert.equal(id('cd "C:/x y/task-77" && node "C:/x y/scripts/gds/ship.js" --regrade 1003848 --notes "3 of 404 pages"'), '1003848');
+  assert.equal(id('bongos claim 7'), '7', 'a fresh instance numbers its tasks from 1');
+  assert.equal(id('timeout 120 node scripts/gds/start.js'), '');
+});
+
+t('only a builder CLI run can hit a wall — reading a file that quotes a card cannot', () => {
+  for (const cmd of ['cat docs/session-logs/x.md', 'git diff', 'grep -A5 otb-plain tests/stuck_detector.mjs', 'cat scripts/gds/claim.js | node -e ""']) {
+    assert.deepEqual(detector.wallsIn(cmd, card('REBASE_REQUIRED')).walls, [], cmd);
+  }
+  assert.equal(detector.wallsIn('node node_modules/@cloudbongos/core/scripts/gds/claim.js 5', card('REBASE_REQUIRED')).walls.length, 1);
+});
+
+t('parallel hook processes cannot wipe each other: the counter is append-only', () => {
+  const src = fs.readFileSync(hookPath('stuck-strikes'), 'utf8');
+  assert.match(src, /appendFileSync/);
+  assert.ok(!/writeFileSync/.test(src), 'a read-modify-write would let one hook reset another\'s counts');
+});
+
+t('recordStrike counts per session and per signature, and never throws', () => {
+  assert.equal(strikes.recordStrike('s-unit', 'a', DIR), 1);
+  assert.equal(strikes.recordStrike('s-unit', 'a', DIR), 2);
+  assert.equal(strikes.recordStrike('s-unit', 'b', DIR), 1);
+  assert.equal(strikes.recordStrike('s-other', 'a', DIR), 1);
+  assert.equal(strikes.recordStrike('', 'a', DIR), 0, 'no session id → cannot count → quiet');
+  assert.equal(strikes.recordStrike('s-unit', 'a', path.join(DIR, 'missing', 'dir')), 0, 'unwritable dir → quiet');
+});
+
+// ---- kind 1: the same refused claim ----------------------------------------
+t('the same refused claim: silent twice, one instruction on the third', () => {
+  const out = `Claim refused: 409 REBASE_REQUIRED\n${card('REBASE_REQUIRED')}`;
+  const p = bash('s-claim', 'node scripts/gds/claim.js 1003848 --worktree task-1003848', out);
+  for (let i = 0; i < 2; i++) {
+    const r = run('stuck-detector', p);
+    assert.equal(r.status, 0);
+    assert.equal(r.stdout, '', `strike ${i + 1} must be silent`);
+  }
+  const third = run('stuck-detector', p);
+  assert.equal(third.status, 0, 'never blocks: exit 0 even when it speaks');
+  const ctx = injected(third);
+  assert.match(ctx, /\[otb-stuck\]/);
+  assert.match(ctx, /3 times/);
+  assert.match(ctx, /rule, not a fault/);
+  assert.match(ctx, /\/ask-for-help/);
+  assert.ok(!ctx.includes(CARDS.REBASE_REQUIRED.happened), 'static text only — tool output is never echoed back');
+});
+
+t('a different task id is a different wall', () => {
+  const out = card('ALREADY_CLAIMED');
+  for (const id of ['2001', '2002', '2003']) {
+    assert.equal(run('stuck-detector', bash('s-ids', `node scripts/gds/claim.js ${id}`, out)).stdout, '');
+  }
+});
+
+// ---- kind 2: the same red check on the same branch -------------------------
+t('the same red check: third identical RED names the diagnostic path', () => {
+  const red = '  ci-land: the PR is RED — tests/security.mjs failed. Reproduce with `node tests/<name>.mjs`, fix it';
+  const out = `${red}\n${card('failing_check')}\n${card('land_pending')}`;
+  const p = bash('s-red', 'node scripts/gds/ship.js 1003848 --notes x --summary y', out);
+  run('stuck-detector', p); run('stuck-detector', p);
+  const ctx = injected(run('stuck-detector', p));
+  assert.match(ctx, /same failure 3 times/);
+  assert.match(ctx, /publish-status/);
+  assert.match(ctx, /1003848/);
+});
+
+t('a red check that names DIFFERENT failing tests each time is progress, not a wall', () => {
+  for (const name of ['a', 'b', 'c']) {
+    const out = `  ci-land: the PR is RED — tests/${name}.mjs failed.\n${card('failing_check')}`;
+    assert.equal(run('stuck-detector', bash('s-progress', 'node scripts/gds/ship.js 77001', out)).stdout, '');
+  }
+});
+
+t('resultText reads the output from whichever field the harness used', () => {
+  assert.equal(detector.resultText({ tool_response: { stdout: 'a', stderr: 'b' } }), 'a\nb');
+  assert.equal(detector.resultText({ tool_output: { output: 'c', exit_code: 1 } }), 'c');
+  assert.equal(detector.resultText({ tool_response: 'd', error_message: 'e', error: 'f' }), 'd\nf\ne');
+  assert.equal(detector.resultText({ tool_response: 42, error: null }), '');
+});
+
+// A refusal exits non-zero; whether that routes to PostToolUse or PostToolUseFailure is
+// the harness's business, so the hook is wired on both and answers as whichever fired.
+t('a failed tool call (PostToolUseFailure: error_message, no tool_response) still counts', () => {
+  const p = { session_id: 's-fail', hook_event_name: 'PostToolUseFailure', tool_name: 'PowerShell', tool_input: { command: 'node scripts/gds/claim.js 555' }, error_message: `exit 1\n${card('DEPS_NOT_SHIPPED')}` };
+  run('stuck-detector', p); run('stuck-detector', p);
+  const r = run('stuck-detector', p);
+  assert.match(JSON.parse(r.stdout).hookSpecificOutput.hookEventName, /^PostToolUseFailure$/);
+  assert.match(injected(r), /\[otb-stuck\]/);
+});
+
+// ---- kind 3: the same command blocked by a guard ---------------------------
+t('git-guard: the third block of the same rule appends the instruction; the block itself is unchanged', () => {
+  const p = { session_id: 's-git', tool_name: 'Bash', tool_input: { command: 'git stash' } };
+  for (let i = 0; i < 2; i++) {
+    const r = run('git-guard', p);
+    assert.equal(r.status, 2);
+    assert.ok(!r.stderr.includes('[otb-stuck]'), `block ${i + 1} carries no nudge`);
+  }
+  const third = run('git-guard', { ...p, tool_input: { command: 'git stash push -m again' } });
+  assert.equal(third.status, 2);
+  assert.match(third.stderr, /git-guard: blocked/);
+  assert.match(third.stderr, /\[otb-stuck\]/);
+  assert.match(third.stderr, /remedy/i);
+});
+
+t('worktree-guard: the same wrong-tree file three times appends the instruction to the deny reason', () => {
+  // The guard resolves its roots from git, so the spawned case needs a real linked
+  // worktree; from the main checkout (CI) the in-process case below carries it.
+  const common = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: ROOT, encoding: 'utf8' }).stdout.trim();
+  const mainRoot = path.dirname(common);
+  const guard = require('../.claude/hooks/worktree-guard.js');
+  const deny = { deny: true, reason: 'Wrong git checkout.' };
+  assert.equal(guard.withStuckNudge(deny, 's-wt-pure', '/repo/server.js', ENV).reason, deny.reason);
+  assert.equal(guard.withStuckNudge(deny, 's-wt-pure', '/repo/server.js', ENV).reason, deny.reason);
+  assert.match(guard.withStuckNudge(deny, 's-wt-pure', '/repo/server.js', ENV).reason, /^Wrong git checkout\.\n\[otb-stuck\]/);
+  if (!common || path.resolve(mainRoot) === path.resolve(ROOT)) return;
+  const p ={ session_id: 's-wt', cwd: ROOT, tool_name: 'Edit', tool_input: { file_path: path.join(mainRoot, 'server.js') } };
+  const reason = (r) => JSON.parse(r.stdout).hookSpecificOutput.permissionDecisionReason;
+  assert.ok(!reason(run('worktree-guard', p)).includes('[otb-stuck]'));
+  assert.ok(!reason(run('worktree-guard', p)).includes('[otb-stuck]'));
+  const third = run('worktree-guard', p);
+  assert.equal(third.status, 0);
+  assert.match(reason(third), /Wrong git checkout/);
+  assert.match(reason(third), /\[otb-stuck\]/);
+});
+
+// ---- the quiet path --------------------------------------------------------
+t('quiet on a clean run: no card → exit 0, no stdout, no stderr, nothing written', () => {
+  const before = fs.readdirSync(DIR).length;
+  for (const p of [
+    bash('s-quiet', 'node scripts/gds/claim.js 1003990', 'Claimed task 1003990\n[otb-confirm] claimed'),
+    bash('s-quiet', 'npm test', 'FAIL tests/x.mjs'),
+    { session_id: 's-quiet', tool_name: 'Read', tool_input: { file_path: 'x' } },
+    {},
+  ]) {
+    const r = run('stuck-detector', p);
+    assert.deepEqual([r.status, r.stdout, r.stderr], [0, '', '']);
+  }
+  assert.equal(fs.readdirSync(DIR).length, before);
+});
+
+t('malformed stdin fails open and silent', () => {
+  for (const raw of ['', 'not json', '{"tool_name":"Bash",']) {
+    const r = spawnSync(process.execPath, [hookPath('stuck-detector')], { input: raw, encoding: 'utf8', env: ENV });
+    assert.deepEqual([r.status, r.stdout, r.stderr], [0, '', '']);
+  }
+});
+
+t('kill-switch: BONGOS_STUCK_DETECTOR_OFF=1 silences the detector and the guard nudges', () => {
+  const p = bash('s-off', 'node scripts/gds/claim.js 9', card('TASK_NOT_READY'));
+  for (let i = 0; i < 4; i++) assert.equal(run('stuck-detector', p, { BONGOS_STUCK_DETECTOR_OFF: '1' }).stdout, '');
+  const g = { session_id: 's-off-git', tool_name: 'Bash', tool_input: { command: 'git branch -D x' } };
+  for (let i = 0; i < 4; i++) assert.ok(!run('git-guard', g, { BONGOS_STUCK_DETECTOR_OFF: '1' }).stderr.includes('[otb-stuck]'));
+});
+
+t('wired in .claude/settings.json through run-node.sh, on both tool-result events', () => {
+  const settings = JSON.parse(fs.readFileSync(path.join(ROOT, '.claude', 'settings.json'), 'utf8'));
+  for (const event of ['PostToolUse', 'PostToolUseFailure']) {
+    const cmds = (settings.hooks[event] || []).flatMap((g) => g.hooks.map((h) => h.command));
+    const mine = cmds.filter((c) => c.includes('stuck-detector.js'));
+    assert.equal(mine.length, 1, `${event}: expected exactly one stuck-detector entry`);
+    assert.match(mine[0], /run-node\.sh/);
+  }
+});
+
+fs.rmSync(DIR, { recursive: true, force: true });
+console.log(`\nstuck_detector: ${passed} passed, ${failed} failed`);
+process.exitCode = failed ? 1 : 0;