claude-code-session-manager 0.86.0 → 0.87.0

package/src/main/__tests__/scheduler-reaper-helpers-basics.test.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+// Ported from the retired top-level test-root directory (a node:test suite,
+// never runnable by this repo's vitest-only setup — see CLAUDE.md's Commands
+// section). The existing src/main/lib/__tests__/reaperHelpers.test.cjs
+// exercises classifyRunOutcome extensively via selectReapableJobs and the
+// rate-limit paths, but never asserts claudePidAlive directly (only ever
+// injects a stand-in `pidAlive` function), and never pins the bare
+// no-result/empty-file/malformed-event edge cases below. These fill that
+// gap.
+//
+// Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reaper-helpers-basics.test.cjs
+
+const assert = require('node:assert/strict');
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+const { claudePidAlive, classifyRunOutcome } = require('../lib/reaperHelpers.cjs');
+
+// ─────────────────────────────────────────── claudePidAlive
+
+test('claudePidAlive: nonexistent pid (999999) returns false', () => {
+  assert.equal(claudePidAlive(999999), false);
+});
+
+test('claudePidAlive: pid 0 returns false', () => {
+  assert.equal(claudePidAlive(0), false);
+});
+
+test('claudePidAlive: pid 1 returns false', () => {
+  assert.equal(claudePidAlive(1), false);
+});
+
+test('claudePidAlive: null returns false', () => {
+  assert.equal(claudePidAlive(null), false);
+});
+
+test('claudePidAlive: undefined returns false', () => {
+  assert.equal(claudePidAlive(undefined), false);
+});
+
+// ─────────────────────────────────────────── classifyRunOutcome
+
+function writeTempLog(content) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'reaper-basics-test-'));
+  const filePath = path.join(dir, 'test.log');
+  fs.writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+test('classifyRunOutcome: success without an is_error field → success', () => {
+  const p = writeTempLog('{"type":"result","subtype":"success","result":"ok"}\n');
+  assert.equal(classifyRunOutcome(p), 'success');
+});
+
+test('classifyRunOutcome: subtype success but is_error:true → failed (error wins)', () => {
+  const p = writeTempLog('{"type":"result","subtype":"success","is_error":true}\n');
+  assert.equal(classifyRunOutcome(p), 'failed');
+});
+
+test('classifyRunOutcome: no result event in the tail → no_result', () => {
+  const log = [
+    '{"type":"assistant","message":"working"}',
+    '{"type":"tool_use","name":"bash"}',
+    'some plain text log line',
+  ].join('\n');
+  const p = writeTempLog(log);
+  assert.equal(classifyRunOutcome(p), 'no_result');
+});
+
+test('classifyRunOutcome: empty file → no_result', () => {
+  const p = writeTempLog('');
+  assert.equal(classifyRunOutcome(p), 'no_result');
+});
+
+test('classifyRunOutcome: last result event wins when multiple exist', () => {
+  const log = [
+    '{"type":"result","subtype":"success"}',
+    '{"type":"result","subtype":"error","is_error":true}',
+  ].join('\n');
+  const p = writeTempLog(log);
+  assert.equal(classifyRunOutcome(p), 'failed');
+});
+
+test('classifyRunOutcome: nonexistent file → no_result (readTail swallows I/O errors)', () => {
+  assert.equal(classifyRunOutcome('/nonexistent/path/that/cannot/exist.log'), 'no_result');
+});

package/src/main/__tests__/scheduler-shared-tree-guard.test.cjs

@@ -16,6 +16,7 @@
 'use strict';
 
 import { test, expect, vi, afterEach } from 'vitest';
+const fs = require('node:fs');
 const scheduler = require('../scheduler.cjs');
 const { evaluateSharedTreeGuard, checkSharedTreeGuard } = scheduler;
 
@@ -210,3 +211,90 @@ test('checkSharedTreeGuard never throws when the underlying git calls reject', a
   });
   expect(result).toBeNull();
 });
