switchroom 0.14.59 → 0.14.61

package/dist/cli/switchroom.js

@@ -49452,8 +49452,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.59";
-var COMMIT_SHA = "178c6d14";
+var VERSION = "0.14.61";
+var COMMIT_SHA = "6b3330f4";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.59",
+  "version": "0.14.61",
   "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

@@ -47135,20 +47135,37 @@ function createPendingInboundBuffer(opts = {}) {
 // gateway/obligation-ledger.ts
 class ObligationLedger {
   maxRepresents;
+  hooks;
   open = new Map;
-  constructor(maxRepresents = 2) {
+  constructor(maxRepresents = 2, hooks = {}) {
     this.maxRepresents = maxRepresents;
+    this.hooks = hooks;
+  }
+  persist() {
+    this.hooks.onChange?.(this.list());
   }
   openIfAbsent(input) {
     if (this.open.has(input.originTurnId))
       return false;
     this.open.set(input.originTurnId, { ...input, representCount: 0 });
+    this.persist();
     return true;
   }
   close(originTurnId) {
     if (originTurnId == null)
       return false;
-    return this.open.delete(originTurnId);
+    const closed = this.open.delete(originTurnId);
+    if (closed)
+      this.persist();
+    return closed;
+  }
+  hydrate(snapshot) {
+    this.open.clear();
+    for (const o of snapshot) {
+      if (o != null && typeof o.originTurnId === "string" && o.originTurnId.length > 0) {
+        this.open.set(o.originTurnId, { ...o });
+      }
+    }
   }
   isOpen(originTurnId) {
     return this.open.has(originTurnId);
@@ -47190,8 +47207,17 @@ class ObligationLedger {
     if (o === undefined)
       return 0;
     o.representCount += 1;
+    this.persist();
     return o.representCount;
   }
+  markEscalateAttempt(originTurnId) {
+    const o = this.open.get(originTurnId);
+    if (o === undefined)
+      return 0;
+    o.escalateAttempts = (o.escalateAttempts ?? 0) + 1;
+    this.persist();
+    return o.escalateAttempts;
+  }
 }
 var REPRESENT_PREVIEW_MAX = 200;
 function buildObligationRepresentInbound(o, now) {
@@ -47218,6 +47244,47 @@ function obligationEscalationText(o) {
   return `\u26a0\ufe0f I may have missed an earlier message and I'm not sure I answered it: ` + `"${preview}". If you still need it, please re-send.`;
 }
 
+// gateway/obligation-store.ts
+function isObligationRow(x) {
+  if (x == null || typeof x !== "object")
+    return false;
+  const o = x;
+  return typeof o.originTurnId === "string" && o.originTurnId.length > 0 && typeof o.chatId === "string" && typeof o.messageId === "number" && typeof o.text === "string" && typeof o.openedAt === "number" && typeof o.representCount === "number";
+}
+function loadObligations(path, fs2) {
+  if (!fs2.existsSync(path))
+    return [];
+  let raw = "";
+  try {
+    raw = fs2.readFileSync(path);
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (parsed == null || typeof parsed !== "object")
+    return [];
+  const env = parsed;
+  if (env.v !== 1 || !Array.isArray(env.obligations))
+    return [];
+  return env.obligations.filter(isObligationRow);
+}
+function persistObligations(path, fs2, snapshot, log = (l) => process.stderr.write(l)) {
+  const env = { v: 1, obligations: [...snapshot] };
+  const tmp = path + ".tmp";
+  try {
+    fs2.writeFileSync(tmp, JSON.stringify(env));
+    fs2.renameSync(tmp, path);
+  } catch (err) {
+    log(`obligation-store: persist FAILED path=${path}: ${err.message} \u2014 ` + `durability degraded to in-memory
+`);
+  }
+}
+
 // 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) {
@@ -52310,10 +52377,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.59";
-var COMMIT_SHA = "178c6d14";
-var COMMIT_DATE = "2026-06-04T07:31:45Z";
-var LATEST_PR = 2146;
+var VERSION = "0.14.61";
+var COMMIT_SHA = "6b3330f4";
+var COMMIT_DATE = "2026-06-04T10:11:35Z";
+var LATEST_PR = 2151;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -53514,7 +53581,26 @@ var deliveryQueue = createDeliveryQueue();
 var OBLIGATION_LEDGER_ENABLED = process.env.SWITCHROOM_OBLIGATION_LEDGER === "1";
 var OBLIGATION_REPRESENT_MAX = 2;
 var OBLIGATION_SWEEP_MS = 5000;
-var obligationLedger = new ObligationLedger(OBLIGATION_REPRESENT_MAX);
+var OBLIGATION_ESCALATE_MAX = 3;
+var OBLIGATION_STORE_PATH = join35(STATE_DIR, "obligations.json");
+var obligationStoreFs = {
+  readFileSync: (p) => readFileSync36(p, "utf8"),
+  writeFileSync: (p, d) => writeFileSync25(p, d),
+  renameSync: (a, b) => renameSync12(a, b),
+  existsSync: (p) => existsSync38(p)
+};
+var obligationLedger = new ObligationLedger(OBLIGATION_REPRESENT_MAX, {
+  onChange: STATIC || !OBLIGATION_LEDGER_ENABLED ? undefined : (snapshot) => persistObligations(OBLIGATION_STORE_PATH, obligationStoreFs, snapshot)
+});
+if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
+  const restored = loadObligations(OBLIGATION_STORE_PATH, obligationStoreFs);
+  if (restored.length > 0) {
+    obligationLedger.hydrate(restored);
+    process.stderr.write(`telegram gateway: obligation-ledger hydrated ${restored.length} open obligation(s) from ${OBLIGATION_STORE_PATH}
+`);
+  }
+}
+var obligationEscalateInFlight = new Set;
 var SERIALIZE_UNTIL_REPLIED_ENABLED = process.env.SWITCHROOM_SERIALIZE_UNTIL_REPLIED !== "0";
 var _noReplyDrainRaw = process.env.SWITCHROOM_SERIALIZE_NOREPLY_DRAIN_MS;
 var _noReplyDrainParsed = _noReplyDrainRaw != null && _noReplyDrainRaw !== "" ? Number(_noReplyDrainRaw) : 2500;
@@ -53806,6 +53892,9 @@ function endCurrentTurnAtomic(turn) {
   if (currentTurn !== turn)
     return;
   currentTurn = null;
+  if (OBLIGATION_LEDGER_ENABLED && turn.finalAnswerDelivered) {
+    obligationLedger.close(turn.turnId);
+  }
   if (turn.noReplyDrainTimer != null) {
     clearTimeout(turn.noReplyDrainTimer);
     turn.noReplyDrainTimer = null;
@@ -54895,19 +54984,35 @@ function obligationSweep() {
     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}
+    const attempt2 = obligationLedger.markRepresented(o.originTurnId);
+    process.stderr.write(`telegram gateway: obligation re-presented origin=${o.originTurnId} attempt=${attempt2}/${OBLIGATION_REPRESENT_MAX}
 `);
     return;
   }
-  obligationLedger.close(o.originTurnId);
-  process.stderr.write(`telegram gateway: obligation escalated (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${o.originTurnId}
+  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}
 `);
-  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}
+  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" }).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);
   });
 }
 if (!STATIC && OBLIGATION_LEDGER_ENABLED) {

package/telegram-plugin/gateway/gateway.ts

@@ -283,6 +283,7 @@ import {
   buildObligationRepresentInbound,
   obligationEscalationText,
 } from './obligation-ledger.js'
+import { loadObligations, persistObligations } from './obligation-store.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
@@ -1397,7 +1398,49 @@ const deliveryQueue = createDeliveryQueue<InboundMessage>()
 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)
+// Bound on escalation SEND attempts. The escalation now closes only AFTER a
+// successful send (a transient failure stays OPEN and retries next sweep), so a
+// PERMANENTLY-undeliverable nudge (dead/renumbered topic → Telegram 400 even
+// after thread-fallback, blocked bot) would loop forever — and, with the
+// durable snapshot, re-enter that loop on every boot. After this many failed
+// attempts the gateway closes best-effort (loud log): the user is genuinely
+// unreachable, so a bounded give-up beats an infinite/poison loop.
+const OBLIGATION_ESCALATE_MAX = 3
+// Durable snapshot of the open obligation set on the persistent per-agent
+// volume (STATE_DIR = /state/agent/telegram in prod). Closes the restart hole:
+// the in-memory ledger alone empties on restart and the spool's boot-replay
+// bypasses handleInbound (where obligations OPEN), so a delivered-but-unanswered
+// message used to lose its obligation across a restart. onChange persists every
+// mutation; boot hydrate (below) restores OPEN/ESCALATING with representCount +
+// escalateAttempts intact. STATIC mode (no runtime) and flag-off both skip disk.
+const OBLIGATION_STORE_PATH = join(STATE_DIR, 'obligations.json')
+const obligationStoreFs = {
+  readFileSync: (p: string) => readFileSync(p, 'utf8'),
+  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  renameSync: (a: string, b: string) => renameSync(a, b),
+  existsSync: (p: string) => existsSync(p),
+}
+const obligationLedger = new ObligationLedger(OBLIGATION_REPRESENT_MAX, {
+  onChange:
+    STATIC || !OBLIGATION_LEDGER_ENABLED
+      ? undefined
+      : (snapshot) => persistObligations(OBLIGATION_STORE_PATH, obligationStoreFs, snapshot),
+})
+if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
+  // Restart-durability: re-open obligations that were OPEN/ESCALATING when the
+  // gateway last ran. The very next idle sweep re-presents or re-escalates them.
+  const restored = loadObligations(OBLIGATION_STORE_PATH, obligationStoreFs)
+  if (restored.length > 0) {
+    obligationLedger.hydrate(restored)
+    process.stderr.write(
+      `telegram gateway: obligation-ledger hydrated ${restored.length} open obligation(s) from ${OBLIGATION_STORE_PATH}\n`,
+    )
+  }
+}
+// Origin ids with an escalation send IN FLIGHT — prevents the 5s sweep from
+// firing a second concurrent send for the same obligation while the first is
+// still awaiting (an escalation that takes >5s, or repeated failures).
+const obligationEscalateInFlight = new Set<string>()
 
 // ─── Serialize-until-replied (multitopic reply-routing) ───────────────────
 // Component 1 (deliver-before-drain gate). A buffered cross-topic inbound
