instar 0.28.76 → 0.28.77

package/upgrades/side-effects/threadline-canonical-inbox-write.md

@@ -0,0 +1,218 @@
+# Side-Effects Review — Threadline Canonical Inbox Write at Relay-Ingest
+
+**Version / slug:** `threadline-canonical-inbox-write`
+**Date:** `2026-05-02`
+**Author:** `echo`
+**Second-pass reviewer:** `self (incident-grounded reasoning)`
+
+## Summary of the change
+
+The threadline relay handler in `src/commands/server.ts` (`gate-passed`
+event listener) had three routing branches — pipe-mode (`PipeSessionSpawner`),
+warm-listener (`ListenerSessionManager.writeToInbox`), and cold-spawn
+(`ThreadlineRouter.handleInboundMessage`). Only the warm-listener branch
+wrote to a per-rotation queue file (`state/listener-inbox-{rotation}.jsonl`);
+none of the three branches wrote to the **canonical** threadline inbox at
+`.instar/threadline/inbox.jsonl.active`. As a result the canonical inbox
+file was frozen since 2026-04-05, hiding ~4 weeks of inbound traffic from
+the dashboard, observability, and any consumer that reads the canonical
+file (e.g. the planned threadline → telegram bridge).
+
+This change adds a single canonical-inbox append at relay-ingest, BEFORE
+the pipe / listener / cold-spawn branching, so all three paths agree on
+one source of truth. The hoist runs through a new
+`ListenerSessionManager.appendCanonicalInboxEntry()` helper that writes
+HMAC-signed entries to `threadline/inbox.jsonl.active` using the same
+HKDF-derived signing key the daemon and warm-listener already share —
+no key divergence, no ambient-key footgun.
+
+Files modified:
+
+- `src/threadline/ListenerSessionManager.ts` — adds
+  `canonicalInboxPath` getter and `appendCanonicalInboxEntry(opts)` method.
+  The new method writes to the canonical inbox path; it does NOT write
+  the wake sentinel (the warm-listener queue and its sentinel remain a
+  separate, listener-only concern).
+- `src/commands/server.ts` — in the `gate-passed` event handler, after
+  auto-ack and BEFORE the pipe / listener / cold-spawn branching, calls
+  `listenerManager.appendCanonicalInboxEntry({ ... })` once. Wrapped in
+  try/catch with a non-fatal warn — routing continues even if the
+  canonical append fails, preserving message liveness over auditability.
+
+Tests added: 6 new unit cases in
+`tests/unit/ListenerSessionManager.test.ts > canonical inbox`:
+
+1. `canonicalInboxPath` getter returns `threadline/inbox.jsonl.active`
+2. `appendCanonicalInboxEntry` creates the directory on first write and
+   appends a parseable JSON line with the right fields
+3. The HMAC of a canonical entry round-trips through the existing
+   `verifyEntry()` — proves daemon/listener/relay share one signing key
+4. Multiple appends produce multiple lines in chronological order
+5. An optional caller-supplied `messageId` is honored as the entry id
+6. The canonical inbox file is created with `0o600` permissions
+
+Local result: 45/46 pass; the 1 failing case
+(`state management > starts in dead state`) is a pre-existing failure
+documented in prior `instar-dev` traces (e.g.
+`2026-04-27T15-50-00Z-telegram-delivery-robustness-layer-3.json`) and
+unrelated to this change.
+
+## Decision-point inventory
+
+- `ListenerSessionManager.appendCanonicalInboxEntry` — **add** — pure
+  canonical-inbox append, no wake sentinel.
+- `ListenerSessionManager.canonicalInboxPath` — **add** — getter for the
+  canonical inbox path, kept side-by-side with `inboxPath` (warm-listener
+  queue) so the two roles are visibly distinct in the API surface.
+- `gate-passed` handler in `server.ts` — **modify** — runs canonical
+  append once, before any branching. No change to pipe-mode, warm-listener,
+  or cold-spawn routing decisions or behavior.
+- HMAC key — **pass-through** — the new helper uses the same HKDF-derived
+  signing key (`info: 'instar-inbox-signing'`) that
+  `writeToInbox` and the listener daemon already use; no new key, no new
+  derivation parameter.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None. The hoist is a relay (write-only), not a gate. It does not block,
+delay, or filter messages. Routing decisions — pipe vs warm vs cold-spawn —
+are unchanged. Auto-ack timing is unchanged. The canonical write happens
+synchronously in the same event handler, on the same Node.js event loop,
+adding a single `appendFileSync` call — no I/O contention with the routing
+branches that follow.
+
+The append is wrapped in try/catch with a non-fatal warning. If the
+canonical write fails (disk full, permission error, etc.), the message
+still routes through pipe / listener / cold-spawn as it does today.
+Liveness is preserved over auditability when those two are in tension.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Failure-open on canonical-inbox write.** A disk error during
+  `appendFileSync` produces a single warn line and the message routes
+  normally. The canonical inbox loses that entry. Acceptable: the same
+  behavior is already in place for the warm-listener `writeToInbox` and
+  for the daemon's `writeInboxEntry` — none of them block routing on
+  inbox-write failure. The canonical inbox is an audit / observability
+  surface, not a gate.
+- **Pre-existing freeze (Apr 5 → May 1).** Backfilling the missing
+  ~4 weeks of inbound messages is OUT OF SCOPE for this PR — that's
+  deliverable (c) in the topic-8686 build (separate PR, separate review).
+  This PR fixes the write-path going forward; (c) reconstructs the
+  history from spawn-session transcripts and the thread-resume map.
+- **Listener daemon path (`listener-daemon.ts`) still bypasses this code
+  path.** The daemon connects to the relay independently and has its own
+  `writeInboxEntry` that already targets the canonical file. This PR
+  does NOT alter the daemon. When the daemon is the active relay
+  consumer, it continues to write canonically as it does today; when the
+  in-process relay client (server.ts handler) is the consumer, the new
+  hoist takes care of canonical writes. Both paths converge on the same
+  file with the same HMAC key.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The relay handler is the natural choke point: it is the single
+function in the in-process relay consumer that sees every inbound
+message exactly once before any routing decision. Doing the canonical
+write here — rather than inside each routing branch — is the
+single-source-of-truth pattern the spec calls for.
+
+The helper lives on `ListenerSessionManager` because that class already
+owns the HMAC key derivation and the existing `writeToInbox` + `verifyEntry`
+methods. Adding a sibling method that targets the canonical path keeps
+the key derivation, HMAC computation, and entry shape in one place.
+A future refactor could extract a separate `CanonicalInboxWriter` class,
+but the cost-of-now (one new method, ~30 LoC, one new getter) is lower
+than the cost-of-extraction (new class, dependency wiring, test scaffolding).
+
+## 4. Signal-vs-authority compliance
+
+**Where is the signal? Where is the authority?**
+
+- **Signal:** the inbound `gate-passed` event itself, which has already
+  been authorized by `InboundMessageGate`. The canonical append is a
+  pure observation of that signal — write-once, append-only, no decision
+  surface.
+- **Authority:** unchanged. The pipe / warm-listener / cold-spawn
+  routing decision still lives in `server.ts` (and downstream in
+  `PipeSessionSpawner.shouldUsePipeMode`, `ListenerSessionManager.shouldUseListener`,
+  `ThreadlineRouter.handleInboundMessage`). The canonical inbox does not
+  gate, throttle, or veto routing.
+
+The split passes the signal-vs-authority memory test: a brittle/low-context
+write path (the canonical append) emits a signal; the higher-level
+intelligent gate (already-existing `InboundMessageGate` upstream of the
+`gate-passed` event) holds the blocking authority.
+
+## 5. Interactions
+
+**What other systems does this touch?**
+
+- **Warm-listener queue (`state/listener-inbox-{rotation}.jsonl`).** No
+  change. The warm-listener path still calls `writeToInbox` which writes
+  to the rotated per-listener file AND the wake sentinel. Both files
+  coexist: canonical = audit/observability/bridge source; rotated =
+  warm-listener queue.
+- **Listener daemon (`listener-daemon.ts`).** No change. The daemon's
+  `writeInboxEntry` already targets the canonical file. After this PR,
+  there are exactly two writers to the canonical file — the daemon (for
+  the standalone-listener mode) and the in-process relay handler (for
+  the in-server mode). They are mutually exclusive at runtime: only one
+  is the active relay consumer at a time.
+- **Threadline → Telegram bridge (deliverable b, future PR).** This PR
+  is a precondition. The bridge reads the canonical inbox to know which
+  messages to mirror into Telegram; without this fix, the bridge would
+  see no traffic on the cold-spawn or pipe paths. After this PR the
+  bridge has a complete signal stream.
+- **Dashboard observability tab (deliverable 4, future PR).** Same: the
+  observability tab reads the canonical inbox and the thread-resume map.
+  This PR ensures the canonical inbox is actually populated.
+
+## 6. Rollback cost
+
+**How easy is it to undo this if it breaks something in production?**
+
+Trivially easy. The change is two surgical additions:
+
+1. A new method + getter on `ListenerSessionManager` (no callers in
+   tests or production reference it except the new test file and the
+   new `server.ts` call site).
+2. A 13-line block in `server.ts` that is fully wrapped in `if (listenerManager)`
+   and `try/catch`. Removing that block restores the prior behavior
+   exactly.
+
+No schema migrations, no new file format, no new key material, no
+dashboard changes. The canonical inbox file is append-only JSONL — if a
+subsequent change wants to drop the entries, `rm` the file (or rotate
+it). No referential integrity to unwind.
+
+## Plan if a regression appears
+
+- **Symptom: routing latency increases.** Profile the `appendFileSync`
+  call. The canonical inbox is local-filesystem JSONL; on macOS APFS
+  / ext4 / xfs the syscall is sub-millisecond. If unexpectedly slow,
+  hoist into a `setImmediate` so the routing branches run first.
+- **Symptom: canonical inbox file grows unboundedly.** Same growth rate
+  as the warm-listener queue's rotation cycle — so we already know the
+  steady-state. If growth is a problem, add a rotation policy mirroring
+  the listener's (compaction at N messages, archive on rotation).
+- **Symptom: HMAC verification fails for canonical entries.** The signing
+  key comes from the same HKDF derivation as `writeToInbox` and
+  `loadSigningKey` — verified by the round-trip unit test. If a real
+  failure shows up, look for an authToken mismatch between processes.
+
+## Phase / scope
+
+This is the FIRST of five deliverables in topic-8686 (Threadline → Telegram
+Bridge). Subsequent deliverables — dashboard settings, bridge module,
+observability tab, and four-thread backfill — depend on this canonical
+write-path being live. Each will ship as its own PR with its own
+side-effects review.

