claude-code-session-manager 0.65.0 → 0.67.0

package/plugins/session-manager-dev/skills/develop/SKILL.md

@@ -57,11 +57,15 @@ scheduler isn't decomposition need, it's model economics: keep the interactive m
 (an expensive planner-tier model) focused on discussion and decisions, and let a cheaper executor
 model do the implementing as a headless `claude -p` job.
 
-**Only execution is delegated — authoring never is.** Write every PRD's markdown yourself, in
-the main loop: the thinking, decomposition, scope, and acceptance criteria are the planner's
-job. Do not spawn a subagent to draft a PRD or otherwise hand off the writing/thinking — that
-defeats the point of keeping planning on the expensive model. The scheduled `claude -p` job is
-the only step that runs on the cheaper executor.
+**Only execution is delegated — authoring never is.** Do the thinking — decomposition, scope,
+title, goal, and acceptance criteria — yourself, in the main loop; that's what "authoring" means
+here, and it's non-negotiable regardless of which mechanism ends up putting bytes on disk. Do
+not spawn a subagent to draft a PRD or otherwise hand off the writing/thinking — that defeats the
+point of keeping planning on the expensive model. Once you've composed the PRD yourself, submit
+it through `scheduler_create_prd` (the MCP tool — see step 4's "PRD structure and location"
+below): that tool call is the sanctioned path from your own composed content to a file on disk,
+not a second author. The scheduled `claude -p` job remains the only step that runs on the
+cheaper executor.
 
 ## Standards (single source of truth)
 
@@ -206,8 +210,20 @@ can't load skills.
      separate PRDs into one oversized one; if the sub-task groups would each take real time on
      their own, that's a signal to split into a chain link instead of one bloated PRD.
 
-   **Prefer creating each PRD via the `scheduler_create_prd` MCP tool**
-   (`mcp__session-manager-scheduler__scheduler_create_prd`) over hand-writing the file. Its input
+   **Preflight — confirm the tool is even in your tool list before you start composing PRDs.**
+   Check for `mcp__session-manager-scheduler__scheduler_create_prd` in your available tools as
+   the very first thing you do in this step, before any drafting — catching a missing tool here
+   costs nothing; catching it after you've already composed and written PRD bodies means
+   discarding that work. If it's absent, see "Two failure modes" immediately below — case (b),
+   not the reachable-but-erroring fallback.
+
+   **`scheduler_create_prd` is the ONLY sanctioned way to author a PRD — not a preference, a
+   rule.** Every PRD reaches disk through the MCP tool
+   (`mcp__session-manager-scheduler__scheduler_create_prd`). Hand-writing the file directly is a
+   degraded, LAST-RESORT fallback (below) reserved for the single case where the tool is present
+   but errors as unreachable — never a co-equal alternative to reach for out of habit or
+   convenience, and never applicable when the tool isn't in your list at all (see "Two failure
+   modes" below). Its input
    (`title`, `cwd`, `estimateMinutes`, `goal`, `acceptanceCriteria[]`, `implementationNotes`,
    `outOfScope[]`) maps directly onto the sections below — pass them straight through. **Always
    pass `sourcePromptId` explicitly, set to the `<epic-id>` resolved in the Epic-gated step
@@ -220,9 +236,38 @@ can't load skills.
    `parallelGroup` is DEPRECATED and ignored — express ordering with the `dependsOn` input
    (slugs that must complete first); independent PRDs simply omit it and may run in parallel.
 
