claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/opsOwnership.cjs

@@ -48,17 +48,10 @@ const OWNERS = Object.freeze({
   'scheduler': 'scheduler',
   // Project Home owns the synthesized Brief (generate + hand-edit).
   'project-brief': 'project-home',
-  // Project Home also owns the app-side render path for Project Pages
-  // (summary.json/picks.json/output/* written via the
-  // /admin/project-home/render route, config.cjs's writeJson). This is a
-  // NARROWER claim than "project-home owns everything under this folder":
-  // the SAME folder is also written directly by a project-home-builder
-  // Epic's own Write tool, which never goes through config.cjs and so is
-  // NOT governed by this table at all (see
-  // session-manager-operations/project-pages/README.md). Declaring the
-  // namespace here only closes the fail-closed gap for the app's own write
-  // path — it does not claim exclusivity over the agent's Write-tool calls,
-  // which remain outside this law by construction.
+  // Project Home owns project-pages/home.html, written only via the
+  // project_home_write MCP tool -> /admin/project-home/write route
+  // (config.cjs's writeTextAtomic). See
+  // session-manager-operations/project-pages/README.md.
   'project-pages': 'project-home',
   // Structured per-tab error log lines (JSONL), tagged for tracing/analysis.
   'logs': 'logs',
@@ -177,11 +170,13 @@ function assertOpsWrite(absPath, writer) {
   // worktree-cwd hazard (PRD 1082; incidents 2026-08-30, 2026-09-01).
   const { inOps } = parseOpsPath(absPath);
   if (inOps) {
-    const segs = absPath.split(path.sep);
-    const idx = segs.lastIndexOf(OPS_ROOT_DIR);
-    const projectRoot = segs.slice(0, idx).join(path.sep) || path.sep;
-    const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
-    if (isEphemeralCwd(projectRoot)) {
+    // innermostOpsRoot (lastIndexOf) is the fact THIS gate keys on; activeSessions
+    // truncates at the outermost instead — cwdClassify returns both, unified in
+    // neither direction.
+    const { classifyCwd } = require('./cwdClassify.cjs');
+    const projectRoot = path.dirname(classifyCwd(absPath).innermostOpsRoot);
+    const { kind, reason } = classifyCwd(projectRoot);
+    if (kind === 'ephemeral' || kind === 'worktree') {
       const err = new Error(
         `refusing to write ${OPS_ROOT_DIR}/ state under an ephemeral project root `
         + `(tmpdir or linked git worktree): "${projectRoot}" — see lib/opsOwnership.cjs resolveProjectRoot`,
@@ -189,6 +184,17 @@ function assertOpsWrite(absPath, writer) {
       err.ephemeral = true;
       throw err;
     }
+    if (kind === 'unknown') {
+      // Fail closed on the unprovable case (worktree .git file whose admin
+      // back-reference is gone, garbled .git file): the exact shape behind the
+      // lost-Epics incidents. WRITES only — reads and dispatch stay open.
+      const err = new Error(
+        `refusing to write ${OPS_ROOT_DIR}/ state under "${projectRoot}": project identity `
+        + `cannot be proven (${reason}) — see lib/cwdClassify.cjs`,
+      );
+      err.unknownCwd = true;
+      throw err;
+    }
   }
 }
 
@@ -236,10 +242,12 @@ function resolveProjectRoot(cwd, { opsInternal = 'normalize' } = {}) {
       `resolveProjectRoot: cwd must be a project root, not a path inside ${OPS_ROOT_DIR}/, got "${cwd}"`,
     );
   }
-  // Lazy: activeSessions → gitWorktree → (lazily) config.cjs → this module.
-  const { projectRootOf } = require('../../../scripts/lib/activeSessions.cjs');
+  // Lazy: cwdClassify → schedulerPaths; ephemeralCwd → cwdClassify.
+  const { classifyCwd } = require('./cwdClassify.cjs');
   const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
-  const root = projectRootOf(cwd);
+  // `unknown` deliberately does NOT throw here: reads and dispatch must keep
+  // working; assertOpsWrite is the choke point that refuses the WRITE.
+  const root = classifyCwd(cwd).projectRoot;
   if (isEphemeralCwd(root)) {
     const err = new Error(
       `resolveProjectRoot: refusing ephemeral cwd (tmpdir or linked git worktree), got "${cwd}"`,

package/src/main/lib/prdAuthoringSeed.cjs

@@ -0,0 +1,36 @@
+'use strict';
+// Seed-when-the-stamp-differs for the bundled PRD_AUTHORING.md guide.
+// Pure fs + injected writer so it is testable without an Electron app.
+
+const fs = require('fs');
+
+const STAMP_RE = /^<!--\s*PRD_AUTHORING\.md\s+(v\d+)\s*-->/;
+
+/** Version stamp from line 1 of `text`, or null when absent. */
+function readStamp(text) {
+  const first = String(text).split(/\r?\n/, 1)[0];
+  const m = STAMP_RE.exec(first);
+  return m ? m[1] : null;
+}
+
+/** True when dest should be (re)written from src: missing/unstamped/differing stamp. */
+function shouldSeed(srcText, destText) {
+  if (destText == null) return true;
+  const destStamp = readStamp(destText);
+  return destStamp === null || destStamp !== readStamp(srcText);
+}
+
+/**
+ * Overwrite `dest` with `src` when shouldSeed. `write(abs, text)` is the atomic
+ * writer (config.writeTextAtomic). Resolves true when it wrote, false otherwise.
+ */
+async function seedAuthoringGuide({ src, dest, write }) {
+  if (!fs.existsSync(src)) return false;
+  const srcText = fs.readFileSync(src, 'utf8');
+  const destText = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf8') : null;
+  if (!shouldSeed(srcText, destText)) return false;
+  await write(dest, srcText);
+  return true;
+}
+
+module.exports = { readStamp, shouldSeed, seedAuthoringGuide };

package/src/main/lib/prdCreate.cjs

@@ -30,6 +30,7 @@ const { fixChainDepthOf, baseSlugOf } = require('./fixChainDepth.cjs');
 const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentType.cjs');
 const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
+const { isIncomplete, resolveChainTerminals } = require('./prdDisposition.cjs');
 
 // A caller-supplied slug that already starts with its own `NN-` (e.g.
 // "254-perf-x") used to silently become the double-prefixed row
@@ -74,7 +75,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine, disposition,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -108,6 +109,11 @@ function buildPrdBody(input) {
   fmLines.push(`agentType: ${agentType || DEFAULT_PRD_AGENT_TYPE}`);
   // Explicit ordering (PRD 832): replaces the retired shared-NN convention.
   if (dependsOn && dependsOn.length) fmLines.push(`dependsOn: [${dependsOn.join(', ')}]`);
+  // Wave-authoring decision (scheduler wave-disposition PRD) — only ever set
+  // when createPrd() actually had a disposition to record (see the call
+  // site above); a first-ever PRD in an Epic, or one with its own explicit
+  // dependsOn, has nothing to decide against and omits this key.
+  if (disposition) fmLines.push(`disposition: ${disposition}`);
   // Opt-in exclusive-lease flag (PRD 1107): serializes this job against
   // every other job machine-wide for its run, for a PRD whose acceptance
   // criteria are wall-clock/timing measurements that CPU contention from
@@ -237,6 +243,55 @@ async function createPrd(input, remote) {
     if (fallback) input = { ...input, sourcePromptId: fallback };
   }
 
+  // Wave-disposition decision point (scheduler wave-disposition PRD): only
+  // matters for a PRD that would become a ROOT of its own wave — one the
+  // caller didn't already give an explicit dependsOn (that already fixes
+  // its position in some chain) — joining an Epic whose sourcePromptId this
+  // PRD shares. See prdDisposition.cjs's header for the full contract.
+  if (input.sourcePromptId && (!input.dependsOn || input.dependsOn.length === 0)) {
+    let epicRows = [];
+    try {
+      const listing = await remote.listPrds({ cwd: input.cwd, fields: 'full', limit: Number.MAX_SAFE_INTEGER });
+      epicRows = (listing?.prds ?? []).filter((p) => p.sourcePromptId === input.sourcePromptId);
+    } catch (e) {
+      console.warn(`[prdCreate] disposition resolution skipped (listPrds failed): ${e?.message ?? e}`);
+    }
+    if (epicRows.some((p) => isIncomplete(p.status))) {
+      let disposition = input.disposition ?? null;
+      if (!disposition) {
+        // A headless PRD executor's own job has SM_SCHEDULER_JOB_SLUG set on
+        // its env (scheduler.cjs stamps every spawned job's child env with
+        // it) — no human is present to ask, so the conservative default
+        // ('append') applies and is logged as a default, never as a silent
+        // choice. Anything else (a live interactive Epic chat session, or a
+        // direct admin-route call) is refused instead of guessed — see this
+        // PRD's AC2.
+        const nonInteractive = Boolean(process.env.SM_SCHEDULER_JOB_SLUG);
+        if (!nonInteractive) {
+          return {
+            ok: false,
+            status: 400,
+            error: `Epic ${input.sourcePromptId} already has incomplete PRDs — pass disposition: "append" ` +
+              '(extend the existing chain behind its current tail) or "new-head" (an independent root, ' +
+              'eligible to run in parallel) to record this wave\'s relationship to the existing plan.',
+          };
+        }
+        disposition = 'append';
+        console.warn(`[prdCreate] disposition defaulted to "append" for a non-interactive caller (epic ${input.sourcePromptId})`);
+        appendAuditEvent('prd_disposition_defaulted', { cwd: input.cwd, epicId: input.sourcePromptId, disposition });
+      }
+      if (disposition === 'append') {
+        // Only the Epic's still-incomplete rows count as "the active plan" to
+        // append behind — a completed, undepended-upon row would otherwise
+        // also read as a terminal, silently attaching this wave to already-
+        // finished work instead of purely the current chain's live tail(s).
+        const terminals = resolveChainTerminals(epicRows.filter((p) => isIncomplete(p.status)));
+        if (terminals.length) input = { ...input, dependsOn: terminals };
+      }
+      input = { ...input, disposition };
+    }
+  }
+
   if (input.slug) {
     const nnMatch = SLUG_HAS_NN_PREFIX_RE.exec(input.slug);
     if (nnMatch) {

package/src/main/lib/prdDisposition.cjs

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * prdDisposition.cjs — the wave-authoring decision (scheduler wave-
+ * disposition PRD): when a new PRD wave joins an Epic that already has
+ * incomplete PRDs, does the wave APPEND behind the existing chain's tail, or
+ * start an independent NEW-HEAD root eligible to run in parallel? Before
+ * this module the choice didn't exist — every new root PRD silently landed
+ * as a parallel-eligible row, so waves interleaved with no recorded
+ * relationship and a human reading the backlog couldn't tell a plan from a
+ * pile.
+ *
+ * Two call sites:
+ *   - prdCreate.cjs's createPrd() — AUTHORING TIME. Resolves 'append' into a
+ *     concrete dependsOn via resolveChainTerminals() over the Epic's
+ *     existing rows.
+ *   - scheduler.cjs's `schedule:set-prd-disposition` IPC handler — CHANGING
+ *     an already-written PRD's disposition from the Scheduler UI. Uses
+ *     computeDispositionRewrite() to validate the rewrite is safe before
+ *     handing the new dependsOn to remote.updatePrd (which itself refuses a
+ *     non-pending/quarantined row — see scheduler.cjs's updatePrd).
+ *
+ * `rows` throughout is the same shape listPrdsInternal() already produces:
+ * { slug, status, dependsOn }. dependsOn entries are resolved against `rows`
+ * via depSlugResolve.cjs's resolveDepSlug — the SAME rule
+ * schedulerBatch.cjs's findBlockingDep and prdCreate.cjs's write-time FK
+ * check use, so a terminal/cycle computed here can never disagree with what
+ * the scheduler considers a row's real blockers at run time.
+ */
+
+const { resolveDepSlug } = require('./depSlugResolve.cjs');
+
+/** A row is "incomplete" (still part of the Epic's active plan) unless it
+ *  has actually finished. Treats every other status — including a brand-new
+ *  row with no queue entry yet (`status: null`) — as incomplete, since none
+ *  of those represent shipped work a wave could safely ignore. */
+function isIncomplete(status) {
+  return status !== 'completed';
+}
+
+/** Resolve each row's dependsOn entries to actual row slugs present in
+ *  `rows`, via the shared resolution rule. A dep that doesn't resolve to
+ *  anything in this row set (dangling, or lives outside this Epic) is
+ *  dropped — it can't affect this Epic's own terminal computation. */
+function resolvedDependents(rows) {
+  const slugs = rows.map((r) => r.slug);
+  const dependedUpon = new Set();
+  for (const r of rows) {
+    for (const dep of r.dependsOn ?? []) {
+      for (const resolved of resolveDepSlug(dep, slugs)) dependedUpon.add(resolved);
+    }
+  }
+  return dependedUpon;
+}
+
+/** Every row participating in a dependsOn cycle within `rows` (self-loops
+ *  included) — mirrors backlogTree.ts's detectCycles (renderer-only, can't
+ *  be required from this CJS main-process module; kept in sync by hand). */
+function detectCycles(rows) {
+  const bySlug = new Map(rows.map((r) => [r.slug, r]));
+  const slugs = rows.map((r) => r.slug);
+  const color = new Map();
+  const cyclic = new Set();
+  const stack = [];
+
+  function visit(slug) {
+    color.set(slug, 1);
+    stack.push(slug);
+    const r = bySlug.get(slug);
+    const deps = new Set();
+    for (const dep of r?.dependsOn ?? []) {
+      for (const resolved of resolveDepSlug(dep, slugs)) deps.add(resolved);
+    }
+    for (const dep of deps) {
+      const c = color.get(dep);
+      if (c === 1) {
+        const idx = stack.indexOf(dep);
+        for (let i = idx; i < stack.length; i++) cyclic.add(stack[i]);
+      } else if (c === undefined) {
+        visit(dep);
+      }
+    }
+    stack.pop();
+    color.set(slug, 2);
+  }
+
+  for (const r of rows) {
+    if (!color.has(r.slug)) visit(r.slug);
+  }
+  return cyclic;
+}
+
+/**
+ * Terminal (leaf) slugs of the dependency forest formed by `rows` — the
+ * row(s) nothing else in `rows` depends on. This is what an 'append'
+ * disposition attaches a new wave's root behind: depending on every current
+ * terminal means the new wave runs only once everything already queued (in
+ * every existing head) has finished, the conservative reading of "append".
+ * A row participating in a cycle is excluded — never used as a rewrite
+ * target, since a cycle indicates the existing graph shouldn't be extended
+ * until it's fixed by hand.
+ */
+function resolveChainTerminals(rows) {
+  if (!rows.length) return [];
+  const dependedUpon = resolvedDependents(rows);
+  const cyclic = detectCycles(rows);
+  return rows
+    .map((r) => r.slug)
+    .filter((slug) => !dependedUpon.has(slug) && !cyclic.has(slug));
+}
+
+/**
+ * Would setting `slug`'s dependsOn to `newDependsOn` create a cycle? Checks
+ * reachability from each (resolved) proposed dependency back to `slug`
+ * following the EXISTING graph in `rows` (never `slug`'s own current
+ * dependsOn, which is being replaced) — a direct self-reference is always a
+ * cycle, checked first without needing a graph walk.
+ */
+function wouldCreateCycle(rows, slug, newDependsOn) {
+  const slugs = rows.map((r) => r.slug);
+  const bySlug = new Map(rows.map((r) => [r.slug, r]));
+  const resolvedTargets = new Set();
+  for (const dep of newDependsOn) {
+    for (const resolved of resolveDepSlug(dep, slugs)) resolvedTargets.add(resolved);
+  }
+  if (resolvedTargets.has(slug)) return true;
+
+  const visited = new Set();
+  function reachesSlug(from) {
+    if (from === slug) return true;
+    if (visited.has(from)) return false;
+    visited.add(from);
+    const r = bySlug.get(from);
+    for (const dep of r?.dependsOn ?? []) {
+      for (const resolved of resolveDepSlug(dep, slugs)) {
+        if (reachesSlug(resolved)) return true;
+      }
+    }
+    return false;
+  }
+  for (const target of resolvedTargets) {
+    if (reachesSlug(target)) return true;
+  }
+  return false;
+}
+
+/**
+ * Validates and computes the new dependsOn for a disposition change on an
+ * already-written PRD (the Scheduler UI's "promote to head" / "attach
+ * behind another chain" action). Pure — returns the new dependsOn value on
+ * success; the caller (scheduler.cjs's IPC handler) is responsible for
+ * actually persisting it via remote.updatePrd, which independently refuses
+ * a non-pending/quarantined row (defense in depth, not duplicated here).
+ *
+ * Refuses (ok: false) when:
+ *   - `slug` isn't a known row.
+ *   - the row itself is 'running' or 'completed' — never touch live or
+ *     shipped work.
+ *   - any of the row's CURRENT dependsOn entries already resolved
+ *     ('completed') — the row may already be scheduler-eligible, and
+ *     rewriting its ordering out from under a resolved blocker risks
+ *     resurrecting/racing already-finished work (see this module's header).
+ *   - the proposed dependsOn would create a cycle.
+ */
+function computeDispositionRewrite({ slug, disposition, dependsOn, rows }) {
+  const row = rows.find((r) => r.slug === slug);
+  if (!row) return { ok: false, error: `PRD not found: ${slug}` };
+  if (row.status === 'running' || row.status === 'completed') {
+    return { ok: false, error: `cannot change disposition of a "${row.status}" PRD — it is no longer part of the open plan` };
+  }
+
+  const slugs = rows.map((r) => r.slug);
+  for (const dep of row.dependsOn ?? []) {
+    for (const resolved of resolveDepSlug(dep, slugs)) {
+      const depRow = rows.find((r) => r.slug === resolved);
+      if (depRow?.status === 'completed') {
+        return {
+          ok: false,
+          error: `refusing to rewrite dependsOn: blocker "${resolved}" has already completed — this PRD may ` +
+            'already be eligible to run; changing its ordering now risks resurrecting finished work',
+        };
+      }
+    }
+  }
+
+  const newDependsOn = disposition === 'new-head' ? [] : Array.from(new Set(dependsOn ?? []));
+  if (newDependsOn.length && wouldCreateCycle(rows, slug, newDependsOn)) {
+    return { ok: false, error: `dependsOn ${JSON.stringify(newDependsOn)} would create a dependency cycle` };
+  }
+
+  return { ok: true, dependsOn: newDependsOn };
+}
+
+module.exports = {
+  isIncomplete,
+  resolveChainTerminals,
+  wouldCreateCycle,
+  computeDispositionRewrite,
+};

package/src/main/lib/prdFrontmatter.cjs

@@ -77,8 +77,8 @@ function splitFrontmatter(raw) {
  * never emitted, which is how `scheduler_update_prd` clears a dependency.
  */
 
-const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine']);
-const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine'];
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition'];
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 function indentOf(line) {
@@ -179,6 +179,12 @@ function applyKey(fm, key, after) {
       // a no-op line for the overwhelming majority of PRDs that omit it.
       if (v === true) fm.quietMachine = true;
       return;
+    case 'disposition':
+      // Wave-authoring decision ('append'/'new-head') — see
+      // src/renderer/lib/prdFrontmatter.ts's mirror of this field for the
+      // full rationale. Only these two values are recognized.
+      if (v === 'append' || v === 'new-head') fm.disposition = v;
+      return;
   }
 }