switchroom 0.18.12 → 0.18.13

package/telegram-plugin/send-gate.ts

@@ -50,11 +50,13 @@
  *
  * SAFETY / ROLLOUT
  * ----------------
- * Feature-flagged and default-OFF (`SWITCHROOM_TELEGRAM_SEND_GATE=1` to enable,
- * following the `SWITCHROOM_*=== '1'` gateway flag convention). When disabled,
- * `gate()` is a pure passthrough to the wrapped call — zero behaviour change.
- * This is PR 1 of 3; priority-class shedding + degraded mode (PR 2) and
- * observability + operator alert (PR 3) build on the counters exposed here.
+ * ON BY DEFAULT in every install — an escape hatch, not an opt-in feature.
+ * `SWITCHROOM_TELEGRAM_SEND_GATE=0` (or `false`/`off`/`no`) is the safety valve
+ * that disables it without a rebuild, following the repo's default-on kill-
+ * switch convention (`midTurnFloorEnabled`, `SWITCHROOM_RATE_LIMIT_OVERAGE=0`).
+ * When disabled, `gate()` is a pure passthrough to the wrapped call — zero
+ * behaviour change. Priority-class shedding + degraded mode and observability +
+ * operator alert build on the counters exposed here.
  *
  * DETERMINISM / TESTABILITY
  * -------------------------
