claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/health.cjs

@@ -9,13 +9,16 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { execFileSync } = require('node:child_process');
-const { POLL_INTERVAL_MS } = require('./lib/schedulerConfig.cjs');
+const { POLL_INTERVAL_MS, loadGateThreshold } = require('./lib/schedulerConfig.cjs');
+const { opsPath } = require('./lib/opsOwnership.cjs');
 const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
+const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
 const { computeStallSummary } = require('./scheduler.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
+const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -225,6 +228,113 @@ function evaluatePrdMigrationHealth(migrationResult, legacyPrdsDir) {
   };
 }
 
+// Pure shaping of checkDelegationReadiness()'s result (delegationReadiness.cjs)
+// into a health component + issue lines — kept separate from the fs-touching
+// check() call site so it's directly unit-testable, matching
+// evaluatePrdMigrationHealth's pattern. delegationReadiness.cjs already wraps
+// every filesystem read (readJsonSafe / try-catch), so a missing/unreadable
+// config surfaces here as one of `checks` with ok:false, never a throw.
+function evaluateDelegationChainHealth(delegationResult) {
+  const component = { ok: delegationResult.ok, checks: delegationResult.checks };
+  const issues = delegationResult.checks
+    .filter((c) => !c.ok)
+    .map((c) => `Delegation readiness: ${c.label} failed — ${c.detail}${c.fix ? ` (fix: ${c.fix})` : ''}`);
+  return { component, issues };
+}
+
+// computeEpicIndexDrift(cwd) → { orphan_rows, orphan_files, unmirrored,
+//   orphanRowIds, orphanFileIds, unmirroredFiles }
+//
+// One project's drift between active-index.json (the index) and prompt-
+// sessions/<id>.json (the status mirror epicStatusMirror.cjs writes on every
+// status-changing write path). Pure filesystem read, never throws — an
+// unreadable index or prompt-sessions dir degrades to empty rather than
+// aborting the whole health check (matches evaluatePrdMigrationHealth's
+// fail-open-on-read spirit).
+function computeEpicIndexDrift(cwd) {
+  let dir;
+  try {
+    dir = opsPath(cwd, 'prompt-sessions');
+  } catch {
+    return { orphan_rows: 0, orphan_files: 0, unmirrored: 0 }; // unusable cwd degrades to empty, same as an unreadable index below
+  }
+  const indexPath = path.join(dir, 'active-index.json');
+  let sessions = {};
+  let tombstones = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    sessions = parsed && typeof parsed.sessions === 'object' && parsed.sessions ? parsed.sessions : {};
+    tombstones = parsed && typeof parsed.tombstones === 'object' && parsed.tombstones ? parsed.tombstones : {};
+  } catch { /* missing/unreadable index — treat as empty, not a throw */ }
+
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') && f !== 'active-index.json');
+  } catch { /* prompt-sessions/ doesn't exist yet — nothing to compare */ }
+
+  const fileIds = new Set(files.map((f) => f.slice(0, -'.json'.length)));
+  const orphanRowIds = Object.keys(sessions).filter((id) => !fileIds.has(id));
+
+  const orphanFileIds = [];
+  const unmirroredFiles = [];
+  for (const file of files) {
+    const id = file.slice(0, -'.json'.length);
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    } catch {
+      continue; // unreadable file — neither orphan nor unmirrored classification applies
+    }
+    if (!parsed || typeof parsed !== 'object' || !parsed.status) {
+      unmirroredFiles.push(file);
+      continue;
+    }
+    const looksLive = (parsed.status === 'proposed' || parsed.status === 'active') && !parsed.archivedAt;
+    const hasRow = Object.prototype.hasOwnProperty.call(sessions, id);
+    const isTombstoned = Object.prototype.hasOwnProperty.call(tombstones, id);
+    if (looksLive && !hasRow && !isTombstoned) orphanFileIds.push(file);
+  }
+
+  return {
+    orphan_rows: orphanRowIds.length,
+    orphan_files: orphanFileIds.length,
+    unmirrored: unmirroredFiles.length,
+    orphanRowIds,
+    orphanFileIds,
+    unmirroredFiles,
+  };
+}
+
+// evaluateEpicIndexHealth(cwds) → { component, issues }
+//
+// Shapes computeEpicIndexDrift's per-project result into a health component +
+// issue lines, matching evaluateDelegationChainHealth's pattern. Only
+// orphan_rows (an index row whose Epic file is gone — the actual data-loss
+// signal) is an issue; orphan_files and unmirrored are informational drift,
+// not failures — a fresh install or an Epic mid-migration legitimately has
+// unmirrored files.
+function evaluateEpicIndexHealth(cwds) {
+  const byProject = {};
+  const issues = [];
+  let anyOrphanRows = false;
+  for (const cwd of cwds) {
+    const drift = computeEpicIndexDrift(cwd);
+    byProject[cwd] = {
+      orphan_rows: drift.orphan_rows,
+      orphan_files: drift.orphan_files,
+      unmirrored: drift.unmirrored,
+    };
+    if (drift.orphan_rows > 0) {
+      anyOrphanRows = true;
+      issues.push(
+        `Epic index drift: ${cwd} has ${drift.orphan_rows} active-index.json row(s) with no matching `
+        + `prompt-sessions/<id>.json file (${drift.orphanRowIds.join(', ')})`
+      );
+    }
+  }
+  return { component: { ok: !anyOrphanRows, byProject }, issues };
+}
+
 async function check() {
   const start = Date.now();
   const status = {
@@ -340,6 +450,15 @@ async function check() {
       byProject: computeProjectProblemCounts(queueState.jobs),
       perProjectStall,
       tickLiveness: liveness.reason,
+      // Informational only (PRD 1085): current 1-min loadavg per core vs the
+      // launch-gate threshold, so a "nothing is launching" report can be
+      // read next to the reason without opening the app.
+      loadRatio: (() => {
+        const cores = (os.cpus() || []).length;
+        const l1 = os.loadavg()[0];
+        return cores > 0 && Number.isFinite(l1) ? Number((l1 / cores).toFixed(3)) : null;
+      })(),
+      loadGateThreshold: loadGateThreshold(),
     };
     if (liveness.stalled) {
       const ageMin = Math.round(liveness.tickAgeMs / 60_000);
@@ -505,6 +624,22 @@ async function check() {
     }
   }
 
+  // 6.55. Delegation-chain readiness — answers "can this machine actually
+  // delegate work to the scheduler?" (see delegationReadiness.cjs's header:
+  // when the scheduler MCP isn't registered, scheduler_create_prd is simply
+  // absent from the agent's tool list — no error to catch, so an agent asked
+  // to delegate just implements inline instead). Critical: a failing check
+  // here means Epics silently stop queueing PRDs on this machine.
+  try {
+    const delegation = await checkDelegationReadiness({ cwd: PROJECT_ROOT });
+    const { component, issues: delegationIssues } = evaluateDelegationChainHealth(delegation);
+    status.components.delegation_chain = component;
+    status.issues.push(...delegationIssues);
+  } catch (e) {
+    status.components.delegation_chain = { ok: false, error: e.message };
+    status.issues.push(`Delegation readiness check failed: ${e.message}`);
+  }
+
   // 6.6. Run-log retention report (informational only — never blocks health).
   // Read-only against the REAL scheduled-plans/runs/ dir: reports current
   // usage + what the configured policy (if any) would remove. Nothing is
@@ -536,11 +671,24 @@ async function check() {
     status.components.run_log_retention = { ok: true, error: e.message };
   }
 
+  // 6.65. Epic index drift — orphan_rows/orphan_files/unmirrored across every
+  // project this machine has ever opened (allProjectCwds, no recency filter
+  // — a quiet project still owns its Epics). See computeEpicIndexDrift's
+  // header.
+  try {
+    const { component, issues: epicIndexIssues } = evaluateEpicIndexHealth(allProjectCwds());
+    status.components.epic_index = component;
+    status.issues.push(...epicIndexIssues);
+  } catch (e) {
+    status.components.epic_index = { ok: false, error: e.message };
+    status.issues.push(`Epic index health check failed: ${e.message}`);
+  }
+
   // 7. Summary scoring: ok if all critical components pass.
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration', 'claude_md_budget'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -561,6 +709,9 @@ module.exports = {
   evaluateTickLiveness,
   readFreshHeartbeat,
   evaluatePrdMigrationHealth,
+  evaluateDelegationChainHealth,
+  computeEpicIndexDrift,
+  evaluateEpicIndexHealth,
   computeProjectProblemCounts,
   evaluatePerProjectStall,
   parseClaudeMdBudget,

package/src/main/index.cjs

@@ -27,6 +27,7 @@ const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
 const prdAdminRoutes = require('./lib/prdAdminRoutes.cjs');
+const projectHomeAdminRoutes = require('./lib/projectHomeAdminRoutes.cjs');
 const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
@@ -36,7 +37,8 @@ const epicWorktreeMint = require('./lib/epicWorktreeMint.cjs');
 const epicWorktreeMerge = require('./lib/epicWorktreeMerge.cjs');
 const epicWorktreeProjectConfig = require('./lib/epicWorktreeProjectConfig.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
-const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
+const { checkDelegationReadiness, installPrdWriteGuard } = require('./lib/delegationReadiness.cjs');
+const { MCP_TOOL_CATALOG, MCP_RECIPES } = require('./lib/mcpToolCatalog.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const crossProjectFeedback = require('./lib/crossProjectFeedback.cjs');
@@ -44,6 +46,7 @@ const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
 prdAdminRoutes.registerAdminRoute(adminHttp, scheduler.remote);
+projectHomeAdminRoutes.registerAdminRoute(adminHttp);
 chatRunner.registerAdminRoute(adminHttp);
 // Project-to-project feedback conduit — the app is the only process holding
 // several projects' operations roots open, so it performs the cross-folder
@@ -68,7 +71,7 @@ const schedulerConfig = require('./lib/schedulerConfig.cjs');
 const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
 const { registerProjectBriefIpc } = require('./projectBrief.cjs');
-const { registerProjectPagesIpc } = require('./projectPages.cjs');
+const { registerProjectPagesIpc, attachWindow: attachProjectPagesWindow, closeAllOutputWatchers: closeAllProjectPagesWatchers } = require('./projectPages.cjs');
 const { registerBilkoHostIpc } = require('./bilkoHost.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { computeEpicDelegationStats } = require('./lib/epicDelegationStats.cjs');
@@ -81,6 +84,9 @@ const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');
 const { openInEditor, openFileInEditor, openInFinder, openInTerminal } = require('./lib/openExternalApp.cjs');
+const { rebuildActiveIndex } = require('./lib/activeIndexRebuild.cjs');
+const { activeIndexPath: promptSessionsActiveIndexPath } = require('./lib/epicMint.cjs');
+const { allProjectCwds } = require('../../scripts/lib/activeSessions.cjs');
 
 let mainWindow = null;
 let rebooting = false;
@@ -296,6 +302,7 @@ function relaunchViaNpx() {
 async function rebootApp() {
   ptyManager.killAll();
   configMgr.closeAllWatchers();
+  closeAllProjectPagesWatchers();
   transcripts.closeAll();
   watchers.manager.killAll();
 
@@ -322,6 +329,7 @@ async function rebootApp() {
     chatRunner.attachWindow(mainWindow);
     promptSessionEvents.attachWindow(mainWindow);
     attachDocEditWindow(mainWindow);
+    attachProjectPagesWindow(mainWindow);
     rebooting = false;
     return;
   }
@@ -456,6 +464,11 @@ ipcMain.handle('app:launch-mode', () => ({
 // `claude mcp list`. Read-only, single in-flight call — no polling.
 ipcMain.handle('mcp:status', () => probeMcpStatus());
 
+// Project Home's "Agent tools" block (PhAgentTools): the same catalog data
+// GET /admin/mcp/catalog serves to external callers, read in-process here so
+// the renderer never makes a direct HTTP call. Static data, no cwd needed.
+ipcMain.handle('mcp:catalog', () => ({ ok: true, tools: MCP_TOOL_CATALOG, recipes: MCP_RECIPES }));
+
 // Agent Library nav page (Home face only): global `~/.claude/agents/*.md`
 // personas plus, per currently-open project tab, whether that project
 // overlays the same agent name at `<cwd>/.claude/agents/<name>.md`. Read-only.
@@ -494,12 +507,19 @@ ipcMain.handle('agents:get-persona-body', validated(schemas.agentsGetPersonaBody
   agentLibrary.getPersonaBody(payload)));
 
 // "Can this project actually delegate?" probe (PRD: delegation-readiness).
-// Structured data over the four preconditions for scheduler_create_prd being
-// in an agent's tool list at all — surfacing it in the UI is a sibling PRD.
-ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, (payload) =>
+// Structured data over the preconditions for scheduler_create_prd being in an
+// agent's tool list at all — surfacing it in the UI is a sibling PRD.
+ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, async (payload) =>
   checkDelegationReadiness(payload)
 ));
 
+// The one readiness check with a sanctioned one-press install. Session Manager
+// standardizes on the REFERENCE approach (absolute path to this repo's guard
+// script, never a vendored copy) — see installPrdWriteGuard's header.
+ipcMain.handle('app:install-prd-write-guard', validated(schemas.delegationReadinessCwd, (payload) =>
+  installPrdWriteGuard(payload)
+));
+
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 
 // Boot diagnostics — renderer polls these to surface toasts when `claude` isn't
@@ -1152,6 +1172,7 @@ app.whenReady().then(async () => {
   chatRunner.attachWindow(mainWindow);
   promptSessionEvents.attachWindow(mainWindow);
   attachDocEditWindow(mainWindow);
+  attachProjectPagesWindow(mainWindow);
   // 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
@@ -1193,6 +1214,42 @@ app.whenReady().then(async () => {
   seedSchedulerMcp({ logger: console, writeLog: logs.writeLine }).catch((e) => {
     logs.writeLine({ scope: 'seed-scheduler-mcp', level: 'error', message: 'seed failed', meta: { error: e?.message } });
   });
+  // Epic index self-heal: a project whose active-index.json is MISSING or
+  // fails to parse has lost every open Epic's status unless the per-Epic
+  // status mirror (epicStatusMirror.cjs) can rebuild it. Runs once per boot,
+  // fire-and-forget, and only touches a project whose index reads unclean —
+  // a clean index is never rewritten here. See activeIndexRebuild.cjs.
+  try {
+    for (const projectCwd of allProjectCwds()) {
+      const indexPath = promptSessionsActiveIndexPath(projectCwd);
+      let unclean = false;
+      let parseError = null;
+      if (!fs.existsSync(indexPath)) {
+        unclean = true;
+      } else {
+        try {
+          JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        } catch (e) {
+          unclean = true;
+          parseError = e.message;
+        }
+      }
+      if (!unclean) continue;
+      try {
+        const { rows, skipped } = rebuildActiveIndex(projectCwd);
+        logs.writeLine({
+          scope: 'active-index-rebuild',
+          level: 'info',
+          message: 'rebuilt active-index.json from status mirrors',
+          meta: { cwd: projectCwd, parseError, restored: rows.length, skipped: skipped.length },
+        });
+      } catch (e) {
+        logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'rebuild failed', meta: { cwd: projectCwd, error: e?.message } });
+      }
+    }
+  } catch (e) {
+    logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'boot sweep failed', meta: { error: e?.message } });
+  }
   // History rollup finalize pass: deferred 30s past boot so it never competes
   // with first-paint, fire-and-forget (cron/offline refresh is PRD 651 — this
   // is just the one-shot in-app pass).
@@ -1292,6 +1349,7 @@ app.on('window-all-closed', () => {
   if (rebooting) return; // new window is about to be created
   ptyManager.killAll();
   configMgr.closeAllWatchers();
+  closeAllProjectPagesWatchers();
   transcripts.closeAll();
   watchers.manager.killAll();
   if (process.platform !== 'darwin') app.quit();
@@ -1306,6 +1364,7 @@ app.on('before-quit', () => {
   supervisor.stopSupervisor();
   ptyManager.killAll();
   configMgr.closeAllWatchers();
+  closeAllProjectPagesWatchers();
   transcripts.closeAll();
   watchers.manager.killAll();
   adminHttp.stop().catch(() => {});

package/src/main/ipcSchemas.cjs

@@ -10,6 +10,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema, EpicIntakeSectionSchema } = require('./lib/promptSessionSchema.cjs');
 const { PrdWorkTypeSchema } = require('./lib/workTypeLibrary.cjs');
+const { PERSONA_NAME_RE } = require('./agentLibrary.cjs');
 const { AgentPersonaSaveSchema } = require('./lib/agentPersonaSchema.cjs');
 
 // ──────────────────────────────────────────── PTY
@@ -224,6 +225,12 @@ const promptSessionsMergeToMain = z.object({
   epicId: z.string().regex(PROMPT_SESSION_ID_RE),
   branch: z.string().regex(/^sm-epic\/[A-Za-z0-9_-]{1,64}$/),
   dir: z.string().min(1).max(4096),
+  // Base-tree WIP paths carried into this worktree at creation time
+  // (gitWorktree.cjs's createWorktree, PRD 1094) — threaded through so
+  // integrateEpicBranch can apply the same carried-wip-only skip the job
+  // path already gets. Absent on a worktree created before this field
+  // existed, or one whose base tree was clean at creation.
+  carriedPaths: z.array(z.string().min(1).max(4096)).max(2000).optional(),
 });
 
 // Renderer entry points for the per-project "disable Epic worktree
@@ -299,9 +306,21 @@ const PRD_CREATE_SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 // frontmatter-shaped lines into the body. Block newlines at the boundary
 // instead of trying to escape them later.
 const NO_NEWLINE_RE = /^[^\r\n]*$/;
+// WHO executes a PRD — a persona name (agentLibrary.cjs's PERSONA_NAME_RE),
+// distinct from `tag` (the WORK TYPE, above). Not a closed enum here: the
+// Agent Library is user-editable, so the actual FK check (does this name
+// resolve to a readable persona file) happens at write time in
+// prdCreate.cjs's createPrd via prdAgentType.cjs's assertAgentTypeWritable —
+// this schema only enforces the name SHAPE.
+const PrdAgentTypeSchema = z.string().regex(PERSONA_NAME_RE, 'agent name must be lowercase, hyphenated (e.g. "dev-lead")');
 const schedulerCreatePrd = z.object({
   title: z.string().min(1).max(200).regex(NO_NEWLINE_RE, 'must not contain newlines'),
-  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines'),
+  // Optional (PRD: worktree-cwd Epic-lookup hazard) — when omitted, prdCreate.cjs's
+  // createPrd resolves the real project cwd server-side via
+  // projectRootResolve.cjs's resolveProjectContext, using originClaudeSessionId/
+  // sourcePromptId/originProjectRoot. A call with none of those still fails with
+  // a clear "cwd is required" error.
+  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   estimateMinutes: z.number().int().min(1).max(100000),
   goal: z.string().min(1).max(20000),
   acceptanceCriteria: z.array(z.string().min(1).max(2000)).min(1).max(100),
@@ -333,6 +352,13 @@ const schedulerCreatePrd = z.object({
   // within an Epic's own chat session joins that Epic even if the tool call
   // forgot to pass sourcePromptId explicitly.
   originClaudeSessionId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // Trusted project-root hint (SM_PROJECT_ROOT env, stamped by chatRunner.cjs/
+  // pty.cjs/scheduler.cjs's job spawn onto the child that ultimately calls this
+  // route, forwarded by scheduler-mcp-server.cjs as originProjectRoot) — never
+  // written to frontmatter; projectRootResolve.cjs's resolveProjectContext
+  // treats it as a higher-priority hint than the caller-supplied cwd, but
+  // still loses to a resolved Epic's own project cwd.
+  originProjectRoot: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // User-selected work-type tag (PRD 774; independence from the parent
   // Epic's own tag confirmed PRD 1041) — deterministic, never LLM-classified.
   // Epic tag and PRD tag draw on the same WorkType vocabulary
@@ -340,11 +366,27 @@ const schedulerCreatePrd = z.object({
   // excluded here for the same reason adminPrdFrontmatterPatch excludes it
   // below — a discussion-tagged Epic never reaches PRD authoring.
   tag: PrdWorkTypeSchema.optional(),
+  // WHO executes this PRD (persona name, `~/.claude/agents/<name>.md`) —
+  // independent of `tag` above. Optional: prdCreate.cjs's buildPrdBody fills
+  // in DEFAULT_PRD_AGENT_TYPE ('dev-lead') when omitted.
+  agentType: PrdAgentTypeSchema.optional(),
+  // Opt-in exclusive-lease flag (PRD 1107): the scheduler dispatches this PRD
+  // only once zero other jobs are running machine-wide, and holds every other
+  // job off the whole session-slot pool while it runs — for a PRD whose
+  // acceptance criteria are wall-clock/timing measurements (frame time,
+  // performance fences) that CPU contention from sibling jobs would otherwise
+  // invalidate. See prdCreate.cjs's buildPrdBody and schedulerBatch.cjs's
+  // pickNextBatch.
+  quietMachine: z.boolean().optional(),
 });
 
 // Bulk archive: slug list, capped to limit unbounded retag/archive payloads.
+// Optional cwd narrows every slug's directory search to one project (same
+// role as scheduler_get_prd/scheduler_update_prd's cwd hint) — omitted, the
+// search still spans every candidate PRD dir machine-wide.
 const scheduleArchivePrd = z.object({
   slugs: z.array(z.string().regex(SCHEDULE_SLUG_RE)).min(1).max(500),
+  cwd: z.string().min(1).max(4096).optional(),
 });
 
 const scheduleRetagItem = z.object({
@@ -402,12 +444,17 @@ const adminPrdFrontmatterPatch = z.object({
   // discussion-tagged Epic never reaches PRD authoring) — see
   // workTypeLibrary.cjs's PrdWorkTypeSchema.
   tag: PrdWorkTypeSchema.optional(),
+  // WHO executes this PRD — patchable after creation too, same as `tag`.
+  agentType: PrdAgentTypeSchema.optional(),
   // Provenance stamp (PRD-authoring lockdown). Free-text rather than an enum
   // — 'scheduler-api' (create-time) and 'legacy-adopted' (migration/manual
   // adopt) are the two values this codebase writes today, but the field
   // itself is descriptive, not a closed set.
   createdVia: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   issuedAt: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // Opt-in exclusive-lease flag (PRD 1107) — patchable after creation too,
+  // same as every other recognized key here.
+  quietMachine: z.boolean().optional(),
 });
 
 const adminUpdatePrd = z.object({
@@ -425,6 +472,7 @@ const adminUpdatePrd = z.object({
 
 const adminCancelJob = z.object({
   slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
 });
 
 // ──────────────────────────────────────────── Projects
@@ -565,6 +613,23 @@ const projectPagesCwd = z.object({
   cwd: z.string().min(1).max(4096),
 }).strict();
 
+// ──────────────────────────────────────────── Project Home admin routes
+// (PRD: project-home-admin-routes). Same validation split as
+// projectPagesCwd above: real path validation is projectRootResolve.cjs +
+// config.cjs's validatePath at first fs access.
+const projectHomeAdminCwdQuery = z.object({
+  cwd: z.string().min(1).max(4096),
+}).strict();
+const projectHomeAdminValidateSummaryBody = z.object({
+  cwd: z.string().min(1).max(4096),
+  summary: z.unknown(),
+}).strict();
+const projectHomeAdminRenderBody = z.object({
+  cwd: z.string().min(1).max(4096),
+  summary: z.unknown(),
+  picks: z.unknown(),
+}).strict();
+
 // ──────────────────────────────────────────── Host on Bilko.run
 // Same validation split: real path validation is config.cjs's validatePath
 // at first fs access in bilkoHost.cjs — these schemas only bound wire shape.
@@ -973,6 +1038,9 @@ module.exports = {
     memoryStale,
     projectBriefCwd,
     projectPagesCwd,
+    projectHomeAdminCwdQuery,
+    projectHomeAdminValidateSummaryBody,
+    projectHomeAdminRenderBody,
     bilkoHostCwd,
     bilkoHostPrepareBundle,
     bilkoHostAddDocument,