claude-code-session-manager 0.122.1 → 0.123.1

package/src/main/runVerify.cjs

@@ -21,7 +21,8 @@
  *
  * Downgrade policy:
  *   clean           → null        (caller stamps 'completed')
- *   halt            → 'pending'   (re-fires automatically next slot)
+ *   halt            → 'pending'   (re-fires automatically next slot; only for
+ *                                  a run that printed no SCHEDULER_VERDICT line)
  *   deps_unmet      → 'pending'   (re-fires when deps clear)
  *   transcript_errors → historical rows only; no longer emitted
  *   verify_unavailable → 'needs_review' (unreadable log / verifier threw)
@@ -297,6 +298,30 @@ function scanSentinel(resultEvent, events) {
   return null;
 }
 
+/**
+ * First line that starts at column 0 with the exact uppercase halt marker
+ * (`HALT:`) outside a fenced block, else null. Line-anchored and fence-aware
+ * because reports quote the marker in prose and paste tool output in fences,
+ * and PRD_AUTHORING.md §4/§9/§10 tell scripts to print it on failure — neither
+ * is the executor's own stop signal.
+ * @param {unknown} text
+ * @returns {string | null}
+ */
+function scanHaltLine(text) {
+  if (typeof text !== 'string') return null;
+  let inFence = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\r$/, '').trimEnd();
+    const t = line.trimStart();
+    if (t.startsWith('```') || t.startsWith('~~~')) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && line.startsWith('HALT:')) return line;
+  }
+  return null;
+}
+
 /**
  * One-line reason after `SCHEDULER_VERDICT: FAIL` (same two-source scan order
  * as scanSentinel). Trimmed, capped at 300 chars; '' when absent.
@@ -742,13 +767,17 @@ async function verifyRun({
       else if (commitEvidence) commitEvidenceSource = 'transcript';
     }
 
-    // ── 3. HALT detection ─────────────────────────────────────────────────
-    // Primary: check the final `{"type":"result"}` event's `result` text.
-    if (resultEvent) {
-      const rt = resultEvent.resultText;
-      if (/\bHALT:/i.test(rt) || /^HALT\b/m.test(rt)) {
-        const firstLine = rt.split('\n')[0].slice(0, 200);
-        let reason = `Agent HALTed: ${firstLine}`;
+    // ── 3. HALT detection (fallback only) ─────────────────────────────────
+    // The SCHEDULER_VERDICT line is the executor's final say (FINISH_PROTOCOL
+    // VERDICT LINE step); the halt check is a fallback for runs that printed
+    // none. Incident: Rabbits-Game 163-attack-scorecard, 2026-10-24 — a PASS
+    // report quoting the marker in backticks was re-queued as a halt.
+    const sentinel = scanSentinel(resultEvent, events);
+    if (resultEvent && sentinel === null) {
+      const haltLine = scanHaltLine(resultEvent.resultText);
+      if (haltLine) {
+        const rt = resultEvent.resultText;
+        let reason = `Agent HALTed: ${haltLine.slice(0, 200)}`;
         // Embed machine-parseable floor date if present in HALT message.
         const dateMatch = rt.match(/~?(\d{4}-\d{2}-\d{2})/);
         if (dateMatch) reason += ` (eligible from: ${dateMatch[1]})`;
@@ -773,9 +802,6 @@ async function verifyRun({
       }
     }
 
-    // Scan for the SCHEDULER_VERDICT sentinel emitted by the finish protocol.
-    const sentinel = scanSentinel(resultEvent, events);
-
     // An explicit executor FAIL is always blocking — outranks every other
     // verdict and every override below (early return). Transcript issues are
     // kept as annotations so nothing is lost.
@@ -1022,6 +1048,7 @@ module.exports = {
   checkDeps,
   parseLog,
   scanSentinel,
+  scanHaltLine,
   scanSentinelReason,
   scanHumanQuestion,
   scanForeignWipPathsClaim,

package/src/main/scheduler/prdParser.cjs

@@ -19,6 +19,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { splitFrontmatter } = require('../lib/prd/prdFrontmatter.cjs');
 const { deriveEpicIdFromPrdPath } = require('../lib/prd/prdLocations.cjs');
+const { parseFilesSection } = require('../lib/prd/prdGateFiles.cjs');
 const { reportDanglingAgentTypeOnce } = require('../lib/prd/prdAgentType.cjs');
 
 /**
@@ -100,6 +101,8 @@ async function parsePrdRaw(filePath) {
     // queue row is completed (a slug with no row is treated as already
     // done/archived, matching retireCompletedSlugs semantics).
     dependsOn: parseDependsOn(fm.dependsOn),
+    // Declared touch-list from the body's `# Files` section ([] when absent).
+    files: parseFilesSection(body),
     // Provenance stamp (PRD-authoring lockdown): set only by prdCreate.cjs's
     // buildPrdBody (create) or the update-prd route's legacy-adopt patch
     // (migration/manual adopt). A PRD discovered on disk with no value here

package/src/main/scheduler/prdPaths.cjs

@@ -16,6 +16,7 @@ const { DEFAULT_PROJECT_CWD } = require('../lib/scheduler/schedulerBatch.cjs');
 const { resolvePrdsDirs, resolveArchivedPrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, resolveEpicPrdWriteDir, isSafeEpicId, listArchivedPrdDirs, ancestorEpicPrdDirs, ancestorEpicArchivedPrdDirs } = require('../lib/prd/prdLocations.cjs');
 const { migratePrds, consolidateFlatPrds, legacyAdoptExistingPrds } = require('../lib/prd/prdMigration.cjs');
 const { opsPath } = require('../lib/opsOwnership.cjs');
+const { bareSlug, resolveDepSlug } = require('../lib/prd/depSlugResolve.cjs');
 const { allProjectCwds, projectRootOf } = require('../lib/activeSessions.cjs');
 
 /**
@@ -268,6 +269,50 @@ async function safeSlugPath(slug) {
   return module.exports.safeSlugPathIn(dir, slug);
 }
 
+/**
+ * Resolve a BARE slug (no `NN-` prefix) to the unique NN-prefixed PRD file —
+ * for a caller whose create response was lost and never learned the NN.
+ * Scans the live PRD dirs, the archive dirs, and one level of
+ * `prds-archived/<ts>/`, matching with depSlugResolve's rule. `cwd` narrows to
+ * one project; omitted, it searches every candidate dir. Returns
+ * `{ ok: true, path, dir }`, `{ ok: false, reason: 'not-found' }`, or
+ * `{ ok: false, reason: 'ambiguous', files, error }` (never guesses).
+ */
+async function resolveBareSlugFile(slug, cwd) {
+  if (typeof slug !== 'string' || !slug || bareSlug(slug) !== slug) return { ok: false, reason: 'not-found' };
+  const live = cwd ? [module.exports.prdDirForCwd(cwd), ...listEpicPrdDirs(cwd)] : module.exports.candidatePrdsDirs();
+  const archived = cwd ? listArchivedPrdDirs(cwd) : module.exports.candidateArchivedPrdsDirs();
+  const dirs = [...live];
+  for (const a of archived) {
+    dirs.push(a);
+    const subs = await fsp.readdir(a, { withFileTypes: true }).catch(() => []);
+    for (const ent of subs) if (ent.isDirectory()) dirs.push(path.join(a, ent.name));
+  }
+  const found = []; // { slug, dir, file }
+  const seen = new Set();
+  for (const dir of dirs) {
+    const names = await fsp.readdir(dir).catch(() => []);
+    for (const n of names) {
+      if (!n.endsWith('.md')) continue;
+      const file = path.join(dir, n);
+      if (seen.has(file)) continue;
+      seen.add(file);
+      found.push({ slug: n.slice(0, -3), dir, file });
+    }
+  }
+  const matched = new Set(resolveDepSlug(slug, found.map((f) => f.slug)));
+  const hits = found.filter((f) => matched.has(f.slug));
+  if (hits.length === 0) return { ok: false, reason: 'not-found' };
+  if (hits.length > 1) {
+    const files = hits.map((h) => h.file);
+    return { ok: false, reason: 'ambiguous', files, error: `ambiguous slug "${slug}": matches ${files.join(' and ')} — use the full NN-prefixed slug` };
+  }
+  const only = hits[0];
+  const safe = module.exports.safeSlugPathIn(only.dir, only.slug);
+  if (!safe) return { ok: false, reason: 'not-found' };
+  return { ok: true, path: safe, dir: only.dir };
+}
+
 /**
  * The two distinct failure modes safeSlugPath collapses into one nullable
  * return (the defect this fixes — see the PRD that added this helper's
@@ -291,10 +336,10 @@ async function resolveSlugOrReason(slug, cwd) {
         return { ok: true, path: p };
       } catch { /* not in this dir — try the next candidate */ }
     }
