claude-code-session-manager 0.37.1 → 0.38.0

package/src/main/lib/rcaFeedbackHook.cjs

@@ -38,8 +38,8 @@ const PRDS_DIR = path.join(os.homedir(), '.claude', 'session-manager', 'schedule
 const SM_REPO_ROOT = path.join(os.homedir(), 'Projects', 'session-manager');
 const SM_REPO_FEEDBACK_DIR = path.join(SM_REPO_ROOT, 'session-manager-operations', 'feedback');
 
-// NEVER write here: ~/.claude/session-manager/feedback/ is the external
-// watchdog's auto-PRD intake (scripts/scheduler-watchdog.cjs `sweep()`) — it
+// NEVER write here: ~/.claude/session-manager/feedback/ is the scheduler's
+// auto-PRD intake (src/main/scheduler.cjs's periodic feedback sweep) — it
 // converts anything dropped there into a scheduled PRD automatically. Filing
 // an RCA there would create an RCA → auto-PRD → run → needs_review → RCA
 // cycle with no human in the loop. Both real destinations below are project

package/src/main/lib/singleInstanceGuard.cjs

@@ -0,0 +1,20 @@
+/**
+ * singleInstanceGuard.cjs — the losing side of Electron's single-instance
+ * lock must actually terminate the process, not just request a quit.
+ *
+ * app.quit() only requests a graceful shutdown via the normal
+ * window-all-closed -> quit -> exit chain; a losing instance calls it before
+ * app.whenReady() ever fires (no window, no IPC), so there's nothing for
+ * that chain to hook into and the process can sit as a zombie indefinitely.
+ * app.exit() terminates immediately without waiting on that chain; the
+ * setTimeout is a defense-in-depth backstop in case app.exit() itself is
+ * ever delayed by an Electron internal on a future version.
+ */
+'use strict';
+
+function terminateLosingInstance(app, { fallbackDelayMs = 2000 } = {}) {
+  setTimeout(() => process.exit(0), fallbackDelayMs).unref?.();
+  app.exit(0);
+}
+
+module.exports = { terminateLosingInstance };

package/src/main/scheduler.cjs

@@ -63,6 +63,7 @@ const prdParser = require('./scheduler/prdParser.cjs');
 const { verifyRun } = require('./runVerify.cjs');
 const logs = require('./logs.cjs');
 const { schemas, validated } = require('./ipcSchemas.cjs');
+const { readBody, sendJson } = require('./lib/localAdminHttp.cjs');
 const {
   POLL_INTERVAL_MS,
   USAGE_REFRESH_INTERVAL_MS,
@@ -74,6 +75,12 @@ const { runDefinitionOfDoneOnDrain } = require('./lib/dodDrainHook.cjs');
 const { fileRcaFeedback, extractRcaBlock } = require('./lib/rcaFeedbackHook.cjs');
 const queueHistory = require('./lib/queueHistory.cjs');
 const queueOps = require('./queueOps.cjs');
+// Feedback-auto-PRD sweep — formerly only run by the external scheduler-watchdog
+// while the app was down (PRD 686 moved it in-app so it also runs while alive).
+// Plain Node module, no Electron dependency; queuePath/prdsDir defaults already
+// match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
+// home-dir layout.
+const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
 
 const MAX_INVESTIGATION_DURATION_MS = 30 * 60_000;
 
@@ -201,15 +208,38 @@ function gitHead(cwd) {
   });
 }
 
+// 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
+// from THAT worktree, then removes it — the commit never touches job.cwd's
+// own refs, so job.cwd's remote-tracking branches can be stale relative to
+// what was actually pushed. Refreshing them here is what lets the git log
+// --all scan below see a worktree-pushed commit. Resolves once fetch settles
+// (or times out / errors) — callers don't need the result, just the refresh.
+function fetchAllRefs(cwd) {
+  return new Promise((resolve) => {
+    if (!cwd) { resolve(); return; }
+    execFile(
+      'git',
+      ['-C', cwd, 'fetch', '--all', '--prune'],
+      { timeout: 20_000, windowsHide: true },
+      () => resolve(),
+    );
+  });
+}
+
 // Returns true if ≥1 commit landed on any ref (branch, remote-tracking branch,
 // or tag) in cwd between startedAt and finishedAt (with 60s slack) — not just
