claude-code-session-manager 0.76.0 → 0.77.0

package/src/main/lib/schedulerBatch.cjs

@@ -14,10 +14,40 @@
 
 const path = require('node:path');
 const os = require('node:os');
-const { projectJobCap } = require('./schedulerConfig.cjs');
+const { projectJobCap, quietMachineWaitMs } = require('./schedulerConfig.cjs');
 
 const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
 
+/**
+ * The dep slug (if any) blocking `job` from running, per PRD 832's
+ * dependsOn semantics — a dep is blocking while a queue row for it exists
+ * in a non-completed state; a slug with no row is treated as already done
+ * (completed rows are retired to history shards). Resolves a dep by exact
+ * slug first, then by bare-name match (a human-authored `dependsOn:` can't
+ * know the `NN-` prefix the allocator will hand a sibling PRD — see
+ * pickForProject's own comment on this for the incident it fixes).
+ * Shared by pickForProject (per-project gating) and pickNextBatch's
+ * quiet-machine dispatch check (PRD 1107), so the two can never disagree
+ * about whether a job is eligible.
+ */
+function findBlockingDep(job, projectJobs) {
+  const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
+  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);
+  }
+  const rowsForDep = (slug) => {
+    const exact = rowBySlug.get(slug);
+    if (exact) return [exact];
+    return rowsByBareSlug.get(String(slug ?? '').replace(/^\d+-/, '')) ?? [];
+  };
+  return (job.dependsOn ?? []).find((slug) => (
+    rowsForDep(slug).some((dep) => dep.status !== 'completed')
+  ));
+}
+
 /**
  * Per-project batch picker. `dependsOn` is the ONLY ordering primitive.
  *
@@ -52,7 +82,7 @@ const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager
  *   project this tick, plus (when batch is empty because a gate held it) the
  *   human-readable reason text that would otherwise only reach console.log.
  */