@@ -2354,6 +2397,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) {
@@ -4833,20 +4891,53 @@ function obligationSweep(): void {
     )
     return
   }
-  // escalate — close FIRST so the loop ends even if the send fails.
-  obligationLedger.close(o.originTurnId)
+  // escalate — re-present ladder exhausted. Send ONE operator-visible nudge and
+  // close the obligation ONLY AFTER it actually lands. This inverts the old
+  // close-before-send (which silently dropped the terminal whenever the send
+  // failed): the close is now itself an observable terminal. A transient send
+  // failure leaves the obligation OPEN → retried next sweep; a PERMANENT one
+  // (dead topic even after thread-fallback, blocked bot) is bounded by
+  // OBLIGATION_ESCALATE_MAX → close best-effort (the user is unreachable, so a
+  // bounded give-up beats an infinite loop / a boot-surviving poison record).
+  if (obligationEscalateInFlight.has(o.originTurnId)) return // a send is already awaiting
+  const escId = o.originTurnId
+  const attempt = obligationLedger.markEscalateAttempt(escId)
+  obligationEscalateInFlight.add(escId)
   process.stderr.write(
-    `telegram gateway: obligation escalated (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${o.originTurnId}\n`,
+    `telegram gateway: obligation escalating (exhausted ${OBLIGATION_REPRESENT_MAX} re-presents) origin=${escId} attempt=${attempt}/${OBLIGATION_ESCALATE_MAX}\n`,
   )
