claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/projectHomeAdminRoutes.cjs

@@ -1,25 +1,14 @@
 /**
- * projectHomeAdminRoutes.cjs — the app-side half of "the generating session
- * needs zero repo knowledge to build a Project Home page" (PRD:
- * project-home-admin-routes). Before this file, the project-home-builder
- * Epic had to know session-manager's own repo layout (where the catalog
- * lives, how to invoke the validator/renderer CLIs, which build step to run
- * first) — which is exactly why generation silently hung on a foreign
- * machine with no repo checked out. These four routes make the app itself
- * the authority on paths/schema/catalog/rendering, reusing the shipped
- * assets PRD 1088 put in the npm tarball (scripts/render-project-pages/dist/
- * renderer.cjs, scripts/project-pages-logic/dist/logic.cjs,
- * src/main/templates/project-pages-catalog.json,
- * src/main/templates/project-pages-pipeline.md) rather than reimplementing
- * any of them.
+ * projectHomeAdminRoutes.cjs — the single admin route behind the
+ * `project_home_write` MCP tool: POST /admin/project-home/write {cwd, html}
+ * writes one self-contained HTML document to
+ * `session-manager-operations/project-pages/home.html` (owner: project-home,
+ * see opsOwnership.cjs). Registered against the same injected
+ * localAdminHttp.cjs transport as prdAdminRoutes.cjs.
  *
- * Registered against the same injected localAdminHttp.cjs transport as
- * prdAdminRoutes.cjs — see that file's header for the transport contract
- * (`registerRoute(method, url, handler)`, handlers get
- * `(req, res, query: URLSearchParams)`).
- *
- * The MCP tool surface that calls these routes is the NEXT PRD in this
- * chain — this file only exposes the HTTP contract.
+ * "Self-contained" is enforced here, not trusted: the document must not
+ * reference any remote resource (`<script src>`, `<link href=http*>`,
+ * remote `@import` / `url(http*)`), so opening it never causes network egress.
  */
 'use strict';
 
@@ -28,64 +17,31 @@ const path = require('node:path');
 const { readBody, sendJson } = require('./localAdminHttp.cjs');
 const { resolveProjectContext } = require('./projectRootResolve.cjs');
 const { opsPath, OPS_ROOT_DIR } = require('./opsOwnership.cjs');
-const { PROJECT_PAGE_SUMMARY_JSON_SCHEMA, PROJECT_PAGE_PICKS_JSON_SCHEMA } = require('./projectPageSummarySchema.cjs');
 const config = require('../config.cjs');
 const { schemas } = require('../ipcSchemas.cjs');
 
