claude-code-session-manager 0.39.4 → 0.40.0

package/src/main/lib/instanceLock.cjs

@@ -0,0 +1,100 @@
+/**
+ * instanceLock.cjs — machine-wide scheduler-ownership lock (PRD 834).
+ *
+ * Electron's app.requestSingleInstanceLock() is keyed by userData path, so an
+ * instance launched with a different identity bypasses it entirely — live
+ * incident 2026-07-31: a Playwright `_electron.launch(src/main/index.cjs)`
+ * runs as the "Electron" default app (userData ~/.config/Electron), won its
+ * own Electron lock, ran full scheduler boot reconciliation against the same
+ * per-project queue state as the production instance, SIGTERM'd the
+ * production instance's live job as an "orphan", and overwrote
+ * admin-api.json. Dev/e2e launches skip the Electron lock on purpose, with
+ * the same effect.
+ *
+ * This lock is identity-independent: a pid file at a FIXED path under
+ * ~/.claude/session-manager/. Exactly one process — whichever wins the
+ * atomic 'wx' create — owns scheduler mutation (boot reconciliation, queue
+ * ticking, feedback sweep, supervisor, heartbeat) and the admin API. Every
+ * other instance runs scheduler-passive: UI reads still work (IPC read
+ * handlers register unconditionally), but nothing that mutates queue state
+ * or kills processes runs.
+ *
+ * Deliberately plain sync fs (no config.cjs writeJson): this runs before
+ * app.whenReady and must not await; the file is tiny and single-writer.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Env override is for unit tests only (isolates the lock from the real
+// ~/.claude of the machine running the suite).
+function lockPath() {
+  return process.env.SM_SCHEDULER_LOCK_PATH
+    || path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-owner.lock');
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = alive but not ours; ESRCH = dead.
+    return e && e.code === 'EPERM';
+  }
+}
+
+function readLock() {
+  try {
+    const raw = fs.readFileSync(lockPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return Number.isInteger(parsed?.pid) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLockExclusive() {
+  const body = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+  // 'wx' = atomic create-or-fail — two racing instances cannot both win.
+  fs.writeFileSync(lockPath(), body, { flag: 'wx', mode: 0o600 });
+}
+
+/**
+ * Try to become the machine's scheduler owner.
+ * Returns { owner: true } or { owner: false, holderPid } — never throws.
+ */
+function acquireSchedulerOwnership() {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const existing = readLock();
+    if (existing && existing.pid !== process.pid && pidAlive(existing.pid)) {
+      return { owner: false, holderPid: existing.pid };
+    }
+    // Missing, unreadable, our own, or stale (holder pid dead) — take it.
+    try {
+      if (existing || fs.existsSync(lockPath())) fs.unlinkSync(lockPath());
+    } catch { /* raced with another breaker — retry loop below settles it */ }
+    try {
+      writeLockExclusive();
+      return { owner: true };
+    } catch {
+      // Lost the create race — loop once more to report the winner's pid.
+    }
+  }
+  const winner = readLock();
+  return { owner: false, holderPid: winner?.pid };
+}
+
+/** Best-effort release on clean shutdown; stale-pid detection covers crashes. */
+function releaseSchedulerOwnership() {
+  try {
+    const existing = readLock();
+    if (existing && existing.pid === process.pid) fs.unlinkSync(lockPath());
+  } catch { /* nothing to release */ }
+}
+
+module.exports = { acquireSchedulerOwnership, releaseSchedulerOwnership, pidAlive, lockPath };

package/src/main/lib/prdCreate.cjs

