switchroom 0.18.7 → 0.18.9

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

@@ -0,0 +1,198 @@
+/**
+ * Durable session-model stickiness — file helpers shared by the gateway.
+ *
+ * Two files in the bind-mounted agent state dir carry the contract
+ * (reference/rfcs/session-model-stickiness.md):
+ *
+ *   - `.session-model` — the DURABLE session override written on every
+ *     positively-confirmed `/model` switch. One-line JSON
+ *     `{"model","configuredDefaultAtWrite","ts"}`. It is NOT consumed by a
+ *     keep-path boot; start.sh deletes it on revert / invalidation /
+ *     corruption / 7-day staleness, and the gateway deletes it on
+ *     `/model default`.
+ *
+ *   - `.relaunch-model-intent` — the ONE-SHOT intent bit for the next boot.
+ *     One-line JSON `{"intent":"keep"|"revert","reason","ts"}`, atomic
+ *     write, last-writer-wins. Boot default is REVERT (operator decision:
+ *     a raw `docker restart` / host reboot / crash must revert to the yaml
+ *     model), so every switchroom-managed KEEP path must stamp keep-intent
+ *     BEFORE the bounce. start.sh consumes it (rm -f) every boot; a stale
+ *     (>10 min by the embedded ts) or corrupt intent counts as no intent.
+ *
+ * The `model` token is always a canonical `claude --model` token (alias,
+ * `claude-*` id, or `sr-*` id) — NEVER a display label like "Opus 4.8".
+ * Shape-gated on write with the same regex start.sh greps with.
+ */
+
+import { readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+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'
+
+export type RelaunchModelIntent = 'keep' | 'revert'
+
+export interface SessionModelRecord {
+  model: string
+  configuredDefaultAtWrite: string
+  ts: number
+}
+
+/**
+ * Restart reasons whose semantics are "revert the session model to the
+ * configured default". Everything else `triggerSelfRestart` fires with is a
+ * switchroom-managed relaunch (watchdog recovery, drain-cap bounce,
+ * turn-complete deferred restart, fleet-fallback resume, sr-to-claude model
+ * switch, grant restarts) and KEEPS the override — the whole point of the
+ * stickiness contract. Enumerated in the RFC §3; default-keep here is safe
+ * because only gateway code calls triggerSelfRestart, and a bounce nobody
+ * stamped (crash, raw docker restart, deploy) reverts by boot default anyway.
+ */
+const REVERT_RESTART_REASONS: ReadonlySet<string> = new Set(['inline-button-restart'])
+
+/** Classify a triggerSelfRestart reason into the intent the boot should honor. */
+export function intentForRestartReason(reason: string): RelaunchModelIntent {
+  return REVERT_RESTART_REASONS.has(reason) ? 'revert' : 'keep'
+}
+
+function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmp, content, 'utf8')
+  renameSync(tmp, path)
+}
+
+/** Serialize a `.session-model` record (one line + trailing newline). */
+export function serializeSessionModel(rec: SessionModelRecord): string {
+  return `${JSON.stringify({
+    model: rec.model,
+    configuredDefaultAtWrite: rec.configuredDefaultAtWrite,
+    ts: rec.ts,
+  })}\n`
+}
+
+/**
+ * Parse `.session-model` content. Returns null on corrupt JSON, a missing /
+ * non-string field, or a model token that fails the MODEL_ARG_RE shape gate
+ * (never trust an unvalidated string near `claude --model`).
+ */
+export function parseSessionModel(text: string): SessionModelRecord | null {
+  try {
+    const raw = JSON.parse(text) as Partial<SessionModelRecord>
+    if (
+      typeof raw.model !== 'string' ||
+      typeof raw.configuredDefaultAtWrite !== 'string' ||
+      typeof raw.ts !== 'number' ||
+      !isValidModelArg(raw.model)
+    ) {
+      return null
+    }
+    return { model: raw.model, configuredDefaultAtWrite: raw.configuredDefaultAtWrite, ts: raw.ts }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write the durable session override. Throws on a non-canonical token —
+ * callers must pass a `claude --model` token, never a display label
+ * (regression guard for the "Opus 4.5 persisted" class).
+ */
+export function writeSessionModelFile(
+  agentDir: string,
+  model: string,
+  configuredDefaultAtWrite: string,
+): void {
+  if (!isValidModelArg(model)) {
+    throw new Error(`refusing to persist non-canonical session model token: ${JSON.stringify(model)}`)
+  }
+  atomicWrite(
+    join(agentDir, SESSION_MODEL_FILE),
+    serializeSessionModel({ model, configuredDefaultAtWrite, ts: Date.now() }),
+  )
+}
+
+/** Raw file text (for rollback snapshots), or null when absent/unreadable. */
+export function readSessionModelFileRaw(agentDir: string): string | null {
+  try {
+    return readFileSync(join(agentDir, SESSION_MODEL_FILE), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** Parsed durable override, or null when absent/corrupt. */
+export function readSessionModelFile(agentDir: string): SessionModelRecord | null {
+  const raw = readSessionModelFileRaw(agentDir)
+  return raw == null ? null : parseSessionModel(raw)
+}
+
+/** Delete the durable override (`/model default`, rollback). Best-effort. */
+export function clearSessionModelFile(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Restore a rollback snapshot taken with readSessionModelFileRaw. */
+export function restoreSessionModelFileRaw(agentDir: string, raw: string | null): void {
+  if (raw == null) {
+    clearSessionModelFile(agentDir)
+    return
+  }
+  try {
+    atomicWrite(join(agentDir, SESSION_MODEL_FILE), raw)
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Stamp the one-shot relaunch intent. MUST be called synchronously BEFORE
+ * the restart signal/dispatch it describes (write-before-kill invariant —
+ * the next start.sh boot reads this to decide keep vs revert). Best-effort:
+ * a failed write means the boot falls back to the default (revert), which
+ * is the safe side.
+ */
+export function writeRelaunchModelIntent(
+  agentDir: string,
+  intent: RelaunchModelIntent,
+  reason: string,
+): void {
+  try {
+    atomicWrite(
+      join(agentDir, RELAUNCH_MODEL_INTENT_FILE),
+      `${JSON.stringify({ intent, reason, ts: Date.now() })}\n`,
+    )
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: relaunch-model-intent write failed (boot will revert): ${(err as Error)?.message ?? String(err)}\n`,
+    )
+  }
+}
+
+/** Remove a stamped intent (rollback of a failed dispatch). Best-effort. */
+export function clearRelaunchModelIntent(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * The resolved configured default start.sh recorded this boot
+ * (`.configured-default-model`, written before override resolution — the
+ * same resolver output the invalidation compare uses). Null when missing.
+ */
+export function readConfiguredDefaultModel(agentDir: string): string | null {
+  try {
+    const v = readFileSync(join(agentDir, CONFIGURED_DEFAULT_MODEL_FILE), 'utf8').trim()
+    return v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}

package/telegram-plugin/gateway/status-pin-store.ts

@@ -12,10 +12,13 @@
  * a dead session lingers.
  *
  * This makes cleanup self-contained across restart: every pin claim persists
- * here; on boot the gateway loads the persisted set and unpins each entry
- * (a status pin from a PRIOR session is stale by definition — the turn it
- * represented is over or crashed), then clears the store. It does NOT re-adopt
- * or re-pin — it only cleans up.
+ * here; on boot the gateway loads the persisted set and unpins each
+ * work-scoped entry (a status pin from a PRIOR session is stale by definition
+ * — the turn it represented is over or crashed), dropping rows only after a
+ * successful unpin (failed ones are retained with an attempt counter for a
+ * next-boot retry — see runStatusPinBootCleanup). Time-scoped `tool:` rows
+ * (the `pin_message` MCP tool, #3001) survive boots until their `expiresAt`.
+ * It does NOT re-adopt or re-pin — it only cleans up.
  *
  * Shape choice — SNAPSHOT, not append-log, mirroring obligation-store.ts. The
  * claim set is tiny and bounded (one entry per in-flight pinned key, normally
@@ -55,8 +58,27 @@ export interface PersistedStatusPin {
   messageId: number
   /** True while the pin API call is in-flight / unconfirmed (see above). */
   pending?: boolean
+  /** Wall-clock ms after which this pin is stale and boot cleanup unpins it.
+   *  Rows WITHOUT this field are work-scoped (fg:/wk:/banner:) — stale the
+   *  moment their owning session dies, so boot cleanup unpins them
+   *  unconditionally. Rows WITH it (the `tool:` pins written by the
+   *  `pin_message` MCP tool, #3001) represent deliberate agent pins that have
+   *  no "work finished" event: they SURVIVE restarts and are only swept once
+   *  expired. */
+  expiresAt?: number
+  /** Boot-cleanup unpin retry counter (#3001). Incremented each boot the
+   *  unpin fails (flood-wait exhausted / transient 5xx); the row is retained
+   *  for retry until BOOT_UNPIN_MAX_ATTEMPTS, then forfeited. Absent = 0. */
+  attempts?: number
 }
 
+/** How many boots may retry a failing boot-cleanup unpin before the row is
+ *  forfeited. Unpins are idempotent (unpinning an already-unpinned or deleted
+ *  message no-ops), so retrying across boots is safe; the cap only bounds a
+ *  permanently-undeliverable unpin (chat gone, bot removed) so it cannot
+ *  re-fail on every boot forever. */
+export const BOOT_UNPIN_MAX_ATTEMPTS = 5
+
 /** Envelope version. v1 had no `pending` field; a v1 row loads as a confirmed
  *  pin (pending undefined). v2 adds the optional `pending` flag. Both load
  *  fail-open — an unknown/newer version yields []. */
@@ -74,7 +96,9 @@ function isPinRow(x: unknown): x is PersistedStatusPin {
     typeof o.chatId === 'string' &&
     o.chatId.length > 0 &&
     typeof o.messageId === 'number' &&
-    (o.pending === undefined || typeof o.pending === 'boolean')
+    (o.pending === undefined || typeof o.pending === 'boolean') &&
+    (o.expiresAt === undefined || typeof o.expiresAt === 'number') &&
+    (o.attempts === undefined || typeof o.attempts === 'number')
   )
 }
 
@@ -170,16 +194,27 @@ export function pinnedMessageIsOurs(
  * the ordering + best-effort contract is unit-testable against the REAL code
  * (the gateway's thin wrapper just binds the live fs / unpin api / logger).
  *
- * Any pin persisted by a PRIOR session is stale by definition — its turn ended
- * or the session crashed before its unpin reconcile ran. This includes records
- * left `pending` (the persist-intent-first write from `reconcileAndPersist-
- * StatusPin`): a crash between the pin API call and its confirming rewrite
- * leaves a pending record whose pin MAY have landed in Telegram, so we must
- * treat it exactly like a confirmed one and unpin it. We therefore best-effort
- * unpin EVERY persisted entry (confirmed and pending alike — a failure is
- * non-fatal) and then EMPTY the store regardless, so a permanently-
- * undeliverable unpin can't re-run on every boot. We do NOT re-adopt or re-pin.
- * Returns the counts for logging/testing.
+ * The restart rule (#3001): a WORK-SCOPED pin persisted by a PRIOR session
+ * (fg:/wk:/banner: — any row without `expiresAt`) is stale by definition — its
+ * work ended or the session crashed before its unpin reconcile ran, so
+ * restart = reset: it is unpinned here. This includes records left `pending`
+ * (the persist-intent-first write from `reconcileAndPersistStatusPin`): a
+ * crash between the pin API call and its confirming rewrite leaves a pending
+ * record whose pin MAY have landed in Telegram, so we must treat it exactly
+ * like a confirmed one and unpin it.
+ *
+ * TIME-SCOPED rows (`tool:` pins from the `pin_message` MCP tool, carrying
+ * `expiresAt`) have no "work finished" event, so a restart does NOT reset
+ * them: an unexpired row is RETAINED untouched across boots and only unpinned
+ * once `now >= expiresAt`.
+ *
+ * RETRY-SAFETY (#3001): a row is dropped only AFTER its unpin resolves. A
+ * failing unpin (flood-wait exhausted / transient 5xx) retains the row with an
+ * incremented `attempts` counter so the NEXT boot retries, up to
+ * BOOT_UNPIN_MAX_ATTEMPTS — then the row is forfeited (a permanently-
+ * undeliverable unpin must not re-fail on every boot forever). Unpins are
+ * idempotent, so the retry can never double-unpin harmfully. We do NOT
+ * re-adopt or re-pin. Returns the counts for logging/testing.
  *
  * CRITICAL: the caller MUST only invoke this AFTER winning the startup mutex.
  * The store is a shared per-agent file; on a double-boot a losing gateway
@@ -189,27 +224,52 @@ export async function runStatusPinBootCleanup(args: {
   path: string
   fs: StatusPinStoreFsSeam
   unpin: (chatId: string, messageId: number) => Promise<unknown>
+  now?: number
   log?: (line: string) => void
-}): Promise<{ cleared: number; total: number }> {
+}): Promise<{ cleared: number; retained: number; kept: number; total: number }> {
   const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const now = args.now ?? Date.now()
   const persisted = loadStatusPins(args.path, args.fs)
-  if (persisted.length === 0) return { cleared: 0, total: 0 }
+  if (persisted.length === 0) return { cleared: 0, retained: 0, kept: 0, total: 0 }
   let cleared = 0
+  let retained = 0
+  let kept = 0
+  const next: PersistedStatusPin[] = []
   for (const pin of persisted) {
+    // Unexpired time-scoped row (tool: pin): deliberately survives the
+    // restart — keep it as-is, no unpin.
+    if (pin.expiresAt != null && pin.expiresAt > now) {
+      next.push(pin)
+      kept++
+      continue
+    }
     try {
       await args.unpin(pin.chatId, pin.messageId)
       cleared++
     } catch (err) {
+      const attempts = (pin.attempts ?? 0) + 1
       log(
         `status-pin-store: boot cleanup unpin failed ` +
-          `(chat=${pin.chatId} msg=${pin.messageId}): ${(err as Error).message}\n`,
+          `(chat=${pin.chatId} msg=${pin.messageId} attempt=${attempts}): ` +
+          `${(err as Error).message}\n`,
       )
+      if (attempts < BOOT_UNPIN_MAX_ATTEMPTS) {
+        // Retain for a retry on the next boot instead of forfeiting the
+        // orphan permanently (retry-safe boot sweep, #3001).
+        next.push({ ...pin, attempts })
+        retained++
+      } else {
+        log(
+          `status-pin-store: boot cleanup FORFEITING pin after ` +
+            `${attempts} failed unpin attempts ` +
+            `(key=${pin.pinKey} chat=${pin.chatId} msg=${pin.messageId}) — ` +
+            `will not retry again\n`,
+        )
+      }
     }
   }
-  // Empty the store regardless — these claims belong to a dead session; leaving
-  // them would re-attempt the same (already-tried) unpins on every future boot.
-  persistStatusPins(args.path, args.fs, [], log)
-  return { cleared, total: persisted.length }
+  persistStatusPins(args.path, args.fs, next, log)
+  return { cleared, retained, kept, total: persisted.length }
 }
 
 /**

package/telegram-plugin/gateway/worker-pin-reaper.ts

@@ -0,0 +1,114 @@
+/**
+ * worker-pin-reaper.ts — pure decision for the mid-session `wk:` pin sweep
+ * (#3001).
+ *
+ * Why this exists: the background-worker pin (`wk:<agentId>`, pinned on the
+ * `🛠 Worker` feed message while the worker runs) is normally unpinned by the
+ * worker's completion handler (`reconcileWorkerPin(agentId, null, false)` on
+ * the watcher's onFinish). But that event can be MISSED — watcher crash, SDK
+ * subprocess SIGKILL, a dropped JSONL tail — and then nothing ever unpins the
+ * worker's message until the next gateway boot. Log evidence on one agent:
+ * ~1120 pinChatMessage vs ~1014 unpinChatMessage with zero logged failures —
+ * a long tail of stale pins glued to the top of the chat.
+ *
+ * This module is the pure half (mirrors `runActivityCardMidSessionReaper`'s
+ * decide-over-injected-seams shape): given the currently-claimed `wk:` pins,
+ * a terminality predicate over the sub-agent registry, and a TTL, it returns
+ * the pins that should be unpinned NOW. The gateway executes each reap via
+ * `reconcileStatusPin(key, chat, { pinned: false })` so the in-memory claim
+ * AND the durable store row clear together.
+ *
+ * A pin is reaped when EITHER:
+ *   - `terminal` — the registry says the worker reached a terminal status
+ *     (completed | failed): its work is finished, the pin must go, however
+ *     young it is. (A missed onFinish is exactly this case.)
+ *   - `ttl` — the pin has been held past `ttlMs` AND the registry cannot
+ *     vouch for the worker (no row / never linked / `stalled` / lookup
+ *     error). A registry-confirmed RUNNING row exempts the pin from the TTL
+ *     entirely: a healthy 7h worker keeps its pin for the whole run instead
+ *     of churning unpin→re-pin every TTL. The stall detector demotes a dead
+ *     worker's row out of 'running' within ~60s, so the TTL still catches
+ *     true zombies.
+ *
+ * A worker the registry can't vouch for is still never touched before the
+ * TTL — the sweep can only ever shorten a stale pin's life, not a live one's.
+ */
+
+/** Default TTL for a held worker pin: 6 hours. Rationale: worker turns are
+ *  expected to run minutes-to-a-couple-of-hours (the watcher's own stall
+ *  detection fires after ~60s of JSONL inactivity, and the longest sanctioned
+ *  background dispatches are bounded by a single Claude session's lifetime).
+ *  6h comfortably exceeds any legitimate worker turn while bounding the
+ *  stale-pin window to the same day instead of "until the next restart". */
+export const WORKER_PIN_TTL_MS_DEFAULT = 6 * 60 * 60_000
+
+export const WORKER_PIN_KEY_PREFIX = 'wk:'
+
+/** One currently-claimed worker pin, flattened from the gateway's Maps. */
+export interface WorkerPinCandidate {
+  /** Full pin key, `wk:<agentId>` shape. */
+  pinKey: string
+  /** Chat the pin lives in (from the gateway's pinKey → chatId registry). */
+  chatId: string
+  /** Wall-clock ms the claim was first taken (gateway's pinnedAt registry). */
+  pinnedAt: number
+}
+
+export interface WorkerPinReap extends WorkerPinCandidate {
+  reason: 'terminal' | 'ttl'
+}
+
+/** Extract the agentId from a `wk:<agentId>` pin key, or null for any other
+ *  key shape (fg:/banner:/tool: keys are never worker-reaped). */
+export function workerAgentIdOfPinKey(pinKey: string): string | null {
+  if (!pinKey.startsWith(WORKER_PIN_KEY_PREFIX)) return null
+  const agentId = pinKey.slice(WORKER_PIN_KEY_PREFIX.length)
+  return agentId.length > 0 ? agentId : null
+}
+
+/** The registry's view of a worker, distilled for the reap decision.
+ *  - 'terminal' — row exists in completed | failed: reap now.
+ *  - 'running'  — row exists and is still 'running': NEVER reap, not even
+ *    past the TTL. A healthy 7h worker must not get unpinned mid-run only
+ *    for the next feed edit to re-pin it (pin/unpin churn every TTL). The
+ *    subagent-watcher's stall detection demotes a dead worker's row out of
+ *    'running' within ~60s of its JSONL going quiet, so a true zombie can
+ *    only hold 'running' briefly — the TTL still catches everything the
+ *    registry has lost track of.
+ *  - 'unknown'  — no row / never linked / 'stalled' / lookup error: the
+ *    TTL gate applies (the registry can't vouch for it). */
+export type WorkerRegistryStatus = 'terminal' | 'running' | 'unknown'
+
+/**
+ * Decide which claimed worker pins to unpin now. Pure: the registry lookup is
+ * an injected predicate (`statusOf` must return 'terminal' ONLY for a row in
+ * completed | failed, 'running' only for a live 'running' row, and 'unknown'
+ * for stalled / missing / lookup-error; a DB hiccup must degrade to 'unknown'
+ * — kept until the TTL — never to a spurious 'terminal' unpin).
+ */
+export function decideWorkerPinReaps(args: {
+  pins: Iterable<WorkerPinCandidate>
+  statusOf: (agentId: string) => WorkerRegistryStatus
+  ttlMs: number
+  now: number
+}): WorkerPinReap[] {
+  const reaps: WorkerPinReap[] = []
+  for (const pin of args.pins) {
+    const agentId = workerAgentIdOfPinKey(pin.pinKey)
+    if (agentId == null) continue // not a worker pin — never ours to reap
+    if (pin.chatId.length === 0) continue // can't unpin without a chat
+    const status = args.statusOf(agentId)
+    if (status === 'terminal') {
+      reaps.push({ ...pin, reason: 'terminal' })
+      continue
+    }
+    // A registry-confirmed RUNNING worker keeps its pin regardless of age —
+    // the TTL only reaps pins the registry can't vouch for (see
+    // WorkerRegistryStatus doc).
+    if (status === 'running') continue
+    if (args.now - pin.pinnedAt >= args.ttlMs) {
+      reaps.push({ ...pin, reason: 'ttl' })
+    }
+  }
+  return reaps
+}

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',