claude-code-session-manager 0.76.0 → 0.78.0

package/src/main/lib/landedSinceRun.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * landedSinceRun.cjs — widened, path-scoped commit evidence for the reverify
+ * self-heal pass (PRD 1102).
+ *
+ * committedInWindow (scheduler.cjs) only sees commits inside
+ * [startedAt, finishedAt+60s] — a commit that lands later (a retry, a
+ * sibling run, a human) is invisible to it. landedSinceRun has no upper
+ * bound, but narrows the OTHER way that committedInWindow is dangerously
+ * broad: it is scoped to paths the PRD itself declares, so an unrelated
+ * commit elsewhere in the repo is not credited to this job (see
+ * scheduler.cjs's healRefusalReason for why repo-wide, unscoped evidence is
+ * not attribution).
+ *
+ * Pure git wrapper — no fetch, no scheduler state. Callers that need remote
+ * commits visible (e.g. a job that committed in a since-removed worktree)
+ * must call scheduler.cjs's fetchAllRefs(cwd) first, same as
+ * committedInWindow's own callers do.
+ */
+
+const { execFile } = require('node:child_process');
+
+const LANDED_SINCE_RUN_TIMEOUT_MS = 10_000;
+
+/**
+ * Commits in `cwd` since `sinceIso` (no upper bound) that touch any of
+ * `paths`. Never throws — git-unavailable, a non-repo cwd, or an empty
+ * `paths` list all resolve to `[]` rather than fabricating evidence.
+ *
+ * @param {string} cwd
+ * @param {string} sinceIso
+ * @param {string[]} paths
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<string[]>} full commit SHAs, newest first
+ */
+function landedSinceRun(cwd, sinceIso, paths, { timeoutMs = LANDED_SINCE_RUN_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    if (!cwd || !sinceIso || !Array.isArray(paths) || paths.length === 0) {
+      resolve([]);
+      return;
+    }
+    execFile(
+      'git',
+      ['-C', cwd, 'log', '--all', `--since=${sinceIso}`, '--format=%H', '--', ...paths],
+      { timeout: timeoutMs, windowsHide: true },
+      (err, stdout) => {
+        if (err) { resolve([]); return; }
+        resolve(String(stdout || '').trim().split('\n').filter(Boolean));
+      },
+    );
+  });
+}
+
+module.exports = { landedSinceRun, LANDED_SINCE_RUN_TIMEOUT_MS };

