claude-code-session-manager 0.64.0 → 0.66.0

package/src/main/__tests__/scheduler-reconcile-invalid-repair.test.cjs

@@ -0,0 +1,203 @@
+/**
+ * scheduler-reconcile-invalid-repair.test.cjs — end-to-end reproduction of
+ * the 2026-08-07 1021/1022 incident: a queue.json row with `"status":
+ * "queued"` (a value outside ScheduleJobStatus) sat unpicked for 4+ hours.
+ *
+ * queueStore.shapeJobs (scheduleJobSchema.cjs, landed by a prior PRD)
+ * already quarantines such a row into `invalidJobs` on read rather than
+ * passing it through — but reconcile() itself was still add-only (`if
+ * (seen.has(slug)) continue`), so a quarantined row was never repaired, only
+ * silently absent from state.jobs with no log of what its bad status had
+ * been.
+ *
+ * This test exercises the real quarantine path (queueStore.shapeJobs on the
+ * raw incident JSON) against a real on-disk PRD, runs the real reconcile(),
+ * and asserts: computeStallSummary flags the PRE-repair state as stalled,
+ * reconcile() repairs the row to 'pending', logs the repair at warn level,
+ * and audits it.
+ *
+ * HOME-isolated (mirrors scheduler-prd-missing-skip.test.cjs): stub HOME to
+ * a mkdtemp dir before requiring scheduler.cjs/queueStore.cjs, and register
+ * the fixture project as "active" via a fake ~/.claude/projects transcript —
+ * reconcile's PRD/history discovery (prdLocations.cjs, queueHistory.cjs)
+ * only scans cwds it can find that way.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reconcile-invalid-repair.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-repair-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+
+  if (!scheduler.PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${scheduler.PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  const prdsDir = path.join(opsRoot, 'scheduler', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { cwd, prdsDir, stateDir };
+}
+
+test('reconcile() repairs a queue row with an invalid status back to pending, logs, and audits it', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-reconcile-repair-proj-');
+  try {
+    // Real on-disk PRD (its file location is the reconcile source of truth).
+    fs.writeFileSync(
+      path.join(prdsDir, '1021-fix-the-thing.md'),
+      '---\ntitle: Fix the thing\ncwd: ' + cwd + '\nestimateMinutes: 15\n---\n\n# Goal\nFix it.\n',
+      'utf8',
+    );
+
+    // The exact incident shape: a row whose status is 'queued', outside
+    // ScheduleJobStatus entirely.
+    const badRow = {
+      slug: '1021-fix-the-thing',
+      title: 'Fix the thing',
+      cwd,
+      status: 'queued',
+      runId: null,
+      startedAt: null,
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    const queuePath = path.join(stateDir, 'queue.json');
+    fs.writeFileSync(queuePath, JSON.stringify({ jobs: [badRow] }, null, 2), 'utf8');
+
+    // Exercise the REAL quarantine gate (same one queueStore.readMerged runs
+    // at boot/every IPC read) rather than hand-building invalidJobs.
+    const { jobs, invalid } = queueStore.shapeJobs(fs.readFileSync(queuePath, 'utf8'), queuePath);
+    expect(jobs.length).toBe(0); // the bad row never reaches state.jobs
+    expect(invalid.length).toBe(1);
+    expect(invalid[0].slug).toBe(badRow.slug);
+    expect(invalid[0].row.status).toBe('queued');
+
+    const state = { jobs, invalidJobs: invalid, paused: null };
+
+    // Stall detector must flag the PRE-repair state: the queue holds a
+    // (quarantined) job but nothing is running or pending and it isn't
+    // paused — this is exactly the condition that was silent for 4+ hours.
+    const preRepairStall = scheduler.computeStallSummary(state);
+    expect(preRepairStall.stalled).toBe(true);
+    expect(preRepairStall.total).toBe(1);
+    expect(preRepairStall.running).toBe(0);
+    expect(preRepairStall.pending).toBe(0);
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // scheduler.cjs destructures `appendAuditEvent` out of auditLog.cjs at
+    // require time, so spying on the module's export property after the
+    // fact wouldn't intercept scheduler.cjs's already-bound reference —
+    // assert against the real (tmpHome-isolated) audit log file instead.
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+    expect(AUDIT_LOG_PATH.startsWith(tmpHome)).toBe(true);
+
+    queueStore.bustCwdCache();
+    await scheduler.reconcile(state);
+
+    const repaired = state.jobs.find((j) => j.slug === badRow.slug);
+    expect(repaired).toBeDefined();
+    expect(repaired.status).toBe('pending');
+
+    const warnedRepair = warnSpy.mock.calls.some((args) =>
+      String(args[0]).includes('repaired invalid queue row') && String(args[0]).includes(badRow.slug),
+    );
+    expect(warnedRepair).toBe(true);
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    const auditedRepair = auditLines.some(
+      (rec) => rec.kind === 'scheduler_row_repaired' && rec.slug === badRow.slug && rec.oldStatus === 'queued',
+    );
+    expect(auditedRepair).toBe(true);
+
+    // Post-repair, the same condition must no longer read as stalled.
+    const postRepairStall = scheduler.computeStallSummary(state);
+    expect(postRepairStall.stalled).toBe(false);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() does not resurrect an invalid row whose slug already has a terminal history record', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-reconcile-repair-done-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '1022-already-done.md'),
+      '---\ntitle: Already done\ncwd: ' + cwd + '\nestimateMinutes: 15\n---\n\n# Goal\nDone.\n',
+      'utf8',
+    );
+
+    const badRow = {
+      slug: '1022-already-done',
+      title: 'Already done',
+      cwd,
+      status: 'queued',
+      runId: 'run-xyz',
+      startedAt: new Date().toISOString(),
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    const queuePath = path.join(stateDir, 'queue.json');
+    fs.writeFileSync(queuePath, JSON.stringify({ jobs: [badRow] }, null, 2), 'utf8');
+
+    const { jobs, invalid } = queueStore.shapeJobs(fs.readFileSync(queuePath, 'utf8'), queuePath);
+    expect(invalid.length).toBe(1);
+
+    const state = { jobs, invalidJobs: invalid, paused: null };
+
+    // A terminal record already exists for this slug — reconcile must never
+    // repair the corrupted row back into a runnable 'pending' state on top
+    // of already-shipped work.
+    fs.writeFileSync(
+      path.join(stateDir, 'history.jsonl'),
+      JSON.stringify({ slug: badRow.slug, status: 'completed', finishedAt: new Date().toISOString(), runId: 'run-xyz' }) + '\n',
+      'utf8',
+    );
+
+    queueStore.bustCwdCache();
+    await scheduler.reconcile(state);
+
+    expect(state.jobs.find((j) => j.slug === badRow.slug)).toBeUndefined();
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/scheduler-reconcile-quarantine.test.cjs

@@ -0,0 +1,196 @@
+/**
+ * scheduler-reconcile-quarantine.test.cjs — PRD-authoring-lockdown provenance
+ * gate: reconcile() must never turn a discovered PRD with no `createdVia`
+ * frontmatter into a runnable 'pending' queue row. It quarantines it instead
+ * (a distinct, non-runnable status), logs a warning naming the file, and
+ * audits the event — then, once the file is stamped (the Scheduler tab's
+ * "adopt PRD" action / scheduler_update_prd, both routed through
+ * remote.updatePrd), promotes the row to 'pending' on the very next pass.
+ *
+ * Mirrors scheduler-reconcile-invalid-repair.test.cjs's HOME-isolation setup.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reconcile-quarantine.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let scheduler;
+let queueStore;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-quarantine-home-'));
+  process.env.HOME = tmpHome;
+
+  scheduler = require('../scheduler.cjs');
+  queueStore = require('../lib/queueStore.cjs');
+
+  if (!scheduler.PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${scheduler.PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function registerActiveProject(cwd) {
+  const projectsDir = path.join(tmpHome, '.claude', 'projects');
+  const slugDir = path.join(projectsDir, `fake-project-slug-${path.basename(cwd)}`);
+  fs.mkdirSync(slugDir, { recursive: true });
+  fs.writeFileSync(path.join(slugDir, 'transcript.jsonl'), JSON.stringify({ cwd }) + '\n');
+}
+
+function makeFixtureProject(prefix) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  registerActiveProject(cwd);
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  // Epic-scoped, not the retired flat dir: a flat PRD with no live queue row
+  // gets swept into prds-archived/ by reconcile()'s own consolidation pass
+  // (see consolidateAllFlatPrds) BEFORE it's ever scanned as a discoverable
+  // PRD — exactly the scenario every test below needs to observe, so the
+  // flat layout would race the very thing under test.
+  const prdsDir = path.join(opsRoot, 'scheduler', 'epics', 'test-epic-1', 'prds');
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  return { cwd, prdsDir, stateDir };
+}
+
+test('reconcile() quarantines a newly-discovered PRD with no createdVia provenance', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-new-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9001-hand-written.md'),
+      `---\ntitle: Hand-written PRD\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9001-hand-written');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('quarantined');
+
+    const warned = warnSpy.mock.calls.some((args) =>
+      String(args[0]).includes('quarantining unstamped PRD') && String(args[0]).includes('9001-hand-written'),
+    );
+    expect(warned).toBe(true);
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    expect(auditLines.some((rec) => rec.kind === 'prd_quarantined' && rec.slug === '9001-hand-written')).toBe(true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() queues a newly-discovered PRD stamped with createdVia as pending, not quarantined', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-stamped-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9002-api-written.md'),
+      `---\ntitle: API-written PRD\ncwd: ${cwd}\nestimateMinutes: 15\ncreatedVia: scheduler-api\nissuedAt: 2026-08-07T00:00:00.000Z\n---\n\n# Goal\nDo the thing.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9002-api-written');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() exempts a fix-plan PRD (NN-fix-*) from quarantine even with no createdVia', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-fixplan-');
+  try {
+    fs.writeFileSync(
+      path.join(prdsDir, '9003-fix-something.md'),
+      `---\ntitle: Fix something\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nHeal it.\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [] }, null, 2), 'utf8');
+
+    queueStore.bustCwdCache();
+    const state = { jobs: [], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9003-fix-something');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() adopts a quarantined row to pending once its PRD file is stamped', async () => {
+  const { cwd, prdsDir, stateDir } = makeFixtureProject('sm-quarantine-adopt-');
+  try {
+    const prdPath = path.join(prdsDir, '9004-adopt-me.md');
+    fs.writeFileSync(
+      prdPath,
+      `---\ntitle: Adopt me\ncwd: ${cwd}\nestimateMinutes: 15\n---\n\n# Goal\nAdopt.\n`,
+      'utf8',
+    );
+    const quarantinedRow = {
+      slug: '9004-adopt-me',
+      title: 'Adopt me',
+      cwd,
+      status: 'quarantined',
+      runId: null,
+      startedAt: null,
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    };
+    fs.writeFileSync(path.join(stateDir, 'queue.json'), JSON.stringify({ jobs: [quarantinedRow] }, null, 2), 'utf8');
+
+    // Simulate the adopt action: stamp the file via the same update-prd
+    // logic the IPC handler/admin route call (parsePrdFile/serializePrdFile
+    // round-trip), rather than hand-writing raw text, to exercise the real
+    // round-trip path this feature depends on.
+    const { parsePrdFile, serializePrdFile } = require('../lib/prdFrontmatter.cjs');
+    const raw = fs.readFileSync(prdPath, 'utf8');
+    const { frontmatter: fm, body } = parsePrdFile(raw);
+    fm.createdVia = 'legacy-adopted';
+    fm.issuedAt = '2026-08-07T01:00:00.000Z';
+    fs.writeFileSync(prdPath, serializePrdFile(fm, body), 'utf8');
+
+    const { AUDIT_LOG_PATH } = require('../lib/auditLog.cjs');
+    queueStore.bustCwdCache();
+    const state = { jobs: [quarantinedRow], invalidJobs: [], paused: null };
+    await scheduler.reconcile(state);
+
+    const row = state.jobs.find((j) => j.slug === '9004-adopt-me');
+    expect(row).toBeDefined();
+    expect(row.status).toBe('pending');
+
+    const auditLines = fs.readFileSync(AUDIT_LOG_PATH, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    expect(auditLines.some((rec) => rec.kind === 'scheduler_prd_adopted' && rec.slug === '9004-adopt-me')).toBe(true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

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/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' });
     }