switchroom 0.19.4 → 0.19.6

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) {

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

@@ -55,6 +55,9 @@
 // (`done:true`) call as the qualifying one regardless of how many
 // intermediate non-final `stream_reply` calls preceded it. No gap found;
 // re-verify only if a new outbound-delivery tool is added to bridge.ts.
+import { statSync } from 'node:fs'
+import { join } from 'node:path'
+
 const REPLY_TOOLS = new Set([
   'mcp__switchroom-telegram__reply',
   'mcp__switchroom-telegram__stream_reply',
@@ -97,6 +100,68 @@ export function endsWithSilentMarker(text) {
   return SILENT_MARKER_RE.test(lines[lines.length - 1])
 }
 
+// ── Narration heuristics — ported from `turn-flush-safety.ts:198-274` ──
+//
+// Kept byte-parallel with `selectFlushDeliveryText` / `isNarrationBlock` so
+// the JOINED multi-block prose the scan persists as `pendingText` (for the
+// capture-divergence corner) matches what the gateway flush would itself have
+// delivered. The scan has no structural `followedByToolUse` provenance, so it
+// uses the opener/trailer heuristic fallback (the same branch the TS side
+// takes when the flag is absent). MUST stay in sync with the TS source; a
+// drift only affects the rare capture-empty corner, never the primary flush.
+const NARRATION_OPENER =
+  /^(let me\b|lemme\b|i'?ll\b|i will\b|i am going to\b|i'?m going to\b|i'?m about to\b|going to\b|first,?\s+(?:let me|i'?ll|i will)\b|now,?\s+(?:let me|i'?ll|i will)\b|next,?\s+(?:let me|i'?ll|i will)\b|let'?s\b)/i
+const NARRATION_TRAILER = /(?:\.{3}|…|:)\s*$/
+
+function isTrailingNarrationLine(block) {
+  const t = block.trim()
+  if (t.length === 0 || t.length >= FINAL_ANSWER_MIN_CHARS) return false
+  if (t.includes('\n')) return false
+  return NARRATION_TRAILER.test(t)
+}
+
+function isNarrationBlock(block) {
+  return NARRATION_OPENER.test(block.trimStart()) || isTrailingNarrationLine(block)
+}
+
+/**
+ * Choose the prose the captured-prose bridge should deliver from the trailing
+ * text blocks in the ZERO-reply case, mirroring `selectFlushDeliveryText`
+ * (`turn-flush-safety.ts:198-232`). `texts` are already trimmed non-empty.
+ *
+ *   - 0 blocks   → undefined (nothing to deliver).
+ *   - 1 block    → that block (the real single-block short-answer shape;
+ *                  persisted even below the substance floor so the lowered-
+ *                  floor capture-divergence corner can deliver it).
+ *   - ≥2 blocks  → strip leading narration exactly as the flush does: if EVERY
+ *                  preceding block is narration, deliver only the terminal
+ *                  block; otherwise JOIN all blocks with a paragraph break (a
+ *                  genuine multi-paragraph answer split across blocks). When
+ *                  the result is narration-only (terminal block is itself
+ *                  narration AND all preceding are narration) → undefined, so a
+ *                  pure narration run never masquerades as an answer (#3228
+ *                  Finding 2 parity).
+ *
+ * @param {string[]} texts
+ * @returns {string | undefined}
+ */
+export function selectBridgePendingText(texts) {
+  const candidates = texts.map((t) => t.trim()).filter((t) => t.length > 0)
+  if (candidates.length === 0) return undefined
+  if (candidates.length === 1) return candidates[0]
+  const answer = candidates[candidates.length - 1]
+  const preceding = candidates.slice(0, -1)
+  const allPrecedingNarration = preceding.every((b) => isNarrationBlock(b))
+  if (allPrecedingNarration) {
+    // Deliver only the terminal block — unless it too is pure narration, in
+    // which case the whole run is narration and there is no answer to bridge.
+    return isNarrationBlock(answer) ? undefined : answer
+  }
+  // A preceding block carries real content → keep the whole answer joined so a
+  // multi-block answer is never truncated to its last paragraph.
+  return candidates.join('\n\n')
+}
+
 /**
  * Predicate ported from `telegram-plugin/final-answer-detect.ts:78-83`.
  * Kept in this .mjs so the hook is fully self-contained (no TS import).
@@ -193,8 +258,16 @@ function buildTurnId(chatId, threadId, messageId) {
  *   clears the substance floor, so the gateway never re-delivers a short
  *   trailing pleasantry. Omitted entirely otherwise.
  */
-function buildBlockResult(envelope, reason, pendingText) {
+function buildBlockResult(envelope, reason, pendingText, hasTrailingProse) {
   const block = { decided: 'block', reason }
+  // Single-writer election input (#duplicate-message fix): does ANY
+  // non-empty, non-silent trailing text block exist after the last
+  // delivery event? The zero-reply election allows only when this is
+  // true — `decideTurnFlush` has no length floor, so any non-empty
+  // non-silent captured text WILL flush; but a turn with NO trailing
+  // prose at all (tool calls only) has nothing for any delivery
+  // machine to send and must keep blocking.
+  if (hasTrailingProse === true) block.hasTrailingProse = true
   if (envelope.chatId) {
     block.chatId = envelope.chatId
     block.threadId = envelope.threadId
@@ -432,6 +505,32 @@ export function scanTurnForFinalReply(jsonl) {
     substantiveBlocks.length > 0
       ? substantiveBlocks[substantiveBlocks.length - 1].text
       : undefined
+  const trailingTextBlocks = undeliveredSlice.filter(
+    (b) => b.kind === 'text' && typeof b.text === 'string' && b.text.length > 0,
+  )
+  const hasTrailingProse = trailingTextBlocks.length > 0
+  // Capture-divergence bridge (#duplicate-message fix): in the ZERO-reply
+  // case, persist the last trailing block even when no single block clears
+  // the 200-char substance floor. The gateway's flush normally delivers any
+  // non-empty captured text, but when the gateway's own capture diverged
+  // (captured empty) the captured-prose bridge is the only delivery machine
+  // left, and it reads `pendingText` — the gateway lowers `minChars` for
+  // exactly this corner (`capturedProseMinCharsFor`, silent-end.ts). The
+  // interim-ack case (`trailing-text-after-reply`) keeps the substantive
+  // floor unchanged — a short closer after a real reply is not a dropped
+  // answer.
+  //
+  // Multi-block corner (review item 3): a real answer split across ≥2
+  // individually-sub-200 blocks (e.g. two ~150-char paragraphs) would
+  // otherwise yield NO pendingText — and in the capture-divergence-empty
+  // corner (gateway `capturedText` empty → flush skips 'empty-text') the
+  // bridge would then have nothing to deliver and the hook already allowed the
+  // stop: a DROPPED ANSWER. `selectBridgePendingText` mirrors the flush's own
+  // `selectFlushDeliveryText` narration-strip/join, so the bridge delivers the
+  // joined prose (with the lowered `minChars`) instead of dropping. The #3228
+  // Finding 2 guard is preserved: a pure narration run still yields undefined.
+  const zeroReplyPendingText =
+    pendingText ?? selectBridgePendingText(trailingTextBlocks.map((b) => b.text))
 
   if (lastAllowBlockIdx === -1) {
     // No qualifying delivery/silence event anywhere in the turn.
@@ -444,7 +543,7 @@ export function scanTurnForFinalReply(jsonl) {
     if (envelope.source === 'cron') {
       return { decided: 'allow', reason: 'cron-source' }
     }
-    return buildBlockResult(envelope, 'no-final-reply', pendingText)
+    return buildBlockResult(envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse)
   }
 
   if (sawUndeliveredTextAfterAllow) {
@@ -453,8 +552,169 @@ export function scanTurnForFinalReply(jsonl) {
     // sent through a delivery tool. This is the "at least once" bug:
     // an early ack (or any qualifying reply) must not amnesty
     // everything written afterward.
-    return buildBlockResult(envelope, 'trailing-text-after-reply', pendingText)
+    return buildBlockResult(envelope, 'trailing-text-after-reply', pendingText, hasTrailingProse)
   }
 
   return { decided: 'allow', reason: lastAllowReason }
 }
+
+// ── Single-writer election (duplicate-message fix) ───────────────────
+//
+// RCA: when a turn ends with its final answer as plain transcript text,
+// TWO uncoordinated recovery paths both fire — (A) the gateway's
+// deterministic turn-end flush (`decideTurnFlush` /
+// `answer-ready-flush.ts`) delivers the captured transcript prose, AND
+// (B) this Stop hook blocks and re-prompts the model, which regenerates
+// a REWORDED reply that defeats the exact-match dedup
+// (`flushed-turn-supersede.ts` `flushedAnswerMatchesReply`). The user
+// gets two near-identical messages.
+//
+// Fix: the Stop hook is the single elector. On a would-BLOCK scan it
+// ALLOWS the stop (still persisting the state file so the gateway's
+// delivery machines have their input) IFF it can PROVE a gateway
+// delivery machine will handle the trailing prose. Every gate below
+// exists to prevent a DROP (worse than a duplicate):
+//
+//   1. deliverable trailing prose exists AND the right machine covers it
+//      - zero-reply (`no-final-reply`): ANY non-empty non-silent
+//        trailing prose — `decideTurnFlush` has no length floor and
+//        flushes any non-empty non-silent captured text. (No 200-char
+//        floor here.)
+//      - interim-ack (`trailing-text-after-reply`, replyCalled=true):
+//        ONLY the captured-prose bridge delivers there (the flush skips
+//        on reply-called), and its floor is 200 — so short trailing
+//        text after a real reply keeps BLOCKING (no duplicate exists in
+//        that case today).
+//   2. the governing delivery flag is enabled (read by the hook from
+//      its own env): zero-reply needs the turn-flush-safety flag AND
+//      the captured-prose flag (the bridge is the capture-divergence
+//      backstop when the gateway captured empty); interim-ack needs the
+//      captured-prose flag. Flag off → the machine won't fire → BLOCK.
+//   3. retryCount === 0 — a prior failed delivery must fall back to
+//      today's BLOCK, preserving the #3228 send-failure recovery net.
+//   4. gateway liveness — the gateway heartbeat file must be FRESH.
+//      Allowing into a dead gateway is the one drop worse than a
+//      duplicate; when liveness can't be established, BLOCK.
+//
+// Pure and deterministic: the hook wrapper does the IO (env read, stat,
+// state-file write) and maps this verdict to exit-0-allow vs
+// decision:block.
+
+/**
+ * @param {{
+ *   scan: ReturnType<typeof scanTurnForFinalReply>,
+ *   retryCount: number,
+ *   turnFlushSafetyEnabled: boolean,
+ *   capturedProseDeliveryEnabled: boolean,
+ *   gatewayLive: boolean,
+ * }} input
+ * @returns {{ action: 'allow-scan' | 'allow-elected' | 'block', reason: string }}
+ */
+export function decideStopHookDisposition(input) {
+  const {
+    scan,
+    retryCount,
+    turnFlushSafetyEnabled,
+    capturedProseDeliveryEnabled,
+    gatewayLive,
+  } = input
+  if (scan == null || scan.decided !== 'block') {
+    return { action: 'allow-scan', reason: `scan-${scan?.decided ?? 'unknown'}` }
+  }
+  // Gate 4 — never allow into a possibly-dead gateway.
+  if (gatewayLive !== true) {
+    return { action: 'block', reason: 'gateway-liveness-not-fresh' }
+  }
+  // Gate 3 — a retry ladder already in flight means a prior delivery
+  // attempt failed; today's BLOCK is the recovery net (#3228).
+  if (retryCount !== 0) {
+    return { action: 'block', reason: 'retry-ladder-in-flight' }
+  }
+  if (scan.reason === 'no-final-reply') {
+    // Gate 2 (zero-reply): the turn-end flush is the delivery machine;
+    // the captured-prose bridge is the capture-divergence backstop.
+    if (!turnFlushSafetyEnabled) {
+      return { action: 'block', reason: 'turn-flush-flag-disabled' }
+    }
+    if (!capturedProseDeliveryEnabled) {
+      return { action: 'block', reason: 'captured-prose-flag-disabled' }
+    }
+    // Gate 1 (zero-reply): any non-empty non-silent trailing prose.
+    if (scan.hasTrailingProse !== true) {
+      return { action: 'block', reason: 'no-trailing-prose' }
+    }
+    return { action: 'allow-elected', reason: 'flush-will-deliver' }
+  }
+  if (scan.reason === 'trailing-text-after-reply') {
+    // Gate 2 (interim-ack): only the captured-prose bridge delivers here.
+    if (!capturedProseDeliveryEnabled) {
+      return { action: 'block', reason: 'captured-prose-flag-disabled' }
+    }
+    // Gate 1 (interim-ack): the bridge's substance floor is 200 chars
+    // (CAPTURED_PROSE_MIN_CHARS, silent-end.ts). Below it the bridge
+    // will NOT deliver — keep blocking (matches today: no duplicate
+    // exists for short trailing text after a real reply).
+    if (
+      typeof scan.pendingText !== 'string' ||
+      scan.pendingText.trim().length < FINAL_ANSWER_MIN_CHARS
+    ) {
+      return { action: 'block', reason: 'short-trailing-after-reply' }
+    }
+    return { action: 'allow-elected', reason: 'bridge-will-deliver' }
+  }
+  // Unknown block reason — conservatively keep today's behaviour.
+  return { action: 'block', reason: `unrecognized-scan-reason-${scan.reason}` }
+}
+
+/**
+ * Mirror of `isTurnFlushSafetyEnabled` (`turn-flush-safety.ts:392-400`).
+ * Kept in this .mjs so the hook is self-contained (no TS import); MUST
+ * stay in sync — default ON, disabled by `0` / `false` / `off` / `no`.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isTurnFlushSafetyEnabledEnv(env) {
+  const raw = env.SWITCHROOM_TG_TURN_FLUSH_SAFETY
+  if (raw == null) return true
+  const v = raw.trim().toLowerCase()
+  return !(v === '0' || v === 'false' || v === 'off' || v === 'no')
+}
+
+/**
+ * Mirror of `CAPTURED_PROSE_DELIVERY_ENABLED` (`gateway/gateway.ts` —
+ * `SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY !== '0'`). MUST stay in sync.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isCapturedProseDeliveryEnabledEnv(env) {
+  return env.SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY !== '0'
+}
+
+// MUST stay in sync with gateway/gateway-heartbeat.ts (the hook is a
+// standalone .mjs and can't import the TS module). The gateway touches
+// the file every GATEWAY_HEARTBEAT_INTERVAL_MS (15s); freshness bound is
+// 4 intervals — conservative against scheduler jitter, small enough that
+// a dead gateway is detected before its stale heartbeat can swallow more
+// than one turn's election.
+export const GATEWAY_HEARTBEAT_FILE = 'gateway-heartbeat'
+export const GATEWAY_HEARTBEAT_FRESH_MS = 60_000
+
+/**
+ * Gate 4 IO helper: is the gateway heartbeat file fresh? Missing,
+ * unstattable, or stale ⇒ false (BLOCK — never allow into a possibly-
+ * dead gateway).
+ *
+ * @param {string} stateDir
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function isGatewayHeartbeatFresh(stateDir, now = Date.now()) {
+  try {
+    const st = statSync(join(stateDir, GATEWAY_HEARTBEAT_FILE))
+    return now - st.mtimeMs <= GATEWAY_HEARTBEAT_FRESH_MS
+  } catch {
+    return false
+  }
+}