switchroom 0.18.11 → 0.18.13

package/telegram-plugin/gateway/pending-session-command.ts

@@ -162,14 +162,26 @@ export interface DrainIo {
  * both a model AND an effort command; breaking after re-enqueueing only the
  * current one would silently drop the other with its ack card stuck at
  * "queued" forever.
+ *
+ * Restart-pending is SNAPSHOTTED once at drain entry (#3021): the caller's
+ * `restartPending()` reads a `pendingRestarts` map that the turn-end idle gate
+ * empties in a synchronous loop dispatched right alongside this (async) drain.
+ * For the FIRST command the per-iteration read still sees the entry, but by the
+ * time an `await` yields to the second command the sync loop has emptied the
+ * map — so a naive per-command re-check would let the second command apply live
+ * into a session that is ~100ms from triggerSelfRestart and falsely confirm.
+ * Latching the entry state fixes that. We still OR in the live re-check so a
+ * restart that BECOMES pending mid-drain (a model apply can itself enqueue one)
+ * is honored for the commands that follow it.
  */
 export async function drainTakenCommands(
   taken: readonly PendingSessionCommand[],
   io: DrainIo,
 ): Promise<void> {
+  const restartPendingAtEntry = io.restartPending()
   for (let i = 0; i < taken.length; i++) {
     const cmd = taken[i]
-    if (io.restartPending()) {
+    if (restartPendingAtEntry || io.restartPending()) {
       // The live session is going away — carry the choice across the bounce
       // via the durable carriers (or the re-issue fallback).
       await io.editCard(cmd, io.resolveForRestartText(cmd))

package/telegram-plugin/gateway/permission-ttl-sweep.ts

@@ -0,0 +1,66 @@
+/**
+ * The permission TTL sweep — the code path that used to auto-deny approvals the
+ * operator never saw.
+ *
+ * WHY THIS IS A MODULE AND NOT A LOOP INSIDE gateway.ts:
+ *
+ * gateway.ts has top-level side effects and is not importable from a test. The
+ * first version of the outcome test worked around that by letting its harness
+ * carry a PRIVATE re-implementation of this sweep. The result was a placebo:
+ * deleting the real guard from gateway.ts left every behavioural assertion GREEN,
+ * because the double silently compensated — only a source-text grep noticed.
+ *
+ * A test that cannot fail is not a test, and this is the sweep that implements the
+ * `no-self-escalation` / `on-leash` invariant. So the DECISION lives here, in one
+ * importable place, and both gateway.ts and the outcome test drive this exact
+ * function. Delete the leash check inside `shouldExpirePermission` and the outcome
+ * test goes red — because there is only one implementation to delete.
+ *
+ * @see reference/jobs/approve-what-my-agent-can-touch.md
+ * @see reference/invariants.md § no-self-escalation, § on-leash
+ */
+
+import { shouldExpirePermission, type UndeliverableMark } from './approval-hold.js'
+
+/** The fields of a pending permission this sweep actually reads. */
+export interface TtlSweepEntry {
+  tool_name: string
+  startedAt: number
+  undeliverable?: UndeliverableMark | null
+}
+
+export interface TtlSweepDeps<T extends TtlSweepEntry> {
+  /** The live pending-permission map. */
+  entries: Iterable<readonly [string, T]>
+  now: number
+  /** Per-tool TTL (hostd fleet-mutation verbs get a longer human-scale window). */
+  ttlForTool: (toolName: string) => number
+  /**
+   * Expire this request: dispatch the deny verdict, strip the card's keyboard,
+   * wake the parked turn, record the miss, and drop the entry. Everything the
+   * gateway does on a timeout — the sweep decides WHETHER, the caller decides HOW.
+   */
+  onExpire: (requestId: string, pend: T, ttlMs: number) => void
+}
+
+/**
+ * Expire every pending permission past its TTL — except the HELD ones, which
+ * never expire.
+ *
+ * Returns the ids it expired (for logging/tests).
+ */
+export function sweepPermissionTtl<T extends TtlSweepEntry>(
+  deps: TtlSweepDeps<T>,
+): string[] {
+  const expired: string[] = []
+  for (const [requestId, pend] of deps.entries) {
+    const ttlMs = deps.ttlForTool(pend.tool_name)
+    // THE LEASH. `shouldExpirePermission` returns false for any entry marked
+    // undeliverable — an ask the operator was never shown. Never auto-approve,
+    // never auto-deny, not even on a deadline.
+    if (!shouldExpirePermission(pend, deps.now, ttlMs)) continue
+    deps.onExpire(requestId, pend, ttlMs)
+    expired.push(requestId)
+  }
+  return expired
+}

package/telegram-plugin/gateway/pre-approval-check.ts

@@ -0,0 +1,74 @@
+// #2975 Stage 2 — read-only pre-approval predicate.
+//
+// hostd asks (over the approval-gateway socket, via `check_pre_approved`)
+// whether an EXACT `(agent, diff)` pair is already operator-consented, so it
+// can skip the `config_propose_edit` per-hour rate limit for that persist. This
+// is the READ-ONLY sibling of the `tryAutoResolve` auto-resolve hook wired into
+// `onRequestConfigApproval`: it runs the SAME forge-resistance gate — an EXACT
+// byte-match of the incoming diff against a diff the gateway itself
+// pre-registered when the operator tapped Approve — but it MUST NOT delete the
+// correlation. The single-use delete stays on the real
+// `request_config_approval` auto-resolve, so a peek can never consume the
+// consent (and a rate-limit bypass can never spend a correlation that the
+// actual persist then needs).
+//
+// Extracted as a pure function (stores + helpers injected) so the exact
+// contract — true only for a registered byte-exact pair, and NEVER a mutation —
+// is unit-testable without importing the whole gateway module.
+
+/** Minimal read surface this predicate needs from a correlation store. It only
+ *  ever calls `sweep` (evict-expired, which is not a semantic mutation of a
+ *  live entry) and `get` (read). It deliberately has NO `delete`/`set` so a
+ *  mis-edit that mutates the store won't typecheck here. */
+export interface ReadonlyCorrelationStore {
+  sweep(now: number): void;
+  get(key: string): { unifiedDiff: string } | undefined;
+}
+
+export interface PreApprovalCheckDeps {
+  /** "🔁 Always allow" correlations, keyed `${agentName}::${rule}`. */
+  alwaysAllow: ReadonlyCorrelationStore;
+  /** Mental-model-proposal correlations, keyed by mentalModelCorrelationKey. */
+  mentalModel: ReadonlyCorrelationStore;
+  /** Locate a CANDIDATE always-allow entry by the rule token the diff adds.
+   *  Shape-based, NOT the security gate — the gate is the byte-match below. */
+  extractAddedAllowRule: (unifiedDiff: string) => string | null;
+  /** Compose the mental-model correlation key for `(agent, diff)`. */
+  mentalModelCorrelationKey: (agentName: string, unifiedDiff: string) => string;
+  /** Clock seam (defaults to Date.now()). */
+  now?: () => number;
+}
+
+/**
+ * Returns true iff `(agentName, unifiedDiff)` byte-matches a still-live
+ * pre-registered correlation (always-allow OR mental-model). Read-only: it
+ * never deletes a correlation. A forged diff — the consented token under a
+ * different field, or ANY byte difference — finds no byte-exact entry and
+ * returns false, so hostd falls back to the ordinary rate-limited path.
+ */
+export function isDiffPreApproved(
+  agentName: string,
+  unifiedDiff: string,
+  deps: PreApprovalCheckDeps,
+): boolean {
+  const now = (deps.now ?? Date.now)();
+
+  // "🔁 Always allow": locate a candidate by the added rule token, then require
+  // an EXACT byte-match of the diff (the token match alone is NOT the gate).
+  deps.alwaysAllow.sweep(now);
+  const added = deps.extractAddedAllowRule(unifiedDiff);
+  if (added) {
+    const entry = deps.alwaysAllow.get(`${agentName}::${added}`);
+    if (entry && entry.unifiedDiff === unifiedDiff) return true;
+  }
+
+  // Mental-model proposal the operator approved on the proposal card: byte-exact
+  // match against the pre-registered diff (the security gate).
+  deps.mentalModel.sweep(now);
+  const mmEntry = deps.mentalModel.get(
+    deps.mentalModelCorrelationKey(agentName, unifiedDiff),
+  );
+  if (mmEntry && mmEntry.unifiedDiff === unifiedDiff) return true;
+
+  return false;
+}

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

@@ -0,0 +1,217 @@
+/**
+ * queued-card-store.ts — durable handle for the component-5 queued-status
+ * placeholder and the #2995 mid-flight busy-ack card, so a gateway restart
+ * mid-turn can reap the orphaned card instead of leaving a permanent stale
+ * "⏳ Queued…" line in the chat.
+ *
+ * Why this exists (#3002): both cards track their sent Telegram message id ONLY
+ * in the in-memory `queuedStatusMsgIds` Map in gateway.ts. A gateway/container
+ * restart between posting a card and its in-process promote/reap empties that
+ * Map, so the card is stranded: a permanent "⏳ Queued — replying in another
+ * topic first…" (or busy-ack) line that never gets promoted or deleted, sitting
+ * above the real answer.
+ *
+ * The fix mirrors `activity-card-store.ts` / `status-pin-store.ts` in shape: a
+ * tiny durable snapshot on the per-agent state volume (STATE_DIR), written
+ * whenever a card is POSTED, cleared the moment it is reaped/deleted in-process.
+ * On boot, AFTER this gateway wins the startup mutex (same ordering constraint
+ * as the status-pin/activity-card cleanups — this is a shared per-agent file, so
+ * a losing double-boot must never touch it), a one-shot reaper DELETES any
+ * leftover card via the Bot API and clears the store.
+ *
+ * DELETION is the honest terminal (deliberate — reap-on-boot only, NO
+ * promote-across-restart): a "Queued" / "On it — replying now" claim is ALWAYS
+ * wrong after a restart (the turn it referred to is over or being re-run from
+ * scratch), so the only correct move is to remove the card. We do NOT attempt to
+ * re-promote or re-adopt it across the restart; the resumed/replayed turn owns
+ * fresh surfaces.
+ *
+ * Crash-safety: write-tmp + atomic rename (identical convention to
+ * activity-card-store.ts / status-pin-store.ts). A corrupt or unreadable file
+ * fails open to `[]` — never crashes boot, worst case an orphan isn't reaped
+ * this boot, no worse than pre-fix behaviour.
+ *
+ * IDEMPOTENCY: the reaper deletes each record from the on-disk store BEFORE
+ * attempting its Telegram delete (delete-first, mirroring the activity-card
+ * reaper), so a crash mid-reap or a second boot re-reading the file can never
+ * re-issue a delete for a message already handled. A Telegram delete of an
+ * already-gone message is itself harmless (the caller tolerates "message not
+ * found"); delete-first simply keeps the store honest.
+ */
+
+export interface QueuedCardStoreFsSeam {
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename) so a crash mid-write can't tear
+   *  the snapshot. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+}
+
+/** One persisted queued/busy-ack card: enough to delete the orphaned Telegram
+ *  message on a future boot, without any live turn state. */
+export interface QueuedCardRecord {
+  /** Stable per-topic key (`statusKey(chatId, threadId)` shape) — also the
+   *  upsert key: a fresh post for the same topic replaces any stale row. */
+  key: string
+  chatId: string
+  /** Forum topic id, or null for a DM / General-topic card. */
+  threadId: number | null
+  messageId: number
+}
+
+interface SnapshotEnvelope {
+  v: 1
+  cards: QueuedCardRecord[]
+}
+
+function isCardRow(x: unknown): x is QueuedCardRecord {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.key === 'string' &&
+    o.key.length > 0 &&
+    typeof o.chatId === 'string' &&
+    o.chatId.length > 0 &&
+    (o.threadId === null || typeof o.threadId === 'number') &&
+    typeof o.messageId === 'number'
+  )
+}
+
+/**
+ * Load the persisted card set. Returns [] on a missing, unreadable, or
+ * malformed file — fail-open, never throws.
+ */
+export function loadQueuedCards(
+  path: string,
+  fs: QueuedCardStoreFsSeam,
+): QueuedCardRecord[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if (env.v !== 1 || !Array.isArray(env.cards)) return []
+  return env.cards.filter(isCardRow)
+}
+
+/**
+ * Persist the card set atomically (write sibling tmp → rename). Never throws —
+ * a write failure is logged and the store degrades to in-memory-only for this
+ * process (same contract as `activity-card-store.ts`).
+ */
+export function persistQueuedCards(
+  path: string,
+  fs: QueuedCardStoreFsSeam,
+  snapshot: readonly QueuedCardRecord[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SnapshotEnvelope = { v: 1, cards: [...snapshot] }
+  const tmp = path + '.tmp'
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(env))
+    fs.renameSync(tmp, path)
+  } catch (err) {
+    log(
+      `queued-card-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded to in-memory\n`,
+    )
+  }
+}
+
+/**
+ * Upsert the card row for `key` (replacing any stale row for the same topic).
+ * Called the moment a queued-status / busy-ack card is POSTED (its message id
+ * is recorded into the in-memory `queuedStatusMsgIds` Map).
+ */
+export function writeQueuedCardRecord(
+  path: string,
+  fs: QueuedCardStoreFsSeam,
+  record: QueuedCardRecord,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const current = loadQueuedCards(path, fs)
+  const others = current.filter((c) => c.key !== record.key)
+  persistQueuedCards(path, fs, [...others, record], log)
+}
+
+/**
+ * Remove the card row for `key`, if present. Called the moment the card is
+ * reaped/deleted in-process (reapQueuedStatus), and by the boot reaper (BEFORE
+ * attempting the Telegram delete — the idempotency guard).
+ *
+ * When `messageId` is supplied, only a row matching BOTH `key` AND `messageId`
+ * is removed (reap-race guard): during a slow multi-record reap a fresh live
+ * turn could post a NEW card under the same key (its own, different messageId);
+ * a key-only clear would then drop the live card's durable protection. Omit
+ * `messageId` only when you mean "clear whatever row exists for this topic".
+ */
+export function clearQueuedCardRecord(
+  path: string,
+  fs: QueuedCardStoreFsSeam,
+  key: string,
+  messageId?: number,
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const current = loadQueuedCards(path, fs)
+  if (current.length === 0) return
+  const next = current.filter(
+    (c) => c.key !== key || (messageId !== undefined && c.messageId !== messageId),
+  )
+  if (next.length === current.length) return
+  persistQueuedCards(path, fs, next, log)
+}
+
+/**
+ * Boot-time orphan reaper, extracted as a pure routine over injected seams
+ * (mirrors `runActivityCardBootReaper`). The gateway's thin wrapper binds the
+ * live fs, a Telegram delete call, and the logger.
+ *
+ * CRITICAL ordering, identical constraint to the status-pin / activity-card
+ * cleanups: the caller MUST only invoke this AFTER winning the startup mutex.
+ * The store is a shared per-agent file; a losing double-boot running this would
+ * delete a card the still-alive holder's in-flight turn still legitimately owns.
+ *
+ * Deletes each record from disk BEFORE attempting its Telegram delete (not
+ * after), so a crash mid-reap, or a second boot re-reading the file, can never
+ * re-issue a delete. A `deleteCard` failure (message already gone, chat
+ * unreachable, permissions changed) is swallowed — non-fatal, logged, and never
+ * re-attempted since the record is already gone. Returns counts for
+ * logging/testing.
+ */
+export async function runQueuedCardBootReaper(args: {
+  path: string
+  fs: QueuedCardStoreFsSeam
+  deleteCard: (record: QueuedCardRecord) => Promise<unknown>
+  log?: (line: string) => void
+}): Promise<{ deleted: number; total: number }> {
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const persisted = loadQueuedCards(args.path, args.fs)
+  if (persisted.length === 0) return { deleted: 0, total: 0 }
+  let deleted = 0
+  for (const record of persisted) {
+    // Delete BEFORE attempting the Telegram delete — the idempotency guard.
+    clearQueuedCardRecord(args.path, args.fs, record.key, record.messageId, log)
+    try {
+      await args.deleteCard(record)
+      deleted++
+    } catch (err) {
+      log(
+        `queued-card-store: boot reaper delete failed ` +
+          `(chat=${record.chatId} msg=${record.messageId}): ` +
+          `${(err as Error).message}\n`,
+      )
+    }
+  }
+  return { deleted, total: persisted.length }
+}

package/telegram-plugin/gateway/session-model-file.ts

@@ -40,6 +40,8 @@ import { isValidModelArg } from './model-command.js'
 export const SESSION_MODEL_FILE = '.session-model'
 export const RELAUNCH_MODEL_INTENT_FILE = '.relaunch-model-intent'
 export const CONFIGURED_DEFAULT_MODEL_FILE = '.configured-default-model'
+/** Crashloop self-heal counter (start.sh stamps `<count> <epoch>` per fast boot). */
+export const SESSION_MODEL_BOOT_ATTEMPTS_FILE = '.session-model-boot-attempts'
 
 export type RelaunchModelIntent = 'keep' | 'revert'
 
@@ -142,7 +144,30 @@ export function clearSessionModelFile(agentDir: string): void {
     // #3042 item 4: also drop the kept-alert dedup sentinel so a future
     // override of the same name re-alerts on its first kept boot.
     rmSync(join(agentDir, '.session-model-kept-notified'), { force: true })
-    rmSync(join(agentDir, '.session-model-boot-attempts'), { force: true })
+    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * #3043 item 2: clear ONLY the crashloop boot-attempts counter — a positive
+ * health signal from the gateway, not a carrier change.
+ *
+ * start.sh's self-heal (start.sh.hbs "Override crashloop self-heal") increments
+ * the counter on every boot that re-enters within 150s with the override still
+ * active, and clears a healthy override after 3 fast boots. That window can't
+ * tell a genuine crashloop from three quick OPERATOR hand-bounces of a healthy
+ * agent — both look like fast successive boots — so three deliberate restarts
+ * would spuriously wipe a working override. A boot that reaches bridge
+ * registration is proven healthy (the session came all the way up and the
+ * bridge connected), so the gateway deletes the counter there. Only boots that
+ * genuinely FAIL before the bridge registers now accumulate toward the 3-strike
+ * clear. Best-effort; absent file is fine.
+ */
+export function clearSessionModelBootAttempts(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
   } catch {
     /* best-effort */
   }

package/telegram-plugin/gateway/turn-end-gate-backstop.ts

@@ -0,0 +1,59 @@
+/**
+ * turn-end gate-wedge backstop (#2094 finding 1).
+ *
+ * The `turn_end` session-event handler in `gateway.ts` runs a long
+ * synchronous prelude (narrative dedup, answer-stream finalize,
+ * `redactOutboundText`, `progressDriver?.takeOverCard`, …) before it reaches
+ * the branch that calls `endCurrentTurnAtomic` → `purgeReactionTracking` —
+ * the canonical op that deletes this turn's `activeTurnStartedAt` entry and
+ * re-opens the #1556 inbound buffer gate.
+ *
+ * If ANY of those pre-purge ops throws, the handler exits before the canonical
+ * purge runs, leaving `activeTurnStartedAt` (and the mirrored `claudeBusyKeys`
+ * that `purgeReactionTracking` drains) populated. The #1556 inbound gate then
+ * wedges CLOSED: every subsequent inbound buffers, and only the 300 s
+ * silence-poke fallback eventually recovers it (degraded, not permanent).
+ *
+ * `withTurnEndGateBackstop` wraps the handler body in a guarded `try/finally`.
+ * The `finally` acts ONLY when a throw skipped the canonical purge — detected
+ * by the turn's key still being present in `activeTurnStartedAt`. On the happy
+ * path the canonical purge already deleted the key, so the backstop is a
+ * no-op. The original error is NOT swallowed: `finally` re-raises it after the
+ * backstop purge, so upstream error handling / unhandled-rejection policy is
+ * unchanged.
+ */
+export interface TurnEndGateBackstopDeps<T> {
+  /** True while `key`'s `activeTurnStartedAt` entry is still populated. */
+  hasActiveTurn: (key: string) => boolean
+  /** The canonical purge (production wires this to `purgeReactionTracking`). */
+  purge: (key: string, endingTurn: T | undefined) => void
+  /** Optional structured log emitted only when the backstop actually fires. */
+  log?: (msg: string) => void
+}
+
+/**
+ * Run `body` (the synchronous turn_end handler body) under a guarded finally.
+ *
+ * @param key         the turn's status key, or null when there was no live
+ *                    turn to end (then the backstop can never fire).
+ * @param endingTurn  the captured turn atom, forwarded to `purge` so the
+ *                    shadow trace sees the authoritative `replyCalled` flag.
+ */
+export function withTurnEndGateBackstop<T>(
+  key: string | null,
+  endingTurn: T | null,
+  body: () => void,
+  deps: TurnEndGateBackstopDeps<T>,
+): void {
+  try {
+    body()
+  } finally {
+    if (key != null && deps.hasActiveTurn(key)) {
+      deps.log?.(
+        `telegram gateway: turn_end backstop-purge — a pre-purge throw left ` +
+          `the #1556 inbound gate wedged (key=${key}); forcing purge (#2094)`,
+      )
+      deps.purge(key, endingTurn ?? undefined)
+    }
+  }
+}

package/telegram-plugin/gateway/turn-end-gate.ts

@@ -0,0 +1,95 @@
+// #1667 — pure decision core for the `turn_end` handler's answer-delivery
+// gate (originally landed inline in `gateway.ts` by #1664).
+//
+// The gateway's `case 'turn_end':` block resolves, in strict order, which of
+// four terminal dispositions a just-ended turn takes:
+//
+//   1. silent-marker suppression  — the model's only output was a silent-turn
+//      sentinel (NO_REPLY / HEARTBEAT_OK, or composite/ trailing silent
+//      noise). `decideTurnFlush` returns `{kind:'skip', reason:'silent-marker'}`.
+//      The gateway suppresses the card without a "Done" edit and returns.
+//   2. turn-flush                 — the model skipped reply/stream_reply but
+//      left substantive terminal prose; `decideTurnFlush` returns
+//      `{kind:'flush', text}`. The gateway delivers that prose as the answer
+//      (setting `finalAnswerDelivered = true`) and returns.
+//   3. re-prompt (#1664 gate)     — the reply-called tail. The turn neither
+//      suppressed nor flushed, and `finalAnswerDelivered === false`: the model
+//      sent only an interim ack (or nothing) and never delivered a real
+//      answer. The silent-end machinery re-prompts so the answer lands.
+//   4. none                       — the reply-called tail with
+//      `finalAnswerDelivered === true`: a genuine final answer was delivered;
+//      no re-prompt.
+//
+// This module hoists that ordering into a single pure function so it is
+// testable against the code the gateway actually runs (the gateway's
+// `turn_end` case delegates to `decideTurnEndGate`). It is a strictly
+// behaviour-preserving extraction — the exact conditionals and their order,
+// no logic change.
+//
+// What deliberately remains inline in the gateway (side effects, not
+// decisions): the synthetic-backstop `durationMs === -1` suppression, the
+// `turn == null` guard, the answer-stream materialize/retract block (which may
+// set `finalAnswerDelivered = true` BEFORE this gate is consulted), and every
+// disposition's actual teardown / send / telemetry. Those are not part of the
+// decision — they are what each decision drives. The gate is computed once,
+// immediately after `flushDecision`, reading `finalAnswerDelivered` at its
+// tail value (the answer-stream branch has already run by then; the flush
+// branch, which also sets it, is not yet entered and does not influence the
+// gate's own outcome).
+
+import type { FlushDecision } from '../turn-flush-safety.js'
+
+/**
+ * The terminal disposition of a `turn_end`, in the gateway's evaluation order.
+ * - `silent_end`  → silent-marker suppression path (no reply, no card edit).
+ * - `flush`       → turn-flush delivers the model's terminal prose as the answer.
+ * - `reprompt`    → #1664 gate: no final answer delivered → silent-end re-prompt.
+ * - `none`        → final answer delivered; normal terminal, no re-prompt.
+ */
+export type TurnEndDecision = 'silent_end' | 'flush' | 'reprompt' | 'none'
+
+export interface TurnEndGateSnapshot {
+  /** The result of `decideTurnFlush(...)` for this turn (or the synthetic
+   * `{kind:'skip', reason:'reply-called'}` the gateway substitutes when the
+   * answer-stream already materialised the answer). */
+  flushDecision: FlushDecision
+  /**
+   * `turn.finalAnswerDelivered` at the point the gate is consulted — i.e. after
+   * the answer-stream materialize branch may have set it true, but reflecting
+   * whether a genuine final answer (not a bare interim ack) has been delivered.
+   * Only consulted on the reply-called tail (neither silent-marker nor flush).
+   */
+  finalAnswerDelivered: boolean
+}
+
+/**
+ * Pure decision core for the `turn_end` answer-delivery gate. Mirrors the
+ * gateway's branch ordering exactly: silent-marker early-return, then
+ * turn-flush early-return, then the `finalAnswerDelivered === false` re-prompt
+ * gate, else no re-prompt. No side effects.
+ */
+export function decideTurnEndGate(snapshot: TurnEndGateSnapshot): TurnEndDecision {
+  const { flushDecision, finalAnswerDelivered } = snapshot
+
+  // 1. Silent-marker suppression takes precedence: the model's only output was
+  //    a silent-turn sentinel. Suppress without a card edit; never re-prompt.
+  if (flushDecision.kind === 'skip' && flushDecision.reason === 'silent-marker') {
+    return 'silent_end'
+  }
+
+  // 2. Turn-flush: the model left substantive terminal prose without calling
+  //    the reply tool. Deliver it as the answer; the turn IS answered.
+  if (flushDecision.kind === 'flush') {
+    return 'flush'
+  }
+
+  // 3. Reply-called tail. #1664: the trigger is "no final answer delivered",
+  //    not "zero outbound". An interim-ack-only turn (reply called, but
+  //    finalAnswerDelivered still false) re-prompts; a delivered final answer
+  //    does not. A zero-outbound turn also lands here with
+  //    finalAnswerDelivered === false and re-prompts.
+  if (finalAnswerDelivered === false) {
+    return 'reprompt'
+  }
+  return 'none'
+}

package/telegram-plugin/gateway/turn-typing-loop.ts

@@ -16,8 +16,16 @@
  * a mid-turn reply's `finally { stopTypingLoop }` would kill it and the chat
  * would go dark for the rest of the turn. A dedicated map makes the turn loop
  * structurally immune to those stops — only `stop` (the canonical turn-end)
- * clears it. The redundant `typing` pings while a reply is mid-flight are
- * harmless (same action, and `sendChatAction` is cheap).
+ * clears it.
+ *
+ * The map is separate; the SENDS are not (#3084). This file used to claim the
+ * redundant pings were "harmless — same action, and `sendChatAction` is cheap".
+ * They are not cheap: they spend the per-bot flood budget the REPLIES need, and
+ * on 2026-07-11 the two loops together earned a 4.6-hour flood ban. The gateway
+ * now injects a `sendChatAction` that routes through the SHARED typing emitter
+ * (`typing-emitter.ts`), which enforces one action per chat key per refresh
+ * window across BOTH loops. This factory keeps its lifecycle semantics —
+ * fire-on-start, refresh, stop-at-turn-end — and the floor lives in the emitter.
  *
  * Extracted into a factory so the lifecycle (fires on start, refreshes on the
  * interval, stops on turn-end, NEVER leaks a refresh interval after the turn

package/telegram-plugin/gateway/unhandled-rejection-policy.ts

@@ -12,6 +12,8 @@
 
 import { GrammyError, HttpError } from 'grammy'
 
+import { FLOOD_WAIT_ACTIVE } from '../retry-api-call.js'
+
 export type RejectionAction = 'shutdown' | 'log_only'
 
 export interface RejectionPolicyOptions {
@@ -65,6 +67,17 @@ export function classifyRejection(
       : err instanceof HttpError
   if (isHttp) return 'log_only'
 
+  // FLOOD_WAIT_ACTIVE (#3084): retry-api-call throws this plain Error marker
+  // instead of sleeping through a multi-hour per-bot flood ban (overlord saw
+  // retry_after = 16739s ≈ 4.6h). It is the SAME condition as the GrammyError
+  // 429 handled below — just surfaced as a non-retryable marker rather than a
+  // raw grammy error — so it takes the same posture. A leaked one (a
+  // fire-and-forget send that wasn't wrapped in swallowingApiCall) must NOT
+  // crash the gateway: the bot is already rate-limited, and a crash→restart
+  // fires MORE sends into the open window and extends the ban, which is the
+  // exact amplification the #2923 circuit breaker exists to stop.
+  if (err instanceof Error && err.message === FLOOD_WAIT_ACTIVE) return 'log_only'
+
   if (!isGrammy) return 'shutdown'
 
   const e = err as { error_code?: number; description?: string }