claude-code-session-manager 0.62.0 → 0.63.0

package/src/main/runVerify.cjs

@@ -157,6 +157,7 @@ function parseLog(logPath) {
   const events = [];
   let resultEvent = null;
   let seq = 0;
+  let transcriptCommitLanded = false;
 
   for (const line of text.split('\n')) {
     const trimmed = line.trim();
@@ -166,6 +167,18 @@ function parseLog(logPath) {
     try { obj = JSON.parse(trimmed); } catch { continue; }
     if (!obj || typeof obj !== 'object') continue;
 
+    // Harness-emitted commit evidence: git itself produced these lines (a
+    // `vcs_state_changed` system event, or a tool_use_result carrying a
+    // gitOperation), so the model cannot fabricate them. Detected here as a
+    // plain boolean scan — never pushed into `events`, so the index-based
+    // final-20% math elsewhere is unaffected.
+    if (obj.type === 'system' && obj.subtype === 'vcs_state_changed' && obj.kind === 'commit') {
+      transcriptCommitLanded = true;
+    }
+    if (obj.tool_use_result?.gitOperation?.commit?.kind === 'committed') {
+      transcriptCommitLanded = true;
+    }
+
     // Final result event.
     if (obj.type === 'result') {
       const ev = {
@@ -215,7 +228,7 @@ function parseLog(logPath) {
     }
   }
 
-  return { events, resultEvent, error: null };
+  return { events, resultEvent, error: null, transcriptCommitLanded };
 }
 
 // ─── self-recovery helpers ────────────────────────────────────────────────────
@@ -591,6 +604,27 @@ function isAncestorCommit({ cwd, sha, timeoutMs = GH_CHECK_TIMEOUT_MS, execImpl
   }
 }
 
+/**
+ * True when `cwd` is inside a git repository. Used to gate the transcript
+ * commit-evidence fallback below: a job whose cwd is not a git repo can never
+ * produce committedDuringRun=true (gitHead()/committedInWindow() fail closed
+ * there), so the fallback must only apply in that narrow case — never when
+ * git ancestry is actually observable.
+ */
+function isGitRepo(cwd) {
+  if (!cwd) return false;
+  try {
+    execFileSync('git', ['-C', cwd, 'rev-parse', '--git-dir'], {
+      timeout: 10_000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── already-shipped postcondition exemption (original PRD re-runs) ─────────
 
 const PRD_DELIVERABLE_PATH_RE = /(?:^|[`\s(])((?:src|scripts|session-manager-operations|test|tests|docs|bin)\/[A-Za-z0-9_./-]*[A-Za-z0-9_-]\.[A-Za-z0-9]+)\b/g;
@@ -743,12 +777,21 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
     }
 
     // ── 2. Parse log ───────────────────────────────────────────────────────
-    const { events, resultEvent, error: parseError } = parseLog(logPath);
+    const { events, resultEvent, error: parseError, transcriptCommitLanded } = parseLog(logPath);
 
     if (parseError) {
       return conclude('verify_unavailable', `log unreadable: ${parseError}`, 'needs_review');
     }
 
+    // A job whose cwd is not a git repo (e.g. an investigation fix-plan that
+    // inherited cwd: /tmp) can never produce committedDuringRun=true —
+    // gitHead()/committedInWindow() both fail closed there. In that case
+    // ONLY, fall back to the harness-emitted commit evidence in the
+    // transcript, which git itself produced and the model cannot fabricate.
+    const cwdIsGitRepo = isGitRepo(queueEntry?.cwd);
+    const commitEvidence = committedDuringRun || (!cwdIsGitRepo && transcriptCommitLanded);
+    const commitEvidenceSource = (!committedDuringRun && commitEvidence) ? 'transcript' : null;
+
     // ── 3. HALT detection ─────────────────────────────────────────────────
     // Primary: check the final `{"type":"result"}` event's `result` text.
     if (resultEvent) {
@@ -865,7 +908,7 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
     // committed anything nor ever emitted the finish-protocol sentinel likely
     // ended before doing real work (e.g. stopped on a clarifying question).
     // Weaker evidence than a caught transcript error, but still not clean.
-    if (sentinel === null && !committedDuringRun) {
+    if (sentinel === null && !commitEvidence) {
       issues.push({
         verdict: 'no_verdict_sentinel',
         reason: 'run made no commit and emitted no SCHEDULER_VERDICT sentinel — likely ended before the finish protocol (e.g. stopped on a clarifying question)',
@@ -894,7 +937,7 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
     // bare PASS with no commit from one is still a strong silent-failure
     // signal and stays covered by this check.
     const isFixPlanJob = /^\d+-fix-/.test(queueEntry?.slug || '');
-    if (sentinel === 'pass' && !committedDuringRun && !isFixPlanJob) {
+    if (sentinel === 'pass' && !commitEvidence && !isFixPlanJob) {
       // EXEMPTION: `-merge-main` PRDs (see isMergeMainSlug) can genuinely and
       // correctly find nothing left to do when an out-of-band actor (a human,
       // another agent, a sibling scheduler job) already merged/updated the
@@ -1015,13 +1058,18 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
     // MUST NOT apply to halt or deps_unmet — those keep their existing semantics.
     if (
       sentinel === 'pass'
-      && committedDuringRun
+      && commitEvidence
       && (top.verdict === 'transcript_errors' || top.verdict === 'verify_unavailable')
     ) {
       return conclude('clean',
         `SCHEDULER_VERDICT: PASS + commit landed overrides ${top.verdict}`,
         null,
-        { ...(annotations.length ? { annotations } : {}), sentinel, sentinelOverride: top.verdict },
+        {
+          ...(annotations.length ? { annotations } : {}),
+          sentinel,
+          sentinelOverride: top.verdict,
+          ...(commitEvidenceSource ? { commitEvidenceSource } : {}),
+        },
       );
     }
 
@@ -1073,4 +1121,5 @@ module.exports = {
   extractPrdDeliverablePaths,
   allDeliverablesAlreadyTracked,
   isAncestorCommit,
+  isGitRepo,
 };

package/src/main/scheduler.cjs

@@ -271,6 +271,28 @@ function gitHead(cwd) {
   });
 }
 
+// True when cwd is inside a git repository. Used to keep a non-git cwd (e.g.
+// a scratch dir like /tmp) from ever being handed to an investigation's
+// fix-plan as its cwd — the commit guard, worktree isolation, and
+// runVerify's PASS+commit sentinel override all read git state from job.cwd,
+// so a fix plan rooted at a non-repo path gets parked in needs_review even
+// when its commit really landed (Incident: 99-fix-e2e-needs-review-test,
+// 2026-08-07 — green, committed 6ecbd40, PASS sentinel, still needs_review).
+// Bounded and never throws.
+function isGitRepoSync(cwd) {
+  if (!cwd) return false;
+  try {
+    execFileSync('git', ['-C', cwd, 'rev-parse', '--git-dir'], {
+      timeout: 10_000,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Best-effort `git fetch --all --prune` in cwd, bounded and never throwing.
 // A PRD that does its work in a separate `git worktree add` checkout (per
 // standards.md's own recommended pattern for shared repos) commits and pushes
@@ -2666,6 +2688,10 @@ ${logTail}
    estimateMinutes: <your time estimate>
    ---
    \`\`\`
+   \`cwd\` must be the git repo root where the fix will actually land. If the failed job's cwd is
+   not that repo (e.g. a scratch dir like \`/tmp\`), set \`cwd:\` to the correct repo root instead —
+   the scheduler's commit guard and post-run verifier read git state from this path, and a
+   non-repo cwd parks even a fully green, committed run in \`needs_review\`.
 6. The PRD body MUST be self-contained — \`claude -p\` runs it on a fresh Sonnet session with NO conversation context. Include:
    - Root-cause analysis (what went wrong and why)
    - Concrete fix steps (specific files / commands / edits)
@@ -2803,6 +2829,16 @@ async function spawnInvestigation(failedJob, runDir) {
     console.warn(`[scheduler] investigation cwd missing (${cwd}); falling back to ${DEFAULT_PROJECT_CWD}`);
     cwd = DEFAULT_PROJECT_CWD;
   }
+  // A non-git cwd is unusable as a fix-plan cwd: the commit guard, worktree
+  // isolation, and runVerify's PASS+commit sentinel override all read git
+  // state from job.cwd, so a fix plan rooted at e.g. /tmp gets parked in
+  // needs_review even when its commit really landed. (Incident:
+  // 99-fix-e2e-needs-review-test, 2026-08-07 — green, committed 6ecbd40,
+  // PASS sentinel, still needs_review.)
+  if (!isGitRepoSync(cwd)) {
+    console.warn(`[scheduler] investigation cwd is not a git repo (${cwd}); falling back to ${DEFAULT_PROJECT_CWD}`);
+    cwd = DEFAULT_PROJECT_CWD;
+  }
   const prompt = buildInvestigationPrompt({ failedJob, cwd, failedLogPath, originalBody, logTail, fixPath, group });
 
   // Phase 1: open log fd for pre-spawn diagnostics.
@@ -3024,11 +3060,12 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       await setPaused('rate_limit', resetIso);
     }
 
-    // Stale queue entry: the PRD already shipped and was archived before this
-    // run fired (see archivedTwinExists in executeJob). Treat it as a plain
-    // completion — no verify pass, no commit guard, no RCA feedback — since
-    // there is no real transcript/commit to check.
-    if (res.skipped === 'prd-archived') {
+    // Stale queue entry: the PRD was archived (already shipped) or is gone
+    // from disk entirely (deleted before dispatch). Both are retire-not-fail
+    // results from prdArchivedSkipResult with exitCode 0 and no transcript —
+    // treat any truthy skip reason as a plain completion: no verify pass, no
+    // commit guard, no RCA feedback item.
+    if (res.skipped) {
       await mutate((s) => {
         const idx = s.jobs.findIndex((x) => x.slug === job.slug);
         if (idx >= 0) {
@@ -4765,7 +4802,9 @@ async function init() {
   }
 }
 
-// remote — callable from webRemote.cjs without going through IPC.
+// remote — in-process (non-IPC) scheduler accessors, used by prdCreate.cjs
+// and other main-process callers. (Named for the retired web-remote relay,
+// its original consumer; kept because it still has in-process callers.)
 const remote = {
   // `cwd` is optional: prdCreate.cjs's create flow passes the target
   // project's cwd explicitly (the file may not exist yet, so there's
@@ -4956,4 +4995,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, resolveVerifyPrdPath, resolveNotifyPrd, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, healRefusalReason, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, isGitRepoSync, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, resolveVerifyPrdPath, resolveNotifyPrd, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult, spawnJob };

package/src/main/transcripts.cjs

@@ -126,8 +126,23 @@ async function readDelta(sub) {
   }
 }
 
+// Cap on the number of events carried in a single `transcript:event:<tabId>`
+// IPC message. One flush can classify a large delta (e.g. a rotated/replayed
+// transcript, or the 8 MB MAX_DELTA_BYTES window) into far more than a
+// screenful of events — sending them all as one unbounded array risks a
+// single oversized IPC payload. Above this count, doFlush sends multiple
+// ordered batches instead of one giant one; each still lands as one store
+// commit on the renderer side.
+const MAX_EVENTS_PER_BATCH = 200;
+
 async function doFlush(sub, { emit = true } = {}) {
   const lines = await readDelta(sub);
+  let batch = [];
+  const flushBatch = () => {
+    if (batch.length === 0) return;
+    if (emit) sendIfAlive(window, `transcript:event:${sub.tabId}`, batch);
+    batch = [];
+  };
   for (const line of lines) {
     // Index every line — including ones that fail to parse — so line numbers
     // and byte offsets stay correct for paged reads regardless of content.
@@ -142,13 +157,13 @@ async function doFlush(sub, { emit = true } = {}) {
     const ref = { filePath: sub.filePath, byteOffset: line.byteOffset, byteLength: line.byteLength };
     const events = classifyLine(obj, ref);
     for (const ev of events) {
-      if (emit) sendIfAlive(window, `transcript:event:${sub.tabId}`, ev);
+      batch.push(ev);
       // Mirror to OTEL — no-op when disabled. We emit on the initial drain too
       // so backfilled transcripts show up in the trace store. One span per
-      // emitted event, not per line. doFlush only ever processes a given
-      // line once (readDelta never re-returns already-consumed bytes), so
-      // this can't double-record — paged re-reads (readPage) go through a
-      // separate code path below that never touches OTEL.
+      // emitted event, not per line or per batch. doFlush only ever processes
+      // a given line once (readDelta never re-returns already-consumed
+      // bytes), so this can't double-record — paged re-reads (readPage) go
+      // through a separate code path below that never touches OTEL.
       otel.recordTranscriptEvent({
         tabId: sub.tabId,
         tabCwd: sub.cwd,
@@ -156,8 +171,10 @@ async function doFlush(sub, { emit = true } = {}) {
         data: ev.data,
         ts: Date.now(),
       });
+      if (batch.length >= MAX_EVENTS_PER_BATCH) flushBatch();
     }
   }
+  flushBatch();
 }
 
 /**
@@ -525,4 +542,11 @@ module.exports = {
   // particular) — asserting a memory ceiling requires inspecting what's
   // actually held, not just what a read API returns.
   __getSubForTest: (tabId) => subs.get(tabId),
+  // Test-only: run a live (emit:true) flush directly against a subscription,
+  // without going through the chokidar watcher — lets batching/IPC-shape
+  // tests stay deterministic instead of racing a filesystem watch event.
+  __doFlushForTest: (sub, opts) => doFlush(sub, opts),
+  // Batch size cap for a single transcript:event IPC message — exported so
+  // tests can size fixtures against it without a magic-number duplicate.
+  MAX_EVENTS_PER_BATCH,
 };

package/src/preload/api.d.ts

@@ -29,82 +29,6 @@ export interface WriteErrorEvent {
   reason: string;
 }
 
-export interface BrowserNavState {
-  url: string;
-  title: string;
-  canGoBack: boolean;
-  canGoForward: boolean;
-  loading: boolean;
-  isSecure: boolean;
-}
-
-/** One captured recorder step (PRD 408 engine → PRD 409 panel). */
-export interface RecordStep {
-  n: number;
-  /** `select` is accepted by replay/export (PRD 410) for forward-compat;
-   * the live engine does not emit it yet. */
-  verb: 'navigate' | 'click' | 'type' | 'select' | 'wait-for' | 'drag';
-  target: string;
-  kind?: 'nav' | 'assert';
-  /** True for `type` steps — the actual typed value is never captured. */
-  masked?: boolean;
-  /** Engine-suggested `{{var}}` name for a `type` step (e.g. field name). */
-  variableSuggestion?: string;
-  /** Renderer-owned: set once the user checks "parameterize as {{var}}". */
-  variable?: string | null;
-  /** `select` steps only — the option value to choose on replay/export. */
-  value?: string;
-  /** Click position, or drag-start position for `drag` steps. */
-  x?: number;
-  /** Click position, or drag-start position for `drag` steps. */
-  y?: number;
-  /** `drag` steps only — drag-end target selector. */
-  endTarget?: string;
-  /** `drag` steps only — drag-end x position. */
-  endX?: number;
-  /** `drag` steps only — drag-end y position. */
-  endY?: number;
-}
-
-/** Per-step replay outcome (PRD 410), streamed as `browser:replay-step:<viewId>`. */
-export interface ReplayStepResult {
-  n: number;
-  status: 'pass' | 'fail';
-  detail?: string;
-}
-
-/** find-in-page result (PRD 402), streamed as `browser:find-result:<viewId>`. */
-export interface FindResult {
-  requestId: number;
-  matches: number;
-  activeMatchOrdinal: number;
-}
-
-/** Element-picker event (PRD 403), streamed as `browser:picker-event:<viewId>`. */
-export interface PickerEvent {
-  type: 'hover' | 'pick' | 'unpick' | 'exit';
-  selector?: string;
-  label?: string;
-  tag?: string;
-  rect?: { x: number; y: number; width: number; height: number };
-  /** Present on a 'pick' event fired by an unmodified click — the selection was replaced, not accumulated. */
-  replace?: boolean;
-}
-
-/** One entry in `~/.claude/session-manager/browser/history.json` (PRD 402). */
-export interface BrowserHistoryEntry {
-  url: string;
-  title: string;
-  ts: number;
-}
-
-/** One entry in `~/.claude/session-manager/browser/bookmarks.json` (PRD 402). */
-export interface BrowserBookmark {
-  url: string;
-  title: string;
-  ts: number;
-}
-
 export interface ReadJsonResult {
   exists: boolean;
   raw: string;
@@ -119,6 +43,13 @@ export interface ReadTextResult {
   text: string;
   mtimeMs: number;
   error: string | null;
+  /** True when maxBytes was set and the file is larger than the read prefix. */
+  truncated: boolean;
+}
+
+export interface ReadTextOptions {
+  /** Read at most this many bytes from the start of the file instead of the whole file. */
+  maxBytes?: number;
 }
 
 /** One resolved node in a CLAUDE.md-like file's `@path` import chain. */
@@ -133,7 +64,7 @@ export interface ImportRef {
 /** Declared owner ids for the single-writer law over a project's
  *  session-manager-operations/ root. Mirrors OWNERS in
  *  src/main/lib/opsOwnership.cjs — one writer per namespace; everyone reads. */
-export type OpsWriter = 'epics' | 'scheduler' | 'project-home' | 'browser';
+export type OpsWriter = 'epics' | 'scheduler' | 'project-home';
 
 export interface WriteResult {
   ok: boolean;
@@ -1162,46 +1093,6 @@ export interface PluginInstallProgressEvent {
   line: string;
 }
 
-// ────────────────────────────────────────────── Web Remote (PRD 08)
-
-export interface WebRemoteDevice {
-  deviceId: string;
-  deviceName: string;
-  issuedAt: string;
-  lastConnectedAt: string | null;
-}
-
-export interface WebRemoteStatus {
-  enabled: boolean;
-  remoteControlEnabled: boolean;
-  connected: boolean;
-  e2eActive: boolean;
-  /** True once the user has confirmed the SAS on the desktop. */
-  e2eAuthenticated: boolean;
-  /** Explicit E2E session state for UI rendering. */
-  e2eState: 'idle' | 'pending_sas' | 'authenticated' | 'failed';
-  /** 6-digit Short Authentication String pending user confirmation, or null. */
-  pendingSas: string | null;
-  devices: WebRemoteDevice[];
-}
-
-export interface WebRemotePairResult {
-  ok: boolean;
-  deviceId?: string;
-  error?: string;
-}
-
-export interface WebRemoteMutationResult {
-  ok: boolean;
-  error?: string;
-}
-
-export interface WebRemoteAuditTailResult {
-  ok: boolean;
-  lines?: string[];
-  error?: string;
-}
-
 // ────────────────────────────────────────────── Chat runner (PRD 319)
 
 export interface ChatRunPayload {
@@ -1344,63 +1235,6 @@ export interface SessionManagerAPI {
     onExit: (tabId: string, handler: (info: PtyExit) => void) => () => void;
     onWriteError: (handler: (ev: WriteErrorEvent) => void) => () => void;
   };
-  browser: {
-    create: (payload: { viewId: string; partition: string }) => Promise<{ ok: boolean }>;
-    setBounds: (payload: { viewId: string; x: number; y: number; width: number; height: number }) => Promise<{ ok: boolean }>;
-    show: (viewId: string) => Promise<{ ok: boolean }>;
-    hide: (viewId: string) => Promise<{ ok: boolean }>;
-    destroy: (viewId: string) => Promise<{ ok: boolean }>;
-    navigate: (payload: { viewId: string; url: string }) => Promise<{ ok: boolean; error?: string }>;
-    back: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    forward: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    reload: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    stop: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    onNavState: (viewId: string, handler: (state: BrowserNavState) => void) => () => void;
-    recordStart: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    recordStop: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    onRecordStep: (viewId: string, handler: (step: RecordStep) => void) => () => void;
-    captureDom: (payload: { viewId: string; kind: 'text' | 'html' }) => Promise<
-      | { ok: true; url: string; title: string; text: string; truncated?: boolean }
-      | { ok: false; error: string }
-    >;
-    captureShot: (viewId: string) => Promise<
-      | { ok: true; url: string; title: string; dataUrl: string }
-      | { ok: false; error: string }
-    >;
-    saveBinary: (path: string, base64: string, writer?: OpsWriter) => Promise<{ ok: boolean; error?: string }>;
-    /** Opens a native "Save As" dialog and writes `text` to the chosen path directly
-     *  (bypasses config.cjs's write-boundary check — the path is user-chosen via OS dialog). */
-    saveRecording: (payload: { defaultName: string; text: string }) => Promise<
-      | { ok: true; path: string }
-      | { ok: false; canceled: true }
-      | { ok: false; error: string }
-    >;
-    replay: (payload: {
-      viewId: string;
-      steps: RecordStep[];
-      values?: Record<string, string>;
-      continueOnError?: boolean;
-    }) => Promise<{ ok: boolean; error?: string; stopped?: boolean; failedAt?: number }>;
-    onReplayStep: (viewId: string, handler: (step: ReplayStepResult) => void) => () => void;
-    setZoom: (payload: { viewId: string; factor: number }) => Promise<{ ok: boolean; error?: string; factor?: number }>;
-    find: (payload: { viewId: string; text: string; forward?: boolean }) => Promise<{ ok: boolean; error?: string }>;
-    stopFind: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    onFindResult: (viewId: string, handler: (result: FindResult) => void) => () => void;
-    pickerStart: (viewId: string) => Promise<{ ok: boolean; error?: string }>;
-    pickerStop: (viewId: string) => Promise<{ ok: boolean; error?: string; wasPicking?: boolean }>;
-    onPickerEvent: (viewId: string, handler: (ev: PickerEvent) => void) => () => void;
-    /** Selection-scoped capture pipeline (PRD 404): filter -> prune -> summarize -> chunk for 'agent', outerHTML for 'html', CDP AX-tree for 'a11y', fallback-chain for 'selector'. */
-    capture: (payload: {
-      viewId: string;
-      selectors: string[];
-      mode: 'agent' | 'html' | 'a11y' | 'selector';
-    }) => Promise<
-      | { ok: true; mode: string; text: string; meta: { chunks?: number; tokens?: number } }
-      | { ok: false; error: string }
-    >;
-    /** Fired when the embedded page tries to open a new window (target="_blank", window.open, ctrl/cmd-click) — the main process denies the native popup and forwards the URL here. */
-    onOpenTabRequest: (handler: (payload: { url: string }) => void) => () => void;
-  };
   transcripts: {
     subscribe: (payload: { tabId: string; cwd: string; sessionUuid: string }) => Promise<SubscribeResult>;
     /** Release the sub back to the LRU cache (view-switch). Does not destroy the watcher. */
@@ -1418,7 +1252,10 @@ export interface SessionManagerAPI {
      *  session with no transcript file yet (or one over the main-process size
      *  cap) maps to null. */
     usageFor: (cwd: string, sessionIds: string[]) => Promise<Record<string, { inputTokens: number; outputTokens: number } | null>>;
-    onEvent: (tabId: string, handler: (ev: TranscriptEvent) => void) => () => void;
+    /** Fires once per main-process flush with the ORDERED batch of events that
+     *  flush produced (never one call per event) — see transcripts.cjs's
+     *  doFlush / MAX_EVENTS_PER_BATCH. */
+    onEvent: (tabId: string, handler: (events: TranscriptEvent[]) => void) => () => void;
   };
   sessions: {
     load: () => Promise<LoadedSessions>;
@@ -1454,7 +1291,7 @@ export interface SessionManagerAPI {
   };
   config: {
     readJson: (path: string) => Promise<ReadJsonResult>;
-    readText: (path: string) => Promise<ReadTextResult>;
+    readText: (path: string, opts?: ReadTextOptions) => Promise<ReadTextResult>;
     /** `writer` declares the owning surface for the single-writer law — required
      *  when `path` is inside a project's session-manager-operations/ root. */
     writeJson: (path: string, data: unknown, writer?: OpsWriter) => Promise<WriteResult>;
@@ -1499,6 +1336,10 @@ export interface SessionManagerAPI {
     status: () => Promise<OtelStatus>;
     configPath: () => Promise<string>;
   };
+  diagnostics: {
+    /** Rejects unless the main process has SM_HEAP_SNAPSHOT=1 set. */
+    takeHeapSnapshot: () => Promise<{ filePath: string; bytes: number | null; ms: number }>;
+  };
   files: {
     list: (path: string, showHidden?: boolean) => Promise<FilesListResult>;
     read: (path: string) => Promise<FilesReadResult>;
@@ -1507,6 +1348,7 @@ export interface SessionManagerAPI {
     rename: (path: string, newName: string) => Promise<FilesRenameResult>;
     delete: (path: string) => Promise<FilesDeleteResult>;
     duplicate: (path: string) => Promise<FilesDuplicateResult>;
+    saveBinary: (path: string, base64: string, writer?: OpsWriter) => Promise<{ ok: boolean; error?: string }>;
   };
   docEdit: {
     run: (payload: { path: string; before: string; instruction: string; documentText?: string }) => Promise<DocEditResult>;
@@ -1616,8 +1458,6 @@ export interface SessionManagerAPI {
       | { ok: true; text: string }
       | { ok: false; error?: string }
     >;
-    /** Write side — copies a Capture-panel screenshot data URL to the OS clipboard. */
-    copyImage: (dataUrl: string) => Promise<{ ok: boolean; error?: string }>;
     /** Write side — copies arbitrary text (e.g. a recorded flow export) to the OS clipboard. */
     writeText: (text: string) => Promise<{ ok: boolean; error?: string }>;
   };
@@ -1704,27 +1544,6 @@ export interface SessionManagerAPI {
      *  renderer needs per-row badges without a separate git call per file. */
     fileStatus: (cwd: string) => Promise<GitFileStatusMap>;
   };
-  webRemote: {
-    getStatus: () => Promise<WebRemoteStatus>;
-    enable: () => Promise<WebRemoteMutationResult>;
-    disable: () => Promise<WebRemoteMutationResult>;
-    /** Allow MUTATE-tier commands (pty spawn/write, scheduler writes). Default off. */
-    enableControl: () => Promise<WebRemoteMutationResult>;
-    /** Block MUTATE-tier commands — mobile becomes read-only mirror. */
-    disableControl: () => Promise<WebRemoteMutationResult>;
-    pair: (otp: string) => Promise<WebRemotePairResult>;
-    revokeDevice: (deviceId: string) => Promise<WebRemoteMutationResult>;
-    auditTail: (lines?: number) => Promise<WebRemoteAuditTailResult>;
-    onStatus: (handler: (status: WebRemoteStatus) => void) => () => void;
-    onTokenRevoked: (handler: (ev: { deviceId: string }) => void) => () => void;
-    /** Revoke ALL paired devices and tear down every session immediately (panic). */
-    revokeAll: () => Promise<WebRemoteMutationResult>;
-    /** Subscribe to the completion event broadcast after revokeAll. */
-    onRevokedAll: (handler: (ev: { revokedCount: number }) => void) => () => void;
-    /** Confirm that the SAS shown on the desktop matches the browser — marks the
-     *  E2E session as authenticated and unblocks MUTATE-tier commands. */
-    confirmSas: () => Promise<WebRemoteMutationResult>;
-  };
   chat: {
     /** Spawn a headless `claude -p` run for a tab. Results arrive via the on* listeners. */
     run: (payload: ChatRunPayload) => Promise<{ ok: boolean }>;