skalpel 4.0.20 → 4.0.21

package/auth.mjs

@@ -131,11 +131,21 @@ function persistTokens(auth, t) {
   }
 }
 
+// Returns { uid, token } on success. On failure it distinguishes two cases the caller MUST treat
+// differently, via an `expired` flag:
+//   • not signed in yet (no saved session)  -> { uid:null, token:null }            (expired absent/false)
+//   • signed in, but a token REFRESH FAILED -> { uid:null, token:null, expired:true }
+// The hook uses `expired` to surface a visible "session expired — run `skalpel login`" note instead
+// of silently degrading to the anonymous graph (which reads as "skalpel found nothing").
 export async function identity() {
   if (process.env.SKALPEL_USER) return { uid: process.env.SKALPEL_USER, token: null };
 
   const auth = loadCliAuth();
-  if (!auth) return { uid: null, token: null };
+  if (!auth) return { uid: null, token: null }; // genuinely not signed in — stay silent
+
+  // Whether we attempted a refresh and it failed. Only set true on a real refresh failure of a saved
+  // session, never on "no session" — so the caller can tell an expiry apart from a fresh install.
+  let refreshFailed = false;
 
   // Google is the account plane (from `skalpel login`). Send the Google id_token; the server verifies
   // it (aud-pinned) and keys the graph by the verified email. Refresh through AWS (/oauth/refresh) so
@@ -157,7 +167,8 @@ export async function identity() {
           /* never block on persist */
         }
       } else {
-        idt = null; // refresh failed — fall through to the Cognito bridge
+        idt = null; // refresh failed — fall through to the Cognito bridge if one exists
+        refreshFailed = true;
       }
     }
     if (idt) {
@@ -167,17 +178,22 @@ export async function identity() {
   }
 
   // The hosted graph verifies the ACCESS token (Cognito /oauth2/userInfo -> email; an id_token is
-  // rejected there). Send the access token; the server keys the graph by the verified email.
+  // rejected there). Send the access token; the server keys the graph by the verified email. With no
+  // Cognito bridge to fall back on (e.g. a Google-only session whose refresh just failed), the
+  // signed-in session is dead — report the expiry rather than dereferencing a missing `auth.cognito`.
+  if (!auth.cognito || (!auth.cognito.access_token && !auth.cognito.refresh_token)) {
+    return { uid: null, token: null, expired: refreshFailed };
+  }
   let access = auth.cognito.access_token;
   const claims = decodeJwtPayload(access);
   const expiresAt = toEpochSeconds(auth.cognito.expires_at) ?? claims?.exp ?? null;
   if (!access || (expiresAt !== null && expiresAt - Math.floor(Date.now() / 1000) < 60)) {
     const t = await refreshTokens(auth.cognito.refresh_token);
-    if (!t) return { uid: null, token: null };
+    if (!t) return { uid: null, token: null, expired: true }; // signed in, but refresh FAILED
     access = t.access_token;
     persistTokens(auth, t);
   }
 
   const uid = decodeJwtPayload(access)?.sub ?? auth.subject?.user_id ?? null;
-  return uid ? { uid, token: access } : { uid: null, token: null };
+  return uid ? { uid, token: access } : { uid: null, token: null, expired: refreshFailed };
 }

package/bootstrap.mjs

@@ -23,6 +23,7 @@ import { pathToFileURL } from "node:url";
 import { gzipSync } from "node:zlib";
 import { identity } from "./auth.mjs";
 import { recordInsight } from "./insights.mjs";
+import { isGenuineUserTurn } from "./session-turns.mjs";
 
 const DIR = join(homedir(), ".skalpel");
 const STATE_PATH = join(DIR, "bootstrap.json");
@@ -127,7 +128,9 @@ async function userTurnCount(path, cap = MIN_USER_TURNS) {
       } catch {
         continue;
       }
