claude-code-session-manager 0.85.0 → 0.87.0

package/src/main/lib/loadGate.cjs

@@ -32,6 +32,15 @@ const { loadGateThreshold, JOB_OVERRUN_FLOOR_MS } = require('./schedulerConfig.c
 // every tick would bury the signal in its own noise.
 const AUDIT_INTERVAL_MS = 10 * 60_000;
 
+// Default hysteresis release window for the gated stretch (PRD: boundary-
+// hovering load). A box sitting right at the threshold oscillates above/below
+// it tick to tick; clearing `gatedSince` on the first sub-threshold sample
+// reset the stretch counter every time, so `escalate` (and the warn-log with
+// topCpuConsumers()) never fired even after 80+ minutes of effectively
+// continuous gating. The stretch now only clears once load has stayed below
+// threshold continuously for this long.
+const RELEASE_WINDOW_MS = 2 * 60_000;
+
 /**
  * isLoadGated(loadavg1, cores, threshold) → boolean
  *
@@ -82,9 +91,11 @@ function createLoadGate({
   threshold = loadGateThreshold,
   auditIntervalMs = AUDIT_INTERVAL_MS,
   escalateAfterMs = JOB_OVERRUN_FLOOR_MS,
+  releaseWindowMs = RELEASE_WINDOW_MS,
 } = {}) {
   let lastAuditAt = null; // null = never audited; the first gated tick always audits
   let gatedSince = null;
+  let belowSince = null; // start of the current continuous sub-threshold run, while a stretch is open
   let last = null;
 
   function evaluate({ bypass = false } = {}) {
@@ -95,10 +106,21 @@ function createLoadGate({
     const ratio = c > 0 && Number.isFinite(l1) ? l1 / c : 0;
     const wouldGate = isLoadGated(l1, c, th);
 
+    // Hysteresis: the STRETCH (gatedSince) only clears after load has stayed
+    // below threshold continuously for releaseWindowMs. This never affects
+    // `gated` itself below — a sub-threshold tick still returns gated:false
+    // immediately; only the bookkeeping/escalation lags behind.
     if (wouldGate) {
       if (gatedSince === null) gatedSince = t;
+      belowSince = null;
+    } else if (gatedSince !== null) {
+      if (belowSince === null) belowSince = t;
+      if (t - belowSince >= releaseWindowMs) {
+        gatedSince = null;
+        belowSince = null;
+      }
     } else {
-      gatedSince = null;
+      belowSince = null;
     }
     const gated = wouldGate && !bypass;
     const bypassed = wouldGate && bypass;

package/src/main/lib/machineProfile.cjs

@@ -51,6 +51,20 @@ function resolveInstallChannel({ appPath = null, devFlag = !!process.env.SM_DEV
   return 'unknown';
 }
 
+/**
+ * Resolves the wire-level `env` discriminator ('prod' | 'dev' | 'test') from
+ * the real signals the caller already has — never inferred downstream from
+ * an appVersion string, which is how 1,526 pre-release/test `epic.create`
+ * records ended up misread as production usage (see telemetry.md). `test`
+ * takes priority: a vitest run that happens to report a `dev` installChannel
+ * (SM_DEV set in the test env) is still test traffic, not dev usage.
+ */
+function resolveEnv({ isTestRunner = false, installChannel } = {}) {
+  if (isTestRunner) return 'test';
+  if (installChannel === 'dev') return 'dev';
+  return 'prod';
+}
+
 /** sha256 of the concatenated stable spec fields, truncated to 12 hex chars. */
 function computeMachineDigest(specs) {
   const material = [
@@ -141,4 +155,5 @@ module.exports = {
   buildMachineProfile,
   computeMachineDigest,
   resolveInstallChannel,
+  resolveEnv,
 };

package/src/main/lib/mcpToolCatalog.cjs

@@ -75,7 +75,10 @@ const MCP_TOOL_CATALOG = [
       + '`tag` and `agentType` are two DIFFERENT, independent fields — `tag` is WHAT KIND '
       + 'of work this PRD is (feature/bug/build/...); `agentType` is WHO executes it (a '
       + 'persona name, e.g. "dev-lead"). `agentType` defaults to "dev-lead" when omitted, '
-      + 'and is rejected at write time if it does not name a real persona file.',
+      + 'and is rejected at write time if it does not name a real persona file. '
+      + 'If this PRD has no dependsOn of its own AND the target Epic already has incomplete PRDs, '
+      + '`disposition` ("append" or "new-head") is REQUIRED — the write is refused without it (a '
+      + 'headless job caller instead gets a logged "append" default, since no human is present to ask).',
     whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
     whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
       + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '

package/src/main/lib/needsReviewLedger.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+/**
+ * needsReviewLedger.cjs — pure helpers that make `needs_review` episodes
+ * durable and queryable in history.jsonl.
+ *
+ * Before this module, `queueHistory.cjs` archived a job to history.jsonl
+ * only on a TERMINAL status (completed/failed/skipped) — a needs_review
+ * park never left queue.json's hot jobs[] (it isn't terminal; see
+ * queueHistory.cjs's partitionJobs), so it never reached durable history
+ * either. Profiling history.jsonl for "how much needs_review is really
+ * happening" therefore always returned zero, however loud the problem
+ * looked in the UI.
+ *
+ * Two line shapes are appended to the SAME history.jsonl a terminal row
+ * lands in, distinguished by `kind` so existing terminal-only readers can
+ * filter them out on sight (see scheduleJobTransitions.cjs, the actual
+ * write choke point, and its callers' audit in the owning PRD):
+ *   - kind: 'needs_review_entry'      — one per transition INTO needs_review
+ *   - kind: 'needs_review_resolution' — one per transition OUT of needs_review,
+ *     referencing the entry's own runId so the two can be paired
+ *
+ * Kept fs-free and pure (mirrors reaperHelpers.cjs's rationale) so the
+ * ladder-rung classification and rollup reduction are unit-testable without
+ * touching disk or importing scheduler.cjs (which requires electron).
+ */
+
+// The 6 named ladder rungs a needs_review episode can resolve through
+// (spawnJob's mechanical/resume/quarantine/auto-fix branches, the periodic
+// reverifyNeedsReview heal pass, or an explicit human/API reset). Any
+// resolution whose transitionJob `source` doesn't match a known automated
+// rung is bucketed as 'manual-reset' — the conservative default for
+// anything that isn't a recognized self-healing path.
+const LADDER_RUNGS = [
+  'mechanical-recovery',
+  'resume-recovery',
+  'quarantine',
+  'auto-fix',
+  'reverify',
+  'manual-reset',
+];
+
+/**
+ * classifyLadderRung({ source, reason }) → one of LADDER_RUNGS.
+ *
+ * Matches the exact `source` strings scheduleJobTransitions.cjs's callers in
+ * scheduler.cjs pass for each recovery-ladder rung (see that module's
+ * LEGAL_TRANSITIONS doc comment for the full call-site inventory). Pattern
+ * matching, not an exhaustive enum lookup, because 'spawnJob:dispatch' is
+ * shared between the ordinary pending->running dispatch and the
+ * needs_review->running resume-recovery dispatch — the two are only
+ * distinguishable by `reason` text.
+ */
+function classifyLadderRung({ source, reason } = {}) {
+  const s = typeof source === 'string' ? source : '';
+  const r = typeof reason === 'string' ? reason : '';
+
+  if (s === 'scheduler:mechanicalRecovery') return 'mechanical-recovery';
+  if (s === 'spawnJob:dispatch' && /resume-recovery/i.test(r)) return 'resume-recovery';
+  if (s === 'spawnInvestigation:start' || s === 'spawnJob:auto-promote' || s === 'reverifyNeedsReview:auto-promote') {
+    return 'auto-fix';
+  }
+  if (s === 'reverifyNeedsReview:heal' || s === 'needsReviewAutoResolve') return 'reverify';
+  // No transitionJob call site resolves needs_review with a 'quarantine'
+  // source today (performLeftoverQuarantine cleans up leftover paths without
+  // itself changing job.status — the row stays needs_review until a later
+  // reverify/auto-resolve pass actually resolves it), but the rung is kept
+  // in LADDER_RUNGS/this classifier so a future direct-resolving quarantine
+  // path is classified correctly without another migration.
+  return 'manual-reset';
+}
+
+/**
+ * buildNeedsReviewEntryLine(job, entry) → JSONL-ready object.
+ *
+ * `entry` is the statusHistory record scheduleJobTransitions.cjs just
+ * pushed for this transition ({ from, to, reason, source, at }). The park
+ * reason prefers the structured `verifierVerdict` (a short, bucketable
+ * code) over the free-text `heldReason`/`error` fields, since those are the
+ * only reason evidence available for parks that never went through the
+ * verifier (e.g. a pidless-reap needs_review park).
+ */
+function buildNeedsReviewEntryLine(job, entry) {
+  return {
+    kind: 'needs_review_entry',
+    slug: job?.slug ?? null,
+    cwd: job?.cwd ?? null,
+    epicId: job?.epicId ?? null,
+    runId: job?.runId ?? null,
+    at: entry?.at ?? new Date().toISOString(),
+    reason: job?.verifierVerdict ?? job?.heldReason ?? job?.error ?? null,
+    source: entry?.source ?? null,
+  };
+}
+
+/**
+ * buildNeedsReviewResolutionLine(job, entry, episode) → JSONL-ready object.
+ *
+ * `episode` is `{ runId, enteredAt }` captured off the job at entry time
+ * (needsReviewEntryRunId/needsReviewEnteredAt) — the resolution line
+ * references the ENTRY's runId (which may differ from `job.runId` by
+ * resolution time, e.g. after a resume-recovery re-dispatch minted a fresh
+ * one), not whatever runId the job carries right now.
+ */
+function buildNeedsReviewResolutionLine(job, entry, episode) {
+  const enteredAtMs = episode?.enteredAt ? Date.parse(episode.enteredAt) : NaN;
+  const resolvedAtMs = entry?.at ? Date.parse(entry.at) : NaN;
+  const dwellMs = Number.isFinite(enteredAtMs) && Number.isFinite(resolvedAtMs)
+    ? Math.max(0, resolvedAtMs - enteredAtMs)
+    : null;
+  return {
+    kind: 'needs_review_resolution',
+    slug: job?.slug ?? null,
+    cwd: job?.cwd ?? null,
+    epicId: job?.epicId ?? null,
+    runId: episode?.runId ?? job?.runId ?? null,
+    at: entry?.at ?? new Date().toISOString(),
+    resolvedTo: entry?.to ?? null,
+    ladderRung: classifyLadderRung({ source: entry?.source, reason: entry?.reason }),
+    source: entry?.source ?? null,
+    dwellMs,
+  };
+}
+
+function percentile(sortedValues, p) {
+  if (!sortedValues.length) return null;
+  const idx = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil((p / 100) * sortedValues.length) - 1));
+  return sortedValues[idx];
+}
+
+/**
+ * reduceNeedsReviewLedger(lines) → rollup.
+ *
+ * Pure O(n log n) reduction (the log n is the dwell-time sort for the
+ * percentiles) over a flat array of already-parsed history.jsonl rows
+ * (mixing needs_review_entry/needs_review_resolution/terminal rows is fine —
+ * anything that isn't one of the two kinds this module writes is ignored).
+ *
+ * Pairs an entry with its resolution by (slug, runId) — the same pairing
+ * key buildNeedsReviewResolutionLine's `episode.runId` guarantees matches
+ * the entry line's `runId`. A slug that parks twice (two different runIds)
+ * produces two independent pairs, matching two independent recovery
+ * episodes rather than being conflated into one.
+ *
+ * Returns:
+ *   - byReason:     { [reason]: entryCount }   (reason = entry line's `reason`, or 'unknown')
+ *   - byLadderRung: { [rung]: resolutionCount } (rung = one of LADDER_RUNGS)
+ *   - unresolvedCount: entries with no matching resolution line yet
+ *   - dwellMsP50 / dwellMsP90: percentiles over resolved episodes' dwellMs (null if none)
+ */
+function reduceNeedsReviewLedger(lines) {
+  const list = Array.isArray(lines) ? lines : [];
+  const entriesByKey = new Map();
+  const resolutionsByKey = new Map();
+
+  for (const line of list) {
+    if (!line || typeof line !== 'object') continue;
+    const key = `${line.slug ?? ''}|${line.runId ?? ''}`;
+    if (line.kind === 'needs_review_entry') {
+      entriesByKey.set(key, line);
+    } else if (line.kind === 'needs_review_resolution') {
+      resolutionsByKey.set(key, line);
+    }
+  }
+
+  const byReason = {};
+  let unresolvedCount = 0;
+  for (const [key, entry] of entriesByKey) {
+    const reason = entry.reason ?? 'unknown';
+    byReason[reason] = (byReason[reason] ?? 0) + 1;
+    if (!resolutionsByKey.has(key)) unresolvedCount += 1;
+  }
+
+  const byLadderRung = {};
+  const dwellMsValues = [];
+  for (const [key, resolution] of resolutionsByKey) {
+    const rung = LADDER_RUNGS.includes(resolution.ladderRung) ? resolution.ladderRung : 'manual-reset';
+    byLadderRung[rung] = (byLadderRung[rung] ?? 0) + 1;
+    // Only count dwell for episodes that actually matched an entry — a
+    // resolution line with no paired entry (e.g. history truncated by
+    // retention before the entry aged out — never happens for needs_review
+    // rows today since they're excluded from partitionJobs' archivable set,
+    // but this stays defensive) has no truthful dwell to report.
+    if (entriesByKey.has(key) && typeof resolution.dwellMs === 'number' && Number.isFinite(resolution.dwellMs)) {
+      dwellMsValues.push(resolution.dwellMs);
+    }
+  }
+  dwellMsValues.sort((a, b) => a - b);
+
+  return {
+    byReason,
+    byLadderRung,
+    unresolvedCount,
+    dwellMsP50: percentile(dwellMsValues, 50),
+    dwellMsP90: percentile(dwellMsValues, 90),
+  };
+}
+
+module.exports = {
+  LADDER_RUNGS,
+  classifyLadderRung,
+  buildNeedsReviewEntryLine,
+  buildNeedsReviewResolutionLine,
+  reduceNeedsReviewLedger,
+};

package/src/main/lib/opsErrorLog.cjs

@@ -107,7 +107,7 @@ function writeLocalLine({ cwd, scope, level, tabId, epicId, tags, message, meta
 function reportToTelemetry({ cwd, scope, level, tabId, epicId, tags, message }) {
   try {
     const telemetryClient = require('./telemetryClient.cjs');
-    const { projectRootOf } = require('../../../scripts/lib/activeSessions.cjs');
+    const { projectRootOf } = require('./activeSessions.cjs');
     const normalizedCwd = projectRootOf(cwd) || cwd;
     const autoTags = [
       `scope:${scope || 'unknown'}`,

package/src/main/lib/opsOwnership.cjs

@@ -237,7 +237,7 @@ function resolveProjectRoot(cwd, { opsInternal = 'normalize' } = {}) {
     );
   }
   // Lazy: activeSessions → gitWorktree → (lazily) config.cjs → this module.
-  const { projectRootOf } = require('../../../scripts/lib/activeSessions.cjs');
+  const { projectRootOf } = require('./activeSessions.cjs');
   const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
   const root = projectRootOf(cwd);
   if (isEphemeralCwd(root)) {

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;
   }
 }