-   **Fallback — only when the tool errors with "app not running" / admin API unreachable**
-   (the session-manager Electron app must be running for this MCP tool to work; if it isn't,
-   don't block on it): compute the highest in-use number deterministically yourself — never
+   **Two failure modes — do not conflate them. They have opposite correct responses.**
+
+   - **(a) Tool PRESENT but ERRORS as "app not running" / admin API unreachable.** The tool
+     shows up in your tool list (`mcp__session-manager-scheduler__scheduler_create_prd` is
+     callable), but calling it fails because the session-manager Electron app that hosts the
+     admin API isn't running right now. This is the ONLY case the manual-write fallback below
+     covers. Do not use this path when the tool is reachable but merely returned a validation
+     error (bad frontmatter, unresolvable Epic, etc.) — fix the input and retry the tool; a
+     validation error is not "the app is not running."
+   - **(b) Tool ABSENT from your tool list entirely.** You never see
+     `mcp__session-manager-scheduler__scheduler_create_prd` offered at all — there is no error to
+     catch, because the tool call is never attempted. This means the `session-manager-scheduler`
+     MCP server is not registered for the project you're running against — a **misconfiguration**,
+     not "the app is offline." **STOP. Do not write any PRD file, hand-authored or otherwise.**
+     Report to the human, by name: "the `session-manager-scheduler` MCP tool is not available in
+     this session — the server isn't registered for this project." Point them at the fix: it
+     should be registered once at USER scope (`claude mcp add session-manager-scheduler --scope
+     user -- node <path-to-session-manager-repo>/scripts/scheduler-mcp-server.cjs`, or run
+     `scripts/install-scheduler-mcp-user-scope.sh` from the session-manager repo) so every
+     project gets the tool without a per-repo `.mcp.json` edit — do not work around a missing
+     tool by hand-writing the file, and do not add a project-local `.mcp.json` entry yourself as
+     a substitute; that's the human's call and re-introduces the per-repo drift this fix removes.
+
+   **Fallback for case (a) only.** This is a deliberate bypass of the service boundary, not a
+   shortcut: using it means the frontmatter validation, atomic `NN` allocation, standards-pointer
+   insertion, and Epic-existence check that `scheduler_create_prd` normally performs did not
+   run. **You MUST call this out, visibly, in your report** — state plainly that the app wasn't
+   running, that you hand-authored the PRD file directly instead of using the tool, name the
+   exact file, and flag it for human verification (this bypass is also what
+   `scripts/audit-ops-hygiene.cjs` and the `ops-sweep` skill look for and report as a hygiene
+   finding, independent of your own report).
+   When you do use it: compute the highest in-use number deterministically yourself — never
    eyeball or narrow-grep the `ls` (a narrowed pattern like `'^10[0-9]'` silently misses `110+`
    and collides). PRDs are stored per-project, so `NN` allocation for a given PRD only needs
    *that project's own* prds directory scanned — not every project's:
@@ -268,9 +313,16 @@ can't load skills.
    **Anywhere else doesn't get scheduled or gets retired.** `data/prds/`, `docs/prds/`, and the
    old global `prds/` dir under `~/.claude/session-manager/scheduled-plans/` are invisible to
    the scheduler; the legacy flat `session-manager-operations/scheduler/prds/` dir is RETIRED —
-   anything written there is auto-consolidated into `prds-archived/` at the next app boot
-   without being executed. PRD *source* files are per-project and per-Epic, resolved at runtime
-   via `src/main/lib/prdLocations.cjs`.
+   anything written there is auto-consolidated into `prds-archived/` and never executed. This
+   consolidation runs at the top of every `reconcile()` call (`consolidateAllFlatPrds`, called
+   from inside `reconcile()` itself in `src/main/scheduler.cjs`, before `reconcile` scans that
+   dir for PRD sources) — not only at app boot, and not just from the tick-queue poll:
+   `reconcile()` also runs from job completion, the `schedule:state`/`schedule:rescan` IPC
+   handlers, and `rescheduleTimer()`, so the sweep is guaranteed regardless of which of those
+   triggers the next pass. A file landing in the flat dir while the app is already running is
+   swept out before it could ever be turned into a job, closing the window a boot-only pass left
+   open. PRD *source* files are per-project and per-Epic, resolved at runtime via
+   `src/main/lib/prdLocations.cjs`.
 
    **Filename rules.** `NN` is the PRD's unique per-project number (always next free =
    max+1 per the `ls` command above; ordering via `dependsOn` frontmatter, never via shared
@@ -423,11 +475,17 @@ single definition of "tracked to done" for both entry paths.
 
 ## Notes
 
-- Write PRD files directly, then confirm — don't draft them inline in chat for review first.
+- Submit each PRD through `scheduler_create_prd`, then confirm — don't draft them inline in chat
+  for review first. Only hand-write the file when the tool is PRESENT but ERRORS as unreachable
+  (app not running) — see the "Two failure modes" note above, including its mandatory bypass
+  warning. If the tool is ABSENT from your tool list, that's a misconfiguration, not an offline
+  app: stop and tell the human, never hand-write the file.
 - Don't combine unrelated features into one PRD. One focused, completable unit each.
 - Don't add a `parallelGroup` frontmatter key — the filename `NN-` prefix drives grouping.
 - Don't write a PRD to `data/prds/`, `docs/prds/`, the project's own folder, or anywhere outside
-  the canonical path. The user has explicitly flagged this as a recurring problem.
+  the canonical path — and don't reach for a hand-written file at the canonical path either, when
+  `scheduler_create_prd` is reachable. The user has explicitly flagged this as a recurring
+  problem.
 - Don't leave `cwd` unset hoping for the default. Be explicit.
 - Don't skip a step-3 lens silently and don't force every request into a chain — most asks are
   still an independent set of small PRDs; reach for the 3-5-PRD evolving chain only when the

package/plugins/session-manager-dev/skills/ops-sweep/SKILL.md

@@ -36,6 +36,16 @@ etc.), this skill makes **no assumption about the target project's namespace
 names, its OWNERS table shape, or whether it has a CLAUDE.md at all**. It
 re-derives the source-of-truth hierarchy from what that specific project has:
 
