claude-code-session-manager 0.65.0 → 0.67.0

package/src/main/__tests__/scheduler-stall-per-project.test.cjs

@@ -0,0 +1,108 @@
+/**
+ * scheduler-stall-per-project.test.cjs — unit tests for computeStallSummary's
+ * per-project `stalled` verdict and findStaleQuarantinedJobs' age-based
+ * escalation.
+ *
+ * Covers the exact burrow-vs-others shape observed live: one project (burrow)
+ * holds only quarantined rows (0 running, 0 pending) while another project
+ * has running + pending work — the machine-wide `stalled` boolean reads
+ * false (masking burrow), but burrow's own byProject entry must read true.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/scheduler-stall-per-project.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { computeStallSummary, findStaleQuarantinedJobs, QUARANTINE_ESCALATE_MS } = require('../scheduler.cjs');
+
+test('computeStallSummary: burrow fully stalled (quarantined only) while another project is busy — machine-wide false, burrow true', () => {
+  const state = {
+    paused: null,
+    jobs: [
+      { slug: '821-a', cwd: '/home/bilko/Projects/burrow', status: 'quarantined' },
+      { slug: '822-b', cwd: '/home/bilko/Projects/burrow', status: 'quarantined' },
+      { slug: '823-c', cwd: '/home/bilko/Projects/burrow', status: 'quarantined' },
+      { slug: '824-d', cwd: '/home/bilko/Projects/burrow', status: 'quarantined' },
+      { slug: '900-e', cwd: '/home/bilko/Projects/other', status: 'running' },
+      { slug: '901-f', cwd: '/home/bilko/Projects/other', status: 'pending' },
+    ],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  assert.strictEqual(summary.stalled, false, 'machine-wide must NOT read stalled — other project is busy');
+  assert.strictEqual(summary.byProject['/home/bilko/Projects/burrow'].stalled, true, 'burrow must read stalled on its own');
+  assert.strictEqual(summary.byProject['/home/bilko/Projects/other'].stalled, false);
+});
+
+test('computeStallSummary: both projects busy — neither stalled', () => {
+  const state = {
+    paused: null,
+    jobs: [
+      { slug: 'a', cwd: '/p1', status: 'running' },
+      { slug: 'b', cwd: '/p2', status: 'pending' },
+    ],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  assert.strictEqual(summary.stalled, false);
+  assert.strictEqual(summary.byProject['/p1'].stalled, false);
+  assert.strictEqual(summary.byProject['/p2'].stalled, false);
+});
+
+test('computeStallSummary: both projects stalled — machine-wide AND both per-project read true', () => {
+  const state = {
+    paused: null,
+    jobs: [
+      { slug: 'a', cwd: '/p1', status: 'failed' },
+      { slug: 'b', cwd: '/p2', status: 'needs_review' },
+    ],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  assert.strictEqual(summary.stalled, true);
+  assert.strictEqual(summary.byProject['/p1'].stalled, true);
+  assert.strictEqual(summary.byProject['/p2'].stalled, true);
+});
+
+test('computeStallSummary: paused scheduler never reads stalled, machine-wide or per-project', () => {
+  const state = {
+    paused: { reason: 'rate_limit' },
+    jobs: [{ slug: 'a', cwd: '/p1', status: 'quarantined' }],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  assert.strictEqual(summary.stalled, false);
+  assert.strictEqual(summary.byProject['/p1'].stalled, false);
+});
+
+test('findStaleQuarantinedJobs: fires past threshold, not before', () => {
+  const now = Date.parse('2026-08-08T12:00:00.000Z');
+  const jobs = [
+    {
+      slug: 'fresh',
+      cwd: '/p1',
+      status: 'quarantined',
+      statusHistory: [{ to: 'quarantined', at: new Date(now - 1 * 60 * 60_000).toISOString() }],
+    },
+    {
+      slug: 'stale',
+      cwd: '/p1',
+      status: 'quarantined',
+      statusHistory: [{ to: 'quarantined', at: new Date(now - 25 * 60 * 60_000).toISOString() }],
+    },
+    {
+      slug: 'exactly-at-threshold',
+      cwd: '/p1',
+      status: 'quarantined',
+      statusHistory: [{ to: 'quarantined', at: new Date(now - QUARANTINE_ESCALATE_MS).toISOString() }],
+    },
+    { slug: 'no-history', cwd: '/p1', status: 'quarantined' },
+    { slug: 'not-quarantined', cwd: '/p1', status: 'pending' },
+  ];
+  const stale = findStaleQuarantinedJobs(jobs, now, QUARANTINE_ESCALATE_MS);
+  const slugs = stale.map((s) => s.slug).sort();
+  assert.deepStrictEqual(slugs, ['exactly-at-threshold', 'stale']);
+  assert.strictEqual(stale.find((s) => s.slug === 'stale').cwd, '/p1');
+});

package/src/main/agentLibrary.cjs

@@ -34,6 +34,25 @@ function parseTools(raw) {
 /** Filename-safe persona name: lowercase, hyphenated, matches the `.md` files on disk. */
 const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
 
