@cstart/coldstart 2.1.1 → 2.2.0

package/hooks/cursor-kb-elicit.mjs

@@ -1,38 +1,48 @@
 #!/usr/bin/env node
 /**
- * cursor-kb-elicit.mjs — Cursor stop + subagentStop notebook capture.
+ * cursor-kb-elicit.mjs — Cursor stop + subagentStop notebook capture, v5
+ * TRIGGER-TIMED (ported from kb-elicit.mjs 2026-07-17; the v4 always-fire
+ * walker is gone).
  *
- * ALWAYS FIRES when the agent touched ANY repo file this turn (mechanical
- * extraction only; THE AGENT decides what's worth writing). Same policy as
- * codex-kb-elicit.mjs — see it for the full rationale. The shared helpers
- * (buildCapturePrompt, filesBlock, noteAnnotations, the path scan, normRel) are
- * copied verbatim; only three things are Cursor-specific:
+ * Cursor's stop fires per turn (like Claude's Stop), so the FULL trigger
+ * machine applies: every stop updates per-file evidence records
+ * (evidence.mjs extractCursorEvidence — edit/read/gs tiers; mentions and
+ * .coldstartignore'd files never count) and advances trigger.mjs. Most stops
+ * exit silently. Fires:
  *
- *   1. TRANSCRIPT WALK — Cursor's transcript is JSONL of
- *        {role, message:{content:[{type:"tool_use", input}]}}   (+ {type:"turn_ended"})
- *      not Codex's response_item rollout. We stringify each tool_use.input and run
- *      the SAME path-token scan (Read → input.path, Shell → input.command, MCP →
- *      tool-specific), so detection stays tool-agnostic. Scoped to the CURRENT
- *      turn via the free `turn_ended` boundary.
- *   2. RE-ENTRANCY GUARD — Cursor's followup_message re-fires `stop` on a NEW
- *      generation, so a per-generation marker alone can't stop the loop. But
- *      loop_count increments (0 = the user's own turn, >0 = a hook-continued
- *      turn), so we capture ONLY when loop_count === 0. Proven empirically
- *      2026-07-08. The generation_id marker is a belt-and-suspenders against a
- *      double-fire within one turn.
- *   3. OUTPUT — Cursor's stop/subagentStop "continue" channel is
- *      `{followup_message}` (auto-submits the next turn), not Codex's
- *      `{decision:"block", reason}`.
+ *   descent/surge → NON-BLOCKING: payload → pending file; cursor-kb-recall
+ *     (beforeSubmitPrompt) delivers it with the user's next prompt via
+ *     additional_context.
+ *   cap → also non-blocking (same rationale as the Claude hook: replay showed
+ *     dense sessions starve descent; blocking each cap re-created v4 agitation).
+ *   head-drift → BLOCKING via {followup_message} (commit boundary: the work
+ *     just landed, capture before it goes stale).
+ *   subagentStop → one-shot BLOCKING with the restate-deliverable tail (#61).
+ *
+ * Cursor specifics vs the Claude hook:
+ *   - Input: root from workspace_roots (cursor-input.mjs); loop_count>0 =
+ *     hook-continued turn → never process (replaces stop_hook_active).
+ *   - Transcript: conversation JSONL with NO tool_result records — evidence is
+ *     call-level, compensated by stat-existence checks on every claim (see
+ *     extractCursorEvidence). Sliced incrementally by lineCount, same as Claude.
+ *   - Output: block = {followup_message} (auto-submits a continuation turn);
+ *     silence = plain exit 0.
  *
- * Hooks never author or parse markdown — all facts come from `coldstart kb`.
  * Self-contained + fail-open: ANY error → exit 0 → the stop is allowed.
  */
 
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
-import { existsSync, writeFileSync, appendFileSync, readFileSync, mkdirSync, statSync } from "node:fs";
+import { existsSync, writeFileSync, appendFileSync, readFileSync } from "node:fs";
+
+import { extractCursorEvidence, segmentStatsCursor } from "./evidence.mjs";
+import { initialState, step } from "./trigger.mjs";
+import { loadIgnore } from "./ignore.mjs";
+import { buildCapturePayload } from "./capture-payload.mjs";
+import {
+  worklistEntries, freshNotedSet, gitHead, logCaptureEvent, writePendingCapture,
+} from "./elicit-core.mjs";
 import { cursorRoot } from "./cursor-input.mjs";
 
 // hooks/ sits beside dist/ in both the repo and the published package.
