peon-mem 1.0.0 → 1.0.1

package/README.md

@@ -1,5 +1,7 @@
 # 🧠 Peon — a memory brain for your AI coding agents
 
+[![npm](https://img.shields.io/npm/v/peon-mem)](https://www.npmjs.com/package/peon-mem) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![tests](https://img.shields.io/badge/tests-255%20passing-brightgreen)](test/)
+
 **Local-first, hierarchical, self-improving memory for Claude Code, Codex, and any MCP client.**
 
 Your AI forgets everything between sessions. Peon doesn't. It records your sessions, consolidates
@@ -40,6 +42,9 @@ automatically, from a daemon that never leaves your machine.
 ![The Neural Universe — every belief is a star, projects are galaxies](docs/assets/neural-universe.png)
 *The live monitor: 18k real beliefs rendered as stars. Type to make matching beliefs flare; click one to inspect it.*
 
+![Search flare — type a query and matching beliefs light up across every galaxy](docs/assets/search-flare.gif)
+*Ask the field: typing "wulver cluster" makes 400+ matching beliefs flare while the rest dim, and the camera flies to them.*
+
 ## Why "Peon"?
 
 The name comes from Indian offices. Every office had a **peon** — the person who walked desk to
@@ -78,10 +83,10 @@ recommended (consolidation + semantic embeddings); without one Peon still works
 One line:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash
+npm install -g peon-mem && peon-mem install
 ```
 
-(or, once you have the CLI: `npm install -g peon-mem && peon-mem install`)
+(no Node? `curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash`)
 
 The guided setup asks four things:
 
@@ -276,6 +281,69 @@ launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist
   swallow a project's memory.
 - The global brain lives in `~/Library/Application Support/Peon/global/` (macOS).
 
+## Using Peon with NO AI at all
+
+Some people want a memory system that never calls a model — no API keys, no local LLM, no
+embeddings, fully deterministic. Peon supports that as a first-class mode: pick **skip** in the
+install wizard, or set two env vars in `<memory-home>/.env`:
+
+```
+PEON_AI_MODE=off
+PEON_EMBEDDING_MODE=off
+```
+
+**What still works (all of it deterministic code, no model anywhere):**
+
+- **Capture** — hooks record every prompt, tool call, and session event to plain JSONL in
+  `<project>/.peon/raw/`.
+- **Real-time brain files** — decisions, preferences, open questions, and artifacts are written
+  live to readable `.md` files by rule-based extraction as events arrive.
+- **Injection** — session-start context comes from those real-time files, query-focused and
+  budgeted, same as always.
+- **Search** — lexical retrieval (RRF over keyword rank + recency + importance + type priors).
+  No embeddings needed; this is the same degrade path the semantic stack falls back to.
+- **Episodic recall** — verbatim what-was-said lookup is lexical by design, so it is unaffected.
+- **Monitor UI, token tracking, cross-project search, backups** — all model-free.
+
+**What you give up:** consolidation (raw events are never distilled into deduplicated beliefs —
+memory grows as an append-only journal), semantic search (paraphrased queries need shared
+keywords), automatic entity extraction, and stale-shadow demotion (it compares embeddings).
+
+**Two escape hatches if you want curation without external AI:**
+
+1. `process_memory` accepts a pre-built `aiResult` — the coding agent you already run (Claude
+   Code, Codex) can do the distillation itself in-session and hand Peon the structured result.
+   Memory stays curated, and Peon itself never spends a token.
+2. Everything is plain JSONL/Markdown on disk — you can edit beliefs by hand or through the
+   monitor's memory endpoints. Peon backs up before every mutation.
+
+## Measured: does memory actually save tokens?
+
+A/B test, real `claude -p` sessions, one question per session, same repo, same model. ON = Peon
+hooks active (memory injected at session start), OFF = `PEON_DISABLED=1` (agent falls back to
+reading files). 20 questions across procedures, past results, decisions, and current-state facts;
+15 clean ON/OFF pairs survived tooling issues. Token counts read from Claude Code's own
+session transcripts.
+
+| paired, n=15/arm | ON (Peon) | OFF | delta |
+|---|---|---|---|
+| avg tokens (in+out) | **511** | 878 | **−42%** |
+| median tokens | **225** | 1,048 | **−79%** |
+| cache-read tokens | 81.6k | 110.5k | 1.35× less |
+| cheaper arm | **ON wins 12/15** | | |
+
+Answer quality (graded against repo ground truth): 8 ties, 1 clear Peon win, 5 baseline wins,
+1 both-weak. The Peon win is the interesting one: a rule that was only ever stated in a
+conversation (a professor's citation policy from an email) — the baseline answered *"no such
+rule found"*, Peon recited it exactly. Conversation-borne knowledge has no file to grep.
+
+Honest caveats: the test repo has unusually good docs (a maintained research log), which makes
+the baseline strong — most repos aren't like that; n=15 is small; questions were picked to have
+known answers, not sampled from real usage. Two weaknesses this test exposed — a stale
+superseded belief outranking the newer truth, and token rows lost when consolidation outlived
+the hook timeout — are both fixed (stale-shadow demotion at retrieval; usage logged before
+consolidation).
+
 ## Honesty section
 
 Peon's development is eval-gated and keeps its negative results: an associative entity graph was

package/bin/peon-mem.mjs

@@ -205,7 +205,12 @@ if (cmd === "install") {
     if (!up) log("  → Ollama not running. Install: https://ollama.com  then: ollama pull llama3.2 && ollama pull nomic-embed-text");
     else log("  ✔ Ollama detected on :11434 — pull models if missing: ollama pull llama3.2 && ollama pull nomic-embed-text");
   } else {
-    envLines.push("# no provider configured — Peon runs lexical-only. Re-run `peon-mem install` anytime.");
+    envLines.push(
+      "# No-AI mode: no provider, no model calls, no embeddings. Peon runs as a",
+      "# deterministic memory recorder with lexical retrieval. Re-run `peon-mem install` anytime.",
+      "PEON_AI_MODE=off",
+      "PEON_EMBEDDING_MODE=off"
+    );
   }
   if (existsSync(envFile)) log("  ✔ keeping existing " + envFile);
   else act("write " + envFile, () => writeFileSync(envFile, envLines.join("\n") + "\n"));

package/dist/memory-store.js

@@ -7,7 +7,7 @@ import { cosineSimilarity, createEmbeddingClient } from "./embeddings.js";
 import { applyDelete, applyMerge, applyPin, applyUpdate } from "./memory-mutations.js";
 import { runSleepCycle } from "./brain.js";
 import { readdir, rm } from "node:fs/promises";
-import { rankMemoryRecords as rankWithRetrieval, computeGraphActivation, diversifyByMMR } from "./retrieval.js";
+import { rankMemoryRecords as rankWithRetrieval, computeGraphActivation, demoteStaleShadows, diversifyByMMR } from "./retrieval.js";
 import { currentAsOf, changesBetween } from "./temporal.js";
 import { inferCanonicalEntities, buildEntityRegistry, canonicalizeEntity } from "./entities.js";
 import { redactSecrets } from "./injection.js";
@@ -464,14 +464,14 @@ export class PeonMemoryStore {
         const limit = options.limit ?? 50;
         const direct = rankWithRetrieval(records, query, { limit, semantic });
         if (!options.expandGraph || direct.length === 0)
-            return direct;
+            return demoteStaleShadows(direct, semantic?.vectorById);
         // FUSED associative recall: spread activation from the direct hits through the entity graph,
         // then RE-RANK with that activation as a (damped) signal — so a strongly-associated belief can
         // enter the top-K and displace a weak direct hit, instead of being appended out of the window.
         const graphActivation = computeGraphActivation(direct, records);
         if (graphActivation.size === 0)
-            return direct;
-        return rankWithRetrieval(records, query, { limit, semantic, graphActivation });
+            return demoteStaleShadows(direct, semantic?.vectorById);
+        return demoteStaleShadows(rankWithRetrieval(records, query, { limit, semantic, graphActivation }), semantic?.vectorById);
     }
     /**
      * Rank records WITHOUT mutating anything — uses only embeddings already on disk
@@ -497,7 +497,7 @@ export class PeonMemoryStore {
                 // lexical-only on any embedding failure
             }
         }
-        return rankWithRetrieval(records, query, { limit: options.limit ?? 50, semantic });
+        return demoteStaleShadows(rankWithRetrieval(records, query, { limit: options.limit ?? 50, semantic }), semantic?.vectorById);
     }
     async buildSemanticInput(query, records) {
         if (!query || !query.trim() || !this.embeddingClient || !this.embeddingStore || records.length === 0) {

package/dist/monitor.js

@@ -92,6 +92,10 @@ const CLIENT_SCRIPT = String.raw `
   function renderRoute(force){
     var r=currentRoute();
     ROUTES.forEach(function(x){ var p=EL("page-"+x); if(p) p.hidden=(x!==r); });
+    // The project dropdown is CONTEXT, not chrome: it only applies inside a project's
+    // Insights/Memory pages. Global pages (Neural Core / Sectors / Systems) hide it —
+    // switching projects there happens by picking a galaxy or a sector card.
+    var sw=EL("switcher"); if(sw) sw.hidden=!(r==="overview"||r==="memory");
     // Nav highlight: overview/memory belong under "projects".
     ["brain","projects","ops"].forEach(function(x){ var t=EL("nav-"+x); if(t) t.classList.toggle("on", x===r || ((r==="overview"||r==="memory")&&x==="projects")); });
     if(r==="brain"){ loadDashboard(force); renderBrainHome(); }
@@ -184,6 +188,20 @@ const CLIENT_SCRIPT = String.raw `
       ' <span class="stl-dot" style="background:'+dotc+'" title="'+esc(stl)+'"></span>';
   }
 
+  var SPRITES={};
+  function nodeSprite(color, glow){
+    var key=color+(glow?"G":"");
+    if(SPRITES[key]) return SPRITES[key];
+    var pad=glow?10:2, R=6, size=(R+pad)*2;
+    var sc=document.createElement("canvas"); sc.width=size; sc.height=size;
+    var g=sc.getContext("2d");
+    if(glow){ g.shadowColor=color; g.shadowBlur=9; }
+    g.fillStyle=color; g.beginPath(); g.arc(size/2,size/2,R,0,6.29); g.fill();
+    if(glow){ g.fill(); }
+    SPRITES[key]={c:sc,R:R,half:size/2};
+    return SPRITES[key];
+  }
+
   function uniProject(n){ /* world position with slow galaxy rotation */
     var t=(Date.now()-UNI.t0);
     var th=n.th + t*n.cl.spin;
@@ -237,18 +255,22 @@ const CLIENT_SCRIPT = String.raw `
     });
     // nodes
     var hits=UNI.hits, dimOthers=!!(hits&&hits.size);
+    // viewport bounds in world coords (with margin) for culling
+    var vw=W/2/UNI.cam.z+30, vh=H/2/UNI.cam.z+30, vcx=UNI.cam.x, vcy=UNI.cam.y;
     UNI.nodes.forEach(function(n){
       uniProject(n);
+      if(n.x<vcx-vw||n.x>vcx+vw||n.y<vcy-vh||n.y>vcy+vh) return; // offscreen — skip draw
       var tw=0.78+0.22*Math.sin(t/900+n.tw);
       var a=n.a*tw, r=n.r;
       if(dimOthers){ if(hits.has(n.id)){ a=1; r=n.r*1.7; } else a*=0.08; }
       if(n.hot) r*=1.15;
-      ctx.beginPath(); ctx.arc(n.x,n.y,r/Math.sqrt(UNI.cam.z),0,6.29);
+      var glow=(dimOthers&&hits.has(n.id))||n===UNI.hover||n===UNI.selected||n.rec.status==="conflicted";
+      var sp=nodeSprite(n.c, glow);
+      var scale=(r/Math.sqrt(UNI.cam.z))/sp.R;
       ctx.globalAlpha=Math.min(1,a);
-      ctx.fillStyle=n.c;
-      if((dimOthers&&hits.has(n.id))||n===UNI.hover||n===UNI.selected||n.rec.status==="conflicted"){ ctx.shadowColor=n.c; ctx.shadowBlur=12; } else ctx.shadowBlur=0;
-      ctx.fill(); ctx.shadowBlur=0; ctx.globalAlpha=1;
+      ctx.drawImage(sp.c, n.x-sp.half*scale, n.y-sp.half*scale, sp.c.width*scale, sp.c.height*scale);
     });
+    ctx.globalAlpha=1;
     // hover crosshair
     if(UNI.hover){ var hN=UNI.hover; var hr=10/UNI.cam.z;
       ctx.strokeStyle="rgba(234,255,255,.85)"; ctx.lineWidth=1/UNI.cam.z;
@@ -257,14 +279,15 @@ const CLIENT_SCRIPT = String.raw `
       ctx.moveTo(hN.x,hN.y-hr*1.8); ctx.lineTo(hN.x,hN.y-hr); ctx.moveTo(hN.x,hN.y+hr); ctx.lineTo(hN.x,hN.y+hr*1.8); ctx.stroke();
     }
     ctx.restore();
-    uniGridBuild();
+    if(!UNI.lastGrid||t-UNI.lastGrid>250){ uniGridBuild(); UNI.lastGrid=t; }
     // tooltip
     var tip=EL("uni-tip");
     if(tip){ if(UNI.hover){ var sp=uniToScreen(UNI.hover,W,H);
         tip.hidden=false; tip.style.left=Math.min(W-330,Math.max(8,sp.x+16))+"px"; tip.style.top=Math.max(8,sp.y-14)+"px";
         tip.innerHTML='<span class="tt-type" style="color:'+UNI.hover.c+'">'+esc(UNI.hover.rec.type)+'</span> '+esc(clip(UNI.hover.rec.content,140));
       } else tip.hidden=true; }
-    UNI.raf=requestAnimationFrame(uniDraw);
+    // ~30fps is indistinguishable here and halves the draw cost on big brains
+    UNI.raf=requestAnimationFrame(function(){ setTimeout(function(){ UNI.raf=0; uniDraw(); }, 15); });
   }
   function uniToScreen(n,W,H){ return { x:(n.x-UNI.cam.x)*UNI.cam.z+W/2, y:(n.y-UNI.cam.y)*UNI.cam.z+H/2 }; }
   function uniToWorld(sx,sy){ var c=uniCanvas(); var W=c.clientWidth,H=c.clientHeight;
@@ -822,7 +845,7 @@ const DOCUMENT = String.raw `<!doctype html>
   .uniwrap::before{content:""; position:absolute; top:0; left:0; width:16px; height:16px; border-top:1.5px solid var(--line2); border-left:1.5px solid var(--line2); z-index:5; pointer-events:none;}
   .uniwrap::after{content:""; position:absolute; bottom:0; right:0; width:16px; height:16px; border-bottom:1.5px solid var(--line2); border-right:1.5px solid var(--line2); z-index:5; pointer-events:none;}
   #uni{position:absolute; inset:0; width:100%; height:100%; cursor:crosshair;}
-  .uni-search{position:absolute; top:14px; left:50%; transform:translateX(-50%); z-index:6; display:flex; gap:8px; align-items:center; width:min(560px,80%);}
+  .uni-search{position:absolute; top:68px; left:50%; transform:translateX(-50%); z-index:6; display:flex; gap:8px; align-items:center; width:min(560px,72%);}
   .uni-search input{flex:1; padding:9px 16px; border:1px solid rgba(89,227,255,.5); clip-path:var(--cham); background:rgba(3,12,22,.88);
     font-family:var(--mono); font-size:12px; color:var(--cyan-ink); backdrop-filter:blur(8px);}
   .uni-search input:focus{border-color:var(--cyan); outline:none; box-shadow:0 0 22px -6px rgba(89,227,255,.9);}
@@ -831,7 +854,7 @@ const DOCUMENT = String.raw `<!doctype html>
   .uni-hud{position:absolute; z-index:6; font-family:var(--mono); font-size:10px; letter-spacing:.12em; color:var(--muted);
     background:rgba(3,12,22,.72); border:1px solid var(--line); padding:7px 12px; clip-path:var(--cham); backdrop-filter:blur(6px);}
   .uni-hud b{color:var(--cyan-ink); font-weight:700;} .uni-hud b.warn{color:var(--amber);}
-  .uni-hud.tl{top:14px; left:14px;} .uni-hud.tr{top:60px; right:14px;}
+  .uni-hud.tl{top:14px; left:14px; max-width:58%;} .uni-hud.tr{top:14px; right:14px;}
   .stl-dot{display:inline-block; width:8px; height:8px; border-radius:50%; margin-left:6px; vertical-align:-1px; box-shadow:0 0 8px currentColor;}
   .uni-legend{position:absolute; left:14px; bottom:76px; z-index:6; display:flex; flex-wrap:wrap; gap:9px; max-width:70%;}
   .ul{display:inline-flex; align-items:center; gap:5px; font-family:var(--mono); font-size:9px; letter-spacing:.1em; text-transform:uppercase; color:var(--muted);}

package/dist/retrieval.d.ts

@@ -104,3 +104,19 @@ export declare function computeGraphActivation(seeds: RankedMemoryRecord[], pool
  * rankMemoryRecords' graphActivation option, which lets associations compete inside the top-K.
  */
 export declare function expandByEntityGraph(seeds: RankedMemoryRecord[], pool: MemoryRecord[], options?: GraphExpandOptions): RankedMemoryRecord[];
+/**
+ * Stale-shadow demotion. Measured failure mode (token A/B, question x1): recall answered with a
+ * SUPERSEDED architecture description because the old belief was still active, semantically strong,
+ * and outranked the newer truth. When two active beliefs in the ranked window describe the same fact
+ * — near-duplicate vectors, or moderately similar with a shared entity and the same type — but were
+ * written in different eras, the older one is treated as a stale shadow of the newer: its score is
+ * scaled down so the newer belief always outranks it. Nothing is deleted or re-statused here; real
+ * supersession stays the consolidator's job. Pinned records are never demoted.
+ */
+export declare function demoteStaleShadows(ranked: RankedMemoryRecord[], vectorById: Map<string, EmbeddingVector> | undefined, options?: {
+    scan?: number;
+    hardSim?: number;
+    softSim?: number;
+    ageGapMs?: number;
+    penalty?: number;
+}): RankedMemoryRecord[];

package/dist/retrieval.js

@@ -390,3 +390,70 @@ function clamp(value) {
 function roundScore(value) {
     return Math.round(value * 1000) / 1000;
 }
+/**
+ * Stale-shadow demotion. Measured failure mode (token A/B, question x1): recall answered with a
+ * SUPERSEDED architecture description because the old belief was still active, semantically strong,
+ * and outranked the newer truth. When two active beliefs in the ranked window describe the same fact
+ * — near-duplicate vectors, or moderately similar with a shared entity and the same type — but were
+ * written in different eras, the older one is treated as a stale shadow of the newer: its score is
+ * scaled down so the newer belief always outranks it. Nothing is deleted or re-statused here; real
+ * supersession stays the consolidator's job. Pinned records are never demoted.
+ */
+export function demoteStaleShadows(ranked, vectorById, options = {}) {
+    if (!vectorById || vectorById.size === 0 || ranked.length < 2)
+        return ranked;
+    const scan = options.scan ?? 30;
+    const hardSim = options.hardSim ?? 0.8;
+    const softSim = options.softSim ?? 0.6;
+    const ageGapMs = options.ageGapMs ?? 3 * 24 * 60 * 60 * 1000;
+    const penalty = options.penalty ?? 0.35;
+    const window = ranked.slice(0, scan);
+    const recordTime = (item) => timestamp(item.record.updatedAt || item.record.createdAt);
+    const shadowOf = new Map(); // demoted id -> newer id it shadows
+    for (let i = 0; i < window.length; i += 1) {
+        for (let j = i + 1; j < window.length; j += 1) {
+            const a = window[i];
+            const b = window[j];
+            if (a.record.type !== b.record.type)
+                continue;
+            if (a.record.status !== "active" || b.record.status !== "active")
+                continue;
+            const va = vectorById.get(a.record.id);
+            const vb = vectorById.get(b.record.id);
+            if (!va || !vb)
+                continue;
+            const sim = cosineSimilarity(va, vb);
+            if (sim < softSim)
+                continue;
+            const sharedEntity = a.record.entities.some((e) => b.record.entities.includes(e));
+            if (sim < hardSim && !sharedEntity)
+                continue;
+            const [older, newer] = recordTime(a) <= recordTime(b) ? [a, b] : [b, a];
+            if (recordTime(newer) - recordTime(older) < ageGapMs)
+                continue;
+            if (older.record.pinned)
+                continue;
+            if (!shadowOf.has(older.record.id))
+                shadowOf.set(older.record.id, newer.record.id);
+        }
+    }
+    if (shadowOf.size === 0)
+        return ranked;
+    return ranked
+        .map((item) => {
+        const newerId = shadowOf.get(item.record.id);
+        if (!newerId)
+            return item;
+        return {
+            ...item,
+            score: roundScore(item.score * penalty),
+            explanation: `${item.explanation}; stale shadow of newer belief ${newerId}`,
+            reasons: [...item.reasons, { kind: "status", label: `stale shadow of ${newerId}`, score: 0 }]
+        };
+    })
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return timestamp(right.record.updatedAt) - timestamp(left.record.updatedAt);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peon-mem",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/scripts/claude-peon-hook.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { appendFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createReadStream as fsCreateReadStream, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 
-// Hard off-switch (for A/B testing). When PEON_DISABLED is set, the hook does
-// nothing at all — no recording, no context injection, no daemon calls — so the
-// session runs purely on the cloud model with zero Peon involvement.
-if (/^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "")) process.exit(0);
+// Hard off-switch (for A/B testing). When PEON_DISABLED is set, Peon does nothing —
+// no injection, no recording, no daemon calls — EXCEPT counting the session's token
+// usage on Stop/SessionEnd, because the OFF arm's whole purpose is to be the baseline
+// in the token A/B comparison. (Handled inside the main block below.)
+const PEON_OFF = /^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "");
 
 const daemonUrl = (process.env.PEON_DAEMON_URL || "http://127.0.0.1:3737").replace(/\/$/, "");
 const stateDir =
@@ -39,6 +40,12 @@ const PEON_FIRST_DIRECTIVE =
 // so it is initialized before the top-level await block calls getProjectContext.
 const MAX_CONTEXT_QUERY_CHARS = 2000;
 
+// Token A/B ledger paths — declared BEFORE the top-level await block (everything the main
+// block touches must be initialized first, or the reference throws a silent TDZ error;
+// that exact bug made token tracking a no-op for weeks).
+const TOKEN_AB_LOG = join(homedir(), "Library", "Application Support", "Peon", "token-ab-log.jsonl");
+const TOKEN_AB_LOGGED_SESSIONS = join(homedir(), "Library", "Application Support", "Peon", "token-ab-sessions.json");
+
 // Resolve any working directory to its ONE project brain, so memory never fragments:
 //   1. collapse git-worktree paths to the repo root (…/.claude/worktrees/x → repo)
 //   2. walk UP to the TOPMOST ancestor that already holds a Peon brain (.peon), bounded by
@@ -88,6 +95,11 @@ try {
     readText(input, ["session_id", "sessionId", "conversation_id", "conversationId", "thread_id", "threadId"]) ||
     externalSessionId;
 
+  if (PEON_OFF) {
+    if (eventName === "Stop" || eventName === "SessionEnd") await trackTokenUsage(input, projectPath, externalSessionId);
+    process.exit(0);
+  }
+
   if (eventName === "SessionStart") {
     await ensurePeonSession({ projectPath, externalSessionId, client: hookClient });
     const context = await getProjectContext(projectPath, "recent project context decisions artifacts current work");
@@ -159,14 +171,17 @@ try {
     // A response TURN finished — capture the summary and let Peon consolidate,
     // but keep the session ALIVE. Stop fires after every turn; the Claude session
     // (and the Peon session) continues across turns and only ends on SessionEnd.
+    // Token tracking runs FIRST: consolidation below can outlive the hook timeout
+    // ("Hook cancelled"), which used to silently drop the token ledger row.
+    await trackTokenUsage(input, projectPath, externalSessionId);
     const finalMessage = extractAssistantSummary(input);
     if (finalMessage.trim()) {
       await recordWithSession({ projectPath, externalSessionId, client: hookClient }, (sessionId) =>
         postJson("/events", { sessionId, type: "assistant_summary", content: finalMessage.slice(0, 2000) }));
     }
     await postJson("/process/auto", { projectPath, trigger: "turn_end" }).catch(() => undefined);
-    await trackTokenUsage(input, projectPath, externalSessionId);
   } else if (eventName === "SessionEnd") {
+    await trackTokenUsage(input, projectPath, externalSessionId);
     const finalMessage = extractAssistantSummary(input);
     if (finalMessage.trim()) {
       await recordWithSession({ projectPath, externalSessionId, client: hookClient }, (sessionId) =>
@@ -180,7 +195,6 @@ try {
       // stale session id gets replayed forever and recording silently dies.
       await removeSession(externalSessionId);
     }
-    await trackTokenUsage(input, projectPath, externalSessionId);
   }
 } catch (error) {
   await appendLocalError({
@@ -400,16 +414,11 @@ function safeName(value) {
   return String(value).replace(/[^a-zA-Z0-9_.-]/g, "_");
 }
 
-const TOKEN_AB_LOG = join(homedir(), "Library", "Application Support", "Peon", "token-ab-log.jsonl");
-
-const TOKEN_AB_LOGGED_SESSIONS = join(homedir(), "Library", "Application Support", "Peon", "token-ab-sessions.json");
-
 async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath }) {
   try {
-    // Only log once per session — Stop fires on every response turn, not just session end.
-    const logged = JSON.parse(await readFile(TOKEN_AB_LOGGED_SESSIONS, "utf8").catch(() => "[]"));
-    if (logged.includes(externalSessionId)) return;
-
+    // Upsert per session: Stop fires after every turn, so each firing re-reads the full
+    // transcript and replaces this session's row — the last Stop leaves the final totals.
+    // (The old once-per-session gate froze turn-1 partials and dropped the rest.)
     const totals = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0, model: "unknown" };
     const rl = createInterface({ input: fsCreateReadStream(transcriptPath), crlfDelay: Infinity });
     for await (const line of rl) {
@@ -425,6 +434,9 @@ async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath
         if (obj?.message?.model) totals.model = obj.message.model;
       } catch { /* skip malformed lines */ }
     }
+    // A Stop can fire before any usage lines hit the transcript — never write an empty row.
+    if (totals.input + totals.output === 0) return;
+
     const peonEnabled = !/^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "");
     const record = {
       ts: new Date().toISOString(),
@@ -438,13 +450,20 @@ async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath
       cacheCreateTokens: totals.cacheCreate,
       totalTokens: totals.input + totals.output,
     };
+    if (process.env.PEON_AB_TAG) record.tag = process.env.PEON_AB_TAG;
     const dir = join(homedir(), "Library", "Application Support", "Peon");
     await mkdir(dir, { recursive: true });
-    await appendFile(TOKEN_AB_LOG, JSON.stringify(record) + "\n", "utf8");
-    // Mark session as logged (keep last 500 to avoid unbounded growth)
-    logged.push(externalSessionId);
-    await writeFile(TOKEN_AB_LOGGED_SESSIONS, JSON.stringify(logged.slice(-500)), "utf8");
-  } catch { /* non-fatal */ }
+    // Rewrite the log with this session's previous rows dropped — file stays one row per session.
+    const existing = (await readFile(TOKEN_AB_LOG, "utf8").catch(() => ""))
+      .split("\n").filter(Boolean)
+      .filter((line) => {
+        try { return JSON.parse(line).sessionId !== externalSessionId; } catch { return true; }
+      });
+    existing.push(JSON.stringify(record));
+    const tmp = TOKEN_AB_LOG + ".tmp";
+    await writeFile(tmp, existing.slice(-2000).join("\n") + "\n", "utf8");
+    await rename(tmp, TOKEN_AB_LOG);
+  } catch (e) { if (process.env.PEON_AB_DEBUG) console.error("AB-ERR:", e && e.message); }
 }
 
 async function appendLocalError(error) {