@cstart/coldstart 2.2.7 → 2.2.9

package/hooks/recall-query.mjs

@@ -0,0 +1,83 @@
+/**
+ * recall-query.mjs — turn a raw UserPromptSubmit payload into a recall QUERY.
+ *
+ * The hosts do not hand us the user's words. They hand us the user's words
+ * WRAPPED IN HARNESS TELEMETRY: the file that happens to be open in the editor,
+ * the current selection, a finished subagent's summary, the expansion of a
+ * slash command. That text is file- and symbol-rich, so `kb search --hook`
+ * treats it as if the user had named those files — most damagingly through the
+ * path-name override in src/kb/search.ts, which boosts a note past every
+ * eligibility gate when the query string contains its anchor path. A stale-open
+ * editor tab then hijacks recall for turns at a time.
+ *
+ * So: strip the wrappers (tag AND content) before the query is built, and
+ * before truncation — a 1.5KB <ide_selection> ahead of a short question would
+ * otherwise eat the whole MAX_QUERY_CHARS budget and leave the real ask cut off.
+ *
+ * Only a NAMED set of tags is stripped. Anything else — including XML or HTML
+ * the user pasted deliberately — is left alone; over-stripping would silently
+ * drop real questions, which is the failure this is meant to prevent.
+ *
+ * Fail-open: on any error the raw text is returned unchanged.
+ */
+
+/** Harness-emitted wrappers, union across Claude Code / Cursor / Codex. A tag
+ *  a given host never emits simply never matches. */
+export const HARNESS_TAGS = [
+  // Claude Code
+  "system-reminder",
+  "ide_opened_file",
+  "ide_selection",
+  "ide_diagnostics",
+  "task-notification",
+  "local-command-caveat",
+  "local-command-stdout",
+  "local-command-stderr",
+  "command-name",
+  "command-message",
+  "command-args",
+  "user-prompt-submit-hook",
+  // Cursor
+  "browser_instruction",
+  // Codex
+  "environment_context",
+  "user_instructions",
+];
+
+const NAMES = HARNESS_TAGS.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+// Well-formed pair, content included. Non-greedy, /s so it spans newlines.
+const PAIRED = new RegExp(`<(${NAMES})(?:\\s[^>]*)?>[\\s\\S]*?<\\/\\1\\s*>`, "gi");
+// Leftovers: self-closing, or a lone open/close tag from a truncated payload.
+const LONE = new RegExp(`<\\/?(?:${NAMES})(?:\\s[^>]*)?\\/?>`, "gi");
+
+/**
+ * Strip harness wrappers from a raw prompt.
+ * @param {string} raw
+ * @returns {string} the user's own text; "" when nothing but telemetry remains.
+ */
+export function stripHarnessWrappers(raw) {
+  try {
+    let s = String(raw ?? "");
+    if (!s) return "";
+    // Nested wrappers (a system-reminder inside a task-notification) need more
+    // than one pass; bounded so a pathological payload cannot spin.
+    for (let i = 0; i < 4; i++) {
+      const next = s.replace(PAIRED, " ");
+      if (next === s) break;
+      s = next;
+    }
+    return s.replace(LONE, " ").replace(/[ \t]+/g, " ").trim();
+  } catch {
+    return String(raw ?? "");
+  }
+}
+
+/**
+ * The full prompt → query pipeline: strip, THEN truncate.
+ * @param {string} raw raw `input.prompt`
+ * @param {number} maxChars
+ * @returns {string} "" when there is nothing left to search for.
+ */
+export function recallQuery(raw, maxChars) {
+  return stripHarnessWrappers(raw).slice(0, maxChars).trim();
+}

