nubos-pilot 0.6.0 → 0.6.2

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

@@ -0,0 +1,163 @@
+'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-claude-hooks-'));
+  fs.mkdirSync(path.join(dir, '.claude'), { recursive: true });
+  fs.mkdirSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-statusline.js'), '// stub\n');
+  fs.writeFileSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-ctx-monitor.js'), '// stub\n');
+  return dir;
+}
+
+test('claude-hooks: fresh install writes both hooks to local settings', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.dryRun, false);
+    assert.equal(res.results.statusline.action, 'installed');
+    assert.equal(res.results.ctxMonitor.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.type, 'command');
+    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+    assert.ok(Array.isArray(settings.hooks.PostToolUse));
+    assert.equal(settings.hooks.PostToolUse[0].matcher, '.*');
+    assert.ok(settings.hooks.PostToolUse[0].hooks[0].command.includes('np-ctx-monitor.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: existing foreign statusLine is preserved without force', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo my-custom-bar' },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.statusline.action, 'skipped-existing');
+    assert.equal(res.results.statusline.existingCommand, 'echo my-custom-bar');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.command, 'echo my-custom-bar');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: --force overwrites foreign statusLine', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo other' },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', force: true });
+    assert.equal(res.results.statusline.action, 'overwrote');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.ok(settings.statusLine.command.includes('np-statusline.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: re-install is idempotent (updates nubos-pilot hook path)', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    const res2 = mod.installClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res2.results.statusline.action, 'updated');
+    assert.equal(res2.results.ctxMonitor.action, 'updated');
+    const settings = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
+    assert.equal(settings.hooks.PostToolUse.length, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: preserves unrelated PostToolUse hooks', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      hooks: {
+        PostToolUse: [
+          { matcher: 'Bash', hooks: [{ type: 'command', command: 'echo other-hook' }] },
+        ],
+      },
+    }));
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'ctx-monitor' });
+    assert.equal(res.results.ctxMonitor.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.hooks.PostToolUse.length, 2);
+    assert.equal(settings.hooks.PostToolUse[0].matcher, 'Bash');
+    assert.ok(settings.hooks.PostToolUse[1].hooks[0].command.includes('np-ctx-monitor.js'));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: uninstall removes only our entries', () => {
+  const dir = _mkSandbox();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      statusLine: { type: 'command', command: 'echo custom' },
+      hooks: { PostToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'echo foreign' }] }] },
+    }));
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'ctx-monitor' });
+    const res = mod.uninstallClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.ctxMonitor.action, 'removed');
+    assert.equal(res.results.statusline.action, 'not-ours');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(settings.statusLine.command, 'echo custom');
+    assert.equal(settings.hooks.PostToolUse.length, 1);
+    assert.equal(settings.hooks.PostToolUse[0].matcher, 'Bash');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: missing hook script throws structured error', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-no-scripts-'));
+  try {
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local' }),
+      (err) => err && err.code === 'claude-hooks-script-missing',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: dryRun returns planned settings without writing', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', dryRun: true });
+    assert.equal(res.dryRun, true);
+    assert.ok(res.settings.statusLine);
+    assert.equal(fs.existsSync(res.path), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks: invalid JSON in settings yields structured error', () => {
+  const dir = _mkSandbox();
+  try {
+    fs.writeFileSync(path.join(dir, '.claude', 'settings.local.json'), '{broken');
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local' }),
+      (err) => err && err.code === 'claude-settings-invalid-json',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/roadmap.cjs

@@ -413,6 +413,112 @@ function addBacklogEntry(description, opts) {
   });
 }
 
