claude-code-session-manager 0.39.4 → 0.40.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-XGsBHqYu.js"></script>
+    <script type="module" crossorigin src="./assets/index-oMNYp73N.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-DyLm7GM_.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-CR-WdMgm.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.4",
+  "version": "0.40.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",

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

@@ -161,8 +161,9 @@ can't load skills.
    - **Evolving chain (3-5 PRDs).** Use this shape when the request is naturally a sequence of
      stages that build on each other rather than independent units — e.g. scaffold → core
      behavior → edge-case/interaction hardening → integration wiring → UI validation pass. Each
-     PRD in the chain: gets the **next sequential `NN`** (never the same `NN` as the PRD it
-     depends on — same-`NN` means "can run in parallel," which a chain link cannot), and its
+     PRD in the chain: gets its own unique `NN` (numbers are strictly unique per project —
+     PRD 832, user decision 2026-07-31) plus a `dependsOn: [<previous-link-slug>]`
+     frontmatter line expressing the chain edge explicitly, and its
      `# Implementation notes` states in one line what the *previous* link actually delivered
      (file paths/functions it added, referencing its real landed state — not the plan for it,
      since PRDs 1..k-1 may have adjusted scope during execution) and what this link is expected
@@ -184,11 +185,11 @@ can't load skills.
    (`mcp__session-manager-scheduler__scheduler_create_prd`) over hand-writing the file. Its input
    (`title`, `cwd`, `estimateMinutes`, `goal`, `acceptanceCriteria[]`, `implementationNotes`,
    `outOfScope[]`) maps directly onto the sections below — pass them straight through. It
