switchroom 0.20.10 → 0.20.12

package/telegram-plugin/gateway/stream-render.ts

@@ -90,7 +90,7 @@ import { formatTurnLifecycle } from './status-surface-log.js'
 import { removeTurnActiveMarker, touchTurnActiveMarker, writeTurnActiveMarker } from './turn-active-marker.js'
 import { withTurnEndGateBackstop } from './turn-end-gate-backstop.js'
 import { decideTurnEndGate } from './turn-end-gate.js'
-import { finalizeBackstopSendGated } from './turn-record-status.js'
+import { finalizeBackstopSendGated, computeTurnDurationMs } from './turn-record-status.js'
 import type { SilentEndDeps } from '../silent-end.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import type { SessionEvent } from '../session-tail.js'
@@ -2174,7 +2174,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
             chatId,
             threadId,
             turnId: turn.turnId,
-            turnDurationMs: turn.startedAt > 0 ? Date.now() - turn.startedAt : 0,
+            turnDurationMs: computeTurnDurationMs(turn.startedAt, Date.now()),
             reactionCount: reactionTransitionCounts.get(tKey) ?? 0,
           })
         }
@@ -2214,7 +2214,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
         // still appear in turn-duration graphs.
         {
           const sKey = streamKey(chatId, threadId)
-          const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
+          const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now())
           logStreamingEvent({
             kind: 'turn_end',
             chatId,
@@ -2799,7 +2799,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       finalizeStatusReaction(chatId, threadId, terminalReason)
       {
         const sKey = streamKey(chatId, threadId)
-        const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
+        const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now())
         logStreamingEvent({
           kind: 'turn_end',
           chatId,

package/telegram-plugin/gateway/throttle-tier-wiring.ts

@@ -73,6 +73,10 @@ export interface ThrottleBrokerClient {
     throttled_until: number
     escalated: boolean
     rolledTo?: string | null
+    /** True when the caller has a strict pin (`auth.strict`) — its null
+     *  `rolledTo` means "riding out the wall", not fleet all-blocked.
+     *  Absent on pre-flag brokers. */
+    caller_pinned_strict?: boolean
   }>
   claimNotification(key: string, windowMs: number): Promise<{ granted: boolean }>
 }
@@ -214,19 +218,22 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     client: ThrottleBrokerClient | null,
     account: string | null,
     rolledTo: string | null,
+    callerPinnedStrict: boolean,
     triggerAgent: string,
     armedAtMs: number,
   ): Promise<void> {
     deps.log(
       `[throttle-tier] escalated to wall account=${account ?? '?'} ` +
-        `rolledTo=${rolledTo ?? 'none (all blocked)'}`,
+        `rolledTo=${rolledTo ?? (callerPinnedStrict ? 'none (strict pin, riding it out)' : 'none (all blocked)')}`,
     )
     await broadcastDeduped(
       client,
       'throttle-escalation',
       account,
-      renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo }),
+      renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo, callerPinnedStrict }),
     )
+    // No nudge on a null rolledTo — for a strict pin a resume would replay
+    // the turn straight back into the wall it just hit.
     if (rolledTo) nudgeResume('throttle-escalation-resume', armedAtMs)
   }
 
@@ -240,6 +247,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     let account: string | null = null
     let escalated = false
     let rolledTo: string | null = null
