skalpel 4.0.34 → 4.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.34",
+  "version": "4.0.35",
   "description": "Behavioral graph for AI-assisted coding — learns how you work and steers Claude Code + Codex in real time.",
   "type": "module",
   "bin": {

package/skalpel-hook.mjs

@@ -146,6 +146,43 @@ function writePending(obj) {
   }
 }
 
+// ALWAYS-ON PRESENCE tally — the honest lifetime record the statusline reads for its baseline line.
+// Concept is Raahil's (#609): steers = count of steers ACTUALLY applied (fired AND not suppressed) across
+// all sessions; saved_min = Σ, over those applied steers, of the user's OWN median cost of one loop of
+// that steer's work-type (the server's `median_loop_min`, from the causal graph's sink/loop stats). It is
+// NEVER a server wall-clock estimate; when the server has no median (null) we credit NOTHING.
+//
+// RACE-FREE by construction (audit Finding 2 — a read-modify-write single-counter loses increments under
+// concurrent hook double-fires; metrics.mjs's own comment warns the same). So this is an APPEND-ONLY log:
+// ONE atomic `appendFileSync` line per applied steer. POSIX guarantees a single small append is atomic, so
+// N concurrent applied-steer writes yield exactly N lines (0 loss). No read, no tmp, no rename, no mutated
+// counter. Same idiom as metrics.ndjson / insights.ndjson.
+//
+// ── STEERS SOURCE CONTRACT (the source of truth for the statusline baseline AND #620's analytics TUI) ──
+//   file  : ~/.skalpel/steers.ndjson   (append-only; one line per APPLIED steer; never rewritten/trimmed)
+//   line  : {"ts": <epoch ms>, "saved_min_delta": <number ≥ 0>}
+//             ts              = Date.now() when the steer was applied.
+//             saved_min_delta = the median_loop_min credited for THIS steer (≥ 0; 0 when the server sent
+//                               no positive median — never fabricated).
+//   derive: steers    = count of valid JSON lines (one line == one applied steer).
+//           saved_min = Σ saved_min_delta over valid lines (round to 1 dp; garbage/partial lines skipped).
+//   Readers MUST fail open (unreadable/absent → {steers:0, saved_min:0}) and MUST NOT mutate this file.
+const STATE_LOG_PATH = join(homedir(), ".skalpel", "steers.ndjson");
+function bumpState(medianMin) {
+  try {
+    // credit ONLY a real, positive median from the server; null/NaN/<=0 → 0 credit (no fabrication).
+    const savedMinDelta = Number.isFinite(medianMin) && medianMin > 0 ? medianMin : 0;
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    // ONE atomic append == ONE applied steer. Race-free (never a read-modify-write of a counter).
+    appendFileSync(
+      STATE_LOG_PATH,
+      JSON.stringify({ ts: Date.now(), saved_min_delta: savedMinDelta }) + "\n",
+    );
+  } catch {
+    /* the presence tally is a bonus; never block the hook */
+  }
+}
+
 // STEER label — the statusline reads this so the user SEES skalpel steering LIVE, every turn a steer
 // injects, INDEPENDENT of whether the model surfaces a 🔬 line (the deterministic awareness channel).
 // A one-glance 2-word label derived from the top injected steer type. Overwritten each turn.