+/** Sentinel `projects:` entry meaning "this agent's Action button shows in every project". */
+const ALL_PROJECTS = '*';
+
+/**
+ * Frontmatter values are single-line (see lib/prdFrontmatter.cjs) but an
+ * Action's opening instruction is genuinely multi-line prose (the builder
+ * action is `/builder\n\n<instruction>`). Encode newlines as a literal `\n`
+ * two-char sequence on the way out, decode on the way in — one place, so the
+ * round-trip is structural rather than something each caller remembers.
+ */
+function encodeLine(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/\r?\n/g, '\\n');
+}
+
+function decodeLine(s) {
+  if (!s) return '';
+  return String(s).replace(/\\([\\n])/g, (_m, c) => (c === 'n' ? '\n' : '\\'));
+}
+
 /**
  * Serializes a persona's frontmatter + body back to `.md` file text.
  * `tags` is a Claude-Code-agnostic extension of the frontmatter (Claude Code
@@ -41,14 +60,25 @@ const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
  * this persona is associated with, so Agent Library and Tag Library can each
  * assign/remove the relationship from either side. Stored the same
  * comma-list way as `tools` for one parser to cover both.
+ *
+ * `projects` / `action` / `actionLabel` are the same kind of extension, for
+ * the Sessions workspace's per-project **Action buttons**: `projects` is the
+ * list of project cwds (or the `*` sentinel = every project) whose Sessions
+ * toolbar shows a one-click button for this agent, `action` is the opening
+ * instruction that button sends into the new session, and `actionLabel`
+ * overrides the button's caption (defaults to the persona name). Claude Code
+ * ignores all three; only this app reads them.
  */