-  void robustApiCall(
-    () =>
+  // retryWithThreadFallback: a stale/renumbered topic returns THREAD_NOT_FOUND;
+  // retry WITHOUT the thread so the nudge still lands in the chat (the #2096
+  // pattern) instead of being permanently undeliverable to a dead topic.
+  void retryWithThreadFallback(
+    robustApiCall,
+    (tid) =>
       bot.api.sendMessage(o.chatId, obligationEscalationText(o), {
-        ...(o.threadId != null ? { message_thread_id: o.threadId } : {}),
+        ...(tid != null ? { message_thread_id: tid } : {}),
       }),
-    { 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`)
-  })
+    { threadId: o.threadId, chat_id: o.chatId, verb: 'obligation.escalate' },
+  )
+    .then(() => {
+      obligationLedger.close(escId)
+      process.stderr.write(
+        `telegram gateway: obligation escalation delivered + closed origin=${escId}\n`,
+      )
+    })
+    .catch((err) => {
+      if (attempt >= OBLIGATION_ESCALATE_MAX) {
+        obligationLedger.close(escId)
+        process.stderr.write(
+          `telegram gateway: obligation escalation PERMANENTLY undeliverable after ${attempt} attempts — closing best-effort origin=${escId}: ${err}\n`,
+        )
+      } else {
+        process.stderr.write(
+          `telegram gateway: obligation escalation send failed (attempt ${attempt}/${OBLIGATION_ESCALATE_MAX}), retrying next sweep origin=${escId}: ${err}\n`,
+        )
+      }
+    })
+    .finally(() => {
+      obligationEscalateInFlight.delete(escId)
+    })
 }
 if (!STATIC && OBLIGATION_LEDGER_ENABLED) {
   setInterval(obligationSweep, OBLIGATION_SWEEP_MS).unref()

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

@@ -38,6 +38,12 @@ export interface Obligation {
   readonly openedAt: number
   /** How many times it has been re-presented (0 on first open). */
   representCount: number
+  /** How many times the operator-escalation send has been ATTEMPTED (0 until
+   *  the represent ladder is exhausted). Bounds escalation so a permanently-
+   *  undeliverable nudge (dead/renumbered topic → Telegram 400, blocked bot)
+   *  can't loop forever — and, because it is part of the durable snapshot,
+   *  can't become a boot-surviving poison record either. */
+  escalateAttempts?: number
 }
 
 /** What the gateway should do for the oldest open obligation at an idle boundary. */
@@ -57,14 +63,33 @@ export interface ObligationInput {
   openedAt: number
 }
 
+/** Side-effect hooks the gateway injects. Kept out of the pure decision logic
+ *  so the ledger stays unit-testable (a capturing `onChange` in tests). */
+export interface ObligationLedgerHooks {
+  /** Called after EVERY state mutation (open/close/represent/escalate-attempt)
+   *  with the full open snapshot, so the gateway can durably persist it. NOT
+   *  called by hydrate() — that IS the restoration of persisted state. */
+  onChange?: (snapshot: Obligation[]) => void
+}
+
 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.
+   * @param hooks optional side-effect hooks (durable persistence). Omitted in
+   *   pure unit tests; the gateway wires `onChange` to the snapshot store.
    */
-  constructor(private readonly maxRepresents = 2) {}
+  constructor(
+    private readonly maxRepresents = 2,
+    private readonly hooks: ObligationLedgerHooks = {},
+  ) {}
+
+  /** Persist the current open set via the injected hook (no-op if unwired). */
+  private persist(): void {
+    this.hooks.onChange?.(this.list())
+  }
 
   /**
    * Open an obligation if not already tracked. Idempotent on originTurnId — a
@@ -75,13 +100,33 @@ export class ObligationLedger {
   openIfAbsent(input: ObligationInput): boolean {
     if (this.open.has(input.originTurnId)) return false
     this.open.set(input.originTurnId, { ...input, representCount: 0 })
+    this.persist()
     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)
+    const closed = this.open.delete(originTurnId)
+    if (closed) this.persist()
+    return closed
+  }
+
+  /**
+   * Re-populate from a persisted snapshot at boot — the restart-durability seam.
+   * Open obligations (with their representCount + escalateAttempts intact)
+   * survive a gateway/container restart, so the next idle sweep re-presents or
+   * re-escalates them rather than silently losing a delivered-but-unanswered
+   * message. Replaces current contents; does NOT fire onChange (this state is
+   * already what's on disk). Tolerates a malformed snapshot (skips bad rows).
+   */
+  hydrate(snapshot: readonly Obligation[]): void {
+    this.open.clear()
+    for (const o of snapshot) {
+      if (o != null && typeof o.originTurnId === 'string' && o.originTurnId.length > 0) {
+        this.open.set(o.originTurnId, { ...o })
+      }
+    }
   }
 
   isOpen(originTurnId: string): boolean {
@@ -156,8 +201,26 @@ export class ObligationLedger {
     const o = this.open.get(originTurnId)
     if (o === undefined) return 0
     o.representCount += 1
+    this.persist()
     return o.representCount
   }
+
+  /**
+   * Record an operator-escalation SEND attempt (bumps escalateAttempts).
+   * Returns the new count. The gateway calls this immediately before each
+   * escalation send and uses the count to bound retries: a transient send
+   * failure leaves the obligation OPEN and is retried next sweep, but after
+   * the bound the gateway closes best-effort so a permanently-undeliverable
+   * nudge can neither loop forever nor (now that the count is durable) re-enter
+   * the loop on every boot.
+   */
+  markEscalateAttempt(originTurnId: string): number {
+    const o = this.open.get(originTurnId)
+    if (o === undefined) return 0
+    o.escalateAttempts = (o.escalateAttempts ?? 0) + 1
+    this.persist()
+    return o.escalateAttempts
+  }
 }
 
 /** Original message preview length for re-presentation (mirrors resume builder). */

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

@@ -0,0 +1,107 @@
+/**
+ * obligation-store.ts — durable snapshot for the obligation ledger.
+ *
+ * Why this exists: `ObligationLedger` is an in-memory Map. A gateway/container
+ * restart (switchroom update, agent restart, self-restart, OOM) empties it, so
+ * an inbound that was OPEN-but-unanswered when the process died loses its
+ * answer-obligation. The inbound-spool redelivers the MESSAGE on boot, but its
+ * replay bypasses `handleInbound` (the only place obligations OPEN), so the
+ * obligation is never reborn and a post-restart deferral is silently dropped —
+ * the determinism hole the systems analysis flagged.
+ *
+ * This makes the obligation guarantee SELF-CONTAINED across restart: every
+ * ledger mutation persists the full open set here; on boot the gateway hydrates
+ * the ledger from it, so OPEN/ESCALATING obligations survive WITH their
+ * representCount + escalateAttempts intact (the latter so a permanently-
+ * undeliverable escalation can't re-enter its retry loop on every boot).
+ *
+ * Shape choice — SNAPSHOT, not append-log. The open set is tiny and bounded
+ * (the count of currently-unanswered messages — normally 0–3), so rewriting the
+ * whole set on each change is trivially cheap and needs NO compaction,
+ * tombstones, or torn-tail replay. Crash-safety is a single write-tmp +
+ * atomic rename: a crash leaves EITHER the prior complete snapshot OR the new
+ * complete one — never a torn file. This is strictly simpler than the spool's
+ * append+ack+compact idiom, which that file needs only because its set is
+ * unbounded. PURE w.r.t. the injected fs seam ⇒ unit-testable.
+ */
+
+import type { Obligation } from './obligation-ledger.js'
+
+export interface ObligationStoreFsSeam {
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename) so a crash mid-write can't tear
+   *  the snapshot. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+}
+
+interface SnapshotEnvelope {
+  v: 1
+  obligations: Obligation[]
+}
+
+function isObligationRow(x: unknown): x is Obligation {
+  if (x == null || typeof x !== 'object') return false
+  const o = x as Record<string, unknown>
+  return (
+    typeof o.originTurnId === 'string' &&
+    o.originTurnId.length > 0 &&
+    typeof o.chatId === 'string' &&
+    typeof o.messageId === 'number' &&
+    typeof o.text === 'string' &&
+    typeof o.openedAt === 'number' &&
+    typeof o.representCount === 'number'
+  )
+}
+
+/**
+ * Load the persisted open set. Returns [] on a missing, unreadable, or
+ * malformed file (fail-open to empty: a corrupt snapshot must never crash boot;
+ * worst case we lose the cross-restart obligation guarantee for that boot and
+ * fall back to the spool's message redelivery — strictly no worse than today).
+ */
+export function loadObligations(path: string, fs: ObligationStoreFsSeam): Obligation[] {
+  if (!fs.existsSync(path)) return []
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path)
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed == null || typeof parsed !== 'object') return []
+  const env = parsed as Record<string, unknown>
+  if (env.v !== 1 || !Array.isArray(env.obligations)) return []
+  return env.obligations.filter(isObligationRow)
+}
+
+/**
+ * Persist the open set atomically (write sibling tmp → rename over the real
+ * path). Best-effort relative to fs availability: a write failure is logged but
+ * never thrown — a failing store degrades to in-memory-only (today's behaviour),
+ * it must not break live delivery.
+ */
+export function persistObligations(
+  path: string,
+  fs: ObligationStoreFsSeam,
+  snapshot: readonly Obligation[],
+  log: (line: string) => void = (l) => process.stderr.write(l),
+): void {
+  const env: SnapshotEnvelope = { v: 1, obligations: [...snapshot] }
+  const tmp = path + '.tmp'
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(env))
+    fs.renameSync(tmp, path)
+  } catch (err) {
+    log(
+      `obligation-store: persist FAILED path=${path}: ${(err as Error).message} — ` +
+        `durability degraded to in-memory\n`,
+    )
+  }
+}

package/telegram-plugin/tests/obligation-determinism.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "vitest";
+import { ObligationLedger, type Obligation } from "../gateway/obligation-ledger.js";
+import {
+  loadObligations,
+  persistObligations,
+  type ObligationStoreFsSeam,
+} from "../gateway/obligation-store.js";
+
+/**
+ * DETERMINISM PROOF (by exhaustive simulation, not live observation).
+ *
+ * The operator's requirement: be confident — by reasoning — that EVERY real
+ * inbound reaches answered-or-escalated for ANY model behaviour and ANY timing,
+ * including across a restart, with no silent drop and no double-ask of a message
+ * that WAS answered.
+ *
+ * This drives the REAL ObligationLedger + the REAL durable snapshot store
+ * (obligation-store, over an in-memory fs whose rename is atomic) through a
+ * faithful model of the gateway's obligation lifecycle:
+ *
+ *   OPEN     — on receipt (handleInbound, idempotent).
+ *   close    — at turn_end iff the turn delivered a final answer (finalAnswerDelivered).
+ *   represent— idle sweep, bounded by maxRepresents, drives a fresh must-answer turn.
+ *   escalate — ladder exhausted: send the operator nudge; close ONLY after it
+ *              lands; a transient send failure stays OPEN and retries; a permanent
+ *              one is bounded (OBLIGATION_ESCALATE_MAX) → close best-effort.
+ *   restart  — fresh ledger hydrated from the durable snapshot (counters intact).
+ *
+ * Over thousands of random schedules it asserts the invariant holds and the
+ * engine always terminates (no infinite loop). The COALESCED PARTIAL-ANSWER
+ * residual is deliberately NOT modelled — it is the one honest hard limit (a
+ * turn-keyed ledger cannot see "answered half" without parsing model prose) and
+ * is mitigated by coalescing policy, not the ledger.
+ */
+
+// Mirrors the gateway constants under test.
+const MAX_REPRESENTS = 2;
+const ESCALATE_MAX = 3;
+
+// Deterministic PRNG (mulberry32) so any failure reproduces from its seed.
+function rng(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function memStore(): { fs: ObligationStoreFsSeam } {
+  const files = new Map<string, string>();
+  return {
+    fs: {
+      readFileSync: (p) => {
+        if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+        return files.get(p)!;
+      },
+      writeFileSync: (p, d) => files.set(p, d),
+      renameSync: (a, b) => {
+        if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+        files.set(b, files.get(a)!);
+        files.delete(a);
+      },
+      existsSync: (p) => files.has(p),
+    },
+  };
+}
+
+type Terminal = "answered" | "escalation-delivered" | "escalation-give-up";
+
+interface Msg {
+  id: string;
+  /** Real numeric Telegram message id (the gateway only opens an obligation
+   *  when deriveTurnId is non-null, i.e. messageId > 0 — so the durable row
+   *  always carries a valid number). */
+  msgId: number;
+  /** Turn attempt index (0 = original, 1 = 1st re-present, 2 = 2nd) at which
+   *  the model delivers a final answer. >MAX_REPRESENTS ⇒ never answered ⇒ escalates. */
+  answerOnAttempt: number;
+  /** How many escalation SEND attempts fail before one succeeds. ≥ESCALATE_MAX
+   *  ⇒ permanently undeliverable ⇒ bounded give-up. */
+  escalateFailsFor: number;
+}
+
+interface Sim {
+  terminals: Map<string, Terminal>;
+  steps: number;
+}
+
+function runSchedule(msgs: Msg[], seed: number): Sim {
+  const PATH = "/state/agent/telegram/obligations.json";
+  const store = memStore();
+  let ledger = new ObligationLedger(MAX_REPRESENTS, {
+    onChange: (snap) => persistObligations(PATH, store.fs, snap),
+  });
+  const r = rng(seed);
+
+  const pending = [...msgs]; // not yet received
+  const byId = new Map(msgs.map((m) => [m.id, m]));
+  const turnsHad = new Map<string, number>(); // total turns delivered to each obligation
+  const terminals = new Map<string, Terminal>();
+  const received = new Set<string>();
+
+  const close = (id: string, why: Terminal) => {
+    ledger.close(id);
+    terminals.set(id, why);
+  };
+
+  // Run one turn for an obligation; close if the model answers on this attempt.
+  const deliverTurn = (id: string) => {
+    const had = (turnsHad.get(id) ?? 0);
+    const attemptIndex = had; // 0-based
+    turnsHad.set(id, had + 1);
+    if (byId.get(id)!.answerOnAttempt === attemptIndex) close(id, "answered");
+  };
+
+  const ESC_IN_FLIGHT = new Set<string>(); // mirrors the gateway's concurrency guard (no-op in a sync model)
+
+  let steps = 0;
+  const CAP = 10_000; // generous; a real infinite loop blows past this and fails
+  while (steps < CAP) {
+    steps++;
+    const open = ledger.hasOpen();
+    // Receive a fresh inbound (interleave: maybe receive while something is open,
+    // exercising multi-open). Always receive if nothing is open and work remains.
+    if (pending.length > 0 && (!open || r() < 0.5)) {
+      const m = pending.shift()!;
+      received.add(m.id);
+      // OPEN at receipt — keyed origin id; idempotent.
+      ledger.openIfAbsent({
+        originTurnId: m.id,
+        chatId: "-100123",
+        threadId: 3,
+        messageId: m.msgId,
+        text: `msg ${m.id}`,
+        openedAt: 1000 + steps,
+      });
+      deliverTurn(m.id); // original turn (attempt 0)
+    } else if (open) {
+      const decision = ledger.decideAtIdle();
+      const o = decision.obligation as Obligation;
+      // INVARIANT (no double-ask): a terminated obligation must never resurface.
+      expect(terminals.has(o.originTurnId)).toBe(false);
+      if (decision.action === "represent") {
+        ledger.markRepresented(o.originTurnId);
+        deliverTurn(o.originTurnId); // the re-present turn
+      } else if (decision.action === "escalate") {
+        if (ESC_IN_FLIGHT.has(o.originTurnId)) continue;
+        const attempt = ledger.markEscalateAttempt(o.originTurnId);
+        const willSucceed = byId.get(o.originTurnId)!.escalateFailsFor < attempt;
+        if (willSucceed) {
+          close(o.originTurnId, "escalation-delivered");
+        } else if (attempt >= ESCALATE_MAX) {
+          close(o.originTurnId, "escalation-give-up");
+        }
+        // else: transient failure — stays OPEN, retried next sweep.
+      }
+    } else {
+      break; // idle: nothing pending, nothing open → done
+    }
+
+    // Random restart: the durable snapshot is the only thing that survives.
+    // A fresh ledger hydrated from disk must resume exactly where we left off.
+    if (r() < 0.15) {
+      ledger = new ObligationLedger(MAX_REPRESENTS, {
+        onChange: (snap) => persistObligations(PATH, store.fs, snap),
+      });
+      ledger.hydrate(loadObligations(PATH, store.fs));
+    }
+  }
+
+  return { terminals, steps };
+}
+
+function pick<T>(arr: T[], r: () => number): T {
+  return arr[Math.floor(r() * arr.length)];
+}
+
+describe("obligation determinism — every inbound reaches a terminal, no silent loss, no double-ask", () => {
+  it("holds across 3000 random {model-behavior × timing × restart} schedules", () => {
+    const ANSWER = [0, 1, 2, 3, 99]; // 0..2 = answered via ladder; 3/99 = never → escalate
+    const ESCFAIL = [0, 1, 2, 3, 5]; // 0 = first send ok; ≥3 = permanently undeliverable
+    for (let seed = 1; seed <= 3000; seed++) {
+      const r = rng(seed * 7919);
+      const n = 1 + Math.floor(r() * 5); // 1..5 messages
+      const msgs: Msg[] = [];
+      for (let i = 0; i < n; i++) {
+        const msgId = seed * 100 + i; // real positive integer id
+        msgs.push({
+          id: `c:3#${msgId}`,
+          msgId,
+          answerOnAttempt: pick(ANSWER, r),
+          escalateFailsFor: pick(ESCFAIL, r),
+        });
+      }
+      const { terminals, steps } = runSchedule(msgs, seed * 104729);
+
+      // 1. TERMINATION: the engine settled well within the cap (no infinite loop).
+      expect(steps).toBeLessThan(10_000);
+
+      // 2. NO SILENT LOSS: every message received reached a terminal.
+      for (const m of msgs) {
+        const t = terminals.get(m.id);
+        expect(t, `seed=${seed} msg=${m.id} answer=${m.answerOnAttempt} escFail=${m.escalateFailsFor}`).toBeDefined();
+
+        // 3. CORRECT TERMINAL per behaviour:
+        if (m.answerOnAttempt <= MAX_REPRESENTS) {
+          // answerable within the represent ladder → answered (never escalated early)
+          expect(t).toBe("answered");
+        } else if (m.escalateFailsFor < ESCALATE_MAX) {
+          // never answered, escalation eventually lands
+          expect(t).toBe("escalation-delivered");
+        } else {
+          // never answered, escalation permanently undeliverable → bounded give-up
+          expect(t).toBe("escalation-give-up");
+        }
+      }
+    }
+  });
+
+  it("a delivered-but-unanswered obligation survives a restart and is escalated, not lost", () => {
+    // Deterministic single case: model NEVER answers, escalation succeeds first try,
+    // with a restart forced mid-life via a seed that triggers the 0.15 branch.
+    const { terminals } = runSchedule(
+      [{ id: "c:3#715", msgId: 715, answerOnAttempt: 99, escalateFailsFor: 0 }],
+      42,
+    );
+    expect(terminals.get("c:3#715")).toBe("escalation-delivered");
+  });
+
+  it("escalation that is permanently undeliverable is bounded (give-up), never an infinite loop", () => {
+    const { terminals, steps } = runSchedule(
+      [{ id: "c:3#900", msgId: 900, answerOnAttempt: 99, escalateFailsFor: 99 }],
+      7,
+    );
+    expect(terminals.get("c:3#900")).toBe("escalation-give-up");
+    expect(steps).toBeLessThan(10_000);
+  });
+});

