switchroom 0.14.57 → 0.14.59

package/telegram-plugin/gateway/gateway.ts

@@ -94,7 +94,7 @@ import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
 import * as pendingProgress from '../pending-work-progress.js'
 import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd } from '../silent-end.js'
-import { isFinalAnswerReply } from '../final-answer-detect.js'
+import { isFinalAnswerReply, isSubstantiveFinalReply } from '../final-answer-detect.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
 import { parseVisibleAnswerStreamEnabled } from '../answer-stream-flag.js'
 import { type SessionEvent } from '../session-tail.js'
@@ -278,10 +278,16 @@ import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
+import {
+  ObligationLedger,
+  buildObligationRepresentInbound,
+  obligationEscalationText,
+} from './obligation-ledger.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { mayDrainBufferedInbound, shouldArmNoReplyDrain } from './serialize-drain-gate.js'
+import { decideFeedReopen } from './feed-reopen-gate.js'
 import { resolveAnswerThreadId } from './answer-thread-resolve.js'
 import {
   createDeliveryQueue,
@@ -1379,6 +1385,20 @@ const DELIVERY_CONFIRM_TIMEOUT_MS =
 const DELIVERY_CONFIRM_SWEEP_MS = 5_000
 const deliveryQueue = createDeliveryQueue<InboundMessage>()
 
+// ─── Deterministic delivery-obligation ledger (systems-analysis PR2) ──────────
+// An inbound is an OBLIGATION (keyed origin_turn_id) that is OPEN at receipt and
+// CLOSED only by an observable substantive reply resolving to that origin —
+// never the model's words. An open obligation that survives a turn boundary is
+// re-presented (bounded) until it closes, so a message the model read but never
+// answered (the marko 715 drop) cannot be silently lost. ADDITIVE + flagged: it
+// runs ALONGSIDE the existing acks/spool/buffer (PR3 retires the redundant
+// pieces). Default OFF — the canary turns it on (713/715 interleave UAT) before
+// any fleet activation. When off, every hook below is a no-op → zero change.
+const OBLIGATION_LEDGER_ENABLED = process.env.SWITCHROOM_OBLIGATION_LEDGER === '1'
+const OBLIGATION_REPRESENT_MAX = 2
+const OBLIGATION_SWEEP_MS = 5_000
+const obligationLedger = new ObligationLedger(OBLIGATION_REPRESENT_MAX)
+
 // ─── Serialize-until-replied (multitopic reply-routing) ───────────────────
 // Component 1 (deliver-before-drain gate). A buffered cross-topic inbound
 // drains ONLY after the just-ended turn delivered its reply to its own
@@ -1419,6 +1439,35 @@ const TOPIC_FRAMING_ENABLED =
 // → no placeholder (the 👀 ack reaction still fires). Delete-on-answer.
 const QUEUED_STATUS_UX_ENABLED =
   process.env.SWITCHROOM_QUEUED_STATUS_UX !== '0'
+// Feed-reopen-after-ack. When a tool label arrives for a turn already
+// marked finalAnswerDelivered, the model is still WORKING — so the earlier
+// "final" reply was an interim ACK (an ack-first reply pings or runs ≥200
+// chars, both of which isFinalAnswerReply classifies as final). Re-open the
+// live activity feed for the post-ack work instead of dropping the label.
+// Kill switch off (=0) → legacy behaviour: the label is dropped and the
+// post-ack feed stays dark. See `feed-reopen-gate.ts` for the rationale and
+// the finalAnswerDelivered-consumer interactions.
+const FEED_REOPEN_AFTER_ACK_ENABLED =
+  process.env.SWITCHROOM_FEED_REOPEN_AFTER_ACK !== '0'
+
+// Activity-feed heartbeat (PR1). The feed is pull-only — it only re-renders on
+// a tool_label event, so a long single step that emits no new label leaves the
+// feed frozen on "→ doing X" for tens of seconds (the marko ~26s freeze). The
+// heartbeat re-renders the live feed every FEED_HEARTBEAT_TICK_MS with a
+// climbing " · Ns" elapsed on the in-progress line, but only once the current
+// step has run >= FEED_HEARTBEAT_MIN_STALE_MS (so a normally-advancing feed is
+// untouched). Kill switch: SWITCHROOM_FEED_HEARTBEAT=0. Default on.
+const FEED_HEARTBEAT_ENABLED = process.env.SWITCHROOM_FEED_HEARTBEAT !== '0'
+const FEED_HEARTBEAT_TICK_MS = 6_000
+const FEED_HEARTBEAT_MIN_STALE_MS = 6_000
+
+/** Compact mm/ss-ish elapsed for the live feed suffix: "18s", "1m05s". */
+function formatFeedElapsed(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  return `${m}m${(s % 60).toString().padStart(2, '0')}s`
+}
 
 /**
  * Authoritative "is a turn in flight?" for every gate that previously
@@ -1552,6 +1601,20 @@ type CurrentTurn = {
   // even though `replyCalled` is true — the #1664 case where the real answer
   // ended up as plain transcript text rendered into an ephemeral draft.
   finalAnswerDelivered: boolean
+  // Feed-reopen-after-ack refinement — whether the reply that set
+  // `finalAnswerDelivered` was a *substantive* final answer (stream
+  // `done`, or ≥200 chars) as opposed to a short pinging interim ACK.
+  // Set via `isSubstantiveFinalReply` at every site that sets
+  // `finalAnswerDelivered = true`. The tool_label handler re-opens the
+  // live activity feed ONLY when `finalAnswerDelivered && !finalAnswer-
+  // Substantive` (the prior "final" was an ack). After a genuine final
+  // answer this stays true, so routine post-answer housekeeping (memory
+  // write / TodoWrite / Bash — non-surface tools that reach the handler)
+  // does NOT reopen and does NOT reset `finalAnswerDelivered`, which would
+  // otherwise spuriously trip the silent-end re-prompt → duplicate answer.
+  // Reset to false on every fresh-turn enqueue alongside
+  // `finalAnswerDelivered`.
+  finalAnswerSubstantive: boolean
   // #1675 (over-ping safety net): wall-clock ms of the first reply
   // this turn that landed with `disable_notification: false` (a real
   // device ping). The conversational-pacing contract
@@ -1628,6 +1691,12 @@ type CurrentTurn = {
   activityInFlight: Promise<void> | null
   activityPendingRender: string | null
   activityLastSentRender: string | null
+  // Wall-clock anchor for the newest in-progress feed step — set each time a
+  // tool_label re-renders the feed. The heartbeat (`feedHeartbeatTick`) reads
+  // it to show a climbing " · Ns" elapsed on the live line so a long single
+  // step that emits no new label doesn't read as frozen (the feed is otherwise
+  // pull-only). undefined until the first label of the turn renders.
+  lastToolLabelAt?: number
   // Accumulating friendly-action feed for this turn. Each non-surface
   // tool_label appends a line via `appendActivityLabel`; the feed renders
   // (via `renderActivityFeed`) as a capped chronological list into the
@@ -1702,6 +1771,69 @@ function findTurnByOriginId(originTurnId: string | null | undefined): CurrentTur
   return recentTurnsById.get(originTurnId) ?? null
 }
 
+/**
+ * PR2 obligation-ledger CLOSE. Called when a SUBSTANTIVE final answer lands
+ * (not a bare interim ack — using finalAnswerSubstantive, the #2141 signal): the
+ * obligation discharged is the one for the SAME origin the answer routes to
+ * (origin_turn_id the model echoed, else the live turn). So 713's reply closes
+ * 713's obligation even after currentTurn flipped to 715, and 715 stays open
+ * until ITS own substantive answer. An ack does NOT close (so ack-then-ghost is
+ * re-presented, not re-dropped). turn.turnId === the obligation's origin id
+ * (both deriveTurnId(chat,thread,messageId) of the same inbound). No-op unless
+ * the flag is on. NOTE residual: a genuinely SHORT answer (<200 chars, not a
+ * stream-done) reads as non-substantive and won't close → a bounded re-ask
+ * (≤2) then one operator-visible nudge — the accepted double-ask tradeoff,
+ * measured in the canary.
+ */
+function closeObligationOnSubstantiveReply(
+  args: Record<string, unknown>,
+  liveTurn: CurrentTurn | null | undefined,
+): void {
+  if (!OBLIGATION_LEDGER_ENABLED) return
+  const echoed = findTurnByOriginId(args.origin_turn_id as string | undefined)
+  const target = obligationLedger.resolveCloseTarget(echoed?.turnId, liveTurn?.turnId)
+  if (target != null) obligationLedger.close(target)
+}
+
+/**
+ * PR2 obligation-ledger OPEN. Track a fresh user inbound as an unanswered
+ * obligation the moment it is received — called BEFORE the buffer-until-idle /
+ * deliver split so a mid-turn cross-topic inbound (the 715 case: buffered while
+ * another turn runs) is tracked too. Drain paths re-deliver buffered inbounds
+ * via sendToAgent (NOT through handleInbound), so handleInbound is the ONLY
+ * point that sees every fresh inbound — opening here is mandatory for both
+ * branches. Same gate as delivery-tracking (real user turns only; synthetic /
+ * steering / `!` interrupt / empty excluded — they have no origin id / need no
+ * answer; deriveTurnId null-guards them). Idempotent → opening at buffer-time
+ * and any later delivery is safe. No-op unless the flag is on.
+ */
+function openObligationFromInbound(
+  inboundMsg: InboundMessage,
+  gate: { isSteering: boolean; isInterrupt: boolean; effectiveText: string },
+): void {
+  if (!OBLIGATION_LEDGER_ENABLED) return
+  if (
+    !shouldTrackDelivery({
+      isSteering: gate.isSteering,
+      isInterrupt: gate.isInterrupt,
+      hasSource: inboundMsg.meta?.source != null,
+      effectiveText: gate.effectiveText,
+    })
+  ) {
+    return
+  }
+  const oid = deriveTurnId(inboundMsg.chatId, inboundMsg.threadId, inboundMsg.messageId)
+  if (oid == null) return
+  obligationLedger.openIfAbsent({
+    originTurnId: oid,
+    chatId: inboundMsg.chatId,
+    threadId: inboundMsg.threadId,
+    messageId: inboundMsg.messageId,
+    text: inboundMsg.text ?? '',
+    openedAt: Date.now(),
+  })
+}
+
 /**
  * Component 5 — post a "Queued — replying in another topic first" status
  * into a cross-topic buffered message's OWN topic. Fire-and-forget through
@@ -4675,6 +4807,51 @@ const inboundSpool = STATIC
       },
     })
 const pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool })
+
+// PR2 obligation-ledger idle sweep. Re-present an OPEN obligation only at a
+// CLEAN idle: no turn in flight AND the inbound buffer is empty — so the
+// existing buffer-drain has already had its turn and anything still OPEN is
+// "delivered but never answered" (the 715 gap). Re-present by pushing a
+// synthetic must-answer inbound through the SAME buffer→drain path (idempotent
+// OPEN via meta.source; reuses tested delivery). Bounded: after maxRepresents,
+// escalate to ONE operator-visible "did I miss this?" and close — no loop.
+// No-op unless the flag is on; gated on the same idle predicate as the drains.
+function obligationSweep(): void {
+  if (!OBLIGATION_LEDGER_ENABLED) return
+  if (!obligationLedger.hasOpen()) return
+  if (turnInFlightForGate()) return // a turn is running — let it finish/answer
+  const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  if (pendingInboundBuffer.depth(agent) > 0) return // existing drain runs first; avoids double-present
+  const decision = obligationLedger.decideAtIdle()
+  const o = decision.obligation
+  if (decision.action === 'none' || o == null) return
+  if (decision.action === 'represent') {
+    pendingInboundBuffer.push(agent, buildObligationRepresentInbound(o, Date.now()))
+    const attempt = obligationLedger.markRepresented(o.originTurnId)
+    process.stderr.write(
+      `telegram gateway: obligation re-presented origin=${o.originTurnId} attempt=${attempt}/${OBLIGATION_REPRESENT_MAX}\n`,
+    )
+    return
+  }
+  // escalate — close FIRST so the loop ends even if the send fails.
+  obligationLedger.close(o.originTurnId)
+  process.stderr.write(
+    `telegram gateway: obligation escalated (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${o.originTurnId}\n`,
+  )
+  void robustApiCall(
+    () =>
+      bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
+        ...(o.threadId != null ? { message_thread_id: o.threadId } : {}),
+      }),
+    { chat_id: o.chatId, ...(o.threadId != null ? { threadId: o.threadId } : {}), verb: 'obligation.escalate' },
+  ).catch((err) => {
+    process.stderr.write(`telegram gateway: obligation escalation send failed: ${err}\n`)
+  })
+}
+if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
+  setInterval(obligationSweep, OBLIGATION_SWEEP_MS).unref()
+}
+
 // Honest-restart-resume: inject the boot resume/report inbound built by the
 // registry classifier above. When the spool exists we only PUT it (the
 // boot-replay loop below pulls it into the in-memory buffer exactly once via
@@ -6305,6 +6482,13 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
             })
           ) {
             turn.finalAnswerDelivered = true
+            // Feed-reopen refinement: a substantive merged silent-anchor
+            // answer must NOT re-open the feed on post-answer housekeeping.
+            turn.finalAnswerSubstantive = isSubstantiveFinalReply({
+              text: decision.mergedText,
+              disableNotification,
+            })
+            if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn)
           }
           outboundDedup.record(
             chat_id,
@@ -6644,6 +6828,10 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     // end re-prompt from spuriously firing on a delivered final.
     if (turn != null && isFinalAnswerReply({ text: rawText, disableNotification })) {
       turn.finalAnswerDelivered = true
+      // Feed-reopen refinement: track whether this final was substantive
+      // (≥200 chars or stream-done — not a short pinging ack) so post-answer
+      // housekeeping tool work does NOT re-open the feed / trip silent-end.
+      turn.finalAnswerSubstantive = isSubstantiveFinalReply({ text: rawText, disableNotification })
       // #1728: release the buffer gate + emit terminal 👍. Mid-turn
       // acks bypass this branch and remain non-events for the
       // reaction (preserves #1713). The full turn-state teardown
@@ -6651,6 +6839,9 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
       // the `turn_end` handler when it lands; this only fires the
       // observable side effects that #1718 deferred unconditionally.
       finalizeStatusReaction(chat_id, threadId, 'done')
+      // PR2: close this origin's obligation on a SUBSTANTIVE final answer
+      // (after finalize so the reaction guard test's anchor window is stable).
+      if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn)
     }
     // v0.13.30 follow-up — release the buffer gate on EVERY reply
     // finalize, not just on `isFinalAnswerReply`. The narrow
@@ -6987,6 +7178,15 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
     })
   ) {
     turn.finalAnswerDelivered = true
+    // Feed-reopen refinement: a stream_reply done=true (or a ≥200-char
+    // chunk) is substantive; a short pinging non-done chunk is an ack. Only
+    // the latter should re-open the feed on subsequent post-answer work.
+    turn.finalAnswerSubstantive = isSubstantiveFinalReply({
+      text: (args.text as string | undefined) ?? '',
+      disableNotification: args.disable_notification === true,
+      done: args.done === true,
+    })
+    if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn)
     // #1744 follow-up — stream_reply edge case. The first-emit gate at
     // L5178 only clears silent-end state on the FIRST emit of a stream.
     // If a stream's first emit was ack-shaped (disable_notification:true,
@@ -8374,12 +8574,12 @@ const FOREGROUND_SUBAGENT_ACCUM_MAX = 12
  * order; the single-sub-agent common case nests precisely under its
  * Delegating line.
  */
-function composeTurnActivity(turn: CurrentTurn, final = false): string | null {
+function composeTurnActivity(turn: CurrentTurn, final = false, liveSuffix = ''): string | null {
   const childLines: string[] = []
   for (const narrative of turn.foregroundSubAgents.values()) {
     childLines.push(...narrative)
   }
-  return renderActivityFeedWithNested(turn.mirrorLines, childLines, final)
+  return renderActivityFeedWithNested(turn.mirrorLines, childLines, final, liveSuffix)
 }
 
 /**
@@ -8452,6 +8652,35 @@ async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
   }
 }
 
+/**
+ * Heartbeat tick (PR1): keep the live activity feed visibly advancing during a
+ * long single step that emits no new tool_label. Re-renders the feed with a
+ * climbing " · Ns" elapsed on the in-progress line through the SAME single-flight
+ * drain path the tool_label handler uses (no separate transport, no race). Pure
+ * no-op unless there is a live in-flight feed whose newest step has gone stale.
+ * Skips once the final answer landed (the feed is handing off) and after the
+ * turn ends (activityMessageId nulled by clearActivitySummary). Deterministic +
+ * framework-owned — never depends on the model.
+ */
+function feedHeartbeatTick(): void {
+  const turn = currentTurn
+  if (turn == null) return
+  if (turn.activityMessageId == null) return // no live feed yet / already cleared
+  if (turn.finalAnswerDelivered) return // feed handed off to the answer
+  if (turn.lastToolLabelAt == null) return // feed not driven by a labelled step
+  const elapsed = Date.now() - turn.lastToolLabelAt
+  if (elapsed < FEED_HEARTBEAT_MIN_STALE_MS) return // step is fresh; feed advancing normally
+  const rendered = composeTurnActivity(turn, false, ` · ${formatFeedElapsed(elapsed)}`)
+  if (rendered == null) return
+  turn.activityPendingRender = rendered
+  if (turn.activityInFlight == null) {
+    turn.activityInFlight = drainActivitySummary(turn)
+  }
+}
+if (!STATIC && FEED_HEARTBEAT_ENABLED) {
+  setInterval(feedHeartbeatTick, FEED_HEARTBEAT_TICK_MS).unref()
+}
+
 /**
  * Reconcile the activity summary when the model's reply tool takes over as the
  * authoritative surface. Awaits any in-flight render so we don't race a stale
@@ -8577,6 +8806,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           finalAnswerDelivered: false,
+          finalAnswerSubstantive: false,
           firstPingAt: null,
           silentAnchorMessageId: null,
           silentAnchorText: '',
@@ -8794,9 +9024,59 @@ function handleSessionEvent(ev: SessionEvent): void {
       // the FINAL answer would re-`sendMessage` a fresh feed below it (flicker).
       // Safe ordering: `tool_label` is real-time (PreToolUse, ~250ms) while
       // `finalAnswerDelivered` is set from executeReply on the final answer.
-      if (turn.finalAnswerDelivered) return
+      //
+      // Feed-reopen-after-ack: a tool label here means the model is STILL
+      // working. If the turn was already marked finalAnswerDelivered, the
+      // "final" reply MIGHT have been an interim ACK ("on it, checking
+      // Brevo…" pings, classified final by isFinalAnswerReply), so the
+      // post-ack work had no live feed — the gate above dropped every label.
+      //
+      // ACK-ONLY refinement: finalAnswerDelivered latches true for BOTH a
+      // short pinging ack AND a substantive answer. Reopening unconditionally
+      // is harmful after a GENUINE final answer — routine post-answer
+      // housekeeping (memory write / TodoWrite / Bash; non-surface tools that
+      // reach here) would reset finalAnswerDelivered=false and trip the
+      // silent-end re-prompt (NOT zero-outbound gated) → duplicate answer. So
+      // reopen ONLY when the prior final was a short ack
+      // (finalAnswerSubstantive=false). When it was substantive, drop the
+      // label (legacy gate) so the genuine final stays delivered.
+      //
+      // On reopen: reclassify the interim ack — the turn has NOT delivered its
+      // final answer while still doing tool work. Reset the flag and clear
+      // activityMessageId so a FRESH feed message opens below the ack, then
+      // proceed normally. When the model's REAL final answer lands,
+      // executeReply / stream_reply re-set finalAnswerDelivered=true (and
+      // finalAnswerSubstantive) and the feed gates off again. The reset keeps
+      // the #2137 serialize gate HOLDING the next topic mid-work (next-topic
+      // liveness is the bounded no-reply timer's job) and lets the silent-end
+      // re-prompt fire if the turn ends on only an ack.
+      // Kill switch SWITCHROOM_FEED_REOPEN_AFTER_ACK=0 → legacy `return`.
+      if (turn.finalAnswerDelivered) {
+        // decideFeedReopen returns dropLabel (legacy return) or the reset
+        // deltas: finalAnswerDelivered→false (the turn has NOT delivered its
+        // final answer while still doing tool work), activityMessageId→null
+        // (a FRESH feed message opens below the ack), activityLastSentRender
+        // →null (so the drain loop's `pending !== lastSent` guard never
+        // mistakes the fresh render for the ack's finalized one and skips it).
+        const reopen = decideFeedReopen({
+          finalAnswerDelivered: turn.finalAnswerDelivered,
+          // ACK-ONLY: reopen only when the prior final was a short ack, not a
+          // substantive answer — otherwise post-answer housekeeping would
+          // reset finalAnswerDelivered and trip the silent-end re-prompt.
+          finalAnswerSubstantive: turn.finalAnswerSubstantive,
+          enabled: FEED_REOPEN_AFTER_ACK_ENABLED,
+        })
+        if (reopen.dropLabel) return
+        turn.finalAnswerDelivered = reopen.reset!.finalAnswerDelivered
+        turn.activityMessageId = reopen.reset!.activityMessageId
+        turn.activityLastSentRender = reopen.reset!.activityLastSentRender
+      }
       const rendered = appendActivityLabel(turn.mirrorLines, ev.label)
       if (rendered != null) {
+        // A new tool label = a new live step → re-anchor the heartbeat clock so
+        // the " · Ns" elapsed restarts from this step (and the feed itself just
+        // advanced, so it isn't stale).
+        turn.lastToolLabelAt = Date.now()
         // Recompose so any active foreground sub-agent's nested block (Model A)
         // is preserved when the parent appends its own step. composeTurnActivity
         // == the flat render when no foreground sub-agent is active.
@@ -9148,6 +9428,11 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.answerStream = null
           streamFinalizedAsAnswer = true
           turn.finalAnswerDelivered = true
+          // Feed-reopen refinement: the stream is being finalized as the
+          // turn's answer (the model's terminal text), i.e. done=true by
+          // construction → substantive. Post-answer housekeeping must NOT
+          // re-open the feed.
+          turn.finalAnswerSubstantive = true
           // Capture the old streamed message_id BEFORE materialize so
           // we can delete it after the fresh ping send. materialize()
           // overwrites `streamMsgId` internally with the new send's id;
@@ -9424,6 +9709,12 @@ function handleSessionEvent(ev: SessionEvent): void {
         // it keeps the captured `turn` atom internally consistent for any
         // future reader.)
         turn.finalAnswerDelivered = true
+        // Feed-reopen refinement: turn-flush delivers the model's terminal
+        // transcript text as the genuine answer (not an ack). Default to
+        // substantive so a late tool label does NOT re-open the feed / trip
+        // the silent-end re-prompt. (Belt-and-braces, like the set above —
+        // this branch returns before any further tool_label can arrive.)
+        turn.finalAnswerSubstantive = true
 
         // #654 deterministic double-message fix. Hand off the pinned
         // progress card BEFORE state reset so the driver doesn't keep
@@ -11336,6 +11627,15 @@ async function handleInbound(
     return
   }
 
+  // PR2 obligation-ledger OPEN — BEFORE the buffer-until-idle / deliver split so
+  // a mid-turn cross-topic inbound (the 715 case) is tracked whether it is
+  // buffered or delivered now. Idempotent + gated; no-op when the flag is off.
+  openObligationFromInbound(inboundMsg, {
+    isSteering,
+    isInterrupt: interrupt.isInterrupt,
+    effectiveText,
+  })
+
   if (
     decideInboundDelivery({
       turnInFlight: turnInFlightAtReceipt,

package/telegram-plugin/gateway/obligation-ledger.ts

@@ -0,0 +1,216 @@
+/**
+ * Deterministic delivery-obligation ledger (systems-analysis PR2).
+ *
+ * The framework today tracks whether an inbound was DELIVERED (read by claude),
+ * never whether it was ANSWERED — so a message claude reads but never replies to
+ * (the marko msg-715 verbal-deferral drop) is silently lost. This ledger adds
+ * the one missing invariant, and it is model-INDEPENDENT by construction:
+ *
+ *   An inbound is an OBLIGATION keyed by its origin_turn_id. It is OPEN the
+ *   moment the message is received, and CLOSED only by an observable framework
+ *   event — a reply-tool call whose resolved target equals that origin_turn_id
+ *   AND that carries a substantive answer (not a bare interim ack). The engine
+ *   may go idle only when no obligation is OPEN; an OPEN obligation that
+ *   survives a turn boundary is re-presented as a fresh must-answer turn until
+ *   it closes, bounded so a mis-close degrades to ONE operator-visible nudge
+ *   rather than an infinite re-ask loop.
+ *
+ * This file is PURE state + decisions — no Telegram, no claude, no timers. The
+ * gateway owns OPEN/CLOSE/re-present I/O and calls in here. Pure ⇒ unit-testable
+ * (see tests/obligation-ledger.test.ts), the seam the analysis demanded.
+ *
+ * The close event (substantive reply resolving to origin) is observed by the
+ * framework, never the model's narration/promise — that is the whole point: the
+ * 715 "I'll handle thread 3 as its own turn" does NOT close the obligation.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+export interface Obligation {
+  /** deriveTurnId(chat, thread, messageId) — the stable identity. */
+  readonly originTurnId: string
+  readonly chatId: string
+  readonly threadId?: number
+  readonly messageId: number
+  /** Original inbound text (may be truncated by the caller for re-presentation). */
+  readonly text: string
+  /** Wall-clock ms the obligation was first opened. */
+  readonly openedAt: number
+  /** How many times it has been re-presented (0 on first open). */
+  representCount: number
+}
+
+/** What the gateway should do for the oldest open obligation at an idle boundary. */
+export type LedgerAction = 'none' | 'represent' | 'escalate'
+
+export interface LedgerDecision {
+  action: LedgerAction
+  obligation?: Obligation
+}
+
+export interface ObligationInput {
+  originTurnId: string
+  chatId: string
+  threadId?: number
+  messageId: number
+  text: string
+  openedAt: number
+}
+
+export class ObligationLedger {
+  private readonly open = new Map<string, Obligation>()
+
+  /**
+   * @param maxRepresents max re-presentations before escalating to an
+   *   operator-visible nudge instead of re-asking again. Default 2.
+   */
+  constructor(private readonly maxRepresents = 2) {}
+
+  /**
+   * Open an obligation if not already tracked. Idempotent on originTurnId — a
+   * message that is buffered AND later enqueued opens once, keeping the first
+   * (earliest openedAt + accumulated representCount). Returns true if newly
+   * opened.
+   */
+  openIfAbsent(input: ObligationInput): boolean {
+    if (this.open.has(input.originTurnId)) return false
+    this.open.set(input.originTurnId, { ...input, representCount: 0 })
+    return true
+  }
+
+  /** Close by origin id. Returns true if an obligation was open and is now closed. */
+  close(originTurnId: string | null | undefined): boolean {
+    if (originTurnId == null) return false
+    return this.open.delete(originTurnId)
+  }
+
+  isOpen(originTurnId: string): boolean {
+    return this.open.has(originTurnId)
+  }
+
+  hasOpen(): boolean {
+    return this.open.size > 0
+  }
+
+  size(): number {
+    return this.open.size
+  }
+
+  /** Snapshot of open obligations, oldest first. For introspection/tests. */
+  list(): Obligation[] {
+    return [...this.open.values()].sort((a, b) => a.openedAt - b.openedAt)
+  }
+
+  /** The oldest open obligation, or undefined. */
+  private oldest(): Obligation | undefined {
+    let best: Obligation | undefined
+    for (const o of this.open.values()) {
+      if (best === undefined || o.openedAt < best.openedAt) best = o
+    }
+    return best
+  }
+
+  /**
+   * Decide what to do at an idle boundary (caller guarantees: no turn in flight
+   * AND the inbound buffer is empty — so the existing buffer-drain has already
+   * had its turn and anything still OPEN is "delivered but unanswered"). PURE —
+   * does not mutate. The caller performs the side effect then calls
+   * markRepresented / close accordingly.
+   *
+   *  - 'none'      → no open obligation; the agent may idle.
+   *  - 'represent' → re-present `obligation` as a fresh must-answer turn.
+   *  - 'escalate'  → it has already been re-presented maxRepresents times; send
+   *                  ONE operator-visible "did I miss this?" and close it
+   *                  (caller calls close) rather than loop forever.
+   */
+  decideAtIdle(): LedgerDecision {
+    const o = this.oldest()
+    if (o === undefined) return { action: 'none' }
+    if (o.representCount >= this.maxRepresents) return { action: 'escalate', obligation: o }
+    return { action: 'represent', obligation: o }
+  }
+
+  /**
+   * Decide which obligation a substantive reply discharges — DETERMINISTICALLY,
+   * holding for any model behavior:
+   *  - `echoedTurnId` (the model echoed origin_turn_id back) → authoritative;
+   *    close exactly that (a no-op via close() if it isn't actually open).
+   *  - else, close the live turn's obligation ONLY when UNAMBIGUOUS — exactly
+   *    one obligation open. With >1 open and no echo we cannot tell which one
+   *    the reply answered; closing the live turn's would silently drop the other
+   *    (713's un-echoed reply landing while currentTurn=715 must NOT close 715).
+   *    So we close nothing → the real target stays open and is re-presented (a
+   *    bounded double-ask), never wrong-closed. Returns the id to close, or null.
+   */
+  resolveCloseTarget(
+    echoedTurnId: string | null | undefined,
+    liveTurnId: string | null | undefined,
+  ): string | null {
+    if (echoedTurnId != null) return echoedTurnId
+    if (liveTurnId != null && this.open.size === 1 && this.open.has(liveTurnId)) return liveTurnId
+    return null
+  }
+
+  /** Record that an obligation was just re-presented (bumps representCount). */
+  markRepresented(originTurnId: string): number {
+    const o = this.open.get(originTurnId)
+    if (o === undefined) return 0
+    o.representCount += 1
+    return o.representCount
+  }
+}
+
+/** Original message preview length for re-presentation (mirrors resume builder). */
+const REPRESENT_PREVIEW_MAX = 200
+
+/**
+ * Build the synthetic inbound that RE-PRESENTS an open obligation as a fresh
+ * must-answer turn. Carries the obligation's original message_id (so the
+ * reply-quote and origin routing land in the right place) and origin_turn_id in
+ * meta (so the model's reply resolves back to THIS obligation → the close event
+ * matches). `source: obligation_represent` marks it synthetic, so it is NOT
+ * delivery-tracked and does NOT open a fresh obligation (the original stays
+ * open until a substantive reply closes it). Pure — the gateway injects it via
+ * the existing buffer→drain path. Context restoration (inject vs pointer) is a
+ * separate layer; here we point at get_recent_messages and quote the original.
+ */
+export function buildObligationRepresentInbound(o: Obligation, now: number): InboundMessage {
+  const preview =
+    o.text.length > REPRESENT_PREVIEW_MAX ? o.text.slice(0, REPRESENT_PREVIEW_MAX - 1) + '…' : o.text
+  const topicClause = o.threadId != null ? ' in this topic' : ''
+  return {
+    type: 'inbound',
+    chatId: o.chatId,
+    ...(o.threadId != null ? { threadId: o.threadId } : {}),
+    messageId: o.messageId,
+    user: 'switchroom',
+    userId: 0,
+    ts: now,
+    text:
+      `You have an earlier message${topicClause} that you started but never actually ` +
+      `answered (you may have set it aside mid-work): "${preview}". Answer it now via the ` +
+      `reply tool — deliver the real answer, don't just acknowledge it. If you've lost the ` +
+      `surrounding context, call get_recent_messages for this chat${topicClause} first. ` +
+      `That quoted text may be only the first ~200 characters of the original.`,
+    meta: {
+      source: 'obligation_represent',
+      origin_turn_id: o.originTurnId,
+      represent_count: String(o.representCount + 1),
+    },
+  }
+}
+
+/**
+ * Build the operator-visible escalation message text, used when an obligation
+ * has been re-presented maxRepresents times without closing — rather than loop
+ * forever (the new failure mode this trades silent-drop for), surface ONE
+ * honest "did I miss this?" and close it.
+ */
+export function obligationEscalationText(o: Obligation): string {
+  const preview =
+    o.text.length > REPRESENT_PREVIEW_MAX ? o.text.slice(0, REPRESENT_PREVIEW_MAX - 1) + '…' : o.text
+  return (
+    `⚠️ I may have missed an earlier message and I'm not sure I answered it: ` +
+    `"${preview}". If you still need it, please re-send.`
+  )
+}