+    let callerPinnedStrict = false
     try {
       client = await deps.getBrokerClient()
       if (client) {
@@ -247,6 +255,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
         account = r.account
         escalated = r.escalated
         rolledTo = r.rolledTo ?? null
+        callerPinnedStrict = r.caller_pinned_strict ?? false
       } else {
         deps.log(
           `[throttle-tier] broker unreachable — notice only, no ledger record agent=${triggerAgent}`,
@@ -259,7 +268,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     }
 
     if (escalated) {
-      await announceEscalation(client, account, rolledTo, triggerAgent, armedAtMs)
+      await announceEscalation(client, account, rolledTo, callerPinnedStrict, triggerAgent, armedAtMs)
       return
     }
 
@@ -303,6 +312,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     let account: string | null = null
     let escalated = false
     let rolledTo: string | null = null
+    let callerPinnedStrict = false
     try {
       client = await deps.getBrokerClient()
       if (client) {
@@ -312,6 +322,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
         account = r.account
         escalated = r.escalated
         rolledTo = r.rolledTo ?? null
+        callerPinnedStrict = r.caller_pinned_strict ?? false
       } else {
         deps.log(
           `[throttle-tier] broker unreachable — probe-only skipped agent=${triggerAgent}`,
@@ -324,7 +335,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     }
 
     if (escalated) {
-      await announceEscalation(client, account, rolledTo, triggerAgent, armedAtMs)
+      await announceEscalation(client, account, rolledTo, callerPinnedStrict, triggerAgent, armedAtMs)
       return
     }
 

package/telegram-plugin/gateway/turn-record-status.ts

@@ -24,6 +24,37 @@
  */
 export type DeliveryOutcome = 'delivered' | 'failed' | 'suppressed'
 
+/**
+ * The ONE way a turn's `duration_ms` is computed, shared by every emitter
+ * (`buildTurnRecord` → turns.jsonl, and all three `turn_ended` runtime-metric
+ * sites: the two stream-render turn-end paths + the liveness framework_fallback).
+ *
+ * Why a single helper: the three `turn_ended` emitters each hand-rolled the
+ * subtraction, and one drifted. `stream-render.ts` guarded with
+ * `startedAt > 0 ? now - startedAt : 0`; the framework_fallback path in
+ * `liveness-wiring.ts` did a bare `Date.now() - turnStartedAt` with only a
+ * `!= null` presence check. When `activeTurnStartedAt` held `0` (or any
+ * non-positive / non-finite value), that path emitted `duration_ms = now - 0`,
+ * i.e. the absolute Unix-epoch-ms — a ~56,000-year "duration". This poisoned the
+ * analysed turn_ended dataset (observed: 110 rows where `duration_ms === ts`),
+ * making every latency aggregate unusable.
+ *
+ * The invariant this helper enforces: a `duration_ms` is ALWAYS a non-negative
+ * elapsed-milliseconds value derived from a positive, finite start stamp — never
+ * an absolute epoch value, never negative (clock step back), never NaN. A start
+ * that is missing / zero / bogus yields `0` (a bounded, filterable sentinel)
+ * instead of a value that destroys aggregates.
+ */
+export function computeTurnDurationMs(
+  startedAt: number | null | undefined,
+  now: number,
+): number {
+  if (typeof startedAt !== 'number' || !Number.isFinite(startedAt) || startedAt <= 0) {
+    return 0
+  }
+  return Math.max(0, now - startedAt)
+}
+
 /** The status strings written to turns.jsonl. `send_failed` is new in PR B. */
 export type TurnStatus = 'complete' | 'no_reply' | 'send_failed'
 
@@ -261,7 +292,7 @@ export function buildTurnRecord(
   return {
     ts: Math.floor(endedAt / 1000),
     agent: turn.agent,
-    duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
+    duration_ms: computeTurnDurationMs(turn.startedAt, endedAt),
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,

package/telegram-plugin/hooks/hooks.json

@@ -5,16 +5,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-guard-pretool.mjs\"",
             "timeout": 10
           }
         ]
       },
       {
+        "matcher": "^mcp__switchroom-telegram__(reply|stream_reply)$",
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/sentinel-reply-guard-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -24,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-pretool.mjs\"",
             "timeout": 10
           }
         ]
@@ -33,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -43,7 +44,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/repo-context-pretool.mjs\"",
             "timeout": 5
           }
         ]
@@ -55,7 +56,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-tracker-posttool.mjs\"",
             "timeout": 10
           }
         ]
@@ -65,7 +66,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
             "timeout": 3
           }
         ]
@@ -76,7 +77,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-marker-precompact.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-marker-precompact.mjs\"",
             "timeout": 5
           }
         ]
@@ -87,7 +88,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/secret-scrub-stop.mjs\"",
             "timeout": 15,
             "async": true
           }
@@ -97,7 +98,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/silent-end-interrupt-stop.mjs\"",
             "timeout": 5
           }
         ]
@@ -106,7 +107,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-claim-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-claim-stop.mjs\"",
             "timeout": 5
           }
         ]
@@ -115,7 +116,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" bun \"${CLAUDE_PLUGIN_ROOT}/hooks/tool-label-stop.mjs\"",
             "timeout": 5,
             "async": true
           }

package/telegram-plugin/hooks/narration-classify.mjs

@@ -108,7 +108,7 @@ export function isStructuralNarration(text, followedByToolUse) {
  * follow-up, MF4). A text block followed ONLY by tools in this set is still the
  * TERMINAL answer for backstop-coalescing purposes — these tools carry no
  * model-authored answer text and are the only ones plausibly fired AFTER a
