claude-code-session-manager 0.76.0 → 0.77.0

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

@@ -0,0 +1,350 @@
+/**
+ * schedulerMcpServerProjectHome.test.cjs — the four project_home_* MCP
+ * tools (PRD: project-home-mcp-tools) that wrap PRD 1089's admin routes.
+ * Covers: presence in TOOLS, catalog-composed descriptions, correct
+ * route/payload dispatch via a stubbed admin HTTP server, cwd defaulting to
+ * SM_PROJECT_ROOT/process.cwd() when omitted, the app-not-running failure
+ * shape, and that project_home_get_contract's composed response is
+ * self-sufficient (mentions all 5 lens ids, no repo-relative path).
+ *
+ * Same HOME-repointing pattern as schedulerMcpServerHelp.test.cjs — see that
+ * file's header for why.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerMcpServerProjectHome.test.cjs
+ */
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const http = require('node:http');
+const os = require('node:os');
+const path = require('node:path');
+
+const SERVER_PATH = path.join(__dirname, '../../../../scripts/scheduler-mcp-server.cjs');
+const { MCP_TOOL_CATALOG, composeDescription } = require('../mcpToolCatalog.cjs');
+
+const PROJECT_HOME_TOOL_NAMES = [
+  'project_home_get_contract',
+  'project_home_validate_summary',
+  'project_home_render',
+  'project_home_status',
+];
+
+const tmpDirs = [];
+const servers = [];
+let originalHome;
+let originalProjectRoot;
+
+afterEach(async () => {
+  if (originalHome !== undefined) {
+    process.env.HOME = originalHome;
+    originalHome = undefined;
+  }
+  if (originalProjectRoot !== undefined) {
+    if (originalProjectRoot === null) delete process.env.SM_PROJECT_ROOT;
+    else process.env.SM_PROJECT_ROOT = originalProjectRoot;
+    originalProjectRoot = undefined;
+  }
+  delete require.cache[require.resolve(SERVER_PATH)];
+  while (servers.length) {
+    const s = servers.pop();
+    await new Promise((resolve) => s.close(resolve));
+  }
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkTmp() {
+  const d = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-mcp-project-home-'));
+  tmpDirs.push(d);
+  return d;
+}
+
+/** Starts a fake admin HTTP server that records every request and answers with `body`. */
+function startFakeAdminServer(token, body) {
+  const requests = [];
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      const chunks = [];
+      req.on('data', (c) => chunks.push(c));
+      req.on('end', () => {
+        if (req.headers.authorization !== `Bearer ${token}`) {
+          res.writeHead(401, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'bad token' }));
+          return;
+        }
+        const raw = Buffer.concat(chunks).toString('utf8');
+        requests.push({
+          method: req.method,
+          url: req.url,
+          body: raw ? JSON.parse(raw) : undefined,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(body));
+      });
+    });
+    server.listen(0, '127.0.0.1', () => resolve({ server, requests }));
+  });
+}
+
+function requireServerWithHome(homeDir) {
+  originalHome = process.env.HOME;
+  process.env.HOME = homeDir;
+  delete require.cache[require.resolve(SERVER_PATH)];
+  const mod = require(SERVER_PATH);
+  process.env.HOME = originalHome;
+  originalHome = undefined;
+  return mod;
+}
+
+async function writeAdminConfig(homeDir, { port, token }) {
+  const tokenPath = path.join(homeDir, '.claude', 'session-manager', 'admin-api.json');
+  await fsp.mkdir(path.dirname(tokenPath), { recursive: true });
+  await fsp.writeFile(tokenPath, JSON.stringify({ port, token }), 'utf8');
+}
+
+function callTool(handleCallTool, name, args) {
+  return handleCallTool({ params: { name, arguments: args } });
+}
+
+test('all four project_home_* tools are present in TOOLS with correct input schemas', async () => {
+  const homeDir = await mkTmp();
+  const { TOOLS } = requireServerWithHome(homeDir);
+  for (const name of PROJECT_HOME_TOOL_NAMES) {
+    const tool = TOOLS.find((t) => t.name === name);
+    expect(tool).toBeTruthy();
+    expect(tool.inputSchema.type).toBe('object');
+    expect(tool.inputSchema.properties.cwd).toBeTruthy();
+    // cwd is never required on any of the four
+    expect(tool.inputSchema.required ?? []).not.toContain('cwd');
+  }
+  const validate = TOOLS.find((t) => t.name === 'project_home_validate_summary');
+  expect(validate.inputSchema.required).toContain('summary');
+  const render = TOOLS.find((t) => t.name === 'project_home_render');
+  expect(render.inputSchema.required).toEqual(expect.arrayContaining(['summary', 'picks']));
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s description equals the catalog-composed string', async (name) => {
+  const homeDir = await mkTmp();
+  const { TOOLS } = requireServerWithHome(homeDir);
+  const tool = TOOLS.find((t) => t.name === name);
+  const entry = MCP_TOOL_CATALOG.find((e) => e.name === name);
+  expect(entry).toBeTruthy();
+  expect(entry.group).toBe('project-home');
+  expect(tool.description).toBe(composeDescription(entry));
+});
+
+test('project_home_get_contract dispatches GET /admin/project-home/contract with cwd query param', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    protocol: ['step one'],
+    catalog: { lenses: [{ id: 'home' }, { id: 'marketing' }, { id: 'feature' }, { id: 'architecture' }, { id: 'brief' }] },
+    paths: { summaryPath: '/abs/summary.json', picksPath: '/abs/picks.json', outputDir: '/abs/output' },
+    spec: { text: 'spec text', path: '/abs/spec.md' },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_get_contract', { cwd: '/home/bilko/Projects/session-manager' });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('GET');
+  expect(requests[0].url).toBe('/admin/project-home/contract?cwd=%2Fhome%2Fbilko%2FProjects%2Fsession-manager');
+});
+
+test('project_home_get_contract composed response mentions all 5 lens ids and no repo-relative path', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server } = await startFakeAdminServer(token, {
+    ok: true,
+    protocol: [
+      'Call GET /admin/project-home/status?cwd=<abs> first.',
+      'Compose a ProjectPageSummary matching summarySchema.',
+      'For each lens in catalog.lenses, pick a variant per slot.',
+      'POST /admin/project-home/validate-summary with {cwd, summary}.',
+      'POST /admin/project-home/render with {cwd, summary, picks}.',
+    ],
+    summarySchema: { type: 'object' },
+    picksSchema: { type: 'object' },
+    catalog: {
+      lenses: [
+        { id: 'home', slots: [] },
+        { id: 'marketing', slots: [] },
+        { id: 'feature', slots: [] },
+        { id: 'architecture', slots: [] },
+        { id: 'brief', slots: [] },
+      ],
+    },
+    paths: { summaryPath: '/abs/project-pages/summary.json', picksPath: '/abs/project-pages/picks.json', outputDir: '/abs/project-pages/output' },
+    spec: { text: 'This project uses absolute paths only, never repo-relative ones.', path: '/abs/project-pages-pipeline.md' },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_get_contract', {});
+  expect(result.isError).toBeFalsy();
+  const text = result.content[0].text;
+  for (const lens of ['home', 'marketing', 'feature', 'architecture', 'brief']) {
+    expect(text).toContain(lens);
+  }
+  expect(text).not.toMatch(/session-manager-operations\/architecture\//);
+  expect(text).not.toMatch(/\.claude\/agents\//);
+});
+
+test('project_home_validate_summary dispatches POST /admin/project-home/validate-summary with cwd+summary', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, { ok: true, valid: true, errors: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const summary = { title: 'Example Project' };
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary,
+  });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('POST');
+  expect(requests[0].url).toBe('/admin/project-home/validate-summary');
+  expect(requests[0].body).toEqual({ cwd: '/home/bilko/Projects/session-manager', summary });
+});
+
+test('project_home_validate_summary surfaces per-field errors from the route, not a generic failure', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server } = await startFakeAdminServer(token, {
+    ok: true,
+    valid: false,
+    errors: [{ field: 'quotes[0].attribution', message: 'quotes[0].attribution must not be a placeholder value' }],
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary: { title: 'x', quotes: [{ attribution: 'TODO' }] },
+  });
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(body.valid).toBe(false);
+  expect(body.errors).toEqual([
+    { field: 'quotes[0].attribution', message: 'quotes[0].attribution must not be a placeholder value' },
+  ]);
+});
+
+test('project_home_validate_summary requires summary', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', { cwd: '/x' });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('summary');
+});
+
+test('project_home_render dispatches POST /admin/project-home/render with cwd+summary+picks', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    filesWritten: ['/abs/summary.json'],
+    generatedAt: '2026-09-01T00:00:00.000Z',
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const summary = { title: 'Example Project' };
+  const picks = { home: { hero: 'variant-a' } };
+  const result = await callTool(handleCallTool, 'project_home_render', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary,
+    picks,
+  });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('POST');
+  expect(requests[0].url).toBe('/admin/project-home/render');
+  expect(requests[0].body).toEqual({ cwd: '/home/bilko/Projects/session-manager', summary, picks });
+});
+
+test('project_home_render requires both summary and picks', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+
+  const missingSummary = await callTool(handleCallTool, 'project_home_render', { picks: {} });
+  expect(missingSummary.isError).toBe(true);
+  expect(missingSummary.content[0].text).toContain('summary');
+
+  const missingPicks = await callTool(handleCallTool, 'project_home_render', { summary: {} });
+  expect(missingPicks.isError).toBe(true);
+  expect(missingPicks.content[0].text).toContain('picks');
+});
+
+test('project_home_status dispatches GET /admin/project-home/status with cwd query param', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    summary: { exists: false, mtimeMs: null },
+    picks: { exists: false, mtimeMs: null },
+    output: {
+      home: { exists: false, mtimeMs: null },
+      marketing: { exists: false, mtimeMs: null },
+      feature: { exists: false, mtimeMs: null },
+      architecture: { exists: false, mtimeMs: null },
+      brief: { exists: false, mtimeMs: null },
+    },
+    manifest: { exists: false, generatedAt: null },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_status', { cwd: '/home/bilko/Projects/session-manager' });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('GET');
+  expect(requests[0].url).toBe('/admin/project-home/status?cwd=%2Fhome%2Fbilko%2FProjects%2Fsession-manager');
+
+  // Never-generated project: well-formed all-absent result, not an error.
+  const body = JSON.parse(result.content[0].text);
+  expect(body.ok).toBe(true);
+  expect(body.summary.exists).toBe(false);
+  expect(body.manifest.exists).toBe(false);
+  expect(body.output.brief.exists).toBe(false);
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s defaults cwd to SM_PROJECT_ROOT when omitted', async (name) => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, { ok: true, valid: true, errors: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  originalProjectRoot = process.env.SM_PROJECT_ROOT ?? null;
+  process.env.SM_PROJECT_ROOT = '/home/bilko/Projects/session-manager/session-manager-operations/scheduler/epics/some-epic/worktree';
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const args = name === 'project_home_render' ? { summary: {}, picks: {} } : name === 'project_home_validate_summary' ? { summary: {} } : {};
+  await callTool(handleCallTool, name, args);
+  expect(requests).toHaveLength(1);
+  const encoded = requests[0].body?.cwd ?? new URLSearchParams(requests[0].url.split('?')[1]).get('cwd');
+  expect(encoded).toBe(process.env.SM_PROJECT_ROOT);
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s returns the app-not-running error when the admin API is unreachable', async (name) => {
+  const homeDir = await mkTmp();
+  const { handleCallTool, NOT_RUNNING_ERROR } = requireServerWithHome(homeDir);
+  const args = name === 'project_home_render' ? { summary: {}, picks: {} } : name === 'project_home_validate_summary' ? { summary: {} } : {};
+  const result = await callTool(handleCallTool, name, args);
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toBe(NOT_RUNNING_ERROR);
+});