package/hooks/recall-seen.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * recall-seen.mjs — per-session dedup state for the recall hooks.
+ *
+ * 61% of notebook injections re-showed a note the SAME session had already
+ * been given (worst case 12x). That is pure tax: the title and gist are
+ * already in the agent's context, so the repeat buys nothing and pushes the
+ * page toward the host's size cap. Each recall hook remembers the ids it has
+ * shown and passes them to `kb search --seen`, which drops them from the page
+ * it would otherwise have rendered (no backfill; all-seen => inject nothing).
+ *
+ * Reset on COMPACTION, not on a clock. After a compact the session id is
+ * unchanged but the agent's context is gone, so a previously-shown note is
+ * genuinely absent again and SHOULD be re-injectable. A shrinking transcript
+ * file is the observable signal — the same one kb-elicit uses for its own
+ * resume handling. Hosts that expose no transcript path (ephemeral Codex runs)
+ * simply never reset: dedup still works, it just holds for the whole session.
+ *
+ * Shared by kb-recall.mjs (Claude), cursor-kb-recall.mjs and
+ * codex-kb-recall.mjs so the three cannot drift. Every function is fail-open:
+ * any error leaves dedup OFF rather than blocking recall.
+ */
+
+import { readFileSync, writeFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const SEEN_TTL_MS = 24 * 60 * 60 * 1000;
+/** os.tmpdir(), NOT literal /tmp — that path is reserved for the find_nudge
+ *  state file, which the nudge handler reads back by an agreed literal path. */
+const seenPath = (sid) => join(tmpdir(), `coldstart-recall-seen-${sid}.json`);
+
+function transcriptSize(p) {
+  try { return p ? statSync(p).size : 0; } catch { return 0; }
+}
+
+/**
+ * Ids already shown this session. `log` is optional (each host has its own).
+ * Returns { ids, size } — pass both back to writeSeen.
+ */
+export function readSeen(sid, transcriptPath, log) {
+  if (!sid) return { ids: [], size: 0 };
+  try {
+    const st = JSON.parse(readFileSync(seenPath(sid), "utf8"));
+    if (!st || !Array.isArray(st.ids)) return { ids: [], size: 0 };
+    if (Date.now() - (st.ts || 0) > SEEN_TTL_MS) return { ids: [], size: 0 };
+    const now = transcriptSize(transcriptPath);
+    if (now && st.size && now < st.size) {
+      log?.(`compaction detected (${st.size} -> ${now} bytes): clearing ${st.ids.length} seen ids`);
+      return { ids: [], size: now };
+    }
+    return { ids: st.ids, size: st.size || 0 };
+  } catch { return { ids: [], size: 0 }; }
+}
+
+export function writeSeen(sid, ids, transcriptPath) {
+  if (!sid) return;
+  try {
+    writeFileSync(seenPath(sid), JSON.stringify({
+      ids: [...new Set(ids)].slice(-200), // bounded; a session never shows this many
+      size: transcriptSize(transcriptPath),
+      ts: Date.now(),
+    }));
+  } catch { /* fail-open: dedup is an optimisation, never a gate */ }
+}
+
+/** Note ids on a rendered pointer page — each hit carries `→ open: …/<id>.md`.
+ *  Read back off the rendered text so the hooks need no structured output. */
+export function idsInPage(page) {
+  return [...page.matchAll(/→ open:\s*\S*?notes\/([\w.-]+)\.md/g)].map((m) => m[1]);
+}
+
+/** The `--seen a,b,c` argv fragment, or [] when there is nothing to exclude. */
+export function seenArgs(ids) {
+  return ids.length ? ["--seen", ids.join(",")] : [];
+}

package/hooks/trigger.mjs

@@ -3,18 +3,34 @@
  * clock, no client specifics. The hook feeds it one stop's observations and
  * it returns the updated state + a fire decision.
  *
- * FROZEN SPEC (2026-07-15, replay + wave-lab validated; 2026-07-21 descent/synthesis update):
+ * FROZEN SPEC (2026-07-15, replay + wave-lab validated; 2026-07-21 descent/synthesis update;
+ *              2026-07-24 "option C" — see the REGRESSION note below):
  *   score  = uncaptured contentRead files ×1
  *          + settled edited files       ×2   (settled = 3 active stops w/o re-edit)
- *          + active stops since last fire     (new files or edits only; synthesis no longer counts as active)
+ *          + ALL stops since last fire        (every stop is engagement; see below)
  *     fresh-noted files contribute NOTHING — genuinely new knowledge drives firing.
- *   arm    at score ≥ T(10), requiring ≥2 active stops AND ≥2 uncaptured files.
+ *   arm    at score ≥ T(10), requiring ≥1 active stop AND ≥1 uncaptured file.
  *   fire   armed + descent (1 quiet stop)               → non-blocking (inject)
- *          score ≥ CAP(20)                              → non-blocking (backlog
+ *          score ≥ CAP(20), ≥2 uncaptured files         → non-blocking (backlog
  *            rescue — replay showed dense sessions starve descent and hit cap
  *            repeatedly; blocking each cap re-created the v4 agitation)
  *          .git/HEAD drift, ≥2 uncaptured files         → BLOCKING (instant —
  *            the one boundary where waiting for a next prompt loses the moment)
+ *
+ * REGRESSION FIXED 2026-07-24 (why the stop term is ALL stops, not active ones):
+ *   The 2026-07-21 change made synthesis turns count as QUIET so they could feed
+ *   descent. Correct for descent — but the score's stop term read `activeStops`,
+ *   so the same edit silently DELETED the only score-growth term a discussion
+ *   session has. Measured consequence: descent fired ZERO times in this repo's
+ *   entire history (104 stops / 24 fires — all head-drift or cap). A session that
+ *   reads 3 files then discusses them for 8 turns sat at score 4 forever.
+ *   The two questions are now asked of different counters, which is the point:
+ *     "has enough happened?"  → score, counting EVERY stop (engagement)
+ *     "has it wound down?"    → quietRun, counting only non-active stops
+ *   The ≥2-active-stops arming gate went with it: a discussion session bursts its
+ *   file reads in ONE stop, so that gate alone would have kept the fix inert.
+ *   Blocking paths (head-drift) keep MIN_FILES=2 — relaxing those to 1 re-creates
+ *   the v4 single-file agitation this design exists to kill.
  *   NEVER: first-stop fire, wall-clock, gap/resume, conversation classification.
  *   (surge removed 2026-07-21: with descent=1 a quiet stop fires descent before
  *    surge could ever apply — the two were redundant. cap + head-drift remain the
@@ -27,15 +43,27 @@
 
 export const T_ARM = 10;
 export const T_CAP = 20;
+/** Files a single fire CLAIMS (marks captured) and lists — the same cap the
+ *  worklist prompt renders (elicit-core slices its display to it). Files beyond
+ *  it stay UNCAPTURED so they roll into the NEXT fire's worklist, rather than
+ *  being marked done but never shown — which silently dropped notes on sessions
+ *  that touched more than this many files (a long autonomous grind). */
+export const MAX_CAPTURE_FILES = 30;
 export const SETTLE_ACTIVE_STOPS = 3;
 export const DESCENT_QUIET = 1;
+/** Uncaptured-file floor for the BLOCKING/backlog paths (head-drift, cap).
+ *  Stays at 2 deliberately: a one-file blocking prompt is the v4 agitation. */
 export const MIN_FILES = 2;
+/** Floor for the non-blocking paths (arm → descent). One real file is enough to
+ *  be worth a note, and descent only ever injects. */
+export const MIN_FILES_ARM = 1;
 
 export function initialState() {
   return {
     v: 2,
     stop: 0,            // stops processed
-    activeStops: 0,     // ACTIVE stops since last fire
+    activeStops: 0,     // ACTIVE stops since last fire (settle clock + arming floor)
+    stopsSinceFire: 0,  // ALL stops since last fire (score's engagement term)
     quietRun: 0,        // consecutive quiet stops
     armed: false,
     fires: 0,
@@ -99,6 +127,9 @@ export function step(state, obs) {
   // so it counts as quiet, not active.
   const active = newFiles > 0 || editsThisStop > 0;
   if (active) { s.activeStops++; s.quietRun = 0; } else { s.quietRun++; }
+  // Engagement, counted separately from "work happened". `|| 0` tolerates
+  // markers written before this field existed (a live session mid-upgrade).
+  s.stopsSinceFire = (s.stopsSinceFire || 0) + 1;
   for (const f of Object.values(s.files)) {
     if (f.lastEditActive === -2) f.lastEditActive = s.activeStops; // edit stamped at current active count
   }
@@ -109,10 +140,10 @@ export function step(state, obs) {
   const settledEdits = uncaptured.filter(([, f]) =>
     f.edits > 0 && f.lastEditActive >= 0 && s.activeStops - f.lastEditActive >= SETTLE_ACTIVE_STOPS,
   ).length;
-  const score = readPts + settledEdits * 2 + s.activeStops;
+  const score = readPts + settledEdits * 2 + s.stopsSinceFire;
 
   // ---- arm / fire ----------------------------------------------------------------
-  if (!s.armed && score >= T_ARM && s.activeStops >= 2 && uncaptured.length >= MIN_FILES) {
+  if (!s.armed && score >= T_ARM && s.activeStops >= 1 && uncaptured.length >= MIN_FILES_ARM) {
     s.armed = true;
   }
 
@@ -127,13 +158,18 @@ export function step(state, obs) {
 
   let decision = null;
   if (fire) {
-    // worklist = the uncaptured set, most-worked first (edits, then retouches)
-    const files = uncaptured
+    // worklist = the uncaptured set, most-worked first (edits, then retouches),
+    // capped to what one fire claims. Mark ONLY the listed files captured; the
+    // overflow stays uncaptured and rolls into the next fire (which re-fires
+    // soon, since the backlog keeps the score high).
+    const ranked = uncaptured
       .sort((a, b) => (b[1].edits - a[1].edits) || (b[1].retouches - a[1].retouches) || (b[1].reads - a[1].reads))
-      .map(([rel]) => rel);
-    for (const [, f] of uncaptured) f.captured = true;
+      .slice(0, MAX_CAPTURE_FILES);
+    const files = ranked.map(([rel]) => rel);
+    for (const [, f] of ranked) f.captured = true;
     s.armed = false;
     s.activeStops = 0;
+    s.stopsSinceFire = 0;
     s.quietRun = 0;
     s.fires++;
     decision = { ...fire, files, score };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cstart/coldstart",
-  "version": "2.2.7",
+  "version": "2.2.9",
   "mcpName": "io.github.AkashGoenka/coldstart",
   "publishConfig": {
     "access": "public"
@@ -39,10 +39,11 @@
     "tree-sitter"
   ],
   "license": "MIT",
+  "author": "Akash Goenka (https://github.com/AkashGoenka)",
   "homepage": "https://akashgoenka.github.io/coldstart/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AkashGoenka/coldstart"
+    "url": "git+https://github.com/AkashGoenka/coldstart.git"
   },
   "bugs": {
     "url": "https://github.com/AkashGoenka/coldstart/issues"
@@ -54,7 +55,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "latest",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@vscode/ripgrep": "^1.18.0",
     "web-tree-sitter": "^0.26.10"
   },