package/src/main/lib/launchFailure.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+/**
+ * launchFailure.cjs — detects a headless `claude -p` run that NEVER RAN, and
+ * models the per-persona launch circuit breaker the scheduler routes on.
+ *
+ * Incident (GitHub issue #11, 2026-09-02, macOS): the installed Claude CLI
+ * sent `thinking.type.enabled` to a model that only accepts
+ * `thinking.type.adaptive`. The API answered HTTP 400 on the very first
+ * request, so every job did zero turns, spent zero output tokens, wrote zero
+ * files, exited 1 in ~25 s — and was recorded as `failed` with `error: null`,
+ * indistinguishable from a real implementation failure. The auto-fix
+ * investigation probe then launched with the same CLI and died the same way.
+ * 12 of 41 transcripts in one project over a month were this signature.
+ *
+ * Two facts this module makes first-class:
+ *
+ *  1. A NON-RUN is not a failure of the PRD. `classifyLaunchFailure` is
+ *     deliberately narrow — it only fires when the transcript's `result`
+ *     event shows no real turn (num_turns ≤ 1 AND output_tokens = 0) AND the
+ *     result text carries the CLI's literal `API Error:` prefix. Anything
+ *     that did a turn, or failed without the API marker, is somebody else's
+ *     classification (rate-limit, network, transient, verifier).
+ *
+ *  2. The environment is broken, not the job — so the scheduler must stop
+ *     re-dispatching identical launches (each one is a wasted 25 s + a
+ *     misleading `failed` row + a doomed investigation) while still
+ *     self-healing the moment the environment is fixed. That is a circuit
+ *     breaker keyed by the launch persona (`agentType` → model): closed
+ *     (normal) → open (blocked, exponential backoff) → half-open (exactly one
+ *     probe job goes through) → closed again on a real turn. A CLI version
+ *     change (the actual fix for the incident: `claude update`) short-circuits
+ *     the backoff so the queue resumes on the next tick, not the next hour.
+ *
+ * Pure and Electron-free: every function here takes plain values (a parsed
+ * result event, a block record, `now`) so the whole state machine is
+ * unit-testable without a spawn. scheduler.cjs owns the I/O around it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readTail } = require('./fileTail.cjs');
+
+const LAUNCH_FAILURE_KINDS = Object.freeze({
+  /** HTTP 400 naming a thinking/effort/config parameter the model rejects — the issue-#11 signature. */
+  MODEL_CONFIG_REJECTED: 'model_config_rejected',
+  /** Any other HTTP 400 on the first request (malformed request body, unsupported flag combo). */
+  BAD_REQUEST: 'bad_request',
+  /** HTTP 401/403 — the CLI's credentials are missing, expired, or lack access to the model. */
+  AUTH_FAILED: 'auth_failed',
+  /** HTTP 404 that names the model — the pinned `--model` does not exist for this account/CLI. */
+  MODEL_NOT_FOUND: 'model_not_found',
+  /** HTTP 5xx / 529 / "Overloaded" — the API itself is unavailable right now. */
+  API_OVERLOADED: 'api_overloaded',
+  /** Any other first-request API error. */
+  API_ERROR: 'api_error',
+});
+
+/** Tail bytes scanned for the `result` event — same budget classifyRunOutcome uses. */
+const RESULT_TAIL_BYTES = 65536;
+
+/**
+ * Parse the LAST `{"type":"result",...}` stream-json event out of a log tail.
+ * Returns a flat, typed summary or null when no result event is present
+ * (the process died before the harness could emit one — that is
+ * reaperHelpers' `no_result`, not a launch failure).
+ */
+function parseResultEvent(text) {
+  if (!text) return null;
+  let last = null;
+  for (const line of String(text).split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{') || !t.includes('"type":"result"')) continue;
+    try {
+      const obj = JSON.parse(t);
+      if (obj && obj.type === 'result') last = obj;
+    } catch { /* partial line at the tail boundary */ }
+  }
+  if (!last) return null;
+  const usage = last.usage && typeof last.usage === 'object' ? last.usage : {};
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  return {
+    subtype: typeof last.subtype === 'string' ? last.subtype : '',
+    isError: last.is_error === true,
+    numTurns: num(last.num_turns),
+    outputTokens: num(usage.output_tokens),
+    inputTokens: num(usage.input_tokens),
+    apiErrorStatus: num(last.api_error_status),
+    totalCostUsd: num(last.total_cost_usd),
+    durationMs: num(last.duration_ms),
+    terminalReason: typeof last.terminal_reason === 'string' ? last.terminal_reason : null,
+    resultText: typeof last.result === 'string' ? last.result : '',
+  };
+}
+
+function readResultEvent(logPath) {
+  try {
+    return parseResultEvent(readTail(logPath, RESULT_TAIL_BYTES));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull the human-readable message out of the CLI's `API Error: <status> <json>`
+ * text. The body nests unpredictably (`{"error":{"message":...}}`, or
+ * `{"detail":{"error":"<json string with message>"}}` as in issue #11), so
+ * this walks any `message`/`error` chain it can parse and falls back to the
+ * raw text, bounded.
+ */
+function extractApiMessage(text) {
+  const raw = String(text || '').trim();
+  const jsonStart = raw.indexOf('{');
+  if (jsonStart >= 0) {
+    let node;
+    try { node = JSON.parse(raw.slice(jsonStart)); } catch { node = null; }
+    let depth = 0;
+    while (node && depth < 6) {
+      depth += 1;
+      if (typeof node === 'string') {
+        const s = node.trim();
+        if (s.startsWith('{')) {
+          try { node = JSON.parse(s); continue; } catch { /* not JSON — it's the message */ }
+        }
+        return s.slice(0, 400);
+      }
+      if (typeof node !== 'object') break;
+      if (typeof node.message === 'string') return node.message.slice(0, 400);
+      node = node.error ?? node.detail ?? null;
+    }
+  }
+  return raw.slice(0, 400);
+}
+
+/**
+ * classifyLaunchFailure(result) → null | { kind, httpStatus, message }
+ *
+ * `result` is parseResultEvent()'s output. Returns null for every run that
+ * did real work (or failed for a reason that is not a first-request API
+ * rejection) — the narrowness is the point; see the module header.
+ * HTTP 429 is excluded: the rate-limit pause path owns it.
+ */
+function classifyLaunchFailure(result) {
+  if (!result) return null;
+  const numTurns = result.numTurns ?? 0;
+  const outputTokens = result.outputTokens ?? 0;
+  if (numTurns > 1 || outputTokens > 0) return null;
+  const text = result.resultText || '';
+  const marker = /API Error:?\s*(\d{3})?/i.exec(text);
+  if (!marker && !(result.isError && result.apiErrorStatus)) return null;
+  const httpStatus = (marker && marker[1] ? Number(marker[1]) : null) ?? result.apiErrorStatus ?? null;
+  if (httpStatus === 429) return null;
+  const message = extractApiMessage(text.replace(/^.*?API Error:?\s*(\d{3})?\s*/i, '')) || text.slice(0, 400);
+  let kind;
+  if (httpStatus === 400) {
+    kind = /thinking|not supported for this model|output_config|effort/i.test(text)
+      ? LAUNCH_FAILURE_KINDS.MODEL_CONFIG_REJECTED
+      : LAUNCH_FAILURE_KINDS.BAD_REQUEST;
+  } else if (httpStatus === 401 || httpStatus === 403) {
+    kind = LAUNCH_FAILURE_KINDS.AUTH_FAILED;
+  } else if (httpStatus === 404 && /model/i.test(text)) {
+    kind = LAUNCH_FAILURE_KINDS.MODEL_NOT_FOUND;
+  } else if ((httpStatus !== null && httpStatus >= 500) || /overloaded/i.test(text)) {
+    kind = LAUNCH_FAILURE_KINDS.API_OVERLOADED;
+  } else {
+    kind = LAUNCH_FAILURE_KINDS.API_ERROR;
+  }
+  return { kind, httpStatus, message };
+}
+
+/** Did this run get at least one real model turn? (The half-open probe's "close the breaker" evidence.) */
+function resultShowsRealTurn(result) {
+  if (!result) return false;
+  return (result.numTurns ?? 0) > 1 || (result.outputTokens ?? 0) > 0;
+}
+
+// ─── Circuit breaker ────────────────────────────────────────────────────────
+
+/** After this many consecutive failed probes the block stays open until the CLI version changes or a human resets it. */
+const LAUNCH_BLOCK_MAX_ATTEMPTS = 8;
+/** A probe that has not reported back in this long is presumed dead; the next tick may probe again. */
+const LAUNCH_PROBE_STALE_MS = 30 * 60_000;
+
+const BACKOFF_BASE_MS = {
+  [LAUNCH_FAILURE_KINDS.MODEL_CONFIG_REJECTED]: 5 * 60_000,
+  [LAUNCH_FAILURE_KINDS.BAD_REQUEST]: 5 * 60_000,
+  [LAUNCH_FAILURE_KINDS.AUTH_FAILED]: 5 * 60_000,
+  [LAUNCH_FAILURE_KINDS.MODEL_NOT_FOUND]: 10 * 60_000,
+  [LAUNCH_FAILURE_KINDS.API_OVERLOADED]: 60_000,
+  [LAUNCH_FAILURE_KINDS.API_ERROR]: 2 * 60_000,
+};
+const BACKOFF_CAP_MS = 60 * 60_000;
+
+/** Exponential backoff for the Nth consecutive failure (attempts ≥ 1), capped at one hour. */
+function backoffMsFor(kind, attempts) {
+  const base = BACKOFF_BASE_MS[kind] ?? BACKOFF_BASE_MS[LAUNCH_FAILURE_KINDS.API_ERROR];
+  const n = Math.max(0, (attempts ?? 1) - 1);
+  return Math.min(BACKOFF_CAP_MS, base * 2 ** n);
+}
+
+/**
+ * Environment the scheduler applies to a launch as a DEGRADED-MODE
+ * mitigation for a kind, or null when there is none. For the issue-#11
+ * signature the CLI's `MAX_THINKING_TOKENS=0` switches extended thinking off
+ * entirely, so an older CLI stops sending the rejected `thinking` block at
+ * all — the run proceeds without thinking rather than not at all. Harmless
+ * if the CLI ignores it (the probe simply fails again and the backoff holds).
+ */
+function mitigationEnvFor(kind) {
+  if (kind === LAUNCH_FAILURE_KINDS.MODEL_CONFIG_REJECTED) return { MAX_THINKING_TOKENS: '0' };
+  return null;
+}
+
+/** Circuit-breaker key: the launch persona, because `agentType` is what selects the `--model`. */
+function launchBlockKeyFor(job) {
+  return (job && typeof job.agentType === 'string' && job.agentType) || 'default';
+}
+
+/** Operator-facing explanation + the one action that clears the condition. */
+function launchFailureHint(kind, { claudeVersion, mitigationInForce = false } = {}) {
+  const ver = claudeVersion ? `installed Claude CLI ${claudeVersion}` : 'installed Claude CLI';
+  switch (kind) {
+    case LAUNCH_FAILURE_KINDS.MODEL_CONFIG_REJECTED:
+      return mitigationInForce
+        ? `The ${ver} sends a thinking parameter this model rejects, and disabling thinking (MAX_THINKING_TOKENS=0) did not get past it. Update the CLI (\`claude update\` or \`npm i -g @anthropic-ai/claude-code@latest\`); the queue resumes automatically when the version changes.`
+        : `The ${ver} sends a thinking parameter this model rejects (HTTP 400 on the first request — no work was attempted). Update the CLI (\`claude update\` or \`npm i -g @anthropic-ai/claude-code@latest\`); until then jobs re-probe with thinking disabled, and the queue resumes automatically when the version changes.`;
+    case LAUNCH_FAILURE_KINDS.AUTH_FAILED:
+      return `The API rejected the CLI's credentials (HTTP 401/403) before any work started. Run \`claude login\` (or check the model is enabled for this account), then press Retry now.`;
+    case LAUNCH_FAILURE_KINDS.MODEL_NOT_FOUND:
+      return `The pinned --model does not exist for the ${ver} / this account (HTTP 404). Fix the persona's \`model:\` in the Agent Library or update the CLI, then press Retry now.`;
+    case LAUNCH_FAILURE_KINDS.API_OVERLOADED:
+      return 'The API is overloaded or unavailable (HTTP 5xx/529). Nothing is wrong with the PRD; the scheduler re-probes with backoff and resumes on its own.';
+    case LAUNCH_FAILURE_KINDS.BAD_REQUEST:
+      return `The API rejected the launch request (HTTP 400) before any work started. Check the ${ver} against the pinned model, then press Retry now.`;
+    default:
+      return 'The first API request of the run failed before any work started. The scheduler re-probes with backoff; press Retry now to probe immediately.';
+  }
+}
+
+/**
+ * armLaunchBlock(prev, failure) → block
+ *
+ * Opens (or re-opens with a longer backoff) the breaker for one key after a
+ * launch failure. `prev` is the existing block for the key or null; a
+ * different `kind` than before restarts the attempt count, the same kind
+ * escalates it. Beyond LAUNCH_BLOCK_MAX_ATTEMPTS `until` becomes null:
+ * blocked indefinitely — only a CLI version change or a human Retry clears
+ * it, and the UI says so.
+ */
+function armLaunchBlock(prev, { kind, httpStatus, message, now, claudeVersion, slug, runId, mitigationApplied = false }) {
+  const sameKind = prev && prev.kind === kind;
+  const attempts = sameKind ? (prev.attempts ?? 0) + 1 : 1;
+  const exhausted = attempts >= LAUNCH_BLOCK_MAX_ATTEMPTS;
+  const mitigationEnv = mitigationEnvFor(kind);
+  return {
+    kind,
+    httpStatus: httpStatus ?? null,
+    message: String(message || '').slice(0, 400),
+    hint: launchFailureHint(kind, { claudeVersion, mitigationInForce: mitigationApplied }),
+    since: sameKind && prev.since ? prev.since : new Date(now).toISOString(),
+    lastAt: new Date(now).toISOString(),
+    until: exhausted ? null : new Date(now + backoffMsFor(kind, attempts)).toISOString(),
+    attempts,
+    exhausted,
+    claudeVersion: claudeVersion ?? null,
+    lastSlug: slug ?? null,
+    lastRunId: runId ?? null,
+    mitigationEnv,
+    mitigationApplied,
+    probing: null,
+  };
+}
+
+/**
+ * evaluateLaunchGate(block, { now, claudeVersion }) →
+ *   { state: 'open' | 'blocked' | 'probe', reason }
+ *
+ * 'open'    — no block, or the CLI version changed since it was armed (the
+ *             caller should drop the block: the environment was replaced).
+ * 'blocked' — inside the backoff window, exhausted, or a probe is already in
+ *             flight. `reason` is the row-level hold text.
+ * 'probe'   — backoff elapsed: let exactly ONE job through as the probe.
+ */
+function evaluateLaunchGate(block, { now, claudeVersion } = {}) {
+  if (!block) return { state: 'open', reason: null };
+  if (claudeVersion && block.claudeVersion && claudeVersion !== block.claudeVersion) {
+    return { state: 'open', reason: `cli-version-changed (${block.claudeVersion} → ${claudeVersion})` };
+  }
+  const t = typeof now === 'number' ? now : Date.now();
+  if (block.probing && block.probing.at) {
+    const age = t - Date.parse(block.probing.at);
+    if (Number.isFinite(age) && age >= 0 && age < LAUNCH_PROBE_STALE_MS) {
+      return { state: 'blocked', reason: `launch blocked (${block.kind}) — probe ${block.probing.slug} in flight` };
+    }
+  }
+  if (block.until === null || block.until === undefined) {
+    return { state: 'blocked', reason: `launch blocked (${block.kind}) after ${block.attempts} failed probe(s) — ${block.hint}` };
+  }
+  const until = Date.parse(block.until);
+  if (Number.isFinite(until) && t < until) {
+    const mins = Math.max(1, Math.round((until - t) / 60_000));
+    return { state: 'blocked', reason: `launch blocked (${block.kind}) — re-probe in ${mins} min. ${block.hint}` };
+  }
+  return { state: 'probe', reason: `launch probe (${block.kind}) — attempt ${(block.attempts ?? 0) + 1}` };
+}
+
+/**
+ * Terminal-reason taxonomy for a finalized job row (issue #11 list A2). A
+ * closed set so operators never have to open a transcript to tell a
+ * non-start from an implementation failure from a verifier downgrade.
+ */
+function deriveTerminalReason({ effectiveStatus, exitCode, verifyResult, sigtermOverride, worktreeIntegrationFailure }) {
+  if (worktreeIntegrationFailure) return 'worktree_integration_failed';
+  if (effectiveStatus === 'completed') return 'completed';
+  if (sigtermOverride) return 'signal_kill_with_commit';
+  if (exitCode === 143 || exitCode === 137) return 'signal_kill';
+  if (typeof exitCode === 'number' && exitCode !== 0) return `impl_failed:exit_${exitCode}`;
+  if (effectiveStatus === 'needs_review' && verifyResult && verifyResult.verdict) return `verifier:${verifyResult.verdict}`;
+  return effectiveStatus || 'unknown';
+}
+
+/**
+ * Write the per-run `<slug>.outcome.json` sidecar (issue #11 list B5): the
+ * handful of numbers that make fleet health computable without parsing
+ * transcripts. Best-effort, never throws.
+ */
+function writeOutcomeSidecar(runDir, slug, outcome) {
+  if (!runDir || !slug) return null;
+  const p = path.join(runDir, `${slug}.outcome.json`);
+  try {
+    const tmp = `${p}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ slug, writtenAt: new Date().toISOString(), ...outcome }, null, 2));
+    fs.renameSync(tmp, p);
+    return p;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  LAUNCH_FAILURE_KINDS,
+  LAUNCH_BLOCK_MAX_ATTEMPTS,
+  LAUNCH_PROBE_STALE_MS,
+  parseResultEvent,
+  readResultEvent,
+  extractApiMessage,
+  classifyLaunchFailure,
+  resultShowsRealTurn,
+  backoffMsFor,
+  mitigationEnvFor,
+  launchBlockKeyFor,
+  launchFailureHint,
+  armLaunchBlock,
+  evaluateLaunchGate,
+  deriveTerminalReason,
+  writeOutcomeSidecar,
+};

package/src/main/lib/mcpToolCatalog.cjs

@@ -23,7 +23,7 @@ const { z } = require('zod');
 
 const CatalogEntrySchema = z.object({
   name: z.string().min(1),
-  group: z.enum(['scheduler', 'chat', 'feedback', 'help']),
+  group: z.enum(['scheduler', 'chat', 'feedback', 'help', 'project-home']),
   purpose: z.string().min(1),
   whenToUse: z.string().min(1),
   whenNotToUse: z.string().min(1),
@@ -71,7 +71,11 @@ const MCP_TOOL_CATALOG = [
       + '`cwd` is OPTIONAL when called from inside an Epic session (chat or terminal, '
       + 'including from inside that Epic\'s own git worktree pwd): the server resolves '
       + 'the real project from the calling session\'s sourcePromptId/originClaudeSessionId, '
-      + 'never from a worktree\'s own possibly-stale active-index.json snapshot.',
+      + 'never from a worktree\'s own possibly-stale active-index.json snapshot. '
+      + '`tag` and `agentType` are two DIFFERENT, independent fields — `tag` is WHAT KIND '
+      + 'of work this PRD is (feature/bug/build/...); `agentType` is WHO executes it (a '
+      + 'persona name, e.g. "dev-lead"). `agentType` defaults to "dev-lead" when omitted, '
+      + 'and is rejected at write time if it does not name a real persona file.',
     whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
     whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
       + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '
@@ -213,6 +217,68 @@ const MCP_TOOL_CATALOG = [
       + 'the other project has "been fixed" or "is working on it". Report only that the proposal was '
       + 'delivered.',
   },
+  {
+    name: 'project_home_get_contract',
+    group: 'project-home',
+    purpose: "Fetch the self-sufficient contract for generating this project's Project Home pages via the "
+      + "session-manager app's admin API — the protocol steps, the ProjectPageSummary/ProjectPagePicks JSON "
+      + 'schemas, the component catalog (all 5 lenses: home, marketing, feature, architecture, brief), the '
+      + 'absolute output paths, and the full pipeline spec text. Nothing in the response requires reading '
+      + "session-manager's own repo — this is what makes generation work on a machine with only the npm "
+      + 'package installed.',
+    whenToUse: 'Call this FIRST, before composing any ProjectPageSummary content or picking variants, whenever '
+      + 'a project-home-builder session starts generating Project Home pages for a project.',
+    whenNotToUse: 'Do not begin composing a ProjectPageSummary or choosing variants before calling this — it '
+      + 'must be the FIRST call a project-home-builder session makes; every other project_home_* tool assumes '
+      + "you already have this response's schema/catalog/paths in hand.",
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
+    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
+  },
+  {
+    name: 'project_home_validate_summary',
+    group: 'project-home',
+    purpose: 'Validate a composed ProjectPageSummary against the schema from project_home_get_contract via the '
+      + "session-manager app's admin API, without writing anything to disk.",
+    whenToUse: 'Use after composing (or editing) a ProjectPageSummary and before calling project_home_render — '
+      + 'fix every returned {field, message} error and re-validate until valid:true.',
+    whenNotToUse: 'Do not skip straight to project_home_render on an unvalidated summary — render does '
+      + 're-validate server-side and rejects with no writes on failure, but catching errors here first saves a '
+      + 'round trip and gives per-field detail sooner.',
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager', summary: { title: 'Example Project' } },
+    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
+  },
+  {
+    name: 'project_home_render',
+    group: 'project-home',
+    purpose: 'Render and write all 5 Project Home lenses (home, marketing, feature, architecture, brief) plus '
+      + "summary.json/picks.json/manifest.json via the session-manager app's admin API — the only write path "
+      + 'for Project Home generation.',
+    whenToUse: 'Use once project_home_validate_summary reports valid:true and a variant has been picked for '
+      + "every lens/slot in the contract's catalog.",
+    whenNotToUse: 'Must NOT be used to fabricate summary content — every field of the summary passed here must '
+      + 'trace to something concrete about the real project (an Epic goal, a source file/dir, a convention, a '
+      + 'git log entry). This tool re-validates the summary server-side and rejects with no writes on schema '
+      + 'failure, but it only checks shape, never truthfulness.',
+    exampleArgs: {
+      cwd: '/home/bilko/Projects/session-manager',
+      summary: { title: 'Example Project' },
+      picks: { home: { hero: 'variant-a' } },
+    },
+    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
+  },
+  {
+    name: 'project_home_status',
+    group: 'project-home',
+    purpose: "Report what already exists for this project's Project Home generation via the session-manager "
+      + "app's admin API — summary.json/picks.json/each lens file's existence + mtime, and manifest.json's "
+      + 'generatedAt.',
+    whenToUse: 'Use before starting generation to see prior state, and again after project_home_render to '
+      + 'confirm the new files landed.',
+    whenNotToUse: 'Do not treat an all-absent result as an error — a project that has never generated a '
+      + 'Project Home page yet still returns a well-formed status with every exists:false rather than failing.',
+    exampleArgs: { cwd: '/home/bilko/Projects/session-manager' },
+    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
+  },
   {
     name: 'session_manager_help',
     group: 'help',
@@ -263,6 +329,25 @@ const MCP_RECIPES = [
       'The call only delivers a PROPOSED session in the receiving project — nothing runs until a human there presses Approve & start; there is no reply channel.',
     ],
   },
+  {
+    id: 'generate-project-home',
+    title: "Generate a project's Project Home pages",
+    steps: [
+      "Call project_home_get_contract to get the protocol, ProjectPageSummary/ProjectPagePicks schemas, "
+        + 'component catalog, absolute output paths, and pipeline spec — the FIRST call any '
+        + 'project-home-builder session makes.',
+      'Author a ProjectPageSummary matching the contract\'s summarySchema — every field must trace to '
+        + 'something concrete about the real project; never fabricate content.',
+      'Call project_home_validate_summary with { cwd, summary } and fix every {field, message} error it '
+        + 'returns, re-validating until valid:true.',
+      "For each lens and slot in the contract's catalog, choose exactly one variant id by judging the "
+        + 'candidate variants against the summary you composed, assembling a ProjectPagePicks object '
+        + '(lensId -> slotId -> variantId).',
+      'Call project_home_render with { cwd, summary, picks } to render all 5 lenses and write '
+        + 'summary.json/picks.json/output files.',
+      "Call project_home_status to confirm the new files landed and read manifest.json's generatedAt.",
+    ],
+  },
 ];
 
 for (const entry of MCP_TOOL_CATALOG) {

package/src/main/lib/opsOwnership.cjs

@@ -48,6 +48,18 @@ const OWNERS = Object.freeze({
   'scheduler': 'scheduler',
   // Project Home owns the synthesized Brief (generate + hand-edit).
   'project-brief': 'project-home',
+  // Project Home also owns the app-side render path for Project Pages
+  // (summary.json/picks.json/output/* written via the
+  // /admin/project-home/render route, config.cjs's writeJson). This is a
+  // NARROWER claim than "project-home owns everything under this folder":
+  // the SAME folder is also written directly by a project-home-builder
+  // Epic's own Write tool, which never goes through config.cjs and so is
+  // NOT governed by this table at all (see
+  // session-manager-operations/project-pages/README.md). Declaring the
+  // namespace here only closes the fail-closed gap for the app's own write
+  // path — it does not claim exclusivity over the agent's Write-tool calls,
+  // which remain outside this law by construction.
+  'project-pages': 'project-home',
   // Structured per-tab error log lines (JSONL), tagged for tracing/analysis.
   'logs': 'logs',
   // Host on Bilko.run tab's deterministic bundle prep (dist/index.html +

package/src/main/lib/prdAgentType.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * prdAgentType.cjs — the PRD-frontmatter `agentType` FK, mirroring
+ * agentModelResolve.cjs's/epicMint.cjs's established convention for the
+ * Epic-level `agentType` FK: THROW ON WRITE, REPORT ON READ.
+ *
+ * A PRD's `agentType` names the persona (`~/.claude/agents/<name>.md`, or a
+ * project overlay at `<cwd>/.claude/agents/<name>.md`) that should execute
+ * it — distinct from `tag` (workTypeLibrary.cjs), which is the WORK TYPE.
+ * Reuses epicMint.cjs's personaFileExists/resolvePersonaPaths rather than a
+ * second persona-file reader, and agentLibrary.cjs's listPersonas() for the
+ * "available personas" name list surfaced in the write-time rejection error.
+ */
+
+const { personaFileExists, resolvePersonaPaths } = require('./epicMint.cjs');
+const { listPersonas } = require('../agentLibrary.cjs');
+
+/** PRD execution's documented default persona (dev-lead.md's own frontmatter role). */
+const DEFAULT_PRD_AGENT_TYPE = 'dev-lead';
+
+// READ side of the FK — logged at most once per (cwd, agentType) so a hot
+// reconcile/list pass re-parsing the same on-disk PRD every tick doesn't
+// flood opsErrorLog's daily file. Mirrors agentModelResolve.cjs's
+// loggedDanglingPersonas set.
+const loggedDanglingAgentTypes = new Set();
+
+/**
+ * Read-time tolerance check: a PRD on disk whose persona was renamed or
+ * deleted after the PRD was written must still load. Never throws — logs at
+ * most once via opsErrorLog when `agentType` is set but unresolvable.
+ */
+function reportDanglingAgentTypeOnce(cwd, agentType, deps = {}) {
+  if (!cwd || !agentType) return;
+  try {
+    const checkPersonaExists = deps.personaExists || personaFileExists;
+    if (checkPersonaExists(cwd, agentType, deps)) return;
+    const key = `${cwd}::${agentType}`;
+    if (loggedDanglingAgentTypes.has(key)) return;
+    loggedDanglingAgentTypes.add(key);
+    // Required lazily, same rationale as agentModelResolve.cjs's
+    // logDanglingPersonaOnce: pay for this leaf module only on the (rare)
+    // miss path.
+    const { appendError } = require('./opsErrorLog.cjs');
+    appendError({
+      cwd,
+      scope: 'prdAgentType',
+      level: 'warn',
+      message: `PRD agentType '${agentType}' has no resolvable persona file — PRD still loads`,
+      meta: { agentType },
+    });
+  } catch { /* logging must never break PRD loading */ }
+}
+
+/**
+ * Write-time FK check: throws when `agentType` is supplied but doesn't
+ * resolve to a readable persona file, naming the available personas (from
+ * the Agent Library) so the caller can pick a real one. A no-op when
+ * `agentType` is falsy — the caller is expected to default it separately
+ * (buildPrdBody's DEFAULT_PRD_AGENT_TYPE fill-in).
+ */
+async function assertAgentTypeWritable(cwd, agentType, deps = {}) {
+  if (!agentType) return;
+  const checkPersonaExists = deps.personaExists || personaFileExists;
+  if (checkPersonaExists(cwd, agentType, deps)) return;
+
+  const load = deps.listPersonas || listPersonas;
+  let available = [];
+  try {
+    available = (await load()).map((p) => p.name).filter(Boolean).sort();
+  } catch { /* best-effort — still throw below even if listing failed */ }
+
+  const { projectPath, globalPath } = resolvePersonaPaths(cwd, agentType, deps);
+  throw new Error(
+    `agentType '${agentType}' does not resolve to a readable persona file — checked ${projectPath} and `
+    + `${globalPath}. Available personas: ${available.length ? available.join(', ') : '(none found)'}`,
+  );
+}
+
+module.exports = {
+  DEFAULT_PRD_AGENT_TYPE,
+  assertAgentTypeWritable,
+  reportDanglingAgentTypeOnce,
+};