+
+// --- 2026-09-12 false-positive: an untracked path that merely became
+// IGNORED during the run (a .gitignore edit) is not a revert. See the
+// evaluateSharedTreeGuard doc comment for the full incident writeup. Each
+// test below is written to FAIL against the pre-fix implementation (which
+// computed `reverted = dirtyBefore - dirtyAfter - committed` with no
+// existence/tracked-status distinction at all) and PASS after it.
+
+test('evaluateSharedTreeGuard: an untracked path that disappears from git status but STILL EXISTS on disk is nowIgnored, not reverted', () => {
+  // Pre-fix behavior: this path would land in `reverted` (dirtyBefore minus
+  // dirtyAfter minus committed, no existence check at all) — FAILS pre-fix.
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [],
+    dirtyBefore: [{ code: '??', path: 'session-manager-operations/logs/errors-2026-09-12.jsonl' }],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: ['.gitignore'],
+    existsAfter: ['session-manager-operations/logs/errors-2026-09-12.jsonl'],
+  });
+  expect(result.reverted).toEqual([]);
+  expect(result.nowIgnored).toEqual(['session-manager-operations/logs/errors-2026-09-12.jsonl']);
+});
+
+test('evaluateSharedTreeGuard: an untracked path that disappears from git status AND no longer exists on disk is still reverted', () => {
+  // Proves the fix is not a blanket "stop reporting reverted": a genuinely
+  // deleted untracked file (the guard's real purpose — catching a job that
+  // discarded uncommitted work) must still surface. If the fix had simply
+  // stopped reporting any untracked-and-missing path as reverted, this test
+  // would fail (reverted would come back empty instead of containing the
+  // path).
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [],
+    dirtyBefore: [{ code: '??', path: 'data/scratch.txt' }],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: [],
+    existsAfter: [], // file no longer exists on disk
+  });
+  expect(result.reverted).toEqual(['data/scratch.txt']);
+  expect(result.nowIgnored).toEqual([]);
+});
+
+test('evaluateSharedTreeGuard: a TRACKED path clean after the run is still reverted even though it exists on disk', () => {
+  // A tracked file leaving the dirty set means its content was restored to
+  // HEAD — exactly the discard this guard exists to catch — regardless of
+  // whether the file is still present. Pre-fix this already worked by
+  // accident (no existence check existed at all); this test pins the
+  // behavior now that existence checks exist for the untracked branch, so a
+  // future change can't accidentally start trusting `existsAfter` for
+  // tracked paths too.
+  const result = evaluateSharedTreeGuard({
+    stashBefore: [],
+    stashAfter: [],
+    dirtyBefore: [{ code: ' M', path: 'src/config.js' }],
+    dirtyAfter: [],
+    pathsCommittedDuringRun: [],
+    existsAfter: ['src/config.js'], // file exists, but content was reset to HEAD
+  });
+  expect(result.reverted).toEqual(['src/config.js']);
+  expect(result.nowIgnored).toEqual([]);
+});
+
+test('checkSharedTreeGuard end-to-end: the real 2026-09-12 incident shape — untracked logs path ignored by a committed .gitignore change, file still on disk — must NOT verdict shared_tree_reverted', async () => {
+  // PRD 1181's exact shape: a bare `logs/` pattern lands in .gitignore during
+  // the run (committed), eleven untracked log paths vanish from `git status`,
+  // and the files are untouched on disk. Pre-fix, checkSharedTreeGuard's
+  // `reverted` would contain this path (no existsAfter computation existed),
+  // driving the caller's `verdict: 'shared_tree_reverted'` downgrade — FAILS
+  // pre-fix.
+  const logPath = 'session-manager-operations/logs/errors-2026-09-12.jsonl';
+  vi.spyOn(scheduler, 'stashList').mockResolvedValue([]);
+  vi.spyOn(scheduler, 'gitHead').mockResolvedValue('sha-after');
+  vi.spyOn(scheduler, 'pathsChangedSince').mockResolvedValue(['.gitignore']);
+  vi.spyOn(scheduler, 'uncommittedChanges').mockResolvedValue([]); // the log path no longer shows up at all
+  vi.spyOn(fs, 'existsSync').mockImplementation((p) => String(p).includes('errors-2026-09-12.jsonl'));
+
+  const result = await checkSharedTreeGuard({
+    cwd: '/repo',
+    stashBaseline: [],
+    dirtyBaseline: [{ code: '??', path: logPath }],
+    headBefore: 'sha-before',
+    slug: 'job-1181',
+  });
+
+  expect(result.reverted).toBeUndefined();
+  expect(result.nowIgnored).toEqual([logPath]);
+});

