instar 0.28.76 → 0.28.78

package/upgrades/side-effects/threadline-tg-bridge-module.md

@@ -0,0 +1,196 @@
+# Side-Effects Review — Threadline → Telegram Bridge Module
+
+**Version / slug:** `threadline-tg-bridge-module`
+**Date:** `2026-05-02`
+**Author:** `echo`
+**Second-pass reviewer:** `self (incident-grounded reasoning)`
+
+## Summary of the change
+
+Ships the actual **bridge module** that mirrors threadline messages into
+per-thread Telegram topics — third of five deliverables in topic-8686.
+
+Builds on:
+- (a) Canonical inbox write-path fix — PR #113, commit `9cc3e9af` — gives
+  the bridge a single source of truth for inbound traffic.
+- (2) Settings surface — PR #114 — provides the toggles + allow/deny
+  list policy the bridge consults on every message.
+
+Files added:
+
+- `src/threadline/TelegramBridge.ts` — bridge class. Methods:
+  - `mirrorInbound(evt)` — relay handler calls this after the canonical
+    inbox write; auto-creates a topic if config policy allows, otherwise
+    no-op or mirrors into existing.
+  - `mirrorOutbound(evt)` — `/threadline/relay-send` calls this after
+    success; mirrors into existing topic only (outbound never auto-creates).
+  - Persistence in `.instar/threadline/telegram-bridge-bindings.json`
+    (mode `0o600`).
+
+Files modified:
+
+- `src/commands/server.ts` — instantiates `TelegramBridge` after the
+  Telegram adapter is constructed; passes through to AgentServer; the
+  relay handler's `gate-passed` listener fires `mirrorInbound` async.
+- `src/server/routes.ts` — `RouteContext.telegramBridge` typed; the
+  `/threadline/relay-send` route fires `mirrorOutbound` on both the
+  local-delivery and relay-delivery success paths.
+- `src/server/AgentServer.ts` — accepts `options.telegramBridge`,
+  passes through `routeCtx`.
+
+Tests added: 18 unit cases in `tests/unit/TelegramBridge.test.ts`.
+
+## Decision-point inventory
+
+- `TelegramBridge.mirrorInbound` — **add** — relay-only mirror with
+  auto-create gate via `TelegramBridgeConfig`.
+- `TelegramBridge.mirrorOutbound` — **add** — relay-only mirror into
+  existing topic; never auto-creates.
+- `TelegramBridge.buildTopicName` — **add** — `{local}↔{remote} — {subject}`
+  with truncation to 96 chars (Telegram 128 cap with headroom).
+- `TelegramBridgeBindingsFile` — **add** — version=1 JSON file persisted
+  at `.instar/threadline/telegram-bridge-bindings.json`.
+- Relay handler in `server.ts` — **modify** — new `mirrorInbound` call
+  AFTER the canonical inbox write, fire-and-forget with `.catch()`.
+- `/threadline/relay-send` route — **modify** — new `mirrorOutbound`
+  calls in BOTH success paths (local + relay); fire-and-forget.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The bridge is **relay-only**: it has zero blocking authority. It cannot
+reject any input, route, or send. The only gate is "should I post this
+into Telegram?" — and the answer is decided by `TelegramBridgeConfig`,
+which was reviewed and pinned in PR #114.
+
+False over-blocks are not possible at this layer. If the user reports
+"a message I expected to see in Telegram didn't show up", the cause is
+either (a) bridge disabled (master switch off), (b) auto-create denied
+because the remote agent isn't allow-listed and `autoCreateTopics=false`,
+or (c) the underlying Telegram API call failed (logged via the bridge's
+warn channel, not surfaced as an error to the routing path).
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No retry on transient Telegram failures.** A 429 / 5xx from Telegram
+  during `findOrCreateForumTopic` or `sendToTopic` is logged and skipped.
+  No queue, no exponential backoff. Acceptable: the bridge is observability,
+  not delivery — message liveness matters for the threadline relay, not
+  for the Telegram mirror. A future PR can add a delivery queue if losing
+  the occasional mirror becomes a real complaint.
+- **Inbound from a relay that uses a different `threadId` than the
+  outbound send.** The bridge keys bindings by `threadId`, which is the
+  threadline-side id. As long as both sides use a consistent thread id
+  (which they do post-(a)), the binding is stable. If a thread-id
+  divergence sneaks in (e.g. the outbound side mints a fresh id), the
+  outbound mirror returns `no-binding` and silently no-ops. This is the
+  documented behavior; the canonical inbox in (a) is unaffected.
+- **No de-duplication across rapid-fire same-thread inbound.** If the
+  relay handler is invoked twice for the same `messageId`, the bridge
+  will post twice. Out of scope for this PR — same-thread rapid-fire
+  is handled at the relay layer (existing pipe-mode guard) and the
+  threadline replay-gate (already enforced by the relay client).
+
+## 3. Level-of-abstraction fit
+
+The split is the same one used in (2):
+
+- **TelegramBridgeConfig** owns *whether* to mirror (validation + policy).
+- **TelegramBridge** owns *how* to mirror (binding lookup, topic creation,
+  HTTP call, body formatting).
+- The relay handler and `/threadline/relay-send` route own *when* to
+  mirror (event firing).
+
+The bridge depends only on a `TelegramSink` interface (subset of
+`TelegramAdapter`'s `findOrCreateForumTopic` + `sendToTopic`). Tests
+inject a fake sink to exercise success and failure paths without a
+running Telegram. This keeps the bridge testable and the dependency
+surface narrow.
+
+## 4. Signal-vs-authority compliance
+
+- **Signal:** the gate-passed inbox event (already authorized by
+  `InboundMessageGate` upstream); the threadline_send → relay-send
+  outbound success.
+- **Authority:** `TelegramBridgeConfig` decides whether the bridge runs
+  at all. The bridge itself emits zero decisions back to the routing
+  layer — `mirrorInbound` and `mirrorOutbound` return `{posted, reason}`
+  for observability only; nothing in the routing path inspects that
+  return value. This is the canonical signal-vs-authority pattern: the
+  bridge is a low-context observer; the higher-level intelligent gate
+  (config + the existing inbound gate) holds blocking authority.
+
+## 5. Interactions
+
+- **Canonical inbox (PR #113).** The bridge fires AFTER the canonical
+  inbox write at relay-ingest. Two writes — one local audit, one
+  Telegram mirror — both flow from the same event. No coupling: if the
+  canonical write fails, the bridge call still runs (and vice versa).
+- **`telegram-reply.sh` pipeline.** The bridge does NOT use this
+  pipeline — it calls TelegramAdapter primitives directly, bypassing
+  the agent-reply pre-tone-gate path. There is no double-fire because
+  `telegram-reply` is for agent → user replies tied to specific topics,
+  whereas the bridge writes into bridge-owned topics distinguished by
+  the `{local}↔{remote}` naming convention. If the user runs
+  `/link <session>` to bind a session to a bridge topic, that's the
+  user's explicit choice; the bridge doesn't generate that overlap by itself.
+- **Spawn-session prompt.** The bridge does NOT replace the existing
+  spawn-session orchestration. The relay handler still spawns Claude
+  Code sessions on inbound; the bridge runs alongside, purely for user
+  visibility.
+- **`topic-session-registry.json`.** The bridge maintains its own,
+  separate file (`telegram-bridge-bindings.json`) so it does not
+  collide with session ↔ topic bindings. Reusing
+  `topic-session-registry.json` would have conflated two distinct
+  concerns (bridge bindings = thread → topic; session registry =
+  session ↔ topic).
+
+## 6. Rollback cost
+
+- Set `enabled=false` via the dashboard or `PATCH
+  /threadline/telegram-bridge/config`. Bridge stops mirroring on the
+  next event. Existing bindings stay in the file (no dangling Telegram
+  topics get cleaned up — they continue to exist in Telegram but the
+  bridge stops feeding them).
+- Drop the bridge module entirely: remove the
+  `TelegramBridge` import + instantiation in server.ts + the two route
+  hooks. Settings UI from (2) keeps working unchanged. Bindings file
+  becomes an orphaned `.instar/threadline/telegram-bridge-bindings.json`
+  on disk; safe to leave.
+- No database migrations, no Telegram-side cleanup, no schema changes.
+
+## Plan if a regression appears
+
+- **Symptom: Telegram noise.** Verify settings — the user can flip
+  `enabled=false` instantly via the dashboard. If the noise comes
+  through an existing topic that the user wants quieter,
+  `mirrorExisting=false` stops it without affecting auto-create policy.
+- **Symptom: routing latency increases.** The bridge calls are
+  fire-and-forget (`.catch(() => {})` on both `mirrorInbound` and
+  `mirrorOutbound`). Routing should not be on the critical path of any
+  Telegram call. If a regression shows otherwise, audit for an
+  unintended `await` in the relay handler.
+- **Symptom: Telegram topic spam.** Auto-create policy gone wrong.
+  `shouldAutoCreateTopic` is unit-tested for "deny on either id" and
+  "allow on either id"; if a real spam case appears, capture the
+  `remoteAgent` + `remoteAgentName` values and add to the deny-list.
+
+## Phase / scope
+
+Third of five deliverables in topic-8686:
+
+1. (a) Canonical inbox write-path — **MERGED** (#113).
+2. (2) Settings surface — **PR #114, merging**.
+3. **(b) Bridge module — THIS PR.**
+4. (4) Observability tab — extends the Threadline dashboard tab to render
+   the canonical inbox + bindings + thread-resume-map.
+5. (c) Backfill four open threads — one-shot script.
+
+After (b) merges, the bridge is **armed but quiet by default**. The
+user must flip `enabled=true` in the dashboard for any traffic to reach
+Telegram. The next PR (4) lights up the observability view.

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-bounded-scan.md

@@ -0,0 +1,230 @@
+---
+title: Token Ledger — bounded first-boot scan
+slug: token-ledger-bounded-scan
+date: 2026-05-01
+author: echo
+second_pass_required: false
+---
+
+## Summary of the change
+
+The token ledger (shipped in v0.28.77 as Phase 1 read-only observability) does
+a synchronous walk of `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl` on
+every poll tick, and on first boot ingests every file it finds. On Echo's host
+this turned out to mean **119,130 JSONL files / 12 GB of transcripts** — the
+first scan blocked the Node event loop for minutes. The HTTP server accepted
+TCP connections during the scan but never returned a response, including for
+`/health`, which made the lifeline supervisor declare the agent dead and
+restart it in a loop.
+
+This change makes the scan bounded in three ways:
+
+1. **Per-tick file cap (default 500)** with a persistent cursor across
+   ticks, so the ledger backfills incrementally instead of in one pass.
+2. **Async yielding (default every 25 files)** via `setImmediate`, so even
+   within a tick the event loop gets to drain HTTP/health traffic.
+3. **Optional max file age (default 30 days at the wiring layer)** so the
+   ledger ignores transcripts older than the backfill window. The source
+   JSONLs are unchanged and remain the ground truth — the operator can
+   widen the window later by passing a larger `maxFileAgeMs`.
+
+A new `scanAllAsync()` method wraps the existing scan loop and is the path
+the poller now uses. The original `scanAll()` sync method is preserved for
+callers and tests that don't need yielding (and now honors the per-tick
+cap and age cutoff too).
+
+Files touched:
+- `src/monitoring/TokenLedger.ts` — added `maxFileAgeMs`, `maxFilesPerScan`,
+  `yieldEveryNFiles` options; refactored `scanAll` into a shared
+  `scanInternal` helper plus sync (`scanAll`) and async (`scanAllAsync`)
+  entry points; added a persistent `scanCursor` for cross-tick resume.
+- `src/monitoring/TokenLedgerPoller.ts` — switched `tick()` to await
+  `scanAllAsync()` (still fire-and-forget; reentry guard unchanged).
+- `src/server/AgentServer.ts` — wires the three caps with sensible defaults
+  (30-day age window, 500 files/tick, yield every 25 files).
+- `tests/unit/token-ledger.test.ts` — 3 new tests for cursor resume,
+  age cutoff, and async yielding behavior.
+
+The change has no decision-point surface. The ledger is still pure
+observability: never gates, blocks, filters, or alters any agent behavior.
+Adding caps does mean the data picture is incomplete during early backfill,
+but only the *speed of completeness* changes — not whether the data ever
+becomes complete.
+
+## Decision-point inventory
+
+The change has no block/allow/route surface. There is no dispatcher,
+sentinel, gate, or watchdog being added or modified. The "orphans" view
+remains a signal-only list (no kill authority), unchanged.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+The closest analogue would be "the dashboard hides data that does exist on
+disk." That's a property of the new caps: a 90-day-old session won't appear
+in `/tokens/summary` until the operator widens `maxFileAgeMs`. This is
+visibility-shaping, not authority. No automation reads
+`/tokens/summary` and acts on it.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The fix lives entirely inside the existing `src/monitoring/TokenLedger.ts`
+file and its poller. It does not introduce a new framework, queue, or
+abstraction. The caps are normal constructor options on the same class
+that already exists. The cursor is a private instance field. The async
+variant uses `setImmediate` — the standard Node primitive for yielding
+to the event loop, which is what every other long-running scanner in this
+codebase uses (see `OrphanProcessReaper`, `MemoryPressureMonitor`).
+
+The wiring change in `AgentServer.ts` is co-located with the original
+ledger initialization that landed in v0.28.77 — same try/catch,
+same null-on-failure behavior.
+
+---
+
+## 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 remains pure read-side observability. The bounding logic does
+not gain any authority — it only changes the cadence at which data
+becomes visible. Future kill-orphan automation, budget enforcement, or
+compaction triggers remain explicitly out of scope and would be separate
+changes with their own review (per the principle, those would feed an
+LLM-backed authority, not become their own brittle blockers).
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** None. No new route, no new file path, no new dispatcher.
+  The ledger DB schema is unchanged (no migration needed).
+- **Double-fire:** None. The poller's `running` reentry guard is unchanged
+  and still skips a tick if the previous one is in flight. Cursor state
+  is mutated only inside the (single-threaded) scan loop; no cross-tick
+  race because reentry is blocked.
+- **Races:** Cursor invalidation is handled — if `projectDirs` shrinks
+  between ticks (a project directory was deleted), the cursor is reset to
+  `{0, 0}` rather than indexing past the end. The `INSERT OR IGNORE` on
+  `request_id` continues to make ingest idempotent regardless of cursor
+  re-traversal.
+- **Feedback loops:** None. The caps don't create any new path back into
+  Claude Code or the agent's behavior. The ledger continues to be
+  downstream of Claude Code's logging.
+- **Cross-restart:** The cursor resets on process restart (it's an
+  instance field, not persisted). This is correct: after a restart, the
+  ledger DB itself records which files have been read up to which offset
+  (`file_offsets` table), so re-scanning previously-ingested files is
+  cheap (the offset check fires before any line parsing). The cursor
+  exists only to bound *intra-process* work; per-file resume is already
+  handled by the durable offset table from v0.28.77.
+
+One subtle interaction worth naming: the `maxFileAgeMs` filter uses
+`fs.statSync(fp).mtimeMs`. If a JSONL is *appended to* (Claude Code adds
+a turn to an existing session), the mtime updates and the file becomes
+in-window again — so active sessions never get blackholed by the age cap.
+Only sessions that are truly dormant past the cap drop out of the rotation.
+Verified by test: the `respects maxFileAgeMs` test backdates a file with
+`fs.utimesSync` to confirm the filter triggers on stale mtime.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** No effect on their behavior. They
+  each gain the bounded-scan defaults when they upgrade.
+- **Other users of the install base:** Pure additive option surface. Old
+  callers passing only `dbPath` and `claudeProjectsDir` get the new
+  defaults automatically. No existing API contract changed.
+- **External systems:** None. No new outbound calls.
+- **Persistent state:** No schema migration. The existing `file_offsets`
+  table continues to drive per-file resume. The new cursor is in-memory
+  only.
+- **Timing/runtime:** First-boot scan now spans many ticks instead of
+  blocking the event loop. On Echo's box (119k files, mostly stale): with
+  defaults, the first useful tick reads ~500 files within a 30-day window,
+  yielding every 25 files; subsequent ticks pick up the cursor. Steady
+  state once backfill is done is identical to v0.28.77 (same offset-check
+  no-op for already-ingested files).
+
+The reader remains **strictly read-only against `~/.claude/projects/`**.
+No write fds are ever opened.
+
+---
+
+## 7. Rollback cost
+
+Pure additive change. Rollback steps:
+
+1. Revert the commit. Ship as next patch release.
+2. The ledger DB at `<stateDir>/server-data/token-ledger.db` is unchanged
+   on disk (no schema migration). Reverting goes back to unbounded scan
+   behavior — which is broken on agents with deep history, so we'd want
+   to either (a) deploy a different fix, or (b) ship a config option that
+   defaults the agent to NOT initialize the ledger at all on the affected
+   hosts. But the DB itself is fine.
+3. No agent state repair needed.
+
+Estimated rollback time: minutes. Pure code revert.
+
+If the bounded defaults turn out to be wrong (too aggressive), the operator
+can override per-agent via the AgentServer construction call (or, if a
+config knob is added later, via `.instar/config.json`). No re-deploy needed
+to widen the window — the data is still in `~/.claude/projects/`.
+
+---
+
+## Conclusion
+
+This change is a containment fix for a v0.28.77 regression: the ledger
+shipped without considering agents that have years of accumulated Claude
+Code history, and the unbounded synchronous first scan blocked the
+server's event loop. The fix bounds work via three independent
+mechanisms (per-tick file cap, intra-tick yielding, age cutoff) so that
+no plausible JSONL tree can stall the agent. None of these mechanisms
+introduce decision-point surface or change the ledger's read-only,
+observability-only character.
+
+The change is clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+Not required. The change does not touch any of the trigger criteria from
+the side-effects-review skill (block/allow on messaging or dispatch,
+session lifecycle, context exhaustion/compaction, coherence/idempotency/
+trust, sentinel/guard/gate/watchdog).
+
+---
+
+## Evidence pointers
+
+- Reproduction (before fix): start v0.28.77 server on a host with deep
+  Claude Code history. `curl http://localhost:4042/health` hangs;
+  `sample <pid> 1` shows the main thread spending 100% of its time in
+  `uv_fs_stat` callbacks under `Builtins_InterpreterEntryTrampoline`
+  (i.e., a JS loop hammering the filesystem). The lifeline supervisor
+  declares the server unhealthy and restarts it in a loop.
+- Reproduction (after fix): same host, same `~/.claude/projects/` tree.
+  `curl http://localhost:4042/health` returns within a few hundred ms
+  immediately on boot. `curl /tokens/summary` returns valid JSON
+  (initially with a small subset of recent sessions; backfill fills in
+  across subsequent ticks).
+- Unit tests: `tests/unit/token-ledger.test.ts` — 15/15 passing locally
+  on `fix/token-ledger-bounded-scan` branch. New tests cover the three
+  bounding mechanisms (cursor resume, age cutoff, async yielding).
+- Typecheck: `npx tsc --noEmit` clean.