switchroom 0.18.7 → 0.18.8

package/telegram-plugin/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
             "timeout": 10
           }
         ]
@@ -14,7 +14,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -24,7 +24,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
             "timeout": 10
           }
         ]
@@ -33,7 +33,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -43,7 +43,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -55,7 +55,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
             "timeout": 10
           }
         ]
@@ -65,7 +65,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
             "timeout": 3
           }
         ]
@@ -76,7 +76,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -86,7 +86,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
             "timeout": 5
           }
         ]
@@ -95,7 +95,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
             "timeout": 5,
             "async": true
           }

package/telegram-plugin/hooks/run-hook.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# run-hook.sh — resilient launcher for Claude Code Node hooks (issue #2555).
+#
+# Under cgroup memory-ceiling pressure (the cgroup pinned at memory.max with
+# reclaim lagging, page cache ~= cap), a freshly-spawned Node process can abort
+# at STARTUP with exit 134 (SIGABRT) inside the libuv threadpool constructor —
+# `Assertion failed: (0) == (uv_thread_create(...))` — BEFORE any hook code
+# runs. It is a transient allocation failure, not a real hook error, but it
+# surfaces a 🔴 issues card and skips the hook's work on that one tool call.
+#
+# This wrapper makes the invocation tolerant:
+#   1. Shrink the libuv threadpool to 1 so Node needs the fewest possible
+#      thread-stack mmaps at startup (minimises the failure window).
+#   2. Capture the hook payload from stdin ONCE and replay it on each attempt.
+#      The abort can land AFTER Node started draining the pipe, so a naive
+#      retry would feed the second attempt EMPTY stdin — a secret scanner would
+#      then scan nothing. Replaying the captured payload keeps the retry
+#      faithful.
+#   3. Retry ONCE on a 134 abort after a brief backoff.
+#   4. If it STILL aborts:
+#        - for SECURITY-CRITICAL hooks (secret-guard / secret-scrub) FAIL
+#          CLOSED — propagate 134 so the runtime cards it. 134 is a generic
+#          SIGABRT (assertion / OOM / any abort), not memory-pressure-specific,
+#          so silently returning 0 for a genuinely broken scanner would be a
+#          silent security BYPASS. Those hooks must never fail open.
+#        - for all other hooks, SKIP CLEANLY (exit 0) with a single stderr
+#          warn. A skipped label/context hook on one call is the documented,
+#          accepted degradation; a crash-card storm under memory pressure is
+#          not.
+#
+# Any non-134 exit status is passed through unchanged — real hook decisions
+# (block/allow/non-zero) are never masked. `sleep 0.15` uses a fractional
+# second (supported by GNU/BusyBox sleep, both present in the agent image).
+#
+# Usage (from hooks.json):
+#   sh "${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh" node "${CLAUDE_PLUGIN_ROOT}/hooks/<name>.mjs"
+
+export UV_THREADPOOL_SIZE="${UV_THREADPOOL_SIZE:-1}"
+
+# Identify the hook script (the .mjs argument) to decide fail-open vs closed.
+hook_path=""
+for a in "$@"; do
+  case "$a" in
+    *.mjs) hook_path="$a" ;;
+  esac
+done
+hook_name=$(basename "$hook_path" 2>/dev/null)
+
+# Security-critical hooks MUST fail closed on a persistent abort.
+fail_closed=0
+case "$hook_name" in
+  secret-guard-pretool.mjs | secret-scrub-stop.mjs) fail_closed=1 ;;
+esac
+
+# Capture stdin once so both attempts see the SAME payload. Claude Code feeds
+# the hook a single JSON object on stdin and closes it, so `cat` returns at
+# EOF. (Command substitution strips trailing newlines, which JSON parsing does
+# not care about.)
+payload=$(cat)
+
+run_hook() {
+  printf '%s' "$payload" | "$@"
+}
+
+run_hook "$@"
+status=$?
+if [ "$status" -ne 134 ]; then
+  exit "$status"
+fi
+
+# Transient thread-create abort — brief backoff, then retry once with the
+# faithfully-replayed payload.
+sleep 0.15
+run_hook "$@"
+status=$?
+if [ "$status" -eq 134 ]; then
+  if [ "$fail_closed" -eq 1 ]; then
+    echo "run-hook: security hook '$hook_name' aborted twice with exit 134 — FAILING CLOSED (not skipping) (#2555)" >&2
+    exit 134
+  fi
+  echo "run-hook: '$hook_name' aborted twice with exit 134 (uv_thread_create under memory pressure) — skipping hook cleanly (#2555)" >&2
+  exit 0
+fi
+exit "$status"