+function _normalizeScList(scs) {
+  if (!Array.isArray(scs)) {
+    throw new NubosPilotError(
+      'roadmap-invalid-success-criteria',
+      'success_criteria must be an array',
+      { received: typeof scs },
+    );
+  }
+  const out = [];
+  for (let i = 0; i < scs.length; i++) {
+    const sc = scs[i];
+    if (typeof sc === 'string') {
+      const s = sc.trim();
+      if (!s) {
+        throw new NubosPilotError('roadmap-invalid-success-criteria',
+          'success_criteria[' + i + '] must be non-empty', { index: i });
+      }
+      out.push(s);
+      continue;
+    }
+    if (sc && typeof sc === 'object') {
+      const id = typeof sc.id === 'string' ? sc.id.trim() : '';
+      const text = typeof sc.text === 'string' ? sc.text.trim() : '';
+      if (!id || !/^SC-\d+$/.test(id)) {
+        throw new NubosPilotError('roadmap-invalid-success-criteria',
+          'success_criteria[' + i + '].id must match /^SC-\\d+$/', { index: i, id: sc.id });
+      }
+      if (!text) {
+        throw new NubosPilotError('roadmap-invalid-success-criteria',
+          'success_criteria[' + i + '].text must be non-empty', { index: i });
+      }
+      out.push({ id, text });
+      continue;
+    }
+    throw new NubosPilotError('roadmap-invalid-success-criteria',
+      'success_criteria[' + i + '] must be string or {id,text}', { index: i });
+  }
+  return out;
+}
+
+function _normalizeReqList(reqs) {
+  if (!Array.isArray(reqs)) {
+    throw new NubosPilotError('roadmap-invalid-requirements',
+      'requirements must be an array', { received: typeof reqs });
+  }
+  return reqs.map((r, i) => {
+    if (typeof r !== 'string' || !r.trim()) {
+      throw new NubosPilotError('roadmap-invalid-requirements',
+        'requirements[' + i + '] must be non-empty string', { index: i });
+    }
+    return r.trim();
+  });
+}
+
+function updatePhase(n, patch, cwd = process.cwd()) {
+  const want = String(n);
+  const p = patch || {};
+  const allowed = ['name', 'goal', 'requirements', 'success_criteria'];
+  const unknown = Object.keys(p).filter((k) => !allowed.includes(k));
+  if (unknown.length) {
+    throw new NubosPilotError('roadmap-invalid-patch',
+      'updatePhase: unknown keys: ' + unknown.join(', '),
+      { unknown, allowed });
+  }
+  const prepared = {};
+  if ('name' in p) {
+    if (typeof p.name !== 'string' || !p.name.trim()) {
+      throw new NubosPilotError('roadmap-invalid-patch',
+        'name must be non-empty string', {});
+    }
+    prepared.name = p.name.trim();
+  }
+  if ('goal' in p) {
+    if (typeof p.goal !== 'string') {
+      throw new NubosPilotError('roadmap-invalid-patch',
+        'goal must be string', {});
+    }
+    prepared.goal = p.goal;
+  }
+  if ('requirements' in p) prepared.requirements = _normalizeReqList(p.requirements);
+  if ('success_criteria' in p) prepared.success_criteria = _normalizeScList(p.success_criteria);
+
+  return _mutate(cwd, (doc) => {
+    let target = null;
+    for (const ms of doc.milestones) {
+      if (!ms) continue;
+      if (Array.isArray(ms.slices) && String(ms.number) === want) { target = ms; break; }
+      if (Array.isArray(ms.phases)) {
+        const hit = ms.phases.find((ph) => ph && String(ph.number) === want);
+        if (hit) { target = hit; break; }
+      }
+    }
+    if (!target) {
+      throw new NubosPilotError('phase-not-found',
+        'Phase ' + want + ' not found in roadmap.yaml',
+        { requested: want });
+    }
+    const updated = [];
+    for (const k of Object.keys(prepared)) {
+      target[k] = prepared[k];
+      updated.push(k);
+    }
+    return { number: want, name: target.name || '', fields_updated: updated };
+  });
+}
+
 function collapseMilestone(milestoneId, opts) {
   const cwd = (opts && opts.cwd) || process.cwd();
   if (typeof milestoneId !== 'string' || !/^[vV0-9._-]+$/.test(milestoneId)) {
@@ -446,6 +552,7 @@ module.exports = {
   addMilestone,
   addPhase,
   insertPhaseAfter,
+  updatePhase,
   addBacklogEntry,
   collapseMilestone,
 };

package/lib/roadmap.test.cjs

@@ -369,3 +369,87 @@ test('ROAD-COLLAPSE-3: unknown milestoneId throws roadmap-milestone-not-found',
     (err) => err.name === 'NubosPilotError' && err.code === 'roadmap-milestone-not-found',
   );
 });