-const LENSES = ['home', 'marketing', 'feature', 'architecture', 'brief'];
-
-// Shipped, build-time assets — fixed app-relative paths, read once and
-// cached in-process, same pattern as projectPages.cjs's
-// cachedDefaultHomeHtml (this file never changes at runtime; a repo edit
-// requires an app restart to pick up during dev, same as that module).
-const CATALOG_PATH = path.join(__dirname, '..', 'templates', 'project-pages-catalog.json');
-const SPEC_PATH = path.join(__dirname, '..', 'templates', 'project-pages-pipeline.md');
-const RENDERER_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'scripts', 'render-project-pages', 'dist', 'renderer.cjs');
-const LOGIC_BUNDLE_PATH = path.join(__dirname, '..', '..', '..', 'scripts', 'project-pages-logic', 'dist', 'logic.cjs');
-
-let cachedCatalog = null;
-function loadCatalog() {
-  if (!cachedCatalog) {
-    const raw = fs.readFileSync(CATALOG_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    // Drop $comment — it names the repo-relative source files the catalog
-    // was generated from (build-tooling provenance), which would violate
-    // this route's "never point the caller at a repo-relative path"
-    // contract if echoed back verbatim.
-    cachedCatalog = { lenses: parsed.lenses };
-  }
-  return cachedCatalog;
-}
-
-let cachedSpecText = null;
-function loadSpecText() {
-  if (cachedSpecText === null) {
-    cachedSpecText = fs.readFileSync(SPEC_PATH, 'utf8');
-  }
-  return cachedSpecText;
-}
-
-let cachedRenderer = null;
-function loadRenderer() {
-  if (!cachedRenderer) {
-    ({ renderProjectPages: cachedRenderer } = require(RENDERER_BUNDLE_PATH));
-  }
-  return cachedRenderer;
-}
-
-let cachedValidator = null;
-function loadValidator() {
-  if (!cachedValidator) {
-    ({ validateProjectPageSummary: cachedValidator } = require(LOGIC_BUNDLE_PATH));
+const MAX_HTML_BYTES = 1024 * 1024;
+
+// Each detector is a linear regex scan; the input is capped at 1MB first.
+const REMOTE_REFERENCE_CHECKS = [
+  { re: /<script\b[^>]*\bsrc\s*=/i, message: '<script src> is not allowed — inline all scripts' },
+  { re: /<link\b[^>]*\bhref\s*=\s*["']?\s*(?:https?:)?\/\//i, message: '<link href="http(s)://…"> is not allowed — inline all styles' },
+  { re: /@import\b/i, message: '@import is not allowed — inline all styles' },
+  { re: /url\(\s*["']?\s*(?:https?:)?\/\//i, message: 'url(http(s)://…) is not allowed — embed assets as data: URIs' },
+];
+
+/** -> null when `html` is acceptable, else a human-readable rejection reason. */
+function validateHomeHtml(html) {
+  if (typeof html !== 'string' || html.trim().length === 0) return 'html must be a non-empty string';
+  if (Buffer.byteLength(html, 'utf8') > MAX_HTML_BYTES) return `html exceeds the ${MAX_HTML_BYTES}-byte limit`;
+  for (const { re, message } of REMOTE_REFERENCE_CHECKS) {
+    if (re.test(html)) return `html must be self-contained: ${message}`;
   }
-  return cachedValidator;
+  return null;
 }
 
 /** Same definition crossProjectFeedback.cjs uses for "is this a Session
- * Manager project": it already has an operations root. Deliberately does
- * NOT require project-pages/ specifically to exist — a project that has
- * never generated a Project Home page yet is still a Session Manager
- * project (see the "no output dir yet" edge case on /status and /render). */
+ * Manager project": it already has an operations root. */
 function isSessionManagerProject(cwd) {
   try {
     return fs.statSync(path.join(cwd, OPS_ROOT_DIR)).isDirectory();
@@ -94,26 +50,8 @@ function isSessionManagerProject(cwd) {
   }
 }
 
-function projectPagesPaths(cwd) {
-  const dir = opsPath(cwd, 'project-pages');
-  return {
-    summaryPath: path.join(dir, 'summary.json'),
-    picksPath: path.join(dir, 'picks.json'),
-    outputDir: path.join(dir, 'output'),
-  };
-}
-
-/**
- * Resolve+validate a caller-supplied cwd into a real Session Manager
- * project root. Never throws — returns a structured verdict so every route
- * can turn a bad cwd into a JSON error instead of an unhandled throw (this
- * PRD's edge-case requirement).
- *
- * Deliberately does NOT call config.addAllowedRoot here — that widens
- * config.cjs's process-lifetime write boundary and belongs only on an
- * actual write path (the render route calls it itself, right before
- * writing), not on every GET this function also gates.
- */
+/** Resolve a caller-supplied cwd into a real Session Manager project root.
+ * Never throws — returns a structured verdict. */
 function resolveCwd(rawCwd) {
   if (!rawCwd || typeof rawCwd !== 'string') {
     return { ok: false, status: 400, error: 'cwd is required' };
@@ -121,9 +59,8 @@ function resolveCwd(rawCwd) {
   if (!path.isAbsolute(rawCwd)) {
     return { ok: false, status: 400, error: 'cwd must be an absolute path' };
   }
-  // Normalizes a worktree/ops-internal cwd to its real project root (see
-  // projectRootResolve.cjs's header) so a headless job running inside an
-  // Epic's worktree still targets the right project.
+  // Normalizes a worktree/ops-internal cwd to its real project root so a
+  // headless job inside an Epic's worktree still targets the right project.
   const resolved = resolveProjectContext({ cwd: rawCwd });
   const candidate = resolved.cwd || rawCwd;
   let realCwd;
@@ -142,261 +79,53 @@ function resolveCwd(rawCwd) {
   return { ok: true, cwd: realCwd };
 }
 
-/** Each validateProjectPageSummary error string is "<field.path> must ...".
- * Split it into { field, message } for the route's documented response
- * shape — the validator itself only returns flat strings. */
-function toFieldErrors(errors) {
-  return errors.map((message) => {
-    const m = /^([\w.]+)\s/.exec(message);
-    return { field: m ? m[1] : 'summary', message };
-  });
-}
-
-/**
- * Structural check for ProjectPagePicks (lensId -> slotId -> variantId) —
- * the shipped validator only covers `summary`, so this is the one guard
- * against handing the renderer bundle a shape it doesn't expect. Returns
- * "<field> must ..." strings in the same format toFieldErrors expects, so
- * both routes can share one error-shape.
- */
-function validatePicksShape(picks) {
-  if (picks === null || typeof picks !== 'object' || Array.isArray(picks)) {
-    return ['picks must be an object'];
-  }
-  const errors = [];
-  for (const [lensId, slotMap] of Object.entries(picks)) {
-    if (slotMap === null || typeof slotMap !== 'object' || Array.isArray(slotMap)) {
-      errors.push(`picks.${lensId} must be an object`);
-      continue;
-    }
-    for (const [slotId, variantId] of Object.entries(slotMap)) {
-      if (typeof variantId !== 'string' || variantId.length === 0) {
-        errors.push(`picks.${lensId}.${slotId} must be a non-empty string`);
-      }
-    }
-  }
-  return errors;
-}
-
-/** Shared readBody -> JSON.parse -> zod-schema.parse pipeline for the two
- * POST routes — collapses the 3-step try/catch chain that was previously
- * duplicated in both handlers into one call. Returns either
- * { ok: true, input } or { ok: false, status, error, details }. */
-async function parseJsonBody(req, schema) {
-  const raw = await readBody(req);
-  let body;
-  try {
-    body = raw ? JSON.parse(raw) : {};
-  } catch {
-    return { ok: false, status: 400, error: 'invalid JSON body' };
-  }
-  try {
-    return { ok: true, input: schema.parse(body) };
-  } catch (e) {
-    return { ok: false, status: 400, error: 'invalid payload', details: e?.issues ?? e?.message };
-  }
-}
-
-function buildProtocol() {
-  return [
-    'Call GET /admin/project-home/status?cwd=<abs> to see what already exists for this project (summary.json, picks.json, and any prior output).',
-    'Compose a ProjectPageSummary object matching the schema in this response\'s "summarySchema" field. Never fabricate content — every field must trace to something concrete about this project (an Epic goal, a source file/dir, a convention, a git log entry). Omit "brief" entirely if this project has no generated brief.json yet; omit "quotes" entries rather than inventing a testimonial.',
-    'For each lens in this response\'s "catalog.lenses", and for each of that lens\'s slots, pick exactly one variant id by judging the candidate variants\' "note" text against the summary content you composed. Assemble the picks into a ProjectPagePicks object (lensId -> slotId -> variantId) matching "picksSchema".',
-    'POST /admin/project-home/validate-summary with {cwd, summary}. If "valid" is false, fix every listed {field, message} error and re-validate before continuing.',
-    'POST /admin/project-home/render with {cwd, summary, picks}. This re-validates the summary server-side (rejecting with no writes on failure), renders all 5 lenses, and writes summary.json, picks.json, and output/{home,marketing,feature,architecture,brief}.html + output/manifest.json at the absolute paths in this response\'s "paths" field.',
-    'Optionally call GET /admin/project-home/status again to confirm the new files landed and to read manifest.json\'s generatedAt.',
-  ];
-}
-
 function registerAdminRoute(adminHttp) {
-  // GET /admin/project-home/contract?cwd=<abs> — the self-sufficient
-  // contract: protocol, schema, catalog, absolute paths, spec. Nothing in
-  // this response should require the caller to read a repo-relative path.
-  adminHttp.registerRoute('GET', '/admin/project-home/contract', async (req, res, query) => {
-    let input;
+  // POST /admin/project-home/write {cwd, html}
+  adminHttp.registerRoute('POST', '/admin/project-home/write', async (req, res) => {
+    // Allow headroom over MAX_HTML_BYTES for JSON escaping; the html byte
+    // limit itself is enforced by validateHomeHtml below.
+    let raw;
     try {
-      input = schemas.projectHomeAdminCwdQuery.parse(Object.fromEntries(query ?? []));
+      raw = await readBody(req, MAX_HTML_BYTES * 2 + 4096);
     } catch (e) {
-      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      sendJson(res, 400, { ok: false, error: `request body rejected: ${e?.message ?? 'unreadable'} (html limit is ${MAX_HTML_BYTES} bytes)` });
       return;
     }
-    const resolved = resolveCwd(input.cwd);
-    if (!resolved.ok) {
-      sendJson(res, resolved.status, { ok: false, error: resolved.error });
+    let body;
+    try {
+      body = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
       return;
     }
-    // projectPagesPaths()->opsPath() can throw for a cwd resolveCwd accepted
-    // but opsPath's own (separate) ephemeral-root check refuses — keep this
-    // route's "never an unhandled throw" contract even on that edge.
+    let input;
     try {
-      const { summaryPath, picksPath, outputDir } = projectPagesPaths(resolved.cwd);
-      sendJson(res, 200, {
-        ok: true,
-        protocol: buildProtocol(),
-        summarySchema: PROJECT_PAGE_SUMMARY_JSON_SCHEMA,
-        picksSchema: PROJECT_PAGE_PICKS_JSON_SCHEMA,
-        catalog: loadCatalog(),
-        paths: { summaryPath, picksPath, outputDir },
-        spec: { text: loadSpecText(), path: SPEC_PATH },
-      });
+      input = schemas.projectHomeAdminWriteBody.parse(body);
     } catch (e) {
-      sendJson(res, 400, { ok: false, error: e?.message ?? 'failed to resolve project-pages paths' });
-    }
-  });
-
-  // POST /admin/project-home/validate-summary {cwd, summary}
-  adminHttp.registerRoute('POST', '/admin/project-home/validate-summary', async (req, res) => {
-    const parsed = await parseJsonBody(req, schemas.projectHomeAdminValidateSummaryBody);
-    if (!parsed.ok) {
-      sendJson(res, parsed.status, { ok: false, error: parsed.error, details: parsed.details });
-      return;
-    }
-    const { input } = parsed;
-    const resolved = resolveCwd(input.cwd);
-    if (!resolved.ok) {
-      sendJson(res, resolved.status, { ok: false, error: resolved.error });
-      return;
-    }
-    const validateProjectPageSummary = loadValidator();
-    const result = validateProjectPageSummary(input.summary);
-    if (!result.ok) {
-      sendJson(res, 200, { ok: true, valid: false, errors: toFieldErrors(result.errors) });
-      return;
-    }
-    sendJson(res, 200, { ok: true, valid: true, errors: [] });
-  });
-
-  // POST /admin/project-home/render {cwd, summary, picks}
-  adminHttp.registerRoute('POST', '/admin/project-home/render', async (req, res) => {
-    const parsed = await parseJsonBody(req, schemas.projectHomeAdminRenderBody);
-    if (!parsed.ok) {
-      sendJson(res, parsed.status, { ok: false, error: parsed.error, details: parsed.details });
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
       return;
     }
-    const { input } = parsed;
     const resolved = resolveCwd(input.cwd);
     if (!resolved.ok) {
       sendJson(res, resolved.status, { ok: false, error: resolved.error });
       return;
     }
-    const validateProjectPageSummary = loadValidator();
-    const validation = validateProjectPageSummary(input.summary);
-    const picksErrors = validatePicksShape(input.picks);
-    if (!validation.ok || picksErrors.length > 0) {
-      sendJson(res, 400, {
-        ok: false,
-        valid: false,
-        errors: [...toFieldErrors(validation.ok ? [] : validation.errors), ...toFieldErrors(picksErrors)],
-      });
+    const rejection = validateHomeHtml(input.html);
+    if (rejection) {
+      sendJson(res, 400, { ok: false, error: rejection });
       return;
     }
-
-    // Only a route that is actually about to write registers the cwd as a
-    // write-allowed root — see resolveCwd's header for why this must not
-    // happen on the GET routes above.
+    // Only a route that is actually about to write widens config.cjs's
+    // write boundary to this project root.
     config.addAllowedRoot(resolved.cwd);
     try {
-      const result = await serializedPerCwd(resolved.cwd, () => doRender(resolved.cwd, input.summary, input.picks));
-      sendJson(res, 200, { ok: true, ...result });
+      const homePath = opsPath(resolved.cwd, 'project-pages', 'home.html');
+      await config.writeTextAtomic(homePath, input.html, { writer: 'project-home' });
+      sendJson(res, 200, { ok: true, path: homePath, bytes: Buffer.byteLength(input.html, 'utf8') });
     } catch (e) {
-      sendJson(res, 500, { ok: false, error: e?.message ?? 'render failed' });
+      sendJson(res, 500, { ok: false, error: e?.message ?? 'write failed' });
     }
   });
-
-  // GET /admin/project-home/status?cwd=<abs>
-  adminHttp.registerRoute('GET', '/admin/project-home/status', async (req, res, query) => {
-    let input;
-    try {
-      input = schemas.projectHomeAdminCwdQuery.parse(Object.fromEntries(query ?? []));
-    } catch (e) {
-      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
-      return;
-    }
-    const resolved = resolveCwd(input.cwd);
-    if (!resolved.ok) {
-      sendJson(res, resolved.status, { ok: false, error: resolved.error });
-      return;
-    }
-    try {
-      const status = await getStatus(resolved.cwd);
-      sendJson(res, 200, { ok: true, ...status });
-    } catch (e) {
-      sendJson(res, 400, { ok: false, error: e?.message ?? 'failed to read project-pages status' });
-    }
-  });
-}
-
-// Per-cwd in-process promise chain — the render route's only concurrency
-// guard. Sufficient because this admin HTTP server is a single Node
-// process (Electron main) with no worker pool for these routes; a second
-// concurrent render for the SAME cwd simply waits for the first to finish
-// writing before it starts, so output/ is never observed half-written by
-// two overlapping /render calls (it does NOT defend against a
-// project-home-builder Epic's own separate Write-tool calls racing this
-// route from a different OS process — see project-pages/README.md's
-// concurrency section). Entries are evicted once their chain settles so
-// this Map doesn't grow for the life of the process across many cwds.
-const renderChains = new Map();
-function serializedPerCwd(cwd, fn) {
-  const prev = renderChains.get(cwd) || Promise.resolve();
-  const next = prev.catch(() => {}).then(fn);
-  const settled = next.catch(() => {});
-  renderChains.set(cwd, settled);
-  settled.finally(() => {
-    if (renderChains.get(cwd) === settled) renderChains.delete(cwd);
-  });
-  return next;
-}
-
-async function doRender(cwd, summary, picks) {
-  const renderProjectPages = loadRenderer();
-  const pages = renderProjectPages(summary, picks);
-  const generatedAt = new Date().toISOString();
-  const { summaryPath, picksPath, outputDir } = projectPagesPaths(cwd);
-
-  // The 5 lens files plus summary.json/picks.json have no ordering
-  // dependency on each other — only manifest.json's presence is the
-  // "generation complete" signal getStatus() relies on, so it's written
-  // last, after everything else has landed.
-  const lensWrites = LENSES.map((lens) => {
-    const lensPath = path.join(outputDir, `${lens}.html`);
-    return config.writeTextAtomic(lensPath, pages[lens], { writer: 'project-home' }).then(() => lensPath);
-  });
-  const [, , ...lensPaths] = await Promise.all([
-    config.writeJson(summaryPath, summary, { writer: 'project-home' }).then(() => summaryPath),
-    config.writeJson(picksPath, picks, { writer: 'project-home' }).then(() => picksPath),
-    ...lensWrites,
-  ]);
-  const manifestPath = path.join(outputDir, 'manifest.json');
-  await config.writeJson(manifestPath, { generatedAt }, { writer: 'project-home' });
-
-  return { filesWritten: [summaryPath, picksPath, ...lensPaths, manifestPath], generatedAt };
-}
-
-async function getStatus(cwd) {
-  const { summaryPath, picksPath, outputDir } = projectPagesPaths(cwd);
-  const [summaryRes, picksRes, manifestRes, ...lensRes] = await Promise.all([
-    config.readJson(summaryPath),
-    config.readJson(picksPath),
-    config.readJson(path.join(outputDir, 'manifest.json')),
-    ...LENSES.map((lens) => config.readText(path.join(outputDir, `${lens}.html`))),
-  ]);
-
-  const output = {};
-  LENSES.forEach((lens, i) => {
-    const r = lensRes[i];
-    output[lens] = { exists: r.exists, mtimeMs: r.exists ? r.mtimeMs : null };
-  });
-
-  return {
-    summary: { exists: summaryRes.exists, mtimeMs: summaryRes.exists ? summaryRes.mtimeMs : null },
-    picks: { exists: picksRes.exists, mtimeMs: picksRes.exists ? picksRes.mtimeMs : null },
-    output,
-    manifest: {
-      exists: manifestRes.exists,
-      generatedAt: manifestRes.exists && manifestRes.data ? (manifestRes.data.generatedAt ?? null) : null,
-    },
-  };
 }
 
-module.exports = { registerAdminRoute };
+module.exports = { registerAdminRoute, validateHomeHtml, MAX_HTML_BYTES };

package/src/main/lib/projectRootResolve.cjs

@@ -34,7 +34,7 @@
  */
 
 const path = require('node:path');
-const { projectRootOf, allProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { projectRootOf, allProjectCwds } = require('./activeSessions.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
 

package/src/main/lib/queueHistory.cjs

@@ -10,11 +10,11 @@
 // `nowMs` and `opts` so it's testable without touching the real clock or
 // disk. appendHistory/readHistory own the actual fs I/O.
 
-const os = require('os');
 const path = require('path');
 const fsp = require('fs').promises;
 const { HISTORY_RETENTION_MS } = require('./schedulerConfig.cjs');
 const { projectHistoryPath, stateCwds } = require('./queueStore.cjs');
+const { queueHistoryPath } = require('./schedulerPaths.cjs');
 const { resolveIsFixPlan } = require('./fixPlanSlug.cjs');
 
 // Legacy global sidecar — READ-ONLY since 2026-07-31 (federated per-project
@@ -26,8 +26,9 @@ const { resolveIsFixPlan } = require('./fixPlanSlug.cjs');
 // Overridable via SM_HISTORY_PATH_OVERRIDE so queueHistory.test.cjs can point
 // this at an isolated tmpdir path instead of racing a live Electron
 // instance's scheduler.cjs, which writes this same machine-global file.
-const HISTORY_PATH = process.env.SM_HISTORY_PATH_OVERRIDE
-  || path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'history.jsonl');
+function historyPath() {
+  return process.env.SM_HISTORY_PATH_OVERRIDE || queueHistoryPath();
+}
 
 /**
  * Every history file currently in play: each project's shard + the legacy
@@ -37,12 +38,12 @@ const HISTORY_PATH = process.env.SM_HISTORY_PATH_OVERRIDE
  * would leak real production history rows into an otherwise-isolated test.
  */
 function historyPaths() {
-  if (process.env.SM_HISTORY_PATH_OVERRIDE) return [HISTORY_PATH];
+  if (process.env.SM_HISTORY_PATH_OVERRIDE) return [historyPath()];
   const paths = [];
   for (const cwd of stateCwds()) {
     try { paths.push(projectHistoryPath(cwd)); } catch { /* unusable cwd */ }
   }
-  paths.push(HISTORY_PATH);
+  paths.push(historyPath());
   return paths;
 }
 
@@ -50,11 +51,18 @@ function historyPathFor(entry) {
   if (entry && entry.cwd) {
     try { return projectHistoryPath(entry.cwd); } catch { /* fall through */ }
   }
-  return HISTORY_PATH;
+  return historyPath();
 }
 
+// `kind` keeps a needs_review_entry/needs_review_resolution line (see
+// needsReviewLedger.cjs) from colliding with a TERMINAL row that shares the
+// same slug+runId — an entry and its resolution deliberately reference the
+// SAME runId (that's how they're paired), so without `kind` in the dedupe
+// key the second append would look like a replay of the first and silently
+// never be written. Absent `kind` (every existing terminal row) buckets
+// under 'terminal', so today's on-disk rows and callers are unaffected.
 function jobKey(job) {
-  return `${job?.slug ?? ''}|${job?.runId ?? ''}`;
+  return `${job?.slug ?? ''}|${job?.runId ?? ''}|${job?.kind ?? 'terminal'}`;
 }
 
 /**
@@ -259,6 +267,12 @@ async function historyTerminalBySlug() {
       if (!line.trim()) continue;
       try {
         const j = JSON.parse(line);
+        // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
+        // share this file but aren't a job's terminal record — skip them, or a
+        // needs_review episode logged for a slug AFTER its real terminal row
+        // (e.g. it re-parked on a later run) would overwrite a true 'completed'
+        // with a kind-less, status-less row read as "not terminal".
+        if (j?.kind && j.kind !== 'terminal') continue;
         if (j?.slug) map.set(j.slug, { status: j.status, finishedAt: j.finishedAt, landedCommit: j.landedCommit ?? null });
       } catch {
         // corrupt/partial line — ignore
@@ -301,6 +315,11 @@ async function completedSlugsForCwd(cwd) {
     if (!line.trim()) continue;
     try {
       const j = JSON.parse(line);
+      // Skip needs_review ledger lines (needsReviewLedger.cjs) — they carry
+      // no `status` field, so treating them as a real record would let a
+      // later needs_review park/resolution silently blank out this slug's
+      // last true terminal status.
+      if (j?.kind && j.kind !== 'terminal') continue;
       if (j?.slug) statusBySlug.set(j.slug, j.status);
     } catch {
       // corrupt/partial line — ignore
@@ -314,7 +333,7 @@ async function completedSlugsForCwd(cwd) {
 }
 
 module.exports = {
-  HISTORY_PATH,
+  historyPath,
   partitionJobs,
   appendHistory,
   readHistory,