instar 0.28.77 → 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-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.

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.