switchroom 0.11.1 → 0.12.0

package/telegram-plugin/gateway/gateway.ts

@@ -62,6 +62,7 @@ import {
   createRetryApiCall,
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
+  isHtmlParseRejectError,
 } from '../retry-api-call.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
 import { buildAttachmentPath, assertInsideInbox } from '../attachment-path.js'
@@ -137,7 +138,7 @@ import { validateStringArray } from './access-validator.js'
  * identical envelope shapes.
  */
 const REPLY_TO_TEXT_MAX = 200
-import { markdownToHtml, splitHtmlChunks, repairEscapedWhitespace } from '../format.js'
+import { markdownToHtml, splitHtmlChunks, repairEscapedWhitespace, telegramHtmlToPlainText } from '../format.js'
 import {
   validateInlineKeyboard,
   type AnyButton,
@@ -213,6 +214,7 @@ import {
 import {
   fetchQuota,
   formatQuotaBlock,
+  type QuotaResult,
 } from '../quota-check.js'
 import {
   loadLockout,
@@ -301,6 +303,7 @@ import {
 } from './boot-card.js'
 import { determineRestartReason } from './boot-reason.js'
 import { shouldSkipDuplicateBootCard, type RestartReason } from './boot-card.js'
+import { maybeRenderUpdateAnnouncement } from './update-announce.js'
 import { createIssuesCardHandle, type IssuesCardHandle } from '../issues-card.js'
 import { startIssuesWatcher, type IssuesWatcherHandle } from '../issues-watcher.js'
 import { list as listIssues, resolve as resolveIssue } from '../../src/issues/index.js'
@@ -2775,6 +2778,12 @@ const ipcServer: IpcServer = createIpcServer({
           // second bridge-reconnect in the same lifetime can't race against
           // an in-flight sendMessage here either (#489).
           bootCardPending = true
+          // PR C: surface the most recent terminal update_apply audit
+          // row if it lands within the lookback window AND no other
+          // boot has claimed it. Cheap (one file read + one O_EXCL).
+          const updateOutcomeLine = (() => {
+            try { return maybeRenderUpdateAnnouncement() ?? undefined } catch { return undefined }
+          })()
           startBootCard(chatId, threadId, botApiForCard, {
             agentName: agentDisplayName,
             agentSlug,
@@ -2785,8 +2794,10 @@ const ipcServer: IpcServer = createIpcServer({
             restartAgeMs: markerAgeMs,
             restartReasonDetail: cleanMarker?.reason,
             loadAccounts: () => loadAccountsForBootCard(agentSlug),
+            probeQuotaViaBroker: (t) => probeQuotaForBootCard(agentSlug, t),
             tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
             dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
+            ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
           }, ackMsgId).then(handle => {
             activeBootCard = handle
           }).catch((err: Error) => {
@@ -3484,6 +3495,31 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
         }
       }
 
+      // Last-resort: resend this chunk as plain text (parse_mode unset).
+      // Keeps thread / reply / markup params; only the formatting is
+      // sacrificed. Used when Telegram rejects our HTML — better an
+      // unformatted answer than a vanished one.
+      const sendChunkPlainText = async (opts: Record<string, unknown>): Promise<void> => {
+        const plainOpts = { ...opts }
+        delete (plainOpts as { parse_mode?: unknown }).parse_mode
+        // A chunk that was pure markup (no text content) strips to ''.
+        // Sending '' is a Telegram 400 "message text is empty" — i.e.
+        // the answer would still vanish, in the exact path that exists
+        // to prevent that. Substitute an honest placeholder so the
+        // user at least sees that a fragment was unrenderable.
+        const stripped = telegramHtmlToPlainText(chunks[i])
+        const plain =
+          stripped.length > 0
+            ? stripped
+            : '⚠️ (a formatted fragment could not be rendered for Telegram)'
+        const sent = await lockedBot.api.sendMessage(chat_id, plain, plainOpts as never)
+        sentIds.push(sent.message_id)
+        logOutbound('reply', chat_id, sent.message_id, plain.length, `chunk=${i + 1}/${chunks.length} plaintext-fallback`)
+        process.stderr.write(
+          `telegram gateway: HTML parse-reject — resent chunk ${i + 1}/${chunks.length} as plain text\n`,
+        )
+      }
+
       try {
         const sent = await robustApiCall(
           () => lockedBot.api.sendMessage(chat_id, chunks[i], sendOpts as never),
@@ -3496,8 +3532,16 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
           threadId = undefined
           const retryOpts = { ...sendOpts }
           delete (retryOpts as any).message_thread_id
-          const sent = await lockedBot.api.sendMessage(chat_id, chunks[i], retryOpts as never)
-          sentIds.push(sent.message_id)
+          try {
+            const sent = await lockedBot.api.sendMessage(chat_id, chunks[i], retryOpts as never)
+            sentIds.push(sent.message_id)
+          } catch (retryErr) {
+            // Thread dropped, but the HTML is also unparseable — go plain.
+            if (isHtmlParseRejectError(retryErr)) await sendChunkPlainText(retryOpts)
+            else throw retryErr
+          }
+        } else if (isHtmlParseRejectError(err)) {
+          await sendChunkPlainText(sendOpts)
         } else {
           throw err
         }
@@ -6658,7 +6702,7 @@ async function handleInbound(
       } else {
         // Fresh turn — priorTurnInFlight is false, so priorActive is
         // provably undefined. Earlier `if (priorActive)` block was dead
-        // code (mirrors first-paint.ts cleanup).
+        // code, removed in the same first-paint cleanup pass.
         const sKey = streamKey(chat_id, messageThreadId)
         const priorStream = activeDraftStreams.get(sKey)
         if (priorStream && !priorStream.isFinal()) {
@@ -7770,26 +7814,65 @@ async function runSwitchroomCommandFormatted(ctx: Context, args: string[], label
 // every agent can self-restart without admin privilege. `/restart <other>`
 // is blocked just like any other admin verb.
 //
-// Invariant: when AGENT_ADMIN=true, this middleware is a no-op — bot.command()
-// handlers run normally for all admin verbs and Claude never sees them.
+// sec WS7-F2 (#1394): when AGENT_ADMIN=true this middleware is NO LONGER a
+// no-op — a `block`-classified verb (fleet-admin / `/restart <other>`)
+// requires OPERATOR-PRIVATE (a private chat from a strict
+// `access.allowFrom` sender), because the per-command `isAuthorizedSender`
+// gate treats an empty group `allowFrom` as "allow every member". Non-
+// admin-verb traffic (`pass-through`, incl. `/restart`-self and all normal
+// chat) is untouched and reaches `next()` exactly as before.
 bot.use(async (ctx, next) => {
-  if (!AGENT_ADMIN && ctx.message?.text) {
+  if (ctx.message?.text) {
     const myName = getMyAgentName()
     const decision = classifyAdminGate(ctx.message.text, myName)
     if (decision.action === 'block') {
-      // Block admin commands the LLM should never see. Reply with a concise
-      // "admin required" warning instead of forwarding to Claude.
-      process.stderr.write(
-        `telegram gateway: admin-gate blocked cmd=/${decision.cmd} agent=${process.env.SWITCHROOM_AGENT_NAME ?? '-'} reason=${decision.reason} (AGENT_ADMIN=false)\n`,
-      )
+      // `block` = a fleet-admin verb (ADMIN_COMMAND_NAMES) or
+      // `/restart <other-agent>`. classifyAdminGate already lets
+      // `/restart`-self and every non-admin command pass through, so
+      // this branch is exactly the privileged set.
       const cmdHtml = escapeHtmlForTg(`/${decision.cmd}`)
       const nameHtml = escapeHtmlForTg(myName)
-      const text =
+      const notFlagged =
         decision.reason === 'other-agent'
           ? `⚠️ <code>${cmdHtml}</code> targeting another agent is an admin operation — this agent (<code>${nameHtml}</code>) isn't admin-flagged. Run it from an admin agent, or set <code>admin: true</code> for this agent in switchroom.yaml. (Self-restart is allowed: send <code>/restart</code> with no arg.)`
           : `⚠️ <code>${cmdHtml}</code> is an admin command — this agent (<code>${nameHtml}</code>) isn't admin-flagged. Run it from an admin agent, or set <code>admin: true</code> for this agent in switchroom.yaml.`
-      await switchroomReply(ctx, text, { html: true })
-      return
+      if (!AGENT_ADMIN) {
+        // Unchanged behaviour: a non-admin agent never executes admin
+        // verbs locally and must not forward them to Claude.
+        process.stderr.write(
+          `telegram gateway: admin-gate blocked cmd=/${decision.cmd} agent=${process.env.SWITCHROOM_AGENT_NAME ?? '-'} reason=${decision.reason} (AGENT_ADMIN=false)\n`,
+        )
+        await switchroomReply(ctx, notFlagged, { html: true })
+        return
+      }
+      // sec WS7-F2 (#1394): fleet-admin is OPERATOR-PRIVATE. Honor it
+      // ONLY in a private chat from an `access.allowFrom` sender.
+      // Before this, when AGENT_ADMIN=true the middleware was a no-op
+      // and the per-command `isAuthorizedSender` gate treats an empty
+      // group `allowFrom` as "allow every member" — so any member of
+      // an admin agent's forum/group could run /vault, /update apply,
+      // /grant, /dangerous, etc. (the default shape for an agent
+      // created via `agent add --topology forum` + `admin: true`).
+      // Strict `access.allowFrom` + private-chat-only — never the
+      // group-permissive isAuthorizedSender.
+      const senderId = String(ctx.from?.id ?? '')
+      const operatorPrivate =
+        ctx.chat?.type === 'private' &&
+        loadAccess().allowFrom.includes(senderId)
+      if (!operatorPrivate) {
+        process.stderr.write(
+          `telegram gateway: admin-gate refused (not operator-private) cmd=/${decision.cmd} agent=${process.env.SWITCHROOM_AGENT_NAME ?? '-'} chat=${ctx.chat?.type ?? '?'} sender=${senderId}\n`,
+        )
+        await switchroomReply(
+          ctx,
+          `⚠️ <code>${cmdHtml}</code> is a fleet-admin command — it is <b>operator-private</b>. Send it as a direct message to me from your operator account (a private chat where your Telegram ID is on the access allowlist), not in a group or forum.`,
+          { html: true },
+        )
+        return
+      }
+      // operator-private admin verb on an admin agent → fall through
+      // to the bot.command() handler (which re-checks isAuthorizedSender
+      // — redundant but harmless in a private allowFrom chat).
     }
   }
   await next()
@@ -7958,6 +8041,7 @@ async function buildLiveProbeRows(agentName: string): Promise<StatusProbeRow[]>
       gatewayInfo: { pid: process.pid, startedAtMs: GATEWAY_STARTED_AT_MS },
       tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
       dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
+      probeQuotaViaBroker: (t) => probeQuotaForBootCard(agentName, t),
     })
     const rows: StatusProbeRow[] = []
     // Render order matches the boot card's PROBE_KEYS so the two
@@ -8574,7 +8658,7 @@ bot.command('audit', async ctx => {
   if (arg === '' || arg === 'help' || arg === '--help') {
     await switchroomReply(
       ctx,
-      'Usage: <code>/audit hostd [--tail N] [--agent &lt;name&gt;] [--op &lt;verb&gt;] [--error]</code>',
+      'Usage: <code>/audit hostd [--tail N] [--agent &lt;name&gt;] [--op &lt;verb&gt;] [--error] [--verbose]</code>',
       { html: true },
     )
     return
@@ -8601,6 +8685,7 @@ bot.command('audit', async ctx => {
   for (let i = 1; i < tokens.length; i++) {
     const t = tokens[i]!
     if (t === '--error') { argv.push('--error'); continue }
+    if (t === '--verbose') { argv.push('--verbose'); continue }
     if (t === '--tail' || t === '--agent' || t === '--op') {
       const v = tokens[++i]
       if (v == null) {
@@ -8630,7 +8715,7 @@ bot.command('audit', async ctx => {
     await switchroomReply(
       ctx,
       `Unknown flag <code>${escapeHtmlForTg(t)}</code>. ` +
-      `Allowed: <code>--tail</code>, <code>--agent</code>, <code>--op</code>, <code>--error</code>.`,
+      `Allowed: <code>--tail</code>, <code>--agent</code>, <code>--op</code>, <code>--error</code>, <code>--verbose</code>.`,
       { html: true },
     )
     return
@@ -9011,7 +9096,39 @@ async function runCreditWatch(): Promise<void> {
 }
 
 bot.command("auth", async ctx => {
-  if (!isAuthorizedSender(ctx)) return
+  // sec WS7-F2b (#1394): `/auth` drives the auth-broker credential
+  // lifecycle (`/auth add` mints/attaches an Anthropic account token,
+  // `/auth use` switches the active account, …). It is NOT in
+  // ADMIN_COMMAND_NAMES (deliberately gateway-handled even on
+  // non-admin agents so it works when the model is unreachable — that
+  // routing is unchanged), so the WS7-F2 operator-private middleware
+  // does not cover it, and its only sender gate was the
+  // group-permissive `isAuthorizedSender` (empty group `allowFrom` =
+  // allow every member). On an `admin:true` forum agent any
+  // forum/supergroup member could therefore run privileged `/auth`.
+  // Credential-plane admin is OPERATOR-PRIVATE, exactly like the
+  // ADMIN_COMMAND_NAMES verbs (WS7-F2 / #1408): honor `/auth` ONLY in
+  // a private chat from a strict `access.allowFrom` sender — never the
+  // group-permissive isAuthorizedSender. The agent-admin-flag /
+  // broker-side enforcement (isAuthAdmin below) is orthogonal and
+  // unchanged; operator auth-recovery is via DM (same as #1408).
+  const authSenderId = String(ctx.from?.id ?? '')
+  const authOperatorPrivate =
+    ctx.chat?.type === 'private' &&
+    loadAccess().allowFrom.includes(authSenderId)
+  if (!authOperatorPrivate) {
+    if (ctx.chat?.type !== 'private') {
+      process.stderr.write(
+        `telegram gateway: /auth refused (not operator-private) agent=${process.env.SWITCHROOM_AGENT_NAME ?? '-'} chat=${ctx.chat?.type ?? '?'} sender=${authSenderId}\n`,
+      )
+      await switchroomReply(
+        ctx,
+        `⚠️ <code>/auth</code> manages account credentials — it is <b>operator-private</b>. Send it as a direct message to me from your operator account (a private chat where your Telegram ID is on the access allowlist), not in a group or forum.`,
+        { html: true },
+      ).catch(() => {})
+    }
+    return
+  }
   const text = ctx.message?.text ?? ""
   const parsed = parseAuthCommand(text)
   if (!parsed) return
@@ -9174,6 +9291,33 @@ async function loadAccountsForBootCard(agent: string): Promise<ListStateData | n
   }
 }
 
+/**
+ * Canonical boot-card quota probe (#1336): resolve this agent's
+ * effective account, then have the broker probe Anthropic server-side.
+ * Returns null on any failure (broker unreachable, no active account)
+ * so `probeQuota` falls back to a direct probe. Mirrors
+ * `loadAccountsForBootCard`'s broker-client + swallow-to-null shape,
+ * and the override→account→active resolution used by auth-line.ts.
+ */
+async function probeQuotaForBootCard(
+  agent: string,
+  timeoutMs?: number,
+): Promise<QuotaResult | null> {
+  try {
+    const client = await getAuthBrokerClient(agent)
+    if (!client) return null
+    const state = await client.listState()
+    const entry = state.agents.find((a) => a.name === agent)
+    const label = entry?.override ?? entry?.account ?? state.active
+    if (!label) return null
+    const { results } = await client.probeQuota([label], timeoutMs)
+    return results.find((r) => r.label === label)?.result ?? null
+  } catch (err) {
+    process.stderr.write(`telegram gateway: boot-card quota probe failed: ${(err as Error)?.message ?? String(err)}\n`)
+    return null
+  }
+}
+
 /**
  * Read the pending auth session's target slot from the agent's
  * `.setup-token.session.json` meta file. Returns null when no session
@@ -11501,7 +11645,24 @@ bot.on('callback_query:data', async ctx => {
   // Routed through the generic kernel handler so any surface that uses
   // buildApprovalCard inherits consume → record → confirmation UX without
   // each surface re-implementing it.
+  //
+  // SECURITY (sec WS7-F1, #1394): this is the human-in-the-loop gate for
+  // EVERY dangerous tool call + Drive write. handleApprovalCallback records
+  // whoever tapped as the approver (`granted_by_user_id = ctx.from.id`) and
+  // the approval-kernel performs NO server-side approver validation, so an
+  // unauthorized tap is laundered into a real grant. The card is delivered
+  // to the agent's chat(s) — for a forum/group agent that is every member.
+  // Refuse callbacks from anyone outside `access.allowFrom`, BEFORE the
+  // approval_consume nonce burn. Strict `access.allowFrom` — identical to
+  // the drvpick:/op:/vd:/vg:/vra:/vrs:/vrd: families; the absence of this
+  // check (not a deliberate exemption) was the vulnerability.
   if (data.startsWith('apv:')) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
     const { handleApprovalCallback } = await import('./approval-callback.js')
     await handleApprovalCallback(ctx, data)
     return
@@ -11512,10 +11673,11 @@ bot.on('callback_query:data', async ctx => {
   // grant writes an allow_always kernel decision at
   // doc:gdrive:folder/<id>/** and edits the card to a confirmation.
   //
-  // Auth gate: the picker grant is an OPERATOR action (mirrors the
-  // `op:`/`vd:`/`vg:` family, not the `apv:` agent-approval shape).
-  // Mirror those patterns — refuse callbacks from anyone outside
-  // `access.allowFrom`. Without this, a group member who isn't in
+  // Auth gate: the picker grant is an OPERATOR action — same strict
+  // `access.allowFrom` check as every other callback family (`op:`/
+  // `vd:`/`vg:`/`apv:` since sec WS7-F1, …). Refuse callbacks from
+  // anyone outside `access.allowFrom`. Without this, a group member
+  // who isn't in
   // the operator allowlist could still tap [✅ Allow "<folder>"] on
   // a card that landed in the group and write an `allow_always`
   // decision attributed to themselves.
@@ -13433,6 +13595,13 @@ void (async () => {
                   // sendMessage round-trip) sees an in-flight emit. See #489.
                   bootCardPending = true
                   try {
+                    // PR C: mirror the bridge-reconnect path — surface
+                    // a recent terminal update_apply outcome with claim
+                    // dedupe so it doesn't render twice if bridge
+                    // re-connects within the lookback window.
+                    const updateOutcomeLine = (() => {
+                      try { return maybeRenderUpdateAnnouncement() ?? undefined } catch { return undefined }
+                    })()
                     const handle = await startBootCard(chatId, threadId, botApiForCard, {
                       agentName: agentDisplayName,
                       agentSlug,
@@ -13443,8 +13612,10 @@ void (async () => {
                       restartAgeMs: markerAgeMs,
                       restartReasonDetail: cleanMarker?.reason,
                       loadAccounts: () => loadAccountsForBootCard(agentSlug),
+                      probeQuotaViaBroker: (t) => probeQuotaForBootCard(agentSlug, t),
                       tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
                       dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
+                      ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
                     }, ackMsgId)
                     activeBootCard = handle
                   } catch (err) {

package/telegram-plugin/gateway/update-announce.ts

@@ -0,0 +1,167 @@
+/**
+ * Update-flow PR C — boot-card surfacing for MCP-originated updates.
+ *
+ * When an agent (e.g. klanker) runs `mcp__hostd__update_apply` the work
+ * happens hostd-side, the agent itself restarts at the end, and the
+ * resulting boot card for THIS agent (the one that just restarted via
+ * the redeploy) needs to surface the outcome — success or failure with a
+ * recovery hint — so the operator sees what happened without trawling
+ * the audit log.
+ *
+ * Implementation: on boot, scan ~/.switchroom/host-control-audit.log for
+ * the most recent `phase: "terminal"` `update_apply` row within a recent
+ * window. Dedupe via an atomic O_EXCL marker so a respawn within the
+ * window doesn't re-announce. Render a single line that's appended to
+ * the existing boot-card body.
+ *
+ * Pure & test-friendly — `readLastTerminalUpdateAudit` accepts an
+ * injectable file-reader, `renderUpdateOutcomeLine` is a pure function,
+ * and `claimUpdateAnnouncement` accepts an injectable claim-dir + clock.
+ */
+
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { readAndFilter, defaultAuditLogPath, type AuditEntry } from '../../src/host-control/audit-reader.js'
+
+/** Default lookback window: 10 minutes is enough to catch the boot that
+ *  follows a normal update_apply but small enough that an audit row from
+ *  yesterday's run can't re-trigger an announcement after a long
+ *  outage. */
+export const DEFAULT_LOOKBACK_MS = 10 * 60 * 1000
+
+export interface ReadOpts {
+  /** Read the file system. Override in tests. */
+  readFile?: (path: string) => string
+  /** Exists check. Override in tests. */
+  exists?: (path: string) => boolean
+  /** Override the audit-log path (defaults to ~/.switchroom/host-control-audit.log). */
+  auditLogPath?: string
+  /** Wall-clock for the lookback comparison. */
+  now?: number
+  /** Lookback window in ms. Defaults to {@link DEFAULT_LOOKBACK_MS}. */
+  lookbackMs?: number
+}
+
+/**
+ * Read the audit log and return the most-recent `update_apply` terminal
+ * row within the lookback window, or null if none. We deliberately do
+ * not filter by caller — any update_apply outcome is interesting to the
+ * person watching this chat regardless of which agent ran the verb.
+ */
+export function readLastTerminalUpdateAudit(opts: ReadOpts = {}): AuditEntry | null {
+  const path = opts.auditLogPath ?? defaultAuditLogPath()
+  const exists = opts.exists ?? existsSync
+  const readFile = opts.readFile ?? ((p: string) => readFileSync(p, 'utf-8'))
+  if (!exists(path)) return null
+  let raw: string
+  try {
+    raw = readFile(path)
+  } catch {
+    return null
+  }
+  // Pull recent update_apply rows, then trim to terminal-phase within window.
+  const recent = readAndFilter(raw, { op: 'update_apply' }, 200)
+  const now = opts.now ?? Date.now()
+  const since = now - (opts.lookbackMs ?? DEFAULT_LOOKBACK_MS)
+  let best: AuditEntry | null = null
+  for (const e of recent) {
+    if (e.phase !== 'terminal') continue
+    const ts = Date.parse(e.ts)
+    if (Number.isNaN(ts)) continue
+    if (ts < since) continue
+    if (best == null || Date.parse(best.ts) < ts) best = e
+  }
+  return best
+}
+
+const RECOVERY_HINTS: Record<string, string> = {
+  binary:
+    'curl https://switchroom.ai/install.sh | sh && switchroom update',
+  source:
+    'cd ~/code/switchroom && git pull && bun install && bun run build && switchroom update',
+  'source-unlinked':
+    'cd ~/code/switchroom && bun link && switchroom update  # ensures binary is in PATH first',
+  docker:
+    'docker compose -p switchroom pull && docker compose -p switchroom up -d',
+  unknown:
+    'Cannot auto-detect install type. Run `switchroom apply` to refresh ~/.switchroom/install-type.json, then retry.',
+}
+
+function recoveryHint(installType: string | undefined): string {
+  if (!installType) return RECOVERY_HINTS.unknown
+  return RECOVERY_HINTS[installType] ?? RECOVERY_HINTS.unknown
+}
+
+function shortSha(s: string): string {
+  return s.replace(/^sha256:/, '').slice(0, 12)
+}
+
+/**
+ * Pure renderer. Returns the single line (HTML-safe — plain ASCII)
+ * to append to the boot card body. `null` means nothing to surface
+ * (entry too stale, schema invalid, etc.).
+ */
+export function renderUpdateOutcomeLine(entry: AuditEntry): string {
+  const success = entry.exit_code === 0 && entry.result !== 'error' && entry.result !== 'denied'
+  if (success) {
+    const channel = entry.channel ? `channel:${entry.channel}` : entry.pin ? `pin:${entry.pin}` : 'channel:?'
+    let shaStr = ''
+    if (entry.resolved_sha) {
+      const firstSha = Object.values(entry.resolved_sha)[0]
+      if (firstSha) shaStr = `, sha:${shortSha(firstSha)}`
+    }
+    return `✅ update completed (${channel}${shaStr})`
+  }
+  const stderrTail = (entry.stderr_tail ?? entry.error ?? '').slice(-400)
+  const opStep = entry.op
+  const hint = recoveryHint(entry.install_context?.install_type)
+  // Single line is reader-friendly when short; multi-line when stderr is present.
+  const lines = [`❌ update failed at ${opStep}: ${stderrTail || '(no stderr captured)'}`, `    ↳ Recovery: ${hint}`]
+  return lines.join('\n')
+}
+
+export interface ClaimOpts {
+  /** Override state-dir base (default: $TELEGRAM_STATE_DIR or ~/.switchroom/<agent>/telegram). */
+  stateDir?: string
+}
+
+/**
+ * Atomic claim via `O_CREAT|O_EXCL` — returns true if THIS process is
+ * the first to announce this request_id. Idempotent across respawns
+ * within the same state-dir. We deliberately don't clean up old
+ * markers — they're tiny and bounded by the lookback window above.
+ */
+export function claimUpdateAnnouncement(requestId: string, opts: ClaimOpts = {}): boolean {
+  const stateDir = opts.stateDir ?? process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.switchroom')
+  const dir = join(stateDir, 'update-announced')
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {
+    return false
+  }
+  const safeId = requestId.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 200)
+  const path = join(dir, safeId)
+  try {
+    // O_CREAT | O_EXCL — fails with EEXIST if another boot already
+    // claimed this request_id.
+    const fd = openSync(path, 'wx')
+    closeSync(fd)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Combined entry-point used by the gateway boot path: read + claim +
+ * render. Returns the line to append (already escaped for HTML — plain
+ * ASCII text — caller embeds with no further processing) or null when
+ * there's nothing to surface OR another boot already claimed the row.
+ */
+export function maybeRenderUpdateAnnouncement(opts: ReadOpts & ClaimOpts = {}): string | null {
+  const entry = readLastTerminalUpdateAudit(opts)
+  if (!entry) return null
+  if (!claimUpdateAnnouncement(entry.request_id, opts)) return null
+  return renderUpdateOutcomeLine(entry)
+}