claude-code-session-manager 0.58.0 → 0.60.0

package/src/main/lib/schedulerBatch.cjs

@@ -18,15 +18,29 @@ const os = require('node:os');
 const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
 
 /**
- * Per-project batch picker. Applies group-ordering rules scoped to a single
- * project (all jobs sharing one cwd).
+ * Per-project batch picker. `dependsOn` is the ONLY ordering primitive.
  *
- * Rules (same as original global pickNextBatch, but scoped):
- *   1. Find the lowest parallelGroup with pending jobs not already running.
- *   2. Failure gate: if an earlier group has failed jobs, hold this project.
- *   3. If that group has jobs in flight (backfill), fire more from SAME group.
- *   4. If a lower-numbered group arrives late (late-arrival), fire it now.
- *   5. If no group is in flight, start the lowest pending group fresh.
+ * Rules:
+ *   1. Eligible = pending, not already running, and no blocking dependency.
+ *   2. A dep is blocking while a queue row for it exists non-completed; a
+ *      FAILED dep holds its dependents with an explicit reason. Transitive
+ *      holds fall out of this for free (a held job stays `pending`, which is
+ *      itself a blocking state for anything depending on IT).
+ *   3. Everything eligible fires, up to `slots`, ordered by parallelGroup
+ *      ascending as a PRIORITY HINT only — never as a barrier.
+ *
+ * `parallelGroup` used to be a WAVE number and this function used to fire at
+ * most one wave per tick, holding every higher wave while a lower one was in
+ * flight. PRD 832 made the number strictly UNIQUE per PRD and moved ordering
+ * to `dependsOn` — `prdCreate.cjs` now warns that an explicit parallelGroup is
+ * "deprecated and ignored" — but this picker was never updated to match. With
+ * unique numbers every wave is a singleton, so the batch was always exactly
+ * ONE job, and because numbers are allocated monotonically upward, each newly
+ * queued PRD always sorted ABOVE the in-flight one and was held behind it.
+ * Measured effect: max concurrency 1 across 25 recorded runs, against a
+ * 5-slot pool. The group logic is gone; the real limits are the machine-wide
+ * `sessionSlots` pool and the memory gate, both enforced by the caller in
+ * scheduler.cjs's tickQueue.
  *
  * @param {object[]} projectJobs - All jobs for this project (all statuses).
  * @param {Set<string>} runningSlugsInProject - Slugs from the global
@@ -79,14 +93,24 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   const allPending = projectJobs.filter(
     (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
   );
-  if (allPending.length === 0) return { batch: [], reason: null };
+  if (allPending.length === 0) return { batch: [], reason: null, holds: [] };
 
   const pending = [];
   const heldByFailedDep = [];
+  // 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 = [];
   for (const j of allPending) {
     const dep = blockingDep(j);
     if (!dep) { pending.push(j); continue; }
-    if (rowsForDep(dep).some((d) => d.status === 'failed')) heldByFailedDep.push({ job: j, dep });
+    const depRows = rowsForDep(dep);
+    const failed = depRows.some((d) => d.status === 'failed');
+    if (failed) heldByFailedDep.push({ job: j, dep });
+    holds.push({
+      slug: j.slug,
+      dep,
+      depStatus: depRows.find((d) => d.status !== 'completed')?.status ?? 'unknown',
+    });
     // running/pending/needs_review dep — simply not eligible this tick.
   }
   if (pending.length === 0) {
@@ -94,136 +118,69 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
       const detail = heldByFailedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
       const reason = `[scheduler] depends-gate [${projectCwd}]: holding ${heldByFailedDep.length} job(s) behind failed dependencies [${detail}]. Reset or archive the dep to unblock.`;
       console.log(reason);
-      return { batch: [], reason };
+      return { batch: [], reason, holds };
     }
-    return { batch: [], reason: null };
+    return { batch: [], reason: null, holds };
   }
 
-  // Lowest pending group (computed up-front for the failure-gate check).
-  const lowestPendingGroup = pending.reduce(
-    (min, j) => Math.min(min, j.parallelGroup ?? 99),
-    Infinity,
-  );
-
-  // Cross-group failure gate: refuse to advance past a group with failed jobs.
-  // A failed foundation PRD should not allow later groups to run and
-  // silently corrupt project state. needs_review is NOT a blocker.
-  const blockingFailures = projectJobs.filter(
-    (j) => j.status === 'failed' && (j.parallelGroup ?? 99) < lowestPendingGroup,
-  );
-  if (blockingFailures.length > 0) {
-    const slugs = blockingFailures.map((j) => j.slug).join(', ');
-    const reason = `[scheduler] failure-gate [${projectCwd}]: holding g${lowestPendingGroup} — ` +
-      `${blockingFailures.length} failed job(s) in earlier groups [${slugs}]. ` +
-      `Reset to pending or archive to unblock.`;
-    console.log(reason);
-    return { batch: [], reason };
-  }
-
-  // Groups with at least one job in flight: either tracked in runningSlugsInProject
-  // (this process spawned it) or still marked 'running' in queue.json
-  // (persisted from a previous session that hasn't been orphan-reset yet).
-  const jobBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
-  const activeGroups = new Set();
-  for (const slug of runningSlugsInProject) {
-    const job = jobBySlug.get(slug);
-    if (job) activeGroups.add(job.parallelGroup ?? 99);
-  }
-  for (const j of projectJobs) {
-    if (j.status === 'running' && !runningSlugsInProject.has(j.slug)) {
-      activeGroups.add(j.parallelGroup ?? 99);
-    }
-  }
-
-  if (activeGroups.size > 0) {
-    const lowestActive = Math.min(...activeGroups);
-    if (lowestPendingGroup > lowestActive) {
-      // Earlier group still running — wait for it to drain before advancing.
-      const reason = `[scheduler] concurrency [${projectCwd}]: g${lowestActive} in flight, holding g${lowestPendingGroup}`;
-      console.log(reason);
-      return { batch: [], reason };
-    }
-    if (lowestPendingGroup < lowestActive) {
-      // Late-arrival: a lower-numbered (higher-priority) PRD reconciled AFTER
-      // a higher-numbered group was already picked. Fire it now in parallel
-      // with the active group rather than starving it until drain.
-      if (slots <= 0) {
-        const reason = `[scheduler] concurrency [${projectCwd}]: no slots for late-arrival g${lowestPendingGroup}`;
-        console.log(reason);
-        return { batch: [], reason };
-      }
-      const batch = pending
-        .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
-        .slice(0, slots);
-      console.log(
-        `[scheduler] concurrency [${projectCwd}]: firing late-arrival g${lowestPendingGroup} ` +
-        `(${batch.length} job(s)) alongside active g${lowestActive}`,
-      );
-      return { batch, reason: null };
-    }
-    // Backfill slots remaining in the current group.
-    if (slots <= 0) {
-      const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
-      console.log(reason);
-      return { batch: [], reason };
-    }
-    const batch = pending
-      .filter((j) => (j.parallelGroup ?? 99) === lowestActive)
-      .slice(0, slots);
-    if (batch.length > 0) {
-      console.log(
-        `[scheduler] concurrency [${projectCwd}]: backfilling ${batch.length} into g${lowestActive}`,
-      );
-    }
-    return { batch, reason: null };
-  }
-
-  // No active group — start the next group fresh.
   if (slots <= 0) {
-    const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
+    const reason = `[scheduler] concurrency [${projectCwd}]: no slots free, holding ${pending.length} eligible job(s)`;
     console.log(reason);
-    return { batch: [], reason };
+    return { batch: [], reason, holds };
   }
+
+  // parallelGroup is a PRIORITY HINT, not a barrier: when there are more
+  // eligible jobs than slots, the lower (earlier-authored) PRD numbers go
+  // first. Everything else about the number is display-only.
   const batch = pending
-    .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
+    .slice()
+    .sort((a, b) => (a.parallelGroup ?? 99) - (b.parallelGroup ?? 99))
     .slice(0, slots);
   console.log(
-    `[scheduler] concurrency [${projectCwd}]: starting g${lowestPendingGroup} with ${batch.length} job(s)`,
+    `[scheduler] concurrency [${projectCwd}]: firing ${batch.length} of ${pending.length} ` +
+    `eligible job(s) [${batch.map((j) => j.slug).join(', ')}]`,
   );
-  return { batch, reason: null };
+  return { batch, reason: null, holds };
 }
 
 /**
  * Pick the next batch of jobs to spawn this tick.
  *
- * Group-ordering gates are evaluated PER PROJECT (keyed by cwd), so jobs in
- * different projects are not serialized by each other's groups. Within a
- * single project, the existing sequential-group semantics are fully preserved.
+ * Dependency gates are evaluated PER PROJECT (keyed by cwd), so jobs in
+ * different projects never serialize each other.
  *
  * O(N) where N = allJobs.length.
  *
  * @param {object[]} allJobs - Full queue.json job list.
  * @param {Set<string>} running - In-process running slugs (runningSet).
- * @param {number} cap - concurrencyCap.
+ * @param {number} freeSlots - Slots free RIGHT NOW in the machine-wide
+ *   `sessionSlots` pool (`sessionSlots.available()`). This is already
+ *   net of every held slot — scheduler jobs AND chat runs — so it must not
+ *   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.
  * @returns {{ batch: object[], reason: string | null }} 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, cap) {
+function pickNextBatch(allJobs, running, freeSlots) {
   if (!allJobs.some((j) => j.status === 'pending' && !running.has(j.slug))) {
-    return { batch: [], reason: null };
+    return { batch: [], reason: null, holds: [] };
   }
 
-  // Global slot accounting: take the higher of in-process running count and
-  // queue.json running count (handles orphaned running entries from a previous
-  // session not yet reaped).
+  // Orphan correction: a queue.json row still marked `running` that this
+  // process did NOT spawn holds no pool slot (it is a leftover from a crashed
+  // prior session, pending boot reconciliation). The pool cannot see it, so
+  // discount it here rather than starting a job into a slot a soon-to-be-
+  // reaped process may still be occupying.
   const queueRunningCount = allJobs.filter((j) => j.status === 'running').length;
-  const effectiveRunning = Math.max(running.size, queueRunningCount);
-  let slots = cap - effectiveRunning;
+  const untrackedRunning = Math.max(0, queueRunningCount - running.size);
+  let slots = freeSlots - untrackedRunning;
   if (slots <= 0) {
-    const reason = `[scheduler] concurrency: cap ${cap} reached (${effectiveRunning} running), no slots`;
+    const reason = `[scheduler] concurrency: no session slots free ` +
+      `(${freeSlots} free in pool, ${untrackedRunning} untracked running row(s))`;
     console.log(reason);
-    return { batch: [], reason };
+    return { batch: [], reason, holds: [] };
   }
 
   // Group all jobs by project cwd.
@@ -259,15 +216,17 @@ function pickNextBatch(allJobs, running, cap) {
   // Aggregate batch across projects, consuming global slots as we go. Track
   // the first hold reason seen so callers can explain an empty overall batch.
   const batch = [];
+  const holds = [];
   let heldReason = null;
   for (const { projectJobs, runningSlugsInProject } of projectCandidates) {
     if (slots <= 0) break;
     const projectResult = pickForProject(projectJobs, runningSlugsInProject, slots);
     batch.push(...projectResult.batch);
+    holds.push(...(projectResult.holds ?? []));
     slots -= projectResult.batch.length;
     if (heldReason === null && projectResult.reason) heldReason = projectResult.reason;
   }
-  return { batch, reason: batch.length === 0 ? heldReason : null };
+  return { batch, reason: batch.length === 0 ? heldReason : null, holds };
 }
 
 module.exports = { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD };

package/src/main/lib/schedulerConfig.cjs

@@ -17,7 +17,6 @@ module.exports = {
   HTTP_TIMEOUT_MS: 30_000,
   HTTP_RETRY_DELAY_MS: 1_000,
   OFFSET_MINUTES_MAX: 180,
-  CONCURRENCY_CAP_MAX: 20,
   MAX_JOB_DURATION_MS: 4 * 60 * 60_000,
   SUPERVISOR_INTERVAL_MS: 15 * 60_000,
   SUPERVISOR_PROBE_STALE_MS: 10 * 60_000,

package/src/main/otel.cjs

@@ -1,7 +1,9 @@
 /**
  * otel — mirrors transcripts.cjs classified events as OpenTelemetry spans.
  *
- * Spans are 0-duration "events": one span per classified transcript line,
+ * Spans are 0-duration "events": one span per classified transcript EVENT
+ * (a single JSONL line can classify to several events — e.g. a usage rollup
+ * alongside real content, or several tool calls in one assistant turn),
  * named `transcript.<kind>`, with structural attributes only. Tool inputs,
  * plan text, and agent prompts are excluded unless `includeContent` is on
  * (matches upstream OTEL_LOG_USER_PROMPTS opt-in).

package/src/main/projectPages.cjs

@@ -11,9 +11,19 @@
  * session-manager-operations/project-pages/README.md. Structure mirrors
  * projectBrief.cjs's `get()`: validatePath first, config.cjs read helpers,
  * one ipcMain.handle registered from index.cjs's registerXHandlers() pattern.
+ *
+ * Shipped default (PRD "project-home-hosted-html-spec"): when a project has
+ * never generated its own output, `get()` no longer returns the bare
+ * `{ output: null }` empty-state signal — it falls back to a build-time
+ * default `home.html` shipped with the app (`templates/`), returned with
+ * `isDefault: true` and `generatedAt: null` so the renderer can label
+ * provenance. That default is read from a fixed app-relative path, never
+ * written into any project's own `session-manager-operations/` tree — this
+ * module stays read-only.
  */
 
 const { ipcMain } = require('electron');
