nubos-pilot 1.2.2 → 1.2.4

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/lib/install/claude-hooks-learnings.test.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const mod = require('./claude-hooks.cjs');
+
+function _mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-learn-hooks-'));
+  const hooksDir = path.join(dir, '.claude', 'nubos-pilot', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.writeFileSync(path.join(hooksDir, 'np-statusline.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-ctx-monitor.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-security-hook.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-learnings-hook.cjs'), '// stub\n');
+  return dir;
+}
+
+test('LH-1: which=learnings registers capture on Stop + reset on UserPromptSubmit', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    assert.equal(res.results.learnings.capture.action, 'installed');
+    assert.equal(res.results.learnings.reset.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    const stop = JSON.stringify(settings.hooks.Stop);
+    const ups = JSON.stringify(settings.hooks.UserPromptSubmit);
+    assert.ok(stop.includes('np-learnings-hook.cjs'));
+    assert.ok(stop.includes(' capture'));
+    assert.ok(ups.includes('np-learnings-hook.cjs'));
+    assert.ok(ups.includes(' reset'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-2: which=all installs learnings alongside security', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    assert.ok(res.results.learnings);
+    assert.ok(res.results.security);
+    assert.equal(res.results.learnings.capture.action, 'installed');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-3: install is idempotent — second run updates, not duplicates', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    const res2 = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    assert.equal(res2.results.learnings.capture.action, 'updated');
+    const settings = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
+    const stopLearnings = settings.hooks.Stop.filter((e) =>
+      JSON.stringify(e).includes('np-learnings-hook.cjs'));
+    assert.equal(stopLearnings.length, 1);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-4: uninstall removes learnings hooks', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    const res = mod.uninstallClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.learnings.action, 'removed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    const dump = JSON.stringify(settings.hooks || {});
+    assert.ok(!dump.includes('np-learnings-hook.cjs'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-5: missing learnings hook script throws claude-hooks-script-missing', () => {
+  const dir = _mkSandbox();
+  try {
+    fs.rmSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-learnings-hook.cjs'));
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' }),
+      (e) => e.code === 'claude-hooks-script-missing',
+    );
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});

package/lib/install/claude-hooks.cjs

@@ -17,9 +17,11 @@ const { atomicWriteFileSync, NubosPilotError, withFileLock } = require('../core.
 const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.cjs';
 const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.cjs';
 const SECURITY_HOOK_REL = '.claude/nubos-pilot/hooks/np-security-hook.cjs';
+const LEARNINGS_HOOK_REL = '.claude/nubos-pilot/hooks/np-learnings-hook.cjs';
 const NP_STATUSLINE_MARKER = 'np-statusline.';
 const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.';
 const NP_SECURITY_MARKER = 'np-security-hook.';
+const NP_LEARNINGS_MARKER = 'np-learnings-hook.';
 
 // ADR-0020: in-session security review layer. One DRY hook script, registered
 // against five Claude Code lifecycle events, differentiated by a trailing verb.
@@ -32,6 +34,15 @@ const SECURITY_HOOKS = Object.freeze([
 ]);
 const SECURITY_EVENTS = Object.freeze(['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse']);
 
+// ADR-0010 / ECC continuous-learning: one DRY hook script. `capture` on Stop
+// (rate-limited auto-extraction of the turn's learnings); `reset` on
+// UserPromptSubmit (clears the consecutive-stop streak).
+const LEARNINGS_HOOKS = Object.freeze([
+  { verb: 'reset',   event: 'UserPromptSubmit', matcher: undefined },
+  { verb: 'capture', event: 'Stop',             matcher: undefined },
+]);
+const LEARNINGS_EVENTS = Object.freeze(['UserPromptSubmit', 'Stop']);
+
 function _settingsPath(scope, projectRoot) {
   if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
   return path.join(projectRoot, '.claude', 'settings.local.json');
@@ -119,14 +130,15 @@ function _verbOf(command) {
   return m ? m[1] : null;
 }
 
-function _installVerbHook(settings, eventName, matcher, cmd, verb) {
+function _installVerbHook(settings, eventName, matcher, cmd, verb, marker) {
+  const mark = marker || NP_SECURITY_MARKER;
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
   if (!Array.isArray(settings.hooks[eventName])) settings.hooks[eventName] = [];
   const list = settings.hooks[eventName];
   for (const entry of list) {
     const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
     for (const h of hooks) {
-      if (h && typeof h.command === 'string' && h.command.includes(NP_SECURITY_MARKER) && _verbOf(h.command) === verb) {
+      if (h && typeof h.command === 'string' && h.command.includes(mark) && _verbOf(h.command) === verb) {
         h.command = cmd;
         h.type = 'command';
         if (matcher !== undefined) entry.matcher = matcher;
@@ -145,11 +157,42 @@ function _installSecurity(settings, scope, projectRoot) {
   const base = _hookCommand(SECURITY_HOOK_REL, scope, projectRoot);
   const results = {};
   for (const h of SECURITY_HOOKS) {
-    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb);
+    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb, NP_SECURITY_MARKER);
+  }
+  return results;
+}
+
+function _installLearnings(settings, scope, projectRoot) {
+  const base = _hookCommand(LEARNINGS_HOOK_REL, scope, projectRoot);
+  const results = {};
+  for (const h of LEARNINGS_HOOKS) {
+    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb, NP_LEARNINGS_MARKER);
   }
   return results;
 }
 
+function _removeLearnings(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') return { action: 'absent' };
+  let removed = 0;
+  for (const eventName of LEARNINGS_EVENTS) {
+    if (!Array.isArray(settings.hooks[eventName])) continue;
+    const filtered = [];
+    for (const entry of settings.hooks[eventName]) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      const kept = hooks.filter((h) => !(h && typeof h.command === 'string' && h.command.includes(NP_LEARNINGS_MARKER)));
+      if (kept.length > 0) {
+        filtered.push(kept.length === hooks.length ? entry : Object.assign({}, entry, { hooks: kept }));
+      } else {
+        removed++;
+      }
+    }
+    settings.hooks[eventName] = filtered;
+    if (filtered.length === 0) delete settings.hooks[eventName];
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  return { action: removed > 0 ? 'removed' : 'absent' };
+}
+
 function _removeSecurity(settings) {
   if (!settings.hooks || typeof settings.hooks !== 'object') return { action: 'absent' };
   let removed = 0;
@@ -214,6 +257,7 @@ function installClaudeHooks(opts) {
   const wantStatusline = which === 'statusline' || which === 'both' || which === 'all';
   const wantCtxMonitor = which === 'ctx-monitor' || which === 'both' || which === 'all';
   const wantSecurity = which === 'security' || which === 'all';
+  const wantLearnings = which === 'learnings' || which === 'all';
 
   const statuslineCmd = _hookCommand(STATUSLINE_REL, scope, projectRoot);
   const ctxMonitorCmd = _hookCommand(CTX_MONITOR_REL, scope, projectRoot);
@@ -222,6 +266,7 @@ function installClaudeHooks(opts) {
   const statuslineAbs = path.join(base, STATUSLINE_REL);
   const ctxMonitorAbs = path.join(base, CTX_MONITOR_REL);
   const securityAbs = path.join(base, SECURITY_HOOK_REL);
+  const learningsAbs = path.join(base, LEARNINGS_HOOK_REL);
 
   if (wantStatusline) {
     if (!fs.existsSync(statuslineAbs)) {
@@ -250,6 +295,15 @@ function installClaudeHooks(opts) {
       );
     }
   }
+  if (wantLearnings) {
+    if (!fs.existsSync(learningsAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Learnings hook script not found: ' + learningsAbs,
+        { script: learningsAbs },
+      );
+    }
+  }
 
   fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
 
@@ -266,6 +320,9 @@ function installClaudeHooks(opts) {
     if (wantSecurity) {
       results.security = _installSecurity(settings, scope, projectRoot);
     }
+    if (wantLearnings) {
+      results.learnings = _installLearnings(settings, scope, projectRoot);
+    }
 
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
 
@@ -279,7 +336,7 @@ function uninstallClaudeHooks(opts) {
   const projectRoot = o.projectRoot || process.cwd();
   const scope = o.scope === 'global' ? 'global' : 'local';
   const settingsPath = _settingsPath(scope, projectRoot);
-  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' }, security: { action: 'absent' } } };
+  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' }, security: { action: 'absent' }, learnings: { action: 'absent' } } };
 
   return withFileLock(settingsPath, () => {
     const settings = _readJsonSafe(settingsPath);
@@ -287,6 +344,7 @@ function uninstallClaudeHooks(opts) {
       statusline: _removeStatusLine(settings),
       ctxMonitor: _removePostToolUse(settings),
       security: _removeSecurity(settings),
+      learnings: _removeLearnings(settings),
     };
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
     atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -304,6 +362,9 @@ module.exports = {
   NP_CTX_MONITOR_MARKER,
   NP_SECURITY_MARKER,
   SECURITY_HOOKS,
+  LEARNINGS_HOOK_REL,
+  NP_LEARNINGS_MARKER,
+  LEARNINGS_HOOKS,
   _settingsPath,
   _hookCommand,
 };

package/lib/install/claude-hooks.test.cjs

@@ -230,7 +230,7 @@ function _mkSandboxAll() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-all-'));
   const hooksDir = path.join(dir, '.claude', 'nubos-pilot', 'hooks');
   fs.mkdirSync(hooksDir, { recursive: true });
-  for (const f of ['np-statusline.cjs', 'np-ctx-monitor.cjs', 'np-security-hook.cjs']) {
+  for (const f of ['np-statusline.cjs', 'np-ctx-monitor.cjs', 'np-security-hook.cjs', 'np-learnings-hook.cjs']) {
     fs.writeFileSync(path.join(hooksDir, f), '// stub\n');
   }
   return dir;
@@ -269,7 +269,10 @@ test('claude-hooks SEC: re-install is idempotent (no duplicate entries)', () =>
     assert.equal(res2.results.security.scan.action, 'updated');
     const s = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
     assert.equal(s.hooks.SessionStart.length, 1);
-    assert.equal(s.hooks.Stop.length, 1);
+    // Stop now carries the security 'review' hook + the learnings 'capture' hook (which=all installs both).
+    assert.equal(s.hooks.Stop.length, 2);
+    assert.equal(s.hooks.Stop.filter((e) => e.hooks[0].command.includes('np-security-hook.')).length, 1);
+    assert.equal(s.hooks.Stop.filter((e) => e.hooks[0].command.includes('np-learnings-hook.')).length, 1);
     assert.equal(s.hooks.PostToolUse.filter((e) => e.hooks[0].command.includes('np-security-hook.')).length, 2);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });

package/lib/learnings/capture-ledger.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Rate-limit ledger for Stop-hook learning auto-capture. Mirrors the ADR-0020
+// security ledger's posture (sliding per-hour window + consecutive-stop streak)
+// but is its own concern and its own file. Per-session JSON under the OS temp
+// dir; a session that never stops leaves nothing behind worth cleaning.
+
+const DIR = path.join(os.tmpdir(), 'nubos-pilot-learnings');
+
+function sanitizeSid(sid) {
+  return String(sid || 'nosid').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+
+function ledgerPath(sid) {
+  return path.join(DIR, sanitizeSid(sid) + '.json');
+}
+
+function _read(sid) {
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath(sid), 'utf-8'));
+  } catch {
+    return { session_id: sanitizeSid(sid), created_at: Date.now(), capture_times: [], stop_streak: 0 };
+  }
+}
+
+function _write(sid, l) {
+  try {
+    fs.mkdirSync(DIR, { recursive: true });
+    fs.writeFileSync(ledgerPath(sid), JSON.stringify(l), 'utf-8');
+  } catch { /* a rate-limit ledger must never break the session */ }
+}
+
+/**
+ * Record an attempt to auto-capture on this session's Stop. Returns whether the
+ * capture is allowed under both caps. The per-hour window prevents runaway cost;
+ * the in-a-row streak prevents back-to-back Stops (e.g. a tight edit loop) each
+ * firing an extraction.
+ * @returns {{allowed: boolean, count: number, streak: number, reason?: string}}
+ */
+function tryRecordCapture(sid, opts) {
+  const maxPerHour = opts && Number.isFinite(opts.maxPerHour) ? opts.maxPerHour : 10;
+  const maxStreak = opts && Number.isFinite(opts.maxStreak) ? opts.maxStreak : 3;
+  const now = Date.now();
+  const hourAgo = now - 3600 * 1000;
+
+  const l = _read(sid);
+  l.capture_times = (Array.isArray(l.capture_times) ? l.capture_times : []).filter((t) => t > hourAgo);
+  l.stop_streak = Number.isFinite(l.stop_streak) ? l.stop_streak : 0;
+
+  if (l.capture_times.length >= maxPerHour) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'per-hour-cap' };
+  }
+  if (l.stop_streak >= maxStreak) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'streak-cap' };
+  }
+
+  l.capture_times.push(now);
+  l.stop_streak += 1;
+  _write(sid, l);
+  return { allowed: true, count: l.capture_times.length, streak: l.stop_streak };
+}
+
+/** Reset the consecutive-stop streak — call after a user prompt (real activity). */
+function resetStreak(sid) {
+  const l = _read(sid);
+  l.stop_streak = 0;
+  _write(sid, l);
+}
+
+function removeLedger(sid) {
+  try { fs.unlinkSync(ledgerPath(sid)); } catch {}
+}
+
+module.exports = { tryRecordCapture, resetStreak, removeLedger, ledgerPath, sanitizeSid, _read };

package/lib/learnings/capture-ledger.test.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { tryRecordCapture, resetStreak, removeLedger } = require('./capture-ledger.cjs');
+
+function _sid(name) { return 'np-test-ledger-' + name + '-' + process.pid; }
+
+test('CL-1: streak cap blocks after maxStreak consecutive stops', () => {
+  const sid = _sid('streak');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'streak-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-2: resetStreak clears the streak so capture is allowed again', () => {
+  const sid = _sid('reset');
+  removeLedger(sid);
+  try {
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, false);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, true);
+  } finally { removeLedger(sid); }
+});
+
+test('CL-3: per-hour cap blocks regardless of streak resets', () => {
+  const sid = _sid('hour');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'per-hour-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-4: a fresh session starts allowed', () => {
+  const sid = _sid('fresh');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, {}).allowed, true);
+  } finally { removeLedger(sid); }
+});