feat(util): add stateful default-off research loop cap

lib/util/research-loop-cap.mjs

@@ -0,0 +1,144 @@
+// lib/util/research-loop-cap.mjs
+// Stateful, default-off cost cap for the /trekresearch bounded conversation
+// loop (Phase 4.5 dimension discovery + Phase 5 loop turns).
+//
+// Three properties the plan review required:
+//   (a) Default-off — VOYAGE_STORM_ENABLED must be '1'; otherwise the budget
+//       is 0 regardless of effort. This IS the decline branch: doing nothing
+//       leaves the mechanism off, and adopt is flipping this one constant.
+//   (b) The cap counts itself — allowTurn() derives used-turn count from an
+//       append-only JSONL ledger, never from a caller-supplied number. A cap
+//       that asks the caller how many turns it has used is not a cap.
+//   (c) Correct size bound — worst case is max_conv_turns × max_total_dimensions,
+//       where max_total_dimensions is the WHOLE list (interview + discovered)
+//       under settings.json:16's cap of 8 — not × discovered-only.
+//
+// CLAUDE_PLUGIN_DATA absent => DENY (fail-closed). This is the opposite of
+// lib/stats/event-emit.mjs's fail-open: that module is telemetry (must never
+// block workflow); this module is a budget control (must never silently
+// grant unlimited turns just because the data dir is missing).
+//
+// CLI shim:
+//   node lib/util/research-loop-cap.mjs --run-id ID --dimension D --effort E
+//   → JSON: { ok, used, budget, reason? }   (exit 0 = granted, exit 1 = denied)
+
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MAX_CONV_TURNS = 3;
+export const MAX_TOTAL_DIMENSIONS = 8; // settings.json:16 maxDimensions — whole list, not discovered-only
+
+const LEDGER_FILENAME = 'trekresearch-loop-ledger.jsonl';
+
+export function isStormEnabled(env = process.env) {
+  return env.VOYAGE_STORM_ENABLED === '1';
+}
+
+/**
+ * Coerce TREKRESEARCH_MAX_CONV_TURNS. NaN, empty, negative, or zero all fall
+ * back to MAX_CONV_TURNS — never to unbounded.
+ */
+export function resolveMaxConvTurns(env = process.env) {
+  const raw = env.TREKRESEARCH_MAX_CONV_TURNS;
+  if (raw === undefined || raw === null || raw === '') return MAX_CONV_TURNS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return MAX_CONV_TURNS;
+  return Math.floor(n);
+}
+
+export function resolveLedgerPath(env = process.env) {
+  const dir = env.CLAUDE_PLUGIN_DATA;
+  if (!dir || typeof dir !== 'string' || dir.length === 0) return null;
+  return join(dir, LEDGER_FILENAME);
+}
+
+function countTurns(ledgerPath, runId) {
+  if (!existsSync(ledgerPath)) return 0;
+  let text;
+  try { text = readFileSync(ledgerPath, 'utf-8'); }
+  catch { return 0; }
+  let count = 0;
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (rec.runId === runId) count++;
+    } catch { /* skip malformed lines */ }
+  }
+  return count;
+}
+
+/**
+ * Decide whether one more research-loop turn may run. Append-only: never
+ * read-modify-write, because Phase 4.5/5 may spawn multiple agents in a
+ * single message and a read-modify-write counter would lose concurrent
+ * grants.
+ *
+ * @param {{runId: string, dimension: string, effort: string}} args
+ * @param {{env?: object, now?: Date}} [opts]
+ * @returns {{ok: boolean, used: number, budget: number, reason?: string}}
+ */
+export function allowTurn({ runId, dimension, effort } = {}, opts = {}) {
+  const env = opts.env || process.env;
+  const now = opts.now || new Date();
+
+  if (!isStormEnabled(env)) {
+    return { ok: false, used: 0, budget: 0, reason: 'storm_disabled' };
+  }
+  if (effort !== 'high') {
+    return { ok: false, used: 0, budget: 0, reason: 'effort_not_high' };
+  }
+  if (!runId || !dimension) {
+    return { ok: false, used: 0, budget: 0, reason: 'missing_args' };
+  }
+
+  const maxConvTurns = resolveMaxConvTurns(env);
+  const budget = maxConvTurns * MAX_TOTAL_DIMENSIONS;
+
+  const ledgerPath = resolveLedgerPath(env);
+  if (!ledgerPath) {
+    return { ok: false, used: 0, budget, reason: 'no_plugin_data_dir' };
+  }
+
+  const used = countTurns(ledgerPath, runId);
+  if (used >= budget) {
+    return { ok: false, used, budget, reason: 'budget_exhausted' };
+  }
+
+  try {
+    const dir = dirname(ledgerPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(ledgerPath, JSON.stringify({ ts: now.toISOString(), runId, dimension, effort }) + '\n');
+  } catch (e) {
+    return { ok: false, used, budget, reason: `ledger-write-failed: ${e.message}` };
+  }
+
+  return { ok: true, used: used + 1, budget };
+}
+
+// ---- CLI shim ----------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--run-id') out.runId = argv[++i];
+    else if (a === '--dimension') out.dimension = argv[++i];
+    else if (a === '--effort') out.effort = argv[++i];
+  }
+  return out;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.runId || !args.dimension || !args.effort) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      reason: 'usage: research-loop-cap.mjs --run-id ID --dimension D --effort standard|high|low',
+    }) + '\n');
+    process.exit(1);
+  }
+  const result = allowTurn(args);
+  process.stdout.write(JSON.stringify(result) + '\n');
+  process.exit(result.ok ? 0 : 1);
+}