+
+const WRITE_SEED_TOP_LEVEL = [
+  'schema_version: 1',
+  'milestones:',
+  '  - id: M001',
+  '    number: 1',
+  '    name: Auth',
+  '    goal: log users in',
+  '    status: pending',
+  '    requirements: []',
+  '    success_criteria: []',
+  '    slices: []',
+  '  - id: M002',
+  '    number: 2',
+  '    name: Voice',
+  '    goal: voice pipeline',
+  '    status: pending',
+  '    requirements: []',
+  '    success_criteria: []',
+  '    slices: []',
+  '',
+].join('\n');
+
+test('RM-UPDATE-1: updatePhase writes success_criteria to nested milestone.phases[]', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  const res = roadmap.updatePhase(1, {
+    success_criteria: [{ id: 'SC-1', text: 'scaffold exists' }, { id: 'SC-2', text: 'ADRs committed' }],
+  }, sandbox);
+  assert.deepEqual(res.fields_updated, ['success_criteria']);
+  const p = roadmap.getPhase(1, sandbox);
+  assert.equal(p.success_criteria.length, 2);
+  assert.equal(p.success_criteria[0].id, 'SC-1');
+});
+
+test('RM-UPDATE-2: updatePhase writes to top-level milestone (new-style roadmap)', () => {
+  const sandbox = makeSandbox(WRITE_SEED_TOP_LEVEL);
+  roadmap.updatePhase(2, {
+    success_criteria: ['Speaker ID works', 'Latency < 2s'],
+    requirements: ['REQ-01'],
+  }, sandbox);
+  const p = roadmap.getPhase(2, sandbox);
+  assert.deepEqual(p.success_criteria, ['Speaker ID works', 'Latency < 2s']);
+  assert.deepEqual(p.requirements, ['REQ-01']);
+});
+
+test('RM-UPDATE-3: unknown phase number throws phase-not-found', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  assert.throws(
+    () => roadmap.updatePhase(99, { success_criteria: ['x'] }, sandbox),
+    (err) => err.name === 'NubosPilotError' && err.code === 'phase-not-found',
+  );
+});
+
+test('RM-UPDATE-4: invalid SC id format throws roadmap-invalid-success-criteria', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  assert.throws(
+    () => roadmap.updatePhase(1, { success_criteria: [{ id: 'BAD', text: 'x' }] }, sandbox),
+    (err) => err.name === 'NubosPilotError' && err.code === 'roadmap-invalid-success-criteria',
+  );
+});
+
+test('RM-UPDATE-5: unknown patch key throws roadmap-invalid-patch', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  assert.throws(
+    () => roadmap.updatePhase(1, { status: 'done' }, sandbox),
+    (err) => err.name === 'NubosPilotError' && err.code === 'roadmap-invalid-patch',
+  );
+});
+
+test('RM-UPDATE-6: partial patch — only updates given fields', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  roadmap.updatePhase(1, { goal: 'new goal text' }, sandbox);
+  const p = roadmap.getPhase(1, sandbox);
+  assert.equal(p.goal, 'new goal text');
+  assert.equal(p.success_criteria.length, 0, 'SCs untouched');
+  assert.equal(p.name, 'Foundation', 'name untouched');
+});
+
+test('RM-UPDATE-7: re-renders ROADMAP.md alongside roadmap.yaml', () => {
+  const sandbox = makeSandbox(WRITE_SEED);
+  roadmap.updatePhase(1, { success_criteria: ['check 1'] }, sandbox);
+  const md = fs.readFileSync(path.join(sandbox, '.nubos-pilot', 'ROADMAP.md'), 'utf-8');
+  assert.ok(md.includes('check 1'), 'ROADMAP.md re-rendered with new SC');
+});