package/src/main/__tests__/scheduler-starve-escalation.test.cjs

@@ -12,21 +12,26 @@
  * Exercises selectStarveEscalations() (pure) directly, and
  * runStarveEscalationSweep() (the side-effecting wrapper) against a real,
  * scratch audit-log.jsonl and a fake attached window — matching
- * queue-starvation-per-project.test.cjs's pattern of setting HOME before
- * require() since every state path is baked from os.homedir() at load.
+ * pollLoop-dispatch-on-failure.test.cjs's pattern of setting HOME before
+ * require() (beforeAll runs AFTER module evaluation) since every state path
+ * is baked from os.homedir() at load, and restoring it in afterAll.
  *
  * Run: timeout 180 npx vitest run src/main/__tests__/scheduler-starve-escalation.test.cjs
  */
 
 'use strict';
 
-import { test, beforeEach } from 'vitest';
+import { test, beforeEach, afterAll } from 'vitest';
 const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-process.env.HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'starve-escalation-test-'));
+const originalHome = process.env.HOME;
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'starve-escalation-test-'));
+process.env.HOME = tmpHome;
+fs.mkdirSync(path.join(tmpHome, '.claude', 'session-manager'), { recursive: true });
+fs.mkdirSync(path.join(tmpHome, '.claude', 'projects'), { recursive: true });
 
 const {
   selectStarveEscalations,
@@ -36,6 +41,11 @@ const {
 } = require('../scheduler.cjs');
 const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
 
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
 const CWD_A = '/home/bilko/Projects/Bilko';
 const CWD_B = '/home/bilko/Projects/session-manager';
 

package/src/main/__tests__/scheduler-worktree-cap-defer.test.cjs

@@ -187,6 +187,20 @@ test('a non-git cwd still falls back to running in place (unchanged behaviour
     expect(row.worktreeFallbackReason).toMatch(/not a git repository/);
     // Ran IN PLACE — the marker landed directly in projectCwd, not a worktree.
     expect(fs.existsSync(path.join(projectCwd, 'ran-here.marker'))).toBe(true);
+
+    // A job losing worktree isolation must never be a silent downgrade
+    // discoverable only by reading queue.json afterwards — it must also land
+    // as a warn line in the durable ops error log, naming the slug, cwd, and
+    // reason.
+    const { todayFile } = require('../lib/opsErrorLog.cjs');
+    const errorLogPath = todayFile(projectCwd);
+    expect(fs.existsSync(errorLogPath)).toBe(true);
+    const logLines = fs.readFileSync(errorLogPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+    const fallbackLine = logLines.find((l) => l.scope === 'scheduler' && l.level === 'warn' && l.message.includes(slug));
+    expect(fallbackLine).toBeTruthy();
+    expect(fallbackLine.message).toMatch(/SHARED working tree/);
+    expect(fallbackLine.message).toMatch(/not a git repository/);
+    expect(fallbackLine.meta).toMatchObject({ slug, cwd: projectCwd, reason: expect.stringMatching(/not a git repository/) });
   } finally {
     fs.rmSync(projectCwd, { recursive: true, force: true });
     fs.rmSync(runDir, { recursive: true, force: true });

package/src/main/chatRunner.cjs

@@ -530,11 +530,14 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     const fullPrompt = STOP_SIGNAL_INSTRUCTION + CHAT_MODE_TRUTH_INSTRUCTION + prompt;
 
     // sessionId is the Epic's claudeSessionId for an Epic-backed tab (see
-    // comment above childEnv) — resolve that Epic's agentType persona model
-    // so Chat and Terminal views of the same Epic launch with the same
-    // model. Never throws; falls back to the hardcoded 'sonnet' literal when
-    // there's no Epic, no agentType, or the persona has no model/'inherit' —
-    // --model must never be left unpinned (CLAUDE.md model-pinning rule).
+    // comment above childEnv) — resolve that Epic's agentType persona model,
+    // project-overlay-then-global (agentModelResolve.cjs's
+    // readOverlayAwarePersonaModel). Terminal (EpicTerminalPane.tsx) calls
+    // this SAME function via the agents:resolve-epic-model IPC, so the two
+    // views of one Epic agree by construction, not by convention. Never
+    // throws; falls back to the hardcoded 'sonnet' literal when there's no
+    // Epic, no agentType, or the persona has no model/'inherit' — --model
+    // must never be left unpinned (CLAUDE.md model-pinning rule).
     const model = agentModelResolve.resolveEpicModel({ cwd, claudeSessionId: sessionId });
 
     // Build argv as an array — no shell: true, no string interpolation

package/src/main/health.cjs

@@ -20,7 +20,7 @@ const { computeStallSummary, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD
 const { findStarvedProjects } = require('./lib/schedulerBatch.cjs');
 const { AUDIT_LOG_PATH } = require('./lib/auditLog.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
-const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
+const { allProjectCwds } = require('./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, '../..');

package/src/main/historyAggregator.cjs

@@ -21,10 +21,14 @@ const CACHE_MAX = 50_000;
 // tokens are priced far below input because they're served from
 // Anthropic's prompt cache, not re-processed — this is what makes the
 // cache-savings figure in the dashboard real money, not a vanity stat.
+// fable: Claude Fable 5.1 (claude-fable-5-1) — $10/$50 per MTok input/output,
+// cache reads at $0.25/MTok (the `claude-api` skill's model reference and its
+// Claude Fable 5.1 migration notes, both cached 2026-06-24).
 const MODEL_PRICING = {
   opus:   { i: 15,  o: 75, c: 1.5 },
   sonnet: { i: 3,   o: 15, c: 0.3 },
   haiku:  { i: 0.8, o: 4,  c: 0.08 },
+  fable:  { i: 10,  o: 50, c: 0.25 },
 };
 const DEFAULT_PRICING_KEY = 'sonnet'; // fallback for unrecognized model ids
 
@@ -40,6 +44,7 @@ function resolvePricingKey(modelId) {
   if (id.includes('opus')) return { key: 'opus', estimated: false };
   if (id.includes('sonnet')) return { key: 'sonnet', estimated: false };
   if (id.includes('haiku')) return { key: 'haiku', estimated: false };
+  if (id.includes('fable')) return { key: 'fable', estimated: false };
   return { key: DEFAULT_PRICING_KEY, estimated: true };
 }
 

package/src/main/index.cjs

@@ -37,7 +37,11 @@ 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, installPrdWriteGuard, installDestructiveGitGuard, installInlineImplementationGuard } = require('./lib/delegationReadiness.cjs');
+const agentModelResolve = require('./lib/agentModelResolve.cjs');
+const { resolveEffectiveModelInfo } = require('./lib/effectiveModelInfo.cjs');
+const { checkDelegationReadiness, ensureGuardsInstalled, installPrdWriteGuard, installDestructiveGitGuard, installInlineImplementationGuard } = require('./lib/delegationReadiness.cjs');
+const { resolveProjectContext } = require('./lib/projectRootResolve.cjs');
+const { writeGuardShims } = require('./lib/guardShims.cjs');
 const { MCP_TOOL_CATALOG, MCP_RECIPES } = require('./lib/mcpToolCatalog.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
@@ -70,7 +74,7 @@ const telemetryConsent = require('./lib/telemetryConsent.cjs');
 const { registerHistoryAggregatorHandlers, finalizeClosedDays, refreshIntradayToday } = require('./historyAggregator.cjs');
 const runLogRetention = require('./lib/runLogRetention.cjs');
 const { registerHistoryDashboardHandlers } = require('./historyDashboard.cjs');
-const { tryAcquireLock, releaseLock, DEFAULT_LOCK_PATH } = require('../../scripts/lib/watchdogHelpers.cjs');
+const { tryAcquireLock, releaseLock, DEFAULT_LOCK_PATH } = require('./lib/watchdogHelpers.cjs');
 const schedulerConfig = require('./lib/schedulerConfig.cjs');
 const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
@@ -90,7 +94,8 @@ 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');
+const { allProjectCwds } = require('./lib/activeSessions.cjs');
+const { scheduleBootSelfHeal } = require('./lib/bootSelfHeal.cjs');
 
 let mainWindow = null;
 let rebooting = false;
@@ -520,12 +525,78 @@ ipcMain.handle('agents:remove-override', async (_e, payload) => {
 ipcMain.handle('agents:get-persona-body', validated(schemas.agentsGetPersonaBody, (payload) =>
   agentLibrary.getPersonaBody(payload)));
 
+// "What will this Epic's launch actually use for --model?" — the SAME
+// resolver chatRunner.cjs's Chat-view launch calls in-process
+// (agentModelResolve.cjs's resolveEpicModel), reached here so Terminal's
+// launch (EpicTerminalPane.tsx, a renderer module with no fs access) agrees
+// with Chat by calling the identical function rather than a second one that
+// is merely supposed to. Never throws (resolveEpicModel's own contract).
+ipcMain.handle('agents:resolve-epic-model', validated(schemas.agentsResolveEpicModel, (payload) =>
+  agentModelResolve.resolveEpicModel(payload)));
+
+// "What will this Epic actually run as?" (PRD: effective-model-resolver) —
+// persona alias + evidence-based concrete model id + provenance, for a given
+// (cwd, agentType). Read-only observer; never affects what a launch resolves.
+ipcMain.handle('agents:resolve-model-info', validated(schemas.agentsResolveModelInfo, (payload) =>
+  resolveEffectiveModelInfo(payload)));
+
 // "Can this project actually delegate?" probe (PRD: delegation-readiness).
 // 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)
-));
+//
+// Self-heals BEFORE computing the checks (PRD: guards-auto-install) — Fix It
+// used to be the only call site for the three guard installers, so every
+// project the human opened started red and demanded three manual clicks.
+// ensureGuardsInstalled never rejects on its own, but it is still awaited
+// inside a try/catch here so a future change to it can never turn this into
+// a rejected IPC handler.
+//
+// `cwd` is normalized to its real project root via the SAME resolver
+// prdAdminRoutes.cjs's session_manager_help readiness route already uses
+// (projectRootResolve.cjs's resolveProjectContext) before either the install
+// or the read-back check runs, so a worktree/ops-internal cwd can't install
+// into one path while the banner reads another.
+ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, async (payload) => {
+  const resolved = resolveProjectContext({ cwd: payload.cwd });
+  const cwd = resolved.cwd || payload.cwd;
+  try {
+    await ensureGuardsInstalled(cwd);
+  } catch { /* auto-install must never block the readiness probe itself */ }
+  return checkDelegationReadiness({ ...payload, cwd });
+}));
+
+// Every guard-install attempt is logged from MAIN, not the renderer — a
+// press that never reaches this process (e.g. a renderer talking to an
+// older main with no handler for the channel, Electron's own "No handler
+// registered for ..." rejection) leaves no line here, which is exactly what
+// makes it distinguishable from a press that reached main and failed. Uses
+// opsErrorLog.appendError (the sole writer of the `logs` ops namespace) so
+// the record lands in the project's own
+// session-manager-operations/logs/errors-<date>.jsonl, same shape as every
+// other structured error line.
+function logGuardInstallAttempt(guard, cwd, outcome) {
+  const opsErrorLog = require('./lib/opsErrorLog.cjs');
+  opsErrorLog.appendError({
+    cwd,
+    scope: 'delegationReadinessGuardInstall',
+    level: outcome.ok ? 'info' : 'error',
+    message: outcome.ok
+      ? `${guard} install ${outcome.action}`
+      : `${guard} install failed: ${outcome.error || 'unknown error'}`,
+    meta: { guard, ...outcome },
+  });
+}
+
+async function handleGuardInstall(guard, installFn, payload) {
+  try {
+    const result = await installFn(payload);
+    logGuardInstallAttempt(guard, payload.cwd, result);
+    return result;
+  } catch (err) {
+    logGuardInstallAttempt(guard, payload.cwd, { ok: false, action: 'error', error: err?.message ?? String(err) });
+    throw err;
+  }
+}
 
 // The three readiness checks with a sanctioned one-press install. Session
 // Manager standardizes on the REFERENCE approach (absolute path to this
@@ -536,13 +607,13 @@ ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadiness
 // header. inline-implementation-guard shares prd-write-guard's matcher, so
 // its installer appends into that SAME matcher's `hooks` array instead.
 ipcMain.handle('app:install-prd-write-guard', validated(schemas.delegationReadinessCwd, (payload) =>
-  installPrdWriteGuard(payload)
+  handleGuardInstall('prd-write-guard', installPrdWriteGuard, payload)
 ));
 ipcMain.handle('app:install-destructive-git-guard', validated(schemas.delegationReadinessCwd, (payload) =>
-  installDestructiveGitGuard(payload)
+  handleGuardInstall('destructive-git-guard', installDestructiveGitGuard, payload)
 ));
 ipcMain.handle('app:install-inline-implementation-guard', validated(schemas.delegationReadinessCwd, (payload) =>
-  installInlineImplementationGuard(payload)
+  handleGuardInstall('inline-implementation-guard', installInlineImplementationGuard, payload)
 ));
 
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
@@ -1274,42 +1345,22 @@ 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 } });
   });
