claude-code-session-manager 0.75.3 → 0.76.0

package/src/main/health.cjs

@@ -9,13 +9,16 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { execFileSync } = require('node:child_process');
-const { POLL_INTERVAL_MS } = require('./lib/schedulerConfig.cjs');
+const { POLL_INTERVAL_MS, loadGateThreshold } = require('./lib/schedulerConfig.cjs');
+const { opsPath } = require('./lib/opsOwnership.cjs');
 const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
+const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
 const { computeStallSummary } = require('./scheduler.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
+const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -225,6 +228,113 @@ function evaluatePrdMigrationHealth(migrationResult, legacyPrdsDir) {
   };
 }
 
+// Pure shaping of checkDelegationReadiness()'s result (delegationReadiness.cjs)
+// into a health component + issue lines — kept separate from the fs-touching
+// check() call site so it's directly unit-testable, matching
+// evaluatePrdMigrationHealth's pattern. delegationReadiness.cjs already wraps
+// every filesystem read (readJsonSafe / try-catch), so a missing/unreadable
+// config surfaces here as one of `checks` with ok:false, never a throw.
+function evaluateDelegationChainHealth(delegationResult) {
+  const component = { ok: delegationResult.ok, checks: delegationResult.checks };
+  const issues = delegationResult.checks
+    .filter((c) => !c.ok)
+    .map((c) => `Delegation readiness: ${c.label} failed — ${c.detail}${c.fix ? ` (fix: ${c.fix})` : ''}`);
+  return { component, issues };
+}
+
+// computeEpicIndexDrift(cwd) → { orphan_rows, orphan_files, unmirrored,
+//   orphanRowIds, orphanFileIds, unmirroredFiles }
+//
+// One project's drift between active-index.json (the index) and prompt-
+// sessions/<id>.json (the status mirror epicStatusMirror.cjs writes on every
+// status-changing write path). Pure filesystem read, never throws — an
+// unreadable index or prompt-sessions dir degrades to empty rather than
+// aborting the whole health check (matches evaluatePrdMigrationHealth's
+// fail-open-on-read spirit).
+function computeEpicIndexDrift(cwd) {
+  let dir;
+  try {
+    dir = opsPath(cwd, 'prompt-sessions');
+  } catch {
+    return { orphan_rows: 0, orphan_files: 0, unmirrored: 0 }; // unusable cwd degrades to empty, same as an unreadable index below
+  }
+  const indexPath = path.join(dir, 'active-index.json');
+  let sessions = {};
+  let tombstones = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    sessions = parsed && typeof parsed.sessions === 'object' && parsed.sessions ? parsed.sessions : {};
+    tombstones = parsed && typeof parsed.tombstones === 'object' && parsed.tombstones ? parsed.tombstones : {};
+  } catch { /* missing/unreadable index — treat as empty, not a throw */ }
+
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') && f !== 'active-index.json');
+  } catch { /* prompt-sessions/ doesn't exist yet — nothing to compare */ }
+
+  const fileIds = new Set(files.map((f) => f.slice(0, -'.json'.length)));
+  const orphanRowIds = Object.keys(sessions).filter((id) => !fileIds.has(id));
+
+  const orphanFileIds = [];
+  const unmirroredFiles = [];
+  for (const file of files) {
+    const id = file.slice(0, -'.json'.length);
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    } catch {
+      continue; // unreadable file — neither orphan nor unmirrored classification applies
+    }
+    if (!parsed || typeof parsed !== 'object' || !parsed.status) {
+      unmirroredFiles.push(file);
+      continue;
+    }
+    const looksLive = (parsed.status === 'proposed' || parsed.status === 'active') && !parsed.archivedAt;
+    const hasRow = Object.prototype.hasOwnProperty.call(sessions, id);
+    const isTombstoned = Object.prototype.hasOwnProperty.call(tombstones, id);
+    if (looksLive && !hasRow && !isTombstoned) orphanFileIds.push(file);
+  }
+
+  return {
+    orphan_rows: orphanRowIds.length,
+    orphan_files: orphanFileIds.length,
+    unmirrored: unmirroredFiles.length,
+    orphanRowIds,
+    orphanFileIds,
+    unmirroredFiles,
+  };
+}
+
+// evaluateEpicIndexHealth(cwds) → { component, issues }
+//
+// Shapes computeEpicIndexDrift's per-project result into a health component +
+// issue lines, matching evaluateDelegationChainHealth's pattern. Only
+// orphan_rows (an index row whose Epic file is gone — the actual data-loss
+// signal) is an issue; orphan_files and unmirrored are informational drift,
+// not failures — a fresh install or an Epic mid-migration legitimately has
+// unmirrored files.
+function evaluateEpicIndexHealth(cwds) {
+  const byProject = {};
+  const issues = [];
+  let anyOrphanRows = false;
+  for (const cwd of cwds) {
+    const drift = computeEpicIndexDrift(cwd);
+    byProject[cwd] = {
+      orphan_rows: drift.orphan_rows,
+      orphan_files: drift.orphan_files,
+      unmirrored: drift.unmirrored,
+    };
+    if (drift.orphan_rows > 0) {
+      anyOrphanRows = true;
+      issues.push(
+        `Epic index drift: ${cwd} has ${drift.orphan_rows} active-index.json row(s) with no matching `
+        + `prompt-sessions/<id>.json file (${drift.orphanRowIds.join(', ')})`
+      );
+    }
+  }
+  return { component: { ok: !anyOrphanRows, byProject }, issues };
+}
+
 async function check() {
   const start = Date.now();
   const status = {
@@ -340,6 +450,15 @@ async function check() {
       byProject: computeProjectProblemCounts(queueState.jobs),
       perProjectStall,
       tickLiveness: liveness.reason,
+      // Informational only (PRD 1085): current 1-min loadavg per core vs the
+      // launch-gate threshold, so a "nothing is launching" report can be
+      // read next to the reason without opening the app.
+      loadRatio: (() => {
+        const cores = (os.cpus() || []).length;
+        const l1 = os.loadavg()[0];
+        return cores > 0 && Number.isFinite(l1) ? Number((l1 / cores).toFixed(3)) : null;
+      })(),
+      loadGateThreshold: loadGateThreshold(),
     };
     if (liveness.stalled) {
       const ageMin = Math.round(liveness.tickAgeMs / 60_000);
@@ -505,6 +624,22 @@ async function check() {
     }
   }
 
+  // 6.55. Delegation-chain readiness — answers "can this machine actually
+  // delegate work to the scheduler?" (see delegationReadiness.cjs's header:
+  // when the scheduler MCP isn't registered, scheduler_create_prd is simply
+  // absent from the agent's tool list — no error to catch, so an agent asked
+  // to delegate just implements inline instead). Critical: a failing check
+  // here means Epics silently stop queueing PRDs on this machine.
+  try {
+    const delegation = await checkDelegationReadiness({ cwd: PROJECT_ROOT });
+    const { component, issues: delegationIssues } = evaluateDelegationChainHealth(delegation);
+    status.components.delegation_chain = component;
+    status.issues.push(...delegationIssues);
+  } catch (e) {
+    status.components.delegation_chain = { ok: false, error: e.message };
+    status.issues.push(`Delegation readiness check failed: ${e.message}`);
+  }
+
   // 6.6. Run-log retention report (informational only — never blocks health).
   // Read-only against the REAL scheduled-plans/runs/ dir: reports current
   // usage + what the configured policy (if any) would remove. Nothing is
@@ -536,11 +671,24 @@ async function check() {
     status.components.run_log_retention = { ok: true, error: e.message };
   }
 
+  // 6.65. Epic index drift — orphan_rows/orphan_files/unmirrored across every
+  // project this machine has ever opened (allProjectCwds, no recency filter
+  // — a quiet project still owns its Epics). See computeEpicIndexDrift's
+  // header.
+  try {
+    const { component, issues: epicIndexIssues } = evaluateEpicIndexHealth(allProjectCwds());
+    status.components.epic_index = component;
+    status.issues.push(...epicIndexIssues);
+  } catch (e) {
+    status.components.epic_index = { ok: false, error: e.message };
+    status.issues.push(`Epic index health check failed: ${e.message}`);
+  }
+
   // 7. Summary scoring: ok if all critical components pass.
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration', 'claude_md_budget'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -561,6 +709,9 @@ module.exports = {
   evaluateTickLiveness,
   readFreshHeartbeat,
   evaluatePrdMigrationHealth,
+  evaluateDelegationChainHealth,
+  computeEpicIndexDrift,
+  evaluateEpicIndexHealth,
   computeProjectProblemCounts,
   evaluatePerProjectStall,
   parseClaudeMdBudget,

package/src/main/index.cjs

@@ -36,7 +36,8 @@ const epicWorktreeMint = require('./lib/epicWorktreeMint.cjs');
 const epicWorktreeMerge = require('./lib/epicWorktreeMerge.cjs');
 const epicWorktreeProjectConfig = require('./lib/epicWorktreeProjectConfig.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
-const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
+const { checkDelegationReadiness, installPrdWriteGuard } = require('./lib/delegationReadiness.cjs');
+const { MCP_TOOL_CATALOG, MCP_RECIPES } = require('./lib/mcpToolCatalog.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const crossProjectFeedback = require('./lib/crossProjectFeedback.cjs');
@@ -81,6 +82,9 @@ const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');
 const { openInEditor, openFileInEditor, openInFinder, openInTerminal } = require('./lib/openExternalApp.cjs');
+const { rebuildActiveIndex } = require('./lib/activeIndexRebuild.cjs');
+const { activeIndexPath: promptSessionsActiveIndexPath } = require('./lib/epicMint.cjs');
+const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
 let mainWindow = null;
 let rebooting = false;
@@ -456,6 +460,11 @@ ipcMain.handle('app:launch-mode', () => ({
 // `claude mcp list`. Read-only, single in-flight call — no polling.
 ipcMain.handle('mcp:status', () => probeMcpStatus());
 
+// Project Home's "Agent tools" block (PhAgentTools): the same catalog data
+// GET /admin/mcp/catalog serves to external callers, read in-process here so
+// the renderer never makes a direct HTTP call. Static data, no cwd needed.
+ipcMain.handle('mcp:catalog', () => ({ ok: true, tools: MCP_TOOL_CATALOG, recipes: MCP_RECIPES }));
+
 // Agent Library nav page (Home face only): global `~/.claude/agents/*.md`
 // personas plus, per currently-open project tab, whether that project
 // overlays the same agent name at `<cwd>/.claude/agents/<name>.md`. Read-only.
@@ -494,12 +503,19 @@ ipcMain.handle('agents:get-persona-body', validated(schemas.agentsGetPersonaBody
   agentLibrary.getPersonaBody(payload)));
 
 // "Can this project actually delegate?" probe (PRD: delegation-readiness).
-// Structured data over the four preconditions for scheduler_create_prd being
-// in an agent's tool list at all — surfacing it in the UI is a sibling PRD.
-ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, (payload) =>
+// Structured data over the preconditions for scheduler_create_prd being in an
+// agent's tool list at all — surfacing it in the UI is a sibling PRD.
+ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, async (payload) =>
   checkDelegationReadiness(payload)
 ));
 
+// The one readiness check with a sanctioned one-press install. Session Manager
+// standardizes on the REFERENCE approach (absolute path to this repo's guard
+// script, never a vendored copy) — see installPrdWriteGuard's header.
+ipcMain.handle('app:install-prd-write-guard', validated(schemas.delegationReadinessCwd, (payload) =>
+  installPrdWriteGuard(payload)
+));
+
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 
 // Boot diagnostics — renderer polls these to surface toasts when `claude` isn't
@@ -1193,6 +1209,42 @@ app.whenReady().then(async () => {
   seedSchedulerMcp({ logger: console, writeLog: logs.writeLine }).catch((e) => {
     logs.writeLine({ scope: 'seed-scheduler-mcp', level: 'error', message: 'seed failed', meta: { error: e?.message } });
   });
+  // Epic index self-heal: a project whose active-index.json is MISSING or
+  // fails to parse has lost every open Epic's status unless the per-Epic
+  // status mirror (epicStatusMirror.cjs) can rebuild it. Runs once per boot,
+  // fire-and-forget, and only touches a project whose index reads unclean —
+  // a clean index is never rewritten here. See activeIndexRebuild.cjs.
+  try {
+    for (const projectCwd of allProjectCwds()) {
+      const indexPath = promptSessionsActiveIndexPath(projectCwd);
+      let unclean = false;
+      let parseError = null;
+      if (!fs.existsSync(indexPath)) {
+        unclean = true;
+      } else {
+        try {
+          JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        } catch (e) {
+          unclean = true;
+          parseError = e.message;
+        }
+      }
+      if (!unclean) continue;
+      try {
+        const { rows, skipped } = rebuildActiveIndex(projectCwd);
+        logs.writeLine({
+          scope: 'active-index-rebuild',
+          level: 'info',
+          message: 'rebuilt active-index.json from status mirrors',
+          meta: { cwd: projectCwd, parseError, restored: rows.length, skipped: skipped.length },
+        });
+      } catch (e) {
+        logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'rebuild failed', meta: { cwd: projectCwd, error: e?.message } });
+      }
+    }
+  } catch (e) {
+    logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'boot sweep failed', meta: { error: e?.message } });
+  }
   // History rollup finalize pass: deferred 30s past boot so it never competes
   // with first-paint, fire-and-forget (cron/offline refresh is PRD 651 — this
   // is just the one-shot in-app pass).

package/src/main/ipcSchemas.cjs

@@ -301,7 +301,12 @@ const PRD_CREATE_SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const NO_NEWLINE_RE = /^[^\r\n]*$/;
 const schedulerCreatePrd = z.object({
   title: z.string().min(1).max(200).regex(NO_NEWLINE_RE, 'must not contain newlines'),
-  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines'),
+  // Optional (PRD: worktree-cwd Epic-lookup hazard) — when omitted, prdCreate.cjs's
+  // createPrd resolves the real project cwd server-side via
+  // projectRootResolve.cjs's resolveProjectContext, using originClaudeSessionId/
+  // sourcePromptId/originProjectRoot. A call with none of those still fails with
+  // a clear "cwd is required" error.
+  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   estimateMinutes: z.number().int().min(1).max(100000),
   goal: z.string().min(1).max(20000),
   acceptanceCriteria: z.array(z.string().min(1).max(2000)).min(1).max(100),
@@ -333,6 +338,13 @@ const schedulerCreatePrd = z.object({
   // within an Epic's own chat session joins that Epic even if the tool call
   // forgot to pass sourcePromptId explicitly.
   originClaudeSessionId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // Trusted project-root hint (SM_PROJECT_ROOT env, stamped by chatRunner.cjs/
+  // pty.cjs/scheduler.cjs's job spawn onto the child that ultimately calls this
+  // route, forwarded by scheduler-mcp-server.cjs as originProjectRoot) — never
+  // written to frontmatter; projectRootResolve.cjs's resolveProjectContext
+  // treats it as a higher-priority hint than the caller-supplied cwd, but
+  // still loses to a resolved Epic's own project cwd.
+  originProjectRoot: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // User-selected work-type tag (PRD 774; independence from the parent
   // Epic's own tag confirmed PRD 1041) — deterministic, never LLM-classified.
   // Epic tag and PRD tag draw on the same WorkType vocabulary
@@ -343,8 +355,12 @@ const schedulerCreatePrd = z.object({
 });
 
 // Bulk archive: slug list, capped to limit unbounded retag/archive payloads.
+// Optional cwd narrows every slug's directory search to one project (same
+// role as scheduler_get_prd/scheduler_update_prd's cwd hint) — omitted, the
+// search still spans every candidate PRD dir machine-wide.
 const scheduleArchivePrd = z.object({
   slugs: z.array(z.string().regex(SCHEDULE_SLUG_RE)).min(1).max(500),
+  cwd: z.string().min(1).max(4096).optional(),
 });
 
 const scheduleRetagItem = z.object({
@@ -425,6 +441,7 @@ const adminUpdatePrd = z.object({
 
 const adminCancelJob = z.object({
   slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
 });
 
 // ──────────────────────────────────────────── Projects

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

@@ -0,0 +1,179 @@
+/**
+ * activeIndexRebuild.test.cjs — rebuildActiveIndex reconstructs
+ * active-index.json's `sessions` map from the per-Epic status mirrors
+ * epicStatusMirror.cjs writes, honoring tombstones and archivedAt exactly
+ * the way the domain model requires (never resurrecting either).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/activeIndexRebuild.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { rebuildActiveIndex } = require('../activeIndexRebuild.cjs');
+const { activeIndexPath, readActiveIndex } = require('../epicMint.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkCwd() {
+  const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-rebuild-cwd-'));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+function promptSessionsDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'prompt-sessions');
+}
+
+function writeMirrorFile(cwd, id, data) {
+  const dir = promptSessionsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${id}.json`), JSON.stringify(data, null, 2));
+}
+
+function writeIndex(cwd, index) {
+  const dir = promptSessionsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'active-index.json'), JSON.stringify(index, null, 2));
+}
+
+function liveMirror(id, cwd, overrides = {}) {
+  return {
+    id,
+    cwd,
+    goalText: `goal for ${id}`,
+    claudeSessionId: `sess-${id}`,
+    status: 'proposed',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    completedAt: null,
+    archivedAt: null,
+    indexedAt: '2026-01-01T00:00:01.000Z',
+    ...overrides,
+  };
+}
+
+test('restores a row for every mirrored file with a live status', async () => {
+  const cwd = await mkCwd();
+  writeMirrorFile(cwd, 'e-1', liveMirror('e-1', cwd, { status: 'proposed' }));
+  writeMirrorFile(cwd, 'e-2', liveMirror('e-2', cwd, { status: 'active' }));
+
+  const { rows, skipped, reasons } = await rebuildActiveIndex(cwd);
+
+  expect(rows.map((r) => r.id).sort()).toEqual(['e-1', 'e-2']);
+  expect(skipped).toEqual([]);
+  expect(reasons).toEqual({});
+
+  const onDisk = readActiveIndex(cwd);
+  expect(onDisk.sessions['e-1'].status).toBe('proposed');
+  expect(onDisk.sessions['e-2'].status).toBe('active');
+});
+
+test('respects tombstones — a tombstoned id is never resurrected even if its file says active', async () => {
+  const cwd = await mkCwd();
+  writeIndex(cwd, { sessions: {}, events: {}, tombstones: { 'e-dead': '2026-01-02T00:00:00.000Z' } });
+  writeMirrorFile(cwd, 'e-dead', liveMirror('e-dead', cwd, { status: 'active' }));
+  writeMirrorFile(cwd, 'e-alive', liveMirror('e-alive', cwd, { status: 'proposed' }));
+
+  const { rows, skipped, reasons } = await rebuildActiveIndex(cwd);
+
+  expect(rows.map((r) => r.id)).toEqual(['e-alive']);
+  expect(skipped).toContain('e-dead.json');
+  expect(reasons['e-dead.json']).toMatch(/tombstoned/);
+
+  const onDisk = readActiveIndex(cwd);
+  expect(onDisk.sessions['e-dead']).toBeUndefined();
+  expect(onDisk.tombstones['e-dead']).toBe('2026-01-02T00:00:00.000Z');
+});
+
+test('respects archivedAt — a completed Epic file is never restored as a live row', async () => {
+  const cwd = await mkCwd();
+  writeMirrorFile(cwd, 'e-done', {
+    ...liveMirror('e-done', cwd, { status: 'completed' }),
+    archivedAt: '2026-01-03T00:00:00.000Z',
+  });
+  writeMirrorFile(cwd, 'e-open', liveMirror('e-open', cwd, { status: 'active' }));
+
+  const { rows, skipped, reasons } = await rebuildActiveIndex(cwd);
+
+  expect(rows.map((r) => r.id)).toEqual(['e-open']);
+  expect(skipped).toContain('e-done.json');
+  expect(reasons['e-done.json']).toMatch(/archivedAt/);
+});
+
+test('is idempotent — running it twice on a clean project yields a byte-identical index', async () => {
+  const cwd = await mkCwd();
+  writeMirrorFile(cwd, 'e-1', liveMirror('e-1', cwd));
+  writeMirrorFile(cwd, 'e-2', liveMirror('e-2', cwd, { status: 'active' }));
+
+  await rebuildActiveIndex(cwd);
+  const first = fs.readFileSync(activeIndexPath(cwd), 'utf8');
+
+  await rebuildActiveIndex(cwd);
+  const second = fs.readFileSync(activeIndexPath(cwd), 'utf8');
+
+  expect(second).toBe(first);
+});
+
+test('skips an unreadable Epic file, naming it in reasons, without aborting the rebuild', async () => {
+  const cwd = await mkCwd();
+  const dir = promptSessionsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'e-corrupt.json'), '{ this is not json');
+  writeMirrorFile(cwd, 'e-good', liveMirror('e-good', cwd));
+
+  const { rows, skipped, reasons } = await rebuildActiveIndex(cwd);
+
+  expect(rows.map((r) => r.id)).toEqual(['e-good']);
+  expect(skipped).toContain('e-corrupt.json');
+  expect(reasons['e-corrupt.json']).toMatch(/unreadable/);
+});
+
+test('a file with no mirrored status is skipped and listed with a reason, never guessed at', async () => {
+  const cwd = await mkCwd();
+  const dir = promptSessionsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'e-legacy.json'), JSON.stringify({ id: 'e-legacy', cwd }));
+
+  const { rows, skipped, reasons } = await rebuildActiveIndex(cwd);
+
+  expect(rows).toEqual([]);
+  expect(skipped).toContain('e-legacy.json');
+  expect(reasons['e-legacy.json']).toMatch(/no status mirror/);
+});
+
+test('preserves the existing events and tombstones maps untouched', async () => {
+  const cwd = await mkCwd();
+  const events = { 'e-1': [{ id: 'evt-1', promptSessionId: 'e-1', kind: 'prompt', causedByEventId: null, at: '2026-01-01T00:00:00.000Z', text: 'go' }] };
+  const tombstones = { 'e-old': '2026-01-01T00:00:00.000Z' };
+  writeIndex(cwd, { sessions: {}, events, tombstones });
+  writeMirrorFile(cwd, 'e-1', liveMirror('e-1', cwd));
+
+  await rebuildActiveIndex(cwd);
+
+  const onDisk = readActiveIndex(cwd);
+  expect(onDisk.events).toEqual(events);
+  expect(onDisk.tombstones).toEqual(tombstones);
+});
+
+test('dryRun previews without writing anything to disk', async () => {
+  const cwd = await mkCwd();
+  writeIndex(cwd, { sessions: {}, events: {}, tombstones: {} });
+  writeMirrorFile(cwd, 'e-1', liveMirror('e-1', cwd));
+
+  const before = fs.readFileSync(activeIndexPath(cwd), 'utf8');
+  const { rows } = await rebuildActiveIndex(cwd, { dryRun: true });
+  const after = fs.readFileSync(activeIndexPath(cwd), 'utf8');
+
+  expect(rows.map((r) => r.id)).toEqual(['e-1']);
+  expect(after).toBe(before);
+});

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

@@ -0,0 +1,63 @@
+// PRD 1065 — post-exit process-group sweep. A detached job's descendants must
+// not outlive the job (2026-08-31 starry-night-ships incident: orphaned test
+// batteries reparented to init after their job exited normally).
+import { describe, it, expect, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const { openLog, withChildAndLog, POST_EXIT_GROUP_SWEEP_GRACE_MS } = require('../childWithLog.cjs');
+
+let dir;
+
+afterEach(() => {
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  dir = undefined;
+});
+
+describe('childWithLog post-exit group sweep (PRD 1065)', () => {
+  it.skipIf(process.platform !== 'linux')(
+    'kills a detached child\'s backgrounded grandchild after exit + grace',
+    async () => {
+      dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-child-sweep-'));
+      const logPath = path.join(dir, 'job.log');
+      const pidFile = path.join(dir, 'grandchild.pid');
+      const { fd, safeLog, closeFd } = openLog(logPath);
+
+      const exited = new Promise((resolve) => {
+        withChildAndLog({
+          fd,
+          logPath,
+          safeLog,
+          closeFd,
+          spawn: {
+            command: 'sh',
+            args: [
+              '-c',
+              `sleep 30 & echo $! > ${pidFile}; exec sleep 0.2`,
+            ],
+            options: { detached: true },
+          },
+          onExit: () => resolve(),
+        });
+      });
+
+      await exited;
+
+      // Grandchild pid file is written by a backgrounded subshell that may
+      // race the parent's own exit; give it a moment to land.
+      for (let i = 0; i < 20 && !fs.existsSync(pidFile); i++) {
+        await new Promise((r) => setTimeout(r, 50));
+      }
+      expect(fs.existsSync(pidFile)).toBe(true);
+      const grandchildPid = Number(fs.readFileSync(pidFile, 'utf8').trim());
+      expect(Number.isInteger(grandchildPid) && grandchildPid > 1).toBe(true);
+
+      // Wait past the SIGTERM->SIGKILL grace window.
+      await new Promise((r) => setTimeout(r, POST_EXIT_GROUP_SWEEP_GRACE_MS + 1000));
+
+      expect(() => process.kill(grandchildPid, 0)).toThrow();
+    },
+    15000,
+  );
+});