claude-code-session-manager 0.88.1 → 0.90.0

package/src/main/lib/telemetryClient.cjs

@@ -374,12 +374,19 @@ async function persistSent() {
   await config.writeJson(sentPath(), { ids: S.sentOrder, updatedAt: new Date().toISOString() }, { mode: 0o600 });
 }
 
+// Records are immutable once queued, so their serialized size is computed once. Without
+// this, enforceCap() re-stringified the whole queue on every append: O(n^2) stringifies
+// (~15s idle for 5000 appends) and the reason the cap tests blew their budget under load.
+const recordBytesCache = new WeakMap();
 function recordBytes(r) {
+  const hit = recordBytesCache.get(r);
+  if (hit !== undefined) return hit;
+  let n = 0;
   try {
-    return Buffer.byteLength(JSON.stringify(r), 'utf8');
-  } catch {
-    return 0;
-  }
+    n = Buffer.byteLength(JSON.stringify(r), 'utf8');
+  } catch { /* unserializable -> 0 */ }
+  recordBytesCache.set(r, n);
+  return n;
 }
 
 /** Oldest-first eviction, bounded by count and total bytes. O(n) per call, n <= QUEUE_CAP_COUNT. */

package/src/main/lib/terminalRunOutcome.cjs

@@ -21,6 +21,7 @@ const COMPLETED_EQUIVALENT_VERDICTS = new Set([
   'pass_no_commit_target_verified',
   'pass_no_commit_already_shipped',
   'pass_no_commit_prior_run_verified',
+  'pass_no_commit_artifact_verified',
 ]);
 
 // Bounds the scan: only the newest few run dirs are stat'd per slug, never

package/src/main/pty.cjs

@@ -181,7 +181,7 @@ class PtyManager {
     // returns its isolated worktree dir when one exists — `cwd` itself is
     // NEVER repointed; only this actual PTY spawn option is. See
     // epicSpawnCwd.cjs's header comment (the ops-root hazard) for why.
-    const spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: tabId });
+    const spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: tabId, deps: { restore: true } });
     if (spawnCwd !== cwd) {
       console.log(`[pty] tabId=${tabId} isolated in worktree ${spawnCwd}`);
     }

package/src/main/runVerify.cjs

@@ -40,6 +40,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { parsePrdFile } = require('./lib/prdFrontmatter.cjs');
 
 const VERDICTS_SCHEMA_VERSION = 1;
 
@@ -778,6 +779,57 @@ function allDeliverablesAlreadyTracked({ cwd, paths, execImpl = execFileSync, ti
   }
 }
 
+
+/**
+ * Material check for a DECLARED artifact-only PRD (`deliverable: artifact` +
+ * `artifactPaths`). Returns true only when every declared path resolves inside
+ * `cwd`, is a non-empty regular file, and has an mtime inside the run window
+ * (startedAt - 60s .. (finishedAt ?? now) + 120s). Never throws: any doubt
+ * (no paths, `..`, escape, missing, non-file, empty, stale, fs error) → false.
+ * `cwd` may be a list of roots; a path is accepted if it verifies under any.
+ * Complexity O(paths).
+ */
+function artifactsVerifiedOnDisk({ cwd, paths, startedAt, finishedAt, fsImpl = fs } = {}) {
+  return artifactsCheck({ cwd, paths, startedAt, finishedAt, fsImpl }).ok;
+}
+
+function artifactsCheck({ cwd, paths, startedAt, finishedAt, fsImpl = fs }) {
+  const fail = { ok: false, verified: [] };
+  try {
+    const roots = (Array.isArray(cwd) ? cwd : [cwd]).filter((r) => typeof r === 'string' && r);
+    if (!roots.length || !Array.isArray(paths) || paths.length === 0) return fail;
+    const start = Date.parse(startedAt ?? '');
+    if (Number.isNaN(start)) return fail;
+    const endParsed = finishedAt ? Date.parse(finishedAt) : NaN;
+    const end = Number.isNaN(endParsed) ? Date.now() : endParsed;
+    const lo = start - 60_000;
+    const hi = end + 120_000;
+    const verified = [];
+    for (const p of paths) {
+      if (typeof p !== 'string' || !p || p.includes('\0')) return fail;
+      if (p.split(/[\\/]/).includes('..')) return fail;
+      let hit = null;
+      for (const root of roots) {
+        const base = path.resolve(root);
+        const abs = path.resolve(base, p);
+        const rel = path.relative(base, abs);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        let st;
+        try { st = fsImpl.statSync(abs); } catch { continue; }
+        if (!st.isFile() || st.size <= 0) continue;
+        if (st.mtimeMs < lo || st.mtimeMs > hi) continue;
+        hit = { path: p, size: st.size, mtime: new Date(st.mtimeMs).toISOString() };
+        break;
+      }
+      if (!hit) return fail;
+      verified.push(hit);
+    }
+    return { ok: true, verified };
+  } catch {
+    return fail;
+  }
+}
+
 // ─── main verifier ────────────────────────────────────────────────────────────
 
 /**
@@ -830,7 +882,7 @@ function allDeliverablesAlreadyTracked({ cwd, paths, execImpl = execFileSync, ti
  */
 async function verifyRun({
   runDir, prdPath, queueEntry, allJobs = [], committedDuringRun = false, allowPreSentinelHeal = false,
-  ghExecImpl, priorLandedCommit = null, jobLandedCommitThisRun = null, exitCode = null,
+  ghExecImpl, priorLandedCommit = null, jobLandedCommitThisRun = null, exitCode = null, worktreeDir = null,
 }) {
   const { slug } = queueEntry;
   const logPath = path.join(runDir, `${slug}.log`);
@@ -1202,7 +1254,42 @@ async function verifyRun({
           );
         }
       }
