switchroom 0.18.12 → 0.18.14

package/dist/vault/approvals/kernel-server.js

@@ -4244,7 +4244,6 @@ var init_schema = __esm(() => {
     enabled: exports_external.boolean().default(true).describe("Master switch for the per-agent Telegram gateway sidecar. " + "When false, start.sh skips the gateway supervise loop and the " + "agent boots without bot-token requirements (smoke-test + " + "offline-dev use case)."),
     plugin: exports_external.enum(["switchroom", "official"]).optional().describe("Which Telegram MCP plugin to load. Default is 'switchroom' — the " + "enhanced fork with streaming edits, reactions, history, and " + "access control. Set to 'official' for the upstream marketplace " + "plugin (basic send/receive only)."),
     format: exports_external.enum(["html", "markdownv2", "text"]).optional().describe("Default reply format passed to the plugin"),
-    rate_limit_ms: exports_external.number().optional().describe("Minimum delay between outgoing messages in ms"),
     stream_mode: exports_external.enum(["pty", "checklist"]).optional().describe("How live progress is streamed to Telegram during a turn. " + "'pty' (default) surfaces text snapshots of Claude Code's TUI — " + "compatible but can flicker as Ink re-renders. 'checklist' drives " + "a structured progress card from session-tail events — stable " + "order, per-tool status emojis, fires only on semantic transitions."),
     stream_throttle_ms: exports_external.number().int().nonnegative().optional().describe("Throttle window in ms between successive in-place stream edits " + "during a turn. Lower = more responsive stream, higher = fewer API " + "calls. Floored at 250 by draft-stream itself. Default 400 ms for DMs " + "and 1000 ms for groups/forums (respects Telegram's ~1 edit/sec/message " + "practical ceiling). Override per-agent if a particular agent needs " + "snappier or quieter streaming."),
     clear_status_on_completion: exports_external.boolean().optional().describe("When true, the live activity/status feed (the in-place 'what it's " + "doing' message — Reading X, Searching the web for Y, …) is DELETED " + "when the turn's final answer lands, so only the reply remains. " + "Default false: the status message is left in the chat as a record " + "(its last step marked done) — no post-then-delete. Per-agent " + "override; cascades defaults → profile → agent (per-key)."),
@@ -4778,6 +4777,13 @@ var init_schema = __esm(() => {
   });
 });
 
