switchroom 0.19.4 → 0.19.5

package/telegram-plugin/gateway/hang-restart-decision.ts

@@ -0,0 +1,189 @@
+/**
+ * hang-restart-decision.ts — the progress-based hang-restart discriminator
+ * (Stage B safety net).
+ *
+ * WHY THIS EXISTS
+ *
+ * The silence-poke framework fallback (`liveness-wiring.ts onFrameworkFallback`)
+ * is the last-resort unwedge, but it only tears down GATEWAY state — it never
+ * kills the wedged `claude` child. So a turn that hangs mid-tool-call recovers
+ * its conversation slot but leaves the child stuck; the "carrie" incident
+ * needed a MANUAL restart. Stage B closes that: when the fallback fires with a
+ * tool still mid-call AND no real progress, escalate to an actual restart via
+ * the SIGTERM-PID1 path, then let the boot classifier route recovery through
+ * the ask-first `resume_watchdog_timeout` inbound (never assertive auto-resume).
+ *
+ * THE DISCRIMINATOR (the crux — do NOT key on "tool open N seconds")
+ *
+ * A healthy 20-minute research turn must NOT be killed. The honest progress
+ * signal is the turn-active marker's mtime: it is touched on every `tool_use`
+ * AND on foreground sub-agent JSONL growth (`subagent-watcher.ts`), so a turn
+ * that keeps advancing it is working; a stale mtime means work stopped.
+ *
+ *   markerAgeMs (from readTurnActiveMarkerAgeMs) small  → progress → NOT a hang
+ *   markerAgeMs large, or null (no progress signal at all) → stale → hang
+ *
+ * THE MARKER-ADVANCEMENT BLIND SPOT + THE TOOL-CLASS GUARD (review Finding A)
+ *
+ * The marker advances only on `tool_use` and sub-agent JSONL growth. A healthy
+ * long SINGLE FOREGROUND tool with no sub-agent and no interim tool_use never
+ * advances it — a 15-min foreground `Bash` build/test, a big `WebFetch`/crawl,
+ * a multi-minute research call. At the 15-min silence ceiling that turn is
+ * mid-tool with a stale marker and would be WRONGLY restarted by marker
+ * staleness alone. So we additionally protect known-long-running tool classes:
+ * if any in-flight tool is a `background`/long-fetch/research class, we do NOT
+ * restart, regardless of marker age.
+ *
+ *   RESIDUAL RISK (documented, not silently accepted): a genuine hang INSIDE a
+ *   protected long-running tool (a truly-wedged `Bash`, a `WebFetch` that never
+ *   returns) is indistinguishable from healthy long work by any signal the
+ *   gateway has — the marker cannot advance mid-single-tool either way. Those
+ *   are NOT auto-restarted here; recovery for that class relies on the tool's
+ *   own timeout, an operator `/restart`, or the ordinary state-teardown. We
+ *   choose to never false-kill a healthy long tool over catching the rare
+ *   hung-inside-a-long-tool case, because the false-kill is the common,
+ *   user-visible harm and the discriminator exists precisely to avoid it.
+ *
+ * Recovery routes through the ask-first resume path so a turn that would hang
+ * again the same way is reported to the user, not silently re-run — that is
+ * also the storm guard (see § STORM GUARD below).
+ *
+ * Pure + deterministic: the clock, the marker age, and the in-flight tool names
+ * are all injected. The gateway owns the SIGTERM side effect.
+ */
+
+/**
+ * Tool classes ported from Stage A's tool-call-deadline taxonomy. `background`
+ * covers sub-agent dispatch + long Bash; `human` covers approval waits;
+ * `standard` is everything else. Stage B additionally treats a broader set of
+ * single-foreground long tools as hang-restart-protected (see
+ * `isHangRestartProtectedTool`).
+ */
+export type ToolDeadlineClass = 'standard' | 'human' | 'background'
+
+/** Human-in-the-loop waits. */
+const HUMAN_WAIT_TOOLS = new Set<string>(['ask_user'])
+/** Sub-agent dispatch — progress is sub-agent JSONL growth. */
+const BACKGROUND_TOOLS = new Set<string>(['Task', 'Agent'])
+
+/**
+ * Classify a tool into the Stage A taxonomy. `Bash` with `run_in_background` is
+ * `background`; `Task`/`Agent` are `background`; `ask_user` is `human`.
+ */
+export function classifyToolClass(
+  toolName: string,
+  opts: { awaitingApproval?: boolean; backgroundBash?: boolean } = {},
+): ToolDeadlineClass {
+  if (opts.awaitingApproval === true) return 'human'
+  if (HUMAN_WAIT_TOOLS.has(toolName)) return 'human'
+  if (BACKGROUND_TOOLS.has(toolName)) return 'background'
+  if (toolName === 'Bash' && opts.backgroundBash === true) return 'background'
+  return 'standard'
+}
+
+/**
+ * Exact-name tools that legitimately run long as a SINGLE foreground call
+ * without touching the marker, so their staleness is not a hang signal.
+ */
+const HANG_PROTECTED_EXACT = new Set<string>([
+  'Task', 'Agent',      // sub-agent dispatch (background class)
+  'Bash',               // foreground builds/tests routinely run many minutes
+  'WebFetch', 'WebSearch',
+])
+
+/**
+ * Name substrings marking long-running fetch/crawl/research MCP tools (matched
+ * case-insensitively) — perplexity_research, deep research, site crawls, etc.
+ */
+const HANG_PROTECTED_SUBSTRINGS = ['research', 'perplexity', 'crawl', 'deep_research', 'webkite']
+
+/**
+ * True when a tool is a known-long-running / opaque-progress class that must
+ * NOT be hang-restarted on marker staleness (review Finding A). Covers the
+ * `background` class plus foreground Bash, web fetch/search, and research/crawl
+ * MCP tools. `ask_user` (`human`) is also protected — an operator wait is not a
+ * hang. See the module header § RESIDUAL RISK for the tradeoff.
+ */
+export function isHangRestartProtectedTool(toolName: string): boolean {
+  if (HANG_PROTECTED_EXACT.has(toolName)) return true
+  if (classifyToolClass(toolName) !== 'standard') return true // background / human
+  const lower = toolName.toLowerCase()
+  return HANG_PROTECTED_SUBSTRINGS.some((s) => lower.includes(s))
+}
+
+export interface HangRestartInput {
+  /** Names of the tools in flight when the fallback fired (silence-poke
+   *  snapshot). Empty ⇒ not a mid-tool fallback (ordinary teardown owns it). */
+  inFlightToolNames: string[]
+  /** Turn-active marker mtime age in ms (`readTurnActiveMarkerAgeMs`), or null
+   *  when the marker is absent/unstattable (no progress signal). */
+  markerAgeMs: number | null
+  /** Staleness ceiling: marker age at/above this counts as "no progress". Keyed
+   *  to the same TURN_HANG_SECS the boot classifier uses so the live decision
+   *  and the boot reclassification agree on what "stalled" means. */
+  stalenessThresholdMs: number
+}
+
+export interface HangRestartDecision {
+  restart: boolean
+  reason: string
+}
+
+/**
+ * Decide whether a mid-tool framework-fallback should escalate to a real
+ * restart. Pure.
+ *
+ *  - not mid-tool            → no restart (ordinary teardown path owns it)
+ *  - a protected long tool in flight → no restart (healthy long tool / sub-
+ *                              agent / research — the crux false-positive we
+ *                              must never kill; see § RESIDUAL RISK)
+ *  - marker still advancing  → no restart (real progress)
+ *  - marker stale or absent  → RESTART (genuine hang: mid-tool + no progress
+ *                              + no protected long tool that would explain it)
+ */
+export function decideHangRestart(input: HangRestartInput): HangRestartDecision {
+  if (input.inFlightToolNames.length === 0) return { restart: false, reason: 'not-mid-tool' }
+  // Finding A: never restart while a known-long-running tool is in flight — a
+  // stale marker is EXPECTED for a single long foreground tool.
+  const protectedName = input.inFlightToolNames.find(isHangRestartProtectedTool)
+  if (protectedName != null) {
+    return { restart: false, reason: `protected-long-tool:${protectedName}` }
+  }
+  // A working turn keeps touching the marker (tool_use + sub-agent JSONL
+  // growth), so a SMALL non-null age means real progress.
+  if (input.markerAgeMs != null && input.markerAgeMs < input.stalenessThresholdMs) {
+    return { restart: false, reason: 'marker-advancing' }
+  }
+  return { restart: true, reason: 'mid-tool-marker-stale' }
+}
+
+/** Default staleness ceiling (ms) — mirrors the watchdog's TURN_HANG_SECS=300. */
+export const DEFAULT_HANG_STALENESS_MS = 300_000
+
+/**
+ * Resolve the staleness ceiling from the environment, keyed to the SAME
+ * `TURN_HANG_SECS` the boot classifier reads, so a live kill and the boot
+ * reclassification agree on "stalled". Blank/garbage/non-positive → default.
+ */
+export function hangStalenessMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.TURN_HANG_SECS
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_HANG_STALENESS_MS
+  return Math.floor(n * 1000)
+}
+
+/**
+ * § STORM GUARD (review Finding B)
+ *
+ * There is deliberately NO restart cooldown here. A cooldown could only engage
+ * if two hang-restarts fired close together, but two mid-tool framework
+ * fallbacks are >= the 15-min silence-defer ceiling apart (they only fire after
+ * that ceiling), so a sub-15-min cooldown can never engage on the organic path
+ * — a dead guard giving false confidence. The REAL storm guard is the ask-first
+ * `resume_watchdog_timeout` recovery: after a hang-restart the agent does NOT
+ * auto-resume the wedged work — it reports to the user and asks — so the same
+ * hang cannot immediately recur without fresh human action. That is sufficient
+ * and self-documenting; a persisted cooldown file is not needed.
+ */

