claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/lib/__tests__/landedSinceRun.test.cjs

@@ -0,0 +1,73 @@
+/**
+ * landedSinceRun.test.cjs — the widened, path-scoped commit evidence helper
+ * behind reverifyNeedsReview's looksDone annotation (PRD 1102).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/landedSinceRun.test.cjs
+ */
+
+'use strict';
+
+import { test } from 'vitest';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { landedSinceRun } = require('../landedSinceRun.cjs');
+
+function mkRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'landed-since-run-'));
+  execFileSync('git', ['-C', dir, 'init', '-q']);
+  execFileSync('git', ['-C', dir, 'config', 'user.email', 'test@test.com']);
+  execFileSync('git', ['-C', dir, 'config', 'user.name', 'Test']);
+  return dir;
+}
+
+function commitFile(dir, relPath, content, message) {
+  const abs = path.join(dir, relPath);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+  execFileSync('git', ['-C', dir, 'add', relPath]);
+  execFileSync('git', ['-C', dir, 'commit', '-q', '-m', message]);
+}
+
+test('finds a commit landed after sinceIso that touches a declared path', async () => {
+  const dir = mkRepo();
+  const since = new Date().toISOString();
+  await new Promise((r) => setTimeout(r, 1100)); // git --since has 1s resolution
+  commitFile(dir, 'src/foo.js', 'hello', 'touch foo');
+  const shas = await landedSinceRun(dir, since, ['src/foo.js']);
+  assert.strictEqual(shas.length, 1);
+});
+
+test('ignores a commit that does not touch any declared path', async () => {
+  const dir = mkRepo();
+  const since = new Date().toISOString();
+  await new Promise((r) => setTimeout(r, 1100));
+  commitFile(dir, 'src/unrelated.js', 'hello', 'touch unrelated');
+  const shas = await landedSinceRun(dir, since, ['src/foo.js']);
+  assert.deepStrictEqual(shas, []);
+});
+
+test('empty paths never fabricates evidence — resolves []', async () => {
+  const dir = mkRepo();
+  commitFile(dir, 'src/foo.js', 'hello', 'touch foo');
+  const shas = await landedSinceRun(dir, new Date(0).toISOString(), []);
+  assert.deepStrictEqual(shas, []);
+});
+
+test('no cwd resolves [] without throwing', async () => {
+  const shas = await landedSinceRun(null, new Date().toISOString(), ['src/foo.js']);
+  assert.deepStrictEqual(shas, []);
+});
+
+test('git-unavailable (non-repo cwd) resolves [] without throwing', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'landed-since-run-norepo-'));
+  const shas = await landedSinceRun(dir, new Date().toISOString(), ['src/foo.js']);
+  assert.deepStrictEqual(shas, []);
+});
+
+test('has a bounded default timeout', () => {
+  const { LANDED_SINCE_RUN_TIMEOUT_MS } = require('../landedSinceRun.cjs');
+  assert.ok(LANDED_SINCE_RUN_TIMEOUT_MS > 0 && LANDED_SINCE_RUN_TIMEOUT_MS <= 60_000);
+});

package/src/main/lib/__tests__/launchFailure.test.cjs