@@ -559,6 +596,7 @@ async function main() {
   let steerType = null; // raw top-steer type (TELL/SINK/…) — for the feedback loop + session log
   let steerWt = null; // the work-type the steer is about (refine/debug/…)
   let brokeOut = false; // behavioral-only: did expected-waste-ahead drop after last turn's steer (adherence)
+  let medianLoopMin = null; // server's per-work-type median loop cost (min) — the ONLY input to "saved"
 
   if (!authNote) {
     const remaining = deadline - Date.now();
@@ -596,6 +634,14 @@ async function main() {
         steerLabel = j?.steer_label; // surfaced on the statusline (written once below, with any credit)
         steerType = j?.steer_type || null;
         steerWt = j?.steer_wt || (j?.entry ? String(j.entry).split("/")[0] : null);
+        // the user's OWN median cost of one loop of this steer's work-type (from the graph's sink stats).
+        // The ONLY quantity we ever turn into "saved" minutes, and only for an APPLIED steer (below).
+        medianLoopMin =
+          typeof j?.median_loop_min === "number" &&
+          isFinite(j.median_loop_min) &&
+          j.median_loop_min > 0
+            ? j.median_loop_min
+            : null;
         if (j?.entry) pushTraj(String(j.entry).split("/")[0]); // remember this turn's work-type
         dbg(`  -> sim=${j?.top_sim ?? "?"} ${injection ? "INJECT" : "silent"}`);
 
@@ -693,6 +739,9 @@ async function main() {
   const steerId = injection ? String(Date.now()) : null;
   writeSteer(steerLabel, steerType, steerWt, steerId);
   if (injection) logSessionEvent({ type: steerType, wt: steerWt }); // feed the end-of-session recap
+  // ALWAYS-ON presence tally: a steer was APPLIED this turn (fired + survived suppression). Count it,
+  // and credit its honest median-loop cost ONLY when the server sent a real number (null -> +0).
+  if (injection) bumpState(medianLoopMin);
 
   // LOCAL INSIGHT RECORDS (~/.skalpel/insights.ndjson) — one plain-English row per note kind that
   // fired this turn, post-suppression (a muted/suppressed steer writes nothing). recordInsight

package/skalpel-statusline.mjs

@@ -1,12 +1,31 @@
 #!/usr/bin/env node
-// skalpel statusline — COUNT-OR-NOTHING. Prints ONLY facts that reproduce from local state, never an
-// estimate dressed up as a measurement. There is no "~Xh saved" and no "+min this turn": those were a
-// SERVER estimate of expected-waste (never a measured clock), so they are gone. What can honestly show:
+// skalpel statusline — HONEST-OR-NOTHING. Prints only facts grounded in local state, never a server
+// estimate dressed up as a measurement. In priority order (highest first):
+//   • the AHA CATCH reveal — agent claimed done, its OWN proof re-run GENUINELY failed (opt-in,
+//     SKALPEL_VERIFY_REVEAL; dark by default → byte-identical to the always-on baseline when off); else
+//   • the green "✓ verified" stamp — that same proof re-run really PASSED (same opt-in flag); else
 //   • the live re-ask/interrupt COUNT for THIS session, read straight from the transcript Claude Code
 //     hands us on stdin — the exact material `skalpel autopsy` re-derives from disk, a count of things
-//     that verifiably happened, or
-//   • the current steer's plain-English label (what skalpel is doing now) — a description, not a number.
-// A clean session prints NOTHING. Fail-open: any error → print nothing, exit 0. Never blocks the bar.
+//     that verifiably happened; else
+//   • the current steer's plain-English label (what skalpel is doing now) — a description, not a number;
+//     else
+//   • the ALWAYS-ON presence line, "skalpel · N steers[ · <time clause>]".
+//     N = steers ACTUALLY applied (fired + not suppressed), counted from the append-only
+//     ~/.skalpel/steers.ndjson — a fresh install reads "0 steers", present, never blank. The optional
+//     TIME clause is chosen by BASELINE_TIME_MODE (Ryan flips one constant):
+//       · <Xm> caught — the CUMULATIVE LIFETIME sum of every real MEASURED red→green delta (each caught
+//         false "done" and the moment that SAME proof, that SAME session, was later logged PASS — real
+//         timestamps; reuses ledger.mjs's measureFixDelta logic). ALWAYS-ON once real catches exist (it is
+//         skalpel's terminal presence — never gated/hidden). A measured total, NEVER an estimate; a catch
+//         with no later PASS adds 0. Cumulative framing (not present-tense) keeps it honest for old data.
+//       · ~Xm saved — Raahil's #609 estimate: (applied steers) × (the user's OWN median loop cost from
+//         their causal graph). A `~`-prefixed ESTIMATE grounded in their own data, shown only when
+//         saved_min > 0. Never a server wall-clock number; never "skalpel saved you X" as a fact.
+// Every value here is a real count or a real measured timestamp delta (or a clearly `~`-marked estimate).
+// NOTE: this always-on presence line is a DELIBERATE new behavior — origin/main's clean-idle bar emitted
+// ZERO bytes; this emits "skalpel · 0 steers" (Ryan: always-on presence, non-negotiable). Byte-identical
+// to origin/main is preserved ONLY for the untouched reveal / verdict / re-ask surfaces, not clean-idle.
+// Fail-open: any error → print nothing (or just the presence line), exit 0. Never blocks the bar.
 import { readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -19,16 +38,34 @@ const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
 
+// ── RENDER MODE — the ONE constant Ryan flips. Governs the optional TIME clause on the always-on
+// `skalpel · N steers` baseline. The steers count + Raahil's #609 BOLD/CYAN styling are ALWAYS present,
+// unchanged, in every mode. Nothing else on the bar (reveal / verdict / re-ask / steer label) is affected.
+//   "steers"   → skalpel · N steers
+//   "measured" → skalpel · N steers · 38m caught          (DEFAULT — cumulative lifetime MEASURED red→green)
+//   "saved"    → skalpel · N steers · ~7m saved           (Raahil's own-graph ESTIMATE, from steers.ndjson)
+//   "both"     → skalpel · N steers · 38m caught · ~7m saved
+const BASELINE_TIME_MODE = "measured";
+const SHOW_MEASURED = BASELINE_TIME_MODE === "measured" || BASELINE_TIME_MODE === "both";
+const SHOW_SAVED = BASELINE_TIME_MODE === "saved" || BASELINE_TIME_MODE === "both";
+
 // AHA CATCH REVEAL — how long a fresh catch stays on the bar before it auto-clears (so it never
 // wallpapers). verify-shadow.mjs writes the reveal the moment a GENUINE_FAIL mismatch is re-run; it also
 // retracts it if a later proof re-run PASSES. This TTL covers the abandoned case (user moved on).
 const REVEAL_TTL_MS = 90_000;
 // LIVE VERDICT green stamp — the earned "✓ verified" written on a clean PASS. DELIBERATELY short-lived:
 // it flashes right after the claim, then recedes so a stream of greens stays ambient (quiet trust) and
-// never competes with the loud red catch. Short TTL is the whole point — a green that lingers is clutter;
-// a green that blinks by, turn after turn, is what makes the rare red land like a thunderclap.
+// never competes with the loud red catch. Short TTL is the whole point — a green that lingers is clutter.
 const VERDICT_TTL_MS = 20_000;
 
+// The verify-shadow log the measured clause reads. Defined LOCALLY (not imported from verify-shadow.mjs)
+// on purpose: this runs on EVERY bar render, so it must not pull that module's heavy (child_process /
+// probe) import graph onto the hot path — it only READS the file verify-shadow.mjs owns. verify-shadow.mjs
+// self-trims the log to ~1MB/500 lines, so this bounded tail reads the whole retained log in practice
+// while staying safe against a pathological huge file (a bounded read can only UNDERCOUNT, never overstate).
+const VERIFY_LOG_PATH = join(homedir(), ".skalpel", "verify-shadow.log");
+const SHADOW_READ_BYTES = 1024 * 1024;
+
 // Claude Code pipes a JSON status payload on stdin (transcript_path, session_id, …). Read it ONLY when
 // stdin is actually piped — never block on a TTY (manual invocation) where reading fd 0 would hang.
 function readPayload() {
@@ -101,7 +138,7 @@ function steerLabel() {
 // The opt-in AHA CATCH: read the reveal state file verify-shadow.mjs wrote. Returns the plain reveal
 // line (fresh + honest — the statusline never invents it, it only renders what the re-run recorded) or
 // null. Auto-clears when stale (past the TTL) so an old catch can't wallpaper the bar. GATED entirely on
-// SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the original.
+// SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the baseline.
 function revealNote() {
   try {
     const r = JSON.parse(readFileSync(REVEAL_PATH, "utf8"));
@@ -125,7 +162,7 @@ function revealNote() {
 // The LIVE VERDICT green stamp: read the verdict state verify-shadow.mjs wrote on a clean PASS. Returns
 // the plain "✓ verified" line (fresh + honest — the statusline never invents it, it only renders what the
 // re-run recorded) or null. Auto-clears past its short TTL so a stale green never lingers. GATED entirely
-// on SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the original.
+// on SKALPEL_VERIFY_REVEAL: when off, this is never called and the bar is byte-identical to the baseline.
 function verdictNote() {
   try {
     const r = JSON.parse(readFileSync(VERDICT_PATH, "utf8"));
@@ -146,21 +183,148 @@ function verdictNote() {
   }
 }
 
-async function main() {
+// The always-on presence tally — derived from ~/.skalpel/steers.ndjson, the APPEND-ONLY log the hook
+// writes (one atomic line per APPLIED steer; see the STEERS SOURCE CONTRACT in skalpel-hook.mjs). This is
+// the RACE-FREE replacement for the old mutated state.json counter (audit Finding 2): steers = the count
+// of valid lines, saved_min = Σ saved_min_delta. Defaults to zeros so the baseline line is never blank;
+// garbage/partial lines are skipped; the sum only ever adds ≥0 deltas, so it is honest and never negative.
+function readState() {
+  try {
+    const raw = readFileSync(join(homedir(), ".skalpel", "steers.ndjson"), "utf8");
+    let steers = 0;
+    let savedMin = 0;
+    for (const line of raw.split("\n")) {
+      const l = line.trim();
+      if (!l) continue;
+      let rec;
+      try {
+        rec = JSON.parse(l);
+      } catch {
+        continue; // a partial/garbage line — skip it (fail-open), keep counting the rest
+      }
+      if (!rec || typeof rec !== "object") continue;
+      steers += 1; // one valid line == one applied steer (append-only ⇒ exact, race-free count)
+      if (Number.isFinite(rec.saved_min_delta) && rec.saved_min_delta > 0)
+        savedMin += rec.saved_min_delta;
+    }
+    return { steers, savedMin: Math.round(savedMin * 10) / 10 };
+  } catch {
+    return { steers: 0, savedMin: 0 }; // absent/unreadable → honest zero-state (fail-open)
+  }
+}
+
+// The `~`-prefixed saved ESTIMATE, or null when there's no real credit (never show a fake/zero number).
+// Minutes below an hour render as ~Xm; an hour or more as ~Xh (one decimal, trimmed of a trailing .0).
+// [Raahil #609 — preserved verbatim so the "saved"/"both" modes match his line byte-for-byte.]
+function savedPhrase(min) {
+  if (!(min > 0)) return null;
+  if (min >= 60) {
+    const h = min / 60;
+    const s = h >= 10 ? String(Math.round(h)) : h.toFixed(1).replace(/\.0$/, "");
+    return `~${s}h saved`;
+  }
+  return `~${Math.round(min)}m saved`;
+}
+
+// ── MEASURED red→green delta (real timestamps only — the honest replacement for the banned "~Xh saved").
+// tsMs + measureFixDelta are the EXACT logic from ledger.mjs, replicated here (not imported) so the hot
+// statusline path never pulls verify-shadow.mjs's heavy graph. Parse an ISO ts to epoch ms, or null.
+function tsMs(ts) {
+  if (typeof ts !== "string") return null;
+  const n = Date.parse(ts);
+  return Number.isFinite(n) ? n : null;
+}
+
+// measureFixDelta(falseRow, rows) → { ms, atTs } for the EARLIEST later row that is, in the SAME session,
+// the SAME proof_command, and a genuine PASS whose timestamp is strictly after the caught-false claim.
+// That is the real moment the false "done" became a true "done": the exact proof that failed later passed.
+// Returns null when no such row exists (then we show NO time — never an invented minute). [ledger.mjs]
+function measureFixDelta(falseRow, rows) {
+  const t0 = tsMs(falseRow.ts);
+  if (t0 == null) return null;
+  const session = falseRow.session ?? null;
+  // Finding 3: a REAL session id is required to tie a fix to a claim. With a null session, the
+  // `(r.session ?? null) !== session` guard below would treat every OTHER null-session row as
+  // "same session" and cross-attribute a bogus delta — so refuse to measure when session is null.
+  if (session == null) return null;
+  const proof = falseRow.proof_command || null;
+  if (!proof) return null; // can't tie a fix to a claim with no proof — count only
+  let best = null;
+  for (const r of rows) {
+    if (r === falseRow) continue;
+    if ((r.session ?? null) !== session) continue;
+    if ((r.proof_command || null) !== proof) continue;
+    if (r.outcome !== "PASS") continue; // the SAME proof genuinely passing = the real done
+    const t1 = tsMs(r.ts);
+    if (t1 == null || t1 <= t0) continue; // must be strictly LATER than the false claim
+    if (best == null || t1 < best) best = t1;
+  }
+  return best == null ? null : { ms: best - t0, atTs: new Date(best).toISOString() };
+}
+
+// Compact one-line duration for the bar. Input is a real (t_pass − t_false) MEASURED delta; this only
+// formats it. FLOORS every unit so it can never round UP into a number larger than the real measurement.
+// Sub-second deltas → null (nothing worth a clause). Seconds < 1m; whole minutes < 1h; else hours.
+function compactMeasured(ms) {
+  if (!Number.isFinite(ms) || ms < 1000) return null;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = s / 3600;
+  return h >= 10
+    ? `${Math.floor(h)}h`
+    : `${(Math.floor(h * 10) / 10).toFixed(1).replace(/\.0$/, "")}h`;
+}
+
+// measuredCaughtTotalMs() → the CUMULATIVE LIFETIME sum, in ms, of EVERY real measured red→green delta:
+// each caught false "done" (mismatch row) that has a later same-session same-proof PASS contributes that
+// one measured (t_pass − t_false) delta; a catch with no later PASS contributes 0 (never estimated). This
+// is an AGGREGATE — only the total number is ever rendered, never any per-catch claim text or proof (those
+// stay in the opt-in reveal + the analytics TUI). Framed on the bar as a cumulative "Xm caught", NOT a
+// present-tense "just caught", so it stays honest for old catches — the TOTAL genuinely happened.
+//
+// This always-on aggregate counter is an EXPLICIT PRODUCT DECISION by the owner: it is skalpel's terminal
+// presence and must never be gated/hidden ("never remove it from the terminal otherwise skalpel is
+// invisible"). Aggregate-only + no fabrication is what keeps that always-on surface honest.
+function measuredCaughtTotalMs() {
+  try {
+    const lines = tailLines(VERIFY_LOG_PATH, SHADOW_READ_BYTES);
+    if (!lines.length) return 0;
+    const rows = [];
+    for (const l of lines) {
+      try {
+        const r = JSON.parse(l);
+        if (r && typeof r === "object") rows.push(r);
+      } catch {
+        /* partial / garbage line — skip it, keep the rest (fail-open) */
+      }
+    }
+    let total = 0;
+    for (const r of rows) {
+      if (r.mismatch !== true) continue; // only a caught false "done" (verify-shadow's money metric)
+      const d = measureFixDelta(r, rows); // exact ledger.mjs logic; null-session rows excluded (Finding 3)
+      if (d && Number.isFinite(d.ms) && d.ms > 0) total += d.ms; // real measured delta only; else +0
+    }
+    return total;
+  } catch {
+    return 0; // any error → no measured total (fail-open: never break or slow the bar)
+  }
+}
+
+function main() {
   const payload = readPayload();
 
-  // AHA CATCH REVEAL (opt-in). The single highest-priority line: the agent claimed done but its OWN proof,
-  // re-run, GENUINELY failed. Fully gated on SKALPEL_VERIFY_REVEAL — when off, this branch never runs and
-  // the statusline output is byte-identical to the count-or-nothing original.
+  // AHA CATCH REVEAL / green ✓ verified (opt-in). The highest-priority surfaces: the agent claimed done
+  // and its OWN proof, re-run, GENUINELY failed (red) — or really passed (green). Fully gated on
+  // SKALPEL_VERIFY_REVEAL — when off (the default) this branch never runs and the bar is byte-identical to
+  // the always-on baseline below.
   if (revealEnabled(process.env)) {
     const reveal = revealNote();
     if (reveal) {
       process.stdout.write(`${BOLD}${reveal}${RESET}`);
       return;
     }
-    // No red catch pending → the quiet green half. A fresh PASS stamp shows dim (ambient, not shouting)
-    // for a short beat. Lower priority than the red catch, higher than the re-ask count: it's the most
-    // recent verdict on the last claim, and it's what earns the trust the red catch spends.
     const verdict = verdictNote();
     if (verdict) {
       process.stdout.write(`${DIM}${GREEN}${verdict}${RESET}`);
@@ -178,17 +342,40 @@ async function main() {
     return;
   }
 
-  // Otherwise, if a steer is live, name what it's doing — a description, no number. Else: print NOTHING.
+  // Otherwise, if a steer is live, name what it's doing — a description, no number.
   const label = steerLabel();
   if (label) {
     process.stdout.write(`${BOLD}skalpel${RESET} · ${CYAN}${label}${RESET}`);
     return;
   }
-  // Clean session → COUNT-OR-NOTHING resolves to nothing. Emit no bytes.
+
+  // ALWAYS-ON baseline presence line — skalpel's terminal presence (owner product decision: never gated,
+  // never hidden). `N steers` is ALWAYS shown (fresh install reads "0 steers" — honest, present, never
+  // blank; the user's own applied-steer count). Then the ONE optional time clause selected by
+  // BASELINE_TIME_MODE, each an AGGREGATE number only (never per-catch claim text / proof — those live in
+  // the opt-in reveal + the TUI), shown only when its real value exists:
+  //   • MEASURED "· Xm caught" — the CUMULATIVE LIFETIME sum of every real measured red→green delta
+  //     (measuredCaughtTotalMs). Always-on once real catches exist; a MEASURED wall-clock, never an
+  //     estimate. Cumulative framing (not present-tense "just caught"), so it stays honest for old catches.
+  //   • Raahil's `~`-prefixed saved ESTIMATE ("· ~7m saved") — shown only when saved_min > 0 (its data is
+  //     the user's own steers.ndjson credit, not the shadow log, so it keeps his always-on #609 behavior).
+  const { steers, savedMin } = readState();
+  let line = `${BOLD}skalpel${RESET} · ${CYAN}${steers} steers${RESET}`;
+  if (SHOW_MEASURED) {
+    const caught = compactMeasured(measuredCaughtTotalMs()); // null when < 1s of real measured catches
+    if (caught) line += ` · ${CYAN}${caught} caught${RESET}`;
+  }
+  if (SHOW_SAVED) {
+    const phrase = savedPhrase(savedMin);
+    if (phrase) line += ` · ${CYAN}${phrase}${RESET}`;
+  }
+  process.stdout.write(line);
 }
 
-// Fail-open, matching the other three hooks (skalpel-hook / -session / -session-end): any error →
-// print nothing → exit 0, so a thrown error can never spill a stack trace into the live status bar.
-main()
-  .then(() => process.exit(0))
-  .catch(() => process.exit(0));
+// Fail-open: wrap the whole render so a thrown error can never spill a stack trace into the live status
+// bar. Every helper is already individually try/caught; this is the last-line guard. Exit 0 regardless.
+try {
+  main();
+} catch {
+  /* never let the statusline break or slow the bar */
+}