switchroom 0.21.12 → 0.21.13

package/skills/switchroom-status/scripts/status.sh

@@ -22,18 +22,16 @@ RAW=$(switchroom agent list --json 2>/dev/null) || {
   exit 1
 }
 
-if [ -z "$RAW" ] || [ "$RAW" = "[]" ]; then
+if [ -z "$RAW" ] || [ "$RAW" = '{"agents":[]}' ]; then
   echo "No agents configured."
   exit 0
 fi
 
-TOTAL=$(echo "$RAW" | python3 -c "import sys,json; agents=json.load(sys.stdin); print(len(agents))" 2>/dev/null || echo "?")
-RUNNING=0
-
 echo "$RAW" | python3 -c "
-import sys, json, datetime
+import sys, json
 
-agents = json.load(sys.stdin)
+payload = json.load(sys.stdin)
+agents = payload.get('agents', [])
 running = 0
 
 for a in agents:
@@ -41,11 +39,9 @@ for a in agents:
     status  = a.get('status', 'unknown')
     model   = a.get('model', 'unknown')
     topic   = a.get('topic_name', '')
-    coll    = a.get('memory', {}).get('collection', '')
     uptime  = a.get('uptime', '')
-    pid     = a.get('pid', '')
 
-    status_icon = '✓' if status == 'running' else '✗' if status in ('stopped','failed') else '?'
+    status_icon = '✓' if status == 'active' else '✗' if status in ('inactive', 'exited', 'dead') else '?'
 
     line = f'{status_icon} {name}'
     if topic:
@@ -54,16 +50,11 @@ for a in agents:
     if uptime:
         line += f' ({uptime})'
     print(line)
-    print(f'    model: {model}', end='')
-    if coll:
-        print(f'  collection: {coll}', end='')
-    if pid:
-        print(f'  pid: {pid}', end='')
-    print()
+    print(f'    model: {model}')
     print()
 
-    if status == 'running':
+    if status == 'active':
         running += 1
 
 print(f'{running} of {len(agents)} agents running.')
-" 2>/dev/null || echo "$RAW"
+"

package/skills/telegram-test-harness/SKILL.md

@@ -23,8 +23,12 @@ at `telegram-plugin/tests/`. Use it to lock in the Bot API call
 sequences switchroom emits — what the user actually sees in chat — so
 regressions fail a test instead of going silent in production.
 
