claude-code-session-manager 0.86.0 → 0.87.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-CXFQIPhO.js"></script>
+    <script type="module" crossorigin src="./assets/index-fc_JjdxL.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-CDo9xBR9.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-DV3PorRY.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",
@@ -12,13 +12,12 @@
     ".claude-plugin/",
     "plugins/",
     "scripts/postinstall.cjs",
-    "scripts/lib/",
     "scripts/mint-epic.cjs",
     "scripts/scheduler-mcp-server.cjs",
-    "scripts/render-project-pages.cjs",
-    "scripts/render-project-pages/dist/",
-    "scripts/project-pages-logic/dist/",
-    "scripts/validate-project-pages-summary.cjs",
+    "web/project-pages/render.cjs",
+    "web/project-pages/renderer/dist/",
+    "web/project-pages/logic/dist/",
+    "web/project-pages/validate-summary.cjs",
     "scripts/hooks/guard-prd-writes.cjs",
     "scripts/hooks/guard-destructive-git.cjs",
     "scripts/hooks/guard-inline-implementation.cjs",
@@ -36,10 +35,10 @@
     "dev:renderer": "vite",
     "dev:electron": "wait-on http://localhost:5173 && SM_DEV=1 electron .",
     "build": "vite build",
-    "build:project-pages": "node scripts/build-project-pages-renderer.mjs",
-    "build:project-pages-logic": "node scripts/build-project-pages-logic.mjs",
-    "build:project-pages-assets": "node scripts/project-pages-assets.cjs",
-    "project-pages:gate": "node scripts/project-pages-publish-gate.cjs",
+    "build:project-pages": "node web/project-pages/build-renderer.mjs",
+    "build:project-pages-logic": "node web/project-pages/build-logic.mjs",
+    "build:project-pages-assets": "node web/project-pages/assets.cjs",
+    "project-pages:gate": "node web/project-pages/publish-gate.cjs",
     "typecheck": "tsc --noEmit",
     "start": "electron .",
     "postinstall": "node scripts/postinstall.cjs",
@@ -51,13 +50,14 @@
     "test:e2e:gen-fixture": "espeak-ng -w /tmp/sm-raw.wav -s 140 'testing one two three four five' && ffmpeg -y -i /tmp/sm-raw.wav -ar 48000 -ac 2 -sample_fmt s16 e2e/fixtures/speech.wav",
     "refresh:vad-assets": "cp node_modules/@ricky0123/vad-web/dist/silero_vad_v5.onnx node_modules/@ricky0123/vad-web/dist/vad.worklet.bundle.min.js src/renderer/public/vad/ && cp node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.wasm node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.mjs node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.jsep.wasm node_modules/onnxruntime-web/dist/ort-wasm-simd-threaded.jsep.mjs src/renderer/public/vad/",
     "health": "node src/main/health.cjs",
-    "manual:check": "node scripts/build-manual.mjs --check",
-    "manual:build": "node scripts/build-manual.mjs",
-    "manual:figures": "xvfb-run -a node scripts/capture-manual-figures.mjs",
+    "manual:check": "node web/manual/build.mjs --check",
+    "manual:build": "node web/manual/build.mjs",
+    "manual:figures": "xvfb-run -a node web/manual/capture-figures.mjs",
     "lint:selectors": "node scripts/check-unstable-selectors.cjs",
     "lint:hooks": "node scripts/check-conditional-hooks.cjs",
     "lint:unregistered-tests": "node scripts/check-unregistered-tests.cjs",
