nubos-pilot 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to nubos-pilot are documented in this file. Format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
 follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.4] - 2026-06-15
+
+Fixed a recursion fault in the in-session hooks that could spawn an unbounded cascade of headless `claude -p` processes.
+
+- The Stop-hook security review and continuous-learning capture each spawn a headless `claude -p` to do their work. That headless run re-fires the same SessionStart/Stop hooks, which spawned another headless run, and so on — a fork bomb of `claude`, `np-tools` and duplicated MCP servers that survived closing the terminal. nubos-pilot now marks every headless spawn with `NUBOS_PILOT_HEADLESS=1` and a `NUBOS_PILOT_HOOK_DEPTH` counter; the hooks no-op immediately inside a headless run, so the chain stops at exactly one level.
+- Three independent guards back this up: the hook scripts and the `security`/`learnings` backends exit early when `NUBOS_PILOT_HEADLESS` is set; `spawn-headless` refuses to start a nested headless run (reentrancy + depth cap, default one level); and a per-agent lockfile under `.nubos-pilot/run/` bounds concurrent headless runs to one per agent even if the environment is not inherited. Headless runs already carry a hard timeout with SIGKILL, so a hung review cannot linger.
+- Escape hatch: the guard keys off `NUBOS_PILOT_HEADLESS`, set automatically on the spawned `claude` — do not set it in your own shell or the in-session hooks will silently no-op. Raise the depth cap with `NUBOS_PILOT_MAX_HOOK_DEPTH` only if you understand the recursion risk.
+
 ## [1.2.3] — 2026-06-14
 
 Three opt-in layers that make execution cheaper, more reliable, and self-improving.

package/README.md

@@ -169,6 +169,22 @@ load-bearing ones for users and contributors:
 See [`SECURITY.md`](./SECURITY.md) for the vulnerability disclosure policy
 and threat model.
 
