claude-code-session-manager 0.58.0 → 0.59.0

package/src/main/lib/prdMigration.cjs

@@ -18,6 +18,7 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
+const { projectQueuePath } = require('./queueStore.cjs');
 const { expandHome } = require('./expandHome.cjs');
 
 /**
@@ -95,22 +96,92 @@ async function migratePrds(legacyPrdsDir) {
  * Name collisions in prds-archived/ get a `-legacy-<n>` suffix, never an
  * overwrite. Idempotent: an emptied flat dir is a no-op readdir.
  *
- * Returns { moved, failed: [{ file, reason }] }.
+ * LIVE JOBS ARE NEVER ARCHIVED (PRD 992). The scheduler still scans this flat
+ * dir as a PRD *source* (prdLocations.cjs's resolvePrdsDirs, "scan sources
+ * alongside the legacy flat dir"), so a file sitting here can legitimately
+ * have a pending/running job. Archiving it out from under that job strands the
+ * queue row with no resolvable source. Observed live 2026-08-02:
+ * `980-fix-chat-typed-event-renderers.md` sat in this dir with status
+ * `running` — a restart in that window would have moved its source mid-run.
+ * Such files are left in place and reported as `skipped`, mirroring how the
+ * sibling migratePrds() reports `unresolved` rather than dropping anything.
+ *
+ * Returns { moved, failed: [{ file, reason }], skipped: [{ file, reason }] }.
+ */
+
+/** Job statuses that mean "this PRD's source must survive". `needs_review` is
+ *  live on purpose: it is awaiting human action and will be re-read. */
+const LIVE_JOB_STATUSES = new Set(['pending', 'running', 'needs_review', 'investigating']);
+
+/**
+ * Slugs with a live job in this project's own queue shard.
+ *
+ * Returns null when liveness cannot be determined (unreadable/unparseable
+ * queue.json) — the caller then FAILS CLOSED and archives nothing, since it
+ * cannot prove a file is safe to move. A merely ABSENT queue.json is not an
+ * error: a project with no scheduler state has no jobs, so an empty set is
+ * the correct answer and consolidation proceeds normally.
  */