package/telegram-plugin/gateway/liveness-wiring.ts

@@ -24,7 +24,8 @@ import { emitRuntimeMetric } from '../runtime-metrics.js'
 import { logStreamingEvent } from '../streaming-metrics.js'
 import { clearSilentEndState } from '../silent-end.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
-import { removeTurnActiveMarker } from './turn-active-marker.js'
+import { removeTurnActiveMarker, readTurnActiveMarkerAgeMs } from './turn-active-marker.js'
+import { decideHangRestart } from './hang-restart-decision.js'
 import { recordTurnEnd } from '../registry/turns-schema.js'
 import { hostdGetStatusOnce } from './hostd-dispatch.js'
 import { formatUpdateStatusLine } from './update-status-line.js'
@@ -60,6 +61,7 @@ export function buildSilencePokeOptions(deps: LivenessWiringDeps): Parameters<ty
     trackRedeliveredInbound,
     closeActivityLane,
     closeProgressLane,
+    hangRestart,
   } = deps
 
   return {
@@ -160,6 +162,38 @@ export function buildSilencePokeOptions(deps: LivenessWiringDeps): Parameters<ty
       return
     }
 
+    // Stage B: escalate a mid-tool hang to a REAL restart. The fallback fires
+    // here with a tool still in flight only after silence crossed the 15-min
+    // defer ceiling (isLegitimatelyWorking held it that long). The honest
+    // hang/health discriminator is the turn-active marker's mtime age: a healthy
+    // turn keeps advancing it (tool_use + sub-agent JSONL growth), a true hang
+    // lets it go stale. A known-long-running tool in flight (Task/Agent/Bash/
+    // WebFetch/research) is protected regardless of marker age — a single long
+    // foreground tool legitimately can't advance the marker (Finding A). Only a
+    // stale (or absent) marker with no protected long tool triggers the
+    // SIGTERM-PID1 restart; the boot classifier then routes recovery through the
+    // ask-first resume_watchdog_timeout inbound. We return BEFORE the state-
+    // teardown so the turn-active marker survives for the boot reclassification.
+    if (hangRestart != null && ctx.inFlightTools.length > 0) {
+      const markerAgeMs = readTurnActiveMarkerAgeMs(STATE_DIR)
+      const inFlightToolNames = ctx.inFlightTools.map((t) => t.name)
+      const decision = decideHangRestart({
+        inFlightToolNames,
+        markerAgeMs,
+        stalenessThresholdMs: hangRestart.stalenessThresholdMs,
+      })
+      process.stderr.write(
+        `telegram gateway: [hang-watchdog] fallback mid-tool chat=${ctx.chatId} ` +
+        `thread=${ctx.threadId ?? '-'} silence_ms=${ctx.silenceMs} ` +
+        `tools=${inFlightToolNames.join(',')} marker_age_ms=${markerAgeMs ?? 'null'} ` +
+        `restart=${decision.restart} reason=${decision.reason}\n`,
+      )
+      if (decision.restart) {
+        hangRestart.request(decision.reason, markerAgeMs ?? ctx.silenceMs)
+        return
+      }
+    }
+
     // Deterministic in-flight update status (klanker incident). If this
     // gateway dispatched an update_apply that's still running, the
     // recurring framework fallback carries hostd's REAL phase + elapsed

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

