kankaku-claude 1.0.0 → 1.0.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kankaku",
   "description": "Records how long Claude Code works on each of your prompts: wall time, waiting time, work time and cost, per prompt, in kankaku's worklog format.",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": {
     "name": "soyunninja"
   },

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 1.0.2 — 2026-09-29
+
+### Fixed
+
+- **`/kankaku:status` promised a recovery that would not happen.** The
+  line compared the session total with the sum of ALL the session's
+  records and, when idle, called the whole difference "unrecorded, goes
+  to the next prompt". For a session that spent money before it had a
+  chained baseline (upgraded mid-way, or resumed without its state) that
+  was false: the next prompt only carries what was spent since the last
+  settle. The line now separates `this prompt so far`, `pending, goes to
+  the next prompt` and `never recorded`. Attribution itself was correct
+  in 1.0.1 and is unchanged.
+
+## 1.0.1 — 2026-09-29
+
+### Fixed
+
+- Spend that landed between two prompts was in no record: on a real session
+  the statusline total was 461.06 USD while its 134 records summed to
+  299.80 USD, so 35 % of the spend was missing. A prompt's cost was measured
+  from the statusline snapshot at submit, which left background subagent
+  work and late statusline refreshes after a `Stop` unattributed. The
+  session state now keeps `costBaseline`, the total at the last settle, and
+  each prompt is measured from it (Stop, SessionEnd and crash recovery), so
+  the records of a session add up to its total. A new session starts at 0; a
+  counter reset records the new total. `/kankaku:status` shows `recorded $X
+  of $Y` and flags an unrecorded gap. Headless runs still have no cost.
+
 ## 1.0.0 — 2026-09-29
 
 ### Changed

package/README.md

@@ -140,8 +140,16 @@ anything behind in whatever project happens to be open.
   `node dist/cli.js report`).
 - `/kankaku:status` — the sessions kankaku-claude currently has state for:
   session id, whether its process is still alive, whether a prompt is open,