+  // Rewrite the stable guard-hook shims (~/.claude/session-manager/hooks/) to
+  // point at THIS running app's root, on every boot. An already-installed
+  // project hook resolves through the shim at invocation time, so an app
+  // upgrade (a new npx hash dir) just follows along with no re-install — see
+  // guardShims.cjs's header.
+  writeGuardShims().catch((e) => {
+    logs.writeLine({ scope: 'guard-shims', level: 'error', message: 'writeGuardShims 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 } });
-  }
+  // status mirror (epicStatusMirror.cjs) can rebuild it. Runs once per boot
+  // and only touches a project whose index reads unclean — a clean index is
+  // never rewritten. Deferred until the window paints (did-finish-load) so
+  // the ~270ms allProjectCwds() scan doesn't compete with the renderer's
+  // first IPC round trips for the event loop — see bootSelfHeal.cjs.
+  scheduleBootSelfHeal(mainWindow, { fs, allProjectCwds, promptSessionsActiveIndexPath, rebuildActiveIndex, logs });
   // 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).
@@ -1340,7 +1391,7 @@ app.whenReady().then(async () => {
   }, 30_000);
   // Keep TODAY's rollup line current so the History dashboard never needs to
   // fall back to a live transcript scan. Shares the same O_EXCL lock file as
-  // the external watchdog's finalize pass (scripts/lib/watchdogHelpers.cjs)
+  // the external watchdog's finalize pass (src/main/lib/watchdogHelpers.cjs)
   // so the two never interleave writes to the rollup; a contended lock just
   // means this tick's refresh is skipped (harmless — the next tick retries).
   const intradayTimer = setInterval(runIntradayRefresh, schedulerConfig.HISTORY_INTRADAY_REFRESH_MS);

package/src/main/ipcSchemas.cjs

@@ -320,6 +320,11 @@ const PrdAgentTypeSchema = z.string().regex(PERSONA_NAME_RE, 'agent name must be
 // call site since update also allows an explicit empty array to CLEAR the
 // dependency, which create has no reason to accept.
 const DepSlugSchema = z.string().min(1).max(160).regex(/^[A-Za-z0-9][\w.-]*$/);
+// Wave-authoring decision (scheduler wave-disposition PRD), shared between
+// schedulerCreatePrd (authoring time) and adminPrdFrontmatterPatch (the
+// after-the-fact change path) so both can never disagree on what a valid
+// disposition value is.
+const PrdDispositionSchema = z.enum(['append', 'new-head']);
 const schedulerCreatePrd = z.object({
   title: z.string().min(1).max(200).regex(NO_NEWLINE_RE, 'must not contain newlines'),
   // Optional (PRD: worktree-cwd Epic-lookup hazard) — when omitted, prdCreate.cjs's
@@ -340,6 +345,12 @@ const schedulerCreatePrd = z.object({
   // Explicit ordering (PRD 832): slugs that must complete before this PRD
   // becomes eligible. Written to frontmatter as `dependsOn: [a, b]`.
   dependsOn: z.array(DepSlugSchema).max(20).optional(),
+  // Explicit wave-authoring decision (scheduler wave-disposition PRD) — only
+  // meaningful (and only stamped) when this PRD joins an Epic that already
+  // has incomplete PRDs and lands as a wave root (no dependsOn of its own);
+  // createPrd() requires it in that situation for an interactive caller and
+  // defaults to 'append' (logged as a default) for a non-interactive one.
+  disposition: PrdDispositionSchema.optional(),
   // An EXISTING Epic's promptSessionId (PRD 748) — NOT a PromptTicket.id.
   // ensureEpic() (epicMint.cjs) joins the Epic whose active-index.json
   // sessions key literally equals this value; the renderer only ever sends
@@ -387,6 +398,19 @@ const schedulerCreatePrd = z.object({
   quietMachine: z.boolean().optional(),
 });
 
+// Renderer-facing counterpart to adminPrdFrontmatterPatch's dependsOn/
+// disposition patch (scheduler wave-disposition PRD) — backs the Scheduler
+// UI's "change disposition" action. `dependsOn` is the caller's already-
+// computed target (from the SAME backlog tree the UI renders — see
+// lib/backlogTree.ts); the main-process handler only validates the rewrite
+// is safe (prdDisposition.cjs), never re-derives "the" terminal itself.
+const scheduleSetPrdDisposition = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
+  disposition: PrdDispositionSchema,
+  dependsOn: z.array(DepSlugSchema).max(20).optional(),
+});
+
 // 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
@@ -469,6 +493,11 @@ const adminPrdFrontmatterPatch = z.object({
   // (depSlugResolve.cjs) scheduler_create_prd uses, so update and create
   // can never disagree about what a dependsOn entry resolves to.
   dependsOn: z.array(DepSlugSchema).max(20).optional(),
+  // Patchable after creation too — the Scheduler UI's "change disposition"
+  // action (promote a wave to its own head, or attach it behind another
+  // chain) rewrites this alongside dependsOn via the same
+  // schedule:set-prd-disposition path (see prdDisposition.cjs).
+  disposition: PrdDispositionSchema.optional(),
 });
 
 const adminUpdatePrd = z.object({
@@ -623,6 +652,21 @@ const agentsGetPersonaBody = z.object({
   name: z.string().min(1).max(200),
 }).strict();
 
+// ──────────────────────────────────────────── Effective model info (PRD: what-will-this-run-as)
+const agentsResolveModelInfo = z.object({
+  cwd: z.string().min(1).max(4096),
+  agentType: z.string().min(1).max(200),
+}).strict();
+
+// ──────────────────────────────────────────── Epic launch model (PRD: unify-epic-model-resolution)
+// Terminal's (EpicTerminalPane.tsx) call into agentModelResolve.cjs's
+// resolveEpicModel — the same launch-model authority chatRunner.cjs's Chat
+// path calls in-process, reached here over IPC since the renderer has no fs.
+const agentsResolveEpicModel = z.object({
+  cwd: z.string().min(1).max(4096),
+  claudeSessionId: z.string().min(1).max(200),
+}).strict();
+
 // ──────────────────────────────────────────── Project Pages (PRD 932)
 // Same validation split as projectBriefCwd above: real path validation is
 // config.cjs's validatePath at first fs access in projectPages.cjs.
@@ -1037,6 +1081,7 @@ module.exports = {
     scheduleReadLog,
     scheduleWritePrd,
     schedulerCreatePrd,
+    scheduleSetPrdDisposition,
     scheduleArchivePrd,
     scheduleRetagPrd,
     adminListPrdsQuery,
@@ -1108,6 +1153,8 @@ module.exports = {
     exchangesList,
     agentsSavePersona,
     agentsGetPersonaBody,
+    agentsResolveModelInfo,
+    agentsResolveEpicModel,
     delegationReadinessCwd,
     telemetrySetConfig,
   },