claude-code-session-manager 0.85.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-DhvuQL4C.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.85.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,12 +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": "npm run lint:selectors && npm run lint:hooks"
+    "lint:unregistered-tests": "node scripts/check-unregistered-tests.cjs",
+    "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__/health-starve-escalation.test.cjs

@@ -0,0 +1,94 @@
+/**
+ * health-starve-escalation.test.cjs — `npm run health` must report
+ * non-GREEN when any project has been starved (findStarvedProjects) past
+ * the LATER escalation threshold (STARVE_ESCALATION_MS), naming the project
+ * and the hold reason scheduler.cjs's runStarveEscalationSweep already
+ * recorded on the matching 'project_starve_escalated' audit event — health
+ * runs as its own cold process with no access to the live scheduler's
+ * in-memory `lastTick`, so the durable audit-log.jsonl trail is the only
+ * place that reason survives to be read from here.
+ *
+ * Exercises evaluateStarveEscalationHealth() and
+ * latestStarveEscalationReasons() directly — pure/fs-scoped, matching every
+ * other evaluate* helper's test pattern in this file (see
+ * health-queue-dispatch.test.cjs's header). `project_starve_escalation` is
+ * wired into health.cjs's `criticalComponents` gate, so `ok: false` here is
+ * exactly what flips `npm run health`'s exit code from 0 to 1.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-starve-escalation.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  evaluateStarveEscalationHealth,
+  latestStarveEscalationReasons,
+} = require('../health.cjs');
+const { STARVE_ESCALATION_MS } = require('../scheduler.cjs');
+
+const CWD = '/home/bilko/Projects/Bilko';
+const NOW = Date.parse('2026-09-12T20:00:00.000Z');
+const idleFor = (ms) => NOW - ms;
+
+test('a project starved past the escalation threshold is non-GREEN and names the project + hold reason', () => {
+  const jobs = [{ slug: 'a', cwd: CWD, status: 'pending', createdAt: new Date(idleFor(STARVE_ESCALATION_MS + 60_000)).toISOString() }];
+  // findStarvedProjects requires some OTHER project to be running — an idle
+  // machine is not starvation, only a passed-over project is.
+  const allJobs = [...jobs, { slug: 'other', cwd: '/home/bilko/Projects/other', status: 'running' }];
+  const result = evaluateStarveEscalationHealth(allJobs, NOW, STARVE_ESCALATION_MS, { [CWD]: 'slots-exhausted' });
+  expect(result.ok).toBe(false);
+  expect(result.projects).toEqual([
+    expect.objectContaining({ cwd: CWD, pendingCount: 1, holdReason: 'slots-exhausted' }),
+  ]);
+  expect(result.message).toMatch(new RegExp(CWD.replace(/\//g, '\\/')));
+  expect(result.message).toMatch(/slots-exhausted/);
+});
+
+test('a starved project with no recorded escalation reason yet reports "unknown", not a throw', () => {
+  const allJobs = [
+    { slug: 'a', cwd: CWD, status: 'pending', createdAt: new Date(idleFor(STARVE_ESCALATION_MS + 1)).toISOString() },
+    { slug: 'other', cwd: '/home/bilko/Projects/other', status: 'running' },
+  ];
+  const result = evaluateStarveEscalationHealth(allJobs, NOW, STARVE_ESCALATION_MS, {});
+  expect(result.ok).toBe(false);
+  expect(result.projects[0].holdReason).toBe('unknown');
+});
+
+test('a starve below the escalation threshold stays GREEN', () => {
+  const allJobs = [
+    { slug: 'a', cwd: CWD, status: 'pending', createdAt: new Date(idleFor(STARVE_ESCALATION_MS - 60_000)).toISOString() },
+    { slug: 'other', cwd: '/home/bilko/Projects/other', status: 'running' },
+  ];
+  const result = evaluateStarveEscalationHealth(allJobs, NOW, STARVE_ESCALATION_MS, {});
+  expect(result).toEqual({ ok: true });
+});
+
+test('nothing pending anywhere stays GREEN', () => {
+  const result = evaluateStarveEscalationHealth([], NOW, STARVE_ESCALATION_MS, {});
+  expect(result).toEqual({ ok: true });
+});
+
+test('latestStarveEscalationReasons reads the LAST recorded holdReason per cwd from the audit log', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'starve-health-audit-'));
+  const auditPath = path.join(dir, 'audit-log.jsonl');
+  const lines = [
+    { kind: 'project_starved', cwd: CWD, ageMs: 1000 }, // different kind — must be ignored
+    { kind: 'project_starve_escalated', cwd: CWD, holdReason: 'memory-deferred' },
+    { kind: 'project_starve_escalated', cwd: CWD, holdReason: 'load-deferred' }, // latest wins
+    { kind: 'project_starve_escalated', cwd: '/home/bilko/Projects/other', holdReason: 'held' },
+  ];
+  fs.writeFileSync(auditPath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+
+  const reasons = latestStarveEscalationReasons(auditPath);
+  expect(reasons[CWD]).toBe('load-deferred');
+  expect(reasons['/home/bilko/Projects/other']).toBe('held');
+});
+
+test('latestStarveEscalationReasons returns {} for a missing audit log, never a throw', () => {
+  expect(latestStarveEscalationReasons('/nonexistent/path/audit-log.jsonl')).toEqual({});
+});

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

@@ -0,0 +1,31 @@
+/**
+ * loadGateDetailTick.test.cjs — unit test for the human-readable detail
+ * string a `reason: 'load-deferred'` tick surfaces to the renderer via
+ * lastTick.detail (buildScheduleStatePayload). Extracted as a pure function
+ * (formatLoadGateDetail) so this is testable without driving tickQueue's
+ * full fs/worktree machinery or launching the app.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/loadGateDetailTick.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { formatLoadGateDetail } = require('../scheduler.cjs');
+
+test('names the load gate, the measured ratio, the threshold and how long it has been held', () => {
+  const detail = formatLoadGateDetail({
+    loadavg1: 13.31,
+    cores: 14,
+    ratio: 0.951,
+    threshold: 0.85,
+    gatedSinceMs: 83 * 60_000,
+  });
+
+  expect(detail).toMatch(/load gate/i);
+  expect(detail).toContain('13.31');
+  expect(detail).toContain('14');
+  expect(detail).toContain('0.951');
+  expect(detail).toContain('0.85');
+  expect(detail).toMatch(/83m/);
+});

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

@@ -7,7 +7,7 @@
 
 import { test, expect } from 'vitest';
 const os = require('node:os');
-const { buildMachineProfile, computeMachineDigest, resolveInstallChannel } = require('../lib/machineProfile.cjs');
+const { buildMachineProfile, computeMachineDigest, resolveInstallChannel, resolveEnv } = require('../lib/machineProfile.cjs');
 
 function fakeOs(overrides = {}) {
   return {
@@ -132,3 +132,21 @@ test('resolveInstallChannel: dev when SM_DEV flag is set, regardless of app path
 test('resolveInstallChannel: unknown otherwise', () => {
   expect(resolveInstallChannel({ appPath: '/opt/some/app', devFlag: false })).toBe('unknown');
 });
+
+// ─── resolveEnv (wire-level env discriminator) ──────────────────────────
+
+test('resolveEnv: test when running under a test runner, regardless of installChannel', () => {
+  expect(resolveEnv({ isTestRunner: true, installChannel: 'dev' })).toBe('test');
+  expect(resolveEnv({ isTestRunner: true, installChannel: 'npx' })).toBe('test');
+  expect(resolveEnv({ isTestRunner: true, installChannel: 'unknown' })).toBe('test');
+});
+
+test('resolveEnv: dev when installChannel is dev and not under a test runner', () => {
+  expect(resolveEnv({ isTestRunner: false, installChannel: 'dev' })).toBe('dev');
+});
+
+test('resolveEnv: prod for every other installChannel (npx, unknown) when not under a test runner', () => {
+  expect(resolveEnv({ isTestRunner: false, installChannel: 'npx' })).toBe('prod');
+  expect(resolveEnv({ isTestRunner: false, installChannel: 'unknown' })).toBe('prod');
+  expect(resolveEnv({ isTestRunner: false, installChannel: undefined })).toBe('prod');
+});