@nforma.ai/nforma 0.2.1 → 0.28.0

package/hooks/dist/nf-session-start.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// hooks/nf-session-start.js
+// SessionStart hook — syncs nForma keychain secrets into ~/.claude.json
+// on every session start so mcpServers env blocks always reflect current keychain state.
+//
+// Runs synchronously (hook expects process to exit) — uses async IIFE with catch.
+
+'use strict';
+
+const path = require('path');
+const os   = require('os');
+const fs   = require('fs');
+
+const { loadConfig, shouldRunHook } = require('./config-loader');
+
+// ─── Stdin accumulation (for hook input JSON containing cwd) ─────────────────
+let _stdinRaw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => _stdinRaw += c);
+
+let _stdinReady;
+const _stdinPromise = new Promise(resolve => { _stdinReady = resolve; });
+process.stdin.on('end', () => _stdinReady());
+
+// Locate secrets.cjs — try installed global path first, then local dev path.
+//
+// IMPORTANT: install.js copies bin/*.cjs to ~/.claude/nf-bin/ (not ~/.claude/nf/bin/).
+// See bin/install.js line ~1679: binDest = path.join(targetDir, 'nf-bin')
+// where targetDir = os.homedir() + '/.claude'.
+function findSecrets() {
+  const candidates = [
+    path.join(os.homedir(), '.claude', 'nf-bin', 'secrets.cjs'),  // installed path
+    path.join(__dirname, '..', 'bin', 'secrets.cjs'),                 // local dev path
+  ];
+  for (const p of candidates) {
+    try {
+      return require(p);
+    } catch (_) {}
+  }
+  return null;
+}
+
+// ─── State reminder parser ──────────────────────────────────────────────────
+
+/**
+ * Parse STATE.md content for an in-progress phase and return a terse reminder.
+ * Returns null if no reminder is needed (complete, not started, or missing fields).
+ * @param {string} stateContent - Raw STATE.md content.
+ * @returns {string|null}
+ */
+function parseStateForReminder(stateContent) {
+  if (!stateContent || typeof stateContent !== 'string') return null;
+
+  const phaseMatch = stateContent.match(/Phase:\s*(.+)/);
+  const statusMatch = stateContent.match(/Status:\s*(.+)/);
+  const planMatch = stateContent.match(/Plan:\s*(.+)/);
+  const lastMatch = stateContent.match(/Last activity:\s*(.+)/);
+
+  if (!phaseMatch) return null;
+  if (!statusMatch) return null;
+
+  const status = statusMatch[1].trim();
+  if (status === 'Complete' || status === 'Not started') return null;
+
+  const phase = phaseMatch[1].trim();
+  const plan = planMatch ? planMatch[1].trim() : 'unknown plan';
+  const lastActivity = lastMatch ? lastMatch[1].trim() : 'unknown';
+
+  return 'SESSION STATE REMINDER: Phase ' + phase + ' -- ' + plan + ' -- ' + status + ' (last: ' + lastActivity + ')';
+}
+
+(async () => {
+  // Resolve project cwd from hook input JSON
+  await _stdinPromise;
+  let _hookCwd = process.cwd();
+  try { _hookCwd = JSON.parse(_stdinRaw).cwd || process.cwd(); } catch (_) {}
+
+  // Profile guard — exit early if this hook is not active for the current profile
+  const config = loadConfig(_hookCwd);
+  const profile = config.hook_profile || 'standard';
+  if (!shouldRunHook('nf-session-start', profile)) {
+    process.exit(0);
+  }
+
+  const secrets = findSecrets();
+  if (!secrets) {
+    // silently skip — nForma may not be installed yet or keytar absent
+    process.exit(0);
+  }
+  try {
+    await secrets.syncToClaudeJson(secrets.SERVICE);
+  } catch (e) {
+    // Non-fatal — write to stderr for debug logs, but never block session start
+    process.stderr.write('[nf-session-start] sync error: ' + e.message + '\n');
+  }
+
+  // Populate CCR config from keytar (fail-silent — CCR may not be installed)
+  try {
+    const { execFileSync } = require('child_process');
+    const nodeFsRef = require('fs');
+    const ccrCandidates = [
+      path.join(os.homedir(), '.claude', 'nf-bin', 'ccr-secure-config.cjs'),
+      path.join(__dirname, '..', 'bin', 'ccr-secure-config.cjs'),
+    ];
+    let ccrConfigPath = null;
+    for (const p of ccrCandidates) {
+      if (nodeFsRef.existsSync(p)) { ccrConfigPath = p; break; }
+    }
+    if (ccrConfigPath) {
+      execFileSync(process.execPath, [ccrConfigPath], { stdio: 'pipe', timeout: 10000 });
+    }
+  } catch (e) {
+    process.stderr.write('[nf-session-start] CCR config error: ' + e.message + '\n');
+  }
+
+  // Collect all additionalContext pieces — write once at the end
+  const _contextPieces = [];
+
+  // Telemetry surfacing — inject top unsurfaced issue as additionalContext
+  // Guard: only active when running inside the nForma dev repo itself
+  try {
+    const pkgPath = path.join(_hookCwd, 'package.json');
+    const isNfRepo = fs.existsSync(pkgPath) &&
+      JSON.parse(fs.readFileSync(pkgPath, 'utf8')).name === 'nforma';
+    const fixesPath = path.join(_hookCwd, '.planning', 'telemetry', 'pending-fixes.json');
+    if (isNfRepo && fs.existsSync(fixesPath)) {
+      const fixes = JSON.parse(fs.readFileSync(fixesPath, 'utf8'));
+      const issue = (fixes.issues || []).find(i => !i.surfaced && i.priority >= 50);
+      if (issue) {
+        issue.surfaced = true;
+        issue.surfacedAt = new Date().toISOString();
+        fs.writeFileSync(fixesPath, JSON.stringify(fixes, null, 2), 'utf8');
+        _contextPieces.push('Telemetry alert [priority=' + issue.priority + ']: ' + issue.description + '\nSuggested fix: ' + issue.action);
+      }
+    }
+  } catch (_) {}
+
+  // Session state reminder — inject brief context when work is in progress
+  try {
+    const statePath = path.join(_hookCwd, '.planning', 'STATE.md');
+    if (fs.existsSync(statePath)) {
+      const stateContent = fs.readFileSync(statePath, 'utf8');
+      const reminder = parseStateForReminder(stateContent);
+      if (reminder) {
+        _contextPieces.push(reminder);
+      }
+    }
+  } catch (_) {}
+
+  // Write combined additionalContext output (once)
+  if (_contextPieces.length > 0) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: _contextPieces.join('\n\n') }
+    }));
+  }
+
+  // Memory staleness check — warn about outdated MEMORY.md entries
+  try {
+    const validateMemoryCandidates = [
+      path.join(os.homedir(), '.claude', 'nf-bin', 'validate-memory.cjs'),
+      path.join(__dirname, '..', 'bin', 'validate-memory.cjs'),
+    ];
+    let validateMemoryMod = null;
+    for (const p of validateMemoryCandidates) {
+      try { validateMemoryMod = require(p); break; } catch (_) {}
+    }
+    if (validateMemoryMod) {
+      const { findings } = validateMemoryMod.validateMemory({ cwd: _hookCwd, quiet: true });
+      if (findings.length > 0) {
+        const summary = findings
+          .map(f => '[memory-check] ' + f.message)
+          .join('\n');
+        process.stderr.write(summary + '\n');
+      }
+    }
+  } catch (_) {}
+
+  process.exit(0);
+})();
+
+// Export for unit testing
+if (typeof module !== 'undefined') {
+  module.exports = module.exports || {};
+  module.exports.parseStateForReminder = parseStateForReminder;
+}