+      // EXEMPTION: a PRD that DECLARES `deliverable: artifact` + `artifactPaths`
+      // (all deliverables live in a git-excluded dir, so "no commit" is
+      // correct). Reads the declared list from frontmatter — never scrapes
+      // prose — and stat-checks each file on disk (non-empty, in the run
+      // window). Paths resolve against queueEntry.cwd, then retry against the
+      // run's worktree dir when the caller supplies one. Any doubt falls
+      // through to pass_no_commit below. The commit guard separately requires
+      // a clean tree for this verdict (scheduler.cjs commitGuardVerdict).
+      let artifactVerified = false;
       if (!mergeMainVerified && !priorRunVerified && !alreadyShipped) {
+        let fm = null;
+        try { fm = parsePrdFile(prdFullText).frontmatter; } catch { fm = null; }
+        if (fm && fm.deliverable === 'artifact' && Array.isArray(fm.artifactPaths) && fm.artifactPaths.length > 0) {
+          const check = artifactsCheck({
+            cwd: [queueEntry?.cwd, worktreeDir],
+            paths: fm.artifactPaths,
+            startedAt: queueEntry?.startedAt,
+            finishedAt: queueEntry?.finishedAt,
+          });
+          if (check.ok) {
+            artifactVerified = true;
+            return conclude(
+              'pass_no_commit_artifact_verified',
+              'SCHEDULER_VERDICT: PASS with no commit, but every declared artifact exists, is non-empty, and was '
+                + `written inside the run window (${check.verified.map((v) => v.path).join(', ')})`,
+              null,
+              {
+                ...(annotations.length ? { annotations } : {}),
+                sentinel,
+                verifiedArtifacts: check.verified,
+              },
+            );
+          }
+        }
+      }
+      if (!mergeMainVerified && !priorRunVerified && !alreadyShipped && !artifactVerified) {
         issues.push({
           verdict: 'pass_no_commit',
           reason: 'SCHEDULER_VERDICT: PASS but no commit landed during the run window — the run claims success but produced no code change',
@@ -1294,6 +1381,7 @@ module.exports = {
   checkMergeablePr,
   extractPrdDeliverablePaths,
   allDeliverablesAlreadyTracked,
+  artifactsVerifiedOnDisk,
   isAncestorCommit,
   isGitRepo,
   hasAbandonedBackgroundTask,

package/src/main/scheduler.cjs

@@ -4540,11 +4540,18 @@ async function findSatisfyingCommitOnMain(job) {
  *     newlyDirty is empty: a fix-plan job that left real dirt behind is
  *     still a genuine finish-protocol violation (incident:
  *     523-fix-bounded-fix-plan-retry, 2026-07-12).
- */
-function commitGuardVerdict({ newlyDirty, siblingRunning, ranInWorktree, jobSelfCommitted, legitimateNoOp, isFixPlanJob, verifyResult, salvagePatch }) {
+ *   - artifactVerified (zero-edit case only): runVerify.cjs proved a PRD that
+ *     DECLARED `deliverable: artifact` wrote its git-excluded artifacts inside
+ *     the run window (pass_no_commit_artifact_verified). That verdict is
+ *     deliberately NOT blanket-excused via legitimateNoOp (the call site
+ *     excludes it) — it stands the guard down only on a clean tree, like the
+ *     fix-plan carve-out, so stray uncommitted tracked edits still park as
+ *     uncommitted_changes.
+ */
+function commitGuardVerdict({ newlyDirty, siblingRunning, ranInWorktree, jobSelfCommitted, legitimateNoOp, isFixPlanJob, artifactVerified, verifyResult, salvagePatch }) {
   if ((siblingRunning && !ranInWorktree) || jobSelfCommitted || legitimateNoOp) return null;
   const dirty = newlyDirty || [];
-  if (dirty.length === 0 && isFixPlanJob) return null;
+  if (dirty.length === 0 && (isFixPlanJob || artifactVerified)) return null;
 
   const carried = [...(verifyResult?.annotations ?? [])];
   if (verifyResult && verifyResult.verdict !== 'clean') {
@@ -4797,6 +4804,25 @@ As the LAST LINE of your final result text, emit exactly one of:
 Print PASS only once the commit above has actually landed.`;
 }
 
+/**
+ * Stamps integrateBranch's failure subtype (`failureKind`) and conflicted
+ * paths onto a job row at finalize; clears both when there is no failure so
+ * a re-run never carries a stale subtype. Plain JSON values only.
+ */
+function stampIntegrationFailure(row, integration) {
+  if (integration && integration.failureKind) {
+    row.integrationFailureKind = integration.failureKind;
+    if (Array.isArray(integration.conflictedPaths)) row.integrationConflictPaths = integration.conflictedPaths;
+    else delete row.integrationConflictPaths;
+    if (integration.baseHeadSha) row.integrationBaseHeadSha = integration.baseHeadSha;
+    else delete row.integrationBaseHeadSha;
+  } else {
+    delete row.integrationFailureKind;
+    delete row.integrationConflictPaths;
+    delete row.integrationBaseHeadSha;
+  }
+}
+
 /**
  * Mechanical recovery (PRD 1130). isFixPlanBeyondDepthCap (below) is the
  * ONLY gate on re-investigating a fix-plan job at investigationDepth >= 2 —
@@ -4809,14 +4835,21 @@ Print PASS only once the commit above has actually landed.`;
  * auto-fix it authors no plan and spawns no model; it is pure git.
  *
  * The closed set of mechanically-resolvable verdicts starts at exactly
- * 'worktree_integration_failed': PRD 1125 already taught integrateBranch to
- * parse git's "would be overwritten by merge" stderr, verify the blocking
- * paths are byte-identical to the branch, discard the proven duplicates, and
- * retry the merge once. A job parked with this verdict has its `sm-job/
- * <slug>` branch preserved (integrateJobBranch never deletes the branch on
- * failure — see cleanupJobWorktree's `keepBranch: !integration.ok`), so a
- * plain re-call of integrateBranch against that same branch inherits PRD
- * 1125's auto-resolution for free — no re-implementation needed here.
+ * 'worktree_integration_failed', which covers two subtypes (job.
+ * integrationFailureKind): `blocking_paths` — PRD 1125 taught integrateBranch
+ * to parse git's "would be overwritten by merge" stderr, verify the blocking
+ * paths are byte-identical to the branch, discard the proven duplicates and
+ * retry once, so a re-call can genuinely succeed once the dirty files are
+ * gone — and `content_conflict`, which PRD 1125 explicitly does NOT handle
+ * (parseBlockingMergePaths returns null for it). Only pure-addition text
+ * conflicts are auto-resolved (mc-02, gitWorktree.cjs, kill switch
+ * SM_PURE_ADDITION_MERGE_DISABLE=1) — and that already ran inside the
+ * original failed integration. Re-calling integrateBranch for a content
+ * conflict that survived it, against an unmoved base HEAD, fails
+ * deterministically, so the selector skips it (WITHOUT spending the one
+ * attempt) until HEAD moves — a sibling merge may make the retry succeed.
+ * A job parked with this verdict has its `sm-job/<slug>` branch preserved
+ * (cleanupJobWorktree's `keepBranch: !integration.ok`).
  *
  * Bounded to exactly one attempt via job.mechanicalRecoveryAttempted,
  * stamped in the SAME mutate as the outcome (performMechanicalRecovery,
@@ -4828,11 +4861,41 @@ Print PASS only once the commit above has actually landed.`;
  */
 const MECHANICALLY_RESOLVABLE_VERDICTS = new Set(['worktree_integration_failed']);
 
-function selectMechanicalRecoveryTarget(job) {
+/**
+ * True when a retry is provably futile: a content_conflict whose base HEAD is
+ * the same as at failure time. Unknown state (no stamp, null current HEAD)
+ * is NOT futile — falls back to attempting the retry.
+ */
+function isMechanicalRecoveryFutile(job, currentHeadSha) {
+  return job.integrationFailureKind === 'content_conflict'
+    && !!job.integrationBaseHeadSha
+    && !!currentHeadSha
+    && job.integrationBaseHeadSha === currentHeadSha;
+}
+
+/**
+ * Resolves the current HEAD once per distinct cwd for a pass. Returns a
+ * `(job) => sha|null` lookup over `jobs`; the memo lives only as long as the
+ * returned closure. O(distinct cwds) git calls, not O(jobs).
+ */
+async function resolveHeadShasForPass(jobs) {
+  const byCwd = new Map();
+  for (const j of jobs || []) {
+    if (!j || j.status !== 'needs_review' || j.integrationFailureKind !== 'content_conflict') continue;
+    const cwd = j.cwd || DEFAULT_PROJECT_CWD;
+    if (!byCwd.has(cwd)) byCwd.set(cwd, gitHead(cwd));
+  }
+  const resolved = new Map();
+  for (const [cwd, p] of byCwd) resolved.set(cwd, await p);
+  return (j) => (j && resolved.get(j.cwd || DEFAULT_PROJECT_CWD)) || null;
+}
+
+function selectMechanicalRecoveryTarget(job, currentHeadSha = null) {
   if (process.env.SM_MECHANICAL_RECOVERY_DISABLE === '1') return null;
   if (!job || job.status !== 'needs_review') return null;
   if (!MECHANICALLY_RESOLVABLE_VERDICTS.has(job.verifierVerdict)) return null;
   if (job.mechanicalRecoveryAttempted === true) return null;
+  if (isMechanicalRecoveryFutile(job, currentHeadSha)) return null;
   const cwd = job.cwd || DEFAULT_PROJECT_CWD;
   return { slug: job.slug, cwd, branch: jobWorktree.branchNameFor(job.slug), carriedPaths: job.carriedPaths || [] };
 }
@@ -6044,7 +6107,7 @@ async function spawnInvestigation(failedJob, runDir, { deadChild = null } = {})
   // Mechanical recovery (PRD 1130): same first-refusal treatment — a job
   // eligible for a pure-git retry must never also get a cold-read fix-plan
   // PRD authored in the same pass.
-  if (selectMechanicalRecoveryTarget(failedJob)) {
+  if (selectMechanicalRecoveryTarget(failedJob, failedJob.integrationFailureKind === 'content_conflict' ? await gitHead(failedJob.cwd || DEFAULT_PROJECT_CWD) : null)) {
     console.log(`[scheduler] skip investigation: ${failedJob.slug} is mechanical-recovery eligible`);
     return { deferred: false };
   }
@@ -6859,6 +6922,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     let res;
     let worktreeLeftoverDirty = [];
     let worktreeIntegrationFailure = null;
+    let worktreeIntegrationDetail = null;
     // Set only when integrateJobBranch's stderr-parsing auto-resolve fired
     // (PRD 1125) — surfaced on the job row so the Queue UI can say the merge
     // self-healed rather than silently looking like an ordinary merge.
@@ -6919,6 +6983,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
         }
         if (!integration.ok) {
           worktreeIntegrationFailure = integration.reason;
+          worktreeIntegrationDetail = integration;
           console.error(`[scheduler] ${job.slug}: worktree branch integration FAILED (${integration.reason}) — branch ${worktree.branch} preserved in ${guardCwd} for manual recovery`);
         } else if (integration.integrated) {
           console.log(`[scheduler] ${job.slug}: worktree branch ${worktree.branch} integrated into ${guardCwd}${integration.mergeCommit ? ' (merge commit)' : ' (fast-forward)'}`);
@@ -7117,6 +7182,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
         priorLandedCommit,
         jobLandedCommitThisRun,
         exitCode: res.exitCode,
+        worktreeDir: worktree.ok ? worktree.dir : null,
       }).catch((e) => ({
         verdict: 'verify_unavailable',
         reason: `verifier threw: ${e?.message ?? String(e)}`,
@@ -7151,7 +7217,8 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     // annotation, so a real "finish protocol incomplete" is distinguishable from
     // transcript noise in the queue (feedback 2026-06-10 addendum).
     const guardWillRefire = verifyResult && verifyResult.downgradeTo === 'pending';
-    const guardIsLegitimateNoOp = verifyResult && COMPLETED_EQUIVALENT_VERDICTS.has(verifyResult.verdict);
+    const guardArtifactVerified = verifyResult?.verdict === 'pass_no_commit_artifact_verified';
+    const guardIsLegitimateNoOp = verifyResult && !guardArtifactVerified && COMPLETED_EQUIVALENT_VERDICTS.has(verifyResult.verdict);
     if (res.exitCode === 0 && !res.rateLimited && !guardWillRefire && !guardIsLegitimateNoOp) {
       // afterGuardCwd === null means non-git cwd (or git errored) —
       // best-effort skip, same as always; only a git-status result (even an
@@ -7172,6 +7239,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
           jobSelfCommitted,
           legitimateNoOp: guardIsLegitimateNoOp,
           isFixPlanJob: resolveIsFixPlan(job.slug, job.isFixPlan),
+          artifactVerified: guardArtifactVerified,
           verifyResult,
           salvagePatch,
         });
@@ -7205,7 +7273,9 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     if (worktreeIntegrationFailure) {
       verifyResult = {
         verdict: 'worktree_integration_failed',
-        reason: `worktree branch integration failed: ${worktreeIntegrationFailure} — branch preserved for manual merge`,
+        reason: worktreeIntegrationDetail && worktreeIntegrationDetail.failureKind === 'content_conflict'
+          ? `Integration blocked by a content conflict in ${(worktreeIntegrationDetail.conflictedPaths || []).join(', ') || 'unknown paths'} — branch ${jobWorktree.branchNameFor(job.slug)} preserved; needs a manual merge.`
+          : `worktree branch integration failed: ${worktreeIntegrationFailure} — branch preserved for manual merge`,
         downgradeTo: 'needs_review',
       };
     }
@@ -7320,6 +7390,9 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     let mechanicalRecoveryTarget = null;
     let terminalNotifySnapshot = null;
     const newlyCompletedPrds = [];
+    // Base HEAD for the mechanical-recovery futility check — read here, never inside mutate() (no I/O).
+    const finalizeHeadSha = worktreeIntegrationDetail && worktreeIntegrationDetail.failureKind === 'content_conflict'
+      ? await gitHead(guardCwd) : null;
     await mutate((s) => {
       const i2 = s.jobs.findIndex((x) => x.slug === job.slug);
       // A job already moved off 'running' by someone else (namely
@@ -7511,6 +7584,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
           } else if (!['blocked_by_foreign_wip_streak', 'budget_exceeded'].includes(s.jobs[i2].verifierVerdict)) {
             delete s.jobs[i2].verifierVerdict;
           }
+          stampIntegrationFailure(s.jobs[i2], worktreeIntegrationFailure ? worktreeIntegrationDetail : null);
           transitionJob(s.jobs[i2], effectiveStatus, { reason: finalizeReason, source: 'spawnJob:finalize' });
           s.jobs[i2].finishedAt = new Date().toISOString();
           s.jobs[i2].exitCode = res.exitCode;
@@ -7620,7 +7694,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
             // depth-cap check, so it must never fall through to either.
             // Snapshot only (no I/O inside mutate()); the actual git retry
             // happens outside mutate(), below.
-            const mTarget = selectMechanicalRecoveryTarget(s.jobs[i2]);
+            const mTarget = selectMechanicalRecoveryTarget(s.jobs[i2], finalizeHeadSha);
             if (mTarget) {
               mechanicalRecoveryJob = { ...s.jobs[i2] };
               mechanicalRecoveryTarget = mTarget;
@@ -10828,9 +10902,17 @@ async function reverifyNeedsReview() {
   // check in spawnJob missed because the app restarted in between). Depth
   // never disqualifies it, so it runs regardless of investigationDepth.
   {
+    const headFor = await resolveHeadShasForPass(queueForResumeAndAutofix.jobs);
     for (const job of queueForResumeAndAutofix.jobs) {
-      const target = selectMechanicalRecoveryTarget(job);
-      if (!target) continue;
+      const head = headFor(job);
+      const target = selectMechanicalRecoveryTarget(job, head);
+      if (!target) {
+        if (job.status === 'needs_review' && job.mechanicalRecoveryAttempted !== true
+          && MECHANICALLY_RESOLVABLE_VERDICTS.has(job.verifierVerdict) && isMechanicalRecoveryFutile(job, head)) {
+          console.log(`[scheduler] mechanical-recovery: skip ${job.slug} — content conflict, base HEAD unchanged since failure`);
+        }
+        continue;
+      }
       console.log(`[scheduler] mechanical-recovery: needs_review ${job.slug} → re-integrating ${target.branch}`);
       performMechanicalRecovery(job, target).catch((e) => {
         console.error('[scheduler] performMechanicalRecovery error', job.slug, e);
@@ -10984,6 +11066,9 @@ function registerScheduleHandlers() {
   // configuration tab.
   ipcMain.handle('schedule:session-slots', () => sessionSlots.snapshot());
 
+  // Read-only: where Epic/job git worktrees (and so their CLI transcript encodings) live.
+  ipcMain.handle('schedule:worktree-base', () => require('./lib/schedulerPaths.cjs').worktreeBase());
+
   // Home-tab control for the same pool: user-set cap in [0, 10], default 5.
   // 0 pauses new claude -p launches machine-wide without killing anything
   // already running. SM_SESSION_SLOTS (if set) still overrides this at read
@@ -12598,6 +12683,9 @@ module.exports = {
   buildClaudeSpawnArgs,
   spawnResumeRecovery,
   selectMechanicalRecoveryTarget,
+  isMechanicalRecoveryFutile,
+  resolveHeadShasForPass,
+  stampIntegrationFailure,
   performMechanicalRecovery,
   MECHANICALLY_RESOLVABLE_VERDICTS,
   selectLeftoverQuarantineTarget,

package/src/main/templates/PRD_AUTHORING.md

@@ -141,6 +141,17 @@ estimateMinutes: 60
 - `estimateMinutes` is used for ETA display; include a realistic estimate (note: empirical median is ~10 min, p90 ~20 min — avoid wildly inflated estimates that hide real outliers).
 - `parallelGroup` in frontmatter, when present, IS honored by the scheduler (`pickNextBatch` reads `parallelGroup ?? 99` and overrides the filename NN). Use this only for cross-stream interleaving — e.g., the cellar series `122-`, `123-`, `124-` overrides to groups `113`, `114`, `115` so cellar steps fire alongside the parallel etch steps. Do NOT use it to reorder within a single stream; rename the file instead.
 
+### Artifact-only PRDs
+
+Use `deliverable: artifact` + `artifactPaths: [a, b]` (both passed to `scheduler_create_prd`) ONLY when every deliverable is a file the target repo deliberately git-excludes (e.g. patches/notes under `session-manager-operations/review-records/`, matched by `.git/info/exclude`), so "no commit" is the correct outcome.
+
+- Every artifact path must be named in `artifactPaths`; an unlisted file is invisible to the verifier. Each path is relative, never contains `..`.
+- The artifact must be non-empty and written during the run window — the verifier stat-checks it on disk (verdict `pass_no_commit_artifact_verified`; window = start−60s..finish+120s).
+- The run must still leave the working tree clean — declaring artifacts excuses the missing commit, not stray tracked edits. The commit guard enforces this: the `pass_no_commit_artifact_verified` verdict stands the guard down only when nothing tracked was left dirty; any uncommitted tracked change still parks as `uncommitted_changes`.
+- Both fields are required together: the write is refused if only one is given.
+
+Incident: sigma PRD `816-prepare-157-copy-citation-extras-patch` (2026-09-20) wrote its patch into a git-excluded folder; with no way to declare that, two runs both parked in `needs_review`.
+
 ---
 
 ## §7 Self-containment

package/src/main/transcripts.cjs

@@ -38,9 +38,22 @@ function attachWindow(w) {
 
 const { encodeCwd } = require('./lib/encodeCwd.cjs');
 const { classifyLine } = require('./lib/classifyTranscriptLine.cjs');
+const { resolveEpicTranscriptPath } = require('./lib/epicTranscriptPath.cjs');
+
+/**
+ * Where the CLI's JSONL for this session lives. Epic sessions run in a
+ * worktree, so the resolver checks the worktree encoding as well as the
+ * project one; a non-Epic tab resolves to the plain project-encoded path.
+ * Sync + absolute always (falls back to the plain path on invalid input).
+ */
+function resolveTranscript(cwd, sessionUuid) {
+  const r = resolveEpicTranscriptPath({ cwd, claudeSessionId: sessionUuid });
+  const filePath = r.path || path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd), `${sessionUuid}.jsonl`);
+  return { filePath, existsAnywhere: !!r.existsAnywhere };
+}
 
 function transcriptPath(cwd, sessionUuid) {
-  return path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd), `${sessionUuid}.jsonl`);
+  return resolveTranscript(cwd, sessionUuid).filePath;
 }
 
 // Cap bytes read per readDelta pass. Bounds memory on first attach to a very
@@ -191,8 +204,11 @@ async function readPage(sub, startLine, endLine) {
   const from = Math.max(0, Math.min(startLine, total - 1));
   const to = Math.max(0, Math.min(endLine, total - 1));
   if (total === 0 || from > to) return { events: [], totalLines: total };
-  const first = sub.lineIndex[from];
-  const last = sub.lineIndex[to];
+  // Snapshot the entries synchronously: the awaits below can interleave with a
+  // rotation/truncation rebuild that shrinks sub.lineIndex, so never re-index it after.
+  const entries = sub.lineIndex.slice(from, to + 1);
+  const first = entries[0];
+  const last = entries[entries.length - 1];
   const spanOffset = first.byteOffset;
   const spanLength = last.byteOffset + last.byteLength - spanOffset;
   const events = [];
@@ -202,7 +218,7 @@ async function readPage(sub, startLine, endLine) {
     const buf = Buffer.alloc(spanLength);
     await fd.read(buf, 0, spanLength, spanOffset);
     for (let lineNo = from; lineNo <= to; lineNo++) {
-      const entry = sub.lineIndex[lineNo];
+      const entry = entries[lineNo - from];
       const relOffset = entry.byteOffset - spanOffset;
       const text = buf.toString('utf8', relOffset, relOffset + entry.byteLength);
       let obj;
@@ -361,9 +377,14 @@ async function subscribe({ tabId, cwd, sessionUuid }) {
     });
     return { ok: false, path: null, error: 'too many active subscriptions' };
   }
-  const filePath = transcriptPath(cwd, sessionUuid);
-  const dir = path.dirname(filePath);
-  await fsp.mkdir(dir, { recursive: true }).catch(() => {});
+  // Known limitation: filePath is latched here and never re-resolved. Fine
+  // because nothing relocates a transcript under an open subscription.
+  const { filePath, existsAnywhere } = resolveTranscript(cwd, sessionUuid);
+  // Only create the dir when no transcript exists anywhere (it is the dir the
+  // CLI is about to write); otherwise we'd mint empty project dirs it never made.
+  if (!existsAnywhere) {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true }).catch(() => {});
+  }
   const sub = {
     tabId,
     cwd,

package/src/preload/api.d.ts

@@ -1780,6 +1780,8 @@ export interface SessionManagerAPI {
       total: number; inUse: number; holders: { owner: string; at: string }[];
       min: number; max: number; default: number; envOverride: boolean;
     }>;
+    /** Resolved base dir of managed Epic/job worktrees (SM_WORKTREE_ROOT, else the persistent per-user state dir). */
+    worktreeBase: () => Promise<string>;
     /** Set the slot pool's user cap (Home tab), [0, 10]; 0 pauses new launches. Ignored if SM_SESSION_SLOTS is set. */
     setSessionSlots: (cap: number) => Promise<{
       total: number; inUse: number; holders: { owner: string; at: string }[];

package/src/preload/index.cjs

@@ -231,6 +231,7 @@ contextBridge.exposeInMainWorld('api', {
   schedule: {
     state: () => ipcRenderer.invoke('schedule:state'),
     sessionSlots: () => ipcRenderer.invoke('schedule:session-slots'),
+    worktreeBase: () => ipcRenderer.invoke('schedule:worktree-base'),
     setSessionSlots: (cap) => ipcRenderer.invoke('schedule:set-session-slots', { cap }),
     setConfig: (partial) => ipcRenderer.invoke('schedule:set-config', partial),
     resetJob: (slug) => ipcRenderer.invoke('schedule:reset-job', { slug }),

package/dist/assets/DataModel-CY_mMnsr.js

@@ -1 +0,0 @@
-import{al as d,f as j,ab as $,U as g,aa as e,j as N,V as E,ad as S,W as b,an as T,b as p,I as D,g as v,E as R}from"./index-Dp4Rc--q.js";import{P as V}from"./Panel-I1s6ghPo.js";import"./monaco-editor-BW5C4Iv1.js";const C=[{key:"diagram",label:"Diagram"},{key:"tables",label:"Tables"}];function G(){const[s,t]=d.useState("diagram"),[a,i]=d.useState(null),[l,n]=d.useState(()=>new Set),c=d.useMemo(()=>j.filter(r=>!l.has(r.group)),[l]),m=d.useMemo(()=>$(c),[c]),o=r=>{n(x=>{const h=new Set(x);return h.has(r)?h.delete(r):h.add(r),h}),i(null)},u=a?g(a):null,y=r=>c.some(x=>x.id===r);return e.jsx(V,{toolbar:e.jsxs(e.Fragment,{children:[e.jsx(E,{options:C,active:s,onChange:t}),e.jsx(M,{hiddenGroups:l,onToggle:o}),e.jsxs("span",{className:"ml-auto text-fg-faint",children:[j.length," entities"]})]}),children:s==="diagram"?e.jsxs("div",{className:"h-full flex",children:[e.jsx("div",{className:"flex-1 min-w-0 overflow-auto",children:e.jsx(O,{layout:m,selectedId:a,onSelect:r=>i(x=>x===r?null:r)})}),e.jsx("div",{className:"w-96 shrink-0 border-l border-line overflow-y-auto",children:u?e.jsx(F,{entity:u,onSelectRelated:r=>y(r)?i(r):void 0}):e.jsx(N,{title:"select an entity",hint:"click a box in the diagram to see its storage, fields, and relations"})})]}):e.jsx(P,{})})}const L=d.memo(G);function M({hiddenGroups:s,onToggle:t}){return e.jsx("div",{className:"flex items-center gap-1.5 flex-wrap",children:v.map(a=>{const i=s.has(a.id);return e.jsxs("button",{onClick:()=>t(a.id),title:`${a.blurb} (${a.realm})`,className:`flex items-center gap-1 px-1.5 py-0.5 rounded border text-[10.5px] ${i?"border-line text-fg-faint opacity-50":"border-line text-fg-dim hover:text-fg"}`,children:[e.jsx("span",{className:`w-1.5 h-1.5 rounded-full ${a.tone.dot}`}),a.label,e.jsx("span",{className:"text-fg-faint",children:a.realm})]},a.id)})})}function O({layout:s,selectedId:t,onSelect:a}){const i=d.useMemo(()=>t?new Set(S(t)):null,[t]),l=n=>!!t&&(n.relation.from===t||n.relation.to===t);return s.boxes.length===0?e.jsx(N,{title:"no entities in view",hint:"toggle a group in the legend to show its entities"}):e.jsxs("div",{className:"relative p-4",style:{width:s.width+32,height:s.height+32},children:[e.jsxs("svg",{width:s.width,height:s.height,className:"absolute left-4 top-4 overflow-visible",children:[s.edges.map(n=>{const c=l(n);return e.jsx("path",{"data-testid":`erd-edge-${n.relation.from}-${n.relation.to}`,d:n.d,fill:"none",className:c?"stroke-accent":"stroke-line",strokeWidth:c?2:1,opacity:t&&!c?.25:1},`${n.relation.from}-${n.relation.to}-${n.relation.label}`)}),s.edges.map(n=>l(n)?e.jsx("text",{x:n.mx,y:n.my,textAnchor:"middle",className:"fill-fg-dim text-[10px]",children:n.relation.label},`label-${n.relation.from}-${n.relation.to}-${n.relation.label}`):null)]}),s.boxes.map(n=>e.jsx(_,{box:n,selected:n.id===t,dimmed:!!t&&n.id!==t&&!(i!=null&&i.has(n.id)),onClick:()=>a(n.id)},n.id))]})}function _({box:s,selected:t,dimmed:a,onClick:i}){const l=g(s.id),n=b(s.group),c=l.fields.slice(0,R),m=l.fields.length-c.length;return e.jsxs("button",{type:"button","data-testid":`erd-box-${s.id}`,onClick:i,className:`absolute text-left rounded border overflow-hidden bg-bg-hi ${t?"border-accent ring-1 ring-accent":"border-line"} ${a?"opacity-30":""}`,style:{left:s.x,top:s.y,width:s.w,height:s.h},children:[e.jsxs("div",{className:"px-2 py-1 border-b border-line flex items-center gap-1.5",children:[e.jsx("span",{className:`w-1.5 h-1.5 rounded-full shrink-0 ${n.tone.dot}`}),e.jsx("span",{className:"text-[11px] font-semibold text-fg truncate",children:l.name})]}),l.aka&&e.jsx("div",{className:"px-2 pt-0.5 text-[9.5px] text-fg-faint truncate",children:l.aka}),e.jsxs("div",{className:"px-2 py-0.5",children:[c.map(o=>e.jsxs("div",{className:"text-[9.5px] font-mono text-fg-dim truncate flex items-center gap-1",children:[o.key&&e.jsx("span",{className:"text-fg-faint",children:o.key}),e.jsx("span",{className:"truncate",children:o.name})]},o.name)),m>0&&e.jsxs("div",{className:"text-[9.5px] text-fg-faint italic",children:["+",m," more"]})]})]})}function w({fields:s}){return e.jsxs("table",{className:"w-full text-[11px] font-mono",children:[e.jsx("thead",{className:"text-fg-faint uppercase tracking-wide text-[9.5px]",children:e.jsxs("tr",{className:"border-b border-line",children:[e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"name"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"type"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"key"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"note"})]})}),e.jsx("tbody",{children:s.map(t=>e.jsxs("tr",{className:"border-b border-line/50",children:[e.jsxs("td",{className:"px-2 py-1 text-fg",children:[t.name,t.optional&&e.jsx("span",{className:"text-fg-faint",children:"?"})]}),e.jsx("td",{className:"px-2 py-1 text-fg-dim",children:t.type}),e.jsx("td",{className:"px-2 py-1",children:t.key&&e.jsxs(p,{tone:t.key==="pk"?"accent":"dim",children:[t.key,t.ref?` → ${t.ref}`:""]})}),e.jsx("td",{className:"px-2 py-1 text-fg-faint",children:t.note})]},t.name))})]})}function k({entity:s}){return e.jsxs("div",{className:"space-y-1 text-[11px]",children:[e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"path"}),e.jsx("span",{className:"font-mono text-fg-dim break-all",children:s.store.path})]}),e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"format"}),e.jsx("span",{className:"font-mono text-fg-dim",children:s.store.format})]}),s.store.writer&&e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"writer"}),e.jsxs(p,{tone:"accent",children:["single-writer: ",s.store.writer]})]}),e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"definedIn"}),e.jsx("span",{className:"font-mono text-fg-dim break-all",children:s.store.definedIn})]})]})}function F({entity:s,onSelectRelated:t}){const a=b(s.group),i=T(s.id);return e.jsxs("div",{className:"p-3 space-y-3",children:[e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:`w-2 h-2 rounded-full ${a.tone.dot}`}),e.jsx("span",{className:"text-sm font-semibold text-fg",children:s.name})]}),s.aka&&e.jsx("div",{className:"text-[10.5px] text-fg-faint",children:s.aka}),e.jsx(p,{tone:"dim",className:"mt-1",children:a.label})]}),e.jsx("div",{className:"text-xs text-fg-dim leading-relaxed",children:s.summary}),e.jsxs("div",{children:[e.jsx(f,{children:"storage"}),e.jsx(k,{entity:s})]}),e.jsxs("div",{children:[e.jsx(f,{children:"fields"}),e.jsx(w,{fields:s.fields})]}),s.notes&&s.notes.length>0&&e.jsxs("div",{children:[e.jsx(f,{children:"notes"}),e.jsx("ul",{className:"list-disc pl-4 space-y-0.5 text-xs text-fg-dim",children:s.notes.map(l=>e.jsx("li",{children:l},l))})]}),e.jsxs("div",{children:[e.jsx(f,{children:"relations"}),i.length===0?e.jsx("div",{className:"text-xs text-fg-faint italic",children:"no relations"}):e.jsx("ul",{className:"space-y-1",children:i.map(l=>{const n=l.from===s.id?l.to:l.from,c=g(n);return e.jsxs("li",{className:"flex items-center gap-1.5 text-xs",children:[e.jsx("span",{className:"font-mono text-fg-faint w-10 shrink-0",children:D(l.cardinality)}),e.jsx("span",{className:"text-fg-dim",children:l.label}),l.via&&e.jsxs("span",{className:"font-mono text-[10px] text-fg-faint",children:["via ",l.via]}),e.jsx("button",{type:"button",onClick:()=>t(n),className:"ml-auto text-accent hover:underline font-mono",children:c.name})]},`${l.from}-${l.to}-${l.label}`)})})]})]})}function f({children:s}){return e.jsx("div",{className:"text-[10.5px] uppercase tracking-wide text-fg-faint mb-1 font-mono",children:s})}function P(){return e.jsx("div",{className:"p-4 space-y-6",children:v.map(s=>{const t=j.filter(a=>a.group===s.id);return t.length===0?null:e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-1.5 mb-2",children:[e.jsx("span",{className:`w-2 h-2 rounded-full ${s.tone.dot}`}),e.jsx("span",{className:"text-xs font-semibold text-fg",children:s.label}),e.jsx("span",{className:"text-[10.5px] text-fg-faint",children:s.realm})]}),e.jsx("div",{className:"grid grid-cols-1 xl:grid-cols-2 gap-3",children:t.map(a=>e.jsxs("div",{className:"border border-line rounded bg-bg-hi p-3 space-y-2",children:[e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsx("span",{className:"text-sm font-semibold text-fg",children:a.name}),a.aka&&e.jsx("span",{className:"text-[10.5px] text-fg-faint",children:a.aka})]}),e.jsx(p,{tone:"dim",className:"mt-1",children:s.label})]}),e.jsx("div",{className:"text-xs text-fg-dim leading-relaxed",children:a.summary}),e.jsx(k,{entity:a}),e.jsx(w,{fields:a.fields}),a.notes&&a.notes.length>0&&e.jsx("ul",{className:"list-disc pl-4 space-y-0.5 text-xs text-fg-dim",children:a.notes.map(i=>e.jsx("li",{children:i},i))})]},a.id))})]},s.id)})})}export{L as DataModel};

package/dist/assets/MarkdownEditor-HPoNeKhT.js

@@ -1 +0,0 @@
-import{aa as i,F as r}from"./index-Dp4Rc--q.js";function l({value:e,onChange:a,path:n,readOnly:o}){return i.jsx(r,{path:`file://${n}`,defaultLanguage:"markdown",value:e,onChange:t=>a(t??""),theme:"vs-dark",options:{minimap:{enabled:!1},fontSize:13,fontFamily:"JetBrains Mono, ui-monospace, Menlo, monospace",lineNumbers:"on",renderLineHighlight:"line",scrollBeyondLastLine:!1,tabSize:2,wordWrap:"on",readOnly:o,automaticLayout:!0}})}export{l as M};