claude-code-session-manager 0.39.2 → 0.39.4

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-BPbLVT6E.js"></script>
+    <script type="module" crossorigin src="./assets/index-XGsBHqYu.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-DVlD8N1X.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-DyLm7GM_.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.39.2",
+  "version": "0.39.4",
   "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",

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

@@ -77,7 +77,7 @@ can't load skills.
    do they actually share the same shape, or only look similar — confirm by reading, don't
    assume: a wrong assumption here means an inaccurate PRD, discovered only after the executor
    runs it), check existing tests for the area, and check whether a prior PRD already touched
-   this subsystem (`ls <cwd>/session-manager-operations/scheduler/prds/` for related slugs, in
+   this subsystem (`ls <cwd>/session-manager-operations/scheduler/epics/*/prds/` for related slugs, in
    the target repo) — duplicating or contradicting a still-queued PRD is a real failure mode,
    not a hypothetical one.
 
@@ -197,7 +197,7 @@ can't load skills.
    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:
    ```bash
-   ls <cwd>/session-manager-operations/scheduler/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
+   ls <cwd>/session-manager-operations/scheduler/epics/*/prds/ <cwd>/session-manager-operations/scheduler/prds-archived/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
    ```
    (`<cwd>` is the target repo's absolute path — the same one this PRD's `cwd` field will use.)
    The last line is the current max within that project. Then: same `NN` as a logically
@@ -218,19 +218,25 @@ can't load skills.
    system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour
    token-window resets, with auto-pause on rate-limit and auto-resume.
 
-   **Canonical location — non-negotiable.** PRDs MUST be written to, inside the target repo:
+   **Canonical location — non-negotiable.** Every PRD belongs to an **Epic** (the TAB → EPIC →
+   PRD domain model in the project CLAUDE.md). PRDs MUST be written to, inside the target repo:
    ```
-   <cwd>/session-manager-operations/scheduler/prds/<NN>-<kebab-slug>.md
+   <cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds/<NN>-<kebab-slug>.md
    ```
-   **Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the
-   old, now-retired global `prds/` dir under `~/.claude/session-manager/scheduled-plans/`,
-   the scheduler will not see it and the user loses their token-budget-managed execution. PRD
-   *source* files are per-project — each active project's own
-   `session-manager-operations/scheduler/prds/` directory, resolved at runtime from active
-   session cwds (`src/main/lib/prdLocations.cjs`) — but there is still exactly one **queue**
-   across all projects (`queue.json`/`history.jsonl`/`runs/` under
-   `~/.claude/session-manager/scheduled-plans/` remain global bookkeeping), because the 5-hour
-   token budget is global across all of the user's Claude work.
+   Get `<epic-id>`'s prds/ directory by minting (or joining) an Epic first:
+   ```bash
+   node <session-manager-repo>/scripts/mint-epic.cjs <cwd> "<one-line goal for this work>" [feature|bug|discussion]
+   ```
+   The last stdout line is the exact directory to write into. Reuse-by-goal makes it idempotent —
+   all PRDs of one /develop ask share one Epic. (The MCP `scheduler_create_prd` tool does all of
+   this automatically; the mint step is only for the manual-write fallback.)
+
+   **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`.
 
    **Filename rules.** `NN` is the 2-digit zero-padded parallel group (picked per the `ls`
    command above — same `NN` as an independent sibling, or next free `NN` = max+1 when this PRD

package/scripts/lib/watchdogHelpers.cjs

@@ -8,7 +8,9 @@ const os = require('node:os');
 const path = require('node:path');
 
 const { activeProjectCwds } = require('./activeSessions.cjs');
-const { resolvePrdWriteDir } = require('../../src/main/lib/prdLocations.cjs');
+const { resolvePrdWriteDir, listEpicPrdDirs } = require('../../src/main/lib/prdLocations.cjs');
+const { ensureEpic, appendPrdCreatedEvent } = require('../../src/main/lib/epicMint.cjs');
+const { projectQueuePath } = require('../../src/main/lib/queueStore.cjs');
 
 // Mirrors scheduler.cjs:215 (single source of truth there; kept in sync here).
 const DEFAULT_HEARTBEAT_PATH = path.join(
@@ -294,7 +296,7 @@ function hasOpenFeedback(cwd) {
  */
 function emitFeedbackPRD(cwd, {
   prdsDir,
-  queuePath = DEFAULT_QUEUE_PATH,
+  queuePath,
   skillPath,
   standardsPath,
   pluginCacheRoot = PLUGIN_CACHE_ROOT,
@@ -306,8 +308,18 @@ function emitFeedbackPRD(cwd, {
   // PRD dir so the sweep writer agrees with scheduler.cjs's reader (see
   // prdLocations.cjs — PRD chain 808→811 moved PRD sources out of the legacy
   // global dir into `<cwd>/session-manager-operations/scheduler/prds`).
+  let epicId = null;
   if (prdsDir === undefined) {
-    prdsDir = resolvePrdWriteDir(cwd);
+    // Every PRD belongs to an Epic (CLAUDE.md domain model). The sweep joins
+    // one standing "Inbound feedback" Epic per project (reuseByGoal) so
+    // recurring ticks chain into a single Epic rather than minting one each.
+    const epic = ensureEpic(cwd, {
+      goalText: 'Inbound feedback processing',
+      tag: 'discussion',
+      reuseByGoal: true,
+    });
+    epicId = epic.epicId;
+    prdsDir = epic.prdDir;
   }
   const skillPathExplicit = skillPath !== undefined;
   const standardsPathExplicit = standardsPath !== undefined;
@@ -319,11 +331,20 @@ function emitFeedbackPRD(cwd, {
   }
   const project = slugify(path.basename(cwd));
 
-  // De-dup: check queue.json for pending/running feedback job for this project.
-  let queueState = { jobs: [] };
-  try {
-    queueState = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
-  } catch { /* queue.json may not exist */ }
+  // De-dup: check the queue for a pending/running feedback job for this
+  // project. Federated state (2026-07-31): the project's own shard is the
+  // system of record; the legacy global path is still consulted as a fallback
+  // during transition. An explicit queuePath override (tests) wins verbatim.
+  const queuePaths = queuePath !== undefined
+    ? [queuePath]
+    : [projectQueuePath(cwd), DEFAULT_QUEUE_PATH];
+  const queueState = { jobs: [] };
+  for (const qp of queuePaths) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(qp, 'utf8'));
+      queueState.jobs.push(...(Array.isArray(parsed.jobs) ? parsed.jobs : []));
+    } catch { /* file may not exist */ }
+  }
 
   // project only contains [a-z0-9-] after slugify — no regex metachar escaping needed.
   const dupRe = new RegExp(`^\\d+-feedback-${project}$`);
@@ -341,18 +362,28 @@ function emitFeedbackPRD(cwd, {
   // watchdog tick emits a fresh NN-feedback-<project>.md, unbounded.
   const prdDupRe = new RegExp(`^\\d+-feedback-${project}\\.md$`);
   let maxNN = 0;
-  let prdFiles = [];
-  try {
-    prdFiles = fs.readdirSync(prdsDir);
-  } catch { /* prdsDir may not exist yet */ }
-  for (const f of prdFiles) {
-    if (prdDupRe.test(f)) {
-      return { emitted: false, reason: 'duplicate' };
-    }
-    const m = f.match(/^(\d+)-/);
-    if (m) {
-      const n = parseInt(m[1], 10);
-      if (n > maxNN) maxNN = n;
+  // NN numbering and the on-disk dedup are project-global, so scan every PRD
+  // location the project has: the write dir, the legacy flat dir, and every
+  // Epic's prds/ dir. (An explicit prdsDir override — tests — scans only it.)
+  const scanDirs = new Set([prdsDir]);
+  if (epicId !== null) {
+    try { scanDirs.add(resolvePrdWriteDir(cwd)); } catch { /* unusable cwd */ }
+    for (const d of listEpicPrdDirs(cwd)) scanDirs.add(d);
+  }
+  for (const dir of scanDirs) {
+    let prdFiles = [];
+    try {
+      prdFiles = fs.readdirSync(dir);
+    } catch { continue; /* dir may not exist yet */ }
+    for (const f of prdFiles) {
+      if (prdDupRe.test(f)) {
+        return { emitted: false, reason: 'duplicate' };
+      }
+      const m = f.match(/^(\d+)-/);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > maxNN) maxNN = n;
+      }
     }
   }
   const nn = String(maxNN + 1).padStart(2, '0');
@@ -440,6 +471,11 @@ function emitFeedbackPRD(cwd, {
     fs.mkdirSync(prdsDir, { recursive: true });
     fs.writeFileSync(tmpPath, body + '\n', 'utf8');
     fs.renameSync(tmpPath, prdPath);
+    if (epicId !== null) {
+      // Trace the dispatch on the Epic's event chain (prompt → prd_created →
+      // ...) so the Epic conversation shows the PRD it spawned.
+      try { appendPrdCreatedEvent(cwd, epicId, slug, `Feedback sweep emitted ${slug}`); } catch { /* trace is best-effort */ }
+    }
   } catch (e) {
     try { fs.unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
     throw e;
@@ -622,7 +658,7 @@ function maybeRelaunchApp({
 function sweep({
   projectsDir,
   prdsDir,
-  queuePath = DEFAULT_QUEUE_PATH,
+  queuePath,
   skillPath,
   standardsPath,
 } = {}) {

package/src/main/__tests__/health-prd-migration.test.cjs

@@ -0,0 +1,37 @@
+/**
+ * health-prd-migration.test.cjs — stranded-PRD-migration health signal
+ * (behind two real 2026-07-31 incidents: a single stranded PRD causing an
+ * instant ENOENT job failure, and 223 stranded legacy PRDs + a missing
+ * history.jsonl resurrecting 189 completed jobs). Exercises
+ * evaluatePrdMigrationHealth() directly since it's pure — no need to spawn
+ * the full check() (which shells out to npm run typecheck) to cover this.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-prd-migration.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { evaluatePrdMigrationHealth } = require('../health.cjs');
+
+const LEGACY_DIR = '/home/user/.claude/session-manager/scheduled-plans/prds';
+
+test('reports ok when nothing is stranded', () => {
+  const result = evaluatePrdMigrationHealth({ moved: 3, skipped: 0, unresolved: [] }, LEGACY_DIR);
+  expect(result.ok).toBe(true);
+  expect(result.strandedCount).toBe(0);
+  expect(result.legacyDir).toBe(LEGACY_DIR);
+  expect(result.unresolved).toBeUndefined();
+});
+
+test('reports RED with count and legacy dir path when files are stranded', () => {
+  const unresolved = [
+    { file: '01-stuck.md', reason: 'no cwd in frontmatter' },
+    { file: '02-stuck.md', reason: 'cwd does not exist on disk' },
+  ];
+  const result = evaluatePrdMigrationHealth({ moved: 0, skipped: 0, unresolved }, LEGACY_DIR);
+  expect(result.ok).toBe(false);
+  expect(result.strandedCount).toBe(2);
+  expect(result.legacyDir).toBe(LEGACY_DIR);
+  expect(result.unresolved).toEqual(unresolved);
+});

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

@@ -146,11 +146,13 @@ test('readHistory respects limit and returns [] when file is absent', async () =
   const empty = await queueHistory.readHistory({ limit: 5 });
   expect(empty).toEqual([]);
 
-  const entries = Array.from({ length: 8 }, (_, i) => old({ slug: `s${i}`, runId: `r${i}`, finishedAt: new Date(NOW - i * 60_000).toISOString() }));
+  // Realistic append order: oldest finishedAt first (append-only file grows
+  // forward in time), so s7 is both last-appended and newest.
+  const entries = Array.from({ length: 8 }, (_, i) => old({ slug: `s${i}`, runId: `r${i}`, finishedAt: new Date(NOW - (7 - i) * 60_000).toISOString() }));
   await queueHistory.appendHistory(entries);
   const read = await queueHistory.readHistory({ limit: 3 });
   expect(read.length).toBe(3);
-  // newest-appended-first == last 3 entries reversed
+  // Federated readHistory (2026-07-31) orders by finishedAt newest-first.
   expect(read.map((j) => j.slug)).toEqual(['s7', 's6', 's5']);
 });
 
@@ -165,8 +167,11 @@ test('readHistory tail-reads correctly when the file is larger than one chunk',
   }));
   await queueHistory.appendHistory(bigEntries);
   const read = await queueHistory.readHistory({ limit: 5 });
-  // appended in ascending index order; readHistory reverses to newest-appended-first
-  expect(read.map((j) => j.slug)).toEqual(['bulk-1999', 'bulk-1998', 'bulk-1997', 'bulk-1996', 'bulk-1995']);
+  // The tail read only touches the file's end; whatever was read comes back
+  // ordered by finishedAt newest-first.
+  expect(read.length).toBe(5);
+  const t = (j) => Date.parse(j.finishedAt);
+  for (let i = 1; i < read.length; i++) expect(t(read[i - 1])).toBeGreaterThanOrEqual(t(read[i]));
 });
 
 // ---------- selectHistoryJobs merge (scheduler.cjs) ----------

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

@@ -140,3 +140,15 @@ test('autoArchiveCompleted: tolerates a missing/malformed state.jobs', async ()
   const result = await autoArchiveCompleted({}, { nowMs: NOW });
   expect(result.archived).toBe(0);
 });
+
+// ---------- archiving never strands a runnable queue job (scheduler PRD:
+// archived-prd-skip — job 822-epics-nav-rename fired ENOENT after its PRD
+// was archived out from under a still-queued job) ----------
+
+test('selectAutoArchivable never selects a slug whose job is still pending or running, so auto-archive can never leave a runnable job pointing at an archived PRD', () => {
+  const pending = old({ slug: '13-pending', status: 'pending', finishedAt: null });
+  const running = old({ slug: '14-running', status: 'running', finishedAt: null });
+  const completed = old({ slug: '15-done', status: 'completed' });
+  const slugs = selectAutoArchivable([pending, running, completed], { nowMs: NOW });
+  expect(slugs).toEqual(['15-done']);
+});

package/src/main/__tests__/scheduler-archived-twin-guard.test.cjs

@@ -0,0 +1,92 @@
+/**
+ * scheduler-archived-twin-guard.test.cjs — unit tests for archivedTwinExists
+ * (PRD 822-promptsession-prd-trace-events recurrence fix): a queue row whose
+ * PRD `.md` has already been moved to the sibling `prds-archived/` dir (work
+ * shipped out-of-band) must be recognized as stale, not a genuine missing-PRD
+ * failure.
+ *
+ * Uses a temp cwd fixture (`prdDirForCwd` is a pure path join off `cwd`) so
+ * this never touches the real `~/.claude/session-manager/` tree.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-archived-twin-guard.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { archivedTwinExists, archivedPrdPathForJob, prdDirForCwd } = require('../scheduler.cjs');
+
+const tmpDirs = [];
+
+function makeFixtureCwd() {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-archived-twin-'));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+afterEach(() => {
+  while (tmpDirs.length) {
+    const dir = tmpDirs.pop();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('archivedTwinExists returns true when the archived twin exists and the live PRD does not', async () => {
+  const cwd = makeFixtureCwd();
+  const slug = 'test-shipped-and-archived';
+  const prdsDir = prdDirForCwd(cwd);
+  const archivedDir = path.join(prdsDir, '..', 'prds-archived');
+  fs.mkdirSync(archivedDir, { recursive: true });
+  fs.writeFileSync(path.join(archivedDir, `${slug}.md`), '# Goal\n\nshipped\n', 'utf8');
+
+  await expect(archivedTwinExists({ slug, cwd })).resolves.toBe(true);
+});
+
+test('archivedTwinExists returns false when neither the live PRD nor an archived twin exists', async () => {
+  const cwd = makeFixtureCwd();
+  const slug = 'test-genuinely-missing';
+  fs.mkdirSync(prdDirForCwd(cwd), { recursive: true });
+
+  await expect(archivedTwinExists({ slug, cwd })).resolves.toBe(false);
+});
+
+test('archivedTwinExists returns false for a slug whose archived twin belongs to a different cwd', async () => {
+  const cwd = makeFixtureCwd();
+  const otherCwd = makeFixtureCwd();
+  const slug = 'test-cross-cwd-twin';
+  const otherArchivedDir = path.join(prdDirForCwd(otherCwd), '..', 'prds-archived');
+  fs.mkdirSync(otherArchivedDir, { recursive: true });
+  fs.writeFileSync(path.join(otherArchivedDir, `${slug}.md`), '# Goal\n\nother project\n', 'utf8');
+  fs.mkdirSync(prdDirForCwd(cwd), { recursive: true });
+
+  await expect(archivedTwinExists({ slug, cwd })).resolves.toBe(false);
+});
+
+test('archivedTwinExists returns false when the PRD is still live in prds/ (never short-circuits a normal run)', async () => {
+  const cwd = makeFixtureCwd();
+  const slug = 'test-still-live';
+  const prdsDir = prdDirForCwd(cwd);
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), '# Goal\n\nlive\n', 'utf8');
+
+  await expect(archivedTwinExists({ slug, cwd })).resolves.toBe(false);
+});
+
+test('archivedPrdPathForJob resolves to the sibling prds-archived/<slug>.md for a job cwd', () => {
+  const cwd = makeFixtureCwd();
+  const job = { cwd, slug: 'my-slug' };
+  const prdsDir = prdDirForCwd(cwd);
+  const expected = path.join(prdsDir, '..', 'prds-archived', 'my-slug.md');
+  expect(archivedPrdPathForJob(job)).toBe(expected);
+});
+
+test('archivedPrdPathForJob does not escape prds-archived/ for a well-formed slug', () => {
+  const cwd = makeFixtureCwd();
+  const job = { cwd, slug: 'well-formed-slug' };
+  const resolved = path.resolve(archivedPrdPathForJob(job));
+  const archiveDir = path.resolve(path.join(prdDirForCwd(cwd), '..', 'prds-archived'));
+  expect(resolved.startsWith(archiveDir + path.sep)).toBe(true);
+});

package/src/main/__tests__/scheduler-unreadable-queue-guard.test.cjs

@@ -32,7 +32,7 @@ const unreadableState = () => ({
 });
 
 test('writeQueue refuses to persist a state derived from an unreadable read', async () => {
-  await expect(writeQueue(unreadableState())).rejects.toThrow(/refusing to write queue\.json/i);
+  await expect(writeQueue(unreadableState())).rejects.toThrow(/refusing to write queue/i);
 });
 
 test('writeQueue still persists a normal state (guard is not a blanket block)', () => {

package/src/main/chatRunner.cjs

@@ -54,6 +54,7 @@ const { recordExchange } = require('./exchanges.cjs');
 const { classifyToolUse } = require('./lib/toolUseClassify.cjs');
 const { extractJson } = require('./lib/extractJson.cjs');
 const { classifyPromptTicket } = require('./lib/classifyPromptTicket.cjs');
+const sessionSlots = require('./lib/sessionSlots.cjs');
 
 // ─── Stop-signal protocol ──────────────────────────────────────────────────
 // Single source of truth for the sentinel and parser. The renderer (PRD 320)
@@ -387,6 +388,12 @@ function run(opts) {
 // the remainder. O(n) over the waiting list (bounded by open tabs).
 function pump() {
   while (activeCount < getConcurrencyCap() && waiting.length > 0) {
+    // The chat lane cap is a POLICY bound; actual capacity comes from the
+    // Session-Manager-wide slot pool shared with the scheduler
+    // (lib/sessionSlots.cjs). No slot → everyone keeps waiting; the next
+    // settle() in either subsystem re-pumps.
+    const slotToken = sessionSlots.acquire(`chat:${waiting[0].tabId}`);
+    if (!slotToken) break;
     const job = waiting.shift();
     activeCount += 1;
     Promise.resolve()
@@ -397,7 +404,7 @@ function pump() {
         return donePromise;
       })
       .catch(() => { /* executeRun never rejects; defensive */ })
-      .finally(() => { activeCount -= 1; pump(); });
+      .finally(() => { sessionSlots.release(slotToken); activeCount -= 1; pump(); });
   }
   // Anyone still waiting gets a 1-based position update. Silent (automated
   // probe) runs must stay invisible to the renderer, same as every other
@@ -409,6 +416,9 @@ function pump() {
   });
 }
 
+// A slot freed anywhere (e.g. a scheduler job settled) may unblock our lane.
+sessionSlots.subscribe(() => { try { pump(); } catch { /* defensive */ } });
+
 // ─── Core runner ──────────────────────────────────────────────────────────
 
 /**

package/src/main/health.cjs

@@ -12,6 +12,8 @@ const { execFileSync } = require('node:child_process');
 const { POLL_INTERVAL_MS } = require('./lib/schedulerConfig.cjs');
 const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
+const { migratePrds } = require('./lib/prdMigration.cjs');
+const queueStore = require('./lib/queueStore.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -119,6 +121,19 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
   };
 }
 
+// Pure evaluator over migratePrds()'s { moved, skipped, unresolved } result —
+// kept separate from the fs-touching check() call site so it's directly
+// unit-testable, matching evaluateTickLiveness's pattern.
+function evaluatePrdMigrationHealth(migrationResult, legacyPrdsDir) {
+  const strandedCount = migrationResult.unresolved.length;
+  return {
+    ok: strandedCount === 0,
+    legacyDir: legacyPrdsDir,
+    strandedCount,
+    ...(strandedCount > 0 ? { unresolved: migrationResult.unresolved } : {}),
+  };
+}
+
 async function check() {
   const start = Date.now();
   const status = {
@@ -183,16 +198,14 @@ async function check() {
     status.ok = false;
   }
 
-  // 3. Check scheduler PRD directory and queue.json.
-  const schedulerBaseDir = path.join(
-    os.homedir(),
-    '.claude/session-manager/scheduled-plans'
-  );
-  const queuePath = path.join(schedulerBaseDir, 'queue.json');
+  // 3. Check scheduler state (federated, 2026-07-31): machine runtime file +
+  // per-project job shards merged via queueStore — the retired global
+  // queue.json is no longer consulted.
+  const queuePath = queueStore.MACHINE_STATE_PATH;
   let queueState = null;
   try {
-    const queueText = await fsp.readFile(queuePath, 'utf8');
-    queueState = JSON.parse(queueText);
+    queueState = queueStore.readMergedSync();
+    if (queueState.unreadable) throw new Error(queueState.unreadable);
     const runningCount = Object.values(queueState.jobs || {}).filter(
       (j) => j.status === 'running'
     ).length;
@@ -266,6 +279,29 @@ async function check() {
     ...(prdsDirs.length === 0 || anyPrdsDirAccessible ? {} : { exists: false }),
   };
 
+  // 4.5. Check for stranded legacy-dir PRDs left behind by runPrdMigration()
+  // (scheduler.cjs). A stranded PRD is the cheapest generic leading indicator
+  // of a stale installed build vs. the git repo — it fires regardless of
+  // *why* the build is stale (the 2026-07-31 burrow-project ENOENT + the
+  // 223-file/189-resurrected-job incident both trace back to this).
+  const legacyPrdsDir = path.join(
+    os.homedir(),
+    '.claude/session-manager/scheduled-plans/prds'
+  );
+  try {
+    const migrationResult = await migratePrds(legacyPrdsDir);
+    status.components.prd_migration = evaluatePrdMigrationHealth(migrationResult, legacyPrdsDir);
+  } catch (e) {
+    status.components.prd_migration = { ok: false, legacyDir: legacyPrdsDir, error: e.message };
+  }
+  if (!status.components.prd_migration.ok) {
+    status.issues.push(
+      status.components.prd_migration.error
+        ? `PRD migration check failed: ${status.components.prd_migration.error}`
+        : `PRD migration: ${status.components.prd_migration.strandedCount} file(s) stranded in legacy dir ${legacyPrdsDir} — could not be resolved into a per-project dir`
+    );
+  }
+
   // 5. Check transcripts directory (where live session logs are tailed).
   const projectsDir = path.join(os.homedir(), '.claude/projects');
   try {
@@ -329,7 +365,7 @@ async function check() {
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -345,4 +381,4 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { check, evaluateTickLiveness, readFreshHeartbeat, TICK_STALL_THRESHOLD_MS, HEARTBEAT_STALE_MS };
+module.exports = { check, evaluateTickLiveness, readFreshHeartbeat, evaluatePrdMigrationHealth, TICK_STALL_THRESHOLD_MS, HEARTBEAT_STALE_MS };

package/src/main/index.cjs

@@ -450,9 +450,12 @@ ipcMain.handle('app:home-self-check', () => bootHomeSelfCheck);
 ipcMain.handle('app:pick-directory', async () => {
   console.log('[main] pick-directory invoked');
   const result = await dialog.showOpenDialog(mainWindow, {
-    properties: ['openDirectory'],
+    // createDirectory enables the picker's "New Folder" affordance (macOS;
+    // the GTK chooser has its own) — this is the "Start Project" path:
+    // create a fresh folder in place, open it as the project's TAB.
+    properties: ['openDirectory', 'createDirectory'],
     defaultPath: os.homedir(),
-    title: 'Choose project directory for new session',
+    title: 'Open a project folder — or create a new one to start a project',
   });
   console.log('[main] pick-directory result:', result);
   if (result.canceled || result.filePaths.length === 0) return null;
@@ -760,7 +763,7 @@ voiceWizard.registerWizardHandlers();
 scheduler.registerScheduleHandlers();
 watchers.registerWatcherHandlers();
 teams.registerTeamsHandlers();
-queueOps.registerQueueOpsHandlers();
+queueOps.registerQueueOpsHandlers({ retireCompletedSlugs: scheduler.retireCompletedSlugs });
 registerHistoryAggregatorHandlers();
 registerHistoryDashboardHandlers();
 pluginInstall.registerPluginInstallHandlers();

package/src/main/lib/__tests__/sessionSlots.test.cjs

@@ -0,0 +1,55 @@
+// sessionSlots.cjs — the Session-Manager-owned machine-wide claude -p pool.
+// vitest globals (test/beforeEach/afterEach) — same convention as the other .cjs tests.
+const assert = require('node:assert');
+const slots = require('../sessionSlots.cjs');
+
+beforeEach(() => slots.__resetForTests());
+afterEach(() => {
+  slots.__resetForTests();
+  delete process.env.SM_SESSION_SLOTS;
+});
+
+test('pool defaults to 3 slots and exhausts', () => {
+  assert.equal(slots.totalSlots(), 3);
+  const t1 = slots.acquire('a');
+  const t2 = slots.acquire('b');
+  const t3 = slots.acquire('c');
+  assert.ok(t1 && t2 && t3);
+  assert.equal(slots.available(), 0);
+  assert.equal(slots.acquire('d'), null, 'fourth acquire must be refused');
+  slots.release(t2);
+  assert.equal(slots.available(), 1);
+  assert.ok(slots.acquire('d'));
+});
+
+test('SM_SESSION_SLOTS overrides, clamped to [1,3]', () => {
+  process.env.SM_SESSION_SLOTS = '1';
+  assert.equal(slots.totalSlots(), 1);
+  process.env.SM_SESSION_SLOTS = '9';
+  assert.equal(slots.totalSlots(), 3, 'clamped high');
+  process.env.SM_SESSION_SLOTS = '0';
+  assert.equal(slots.totalSlots(), 1, 'clamped low');
+  process.env.SM_SESSION_SLOTS = 'junk';
+  assert.equal(slots.totalSlots(), 3, 'non-numeric falls back to default');
+});
+
+test('release is idempotent and notifies subscribers exactly on real releases', () => {
+  let notified = 0;
+  const unsub = slots.subscribe(() => { notified += 1; });
+  const t = slots.acquire('a');
+  assert.equal(slots.release(t), true);
+  assert.equal(slots.release(t), false, 'double release is a no-op');
+  assert.equal(notified, 1, 'no notification for the no-op release');
+  unsub();
+  const t2 = slots.acquire('b');
+  slots.release(t2);
+  assert.equal(notified, 1, 'unsubscribed listener stays quiet');
+});
+
+test('snapshot names holders for attribution', () => {
+  slots.acquire('scheduler:42-fix-thing');
+  slots.acquire('chat:tab-1');
+  const snap = slots.snapshot();
+  assert.equal(snap.inUse, 2);
+  assert.deepEqual(snap.holders.map((h) => h.owner).sort(), ['chat:tab-1', 'scheduler:42-fix-thing']);
+});