@@ -104,6 +104,19 @@ export function writeSessionModelFile(
   if (!isValidModelArg(model)) {
     throw new Error(`refusing to persist non-canonical session model token: ${JSON.stringify(model)}`)
   }
+  // A FRESH carrier gets a FRESH retry budget: clear any bounded-retry counter
+  // left over from a prior carrier's boots. Without this, an orphan counter
+  // survives the whole session on a healthy snapshot-apply boot (the apply
+  // branch re-writes the live counter AFTER the gateway's healthy-boot consume
+  // already deleted it), gets snapshotted alongside the NEW carrier at the next
+  // boot, and burns the new override's retry budget from a stale count — three
+  // such sessions in a row and a perfectly healthy /model is refused with a
+  // false "did not reach a healthy boot after 3 attempts" revert.
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
+  } catch {
+    /* best-effort — worst case is a stale count, bounded and non-fatal */
+  }
   atomicWrite(
     join(agentDir, SESSION_MODEL_FILE),
     serializeSessionModel({ model, configuredDefaultAtWrite, ts: Date.now() }),

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

@@ -2018,6 +2018,23 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           // represent. The delivery closes the obligation + records dedup, so
           // the represent and a late reply-tool retry are both suppressed —
           // captured-prose delivery and represent are mutually exclusive.
+          // Capture-divergence corner (duplicate-message fix): when this is a
+          // ZERO-reply silent-end AND the gateway's OWN capture came up empty
+          // (so `decideTurnFlush` had nothing to flush — its 'empty-text'
+          // skip), the captured-prose bridge is the ONLY delivery machine
+          // left. The Stop hook scanned the transcript and DID find the
+          // model's short trailing answer, persisting it as `pendingText`. In
+          // that corner the 200-char substance floor would wrongly drop a
+          // legitimately-short answer that no other machine can deliver, so
+          // lower the floor to 1. This is scoped tightly: only when the model
+          // never called reply (`replyCalled === false`) AND the gateway
+          // captured nothing — the interim-ack case (replyCalled) keeps the
+          // full 200 floor (a short closer after a real reply is not a dropped
+          // answer, and the hook already refuses to persist <200 there).
+          const gatewayCapturedEmpty =
+            turn.capturedText.join('\n\n').trim().length === 0
+          const proseMinChars =
+            !turn.replyCalled && gatewayCapturedEmpty ? 1 : CAPTURED_PROSE_MIN_CHARS
           const proseDecision = CAPTURED_PROSE_DELIVERY_ENABLED
             ? decideCapturedProseDelivery({
                 turnKey: tKey,
@@ -2025,7 +2042,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
                 // belong to THIS turn, not a stale carryover from a prior turn
                 // on the same chat/thread (tKey is not per-turn unique).
                 turnId: turn.turnId,
-                minChars: CAPTURED_PROSE_MIN_CHARS,
+                minChars: proseMinChars,
               })
             : { deliver: false as const, reason: 'no-state' as const }
           if (proseDecision.deliver && proseDecision.text != null) {

package/telegram-plugin/gateway/turn-active-marker.ts

@@ -1,26 +1,38 @@
 /**
  * Turn-active liveness marker (#412).
  *
- * Writes `<STATE_DIR>/turn-active.json` on turn_start, touches its mtime
- * on every tool_use, removes it on turn_complete. The watchdog
- * (bin/bridge-watchdog.sh) reads the mtime: if the file exists AND its
- * mtime is older than TURN_HANG_SECS (default 300s = 5min), the agent
- * is wedged mid-turn and the watchdog restarts.
+ * Writes `<STATE_DIR>/turn-active.json` on turn_start, touches its mtime on
+ * every tool_use AND (via the subagent-watcher, #501) on foreground sub-agent
+ * JSONL growth, removes it on turn_complete. The mtime is therefore "ms since
+ * last observable progress": it advances while a turn — even a long one running
+ * one big tool or a sub-agent — is genuinely working, and goes stale only when
+ * work stops (a wedge).
  *
- * Why this exists: PR #410 raised the journal-silence detector to 4000s
- * to kill false positives on chat-cadence agents that legitimately
- * idle for hours between turns. That left a gap — Stop-hook deadlocks
- * (the original failure mode #116 tracked) are no longer caught under
- * default thresholds.
+ * Why this exists: PR #410 raised the journal-silence detector to 4000s to kill
+ * false positives on chat-cadence agents that legitimately idle for hours
+ * between turns. That left a gap — Stop-hook deadlocks (the original failure
+ * mode #116 tracked) are no longer caught under default thresholds. The
+ * distinguisher is "in-turn-and-silent" vs "between-turns-and-silent": the
+ * former is a wedge, the latter is healthy idle. This marker exists exactly
+ * during in-turn windows, so its staleness uniquely indicates the wedge.
  *
- * The distinguisher is "in-turn-and-silent" vs "between-turns-and-silent":
- * the former is a wedge, the latter is healthy idle. This marker exists
- * exactly during in-turn windows, so its staleness uniquely indicates
- * the wedge.
+ * WHO CONSUMES THE STALENESS (contract corrected — the historical
+ * `bin/bridge-watchdog.sh` bash watchdog this header once named was never
+ * committed to the repo; do not reintroduce a reference to it):
  *
- * Pure file I/O. The actual hang-detection-and-restart loop lives in the
- * bash watchdog, where it composes with the existing
- * Restart=on-failure / journal-silence / bridge-disconnect detectors.
+ *   - The gateway BOOT classifier (`markOrphanedWithTimeoutClassification` in
+ *     gateway.ts): on restart, a marker whose mtime is older than TURN_HANG_SECS
+ *     (default 300s) reclassifies the orphaned turn as `timeout`, routing the
+ *     next session to the ask-first `resume_watchdog_timeout` inbound.
+ *   - The LIVE Stage B hang-restart (`hang-restart-decision.ts`, consulted from
+ *     the silence-poke framework fallback): a mid-tool fallback with a stale
+ *     marker escalates to a real SIGTERM-PID1 restart. `readTurnActiveMarkerAgeMs`
+ *     below is the shared read.
+ *   - The obligation / phantom-turn sweeps (`readTurnActiveMarkerAgeMs`,
+ *     `effectiveTurnAgeMs`): a small age means work is still in flight, so a
+ *     "did I miss this?" re-send is suppressed.
+ *
+ * Pure file I/O; the mtime is the honest cross-process progress signal.
  */
 
 import {

package/telegram-plugin/gateway/worker-feed-dispatch.ts

@@ -40,6 +40,145 @@ export function handleWorkerResume(
   log(`telegram gateway: worker ${agentId} card RE-SURFACED — resumed via SendMessage after a genuine terminal (issue #3373)`)
 }
 
+/**
+ * Worker-feed origin-race defer decision (issue: DM-misrouted worker card).
+ *
+ * The gateway picks a worker card's destination on the FIRST progress tick of
+ * a new sub-agent. That tick can beat the async `jsonl_agent_id` backfill that
+ * links the sub-agent's registry row to its origin turn (retried ~every 3s).
+ * Until the link lands, origin resolution returns null and the gateway's
+ * `resolveWorkerFeedChat` hard-falls back to the owner DM — CREATING the card
+ * there. The origin (supergroup + forum topic) resolves ~3s later, but the DM
+ * card already exists and stays the visible one.
+ *
+ * Decision: DEFER card creation while the agent is not yet linked to its
+ * origin AND no card exists yet for it. The subagent-watcher re-fires within
+ * seconds; once the backfill completes the origin resolves and the card is
+ * created in the correct chat+topic. Only CARD CREATION is deferred — if a
+ * card already exists, updates always proceed (`defer:false`). A bounded
+ * counter caps the wait: after `maxDeferrals` unlinked ticks (pathological
+ * backfill failure) it stops deferring so active work always gets a card.
+ *
+ * Pure so the seam is unit-testable — see worker-feed-dispatch.test.ts. The
+ * gateway must never inline this decision again.
+ */
+export function decideWorkerFeedOriginDefer(input: {
+  /** True once `resolveSubagentOriginChat` returns a chat (row linked). */
+  originResolved: boolean
+  /** True if the feed already has a posted message for this worker. */
+  cardExists: boolean
+  /** Consecutive prior deferrals for this agent (0 on the first tick). */
+  priorDeferrals: number
+  /** Max consecutive deferrals before painting anyway. */
+  maxDeferrals: number
+}): { defer: boolean; deferrals: number } {
+  const { originResolved, cardExists, priorDeferrals, maxDeferrals } = input
+  // A card already exists, or the origin has resolved: never defer.
+  if (originResolved || cardExists) return { defer: false, deferrals: 0 }
+  const deferrals = priorDeferrals + 1
+  // Bounded: stop deferring once we've waited long enough for the backfill.
+  if (deferrals >= maxDeferrals) return { defer: false, deferrals }
+  return { defer: true, deferrals }
+}
+
+/**
+ * The FULL worker-feed destination decision for a single onProgress tick,
+ * extracted verbatim from the gateway's inline `onProgress` block (issue
+ * #3460). It folds two concerns that the gateway used to run inline:
+ *
+ *  1. the origin-race defer choice (`decideWorkerFeedOriginDefer`), and
+ *  2. the chat/thread RESOLUTION the gateway's `resolveWorkerFeedChat`
+ *     performed (origin chat → fleet chat / stamp-turn fallback → owner DM),
+ *     including the exhausted-defer stamp-turn forum-thread carry (#3458).
+ *
+ * Returning a plain decision object lets the gateway keep only a thin
+ * delegation (defer-map bookkeeping + the two audit logs + the feed.update)
+ * and gives this whole path REAL regression coverage — the test drives THIS
+ * function, the same code the gateway runs, instead of a hand-rolled replica.
+ *
+ * Pure and side-effect-free: the two audit-log side effects the gateway used
+ * to emit inline (`exhausted`, `ownerDmFallback`) are returned as flags so the
+ * caller performs them against its module-level state. Behavior — routing — is
+ * identical to the prior inline path; only the seam moved.
+ *
+ * Precedence for a PAINT (mirrors `resolveWorkerFeedChat`):
+ *   origin chat (when resolved, non-empty) → fleet chat, else stamp-turn chat
+ *   when no fleet chat is configured (carrying the stamp-turn forum topic) →
+ *   owner DM (durable floor). Never returns an empty chat for a paint unless
+ *   every source is empty.
+ */
+export type WorkerFeedDestination =
+  | { action: 'defer'; deferrals: number }
+  | {
+      action: 'paint'
+      chatId: string
+      threadId: number | undefined
+      /** New consecutive-deferral count to persist (0 once painting resumes). */
+      deferrals: number
+      /** True when painting only because the bounded defer cap was hit and the
+       *  origin never linked — the gateway logs the "never linked" audit line. */
+      exhausted: boolean
+      /** True when the paint fell all the way to the owner DM (origin unresolved
+       *  AND no fleet/stamp chat) — the gateway logs the once-per-agent misroute. */
+      ownerDmFallback: boolean
+    }
+
+export function decideWorkerFeedDestination(input: {
+  /** Resolved origin chat/topic (`resolveSubagentOriginChat`), or null if the
+   *  `jsonl_agent_id` backfill hasn't linked the row to its origin turn yet. */
+  origin: { chatId: string; threadId?: number } | null
+  /** True if the feed already has a posted message for this worker. */
+  cardExists: boolean
+  /** Consecutive prior deferrals for this agent (0 on the first tick). */
+  priorDeferrals: number
+  /** Max consecutive deferrals before painting anyway. */
+  maxDeferrals: number
+  /** The gateway's outer `fleetChatId` (may be empty). */
+  fleetChatId: string
+  /** Live turn's chat (`stampTurn.sessionChatId`) — the stamp-turn fallback
+   *  used only when no fleet chat is configured. */
+  stampChatId?: string
+  /** Live turn's forum topic (`stampTurn.sessionThreadId`), carried on the
+   *  stamp-turn fallback so an exhausted-defer paint lands in the origin
+   *  topic, not General (#3458). */
+  stampThreadId?: number
+  /** Owner DM chat id (`loadAccess().allowFrom[0]`) — the durable floor. */
+  ownerDm: string
+}): WorkerFeedDestination {
+  const { origin, cardExists, priorDeferrals, maxDeferrals, fleetChatId, stampChatId, stampThreadId, ownerDm } = input
+  const originResolved = origin != null
+  const { defer, deferrals } = decideWorkerFeedOriginDefer({
+    originResolved,
+    cardExists,
+    priorDeferrals,
+    maxDeferrals,
+  })
+  if (defer) return { action: 'defer', deferrals }
+  // Painting: exhausted-defer iff we're painting despite no origin and no card.
+  const exhausted = !originResolved && !cardExists
+  // Prefer the live turn's chat/topic over the owner DM when we must fall back
+  // (a misroute at least lands near the work) — only when NO fleet chat is set.
+  const usingStampFallback = fleetChatId.length === 0
+  const workerFleetChatId = usingStampFallback ? stampChatId ?? fleetChatId : fleetChatId
+  const fallbackThreadId = usingStampFallback ? stampThreadId : undefined
+  // resolveWorkerFeedChat precedence:
+  if (origin != null && origin.chatId.length > 0) {
+    return { action: 'paint', chatId: origin.chatId, threadId: origin.threadId, deferrals, exhausted, ownerDmFallback: false }
+  }
+  if (workerFleetChatId.length > 0) {
+    return { action: 'paint', chatId: workerFleetChatId, threadId: fallbackThreadId, deferrals, exhausted, ownerDmFallback: false }
+  }
+  const ownerDmFallback = origin == null && workerFleetChatId.length === 0 && ownerDm.length > 0
+  return {
+    action: 'paint',
+    chatId: ownerDm,
+    threadId: origin?.threadId ?? fallbackThreadId,
+    deferrals,
+    exhausted,
+    ownerDmFallback,
+  }
+}
+
 export interface WorkerFeedDispatch {
   /** True when the sub-agent was dispatched with `run_in_background: true`. */
   isBackground: boolean

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -58,7 +58,13 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 
-import { scanTurnForFinalReply } from './silent-end-scan.mjs'
+import {
+  scanTurnForFinalReply,
+  decideStopHookDisposition,
+  isTurnFlushSafetyEnabledEnv,
+  isCapturedProseDeliveryEnabledEnv,
+  isGatewayHeartbeatFresh,
+} from './silent-end-scan.mjs'
 
 // MUST stay in sync with SILENT_END_MAX_RETRIES in telegram-plugin/silent-end.ts
 // (this hook is a standalone .mjs and can't import the TS module).
@@ -77,6 +83,54 @@ function getStateDir() {
   return process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 }
 
+/**
+ * Build the state-file payload the gateway reads back: carries `turnKey` /
+ * `chatId` / `threadId` / per-turn `turnId` nonce and the Option-A
+ * `pendingText` bridge, with the given `retryCount`. Stale carryover values
+ * from the prior on-disk state (`base`) are explicitly dropped when THIS turn
+ * has no derivable nonce / no deliverable prose.
+ *
+ * @param {object} base   Prior on-disk state (spread as a starting point).
+ * @param {ReturnType<import('./silent-end-scan.mjs').scanTurnForFinalReply>} decision
+ * @param {number} retryCount
+ */
+function buildNextState(base, decision, retryCount) {
+  const next = { ...base, retryCount, timestamp: Date.now() }
+  if (decision.turnKey) {
+    next.turnKey = decision.turnKey
+    next.chatId = decision.chatId
+    if (decision.threadId != null) next.threadId = decision.threadId
+    if (decision.turnId) next.turnId = decision.turnId
+    else delete next.turnId
+  } else {
+    delete next.turnId
+  }
+  if (typeof decision.pendingText === 'string' && decision.pendingText.length > 0) {
+    next.pendingText = decision.pendingText
+  } else {
+    delete next.pendingText
+  }
+  return next
+}
+
+/**
+ * Persist the elected state file (single-writer election allow path).
+ * retryCount is left UNCHANGED (this is a hand-off to the gateway's delivery
+ * machine, not a re-prompt). Fail-open on write error — an allow never loops.
+ *
+ * @param {string} statePath
+ * @param {object} base
+ * @param {ReturnType<import('./silent-end-scan.mjs').scanTurnForFinalReply>} decision
+ */
+function writeElectedState(statePath, base, decision) {
+  const retryCount = typeof base.retryCount === 'number' ? base.retryCount : 0
+  try {
+    writeFileSync(statePath, JSON.stringify(buildNextState(base, decision, retryCount)), 'utf8')
+  } catch (err) {
+    process.stderr.write(`[silent-end-interrupt] failed to write elected state file: ${err.message}\n`)
+  }
+}
+
 function main() {
   const raw = readStdin().trim()
   if (!raw) process.exit(0)
@@ -136,6 +190,34 @@ function main() {
 
   const retryCount = typeof state.retryCount === 'number' ? state.retryCount : 0
 
+  // ── Single-writer election (duplicate-message fix) ────────────────
+  // On a would-BLOCK scan, ALLOW the stop (while still writing the state
+  // file so the gateway's delivery machines have their input) IFF a
+  // gateway delivery machine is PROVABLY going to deliver the trailing
+  // prose. Otherwise BLOCK exactly as today. See
+  // `decideStopHookDisposition` in silent-end-scan.mjs for the four
+  // never-drop gates. This eliminates the double-send: the gateway flush
+  // / captured-prose bridge is the single writer; the hook no longer
+  // re-prompts a reworded reply that defeats the exact-match dedup.
+  const disposition = decideStopHookDisposition({
+    scan: decision,
+    retryCount,
+    turnFlushSafetyEnabled: isTurnFlushSafetyEnabledEnv(process.env),
+    capturedProseDeliveryEnabled: isCapturedProseDeliveryEnabledEnv(process.env),
+    gatewayLive: isGatewayHeartbeatFresh(stateDir),
+  })
+  if (disposition.action === 'allow-elected') {
+    // Persist the state file (turnKey / turnId / pendingText) so the
+    // gateway's turn-end path delivers the answer — retryCount stays at 0
+    // (this is NOT a re-prompt, it's a hand-off to the single writer).
+    writeElectedState(statePath, state, decision)
+    process.stderr.write(
+      `[silent-end-interrupt] single-writer election ALLOWED stop ` +
+        `(scan=${decision.reason} elect=${disposition.reason}) — gateway will deliver\n`,
+    )
+    process.exit(0)
+  }
+
   if (retryCount >= MAX_RETRIES) {
     // Budget spent. Let the session end so the gateway's
     // `silent-end.ts:recordUndeliveredTurnEnd` path delivers the
@@ -161,41 +243,10 @@ function main() {
   // doubles the effective re-prompt budget vs. the design. With turnKey
   // present (same chatKey shape the gateway uses), the match succeeds
   // and the budget is honored.
-  const nextState = {
-    ...state,
-    retryCount: retryCount + 1,
-    timestamp: Date.now(),
-  }
-  if (decision.turnKey) {
-    nextState.turnKey = decision.turnKey
-    nextState.chatId = decision.chatId
-    if (decision.threadId != null) {
-      nextState.threadId = decision.threadId
-    }
-    // Per-turn nonce (Finding 3, #3228). The gateway requires this to match
-    // the live turn's `turnId` before delivering `pendingText`, so a stale
-    // record left over from a prior turn on the same chat/thread can never
-    // deliver a previous turn's answer on a later one. Explicitly drop a
-    // carried-over `turnId` from the spread `...state` when THIS turn has no
-    // derivable nonce, so an old value never lingers.
-    if (decision.turnId) nextState.turnId = decision.turnId
-    else delete nextState.turnId
-  } else {
-    delete nextState.turnId
-  }
-  // Option A transcript-prose bridge: when the scan isolated a substantive
-  // final answer the model wrote as plain text but never sent through the
-  // reply tool, persist it so the gateway's turn-end path can deliver it
-  // directly on the first silent-end (instead of relying on this hook's
-  // re-prompt / the obligation represent to eventually recover it). The
-  // gateway reads this field back out of the same state file. Explicitly
-  // clear a stale carryover value from a prior turn's spread `...state` when
-  // THIS turn has no deliverable prose, so an old answer is never re-sent.
-  if (typeof decision.pendingText === 'string' && decision.pendingText.length > 0) {
-    nextState.pendingText = decision.pendingText
-  } else {
-    delete nextState.pendingText
-  }
+  //
+  // Per-turn nonce (Finding 3, #3228) and the Option-A `pendingText` bridge
+  // are plumbed by `buildNextState`.
+  const nextState = buildNextState(state, decision, retryCount + 1)
   try {
     writeFileSync(statePath, JSON.stringify(nextState), 'utf8')
   } catch (err) {