claude-code-session-manager 0.37.0 → 0.37.2

package/src/main/lib/prdCreate.cjs

@@ -1,22 +1,28 @@
 /**
- * prdCreate.cjs — PRD-body builder for the create-prd admin route (PRD 549,
- * gh-issue-6). Pure functions only: no filesystem writes, no NN allocation,
- * no HTTP. adminServer.cjs owns orchestration (auth, cwd validation via
- * config.cjs's validatePath, NN allocation via the injected remote,
- * writing via remote.writePrd -> config.cjs's writeTextAtomic) so this
- * module stays trivially unit-testable.
+ * prdCreate.cjs — PRD-body builder + create-prd admin HTTP route (PRD 549,
+ * gh-issue-6; route consolidated here from the former standalone admin HTTP
+ * server module by PRD 689). buildPrdBody/deriveSlugFromTitle/readStandards are pure
+ * functions: no filesystem writes, no NN allocation, no HTTP. registerAdminRoute
+ * owns orchestration (auth is the injected transport's job, cwd validation
+ * via config.cjs's validatePath, NN allocation via the injected remote,
+ * writing via remote.writePrd -> config.cjs's writeTextAtomic).
  *
- * Standards are read fresh from disk on every call (no in-process caching)
- * so a live edit to standards.md is picked up by the next create-prd call
- * without an app restart — same one-concept-one-implementation reasoning
- * that keeps the /develop skill re-reading it fresh per PRD (see SKILL.md).
+ * Neither this route nor the /develop skill embeds standards.md's contents
+ * anymore — both just point the headless executor at STANDARDS_PATH with an
+ * instruction to read it before starting. There's nothing to go stale: the
+ * executor always reads the live file at run time, same one-concept-one-
+ * implementation reasoning that keeps the two PRD-creation paths in sync
+ * (see SKILL.md).
  */
 'use strict';
 
 const fsp = require('node:fs/promises');
 const path = require('node:path');
-const { PRD_CREATE_SLUG_RE } = require('../ipcSchemas.cjs');
+const { schemas, PRD_CREATE_SLUG_RE } = require('../ipcSchemas.cjs');
 const { kebabCase } = require('./kebabCase.cjs');
