claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/lib/prdAgentType.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * prdAgentType.cjs — the PRD-frontmatter `agentType` FK, mirroring
+ * agentModelResolve.cjs's/epicMint.cjs's established convention for the
+ * Epic-level `agentType` FK: THROW ON WRITE, REPORT ON READ.
+ *
+ * A PRD's `agentType` names the persona (`~/.claude/agents/<name>.md`, or a
+ * project overlay at `<cwd>/.claude/agents/<name>.md`) that should execute
+ * it — distinct from `tag` (workTypeLibrary.cjs), which is the WORK TYPE.
+ * Reuses epicMint.cjs's personaFileExists/resolvePersonaPaths rather than a
+ * second persona-file reader, and agentLibrary.cjs's listPersonas() for the
+ * "available personas" name list surfaced in the write-time rejection error.
+ */
+
+const { personaFileExists, resolvePersonaPaths } = require('./epicMint.cjs');
+const { listPersonas } = require('../agentLibrary.cjs');
+
+/** PRD execution's documented default persona (dev-lead.md's own frontmatter role). */
+const DEFAULT_PRD_AGENT_TYPE = 'dev-lead';
+
+// READ side of the FK — logged at most once per (cwd, agentType) so a hot
+// reconcile/list pass re-parsing the same on-disk PRD every tick doesn't
+// flood opsErrorLog's daily file. Mirrors agentModelResolve.cjs's
+// loggedDanglingPersonas set.
+const loggedDanglingAgentTypes = new Set();
+
+/**
+ * Read-time tolerance check: a PRD on disk whose persona was renamed or
+ * deleted after the PRD was written must still load. Never throws — logs at
+ * most once via opsErrorLog when `agentType` is set but unresolvable.
+ */
+function reportDanglingAgentTypeOnce(cwd, agentType, deps = {}) {
+  if (!cwd || !agentType) return;
+  try {
+    const checkPersonaExists = deps.personaExists || personaFileExists;
+    if (checkPersonaExists(cwd, agentType, deps)) return;
+    const key = `${cwd}::${agentType}`;
+    if (loggedDanglingAgentTypes.has(key)) return;
+    loggedDanglingAgentTypes.add(key);
+    // Required lazily, same rationale as agentModelResolve.cjs's
+    // logDanglingPersonaOnce: pay for this leaf module only on the (rare)
+    // miss path.
+    const { appendError } = require('./opsErrorLog.cjs');
+    appendError({
+      cwd,
+      scope: 'prdAgentType',
+      level: 'warn',
+      message: `PRD agentType '${agentType}' has no resolvable persona file — PRD still loads`,
+      meta: { agentType },
+    });
+  } catch { /* logging must never break PRD loading */ }
+}
+
+/**
+ * Write-time FK check: throws when `agentType` is supplied but doesn't
+ * resolve to a readable persona file, naming the available personas (from
+ * the Agent Library) so the caller can pick a real one. A no-op when
+ * `agentType` is falsy — the caller is expected to default it separately
+ * (buildPrdBody's DEFAULT_PRD_AGENT_TYPE fill-in).
+ */
+async function assertAgentTypeWritable(cwd, agentType, deps = {}) {
+  if (!agentType) return;
+  const checkPersonaExists = deps.personaExists || personaFileExists;
+  if (checkPersonaExists(cwd, agentType, deps)) return;
+
+  const load = deps.listPersonas || listPersonas;
+  let available = [];
+  try {
+    available = (await load()).map((p) => p.name).filter(Boolean).sort();
+  } catch { /* best-effort — still throw below even if listing failed */ }
+
+  const { projectPath, globalPath } = resolvePersonaPaths(cwd, agentType, deps);
+  throw new Error(
+    `agentType '${agentType}' does not resolve to a readable persona file — checked ${projectPath} and `
+    + `${globalPath}. Available personas: ${available.length ? available.join(', ') : '(none found)'}`,
+  );
+}
+
+module.exports = {
+  DEFAULT_PRD_AGENT_TYPE,
+  assertAgentTypeWritable,
+  reportDanglingAgentTypeOnce,
+};

package/src/main/lib/prdCreate.cjs