-   allocates the parallel-group `NN` atomically (no read-then-write race against another
-   concurrent `/develop`/`/process-feedback` invocation), derives and collision-checks the slug,
-   and embeds the standards pointer for you. Set `parallelGroup` explicitly only when this PRD
-   must share an existing sibling's `NN` (a logically independent PRD that can run in parallel
-   with one already queued); omit it to get the next free `NN` atomically.
+   allocates a strictly-unique `NN` atomically (no read-then-write race against another
+   concurrent `/develop`/`/process-feedback` invocation, never reused across the project — PRD
+   832), derives and collision-checks the slug, and embeds the standards pointer for you.
+   `parallelGroup` is DEPRECATED and ignored — express ordering with the `dependsOn` input
+   (slugs that must complete first); independent PRDs simply omit it and may run in parallel.
 
    **Fallback — only when the tool errors with "app not running" / admin API unreachable**
    (the session-manager Electron app must be running for this MCP tool to work; if it isn't,
@@ -200,9 +201,9 @@ can't load skills.
    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
-   independent sibling that can run in parallel; **next free `NN` = max+1** when this PRD
-   hard-depends on prior work or is unrelated to every existing group. This manual path has a
+   The last line is the current max within that project. Then: **always next free `NN` =
+   max+1** — never reuse a sibling's number (unique-per-project rule, PRD 832); express
+   ordering with `dependsOn: [<slug>]` frontmatter instead. This manual path has a
    small, accepted race (two concurrent authors could compute the same "next free" `NN`) —
    cosmetic (two unrelated groups end up sharing a number) rather than destructive, and only
    reachable when the atomic tool path above isn't available. Record each cross-PRD dependency
@@ -238,9 +239,9 @@ can't load skills.
    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
-   hard-depends on prior work). `<kebab-slug>` is a short, descriptive kebab-case identifier
+   **Filename rules.** `NN` is the PRD's unique per-project number (always next free =
+   max+1 per the `ls` command above; ordering via `dependsOn` frontmatter, never via shared
+   numbers). `<kebab-slug>` is a short, descriptive kebab-case identifier
    (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`), kept under 60 chars. Verify your
    chosen filename doesn't already exist before writing.
 

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

@@ -307,7 +307,7 @@ test('POST /admin/scheduler/create-prd rejects a title containing a newline (fro
   }
 });
 
-test('POST /admin/scheduler/create-prd with an explicit parallelGroup+slug that already exists on disk returns 409 and does not clobber the file', async () => {
+test('PRD 832: an explicit parallelGroup colliding with an existing file is ignored — a fresh unique NN is allocated and nothing is clobbered', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
   const { admin, port, token } = await startWithRemote(remote);
@@ -317,17 +317,18 @@ test('POST /admin/scheduler/create-prd with an explicit parallelGroup+slug that
       method: 'POST', path: '/admin/scheduler/create-prd', token,
       body: validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }),
     });
-    expect(res.status).toBe(409);
-    expect(res.json.ok).toBe(false);
+    expect(res.status).toBe(200);
+    // Allocator scans past the existing 777 — unique per project, never reused.
+    expect(res.json.nn).toBe(778);
+    expect(res.json.filename).toBe('778-my-explicit-slug.md');
     const stillThere = await fsp.readFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'utf8');
-    // existing PRD file must not be overwritten
     expect(stillThere).toBe('ORIGINAL CONTENT\n');
   } finally {
     await admin.stop();
   }
 });
 
-test('POST /admin/scheduler/create-prd honors an explicit slug + parallelGroup instead of deriving/allocating', async () => {
+test('PRD 832: explicit parallelGroup input is deprecated and ignored — NN always comes from the allocator', async () => {
   const prdsDir = await mkTmpPrdsDir();
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
   const { admin, port, token } = await startWithRemote(remote);
@@ -337,9 +338,9 @@ test('POST /admin/scheduler/create-prd honors an explicit slug + parallelGroup i
       body: validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }),
     });
     expect(res.status).toBe(200);
-    expect(res.json.nn).toBe(777);
-    expect(res.json.filename).toBe('777-my-explicit-slug.md');
-    expect(fs.existsSync(path.join(prdsDir, '777-my-explicit-slug.md'))).toBeTruthy();
+    expect(res.json.nn).toBe(1);
+    expect(res.json.filename).toBe('1-my-explicit-slug.md');
+    expect(fs.existsSync(path.join(prdsDir, '1-my-explicit-slug.md'))).toBeTruthy();
   } finally {
     await admin.stop();
   }
@@ -385,17 +386,55 @@ test('createPrd with a valid payload allocates a group, writes through remote.wr
   expect(written).toMatch(/# Goal/);
 });
 
-test('createPrd returns {ok:false, status:409} without clobbering an existing file at the same destination', async () => {
+test('createPrd returns {ok:false, status:409} without clobbering when the destination already exists', async () => {
   const prdsDir = await mkTmpPrdsDir();
+  // The existence guard survives PRD 832: whatever NN the allocator picks,
+  // a pre-existing file at that exact destination must 409, never clobber.
   const remote = makeFakeRemoteWithPrdsDir(prdsDir);
-  await fsp.writeFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'ORIGINAL CONTENT\n');
+  const realRead = remote.readPrd.bind(remote);
+  remote.readPrd = async (slug) => (slug.endsWith('my-explicit-slug') ? { ok: true, text: 'ORIGINAL' } : realRead(slug));
+  const writes = [];
+  const realWrite = remote.writePrd.bind(remote);
+  remote.writePrd = async (...a) => { writes.push(a[0]); return realWrite(...a); };
 
-  const result = await createPrd(validCreateBody({ slug: 'my-explicit-slug', parallelGroup: 777 }), remote);
+  const result = await createPrd(validCreateBody({ slug: 'my-explicit-slug' }), remote);
 
   expect(result.ok).toBe(false);
   expect(result.status).toBe(409);
-  const stillThere = await fsp.readFile(path.join(prdsDir, '777-my-explicit-slug.md'), 'utf8');
-  expect(stillThere).toBe('ORIGINAL CONTENT\n');
+  expect(writes).toEqual([]);
+});
+
+// ──────────────────────────────────────────── PRD 825: Epic PRD dir write grant + `~` cwd normalization
+
+test('validateWrite allows writes under <root>/session-manager-operations/scheduler/epics/<id>/prds/', async () => {
+  const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-scheduler-epics-'));
+  config.addAllowedRoot(root);
+  const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'epic-abc123', 'prds');
+  await fsp.mkdir(prdsDir, { recursive: true });
+  const filePath = path.join(prdsDir, '1-do-thing.md');
+
+  await config.writeTextAtomic(filePath, 'PRD body\n');
+
+  expect(fs.existsSync(filePath)).toBeTruthy();
+  expect(await fsp.readFile(filePath, 'utf8')).toBe('PRD body\n');
+});
+
+test('createPrd normalizes a `~`-prefixed cwd via expandHome before calling remote', async () => {
+  const receivedCwds = [];
+  const remote = {
+    async allocateParallelGroup(cwd) { receivedCwds.push(cwd); return 42; },
+    async readPrd(slug, cwd) { receivedCwds.push(cwd); return { ok: false }; },
+    async writePrd(slug, body, cwd) { receivedCwds.push(cwd); return { ok: true, bytesWritten: body.length }; },
+  };
+
+  const result = await createPrd(validCreateBody({ cwd: '~' }), remote);
+
+  expect(result.ok).toBe(true);
+  expect(receivedCwds.length).toBeGreaterThan(0);
+  for (const cwd of receivedCwds) {
+    expect(cwd.startsWith('~')).toBe(false);
+    expect(cwd).toBe(os.homedir());
+  }
 });
 
 test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the created PRD frontmatter', async () => {
@@ -405,10 +444,10 @@ test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the cr
   try {
     const res = await request(port, {
       method: 'POST', path: '/admin/scheduler/create-prd', token,
-      body: validCreateBody({ slug: 'from-a-ticket', parallelGroup: 888, sourcePromptId: 'ticket-xyz-789' }),
+      body: validCreateBody({ slug: 'from-a-ticket', sourcePromptId: 'ticket-xyz-789' }),
     });
     expect(res.status).toBe(200);
-    const written = fs.readFileSync(path.join(prdsDir, '888-from-a-ticket.md'), 'utf8');
+    const written = fs.readFileSync(path.join(prdsDir, `${res.json.nn}-from-a-ticket.md`), 'utf8');
     expect(written).toMatch(/sourcePromptId: ticket-xyz-789/);
   } finally {
     await admin.stop();

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

@@ -0,0 +1,118 @@
+/**
+ * prdSourcePromptIdBackfill.test.cjs — PRD 830: a PRD file's location under
+ * `.../scheduler/epics/<epicId>/prds/<slug>.md` already IS its Epic
+ * membership, so ingest should stamp `sourcePromptId = <epicId>` whenever
+ * frontmatter doesn't supply one — instead of leaving it null forever.
+ *
+ * Covers:
+ *   - deriveEpicIdFromPrdPath: pure path-shape extraction (prdLocations.cjs)
+ *   - parsePrdRaw: dir-derived stamping + frontmatter-wins precedence
+ *   - reconcileSourcePromptId: pending-only backfill (scheduler.cjs)
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdSourcePromptIdBackfill.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { deriveEpicIdFromPrdPath, resolveEpicPrdWriteDir } = require('../lib/prdLocations.cjs');
+const { parsePrdRaw, _resetCache } = require('../scheduler/prdParser.cjs');
+const { reconcileSourcePromptId } = require('../scheduler.cjs');
+
+async function mkProjectCwd() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-backfill-'));
+}
+
+// ---------- deriveEpicIdFromPrdPath ----------
+
+test('deriveEpicIdFromPrdPath extracts the epic id from a well-formed epic PRD path', async () => {
+  const cwd = await mkProjectCwd();
+  const epicId = 'some-epic-abc123';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '900-example.md');
+  expect(deriveEpicIdFromPrdPath(filePath)).toBe(epicId);
+});
+
+test('deriveEpicIdFromPrdPath returns null for the retired flat prds/ layout', () => {
+  const filePath = '/home/user/Projects/foo/session-manager-operations/scheduler/prds/900-example.md';
+  expect(deriveEpicIdFromPrdPath(filePath)).toBe(null);
+});
+
+test('deriveEpicIdFromPrdPath returns null for an unrelated path', () => {
+  expect(deriveEpicIdFromPrdPath('/tmp/whatever/900-example.md')).toBe(null);
+  expect(deriveEpicIdFromPrdPath(null)).toBe(null);
+});
+
+// ---------- parsePrdRaw: dir-derived stamping + frontmatter-wins ----------
+
+test('parsePrdRaw derives sourcePromptId from the parent epic dir when frontmatter omits it', async () => {
+  _resetCache();
+  const cwd = await mkProjectCwd();
+  const epicId = 'derive-me-epic-def456';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '901-hand-authored.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Hand-authored, no sourcePromptId',
+    `cwd: ${cwd}`,
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe(epicId);
+});
+
+test('parsePrdRaw: explicit frontmatter sourcePromptId wins over the dir-derived epic id', async () => {
+  _resetCache();
+  const cwd = await mkProjectCwd();
+  const epicId = 'dir-epic-ghi789';
+  const dir = resolveEpicPrdWriteDir(cwd, epicId);
+  await fsp.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, '902-explicit.md');
+  await fsp.writeFile(filePath, [
+    '---',
+    'title: Explicit sourcePromptId',
+    `cwd: ${cwd}`,
+    'sourcePromptId: ticket-explicit-999',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(filePath);
+  expect(parsed.sourcePromptId).toBe('ticket-explicit-999');
+});
+
+// ---------- reconcileSourcePromptId: pending-only backfill ----------
+
+test('reconcileSourcePromptId backfills a pending job whose sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'pending', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe('epic-abc');
+});
+
+test('reconcileSourcePromptId leaves a running job untouched even if its sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'running', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe(null);
+});
+
+test('reconcileSourcePromptId leaves a completed job untouched even if its sourcePromptId is null', () => {
+  const job = { slug: 'x', status: 'completed', sourcePromptId: null };
+  expect(reconcileSourcePromptId(job, 'epic-abc')).toBe(null);
+});
+
+test('reconcileSourcePromptId keeps a pending job\'s existing value if the fresh parse yields null', () => {
+  const job = { slug: 'x', status: 'pending', sourcePromptId: 'already-set' };
+  expect(reconcileSourcePromptId(job, null)).toBe('already-set');
+});

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/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/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');
@@ -1090,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 } });
   });
@@ -1199,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/epicMint.cjs

@@ -141,4 +141,4 @@ function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
   return true;
 }
 
-module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath };
+module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath, readActiveIndex };