claude-code-session-manager 0.75.2 → 0.76.0

package/src/main/lib/opsOwnership.cjs

@@ -158,6 +158,97 @@ function checkOpsWrite(absPath, writer) {
 function assertOpsWrite(absPath, writer) {
   const verdict = checkOpsWrite(absPath, writer);
   if (!verdict.ok) throw new Error(verdict.error);
+  // Ownership is one question; WHERE the ops root lives is another. A writer
+  // that bypasses the path helpers below and builds its own absolute path can
+  // still aim at an ephemeral project root (a worktree, os.tmpdir()) — refuse
+  // that here too so the single-writer gate is also the last line against the
+  // 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)) {
+      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`,
+      );
+      err.ephemeral = true;
+      throw err;
+    }
+  }
+}
+
+// ─── THE ONE ops-root resolver (PRD 1082) ─────────────────────────────────
+//
+// Every namespace used to compute its own path with a bare
+// `path.join(cwd, 'session-manager-operations', ...)`, each one independently
+// trusting its `cwd`. The worktree / ops-internal cwd hazard therefore had to
+// be fixed one call site at a time (activeSessions 2026-08-30, PRDs 1073,
+// 1074, 1081). This is the single choke point every reader and writer of the
+// ops root goes through instead — normalize what can be normalized, refuse
+// what cannot — so the next stray cwd is caught by construction, not by
+// incident. `scripts/ops-sweep.cjs` lints that no other file in src/main/
+// spells the ops-root literal.
+//
+// Normalization is `activeSessions.projectRootOf`: an ops-internal path is
+// truncated to the project above it, a linked git worktree is mapped to its
+// main tree via the `.git` file's `gitdir:` pointer, and a subdirectory of a
+// git repo resolves to that repo's root. A plain directory with no enclosing
+// `.git` is returned unchanged (byte-identical to the old join). A nested
+// project that IS its own git repo (e.g. Apple/01-Shapes-Foundation) keeps its
+// own root — the walk stops at the first `.git` it meets.
+
+/**
+ * resolveProjectRoot(cwd, { opsInternal }) → absolute project root.
+ *
+ * Throws on a missing/non-string/relative cwd (a caller that cannot name an
+ * absolute project has no business touching that project's state), and
+ * throws a tagged `err.ephemeral = true` when the normalized root is still
+ * inside os.tmpdir() or is a linked worktree root (ephemeralCwd.cjs).
+ *
+ * `opsInternal` — 'normalize' (default): a cwd inside session-manager-
+ * operations/ is truncated up to its project, the reader-friendly behaviour
+ * activeSessions already has. 'refuse': throw instead — the fail-closed
+ * posture a WRITER wants (queueStore.projectStateDir), since silently
+ * redirecting a write target is riskier than refusing it.
+ */
+function resolveProjectRoot(cwd, { opsInternal = 'normalize' } = {}) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('resolveProjectRoot: cwd is required');
+  if (!path.isAbsolute(cwd)) {
+    throw new Error(`resolveProjectRoot: cwd must be an absolute path, got "${cwd}"`);
+  }
+  if (opsInternal === 'refuse' && cwd.split(path.sep).includes(OPS_ROOT_DIR)) {
+    throw new Error(
+      `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');
+  const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
+  const root = projectRootOf(cwd);
+  if (isEphemeralCwd(root)) {
+    const err = new Error(
+      `resolveProjectRoot: refusing ephemeral cwd (tmpdir or linked git worktree), got "${cwd}"`,
+    );
+    err.ephemeral = true;
+    throw err;
+  }
+  return root;
+}
+
+/** resolveOpsRoot(cwd, opts) → `<projectRoot>/session-manager-operations`. */
+function resolveOpsRoot(cwd, opts) {
+  return path.join(resolveProjectRoot(cwd, opts), OPS_ROOT_DIR);
+}
+
+/**
+ * opsPath(cwd, ...segments) → `<projectRoot>/session-manager-operations/<segments>`.
+ * The only sanctioned way to build a path inside a project's ops root.
+ */
+function opsPath(cwd, ...segments) {
+  return path.join(resolveOpsRoot(cwd), ...segments);
 }
 
 module.exports = {
@@ -167,4 +258,7 @@ module.exports = {
   parseOpsPath,
   checkOpsWrite,
   assertOpsWrite,
+  resolveProjectRoot,
+  resolveOpsRoot,
+  opsPath,
 };

package/src/main/lib/prdAdminRoutes.cjs

@@ -29,6 +29,9 @@ const { schemas } = require('../ipcSchemas.cjs');
 const { readBody, sendJson } = require('./localAdminHttp.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
 const queueOps = require('../queueOps.cjs');
+const { MCP_TOOL_CATALOG, MCP_RECIPES } = require('./mcpToolCatalog.cjs');
+const { checkDelegationReadiness } = require('./delegationReadiness.cjs');
+const { resolveProjectContext } = require('./projectRootResolve.cjs');
 
 function parseJsonBody(raw) {
   try {
@@ -45,6 +48,41 @@ function parseJsonBody(raw) {
  * scheduler.cjs's own registerAdminRoute(s) pattern.
  */
 function registerAdminRoute(adminHttp, remote) {
+  // GET /admin/mcp/catalog — read-only surface for mcpToolCatalog.cjs, the
+  // single source of truth scheduler-mcp-server.cjs's tool descriptions are
+  // now composed from (PRD: agent-facing help + Home-tab surface). No
+  // `remote` dependency; kept in this file only because it registers
+  // "alongside the existing PRD admin routes".
+  adminHttp.registerRoute('GET', '/admin/mcp/catalog', async (req, res) => {
+    sendJson(res, 200, { ok: true, tools: MCP_TOOL_CATALOG, recipes: MCP_RECIPES });
+  });
+
+  // GET /admin/mcp/readiness?cwd=... — session_manager_help's live half: the
+  // catalog above is static and always answerable in-process, but "is this
+  // MCP server actually wired up for this project" needs the same four
+  // checks delegationReadiness.cjs already runs for the New Epic readiness
+  // banner. `cwd` is a required query param (this server has no notion of
+  // "the" project — one admin API instance serves every open tab/project).
+  adminHttp.registerRoute('GET', '/admin/mcp/readiness', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.delegationReadinessCwd.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    // Normalize a worktree/ops-internal cwd to its real project root first —
+    // session_manager_help called from inside an Epic's worktree must report
+    // THAT project's readiness, not a worktree checkout's own (nonexistent)
+    // config state. See projectRootResolve.cjs's header.
+    const resolved = resolveProjectContext({ cwd: input.cwd });
+    const result = await checkDelegationReadiness({ cwd: resolved.cwd || input.cwd });
+    // `ok: true` means "the route answered"; `ready`/`checks` carry the
+    // actual delegation-readiness verdict — kept distinct so a caller can't
+    // mistake "readiness is false" for "the request itself failed".
+    sendJson(res, 200, { ok: true, ready: result.ok, checks: result.checks });
+  });
+
   // GET /admin/scheduler/prds — paginated PRD listing (PRD: 353KB/120s
   // fix). Sort order is stable and explicit: slug ascending via
   // String.localeCompare(..., { numeric: true }) (listPrdsInternal in
@@ -121,7 +159,7 @@ function registerAdminRoute(adminHttp, remote) {
       sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
       return;
     }
-    const result = await queueOps.archiveMany(input.slugs);
+    const result = await queueOps.archiveMany(input.slugs, input.cwd);
     // Audit only the slugs that actually archived — archiveMany's `results`
     // array carries the real per-slug outcome; logging every requested slug
     // regardless of whether it succeeded would misrepresent a partial-failure
@@ -147,9 +185,11 @@ function registerAdminRoute(adminHttp, remote) {
       sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
       return;
     }
-    const result = await remote.cancelJob(input.slug);
+    const result = await remote.cancelJob(input.slug, { cwd: input.cwd });
     if (!result.ok) {
-      const status = /not found/i.test(result.error ?? '') ? 404 : 409;
+      const status = result.error === 'invalid slug' ? 400
+        : /unknown slug|not found/i.test(result.error ?? '') ? 404
+          : 409;
       sendJson(res, status, result);
       return;
     }

package/src/main/lib/prdCreate.cjs

@@ -25,6 +25,7 @@ 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 STANDARDS_PATH = path.join(
   __dirname, '..', '..', '..',
@@ -138,17 +139,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 +189,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);

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;

package/src/main/lib/projectRootResolve.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * projectRootResolve.cjs — server-side project/Epic resolution for every
+ * cwd-accepting ops-root entry point (PRD: worktree-cwd Epic-lookup hazard).
+ *
+ * Problem this closes. An agent running inside an Epic's git worktree has
+ * `pwd` = `/tmp/session-manager-epic-worktrees/<hash>/<epicId>` and naturally
+ * passes that as `cwd` to `scheduler_create_prd` / `feedback_open_session`.
+ * `active-index.json` (the Epic registry) is git-tracked, so the worktree's
+ * copy is a snapshot frozen at branch time — it usually does NOT contain the
+ * very Epic the agent is running inside. Verified live 2026-09-01 on
+ * starry-night-ships: main's index had 5 rows including the running Epic; the
+ * worktree's copy had 1 row and did not contain it, so a naive per-cwd lookup
+ * returns null and the write is refused with "create/approve an Epic first" —
+ * reading to the human as "the Epic got lost", when it never did.
+ *
+ * `resolveProjectContext` fixes this at the API boundary, not by trying to
+ * keep every cwd-accepting caller worktree-aware individually:
+ *   1. Normalizes any supplied cwd through `activeSessions.projectRootOf`
+ *      (worktree -> main tree, ops-internal path -> project root).
+ *   2. When an `originClaudeSessionId` (or explicit `epicId`) is known,
+ *      searches for the owning Epic first in the normalized cwd's own
+ *      active-index, then across every project this machine has ever opened
+ *      (`activeSessions.allProjectCwds`) — because the Epic's OWN project may
+ *      not even be the cwd the agent guessed (e.g. a worktree whose gitdir
+ *      pointer is stale/unresolvable, or a cross-project mixup).
+ *   3. A resolved Epic's own project cwd (`epicCwd`) always wins over the
+ *      supplied/hinted cwd when they differ — the Epic is the ground truth.
+ *
+ * Pure, synchronous, fs-only — no Electron deps — so it can be required from
+ * the standalone scheduler-mcp-server.cjs process and from every ops-root
+ * path helper a sibling PRD (ops-root-single-resolver) folds in later.
+ */
+
+const path = require('node:path');
+const { projectRootOf, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
+
+/**
+ * resolveProjectContext({ cwd, originClaudeSessionId, epicId, originProjectRoot }, deps?)
+ *   → { cwd, epicId, epicCwd, source }
+ *
+ * `cwd` — the caller-supplied cwd (may be inside a worktree/ops-internal path,
+ *   or absent entirely when the caller is relying purely on Epic resolution).
+ * `originClaudeSessionId` — the calling session's own claude session id
+ *   (chatRunner.cjs's SM_CHAT_SESSION_ID / pty.cjs's tabId) — matched against
+ *   each Epic's `claudeSessionId`.
+ * `epicId` — an explicit already-known Epic id (e.g. a caller-supplied
+ *   `sourcePromptId`) — matched against each Epic's `id`. Either identifier
+ *   (or both) may be supplied; a match on either counts.
+ * `originProjectRoot` — a trusted hint (e.g. SM_PROJECT_ROOT env, stamped by
+ *   the process that actually knows the real project root) — normalized the
+ *   same way as `cwd` and preferred over it when both are given, but still
+ *   loses to a resolved Epic's own `epicCwd`.
+ *
+ * `source` records which path produced the returned `cwd`/`epicId`:
+ *   'cwd'                — no Epic identifier given, or none resolved; cwd is
+ *                          just the normalized supplied/hinted value.
+ *   'epic-index'          — the Epic was found in the (single) normalized
+ *                          base cwd's own active-index.
+ *   'cross-project-scan'  — the Epic was found only by scanning other known
+ *                          projects (or a duplicate id required tie-breaking).
+ *
+ * Never throws: an unresolvable cwd/hint/Epic id just yields a smaller
+ * result, never an error — refusal is the caller's decision, not this
+ * resolver's.
+ */
+function resolveProjectContext({ cwd, originClaudeSessionId, epicId: wantedEpicId, originProjectRoot } = {}, deps = {}) {
+  const projectRootOfFn = deps.projectRootOf || projectRootOf;
+  const allProjectCwdsFn = deps.allProjectCwds || allProjectCwds;
+  const readActiveIndexFn = deps.readActiveIndex || readActiveIndex;
+  const isEphemeralCwdFn = deps.isEphemeralCwd || isEphemeralCwd;
+  const warn = deps.warn || console.warn;
+
+  let baseCwd = null;
+  if (cwd && typeof cwd === 'string') {
+    baseCwd = projectRootOfFn(path.resolve(cwd));
+  }
+  if (originProjectRoot && typeof originProjectRoot === 'string') {
+    const hintRoot = projectRootOfFn(path.resolve(originProjectRoot));
+    // A trusted hint outranks the agent-supplied cwd, but a resolved Epic
+    // (below) still outranks both.
+    if (hintRoot) baseCwd = hintRoot;
+  }
+
+  const result = { cwd: baseCwd, epicId: null, epicCwd: null, source: 'cwd' };
+
+  if (!originClaudeSessionId && !wantedEpicId) return result;
+
+  const candidates = [];
+  if (baseCwd) candidates.push(baseCwd);
+  for (const p of allProjectCwdsFn()) {
+    if (!candidates.includes(p)) candidates.push(p);
+  }
+
+  const matches = [];
+  for (const projectCwd of candidates) {
+    const { sessions } = readActiveIndexFn(projectCwd);
+    for (const session of Object.values(sessions)) {
+      if (!session) continue;
+      const idHit = wantedEpicId && session.id === wantedEpicId;
+      const claudeHit = originClaudeSessionId && session.claudeSessionId === originClaudeSessionId;
+      if (idHit || claudeHit) {
+        matches.push({ projectCwd, epicId: session.id, status: session.status ?? null });
+        break;
+      }
+    }
+  }
+
+  if (matches.length === 0) return result;
+
+  let chosen = matches[0];
+  if (matches.length > 1) {
+    const score = (m) => (isEphemeralCwdFn(m.projectCwd) ? 0 : 2) + (m.status === 'active' ? 1 : 0);
+    chosen = matches.reduce((best, m) => (score(m) > score(best) ? m : best), matches[0]);
+    warn(
+      `[projectRootResolve] Epic id ${chosen.epicId} matched in multiple projects: `
+      + `${matches.map((m) => m.projectCwd).join(', ')} — choosing ${chosen.projectCwd} `
+      + '(prefers a non-worktree/tmp project with status=active)',
+    );
+  }
+
+  result.epicId = chosen.epicId;
+  result.epicCwd = chosen.projectCwd;
+  result.cwd = chosen.projectCwd;
+  result.source = matches.length > 1
+    ? 'cross-project-scan'
+    : (chosen.projectCwd === baseCwd ? 'epic-index' : 'cross-project-scan');
+  return result;
+}
+
+module.exports = { resolveProjectContext };

package/src/main/lib/promptSessionSchema.cjs

@@ -79,6 +79,13 @@ const PromptSessionSchema = z.object({
   // Passthrough only as of PRD 1032 — nothing populates this yet; the next
   // PRD in this chain wires Epic worktree minting.
   worktree: EpicWorktreeSchema.optional(),
+  // Status-mirror fields (epicStatusMirror.cjs) written onto prompt-sessions/
+  // <id>.json alongside the active-index.json row — never onto the index row
+  // itself, so a plain PromptSession read from active-index.json normally
+  // omits them. Optional here only so activeIndexRebuild.cjs can validate a
+  // mirrored file's reconstructed row against this same schema.
+  archivedAt: z.string().nullable().optional(),
+  indexedAt: z.string().optional(),
 });
 
 /**

package/src/main/lib/queueStore.cjs

@@ -33,12 +33,13 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { allProjectCwds, activeProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
-const { assertOpsWrite } = require('./opsOwnership.cjs');
+const { assertOpsWrite, resolveOpsRoot, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 const { ScheduleJobSchema } = require('./scheduleJobSchema.cjs');
 
 const MACHINE_STATE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-machine.json');
 const LEGACY_QUEUE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'queue.json');
-const STATE_SUBPATH = ['session-manager-operations', 'scheduler', 'state'];
+const OPS_DIRNAME = OPS_ROOT_DIR;
+const STATE_SUBPATH = ['scheduler', 'state'];
 
 /**
  * A project's `session-manager-operations/scheduler/state/` directory.
@@ -60,7 +61,43 @@ function projectStateDir(cwd) {
   if (!path.isAbsolute(cwd)) {
     throw new Error(`projectStateDir: cwd must be an absolute path, got "${cwd}"`);
   }
-  return path.join(cwd, ...STATE_SUBPATH);
+  // ...and it must not itself sit INSIDE an ops root. Absolute-and-existing
+  // was not enough: a transcript records an agent's `cd` into a PRD folder,
+  // activeSessions hands that subdirectory over as a project, and this join
+  // materializes a second ops root under the first — the doubled
+  // `.../prds/session-manager-operations/scheduler/state/queue.json` stubs
+  // found in starry-night-ships on 2026-08-30 (14 of them, 8 days' worth).
+  // activeSessions.projectRootOf normalizes such a cwd away upstream; this is
+  // the fail-closed backstop for every other caller. A queue file below an
+  // ops root is always a bug, never a project.
+  if (cwd.split(path.sep).includes(OPS_DIRNAME)) {
+    throw new Error(
+      `projectStateDir: cwd must be a project root, not a path inside ${OPS_DIRNAME}/, got "${cwd}"`,
+    );
+  }
+  // ...and it must not be an EPHEMERAL cwd (inside os.tmpdir(), or a linked
+  // git worktree root) — a worktree is torn down when its Epic/job ends, so
+  // any state written there is silently destroyed (verified live 2026-09-01
+  // as a scheduler shard rewritten every reconcile pass inside a since-deleted
+  // epic worktree). That check, and the worktree → main-tree normalization,
+  // live in opsOwnership.resolveOpsRoot (PRD 1082) — the one resolver every
+  // ops-root reader/writer goes through. `opsInternal: 'refuse'` keeps this
+  // WRITER fail-closed on an ops-internal cwd (the guard above shapes the
+  // message; the resolver is the backstop).
+  let opsRoot;
+  try {
+    opsRoot = resolveOpsRoot(cwd, { opsInternal: 'refuse' });
+  } catch (e) {
+    if (e?.ephemeral) {
+      const err = new Error(
+        `projectStateDir: refusing ephemeral cwd (tmpdir or linked git worktree), got "${cwd}"`,
+      );
+      err.ephemeral = true;
+      throw err;
+    }
+    throw e;
+  }
+  return path.join(opsRoot, ...STATE_SUBPATH);
 }
 
 function projectQueuePath(cwd) {
@@ -71,6 +108,26 @@ function projectHistoryPath(cwd) {
   return path.join(projectStateDir(cwd), 'history.jsonl');
 }
 
+/**
+ * queuePathOrSkip(cwd, context) → the shard path, or null when `cwd` is not a
+ * usable project root. projectStateDir fails closed on a relative or
+ * ops-internal cwd; a single such job row (or a stale cached cwd) must not
+ * abort a whole read or write of every OTHER project's queue, so callers that
+ * loop over many cwds log-and-skip instead of throwing.
+ */
+function queuePathOrSkip(cwd, context) {
+  try {
+    return projectQueuePath(cwd);
+  } catch (e) {
+    if (e?.ephemeral) {
+      console.warn(`[queueStore] ${context}: refusing ephemeral cwd "${cwd}" — ${e.message}`);
+    } else {
+      console.error(`[queueStore] ${context}: skipping invalid project cwd — ${e?.message}`);
+    }
+    return null;
+  }
+}
+
 function writeJsonAtomicSync(file, value) {
   assertOpsWrite(file, 'scheduler');
   fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -183,7 +240,8 @@ function readMergedSync(opts) {
     }
   }
   for (const cwd of stateCwds(opts)) {
-    const file = projectQueuePath(cwd);
+    const file = queuePathOrSkip(cwd, 'read');
+    if (!file) continue;
     try {
       const { jobs, invalid } = shapeJobs(fs.readFileSync(file, 'utf8'), file);
       out.jobs.push(...jobs);
@@ -212,7 +270,8 @@ async function readMerged(opts) {
     }
   }
   for (const cwd of stateCwds(opts)) {
-    const file = projectQueuePath(cwd);
+    const file = queuePathOrSkip(cwd, 'read');
+    if (!file) continue;
     try {
       const { jobs, invalid } = shapeJobs(await fsp.readFile(file, 'utf8'), file);
       out.jobs.push(...jobs);
@@ -261,12 +320,14 @@ async function writeSplit(state, defaultCwd) {
     byCwd.get(cwd).push(job);
   }
   for (const [cwd, jobs] of byCwd) {
+    const file = queuePathOrSkip(cwd, 'writeSplit');
+    if (!file) continue;
     try {
-      await writeJsonAtomic(projectQueuePath(cwd), { jobs });
+      await writeJsonAtomic(file, { jobs });
     } catch (e) {
       // A single unwritable project (deleted repo dir, permissions) must not
       // lose every other project's write.
-      console.error(`[queueStore] failed to write ${projectQueuePath(cwd)}: ${e?.message}`);
+      console.error(`[queueStore] failed to write ${file}: ${e?.message}`);
     }
   }
   bustCwdCache();
@@ -316,7 +377,8 @@ async function migrateLegacyGlobalQueue(defaultCwd) {
   }
   let moved = 0;
   for (const [cwd, jobs] of byCwd) {
-    const file = projectQueuePath(cwd);
+    const file = queuePathOrSkip(cwd, 'legacy split');
+    if (!file) continue;
     let existing = [];
     try { existing = shapeJobs(await fsp.readFile(file, 'utf8'), file).jobs; } catch { /* fresh shard */ }
     const have = new Set(existing.map((j) => j.slug));

package/src/main/lib/rcaReport.cjs

@@ -74,7 +74,7 @@ const PREVENTION_HINTS = {
   [FAILURE_CLASSES.ALREADY_SHIPPED]:
     "This run found its acceptance criteria already satisfied by a prior commit and correctly made no change, so no commit landed and the verifier returned `pass_no_commit`. This is a stale re-run, not an execution failure — the PRD's `.md` was never moved out of `session-manager-operations/scheduler/prds/` after the work shipped. Archive the PRD into `session-manager-operations/scheduler/prds-archived/` instead of re-queuing or re-running it.",
   [FAILURE_CLASSES.SELF_QUEUE]:
-    "This run either invoked /develop or /process-feedback from inside its own headless execution, or backgrounded a long-running command and called ScheduleWakeup to check back later — both are the 'you ARE the executor — never re-queue or self-schedule' anti-pattern. A headless PRD run must perform its own acceptance criteria directly and has no next turn to resume it (standards.md → Execution discipline).",
+    "This run either invoked /develop or /process-feedback from inside its own headless execution, or backgrounded a long-running command (e.g. a verification/test run) and called Monitor, TaskOutput, or ScheduleWakeup to check back later — all are the 'you ARE the executor — never re-queue or self-schedule' anti-pattern. A headless PRD run must perform its own acceptance criteria directly and has no next turn to resume it (standards.md → Execution discipline).",
   [FAILURE_CLASSES.STUCK_LOOP]:
     'Bound every command with `timeout <N> <cmd>` — never leave an unbounded `until`/`while true`/`sleep` poll in a PRD body (PRD_AUTHORING.md loop-hang guidance).',
   [FAILURE_CLASSES.POST_AC_OVERRUN]: