claude-code-session-manager 0.75.3 → 0.77.0

package/src/main/lib/__tests__/schedulerMcpServerProjectHome.test.cjs

@@ -0,0 +1,350 @@
+/**
+ * schedulerMcpServerProjectHome.test.cjs — the four project_home_* MCP
+ * tools (PRD: project-home-mcp-tools) that wrap PRD 1089's admin routes.
+ * Covers: presence in TOOLS, catalog-composed descriptions, correct
+ * route/payload dispatch via a stubbed admin HTTP server, cwd defaulting to
+ * SM_PROJECT_ROOT/process.cwd() when omitted, the app-not-running failure
+ * shape, and that project_home_get_contract's composed response is
+ * self-sufficient (mentions all 5 lens ids, no repo-relative path).
+ *
+ * Same HOME-repointing pattern as schedulerMcpServerHelp.test.cjs — see that
+ * file's header for why.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/schedulerMcpServerProjectHome.test.cjs
+ */
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const http = require('node:http');
+const os = require('node:os');
+const path = require('node:path');
+
+const SERVER_PATH = path.join(__dirname, '../../../../scripts/scheduler-mcp-server.cjs');
+const { MCP_TOOL_CATALOG, composeDescription } = require('../mcpToolCatalog.cjs');
+
+const PROJECT_HOME_TOOL_NAMES = [
+  'project_home_get_contract',
+  'project_home_validate_summary',
+  'project_home_render',
+  'project_home_status',
+];
+
+const tmpDirs = [];
+const servers = [];
+let originalHome;
+let originalProjectRoot;
+
+afterEach(async () => {
+  if (originalHome !== undefined) {
+    process.env.HOME = originalHome;
+    originalHome = undefined;
+  }
+  if (originalProjectRoot !== undefined) {
+    if (originalProjectRoot === null) delete process.env.SM_PROJECT_ROOT;
+    else process.env.SM_PROJECT_ROOT = originalProjectRoot;
+    originalProjectRoot = undefined;
+  }
+  delete require.cache[require.resolve(SERVER_PATH)];
+  while (servers.length) {
+    const s = servers.pop();
+    await new Promise((resolve) => s.close(resolve));
+  }
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkTmp() {
+  const d = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-mcp-project-home-'));
+  tmpDirs.push(d);
+  return d;
+}
+
+/** Starts a fake admin HTTP server that records every request and answers with `body`. */
+function startFakeAdminServer(token, body) {
+  const requests = [];
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      const chunks = [];
+      req.on('data', (c) => chunks.push(c));
+      req.on('end', () => {
+        if (req.headers.authorization !== `Bearer ${token}`) {
+          res.writeHead(401, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'bad token' }));
+          return;
+        }
+        const raw = Buffer.concat(chunks).toString('utf8');
+        requests.push({
+          method: req.method,
+          url: req.url,
+          body: raw ? JSON.parse(raw) : undefined,
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(body));
+      });
+    });
+    server.listen(0, '127.0.0.1', () => resolve({ server, requests }));
+  });
+}
+
+function requireServerWithHome(homeDir) {
+  originalHome = process.env.HOME;
+  process.env.HOME = homeDir;
+  delete require.cache[require.resolve(SERVER_PATH)];
+  const mod = require(SERVER_PATH);
+  process.env.HOME = originalHome;
+  originalHome = undefined;
+  return mod;
+}
+
+async function writeAdminConfig(homeDir, { port, token }) {
+  const tokenPath = path.join(homeDir, '.claude', 'session-manager', 'admin-api.json');
+  await fsp.mkdir(path.dirname(tokenPath), { recursive: true });
+  await fsp.writeFile(tokenPath, JSON.stringify({ port, token }), 'utf8');
+}
+
+function callTool(handleCallTool, name, args) {
+  return handleCallTool({ params: { name, arguments: args } });
+}
+
+test('all four project_home_* tools are present in TOOLS with correct input schemas', async () => {
+  const homeDir = await mkTmp();
+  const { TOOLS } = requireServerWithHome(homeDir);
+  for (const name of PROJECT_HOME_TOOL_NAMES) {
+    const tool = TOOLS.find((t) => t.name === name);
+    expect(tool).toBeTruthy();
+    expect(tool.inputSchema.type).toBe('object');
+    expect(tool.inputSchema.properties.cwd).toBeTruthy();
+    // cwd is never required on any of the four
+    expect(tool.inputSchema.required ?? []).not.toContain('cwd');
+  }
+  const validate = TOOLS.find((t) => t.name === 'project_home_validate_summary');
+  expect(validate.inputSchema.required).toContain('summary');
+  const render = TOOLS.find((t) => t.name === 'project_home_render');
+  expect(render.inputSchema.required).toEqual(expect.arrayContaining(['summary', 'picks']));
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s description equals the catalog-composed string', async (name) => {
+  const homeDir = await mkTmp();
+  const { TOOLS } = requireServerWithHome(homeDir);
+  const tool = TOOLS.find((t) => t.name === name);
+  const entry = MCP_TOOL_CATALOG.find((e) => e.name === name);
+  expect(entry).toBeTruthy();
+  expect(entry.group).toBe('project-home');
+  expect(tool.description).toBe(composeDescription(entry));
+});
+
+test('project_home_get_contract dispatches GET /admin/project-home/contract with cwd query param', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    protocol: ['step one'],
+    catalog: { lenses: [{ id: 'home' }, { id: 'marketing' }, { id: 'feature' }, { id: 'architecture' }, { id: 'brief' }] },
+    paths: { summaryPath: '/abs/summary.json', picksPath: '/abs/picks.json', outputDir: '/abs/output' },
+    spec: { text: 'spec text', path: '/abs/spec.md' },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_get_contract', { cwd: '/home/bilko/Projects/session-manager' });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('GET');
+  expect(requests[0].url).toBe('/admin/project-home/contract?cwd=%2Fhome%2Fbilko%2FProjects%2Fsession-manager');
+});
+
+test('project_home_get_contract composed response mentions all 5 lens ids and no repo-relative path', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server } = await startFakeAdminServer(token, {
+    ok: true,
+    protocol: [
+      'Call GET /admin/project-home/status?cwd=<abs> first.',
+      'Compose a ProjectPageSummary matching summarySchema.',
+      'For each lens in catalog.lenses, pick a variant per slot.',
+      'POST /admin/project-home/validate-summary with {cwd, summary}.',
+      'POST /admin/project-home/render with {cwd, summary, picks}.',
+    ],
+    summarySchema: { type: 'object' },
+    picksSchema: { type: 'object' },
+    catalog: {
+      lenses: [
+        { id: 'home', slots: [] },
+        { id: 'marketing', slots: [] },
+        { id: 'feature', slots: [] },
+        { id: 'architecture', slots: [] },
+        { id: 'brief', slots: [] },
+      ],
+    },
+    paths: { summaryPath: '/abs/project-pages/summary.json', picksPath: '/abs/project-pages/picks.json', outputDir: '/abs/project-pages/output' },
+    spec: { text: 'This project uses absolute paths only, never repo-relative ones.', path: '/abs/project-pages-pipeline.md' },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_get_contract', {});
+  expect(result.isError).toBeFalsy();
+  const text = result.content[0].text;
+  for (const lens of ['home', 'marketing', 'feature', 'architecture', 'brief']) {
+    expect(text).toContain(lens);
+  }
+  expect(text).not.toMatch(/session-manager-operations\/architecture\//);
+  expect(text).not.toMatch(/\.claude\/agents\//);
+});
+
+test('project_home_validate_summary dispatches POST /admin/project-home/validate-summary with cwd+summary', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, { ok: true, valid: true, errors: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const summary = { title: 'Example Project' };
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary,
+  });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('POST');
+  expect(requests[0].url).toBe('/admin/project-home/validate-summary');
+  expect(requests[0].body).toEqual({ cwd: '/home/bilko/Projects/session-manager', summary });
+});
+
+test('project_home_validate_summary surfaces per-field errors from the route, not a generic failure', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server } = await startFakeAdminServer(token, {
+    ok: true,
+    valid: false,
+    errors: [{ field: 'quotes[0].attribution', message: 'quotes[0].attribution must not be a placeholder value' }],
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary: { title: 'x', quotes: [{ attribution: 'TODO' }] },
+  });
+  expect(result.isError).toBeFalsy();
+  const body = JSON.parse(result.content[0].text);
+  expect(body.valid).toBe(false);
+  expect(body.errors).toEqual([
+    { field: 'quotes[0].attribution', message: 'quotes[0].attribution must not be a placeholder value' },
+  ]);
+});
+
+test('project_home_validate_summary requires summary', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_validate_summary', { cwd: '/x' });
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('summary');
+});
+
+test('project_home_render dispatches POST /admin/project-home/render with cwd+summary+picks', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    filesWritten: ['/abs/summary.json'],
+    generatedAt: '2026-09-01T00:00:00.000Z',
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const summary = { title: 'Example Project' };
+  const picks = { home: { hero: 'variant-a' } };
+  const result = await callTool(handleCallTool, 'project_home_render', {
+    cwd: '/home/bilko/Projects/session-manager',
+    summary,
+    picks,
+  });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('POST');
+  expect(requests[0].url).toBe('/admin/project-home/render');
+  expect(requests[0].body).toEqual({ cwd: '/home/bilko/Projects/session-manager', summary, picks });
+});
+
+test('project_home_render requires both summary and picks', async () => {
+  const homeDir = await mkTmp();
+  const { handleCallTool } = requireServerWithHome(homeDir);
+
+  const missingSummary = await callTool(handleCallTool, 'project_home_render', { picks: {} });
+  expect(missingSummary.isError).toBe(true);
+  expect(missingSummary.content[0].text).toContain('summary');
+
+  const missingPicks = await callTool(handleCallTool, 'project_home_render', { summary: {} });
+  expect(missingPicks.isError).toBe(true);
+  expect(missingPicks.content[0].text).toContain('picks');
+});
+
+test('project_home_status dispatches GET /admin/project-home/status with cwd query param', async () => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, {
+    ok: true,
+    summary: { exists: false, mtimeMs: null },
+    picks: { exists: false, mtimeMs: null },
+    output: {
+      home: { exists: false, mtimeMs: null },
+      marketing: { exists: false, mtimeMs: null },
+      feature: { exists: false, mtimeMs: null },
+      architecture: { exists: false, mtimeMs: null },
+      brief: { exists: false, mtimeMs: null },
+    },
+    manifest: { exists: false, generatedAt: null },
+  });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const result = await callTool(handleCallTool, 'project_home_status', { cwd: '/home/bilko/Projects/session-manager' });
+  expect(result.isError).toBeFalsy();
+  expect(requests).toHaveLength(1);
+  expect(requests[0].method).toBe('GET');
+  expect(requests[0].url).toBe('/admin/project-home/status?cwd=%2Fhome%2Fbilko%2FProjects%2Fsession-manager');
+
+  // Never-generated project: well-formed all-absent result, not an error.
+  const body = JSON.parse(result.content[0].text);
+  expect(body.ok).toBe(true);
+  expect(body.summary.exists).toBe(false);
+  expect(body.manifest.exists).toBe(false);
+  expect(body.output.brief.exists).toBe(false);
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s defaults cwd to SM_PROJECT_ROOT when omitted', async (name) => {
+  const homeDir = await mkTmp();
+  const token = 'test-token';
+  const { server, requests } = await startFakeAdminServer(token, { ok: true, valid: true, errors: [] });
+  servers.push(server);
+  await writeAdminConfig(homeDir, { port: server.address().port, token });
+
+  originalProjectRoot = process.env.SM_PROJECT_ROOT ?? null;
+  process.env.SM_PROJECT_ROOT = '/home/bilko/Projects/session-manager/session-manager-operations/scheduler/epics/some-epic/worktree';
+
+  const { handleCallTool } = requireServerWithHome(homeDir);
+  const args = name === 'project_home_render' ? { summary: {}, picks: {} } : name === 'project_home_validate_summary' ? { summary: {} } : {};
+  await callTool(handleCallTool, name, args);
+  expect(requests).toHaveLength(1);
+  const encoded = requests[0].body?.cwd ?? new URLSearchParams(requests[0].url.split('?')[1]).get('cwd');
+  expect(encoded).toBe(process.env.SM_PROJECT_ROOT);
+});
+
+test.each(PROJECT_HOME_TOOL_NAMES)('%s returns the app-not-running error when the admin API is unreachable', async (name) => {
+  const homeDir = await mkTmp();
+  const { handleCallTool, NOT_RUNNING_ERROR } = requireServerWithHome(homeDir);
+  const args = name === 'project_home_render' ? { summary: {}, picks: {} } : name === 'project_home_validate_summary' ? { summary: {} } : {};
+  const result = await callTool(handleCallTool, name, args);
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toBe(NOT_RUNNING_ERROR);
+});