-    return { ok: false, reason: 'not-found' };
+    return module.exports.resolveBareSlugFile(slug, cwd);
   }
   const dir = await module.exports.findPrdDir(slug);
-  if (!dir) return { ok: false, reason: 'not-found' };
+  if (!dir) return module.exports.resolveBareSlugFile(slug, cwd);
   const p = module.exports.safeSlugPathIn(dir, slug);
   if (!p) return { ok: false, reason: 'not-found' };
   return { ok: true, path: p };
@@ -522,6 +567,7 @@ module.exports = {
   safeSlugPathIn,
   realPrdsDir,
   safeSlugPath,
+  resolveBareSlugFile,
   resolveSlugOrReason,
   jobMatchesSlugAndCwd,
   unknownSlugMessage,

package/src/main/scheduler.cjs

@@ -82,6 +82,7 @@ const { detectRateLimitInLog } = require('./lib/claude/rateLimitDetect.cjs');
 const { stripAppOwnedChurn } = require('./lib/scheduler/jobDirtFilter.cjs');
 const { GATE_AUTHORITY_VERDICTS, decideGateAuthority } = require('./lib/scheduler/gateAuthority.cjs');
 const { decideBaselineAuthority } = require('./lib/scheduler/baselineGate.cjs');
+const { formatSetupOutcome: formatWorktreeSetupOutcome, isSetupSettled: isWorktreeSetupSettled } = require('./lib/git/worktreeSetup.cjs');
 const { linkDependencyDirs } = require('./lib/git/worktreeDeps.cjs');
 const { checkMainDependencyHealth, repairMainDependencies } = require('./lib/git/depHealth.cjs');
 // cwd -> last main-checkout dependency repair attempt (ms); caps repair to once per cooldown.
@@ -107,6 +108,8 @@ const { appendResponseEventIfKnown, appendResponseEventWithReason } = require('.
 const { buildReviewNotice, selectDueReviewNotices, formatReviewNotice, holdMsFromEnv } = require('./lib/scheduler/reviewNotice.cjs');
 const epicValidationHook = require('./lib/epic/epicValidationHook.cjs');
 const prdCreate = require('./lib/prd/prdCreate.cjs');
+const { resolveProjectContext } = require('./lib/projectRootResolve.cjs');
+const { expandHome } = require('./lib/util/expandHome.cjs');
 const { parseValidationSentinels } = require('./lib/scheduler/validationSentinels.cjs');
 const { hasDownstreamValidator } = require('./lib/prd/planValidator.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
@@ -187,6 +190,8 @@ const queueStore = require('./lib/scheduler/queueStore.cjs');
 const supervisorRecord = require('./lib/scheduler/jobSupervisorRecord.cjs');
 const adoptedRunSupervisor = require('./lib/scheduler/adoptedRunSupervisor.cjs');
 const { splitFrontmatter, parsePrdFile, serializePrdFile } = require('./lib/prd/prdFrontmatter.cjs');
+const { applyStructuredPrdPatch } = require('./lib/prd/prdBodyPatch.cjs');
+const { resolvePersonaDefaultEstimate, DEFAULT_PRD_AGENT_TYPE } = require('./lib/prd/prdAgentType.cjs');
 const { resolveDepSlug, findNearMatches } = require('./lib/prd/depSlugResolve.cjs');
 const { computeDispositionRewrite, mintPlanId, resolveInheritedPlanId } = require('./lib/prd/prdDisposition.cjs');
 const { allProjectCwds } = require('./lib/activeSessions.cjs');
@@ -539,7 +544,7 @@ function biasJobOomScore(pid) {
 async function recheckPrdSourceForJob(job) {
   const slug = job && job.slug;
   if (typeof slug !== 'string' || !slug || path.basename(slug) !== slug) return null;
-  try { require('./lib/activeSessions.cjs').bustProjectCwdCache(); } catch { /* best-effort */ }
+  try { require('./lib/activeSessions.cjs').bustProjectCwdCache({ deep: true }); } catch { /* best-effort */ }
   const dirs = [...(await prdPaths.jobScopedPrdDirs(job))];
   const found = await prdPaths.findPrdDirForJob(job);
   if (found) dirs.push(found);
@@ -563,7 +568,7 @@ async function recheckPrdSourceForJob(job) {
  *     fixture that leaked into the live queue and was cleaned up by its own
  *     `finally` block). Retire the row rather than fail it.
  */
-function prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, reason = 'prd-archived') {
+function prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, reason = 'prd-archived', extraMeta = {}) {
   const msg = reason === 'prd-missing'
     ? 'PRD source no longer exists on disk — retiring stale queue entry'
     : (() => {
@@ -575,7 +580,7 @@ function prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd,
   const finishedAt = Date.now();
   config.writeJsonSync(metaPath, {
     slug: job.slug, cwd, sessionId, exitCode: 0, skipped: reason,
-    note: msg, startedAt, finishedAt, durationMs: 0, ...SCHEDULER_META_IDENTITY,
+    note: msg, startedAt, finishedAt, durationMs: 0, ...SCHEDULER_META_IDENTITY, ...extraMeta,
   });
   return { exitCode: 0, durationMs: 0, skipped: reason, note: msg, sessionId };
 }
@@ -1604,6 +1609,7 @@ async function reconcile(state) {
       // membership, so moving the file between Epic dirs must re-point the row.
       epicId: p.epicId ?? job.epicId ?? null,
       dependsOn: p.dependsOn,
+      files: p.files ?? [],
       disposition: p.disposition ?? null,
       planId: p.planId ?? null,
       quietMachine: p.quietMachine === true,
@@ -1727,6 +1733,7 @@ async function reconcile(state) {
       sourceTabId: p.sourceTabId ?? inv.row?.sourceTabId ?? null,
       epicId: p.epicId ?? inv.row?.epicId ?? null,
       dependsOn: p.dependsOn,
+      files: p.files ?? [],
       disposition: p.disposition ?? null,
       planId: p.planId ?? null,
       quietMachine: p.quietMachine === true,
@@ -1862,6 +1869,7 @@ async function reconcile(state) {
       sourceTabId: p.sourceTabId,
       epicId: p.epicId ?? null,
       dependsOn: p.dependsOn,
+      files: p.files ?? [],
       disposition: p.disposition ?? null,
       planId: p.planId ?? null,
       quietMachine: p.quietMachine === true,
@@ -4205,13 +4213,14 @@ function ensureTimeoutShimOnce() {
  * Watchdogs are declared as an array; the result-tailer's exit-code mapping
  * (success+killedBySignal → 0) is scheduler-specific and lives in onExit.
  */
-async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget = null, foreignWip = null, launchEnv = null, onPhase = null, reviewInRun = true) {
+async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget = null, foreignWip = null, launchEnv = null, onPhase = null, reviewInRun = true, worktreeSetup = null) {
   // First statement — stamps the 'exec-entered' dispatch-phase breadcrumb
   // before openLog below, so a hang inside openLog/spawn itself still shows
   // execution reached this function (see spawnJob's dispatchPhase comment).
   if (onPhase) await onPhase('exec-entered');
   const logPath = path.join(runDir, `${job.slug}.log`);
   const metaPath = path.join(runDir, `${job.slug}.meta.json`);
+  const setupMeta = worktreeSetup ? { worktreeSetup } : {};
   // `cwd` stays the MAIN tree throughout — PRD lookup (findPrdDir/prdPathForJob)
   // and every git call below key off this value, never the worktree. Only the
   // spawned child's own process cwd (spawnCwd) may point at a job worktree —
@@ -4237,6 +4246,12 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
 
   safeLog(`[scheduler] starting ${job.slug} at ${new Date().toISOString()}\n[scheduler] cwd=${cwd}` +
     (spawnCwd !== cwd ? ` (running isolated in worktree ${spawnCwd})` : '') + '\n\n');
+  if (worktreeSetup) {
+    try {
+      const setupLines = formatWorktreeSetupOutcome(worktreeSetup);
+      if (setupLines.length) safeLog(setupLines.join('\n') + '\n\n');
+    } catch { /* logging must never break a run */ }
+  }
 
   // Dead-cwd guard: verify the target directory exists and is traversable
   // before handing it to the child process. Checks spawnCwd (where the child
@@ -4249,7 +4264,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
     // Sync write: this is an early-exit error path inside an async function,
     // so we could await, but using the sync variant keeps the error path
     // ordering identical to the spawn-failed branch below (also sync).
-    config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs: 0, ...SCHEDULER_META_IDENTITY });
+    config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs: 0, ...SCHEDULER_META_IDENTITY, ...setupMeta });
     return { exitCode: -1, durationMs: 0, error: errMsg, sessionId };
   }
 
@@ -4327,12 +4342,12 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
         // real failure. Anything else (malformed/unreadable PRD) is a real
         // failure and keeps exitCode: -1.
         if (await prdPaths.archivedTwinExists(job)) {
-          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
+          return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived', setupMeta);
         }
         if (e2 && e2.code === 'ENOENT') {
           const rc = await recheckBeforeMissingSkip();
           if (rc && rc !== 'resolved') return rc;
-          if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+          if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing', setupMeta);
         } else {
           safeLog(`[scheduler] failed to read PRD: ${e2?.message}\n`);
           closeFd();
@@ -4347,12 +4362,12 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
       // than a hard failure. Anything else (a real read/parse error) still
       // fails the job.
       if (await prdPaths.archivedTwinExists(job)) {
-        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived');
+        return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-archived', setupMeta);
       }
       if (e && e.code === 'ENOENT') {
         const rc = await recheckBeforeMissingSkip();
         if (rc && rc !== 'resolved') return rc;
-        if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing');
+        if (!rc) return prdArchivedSkipResult(job, cwd, sessionId, startedAt, safeLog, closeFd, metaPath, 'prd-missing', setupMeta);
       } else {
         safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
         closeFd();
@@ -4437,7 +4452,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
   if (!promptCheck.ok) {
     safeLog(`[scheduler] ${promptCheck.error}\n`);
     closeFd();
-    config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: promptCheck.error, startedAt, finishedAt: Date.now(), durationMs: 0, ...SCHEDULER_META_IDENTITY });
+    config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: promptCheck.error, startedAt, finishedAt: Date.now(), durationMs: 0, ...SCHEDULER_META_IDENTITY, ...setupMeta });
     return { exitCode: -1, durationMs: 0, error: promptCheck.error, sessionId };
   }
 
@@ -4603,7 +4618,8 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
     // is calibrated against). `quietMachine` jobs and any PRD with an
     // explicit `budgetExempt: true` opt out entirely — logged once here so
     // an unbounded job is never silently unbounded.
-    const jobBudgetMs = budget.computeJobBudgetMs(job.estimateMinutes);
+    const jobBudgetMs = budget.computeJobBudgetMs(
+      job.estimateMinutes ?? resolvePersonaDefaultEstimate(job.cwd, job.agentType || DEFAULT_PRD_AGENT_TYPE));
     const budgetExempt = budget.isJobBudgetExempt(job);
     if (budgetExempt) {
       safeLog(`[scheduler] wall-clock budget watchdog EXEMPT for ${job.slug} ` +
@@ -4701,7 +4717,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
           sl(`\n[scheduler] ${errMsg}\n`);
           // Sync write: inside a Promise executor callback; must flush meta
           // before resolve() so the spawnJob mutate() that follows sees it.
-          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, leakedDescendants: leaked, ...SCHEDULER_META_IDENTITY, originSessionId, contextDigestApplied });
+          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, leakedDescendants: leaked, ...SCHEDULER_META_IDENTITY, ...setupMeta, originSessionId, contextDigestApplied });
           resolve({ exitCode: -1, durationMs, error: errMsg, leakedDescendants: leaked, sessionId });
           return;
         }