@@ -45,222 +55,7 @@ function log(msg) {
   try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] elicit: ${msg}\n`); } catch { /* never fail logging */ }
 }
 
-// --- Touched-file detection ----------------------------------------------------
-function normRel(root, p) {
-  let s = String(p || "").trim();
-  if (!s) return "";
-  if (s.startsWith("/")) {
-    if (root && s.startsWith(root + "/")) return s.slice(root.length + 1);
-    return "";
-  }
-  return s.replace(/^\.\//, "");
-}
-
-// Path-like tokens inside any tool input. Existence under root is checked by the
-// caller, so structured paths (Read input.path), shell command strings (Shell
-// input.command), and MCP JSON can all be scanned without depending on a
-// particular tool implementation.
-const BASH_PATH_RE = /(?:^|[\s"'`=(:;|])((?:\.{1,2}\/|\/)?[A-Za-z0-9_][A-Za-z0-9_.\/-]*\.[A-Za-z0-9]{1,8})(?=$|[\s"'`):;,|>])/gm;
-
-// The transcript accumulates the whole conversation; capture only the CURRENT
-// turn. Turns are delimited by {type:"turn_ended"}; the final such record is
-// this turn's own terminator, so scope to records AFTER the previous one.
-function currentTurnLines(lines) {
-  let boundary = -1;
-  for (let i = 0; i < lines.length - 1; i++) {
-    if (lines[i].includes('"turn_ended"')) boundary = i;
-  }
-  return lines.slice(boundary + 1);
-}
-
-function touchedFiles(transcriptPath, root) {
-  const out = [];
-  const seen = new Set();
-  const add = (rel, mustExist) => {
-    if (!rel || seen.has(rel) || rel.startsWith(".coldstart/")) return;
-    if (mustExist) {
-      try { if (!statSync(join(root, rel)).isFile()) return; } catch { return; }
-    }
-    seen.add(rel);
-    out.push(rel);
-  };
-  let text = "";
-  try { text = readFileSync(transcriptPath, "utf8"); } catch { return out; }
-  const lines = text.split("\n").filter((l) => l.trim() && l[0] === "{");
-  for (const line of currentTurnLines(lines)) {
-    let rec;
-    try { rec = JSON.parse(line); } catch { continue; }
-    const content = rec && rec.message && rec.message.content;
-    if (!Array.isArray(content)) continue;
-    for (const item of content) {
-      if (!item || item.type !== "tool_use") continue;
-      const source =
-        item.input && typeof item.input === "object" ? JSON.stringify(item.input) : String(item.input || "");
-      if (!source) continue;
-      for (const g of source.matchAll(/coldstart\s+gs\s+([^\s"'`]+)/g)) add(normRel(root, g[1]), true);
-      let n = 0;
-      for (const m of source.matchAll(BASH_PATH_RE)) {
-        if (++n > 40) break;
-        add(normRel(root, m[1]), true);
-      }
-    }
-  }
-  return out;
-}
-
-// --- Per-file annotations from the core (hooks never parse md) -----------------
-function noteAnnotations(root, files) {
-  try {
-    const raw = execFileSync(
-      "node", [CLI, "kb", "status", "--json", "--paths", files.join(","), "--root", root],
-      { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] },
-    );
-    const parsed = JSON.parse(raw);
-    const byPath = new Map();
-    for (const entry of parsed.paths || []) byPath.set(entry.path, entry.notes || []);
-    return byPath;
-  } catch (e) {
-    log(`kb status unavailable (${String(e).split("\n")[0]}) — annotating as no-notes`);
-    return new Map();
-  }
-}
-
-const MAX_PROMPT_FILES = 30;
-
-function filesBlock(root, files) {
-  const notes = noteAnnotations(root, files);
-  let listed = files;
-  if (files.length > MAX_PROMPT_FILES) {
-    const noted = files.filter((f) => (notes.get(f) || []).length);
-    const bare = files.filter((f) => !(notes.get(f) || []).length);
-    listed = [...noted, ...bare].slice(0, MAX_PROMPT_FILES);
-  }
-  const lines = [];
-  for (const rel of listed) {
-    const anchored = notes.get(rel) || [];
-    if (!anchored.length) { lines.push(`- ${rel}   [no notes yet]`); continue; }
-    const parts = anchored.map((n) => {
-      const flag = n.state === "changed" || n.state === "missing"
-        ? ` — FLAGGED STALE: you just read this file, so fix or re-stamp it (list the path in "verified")`
-        : "";
-      return `${n.id} [${n.type} · ${n.state}]${flag} (.coldstart/notebook/notes/${n.id}.md)`;
-    });
-    lines.push(`- ${rel}   has notes: ${parts.join("; ")}`);
-  }
-  if (listed.length < files.length) lines.push(`- …and ${files.length - listed.length} more touched files`);
-  return lines.join("\n");
-}
-
-// --- The capture prompt (kept identical to the Codex/Claude capture prompt) ----
-function buildCapturePrompt(root, block, sid, isSubagent) {
-  return `You have completed a task now and have gathered knowledge as a part of that task or \
-process — knowledge another agent in future could make use of.
-
-But before writing any notes, we need to decide whether the task you completed deserves a note. \
-If you were investigating on an older branch or doing a PR review, we may not need to save notes \
-because that code is not in the present — it's in the past or it's in the future. The notes that \
-we write are backed by the code in the present. This was an example to explain to you. As an \
-agent who worked on the current task, you know its exact intent and are best suited to decide \
-whether this task deserves a note. And if nothing about the current code is worth recording, \
-then no note is the right answer.
-
-Once you decide the task does deserve a note, we store it in a notebook format, and this \
-notebook has to be backed by the codebase you are working on.
-
-We need to save only the working knowledge of the codebase in a specific format so that it can \
-be searched and served to future cold agents. We don't need to store any general interaction you \
-had, just the knowledge about the codebase. As a part of your task, you must have done some \
-investigation, file reading, new file/feature addition or updated existing files or features. It \
-could have been a bug fix or any other operation on the codebase. We need to store it in the \
-below format —
-
-THE NOTEBOOK HAS THREE CONTAINERS. Put each piece of knowledge in its one home:
-
-1. FILE notes (if you decided to write a note for the entire task) — write one for EVERY file \
-you actually read and understood this session. No judgment call about whether it seems obvious. \
-First decide the file's CHARACTER:
-   - hub    = the file has no single purpose (models.py, helpers, utils). Knowledge lives per \
-SYMBOL, as facets: one facet for each symbol you worked with this session. Only symbols you \
-have firsthand knowledge of — never enumerate the rest.
-   - single = the file has one purpose. One summary, 1-3 sentences.
-   The best facet/summary says: what it does that the name doesn't tell you, what to watch out \
-for when changing it, and which tests or checks matter.
-
-2. FLOW notes — when your task traced how something works ACROSS files: the ordered story. Each \
-step points at a file (path + symbols) with its role in the story. A step never restates what a \
-file note already says — the detail lives in the file's facet; the flow links to it.
-
-3. LESSON notes — rare. Only one thing qualifies:
-   - a confirmed ABSENCE ("there is no X in this repo"), with the search terms that proved it.
-   If it is about one file or one symbol, it is a facet, not a lesson. Repo-wide rules and \
-conventions are the human's to define (CLAUDE.md / coldstart.md / AGENTS.md) — do not mint them here.
-
-Fixed a bug? The actual cause goes into the culpable file's facet, and the SYMPTOM words go \
-into that file note's "aliases" — the symptom is what a future agent will search. If the cause \
-spans files, the story is a flow.
-
-Read a note this session that turned out WRONG? Correct it now — same spec with its "id" \
-(fields merge; yours win), or op "retract" for a wrong claim. You are the warm agent; there is \
-no "next".
-
-RULES:
-- Codebase knowledge only — never the interaction, the user, or your own process.
-- Firsthand only: if it arrived secondhand (e.g. a subagent's report) and you did not verify it \
-yourself, do not store it.
-- If a future agent would not act differently for knowing it, do not store it.
-- SEARCH BEFORE YOU WRITE a flow or lesson: run \`node ${CLI} kb search "<your task words>" \
---root ${root}\` once. If an existing flow already tells this mechanism's story, UPDATE it \
-(same spec with its "id") instead of writing a near-duplicate.
-- Note ids are never composed by you. In facet "flows" backlinks, reference a flow by its \
-EXACT title (as written in your flow spec) or by an id copied from kb search output — the \
-tool resolves titles to ids at write time. A typo prints a WARNING (the ref is kept but \
-dangling) — fix any warning the write prints, in this session. Never guess an id.
-- "verified": list every anchor path you actually read THIS session — that re-stamps its \
-freshness. Never list a file you did not open.
-- Paths are join keys: always repo-relative, exactly as they appear in the repo. Fix any path \
-warning the write prints — a wrong path is a silently dangling link.
-
-Files you touched this run, with their existing notes (read one before writing if you need to \
-see what it already says — never create a second note for the same file):
-
-${block}
-
-HOW TO WRITE — ONE terminal block TOTAL: author every spec with a heredoc and
-chain every write in the SAME block, flows before the file notes that
-reference them. Never author specs one-per-message with a file-editing tool —
-that is the single biggest waste of turns here.
-
-  cat > /tmp/spec-1.json <<'SPEC'
-  { ...flow... }
-SPEC
-  cat > /tmp/spec-2.json <<'SPEC'
-  { ...file note; facets reference the flow by its EXACT title... }
-SPEC
-  node ${CLI} kb write /tmp/spec-1.json --root ${root} --session ${sid} --force && \\
-  node ${CLI} kb write /tmp/spec-2.json --root ${root} --session ${sid} --force
-Chain the writes with && — if a flow write fails, its dependent file notes
-must not run. Never write the same note id twice.
-
-Spec shapes (only include fields you actually have):
-  file (hub):    {"type":"file-hub","path":"src/x.py","aliases":["symptom or search words"],
-                  "facets":[{"symbol":"ClassOrFn","detail":"the non-obvious thing about THIS symbol",
-                             "flows":["<flow-note-id or the flow's exact title>"]}]}
-  file (single): {"type":"file-single","path":"src/x.py",
-                  "summary":"its one purpose + how (1-3 sentences)"}
-  flow:          {"type":"flow","title":"how X happens","aliases":["other words for X"],
-                  "summary":"one paragraph",
-                  "steps":[{"path":"src/a.py","symbols":["entry"],"role":"receives the request"}],
-                  "invariants":["what must hold"],"verified":["src/a.py"]}
-  lesson:        {"type":"lesson","kind":"absence","title":"the absence, e.g. no retry logic",
-                  "body":"what you looked for + that it is not there",
-                  "scope":{"terms":["search","terms"]}}          (the search that proved it)
-
-${isSubagent
-  ? `Once you have handled the notebook — whether you wrote notes or decided none were needed — remember you were spawned as a subagent. The coordinator that spawned you receives ONLY your final message, so your last message must repeat, in full, the result you produced for it — your findings, not the notebook decision.`
-  : `When your notes are written, stop.`}`;
-}
-
-// --- stdin + guards -------------------------------------------------------------
+// --- stdin ---------------------------------------------------------------------
 function readStdin() {
   return new Promise((res) => {
     let data = "";
@@ -277,14 +72,6 @@ function readStdin() {
   });
 }
 
-function logCaptureEvent(root, event) {
-  try {
-    const dir = join(root, ".coldstart", "notebook", ".metrics");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "capture.jsonl"), JSON.stringify({ ts: new Date().toISOString(), ...event }) + "\n");
-  } catch { /* metrics never wedge a stop */ }
-}
-
 process.on("uncaughtException", (e) => { log(`uncaught ${e?.stack || e}`); process.exit(0); });
 process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); process.exit(0); });
 
@@ -300,25 +87,30 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     setLogRoot(root);
     if (!root) { log("SKIP no-root"); process.exit(0); }
 
-    // Re-entrancy guard (see header): capture only on the user's own turn.
+    // Hook-continued turn (followup_message re-fires stop on a new generation):
+    // never process — the capture turn's own stop must not advance the trigger.
     const lc = typeof input.loop_count === "number" ? input.loop_count : 0;
     if (lc > 0) { log(`SKIP hook-continuation loop_count=${lc}`); process.exit(0); }
 
     const sid = String(input.session_id || "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!sid) { log("SKIP no-session-id"); process.exit(0); }
-    // generation_id is unique per turn; dedupe a double-fire within one turn.
-    const tid = String(input.generation_id || sid).replace(/[^A-Za-z0-9_-]/g, "") || sid;
 
-    const event = String(input.hook_event_name || "");
     const aid = String(input.subagent_id || input.agent_id || "main").replace(/[^A-Za-z0-9_-]/g, "") || "main";
-    const marker = join(tmpdir(), `coldstart-cursor-kb-${tid}-${aid}.done`);
-    if (existsSync(marker)) { log(`SKIP already-elicited session=${sid} agent=${aid}`); process.exit(0); }
-    try { writeFileSync(marker, String(Date.now())); } catch { /* best effort */ }
+    const isSubagent = String(input.hook_event_name || "") === "subagentStop";
+
+    // Belt-and-suspenders vs a double-fire within one turn: generation_id is
+    // unique per turn; a second stop for the same generation is a duplicate.
+    const tid = String(input.generation_id || "").replace(/[^A-Za-z0-9_-]/g, "");
+    if (tid) {
+      const turnMarker = join(tmpdir(), `coldstart-cursor-kb-turn-${tid}-${aid}.done`);
+      if (existsSync(turnMarker)) { log(`SKIP duplicate-generation ${tid}`); process.exit(0); }
+      try { writeFileSync(turnMarker, String(Date.now())); } catch { /* best effort */ }
+    }
 
     // subagentStop supplies the child's own transcript as agent_transcript_path;
     // stop's transcript_path is the main conversation JSONL.
     let transcriptPath = String(input.transcript_path || "");
-    if (event === "subagentStop") {
+    if (isSubagent) {
       const own = String(input.agent_transcript_path || "");
       if (!own || !existsSync(own)) {
         log(`SKIP subagent-transcript-missing session=${sid} agent=${aid} tried=${own || "n/a"}`);
@@ -326,20 +118,83 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       }
       transcriptPath = own;
     }
-    // transcript_path is null on a brand-new conversation's first events. Fail
-    // open: nav/recall still work, capture just has no evidence this turn.
-    const files = transcriptPath && existsSync(transcriptPath) ? touchedFiles(transcriptPath, root) : [];
+    if (!transcriptPath || !existsSync(transcriptPath)) { log("SKIP no-transcript"); process.exit(0); }
+
+    const ignore = loadIgnore(root);
+    const marker = join(tmpdir(), `coldstart-cursor-kb-${sid}-${aid}.json`);
+    let state = null;
+    try {
+      const parsed = JSON.parse(readFileSync(marker, "utf8"));
+      if (parsed && parsed.v === 2) state = parsed;
+    } catch { /* first stop of this session (or a pre-v5 marker: start fresh) */ }
+    if (!state) state = initialState();
+
+    // This stop's transcript slice (everything since the last processed line).
+    const text = readFileSync(transcriptPath, "utf8");
+    const lines = text.split("\n");
+    const segment = lines.slice(state.lineCount).join("\n");
+    state.lineCount = lines.length;
+
+    // Evidence: contentRead tiers only, ignore-filtered. Mentions never count.
+    const raw = extractCursorEvidence(segment, root);
+    const delta = new Map();
+    for (const [rel, r] of raw) {
+      if (r.reads + r.edits + r.gs === 0) continue;
+      if (ignore(rel)) continue;
+      delta.set(rel, r);
+    }
+
+    // --- Subagent path: one-shot, no trigger. Offer once, block-deliver. ------
+    if (isSubagent) {
+      const offered = new Set(Object.keys(state.files));
+      const fresh = [...delta.keys()].filter((rel) => !offered.has(rel));
+      for (const rel of fresh) state.files[rel] = { ...delta.get(rel), captured: true };
+      writeFileSync(marker, JSON.stringify(state));
+      if (!fresh.length) { log(`FAST-EXIT subagent no-new-files session=${sid} agent=${aid}`); process.exit(0); }
+      const entries = worklistEntries(CLI, root, fresh, Object.fromEntries(fresh.map((rel) => [rel, delta.get(rel)])), log);
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "subagent" });
+      logCaptureEvent(root, { event: "fire", reason: "subagent", session: sid, agent: aid, files: fresh.length, host: "cursor" });
+      log(`FIRE subagent session=${sid} agent=${aid} files=${fresh.length}`);
+      process.stdout.write(JSON.stringify({ followup_message: payload }));
+      process.exit(0);
+    }
+
+    // --- Main path: trigger state machine -------------------------------------
+    const head = gitHead(root);
+    const headDrift = Boolean(state.head && head && head !== state.head);
+    state.head = head || state.head;
 
-    // FAST-EXIT only when the turn touched NO repo file (pure Q&A / orchestration).
-    if (!files.length) {
-      log(`FAST-EXIT zero touched files session=${sid} agent=${aid} event=${event || "?"}`);
+    const stats = segmentStatsCursor(segment);
+    const freshNoted = freshNotedSet(CLI, root, [...delta.keys()].filter((rel) => !state.files[rel]), log);
+
+    const { state: next, decision } = step(state, {
+      delta,
+      synthesis: stats.synthesis,
+      freshNoted,
+      headDrift,
+    });
+    writeFileSync(marker, JSON.stringify(next));
+
+    if (!decision) {
+      log(`TICK session=${sid} stop=${next.stop} active=${next.activeStops} quiet=${next.quietRun} armed=${next.armed} files=${Object.keys(next.files).length} delta=${delta.size}`);
       process.exit(0);
     }
 
-    const prompt = buildCapturePrompt(root, filesBlock(root, files), sid, event === "subagentStop");
-    logCaptureEvent(root, { event: "elicit", session: sid, agent: aid, touched: files.length, hook: event });
-    log(`ELICIT session=${sid} agent=${aid} touched=${files.length} promptBytes=${prompt.length} event=${event || "?"}`);
-    process.stdout.write(JSON.stringify({ followup_message: prompt }));
+    const entries = worklistEntries(CLI, root, decision.files, next.files, log);
+    logCaptureEvent(root, {
+      event: "fire", reason: decision.fire, mode: decision.mode, session: sid,
+      score: decision.score, files: decision.files.length, stop: next.stop, fires: next.fires, host: "cursor",
+    });
+    log(`FIRE ${decision.fire} mode=${decision.mode} session=${sid} score=${decision.score} files=${decision.files.length}`);
+
+    if (decision.mode === "block") {
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "block" });
+      process.stdout.write(JSON.stringify({ followup_message: payload }));
+    } else {
+      // Non-blocking: cursor-kb-recall delivers this with the user's next prompt.
+      const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "inject" });
+      writePendingCapture(sid, decision.fire, payload);
+    }
   } catch (e) {
     log(`handler ${e?.stack || e}`); // fail-open: no stdout → stop allowed
   }

