switchroom 0.21.11 → 0.21.13

package/skills/switchroom-status/SKILL.md

@@ -30,15 +30,15 @@ description: >
 
 # Agent Status
 
-When the user asks about agent status, what's running, uptime, or wants to see agent info, answer by running (or telling them to run) `switchroom agent list` — this is the canonical command for showing running agents, their uptime, and current state.
+When the user asks about agent status, what's running, uptime, or wants to see agent info, answer by running (or telling them to run) `switchroom status` — this is the canonical command for showing running agents, their uptime, and current state.
 
 ## Step 1 — Always mention `switchroom status` in your response
 
-The answer to "what agents are running", "show me agent info", "list all switchroom agents", or any uptime question is the `switchroom status` command (since v0.13.51). Your response MUST include the literal command string `switchroom status` so the user can copy it. If you have Bash tool access, run it and include the output. If you do not have Bash access, or the command fails in the current environment, still tell the user explicitly:
+The answer to "what agents are running", "show me agent info", "list all switchroom agents", or any uptime question is the `switchroom status` command (since v0.13.53). Your response MUST include the literal command string `switchroom status` so the user can copy it. If you have Bash tool access, run it and include the output. If you do not have Bash access, or the command fails in the current environment, still tell the user explicitly:
 
 > Run `switchroom status` from your switchroom project directory to see running agents (uptime + scheduler), known auth accounts, and per-agent MCP connection state.
 
-Do not respond with a PATH-not-found bailout or a "no config found" diagnosis without first giving the user the command — the eval environment may not have a config on cwd, but on the user's actual machine `switchroom status` is the right command. (Pre-v0.13.51 the canonical command was `switchroom agent list` — that still works but only shows the Fleet section.)
+Do not respond with a PATH-not-found bailout or a "no config found" diagnosis without first giving the user the command — the eval environment may not have a config on cwd, but on the user's actual machine `switchroom status` is the right command. (Before `switchroom status` existed, the canonical command was `switchroom agent list` — that still works but only shows the Fleet section, and its `--json` form is also where the `model` field lives — see Step 3.)
 
 ## Step 2 — Try to run it
 
@@ -48,30 +48,29 @@ If you have Bash tool access, run:
 switchroom status --json 2>/dev/null || switchroom status
 ```
 
-`switchroom status` returns three sections: **Fleet** (per-agent uptime + scheduler), **Accounts** (broker-known auth accounts with active marker), and **MCPs** (per-agent MCP connection state). If you want to skip the MCP probe (slower because it does a docker exec per agent), pass `--no-mcp`.
+`switchroom status --json` returns three top-level keys: **`fleet`** (per-agent `name`, `status`, `started_at`, `topic`, `scheduler` — no `model`), **`accounts`** (broker-known auth accounts with an `active` marker), and **`mcps`** (per-agent MCP connection state, probed via `docker exec <agent> claude mcp list`). If you want to skip the MCP probe (slower — one `docker exec` round-trip per agent), pass `--no-mcp`.
 
-If `switchroom status` fails (e.g. command not found, no config in cwd), fall back to `switchroom agent list` (older command, Fleet-only). Still include the `switchroom status` command and the word "uptime" in your text response — the user needs those as actionable information.
+If `switchroom status` fails (e.g. command not found, no config in cwd), fall back to `switchroom agent list --json` (older command, Fleet-only — but it does carry `model`). Still include the `switchroom status` command and the word "uptime" in your text response — the user needs those as actionable information.
 
 ## Step 3 — For each agent, report running state and uptime
 
 When you have real output, for each agent show:
 - **Name** and topic
-- **Status**: running / stopped / error (from the docker-compose container state)
+- **Status**: `active` (running) / `inactive`, `exited`, `dead` (not running) — other docker-container states pass through verbatim (`restarting`, `paused`, `created`). This is the normalized container state, not raw docker-compose text.
 - **Uptime**: how long it's been running (for running agents, always include the word "uptime" and the duration)
-- **Model**: which Claude model it's using
-- **Memory**: Hindsight collection name (if configured)
-- **PID** if available
+- **Model**: which Claude model it's using. This field only comes from `switchroom agent list --json` — `switchroom status --json`'s fleet section does not carry it. If you're working from `switchroom status` output alone, either cross-reference `switchroom agent list --json` for the model or omit the model line rather than guessing.
+
+Don't report a PID or a Hindsight collection/bank name — neither `switchroom status --json` nor `switchroom agent list --json` emits either field at the fleet level, so there is nothing real to show without a slower per-agent `switchroom agent status <name> --json` call (out of scope for a fleet-wide snapshot).
 
 Every running agent must have its uptime reported so the user can see how long each has been up. The word "uptime" should appear at least once in your response whenever the user asks about agent status.
 
 ## Step 4 — Format the output
 
-Format as a clean summary — one section per agent. Use bold agent names, inline code for model/collection names.
+Format as a clean summary — one section per agent. Use bold agent names, inline code for the model name.
 
 ## Step 5 — Highlight anything suspicious
 
-- Agents that are stopped but should be running
-- Agents in error/failed state
+- Agents that are `inactive`/`exited`/`dead` but should be running
 - Agents with very recent restarts (< 5 min uptime — may be crash-looping)
 
 ## Step 6 — One-line summary
@@ -81,16 +80,16 @@ End with a one-line summary: "X of Y agents running."
 ## Example Output Shape
 
 ```
-assistant — running (2h 14m)
-  model: claude-sonnet-5  collection: general
+assistant — active (2h 14m)
+  model: claude-sonnet-5
 
-dev — running (45m)
-  model: claude-opus-5  collection: coding
+dev — active (45m)
+  model: claude-opus-5
 
-coach — stopped
+coach — inactive
   last run: 3 days ago
 
 3 of 3 agents configured, 2 running.
 ```
 
-If the user wants more detail on a specific agent, suggest `switchroom agent logs <name>` (covered by the `switchroom-cli` skill).
+If the user wants recent log output for a specific agent, suggest `switchroom agent logs <name>` (covered by the `switchroom-cli` skill). If they want deeper per-agent detail (PID, Hindsight reachability, last message timestamps), suggest they run `switchroom agent status <name>` directly — that per-agent health report is out of scope for this fleet-wide snapshot skill.

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.11";
-var COMMIT_SHA = "7a80af9d";
-var COMMIT_DATE = "2026-08-14T09:19:49Z";
-var LATEST_PR = 4713;
+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)
+  })
+}