package/lib/text-mode.cjs

@@ -5,7 +5,7 @@ const path = require('node:path');
 const { findProjectRoot, NubosPilotError } = require('./core.cjs');
 
 const DEFAULT_TEXT_MODE = false;
-const CLAUDE_ENV_KEYS = ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'];
+const CLAUDE_ENV_KEYS = [];
 
 function _coerceBool(raw) {
   if (raw === true || raw === false) return raw;

package/lib/text-mode.test.cjs

@@ -29,32 +29,21 @@ test('text-mode: default without config or runtime env is false', () => {
   }
 });
 
-test('text-mode: CLAUDECODE=1 in env flips default to true', () => {
+test('text-mode: CLAUDECODE=1 no longer flips to true (Claude Code uses AskUserQuestion)', () => {
   const dir = _mkSandbox();
   try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), true);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), false);
     const detail = tm.resolveTextModeDetail(dir, { CLAUDECODE: '1' });
-    assert.deepEqual(detail, { enabled: true, source: 'runtime' });
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('text-mode: CLAUDE_CODE_ENTRYPOINT non-empty flips to true', () => {
-  const dir = _mkSandbox();
-  try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDE_CODE_ENTRYPOINT: 'cli' }), true);
+    assert.deepEqual(detail, { enabled: false, source: 'default' });
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test('text-mode: env value "0" or "false" does not flip', () => {
+test('text-mode: CLAUDE_CODE_ENTRYPOINT no longer flips to true', () => {
   const dir = _mkSandbox();
   try {
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '0' }), false);
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: 'false' }), false);
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '' }), false);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDE_CODE_ENTRYPOINT: 'cli' }), false);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -71,7 +60,7 @@ test('text-mode: config workflow.text_mode=true wins over absent runtime', () =>
   }
 });
 
