@cstart/coldstart 2.2.15 → 2.2.16

package/hooks/capture-payload.mjs

@@ -16,7 +16,7 @@
  *              (the coordinator only sees the final message — #61).
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 // The spec shapes are NOT written here any more. They come from the one table
 // the write guide, the MCP tool description and `kb repair` also render from —
@@ -32,27 +32,93 @@ import { shapesBlock } from "./note-shape.mjs";
  * checklist + the write contract) was delivered one-shot and lost to compaction
  * — the agent had to re-derive the note shape from memory 80 tool-calls later.
  *
- * So the pair now lives in the repo notebook, keyed by root, and holds BOTH:
- *   .worklist.json  structured scope (the coverage source of truth)
- *   .worklist.md    the full rendered payload — worklist + write contract
+ * So the pair now lives in the repo notebook and holds BOTH:
+ *   .worklist-<sid>-<aid>.json  structured scope (the coverage source of truth)
+ *   .worklist-<sid>-<aid>.md    today's worklist + a pointer (see below)
  * The agent re-Reads the .md whenever this scrolls away; `kb write` credits and
  * trims/clears the pair (src/kb/durable-worklist.ts) so a stale snapshot never
  * lingers, and the next capture fire regenerates it against live freshness.
  *
+ * The .md used to hold the FULL rendered payload — the ~150 lines of static
+ * DECIDE-FIRST/per-note/FLOWS/WRITE rules, byte-identical every session,
+ * duplicated onto disk every single fire. Since 2026-08-06 that static text
+ * lives once in a PERMANENT file, `.capture-instructions.md` (also gitignored,
+ * but never deleted/regenerated per fire — only rewritten if its version tag is
+ * stale, see INSTRUCTIONS_VERSION below); the per-session .md now holds only
+ * the worklist + a pointer to it. The payload delivered to the agent THIS turn
+ * (buildCapturePayload's return value) is unaffected — it still inlines the
+ * full instructions text so nothing changes for the current fire, only what's
+ * persisted for a later re-Read.
+ *
+ * KEYED BY <sid>-<aid>, the SAME identity as the tmpdir evidence marker — NOT by
+ * root, and NOT by sid alone. A subagent shares its parent's session id, so a
+ * sid-only (or root-only) key would let a subagent's capture clobber the main
+ * agent's worklist. Each agent stream owns its own pair; the printed `kb write`
+ * carries `--session <sid> --agent <aid>` so finalize trims the right one.
+ *
  * CONTRACT TWIN: src/kb/durable-worklist.ts — keep the paths and the .json shape
- * (ts, sid, files:[{path,tier,needsNote}], wrote:[]) in step. Both gitignored
- * (src/kb/store.ts initSkeleton). One active worklist per repo (concurrent
- * sessions last-write-wins, an accepted edge). Best-effort: capture must never
- * fail because these could not be written.
+ * (ts, sid, aid, files:[{path,tier,needsNote}], wrote:[]) in step. Both gitignored
+ * (src/kb/store.ts initSkeleton). Best-effort: capture must never fail because
+ * these could not be written.
  */
-export function worklistJsonPath(root) {
-  return join(root, ".coldstart", "notebook", ".worklist.json");
+export function worklistJsonPath(root, sid, aid) {
+  const k = worklistKey(sid, aid);
+  return join(root, ".coldstart", "notebook", k ? `.worklist-${k}.json` : ".worklist.json");
+}
+export function worklistMdPath(root, sid, aid) {
+  const k = worklistKey(sid, aid);
+  return join(root, ".coldstart", "notebook", k ? `.worklist-${k}.md` : ".worklist.md");
+}
+function worklistKey(sid, aid) {
+  const s = String(sid ?? "").replace(/[^A-Za-z0-9_-]/g, "");
+  return s ? `${s}-${String(aid ?? "").replace(/[^A-Za-z0-9_-]/g, "") || "main"}` : "";
 }
-export function worklistMdPath(root) {
-  return join(root, ".coldstart", "notebook", ".worklist.md");
+
+// Abandoned sessions' worklist pairs would otherwise accrue forever (a session
+// that fires once then never captures again leaves its pair behind). Prune any
+// sibling worklist file whose json is older than this on each fire — long enough
+// that a still-live session is never touched, short enough to stay tidy.
+const STALE_WORKLIST_MS = 3 * 24 * 60 * 60 * 1000;
+function pruneStaleWorklists(dir, keepKey) {
+  try {
+    for (const n of readdirSync(dir)) {
+      const m = /^\.worklist-([A-Za-z0-9_-]+)\.json$/.exec(n);
+      if (!m || m[1] === keepKey) continue;
+      // Age by the json's own ts; fall back to file mtime when ts is absent or
+      // unreadable, NEVER to 0 — a ts-less-but-recent file must not read as 1970
+      // and get deleted out from under a live session.
+      let ts = 0;
+      try { ts = JSON.parse(readFileSync(join(dir, n), "utf8"))?.ts || statMtime(join(dir, n)); } catch { ts = statMtime(join(dir, n)); }
+      if (Date.now() - ts < STALE_WORKLIST_MS) continue;
+      for (const p of [join(dir, n), join(dir, n.replace(/\.json$/, ".md"))]) {
+        try { unlinkSync(p); } catch { /* best-effort */ }
+      }
+    }
+  } catch { /* best-effort */ }
+}
+function statMtime(p) { try { return statSync(p).mtimeMs; } catch { return 0; } }
+
+/**
+ * The .md half of the durable pair used to hold the FULL rendered payload
+ * (instructions + worklist) — meaning the ~150-line static instructions were
+ * duplicated onto disk once per session, every session, forever. Since
+ * 2026-08-06 that static text lives once in the permanent
+ * .capture-instructions.md (below); the per-session .md only needs to point at
+ * it plus carry the part that's actually per-session, the worklist.
+ */
+function renderDurableMd(sid, aid, entries) {
+  return `**Notebook capture point.** Full instructions: \`.coldstart/notebook/.capture-instructions.md\` \
+(stable — re-Read it once; it does not change per session). This file holds only today's worklist.
+
+WORKLIST — files you actually read this session, most-worked first:
+
+${worklistLines(entries)}
+
+Write command: node <cli> kb write /tmp/notes.json --root <root> --session ${sid} --agent ${aid} --force
+`;
 }
 
-function writeDurableWorklist(root, sid, entries, mdBody) {
+function writeDurableWorklist(root, sid, aid, entries) {
   if (!root || !entries?.length) return;
   try {
     // needsNote: no note yet, or the note it has is stale. A file whose note is
@@ -63,16 +129,18 @@ function writeDurableWorklist(root, sid, entries, mdBody) {
       tier: e.tier,
       needsNote: !e.notes?.length || e.notes.some((n) => n.state === "changed" || n.state === "missing"),
     }));
-    mkdirSync(join(root, ".coldstart", "notebook"), { recursive: true });
-    writeFileSync(worklistJsonPath(root), JSON.stringify({ ts: Date.now(), sid, files, wrote: [] }));
-    writeFileSync(worklistMdPath(root), mdBody);
+    const dir = join(root, ".coldstart", "notebook");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(worklistJsonPath(root, sid, aid), JSON.stringify({ ts: Date.now(), sid, aid: aid || "main", files, wrote: [] }));
+    writeFileSync(worklistMdPath(root, sid, aid), renderDurableMd(sid, aid || "main", entries));
+    pruneStaleWorklists(dir, worklistKey(sid, aid));
   } catch { /* best-effort */ }
 }
 
 /**
  * SPIKE (experimental, undocumented): a repo can replace the shipped checklist
  * with its own `.coldstart/checklist.md`. Placeholders {{WORKLIST}}, {{CLI}},
- * {{ROOT}}, {{SID}} are substituted. The worklist is LOAD-BEARING (it is the
+ * {{ROOT}}, {{SID}}, {{AID}} are substituted. The worklist is LOAD-BEARING (it is the
  * scope rule) — an override that omits {{WORKLIST}} gets it appended anyway.
  * Trigger mechanics stay in code; only the prompt text is overridable. Merge
  * semantics when the shipped default evolves = none (the override wins
@@ -86,72 +154,31 @@ function loadChecklistOverride(root) {
 }
 
 /**
- * worklist entry: { path, tier, retouches, notes: [{id, type, state}], noConsumers }
- *   tier: "edited ×N" | "read" | "skimmed"
+ * The shipped instructions (DECIDE-FIRST rules, per-note rules, FLOWS, WRITE
+ * mechanics) are identical every fire, every session — only the worklist and a
+ * handful of interpolated values change. Since 2026-08-06 this static text is
+ * generated ONCE into a permanent file (`.capture-instructions.md`, gitignored
+ * like the rest of the durable-worklist pair, but never deleted/regenerated per
+ * fire) instead of being duplicated onto disk in every session's .md — same
+ * placeholder mechanism as the user-authored checklist override above, so both
+ * paths share one substitution pass in renderCapturePayload.
+ *
+ * VERSIONED so an upgrade that changes the shipped text self-heals an existing
+ * repo's stale copy instead of silently drifting; bump when the template below
+ * changes.
  */
-function worklistLines(entries) {
-  const lines = [];
-  for (const e of entries) {
-    const ann = [];
-    ann.push(`[${e.tier}]`);
-    if (!e.notes?.length) {
-      ann.push("no note yet");
-    } else {
-      for (const n of e.notes) {
-        if (n.state === "fresh") {
-          ann.push(`note ${n.id} (fresh) → update ONLY if this session taught something the note lacks (.coldstart/notebook/notes/${n.id}.md)`);
-        } else if (n.state === "changed" || n.state === "missing") {
-          ann.push(`note ${n.id} (STALE) → fix or re-stamp; list the path in "verified" (.coldstart/notebook/notes/${n.id}.md)`);
-        } else {
-          ann.push(`note ${n.id} → read it first, update by its "id" (.coldstart/notebook/notes/${n.id}.md)`);
-        }
-      }
-    }
-    if (e.noConsumers) ann.push("no consumers in import graph");
-    lines.push(`- ${e.path}   ${ann.join(" · ")}`);
-  }
-  return lines.join("\n");
-}
+const INSTRUCTIONS_VERSION = 1;
+const INSTRUCTIONS_VERSION_TAG = `<!-- coldstart:capture-instructions:v${INSTRUCTIONS_VERSION} -->`;
 
-export function buildCapturePayload(args) {
-  const payload = renderCapturePayload(args);
-  // Persist the WHOLE payload durably so the agent can re-Read it later, and the
-  // structured scope for `kb write` coverage. Best-effort; never blocks capture.
-  writeDurableWorklist(args.root, args.sid, args.entries, payload);
-  return payload;
+function captureInstructionsPath(root) {
+  return join(root, ".coldstart", "notebook", ".capture-instructions.md");
 }
 
-function renderCapturePayload({ root, cli, sid, entries, envelope }) {
-  const opening = envelope === "block"
-    ? "Handle capture now, then stop."
-    : envelope === "manual"
-    ? "You invoked this capture yourself (/capture-notes) — handle it now, then carry on."
-    : "Handle capture first, then continue with the user's request.";
-
-  const tail = envelope === "subagent"
-    ? `\nOnce 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.`
-    : "";
-
-  const override = loadChecklistOverride(root);
-  if (override) {
-    const worklist = worklistLines(entries);
-    let body = override
-      .replaceAll("{{CLI}}", String(cli))
-      .replaceAll("{{ROOT}}", String(root))
-      .replaceAll("{{SID}}", String(sid));
-    body = body.includes("{{WORKLIST}}")
-      ? body.replaceAll("{{WORKLIST}}", worklist)
-      : `${body.trimEnd()}\n\nWORKLIST — files you actually read this session, most-worked first \
-(your scope; if you edited or deep-read a file that isn't listed, you can note it too):\n\n${worklist}`;
-    return `**Notebook capture point.** ${opening}\n\n${body.trimEnd()}${tail}`;
-  }
-
-  return `**Notebook capture point.** You have completed work and gathered knowledge as part \
-of it — knowledge a future agent could use. This repo keeps that knowledge in a notebook: \
-notes are searched and served to future cold agents when their task matches. ${opening}
+function shippedInstructionsTemplate() {
+  return `${INSTRUCTIONS_VERSION_TAG}
+You have completed work and gathered knowledge as part of it — knowledge a future agent \
+could use. This repo keeps that knowledge in a notebook: notes are searched and served to \
+future cold agents when their task matches.
 
 DECIDE FIRST — as the agent who worked on this task, you know its exact intent:
 1. So you, not any rule, are best suited to judge whether this work was about the code in \
@@ -169,14 +196,15 @@ changed and what you had to understand to change it, and that is precisely the k
 cold agent lacks. The default for an edited file is a note. Walk the worklist top to bottom \
 and decide each one explicitly; do not stop at the first two or three. If you end up writing \
 notes for well under half the [edited] files, you have under-captured — say which files you \
-skipped and why, so the decision is visible instead of silent. This whole checklist (worklist \
-+ the write contract below) is saved at \`.coldstart/notebook/.worklist.md\` — re-Read that file \
-any time this session if this scrolls out of context. Your \`kb write\` call ends with a coverage \
-line naming any worked file still without a note; read it back before you finish.
+skipped and why, so the decision is visible instead of silent. These instructions are \
+permanent at \`.coldstart/notebook/.capture-instructions.md\`; today's worklist is at \
+\`.coldstart/notebook/.worklist-{{SID}}-{{AID}}.md\` — re-Read whichever scrolls out of context \
+this session. Your \`kb write\` call ends with a coverage line naming any worked file still \
+without a note; read it back before you finish.
 
 WORKLIST — files you actually read this session, most-worked first:
 
-${worklistLines(entries)}
+{{WORKLIST}}
 
 FOR EACH NOTE:
 4. Say only what you verified in THIS file, this session. A confident whole-file claim from \
@@ -256,14 +284,102 @@ found wrong: {"op":"retract","id":"<id>","target":{"kind":"note"}} (as one array
   cat > /tmp/notes.json <<'JSON'
   [ {…note 1…}, {…note 2…} ]
 JSON
-  node ${cli} kb write /tmp/notes.json --root ${root} --session ${sid} --force
-  Full shapes: run \`node ${cli} kb write --root ${root}\` with no spec — it prints the guide.
+  node {{CLI}} kb write /tmp/notes.json --root {{ROOT}} --session {{SID}} --agent {{AID}} --force
+  Full shapes: run \`node {{CLI}} kb write --root {{ROOT}}\` with no spec — it prints the guide.
+  (Keep --session/--agent exactly as written — they point coverage at THIS agent's worklist.)
 
 FLOW DECISION — record what you decided about FLOWS (created a new one, folded into an \
 existing one, or none) so the flow gate can be measured. Ride it on the SAME batch write — it \
 is a flag, not a second command:
-  node ${cli} kb write /tmp/notes.json --root ${root} --session ${sid} --force \\
+  node {{CLI}} kb write /tmp/notes.json --root {{ROOT}} --session {{SID}} --agent {{AID}} --force \\
     --decision <none|new|update> [--id <flow id>] --why "<one clause>"
 Only when you wrote NO notes at all is there no write to carry it, and then run it alone:
-  node ${cli} kb flow-decision --decision none --why "<one clause>" --root ${root} --session ${sid}${tail}`;
+  node {{CLI}} kb flow-decision --decision none --why "<one clause>" --root {{ROOT}} --session {{SID}}`;
+}
+
+/** Ensure the permanent instructions file exists and is current; return its
+ *  body (without the version-tag line). Best-effort — a write failure still
+ *  returns the shipped text so THIS fire's payload is unaffected; only the
+ *  on-disk persistence for later re-Reads is at risk. */
+function ensureCaptureInstructions(root) {
+  const p = captureInstructionsPath(root);
+  try {
+    const existing = readFileSync(p, "utf8");
+    if (existing.startsWith(INSTRUCTIONS_VERSION_TAG)) {
+      return existing.slice(existing.indexOf("\n") + 1);
+    }
+  } catch { /* missing — write below */ }
+  const text = shippedInstructionsTemplate();
+  try {
+    mkdirSync(join(root, ".coldstart", "notebook"), { recursive: true });
+    writeFileSync(p, text);
+  } catch { /* best-effort; still usable in-memory this fire */ }
+  return text.slice(text.indexOf("\n") + 1);
+}
+
+/**
+ * worklist entry: { path, tier, retouches, notes: [{id, type, state}], noConsumers }
+ *   tier: "edited ×N" | "read" | "skimmed"
+ */
+function worklistLines(entries) {
+  const lines = [];
+  for (const e of entries) {
+    const ann = [];
+    ann.push(`[${e.tier}]`);
+    if (!e.notes?.length) {
+      ann.push("no note yet");
+    } else {
+      for (const n of e.notes) {
+        if (n.state === "fresh") {
+          ann.push(`note ${n.id} (fresh) → update ONLY if this session taught something the note lacks (.coldstart/notebook/notes/${n.id}.md)`);
+        } else if (n.state === "changed" || n.state === "missing") {
+          ann.push(`note ${n.id} (STALE) → fix or re-stamp; list the path in "verified" (.coldstart/notebook/notes/${n.id}.md)`);
+        } else {
+          ann.push(`note ${n.id} → read it first, update by its "id" (.coldstart/notebook/notes/${n.id}.md)`);
+        }
+      }
+    }
+    if (e.noConsumers) ann.push("no consumers in import graph");
+    lines.push(`- ${e.path}   ${ann.join(" · ")}`);
+  }
+  return lines.join("\n");
+}
+
+export function buildCapturePayload(args) {
+  const payload = renderCapturePayload(args);
+  // Persist the structured scope (+ a small pointer .md — the static
+  // instructions live in the permanent .capture-instructions.md, not
+  // duplicated per session) so the agent can re-Read it later and `kb write`
+  // has coverage to check against. Best-effort; never blocks capture.
+  writeDurableWorklist(args.root, args.sid, args.aid, args.entries);
+  return payload;
+}
+
+function renderCapturePayload({ root, cli, sid, aid, entries, envelope }) {
+  aid = String(aid ?? "main").replace(/[^A-Za-z0-9_-]/g, "") || "main";
+  const opening = envelope === "block"
+    ? "Handle capture now, then stop."
+    : envelope === "manual"
+    ? "You invoked this capture yourself (/capture-notes) — handle it now, then carry on."
+    : "Handle capture first, then continue with the user's request.";
+
+  const tail = envelope === "subagent"
+    ? `\nOnce 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.`
+    : "";
+
+  const worklist = worklistLines(entries);
+  const source = loadChecklistOverride(root) ?? ensureCaptureInstructions(root);
+  let body = source
+    .replaceAll("{{CLI}}", String(cli))
+    .replaceAll("{{ROOT}}", String(root))
+    .replaceAll("{{SID}}", String(sid))
+    .replaceAll("{{AID}}", String(aid));
+  body = body.includes("{{WORKLIST}}")
+    ? body.replaceAll("{{WORKLIST}}", worklist)
+    : `${body.trimEnd()}\n\nWORKLIST — files you actually read this session, most-worked first \
+(your scope; if you edited or deep-read a file that isn't listed, you can note it too):\n\n${worklist}`;
+  return `**Notebook capture point.** ${opening}\n\n${body.trimEnd()}${tail}`;
 }

package/hooks/capture-sentinel.d.mts

@@ -0,0 +1,4 @@
+/** Types for capture-sentinel.mjs — plain ESM so the capture hooks can import
+ *  it without a build step; this declaration is what lets the TypeScript side
+ *  (src/init.ts) import the same file instead of copying the string. */
+export declare const CAPTURE_SENTINEL: string;

package/hooks/capture-sentinel.mjs

@@ -0,0 +1,10 @@
+/**
+ * capture-sentinel.mjs — the marker `/capture-notes` command bodies carry so a
+ * host's own pre-prompt recall hook can recognize "this submitted prompt IS
+ * the capture command" and run `kb-elicit.mjs --manual` itself with the real
+ * session id it already has (Cursor/Codex have no way to pass a session id
+ * INTO the command the way Claude's `!`-expansion does). Wording in the
+ * command body can drift; this string must not — it is grepped verbatim
+ * against the raw submitted prompt.
+ */
+export const CAPTURE_SENTINEL = "<!-- coldstart:capture-notes -->";

package/hooks/codex-kb-elicit.mjs

@@ -105,7 +105,11 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     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`);
+    // Unified marker namespace (2026-08-06): manual /capture-notes always ran
+    // the SHARED kb-elicit.mjs --manual, which reads coldstart-kb-<sid>-<aid>.json
+    // — a per-host prefix here meant it could never see this host's own
+    // automatic evidence. One prefix for all three hosts fixes that outright.
+    const marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
     let state = null;
     try {
       const parsed = JSON.parse(readFileSync(marker, "utf8"));
@@ -140,7 +144,7 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
 
     const entries = worklistEntries(CLI, root, fresh, state.files, log);
     const payload = buildCapturePayload({
-      root, cli: CLI, sid, entries,
+      root, cli: CLI, sid, aid, entries,
       envelope: isSubagent ? "subagent" : "block",
     });
     logCaptureEvent(root, {

package/hooks/codex-kb-recall.mjs

@@ -18,6 +18,17 @@
  * arriving via PRs are a prompt-injection surface; the framing line is the
  * cheap mitigation.
  *
+ * MANUAL CAPTURE ON-DEMAND (2026-08-06): Codex's `/capture-notes` skill has no
+ * way to pass its own real session id into `kb-elicit.mjs --manual` the way
+ * Claude's `!`-expansion does — the skill body used to just ask the agent to
+ * run the command itself, blind to which session it's in. But THIS hook
+ * receives a real `input.session_id` on every prompt. So: when the submitted
+ * prompt IS the capture skill (its body carries a stable sentinel,
+ * CAPTURE_SENTINEL), run `--manual --session <real sid>` right here and inject
+ * its output — deterministic, no LLM has to type a correct `--session <id>`.
+ * The skill body keeps "run this in the terminal" as a fallback for when this
+ * hook is disabled or fails. See hooks/capture-sentinel.mjs.
+ *
  * Self-contained + fail-open: ANY error → exit 0 with no stdout → nothing
  * injected, the prompt proceeds untouched.
  */
@@ -29,6 +40,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 // Strip host telemetry wrappers before the query is built — see recall-query.mjs.
 import { recallQuery } from "./recall-query.mjs";
+import { CAPTURE_SENTINEL } from "./capture-sentinel.mjs";
 // Per-session dedup shared with the other recall hooks — see recall-seen.mjs.
 // Hosts with no transcript path never reset; dedup still holds for the session.
 import { readSeen, writeSeen, idsInPage, seenArgs } from "./recall-seen.mjs";
@@ -78,11 +90,43 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
 
     const sid = String(input.session_id || "").replace(/[^\w-]/g, "");
 
-    // No notebook → no tax, not even a child process.
-    if (!existsSync(join(root, ".coldstart", "notebook", ".raw"))) process.exit(0);
+    // The submitted prompt IS /capture-notes (its skill body carries this
+    // sentinel) → run the on-demand capture ourselves with the real session id
+    // this hook already has, instead of leaving the agent to guess one.
+    let manual = "";
+    if (sid && String(input.prompt || "").includes(CAPTURE_SENTINEL)) {
+      try {
+        const elicit = fileURLToPath(new URL("./kb-elicit.mjs", import.meta.url));
+        manual = execFileSync("node", [elicit, "--manual", "--session", sid, "--root", root], {
+          encoding: "utf8",
+          timeout: 8000,
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (manual) log(`MANUAL-INJECT session=${sid} bytes=${manual.length}`);
+      } catch (e) {
+        log(`manual-capture-inject failed: ${String(e).split("\n")[0]}`);
+      }
+    }
+
+    // Below this point, every early exit falls back to delivering the manual
+    // capture alone (if we have one) instead of exiting silently — a recall
+    // miss must never swallow an explicit /capture-notes.
+    const deliverManualOnlyAndExit = (why) => {
+      if (!manual) process.exit(0);
+      log(`INJECT bytes=${manual.length} (manual only, ${why})`);
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: manual },
+      }));
+      process.exit(0);
+    };
+
+    // No notebook → no recall tax, not even a child process (the manual
+    // capture above is independent of the notebook existing — it's what
+    // creates the first note).
+    if (!existsSync(join(root, ".coldstart", "notebook", ".raw"))) deliverManualOnlyAndExit("no notebook yet");
 
     const prompt = recallQuery(input.prompt, MAX_QUERY_CHARS);
-    if (!prompt) process.exit(0);
+    if (!prompt) deliverManualOnlyAndExit("empty query");
 
     // Ephemeral Codex runs expose no rollout path; readSeen then never resets,
     // which is the safe direction — dedup simply holds for the whole session.
@@ -99,12 +143,12 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       });
     } catch (e) {
       log(`search failed/timed out: ${String(e).split("\n")[0]}`);
-      process.exit(0);
+      deliverManualOnlyAndExit("search failed");
     }
 
     if (!page.trim() || page.startsWith("No notebook notes match") || page.startsWith("No notebook in")) {
       log(`no hits (promptChars=${prompt.length})`);
-      process.exit(0);
+      deliverManualOnlyAndExit("no recall hits");
     }
 
     // Record what this page hands over before the size guards can trim it — a
@@ -140,6 +184,11 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // never exceed 8.5KB.
     if (block.length > 8500) block = block.slice(0, 8500) + "\n…(truncated)";
 
+    // An explicit /capture-notes rides FIRST — it's what the user asked for
+    // this turn. If the combination would spill past the host's payload cap,
+    // recall yields — the capture checklist must arrive whole.
+    if (manual) block = manual.length + block.length > 9500 ? manual : `${manual}\n\n---\n\n${block}`;
+
     // Arm the PostToolUse nudge detectors (nudge-handler.mjs gates its spiral
     // detectors on seen_find so it never nags sessions that don't use coldstart).
     // An injected session IS coldstart-aware even if it never runs `find` — the

package/hooks/cursor-kb-elicit.mjs

@@ -121,7 +121,11 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     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`);
+    // Unified marker namespace (2026-08-06): manual /capture-notes always ran
+    // the SHARED kb-elicit.mjs --manual, which reads coldstart-kb-<sid>-<aid>.json
+    // — a per-host prefix here meant it could never see this host's own
+    // automatic evidence. One prefix for all three hosts fixes that outright.
+    const marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
     let state = null;
     try {
       const parsed = JSON.parse(readFileSync(marker, "utf8"));
@@ -152,7 +156,7 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
       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" });
+      const payload = buildCapturePayload({ root, cli: CLI, sid, aid, 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 }));
@@ -188,11 +192,11 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     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" });
+      const payload = buildCapturePayload({ root, cli: CLI, sid, aid, 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" });
+      const payload = buildCapturePayload({ root, cli: CLI, sid, aid, entries, envelope: "inject" });
       writePendingCapture(sid, decision.fire, payload);
     }
   } catch (e) {

package/hooks/cursor-kb-recall.mjs

@@ -16,6 +16,17 @@
  *     injection channel used here. If a future Cursor build stops honoring it,
  *     recall silently no-ops (fail-open) — nav + capture are unaffected.
  *
+ * MANUAL CAPTURE ON-DEMAND (2026-08-06): Cursor's `/capture-notes` command has
+ * no `!`-expansion (unlike Claude), so it can't pass its own real session id to
+ * `kb-elicit.mjs --manual` the way Claude does — the command body used to just
+ * ask the agent to run the command itself, blind to which session it's in. But
+ * THIS hook receives a real `input.session_id` on every prompt. So: when the
+ * submitted prompt IS the capture command (its body carries a stable sentinel,
+ * CAPTURE_SENTINEL), run `--manual --session <real sid>` right here and inject
+ * its output the same way a pending automatic fire is injected — deterministic,
+ * no LLM has to type a correct `--session <id>`. The command body keeps "run
+ * this in the terminal" as a fallback for when this hook is disabled/fails.
+ *
  * Self-contained + fail-open: ANY error → exit 0, no stdout → nothing injected.
  */
 
@@ -31,6 +42,7 @@ import { cursorRoot } from "./cursor-input.mjs";
 import { takePendingCapture } from "./elicit-core.mjs";
 // Strip host telemetry wrappers before the query is built — see recall-query.mjs.
 import { recallQuery } from "./recall-query.mjs";
+import { CAPTURE_SENTINEL } from "./capture-sentinel.mjs";
 // Per-session dedup shared with the other recall hooks — see recall-seen.mjs.
 // Hosts with no transcript path never reset; dedup still holds for the session.
 import { readSeen, writeSeen, idsInPage, seenArgs } from "./recall-seen.mjs";
@@ -83,7 +95,28 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
     // 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);
+    let pending = takePendingCapture(sid);
+
+    // The submitted prompt IS /capture-notes (its command body carries this
+    // sentinel) → run the on-demand capture ourselves with the real session id
+    // this hook already has, instead of leaving the agent to guess one. See
+    // the file header and hooks/capture-sentinel.mjs.
+    if (sid && String(input.prompt || "").includes(CAPTURE_SENTINEL)) {
+      try {
+        const elicit = fileURLToPath(new URL("./kb-elicit.mjs", import.meta.url));
+        const manual = execFileSync("node", [elicit, "--manual", "--session", sid, "--root", root], {
+          encoding: "utf8",
+          timeout: 8000,
+          stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (manual.trim()) {
+          pending = pending ? `${manual.trim()}\n\n---\n\n${pending}` : manual.trim();
+          log(`MANUAL-INJECT session=${sid} bytes=${manual.length}`);
+        }
+      } catch (e) {
+        log(`manual-capture-inject failed: ${String(e).split("\n")[0]}`);
+      }
+    }
 
     const prompt = recallQuery(input.prompt, MAX_QUERY_CHARS);