switchroom 0.14.62 → 0.14.64

package/dist/cli/switchroom.js

@@ -49452,8 +49452,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.62";
-var COMMIT_SHA = "3967bb6f";
+var VERSION = "0.14.64";
+var COMMIT_SHA = "fb6bbe00";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.62",
+  "version": "0.14.64",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -41593,6 +41593,33 @@ function formatReplyToText(text, maxChars) {
   return escapeXmlAttribute(truncated);
 }
 
+// gateway/auto-classify-mid-turn.ts
+function sameThread(a, b) {
+  const norm = (t) => t == null || t === 0 ? null : t;
+  return norm(a) === norm(b);
+}
+function autoClassifyMidTurnInbound(i) {
+  if (i.isSteerPrefix)
+    return { decision: "steer", reason: "steer_prefix" };
+  if (i.isQueuePrefix)
+    return { decision: "queue", reason: "queue_prefix" };
+  if (!i.priorTurnInFlight)
+    return { decision: "queue", reason: "not_mid_turn" };
+  const recent = i.msSinceLastAgentOutput != null && i.msSinceLastAgentOutput >= 0;
+  if (i.isDm) {
+    if (i.dmSteerWindowMs <= 0)
+      return { decision: "queue", reason: "dm_disabled" };
+    return recent && i.msSinceLastAgentOutput <= i.dmSteerWindowMs ? { decision: "steer", reason: "dm_recent" } : { decision: "queue", reason: "dm_disabled" };
+  }
+  const topicMatch = sameThread(i.incomingThreadId, i.activeTurnThreadId);
+  if (i.topicSteerWindowMs <= 0) {
+    return { decision: "queue", reason: "topic_disabled", sameTopic: topicMatch };
+  }
+  if (!topicMatch)
+    return { decision: "queue", reason: "cross_topic", sameTopic: false };
+  return recent && i.msSinceLastAgentOutput <= i.topicSteerWindowMs ? { decision: "steer", reason: "same_topic_recent", sameTopic: true } : { decision: "queue", reason: "same_topic_stale", sameTopic: true };
+}
+
 // operator-events.ts
 function renderOperatorEvent(ev) {
   const agent = escHtml(ev.agent);
@@ -47443,14 +47470,31 @@ class ObligationLedger {
     }
     return best;
   }
-  decideAtIdle() {
-    const o = this.oldest();
+  decideAtIdle(opts) {
+    const o = opts != null && opts.graceMs > 0 ? this.oldestEligible(opts.now, opts.graceMs) : this.oldest();
     if (o === undefined)
       return { action: "none" };
     if (o.representCount >= this.maxRepresents)
       return { action: "escalate", obligation: o };
     return { action: "represent", obligation: o };
   }
+  oldestEligible(now, graceMs) {
+    let best;
+    for (const o of this.open.values()) {
+      if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs)
+        continue;
+      if (best === undefined || o.openedAt < best.openedAt)
+        best = o;
+    }
+    return best;
+  }
+  noteTurnEnded(originTurnId, ts) {
+    const o = this.open.get(originTurnId);
+    if (o === undefined)
+      return;
+    o.lastTurnEndedAt = ts;
+    this.persist();
+  }
   resolveCloseTarget(echoedTurnId, liveTurnId) {
     if (echoedTurnId != null)
       return echoedTurnId;
@@ -47555,6 +47599,35 @@ function withDeadline(p, ms, timeoutMessage) {
   });
 }
 
