claude-code-session-manager 0.75.3 → 0.76.0

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

@@ -0,0 +1,217 @@
+/**
+ * schedulerMcpServerHelp.test.cjs — session_manager_help argument handling
+ * (none/tool/topic/unknown/both) and the pointer-suffix contract every
+ * isError return in scheduler-mcp-server.cjs now carries. Also covers the
+ * "app not running" degradation: the static catalog must still answer even
+ * when the admin API is unreachable — only the readiness section may report
+ * unavailable.
+ *
+ * TOKEN_PATH (scripts/scheduler-mcp-server.cjs) is computed once, at
+ * require-time, from os.homedir(). Since os.homedir() reads process.env.HOME
+ * on POSIX, each test temporarily repoints HOME at a fresh tmp dir, clears
+ * the require cache, and re-requires the module so TOKEN_PATH resolves under
+ * that tmp dir — never touching the real ~/.claude/session-manager/admin-api.json.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerMcpServerHelp.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 tmpDirs = [];
+const servers = [];
+let originalHome;
+
+afterEach(async () => {
+  if (originalHome !== undefined) {
+    process.env.HOME = originalHome;
+    originalHome = 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-help-'));
+  tmpDirs.push(d);
+  return d;
+}
+
+/** Starts a fake admin HTTP server answering GET /admin/mcp/readiness. */
+function startFakeAdminServer(token, readinessBody) {
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      if (req.headers.authorization !== `Bearer ${token}`) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'bad token' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(readinessBody));
+    });
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+/** Requires a fresh scheduler-mcp-server.cjs with TOKEN_PATH under `homeDir`. */
+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('session_manager_help with no arguments returns grouped tool list + recipe titles + readiness', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const server = await startFakeAdminServer(token, { ok: true, ready: true, checks: [{ id: 'scheduler-mcp', ok: true }] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', {});
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(Array.isArray(body.tools)).toBe(true);
+  expect(body.tools.some((t) => t.name === 'session_manager_help')).toBe(true);
+  expect(Array.isArray(body.recipes)).toBe(true);
+  expect(body.recipes.some((r) => r.id === 'queue-work-via-develop')).toBe(true);
+  expect(body.tool).toBeUndefined();
+  expect(body.recipe).toBeUndefined();
+  expect(body.readiness.available).toBe(true);
+  expect(body.readiness.ok).toBe(true);
+});
+
+test('session_manager_help with a valid tool returns that entry including exampleArgs', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const server = await startFakeAdminServer(token, { ok: true, ready: true, checks: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', { tool: 'scheduler_create_prd' });
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(body.tool.name).toBe('scheduler_create_prd');
+  expect(body.tool.exampleArgs).toBeTruthy();
+  expect(body.tools).toBeUndefined();
+});
+
+test('session_manager_help with a valid topic returns that recipe\'s steps', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const server = await startFakeAdminServer(token, { ok: true, ready: true, checks: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', { topic: 'unstick-needs-review-job' });
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(body.recipe.id).toBe('unstick-needs-review-job');
+  expect(Array.isArray(body.recipe.steps)).toBe(true);
+  expect(body.recipe.steps.length).toBeGreaterThan(0);
+});
+
+test('session_manager_help accepts both tool and topic together, returning both sections', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const server = await startFakeAdminServer(token, { ok: true, ready: true, checks: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', {
+    tool: 'scheduler_list_jobs',
+    topic: 'queue-work-via-develop',
+  });
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(body.tool.name).toBe('scheduler_list_jobs');
+  expect(body.recipe.id).toBe('queue-work-via-develop');
+});
+
+test('session_manager_help with an unknown tool returns a helpful error listing valid names', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', { tool: 'not_a_real_tool' });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('not_a_real_tool');
+  expect(result.content[0].text).toContain('scheduler_create_prd');
+  expect(result.content[0].text).toContain('call session_manager_help for the correct usage');
+});
+
+test('session_manager_help with an unknown topic returns a helpful error listing valid ids', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', { topic: 'not-a-real-recipe' });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('not-a-real-recipe');
+  expect(result.content[0].text).toContain('queue-work-via-develop');
+});
+
+test('session_manager_help still returns the static catalog when the app is not running, with readiness unavailable', async () => {
+  // No admin-api.json written under this tmp HOME at all — simulates the app
+  // being down. The catalog is bundled in-process, so this must NOT fail
+  // wholesale; only the readiness half degrades.
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'session_manager_help', {});
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(Array.isArray(body.tools)).toBe(true);
+  expect(body.tools.length).toBeGreaterThan(0);
+  expect(body.readiness.available).toBe(false);
+  expect(typeof body.readiness.reason).toBe('string');
+  expect(body.readiness.reason.length).toBeGreaterThan(0);
+});
+
+test('every isError return from the tool handler carries the session_manager_help pointer', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+
+  const missingSlug = await callTool(handleCallTool, 'scheduler_reset_job', {});
+  expect(missingSlug.isError).toBe(true);
+  expect(missingSlug.content[0].text).toContain('call session_manager_help for the correct usage');
+
+  const unknownTool = await callTool(handleCallTool, 'not_a_tool_at_all', {});
+  expect(unknownTool.isError).toBe(true);
+  expect(unknownTool.content[0].text).toContain('call session_manager_help for the correct usage');
+});
+
+test('NOT_RUNNING_ERROR (app not running) carries the pointer and is surfaced via isError', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool, NOT_RUNNING_ERROR } = requireServerWithHome(homeDir);
+  expect(NOT_RUNNING_ERROR).toContain('call session_manager_help for the correct usage');
+
+  const result = await callTool(handleCallTool, 'scheduler_list_jobs', {});
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toBe(NOT_RUNNING_ERROR);
+});