-test('text-mode: config workflow.text_mode=false overrides CLAUDECODE runtime', () => {
+test('text-mode: config workflow.text_mode=false stays false under CLAUDECODE env', () => {
   const dir = _mkSandbox();
   try {
     _writeConfig(dir, { workflow: { text_mode: false } });
@@ -97,11 +86,11 @@ test('text-mode: config workflow.text_mode="true" string coerced to boolean', ()
   }
 });
 
-test('text-mode: config missing workflow.text_mode falls through to runtime detection', () => {
+test('text-mode: config missing workflow.text_mode falls through to default (false)', () => {
   const dir = _mkSandbox();
   try {
     _writeConfig(dir, { response_language: 'de' });
-    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), true);
+    assert.equal(tm.resolveTextMode(dir, { CLAUDECODE: '1' }), false);
     assert.equal(tm.resolveTextMode(dir, {}), false);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -131,9 +120,9 @@ test('text-mode: readConfigTextMode throws on invalid JSON', () => {
   }
 });
 
-test('text-mode: detectRuntimeTextMode honors multiple env keys', () => {
-  assert.equal(tm.detectRuntimeTextMode({ CLAUDECODE: '1' }), true);
-  assert.equal(tm.detectRuntimeTextMode({ CLAUDE_CODE_ENTRYPOINT: 'cli' }), true);
+test('text-mode: detectRuntimeTextMode returns false for all envs (no runtime auto-flip anymore)', () => {
+  assert.equal(tm.detectRuntimeTextMode({ CLAUDECODE: '1' }), false);
+  assert.equal(tm.detectRuntimeTextMode({ CLAUDE_CODE_ENTRYPOINT: 'cli' }), false);
   assert.equal(tm.detectRuntimeTextMode({ OTHER: '1' }), false);
   assert.equal(tm.detectRuntimeTextMode({}), false);
 });

package/np-tools.cjs

@@ -50,6 +50,7 @@ const topLevelCommands = {
   'text-mode':      require('./bin/np-tools/text-mode.cjs'),
   'detect-runtime': require('./bin/np-tools/detect-runtime.cjs'),
   'template-path':  require('./bin/np-tools/template-path.cjs'),
+  'update-phase-meta': require('./bin/np-tools/update-phase-meta.cjs'),
 };
 
 const THRESHOLD = 16 * 1024;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "AI-driven planning and execution tool for code projects",
   "homepage": "https://github.com/Nubos-AI/nubos-pilot",
   "repository": {

package/templates/claude/payload/hooks/np-ctx-monitor.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const WARN_THRESHOLD = 35;
+const CRITICAL_THRESHOLD = 25;
+const DEBOUNCE_TOOLS = 5;
+
+function readStdinJson() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve({});
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    const timer = setTimeout(() => {
+      try { process.stdin.removeAllListeners(); } catch {}
+      resolve(safeParse(buf));
+    }, 500);
+    process.stdin.on('data', (c) => { buf += c; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(safeParse(buf)); });
+  });
+}
+
+function safeParse(s) {
+  try { return s ? JSON.parse(s) : {}; } catch { return {}; }
+}
+
+function severityFor(remaining) {
+  if (remaining <= CRITICAL_THRESHOLD) return 'critical';
+  if (remaining <= WARN_THRESHOLD) return 'warning';
+  return 'normal';
+}
+
+function sanitizeSid(sid) {
+  return String(sid || '').replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+(async () => {
+  let payload = {};
+  try { payload = await readStdinJson(); } catch { payload = {}; }
+  const sid = payload && payload.session_id;
+  if (!sid) { process.exit(0); return; }
+  const safeSid = sanitizeSid(sid);
+  const bridgePath = path.join(os.tmpdir(), 'claude-ctx-' + safeSid + '.json');
+  if (!fs.existsSync(bridgePath)) { process.exit(0); return; }
+
+  let bridge;
+  try { bridge = JSON.parse(fs.readFileSync(bridgePath, 'utf-8')); } catch { process.exit(0); return; }
+  const remaining = Number(bridge && bridge.usable_remaining_pct);
+  if (!Number.isFinite(remaining)) { process.exit(0); return; }
+
+  const statePath = path.join(os.tmpdir(), 'claude-ctx-warn-' + safeSid + '.json');
+  let state = { tool_count: 0, last_warn_at: -999, last_severity: 'normal' };
+  try {
+    const existing = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    state = Object.assign(state, existing);
+  } catch {}
+  state.tool_count = Number(state.tool_count || 0) + 1;
+
+  const sev = severityFor(remaining);
+  const escalated = sev !== 'normal' && sev !== state.last_severity && state.last_severity !== 'critical';
+  const firstWarn = state.last_severity === 'normal' && sev !== 'normal';
+  const enoughGap = (state.tool_count - Number(state.last_warn_at || -999)) >= DEBOUNCE_TOOLS;
+
+  if (sev === 'normal') {
+    state.last_severity = 'normal';
+    try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+    process.exit(0); return;
+  }
+
+  if (!firstWarn && !escalated && !enoughGap) {
+    try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+    process.exit(0); return;
+  }
+
+  state.last_warn_at = state.tool_count;
+  state.last_severity = sev;
+  try { fs.writeFileSync(statePath, JSON.stringify(state)); } catch {}
+
+  const msg = sev === 'critical'
+    ? 'CONTEXT CRITICAL: only ' + remaining + '% of usable context remaining. Stop taking new work — save state now with /np:pause-work before autocompact triggers.'
+    : 'CONTEXT LOW: ' + remaining + '% of usable context remaining. Wrap up the current task and consider /np:pause-work soon.';
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: '[nubos-pilot ctx-monitor] ' + msg,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+})().catch(() => { process.exit(0); });