claude-code-session-manager 0.39.3 → 0.40.0

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/__tests__/uniquePrdNumbers.test.cjs

@@ -0,0 +1,119 @@
+// PRD 832 — unique per-project PRD numbers + dependsOn eligibility.
+// User decision 2026-07-31: duplicate NN must be impossible; ordering is
+// expressed via dependsOn frontmatter, never via shared numbers.
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const prdParser = require('../scheduler/prdParser.cjs');
+const { pickForProject } = require('../lib/schedulerBatch.cjs');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'sm-832-'));
+}
+
+const job = (slug, status, group, extra = {}) => ({
+  slug, status, parallelGroup: group, cwd: '/proj', ...extra,
+});
+
+describe('allocateParallelGroup extraFloor (PRD 832)', () => {
+  it('never allocates at or below the cross-dir max', async () => {
+    const dir = tmpdir();
+    // Bookkeeping dir itself is empty; another dir in the project already
+    // used numbers up to 830.
+    const nn = await prdParser.allocateParallelGroup(dir, { extraFloor: 830 });
+    expect(nn).toBe(831);
+    // And the high-water mark persists the raised floor for later calls.
+    const nn2 = await prdParser.allocateParallelGroup(dir);
+    expect(nn2).toBe(832);
+  });
+
+  it('local scan still wins when higher than extraFloor', async () => {
+    const dir = tmpdir();
+    fs.writeFileSync(path.join(dir, '900-existing.md'), '---\ntitle: x\n---\n# Goal\n');
+    const nn = await prdParser.allocateParallelGroup(dir, { extraFloor: 10 });
+    expect(nn).toBe(901);
+  });
+});
+
+describe('parsePrdRaw dependsOn (PRD 832)', () => {
+  it('parses bracket and comma forms, rejects junk', async () => {
+    const dir = tmpdir();
+    const fp = path.join(dir, '840-x.md');
+    fs.writeFileSync(fp, '---\ntitle: x\ncwd: /proj\ndependsOn: [833-epics-review-fixes, 834-guard]\n---\n# Goal\nbody\n');
+    const p = await prdParser.parsePrdRaw(fp);
+    expect(p.dependsOn).toEqual(['833-epics-review-fixes', '834-guard']);
+
+    const fp2 = path.join(dir, '841-y.md');
+    fs.writeFileSync(fp2, '---\ntitle: y\ncwd: /proj\ndependsOn: 833-a, ../evil/path, 834-b\n---\n# Goal\nbody\n');
+    const p2 = await prdParser.parsePrdRaw(fp2);
+    expect(p2.dependsOn).toEqual(['833-a', '834-b']);
+
+    const fp3 = path.join(dir, '842-z.md');
+    fs.writeFileSync(fp3, '---\ntitle: z\ncwd: /proj\n---\n# Goal\nbody\n');
+    const p3 = await prdParser.parsePrdRaw(fp3);
+    expect(p3.dependsOn).toEqual([]);
+  });
+});
+
+describe('pickForProject dependsOn eligibility (PRD 832)', () => {
+  it('holds a job while its dep row is pending/running; releases when completed', () => {
+    const dep = job('850-base', 'running', 850);
+    const dependent = job('851-next', 'pending', 851, { dependsOn: ['850-base'] });
+
+    // Dep running (tracked in queue rows, not runningSet) — not eligible.
+    let res = pickForProject([dep, dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).not.toContain('851-next');
+
+    // Dep completed — eligible.
+    res = pickForProject([{ ...dep, status: 'completed' }, dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).toContain('851-next');
+  });
+
+  it('a dep slug with NO queue row counts as done (retired to history)', () => {
+    const dependent = job('853-next', 'pending', 853, { dependsOn: ['852-archived-long-ago'] });
+    const res = pickForProject([dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).toContain('853-next');
+  });
+
+  it('a FAILED dep holds the dependent with an explicit depends-gate reason', () => {
+    const dep = job('854-base', 'failed', 854);
+    const dependent = job('855-next', 'pending', 855, { dependsOn: ['854-base'] });
+    const res = pickForProject([dep, dependent], new Set(), 3);
+    expect(res.batch).toEqual([]);
+    expect(res.reason).toMatch(/depends-gate/);
+    expect(res.reason).toContain('855-next');
+    expect(res.reason).toContain('854-base');
+  });
+
+  it('legacy same-NN pending jobs keep their wave order untouched', () => {
+    const a = job('827-one', 'pending', 827);
+    const b = job('827-two', 'pending', 827);
+    const later = job('828-three', 'pending', 828);
+    const res = pickForProject([a, b, later], new Set(), 3);
+    expect(res.batch.map((j) => j.slug).sort()).toEqual(['827-one', '827-two']);
+  });
+});
+
+describe('reconcile retires archived-twin pending rows (post-832 cleanup)', () => {
+  it('drops a pending row whose PRD lives in prds-archived, keeps a normal invisible pending row', async () => {
+    const scheduler = require('../scheduler.cjs');
+    const root = tmpdir();
+    const opsDir = path.join(root, 'session-manager-operations', 'scheduler');
+    fs.mkdirSync(path.join(opsDir, 'prds'), { recursive: true });
+    fs.mkdirSync(path.join(opsDir, 'prds-archived'), { recursive: true });
+    fs.writeFileSync(path.join(opsDir, 'prds-archived', '833-landed-inline.md'), '---\ntitle: x\n---\n# Goal\n');
+
+    const state = {
+      jobs: [
+        job('833-landed-inline', 'pending', 833, { cwd: root }),
+        job('900-still-hidden', 'pending', 900, { cwd: root }),
+      ],
+    };
+    await scheduler.reconcile(state);
+    const slugs = state.jobs.map((j) => j.slug);
+    expect(slugs).not.toContain('833-landed-inline');
+    expect(slugs).toContain('900-still-hidden');
+  });
+});

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/config.cjs

@@ -152,6 +152,16 @@ function validateWrite(realAbs) {
       if (realAbs === promptSessionsSub || realAbs.startsWith(promptSessionsSub + path.sep)) {
         return;
       }
+      // Scheduler PRD sources (PRD 825 — per-project Epic PRD dirs under
+      // scheduler/epics/<id>/prds/, plus the legacy flat scheduler/prds/ and
+      // scheduler/state/ shards): narrowly scoped to
+      // session-manager-operations/scheduler/, this repo's existing
+      // per-project artifact-store convention (scheduler.cjs's remote.writePrd
+      // writes here via config.writeTextAtomic).
+      const schedulerSub = path.join(realRoot, 'session-manager-operations', 'scheduler');
+      if (realAbs === schedulerSub || realAbs.startsWith(schedulerSub + path.sep)) {
+        return;
+      }
     }
   }
   throw new Error(`Write outside allowed write boundaries: ${realAbs}`);

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

@@ -7,6 +7,7 @@ const os = require('node:os');
 const { schemas, validated } = require('./ipcSchemas.cjs');
 const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
 const { terminateLosingInstance } = require('./lib/singleInstanceGuard.cjs');
+const { acquireSchedulerOwnership, releaseSchedulerOwnership } = require('./lib/instanceLock.cjs');
 const { manager: ptyManager, registerPtyHandlers } = require('./pty.cjs');
 const browserView = require('./browserView.cjs');
 const browserCapture = require('./browserCapture.cjs');
@@ -450,9 +451,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 +764,7 @@ voiceWizard.registerWizardHandlers();
 scheduler.registerScheduleHandlers();
 watchers.registerWatcherHandlers();
 teams.registerTeamsHandlers();
-queueOps.registerQueueOpsHandlers();
+queueOps.registerQueueOpsHandlers({ retireCompletedSlugs: scheduler.retireCompletedSlugs });
 registerHistoryAggregatorHandlers();
 registerHistoryDashboardHandlers();
 pluginInstall.registerPluginInstallHandlers();
@@ -1087,12 +1091,26 @@ app.whenReady().then(async () => {
   webRemote.attachWindow(mainWindow);
   chatRunner.attachWindow(mainWindow);
   attachDocEditWindow(mainWindow);
-  scheduler.init().catch((e) => {
-    logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
-  });
-  adminHttp.start().catch((e) => {
-    logs.writeLine({ scope: 'admin-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
-  });
+  // Scheduler ownership (PRD 834): exactly one instance machine-wide runs
+  // scheduler mutation (boot reconciliation, ticking, sweep, supervisor) and
+  // the admin API. Electron's own single-instance lock is keyed by userData
+  // identity, which a dev/e2e/Playwright launch bypasses — live incident
+  // 2026-07-31: a secondary instance's boot reconciliation SIGTERM'd the
+  // owner's running job and overwrote admin-api.json. Losing instances run
+  // scheduler-PASSIVE: read IPC still works (handlers registered above),
+  // nothing mutates.
+  const ownership = acquireSchedulerOwnership();
+  if (ownership.owner) {
+    scheduler.init().catch((e) => {
+      logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
+    });
+    adminHttp.start().catch((e) => {
+      logs.writeLine({ scope: 'admin-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
+    });
+  } else {
+    console.log(`[main] scheduler ownership held by pid ${ownership.holderPid} — running scheduler-passive (no reconciliation, no admin server)`);
+    logs.writeLine({ scope: 'scheduler', level: 'info', message: 'scheduler-passive: ownership held by another instance', meta: { holderPid: ownership.holderPid } });
+  }
   browserAgentServer.start().catch((e) => {
     logs.writeLine({ scope: 'browser-agent-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
@@ -1196,6 +1214,7 @@ app.on('activate', () => {
 });
 
 app.on('before-quit', () => {
+  releaseSchedulerOwnership();
   supervisor.stopSupervisor();
   ptyManager.killAll();
   configMgr.closeAllWatchers();

package/src/main/ipcSchemas.cjs

@@ -20,6 +20,10 @@ const ptySpawn = z.object({
 
 const ptyTabId = z.object({ tabId: z.string().min(1).max(128) });
 
+// PRD 833 C1: Epics-workspace reconcile — which of these session keys still
+// have a live PTY? Bounded so the renderer can't ask about unbounded lists.
+const ptyAlive = z.object({ tabIds: z.array(z.string().min(1).max(128)).max(500) });
+
 // v2 mobile: subscribe to a session's live state + summary. cwd is needed to
 // locate the transcript JSONL (transcriptPath); validated against home-dir boundary
 // in webRemote before any fs access.
@@ -266,7 +270,12 @@ const schedulerCreatePrd = z.object({
   implementationNotes: z.string().min(1).max(20000),
   outOfScope: z.array(z.string().min(1).max(2000)).max(100).optional(),
   slug: z.string().min(1).max(60).regex(PRD_CREATE_SLUG_RE).optional(),
+  // DEPRECATED (PRD 832): accepted for wire-compat but ignored — numbers are
+  // strictly unique per project; use dependsOn for ordering.
   parallelGroup: z.number().int().min(1).max(999999).optional(),
+  // Explicit ordering (PRD 832): slugs that must complete before this PRD
+  // becomes eligible. Written to frontmatter as `dependsOn: [a, b]`.
+  dependsOn: z.array(z.string().min(1).max(160).regex(/^[A-Za-z0-9][\w.-]*$/)).max(20).optional(),
   // Originating PromptTicket.id (PRD 748) when this PRD was authored from a
   // ticket classified 'develop' (PRD 749) — traces the PRD back to the
   // prompt that spawned it. Same newline-injection guard as title/cwd since
@@ -726,6 +735,7 @@ module.exports = {
     webRemoteAuditTail,
     ptySpawn,
     ptyTabId,
+    ptyAlive,
     ptyWrite,
     ptyResize,
     sessionSubscribe,

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

@@ -0,0 +1,87 @@
+// PRD 834 — machine-wide scheduler-ownership lock. Secondary instances must
+// go scheduler-passive instead of running boot reconciliation / admin server
+// against the owner's queue state (live incident 2026-07-31).
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const {
+  acquireSchedulerOwnership,
+  releaseSchedulerOwnership,
+  pidAlive,
+  lockPath,
+} = require('../instanceLock.cjs');
+
+let dir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-instance-lock-'));
+  process.env.SM_SCHEDULER_LOCK_PATH = path.join(dir, 'scheduler-owner.lock');
+});
+
+afterEach(() => {
+  delete process.env.SM_SCHEDULER_LOCK_PATH;
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('instanceLock (PRD 834)', () => {
+  it('first acquirer becomes owner and writes its pid', () => {
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+    const onDisk = JSON.parse(fs.readFileSync(lockPath(), 'utf8'));
+    expect(onDisk.pid).toBe(process.pid);
+  });
+
+  it('a live foreign holder makes acquisition passive with the holder pid reported', () => {
+    // Use our own live pid as the "foreign" holder — pidAlive(process.pid) is
+    // true, and acquire treats pid !== process.pid as foreign, so fake one by
+    // writing pid 1 (init — always alive, never ours).
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 1, startedAt: 'x' }));
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(false);
+    expect(res.holderPid).toBe(1);
+    // The holder's lock is untouched.
+    expect(JSON.parse(fs.readFileSync(lockPath(), 'utf8')).pid).toBe(1);
+  });
+
+  it('a stale lock (dead pid) is broken and ownership taken', () => {
+    // Find a pid that is certainly dead: spawn nothing — use a huge pid
+    // beyond pid_max defaults.
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 2 ** 30, startedAt: 'x' }));
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+    expect(JSON.parse(fs.readFileSync(lockPath(), 'utf8')).pid).toBe(process.pid);
+  });
+
+  it('re-acquiring our own lock stays owner (idempotent across re-init)', () => {
+    expect(acquireSchedulerOwnership().owner).toBe(true);
+    expect(acquireSchedulerOwnership().owner).toBe(true);
+  });
+
+  it('release removes only our own lock', () => {
+    acquireSchedulerOwnership();
+    releaseSchedulerOwnership();
+    expect(fs.existsSync(lockPath())).toBe(false);
+    // A foreign lock is never removed by release.
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 1, startedAt: 'x' }));
+    releaseSchedulerOwnership();
+    expect(fs.existsSync(lockPath())).toBe(true);
+  });
+
+  it('a corrupt lock file is treated as stale, not fatal', () => {
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), 'not json {');
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+  });
+
+  it('pidAlive: own pid alive, absurd pid dead', () => {
+    expect(pidAlive(process.pid)).toBe(true);
+    expect(pidAlive(2 ** 30)).toBe(false);
+    expect(pidAlive(-5)).toBe(false);
+    expect(pidAlive(0)).toBe(false);
+  });
+});

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