-This skill is a quick-reference for that harness. The full guide lives
-at [`telegram-plugin/tests/HARNESS.md`](../../telegram-plugin/tests/HARNESS.md).
+This skill is the reference for that harness — there is no separate
+`HARNESS.md` guide file (it existed briefly, was deleted in the pinned
+progress-card removal (#1126), and was never recreated). Read the fake
+implementations directly for the authoritative contract:
+`telegram-plugin/tests/fake-bot-api.ts`, `update-factory.ts`,
+`bot-api.harness.ts`.
 
 ## When to use this harness
 
@@ -147,8 +151,6 @@ Example pairs:
 
 - `slot-banner.test.ts` (pure decision) +
   `slot-banner-driver.e2e.test.ts` (Bot API dispatch)
-- `auto-fallback.test.ts` (pure plan) +
-  `auto-fallback-dispatcher.e2e.test.ts` (notification dispatch)
 
 ## Test-design checklist
 
@@ -187,7 +189,6 @@ Before writing the test, ask:
 
 ## See also
 
-- `telegram-plugin/tests/HARNESS.md` — full guide
 - `telegram-plugin/tests/fake-bot-api.test.ts` — meta-test of the fake;
   read first when adding new fake-bot capabilities
 - `telegram-plugin/tests/streaming-e2e.test.ts` — worked example of a

package/telegram-plugin/dist/gateway/gateway.js

@@ -21648,7 +21648,7 @@ var init_observation_scopes = __esm(() => {
 });
 
 // ../src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, GoogleWorkspaceConfigSchema, LiteLLMConfigSchema, HindsightPerOpLlmSchema, HindsightConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, MicrosoftAccountEmailSchema, MicrosoftToolTokenSchema, MicrosoftAccountBindingSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, releaseBlockFields, ReleaseBlock, RootReleaseBlock, NetworkIsolationSchema, servesField, knowsField, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, PollSpecSchema, TelegramMessageActionSchema, WebhookActionSchema, ActionSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, ObservationScopesSchema, ObservationScopeStrategySchema, AntiConfabulationDirectiveSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, webhookDispatchRule, TelegramChannelSchema, BuzzChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleServiceTokenSchema, GoogleWorkspaceConfigSchema, LiteLLMConfigSchema, HindsightPerOpLlmSchema, HindsightConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, MicrosoftAccountEmailSchema, MicrosoftToolTokenSchema, MicrosoftAccountBindingSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReactionDispatchSchema, releaseBlockFields, ReleaseBlock, RootReleaseBlock, NetworkIsolationSchema, servesField, knowsField, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, ScratchConfigSchema, DiskConfigSchema, HostControlConfigSchema, WebServiceConfigSchema, FleetHealthConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, UserSchema, ConfigRepoConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   init_observation_scopes();
@@ -22521,6 +22521,27 @@ var init_schema = __esm(() => {
     notify_on_detect: exports_external.boolean().default(false).describe("KEN-129 \u2014 operator-in-the-loop update prompt. Only consulted " + "when apply_on_detect is false (auto-apply supersedes notify): " + "a newly detected release posts ONE operator approval card " + "('fleet is behind \u2014 tap to apply') via an admin agent's " + "gateway; Approve runs hostd's update_apply path (fleet-" + "mutation-locked, durable status rows, get_status-pollable). " + "Dedup on release id: the last-notified id persists in " + "~/.switchroom/release-notify-state.json, so a card that " + "reached the operator is never re-posted for the same release."),
     image_ref: exports_external.string().default("ghcr.io/switchroom/switchroom-agent:latest").describe("Image reference whose remote digest is compared to the local " + "image digest. Defaults to the agent image's :latest tag, which " + "is the canonical signal that a release has been promoted.")
   });
+  ScratchConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true).describe("Whether agents get a scratch mount at /scratch with their package " + "caches redirected there. Default: true \u2014 but the feature only " + "engages when `volume` actually exists on the host, so a single-disk " + "machine is unaffected. Set false to opt out even where it does."),
+    volume: exports_external.string().refine((v) => v.startsWith("/"), {
+      message: "scratch.volume must be an absolute host path"
+    }).default("/mnt/bulkdata").describe("Absolute host path of the bulk device's mountpoint. MUST already " + "exist \u2014 its presence is the single probe that turns the feature on, " + "so a typo degrades to the pre-existing behaviour rather than " + "quietly relocating caches somewhere that is still the root disk. " + "Default: /mnt/bulkdata."),
+    subdir: exports_external.string().refine((v) => !v.startsWith("/") && !v.split("/").includes(".."), {
+      message: "scratch.subdir must be a relative path without '..' segments"
+    }).default("switchroom/scratch").describe("Relative path under `volume` holding the per-agent scratch " + "directories (`<volume>/<subdir>/<agent>`). Default: " + "switchroom/scratch.")
+  });
+  DiskConfigSchema = exports_external.object({
+    warn_pct: exports_external.number().int().min(1).max(99).default(80).describe("Used-percentage at or above which `switchroom doctor` WARNs about " + "the filesystem holding the agents directory. Default 80 \u2014 the " + "reference fleet was at 85% when the condition was found by hand."),
+    fail_pct: exports_external.number().int().min(2).max(100).default(90).describe("Used-percentage at or above which `switchroom doctor` FAILs. Must " + "be greater than `warn_pct`. Default 90."),
+    reap_report: exports_external.object({
+      enabled: exports_external.boolean().default(true).describe("Whether doctor checks that the report-only worktree sweep " + "(`switchroom worktree reap-report --append <file>`) is actually " + "running. Set false on a host that deliberately does not run it."),
+      log: exports_external.string().min(1).default("/var/log/switchroom/reap-report.jsonl").describe("Path of the JSONL evidence log the scheduled `worktree " + "reap-report --append` writes. Doctor reads the newest record's " + "`generatedAt` \u2014 it detects the sweep by its OUTPUT, so it is " + "agnostic about whether an operator crontab, /etc/cron.d, or a " + "systemd timer drives it. Default " + "/var/log/switchroom/reap-report.jsonl (the path documented in " + "docs/operators/worktree-gc.md)."),
+      max_age_hours: exports_external.number().int().min(1).max(720).default(48).describe("How old the newest record in `log` may be before doctor WARNs " + "that the sweep has stopped running. Default 48 \u2014 twice the " + "documented daily cadence, so a single missed run is not noise.")
+    }).default({}).describe("Liveness check for the report-only worktree sweep. REPORT-ONLY by " + "construction: doctor reads an evidence log and never invokes any " + "reclaim path.")
+  }).refine((v) => v.fail_pct > v.warn_pct, {
+    message: "disk.fail_pct must be greater than disk.warn_pct",
+    path: ["fail_pct"]
+  });
   HostControlConfigSchema = exports_external.object({
     enabled: exports_external.boolean().default(true).describe("Whether the host-control daemon is in use. Default: true (since " + "RFC C Phase 2 default-flip \u2014 the gateway's /restart, /new, /reset, " + "and /update apply slash-commands all dispatch through hostd, and " + "without it those verbs fail on docker-mode installs because the " + "agent container has no docker binary/socket). " + "When true, the compose generator emits per-agent bind mounts " + "at `~/.switchroom/hostd/<name>/sock` for every admin-flagged " + "agent. Install the daemon with `switchroom hostd install` \u2014 " + "it runs as a docker container in its own compose project " + "(`switchroom-hostd`), separate from the agent fleet's compose " + "project so `up -d --remove-orphans` cycles of the fleet " + "can't recreate the daemon mid-RPC. See RFC C \u00a75.1. " + "Set enabled: false only on legacy systemd-mode installs that " + "still rely on the in-container `spawnSwitchroomDetached` " + "shellout (removal is tracked as RFC C Phase 3)."),
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
@@ -22595,6 +22616,8 @@ var init_schema = __esm(() => {
     microsoft_workspace: MicrosoftWorkspaceConfigSchema.describe("RFC #1873 (Microsoft 365 integration). Top-level Microsoft Workspace " + "configuration \u2014 OAuth client credentials (Entra app), authority " + "endpoint (defaults to /common for personal MSA + work), and the " + "org_mode opt-in for Teams/SharePoint surfaces. Block is optional; " + "when omitted the broker does not register the Microsoft provider."),
     notion_workspace: NotionWorkspaceConfigSchema.describe("RFC reference/rfcs/notion-integration.md. Top-level Notion integration " + "config \u2014 vault key for the integration token, friendly-name \u2192 " + "database UUID map, optional MCP-package version pin, and optional " + "global rate-limit override (default 3 rps, Notion's documented " + "public-API limit). Block is optional; when omitted no agent gets a " + "Notion MCP entry regardless of per-agent config."),
     quota: QuotaConfigSchema.optional().describe("Optional weekly/monthly USD spend budgets rendered in the session " + "greeting. Usage is read from ccusage at runtime; no network calls."),
+    scratch: ScratchConfigSchema.optional().describe("Per-agent scratch volume. Relocates every agent's build/package " + "caches (uv, npm, bun, playwright, puppeteer, pip user-site) off the " + "root disk onto a bulk device, bind-mounted at /scratch inside each " + "container. Framework-injected for EVERY agent \u2014 not routed through " + "the admin-only `bind_mounts:` escalation, because the biggest cache " + "consumers are ordinary non-admin agents. Omit the block to accept " + "defaults; the feature is a no-op unless `scratch.volume` exists on " + "the host."),
+    disk: DiskConfigSchema.default({}).describe("Root-disk headroom thresholds for `switchroom doctor`. Measured " + "against the filesystem holding the agents directory (and the scratch " + "volume when that feature is engaged), not against `/`. Omit the block " + "to accept the defaults (WARN at 80% used, FAIL at 90%)."),
     host_control: HostControlConfigSchema.default({}).describe("Host-control daemon configuration. Defaults to enabled=true since " + "RFC C Phase 2 (reference/rfcs/host-control-daemon.md). Omit the block " + "to accept defaults; set `enabled: false` only on legacy systemd-" + "mode installs (removal tracked as RFC C Phase 3)."),
     hostd: HostdConfigSchema.default({}).describe("hostd verb-level knobs (RFC admin-agent-config-edit). Distinct " + "from `host_control:` which governs whether the daemon runs at " + "all. Scopes the opt-in flag and rate cap for the " + "`config_propose_edit` verb (disabled by default)."),
     fleet_health: FleetHealthConfigSchema.default({}).describe("Fleet Health \u2014 job-spec-anchored, operator-facing issue tracker (RFC " + "fleet-health.md, serves fleet-stays-healthy). Assigns the owner agent " + "that runs the nightly model-free sensor + weekly deep-dive. Default " + "unset owner_agent \u2192 inert; the admin page renders an empty state."),
@@ -67956,6 +67979,110 @@ function resolveSendContext(payload) {
   };
 }
 
+// shared/utf8-sanitize.ts
+var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+function hasLoneSurrogate(s) {
+  LONE_SURROGATE.lastIndex = 0;
+  return LONE_SURROGATE.test(s);
+}
+function countLoneSurrogates(s) {
+  return (s.match(LONE_SURROGATE) ?? []).length;
+}
+function sanitizeLoneSurrogates(s) {
+  if (!hasLoneSurrogate(s))
+    return s;
+  return s.replace(LONE_SURROGATE, "\ufffd");
+}
+function isWalkable(v) {
+  if (Array.isArray(v))
+    return true;
+  if (v === null || typeof v !== "object")
+    return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+var MAX_DEPTH3 = 16;
+function defineOwn(out, k, v) {
+  Object.defineProperty(out, k, {
+    value: v,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  });
+}
+function sanitizePayloadStrings(value, depth = 0, stats) {
+  if (typeof value === "string") {
+    const next = sanitizeLoneSurrogates(value);
+    if (stats && next !== value)
+      stats.repaired += countLoneSurrogates(value);
+    return next;
+  }
+  if (depth >= MAX_DEPTH3 || !isWalkable(value))
+    return value;
+  if (Array.isArray(value)) {
+    let out2;
+    for (let i = 0;i < value.length; i++) {
+      const item = value[i];
+      const next = sanitizePayloadStrings(item, depth + 1, stats);
+      if (out2 === undefined && next !== item)
+        out2 = value.slice(0, i);
+      if (out2 !== undefined)
+        out2.push(next);
+    }
+    return out2 ?? value;
+  }
+  const hasOwn = Object.prototype.hasOwnProperty;
+  let out;
+  for (const k in value) {
+    if (!hasOwn.call(value, k))
+      continue;
+    const v = value[k];
+    const next = sanitizePayloadStrings(v, depth + 1, stats);
+    if (out === undefined && next !== v) {
+      out = {};
+      for (const prev in value) {
+        if (prev === k)
+          break;
+        if (!hasOwn.call(value, prev))
+          continue;
+        defineOwn(out, prev, value[prev]);
+      }
+    }
+    if (out !== undefined)
+      defineOwn(out, k, next);
+  }
+  return out ?? value;
+}
+var LOG_THROTTLE_MS = 60000;
+function installUtf8Sanitizer(bot, now = Date.now) {
+  const lastLoggedAtByMethod = new Map;
+  const shouldLogRepair = (method, at) => {
+    const last = lastLoggedAtByMethod.get(method);
+    if (last !== undefined && at - last < LOG_THROTTLE_MS)
+      return false;
+    lastLoggedAtByMethod.set(method, at);
+    return true;
+  };
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    let clean = payload;
+    const stats = { repaired: 0 };
+    try {
+      clean = sanitizePayloadStrings(payload, 0, stats);
+    } catch (err) {
+      clean = payload;
+      if (shouldLogRepair(`${method}\x00sanitize-failed`, now())) {
+        process.stderr.write(`telegram gateway: utf8-sanitize FAILED OPEN method=${method} \u2014 ` + `payload sent unrepaired; if it carries a lone surrogate Telegram ` + `will reject it (400 "strings must be encoded in UTF-8"): ` + `${err instanceof Error ? err.message : String(err)}
+`);
+      }
+    }
+    if (clean !== payload && shouldLogRepair(method, now())) {
+      process.stderr.write(`telegram gateway: utf8-sanitize repaired ${stats.repaired} lone surrogate(s) ` + `method=${method} \u2014 body would have been rejected by Telegram ` + `(400 "strings must be encoded in UTF-8")
+`);
+    }
+    return prev(method, clean, signal);
+  });
+}
+
 // shared/sent-text-capture.ts
 var SENT_TEXT = Symbol.for("switchroom.telegram.sentText");
 var MAX_BLOCK_DEPTH = 8;
@@ -105739,10 +105866,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.21.12";
-var COMMIT_SHA = "66041822";
-var COMMIT_DATE = "2026-08-14T20:57:00Z";
-var LATEST_PR = 4717;
+var VERSION2 = "0.21.13";
+var COMMIT_SHA = "4a70ee58";
+var COMMIT_DATE = "2026-08-15T09:11:57Z";
+var LATEST_PR = 4734;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -119159,6 +119286,7 @@ async function initGatewayBot() {
     process.exit(1);
   }
   bot = new import_grammy17.Bot(TOKEN);
+  installUtf8Sanitizer(bot);
   installTgPostLogger(bot);
   installRichMarkdownGuard(bot);
   installSentTextCapture(bot);

package/telegram-plugin/gateway/gateway.ts

@@ -303,6 +303,7 @@ import { installEditFloodFuse, editFloodFuseConfigFromEnv } from '../edit-flood-
 import { createSendGate, sendGateConfigFromEnv, isSendGateShed } from '../send-gate.js'
 import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
 import { installTgPostLogger, installRichMarkdownGuard, withTgPostTags, withTgSendContext, installSystemMessageObserver } from '../shared/bot-runtime.js'
+import { installUtf8Sanitizer } from '../shared/utf8-sanitize.js'
 import { installSentTextCapture } from '../shared/sent-text-capture.js'
 import {
   floodStatePath,
@@ -22873,6 +22874,7 @@ async function initGatewayBot(): Promise<void> {
   }
 
   bot = new Bot(TOKEN)
+  installUtf8Sanitizer(bot) // #4728: installed FIRST so it composes INNERMOST — the last thing to touch the payload before serialisation; see installUtf8Sanitizer docblock
   installTgPostLogger(bot); installRichMarkdownGuard(bot) // #3252/#3463: universal fmt guard installed after logger (composes outermost); see installRichMarkdownGuard docblock
   // #4576 follow-up: FALLBACK card body. The observer takes the stored body off
   // the RESPONSE (`rich_message` → `text`/`caption`); this stamps the REQUEST body

package/telegram-plugin/shared/utf8-sanitize.ts

@@ -0,0 +1,269 @@
+/**
+ * Wire-level UTF-8 sanitiser (#4728).
+ *
+ * ── The failure this exists to stop ───────────────────────────────────────
+ *
+ * A JavaScript string is UTF-16, and UTF-16 permits a LONE SURROGATE — a high
+ * (`\uD800`-`\uDBFF`) or low (`\uDC00`-`\uDFFF`) code unit with no partner.
+ * A lone surrogate has NO valid UTF-8 encoding. `JSON.stringify` does not
+ * throw on one (well-formed `JSON.stringify`, ES2019): it emits the `\udXXX`
+ * escape, so grammy happily POSTs a body Telegram's decoder then rejects with
+ *
+ *     400 Bad Request: strings must be encoded in UTF-8
+ *
+ * Observed in production on 2026-07-31 (agent `gymbro`, twice): a
+ * `permission_request` approval card 400'd on `sendRichMessage` with exactly
+ * that description and the operator never saw the card. An approval card is
+ * the human safety boundary for a gated tool call — a dropped card means a
+ * gated action silently never happens.
+ *
+ * ── Why HERE and not in the card formatter ────────────────────────────────
+ *
+ * The plugin already repairs a *trailing* high surrogate at each of its
+ * truncation sites (`card-layout.ts:384`, `format.ts:1551`,
+ * `tool-activity-summary.ts:488`, `reply-quote.ts:78`). Every one of those is
+ * a per-cut patch that (a) only covers the cut it guards and (b) only covers
+ * the HIGH half — an orphaned LOW surrogate, or a lone surrogate that entered
+ * the body from upstream data (a tool `input_preview`, a file path, a
+ * model-emitted token) rather than from a cut, sails straight through all of
+ * them onto the wire. So the repair belongs at the ONE place every outbound
+ * call must transit: the grammy API-transformer layer, which no `ctx.*`
+ * helper and no raw `bot.api.*` call can bypass
+ * (see `shared/bot-runtime.ts` header).
+ *
+ * The sanitiser walks the WHOLE payload, not a named field list, because a
+ * lone surrogate anywhere in the JSON body fails the whole request — inline
+ * keyboard button labels (`reply_markup`, which every approval card carries),
+ * captions, `rich_message.markdown` and plain `text` alike.
+ *
+ * Substitution is U+FFFD REPLACEMENT CHARACTER rather than deletion: it is
+ * the Unicode-standard substitution, and it is length-preserving in UTF-16
+ * code units, so a body that was sized against a char budget upstream cannot
+ * be pushed over that budget by the repair.
+ */
+
+import type { Bot } from 'grammy'
+
+/**
+ * Matches a code unit that is a surrogate with no partner:
+ * a high surrogate not followed by a low one, or a low surrogate not
+ * preceded by a high one. A well-formed pair matches neither alternative.
+ */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+
+/** True when `s` contains at least one unpaired surrogate. */
+export function hasLoneSurrogate(s: string): boolean {
+  LONE_SURROGATE.lastIndex = 0
+  return LONE_SURROGATE.test(s)
+}
+
+/**
+ * How many unpaired surrogate code units `s` carries. Safe to call on the
+ * shared `/g` regex: `String.prototype.match` with a global pattern resets
+ * `lastIndex` to 0 itself before it collects, so this cannot leak state into
+ * `hasLoneSurrogate`.
+ */
+function countLoneSurrogates(s: string): number {
+  return (s.match(LONE_SURROGATE) ?? []).length
+}
+
+/**
+ * Replace every unpaired surrogate in `s` with U+FFFD. Returns the SAME
+ * string instance when there is nothing to repair, so callers can use
+ * identity to detect a no-op. Idempotent: U+FFFD is not a surrogate.
+ */
+export function sanitizeLoneSurrogates(s: string): string {
+  if (!hasLoneSurrogate(s)) return s
+  return s.replace(LONE_SURROGATE, '�')
+}
+
+/**
+ * True for a value we may safely recurse into and rebuild: a plain object or
+ * an array. Anything else (an `InputFile`, a `Buffer`, a stream, a `Date`,
+ * a class instance) is returned untouched — rebuilding it would destroy its
+ * prototype and grammy's multipart layer depends on those identities.
+ */
+function isWalkable(v: unknown): v is Record<string, unknown> | unknown[] {
+  if (Array.isArray(v)) return true
+  if (v === null || typeof v !== 'object') return false
+  const proto = Object.getPrototypeOf(v)
+  return proto === Object.prototype || proto === null
+}
+
+/** Depth cap: Telegram payloads are shallow (deepest real nesting is
+ * `reply_markup.inline_keyboard[][]`, depth 3). The cap is a cheap guard
+ * against a pathological or cyclic input, never reached in practice. */
+const MAX_DEPTH = 16
+
+/** Mutable tally threaded through the walk so the caller can log HOW MANY
+ * code units were repaired without ever seeing the content itself. */
+export interface SanitizeStats {
+  /** Total unpaired surrogate code units replaced with U+FFFD. */
+  repaired: number
+}
+
+/**
+ * Define `k` as an own enumerable data property of `out`.
+ *
+ * `out[k] = v` would REASSIGN the clone's prototype for the single key
+ * `__proto__` (the `Object.prototype` accessor), silently dropping an own
+ * `__proto__` key from the payload. defineProperty always makes an own data
+ * property, for that key like any other.
+ */
+function defineOwn(out: Record<string, unknown>, k: string, v: unknown): void {
+  Object.defineProperty(out, k, {
+    value: v,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  })
+}
+
+/**
+ * Deep-sanitise every string in `value`, CLONE-ON-WRITE: the input is never
+ * mutated, and the exact same instance is returned when nothing changed.
+ *
+ * The clone is materialised LAZILY, on the first key/index that actually
+ * changed — so a clean payload allocates no container and performs no
+ * property definition at any depth, it is only walked and handed back by
+ * identity. That matters: this runs on the innermost hop of EVERY `bot.api.*`
+ * call, including the draft-stream `editMessageText` path that edits the same
+ * card several times a second, and the overwhelming majority of payloads are
+ * clean. (Pinned by the "clean nested payload" test, which fails if any
+ * container is rebuilt.)
+ *
+ * Pass `stats` to collect the repair count.
+ */
+export function sanitizePayloadStrings<T>(value: T, depth = 0, stats?: SanitizeStats): T {
+  if (typeof value === 'string') {
+    const next = sanitizeLoneSurrogates(value)
+    if (stats && next !== value) stats.repaired += countLoneSurrogates(value)
+    return next as unknown as T
+  }
+  if (depth >= MAX_DEPTH || !isWalkable(value)) return value
+
+  if (Array.isArray(value)) {
+    let out: unknown[] | undefined
+    for (let i = 0; i < value.length; i++) {
+      const item = value[i]
+      const next = sanitizePayloadStrings(item, depth + 1, stats)
+      // First change: copy the already-walked prefix, all of it unchanged.
+      if (out === undefined && next !== item) out = value.slice(0, i)
+      if (out !== undefined) out.push(next)
+    }
+    return (out ?? value) as unknown as T
+  }
+
+  // `for...in` rather than `Object.entries`, so the clean path allocates no
+  // key/entry array either. The `hasOwnProperty` guard keeps this EXACTLY
+  // equivalent to `Object.entries`: `for...in` also yields INHERITED
+  // enumerable keys, so without it a polluted `Object.prototype` would leak an
+  // extra field into the body we hand to Telegram.
+  const hasOwn = Object.prototype.hasOwnProperty
+  let out: Record<string, unknown> | undefined
+  for (const k in value) {
+    if (!hasOwn.call(value, k)) continue
+    const v = (value as Record<string, unknown>)[k]
+    const next = sanitizePayloadStrings(v, depth + 1, stats)
+    if (out === undefined && next !== v) {
+      // First change: materialise the clone and backfill the keys already
+      // walked, every one of which came back unchanged. This re-reads those
+      // properties (so an own getter in the prefix is invoked twice), which
+      // only ever happens on the repair path — a payload with an own getter
+      // AND a lone surrogate. Telegram payloads are plain data; a getter that
+      // throws is caught by the fail-open guard in `installUtf8Sanitizer`.
+      out = {}
+      for (const prev in value) {
+        if (prev === k) break
+        if (!hasOwn.call(value, prev)) continue
+        defineOwn(out, prev, (value as Record<string, unknown>)[prev])
+      }
+    }
+    if (out !== undefined) defineOwn(out, k, next)
+  }
+  return (out ?? value) as unknown as T
+}
+
+/** One log line per method per minute. The draft-stream `editMessageText`
+ * path edits the same card many times a second, so an upstream that is
+ * PERSISTENTLY corrupt would otherwise emit a line per edit and drown the
+ * gateway log in the exact situation you most need to read it. */
+const LOG_THROTTLE_MS = 60_000
+
+/**
+ * Install the UTF-8 sanitiser as a grammy API transformer.
+ *
+ * MUST be installed FIRST, before every other transformer: grammy composes
+ * `call = trans(prev, ...)` (`grammy/out/core/client.js:9-11,91`), so the
+ * LAST-installed transformer is the OUTERMOST and the FIRST-installed is the
+ * INNERMOST — the one that sees the final payload immediately before it is
+ * serialised and POSTed. Anything installed after this one can therefore not
+ * reintroduce a lone surrogate behind its back.
+ *
+ * A repair is logged with the method and the repaired code-unit COUNT — never
+ * the body, which may carry operator content — so a corrupt upstream producer
+ * stays diagnosable instead of being silently papered over. The line is
+ * throttled to once per method per minute.
+ *
+ * The sanitise call FAILS OPEN. It runs on the innermost hop of every single
+ * `bot.api.*` call, and its object walk reads own enumerable properties —
+ * which invokes getters. A throwing getter, or any future bug in the walk,
+ * would otherwise propagate out of every outbound call and wedge the whole
+ * gateway. Sending the original payload is never worse than throwing: the
+ * worst case is the pre-#4728 behaviour (Telegram 400s that one send), while
+ * throwing here breaks sends that had nothing wrong with them. It is not
+ * silent, though: failing open logs its own throttled line naming the method,
+ * so the degraded state stays diagnosable.
+ *
+ * `now` is an injected clock so the throttle can be driven deterministically
+ * from a test: this file runs under BOTH vitest and `bun test`, and bun's
+ * `vi` has no `setSystemTime`.
+ */
+export function installUtf8Sanitizer(bot: Bot, now: () => number = Date.now): void {
+  // Throttle state is per-install, not module-global, so one bot's log budget
+  // cannot be consumed by another (and a test needs no reset hook).
+  const lastLoggedAtByMethod = new Map<string, number>()
+  const shouldLogRepair = (method: string, at: number): boolean => {
+    const last = lastLoggedAtByMethod.get(method)
+    if (last !== undefined && at - last < LOG_THROTTLE_MS) return false
+    lastLoggedAtByMethod.set(method, at)
+    return true
+  }
+
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    let clean = payload
+    const stats: SanitizeStats = { repaired: 0 }
+    try {
+      clean = sanitizePayloadStrings(payload, 0, stats)
+    } catch (err) {
+      clean = payload
+      // Fail open, but never SILENTLY: without this line a future walk bug or
+      // a genuinely throwing getter degrades to a bare Telegram 400 with no
+      // trail back to the sanitiser — precisely the opacity #4728 exists to
+      // end. Throttled on its own budget (a distinct key), so a persistent
+      // walk failure cannot be starved by, or starve, the repair line above.
+      // The error MESSAGE is included because without it the line cannot
+      // diagnose anything; the payload body still never is.
+      // The separator is written as the ESCAPE "backslash-u-0000", never as a raw NUL
+      // byte: a literal 0x00 in a source file trips the #3676 binary-file
+      // guard (tests/source-files-are-text.test.ts) and blocks the merge
+      // queue. The runtime key is identical either way.
+      if (shouldLogRepair(`${method}\u0000sanitize-failed`, now())) {
+        process.stderr.write(
+          `telegram gateway: utf8-sanitize FAILED OPEN method=${method} — ` +
+          `payload sent unrepaired; if it carries a lone surrogate Telegram ` +
+          `will reject it (400 "strings must be encoded in UTF-8"): ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+        )
+      }
+    }
+    if (clean !== payload && shouldLogRepair(method, now())) {
+      process.stderr.write(
+        `telegram gateway: utf8-sanitize repaired ${stats.repaired} lone surrogate(s) ` +
+        `method=${method} — body would have been rejected by Telegram ` +
+        `(400 "strings must be encoded in UTF-8")\n`,
+      )
+    }
+    return prev(method, clean, signal)
+  })
+}