package/src/main/lib/activeIndexMerge.cjs

@@ -36,6 +36,7 @@
 const path = require('path');
 const { activeIndexPath, withPathLock } = require('./epicMint.cjs');
 const config = require('../config.cjs');
+const { mirrorEpicStatus } = require('./epicStatusMirror.cjs');
 
 function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
@@ -160,6 +161,20 @@ async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events:
     // payload, so a compromised/forged renderer call can't claim a
     // different writer id.
     await config.writeJson(filePath, index, { writer: 'epics' });
+    // Status mirror (epicStatusMirror.cjs) — this IPC handler is the
+    // renderer-driven persist path (persistActiveIndex), the write site for
+    // both the 'proposed'->'active' start transition (approveProposed) and
+    // every other in-place session mutation. Mirrors every surviving row so
+    // a lost/clobbered active-index.json can be reconstructed from these
+    // files (activeIndexRebuild.cjs). Best-effort per row: one bad write must
+    // not undo the index write that already landed above.
+    for (const [id, sess] of Object.entries(mergedSessions)) {
+      try {
+        mirrorEpicStatus(cwd, id, { session: sess, status: sess.status });
+      } catch (e) {
+        console.warn(`[activeIndexMerge] mirrorEpicStatus failed for ${id}`, e);
+      }
+    }
     return { sessions: mergedSessions, events: mergedEvents };
   });
 }