@@ -25,6 +25,19 @@ const { expandHome } = require('./expandHome.cjs');
 const { readBody, sendJson } = require('./localAdminHttp.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
+const { resolveProjectContext } = require('./projectRootResolve.cjs');
+const { fixChainDepthOf, baseSlugOf } = require('./fixChainDepth.cjs');
+const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentType.cjs');
+
+// Fix-chain depth cap (PRD 1113): a fix-of-a-fix (depth >= 2) is refused at
+// this shared write path rather than caught later — scheduler.cjs's
+// MAX_INVESTIGATION_DEPTH=1 caps the auto-fix loop's OWN recursion the same
+// way, so the two limits must stay numerically consistent (depth 1 allowed,
+// depth 2 refused). This guard exists because that auto-fix cap only ever
+// sees PRDs `spawnInvestigation` itself authors; a human or planner session
+// authoring a `*-fix-fix-*` slug through this API bypasses it entirely —
+// which is exactly what happened on starry-night-ships (see PRD 1113's Goal).
+const FIX_CHAIN_DEPTH_CAP = 1;
 
 const STANDARDS_PATH = path.join(
   __dirname, '..', '..', '..',
@@ -50,7 +63,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, dependsOn,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -75,8 +88,21 @@ function buildPrdBody(input) {
   // Optional, additive: the user-selected Feature/Bug tag (PRD 774) carried
   // through from the originating PromptTicket — deterministic, never LLM-classified.
   if (tag) fmLines.push(`tag: ${tag}`);
+  // WHO executes this PRD — distinct from `tag` (the WORK TYPE, above).
+  // Always emitted (unlike tag): a PRD with no agentType is ambiguous about
+  // who runs it, so createPrd() fills in DEFAULT_PRD_AGENT_TYPE ('dev-lead')
+  // before calling this function when the caller omitted one. Validated at
+  // write time by createPrd() via prdAgentType.cjs's assertAgentTypeWritable
+  // — this function only serializes, it never validates.
+  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(', ')}]`);
+  // 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
+  // sibling jobs would otherwise invalidate. Only emitted when true — see
+  // prdFrontmatter.cjs's applyKey for the matching "only true opts in" parse.
+  if (quietMachine === true) fmLines.push('quietMachine: true');
   fmLines.push('---', '');
 
   const acLines = acceptanceCriteria.map((line) => `- [ ] ${line}`).join('\n');
@@ -138,17 +164,41 @@ function resolveSourcePromptIdFromClaudeSession(cwd, claudeSessionId) {
  * (400/409/500), left to the caller since only the HTTP route needs it.
  */
 async function createPrd(input, remote) {
-  // cwd is untrusted: this is the first *creating* mutation on a
-  // token-authed API whose product is "a command that will later run
-  // with --dangerously-skip-permissions in a chosen cwd". Route it
-  // through config.cjs's validatePath (allowedRoots = home dir) —
-  // same boundary every other fs-touching IPC handler uses — never a
-  // bespoke check here.
-  // Normalize a `~`-prefixed cwd BEFORE it reaches allocateParallelGroup/
-  // readPrd/writePrd — those pass cwd through to safeSlugPathIn-adjacent path
-  // joins that treat it as a literal path segment, so an unexpanded `~/...`
-  // fails downstream as a bare "invalid slug" instead of a clear cwd error.
-  const cwd = expandHome(input.cwd);
+  // cwd is untrusted AND, since this PRD, optional — a caller inside an
+  // Epic's git worktree naturally passes its worktree pwd (or omits cwd
+  // entirely and relies on originClaudeSessionId/sourcePromptId). Resolve the
+  // real project + owning Epic server-side BEFORE any validation: a worktree
+  // cwd currently PASSES config.validatePath and then reads the WRONG
+  // active-index.json (a git-tracked snapshot frozen at branch time), which
+  // is why "the Epic got lost" reports keep recurring even though the Epic
+  // never left main's index. See projectRootResolve.cjs's header.
+  const rawCwd = input.cwd ? expandHome(input.cwd) : null;
+  const originProjectRoot = input.originProjectRoot ? expandHome(input.originProjectRoot) : null;
+  const resolved = resolveProjectContext({
+    cwd: rawCwd,
+    originClaudeSessionId: input.originClaudeSessionId,
+    // Only ask the resolver to hunt for the project BY Epic id when no cwd
+    // (nor a trusted SM_PROJECT_ROOT hint) was supplied at all — an explicit
+    // cwd that merely needs worktree/ops-path normalization is already fixed
+    // by projectRootOf above, so the common already-correct-cwd call (cwd +
+    // sourcePromptId both supplied) never pays for a cross-project scan.
+    epicId: (rawCwd || originProjectRoot) ? undefined : input.sourcePromptId,
+    originProjectRoot,
+  });
+
+  if (!resolved.cwd) {
+    return {
+      ok: false,
+      status: 400,
+      error: 'cwd is required — pass cwd explicitly, or originClaudeSessionId/sourcePromptId that resolves '
+        + 'to an existing, already-approved Epic (create/approve an Epic first)',
+    };
+  }
+
+  // A resolved Epic's own project cwd always wins over the supplied/hinted
+  // one — see resolveProjectContext's header. `cwd` below is that final,
+  // already-normalized (worktree -> main tree) value.
+  const cwd = resolved.cwd;
   let realCwd;
   try {
     realCwd = config.validatePath(cwd);
@@ -164,9 +214,16 @@ async function createPrd(input, remote) {
   config.addAllowedRoot(realCwd);
   input = { ...input, cwd };
 
-  if (!input.sourcePromptId && input.originClaudeSessionId) {
-    const resolved = resolveSourcePromptIdFromClaudeSession(cwd, input.originClaudeSessionId);
-    if (resolved) input = { ...input, sourcePromptId: resolved };
+  if (resolved.epicId) {
+    input = { ...input, sourcePromptId: resolved.epicId };
+  } else if (!input.sourcePromptId && input.originClaudeSessionId) {
+    // Fallback kept for the narrow case a caller passes originClaudeSessionId
+    // but resolveProjectContext (which also scans cross-project) somehow
+    // missed it — resolveSourcePromptIdFromClaudeSession is the single-cwd
+    // primitive resolveProjectContext itself is built from, so this can only
+    // ever be a no-op in practice; kept for defense-in-depth, not duplicated logic.
+    const fallback = resolveSourcePromptIdFromClaudeSession(cwd, input.originClaudeSessionId);
+    if (fallback) input = { ...input, sourcePromptId: fallback };
   }
 
   const slug = input.slug || deriveSlugFromTitle(input.title);
@@ -185,6 +242,23 @@ async function createPrd(input, remote) {
   const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 
+  // Fix-chain depth guard (PRD 1113): refuse a fix-of-a-fix before it's ever
+  // written. depth 0/1 pass through unchanged (an ordinary PRD, or a first
+  // fix-plan, is never blocked); depth >= 2 means the base job has already
+  // failed to close via at least one prior fix attempt for reasons a repeat
+  // attempt won't resolve.
+  const chainDepth = fixChainDepthOf(filenameSlug);
+  if (chainDepth > FIX_CHAIN_DEPTH_CAP) {
+    const base = baseSlugOf(filenameSlug);
+    return {
+      ok: false,
+      status: 409,
+      error: `Fix-chain depth cap exceeded: "${base}" has already failed to close ${chainDepth} time(s) for ` +
+        `infrastructure reasons (refusing to write "${filenameSlug}.md" at depth ${chainDepth}). Authoring a ` +
+        'deeper fix PRD is not the correct response — stop and surface this to a human instead of retrying again.',
+    };
+  }
+
   // An explicit `parallelGroup` bypasses allocateParallelGroup()'s
   // collision-proof reservation, so re-check for an existing file at
   // this exact destination before writing — remote.writePrd itself has
@@ -196,6 +270,20 @@ async function createPrd(input, remote) {
     return { ok: false, status: 409, error: `PRD already exists: ${filenameSlug}.md` };
   }
 
+  // Write-time FK check (throw on write, report on read — see
+  // prdAgentType.cjs's header): a caller-supplied agentType that doesn't
+  // resolve to a readable persona file is rejected before anything is
+  // written, naming the available personas. A no-op when agentType is
+  // omitted — buildPrdBody fills in DEFAULT_PRD_AGENT_TYPE for that case,
+  // and the default persona is trusted without a lookup.
+  if (input.agentType) {
+    try {
+      await assertAgentTypeWritable(input.cwd, input.agentType);
+    } catch (e) {
+      return { ok: false, status: 400, error: e?.message ?? 'invalid agentType' };
+    }
+  }
+
   const body = buildPrdBody(input);
   const writeResult = await remote.writePrd(filenameSlug, body, input.cwd);
   if (!writeResult?.ok) {

package/src/main/lib/prdDeclaredPaths.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * prdDeclaredPaths.cjs — derive the file paths a PRD declares it touches, for
+ * the reverify self-heal pass's widened evidence window (PRD 1102).
+ *
+ * Reuses definitionOfDone.cjs's existing `extractSection` (already the PRD
+ * markdown section parser used by flagRiskySurfaces) rather than
+ * re-implementing one — see standards.md's API-reuse rule.
+ */
+
+const fs = require('node:fs');
+const { splitFrontmatter } = require('./prdFrontmatter.cjs');
+const { extractSection } = require('./definitionOfDone.cjs');
+
+// Backtick-quoted, extension-bearing relative paths, e.g. `src/main/scheduler.cjs`
+// or `src/main/scheduler.cjs:490` (trailing :line dropped). Requires at least
+// one `/` so bare identifiers like `npm` or `RESCANNABLE_VERDICTS` never match.
+const PATH_RE = /`([a-zA-Z0-9_][\w.-]*(?:\/[\w.-]+)+\.[a-zA-Z0-9]+)(?::\d+)?`/g;
+
+/**
+ * Extract declared file paths from a PRD body (frontmatter already
+ * stripped). Scans the `# Implementation notes` and `# Acceptance criteria`
+ * sections only — the same sections flagRiskySurfaces and the PRD-authoring
+ * convention already treat as where files-touched are named. Returns `[]`
+ * (never fabricates a path) when neither section names one.
+ *
+ * @param {string} prdBody
+ * @returns {string[]} deduped, in first-seen order
+ */
+function extractDeclaredPaths(prdBody) {
+  if (!prdBody || typeof prdBody !== 'string') return [];
+  const text = [
+    extractSection(prdBody, 'Implementation notes'),
+    extractSection(prdBody, 'Acceptance criteria'),
+  ].join('\n');
+
+  const paths = [];
+  const seen = new Set();
+  let m;
+  PATH_RE.lastIndex = 0;
+  while ((m = PATH_RE.exec(text))) {
+    if (!seen.has(m[1])) {
+      seen.add(m[1]);
+      paths.push(m[1]);
+    }
+  }
+  return paths;
+}
+
+/**
+ * Read a PRD file and extract its declared paths. Never throws — a missing
+ * or unreadable PRD (e.g. archived and swept) resolves to `[]`.
+ *
+ * @param {string|null} prdPath
+ * @returns {string[]}
+ */
+function declaredPathsForPrd(prdPath) {
+  if (!prdPath) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(prdPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const { body } = splitFrontmatter(raw);
+  return extractDeclaredPaths(body);
+}
+
+module.exports = { extractDeclaredPaths, declaredPathsForPrd };

package/src/main/lib/prdFrontmatter.cjs

@@ -62,7 +62,7 @@ function splitFrontmatter(raw) {
  * either surface never reorders or drops a key it didn't touch. Recognized
  * key set intentionally mirrors the TS module exactly (title, cwd,
  * estimateMinutes, parallelGroup, sourcePromptId, sourceTabId, tag,
- * createdVia, issuedAt); every other frontmatter key (e.g. dependsOn)
+ * agentType, createdVia, issuedAt); every other frontmatter key (e.g. dependsOn)
  * round-trips via `extras`, same as the renderer's editor today.
  *
  * `createdVia`/`issuedAt` (PRD provenance-lockdown) are recognized here so
@@ -72,8 +72,8 @@ function splitFrontmatter(raw) {
  * into `extras`.
  */
 
-const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt']);
-const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt'];
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'quietMachine']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'quietMachine'];
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 function indentOf(line) {
@@ -125,12 +125,26 @@ function applyKey(fm, key, after) {
       // Matches the TS source's applyKey exactly — see PRD_TAG_VALUES above.
       if (PRD_TAG_VALUES.has(v)) fm.tag = v;
       return;
+    case 'agentType':
+      // WHO executes this PRD — a persona name, not a closed enum (the
+      // Agent Library is user-editable). FK resolution against the Agent
+      // Library happens in prdAgentType.cjs, not here — this parser only
+      // round-trips the string.
+      fm.agentType = String(v);
+      return;
     case 'createdVia':
       fm.createdVia = String(v);
       return;
     case 'issuedAt':
       fm.issuedAt = String(v);
       return;
+    case 'quietMachine':
+      // Opt-in exclusive-lease flag (PRD 1107) — only a literal `true`
+      // frontmatter value opts in; anything else (including an explicit
+      // `false`) is treated as "not set" so the field never round-trips as
+      // a no-op line for the overwhelming majority of PRDs that omit it.
+      if (v === true) fm.quietMachine = true;
+      return;
   }
 }
 

package/src/main/lib/prdLocations.cjs

@@ -19,8 +19,14 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { activeProjectCwds, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
 
-const PRD_SUBPATH = ['session-manager-operations', 'scheduler', 'prds'];
-const EPICS_SUBPATH = ['session-manager-operations', 'scheduler', 'epics'];
+const { opsPath, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
+
+// Segments UNDER the ops root; the ops root itself is resolved by
+// opsOwnership.opsPath (PRD 1082) — never joined onto a raw cwd here.
+const PRD_SUBPATH = ['scheduler', 'prds'];
+const EPICS_SUBPATH = ['scheduler', 'epics'];
+// Segment count from a project root to an epic's own dir: <ops-root> + EPICS_SUBPATH.
+const EPICS_DEPTH_FROM_PROJECT = 1 + EPICS_SUBPATH.length;
 
 /**
  * resolveEpicsRoot(cwd) → `<cwd>/session-manager-operations/scheduler/epics`
@@ -30,7 +36,7 @@ function resolveEpicsRoot(cwd) {
   if (!cwd || typeof cwd !== 'string') {
     throw new Error('resolveEpicsRoot: cwd is required');
   }
-  return path.join(cwd, ...EPICS_SUBPATH);
+  return opsPath(cwd, ...EPICS_SUBPATH);
 }
 
 /**
@@ -69,7 +75,8 @@ function listEpicPrdDirs(cwd) {
  * its Epic (the layout every new PRD uses) is still found.
  */
 function listArchivedPrdDirs(cwd) {
-  const dirs = [path.join(cwd, ...PRD_SUBPATH, '..', 'prds-archived')];
+  let dirs;
+  try { dirs = [opsPath(cwd, ...PRD_SUBPATH, '..', 'prds-archived')]; } catch { return []; }
   let root;
   try { root = resolveEpicsRoot(cwd); } catch { return dirs; }
   let entries;
@@ -91,7 +98,7 @@ function resolvePrdWriteDir(cwd) {
   if (!cwd || typeof cwd !== 'string') {
     throw new Error('resolvePrdWriteDir: cwd is required');
   }
-  return path.join(cwd, ...PRD_SUBPATH);
+  return opsPath(cwd, ...PRD_SUBPATH);
 }
 
 /**
@@ -202,7 +209,7 @@ function deriveEpicIdFromPrdPath(filePath) {
   const epicId = path.basename(epicDir);
   if (!epicId || epicId === '.' || epicId === path.sep) return null;
   let projectCwd = path.dirname(epicDir); // epicsRoot (.../scheduler/epics)
-  for (let i = 0; i < EPICS_SUBPATH.length; i++) projectCwd = path.dirname(projectCwd);
+  for (let i = 0; i < EPICS_DEPTH_FROM_PROJECT; i++) projectCwd = path.dirname(projectCwd);
   let epicsRoot;
   try { epicsRoot = resolveEpicsRoot(projectCwd); } catch { return null; }
   if (path.join(epicsRoot, epicId, dirName) !== prdsDir) return null;