claude-code-session-manager 0.112.0 → 0.114.0

package/src/main/lib/feedback-remote/crossProjectFeedback.cjs

@@ -33,7 +33,19 @@
  * feedback Epic is born 'proposed' like every other Epic (epicMint.cjs's
  * BORN-PROPOSED check applies to this mint authority verbatim), so the human
  * in the RECEIVING project is still the one who decides whether a single token
- * gets spent. An agent can ask; it cannot start.
+ * gets spent. An agent can ask; it cannot start on its own say-so.
+ *
+ * The one exception is a VERIFIED HUMAN REQUEST. When the human themselves
+ * asked, in chat, for work in another project, making them re-confirm in the
+ * receiving project is pure friction. So `autoStart: true` plus a
+ * `humanRequestQuote` is honored only when main can check the quote against
+ * humanPromptLedger (prompts chat:run recorded with human origin) for the
+ * originating chat session — `input.originClaudeSessionId`, taken from the MCP
+ * server's env, set only for interactive chat runs, never for scheduler jobs —
+ * AND that human prompt names the target project. Even then the Epic is still
+ * minted 'proposed'; it is only stamped `source.autoApprove` and the renderer
+ * is told to approve-and-start it through its normal approveProposed path.
+ * Anything unverifiable degrades to the ordinary proposal.
  *
  * Guards, all fail-closed:
  *   - both cwds go through config.cjs's validatePath (allowedRoots = home)
@@ -90,6 +102,7 @@ const MAX_SERIES_KEY_CHARS = 60;
 const MAX_SERIES_TITLE_CHARS = 120;
 const MAX_SERIES_TOTAL = 50;
 const MAX_ORIGIN_ASK_CHARS = 300;