+const config = require('../config.cjs');
+const { expandHome } = require('./expandHome.cjs');
+const { readBody, sendJson } = require('./localAdminHttp.cjs');
 
 const STANDARDS_PATH = path.join(
   __dirname, '..', '..', '..',
@@ -33,12 +39,13 @@ function deriveSlugFromTitle(title) {
 }
 
 /**
- * Build the full PRD markdown body (frontmatter + required sections +
- * verbatim engineering standards), matching the structure `/develop`'s
- * SKILL.md documents: frontmatter, then Goal / Acceptance criteria /
- * Implementation notes / Out of scope / Engineering standards, in order.
+ * Build the full PRD markdown body (frontmatter + required sections + a
+ * pointer at the engineering standards file), matching the structure
+ * `/develop`'s SKILL.md documents: frontmatter, then Goal / Acceptance
+ * criteria / Implementation notes / Out of scope / Engineering standards,
+ * in order.
  */
-function buildPrdBody(input, standardsText) {
+function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
     implementationNotes, outOfScope,
@@ -53,21 +60,104 @@ function buildPrdBody(input, standardsText) {
   const oosSource = outOfScope && outOfScope.length ? outOfScope : ['(none)'];
   const oosLines = oosSource.map((line) => `- ${line}`).join('\n');
 
+  const standardsPointer = [
+    `Before writing any code, read \`${STANDARDS_PATH}\` — it has the Performance, Debugging,`,
+    'API-reuse, TDD, and Execution-discipline rules that apply to this PRD. Every rule in it is',
+    'mandatory, especially Execution discipline (bounded commands, verify before done, the',
+    'finish-protocol sentinel).',
+  ].join('\n');
+
   const bodyLines = [
     '# Goal', '', goal, '',
     '# Acceptance criteria', '', acLines, '',
     '# Implementation notes', '', implementationNotes, '',
     '# Out of scope', '', oosLines, '',
-    '## Engineering standards', '', standardsText.trimEnd(), '',
+    '## Engineering standards', '', standardsPointer, '',
   ];
 
   return `${fmLines.join('\n')}${bodyLines.join('\n')}`;
 }
 
+/**
+ * Registers the create-prd admin HTTP route (PRD 689 — moved verbatim out of
+ * the former standalone admin HTTP server module's handleRequest, no behavior
+ * change) against an injected localAdminHttp.cjs transport. `remote` is
+ * scheduler.cjs's remote object, passed explicitly (not required directly) so
+ * this stays testable without booting Electron, matching that former
+ * module's original dependency-injection pattern.
+ */
+function registerAdminRoute(adminHttp, remote) {
+  adminHttp.registerRoute('POST', '/admin/scheduler/create-prd', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+
+    let input;
+    try {
+      input = schemas.schedulerCreatePrd.parse(parsed);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid PRD payload', details: e?.issues ?? e?.message });
+      return;
+    }
+
+    // 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.
+    try {
+      config.validatePath(expandHome(input.cwd));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` });
+      return;
+    }
+
+    const slug = input.slug || deriveSlugFromTitle(input.title);
+    if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
+      sendJson(res, 400, { ok: false, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' });
+      return;
+    }
+
+    // NN allocation is delegated to allocateParallelGroup() (PRD 548) via
+    // the injected remote — never re-derived here — unless the caller
+    // opted into an existing group explicitly.
+    const nn = input.parallelGroup ?? await remote.allocateParallelGroup();
+    const filenameSlug = `${nn}-${slug}`;
+
+    // An explicit `parallelGroup` bypasses allocateParallelGroup()'s
+    // collision-proof reservation, so re-check for an existing file at
+    // this exact destination before writing — remote.writePrd itself has
+    // no existence guard (by design, it doubles as the edit-in-place
+    // path for Scheduler UI PRD edits), so "create" must not silently
+    // clobber an existing job's PRD.
+    const existing = await remote.readPrd(filenameSlug);
+    if (existing?.ok) {
+      sendJson(res, 409, { ok: false, error: `PRD already exists: ${filenameSlug}.md` });
+      return;
+    }
+
+    const body = buildPrdBody(input);
+    const writeResult = await remote.writePrd(filenameSlug, body);
+    if (!writeResult?.ok) {
+      sendJson(res, 500, { ok: false, error: writeResult?.error ?? 'write failed' });
+      return;
+    }
+
+    sendJson(res, 200, { nn, filename: `${filenameSlug}.md`, status: 'queued' });
+  });
+}
+
 module.exports = {
   PRD_CREATE_SLUG_RE,
   STANDARDS_PATH,
   readStandards,
   deriveSlugFromTitle,
   buildPrdBody,
+  registerAdminRoute,
 };

package/src/main/lib/rcaFeedbackHook.cjs

@@ -38,8 +38,8 @@ const PRDS_DIR = path.join(os.homedir(), '.claude', 'session-manager', 'schedule
 const SM_REPO_ROOT = path.join(os.homedir(), 'Projects', 'session-manager');
 const SM_REPO_FEEDBACK_DIR = path.join(SM_REPO_ROOT, 'session-manager-operations', 'feedback');
 
-// NEVER write here: ~/.claude/session-manager/feedback/ is the external
-// watchdog's auto-PRD intake (scripts/scheduler-watchdog.cjs `sweep()`) — it
+// NEVER write here: ~/.claude/session-manager/feedback/ is the scheduler's
+// auto-PRD intake (src/main/scheduler.cjs's periodic feedback sweep) — it
 // converts anything dropped there into a scheduled PRD automatically. Filing
 // an RCA there would create an RCA → auto-PRD → run → needs_review → RCA
 // cycle with no human in the loop. Both real destinations below are project

package/src/main/lib/singleInstanceGuard.cjs

@@ -0,0 +1,20 @@
+/**
+ * singleInstanceGuard.cjs — the losing side of Electron's single-instance
+ * lock must actually terminate the process, not just request a quit.
+ *
+ * app.quit() only requests a graceful shutdown via the normal
+ * window-all-closed -> quit -> exit chain; a losing instance calls it before
+ * app.whenReady() ever fires (no window, no IPC), so there's nothing for
+ * that chain to hook into and the process can sit as a zombie indefinitely.
+ * app.exit() terminates immediately without waiting on that chain; the
+ * setTimeout is a defense-in-depth backstop in case app.exit() itself is
+ * ever delayed by an Electron internal on a future version.
+ */
+'use strict';
+
+function terminateLosingInstance(app, { fallbackDelayMs = 2000 } = {}) {
+  setTimeout(() => process.exit(0), fallbackDelayMs).unref?.();
+  app.exit(0);
+}
+
+module.exports = { terminateLosingInstance };

package/src/main/scheduler.cjs

@@ -63,6 +63,7 @@ const prdParser = require('./scheduler/prdParser.cjs');
 const { verifyRun } = require('./runVerify.cjs');
 const logs = require('./logs.cjs');
 const { schemas, validated } = require('./ipcSchemas.cjs');
+const { readBody, sendJson } = require('./lib/localAdminHttp.cjs');
 const {
   POLL_INTERVAL_MS,
   USAGE_REFRESH_INTERVAL_MS,
@@ -74,6 +75,12 @@ const { runDefinitionOfDoneOnDrain } = require('./lib/dodDrainHook.cjs');
 const { fileRcaFeedback, extractRcaBlock } = require('./lib/rcaFeedbackHook.cjs');
 const queueHistory = require('./lib/queueHistory.cjs');
 const queueOps = require('./queueOps.cjs');
+// Feedback-auto-PRD sweep — formerly only run by the external scheduler-watchdog
+// while the app was down (PRD 686 moved it in-app so it also runs while alive).
+// Plain Node module, no Electron dependency; queuePath/prdsDir defaults already
+// match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
+// home-dir layout.
+const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
 
 const MAX_INVESTIGATION_DURATION_MS = 30 * 60_000;
 
@@ -203,10 +210,10 @@ function gitHead(cwd) {
 
 // Returns true if ≥1 commit landed on any ref (branch, remote-tracking branch,
 // or tag) in cwd between startedAt and finishedAt (with 60s slack) — not just
-// the currently checked-out branch. Used by the self-heal pass to derive
-// committedDuringRun from the recorded run window — the live commit-guard uses
-// gitHead() instead. Never throws; git-unavailable → false (no override, job
-// stays as-is).
+// the currently checked-out branch. Used both by the self-heal pass and by the
+// live commit-guard's fallback (see computeCommittedDuringRun) to derive
+// committedDuringRun from the recorded run window. Never throws;
+// git-unavailable → false (no override, job stays as-is).
 function committedInWindow(cwd, startedAt, finishedAt) {
   return new Promise((resolve) => {
     if (!cwd || !startedAt) { resolve(false); return; }
@@ -222,6 +229,16 @@ function committedInWindow(cwd, startedAt, finishedAt) {
   });
 }
 
+// Live commit-guard: cheap HEAD-diff fast path, falling back to the
+// git-log --all scan when HEAD didn't move on the starting branch. A PRD that
+// checks out other branches, commits real work on each, then checks its
+// starting branch back out before exit leaves HEAD unchanged even though
+// commits landed — the fallback catches that case. Never throws.
+async function computeCommittedDuringRun(cwd, headBefore, headAfter, startedAt, untilIso) {
+  if (headBefore && headAfter && headBefore !== headAfter) return true;
+  return committedInWindow(cwd, startedAt, untilIso);
+}
+
 const ROOT = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans');
 const PRDS_DIR = path.join(ROOT, 'prds');
 const RUNS_DIR = path.join(ROOT, 'runs');
@@ -817,6 +834,17 @@ let resumeTimer = null;
 let pollLoopTimer = null;
 let rescheduleInterval = null;
 let heartbeatInterval = null;
+// Feedback sweep piggybacks on the 60s heartbeat tick but runs far less often —
+// every Nth tick — since it's a readdir-per-active-project scan, not free.
+// 5 ticks = 5 minutes; well inside sweep()/activeProjectCwds()'s 90-minute
+// active-session window, so no active project can be missed between sweeps.
+const FEEDBACK_SWEEP_TICK_INTERVAL = 5;
+let feedbackSweepTickCount = 0;
+/** Pure gate for the tick counter above — exported so the wiring is testable
+ *  without waiting on real setInterval timers. */
+function feedbackSweepDue(tickCount, interval = FEEDBACK_SWEEP_TICK_INTERVAL) {
+  return tickCount >= interval;
+}
 // In-memory set of slugs currently spawned in this process. Prevents
 // double-spawn when runDueJobs() is called while jobs are in flight.
 const runningSet = new Set();
@@ -1059,6 +1087,79 @@ function resetJobFields(job, errorMsg) {
   delete job.verifierVerdict;
 }
 
+// Grace period between a boot orphan's SIGTERM and reading its log to
+// classify the outcome — matches killOrphanClaudePid's own internal 5s
+// SIGKILL follow-up delay, plus a small margin so classification always runs
+// after that SIGKILL has had a chance to land.
+const BOOT_ORPHAN_KILL_GRACE_MS = 6000;
+
+/**
+ * partitionBootOrphans(jobs, isAlive?) → { immediate: string[], deferred: string[] }
+ *
+ * Pure decision split for boot reconciliation. A 'running' job whose recorded
+ * pid is still alive must NOT be classified from its log yet — the orphaned
+ * process may still be writing to it, so reading now risks misclassifying a
+ * job that is about to emit result:success as no_result and double-running it.
+ * Ported from reconcileQueueOffline's cross-tick escalation (see
+ * scripts/lib/watchdogHelpers.cjs) — here it's a single deferred window since
+ * this process stays up to revisit it, rather than a separate short-lived
+ * watchdog process needing another tick.
+ */
+function partitionBootOrphans(jobs, isAlive = claudePidAlive) {
+  const immediate = [];
+  const deferred = [];
+  for (const j of jobs) {
+    if (j.status !== 'running') continue;
+    const pid = j.runtime?.pid;
+    if (pid && isAlive(pid)) {
+      deferred.push(j.slug);
+    } else {
+      immediate.push(j.slug);
+    }
+  }
+  return { immediate, deferred };
+}
+
+/**
+ * applyOrphanOutcome(job, outcome, killNote?) → void
+ *
+ * Mutates `job` in place to finalize a boot-orphaned 'running' job given its
+ * classified run outcome: success/failed finalize terminally; no_result/unknown
+ * re-queues to pending bounded by ORPHAN_REQUEUE_CAP. The status-mutation
+ * semantics (and the cap-exhaustion boundary) match the now-deleted
+ * reconcileQueueOffline (scripts/lib/watchdogHelpers.cjs) verbatim; killNote
+ * plumbing differs slightly (see call sites) since this path always knows
+ * pid liveness up front rather than re-checking per tick.
+ */
+function applyOrphanOutcome(job, outcome, killNote = '') {
+  const now = new Date().toISOString();
+  if (outcome === 'success') {
+    job.status = 'completed';
+    job.exitCode = 0;
+    job.error = null;
+    job.finishedAt = now;
+    delete job.runtime;
+  } else if (outcome === 'failed') {
+    job.status = 'failed';
+    job.exitCode = job.exitCode ?? 1;
+    job.error = `orphaned: app restarted while running${killNote}`;
+    job.finishedAt = now;
+    delete job.runtime;
+  } else {
+    const tries = job.orphanRetries ?? 0;
+    if (tries < ORPHAN_REQUEUE_CAP) {
+      resetJobFields(job, `orphaned: app restarted mid-run, re-queued (attempt ${tries + 1}/${ORPHAN_REQUEUE_CAP})${killNote}`);
+      job.orphanRetries = tries + 1;
+    } else {
+      job.status = 'failed';
+      job.exitCode = job.exitCode ?? 1;
+      job.error = `orphaned: app restarted while running, exhausted ${ORPHAN_REQUEUE_CAP} re-queue attempts${killNote}`;
+      job.finishedAt = now;
+      delete job.runtime;
+    }
+  }
+}
+
 /** Scan the tail of a job's log for the canonical rate-limit signal. We look
  *  at the last 16 KB — final result event always lands at the end.
  *  Uses readTail() so no raw fd lifecycle is needed here. */
@@ -1730,7 +1831,13 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
       // Used by the sentinel override: SCHEDULER_VERDICT: PASS + a landed
       // commit together override incidental transcript noise verdicts.
       const headAtExit = await gitHead(guardCwd);
-      const committedDuringRun = !!(guardHeadBefore && headAtExit && guardHeadBefore !== headAtExit);
+      const committedDuringRun = await computeCommittedDuringRun(
+        guardCwd,
+        guardHeadBefore,
+        headAtExit,
+        job.startedAt,
+        new Date().toISOString(),
+      );
 
       const prdPath = path.join(PRDS_DIR, `${job.slug}.md`);
       const stateForDeps = await readQueue();
@@ -2944,65 +3051,60 @@ async function init() {
   // classifyRunOutcome calls readTail → fs.readFileSync (up to 64 KB per job).
   // Pre-compute all outcomes BEFORE entering the mutate lock so the blocking I/O
   // does not stall the event loop or hold the mutateTail chain during startup.
+  //
+  // Jobs whose recorded pid is still alive are deferred (not classified here) —
+  // see partitionBootOrphans. Everything else (dead pid or no pid) is safe to
+  // classify immediately below.
   const bootSnap = readQueueSync();
+  const { immediate: immediateSlugs, deferred: deferredSlugs } = partitionBootOrphans(bootSnap.jobs);
   const bootOutcomes = new Map();
   for (const j of bootSnap.jobs) {
-    if (j.status !== 'running') continue;
+    if (!immediateSlugs.includes(j.slug)) continue;
     const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
     bootOutcomes.set(j.slug, logPath ? classifyRunOutcome(logPath) : 'unknown');
   }
   await mutate((state) => {
     for (const j of state.jobs) {
-      if (j.status !== 'running') continue;
-      const pid = j.runtime?.pid;
-      let killNote = '';
-      if (pid) {
-        const result = killOrphanClaudePid(pid);
-        killNote = ` (orphan pid=${pid}: ${result})`;
-        if (result === 'killed') {
-          console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${j.slug}`);
-        }
-      }
+      if (j.status !== 'running' || !immediateSlugs.includes(j.slug)) continue;
       const outcome = bootOutcomes.get(j.slug) ?? 'unknown';
-      if (outcome === 'success') {
-        // Job finished cleanly before the crash — keep the win.
-        j.status = 'completed';
-        j.exitCode = 0;
-        j.error = null;
-        j.finishedAt = new Date().toISOString();
-        delete j.runtime;
-        console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=success → completed`);
-      } else if (outcome === 'failed') {
-        // The log carries a real failure result event — a genuine failure, keep it.
-        j.status = 'failed';
-        j.exitCode = j.exitCode ?? 1;
-        j.error = `orphaned: app restarted while running${killNote}`;
-        j.finishedAt = new Date().toISOString();
-        delete j.runtime;
-        console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=failed → failed`);
-      } else {
-        // no_result / unknown: the run was interrupted (host died / app restarted)
-        // with NO evidence it failed on its own merits. Punishing the PRD here is
-        // the wrong call — it demands a manual flip and burns an Opus fix-plan on a
-        // job that never actually failed. Re-queue it (bounded) so an app restart
-        // self-recovers. Mirrors the transient-kill auto-retry on the live path.
-        const tries = j.orphanRetries ?? 0;
-        if (tries < ORPHAN_REQUEUE_CAP) {
-          resetJobFields(j, `orphaned: app restarted mid-run, re-queued (attempt ${tries + 1}/${ORPHAN_REQUEUE_CAP})${killNote}`);
-          j.orphanRetries = tries + 1;
-          console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → re-queued (${tries + 1}/${ORPHAN_REQUEUE_CAP})`);
-        } else {
-          j.status = 'failed';
-          j.exitCode = j.exitCode ?? 1;
-          j.error = `orphaned: app restarted while running, exhausted ${ORPHAN_REQUEUE_CAP} re-queue attempts${killNote}`;
-          j.finishedAt = new Date().toISOString();
-          delete j.runtime;
-          console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → failed (orphan retries exhausted)`);
-        }
-      }
+      const pid = j.runtime?.pid;
+      const killNote = pid ? ` (orphan pid=${pid}: dead)` : '';
+      applyOrphanOutcome(j, outcome, killNote);
+      console.log(`[scheduler] boot reconcile: slug=${j.slug} outcome=${outcome} → status=${j.status}`);
     }
   });
 
