claude-code-session-manager 0.85.0 → 0.87.0

package/src/main/__tests__/telemetrySettings.test.cjs

@@ -168,6 +168,38 @@ test('isMachineReportDue: true when lastMachineReportAt is more than 30 days bef
   expect(telemetrySettings.isMachineReportDue(cfg, { now, appVersion: '0.81.0' })).toBe(true);
 });
 
+test('save() merges a partial patch onto a fresh disk read — concurrent savers do not clobber each other', async () => {
+  const home = await mkHome();
+  const telemetrySettings = await freshModule(home);
+  const base = await telemetrySettings.load(); // mints + persists installId
+  expect(base.installId).not.toBe('');
+
+  // Two independent writers, each stamping a DIFFERENT field, racing each
+  // other — mirrors telemetryBoot's install-report stamp landing around the
+  // same time as telemetryClient's own daily-flush stamp. Neither holds the
+  // other's snapshot; each passes only the field it intends to change.
+  await Promise.all([
+    telemetrySettings.save({ lastMachineReportAt: '2026-01-01T00:00:00.000Z', lastMachineReportVersion: '2.0.0' }),
+    telemetrySettings.save({ lastDailyFlushAt: '2026-01-01T01:00:00.000Z' }),
+  ]);
+
+  const onDisk = await telemetrySettings.load();
+  expect(onDisk.lastMachineReportAt).toBe('2026-01-01T00:00:00.000Z');
+  expect(onDisk.lastMachineReportVersion).toBe('2.0.0');
+  expect(onDisk.lastDailyFlushAt).toBe('2026-01-01T01:00:00.000Z');
+  // Neither save touched installId/enabled/endpoint — they must survive too.
+  expect(onDisk.installId).toBe(base.installId);
+  expect(onDisk.enabled).toBe(base.enabled);
+  expect(onDisk.endpoint).toBe(base.endpoint);
+});
+
+test('save() rejects an unknown key without touching disk', async () => {
+  const home = await mkHome();
+  const telemetrySettings = await freshModule(home);
+  await telemetrySettings.load();
+  await expect(telemetrySettings.save({ notARealField: 'x' })).rejects.toThrow('Invalid telemetry config');
+});
+
 test('isMachineReportDue: false when same version and reported less than 30 days ago', async () => {
   const home = await mkHome();
   const telemetrySettings = await freshModule(home);

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

@@ -16,9 +16,11 @@ 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, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD, classifyQueueStarvation } = require('./scheduler.cjs');
+const { computeStallSummary, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD, classifyQueueStarvation, STARVE_ESCALATION_MS } = require('./scheduler.cjs');
+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, '../..');
@@ -458,6 +460,63 @@ function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs
   };
 }
 
+/**
+ * latestStarveEscalationReasons(auditLogPath) → { [cwd]: holdReason }
+ *
+ * health.cjs runs as its own cold process (`npm run health`), so it has no
+ * access to the live scheduler's in-memory `lastTick` — the durable
+ * audit-log.jsonl trail (auditLog.cjs) is the only place the hold reason a
+ * 'project_starve_escalated' event already recorded (scheduler.cjs's
+ * runStarveEscalationSweep) survives to be read from here. Reads the SAME
+ * recorded value rather than re-deriving it; the last record per cwd wins.
+ * Missing/unreadable log → {} (no reasons known yet), never a throw.
+ */
+function latestStarveEscalationReasons(auditLogPath) {
+  let lines;
+  try {
+    lines = fs.readFileSync(auditLogPath, 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return {};
+  }
+  const byCwd = {};
+  for (const line of lines) {
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (rec?.kind === 'project_starve_escalated' && rec.cwd) byCwd[rec.cwd] = rec.holdReason ?? 'unknown';
+  }
+  return byCwd;
+}
+
+/**
+ * evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons)
+ *   → { ok, projects?, message? }
+ *
+ * Pure over its inputs. Reuses findStarvedProjects — the exact per-cwd
+ * STARVED verdict the live escalation (scheduler.cjs) acts on — so health
+ * reports the identical set of starved-past-threshold projects, never a
+ * re-derived one. `escalationReasons` supplies the hold reason per cwd (see
+ * latestStarveEscalationReasons); a cwd with no recorded reason yet reports
+ * 'unknown' rather than failing.
+ */
+function evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons = {}) {
+  const starved = findStarvedProjects(jobs, now, thresholdMs);
+  if (starved.length === 0) return { ok: true };
+  const projects = starved.map((sp) => ({
+    cwd: sp.cwd,
+    pendingCount: sp.pendingCount,
+    ageMs: sp.ageMs,
+    holdReason: escalationReasons[sp.cwd] ?? 'unknown',
+  }));
+  const message = `Project(s) starved past the ${Math.round(thresholdMs / 60_000)}m escalation threshold: ${
+    projects.map((p) => `${p.cwd} (${Math.round(p.ageMs / 60_000)}m, ${p.pendingCount} pending, hold=${p.holdReason})`).join('; ')
+  }`;
+  return { ok: false, projects, message };
+}
+
 function loadUsagePollerState(statePath) {
   let raw;
   try {
@@ -640,6 +699,18 @@ async function check() {
       status.issues.push(`Queue dispatch: ${status.components.queue_dispatch.message}`);
     }
 
+    // Per-project starve escalation (bounded consequence for project_starved
+    // — see runStarveEscalationSweep in scheduler.cjs). Distinct from
+    // queue_dispatch above: that's machine-wide dispatch liveness, this is
+    // "has any ONE project been starved past the LATER escalation threshold",
+    // the exact condition the 2026-09-12 19h Bilko starve went unreported by.
+    status.components.project_starve_escalation = evaluateStarveEscalationHealth(
+      queueState.jobs, now, STARVE_ESCALATION_MS, latestStarveEscalationReasons(AUDIT_LOG_PATH),
+    );
+    if (!status.components.project_starve_escalation.ok) {
+      status.issues.push(status.components.project_starve_escalation.message);
+    }
+
     // Worktree cap blocking every dispatchable pending job with nothing
     // running (see evaluateWorktreeCapBlocked's header) — a distinct
     // condition from generic tick/dispatch staleness above, since a leaked
@@ -877,7 +948,7 @@ async function check() {
   // 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', 'queue_dispatch', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'queue_dispatch', 'project_starve_escalation', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -909,6 +980,8 @@ module.exports = {
   evaluateUsagePollerHealth,
   loadUsagePollerState,
   evaluateQueueDispatchHealth,
+  evaluateStarveEscalationHealth,
+  latestStarveEscalationReasons,
   DISPATCH_STALL_THRESHOLD_MS,
   TICK_STALL_THRESHOLD_MS,
   HEARTBEAT_STALE_MS,

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,
   },