-function pickForProject(projectJobs, runningSlugsInProject, slots) {
+function pickForProject(projectJobs, runningSlugsInProject, slots, heldSlugs = new Map()) {
   const projectCwd = (projectJobs.find((j) => j.cwd) || {}).cwd || DEFAULT_PROJECT_CWD;
 
   // Explicit dependsOn eligibility (PRD 832). A dep slug is BLOCKING while a
@@ -63,7 +93,6 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   // Legacy jobs without dependsOn keep the shared-NN group semantics below
   // 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]));
   // 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
@@ -72,29 +101,37 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   // 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). */
+  // though the framework PRD they build on had not landed). findBlockingDep
+  // resolves a dep by exact slug first, then falls back to matching rows
+  // whose slug is that dep with a leading `NN-` stripped.
+  const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
   const rowsForDep = (slug) => {
     const exact = rowBySlug.get(slug);
     if (exact) return [exact];
-    return rowsByBareSlug.get(String(slug ?? '').replace(/^\d+-/, '')) ?? [];
+    const bare = String(slug ?? '').replace(/^\d+-/, '');
+    return projectJobs.filter((j) => String(j.slug ?? '').replace(/^\d+-/, '') === bare);
   };
-  const blockingDep = (j) => (j.dependsOn ?? []).find((slug) => (
-    rowsForDep(slug).some((dep) => dep.status !== 'completed')
-  ));
+  const blockingDep = (j) => findBlockingDep(j, projectJobs);
 
+  // quietMachine jobs (PRD 1107) never dispatch through the ordinary
+  // per-project picker — pickNextBatch's dedicated quiet-machine check
+  // (evaluated before this function is ever called) is the only path that
+  // can fire one, since dispatching one is a whole-tick, all-projects
+  // exclusive decision this per-project function can't see.
+  // Launch-gate holds (lib/launchFailure.cjs, issue #11): a pending row
+  // whose launch persona is circuit-broken is NOT a candidate this tick and
+  // must not shadow a pickable sibling behind it. It still gets a per-row
+  // hold record so the Queue UI says why it is waiting.
+  const launchHolds = [];
+  for (const j of projectJobs) {
+    if (j.status === 'pending' && !runningSlugsInProject.has(j.slug) && heldSlugs.has(j.slug)) {
+      launchHolds.push({ slug: j.slug, dep: null, depStatus: null, reason: heldSlugs.get(j.slug) || 'launch blocked' });
+    }
+  }
   const allPending = projectJobs.filter(
-    (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
+    (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug) && j.quietMachine !== true && !heldSlugs.has(j.slug),
   );
-  if (allPending.length === 0) return { batch: [], reason: null, holds: [] };
+  if (allPending.length === 0) return { batch: [], reason: null, holds: launchHolds };
 
   const pending = [];
   const heldByFailedDep = [];
@@ -106,7 +143,7 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   const heldBySkippedDep = [];
   // Per-job hold records, surfaced to the UI so a `pending` row can say WHICH
   // dep is holding it instead of leaving the reason in console.log.
-  const holds = [];
+  const holds = [...launchHolds];
   for (const j of allPending) {
     const dep = blockingDep(j);
     if (!dep) { pending.push(j); continue; }
@@ -247,13 +284,46 @@ function enqueueTimestamp(job) {
  *   have the running count subtracted from it again. The scheduler no longer
  *   keeps a private concurrency cap of its own: per sessionSlots.cjs's own
  *   charter, caps belong to Session-Manager's one pool, not to each consumer.
+ * @param {object} [quietOpts] - PRD 1107 quiet-machine state, all pure inputs
+ *   so this function stays unit-testable without electron/sessionSlots:
+ *   - leaseHeld: true while a quiet-machine job is currently running
+ *     (quietMachineLease.cjs's isHeld()) — holds ALL dispatch, every project,
+ *     until it releases.
+ *   - machineInUse: sessionSlots.inUse() — jobs running machine-wide RIGHT
+ *     NOW (scheduler jobs AND chat runs). A quiet-machine job only dispatches
+ *     when this is 0, unless it has waited past quietMachineWaitMs().
+ *   - now: ms epoch, defaults to Date.now() (injectable for tests).
  * @returns {{ batch: object[], reason: string | null, holds: object[] }} Jobs
  *   to spawn this tick, plus (when batch is empty because a gate held it) the
  *   human-readable hold reason that would otherwise only reach console.log.
  */
-function pickNextBatch(allJobs, running, freeSlots) {
-  if (!allJobs.some((j) => j.status === 'pending' && !running.has(j.slug))) {
-    return { batch: [], reason: null, holds: [] };
+function pickNextBatch(allJobs, running, freeSlots, quietOpts = {}) {
+  const { leaseHeld = false, machineInUse = 0, now = Date.now() } = quietOpts;
+  // slug → hold reason for rows the launch circuit breaker is holding back
+  // this tick (scheduler.cjs computes it from state.launchBlocks). Held rows
+  // are invisible to every pick below but still surface as holds.
+  const heldSlugs = quietOpts.heldSlugs instanceof Map ? quietOpts.heldSlugs : new Map();
+  const pickable = (j) => j.status === 'pending' && !running.has(j.slug) && !heldSlugs.has(j.slug);
+
+  // Exclusive lease (PRD 1107): while a quiet-machine job is running, it
+  // holds the WHOLE pool — no other job, in any project, dispatches until it
+  // releases. Checked first, ahead of even the "anything pending?" early
+  // return, so the reason is always attributable to the lease rather than a
+  // generic drain.
+  if (leaseHeld) {
+    const reason = '[scheduler] quiet-machine: lease held by a running job — holding all dispatch until it releases';
+    console.log(reason);
+    return { batch: [], reason, holds: [] };
+  }
+
+  if (!allJobs.some(pickable)) {
+    const holds = [];
+    for (const j of allJobs) {
+      if (j.status === 'pending' && !running.has(j.slug) && heldSlugs.has(j.slug)) {
+        holds.push({ slug: j.slug, dep: null, depStatus: null, reason: heldSlugs.get(j.slug) || 'launch blocked' });
+      }
+    }
+    return { batch: [], reason: null, holds };
   }
 
   // Orphan correction: a queue.json row still marked `running` that this
@@ -279,14 +349,38 @@ function pickNextBatch(allJobs, running, freeSlots) {
     projectMap.get(key).push(job);
   }
 
+  // Quiet-machine dispatch (PRD 1107) — evaluated BEFORE the ordinary
+  // per-project round-robin, and as an ALL-OR-NOTHING decision for this
+  // tick: a quiet-machine job either fires alone (nothing else in this
+  // batch), or it doesn't fire and the ordinary round-robin runs unaffected.
+  // This is what makes "while it runs no other job is dispatched" true —
+  // ordinary jobs are simply never offered a slot in the SAME tick a quiet
+  // job dispatches.
+  if (slots > 0) {
+    const quietWaitMs = quietMachineWaitMs();
+    const quietPending = allJobs.filter((j) => pickable(j) && j.quietMachine === true);
+    for (const job of quietPending) {
+      const projectJobs = projectMap.get(job.cwd || DEFAULT_PROJECT_CWD) || [job];
+      if (findBlockingDep(job, projectJobs)) continue; // blocked — try the next quiet candidate
+      const machineQuiet = machineInUse === 0;
+      const waitedMs = now - enqueueTimestamp(job);
+      const degraded = !machineQuiet && waitedMs >= quietWaitMs;
+      if (!machineQuiet && !degraded) continue; // still waiting for a quiet machine
+      const reason = machineQuiet
+        ? `[scheduler] quiet-machine: dispatching ${job.slug} exclusively (machine idle)`
+        : `[scheduler] quiet-machine: dispatching ${job.slug} DEGRADED — waited ${Math.round(waitedMs / 60_000)}m ` +
+          `> ${Math.round(quietWaitMs / 60_000)}m without the machine going quiet`;
+      console.log(reason);
+      return { batch: [{ ...job, quietLeaseDegraded: degraded }], reason: null, holds: [] };
+    }
+  }
+
   // Per-project candidates (only projects with pending work), each carrying
   // a per-tick VIEW of its rows that this loop mutates as it picks, so
   // pickForProject's running count and cap stay accurate across passes.
   const candidates = [];
   for (const [cwd, projectJobs] of projectMap) {
-    const hasPending = projectJobs.some(
-      (j) => j.status === 'pending' && !running.has(j.slug),
-    );
+    const hasPending = projectJobs.some(pickable);
     if (!hasPending) continue;
     const view = projectJobs.map((j) => ({ ...j }));
     const runningSlugsInProject = new Set(
@@ -294,7 +388,7 @@ function pickNextBatch(allJobs, running, freeSlots) {
     );
     const runningCount = projectJobs.filter((j) => j.status === 'running').length;
     const oldestPendingMs = projectJobs
-      .filter((j) => j.status === 'pending' && !running.has(j.slug))
+      .filter(pickable)
       .reduce((min, j) => Math.min(min, enqueueTimestamp(j)), Infinity);
     candidates.push({ cwd, view, runningSlugsInProject, runningCount, oldestPendingMs, active: true });
   }
@@ -314,7 +408,7 @@ function pickNextBatch(allJobs, running, freeSlots) {
     for (const c of candidates) {
       if (slots <= 0) break;
       if (!c.active) continue;
-      const result = pickForProject(c.view, c.runningSlugsInProject, 1);
+      const result = pickForProject(c.view, c.runningSlugsInProject, 1, heldSlugs);
       for (const h of result.holds ?? []) if (!holdsBySlug.has(h.slug)) holdsBySlug.set(h.slug, h);
       if (result.batch.length === 0) {
         if (heldReason === null && result.reason) heldReason = result.reason;
@@ -334,6 +428,14 @@ function pickNextBatch(allJobs, running, freeSlots) {
     }
     if (addedThisPass === 0) break;
   }
+  // A project whose only pending rows are launch-held never becomes a
+  // candidate above, so its hold records would be lost — surface them here
+  // so the Queue UI still says why those rows are waiting.
+  for (const j of allJobs) {
+    if (j.status === 'pending' && !running.has(j.slug) && heldSlugs.has(j.slug) && !holdsBySlug.has(j.slug)) {
+      holdsBySlug.set(j.slug, { slug: j.slug, dep: null, depStatus: null, reason: heldSlugs.get(j.slug) || 'launch blocked' });
+    }
+  }
   const holds = [...holdsBySlug.values()];
   return { batch, reason: batch.length === 0 ? heldReason : null, holds };
 }
@@ -387,4 +489,6 @@ function findStarvedProjects(jobs, now, thresholdMs) {
   return out;
 }
 
-module.exports = { pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, DEFAULT_PROJECT_CWD };
+module.exports = {
+  pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, DEFAULT_PROJECT_CWD,
+};

package/src/main/lib/schedulerConfig.cjs

@@ -129,8 +129,27 @@ module.exports = {
   // SM_LOAD_GATE_PER_CORE (float, clamped to [0.25, 4]; 0 disables).
   LOAD_GATE_PER_CORE: 0.85,
   loadGateThreshold,
+
+  // A `quietMachine: true` PRD (PRD 1107 — see quietMachineLease.cjs +
+  // schedulerBatch.cjs's pickNextBatch) waits for zero other jobs to be
+  // running machine-wide before it dispatches, so its own timing-sensitive
+  // acceptance criteria (frame time, performance fences) aren't measured
+  // under CPU contention. A queue's worth of ordinary jobs must never wedge
+  // behind one waiting forever: past this many ms of waiting it dispatches
+  // anyway, stamped `quietLeaseDegraded: true`. Override with
+  // SM_QUIET_MACHINE_WAIT_MINUTES (integer minutes, clamped to [1, 1440]).
+  DEFAULT_QUIET_MACHINE_WAIT_MS: 30 * 60_000,
+  quietMachineWaitMs,
 };
 
+function quietMachineWaitMs() {
+  const raw = process.env.SM_QUIET_MACHINE_WAIT_MINUTES;
+  if (raw === undefined || raw === '') return module.exports.DEFAULT_QUIET_MACHINE_WAIT_MS;
+  const parsed = parseInt(raw, 10);
+  if (!Number.isFinite(parsed)) return module.exports.DEFAULT_QUIET_MACHINE_WAIT_MS;
+  return Math.min(1440, Math.max(1, parsed)) * 60_000;
+}
+
 function loadGateThreshold() {
   const raw = process.env.SM_LOAD_GATE_PER_CORE;
   if (raw === undefined || raw === '') return module.exports.LOAD_GATE_PER_CORE;

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,13 +27,36 @@
 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 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
 // default-document requirement) — a fixed app-relative path with no
 // user-controlled segment, so it deliberately does NOT go through
@@ -60,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() };
@@ -100,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/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(),
   };
 }