@agentguard-run/burn 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.2 (2026-09-21)
+
+- Follow the newest ledger decision on every live refresh, unless a session is pinned. Show the raw session ID prefix and record identity switches. A switch immediately releases a previous session's STOP hold.
+- Read panel counters from the hook's decision window, including pending spawn reservations. Record the exact active window, token count and ceiling for future decisions. Elapsed starts at the first ledger decision, not the transcript start. Historical measurements that were never recorded remain unknown.
+- Add `record --session ID --from ISO --to ISO --out run.jsonl` to reconstruct local ledger decisions at their original timestamps with one-second display ticks. No transcript contents or live state changes are needed.
+- Replace the current showcase with the verified September 20 spawn-rate block: 16 proposals against 16, with a full red bar, the STOP reason and original timing. The older hashed display ID referred to this same session; the defect was stale transcript counters versus pending reservations.
+
 ## 0.3.1 (2026-09-20)
 
 - Add the live session screen: block-digit counters for spawns, tokens in window and replay share, a spawn-rate bar against the policy ceiling, the last decisions with verdict chips, and a two-second STOP hold, all through the canvas. The same screen renders recorded runs.

package/README.md

@@ -387,9 +387,28 @@ No telemetry. No provider-quota guesses. Account forecasts use only observed hos
 
 ### Local live panel
 
-`agentguard-burn live` displays spawn and token counts within the active window,
-session cache-read share, the policy rate bar and the last eight local decisions.
-Use `--session ID`, `--once`, `--record run.jsonl`, or `--replay run.jsonl`.
-STOP reasons hold for two seconds while observations continue. The display is
-local and does not affect admission. Missing observations remain unknown.
-See [the live panel and recorded September 19 evidence](docs/LIVE_PANEL_2026_09.md).
+`agentguard-burn live` follows the session with the newest local ledger decision
+on every refresh. `--session ID` pins a full ID, unique ID prefix or digest.
+The header shows the raw session ID prefix when the decision ledger supplies it.
+Spawn and token counters, the rate ceiling and the last eight decisions come
+from that session's decision ledger. Pending spawn proposals are included,
+exactly as the hook measured them. Elapsed starts at its first ledger decision.
+A change of session is captured as `sessionSwitch` in `--record run.jsonl`.
+
+Use `--once`, `--record run.jsonl`, or `--replay run.jsonl`. STOP reasons hold
+for two seconds while observations continue, and a session switch releases
+that hold immediately. The display never changes admission. Historical token
+windows and cache-read share remain unknown when the ledger did not record them.
+
+Reconstruct an event after it happened, entirely from local ledgers:
+
+```sh
+agentguard-burn record --session 0b0c2202 --from 2026-09-20T20:20:32Z --to 2026-09-20T20:20:52Z --out run.jsonl
+agentguard-burn render run.jsonl --mp4 run.mp4 --gif run.gif
+```
+
+`record` writes each decision at its real timestamp, with one frame per second
+between decisions. Bounds are optional and otherwise use the session's first
+and last decisions. Earlier decisions still supply window context. The output
+must be new. It contains identifiers and measured metadata, never tool input,
+output or transcript content. See [the live panel and September 20 evidence](docs/LIVE_PANEL_2026_09.md).

package/dist/src/cli.d.ts

@@ -4,6 +4,7 @@
  *
  *   ps                local agent processes, held memory and orphan workspace disk
  *   reap              interactively SIGTERM selected safe processes, never delete
+ *   record            reconstruct a session recording from its ledger decisions
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
  *   status            mode, shadow decisions, eligibility, every host's sessions

package/dist/src/cli.js

@@ -5,6 +5,7 @@
  *
  *   ps                local agent processes, held memory and orphan workspace disk
  *   reap              interactively SIGTERM selected safe processes, never delete
+ *   record            reconstruct a session recording from its ledger decisions
  *   replay            what enforcement would have stopped, on your history
  *   calibrate         fit thresholds to your own usage, write shadow policy
  *   status            mode, shadow decisions, eligibility, every host's sessions
@@ -130,6 +131,13 @@ async function main(argv) {
             const { runLivePanel } = await Promise.resolve().then(() => __importStar(require('./live-panel')));
             return runLivePanel(HOME, rawRest);
         }
+        case 'record': {
+            const { recordLedger, recordLedgerArguments } = await Promise.resolve().then(() => __importStar(require('./record-ledger')));
+            const result = recordLedger(HOME, recordLedgerArguments(rest));
+            show({ kind: 'command', command, values: { ...result } }, `Recording: ${result.output}\nSession: ${result.session}\nRange: ${result.from} to ${result.to}\n${result.frameCount} frames from ${result.decisionCount} ledger decisions.\n`
+                + (result.clippedStopHold ? 'The requested end clips the final STOP hold. No decision timestamps were extended.\n' : ''));
+            return 0;
+        }
         case 'ps':
         case 'reap':
             return (0, cli_1.runIdleCommand)(command, rawRest, HOME);