tests/lib/research-loop-cap.test.mjs

@@ -0,0 +1,233 @@
+// tests/lib/research-loop-cap.test.mjs
+// Cover lib/util/research-loop-cap.mjs: default-off, worst-case arithmetic,
+// anti-dead-data (different caps → different denial points), statefulness
+// (identical args → different answers once the budget is hit), env
+// coercion, fail-closed on missing CLAUDE_PLUGIN_DATA, and the CLI shim.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  allowTurn,
+  isStormEnabled,
+  resolveMaxConvTurns,
+  resolveLedgerPath,
+  MAX_CONV_TURNS,
+  MAX_TOTAL_DIMENSIONS,
+} from '../../lib/util/research-loop-cap.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SHIM = join(HERE, '..', '..', 'lib', 'util', 'research-loop-cap.mjs');
+
+function withTmpDataDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'research-loop-cap-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function runShim(args, env) {
+  try {
+    const out = execFileSync(process.execPath, [SHIM, ...args], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, ...env },
+    });
+    return { code: 0, out };
+  } catch (e) {
+    return { code: e.status ?? 1, out: e.stdout?.toString() ?? '' };
+  }
+}
+
+// ---- (a) default-off --------------------------------------------------------
+
+test('allowTurn — VOYAGE_STORM_ENABLED unset denies with budget 0, regardless of effort', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir };
+    const r = allowTurn({ runId: 'r1', dimension: 'd1', effort: 'high' }, { env });
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'storm_disabled');
+    assert.equal(r.budget, 0);
+  });
+});
+
+test('allowTurn — VOYAGE_STORM_ENABLED=0 denies same as unset', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '0' };
+    const r = allowTurn({ runId: 'r1', dimension: 'd1', effort: 'high' }, { env });
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'storm_disabled');
+  });
+});
+
+test('allowTurn — enabled but effort !== high denies with budget 0', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1' };
+    const r = allowTurn({ runId: 'r1', dimension: 'd1', effort: 'standard' }, { env });
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'effort_not_high');
+    assert.equal(r.budget, 0);
+  });
+});
+
+// ---- (f) CLAUDE_PLUGIN_DATA unset => fail-closed deny -----------------------
+
+test('allowTurn — CLAUDE_PLUGIN_DATA unset denies even when enabled + high effort', () => {
+  const env = { VOYAGE_STORM_ENABLED: '1' }; // no CLAUDE_PLUGIN_DATA
+  const r = allowTurn({ runId: 'r1', dimension: 'd1', effort: 'high' }, { env });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_plugin_data_dir');
+  assert.equal(r.budget, MAX_CONV_TURNS * MAX_TOTAL_DIMENSIONS);
+});
+
+// ---- (c) worst-case arithmetic ----------------------------------------------
+
+test('allowTurn — budget is max_conv_turns × max_total_dimensions (default 3×8=24)', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1' };
+    const r = allowTurn({ runId: 'r1', dimension: 'd1', effort: 'high' }, { env });
+    assert.equal(r.ok, true);
+    assert.equal(r.budget, 24);
+    assert.equal(r.used, 1);
+  });
+});
+
+test('allowTurn — grants exactly `budget` turns then denies the next one (default 24)', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1' };
+    let last;
+    for (let i = 0; i < 24; i++) {
+      last = allowTurn({ runId: 'r-exhaust', dimension: `d${i % 8}`, effort: 'high' }, { env });
+      assert.equal(last.ok, true, `turn ${i + 1} should be granted`);
+    }
+    const denied = allowTurn({ runId: 'r-exhaust', dimension: 'd0', effort: 'high' }, { env });
+    assert.equal(denied.ok, false);
+    assert.equal(denied.reason, 'budget_exhausted');
+    assert.equal(denied.used, 24);
+    assert.equal(denied.budget, 24);
+  });
+});
+
+// ---- (c)/(anti-dead-data) — different caps → observably different denial points
+
+test('allowTurn — TREKRESEARCH_MAX_CONV_TURNS=1 denies after 8 turns (1×8), not 24', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1', TREKRESEARCH_MAX_CONV_TURNS: '1' };
+    let last;
+    for (let i = 0; i < 8; i++) {
+      last = allowTurn({ runId: 'r-narrow', dimension: `d${i}`, effort: 'high' }, { env });
+      assert.equal(last.ok, true, `turn ${i + 1} should be granted`);
+    }
+    const denied = allowTurn({ runId: 'r-narrow', dimension: 'd8', effort: 'high' }, { env });
+    assert.equal(denied.ok, false);
+    assert.equal(denied.budget, 8);
+    assert.notEqual(denied.budget, 24, 'a narrower cap must produce a different denial point than the default');
+  });
+});
+
+// ---- (d) stateful — identical args give different answers once exhausted ---
+
+test('allowTurn — identical {runId, dimension, effort} args diverge once the budget is hit (proves statefulness)', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1', TREKRESEARCH_MAX_CONV_TURNS: '1' };
+    const args = { runId: 'r-identical', dimension: 'same-dim', effort: 'high' };
+    const results = [];
+    for (let i = 0; i < 9; i++) results.push(allowTurn(args, { env }));
+    // First 8 (budget = 1*8) granted, 9th denied — same exact input object each time.
+    assert.deepEqual(results.slice(0, 8).map(r => r.ok), Array(8).fill(true));
+    assert.equal(results[8].ok, false);
+    assert.equal(results[8].reason, 'budget_exhausted');
+  });
+});
+
+// ---- (e) env coercion --------------------------------------------------------
+
+test('resolveMaxConvTurns — NaN string falls back to default', () => {
+  assert.equal(resolveMaxConvTurns({ TREKRESEARCH_MAX_CONV_TURNS: 'abc' }), MAX_CONV_TURNS);
+});
+
+test('resolveMaxConvTurns — empty string falls back to default', () => {
+  assert.equal(resolveMaxConvTurns({ TREKRESEARCH_MAX_CONV_TURNS: '' }), MAX_CONV_TURNS);
+});
+
+test('resolveMaxConvTurns — negative value falls back to default', () => {
+  assert.equal(resolveMaxConvTurns({ TREKRESEARCH_MAX_CONV_TURNS: '-5' }), MAX_CONV_TURNS);
+});
+
+test('resolveMaxConvTurns — zero falls back to default (never unbounded)', () => {
+  assert.equal(resolveMaxConvTurns({ TREKRESEARCH_MAX_CONV_TURNS: '0' }), MAX_CONV_TURNS);
+});
+
+test('resolveMaxConvTurns — unset falls back to default', () => {
+  assert.equal(resolveMaxConvTurns({}), MAX_CONV_TURNS);
+});
+
+test('resolveMaxConvTurns — valid positive integer string is honored', () => {
+  assert.equal(resolveMaxConvTurns({ TREKRESEARCH_MAX_CONV_TURNS: '2' }), 2);
+});
+
+// ---- pure-core unit coverage --------------------------------------------------
+
+test('isStormEnabled — only the literal string "1" enables', () => {
+  assert.equal(isStormEnabled({ VOYAGE_STORM_ENABLED: '1' }), true);
+  assert.equal(isStormEnabled({ VOYAGE_STORM_ENABLED: 'true' }), false);
+  assert.equal(isStormEnabled({}), false);
+});
+
+test('resolveLedgerPath — null when CLAUDE_PLUGIN_DATA unset or empty', () => {
+  assert.equal(resolveLedgerPath({}), null);
+  assert.equal(resolveLedgerPath({ CLAUDE_PLUGIN_DATA: '' }), null);
+});
+
+test('resolveLedgerPath — joins CLAUDE_PLUGIN_DATA with the ledger filename', () => {
+  const p = resolveLedgerPath({ CLAUDE_PLUGIN_DATA: '/tmp/plugin-data' });
+  assert.equal(p, join('/tmp/plugin-data', 'trekresearch-loop-ledger.jsonl'));
+});
+
+test('allowTurn — missing runId or dimension denies with missing_args', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1' };
+    const r1 = allowTurn({ dimension: 'd1', effort: 'high' }, { env });
+    assert.equal(r1.ok, false);
+    assert.equal(r1.reason, 'missing_args');
+    const r2 = allowTurn({ runId: 'r1', effort: 'high' }, { env });
+    assert.equal(r2.ok, false);
+    assert.equal(r2.reason, 'missing_args');
+  });
+});
+
+// ---- (g) shim contract --------------------------------------------------------
+
+test('CLI shim — grants and exits 0 when enabled + high effort + budget available', () => {
+  withTmpDataDir((dir) => {
+    const r = runShim(
+      ['--run-id', 'shim-1', '--dimension', 'd1', '--effort', 'high'],
+      { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1' },
+    );
+    assert.equal(r.code, 0);
+    const parsed = JSON.parse(r.out.trim());
+    assert.equal(parsed.ok, true);
+  });
+});
+
+test('CLI shim — denies and exits 1 when disabled', () => {
+  const r = runShim(['--run-id', 'shim-2', '--dimension', 'd1', '--effort', 'high'], { VOYAGE_STORM_ENABLED: '0' });
+  assert.equal(r.code, 1);
+  const parsed = JSON.parse(r.out.trim());
+  assert.equal(parsed.ok, false);
+  assert.equal(parsed.reason, 'storm_disabled');
+});
+
+test('CLI shim — missing required args exits 1 with usage reason', () => {
+  const r = runShim(['--run-id', 'shim-3']);
+  assert.equal(r.code, 1);
+  const parsed = JSON.parse(r.out.trim());
+  assert.equal(parsed.ok, false);
+  assert.match(parsed.reason, /usage:/);
+});