+// src/util/atomic.ts
+import { closeSync, constants, fsyncSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+var TMP_OPEN_FLAGS;
+var init_atomic = __esm(() => {
+  TMP_OPEN_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0);
+});
+
 // src/config/merge.ts
 function dedupe(items) {
   const seen = new Set;
@@ -18249,6 +18255,13 @@ var ApprovalLookupRequestSchema = exports_external.object({
   action: exports_external.string().min(1),
   current_approver_set: exports_external.array(exports_external.string())
 });
+var ApprovalLookupByRequestRequestSchema = exports_external.object({
+  v: exports_external.literal(1),
+  op: exports_external.literal("approval_lookup_by_request"),
+  agent_unit: exports_external.string().min(1),
+  request_id: exports_external.string().regex(/^[0-9a-f]{32}$/),
+  current_approver_set: exports_external.array(exports_external.string())
+});
 var ApprovalConsumeRequestSchema = exports_external.object({
   v: exports_external.literal(1),
   op: exports_external.literal("approval_consume"),
@@ -18303,6 +18316,7 @@ var RequestSchema = exports_external.discriminatedUnion("op", [
   RevokeGrantRequestSchema,
   ApprovalRequestRequestSchema,
   ApprovalLookupRequestSchema,
+  ApprovalLookupByRequestRequestSchema,
   ApprovalConsumeRequestSchema,
   ApprovalRevokeRequestSchema,
   ApprovalListRequestSchema,
@@ -18664,6 +18678,30 @@ function lookupDecision(db, query, opts = {}, now = Date.now()) {
        ORDER BY granted_at DESC LIMIT 1`).get(query.agent_unit, query.scope, query.action);
   if (!row)
     return { state: "no_decision" };
+  return evaluateDecisionRow(db, row, currentCanonical, opts, now);
+}
+function lookupDecisionByRequestId(db, query, opts = {}, now = Date.now()) {
+  const currentCanonical = canonicalizeApproverSet(query.current_approver_set);
+  const nonceRow = db.query(`SELECT * FROM approval_nonces WHERE request_id = ?`).get(query.request_id);
+  if (!nonceRow)
+    return { state: "no_decision" };
+  const nonce = nonceFromRow(nonceRow);
+  if (nonce.agent_unit !== query.agent_unit)
+    return { state: "no_decision" };
+  if (nonce.decision_id === null) {
+    if (nonce.expires_at < now)
+      return { state: "expired" };
+    return { state: "pending", request_id: nonce.request_id };
+  }
+  const decRow = db.query(`SELECT * FROM approval_decisions WHERE id = ?`).get(nonce.decision_id);
+  if (!decRow)
+    return { state: "expired" };
+  if (decRow.revoked_at != null) {
+    return { state: "denied", decision: rowToDecision(decRow) };
+  }
+  return evaluateDecisionRow(db, decRow, currentCanonical, opts, now);
+}
+function evaluateDecisionRow(db, row, currentCanonical, opts, now) {
   const decision = rowToDecision(row);
   if (decision.decision === "deny_perm") {
     return { state: "denied", decision };
@@ -18860,6 +18898,7 @@ init_schema();
 
 // src/agents/scaffold.ts
 import { join as join4, resolve as resolve5 } from "node:path";
+init_atomic();
 init_schema();
 
 // src/config/users.ts
@@ -19301,6 +19340,33 @@ function handleRequest(socket, req, agent, db, peerUid, isOperator = false) {
     socket.write(encodeResponse({ ok: true, state: r.state, decision }));
     return;
   }
+  if (req.op === "approval_lookup_by_request") {
+    const acl = checkApprovalAclByAgent(agent, req.agent_unit);
+    if (!acl.allow) {
+      socket.write(encodeResponse(errorResponse("DENIED", acl.reason)));
+      return;
+    }
+    const r = lookupDecisionByRequestId(db, {
+      agent_unit: req.agent_unit,
+      request_id: req.request_id,
+      current_approver_set: req.current_approver_set
+    });
+    const decision = r.state === "granted" || r.state === "denied" ? {
+      id: r.decision.id,
+      agent_unit: r.decision.agent_unit,
+      scope: r.decision.scope,
+      action: r.decision.action,
+      decision: r.decision.decision,
+      granted_at: r.decision.granted_at,
+      granted_by_user_id: r.decision.granted_by_user_id,
+      ttl_expires_at: r.decision.ttl_expires_at,
+      last_used_at: r.decision.last_used_at,
+      revoked_at: r.decision.revoked_at,
+      revoke_reason: r.decision.revoke_reason
+    } : null;
+    socket.write(encodeResponse({ ok: true, state: r.state, decision }));
+    return;
+  }
   if (req.op === "approval_consume") {
     const peek = getNonce(db, req.request_id);
     if (peek !== null) {

package/dist/vault/broker/server.js

@@ -4244,7 +4244,6 @@ var init_schema = __esm(() => {
     enabled: exports_external.boolean().default(true).describe("Master switch for the per-agent Telegram gateway sidecar. " + "When false, start.sh skips the gateway supervise loop and the " + "agent boots without bot-token requirements (smoke-test + " + "offline-dev use case)."),
     plugin: exports_external.enum(["switchroom", "official"]).optional().describe("Which Telegram MCP plugin to load. Default is 'switchroom' — the " + "enhanced fork with streaming edits, reactions, history, and " + "access control. Set to 'official' for the upstream marketplace " + "plugin (basic send/receive only)."),
     format: exports_external.enum(["html", "markdownv2", "text"]).optional().describe("Default reply format passed to the plugin"),
-    rate_limit_ms: exports_external.number().optional().describe("Minimum delay between outgoing messages in ms"),
     stream_mode: exports_external.enum(["pty", "checklist"]).optional().describe("How live progress is streamed to Telegram during a turn. " + "'pty' (default) surfaces text snapshots of Claude Code's TUI — " + "compatible but can flicker as Ink re-renders. 'checklist' drives " + "a structured progress card from session-tail events — stable " + "order, per-tool status emojis, fires only on semantic transitions."),
     stream_throttle_ms: exports_external.number().int().nonnegative().optional().describe("Throttle window in ms between successive in-place stream edits " + "during a turn. Lower = more responsive stream, higher = fewer API " + "calls. Floored at 250 by draft-stream itself. Default 400 ms for DMs " + "and 1000 ms for groups/forums (respects Telegram's ~1 edit/sec/message " + "practical ceiling). Override per-agent if a particular agent needs " + "snappier or quieter streaming."),
     clear_status_on_completion: exports_external.boolean().optional().describe("When true, the live activity/status feed (the in-place 'what it's " + "doing' message — Reading X, Searching the web for Y, …) is DELETED " + "when the turn's final answer lands, so only the reply remains. " + "Default false: the status message is left in the chat as a record " + "(its last step marked done) — no post-then-delete. Per-agent " + "override; cascades defaults → profile → agent (per-key)."),
@@ -4778,6 +4777,13 @@ var init_schema = __esm(() => {
   });
 });
 
+// src/util/atomic.ts
+import { closeSync, constants, fsyncSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+var TMP_OPEN_FLAGS;
+var init_atomic = __esm(() => {
+  TMP_OPEN_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0);
+});
+
 // src/config/merge.ts
 function dedupe(items) {
   const seen = new Set;
@@ -18087,7 +18093,7 @@ var require_lib = __commonJS((exports, module) => {
 
 // src/vault/broker/server.ts
 import * as net from "node:net";
-import { mkdirSync as mkdirSync6, chmodSync as chmodSync4, chownSync, existsSync as existsSync11, readFileSync as readFileSync10, readdirSync as readdirSync4, statSync as statSync6, unlinkSync as unlinkSync6, writeFileSync as writeFileSync3, renameSync as renameSync6 } from "node:fs";
+import { mkdirSync as mkdirSync6, chmodSync as chmodSync4, chownSync, existsSync as existsSync11, readFileSync as readFileSync10, readdirSync as readdirSync4, statSync as statSync6, unlinkSync as unlinkSync6, writeFileSync as writeFileSync3, renameSync as renameSync7 } from "node:fs";
 
 // src/agents/compose.ts
 import { createHash } from "node:crypto";
@@ -18095,6 +18101,7 @@ init_schema();
 
 // src/agents/scaffold.ts
 import { join as join4, resolve as resolve6 } from "node:path";
+init_atomic();
 init_schema();
 
 // src/config/users.ts
@@ -18424,14 +18431,14 @@ init_loader();
 import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:crypto";
 import {
   readFileSync as readFileSync5,
-  writeSync as writeSync2,
+  writeSync as writeSync3,
   existsSync as existsSync6,
-  renameSync,
+  renameSync as renameSync2,
   mkdirSync as mkdirSync2,
   unlinkSync as unlinkSync2,
-  fsyncSync as fsyncSync2,
-  openSync as openSync2,
-  closeSync as closeSync2,
+  fsyncSync as fsyncSync3,
+  openSync as openSync3,
+  closeSync as closeSync3,
   lstatSync,
   realpathSync as realpathSync2
 } from "node:fs";
@@ -18440,10 +18447,10 @@ import { dirname, basename as basename2, resolve as resolve5 } from "node:path";
 // src/vault/flock.ts
 import {
   existsSync as existsSync5,
-  openSync,
-  closeSync,
-  writeSync,
-  fsyncSync,
+  openSync as openSync2,
+  closeSync as closeSync2,
+  writeSync as writeSync2,
+  fsyncSync as fsyncSync2,
   unlinkSync,
   readFileSync as readFileSync4,
   readdirSync as readdirSync3,
@@ -18568,7 +18575,7 @@ function acquireLock(vaultPath, options = {}) {
   while (true) {
     let fd = null;
     try {
-      fd = openSync(lockPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 384);
+      fd = openSync2(lockPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 384);
     } catch (err) {
       const code = err?.code ?? "";
       if (code === "EEXIST") {
@@ -18604,11 +18611,11 @@ function acquireLock(vaultPath, options = {}) {
 ${Date.now()}
 ${process.argv[1] ?? ""}
 `;
-      writeSync(fd, meta);
-      fsyncSync(fd);
+      writeSync2(fd, meta);
+      fsyncSync2(fd);
     } catch {
       try {
-        closeSync(fd);
+        closeSync2(fd);
       } catch {}
       try {
         unlinkSync(lockPath);
@@ -18619,7 +18626,7 @@ ${process.argv[1] ?? ""}
     return {
       release: () => {
         try {
-          closeSync(ownedFd);
+          closeSync2(ownedFd);
         } catch {}
         try {
           unlinkSync(lockPath);
@@ -18675,20 +18682,20 @@ function atomicWriteFileSync(path, data, mode) {
   const dir = dirname(resolve5(effectivePath));
   const tmp = resolve5(dir, `.${basename2(effectivePath)}.${process.pid}.${Date.now()}.tmp`);
   try {
-    const fd = openSync2(tmp, "wx", mode);
+    const fd = openSync3(tmp, "wx", mode);
     try {
-      writeSync2(fd, data);
-      fsyncSync2(fd);
+      writeSync3(fd, data);
+      fsyncSync3(fd);
     } finally {
-      closeSync2(fd);
+      closeSync3(fd);
     }
-    renameSync(tmp, effectivePath);
+    renameSync2(tmp, effectivePath);
     try {
-      const dirFd = openSync2(dir, "r");
+      const dirFd = openSync3(dir, "r");
       try {
-        fsyncSync2(dirFd);
+        fsyncSync3(dirFd);
       } finally {
-        closeSync2(dirFd);
+        closeSync3(dirFd);
       }
     } catch {}
   } catch (err) {
@@ -19264,6 +19271,13 @@ var ApprovalLookupRequestSchema = exports_external.object({
   action: exports_external.string().min(1),
   current_approver_set: exports_external.array(exports_external.string())
 });
+var ApprovalLookupByRequestRequestSchema = exports_external.object({
+  v: exports_external.literal(1),
+  op: exports_external.literal("approval_lookup_by_request"),
+  agent_unit: exports_external.string().min(1),
+  request_id: exports_external.string().regex(/^[0-9a-f]{32}$/),
+  current_approver_set: exports_external.array(exports_external.string())
+});
 var ApprovalConsumeRequestSchema = exports_external.object({
   v: exports_external.literal(1),
   op: exports_external.literal("approval_consume"),
@@ -19318,6 +19332,7 @@ var RequestSchema = exports_external.discriminatedUnion("op", [
   RevokeGrantRequestSchema,
   ApprovalRequestRequestSchema,
   ApprovalLookupRequestSchema,
+  ApprovalLookupByRequestRequestSchema,
   ApprovalConsumeRequestSchema,
   ApprovalRevokeRequestSchema,
   ApprovalListRequestSchema,
@@ -19570,13 +19585,13 @@ import {
   copyFileSync as copyFileSync2,
   chmodSync,
   existsSync as existsSync7,
-  fsyncSync as fsyncSync3,
+  fsyncSync as fsyncSync4,
   lstatSync as lstatSync2,
   mkdirSync as mkdirSync3,
-  openSync as openSync3,
-  closeSync as closeSync3,
+  openSync as openSync4,
+  closeSync as closeSync4,
   readFileSync as readFileSync7,
-  renameSync as renameSync2,
+  renameSync as renameSync3,
   statSync as statSync4,
   symlinkSync,
   unlinkSync as unlinkSync3
@@ -19642,7 +19657,7 @@ function runMigration(home2, opts) {
       copyFileSync2(oldPath, tempNew);
       chmodSync(tempNew, 384);
       fsyncFile(tempNew);
-      renameSync2(tempNew, newPath);
+      renameSync3(tempNew, newPath);
       fsyncDir(parent);
       atomicReplaceWithSymlink(oldPath, "vault/vault.enc");
       fsyncDir(switchroomRoot);
@@ -19676,22 +19691,22 @@ function atomicReplaceWithSymlink(target, linkTarget) {
     } catch {}
   }
   symlinkSync(linkTarget, tmp);
-  renameSync2(tmp, target);
+  renameSync3(tmp, target);
 }
 function fsyncFile(path) {
-  const fd = openSync3(path, "r+");
+  const fd = openSync4(path, "r+");
   try {
-    fsyncSync3(fd);
+    fsyncSync4(fd);
   } finally {
-    closeSync3(fd);
+    closeSync4(fd);
   }
 }
 function fsyncDir(path) {
-  const fd = openSync3(path, "r");
+  const fd = openSync4(path, "r");
   try {
-    fsyncSync3(fd);
+    fsyncSync4(fd);
   } finally {
-    closeSync3(fd);
+    closeSync4(fd);
   }
 }
 
@@ -19702,15 +19717,15 @@ init_loader();
 import { createHmac, randomBytes as randomBytes2, createCipheriv as createCipheriv2, createDecipheriv as createDecipheriv2 } from "node:crypto";
 import {
   chmodSync as chmodSync2,
-  closeSync as closeSync4,
+  closeSync as closeSync5,
   existsSync as existsSync8,
-  fsyncSync as fsyncSync4,
+  fsyncSync as fsyncSync5,
   mkdirSync as mkdirSync4,
-  openSync as openSync4,
+  openSync as openSync5,
   readFileSync as readFileSync8,
-  renameSync as renameSync3,
+  renameSync as renameSync4,
   unlinkSync as unlinkSync4,
-  writeSync as writeSync3
+  writeSync as writeSync4
 } from "node:fs";
 var FORMAT_VERSION = 1;
 var SALT_LEN = 16;
@@ -19803,7 +19818,7 @@ import * as path from "node:path";
 
 // src/util/audit-hashchain.ts
 import { createHash as createHash4 } from "node:crypto";
-import { openSync as openSync5, readSync, fstatSync as fstatSync2, closeSync as closeSync5 } from "node:fs";
+import { openSync as openSync6, readSync, fstatSync as fstatSync2, closeSync as closeSync6 } from "node:fs";
 var CHAIN_GENESIS = "GENESIS";
 var SEP = "\x00";
 function rowHash(prev, seq, rowJsonNoChain) {
@@ -19824,7 +19839,7 @@ function chainRow(state, entry) {
 function readTail(path, tailBytes = 64 * 1024) {
   let fd;
   try {
-    fd = openSync5(path, "r");
+    fd = openSync6(path, "r");
   } catch {
     return null;
   }
@@ -19840,7 +19855,7 @@ function readTail(path, tailBytes = 64 * 1024) {
     return null;
   } finally {
     try {
-      closeSync5(fd);
+      closeSync6(fd);
     } catch {}
   }
 }
@@ -22196,6 +22211,9 @@ function lookupDecision(db, query, opts = {}, now = Date.now()) {
        ORDER BY granted_at DESC LIMIT 1`).get(query.agent_unit, query.scope, query.action);
   if (!row)
     return { state: "no_decision" };
+  return evaluateDecisionRow(db, row, currentCanonical, opts, now);
+}
+function evaluateDecisionRow(db, row, currentCanonical, opts, now) {
   const decision = rowToDecision(row);
   if (decision.decision === "deny_perm") {
     return { state: "denied", decision };
@@ -23203,6 +23221,41 @@ class VaultBroker {
       if (req.token !== undefined && req.token !== "") {
         const v = await validateGrantForWrite(this.grantsDb, req.token, req.key);
         if (v.ok) {
+          const writeGrantAgentSlug = v.grant.agent_slug;
+          if (agentName !== null && writeGrantAgentSlug !== agentName) {
+            this.auditLogger.write({
+              ts: new Date().toISOString(),
+              op: "put",
+              key: req.key,
+              caller: auditCaller,
+              pid: auditPid,
+              cgroup: auditCgroup,
+              result: "denied:grant-identity-mismatch",
+              method: "grant",
+              grant_id: v.grant.id
+            });
+            socket.write(encodeResponse(errorResponse("DENIED", "grant-identity-mismatch")));
+            return;
+          }
+          const existingForScope = this.secrets[req.key];
+          if (existingForScope !== undefined) {
+            const writeScope = checkEntryScope(existingForScope.scope, writeGrantAgentSlug);
+            if (!writeScope.allow) {
+              this.auditLogger.write({
+                ts: new Date().toISOString(),
+                op: "put",
+                key: req.key,
+                caller: auditCaller,
+                pid: auditPid,
+                cgroup: auditCgroup,
+                result: `denied:${writeScope.reason}`,
+                method: "grant",
+                grant_id: v.grant.id
+              });
+              socket.write(encodeResponse(errorResponse("DENIED", writeScope.reason)));
+              return;
+            }
+          }
           writeGrantId = v.grant.id;
         } else if (v.reason === "grant-expired" || v.reason === "grant-revoked") {
           this.auditLogger.write({
@@ -23550,7 +23603,7 @@ class VaultBroker {
         const tokenPath = path3.join(tokenDir, ".vault-token");
         const tmpPath = `${tokenPath}.tmp.${process.pid}`;
         writeFileSync3(tmpPath, mintResult.token, { mode: 384 });
-        renameSync6(tmpPath, tokenPath);
+        renameSync7(tmpPath, tokenPath);
         try {
           const uid = allocateAgentUid(agent);
           chownSync(tokenPath, uid, uid);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.18.12",
+  "version": "0.18.14",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/coding/CLAUDE.md.hbs

@@ -51,6 +51,8 @@ Save proactively: architecture decisions, codebase patterns, conventions, known
 
 If sub-agents are configured, delegate implementation to `@worker` (background, own worktree) and research to `@researcher` (background). Keep your turns short — dispatch and acknowledge quickly so you stay available for the user.
 
+If the user amends in-flight delegated work mid-turn, steer the running worker now (`SendMessage` to the worker by name, or by the agent id from its spawn result) instead of holding the update for handback — and say in your reply whether you folded the update into the running worker or queued it as a separate task; never classify silently. If unsure whether a message amends in-flight work, queue it and say so — queue is the default. If the steer lands too late (worker effectively done), say so and apply the update yourself.
+
 {{#if schedule}}
 ## Schedule
 You are running on a schedule: `{{schedule}}`. Use scheduled runs to check CI status, review open PRs, or surface stale issues.

package/profiles/default/CLAUDE.md.hbs

@@ -92,6 +92,8 @@ The main session is for conversation. Execution belongs in sub-agents. Before ma
 
 **Anti-patterns:** starting a task inline then realizing it's complex mid-way; doing 5+ tool calls "because it's almost done"; polling sub-agent status in a loop.
 
+**Steer running workers — don't sit on amendments.** When a mid-turn user message amends work you've already delegated to a running sub-agent, forward the amendment to that worker now — `SendMessage` to the worker by name (or by the agent id from the Agent tool's spawn result, if it has no name) — rather than holding it for handback. If the message is a new independent task, queue it instead; if you're unsure whether it amends the in-flight work, queue it and say so — queue is the default. Either way, state in your reply which you did ("folded your update into the running worker" / "queued as a separate task after the current one") — the steer-or-queue rule is that the classification is always visible in chat, never inferred. If the steer arrives too late (the worker is effectively done), say that and apply the update yourself in the parent.
+
 If no sub-agents are configured, do the work yourself.
 
 ## Session Continuity

package/skills/switchroom-architecture/telegram.md

@@ -81,7 +81,6 @@ agents:
 | Var | Source | Purpose |
 |-----|--------|---------|
 | `SWITCHROOM_TG_FORMAT` | `channels.telegram.format` | Default reply format |
-| `SWITCHROOM_TG_RATE_LIMIT_MS` | `channels.telegram.rate_limit_ms` | Min delay between outgoing messages |
 | `TELEGRAM_STATE_DIR` | Auto-set by scaffold | Path to `telegram/` dir |
 | `SWITCHROOM_AGENT_NAME` | Auto-set by scaffold | Agent name (used for self-restart detection) |
 | `SWITCHROOM_CONFIG` | Auto-set by scaffold | Path to switchroom.yaml |

package/telegram-plugin/auth-snapshot-format.ts

@@ -704,6 +704,22 @@ export interface FallbackAnnouncementInput {
    * shows the target's headroom and is unchanged.
    */
   fleetSnapshots?: AccountSnapshot[];
+  /**
+   * 429 throttle tier enrichment — the reset time PARSED from the error
+   * prose ("resets 8:50am (TZ)" / "retry after 60s") that triggered the
+   * fallback. Fallback for the recovery line when the old account's probe
+   * carried no reset (probe failed / thin headers), so the announcement
+   * still names when the account frees. A probe-derived reset wins when
+   * present — it is the fresher, server-authoritative signal.
+   */
+  parsedResetAt?: Date | null;
+  /**
+   * 429 throttle tier escalation — the trigger was a long-reset transient
+   * RATE LIMIT, not a quota wall. Names the headline honestly ("rate limit
+   * on X" instead of a utilization-derived "5-hour limit on X", which would
+   * be wrong: a rate-limited account's utilization is typically LOW).
+   */
+  cause?: 'rate-limit';
   tz?: string;
   now?: Date;
 }
@@ -728,7 +744,12 @@ export function renderFallbackAnnouncement(input: FallbackAnnouncementInput): st
   const lines: string[] = [];
 
   const limitWord = input.oldQuota ? limitWordFor(input.oldQuota) : 'quota';
-  const headerLimit = limitWord === 'quota' ? 'quota cap' : `${limitWord} limit`;
+  const headerLimit =
+    input.cause === 'rate-limit'
+      ? 'rate limit'
+      : limitWord === 'quota'
+        ? 'quota cap'
+        : `${limitWord} limit`;
 
   if (!input.newLabel) {
     // All-blocked path — no swap occurred. Tell user what's broken and, so they
@@ -765,9 +786,14 @@ export function renderFallbackAnnouncement(input: FallbackAnnouncementInput): st
             `${formatAbsolute(earliest.at, tz)} (in ${formatRelative(earliest.at, now)})`,
         );
       }
-    } else if (input.oldQuota) {
+    } else {
       // Back-compat: no fleet snapshot supplied → old single-account shape.
-      const recovery = recoveryAtFor(input.oldQuota);
+      // Probe-derived reset first; the prose-parsed reset (429 throttle tier
+      // enrichment) covers the probe-failed case.
+      const recovery =
+        (input.oldQuota ? recoveryAtFor(input.oldQuota) : null) ??
+        input.parsedResetAt ??
+        null;
       if (recovery) {
         lines.push(
           `${escapeMarkdown(input.oldLabel)} recovers ${formatAbsolute(recovery, tz)} ` +
@@ -794,8 +820,14 @@ export function renderFallbackAnnouncement(input: FallbackAnnouncementInput): st
   lines.push(`Triggered by: agent **${escapeMarkdown(input.triggerAgent)}**`);
   lines.push('');
 
-  if (input.oldQuota) {
-    const recovery = recoveryAtFor(input.oldQuota);
+  {
+    // Probe-derived reset first; the prose-parsed reset (429 throttle tier
+    // enrichment) keeps the recovery line honest when the old account's
+    // probe failed at the moment of the wall.
+    const recovery =
+      (input.oldQuota ? recoveryAtFor(input.oldQuota) : null) ??
+      input.parsedResetAt ??
+      null;
     if (recovery) {
       lines.push(
         `\`${codeSpanSafe(input.oldLabel)}\` recovers ` +

package/telegram-plugin/auto-fallback-fleet.ts

@@ -183,6 +183,26 @@ export interface FleetFallbackDeps {
   /** Operator timezone for absolute reset times in the announcement. */
   tz?: string;
   now?: Date;
+  /**
+   * The reset time PARSED from the triggering error prose (429 throttle tier
+   * enrichment) — threaded into the announcement as the recovery-line
+   * fallback when the old account's live probe carried no reset.
+   */
+  parsedResetAt?: Date;
+  /**
+   * 429 throttle tier escalation: the trigger is a TERMINAL transient 429
+   * whose parsed reset lies beyond the retry-in-place threshold. Its wording
+   * explicitly NEGATES the usage-limit reading, so the old account's
+   * UTILIZATION probe typically classifies healthy — the healthy-idempotency
+   * guard would self-cancel the swap ("probed healthy / Stale event?"),
+   * silently dropping the spec's ">threshold → mark + fail over" leg. When
+   * set, the terminal parsed-reset signal is trusted over the utilization
+   * probe: the guard is bypassed and the swap proceeds (the broker mark
+   * honors the caller-passed `until` — the parsed reset). Staleness safety
+   * holds upstream: the flag is only set for a terminal error line the
+   * session-tail just read, never for replayed/late events.
+   */
+  rateLimitTrigger?: boolean;
 }
 
 /**
@@ -217,8 +237,12 @@ export async function runFleetAutoFallback(
   // normalization uses the same clock as the rest of the decision (a default
   // `new Date()` would diverge from `deps.now` and could mis-zero a window
   // whose reset is still future relative to the event's clock).
+  // 429 throttle tier: a rate-limit trigger's wording NEGATES the usage-limit
+  // reading, so healthy utilization is the EXPECTED state, not evidence of a
+  // stale event — the guard must not self-cancel that swap (see
+  // FleetFallbackDeps.rateLimitTrigger).
   const oldHealth = classifyHealth(oldSnap, now);
-  if (oldHealth === 'healthy') {
+  if (oldHealth === 'healthy' && !deps.rateLimitTrigger) {
     return {
       kind: 'no-eligible-target',
       oldLabel: oldSnap.label,
@@ -255,6 +279,8 @@ export async function runFleetAutoFallback(
         // card enumerates EVERY account (5h%/7d% + recovery ETA), letting the
         // user verify the fleet is truly exhausted, not just the trigger account.
         fleetSnapshots: snapshots,
+        parsedResetAt: deps.parsedResetAt ?? null,
+        cause: deps.rateLimitTrigger ? 'rate-limit' : undefined,
         tz,
         now,
       }),
@@ -278,6 +304,8 @@ export async function runFleetAutoFallback(
       newLabel: rolledTo,
       newQuota,
       triggerAgent: deps.triggerAgent,
+      parsedResetAt: deps.parsedResetAt ?? null,
+      cause: deps.rateLimitTrigger ? 'rate-limit' : undefined,
       tz,
       now,
     }),

package/telegram-plugin/bridge/bridge.ts

@@ -80,6 +80,8 @@ const mcp = new Server(
       '',
       'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings — image_path_2, image_path_3, … (Read each) and attachment_file_id_2, attachment_file_id_3, … (download_attachment each). Process every one, not just the first. Reply with the reply tool — pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       '',
+      'If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram\'s native Reply on a prior message — treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender\'s name/title as stamped by Telegram\'s servers (not typed by the sender — the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, and forwarded_date is when the original was sent. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id — do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, …); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER\'s own commentary rather than forwarded content — the forwarded_* attributes describe the burst as a whole, not each line of the body.',
+      '',
       'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text — delete is for retraction). Edits don\'t trigger push notifications — when a long task completes, send a new reply so the user\'s device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.',
       '',
       'If a message includes message_thread_id, it came from a forum topic. The reply tool automatically routes a reply back to the topic the question came from — the framework owns the answer\'s topic, so do NOT pass message_thread_id on a reply; a reply always lands where it was asked. Each <channel> message is the current topic — answer ONLY this message\'s question; do not also answer a pending message from another topic. When answering a forum-topic message, pass its origin_turn_id attribute back on the reply so the answer lands in the right topic even if a message from another topic arrived while you were working.',