@@ -374,9 +382,10 @@ async function main(argv) {
             return 0;
         }
         default:
-            show({ kind: 'command', command: 'help', values: { commands: ['ps', 'reap', 'live', 'render', 'blocks', 'why', 'rewrites', 'pace', 'statusline', 'pricing', 'replay', 'calibrate', 'status', 'init', 'enforce', 'shadow', 'resume', 'proxy', 'conformance'] } }, 'agentguard-burn <ps|reap|live|render|blocks|why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+            show({ kind: 'command', command: 'help', values: { commands: ['ps', 'reap', 'live', 'record', 'render', 'blocks', 'why', 'rewrites', 'pace', 'statusline', 'pricing', 'replay', 'calibrate', 'status', 'init', 'enforce', 'shadow', 'resume', 'proxy', 'conformance'] } }, 'agentguard-burn <ps|reap|live|record|render|blocks|why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
                 '  ps [--json]          local agent processes, held memory and workspace disk\n' +
                 '  render <run.jsonl> --mp4 <out.mp4> [--gif <out.gif>]   local recorded-run export\n' +
+                '  record --session <id> [--from <iso>] [--to <iso>] --out <run.jsonl>   reconstruct local ledger frames\n' +
                 '  live [--session ID] [--once] [--replay run.jsonl]  local instrument panel\n' +
                 '  --record <file.jsonl> append structured frames for any command; --no-color keeps plain output\n' +
                 '  reap                 numbered interactive SIGTERM, never delete or force-kill\n' +
@@ -401,6 +410,11 @@ async function main(argv) {
 }
 async function run() {
     const parsed = (0, recording_1.recordingArguments)(process.argv.slice(2));
+    if (parsed.args[0] === 'record' && parsed.file) {
+        const { recordLedgerArguments, validateCompanionRecording } = await Promise.resolve().then(() => __importStar(require('./record-ledger')));
+        const options = recordLedgerArguments(parsed.args.slice(1).filter(arg => arg !== '--no-color'));
+        validateCompanionRecording(HOME, options.out, parsed.file);
+    }
     (0, recording_1.configureRecording)(parsed.file);
     try {
         const code = await main(parsed.args);

package/dist/src/gateway.js

@@ -219,13 +219,13 @@ class Gateway {
                 }
                 const live = new Map(meta.liveSpawns);
                 const proposedDepth = event.proposedDepth ?? (event.issuerId !== undefined && live.has(event.issuerId) ? live.get(event.issuerId) + 1 : 1);
-                const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, event.spawnId, event.at, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
+                const { report, reservation, window } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, event.spawnId, event.at, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at }, meta.capabilities);
                 const wouldBlock = report.verdict === 'STOP' || !reservation.allowed;
                 const verdict = wouldBlock ? 'STOP' : report.verdict;
                 // Session-scope STOPs need a session we trust. Fan-out is session scope.
                 const due = wouldBlock && policy.mode === 'enforce' && event.attribution === 'high';
                 const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
-                const decision = this.finish({ action: 'spawn', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth, verdict, wouldBlock, blocked: due && !override, override, report, effectiveSpawns: reservation.effectiveSpawns, compute: null }, policy, meta, state);
+                const decision = this.finish({ action: 'spawn', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth, verdict, wouldBlock, blocked: due && !override, override, report, effectiveSpawns: reservation.effectiveSpawns, compute: null, window }, policy, meta, state);
                 this.save(meta, state);
                 return decision;
             });