-async function consolidateFlatPrds(cwd) {
+async function liveSlugsForCwd(cwd) {
+  let raw;
+  try {
+    raw = await fsp.readFile(projectQueuePath(cwd), 'utf8');
+  } catch (e) {
+    if (e?.code === 'ENOENT') return new Set(); // fresh project — nothing queued
+    return null; // unreadable — caller fails closed
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null; // corrupt — caller fails closed
+  }
+  const jobs = Array.isArray(parsed?.jobs) ? parsed.jobs : [];
+  const live = new Set();
+  for (const job of jobs) {
+    if (job && typeof job.slug === 'string' && LIVE_JOB_STATUSES.has(job.status)) {
+      live.add(job.slug);
+    }
+  }
+  return live;
+}
+
+/** A queue job's slug is its PRD filename minus the `.md` suffix. */
+function slugForPrdFile(name) {
+  return name.slice(0, -3);
+}
+
+async function consolidateFlatPrds(cwd, opts = {}) {
   const flatDir = resolvePrdWriteDir(cwd);
   const archiveDir = path.join(path.dirname(flatDir), 'prds-archived');
   let entries;
   try {
     entries = await fsp.readdir(flatDir);
   } catch {
-    return { moved: 0, failed: [] };
+    return { moved: 0, failed: [], skipped: [] };
   }
 
+  const liveSlugs = opts.liveSlugs !== undefined ? opts.liveSlugs : await liveSlugsForCwd(cwd);
+
   let moved = 0;
   const failed = [];
+  const skipped = [];
+
+  // Fail closed: liveness unknown means every file might belong to a live job.
+  if (liveSlugs === null) {
+    for (const name of entries) {
+      if (!name.endsWith('.md') || name.startsWith('.')) continue;
+      skipped.push({ file: name, reason: 'queue state unreadable — cannot prove no live job' });
+    }
+    return { moved: 0, failed, skipped };
+  }
+
   for (const name of entries) {
     if (!name.endsWith('.md') || name.startsWith('.')) continue;
+    if (liveSlugs.has(slugForPrdFile(name))) {
+      skipped.push({ file: name, reason: 'live queue job — source must survive' });
+      continue;
+    }
     const src = path.join(flatDir, name);
     try {
       await fsp.mkdir(archiveDir, { recursive: true });
@@ -125,7 +196,7 @@ async function consolidateFlatPrds(cwd) {
       failed.push({ file: name, reason: e?.message ?? 'move failed' });
     }
   }
-  return { moved, failed };
+  return { moved, failed, skipped };
 }
 
-module.exports = { migratePrds, consolidateFlatPrds };
+module.exports = { migratePrds, consolidateFlatPrds, LIVE_JOB_STATUSES };

package/src/main/lib/promptSessionSchema.cjs

@@ -38,6 +38,17 @@ const EpicSourceSchema = z.object({
   sourceTabId: z.string().optional(),
 });
 
+// Mirrors EpicIntakeSection (src/renderer/lib/epicIntake.ts) — the labeled
+// slices composeEpicIntake emits alongside the flat `openingPrompt`, kept as
+// data so the Epic's first turn can render a structured AIM briefing card
+// instead of regex-parsing the flat string back apart.
+const EpicIntakeSectionSchema = z.object({
+  kind: z.enum(['actor', 'injection', 'input', 'mission', 'goal', 'reference']),
+  label: z.string(),
+  text: z.string(),
+  source: z.string().optional(),
+});
+
 // Mirrors PromptSession (src/renderer/state/promptSessions.ts:29-76).
 const PromptSessionSchema = z.object({
   id: z.string(),
@@ -52,6 +63,10 @@ const PromptSessionSchema = z.object({
   openingPrompt: z.string().nullable().optional(),
   source: EpicSourceSchema.optional(),
   agentType: z.string().optional(),
+  // Absent on Epics minted before this field existed — those fall back to
+  // rendering the flat `openingPrompt` as a single block (see
+  // ChatTranscriptTurn.tsx's EpicIntakeCard).
+  sections: z.array(EpicIntakeSectionSchema).optional(),
 });
 
 /**
@@ -75,5 +90,6 @@ module.exports = {
   PromptSessionSchema,
   EpicSourceSchema,
   EpicTagSchema,
+  EpicIntakeSectionSchema,
   assertValidPromptSession,
 };

package/src/main/lib/promptSessionsCreateEpic.cjs

@@ -41,13 +41,15 @@ const { validatePath } = require('../config.cjs');
  * IPC (config:read-json/write-json, lib/activeIndexMerge.cjs's own merge) is
  * already required to pass through.
  */
-async function createEpicViaIpc(cwd, { goalText, tag, agentType, source } = {}) {
+async function createEpicViaIpc(cwd, { goalText, tag, agentType, source, openingPrompt, sections } = {}) {
   validatePath(cwd);
   const { epicId } = await ensureEpic(cwd, {
     goalText,
     tag,
     agentType,
     source,
+    openingPrompt,
+    sections,
     mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI,
     status: 'proposed',
   });
@@ -60,8 +62,8 @@ function registerPromptSessionsCreateEpicHandlers() {
   const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
   ipcMain.handle(
     'promptSessions:create-epic',
-    v(s.promptSessionsCreateEpic, ({ cwd, goalText, tag, agentType, source }) =>
-      createEpicViaIpc(cwd, { goalText, tag, agentType, source })),
+    v(s.promptSessionsCreateEpic, ({ cwd, goalText, tag, agentType, source, openingPrompt, sections }) =>
+      createEpicViaIpc(cwd, { goalText, tag, agentType, source, openingPrompt, sections })),
   );
 }
 

package/src/main/lib/schedulerBatch.cjs

@@ -18,15 +18,29 @@ const os = require('node:os');
 const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
 
 /**
- * Per-project batch picker. Applies group-ordering rules scoped to a single
- * project (all jobs sharing one cwd).
+ * Per-project batch picker. `dependsOn` is the ONLY ordering primitive.
  *
- * Rules (same as original global pickNextBatch, but scoped):
- *   1. Find the lowest parallelGroup with pending jobs not already running.
- *   2. Failure gate: if an earlier group has failed jobs, hold this project.
- *   3. If that group has jobs in flight (backfill), fire more from SAME group.
- *   4. If a lower-numbered group arrives late (late-arrival), fire it now.
- *   5. If no group is in flight, start the lowest pending group fresh.
+ * Rules:
+ *   1. Eligible = pending, not already running, and no blocking dependency.
+ *   2. A dep is blocking while a queue row for it exists non-completed; a
+ *      FAILED dep holds its dependents with an explicit reason. Transitive
+ *      holds fall out of this for free (a held job stays `pending`, which is
+ *      itself a blocking state for anything depending on IT).
+ *   3. Everything eligible fires, up to `slots`, ordered by parallelGroup
+ *      ascending as a PRIORITY HINT only — never as a barrier.
+ *
+ * `parallelGroup` used to be a WAVE number and this function used to fire at
+ * most one wave per tick, holding every higher wave while a lower one was in
+ * flight. PRD 832 made the number strictly UNIQUE per PRD and moved ordering
+ * to `dependsOn` — `prdCreate.cjs` now warns that an explicit parallelGroup is
+ * "deprecated and ignored" — but this picker was never updated to match. With
+ * unique numbers every wave is a singleton, so the batch was always exactly
+ * ONE job, and because numbers are allocated monotonically upward, each newly
+ * queued PRD always sorted ABOVE the in-flight one and was held behind it.
+ * Measured effect: max concurrency 1 across 25 recorded runs, against a
+ * 5-slot pool. The group logic is gone; the real limits are the machine-wide
+ * `sessionSlots` pool and the memory gate, both enforced by the caller in
+ * scheduler.cjs's tickQueue.
  *
  * @param {object[]} projectJobs - All jobs for this project (all statuses).
  * @param {Set<string>} runningSlugsInProject - Slugs from the global
@@ -79,14 +93,24 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
   const allPending = projectJobs.filter(
     (j) => j.status === 'pending' && !runningSlugsInProject.has(j.slug),
   );
-  if (allPending.length === 0) return { batch: [], reason: null };
+  if (allPending.length === 0) return { batch: [], reason: null, holds: [] };
 
   const pending = [];
   const heldByFailedDep = [];
+  // Per-job hold records, surfaced to the UI so a `pending` row can say WHICH
+  // dep is holding it instead of leaving the reason in console.log.
+  const holds = [];
   for (const j of allPending) {
     const dep = blockingDep(j);
     if (!dep) { pending.push(j); continue; }
-    if (rowsForDep(dep).some((d) => d.status === 'failed')) heldByFailedDep.push({ job: j, dep });
+    const depRows = rowsForDep(dep);
+    const failed = depRows.some((d) => d.status === 'failed');
+    if (failed) heldByFailedDep.push({ job: j, dep });
+    holds.push({
+      slug: j.slug,
+      dep,
+      depStatus: depRows.find((d) => d.status !== 'completed')?.status ?? 'unknown',
+    });
     // running/pending/needs_review dep — simply not eligible this tick.
   }
   if (pending.length === 0) {
@@ -94,136 +118,69 @@ function pickForProject(projectJobs, runningSlugsInProject, slots) {
       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, holds };
     }
-    return { batch: [], reason: null };
+    return { batch: [], reason: null, holds };
   }
 
-  // Lowest pending group (computed up-front for the failure-gate check).
-  const lowestPendingGroup = pending.reduce(
-    (min, j) => Math.min(min, j.parallelGroup ?? 99),
-    Infinity,
-  );
-
-  // Cross-group failure gate: refuse to advance past a group with failed jobs.
-  // A failed foundation PRD should not allow later groups to run and
-  // silently corrupt project state. needs_review is NOT a blocker.
-  const blockingFailures = projectJobs.filter(
-    (j) => j.status === 'failed' && (j.parallelGroup ?? 99) < lowestPendingGroup,
-  );
-  if (blockingFailures.length > 0) {
-    const slugs = blockingFailures.map((j) => j.slug).join(', ');
-    const reason = `[scheduler] failure-gate [${projectCwd}]: holding g${lowestPendingGroup} — ` +
-      `${blockingFailures.length} failed job(s) in earlier groups [${slugs}]. ` +
-      `Reset to pending or archive to unblock.`;
-    console.log(reason);
-    return { batch: [], reason };
-  }
-
-  // Groups with at least one job in flight: either tracked in runningSlugsInProject
-  // (this process spawned it) or still marked 'running' in queue.json
-  // (persisted from a previous session that hasn't been orphan-reset yet).
-  const jobBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
-  const activeGroups = new Set();
-  for (const slug of runningSlugsInProject) {
-    const job = jobBySlug.get(slug);
-    if (job) activeGroups.add(job.parallelGroup ?? 99);
-  }
-  for (const j of projectJobs) {
-    if (j.status === 'running' && !runningSlugsInProject.has(j.slug)) {
-      activeGroups.add(j.parallelGroup ?? 99);
-    }
-  }
-
-  if (activeGroups.size > 0) {
-    const lowestActive = Math.min(...activeGroups);
-    if (lowestPendingGroup > lowestActive) {
-      // Earlier group still running — wait for it to drain before advancing.
-      const reason = `[scheduler] concurrency [${projectCwd}]: g${lowestActive} in flight, holding g${lowestPendingGroup}`;
-      console.log(reason);
-      return { batch: [], reason };
-    }
-    if (lowestPendingGroup < lowestActive) {
-      // Late-arrival: a lower-numbered (higher-priority) PRD reconciled AFTER
-      // a higher-numbered group was already picked. Fire it now in parallel
-      // with the active group rather than starving it until drain.
-      if (slots <= 0) {
-        const reason = `[scheduler] concurrency [${projectCwd}]: no slots for late-arrival g${lowestPendingGroup}`;
-        console.log(reason);
-        return { batch: [], reason };
-      }
-      const batch = pending
-        .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
-        .slice(0, slots);
-      console.log(
-        `[scheduler] concurrency [${projectCwd}]: firing late-arrival g${lowestPendingGroup} ` +
-        `(${batch.length} job(s)) alongside active g${lowestActive}`,
-      );
-      return { batch, reason: null };
-    }
-    // Backfill slots remaining in the current group.
-    if (slots <= 0) {
-      const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
-      console.log(reason);
-      return { batch: [], reason };
-    }
-    const batch = pending
-      .filter((j) => (j.parallelGroup ?? 99) === lowestActive)
-      .slice(0, slots);
-    if (batch.length > 0) {
-      console.log(
-        `[scheduler] concurrency [${projectCwd}]: backfilling ${batch.length} into g${lowestActive}`,
-      );
-    }
-    return { batch, reason: null };
-  }
-
-  // No active group — start the next group fresh.
   if (slots <= 0) {
-    const reason = `[scheduler] concurrency [${projectCwd}]: cap reached, no slots`;
+    const reason = `[scheduler] concurrency [${projectCwd}]: no slots free, holding ${pending.length} eligible job(s)`;
     console.log(reason);
-    return { batch: [], reason };
+    return { batch: [], reason, holds };
   }
+
+  // parallelGroup is a PRIORITY HINT, not a barrier: when there are more
+  // eligible jobs than slots, the lower (earlier-authored) PRD numbers go
+  // first. Everything else about the number is display-only.
   const batch = pending
-    .filter((j) => (j.parallelGroup ?? 99) === lowestPendingGroup)
+    .slice()
+    .sort((a, b) => (a.parallelGroup ?? 99) - (b.parallelGroup ?? 99))
     .slice(0, slots);
   console.log(
-    `[scheduler] concurrency [${projectCwd}]: starting g${lowestPendingGroup} with ${batch.length} job(s)`,
+    `[scheduler] concurrency [${projectCwd}]: firing ${batch.length} of ${pending.length} ` +
+    `eligible job(s) [${batch.map((j) => j.slug).join(', ')}]`,
   );
-  return { batch, reason: null };
+  return { batch, reason: null, holds };
 }
 
 /**
  * Pick the next batch of jobs to spawn this tick.
  *
- * Group-ordering gates are evaluated PER PROJECT (keyed by cwd), so jobs in
- * different projects are not serialized by each other's groups. Within a
- * single project, the existing sequential-group semantics are fully preserved.
+ * Dependency gates are evaluated PER PROJECT (keyed by cwd), so jobs in
+ * different projects never serialize each other.
  *
  * O(N) where N = allJobs.length.
  *
  * @param {object[]} allJobs - Full queue.json job list.
  * @param {Set<string>} running - In-process running slugs (runningSet).
- * @param {number} cap - concurrencyCap.
+ * @param {number} freeSlots - Slots free RIGHT NOW in the machine-wide
+ *   `sessionSlots` pool (`sessionSlots.available()`). This is already
+ *   net of every held slot — scheduler jobs AND chat runs — so it must not
+ *   have the running count subtracted from it again. The scheduler no longer
+ *   keeps a private concurrency cap of its own: per sessionSlots.cjs's own
+ *   charter, caps belong to Session-Manager's one pool, not to each consumer.
  * @returns {{ batch: object[], reason: string | null }} Jobs to spawn this
  *   tick, plus (when batch is empty because a gate held it) the human-readable
  *   hold reason that would otherwise only reach console.log.
  */
-function pickNextBatch(allJobs, running, cap) {
+function pickNextBatch(allJobs, running, freeSlots) {
   if (!allJobs.some((j) => j.status === 'pending' && !running.has(j.slug))) {
-    return { batch: [], reason: null };
+    return { batch: [], reason: null, holds: [] };
   }
 
-  // Global slot accounting: take the higher of in-process running count and
-  // queue.json running count (handles orphaned running entries from a previous
-  // session not yet reaped).
+  // Orphan correction: a queue.json row still marked `running` that this
+  // process did NOT spawn holds no pool slot (it is a leftover from a crashed
+  // prior session, pending boot reconciliation). The pool cannot see it, so
+  // discount it here rather than starting a job into a slot a soon-to-be-
+  // reaped process may still be occupying.
   const queueRunningCount = allJobs.filter((j) => j.status === 'running').length;
-  const effectiveRunning = Math.max(running.size, queueRunningCount);
-  let slots = cap - effectiveRunning;
+  const untrackedRunning = Math.max(0, queueRunningCount - running.size);
+  let slots = freeSlots - untrackedRunning;
   if (slots <= 0) {
-    const reason = `[scheduler] concurrency: cap ${cap} reached (${effectiveRunning} running), no slots`;
+    const reason = `[scheduler] concurrency: no session slots free ` +
+      `(${freeSlots} free in pool, ${untrackedRunning} untracked running row(s))`;
     console.log(reason);
-    return { batch: [], reason };
+    return { batch: [], reason, holds: [] };
   }
 
   // Group all jobs by project cwd.
@@ -259,15 +216,17 @@ function pickNextBatch(allJobs, running, cap) {
   // Aggregate batch across projects, consuming global slots as we go. Track
   // the first hold reason seen so callers can explain an empty overall batch.
   const batch = [];
+  const holds = [];
   let heldReason = null;
   for (const { projectJobs, runningSlugsInProject } of projectCandidates) {
     if (slots <= 0) break;
     const projectResult = pickForProject(projectJobs, runningSlugsInProject, slots);
     batch.push(...projectResult.batch);
+    holds.push(...(projectResult.holds ?? []));
     slots -= projectResult.batch.length;
     if (heldReason === null && projectResult.reason) heldReason = projectResult.reason;
   }
-  return { batch, reason: batch.length === 0 ? heldReason : null };
+  return { batch, reason: batch.length === 0 ? heldReason : null, holds };
 }
 
 module.exports = { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD };

package/src/main/lib/schedulerConfig.cjs

@@ -17,7 +17,6 @@ module.exports = {
   HTTP_TIMEOUT_MS: 30_000,
   HTTP_RETRY_DELAY_MS: 1_000,
   OFFSET_MINUTES_MAX: 180,
-  CONCURRENCY_CAP_MAX: 20,
   MAX_JOB_DURATION_MS: 4 * 60 * 60_000,
   SUPERVISOR_INTERVAL_MS: 15 * 60_000,
   SUPERVISOR_PROBE_STALE_MS: 10 * 60_000,

package/src/main/otel.cjs

@@ -1,7 +1,9 @@
 /**
  * otel — mirrors transcripts.cjs classified events as OpenTelemetry spans.
  *
- * Spans are 0-duration "events": one span per classified transcript line,
+ * Spans are 0-duration "events": one span per classified transcript EVENT
+ * (a single JSONL line can classify to several events — e.g. a usage rollup
+ * alongside real content, or several tool calls in one assistant turn),
  * named `transcript.<kind>`, with structural attributes only. Tool inputs,
  * plan text, and agent prompts are excluded unless `includeContent` is on
  * (matches upstream OTEL_LOG_USER_PROMPTS opt-in).

package/src/main/projectPages.cjs

@@ -11,9 +11,19 @@
  * session-manager-operations/project-pages/README.md. Structure mirrors
  * projectBrief.cjs's `get()`: validatePath first, config.cjs read helpers,
  * one ipcMain.handle registered from index.cjs's registerXHandlers() pattern.
+ *
+ * Shipped default (PRD "project-home-hosted-html-spec"): when a project has
+ * never generated its own output, `get()` no longer returns the bare
+ * `{ output: null }` empty-state signal — it falls back to a build-time
+ * default `home.html` shipped with the app (`templates/`), returned with
+ * `isDefault: true` and `generatedAt: null` so the renderer can label
+ * provenance. That default is read from a fixed app-relative path, never
+ * written into any project's own `session-manager-operations/` tree — this
+ * module stays read-only.
  */
 
 const { ipcMain } = require('electron');
+const fs = require('node:fs');
 const path = require('node:path');
 const config = require('./config.cjs');
 
@@ -21,38 +31,72 @@ function outputDir(cwd) {
   return path.join(cwd, 'session-manager-operations', 'project-pages', 'output');
 }
 
-const LENSES = ['home', 'marketing', 'feature', 'architecture'];
+// Shipped build-time asset (see PRD "project-home-hosted-html-spec"'s
+// default-document requirement) — a fixed app-relative path with no
+// user-controlled segment, so it deliberately does NOT go through
+// config.cjs's validatePath (whose allowedRoots is the user's home dir and
+// would reject/mis-resolve a path under the app's own install directory,
+// e.g. when installed via npx/global npm outside $HOME). Read once and
+// cached in-process; this file never changes at runtime.
+const DEFAULT_HOME_PATH = path.join(__dirname, 'templates', 'project-pages-default-home.html');
+let cachedDefaultHomeHtml = null;
+function readDefaultHomeHtml() {
+  if (cachedDefaultHomeHtml === null) {
+    cachedDefaultHomeHtml = fs.readFileSync(DEFAULT_HOME_PATH, 'utf8');
+  }
+  return cachedDefaultHomeHtml;
+}
+function defaultOutput() {
+  return { home: readDefaultHomeHtml(), generatedAt: null, isDefault: true };
+}
+
+// The original 4 lenses stay required — their absence still means "no
+// Project Pages generated yet" (now the shipped-default fallback rather
+// than a bare null). 'brief' was added later (5th lens): a project that
+// generated its output BEFORE 'brief'
+// existed has home/marketing/feature/architecture.html but no brief.html, and
+// that must keep reading as "has output" rather than suddenly regressing to
+// the empty state for every pre-existing project. So brief.html is read
+// tolerantly — present, its text is returned; absent, the field is simply
+// omitted from the payload rather than failing the whole read.
+const REQUIRED_LENSES = ['home', 'marketing', 'feature', 'architecture'];
+const OPTIONAL_LENSES = ['brief'];
+const LENSES = [...REQUIRED_LENSES, ...OPTIONAL_LENSES];
 
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
   const dir = outputDir(realCwd);
   const manifestResult = await config.readJson(path.join(dir, 'manifest.json'));
   if (!manifestResult.exists || !manifestResult.data || manifestResult.parseError) {
-    return { output: null };
+    return { output: defaultOutput() };
   }
 
   const htmlResults = await Promise.all(
     LENSES.map((lens) => config.readText(path.join(dir, `${lens}.html`))),
   );
-  if (htmlResults.some((r) => !r.exists)) {
-    return { output: null };
+  const byLens = Object.fromEntries(LENSES.map((lens, i) => [lens, htmlResults[i]]));
+  if (REQUIRED_LENSES.some((lens) => !byLens[lens].exists)) {
+    return { output: defaultOutput() };
   }
 
-  const [home, marketing, feature, architecture] = htmlResults;
   const generatedAt = typeof manifestResult.data.generatedAt === 'string' ? manifestResult.data.generatedAt : null;
   if (!generatedAt) {
-    return { output: null };
+    return { output: defaultOutput() };
   }
 
-  return {
-    output: {
-      home: home.text,
-      marketing: marketing.text,
-      feature: feature.text,
-      architecture: architecture.text,
-      generatedAt,
-    },
+  const output = {
+    home: byLens.home.text,
+    marketing: byLens.marketing.text,
+    feature: byLens.feature.text,
+    architecture: byLens.architecture.text,
+    generatedAt,
+    isDefault: false,
   };
+  if (byLens.brief.exists) {
+    output.brief = byLens.brief.text;
+  }
+
+  return { output };
 }
 
 function registerProjectPagesIpc() {
@@ -63,4 +107,6 @@ function registerProjectPagesIpc() {
 module.exports = {
   registerProjectPagesIpc,
   get,
+  DEFAULT_HOME_PATH,
+  readDefaultHomeHtml,
 };

package/src/main/promptSessionEvents.cjs

@@ -51,8 +51,20 @@ function mintEventId() {
  * unknown id, a completed session, an empty event chain, or any I/O error —
  * so notifyOriginatingTab's existing tab-external-ticket path stays the
  * safety net, not a special case.
+ *
+ * The optional 4th argument stamps `prdSlug`/`outcome` onto the appended
+ * event (PRD 976) — which PRD checked in and whether it completed, failed,
+ * or needs review — so the Epic's own event chain keeps that signal even
+ * after the job is archived out of queue.json. PRD 986 extends the same
+ * meta arg (not a fifth positional parameter) with `validation`: a
+ * scheduler check-in is born `'unvalidated'` — never `'verified'` —
+ * regardless of the job's self-reported outcome; the authoring Epic's own
+ * validation pass is what may later move it to 'verified'/'refuted'. All
+ * keys are added to the event object only when present in `meta`, never as
+ * `undefined`-valued keys, so events appended without them serialize
+ * identically to before.
  */
-async function appendResponseEventIfKnown(cwd, sourcePromptId, text) {
+async function appendResponseEventIfKnown(cwd, sourcePromptId, text, meta = {}) {
   if (!cwd || !sourcePromptId) return false;
   const path = promptSessionActiveIndexPath(cwd);
   try {
@@ -73,6 +85,9 @@ async function appendResponseEventIfKnown(cwd, sourcePromptId, text) {
         at: new Date().toISOString(),
         text,
       };
+      if (meta && meta.prdSlug) event.prdSlug = meta.prdSlug;
+      if (meta && meta.outcome) event.outcome = meta.outcome;
+      if (meta && meta.validation) event.validation = meta.validation;
       data.events[sourcePromptId] = [...events, event];
       await config.writeJson(path, data, { writer: 'scheduler' });
       broadcast(EVENT_APPENDED_CHANNEL, { cwd, promptSessionId: sourcePromptId, event });