@cstart/coldstart 2.0.2 → 2.1.0

package/hooks/codex-nudge-handler.mjs

@@ -37,6 +37,7 @@
 
 import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { canonicalFindKey } from "./canonical-find-key.mjs";
@@ -67,6 +68,48 @@ const SEARCH_RE =
   /(^|[;&|]|\s)(grep|egrep|fgrep|rg)\b|git\s+grep|git\s+log|(^|[;&|]|\s)find\s|(^|[;&|]|\s)ls\b|(^|[;&|]|\s)cat\b/;
 const GS_FILE_RE = /(?:coldstart|index\.js)\s+gs\s+(\S+)/;
 
+// The checkpoint (detector 4) only makes sense when the agent may be SPINNING IN
+// SEARCH — never mid-implementation. A write is the signal that it is producing,
+// not spinning. Fast per-call detection: structured write tools + write-shaped
+// shell (sed -i, redirections, cp/mv/rm, git apply/checkout…). This is the
+// fallback; git ground-truth (below) is authoritative when the repo is a git repo.
+const WRITE_TOOLS = new Set([
+  "Edit", "Write", "MultiEdit", "NotebookEdit", // Claude
+  "apply_patch", "edit_file", "write_file", "create_file", // Codex / Cursor / MCP writers
+]);
+const WRITE_CMD_RE =
+  /(^|[\s;&|(])(sed\s+-i|tee|dd|truncate|patch|apply_patch|cp|mv|rm|mkdir|touch|install)\b|>>?(?!\s*\/dev\/null)|git\s+(apply|checkout|restore|stash|reset|revert|commit|mv|rm)\b/;
+
+// Genuine, tool-agnostic write detection: hash the working-tree state so ANY
+// modification (Edit, sed -i, >>, an MCP writer, a new or deleted file) changes
+// it, while pure reads leave it untouched. Empty string when git is unavailable
+// (no repo / no commits / no git) — callers fall back to the fast signal above.
+// porcelain catches added/removed/untracked files; shortstat catches further
+// edits to an already-dirty file. Verified across write modalities 2026-07-10.
+function gitFingerprint(root) {
+  try {
+    const opts = { cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] };
+    const status = execFileSync("git", ["status", "--porcelain=v1"], opts);
+    const stat = execFileSync("git", ["diff", "HEAD", "--shortstat"], opts);
+    return createHash("sha1").update(status + " " + stat).digest("hex").slice(0, 16);
+  } catch {
+    return "";
+  }
+}
+
+// Current HEAD (short sha), or "" when unavailable. The fingerprint above reads
+// the working-tree DIFF against HEAD, so a HEAD move (branch switch / commit /
+// rebase) can shift it without the agent writing anything — we compare HEAD
+// across checkpoints and distrust the fingerprint whenever it moved.
+function gitHead(root) {
+  try {
+    const opts = { cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] };
+    return execFileSync("git", ["rev-parse", "HEAD"], opts).trim().slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
 // Evidence store regexes — paths printed in ANY output, and files named as ARGS.
 const PATH_RE = /[\w./-]+\.(?:py|js|jsx|ts|tsx|htm|html|vue|json|scss|css|rb|java)/g;
 const FILE_ARG_RE =
@@ -161,6 +204,9 @@ export default function handle(input) {
     held_files: [],
     redundant_fired: 0,
     seen_find_queries: [],
+    wrote_since_ckpt: false, // (4) any write since the last checkpoint window
+    git_fp: "", // (4) working-tree fingerprint at the last checkpoint
+    git_head: "", // (4) HEAD at the last checkpoint — a move invalidates the fp diff
   };
   try {
     Object.assign(st, JSON.parse(readFileSync(stateFile, "utf8")));
@@ -185,6 +231,8 @@ export default function handle(input) {
     tool === "Glob" ||
     (tool === "Bash" && !isFind && !isGs && !isKb && SEARCH_RE.test(cmd));
   const isNonfindShell = isSearch;
+  // Producing, not spinning — used only to gate the checkpoint (detector 4).
+  const isWrite = WRITE_TOOLS.has(tool) || (tool === "Bash" && WRITE_CMD_RE.test(cmd));
 
   const _ob = out !== null && out !== undefined ? out.trim().toLowerCase() : null;
   const outEmpty =
@@ -195,6 +243,7 @@ export default function handle(input) {
       _ob === "no files found");
 
   st.total += 1;
+  if (isWrite) st.wrote_since_ckpt = true;
   // seen_find gates the spiral detectors (3/3b): they stay silent for sessions that
   // never touch coldstart at all (deliberate — this hook must not nag non-users).
   // Any coldstart surface proves awareness: find (set below on the find branch),
@@ -329,19 +378,38 @@ export default function handle(input) {
     st.last_gs_fallback = out && GS_FALLBACK_RE.test(out) ? gsFile : "";
   }
 
-  // (4) checkpoint — periodic, lowest urgency
+  // (4) checkpoint — periodic, lowest urgency. Fires ONLY when the agent may be
+  // spinning in search: suppressed whenever a write happened in the window, so it
+  // never nags mid-implementation (where "stop searching and answer" is nonsense).
+  // git is authoritative when present (ground-truth over the whole window); the
+  // fast per-call signal covers the first window and non-git repos.
   if (st.total - st.last_checkpoint >= CHECKPOINT_EVERY) {
     st.last_checkpoint = st.total;
-    msgs.push([
-      5,
-      `Checkpoint (${st.total} tool calls). Stop and think before the next call — answer these in order:\n` +
-        "1. Restate the task in one sentence — what is the ONE thing it asks for?\n" +
-        "2. List the files you have already surfaced or read that bear on it.\n" +
-        "3. Can you answer (1) from (2)? If YES — write the answer now and stop searching; you almost " +
-        "certainly have enough.\n" +
-        "4. Only if NO — name the single specific fact still missing, and make the next call target ONLY " +
-        "that. Do not re-run a search whose results are already in your context.",
-    ]);
+    const headNow = gitHead(input.cwd);
+    const fpNow = gitFingerprint(input.cwd);
+    // Trust the git working-tree diff only with a prior baseline AND an unmoved
+    // HEAD — a branch switch / commit / rebase shifts the whole tree and would
+    // read as a spurious write. Otherwise (first window, no git, or HEAD moved)
+    // the fast per-call signal governs: it tracks the agent's own writes and is
+    // immune to branch movement.
+    const gitUsable = !!fpNow && !!st.git_fp && !!headNow && headNow === st.git_head;
+    const wrote = gitUsable ? fpNow !== st.git_fp : st.wrote_since_ckpt;
+    if (fpNow) st.git_fp = fpNow;
+    if (headNow) st.git_head = headNow;
+    st.wrote_since_ckpt = false;
+    if (!wrote) {
+      msgs.push([
+        5,
+        `Checkpoint (${st.total} tool calls). If you are searching or investigating, stop and think ` +
+          "before the next call (if you are mid-implementation, disregard this):\n" +
+          "1. Restate the task in one sentence — what is the ONE thing it asks for?\n" +
+          "2. List the files you have already surfaced or read that bear on it.\n" +
+          "3. Can you answer (1) from (2)? If YES — write the answer now and stop searching; you almost " +
+          "certainly have enough.\n" +
+          "4. Only if NO — name the single specific fact still missing, and make the next call target ONLY " +
+          "that. Do not re-run a search whose results are already in your context.",
+      ]);
+    }
   }
 
   // merge THIS call's evidence into the store (after novelty was computed above)

package/hooks/kb-elicit.mjs

@@ -181,9 +181,17 @@ have firsthand knowledge of — never enumerate the rest.
    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.
+2. FLOW notes — RARE. Not "my task touched several files": that is most tasks, and its \
+knowledge belongs in the file notes. A flow exists only when the RELATIONSHIP between files is \
+itself the knowledge — such as an enforcement gap, an asymmetry or inconsistency between files, \
+a dead/unreachable path, or an evolution that explains a surprising present shape. The gate: \
+name, in one sentence, the fact a reader of ALL the file notes would still be missing; if you \
+cannot, there is no flow — put the facts in file notes. That sentence is the FIRST sentence of \
+the flow's summary. Never a flow: a feature's parts-list ("the model, the view, the route, the \
+config, the tests" — an index, not knowledge); a mechanism living in one file (that file's note); a call-chain or \
+version history with no gotcha at the end. Steps are the minimal chain carrying the missing \
+fact — not a tour of every file the task visited. 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.
@@ -202,6 +210,10 @@ 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.
+- Say only what you verified in THIS file, this session: never assert a method, branch, or \
+config key you did not confirm is present, and never describe what a DIFFERENT file does (that \
+is a flow, or that file's own note). A confident whole-file claim from a partial read is the \
+single most common bad note.
 - 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 \
@@ -300,12 +312,16 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     const sid = String(input.session_id || "").replace(/[^A-Za-z0-9_-]/g, "");
     if (!sid) { log("SKIP no-session-id"); process.exit(0); }
 
-    // Guard 2: one elicitation per (session, agent) — subagents share the
-    // parent session_id, so the marker is scoped by agent too.
+    // Guard 2: capture across a long session, but only files not yet offered.
+    // A boolean once-per-(session,agent) marker silently dropped ALL knowledge
+    // after the first Stop; instead we remember which files were already offered
+    // for capture and elicit only the new ones (the delta is computed below,
+    // once the SubagentStop transcript is resolved). 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-kb-${sid}-${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 marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
+    let offered = new Set();
+    try { offered = new Set(JSON.parse(readFileSync(marker, "utf8")).files || []); } catch { /* first Stop of this session */ }
 
     // On SubagentStop, transcript_path is the PARENT's transcript (confirmed:
     // claude-code#11396) — scanning it would elicit the sub off the parent's
@@ -326,18 +342,27 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       transcriptPath = own;
     }
     const files = transcriptPath ? touchedFiles(transcriptPath, root) : [];
-
-    // FAST-EXIT only when the agent touched NO repo file at all (pure
-    // orchestration / Q&A). Anything touched → the agent judges what's worth
-    // capturing; the hook never guesses from read modality.
-    if (!files.length) {
-      log(`FAST-EXIT zero touched files session=${sid} agent=${aid} event=${input.hook_event_name || "?"}`);
+    // Delta: only files not already offered on an earlier Stop this session.
+    const newFiles = files.filter((f) => !offered.has(f));
+
+    // 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 prompt = buildCapturePrompt(root, filesBlock(root, files), sid, input.hook_event_name === "SubagentStop");
-    logCaptureEvent(root, { event: "elicit", session: sid, agent: aid, touched: files.length, hook: input.hook_event_name });
-    log(`ELICIT session=${sid} agent=${aid} touched=${files.length} promptBytes=${prompt.length} event=${input.hook_event_name || "?"}`);
+    // Record everything now offered BEFORE returning the block, so the post-write
+    // re-Stop and every later Stop skip these files. stop_hook_active (Guard 1)
+    // still short-circuits the immediate re-Stop; this record survives across the
+    // natural turns of a long session.
+    try { writeFileSync(marker, JSON.stringify({ files: [...offered, ...newFiles], ts: Date.now() })); } catch { /* best effort */ }
+
+    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 }));
   } catch (e) {
     log(`handler ${e?.stack || e}`); // fail-open: no stdout → stop allowed

package/hooks/nudge-handler.mjs

@@ -37,6 +37,7 @@
 
 import { readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { canonicalFindKey } from "./canonical-find-key.mjs";
@@ -67,6 +68,48 @@ const SEARCH_RE =
   /(^|[;&|]|\s)(grep|egrep|fgrep|rg)\b|git\s+grep|git\s+log|(^|[;&|]|\s)find\s|(^|[;&|]|\s)ls\b|(^|[;&|]|\s)cat\b/;
 const GS_FILE_RE = /(?:coldstart|index\.js)\s+gs\s+(\S+)/;
 
+// The checkpoint (detector 4) only makes sense when the agent may be SPINNING IN
+// SEARCH — never mid-implementation. A write is the signal that it is producing,
+// not spinning. Fast per-call detection: structured write tools + write-shaped
+// shell (sed -i, redirections, cp/mv/rm, git apply/checkout…). This is the
+// fallback; git ground-truth (below) is authoritative when the repo is a git repo.
+const WRITE_TOOLS = new Set([
+  "Edit", "Write", "MultiEdit", "NotebookEdit", // Claude
+  "apply_patch", "edit_file", "write_file", "create_file", // Codex / Cursor / MCP writers
+]);
+const WRITE_CMD_RE =
+  /(^|[\s;&|(])(sed\s+-i|tee|dd|truncate|patch|apply_patch|cp|mv|rm|mkdir|touch|install)\b|>>?(?!\s*\/dev\/null)|git\s+(apply|checkout|restore|stash|reset|revert|commit|mv|rm)\b/;
+
+// Genuine, tool-agnostic write detection: hash the working-tree state so ANY
+// modification (Edit, sed -i, >>, an MCP writer, a new or deleted file) changes
+// it, while pure reads leave it untouched. Empty string when git is unavailable
+// (no repo / no commits / no git) — callers fall back to the fast signal above.
+// porcelain catches added/removed/untracked files; shortstat catches further
+// edits to an already-dirty file. Verified across write modalities 2026-07-10.
+function gitFingerprint(root) {
+  try {
+    const opts = { cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] };
+    const status = execFileSync("git", ["status", "--porcelain=v1"], opts);
+    const stat = execFileSync("git", ["diff", "HEAD", "--shortstat"], opts);
+    return createHash("sha1").update(status + " " + stat).digest("hex").slice(0, 16);
+  } catch {
+    return "";
+  }
+}
+
+// Current HEAD (short sha), or "" when unavailable. The fingerprint above reads
+// the working-tree DIFF against HEAD, so a HEAD move (branch switch / commit /
+// rebase) can shift it without the agent writing anything — we compare HEAD
+// across checkpoints and distrust the fingerprint whenever it moved.
+function gitHead(root) {
+  try {
+    const opts = { cwd: root, encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] };
+    return execFileSync("git", ["rev-parse", "HEAD"], opts).trim().slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
 // Evidence store regexes — paths printed in ANY output, and files named as ARGS.
 const PATH_RE = /[\w./-]+\.(?:py|js|jsx|ts|tsx|htm|html|vue|json|scss|css|rb|java)/g;
 const FILE_ARG_RE =
@@ -161,6 +204,9 @@ export default function handle(input) {
     held_files: [],
     redundant_fired: 0,
     seen_find_queries: [],
+    wrote_since_ckpt: false, // (4) any write since the last checkpoint window
+    git_fp: "", // (4) working-tree fingerprint at the last checkpoint
+    git_head: "", // (4) HEAD at the last checkpoint — a move invalidates the fp diff
   };
   try {
     Object.assign(st, JSON.parse(readFileSync(stateFile, "utf8")));
@@ -185,6 +231,8 @@ export default function handle(input) {
     tool === "Glob" ||
     (tool === "Bash" && !isFind && !isGs && !isKb && SEARCH_RE.test(cmd));
   const isNonfindShell = isSearch;
+  // Producing, not spinning — used only to gate the checkpoint (detector 4).
+  const isWrite = WRITE_TOOLS.has(tool) || (tool === "Bash" && WRITE_CMD_RE.test(cmd));
 
   const _ob = out !== null && out !== undefined ? out.trim().toLowerCase() : null;
   const outEmpty =
@@ -195,6 +243,7 @@ export default function handle(input) {
       _ob === "no files found");
 
   st.total += 1;
+  if (isWrite) st.wrote_since_ckpt = true;
   // seen_find gates the spiral detectors (3/3b): they stay silent for sessions that
   // never touch coldstart at all (deliberate — this hook must not nag non-users).
   // Any coldstart surface proves awareness: find (set below on the find branch),
@@ -329,19 +378,38 @@ export default function handle(input) {
     st.last_gs_fallback = out && GS_FALLBACK_RE.test(out) ? gsFile : "";
   }
 
-  // (4) checkpoint — periodic, lowest urgency
+  // (4) checkpoint — periodic, lowest urgency. Fires ONLY when the agent may be
+  // spinning in search: suppressed whenever a write happened in the window, so it
+  // never nags mid-implementation (where "stop searching and answer" is nonsense).
+  // git is authoritative when present (ground-truth over the whole window); the
+  // fast per-call signal covers the first window and non-git repos.
   if (st.total - st.last_checkpoint >= CHECKPOINT_EVERY) {
     st.last_checkpoint = st.total;
-    msgs.push([
-      5,
-      `Checkpoint (${st.total} tool calls). Stop and think before the next call — answer these in order:\n` +
-        "1. Restate the task in one sentence — what is the ONE thing it asks for?\n" +
-        "2. List the files you have already surfaced or read that bear on it.\n" +
-        "3. Can you answer (1) from (2)? If YES — write the answer now and stop searching; you almost " +
-        "certainly have enough.\n" +
-        "4. Only if NO — name the single specific fact still missing, and make the next call target ONLY " +
-        "that. Do not re-run a search whose results are already in your context.",
-    ]);
+    const headNow = gitHead(input.cwd);
+    const fpNow = gitFingerprint(input.cwd);
+    // Trust the git working-tree diff only with a prior baseline AND an unmoved
+    // HEAD — a branch switch / commit / rebase shifts the whole tree and would
+    // read as a spurious write. Otherwise (first window, no git, or HEAD moved)
+    // the fast per-call signal governs: it tracks the agent's own writes and is
+    // immune to branch movement.
+    const gitUsable = !!fpNow && !!st.git_fp && !!headNow && headNow === st.git_head;
+    const wrote = gitUsable ? fpNow !== st.git_fp : st.wrote_since_ckpt;
+    if (fpNow) st.git_fp = fpNow;
+    if (headNow) st.git_head = headNow;
+    st.wrote_since_ckpt = false;
+    if (!wrote) {
+      msgs.push([
+        5,
+        `Checkpoint (${st.total} tool calls). If you are searching or investigating, stop and think ` +
+          "before the next call (if you are mid-implementation, disregard this):\n" +
+          "1. Restate the task in one sentence — what is the ONE thing it asks for?\n" +
+          "2. List the files you have already surfaced or read that bear on it.\n" +
+          "3. Can you answer (1) from (2)? If YES — write the answer now and stop searching; you almost " +
+          "certainly have enough.\n" +
+          "4. Only if NO — name the single specific fact still missing, and make the next call target ONLY " +
+          "that. Do not re-run a search whose results are already in your context.",
+      ]);
+    }
   }
 
   // merge THIS call's evidence into the store (after novelty was computed above)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cstart/coldstart",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -14,7 +14,8 @@
   "files": [
     "dist",
     "hooks",
-    "templates"
+    "templates",
+    "vendor/wasm"
   ],
   "keywords": [
     "cli",
@@ -45,22 +46,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "latest",
-    "@tree-sitter-grammars/tree-sitter-toml": "^0.7.0",
-    "@tree-sitter-grammars/tree-sitter-xml": "^0.7.0",
-    "@tree-sitter-grammars/tree-sitter-yaml": "^0.7.1",
     "@vscode/ripgrep": "^1.18.0",
-    "tree-sitter": "^0.22.4",
-    "tree-sitter-c-sharp": "^0.21.3",
-    "tree-sitter-cpp": "^0.23.4",
-    "tree-sitter-go": "^0.23.4",
-    "tree-sitter-groovy": "^0.1.2",
-    "tree-sitter-java": "^0.23.5",
-    "tree-sitter-kotlin": "^0.3.8",
-    "tree-sitter-php": "^0.23.12",
-    "tree-sitter-python": "^0.23.4",
-    "tree-sitter-ruby": "^0.23.1",
-    "tree-sitter-rust": "^0.23.1",
-    "tree-sitter-typescript": "^0.23.2"
+    "web-tree-sitter": "^0.26.10"
   },
   "devDependencies": {
     "@types/node": "^22",