package/telegram-plugin/tests/obligation-ledger.test.ts

@@ -165,3 +165,72 @@ describe("buildObligationRepresentInbound", () => {
     expect(obligationEscalationText(ob)).toMatch(/re-?send/i);
   });
 });
+
+describe("ObligationLedger — durability hooks + escalate-attempt counter", () => {
+  function input(id: string, openedAt: number, text = "do the thing") {
+    return { originTurnId: id, chatId: "-100123", threadId: 3, messageId: Number(id.split("#").pop() ?? 0), text, openedAt };
+  }
+
+  it("fires onChange after every mutation with the full open snapshot", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000)); // open
+    L.openIfAbsent(input("c:3#2", 1001)); // open
+    L.markRepresented("c:3#1"); // represent
+    L.markEscalateAttempt("c:3#1"); // escalate-attempt
+    L.close("c:3#1"); // close
+    // open, open, represent, escalate-attempt, close = 5 mutations.
+    expect(snapshots.length).toBe(5);
+    expect(snapshots[1].map((o) => o.originTurnId).sort()).toEqual(["c:3#1", "c:3#2"]);
+    // last snapshot reflects the close.
+    expect(snapshots[4].map((o) => o.originTurnId)).toEqual(["c:3#2"]);
+  });
+
+  it("does NOT fire onChange for an idempotent (already-open) openIfAbsent", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    expect(L.openIfAbsent(input("c:3#1", 1000))).toBe(true);
+    expect(L.openIfAbsent(input("c:3#1", 9999))).toBe(false); // dup
+    expect(snapshots.length).toBe(1);
+  });
+
+  it("does NOT fire onChange for a close of an unknown id", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    expect(L.close("nope")).toBe(false);
+    expect(snapshots.length).toBe(0);
+  });
+
+  it("markEscalateAttempt increments per call and persists", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000));
+    expect(L.markEscalateAttempt("c:3#1")).toBe(1);
+    expect(L.markEscalateAttempt("c:3#1")).toBe(2);
+    expect(L.list()[0].escalateAttempts).toBe(2);
+    expect(L.markEscalateAttempt("missing")).toBe(0);
+  });
+
+  it("hydrate restores the open set WITH counters and does not fire onChange", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.hydrate([
+      { originTurnId: "c:3#715", chatId: "-100123", threadId: 3, messageId: 715, text: "x", openedAt: 1000, representCount: 2, escalateAttempts: 1 },
+    ]);
+    expect(snapshots.length).toBe(0); // hydrate is restoration, not a mutation
+    expect(L.isOpen("c:3#715")).toBe(true);
+    expect(L.list()[0].representCount).toBe(2);
+    expect(L.list()[0].escalateAttempts).toBe(1);
+    // a represented obligation at/over max decides 'escalate', preserving count across restart
+    expect(L.decideAtIdle().action).toBe("escalate");
+  });
+
+  it("hydrate skips malformed rows", () => {
+    const L = new ObligationLedger();
+    L.hydrate([
+      { originTurnId: "c:3#1", chatId: "-100123", messageId: 1, text: "x", openedAt: 1000, representCount: 0 },
+      { originTurnId: "", chatId: "x", messageId: 0, text: "", openedAt: 0, representCount: 0 } as Obligation,
+    ]);
+    expect(L.size()).toBe(1);
+  });
+});

