switchroom 0.19.4 → 0.19.6

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/outbound-send-path.ts

@@ -56,9 +56,10 @@ import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
 import {
   decideSupersedeCorrection,
   flushedAnswerMatchesReply,
+  DEFAULT_SUPERSEDE_TTL_MS,
   type FlushedTurnSupersedeRegistry,
 } from '../flushed-turn-supersede.js'
-import { decideAnswerLatchSuppression } from '../reply-owner-resolve.js'
+import { decideAnswerLatchSuppression, type ReplyOwnerTier } from '../reply-owner-resolve.js'
 import { deriveTelegraphTitle } from '../telegraph.js'
 import {
   mintVoiceOnDemandToken,
@@ -658,7 +659,7 @@ export interface SendReplyGatewayDeps {
   assertSendable(f: string): void
   statusKey(chatId: string, threadId?: number | null): string
   streamKey(chatId: string, threadId?: number | null): string
-  resolveReplyOwnerTurn(liveTurn: CurrentTurn | null, chatId: string, args: Record<string, unknown>): CurrentTurn | null
+  resolveReplyOwnerTurn(liveTurn: CurrentTurn | null, chatId: string, args: Record<string, unknown>): { turn: CurrentTurn | null; tier: ReplyOwnerTier }
   findTurnByOriginId(originTurnId: string | null | undefined): CurrentTurn | null
   findTurnByQuotedMessageId(chatId: string, replyTo: unknown): CurrentTurn | null
   resolveAnswerThreadWithLog(
@@ -671,6 +672,7 @@ export interface SendReplyGatewayDeps {
   ): number | undefined
   resolveThreadId(chatId: string, explicit?: string | number | null): number | undefined
   getLatestInboundMessageId(chatId: string, threadId: number | null): number | null | undefined
+  getLastSubagentHandbackAt(chatId: string): number | null
   recordOutbound(rec: {
     chat_id: string
     thread_id: number | null
@@ -735,7 +737,7 @@ export async function sendReply(
     statusKey, streamKey,
     resolveReplyOwnerTurn, findTurnByOriginId, findTurnByQuotedMessageId,
     resolveAnswerThreadWithLog, resolveThreadId,
-    getLatestInboundMessageId, recordOutbound,
+    getLatestInboundMessageId, getLastSubagentHandbackAt, recordOutbound,
     emissionAuthorityFor, clearActivitySummary,
     startTypingLoop, stopTypingLoop, logOutbound,
     closeObligationOnSubstantiveReply, finalizeStatusReaction,
@@ -874,18 +876,56 @@ export async function sendReply(
     // double-send). The quoted / latest-ended recoveries are precisely what the
     // router already did for the same reply, so unifying here makes the two
     // resolvers agree and the late-reply supersede fires by identity.
-    const ownerTurn = resolveReplyOwnerTurn(turn, chat_id, args)
+    const { turn: ownerTurn, tier: ownerTier } = resolveReplyOwnerTurn(turn, chat_id, args)
     const resolvedTurnId = ownerTurn?.turnId ?? null
-    // #3429 — pass the (normalized) reply text so the registry can apply the
-    // new-content gate: identity match + TTL alone also fits an async handback
-    // that merely resolved this flush-delivered ENDED turn as its owner via
-    // the latest-ended tier. Editing the flushed message in place with that
-    // handback's text does not re-notify client-side (Telegram edits never
-    // push) — the observed silent non-surfacing of msgs 10482/10486.
+    // #3429 — pass the (normalized) reply text so the registry CAN apply the
+    // new-content gate: identity match + TTL alone also fits a background
+    // sub-agent handback that merely resolved this flush-delivered ENDED turn as
+    // its owner via the latest-ended tier. Editing/deleting the flushed message
+    // for that handback's unrelated text is the #3429 silent client-side drop
+    // (msgs 10482/10486). But that gate ALSO declines the turn's OWN reworded
+    // late reply (model narrated → flushed → fired `reply` with a paraphrase),
+    // which is the dominant real duplicate (agent:marko 2026-07-20: 11/11
+    // declines were own-replies, turns #1177/#1182/#1201 double-sent). So we
+    // BYPASS the content gate ONLY when the reply is confidently the flushed
+    // turn's OWN answer. The primary, deterministic signal is the absence of a
+    // background sub-agent handback that could own this reply: the gateway
+    // records when it synthesizes a `subagent_handback` inbound per chat, and if
+    // NONE was enqueued for this chat AFTER the flushed turn ended within the
+    // supersede TTL, the reply is that turn's own answer → supersede regardless
+    // of a model rewording (closes the DM default-reply duplicate, where every
+    // own-reply resolves via the latest-ended tier).
+    //
+    // MUST-FIX 1 (silent-data-loss): the owner-resolution `quoted` / `origin`
+    // tiers are derived from MODEL-SUPPLIED args (`args.reply_to` /
+    // `args.origin_turn_id`), so a background handback turn can STEER them —
+    // pass `reply_to = <the user's original msg id>` and it resolves the PRIOR
+    // flushed turn via `quoted`, which used to force the bypass and silently
+    // edit-over that turn's delivered answer (#3429-class, model-steerable). So
+    // a positive tier NEVER overrides an in-window handback; only the
+    // FRAMEWORK-owned `live` tier (the live `currentTurn`, not model-derived,
+    // and structurally unable to collide with an ended turn's flush record —
+    // `decideSupersede` requires same turnId) may bypass a handback window.
+    //
+    // The content gate is therefore kept whenever a handback WAS enqueued in the
+    // window (any non-live tier): the late reply might BE that handback, so
+    // genuinely-new content sends fresh (two messages, #3429 preserved).
+    // Concurrency note: a case-A own reply coinciding with an unrelated
+    // background handback in the same ≤TTL window degrades to today's behaviour
+    // (two messages) — safe (never a silent drop/edit), just not collapsed.
+    const ownerEndedAt = ownerTurn?.endedAt ?? null
+    const handbackAt = getLastSubagentHandbackAt(chat_id)
+    const now = Date.now()
+    const handbackCouldOwnReply =
+      handbackAt != null &&
+      ownerEndedAt != null &&
+      handbackAt > ownerEndedAt &&
+      now - handbackAt <= DEFAULT_SUPERSEDE_TTL_MS
+    const replyIsOwnAnswer = ownerTier === 'live' || !handbackCouldOwnReply
     const decision = flushedTurnSupersede.take(
       chat_id,
       replyThreadId,
-      { liveTurnId: resolvedTurnId, replyText: text, now: Date.now() },
+      { liveTurnId: resolvedTurnId, replyText: text, positiveAttribution: replyIsOwnAnswer, now },
     )
     if (decision.supersede) {
       process.stderr.write(

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -79,6 +79,16 @@ export interface PendingInboundBufferOptions {
    * never breaks the push hot path.
    */
   onEvict?: (agent: string, evicted: InboundMessage) => void
+  /**
+   * fix/backstop-duplicate-reply MUST-FIX 2 — called on every push of a
+   * `subagent_handback` envelope (live synthesis AND boot-replay re-push),
+   * carrying the envelope's `chatId` and its own `ts` (ms). The gateway wires
+   * this to the per-chat subagent-handback marker so the supersede path can tell
+   * a flushed turn's own late reply from a background handback attributed to it
+   * — INCLUDING after a restart, where the only handback push is the replay.
+   * Best-effort: a throw here never breaks the push hot path.
+   */
+  onHandbackEnqueue?: (chatId: string, ts: number) => void
 }
 
 /**
@@ -342,6 +352,23 @@ export function createPendingInboundBuffer(
         }
       }
       q.push(msg)
+      // fix/backstop-duplicate-reply MUST-FIX 2 — stamp the subagent-handback
+      // marker at THIS chokepoint, not at the live onFinish enqueue site alone.
+      // Every handback enqueue funnels through here — the live synthesis push
+      // AND the boot-replay re-push of un-acked spooled inbounds — so stamping
+      // here (rather than only at the live site) means a handback replayed after
+      // a restart still populates the marker. Otherwise the Map is empty
+      // post-boot and a replayed handback's late reply bypasses the #3429
+      // content gate → silent edit-over-answer. Uses the envelope's own `ts`
+      // (ms, `Date.now()`-derived at synthesis) so the marker reflects when the
+      // handback actually happened, not the replay moment. Best-effort.
+      if (msg.meta?.source === 'subagent_handback' && opts.onHandbackEnqueue != null) {
+        try {
+          opts.onHandbackEnqueue(msg.chatId, msg.ts)
+        } catch {
+          /* marker stamp is best-effort; never break the push hot path */
+        }
+      }
       // Durable record FIRST-class to the in-memory queue: spool BEFORE
       // returning, regardless of the cap eviction above — an entry the
       // in-memory cap drops still survives in the spool (boot-replayed /

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/subagent-handback-marker.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-chat marker of the most recent gateway-synthesized `subagent_handback`
+ * enqueue (fix/backstop-duplicate-reply).
+ *
+ * A BACKGROUND sub-agent completion is a GATEWAY-SYNTHESIZED event, not model
+ * output: when a background worker terminates the gateway wakes the agent with a
+ * `subagent_handback` inbound. Recording WHEN one was enqueued, per chat, is the
+ * ONE deterministic signal that distinguishes the two late-reply cases that both
+ * resolve a flush-delivered ENDED turn via the latest-ended tier — the case the
+ * owner-resolution tier alone cannot separate (a DM late reply has no
+ * live/origin/quoted attribution, so both land on latest-ended):
+ *
+ *   - CASE A — the flushed turn's OWN reworded reply landing late. NO
+ *     `subagent_handback` was enqueued for this chat after the turn ended, so the
+ *     reply is that turn's own answer → the supersede path collapses the
+ *     provisional flush REGARDLESS of the model's rewording (closes the #3429
+ *     reworded-duplicate regression: agent:marko 2026-07-20, turns
+ *     #1177/#1182/#1201 double-sent).
+ *   - CASE B — a background handback attributed to that ended turn. A
+ *     `subagent_handback` WAS enqueued after the turn ended and within the
+ *     supersede TTL, so the late reply might BE it → keep the #3429 content gate
+ *     and send fresh (two messages), never silently edit/delete the flushed
+ *     answer.
+ *
+ * One entry per chat (overwritten on each enqueue), so bounded by chat count. No
+ * clock reads beyond the caller-supplied `now`; the gateway wires the actual
+ * enqueue site and the supersede-path read. Deterministic — keyed on a
+ * gateway-emitted event, never on model discipline (Ken's controls-in-code rule).
+ */
+export class SubagentHandbackMarker {
+  private readonly lastAtByChat = new Map<string, number>()
+
+  /** Record that a `subagent_handback` was enqueued for `chatId` at `now` (ms). */
+  record(chatId: string, now: number): void {
+    this.lastAtByChat.set(chatId, now)
+  }
+
+  /** Wall-clock ms of the most recent handback enqueue for `chatId`, or null. */
+  lastAt(chatId: string): number | null {
+    return this.lastAtByChat.get(chatId) ?? 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 {