claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/projectPages.cjs

@@ -5,7 +5,9 @@
  * display (PRD 932). Reads what the `project-home-builder` Epic's own
  * session writes directly with its Write tool
  * (`session-manager-operations/project-pages/output/*.html` + manifest.json)
- * — this module never writes anything, matching the corrected "not an
+ * — this module never writes any CONTENT (the one exception, watchOutput()'s
+ * `fs.mkdirSync` to ensure the output dir exists before attaching a watcher,
+ * creates an empty directory only), matching the corrected "not an
  * OWNERS namespace" storage/ownership note in
  * session-manager-operations/architecture/project-pages-pipeline.md and
  * session-manager-operations/project-pages/README.md. Structure mirrors
@@ -25,10 +27,34 @@
 const { ipcMain } = require('electron');
 const fs = require('node:fs');
 const path = require('node:path');
+const chokidar = require('chokidar');
 const config = require('./config.cjs');
+const { opsPath } = require('./lib/opsOwnership.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+
+let mainWindow = null;
+function attachWindow(window) {
+  mainWindow = window;
+}
 
 function outputDir(cwd) {
-  return path.join(cwd, 'session-manager-operations', 'project-pages', 'output');
+  return opsPath(cwd, 'project-pages', 'output');
+}
+
+/**
+ * Resolve `cwd`'s output dir, treating the opsOwnership "ephemeral cwd"
+ * throw (a tmpdir/linked-worktree project root — see opsOwnership.cjs's
+ * resolveProjectRoot) as "no output dir available" rather than letting it
+ * propagate. Both get() and the watcher below go through this so a builder
+ * Epic running in a worktree can never crash either path.
+ */
+function tryOutputDir(realCwd) {
+  try {
+    return { dir: outputDir(realCwd), ephemeral: false };
+  } catch (e) {
+    if (e.ephemeral) return { dir: null, ephemeral: true };
+    throw e;
+  }
 }
 
 // Shipped build-time asset (see PRD "project-home-hosted-html-spec"'s
@@ -59,13 +85,24 @@ function defaultOutput() {
 // the empty state for every pre-existing project. So brief.html is read
 // tolerantly — present, its text is returned; absent, the field is simply
 // omitted from the payload rather than failing the whole read.
+// Partial-output strategy (see this file's module doc + PRD
+// "project-home-generate-preflight-and-push"): the render route
+// (projectHomeAdminRoutes.cjs's doRender) writes every lens file
+// concurrently and writes manifest.json ONLY AFTER all of them have landed.
+// So manifest.json's existence is already an all-or-nothing commit signal —
+// gating get() on it (below) means a reader can never observe a lens file
+// that arrived without its siblings. No second partial-state representation
+// is needed; this file just relies on that write order.
 const REQUIRED_LENSES = ['home', 'marketing', 'feature', 'architecture'];
 const OPTIONAL_LENSES = ['brief'];
 const LENSES = [...REQUIRED_LENSES, ...OPTIONAL_LENSES];
 
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
-  const dir = outputDir(realCwd);
+  const { dir, ephemeral } = tryOutputDir(realCwd);
+  if (ephemeral) {
+    return { output: defaultOutput() };
+  }
   const manifestResult = await config.readJson(path.join(dir, 'manifest.json'));
   if (!manifestResult.exists || !manifestResult.data || manifestResult.parseError) {
     return { output: defaultOutput() };
@@ -99,14 +136,136 @@ async function get({ cwd }) {
   return { output };
 }
 
+// ─── Push channel (PRD "project-home-generate-preflight-and-push") ────────
+//
+// project-pages:get above is a one-shot pull, fetched once at mount by
+// ProjectHome.tsx. That leaves a finished (or stuck) builder Epic invisible
+// until the next manual refresh/app restart. This section adds a per-cwd
+// chokidar watcher on the output dir (the same debounced-write library
+// config.cjs already uses for its generic file watcher) that recomputes
+// get() and pushes it to the renderer whenever the dir changes.
+//
+// Map<realCwd, { watcher, refCount }> — refcounted like config.cjs's own
+// watchers Map so more than one mounted component watching the same cwd
+// doesn't spawn a second chokidar instance, and doesn't get torn down by
+// the first component's unmount while a second is still watching.
+const outputWatchers = new Map();
+
+/**
+ * Watch `cwd`'s output dir. Resolves `{ ok: true }` once watching is actually
+ * live (or already watching), or `{ ok: false, reason: 'ephemeral' |
+ * 'invalid-cwd' }` when there is nothing safe to watch — callers must not
+ * treat that as an error, just as "no live updates for this cwd" (e.g. a
+ * worktree cwd). Async: waits for chokidar's own 'ready' before resolving so
+ * a write landing immediately after the call is never missed in the window
+ * before the underlying fs watch handle is actually registered.
+ */
+async function watchOutput(cwd) {
+  let realCwd;
+  try {
+    realCwd = config.validatePath(cwd);
+  } catch {
+    return { ok: false, reason: 'invalid-cwd' };
+  }
+
+  const existing = outputWatchers.get(realCwd);
+  if (existing) {
+    existing.refCount += 1;
+    return { ok: true };
+  }
+
+  const { dir, ephemeral } = tryOutputDir(realCwd);
+  if (ephemeral) {
+    return { ok: false, reason: 'ephemeral' };
+  }
+  // Ensure the (possibly not-yet-generated) output dir exists before
+  // chokidar attaches: watching a path 3 levels deep that doesn't exist yet
+  // does not reliably pick up files later written into it (verified — the
+  // watcher silently misses the first write without this). This creates an
+  // EMPTY directory only, no content, so it does not conflict with this
+  // module's read-only contract or the single-writer law (opsOwnership.cjs)
+  // — it bypasses config.cjs's writer-tracked write path deliberately,
+  // exactly like a project-home-builder Epic's own untracked Write-tool
+  // calls into this same folder (see opsOwnership.cjs's 'project-pages'
+  // entry).
+  fs.mkdirSync(dir, { recursive: true });
+
+  const push = async () => {
+    let result;
+    try {
+      result = await get({ cwd: realCwd });
+    } catch {
+      return; // best-effort; the renderer keeps its last-known output
+    }
+    sendIfAlive(mainWindow, 'project-pages:changed', { cwd: realCwd, output: result.output });
+  };
+
+  const watcher = chokidar.watch(dir, {
+    ignoreInitial: true,
+    persistent: true,
+    // manifest.json is the LAST file doRender writes (see REQUIRED_LENSES's
+    // comment above) — but the burst of per-lens writes leading up to it
+    // still fires several fs events in quick succession. awaitWriteFinish
+    // (same 50ms/25ms shape config.cjs's generic watcher uses) collapses
+    // that burst into one push instead of flapping the UI once per file.
+    awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
+  });
+  watcher.on('add', push);
+  watcher.on('change', push);
+  watcher.on('unlink', push);
+  watcher.on('error', (err) => {
+    console.warn('[projectPages] watcher error for', dir, err?.message);
+  });
+
+  outputWatchers.set(realCwd, { watcher, refCount: 1 });
+  await new Promise((resolve) => watcher.once('ready', resolve));
+  return { ok: true };
+}
+
+/** Decrement `cwd`'s watch refcount; closes the underlying watcher at 0. */
+function unwatchOutput(cwd) {
+  let realCwd;
+  try {
+    realCwd = config.validatePath(cwd);
+  } catch {
+    return;
+  }
+  const entry = outputWatchers.get(realCwd);
+  if (!entry) return;
+  entry.refCount -= 1;
+  if (entry.refCount <= 0) {
+    entry.watcher.close().catch(() => {});
+    outputWatchers.delete(realCwd);
+  }
+}
+
+/** Window close / app quit teardown — mirrors config.cjs's closeAllWatchers. */
+function closeAllOutputWatchers() {
+  for (const { watcher } of outputWatchers.values()) {
+    watcher.close().catch(() => {});
+  }
+  outputWatchers.clear();
+}
+
 function registerProjectPagesIpc() {
   const { schemas: s, validated: v } = require('./ipcSchemas.cjs');
   ipcMain.handle('project-pages:get', v(s.projectPagesCwd, get));
+  ipcMain.handle('project-pages:watch', v(s.projectPagesCwd, ({ cwd }) => watchOutput(cwd)));
+  ipcMain.handle('project-pages:unwatch', v(s.projectPagesCwd, ({ cwd }) => {
+    unwatchOutput(cwd);
+    return { ok: true };
+  }));
 }
 
 module.exports = {
+  attachWindow,
   registerProjectPagesIpc,
   get,
+  watchOutput,
+  unwatchOutput,
+  closeAllOutputWatchers,
   DEFAULT_HOME_PATH,
   readDefaultHomeHtml,
+  // Test-only introspection of the refcounted watcher map.
+  _outputWatchers: outputWatchers,
 };

package/src/main/pty.cjs

@@ -156,6 +156,11 @@ class PtyManager {
       // back to its originating Epic and minted an unrelated sibling one
       // instead (prdCreate.cjs's resolveSourcePromptIdFromClaudeSession).
       SM_CHAT_SESSION_ID: tabId,
+      // The real project cwd (never the worktree spawnCwd resolved below) —
+      // forwarded by scheduler-mcp-server.cjs as originProjectRoot so
+      // create-prd/open-session/readiness resolve the right project even
+      // from a worktree pwd. See projectRootResolve.cjs.
+      SM_PROJECT_ROOT: cwd,
     });
 
     const shell = process.env.SHELL || '/bin/bash';

package/src/main/queueOps.cjs

@@ -128,7 +128,7 @@ const INTERACTIVE_AC_PATTERNS = [
 ];
 
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
-const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
+const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs } = require('./lib/prdLocations.cjs');
 
 // PRD 808: PRDS_DIR is now the LEGACY global dir — kept as a migration
 // source and search fallback for not-yet-migrated files. Live PRDs resolve
@@ -139,9 +139,16 @@ function candidatePrdsDirs() {
   return [PRDS_DIR, ...resolvePrdsDirs()];
 }
 
-/** Search every candidate PRD dir for `<slug>.md`; returns the containing dir or null. */
-async function findPrdDir(slug) {
-  for (const dir of candidatePrdsDirs()) {
+/**
+ * Search every candidate PRD dir for `<slug>.md`; returns the containing dir
+ * or null. `cwd`, if given, narrows the search to that one project's own PRD
+ * dirs (its flat prds/ dir plus its Epic-scoped dirs) instead of scanning
+ * every project machine-wide — same narrowing pattern scheduler.cjs's
+ * getPrdParsed uses.
+ */
+async function findPrdDir(slug, cwd) {
+  const dirs = cwd ? [resolvePrdWriteDir(cwd), ...listEpicPrdDirs(cwd)] : candidatePrdsDirs();
+  for (const dir of dirs) {
     try {
       await fsp.access(path.join(dir, `${slug}.md`));
       return dir;
@@ -311,9 +318,9 @@ function archiveDirForSource(srcDir, ts) {
   return path.join(path.dirname(srcDir), 'prds-archived', ts);
 }
 
-async function archiveOne(slug, ts) {
+async function archiveOne(slug, ts, cwd) {
   if (!SLUG_RE.test(slug)) return { ok: false, slug, error: 'invalid slug' };
-  const srcDir = await findPrdDir(slug);
+  const srcDir = await findPrdDir(slug, cwd);
   if (!srcDir) return { ok: false, slug, error: 'not found in any PRDs dir' };
   const src = path.resolve(path.join(srcDir, `${slug}.md`));
   if (!src.startsWith(srcDir + path.sep)) return { ok: false, slug, error: 'path escape (src)' };
@@ -342,7 +349,7 @@ async function archiveOne(slug, ts) {
  */
 let retireCompletedSlugsFn = async () => {};
 
-async function archiveMany(slugs) {
+async function archiveMany(slugs, cwd) {
   if (!Array.isArray(slugs) || slugs.length === 0) {
     return { ok: true, archived: 0, archivedTo: null, results: [] };
   }
@@ -353,7 +360,7 @@ async function archiveMany(slugs) {
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   const results = [];
   for (const slug of slugs) {
-    results.push(await archiveOne(slug, ts));
+    results.push(await archiveOne(slug, ts, cwd));
   }
   const archived = results.filter((r) => r.ok).length;
   const archivedSlugs = results.filter((r) => r.ok).map((r) => r.slug);

package/src/main/runVerify.cjs

@@ -13,7 +13,8 @@
  *   verifyRun({ runDir, prdPath, queueEntry, allJobs }) → Promise<Verdict>
  *
  * Verdict shape:
- *   { verdict: 'clean'|'halt'|'deps_unmet'|'transcript_errors'|'verify_unavailable',
+ *   { verdict: 'clean'|'halt'|'deps_unmet'|'transcript_errors'|'verify_unavailable'
+ *       |'no_verdict_sentinel'|'abandoned_background_task',
  *     reason: string,
  *     downgradeTo: 'pending'|'needs_review'|null }
  *
@@ -23,6 +24,8 @@
  *   deps_unmet      → 'pending'   (re-fires when deps clear)
  *   transcript_errors → 'needs_review' (requires human flip)
  *   verify_unavailable → 'needs_review'
+ *   no_verdict_sentinel → 'needs_review'
+ *   abandoned_background_task → 'needs_review'
  *
  * Time complexity: O(N·L) where N = log line count, L = avg content line count.
  * The log is read once with readFileSync (700 KB typical; well within Node.js
@@ -231,6 +234,28 @@ function parseLog(logPath) {
   return { events, resultEvent, error: null, transcriptCommitLanded };
 }
 
+// Stable, narrow substrings of the harness's auto-background tool_result text
+// (Bash: "Command did not complete within its 120s timeout and was moved to
+// the background... You will be notified when it completes."). Anchored on
+// short distinctive fragments rather than the whole sentence so harness
+// wording drift degrades to the generic no_verdict_sentinel verdict instead
+// of throwing.
+const BACKGROUND_TASK_MARKERS = ['moved to the background', 'You will be notified when it completes'];
+
+/**
+ * True when any tool_result in the transcript carries the harness's
+ * auto-background marker text — i.e. a Bash command was auto-backgrounded
+ * after its foreground timeout and the run ended waiting for a notification
+ * a headless run structurally cannot receive.
+ */
+function hasAbandonedBackgroundTask(events) {
+  for (const ev of events) {
+    if (ev.kind !== 'tool_result' || !ev.content) continue;
+    if (BACKGROUND_TASK_MARKERS.some((marker) => ev.content.includes(marker))) return true;
+  }
+  return false;
+}
+
 // ─── self-recovery helpers ────────────────────────────────────────────────────
 
 /**
@@ -905,15 +930,30 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
       : undefined;
 
     // No pattern hits is not automatically "clean": a run that neither
-    // 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.
+    // committed anything nor ever emitted the finish-protocol sentinel did not
+    // finish for SOME reason. When the transcript shows the harness's
+    // auto-background marker, that reason is knowable and cheap to recover
+    // from: the run backgrounded a long Bash command past its foreground
+    // timeout and ended waiting for a "you will be notified" callback a
+    // headless run can never receive — it did not necessarily fail to do the
+    // work, it failed to come back and commit it. That gets its own verdict
+    // (abandoned_background_task) so the auto-fix investigation checks the
+    // working tree for already-written work first, instead of re-planning the
+    // whole PRD from a wrong "stopped on a clarifying question" premise.
     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)',
-        priority: 1,
-      });
+      if (hasAbandonedBackgroundTask(events)) {
+        issues.push({
+          verdict: 'abandoned_background_task',
+          reason: 'run made no commit and emitted no SCHEDULER_VERDICT sentinel, and the transcript shows a Bash command auto-backgrounded past its foreground timeout — the run likely ended waiting for a background-task notification a headless run cannot receive, not because the work failed; the work is probably already written and just needs to be committed',
+          priority: 1,
+        });
+      } else {
+        issues.push({
+          verdict: 'no_verdict_sentinel',
+          reason: 'run made no commit and emitted no SCHEDULER_VERDICT sentinel — the run ended before the finish protocol for some reason (stopped on a clarifying question, crashed, ran out of turns, or another cause not identifiable from this transcript alone)',
+          priority: 1,
+        });
+      }
     }
 
     // A truthful-looking PASS sentinel with no commit is still not "clean":
@@ -1122,4 +1162,5 @@ module.exports = {
   allDeliverablesAlreadyTracked,
   isAncestorCommit,
   isGitRepo,
+  hasAbandonedBackgroundTask,
 };

package/src/main/scheduler/prdParser.cjs

@@ -19,6 +19,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { splitFrontmatter } = require('../lib/prdFrontmatter.cjs');
 const { deriveEpicIdFromPrdPath } = require('../lib/prdLocations.cjs');
+const { reportDanglingAgentTypeOnce } = require('../lib/prdAgentType.cjs');
 
 /**
  * Expand a PRD `cwd` value to an absolute path.
@@ -57,12 +58,19 @@ async function parsePrdRaw(filePath) {
     const m = base.match(/^(\d+)-/);
     return m ? Number(m[1]) : null;
   })();
+  const cwd = expandCwd(fm.cwd || null);
+
+  // Read-time tolerance for the agentType FK (throw on write, report on
+  // read — prdAgentType.cjs's header): a persona renamed/deleted after this
+  // PRD was written must not stop the PRD from loading. Best-effort only —
+  // never lets a logging failure affect parsing.
+  if (fm.agentType && cwd) reportDanglingAgentTypeOnce(cwd, fm.agentType);
 
   return {
     slug: base,
     path: filePath,
     title: fm.title || base,
-    cwd: expandCwd(fm.cwd || null),
+    cwd,
     estimateMinutes: fm.estimateMinutes ? Number(fm.estimateMinutes) || null : null,
     parallelGroup: (fm.parallelGroup ? Number(fm.parallelGroup) || null : null) ?? groupFromName ?? 99,
     // Optional traceability back to the PromptTicket.id (PRD 748) that was
@@ -99,6 +107,15 @@ async function parsePrdRaw(filePath) {
     // quarantines it instead of queuing it to run.
     createdVia: fm.createdVia || null,
     issuedAt: fm.issuedAt || null,
+    // WHO executes this PRD (persona name) — distinct from `tag` (work
+    // type). Absent on every PRD authored before this field existed; the
+    // dependent follow-up PRD (scheduler-launch-as-persona) resolves this
+    // into a launch decision, which this module does not do.
+    agentType: fm.agentType || null,
+    // Opt-in exclusive-lease flag (PRD 1107, quietMachineLease.cjs +
+    // schedulerBatch.cjs's pickNextBatch). Only a literal `true` opts in —
+    // matches prdFrontmatter.cjs's applyKey semantics for this field.
+    quietMachine: fm.quietMachine === 'true',
     body: body.trim(),
   };
 }