@@ -272,7 +272,8 @@ class Gateway {
                 const due = wouldBlock && policy.mode === 'enforce' && (event.attribution === 'high' || machineStop);
                 const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
                 const blocked = due && !override;
-                const decision = this.finish({ action: 'model_call', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth: null, verdict: report.verdict, wouldBlock, blocked, override, report, effectiveSpawns: state.spawnCount, compute }, policy, meta, state);
+                const decision = this.finish({ action: 'model_call', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth: null, verdict: report.verdict, wouldBlock, blocked, override, report, effectiveSpawns: state.spawnCount, compute,
+                    window: (0, spawn_window_1.decisionWindow)(state, policy.thresholds, false, meta.capabilities) }, policy, meta, state);
                 if (blocked) {
                     // A denied call neither occupies the machine nor spends tokens.
                     tx.finishCall(event.callId, windowMs(policy), event.at);
@@ -379,6 +380,7 @@ class Gateway {
             findings: d.report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
             effectiveSpawns: d.effectiveSpawns,
             totals: d.report.totals,
+            window: d.window,
             compute: d.compute,
             coverage: meta.capabilities,
         })}\n`, { mode: 0o600 });

package/dist/src/hook/pre-tool-use.js

@@ -189,7 +189,7 @@ function handleSpawnPreToolUse(input, home, now) {
             // Depth of the proposed child: the issuing agent's depth plus one. A hook
             // fired inside a subagent carries agent_id; treat that as depth 1 issuer.
             const proposedDepth = input.agent_id ? 2 : 1;
-            const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, input.tool_use_id ?? `${input.session_id}:${now}`, now, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
+            const { report, reservation, window } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, input.tool_use_id ?? `${input.session_id}:${now}`, now, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
             const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
             const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
             // The audited override: only consulted when a block is about to happen.
@@ -223,6 +223,7 @@ function handleSpawnPreToolUse(input, home, now) {
                 findings: report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
                 effectiveSpawns: reservation.effectiveSpawns,
                 totals: report.totals,
+                window,
             });
             if (shouldDeny && policy.mode === 'enforce') {
                 if (!override) {

package/dist/src/ledger-panel.d.ts

@@ -0,0 +1,40 @@
+import type { LivePanelSnapshot, PanelDecision } from './live-panel';
+import type { Verdict } from './types';
+export interface LedgerWindow {
+    activeMinutes: number | null;
+    windowActiveMinutes: number | null;
+    spawns: number | null;
+    tokens: number | null;
+    spawnCeiling: number | null;
+    replayShare: number | null;
+}
+export interface LedgerSession {
+    sessionId: string | null;
+    sessionDigest: string;
+}
+export interface LedgerDecision extends PanelDecision, LedgerSession {
+    /** Unique chronological order after joining matching receipts. */
+    sequence: number;
+    activeMinutes: number | null;
+    effectiveSpawns: number | null;
+    totalSpawns: number | null;
+    totalTokens: number | null;
+    window: LedgerWindow | null;
+    rate: {
+        observed: number;
+        threshold: number | null;
+        verdict: Verdict;
+    } | null;
+    usageKnown: boolean;
+    spawnsKnown: boolean;
+    /** Loaded only when the signed receipt proves the exact policy digest. */
+    legacyPolicy: {
+        windowActiveMinutes: number;
+        spawnCeiling: number;
+    } | null;
+}
+/** Join each receipt once. Signed receipt identifiers do not duplicate decisions. */
+export declare function readPanelLedger(home: string): LedgerDecision[];
+/** Accept full ids or unique raw-id/digest prefixes; never silently pick ambiguity. */
+export declare function resolveLedgerSession(rows: LedgerDecision[], selector?: string): LedgerSession | undefined;
+export declare function projectLedgerPanel(rows: LedgerDecision[], selector?: string, at?: number): LivePanelSnapshot;

package/dist/src/ledger-panel.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPanelLedger = readPanelLedger;
+exports.resolveLedgerSession = resolveLedgerSession;
+exports.projectLedgerPanel = projectLedgerPanel;
+/** Content-free panel projection from the decisions the local gate recorded. */
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_string_decoder_1 = require("node:string_decoder");
+const defaults_1 = require("./defaults");
+const policy_1 = require("./policy");
+const receipt_1 = require("./receipt");
+const digest = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const number = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+const positive = (value) => number(value) !== null && Number(value) > 0 ? Number(value) : null;
+const verdict = (value) => value === 'OK' || value === 'WARN' || value === 'STOP' ? value : null;
+const safe = (value, fallback) => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,160}$/.test(value) ? value : fallback;
+const known = (coverage) => coverage === undefined || coverage === 'authoritative' || coverage === 'estimated';
+/** Scan complete history in chunks, including a complete final line without LF. */
+function rows(file) {
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(file, 'r');
+    }
+    catch {
+        return [];
+    }
+    const out = [], decoder = new node_string_decoder_1.StringDecoder('utf8'), bytes = Buffer.alloc(64 * 1024);
+    let pending = '';
+    const parse = (line) => { try {
+        const value = object(JSON.parse(line));
+        if (Object.keys(value).length)
+            out.push(value);
+    }
+    catch { /* Incomplete or malformed rows are not observations. */ } };
+    try {
+        let length;
+        while ((length = (0, node_fs_1.readSync)(fd, bytes, 0, bytes.length, null)) > 0) {
+            pending += decoder.write(bytes.subarray(0, length));
+            let end;
+            while ((end = pending.indexOf('\n')) >= 0) {
+                parse(pending.slice(0, end));
+                pending = pending.slice(end + 1);
+            }
+        }
+        pending += decoder.end();
+        if (pending.trim())
+            parse(pending);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    return out;
+}
+function parseWindow(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const w = object(value), replay = number(w.replayShare);
+    return { activeMinutes: number(w.activeMinutes), windowActiveMinutes: positive(w.windowActiveMinutes),
+        spawns: number(w.spawns), tokens: number(w.tokens), spawnCeiling: positive(w.spawnCeiling),
+        replayShare: replay !== null && replay <= 1 ? replay : null };
+}
+function decision(raw, sequence) {
+    const sessionId = typeof raw.sessionId === 'string' && raw.sessionId.length ? raw.sessionId : null;
+    const at = number(raw.at), result = verdict(raw.verdict);
+    if (!sessionId || at === null || !Number.isFinite(new Date(at).getTime()) || !result)
+        return null;
+    const findings = Array.isArray(raw.findings) ? raw.findings.map(object) : [];
+    const rate = findings.find(f => f.detector === 'spawn_rate' && number(f.observed) !== null && verdict(f.verdict));
+    const totals = object(raw.totals), coverage = object(raw.coverage), window = parseWindow(raw.window);
+    return { sessionId, sessionDigest: digest(sessionId), sequence, at, verdict: result,
+        id: safe(raw.toolUseId, digest(JSON.stringify(raw)) + ':' + sequence), tool: safe(raw.action ?? raw.tool, 'spawn'),
+        blocked: typeof raw.enforced === 'boolean' ? raw.enforced : null,
+        reason: findings.map(f => `${safe(f.detector, 'unknown')}:${verdict(f.verdict) ?? 'OK'}`).join(' + ')
+            || (raw.failClosed === true ? 'local fail-closed condition' : result === 'OK' ? 'within policy' : 'reason unavailable'),
+        activeMinutes: window?.activeMinutes ?? number(totals.activeMinutes), effectiveSpawns: number(raw.effectiveSpawns),
+        totalSpawns: number(totals.spawns), totalTokens: number(totals.tokens), window,
+        rate: rate ? { observed: Number(rate.observed), threshold: positive(rate.threshold), verdict: verdict(rate.verdict) } : null,
+        usageKnown: known(coverage.usage), spawnsKnown: known(coverage.spawns), legacyPolicy: null };
+}
+function receipt(raw, sequence) {
+    const p = object(raw.payload), at = number(p.at), result = verdict(p.verdict);
+    if (typeof p.sessionDigest !== 'string' || !/^[a-f0-9]{64}$/.test(p.sessionDigest) || at === null || !Number.isFinite(new Date(at).getTime()) || !result)
+        return null;
+    const measured = object(p.measured), coverage = object(p.coverage);
+    return { sessionId: null, sessionDigest: p.sessionDigest, sequence, at, verdict: result,
+        id: safe(p.decisionId, digest(JSON.stringify(p))), tool: safe(p.action, 'unknown'),
+        blocked: typeof p.blocked === 'boolean' ? p.blocked : null,
+        reason: Array.isArray(p.reasons) && p.reasons.length ? [...new Set(p.reasons.map(reason => safe(reason, 'unknown')))].join(' + ') : result === 'OK' ? 'within policy' : 'reason unavailable',
+        activeMinutes: null, effectiveSpawns: number(measured.sessionSpawns), totalSpawns: null, totalTokens: number(measured.sessionTokens),
+        window: parseWindow(p.window), rate: null, usageKnown: known(coverage.usage), spawnsKnown: known(coverage.spawns), legacyPolicy: null };
+}
+/** Join each receipt once. Signed receipt identifiers do not duplicate decisions. */
+function readPanelLedger(home) {
+    const decisions = rows((0, node_path_1.join)(home, 'decisions.ndjson')).flatMap((raw, i) => { const d = decision(raw, i); return d ? [d] : []; });
+    const ids = new Map(decisions.map(d => [d.sessionDigest, d.sessionId]));
+    const policy = (0, policy_1.loadPolicy)(home, { notice: false }), policyDigest = digest((0, receipt_1.canonical)(policy));
+    const matched = new Set();
+    for (const [i, raw] of rows((0, node_path_1.join)(home, 'receipts.ndjson')).entries()) {
+        const r = receipt(raw, decisions.length + i);
+        if (!r)
+            continue;
+        try {
+            if (object(object(raw.payload).policy).digest === policyDigest && (0, receipt_1.verifyReceipt)(raw)) {
+                r.legacyPolicy = { windowActiveMinutes: policy.thresholds.spawnRate.windowActiveMinutes, spawnCeiling: policy.thresholds.spawnRate.stop };
+            }
+        }
+        catch { /* Unverified policy metadata cannot define a historical window. */ }
+        const index = decisions.findIndex((d, j) => !matched.has(j) && d.sessionDigest === r.sessionDigest && d.at === r.at && d.tool === r.tool && d.verdict === r.verdict && d.blocked === r.blocked);
+        if (index >= 0) {
+            decisions[index] = { ...decisions[index], id: r.id, reason: r.reason, blocked: r.blocked, legacyPolicy: r.legacyPolicy };
+            matched.add(index);
+        }
+        else {
+            matched.add(decisions.length);
+            decisions.push({ ...r, sessionId: ids.get(r.sessionDigest) ?? null });
+        }
+    }
+    return decisions.sort((a, b) => a.at - b.at || a.sequence - b.sequence).map((d, sequence) => ({ ...d, sequence }));
+}
+/** Accept full ids or unique raw-id/digest prefixes; never silently pick ambiguity. */
+function resolveLedgerSession(rows, selector) {
+    const sessions = new Map();
+    for (const r of rows)
+        sessions.set(r.sessionDigest, { sessionId: r.sessionId ?? sessions.get(r.sessionDigest)?.sessionId ?? null, sessionDigest: r.sessionDigest });
+    if (!selector) {
+        const latest = rows.at(-1);
+        return latest ? sessions.get(latest.sessionDigest) : undefined;
+    }
+    const all = [...sessions.values()];
+    const exact = all.filter(s => s.sessionId === selector || s.sessionDigest === selector);
+    const matching = exact.length ? exact : all.filter(s => s.sessionId?.startsWith(selector) || s.sessionDigest.startsWith(selector));
+    if (matching.length > 1)
+        throw new Error('Session prefix is ambiguous. Use the full session id or digest.');
+    return matching[0];
+}
+/** Older ledgers can prove a whole-lifetime window, but not an arbitrary token window. */
+function legacySpawns(rows, current, windowMinutes) {
+    if (!current.spawnsKnown)
+        return null;
+    if (current.rate)
+        return current.rate.observed;
+    if (windowMinutes === null || current.activeMinutes === null || current.effectiveSpawns === null || current.tool !== 'spawn')
+        return null;
+    if (Math.floor(current.activeMinutes) <= windowMinutes)
+        return current.effectiveSpawns;
+    const first = rows.find(d => d.tool === 'spawn');
+    if (!first || first.totalSpawns !== 0 || first.effectiveSpawns !== 1 || first.activeMinutes === null)
+        return null;
+    const from = Math.max(0, Math.floor(current.activeMinutes) - windowMinutes);
+    return Math.floor(first.activeMinutes) >= from ? current.effectiveSpawns : null;
+}
+function projectLedgerPanel(rows, selector, at = Date.now()) {
+    const available = rows.filter(d => d.at <= at), session = resolveLedgerSession(available, selector);
+    const defaults = defaults_1.DEFAULT_THRESHOLDS.spawnRate;
+    const base = { session: 'unavailable', startedAt: at, observedAt: at, elapsedMs: null,
+        spawns: null, tokens: null, replayShare: null, windowActiveMinutes: defaults.windowActiveMinutes, spawnCeiling: defaults.stop,
+        decisions: [], note: 'No readable ledger decisions. Waiting for local observations.' };
+    if (!session)
+        return base;
+    const selected = available.filter(d => d.sessionDigest === session.sessionDigest), current = selected.at(-1);
+    const window = current.window, windowMinutes = window?.windowActiveMinutes ?? current.legacyPolicy?.windowActiveMinutes ?? null;
+    const spawns = window ? current.spawnsKnown ? window.spawns : null : legacySpawns(selected, current, windowMinutes);
+    const tokens = current.usageKnown ? window ? window.tokens
+        : windowMinutes !== null && current.activeMinutes !== null && Math.floor(current.activeMinutes) <= windowMinutes ? current.totalTokens : null : null;
+    const decisions = selected.slice(-8).map(({ id, at, tool, verdict, reason, blocked }) => ({ id, at, tool, verdict, reason, blocked }));
+    return { ...base, session: (session.sessionId ?? session.sessionDigest).slice(0, 8), sessionDigest: session.sessionDigest, startedAt: selected[0].at, elapsedMs: at - selected[0].at,
+        spawns, tokens, replayShare: current.usageKnown ? window?.replayShare ?? null : null,
+        windowActiveMinutes: windowMinutes, spawnCeiling: window?.spawnCeiling ?? (current.rate?.verdict === 'STOP' ? current.rate.threshold : null) ?? current.legacyPolicy?.spawnCeiling ?? null,
+        decisions, note: window ? 'Ledger decision snapshot. Counters include the proposal evaluated by the hook.'
+            : `Ledger decisions. ${tokens === null ? 'Token window and replay share were not recorded.' : 'Replay share was not recorded.'}${spawns === null ? ' Spawn window is unknown.' : ''}${current.legacyPolicy ? ' Policy digest verified.' : ''}` };
+}

package/dist/src/live-panel.d.ts

@@ -11,8 +11,14 @@ export interface PanelDecision {
 }
 export interface LivePanelSnapshot {
     session: string;
+    sessionDigest?: string;
     startedAt: number;
     observedAt: number;
+    sessionSwitch?: {
+        from: string;
+        to: string;
+        at: number;
+    };
     spawns: number | null;
     tokens: number | null;
     replayShare: number | null;
@@ -25,8 +31,14 @@ export interface LivePanelSnapshot {
     note: string;
     stop?: PanelDecision;
 }
+/** The ledger is the single source for decisions, counters and session selection. */
 export declare function panelDecisions(home: string, sessionId: string, at?: number): PanelDecision[];
 export declare function collectLivePanel(home: string, session?: string, now?: number): LivePanelSnapshot;
+/** Record changes of identity, including switches between sessions with the same short prefix. */
+export declare class SessionFollow {
+    private previous?;
+    update(snapshot: LivePanelSnapshot, now: number): LivePanelSnapshot;
+}
 export declare function spawnBarColor(spawns: number | null, ceiling: number | null): CanvasColor;
 export declare function renderLivePanel(snapshot: LivePanelSnapshot, options?: FrameOptions): Canvas;
 /** STOP report adaptation uses only already-computed metadata, never local I/O. */

package/dist/src/live-panel.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StopHold = void 0;
+exports.StopHold = exports.SessionFollow = void 0;
 exports.panelDecisions = panelDecisions;
 exports.collectLivePanel = collectLivePanel;
 exports.spawnBarColor = spawnBarColor;
@@ -10,116 +10,29 @@ exports.runLivePanel = runLivePanel;
 /** Local, content-free instrument panel. It observes; it never changes admission. */
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
 const canvas_1 = require("./canvas");
-const policy_1 = require("./policy");
+const ledger_panel_1 = require("./ledger-panel");
 const recording_1 = require("./recording");
-const session_1 = require("./state/session");
 const digest = (text) => (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
-const number = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
-const row = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
-const safe = (v, fallback) => typeof v === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(v) ? v : fallback;
-const verdict = (v) => v === 'OK' || v === 'WARN' || v === 'STOP' ? v : null;
-function buckets(value) {
-    if (!Array.isArray(value) || !value.every(v => Array.isArray(v) && v.length === 2 && number(v[0]) !== null && number(v[1]) !== null))
-        return null;
-    return new Map(value);
-}
-/** Read a bounded tail and discard an incomplete first/last JSON row. */
-function ledger(file) {
-    try {
-        const size = (0, node_fs_1.statSync)(file).size, offset = Math.max(0, size - 4 * 1024 * 1024), fd = (0, node_fs_1.openSync)(file, 'r');
-        const bytes = Buffer.alloc(size - offset);
-        try {
-            (0, node_fs_1.readSync)(fd, bytes, 0, bytes.length, offset);
-        }
-        finally {
-            (0, node_fs_1.closeSync)(fd);
-        }
-        const text = bytes.toString('utf8'), lines = text.slice(offset ? text.indexOf('\n') + 1 : 0, text.lastIndexOf('\n') + 1).split('\n');
-        return lines.flatMap(line => { try {
-            return [row(JSON.parse(line))];
-        }
-        catch {
-            return [];
-        } });
-    }
-    catch {
-        return [];
-    }
-}
+/** The ledger is the single source for decisions, counters and session selection. */
 function panelDecisions(home, sessionId, at = Date.now()) {
-    const sessionDigest = digest(sessionId);
-    const receiptRows = ledger((0, node_path_1.join)(home, 'receipts.ndjson')).flatMap(raw => {
-        const p = row(raw.payload);
-        if (p.sessionDigest !== sessionDigest || number(p.at) === null || Number(p.at) > at || !verdict(p.verdict))
-            return [];
-        return [{ id: safe(p.decisionId, digest(JSON.stringify(p))), at: Number(p.at), tool: safe(p.action, 'unknown'), verdict: verdict(p.verdict),
-                reason: Array.isArray(p.reasons) ? [...new Set(p.reasons.map(v => safe(v, 'unknown')))].join(' + ') : 'reason unavailable', blocked: p.blocked === true }];
-    });
-    const decisions = ledger((0, node_path_1.join)(home, 'decisions.ndjson')).flatMap(p => {
-        if (p.sessionId !== sessionId || number(p.at) === null || Number(p.at) > at || !verdict(p.verdict))
-            return [];
-        const findings = Array.isArray(p.findings) ? p.findings.map(row) : [];
-        return [{ id: safe(p.toolUseId, digest(JSON.stringify(p))), at: Number(p.at), tool: safe(p.action ?? p.tool, 'spawn'), verdict: verdict(p.verdict),
-                reason: findings.map(f => `${safe(f.detector, 'unknown')}:${verdict(f.verdict) ?? 'OK'}`).join(' + ') || (p.failClosed === true ? 'local fail-closed condition' : p.verdict === 'OK' ? 'within policy' : 'reason unavailable'), blocked: p.enforced === true }];
-    });
-    const merged = [...decisions], joined = new Set();
-    for (const d of receiptRows) {
-        const index = merged.findIndex((candidate, i) => !joined.has(i) && candidate.at === d.at && candidate.tool === d.tool && candidate.verdict === d.verdict && candidate.blocked === d.blocked);
-        if (index >= 0) {
-            merged[index] = d;
-            joined.add(index);
-        }
-        else {
-            joined.add(merged.length);
-            merged.push(d);
-        }
-    }
-    return merged.sort((a, b) => a.at - b.at).slice(-8);
+    return (0, ledger_panel_1.projectLedgerPanel)((0, ledger_panel_1.readPanelLedger)(home), sessionId, at).decisions;
 }
 function collectLivePanel(home, session, now = Date.now()) {
-    const policy = (0, policy_1.loadPolicy)(home, { notice: false });
-    const configured = policy.thresholds.spawnRate;
-    const windowActiveMinutes = number(configured?.windowActiveMinutes) || 15, spawnCeiling = number(configured?.stop) || 16;
-    const base = { session: 'unavailable', startedAt: now, observedAt: now, spawns: null, tokens: null, replayShare: null,
-        windowActiveMinutes, spawnCeiling, decisions: [], note: 'No readable session state. Waiting for local observations.' };
-    let names;
-    try {
-        names = (0, node_fs_1.readdirSync)((0, node_path_1.join)(home, 'sessions')).filter(name => name.endsWith('.json'));
-    }
-    catch {
-        return base;
+    return (0, ledger_panel_1.projectLedgerPanel)((0, ledger_panel_1.readPanelLedger)(home), session, now);
+}
+/** Record changes of identity, including switches between sessions with the same short prefix. */
+class SessionFollow {
+    previous;
+    update(snapshot, now) {
+        const identity = snapshot.sessionDigest ?? snapshot.session;
+        const sessionSwitch = this.previous !== undefined && this.previous !== identity
+            ? { from: this.previous, to: identity, at: now } : undefined;
+        this.previous = identity;
+        return { ...snapshot, ...(sessionSwitch ? { sessionSwitch } : {}) };
     }
-    const candidates = names.flatMap(name => {
-        try {
-            const path = (0, node_path_1.join)(home, 'sessions', name);
-            if ((0, node_fs_1.statSync)(path).size > 16 * 1024 * 1024)
-                return [];
-            const raw = row(JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'))), state = row(raw.state);
-            if (typeof state.sessionId !== 'string' || number(state.lastEventAt) === null || number(state.startedAt) === null)
-                return [];
-            if (session && state.sessionId !== session && !state.sessionId.startsWith(session) && !digest(state.sessionId).startsWith(session))
-                return [];
-            return [{ raw, state }];
-        }
-        catch {
-            return [];
-        }
-    }).sort((a, b) => Number(b.state.lastEventAt) - Number(a.state.lastEventAt));
-    if (!candidates.length)
-        return base;
-    const { raw, state } = candidates[0], active = number(state.activeMinutes), spawned = buckets(state.spawnsByActiveMinute), tokens = buckets(state.tokensByActiveMinute);
-    const total = number(state.totalTokens), cached = number(state.totalCacheRead), decisions = panelDecisions(home, String(state.sessionId), now);
-    const coverage = row(raw.capabilities), gateway = Array.isArray(raw.hosts);
-    const spawnKnown = !gateway || ['authoritative', 'estimated'].includes(String(coverage.spawns));
-    const usageKnown = !gateway || ['authoritative', 'estimated'].includes(String(coverage.usage));
-    return { ...base, session: digest(String(state.sessionId)).slice(0, 8), startedAt: Number(state.startedAt),
-        spawns: spawnKnown && spawned && active !== null ? (0, session_1.windowSum)(spawned, active, windowActiveMinutes) : null,
-        tokens: usageKnown && tokens && active !== null ? (0, session_1.windowSum)(tokens, active, windowActiveMinutes) : null,
-        replayShare: usageKnown && total !== null && cached !== null && total > 0 ? Math.min(1, cached / total) : null, decisions,
-        note: row(raw.cursor).usageVersion === undefined && raw.cursor ? 'Legacy stored usage counts; no recount applied.' : gateway ? `Local observations. Coverage: spawns ${safe(coverage.spawns, 'unknown')}, usage ${safe(coverage.usage, 'unknown')}.` : 'Local observations only. Replay share is session cache-read / tokens.' };
 }
+exports.SessionFollow = SessionFollow;
 const compact = (v) => v === null ? { digits: '-', unit: 'unknown' } : v >= 1e9 ? { digits: (v / 1e9).toFixed(2), unit: 'B tokens' } : v >= 1e6 ? { digits: (v / 1e6).toFixed(2), unit: 'M tokens' } : v >= 1e3 ? { digits: (v / 1e3).toFixed(1), unit: 'K tokens' } : { digits: String(Math.round(v)), unit: 'tokens' };
 function spawnBarColor(spawns, ceiling) {
     return spawns === null || ceiling === null ? 'slate' : spawns >= ceiling ? 'red' : spawns >= ceiling * .8 ? 'amber' : 'mint';
@@ -178,7 +91,7 @@ function panelFromReport(report, at, outcome, subject) {
     const note = outcome === 'blocked' ? (subject === 'call' ? 'model call blocked' : 'agent spawn blocked')
         : outcome === 'shadow' ? 'shadow: would have blocked, call allowed' : outcome === 'overridden' ? 'override: call allowed'
             : outcome === 'allowed' ? 'call allowed' : 'STOP boundary · enforcement outcome not recorded';
-    return { session: digest(report.sessionId).slice(0, 8), startedAt: at, observedAt: at, elapsedMs: null, controls: false, stopHold: false,
+    return { session: (/^[A-Za-z0-9_-]+$/.test(report.sessionId) ? report.sessionId : digest(report.sessionId)).slice(0, 8), startedAt: at, observedAt: at, elapsedMs: null, controls: false, stopHold: false,
         spawns: rate?.observed ?? null, tokens: null, replayShare: Number.isFinite(report.cacheReadRatio) ? report.cacheReadRatio : null,
         windowActiveMinutes: null, spawnCeiling: rate?.verdict === 'STOP' ? rate.threshold : null,
         decisions: [decision], stop: decision, note: `${note}. Unknown window metrics remain unknown.` };
@@ -190,8 +103,15 @@ class StopHold {
     seen = new Set();
     latest;
     update(snapshot, now) {
+        if (this.latest && (this.latest.sessionDigest ?? this.latest.session) !== (snapshot.sessionDigest ?? snapshot.session)) {
+            this.held = undefined;
+            this.until = 0;
+            this.seen.clear();
+        }
         this.latest = snapshot;
-        const stop = snapshot.decisions.filter(d => d.verdict === 'STOP' && !this.seen.has(d.id)).at(-1);
+        // A historical STOP in the right column must not borrow a later decision's counters.
+        const latestDecision = snapshot.decisions.at(-1);
+        const stop = latestDecision?.verdict === 'STOP' && !this.seen.has(latestDecision.id) ? latestDecision : undefined;
         for (const decision of snapshot.decisions)
             this.seen.add(decision.id);
         if (stop) {
@@ -260,10 +180,10 @@ async function runLivePanel(home, args) {
             }
         }
         else {
-            const hold = new StopHold();
+            const hold = new StopHold(), follow = new SessionFollow();
             do {
                 if (!paused) {
-                    const now = Date.now(), snapshot = hold.update(collectLivePanel(home, selected, now), now);
+                    const now = Date.now(), snapshot = follow.update(hold.update(collectLivePanel(home, selected, now), now), now);
                     display(snapshot, false, new Date(now).toISOString());
                 }
                 if (!once)

package/dist/src/record-ledger.d.ts

@@ -0,0 +1,30 @@
+import { type LedgerDecision } from './ledger-panel';
+import type { RecordedFrame } from './recording';
+export interface RecordLedgerOptions {
+    session: string;
+    from?: string;
+    to?: string;
+    out: string;
+}
+export interface RecordLedgerResult {
+    output: string;
+    session: string;
+    from: string;
+    to: string;
+    frameCount: number;
+    decisionCount: number;
+    clippedStopHold: boolean;
+}
+/** Require an explicit timezone and reject dates Date.parse would normalize. */
+export declare function ledgerTimestamp(value: string): number;
+export declare function validateCompanionRecording(home: string, output: string, recording: string): void;
+export declare function recordLedgerArguments(args: string[]): RecordLedgerOptions;
+export declare function reconstructLedgerFrames(rows: LedgerDecision[], options: Omit<RecordLedgerOptions, 'out'>): {
+    frames: RecordedFrame[];
+    session: string;
+    from: number;
+    to: number;
+    decisionCount: number;
+    clippedStopHold: boolean;
+};
+export declare function recordLedger(home: string, options: RecordLedgerOptions): RecordLedgerResult;