@@ -0,0 +1,220 @@
+/**
+ * launchFailure.test.cjs — the non-run classifier + launch circuit breaker
+ * behind GitHub issue #11 (macOS, 2026-09-02): an outdated Claude CLI sent
+ * `thinking.type.enabled`, the API answered HTTP 400 on the first request,
+ * and 12 of 41 runs in one project were recorded as `failed` with
+ * `error: null` and then investigated by a probe that died the same way.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/launchFailure.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const lf = require('../launchFailure.cjs');
+
+// Verbatim shape from the issue-#11 transcript (2c3cd24f-…ccf0eb290fff.jsonl):
+// a single assistant entry that IS the raw API error, then the result event.
+const THINKING_400_RESULT = {
+  type: 'result', subtype: 'error', is_error: true, api_error_status: 400, num_turns: 1,
+  duration_ms: 23811, total_cost_usd: 0,
+  usage: { input_tokens: 0, output_tokens: 0 },
+  result: 'API Error: 400 {"detail":{"error":"{\\"message\\":\\"\\\\\\"thinking.type.enabled\\\\\\" is not supported for this model. Use \\\\\\"thinking.type.adaptive\\\\\\" and \\\\\\"output_config.effort\\\\\\" to control thinking behavior.\\"}"}}',
+};
+
+const REAL_WORK_FAILURE = {
+  type: 'result', subtype: 'error', is_error: true, num_turns: 19,
+  usage: { input_tokens: 4000, output_tokens: 2200 },
+  result: 'Error: expected 2 but got 3\n  at test/foo.test.ts:12:5', terminal_reason: 'error_max_turns',
+};
+
+function tmpLog(lines) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-launch-'));
+  const p = path.join(dir, 'run.log');
+  fs.writeFileSync(p, lines.map((l) => (typeof l === 'string' ? l : JSON.stringify(l))).join('\n') + '\n');
+  return p;
+}
+
+test('parseResultEvent: flattens the last result event with turns/tokens/status', () => {
+  const r = lf.parseResultEvent([
+    '[scheduler] starting foo',
+    JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'API Error: 400 …' }] } }),
+    JSON.stringify(THINKING_400_RESULT),
+  ].join('\n'));
+  expect(r).toMatchObject({ subtype: 'error', isError: true, numTurns: 1, outputTokens: 0, apiErrorStatus: 400 });
+  expect(r.resultText).toMatch(/thinking\.type\.enabled/);
+});
+
+test('parseResultEvent: null when no result event exists (process died first)', () => {
+  expect(lf.parseResultEvent('[scheduler] starting\n{"type":"system","subtype":"init"}\n')).toBeNull();
+  expect(lf.parseResultEvent('')).toBeNull();
+});
+
+test('classifyLaunchFailure: the issue-#11 thinking 400 → model_config_rejected with the API message', () => {
+  const c = lf.classifyLaunchFailure(lf.parseResultEvent(JSON.stringify(THINKING_400_RESULT)));
+  expect(c).not.toBeNull();
+  expect(c.kind).toBe('model_config_rejected');
+  expect(c.httpStatus).toBe(400);
+  expect(c.message).toMatch(/thinking\.type\.enabled.*not supported for this model/);
+  expect(c.message).not.toMatch(/^API Error/);
+});
+
+test('classifyLaunchFailure: a run that took real turns is NEVER a launch failure, even with API Error text', () => {
+  expect(lf.classifyLaunchFailure(lf.parseResultEvent(JSON.stringify(REAL_WORK_FAILURE)))).toBeNull();
+  const lateApiError = { ...THINKING_400_RESULT, num_turns: 7, usage: { output_tokens: 900 } };
+  expect(lf.classifyLaunchFailure(lf.parseResultEvent(JSON.stringify(lateApiError)))).toBeNull();
+});
+
+test('classifyLaunchFailure: zero-turn failure WITHOUT the API Error marker is not classified (someone else owns it)', () => {
+  const r = lf.parseResultEvent(JSON.stringify({ type: 'result', subtype: 'error', is_error: true, num_turns: 1, usage: { output_tokens: 0 }, result: 'Invalid prompt' }));
+  expect(lf.classifyLaunchFailure(r)).toBeNull();
+});
+
+test('classifyLaunchFailure: 429 is left to the rate-limit path', () => {
+  const r = lf.parseResultEvent(JSON.stringify({ type: 'result', subtype: 'error', is_error: true, api_error_status: 429, num_turns: 1, usage: { output_tokens: 0 }, result: 'API Error: 429 {"error":{"message":"rate limited"}}' }));
+  expect(lf.classifyLaunchFailure(r)).toBeNull();
+});
+
+test('classifyLaunchFailure: status → kind mapping', () => {
+  const mk = (status, text) => lf.classifyLaunchFailure(lf.parseResultEvent(JSON.stringify({
+    type: 'result', subtype: 'error', is_error: true, num_turns: 1, usage: { output_tokens: 0 }, result: `API Error: ${status} ${text}`,
+  })));
+  expect(mk(401, '{"error":{"message":"invalid x-api-key"}}').kind).toBe('auth_failed');
+  expect(mk(403, '{"error":{"message":"forbidden"}}').kind).toBe('auth_failed');
+  expect(mk(404, '{"error":{"message":"model: claude-x not found"}}').kind).toBe('model_not_found');
+  expect(mk(400, '{"error":{"message":"max_tokens must be > 0"}}').kind).toBe('bad_request');
+  expect(mk(529, '{"error":{"type":"overloaded_error","message":"Overloaded"}}').kind).toBe('api_overloaded');
+  expect(mk(500, '{"error":{"message":"internal"}}').kind).toBe('api_overloaded');
+  expect(mk(418, 'teapot').kind).toBe('api_error');
+  expect(mk(401, '{"error":{"message":"invalid x-api-key"}}').message).toBe('invalid x-api-key');
+});
+
+test('readResultEvent + classify on a real log tail (scheduler log lines interleaved)', () => {
+  const p = tmpLog([
+    '[scheduler] starting 04-fix-cdp at 2026-09-02T17:54:14.770Z',
+    { type: 'system', subtype: 'init', session_id: 'x' },
+    { type: 'user', message: { content: [{ type: 'text', text: 'PRD body' }] } },
+    { type: 'assistant', message: { content: [{ type: 'text', text: 'API Error: 400 …' }] } },
+    THINKING_400_RESULT,
+    '[scheduler] exit code=1 (raw code=1 signal=null) duration=25s',
+  ]);
+  try {
+    const r = lf.readResultEvent(p);
+    expect(lf.classifyLaunchFailure(r)?.kind).toBe('model_config_rejected');
+    expect(lf.resultShowsRealTurn(r)).toBe(false);
+  } finally {
+    fs.rmSync(path.dirname(p), { recursive: true, force: true });
+  }
+});
+
+test('resultShowsRealTurn: true once a turn or any output token happened', () => {
+  expect(lf.resultShowsRealTurn({ numTurns: 1, outputTokens: 0 })).toBe(false);
+  expect(lf.resultShowsRealTurn({ numTurns: 2, outputTokens: 0 })).toBe(true);
+  expect(lf.resultShowsRealTurn({ numTurns: 1, outputTokens: 12 })).toBe(true);
+  expect(lf.resultShowsRealTurn(null)).toBe(false);
+});
+
+// ─── circuit breaker ────────────────────────────────────────────────────────
+
+const T0 = Date.parse('2026-09-02T18:00:00Z');
+
+test('armLaunchBlock: first failure opens with the kind backoff, a mitigation env, and an operator hint', () => {
+  const b = lf.armLaunchBlock(null, { kind: 'model_config_rejected', httpStatus: 400, message: 'm', now: T0, claudeVersion: '1.0.90', slug: 'a', runId: 'r1' });
+  expect(b.attempts).toBe(1);
+  expect(b.exhausted).toBe(false);
+  expect(Date.parse(b.until) - T0).toBe(lf.backoffMsFor('model_config_rejected', 1));
+  expect(b.mitigationEnv).toEqual({ MAX_THINKING_TOKENS: '0' });
+  expect(b.hint).toMatch(/claude update/);
+  expect(b.claudeVersion).toBe('1.0.90');
+  expect(b.probing).toBeNull();
+});
+
+test('armLaunchBlock: repeated same-kind failures escalate, cap at 60 min, then exhaust (until=null)', () => {
+  let b = null;
+  const seen = [];
+  for (let i = 0; i < lf.LAUNCH_BLOCK_MAX_ATTEMPTS; i++) {
+    b = lf.armLaunchBlock(b, { kind: 'api_error', message: 'x', now: T0 + i * 1000 });
+    seen.push(b.until ? Date.parse(b.until) - (T0 + i * 1000) : null);
+  }
+  expect(b.attempts).toBe(lf.LAUNCH_BLOCK_MAX_ATTEMPTS);
+  expect(b.exhausted).toBe(true);
+  expect(b.until).toBeNull();
+  const finite = seen.filter((x) => x !== null);
+  for (let i = 1; i < finite.length; i++) expect(finite[i]).toBeGreaterThanOrEqual(finite[i - 1]);
+  expect(Math.max(...finite)).toBeLessThanOrEqual(60 * 60_000);
+  expect(b.since).toBe(new Date(T0).toISOString()); // first-failure time survives re-arming
+});
+
+test('armLaunchBlock: a different kind restarts the attempt count', () => {
+  const a = lf.armLaunchBlock(null, { kind: 'api_overloaded', message: 'x', now: T0 });
+  const b = lf.armLaunchBlock(a, { kind: 'api_overloaded', message: 'x', now: T0 + 1 });
+  const c = lf.armLaunchBlock(b, { kind: 'auth_failed', message: 'y', now: T0 + 2 });
+  expect(b.attempts).toBe(2);
+  expect(c.attempts).toBe(1);
+  expect(c.mitigationEnv).toBeNull();
+});
+
+test('evaluateLaunchGate: open → blocked during backoff → probe after → blocked while a probe is in flight', () => {
+  expect(lf.evaluateLaunchGate(null, { now: T0 }).state).toBe('open');
+  const b = lf.armLaunchBlock(null, { kind: 'model_config_rejected', message: 'm', now: T0, claudeVersion: '1.0.90' });
+  expect(lf.evaluateLaunchGate(b, { now: T0 + 1000, claudeVersion: '1.0.90' }).state).toBe('blocked');
+  expect(lf.evaluateLaunchGate(b, { now: T0 + 1000 }).reason).toMatch(/re-probe in \d+ min/);
+  const afterBackoff = Date.parse(b.until) + 1;
+  expect(lf.evaluateLaunchGate(b, { now: afterBackoff, claudeVersion: '1.0.90' }).state).toBe('probe');
+  const probing = { ...b, probing: { slug: 'p', at: new Date(afterBackoff).toISOString() } };
+  const g = lf.evaluateLaunchGate(probing, { now: afterBackoff + 60_000, claudeVersion: '1.0.90' });
+  expect(g.state).toBe('blocked');
+  expect(g.reason).toMatch(/probe p in flight/);
+  // a probe that never reported back goes stale and the gate re-opens to a new probe
+  expect(lf.evaluateLaunchGate(probing, { now: afterBackoff + lf.LAUNCH_PROBE_STALE_MS + 1, claudeVersion: '1.0.90' }).state).toBe('probe');
+});
+
+test('evaluateLaunchGate: a CLI version change short-circuits the backoff (the real fix for issue #11)', () => {
+  const b = lf.armLaunchBlock(null, { kind: 'model_config_rejected', message: 'm', now: T0, claudeVersion: '1.0.90' });
+  const g = lf.evaluateLaunchGate(b, { now: T0 + 1000, claudeVersion: '1.0.128' });
+  expect(g.state).toBe('open');
+  expect(g.reason).toMatch(/cli-version-changed/);
+  // unknown current version (probe failed) → no shortcut, backoff still holds
+  expect(lf.evaluateLaunchGate(b, { now: T0 + 1000, claudeVersion: null }).state).toBe('blocked');
+});
+
+test('evaluateLaunchGate: an exhausted block stays blocked until version change', () => {
+  let b = null;
+  for (let i = 0; i < lf.LAUNCH_BLOCK_MAX_ATTEMPTS; i++) b = lf.armLaunchBlock(b, { kind: 'auth_failed', message: 'x', now: T0, claudeVersion: 'v1' });
+  expect(lf.evaluateLaunchGate(b, { now: T0 + 365 * 24 * 3600_000, claudeVersion: 'v1' }).state).toBe('blocked');
+  expect(lf.evaluateLaunchGate(b, { now: T0 + 1, claudeVersion: 'v2' }).state).toBe('open');
+});
+
+test('launchBlockKeyFor: persona is the key, default when absent', () => {
+  expect(lf.launchBlockKeyFor({ agentType: 'dev-lead' })).toBe('dev-lead');
+  expect(lf.launchBlockKeyFor({})).toBe('default');
+  expect(lf.launchBlockKeyFor(null)).toBe('default');
+});
+
+test('deriveTerminalReason: closed-set taxonomy', () => {
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'completed', exitCode: 0 })).toBe('completed');
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'failed', exitCode: 1 })).toBe('impl_failed:exit_1');
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'failed', exitCode: 143 })).toBe('signal_kill');
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'needs_review', exitCode: 143, sigtermOverride: { status: 'needs_review' } })).toBe('signal_kill_with_commit');
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'needs_review', exitCode: 0, verifyResult: { verdict: 'silent_no_op' } })).toBe('verifier:silent_no_op');
+  expect(lf.deriveTerminalReason({ effectiveStatus: 'needs_review', exitCode: 0, worktreeIntegrationFailure: 'conflict' })).toBe('worktree_integration_failed');
+});
+
+test('writeOutcomeSidecar: writes <slug>.outcome.json atomically and never throws on a bad dir', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-outcome-'));
+  try {
+    const p = lf.writeOutcomeSidecar(dir, '12-foo', { numTurns: 1, outputTokens: 0, terminalReason: 'launch_failure:model_config_rejected' });
+    expect(p).toBe(path.join(dir, '12-foo.outcome.json'));
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+    expect(parsed).toMatchObject({ slug: '12-foo', numTurns: 1, outputTokens: 0, terminalReason: 'launch_failure:model_config_rejected' });
+    expect(parsed.writtenAt).toMatch(/^\d{4}-/);
+    expect(fs.existsSync(`${p}.tmp`)).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  expect(lf.writeOutcomeSidecar('/nonexistent/dir/for/sure', 'x', {})).toBeNull();
+  expect(lf.writeOutcomeSidecar(null, 'x', {})).toBeNull();
+});

package/src/main/lib/__tests__/loadGate.test.cjs

@@ -0,0 +1,159 @@
+'use strict';
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/loadGate.test.cjs
+//
+// PRD 1085 — CPU-load launch gate. The static per-project cap
+// (schedulerBatchProjectCap.test.cjs) cannot see the feedback loop observed
+// 2026-09-01 on starry-night-ships: 4 Godot test batteries under Xvfb,
+// loadavg 12.95 / 14 cores = 0.93, every battery stretching past its
+// executor's timeout and spawning fix-chain reruns that launch more
+// batteries. These tests pin the pure decision, the audit rate-limit and the
+// escalation, with loadavg/cores/clock all injected.
+const assert = require('node:assert/strict');
+const { isLoadGated, createLoadGate, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
+const { loadGateThreshold, LOAD_GATE_PER_CORE } = require('../schedulerConfig.cjs');
+
+const ORIGINAL_ENV = process.env.SM_LOAD_GATE_PER_CORE;
+afterEach(() => {
+  if (ORIGINAL_ENV === undefined) delete process.env.SM_LOAD_GATE_PER_CORE;
+  else process.env.SM_LOAD_GATE_PER_CORE = ORIGINAL_ENV;
+});
+
+// ─── isLoadGated ────────────────────────────────────────────────────────────
+
+test('the live incident shape gates: 12.95 / 14 cores = 0.93 > 0.85', () => {
+  assert.equal(isLoadGated(12.95, 14, 0.85), true);
+});
+
+test('below threshold does not gate', () => {
+  assert.equal(isLoadGated(5, 14, 0.85), false);
+});
+
+test('exactly AT threshold does not gate (strictly greater)', () => {
+  assert.equal(isLoadGated(0.85 * 14, 14, 0.85), false);
+});
+
+test('zero cores never gates (unknown topology must not wedge the queue)', () => {
+  assert.equal(isLoadGated(100, 0, 0.85), false);
+});
+
+test('loadavg [0,0,0] (Windows / unsupported) never gates', () => {
+  assert.equal(isLoadGated(0, 14, 0.85), false);
+});
+
+test('a disabled threshold (0) never gates regardless of load', () => {
+  assert.equal(isLoadGated(1000, 1, 0), false);
+});
+
+// ─── loadGateThreshold (env) ────────────────────────────────────────────────
+
+test('default threshold is the documented 0.85', () => {
+  delete process.env.SM_LOAD_GATE_PER_CORE;
+  assert.equal(LOAD_GATE_PER_CORE, 0.85);
+  assert.equal(loadGateThreshold(), 0.85);
+});
+
+test('SM_LOAD_GATE_PER_CORE is honored and clamped to [0.25, 4]; 0 disables; garbage falls back', () => {
+  process.env.SM_LOAD_GATE_PER_CORE = '1.5';
+  assert.equal(loadGateThreshold(), 1.5);
+  process.env.SM_LOAD_GATE_PER_CORE = '0.01';
+  assert.equal(loadGateThreshold(), 0.25);
+  process.env.SM_LOAD_GATE_PER_CORE = '99';
+  assert.equal(loadGateThreshold(), 4);
+  process.env.SM_LOAD_GATE_PER_CORE = '0';
+  assert.equal(loadGateThreshold(), 0);
+  process.env.SM_LOAD_GATE_PER_CORE = 'banana';
+  assert.equal(loadGateThreshold(), 0.85);
+});
+
+// ─── createLoadGate: decision, 1-minute-only, bypass ───────────────────────
+
+function gateWith({ l1 = 12.95, l5 = 0, l15 = 0, cores = 14, threshold = 0.85, clock }) {
+  let t = clock ?? 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, l5, l15],
+    cores: () => cores,
+    now: () => t,
+    threshold,
+  });
+  return { g, tick: (ms) => { t += ms; } };
+}
+
+test('evaluate() gates on the incident shape and reports ratio/threshold', () => {
+  const { g } = gateWith({});
+  const r = g.evaluate();
+  assert.equal(r.gated, true);
+  assert.equal(r.bypassed, false);
+  assert.equal(r.ratio, 0.925);
+  assert.equal(r.threshold, 0.85);
+  assert.equal(r.loadavg1, 12.95);
+  assert.equal(r.cores, 14);
+});
+
+test('only the 1-minute average is consulted — a saturated 5/15-minute history with a quiet last minute launches', () => {
+  const { g } = gateWith({ l1: 2, l5: 13, l15: 13 });
+  assert.equal(g.evaluate().gated, false);
+});
+
+test('an explicit Run now bypasses the gate but records that it did', () => {
+  const { g } = gateWith({});
+  const r = g.evaluate({ bypass: true });
+  assert.equal(r.gated, false);
+  assert.equal(r.bypassed, true);
+});
+
+test('bypass on an UNgated tick is not reported as a bypass', () => {
+  const { g } = gateWith({ l1: 1 });
+  const r = g.evaluate({ bypass: true });
+  assert.deepEqual([r.gated, r.bypassed], [false, false]);
+});
+
+// ─── audit rate limit + escalation (fake clock) ─────────────────────────────
+
+test('audits once, then not again until AUDIT_INTERVAL_MS has elapsed', () => {
+  const { g, tick } = gateWith({});
+  assert.equal(g.evaluate().shouldAudit, true, 'first gated tick audits');
+  tick(60_000);
+  assert.equal(g.evaluate().shouldAudit, false, '1 min later: silent');
+  tick(AUDIT_INTERVAL_MS - 60_000 - 1);
+  assert.equal(g.evaluate().shouldAudit, false, 'just under the interval: silent');
+  tick(1);
+  assert.equal(g.evaluate().shouldAudit, true, 'at the interval: audits again');
+});
+
+test('an ungated tick never audits', () => {
+  const { g } = gateWith({ l1: 1 });
+  assert.equal(g.evaluate().shouldAudit, false);
+});
+
+test('escalates once the gated stretch exceeds the escalation window, and the stretch resets when load drops', () => {
+  let l1 = 12.95;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    escalateAfterMs: 45 * 60_000,
+  });
+  assert.equal(g.evaluate().escalate, false);
+  t += 44 * 60_000;
+  assert.equal(g.evaluate().escalate, false, 'under 45m: no escalation');
+  t += 60_000;
+  const r = g.evaluate();
+  assert.equal(r.escalate, true, 'at 45m: escalates');
+  assert.equal(r.gatedSinceMs, 45 * 60_000);
+  l1 = 1; t += 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'load dropped: stretch resets');
+  l1 = 12.95; t += 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'a fresh stretch starts from zero');
+});
+
+test('snapshot() reflects the last evaluation and is null before any', () => {
+  const { g } = gateWith({});
+  assert.equal(g.snapshot(), null);
+  g.evaluate();
+  const s = g.snapshot();
+  assert.equal(s.gated, true);
+  assert.equal(typeof s.at, 'string');
+  assert.equal('shouldAudit' in s, false, 'per-tick flags are not part of the persisted snapshot');
+});

package/src/main/lib/__tests__/mcpToolCatalog.test.cjs

@@ -0,0 +1,102 @@
+/**
+ * mcpToolCatalog.test.cjs — parity + shape gate for PRD (mcpToolCatalog):
+ * asserts the catalog and the live scheduler-mcp-server.cjs TOOLS array can
+ * never drift apart, that every catalog entry is a well-formed
+ * documentation record, and that each tool's exampleArgs is actually
+ * runnable against that tool's own inputSchema.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/mcpToolCatalog.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const path = require('node:path');
+const { MCP_TOOL_CATALOG, MCP_RECIPES, CatalogEntrySchema, composeDescription } = require('../mcpToolCatalog.cjs');
+// scheduler-mcp-server.cjs guards its stdio-server main() behind
+// `require.main === module`, so requiring it here (require.main is the test
+// runner, not this file) just loads TOOLS without opening a stdio transport.
+const { TOOLS } = require(path.join(__dirname, '../../../../scripts/scheduler-mcp-server.cjs'));
+
+const LIVE_MCP_TOOL_NAMES = TOOLS.map((t) => t.name);
+
+test('every live MCP tool name has a catalog entry', () => {
+  const catalogNames = new Set(MCP_TOOL_CATALOG.map((e) => e.name));
+  const missing = LIVE_MCP_TOOL_NAMES.filter((n) => !catalogNames.has(n));
+  expect(missing).toEqual([]);
+});
+
+test('every catalog entry corresponds to a live MCP tool', () => {
+  const liveNames = new Set(LIVE_MCP_TOOL_NAMES);
+  const extra = MCP_TOOL_CATALOG.filter((e) => !liveNames.has(e.name)).map((e) => e.name);
+  expect(extra).toEqual([]);
+});
+
+test.each(TOOLS)('$name description is composed from the catalog, not a separate literal', (tool) => {
+  const entry = MCP_TOOL_CATALOG.find((e) => e.name === tool.name);
+  expect(entry).toBeTruthy();
+  expect(tool.description).toBe(composeDescription(entry));
+  expect(tool.description.length).toBeGreaterThan(0);
+});
+
+test.each(MCP_TOOL_CATALOG)('$name has all required catalog fields', (entry) => {
+  expect(() => CatalogEntrySchema.parse(entry)).not.toThrow();
+  expect(entry.name).toBeTruthy();
+  expect(entry.group).toBeTruthy();
+  expect(entry.purpose).toBeTruthy();
+  expect(entry.whenToUse).toBeTruthy();
+  expect(entry.whenNotToUse).toBeTruthy();
+  expect(entry.exampleArgs).toBeTruthy();
+});
+
+test('a catalog entry missing a required field fails schema validation', () => {
+  const broken = {
+    name: 'some_tool',
+    group: 'scheduler',
+    purpose: '',
+    whenToUse: 'x',
+    whenNotToUse: 'y',
+    exampleArgs: {},
+    notes: null,
+  };
+  expect(() => CatalogEntrySchema.parse(broken)).toThrow();
+
+  const missingField = {
+    name: 'some_tool',
+    group: 'scheduler',
+    purpose: 'x',
+    whenToUse: 'y',
+    // whenNotToUse omitted entirely
+    exampleArgs: {},
+    notes: null,
+  };
+  expect(() => CatalogEntrySchema.parse(missingField)).toThrow();
+});
+
+test.each(MCP_TOOL_CATALOG)('$name composeDescription joins purpose/whenToUse/whenNotToUse/notes deterministically', (entry) => {
+  const expected = [entry.purpose, entry.whenToUse, entry.whenNotToUse, entry.notes].filter(Boolean).join(' ');
+  expect(composeDescription(entry)).toBe(expected);
+  expect(composeDescription(entry).length).toBeGreaterThan(0);
+});
+
+test('MCP_RECIPES covers queue-work, unstick-needs-review, and hand-off-to-another-project', () => {
+  const ids = MCP_RECIPES.map((r) => r.id);
+  expect(ids).toContain('queue-work-via-develop');
+  expect(ids).toContain('unstick-needs-review-job');
+  expect(ids).toContain('hand-finding-to-another-project');
+  expect(ids).toContain('generate-project-home');
+  for (const recipe of MCP_RECIPES) {
+    expect(recipe.title).toBeTruthy();
+    expect(Array.isArray(recipe.steps)).toBe(true);
+    expect(recipe.steps.length).toBeGreaterThan(0);
+  }
+});
+
+test.each(MCP_TOOL_CATALOG)('$name exampleArgs satisfies its own inputSchema required fields', (entry) => {
+  const tool = TOOLS.find((t) => t.name === entry.name);
+  expect(tool).toBeTruthy();
+  const required = tool.inputSchema?.required ?? [];
+  for (const key of required) {
+    expect(Object.prototype.hasOwnProperty.call(entry.exampleArgs, key)).toBe(true);
+    expect(entry.exampleArgs[key]).not.toBeUndefined();
+  }
+});

package/src/main/lib/__tests__/opsOwnership.test.cjs

@@ -27,6 +27,12 @@ test('the owner of a namespace may write it', () => {
   assert.equal(checkOpsWrite(`${P}/prompt-sessions/active-index.json`, 'epics').ok, true);
   assert.equal(checkOpsWrite(`${P}/scheduler/state/queue.json`, 'scheduler').ok, true);
   assert.equal(checkOpsWrite(`${P}/project-brief/brief.json`, 'project-home').ok, true);
+  // project-pages: declared owner is 'project-home', same as project-brief —
+  // this governs only the app's own /admin/project-home/render write path
+  // (config.cjs), NOT a project-home-builder Epic's own Write-tool authoring
+  // of summary.json/picks.json, which never goes through config.cjs at all
+  // and so is unaffected by this table either way (see project-pages/README.md).
+  assert.equal(checkOpsWrite(`${P}/project-pages/output/manifest.json`, 'project-home').ok, true);
 });
 
 test('a non-owner is refused, and the error names the owner', () => {
@@ -36,6 +42,7 @@ test('a non-owner is refused, and the error names the owner', () => {
   // The exact cross-write this law exists to prevent: another surface
   // rewriting the Epic store out from under Epics.
   assert.equal(checkOpsWrite(`${P}/prompt-sessions/psess-1.json`, 'scheduler').ok, false);
+  assert.equal(checkOpsWrite(`${P}/project-pages/output/manifest.json`, 'scheduler').ok, false);
 });
 
 test('an undeclared writer is refused (fail-closed)', () => {