- * terminal answer (answer, then react / pin / typing / edit). Everything NOT in
+ * terminal answer (answer, then react / typing / edit). Everything NOT in
  * this set — work / deliverable tools (download_attachment, get_recent_messages,
  * send_checklist, ask_user, …) and every non-telegram tool (retain / read /
  * bash / web / …) — is turn-CONTINUING: a text block a real tool followed is
@@ -123,7 +123,6 @@ export function isStructuralNarration(text, followedByToolUse) {
 export const EPHEMERAL_TOOLS = new Set([
   'react',
   'send_typing',
-  'pin_message',
   'delete_message',
   'edit_message',
 ])

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -41,7 +41,7 @@
 // Cross-checked the full tool surface in `telegram-plugin/bridge/bridge.ts`
 // (`TOOL_SCHEMAS`, kept in sync with `gateway/gateway.ts`): `edit_message`
 // explicitly does NOT ping/deliver a fresh answer (its own description says
-// "send a new reply when a long task completes"); `react`, `pin_message`,
+// "send a new reply when a long task completes"); `react`,
 // `delete_message`, `forward_message`, `send_typing`, `download_attachment`,
 // `get_recent_messages` carry no model-authored answer text at all;
 // `send_checklist` / `send_sticker` / `send_gif` / `ask_user` /

package/telegram-plugin/slot-banner-driver.ts

@@ -22,6 +22,11 @@
 
 import type { BannerState } from './slot-banner.js';
 import { decideBannerAction } from './slot-banner.js';
+// Shared rights model (D5): the banner adopts the status-pin path's rights
+// detector, terminal-unpin classifier and per-process negative cache, so the two
+// pin owners agree on which chats are rights-less instead of the banner's old
+// drop-on-ANY-unpin. status-pin.ts is dependency-free.
+import { isPinRightsError, isUnpinTerminalError, type PinRightsCache } from './status-pin.js';
 
 /** Minimal subset of grammy's `bot.api` we depend on. Letting tests
  *  swap in `fake-bot-api.ts` without dragging in the full Bot type. */
@@ -72,6 +77,15 @@ export interface RefreshBannerArgs {
   /** Optional API-failure observer. Phase identifies which Bot API
    *  call failed so the caller can log meaningfully. Default: silent. */
   onError?: (phase: 'pin' | 'edit' | 'unpin', err: unknown) => void;
+  /** Shared per-process pin-rights negative cache (status-pin.ts
+   *  `PinRightsCache`), unifying the banner with the status-pin path on
+   *  rights-less chats (D5). When the chat is already known rights-less the pin
+   *  action is skipped so we never emit an un-pinnable notice; a real pin-rights
+   *  400 from the pin/unpin verb records the block and a confirmed pin clears
+   *  it. Fed ONLY from the pin/unpin verbs — a `sendMessage` failure is never
+   *  cached, because a send failure is not a pin-rights signal. Optional;
+   *  omitted in unit tests. */
+  rightsCache?: Pick<PinRightsCache, 'isBlocked' | 'block' | 'clear'>;
   /** Optional durable-persistence hooks so an orphaned banner pin is
    *  recoverable across a gateway crash. The gateway wires these to the
    *  shared status-pin store (a distinct `banner:` pinKey), mirroring the
@@ -127,20 +141,34 @@ export async function refreshBanner(
 
   if (action.kind === 'unpin') {
     try {
+      // allow-raw-pin: the slot banner is a sanctioned separate pin owner (see
+      // scripts/check-status-pin-single-path-allowlist.txt); its unpin is not
+      // routed through reconcileStatusPin.
       await args.bot.api.unpinChatMessage(args.ownerChatId, action.messageId);
     } catch (err) {
       args.onError?.('unpin', err);
+      // Feed the shared negative cache ONLY from a real pin-rights 400 on the
+      // unpin verb — never from any other failure class (D5).
+      if (isPinRightsError(err)) args.rightsCache?.block(String(args.ownerChatId));
+      // Adopt the status-pin terminal-vs-never-confirmed contract (#3664 Defect
+      // B) instead of drop-on-ANY-unpin: retain the claim when the unpin did
+      // NOT terminally land (transient flood/5xx/network), so the next refresh
+      // retries rather than orphaning a still-pinned banner with no record. A
+      // terminal 4xx (rights, message gone, bot kicked) — and a success — fall
+      // through to the drop below, because re-issuing cannot help.
+      if (!isUnpinTerminalError(err)) return args.prevState;
     }
-    // Even if unpin failed, drop our claim — the message may have been
-    // unpinned out-of-band (operator did it manually) and re-pinning
-    // would be more confusing than surfacing it again later. Drop the
-    // persisted record too (unpin-then-clear mirrors the status-pin store:
-    // a crash between unpin and clear just re-unpins next boot, idempotent).
+    // Terminal outcome: drop our claim and the persisted record. A crash
+    // between unpin and clear just re-unpins next boot (idempotent).
     safePersist(args.persist?.clear);
     return null;
   }
 
   if (action.kind === 'pin') {
+    // The banner is a PINNED notice: if this chat is already known rights-less
+    // (proved by the status-pin path or an earlier banner pin), skip the whole
+    // send+pin — an un-pinnable send is pure noise (D5).
+    if (args.rightsCache?.isBlocked(String(args.ownerChatId))) return args.prevState;
     let sent: { message_id: number };
     try {
       // sendRichMessage doesn't accept link_preview_options — omit it.
@@ -150,6 +178,8 @@ export async function refreshBanner(
         disable_notification: true,
       });
     } catch (err) {
+      // SEND failure — deliberately NOT a pin-rights signal, so the cache is
+      // NEVER written here even though the phase tag below is 'pin' (D5).
       args.onError?.('pin', err);
       return args.prevState;
     }
@@ -158,17 +188,24 @@ export async function refreshBanner(
     // unpins next boot — closing the persist-after-pin leak.
     safePersist(() => args.persist?.pending?.(String(args.ownerChatId), sent.message_id));
     try {
+      // allow-raw-pin: sanctioned banner pin owner (see the allowlist).
       await args.bot.api.pinChatMessage(args.ownerChatId, sent.message_id, {
         disable_notification: true,
       });
     } catch (err) {
       args.onError?.('pin', err);
+      // The PIN verb failing with a real pin-rights 400 IS the rights signal —
+      // record it so later refreshes skip the doomed send+pin (D5).
+      if (isPinRightsError(err)) args.rightsCache?.block(String(args.ownerChatId));
       // sendMessage succeeded but pin failed — don't claim the message, and
       // drop the pending record so we don't leave a phantom claim for a pin
       // that never landed.
       safePersist(args.persist?.clear);
       return args.prevState;
     }
+    // Pin confirmed — rights are present, so clear any stale block for this chat
+    // (mirrors the status-pin path clearing on a successful pin).
+    args.rightsCache?.clear(String(args.ownerChatId));
     // Pin confirmed — rewrite the record without the pending flag.
     safePersist(() => args.persist?.confirm?.(String(args.ownerChatId), sent.message_id));
     return { messageId: sent.message_id, slot: action.slot };

package/telegram-plugin/status-pin.ts

@@ -210,12 +210,9 @@ export function isUnpinTerminalError(err: unknown): boolean {
  * Deliberately IN-MEMORY / per-boot only: pin rights may be granted later, and
  * Telegram surfaces the new permission to the bot only on a fresh chat-member
  * fetch — a gateway restart. Clearing the cache on restart is therefore the
- * correct re-enable trigger. An explicit `pin_message` tool success in a chat
- * also clears its entry (rights were granted mid-session).
+ * correct re-enable trigger.
  *
- * Scope: the AUTO status-pin path only. The explicit `pin_message` MCP tool
- * never consults this cache — it always attempts and surfaces the error to the
- * agent as a normal tool error.
+ * Scope: the AUTO status-pin path only (`pin_status_while_working`).
  */
 export class PinRightsCache {
   private readonly blocked = new Set<string>()

package/telegram-plugin/tests/auto-fallback-fleet.test.ts

@@ -190,6 +190,30 @@ describe('runFleetAutoFallback', () => {
     expect(failover).toHaveBeenCalledTimes(1);
   });
 
+  it('strict-pinned caller: null rolledTo yields the strict-pinned outcome, NOT all-blocked', async () => {
+    // agents.<name>.auth.strict — the broker marked the account but
+    // deliberately did not roll the caller. The all-blocked card here would
+    // claim fleet-wide exhaustion while its own snapshots show healthy
+    // accounts.
+    const failover = vi.fn(async () => ({
+      rolledTo: null, rolled: [], callerPinnedStrict: true,
+    }));
+    const out = await runFleetAutoFallback({
+      state: state('work@x', ['work@x']),
+      quotas: [qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 })],
+      failover,
+      triggerAgent: 'workbot',
+      now: NOW,
+      tz: 'UTC',
+      rateLimitTrigger: true,
+    });
+    expect(out.kind).toBe('strict-pinned');
+    expect(failover).toHaveBeenCalledTimes(1);
+    expect(out.announcement).toContain('strictly pinned');
+    expect(out.announcement).toContain('fleet is unaffected');
+    expect(out.announcement).not.toContain('blocked');
+  });
+
   it('idempotency: skips the swap WITHOUT calling failover when active probes healthy', async () => {
     const failover = vi.fn();
     const out = await runFleetAutoFallback({

package/telegram-plugin/tests/backstop-exactly-once.test.ts

@@ -121,9 +121,9 @@ describe('selectBackstopDelivery — deterministic backstop coalescer (#3513 fol
 // ── isEphemeralTool — MF4 exact set ─────────────────────────────────────────
 
 describe('isEphemeralTool — the exact ephemeral surface set (MF4)', () => {
-  it('recognises exactly {react, send_typing, pin_message, delete_message, edit_message}, MCP-prefixed or bare', () => {
+  it('recognises exactly {react, send_typing, delete_message, edit_message}, MCP-prefixed or bare', () => {
     expect([...EPHEMERAL_TOOLS].sort()).toEqual(
-      ['delete_message', 'edit_message', 'pin_message', 'react', 'send_typing'].sort(),
+      ['delete_message', 'edit_message', 'react', 'send_typing'].sort(),
     )
     for (const t of EPHEMERAL_TOOLS) {
       expect(isEphemeralTool(t)).toBe(true)
@@ -132,6 +132,12 @@ describe('isEphemeralTool — the exact ephemeral surface set (MF4)', () => {
     }
   })
 
+  it('pin_message is NOT ephemeral — the pin_message MCP tool was retired (#4452)', () => {
+    expect(EPHEMERAL_TOOLS.has('pin_message')).toBe(false)
+    expect(isEphemeralTool('pin_message')).toBe(false)
+    expect(isEphemeralTool('mcp__switchroom-telegram__pin_message')).toBe(false)
+  })
+
   it('progress_update is NOT ephemeral (MF4 — dropped from the set)', () => {
     expect(isEphemeralTool('progress_update')).toBe(false)
     expect(isEphemeralTool('mcp__switchroom-telegram__progress_update')).toBe(false)

package/telegram-plugin/tests/framework-fallback-duration-guard.test.ts

@@ -0,0 +1,125 @@
+/**
+ * M0 metric-corruption regression — the framework_fallback `turn_ended` emitter
+ * must never write an absolute Unix-epoch value as `duration_ms`.
+ *
+ * ROOT CAUSE (fixed by this change): the 300 s framework-fallback unwedge in
+ * `liveness-wiring.ts` read the turn's start from `activeTurnStartedAt.get(key)`
+ * and, guarded only by a `!= null` presence check, computed
+ * `Date.now() - turnStartedAt` inline. When the map held `0` (a bogus / not-yet
+ * stamped start — reproduced here exactly as the parked-turn fixture does with
+ * `activeTurnStartedAt.set(KEY, 0)`), it emitted `duration_ms = Date.now() - 0`,
+ * i.e. the current epoch-ms — a ~56,000-year "duration". The analysed dataset
+ * carried 110 such rows (`duration_ms === ts`, `ended_via: "framework_fallback"`),
+ * making every latency aggregate unusable.
+ *
+ * The two `stream-render.ts` turn_ended paths already guarded with
+ * `startedAt > 0 ? … : 0`; this path had drifted. The fix routes all emitters
+ * through the shared `computeTurnDurationMs`, which returns 0 for a non-positive
+ * start.
+ *
+ * This test drives the REAL `onFrameworkFallback` (via `buildSilencePokeOptions`,
+ * same standard as the other liveness-wiring tests) with a 0 start and asserts on
+ * the ACTUAL emitted `turn_ended` row (captured through the real runtime-metrics
+ * JSONL sink, pinned to a temp file). It asserts the OUTCOME — the emitted
+ * `duration_ms` — not a code path.
+ *
+ * Pre-fix: `duration_ms` ≈ `Date.now()` (~1.78e12). Post-fix: `duration_ms === 0`.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { buildSilencePokeOptions } from '../gateway/liveness-wiring.js'
+import {
+  __setRuntimeMetricsPathForTests,
+} from '../runtime-metrics.js'
+import { makeLivenessFixture, makeTurn, statusKeyForTests } from './helpers/liveness-wiring-fixture.js'
+
+const CHAT = '-100999'
+
+function readTurnEndedRows(path: string): Array<Record<string, unknown>> {
+  if (!existsSync(path)) return []
+  return readFileSync(path, 'utf-8')
+    .split('\n')
+    .filter((l) => l.trim() !== '')
+    .map((l) => JSON.parse(l) as Record<string, unknown>)
+    .filter((r) => r.kind === 'turn_ended')
+}
+
+describe('framework_fallback turn_ended never emits an epoch value as duration_ms', () => {
+  let metricsPath: string
+
+  beforeEach(() => {
+    const dir = mkdtempSync(join(tmpdir(), 'fallback-duration-'))
+    metricsPath = join(dir, 'runtime-metrics.jsonl')
+    __setRuntimeMetricsPathForTests(metricsPath)
+  })
+
+  afterEach(() => {
+    __setRuntimeMetricsPathForTests(null)
+  })
+
+  it('emits duration_ms === 0 for a zero/bogus start instead of Date.now()', async () => {
+    const KEY = statusKeyForTests(CHAT, null)
+    const fx = makeLivenessFixture()
+
+    // The wedged turn's start is 0 — the exact corruption trigger. Before the
+    // fix this made the fallback emit `Date.now() - 0`.
+    fx.activeTurnStartedAt.set(KEY, 0)
+    fx.setCurrentTurn(
+      makeTurn({ sessionChatId: CHAT, sessionThreadId: undefined, turnId: `${KEY}#42` }),
+    )
+
+    const opts = buildSilencePokeOptions(fx.deps)
+    await opts.onFrameworkFallback({
+      key: KEY,
+      chatId: CHAT,
+      threadId: null,
+      fallbackKind: 'working',
+      silenceMs: 302_000,
+      inFlightTools: [],
+    })
+
+    const rows = readTurnEndedRows(metricsPath)
+    const fallbackRow = rows.find((r) => r.ended_via === 'framework_fallback')
+    expect(fallbackRow, 'framework_fallback turn_ended row was emitted').toBeDefined()
+
+    const duration = fallbackRow!.duration_ms as number
+    // The falsifying assertion: pre-fix this is ~Date.now() (an epoch-ms value,
+    // ~1.78e12), and in particular equals the row's own `ts`. Post-fix it is 0.
+    expect(duration).toBe(0)
+    // Belt-and-braces: a duration can never be an absolute epoch stamp, and can
+    // never equal the emission timestamp.
+    expect(duration).not.toBe(fallbackRow!.ts as number)
+    expect(duration).toBeLessThan(365 * 24 * 60 * 60 * 1000) // < 1 year, sane bound
+  })
+
+  it('emits a real elapsed duration for a valid positive start', async () => {
+    const KEY = statusKeyForTests(CHAT, null)
+    const fx = makeLivenessFixture()
+
+    const startedAt = Date.now() - 302_000 // ~5 min ago
+    fx.activeTurnStartedAt.set(KEY, startedAt)
+    fx.setCurrentTurn(
+      makeTurn({ sessionChatId: CHAT, sessionThreadId: undefined, turnId: `${KEY}#43` }),
+    )
+
+    const opts = buildSilencePokeOptions(fx.deps)
+    await opts.onFrameworkFallback({
+      key: KEY,
+      chatId: CHAT,
+      threadId: null,
+      fallbackKind: 'working',
+      silenceMs: 302_000,
+      inFlightTools: [],
+    })
+
+    const fallbackRow = readTurnEndedRows(metricsPath).find(
+      (r) => r.ended_via === 'framework_fallback',
+    )
+    const duration = fallbackRow!.duration_ms as number
+    // Around 302 s, with generous slack for test-runtime jitter.
+    expect(duration).toBeGreaterThanOrEqual(302_000)
+    expect(duration).toBeLessThan(360_000)
+  })
+})

package/telegram-plugin/tests/gateway-handler-registration-wiring.test.ts

@@ -57,6 +57,8 @@ const GOLDEN_REGISTRATIONS: readonly string[] = [
   'command:inject',
   'command:compact',
   'command:clear',
+  'command:private',
+  'command:public',
   'helper:registerModelEffortCommands',
   'command:agentstart',
   'command:agentstop',