+### Headless recursion guard
+
+The in-session security review and continuous-learning hooks do their work in
+a headless `claude -p` subprocess. To stop that subprocess from re-firing the
+same hooks (which would cascade into an unbounded fork of `claude`/`np-tools`
+processes), nubos-pilot sets `NUBOS_PILOT_HEADLESS=1` and a
+`NUBOS_PILOT_HOOK_DEPTH` counter on every headless spawn. The hooks no-op when
+`NUBOS_PILOT_HEADLESS` is set, `spawn-headless` refuses a nested or
+depth-exceeded spawn, and a per-agent lockfile under `.nubos-pilot/run/` bounds
+concurrent headless runs to one per agent.
+
+The guard is automatic — do not export `NUBOS_PILOT_HEADLESS` in your own
+shell, or the in-session hooks will silently do nothing. The depth cap is one
+level; override it with `NUBOS_PILOT_MAX_HOOK_DEPTH` only if you understand the
+recursion risk.
+
 ## Support
 
 - Bugs / features: [GitHub issues](https://github.com/Nubos-AI/nubos-pilot/issues)

package/bin/np-tools/learnings.cjs

@@ -6,6 +6,7 @@ const child_process = require('node:child_process');
 const { tryReadConfigPath } = require('../../lib/config.cjs');
 const ledger = require('../../lib/learnings/capture-ledger.cjs');
 const extract = require('../../lib/learnings/extract.cjs');
+const headlessGuard = require('../../lib/headless-guard.cjs');
 const args = require('./_args.cjs');
 
 function _readStdin() {
@@ -60,6 +61,9 @@ async function run(argv, ctx) {
   const stdout = context.stdout || process.stdout;
   const list = Array.isArray(argv) ? argv : [];
   const verb = list[0];
+
+  if (headlessGuard.isHeadless(process.env)) return 0;
+
   const cfg = _cfg(cwd);
 
   // 'reset' (UserPromptSubmit) and 'run-extract' (background worker) are not

package/bin/np-tools/security.cjs

@@ -8,6 +8,7 @@ const { tryReadConfigPath } = require('../../lib/config.cjs');
 const scan = require('../../lib/security/scan.cjs');
 const ledger = require('../../lib/security/ledger.cjs');
 const review = require('../../lib/security/review.cjs');
+const headlessGuard = require('../../lib/headless-guard.cjs');
 const args = require('./_args.cjs');
 
 const COMMIT_RE = /\bgit\b[\s\S]*\b(commit|push)\b/;
@@ -93,6 +94,8 @@ async function run(argv, ctx) {
   const list = Array.isArray(argv) ? argv : [];
   const verb = list[0];
 
+  if (headlessGuard.isHeadless(process.env)) return 0;
+
   const cfg = _cfg(cwd);
   if (!cfg.enabled && verb !== 'run-review') return 0;
 

package/bin/np-tools/spawn-headless.cjs

@@ -8,6 +8,7 @@ const child_process = require('node:child_process');
 const { NubosPilotError, atomicWriteFileSync, appendJsonl, findProjectRoot } = require('../../lib/core.cjs');
 const runContext = require('../../lib/run-context.cjs');
 const safePath = require('../../lib/safe-path.cjs');
+const headlessGuard = require('../../lib/headless-guard.cjs');
 const args = require('./_args.cjs');
 
 function _sha256(s) {
@@ -171,6 +172,22 @@ function run(argv, ctx) {
   const stdout = context.stdout || process.stdout;
   const list = Array.isArray(argv) ? argv : [];
 
+  if (headlessGuard.isHeadless(process.env)) {
+    throw new NubosPilotError(
+      'spawn-headless-reentrant',
+      'refusing to spawn a nested headless `claude` (NUBOS_PILOT_HEADLESS is set) — recursion guard',
+      { depth: headlessGuard.currentDepth(process.env) },
+    );
+  }
+  if (headlessGuard.depthExceeded(process.env)) {
+    throw new NubosPilotError(
+      'spawn-headless-depth-exceeded',
+      'refusing to spawn headless `claude`: hook depth ' + headlessGuard.currentDepth(process.env)
+        + ' has reached the cap ' + headlessGuard.maxDepth(process.env) + ' (recursion guard)',
+      { depth: headlessGuard.currentDepth(process.env), max: headlessGuard.maxDepth(process.env) },
+    );
+  }
+
   const agent = args.getFlag(list, '--agent');
   if (!agent) {
     throw new NubosPilotError(
@@ -213,6 +230,21 @@ function run(argv, ctx) {
 
   const runId = runContext.getRunId();
 
+  let lockRoot;
+  try { lockRoot = findProjectRoot(cwd); }
+  catch { lockRoot = cwd; }
+  const lock = headlessGuard.tryAcquireSpawnLock(lockRoot, agent);
+  if (!lock.acquired) {
+    throw new NubosPilotError(
+      'spawn-headless-locked',
+      'another headless run for agent `' + agent + '` is already active in this project (concurrency guard)',
+      { agent, holder: lock.holder || null },
+    );
+  }
+
+  const childEnv = _filterSpawnEnv(process.env);
+  Object.assign(childEnv, headlessGuard.childSpawnEnv(process.env));
+
   const bin = _claudeBinary();
   const claudeArgs = ['-p', '--output-format', 'json'];
   const startedAt = new Date().toISOString();
@@ -224,7 +256,7 @@ function run(argv, ctx) {
       timeout: timeoutMs,
       maxBuffer: 64 * 1024 * 1024,
       encoding: 'utf-8',
-      env: _filterSpawnEnv(process.env),
+      env: childEnv,
       killSignal: 'SIGKILL',
     });
   } catch (err) {
@@ -233,6 +265,8 @@ function run(argv, ctx) {
       'failed to spawn `' + bin + '`: ' + (err && err.message),
       { bin, cause: err && err.code },
     );
+  } finally {
+    lock.release();
   }
   if (result.error && result.error.code === 'ENOENT') {
     throw new NubosPilotError(

package/bin/np-tools/spawn-headless.test.cjs

@@ -8,6 +8,14 @@ const assert = require('node:assert/strict');
 
 const spawnHeadless = require('./spawn-headless.cjs');
 const runContext = require('../../lib/run-context.cjs');
+const headlessGuard = require('../../lib/headless-guard.cjs');
+
+function _mockClaude(r, name, body) {
+  const p = path.join(r, name);
+  fs.writeFileSync(p, body, 'utf-8');
+  fs.chmodSync(p, 0o755);
+  return p;
+}
 
 const _sandboxes = [];
 const _envBackup = {};
@@ -488,6 +496,133 @@ test('SH-TRAIL-2 two sequential spawns append two parseable trail lines (jsonl i
   for (const l of lines) JSON.parse(l);
 });
 
+test('SH-GUARD-1 refuses to spawn when NUBOS_PILOT_HEADLESS=1 (reentrancy guard)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  _setEnv('NUBOS_PILOT_HEADLESS', '1');
+  const cap = _cap();
+  assert.throws(
+    () => spawnHeadless.run(
+      ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+      { cwd: r, stdout: cap.stub },
+    ),
+    (err) => err && err.code === 'spawn-headless-reentrant',
+  );
+  assert.equal(fs.existsSync(path.join(r, 'out.json')), false, 'no claude must be spawned inside a headless run');
+});
+
+test('SH-GUARD-2 refuses to spawn when hook depth has reached the cap (depth guard)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  _setEnv('NUBOS_PILOT_HOOK_DEPTH', '1');
+  const cap = _cap();
+  assert.throws(
+    () => spawnHeadless.run(
+      ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+      { cwd: r, stdout: cap.stub },
+    ),
+    (err) => err && err.code === 'spawn-headless-depth-exceeded',
+  );
+});
+
+test('SH-GUARD-3 child env carries NUBOS_PILOT_HEADLESS=1 and depth=1 (one level deep only)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh',
+    '#!/bin/sh\ncat > /dev/null\nprintf \'{"hl":"\'$NUBOS_PILOT_HEADLESS\'","depth":"\'$NUBOS_PILOT_HOOK_DEPTH\'"}\\n\'\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  const cap = _cap();
+  const rc = spawnHeadless.run(
+    ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+    { cwd: r, stdout: cap.stub },
+  );
+  assert.equal(rc, 0);
+  const child = JSON.parse(fs.readFileSync(path.join(r, 'out.json'), 'utf-8'));
+  assert.equal(child.hl, '1', 'child claude must run with NUBOS_PILOT_HEADLESS=1');
+  assert.equal(child.depth, '1', 'child claude must run at hook depth 1');
+});
+
+test('SH-GUARD-4 refuses to spawn while a live lock for the same agent is held (concurrency guard)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  const held = headlessGuard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(held.acquired, true);
+  const cap = _cap();
+  try {
+    assert.throws(
+      () => spawnHeadless.run(
+        ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+        { cwd: r, stdout: cap.stub },
+      ),
+      (err) => err && err.code === 'spawn-headless-locked',
+    );
+  } finally {
+    held.release();
+  }
+});
+
+test('SH-GUARD-5 lock is released after a successful spawn (re-spawnable)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  const cap = _cap();
+  for (let i = 0; i < 2; i++) {
+    const rc = spawnHeadless.run(
+      ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out' + i + '.json'],
+      { cwd: r, stdout: cap.stub },
+    );
+    assert.equal(rc, 0, 'sequential spawns must each acquire and release the lock');
+  }
+  assert.equal(fs.existsSync(headlessGuard._lockPath(r, 'np-test-critic')), false, 'no lock residue after spawns');
+});
+
+test('SH-GUARD-6 a held lock for one agent does NOT block a different agent (per-agent scope)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(
+    path.join(r, '.nubos-pilot', 'agents', 'np-other-critic.md'),
+    '---\nname: np-other-critic\n---\n\n# Role\n',
+    'utf-8',
+  );
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
+  const held = headlessGuard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(held.acquired, true);
+  const cap = _cap();
+  try {
+    const rc = spawnHeadless.run(
+      ['--agent', 'np-other-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+      { cwd: r, stdout: cap.stub },
+    );
+    assert.equal(rc, 0, 'a different agent must spawn while np-test-critic is locked');
+  } finally {
+    held.release();
+  }
+});
+
+test('SH-GUARD-7 lock is released even when the spawn errors (claude-not-found)', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', path.join(r, 'no-such-binary'));
+  const cap = _cap();
+  assert.throws(
+    () => spawnHeadless.run(
+      ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+      { cwd: r, stdout: cap.stub },
+    ),
+    (err) => err && err.code === 'spawn-headless-claude-not-found',
+  );
+  assert.equal(fs.existsSync(headlessGuard._lockPath(r, 'np-test-critic')), false,
+    'the per-agent lock must not leak when the spawn fails');
+});
+
 test('SH-ENV-4 NUBOS_PILOT_/CLAUDE_/ANTHROPIC_ prefixed vars pass through (whitelisted prefix)', () => {
   const parent = {
     PATH: '/usr/bin',

package/lib/headless-guard.cjs

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { atomicCreateExclusiveSync } = require('./core.cjs');
+
+const HEADLESS_ENV = 'NUBOS_PILOT_HEADLESS';
+const DEPTH_ENV = 'NUBOS_PILOT_HOOK_DEPTH';
+const MAX_DEPTH_ENV = 'NUBOS_PILOT_MAX_HOOK_DEPTH';
+const DEFAULT_MAX_DEPTH = 1;
+const DEFAULT_LOCK_STALE_MS = 15 * 60 * 1000;
+
+function isHeadless(env) {
+  const e = env || process.env;
+  return e[HEADLESS_ENV] === '1';
+}
+
+function currentDepth(env) {
+  const e = env || process.env;
+  const n = parseInt(e[DEPTH_ENV], 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function maxDepth(env) {
+  const e = env || process.env;
+  const n = parseInt(e[MAX_DEPTH_ENV], 10);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_MAX_DEPTH;
+}
+
+function depthExceeded(env) {
+  return currentDepth(env) >= maxDepth(env);
+}
+
+function childSpawnEnv(env) {
+  const out = Object.create(null);
+  out[HEADLESS_ENV] = '1';
+  out[DEPTH_ENV] = String(currentDepth(env) + 1);
+  return out;
+}
+
+function _isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    if (err && err.code === 'EPERM') return true;
+    return true;
+  }
+}
+
+function _lockPath(root, agent) {
+  return path.join(root, '.nubos-pilot', 'run', 'headless-' + agent + '.lock');
+}
+
+function _reclaimStaleLock(lockPath) {
+  const aside = lockPath + '.stale.' + process.pid + '.' + crypto.randomBytes(4).toString('hex');
+  try { fs.renameSync(lockPath, aside); }
+  catch { return; }
+  try { fs.unlinkSync(aside); } catch {}
+}
+
+function tryAcquireSpawnLock(root, agent, opts) {
+  const o = opts || {};
+  const staleMs = Number.isFinite(o.staleMs) ? o.staleMs : DEFAULT_LOCK_STALE_MS;
+  const lockPath = _lockPath(root, agent);
+  try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch {}
+  const payload = JSON.stringify({
+    pid: process.pid,
+    agent,
+    hostname: os.hostname(),
+    acquiredAt: new Date().toISOString(),
+  });
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      atomicCreateExclusiveSync(lockPath, payload);
+      let released = false;
+      return {
+        acquired: true,
+        lockPath,
+        release() {
+          if (released) return;
+          released = true;
+          let meta = null;
+          try { meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8')); } catch {}
+          if (meta && meta.pid !== process.pid) return;
+          try { fs.unlinkSync(lockPath); } catch {}
+        },
+      };
+    } catch (err) {
+      if (!err || err.code !== 'EEXIST') {
+        return { acquired: false, error: (err && err.code) || 'unknown' };
+      }
+      let meta = null;
+      let stat = null;
+      try { meta = JSON.parse(fs.readFileSync(lockPath, 'utf-8')); } catch {}
+      try { stat = fs.statSync(lockPath); } catch {}
+      const ageStale = !!stat && (Date.now() - stat.mtimeMs > staleMs);
+      const pidDead = !!meta && _isPidAlive(meta.pid) === false;
+      if (ageStale || pidDead) {
+        _reclaimStaleLock(lockPath);
+        continue;
+      }
+      return { acquired: false, holder: meta };
+    }
+  }
+  return { acquired: false };
+}
+
+module.exports = {
+  HEADLESS_ENV,
+  DEPTH_ENV,
+  MAX_DEPTH_ENV,
+  DEFAULT_MAX_DEPTH,
+  DEFAULT_LOCK_STALE_MS,
+  isHeadless,
+  currentDepth,
+  maxDepth,
+  depthExceeded,
+  childSpawnEnv,
+  tryAcquireSpawnLock,
+  _isPidAlive,
+  _lockPath,
+};

package/lib/headless-guard.test.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const guard = require('./headless-guard.cjs');
+
+const _sandboxes = [];
+
+function _mkRoot() {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'np-headless-guard-'));
+  fs.mkdirSync(path.join(r, '.nubos-pilot'), { recursive: true });
+  _sandboxes.push(r);
+  return r;
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    const r = _sandboxes.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('HG-1: isHeadless is true only when NUBOS_PILOT_HEADLESS=1', () => {
+  assert.equal(guard.isHeadless({}), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: '0' }), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: 'yes' }), false);
+  assert.equal(guard.isHeadless({ NUBOS_PILOT_HEADLESS: '1' }), true);
+});
+
+test('HG-2: currentDepth parses NUBOS_PILOT_HOOK_DEPTH, defaults to 0', () => {
+  assert.equal(guard.currentDepth({}), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: 'x' }), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: '0' }), 0);
+  assert.equal(guard.currentDepth({ NUBOS_PILOT_HOOK_DEPTH: '2' }), 2);
+});
+
+test('HG-3: depthExceeded honours default cap of 1 and the env override', () => {
+  assert.equal(guard.depthExceeded({}), false);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '1' }), true);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '1', NUBOS_PILOT_MAX_HOOK_DEPTH: '2' }), false);
+  assert.equal(guard.depthExceeded({ NUBOS_PILOT_HOOK_DEPTH: '2', NUBOS_PILOT_MAX_HOOK_DEPTH: '2' }), true);
+});
+
+test('HG-4: childSpawnEnv marks headless and increments depth', () => {
+  assert.deepEqual({ ...guard.childSpawnEnv({}) }, { NUBOS_PILOT_HEADLESS: '1', NUBOS_PILOT_HOOK_DEPTH: '1' });
+  assert.deepEqual(
+    { ...guard.childSpawnEnv({ NUBOS_PILOT_HOOK_DEPTH: '1' }) },
+    { NUBOS_PILOT_HEADLESS: '1', NUBOS_PILOT_HOOK_DEPTH: '2' },
+  );
+});
+
+test('HG-5: tryAcquireSpawnLock acquires, then refuses a live concurrent holder', () => {
+  const r = _mkRoot();
+  const first = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(first.acquired, true);
+  assert.ok(fs.existsSync(first.lockPath));
+
+  const second = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(second.acquired, false, 'second concurrent acquire must be refused');
+  assert.ok(second.holder && second.holder.pid === process.pid);
+
+  first.release();
+  assert.equal(fs.existsSync(first.lockPath), false, 'release removes the lock');
+
+  const third = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(third.acquired, true, 'lock is re-acquirable after release');
+  third.release();
+});
+
+test('HG-6: different agents get independent locks', () => {
+  const r = _mkRoot();
+  const a = guard.tryAcquireSpawnLock(r, 'np-security-reviewer');
+  const b = guard.tryAcquireSpawnLock(r, 'np-learnings-extractor');
+  assert.equal(a.acquired, true);
+  assert.equal(b.acquired, true, 'a second agent must not be blocked by the first');
+  a.release();
+  b.release();
+});
+
+test('HG-7: a stale lock (old mtime) is reclaimed', () => {
+  const r = _mkRoot();
+  const held = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(held.acquired, true);
+  const past = new Date(Date.now() - 60 * 60 * 1000);
+  fs.utimesSync(held.lockPath, past, past);
+
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic', { staleMs: 1000 });
+  assert.equal(next.acquired, true, 'a lock older than staleMs must be reclaimed');
+  next.release();
+});
+
+test('HG-8: a dead-pid lock is reclaimed even when fresh', () => {
+  const r = _mkRoot();
+  const lockPath = guard._lockPath(r, 'np-test-critic');
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  fs.writeFileSync(lockPath, JSON.stringify({ pid: 2147483646, hostname: os.hostname(), acquiredAt: new Date().toISOString() }), 'utf-8');
+  assert.equal(guard._isPidAlive(2147483646), false);
+
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  assert.equal(next.acquired, true, 'a lock owned by a dead pid must be reclaimed');
+  next.release();
+});
+
+test('HG-9: stale reclaim leaves no .stale residue behind', () => {
+  const r = _mkRoot();
+  const held = guard.tryAcquireSpawnLock(r, 'np-test-critic');
+  const past = new Date(Date.now() - 60 * 60 * 1000);
+  fs.utimesSync(held.lockPath, past, past);
+  const next = guard.tryAcquireSpawnLock(r, 'np-test-critic', { staleMs: 1000 });
+  assert.equal(next.acquired, true);
+  next.release();
+  const runDir = path.join(r, '.nubos-pilot', 'run');
+  const residue = fs.readdirSync(runDir).filter((n) => n.includes('.stale.'));
+  assert.deepEqual(residue, [], 'rename-aside reclaim must clean up its temp file');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Self-hosted AI pilot for any codebase. Researcher and critic agents plan, execute and verify each change.",
   "homepage": "https://pilot.nubos.cloud",
   "repository": {

package/templates/claude/payload/hooks/np-learnings-hook.cjs

@@ -37,6 +37,7 @@ function readStdin() {
 }
 
 (async () => {
+  if (process.env.NUBOS_PILOT_HEADLESS === '1') { process.exit(0); return; }
   const verb = process.argv[2];
   if (!ALLOWED_VERBS.has(verb)) { process.exit(0); return; }
   const npTools = resolveNpTools();

package/templates/claude/payload/hooks/np-security-hook.cjs

@@ -31,6 +31,7 @@ function readStdin() {
 }
 
 (async () => {
+  if (process.env.NUBOS_PILOT_HEADLESS === '1') { process.exit(0); return; }
   const verb = process.argv[2];
   if (!ALLOWED_VERBS.has(verb)) { process.exit(0); return; }
   const npTools = resolveNpTools();