package/hooks/cursor-kb-recall.mjs

@@ -25,6 +25,10 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { cursorRoot } from "./cursor-input.mjs";
+// Pending-capture delivery (v5 trigger): a descent/surge/cap fire at a previous
+// stop wrote its worklist payload to a pending file instead of blocking; it
+// rides this same next-prompt channel — capture first, then the user's request.
+import { takePendingCapture } from "./elicit-core.mjs";
 
 // hooks/ sits beside dist/ in both the repo and the published package.
 const CLI = fileURLToPath(new URL("../dist/index.js", import.meta.url));
@@ -69,33 +73,43 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     if (!root) process.exit(0);
     setLogRoot(root);
 
-    // No notebook → no tax, not even a child process.
-    if (!existsSync(join(root, ".coldstart", "notebook", ".raw"))) process.exit(0);
+    const sid = String(input.session_id || "").replace(/[^\w-]/g, "");
+
+    // A pending capture (non-blocking fire at a previous stop) is delivered
+    // regardless of recall hits — it must not depend on the notebook existing
+    // (the first capture is what creates it).
+    const pending = takePendingCapture(sid);
 
     const prompt = String(input.prompt || "").slice(0, MAX_QUERY_CHARS).trim();
-    if (!prompt) process.exit(0);
 
     let page = "";