+const fs = require('node:fs');
 const path = require('node:path');
 const config = require('./config.cjs');
 
@@ -21,38 +31,72 @@ function outputDir(cwd) {
   return path.join(cwd, 'session-manager-operations', 'project-pages', 'output');
 }
 
-const LENSES = ['home', 'marketing', 'feature', 'architecture'];
+// 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
+// config.cjs's validatePath (whose allowedRoots is the user's home dir and
+// would reject/mis-resolve a path under the app's own install directory,
+// e.g. when installed via npx/global npm outside $HOME). Read once and
+// cached in-process; this file never changes at runtime.
+const DEFAULT_HOME_PATH = path.join(__dirname, 'templates', 'project-pages-default-home.html');
+let cachedDefaultHomeHtml = null;
+function readDefaultHomeHtml() {
+  if (cachedDefaultHomeHtml === null) {
+    cachedDefaultHomeHtml = fs.readFileSync(DEFAULT_HOME_PATH, 'utf8');
+  }
+  return cachedDefaultHomeHtml;
+}
+function defaultOutput() {
+  return { home: readDefaultHomeHtml(), generatedAt: null, isDefault: true };
+}
+
+// The original 4 lenses stay required — their absence still means "no
+// Project Pages generated yet" (now the shipped-default fallback rather
+// than a bare null). 'brief' was added later (5th lens): a project that
+// generated its output BEFORE 'brief'
+// existed has home/marketing/feature/architecture.html but no brief.html, and
+// that must keep reading as "has output" rather than suddenly regressing to
+// 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.
+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 manifestResult = await config.readJson(path.join(dir, 'manifest.json'));
   if (!manifestResult.exists || !manifestResult.data || manifestResult.parseError) {
-    return { output: null };
+    return { output: defaultOutput() };
   }
 
   const htmlResults = await Promise.all(
     LENSES.map((lens) => config.readText(path.join(dir, `${lens}.html`))),
   );