package/src/main/lib/activeIndexMerge.cjs

@@ -36,6 +36,7 @@
 const path = require('path');
 const { activeIndexPath, withPathLock } = require('./epicMint.cjs');
 const config = require('../config.cjs');
+const { mirrorEpicStatus } = require('./epicStatusMirror.cjs');
 
 function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
@@ -160,6 +161,20 @@ async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events:
     // payload, so a compromised/forged renderer call can't claim a
     // different writer id.
     await config.writeJson(filePath, index, { writer: 'epics' });
+    // Status mirror (epicStatusMirror.cjs) — this IPC handler is the
+    // renderer-driven persist path (persistActiveIndex), the write site for
+    // both the 'proposed'->'active' start transition (approveProposed) and
+    // every other in-place session mutation. Mirrors every surviving row so
+    // a lost/clobbered active-index.json can be reconstructed from these
+    // files (activeIndexRebuild.cjs). Best-effort per row: one bad write must
+    // not undo the index write that already landed above.
+    for (const [id, sess] of Object.entries(mergedSessions)) {
+      try {
+        mirrorEpicStatus(cwd, id, { session: sess, status: sess.status });
+      } catch (e) {
+        console.warn(`[activeIndexMerge] mirrorEpicStatus failed for ${id}`, e);
+      }
+    }
     return { sessions: mergedSessions, events: mergedEvents };
   });
 }