@@ -356,6 +358,26 @@ interface PendingEdit {
   promise: Promise<unknown>
   resolve: (v: unknown) => void
   reject: (e: unknown) => void
+  /**
+   * Effective priority of the CURRENTLY-queued edit for this message. Set when
+   * the pending edit is created and UPGRADED (never downgraded) on coalesce, so
+   * that a `critical` edit coalescing onto a non-critical driver still gets the
+   * critical fail-fast treatment. The driver reads THIS (not the driver-start
+   * opts) to decide fail-fast vs unbounded admit (F2, review 2026-07-12).
+   */
+  priorityClass: PriorityClass
+}
+
+/** Total order over priority classes: cosmetic < useful < critical. */
+const PRIORITY_RANK: Record<PriorityClass, number> = {
+  cosmetic: 0,
+  useful: 1,
+  critical: 2,
+}
+
+/** Return the HIGHER-priority of two classes (upgrade-only; never downgrades). */
+function maxPriority(a: PriorityClass, b: PriorityClass): PriorityClass {
+  return PRIORITY_RANK[b] > PRIORITY_RANK[a] ? b : a
 }
 
 interface MessageEditState {
@@ -806,7 +828,37 @@ export function createSendGate(config: SendGateConfig): SendGate {
           continue
         }
 
-        await admit(bucketsFor(opts))
+        // A `critical` edit must NEVER block unbounded (part3-design §3). Mirror
+        // the non-edit critical path in `gate`: admit via the priority-aware loop
+        // so a flood-wait ban longer than the fail-fast ceiling rejects with a
+        // structured FLOOD_WAIT_ACTIVE — and a window that EXTENDS past the
+        // ceiling while we wait out a short window converts to fail-fast too (M2,
+        // review PR #3106) — instead of the unbounded `admit` below, which would
+        // re-introduce the multi-hour reply wedge the send-gate exists to
+        // eliminate (F4, review 2026-07-11). Non-critical edits keep PR 1's
+        // unbounded coalescing admit unchanged.
+        //
+        // Read the CURRENT pending edit's class (`p.priorityClass`), NOT the
+        // driver-start `opts`: a `critical` edit that coalesced onto a driver
+        // started by a non-critical edit upgraded `p.priorityClass`, and MUST
+        // fail-fast here rather than ride the non-critical unbounded admit for
+        // the whole ban (F2, review 2026-07-12).
+        if (p.priorityClass === 'critical') {
+          const outcome = await admitPriority(bucketsFor(opts), 'critical')
+          if (outcome.result === 'failfast') {
+            counters.failedFast++
+            const retryAfterSec = Math.ceil((outcome.untilTs - clock.now()) / 1000)
+            openScopedWindowsForOpts(opts, outcome.untilTs)
+            // Reject THIS edit's own promise (fail fast) and loop: a distinct
+            // newer edit that arrived during the wait owns a fresh state.pending
+            // and is handled on the next iteration.
+            p.reject(makeFloodWaitActiveError(retryAfterSec, outcome.untilTs, null))
+            continue
+          }
+          // outcome.result === 'ok' → admitPriority already consumed the buckets.
+        } else {
+          await admit(bucketsFor(opts))
+        }
         // Reserve the send-start time BEFORE awaiting the network so the floor
         // is measured from send start (matches the per-message serialization).
         state.lastSentMs = clock.now()
@@ -874,6 +926,17 @@ export function createSendGate(config: SendGateConfig): SendGate {
     // a coalesced revert so nothing needless hits the API. All callers share the
     // single pending promise, which resolves with the coalesced send's result.
     if (state.pending) {
+      // Upgrade (never downgrade) the queued edit's effective priority. A
+      // `critical` edit coalescing onto a `useful`/`cosmetic` pending edit must
+      // ride the driver's critical fail-fast path — otherwise the critical work
+      // rides the non-critical unbounded admit and blocks for a whole flood ban
+      // (F2, review 2026-07-12). We upgrade even when the hash is unchanged (a
+      // no-op payload from a critical caller still deserves fail-fast, not an
+      // unbounded block); a lower-priority coalesce leaves the class intact.
+      state.pending.priorityClass = maxPriority(
+        state.pending.priorityClass,
+        opts.priorityClass ?? 'useful',
+      )
       if (state.pending.hash !== hash) {
         counters.coalesced++
         state.pending.hash = hash
@@ -905,6 +968,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
       promise,
       resolve,
       reject,
+      priorityClass: opts.priorityClass ?? 'useful',
     }
     state.pending = pending
     if (!state.running) void drive(state, opts)
@@ -976,7 +1040,17 @@ export function createSendGate(config: SendGateConfig): SendGate {
   return { gate, openFloodWindow, stats }
 }
 
-/** Read the feature flag using the standard `SWITCHROOM_*=== '1'` convention. */
+/**
+ * The send gate is an ESCAPE HATCH, not an opt-in feature: it is ON BY DEFAULT
+ * in every install and can be disabled as a safety valve. Mirrors the repo's
+ * default-on kill-switch convention (`midTurnFloorEnabled`, `PIN_STATUS_WHILE_
+ * WORKING`, `SWITCHROOM_RATE_LIMIT_OVERAGE`): enabled unless
+ * `SWITCHROOM_TELEGRAM_SEND_GATE` is explicitly set to a falsey/off value
+ * (`0`/`false`/`off`/`no`, case-insensitive, trimmed). Unset → enabled.
+ */
 export function sendGateEnabledFromEnv(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.SWITCHROOM_TELEGRAM_SEND_GATE === '1'
+  const v = env.SWITCHROOM_TELEGRAM_SEND_GATE
+  if (v == null) return true
+  const t = v.trim().toLowerCase()
+  return !(t === '0' || t === 'false' || t === 'off' || t === 'no')
 }

package/telegram-plugin/session-tail.ts

@@ -41,7 +41,8 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return env.PROGRESS_CARD_MULTI_AGENT !== '0'
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
-import { createToolLabelSidecar, type ToolLabelSidecar } from './tool-label-sidecar.js'
+import { isTransientUpstreamSignal } from './model-unavailable.js'
+import { createToolLabelSidecar, type ToolLabelSidecar, type SidecarOptions } from './tool-label-sidecar.js'
 import { isModelSentinel } from './model-label.js'
 
 /** Match Claude Code's cli.js VX() function. */
@@ -668,13 +669,26 @@ export function detectErrorInTranscriptLine(
       typeof obj.apiErrorStatus === 'number' ? obj.apiErrorStatus : null
     const errStr = typeof obj.error === 'string' ? obj.error : ''
     const text = extractAssistantText(obj)
-    // A 429 in this shape is a subscription usage-limit hit (it carries
-    // a reset time) — classify it quota-exhausted so the operator event
-    // resolves to an auto-fallback-eligible kind. Other statuses fall
+    // A 429 in this shape is USUALLY a subscription usage-limit wall (it
+    // carries a reset time) — classify it quota-exhausted so the operator
+    // event resolves to an auto-fallback-eligible kind that always shows the
+    // "model unavailable" card. BUT Anthropic also emits a 429 for a TRANSIENT
+    // per-account burst / RPM throttle whose wording explicitly negates the
+    // account-quota reading ("This request would exceed your account's rate
+    // limit … not your usage limit"). That is a self-healing few-second throttle
+    // Claude Code retries internally — blanket-labeling it quota-exhausted fired
+    // a false scary card on the fleet (carrie incident, 2026-07-12). So a 429 is
+    // only quota-exhausted when it LACKS an explicit transient-burst marker;
+    // with one, classify it rate-limited so it takes the calm path (no card, no
+    // failover). Keyed on the explicit transient NEGATION (canonical list in
+    // model-unavailable.ts) — an ambiguous 429 that merely says "limit" stays
+    // quota-exhausted, biasing toward surfacing a real wall. Other statuses fall
     // through to the shared classifier.
     const kind: OperatorEventKind =
       status === 429
-        ? 'quota-exhausted'
+        ? isTransientUpstreamSignal(`${text}\n${errStr}`)
+          ? 'rate-limited'
+          : 'quota-exhausted'
         : classifyClaudeError({ type: errStr, status, message: text })
     // An `isApiErrorMessage` line is Claude surfacing the failure to the
     // user — terminal by construction (Claude writes this shape only
@@ -781,6 +795,13 @@ export interface SessionTailConfig {
   claudeHome?: string
   /** How often to re-scan for a new active session file (ms). Default 500. */
   rescanIntervalMs?: number
+  /**
+   * Idle window before an inactive sub-agent FSWatcher (and its PreToolUse
+   * sidecar) is reaped, in ms. Defaults to 5 minutes — well past the 99th-
+   * percentile sub-agent completion time. Exposed only so tests can drive the
+   * reap deterministically without a 5-minute wall-clock wait.
+   */
+  subTailIdleReapMs?: number
   /** Optional logger. */
   log?: (msg: string) => void
   /** Called for each parsed event. */
@@ -791,6 +812,18 @@ export interface SessionTailConfig {
    * TODO(Phase 4b): wire this to the gateway's emitOperatorEvent pipeline.
    */
   onOperatorEvent?: (event: TailOperatorEvent) => void
+  /**
+   * PreToolUse sidecar factory. Defaults to the real `createToolLabelSidecar`;
+   * production never sets this. It exists as a dependency-injection seam so the
+   * M1 FD-leak reap test can drive a fake sidecar per session WITHOUT
+   * `vi.mock`-ing the shared `tool-label-sidecar` module: bun's `vi.mock` is
+   * process-global (not file-scoped like vitest), and the CI bun-test shard
+   * runs the whole `tests/` dir in ONE process, so a module-mock here would
+   * leak into the real `tool-label-sidecar.test.ts` suite and break it. This
+   * mirrors the repo's bun-safe injection precedent (`vault-write-posture`'s
+   * optional `deps` param).
+   */
+  createSidecar?: (opts: SidecarOptions) => ToolLabelSidecar
 }
 
 export interface SessionTailHandle {
@@ -887,6 +920,7 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
   // $TELEGRAM_STATE_DIR/tool-labels-<session_id>.jsonl. Each sub-agent
   // has its OWN sessionId (its jsonl filename stem), so we key by that.
   const sidecars = new Map<string, ToolLabelSidecar>()
+  const createSidecar = config.createSidecar ?? createToolLabelSidecar
   const stateDirForSidecar = process.env.TELEGRAM_STATE_DIR ?? null
   function sessionIdForFile(file: string | null): string | null {
     if (!file) return null
@@ -898,7 +932,7 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
     const existing = sidecars.get(sessionId)
     if (existing) return existing
     try {
-      const s = createToolLabelSidecar({ stateDir: stateDirForSidecar, sessionId })
+      const s = createSidecar({ stateDir: stateDirForSidecar, sessionId })
       sidecars.set(sessionId, s)
       // Real-time draft-mirror source: emit a `tool_label` event the moment
       // the hook writes a label (flush-independent), so the gateway can
@@ -913,6 +947,22 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       return null
     }
   }
+  /**
+   * M1 FD-leak fix: stop and forget the PreToolUse sidecar for a session that
+   * has ended (a rotated-away parent session, or a reaped sub-agent). Each
+   * sidecar holds its own stat-poll timer (and, on real fs, a file handle);
+   * pre-fix they were only reaped in `stop()`, so every session rotation
+   * (`/clear`, compaction → new sessionId) and every finished sub-agent leaked
+   * one for the gateway's life. Idempotent — a no-op when the key is absent.
+   */
+  function stopSidecar(sessionId: string | null): void {
+    if (!sessionId) return
+    const s = sidecars.get(sessionId)
+    if (!s) return
+    try { s.stop() } catch { /* ignore */ }
+    sidecars.delete(sessionId)
+  }
+
   function decorate(ev: SessionEvent, sessionId: string | null): SessionEvent {
     if (!sessionId) return ev
     if (ev.kind !== 'tool_use' && ev.kind !== 'sub_agent_tool_use') return ev
@@ -1024,6 +1074,19 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       try { watcher.close() } catch { /* ignore */ }
       watcher = null
     }
+    // M1 FD-leak fix: we are rotating the PARENT tail off `currentFile`; its
+    // PreToolUse sidecar is no longer needed (its watcher just closed). Reap it
+    // so `/clear`- and compaction-driven session rotations don't accumulate one
+    // idle sidecar poll-timer per rotation. Parent session ids are the JSONL
+    // stem (`<uuid>`); sub-agent sidecars are keyed by `agent-<id>` stems and
+    // owned by their sub-tail (reaped in `reapIdleSubTails`), so this never
+    // stops a sidecar a live sub-tail still depends on. A later re-attach to
+    // this same file transparently recreates the sidecar via `ensureSidecar`.
+    const rotatedAwaySid = sessionIdForFile(currentFile)
+    const nextSid = sessionIdForFile(file)
+    if (rotatedAwaySid != null && rotatedAwaySid !== nextSid) {
+      stopSidecar(rotatedAwaySid)
+    }
     currentFile = file
     const prior = fileCursors.get(file)
     if (prior != null) {
@@ -1113,7 +1176,12 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
    * very-long task (rescanSubagents picks the file back up on the
    * next tick if it grows).
    */
-  const IDLE_FSWATCH_TTL_MS = 5 * 60 * 1000
+  // Floor-clamp the reap window: a 0 / negative override would make
+  // `reapIdleSubTails` treat every live sub-tail as instantly idle
+  // (cutoff = Date.now() - 0 ≥ lastActivityAt), reaping every live
+  // sidecar on the first tick. Only tests set this today, but the clamp
+  // makes the footgun unreachable — the smallest sane window is 1s.
+  const IDLE_FSWATCH_TTL_MS = Math.max(1000, config.subTailIdleReapMs ?? 5 * 60 * 1000)
 
   function readSub(t: SubTail): void {
     if (stopped) return
@@ -1254,6 +1322,13 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
           try { t.watcher.close() } catch { /* ignore */ }
           t.watcher = null
         }
+        // M1 FD-leak fix: reap the sub-agent's PreToolUse sidecar alongside its
+        // file watcher. Sub-agent sidecars are keyed by the sub file's stem
+        // (`agent-<id>`), created lazily by `decorate` while reading the sub
+        // JSONL. Pre-fix `reapIdleSubTails` closed the sub-tail watcher but left
+        // the sidecar (and its poll timer) alive until `stop()`, so a long-lived
+        // agent leaked one sidecar per finished sub-agent.
+        stopSidecar(sessionIdForFile(t.file))
         subTails.delete(file)
         log?.(`session-tail: reaped idle sub ${t.agentId} (${file})`)
       }

package/telegram-plugin/subagent-watcher.ts

@@ -1779,21 +1779,39 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       maybySendStateTransition(agentId)
     }
 
-    // Set up FSWatcher
-    try {
-      tail.watcher = fs.watch(filePath, () => {
-        if (stopped) return
-        const entry = registry.get(agentId)
-        const t = tails.get(agentId)
-        if (!entry || !t) return
-        checkBootPromotionGrowth(entry, t, nowFn())
-        readSubTail(entry, t, nowFn(), (desc) => {
-          log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
-        }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress)
-        maybySendStateTransition(agentId)
-      })
-    } catch (err) {
-      log?.(`subagent-watcher: fs.watch failed for ${agentId}: ${(err as Error).message}`)
+    // Set up FSWatcher.
+    //
+    // FD-leak fix (H2): only open an inotify watch when it can do real work.
+    // A historical entry that is done-at-boot (already `scheduleTerminalCleanup`d
+    // just above) or a stale `running` entry that will never be promoted (no
+    // `bootPromotionPending`) has NO live transition left to observe —
+    // `checkStalls` skips every historical entry, so such an entry never
+    // reaches a terminal transition and `scheduleTerminalCleanup` never runs
+    // for it. Opening an `fs.watch` for one leaks its inotify FD for the whole
+    // gateway lifetime (the dozens-to-hundreds of dead prior-session
+    // `running` JSONLs a 24/7 agent accumulates). The poll loop still reads
+    // any registered running entry defensively, so dropping the watcher here
+    // costs nothing but the leaked FD. Open the watch only for a live worker
+    // or a historical one still awaiting boot-promotion growth confirmation.
+    const needsWatcher = !entry.historical || entry.bootPromotionPending != null
+    if (needsWatcher) {
+      try {
+        tail.watcher = fs.watch(filePath, () => {
+          if (stopped) return
+          const entry = registry.get(agentId)
+          const t = tails.get(agentId)
+          if (!entry || !t) return
+          checkBootPromotionGrowth(entry, t, nowFn())
+          readSubTail(entry, t, nowFn(), (desc) => {
+            log?.(`subagent-watcher: description updated for ${agentId}: ${desc}`)
+          }, fs, log, db, parentStateDir, config.onUnstall, cleanupTerminalAgent, config.onProgress)
+          maybySendStateTransition(agentId)
+        })
+      } catch (err) {
+        log?.(`subagent-watcher: fs.watch failed for ${agentId}: ${(err as Error).message}`)
+      }
+    } else {
+      log?.(`subagent-watcher: ${agentId} historical/terminal at registration — not opening an FSWatcher (no live transition to observe)`)
     }
   }
 
@@ -1855,7 +1873,17 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     }
     if (n >= pending.deadlineAt) {
       entry.bootPromotionPending = undefined
-      log?.(`subagent-watcher: ${entry.agentId} never observed post-boot JSONL growth within the window — leaving historical/orphan (not promoting; avoids synthesising a stale 'completed' handback from a worker killed before this restart)`)
+      // FD-leak fix (H2): the boot-promotion window elapsed with no growth,
+      // so this entry is now a permanent historical/orphan that `checkStalls`
+      // skips — it will never reach terminal cleanup. Release the FSWatcher we
+      // opened purely for growth-confirmation now; the poll loop remains the
+      // fallback reader if the file ever resumes (rescan re-registers on a
+      // fresh transition).
+      if (tail.watcher) {
+        try { tail.watcher.close() } catch { /* ignore */ }
+        tail.watcher = null
+      }
+      log?.(`subagent-watcher: ${entry.agentId} never observed post-boot JSONL growth within the window — leaving historical/orphan (not promoting; avoids synthesising a stale 'completed' handback from a worker killed before this restart); released growth-confirmation FSWatcher`)
     }
   }
 
@@ -2386,8 +2414,35 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
    * We walk: <agentDir>/.claude/projects/ → each project dir → each session dir
    * → subagents/ → agent-*.jsonl
    */
+  /**
+   * FD-leak fix (H1): close and forget any directory FSWatcher whose watched
+   * directory no longer exists on disk. Every new Claude session mints a fresh
+   * `<sessionId>/subagents/` dir (and `workflows/wf_<id>` sub-dirs); when Claude
+   * Code reaps a prior session's directory, the scan loop below simply skips
+   * the vanished path (`existsSync` guard) WITHOUT closing the watcher it had
+   * opened for it — Node only frees the inotify FD on `.close()`, so each dead
+   * session leaked one dir watcher for the whole gateway lifetime. Sweeping on
+   * every rescan releases them deterministically the tick after the dir goes
+   * away, and also covers a slug that transitions to "foreign" (skipped by the
+   * allow-list filter below). Deleting the current key while iterating a Map's
+   * entries() is safe in JS.
+   */
+  function pruneVanishedDirWatchers(): void {
+    for (const [dirPath, w] of dirWatchers) {
+      if (!fs.existsSync(dirPath)) {
+        try { w.close() } catch { /* ignore */ }
+        dirWatchers.delete(dirPath)
+        log?.(`subagent-watcher: released dir watcher for vanished ${dirPath}`)
+      }
+    }
+  }
+
   function rescanSubagentDirs(): void {
     if (stopped) return
+    // Release watchers for directories reaped since the last tick BEFORE the
+    // early-returns below, so a projectsRoot that vanishes entirely still frees
+    // every child dir watcher.
+    pruneVanishedDirWatchers()
     const claudeHome = join(agentDir, '.claude')
     const projectsRoot = join(claudeHome, 'projects')
     if (!fs.existsSync(projectsRoot)) return

package/telegram-plugin/tests/approval-hold-outcome.test.ts

@@ -261,14 +261,27 @@ describe('gateway wiring — the leash', () => {
     'utf8',
   )
 
+  /**
+   * One anchor + one span for the TTL sweep, shared by every pin below.
+   *
+   * They drifted apart before: one pin still anchored on the inline `for` loop the
+   * shared-sweep extraction had deleted, so it silently matched nothing. A single
+   * definition means a future move breaks every pin at once — loudly — instead of
+   * quietly disarming one of them.
+   *
+   * The span must cover the whole `onExpire` body (~4.2k chars today).
+   */
+  const SWEEP_ANCHOR = 'sweepPermissionTtl({'
+  const SWEEP_SPAN = 6000
+
   it('the TTL sweep routes through the SHARED shouldExpirePermission()', () => {
     // This pin is no longer the safety net — the behavioural tests above are, and
     // they now drive the same `shouldExpirePermission` the gateway does, so deleting
     // the leash turns them RED. This only guards the WIRING: that the sweep can't
     // regrow a private inline check that drifts from what the test exercises.
-    const sweepStart = GATEWAY_SRC.indexOf('sweepPermissionTtl({')
+    const sweepStart = GATEWAY_SRC.indexOf(SWEEP_ANCHOR)
     expect(sweepStart).toBeGreaterThan(-1)
-    const sweep = GATEWAY_SRC.slice(sweepStart, sweepStart + 3500)
+    const sweep = GATEWAY_SRC.slice(sweepStart, sweepStart + SWEEP_SPAN)
     expect(GATEWAY_SRC).toContain('sweepPermissionTtl({')
     // …and must NOT carry its own copy of the leash or the raw TTL comparison.
     // …and the gateway must not regrow a private inline leash check.
@@ -288,9 +301,27 @@ describe('gateway wiring — the leash', () => {
 
   it('nothing in the permission path auto-approves', () => {
     // Never, under any circumstance. A held approval that "times out" into an
-    // allow would be the worst possible reading of Ken's call.
-    const sweepStart = GATEWAY_SRC.indexOf('for (const [k, v] of pendingPermissions) {')
-    const sweep = GATEWAY_SRC.slice(sweepStart, sweepStart + 2500)
+    // ALLOW would be the worst possible reading of Ken's call — the other half of
+    // no-self-escalation.
+    //
+    // This pin was DEAD. It anchored on `for (const [k, v] of pendingPermissions) {`,
+    // the inline loop that the shared-sweep extraction deleted. `indexOf` returned
+    // -1, `slice(-1, 2499)` returned the EMPTY STRING, and `not.toContain` passes on
+    // "" — so the sweep could be changed to dispatch `behavior: 'allow'` and all 13
+    // tests stayed green. Exactly the failure class this file exists to prevent,
+    // inside the file that exists to prevent it.
+    //
+    // Two rules now, and they apply to every grep pin here:
+    //   1. ASSERT THE ANCHOR RESOLVES. A silent -1 is what turns a pin into a lie.
+    //   2. Assert something POSITIVE inside the window, so a window that is too
+    //      small (or empty) fails loudly instead of vacuously passing a `not`.
+    const sweepStart = GATEWAY_SRC.indexOf(SWEEP_ANCHOR)
+    expect(sweepStart).toBeGreaterThan(-1)
+    const sweep = GATEWAY_SRC.slice(sweepStart, sweepStart + SWEEP_SPAN)
+
+    // POSITIVE: proves the window actually covers the verdict dispatch.
+    expect(sweep).toContain("behavior: 'deny',")
+    // …and the sweep may only ever deny. Never allow.
     expect(sweep).not.toContain("behavior: 'allow'")
   })
 })

package/telegram-plugin/tests/callback-query-handlers.test.ts

@@ -41,6 +41,43 @@ import { createSweepableStore } from '../gateway/pending-state-stores.js'
 import { StagingMap } from '../secret-detect/staging.js'
 import { InlineKeyboard } from 'grammy'
 
+// Mock the auth-broker client so the `auth:use:` swap path is observable
+// (spy on setActive) without a live UDS broker. Only handleAuthDashboardCallback
+// touches getAuthBrokerClient, so this is inert for every other family here.
+//
+// The spy is created *inside* the factory and re-exported as a test-only
+// handle (`__setActiveSpy`) rather than closed over from a `vi.hoisted`
+// binding: bun's vitest-compat layer implements `vi.mock`/`vi.fn` but NOT
+// `vi.hoisted`, so a hoisted-closure mock throws `vi.hoisted is not a
+// function` under `bun test` (CI's bun-test-run shard runs this whole dir).
+// A single `setActive` instance is closed over and returned by every
+// `getAuthBrokerClient()` call, so the handler and the tests observe the
+// same spy.
+vi.mock('../gateway/auth-broker-client.js', () => {
+  const setActive = vi.fn(async () => ({ active: 'acct-b', fanned: ['a1'] }))
+  return {
+    getAuthBrokerClient: vi.fn(async () => ({ setActive })),
+  }
+})
+import { getAuthBrokerClient } from '../gateway/auth-broker-client.js'
+// The mocked getAuthBrokerClient closes over one shared `setActive` spy and
+// returns it on every call, so resolving the client here yields the SAME spy
+// the handler observes. A getter defers the read to test-run time (after the
+// mock is live under both runners); a beforeEach caches the resolved spy.
+let resolvedSetActiveSpy: ReturnType<typeof vi.fn> | undefined
+const brokerMock = {
+  get setActive(): ReturnType<typeof vi.fn> {
+    if (!resolvedSetActiveSpy) throw new Error('setActive spy not resolved yet')
+    return resolvedSetActiveSpy
+  },
+}
+beforeEach(async () => {
+  const client = (await getAuthBrokerClient('test-agent')) as {
+    setActive: ReturnType<typeof vi.fn>
+  }
+  resolvedSetActiveSpy = client.setActive
+})
+
 // ── Fakes ────────────────────────────────────────────────────────────────
 
 interface FakeCtxOpts {
@@ -568,6 +605,34 @@ describe('handleAuthDashboardCallback', () => {
       show_alert: false,
     })
   })
+
+  // Security gate (found in an adversarial security review): the auth: family
+  // is a mutating callback family (auth:use:<label> → broker.setActive, a
+  // fleet-wide OAuth account swap) and MUST enforce the same allowFrom gate as
+  // every sibling family. Without the gate, any tapper on an admin forum/
+  // supergroup with an empty group allowFrom could swap the active account.
+  it('rejects an auth:use swap from a sender not on allowFrom (never reaches setActive)', async () => {
+    const { deps } = makeDeps() // allowFrom = ['111','222']
+    const h = createCallbackQueryHandlers(deps)
+    brokerMock.setActive.mockClear()
+    const { ctx, raw } = makeCtx({ senderId: '999', data: 'auth:use:acct-b' })
+    await h.handleAuthDashboardCallback(ctx)
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith({ text: 'Not authorized.' })
+    // The load-bearing assertion: the swap must not fire for an unauthorized tap.
+    expect(brokerMock.setActive).not.toHaveBeenCalled()
+  })
+
+  it('lets an allowFrom sender through to the setActive swap path', async () => {
+    const { deps } = makeDeps()
+    const h = createCallbackQueryHandlers(deps)
+    brokerMock.setActive.mockClear()
+    const { ctx, raw } = makeCtx({ senderId: '111', data: 'auth:use:acct-b' })
+    await h.handleAuthDashboardCallback(ctx)
+    expect(brokerMock.setActive).toHaveBeenCalledWith('acct-b')
+    expect(raw.answerCallbackQuery).toHaveBeenCalledWith(
+      expect.objectContaining({ text: expect.stringContaining('Switched fleet → acct-b') }),
+    )
+  })
 })
 
 // ── vg:* — grant wizard + management ────────────────────────────────────

package/telegram-plugin/tests/gateway-outbound-redact.test.ts

@@ -77,6 +77,63 @@ describe('gateway outbound secret-scrub — structural wiring', () => {
     expect(truncIdx).toBeGreaterThan(redactIdx) // mask BEFORE the slice
   })
 
+  it('ask_user: redacts question + option labels at entry, BEFORE the send', () => {
+    // F1 — ask_user sent the question + button labels unredacted. The scrub
+    // must run at the top of executeAskUser (via redactAskUserFields), before
+    // the keyboard is built and the question is sent to Telegram.
+    const start = src.indexOf('async function executeAskUser(')
+    const redactIdx = src.indexOf('redactAskUserFields(args.question, args.options', start)
+    const keyboardIdx = src.indexOf('const keyboard = new InlineKeyboard()', start)
+    const sendIdx = src.indexOf('sendRichMessage(args.chatId, richMessage(args.question)', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(keyboardIdx).toBeGreaterThan(redactIdx) // mask BEFORE labels become buttons
+    expect(sendIdx).toBeGreaterThan(redactIdx) // mask BEFORE the question is sent
+  })
+
+  it('send_checklist: redacts title + task text BEFORE rawSendChecklist', () => {
+    // F2 — checklist title + task strings were sent unredacted.
+    const start = src.indexOf('async function executeSendChecklist(')
+    const redactIdx = src.indexOf('redactChecklistFields(', start)
+    const sendIdx = src.indexOf('rawSendChecklist({', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(sendIdx).toBeGreaterThan(redactIdx) // mask BEFORE the send
+  })
+
+  it('update_checklist: redacts title + task text BEFORE rawEditMessageChecklist', () => {
+    // F2 sibling — update_checklist shares the identical leak class.
+    const start = src.indexOf('async function executeUpdateChecklist(')
+    const redactIdx = src.indexOf('redactChecklistFields(', start)
+    const editIdx = src.indexOf('rawEditMessageChecklist({', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(editIdx).toBeGreaterThan(redactIdx) // mask BEFORE the edit
+  })
+
+  it('pty draft-preview: redacts at the gateway boundary BEFORE the stream', () => {
+    // F3 — the PTY-tail partial (assistant reply text extracted from the TUI)
+    // forwards straight to the draft-preview stream. Mask at the top of
+    // handlePtyPartial, before it hands off to handlePtyPartialPure.
+    const start = src.indexOf('function handlePtyPartial(text: string): void {')
+    const redactIdx = src.indexOf(`redactOutboundText(text, 'pty_preview')`, start)
+    const pureIdx = src.indexOf('handlePtyPartialPure(text, state', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(pureIdx).toBeGreaterThan(redactIdx) // mask BEFORE the stream push
+  })
+
+  it('pty activity: redacts at the gateway boundary BEFORE the stream', () => {
+    // F3 — the (currently-unwired) PTY-activity lane is masked too so the fix
+    // is durable if it is ever re-armed.
+    const start = src.indexOf('function handlePtyActivity(text: string): void {')
+    const redactIdx = src.indexOf(`redactOutboundText(text, 'pty_activity')`, start)
+    const streamIdx = src.indexOf('handleStreamReply(', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(streamIdx).toBeGreaterThan(redactIdx) // mask BEFORE the stream
+  })
+
   it('does not log the secret value when a mask fires', () => {
     const idx = src.indexOf('function redactOutboundText(')
     const body = src.slice(idx, idx + 400)