package/hooks/dist/nf-session-start.test.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+// Test suite for hooks/nf-session-start.js
+// Uses Node.js built-in test runner: node --test hooks/nf-session-start.test.js
+//
+// All tests spawn the hook as a child process with a mock stdin JSON payload.
+// The hook has no exports — only subprocess integration tests are possible.
+// Timeout is 8000ms to account for async operations (bootstrap secrets sync).
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOOK_PATH = path.join(__dirname, 'nf-session-start.js');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeTmpDir() {
+  const dir = path.join(
+    os.tmpdir(),
+    'nf-ss-' + Date.now() + '-' + Math.random().toString(36).slice(2)
+  );
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function runHook(stdinPayload, opts = {}) {
+  const input = stdinPayload === null ? '' : JSON.stringify(stdinPayload);
+  const result = spawnSync('node', [HOOK_PATH], {
+    input,
+    encoding: 'utf8',
+    timeout: 8000,
+    ...opts,
+  });
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status,
+    parsed: (() => { try { return JSON.parse(result.stdout); } catch { return null; } })(),
+  };
+}
+
+// Write a minimal package.json to the given dir.
+function writePackageJson(dir, name) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({ name }, null, 2),
+    'utf8'
+  );
+}
+
+// Write pending-fixes.json under .planning/telemetry/ in the given dir.
+function writePendingFixes(dir, issues) {
+  const telemetryDir = path.join(dir, '.planning', 'telemetry');
+  fs.mkdirSync(telemetryDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(telemetryDir, 'pending-fixes.json'),
+    JSON.stringify({ issues }, null, 2),
+    'utf8'
+  );
+}
+
+// Read pending-fixes.json back from disk.
+function readPendingFixes(dir) {
+  const fixesPath = path.join(dir, '.planning', 'telemetry', 'pending-fixes.json');
+  return JSON.parse(fs.readFileSync(fixesPath, 'utf8'));
+}
+
+// ─── Subprocess integration tests ───────────────────────────────────────────
+
+test('valid empty JSON stdin → exits 0 (secrets not found, silently skips)', () => {
+  // Pass a cwd that is not a nForma repo so telemetry branch also skips.
+  const tmpDir = makeTmpDir();
+  const { exitCode, stderr } = runHook({ cwd: tmpDir });
+  assert.equal(exitCode, 0, 'hook must exit 0 even when secrets module is absent');
+  // There should be no hard error in stderr (sync errors are expected-silent here)
+  // We allow stderr to contain debug notes but must not crash.
+  assert.ok(
+    !stderr.includes('TypeError') && !stderr.includes('ReferenceError'),
+    'should not throw a JS error on stderr: ' + stderr
+  );
+});
+
+test('invalid JSON stdin → exits 0 (fail-open)', () => {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: 'not valid json {{{',
+    encoding: 'utf8',
+    timeout: 8000,
+  });
+  assert.equal(result.status, 0, 'hook must exit 0 on JSON parse failure');
+});
+
+test('empty stdin → exits 0 (fail-open)', () => {
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: '',
+    encoding: 'utf8',
+    timeout: 8000,
+  });
+  assert.equal(result.status, 0, 'hook must exit 0 when stdin is empty');
+});
+
+test('telemetry: unsurfaced issue with priority >= 50 → outputs additionalContext and marks issue surfaced', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-001',
+      description: 'Quorum scoreboard drift detected in last 3 sessions',
+      action: 'Run node bin/update-scoreboard.cjs --repair',
+      priority: 80,
+      surfaced: false,
+    },
+  ]);
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  assert.ok(parsed !== null, 'stdout should be valid JSON');
+  assert.ok(parsed.hookSpecificOutput, 'output must have hookSpecificOutput');
+  assert.equal(
+    parsed.hookSpecificOutput.hookEventName,
+    'SessionStart',
+    'hookEventName must be SessionStart'
+  );
+
+  const ctx = parsed.hookSpecificOutput.additionalContext;
+  assert.ok(typeof ctx === 'string' && ctx.length > 0, 'additionalContext must be a non-empty string');
+  assert.ok(
+    ctx.includes('Quorum scoreboard drift detected'),
+    'additionalContext must include the issue description'
+  );
+  assert.ok(
+    ctx.includes('priority=80'),
+    'additionalContext must include the priority'
+  );
+  assert.ok(
+    ctx.includes('node bin/update-scoreboard.cjs --repair'),
+    'additionalContext must include the suggested action'
+  );
+
+  // Verify the file was updated on disk to mark the issue surfaced.
+  const updated = readPendingFixes(tmpDir);
+  const issue = updated.issues[0];
+  assert.equal(issue.surfaced, true, 'issue.surfaced must be set to true after surfacing');
+  assert.ok(
+    typeof issue.surfacedAt === 'string' && issue.surfacedAt.length > 0,
+    'issue.surfacedAt must be an ISO timestamp string'
+  );
+});
+
+test('telemetry: issue already surfaced (surfaced=true) → no additionalContext output', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-002',
+      description: 'Old issue already surfaced',
+      action: 'Nothing to do',
+      priority: 90,
+      surfaced: true,
+      surfacedAt: '2026-02-01T00:00:00.000Z',
+    },
+  ]);
+
+  const { exitCode, stdout } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  // When no telemetry issue is surfaced the hook writes nothing to stdout.
+  assert.equal(stdout.trim(), '', 'stdout must be empty when issue is already surfaced');
+});
+
+test('telemetry: priority below 50 → no additionalContext output', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-003',
+      description: 'Low priority noise item',
+      action: 'Ignore for now',
+      priority: 30,
+      surfaced: false,
+    },
+  ]);
+
+  const { exitCode, stdout } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  assert.equal(stdout.trim(), '', 'stdout must be empty when issue priority is below 50');
+});
+
+test('telemetry: priority exactly 50 → outputs additionalContext (boundary value)', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-004',
+      description: 'Boundary priority issue at exactly 50',
+      action: 'Check threshold logic',
+      priority: 50,
+      surfaced: false,
+    },
+  ]);
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  assert.ok(parsed !== null, 'stdout should be valid JSON at boundary priority=50');
+  const ctx = parsed.hookSpecificOutput.additionalContext;
+  assert.ok(
+    ctx.includes('Boundary priority issue at exactly 50'),
+    'additionalContext must include the boundary issue description'
+  );
+});
+
+test('non-nForma repo (package.json name != "nforma") → no telemetry output', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'some-other-project');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-005',
+      description: 'Should never be surfaced in non-nForma repo',
+      action: 'N/A',
+      priority: 99,
+      surfaced: false,
+    },
+  ]);
+
+  const { exitCode, stdout } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  assert.equal(stdout.trim(), '', 'stdout must be empty for non-nForma repo');
+
+  // Verify the file was NOT modified (issue.surfaced remains false).
+  const unchanged = readPendingFixes(tmpDir);
+  assert.equal(
+    unchanged.issues[0].surfaced,
+    false,
+    'issue.surfaced must remain false when repo is not nForma'
+  );
+});
+
+test('missing .planning/telemetry/pending-fixes.json → exits 0 silently', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  // Do NOT write pending-fixes.json — directory does not even exist.
+
+  const { exitCode, stdout, stderr } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0 when pending-fixes.json is absent');
+  assert.equal(stdout.trim(), '', 'stdout must be empty when pending-fixes.json is absent');
+  assert.ok(
+    !stderr.includes('TypeError') && !stderr.includes('ReferenceError'),
+    'no JS error on stderr when telemetry file is absent: ' + stderr
+  );
+});
+
+test('telemetry: multiple issues, only first unsurfaced high-priority one is surfaced', () => {
+  const tmpDir = makeTmpDir();
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-low',
+      description: 'Low priority skipped item',
+      action: 'Skip me',
+      priority: 20,
+      surfaced: false,
+    },
+    {
+      id: 'fix-surfaced',
+      description: 'Already surfaced item',
+      action: 'Already done',
+      priority: 95,
+      surfaced: true,
+      surfacedAt: '2026-02-01T00:00:00.000Z',
+    },
+    {
+      id: 'fix-high',
+      description: 'High priority unsurfaced item that should be picked',
+      action: 'Fix the high priority thing',
+      priority: 75,
+      surfaced: false,
+    },
+    {
+      id: 'fix-second-high',
+      description: 'Second high priority item that should NOT be picked this session',
+      action: 'Fix the second thing',
+      priority: 70,
+      surfaced: false,
+    },
+  ]);
+
+  const { exitCode, parsed } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0, 'hook must exit 0');
+  assert.ok(parsed !== null, 'stdout should be valid JSON');
+  const ctx = parsed.hookSpecificOutput.additionalContext;
+  assert.ok(
+    ctx.includes('High priority unsurfaced item that should be picked'),
+    'additionalContext must include the first eligible unsurfaced issue'
+  );
+  assert.ok(
+    !ctx.includes('Second high priority item that should NOT be picked'),
+    'additionalContext must NOT include the second unsurfaced issue'
+  );
+
+  // Verify only fix-high was marked surfaced on disk.
+  const updated = readPendingFixes(tmpDir);
+  const fixHigh = updated.issues.find(i => i.id === 'fix-high');
+  const fixSecond = updated.issues.find(i => i.id === 'fix-second-high');
+  assert.equal(fixHigh.surfaced, true, 'fix-high must be marked surfaced');
+  assert.equal(fixSecond.surfaced, false, 'fix-second-high must remain unsurfaced');
+});
+
+test('cwd field absent in stdin JSON → exits 0 (defaults to process.cwd, no crash)', () => {
+  // Pass an object with no cwd field. The hook should default to process.cwd()
+  // and not crash regardless of whether that directory has a nForma package.json.
+  const { exitCode } = runHook({});
+  assert.equal(exitCode, 0, 'hook must exit 0 when cwd is absent from stdin');
+});
+
+test('stdout is either empty or valid JSON (never partial/corrupt output)', () => {
+  const tmpDir = makeTmpDir();
+  // Repo with a surfaceable issue to exercise the stdout write path.
+  writePackageJson(tmpDir, 'nforma');
+  writePendingFixes(tmpDir, [
+    {
+      id: 'fix-json-integrity',
+      description: 'Test JSON output integrity',
+      action: 'Verify output is parseable',
+      priority: 60,
+      surfaced: false,
+    },
+  ]);
+
+  const { stdout, exitCode } = runHook({ cwd: tmpDir });
+
+  assert.equal(exitCode, 0);
+  if (stdout.trim().length > 0) {
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch (e) {
+      assert.fail('stdout is non-empty but not valid JSON: ' + stdout);
+    }
+    assert.ok(
+      parsed && typeof parsed === 'object',
+      'parsed stdout must be an object'
+    );
+  }
+});