package/src/main/lib/activeIndexRebuild.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * activeIndexRebuild.cjs — reconstructs `active-index.json` from the
+ * per-Epic status mirrors `epicStatusMirror.cjs` writes onto `prompt-
+ * sessions/<epicId>.json`. This is the recovery path for the incident the
+ * mirror exists to survive: a lost, clobbered, git-reverted, or
+ * worktree-snapshotted index that would otherwise silently erase every open
+ * Epic it held with no way to get them back.
+ *
+ * Rebuild NEVER mints — SINGLE-CREATOR LAW (epicMint.cjs) is untouched
+ * because no new Epic id is ever created here, only rows for ids that
+ * already have a mirrored file re-materialized. It also never resurrects a
+ * tombstoned or archived Epic (see the two "never resurrect" guards below) —
+ * a human's delete/complete decision always wins.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { activeIndexPath, readActiveIndex, writeActiveIndex, withPathLock } = require('./epicMint.cjs');
+
+function promptSessionsDir(cwd) {
+  const { opsPath } = require('./opsOwnership.cjs');
+  return opsPath(cwd, 'prompt-sessions');
+}
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function listMirrorFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter((f) => f.endsWith('.json') && f !== 'active-index.json');
+}
+
+/**
+ * rebuildActiveIndex(cwd, { dryRun? }) → { rows, skipped, reasons }
+ *
+ * `rows` — reconstructed PromptSession objects, one per mirrored file that
+ *   is a live (proposed/active), non-tombstoned, non-archived Epic. These
+ *   become the new `sessions` map (dryRun: false is the default — pass
+ *   `{ dryRun: true }` to preview without writing).
+ * `skipped` — file names not turned into a row.
+ * `reasons` — `{ [fileName]: humanReadableReason }`, one entry per skipped
+ *   file. A file is never guessed at: no mirrored `status` is a skip, not a
+ *   fabricated 'unknown' row (see scripts/mirror-epic-status.cjs for the
+ *   only place that vocabulary is deliberately introduced, for the
+ *   migration's own back-fill bookkeeping).
+ *
+ * `events` and `tombstones` from the existing on-disk index (if any) are
+ * carried through completely untouched — this function only ever
+ * reconstructs `sessions`.
+ */
+function rebuildActiveIndex(cwd, { dryRun = false } = {}) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('rebuildActiveIndex: cwd is required');
+  cwd = path.resolve(cwd);
+  return withPathLock(activeIndexPath(cwd), () => {
+    const dir = promptSessionsDir(cwd);
+    const existing = readActiveIndex(cwd);
+    const tombstones = existing.tombstones || {};
+    const files = listMirrorFiles(dir);
+
+    const rows = [];
+    const skipped = [];
+    const reasons = {};
+
+    for (const file of files) {
+      const id = file.slice(0, -'.json'.length);
+      const full = path.join(dir, file);
+      let parsed;
+      try {
+        parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+      } catch (e) {
+        skipped.push(file);
+        reasons[file] = `unreadable: ${e.message}`;
+        continue;
+      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        skipped.push(file);
+        reasons[file] = 'unreadable: not a JSON object';
+        continue;
+      }
+      // Never resurrected — a tombstoned id stays out even if its file says
+      // 'active' (see activeIndexMerge.cjs's header on why tombstones are
+      // never auto-cleared).
+      if (hasOwn(tombstones, id)) {
+        skipped.push(file);
+        reasons[file] = 'tombstoned — never resurrected by a rebuild';
+        continue;
+      }
+      if (!parsed.status) {
+        skipped.push(file);
+        reasons[file] = 'no status mirror on this file — never guessed at';
+        continue;
+      }
+      // A completed archive (markCompleted's PromptSessionArchive, or any
+      // mirror written after archival) is never restored as a live row.
+      if (parsed.archivedAt) {
+        skipped.push(file);
+        reasons[file] = 'archivedAt is set — completed Epic, not a live row';
+        continue;
+      }
+      if (parsed.status !== 'proposed' && parsed.status !== 'active') {
+        skipped.push(file);
+        reasons[file] = `status '${parsed.status}' is not a live row`;
+        continue;
+      }
+      // Drop mirror-only bookkeeping (`indexedAt`) — it is not part of the
+      // PromptSession shape active-index.json's `sessions` map holds.
+      const { indexedAt, archivedAt, ...row } = parsed;
+      rows.push({ ...row, id, cwd: parsed.cwd || cwd });
+    }
+
+    if (!dryRun) {
+      const sessions = {};
+      for (const row of rows) sessions[row.id] = row;
+      writeActiveIndex(cwd, {
+        sessions,
+        events: existing.events || {},
+        tombstones,
+      });
+    }
+
+    return { rows, skipped, reasons };
+  });
+}
+
+module.exports = { rebuildActiveIndex };

package/src/main/lib/buildTarget.cjs

