@cstart/coldstart 2.1.0 → 2.2.0

package/hooks/codex-kb-elicit.mjs

@@ -1,35 +1,42 @@
 #!/usr/bin/env node
 /**
- * codex-kb-elicit.mjs — Codex Stop + SubagentStop notebook capture.
+ * codex-kb-elicit.mjs — Codex Stop + SubagentStop notebook capture, v5
+ * evidence (ported 2026-07-17; the v4 path-mention walker is gone).
  *
- * ALWAYS FIRES when the agent touched ANY repo file this session — the old
- * deep-read gate (whole-file Reads + `gs` only) is gone: read-modality
- * classification proved unwinnable (windowed Reads, Bash cat/sed, MCP readers
- * are all invisible to it — a q8-style session lost real knowledge to a
- * FAST-EXIT). The hook does mechanical extraction only; THE AGENT decides
- * whether anything is worth writing — the prompt's gate and "write NOTHING
- * when" list carry that decision. FAST-EXIT remains only for sessions that
- * touched zero repo files (pure orchestrators / Q&A turns).
+ * HOST CONSTRAINT: Codex's Stop does NOT fire per turn — in the TUI it fires
+ * once at session EXIT, and `codex exec` is one Stop by construction
+ * (confirmed live 2026-07-13). A multi-stop trigger (arm/descent/surge) has
+ * nothing to time against here, and a pending-file handoff has no next prompt
+ * to ride. So Codex capture is ONE-SHOT: at the session's single Stop, build
+ * the v5 worklist and deliver it BLOCKING ({decision:"block"} re-prompts the
+ * agent before exit). If Codex ever moves to per-turn Stops, port the trigger
+ * machine from cursor-kb-elicit.mjs — the evidence/state plumbing here is
+ * already shaped for it.
  *
- * Merge-vs-new is agent-curated: touched files are annotated with their
- * existing notes (id + note file path, from `coldstart kb status --json`) so
- * the agent can read a candidate and pass --into/--new on its FIRST kb write
- * — the exit-3 candidates bounce is the safety net, not the mechanism.
+ * What v5 changes vs the old walker:
+ *   - EVIDENCE TIERS, result-confirmed: extractCodexEvidence pairs
+ *     custom_tool_call → *_output by call_id and classifies the shell commands
+ *     inside tools.exec_command (read verbs vs sed -i vs mentions) +
+ *     apply_patch file headers as edits. Grep/path mentions NEVER make the
+ *     worklist (v4's biggest noise source).
+ *   - .coldstartignore filtering at the evidence layer.
+ *   - The v5 checklist payload (capture-payload.mjs) with per-file tier +
+ *     note-state + consumers annotations — same as Claude/Cursor.
+ *   - Session-cumulative marker (v2 state, lineCount-sliced): a resumed thread
+ *     only offers files not already offered.
  *
- * SubagentStop fires too (subagents often do the only real reads); duplication
- * is guarded by disjoint transcripts + firsthand-only + SubagentStop preceding
- * Stop (the sub's notes are on disk when the main agent's write runs, so they
- * surface as "candidates → reconcile, don't duplicate").
- *
- * 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 { extractCodexEvidence } from "./evidence.mjs";
+import { loadIgnore } from "./ignore.mjs";
+import { buildCapturePayload } from "./capture-payload.mjs";
+import { worklistEntries, logCaptureEvent } 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));
@@ -41,218 +48,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 Codex tool input. Existence under root is checked by
-// the caller, so strings, shell commands, apply_patch payloads, and MCP JSON can
-// all be scanned without depending on a particular internal 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;
-
-// Codex rollout JSONL stores tool calls as response_item payloads. Current
-// builds use custom_tool_call for the JS-backed exec/apply_patch tools and
-// function_call for other tools. Scan their serialized inputs; only paths that
-// exist as files under the repo survive, so protocol metadata cannot become a
-// notebook anchor.
-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; }
-  for (const line of text.split("\n")) {
-    if (!line.trim() || line[0] !== "{") continue;
-    let rec;
-    try { rec = JSON.parse(line); } catch { continue; }
-    if (rec.type !== "response_item") continue;
-    const call = rec.payload || {};
-    if (call.type !== "custom_tool_call" && call.type !== "function_call") continue;
-    const sources = [];
-    if (typeof call.input === "string") sources.push(call.input);
-    if (typeof call.arguments === "string") sources.push(call.arguments);
-    else if (call.arguments && typeof call.arguments === "object") sources.push(JSON.stringify(call.arguments));
-    for (const source of sources) {
-      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();
-  }
-}
-
-// Always-fire can surface long touch lists; the prompt stays bounded. Files
-// WITH existing notes always make the cut (they carry the merge decision).
-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 (v4, 2026-07-07 — user-authored opening; validation-run
-// configuration: gates off via --force, capture-only) ---------------------------
-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 Bash 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 = "";
@@ -269,14 +65,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); });
 
@@ -294,26 +82,16 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // Guard 1: already inside a hook-induced continuation → let it stop.
     if (input.stop_hook_active === true) { log("SKIP stop_hook_active"); process.exit(0); }
 
-    // Codex session_id identifies a thread; turn_id identifies one user turn.
-    // Capture across the whole thread, incrementally — a resumed thread keeps
-    // contributing new knowledge.
     const sid = String(input.session_id || "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!sid) { log("SKIP no-session-id"); process.exit(0); }
 
-    // Guard 2: capture across the session, but only files not yet offered. The
-    // old per-turn marker re-offered EVERY touched file on every turn; instead we
-    // remember which files were already offered and elicit only the new ones (the
-    // delta is computed below). Subagents share the parent session_id, so the
-    // record is scoped by agent too.
     const aid = String(input.agent_id || "main").replace(/[^A-Za-z0-9_-]/g, "") || "main";
-    const marker = join(tmpdir(), `coldstart-codex-kb-${sid}-${aid}.json`);
-    let offered = new Set();
-    try { offered = new Set(JSON.parse(readFileSync(marker, "utf8")).files || []); } catch { /* first Stop of this session */ }
+    const isSubagent = input.hook_event_name === "SubagentStop";
 
     // Codex supplies the child's own rollout as agent_transcript_path on
     // SubagentStop. Its transcript_path is the parent's rollout at that event.
     let transcriptPath = String(input.transcript_path || "");