package/telegram-plugin/model-unavailable.ts

@@ -69,6 +69,32 @@ export function detectModelUnavailable(
   const sample = stderr.length > 16_384 ? stderr.slice(0, 16_384) : stderr
   const lower = sample.toLowerCase()
 
+  // ── 0. Transient / server-side 429 (NOT account quota) — issue #2922 ────
+  // Anthropic emits a `rate_limit_error` whose message explicitly negates the
+  // account-quota reading: "Server is temporarily limiting requests (not your
+  // usage limit)". A negation-blind substring match on "usage limit" (step 1
+  // below) would misclassify this as `quota_exhausted`, firing a phantom fleet
+  // failover that self-cancels and leaves the turn dead. These are upstream
+  // throttles Claude Code retries internally with backoff — classify them as
+  // `overload` (the calm rate-limit path) BEFORE the quota substrings run, so
+  // the negation is honoured and no failover is announced.
+  const transientUpstreamSignals = [
+    'not your usage limit',
+    'not your account',
+    "not your account's",
+    'temporarily limiting requests',
+    'temporarily rate',
+    'server is temporarily',
+    'would exceed your account’s rate limit',
+    "would exceed your account's rate limit",
+  ]
+  if (transientUpstreamSignals.some(s => lower.includes(s))) {
+    const resetAt = parseResetTime(sample)
+    return resetAt !== undefined
+      ? { kind: 'overload', resetAt, raw: stderr }
+      : { kind: 'overload', raw: stderr }
+  }
+
   // ── 1. Quota / billing exhaustion ──────────────────────────────────────
   const quotaSignals = [
     'out of extra usage',

package/telegram-plugin/pty-partial-handler.ts

@@ -32,6 +32,7 @@ export type PtyPartialAction =
   | 'dedup-skip' // same text as the previous partial; no-op
   | 'update-existing' // pushed into an already-live stream
   | 'update-new' // created a new stream and pushed into it
+  | 'error-suppressed' // raw API-error TUI line; dropped (issue #2922 Bug 3)
 
 export interface PtyHandlerState {
   /**
@@ -84,6 +85,32 @@ export interface PtyHandlerDeps {
   writeError?: (line: string) => void
 }
 
+/**
+ * Detect a raw API-error line scraped from Claude Code's TUI — issue #2922
+ * Bug 3. When the model 429s / errors, the CLI renders an `API Error: … ·
+ * b'{"type":"error",…}'` line into the terminal; the PTY tail would otherwise
+ * scrape it as the assistant reply and relay the raw bytes verbatim to chat.
+ * These lines are suppressed here so the model-unavailable operator-event
+ * pipeline owns the user-facing rendering (a clean ⚠️ card), not the raw tail.
+ *
+ * Kept deliberately tight (anchored error markers, not any mention of "error")
+ * so genuine assistant text that happens to discuss errors is NOT swallowed.
+ */
+export function looksLikeRawApiError(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const lower = text.toLowerCase()
+  return (
+    lower.includes('api error:')
+    || lower.includes('"type":"error"')
+    || lower.includes("'type': 'error'")
+    || lower.includes('rate_limit_error')
+    || lower.includes('overloaded_error')
+    || lower.includes('"is_error":true')
+    // The CLI's Python-style raw-body render: · b'{...}'
+    || / b'\{/.test(text)
+  )
+}
+
 function streamKey(chatId: string, threadId?: number): string {
   // Canonical chat-key derivation lives in gateway/chat-key.ts — keep this
   // expression in lockstep (treats 0/null/undefined the same). See #1564.
@@ -96,6 +123,13 @@ function streamKey(chatId: string, threadId?: number): string {
  *
  * Returns the action taken. All state mutation happens through the
  * supplied `state` object so callers can inspect before/after.
+ *
+ * NOTE on `looksLikeRawApiError` suppression (#2922 Bug 3): this is
+ * *preview-only* scope. PTY partials are the live-streaming terminal tail,
+ * never the authoritative reply (that flows through the operator-event /
+ * reply pipelines). So the worst case of an over-eager match here is a
+ * missing streaming flicker for one snapshot — NOT a dropped user answer.
+ * That asymmetry is why the matcher can stay aggressive on raw error shapes.
  */
 export function handlePtyPartialPure(
   text: string,
@@ -132,6 +166,11 @@ export function handlePtyPartialPure(
 
   if (suppressed) return 'suppressed'
 
+  // Drop raw API-error TUI lines so they never leak to chat as the reply —
+  // the model-unavailable card (operator-event pipeline) renders these
+  // instead. See issue #2922 Bug 3.
+  if (looksLikeRawApiError(text)) return 'error-suppressed'
+
   if (state.lastPtyPreviewByChat.get(sKey) === text) return 'dedup-skip'
 
   const isFirst = !state.lastPtyPreviewByChat.has(sKey)

package/telegram-plugin/render/rich-render.ts

@@ -25,7 +25,18 @@
 
 import { parse } from "./parse.js";
 import { renderSafe, type RenderResult } from "./render.js";
-import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
+
+/**
+ * The legacy plain-text `sendMessage` / `editMessageText` wire cap (4096
+ * UTF-16 units). It does NOT apply to the rich path (`sendRichMessage`, up
+ * to `RICH_MESSAGE_MAX_CHARS`), but it DOES apply the moment `renderSafe`
+ * degrades a body to `mode: "plain"` — the send path then routes it through
+ * the plain `sendMessage` endpoint (see stream-controller `doSend`/`doEdit`).
+ * A degraded plain body larger than this is rejected by Telegram with
+ * `message is too long`, so `renderOutboundChunks` caps plain pieces here.
+ */
+export const PLAIN_TEXT_MAX_CHARS = 4096;
 
 /** Parse the `SWITCHROOM_RICH_RENDER` flag value. Default OFF; accepts the
  *  same truthy tokens as the other switchroom env flags. Pure so the default
@@ -70,3 +81,70 @@ export function maybeRenderOutbound(
   if (!richRenderEnabled(env)) return { text, mode: "markdown", degradations: [] };
   return renderOutbound(text, maxLen);
 }
+
+/**
+ * Flag-gated, CAP-ENFORCING transform for the live send path.
+ *
+ * `maybeRenderOutbound` returns ONE `RenderResult` and can only ever fit a
+ * body into a single wire message. But `renderSafe`'s markdown re-escaping
+ * (GFM-special chars gain a leading `\`) GROWS a chunk: a raw body sized just
+ * under `maxLen` can escape PAST it. `renderSafe` handles that by degrading
+ * the WHOLE document to `mode: "plain"` (raw source, no rich wrapper) — it
+ * never re-splits a multi-block body. The send path then ships that plain
+ * body through the 4096-capped `sendMessage` endpoint, so a ~32k plain body
+ * is rejected by Telegram (`message is too long`) and the answer is dropped.
+ *
+ * This function closes that gap: it returns an ARRAY of pieces, EACH of which
+ * is guaranteed to fit its own wire cap —
+ *   - a `markdown` piece is `<= maxLen` (`renderSafe`'s own guarantee), and
+ *   - a `plain` piece is `<= PLAIN_TEXT_MAX_CHARS` (the plain endpoint's cap).
+ * Pieces are cut only at `splitMarkdownChunks`' safe boundaries, so a fenced
+ * code block or a table row is NEVER bisected. Re-splitting the RAW source and
+ * re-rendering each piece also RECOVERS rich formatting the whole-document
+ * plain degradation would have thrown away: the smaller pieces individually
+ * escape under `maxLen` and come back as `markdown`.
+ *
+ *   - flag OFF (default): `[{ text, mode: "markdown", degradations: [] }]` —
+ *     a single passthrough piece, identical to `maybeRenderOutbound`.
+ *   - flag ON, body fits: `[renderSafe(...)]` — a single piece, identical to
+ *     `maybeRenderOutbound` (byte-for-byte for the common case).
+ *   - flag ON, body oversize: 2+ cap-respecting pieces in send order.
+ */
+export function renderOutboundChunks(
+  text: string,
+  env: NodeJS.ProcessEnv = process.env,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+  plainMax: number = PLAIN_TEXT_MAX_CHARS,
+): RenderResult[] {
+  if (!richRenderEnabled(env)) {
+    return [{ text, mode: "markdown", degradations: [] }];
+  }
+
+  const whole = renderOutbound(text, maxLen);
+  // `markdown` mode from renderSafe is already `<= maxLen`; a `plain` result
+  // that fits the plain cap is a single deliverable piece too. Common case.
+  if (whole.mode === "markdown" && whole.text.length <= maxLen) return [whole];
+  if (whole.mode === "plain" && whole.text.length <= plainMax) return [whole];
+
+  // Oversize: re-split the RAW source at safe boundaries and re-render each
+  // piece. Each sub-piece is `<= maxLen` in raw form, so it usually escapes
+  // back under `maxLen` and renders as rich markdown; a piece whose escaped
+  // form STILL overflows (or an indivisible plain blob) is emitted as plain,
+  // further split to `plainMax` so it fits the plain endpoint.
+  const out: RenderResult[] = [];
+  for (const rawPiece of splitMarkdownChunks(text, maxLen)) {
+    const rendered = renderOutbound(rawPiece, maxLen);
+    if (rendered.mode === "markdown" && rendered.text.length <= maxLen) {
+      out.push(rendered);
+      continue;
+    }
+    // Plain piece — cap at the plain-endpoint limit. `renderSafe` returned the
+    // raw source for a plain result, so split that source (safe boundaries,
+    // never bisecting a fence/table) into `<= plainMax` slices.
+    for (const plainPiece of splitMarkdownChunks(rendered.text, plainMax)) {
+      out.push({ text: plainPiece, mode: "plain", degradations: rendered.degradations });
+    }
+  }
+  // Defensive: a degenerate input that split to nothing still yields one piece.
+  return out.length > 0 ? out : [whole];
+}

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

@@ -63,8 +63,48 @@ export interface RetryApiCallConfig {
   observer?: RetryObserver
   /** Optional log sink for flood-wait / network lines. */
   log?: (line: string) => void
+  /**
+   * Fires whenever a Telegram 429 flood-wait is observed, BEFORE the sleep.
+   * The circuit-breaker (#2923) persists the flood-wait window here so that
+   * a container restart during an active ban can suppress non-essential
+   * sends (boot cards) instead of feeding the same per-bot-token flood
+   * counter and prolonging the ban. Best-effort; a throw here is swallowed.
+   */
+  onFloodWait?: (retryAfterSec: number) => void
+}
+
+/**
+ * True when the thrown error is a LOCAL resource-exhaustion failure —
+ * ENOSPC (disk/tmpfs full), EDQUOT (quota), EIO, or ENOMEM — rather than a
+ * remote Telegram API failure. Issue #2923: an agent's tmpfs filling up
+ * wedges the outbound send's local staging step; retrying that as if it
+ * were a transient REMOTE failure hammers the Bot API and trips a per-bot
+ * flood ban. A local disk error must NOT drive remote retries — surface it
+ * as a distinct, non-retryable degraded state instead.
+ */
+export function isLocalResourceError(err: unknown): boolean {
+  const code = (err as { code?: unknown })?.code
+  if (typeof code === 'string' && ['ENOSPC', 'EDQUOT', 'EIO', 'ENOMEM'].includes(code)) {
+    return true
+  }
+  const msg = err instanceof Error ? err.message : String(err ?? '')
+  return (
+    // Word-boundaried so a substring can't false-match; covers the same set
+    // as the errno code list above (ENOSPC/EDQUOT/EIO/ENOMEM).
+    /\b(ENOSPC|EDQUOT|EIO|ENOMEM)\b/.test(msg) ||
+    /no space left on device/i.test(msg) ||
+    /disk quota exceeded/i.test(msg)
+  )
 }
 
+/**
+ * Marker error thrown when `retryApiCall` refuses to retry a LOCAL
+ * resource-exhaustion failure (#2923). Callers can detect this to surface a
+ * "degraded: local disk full" state rather than treating it like a remote
+ * send failure worth retrying.
+ */
+export const LOCAL_RESOURCE_EXHAUSTED = 'LOCAL_RESOURCE_EXHAUSTED'
+
 const DEFAULT_SLEEP = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
 
 /**
@@ -83,6 +123,7 @@ export function createRetryApiCall(
   const sleep = config.sleep ?? DEFAULT_SLEEP
   const observer = config.observer
   const log = config.log
+  const onFloodWait = config.onFloodWait
 
   return async function retryApiCall<T>(
     fn: () => Promise<T>,
@@ -96,12 +137,33 @@ export function createRetryApiCall(
         const msg = err instanceof Error ? err.message : String(err)
         const desc = isGrammyErr ? (err as GrammyError).description : msg
 
+        // LOCAL resource exhaustion (#2923) — ENOSPC/EDQUOT/EIO/ENOMEM. This
+        // is a LOCAL disk/memory failure, not a remote API failure: retrying
+        // it in a tight loop is exactly what tripped the per-bot flood ban.
+        // Do NOT retry. Throw a distinct, non-retryable marker so the caller
+        // surfaces a degraded "local disk full" state and backs off hard.
+        if (isLocalResourceError(err)) {
+          log?.(
+            `telegram gateway: LOCAL resource exhaustion (${(err as { code?: string }).code ?? 'disk/mem'}) — ` +
+              `not retrying the send (would feed a flood ban); surfacing degraded state\n`,
+          )
+          observer?.onGiveUp?.({ attempts: attempt + 1, error: err })
+          throw Object.assign(new Error(LOCAL_RESOURCE_EXHAUSTED), { original: err })
+        }
+
         // Flood-wait — sleep retry_after and try again.
         if (isGrammyErr && (err as GrammyError).error_code === 429) {
           const retryAfter = Number(
             (err as GrammyError).parameters?.retry_after ?? 5,
           )
           const delayMs = retryAfter * 1000
+          // Persist the flood window so a restart during the ban can suppress
+          // non-essential sends instead of extending it (#2923 circuit breaker).
+          try {
+            onFloodWait?.(retryAfter)
+          } catch {
+            /* best-effort — never let the breaker hook break the retry path */
+          }
           log?.(`telegram gateway: 429 rate limited, waiting ${retryAfter}s\n`)
           observer?.onRetry?.({ attempt, reason: 'flood_wait', delayMs })
           await sleep(delayMs)

package/telegram-plugin/shared/bot-runtime.ts

@@ -29,6 +29,7 @@ import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { createRetryApiCall } from '../retry-api-call.js'
+import { makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
@@ -149,9 +150,15 @@ export function installTgPostLogger(bot: Bot): void {
  * Usage:
  *   const robustApiCall = createRobustApiCall()
  */
-export function createRobustApiCall() {
+export function createRobustApiCall(opts: { floodStatePath?: string } = {}) {
   return createRetryApiCall({
     log: (line) => process.stderr.write(line),
+    // #2923: persist every observed 429 flood-wait window so a restart during
+    // the ban can suppress non-essential sends (boot cards) instead of feeding
+    // the per-bot flood counter and prolonging the ban.
+    ...(opts.floodStatePath
+      ? { onFloodWait: makeFloodWaitRecorder(opts.floodStatePath) }
+      : {}),
   })
 }
 

package/telegram-plugin/silence-poke.ts

@@ -423,6 +423,20 @@ export function formatFrameworkFallbackText(
   return null
 }
 
+/**
+ * #2995 — the LONGEST-running in-flight tool for a turn key, or null when
+ * none is tracked. Read-only accessor over `inFlightTools` for the
+ * mid-flight busy-ack: the gateway needs the blocking step's name/label
+ * and its age to decide whether (and how) to ack a buffered mid-turn
+ * inbound. Does not touch the silence clock.
+ */
+export function longestInFlightTool(key: string, now: number): ToolSnapshot | null {
+  const s = state.get(key)
+  if (s == null) return null
+  const snaps = snapshotInFlight(s, now)
+  return snaps.length > 0 ? snaps[0]! : null
+}
+
 /** Snapshot in-flight tools sorted longest-running first — for the honest
  *  floor/fallback message body. */
 function snapshotInFlight(s: SilencePokeState, now: number): ToolSnapshot[] {