switchroom 0.19.43 → 0.19.45

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -75,9 +75,10 @@ import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
 import {
   decideSupersedeCorrection,
   flushedAnswerMatchesReply,
-  DEFAULT_SUPERSEDE_TTL_MS,
   type FlushedTurnSupersedeRegistry,
 } from '../flushed-turn-supersede.js'
+import { HANDBACK_RECENCY_WINDOW_MS } from './subagent-handback-marker.js'
+import type { SubagentReplyAuthorityView } from './subagent-reply-authority.js'
 import {
   decideAnswerLatchSuppression,
   decideContentGateBypass,
@@ -762,6 +763,16 @@ export interface SendReplyRequest {
    *  Late writes (finalAnswerDelivered) attribute to THIS turn even if the
    *  module-scope turn rolls over mid-call. */
   turn: CurrentTurn | null
+  /** #4172 — true when the calling IPC client is NOT the main agent bridge
+   *  (`replyCallerIsForeignSession`, cron-session.ts): a Tier-1 cheap-cron
+   *  session or an unregistered client. A foreign-session reply can never be
+   *  the main session's own late answer, so the flushed-turn
+   *  supersede/bypass/latch block is skipped wholesale — it always sends
+   *  FRESH (never edits/deletes a flushed answer, never gets latch-
+   *  suppressed). Omitted/false ⇒ main-bridge caller (the gateway's
+   *  `executeReply` always passes the computed value; the default only
+   *  affects test harnesses). */
+  callerIsForeignSession?: boolean
 }
 
 /** Gateway dependencies for {@link sendReply}. Function members use method
@@ -834,6 +845,12 @@ export interface SendReplyGatewayDeps {
   resolveThreadId(chatId: string, explicit?: string | number | null): number | undefined
   getLatestInboundMessageId(chatId: string, threadId: number | null): number | null | undefined
   getLastSubagentHandbackAt(chatId: string): number | null
+  /** #4176 — gateway-observed sub-agent liveness (`subagentReplyAuthority`,
+   *  subagent-reply-authority.ts). A background `Task` sub-agent replies over
+   *  THIS bridge, so neither the #4172 caller-identity gate nor the handback
+   *  marker can see it; while one is live the content-gate bypass is refused so
+   *  a sub-agent's reply can never edit over a flushed answer. */
+  subagentReplyAuthority: SubagentReplyAuthorityView
   recordOutbound(rec: {
     chat_id: string
     thread_id: number | null
@@ -898,7 +915,7 @@ export async function sendReply(
     statusKey, streamKey,
     resolveReplyOwnerTurn, findTurnByOriginId, findTurnByQuotedMessageId,
     resolveAnswerThreadWithLog, resolveThreadId,
-    getLatestInboundMessageId, getLastSubagentHandbackAt, recordOutbound,
+    getLatestInboundMessageId, getLastSubagentHandbackAt, subagentReplyAuthority, recordOutbound,
     emissionAuthorityFor, clearActivitySummary,
     startTypingLoop, stopTypingLoop, logOutbound,
     closeObligationOnSubstantiveReply, finalizeStatusReaction,
@@ -1025,7 +1042,20 @@ export async function sendReply(
   // when the reply fits one plain-text message, and falls back to the legacy
   // delete+resend otherwise. `supersedeFlushIds` carries the ids forward.
   let supersedeFlushIds: number[] = []
-  {
+  // #4172 — caller-identity gate, BEFORE any owner attribution. A reply from a
+  // foreign session (a Tier-1 cheap-cron bridge, or an unregistered client)
+  // can never be the main session's own late/reworded answer, so it gets NO
+  // supersede authority (it must never edit/delete a flushed answer — the
+  // measured #4172 double loss), NO content-gate bypass, and NO exposure to
+  // the answer-delivered latch (which could otherwise silently swallow a cron
+  // digest landing in the flush's pre-record race window). It simply sends
+  // fresh below, leaving any flush record intact for the genuine own-replay.
+  if (req.callerIsForeignSession === true) {
+    process.stderr.write(
+      `telegram gateway: reply: foreign-session caller — supersede/latch skipped (#4172) ` +
+      `chatId=${chat_id}\n`,
+    )
+  } else {
     const replyThreadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
     // 2026-07 double-reply-on-DM fix (Part 1) — resolve the turn this reply
     // belongs to by IDENTITY, via the SAME full chain the thread-router uses
@@ -1107,11 +1137,16 @@ export async function sendReply(
     // correction only ever touches ITS OWN topic's record.
     const handbackAt = getLastSubagentHandbackAt(chat_id)
     const now = Date.now()
+    // #4174 — the handback gate-hold keeps its OWN ~60 s bound
+    // (`HANDBACK_RECENCY_WINDOW_MS`), deliberately NOT the supersede window's:
+    // this read is CHAT-WIDE, so a longer bound would hold the content gate —
+    // and re-open the reworded-own-answer visible-dup class — for every topic
+    // in a delegation-heavy chat, near-continuously. Rationale on the constant.
     const handbackCouldOwnReply =
       handbackAt != null &&
       ownerEndedAt != null &&
       handbackAt > ownerEndedAt &&
-      now - handbackAt <= DEFAULT_SUPERSEDE_TTL_MS
+      now - handbackAt <= HANDBACK_RECENCY_WINDOW_MS
     // MUST-FIX 1 (silent-data-loss, PROVEN by Fable 2026-07-21) + the 2026-07-27
     // corroboration widening — decided by the pure `decideContentGateBypass` so
     // the gateway runs the exact code the unit tests exercise. The rule, in
@@ -1135,11 +1170,27 @@ export async function sendReply(
     //                its OWN turn no longer loses the collapse it would have got
     //                by omitting the echo entirely (the observed 2026-07-27
     //                `via=origin` duplicate).
+    //
+    // #4176 — the SECOND ambiguity, which the marker structurally cannot see. A
+    // background `Task` sub-agent (the `researcher`/`reviewer` types hold the
+    // full tool set) calls `reply` over THIS bridge, mid-run: the #4172
+    // caller-identity gate sees the MAIN agent identity, and a direct tool call
+    // never traverses `pendingInboundBuffer.push`, so no handback marker is
+    // stamped either. Under the #4173 OPEN window that reply resolves the
+    // flush-ended turn at ANY age, so an unguarded bypass supersedes REGARDLESS
+    // of content and silently edits the sub-agent's message over the user's
+    // flushed answer (the review MAJOR on #4167; pre-existing on main at the
+    // 60 s TTL, extended by #4173 to the OPEN cap). Gateway-observed sub-agent
+    // liveness is the deterministic discriminator: while one is live the content
+    // gate is KEPT, so a reply that IS the flushed answer still collapses and a
+    // sub-agent's foreign content ships FRESH (visible, notifying).
+    const subagentCouldOwnReply = subagentReplyAuthority.subagentCouldOwnReply()
     const replyIsOwnAnswer = decideContentGateBypass({
       tier: ownerTier,
       resolvedTurnId,
       candidates: ownerCandidates,
       handbackCouldOwnReply,
+      subagentCouldOwnReply,
     })
     const decision = flushedTurnSupersede.take(
       chat_id,
@@ -1229,7 +1280,7 @@ export async function sendReply(
           // 2026-07-27 duplicate looked like a pure text-matcher failure and
           // took a log-archive dig to attribute to the tier restriction.
           `tier=${ownerTier} latestEnded=${JSON.stringify(ownerCandidates.latestEndedTurnId)} ` +
-          `handbackInWindow=${handbackCouldOwnReply}; sending fresh\n`,
+          `handbackInWindow=${handbackCouldOwnReply} subagentLive=${subagentCouldOwnReply}; sending fresh\n`,
         )
       }
       if (suppressByLatch) {
@@ -1248,9 +1299,10 @@ export async function sendReply(
       // content and must deliver. Byte-identical replays of THIS answer are
       // deduped by the content-keyed #546 cache at the top of this function.
       // Honest bound: the dedup TTL (60 s) is anchored at reply RECORD time,
-      // while the latest-ended owner tier's 60 s is anchored at `endedAt` —
-      // later by the reply→turn_end gap. A byte-identical replay landing >60 s
-      // after record but ≤60 s after endedAt is evicted from dedup yet still
+      // while the latest-ended owner tier's bound is the turn-completion
+      // window (#4173), anchored at the turn's OBSERVED real end — later by
+      // the reply→turn_end gap. A byte-identical replay landing >60 s after
+      // record but still inside that window is evicted from dedup yet still
       // resolves this ended turn, so it now DELIVERS as a duplicate message.
       // Conscious trade: a rare duplicate beats the silent handback drop the
       // boolean latch caused (#3426).

package/telegram-plugin/gateway/reply-owner-wiring.ts

@@ -0,0 +1,128 @@
+/**
+ * Reply owner-turn resolution WIRING (#2996 anti-inflation extraction; #4173).
+ *
+ * The pure precedence/acceptance rules live in `../reply-owner-resolve.ts`;
+ * gateway.ts holds the stateful lookups (recent-turn registry, quoted-message
+ * reverse index). This module is the seam between them: it composes the four
+ * lookups into the `ReplyOwnerCandidates` set — INCLUDING the turn-completion
+ * window bounds (#4173) — exactly once, so the supersede path, the content-gate
+ * bypass, and the tier resolution can never disagree on the candidate set.
+ *
+ * 2026-07 double-reply-on-DM fix (Part 1): this composition uses the SAME full
+ * chain the thread-router uses, so the supersede resolver can never again
+ * diverge from routing (the exact bug: supersede omitted the quoted-message and
+ * latest-ended recoveries, so a DM late reply — no live turn, no
+ * `origin_turn_id` — resolved to a null owner and its flush message was never
+ * superseded → duplicate).
+ *
+ * Precedence (first non-null wins), delegated to the pure
+ * `resolveReplyOwnerTurnId` so the exact precedence is unit-tested:
+ *   1. the live `currentTurn` passed in (null once the flush nulled the atom);
+ *   2. `findTurnByOriginId(origin_turn_id)` — the model echo;
+ *   3. `findTurnByQuotedMessageId(chat_id, reply_to)` — framework-owned quote;
+ *   4. `findLatestTurnForChat(chat_id, {endedOnly:true})` — last ENDED turn.
+ * Returns the turn atom for the winning id (so callers can read its
+ * `answerDelivered` latch), or null when every lookup missed.
+ */
+
+import {
+  resolveReplyOwnerTier,
+  resolveReplyOwnerTurnId,
+  type ReplyOwnerCandidates,
+  type ReplyOwnerTier,
+} from '../reply-owner-resolve.js'
+import {
+  SUPERSEDE_OPEN_WINDOW_CAP_MS,
+  SUPERSEDE_COMPLETED_GRACE_MS,
+} from '../flushed-turn-supersede.js'
+
+/**
+ * #4173/#4175 — the two turn-completion-window bounds, env-overridable as the
+ * operator kill-switch for the window mechanism (clamp the open cap / grace to
+ * taste; e.g. `SWITCHROOM_SUPERSEDE_OPEN_CAP_MS=60000` restores something
+ * close to the pre-#4166 60 s behaviour). Resolved HERE once — the pure
+ * modules stay env-free — and consumed by BOTH window surfaces (the gateway's
+ * `FlushedTurnSupersedeRegistry` ctor and the latest-ended owner-tier
+ * candidates below) so they can never disagree.
+ */
+export const SUPERSEDE_OPEN_CAP_MS = (() => {
+  const raw = Number(process.env.SWITCHROOM_SUPERSEDE_OPEN_CAP_MS)
+  return Number.isFinite(raw) && raw > 0 ? raw : SUPERSEDE_OPEN_WINDOW_CAP_MS
+})()
+export const SUPERSEDE_GRACE_MS = (() => {
+  const raw = Number(process.env.SWITCHROOM_SUPERSEDE_GRACE_MS)
+  return Number.isFinite(raw) && raw > 0 ? raw : SUPERSEDE_COMPLETED_GRACE_MS
+})()
+
+/** The minimal turn-atom shape this wiring reads. Structural on purpose so the
+ *  module never imports gateway.ts (no cycle); gateway's `CurrentTurn`
+ *  satisfies it. */
+export interface OwnerTurnLike {
+  turnId: string
+  endedAt: number | null
+  realEndObservedAt: number | null
+}
+
+/**
+ * Compose the owner-resolution result from the gateway's four lookups.
+ * Generic over the concrete turn atom type so gateway.ts gets its own
+ * `CurrentTurn` back without a cast.
+ */
+export function resolveReplyOwnerTurnWith<T extends OwnerTurnLike>(
+  lookups: {
+    findTurnByOriginId(originTurnId: string | null | undefined): T | null
+    findTurnByQuotedMessageId(chatId: string, replyTo: unknown): T | null
+    findLatestTurnForChat(chatId: string, opts: { endedOnly: boolean }): T | null
+    now(): number
+  },
+  liveTurn: T | null,
+  chatId: string,
+  args: Record<string, unknown>,
+): { turn: T | null; tier: ReplyOwnerTier; candidates: ReplyOwnerCandidates } {
+  const origin = lookups.findTurnByOriginId(args.origin_turn_id as string | undefined)
+  const quoted = lookups.findTurnByQuotedMessageId(chatId, args.reply_to)
+  const latestEnded = lookups.findLatestTurnForChat(chatId, { endedOnly: true })
+  const byId = new Map<string, T>()
+  // Populate lowest-precedence first so a higher tier's turn wins the id slot
+  // when two lookups resolve the same turn (they carry the same turnId anyway).
+  for (const t of [latestEnded, quoted, origin, liveTurn]) {
+    if (t != null) byId.set(t.turnId, t)
+  }
+  // F2 — bound the DESTRUCTIVE latest-ended tier to the turn-completion window
+  // (#4173) so a stale latest-ended turn can't inherit deletion authority over
+  // a newer turn's flush record. #3725: the lookup above is `endedOnly`, so
+  // `endedAt` is non-null here and the age is ALWAYS a real number — a
+  // not-yet-ended turn is no longer a candidate at all, and an explicit null
+  // age fails CLOSED downstream (as does an omitted one, since #4175).
+  const latestEndedAgeMs =
+    latestEnded?.endedAt != null ? lookups.now() - latestEnded.endedAt : null
+  // #4173 — the completion signal: null while the flush-ended turn's REAL
+  // turn_end has not been observed (window OPEN — acceptance falls to the
+  // crash-backstop cap in `latestEndedTtlMs`); ms-since-real-end once observed
+  // (window COMPLETED — only the replay grace remains). For a normally-ended
+  // turn `realEndObservedAt === endedAt`, so the tier keeps its tight bound.
+  const latestEndedRealEndAgeMs =
+    latestEnded == null
+      ? null
+      : latestEnded.realEndObservedAt != null
+        ? lookups.now() - latestEnded.realEndObservedAt
+        : null
+  const candidates: ReplyOwnerCandidates = {
+    liveTurnId: liveTurn?.turnId ?? null,
+    originTurnId: origin?.turnId ?? null,
+    quotedTurnId: quoted?.turnId ?? null,
+    latestEndedTurnId: latestEnded?.turnId ?? null,
+    latestEndedAgeMs,
+    latestEndedTtlMs: SUPERSEDE_OPEN_CAP_MS,
+    latestEndedRealEndAgeMs,
+    latestEndedCompletedGraceMs: SUPERSEDE_GRACE_MS,
+  }
+  // #3429 — the winning tier AND the candidate set it came from travel with the
+  // turn. Tier alone no longer decides the content-gate bypass: the
+  // model-steerable `origin`/`quoted` tiers must be CORROBORATED against the
+  // framework-derived `latestEndedTurnId` (`decideContentGateBypass`). All three
+  // derive from these SAME candidates, so they can never disagree.
+  const tier = resolveReplyOwnerTier(candidates)
+  const winnerId = resolveReplyOwnerTurnId(candidates)
+  return { turn: winnerId != null ? (byId.get(winnerId) ?? null) : null, tier, candidates }
+}

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

@@ -73,6 +73,8 @@ import { logStreamingEvent } from '../streaming-metrics.js'
 import { appendActivityLabel } from '../tool-activity-summary.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { decideTurnFlush } from '../turn-flush-safety.js'
+import { FlushCompletionTracker } from '../flushed-turn-supersede.js'
+import { subagentReplyAuthority } from './subagent-reply-authority.js'
 import { decideTerminalReason, deriveTurnRole } from '../turn-liveness-floor.js'
 import { chatKey, chatKeyWithSuffix } from './chat-key.js'
 import { deriveTurnId } from './derive-turn-id.js'
@@ -222,6 +224,38 @@ function discardParkedTurnStart(rawContent: string): ParkedTurnStart | null {
   return null
 }
 
+/**
+ * #4173 — the ONE turn-completion tracker for flush-ended turns (module-scope
+ * like `parkedTurnStarts`: one CLI session per gateway process). The
+ * quiescence flush ends a turn SYNTHETICALLY while the claude session is still
+ * composing; this holds that turn's atom pending until the session's REAL
+ * turn_end (or a proxy: a new turn minting, the bridge dying) is observed,
+ * then stamps `realEndObservedAt` — the signal that flips the supersede
+ * machinery from the unbounded OPEN phase to the ~60 s replay grace. See the
+ * `flushed-turn-supersede.ts` module header for the full three-phase model.
+ */
+export const flushCompletionTracker = new FlushCompletionTracker()
+
+/**
+ * #4173 — a turn-completion signal was observed: close every open flush
+ * window. Stamps the pending atoms (`flushCompletionTracker`) AND starts the
+ * replay grace on the registry's records (`completeAll`) in one call, so the
+ * two surfaces (latest-ended owner tier / supersede record) can never observe
+ * different phases. Called from the real-turn_end path, the new-turn mint, and
+ * the gateway's bridge-death sweep. Returns how many atom windows closed.
+ */
+export function closeFlushCompletionWindows(
+  // Optional-shaped on purpose: several test harnesses drive `beginTurn` /
+  // `handleSessionEvent` with a partial deps object that carries no supersede
+  // registry. The production deps builder always injects the real one.
+  registry: { completeAll?: (now: number) => void } | null | undefined,
+  now: number,
+): number {
+  const closed = flushCompletionTracker.closeAll(now)
+  registry?.completeAll?.(now)
+  return closed
+}
+
 /** Test seam: the parked store is module-scope (one CLI session, one queue), so
  *  suites that drive `handleSessionEvent` need a deterministic reset. */
 export function __resetParkedTurnStartsForTest(): void {
@@ -558,6 +592,9 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
       flushedAnswerText: null,
       // 2026-07 double-reply-on-DM fix (F2) — stamped at turn end.
       endedAt: null,
+      // #4173 — the turn-completion signal, stamped at turn end (or later, for
+      // a flush-ended turn, when the real turn_end is observed).
+      realEndObservedAt: null,
       firstPingAt: null,
       // Notification ownership (R8 / PR-2): no slot claimed yet, so the
       // "claimer was substantive" flag starts false. Set atomically with
@@ -682,6 +719,12 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
     //     already the single stop-owner for ALL turns, and a start is
     //     self-healing anyway, so this cannot leak an interval.
     startTurnTypingLoop(ev.chatId, enqThreadIdNum ?? null)
+    // #4173 — a new turn minting on the serial claude session is a completion
+    // PROXY for any still-open flush window: the session has moved on, so a
+    // prior flushed turn's own late reply can now only arrive as a bounded
+    // replay (the grace). Closing here is the SAFE direction — a window closed
+    // too early costs at most a visible duplicate, never an edit-over.
+    closeFlushCompletionWindows(deps.flushedTurnSupersede, Date.now())
     // PR-4e — route the turn-SET through the keyed accessor: flag-OFF assigns
     // the singleton (byte-identical to `currentTurn = next`); flag-ON sets the
     // per-topic `byKey[statusKey]` entry AND the most-recent mirror. The key is
@@ -916,6 +959,16 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
     const durationMs = ev.kind === 'turn_end' ? ev.durationMs : undefined
     idleTracker.noteEvent(ev.kind, Date.now(), durationMs)
   }
+  // #4176 — sub-agent liveness, fed from the SAME whole-stream position as the
+  // idle clock above and for the same reason: `sub_agent_*` events arrive with
+  // or without a live gateway turn, and the reply send path must know whether a
+  // background sub-agent could be the author of a decoupled reply (a sub-agent
+  // calls `reply` over the parent's OWN bridge, so neither the caller-identity
+  // gate nor the handback marker can see it). Deliberately BEFORE the switch:
+  // the `sub_agent_tool_use` case below early-returns when `getCurrentTurn()` is
+  // null, which is exactly the post-flush state this gate exists for. See
+  // gateway/subagent-reply-authority.ts.
+  subagentReplyAuthority.noteSessionEvent(ev as { kind: string; agentId?: string })
   switch (ev.kind) {
     case 'enqueue': {
       // #3927 FIX A — an `enqueue` is a QUEUE event, not a turn START event
@@ -1724,6 +1777,17 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           return
         }
       }
+      // #4173 — every turn_end that PROCEEDS (a real turn_end always; a
+      // synthetic one only past the suppression guard above) is a completion
+      // signal for any flush window still open from an EARLIER turn: the
+      // serial session has reached a stop, so that turn's own late reply can
+      // now only arrive as a bounded replay. Close them BEFORE this event's
+      // own processing — the quiescence-flush branch below may OPEN a new
+      // window for THIS turn right after. The common case this serves: the
+      // flush's synthetic turn_end tore the atom down, so when the REAL
+      // turn_end for that same turn lands here it finds no live atom and
+      // otherwise no-ops — this close is how that real turn_end is observed.
+      closeFlushCompletionWindows(flushedTurnSupersede, Date.now())
       // #2094 finding 1 — turn_end gate-wedge backstop. Capture the turn
       // BEFORE the body runs (the body re-reads currentTurn as `turn`, then
       // nulls it via endCurrentTurnAtomic on every clean branch). The guarded
@@ -2244,6 +2308,22 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
         // #1556 wedge-safety reasons. `backstopTurnEndedAt` is null iff the
         // atom was already torn down elsewhere (no record to emit).
         const backstopTurnEndedAt = endCurrentTurnAtomic(turn, { deferRecord: true, deferObligationClose: true })
+        // #4173 — the ANSWER-READY QUIESCENCE variant of this branch ends the
+        // turn SYNTHETICALLY (durationMs === -1): the claude session is still
+        // composing and its REAL turn_end arrives later. Re-open the atom's
+        // completion window (endCurrentTurnAtomic just stamped
+        // `realEndObservedAt` with the default "ended = really ended" rule) and
+        // hold it pending, so the supersede window for this flush stays
+        // claimable until the real turn_end — or a proxy — is observed. This is
+        // what makes a same-session reply landing after a 20-minute /compact
+        // still collapse onto the flushed message (#4166), without holding the
+        // window open for even a second once the session actually stops.
+        // The TURN-END BACKSTOP variant (durationMs >= 0) fires ON the real
+        // turn_end: the session already stopped, so its window is born
+        // completed (grace-bounded) — it must NOT be re-opened.
+        if (ev.durationMs === -1) {
+          flushCompletionTracker.open(turn)
+        }
         // #549 fix — turn-flush takes ownership of the captured-text
         // backup; reset the preamble buffer (its content is already in
         // the captured `capturedText`, which turn-flush is about to send).
@@ -2446,7 +2526,17 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
               flushedTurnSupersede.record(
                 backstopChatId,
                 backstopThreadId,
-                { turnId: turn.turnId, messageIds: sentIds, text: capturedText },
+                // #4173 — inherit the atom's completion state: the async send
+                // above can outlast the real turn_end (a close that ran while
+                // we awaited stamped `realEndObservedAt`), and a window closed
+                // before its record existed must be born completed
+                // (grace-bounded), never resurrected as open.
+                {
+                  turnId: turn.turnId,
+                  messageIds: sentIds,
+                  text: capturedText,
+                  completedAt: turn.realEndObservedAt,
+                },
                 Date.now(),
               )
             }

package/telegram-plugin/gateway/subagent-handback-marker.ts

@@ -18,9 +18,9 @@
  *     #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.
+ *     handback recency window (`HANDBACK_RECENCY_WINDOW_MS` below, #4174), so
+ *     the late reply might BE it → keep the #3429 content gate and send fresh
+ *     (two messages), never silently edit/delete the flushed answer.
  *
  * ## Why thread-keyed (F2, dup-audit 2026-07-21)
  *
@@ -65,12 +65,30 @@
  *     reply with NO live gateway turn of its own (a background worker completion),
  *     so its reply resolves a DIFFERENT, already-ended turn via the latest-ended
  *     tier. It is the F1 vector.
- *   - Every OTHER synthesized source (cron, resume_*, reaction, vault_*, …) lands
- *     as its OWN live inbound turn, so its reply resolves the `live` tier for its
- *     own turnId and structurally cannot supersede a different ended turn's flush
- *     record (`decideSupersede` requires `record.turnId === liveTurnId`). Those
- *     must NOT stamp — stamping them would needlessly hold the content gate open
- *     for an unrelated own-reply in the window (a safe but avoidable visible dup).
+ *   - Every OTHER synthesized source that traverses THIS chokepoint (resume_*,
+ *     reaction, vault_*, Tier-2 cron, …) lands as its OWN live inbound turn, so
+ *     its reply resolves the `live` tier for its own turnId and structurally
+ *     cannot supersede a different ended turn's flush record (`decideSupersede`
+ *     requires `record.turnId === liveTurnId`). Those must NOT stamp — stamping
+ *     them would needlessly hold the content gate open for an unrelated
+ *     own-reply in the window (a safe but avoidable visible dup).
+ *
+ * ## What this chokepoint CANNOT see (#4172 — the caller-identity gate)
+ *
+ * The invariant above only covers sources delivered through
+ * `pendingInboundBuffer.push`. A Tier-1 CHEAP-CRON fire is delivered via
+ * `sendToAgent` to the derived `<agent>-cron` bridge and never traverses the
+ * buffer — AND its session events are dropped for the cron identity in
+ * `onSessionEvent`, so it never mints a live gateway turn either. Its `reply`
+ * therefore arrives decoupled (turn == null) with foreign content and NO
+ * marker — exactly the shape marker-absence was claimed to disprove. The same
+ * holds for any reply arriving on a connection that is not the main agent
+ * bridge. That class is closed at a DIFFERENT chokepoint: the reply send path
+ * (`outbound-send-path.ts`) refuses supersede/bypass/latch authority to any
+ * caller that is not the main agent bridge (`replyCallerIsForeignSession`,
+ *  cron-session.ts) — identity, not marker stamping, is the deterministic
+ * signal there. Setting `cron: { decoupledCompletion: true }` below would NOT
+ * work: a Tier-1 fire never reaches this registry's write site.
  *
  * This predicate is therefore the SINGLE point of extension: any future feature
  * that synthesizes an inbound which can land as a DECOUPLED late reply (no live
@@ -114,6 +132,12 @@ export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion
   // Everything below lands as its OWN live inbound turn (live tier), so its reply
   // resolves the live tier for its own turnId and structurally cannot supersede a
   // different ended turn's record → not a decoupled-completion vector, must not stamp.
+  //
+  // cron: `false` covers the TIER-2 (main-bridge, `context:'agent'`) fire, which
+  // does land as its own live turn through this chokepoint. The TIER-1 cheap-cron
+  // fire never traverses this chokepoint AT ALL (see "What this chokepoint
+  // CANNOT see" above) — it is closed by the caller-identity gate in the reply
+  // send path (#4172), and flipping this to `true` would not reach it.
   cron: { decoupledCompletion: false },
   reaction: { decoupledCompletion: false },
   subagent_progress: { decoupledCompletion: false },
@@ -168,6 +192,22 @@ export function stampsHandbackMarker(source: string | null | undefined): boolean
   return known.decoupledCompletion
 }
 
+/**
+ * #4174 — how long after a `subagent_handback` enqueue the content gate stays
+ * held for late replies attributed to an ended turn (`handbackCouldOwnReply`,
+ * outbound-send-path.ts). This deliberately does NOT follow the supersede
+ * window's bounds (#4173): the gate-hold is CHAT-WIDE (the latest-ended owner
+ * tier is chat-wide, so the read must be too — MUST-FIX 2 above), which means
+ * every in-window handback re-opens the reworded-own-answer visible-duplicate
+ * class for EVERY topic in the chat for the window's length. 60 s — the
+ * originally shipped bound — covers the enqueue→decoupled-reply gap the marker
+ * exists for, while keeping the chat-wide dup exposure per handback small. In
+ * a delegation-heavy agent, tying this to a minutes-long supersede bound would
+ * hold the gate almost continuously — re-opening the exact duplicate class the
+ * supersede machinery closes.
+ */
+export const HANDBACK_RECENCY_WINDOW_MS = 60_000
+
 /** Sentinel thread key for the no-thread (DM / bare-chat) lane. */
 const MAIN_THREAD_KEY = '<main>'
 

package/telegram-plugin/gateway/subagent-reply-authority.ts

@@ -0,0 +1,147 @@
+/**
+ * #4176 — sub-agent reply authority: the discriminator the "serial session"
+ * premise was missing.
+ *
+ * ## The premise that was false
+ *
+ * The turn-completion window (#4173, `flushed-turn-supersede.ts`) rests on this
+ * claim: a `reply` landing on the MAIN agent bridge between a flush's SYNTHETIC
+ * turn_end and the session's REAL turn_end is, by construction, that turn's own
+ * answer still being composed. The stated justification was that no other work
+ * can run on the serial claude session in that span.
+ *
+ * That is true of the session's OWN loop and false of its sub-agents. A
+ * background `Task` sub-agent runs CONCURRENTLY with the parent loop, and it
+ * calls MCP tools through the SAME plugin process and therefore the SAME IPC
+ * bridge — so `client.agentName` is the main agent and the #4172 caller-identity
+ * gate (`replyCallerIsForeignSession`) does not see it. In this fleet the
+ * `researcher` and `reviewer` sub-agent types hold the full tool set, `reply`
+ * included (`worker` holds only `progress_update`).
+ *
+ * The concrete loss that made this a MAJOR (review of #4167): the quiescence
+ * flush delivers the answer as message A and the window is OPEN; a background
+ * sub-agent calls `reply` into the same chat; owner resolution lands on the
+ * flush-ended turn (OPEN is accepted at ANY age up to the crash cap); no
+ * `subagent_handback` marker exists because a DIRECT tool call never traverses
+ * `pendingInboundBuffer.push`; `decideContentGateBypass` therefore grants
+ * `positiveAttribution`, and `decideSupersede` supersedes REGARDLESS of content
+ * — the sub-agent's message silently EDITS OVER the user's flushed answer
+ * (Telegram edits do not re-notify: both messages are lost client-side). The
+ * class pre-exists on `main` bounded by the old 60 s TTL; #4173 extends the tail
+ * to the OPEN-phase cap, which is why it is closed here rather than narrowed.
+ *
+ * ## The discriminator: gateway-observed sub-agent LIVENESS
+ *
+ * The gateway already receives the whole session-event stream, including every
+ * `sub_agent_*` kind, at `onSessionEvent` → `handleSessionEvent`. Those events
+ * are derived by the framework from the sidechain transcript
+ * (`projectSubagentLine`, session-tail.ts) — never from model discipline, never
+ * from anything a reply can steer.
+ *
+ * A sub-agent is tracked LIVE from any `sub_agent_*` event carrying its
+ * `agentId` until its `sub_agent_turn_end`. While ANY sub-agent is live, a
+ * decoupled reply on the main bridge MIGHT be that sub-agent's, so it is denied
+ * the #3429 content-gate bypass (`decideContentGateBypass`) — the reply must
+ * then BE the flushed answer to supersede it. A sub-agent's own (foreign)
+ * content therefore decides `'new-content'` and ships as a fresh, notifying
+ * message, with the flush record left intact for the turn's genuine replay.
+ *
+ * ### Why liveness and not per-reply correlation
+ *
+ * Correlating the landing MCP call with the `sub_agent_tool_use` event for that
+ * same `reply` would be exact, but the two arrive on independent transports (an
+ * MCP stdio round-trip vs. a JSONL tail), so the event can land AFTER the reply
+ * it describes — a race whose losing side is the silent edit-over. Liveness has
+ * the ordering the correlation lacks: a sub-agent cannot call a tool before it
+ * exists, and `sub_agent_started` is projected from its FIRST transcript line,
+ * which precedes any tool call it makes by a full model round-trip. The gate is
+ * therefore armed by the time the reply can exist — a structural ordering
+ * argument, not a tuned delay.
+ *
+ * ### Failure directions (all fail SAFE)
+ *
+ *   - A sub-agent whose `sub_agent_turn_end` is never observed (capped, killed,
+ *     crashed tail) stays live: the content gate holds, so the worst case is a
+ *     REWORDED own-answer shipping as a visible duplicate. Never an edit-over.
+ *     `reset()` on bridge death bounds it — the sub-agents die with the session.
+ *   - A sub-agent steered after its `turn_end` (switchroom's `SendMessage`
+ *     pattern) re-arms on its next `sub_agent_*` event, which again precedes any
+ *     reply it makes by a model round-trip.
+ *   - No sub-agent live ⇒ the premise HOLDS and the #4166 collapse is untouched;
+ *     this gate costs nothing in the non-delegating case.
+ *
+ * ### Residual, stated honestly
+ *
+ * Denying the BYPASS (rather than supersede authority wholesale) is deliberate:
+ * with the gate on, a reply still supersedes when it IS the flushed answer
+ * (`flushedAnswerMatchesReply` — equality, or containment above
+ * `SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS`). Superseding on equality is
+ * content-preserving by definition. The residual is the containment arm: a
+ * sub-agent reply that is a ≥32-char verbatim substring of the flushed answer
+ * would still collapse into it. Denying supersede outright instead would, in a
+ * delegation-heavy agent where a background worker is nearly always live,
+ * re-open #4166 for every own-answer replay — a far larger, constant cost for a
+ * class that requires a sub-agent to emit a verbatim substring of the parent's
+ * answer.
+ *
+ * Pure: a set of ids, no clock reads, no I/O. The gateway wires the feed
+ * (`onSessionEvent`) and the read (the `sendReply` deps).
+ */
+
+/** The read surface the reply send path consumes (injected, so the golden
+ *  harness drives it without touching the singleton). */
+export interface SubagentReplyAuthorityView {
+  /** True when at least one sub-agent is live on this session and could
+   *  therefore be the author of a decoupled reply landing right now. */
+  subagentCouldOwnReply(): boolean
+}
+
+/** The minimal session-event shape this tracker reads. Structural so the module
+ *  never imports the session-tail union (no cycle, trivially fake-able). */
+export interface SubagentLifecycleEvent {
+  kind: string
+  agentId?: string
+}
+
+const SUB_AGENT_KIND_PREFIX = 'sub_agent_'
+
+export class SubagentReplyAuthority implements SubagentReplyAuthorityView {
+  private readonly live = new Set<string>()
+
+  /** Feed EVERY session event here. Non-`sub_agent_*` kinds are ignored, so the
+   *  call site needs no filtering (and cannot drift from this one). */
+  noteSessionEvent(ev: SubagentLifecycleEvent | null | undefined): void {
+    if (ev == null) return
+    const kind = ev.kind
+    if (typeof kind !== 'string' || !kind.startsWith(SUB_AGENT_KIND_PREFIX)) return
+    const agentId = ev.agentId
+    // An id-less sub-agent event cannot be attributed to a lifecycle; ignoring
+    // it is the safe direction for `turn_end` (liveness persists → gate holds)
+    // and merely a missed arm otherwise — every other kind for a real sub-agent
+    // carries the id.
+    if (typeof agentId !== 'string' || agentId === '') return
+    if (kind === `${SUB_AGENT_KIND_PREFIX}turn_end`) this.live.delete(agentId)
+    else this.live.add(agentId)
+  }
+
+  subagentCouldOwnReply(): boolean {
+    return this.live.size > 0
+  }
+
+  /** The bridge died: the claude session and every sub-agent under it are gone.
+   *  Bounds a leaked liveness entry (see "Failure directions"). */
+  reset(): void {
+    this.live.clear()
+  }
+
+  /** Test/diagnostics: how many sub-agents are currently tracked live. */
+  liveCount(): number {
+    return this.live.size
+  }
+}
+
+/** The ONE live instance (one CLI session per gateway process — the same
+ *  module-singleton shape as `flushCompletionTracker` in stream-render.ts).
+ *  Re-`new`ing this anywhere else splits the signal and silently re-opens the
+ *  edit-over hole. */
+export const subagentReplyAuthority = new SubagentReplyAuthority()