claude-code-session-manager 0.123.1 → 0.124.1

package/src/main/scheduler.cjs

@@ -74,7 +74,7 @@ const { readTail } = require('./lib/util/fileTail.cjs');
 const {
   claudePidAlive, classifyRunOutcome, mapOutcomeToGateOutcome, ORPHAN_REQUEUE_CAP, selectReapableJobs,
   findLiveProcessForJob, logHasOutput, resolvePidlessGateOutcome, resolveCommitGuardOutcome,
-  readSpawnedPidFromLog, readLogMtimeMs,
+  readSpawnedPidFromLog, readLogMtimeMs, isClaudeArgv,
 } = require('./lib/scheduler/reaperHelpers.cjs');
 const { resolveProjectRoot } = require('./lib/opsOwnership.cjs');
 const { sweepStrandedJobBranches } = require('./lib/git/branchSweep.cjs');
@@ -359,18 +359,16 @@ ${verdictStepNum}. VERDICT LINE — end your final report with exactly one of th
      SCHEDULER_VERDICT: PASS
      SCHEDULER_VERDICT: FAIL <one-line reason>
      SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP
-     SCHEDULER_VERDICT: NEEDS_HUMAN <one-line question>
    - Print PASS only when the gate is green AND the commit from step ${commitStepNum} landed.
-   - Print FAIL when the gate is red or the commit could not land.
+   - Print FAIL when the gate is red or the commit could not land. Also print
+     FAIL when a step needs something this run cannot reach (live runtime
+     state, credentials, an account or dashboard action, a host install): do
+     everything else, commit it, and name exactly what is missing in the
+     reason. Never ask a question.
    - Never print PASS on a red gate. Why: a false PASS ships broken work that
      no one notices. A true PASS plus a landed commit lets the scheduler ignore
      harmless noise in your transcript, such as grep hits for "Error", an early
      red test run, or debug tracebacks.
-   - Print NEEDS_HUMAN only when finishing needs a decision or action only the
-     human can take (credentials, an account/dashboard action, a product
-     choice, an install on the host) — never for a red gate or a bug you could
-     fix. Commit any finished work first. Phrase the question so a yes/no or
-     one-line answer unblocks it.
    - Print BLOCKED_BY_FOREIGN_WIP ONLY when your gate failed because of a
      sibling job's unfinished, uncommitted file — never because of your own
      change — AND every failing path is one this prompt already listed as
@@ -975,8 +973,10 @@ function heartbeatTick(deps = {}) {
         lastDispatchAttemptAt: s.lastDispatchAttemptAt ?? null,
         lastRunAt: s.lastRunAt ?? null,
         lastTickReason: lastTick?.reason ?? null,
+        lastTickDetail: lastTick?.detail ? stripTickDetailPrefix(lastTick.detail, { keepWord: true }).slice(0, 200) : null,
         pendingDispatchable: Math.max(0, counts.pending - blockedPending),
         runningCount: counts.running,
+        quietLeaseHolder: quietMachineLease.isHeld() ? (quietMachineLease.holder() ?? null) : null,
         paused: Boolean(s.paused),
         drain: s.drain?.active ? { since: s.drain.since ?? null, requestedAt: s.drain.requestedAt ?? null } : null,
       };
@@ -1370,16 +1370,17 @@ function killOrphanClaudePid(pid, recordedIdentity = null) {
   }
   // win32 has no /proc or `ps`: the identity heuristic can't run, so never reap.
   if (process.platform === 'win32') return 'unknown';
-  let cmdline = '';
+  let argv = [];
   try {
-    cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+    argv = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0');
+    if (argv.length && argv[argv.length - 1] === '') argv.pop();
   } catch {
     try {
       const out = require('node:child_process').execSync(`ps -p ${pid} -o command=`, { encoding: 'utf8', stdio: ['ignore','pipe','ignore'] });
-      cmdline = out.trim();
+      argv = out.trim().split(/\s+/).filter(Boolean);
     } catch { return 'unknown'; }
   }
