claude-code-session-manager 0.41.0 → 0.42.0

package/src/main/lib/opsOwnership.cjs

@@ -26,6 +26,7 @@
  *   - config.cjs writeTextAtomic / writeBinaryAtomic / writeJson / writeJsonSync
  *   - lib/epicMint.cjs      (raw fs tmp+rename)
  *   - lib/queueStore.cjs    (raw fs tmp+rename)
+ *   - lib/opsErrorLog.cjs   (raw fs append, JSONL error log)
  * Renderer callers declare their writer id through the IPC payload.
  */
 
@@ -51,6 +52,8 @@ const OWNERS = Object.freeze({
   'feedback': 'feedback',
   // Browser tab scratch saves (DOM captures, screenshots, recorded flows).
   'browser': 'browser',
+  // Structured per-tab error log lines (JSONL), tagged for tracing/analysis.
+  'logs': 'logs',
 });
 
 /**

package/src/main/lib/prdCreate.cjs

@@ -23,6 +23,8 @@ const { kebabCase } = require('./kebabCase.cjs');
 const config = require('../config.cjs');
 const { expandHome } = require('./expandHome.cjs');
 const { readBody, sendJson } = require('./localAdminHttp.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
 
 const STANDARDS_PATH = path.join(
   __dirname, '..', '..', '..',
@@ -90,6 +92,29 @@ function buildPrdBody(input) {
   return `${fmLines.join('\n')}${bodyLines.join('\n')}`;
 }
 
+/**
+ * Best-effort fallback for a PRD queued via the scheduler_create_prd MCP tool
+ * from inside an Epic's own headless chat session, when the model's tool
+ * call omitted `sourcePromptId` — the exact gap that let PRDs 866/867 mint
+ * two unrelated sibling Epics instead of joining the Epic that was actually
+ * driving the conversation (2026-08-01). `claudeSessionId` is this process's
+ * `originClaudeSessionId` input (chatRunner.cjs's SM_CHAT_SESSION_ID env var,
+ * inherited down to the MCP server child); looked up against `cwd`'s
+ * active-index.json for the Epic whose own claudeSessionId matches (domain
+ * model: Epic:claude-session is 1:1). Returns null for a non-Epic tab (plain
+ * SessionTab chat) or when the id is stale/unknown — never throws, since this
+ * is strictly a convenience default and a miss must fall back to minting a
+ * normal Epic exactly like today.
+ */
+function resolveSourcePromptIdFromClaudeSession(cwd, claudeSessionId) {
+  if (!claudeSessionId) return null;
+  const { sessions } = readActiveIndex(cwd);
+  for (const session of Object.values(sessions)) {
+    if (session && session.claudeSessionId === claudeSessionId) return session.id;
+  }
+  return null;
+}
+
 /**
  * Core create-PRD orchestration: cwd validation, slug derivation, NN
  * allocation, existing-file collision check, body build, write. Shared by
@@ -130,6 +155,11 @@ async function createPrd(input, remote) {
   config.addAllowedRoot(realCwd);
   input = { ...input, cwd };
 
+  if (!input.sourcePromptId && input.originClaudeSessionId) {
+    const resolved = resolveSourcePromptIdFromClaudeSession(cwd, input.originClaudeSessionId);
+    if (resolved) input = { ...input, sourcePromptId: resolved };
+  }
+
   const slug = input.slug || deriveSlugFromTitle(input.title);
   if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
     return { ok: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
@@ -163,6 +193,17 @@ async function createPrd(input, remote) {
     return { ok: false, status: 500, error: writeResult?.error ?? 'write failed' };
   }
 
+  // Trace-back point for "who/what created this PRD" (auditLog.cjs) — every
+  // PRD write, whether from the admin/MCP route or the renderer's chat:create-prd
+  // IPC handler, lands one record here regardless of outcome path above.
+  appendAuditEvent('prd_create', {
+    cwd: input.cwd,
+    slug: filenameSlug,
+    title: input.title,
+    sourcePromptId: input.sourcePromptId ?? null,
+    sourceTabId: input.sourceTabId ?? null,
+  });
+
   return { ok: true, nn, filename: `${filenameSlug}.md` };
 }
 
@@ -209,6 +250,7 @@ module.exports = {
   readStandards,
   deriveSlugFromTitle,
   buildPrdBody,
+  resolveSourcePromptIdFromClaudeSession,
   createPrd,
   registerAdminRoute,
 };

package/src/main/lib/schedulerBatch.cjs

@@ -49,10 +49,32 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   // unchanged (lowest-number-first waves), so an in-flight mixed queue keeps
   // its order without migration.
   const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
-  const blockingDep = (j) => (j.dependsOn ?? []).find((slug) => {
-    const dep = rowBySlug.get(slug);
-    return dep && dep.status !== 'completed';
-  });
+  // A PRD's filename slug carries the auto-allocated `NN-` prefix
+  // (prdCreate.cjs builds `${nn}-${slug}`), but a human/agent authoring
+  // `dependsOn:` writes the BARE name it chose — it cannot know the number
+  // the allocator will hand out. Without this, every such dep resolved to
+  // undefined and was silently treated as "already done", turning the whole
+  // dependency gate into a no-op (observed live 2026-08-01: 22 PRDs listing
+  // `leftnav-two-face-framework` while the real row was
+  // `873-leftnav-two-face-framework`, all of them eligible immediately even
+  // though the framework PRD they build on had not landed). Resolve a dep by
+  // exact slug first, then fall back to matching rows whose slug is that dep
+  // with a leading `NN-` stripped.
+  const rowsByBareSlug = new Map();
+  for (const j of projectJobs) {
+    const bare = String(j.slug ?? '').replace(/^\d+-/, '');
+    if (!rowsByBareSlug.has(bare)) rowsByBareSlug.set(bare, []);
+    rowsByBareSlug.get(bare).push(j);
+  }
+  /** Every queue row a dep string refers to (exact match, else bare-name match). */
+  const rowsForDep = (slug) => {
+    const exact = rowBySlug.get(slug);
+    if (exact) return [exact];
+    return rowsByBareSlug.get(String(slug ?? '').replace(/^\d+-/, '')) ?? [];
+  };
+  const blockingDep = (j) => (j.dependsOn ?? []).find((slug) => (
+    rowsForDep(slug).some((dep) => dep.status !== 'completed')
+  ));
 
   const allPending = projectJobs.filter(
     (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
@@ -64,7 +86,7 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   for (const j of allPending) {
     const dep = blockingDep(j);
     if (!dep) { pending.push(j); continue; }
-    if (rowBySlug.get(dep)?.status === 'failed') heldByFailedDep.push({ job: j, dep });
+    if (rowsForDep(dep).some((d) => d.status === 'failed')) heldByFailedDep.push({ job: j, dep });
     // running/pending/needs_review dep — simply not eligible this tick.
   }
   if (pending.length === 0) {

package/src/main/logs.cjs

@@ -1,6 +1,7 @@
 const { app, ipcMain } = require('electron');
 const fs = require('node:fs');
 const path = require('node:path');
+const opsErrorLog = require('./lib/opsErrorLog.cjs');
 
 // Rolling daily files under <userData>/logs/. Anything mtime'd older than
 // RETENTION_MS is pruned at boot; we never compact mid-session, since the
@@ -75,7 +76,24 @@ function writeLine(payload) {
 }
 
 function registerLogHandlers() {
-  ipcMain.on('log:write', (_e, payload) => writeLine(payload));
+  ipcMain.on('log:write', (_e, payload) => {
+    writeLine(payload);
+    // Renderer errors that name which project/tab they belong to also land
+    // in that project's own session-manager-operations/logs/ — the
+    // machine-global file above mixes every project together and isn't
+    // taggable, so it's not a substitute for the per-project trace.
+    if (payload && payload.level === 'error' && payload.cwd) {
+      opsErrorLog.appendError({
+        cwd: payload.cwd,
+        scope: payload.scope,
+        tabId: payload.tabId,
+        epicId: payload.epicId,
+        tags: Array.isArray(payload.tags) ? payload.tags : [],
+        message: payload.message,
+        meta: payload.meta,
+      });
+    }
+  });
   ipcMain.handle('log:dir', () => logDir());
 }
 

package/src/main/pty.cjs

@@ -20,6 +20,7 @@ const { addAllowedRoot } = require('./config.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { checkInsideHome } = require('./lib/insideHome.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+const opsErrorLog = require('./lib/opsErrorLog.cjs');
 
 // Absolute path to the installed package root (src/main/ -> ../../), shown in
 // the remediation message so the user can cd there and rebuild.
@@ -146,6 +147,14 @@ class PtyManager {
       FORCE_COLOR: '1',
       // Tag the session so hook server / transcript tail can correlate.
       SESSION_MANAGER_TAB_ID: tabId,
+      // Tab ID = claudeSessionId by design (see CLAUDE.md domain model), and
+      // for an Epic, Terminal/Chat are two views over the SAME session — so
+      // this is exactly the id chatRunner.cjs sets for headless chat runs.
+      // Without it, a PRD queued via scheduler_create_prd from an
+      // interactive Epic terminal (not headless chat) had no way to resolve
+      // back to its originating Epic and minted an unrelated sibling one
+      // instead (prdCreate.cjs's resolveSourcePromptIdFromClaudeSession).
+      SM_CHAT_SESSION_ID: tabId,
     });
 
     const shell = process.env.SHELL || '/bin/bash';
@@ -162,6 +171,13 @@ class PtyManager {
       });
     } catch (err) {
       console.error('[pty] pty.spawn threw:', err);
+      opsErrorLog.appendError({
+        cwd,
+        scope: 'pty',
+        tabId,
+        tags: ['spawn-failed'],
+        message: `pty.spawn threw: ${err?.message ?? String(err)}`,
+      });
       // Surface the cause in the tab + report a clean exit rather than throwing
       // an opaque IPC error (covers a missing/invalid cwd or a native fault).
       sendIfAlive(this.window, `pty:data:${tabId}`, nativeModuleHelp(`pty.spawn failed: ${err?.message ?? String(err)}`));
@@ -196,6 +212,13 @@ class PtyManager {
       // real interactive shell (which prints a prompt immediately) is exempt.
       if (!gotData && exitCode !== 0 && Date.now() - spawnedAt < 1200) {
         sendIfAlive(this.window, `pty:data:${tabId}`, nativeModuleHelp(`The shell exited immediately (code ${exitCode}).`));
+        opsErrorLog.appendError({
+          cwd,
+          scope: 'pty',
+          tabId,
+          tags: ['immediate-exit'],
+          message: `shell exited immediately (code ${exitCode}, signal ${signal ?? 'none'}) after ${Date.now() - spawnedAt}ms with no output`,
+        });
       }
       sendIfAlive(this.window, `pty:exit:${tabId}`, { exitCode, signal });
       this.sessions.delete(tabId);

package/src/main/scheduler.cjs

@@ -1071,6 +1071,11 @@ function reconcileSourcePromptId(job, parsedSourcePromptId) {
  * Status is preserved: pending stays pending, completed stays completed.
  * Newly-discovered PRDs land as `pending`.
  */
+// Epic ids already warned about (PRD-bearing but absent from
+// active-index.json). Module-scoped so the warning is one line per Epic per
+// process rather than one per 60s reconcile tick.
+const warnedUnregisteredEpics = new Set();
+
 async function reconcile(state) {
   // Defence in depth — tickQueue already gates on this, but reconcile is the
   // function that would do the damage (every unmatched PRD .md becomes a
@@ -1163,8 +1168,54 @@ async function reconcile(state) {
   // for them (that row already exists, durably, in history.jsonl).
   const historyArchiveCandidates = [];
 
+  // Cache active-index.json reads per cwd across this reconcile pass — many
+  // unmatched PRDs typically share a project, and readActiveIndex is a
+  // synchronous fs.readFileSync.
+  const epicStatusCache = new Map(); // cwd -> { sessions }
+  function epicStatus(cwd, epicId) {
+    if (!cwd || !epicId) return null;
+    let idx = epicStatusCache.get(cwd);
+    if (!idx) {
+      idx = readActiveIndex(cwd);
+      epicStatusCache.set(cwd, idx);
+    }
+    return idx.sessions[epicId]?.status ?? null;
+  }
+
   for (const [slug, p] of onDisk) {
     if (seen.has(slug)) continue;
+    // Security gate: a PRD's file location IS its Epic membership
+    // (prdLocations.deriveEpicIdFromPrdPath / p.epicId). Before this check,
+    // the scheduler queued ANY .md file it found under an Epic's prds/ dir
+    // regardless of that Epic's status or even whether it was ever properly
+    // minted — so a PRD filed under a 'proposed' Epic (agent-proposed,
+    // awaiting human Approve & start via EpicApprovalBar), or one dropped
+    // straight onto disk under a directory that was never registered via
+    // ensureEpic()/active-index.json at all (bypassing the app entirely),
+    // would still execute as a claude -p job with --dangerously-skip-permissions.
+    // Block ONLY an explicit 'proposed' — the actual human gate. The human's
+    // Approve action flips status to 'active' (state/promptSessions.ts) and
+    // the very next reconcile pass picks the PRD up with no other change.
+    //
+    // This deliberately does NOT require a positive 'active' registration.
+    // That stricter form shipped briefly and caused a 6-hour silent outage
+    // (2026-08-01): 23 real PRDs whose Epic dir existed on disk but had no
+    // active-index.json entry were skipped forever with no log line, so the
+    // scheduler looked simply dead. Absence of an entry is not evidence of a
+    // rogue writer — an Epic archived on completion also leaves active-index,
+    // and other paths can create the dir without registering it. Fail-closed
+    // is right for the approval gate; it is wrong as a blanket requirement,
+    // because the failure mode is invisible and unrecoverable by the user.
+    const ownerStatus = epicStatus(p.cwd, p.epicId);
+    if (p.epicId && ownerStatus === 'proposed') {
+      continue;
+    }
+    // Unregistered Epic dir: allowed, but never silently — this is the only
+    // signal that a PRD's Epic is missing from the index it should be in.
+    if (p.epicId && ownerStatus === null && !warnedUnregisteredEpics.has(p.epicId)) {
+      warnedUnregisteredEpics.add(p.epicId);
+      console.warn(`[scheduler] epic ${p.epicId} (${p.cwd}) has PRDs on disk but no active-index.json entry — queuing anyway; register or archive it to silence this`);
+    }
     const hist = historyBySlug.get(slug);
     if (hist) {
       if (hist.status === 'completed') {

package/src/preload/api.d.ts

@@ -1283,7 +1283,13 @@ export interface SessionManagerAPI {
     status: () => Promise<McpStatusResult>;
   };
   logs: {
-    write: (scope: string, level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: unknown) => void;
+    write: (
+      scope: string,
+      level: 'debug' | 'info' | 'warn' | 'error',
+      message: string,
+      meta?: unknown,
+      ctx?: { cwd?: string; tabId?: string; epicId?: string; tags?: string[] },
+    ) => void;
     dir: () => Promise<string>;
   };
   config: {

package/src/preload/index.cjs

@@ -146,8 +146,11 @@ contextBridge.exposeInMainWorld('api', {
     status: () => ipcRenderer.invoke('mcp:status'),
   },
   logs: {
-    write: (scope, level, message, meta) =>
-      ipcRenderer.send('log:write', { scope, level, message, meta }),
+    // ctx is optional: { cwd, tabId, epicId, tags } — when present and
+    // level is 'error', main also appends a tagged line to that project's
+    // own session-manager-operations/logs/ (see opsErrorLog.cjs).
+    write: (scope, level, message, meta, ctx) =>
+      ipcRenderer.send('log:write', { scope, level, message, meta, ...ctx }),
     dir: () => ipcRenderer.invoke('log:dir'),
   },
   config: {