package/hooks/dist/{qgsd-slot-correlator.js → nf-slot-correlator.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// hooks/qgsd-slot-correlator.js
-// SubagentStart hook — writes a correlation placeholder file for qgsd-quorum-slot-worker subagents.
+// hooks/nf-slot-correlator.js
+// SubagentStart hook — writes a correlation placeholder file for nf-quorum-slot-worker subagents.
 //
 // At SubagentStart time, the prompt/slot name is not available in the hook payload.
 // This hook writes a stub correlation file { agent_id, ts, slot: null } so the
@@ -8,7 +8,7 @@
 // The slot is resolved from last_assistant_message preamble by the token collector.
 //
 // Guards:
-//   - Only processes agent_type === 'qgsd-quorum-slot-worker' (exits 0 otherwise)
+//   - Only processes agent_type === 'nf-quorum-slot-worker' (exits 0 otherwise)
 //   - If agent_id is absent: exits 0 gracefully
 //   - Fail-open: any unhandled error exits 0
 
@@ -16,6 +16,7 @@
 
 const fs   = require('fs');
 const path = require('path');
+const { loadConfig, shouldRunHook } = require('./config-loader');
 
 function main() {
   let raw = '';
@@ -25,8 +26,15 @@ function main() {
     try {
       const input = JSON.parse(raw);
 
-      // Guard: only process qgsd-quorum-slot-worker subagents
-      if (input.agent_type !== 'qgsd-quorum-slot-worker') {
+      // Profile guard — exit early if this hook is not active for the current profile
+      const config = loadConfig();
+      const profile = config.hook_profile || 'standard';
+      if (!shouldRunHook('nf-slot-correlator', profile)) {
+        process.exit(0);
+      }
+
+      // Guard: only process nf-quorum-slot-worker subagents
+      if (input.agent_type !== 'nf-quorum-slot-worker') {
         process.exit(0);
       }
 

package/hooks/dist/nf-slot-correlator.test.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Test suite for hooks/nf-slot-correlator.js
+// Uses Node.js built-in test runner: node --test hooks/nf-slot-correlator.test.js
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOOK_PATH = path.join(__dirname, 'nf-slot-correlator.js');
+
+// Helper: create isolated tmpdir per test
+function makeTmpDir() {
+  return path.join(os.tmpdir(), 'nf-sc-' + Date.now() + '-' + Math.random().toString(36).slice(2));
+}
+
+// Helper: run the hook with a given stdin JSON payload using tmpDir as cwd
+function runHook(stdinPayload, tmpDir) {
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const result = spawnSync('node', [HOOK_PATH], {
+    input: JSON.stringify(stdinPayload),
+    cwd: tmpDir,
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status,
+  };
+}
+
+test('writes correlation placeholder for nf-quorum-slot-worker', () => {
+  const tmpDir = makeTmpDir();
+
+  const payload = {
+    agent_type: 'nf-quorum-slot-worker',
+    agent_id: 'agent42',
+  };
+
+  const { exitCode } = runHook(payload, tmpDir);
+  assert.equal(exitCode, 0);
+
+  const corrFile = path.join(tmpDir, '.planning', 'quorum', 'correlations', 'quorum-slot-corr-agent42.json');
+  assert.equal(fs.existsSync(corrFile), true, 'Correlation file should exist');
+
+  const data = JSON.parse(fs.readFileSync(corrFile, 'utf8'));
+  assert.equal(data.agent_id, 'agent42');
+  assert.equal(data.slot, null, 'slot should be null in SubagentStart (prompt not available)');
+  assert.ok(data.ts, 'ts field should be present');
+});
+
+test('non-nf agent type: exits 0, no file written', () => {
+  const tmpDir = makeTmpDir();
+
+  const payload = {
+    agent_type: 'other',
+    agent_id: 'agent99',
+  };
+
+  const { exitCode } = runHook(payload, tmpDir);
+  assert.equal(exitCode, 0);
+
+  const planningDir = path.join(tmpDir, '.planning');
+  // No .planning dir should be created at all
+  const anyFile = fs.existsSync(planningDir);
+  assert.equal(anyFile, false, 'No files should be written for non-nf agents');
+});
+
+test('missing agent_id: exits 0 gracefully', () => {
+  const tmpDir = makeTmpDir();
+
+  const payload = {
+    agent_type: 'nf-quorum-slot-worker',
+    agent_id: null,
+  };
+
+  const { exitCode } = runHook(payload, tmpDir);
+  assert.equal(exitCode, 0);
+  // No crash — exits gracefully when agent_id is null
+});