@@ -4763,7 +4779,7 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
           startedAt, finishedAt: Date.now(), durationMs, leakedDescendants: leaked,
           agentResultSubtype, mappedFromSignal: mappedToSuccess ? signal || `code=${exitCode}` : null,
           killedByWatchdog: effectiveKilledByWatchdog, budgetKillReason,
-          ...SCHEDULER_META_IDENTITY,
+          ...SCHEDULER_META_IDENTITY, ...setupMeta,
           originSessionId, contextDigestApplied,
         });
         resolve({
@@ -5722,6 +5738,23 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
       await broadcast({ flush: true });
       return;
     }
+    // Early returns after the preflight worktree exists must not leak the
+    // checkout or its cap count (retries would also re-run the whole setup).
+    const releasePreflightWorktree = async () => {
+      if (!preflightWorktree.ok) return;
+      try {
+        await jobWorktree.cleanupJobWorktree({
+          cwd: job.cwd || defaultCwd,
+          dir: preflightWorktree.dir,
+          branch: preflightWorktree.branch,
+          keepBranch: false,
+        });
+      } catch (err) {
+        try {
+          reportSchedulerError("preflight worktree cleanup failed", job.slug, err);
+        } catch { /* reporting must never throw out of spawnJob */ }
+      }
+    };
     // Launch circuit breaker (lib/scheduler/launchFailure.cjs, issue #11). Re-evaluated
     // here, not just in tickQueue, because the block can change between the
     // pick and this dispatch (another job's probe just failed). 'blocked' →
@@ -5761,6 +5794,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     });
     if (launchGate.state === 'blocked') {
       console.log(`[scheduler] ${job.slug}: deferring — ${launchGate.reason}`);
+      await releasePreflightWorktree();
       await broadcast({ flush: true });
       return;
     }