-    "lint": "npm run lint:selectors && npm run lint:hooks && npm run lint:unregistered-tests"
+    "lint": "npm run lint:selectors && npm run lint:hooks && npm run lint:unregistered-tests",
+    "sync:settings-schema": "node scripts/sync-settings-schema.cjs"
   },
   "keywords": [
     "claude",

package/plugins/CLAUDE.md

@@ -0,0 +1,61 @@
+# plugins/ — scoped context
+
+Part of the **AGENT LAYER** partition — see
+[`project-partition.md`](../session-manager-operations/architecture/project-partition.md).
+
+## What's here
+
+`session-manager-dev/skills/` — 15 skills (`blog-for-project-feature`, `builder`, `develop`,
+`discover-features`, `explain-to-me`, `find-opportunity`, `issue-address`,
+`local-project-health`, `memory-sanitation`, `ops-sweep`, `project-status`, `pr-review-sweep`,
+`pr-signal`, `requesting-code-review`, `send-feedback`) — verified against `ls
+plugins/session-manager-dev/skills` 2026-09-13; keep in sync with `project-partition.md` and
+`seedDevPlugin.cjs`'s header count.
+
+Two manifests: root [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json)
+declares the one plugin (`source: "./plugins/session-manager-dev"`); the plugin's own
+[`session-manager-dev/.claude-plugin/plugin.json`](session-manager-dev/.claude-plugin/plugin.json)
+carries the `description` shown in the marketplace UI — list only shipped skills.
+
+`src/main/seedDevPlugin.cjs` is the first-boot offline installer — installs this plugin from its
+bundled marketplace (no GitHub/registry call) as a default on a fresh machine, then marks
+`~/.claude/session-manager/.dev-plugin-seeded`.
+
+**`skills/develop/standards.md` is a frozen absolute-path contract.** Every scheduler PRD, in
+every consuming repo, points its headless executor at it by resolved absolute path, baked
+in at authoring time — including PRDs already archived in OTHER repos. Renaming or moving it
+breaks them all, undetectably from here.
+
+**Path literals inside shipped skills.** A skill runs in OTHER repos, so a
+session-manager-internal path (`src/main/...`, `src/renderer/...`, bare `scripts/...`) inside one
+is a portability defect unless `$SM_ROOT`-qualified (see `ops-sweep/SKILL.md`'s resolution) or
+removed. Current offenders, not precedent: `memory-sanitation/SKILL.md`, `builder/SKILL.md` +
+`builder/0-diff/SKILL.md`, `develop/SKILL.md`, `develop/standards.md`, `ops-sweep/SKILL.md`.
+
+## Who consumes this
+
+**Other repos**, not (only) this one. A project installs `claude-code-session-manager` from npm,
+or references its skills/hooks directly, for the same dev workflow session-manager uses on itself.
+Editing a skill here changes behavior in every consuming repo. See
+[`../session-manager-operations/reviews/2026-09-12-agent-layer-consumers.md`](../session-manager-operations/reviews/2026-09-12-agent-layer-consumers.md)
+for live sibling consumers.
+
+## What must NOT be assumed
+
+- Treat every skill edit here as a cross-repo API change, not a local-only one.
+- Do not vendor `scripts/hooks/guard-*.cjs` into a skill/repo — adopt **by reference** via the
+  stable shim (`src/main/lib/guardShims.cjs`) at `~/.claude/session-manager/hooks/guard-*.cjs`,
+  never this repo's own absolute path or a copy.
+- Do not confuse this with `.claude/` at the repo root — this repo's own unshipped local dev
+  config. `.claude/agents/*.md` are per-project OVERLAYS that win over
+  `~/.claude/agents/*.md` (Claude Code's own precedence, per `src/main/agentLibrary.cjs`);
+  `src/seed/agents/` is the shipped source for exactly the three personas
+  `src/main/seedAgentPersonas.cjs` copies into `~/.claude/agents/` on first boot (`architect`,
+  `dev-lead`, `project-home-builder`); `builder` and `bilko-host-publisher` have no seed source
+  and exist only as this repo's overlays. Tracked on purpose: `.claude/settings.json` (guard
+  hooks) plus the `builder.md`/`project-home-builder.md` overlays (auditable edits) —
+  `bilko-host-publisher.md` is untracked despite being in use; nothing else under `.claude/` is.
+- `.mcp.json` at the repo root registers only `bilko-host` — the scheduler MCP server
+  (`session-manager-scheduler`) is registered at USER scope in `~/.claude.json`, not here.
+- A skill may run headless via a scheduled PRD in another project — don't rely on
+  interactive-session-only features; check `/develop`'s scheduler flow first.

package/plugins/session-manager-dev/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-manager-dev",
-  "description": "The default end-to-end development skillset for the Claude Code Session Manager: decompose work into scheduler PRDs (/develop), hand a finding to another project on this machine (/send-feedback), rank what to work on next in a shared repo (/find-opportunity), roll up operational status and optimize the North-Star KPI (/project-status, /optimize-kpi, /local-project-health), gate with review (/requesting-code-review, /security-review), document how the project works (/explain-to-me), and keep the auto-memory store clean (/memory-sanitation). Together with the session-manager scheduler these form a closed develop → queue → track → review → status → improve loop.",
+  "description": "The default end-to-end development skillset for the Claude Code Session Manager: decompose work into scheduler PRDs (/develop), hand a finding to another project on this machine (/send-feedback), rank what to work on next in a shared repo (/find-opportunity), roll up operational status (/project-status, /local-project-health), gate with review (/requesting-code-review), document how the project works (/explain-to-me), and keep the auto-memory store clean (/memory-sanitation). Together with the session-manager scheduler these form a closed develop → queue → track → review → status → improve loop.",
   "version": "0.1.0",
   "author": {
     "name": "Stanislav Georgiev",

package/plugins/session-manager-dev/skills/builder/4-manual/SKILL.md

@@ -54,7 +54,7 @@ Hard rules — these are the ones that protect a paying customer:
   the one thing people get wrong, the workflow that pays off. If a paragraph would be equally
   at home in `CLAUDE.md`, cut it.
 - **Preserve the free chapter.** At least one chapter must stay `free: true` — it is the
-  marketing sample, and `scripts/build-manual.mjs` refuses to build without one.
+  marketing sample, and `web/manual/build.mjs` refuses to build without one.
 
 ### 3. Bump the manual's own version
 

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

@@ -133,5 +133,5 @@ id(s) or PRD(s) filed.
   directly; don't run the full sweep for a question with a known answer.
 - Cron/scheduled sweeping across every active project cwd is an explicit
   stretch goal, not implemented here — this skill is manual, single-project,
-  invoked per run. `scripts/lib/watchdogHelpers.cjs`'s `activeProjectCwds()`
+  invoked per run. `src/main/lib/watchdogHelpers.cjs`'s `activeProjectCwds()`
   is the reusable piece if that's ever built.

package/scripts/scheduler-mcp-server.cjs

@@ -164,6 +164,11 @@ const TOOLS = [
         slug: { type: 'string', description: 'Optional kebab-case slug; derived from title if omitted' },
         parallelGroup: { type: 'number', description: 'DEPRECATED and ignored (PRD 832): numbers are strictly unique per project; use dependsOn for ordering' },
         dependsOn: { type: 'array', items: { type: 'string' }, description: 'Optional: PRD slugs that must complete before this one becomes eligible (replaces the retired shared-NN-parallel convention)' },
+        disposition: {
+          type: 'string',
+          enum: ['append', 'new-head'],
+          description: 'Required when this PRD would land as a new root (no dependsOn given) in an Epic that already has incomplete PRDs: "append" depends this wave on the existing chain\'s current terminal PRD(s); "new-head" leaves it independent, eligible to run in parallel. Omit when the Epic has no incomplete PRDs yet, or when dependsOn already places this PRD explicitly.',
+        },
         sourcePromptId: { type: 'string', description: "Effectively required: an EXISTING, already-human-approved Epic's promptSessionId (the id shown in the Epics list / active-index.json sessions key) to join — NOT a PromptTicket.id (those are distinct fields). The server never mints a new Epic; if this is omitted and no Epic can be resolved (via the SM_CHAT_SESSION_ID fallback below), the write is refused with an error telling the caller to create/approve an Epic first." },
         sourceTabId: { type: 'string', description: 'Optional: tab id (claudeSessionId) this PRD was queued from, so the scheduler can route a completion status prompt back to it' },
         tag: {
@@ -231,6 +236,8 @@ const TOOLS = [
             tag: { type: 'string', enum: PRD_WORK_TYPES },
             agentType: { type: 'string', description: 'WHO executes this PRD (persona name) — patchable after creation too, see scheduler_create_prd' },
             quietMachine: { type: 'boolean', description: 'Optional: the exclusive machine-wide quiet lease flag (see scheduler_create_prd) — patchable after creation too' },
+            dependsOn: { type: 'array', items: { type: 'string' }, description: 'Optional: replaces the dependsOn list; an explicit empty array CLEARS it — see scheduler_create_prd' },
+            disposition: { type: 'string', enum: ['append', 'new-head'], description: 'Optional: patches the recorded wave-authoring decision — see scheduler_create_prd' },
           },
         },
         body: { type: 'string', description: 'Optional: full replacement body (everything after the frontmatter)' },

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

@@ -17,7 +17,7 @@ const {
   FALLBACK_MODEL,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
-  readPersonaModel,
+  readOverlayAwarePersonaModel,
   resolvePrdPersonaForSpawn,
 } = require('../lib/agentModelResolve.cjs');
 
@@ -103,37 +103,39 @@ test('findAgentTypeByClaudeSessionId returns null for no match', async () => {
   expect(findAgentTypeByClaudeSessionId(cwd, 'missing')).toBeNull();
 });
 
-test('readPersonaModel returns null for a persona with no model field', async () => {
+test('readOverlayAwarePersonaModel returns null for a persona with no model field', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
   const globalDir = await mkTmpDir('sm-agentmodel-agents-');
   writePersona(globalDir, 'no-model-persona', []);
-  expect(readPersonaModel('no-model-persona', { globalDir, validatePath: noopValidatePath })).toBeNull();
+  expect(readOverlayAwarePersonaModel('no-model-persona', { cwd, globalDir, validatePath: noopValidatePath })).toBeNull();
 });
 
-test('readPersonaModel returns null (never throws) for a path-traversal agentType rejected by validatePath', async () => {
+test('readOverlayAwarePersonaModel returns null (never throws) for a path-traversal agentType rejected by validatePath', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
   const globalDir = await mkTmpDir('sm-agentmodel-agents-');
   const realValidatePath = (p) => {
     const real = path.resolve(p);
     if (!real.startsWith(path.resolve(globalDir) + path.sep)) throw new Error('outside allowed boundaries');
     return real;
   };
-  expect(readPersonaModel('../../../etc/passwd', { globalDir, validatePath: realValidatePath })).toBeNull();
+  expect(readOverlayAwarePersonaModel('../../../etc/passwd', { cwd, globalDir, validatePath: realValidatePath })).toBeNull();
 });
 
 // READ side of the agentType FK: a persona that was valid when the Epic was
 // created but got deleted afterward (rename/deletion in Agent Library) must
 // still resolve to null, not throw — the WRITE side (epicMint.cjs's
 // ensureEpic) is what refuses a bad reference at creation time.
-test('readPersonaModel returns null (does not throw) for a persona deleted after the Epic was created, and logs it once via opsErrorLog', async () => {
+test('readOverlayAwarePersonaModel returns null (does not throw) for a persona deleted after the Epic was created, and logs it once via opsErrorLog', async () => {
   const cwd = await mkTmpDir('sm-agentmodel-cwd-');
   const globalDir = await mkTmpDir('sm-agentmodel-agents-'); // never written to — simulates a deleted persona
 
-  expect(() => readPersonaModel('deleted-persona', { globalDir, validatePath: noopValidatePath, cwd })).not.toThrow();
-  expect(readPersonaModel('deleted-persona', { globalDir, validatePath: noopValidatePath, cwd })).toBeNull();
+  expect(() => readOverlayAwarePersonaModel('deleted-persona', { globalDir, validatePath: noopValidatePath, cwd })).not.toThrow();
+  expect(readOverlayAwarePersonaModel('deleted-persona', { globalDir, validatePath: noopValidatePath, cwd })).toBeNull();
 
   const { todayFile } = require('../lib/opsErrorLog.cjs');
   const lines = fs.readFileSync(todayFile(cwd), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
   const matches = lines.filter((l) => l.message.includes('deleted-persona'));
-  // Logged once despite two readPersonaModel calls above — dedup key is (cwd, agentType).
+  // Logged once despite two readOverlayAwarePersonaModel calls above — dedup key is (cwd, agentType).
   expect(matches).toHaveLength(1);
   expect(matches[0].level).toBe('warn');
 });
@@ -190,6 +192,95 @@ test('resolvePrdPersonaForSpawn returns the fallback (no persona applied) when a
   expect(result).toEqual({ model: FALLBACK_MODEL, systemPrompt: null, personaPath: null });
 });
 
+// Overlay-aware resolution (unify-epic-model-resolution): resolveEpicModel
+// must use the SAME project-overlay-then-global precedence
+// resolvePrdPersonaForSpawn already uses — so a project's
+// `.claude/agents/<name>.md` wins for a launched Chat/Terminal session
+// exactly like it already does for a scheduled PRD.
+
+test('resolveEpicModel prefers a project-overlay persona over the global one with the same name', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
+  const globalDir = await mkTmpDir('sm-agentmodel-agents-');
+  writeIndex(cwd, { 'epic-1': { id: 'epic-1', claudeSessionId: 'sess-overlay', agentType: 'shared-persona' } });
+  writePersona(globalDir, 'shared-persona', ['model: opus']);
+  const projectAgentsDir = path.join(cwd, '.claude', 'agents');
+  writePersona(projectAgentsDir, 'shared-persona', ['model: haiku']);
+
+  const model = resolveEpicModel({
+    cwd,
+    claudeSessionId: 'sess-overlay',
+    deps: { globalDir, validatePath: noopValidatePath },
+  });
+
+  expect(model).toBe('haiku');
+});
+
+test('resolveEpicModel falls through to the global persona when no project overlay exists', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
+  const globalDir = await mkTmpDir('sm-agentmodel-agents-');
+  writeIndex(cwd, { 'epic-1': { id: 'epic-1', claudeSessionId: 'sess-global-only', agentType: 'global-only-persona' } });
+  writePersona(globalDir, 'global-only-persona', ['model: opus']);
+
+  const model = resolveEpicModel({
+    cwd,
+    claudeSessionId: 'sess-global-only',
+    deps: { globalDir, validatePath: noopValidatePath },
+  });
+
+  expect(model).toBe('opus');
+});
+
+test('resolveEpicModel falls back to FALLBACK_MODEL (never throws) for a dangling agentType with no persona file anywhere, and logs it once', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
+  const globalDir = await mkTmpDir('sm-agentmodel-agents-'); // never written to
+  writeIndex(cwd, { 'epic-1': { id: 'epic-1', claudeSessionId: 'sess-dangling', agentType: 'ghost-persona' } });
+
+  const call = () => resolveEpicModel({
+    cwd,
+    claudeSessionId: 'sess-dangling',
+    deps: { globalDir, validatePath: noopValidatePath },
+  });
+
+  expect(call).not.toThrow();
+  expect(call()).toBe(FALLBACK_MODEL);
+  call(); // second call must not log a second line (dedup per (cwd, agentType))
+
+  const { todayFile } = require('../lib/opsErrorLog.cjs');
+  const lines = fs.readFileSync(todayFile(cwd), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const matches = lines.filter((l) => l.message.includes('ghost-persona'));
+  expect(matches).toHaveLength(1);
+});
+
+// Chat (chatRunner.cjs, in-process) and Terminal (EpicTerminalPane.tsx, via
+// the agents:resolve-epic-model IPC added in this change) both call this
+// exact function with the same { cwd, claudeSessionId } shape — so "the same
+// Epic resolves identically in both views" is structural (one function, one
+// call signature), not a coincidence of two implementations agreeing. This
+// asserts the function is a pure, deterministic read of that Epic's overlay-
+// resolved persona model, which is what makes that guarantee hold.
+test('resolveEpicModel resolves identically for the same Epic across repeated calls (the guarantee Chat and Terminal both rely on)', async () => {
+  const cwd = await mkTmpDir('sm-agentmodel-cwd-');
+  const globalDir = await mkTmpDir('sm-agentmodel-agents-');
+  writeIndex(cwd, { 'epic-1': { id: 'epic-1', claudeSessionId: 'sess-shared', agentType: 'shared-epic-persona' } });
+  writePersona(globalDir, 'shared-epic-persona', ['model: haiku']);
+
+  const callArgs = { cwd, claudeSessionId: 'sess-shared', deps: { globalDir, validatePath: noopValidatePath } };
+  const chatResult = resolveEpicModel(callArgs);
+  const terminalResult = resolveEpicModel(callArgs); // simulates the IPC-forwarded call Terminal makes
+
+  expect(chatResult).toBe('haiku');
+  expect(terminalResult).toBe(chatResult);
+});
+
+// --model must never be left unpinned (CLAUDE.md model-pinning rule) on any
+// of the three launch paths. resolvePrdPersonaForSpawn's own miss-path tests
+// above already cover the scheduler call site; this covers the shared
+// Chat/Terminal resolver.
+test('resolveEpicModel never returns an empty/falsy --model value, even on every miss path', async () => {
+  expect(resolveEpicModel({})).toBeTruthy();
+  expect(resolveEpicModel({ cwd: '/nonexistent-cwd-xyz', claudeSessionId: 'no-such-session' })).toBeTruthy();
+});
+
 test('resolvePrdPersonaForSpawn caps the persona body at 6000 characters with a truncation notice naming the persona path', async () => {
   const longBody = 'x'.repeat(6500);
   const result = await resolvePrdPersonaForSpawn({

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

@@ -101,4 +101,22 @@ test('flush() with no pending timer still sends (no-arm case)', async () => {
   expect(sent).toEqual(['state-1']);
 });
 
+test('a getPayload() that throws does not wedge the coalescer — the next schedule() still sends', async () => {
+  const sent = [];
+  const send = vi.fn((payload) => sent.push(payload));
+  const getPayload = vi.fn()
+    .mockRejectedValueOnce(new Error('boom'))
+    .mockResolvedValue('state-recovered');
+  const coalescer = createBroadcastCoalescer({ delayMs: 200, send, getPayload });
+
+  coalescer.schedule();
+  await vi.advanceTimersByTimeAsync(200);
+  expect(sent).toEqual([]);
+
+  coalescer.schedule();
+  await vi.advanceTimersByTimeAsync(200);
+  expect(sent).toEqual(['state-recovered']);
+  expect(getPayload).toHaveBeenCalledTimes(2);
+});
+
 console.log('broadcastCoalescer tests: PASS');

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

@@ -287,8 +287,8 @@ test('ensureEpic refuses the mint and appends an epic_mint_refused audit event w
 // "throw on write, report on read" — a mint whose agentType names a persona
 // that doesn't resolve is refused outright; a persona that goes dangling
 // LATER (renamed/deleted after the Epic was minted) is legitimate history,
-// left to agentModelResolve.cjs's readPersonaModel (stays permissive) and the
-// ops-hygiene sweep to report.
+// left to agentModelResolve.cjs's readOverlayAwarePersonaModel (stays
+// permissive) and the ops-hygiene sweep to report.
 
 test('minting with an unknown agentType throws and names the two paths checked', async () => {
   const cwd = await mkCwd();

package/src/main/__tests__/health-delegation-chain.test.cjs

@@ -86,7 +86,7 @@ test('failing check with no fix omits the "(fix: ...)" suffix', () => {
 test('end-to-end: check() reports delegation_chain for this repo, expected to pass here', async () => {
   const status = await check();
   expect(status.components.delegation_chain).toBeDefined();
-  expect(status.components.delegation_chain.checks).toHaveLength(8);
+  expect(status.components.delegation_chain.checks).toHaveLength(9);
   const ids = status.components.delegation_chain.checks.map((c) => c.id);
   expect(ids).toEqual([
     'scheduler-mcp',
@@ -97,6 +97,7 @@ test('end-to-end: check() reports delegation_chain for this repo, expected to pa
     'prd-write-guard',
     'destructive-git-guard',
     'inline-implementation-guard',
+    'self-schedule-guard',
   ]);
   // This repo registers the scheduler MCP at user scope (~/.claude.json) and
   // wires guard-prd-writes in .claude/settings.json, and no longer carries a

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

@@ -0,0 +1,162 @@
+/**
+ * needsReviewLedger.test.cjs — unit tests for src/main/lib/needsReviewLedger.cjs's
+ * pure ladder-rung classification, line builders, and rollup reduction.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/needsReviewLedger.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  LADDER_RUNGS,
+  classifyLadderRung,
+  buildNeedsReviewEntryLine,
+  buildNeedsReviewResolutionLine,
+  reduceNeedsReviewLedger,
+} = require('../lib/needsReviewLedger.cjs');
+
+// ---------- classifyLadderRung ----------
+
+test('classifyLadderRung maps every known automated source to its named rung', () => {
+  expect(classifyLadderRung({ source: 'scheduler:mechanicalRecovery' })).toBe('mechanical-recovery');
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for resume-recovery' })).toBe('resume-recovery');
+  expect(classifyLadderRung({ source: 'spawnInvestigation:start' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'spawnJob:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:auto-promote' })).toBe('auto-fix');
+  expect(classifyLadderRung({ source: 'reverifyNeedsReview:heal' })).toBe('reverify');
+  expect(classifyLadderRung({ source: 'needsReviewAutoResolve' })).toBe('reverify');
+});
+
+test('classifyLadderRung: ordinary spawnJob:dispatch (no resume-recovery reason) is NOT resume-recovery', () => {
+  // 'spawnJob:dispatch' is shared with the everyday pending->running dispatch
+  // — only the resume-recovery REASON text distinguishes the two.
+  expect(classifyLadderRung({ source: 'spawnJob:dispatch', reason: 'dispatched for execution' })).toBe('manual-reset');
+});
+
+test('classifyLadderRung: unrecognized/explicit-reset sources default to manual-reset', () => {
+  expect(classifyLadderRung({ source: 'ipc:schedule:reset-job' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'remote:resetJob' })).toBe('manual-reset');
+  expect(classifyLadderRung({ source: 'clear-queue' })).toBe('manual-reset');
+  expect(classifyLadderRung({})).toBe('manual-reset');
+});
+
+test('LADDER_RUNGS names exactly the 6 documented rungs', () => {
+  expect(LADDER_RUNGS).toEqual(['mechanical-recovery', 'resume-recovery', 'quarantine', 'auto-fix', 'reverify', 'manual-reset']);
+});
+
+// ---------- buildNeedsReviewEntryLine / buildNeedsReviewResolutionLine ----------
+
+test('buildNeedsReviewEntryLine: park reason prefers verifierVerdict, then heldReason, then error', () => {
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  expect(buildNeedsReviewEntryLine({ slug: 's1', verifierVerdict: 'uncommitted_changes', heldReason: 'held', error: 'err' }, entry).reason).toBe('uncommitted_changes');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', heldReason: 'held', error: 'err' }, entry).reason).toBe('held');
+  expect(buildNeedsReviewEntryLine({ slug: 's1', error: 'err' }, entry).reason).toBe('err');
+  expect(buildNeedsReviewEntryLine({ slug: 's1' }, entry).reason).toBeNull();
+});
+
+test('buildNeedsReviewEntryLine: carries slug/cwd/epicId/runId/at/source verbatim', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-9' };
+  const entry = { to: 'needs_review', source: 'spawnJob:finalize', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewEntryLine(job, entry);
+  expect(line).toEqual({
+    kind: 'needs_review_entry',
+    slug: '42-x',
+    cwd: '/proj',
+    epicId: 'epic-1',
+    runId: 'run-9',
+    at: '2026-09-13T00:00:00.000Z',
+    reason: null,
+    source: 'spawnJob:finalize',
+  });
+});
+
+test('buildNeedsReviewResolutionLine: references the EPISODE runId, not job.runId, and computes dwellMs', () => {
+  const job = { slug: '42-x', cwd: '/proj', epicId: 'epic-1', runId: 'run-LATER' };
+  const entry = { to: 'completed', source: 'reverifyNeedsReview:heal', at: '2026-09-13T00:10:00.000Z' };
+  const episode = { runId: 'run-ORIGINAL', enteredAt: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, episode);
+  expect(line.runId).toBe('run-ORIGINAL');
+  expect(line.resolvedTo).toBe('completed');
+  expect(line.ladderRung).toBe('reverify');
+  expect(line.dwellMs).toBe(10 * 60_000);
+});
+
+test('buildNeedsReviewResolutionLine: dwellMs is null when the episode has no enteredAt (defensive — should not happen in practice)', () => {
+  const job = { slug: '42-x', runId: 'run-1' };
+  const entry = { to: 'failed', source: 'ipc:schedule:reset-job', at: '2026-09-13T00:00:00.000Z' };
+  const line = buildNeedsReviewResolutionLine(job, entry, { runId: 'run-1', enteredAt: null });
+  expect(line.dwellMs).toBeNull();
+});
+
+// ---------- reduceNeedsReviewLedger ----------
+
+function entryLine({ slug, runId, at, reason = 'uncommitted_changes', source = 'spawnJob:finalize' }) {
+  return { kind: 'needs_review_entry', slug, cwd: null, epicId: null, runId, at, reason, source };
+}
+function resolutionLine({ slug, runId, at, resolvedTo = 'completed', ladderRung = 'reverify', source = 'reverifyNeedsReview:heal', dwellMs = 1000 }) {
+  return { kind: 'needs_review_resolution', slug, cwd: null, epicId: null, runId, at, resolvedTo, ladderRung, source, dwellMs };
+}
+
+test('reduceNeedsReviewLedger: entry-only (unresolved) episode counts toward byReason and unresolvedCount, not byLadderRung', () => {
+  const lines = [entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'silent_no_op' })];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ silent_no_op: 1 });
+  expect(rollup.byLadderRung).toEqual({});
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.dwellMsP50).toBeNull();
+  expect(rollup.dwellMsP90).toBeNull();
+});
+
+test('reduceNeedsReviewLedger: entry+resolution pair resolves and contributes dwell', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:05.000Z', dwellMs: 5000, ladderRung: 'mechanical-recovery' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(0);
+  expect(rollup.byLadderRung).toEqual({ 'mechanical-recovery': 1 });
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(5000);
+});
+
+test('reduceNeedsReviewLedger: repeated entries for the same slug (different runIds) count as independent episodes', () => {
+  const lines = [
+    entryLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:00.000Z', reason: 'uncommitted_changes' }),
+    resolutionLine({ slug: 'a', runId: 'r1', at: '2026-09-13T00:00:10.000Z', dwellMs: 10_000, ladderRung: 'manual-reset' }),
+    entryLine({ slug: 'a', runId: 'r2', at: '2026-09-13T01:00:00.000Z', reason: 'uncommitted_changes' }),
+    // r2 never resolves.
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.byReason).toEqual({ uncommitted_changes: 2 });
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(rollup.byLadderRung).toEqual({ 'manual-reset': 1 });
+  expect(rollup.dwellMsP50).toBe(10_000);
+});
+
+test('reduceNeedsReviewLedger: p50/p90 over several resolved episodes', () => {
+  const dwells = [1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10_000];
+  const lines = dwells.flatMap((d, i) => [
+    entryLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z' }),
+    resolutionLine({ slug: `s${i}`, runId: `r${i}`, at: '2026-09-13T00:00:00.000Z', dwellMs: d }),
+  ]);
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.dwellMsP50).toBe(5000);
+  expect(rollup.dwellMsP90).toBe(9000);
+});
+
+test('reduceNeedsReviewLedger: ignores unrelated (terminal) rows mixed into the same lines array', () => {
+  const lines = [
+    { kind: 'terminal', slug: 'a', status: 'completed', runId: 'r1' },
+    { slug: 'b', status: 'failed', runId: 'r2' }, // legacy row, no kind at all
+    entryLine({ slug: 'c', runId: 'r3', at: '2026-09-13T00:00:00.000Z' }),
+  ];
+  const rollup = reduceNeedsReviewLedger(lines);
+  expect(rollup.unresolvedCount).toBe(1);
+  expect(Object.keys(rollup.byReason)).toEqual(['uncommitted_changes']);
+});
+
+test('reduceNeedsReviewLedger: empty/non-array input returns a zeroed rollup, never throws', () => {
+  expect(reduceNeedsReviewLedger([])).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(null)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+  expect(reduceNeedsReviewLedger(undefined)).toEqual({ byReason: {}, byLadderRung: {}, unresolvedCount: 0, dwellMsP50: null, dwellMsP90: null });
+});

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

@@ -24,7 +24,7 @@ afterEach(async () => {
   if (originalSmTelemetrySpool === undefined) delete process.env.SM_TELEMETRY_SPOOL; else process.env.SM_TELEMETRY_SPOOL = originalSmTelemetrySpool;
   const telemetryPath = require.resolve('../lib/telemetryClient.cjs');
   delete require.cache[telemetryPath];
-  const activeSessionsPath = require.resolve('../../../scripts/lib/activeSessions.cjs');
+  const activeSessionsPath = require.resolve('../lib/activeSessions.cjs');
   delete require.cache[activeSessionsPath];
   while (tmpDirs.length) {
     const d = tmpDirs.pop();
@@ -89,8 +89,8 @@ test('an ephemeral cwd yields zero local lines but one telemetry record, with a
   const worktreeCwd = path.join(KIND_CONFIG.epic.root, 'fakehash', 'fake-epic-id');
   const realRoot = '/home/bilko/Projects/real-project';
 
-  const activeSessionsPath = require.resolve('../../../scripts/lib/activeSessions.cjs');
-  const original = require('../../../scripts/lib/activeSessions.cjs');
+  const activeSessionsPath = require.resolve('../lib/activeSessions.cjs');
+  const original = require('../lib/activeSessions.cjs');
   require.cache[activeSessionsPath] = {
     id: activeSessionsPath,
     filename: activeSessionsPath,

package/src/main/__tests__/pollLoop-dispatch-on-failure.test.cjs

@@ -73,10 +73,24 @@ function mkProject() {
   return { cwd, slug };
 }
 
+// dependsOn deliberately references a slug that can never resolve (no such
+// row, no history/archive entry) so pickNextBatch's dep gate holds this job
+// forever instead of ever handing it to spawnJob. tickQueue() still reaches
+// the picker and stamps lastDispatchAttemptAt (that stamp is unconditional —
+// see lastDispatchAttemptAt's own header comment), which is the only thing
+// these tests assert on. Without this, the picker actually dispatches the
+// job: spawnJob() is fire-and-forget (scheduler.cjs's own comment: "spawnJob
+// is fire-and-forget; it calls tickQueue() on completion") and its real
+// child-process exit handler later calls mutate() independently of the
+// tickTail chain flushPendingTick() drains — round-tripping whatever
+// lastDispatchAttemptAt was in memory at ITS read time. Reproduced outside
+// vitest: that stray write landed ~2s after this suite's own reset-to-null,
+// clobbering the NEXT test's "still null" assertion with the previous test's
+// stamp. A held (never-dispatched) job has no such background continuation.
 async function seedOnePendingJob() {
   const { cwd, slug } = mkProject();
   await scheduler.writeQueue({
-    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: [] }],
+    jobs: [{ slug, title: 'x', cwd, status: 'pending', dependsOn: ['unresolvable-dep-never-completes'] }],
     config: {},
     paused: null,
   });