package/upgrades/side-effects/threadline-tg-bridge-settings-surface.md

@@ -0,0 +1,208 @@
+# Side-Effects Review — Threadline → Telegram Bridge: Settings Surface
+
+**Version / slug:** `threadline-tg-bridge-settings-surface`
+**Date:** `2026-05-02`
+**Author:** `echo`
+**Second-pass reviewer:** `self (incident-grounded reasoning)`
+
+## Summary of the change
+
+Ships the **settings surface** for the Threadline → Telegram bridge BEFORE
+the bridge module itself (deliverable b) goes live. This is the second of
+five deliverables in the topic-8686 build; it ensures default-OFF
+auto-create is structurally enforced from day one, so when (b) lights up
+the bridge, the user's noise budget is already wired and respected.
+
+The settings surface is three layers:
+
+1. **`TelegramBridgeConfig` class** — a thin, validated read/write API over
+   `LiveConfig` keys under `threadline.telegramBridge.*`. Owns the policy
+   functions `shouldAutoCreateTopic(remoteAgent)` and
+   `shouldMirrorIntoExistingTopic()` that the bridge module will call on
+   every inbound/outbound message.
+2. **HTTP endpoints** — `GET /threadline/telegram-bridge/config` and
+   `PATCH /threadline/telegram-bridge/config`, mounted in the main route
+   set (bearer-auth enforced globally). Validation lives in the config
+   class; the route handler is a 14-line wrapper.
+3. **Dashboard tab** — a new "Threadline" tab with a Bridge Settings card:
+   master switch, two policy toggles, and dual allow/deny-list management.
+   The same tab is the natural home for deliverable (4)'s observability
+   view; this PR ships a placeholder noting that.
+
+Files added:
+
+- `src/threadline/TelegramBridgeConfig.ts` — config class + `shouldAutoCreateTopic`, `shouldMirrorIntoExistingTopic` policies.
+- `tests/unit/TelegramBridgeConfig.test.ts` — 22 unit cases.
+- `tests/integration/telegram-bridge-config-routes.test.ts` — 8 supertest cases.
+
+Files modified:
+
+- `src/server/routes.ts` — `RouteContext.telegramBridgeConfig: TelegramBridgeConfig | null` + two routes.
+- `src/server/AgentServer.ts` — accepts `options.telegramBridgeConfig`, passes through `routeCtx`.
+- `src/commands/server.ts` — instantiates `new TelegramBridgeConfig(liveConfig)` once at boot, hands it to `AgentServer`.
+- `dashboard/index.html` — new Threadline tab (button + panel + load/patch/render JS + tab-registry entry).
+
+## Decision-point inventory
+
+- `TelegramBridgeConfig.update(patch)` — **add** — partial-patch
+  application with type validation; emits `change` events per field.
+- `TelegramBridgeConfig.shouldAutoCreateTopic(remoteAgent)` — **add** —
+  policy: `enabled && (allowList match → true; denyList match → false; else autoCreateTopics)`.
+- `TelegramBridgeConfig.shouldMirrorIntoExistingTopic()` — **add** —
+  policy: `enabled && mirrorExisting`.
+- `GET /threadline/telegram-bridge/config` — **add** — read endpoint
+  (bearer-auth via global `authMiddleware`).
+- `PATCH /threadline/telegram-bridge/config` — **add** — partial-patch
+  endpoint with 400 on validation error and 503 when config not initialized.
+- Dashboard `loadThreadlineBridgeConfig` / `tlBridgePatchConfig` — **add** —
+  load + optimistic write; rolls back via re-load on 4xx.
+- Toggle change-handlers — **add** — bound once on `DOMContentLoaded` with
+  a `tlBridgeWiring` reentrancy guard (avoids feeding back the
+  programmatic `checked = ...` set into the change event).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The settings class deliberately rejects non-boolean toggles and non-string
+list entries with a 400. The error messages name the offending field
+("enabled must be boolean", "allowList must be string[]"). False positives
+are not possible at the type level: a JSON `true`/`false` is unambiguous,
+and a JSON array of strings is unambiguous. The dashboard cannot send
+malformed input — `<input type="checkbox">.checked` is always a boolean
+and the list-management code stringifies entries.
+
+The PATCH endpoint **ignores unknown fields silently** (the route filters
+the body to known fields before forwarding to `update`). This is
+intentional: future toggles can be deployed server-side without breaking
+older dashboards that don't know about them. There is a unit test for
+this exact behaviour.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No rate-limit on PATCH.** A pathological dashboard could thrash
+  toggles. The cost is bounded — each PATCH writes config.json
+  atomically; throughput is disk-bound, not unbounded. Acceptable for a
+  bearer-auth-gated endpoint with one user.
+- **No audit log on config changes.** A future PR could forward the
+  `change` events from `TelegramBridgeConfig` into the existing event
+  stream, but it's out of scope for this deliverable. Today, config
+  changes show up in `config.json` git history (or backup snapshots).
+- **The `enabled` master switch is still load-bearing for the bridge
+  module that doesn't exist yet.** This PR does NOT enforce default-OFF
+  in any code path that mirrors messages — it only persists the toggles.
+  Enforcement happens in deliverable (b), where the bridge module calls
+  `shouldAutoCreateTopic` and `shouldMirrorIntoExistingTopic` at every
+  routing decision. The unit tests for those two functions in this PR
+  pin the policy contract so (b) cannot drift.
+- **Validation does not deduplicate trailing-whitespace in arbitrary
+  Unicode whitespace.** `dedupeAndTrim` uses `.trim()` (ASCII whitespace
+  + Unicode whitespace per ECMAScript). Acceptable.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The split between class (validation + policy), routes (thin HTTP
+shim), and dashboard (presentation only) is the standard
+"signal-vs-authority" shape: brittle low-context surfaces (the dashboard
+checkboxes) emit signals; the higher-level intelligent gate
+(`TelegramBridgeConfig.update` + the policy functions) holds the
+blocking authority.
+
+The settings class lives under `src/threadline/` because it's a
+threadline-specific feature; placing it in `src/config/` would conflate
+it with the generic `LiveConfig`. The bridge module in deliverable (b)
+will instantiate this class — it does NOT instantiate `LiveConfig`
+directly, which keeps key naming centralized.
+
+## 4. Signal-vs-authority compliance
+
+- **Signal:** dashboard checkbox toggles, dashboard list inputs, REST
+  PATCH bodies. Each is a low-context request that "wants" something to
+  change.
+- **Authority:** `TelegramBridgeConfig.update` is the single chokepoint
+  that validates types, dedupes lists, and writes to config.json. The
+  bridge module (b) will read its decisions through `shouldAutoCreateTopic`
+  and `shouldMirrorIntoExistingTopic` — both pure functions of the
+  current settings.
+
+The bridge module itself, when it ships, will be **relay-only** (no
+block/allow surface). The blocking authority for noise control lives
+exactly here, in the config policy. This separation is the
+signal-vs-authority memory pattern applied correctly: the bridge
+forwards messages it sees; the config class decides what gets seen.
+
+## 5. Interactions
+
+- **`LiveConfig`.** All reads and writes go through the existing
+  `LiveConfig.get` / `.set` API. No new file format, no new mtime
+  watcher, no new poll. Atomic write semantics are inherited.
+- **`config.json` schema.** The new keys `threadline.telegramBridge.*`
+  are namespaced under the existing `threadline` block. Older agents
+  without these keys read the documented defaults (defined in
+  `DEFAULT_TELEGRAM_BRIDGE_SETTINGS`). No migration needed.
+- **Bridge module (deliverable b, future PR).** Will instantiate
+  `TelegramBridgeConfig` from `liveConfig` and call the policy functions.
+  This PR pins the contract via unit tests so (b) cannot accidentally
+  deliver while `enabled=false` or while a remote agent is in the deny
+  list.
+- **Observability tab (deliverable 4, future PR).** Will share the same
+  Threadline dashboard tab and extend the panel HTML; the bridge
+  settings card stays put.
+- **Bearer-auth via `authMiddleware`.** Both routes are
+  globally-authenticated. No change to auth wiring.
+
+## 6. Rollback cost
+
+**How easy is it to undo this if it breaks something in production?**
+
+Trivially. The change is purely additive:
+
+- Drop the new `TelegramBridgeConfig` class file → no callers in
+  production code (only the new server.ts instantiation + the new
+  routes use it).
+- Drop the two routes → unauthenticated GET still 503's elsewhere; the
+  dashboard tab silently fails on `loadThreadlineBridgeConfig`.
+- Drop the dashboard tab + JS → no regression elsewhere; other tabs
+  unaffected.
+- The new `config.json` keys are silently ignored by older agents — no
+  schema migration to unwind.
+
+No file format changes, no shared-state changes, no new processes, no
+new sockets. The PR is a pure "API + UI for not-yet-shipped feature"
+shape — the safest possible kind of change.
+
+## Plan if a regression appears
+
+- **Symptom: dashboard tab errors.** Check `apiFetch` logs in the browser
+  console; verify the bridge config endpoints return 200 from the agent
+  server; verify auth token is correct.
+- **Symptom: toggle change feeds back into a loop.** The
+  `tlBridgeWiring` reentrancy guard skips the change handler while
+  `renderThreadlineBridgeConfig` is programmatically setting `.checked`.
+  If a regression escapes the guard, log the toggle source — DOM
+  `change` events are synchronous, so the guard works as long as the
+  programmatic set is followed by `tlBridgeWiring = false` in a
+  `try/finally`.
+- **Symptom: config.json gets a stray key.** The `update` method only
+  writes the five known keys; no caller has a path to write something
+  else. If junk appears, suspect manual editing.
+
+## Phase / scope
+
+Second of five deliverables in topic-8686. Order:
+
+1. (a) Canonical inbox write-path fix — **MERGED** as PR #113 (commit `9cc3e9af`).
+2. **(2) Settings surface — THIS PR.** Default-OFF auto-create, allow/deny list, dashboard tab.
+3. (b) Bridge module — reads this config, mirrors threadline messages.
+4. (4) Observability tab — extends the Threadline dashboard tab.
+5. (c) Backfill four open threads — one-shot script.
+
+Subsequent deliverables (b, 4, c) all depend on this settings contract.
+The 22 unit tests + 8 integration tests pin the contract so they cannot
+drift as the bridge module is built.