+  // Still-alive orphans: SIGTERM (+ killOrphanClaudePid's own deferred SIGKILL
+  // follow-up) now, but classification waits until BOOT_ORPHAN_KILL_GRACE_MS
+  // later — reading the log while the orphan might still be writing to it
+  // could misclassify an about-to-succeed run as no_result and double-run the
+  // same PRD (2026-05-21 incident this guard exists for).
+  for (const slug of deferredSlugs) {
+    const j = bootSnap.jobs.find((x) => x.slug === slug);
+    const pid = j?.runtime?.pid;
+    const bootRunId = j?.runId ?? null; // captured now — guards against reconciling a DIFFERENT later run of the same slug
+    if (!pid) continue;
+    const result = killOrphanClaudePid(pid);
+    const killNote = ` (orphan pid=${pid}: ${result})`;
+    if (result === 'killed') {
+      console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${slug} — deferring finalize ${BOOT_ORPHAN_KILL_GRACE_MS}ms`);
+    }
+    setTimeout(() => {
+      const logPath = j.runId ? path.join(RUNS_DIR, j.runId, `${j.slug}.log`) : null;
+      const outcome = logPath ? classifyRunOutcome(logPath) : 'unknown';
+      mutate((state) => {
+        const cur = state.jobs.find((x) => x.slug === slug);
+        // Race guard: bail if the job already resolved, OR if it's already been
+        // re-picked into a NEW run (different runId) within the grace window —
+        // that new run is not the boot orphan we SIGTERM'd and must not be
+        // touched by this stale classification.
+        if (!cur || cur.status !== 'running' || cur.runId !== bootRunId) return;
+        applyOrphanOutcome(cur, outcome, killNote);
+        console.log(`[scheduler] boot reconcile (deferred): slug=${slug} outcome=${outcome} → status=${cur.status}`);
+      }).catch((e) => console.error(`[scheduler] deferred boot reconcile failed for ${slug}:`, e?.message));
+    }, BOOT_ORPHAN_KILL_GRACE_MS).unref?.();
+  }
+
   // If we boot up while paused with a resumeAt in the past, clear it. This
   // happens when the app was closed across the reset window.
   const boot = await readQueue();
@@ -3074,6 +3176,16 @@ async function init() {
       utilization: cachedUtilization,
       consecutiveFailures,
     });
+
+    feedbackSweepTickCount++;
+    if (feedbackSweepDue(feedbackSweepTickCount, FEEDBACK_SWEEP_TICK_INTERVAL)) {
+      feedbackSweepTickCount = 0;
+      try {
+        sweepFeedback();
+      } catch (e) {
+        console.warn('[scheduler] feedback sweep failed', e?.message);
+      }
+    }
   }, 60_000);
   if (heartbeatInterval.unref) heartbeatInterval.unref();
 
@@ -3188,7 +3300,7 @@ const remote = {
   },
 
   // Exposes the module-level allocateParallelGroup (PRD 548) to callers that
-  // only hold the `remote` object (adminServer.cjs's create-prd route) —
+  // only hold the `remote` object (lib/prdCreate.cjs's create-prd route) —
   // reuses the same allocator the file-based /develop authoring path relies
   // on implicitly, rather than re-deriving NN here.
   allocateParallelGroup,
@@ -3216,4 +3328,36 @@ const remote = {
   },
 };
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, TRANSIENT_RETRY_CAP, buildScheduleStatePayload };
+// Registers the two job-management admin HTTP routes (PRD 689 — moved
+// verbatim out of the former standalone admin HTTP server module's
+// handleRequest, no behavior change) against an injected localAdminHttp.cjs
+// transport. `remoteObj` is accepted as a parameter (defaults to this
+// module's own `remote`) so the route logic stays testable in isolation
+// without booting Electron, matching that former module's original
+// dependency-injection pattern.
+function registerAdminRoutes(adminHttp, remoteObj = remote) {
+  adminHttp.registerRoute('GET', '/admin/scheduler/jobs', async (req, res) => {
+    const jobs = await remoteObj.listJobs();
+    sendJson(res, 200, jobs);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/reset-job', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    const slug = typeof parsed.slug === 'string' ? parsed.slug : null;
+    if (!slug) {
+      sendJson(res, 400, { ok: false, error: 'missing slug' });
+      return;
+    }
+    const result = await remoteObj.resetJob(slug);
+    sendJson(res, 200, result);
+  });
+}
+
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes };

package/src/main/templates/PRD_AUTHORING.md

@@ -328,7 +328,7 @@ loop but had no documented programmatic queueing path. This section is that path
 ### The `scheduler_create_prd` MCP tool
 
 Wraps `POST /admin/scheduler/create-prd` on the loopback admin API
-(`src/main/adminServer.cjs`, PRD 549) via `scripts/scheduler-mcp-server.cjs`, registered in this
+(`src/main/lib/localAdminHttp.cjs` + `src/main/lib/prdCreate.cjs`, PRD 549/688) via `scripts/scheduler-mcp-server.cjs`, registered in this
 repo's `.mcp.json` as the `session-manager-scheduler` MCP server. An external project wanting to
 call it from its own automation needs the equivalent MCP server registration pointing at this
 repo's `scripts/scheduler-mcp-server.cjs`, or can call the admin HTTP route directly (same
@@ -348,7 +348,7 @@ request/response shape) using the token at `~/.claude/session-manager/admin-api.
 | `slug` | string | no | kebab-case; derived from `title` if omitted |
 | `parallelGroup` | number | no | opt into an existing `NN` group instead of allocating a new one |
 
-**Return** (`{nn, filename, status}`, per `adminServer.cjs`):
+**Return** (`{nn, filename, status}`, per `prdCreate.cjs`'s registerAdminRoute):
 ```json
 { "nn": 550, "filename": "550-my-feature.md", "status": "queued" }
 ```
@@ -380,9 +380,9 @@ produces by hand.
 ### The app-must-be-running caveat (read this first)
 
 **`scheduler_create_prd` only works while the session-manager Electron app is running on this
-machine.** The admin server it depends on (`src/main/adminServer.cjs`) is hosted *inside* the
+machine.** The admin server it depends on (`src/main/lib/localAdminHttp.cjs`) is hosted *inside* the
 Electron process — it binds a loopback port and writes its token to
-`~/.claude/session-manager/admin-api.json` on app boot (see `CLAUDE.md`'s `adminServer.cjs`
+`~/.claude/session-manager/admin-api.json` on app boot (see `CLAUDE.md`'s `localAdminHttp.cjs`
 architecture entry) and stops existing the moment the app quits — it is not a standalone daemon.
 If the app is closed, `scheduler-mcp-server.cjs` cannot read a live port/token and every call
 returns the error `session-manager app is not running (admin API unreachable) — start it first`.