switchroom 0.18.11 → 0.18.13

package/telegram-plugin/retry-api-call.ts

@@ -16,7 +16,8 @@
  *
  *   | Thrown error                                  | This wrapper does                          |
  *   |-----------------------------------------------|--------------------------------------------|
- *   | GrammyError 429                               | sleep retry_after seconds, retry          |
+ *   | GrammyError 429 (retry_after <= ceiling)      | sleep retry_after seconds, retry          |
+ *   | GrammyError 429 (retry_after >  ceiling)      | record window, throw `FLOOD_WAIT_ACTIVE`  |
  *   | GrammyError 400 "message is not modified"     | swallow, return undefined                 |
  *   | GrammyError 400 "message to edit not found"   | swallow, return undefined                 |
  *   | GrammyError 400 "message to delete not found" | swallow, return undefined                 |
@@ -43,6 +44,39 @@ export interface RetryCallOpts {
    * call sites to self-document. Future: surface in retry logs / metrics.
    */
   verb?: string
+  /**
+   * Chat type of the destination (private / group / supergroup / channel).
+   * Consumed by the outbound send gate (#3084, send-gate.ts) to key the
+   * per-group bucket. Optional and additive — the retry policy ignores it.
+   */
+  chatType?: 'private' | 'group' | 'supergroup' | 'channel'
+  /**
+   * For edit calls: the target message id. Enables the send gate's
+   * per-message edit floor + last-write-wins coalescing. Retry policy ignores.
+   */
+  messageId?: number
+  /**
+   * For edit calls: the rendered payload the send gate hashes to skip no-op
+   * edits (identical → dropped) and to coalesce. Retry policy ignores it.
+   */
+  editPayload?: unknown
+  /**
+   * Priority class for the outbound send gate's shedding + degraded mode
+   * (#3084 PR 2, send-gate.ts). The retry policy itself ignores it; it only
+   * governs how the gate treats the call when it is under pressure or a flood
+   * window is open:
+   *   - `critical`  — final reply chunks, approval / vault cards, error
+   *     notices. Never shed; queued unbounded. In degraded mode a critical
+   *     send waits for a short window but fails fast (structured
+   *     `FLOOD_WAIT_ACTIVE`) when the remaining window is long.
+   *   - `useful`    — progress-card creation, worker handbacks, checklists,
+   *     boot/config cards. Queued with a TTL; dropped when stale. DEFAULT
+   *     when unset.
+   *   - `cosmetic`  — typing, reactions, all card EDITS, stream updates,
+   *     heartbeats. Shed immediately when no token is free OR any flood
+   *     window is open.
+   */
+  priorityClass?: 'critical' | 'useful' | 'cosmetic'
 }
 
 export interface RetryObserver {
@@ -57,6 +91,24 @@ export interface RetryObserver {
 export interface RetryApiCallConfig {
   /** Max retries before giving up. Defaults to 3. */
   maxRetries?: number
+  /**
+   * Ceiling (ms) on how long a single 429 flood-wait may be slept IN-PROCESS.
+   * A `retry_after` above this is not slept at all — the window is recorded and
+   * `FLOOD_WAIT_ACTIVE` is thrown instead (see #3084). Defaults to
+   * `DEFAULT_MAX_FLOOD_SLEEP_MS`.
+   */
+  maxFloodSleepMs?: number
+  /**
+   * Remaining ms of a KNOWN-OPEN per-bot flood window, or 0 when none.
+   *
+   * Wired to the #2923 circuit-breaker state file (see
+   * `makeFloodWaitProbe`). When the remaining window is LONGER than
+   * `maxFloodSleepMs`, `retryApiCall` short-circuits BEFORE issuing the call:
+   * the ban is per-bot-token, so nothing can succeed while it's open, and
+   * every attempt only feeds the flood counter (#3084). Fails OPEN — a
+   * missing/corrupt/throwing probe means "no window", never a silenced bot.
+   */
+  floodWaitRemainingMs?: () => number
   /** Sleep helper — injected so tests can use fake timers. */
   sleep?: (ms: number) => Promise<void>
   /** Optional observer hooks. */
@@ -105,6 +157,107 @@ export function isLocalResourceError(err: unknown): boolean {
  */
 export const LOCAL_RESOURCE_EXHAUSTED = 'LOCAL_RESOURCE_EXHAUSTED'
 
+/**
+ * Thrown when every retry is exhausted — a network partition, a Telegram 5xx
+ * outage, or a short-but-persistent 429 (only 429s longer than the in-process
+ * sleep ceiling raise FLOOD_WAIT_ACTIVE; shorter ones are slept, retried, and
+ * end here). Exported as a constant because `approval-hold.ts:holdReasonFor`
+ * classifies on it to decide whether an undeliverable approval is HELD — a
+ * string that drifts would silently reopen the auto-deny hole.
+ */
+export const GIVE_UP_MESSAGE = 'retryApiCall: max retries exceeded'
+
+/**
+ * Marker error thrown when Telegram's reported `retry_after` exceeds the
+ * in-process sleep ceiling (#3084) — i.e. the bot is under a LONG per-bot
+ * flood ban, not a momentary rate-limit blip.
+ *
+ * Carries `{ retryAfterSec, untilTs, original }` so a caller can render a
+ * useful degraded state ("rate-limited by Telegram until HH:MM") instead of
+ * being parked on an await for hours.
+ */
+export const FLOOD_WAIT_ACTIVE = 'FLOOD_WAIT_ACTIVE'
+
+/**
+ * Shape of the error thrown for an over-ceiling flood-wait.
+ *
+ * It deliberately carries Telegram's OWN 429 field shape (`error_code: 429`,
+ * `parameters.retry_after`) in addition to the friendlier fields. Several
+ * best-effort card surfaces duck-type their rate-limit cooldown on exactly
+ * those two fields rather than on `instanceof GrammyError`:
+ *
+ *   - `worker-activity-feed.ts` `extractRetryAfterSecs` → `noteRateLimited`
+ *   - `issues-card.ts` `extractRetryAfterSecs`
+ *   - `pending-work-progress.ts` (its catch assumes upstream retry_after backoff)
+ *
+ * All three route through `robustApiCall`, so once retryApiCall stops sleeping
+ * a long ban and starts THROWING, they see this marker instead of the raw
+ * GrammyError. Without `error_code`/`parameters` they would classify it as a
+ * generic 'transient' error, arm NO cooldown, and let their 5-6s heartbeats
+ * re-drive a fresh Bot API call into the still-open ban — thousands of requests
+ * over a 4.6h window, feeding the very flood counter #2923 exists to starve.
+ * Carrying the 429 shape makes the existing cooldown gates fire on the full
+ * window with no change to those modules.
+ *
+ * It remains a plain `Error` (NOT a `GrammyError`), so the `instanceof`-based
+ * probes — `isHtmlParseRejectError`, `isMessageTooLongError`,
+ * `isPhotoDimensionRejectError` — still correctly do not match it.
+ */
+export interface FloodWaitActiveError extends Error {
+  /** Telegram's reported retry_after, in seconds. */
+  retryAfterSec: number
+  /** Epoch ms at which the flood window is expected to expire. */
+  untilTs: number
+  /** Telegram's 429 code — see the duck-typing note above. */
+  error_code: 429
+  /** Telegram's 429 payload — see the duck-typing note above. */
+  parameters: { retry_after: number }
+  /** The originating GrammyError, or null for a pre-call short-circuit. */
+  original: unknown
+}
+
+/**
+ * Build the marker with the full Telegram-429 duck-type shape.
+ *
+ * Exported so the outbound send gate (#3084 PR 2) can COMPOSE the same
+ * structured error for its own degraded-mode fail-fast (a critical send into a
+ * long open flood window) rather than duplicating the 429 duck-type shape. One
+ * error shape means every downstream cooldown gate + the MCP reply path treat a
+ * gate fail-fast identically to a retry-layer flood-wait.
+ */
+export function makeFloodWaitActiveError(
+  retryAfterSec: number,
+  untilTs: number,
+  original: unknown,
+): FloodWaitActiveError {
+  return Object.assign(new Error(FLOOD_WAIT_ACTIVE), {
+    retryAfterSec,
+    untilTs,
+    error_code: 429 as const,
+    parameters: { retry_after: retryAfterSec },
+    original,
+  })
+}
+
+/** True when `err` is the `FLOOD_WAIT_ACTIVE` marker thrown by `retryApiCall`. */
+export function isFloodWaitActiveError(err: unknown): err is FloodWaitActiveError {
+  return err instanceof Error && err.message === FLOOD_WAIT_ACTIVE
+}
+
+/**
+ * Default ceiling on a single in-process flood-wait sleep: 120s.
+ *
+ * Why 120s and not 30-60s: the flood-waits this bot has historically ridden out
+ * successfully were 28s and 75s — sleeping through those is the RIGHT behaviour
+ * and must not regress, so the ceiling has to sit above 75s with headroom. Why
+ * not higher: the ban this guards against (#3084, overlord 2026-07-11) reported
+ * retry_after = 16739s (~4.6h). A 120s ceiling bounds the worst case in-process
+ * block to maxRetries × 120s (6s→6min at the default 3) instead of hours, which
+ * is short enough that a caller — and the human waiting on a reply — gets a
+ * degraded answer rather than an apparently-wedged agent.
+ */
+export const DEFAULT_MAX_FLOOD_SLEEP_MS = 120_000
+
 const DEFAULT_SLEEP = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
 
 /**
@@ -120,16 +273,56 @@ export function createRetryApiCall(
   config: RetryApiCallConfig = {},
 ): <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T> {
   const maxRetries = config.maxRetries ?? 3
+  const maxFloodSleepMs = config.maxFloodSleepMs ?? DEFAULT_MAX_FLOOD_SLEEP_MS
   const sleep = config.sleep ?? DEFAULT_SLEEP
   const observer = config.observer
   const log = config.log
   const onFloodWait = config.onFloodWait
+  const floodWaitRemainingMs = config.floodWaitRemainingMs
+
+  /**
+   * Remaining ms of a known-open flood window. FAILS OPEN: any throw from the
+   * probe (unreadable state dir, corrupt JSON, clock weirdness) is treated as
+   * "no window" — a broken marker file must never permanently silence the bot.
+   */
+  function openWindowMs(): number {
+    if (!floodWaitRemainingMs) return 0
+    try {
+      const ms = floodWaitRemainingMs()
+      return Number.isFinite(ms) && ms > 0 ? ms : 0
+    } catch {
+      return 0
+    }
+  }
 
   return async function retryApiCall<T>(
     fn: () => Promise<T>,
     opts?: RetryCallOpts,
   ): Promise<T> {
     for (let attempt = 0; attempt < maxRetries; attempt++) {
+      // #3084 — do not send INTO a known-open long ban. Failing the call fast
+      // (rather than sleeping it) is only safe if the caller can't just turn
+      // around and re-drive it: the card surfaces re-attempt on a 5-6s
+      // heartbeat, which over a 4.6h ban would be thousands of requests into
+      // the open window — the exact ban-extension the #2923 breaker exists to
+      // prevent. So the policy itself refuses to issue the call while the
+      // window is open. The ban is per-bot-TOKEN: nothing can succeed during
+      // it, so short-circuiting loses no delivery that would otherwise land.
+      //
+      // Only LONG windows short-circuit (remaining > the sleep ceiling). A
+      // short window is left to the normal path — it may already have expired
+      // server-side, and today's sleep-and-retry rides it out.
+      const remaining = openWindowMs()
+      if (remaining > maxFloodSleepMs) {
+        const retryAfterSec = Math.ceil(remaining / 1000)
+        log?.(
+          `telegram gateway: flood window still open for ${retryAfterSec}s — ` +
+            `not issuing the ${opts?.verb ?? 'api-call'} (would feed the ban)\n`,
+        )
+        const gated = makeFloodWaitActiveError(retryAfterSec, Date.now() + remaining, null)
+        observer?.onGiveUp?.({ attempts: attempt + 1, error: gated })
+        throw gated
+      }
       try {
         return await fn()
       } catch (err) {
@@ -164,6 +357,23 @@ export function createRetryApiCall(
           } catch {
             /* best-effort — never let the breaker hook break the retry path */
           }
+          // #3084: a LONG ban must not be slept in-process. On 2026-07-11
+          // overlord got retry_after = 16739s (~4.6h); `await sleep(delayMs)`
+          // parked the send path — and every caller awaiting it — for hours.
+          // That is a wedge primitive, not a retry. Above the ceiling we've
+          // already recorded the window (the breaker above suppresses
+          // non-essential sends for its duration); now fail FAST with a
+          // distinct non-retryable marker so the caller can surface a degraded
+          // state. Under the ceiling, behaviour is unchanged: sleep and retry.
+          if (delayMs > maxFloodSleepMs) {
+            log?.(
+              `telegram gateway: 429 flood ban of ${retryAfter}s exceeds the ` +
+                `${Math.round(maxFloodSleepMs / 1000)}s in-process sleep ceiling — ` +
+                `not sleeping it; surfacing degraded state\n`,
+            )
+            observer?.onGiveUp?.({ attempts: attempt + 1, error: err })
+            throw makeFloodWaitActiveError(retryAfter, Date.now() + delayMs, err)
+          }
           log?.(`telegram gateway: 429 rate limited, waiting ${retryAfter}s\n`)
           observer?.onRetry?.({ attempt, reason: 'flood_wait', delayMs })
           await sleep(delayMs)
@@ -227,7 +437,7 @@ export function createRetryApiCall(
         throw err
       }
     }
-    const giveUpErr = new Error('retryApiCall: max retries exceeded')
+    const giveUpErr = new Error(GIVE_UP_MESSAGE)
     observer?.onGiveUp?.({ attempts: maxRetries, error: giveUpErr })
     throw giveUpErr
   }

package/telegram-plugin/scoped-approval.ts

@@ -307,9 +307,18 @@ export function isDestructiveBashCommand(command: string): boolean {
   if (/\b(chmod|chown|chgrp)\b[^|;&]*(\s-(-recursive|[a-z]*r[a-z]*)\b)/.test(c)) return true;
   // redirection clobbering devices or system dirs
   if (/>\s*\/(dev|etc|boot|sys|proc)\b/.test(c)) return true;
-  // destructive git
+  // destructive git — discards or rewrites history / working-tree state.
+  //   checkout: `-f`/`--force` (force-overwrite), `git checkout .` / `./`
+  //     / `./<path>` (path-restore of the whole tree or a subtree) and
+  //     `checkout … -- <path>` all discard uncommitted work. A plain
+  //     `git checkout <branch>` (branch switch, reversible) is deliberately
+  //     NOT flagged. NOTE: a bare single-path discard without `--`
+  //     (`git checkout src/x.ts`) is syntactically ambiguous with a branch
+  //     name and is a known uncaught form — not full coverage.
+  //   stash: `drop`/`clear`/`pop` remove stash state irreversibly
+  //     (`stash`/`list`/`show`/`apply` keep it and stay unflagged).
   if (/\bgit\b/.test(c) &&
-      /(push\b[^|;&]*(--force|-f\b|--force-with-lease)|push\s+[^\s]*\s+\+|reset\s+--hard|clean\s+-[a-z]*[fd]|filter-branch|reflog\s+expire|update-ref\s+-d|branch\s+-d{1,2}\b|checkout\s+--\s|restore\b)/.test(c)) return true;
+      /(push\b[^|;&]*(--force|-f\b|--force-with-lease)|push\s+[^\s]*\s+\+|reset\s+--hard|clean\s+-[a-z]*[fd]|filter-branch|reflog\s+expire|update-ref\s+-d|branch\s+-d{1,2}\b|checkout\b[^|;&]*(\s-f\b|\s--force\b|\s--(\s|$)|\s\.(\s|$|\/))|stash\s+(drop|clear|pop)\b|restore\b)/.test(c)) return true;
   // power / process control
   if (/(^|\s|;|&&|\|\||\()(shutdown|reboot|halt|poweroff|kill|killall|pkill)\b/.test(c)) return true;
   if (/(^|\s)init\s+0\b/.test(c)) return true;

package/telegram-plugin/secret-detect/chunker.ts

@@ -1,13 +1,21 @@
 /**
  * Sliding-window chunker for ReDoS-bounded detection.
  *
- * Inputs larger than 32 KB are split into 16 KB windows with 1 KB overlap.
+ * Inputs larger than 32 KB are split into 16 KB windows with 8 KB overlap.
  * Each window is scanned independently; the caller is responsible for
  * dedupe-by-byte-offset when merging per-window hits back together.
  *
  * The overlap exists so a secret that straddles a window boundary is still
- * matched by at least one scan (provided the secret is ≤ 1 KB, which covers
- * every known token format plus typical PEM private keys).
+ * fully contained in at least one scan. The guarantee is exact: a secret is
+ * only missed if its length EXCEEDS the overlap (if length ≤ OVERLAP, a
+ * boundary-straddling secret is wholly inside the next window, which starts
+ * OVERLAP bytes before the boundary). The old 1 KB overlap was smaller than
+ * a real PEM private key — a 4096-bit RSA key in PEM armor is ~3.2 KB, so a
+ * boundary-straddling RSA key in a >32 KB payload slipped through unmasked
+ * (2026-07 secret-scrub review, tp-support F2). At 8 KB the overlap clears
+ * a 4096-bit RSA PEM (~3.2 KB) with >2x margin and also covers larger EC /
+ * certificate blobs. Cost: windows advance by WINDOW_SIZE−OVERLAP = 8 KB,
+ * so a big payload is scanned in ~2x as many windows — bounded and cheap.
  */
 
 export interface Window {
@@ -19,7 +27,13 @@ export interface Window {
 
 export const CHUNK_THRESHOLD = 32 * 1024
 export const WINDOW_SIZE = 16 * 1024
-export const OVERLAP = 1024
+/**
+ * 8 KB. MUST be ≥ the largest secret we need to catch across a window
+ * boundary; a 4096-bit RSA private key in PEM armor is ~3.2 KB, so this
+ * clears it with >2x headroom. See the module header for the exact
+ * "missed only if secret length > OVERLAP" guarantee.
+ */
+export const OVERLAP = 8 * 1024
 
 export function chunk(text: string): Window[] {
   if (text.length <= CHUNK_THRESHOLD) {

package/telegram-plugin/secret-detect/index.ts

@@ -11,17 +11,23 @@
  *      PEM blocks, CLI flags)
  *   3. KEY=VALUE heuristic with Shannon-entropy gate (≥ 4.0)
  *
- * Big inputs (>32 KB) are chunked into 16 KB windows with 1 KB overlap
- * (chunker.ts) for ReDoS bounding; we dedupe by byte-offset after.
+ * Big inputs (>32 KB) are chunked into 16 KB windows with 8 KB overlap
+ * (chunker.ts) for ReDoS bounding; we dedupe by byte-offset after. The
+ * overlap must exceed the largest single secret (an 8192-bit RSA PEM is
+ * ~6.5 KB) so a boundary-straddling key is never split across windows.
  *
  * Nearby test/mock/example/fixture/dummy markers (within 40 chars) demote
  * a hit to `suppressed: true`. The caller decides what that means (our
  * convention: suppressed high-confidence → ambiguous, user is asked).
  *
- * Secretlint is integrated as an async supplementary source via
- * `detectSecretsAsync`. The sync `detectSecrets` keeps the fast vendored-
- * pattern path for callers on the hot path (Telegram message ingest).
- * Gitleaks TOML is loaded via `gitleaks-loader.ts`.
+ * Detection is vendored-patterns-only and synchronous: every live caller
+ * (inbound gate, outbound scrub, `redact.ts`, `pipeline.ts`) runs
+ * `detectSecrets`. There is deliberately NO Secretlint/async "safety net"
+ * layered underneath — an earlier `detectSecretsAsync` + Secretlint wrapper
+ * was never wired into any live path (test-only), so it was a false safety
+ * net and has been removed (2026-07 secret-scrub review, tp-support F1).
+ * Arming a new async scanner belongs in its own validated change, not the
+ * scrub-coverage PR. Gitleaks TOML is loaded via `gitleaks-loader.ts`.
  */
 import { ALL_PATTERNS } from './patterns.js'
 import { scanKeyValue, type RawHit } from './kv-scanner.js'
@@ -209,53 +215,3 @@ function dropOverlaps(hits: RawHit[]): RawHit[] {
 export { maskToken } from './mask.js'
 export { redactUrls } from './url-redact.js'
 export { deriveSlug } from './slug.js'
-export { detectViaSecretlint } from './secretlint-source.js'
-
-/**
- * Async detection pipeline — runs `detectSecrets` (fast vendored engine)
- * and Secretlint in parallel, then merges the results by deduping on
- * `[start, end)` byte ranges. If Secretlint and a vendored pattern both
- * match the same span, the first one wins (vendored, since it's listed
- * first in the merge array below).
- *
- * Slug collisions are re-resolved on the merged list so the overall
- * output has unique `suggested_slug` values.
- */
-export async function detectSecretsAsync(text: string): Promise<Detection[]> {
-  if (!text || text.length === 0) return []
-  const [vendored, viaSecretlint] = await Promise.all([
-    Promise.resolve(detectSecrets(text)),
-    // Lazy-import keeps the sync `detectSecrets` path free of Secretlint
-    // initialization cost; paid once on first async call.
-    import('./secretlint-source.js').then((m) => m.detectViaSecretlint(text)),
-  ])
-
-  // Merge with range-based dedupe. On an exact-range tie, prefer the
-  // higher-confidence detection (else vendored-first). This matters since
-  // the vendored generic high-entropy fallback emits `ambiguous` — without
-  // the confidence tie-break it would shadow a Secretlint `high` provider
-  // hit on the same span and silently downgrade it (mirrors the sync
-  // dedupeRaw's high-over-ambiguous rule).
-  const seen = new Map<string, Detection>()
-  const consider = (d: Detection): void => {
-    const key = `${d.start}:${d.end}`
-    const existing = seen.get(key)
-    if (!existing || (existing.confidence === 'ambiguous' && d.confidence === 'high')) {
-      seen.set(key, d)
-    }
-  }
-  for (const d of vendored) consider(d)
-  for (const d of viaSecretlint) consider(d)
-
-  // Re-derive slugs against the merged set (Secretlint and vendored each
-  // had independent `existing` sets; we coalesce here).
-  const existing = new Set<string>()
-  const out: Detection[] = Array.from(seen.values())
-    .sort((a, b) => a.start - b.start)
-    .map((d) => {
-      const slug = deriveSlug({ key_name: d.key_name, rule_id: d.rule_id }, existing)
-      existing.add(slug)
-      return { ...d, suggested_slug: slug }
-    })
-  return out
-}