package/telegram-plugin/tests/obligation-store.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import {
+  loadObligations,
+  persistObligations,
+  type ObligationStoreFsSeam,
+} from "../gateway/obligation-store.js";
+import type { Obligation } from "../gateway/obligation-ledger.js";
+
+/** In-memory fs seam with an atomic rename, so the store's tmp→rename
+ *  crash-safety contract is exercised without touching the real disk. */
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed));
+  const calls: string[] = [];
+  const fs: ObligationStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+      return files.get(p)!;
+    },
+    writeFileSync: (p, d) => {
+      calls.push(`write:${p}`);
+      files.set(p, d);
+    },
+    renameSync: (a, b) => {
+      calls.push(`rename:${a}->${b}`);
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+      files.set(b, files.get(a)!);
+      files.delete(a);
+    },
+    existsSync: (p) => files.has(p),
+  };
+  return { fs, files, calls };
+}
+
+const PATH = "/state/agent/telegram/obligations.json";
+
+function ob(id: string, over: Partial<Obligation> = {}): Obligation {
+  return {
+    originTurnId: id,
+    chatId: "-100123",
+    threadId: 3,
+    messageId: Number(id.split("#").pop() ?? 1),
+    text: "do the thing",
+    openedAt: 1000,
+    representCount: 0,
+    ...over,
+  };
+}
+
+describe("obligation-store", () => {
+  it("round-trips the open set, preserving representCount + escalateAttempts", () => {
+    const { fs } = memFs();
+    const snap: Obligation[] = [
+      ob("c:3#715", { representCount: 2, escalateAttempts: 1 }),
+      ob("c:5#900", { representCount: 0, openedAt: 2000 }),
+    ];
+    persistObligations(PATH, fs, snap);
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded).toEqual(snap);
+    expect(loaded[0].escalateAttempts).toBe(1);
+    expect(loaded[0].representCount).toBe(2);
+  });
+
+  it("persists atomically: writes a sibling .tmp then renames over the path", () => {
+    const { fs, calls, files } = memFs();
+    persistObligations(PATH, fs, [ob("c:3#1")]);
+    expect(calls).toEqual([`write:${PATH}.tmp`, `rename:${PATH}.tmp->${PATH}`]);
+    // The tmp is gone (renamed); only the real path remains.
+    expect(files.has(PATH)).toBe(true);
+    expect(files.has(`${PATH}.tmp`)).toBe(false);
+  });
+
+  it("returns [] for a missing file", () => {
+    const { fs } = memFs();
+    expect(loadObligations(PATH, fs)).toEqual([]);
+  });
+
+  it("returns [] for a torn / non-JSON file (crash mid-write tolerance)", () => {
+    const { fs } = memFs({ [PATH]: '{"v":1,"obligations":[{"originTurnId":"c:3#7' });
+    expect(loadObligations(PATH, fs)).toEqual([]);
+  });
+
+  it("returns [] for a wrong-version or wrong-shape envelope", () => {
+    const a = memFs({ [PATH]: JSON.stringify({ v: 2, obligations: [ob("c:3#1")] }) });
+    expect(loadObligations(PATH, a.fs)).toEqual([]);
+    const b = memFs({ [PATH]: JSON.stringify({ v: 1, obligations: "nope" }) });
+    expect(loadObligations(PATH, b.fs)).toEqual([]);
+  });
+
+  it("filters out malformed rows but keeps valid ones", () => {
+    const raw = JSON.stringify({
+      v: 1,
+      obligations: [
+        ob("c:3#715"),
+        { originTurnId: "", chatId: "x" }, // empty id → dropped
+        { nope: true }, // missing fields → dropped
+        ob("c:5#900", { openedAt: 2000 }),
+      ],
+    });
+    const { fs } = memFs({ [PATH]: raw });
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded.map((o) => o.originTurnId)).toEqual(["c:3#715", "c:5#900"]);
+  });
+
+  it("never throws on a write failure — degrades to in-memory (logs)", () => {
+    const logs: string[] = [];
+    const fs: ObligationStoreFsSeam = {
+      readFileSync: () => "",
+      writeFileSync: () => {
+        throw new Error("EROFS read-only fs");
+      },
+      renameSync: () => {},
+      existsSync: () => false,
+    };
+    expect(() => persistObligations(PATH, fs, [ob("c:3#1")], (l) => logs.push(l))).not.toThrow();
+    expect(logs.join("")).toContain("persist FAILED");
+  });
+});