package/src/main/lib/activeIndexRebuild.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * activeIndexRebuild.cjs — reconstructs `active-index.json` from the
+ * per-Epic status mirrors `epicStatusMirror.cjs` writes onto `prompt-
+ * sessions/<epicId>.json`. This is the recovery path for the incident the
+ * mirror exists to survive: a lost, clobbered, git-reverted, or
+ * worktree-snapshotted index that would otherwise silently erase every open
+ * Epic it held with no way to get them back.
+ *
+ * Rebuild NEVER mints — SINGLE-CREATOR LAW (epicMint.cjs) is untouched
+ * because no new Epic id is ever created here, only rows for ids that
+ * already have a mirrored file re-materialized. It also never resurrects a
+ * tombstoned or archived Epic (see the two "never resurrect" guards below) —
+ * a human's delete/complete decision always wins.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { activeIndexPath, readActiveIndex, writeActiveIndex, withPathLock } = require('./epicMint.cjs');
+
+function promptSessionsDir(cwd) {
+  const { opsPath } = require('./opsOwnership.cjs');
+  return opsPath(cwd, 'prompt-sessions');
+}
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function listMirrorFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter((f) => f.endsWith('.json') && f !== 'active-index.json');
+}
+
+/**
+ * rebuildActiveIndex(cwd, { dryRun? }) → { rows, skipped, reasons }
+ *
+ * `rows` — reconstructed PromptSession objects, one per mirrored file that
+ *   is a live (proposed/active), non-tombstoned, non-archived Epic. These
+ *   become the new `sessions` map (dryRun: false is the default — pass
+ *   `{ dryRun: true }` to preview without writing).
+ * `skipped` — file names not turned into a row.
+ * `reasons` — `{ [fileName]: humanReadableReason }`, one entry per skipped
+ *   file. A file is never guessed at: no mirrored `status` is a skip, not a
+ *   fabricated 'unknown' row (see scripts/mirror-epic-status.cjs for the
+ *   only place that vocabulary is deliberately introduced, for the
+ *   migration's own back-fill bookkeeping).
+ *
+ * `events` and `tombstones` from the existing on-disk index (if any) are
+ * carried through completely untouched — this function only ever
+ * reconstructs `sessions`.
+ */
+function rebuildActiveIndex(cwd, { dryRun = false } = {}) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('rebuildActiveIndex: cwd is required');
+  cwd = path.resolve(cwd);
+  return withPathLock(activeIndexPath(cwd), () => {
+    const dir = promptSessionsDir(cwd);
+    const existing = readActiveIndex(cwd);
+    const tombstones = existing.tombstones || {};
+    const files = listMirrorFiles(dir);
+
+    const rows = [];
+    const skipped = [];
+    const reasons = {};
+
+    for (const file of files) {
+      const id = file.slice(0, -'.json'.length);
+      const full = path.join(dir, file);
+      let parsed;
+      try {
+        parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+      } catch (e) {
+        skipped.push(file);
+        reasons[file] = `unreadable: ${e.message}`;
+        continue;
+      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        skipped.push(file);
+        reasons[file] = 'unreadable: not a JSON object';
+        continue;
+      }
+      // Never resurrected — a tombstoned id stays out even if its file says
+      // 'active' (see activeIndexMerge.cjs's header on why tombstones are
+      // never auto-cleared).
+      if (hasOwn(tombstones, id)) {
+        skipped.push(file);
+        reasons[file] = 'tombstoned — never resurrected by a rebuild';
+        continue;
+      }
+      if (!parsed.status) {
+        skipped.push(file);
+        reasons[file] = 'no status mirror on this file — never guessed at';
+        continue;
+      }
+      // A completed archive (markCompleted's PromptSessionArchive, or any
+      // mirror written after archival) is never restored as a live row.
+      if (parsed.archivedAt) {
+        skipped.push(file);
+        reasons[file] = 'archivedAt is set — completed Epic, not a live row';
+        continue;
+      }
+      if (parsed.status !== 'proposed' && parsed.status !== 'active') {
+        skipped.push(file);
+        reasons[file] = `status '${parsed.status}' is not a live row`;
+        continue;
+      }
+      // Drop mirror-only bookkeeping (`indexedAt`) — it is not part of the
+      // PromptSession shape active-index.json's `sessions` map holds.
+      const { indexedAt, archivedAt, ...row } = parsed;
+      rows.push({ ...row, id, cwd: parsed.cwd || cwd });
+    }
+
+    if (!dryRun) {
+      const sessions = {};
+      for (const row of rows) sessions[row.id] = row;
+      writeActiveIndex(cwd, {
+        sessions,
+        events: existing.events || {},
+        tombstones,
+      });
+    }
+
+    return { rows, skipped, reasons };
+  });
+}
+
+module.exports = { rebuildActiveIndex };

