@cstart/coldstart 2.2.6 → 2.2.8

package/hooks/capture-payload.mjs

@@ -127,25 +127,27 @@ agent; there is no "next".
 11. Never copy secret VALUES (env contents, tokens, keys) into a note — notes are committed \
 to git.
 
-FLOWS — rare. While investigating you will see flows everywhere: every file connects to \
-something, every feature has a chain. Those connections are not flow notes — at that rate, \
-everything would be a flow.
-A flow note records PRODUCT-level knowledge: how the system behaves as a whole, knowledge no \
-single file owns. The test, for every candidate: is this about how the CODEBASE works, or \
-about how one file works? File-level → it belongs in that file's note. Product-level → flow.
-Examples that can qualify:
+FLOWS — the product-level layer. A flow note records knowledge no single file owns: how the \
+system behaves as a whole. The test, for every candidate: is this about how the CODEBASE \
+works, or about how one file works? File-level → it belongs in that file's note. \
+Product-level → flow.
+Examples that qualify:
 - how authentication works end-to-end
 - how UI components get rendered under different conditions
 - how a file is consumed along a path when its imports don't reveal it and the gotcha spans \
 the path (a single non-obvious consumer is NOT a flow — it goes in that file's own note, rule 6)
 The summary's FIRST sentence states the product-level fact — the thing a reader of all the \
-file notes would still be missing.
+file notes would still be missing. If you cannot write that sentence, there is no flow.
 Steps are the minimal chain, each with its role. kb write WARNS when fewer than two steps \
 are files you read this session — a flow assembled from grep hits is the classic bad flow; \
 take that warning seriously.
 Never a flow: a feature's parts-list, a relationship the import graph already shows, a \
 mechanism living in one file.
-kb search first — update the existing flow, never a near-duplicate.
+kb search first. UPDATE an existing flow only when your missing-fact sentence is THE SAME \
+fact it already leads with — new detail about a mechanism it already tells. A DIFFERENT \
+missing fact is a NEW flow, even in the same subsystem, even across the same files. Folding \
+an unrelated fact into a nearby flow buries it: nobody searching for your fact will find that \
+title.
 
 WRITE — one Bash block total: specs as heredocs, writes chained with &&.
   {"type":"file-single","path":"src/x.py","summary":"1-3 sentences","aliases":["symptom words"]}
@@ -156,5 +158,11 @@ with several of its symbols. file-hub is ONLY for grab-bag files that have no si
 not make a file a hub; having no one purpose does.
   Update = the same spec plus "id":"<id from the worklist>".
   node ${cli} kb write /tmp/spec1.json --root ${root} --session ${sid} --force
-  Flow/lesson shapes: run \`node ${cli} kb write --root ${root}\` with no spec — it prints the full guide.${tail}`;
+  Flow/lesson shapes: run \`node ${cli} kb write --root ${root}\` with no spec — it prints the full guide.
+
+FLOW DECISION — run this EVERY time, as its own command. It stands apart from the WRITE block \
+above: run it even when you decided no note was warranted and emitted no Bash block at all. It \
+records only what you decided about FLOWS (created a new one, folded into an existing one, or \
+none) so the flow gate can be measured.
+  node ${cli} kb flow-decision --decision <none|new|update> [--id <flow id>] --why "<one clause>" --root ${root} --session ${sid}${tail}`;
 }

package/hooks/kb-elicit.mjs

@@ -29,7 +29,7 @@
  */
 
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync, writeFileSync, appendFileSync, readFileSync, readdirSync, statSync } from "node:fs";
 