@@ -30,7 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const BUILD_TARGET_SUBPATH = ['session-manager-operations', 'architecture', 'build-target.json'];
+const BUILD_TARGET_SUBPATH = ['architecture', 'build-target.json']; // joined under opsOwnership.opsPath
 
 function readJson(filePath) {
   try {
@@ -48,7 +48,8 @@ function readJson(filePath) {
 function resolveBuildTarget(cwd) {
   if (!cwd || typeof cwd !== 'string') return null;
 
-  const configPath = path.join(cwd, ...BUILD_TARGET_SUBPATH);
+  const { opsPath } = require('./opsOwnership.cjs');
+  const configPath = opsPath(cwd, ...BUILD_TARGET_SUBPATH);
   const explicit = readJson(configPath);
   if (explicit && typeof explicit === 'object' && !Array.isArray(explicit) && typeof explicit.packageName === 'string') {
     return explicit;

package/src/main/lib/childWithLog.cjs

@@ -49,6 +49,10 @@
 const fs = require('node:fs');
 const { spawn } = 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.
+const POST_EXIT_GROUP_SWEEP_GRACE_MS = 5000;
+
 // ---------- Phase 1 ----------
 
 /**
@@ -119,6 +123,33 @@ function openLog(logPath) {
  * }} opts
  * @returns {{ child: import('child_process').ChildProcess | null, cancel: () => void }}
  */
+// Post-exit process-group sweep.
+//
+// Incident (2026-08-31, ~/Projects/starry-night-ships): scheduler jobs spawn
+// detached: true, and every watchdog path (result-tail, deadman, idle-tail)
+// kills the whole process group via ctx.killTree — but only on an *overrun*
+// exit. When the executor child exits normally, nothing swept the group, so
+// anything the agent had backgrounded to work around the foreground call cap
+// (the `bash -c '<gate> > /tmp/x.log; echo $? > /tmp/x.done'` shape) reparented
+// to init and kept running for nobody: three orphaned test batteries at PPID 1
+// were found, one burning ~5 cores for 56 minutes. The invariant this restores:
+// 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.
+function sweepChildProcessGroup(child, detached) {
+  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;
+
+  try { process.kill(-child.pid, 'SIGTERM'); } catch { /* ESRCH: empty group, the normal case */ }
+
+  const t = setTimeout(() => {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { /* ESRCH: empty group, the normal case */ }
+  }, POST_EXIT_GROUP_SWEEP_GRACE_MS);
+  if (t.unref) t.unref();
+}
+
 function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watchdogs = [], onExit }) {
   const startedAt = Date.now();
 
@@ -183,6 +214,7 @@ function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watc
         safeLog,
       });
     }
+    sweepChildProcessGroup(ctx.child, !!spawnSpec.options?.detached);
     closeFd();
   };
 
@@ -215,4 +247,4 @@ function withChildAndLog({ fd, logPath, safeLog, closeFd, spawn: spawnSpec, watc
   return { child, cancel };
 }
 
-module.exports = { openLog, withChildAndLog };
+module.exports = { openLog, withChildAndLog, POST_EXIT_GROUP_SWEEP_GRACE_MS };

package/src/main/lib/crossProjectFeedback.cjs

@@ -66,6 +66,7 @@ const {
 } = require('./epicMint.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
 const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
+const { resolveProjectContext } = require('./projectRootResolve.cjs');
 
 /** Only these three Epic tags make sense for an inbound report — they are
  *  exactly the tags that route through /develop (tagLibrary.ts). 'build',
@@ -251,8 +252,14 @@ function validateFeedbackInput(input = {}) {
   } catch (e) {
     return bad(400, `toCwd rejected: ${e.message}`);
   }
+  // Normalize fromCwd (worktree -> main tree, ops-internal path -> project
+  // root) BEFORE validatePath/the same-project check below — an agent
+  // sending feedback from inside its own Epic's worktree pwd must be
+  // compared/chained against its REAL project, not the ephemeral checkout.
+  // See projectRootResolve.cjs's header.
+  const normalizedFromCwd = resolveProjectContext({ cwd: input.fromCwd }).cwd || input.fromCwd;
   try {
-    fromCwd = config.validatePath(path.resolve(input.fromCwd));
+    fromCwd = config.validatePath(path.resolve(normalizedFromCwd));
   } catch (e) {
     return bad(400, `fromCwd rejected: ${e.message}`);
   }