+// gateway/escalation-drive.ts
+function driveEscalation(args) {
+  const { escId, inFlight, ledger, send, maxAttempts, deadlineMs } = args;
+  const log = args.log ?? ((l) => process.stderr.write(l));
+  const wd = args.withDeadlineFn ?? withDeadline;
+  if (inFlight.has(escId))
+    return;
+  const attempt = ledger.markEscalateAttempt(escId);
+  inFlight.add(escId);
+  log(`telegram gateway: obligation escalating origin=${escId} attempt=${attempt}/${maxAttempts}
+`);
+  return wd(send(), deadlineMs, "obligation escalation send timed out").then(() => {
+    ledger.close(escId);
+    log(`telegram gateway: obligation escalation delivered + closed origin=${escId}
+`);
+  }).catch((err) => {
+    if (attempt >= maxAttempts) {
+      ledger.close(escId);
+      log(`telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts \u2014 closing best-effort origin=${escId}: ${err}
+`);
+    } else {
+      log(`telegram gateway: obligation escalation send failed (attempt ${attempt}/${maxAttempts}), retrying next sweep origin=${escId}: ${err}
+`);
+    }
+  }).finally(() => {
+    inFlight.delete(escId);
+  });
+}
+
 // gateway/inbound-spool.ts
 function spoolId(msg) {
   if (msg.meta?.source === "subagent_handback" && typeof msg.meta?.subagent_jsonl_id === "string" && msg.meta.subagent_jsonl_id.length > 0) {
@@ -52647,10 +52720,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.62";
-var COMMIT_SHA = "3967bb6f";
-var COMMIT_DATE = "2026-06-04T11:27:55Z";
-var LATEST_PR = 2153;
+var VERSION = "0.14.64";
+var COMMIT_SHA = "fb6bbe00";
+var COMMIT_DATE = "2026-06-04T23:21:00Z";
+var LATEST_PR = 2161;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -53848,11 +53921,30 @@ var _deliveryTimeoutParsed = _deliveryTimeoutRaw != null && _deliveryTimeoutRaw
 var DELIVERY_CONFIRM_TIMEOUT_MS = Number.isFinite(_deliveryTimeoutParsed) && _deliveryTimeoutParsed > 0 ? _deliveryTimeoutParsed : 15000;
 var DELIVERY_CONFIRM_SWEEP_MS = 5000;
 var deliveryQueue = createDeliveryQueue();
-var OBLIGATION_LEDGER_ENABLED = process.env.SWITCHROOM_OBLIGATION_LEDGER === "1";
+var OBLIGATION_LEDGER_ENABLED = process.env.SWITCHROOM_OBLIGATION_LEDGER !== "0";
 var OBLIGATION_REPRESENT_MAX = 2;
 var OBLIGATION_SWEEP_MS = 5000;
 var OBLIGATION_ESCALATE_MAX = 3;
 var OBLIGATION_ESCALATE_SEND_DEADLINE_MS = 45000;
+var OBLIGATION_ESCALATE_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_ESCALATE_GRACE_MS;
+  if (raw == null || raw === "")
+    return 45000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 45000;
+})();
+var AUTOCLASSIFY_MIDTURN_SHADOW = process.env.SWITCHROOM_AUTOCLASSIFY_MIDTURN_SHADOW !== "0";
+var lastAgentOutputAt = new Map;
+var LAST_OUTPUT_MAX_KEYS = 512;
+function noteAgentOutputAt(key, ts) {
+  lastAgentOutputAt.delete(key);
+  lastAgentOutputAt.set(key, ts);
+  if (lastAgentOutputAt.size > LAST_OUTPUT_MAX_KEYS) {
+    const oldest = lastAgentOutputAt.keys().next().value;
+    if (oldest !== undefined)
+      lastAgentOutputAt.delete(oldest);
+  }
+}
 var OBLIGATION_STORE_PATH = join35(STATE_DIR, "obligations.json");
 var obligationStoreFs = {
   readFileSync: (p) => readFileSync36(p, "utf8"),
@@ -54002,6 +54094,17 @@ function reapQueuedStatus(chatId, thread) {
 }
 var toolFlightTracker = new ToolFlightTracker;
 var pendingDeferredInterrupt = null;
+function cancelInterruptedObligation() {
+  if (!OBLIGATION_LEDGER_ENABLED)
+    return;
+  const turn = currentTurn;
+  if (turn == null)
+    return;
+  if (obligationLedger.close(turn.turnId)) {
+    process.stderr.write(`telegram gateway: obligation cancelled by interrupt origin=${turn.turnId}
+`);
+  }
+}
 async function fireDeferredInterrupt(reason) {
   const pending2 = pendingDeferredInterrupt;
   if (pending2 == null)
@@ -54025,6 +54128,7 @@ async function fireDeferredInterrupt(reason) {
     process.stderr.write(`telegram gateway: deferred-interrupt SIGINT failed: ${err.message}
 `);
   }
+  cancelInterruptedObligation();
   const delivered = ipcServer.sendToAgent(pending2.agentName, pending2.inboundMsg);
   if (delivered) {
     markClaudeBusyForInbound(pending2.inboundMsg);
@@ -54163,8 +54267,12 @@ function endCurrentTurnAtomic(turn) {
   if (currentTurn !== turn)
     return;
   currentTurn = null;
-  if (OBLIGATION_LEDGER_ENABLED && turn.finalAnswerDelivered) {
-    obligationLedger.close(turn.turnId);
+  if (OBLIGATION_LEDGER_ENABLED) {
+    if (turn.finalAnswerDelivered) {
+      obligationLedger.close(turn.turnId);
+    } else {
+      obligationLedger.noteTurnEnded(turn.turnId, Date.now());
+    }
   }
   if (turn.noReplyDrainTimer != null) {
     clearTimeout(turn.noReplyDrainTimer);
@@ -55253,7 +55361,7 @@ function obligationSweep() {
   if (turnInFlightForGate())
     return;
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? "";
-  const decision = obligationLedger.decideAtIdle();
+  const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS } : undefined);
   const o = decision.obligation;
   if (decision.action === "none" || o == null)
     return;
@@ -55261,35 +55369,20 @@ function obligationSweep() {
     if (pendingInboundBuffer.depth(agent) > 0)
       return;
     pendingInboundBuffer.push(agent, buildObligationRepresentInbound(o, Date.now()));
-    const attempt2 = obligationLedger.markRepresented(o.originTurnId);
-    process.stderr.write(`telegram gateway: obligation re-presented origin=${o.originTurnId} attempt=${attempt2}/${OBLIGATION_REPRESENT_MAX}
+    const attempt = obligationLedger.markRepresented(o.originTurnId);
+    process.stderr.write(`telegram gateway: obligation re-presented origin=${o.originTurnId} attempt=${attempt}/${OBLIGATION_REPRESENT_MAX}
 `);
     return;
   }
-  if (obligationEscalateInFlight.has(o.originTurnId))
-    return;
-  const escId = o.originTurnId;
-  const attempt = obligationLedger.markEscalateAttempt(escId);
-  obligationEscalateInFlight.add(escId);
-  process.stderr.write(`telegram gateway: obligation escalating (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${escId} attempt=${attempt}/${OBLIGATION_ESCALATE_MAX}
-`);
-  withDeadline(retryWithThreadFallback(robustApiCall, (tid) => bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
-    ...tid != null ? { message_thread_id: tid } : {}
-  }), { threadId: o.threadId, chat_id: o.chatId, verb: "obligation.escalate" }), OBLIGATION_ESCALATE_SEND_DEADLINE_MS, "obligation escalation send timed out").then(() => {
-    obligationLedger.close(escId);
-    process.stderr.write(`telegram gateway: obligation escalation delivered + closed origin=${escId}
-`);
-  }).catch((err) => {
-    if (attempt >= OBLIGATION_ESCALATE_MAX) {
-      obligationLedger.close(escId);
-      process.stderr.write(`telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts \u2014 closing best-effort origin=${escId}: ${err}
-`);
-    } else {
-      process.stderr.write(`telegram gateway: obligation escalation send failed (attempt ${attempt}/${OBLIGATION_ESCALATE_MAX}), retrying next sweep origin=${escId}: ${err}
-`);
-    }
-  }).finally(() => {
-    obligationEscalateInFlight.delete(escId);
+  driveEscalation({
+    escId: o.originTurnId,
+    inFlight: obligationEscalateInFlight,
+    ledger: obligationLedger,
+    send: () => retryWithThreadFallback(robustApiCall, (tid) => bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
+      ...tid != null ? { message_thread_id: tid } : {}
+    }), { threadId: o.threadId, chat_id: o.chatId, verb: "obligation.escalate" }),
+    maxAttempts: OBLIGATION_ESCALATE_MAX,
+    deadlineMs: OBLIGATION_ESCALATE_SEND_DEADLINE_MS
   });
 }
 if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
@@ -56201,6 +56294,8 @@ ${url}`;
   });
   noteOutbound(statusKey(chat_id, threadId), Date.now());
   noteOutbound2(statusKey(chat_id, threadId), Date.now());
+  if (AUTOCLASSIFY_MIDTURN_SHADOW)
+    noteAgentOutputAt(statusKey(chat_id, threadId), Date.now());
   shadowEmit({ kind: "modelOutbound", key: statusKey(chat_id, threadId), at: Date.now() });
   if (isFinalAnswerReply({ text: rawText, disableNotification })) {
     clearSilentEndState(statusKey(chat_id, threadId));
@@ -58654,6 +58749,7 @@ async function handleInbound(ctx, text, downloadImage, attachment, extraAttachme
         process.stderr.write(`telegram gateway: interrupt-marker SIGINT failed: ${err.message}
 `);
       }
+      cancelInterruptedObligation();
     }
     if (interrupt.emptyBody) {
       await swallowingApiCall(() => bot.api.sendMessage(chat_id, "\u26A1 Interrupted. Send your replacement instruction now.", messageThreadId != null ? { message_thread_id: messageThreadId } : {}), {
@@ -59020,6 +59116,23 @@ ${preBlock(write.output)}`;
     isSteering = priorTurnInFlight && isSteerPrefix;
     if (priorTurnInFlight)
       priorTurnStartedAt = activeTurnStartedAt.get(key);
+    if (AUTOCLASSIFY_MIDTURN_SHADOW && priorTurnInFlight) {
+      const lastOut = lastAgentOutputAt.get(key);
+      const msSinceOut = lastOut != null ? Date.now() - lastOut : null;
+      const shadow = autoClassifyMidTurnInbound({
+        isSteerPrefix,
+        isQueuePrefix: isQueuedPrefix,
+        priorTurnInFlight,
+        isDm: isDmChatId(chat_id),
+        incomingThreadId: messageThreadId ?? null,
+        activeTurnThreadId: currentTurn?.sessionThreadId ?? null,
+        msSinceLastAgentOutput: msSinceOut,
+        dmSteerWindowMs: 0,
+        topicSteerWindowMs: 8000
+      });
+      process.stderr.write(`telegram gateway: autoclassify-shadow chat_id=${chat_id} would=${shadow.decision} reason=${shadow.reason} same_topic=${shadow.sameTopic ?? "-"} ms_since_out=${msSinceOut ?? "-"} actual=${isSteering ? "steer" : "queue"}
+`);
+    }
     if (access.statusReactions !== false) {
       if (isSteering) {
         bot.api.setMessageReaction(chat_id, msgId, [{ type: "emoji", emoji: "\uD83E\uDD1D" }]).catch(() => {});

package/telegram-plugin/gateway/auto-classify-mid-turn.ts

@@ -0,0 +1,119 @@
+/**
+ * auto-classify-mid-turn.ts — deterministic, model-free classification of a
+ * mid-turn inbound into STEER (amend the in-flight turn) vs QUEUE (new task),
+ * using TOPIC-vs-active-turn + reply-RECENCY as proxies for intent. No model
+ * inference: the gateway must decide at inbound time while the single CLI is
+ * busy.
+ *
+ * Today a no-prefix mid-turn message always QUEUES (the default flipped
+ * 2026-04-17 away from the blunt "everything steers" — see
+ * reference/steer-or-queue-mid-flight.md). This module is the basis for a
+ * smarter default. It ships first in SHADOW mode (the gateway logs what it WOULD
+ * decide but still queues), to gather real-world data — how often mid-turn
+ * messages are same-topic continuations vs cross-topic new tasks, and the
+ * recency distribution — before any behaviour flips on.
+ *
+ * Signal strength (be honest):
+ *  - TOPIC (supergroup): STRONG + structural. A message in a DIFFERENT forum
+ *    topic than the active turn is, by the supergroup-mode invariant, a separate
+ *    conversation → queue. This needs no timing guess.
+ *  - RECENCY: weaker. Within the same topic it cannot tell "also do X" (steer)
+ *    from "new question, same topic" (queue) — only a tight window + the
+ *    visible/correctable UX (the JTBD doc) makes auto-steer acceptable, and
+ *    that is gated separately. The recency clock is the agent's LAST OUTPUT
+ *    (msSinceLastAgentOutput), NOT turn age: a long actively-narrating worker
+ *    turn must not read "stale".
+ *  - DM: no topic at all → timing-only (the pre-2026-04-17 regime that
+ *    over-steered). DM auto-steer is OFF by default (window 0).
+ *
+ * Pure (no gateway imports) ⇒ unit-testable.
+ */
+
+export type MidTurnClass = 'steer' | 'queue'
+
+export type MidTurnReason =
+  | 'steer_prefix'
+  | 'queue_prefix'
+  | 'not_mid_turn'
+  | 'cross_topic'
+  | 'same_topic_recent'
+  | 'same_topic_stale'
+  | 'dm_recent'
+  | 'dm_disabled'
+  | 'topic_disabled'
+
+export interface AutoClassifyInput {
+  /** Explicit `/steer`|`/s` prefix present — the user's stated intent, authoritative. */
+  isSteerPrefix: boolean
+  /** Explicit `/queue`|`/q` prefix present. */
+  isQueuePrefix: boolean
+  /** Is a turn in flight for this chat/thread? (no → not our decision). */
+  priorTurnInFlight: boolean
+  /** DM (no forum topics) → timing-only. */
+  isDm: boolean
+  /** Incoming message's thread id (undefined/null in a DM). */
+  incomingThreadId: number | null | undefined
+  /** The in-flight turn's thread id (currentTurn.sessionThreadId). */
+  activeTurnThreadId: number | null | undefined
+  /** ms since the agent's LAST visible output in this chat/thread; null when no
+   *  output has been recorded (cold topic) → treated as not-recent. */
+  msSinceLastAgentOutput: number | null
+  /** Auto-steer recency window in a DM. 0 (default) = DM auto-steer OFF. */
+  dmSteerWindowMs: number
+  /** Auto-steer recency window in a supergroup topic. 0 = topic auto-steer OFF. */
+  topicSteerWindowMs: number
+}
+
+export interface AutoClassifyResult {
+  decision: MidTurnClass
+  reason: MidTurnReason
+  /** Whether the incoming message is in the SAME thread as the active turn
+   *  (canonicalized). Undefined when not applicable (no prefix-free mid-turn). */
+  sameTopic?: boolean
+}
+
+/** Canonical thread compare, matching chatKey's collapse (null/undefined/0 → same
+ *  "no-thread" bucket) — never raw === on raw ids (the silence-poke key-mismatch
+ *  bug class). */
+function sameThread(a: number | null | undefined, b: number | null | undefined): boolean {
+  const norm = (t: number | null | undefined): number | null => (t == null || t === 0 ? null : t)
+  return norm(a) === norm(b)
+}
+
+/**
+ * Classify a mid-turn inbound. Precedence: explicit prefix → not-mid-turn →
+ * DM(timing) / supergroup(topic then timing). Defaults bias to QUEUE (the safe,
+ * reversible, current behaviour); STEER only on a strong/recent signal AND its
+ * window enabled.
+ */
+export function autoClassifyMidTurnInbound(i: AutoClassifyInput): AutoClassifyResult {
+  // Explicit prefixes always win — the user's stated intent is authoritative.
+  if (i.isSteerPrefix) return { decision: 'steer', reason: 'steer_prefix' }
+  if (i.isQueuePrefix) return { decision: 'queue', reason: 'queue_prefix' }
+  // No turn in flight → caller starts a fresh turn (not a steer/queue decision).
+  if (!i.priorTurnInFlight) return { decision: 'queue', reason: 'not_mid_turn' }
+
+  const recent =
+    i.msSinceLastAgentOutput != null && i.msSinceLastAgentOutput >= 0
+
+  if (i.isDm) {
+    // DM: no topic → timing-only. Default OFF (dmSteerWindowMs 0).
+    if (i.dmSteerWindowMs <= 0) return { decision: 'queue', reason: 'dm_disabled' }
+    return recent && i.msSinceLastAgentOutput! <= i.dmSteerWindowMs
+      ? { decision: 'steer', reason: 'dm_recent' }
+      : { decision: 'queue', reason: 'dm_disabled' }
+  }
+
+  // Supergroup: topic identity is the PRIMARY signal.
+  const topicMatch = sameThread(i.incomingThreadId, i.activeTurnThreadId)
+  if (i.topicSteerWindowMs <= 0) {
+    return { decision: 'queue', reason: 'topic_disabled', sameTopic: topicMatch }
+  }
+  // Different topic than the in-flight turn → ALWAYS queue (a separate
+  // conversation; never steer it into the wrong topic's turn).
+  if (!topicMatch) return { decision: 'queue', reason: 'cross_topic', sameTopic: false }
+  // Same topic: steer only if recent enough; else a new question → queue.
+  return recent && i.msSinceLastAgentOutput! <= i.topicSteerWindowMs
+    ? { decision: 'steer', reason: 'same_topic_recent', sameTopic: true }
+    : { decision: 'queue', reason: 'same_topic_stale', sameTopic: true }
+}

package/telegram-plugin/gateway/escalation-drive.ts

@@ -0,0 +1,79 @@
+/**
+ * escalation-drive.ts — the obligation-ledger escalation step, extracted from
+ * obligationSweep so the hang → bounded → terminal behaviour is EXECUTABLE in a
+ * test with a fake hanging send. That path is unreachable by the two harnesses
+ * we have: mtcute can't make Telegram's API hang, and the synchronous property
+ * test can't model a promise that never settles — yet it is exactly the path the
+ * total proof flagged as the determinism hole. This file makes the real drive
+ * logic the sweep uses testable in isolation (escalation-drive.test.ts), so the
+ * fix is verified by execution, not only by reasoning + review.
+ *
+ * Invariant it upholds: a single escalation attempt
+ *  - is guarded so a sweep tick cannot fire a second concurrent send for the
+ *    same obligation while one is awaiting;
+ *  - bounds the send with `withDeadline`, so the chain ALWAYS settles within
+ *    `deadlineMs` ⇒ the in-flight flag ALWAYS clears (a hung send becomes a
+ *    bounded reject, handled like any other failed attempt);
+ *  - closes the obligation ONLY after a successful send; a transient failure
+ *    leaves it OPEN (retried next sweep); a permanent failure
+ *    (attempt ≥ maxAttempts) closes best-effort — so repeated hung/failed sends
+ *    reach a terminal in a bounded number of sweeps, never an infinite loop.
+ */
+import { withDeadline } from './with-deadline.js'
+
+/** The slice of the ledger the escalation step needs. */
+export interface EscalationLedger {
+  markEscalateAttempt(originTurnId: string): number
+  close(originTurnId: string | null | undefined): boolean
+}
+
+export interface DriveEscalationArgs {
+  escId: string
+  /** Set of origin ids with an escalation send in flight (concurrency guard). */
+  inFlight: Set<string>
+  ledger: EscalationLedger
+  /** Perform the operator-nudge send (already thread-fallback-wrapped). May hang. */
+  send: () => Promise<unknown>
+  /** Attempts before a permanent failure closes best-effort. */
+  maxAttempts: number
+  /** Bound on a single send so a hang can't leak the in-flight flag. */
+  deadlineMs: number
+  log?: (line: string) => void
+  /** Injectable for tests; defaults to the real withDeadline. */
+  withDeadlineFn?: typeof withDeadline
+}
+
+/**
+ * Drive one escalation attempt. Returns the settling chain promise (so tests can
+ * await it) or `undefined` if the call was a no-op because a send is already in
+ * flight for `escId`. obligationSweep calls this as `void driveEscalation(...)`.
+ */
+export function driveEscalation(args: DriveEscalationArgs): Promise<void> | undefined {
+  const { escId, inFlight, ledger, send, maxAttempts, deadlineMs } = args
+  const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const wd = args.withDeadlineFn ?? withDeadline
+  if (inFlight.has(escId)) return undefined // a send is already awaiting
+  const attempt = ledger.markEscalateAttempt(escId)
+  inFlight.add(escId)
+  log(`telegram gateway: obligation escalating origin=${escId} attempt=${attempt}/${maxAttempts}\n`)
+  return wd(send(), deadlineMs, 'obligation escalation send timed out')
+    .then(() => {
+      ledger.close(escId)
+      log(`telegram gateway: obligation escalation delivered + closed origin=${escId}\n`)
+    })
+    .catch((err: unknown) => {
+      if (attempt >= maxAttempts) {
+        ledger.close(escId)
+        log(
+          `telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts — closing best-effort origin=${escId}: ${err}\n`,
+        )
+      } else {
+        log(
+          `telegram gateway: obligation escalation send failed (attempt ${attempt}/${maxAttempts}), retrying next sweep origin=${escId}: ${err}\n`,
+        )
+      }
+    })
+    .finally(() => {
+      inFlight.delete(escId)
+    })
+}