-      if (event?.type === "user" || event?.role === "user") {
+      // Shared genuine-turn test — excludes the tool_result rows Claude Code logs as role:"user",
+      // exactly like skalpel-setup's scanHistory, so both counting paths agree on "found N".
+      if (isGenuineUserTurn(event)) {
         count += 1;
         if (count >= cap) {
           lines.close();
@@ -266,7 +269,8 @@ export function normalizeJobStatus(status = {}) {
   const terminal = status.terminal === true;
   const requiresReplay = status.requires_replay === true;
   const failed = state === "error" || state === "failed" || (terminal && requiresReplay);
-  const complete = state === "done";
+  const isEmpty = state === "empty"; // zero parseable sessions — terminal, honest, NOT a failure
+  const complete = state === "done" || isEmpty;
   return {
     state,
     done,
@@ -277,6 +281,7 @@ export function normalizeJobStatus(status = {}) {
     requiresReplay,
     complete,
     failed,
+    empty: isEmpty,
     sessions: count(status.n_sessions ?? done),
     message: failed
       ? String(

package/install.mjs

@@ -56,6 +56,7 @@ function stageHookRuntime() {
   copyFileSync(join(PKG_DIR, "reveal.mjs"), join(HOOKS_DIR, "reveal.mjs")); // both hooks import ./reveal.mjs
   copyFileSync(join(PKG_DIR, "transcript.mjs"), join(HOOKS_DIR, "transcript.mjs")); // skalpel-hook.mjs + skalpel-statusline.mjs import ./transcript.mjs (tailLines)
   copyFileSync(join(PKG_DIR, "skalpel-hook.mjs"), HOOK_FILE);
+  copyFileSync(join(PKG_DIR, "transcript.mjs"), join(HOOKS_DIR, "transcript.mjs")); // skalpel-hook imports ./transcript.mjs (tailLines)
   copyFileSync(join(PKG_DIR, "skalpel-hook-session.mjs"), SESSION_FILE);
   copyFileSync(join(PKG_DIR, "incremental-ingest.mjs"), join(HOOKS_DIR, "incremental-ingest.mjs"));
   copyFileSync(join(PKG_DIR, "skalpel-hook-session-end.mjs"), SESSION_END_FILE);

package/package.json

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

package/reveal.mjs

@@ -24,7 +24,10 @@ export function graphReadyNote() {
   try {
     writeFileSync(p, JSON.stringify({ ready: false })); // one-shot — clear so it never repeats
   } catch {
-    /* if we can't clear it, better to drop the reveal than repeat it — but proceed once */
+    // Couldn't clear the marker (e.g. a root-owned ~/.skalpel from a past `sudo` install). If we
+    // proceeded, the reveal would re-inject EVERY turn forever. Drop it instead — better to miss
+    // this one-shot once than to nag on every prompt.
+    return null;
   }
 
   const h = (m.report && m.report.headline) || {};

package/session-turns.mjs

@@ -0,0 +1,24 @@
+// session-turns.mjs — the SINGLE definition of "a genuine human user turn", shared by every path
+// that counts sessions (skalpel-setup's scanHistory + bootstrap's first-run scan). Claude Code logs
+// every tool RESULT back as a role:"user" message (content = [{type:"tool_result"}]); counting those
+// as user turns is the bug that classifies internal tool traffic as real intents and inflates
+// "found N sessions" so the client promises history the server then drops (empty graphs for
+// quiet/agentic users). Mirrors the server's engine._user_turn_count EXACTLY — one definition,
+// imported everywhere so the counting paths can never drift. See docs/SESSION-COUNTING.md.
+//
+// NOTE: this module is imported ONLY by the package-dir runners (skalpel-setup.mjs, bootstrap.mjs),
+// NOT by any hook staged into ~/.skalpel/hooks — so install.mjs deliberately does NOT stage it.
+const _HUMAN_PROMPT_SOURCES = new Set(["typed", "queued", "suggestion_accepted"]);
+
+export function isGenuineUserTurn(e) {
+  if (!(e?.type === "user" || e?.role === "user")) return false;
+  const ps = e?.promptSource;
+  if (ps != null) return _HUMAN_PROMPT_SOURCES.has(ps); // newer CLI: trust the source label
+  // older/current builds omit promptSource — a row is a tool RESULT (not a query) when its content
+  // is a block list carrying a tool_result. Everything else that's role:user is a genuine query.
+  const c = e?.message?.content;
+  if (Array.isArray(c) && c.some((b) => b && typeof b === "object" && b.type === "tool_result")) {
+    return false;
+  }
+  return true;
+}

package/skalpel-hook-session.mjs

@@ -84,6 +84,32 @@ function resetStats() {
   }
 }
 
+// A background graph build that FAILED/stalled (skalpel-setup backgroundBuild) drops
+// ~/.skalpel/build-stalled.json. Surface it ONCE at the next session start so the broken "I'll notify
+// you the moment it's ready" promise becomes visible ("re-run `skalpel`"), then clear it. If the
+// marker can't be cleared, drop the note rather than repeat it every session (same one-shot discipline
+// as the reveal — better to miss it once than nag forever).
+const BUILD_STALLED_PATH = join(homedir(), ".skalpel", "build-stalled.json");
+function buildStalledNote() {
+  let m;
+  try {
+    m = JSON.parse(readFileSync(BUILD_STALLED_PATH, "utf8"));
+  } catch {
+    return null; // no marker pending
+  }
+  if (!m || m.stalled !== true) return null;
+  try {
+    writeFileSync(BUILD_STALLED_PATH, JSON.stringify({ stalled: false })); // one-shot — clear it
+  } catch {
+    return null; // can't clear it (root-owned dir?) → drop rather than repeat every session
+  }
+  return (
+    "[skalpel — the background graph build did NOT finish (it stalled or timed out), so the promised " +
+    '"your graph is ready" never arrived. Tell the user in ONE short line: "🔬 skalpel · your graph ' +
+    'build stalled — re-run `skalpel` to finish it." Then continue normally.]'
+  );
+}
+
 // Config precedence: env > ~/.skalpel/client.json (written by `skalpel-prosumer setup`) > default.
 // Identity: the uid from the Google sign-in (~/.skalpel/auth.json); SKALPEL_USER overrides for dev.
 function fileCfg() {
@@ -151,10 +177,15 @@ async function main() {
     record("session", outcome, Date.now() - t0);
   }
 
-  // A just-finished background build leads (the async payoff — surface it the instant it's ready),
-  // then last session's recap, then the standing profile. Any can fire alone.
+  // A just-finished background build leads (the async payoff — surface it the instant it's ready);
+  // else a build that STALLED surfaces its one-time "re-run `skalpel`" note (the broken-promise trace).
+  // Then last session's recap, then the standing profile. Any can fire alone.
   const readyNote = graphReadyNote();
-  const additionalContext = [readyNote, recapNote, context].filter(Boolean).join("\n\n");
+  const stalled = buildStalledNote(); // reads + clears the one-shot stall marker (no-op when none)
+  const stalledNote = readyNote ? null : stalled; // a just-ready graph supersedes a stale stall note
+  const additionalContext = [readyNote, stalledNote, recapNote, context]
+    .filter(Boolean)
+    .join("\n\n");
 
   // LOCAL INSIGHT RECORDS (~/.skalpel/insights.ndjson) — plain-English rows for the TUI, one per
   // note that fired. recordInsight swallows everything, so these never affect the hook output.

package/skalpel-hook.mjs

@@ -246,21 +246,31 @@ function parseControl(q) {
   const t = (q || "").trim().toLowerCase();
   if (t.length > 60) return null; // a real coding prompt, not a reaction
   const mentionsUs = /\bskalpel\b/.test(t);
+  // A "pure control reaction" = the WHOLE prompt IS the control phrase (bare, aside from a leading
+  // politeness word or trailing punctuation) — "mute", "shut up", "fewer like this". Anchoring to the
+  // whole string is what stops a session-state change firing from a phrase buried in a REAL
+  // instruction like "disable the cache", "turn off dark mode", or "stop this loop from running".
+  // Any state-changing action (mute/unmute/fewer) now needs an explicit "skalpel" mention OR a pure
+  // reaction — never a bare substring. (The old `t.length < 24` heuristic matched that substring and
+  // silently muted every steer for the session; "fewer" had no guard at all.)
+  const pure = (body) => new RegExp(`^(?:please |hey |ok )?(?:${body})[\\s.!]*$`).test(t);
   // Explicit feedback is the LIGHT layer on top of the implicit adherence loop — natural-language
   // control the user can type when they want to steer skalpel directly. Mute is the important one.
   if (
     /\b(mute|silence|shut ?up|turn off|disable|stop steering|quiet)\b/.test(t) &&
-    (mentionsUs || t.length < 24)
+    (mentionsUs || pure("mute|silence|shut ?up|turn off|disable|stop steering|quiet"))
   )
     return { action: "mute" };
   if (
     /\bunmute|re-?enable|turn (it )?back on|resume steering\b/.test(t) &&
-    (mentionsUs || t.length < 24)
+    (mentionsUs || pure("unmute|re-?enable|turn (?:it )?back on|resume steering"))
   )
     return { action: "unmute" };
   if (
-    /\b(fewer|less|stop) (of )?(these|this|that|like this|steers?)\b/.test(t) ||
-    /\bfewer like this\b/.test(t)
+    (/\b(fewer|less|stop) (of )?(these|this|that|like this|steers?)\b/.test(t) ||
+      /\bfewer like this\b/.test(t)) &&
+    (mentionsUs ||
+      pure("(?:fewer|less|stop) (?:of )?(?:these|this|that|like this|steers?)|fewer like this"))
   )
     return { action: "fewer" };
   if (/\b(tell me more|more detail|expand|go deeper|more on this|explain the trap)\b/.test(t))
@@ -402,6 +412,46 @@ function dbg(msg) {
   }
 }
 
+// AUTH EXPIRY — the LOUD, once-per-expiry note. auth.identity() reports `expired:true` when the user
+// IS signed in but a token refresh FAILED. Left unsurfaced, the hook silently queries the graph as
+// `anon` forever — personalization evaporates and it reads as "skalpel found nothing". We surface a
+// single visible "session expired — run `skalpel login`" note, then remember we showed it so we don't
+// nag every turn; a later working identity clears the flag so a FUTURE expiry notifies again.
+const AUTH_NOTICE_PATH = join(homedir(), ".skalpel", "auth-notice.json");
+function authExpiredNoteOnce() {
+  try {
+    if (JSON.parse(readFileSync(AUTH_NOTICE_PATH, "utf8"))?.shown === true) return null; // already told them
+  } catch {
+    /* no notice file yet — this is the first expired turn */
+  }
+  try {
+    mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+    const tmp = `${AUTH_NOTICE_PATH}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ shown: true, ts: Date.now() }));
+    renameSync(tmp, AUTH_NOTICE_PATH);
+  } catch {
+    // Can't record that we showed it → DROP the note rather than risk repeating it every turn
+    // (same discipline as the one-shot reveal). Better to miss it once than nag forever.
+    return null;
+  }
+  return (
+    "[skalpel — the user's saved sign-in EXPIRED and the token refresh FAILED, so skalpel can't " +
+    "personalize this session (it would otherwise silently fall back to an empty anonymous graph). " +
+    'Tell them in ONE short line: "🔬 skalpel · session expired — run `skalpel login` to reconnect ' +
+    'your graph." Then continue with whatever they actually asked.]'
+  );
+}
+function clearAuthExpiredNotice() {
+  try {
+    // Only rewrite when it was actually set, to avoid a needless write on every healthy turn.
+    if (JSON.parse(readFileSync(AUTH_NOTICE_PATH, "utf8"))?.shown === true) {
+      writeFileSync(AUTH_NOTICE_PATH, JSON.stringify({ shown: false }));
+    }
+  } catch {
+    /* no notice file — nothing to clear */
+  }
+}
+
 async function main() {
   let payload = {};
   try {
@@ -481,126 +531,141 @@ async function main() {
 
   // identity from the Google sign-in (refreshed if near expiry); the token authenticates the call so
   // the server keys the graph by the VERIFIED uid. No token (dev/not signed in) -> server falls back.
-  const { uid, token } = await identity();
+  const { uid, token, expired } = await identity();
   const user = uid || CFG.user || "anon";
   const headers = { "content-type": "application/json" };
   if (token) headers.authorization = `Bearer ${token}`;
 
-  const remaining = deadline - Date.now();
-  if (remaining <= 100) {
-    dbg("  -> budget spent by auth, skipping retrieve");
-    record("prompt", "budget_spent", DEADLINE_MS);
-    return;
+  // AUTH EXPIRY (loud, once): signed in but the token refresh FAILED and there's no dev override, so
+  // `user` would fall to the anonymous graph. Surface the one-time "session expired" note and SKIP the
+  // pointless anon /retrieve — a visible nudge to re-login beats a silent "skalpel found nothing".
+  let authNote = null;
+  if (expired && !uid && !CFG.user) {
+    authNote = authExpiredNoteOnce();
+    dbg("  -> auth expired (refresh failed); surfacing login note, skipping anon retrieve");
+  } else if (uid || CFG.user) {
+    clearAuthExpiredNotice(); // a working identity resets the one-shot so a future expiry notifies again
   }
 
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), remaining);
-  const t0 = Date.now();
+  // Declared in main scope so the note-assembly at the bottom still sees them when the retrieve is skipped.
   let injection = null;
   let steerLabel = null; // "what skalpel's doing" for the statusline — a DESCRIPTION, never a number
   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 outcome = "fetch_error";
-  try {
-    const r = await fetch(`${API}/retrieve`, {
-      method: "POST",
-      headers,
-      // `recent` = the last few work-type classes THIS session (the trajectory) — lets the server fire
-      // the discriminative TELL ("you're on refine→refine→refine, the shape that goes bad 8×").
-      // `surface: "panel"` only for embedded TUI spawns (the TUI renders insights in its own panel,
-      // so the server keeps the steering but drops every "emit a 🔬 line" instruction). The key is
-      // omitted entirely otherwise — byte-stable body for non-embedded users.
-      body: JSON.stringify({
-        user_id: user,
-        query,
-        recent: readTraj(),
-        ...(process.env.SKALPEL_EMBEDDED === "1" ? { surface: "panel" } : {}),
-      }),
-      signal: ctrl.signal,
-    });
-    if (r.ok) {
-      const j = await r.json();
-      injection = j?.injection;
-      outcome = injection ? "inject" : "silent";
-      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);
-      if (j?.entry) pushTraj(String(j.entry).split("/")[0]); // remember this turn's work-type
-      dbg(`  -> sim=${j?.top_sim ?? "?"} ${injection ? "INJECT" : "silent"}`);
-
-      // readSteer() still holds the PRIOR turn's steer (we overwrite it below) — used after the n+1
-      // credit resolves to record adherence (did you act on it, and did acting pay off).
-      const prevSteer = readSteer();
-      // HONOR prefs + adherence GATE: mute / per-trap "fewer" / a type you consistently ignore all
-      // suppress the steer; "more" expands it.
-      const key = steerType ? (steerWt ? `${steerType}:${steerWt}` : steerType) : null;
-      const ignored = steerType && ignoredByAdherence(prefs, steerType);
-      if (prefs.muted_session || (key && prefs.suppress[key]) || ignored) {
-        injection = null;
-        steerLabel = null;
-        dbg(
-          `  -> suppressed (${prefs.muted_session ? "muted" : ignored ? "ignored-type" : "fewer"}) ${key || ""}`,
-        );
-      } else if (key && prefs.verbose[key] && injection) {
-        injection +=
-          "\n\n[skalpel — the user asked for MORE on this trap; expand: name the shape, the count, and the way out in 2-3 sentences.]";
-      }
 
-      // --- n+1 CONFIRMATION: did the user BREAK OUT of last turn's flagged pattern? (behavioral only) ---
-      // Turn N (a flagged high-waste moment) armed pending with V(N) = the DAG's expected waste-ahead from
-      // where you were. THIS turn's waste-ahead is V(N+1) = j.state_hours. A meaningful DROP means you
-      // moved toward "resolved" — a BEHAVIORAL signal that feeds adherence (did acting on the steer pay
-      // off). It is NEVER converted into a user-facing "time saved" number: the DAG state values are a
-      // server estimate, not a measured clock, so surfacing them as minutes would be fabrication.
-      const vNow = typeof j?.state_hours === "number" ? j.state_hours : null;
-      const pending = readPending();
-      if (pending && typeof pending.v === "number" && vNow !== null) {
-        // >=0.08 in the estimate's units = a real move toward resolved (not estimate jitter). Boolean only.
-        brokeOut = pending.v - vNow >= 0.08;
-        dbg(
-          `  -> n+1 ${brokeOut ? "BREAK-OUT" : "no-breakout"}: waste-ahead ${pending.v} -> ${vNow}`,
-        );
-        writePending({}); // this turn's confirmation is consumed
-      }
-      // Arm NEXT turn: when the injection fires (a flagged high-waste moment) AND we have a V for this
-      // turn, remember it so N+1 can tell whether you broke out.
-      if (injection && vNow !== null) {
-        writePending({ v: vNow });
-      } else if (!pending || vNow !== null) {
-        writePending({}); // clear only when we actually had data this turn (don't drop a stale carry)
-      }
+  if (!authNote) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 100) {
+      dbg("  -> budget spent by auth, skipping retrieve");
+      record("prompt", "budget_spent", DEADLINE_MS);
+      return;
+    }
 
-      // IMPLICIT ADHERENCE (the real Grammarly loop): now that the break-out check has resolved, record
-      // whether LAST turn's steer landed — did you act on it (moved off its work-type) and did acting pay
-      // off (a break-out this turn). Accretes per steer-type; the gate above reads it next time. This is
-      // categorical revealed-preference data, not a number shown to the user.
-      const paid = brokeOut;
-      const adh = recordAdherence(prefs, prevSteer, steerWt, paid);
-      writePrefs(prefs);
-      // ADHERENCE INSIGHT ROW (data, not display — no `display` field): the same judgment, exported
-      // for the TUI's rail, joined to the prior steer by its minted id. followed = the n+1 credit
-      // landed; ignored = you stayed on the very work-type the steer pushed you off AND no credit;
-      // anything else (no prior steer / indeterminate turn) writes nothing.
-      const adhOutcome = paid ? "followed" : adh && prevSteer.wt && !adh.acted ? "ignored" : null;
-      if (prevSteer?.id && adhOutcome)
-        recordInsight({
-          kind: "adherence",
-          ref: prevSteer.id,
-          outcome: adhOutcome,
-          harness,
-          session_id: sessionId,
-        });
-    } else {
-      outcome = "server_error";
-      dbg(`  -> server ${r.status}`);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), remaining);
+    const t0 = Date.now();
+    let outcome = "fetch_error";
+    try {
+      const r = await fetch(`${API}/retrieve`, {
+        method: "POST",
+        headers,
+        // `recent` = the last few work-type classes THIS session (the trajectory) — lets the server fire
+        // the discriminative TELL ("you're on refine→refine→refine, the shape that goes bad 8×").
+        // `surface: "panel"` only for embedded TUI spawns (the TUI renders insights in its own panel,
+        // so the server keeps the steering but drops every "emit a 🔬 line" instruction). The key is
+        // omitted entirely otherwise — byte-stable body for non-embedded users.
+        body: JSON.stringify({
+          user_id: user,
+          query,
+          recent: readTraj(),
+          ...(process.env.SKALPEL_EMBEDDED === "1" ? { surface: "panel" } : {}),
+        }),
+        signal: ctrl.signal,
+      });
+      if (r.ok) {
+        const j = await r.json();
+        injection = j?.injection;
+        outcome = injection ? "inject" : "silent";
+        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);
+        if (j?.entry) pushTraj(String(j.entry).split("/")[0]); // remember this turn's work-type
+        dbg(`  -> sim=${j?.top_sim ?? "?"} ${injection ? "INJECT" : "silent"}`);
+
+        // readSteer() still holds the PRIOR turn's steer (we overwrite it below) — used after the n+1
+        // credit resolves to record adherence (did you act on it, and did acting pay off).
+        const prevSteer = readSteer();
+        // HONOR prefs + adherence GATE: mute / per-trap "fewer" / a type you consistently ignore all
+        // suppress the steer; "more" expands it.
+        const key = steerType ? (steerWt ? `${steerType}:${steerWt}` : steerType) : null;
+        const ignored = steerType && ignoredByAdherence(prefs, steerType);
+        if (prefs.muted_session || (key && prefs.suppress[key]) || ignored) {
+          injection = null;
+          steerLabel = null;
+          dbg(
+            `  -> suppressed (${prefs.muted_session ? "muted" : ignored ? "ignored-type" : "fewer"}) ${key || ""}`,
+          );
+        } else if (key && prefs.verbose[key] && injection) {
+          injection +=
+            "\n\n[skalpel — the user asked for MORE on this trap; expand: name the shape, the count, and the way out in 2-3 sentences.]";
+        }
+
+        // --- n+1 CONFIRMATION: did the user BREAK OUT of last turn's flagged pattern? (behavioral only) ---
+        // Turn N (a flagged high-waste moment) armed pending with V(N) = the DAG's expected waste-ahead from
+        // where you were. THIS turn's waste-ahead is V(N+1) = j.state_hours. A meaningful DROP means you
+        // moved toward "resolved" — a BEHAVIORAL signal that feeds adherence (did acting on the steer pay
+        // off). It is NEVER converted into a user-facing "time saved" number: the DAG state values are a
+        // server estimate, not a measured clock, so surfacing them as minutes would be fabrication.
+        const vNow = typeof j?.state_hours === "number" ? j.state_hours : null;
+        const pending = readPending();
+        if (pending && typeof pending.v === "number" && vNow !== null) {
+          // >=0.08 in the estimate's units = a real move toward resolved (not estimate jitter). Boolean only.
+          brokeOut = pending.v - vNow >= 0.08;
+          dbg(
+            `  -> n+1 ${brokeOut ? "BREAK-OUT" : "no-breakout"}: waste-ahead ${pending.v} -> ${vNow}`,
+          );
+          writePending({}); // this turn's confirmation is consumed
+        }
+        // Arm NEXT turn: when the injection fires (a flagged high-waste moment) AND we have a V for this
+        // turn, remember it so N+1 can tell whether you broke out.
+        if (injection && vNow !== null) {
+          writePending({ v: vNow });
+        } else if (!pending || vNow !== null) {
+          writePending({}); // clear only when we actually had data this turn (don't drop a stale carry)
+        }
+
+        // IMPLICIT ADHERENCE (the real Grammarly loop): now that the break-out check has resolved, record
+        // whether LAST turn's steer landed — did you act on it (moved off its work-type) and did acting pay
+        // off (a break-out this turn). Accretes per steer-type; the gate above reads it next time. This is
+        // categorical revealed-preference data, not a number shown to the user.
+        const paid = brokeOut;
+        const adh = recordAdherence(prefs, prevSteer, steerWt, paid);
+        writePrefs(prefs);
+        // ADHERENCE INSIGHT ROW (data, not display — no `display` field): the same judgment, exported
+        // for the TUI's rail, joined to the prior steer by its minted id. followed = the n+1 credit
+        // landed; ignored = you stayed on the very work-type the steer pushed you off AND no credit;
+        // anything else (no prior steer / indeterminate turn) writes nothing.
+        const adhOutcome = paid ? "followed" : adh && prevSteer.wt && !adh.acted ? "ignored" : null;
+        if (prevSteer?.id && adhOutcome)
+          recordInsight({
+            kind: "adherence",
+            ref: prevSteer.id,
+            outcome: adhOutcome,
+            harness,
+            session_id: sessionId,
+          });
+      } else {
+        outcome = "server_error";
+        dbg(`  -> server ${r.status}`);
+      }
+    } catch (e) {
+      outcome = e?.name === "AbortError" ? "abort" : "fetch_error";
+      dbg(`  -> fetch failed: ${String(e).slice(0, 60)}`);
+    } finally {
+      clearTimeout(timer);
+      record("prompt", outcome, Date.now() - t0);
     }
-  } catch (e) {
-    outcome = e?.name === "AbortError" ? "abort" : "fetch_error";
-    dbg(`  -> fetch failed: ${String(e).slice(0, 60)}`);
-  } finally {
-    clearTimeout(timer);
-    record("prompt", outcome, Date.now() - t0);
   }
 
   // MUTE is absolute — a shushed session surfaces NOTHING (steer or reset). The ack note (a one-time
@@ -651,10 +716,13 @@ async function main() {
     });
 
   // A just-finished background build leads (one-shot: surface "your graph's ready" the instant the next
-  // prompt fires, so the user doesn't have to restart a session to see it), then ackNote (feedback
-  // confirmation), the reset interrupt (most acute), and the server steer. Any can fire alone.
+  // prompt fires, so the user doesn't have to restart a session to see it), then the one-time auth-expiry
+  // note, then ackNote (feedback confirmation), the reset interrupt (most acute), and the server steer.
+  // Any can fire alone.
   const readyNote = graphReadyNote();
-  const additionalContext = [readyNote, ackNote, resetNote, injection].filter(Boolean).join("\n\n");
+  const additionalContext = [readyNote, authNote, ackNote, resetNote, injection]
+    .filter(Boolean)
+    .join("\n\n");
   if (additionalContext) {
     process.stdout.write(
       JSON.stringify({

package/skalpel-setup.mjs

@@ -21,6 +21,7 @@ import { createInterface, emitKeypressEvents } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { identity as authIdentity, cliAuthPath } from "./auth.mjs";
+import { isGenuineUserTurn } from "./session-turns.mjs";
 
 // CLI (the `skalpel` bin): `skalpel setup [--api https://graph.skalpel.ai]
 // [--user <id>]`, plus `skalpel uninstall` and `skalpel login`. A bare invocation
@@ -437,26 +438,10 @@ async function reportLiveAndLaunch(message) {
 // arbitrary "cap to 100" that could upload fragments and MISS the real sessions.
 const MIN_USER_TURNS = Math.max(1, Number.parseInt(process.env.SKALPEL_MIN_USER_TURNS || "5", 10));
 
-// USER QUERIES ONLY. Claude Code logs every tool RESULT back as a role:"user" message
-// (content = [{type:"tool_result"}]). Counting those as "user turns" is the bug that classified
-// internal tool traffic as real intents and inflated "found N" so the client promised sessions the
-// server then dropped (empty graphs for quiet/agentic users). This mirrors the server's
-// engine._user_turn_count EXACTLY so the client's count == what the server ingests. One definition,
-// two implementations kept in lockstep — see docs/SESSION-COUNTING.md.
-const _HUMAN_PROMPT_SOURCES = new Set(["typed", "queued", "suggestion_accepted"]);
-function isGenuineUserTurn(e) {
-  if (!(e?.type === "user" || e?.role === "user")) return false;
-  const ps = e?.promptSource;
-  if (ps != null) return _HUMAN_PROMPT_SOURCES.has(ps); // newer CLI: trust the source label
-  // older/current builds omit promptSource — a row is a tool RESULT (not a query) when its content
-  // is a block list carrying a tool_result. Everything else that's role:user is a genuine query.
-  const c = e?.message?.content;
-  if (Array.isArray(c) && c.some((b) => b && typeof b === "object" && b.type === "tool_result")) {
-    return false;
-  }
-  return true;
-}
-
+// USER QUERIES ONLY (not the tool_result rows Claude Code logs as role:"user"). The single
+// definition of a genuine turn now lives in ./session-turns.mjs so scanHistory here, bootstrap's
+// first-run scan, and the server's engine._user_turn_count can never drift — see
+// docs/SESSION-COUNTING.md.
 export async function userTurnCount(path, cap = 5) {
   let n = 0;
   const input = createReadStream(path, { encoding: "utf8" });
@@ -640,6 +625,10 @@ async function buildGraph(sp, files, id) {
         done = true;
       } else if (s.state === "error") {
         throw new Error("build failed");
+      } else if (s.state === "empty") {
+        // server found zero parseable sessions — an honest terminal state, not a 20-min hang
+        total = 0;
+        done = true;
       } else if (s.state === "judging" && s.total) {
         sp.text(`Judging your sessions…${label} ${s.done}/${s.total}`);
       }
@@ -1017,10 +1006,18 @@ async function backgroundBuild() {
   if (!id) return; // not signed in — nothing to build under
   const files = await scanHistory();
   if (!files.length) return;
+  const stalledPath = join(homedir(), ".skalpel", "build-stalled.json");
   const sp = { text: () => {}, succeed: () => {} }; // silent — no TTY in the background
   try {
     const built = await buildGraph(sp, files, id);
     if (!built) return;
+    // Build landed — clear any "stalled" marker a prior failed run left, so the next SessionStart
+    // doesn't surface a stale build-stalled note after the graph actually finished.
+    try {
+      writeFileSync(stalledPath, JSON.stringify({ stalled: false }));
+    } catch {
+      /* best-effort */
+    }
     let report = null;
     try {
       report = await fetchProfile(id);
@@ -1039,8 +1036,23 @@ async function backgroundBuild() {
     } catch {
       /* the reveal is a bonus; never block the build on it */
     }
-  } catch {
-    /* fail-open: a failed background build never surfaces; hooks fail open until it succeeds */
+  } catch (e) {
+    // The "I'll notify you the moment it's ready" promise just broke — buildGraph threw (e.g. "build
+    // timed out" / "build failed" / an ingest error). Leave a marker so the next SessionStart can tell
+    // the user to re-run `skalpel`, instead of the promised graph silently never arriving.
+    try {
+      mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
+      writeFileSync(
+        stalledPath,
+        JSON.stringify({
+          stalled: true,
+          ts: Date.now(),
+          error: String(e?.message || e).slice(0, 200),
+        }),
+      );
+    } catch {
+      /* even the marker write failed — nothing more we can do; still fail-open, never throw */
+    }
   }
 }