@@ -5872,7 +5906,10 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
       }
     });
     await broadcast({ flush: true });
-    if (dispatchSkippedAlreadyCompleted) return;
+    if (dispatchSkippedAlreadyCompleted) {
+      await releasePreflightWorktree();
+      return;
+    }
 
     await mutate((s) => {
       const idx = s.jobs.findIndex((x) => x.slug === job.slug);
@@ -5940,6 +5977,19 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     const worktree = preflightWorktree;
     if (worktree.ok) {
       console.log(`[scheduler] ${job.slug}: isolated in worktree ${worktree.dir} (branch ${worktree.branch})`);
+      if (worktree.setup && !isWorktreeSetupSettled(worktree.setup)) {
+        try {
+          const cmds = (Array.isArray(worktree.setup.commands) ? worktree.setup.commands : [])
+            .map((c) => `${c && c.cmd}: exit ${c && c.code} in ${(c && c.ms) || 0}ms`);
+          appendError({
+            cwd: job.cwd || defaultCwd,
+            scope: 'scheduler',
+            level: 'warn',
+            message: `${job.slug}: worktree setup did not pass (${worktree.setup.reason})${cmds.length ? ' — ' + cmds.join('; ') : ''}`,
+            meta: { slug: job.slug, cwd: job.cwd || defaultCwd, reason: worktree.setup.reason, commands: (worktree.setup.commands || []).map((c) => ({ cmd: c && c.cmd, code: c && c.code, ms: c && c.ms })) },
+          });
+        } catch { /* durable logging must never break dispatch */ }
+      }
     } else {
       console.log(`[scheduler] ${job.slug}: running in main tree (worktree not used: ${worktree.reason})`);
       // A job losing worktree isolation must never be a silent downgrade
@@ -6045,7 +6095,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
             s.jobs[idx].dispatchPhaseAt = new Date().toISOString();
           }
         });