+**Hand-authored-PRD detection stays out of this generic script on purpose.**
+`audit-ops-hygiene.cjs`'s Pattern E (cross-referencing a live PRD `.md` file
+against the machine-wide `prd_create` audit log to flag a PRD that bypassed
+`scheduler_create_prd`) requires session-manager's own scheduler/PRD/audit-log
+concepts, which a swept project may not even have — adding it here would break
+the "no assumption about vocabulary" guarantee above. When sweeping
+session-manager's own repo, run `node scripts/audit-ops-hygiene.cjs` alongside
+this skill and fold its Pattern C/D/E findings into the same report; when
+sweeping a different project, Pattern E simply doesn't apply.
+
 1. That project's own `CLAUDE.md` (if present) — the declared architecture.
 2. Each namespace's own `README.md` under its `session-manager-operations/<namespace>/`.
 3. On-disk content — folder names, and archived/processed subfolders.

package/src/main/__tests__/agentLibrary.test.cjs

@@ -213,3 +213,43 @@ test('removeOverride deletes a project overlay resolved by project name, and rej
     removeOverride({ name: 'builder', projectName: 'not-open', loadSessions, validatePath: identityValidatePath }),
   ).rejects.toThrow(/project not open/);
 });
+
+test('projects/action/actionLabel round-trip through savePersona -> listPersonas, with newlines preserved', async () => {
+  const globalDir = await mkTmp('sm-agent-library-action-');
+  const action = '/builder\n\nCheck git vs the published package and publish anything new.';
+  await savePersona({
+    name: 'builder',
+    description: 'Drives the next publish.',
+    tools: ['Bash'],
+    model: 'inherit',
+    color: '',
+    tags: ['build'],
+    projects: ['/home/bilko/Projects/alpha', '/home/bilko/Projects/beta'],
+    action,
+    actionLabel: 'Run Build',
+    body: 'Body.',
+    globalDir,
+    validatePath: identityValidatePath,
+    writeTextAtomic: fakeWriteTextAtomic,
+  });
+
+  // The frontmatter parser is line-based, so the multi-line action must be
+  // stored escaped — a raw newline would silently truncate it on read.
+  const raw = await fsp.readFile(path.join(globalDir, 'builder.md'), 'utf8');
+  expect(raw).toContain('action: /builder\\n\\nCheck git');
+  expect(raw).toContain('projects: /home/bilko/Projects/alpha, /home/bilko/Projects/beta');
+
+  const [p] = await listPersonas({ globalDir, loadSessions: async () => ({ tabs: [] }), validatePath: identityValidatePath });
+  expect(p.projects).toEqual(['/home/bilko/Projects/alpha', '/home/bilko/Projects/beta']);
+  expect(p.action).toBe(action);
+  expect(p.actionLabel).toBe('Run Build');
+});
+
+test('a persona with no Action fields reports them as empty/null rather than undefined', async () => {
+  const globalDir = await mkTmp('sm-agent-library-noaction-');
+  await fsp.writeFile(path.join(globalDir, 'plain.md'), '---\nname: plain\n---\nBody.\n');
+  const [p] = await listPersonas({ globalDir, loadSessions: async () => ({ tabs: [] }), validatePath: identityValidatePath });
+  expect(p.projects).toEqual([]);
+  expect(p.action).toBeNull();
+  expect(p.actionLabel).toBeNull();
+});

