switchroom 0.14.58 → 0.14.60

package/telegram-plugin/gateway/gateway.ts

@@ -278,6 +278,11 @@ 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'
@@ -1380,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
@@ -1431,6 +1450,25 @@ const QUEUED_STATUS_UX_ENABLED =
 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
  * read `claudeBusyKeys.size`. PR 3b cutover (extends PR 3a's bridgeUp
@@ -1653,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
@@ -1727,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
@@ -2247,6 +2354,21 @@ function releaseTurnBufferGate(key: string, endingTurn?: CurrentTurn): void {
 function endCurrentTurnAtomic(turn: CurrentTurn): void {
   if (currentTurn !== turn) return
   currentTurn = null
+  // PR2 obligation-ledger CLOSE-at-turn-end. Close the ended turn's obligation
+  // when it delivered a final answer. finalAnswerDelivered is the right signal
+  // HERE (not isSubstantiveFinalReply at reply-time): a SHORT genuine answer
+  // ("4") is final-but-not-substantive, so the reply-time substantive-close
+  // missed it → it looked unanswered → the idle sweep double-asked every short
+  // turn (canary, v0.14.59). At turn_end the #2141 logic has already demoted a
+  // bare interim ack to non-final, so finalAnswerDelivered===true means GENUINELY
+  // answered. This runs before the next idle sweep, so a short answer closes
+  // cleanly (no double-ask); an ack-then-ghost / no-reply turn ends with
+  // finalAnswerDelivered===false → stays open → re-presented (the intended
+  // catch). close() is a no-op for synthetic turns (turnId not in the ledger).
+  // No-op when the flag is off.
+  if (OBLIGATION_LEDGER_ENABLED && turn.finalAnswerDelivered) {
+    obligationLedger.close(turn.turnId)
+  }
   // Component 2 — clear any prior no-reply drain timer for this turn; a
   // fresh end re-evaluates below. (Idempotent — null when never armed.)
   if (turn.noReplyDrainTimer != null) {
@@ -4700,6 +4822,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
@@ -6336,6 +6503,7 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
               text: decision.mergedText,
               disableNotification,
             })
+            if (turn.finalAnswerSubstantive) closeObligationOnSubstantiveReply(args, turn)
           }
           outboundDedup.record(
             chat_id,
@@ -6686,6 +6854,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
@@ -7030,6 +7201,7 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       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,
@@ -8417,12 +8589,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)
 }
 
 /**
@@ -8495,6 +8667,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
@@ -8887,6 +9088,10 @@ function handleSessionEvent(ev: SessionEvent): void {
       }
       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.
@@ -11437,6 +11642,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.`
+  )
+}