package/src/main/lib/agentModelResolve.cjs

@@ -120,9 +120,67 @@ function resolveEpicModel({ cwd, claudeSessionId, fallbackModel = FALLBACK_MODEL
   }
 }
 
+/** Mirrors epicIntake.ts's AGENT_BODY_CHAR_CAP — a runaway persona file must
+ *  not be able to dominate a spawned job's system prompt either. Duplicated
+ *  rather than imported: epicIntake.ts is a renderer module (no ES modules
+ *  in main). */
+const AGENT_BODY_CHAR_CAP = 6000;
+
+/** Trims a persona's frontmatter-stripped body and caps it at
+ *  AGENT_BODY_CHAR_CAP, appending a truncation notice naming `personaPath`
+ *  — same shape as epicIntake.ts's buildPersonaBodyText. Returns null for an
+ *  empty body. */
+function buildPersonaBodyText(rawBody, personaPath) {
+  const body = (rawBody || '').trim();
+  if (!body) return null;
+  if (body.length <= AGENT_BODY_CHAR_CAP) return body;
+  const truncated = body.slice(0, AGENT_BODY_CHAR_CAP);
+  const pathLabel = personaPath || 'the persona file';
+  return `${truncated}\n\n[Truncated — ${pathLabel} exceeds ${AGENT_BODY_CHAR_CAP} characters; see the file for the full body.]`;
+}
+
+/**
+ * Resolves the persona system-prompt + model a scheduled PRD's `agentType`
+ * should launch its headless `claude -p` spawn with. Never throws — a
+ * missing agentType, or one that no longer resolves to a readable persona
+ * file (renamed/deleted), falls back to `{ systemPrompt: null, model:
+ * fallbackModel, personaPath: null }` and logs once via prdAgentType.cjs's
+ * reportDanglingAgentTypeOnce (the PRD-frontmatter FK's own dangling-read
+ * convention) — a dangling persona must never park or fail the job.
+ *
+ * Reuses agentLibrary.cjs's getPersonaBody (project-overlay-then-global
+ * read, same precedence resolvePersonaPaths documents) rather than a second
+ * persona-file reader, and this module's own frontmatter-stripped-body cap
+ * (mirroring epicIntake.ts's Epic-path treatment) so the PRD path gets the
+ * same runaway-file protection.
+ *
+ * @param {{ cwd: string, agentType: string|null, fallbackModel?: string, deps?: object }} opts
+ * @returns {Promise<{ model: string, systemPrompt: string|null, personaPath: string|null }>}
+ */
+async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLBACK_MODEL, deps = {} } = {}) {
+  const miss = { model: fallbackModel, systemPrompt: null, personaPath: null };
+  if (!agentType) return miss;
+  try {
+    const getBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
+    const persona = await getBody({ cwd, name: agentType });
+    if (!persona) {
+      const reportOnce = deps.reportDanglingAgentTypeOnce || require('./prdAgentType.cjs').reportDanglingAgentTypeOnce;
+      reportOnce(cwd, agentType, deps);
+      return miss;
+    }
+    const { fm, body } = splitFrontmatter(persona.text);
+    const model = fm.model && fm.model !== 'inherit' ? fm.model : fallbackModel;
+    const systemPrompt = buildPersonaBodyText(body, persona.path);
+    return { model, systemPrompt, personaPath: persona.path };
+  } catch {
+    return miss;
+  }
+}
+
 module.exports = {
   FALLBACK_MODEL,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
   readPersonaModel,
+  resolvePrdPersonaForSpawn,
 };