package/src/main/__tests__/develop-skill-failure-modes.test.cjs

@@ -0,0 +1,70 @@
+/**
+ * develop-skill-failure-modes.test.cjs — drift guard for the two
+ * scheduler_create_prd failure-mode branches in the /develop skill.
+ *
+ * PRD 1024-1030 incident (2026-08-08): social-signals-trader's session
+ * hand-wrote 7 PRDs because scheduler_create_prd was ABSENT from its tool
+ * list (the project's .mcp.json didn't register the server yet) — not
+ * because the tool errored as unreachable. The old wording only named the
+ * "tool errors ... unreachable" case, which an absent tool never matches,
+ * so an agent in that situation had no documented path except hand-writing.
+ * This test asserts the fix (two named failure modes, with the absent-tool
+ * case explicitly forbidding hand-writing) is present and doesn't silently
+ * regress back to the single-case wording.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/develop-skill-failure-modes.test.cjs
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+import { test, expect } from 'vitest';
+
+const SKILL_MD = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'plugins',
+  'session-manager-dev',
+  'skills',
+  'develop',
+  'SKILL.md'
+);
+
+function readSkill() {
+  return fs.readFileSync(SKILL_MD, 'utf8');
+}
+
+test('SKILL.md names both failure modes explicitly', () => {
+  const text = readSkill();
+  expect(text).toMatch(/tool PRESENT but ERRORS/i);
+  expect(text).toMatch(/tool ABSENT from your tool list/i);
+});
+
+test('the absent-tool branch explicitly forbids hand-writing and says STOP', () => {
+  const text = readSkill();
+  const absentIdx = text.search(/tool ABSENT from your tool list/i);
+  expect(absentIdx).toBeGreaterThan(-1);
+  const nearby = text.slice(absentIdx, absentIdx + 1200);
+  expect(nearby).toMatch(/STOP/);
+  expect(nearby).toMatch(/[Dd]o not write any PRD file/);
+  expect(nearby).toMatch(/misconfiguration/i);
+});
+
+test('the present-but-erroring branch is the only one pointed at the manual-write fallback', () => {
+  const text = readSkill();
+  expect(text).toMatch(/Fallback for case \(a\) only/);
+});
+
+test('the standalone preflight check appears before PRD composition begins', () => {
+  const text = readSkill();
+  expect(text).toMatch(/Preflight — confirm the tool is even in your tool list/);
+});
+
+test('a preflight-tool-registration fix is named for the human (user-scope claude mcp add)', () => {
+  const text = readSkill();
+  expect(text).toMatch(/claude mcp add session-manager-scheduler --scope\s*\n?\s*user/);
+});

package/src/main/__tests__/flatPrdTickSweep.test.cjs

@@ -0,0 +1,110 @@
+/**
+ * flatPrdTickSweep.test.cjs — the retired flat `scheduler/prds/` dir must be
+ * TRULY inert, not just documented as such.
+ *
+ * Prior to this PRD, `runPrdMigration()`'s consolidation of the flat dir into
+ * `prds-archived/` ran ONLY at Electron boot (src/main/scheduler.cjs). But
+ * `prdLocations.cjs`'s `resolvePrdsDirs()` unconditionally keeps scanning the
+ * flat dir as a live PRD source, and `reconcile()` runs on every tick — so a
+ * PRD hand-written into the flat dir *after* boot sat there live and WOULD
+ * get reconciled into a pending job and executed (observed 2026-08-07:
+ * 1021/1022 PRDs in social-signals-trader executed once their status was
+ * repaired), contradicting the develop skill's documented claim that
+ * anything landed there is "auto-consolidated ... WITHOUT being executed."
+ *
+ * The fix: `consolidateAllFlatPrds()` now also runs at the START of every
+ * `reconcile()` call itself (not just one caller like tickQueue's poll — every
+ * caller of reconcile gets the guarantee), BEFORE reconcile scans the flat
+ * dir. A freshly hand-written PRD has no queue row yet (reconcile hasn't
+ * seen it), so it is never in LIVE_JOB_STATUSES — this sweep archives it
+ * before reconcile ever gets a chance to turn it into a job. This test
+ * proves that invariant directly against `consolidateAllFlatPrds`: a file
+ * with no matching queue job is swept into `prds-archived/` on the very next
+ * call, which prdLocations.cjs's `resolvePrdsDirs()` never scans as a live
+ * source — so it can never be reconciled into a job afterward.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/flatPrdTickSweep.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { consolidateAllFlatPrds } = require('../scheduler.cjs');
+const { resolvePrdWriteDir, resolvePrdsDirs } = require('../lib/prdLocations.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+function newProjectRoot() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-flat-tick-sweep-'));
+  tmpDirs.push(d);
+  return d;
+}
+
+test('a PRD hand-written into the retired flat dir after boot is swept before it could ever be reconciled', async () => {
+  const cwd = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(cwd);
+  await fsp.mkdir(flatDir, { recursive: true });
+  const filename = '999-hand-written-bypass.md';
+  await fsp.writeFile(
+    path.join(flatDir, filename),
+    `---\ntitle: Hand-written bypass\ncwd: ${cwd}\nestimateMinutes: 10\n---\n\n# Goal\n\nSomething.\n`,
+    'utf8',
+  );
+  // No queue.json at all yet — this is exactly the state of a PRD dropped on
+  // disk moments ago, before any reconcile() pass has scanned it into a job.
+
+  await consolidateAllFlatPrds([cwd]);
+
+  // Swept out of the live flat dir...
+  expect(fs.existsSync(path.join(flatDir, filename))).toBe(false);
+  // ...and into prds-archived/, which resolvePrdsDirs() never returns as a
+  // scan source — so no future reconcile() pass can find it and queue it.
+  const archivedPath = path.join(path.dirname(flatDir), 'prds-archived', filename);
+  expect(fs.existsSync(archivedPath)).toBe(true);
+
+  const liveDirs = resolvePrdsDirs(Infinity, { projectsDir: path.join(cwd, '.nonexistent') });
+  expect(liveDirs.every((d) => !d.includes('prds-archived'))).toBe(true);
+});
+
+test('consolidateAllFlatPrds still protects a PRD that already has a live queue job (PRD 992 invariant preserved)', async () => {
+  const cwd = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(cwd);
+  await fsp.mkdir(flatDir, { recursive: true });
+  const stateDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  await fsp.mkdir(stateDir, { recursive: true });
+  await fsp.writeFile(
+    path.join(flatDir, '998-live.md'),
+    `---\ntitle: Live\ncwd: ${cwd}\nestimateMinutes: 10\n---\n\n# Goal\n`,
+    'utf8',
+  );
+  await fsp.writeFile(
+    path.join(stateDir, 'queue.json'),
+    JSON.stringify({ jobs: [{ slug: '998-live', status: 'running' }] }),
+    'utf8',
+  );
+
+  await consolidateAllFlatPrds([cwd]);
+
+  expect(fs.existsSync(path.join(flatDir, '998-live.md'))).toBe(true);
+});
+
+test('consolidateAllFlatPrds never throws when a project errors — one bad cwd does not block the sweep of the rest', async () => {
+  const good = newProjectRoot();
+  const flatDir = resolvePrdWriteDir(good);
+  await fsp.mkdir(flatDir, { recursive: true });
+  await fsp.writeFile(path.join(flatDir, '997-ok.md'), `---\ntitle: Ok\ncwd: ${good}\nestimateMinutes: 5\n---\n\n# Goal\n`, 'utf8');
+
+  await expect(consolidateAllFlatPrds([null, good])).resolves.toBeUndefined();
+
+  expect(fs.existsSync(path.join(flatDir, '997-ok.md'))).toBe(false);
+});

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

@@ -0,0 +1,82 @@
+/**
+ * health-per-project-stall.test.cjs — per-project problem-count rollup and
+ * per-project stall-past-threshold escalation for the scheduler_queue health
+ * check. Covers the gap where a project holding ONLY failed/needs_review/
+ * quarantined rows (0 running, 0 pending) never tripped evaluateTickLiveness
+ * (which requires actual pending work) — the exact way the burrow project's
+ * four quarantined PRDs went dark.
+ *
+ * Run: timeout 120 node --test src/main/__tests__/health-per-project-stall.test.cjs
+ */
+
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  computeProjectProblemCounts,
+  evaluatePerProjectStall,
+  TICK_STALL_THRESHOLD_MS,
+} = require('../health.cjs');
+const { computeStallSummary } = require('../scheduler.cjs');
+
+test('computeProjectProblemCounts: breaks down failed/needs_review/quarantined by project, ignores healthy statuses', () => {
+  const jobs = [
+    { slug: 'a', cwd: '/burrow', status: 'quarantined' },
+    { slug: 'b', cwd: '/burrow', status: 'quarantined' },
+    { slug: 'c', cwd: '/burrow', status: 'quarantined' },
+    { slug: 'd', cwd: '/burrow', status: 'quarantined' },
+    { slug: 'e', cwd: '/other', status: 'failed' },
+    { slug: 'f', cwd: '/other', status: 'needs_review' },
+    { slug: 'g', cwd: '/other', status: 'running' },
+    { slug: 'h', cwd: '/other', status: 'pending' },
+    { slug: 'i', cwd: '/other', status: 'completed' },
+  ];
+  const counts = computeProjectProblemCounts(jobs);
+  assert.deepStrictEqual(counts['/burrow'], { failed: 0, needs_review: 0, quarantined: 4 });
+  assert.deepStrictEqual(counts['/other'], { failed: 1, needs_review: 1, quarantined: 0 });
+});
+
+test('evaluatePerProjectStall: fully-stalled project past threshold flags pastThreshold=true', () => {
+  const state = {
+    lastRunAt: new Date(Date.now() - (TICK_STALL_THRESHOLD_MS + 60_000)).toISOString(),
+    paused: null,
+    jobs: [
+      { slug: 'a', cwd: '/burrow', status: 'quarantined' },
+      { slug: 'b', cwd: '/other', status: 'running' },
+    ],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  const result = evaluatePerProjectStall(summary, state.lastRunAt, Date.now(), TICK_STALL_THRESHOLD_MS);
+  assert.strictEqual(result['/burrow'].stalled, true);
+  assert.strictEqual(result['/burrow'].pastThreshold, true);
+  assert.strictEqual(result['/other'].stalled, false);
+});
+
+test('evaluatePerProjectStall: stalled but NOT yet past threshold flags pastThreshold=false', () => {
+  const state = {
+    lastRunAt: new Date(Date.now() - 1000).toISOString(), // just ticked
+    paused: null,
+    jobs: [{ slug: 'a', cwd: '/burrow', status: 'quarantined' }],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  const result = evaluatePerProjectStall(summary, state.lastRunAt, Date.now(), TICK_STALL_THRESHOLD_MS);
+  assert.strictEqual(result['/burrow'].stalled, true);
+  assert.strictEqual(result['/burrow'].pastThreshold, false);
+});
+
+test('evaluatePerProjectStall: no lastRunAt yet — stalled but not asserted past threshold (caveat, not a false RED)', () => {
+  const state = {
+    lastRunAt: null,
+    paused: null,
+    jobs: [{ slug: 'a', cwd: '/burrow', status: 'quarantined' }],
+    invalidJobs: [],
+  };
+  const summary = computeStallSummary(state);
+  const result = evaluatePerProjectStall(summary, state.lastRunAt, Date.now(), TICK_STALL_THRESHOLD_MS);
+  assert.strictEqual(result['/burrow'].stalled, true);
+  assert.strictEqual(result['/burrow'].pastThreshold, false);
+  assert.strictEqual(result['/burrow'].caveat, 'no-lastRunAt');
+});

package/src/main/__tests__/prdAdminRouteParity.test.cjs

@@ -0,0 +1,68 @@
+/**
+ * prdAdminRouteParity.test.cjs — capability-parity gate for PRD 1024 ("lock
+ * the PRD entity behind the scheduler service boundary, step 1").
+ *
+ * Enumerates every PRD/job mutation the codebase can perform (the full set
+ * of `schedule:*` IPC channels that read/write a PRD file or a queue job,
+ * plus create-prd and cancel-job which have no IPC twin) and asserts each
+ * one has a corresponding admin HTTP route registered by scheduler.cjs's
+ * registerAdminRoutes, prdCreate.cjs's registerAdminRoute, or
+ * prdAdminRoutes.cjs's registerAdminRoute. A future PRD-lifecycle capability
+ * added only as an IPC handler (filesystem-only from the admin API's point
+ * of view) fails this test until an admin route is added for it too — that
+ * is the whole point: the admin API must never fall behind what's actually
+ * possible against a PRD/job.
+ *
+ * Route registration is captured via a fake `adminHttp` stub (just
+ * `registerRoute`) — no real HTTP server or Electron boot needed, matching
+ * how prdCreate.test.cjs already verifies wiring.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdAdminRouteParity.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const scheduler = require('../scheduler.cjs');
+const prdCreate = require('../lib/prdCreate.cjs');
+const prdAdminRoutes = require('../lib/prdAdminRoutes.cjs');
+
+// Every PRD-lifecycle capability the codebase can perform, mapped to the
+// admin HTTP route that must exist for it. `ipcChannel` is informational
+// (documents the renderer-facing twin, if any) — the assertion is only
+// against `adminRoute`.
+const REQUIRED_CAPABILITIES = [
+  { capability: 'create a PRD', ipcChannel: null, adminRoute: 'POST /admin/scheduler/create-prd' },
+  { capability: 'list PRDs (live + archived)', ipcChannel: 'schedule:list-prds', adminRoute: 'GET /admin/scheduler/prds' },
+  { capability: 'read one PRD (body + frontmatter)', ipcChannel: 'schedule:read-prd', adminRoute: 'GET /admin/scheduler/prd' },
+  { capability: 'edit a not-yet-running PRD', ipcChannel: 'schedule:write-prd', adminRoute: 'POST /admin/scheduler/update-prd' },
+  { capability: 'archive a PRD', ipcChannel: 'schedule:archive-prd', adminRoute: 'POST /admin/scheduler/archive-prd' },
+  { capability: 'retag a PRD (parallelGroup/estimateMinutes)', ipcChannel: 'schedule:retag-prd', adminRoute: 'POST /admin/scheduler/retag-prd' },
+  { capability: 'list scheduler jobs', ipcChannel: null, adminRoute: 'GET /admin/scheduler/jobs' },
+  { capability: 'reset a stuck job', ipcChannel: 'schedule:reset-job', adminRoute: 'POST /admin/scheduler/reset-job' },
+  { capability: 'cancel a not-yet-terminal job', ipcChannel: null, adminRoute: 'POST /admin/scheduler/cancel-job' },
+];
+
+function captureRegisteredRoutes() {
+  const registered = new Set();
+  const fakeAdminHttp = {
+    registerRoute(method, url) {
+      registered.add(`${method} ${url}`);
+    },
+  };
+  scheduler.registerAdminRoutes(fakeAdminHttp, scheduler.remote);
+  prdCreate.registerAdminRoute(fakeAdminHttp, scheduler.remote);
+  prdAdminRoutes.registerAdminRoute(fakeAdminHttp, scheduler.remote);
+  return registered;
+}
+
+test('every enumerated PRD/job mutation capability has a registered admin route', () => {
+  const registered = captureRegisteredRoutes();
+  const missing = REQUIRED_CAPABILITIES.filter((c) => !registered.has(c.adminRoute));
+  expect(missing).toEqual([]);
+});
+
+test.each(REQUIRED_CAPABILITIES)('capability "$capability" → $adminRoute is registered', ({ adminRoute }) => {
+  const registered = captureRegisteredRoutes();
+  expect(registered.has(adminRoute)).toBe(true);
+});