-    try {
-      page = execFileSync("node", [CLI, "kb", "search", "--hook", "--max", "3", "--root", root, prompt], {
-        encoding: "utf8",
-        timeout: SEARCH_TIMEOUT_MS,
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch (e) {
-      log(`search failed/timed out: ${String(e).split("\n")[0]}`);
-      process.exit(0);
+    // No notebook / no prompt → no recall search, not even a child process.
+    if (prompt && existsSync(join(root, ".coldstart", "notebook", ".raw"))) {
+      try {
+        page = execFileSync("node", [CLI, "kb", "search", "--hook", "--max", "3", "--root", root, prompt], {
+          encoding: "utf8",
+          timeout: SEARCH_TIMEOUT_MS,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+      } catch (e) {
+        log(`search failed/timed out: ${String(e).split("\n")[0]}`);
+        page = "";
+      }
     }
 
     if (!page.trim() || page.startsWith("No notebook notes match") || page.startsWith("No notebook in")) {
-      log(`no hits (promptChars=${prompt.length})`);
-      process.exit(0);
+      if (!pending) {
+        log(`no hits (promptChars=${prompt.length})`);
+        process.exit(0);
+      }
+      page = "";
     }
 
     // Pointer page — titles + gists + an OPENABLE note path, never a full body.
     // (Same framing as codex-kb-recall.mjs; notes are REFERENCE DATA, not
     // instructions.)
-    let block =
+    let block = "";
+    if (page) block =
       `The repo's notebook (notes written by past agents after real tasks here) has entries ` +
       `matching this request, below — each a title, a gist, and the note's file path. ` +
       `A note is a past agent's verified overview of a file or flow. If one matches your task, ` +
@@ -114,6 +128,16 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
 
     if (block.length > 8500) block = block.slice(0, 8500) + "\n…(truncated)";
 
+    // Pending capture rides FIRST (capture, then the user's request). If the
+    // combination would spill past the host's hook cap, recall yields — the
+    // capture worklist must arrive whole.
+    if (pending) {
+      block = pending.length + block.length > 9500 || !block
+        ? pending
+        : `${pending}\n\n---\n\n${block}`;
+    }
+    if (!block) process.exit(0);
+
     // Arm the postToolUse nudge detectors (they gate their spiral detectors on
     // seen_find so they never nag sessions that don't use coldstart). An injected
     // session IS coldstart-aware even if it never runs `find`. State file path must

package/hooks/elicit-core.mjs

@@ -0,0 +1,126 @@
+/**
+ * elicit-core.mjs — protocol-neutral v5 capture helpers, shared by the three
+ * host elicit hooks (kb-elicit / cursor-kb-elicit / codex-kb-elicit) and the
+ * recall hooks that deliver pending captures.
+ *
+ * Everything here is host-independent: worklist annotation (kb status +
+ * consumers, both fail-open), fresh-note discounting, the git-HEAD
+ * fingerprint, capture metrics, and the pending-file handoff between a
+ * non-blocking fire and the next-prompt recall channel. What stays per-host:
+ * input adaptation, the transcript walk (see evidence.mjs's per-host
+ * extractors), and the output envelope.
+ */
+
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, appendFileSync, mkdirSync } from "node:fs";
+
+export const MAX_WORKLIST = 30;
+
+const noop = () => {};
+
+// --- Annotation sources (fail-open: absence of data = absence of annotation) ---
+export function noteAnnotations(cli, root, files, log = noop) {
+  try {
+    const raw = execFileSync(
+      "node", [cli, "kb", "status", "--json", "--paths", files.join(","), "--root", root],
+      { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const byPath = new Map();
+    for (const entry of JSON.parse(raw).paths || []) byPath.set(entry.path, entry.notes || []);
+    return byPath;
+  } catch (e) {
+    log(`kb status unavailable (${String(e).split("\n")[0]}) — annotating as no-notes`);
+    return new Map();
+  }
+}
+
+export function consumerCounts(cli, root, files, log = noop) {
+  try {
+    const raw = execFileSync(
+      "node", [cli, "consumers", "--json", "--paths", files.join(","), "--root", root],
+      { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const byPath = new Map();
+    for (const entry of JSON.parse(raw).paths || []) byPath.set(entry.path, entry.consumers);
+    return byPath;
+  } catch (e) {
+    log(`consumers unavailable (${String(e).split("\n")[0]}) — no graph annotation`);
+    return new Map();
+  }
+}
+
+export function worklistEntries(cli, root, files, stateFiles, log = noop) {
+  const listed = files.slice(0, MAX_WORKLIST);
+  const notes = noteAnnotations(cli, root, listed, log);
+  const consumers = consumerCounts(cli, root, listed, log);
+  return listed.map((rel) => {
+    const f = stateFiles[rel] || {};
+    const tier = f.edits > 0 ? `edited ×${f.edits}` : f.reads > 0 ? "read" : "skimmed";
+    return {
+      path: rel,
+      tier,
+      notes: (notes.get(rel) || []).map((n) => ({ id: n.id, type: n.type, state: n.state })),
+      noConsumers: consumers.get(rel) === 0,
+    };
+  });
+}
+
+/** Fresh-noted set for score discounting: files whose EVERY anchored note is fresh. */
+export function freshNotedSet(cli, root, files, log = noop) {
+  if (!files.length) return new Set();
+  const notes = noteAnnotations(cli, root, files, log);
+  const fresh = new Set();
+  for (const rel of files) {
+    const anchored = notes.get(rel) || [];
+    if (anchored.length && anchored.every((n) => n.state === "fresh")) fresh.add(rel);
+  }
+  return fresh;
+}
+
+// --- Repo observation: HEAD fingerprint (catches MANUAL commits too) -----------
+export function gitHead(root) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch { return ""; }
+}
+
+// --- Capture metrics -----------------------------------------------------------
+export function logCaptureEvent(root, event) {
+  try {
+    const dir = join(root, ".coldstart", "notebook", ".metrics");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "capture.jsonl"), JSON.stringify({ ts: new Date().toISOString(), ...event }) + "\n");
+  } catch { /* metrics never wedge a stop */ }
+}
+
+// --- Pending-capture handoff ---------------------------------------------------
+// A descent/surge fire writes its worklist payload here instead of blocking the
+// stop; the host's next-prompt recall hook consumes it (capture first, then the
+// user's request). One file per session id — a second fire before delivery
+// overwrites (the later worklist supersedes). Same path scheme across hosts;
+// host session ids never collide (host-distinct formats).
+export function pendingPath(sid) {
+  return join(tmpdir(), `coldstart-kb-pending-${sid}.json`);
+}
+
+export function writePendingCapture(sid, reason, payload) {
+  writeFileSync(pendingPath(sid), JSON.stringify({ ts: Date.now(), reason, payload }));
+}
+
+/** Consume (delete) the pending capture for this session. Stale pendings
+ *  (>24h — e.g. a session resumed days later) are dropped. */
+export function takePendingCapture(sid) {
+  if (!sid) return "";
+  const pf = pendingPath(sid);
+  try {
+    if (!existsSync(pf)) return "";
+    const pending = JSON.parse(readFileSync(pf, "utf8"));
+    unlinkSync(pf);
+    if (Date.now() - (pending.ts || 0) > 24 * 3600 * 1000) return "";
+    return String(pending.payload || "");
+  } catch { return ""; }
+}