@@ -51,6 +51,31 @@ function log(msg) {
   try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] elicit: ${msg}\n`); } catch { /* never fail logging */ }
 }
 
+// --- Repo-root resolution ----------------------------------------------------
+/**
+ * The Stop payload's `cwd` tracks the session's shell, which a `cd` inside a
+ * Bash call moves — sometimes clean OUT of the repo (e.g. into ~/.claude/…/memory
+ * to edit private files). Root was taken raw from that cwd, so normRel would then
+ * strip the WRONG prefix and admit a foreign absolute path into the worklist as if
+ * it were repo-local (observed 2026-07-25: MEMORY.md / drive.mjs entered a marker).
+ * A notebook-inited repo carries a `.coldstart/notebook/` dir, so walk up from cwd
+ * to the nearest ancestor that has one — that is the true root regardless of shell
+ * drift. `.coldstart/notebook` (not bare `.coldstart`) is the marker on purpose: the
+ * GLOBAL `~/.coldstart` dir holds daemon/searcher state and no notebook, so a drift
+ * into ~ must not resolve to the home directory.
+ * Returns "" when cwd is not inside any notebook-inited repo.
+ */
+function findRepoRoot(startDir) {
+  let dir = resolve(startDir || ".");
+  for (let i = 0; i < 40; i++) {
+    if (existsSync(join(dir, ".coldstart", "notebook"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "";
+}
+
 // --- Subagent transcript resolution ------------------------------------------
 /**
  * Resolve a subagent's transcript, supporting both flat and nested layouts.
@@ -108,7 +133,13 @@ process.on("unhandledRejection", (e) => { log(`unhandled ${e?.stack || e}`); pro
 // session: the freshest marker in tmpdir whose recorded (relative) files still
 // resolve under <root> is this repo's active session. We then emit the SAME
 // capture payload an automatic fire would, built from accumulated evidence.
-// READ-ONLY — never mutates the marker, so it cannot perturb automatic firing.
+//
+// It marks the files it LISTED as captured (and nothing else). Without that, a
+// manual capture left every file uncaptured, so the next automatic fire re-asked
+// for notes on the exact same worklist the user had just written up. The trigger's
+// own timing counters (armed / activeStops / stopsSinceFire / quietRun) are left
+// untouched, which is what preserves the real guarantee: an on-demand capture
+// cannot change WHEN automatic capture fires, only what is still outstanding.
 function argValue(name) {
   const i = process.argv.indexOf(name);
   return i >= 0 ? process.argv[i + 1] : undefined;
@@ -129,7 +160,7 @@ function freshestMarkerUnderRoot(root) {
     if (!files.length) continue;
     // Belongs to THIS repo iff a recorded file still resolves under root.
     if (files.some((rel) => existsSync(join(root, rel)))) {
-      return { sid: m.n.slice("coldstart-kb-".length, -"-main.json".length), state };
+      return { sid: m.n.slice("coldstart-kb-".length, -"-main.json".length), state, path: m.p };
     }
   }
   return null;
@@ -148,7 +179,7 @@ if (process.argv.includes("--manual")) {
       log(`MANUAL no-marker root=${root}`);
       process.exit(0);
     }
-    const { sid, state } = found;
+    const { sid, state, path: markerPath } = found;
     const files = Object.keys(state.files).filter((rel) => !state.files[rel].captured);
     if (!files.length) {
       process.stdout.write("Everything worked on so far is already captured — nothing new to write right now.\n");
@@ -157,6 +188,17 @@ if (process.argv.includes("--manual")) {
     }
     const entries = worklistEntries(CLI, root, files, state.files, log);
     const payload = buildCapturePayload({ root, cli: CLI, sid, entries, envelope: "manual" });
+    // Mark ONLY the listed files captured. Re-read first: a Stop hook may have
+    // written the marker since we loaded it, and we must not clobber its
+    // counters. Best-effort — a failure here costs a duplicate ask, never the
+    // payload the user asked for.
+    try {
+      const live = JSON.parse(readFileSync(markerPath, "utf8"));
+      if (live && live.files) {
+        for (const rel of files) if (live.files[rel]) live.files[rel].captured = true;
+        writeFileSync(markerPath, JSON.stringify(live));
+      }
+    } catch (e) { log(`MANUAL mark-captured skipped ${e}`); }
     logCaptureEvent(root, { event: "fire", reason: "manual", session: sid, files: files.length });
     log(`FIRE manual session=${sid} files=${files.length}`);
     process.stdout.write(payload + "\n");
@@ -176,8 +218,8 @@ if (process.argv.includes("--manual")) {
   } catch (e) { log(`bad stdin ${e}`); }
 
   try {
-    const root = String(input.cwd || "");
-    setLogRoot(root);
+    const cwd = String(input.cwd || "");
+    setLogRoot(cwd);
 
     // Guard 1: already inside a hook-induced continuation → let it stop.
     if (input.stop_hook_active === true) { log("SKIP stop_hook_active"); process.exit(0); }
@@ -212,7 +254,6 @@ if (process.argv.includes("--manual")) {
     }
     if (!transcriptPath || !existsSync(transcriptPath)) { log("SKIP no-transcript"); process.exit(0); }
 
-    const ignore = loadIgnore(root);
     const marker = join(tmpdir(), `coldstart-kb-${sid}-${aid}.json`);
     let state = null;
     try {
@@ -222,6 +263,15 @@ if (process.argv.includes("--manual")) {
     const freshMarker = !state; // no valid prior marker: we're attaching, not resuming our own place
     if (!state) state = initialState();
 
+    // Freeze the repo root in the marker: derive it once (walk-up from cwd), then
+    // reuse the stored value on every later stop so a mid-session `cd` out of the
+    // repo can never re-point root at a foreign tree. Fall back to the raw cwd only
+    // when neither a stored root nor a `.coldstart` ancestor exists.
+    const root = (typeof state.root === "string" && state.root) ? state.root : (findRepoRoot(cwd) || cwd);
+    state.root = root;
+    setLogRoot(root);
+    const ignore = loadIgnore(root);
+
     // This stop's transcript slice (everything since the last processed line).
     const text = readFileSync(transcriptPath, "utf8");
     const lines = text.split("\n");

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
@@ -29,13 +45,19 @@ export const T_ARM = 10;
 export const T_CAP = 20;
 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 +121,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 +134,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;
   }
 
@@ -134,6 +159,7 @@ export function step(state, obs) {
     for (const [, f] of uncaptured) 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.6",
+  "version": "2.2.8",
   "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"
   },