switchroom 0.19.5 → 0.19.7

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

@@ -31,6 +31,7 @@
 
 import type { InboundMessage } from './ipc-protocol.js'
 import type { InboundSpool } from './inbound-spool.js'
+import { stampsHandbackMarker } from './subagent-handback-marker.js'
 
 /** Default cap per agent. Tuned for `should fit a reasonable backlog of
  *  approval cards stacked while bridge is offline` but no more. */
@@ -79,6 +80,20 @@ 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`, its `threadId` (the originating forum
+   * topic, or undefined for a DM), and its own `ts` (ms). The gateway wires this
+   * to the per-chat/thread 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.
+   * The `threadId` is passed so the marker keys on the SAME `chatId|threadId`
+   * lane the supersede registry uses (dup-audit F2): a handback in one topic must
+   * not hold the content gate open in another. Best-effort: a throw here never
+   * breaks the push hot path.
+   */
+  onHandbackEnqueue?: (chatId: string, threadId: number | undefined, ts: number) => void
 }
 
 /**
@@ -342,6 +357,31 @@ 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.
+      // F1 (dup-audit) — the ONE chokepoint that decides which sources stamp the
+      // decoupled-completion marker, delegated to the single `stampsHandbackMarker`
+      // predicate (its membership is the invariant's only extension point). Every
+      // inbound — live synthesis AND boot-replay — funnels through this push(), so
+      // routing the decision here makes "a decoupled late-reply source stamps the
+      // marker" true BY CONSTRUCTION rather than by per-feature discipline.
+      if (stampsHandbackMarker(msg.meta?.source) && opts.onHandbackEnqueue != null) {
+        try {
+          // F2 (dup-audit): pass the envelope's originating topic so the marker
+          // keys on the same `chatId|threadId` lane as the supersede registry.
+          opts.onHandbackEnqueue(msg.chatId, msg.threadId, 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/subagent-handback-marker.ts

@@ -0,0 +1,221 @@
+/**
+ * Per-chat-and-thread 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/thread,
+ * 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/thread 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.
+ *
+ * ## Why thread-keyed (F2, dup-audit 2026-07-21)
+ *
+ * The supersede registry this marker gates is keyed on `chatId|threadId`
+ * (`flushed-turn-supersede.ts` `makeKey`). Keying the marker on `chatId` ALONE
+ * was inconsistent: in a forum supergroup a background handback in topic A
+ * stamped the chat-wide marker, and a genuine CASE-A reworded own-reply in ANY
+ * other topic within the 60 s TTL then computed `handbackCouldOwnReply = true` →
+ * kept the content gate → shipped a second visible bubble instead of collapsing.
+ * The blast radius was every topic in the chat for 60 s per handback. Keying on
+ * `chatId + threadId` — the SAME lane the supersede registry uses — confines a
+ * handback's gate-hold to the topic it actually landed in, so an unrelated
+ * topic's CASE-A collapse is untouched. A DM (no thread) collapses to the
+ * chat-only key, so single-lane behaviour is unchanged.
+ *
+ * One entry per chat/thread (overwritten on each enqueue), so bounded by
+ * chat×topic 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).
+ */
+/**
+ * ## The enforced invariant (F1, dup-audit 2026-07-21)
+ *
+ * The whole content-gate bypass rests on this premise: *a decoupled late reply
+ * (turn == null) carrying content that is NOT the flushed turn's own answer,
+ * resolving an ENDED flushed turn as its owner, can ONLY be a gateway-synthesized
+ * completion — and every such completion stamps this marker.* If that premise
+ * holds, then marker-ABSENCE in the window proves the late reply IS the flushed
+ * turn's own (possibly reworded) answer, so bypassing the content gate is safe
+ * (closes the marko duplicate). If a NEW synthesized-inbound source were ever
+ * able to land as a decoupled late reply with foreign content WITHOUT stamping,
+ * it would silently edit over a delivered answer (the #3429 failure).
+ *
+ * We make the premise an ENFORCED invariant rather than an architectural
+ * coincidence by routing the stamp decision through this ONE predicate at the ONE
+ * chokepoint every inbound funnels through (`pendingInboundBuffer.push` — live
+ * synthesis, boot-replay, and every future source alike). The membership of the
+ * decoupled-completion class is defined HERE and nowhere else:
+ *
+ *   - `subagent_handback` — the only source today that wakes the agent to emit a
+ *     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).
+ *
+ * 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
+ * turn) MUST add its `meta.source` here — and because the chokepoint consults
+ * this predicate, doing so is the whole wiring. A source that forgets to opt in
+ * cannot reach the bypass unnoticed: the negative outcome guard
+ * (`send-reply-golden.test.ts`) pins that a decoupled foreign-content reply on a
+ * non-live tier never silently edits over the flushed answer.
+ *
+ * ## Inbound meta.source classification registry (F1 durability — dup-audit
+ * MUST-FIX 3, Fable 2026-07-21)
+ *
+ * The old predicate was a bare `=== 'subagent_handback'` with NO tripwire and an
+ * UNSAFE default: adding a new decoupled-completion source tripped nothing — no
+ * stamp → content-gate bypass eligible → silent edit-over of a delivered answer.
+ * This registry makes the classification EXPLICIT, EXHAUSTIVE and FAIL-SAFE:
+ *
+ *   - Every known `meta.source` is listed with `decoupledCompletion`. Today ONLY
+ *     `subagent_handback` is true; every other synthesized source lands as its
+ *     OWN live inbound turn (live tier → cannot supersede a different ended
+ *     turn's record), so it must NOT stamp.
+ *   - An UNKNOWN / unclassified source FAILS SAFE: `stampsHandbackMarker` returns
+ *     `true`, so it STAMPS → the content gate is KEPT → the worst case is a
+ *     visible duplicate, NEVER a silent edit-over (inverted from the old
+ *     deny-default, which failed toward silent loss).
+ *   - The exhaustiveness test (`subagent-handback-marker.test.ts`) scans the
+ *     gateway for `source:` / `meta.source ===` literals and FAILS when a new one
+ *     is added without a registry entry — forcing a conscious classification.
+ *
+ * Defense-in-depth with the tier restriction (`outbound-send-path.ts`): the
+ * content-gate bypass is now limited to the `live` + `latest-ended` tiers, so
+ * model-steerable `quoted`/`origin` attributions can never bypass regardless of
+ * the marker. This registry closes the residual `latest-ended` vector for a
+ * FUTURE decoupled source, fail-safe.
+ */
+export const INBOUND_SOURCE_CLASSIFICATION: Record<string, { decoupledCompletion: boolean }> = {
+  // The ONE decoupled-completion source today: a background worker termination
+  // wakes the agent with no live turn of its own → its reply resolves a
+  // different, already-ended turn via the latest-ended tier. THE F1 vector.
+  subagent_handback: { decoupledCompletion: true },
+  // 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: { decoupledCompletion: false },
+  reaction: { decoupledCompletion: false },
+  subagent_progress: { decoupledCompletion: false },
+  resume_interrupted: { decoupledCompletion: false },
+  resume_deferred: { decoupledCompletion: false },
+  resume_watchdog_timeout: { decoupledCompletion: false },
+  vault_grant_approved: { decoupledCompletion: false },
+  vault_grant_denied: { decoupledCompletion: false },
+  vault_grant_timeout: { decoupledCompletion: false },
+  vault_save_completed: { decoupledCompletion: false },
+  vault_save_discarded: { decoupledCompletion: false },
+  vault_save_failed: { decoupledCompletion: false },
+  vault_save_timeout: { decoupledCompletion: false },
+  secret_provided: { decoupledCompletion: false },
+  secret_declined: { decoupledCompletion: false },
+  secret_provide_failed: { decoupledCompletion: false },
+  secret_request_timeout: { decoupledCompletion: false },
+  mental_model_propose_timeout: { decoupledCompletion: false },
+  bridge_dead_restart: { decoupledCompletion: false },
+  obligation_represent: { decoupledCompletion: false },
+  missed_approval_retry: { decoupledCompletion: false },
+  skill_proposal_apply: { decoupledCompletion: false },
+  warmup: { decoupledCompletion: false },
+  // dup-audit pass-2 (Fable) — sources the widened exhaustiveness scanner now
+  // sees. Each lands as its OWN live inbound turn (not a decoupled completion
+  // resolving a DIFFERENT ended turn), so it must NOT stamp — else its fail-safe
+  // stamp would hold the content gate chat-wide for 60 s and re-open the
+  // reworded-own-answer visible dup in that window.
+  //   - mental_model_proposal_{applied,denied,failed}: resume-synthetic inbounds
+  //     injected via `deliverResumeSyntheticOrBuffer` as their own live turn.
+  //   - webhook / linear: built in `src/web/webhook-dispatch.ts`, delivered via
+  //     the gateway's `webhookInject` (`sendToAgent`, buffer on miss) as their
+  //     own live turn.
+  mental_model_proposal_applied: { decoupledCompletion: false },
+  mental_model_proposal_denied: { decoupledCompletion: false },
+  mental_model_proposal_failed: { decoupledCompletion: false },
+  webhook: { decoupledCompletion: false },
+  linear: { decoupledCompletion: false },
+}
+
+/**
+ * Whether an inbound of this `meta.source` must stamp the decoupled-completion
+ * marker. Null/undefined (a normal user inbound — not synthesized) → false.
+ * A known source → its registry classification. An UNKNOWN source → true
+ * (fail-safe: stamp, so an unclassified future decoupled source can only cause a
+ * visible dup, never a silent edit-over).
+ */
+export function stampsHandbackMarker(source: string | null | undefined): boolean {
+  if (source == null) return false
+  const known = INBOUND_SOURCE_CLASSIFICATION[source]
+  if (known == null) return true // fail-safe: unknown synthesized source stamps
+  return known.decoupledCompletion
+}
+
+/** Sentinel thread key for the no-thread (DM / bare-chat) lane. */
+const MAIN_THREAD_KEY = '<main>'
+
+export class SubagentHandbackMarker {
+  // chatId → (threadKey → last enqueue ms). Nested so the CONTENT-GATE read can
+  // query chat-wide (`lastAtInChat`) while the record stays thread-resolved.
+  private readonly byChat = new Map<string, Map<string, number>>()
+
+  private threadKey(threadId: number | undefined): string {
+    return threadId == null ? MAIN_THREAD_KEY : String(threadId)
+  }
+
+  /** Record that a `subagent_handback` was enqueued for `chatId`/`threadId` at
+   *  `now` (ms). Thread-resolved so the record retains the originating topic. */
+  record(chatId: string, threadId: number | undefined, now: number): void {
+    let inner = this.byChat.get(chatId)
+    if (inner == null) {
+      inner = new Map<string, number>()
+      this.byChat.set(chatId, inner)
+    }
+    inner.set(this.threadKey(threadId), now)
+  }
+
+  /** Wall-clock ms of the most recent handback enqueue for a SPECIFIC
+   *  `chatId`/`threadId` lane, or null. (Diagnostics / unit tests.) */
+  lastAt(chatId: string, threadId: number | undefined): number | null {
+    return this.byChat.get(chatId)?.get(this.threadKey(threadId)) ?? null
+  }
+
+  /**
+   * Wall-clock ms of the most recent handback enqueue ANYWHERE in `chatId`
+   * (across every topic lane), or null. This is what the content-gate read uses
+   * (dup-audit MUST-FIX 2, Fable 2026-07-21): the owner-resolution latest-ended
+   * tier is CHAT-WIDE (`findLatestEndedTurnForChat` ignores thread), so a
+   * background handback in topic A can resolve — and supersede — topic B's
+   * ended turn. A thread-SPECIFIC gate read (the F2 regression) let a reply
+   * dodge that handback by carrying a different `message_thread_id`, silently
+   * editing over the answer. Querying chat-wide makes the gate un-steerable by
+   * the reply's own thread arg: any in-window handback in the chat keeps the
+   * content gate. The cost is the F2 visible-dup (a handback in one topic keeps
+   * the gate for a coinciding own-reply in another for ≤TTL) — a self-healing
+   * visible duplicate, which is strictly better than a silent edit-over.
+   */
+  lastAtInChat(chatId: string): number | null {
+    const inner = this.byChat.get(chatId)
+    if (inner == null || inner.size === 0) return null
+    let max = -Infinity
+    for (const ts of inner.values()) if (ts > max) max = ts
+    return max === -Infinity ? null : max
+  }
+}

package/telegram-plugin/reply-owner-resolve.ts

@@ -84,6 +84,37 @@ function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
   return age <= ttl
 }
 
+/**
+ * Which precedence tier resolved a reply's owner turn.
+ *
+ *   - `'live'` / `'origin'` / `'quoted'` are POSITIVE attributions: the reply
+ *     is tied to a specific turn by a live atom, the model's own echo, or the
+ *     framework-owned quoted message id — it IS that turn's answer.
+ *   - `'latest-ended'` is the ambiguous FALLBACK: no positive link exists, so
+ *     the reply is merely attributed to the chat's most-recently-ended turn.
+ *     This tier cannot tell the turn's OWN late reply from an async sub-agent
+ *     handback that has no live turn and no quote linkage — both land here with
+ *     the same resolved turnId (#3429). The supersede content gate
+ *     (`flushedAnswerMatchesReply`) is therefore applied ONLY on this tier.
+ *   - `'none'` — every lookup missed (a genuinely unattributable reply).
+ */
+export type ReplyOwnerTier = 'live' | 'origin' | 'quoted' | 'latest-ended' | 'none'
+
+/**
+ * The tier that WINS owner resolution for these candidates — the single source
+ * of the precedence order, consumed by both `resolveReplyOwnerTurnId` (which id)
+ * and the gateway (which discrimination the supersede applies). Same precedence,
+ * first non-null wins; the destructive latest-ended tier is honoured only when
+ * fresh (`latestEndedAccepted`).
+ */
+export function resolveReplyOwnerTier(candidates: ReplyOwnerCandidates): ReplyOwnerTier {
+  if (candidates.liveTurnId != null) return 'live'
+  if (candidates.originTurnId != null) return 'origin'
+  if (candidates.quotedTurnId != null) return 'quoted'
+  if (latestEndedAccepted(candidates)) return 'latest-ended'
+  return 'none'
+}
+
 /**
  * Resolve the turnId that OWNS a landing reply, using the SAME full chain the
  * thread-router uses. Precedence, first non-null wins:
@@ -98,13 +129,18 @@ function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
  * to delete any turnId-bearing flush record.
  */
 export function resolveReplyOwnerTurnId(candidates: ReplyOwnerCandidates): string | null {
-  return (
-    candidates.liveTurnId ??
-    candidates.originTurnId ??
-    candidates.quotedTurnId ??
-    (latestEndedAccepted(candidates) ? candidates.latestEndedTurnId : null) ??
-    null
-  )
+  switch (resolveReplyOwnerTier(candidates)) {
+    case 'live':
+      return candidates.liveTurnId
+    case 'origin':
+      return candidates.originTurnId
+    case 'quoted':
+      return candidates.quotedTurnId
+    case 'latest-ended':
+      return candidates.latestEndedTurnId
+    case 'none':
+      return null
+  }
 }
 
 /**

package/telegram-plugin/tests/flushed-turn-supersede.test.ts

@@ -381,3 +381,92 @@ describe('#3429 — decideSupersede new-content gate', () => {
     expect(reg.peek('chat9', undefined, { liveTurnId: 'turn-F', now: now + 21_000 }).reason).toBe('no-record')
   })
 })
+
+/**
+ * The tier discriminator (fix/backstop-duplicate-reply). `positiveAttribution`
+ * lets the gateway bypass the #3429 content gate when the reply's owner turn was
+ * resolved by POSITIVE attribution (live / origin echo / quoted) rather than the
+ * ambiguous latest-ended fallback. On a positive tier a genuinely-DIFFERENT
+ * (reworded) reply for the same turn still supersedes — closing the reworded
+ * same-turn duplicate — while the latest-ended path keeps the content gate so a
+ * true async handback still sends fresh.
+ */
+describe('positiveAttribution — tier-gated content check', () => {
+  const FLUSHED = 'Narration first.\n\nHere is the finished summary of the incident you asked about.'
+  const REWORDED =
+    'So, to wrap up: the incident boiled down to a stale cache entry, and it is fully resolved now.'
+
+  it('positiveAttribution=true: same turn + DIFFERENT (reworded) content STILL supersedes', () => {
+    // Guard: the reworded text is genuinely new vs the flushed blob (would be
+    // declined new-content without the tier bypass).
+    expect(flushedAnswerMatchesReply(FLUSHED, REWORDED)).toBe(false)
+
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+    expect(d.deleteMessageIds).toEqual([101, 102])
+  })
+
+  it('positiveAttribution=false (latest-ended): the SAME reworded content declines as new-content', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: false,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('new-content')
+  })
+
+  it('positiveAttribution=true still requires turn IDENTITY (different turn never supersedes)', () => {
+    const d = decideSupersede(rec({ turnId: 'turn-A', text: FLUSHED }), {
+      liveTurnId: 'turn-B',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('different-turn')
+  })
+
+  it('positiveAttribution=true still respects the TTL (expired record never supersedes)', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: 1_000_000 + DEFAULT_SUPERSEDE_TTL_MS + 1,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('expired')
+  })
+
+  it('registry take() threads positiveAttribution through to the decision', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    const now = 1_000_000
+    reg.record('chatT', undefined, { turnId: 'turn-Q', messageIds: [8001], text: FLUSHED }, now)
+
+    // latest-ended (positiveAttribution falsey): reworded → new-content, kept.
+    const ambiguous = reg.peek('chatT', undefined, {
+      liveTurnId: 'turn-Q',
+      replyText: REWORDED,
+      now: now + 5_000,
+    })
+    expect(ambiguous.reason).toBe('new-content')
+
+    // positive tier: same reworded reply supersedes and consumes the record.
+    const positive = reg.take('chatT', undefined, {
+      liveTurnId: 'turn-Q',
+      replyText: REWORDED,
+      positiveAttribution: true,
+      now: now + 6_000,
+    })
+    expect(positive.supersede).toBe(true)
+    expect(positive.deleteMessageIds).toEqual([8001])
+    expect(reg.peek('chatT', undefined, { liveTurnId: 'turn-Q', now: now + 7_000 }).reason).toBe('no-record')
+  })
+})

package/telegram-plugin/tests/narrative-lane-golden.test.ts

@@ -371,7 +371,8 @@ function makeSendReplyDeps(dedup: OutboundDedupCache) {
     assertSendable: () => {},
     statusKey: key,
     streamKey: key,
-    resolveReplyOwnerTurn: () => null,
+    resolveReplyOwnerTurn: () => ({ turn: null, tier: 'none' as const }),
+    getLastSubagentHandbackAt: () => null,
     findTurnByOriginId: () => null,
     findTurnByQuotedMessageId: () => null,
     resolveAnswerThreadWithLog: (_c: string, explicit: number | undefined) => explicit,

package/telegram-plugin/tests/reply-owner-resolve.test.ts

@@ -32,6 +32,7 @@
 import { describe, it, expect } from 'vitest'
 import {
   resolveReplyOwnerTurnId,
+  resolveReplyOwnerTier,
   decideAnswerLatchSuppression,
   type ReplyOwnerCandidates,
   type AnswerDeliveredLatch,
@@ -611,3 +612,76 @@ describe('#3429 — flush-armed latch with content evidence', () => {
     ).toBe(false)
   })
 })
+
+/**
+ * `resolveReplyOwnerTier` (fix/backstop-duplicate-reply) exposes WHICH precedence
+ * tier won, so the gateway can apply the #3429 content gate ONLY on the ambiguous
+ * `latest-ended` fallback. It shares one precedence with `resolveReplyOwnerTurnId`
+ * (asserted equivalent below), so the winning id and the winning tier can never
+ * disagree.
+ */
+describe('resolveReplyOwnerTier — precedence + latest-ended TTL bound', () => {
+  const base: ReplyOwnerCandidates = {
+    liveTurnId: null,
+    originTurnId: null,
+    quotedTurnId: null,
+    latestEndedTurnId: null,
+  }
+
+  it('live wins over every lower tier', () => {
+    expect(
+      resolveReplyOwnerTier({ ...base, liveTurnId: 'L', originTurnId: 'O', quotedTurnId: 'Q', latestEndedTurnId: 'E' }),
+    ).toBe('live')
+  })
+
+  it('origin wins when no live turn', () => {
+    expect(resolveReplyOwnerTier({ ...base, originTurnId: 'O', quotedTurnId: 'Q', latestEndedTurnId: 'E' })).toBe('origin')
+  })
+
+  it('quoted wins when no live/origin turn (the positive DM recovery tier)', () => {
+    expect(resolveReplyOwnerTier({ ...base, quotedTurnId: 'Q', latestEndedTurnId: 'E' })).toBe('quoted')
+  })
+
+  it('latest-ended is the ambiguous FALLBACK when only it resolves', () => {
+    expect(resolveReplyOwnerTier({ ...base, latestEndedTurnId: 'E' })).toBe('latest-ended')
+  })
+
+  it('none when every lookup missed', () => {
+    expect(resolveReplyOwnerTier(base)).toBe('none')
+  })
+
+  it('a STALE latest-ended (age > TTL) is NOT accepted → none, never latest-ended', () => {
+    const stale: ReplyOwnerCandidates = {
+      ...base,
+      latestEndedTurnId: 'E',
+      latestEndedAgeMs: DEFAULT_SUPERSEDE_TTL_MS + 1,
+      latestEndedTtlMs: DEFAULT_SUPERSEDE_TTL_MS,
+    }
+    expect(resolveReplyOwnerTier(stale)).toBe('none')
+    // And the id resolver agrees (no destructive authority granted to a stale turn).
+    expect(resolveReplyOwnerTurnId(stale)).toBe(null)
+  })
+
+  it('tier and id resolver share one precedence for every candidate shape', () => {
+    const shapes: ReplyOwnerCandidates[] = [
+      base,
+      { ...base, liveTurnId: 'L', quotedTurnId: 'Q', latestEndedTurnId: 'E' },
+      { ...base, originTurnId: 'O', latestEndedTurnId: 'E' },
+      { ...base, quotedTurnId: 'Q' },
+      { ...base, latestEndedTurnId: 'E' },
+    ]
+    const idForTier = (s: ReplyOwnerCandidates): string | null => {
+      switch (resolveReplyOwnerTier(s)) {
+        case 'live': return s.liveTurnId
+        case 'origin': return s.originTurnId
+        case 'quoted': return s.quotedTurnId
+        case 'latest-ended': return s.latestEndedTurnId
+        case 'none': return null
+      }
+    }
+    for (const s of shapes) {
+      // The id the winning tier points at equals what the id resolver returns.
+      expect(resolveReplyOwnerTurnId(s)).toBe(idForTier(s))
+    }
+  })
+})