claude-code-session-manager 0.58.0 → 0.59.0

package/src/main/transcripts.cjs

@@ -50,20 +50,27 @@ const MAX_DELTA_BYTES = 8 * 1024 * 1024;
 /**
  * Read new bytes from sub.filePath into sub.offset/pending/inode in place.
  * Resets offset+pending when the file inode changes (rename+replace rotation).
- * Returns parsed line strings ready for JSON.parse.
+ * Returns `{ text, byteOffset, byteLength }` per complete line, so callers can
+ * build a classifyLine `ref` pointing at the exact bytes on disk without
+ * re-deriving offsets downstream. '\n' is always a single UTF-8 byte (0x0A
+ * never appears inside a multi-byte continuation sequence), so byte lengths
+ * computed from the already-decoded string segments are exact.
  */
 async function readDelta(sub) {
   const stat = await fsp.stat(sub.filePath).catch(() => null);
   if (!stat) return [];
-  // Inode changed → file was replaced underfoot; restart from the top.
+  // Inode changed → file was replaced underfoot; restart from the top. The
+  // line index is keyed to byte offsets in the OLD file, so it's invalid too.
   if (sub.inode !== undefined && stat.ino !== sub.inode) {
     sub.offset = 0;
     sub.pending = '';
+    sub.lineIndex.length = 0;
   }
   if (stat.size < sub.offset) {
-    // File was truncated/rotated — start over.
+    // File was truncated/rotated — start over, and the index goes with it.
     sub.offset = 0;
     sub.pending = '';
+    sub.lineIndex.length = 0;
   }
   if (stat.size === sub.offset) {
     sub.inode = stat.ino;
@@ -72,6 +79,9 @@ async function readDelta(sub) {
   let readFrom = sub.offset;
   let length = stat.size - readFrom;
   let skipped = false;
+  // Byte offset of the first char of `sub.pending` — it was already counted
+  // into sub.offset by the previous readDelta call, so back it out here.
+  let textStartOffset = readFrom - Buffer.byteLength(sub.pending, 'utf8');
   if (length > MAX_DELTA_BYTES) {
     // Huge unread span — typically a very large transcript (hundreds of MB) on
     // first attach. Materializing the whole thing into a Buffer + decoded string
@@ -85,6 +95,7 @@ async function readDelta(sub) {
     length = stat.size - readFrom;
     sub.pending = '';
     skipped = true;
+    textStartOffset = readFrom;
   }
   const fd = await fsp.open(sub.filePath, 'r');
   try {
@@ -93,10 +104,23 @@ async function readDelta(sub) {
     const text = sub.pending + buf.toString('utf8');
     const parts = text.split('\n');
     sub.pending = parts.pop() ?? '';
-    if (skipped) parts.shift(); // discard the partial line at the seek boundary
+    let cursor = textStartOffset;
+    if (skipped) {
+      // Discard the partial line at the seek boundary, but still advance the
+      // cursor past its bytes (+1 for the newline) so kept lines' offsets stay
+      // accurate.
+      const discarded = parts.shift() ?? '';
+      cursor += Buffer.byteLength(discarded, 'utf8') + 1;
+    }
+    const lines = [];
+    for (const part of parts) {
+      const byteLength = Buffer.byteLength(part, 'utf8');
+      if (part) lines.push({ text: part, byteOffset: cursor, byteLength });
+      cursor += byteLength + 1; // +1 for the newline separator
+    }
     sub.offset = stat.size;
     sub.inode = stat.ino;
-    return parts.filter(Boolean);
+    return lines;
   } finally {
     await fd.close();
   }
@@ -105,27 +129,130 @@ async function readDelta(sub) {
 async function doFlush(sub, { emit = true } = {}) {
   const lines = await readDelta(sub);
   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.
+    // This index (not the parsed events) is what's kept in memory long-term.
+    sub.lineIndex.push({ byteOffset: line.byteOffset, byteLength: line.byteLength });
     let obj;
     try {
-      obj = JSON.parse(line);
+      obj = JSON.parse(line.text);
     } catch {
       continue;
     }
-    const ev = classifyLine(obj);
-    if (!ev) continue;
-    // Ring buffer (cap at 500 entries to bound memory).
-    sub.buffer.push(ev);
-    if (sub.buffer.length > 500) sub.buffer.shift();
-    if (emit) sendIfAlive(window, `transcript:event:${sub.tabId}`, ev);
-    // Mirror to OTEL — no-op when disabled. We emit on the initial drain too
-    // so backfilled transcripts show up in the trace store.
-    otel.recordTranscriptEvent({
-      tabId: sub.tabId,
-      tabCwd: sub.cwd,
-      kind: ev.kind,
-      data: ev.data,
-      ts: Date.now(),
-    });
+    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);
+      // 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.
+      otel.recordTranscriptEvent({
+        tabId: sub.tabId,
+        tabCwd: sub.cwd,
+        kind: ev.kind,
+        data: ev.data,
+        ts: Date.now(),
+      });
+    }
+  }
+}
+
+/**
+ * Read events for JSONL lines [startLine, endLine] (inclusive, 0-based) from
+ * disk using the subscription's line-offset index — never the whole file.
+ * A single positional fd.read covers the byte span for the whole requested
+ * window; lines are then re-split and parsed from that buffer only. This is
+ * the only path a caller should use to fetch history beyond what has already
+ * streamed via transcript:event — it never touches OTEL (which fires exactly
+ * once per line, in doFlush, as new bytes are indexed) and never re-emits.
+ */
+async function readPage(sub, startLine, endLine) {
+  const total = sub.lineIndex.length;
+  const from = Math.max(0, Math.min(startLine, total - 1));
+  const to = Math.max(0, Math.min(endLine, total - 1));
+  if (total === 0 || from > to) return { events: [], totalLines: total };
+  const first = sub.lineIndex[from];
+  const last = sub.lineIndex[to];
+  const spanOffset = first.byteOffset;
+  const spanLength = last.byteOffset + last.byteLength - spanOffset;
+  const events = [];
+  if (spanLength <= 0) return { events, totalLines: total };
+  const fd = await fsp.open(sub.filePath, 'r');
+  try {
+    const buf = Buffer.alloc(spanLength);
+    await fd.read(buf, 0, spanLength, spanOffset);
+    for (let lineNo = from; lineNo <= to; lineNo++) {
+      const entry = sub.lineIndex[lineNo];
+      const relOffset = entry.byteOffset - spanOffset;
+      const text = buf.toString('utf8', relOffset, relOffset + entry.byteLength);
+      let obj;
+      try {
+        obj = JSON.parse(text);
+      } catch {
+        continue; // malformed line: index slot preserved, nothing to render
+      }
+      const ref = { filePath: sub.filePath, byteOffset: entry.byteOffset, byteLength: entry.byteLength };
+      for (const ev of classifyLine(obj, ref)) {
+        events.push({ ...ev, lineNumber: lineNo });
+      }
+    }
+  } finally {
+    await fd.close();
+  }
+  return { events, totalLines: total };
+}
+
+async function pageEvents(tabId, startLine, endLine) {
+  const sub = subs.get(tabId);
+  if (!sub) return { events: [], totalLines: 0 };
+  return readPage(sub, startLine, endLine);
+}
+
+// Defensive ceiling on a single-line ref read (transcript:readRef). The
+// largest real JSONL lines observed are multi-MB tool_results; 64 MB is far
+// beyond plausible for ONE line while still bounding a hostile/corrupt ref.
+const MAX_REF_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Read the exact bytes of ONE JSONL line via the classifier's byte reference
+ * ({ filePath, byteOffset, byteLength } — threaded per-event since PRD
+ * transcript-classifier-multi-emit). This is the renderer's expand-to-full-
+ * payload path: the ring-buffered event carries only a bounded preview, the
+ * full untruncated line lives on disk. Positional fd.read only — never the
+ * whole file (same OOM discipline as readDelta/readPage).
+ *
+ * filePath is renderer-supplied, so it is validated with config.cjs's
+ * realpath boundary check AND pinned to the transcripts root
+ * (~/.claude/projects/) — a ref can never read arbitrary home-dir files.
+ */
+async function readRef({ filePath, byteOffset, byteLength }) {
+  const { validatePath } = require('./config.cjs');
+  let real;
+  try {
+    real = validatePath(filePath);
+  } catch (e) {
+    return { ok: false, error: e?.message || 'invalid path' };
+  }
+  const transcriptsRoot = path.join(os.homedir(), '.claude', 'projects') + path.sep;
+  if (!real.startsWith(transcriptsRoot)) {
+    return { ok: false, error: 'ref outside transcripts root' };
+  }
+  if (byteLength > MAX_REF_BYTES) {
+    return { ok: false, error: 'ref byteLength exceeds cap' };
+  }
+  let fd;
+  try {
+    fd = await fsp.open(real, 'r');
+    const buf = Buffer.alloc(byteLength);
+    const { bytesRead } = await fd.read(buf, 0, byteLength, byteOffset);
+    return { ok: true, text: buf.toString('utf8', 0, bytesRead) };
+  } catch (e) {
+    return { ok: false, error: e?.message || 'read failed' };
+  } finally {
+    await fd?.close().catch(() => {});
   }
 }
 
@@ -227,15 +354,20 @@ async function subscribe({ tabId, cwd, sessionUuid }) {
     filePath,
     offset: 0,
     pending: '',
-    buffer: [],
+    // Line-offset index (byteOffset + byteLength per JSONL line) — this is
+    // what's kept in memory across the life of the subscription, not the
+    // parsed events themselves. See readPage() for how events are re-derived
+    // from it on demand.
+    lineIndex: [],
     watcher: null,
     flushing: null,
     dirty: false,
   };
   // If the file already exists, read current content as replay. Do not emit
-  // during this initial drain — the renderer drains sub.buffer via
-  // `transcript:buffer` after `transcript:subscribe` resolves. Emitting here
-  // would race the renderer's onEvent listener registration and drop events.
+  // during this initial drain — the renderer drains history via
+  // `transcript:buffer` (or `transcript:page`) after `transcript:subscribe`
+  // resolves. Emitting here would race the renderer's onEvent listener
+  // registration and drop events.
   if (fs.existsSync(filePath)) {
     await doFlush(sub, { emit: false });
   }
@@ -257,9 +389,21 @@ function unsubscribe(tabId) {
   release(tabId);
 }
 
-function getBuffer(tabId) {
+/**
+ * Full-history drain used by the `transcript:buffer` IPC (initial replay on
+ * subscribe / tab-switch resume). Pages the entire indexed range from disk —
+ * bounded by the index's byte offsets, never a whole-file read — rather than
+ * the old fixed 500-entry ring buffer, so scrolling to the top of a long
+ * session reaches the genuine first event instead of a truncated window.
+ * Large sessions should prefer transcript:page for a specific window; this
+ * stays for existing consumers (live.ts, chat.ts, terminalDigest.ts) that
+ * expect one full drain.
+ */
+async function getBuffer(tabId) {
   const sub = subs.get(tabId);
-  return sub ? sub.buffer.slice() : [];
+  if (!sub || sub.lineIndex.length === 0) return [];
+  const { events } = await readPage(sub, 0, sub.lineIndex.length - 1);
+  return events;
 }
 
 // Cap on the transcript file we'll fully re-read for a token-usage summary —
@@ -305,11 +449,13 @@ async function usageForOne(filePath) {
     } catch {
       continue;
     }
-    const ev = classifyLine(obj);
-    if (!ev || ev.kind !== 'usage') continue;
-    const u = ev.data || {};
-    inputTokens += u.input_tokens ?? u.inputTokens ?? 0;
-    outputTokens += u.output_tokens ?? u.outputTokens ?? 0;
+    const events = classifyLine(obj);
+    for (const ev of events) {
+      if (ev.kind !== 'usage') continue;
+      const u = ev.data || {};
+      inputTokens += u.input_tokens ?? u.inputTokens ?? 0;
+      outputTokens += u.output_tokens ?? u.outputTokens ?? 0;
+    }
   }
   const usage = { inputTokens, outputTokens };
   usageCache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, usage });
@@ -354,6 +500,8 @@ function registerTranscriptHandlers() {
   ipcMain.handle('transcript:buffer', v(s.transcriptTabId, ({ tabId }) => getBuffer(tabId)));
   ipcMain.handle('transcript:path', v(s.transcriptPath, ({ cwd, sessionUuid }) => transcriptPath(cwd, sessionUuid)));
   ipcMain.handle('transcript:usageFor', v(s.transcriptUsageFor, ({ cwd, sessionIds }) => usageFor(cwd, sessionIds)));
+  ipcMain.handle('transcript:page', v(s.transcriptPage, ({ tabId, startLine, endLine }) => pageEvents(tabId, startLine, endLine)));
+  ipcMain.handle('transcript:readRef', v(s.transcriptReadRef, (ref) => readRef(ref)));
 }
 
 module.exports = {
@@ -366,4 +514,15 @@ module.exports = {
   transcriptPath,
   classifyLine,
   usageFor,
+  pageEvents,
+  readRef,
+  // Exported for unit tests exercising the array-of-events flush path
+  // (doFlush) and the line-offset index it maintains — not part of the IPC
+  // surface.
+  subscribe,
+  getBuffer,
+  // Test-only accessor onto the raw Subscription object (its lineIndex in
+  // particular) — asserting a memory ceiling requires inspecting what's
+  // actually held, not just what a read API returns.
+  __getSubForTest: (tabId) => subs.get(tabId),
 };

package/src/main/webRemote.cjs

@@ -649,13 +649,14 @@ async function pollSessionWatcher(w) {
   for (const line of res.lines) {
     let obj;
     try { obj = JSON.parse(line); } catch { continue; }
-    const ev = require('./transcripts.cjs').classifyLine(obj);
-    if (!ev) continue;
-    const s = deriveState(ev, obj);
-    if (s) nextState = s;
-    if (ev.kind === 'assistant') {
-      const text = extractAssistantText(obj);
-      if (text) { newAssistantText = text; newMsgId = obj.uuid || obj.message?.id || `${w.tabId}:${res.size}`; }
+    const events = require('./transcripts.cjs').classifyLine(obj);
+    for (const ev of events) {
+      const s = deriveState(ev, obj);
+      if (s) nextState = s;
+      if (ev.kind === 'assistant') {
+        const text = extractAssistantText(obj);
+        if (text) { newAssistantText = text; newMsgId = obj.uuid || obj.message?.id || `${w.tabId}:${res.size}`; }
+      }
     }
   }
 

package/src/preload/api.d.ts

@@ -171,10 +171,20 @@ export type TranscriptEventKind =
   | 'message'
   | string;
 
+export interface TranscriptEventRef {
+  filePath: string;
+  byteOffset: number;
+  byteLength: number;
+}
+
 export interface TranscriptEvent {
   kind: TranscriptEventKind;
   data: unknown;
   raw: unknown;
+  /** Short, bounded human-scannable preview of `data` — never the source of truth. */
+  previewText: string;
+  /** Byte range of this event's source line on disk; null when classified with no file context. */
+  ref: TranscriptEventRef | null;
 }
 
 export interface SubscribeResult {
@@ -396,7 +406,6 @@ export interface ScheduleConfig {
   /** Minutes to wait after the 5h reset before firing pending jobs.
    *  Used by 'on-reset'. Ignored by 'when-available' and 'manual'. */
   offsetMinutes: number;
-  concurrencyCap: number;
   defaultCwd: string;
   /** Auto-fire policy. Default 'when-available'. */
   firePolicy: ScheduleFirePolicy;
@@ -547,14 +556,45 @@ export interface SchedulePollHealth {
   lastFailureKind: string | null;
 }
 
+/** One `pending` job held by an unsatisfied dependency, and which dep. */
+export interface ScheduleJobHold {
+  slug: string;
+  dep: string;
+  depStatus: string;
+}
+
+/** Outcome of the scheduler's last tick — why the batch was (or wasn't) fired.
+ *  Every field is computed by tickQueue; nothing here is derived in the UI. */
+export interface ScheduleLastTick {
+  fired: boolean;
+  reason: 'held' | 'slots-exhausted' | 'memory-deferred' | 'already-running' | 'drained' | 'paused' | string;
+  /** Human-readable one-liner for the binding constraint, when there is one. */
+  detail?: string;
+  deferredCount?: number;
+  runningCount?: number;
+  count?: number;
+  availableMb?: number;
+  threshold?: number;
+  holders?: { owner: string; at: string }[];
+  holds?: ScheduleJobHold[];
+  at: string;
+}
+
 export interface ScheduleEffectiveConcurrency {
+  /** Total slots in the machine-wide sessionSlots pool — the ONLY concurrency
+   *  limit. The scheduler no longer carries a private concurrencyCap. */
   cap: number;
-  /** 'env' when SM_SCHEDULER_MAX_CONCURRENCY pins the cap; 'config' when concurrencyCap governs. */
-  source: 'env' | 'config';
+  /** Slots free right now (pool total minus held, incl. chat runs). */
+  free: number;
+  /** 'env' when SM_SESSION_SLOTS pins the pool; 'pool' when the persisted
+   *  Home-tab value governs. */
+  source: 'env' | 'pool';
 }
 
 export interface ScheduleStateSnapshot {
   config: ScheduleConfig & { supervisor?: SupervisorConfig };
+  /** Why the last tick fired (or didn't). Null before the first tick. */
+  lastTick?: ScheduleLastTick | null;
   jobs: ScheduleJob[];
   scheduledFor: string | null;
   lastRunAt: string | null;
@@ -948,17 +988,28 @@ export type ProjectBriefUpdateResult =
   | { ok: true; brief: ProjectBrief }
   | { ok: false; error: string };
 
-// ────────────────────────────────────────────── Project Pages (PRD 929-932)
+// ────────────────────────────────────────────── Project Pages (PRD 929-932, 969, project-home-hosted-html-spec)
 export interface ProjectPagesOutput {
   home: string;
-  marketing: string;
-  feature: string;
-  architecture: string;
-  generatedAt: string;
+  /** Absent when `isDefault` is true — the shipped default only covers the home lens. */
+  marketing?: string;
+  /** Absent when `isDefault` is true — the shipped default only covers the home lens. */
+  feature?: string;
+  /** Absent when `isDefault` is true — the shipped default only covers the home lens. */
+  architecture?: string;
+  /** Absent for output generated before the 'brief' lens existed (PRD 969), or
+   *  when `isDefault` is true — a project must regenerate to pick it up. */
+  brief?: string;
+  /** null for the shipped default (never generated). */
+  generatedAt: string | null;
+  /** True when `home` is the build-time shipped default, not this project's own
+   *  generated output — the renderer must label provenance rather than infer it. */
+  isDefault: boolean;
 }
 
 export interface ProjectPagesGetResult {
-  /** null when no manifest/output files exist yet — the empty-state signal. */
+  /** Never null in practice — a project with no generated output still gets the
+   *  shipped default (isDefault: true). The type stays nullable defensively. */
   output: ProjectPagesOutput | null;
 }
 
@@ -1357,6 +1408,11 @@ export interface SessionManagerAPI {
     /** Permanently destroy the sub (genuine tab close). */
     closeTab: (tabId: string) => Promise<{ ok: boolean }>;
     buffer: (tabId: string) => Promise<TranscriptEvent[]>;
+    /** Paged read over the subscribed transcript's line-offset index — [startLine, endLine] inclusive, 0-based.
+     *  Reads only the requested byte range from disk; never materializes the whole file. */
+    page: (tabId: string, startLine: number, endLine: number) => Promise<{ events: (TranscriptEvent & { lineNumber: number })[]; totalLines: number }>;
+    /** Full untruncated single-line read via a classifier byte reference (expand-to-full path). */
+    readRef: (ref: TranscriptEventRef) => Promise<{ ok: boolean; text?: string; error?: string }>;
     pathFor: (cwd: string, sessionUuid: string) => Promise<string>;
     /** Batched token-usage totals, one map entry per requested sessionId. A
      *  session with no transcript file yet (or one over the main-process size
@@ -1752,6 +1808,16 @@ export interface PromptSessionsCreateEpicPayload {
     runId?: string;
     sourceTabId?: string;
   };
+  /** Full first-prompt body + its labeled sections (epicIntake.ts's
+   *  composeEpicIntake) — carried alongside goalText so the Epic's first
+   *  turn can render a structured AIM briefing card. */
+  openingPrompt?: string;
+  sections?: Array<{
+    kind: 'actor' | 'injection' | 'input' | 'mission' | 'goal' | 'reference';
+    label: string;
+    text: string;
+    source?: string;
+  }>;
 }
 
 export interface PromptSessionsCreateEpicResult {

package/src/preload/index.cjs

@@ -121,6 +121,9 @@ contextBridge.exposeInMainWorld('api', {
     unsubscribe: (tabId) => ipcRenderer.invoke('transcript:unsubscribe', { tabId }),
     closeTab: (tabId) => ipcRenderer.invoke('transcript:close', { tabId }),
     buffer: (tabId) => ipcRenderer.invoke('transcript:buffer', { tabId }),
+    page: (tabId, startLine, endLine) =>
+      ipcRenderer.invoke('transcript:page', { tabId, startLine, endLine }),
+    readRef: (ref) => ipcRenderer.invoke('transcript:readRef', ref),
     pathFor: (cwd, sessionUuid) =>
       ipcRenderer.invoke('transcript:path', { cwd, sessionUuid }),
     usageFor: (cwd, sessionIds) =>