switchroom 0.19.44 → 0.19.45

package/telegram-plugin/gateway/turn-end.ts

@@ -437,10 +437,18 @@ function endCurrentTurnAtomic(
   const turnEndedAt = Date.now()
   // 2026-07 double-reply-on-DM fix (F2) — stamp the turn's end time so the
   // `latest-ended` supersede tier can be recency-bounded to the
-  // supersede TTL (a stale latest-ended turn must not inherit deletion
+  // turn-completion window (a stale latest-ended turn must not inherit deletion
   // authority over a newer turn's flush record). Set once; idempotent on the
   // deferRecord flush path (which calls this synchronously before its send).
   turn.endedAt = turnEndedAt
+  // #4173 — default completion stamp: for every ordinary turn-end path, the
+  // turn ending IS the session's real stop, so the completion window is born
+  // closed (the latest-ended tier keeps its tight ~60 s replay grace). The ONE
+  // path where that is false — the answer-ready quiescence flush, which ends
+  // the turn synthetically while the session is still composing — re-opens the
+  // window right after this call (`flushCompletionTracker.open`, stream-render
+  // turn-flush branch) and holds it until the REAL turn_end is observed.
+  turn.realEndObservedAt = turnEndedAt
   process.stderr.write(
     `telegram gateway: ${formatTurnLifecycle('clear', 'turn_end', turn, turnEndedAt)}\n`,
   )

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

@@ -41,6 +41,11 @@
  * feeds their resolved turnIds here; the precedence lives in one place.
  */
 
+// The one cross-module import this pure module takes — a sibling PURE module's
+// constant, so the two consumers of the turn-completion window (#4173) can
+// never disagree on the default replay grace.
+import { SUPERSEDE_COMPLETED_GRACE_MS } from './flushed-turn-supersede.js'
+
 /**
  * The four owner-turn candidate ids, in the gateway's resolution precedence.
  * Each is the `turnId` of the turn a given lookup resolved, or null when that
@@ -63,38 +68,75 @@ export interface ReplyOwnerCandidates {
   latestEndedTurnId: string | null
   /** Age (ms) of the latest-ended turn — `now - turn.endedAt`. The latest-ended
    *  tier carries DESTRUCTIVE authority (it drives supersede deletion), so it is
-   *  honoured ONLY when the turn ended within `latestEndedTtlMs` (the supersede
-   *  TTL). Without the bound, a late reply belonging to an OLDER turn could
-   *  resolve its owner to a NEWER turn now sitting at the registry tail and
-   *  delete THAT turn's legit answer.
+   *  honoured ONLY within the turn-completion window (#4173 — see
+   *  `latestEndedRealEndAgeMs`). Without a bound, a late reply belonging to an
+   *  OLDER turn could resolve its owner to a NEWER turn now sitting at the
+   *  registry tail and delete THAT turn's legit answer.
    *
    *  Two distinct absences (#3725):
-   *    - `undefined` (property omitted) ⇒ unbounded, the pre-F2 back-compat
-   *      escape for callers that don't supply an age at all;
+   *    - `undefined` (property omitted) ⇒ no age supplied at all — fails
+   *      CLOSED since #4175 (the pre-F2 "unbounded" escape granted unbounded
+   *      destructive authority exactly when the wiring was DROPPED, the
+   *      dangerous direction);
    *    - explicit `null` ⇒ the caller COMPUTED no age, i.e. its candidate turn
-   *      has no `endedAt` and has NOT ended. That cannot be TTL-bounded, so it
+   *      has no `endedAt` and has NOT ended. That cannot be bounded, so it
    *      fails CLOSED (not accepted) rather than granting unbounded authority
    *      to a turn that is still running. */
   latestEndedAgeMs?: number | null
-  /** The supersede TTL bound applied to `latestEndedAgeMs`. Undefined ⇒
-   *  unbounded. */
+  /** Bound applied to `latestEndedAgeMs` while the turn's completion window is
+   *  OPEN (#4173): for a flush-ended turn whose REAL turn_end has not been
+   *  observed yet, this is the crash-backstop cap
+   *  (`SUPERSEDE_OPEN_WINDOW_CAP_MS`). Undefined ⇒ fails closed (#4175). */
   latestEndedTtlMs?: number
+  /** #4173 — the turn-completion signal, ms since the candidate turn's REAL
+   *  turn_end was observed (`turn.realEndObservedAt`):
+   *    - `null` ⇒ the real turn_end has NOT been observed (a flush ended this
+   *      turn synthetically and the session is still composing) — the OPEN
+   *      phase; acceptance falls to `latestEndedAgeMs <= latestEndedTtlMs`
+   *      (the crash backstop), so a 20-minute compaction still resolves.
+   *    - a number ⇒ the session stopped that long ago — the COMPLETED phase;
+   *      accepted only within `latestEndedCompletedGraceMs` (the bounded
+   *      tool-call-replay window). For a normally-ended turn the real end IS
+   *      `endedAt`, so this equals `latestEndedAgeMs` and the tier keeps its
+   *      original tight ~60 s bound.
+   *    - `undefined` ⇒ legacy caller shape (no completion signal wired):
+   *      falls back to the plain `age <= ttl` rule. */
+  latestEndedRealEndAgeMs?: number | null
+  /** COMPLETED-phase bound for `latestEndedRealEndAgeMs`. Undefined ⇒ the
+   *  module default (`SUPERSEDE_COMPLETED_GRACE_MS`). */
+  latestEndedCompletedGraceMs?: number
 }
 
 /**
  * Whether the latest-ended candidate is fresh enough to carry supersede
- * (deletion) authority. An OMITTED age or TTL means unbounded (the pre-F2
- * back-compat escape); an EXPLICIT null age fails closed (#3725 — the caller
- * computed no age because its candidate turn has not ended, and an un-ended turn
- * must be resolved by the `live` tier, never by this destructive fallback).
+ * (deletion) authority — the turn-completion-window rule (#4173, three phases
+ * documented on `latestEndedRealEndAgeMs` above).
+ *
+ * An EXPLICIT null age fails closed (#3725 — the caller computed no age
+ * because its candidate turn has not ended, and an un-ended turn must be
+ * resolved by the `live` tier, never by this destructive fallback). An OMITTED
+ * age or TTL also fails closed (#4175): the old "omitted ⇒ unbounded"
+ * back-compat escape meant DROPPING the gateway's bound wiring silently
+ * granted unbounded destructive authority — failing toward silent edit-over.
+ * Now dropped wiring degrades to "tier never accepted" — a visible duplicate,
+ * the safe direction.
  */
 function latestEndedAccepted(candidates: ReplyOwnerCandidates): boolean {
   if (candidates.latestEndedTurnId == null) return false
   const age = candidates.latestEndedAgeMs
   const ttl = candidates.latestEndedTtlMs
-  if (age === null) return false
-  if (age === undefined || ttl == null) return true
-  return age <= ttl
+  if (age == null || ttl == null) return false
+  const realEndAge = candidates.latestEndedRealEndAgeMs
+  if (realEndAge === undefined || realEndAge === null) {
+    // Legacy caller (no completion signal) or OPEN window (real turn_end not
+    // yet observed): the plain age-vs-cap rule. For an open window `ttl` is
+    // the generous crash backstop, so a long compaction still resolves.
+    return age <= ttl
+  }
+  // COMPLETED: the session stopped `realEndAge` ago — only the bounded
+  // tool-call-replay grace remains.
+  const grace = candidates.latestEndedCompletedGraceMs ?? SUPERSEDE_COMPLETED_GRACE_MS
+  return realEndAge <= grace
 }
 
 /**
@@ -207,6 +249,21 @@ export function resolveReplyOwnerTurnId(candidates: ReplyOwnerCandidates): strin
  * `live` keeps its unconditional bypass: `currentTurn` is framework-owned, and
  * `decideSupersede`'s same-turnId requirement already bars it from reaching a
  * DIFFERENT ended turn's record. `none` never bypasses (nothing to attribute).
+ *
+ * ## The second ambiguity: a live sub-agent (#4176)
+ *
+ * `handbackCouldOwnReply` covers the sub-agent completion that the gateway
+ * SYNTHESIZED as an inbound. It does not cover a background sub-agent calling
+ * `reply` DIRECTLY, mid-run: that call rides the same main bridge as the parent
+ * loop (so the #4172 caller-identity gate cannot see it) and never traverses
+ * `pendingInboundBuffer.push` (so no marker is stamped). Marker-absence is only
+ * evidence of "the turn's own answer" if nothing else on the session could have
+ * emitted this reply — which is exactly what `subagentCouldOwnReply` reports,
+ * from gateway-observed `sub_agent_*` liveness. When it is true the content gate
+ * is KEPT on every non-`live` tier: a reply that IS the flushed answer still
+ * collapses, a sub-agent's foreign content sends fresh. See
+ * `gateway/subagent-reply-authority.ts` for the ordering argument and the
+ * failure directions.
  */
 export function decideContentGateBypass(input: {
   /** The winning owner tier (`resolveReplyOwnerTier`). */
@@ -216,18 +273,36 @@ export function decideContentGateBypass(input: {
   /** The SAME candidate set both of the above were derived from — supplies the
    *  framework-derived `latestEndedTurnId` plus its freshness bound, so the
    *  corroboration reuses the EXACT rule `resolveReplyOwnerTier` applies
-   *  (`latestEndedAccepted`) instead of duplicating it: within the TTL, and —
-   *  since #3725 — not a turn that is still running. */
+   *  (`latestEndedAccepted`) instead of duplicating it: within the
+   *  turn-completion window (#4173), and — since #3725 — not a turn that is
+   *  still running. */
   candidates: ReplyOwnerCandidates
   /** True when a decoupled-completion inbound (`subagent_handback`) was enqueued
-   *  in this chat AFTER the owner turn ended and within the supersede TTL — the
-   *  ambiguous window where the late reply might BE that handback rather than
-   *  the turn's own answer. Keeps the content gate on every non-`live` tier. */
+   *  in this chat AFTER the owner turn ended and within the handback recency
+   *  window (`HANDBACK_RECENCY_WINDOW_MS`, #4174) — the ambiguous window where
+   *  the late reply might BE that handback rather than the turn's own answer.
+   *  Keeps the content gate on every non-`live` tier. */
   handbackCouldOwnReply: boolean
+  /** #4176 — true when a sub-agent is LIVE on this session
+   *  (`subagentReplyAuthority`, gateway/subagent-reply-authority.ts). A
+   *  background `Task` sub-agent calls `reply` over the SAME main bridge as the
+   *  parent loop, so the #4172 caller-identity gate cannot see it and — because
+   *  a DIRECT tool call never traverses `pendingInboundBuffer.push` — it stamps
+   *  no handback marker either. Marker-absence therefore does NOT prove "the
+   *  turn's own answer" while a sub-agent is live: the reply might be the
+   *  sub-agent's, and bypassing the content gate would silently EDIT OVER the
+   *  flushed answer. Typed REQUIRED and evaluated FAIL-CLOSED (anything but an
+   *  explicit `false` keeps the gate): `telegram-plugin/` is not covered by
+   *  `tsc --noEmit`, so the type alone cannot stop a caller from dropping the
+   *  wiring — and the #4175 precedent is that a dropped bound fails closed,
+   *  never open. */
+  subagentCouldOwnReply: boolean
 }): boolean {
   if (input.tier === 'live') return true
   if (input.tier === 'none') return false
   if (input.handbackCouldOwnReply) return false
+  // Fail-CLOSED on an omitted flag (see the field doc): `!== false`, not truthiness.
+  if (input.subagentCouldOwnReply !== false) return false
   // Total over degenerate input (#3726). TypeScript makes `candidates` mandatory
   // and the one production caller (`resolveReplyOwnerTurn`) always builds it, so
   // this cannot fire today — but this module is exported precisely so the
@@ -260,16 +335,17 @@ export function decideContentGateBypass(input: {
  * handback pattern (#3426): the parent turn's interim ack (a substantive
  * `reply`) armed the latch, the turn ended, and the sub-agent completion
  * handback — a genuinely NEW answer arriving with no live gateway turn —
- * resolved the ended turn as owner (latest-ended tier, inside the 60 s
- * supersede TTL), saw the stale latch, and was silently dropped with a false
+ * resolved the ended turn as owner (latest-ended tier, inside the — then 60 s —
+ * supersede window), saw the stale latch, and was silently dropped with a false
  * "deduped" success. Tagging the source lets the suppression fire ONLY for the
  * flush races it exists for; byte-identical replays of a reply-delivered
  * answer remain covered by the content-keyed outbound dedup (#546).
  *
  * Honest bound on that dedup cover: the #546 TTL (60 s) is anchored at reply
- * RECORD time, while the latest-ended owner tier's 60 s is anchored at the
- * turn's `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
+ * RECORD time, 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 the completion window is evicted from dedup yet
  * still resolves the ended turn, so it DELIVERS as a duplicate message. That
  * is a conscious trade: this fix also drops the weak "reworded/bridge-replayed
  * duplicate" suppression the reply-armed boolean latch used to provide —

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

@@ -23,7 +23,9 @@ import {
   decideSupersedeCorrection,
   flushedAnswerMatchesReply,
   FlushedTurnSupersedeRegistry,
-  DEFAULT_SUPERSEDE_TTL_MS,
+  FlushCompletionTracker,
+  SUPERSEDE_OPEN_WINDOW_CAP_MS,
+  SUPERSEDE_COMPLETED_GRACE_MS,
   SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS,
   type FlushedTurnRecord,
 } from '../flushed-turn-supersede.js'
@@ -33,6 +35,8 @@ const rec = (over: Partial<FlushedTurnRecord> = {}): FlushedTurnRecord => ({
   messageIds: [101, 102],
   text: 'narration\n\nthe real answer',
   ts: 1_000_000,
+  // #4173 — default fixture is an OPEN window (real turn_end not yet observed).
+  completedAt: null,
   ...over,
 })
 
@@ -133,10 +137,60 @@ describe('decideSupersede — the duplicate-reply decision core', () => {
     expect(d.reason).toBe('different-turn')
   })
 
-  it('does NOT supersede once the record is past its TTL', () => {
+  it('2026-08-01 incident gap: an OPEN record is still live 143 s after the flush ' +
+    '(Stop-hook nudge + proactive /compact delayed the canonical reply)', () => {
+    // klanker msgs 25680/25682: under the old 60 s TTL this returned 'expired'
+    // and the reply shipped as a second bubble. With the turn-completion window
+    // (#4173) the record stays claimable while the session is still composing
+    // (real turn_end not yet observed — completedAt null).
     const d = decideSupersede(rec(), {
       liveTurnId: 'turn-A',
-      now: 1_000_000 + DEFAULT_SUPERSEDE_TTL_MS + 1,
+      now: 1_000_000 + 143_000,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+  })
+
+  it('#4173 outcome: an OPEN record survives a 20-minute /compact — any fixed ' +
+    'sub-20-min TTL turns this red', () => {
+    // The point of the completion signal over a widened constant: a compaction
+    // longer than any tuned TTL still collapses to ONE bubble, because the
+    // claude session has not stopped (no real turn_end observed).
+    const d = decideSupersede(rec(), {
+      liveTurnId: 'turn-A',
+      now: 1_000_000 + 20 * 60_000,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+  })
+
+  it('an OPEN record past the crash-backstop cap does NOT supersede', () => {
+    const d = decideSupersede(rec(), {
+      liveTurnId: 'turn-A',
+      now: 1_000_000 + SUPERSEDE_OPEN_WINDOW_CAP_MS + 1,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('expired')
+  })
+
+  it('#4173: a COMPLETED record stays claimable through the replay grace ' +
+    '(the bridge-reconnect tool_call replay class) …', () => {
+    const d = decideSupersede(rec({ completedAt: 1_010_000 }), {
+      liveTurnId: 'turn-A',
+      now: 1_010_000 + SUPERSEDE_COMPLETED_GRACE_MS - 1,
+    })
+    expect(d.supersede).toBe(true)
+  })
+
+  it('… and EXPIRES past the grace — a late claimant (the Task-sub-agent-after-' +
+    'turn-end shape) can no longer reach the record at all', () => {
+    // Once the session stopped and the grace lapsed, nothing may edit/delete
+    // the flushed answer — a genuinely late duplicate ships fresh (safe).
+    const d = decideSupersede(rec({ completedAt: 1_010_000 }), {
+      liveTurnId: 'turn-A',
+      replyText: 'unrelated worker handback content, definitely not the answer',
+      positiveAttribution: true,
+      now: 1_010_000 + SUPERSEDE_COMPLETED_GRACE_MS + 1,
     })
     expect(d.supersede).toBe(false)
     expect(d.reason).toBe('expired')
@@ -249,7 +303,7 @@ describe('FlushedTurnSupersedeRegistry — record / peek / take lifecycle', () =
   })
 
   it('size() evicts expired records and prunes emptied lanes', () => {
-    const reg = new FlushedTurnSupersedeRegistry({ ttlMs: 1000 })
+    const reg = new FlushedTurnSupersedeRegistry({ openCapMs: 1000 })
     reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [1], text: 'a' }, 1000)
     reg.record('chat1', undefined, { turnId: 'turn-B', messageIds: [2], text: 'b' }, 1000)
     expect(reg.size(1500)).toBe(2)
@@ -257,7 +311,7 @@ describe('FlushedTurnSupersedeRegistry — record / peek / take lifecycle', () =
   })
 
   it('record() actively sweeps expired records (LOW-2 GC — no orphan accumulation)', () => {
-    const reg = new FlushedTurnSupersedeRegistry({ ttlMs: 1000 })
+    const reg = new FlushedTurnSupersedeRegistry({ openCapMs: 1000 })
     reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [1], text: 'a' }, 1000)
     // A much later flush on a DIFFERENT lane sweeps the now-expired turn-A record.
     reg.record('chat2', undefined, { turnId: 'turn-B', messageIds: [2], text: 'b' }, 5000)
@@ -434,12 +488,12 @@ describe('positiveAttribution — tier-gated content check', () => {
     expect(d.reason).toBe('different-turn')
   })
 
-  it('positiveAttribution=true still respects the TTL (expired record never supersedes)', () => {
-    const d = decideSupersede(rec({ text: FLUSHED }), {
+  it('positiveAttribution=true still respects the window (expired record never supersedes)', () => {
+    const d = decideSupersede(rec({ text: FLUSHED, completedAt: 1_000_000 }), {
       liveTurnId: 'turn-A',
       replyText: REWORDED,
       positiveAttribution: true,
-      now: 1_000_000 + DEFAULT_SUPERSEDE_TTL_MS + 1,
+      now: 1_000_000 + SUPERSEDE_COMPLETED_GRACE_MS + 1,
     })
     expect(d.supersede).toBe(false)
     expect(d.reason).toBe('expired')
@@ -470,3 +524,51 @@ describe('positiveAttribution — tier-gated content check', () => {
     expect(reg.peek('chatT', undefined, { liveTurnId: 'turn-Q', now: now + 7_000 }).reason).toBe('no-record')
   })
 })
+
+describe('#4173 — turn-completion window plumbing (completeAll / FlushCompletionTracker)', () => {
+  it('completeAll(now) flips OPEN records to grace-bounded; already-completed keep their earlier stamp', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [1], text: 'a' }, 1_000)
+    reg.record('chat1', undefined, { turnId: 'turn-B', messageIds: [2], text: 'b', completedAt: 2_000 }, 1_000)
+    reg.completeAll(50_000)
+    // turn-A: completed at 50s → claimable until 50s+grace, expired after.
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 50_000 + SUPERSEDE_COMPLETED_GRACE_MS - 1 }).supersede).toBe(true)
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 50_000 + SUPERSEDE_COMPLETED_GRACE_MS + 1 }).reason).toBe('expired')
+    // turn-B kept its ORIGINAL earlier completion (2s) — completeAll never widens.
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-B', now: 2_000 + SUPERSEDE_COMPLETED_GRACE_MS + 1 }).reason).toBe('expired')
+  })
+
+  it('a record born completed (flush send finished AFTER the close) is grace-bounded, never open', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    // The close ran at t=5s while the flush send was in flight; record lands at
+    // t=6s carrying the atom's stamped completion.
+    reg.record('chatX', undefined, { turnId: 'turn-C', messageIds: [9], text: 'c', completedAt: 5_000 }, 6_000)
+    expect(reg.peek('chatX', undefined, { liveTurnId: 'turn-C', now: 5_000 + SUPERSEDE_COMPLETED_GRACE_MS + 1 }).reason).toBe('expired')
+  })
+
+  it('FlushCompletionTracker: open() nulls realEndObservedAt; closeAll() stamps every pending atom once', () => {
+    const t = new FlushCompletionTracker()
+    const turnA = { realEndObservedAt: 111 as number | null }
+    const turnB = { realEndObservedAt: 222 as number | null }
+    t.open(turnA)
+    t.open(turnB)
+    expect(turnA.realEndObservedAt).toBeNull()
+    expect(turnB.realEndObservedAt).toBeNull()
+    expect(t.pendingCount()).toBe(2)
+    expect(t.closeAll(9_000)).toBe(2)
+    expect(turnA.realEndObservedAt).toBe(9_000)
+    expect(turnB.realEndObservedAt).toBe(9_000)
+    expect(t.pendingCount()).toBe(0)
+    // Idempotent: nothing pending → nothing closed, stamps untouched.
+    expect(t.closeAll(10_000)).toBe(0)
+    expect(turnA.realEndObservedAt).toBe(9_000)
+  })
+
+  it('FlushCompletionTracker: re-open of the same atom does not double-register', () => {
+    const t = new FlushCompletionTracker()
+    const turn = { realEndObservedAt: null as number | null }
+    t.open(turn)
+    t.open(turn)
+    expect(t.pendingCount()).toBe(1)
+  })
+})

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

@@ -423,6 +423,8 @@ function makeSendReplyDeps(dedup: OutboundDedupCache) {
     streamKey: key,
     resolveReplyOwnerTurn: () => ownerRes(null, 'none'),
     getLastSubagentHandbackAt: () => null,
+    // #4176 — no sub-agent live on this session (see subagent-reply-authority.ts).
+    subagentReplyAuthority: { subagentCouldOwnReply: () => false },
     findTurnByOriginId: () => null,
     findTurnByQuotedMessageId: () => null,
     resolveAnswerThreadWithLog: (_c: string, explicit: number | undefined) => explicit,