package/upgrades/side-effects/token-ledger-phase1.md

@@ -0,0 +1,123 @@
+# Side-Effects Review — Token Ledger (Phase 1, read-only observability)
+
+**Version / slug:** `token-ledger-phase1`
+**Date:** 2026-04-29
+**Author:** echo
+**Second-pass reviewer:** not required (no decision points; see Q4)
+
+## Summary of the change
+
+Adds a read-only token-usage ledger as a core instar feature. Every agent now tails Claude Code's per-session JSONL files at `~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl`, parses each `assistant` line's `message.usage` block, and records token counts to a SQLite DB at `<stateDir>/server-data/token-ledger.db`. Four new GET endpoints (`/tokens/summary`, `/tokens/sessions`, `/tokens/by-project`, `/tokens/orphans`) expose rollups, and a new "Tokens" dashboard tab renders the data.
+
+Files touched:
+- `src/monitoring/TokenLedger.ts` (new) — SQLite schema + ingest + query methods
+- `src/monitoring/TokenLedgerPoller.ts` (new) — 60s tick wrapping `scanAll()`
+- `src/server/AgentServer.ts` — wires ledger into route context, starts/stops the poller
+- `src/server/routes.ts` — adds the four GET endpoints under existing auth middleware
+- `dashboard/index.html` — adds "Tokens" tab
+- `tests/unit/token-ledger.test.ts` (new) — 12 unit tests
+
+The change interacts with no decision points. The ledger does not gate, block, filter, or alter any agent behavior; it is pure observability.
+
+## Decision-point inventory
+
+The change has no decision-point surface. There is no block/allow logic, no message filtering, no session-lifecycle mutation, no dispatcher, sentinel, gate, or watchdog. The "orphans" endpoint returns a list of idle sessions as data — it does not act on them.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is observability infrastructure, not a decision point. It belongs at the same layer as other monitors in `src/monitoring/` (e.g. `QuotaTracker`, `TelemetryCollector`). It does not duplicate any existing primitive: there is no other instar feature reading Claude Code's per-call JSONL token data — `QuotaTracker` reads a separately-written quota state file, which is a different signal (account-level limit usage) at a different cadence.
+
+The dashboard tab piggybacks on existing `TAB_REGISTRY` + `apiFetch` patterns rather than introducing a new framework. Storage uses the existing `<stateDir>/server-data/<name>.db` convention established by `StopGateDb`.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The ledger is pure read-side observability. Every output is data-for-the-user, never an automated decision. The "orphans" view is explicitly a *signal* (here are sessions idle > N minutes) with no authority to act on the signal. Any future kill-orphan automation, budget enforcement, or compaction trigger would be a separate change with its own review — and per the principle, the orphan list would feed an LLM-backed authority, not become its own brittle blocker.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** None. The ledger reads files Claude Code writes; it does not stand in front of any existing read path. The new routes are under `/tokens/*` — a fresh prefix, no overlap with existing routes.
+- **Double-fire:** None. The poller has a reentry guard (skips a tick if the previous one is still running). Multiple agents on one machine each maintain their own ledger DB under their own state dir, so they don't race on the SQLite file. They DO each scan the same `~/.claude/projects/` tree, but they only read it; the source files are never mutated.
+- **Races:** The ledger writes only to its own DB. `INSERT OR IGNORE` on `request_id` makes ingest idempotent, so even if a file is partially read by one tick and re-read by the next (offset semantics), no double-counting can occur. File-rotation handling resets offset when inode changes.
+- **Feedback loops:** None. The ledger is downstream of Claude Code's logging; it cannot influence what gets logged. It does not call any LLM, does not emit messages, does not write to any path Claude Code reads.
+
+One subtle interaction worth naming: per-line ingest uses an explicit `BEGIN`/`COMMIT` per file. If the process is killed mid-file, the offset for that file is not advanced, so on next startup the file will be re-read from the prior offset — `INSERT OR IGNORE` makes that safe. Verified by the offset-resume test.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** No effect on their behavior. They each gain the same ledger feature when they upgrade. Each agent's DB lives under its own `<stateDir>/server-data/`, so no cross-agent file contention.
+- **Other users of the install base:** Pure additive feature. No existing API contracts changed. Dashboard gains a new tab; existing tabs unchanged.
+- **External systems:** None. No outbound network calls. No Telegram, Slack, GitHub, or Cloudflare interaction.
+- **Persistent state:** New SQLite DB at `<stateDir>/server-data/token-ledger.db`. Auto-created on first boot. No migration needed for existing installs (the DB simply doesn't exist yet and is created on upgrade). The file can be deleted at any time without affecting agent operation — it will be rebuilt by next scan from the source JSONLs (which are themselves the ground truth).
+- **Timing/runtime:** The poller runs every 60s. Each tick performs file I/O proportional to JSONL bytes written since last tick (typically tens of KB/min on a busy agent). SQLite operations are local and bounded. No LLM calls in the hot path. Verified to be cheap by manual sizing — a busy session writes ~1 line per turn, and parsing+inserting one line is microseconds.
+
+The reader is **strictly read-only against `~/.claude/projects/`**. It never opens those files for write. Confirmed by code review of `ingestFile()` — only `fs.openSync(path, 'r')` and `fs.readSync` are used.
+
+---
+
+## 7. Rollback cost
+
+Pure additive code change. Rollback steps:
+
+1. Revert the commit. Ship as next patch release.
+2. The token-ledger DB file at `<stateDir>/server-data/token-ledger.db` becomes orphaned. Safe to ignore — it doesn't affect agent operation. Cleanup is optional (`rm` the file).
+3. No agent state repair needed. No user-visible regression — the dashboard tab disappears, the four endpoints 404. No other behavior changes.
+4. No data migration. No persistent format outside the isolated DB.
+
+Estimated rollback time: minutes. Pure code revert.
+
+---
+
+## Conclusion
+
+This change is read-only observability with no decision-point surface, no external network calls, and no interaction with existing message-flow gates. It follows the established `src/monitoring/` pattern for collectors and the `<stateDir>/server-data/` convention for SQLite storage. The signal-vs-authority principle is preserved by design: the ledger never holds blocking authority, and the "orphans" view is explicitly a signal that any future kill-orphan automation would feed into a smart gate rather than acting on directly.
+
+The change is clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+Not required. This change does not touch any of the trigger criteria from the skill (block/allow on messaging or dispatch, session lifecycle, context exhaustion/compaction, coherence/idempotency/trust, sentinel/guard/gate/watchdog).
+
+---
+
+## Follow-up fix (2026-04-29, post-CI)
+
+CI surfaced a Linux-specific failure in the inode-rotation test: Linux can reuse the same inode number when a file is unlinked and immediately recreated (tmpfs/ext4 behavior). On macOS (where the implementation was first tested) the inode always differs, so the issue was invisible locally.
+
+**Fix:** added a 256-byte content fingerprint (`head_hash` column) to `file_offsets`. Rotation is now detected by `(inode change) OR (head_hash change)`, which is robust across both filesystems. Schema migration is idempotent (`ALTER TABLE … ADD COLUMN` is wrapped in a "duplicate column" swallow).
+
+This change is internal to the ledger and does not affect any of the seven side-effects review answers above. Specifically:
+- No new decision-point surface (still pure observability).
+- No new external surfaces.
+- Rollback cost unchanged — pure code revert; the extra column is harmless if left in place.
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/token-ledger.test.ts` — 12/12 passing locally on `token-ledger-phase1` branch.
+- Typecheck: `npm run lint` clean (tsc --noEmit + lint-no-direct-destructive both pass).
+- JSONL shape verified against real samples in `~/.claude/projects/-Users-justin-Documents-Projects-ai-guy/` before implementation.

package/upgrades/NEXT.md

@@ -1,53 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- bump: patch -->
-<!-- Valid values: patch, minor, major -->
-<!-- patch = bug fixes, refactors, test additions, doc updates -->
-<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
-<!-- major = breaking changes to existing APIs or behavior -->
-
-## What Changed
-
-<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
-<!-- Write this for the AGENT — they need to understand the system deeply. -->
-
-## What to Tell Your User
-
-<!-- Write talking points the agent should relay to their user. -->
-<!-- This should be warm, conversational, user-facing — not a changelog. -->
-<!-- Focus on what THEY can now do, not internal plumbing. -->
-<!--                                                                    -->
-<!-- PROHIBITED in this section (will fail validation):                 -->
-<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
-<!--   Inline code backtick references like silentReject: false        -->
-<!--   Fenced code blocks                                              -->
-<!--   Instructions to edit files or run commands                      -->
-<!--                                                                    -->
-<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
-<!-- The agent relays this to their user — keep it human.              -->
-
-- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| [Capability] | [Endpoint, command, or "automatic"] |
-
-## Evidence
-
-<!-- REQUIRED if this release claims to fix a bug. -->
-<!-- Unit tests passing is NOT evidence. Provide ONE of: -->
-<!--   (a) Reproduction steps + observed before/after on a live system. -->
-<!--       Include log excerpts, observed command output, or behavior -->
-<!--       description. Make it specific enough that a future reader can -->
-<!--       re-run it and see the same thing. -->
-<!--   (b) "Not reproducible in dev — [concrete reason]" if the failure -->
-<!--       mode truly can't be exercised locally (race conditions, -->
-<!--       event-driven paths requiring external signals, etc). -->
-<!--                                                                 -->
-<!-- If this release doesn't claim a bug fix (pure feature / refactor), -->
-<!-- leave this section blank or delete it — it's only enforced when -->
-<!-- "What Changed" describes a fix. -->
-
-[Describe reproduction + verified fix, OR "Not reproducible in dev — [concrete reason]"]