-    if (input.hook_event_name === "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"}`);
@@ -321,29 +99,56 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       }
       transcriptPath = own;
     }
-    // Ephemeral Codex runs deliberately expose no transcript path. Fail open:
-    // navigation/recall still work, but capture has no trustworthy evidence.
-    const files = transcriptPath ? touchedFiles(transcriptPath, root) : [];
-    // Delta: only files not already offered on an earlier Stop this session.
-    const newFiles = files.filter((f) => !offered.has(f));
+    // Ephemeral Codex runs deliberately expose no transcript path. Fail open.
+    if (!transcriptPath || !existsSync(transcriptPath)) { log("SKIP no-transcript"); process.exit(0); }
 
-    // FAST-EXIT when there is nothing NEW to capture — either no repo file was
-    // touched at all (pure orchestration / Q&A) or every touched file was already
-    // offered on a previous Stop. No record is written on this path, so an early
-    // no-op Stop can never burn the session's capture.
-    if (!newFiles.length) {
-      log(`FAST-EXIT no-new-files session=${sid} agent=${aid} touched=${files.length} event=${input.hook_event_name || "?"}`);
-      process.exit(0);
+    const ignore = loadIgnore(root);
+    // Session-cumulative v2 state: which files were already offered, and how
+    // far into the rollout the last Stop read (a resumed thread appends).
+    const marker = join(tmpdir(), `coldstart-codex-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 = { v: 2, lineCount: 0, files: {} };
+
+    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 = extractCodexEvidence(segment, root);
+    const offered = new Set(Object.keys(state.files));
+    const fresh = [];
+    for (const [rel, r] of raw) {
+      if (r.reads + r.edits + r.gs === 0) continue;
+      if (ignore(rel)) continue;
+      if (offered.has(rel)) continue;
+      fresh.push(rel);
+      state.files[rel] = { ...r, captured: true };
     }
+    // Most-worked first, same ranking as contentReadFiles.
+    fresh.sort((a, b) => (state.files[b].edits - state.files[a].edits) || (state.files[b].events - state.files[a].events));
+    writeFileSync(marker, JSON.stringify(state));
 
-    // Record everything now offered BEFORE returning the block, so the post-write
-    // re-Stop and every later Stop skip these files.
-    try { writeFileSync(marker, JSON.stringify({ files: [...offered, ...newFiles], ts: Date.now() })); } catch { /* best effort */ }
+    if (!fresh.length) {
+      log(`FAST-EXIT no-new-files session=${sid} agent=${aid} event=${input.hook_event_name || "?"}`);
+      process.exit(0);
+    }
 
-    const prompt = buildCapturePrompt(root, filesBlock(root, newFiles), sid, input.hook_event_name === "SubagentStop");
-    logCaptureEvent(root, { event: "elicit", session: sid, agent: aid, touched: files.length, new: newFiles.length, hook: input.hook_event_name });
-    log(`ELICIT session=${sid} agent=${aid} new=${newFiles.length} touched=${files.length} promptBytes=${prompt.length} event=${input.hook_event_name || "?"}`);
-    process.stdout.write(JSON.stringify({ decision: "block", reason: prompt }));
+    const entries = worklistEntries(CLI, root, fresh, state.files, log);
+    const payload = buildCapturePayload({
+      root, cli: CLI, sid, entries,
+      envelope: isSubagent ? "subagent" : "block",
+    });
+    logCaptureEvent(root, {
+      event: "fire", reason: isSubagent ? "subagent" : "session-end", session: sid,
+      agent: aid, files: fresh.length, host: "codex",
+    });
+    log(`FIRE ${isSubagent ? "subagent" : "session-end"} session=${sid} agent=${aid} files=${fresh.length} promptBytes=${payload.length}`);
+    process.stdout.write(JSON.stringify({ decision: "block", reason: payload }));
   } catch (e) {
     log(`handler ${e?.stack || e}`); // fail-open: no stdout → stop allowed
   }