-function serializePersona({ name, description, tools, model, color, tags, title, body }) {
+function serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body }) {
   const lines = ['---', `name: ${name}`];
   if (description) lines.push(`description: ${description}`);
   if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
   if (model && model !== 'inherit') lines.push(`model: ${model}`);
   if (color) lines.push(`color: ${color}`);
   if (tags && tags.length) lines.push(`tags: ${tags.join(', ')}`);
+  if (projects && projects.length) lines.push(`projects: ${projects.join(', ')}`);
+  if (action) lines.push(`action: ${encodeLine(action)}`);
+  if (actionLabel) lines.push(`actionLabel: ${encodeLine(actionLabel)}`);
   if (title) lines.push(`title: ${title}`);
   lines.push('---', '');
   return lines.join('\n') + (body || '').trim() + '\n';
@@ -67,6 +97,9 @@ async function savePersona({
   model,
   color,
   tags,
+  projects,
+  action,
+  actionLabel,
   title,
   body,
   globalDir = path.join(os.homedir(), '.claude', 'agents'),
@@ -77,7 +110,7 @@ async function savePersona({
     throw new Error('agent name must be lowercase, hyphenated (e.g. "my-agent")');
   }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  const text = serializePersona({ name, description, tools, model, color, tags, title, body });
+  const text = serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
@@ -203,6 +236,9 @@ async function listPersonas({
       model: fm.model || null,
       color: fm.color || null,
       tags: parseTools(fm.tags),
+      projects: parseTools(fm.projects),
+      action: decodeLine(fm.action) || null,
+      actionLabel: decodeLine(fm.actionLabel) || null,
       title: fm.title || null,
       path: real,
       body: body.trim(),
@@ -220,5 +256,7 @@ module.exports = {
   savePersona,
   deletePersona,
   removeOverride,
+  serializePersona,
   PERSONA_NAME_RE,
+  ALL_PROJECTS,
 };

package/src/main/health.cjs

@@ -14,6 +14,7 @@ const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
+const { computeStallSummary } = require('./scheduler.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
@@ -131,6 +132,55 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
   };
 }
 
+// computeProjectProblemCounts(jobs) → { [cwd]: { failed, needs_review, quarantined } }
+//
+// health.cjs's machine-wide `failed` count answered "is the machine stuck",
+// never "is any ONE project stuck" — a single project with 4 quarantined
+// PRDs and nothing else running was invisible in a rollup dominated by other
+// projects' healthy jobs. Breaks down every non-terminal-problem status
+// (failed/needs_review/quarantined — deliberately NOT 'completed'/'running'/
+// 'pending'/'investigating', which are not problems) by project cwd.
+function computeProjectProblemCounts(jobs) {
+  const byProject = {};
+  for (const j of jobs || []) {
+    if (j.status !== 'failed' && j.status !== 'needs_review' && j.status !== 'quarantined') continue;
+    const cwd = j.cwd || '(unknown)';
+    byProject[cwd] = byProject[cwd] || { failed: 0, needs_review: 0, quarantined: 0 };
+    byProject[cwd][j.status] += 1;
+  }
+  return byProject;
+}
+
+// evaluatePerProjectStall(stallSummary, lastRunAtIso, now, thresholdMs) →
+// { [cwd]: { stalled, pastThreshold?, ageMs?, caveat? } }
+//
+// computeStallSummary's per-project `stalled` flag (scheduler.cjs) is a
+// point-in-time verdict with no duration attached — a project can flip
+// stalled/unstalled within a single tick as work completes, so flagging RED
+// the instant it's true would false-trip on ordinary queue churn. There is
+// no per-project lastRunAt persisted (only a machine-wide one), so this
+// reuses that machine-wide timestamp as the best available "has the
+// scheduler ticked recently at all" signal, gated per-project by whether
+// THAT project currently holds stalled work.
+function evaluatePerProjectStall(stallSummary, lastRunAtIso, now, thresholdMs) {
+  const lastRunAt = lastRunAtIso ? Date.parse(lastRunAtIso) : null;
+  const results = {};
+  for (const cwd of Object.keys(stallSummary?.byProject || {})) {
+    const counts = stallSummary.byProject[cwd];
+    if (!counts.stalled) {
+      results[cwd] = { stalled: false };
+      continue;
+    }
+    if (lastRunAt == null || Number.isNaN(lastRunAt)) {
+      results[cwd] = { stalled: true, pastThreshold: false, caveat: 'no-lastRunAt' };
+      continue;
+    }
+    const ageMs = now - lastRunAt;
+    results[cwd] = { stalled: true, pastThreshold: ageMs >= thresholdMs, ageMs };
+  }
+  return results;
+}
+
 // Pure evaluator over migratePrds()'s { moved, skipped, unresolved } result —
 // kept separate from the fs-touching check() call site so it's directly
 // unit-testable, matching evaluateTickLiveness's pattern.
@@ -222,18 +272,42 @@ async function check() {
     const failedCount = Object.values(queueState.jobs || {}).filter(
       (j) => j.status === 'failed'
     ).length;
+    const needsReviewCount = Object.values(queueState.jobs || {}).filter(
+      (j) => j.status === 'needs_review'
+    ).length;
+    const quarantinedCount = Object.values(queueState.jobs || {}).filter(
+      (j) => j.status === 'quarantined'
+    ).length;
     const heartbeatPath = path.join(
       os.homedir(),
       '.claude/session-manager/scheduler-heartbeat.log'
     );
     const heartbeat = readFreshHeartbeat(heartbeatPath);
     const liveness = evaluateTickLiveness(queueState, heartbeat, Date.now(), runningCount);
+
+    // Per-project rollup (PRD: monitoring must not collapse per-project
+    // reality into one machine-wide boolean — see computeStallSummary /
+    // computeProjectProblemCounts headers). A project holding ONLY
+    // failed/needs_review/quarantined rows (0 running, 0 pending) never
+    // trips evaluateTickLiveness above, since that check requires actual
+    // pending work — this is what let the burrow project go dark.
+    const stallSummary = computeStallSummary(queueState);
+    const now = Date.now();
+    const perProjectStall = evaluatePerProjectStall(stallSummary, queueState.lastRunAt, now, TICK_STALL_THRESHOLD_MS);
+    const projectsPastThreshold = Object.entries(perProjectStall)
+      .filter(([, v]) => v.pastThreshold)
+      .map(([cwd]) => cwd);
+
     status.components.scheduler_queue = {
-      ok: !liveness.stalled,
+      ok: !liveness.stalled && projectsPastThreshold.length === 0,
       path: queuePath,
       jobs: Object.keys(queueState.jobs || {}).length,
       running: runningCount,
       failed: failedCount,
+      needsReview: needsReviewCount,
+      quarantined: quarantinedCount,
+      byProject: computeProjectProblemCounts(queueState.jobs),
+      perProjectStall,
       tickLiveness: liveness.reason,
     };
     if (liveness.stalled) {
@@ -249,6 +323,18 @@ async function check() {
           ? `Tick hasn't advanced in a while but scheduler-heartbeat.log is missing/stale, so current billing utilization can't be checked — cannot rule out a legitimate when-available hold`
           : 'No lastRunAt recorded yet — cannot assess tick liveness';
     }
+    if (projectsPastThreshold.length > 0) {
+      status.components.scheduler_queue.stalledProjects = projectsPastThreshold;
+      for (const cwd of projectsPastThreshold) {
+        const ageMin = Math.round(perProjectStall[cwd].ageMs / 60_000);
+        const counts = status.components.scheduler_queue.byProject[cwd] || {};
+        status.issues.push(
+          `Project fully stalled: ${cwd} — 0 running, 0 pending, only problem jobs `
+          + `(failed=${counts.failed ?? 0} needs_review=${counts.needs_review ?? 0} quarantined=${counts.quarantined ?? 0}), `
+          + `no scheduler tick in ~${ageMin}m (threshold ${Math.round(TICK_STALL_THRESHOLD_MS / 60_000)}m)`
+        );
+      }
+    }
   } catch (e) {
     if (e.code !== 'ENOENT') {
       status.issues.push(`Scheduler queue unreadable: ${e.message}`);
@@ -422,4 +508,13 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { check, evaluateTickLiveness, readFreshHeartbeat, evaluatePrdMigrationHealth, TICK_STALL_THRESHOLD_MS, HEARTBEAT_STALE_MS };
+module.exports = {
+  check,
+  evaluateTickLiveness,
+  readFreshHeartbeat,
+  evaluatePrdMigrationHealth,
+  computeProjectProblemCounts,
+  evaluatePerProjectStall,
+  TICK_STALL_THRESHOLD_MS,
+  HEARTBEAT_STALE_MS,
+};

package/src/main/index.cjs

@@ -26,6 +26,7 @@ const voiceWizard = require('./voiceWizard.cjs');
 const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
+const prdAdminRoutes = require('./lib/prdAdminRoutes.cjs');
 const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
@@ -37,6 +38,7 @@ const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
+prdAdminRoutes.registerAdminRoute(adminHttp, scheduler.remote);
 chatRunner.registerAdminRoute(adminHttp);
 const supervisor = require('./supervisor.cjs');
 const watchers = require('./watchers.cjs');

package/src/main/ipcSchemas.cjs

@@ -327,6 +327,62 @@ const scheduleRetagPrd = z.object({
   items: z.array(scheduleRetagItem).min(1).max(500),
 });
 
+// ──────────────────────────────────────────── Admin API — PRD lifecycle (PRD 1024)
+//
+// GET routes parse their input from URLSearchParams (all values arrive as
+// strings), so numeric/array fields aren't accepted here — only slug/cwd/
+// epicId/status, matching what a query string can actually carry.
+const adminListPrdsQuery = z.object({
+  cwd: z.string().min(1).max(4096).optional(),
+  epicId: z.string().min(1).max(200).optional(),
+  status: z.string().min(1).max(40).optional(),
+});
+
+const adminGetPrdQuery = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
+});
+
+// Partial frontmatter patch for update-prd — same recognized-key set as
+// prdFrontmatter.cjs's parsePrdFile/serializePrdFile round-trip pair. Every
+// field optional; the route refuses an empty patch+no-body request via the
+// top-level .refine below.
+const adminPrdFrontmatterPatch = z.object({
+  title: z.string().min(1).max(200).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  estimateMinutes: z.number().int().min(1).max(100000).optional(),
+  parallelGroup: z.number().int().min(0).max(999999).optional(),
+  sourcePromptId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  sourceTabId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // 'discussion' deliberately excluded: matches prdFrontmatter.cjs's
+  // parsePrdFile, which never parses that value for a PRD's tag key (a
+  // discussion-tagged Epic never reaches PRD authoring).
+  tag: z.enum(['feature', 'bug', 'build']).optional(),
+  // Provenance stamp (PRD-authoring lockdown). Free-text rather than an enum
+  // — 'scheduler-api' (create-time) and 'legacy-adopted' (migration/manual
+  // adopt) are the two values this codebase writes today, but the field
+  // itself is descriptive, not a closed set.
+  createdVia: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  issuedAt: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+});
+
+const adminUpdatePrd = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
+  frontmatter: adminPrdFrontmatterPatch.optional(),
+  body: z.string().refine(
+    (s) => Buffer.byteLength(s, 'utf8') <= PRD_WRITE_MAX_BYTES,
+    `body must be ≤ ${PRD_WRITE_MAX_BYTES} bytes`,
+  ).optional(),
+}).refine(
+  (it) => (it.frontmatter && Object.keys(it.frontmatter).length > 0) || it.body !== undefined,
+  'at least one of frontmatter or body is required',
+);
+
+const adminCancelJob = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+});
+
 // ──────────────────────────────────────────── Projects
 const ENCODED_SLUG_RE = /^[A-Za-z0-9._-]+$/;
 
@@ -812,6 +868,10 @@ module.exports = {
     schedulerCreatePrd,
     scheduleArchivePrd,
     scheduleRetagPrd,
+    adminListPrdsQuery,
+    adminGetPrdQuery,
+    adminUpdatePrd,
+    adminCancelJob,
     setConfigSchema,
     setSessionSlotsSchema,
     shellOpen,

package/src/main/lib/localAdminHttp.cjs

@@ -151,17 +151,24 @@ function createAdminHttp() {
       sendJson(res, 401, { ok: false, error: 'unauthorized' });
       return;
     }
-    if (req.method === 'GET' && req.url === HEALTH_PATH) {
+    // Route lookup is keyed by pathname only — req.url carries the raw query
+    // string too, which would otherwise never match a registered route (every
+    // route before PRD 1024 was query-free, so this was a latent gap, not a
+    // behavior change for them). `query` is handed to the route handler as a
+    // third argument (URLSearchParams) for routes that need it (e.g. GET
+    // /admin/scheduler/prds?cwd=&epicId=&status=).
+    const urlObj = new URL(req.url, 'http://127.0.0.1');
+    if (req.method === 'GET' && urlObj.pathname === HEALTH_PATH) {
       sendJson(res, 200, { ok: true });
       return;
     }
     try {
-      const handler = routes.get(`${req.method} ${req.url}`);
+      const handler = routes.get(`${req.method} ${urlObj.pathname}`);
       if (!handler) {
         sendJson(res, 404, { ok: false, error: 'not found' });
         return;
       }
-      await handler(req, res);
+      await handler(req, res, urlObj.searchParams);
     } catch (e) {
       sendJson(res, 500, { ok: false, error: e?.message ?? 'internal error' });
     }

package/src/main/lib/prdAdminRoutes.cjs

@@ -0,0 +1,175 @@
+/**
+ * prdAdminRoutes.cjs — admin HTTP routes closing the PRD-lifecycle capability
+ * gap (PRD 1024, step 1 of locking the PRD entity behind the scheduler
+ * service boundary — see that PRD's Goal). Before this file, the admin API
+ * exposed only create-prd/jobs/reset-job/send-prompt: there was no way to
+ * READ, LIST, EDIT, ARCHIVE, or CANCEL a PRD/job over HTTP, which is exactly
+ * why direct filesystem access to session-manager-operations/scheduler/ was
+ * still sanctioned. This file plumbs those operations to HTTP; it adds no
+ * enforcement/denial of direct access — that's the dependent PRD's job (see
+ * this PRD's "Out of scope").
+ *
+ * Every route here reuses an existing verified implementation rather than
+ * reimplementing it:
+ *   - list/get/update/cancel delegate to scheduler.cjs's `remote` object
+ *     (job-status-aware; remote already owns the PRD-dir search + symlink
+ *     defense patterns these need)
+ *   - archive/retag delegate to queueOps.cjs's archiveMany/retagMany
+ *     directly (job-status-agnostic bulk file ops; already used by the
+ *     renderer's schedule:archive-prd/schedule:retag-prd IPC handlers)
+ *
+ * Registered against the same injected localAdminHttp.cjs transport as
+ * scheduler.cjs's registerAdminRoutes and prdCreate.cjs's registerAdminRoute
+ * (see index.cjs) — auth, loopback-only binding, and the bearer-token
+ * lifecycle are all the transport's job, not this file's.
+ */
+'use strict';
+
+const { schemas } = require('../ipcSchemas.cjs');
+const { readBody, sendJson } = require('./localAdminHttp.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
+const queueOps = require('../queueOps.cjs');
+
+function parseJsonBody(raw) {
+  try {
+    return { ok: true, value: raw ? JSON.parse(raw) : {} };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * registerAdminRoute(adminHttp, remote) — `remote` is scheduler.cjs's
+ * `remote` object, injected (not required directly) so this file stays
+ * testable without booting Electron, matching prdCreate.cjs's and
+ * scheduler.cjs's own registerAdminRoute(s) pattern.
+ */
+function registerAdminRoute(adminHttp, remote) {
+  adminHttp.registerRoute('GET', '/admin/scheduler/prds', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminListPrdsQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    const prds = await remote.listPrds(input);
+    sendJson(res, 200, { ok: true, prds });
+  });
+
+  adminHttp.registerRoute('GET', '/admin/scheduler/prd', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminGetPrdQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.getPrdParsed(input.slug, input.cwd);
+    if (!result.ok) {
+      sendJson(res, 404, result);
+      return;
+    }
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/update-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminUpdatePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.updatePrd(input);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : /status is/i.test(result.error ?? '') ? 409 : 400;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_prd_update', { route: '/admin/scheduler/update-prd', slug: input.slug, cwd: input.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/archive-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleArchivePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.archiveMany(input.slugs);
+    // Audit only the slugs that actually archived — archiveMany's `results`
+    // array carries the real per-slug outcome; logging every requested slug
+    // regardless of whether it succeeded would misrepresent a partial-failure
+    // batch as a clean one in audit-log.jsonl.
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_archive', { route: '/admin/scheduler/archive-prd', slug: r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/cancel-job', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminCancelJob.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.cancelJob(input.slug);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : 409;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_job_cancel', { route: '/admin/scheduler/cancel-job', slug: input.slug, cwd: result.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/retag-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleRetagPrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.retagMany(input.items);
+    // Audit only the items that actually retagged (see the archive-prd route
+    // above for why this must read result.results rather than the request).
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_retag', { route: '/admin/scheduler/retag-prd', slug: r.newSlug ?? r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+}
+
+module.exports = { registerAdminRoute };