-  if (!/\bclaude\b/.test(cmdline)) return 'mismatch';
+  if (!isClaudeArgv(argv)) return 'mismatch';
   killTree(pid, 'SIGTERM');
   setTimeout(() => {
     try { process.kill(pid, 0); } catch { return; /* already gone */ }
@@ -2303,6 +2304,13 @@ const loadGate = createLoadGate();
 // actually pinned at 1 with nothing on screen explaining why. This is that
 // explanation, recorded once per tick and broadcast with the rest of the state.
 let lastTick = null;
+// Strips the leading '[scheduler] <word> [..]: ' prefix from a tick detail.
+// keepWord=true strips only the '[scheduler] ' tag and keeps '<word>: ' (the
+// heartbeat wants the hold kind, e.g. 'quiet-machine: lease held ...').
+function stripTickDetailPrefix(detail, { keepWord = false } = {}) {
+  const re = keepWord ? /^\[scheduler\]\s*/ : /^\[scheduler\]\s*[\w-]+\s*(?:\[[^\]]*\])?:\s*/;
+  return String(detail ?? '').replace(re, '');
+}
 function recordTick(outcome, extra = {}) {
   lastTick = { ...outcome, ...extra, at: new Date().toISOString() };
   return outcome;
@@ -2820,10 +2828,15 @@ function partitionBootOrphans(jobs, {
 } = {}) {
   const immediate = [];
   const adopted = [];
+  const claimedPids = new Set();
+  for (const r of jobs) {
+    if (r.status === 'running' && r.runtime?.pid) claimedPids.add(r.runtime.pid);
+  }
   for (const j of jobs) {
     if (j.status !== 'running') continue;
     if (isBootRowAlive(j, {
       pidAlive, getLogPid, getLogMtimeMs, logFreshWindowMs, findLiveProcess, readRecord, runsDir, identityOf, now,
+      claimedPids,
     })) adopted.push(j.slug);
     else immediate.push(j.slug);
   }
@@ -2832,6 +2845,7 @@ function partitionBootOrphans(jobs, {
 
 function isBootRowAlive(j, {
   pidAlive, getLogPid, getLogMtimeMs, logFreshWindowMs, findLiveProcess, readRecord, runsDir, identityOf, now,
+  claimedPids = new Set(),
 }) {
   const logMtimeMs = typeof getLogMtimeMs === 'function' ? getLogMtimeMs(j) : null;
   const runDir = j.runId ? path.join(runsDir || schedulerPaths.runsDir(), j.runId) : null;
@@ -2852,7 +2866,12 @@ function isBootRowAlive(j, {
   if (typeof logFreshWindowMs === 'number' && Number.isFinite(logMtimeMs) && now - logMtimeMs <= logFreshWindowMs) return true;
   const logPid = typeof getLogPid === 'function' ? getLogPid(j) : null;
   if (logPid && pidAlive(logPid)) return true;
-  return !!(typeof findLiveProcess === 'function' && findLiveProcess(j));
+  // No run log = dispatch never reached the spawn; a /proc scan could only misattribute a stray process.
+  if (typeof findLiveProcess !== 'function' || !Number.isFinite(logMtimeMs)) return false;
+  const livePid = findLiveProcess(j);
+  if (!livePid || claimedPids.has(livePid)) return false;
+  claimedPids.add(livePid);
+  return true;
 }
 
 /**
@@ -3075,7 +3094,7 @@ function defaultScheduleSettle({ cwd, epicId }) {
         return null;
       }
     },
-    sendPrompt: enqueueExternalPrompt,
+    sendPrompt: (tabId, prompt) => enqueueExternalPrompt(tabId, prompt, { origin: 'scheduler' }),
     appendResponseEvent: appendResponseEventIfKnown,
   };
   epicValidationHook.scheduleEpicSettle({ cwd, epicId }, (args) => epicValidationHook.runEpicSettle(args, deps));
@@ -3280,7 +3299,7 @@ async function notifyOriginatingTab(job, {
       return;
     }
 
-    sendPrompt(targetTabId, message);
+    sendPrompt(targetTabId, message, { origin: 'scheduler' });
   } catch (e) {
     console.error('[scheduler] notifyOriginatingTab error', job?.slug, e);
   }
@@ -4615,15 +4634,15 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
     // clock time regardless of whether the job keeps writing output — the
     // gap a chatty-but-runaway executor slips through (see
     // computeJobBudgetMs's header for the measured p50/p90/max this budget
-    // is calibrated against). `quietMachine` jobs and any PRD with an
-    // explicit `budgetExempt: true` opt out entirely — logged once here so
+    // is calibrated against). Only a PRD with an
+    // explicit `budgetExempt: true` opts out entirely — logged once here so
     // an unbounded job is never silently unbounded.
     const jobBudgetMs = budget.computeJobBudgetMs(
       job.estimateMinutes ?? resolvePersonaDefaultEstimate(job.cwd, job.agentType || DEFAULT_PRD_AGENT_TYPE));
     const budgetExempt = budget.isJobBudgetExempt(job);
     if (budgetExempt) {
       safeLog(`[scheduler] wall-clock budget watchdog EXEMPT for ${job.slug} ` +
-        `(${job.quietMachine === true ? 'quietMachine' : 'budgetExempt'}) — no wall-clock kill ceiling this run\n`);
+        `(budgetExempt) — no wall-clock kill ceiling this run\n`);
     }
     let budgetWarningStamped = false;
     const budgetWatchdog = {
@@ -7546,7 +7565,7 @@ function forceTickOutcome(result) {
     case 'slots-exhausted':
       return { ok: true, kind: 'warn', message: `Deferred ${result.deferredCount} job(s) — all session slots in use (${(result.holders ?? []).map((h) => h.owner).join(', ')})` };
     case 'held': {
-      const detail = String(result.detail ?? '').replace(/^\[scheduler\]\s*[\w-]+\s*(?:\[[^\]]*\])?:\s*/, '');
+      const detail = stripTickDetailPrefix(result.detail);
       return { ok: true, kind: 'warn', message: detail || 'Batch held' };
     }
     default:
@@ -7937,7 +7956,6 @@ async function reapDeadRunningJobs() {
       grace: PIDLESS_SPAWN_GRACE_MS,
       findLiveProcess: (j) => findLiveProcessForJob(j, {
         worktreeDir: jobWorktree.worktreeDirFor(j.cwd || state.config?.defaultCwd || DEFAULT_PROJECT_CWD, j.slug),
-        runCwd: j.runtime?.cwd || j.cwd,
       }),
       getLogPid: (j) => readSpawnedPidFromLog(logPathForJob(j)),
       getLogMtimeMs: (j) => readLogMtimeMs(logPathForJob(j)),
@@ -8651,6 +8669,33 @@ function applyNeedsReviewAutoResolve(j, jobsInProject = []) {
   return 'skipped';
 }
 
+/**
+ * Terminal outcome for a failed row that used every FAILED_AUTORESET_CAP
+ * auto-reset and sat past STUCK_FAILED_ESCALATE_MS: skip it (same marker and
+ * grouped review notice as the rung-6 cap-exhausted skip) so dependents drain
+ * and the Epic's automated turn queues the fix. Mutates in place; returns
+ * 'skipped', or null when the race guard rejects it.
+ */
+function applyStuckFailedAutoSkip(j, ageMs = 0) {
+  if (!j || j.status !== 'failed' || reviewLadder.isCancelledJob(j)) return null;
+  if ((j.failedAutoResetAttempts ?? 0) < reviewLadder.FAILED_AUTORESET_CAP) return null;
+  const cap = reviewLadder.FAILED_AUTORESET_CAP;
+  j.needsReviewAutoResolvedSkip = true;
+  j.error = `failed auto-reset cap exhausted (${cap}/${cap} attempts) after ${Math.round(ageMs / 3_600_000)}h — auto-skipped to unblock downstream dependsOn rows`;
+  j.reviewNotice = buildReviewNotice({
+    job: j,
+    report: null,
+    epicId: j.epicId ?? j.sourcePromptId ?? null,
+    now: new Date().toISOString(),
+    prior: j.reviewNotice,
+  });
+  transitionJob(j, 'skipped', {
+    reason: `failed auto-resets exhausted (${cap}/${cap}) — auto-skipped`,
+    source: 'stuckFailedAutoSkip',
+  });
+  return 'skipped';
+}
+
 /**
  * Self-healing pass over needs_review jobs. The verifier runs in-process, so a
  * fix to runVerify.cjs only takes effect for jobs verified AFTER an app
@@ -10086,18 +10131,19 @@ function rescheduleIntervalTick() {
       }
       for (const stuck of stuckFailed) {
         const j = ms.jobs.find((x) => x.slug === stuck.slug);
-        if (!j || j.status !== 'failed' || j.stuckFailedNotified === true) continue; // race guard
+        if (!j || j.status !== 'failed') continue; // race guard
         // Still has auto-reset attempts left — it will be (or already was,
         // earlier this same pass) picked up by the loop above instead.
         // Never log "reset it by hand" for a row that isn't actually stuck.
         if ((j.failedAutoResetAttempts ?? 0) < reviewLadder.FAILED_AUTORESET_CAP) continue;
-        j.stuckFailedNotified = true;
+        const outcome = applyStuckFailedAutoSkip(j, stuck.ageMs);
+        if (!outcome) continue;
         console.warn(
           `[scheduler] FAILED PRD STUCK: project=${stuck.cwd ?? '(unknown)'} slug=${stuck.slug} `
           + `failed=${Math.round(stuck.ageMs / 3_600_000)}h (>= ${Math.round(reviewLadder.STUCK_FAILED_ESCALATE_MS / 3_600_000)}h threshold) — `
-          + `auto-reset cap exhausted (${reviewLadder.FAILED_AUTORESET_CAP}/${reviewLadder.FAILED_AUTORESET_CAP} attempts); reset it by hand via scheduler_reset_job`,
+          + `auto-reset cap exhausted (${reviewLadder.FAILED_AUTORESET_CAP}/${reviewLadder.FAILED_AUTORESET_CAP} attempts); auto-skipped to unblock dependents`,
         );
-        appendAuditEvent('job_stuck_failed', { slug: stuck.slug, cwd: stuck.cwd, ageMs: stuck.ageMs });
+        appendAuditEvent('job_stuck_failed', { slug: stuck.slug, cwd: stuck.cwd, ageMs: stuck.ageMs, outcome });
       }
       for (const target of exhaustedNeedsReviewTargets) {
         const j = ms.jobs.find((x) => x.slug === target.slug);
@@ -10230,7 +10276,6 @@ async function init() {
       logFreshWindowMs: IDLE_OUTPUT_KILL_MS,
       findLiveProcess: (j) => findLiveProcessForJob(j, {
         worktreeDir: jobWorktree.worktreeDirFor(j.cwd || DEFAULT_PROJECT_CWD, j.slug),
-        runCwd: j.runtime?.cwd || j.cwd,
       }),
       readRecord: supervisorRecord.readSupervisorRecord,
     });
@@ -11130,6 +11175,7 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
 
 module.exports = {
   normalizeConfig,
+  recordTick,
   reportSchedulerError,
   finalizeJobWorktree,
   worktreeIntegrationVerdict,
@@ -11173,6 +11219,7 @@ module.exports = {
   runGateShadow,
   awaitGateShadowIdle: async () => { while (gateShadowPending) await gateShadowPending; },
   applyNeedsReviewAutoResolve,
+  applyStuckFailedAutoSkip,
   computeLooksDone,
   attributeLandedCommits,
   isPromotableOriginal,

package/src/main/seedAgentPersonas.cjs

@@ -80,7 +80,7 @@ const { writeJsonSync, writeTextAtomic, validatePath, validateWrite } = require(
 const { splitFrontmatter } = require('./lib/prd/prdFrontmatter.cjs');
 const { SHIPPED_PERSONA_SEEDS } = require('./lib/persona-macro/shippedPersonaSeeds.cjs');
 
-const PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator', 'demo-video-builder'];
+const PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator', 'demo-video-builder', 'blender-artist'];
 // What `{ done: true }` (the pre-seeded-set marker format) meant: only these two personas existed
 // in PERSONAS at the time. Fixed, not derived from the current PERSONAS array above — otherwise
 // every future persona added to PERSONAS would retroactively count as already delivered to a

package/src/main/templates/PRD_AUTHORING.md

@@ -1,4 +1,4 @@
-<!-- PRD_AUTHORING.md v13 -->
+<!-- PRD_AUTHORING.md v14 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 Rule: every PRD you queue follows the rules below.
@@ -226,5 +226,5 @@ Before queueing a new PRD, verify each of these:
 - [ ] **§10 Negative assertions:** every "should find nothing" check is inverted to exit 0 on the clean case.
 - [ ] **§11 End green:** the gate runs last; any intentional failure runs early and is captured.
 - [ ] **Gate baseline:** every gate command ran green once at HEAD in the main checkout; a red suite is scoped to the PRD's own test files and the PRD notes say why. Why: a gate already red on base parks as `sentinel_fail`.
-- [ ] **No human-only gates:** no gate or criterion needs a human or the passage of time (cron install, live post wait, live payment, dashboard action); those end `SCHEDULER_VERDICT: NEEDS_HUMAN <question>`. Why: no executor can pass them.
+- [ ] **No human-only gates:** no gate or criterion needs a human or the passage of time (cron install, live post wait, live payment, dashboard action); keep them out of the PRD at authoring time; an executor that meets one ends `SCHEDULER_VERDICT: FAIL` naming what is missing. Why: no executor can pass them.
 - [ ] **Gate purity:** a gate command must not create or modify tracked files; outputs go to the per-gate TMPDIR or a gitignored path. Why: a dirtied tree fails the clean-tree check.

package/src/main/voiceHotkey.cjs

@@ -18,6 +18,7 @@
 const { app, globalShortcut, ipcMain } = require('electron');
 const voiceSettings = require('./voiceSettings.cjs');
 const { voiceHotkeyLog } = require('./lib/voice-hotkey-log.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { schemas, validated } = require('./ipcSchemas.cjs');
 
 let mainWindow = null;
@@ -170,7 +171,7 @@ function attachBeforeInput() {
 
 function emitHotkey(phase, source) {
   if (!mainWindow || mainWindow.isDestroyed()) return;
-  mainWindow.webContents.send('voice:hotkey', { phase, source });
+  sendIfAlive(mainWindow, 'voice:hotkey', { phase, source });
   voiceHotkeyLog('info', phase === 'down' ? 'down' : 'up', { source });
 }
 
@@ -308,7 +309,7 @@ function registerHotkeyHandlers() {
     currentConfig = await voiceSettings.load();
     applyConfig(currentConfig);
     if (mainWindow && !mainWindow.isDestroyed()) {
-      mainWindow.webContents.send('voice:hotkey-changed', currentConfig);
+      sendIfAlive(mainWindow, 'voice:hotkey-changed', currentConfig);
     }
     return { ok: true, config: currentConfig };
   }));

package/src/main/webRemote.cjs

@@ -26,7 +26,7 @@ const fsp = require('node:fs/promises');
 const fs = require('node:fs');
 const { writeTextAtomic, validatePath } = require('./config.cjs');
 const logs = require('./logs.cjs');
-const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+const { sendIfAlive, setRemoteFanout } = require('./lib/sendToRenderer.cjs');
 const { claudeHome } = require('./lib/scheduler/schedulerPaths.cjs');
 const { schemas } = require('./ipcSchemas.cjs');
 const { makeState, confirmSas: confirmSasLogic } = require('./lib/e2eStateMachine.cjs');
@@ -902,8 +902,164 @@ async function handleMessage(raw, device) {
   await dispatchEnvelope(envelope, device, client);
 }
 
+const IPC_INVOKE_MAX_CALLS = 50;
+let _ipcDispatcher = null;
+
+/** Install the shared renderer-handler dispatcher (built in index.cjs). */
+function setIpcDispatcher(dispatcher) {
+  _ipcDispatcher = dispatcher;
+}
+
+/** Encrypt + unicast one ipc:result frame to the calling client (never plaintext). */
+function sendIpcResult(callId, frame, client) {
+  if (!_ws || _ws.readyState !== WebSocket.OPEN) return;
+  if (!client || !client.e2e.sessionKey) return;
+  try {
+    const inner = { type: 'ipc:result', id: callId, seq: frame.seq, total: frame.total, data: frame.data, ts: Date.now() };
+    const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), client.e2e.sessionKey);
+    const out = { type: 'e2e:box', id: callId, payload: { nonce, ciphertext }, ts: Date.now() };
+    if (client.key !== LEGACY_CLIENT_KEY) out.toConn = client.key;
+    _ws.send(JSON.stringify(out));
+  } catch (e) {
+    logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'ipc:result send failed', meta: { error: e?.message } });
+  }
+}
+
+/** Batched ipc:invoke — each call runs through the shared dispatcher (same handlers as the renderer). */
+async function dispatchIpcInvoke(envelope, device, client) {
+  const { id, payload } = envelope;
+  const ts = new Date().toISOString();
+  const calls = payload && Array.isArray(payload.calls) ? payload.calls : null;
+  const valid = calls && calls.length >= 1 && calls.length <= IPC_INVOKE_MAX_CALLS &&
+    calls.every((c) => c && typeof c === 'object' && typeof c.channel === 'string' && c.channel.length > 0 &&
+      c.channel.length <= 200 && (c.args === undefined || Array.isArray(c.args)));
+  if (!valid || typeof id !== 'string' || !id || !_ipcDispatcher) {
+    await auditLog(ts, 'ipc:invoke', device.deviceId, id, 'error:rejected', client);
+    respond(id, { error: 'rejected' }, undefined, client);
+    return;
+  }
+  const { chunkFrames } = require('./lib/feedback-remote/remoteIpcDispatch.cjs');
+  for (let i = 0; i < calls.length; i++) {
+    const { channel, args } = calls[i];
+    let out;
+    let audit;
+    try {
+      const r = await _ipcDispatcher.invoke(client, channel, args ?? []);
+      if (r.ok) { out = { ok: true, result: r.result }; audit = 'ok'; }
+      else { out = { ok: false, error: 'rejected' }; audit = `refused:${r.reason}`; }
+    } catch (e) {
+      out = { ok: false, error: 'rejected' };
+      audit = 'refused:dispatch_error';
+    }
+    let chunked = chunkFrames(out);
+    if (!chunked.ok) {
+      chunked = chunkFrames({ ok: false, error: 'rejected' });
+      if (out.ok) audit = 'refused:too_large';
+    }
+    await auditLog(ts, `ipc:${channel}`, device.deviceId, id, audit, client);
+    for (const frame of chunked.frames) sendIpcResult(`${id}.${i}`, frame, client);
+  }
+}
+
+/** asset:manifest / asset:get — E2E-authenticated only; reply is chunked ipc:result-style frames, unicast. */
+async function dispatchAsset(envelope, device, client) {
+  const { type, id, payload } = envelope;
+  const ts = new Date().toISOString();
+  if (typeof id !== 'string' || !id || client.e2e.state !== 'authenticated' || !client.e2e.sessionKey) {
+    await auditLog(ts, type, device.deviceId, id, 'refused:e2e_not_authenticated', client);
+    respond(id, { error: 'rejected' }, undefined, client);
+    return;
+  }
+  const { chunkFrames } = require('./lib/feedback-remote/remoteIpcDispatch.cjs');
+  const assets = require('./lib/feedback-remote/remoteAssets.cjs');
+  let out;
+  let audit = 'ok';
+  try {
+    if (type === 'asset:manifest') out = { ok: true, result: assets.assetManifest() };
+    else {
+      const r = assets.readAsset(payload && payload.name);
+      if (r.ok) out = { ok: true, result: r };
+      else { out = { ok: false, error: 'rejected' }; audit = `refused:${r.error}`; }
+    }
+  } catch {
+    out = { ok: false, error: 'rejected' };
+    audit = 'refused:asset_error';
+  }
+  let chunked = chunkFrames(out);
+  if (!chunked.ok) { chunked = chunkFrames({ ok: false, error: 'rejected' }); audit = 'refused:too_large'; }
+  await auditLog(ts, type, device.deviceId, id, audit, client);
+  for (const frame of chunked.frames) sendIpcResult(id, frame, client);
+}
+
+// ─── ipc:subscribe push fanout ─────────────────────────────────────
+// Mirrors sendIfAlive pushes to E2E-authenticated browser clients that subscribed.
+
+const IPC_SUBSCRIBE_MAX_CHANNELS = 50;
+
+/** True iff the apiSurface lists `channel` as a push (on / on-dynamic) with remote not deny. */
+function isPushableChannel(channel) {
+  if (typeof channel !== 'string' || channel.length === 0 || channel.length > 200) return false;
+  const surface = require('../preload/apiSurface.cjs');
+  return surface.some((r) => {
+    if (r.remote === 'deny') return false;
+    if (r.kind === 'on') return r.channel === channel;
+    if (r.kind === 'on-dynamic') {
+      const prefix = r.channel.endsWith('*') ? r.channel.slice(0, -1) : r.channel;
+      return channel.length > prefix.length && channel.startsWith(prefix);
+    }
+    return false;
+  });
+}
+
+function handleIpcSubscribe(envelope, client, subscribe) {
+  const channels = envelope.payload && Array.isArray(envelope.payload.channels) ? envelope.payload.channels : [];
+  if (!client.pushChannels) client.pushChannels = new Set();
+  for (const ch of channels.slice(0, IPC_SUBSCRIBE_MAX_CHANNELS)) {
+    if (subscribe) { if (isPushableChannel(ch)) client.pushChannels.add(ch); }
+    else client.pushChannels.delete(ch);
+  }
+}
+
+/** Encrypt + unicast one ipc:event frame to one subscribed client. */
+function sendIpcEvent(client, channel, frame) {
+  if (!_ws || _ws.readyState !== WebSocket.OPEN) return;
+  if (!client.e2e.sessionKey) return;
+  const inner = { type: 'ipc:event', id: crypto.randomUUID(), channel, seq: frame.seq, total: frame.total, data: frame.data, ts: Date.now() };
+  const { nonce, ciphertext } = encryptBox(JSON.stringify(inner), client.e2e.sessionKey);
+  const out = { type: 'e2e:box', id: inner.id, payload: { nonce, ciphertext }, ts: Date.now() };
+  if (client.key !== LEGACY_CLIENT_KEY) out.toConn = client.key;
+  _ws.send(JSON.stringify(out));
+}
+
+function fanoutIpcEvent(channel, payload) {
+  const targets = _clients.authenticated().filter((c) => c.pushChannels && c.pushChannels.has(channel));
+  if (targets.length === 0) return;
+  const { chunkFrames } = require('./lib/feedback-remote/remoteIpcDispatch.cjs');
+  const chunked = chunkFrames(payload);
+  if (!chunked.ok) return;
+  for (const client of targets) {
+    try {
+      for (const frame of chunked.frames) sendIpcEvent(client, channel, frame);
+    } catch (e) {
+      logs.writeLine({ scope: 'webRemote', level: 'warn', message: 'ipc:event send failed', meta: { error: e?.message } });
+    }
+  }
+}
+
 async function dispatchEnvelope(envelope, device, client) {
   const { type, id, payload } = envelope;
+  if (type === 'ipc:subscribe' || type === 'ipc:unsubscribe') {
+    if (client.e2e.state === 'authenticated') handleIpcSubscribe(envelope, client, type === 'ipc:subscribe');
+    return;
+  }
+  if (type === 'ipc:invoke') {
+    await dispatchIpcInvoke(envelope, device, client);
+    return;
+  }
+  if (type === 'asset:manifest' || type === 'asset:get') {
+    await dispatchAsset(envelope, device, client);
+    return;
+  }
   if (typeof type !== 'string' || !type.startsWith('cmd:')) return;
 
   const ts = new Date().toISOString();
@@ -1293,6 +1449,7 @@ async function revokeAllDevices() {
 // ─── IPC handlers ─────────────────────────────────────────────────────────────
 
 function registerRemoteHandlers() {
+  setRemoteFanout(fanoutIpcEvent);
   removeOrphanedClientFiles(path.join(claudeHome(), 'session-manager'));
   const { validated } = require('./ipcSchemas.cjs');
 
@@ -1430,6 +1587,8 @@ function destroy() {
 }
 
 module.exports = {
+  loadConfig,
+  setIpcDispatcher,
   attachWindow,
   registerRemoteHandlers,
   init,
@@ -1455,6 +1614,7 @@ module.exports = {
     hasReconnectTimer: () => _reconnectTimer !== null,
     cancelReconnect,
     invalidateConfigCache,
+    fanoutIpcEvent,
     setE2eAuthenticated: (key, clientKey = LEGACY_CLIENT_KEY) => {
       _clients.getOrCreate(clientKey).e2e = makeState('authenticated', key, null);
     },

package/src/preload/api.d.ts

@@ -1,4 +1,4 @@
-import type { PromptSession } from '../renderer/state/promptSessions';
+import type { PromptSession, PromptSessionEvent } from '../renderer/state/promptSessions';
 
 /** Mirrors the item shape returned by main/lib/prereqs.cjs checkPrereqs(). */
 export type OpsRetentionSettings = {
@@ -2320,9 +2320,16 @@ export interface SessionManagerAPI {
     setWorktreeDisabled: (payload: PromptSessionsSetWorktreeDisabledPayload) => Promise<PromptSessionsSetWorktreeDisabledResult>;
     /** Archives the raw Claude JSONL to a gzip sidecar main-side; pointer, or null when absent/empty. */
     archiveTranscript: (payload: { cwd: string; epicId: string; claudeSessionId: string }) => Promise<{ path: string; bytes: number; gzBytes: number; sha256: string } | null>;
+    /** Reopens a completed Epic in place (same id + claudeSessionId); never mints an Epic. */
+    reopen: (payload: PromptSessionsReopenPayload) => Promise<PromptSessionsReopenResult>;
   };
 }
 
+export interface PromptSessionsReopenPayload { cwd: string; epicId: string }
+export type PromptSessionsReopenResult =
+  | { ok: true; session: PromptSession; events: PromptSessionEvent[]; alreadyOpen: boolean }
+  | { ok: false; code: 'not_found' | 'transcript_missing' | 'invalid_session_id' | 'restore_failed' | 'write_failed'; message: string };
+
 // ─────────────────────────────────── PromptSessions active-index merge
 export interface PromptSessionsMergeActiveIndexPayload {
   cwd: string;

package/src/preload/apiSurface.cjs

@@ -0,0 +1,19 @@
+/**
+ * apiSurface.cjs — single source of truth for the renderer↔main `window.api`
+ * surface: one row per method exposed by preload/index.cjs.
+ *
+ * kind:   invoke | send | on | on-dynamic (per-tab channel; `*` = the tabId suffix)
+ * remote: policy when the surface is tunnelled to a remote browser
+ *   read   — never writes state, spawns processes, or touches OS UI
+ *   mutate — everything else that is allowed remotely
+ *   deny   — desktop-only (pty, clipboard, shell, updater, config fs access, …)
+ * Classification is conservative: when unsure, mutate; screen/clipboard/fs/shell => deny.
+ *
+ * Drift is caught by __tests__/apiSurface.test.cjs, which replays the real preload.
+ */
+
+'use strict';
+
+const ROWS = require('./apiSurface.json');
+
+module.exports = Object.freeze(ROWS.map((r) => Object.freeze({ ...r })));