+const MAX_HUMAN_QUOTE_CHARS = 2000;
 const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 /** Bound on how many `~/.claude/projects/` folders listFeedbackTargets will
@@ -349,6 +362,18 @@ function validateFeedbackInput(input = {}) {
     series = { key, title: stitle, index: sr.index, total: sr.total };
   }
 
+  if (input.autoStart !== undefined && input.autoStart !== null && typeof input.autoStart !== 'boolean') {
+    return bad(400, 'autoStart must be a boolean');
+  }
+  let humanRequestQuote = '';
+  if (input.humanRequestQuote !== undefined && input.humanRequestQuote !== null) {
+    if (typeof input.humanRequestQuote !== 'string') return bad(400, 'humanRequestQuote must be a string');
+    humanRequestQuote = input.humanRequestQuote.trim();
+    if (humanRequestQuote.length > MAX_HUMAN_QUOTE_CHARS) {
+      return bad(400, `humanRequestQuote is ${humanRequestQuote.length} chars; cap is ${MAX_HUMAN_QUOTE_CHARS}`);
+    }
+  }
+
   const referencePaths = Array.isArray(input.referencePaths) ? input.referencePaths : [];
   if (referencePaths.length > MAX_REFERENCES) {
     return bad(400, `too many referencePaths (${referencePaths.length}); cap is ${MAX_REFERENCES}`);
@@ -410,6 +435,8 @@ function validateFeedbackInput(input = {}) {
       acceptanceCriteria: lists.acceptanceCriteria,
       outOfScope: lists.outOfScope,
       series,
+      autoStart: input.autoStart === true,
+      humanRequestQuote,
       referencePaths: referencePaths.map((p) => String(p)),
       fromEpicId: input.fromEpicId ? String(input.fromEpicId) : null,
       agentType: input.agentType ? String(input.agentType) : DEFAULT_FEEDBACK_AGENT,
@@ -418,6 +445,44 @@ function validateFeedbackInput(input = {}) {
   };
 }
 
+/** Tell every renderer window to approve-and-start a granted auto-start Epic.
+ *  Electron is required lazily so unit tests never need it. */
+function defaultNotifyRenderer(payload) {
+  try {
+    const { BrowserWindow } = require('electron');
+    for (const win of BrowserWindow.getAllWindows()) {
+      try {
+        win.webContents.send('promptSessions:inbound-auto-approve', payload);
+      } catch { /* window going away */ }
+    }
+  } catch { /* not running under Electron */ }
+}
+
+/**
+ * verifyAutoStart(v, originClaudeSessionId) → { granted: true, quote } | { granted: false, reason }
+ *
+ * Every check is fail-closed. The session identity is ONLY the caller-supplied
+ * originClaudeSessionId (MCP env), never a field an agent can pick freely.
+ */
+function verifyAutoStart(v, originClaudeSessionId) {
+  if (!v.autoStart) return { granted: false, reason: 'autoStart was not requested' };
+  if (!v.humanRequestQuote) return { granted: false, reason: 'no humanRequestQuote was given' };
+  if (!originClaudeSessionId) {
+    return { granted: false, reason: 'no originClaudeSessionId — only interactive chat sessions can auto-start' };
+  }
+  const { findHumanPromptContaining } = require('./humanPromptLedger.cjs');
+  const found = findHumanPromptContaining(originClaudeSessionId, v.humanRequestQuote);
+  if (!found) {
+    return { granted: false, reason: 'humanRequestQuote was not found in a prompt the human typed in this chat session' };
+  }
+  const prompt = found.text.toLowerCase();
+  const base = path.basename(v.toCwd).toLowerCase();
+  if (!(base && prompt.includes(base)) && !prompt.includes(v.toCwd.toLowerCase())) {
+    return { granted: false, reason: `the human's prompt does not name the receiving project (${path.basename(v.toCwd)})` };
+  }
+  return { granted: true, quote: v.humanRequestQuote };
+}
+
 /**
  * openFeedbackSession(input, deps?) → { ok, status?, error?, epicId, toCwd, ... }
  *
@@ -427,8 +492,8 @@ function validateFeedbackInput(input = {}) {
  * best-effort: a failure there never invalidates a delivered proposal, it just
  * reports `receiptOnOriginEpic: false`.
  *
- * `deps` exists so tests can inject the two side-effecting collaborators
- * without an Electron/main-process boot.
+ * `deps` exists so tests can inject the side-effecting collaborators
+ * (ensureEpic, appendResponseEventIfKnown, notifyRenderer) without an Electron/main-process boot.
  */
 async function openFeedbackSession(input, deps = {}) {
   const mint = deps.ensureEpic || ensureEpic;
@@ -439,10 +504,19 @@ async function openFeedbackSession(input, deps = {}) {
     // boot the main process.
     || ((...args) => require('../../promptSessionEvents.cjs').appendResponseEventIfKnown(...args));
 
+  const notify = deps.notifyRenderer || defaultNotifyRenderer;
+
   const checked = validateFeedbackInput(input);
   if (!checked.ok) return checked;
   const v = checked.value;
 
+  const originClaudeSessionId =
+    typeof input.originClaudeSessionId === 'string' && input.originClaudeSessionId
+      ? input.originClaudeSessionId
+      : null;
+  const auto = verifyAutoStart(v, originClaudeSessionId);
+  const verifiedAt = new Date().toISOString();
+
   // The MCP client can't know its own Epic id — it only inherits the claude
   // session id chatRunner.cjs stamps on the `claude -p` child. Resolve it
   // through prdCreate.cjs's existing resolver rather than a second copy of
@@ -488,6 +562,16 @@ async function openFeedbackSession(input, deps = {}) {
         producer: 'cross-project-feedback',
         fromCwd: v.fromCwd,
         ...(v.fromEpicId ? { fromEpicId: v.fromEpicId } : {}),
+        ...(auto.granted
+          ? {
+              autoApprove: {
+                requestedBy: 'human',
+                quote: auto.quote,
+                verifiedAt,
+                fromClaudeSessionId: originClaudeSessionId,
+              },
+            }
+          : {}),
         proposal: {
           motivation: v.motivation,
           originAsk,
@@ -511,8 +595,16 @@ async function openFeedbackSession(input, deps = {}) {
     tag: v.tag,
     title: v.title,
     series: v.series,
+    autoStartGranted: auto.granted,
+    autoStartReason: auto.granted ? 'verified human request' : auto.reason,
   });
 
+  if (auto.granted) {
+    try {
+      notify({ cwd: v.toCwd, epicId: minted.epicId });
+    } catch { /* the Epic is delivered either way; a human can still approve it */ }
+  }
+
   let receiptOnOriginEpic = false;
   if (v.fromEpicId) {
     try {
@@ -522,7 +614,9 @@ async function openFeedbackSession(input, deps = {}) {
         `Feedback delivered to ${v.toCwd} as a proposed session (${minted.epicId}): "${v.title}"`
         + (v.series ? ` [${seriesLine(v.series)}]` : '')
         + '. '
-        + 'It will not run until a human in that project approves it.',
+        + (auto.granted
+          ? 'It was auto-approved at the human\'s explicit request and is starting in that project.'
+          : 'It will not run until a human in that project approves it.'),
       );
     } catch {
       receiptOnOriginEpic = false;
@@ -535,14 +629,18 @@ async function openFeedbackSession(input, deps = {}) {
     toCwd: v.toCwd,
     fromCwd: v.fromCwd,
     tag: v.tag,
-    status: 'proposed',
+    status: auto.granted ? 'auto-approved' : 'proposed',
+    ...(v.autoStart ? { autoStart: auto.granted ? { granted: true } : { granted: false, reason: auto.reason } } : {}),
     receiptOnOriginEpic,
     // Say plainly what did NOT happen, same posture as create-prd's
     // `enqueued: false` — never let a caller report this as "work started".
-    note:
-      'Delivered as a PROPOSED session in the receiving project\'s Sessions queue. Nothing runs and no '
-      + 'tokens are spent until a human in that project presses Approve & start. There is no callback: '
-      + 'if you need an answer, ask the human to follow up.',
+    note: auto.granted
+      ? 'Auto-approved at the human\'s explicit request (verified against their chat prompt): the session '
+        + 'is starting in the receiving project. There is no callback: if you need an answer, ask the human '
+        + 'to follow up.'
+      : 'Delivered as a PROPOSED session in the receiving project\'s Sessions queue. Nothing runs and no '
+        + 'tokens are spent until a human in that project presses Approve & start. There is no callback: '
+        + 'if you need an answer, ask the human to follow up.',
     goalText,
   };
 }

package/src/main/lib/feedback-remote/humanPromptLedger.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * humanPromptLedger.cjs — in-memory record of prompts a HUMAN typed into each
+ * chat claude session, keyed by claudeSessionId.
+ *
+ * Why it exists. The cross-project feedback conduit (crossProjectFeedback.cjs)
+ * may auto-approve a receiving-project session only when the human explicitly
+ * asked for it. An agent's say-so is not evidence of that. This ledger is the
+ * ONLY evidence that a human — not an agent, not an external/Web Remote
+ * injection, not an inbound proposal's agent-written opening prompt — typed a
+ * given prompt. Callers record only prompts that arrived from the human's own
+ * chat input, then ask `findHumanPromptContaining` whether a quoted request
+ * really appears in one.
+ *
+ * In-memory by design. Losing the ledger on restart only degrades auto-approve
+ * back to the ordinary 'proposed' path — it fails closed, so nothing is
+ * persisted to disk.
+ *
+ * Bounds: 10 prompts per session, 24h TTL, 200 sessions (least-recently-
+ * recorded evicted), 20000 chars per stored prompt. Pure Node, no Electron.
+ */
+
+const MIN_QUOTE_CHARS = 20;
+const MAX_PER_SESSION = 10;
+const TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_SESSIONS = 200;
+const MAX_TEXT_CHARS = 20000;
+
+/** @type {Map<string, Array<{ text: string, norm: string, at: number }>>} */
+const ledger = new Map();
+
+/** @param {string} s */
+function normalize(s) {
+  return s.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+/**
+ * @param {unknown} claudeSessionId
+ * @param {unknown} text
+ * @param {number} [now]
+ */
+function recordHumanPrompt(claudeSessionId, text, now = Date.now()) {
+  try {
+    if (typeof claudeSessionId !== 'string' || !claudeSessionId) return;
+    if (typeof text !== 'string' || !text.trim()) return;
+    const stored = text.slice(0, MAX_TEXT_CHARS);
+    const prior = (ledger.get(claudeSessionId) || []).filter((e) => now - e.at <= TTL_MS);
+    prior.push({ text: stored, norm: normalize(stored), at: now });
+    while (prior.length > MAX_PER_SESSION) prior.shift();
+    // Re-insert so Map order is least-recently-recorded first.
+    ledger.delete(claudeSessionId);
+    ledger.set(claudeSessionId, prior);
+    while (ledger.size > MAX_SESSIONS) {
+      const oldest = ledger.keys().next().value;
+      if (oldest === undefined) break;
+      ledger.delete(oldest);
+    }
+  } catch {
+    /* never throws */
+  }
+}
+
+/**
+ * @param {unknown} claudeSessionId
+ * @param {unknown} quote
+ * @param {number} [now]
+ * @returns {{ text: string, at: number } | null}
+ */
+function findHumanPromptContaining(claudeSessionId, quote, now = Date.now()) {
+  try {
+    if (typeof claudeSessionId !== 'string' || typeof quote !== 'string') return null;
+    const q = normalize(quote);
+    if (q.length < MIN_QUOTE_CHARS) return null;
+    const entries = ledger.get(claudeSessionId);
+    if (!entries) return null;
+    const live = entries.filter((e) => now - e.at <= TTL_MS);
+    if (live.length === 0) ledger.delete(claudeSessionId);
+    else if (live.length !== entries.length) ledger.set(claudeSessionId, live);
+    for (let i = live.length - 1; i >= 0; i--) {
+      if (live[i].norm.includes(q)) return { text: live[i].text, at: live[i].at };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function _resetForTests() {
+  ledger.clear();
+}
+
+module.exports = { recordHumanPrompt, findHumanPromptContaining, MIN_QUOTE_CHARS, _resetForTests };

package/src/main/lib/mcpToolCatalog.cjs

@@ -243,7 +243,11 @@ const MCP_TOOL_CATALOG = [
       + '`acceptanceCriteria`; put evidence, symptom and references in `body`. Name the file in THEIR repo '
       + 'that looks responsible if you know it. When one request is split into several proposals, send '
       + 'them ALL with one shared `series` {key, title, total} (plus each one\'s `index`) and summarise '
-      + 'the overall plan in each motivation.',
+      + 'the overall plan in each motivation. TWO MODES: (1) agent-initiated (your own idea) = PROPOSED, a '
+      + 'human in the receiving project must approve it; pass neither autoStart nor humanRequestQuote. '
+      + '(2) human-requested = the human in THIS conversation explicitly asked for the work in that other '
+      + 'project: pass `autoStart: true` plus `humanRequestQuote`, copied VERBATIM from their own message, '
+      + 'which must name the target project. An unverified request silently falls back to PROPOSED.',
     whenNotToUse: 'WHEN NOT TO USE IT: for work in the project you are ALREADY in, run /develop inside the Epic you '
       + 'are already in — this tool refuses toCwd === fromCwd outright.',
     exampleArgs: {
@@ -258,11 +262,13 @@ const MCP_TOOL_CATALOG = [
       series: { key: 'shared-admin-api-f', title: 'Shared admin API field F', index: 1, total: 2 },
       body: 'Symptom: X. Observed while doing Y in session-manager. Expected: Z. Suspected file: <path in their repo>.',
     },
-    notes: 'WHAT THIS DOES NOT DO: it does not start anything, queue a PRD, or spend a token. The session '
+    notes: 'WHAT THIS DOES NOT DO: it never writes code or queues a PRD itself. Agent-initiated, the session '
       + 'lands as `proposed` and runs only if a human in the RECEIVING project presses "Approve & start". '
+      + 'With a verified autoStart + humanRequestQuote the result status is `auto-approved` and the session '
+      + 'starts on its own; otherwise it stays proposed (check the note for the reason). '
       + 'There is no callback and no reply channel — do not wait for an answer, and do not tell the user '
       + 'the other project has "been fixed" or "is working on it". Report only that the proposal was '
-      + 'delivered.',
+      + 'delivered, or that the session was auto-approved and is starting.',
   },
   {
     name: 'project_home_write',

package/src/main/lib/memoryDirResolve.cjs

@@ -0,0 +1,139 @@
+/**
+ * memoryDirResolve.cjs — where Claude Code itself keeps memory.
+ *
+ * Pure resolver (all IO injected) so the Memory tab reads and writes exactly the native locations:
+ *   - workspace memory: ~/.claude/projects/<encoded git-repo root>/memory/ (all worktrees of a
+ *     repo share it), unless the `autoMemoryDirectory` setting overrides it.
+ *   - subagent memory: enabled by a `memory:` frontmatter field on the agent.
+ *
+ * Top-level in lib/ because it spans settings, git and agent files (no single domain folder fits).
+ */
+'use strict';
+
+const path = require('node:path');
+const { encodeCwd } = require('./util/encodeCwd.cjs');
+
+const SCOPES = ['user', 'project', 'local'];
+const NAME_RE = /^[A-Za-z0-9._-]{1,128}$/;
+
+/** Highest-precedence value (local > project > user) of `key` passing `pred`. */
+function pick(settings, key, pred) {
+  for (const layer of ['local', 'project', 'user']) {
+    const s = settings && settings[layer];
+    if (s && typeof s === 'object' && pred(s[key])) return s[key];
+  }
+  return undefined;
+}
+
+function expandDir(value, home, cwd) {
+  if (value === '~') return home;
+  if (value.startsWith('~/')) return path.join(home, value.slice(2));
+  return path.resolve(cwd, value);
+}
+
+function resolveWorkspaceMemoryDir({ home, cwd, settings, repoRoot }) {
+  const override = pick(settings, 'autoMemoryDirectory', (v) => typeof v === 'string' && v.trim() !== '');
+  if (override !== undefined) {
+    return { dir: expandDir(override.trim(), home, cwd), source: 'autoMemoryDirectory' };
+  }
+  return {
+    dir: path.join(home, '.claude', 'projects', encodeCwd(repoRoot || cwd), 'memory'),
+    source: 'default',
+  };
+}
+
+function autoMemoryEnabled(settings) {
+  return pick(settings, 'autoMemoryEnabled', (v) => typeof v === 'boolean') !== false;
+}
+
+function resolveAgentMemoryDir({ home, root, name, scope }) {
+  if (typeof name !== 'string' || !NAME_RE.test(name) || name === '.' || name === '..') {
+    throw new Error(`invalid agent name: ${JSON.stringify(name)}`);
+  }
+  if (!SCOPES.includes(scope)) throw new Error(`unknown memory scope: ${JSON.stringify(scope)}`);
+  if (scope === 'user') return path.join(home, '.claude', 'agent-memory', name);
+  if (typeof root !== 'string' || !root) throw new Error(`scope '${scope}' requires a project root`);
+  return path.join(root, '.claude', scope === 'project' ? 'agent-memory' : 'agent-memory-local', name);
+}
+
+/** Parse the leading `---` block into a flat key -> string map. */
+function parseFrontmatter(text) {
+  const out = {};
+  if (typeof text !== 'string') return out;
+  const lines = text.replace(/^/, '').split(/\r?\n/);
+  if (lines[0].trim() !== '---') return out;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') return out;
+    const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(lines[i]);
+    if (m) out[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, '$2');
+  }
+  return {}; // unterminated block: not frontmatter
+}
+
+function scanAgents(dir, origin, readDir, readText) {
+  let names;
+  try {
+    names = readDir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const file of names || []) {
+    if (typeof file !== 'string' || !file.endsWith('.md')) continue;
+    const agentFile = path.join(dir, file);
+    let text;
+    try {
+      text = readText(agentFile);
+    } catch {
+      continue;
+    }
+    if (text == null) continue;
+    const fm = parseFrontmatter(text);
+    out.push({
+      name: fm.name || file.slice(0, -3),
+      origin,
+      memoryScope: SCOPES.includes(fm.memory) ? fm.memory : null,
+      agentFile,
+    });
+  }
+  return out;
+}
+
+function listMemoryAgents({ home, root, readDir, readText }) {
+  const byName = new Map();
+  for (const a of scanAgents(path.join(home, '.claude', 'agents'), 'user', readDir, readText)) byName.set(a.name, a);
+  if (root) {
+    for (const a of scanAgents(path.join(root, '.claude', 'agents'), 'project', readDir, readText)) byName.set(a.name, a);
+  }
+  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+const rootCache = new Map();
+
+function gitRepoRoot(cwd, execFileSync) {
+  if (rootCache.has(cwd)) return rootCache.get(cwd);
+  let root = null;
+  try {
+    const out = String(
+      execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+        cwd,
+        timeout: 5000,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }),
+    ).trim();
+    if (out.endsWith('/.git')) root = out.slice(0, -'/.git'.length) || null;
+  } catch {
+    root = null;
+  }
+  rootCache.set(cwd, root);
+  return root;
+}
+
+module.exports = {
+  resolveWorkspaceMemoryDir,
+  autoMemoryEnabled,
+  resolveAgentMemoryDir,
+  listMemoryAgents,
+  gitRepoRoot,
+};

package/src/main/lib/memoryIndex.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Pure helpers for Claude Code's auto-memory index file (MEMORY.md): one line
+ * per memory, `- [Title](file.md) — hook`. Claude Code loads only the first
+ * 200 lines / 25KB of it per session, so an unlisted memory is invisible.
+ * No fs/electron access; callers pass text in and write text out.
+ *
+ * Top-level (not in a lib/ subfolder) to sit beside its sibling memoryStale.cjs.
+ */
+
+const MAX_LINES = 200;
+const MAX_BYTES = 25600;
+const NEAR_LINES = 180;
+const NEAR_BYTES = 23040;
+
+// `- [Title](name.md)` with optional ` — hook` / ` - hook`. Bare file names only
+// (no path separators), so links into subfolders or URLs never match.
+const LINE_RE = /^\s*[-*]\s+\[([^\]]*)\]\(([^)\s/\\]+\.md)\)(?:\s+(?:—|-)\s+(.*?))?\s*$/;
+
+/** Split into lines; a trailing newline does not add a line. */
+function splitLines(text) {
+  if (typeof text !== 'string' || text === '') return [];
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+function matchLine(raw) {
+  return LINE_RE.exec(raw.replace(/\r$/, ''));
+}
+
+/**
+ * Parse index link lines. Complexity: O(lines).
+ * @param {string|null} text
+ * @returns {{line: string, lineNo: number, title: string, file: string, hook: string}[]}
+ */
+function parseIndex(text) {
+  const out = [];
+  splitLines(text).forEach((raw, i) => {
+    const m = matchLine(raw);
+    if (!m) return;
+    out.push({ line: raw.replace(/\r$/, ''), lineNo: i + 1, title: m[1], file: m[2], hook: m[3] || '' });
+  });
+  return out;
+}
+
+/**
+ * Append an index line unless `file` is already linked. Complexity: O(lines).
+ * @param {string|null} text
+ * @param {{file: string, title: string, hook?: string}} entry
+ * @returns {string}
+ */
+function addIndexLine(text, { file, title, hook }) {
+  const base = typeof text === 'string' ? text : '';
+  if (parseIndex(base).some((e) => e.file === file)) return base;
+  const line = `- [${title}](${file})${hook ? ` — ${hook}` : ''}`;
+  const trimmed = base.replace(/(\r?\n)+$/, '');
+  return `${trimmed === '' ? '' : `${trimmed}\n`}${line}\n`;
+}
+
+/**
+ * Remove every line linking to `file`; other lines are untouched.
+ * Complexity: O(lines).
+ * @param {string|null} text
+ * @param {string} file
+ * @returns {string}
+ */
+function removeIndexLines(text, file) {
+  if (typeof text !== 'string' || text === '') return '';
+  const parts = text.split('\n');
+  const hadTrailing = parts[parts.length - 1] === '';
+  if (hadTrailing) parts.pop();
+  const kept = parts.filter((raw) => {
+    const m = matchLine(raw);
+    return !(m && m[2] === file);
+  });
+  return kept.length === 0 ? '' : kept.join('\n') + (hadTrailing ? '\n' : '');
+}
+
+/**
+ * Index budget + consistency report. Complexity: O((lines + files) log n).
+ * @param {{indexText: string|null, files: string[]}} args
+ */
+function indexHealth({ indexText, files }) {
+  const text = typeof indexText === 'string' ? indexText : '';
+  const lines = splitLines(text).length;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const overBudget = lines > MAX_LINES || bytes > MAX_BYTES;
+  const nearBudget = !overBudget && (lines >= NEAR_LINES || bytes >= NEAR_BYTES);
+  const present = new Set((files || []).filter((f) => f !== 'MEMORY.md'));
+  const linked = new Set(parseIndex(text).map((e) => e.file));
+  const orphans = [...present].filter((f) => !linked.has(f)).sort();
+  const dangling = [...linked].filter((f) => f !== 'MEMORY.md' && !present.has(f)).sort();
+  return { lines, bytes, maxLines: MAX_LINES, maxBytes: MAX_BYTES, overBudget, nearBudget, orphans, dangling };
+}
+
+module.exports = { parseIndex, addIndexLine, removeIndexLines, indexHealth };

package/src/main/lib/prd/depSlugResolve.cjs

@@ -30,6 +30,21 @@ function resolveDepSlug(depSlug, candidateSlugs) {
   return candidateSlugs.filter((slug) => bareSlug(slug) === bare);
 }
 
+/**
+ * Is this dep ROW satisfied? `completed`, or a `skipped` row stamped
+ * `needsReviewAutoResolvedSkip` — the bounded needs_review auto-resolve's
+ * terminal decision (scheduler.cjs applyNeedsReviewAutoResolve), deliberately
+ * not a permanent block. Shared by schedulerBatch.findBlockingDep (dispatch)
+ * and runVerify.checkDeps (post-run): when they disagreed, the picker fired a
+ * dependent of an auto-skipped row and the verifier downgraded every finished
+ * run back to pending on "is skipped (need completed)" — an unbounded billed
+ * re-run loop (Bilko-Launch-Kit validator, ~20 runs, 2026-10-11).
+ */
+function isSatisfiedDepRow(row) {
+  return row?.status === 'completed'
+    || (row?.status === 'skipped' && row.needsReviewAutoResolvedSkip === true);
+}
+
 /**
  * Levenshtein edit distance. O(n*m) in the two strings' lengths — fine here
  * since it only ever runs over short slug strings (<= 60 chars, PRD_CREATE_SLUG_RE's
@@ -69,4 +84,4 @@ function findNearMatches(depSlug, candidateSlugs, limit = 3) {
     .map((entry) => entry.slug);
 }
 
-module.exports = { bareSlug, resolveDepSlug, findNearMatches };
+module.exports = { bareSlug, resolveDepSlug, findNearMatches, isSatisfiedDepRow };

package/src/main/lib/scheduler/finalizeReason.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * finalizeReason.cjs — the statusHistory reason for a job's running→terminal
+ * finalize transition. Pure; no I/O.
+ */
+
+/**
+ * @param {{
+ *   effectiveStatus: string,
+ *   verifyResult?: { verdict?: string, reason?: string } | null,
+ *   sigtermOverrideReason?: string | null,
+ *   exitCode?: number | null,
+ * }} input
+ * @returns {string}
+ */
+function finalizeReasonFor({ effectiveStatus, verifyResult, sigtermOverrideReason, exitCode }) {
+  if (sigtermOverrideReason) return sigtermOverrideReason;
+  if (effectiveStatus === 'completed' && verifyResult?.verdict === 'already_satisfied_on_main') {
+    return String(verifyResult.reason);
+  }
+  if (effectiveStatus === 'needs_review' && verifyResult?.verdict) {
+    return verifyResult.reason
+      ? `needs_review: ${verifyResult.verdict} — ${verifyResult.reason}`
+      : `needs_review: ${verifyResult.verdict}`;
+  }
+  return `run finished with exit ${exitCode}`;
+}
+
+module.exports = { finalizeReasonFor };

package/src/main/lib/scheduler/flatSweepThrottle.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+/** Retired flat `scheduler/prds/` sweep runs at most once per hour per process. */
+const FLAT_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+
+/**
+ * @param {number} nowMs
+ * @param {number | null} lastRunMs null = never ran this process (always run)
+ * @param {number} [intervalMs]
+ * @returns {boolean}
+ */
+function shouldRunFlatSweep(nowMs, lastRunMs, intervalMs = FLAT_SWEEP_INTERVAL_MS) {
+  if (lastRunMs === null || lastRunMs === undefined) return true;
+  return nowMs - lastRunMs >= intervalMs;
+}
+
+module.exports = { shouldRunFlatSweep, FLAT_SWEEP_INTERVAL_MS };