@@ -48,7 +48,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, dependsOn,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -64,6 +64,8 @@ function buildPrdBody(input) {
   // Optional, additive: the user-selected Feature/Bug tag (PRD 774) carried
   // through from the originating PromptTicket — deterministic, never LLM-classified.
   if (tag) fmLines.push(`tag: ${tag}`);
+  // Explicit ordering (PRD 832): replaces the retired shared-NN convention.
+  if (dependsOn && dependsOn.length) fmLines.push(`dependsOn: [${dependsOn.join(', ')}]`);
   fmLines.push('---', '');
 
   const acLines = acceptanceCriteria.map((line) => `- [ ] ${line}`).join('\n');
@@ -108,21 +110,32 @@ async function createPrd(input, remote) {
   // through config.cjs's validatePath (allowedRoots = home dir) —
   // same boundary every other fs-touching IPC handler uses — never a
   // bespoke check here.
+  // Normalize a `~`-prefixed cwd BEFORE it reaches allocateParallelGroup/
+  // readPrd/writePrd — those pass cwd through to safeSlugPathIn-adjacent path
+  // joins that treat it as a literal path segment, so an unexpanded `~/...`
+  // fails downstream as a bare "invalid slug" instead of a clear cwd error.
+  const cwd = expandHome(input.cwd);
   try {
-    config.validatePath(expandHome(input.cwd));
+    config.validatePath(cwd);
   } catch (e) {
     return { ok: false, status: 400, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` };
   }
+  input = { ...input, cwd };
 
   const slug = input.slug || deriveSlugFromTitle(input.title);
   if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
     return { ok: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
   }
 
-  // NN allocation is delegated to allocateParallelGroup() (PRD 548) via
-  // the injected remote — never re-derived here — unless the caller
-  // opted into an existing group explicitly.
-  const nn = input.parallelGroup ?? await remote.allocateParallelGroup(input.cwd);
+  // NN allocation is delegated to allocateParallelGroup() (PRD 548) via the
+  // injected remote — never re-derived here. `parallelGroup` input is
+  // DEPRECATED (PRD 832, user decision 2026-07-31): numbers are strictly
+  // unique per project; ordering is expressed via `dependsOn` frontmatter,
+  // never by sharing a number. An explicit parallelGroup is ignored.
+  if (input.parallelGroup != null) {
+    console.warn(`[prdCreate] parallelGroup input is deprecated and ignored (got ${input.parallelGroup}) — numbers are unique per project; use dependsOn for ordering`);
+  }
+  const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 
   // An explicit `parallelGroup` bypasses allocateParallelGroup()'s

package/src/main/lib/prdLocations.cjs

@@ -125,12 +125,40 @@ function resolvePrdsDirs(maxAgeMin, opts) {
   return dirs;
 }
 
+/**
+ * deriveEpicIdFromPrdPath(filePath) → epicId | null
+ *
+ * A PRD's file location already IS its Epic membership (epic id == parent
+ * dir name, 1:1 by design). Given an absolute PRD file path, walk back up
+ * `EPICS_SUBPATH.length` segments from the epics root implied by the path's
+ * own `.../prds/<slug>.md` shape and confirm it round-trips through
+ * `resolveEpicsRoot` — i.e. the path really is
+ * `<projectCwd>/session-manager-operations/scheduler/epics/<epicId>/prds/<slug>.md`,
+ * not some other `prds/` dir (e.g. the retired flat layout). Returns null for
+ * any path that doesn't match this shape.
+ */
+function deriveEpicIdFromPrdPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return null;
+  const prdsDir = path.dirname(filePath);
+  if (path.basename(prdsDir) !== 'prds') return null;
+  const epicDir = path.dirname(prdsDir);
+  const epicId = path.basename(epicDir);
+  if (!epicId || epicId === '.' || epicId === path.sep) return null;
+  let projectCwd = path.dirname(epicDir); // epicsRoot (.../scheduler/epics)
+  for (let i = 0; i < EPICS_SUBPATH.length; i++) projectCwd = path.dirname(projectCwd);
+  let epicsRoot;
+  try { epicsRoot = resolveEpicsRoot(projectCwd); } catch { return null; }
+  if (path.join(epicsRoot, epicId, 'prds') !== prdsDir) return null;
+  return epicId;
+}
+
 module.exports = {
   resolvePrdWriteDir,
   resolvePrdsDirs,
   resolveEpicsRoot,
   resolveEpicPrdWriteDir,
   listEpicPrdDirs,
+  deriveEpicIdFromPrdPath,
   PRD_SUBPATH,
   EPICS_SUBPATH,
 };

package/src/main/lib/schedulerBatch.cjs

@@ -38,12 +38,44 @@ const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager
  *   human-readable reason text that would otherwise only reach console.log.
  */
 function pickForProject(projectJobs, runningSlugsInProject, slots) {
-  const pending = projectJobs.filter(
+  const projectCwd = (projectJobs.find((j) => j.cwd) || {}).cwd || DEFAULT_PROJECT_CWD;
+
+  // Explicit dependsOn eligibility (PRD 832). A dep slug is BLOCKING while a
+  // queue row for it exists in a non-completed state; a slug with no row is
+  // treated as already done (completed rows are retired to history shards,
+  // so absence is the normal end-state of a finished dep). A FAILED dep
+  // holds the dependent with an explicit reason, mirroring the failure gate.
+  // Legacy jobs without dependsOn keep the shared-NN group semantics below
+  // unchanged (lowest-number-first waves), so an in-flight mixed queue keeps
+  // its order without migration.
+  const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
+  const blockingDep = (j) => (j.dependsOn ?? []).find((slug) => {
+    const dep = rowBySlug.get(slug);
+    return dep && dep.status !== 'completed';
+  });
+
+  const allPending = projectJobs.filter(
     (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
   );
-  if (pending.length === 0) return { batch: [], reason: null };
-
-  const projectCwd = (projectJobs.find((j) => j.cwd) || {}).cwd || DEFAULT_PROJECT_CWD;
+  if (allPending.length === 0) return { batch: [], reason: null };
+
+  const pending = [];
+  const heldByFailedDep = [];
+  for (const j of allPending) {
+    const dep = blockingDep(j);
+    if (!dep) { pending.push(j); continue; }
+    if (rowBySlug.get(dep)?.status === 'failed') heldByFailedDep.push({ job: j, dep });
+    // running/pending/needs_review dep — simply not eligible this tick.
+  }
+  if (pending.length === 0) {
+    if (heldByFailedDep.length > 0) {
+      const detail = heldByFailedDep.map(({ job, dep }) => `${job.slug} <- ${dep}`).join(', ');
+      const reason = `[scheduler] depends-gate [${projectCwd}]: holding ${heldByFailedDep.length} job(s) behind failed dependencies [${detail}]. Reset or archive the dep to unblock.`;
+      console.log(reason);
+      return { batch: [], reason };
+    }
+    return { batch: [], reason: null };
+  }
 
   // Lowest pending group (computed up-front for the failure-gate check).
   const lowestPendingGroup = pending.reduce(

package/src/main/pty.cjs

@@ -231,6 +231,14 @@ class PtyManager {
   killAll() {
     for (const tabId of [...this.sessions.keys()]) this.kill(tabId);
   }
+
+  /** Subset of `ids` that currently have a live PTY in the sessions map.
+   *  Lets the Epics workspace reconcile Terminal-mode attachment after a
+   *  renderer reload (the PTY survives; the renderer's in-memory attachment
+   *  record does not — PRD 833 C1). */
+  aliveOf(ids) {
+    return ids.filter((id) => this.sessions.has(id));
+  }
 }
 
 const manager = new PtyManager();
@@ -244,6 +252,7 @@ function registerPtyHandlers() {
     if (typeof tabId !== 'string') return;
     manager.kill(tabId);
   });
+  ipcMain.handle('pty:alive', v(s.ptyAlive, ({ tabIds }) => manager.aliveOf(tabIds)));
 }
 
 module.exports = { manager, registerPtyHandlers };

package/src/main/scheduler/prdParser.cjs

@@ -18,6 +18,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const { splitFrontmatter } = require('../lib/prdFrontmatter.cjs');
+const { deriveEpicIdFromPrdPath } = require('../lib/prdLocations.cjs');
 
 /**
  * Expand a PRD `cwd` value to an absolute path.
@@ -66,17 +67,37 @@ async function parsePrdRaw(filePath) {
     parallelGroup: (fm.parallelGroup ? Number(fm.parallelGroup) || null : null) ?? groupFromName ?? 99,
     // Optional traceability back to the PromptTicket.id (PRD 748) that was
     // classified 'develop' and spawned this PRD (PRD 749). Additive — absent
-    // on every PRD authored before this field existed.
-    sourcePromptId: fm.sourcePromptId || null,
+    // on every PRD authored before this field existed. When frontmatter
+    // omits it, fall back to the owning Epic dir name (PRD 830) — a PRD's
+    // file location already IS its Epic membership, so hand-authored PRDs
+    // dropped straight into an Epic's prds/ dir still get real linkage
+    // instead of null.
+    sourcePromptId: fm.sourcePromptId || deriveEpicIdFromPrdPath(filePath) || null,
     // Optional traceability back to the chat tab that queued this PRD (PRD
     // 761) — read back at job completion to route a status prompt via
     // enqueueExternalPrompt (PRD 753). Additive — absent on every PRD
     // authored before this field existed.
     sourceTabId: fm.sourceTabId || null,
+    // Explicit cross-PRD ordering (PRD 832): `dependsOn: [<slug>, <slug>]`
+    // or a comma-separated string. Replaces the retired shared-NN-means-
+    // parallel convention — a job is eligible only once every listed slug's
+    // queue row is completed (a slug with no row is treated as already
+    // done/archived, matching retireCompletedSlugs semantics).
+    dependsOn: parseDependsOn(fm.dependsOn),
     body: body.trim(),
   };
 }
 
+/** `[a, b]` / `a, b` / `a` → ['a','b']; anything else → []. */
+function parseDependsOn(raw) {
+  if (!raw || typeof raw !== 'string') return [];
+  const inner = raw.trim().replace(/^\[/, '').replace(/\]$/, '');
+  return inner
+    .split(',')
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+    .filter((s) => /^[A-Za-z0-9][\w.-]*$/.test(s));
+}
+
 /**
  * List `.md` PRD files under the given dir. Caches the result keyed by the
  * directory mtime so repeated reconcile() calls don't re-stat every entry.
@@ -257,11 +278,14 @@ async function maxParallelGroupInUse(prdsDir) {
  * number) and never wedges future callers, since each attempt only needs
  * the marker for its OWN candidate to not already exist.
  */
-async function allocateParallelGroup(prdsDir) {
+async function allocateParallelGroup(prdsDir, { extraFloor = 0 } = {}) {
   await fsp.mkdir(prdsDir, { recursive: true });
   const scanMax = await maxParallelGroupInUse(prdsDir);
   const highWater = await readHighWaterMark(prdsDir);
-  const floor = Math.max(scanMax, highWater);
+  // extraFloor (PRD 832): the caller's max across OTHER dirs sharing the
+  // project's number space (epic prds/ dirs, prds-archived) — numbers are
+  // unique per project, never merely per directory.
+  const floor = Math.max(scanMax, highWater, extraFloor);
   let candidate = floor + 1;
   for (let attempt = 0; attempt < MAX_RESERVE_ATTEMPTS; attempt += 1) {
     const markerPath = path.join(prdsDir, `.reserved-${candidate}`);

package/src/main/scheduler.cjs

@@ -86,7 +86,25 @@ const queueOps = require('./queueOps.cjs');
 // home-dir layout.
 const { sweep: sweepFeedback } = require('../../scripts/lib/watchdogHelpers.cjs');
 const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs } = require('./lib/prdLocations.cjs');
-const { ensureEpic, appendPrdCreatedEvent } = require('./lib/epicMint.cjs');
+const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+
+// ---------- origin session resolution (PRD 832) ----------
+// An Epic IS a tagged claude session — job rows carry the originating
+// claudeSessionId alongside sourcePromptId so every PRD stays traceable to
+// the session that spawned it. active-index.json is tiny; a short TTL cache
+// keeps reconcile (every 60s, N jobs) at one read per project per pass.
+const originIndexCache = new Map(); // cwd -> { at, sessions }
+const ORIGIN_CACHE_TTL_MS = 30_000;
+function resolveOriginSessionId(cwd, epicId) {
+  if (!cwd || !epicId) return null;
+  let entry = originIndexCache.get(cwd);
+  if (!entry || Date.now() - entry.at > ORIGIN_CACHE_TTL_MS) {
+    entry = { at: Date.now(), sessions: readActiveIndex(cwd).sessions };
+    originIndexCache.set(cwd, entry);
+  }
+  const session = entry.sessions[epicId];
+  return session && typeof session.claudeSessionId === 'string' ? session.claudeSessionId : null;
+}
 const sessionSlots = require('./lib/sessionSlots.cjs');
 const queueStore = require('./lib/queueStore.cjs');
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
@@ -911,7 +929,23 @@ async function listPrdFiles() {
 async function allocateParallelGroup(cwd) {
   const dir = prdDirForCwd(cwd);
   await fsp.mkdir(dir, { recursive: true });
-  return prdParser.allocateParallelGroup(dir);
+  // PRD 832: numbers are unique across the WHOLE project, not just the
+  // allocator's bookkeeping dir — scan every Epic prds/ dir plus the
+  // archive so a number used anywhere (even by a hand-authored or archived
+  // PRD) is never reissued. The reservation markers + high-water sidecar
+  // stay in `dir`; the cross-dir max only raises the floor.
+  const targetCwd = cwd || DEFAULT_PROJECT_CWD;
+  const extraDirs = [
+    ...listEpicPrdDirs(targetCwd),
+    path.join(prdDirForCwd(targetCwd), '..', 'prds-archived'),
+  ];
+  let extraFloor = 0;
+  for (const d of extraDirs) {
+    try {
+      extraFloor = Math.max(extraFloor, await prdParser.maxParallelGroupInUse(d));
+    } catch { /* missing dir — nothing allocated there */ }
+  }
+  return prdParser.allocateParallelGroup(dir, { extraFloor });
 }
 
 /**
@@ -991,6 +1025,20 @@ function validatePromptForSpawn(body, srcLabel) {
 
 // ---------- queue reconciliation ----------
 
+/**
+ * sourcePromptId backfill (PRD 830) is pending-only: a pending row always
+ * takes the freshly-parsed value (explicit frontmatter, or the dir-derived
+ * epic id parsePrd falls back to when frontmatter has none) since it hasn't
+ * started executing yet. A running/completed row's sourcePromptId is left
+ * exactly as it was minted at dispatch time — reconcile must not rewrite
+ * linkage on work already in flight or finished.
+ */
+function reconcileSourcePromptId(job, parsedSourcePromptId) {
+  return job.status === 'pending'
+    ? (parsedSourcePromptId ?? job.sourcePromptId ?? null)
+    : job.sourcePromptId;
+}
+
 /**
  * Walk prds/, ensure every .md has a queue entry. Drop entries whose .md
  * is gone. Refresh title/cwd/parallelGroup from disk every reconcile so
@@ -1033,6 +1081,16 @@ async function reconcile(state) {
       // or mid-move. "I can't see it" is not "the user deleted it", so the
       // row survives — worst case it re-resolves on the next pass.
       if (job.status === 'pending' || job.status === 'running') {
+        // Exception: a PENDING row whose PRD has an archived twin was
+        // retired on purpose (work landed by other means — e.g. implemented
+        // inline — and the source .md moved to prds-archived/). Keeping it
+        // would show a phantom "scheduled" job forever; firing it would just
+        // hit executeJob's archived-twin skip anyway. Running rows are left
+        // alone — the reaper owns their lifecycle.
+        if (job.status === 'pending' && (await archivedTwinExists(job))) {
+          console.log(`[scheduler] reconcile: retiring pending job ${job.slug} — PRD already archived (work landed elsewhere)`);
+          continue;
+        }
         seen.add(job.slug);
         next.push({ ...job });
         console.warn(`[scheduler] reconcile: keeping ${job.status} job ${job.slug} — PRD source not visible in any candidate dir`);
@@ -1046,8 +1104,11 @@ async function reconcile(state) {
       cwd: p.cwd,
       parallelGroup: p.parallelGroup,
       estimateMinutes: p.estimateMinutes,
-      sourcePromptId: p.sourcePromptId,
+      sourcePromptId: reconcileSourcePromptId(job, p.sourcePromptId),
       sourceTabId: p.sourceTabId,
+      dependsOn: p.dependsOn,
+      originSessionId: job.originSessionId
+        ?? resolveOriginSessionId(p.cwd, reconcileSourcePromptId(job, p.sourcePromptId)),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
     });
   }
@@ -1106,6 +1167,8 @@ async function reconcile(state) {
       estimateMinutes: p.estimateMinutes,
       sourcePromptId: p.sourcePromptId,
       sourceTabId: p.sourceTabId,
+      dependsOn: p.dependsOn,
+      originSessionId: resolveOriginSessionId(p.cwd, p.sourcePromptId),
       bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
       status: 'pending',
       runId: null,
@@ -4026,6 +4089,8 @@ const remote = {
   async writePrd(slug, body, cwd) {
     let dir;
     let epicTrace = null;
+    let epicCreated = false;
+    let epicId = null;
     if (cwd) {
       // Edit-in-place if this slug already lives anywhere under this project
       // (legacy flat dir or any Epic's prds/); otherwise this is a CREATE,
@@ -4047,6 +4112,8 @@ const remote = {
           });
           dir = epic.prdDir;
           epicTrace = epic.epicId;
+          epicCreated = epic.created === true;
+          epicId = epic.epicId;
         } catch (e) {
           // Epic mint must never block a PRD write — fall back to the
           // legacy flat dir and log loudly.
@@ -4059,8 +4126,27 @@ const remote = {
       dir = (await findPrdDir(slug)) ?? PRDS_DIR;
       if (dir === PRDS_DIR) ensureDirs();
     }
+
+    // PRD 825: if this call minted a brand-new Epic (ensureEpic's `created`)
+    // and the write below never lands, don't strand an empty Epic dir —
+    // best-effort remove `<epic>/prds` then `<epic>` itself, only when empty.
+    const cleanupEmptyMintedEpic = async () => {
+      if (!epicCreated || !epicId) return;
+      try {
+        const entries = await fsp.readdir(dir);
+        if (entries.length > 0) return;
+        await fsp.rmdir(dir);
+        const epicRootDir = path.dirname(dir);
+        const epicRootEntries = await fsp.readdir(epicRootDir);
+        if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
+      } catch { /* best-effort only */ }
+    };
+
     const resolved = safeSlugPathIn(dir, slug);
-    if (!resolved) return { ok: false, error: 'invalid slug' };
+    if (!resolved) {
+      await cleanupEmptyMintedEpic();
+      return { ok: false, error: 'invalid slug' };
+    }
     try {
       // Symlink defense, matching readPrd/readLog: safeSlugPathIn is lexical
       // and does NOT resolve symlinks, so a rogue job could plant a PRDs-dir
@@ -4070,10 +4156,12 @@ const remote = {
       // symlink.
       const realParent = await fsp.realpath(path.dirname(resolved));
       if (realParent !== dir && !realParent.startsWith(dir + path.sep)) {
+        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       const existing = await fsp.lstat(resolved).catch(() => null);
       if (existing && existing.isSymbolicLink()) {
+        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       await config.writeTextAtomic(resolved, body);
@@ -4084,6 +4172,7 @@ const remote = {
       }
       return { ok: true, bytesWritten: stat.size };
     } catch (e) {
+      await cleanupEmptyMintedEpic();
       return { ok: false, error: e?.message ?? 'write failed' };
     }
   },
@@ -4178,4 +4267,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, feedbackSweepDue, FEEDBACK_SWEEP_TICK_INTERVAL, sweepFeedback, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, candidatePrdsDirs, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields };

package/src/main/templates/PRD_AUTHORING.md

@@ -392,17 +392,21 @@ the user may or may not have open.
 
 ### Fallback: writing the PRD file directly
 
-When the app is not running, write `<NN>-<slug>.md` by hand into the target repo's own
-`<cwd>/session-manager-operations/scheduler/prds/` following the frontmatter rules in §6 and the
+When the app is not running, first mint (or join) an Epic — `node <session-manager-repo>/scripts/mint-epic.cjs <cwd> "<goal>" [feature|bug|discussion]`; its last stdout line is the prds dir — then write `<NN>-<slug>.md` by hand into that
+`<cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds/` dir (the flat `scheduler/prds/` is RETIRED and auto-archived unexecuted at boot), add `sourcePromptId: <epic-id>` to the frontmatter so the job keeps its Epic linkage, following the frontmatter rules in §6 and the
 body conventions the rest of this guide describes (`# Goal`, `# Acceptance criteria`,
 `# Implementation notes`, `## Engineering standards` inlined verbatim — see `/develop`'s output
 for the exact shape). **Trade-off:** this path has no atomic `NN` allocation. The tool's
 `allocateParallelGroup()` (PRD 548) exists specifically to close a race where two writers pick
 the same `NN` at once; a hand-written file bypasses that reservation entirely, so if another
 writer (a human, `/develop`, or another automation) picks the same `NN` around the same time, one
-file silently shadows or is shadowed by the other's parallel-group slot. Pick an `NN` by scanning
-the existing prds directory for the current max and incrementing, and treat a collision as
-possible, not merely theoretical.
+file silently shadows or is shadowed by the other's number. Pick an `NN` by scanning ALL of the
+project's prds dirs (`scheduler/epics/*/prds/` and `prds-archived/`) for the current max and
+incrementing, and treat a collision as possible, not merely theoretical. NN is strictly unique
+per project (PRD 832) — NEVER reuse an existing number to signal "runs in parallel"; that
+convention is retired. Express ordering with `dependsOn: [<slug>, ...]` frontmatter (the job is
+eligible once every listed slug's queue row is completed); independent PRDs omit it and the
+scheduler may run them concurrently.
 
 ### Ownership boundary
 

package/src/preload/api.d.ts

@@ -398,16 +398,22 @@ export interface ScheduleJob {
    */
   verifierVerdict?: string;
   /** Per-job values carried in queue.json for dependency checking. */
+  /** Explicit cross-PRD ordering (PRD 832): slugs that must complete before
+   *  this job is eligible. Replaces the retired shared-NN-parallel convention. */
   dependsOn?: string[];
+  /** The originating claude session — the Epic's claudeSessionId, resolved
+   *  from active-index.json at ingest (PRD 832). An Epic IS a tagged session. */
+  originSessionId?: string | null;
   /** Originating tab id (PRD frontmatter `sourceTabId`), refreshed from the
    *  PRD file on every reconcile. When the PRD was authored from inside a
    *  PromptSessionConversation, this equals that PromptSession's own id
    *  (its chat key) — lets the Scheduler UI trace a job back to the
    *  PromptSession that spawned it. */
   sourceTabId?: string | null;
-  /** Originating prompt id (PRD frontmatter `sourcePromptId`) — the chain-root
-   *  PromptTicket id this PRD was dispatched from. Kept alongside `sourceTabId`
-   *  for referential tracing even when the tab/session no longer resolves. */
+  /** Originating prompt id (PRD frontmatter `sourcePromptId`) — the
+   *  PromptSession (Epic) id this PRD was dispatched from. Kept alongside
+   *  `sourceTabId` for referential tracing even when the tab/session no
+   *  longer resolves. */
   sourcePromptId?: string | null;
 }
 
@@ -450,6 +456,9 @@ export interface PrdListItem {
   cwd: string;
   estimateMinutes: number | null;
   mtimeMs: number;
+  /** PRD frontmatter `sourcePromptId` — the PromptSession (Epic) id this PRD
+   *  was dispatched from, if any. */
+  sourcePromptId?: string | null;
 }
 
 export interface SupervisorConfig {
@@ -1092,6 +1101,10 @@ export interface SessionManagerAPI {
     write: (payload: { tabId: string; data: string }) => void;
     resize: (payload: { tabId: string; cols: number; rows: number }) => void;
     kill: (tabId: string) => void;
+    /** Subset of `tabIds` (session keys) that currently have a live PTY —
+     *  used by the Epics workspace to reconcile Terminal-mode attachment
+     *  after a renderer reload (PRD 833 C1). */
+    alive: (tabIds: string[]) => Promise<string[]>;
     onData: (tabId: string, handler: (data: string) => void) => () => void;
     onExit: (tabId: string, handler: (info: PtyExit) => void) => () => void;
     onWriteError: (handler: (ev: WriteErrorEvent) => void) => () => void;

package/src/preload/index.cjs

@@ -36,6 +36,7 @@ contextBridge.exposeInMainWorld('api', {
     write: (payload) => ipcRenderer.send('pty:write', payload),
     resize: (payload) => ipcRenderer.send('pty:resize', payload),
     kill: (tabId) => ipcRenderer.send('pty:kill', tabId),
+    alive: (tabIds) => ipcRenderer.invoke('pty:alive', { tabIds }),
     onData: (tabId, handler) => {
       const channel = `pty:data:${tabId}`;
       const listener = (_e, data) => handler(data);