-  and the last cost the statusline reported, preceded by the resolved work
-  target (wraps `node dist/cli.js status`).
+  and the last cost the statusline reported, followed by `recorded $X of
+  $Y` (the sum of this session's record costs in this project's worklog
+  against the session total). When they differ by more than a cent the line says what the
+  difference is: `(this prompt so far $R)` for the open prompt's running
+  spend, `(pending $P, goes to the next prompt)` for what was spent since
+  the last settle of a session that has a chained baseline, and
+  `(never recorded $Z)` for spend from before the session had one (a
+  session upgraded mid-way, or resumed without its state) — no later
+  prompt carries that part.
+  The resolved work target comes first (wraps `node dist/cli.js status`).
 - `/kankaku:task` — links this session to a hub task (wraps
   `node dist/cli.js task`); see "Linking a task" below.
 - `/kankaku:setup` — prints the `statusLine` snippet described above (wraps
@@ -257,6 +265,37 @@ from Claude Code is not supported yet. Assignment is create-only
 on the hub: a row already uploaded as unassigned stays that way until it is
 reassigned in the web app; a later sync does not move it.
 
+## How cost is derived
+
+Claude Code hooks carry no cost. The only source is the statusline, whose
+`cost.total_cost_usd` is the running total of the session; the statusline
+command stores the latest value under your home directory (see "Where the
+files live").
+
+- **Per-prompt difference.** A prompt's cost is the session total when the
+  prompt settles minus the total the prompt is measured from, rounded to
+  micro-dollars and never negative.
+- **Chained baseline.** The session state keeps `costBaseline`, the session
+  total at the last settle. The next prompt is measured from that baseline,
+  not from the snapshot at submit, so the records of a session add up to its
+  total. A session Claude Code reports as newly started (`SessionStart`
+  source `startup`) begins with baseline 0. A resumed session keeps the
+  baseline of its state file; with no state file its first prompt is
+  measured from the snapshot at submit.
+- **Spend between prompts belongs to the next record.** `worklog.jsonl` is
+  append-only and the previous record is already written, so anything spent
+  after a settle and before the next prompt (background subagents that keep
+  running, a statusline refresh that arrives after `Stop`) is added to the
+  next record of the same session.
+- **Counter reset.** If the total is lower than the value the prompt is
+  measured from, the counter was reset: the prompt's cost is the new total
+  and the baseline restarts from it.
+- **Headless runs have no cost.** `claude -p` renders no statusline, so
+  there is no total: the record stays without cost (`costObserved` unset)
+  and the baseline does not move.
+- `/kankaku:status` shows `recorded $X of $Y` per live session so a gap is
+  visible.
+
 ## Where the files live
 
 - `<KANKAKU_DIR>/worklog.jsonl` — the append-only log of settled records,
@@ -304,9 +343,11 @@ still open is closed at that same instant.
   only the statusline's aggregate `total_cost_usd`; per-record `usage` token
   fields stay at zero, cost is the only populated figure.
 - **Cost is a per-prompt delta of the session total, from the statusline,
-  and needs the manual setup step.** A tiny race is possible: the statusline
-  can render after `Stop` has already computed the delta, in which case a
-  sliver of one prompt's cost is attributed to the next prompt instead.
+  and needs the manual setup step.** See "How cost is derived". Spend that
+  lands between two prompts (a late statusline refresh, a background
+  subagent still running) is attributed to the next record of the session,
+  not lost. Headless `claude -p` runs have no statusline, so their records
+  carry no cost.
 - **A permission wait ends at the next hook event, not when you actually
   click.** There is no documented hook that fires the moment you answer a
   permission dialog, so the waiting span closes at whatever hook fires next

package/dist/cli-core.js

@@ -52,12 +52,21 @@ function runStatus(deps) {
     if (files.length === 0) {
         return { stdout: `${targetLine}\nNo active sessions.\n`, exitCode: 0 };
     }
+    const recordedBySession = new Map();
+    for (const record of new JsonlWorkLog(kankakuDir).readAll()) {
+        if (record.sessionId === undefined)
+            continue;
+        recordedBySession.set(record.sessionId, (recordedBySession.get(record.sessionId) ?? 0) + record.usage.cost);
+    }
     const lines = files
         .sort()
-        .map((file) => formatStatusLine(sessionIdFromStateFile(file), file, deps.isAlive, deps.env));
+        .map((file) => {
+        const sessionId = sessionIdFromStateFile(file);
+        return formatStatusLine(sessionId, file, deps.isAlive, deps.env, recordedBySession.get(sessionId) ?? 0);
+    });
     return { stdout: [targetLine, ...lines].join("\n") + "\n", exitCode: 0 };
 }
-function formatStatusLine(sessionId, stateFile, isAlive, env) {
+function formatStatusLine(sessionId, stateFile, isAlive, env, recordedUsd) {
     const state = readState(stateFile);
     if (!state)
         return `${sessionId}  (unreadable state)`;
@@ -67,7 +76,41 @@ function formatStatusLine(sessionId, stateFile, isAlive, env) {
         : "idle";
     const cost = readCost(env, sessionId);
     const costWord = cost ? `$${cost.totalUsd.toFixed(2)}` : "-";
-    return `${sessionId}  pid ${state.pid} (${aliveWord})  ${promptWord}  cost ${costWord}`;
+    const base = `${sessionId}  pid ${state.pid} (${aliveWord})  ${promptWord}  cost ${costWord}`;
+    if (!cost)
+        return base;
+    return `${base}  recorded $${recordedUsd.toFixed(2)} of $${cost.totalUsd.toFixed(2)}${describeGap(state, cost.totalUsd, recordedUsd)}`;
+}
+/** Amounts of one cent or less are rounding noise, never reported. */
+const REPORTABLE_USD = 0.01;
+/**
+ * Splits the difference between the session's total and what its records
+ * hold into what it actually is, so the line never promises a recovery
+ * that will not happen:
+ *
+ * - `this prompt so far`: the open prompt's running spend (total − its
+ *   `costAtStart`); it lands in that prompt's own record at settle.
+ * - `pending, goes to the next prompt`: only when idle AND the session has
+ *   a `costBaseline` — the next prompt starts there, so it picks this up.
+ *   Without a baseline the next prompt starts at the snapshot and picks up
+ *   nothing, so nothing is promised.
+ * - `never recorded`: whatever is left — spent before this session had a
+ *   chained baseline (a session upgraded mid-way, or resumed without its
+ *   state). It is in no record and no later prompt will carry it.
+ */
+function describeGap(state, totalUsd, recordedUsd) {
+    const start = state.promptOpen?.costAtStart;
+    const running = state.promptOpen && typeof start === "number" ? Math.max(0, totalUsd - start) : 0;
+    const pending = !state.promptOpen && typeof state.costBaseline === "number" ? Math.max(0, totalUsd - state.costBaseline) : 0;
+    const neverRecorded = totalUsd - recordedUsd - running - pending;
+    const parts = [];
+    if (running > REPORTABLE_USD)
+        parts.push(` (this prompt so far $${running.toFixed(2)})`);
+    if (pending > REPORTABLE_USD)
+        parts.push(` (pending $${pending.toFixed(2)}, goes to the next prompt)`);
+    if (neverRecorded > REPORTABLE_USD)
+        parts.push(` (never recorded $${neverRecorded.toFixed(2)})`);
+    return parts.join("");
 }
 function sessionIdFromStateFile(file) {
     return basename(file).replace(/\.state\.json$/, "");

package/dist/cost-chain.js

@@ -0,0 +1,20 @@
+/**
+ * The chained per-prompt cost rule. `totalUsd` is the session total at
+ * settle, `start` the total the prompt is measured from (the previous
+ * settle's baseline, or the snapshot at submit for a session with none).
+ *
+ * - No finite total (headless, no statusline): nothing observed, baseline
+ *   untouched.
+ * - Total below the start: the counter was reset, so the cost is the total.
+ * - Otherwise cost = total - start, in micro-dollars (no binary float noise).
+ *
+ * Node builtins only; safe on the light hook path.
+ */
+export function settleCost(totalUsd, start) {
+    if (typeof totalUsd !== "number" || !Number.isFinite(totalUsd))
+        return {};
+    if (typeof start !== "number" || !Number.isFinite(start))
+        return { baseline: totalUsd };
+    const raw = totalUsd < start ? totalUsd : totalUsd - start;
+    return { cost: Math.max(0, Math.round(raw * 1e6) / 1e6), baseline: totalUsd };
+}

package/dist/handle-hook.js

@@ -5,6 +5,7 @@ import { readState, writeState, updateState } from "./session-state.js";
 import { resolveClaudePid } from "./claude-pid.js";
 import { splitPrompts } from "./prompts.js";
 import { readCost, deleteCost, sweepStaleCostFiles } from "./cost-store.js";
+import { settleCost } from "./cost-chain.js";
 const STOP_COST_WAIT_POLL_MS = 100;
 const STOP_COST_WAIT_MAX_MS = 1500;
 /**
@@ -31,14 +32,16 @@ export async function handleHook(input, deps) {
                 ? { ts, event: "UserPromptSubmit", prompt, promptId }
                 : { ts, event: "UserPromptSubmit", prompt };
             appendEvent(paths.eventsFile, event);
-            const costAtStart = readCost(deps.env, sessionId)?.totalUsd;
+            const snapshot = readCost(deps.env, sessionId)?.totalUsd;
             updateState(paths.stateFile, (state) => ({
                 pid: state?.pid ?? 0,
                 parentPid: state?.parentPid ?? 0,
                 cwd: state?.cwd || cwd,
                 startedAt: state?.startedAt ?? ts,
-                promptOpen: { id: promptId ?? `${sessionId}:${ts}`, startedAt: ts, costAtStart },
+                // The chained baseline wins over the snapshot: spend since the last settle belongs to this prompt.
+                promptOpen: { id: promptId ?? `${sessionId}:${ts}`, startedAt: ts, costAtStart: state?.costBaseline ?? snapshot },
                 permissionOpen: null,
+                ...(state?.costBaseline !== undefined ? { costBaseline: state.costBaseline } : {}),
             }));
             return;
         }
@@ -68,6 +71,7 @@ export async function handleHook(input, deps) {
                 startedAt: state?.startedAt ?? ts,
                 promptOpen: state?.promptOpen ?? null,
                 permissionOpen: ts,
+                ...(state?.costBaseline !== undefined ? { costBaseline: state.costBaseline } : {}),
             }));
             return;
         }
@@ -95,7 +99,7 @@ export async function handleHook(input, deps) {
         case "SessionStart": {
             const source = readString(raw.source) ?? "startup";
             appendEvent(paths.eventsFile, { ts, event: "SessionStart", source });
-            await handleSessionStart(paths, sessionId, cwd, source, ts, deps);
+            await handleSessionStart(paths, sessionId, cwd, source, raw.source === "startup", ts, deps);
             return;
         }
         case "SessionEnd": {
@@ -128,25 +132,27 @@ async function handleStop(paths, sessionId, deps) {
             deps.stderr(`kankaku: no session state at Stop for ${sessionId}`);
         return;
     }
-    const costAtStart = state.promptOpen?.costAtStart;
-    const totalUsd = cost?.totalUsd;
-    const costDelta = typeof costAtStart === "number" && typeof totalUsd === "number"
-        ? Math.max(0, Math.round((totalUsd - costAtStart) * 1e6) / 1e6) // micro-dollars: no binary float noise in the record
-        : undefined;
-    const core = replayPrompt(last, { cost: costDelta });
+    // A Stop with no open prompt settles nothing: no cost, no baseline move.
+    const settled = state.promptOpen ? settleCost(cost?.totalUsd, state.promptOpen.costAtStart) : {};
+    const core = replayPrompt(last, { cost: settled.cost });
     if (core) {
         const assignment = await assignmentResolver(paths, deps);
         const record = buildClaudeRecord(core, state, sessionId, cost?.model, assignment(state.cwd, sessionId));
         const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
         log.append(record);
     }
-    writeState(paths.stateFile, { ...state, promptOpen: null, permissionOpen: null });
+    writeState(paths.stateFile, {
+        ...state,
+        promptOpen: null,
+        permissionOpen: null,
+        ...(settled.baseline !== undefined ? { costBaseline: settled.baseline } : {}),
+    });
     const keep = events.slice(0, events.length - last.events.length);
     dropSettledPrompts(paths.eventsFile, keep);
     if (core)
         await syncHeavy("agent_settled", state.cwd, deps);
 }
-async function handleSessionStart(paths, sessionId, cwd, source, ts, deps) {
+async function handleSessionStart(paths, sessionId, cwd, source, isStartup, ts, deps) {
     if (source !== "compact") {
         const { recoverStaleSessions } = await import("./inflight-recovery.js");
         const { JsonlWorkLog } = await import("kankaku-pi/hub");
@@ -180,6 +186,8 @@ async function handleSessionStart(paths, sessionId, cwd, source, ts, deps) {
         startedAt: ts,
         promptOpen: null,
         permissionOpen: null,
+        // A newly started session's counter starts at zero; any other source keeps the snapshot-at-submit fallback.
+        ...(isStartup ? { costBaseline: 0 } : {}),
     };
     writeState(paths.stateFile, state);
     await syncHeavy("session_start", cwd, deps);
@@ -194,9 +202,11 @@ async function handleSessionEnd(paths, sessionId, cwd, ts, deps) {
         const prompts = splitPrompts(events);
         const last = prompts[prompts.length - 1];
         if (last) {
-            const core = replayPrompt(last, { settledAt: ts });
+            const costNow = readCost(deps.env, sessionId);
+            const settled = settleCost(costNow?.totalUsd, state.promptOpen.costAtStart);
+            const core = replayPrompt(last, { settledAt: ts, cost: settled.cost });
             if (core) {
-                const model = readCost(deps.env, sessionId)?.model;
+                const model = costNow?.model;
                 const assignment = await assignmentResolver(paths, deps);
                 const record = buildClaudeRecord(core, state, sessionId, model, assignment(state.cwd, sessionId));
                 const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);

package/dist/inflight-recovery.js

@@ -6,6 +6,7 @@ import { readEventLog } from "./event-log.js";
 import { splitPrompts, replayPrompt } from "./replay.js";
 import { buildClaudeRecord } from "./record.js";
 import { readCost, deleteCost } from "./cost-store.js";
+import { settleCost } from "./cost-chain.js";
 /**
  * Crash recovery: for every other session's state file whose pid is dead,
  * replay its still-open prompt (if any) into an `interrupted` record, then
@@ -46,9 +47,10 @@ export function recoverStaleSessions(input) {
                 // `now` is only a fallback when no usable timestamp exists.
                 const lastTs = last.events[last.events.length - 1]?.ts;
                 const settledAt = typeof lastTs === "number" && Number.isFinite(lastTs) ? lastTs : input.now;
-                const core = replayPrompt(last, { settledAt });
+                const costNow = readCost(input.env, sessionId);
+                const core = replayPrompt(last, { settledAt, cost: settleCost(costNow?.totalUsd, state.promptOpen.costAtStart).cost });
                 if (core) {
-                    const model = readCost(input.env, sessionId)?.model;
+                    const model = costNow?.model;
                     records.push(buildClaudeRecord(core, state, sessionId, model, input.resolveAssignment?.(state.cwd, sessionId)));
                 }
             }

package/dist/replay.js

@@ -97,5 +97,10 @@ export function replayPrompt(prompt, opts = {}) {
     if (terminalStopIndex >= 0)
         return settled;
     current = opts.settledAt ?? prompt.events[prompt.events.length - 1].ts;
-    return tracker.onShutdown();
+    const interrupted = tracker.onShutdown();
+    if (!interrupted || typeof opts.cost !== "number" || !Number.isFinite(opts.cost))
+        return interrupted;
+    // An interrupted prompt ends no turn, so the tracker saw no cost; stamp the
+    // measured delta without inventing a turn.
+    return { ...interrupted, usage: { ...interrupted.usage, cost: interrupted.usage.cost + opts.cost }, costObserved: true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [
@@ -27,7 +27,7 @@
     "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "kankaku-pi": "^1.0.0"
+    "kankaku-pi": "^1.0.2"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",