instar 0.28.76 → 0.28.78

package/upgrades/side-effects/threadline-bridge-backfill.md

@@ -0,0 +1,203 @@
+# Side-Effects Review — Threadline Bridge Backfill Script
+
+**Version / slug:** `threadline-bridge-backfill`
+**Date:** `2026-05-02`
+**Author:** `echo`
+**Second-pass reviewer:** `self (incident-grounded reasoning)`
+
+## Summary of the change
+
+Final deliverable in topic-8686. Ships a one-shot CLI script that
+backfills threadline-message history into Telegram topics using the
+bridge primitives from PR #117 — so the user has a complete picture of
+agent-to-agent traffic, including conversations that landed BEFORE the
+bridge shipped.
+
+Files added:
+
+- `scripts/threadline-bridge-backfill.mjs` — the CLI script. Reads the
+  agent's canonical inbox/outbox files (PR #113, PR #118), an optional
+  seed file of historically-reconstructed messages, and the existing
+  bridge bindings. Creates Telegram topics with the bridge naming
+  pattern, posts a backfill banner explaining what the user is seeing,
+  then posts each message chronologically with chunking under 4000 chars.
+  Idempotent via a per-thread ledger at
+  `.instar/threadline/bridge-backfill-ledger.json`.
+- `src/threadline/BackfillCore.ts` — pure helpers (`buildTopicName`,
+  `chunkBody`, `groupByThread`, `pickCounterparty`, `ledgerKey`,
+  `formatBackfillMessage`). Source of truth for the contract; the
+  script's inline copies must stay in sync.
+- `tests/unit/BackfillCore.test.ts` — 16 unit cases pinning the contract.
+
+Files modified: none (this PR is pure additions on top of the four
+prior PRs in the topic-8686 set).
+
+## Decision-point inventory
+
+- `scripts/threadline-bridge-backfill.mjs` — **add** — CLI with
+  `--state-dir`, `--port`, `--threads`, `--seed`, `--dry-run`,
+  `--no-create` flags. Calls `POST /telegram/topics` to create and
+  `POST /telegram/post-update` to post.
+- `BackfillCore.buildTopicName` — **add** — same shape and limits as
+  `TelegramBridge.buildTopicName` from PR #117.
+- `BackfillCore.chunkBody` — **add** — fixed 3800-char chunks with no
+  word-boundary alignment (Telegram preserves whitespace; visual
+  continuity is acceptable).
+- `BackfillCore.groupByThread` — **add** — combines inbox + outbox +
+  seed; sorts each thread chronologically.
+- `BackfillCore.formatBackfillMessage` — **add** — emoji prefix
+  (📥 / 📤), counterparty name, ISO timestamp, body.
+- Backfill ledger format — **add** — `{ version: 1, threads: { [threadId]: { topicId, topicName, posted: [...], lastBackfillAt } } }`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The script is purely additive and doesn't gate any existing flows.
+Validation:
+
+- Empty / unparseable seed file → warn + treat as `[]`.
+- Thread with no on-disk or seed messages → warn + skip.
+- `--no-create` + no existing binding → warn + skip (the user explicitly
+  asked NOT to create topics).
+- `--dry-run` → prints the plan without making any HTTP calls.
+
+No false-positive rejects. The `--threads` filter is exact-match on
+threadId; that's intentional — partial matching here would be a
+foot-gun (accidentally backfilling more threads than intended).
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Orphan topics on partial-success.** If topic creation succeeds but
+  the first message post fails, we have a Telegram topic with only the
+  banner. Acceptable — the ledger records the topic id; a re-run
+  picks up where it left off and posts the remaining messages.
+- **Order-of-arrival sensitivity for the first run.** If two backfill
+  invocations race, both could create a topic for the same thread.
+  Mitigation: the ledger write is the second step (after creation); a
+  duplicate would be detectable and could be removed manually. This
+  script is one-shot, intended to be run by Justin on demand, not
+  scheduled — the race window is hypothetical.
+- **No HMAC verification of inbox/outbox lines.** The script trusts
+  the JSONL files. Same posture as the observability layer in PR #118:
+  the HMAC is for tamper-evidence at write time; reading for
+  user-visible mirroring doesn't need to re-verify (no decision
+  surface). If a tampered line surfaces in Telegram, the user sees
+  it in the conversation view and can investigate.
+- **No quota-aware throttling beyond a 250ms gap.** Telegram's
+  default rate limit is ~30 messages/second to the same chat;
+  4 messages/second is well below. If a thread has 1000+ messages
+  this still completes in ~4 minutes, which is acceptable for a
+  one-shot.
+
+## 3. Level-of-abstraction fit
+
+The script is a CLI wrapper over the agent's existing
+`/telegram/topics` and `/telegram/post-update` HTTP routes. It
+deliberately does NOT:
+
+- Instantiate `TelegramAdapter` directly — would duplicate the agent
+  server's connection state.
+- Call `TelegramBridge.mirrorInbound` — the bridge writes its own
+  bindings file; the script reuses that file. We don't go through the
+  bridge because the bridge would consult `TelegramBridgeConfig`
+  (default-OFF) and refuse to post; the script's purpose is to
+  backfill regardless of the live policy.
+- Touch the canonical inbox/outbox files — those are append-only
+  signals from the live agent; the script reads them but never
+  rewrites them.
+
+Putting the pure helpers in `src/threadline/BackfillCore.ts` keeps
+them tsc-checked and unit-tested while letting the script stay a
+plain `.mjs` (no build step required to run).
+
+## 4. Signal-vs-authority compliance
+
+- **Signal:** the on-disk inbox/outbox files; the optional seed file.
+- **Authority:** none. The script has no decision surface on the
+  routing path — it doesn't gate or alter any threadline flow. The
+  Telegram topic creation goes through the existing `/telegram/topics`
+  route, which is the authority for forum-topic creation.
+
+The script intentionally **bypasses** `TelegramBridgeConfig` because
+backfill is an explicit user action. The user already opted in by
+running the script with the relevant `--threads` argument; consulting
+the dashboard toggle would re-derive that consent. The script's
+output is fully auditable in the ledger.
+
+## 5. Interactions
+
+- **PR #113 (canonical inbox).** Reads `inbox.jsonl.active`. No write.
+- **PR #117 (bridge module).** Reads `telegram-bridge-bindings.json`.
+  Reuses existing bindings (no new bridge-side artifact unless the
+  script creates a topic, in which case the next live `mirrorInbound`
+  / `mirrorOutbound` call will see the binding via the bindings file
+  the script writes — wait, NO: this script does NOT write to
+  `telegram-bridge-bindings.json`. It writes only to its own ledger.
+  This means the live bridge has no awareness of script-created
+  topics until a new bridge-driven message comes through, at which
+  point `findOrCreateForumTopic` returns the existing topic id and
+  the bridge writes its own binding. This is desirable: the bridge
+  remains the only writer of `telegram-bridge-bindings.json`,
+  preserving single-writer simplicity.
+- **PR #118 (observability tab).** Reads `outbox.jsonl.active` (which
+  PR #118 now writes). No write.
+- **`/telegram/topics` route.** Existing route, unchanged.
+- **`/telegram/post-update` route.** Existing route, unchanged.
+- **Backfill ledger.** New file at
+  `.instar/threadline/bridge-backfill-ledger.json` — the script is the
+  only writer. Format is versioned (`version: 1`) so future format
+  changes can land without breaking older ledgers.
+
+## 6. Rollback cost
+
+- The script is a CLI; not running it is the rollback. No recurring
+  process, no background job, no config flag.
+- If a bad backfill posted unwanted content to Telegram, the user
+  deletes the topic via the Telegram UI. The script's ledger entry
+  for that thread can be removed manually (`rm` the
+  `bridge-backfill-ledger.json` entry), and a re-run with
+  `--no-create` will skip the deleted thread.
+- `BackfillCore.ts` is unused outside the test file (the script
+  duplicates the logic inline) — drop the file with no import
+  consequences.
+
+## Plan if a regression appears
+
+- **Symptom: script creates duplicate topics.** Check the ledger;
+  ensure the thread's `topicId` field is populated. If null, the
+  topic-creation HTTP call must have failed mid-flight; re-running
+  is safe (the `bindings` lookup will find the orphan binding from
+  the previous run via the agent's bridge if it ran since). If
+  duplicates persist, delete one in Telegram and remove its ledger
+  entry.
+- **Symptom: messages posted in wrong order.** The grouping step
+  sorts by ISO timestamp. If timestamps are missing or non-ISO,
+  inbound/outbound order can drift. Check the seed file for
+  timestamp consistency.
+- **Symptom: rate-limited by Telegram.** Increase the `SEND_GAP_MS`
+  constant or add `--gap <ms>` flag. Documented in the script header.
+
+## Phase / scope
+
+Final of five deliverables in topic-8686. Closes the build:
+
+1. (a) Canonical inbox write-path — **MERGED** (#113).
+2. (2) Settings surface — **MERGED** (#114).
+3. (b) Bridge module — **MERGED** (#117).
+4. (4) Observability tab — **PR open** (#118).
+5. **(c) Backfill script — THIS PR.**
+
+After this PR ships, Justin can use the dashboard's Threadline tab to
+see live agent-to-agent traffic in real time (post-bridge-enable),
+and run the backfill script to populate Telegram with any historical
+threads he wants visible. The four specific threads named in the
+topic-8686 brief (worktree-audit handoff, Dawn first handoff, Dawn
+four-spawn thread, GROUND-TRUTH round-trip) can be backfilled by
+running the script with a `--seed` file containing the reconstructed
+historical messages — the script handles topic creation, banner,
+chunking, and idempotency.

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-observability-tab.md

@@ -0,0 +1,206 @@
+# Side-Effects Review — Threadline Observability Tab
+
+**Version / slug:** `threadline-observability-tab`
+**Date:** `2026-05-02`
+**Author:** `echo`
+**Second-pass reviewer:** `self (incident-grounded reasoning)`
+
+## Summary of the change
+
+Fourth of five deliverables in topic-8686. Lights up the dashboard
+"Threadline" tab (added in PR #114) with a real conversation-observability
+view: thread list, color-coded message stream, per-thread metrics,
+filters, and search across all threadline message bodies.
+
+Reads three already-existing sources of truth:
+
+- `.instar/threadline/inbox.jsonl.active` — every inbound threadline
+  message (single source post-PR #113).
+- `.instar/threadline/telegram-bridge-bindings.json` — thread → Telegram
+  topic links (single source post-PR #117).
+- `.instar/threadline/thread-resume-map.json` — spawn-session
+  bookkeeping (existing).
+
+Adds one new source of truth:
+
+- `.instar/threadline/outbox.jsonl.active` — every outbound threadline
+  message sent via `/threadline/relay-send`. Mirror of the inbox-write
+  pattern from PR #113. Gives the conversation view BOTH sides of an
+  agent-to-agent thread.
+
+Files added:
+
+- `src/threadline/ThreadlineObservability.ts` — read-only view layer
+  with `listThreads(filters)`, `getThread(threadId)`, `searchMessages(q, limit)`.
+- `tests/unit/ThreadlineObservability.test.ts` — 15 unit cases.
+
+Files modified:
+
+- `src/threadline/ListenerSessionManager.ts` — adds
+  `canonicalOutboxPath` getter and `appendCanonicalOutboxEntry(opts)`
+  helper.
+- `src/server/routes.ts`:
+  - `RouteContext.threadlineObservability: ThreadlineObservability | null`.
+  - Three new endpoints: `GET /threadline/observability/threads`,
+    `GET /threadline/observability/threads/:threadId`,
+    `GET /threadline/observability/search`.
+  - `/threadline/relay-send`: appends a canonical-outbox entry on BOTH
+    success paths (local-delivery + relay-delivery) before returning.
+- `src/server/AgentServer.ts` / `src/commands/server.ts` — instantiate
+  and pass through `threadlineObservability`.
+- `dashboard/index.html` — replaces the placeholder card on the
+  Threadline tab with the conversation view: 280px threads list,
+  conversation pane with header metrics + per-message bubbles,
+  toolbar with filters + debounced search.
+
+## Decision-point inventory
+
+- `appendCanonicalOutboxEntry` — **add** — mirror of the inbound
+  helper from PR #113. HMAC-signed, JSONL-append, 0o600 perms,
+  failure-open.
+- `ThreadlineObservability.listThreads(filters)` — **add** — combines
+  inbox + outbox + bindings + thread-resume-map into per-thread
+  summaries; sorts most-recent first; supports remoteAgent / since /
+  until / hasTopic filters.
+- `ThreadlineObservability.getThread(threadId)` — **add** — returns
+  summary + chronological message stream.
+- `ThreadlineObservability.searchMessages(q, limit)` — **add** —
+  case-insensitive substring search over inbox+outbox bodies; returns
+  hits with snippets bracketed by «...».
+- Three GET endpoints (bearer-auth via global authMiddleware) — **add**.
+- `/threadline/relay-send` outbox writes — **modify** — add one
+  helper call on each of two success branches; failure-open.
+- Dashboard JS handlers (`tlObsLoadThreads`, `tlObsLoadThread`,
+  `tlObsRunSearch`) — **add**.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The observability layer is read-only and never blocks. The new outbox
+write is failure-open and never throws back to `/threadline/relay-send`
+(the route returns its existing success response either way). No
+over-blocks possible.
+
+The endpoints validate query string fields (`hasTopic` only accepts
+`yes` / `no`; everything else is treated as "no filter"). A typo in
+the dashboard's filter UI returns the unfiltered list — which is the
+desirable behavior; the dashboard's controls produce only the valid
+values, and a curl-from-the-CLI user gets an unambiguous result rather
+than a 400.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No persistence boundary on outbox.** `outbox.jsonl.active` grows
+  forever. At the current ~10K msgs/agent envelope this isn't a
+  problem, but a future PR should add rotation parallel to the
+  warm-listener queue's rotation. Out of scope here.
+- **No streaming SSE for the conversation view.** Threads list and
+  conversation are pull-on-activate + manual refresh; new messages
+  don't appear without a refresh. Acceptable for v1; a follow-up can
+  add the existing `/events` SSE channel for live updates.
+- **No FTS5 index.** `searchMessages` does a full-file scan.
+  Sub-100ms at the current envelope; rebuild as FTS5 if it ever
+  becomes a complaint. Documented in the class header.
+- **HMAC verification is NOT performed during read.** The
+  observability layer reads JSONL lines and parses them as data; it
+  doesn't call `verifyEntry` on each row. This is intentional: the
+  inbox write uses HMAC for tamper-evidence at write time; reading
+  for display doesn't need to re-verify. If an attacker tampers with
+  the file at rest, the dashboard would render corrupted bodies, but
+  no decision is made on that data — there's no authority surface
+  here to subvert.
+
+## 3. Level-of-abstraction fit
+
+The class is intentionally thin: it composes the existing files into
+view models. Three sources of truth (inbox, outbox, bindings) compose
+into one summary; the `ListenerSessionManager` already owns the writers.
+This matches the pattern set in PR #113 and #117: each class owns a
+single concern, the observability layer is just a join.
+
+The dashboard handlers debounce input and bind to existing endpoints
+through the existing `apiFetch` helper. No new client-side state
+machine, no caching beyond what the browser does naturally.
+
+## 4. Signal-vs-authority compliance
+
+- **Signal:** dashboard query string parameters; text typed into the
+  search box.
+- **Authority:** none — this layer makes no decisions, gates nothing,
+  blocks nothing. Read-only.
+
+The new outbox write follows the same signal-vs-authority shape as
+the inbound write from PR #113: relay-only, failure-open, no decision
+surface. The route's authority (whether to deliver) was already taken
+upstream.
+
+## 5. Interactions
+
+- **PR #113 (canonical inbox).** Reads the inbox file written by that
+  PR. No coupling beyond file format (well-documented JSONL with
+  `id, timestamp, from, senderName, trustLevel, threadId, text, hmac`).
+- **PR #114 (settings).** Shares the Threadline dashboard tab — the
+  bridge settings card stays at the top, the conversation view sits
+  below.
+- **PR #117 (bridge module).** Reads
+  `telegram-bridge-bindings.json` to populate the per-thread bridge
+  link. The bridge is unaware of the observability layer; the
+  observability layer is unaware of the bridge's runtime — they
+  communicate exclusively through the on-disk file.
+- **`thread-resume-map.json`.** The class accepts both the legacy
+  flat shape (`{threadId: ...}`) and the newer `{threads: {...}}`
+  shape, so it works against either.
+- **`/threadline/relay-send`.** Two new helper calls on the success
+  paths. Same failure-open pattern as PR #113's inbox hoist.
+
+## 6. Rollback cost
+
+- Drop the three observability endpoints + the dashboard handlers →
+  the Threadline tab loses the conversation view but the bridge
+  settings card from PR #114 keeps working.
+- Drop the outbox helper + the two route hooks → outbound messages
+  no longer accrue in `outbox.jsonl.active`, but the relay-send
+  route still functions. The conversation view degrades to inbound-only.
+- The on-disk `outbox.jsonl.active` file is JSONL-append-only with no
+  cross-references; it can be `rm`'d safely if rolled back.
+
+No schema migrations, no shared-state changes, no new processes.
+
+## Plan if a regression appears
+
+- **Symptom: dashboard tab errors loading threads.** Check
+  `apiFetch('/threadline/observability/threads')` — 503 means
+  `threadlineObservability` is null in the route context (server-side
+  bootstrap regression). 200 with empty threads is the correct
+  response for a fresh agent.
+- **Symptom: search slow.** The full-file scan is bounded by
+  `inbox.jsonl.active` + `outbox.jsonl.active` line counts. Profile;
+  if pathological, add an FTS5 index keyed on `(threadId, timestamp)`.
+- **Symptom: outbound messages missing from conversation view.**
+  Either (a) the relay-send route's outbox-append helper threw and
+  was caught, or (b) the threadline message went out via a different
+  path (e.g. legacy direct relay client). Check the warn lines in
+  the agent log. Worst case: roll back the outbox helper additions
+  and rely on the bridge bindings file alone (which still gives
+  thread-level visibility).
+
+## Phase / scope
+
+Fourth of five deliverables in topic-8686:
+
+1. (a) Canonical inbox write-path — **MERGED** (#113).
+2. (2) Settings surface — **MERGED** (#114).
+3. (b) Bridge module — **MERGED** (#117).
+4. **(4) Observability tab — THIS PR.**
+5. (c) Backfill four open threads — final, one-shot script.
+
+After (4) merges, the Threadline tab is the user's single pane of
+glass for agent-to-agent traffic: every thread, every message,
+filters by remote agent / date / has-topic, search, and a clear
+visual signal of which threads have a Telegram topic and which have
+been spawned into a Claude Code session.