package/src/main/lib/childWithLog.cjs

@@ -40,6 +40,10 @@
  *   killedByWatchdog — string | null
  *   error         — Error | undefined (child 'error' event or sync spawn throw)
  *   spawnFailed   — boolean, true when the error came from a synchronous spawn throw
+ *   leakedDescendants — { pid, pcpu, etimes, comm }[], the process-group survivors
+ *                       sweepChildProcessGroup found still alive right before it
+ *                       swept them. [] in the normal case (nothing leaked, or
+ *                       non-Linux, or enumeration failed). See sweepChildProcessGroup.
  *   safeLog       — same safeLog (usable inside onExit for final log lines)
  *
  * Returns { child, cancel } where cancel() clears all timers + SIGKILLs.
@@ -47,7 +51,7 @@
  */
 
 const fs = require('node:fs');
-const { spawn } = require('node:child_process');
+const { spawn, execFileSync } = require('node:child_process');
 
 // Grace period between the post-exit SIGTERM sweep and the follow-up SIGKILL
 // sweep of a detached child's process group. See sweepChildProcessGroup below.
@@ -136,11 +140,39 @@ function openLog(logPath) {
 // a job's descendants must not outlive the job. Killing the job's own process
 // group at the job's own exit is ownership-based and needs no /proc heuristics
 // to distinguish an abandoned descendant from a live one.
+// Enumerate the still-alive members of process group `pgid` (Linux only).
+// Read-only — never throws, never blocks the caller's exit path. Used to
+// report what sweepChildProcessGroup is about to kill, since the kill itself
+// is silent (ESRCH on the normal empty-group case).
+function enumerateProcessGroupSurvivors(pgid) {
+  if (process.platform !== 'linux') return [];
+  if (!pgid || pgid <= 1) return [];
+  try {
+    const out = execFileSync('ps', ['-eo', 'pid,pgrp,pcpu,etimes,comm'], { encoding: 'utf8', timeout: 2000 });
+    const survivors = [];
+    for (const line of out.split('\n').slice(1)) {
+      const m = line.trim().match(/^(\d+)\s+(\d+)\s+([\d.]+)\s+(\d+)\s+(.+)$/);
+      if (!m) continue;
+      const [, pidStr, pgrpStr, pcpuStr, etimesStr, comm] = m;
+      if (Number(pgrpStr) !== pgid) continue;
+      survivors.push({ pid: Number(pidStr), pcpu: Number(pcpuStr), etimes: Number(etimesStr), comm });
+    }
+    return survivors;
+  } catch {
+    return [];
+  }
+}
+
+// Returns the leaked descendants found (see enumerateProcessGroupSurvivors),
+// having enumerated them BEFORE issuing SIGTERM so the report reflects what
+// was actually swept, not what happened to still be running afterward.
 function sweepChildProcessGroup(child, detached) {
-  if (!detached) return;
-  if (!child || !child.pid || child.pid <= 1) return;
+  if (!detached) return [];
+  if (!child || !child.pid || child.pid <= 1) return [];
   // Defensive: never target the Session Manager process's own group.
-  if (child.pid === process.pid) return;
+  if (child.pid === process.pid) return [];
+
+  const leaked = enumerateProcessGroupSurvivors(child.pid).filter((p) => p.pid !== child.pid);
 
   try { process.kill(-child.pid, 'SIGTERM'); } catch { /* ESRCH: empty group, the normal case */ }
 
@@ -148,6 +180,8 @@ function sweepChildProcessGroup(child, detached) {
     try { process.kill(-child.pid, 'SIGKILL'); } catch { /* ESRCH: empty group, the normal case */ }
   }, POST_EXIT_GROUP_SWEEP_GRACE_MS);
   if (t.unref) t.unref();
+
+  return leaked;
 }
 
 function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watchdogs = [], onExit }) {
@@ -204,6 +238,7 @@ function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watc
   // calls onExit (caller may still safeLog inside), then closes the fd.
   const handleDone = (exitCode, signal, error, spawnFailed) => {
     clearAllTimers();
+    const leakedDescendants = sweepChildProcessGroup(ctx.child, !!spawnSpec.options?.detached);
     if (onExit) {
       onExit({
         exitCode,
@@ -211,10 +246,10 @@ function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watc
         killedByWatchdog: ctx.killedByWatchdog,
         error,
         spawnFailed: spawnFailed ?? false,
+        leakedDescendants,
         safeLog,
       });
     }
-    sweepChildProcessGroup(ctx.child, !!spawnSpec.options?.detached);
     closeFd();
   };
 

package/src/main/lib/claudeBin.cjs

@@ -39,4 +39,57 @@ function resolveClaudeBin() {
   return cached;
 }
 
-module.exports = { resolveClaudeBin };
+// ---------- version probe ----------
+//
+// `claude --version`, cached. The scheduler's launch circuit breaker
+// (lib/launchFailure.cjs) records the CLI version a launch block was armed
+// under and drops the block the moment the version changes — the incident
+// behind it (issue #11: an outdated CLI sending a thinking parameter the
+// model rejects) is fixed by `claude update`, and the queue must notice
+// that without a human pressing anything. Async, bounded, never throws:
+// a probe failure yields null and the breaker simply loses the
+// version-change shortcut (backoff still recovers).
+const VERSION_TTL_MS = 5 * 60_000;
+const VERSION_PROBE_TIMEOUT_MS = 8_000;
+let versionCache = { at: 0, value: null, inflight: null };
+
+function probeClaudeVersion({ now = Date.now(), execFileImpl } = {}) {
+  // Operator/test pin: skips executing the binary entirely.
+  if (process.env.SM_CLAUDE_VERSION) return Promise.resolve(process.env.SM_CLAUDE_VERSION);
+  if (versionCache.inflight) return versionCache.inflight;
+  if (versionCache.value !== null && now - versionCache.at < VERSION_TTL_MS) {
+    return Promise.resolve(versionCache.value);
+  }
+  const execFile = execFileImpl || require('node:child_process').execFile;
+  const bin = resolveClaudeBin();
+  versionCache.inflight = new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      versionCache = { at: Date.now(), value, inflight: null };
+      resolve(value);
+    };
+    try {
+      // cwd is a neutral temp dir on purpose: the version does not depend on
+      // it, and the binary must never be handed the caller's working tree —
+      // a stub `claude` (tests point SM_CLAUDE_BIN at one) that writes
+      // markers or commits into process.cwd() once did so in the real repo.
+      execFile(bin, ['--version'], { timeout: VERSION_PROBE_TIMEOUT_MS, windowsHide: true, cwd: os.tmpdir() }, (err, stdout) => {
+        if (err) return done(null);
+        const m = /(\d+\.\d+\.\d+[^\s]*)/.exec(String(stdout || ''));
+        done(m ? m[1] : (String(stdout || '').trim() || null));
+      });
+    } catch {
+      done(null);
+    }
+  });
+  return versionCache.inflight;
+}
+
+/** Test hook — forget the cached version so the next probe re-executes. */
+function resetClaudeVersionCache() {
+  versionCache = { at: 0, value: null, inflight: null };
+}
+
+module.exports = { resolveClaudeBin, probeClaudeVersion, resetClaudeVersionCache };

package/src/main/lib/definitionOfDone.cjs

@@ -328,7 +328,7 @@ const RISK_HEURISTICS = [
  * @param {string} headingText  Case-insensitive heading to find.
  * @returns {string}
  */
-function _extractSection(body, headingText) {
+function extractSection(body, headingText) {
   const escapedHeading = headingText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const headingRe = new RegExp(`^#+\\s+${escapedHeading}`, 'i');
   const lines = body.split('\n');
@@ -398,7 +398,7 @@ function flagRiskySurfaces(jobs, { prdsDir, gitTimeoutMs = 10_000 } = {}) {
       try {
         const raw = fs.readFileSync(path.join(resolvedPrdsDir, `${job.slug}.md`), 'utf8');
         const body = splitFrontmatter(raw).body;
-        candidateText = _extractSection(body, 'Implementation notes');
+        candidateText = extractSection(body, 'Implementation notes');
       } catch { /* no candidate text — skip */ }
     }
 
@@ -573,6 +573,7 @@ module.exports = {
   reportPathFor,
   reportExists,
   extractAcCommand,
+  extractSection,
   reverifyAc,
   reverifyBatch,
   flagRiskySurfaces,