switchroom 0.13.32 → 0.13.35

package/telegram-plugin/tests/boot-clears-clean-shutdown-marker.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Regression guard for the marker-stale crash banner class.
+ *
+ * Pre-2026-05-25 the boot path read the clean-shutdown marker but
+ * never cleared it. A marker from a graceful shutdown 11 hours ago
+ * sat on disk untouched; subsequent boots after an unhandledRejection
+ * crash (which explicitly SKIPS writing a new marker, per
+ * gateway.ts:15107) read the stale marker, classified the age as
+ * >5min, and fired `boot.clean_shutdown_marker_stale age=39976s` →
+ * `reason=crash` → `agent-crashed` operator-event banner posted to
+ * the user's chat.
+ *
+ * That misclassified the user-visible state ("clerk seems to be
+ * crashing") because the banner detail included the stale-marker
+ * artifact rather than just naming the actual crash.
+ *
+ * Fix: clear the marker after every successful boot reads it. The
+ * marker now describes the IMMEDIATELY PRECEDING shutdown only;
+ * a subsequent crash with no marker write leaves an empty marker
+ * file, and boot-reason.ts:84 correctly classifies via the
+ * sessionMarker fallback.
+ *
+ * The gateway IIFE is too entangled to instantiate in-process; this
+ * is a source-level pin matching the pattern used by
+ * `reply-terminal-reaction.test.ts` and `buffer-gate-broadened.test.ts`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('boot path clears the clean-shutdown marker after reading it', () => {
+  it('imports clearCleanShutdownMarker (no longer the "intentionally not imported" comment)', () => {
+    // Pre-fix the import block had a `clearCleanShutdownMarker is
+    // intentionally NOT imported here` block-comment, with a rationale
+    // that was wrong for the unhandledRejection edge case. If a future
+    // commit re-removes the import (and re-adds the wrong comment),
+    // this test trips.
+    expect(gatewaySrc).toMatch(/^\s*clearCleanShutdownMarker,$/m)
+    // The old "intentionally NOT imported" comment must be gone.
+    expect(gatewaySrc).not.toMatch(/clearCleanShutdownMarker is intentionally NOT imported/)
+  })
+
+  it('calls clearCleanShutdownMarker inside the marker-read block at boot', () => {
+    // Slice the marker-read block (between the boot.clean_shutdown_*
+    // diagnostic logs and the next `if (marker)` line). The clear call
+    // MUST appear inside this block, not later in the boot flow —
+    // future readers should see the read and clear together.
+    const anchor = gatewaySrc.indexOf('boot.clean_shutdown_detected')
+    expect(anchor).toBeGreaterThan(-1)
+    const slice = gatewaySrc.slice(anchor, anchor + 4000)
+    expect(slice).toMatch(/clearCleanShutdownMarker\(GATEWAY_CLEAN_SHUTDOWN_MARKER_PATH\)/)
+  })
+
+  it('clear comment explains the unhandledRejection edge case', () => {
+    // Future maintainers MUST understand why the clear is here.
+    // The comment block above the call references the
+    // unhandledRejection / "crash path" semantics so the next
+    // engineer doesn't remove it as cleanup.
+    const callIdx = gatewaySrc.indexOf(
+      'clearCleanShutdownMarker(GATEWAY_CLEAN_SHUTDOWN_MARKER_PATH)',
+    )
+    expect(callIdx).toBeGreaterThan(-1)
+    // The 1500 chars immediately before the call should mention the
+    // failure mode this fixes (the comment block sits right above
+    // the call and is ~1100 chars at current writing).
+    const lead = gatewaySrc.slice(Math.max(0, callIdx - 1500), callIdx)
+    expect(lead).toMatch(/unhandledRejection|crash path/)
+  })
+})

package/telegram-plugin/tests/error-envelope-unlock-card.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Telegram bridge unlock-card safety (#1758 Phase 1).
+ *
+ * The bridge MUST validate `flip_yaml_flag.yaml_path` against the
+ * config-edit-validator allowlist before rendering a one-tap approval
+ * card. A malformed or hostile envelope from any backend could
+ * otherwise nudge the operator into approving an arbitrary flag flip.
+ */
+
+import { describe, it, expect } from "vitest";
+import { renderErrorEnvelopeCard } from "../gateway/error-envelope-card.js";
+import type { HostdResponse } from "../../src/host-control/protocol.js";
+
+function mkResp(fix: HostdResponse["error_envelope"]["fix"]): HostdResponse {
+  return {
+    v: 1,
+    request_id: "r-1",
+    result: "error",
+    exit_code: null,
+    duration_ms: 0,
+    error: "E_FOO: foo",
+    error_envelope: {
+      v: 1,
+      code: "E_FOO",
+      human: "foo",
+      fix,
+      request_id: "r-1",
+    },
+  } as HostdResponse;
+}
+
+describe("renderErrorEnvelopeCard — allowlist guard", () => {
+  it("renders an approval card for an allowlisted yaml_path", () => {
+    const resp = mkResp({
+      kind: "flip_yaml_flag",
+      yaml_path: "hostd.config_edit_enabled",
+      to: true,
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out.kind).toBe("card");
+    if (out.kind === "card") {
+      expect(out.yaml_path).toBe("hostd.config_edit_enabled");
+      expect(out.to).toBe(true);
+      expect(out.card.text).toContain("klanker");
+    }
+  });
+
+  it("falls back to plain-text for a NON-allowlisted yaml_path", () => {
+    const resp = mkResp({
+      kind: "flip_yaml_flag",
+      yaml_path: "hostd.evil_backdoor_flag",
+      to: true,
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+
+  it("falls back to plain-text for request_vault_grant (Phase 2 scope)", () => {
+    const resp = mkResp({
+      kind: "request_vault_grant",
+      vault_key: "openai/api-key",
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+
+  it("falls back to plain-text when no envelope is present", () => {
+    const resp: HostdResponse = {
+      v: 1,
+      request_id: "r-1",
+      result: "error",
+      exit_code: null,
+      duration_ms: 0,
+      error: "legacy string",
+    };
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+});

package/telegram-plugin/tests/silent-end-integration.test.ts

@@ -0,0 +1,268 @@
+/**
+ * silent-end-integration.test.ts — #1744 follow-up.
+ *
+ * The existing silent-end.test.ts (#1741 block, L301-409) exercises the
+ * gate as a pure unit via `simulateReplyAtGateway`, which mirrors the
+ * `isFinalAnswerReply ? clearSilentEndState(...)` contract used at the
+ * `executeReply` send-site (gateway.ts:4609). That's a fine unit test
+ * for the `executeReply` path, but it does NOT model the `stream_reply`
+ * state machine where:
+ *
+ *   - The FIRST stream emit is gated by `!activeDraftStreams.has(sKey)`
+ *     (gateway.ts:5178) — only the first emit per stream considers
+ *     clearing the silent-end state.
+ *   - LATER emits in the same stream (subsequent calls that edit the
+ *     same Telegram message) do NOT re-enter that first-emit branch.
+ *
+ * Pre-fix, a stream whose first emit was ack-shaped (short, silent, no
+ * done) and whose LATER emit carried `done=true` or substantive text
+ * would skip the clear at the first-emit gate and never re-attempt it,
+ * leaving the silent-end state file behind even though the model HAS
+ * now delivered its final answer. The Stop hook would then see a stale
+ * state file and fire a spurious re-prompt on the next turn end.
+ *
+ * The fix in gateway.ts:5343 adds a second clear at the
+ * `finalAnswerDelivered = true` site (which fires on EVERY emit that
+ * qualifies as a final answer, not just the first). This test walks
+ * the full ack-then-final stream sequence and asserts the state file's
+ * lifecycle matches the contract.
+ *
+ * KNOWN GAP — true end-to-end coverage of `executeStreamReply` would
+ * require importing gateway.ts (a multi-thousand-line module with
+ * heavy startup-time side effects: bot creation, IPC server bind, MCP
+ * registration, etc.). Neither `executeReply` nor `executeStreamReply`
+ * is exported. Instead, this test reproduces the EXACT call sequence
+ * the gateway makes at each send-site — same predicate
+ * (`isFinalAnswerReply`), same state-file API (`writeSilentEndState` /
+ * `clearSilentEndState`), same first-emit gating logic — by walking a
+ * tracked `activeDraftStreams` set to model the first-vs-later-emit
+ * branching that's the load-bearing detail of the bug. A future
+ * refactor that drops the second clear at L5343 would fail the
+ * `ack first emit then final later emit` test below, because the
+ * state file would never get cleared on the path that no longer
+ * passes through the first-emit branch.
+ *
+ * If the gateway is ever refactored so `executeReply`/`executeStreamReply`
+ * become testable in isolation (or get extracted into a thin
+ * dispatch shim around a pure handler), prefer wiring those real
+ * functions over this faithful-shape reproduction.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  writeSilentEndState,
+  clearSilentEndState,
+  readSilentEndState,
+} from '../silent-end.js'
+import { isFinalAnswerReply } from '../final-answer-detect.js'
+
+let stateDir: string
+const ORIG_ENV = process.env.TELEGRAM_STATE_DIR
+
+beforeEach(() => {
+  stateDir = mkdtempSync(join(tmpdir(), 'silent-end-integration-test-'))
+  process.env.TELEGRAM_STATE_DIR = stateDir
+})
+
+afterEach(() => {
+  rmSync(stateDir, { recursive: true, force: true })
+  if (ORIG_ENV != null) process.env.TELEGRAM_STATE_DIR = ORIG_ENV
+  else delete process.env.TELEGRAM_STATE_DIR
+})
+
+/**
+ * Shape-accurate reproduction of the gateway's `executeReply` clear
+ * site (gateway.ts:4599-4611). The `reply` tool runs this on every
+ * call — no first-emit gating, because `reply` always produces a
+ * fresh outbound message.
+ */
+function simulateExecuteReply(
+  reply: { text: string; disableNotification: boolean },
+  turnKey: string,
+): { finalAnswerDelivered: boolean } {
+  const final = isFinalAnswerReply(reply)
+  if (final) clearSilentEndState(turnKey)
+  return { finalAnswerDelivered: final }
+}
+
+/**
+ * Shape-accurate reproduction of the gateway's `executeStreamReply`
+ * call (gateway.ts:5172-5344). The stream has TWO clear sites:
+ *
+ *   1. First-emit-only branch (L5178-5195) — fires once per stream,
+ *      regardless of whether this emit is the final answer. Clears
+ *      iff this first emit is a final-answer-shaped reply.
+ *   2. Final-answer site (L5335-5358, added in #1744 follow-up) —
+ *      fires on EVERY emit that qualifies as the final answer,
+ *      including later emits in a stream whose first emit was an ack.
+ *      This is the load-bearing addition: without it, the ack-first-
+ *      then-final-later case leaks the state file.
+ *
+ * `activeDraftStreams` is a Set-like state the gateway carries across
+ * calls within the same turn; this test threads it through explicitly.
+ */
+function simulateExecuteStreamReply(
+  emit: { text: string; disableNotification: boolean; done?: boolean },
+  turnKey: string,
+  state: { activeDraftStreams: Set<string>; finalAnswerDelivered: boolean },
+): { finalAnswerDelivered: boolean } {
+  // Site 1 — first-emit-only branch.
+  const isFirstEmit = !state.activeDraftStreams.has(turnKey)
+  if (isFirstEmit) {
+    if (isFinalAnswerReply(emit)) {
+      clearSilentEndState(turnKey)
+    }
+    // Mark the stream active for subsequent emits.
+    state.activeDraftStreams.add(turnKey)
+  }
+
+  // ... draft / send-message work happens here in the real gateway ...
+
+  // Site 2 — final-answer site (#1744 follow-up at gateway.ts:5343).
+  if (isFinalAnswerReply(emit)) {
+    state.finalAnswerDelivered = true
+    clearSilentEndState(turnKey)
+  }
+  return { finalAnswerDelivered: state.finalAnswerDelivered }
+}
+
+describe('#1744 — silent-end state-file lifecycle through real call paths', () => {
+  it('executeReply: ack reply does not clear, then final-answer reply clears', () => {
+    // Turn-end writer fires from a prior turn that ended undelivered,
+    // OR the framework re-prompted and the state still persists.
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+
+    // Interim ack via `reply` — must NOT clear.
+    const r1 = simulateExecuteReply({ text: 'On it', disableNotification: true }, 'c:_')
+    expect(r1.finalAnswerDelivered).toBe(false)
+    expect(readSilentEndState()).not.toBeNull()
+
+    // Final answer via `reply` (pings) — clears.
+    const r2 = simulateExecuteReply(
+      { text: "Here's the result.", disableNotification: false },
+      'c:_',
+    )
+    expect(r2.finalAnswerDelivered).toBe(true)
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('executeStreamReply: stream that opens with a final-answer first emit clears at first-emit site', () => {
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    const state = { activeDraftStreams: new Set<string>(), finalAnswerDelivered: false }
+
+    // First emit is substantive (>=200 chars) — qualifies as final.
+    simulateExecuteStreamReply(
+      { text: 'x'.repeat(250), disableNotification: true },
+      'c:_',
+      state,
+    )
+    expect(state.finalAnswerDelivered).toBe(true)
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('executeStreamReply ack-then-final edge case: first emit is an ack (no clear at first-emit gate), later emit is the final answer (must clear at the new L5343 site)', () => {
+    // This is the regression the #1744 follow-up fixes. Pre-fix, the
+    // first-emit gate would skip the clear (ack-shaped first emit),
+    // and the later final-answer emit had NO second clear site —
+    // state file leaked.
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    const state = { activeDraftStreams: new Set<string>(), finalAnswerDelivered: false }
+
+    // First emit — ack-shaped. First-emit gate fires but the
+    // isFinalAnswerReply predicate returns false → no clear here.
+    simulateExecuteStreamReply(
+      { text: 'thinking...', disableNotification: true, done: false },
+      'c:_',
+      state,
+    )
+    expect(state.finalAnswerDelivered).toBe(false)
+    // CONTRACT: state file MUST still be present after the ack first emit.
+    expect(readSilentEndState()).not.toBeNull()
+
+    // Second emit — same stream (activeDraftStreams already has the key),
+    // so the first-emit branch is skipped. This emit carries done=true
+    // (the real final-answer signal). Without the L5343 clear, the
+    // state file would persist and the Stop hook would fire a spurious
+    // re-prompt on the next turn.
+    simulateExecuteStreamReply(
+      { text: 'done', disableNotification: true, done: true },
+      'c:_',
+      state,
+    )
+    expect(state.finalAnswerDelivered).toBe(true)
+    // CONTRACT: state file MUST be cleared after the final-answer
+    // emit, even though the first-emit branch was skipped.
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('executeStreamReply: late emit that flips disable_notification=false also clears', () => {
+    // Variant of the edge case — final-answer signal is the pacing
+    // contract flag rather than done=true.
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    const state = { activeDraftStreams: new Set<string>(), finalAnswerDelivered: false }
+
+    simulateExecuteStreamReply(
+      { text: 'one sec', disableNotification: true, done: false },
+      'c:_',
+      state,
+    )
+    expect(readSilentEndState()).not.toBeNull()
+
+    // Later emit drops the disable_notification flag — the pacing
+    // contract's "final answer" signal — but not done yet.
+    simulateExecuteStreamReply(
+      { text: "Here's what I found.", disableNotification: false, done: false },
+      'c:_',
+      state,
+    )
+    expect(state.finalAnswerDelivered).toBe(true)
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('idempotency: clearSilentEndState is safe to call when the file is already gone', () => {
+    // The L5343 clear is unconditional on isFinalAnswerReply — it
+    // fires even when the first-emit gate already cleared. The
+    // clear must be a no-op in that case so it can't accidentally
+    // unlink a fresh state file written for a DIFFERENT later turn.
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    const state = { activeDraftStreams: new Set<string>(), finalAnswerDelivered: false }
+
+    // First emit is final — clears via the first-emit site.
+    simulateExecuteStreamReply(
+      { text: 'answer', disableNotification: false },
+      'c:_',
+      state,
+    )
+    expect(readSilentEndState()).toBeNull()
+
+    // A second final-shaped emit on the same stream re-enters the
+    // L5343 clear. State is already gone — must be a no-op.
+    expect(() => {
+      simulateExecuteStreamReply(
+        { text: 'addendum', disableNotification: false },
+        'c:_',
+        state,
+      )
+    }).not.toThrow()
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('cross-turn safety: clearSilentEndState on turnKey A does NOT clear state for turnKey B', () => {
+    // The clear is keyed on turnKey via the writer's stored value —
+    // a clear call for a DIFFERENT turn must not unlink a state file
+    // written for the in-flight turn. This guards against the L5343
+    // clear accidentally racing a turn-end writer for a newer turn.
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:turn-B' })
+    // A stale clear for turn-A — silent-end.ts only unlinks when the
+    // stored turnKey matches.
+    clearSilentEndState('c:turn-A')
+    expect(readSilentEndState()).not.toBeNull()
+    expect(readSilentEndState()!.turnKey).toBe('c:turn-B')
+
+    // The matching clear works.
+    clearSilentEndState('c:turn-B')
+    expect(readSilentEndState()).toBeNull()
+  })
+})

package/telegram-plugin/tests/silent-end.test.ts

@@ -301,6 +301,111 @@ describe('recordUndeliveredTurnEnd — #1664 extended trigger', () => {
   })
 })
 
+describe('#1741 — ack reply must not clear silent-end state', () => {
+  // The gateway gates `clearSilentEndState` at the reply send-site on
+  // `isFinalAnswerReply`. These tests reproduce that gate as a unit:
+  // simulate a turn's reply sequence by calling the same predicate the
+  // gateway uses, and assert state-file persistence matches the contract.
+  //
+  // Why this matters: if `turn_end` never lands (Claude Code's
+  // `turn_duration` system event is unreliable for trivial-prompt
+  // turns), the only line of defence between an undelivered turn and
+  // the Stop hook is the persistence of `silent-end-pending.json`.
+  // Pre-fix, an ack reply cleared the file unconditionally — so the
+  // Stop hook found no state and allowed the stop on every ack-then-
+  // tool-then-silent shape. Post-fix, only a plausibly-final reply
+  // clears it.
+
+  function simulateReplyAtGateway(
+    reply: { text: string; disableNotification: boolean; done?: boolean },
+    turnKey: string,
+  ): void {
+    // The gateway calls clearSilentEndState ONLY when isFinalAnswerReply
+    // is true. Mirror that gate exactly.
+    if (isFinalAnswerReply(reply)) {
+      clearSilentEndState(turnKey)
+    }
+  }
+
+  it('ack reply (disable_notification, short, no done) does NOT clear pending state', () => {
+    // A prior turn-end already wrote state (or a re-prompt round wrote it).
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    // Agent sends an interim ack.
+    simulateReplyAtGateway(
+      { text: 'On it', disableNotification: true },
+      'c:_',
+    )
+    // State must persist — the Stop hook still needs to be able to
+    // catch a subsequent silent end.
+    expect(readSilentEndState()).not.toBeNull()
+    expect(readSilentEndState()!.turnKey).toBe('c:_')
+  })
+
+  it('final-answer reply (disable_notification=false) clears the state', () => {
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    simulateReplyAtGateway(
+      { text: "Done — here's the result.", disableNotification: false },
+      'c:_',
+    )
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('stream_reply done=true clears the state even with disable_notification=true', () => {
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    simulateReplyAtGateway(
+      { text: 'ok', disableNotification: true, done: true },
+      'c:_',
+    )
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('long ack-shaped reply (>=200 chars) is treated as final and clears the state', () => {
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    simulateReplyAtGateway(
+      { text: 'x'.repeat(250), disableNotification: true },
+      'c:_',
+    )
+    expect(readSilentEndState()).toBeNull()
+  })
+
+  it('ack-then-silent end-to-end: ack does not clear, Stop hook still blocks', () => {
+    // 1. The previous undelivered turn-end wrote state, OR the turn
+    //    starts fresh and only the Stop hook will see this state file
+    //    once the gateway re-writes it. Simulate the gateway's writer
+    //    firing at turn-end with finalAnswerDelivered=false (no
+    //    qualifying reply happened this turn).
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    // 2. Mid-turn ack reply lands. Pre-fix this would unlink the
+    //    state file; post-fix it must persist.
+    simulateReplyAtGateway(
+      { text: 'On it, working on it…', disableNotification: true },
+      'c:_',
+    )
+    // 3. Stop hook fires (separately tested below): it must still
+    //    find the state file and decide to block. Verify the file is
+    //    intact at the path the hook reads.
+    const state = readSilentEndState()
+    expect(state).not.toBeNull()
+    expect(state!.turnKey).toBe('c:_')
+  })
+
+  it('ack-then-final: ack does not clear, final clears', () => {
+    writeSilentEndState({ chatId: 'c', threadId: null, turnKey: 'c:_' })
+    // Interim ack — state persists.
+    simulateReplyAtGateway(
+      { text: 'On it', disableNotification: true },
+      'c:_',
+    )
+    expect(readSilentEndState()).not.toBeNull()
+    // Final answer — state cleared.
+    simulateReplyAtGateway(
+      { text: 'Done — the answer is 42.', disableNotification: false },
+      'c:_',
+    )
+    expect(readSilentEndState()).toBeNull()
+  })
+})
+
 describe('silent-end-interrupt-stop hook — integration', () => {
   const hookPath = join(__dirname, '..', 'hooks', 'silent-end-interrupt-stop.mjs')
 

package/telegram-plugin/tests/unhandled-rejection-policy.test.ts

@@ -103,11 +103,6 @@ describe('classifyRejection — genuine errors still crash', () => {
     expect(classifyRejection(err)).toBe('shutdown')
   })
 
-  it('returns "shutdown" for GrammyError 429 (rate limit) — should be retried not masked', () => {
-    const err = grammyError(429, 'Too Many Requests: retry after 5')
-    expect(classifyRejection(err)).toBe('shutdown')
-  })
-
   it('returns "shutdown" for GrammyError 400 with NEW unknown description', () => {
     // Use a description that's not in the benign list — the policy is
     // intentionally narrow so genuinely new bug categories still crash
@@ -115,9 +110,59 @@ describe('classifyRejection — genuine errors still crash', () => {
     const err = grammyError(400, 'Bad Request: PHOTO_INVALID_DIMENSIONS')
     expect(classifyRejection(err)).toBe('shutdown')
   })
+})
+
+describe('classifyRejection — transient API errors (2026-05-25 follow-up)', () => {
+  // The pre-fix policy crashed on 429 + 5xx + network errors. That's
+  // wrong shape: those errors are already handled by retry-api-call.ts
+  // (3 attempts with backoff). When one leaks past the retry policy —
+  // either because the caller didn't wrap, or because 3 sustained
+  // attempts all failed — crashing the gateway is the worst outcome
+  // (one bad packet = visible "agent-crashed" banner + restart loop
+  // risk). log_only matches the daemon-stays-up posture.
+  //
+  // Surfaced 2026-05-25 on clerk: a sendMessage hit 429 after exhausting
+  // retries, the rejection bubbled to the unhandledRejection handler,
+  // shutdown fired, operator-event banner posted, "clerk seems to be
+  // crashing" user-visible.
+
+  it('returns "log_only" for GrammyError 429 (rate limit) — already handled by retry-api-call', () => {
+    const err = grammyError(429, 'Too Many Requests: retry after 5')
+    expect(classifyRejection(err)).toBe('log_only')
+  })
 
-  it('returns "shutdown" for GrammyError 500 server error', () => {
+  it('returns "log_only" for GrammyError 500 (server error)', () => {
     const err = grammyError(500, 'Internal Server Error')
+    expect(classifyRejection(err)).toBe('log_only')
+  })
+
+  it('returns "log_only" for GrammyError 502 (Bad Gateway)', () => {
+    const err = grammyError(502, 'Bad Gateway')
+    expect(classifyRejection(err)).toBe('log_only')
+  })
+
+  it('returns "log_only" for GrammyError 503 (Service Unavailable)', () => {
+    const err = grammyError(503, 'Service Unavailable')
+    expect(classifyRejection(err)).toBe('log_only')
+  })
+
+  it('returns "log_only" for HttpError (network failure) via injected detector', () => {
+    // Real grammy HttpError surfaces as e.g. "Network request for
+    // 'sendMessage' failed!" wrapping ECONNRESET / ETIMEDOUT / fetch
+    // failed. We inject the detector so this test doesn't depend on
+    // grammy internals; the production path uses `err instanceof
+    // HttpError`.
+    const fakeHttp = new Error("Network request for 'sendMessage' failed!")
+    expect(
+      classifyRejection(fakeHttp, { isHttpError: () => true }),
+    ).toBe('log_only')
+  })
+
+  it('still returns "shutdown" for GrammyError 403 (forbidden) — must not be masked', () => {
+    // 401 (covered above at line 101) and 403 are NOT transient — they
+    // indicate a genuine configuration bug (revoked bot token, removed
+    // from chat) and must crash so systemd surfaces the failure.
+    const err = grammyError(403, 'Forbidden: bot was blocked by the user')
     expect(classifyRejection(err)).toBe('shutdown')
   })
 })