-      }, reviewInRun);
+      }, reviewInRun, worktree.ok ? worktree.setup : { ran: false, ok: false, reason: 'in-place', waitedMs: 0, ms: 0, commands: [] });
     } finally {
       if (worktree.ok) {
         ({ worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha } =
@@ -8894,15 +8944,23 @@ async function runGateShadow(job) {
     } catch { ancestorOk = false; }
     const memo = job.gateShadow?.baseline;
     let baseOutcome = memo && memo.head === headBefore && memo.outcome ? memo.outcome : null;
+    let baseSetup = baseOutcome ? (memo.setup ?? null) : null;
     if (!baseOutcome) {
       const scratch = path.join(os.tmpdir(), `sm-baseline-gate-${process.pid}-${Date.now()}`);
       let added = false;
       try {
         await execGitAt(job.cwd, ['worktree', 'add', '--detach', scratch, job.guardHeadBefore], { timeout: 120_000 });
         added = true;
-        await linkDependencyDirs({ mainCwd: job.cwd, worktreeCwd: scratch });
-        const r = await runGateSequence(gate.sequence, { cwd: scratch });
-        baseOutcome = r.status === 'busy' ? { status: 'unavailable', reason: 'busy', results: [] } : r;
+        const deps = await linkDependencyDirs({ mainCwd: job.cwd, worktreeCwd: scratch });
+        baseSetup = deps && deps.setup ? deps.setup : null;
+        if (!isWorktreeSetupSettled(baseSetup)) {
+          // A declared setup that did not pass can leave a broken cache (cold Godot
+          // import); a base gate failing for that reason must not excuse HEAD's failures.
+          baseOutcome = { status: 'unavailable', reason: `base-setup-${baseSetup?.reason ?? 'error'}`, results: [] };
+        } else {
+          const r = await runGateSequence(gate.sequence, { cwd: scratch });
+          baseOutcome = r.status === 'busy' ? { status: 'unavailable', reason: 'busy', results: [] } : r;
+        }
       } catch (e) {
         baseOutcome = { status: 'unavailable', reason: `base-gate-error: ${e && e.message ? e.message : e}`, results: [] };
       } finally {
@@ -8914,7 +8972,7 @@ async function runGateShadow(job) {
       }
     }
     baselineDecision = decideBaselineAuthority({ job, headOutcome: outcome, baseOutcome, evidenceOk, ancestorOk, cleanOk, headStable });
-    gateShadow.baseline = { head: headBefore, base: job.guardHeadBefore, outcome: baseOutcome, ...baselineDecision };
+    gateShadow.baseline = { head: headBefore, base: job.guardHeadBefore, outcome: baseOutcome, setup: baseSetup, ...baselineDecision };
   }
 
   const runId = job.runId || reviewLadder.resolveRunId(job);
@@ -10358,12 +10416,20 @@ function toCompactPrdEntry(entry) {
  * `schedule:list-prds` IPC handler and the admin HTTP `GET
  * /admin/scheduler/prds` route (PRD 1024) — neither re-implements this scan.
  */
-async function listPrdsInternal({ cwd } = {}) {
+function normalizeListCwd(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return cwd;
+  // Same normalization createPrd applies to frontmatter cwd: tilde expansion,
+  // trailing-slash strip, Epic-worktree path -> main checkout.
+  return resolveProjectContext({ cwd: expandHome(cwd) }).cwd || cwd;
+}
+
+async function listPrdsInternal({ cwd: rawCwd } = {}) {
   ensureDirs();
+  const cwd = normalizeListCwd(rawCwd);
   const out = [];
   const seenSlugs = new Set();
 
-  async function readDirInto(dir, { archived }) {
+  async function readDirInto(dir, { archived, nested = false }) {
     let entries;
     try {
       entries = await fsp.readdir(dir);
@@ -10373,9 +10439,20 @@ async function listPrdsInternal({ cwd } = {}) {
       }
       return;
     }
-    for (const name of entries) {
-      if (!name.endsWith('.md') || name.startsWith('.')) continue;
-      const filePath = path.join(dir, name);
+    const files = entries.filter((n) => n.endsWith('.md') && !n.startsWith('.')).map((n) => path.join(dir, n));
+    if (archived && !nested) {
+      // prds-archived/<ISO-ts>/*.md — exactly one level down (mirrors
+      // budget.cjs computeDepHistorySatisfaction); never recurse further.
+      for (const name of entries) {
+        if (name.endsWith('.md') || name.startsWith('.')) continue;
+        const sub = path.join(dir, name);
+        let st;
+        try { st = await fsp.lstat(sub); } catch { continue; }
+        if (st.isDirectory()) await readDirInto(sub, { archived, nested: true });
+      }
+    }
+    for (const filePath of files) {
+      const name = path.basename(filePath);
       try {
         const parsed = await parsePrd(filePath);
         // A slug can't be both live and archived at once, but a duplicate
@@ -10667,9 +10744,10 @@ const remote = {
   // paging by offset can't skip or duplicate an entry between requests as
   // long as the underlying PRD set doesn't change mid-page.
   async listPrds(filter = {}) {
-    const all = await listPrdsInternal({ cwd: filter.cwd });
+    const filterCwd = normalizeListCwd(filter.cwd);
+    const all = await listPrdsInternal({ cwd: filterCwd });
     const filtered = all.filter((entry) => {
-      if (filter.cwd && entry.cwd !== filter.cwd) return false;
+      if (filterCwd && entry.cwd !== filterCwd) return false;
       if (filter.epicId && entry.epicId !== filter.epicId) return false;
       if (filter.status && entry.status !== filter.status) return false;
       return true;
@@ -10757,7 +10835,15 @@ const remote = {
   // prdFrontmatter.cjs's parsePrdFile/serializePrdFile round-trip pair (PRD
   // 1024) so unrecognized keys (e.g. dependsOn) and untouched recognized
   // keys' original line formatting survive unchanged.
-  async updatePrd({ slug, cwd, frontmatter, body }) {
+  async updatePrd({ slug, cwd, frontmatter, body, gate, files, acceptanceCriteria }) {
+    const structured = {};
+    if (gate !== undefined) structured.gate = gate;
+    if (files !== undefined) structured.files = files;
+    if (acceptanceCriteria !== undefined) structured.acceptanceCriteria = acceptanceCriteria;
+    const hasStructured = Object.keys(structured).length > 0;
+    if (hasStructured && body !== undefined) {
+      return { ok: false, error: 'Pass either body (full replacement) or the structured fields gate/files/acceptanceCriteria, not both.' };
+    }
     const job = await this.getJob(slug);
     const EDITABLE_JOB_STATUSES = new Set(['pending', 'quarantined', 'needs_review', 'failed', 'skipped']);
     if (job && !EDITABLE_JOB_STATUSES.has(job.status)) {
@@ -10837,13 +10923,22 @@ const remote = {
         fm[key] = frontmatter[key];
       }
     }
-    const newBody = body !== undefined ? body : origBody;
+    let newBody = body !== undefined ? body : origBody;
+    let patchWarnings = [];
+    if (hasStructured) {
+      const patched = applyStructuredPrdPatch(origBody, structured);
+      if (!patched.ok) return { ok: false, error: patched.error };
+      newBody = patched.body;
+      patchWarnings = patched.warnings || [];
+    }
     const newRaw = serializePrdFile(fm, newBody);
 
     try {
       await config.writeTextAtomic(filePath, newRaw, { writer: 'scheduler' });
       const stat = await fsp.stat(filePath);
-      return { ok: true, slug, bytesWritten: stat.size };
+      return patchWarnings.length
+        ? { ok: true, slug, bytesWritten: stat.size, warnings: patchWarnings }
+        : { ok: true, slug, bytesWritten: stat.size };
     } catch (e) {
       return { ok: false, error: e?.message ?? 'write failed' };
     }

package/src/main/seedDevPlugin.cjs

@@ -198,4 +198,4 @@ async function seedDevPlugin({
   }
 }
 
-module.exports = { seedDevPlugin, upgradeIfStale, marketplaceIsStale, compareSemver, markerPath, MAX_ATTEMPTS };
+module.exports = { seedDevPlugin, writeMarker, PLUGIN_SLUG, MARKETPLACE, ENABLED_KEY, upgradeIfStale, marketplaceIsStale, compareSemver, markerPath, MAX_ATTEMPTS };

package/src/main/seedSchedulerMcp.cjs

@@ -209,4 +209,4 @@ async function seedSchedulerMcp({ logger = console, addFn = runClaudeMcpAdd, rem
   }
 }
 
-module.exports = { seedSchedulerMcp, mcpAddArgv, markerPath, MAX_ATTEMPTS, serverScriptPath, SERVER_NAME };
+module.exports = { seedSchedulerMcp, writeMarker, runClaudeMcpAdd, runClaudeMcpRemove, mcpAddArgv, markerPath, MAX_ATTEMPTS, serverScriptPath, SERVER_NAME };

package/src/main/templates/PRD_AUTHORING.md

@@ -1,4 +1,4 @@
-<!-- PRD_AUTHORING.md v9 -->
+<!-- PRD_AUTHORING.md v13 -->
 # PRD Authoring Guide — Scheduler Safety Rules
 
 Rule: every PRD you queue follows the rules below.
@@ -69,7 +69,7 @@ if (!found) {
 Rule: every PRD needs these fields.
 1. `title` — one line, plain English.
 2. `cwd` — the Epic's project root, as an absolute path or `~/…`. The API always sets it to the Epic's project, whatever you pass. To work in another project, open an Epic in that project. The folder must exist when you queue.
-3. `estimateMinutes` — optional; omit it. A run without one gets the 45-minute kill-budget floor. Pass one only if the run legitimately needs longer. Most PRDs take 5–10 minutes (§8).
+3. `estimateMinutes` — optional; omit it. A run without one gets its persona's `defaultEstimateMinutes`, else the 45-minute floor. Pass one only if the run legitimately needs longer. Most PRDs take 5–10 minutes (§8).
 
 `parallelGroup` is deprecated and ignored. `dependsOn: [<slug>, ...]` is the only ordering primitive.
 
@@ -100,12 +100,13 @@ Both fields are required in every `scheduler_create_prd` call.
 7. Keep each entry on one line, at most 500 chars, with plain spaces between words.
 8. Use `["none"]` only for docs or config with no runnable check. Write exactly `none`. Never mix `none` with commands.
 9. Put `NAME=value` words before `timeout`, never after it, for example `CI=1 timeout 300 npm test`. A leading `TMPDIR=$(mktemp -d) ` is allowed but not needed: the scheduler gives each gate its own TMPDIR.
+10. A gate command must not create or modify tracked files; write outputs to the per-gate TMPDIR or a gitignored path. Why: a dirtied tree fails the clean-tree check.
 
 ### files
 
 1. 1–50 repo-relative paths. A folder ends with `/`.
 2. No absolute paths, no `~` at the start, no `..` or `.` segments, no `*` or `?`, no `\` or backticks, no leading `-`. Use `/` between folders.
-3. PRDs that can run at the same time must not share a file. If two PRDs touch the same file, chain them with `dependsOn`.
+3. The scheduler never runs two PRDs with overlapping files at once (held as `files-overlap`); `dependsOn` is for real output or order dependencies only.
 
 ### What the API writes
 
@@ -125,7 +126,7 @@ A short Epic-context digest is prepended automatically for orientation only —
 
 The executor can't ask you anything: no `ScheduleWakeup`, Cron, Monitor, `AskUserQuestion`, plan mode, or worktree tools; background tasks are off (a `timeout` command is always on PATH — the app installs a shim on macOS). It must never stop to ask a question — it makes the safest reasonable call and reports it, so write the PRD so that call is obvious.
 
-Worktree reach: every PRD runs in an isolated git worktree holding tracked files plus `.venv`/`venv` (and `node_modules` for non-pnpm projects) symlinked from the main checkout; pnpm projects (pnpm-lock.yaml) get a worktree-local `node_modules` installed offline from the store. Why: a pnpm install through the symlink purged the main checkout's node_modules (Bilko-Game-Academy 2026-10-18). A step that needs gitignored runtime state (databases, `downloads/`, browser profiles, logs) or a live side effect must address the main checkout by absolute path (e.g. `$HOME/Projects/<repo>/...`), be artifact-only (a deliverable artifact + `artifactPaths`, no tracked edits), and `dependsOn` the PRD that lands its tracked edits. Host crontab installs stay human-only (see §14).
+Worktree reach: every PRD runs in an isolated git worktree holding tracked files plus `node_modules` and non-uv `.venv`/`venv` symlinked from the main checkout; pnpm projects (pnpm-lock.yaml) get a worktree-local `node_modules` installed offline from the store, and uv projects (uv.lock) get a worktree-local env built by an offline frozen `uv sync`, not a symlink. Why: a pnpm install through the symlink purged the main checkout's node_modules (Bilko-Game-Academy 2026-10-18). A step that needs gitignored runtime state (databases, `downloads/`, browser profiles, logs) or a live side effect must address the main checkout by absolute path (e.g. `$HOME/Projects/<repo>/...`), be artifact-only (a deliverable artifact + `artifactPaths`, no tracked edits), and `dependsOn` the PRD that lands its tracked edits. A project may declare `worktreeSetup` gate-syntax commands in a tracked `.session-manager.json` at the repo root; they run once per fresh job worktree and baseline scratch worktree, before the executor starts, with cwd = the worktree root (a project in a subfolder names it, e.g. `timeout 600 godot --headless --path game --import`). Setups run one at a time per project and are never skipped; they must write only inside the worktree (node_modules and non-uv venvs are symlinks into the main checkout). The outcome is the `[scheduler] worktree setup:` lines at the top of the run log plus `worktreeSetup` in the run's meta.json. Host crontab installs stay human-only (see §14).
 Why: burrow PRD 1516 halted because its relative `.venv` python against `downloads/fb-tracker.db`, `scripts/install-cron.sh` and `pipeline-cron.sh --now` resolved inside the worktree (no runtime state; install-cron would bake a temporary worktree path into crontab), while sibling 1494 succeeded the same day using an absolute main-checkout path and artifact-only output. `scheduler_create_prd` warns on relative gitignored paths.
 
 ---
@@ -150,6 +151,8 @@ npm test || { echo "HALT: npm test failed — see above"; exit 1; }
 
 Note: a `rateLimited` exit-1 is the scheduler's own benign auto-pause (it resumes at the next 5h reset) — don't engineer retry logic for it.
 
+Note: `HALT:` in a script's output, a PRD, or a report is plain text to the scheduler. Only the verdict line decides the outcome; a report line that starts with `HALT:` re-queues the job only when the report has no `SCHEDULER_VERDICT` line. Why: the verifier used to match `HALT:` anywhere in a report, so finished PASS runs that only described a tool's failure path were re-queued and parked (Rabbits-Game `163-attack-scorecard`, 2026-10-24).
+
 ---
 
 ## §10 Negative-assertion checks must exit 0 on the clean case
@@ -224,3 +227,4 @@ Before queueing a new PRD, verify each of these:
 - [ ] **§11 End green:** the gate runs last; any intentional failure runs early and is captured.
 - [ ] **Gate baseline:** every gate command ran green once at HEAD in the main checkout; a red suite is scoped to the PRD's own test files and the PRD notes say why. Why: a gate already red on base parks as `sentinel_fail`.
 - [ ] **No human-only gates:** no gate or criterion needs a human or the passage of time (cron install, live post wait, live payment, dashboard action); those end `SCHEDULER_VERDICT: NEEDS_HUMAN <question>`. Why: no executor can pass them.
+- [ ] **Gate purity:** a gate command must not create or modify tracked files; outputs go to the per-gate TMPDIR or a gitignored path. Why: a dirtied tree fails the clean-tree check.