-// the currently checked-out branch. Used by the self-heal pass to derive
-// committedDuringRun from the recorded run window — the live commit-guard uses
-// gitHead() instead. Never throws; git-unavailable → false (no override, job
-// stays as-is).
-function committedInWindow(cwd, startedAt, finishedAt) {
+// the currently checked-out branch. Used both by the self-heal pass and by the
+// live commit-guard's fallback (see computeCommittedDuringRun) to derive
+// committedDuringRun from the recorded run window. Fetches remotes first (see
+// fetchAllRefs) so a commit pushed from a separate worktree checkout that was
+// since removed is still visible via job.cwd's remote-tracking refs. Never
+// throws; git-unavailable → false (no override, job stays as-is).
+async function committedInWindow(cwd, startedAt, finishedAt) {
+  if (!cwd || !startedAt) return false;
+  await fetchAllRefs(cwd);
   return new Promise((resolve) => {
-    if (!cwd || !startedAt) { resolve(false); return; }
     const until = finishedAt
       ? new Date(Date.parse(finishedAt) + 60_000).toISOString()
       : new Date().toISOString();
@@ -222,6 +252,16 @@ function committedInWindow(cwd, startedAt, finishedAt) {
   });
 }
 
+// Live commit-guard: cheap HEAD-diff fast path, falling back to the
+// git-log --all scan when HEAD didn't move on the starting branch. A PRD that
+// checks out other branches, commits real work on each, then checks its
+// starting branch back out before exit leaves HEAD unchanged even though
+// commits landed — the fallback catches that case. Never throws.
+async function computeCommittedDuringRun(cwd, headBefore, headAfter, startedAt, untilIso) {
+  if (headBefore && headAfter && headBefore !== headAfter) return true;
+  return committedInWindow(cwd, startedAt, untilIso);
+}
+
 const ROOT = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans');
 const PRDS_DIR = path.join(ROOT, 'prds');
 const RUNS_DIR = path.join(ROOT, 'runs');
@@ -817,6 +857,17 @@ let resumeTimer = null;
 let pollLoopTimer = null;
 let rescheduleInterval = null;
 let heartbeatInterval = null;
+// Feedback sweep piggybacks on the 60s heartbeat tick but runs far less often —
+// every Nth tick — since it's a readdir-per-active-project scan, not free.
+// 5 ticks = 5 minutes; well inside sweep()/activeProjectCwds()'s 90-minute
+// active-session window, so no active project can be missed between sweeps.
+const FEEDBACK_SWEEP_TICK_INTERVAL = 5;
+let feedbackSweepTickCount = 0;
+/** Pure gate for the tick counter above — exported so the wiring is testable
+ *  without waiting on real setInterval timers. */
+function feedbackSweepDue(tickCount, interval = FEEDBACK_SWEEP_TICK_INTERVAL) {
+  return tickCount >= interval;
+}
 // In-memory set of slugs currently spawned in this process. Prevents
 // double-spawn when runDueJobs() is called while jobs are in flight.
 const runningSet = new Set();
@@ -1059,6 +1110,79 @@ function resetJobFields(job, errorMsg) {
   delete job.verifierVerdict;
 }
 
+// Grace period between a boot orphan's SIGTERM and reading its log to
+// classify the outcome — matches killOrphanClaudePid's own internal 5s
+// SIGKILL follow-up delay, plus a small margin so classification always runs
+// after that SIGKILL has had a chance to land.
+const BOOT_ORPHAN_KILL_GRACE_MS = 6000;
+
+/**
+ * partitionBootOrphans(jobs, isAlive?) → { immediate: string[], deferred: string[] }
+ *
+ * Pure decision split for boot reconciliation. A 'running' job whose recorded
+ * pid is still alive must NOT be classified from its log yet — the orphaned
+ * process may still be writing to it, so reading now risks misclassifying a
+ * job that is about to emit result:success as no_result and double-running it.
+ * Ported from reconcileQueueOffline's cross-tick escalation (see
+ * scripts/lib/watchdogHelpers.cjs) — here it's a single deferred window since
+ * this process stays up to revisit it, rather than a separate short-lived
+ * watchdog process needing another tick.
+ */
+function partitionBootOrphans(jobs, isAlive = claudePidAlive) {
+  const immediate = [];
+  const deferred = [];
+  for (const j of jobs) {
+    if (j.status !== 'running') continue;
+    const pid = j.runtime?.pid;
+    if (pid && isAlive(pid)) {
+      deferred.push(j.slug);
+    } else {
+      immediate.push(j.slug);
+    }
+  }
+  return { immediate, deferred };
+}
+
+/**
+ * applyOrphanOutcome(job, outcome, killNote?) → void
+ *
+ * Mutates `job` in place to finalize a boot-orphaned 'running' job given its
+ * classified run outcome: success/failed finalize terminally; no_result/unknown
+ * re-queues to pending bounded by ORPHAN_REQUEUE_CAP. The status-mutation
+ * semantics (and the cap-exhaustion boundary) match the now-deleted
+ * reconcileQueueOffline (scripts/lib/watchdogHelpers.cjs) verbatim; killNote
+ * plumbing differs slightly (see call sites) since this path always knows
+ * pid liveness up front rather than re-checking per tick.
+ */
+function applyOrphanOutcome(job, outcome, killNote = '') {
+  const now = new Date().toISOString();
+  if (outcome === 'success') {
+    job.status = 'completed';
+    job.exitCode = 0;
+    job.error = null;
+    job.finishedAt = now;
+    delete job.runtime;
+  } else if (outcome === 'failed') {
+    job.status = 'failed';
+    job.exitCode = job.exitCode ?? 1;
+    job.error = `orphaned: app restarted while running${killNote}`;
+    job.finishedAt = now;
+    delete job.runtime;
+  } else {
+    const tries = job.orphanRetries ?? 0;
+    if (tries < ORPHAN_REQUEUE_CAP) {
+      resetJobFields(job, `orphaned: app restarted mid-run, re-queued (attempt ${tries + 1}/${ORPHAN_REQUEUE_CAP})${killNote}`);
+      job.orphanRetries = tries + 1;
+    } else {
+      job.status = 'failed';
+      job.exitCode = job.exitCode ?? 1;
+      job.error = `orphaned: app restarted while running, exhausted ${ORPHAN_REQUEUE_CAP} re-queue attempts${killNote}`;
+      job.finishedAt = now;
+      delete job.runtime;
+    }
+  }
+}
+
 /** Scan the tail of a job's log for the canonical rate-limit signal. We look
  *  at the last 16 KB — final result event always lands at the end.
  *  Uses readTail() so no raw fd lifecycle is needed here. */
@@ -1730,7 +1854,13 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       // Used by the sentinel override: SCHEDULER_VERDICT: PASS + a landed
       // commit together override incidental transcript noise verdicts.
       const headAtExit = await gitHead(guardCwd);
-      const committedDuringRun = !!(guardHeadBefore && headAtExit && guardHeadBefore !== headAtExit);
+      const committedDuringRun = await computeCommittedDuringRun(
+        guardCwd,
+        guardHeadBefore,
+        headAtExit,
+        job.startedAt,
+        new Date().toISOString(),
+      );
 
       const prdPath = path.join(PRDS_DIR, `${job.slug}.md`);
       const stateForDeps = await readQueue();
@@ -2944,65 +3074,60 @@ async function init() {
   // classifyRunOutcome calls readTail → fs.readFileSync (up to 64 KB per job).
   // Pre-compute all outcomes BEFORE entering the mutate lock so the blocking I/O
   // does not stall the event loop or hold the mutateTail chain during startup.
+  //
+  // Jobs whose recorded pid is still alive are deferred (not classified here) —
+  // see partitionBootOrphans. Everything else (dead pid or no pid) is safe to
+  // classify immediately below.
   const bootSnap = readQueueSync();
+  const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
   const bootOutcomes = new Map();
   for (const j of bootSnap.jobs) {
-    if (j.status !== 'running') continue;
+    if (!immediateSlugs.includes(j.slug)) continue;
     const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
     bootOutcomes.set(j.slug, logPath ? classifyRunOutcome(logPath) : 'unknown');
   }
   await mutate((state) => {
     for (const j of state.jobs) {
-      if (j.status !== 'running') continue;
-      const pid = j.runtime?.pid;
-      let killNote = '';
-      if (pid) {
-        const result = killOrphanClaudePid(pid);
-        killNote = ` (orphan pid=${pid}: ${result})`;
-        if (result === 'killed') {
-          console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${j.slug}`);
-        }
-      }
+      if (j.status !== 'running' || !immediateSlugs.includes(j.slug)) continue;
       const outcome = bootOutcomes.get(j.slug) ?? 'unknown';
-      if (outcome === 'success') {
-        // Job finished cleanly before the crash — keep the win.
-        j.status = 'completed';
-        j.exitCode = 0;
-        j.error = null;
-        j.finishedAt = new Date().toISOString();
-        delete j.runtime;
-        console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=success → completed`);
-      } else if (outcome === 'failed') {
-        // The log carries a real failure result event — a genuine failure, keep it.
-        j.status = 'failed';
-        j.exitCode = j.exitCode ?? 1;
-        j.error = `orphaned: app restarted while running${killNote}`;
-        j.finishedAt = new Date().toISOString();
-        delete j.runtime;
-        console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=failed → failed`);
-      } else {
-        // no_result / unknown: the run was interrupted (host died / app restarted)
-        // with NO evidence it failed on its own merits. Punishing the PRD here is
-        // the wrong call — it demands a manual flip and burns an Opus fix-plan on a
-        // job that never actually failed. Re-queue it (bounded) so an app restart
-        // self-recovers. Mirrors the transient-kill auto-retry on the live path.
-        const tries = j.orphanRetries ?? 0;
-        if (tries < ORPHAN_REQUEUE_CAP) {
-          resetJobFields(j, `orphaned: app restarted mid-run, re-queued (attempt ${tries + 1}/${ORPHAN_REQUEUE_CAP})${killNote}`);
-          j.orphanRetries = tries + 1;
-          console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → re-queued (${tries + 1}/${ORPHAN_REQUEUE_CAP})`);
-        } else {
-          j.status = 'failed';
-          j.exitCode = j.exitCode ?? 1;
-          j.error = `orphaned: app restarted while running, exhausted ${ORPHAN_REQUEUE_CAP} re-queue attempts${killNote}`;
-          j.finishedAt = new Date().toISOString();
-          delete j.runtime;
-          console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → failed (orphan retries exhausted)`);
-        }
-      }
+      const pid = j.runtime?.pid;
+      const killNote = pid ? ` (orphan pid=${pid}: dead)` : '';
+      applyOrphanOutcome(j, outcome, killNote);
+      console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → status=${j.status}`);
     }
   });
 
+  // Still-alive orphans: SIGTERM (+ killOrphanClaudePid's own deferred SIGKILL
+  // follow-up) now, but classification waits until BOOT_ORPHAN_KILL_GRACE_MS
+  // later — reading the log while the orphan might still be writing to it
+  // could misclassify an about-to-succeed run as no_result and double-run the
+  // same PRD (2026-05-21 incident this guard exists for).
+  for (const slug of deferredSlugs) {
+    const j = bootSnap.jobs.find((x) => x.slug === slug);
+    const pid = j?.runtime?.pid;
+    const bootRunId = j?.runId ?? null; // captured now — guards against reconciling a DIFFERENT later run of the same slug
+    if (!pid) continue;
+    const result = killOrphanClaudePid(pid);
+    const killNote = ` (orphan pid=${pid}: ${result})`;
+    if (result === 'killed') {
+      console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${slug} — deferring finalize ${BOOT_ORPHAN_KILL_GRACE_MS}ms`);
+    }
+    setTimeout(() => {
+      const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
+      const outcome = logPath ? classifyRunOutcome(logPath) : 'unknown';
+      mutate((state) => {
+        const cur = state.jobs.find((x) => x.slug === slug);
+        // Race guard: bail if the job already resolved, OR if it's already been
+        // re-picked into a NEW run (different runId) within the grace window —
+        // that new run is not the boot orphan we SIGTERM'd and must not be
+        // touched by this stale classification.
+        if (!cur || cur.status !== 'running' || cur.runId !== bootRunId) return;
+        applyOrphanOutcome(cur, outcome, killNote);
+        console.log(`[scheduler] boot reconcile (deferred): slug=${slug} outcome=${outcome} → status=${cur.status}`);
+      }).catch((e) => console.error(`[scheduler] deferred boot reconcile failed for ${slug}:`, e?.message));
+    }, BOOT_ORPHAN_KILL_GRACE_MS).unref?.();
+  }
+
   // If we boot up while paused with a resumeAt in the past, clear it. This
   // happens when the app was closed across the reset window.
   const boot = await readQueue();
@@ -3074,6 +3199,16 @@ async function init() {
       utilization: cachedUtilization,
       consecutiveFailures,
     });
+
+    feedbackSweepTickCount++;
+    if (feedbackSweepDue(feedbackSweepTickCount, FEEDBACK_SWEEP_TICK_INTERVAL)) {
+      feedbackSweepTickCount = 0;
+      try {
+        sweepFeedback();
+      } catch (e) {
+        console.warn('[scheduler] feedback sweep failed', e?.message);
+      }
+    }
   }, 60_000);
   if (heartbeatInterval.unref) heartbeatInterval.unref();
 
@@ -3188,7 +3323,7 @@ const remote = {
   },
 
   // Exposes the module-level allocateParallelGroup (PRD 548) to callers that
-  // only hold the `remote` object (adminServer.cjs's create-prd route) —
+  // only hold the `remote` object (lib/prdCreate.cjs's create-prd route) —
   // reuses the same allocator the file-based /develop authoring path relies
   // on implicitly, rather than re-deriving NN here.
   allocateParallelGroup,
@@ -3216,4 +3351,36 @@ const remote = {
   },
 };
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, TRANSIENT_RETRY_CAP, buildScheduleStatePayload };
+// Registers the two job-management admin HTTP routes (PRD 689 — moved
+// verbatim out of the former standalone admin HTTP server module's
+// handleRequest, no behavior change) against an injected localAdminHttp.cjs
+// transport. `remoteObj` is accepted as a parameter (defaults to this
+// module's own `remote`) so the route logic stays testable in isolation
+// without booting Electron, matching that former module's original
+// dependency-injection pattern.
+function registerAdminRoutes(adminHttp, remoteObj = remote) {
+  adminHttp.registerRoute('GET', '/admin/scheduler/jobs', async (req, res) => {
+    const jobs = await remoteObj.listJobs();
+    sendJson(res, 200, jobs);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/reset-job', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    const slug = typeof parsed.slug === 'string' ? parsed.slug : null;
+    if (!slug) {
+      sendJson(res, 400, { ok: false, error: 'missing slug' });
+      return;
+    }
+    const result = await remoteObj.resetJob(slug);
+    sendJson(res, 200, result);
+  });
+}
+
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes };

package/src/main/sessionsStore.cjs

@@ -5,9 +5,9 @@
  * Storage: ~/.config/session-manager/tabs.json
  * Shape: { tabs: PersistedTab[], activeTabId: string | null, savedAt: number }
  *
- * Only serializable, durable fields are persisted: id, claudeSessionId,
- * chatSessionId, cwd, label, presetId. Runtime-only fields (pid, status,
- * startupCommand, exitCode) are recomputed on boot.
+ * Only serializable, durable fields are persisted: id, sessionId, cwd,
+ * label, presetId. Runtime-only fields (pid, status, startupCommand,
+ * exitCode) are recomputed on boot.
  */
 
 const fs = require('node:fs');
@@ -58,8 +58,7 @@ async function markFreshRestart() {
   const crypto = require('node:crypto');
   const freshTabs = tabs.map((t) => ({
     ...t,
-    claudeSessionId: crypto.randomUUID(),
-    chatSessionId: crypto.randomUUID(),
+    sessionId: crypto.randomUUID(),
   }));
   await save({ tabs: freshTabs, activeTabId, freshStart: true });
 }

package/src/main/templates/PRD_AUTHORING.md

@@ -328,7 +328,7 @@ loop but had no documented programmatic queueing path. This section is that path
 ### The `scheduler_create_prd` MCP tool
 
 Wraps `POST /admin/scheduler/create-prd` on the loopback admin API
-(`src/main/adminServer.cjs`, PRD 549) via `scripts/scheduler-mcp-server.cjs`, registered in this
+(`src/main/lib/localAdminHttp.cjs` + `src/main/lib/prdCreate.cjs`, PRD 549/688) via `scripts/scheduler-mcp-server.cjs`, registered in this
 repo's `.mcp.json` as the `session-manager-scheduler` MCP server. An external project wanting to
 call it from its own automation needs the equivalent MCP server registration pointing at this
 repo's `scripts/scheduler-mcp-server.cjs`, or can call the admin HTTP route directly (same
@@ -348,7 +348,7 @@ request/response shape) using the token at `~/.claude/session-manager/admin-api.
 | `slug` | string | no | kebab-case; derived from `title` if omitted |
 | `parallelGroup` | number | no | opt into an existing `NN` group instead of allocating a new one |
 
-**Return** (`{nn, filename, status}`, per `adminServer.cjs`):
+**Return** (`{nn, filename, status}`, per `prdCreate.cjs`'s registerAdminRoute):
 ```json
 { "nn": 550, "filename": "550-my-feature.md", "status": "queued" }
 ```
@@ -380,9 +380,9 @@ produces by hand.
 ### The app-must-be-running caveat (read this first)
 
 **`scheduler_create_prd` only works while the session-manager Electron app is running on this
-machine.** The admin server it depends on (`src/main/adminServer.cjs`) is hosted *inside* the
+machine.** The admin server it depends on (`src/main/lib/localAdminHttp.cjs`) is hosted *inside* the
 Electron process — it binds a loopback port and writes its token to
-`~/.claude/session-manager/admin-api.json` on app boot (see `CLAUDE.md`'s `adminServer.cjs`
+`~/.claude/session-manager/admin-api.json` on app boot (see `CLAUDE.md`'s `localAdminHttp.cjs`
 architecture entry) and stops existing the moment the app quits — it is not a standalone daemon.
 If the app is closed, `scheduler-mcp-server.cjs` cannot read a live port/token and every call
 returns the error `session-manager app is not running (admin API unreachable) — start it first`.

package/src/main/transcripts.cjs

@@ -38,100 +38,16 @@ function attachWindow(w) {
 }
 
 const { encodeCwd } = require('./lib/encodeCwd.cjs');
+const { classifyLine } = require('./lib/classifyTranscriptLine.cjs');
 
 function transcriptPath(cwd, sessionUuid) {
   return path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd), `${sessionUuid}.jsonl`);
 }
 
-const MAX_RAW_STR = 4096;
 // Cap bytes read per readDelta pass. Bounds memory on first attach to a very
 // large transcript (hundreds of MB) — see readDelta's seek-to-tail branch.
 const MAX_DELTA_BYTES = 8 * 1024 * 1024;
 
-// Block types whose text/content fields are parsed structurally by
-// orchestrator.ts / race.ts — truncating them produces mid-token "…" and
-// unparseable JSON, so they are exempt from the size cap.
-const EXEMPT_TYPES = new Set(['tool_result', 'tool_use']);
-
-/**
- * Cap string fields in a content block array so arbitrary tool output doesn't
- * bloat the ring buffer. Blocks whose type is in EXEMPT_TYPES are passed
- * through intact so that structured result payloads survive to the digest
- * parsers in race.ts / orchestrator.ts.
- */
-function trimContentArray(content) {
-  if (!Array.isArray(content)) return content;
-  return content.map((block) => {
-    if (!block || typeof block !== 'object') return block;
-    if (EXEMPT_TYPES.has(block.type)) return block;
-    const b = { ...block };
-    if (typeof b.text === 'string' && b.text.length > MAX_RAW_STR) {
-      b.text = b.text.slice(0, MAX_RAW_STR) + '…';
-    }
-    if (typeof b.content === 'string' && b.content.length > MAX_RAW_STR) {
-      b.content = b.content.slice(0, MAX_RAW_STR) + '…';
-    }
-    if (Array.isArray(b.content)) {
-      b.content = trimContentArray(b.content);
-    }
-    return b;
-  });
-}
-
-/** Build the slim raw projection used by race.ts and orchestrator.ts. */
-function makeRaw(obj) {
-  const msgContent = obj?.message?.content;
-  return { message: { content: trimContentArray(msgContent) } };
-}
-
-/**
- * Parse one JSONL line defensively. Real schema drifts, so we pass through
- * anything that parses and tag a coarse `kind`.
- */
-function classifyLine(obj) {
-  if (!obj || typeof obj !== 'object') return null;
-  // Many shapes exist — try several common fields.
-  const type = obj.type || obj.event || obj.role;
-  const msg = obj.message || obj;
-  const content = msg?.content;
-
-  // Usage rollups arrive as summary events.
-  if (obj.usage || msg?.usage) {
-    return { kind: 'usage', data: obj.usage || msg.usage, raw: makeRaw(obj) };
-  }
-
-  // Tool uses: scan content array for tool_use blocks.
-  if (Array.isArray(content)) {
-    for (const block of content) {
-      if (block?.type === 'tool_use') {
-        if (block.name === 'TodoWrite') {
-          return { kind: 'todo_write', data: block.input?.todos || block.input || [], raw: makeRaw(obj) };
-        }
-        if (block.name === 'ExitPlanMode' || block.name === 'EnterPlanMode') {
-          return { kind: 'plan', data: block.input, raw: makeRaw(obj) };
-        }
-        if (block.name === 'Agent' || block.name === 'Task') {
-          // Include block.id as toolUseId so the live store can match the
-          // corresponding tool_result and update per-agent lastActivityAt.
-          return { kind: 'agent_spawn', data: { ...block.input, toolUseId: block.id }, raw: makeRaw(obj) };
-        }
-        return {
-          kind: 'tool_use',
-          data: { name: block.name, input: block.input, id: block.id },
-          raw: makeRaw(obj),
-        };
-      }
-      // tool_result carries the tool_use_id of the completed Task/Agent call.
-      // The live store uses this to update the agent's lastActivityAt bookend.
-      if (block?.type === 'tool_result' && block.tool_use_id) {
-        return { kind: 'tool_result', data: { toolUseId: block.tool_use_id }, raw: makeRaw(obj) };
-      }
-    }
-  }
-
-  return { kind: type || 'message', data: obj, raw: makeRaw(obj) };
-}
-
 /**
  * Read new bytes from sub.filePath into sub.offset/pending/inode in place.
  * Resets offset+pending when the file inode changes (rename+replace rotation).

package/src/main/webRemote.cjs

@@ -729,13 +729,13 @@ async function pushSessionList() {
     if (_e2e.state !== 'authenticated') return;
     const sessionsStore = require('./sessionsStore.cjs');
     const data = await sessionsStore.load();
-    // Normalize persisted tabs → SessionMeta. tabId === claudeSessionId so it
+    // Normalize persisted tabs → SessionMeta. tabId === sessionId so it
     // matches the transcript JSONL name used by cmd:session:subscribe.
     const sessions = (data?.tabs ?? []).map((t) => ({
-      tabId: t.claudeSessionId,
+      tabId: t.sessionId,
       cwd: t.cwd,
       title: t.label || t.cwd,
-      state: _sessionWatchers.get(t.claudeSessionId)?.state ?? null,
+      state: _sessionWatchers.get(t.sessionId)?.state ?? null,
     }));
     const payload = { sessions, activeTabId: data?.activeTabId ?? null };
     const json = JSON.stringify(payload);

package/src/preload/api.d.ts

@@ -163,9 +163,7 @@ export interface SubscribeResult {
 
 export interface PersistedTab {
   id: string;
-  claudeSessionId: string;
-  /** Chat mode's own session id, decoupled from claudeSessionId. Optional for backwards-compat with tabs.json written before this field existed. */
-  chatSessionId?: string;
+  sessionId: string;
   cwd: string;
   label: string;
   presetId: string | null;
@@ -650,6 +648,7 @@ export interface FilesRenameResult { ok: boolean; newPath?: string; error: strin
 export interface FilesDeleteResult { ok: boolean; error: string | null }
 export interface FilesDuplicateResult { ok: boolean; path?: string; error?: string | null }
 export interface DocEditResult { ok: boolean; after?: string; error?: string }
+export interface DocEditSessionResult { tabId: string; requestId: string; ok: boolean; after?: string; error?: string }
 
 export interface SearchFileEntry {
   name: string;
@@ -1272,7 +1271,17 @@ export interface SessionManagerAPI {
     duplicate: (path: string) => Promise<FilesDuplicateResult>;
   };
   docEdit: {
-    run: (payload: { path: string; before: string; instruction: string }) => Promise<DocEditResult>;
+    run: (payload: { path: string; before: string; instruction: string; documentText?: string }) => Promise<DocEditResult>;
+    runInSession: (payload: {
+      tabId: string;
+      sessionId: string;
+      cwd: string;
+      before: string;
+      instruction: string;
+      documentText?: string;
+      requestId: string;
+    }) => Promise<{ ok: boolean }>;
+    onSessionResult: (handler: (payload: DocEditSessionResult) => void) => () => void;
   };
   /** Consolidated shell open/reveal. One method, discriminated on `as`, replaces
    *  the former app.openIn* / app.openExternal / files.openExternal / files.showInFinder.
@@ -1452,8 +1461,9 @@ export interface SessionManagerAPI {
   chat: {
     /** Spawn a headless `claude -p` run for a tab. Results arrive via the on* listeners. */
     run: (payload: ChatRunPayload) => Promise<{ ok: boolean }>;
-    /** Cancel the in-flight run for a tab (SIGTERM→SIGKILL). No-op when idle. */
-    cancel: (tabId: string) => void;
+    /** Cancel the in-flight run for a tab (SIGTERM→SIGKILL). Resolves once the
+     *  run has fully settled (terminal event fired). No-op when idle. */
+    cancel: (tabId: string) => Promise<void>;
     onQueued: (handler: (e: ChatRunQueuedEvent) => void) => () => void;
     onRunStarted: (handler: (e: ChatRunStartedEvent) => void) => () => void;
     onOutput: (handler: (e: ChatRunOutputEvent) => void) => () => void;

package/src/preload/index.cjs

@@ -229,6 +229,12 @@ contextBridge.exposeInMainWorld('api', {
   },
   docEdit: {
     run: (payload) => ipcRenderer.invoke('docedit:run', payload),
+    runInSession: (payload) => ipcRenderer.invoke('docedit:run-in-session', payload),
+    onSessionResult: (handler) => {
+      const listener = (_e, payload) => handler(payload);
+      ipcRenderer.on('docedit:session-result', listener);
+      return () => ipcRenderer.removeListener('docedit:session-result', listener);
+    },
   },
   // Consolidated shell open/reveal — see shell:open in index.cjs.
   // as: 'editor' | 'fileInEditor' | 'finder' | 'terminal' | 'external' | 'openPath' | 'revealPath'
@@ -387,8 +393,9 @@ contextBridge.exposeInMainWorld('api', {
   chat: {
     /** Spawn a headless claude -p job. Results arrive via the on* listeners. */
     run: (payload) => ipcRenderer.invoke('chat:run', payload),
-    /** Cancel an in-flight run for the given tabId. No-op if none running. */
-    cancel: (tabId) => ipcRenderer.send('chat:cancel', { tabId }),
+    /** Cancel an in-flight run for the given tabId. Resolves once the run has
+     *  fully settled (terminal event fired). No-op if none running. */
+    cancel: (tabId) => ipcRenderer.invoke('chat:cancel', { tabId }),
     onQueued: (handler) => {
       const listener = (_e, payload) => handler(payload);
       ipcRenderer.on('chat:run:queued', listener);