switchroom 0.20.21 → 0.21.0

package/telegram-plugin/gateway/always-allow-persist-queue.ts

@@ -60,7 +60,7 @@
 
 import { writeFileSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import { atomicWriteStateFileSync } from '../../src/util/state-owner.js'
 import {
   preserveUnreadableStoreFile,
   quarantineCorruptStoreFile,
@@ -182,7 +182,7 @@ export function computeBackoffMs(attempts: number, retryAfterMs?: number): numbe
  */
 export const atomicWriteSeam = ((path, data, opts) => {
   const mode = typeof opts === 'object' && opts !== null && typeof opts.mode === 'number' ? opts.mode : 0o600
-  atomicWriteFileSync(path as string, data as string, mode)
+  atomicWriteStateFileSync(path as string, data as string, mode)
 }) as typeof writeFileSync
 
 export function createAlwaysAllowPersistQueue(

package/telegram-plugin/gateway/boot-beacon.ts

@@ -68,7 +68,6 @@ import { randomUUID } from 'node:crypto'
 import {
   closeSync,
   fsyncSync,
-  mkdirSync,
   openSync,
   readFileSync,
   renameSync,
@@ -76,6 +75,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
+import { adoptStateOwnershipFd, mkdirStateSync } from '../../src/util/state-owner.js'
 
 /** Filename under `TELEGRAM_STATE_DIR`. */
 export const BOOT_BEACON_FILE = 'gateway-beacon.json'
@@ -297,12 +297,19 @@ export function writeBootBeaconFile(stateDir: string, beacon: BootBeacon): boole
     // gateway creates it 0o700 at boot. If it were ever missing here, a
     // default-mode recreate by this 5s tick would silently loosen the
     // permissions on that whole directory.
-    mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+    mkdirStateSync(stateDir, { recursive: true, mode: 0o700 })
     fd = openSync(tmp, 'w', 0o600)
     // writeFileSync (not writeSync) on the fd: it loops internally, so a short
     // write can't leave a truncated beacon that we then fsync and rename into
     // place as if it were whole.
     writeFileSync(fd, serializeBootBeacon(beacon))
+    // Ownership on the TEMPFILE FD, before the rename: a root-running gateway
+    // re-creates this file every 5s, so it is the loudest source of root-owned
+    // state in an agent-owned dir. Doing it on the fd (never a path) means no
+    // symlink can be raced in, and doing it before the rename means the file
+    // is never visible at its final name under the wrong owner. No-op off the
+    // root path.
+    adoptStateOwnershipFd(fd, stateDir)
     fsyncSync(fd)
     closeSync(fd)
     fd = undefined

package/telegram-plugin/gateway/gateway-heartbeat.ts

@@ -21,8 +21,9 @@
  * conservatively BLOCKS (re-prompt), which is the safe direction.
  */
 
-import { mkdirSync, utimesSync, writeFileSync } from 'node:fs'
+import { utimesSync } from 'node:fs'
 import { join } from 'node:path'
+import { mkdirStateSync, writeStateFileSync } from '../../src/util/state-owner.js'
 
 /** Filename under `TELEGRAM_STATE_DIR`. MUST stay in sync with
  * `GATEWAY_HEARTBEAT_FILE` in `hooks/silent-end-scan.mjs`. */
@@ -47,8 +48,8 @@ export function touchGatewayHeartbeat(stateDir: string): void {
   } catch {
     // File doesn't exist yet (or unstattable) — create it.
     try {
-      mkdirSync(stateDir, { recursive: true })
-      writeFileSync(path, `${Date.now()}\n`, { mode: 0o600 })
+      mkdirStateSync(stateDir, { recursive: true })
+      writeStateFileSync(path, `${Date.now()}\n`, { mode: 0o600 })
     } catch {
       // Best-effort — a heartbeat write failure makes the hook BLOCK
       // (re-prompt), which is the safe direction.

package/telegram-plugin/gateway/gateway.ts

@@ -395,7 +395,9 @@ import {
   pruneMessagesOlderThanDays,
   hasOutboundDeliveredSince,
   hasOutboundWithText,
+  recordSystemOutbound, updateSystemOutboundText,
 } from '../history.js'
+import { makeSystemMessageObserver } from './system-message-observer.js'
 import {
   runRegistryReaper,
   resolveRetentionDays as resolveRegistryRetentionDays,
@@ -658,7 +660,8 @@ import { createStatusPinApi, type PinCapableBot, type RobustApiSeam } from './st
 import { collectSweepTargets, type StalePinSweeper, type SweepTarget } from './stale-pin-sweep.js'
 import { createGatewayStalePinSweeper } from './stale-pin-sweep-wiring.js'
 import { reseedSweepLedger } from './stale-pin-sweep-store.js'
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+// Ownership choke point for every state-dir write; zero-syscall no-op off the root path. Rationale: src/util/state-owner.ts.
+import { appendStateFileSync, atomicWriteStateFileSync, mkdirStateSync, reconcileStateDirOwnershipLogged, writeStateFileSync } from '../../src/util/state-owner.js'
 import { startWebhookIngestServer } from './webhook-ingest-server.js'
 import { recordWebhookEvent } from '../../src/web/webhook-gateway-record.js'
 
@@ -2148,6 +2151,8 @@ function runHistoryReaperNow(reason: 'boot' | 'periodic'): void {
       process.stderr.write(`telegram gateway: history-reaper (${reason}) failed: ${(err as Error).message}\n`)
     }
   }
+  // State-dir ownership backfill (never throws; rides this EXISTING boot/6h tick). See src/util/state-owner.ts.
+  reconcileStateDirOwnershipLogged(STATE_DIR, reason, { prefix: 'telegram gateway' })
 }
 // Run once at boot to catch up long-stopped agents. (#2996 P0c: gated.)
 if (isGatewayMain) runHistoryReaperNow('boot')
@@ -2668,7 +2673,7 @@ function noteAgentOutputAt(key: string, ts: number): void {
 const OBLIGATION_STORE_PATH = join(STATE_DIR, 'obligations.json')
 const obligationStoreFs = {
   readFileSync: (p: string) => readFileSync(p, 'utf8'),
-  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  writeFileSync: (p: string, d: string) => writeStateFileSync(p, d),
   renameSync: (a: string, b: string) => renameSync(a, b),
   existsSync: (p: string) => existsSync(p),
   fsyncFileSync: fsyncPathSync, fsyncDirSync: fsyncPathSync, unlinkSync,
@@ -5595,10 +5600,26 @@ const rawRobustApiCall = createRetryApiCall({
   floodWaitRemainingMs: probeFloodWaitRemainingMs,
 })
 
+// #4571 — card/system-surface history lane. Every card the gateway posts
+// (activity card, status pin, approval/boot/issues/worker-feed cards, progress
+// lines, notices) goes through `robustApiCall`, so observing its RESOLVED
+// result is the one chokepoint that makes every posted message id resolvable
+// when the operator quote-replies to it. Never throws; see
+// system-message-observer.ts for the send-vs-edit and throttling contract.
+// Gated on the SAME condition as `initHistory` above — a non-main gateway
+// process never opens the DB, so an observer there would be pure noise.
+const observeSentMessage = isGatewayMain && HISTORY_ENABLED
+  ? makeSystemMessageObserver({ insert: recordSystemOutbound, updateText: updateSystemOutboundText })
+  : undefined
+
 const robustApiCall = <T>(
   fn: () => Promise<T>,
   opts?: Parameters<typeof rawRobustApiCall<T>>[1],
-): Promise<T> => sendGate.gate(() => rawRobustApiCall(fn, opts), opts)
+): Promise<T> => {
+  const p = sendGate.gate(() => rawRobustApiCall(fn, opts), opts)
+  if (observeSentMessage == null) return p
+  return p.then((res) => { observeSentMessage(res, opts); return res })
+}
 
 // Fire-and-forget wrapper for outbound surfaces that previously had
 // `.catch(() => {})` directly on `bot.api.*` calls. Resolves to undefined
@@ -8384,7 +8405,7 @@ const statusPinRightsCache = new PinRightsCache()
 const STATUS_PIN_STORE_PATH = join(STATE_DIR, 'status-pins.json')
 const statusPinStoreFs = {
   readFileSync: (p: string) => readFileSync(p, 'utf8'),
-  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  writeFileSync: (p: string, d: string) => writeStateFileSync(p, d),
   renameSync: (a: string, b: string) => renameSync(a, b),
   existsSync: (p: string) => existsSync(p),
 }
@@ -8400,7 +8421,7 @@ const statusPinPersistEnabled = !STATIC && PIN_STATUS_WHILE_WORKING
 const ACTIVITY_CARD_STORE_PATH = join(STATE_DIR, 'activity-cards-pending.json')
 const activityCardStoreFs: ActivityCardStoreFsSeam = {
   readFileSync: (p: string) => readFileSync(p, 'utf8'),
-  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  writeFileSync: (p: string, d: string) => writeStateFileSync(p, d),
   renameSync: (a: string, b: string) => renameSync(a, b),
   existsSync: (p: string) => existsSync(p),
 }
@@ -8419,7 +8440,7 @@ const activityCardPersistEnabled = !STATIC
 const QUEUED_CARD_STORE_PATH = join(STATE_DIR, 'queued-cards-pending.json')
 const queuedCardStoreFs: QueuedCardStoreFsSeam = {
   readFileSync: (p: string) => readFileSync(p, 'utf8'),
-  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  writeFileSync: (p: string, d: string) => writeStateFileSync(p, d),
   renameSync: (a: string, b: string) => renameSync(a, b),
   existsSync: (p: string) => existsSync(p),
 }
@@ -9054,7 +9075,7 @@ let stalePinSweepEligible = false
 const STALE_PIN_SWEEP_STORE_PATH = join(STATE_DIR, 'stale-pin-sweep.json')
 const sweepStoreFs = {
   readFileSync: (p: string) => readFileSync(p, 'utf-8'),
-  writeFileSync: (p: string, data: string) => atomicWriteFileSync(p, data, 0o600),
+  writeFileSync: (p: string, data: string) => atomicWriteStateFileSync(p, data, 0o600),
   existsSync: (p: string) => existsSync(p),
 }
 const stalePinSweeper: StalePinSweeper = createGatewayStalePinSweeper({
@@ -9152,7 +9173,7 @@ let workerActivityFeed: ReturnType<typeof createWorkerActivityFeed> | null = nul
 // ─── IPC server ───────────────────────────────────────────────────────────
 const SOCKET_PATH = process.env.SWITCHROOM_GATEWAY_SOCKET ?? join(STATE_DIR, 'gateway.sock')
 // Ensure the directory for the socket exists (#2996 P0c: gated — disk write).
-if (isGatewayMain) mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 })
+if (isGatewayMain) mkdirStateSync(STATE_DIR, { recursive: true, mode: 0o700 })
 
 // PID file + session marker. See pid-file.ts and session-marker.ts for
 // the 2026-04-22 incident that motivates these. The PID file lets the
@@ -9739,9 +9760,9 @@ if (isGatewayMain) inboundSpool = STATIC
   : createInboundSpool({
       path: join(STATE_DIR, 'inbound-spool.jsonl'),
       fs: {
-        appendFileSync: (p, d) => appendFileSync(p, d),
+        appendFileSync: (p, d) => appendStateFileSync(p, d),
         readFileSync: (p) => readFileSync(p, 'utf8'),
-        writeFileSync: (p, d) => writeFileSync(p, d),
+        writeFileSync: (p, d) => writeStateFileSync(p, d),
         renameSync: (a, b) => renameSync(a, b),
         existsSync: (p) => existsSync(p),
         statSizeSync: (p) => statSync(p).size,
@@ -12848,7 +12869,7 @@ async function publishToTelegraph(
     }
     account = created.value
     try {
-      mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 })
+      mkdirStateSync(STATE_DIR, { recursive: true, mode: 0o700 })
       writeFileSync(accountPath, JSON.stringify(account, null, 2), { mode: 0o600 })
     } catch (err) {
       process.stderr.write(`telegram gateway: telegraph cache write failed: ${(err as Error).message}\n`)
@@ -15048,13 +15069,18 @@ export async function handleInbound(
     replyToText,
     replyToTextEscaped,
     replyToRole,
+    replyToKind,
   } = resolveReplyToFromBuffer({
     replyToMessageId,
     replyToText: replyForwardCtx.replyToText,
     replyToTextEscaped: replyForwardCtx.replyToTextEscaped,
     historyEnabled: HISTORY_ENABLED,
     replyToTextMax: REPLY_TO_TEXT_MAX,
-    lookup: (messageId) => lookupMessageRoleAndText(chat_id, messageId),
+    // includeSystem (#4571): a quote-reply to the live activity card / a status
+    // pin / an approval card must resolve. Scoped to THIS lookup — the
+    // reaction-trigger's bot-authored predicate keeps the default (cards
+    // invisible), so its behaviour is unchanged.
+    lookup: (messageId) => lookupMessageRoleAndText(chat_id, messageId, { includeSystem: true }),
   })
 
   if (HISTORY_ENABLED) {
@@ -15132,6 +15158,7 @@ export async function handleInbound(
     replyToMessageId,
     replyToTextEscaped,
     replyToRole,
+    replyToKind,
     forwardOriginMeta,
     topicFramingEnabled: TOPIC_FRAMING_ENABLED,
     personDirectory: PERSON_DIRECTORY,
@@ -16061,7 +16088,7 @@ function spawnSwitchroomDetached(
   const logPath = join(STATE_DIR, 'detached-spawn.log')
   let outFd: number | null = null
   try {
-    mkdirSync(STATE_DIR, { recursive: true })
+    mkdirStateSync(STATE_DIR, { recursive: true })
     outFd = openSync(logPath, 'a')
     writeFileSync(logPath, `\n[${new Date().toISOString()}] spawn ${SWITCHROOM_CLI} ${fullArgs.join(' ')}\n`, { flag: 'a' })
   } catch {}
@@ -17577,9 +17604,9 @@ function buildFolderPickerDeps(): FolderPickerHandlerDeps {
 // existing on-disk lockouts age out via DEFAULT_FALLBACK_COOLDOWN_MS.
 const lockoutOps: LockoutPersistOps = {
   readFileSync: (p, enc) => readFileSync(p, enc),
-  writeFileSync: (p, data, opts) => writeFileSync(p, data, opts),
+  writeFileSync: (p, data, opts) => writeStateFileSync(p, data, opts),
   existsSync: (p) => existsSync(p),
-  mkdirSync: (p, opts) => mkdirSync(p, opts),
+  mkdirSync: (p, opts) => mkdirStateSync(p, opts),
   joinPath: (...parts) => join(...parts),
 }
 

package/telegram-plugin/gateway/inbound-router.ts

@@ -208,8 +208,14 @@ export interface ReplyToBufferFallbackParams {
   /** REPLY_TO_TEXT_MAX. */
   replyToTextMax: number
   /** `lookupMessageRoleAndText` bound to the chat, or any equivalent. May
-   *  throw (e.g. requireDb when history disabled mid-run) — this is caught. */
-  lookup: (messageId: number) => { role: 'user' | 'assistant'; text: string } | null
+   *  throw (e.g. requireDb when history disabled mid-run) — this is caught.
+   *
+   *  Bind it with `includeSystem: true` (#4571) so a reply that points at a
+   *  CARD — the activity card, a status pin, an approval card — resolves
+   *  instead of returning null. `kind` carries the card family. */
+  lookup: (
+    messageId: number,
+  ) => { role: 'user' | 'assistant' | 'system'; text: string; kind?: string | null } | null
 }
 
 /**
@@ -232,15 +238,22 @@ export interface ReplyToBufferFallbackParams {
 export function resolveReplyToFromBuffer(p: ReplyToBufferFallbackParams): {
   replyToText: string | undefined
   replyToTextEscaped: string | undefined
-  replyToRole: 'user' | 'assistant' | undefined
+  replyToRole: 'user' | 'assistant' | 'system' | undefined
+  /** Card family (`activity-summary`, `approval-card`, …) when the antecedent
+   *  is a system-lane row. Undefined otherwise. #4571. */
+  replyToKind: string | undefined
 } {
   let replyToText = p.replyToText
   let replyToTextEscaped = p.replyToTextEscaped
-  let replyToRole: 'user' | 'assistant' | undefined
+  let replyToRole: 'user' | 'assistant' | 'system' | undefined
+  let replyToKind: string | undefined
   const liveTextEmpty = replyToTextEscaped == null || replyToTextEscaped.length === 0
   if (p.historyEnabled && p.replyToMessageId != null && liveTextEmpty) {
     try {
       const recovered = p.lookup(p.replyToMessageId)
+      if (recovered != null && recovered.role === 'system' && recovered.kind) {
+        replyToKind = recovered.kind
+      }
       if (recovered && recovered.text.length > 0) {
         replyToText =
           recovered.text.length > p.replyToTextMax
@@ -258,7 +271,7 @@ export function resolveReplyToFromBuffer(p: ReplyToBufferFallbackParams): {
       // silently to the id-only inputs (current behavior).
     }
   }
-  return { replyToText, replyToTextEscaped, replyToRole }
+  return { replyToText, replyToTextEscaped, replyToRole, replyToKind }
 }
 
 /** Inputs for {@link buildInboundEnvelope} — every field is an at-call
@@ -288,7 +301,11 @@ export interface EnvelopeBuildParams {
    * message, 'user' = a person's), when known — recovered from the history
    * buffer by handleInbound's reply-to fallback. Undefined when the role
    * can't be determined (e.g. text came live off the update, not the DB). */
-  replyToRole: 'user' | 'assistant' | undefined
+  replyToRole: 'user' | 'assistant' | 'system' | undefined
+  /** #4571 — when the antecedent is a CARD the gateway posted (activity card,
+   * status pin, approval card…), the card family. Emitted as `reply_to_kind`
+   * alongside `reply_to_role="system"`. */
+  replyToKind?: string | undefined
   forwardOriginMeta: Record<string, string>
   /** TOPIC_FRAMING_ENABLED — fixed constant. */
   topicFramingEnabled: boolean
@@ -390,6 +407,14 @@ export function buildInboundEnvelope(p: EnvelopeBuildParams): InboundMessage {
       // guessing the antecedent. Free: the history-buffer lookup that recovers
       // reply_to_text already returns the role. Emitted only when known.
       ...(p.replyToRole != null ? { reply_to_role: p.replyToRole } : {}),
+      // #4571 — the antecedent is one of the bot's own CARDS, not a reply.
+      // `reply_to_role="system"` + `reply_to_kind="activity-summary"` tells the
+      // agent the operator tapped the live working card (the most recent thing
+      // on their screen for most of a turn) rather than an answer, so it can
+      // read `reply_to_text` as the card body instead of reporting amnesia.
+      ...(p.replyToKind != null && p.replyToKind.length > 0
+        ? { reply_to_kind: p.replyToKind }
+        : {}),
       // Forwarded-message origin (server-stamped, attrs-only — see above).
       // forwarded_from / forwarded_from_type / forwarded_from_id /
       // forwarded_date, plus numbered _2.. siblings for a multi-origin

package/telegram-plugin/gateway/missed-approvals-store.ts

@@ -31,7 +31,7 @@
 
 import { unlinkSync } from 'node:fs'
 import { join } from 'node:path'
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import { atomicWriteStateFileSync } from '../../src/util/state-owner.js'
 import {
   preserveUnreadableStoreFile,
   quarantineCorruptStoreFile,
@@ -149,7 +149,7 @@ export function createMissedApprovalsStore(
         unreadable = false
       }
       // tmp + fsync + rename — never truncate the destination in place.
-      atomicWriteFileSync(filePath, JSON.stringify(f), 0o600)
+      atomicWriteStateFileSync(filePath, JSON.stringify(f), 0o600)
     } catch (err) {
       log(`telegram gateway: missed-approvals-store write failed: ${(err as Error).message}\n`)
     }

package/telegram-plugin/gateway/pending-card-store.ts

@@ -44,7 +44,7 @@
 
 import { unlinkSync } from 'node:fs'
 import { join } from 'node:path'
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import { atomicWriteStateFileSync } from '../../src/util/state-owner.js'
 import {
   preserveUnreadableStoreFile,
   quarantineCorruptStoreFile,
@@ -162,7 +162,7 @@ export function createPendingCardStore(
       // tmp + fsync + rename, mode pinned to 0600 on the tempfile fd (so an
       // existing file can't keep laxer perms, and a crash mid-write leaves
       // the previous good file untouched).
-      atomicWriteFileSync(filePath, JSON.stringify(entries), 0o600)
+      atomicWriteStateFileSync(filePath, JSON.stringify(entries), 0o600)
     } catch (err) {
       log(`telegram gateway: pending-card-store write failed: ${(err as Error).message}\n`)
     }

package/telegram-plugin/gateway/privacy-state.ts

@@ -39,7 +39,7 @@ import { readFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import { atomicWriteStateFileSync } from '../../src/util/state-owner.js'
 
 /** One half-open privacy interval. `end: null` = still open ("private now"). */
 export interface PrivacyInterval {
@@ -130,7 +130,7 @@ function writePrivacyState(state: PrivacyState, stateDir: string): void {
     /* dir may already exist / be unwritable — the write below reports */
   }
   try {
-    atomicWriteFileSync(privacyStatePath(stateDir), JSON.stringify(state), 0o600)
+    atomicWriteStateFileSync(privacyStatePath(stateDir), JSON.stringify(state), 0o600)
   } catch (err) {
     process.stderr.write(
       `telegram gateway: privacy-state write failed: ${err instanceof Error ? err.message : String(err)}\n`,

package/telegram-plugin/gateway/scoped-grant-store.ts

@@ -28,7 +28,7 @@
  */
 
 import { join } from 'node:path'
-import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import { atomicWriteStateFileSync } from '../../src/util/state-owner.js'
 import {
   preserveUnreadableStoreFile,
   quarantineCorruptStoreFile,
@@ -105,7 +105,7 @@ export function createScopedGrantStore(
         }
         // tmp + fsync + rename — a crash mid-persist leaves the previous
         // grant set intact rather than a torn file that reads as "no grants".
-        atomicWriteFileSync(filePath, JSON.stringify(serializeScopedGrants(store)), 0o600)
+        atomicWriteStateFileSync(filePath, JSON.stringify(serializeScopedGrants(store)), 0o600)
       } catch (err) {
         log(`telegram gateway: scoped-grant-store write failed: ${(err as Error).message}\n`)
       }

package/telegram-plugin/gateway/system-message-observer.ts

@@ -0,0 +1,242 @@
+/**
+ * system-message-observer.ts — make CARD message ids resolvable (#4571).
+ *
+ * The problem
+ * -----------
+ * Only two things ever reached `history.db`: an inbound message, and an
+ * outbound that flowed through the `reply` / `stream_reply` family (which call
+ * `recordOutbound` explicitly). Everything else the gateway posts — the
+ * mid-turn activity card, the pinned status message, approval / boot / issues
+ * / worker-feed cards, `progress_update` lines, restart notices — consumed a
+ * real Telegram message id and left NO row behind. Measured on a live agent's
+ * buffer: 116 rows across a 266-id span above id 20000, i.e. ~56% of the ids
+ * in that chat were absent, clustered exactly where the cards were.
+ *
+ * That is user-visible, not cosmetic. The activity card is the most recent
+ * message on the operator's screen for most of a turn, so quote-replying to it
+ * is the natural gesture. Telegram then delivers `reply_to_message_id` pointing
+ * at a message the agent has no record of, the reply-antecedent resolver
+ * (`resolveReplyToFromBuffer`) gets `null` back, and the agent has to say "I
+ * can't see the message you replied to".
+ *
+ * The mechanism
+ * -------------
+ * Rather than add a `recordSystemOutbound(...)` call to each of the ~110 raw
+ * send sites (which is exactly the kind of per-call-site discipline that
+ * decays — the `reply` path was the only site anyone remembered), this hooks
+ * the ONE chokepoint every gateway outbound already goes through:
+ * `gateway.ts`'s `robustApiCall` (chat-lock → send-gate → retry policy). Every
+ * card send in the gateway is routed through it, enforced by the
+ * `check-bot-api-wrapping` lint guard.
+ *
+ * The observer reads the Telegram RESPONSE, not the request, which buys three
+ * things for free:
+ *   - the real `message_id` (the only thing a reply can point at),
+ *   - the chat and forum-topic the message actually landed in,
+ *   - the RENDERED text, which for a card is otherwise unrecoverable (it is
+ *     composed from live tool activity and never persisted anywhere).
+ *
+ * Send vs edit is NOT guessed from the verb (verb tagging is not uniform
+ * across call sites and would rot). It falls out of the data: an edit returns
+ * the same `message_id` it edited, so the conditional insert no-ops and the
+ * call falls through to an in-place text refresh. One row per card, forever,
+ * regardless of how many times it is edited.
+ *
+ * Cost control. The activity card is the highest-volume repeated
+ * `editMessageText` in the gateway (it climbs every few seconds for the whole
+ * turn). Refreshing its stored text on every edit would be a SQLite write per
+ * edit. So a per-message throttle (`editRefreshMs`, default 20s) keeps the hot
+ * path entirely in memory: a card edit inside the window costs one Map lookup
+ * and no DB work at all. The stored text is therefore a recent snapshot, not
+ * a byte-exact mirror of the live card — which is the right trade for a
+ * quote-reply antecedent.
+ *
+ * Nothing here throws. A failure to record a card must never break the send it
+ * is observing.
+ */
+
+/** The subset of a Telegram `Message` response this observer reads. */
+export interface SentMessageLike {
+  message_id?: unknown
+  chat?: { id?: unknown } | null
+  message_thread_id?: unknown
+  text?: unknown
+  caption?: unknown
+}
+
+/** The subset of `robustApiCall`'s opts the observer reads. */
+export interface ObservedCallOpts {
+  chat_id?: string
+  threadId?: number
+  verb?: string
+}
+
+export interface SystemMessageObserverDeps {
+  /**
+   * `history.recordSystemOutbound`. Must return true iff it inserted a NEW
+   * row, and false if any row already existed for (chat_id, message_id).
+   */
+  insert: (args: {
+    chat_id: string
+    thread_id: number | null
+    message_id: number
+    kind: string | null
+    text: string
+  }) => boolean
+  /**
+   * `history.updateSystemOutboundText`. Must return true iff it updated a row,
+   * and false when the target row is absent or is NOT a system row (i.e. the
+   * id belongs to a real reply or an inbound).
+   */
+  updateText: (args: { chat_id: string; message_id: number; text: string }) => boolean
+  /** Injectable clock for the edit throttle. Defaults to `Date.now`. */
+  now?: () => number
+}
+
+export interface SystemMessageObserverOptions {
+  /**
+   * Minimum gap between two stored-text refreshes of the SAME message. Edits
+   * inside the window are dropped without touching SQLite.
+   */
+  editRefreshMs?: number
+  /** Cap on tracked message ids before the oldest half is evicted. */
+  maxTracked?: number
+}
+
+export const DEFAULT_EDIT_REFRESH_MS = 20_000
+export const DEFAULT_MAX_TRACKED = 512
+
+/**
+ * Normalise a `robustApiCall` verb into the stored `kind` discriminator.
+ *
+ * The verb is the honest, already-present label for what a send IS
+ * (`activity-summary.send`, `boot-card`, `worker-feed`, `approval-card`), so
+ * the kind is derived rather than invented. The trailing transport suffix is
+ * stripped so a card's OPEN and its EDITs classify identically.
+ *
+ * Pure. Returns null for an absent / blank verb.
+ */
+export function normalizeSendVerb(verb: string | undefined | null): string | null {
+  if (typeof verb !== 'string') return null
+  const trimmed = verb.trim()
+  if (trimmed.length === 0) return null
+  const base = trimmed.replace(/\.(send|edit|create|post|update)$/i, '')
+  const cleaned = (base.length > 0 ? base : trimmed).slice(0, 64)
+  return cleaned.length > 0 ? cleaned : null
+}
+
+/**
+ * Extract the (chat_id, message_id, thread, text) tuple from a Telegram API
+ * result, or null when the result is not a sent/edited Message (the retry
+ * wrapper also returns `true` for pins / deletes / reactions / callback
+ * answers, and `undefined` for a swallowed benign 400).
+ *
+ * The response's own `chat.id` wins over the caller's `chat_id` opt: it is what
+ * Telegram actually delivered to, and several call sites pass no `chat_id` at
+ * all. Pure.
+ */
+export function extractSentMessage(
+  result: unknown,
+  opts?: ObservedCallOpts,
+): { chatId: string; messageId: number; threadId: number | null; text: string } | null {
+  if (result == null || typeof result !== 'object') return null
+  const msg = result as SentMessageLike
+  const id = msg.message_id
+  if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) return null
+  const rawChat = msg.chat?.id
+  const chatId =
+    rawChat != null && (typeof rawChat === 'number' || typeof rawChat === 'string')
+      ? String(rawChat)
+      : opts?.chat_id
+  if (chatId == null || chatId.length === 0) return null
+  const rawThread = msg.message_thread_id
+  const threadId =
+    typeof rawThread === 'number' && Number.isInteger(rawThread)
+      ? rawThread
+      : typeof opts?.threadId === 'number'
+        ? opts.threadId
+        : null
+  const text =
+    typeof msg.text === 'string' ? msg.text : typeof msg.caption === 'string' ? msg.caption : ''
+  return { chatId, messageId: id, threadId, text }
+}
+
+/** Per-id bookkeeping. `foreign` = the id belongs to a non-system row (a real
+ *  reply or an inbound); never write to it again. */
+type TrackedState = { lane: 'system' | 'foreign'; lastStoredMs: number }
+
+/**
+ * Build the observer. The returned function is called with the RESOLVED result
+ * of every `robustApiCall` and never throws.
+ */
+export function makeSystemMessageObserver(
+  deps: SystemMessageObserverDeps,
+  options?: SystemMessageObserverOptions,
+): (result: unknown, opts?: ObservedCallOpts) => void {
+  const now = deps.now ?? Date.now
+  const editRefreshMs = options?.editRefreshMs ?? DEFAULT_EDIT_REFRESH_MS
+  const maxTracked = Math.max(1, options?.maxTracked ?? DEFAULT_MAX_TRACKED)
+  const tracked = new Map<string, TrackedState>()
+
+  function remember(key: string, state: TrackedState): void {
+    tracked.set(key, state)
+    if (tracked.size > maxTracked) {
+      // Map iterates in insertion order — drop the oldest half in one pass so
+      // eviction is amortised O(1) rather than per-insert.
+      const drop = Math.ceil(tracked.size / 2)
+      let i = 0
+      for (const k of tracked.keys()) {
+        if (i++ >= drop) break
+        tracked.delete(k)
+      }
+    }
+  }
+
+  return function observeSentMessage(result: unknown, opts?: ObservedCallOpts): void {
+    try {
+      const sent = extractSentMessage(result, opts)
+      if (sent == null) return
+      const key = `${sent.chatId}:${sent.messageId}`
+      const t = now()
+      const seen = tracked.get(key)
+
+      if (seen != null) {
+        if (seen.lane === 'foreign') return
+        if (t - seen.lastStoredMs < editRefreshMs) return
+        if (deps.updateText({ chat_id: sent.chatId, message_id: sent.messageId, text: sent.text })) {
+          seen.lastStoredMs = t
+        } else {
+          // The row is gone (retention prune / delete) or was promoted to a
+          // real `assistant` reply by recordOutbound. Either way this id is no
+          // longer ours to write.
+          seen.lane = 'foreign'
+        }
+        return
+      }
+
+      const inserted = deps.insert({
+        chat_id: sent.chatId,
+        thread_id: sent.threadId,
+        message_id: sent.messageId,
+        kind: normalizeSendVerb(opts?.verb),
+        text: sent.text,
+      })
+      if (inserted) {
+        remember(key, { lane: 'system', lastStoredMs: t })
+        return
+      }
+      // A row already exists for this id and we did not create it in this
+      // process: either a real reply / inbound (leave it alone), or a card this
+      // gateway posted before a restart. One probing update disambiguates —
+      // `updateText` only ever matches a `system` row.
+      const refreshed = deps.updateText({
+        chat_id: sent.chatId,
+        message_id: sent.messageId,
+        text: sent.text,
+      })
+      remember(key, { lane: refreshed ? 'system' : 'foreign', lastStoredMs: t })
+    } catch {
+      /* observing a send must never break the send */
+    }
+  }
+}