@cstart/coldstart 2.0.3 → 2.1.0

package/dist/unwire.js

@@ -0,0 +1,304 @@
+/**
+ * coldstart unwire — the reverse of `coldstart init`.
+ *
+ * `npm uninstall` cannot clean the per-repo artifacts init wrote (npm fires no
+ * pre/postuninstall reliably, and a global uninstall has no registry of which
+ * repos were inited). So, like husky, coldstart ships an explicit reverse
+ * command. It removes ONLY coldstart-owned markers from the files init touched —
+ * never clobbering user content in shared files — using the SAME detectors init
+ * uses for idempotent re-runs (isColdstartHookEntry / isKbHookEntry /
+ * isCodexHookEntry / isCursorHookEntry / stripCodexColdstartTable). Symmetry:
+ * init writes → unwire removes.
+ *
+ * Scope: all four clients are swept unconditionally (init doesn't record which
+ * client was wired), so unwire cleans whatever it finds and reports "absent" for
+ * the rest. The notebook (`.coldstart/notebook/`) is KEPT by default — it's
+ * committed/shared user data; `--purge` opts in to deleting it plus its git
+ * plumbing (the `.coldstart/` gitignore line + the merge=union gitattribute).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { IMPORT_LINE, AGENTS_START, AGENTS_END, isColdstartHookEntry, isKbHookEntry, isCodexHookEntry, isCursorHookEntry, stripCodexColdstartTable, } from './init.js';
+const DIVIDER = '─'.repeat(60);
+function out(msg) {
+    process.stderr.write(msg + '\n');
+}
+function label(res) {
+    if (typeof res === 'object')
+        return `NOT changed: ${res.error}`;
+    return res;
+}
+// ---------------------------------------------------------------------------
+// Small filesystem helpers
+// ---------------------------------------------------------------------------
+/** Delete a file if it exists. */
+function removeFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return 'absent';
+    fs.unlinkSync(filePath);
+    return 'removed';
+}
+/** Best-effort remove a directory only if it is now empty. Walks up the given
+ *  chain (child → parent) so `.cursor/rules` then `.cursor` both go if empty. */
+function rmEmptyDirs(...dirs) {
+    for (const dir of dirs) {
+        try {
+            if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch {
+            /* best-effort — a non-empty or busy dir just stays */
+        }
+    }
+}
+/** Read a JSON config file. Distinguishes missing (existed:false) from invalid
+ *  (error set) so we can leave a user-owned malformed file untouched. */
+function readJson(filePath) {
+    if (!fs.existsSync(filePath))
+        return { config: {}, existed: false };
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed && typeof parsed === 'object')
+            return { config: parsed, existed: true };
+        return { config: {}, existed: true };
+    }
+    catch {
+        return { config: {}, existed: true, error: `${filePath} is not valid JSON — left untouched` };
+    }
+}
+/**
+ * Strip coldstart-owned entries from a hooks-map config (Claude settings.json,
+ * Codex/Cursor hooks.json). For each listed event key, filter out entries `isOurs`
+ * matches; drop keys that become empty. Prune the hooks map, then any leftover
+ * keys named in `ownedTopKeys` (e.g. Cursor's `version`, which init sets) once the
+ * map is empty; delete the file if the whole config is then empty.
+ *
+ * Returns 'stripped' if we removed anything, 'absent' if there was nothing of
+ * ours, or an error for invalid JSON.
+ */
+function stripHooksConfig(filePath, hooksKey, events, isOurs, ownedTopKeys = []) {
+    const { config, existed, error } = readJson(filePath);
+    if (!existed)
+        return 'absent';
+    if (error)
+        return { error };
+    const hooksCfg = config[hooksKey] && typeof config[hooksKey] === 'object'
+        ? config[hooksKey]
+        : null;
+    if (!hooksCfg)
+        return 'absent';
+    let changed = false;
+    for (const ev of events) {
+        const arr = hooksCfg[ev];
+        if (!Array.isArray(arr))
+            continue;
+        const kept = arr.filter((e) => !isOurs(e));
+        if (kept.length === arr.length)
+            continue;
+        changed = true;
+        if (kept.length === 0)
+            delete hooksCfg[ev];
+        else
+            hooksCfg[ev] = kept;
+    }
+    if (!changed)
+        return 'absent';
+    // Prune the now-empty hooks map, then any coldstart-owned top-level keys that
+    // only exist because we wrote the hooks (Cursor's `version`).
+    if (Object.keys(hooksCfg).length === 0) {
+        delete config[hooksKey];
+        for (const k of ownedTopKeys)
+            delete config[k];
+    }
+    else {
+        config[hooksKey] = hooksCfg;
+    }
+    if (Object.keys(config).length === 0) {
+        fs.unlinkSync(filePath);
+    }
+    else {
+        fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+    }
+    return 'stripped';
+}
+/** Remove `mcpServers.coldstart` from a JSON MCP config, pruning empties and
+ *  deleting the file if it becomes empty. */
+function unwireJsonMcp(cwd, relFile) {
+    const filePath = path.join(cwd, relFile);
+    const { config, existed, error } = readJson(filePath);
+    if (!existed)
+        return 'absent';
+    if (error)
+        return { error };
+    const servers = config.mcpServers && typeof config.mcpServers === 'object'
+        ? config.mcpServers
+        : null;
+    if (!servers || !('coldstart' in servers))
+        return 'absent';
+    delete servers.coldstart;
+    if (Object.keys(servers).length === 0)
+        delete config.mcpServers;
+    else
+        config.mcpServers = servers;
+    if (Object.keys(config).length === 0)
+        fs.unlinkSync(filePath);
+    else
+        fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+    return 'stripped';
+}
+// ---------------------------------------------------------------------------
+// Per-artifact reversers
+// ---------------------------------------------------------------------------
+/** Remove the `@coldstart.md` import line from CLAUDE.md (leave the rest). */
+function unwireClaudeImport(cwd) {
+    const filePath = path.join(cwd, 'CLAUDE.md');
+    if (!fs.existsSync(filePath))
+        return 'absent';
+    const text = fs.readFileSync(filePath, 'utf8');
+    const lines = text.split('\n');
+    const kept = lines.filter((l) => l.trim() !== IMPORT_LINE);
+    if (kept.length === lines.length)
+        return 'absent';
+    // Collapse a blank-line run left behind, then trim trailing blanks.
+    const collapsed = [];
+    for (const l of kept) {
+        if (l.trim() === '' && collapsed.length > 0 && collapsed[collapsed.length - 1].trim() === '')
+            continue;
+        collapsed.push(l);
+    }
+    while (collapsed.length && collapsed[collapsed.length - 1].trim() === '')
+        collapsed.pop();
+    const next = collapsed.join('\n');
+    // If only init's own scaffold heading is left, init created the file — remove it.
+    if (next.trim() === '' || next.trim() === '# Project guidance')
+        fs.unlinkSync(filePath);
+    else
+        fs.writeFileSync(filePath, next + '\n');
+    return 'stripped';
+}
+/** Excise the `<!-- coldstart:start -->…<!-- coldstart:end -->` block from
+ *  AGENTS.md, preserving the rest of the user's file. */
+function unwireCodexAgents(cwd) {
+    const filePath = path.join(cwd, 'AGENTS.md');
+    if (!fs.existsSync(filePath))
+        return 'absent';
+    const text = fs.readFileSync(filePath, 'utf8');
+    const start = text.indexOf(AGENTS_START);
+    if (start === -1)
+        return 'absent';
+    const end = text.indexOf(AGENTS_END, start);
+    if (end === -1)
+        return 'absent';
+    const before = text.slice(0, start).replace(/\n+$/, '\n');
+    const after = text.slice(end + AGENTS_END.length).replace(/^\n+/, '');
+    let next = before + (after ? '\n' + after : '');
+    if (next.trim() === '# AGENTS.md')
+        next = ''; // only our scaffold remained
+    if (next.trim() === '')
+        fs.unlinkSync(filePath);
+    else
+        fs.writeFileSync(filePath, next.endsWith('\n') ? next : next + '\n');
+    return 'stripped';
+}
+/** Strip `[mcp_servers.coldstart]` from .codex/config.toml. */
+function unwireCodexMcp(cwd) {
+    const filePath = path.join(cwd, '.codex', 'config.toml');
+    if (!fs.existsSync(filePath))
+        return 'absent';
+    const before = fs.readFileSync(filePath, 'utf8');
+    const after = stripCodexColdstartTable(before).replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+    if (after.replace(/\s+/g, '') === before.replace(/\s+/g, ''))
+        return 'absent';
+    const trimmed = after.replace(/\n+$/, '');
+    if (trimmed === '')
+        fs.unlinkSync(filePath);
+    else
+        fs.writeFileSync(filePath, trimmed + '\n');
+    return 'stripped';
+}
+/** Drop the `.coldstart/` line from .gitignore (added by init's private default). */
+function removeNotebookGitignore(cwd) {
+    const giPath = path.join(cwd, '.gitignore');
+    if (!fs.existsSync(giPath))
+        return 'absent';
+    const lines = fs.readFileSync(giPath, 'utf8').split('\n');
+    const kept = lines.filter((l) => { const t = l.trim(); return t !== '.coldstart/' && t !== '.coldstart'; });
+    if (kept.length === lines.length)
+        return 'absent';
+    fs.writeFileSync(giPath, kept.join('\n'));
+    return 'stripped';
+}
+/** Drop the notebook merge=union line from .gitattributes. */
+function removeNotebookGitattributes(cwd) {
+    const gaPath = path.join(cwd, '.gitattributes');
+    if (!fs.existsSync(gaPath))
+        return 'absent';
+    const line = '.coldstart/notebook/.raw/*.jsonl merge=union';
+    const lines = fs.readFileSync(gaPath, 'utf8').split('\n');
+    const kept = lines.filter((l) => l.trim() !== line);
+    if (kept.length === lines.length)
+        return 'absent';
+    const next = kept.join('\n').replace(/\n+$/, '');
+    if (next.trim() === '')
+        fs.unlinkSync(gaPath);
+    else
+        fs.writeFileSync(gaPath, next + '\n');
+    return 'stripped';
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+const CLAUDE_HOOK_EVENTS = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'Stop', 'SubagentStop'];
+const CURSOR_HOOK_EVENTS = ['preToolUse', 'postToolUse', 'beforeSubmitPrompt', 'stop', 'subagentStop'];
+export async function runUnwire() {
+    const cwd = process.cwd();
+    const argv = process.argv.slice(3); // tokens after `unwire`
+    const purge = argv.includes('--purge');
+    out('');
+    out('coldstart unwire');
+    out(DIVIDER);
+    out(`  Removing coldstart-owned wiring from ${cwd}`);
+    out('');
+    // Claude Code
+    out('  Claude Code');
+    out(`    coldstart.md  — ${label(removeFile(path.join(cwd, 'coldstart.md')))}`);
+    out(`    CLAUDE.md     — ${label(unwireClaudeImport(cwd))} @coldstart.md import`);
+    out(`    settings.json — ${label(stripHooksConfig(path.join(cwd, '.claude', 'settings.json'), 'hooks', CLAUDE_HOOK_EVENTS, (e) => isColdstartHookEntry(e) || isKbHookEntry(e)))} find/gs + notebook hooks`);
+    out(`    .mcp.json     — ${label(unwireJsonMcp(cwd, '.mcp.json'))} MCP server`);
+    // Codex
+    out('  Codex');
+    out(`    AGENTS.md     — ${label(unwireCodexAgents(cwd))} coldstart block`);
+    out(`    hooks.json    — ${label(stripHooksConfig(path.join(cwd, '.codex', 'hooks.json'), 'hooks', CLAUDE_HOOK_EVENTS, isCodexHookEntry))} Codex hooks`);
+    out(`    config.toml   — ${label(unwireCodexMcp(cwd))} [mcp_servers.coldstart]`);
+    // Cursor
+    out('  Cursor');
+    out(`    coldstart.mdc — ${label(removeFile(path.join(cwd, '.cursor', 'rules', 'coldstart.mdc')))}`);
+    out(`    hooks.json    — ${label(stripHooksConfig(path.join(cwd, '.cursor', 'hooks.json'), 'hooks', CURSOR_HOOK_EVENTS, isCursorHookEntry, ['version']))} Cursor hooks`);
+    out(`    mcp.json      — ${label(unwireJsonMcp(cwd, path.join('.cursor', 'mcp.json')))} MCP server`);
+    // Notebook
+    out('  Notebook');
+    if (purge) {
+        const nb = path.join(cwd, '.coldstart', 'notebook');
+        let nbRes = 'absent';
+        if (fs.existsSync(nb)) {
+            fs.rmSync(nb, { recursive: true, force: true });
+            nbRes = 'removed';
+        }
+        out(`    .coldstart/notebook — ${label(nbRes)} (--purge: notes deleted)`);
+        out(`    .gitignore    — ${label(removeNotebookGitignore(cwd))} .coldstart/ line`);
+        out(`    .gitattributes — ${label(removeNotebookGitattributes(cwd))} merge=union line`);
+        rmEmptyDirs(path.join(cwd, '.coldstart'));
+    }
+    else {
+        out('    .coldstart/notebook — KEPT (committed/shared notes; use --purge to delete)');
+    }
+    // Tidy up now-empty coldstart dirs (best-effort).
+    rmEmptyDirs(path.join(cwd, '.cursor', 'rules'), path.join(cwd, '.cursor'), path.join(cwd, '.claude'), path.join(cwd, '.codex'));
+    out('');
+    out(DIVIDER);
+    out('Unwired. Re-add anytime with: coldstart init');
+    if (!purge)
+        out('The notebook was kept — `coldstart unwire --purge` also deletes it.');
+    out('');
+}
+//# sourceMappingURL=unwire.js.map

package/dist/unwire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwire.js","sourceRoot":"","sources":["../src/unwire.ts"],"names":[],"mappings":"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"}

package/hooks/codex-kb-elicit.mjs

@@ -295,17 +295,20 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     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 once per turn so a resumed thread can contribute new knowledge.
+    // 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); }
-    const tid = String(input.turn_id || sid).replace(/[^A-Za-z0-9_-]/g, "") || sid;
 
-    // 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 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-${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 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 */ }
 
     // Codex supplies the child's own rollout as agent_transcript_path on
     // SubagentStop. Its transcript_path is the parent's rollout at that event.
@@ -321,18 +324,25 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // 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) : [];
-
-    // 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.
+    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/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