@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/diff-anchor.mjs

@@ -0,0 +1,213 @@
+// src/core/diff-anchor.mjs
+// The ONE anchor resolver behind POST /api/history/:key/:id/comments and the
+// add_diff_comment MCP tool. It imports the SAME parser the browser renders with:
+// ui/public/diff-view.mjs is DOM-free by design (its own header says so, and
+// test/diff-view.test.mjs already drives it under node:test), so validation and
+// rendering can never disagree — including MAX_FILE_SECTION_CODE_UNITS, where a row
+// past the cap fails validation here exactly as it fails to render there.
+//
+// This is the ONE place in src/ that reaches into ui/public. ui/server.mjs already
+// imports ./public/hljs-loader.mjs, so the direction is established; concentrating
+// it here keeps it legible. The module is NOT moved: ui/public is the only directory
+// express.static serves, so relocating it under src/ would need a new static route
+// plus edits to app.js, index.html and two test files, for nothing.
+//
+// isProtectedBasename comes from ask/tools.mjs, where it is defined and exported.
+// That direction is safe: tools.mjs has ZERO imports, so this can never close a
+// cycle.
+import { splitPatchSections, patchIndex, sectionKey, parseFileSection, MAX_FILE_SECTION_CODE_UNITS } from '../../ui/public/diff-view.mjs';
+import { isProtectedBasename } from './ask/tools.mjs';
+import { GUARDRAIL_PRESETS } from './guardrails.mjs';
+
+/** The floor, exactly as tool-deps.mjs chooses it: never the run's own set. */
+export const SECURE_PROTECTED_PATHS = Object.freeze([...GUARDRAIL_PRESETS.secure.protectedPaths]);
+
+/** A refusal the caller returns verbatim (HTTP 400 / AskToolError text). */
+export class AnchorError extends Error {
+  constructor(message) { super(message); this.name = 'AnchorError'; }
+}
+
+/**
+ * The member projects a patch declares, in order. The test is byte-identical to
+ * splitPatchSections' own rather than the stricter MEMBER_HEADER_RE in
+ * ask/tools.mjs, so this can never disagree with the sections it is checked
+ * against. Scanned from the raw text, not from the sections, so a member whose
+ * patch contributed no section is still reported.
+ */
+export function patchMembers(text) {
+  const out = [];
+  for (const line of String(text ?? '').split('\n')) {
+    if (!/^# \S/.test(line)) continue;
+    const key = line.slice(2).trim();
+    if (key && !out.includes(key)) out.push(key);
+  }
+  return out;
+}
+
+/** The section a (member, path) pair names in an ALREADY-PARSED index, or null. */
+function pick(index, member, path) {
+  return index.get(sectionKey(member || null, path)) || null;
+}
+
+/** The section a (member, path) pair names, or null. One parse per call. */
+function findSection(text, member, path) {
+  return pick(patchIndex(splitPatchSections(text)), member, path);
+}
+
+/**
+ * A section whose path this parser could NOT read. git C-quotes any name holding
+ * '"', '\\', a tab or a control byte — and, in patches persisted before
+ * core.quotePath=false was pinned (git-info.mjs:127), any non-ASCII name — as
+ * `"a/old\tsecret.pem"`. splitPatchSections keeps that literal, quotes and all
+ * (its DESCOPED note, diff-view.mjs:187-191: graceful for RENDERING), so
+ * isProtectedBasename tests the string `"a/old\tsecret.pem"` against `*.pem` and
+ * answers FALSE. get_run_diff has no such hole — splitUnifiedDiff un-C-quotes
+ * (ask/tools.mjs:23-41) — so this is the ONE place the two disagree, and it
+ * disagrees in the unsafe direction.
+ * It is reachable under an ordinary name: `rename from "old\tsecret.pem"` +
+ * `rename to plain.txt` yields a section keyed on the plain, enumerable
+ * `plain.txt` whose -/context rows are the .pem's content.
+ * A leading '"' can never begin a real path — git quotes precisely because '"'
+ * cannot appear raw — so this refuses nothing legitimate. It mirrors
+ * get_run_diff's `!s.path` drop: unreadable ⇒ dropped, never emitted.
+ */
+const unreadablePath = (p) => typeof p === 'string' && p.startsWith('"');
+
+/**
+ * Resolve one anchor against the persisted patch.
+ *
+ * The member project is an EXPLICIT input and is never inferred — not even when
+ * exactly one member holds the path: the UI always knows which section it rendered
+ * (entry.project), and the model can call get_run_diff / list_diff_comments to find
+ * out. Guessing would make the same {path, side, line} mean different things on
+ * different runs.
+ *
+ * @param {string} patchText  the diff-patch.patch artifact
+ * @param {{project?: string|null, path: string, side: 'old'|'new', line: number, protectedPaths?: string[]}} input
+ * @returns {{project: string|null, path: string, oldPath: string|null, side: 'old'|'new', line: number, lineText: string}}
+ * @throws {AnchorError}
+ */
+export function resolveAnchor(patchText, {
+  project = null, path, side, line, protectedPaths = SECURE_PROTECTED_PATHS,
+} = {}) {
+  const text = String(patchText ?? '');
+  const wantPath = typeof path === 'string' ? path.trim() : '';
+  if (!wantPath) throw new AnchorError('path is required');
+  if (side !== 'old' && side !== 'new') throw new AnchorError('side must be "old" (a removed line) or "new" (an added or context line)');
+  // NOT Math.trunc(Number(line)): that accepted 3.9 as line 3 while the message
+  // below promised an integer, silently anchoring a comment one row off. Number()
+  // still coerces the '2' a JSON-RPC client may send; isSafeInteger keeps 1e21 out.
+  const lineNo = Number(line);
+  if (!Number.isSafeInteger(lineNo) || lineNo < 1) throw new AnchorError('line must be a positive integer');
+
+  const members = patchMembers(text);
+  const member = typeof project === 'string' ? project.trim() : '';
+  if (members.length) {
+    if (!member) throw new AnchorError(`this is a workspace run — name the member project (one of: ${members.join(', ')})`);
+    if (!members.includes(member)) throw new AnchorError(`unknown member project "${member}" (members: ${members.join(', ')})`);
+  } else if (member) {
+    throw new AnchorError('this run has a single project — do not name a member project');
+  }
+  const scope = members.length ? member : null;
+
+  // ONE parse for the whole call: the not-found branch below probes every member,
+  // and findSection used to re-run splitPatchSections + patchIndex over the WHOLE
+  // patch for each of them (M+1 full parses per miss).
+  const index = patchIndex(splitPatchSections(text));
+  const guarded = (p) => !!p && isProtectedBasename(p, protectedPaths);
+  const blocked = (s) => unreadablePath(s.path) || unreadablePath(s.oldPath)
+    || guarded(s.path) || guarded(s.oldPath);
+
+  const section = pick(index, scope, wantPath);
+  if (!section) {
+    // Name the members that DO hold the path so the caller can retry without a
+    // second round trip — but only members whose section this caller could
+    // actually READ. An unfiltered hint is an existence oracle: it answered
+    // "it is in: alpha-…" for a .env that get_run_diff never lists at all.
+    const holders = members.filter((m) => {
+      if (m === member) return false;
+      const s = pick(index, m, wantPath);
+      return !!s && !blocked(s);
+    });
+    throw new AnchorError(holders.length
+      ? `"${wantPath}" is not in ${member}'s diff (it is in: ${holders.join(', ')})`
+      : `"${wantPath}" is not a file of this run's diff`);
+  }
+  // Fail closed exactly as get_run_diff does: BOTH sides, because -M makes a
+  // rename+edit ONE section under its NEW name while its -/context lines are the
+  // OLD file's content. If the model may not read a file's diff, its lines must not
+  // be smuggled into diff_comments as line_text either. splitPatchSections mirrors
+  // one side onto the other, so both fields are always populated for a section that
+  // reached patchIndex.
+  if (unreadablePath(section.path) || unreadablePath(section.oldPath)) {
+    throw new AnchorError(`"${wantPath}" has a git-quoted name this run's patch cannot resolve — it cannot be checked against the protected-path rules, so no comment is stored for it`);
+  }
+  if (guarded(section.path) || guarded(section.oldPath)) {
+    throw new AnchorError(`"${wantPath}" is a protected path — comments are not stored for credential files`);
+  }
+  const parsed = parseFileSection(section.raw);
+  if (parsed.binary || !parsed.hunks.length) throw new AnchorError(`"${wantPath}" has no textual diff to anchor to`);
+  // `lastNo` rides along in the same pass so the refusal can tell "this file has
+  // no such line" apart from "this resolver never read that far". get_run_diff
+  // applies NO cap (ask/tools.mjs pages the whole body), so a model that just read
+  // row 14,195 through it would otherwise be told the row does not exist.
+  let lastNo = 0;
+  for (const hunk of parsed.hunks) {
+    for (const row of hunk.lines) {
+      const no = side === 'old' ? row.oldNo : row.newNo;
+      if (no === lineNo) {
+        return { project: scope, path: wantPath, oldPath: section.oldPath ?? null, side, line: lineNo, lineText: row.text };
+      }
+      if (no != null && no > lastNo) lastNo = no;
+    }
+  }
+  throw new AnchorError(parsed.truncated && lineNo > lastNo
+    ? `"${wantPath}" has no ${side}-side line ${lineNo} in the first ${MAX_FILE_SECTION_CODE_UNITS} characters of its diff — that is as far as this file's section is read here (it stops at ${side}-side line ${lastNo}), so a line beyond the cap cannot be anchored even though get_run_diff can page to it`
+    : `"${wantPath}" has no ${side}-side line ${lineNo} in this run's diff`);
+}
+
+/**
+ * The section keys of `patchText` the floor will always refuse, in the same
+ * `sectionKey(project, path)` form the browser indexes file rows by. Same parser,
+ * same preset, BOTH sides (a rename+edit is ONE section under its new name while
+ * its −/context lines are the old file's content) — so the UI can drop the '+'
+ * without ever seeing the glob list. `[]` for an absent or empty patch.
+ */
+export function protectedSectionKeys(patchText, protectedPaths = SECURE_PROTECTED_PATHS) {
+  const guarded = (p) => !!p && isProtectedBasename(p, protectedPaths);
+  const out = [];
+  for (const s of splitPatchSections(String(patchText ?? ''))) {
+    if (!s.path) continue;
+    if (unreadablePath(s.path) || unreadablePath(s.oldPath) || guarded(s.path) || guarded(s.oldPath)) {
+      out.push(sectionKey(s.project || null, s.path));
+    }
+  }
+  return out;
+}
+
+/**
+ * The `radius` rows either side of an anchor, rendered with their diff sign so the
+ * model reads them the way get_run_diff serves them (parseFileSection strips the
+ * sign into `kind`, so it is re-added here). Produced by the SAME parser as
+ * everything else; `[]` whenever no readable section or no matching row exists
+ * (archived run, binary, a row past the cap), which is the caller's signal to omit
+ * context entirely rather than fake it.
+ * NOT redacted here — the caller redacts, exactly once, at its own boundary.
+ */
+export function hunkContext(patchText, { project = null, path, side, line } = {}, radius = 3) {
+  const text = String(patchText ?? '');
+  const members = patchMembers(text);
+  const section = findSection(text, members.length ? (project || '') : null, String(path ?? ''));
+  if (!section) return [];
+  const parsed = parseFileSection(section.raw);
+  const lineNo = Math.trunc(Number(line));
+  const sign = (kind) => (kind === 'add' ? '+' : kind === 'del' ? '-' : ' ');
+  for (const hunk of parsed.hunks) {
+    const at = hunk.lines.findIndex((r) => (side === 'old' ? r.oldNo : r.newNo) === lineNo);
+    if (at < 0) continue;
+    const from = Math.max(0, at - radius);
+    const to = Math.min(hunk.lines.length, at + radius + 1);
+    return hunk.lines.slice(from, to).map((r) => `${sign(r.kind)}${r.text}`);
+  }
+  return [];
+}

package/src/core/diff-comments.mjs

@@ -0,0 +1,273 @@
+// src/core/diff-comments.mjs
+// Internal, line-anchored comments on a run's persisted diff (diff_comments, v22).
+// The ONE mutation module: the REST routes in ui/server.mjs and the Ask MCP tools
+// (through src/core/ask/comment-deps.mjs) both write through here, so anchor
+// validation, the protected-path floor, the body cap and the change notification
+// can never drift apart. Synchronous DB via getDb()/prepare() — the
+// src/core/ask/store.mjs conventions; ids are shape-checked before use.
+//
+// NOTE on the notification: listeners are PROCESS-LOCAL. ui/server.mjs subscribes
+// at boot and turns each poke into a `diff-comments-changed` broadcast. The MCP
+// stdio server is a separate OS process with its own module instance, so its writes
+// fire only its own (empty) listener set — those reach the UI through the reducer
+// hook in ask/events.mjs instead.
+import { randomBytes } from 'node:crypto';
+import { getDb, prepare, tx } from './db.mjs';
+import { resolveAnchor, AnchorError } from './diff-anchor.mjs';
+
+export const DC_ID_RE = /^dc_[0-9a-f]{8}$/;
+export const COMMENT_BODY_MAX = 4000;
+export const COMMENT_AUTHORS = Object.freeze(['user', 'ask']);
+
+const newCommentId = () => `dc_${randomBytes(4).toString('hex')}`;
+const now = () => new Date().toISOString();
+
+/** A refusal the caller returns verbatim (HTTP 400/409, AskToolError text). */
+export class DiffCommentError extends Error {
+  constructor(message) { super(message); this.name = 'DiffCommentError'; }
+}
+
+function rowToComment(r) {
+  return {
+    id: r.id, storeKey: r.store_key, pipelineId: r.pipeline_id,
+    projectKey: r.project_key ?? null, path: r.path, oldPath: r.old_path ?? null,
+    side: r.side, line: r.line_no, lineText: r.line_text ?? '',
+    body: r.body, author: r.author,
+    resolved: !!r.resolved, resolvedAt: r.resolved_at ?? null,
+    sentRunId: r.sent_run_id ?? null, createdAt: r.created_at,
+  };
+}
+
+// ── change notification ─────────────────────────────────────────────────────
+const listeners = new Set();
+
+/** Subscribe to "this run's comments changed". Returns an unsubscribe function. */
+export function onDiffCommentsChanged(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+/** ids only, no payload: idempotent for the receiver, no ordering concerns. */
+function notify(storeKey, pipelineId) {
+  for (const fn of listeners) {
+    try { fn({ storeKey, pipelineId }); } catch { /* a broken sink never breaks a write */ }
+  }
+}
+
+// ── reads ───────────────────────────────────────────────────────────────────
+
+/** One comment by id, or null. Shape-checks the id: it reaches a SQL parameter only. */
+export function getDiffComment(id) {
+  if (typeof id !== 'string' || !DC_ID_RE.test(id)) return null;
+  getDb();
+  const r = prepare('SELECT * FROM diff_comments WHERE id = ?').get(id);
+  return r ? rowToComment(r) : null;
+}
+
+/**
+ * A run's comments, ordered by path, then line, then CREATION ORDER (the brief:
+ * multiple comments on one line stack in creation order).
+ *
+ * The final key is `rowid`, NOT `created_at, id`: created_at is millisecond ISO
+ * text, so two comments written in the same tick tie, and `id` is random hex — the
+ * pair would order those two randomly. rowid is SQLite's monotonic insertion
+ * counter and the table is not WITHOUT ROWID (D17).
+ *
+ * The SQL is assembled from a CLOSED set of fragments (3 statuses x 2 path
+ * options = 6 texts), so the prepare() cache stays bounded; no caller value is ever
+ * interpolated.
+ * @param {{status?: 'all'|'unresolved'|'resolved', path?: string|null}} [opts]
+ */
+export function listDiffComments(storeKey, pipelineId, { status = 'all', path = null } = {}) {
+  getDb();
+  const where = ['store_key = ?', 'pipeline_id = ?'];
+  const vals = [String(storeKey ?? ''), String(pipelineId ?? '')];
+  if (status === 'unresolved') where.push('resolved = 0');
+  else if (status === 'resolved') where.push('resolved = 1');
+  if (path) { where.push('path = ?'); vals.push(String(path)); }
+  return prepare(`SELECT * FROM diff_comments WHERE ${where.join(' AND ')}
+                  ORDER BY path, line_no, rowid`).all(...vals).map(rowToComment);
+}
+
+/** Unresolved counts keyed "<storeKey>/<pipelineId>", newest-commented first and
+ *  hard-capped: the endpoint fans out to every open tab on every poke, and an
+ *  unbounded row-per-commented-run response is the one part of it that grows with
+ *  history. 5000 is a backstop, not a paging story — /api/history is itself
+ *  unbounded, so anything the cap drops belongs to a card far below the fold. */
+export function unresolvedCounts() {
+  getDb();
+  const out = {};
+  for (const r of prepare(`SELECT store_key, pipeline_id, count(*) AS n, max(rowid) AS last
+                           FROM diff_comments WHERE resolved = 0
+                           GROUP BY store_key, pipeline_id
+                           ORDER BY last DESC LIMIT 5000`).all()) {
+    out[`${r.store_key}/${r.pipeline_id}`] = r.n;
+  }
+  return out;
+}
+
+// ── writes ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create one comment. `patchText` is the run's diff-patch.patch as READ BY THE
+ * CALLER (the server through readRunArtifactText, the MCP bundle through
+ * deps.readDiffPatch) — the anchor, and the line_text snapshot, come from it and
+ * never from the caller's input.
+ * @throws {DiffCommentError} — including for an AnchorError, re-wrapped so callers
+ *   have one error type to map onto 400 / tool-error.
+ */
+export function addDiffComment({
+  storeKey, pipelineId, patchText, project = null, path, side, line, body, author,
+} = {}) {
+  if (patchText == null || String(patchText) === '') {
+    throw new DiffCommentError('this run has no stored diff — comments cannot be created on it');
+  }
+  if (!COMMENT_AUTHORS.includes(author)) throw new DiffCommentError('author must be "user" or "ask"');
+  const text = typeof body === 'string' ? body.trim() : '';
+  if (!text) throw new DiffCommentError('body is required');
+  if (text.length > COMMENT_BODY_MAX) throw new DiffCommentError(`body exceeds ${COMMENT_BODY_MAX} characters`);
+
+  let anchor;
+  try {
+    anchor = resolveAnchor(patchText, { project, path, side, line });
+  } catch (err) {
+    throw err instanceof AnchorError ? new DiffCommentError(err.message) : err;
+  }
+
+  const id = newCommentId();
+  const ts = now();
+  getDb();
+  prepare(`INSERT INTO diff_comments
+    (id, store_key, pipeline_id, project_key, path, old_path, side, line_no, line_text,
+     body, author, resolved, resolved_at, sent_run_id, source, external_url, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, NULL, NULL, NULL, ?)`)
+    .run(id, String(storeKey), String(pipelineId), anchor.project, anchor.path, anchor.oldPath,
+      anchor.side, anchor.line, anchor.lineText, text, author, ts);
+  notify(String(storeKey), String(pipelineId));
+  return getDiffComment(id);
+}
+
+/** Toggle. Returns the updated comment, or null when the id is unknown. */
+export function setDiffCommentResolved(id, resolved = true) {
+  const before = getDiffComment(id);
+  if (!before) return null;
+  const on = resolved !== false;
+  getDb();
+  prepare('UPDATE diff_comments SET resolved = ?, resolved_at = ? WHERE id = ?')
+    .run(on ? 1 : 0, on ? now() : null, id);
+  notify(before.storeKey, before.pipelineId);
+  return getDiffComment(id);
+}
+
+/** Hard delete. true when a row went away. */
+export function deleteDiffComment(id) {
+  const before = getDiffComment(id);
+  if (!before) return false;
+  getDb();
+  const info = prepare('DELETE FROM diff_comments WHERE id = ?').run(id);
+  if (!info.changes) return false;
+  notify(before.storeKey, before.pipelineId);
+  return true;
+}
+
+/**
+ * Stamp `sent_run_id` on every id given. NEVER resolves anything (the brief).
+ * SCOPED to the launched run's store: a comment on project A's run can never be
+ * marked "sent to" a run in project B (nothing ever un-stamps it, so a wrong
+ * marker is permanent). The card's target is NOT authoritative here — the Start
+ * form lets the user re-pick the project/workspace — so the scope comes from the
+ * pipelines row that actually exists by now.
+ * Notifies per DISTINCT comment run, and OUTSIDE the tx: the poke names the run
+ * whose Diff tab shows the marker (its own), not the run it was sent to, and a
+ * listener must never run while the write lock is held (tx() is not re-entrant).
+ * @returns {number} rows stamped
+ */
+export function stampSentRunId(commentIds, pipelineId) {
+  const ids = (Array.isArray(commentIds) ? commentIds : []).filter((s) => typeof s === 'string' && DC_ID_RE.test(s));
+  const pid = typeof pipelineId === 'string' ? pipelineId : '';
+  if (!ids.length || !pid) return 0;
+  getDb();
+  const { n, storeKey: sk, targets } = tx(() => {
+    const run = getDb().prepare('SELECT project_key, workspace_key, target FROM pipelines WHERE id = ?').get(pid);
+    if (!run) return { n: 0, storeKey: null, targets: [] };
+    // SAME formula as artifacts.mjs (`target === 'workspace' && workspace_key`): with
+    // `||` a project row that merely carries a workspace_key was stamped against a
+    // store it does not live in and the comment was never marked (review of PR #376).
+    const storeKey = (run.target === 'workspace' && run.workspace_key) ? `workspaces/${run.workspace_key}` : run.project_key;
+    const stmt = getDb().prepare('UPDATE diff_comments SET sent_run_id = ? WHERE id = ? AND store_key = ?');
+    const read = getDb().prepare('SELECT pipeline_id FROM diff_comments WHERE id = ?');
+    // A stamped row matched `store_key = storeKey`, so its store is already known;
+    // only its own run id varies, and that is what the poke has to name.
+    const runs = new Set();
+    let hits = 0;
+    for (const id of ids) {
+      if (!stmt.run(pid, id, storeKey).changes) continue;
+      hits += 1;
+      const r = read.get(id);
+      if (r) runs.add(r.pipeline_id);
+    }
+    return { n: hits, storeKey, targets: [...runs] };
+  });
+  for (const runId of targets) notify(sk, runId);
+  return n;
+}
+
+/**
+ * Delete every comment of a run. NO transaction of its own — the CALLER owns it
+ * (db.mjs tx() is not re-entrant and throws on nesting, and archivePipeline calls
+ * this from inside its own tx). Used only by the archive path.
+ */
+export function deleteCommentsForRun(pipelineId) {
+  getDb();
+  return getDb().prepare('DELETE FROM diff_comments WHERE pipeline_id = ?').run(String(pipelineId)).changes;
+}
+
+// ── proposal → launch hand-off (D11) ────────────────────────────────────────
+
+/**
+ * Record the comment ids a proposal card is meant to address. Called from the
+ * turn's proposal hook, which is the only place that sees propose_run's raw input:
+ * commentIds deliberately never enter the card block (its key set is pinned in
+ * test/ask-proposal.test.mjs) nor CARD_PATCH_KEYS. Unknown ids are dropped
+ * silently — the model may cite a comment the user deleted in the meantime, and
+ * that must not sink the proposal.
+ */
+export function setPendingCardComments(cardId, commentIds) {
+  const card = typeof cardId === 'string' ? cardId.trim() : '';
+  const ids = (Array.isArray(commentIds) ? commentIds : []).filter((s) => typeof s === 'string' && DC_ID_RE.test(s));
+  if (!card || !ids.length) return 0;
+  getDb();
+  return tx(() => {
+    const stmt = getDb().prepare('INSERT OR IGNORE INTO ask_card_comments (card_id, comment_id, created_at) VALUES (?, ?, ?)');
+    const known = getDb().prepare('SELECT 1 AS ok FROM diff_comments WHERE id = ?');
+    const ts = now();
+    let n = 0;
+    for (const id of ids) {
+      if (!known.get(id)) continue;
+      n += stmt.run(card, id, ts).changes;
+    }
+    return n;
+  });
+}
+
+/**
+ * The pending ids of a card, WITHOUT consuming them. Split from the delete so the
+ * caller can write them onto ask_run_links first and only then drop them: the
+ * consumer's catch merely logs, so a combined take-then-write loses the ids for good
+ * if the write throws.
+ */
+export function peekPendingCardComments(cardId) {
+  const card = typeof cardId === 'string' ? cardId.trim() : '';
+  if (!card) return [];
+  getDb();
+  return getDb().prepare('SELECT comment_id FROM ask_card_comments WHERE card_id = ? ORDER BY rowid')
+    .all(card).map((r) => r.comment_id);
+}
+
+/** Drop a card's pending ids once they are safely on the link row. */
+export function clearPendingCardComments(cardId) {
+  const card = typeof cardId === 'string' ? cardId.trim() : '';
+  if (!card) return 0;
+  getDb();
+  return getDb().prepare('DELETE FROM ask_card_comments WHERE card_id = ?').run(card).changes;
+}

package/src/core/engine-select.mjs

@@ -0,0 +1,32 @@
+// src/core/engine-select.mjs
+// One engine remains. The only decision left is refusing a run/resume that was
+// pinned to the retired v1 engine.
+
+import { createOrchestrator } from './orchestrator.mjs';
+import { V1_RUN_RETIRED } from './db.mjs';
+
+export class EngineRetiredError extends Error {
+  constructor() { super(V1_RUN_RETIRED); this.code = 'ENGINE_RETIRED'; this.status = 409; }
+}
+
+/**
+ * Build the orchestrator this run needs. Still ASYNC (every call site awaits it)
+ * and still accepts `opts.template` as a routing HINT that is never forwarded as
+ * an orchestrator option.
+ * @param {object} opts createOrchestrator options (+ optional opts.resume / opts.template)
+ * @returns {Promise<object>} a graph orchestrator, `.engine === 'graph'`
+ * @throws {EngineRetiredError} when the resume point is not a graph point
+ */
+export async function createOrchestratorFor(opts = {}) {
+  const { template, ...rest } = opts;
+  const rpVersion = rest?.resume?.resumePoint?.version;
+  // A resume must run on the engine that FROZE the point. Only `version: 2` is
+  // resumable now; `undefined` means "no point at all" (a fresh run) and falls
+  // through, but a point that carries any OTHER version — including an
+  // unversioned `null` blob the v1 engine wrote — is refused rather than
+  // silently re-planned on the graph engine.
+  if (rpVersion !== undefined && Number(rpVersion) !== 2) throw new EngineRetiredError();
+  const orch = createOrchestrator(rest);
+  orch.engine = 'graph';   // the only answer there is; kept observable for callers and tests
+  return orch;
+}