-  if (htmlResults.some((r) => !r.exists)) {
-    return { output: null };
+  const byLens = Object.fromEntries(LENSES.map((lens, i) => [lens, htmlResults[i]]));
+  if (REQUIRED_LENSES.some((lens) => !byLens[lens].exists)) {
+    return { output: defaultOutput() };
   }
 
-  const [home, marketing, feature, architecture] = htmlResults;
   const generatedAt = typeof manifestResult.data.generatedAt === 'string' ? manifestResult.data.generatedAt : null;
   if (!generatedAt) {
-    return { output: null };
+    return { output: defaultOutput() };
   }
 
-  return {
-    output: {
-      home: home.text,
-      marketing: marketing.text,
-      feature: feature.text,
-      architecture: architecture.text,
-      generatedAt,
-    },
+  const output = {
+    home: byLens.home.text,
+    marketing: byLens.marketing.text,
+    feature: byLens.feature.text,
+    architecture: byLens.architecture.text,
+    generatedAt,
+    isDefault: false,
   };
+  if (byLens.brief.exists) {
+    output.brief = byLens.brief.text;
+  }
+
+  return { output };
 }
 
 function registerProjectPagesIpc() {
@@ -63,4 +107,6 @@ function registerProjectPagesIpc() {
 module.exports = {
   registerProjectPagesIpc,
   get,
+  DEFAULT_HOME_PATH,
+  readDefaultHomeHtml,
 };

package/src/main/promptSessionEvents.cjs

@@ -51,8 +51,20 @@ function mintEventId() {
  * unknown id, a completed session, an empty event chain, or any I/O error —
  * so notifyOriginatingTab's existing tab-external-ticket path stays the
  * safety net, not a special case.
+ *
+ * The optional 4th argument stamps `prdSlug`/`outcome` onto the appended
+ * event (PRD 976) — which PRD checked in and whether it completed, failed,
+ * or needs review — so the Epic's own event chain keeps that signal even
+ * after the job is archived out of queue.json. PRD 986 extends the same
+ * meta arg (not a fifth positional parameter) with `validation`: a
+ * scheduler check-in is born `'unvalidated'` — never `'verified'` —
+ * regardless of the job's self-reported outcome; the authoring Epic's own
+ * validation pass is what may later move it to 'verified'/'refuted'. All
+ * keys are added to the event object only when present in `meta`, never as
+ * `undefined`-valued keys, so events appended without them serialize
+ * identically to before.
  */
-async function appendResponseEventIfKnown(cwd, sourcePromptId, text) {
+async function appendResponseEventIfKnown(cwd, sourcePromptId, text, meta = {}) {
   if (!cwd || !sourcePromptId) return false;
   const path = promptSessionActiveIndexPath(cwd);
   try {
@@ -73,6 +85,9 @@ async function appendResponseEventIfKnown(cwd, sourcePromptId, text) {
         at: new Date().toISOString(),
         text,
       };
+      if (meta && meta.prdSlug) event.prdSlug = meta.prdSlug;
+      if (meta && meta.outcome) event.outcome = meta.outcome;
+      if (meta && meta.validation) event.validation = meta.validation;
       data.events[sourcePromptId] = [...events, event];
       await config.writeJson(path, data, { writer: 'scheduler' });
       broadcast(EVENT_APPENDED_CHANNEL, { cwd, promptSessionId: sourcePromptId, event });