package/src/main/lib/agentModelResolve.cjs

@@ -120,9 +120,67 @@ function resolveEpicModel({ cwd, claudeSessionId, fallbackModel = FALLBACK_MODEL
   }
 }
 
+/** Mirrors epicIntake.ts's AGENT_BODY_CHAR_CAP — a runaway persona file must
+ *  not be able to dominate a spawned job's system prompt either. Duplicated
+ *  rather than imported: epicIntake.ts is a renderer module (no ES modules
+ *  in main). */
+const AGENT_BODY_CHAR_CAP = 6000;
+
+/** Trims a persona's frontmatter-stripped body and caps it at
+ *  AGENT_BODY_CHAR_CAP, appending a truncation notice naming `personaPath`
+ *  — same shape as epicIntake.ts's buildPersonaBodyText. Returns null for an
+ *  empty body. */
+function buildPersonaBodyText(rawBody, personaPath) {
+  const body = (rawBody || '').trim();
+  if (!body) return null;
+  if (body.length <= AGENT_BODY_CHAR_CAP) return body;
+  const truncated = body.slice(0, AGENT_BODY_CHAR_CAP);
+  const pathLabel = personaPath || 'the persona file';
+  return `${truncated}\n\n[Truncated — ${pathLabel} exceeds ${AGENT_BODY_CHAR_CAP} characters; see the file for the full body.]`;
+}
+
+/**
+ * Resolves the persona system-prompt + model a scheduled PRD's `agentType`
+ * should launch its headless `claude -p` spawn with. Never throws — a
+ * missing agentType, or one that no longer resolves to a readable persona
+ * file (renamed/deleted), falls back to `{ systemPrompt: null, model:
+ * fallbackModel, personaPath: null }` and logs once via prdAgentType.cjs's
+ * reportDanglingAgentTypeOnce (the PRD-frontmatter FK's own dangling-read
+ * convention) — a dangling persona must never park or fail the job.
+ *
+ * Reuses agentLibrary.cjs's getPersonaBody (project-overlay-then-global
+ * read, same precedence resolvePersonaPaths documents) rather than a second
+ * persona-file reader, and this module's own frontmatter-stripped-body cap
+ * (mirroring epicIntake.ts's Epic-path treatment) so the PRD path gets the
+ * same runaway-file protection.
+ *
+ * @param {{ cwd: string, agentType: string|null, fallbackModel?: string, deps?: object }} opts
+ * @returns {Promise<{ model: string, systemPrompt: string|null, personaPath: string|null }>}
+ */
+async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLBACK_MODEL, deps = {} } = {}) {
+  const miss = { model: fallbackModel, systemPrompt: null, personaPath: null };
+  if (!agentType) return miss;
+  try {
+    const getBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
+    const persona = await getBody({ cwd, name: agentType });
+    if (!persona) {
+      const reportOnce = deps.reportDanglingAgentTypeOnce || require('./prdAgentType.cjs').reportDanglingAgentTypeOnce;
+      reportOnce(cwd, agentType, deps);
+      return miss;
+    }
+    const { fm, body } = splitFrontmatter(persona.text);
+    const model = fm.model && fm.model !== 'inherit' ? fm.model : fallbackModel;
+    const systemPrompt = buildPersonaBodyText(body, persona.path);
+    return { model, systemPrompt, personaPath: persona.path };
+  } catch {
+    return miss;
+  }
+}
+
 module.exports = {
   FALLBACK_MODEL,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
   readPersonaModel,
+  resolvePrdPersonaForSpawn,
 };

package/src/main/lib/buildTarget.cjs

@@ -30,7 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const BUILD_TARGET_SUBPATH = ['session-manager-operations', 'architecture', 'build-target.json'];
+const BUILD_TARGET_SUBPATH = ['architecture', 'build-target.json']; // joined under opsOwnership.opsPath
 
 function readJson(filePath) {
   try {
@@ -48,7 +48,8 @@ function readJson(filePath) {
 function resolveBuildTarget(cwd) {
   if (!cwd || typeof cwd !== 'string') return null;
 
-  const configPath = path.join(cwd, ...BUILD_TARGET_SUBPATH);
+  const { opsPath } = require('./opsOwnership.cjs');
+  const configPath = opsPath(cwd, ...BUILD_TARGET_SUBPATH);
   const explicit = readJson(configPath);
   if (explicit && typeof explicit === 'object' && !Array.isArray(explicit) && typeof explicit.packageName === 'string') {
     return explicit;