switchroom 0.20.6 → 0.20.7

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

@@ -21997,7 +21997,7 @@ var init_schema = __esm(() => {
       reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent \u2192 uses global."),
       consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent \u2192 global.")
     }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults."),
-    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_RESERVED_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, GRAPH_SEED_MIN_SIMILARITY, " + "LLM_SUPPORTS_MAX_ITEMS, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_RESERVED_SLOTS reserves out of; " + "unset means upstream's own default; and " + "HINDSIGHT_API_WORKER_RETAIN_RESERVED_SLOTS \u2014 the reserved slot FLOOR for the " + "retain (memory write) lane, carved from that same total; unset means " + "upstream's own 0, i.e. no floor and retain competes for the shared " + "pool; and " + "the pre-0.8.6 name HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS is still " + "accepted for every operation type and normalised to " + "..._RESERVED_SLOTS on the way in, because setting both names for " + "one type is a hard boot failure in the engine and switchroom " + "therefore emits only the canonical name; and " + "HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY \u2014 the cosine-similarity floor a " + "candidate must reach to be returned by the semantic retrieval arm at " + "all (0..1); unset means upstream's own 0.3, and where it should sit " + "depends on the bank's embedding model and phrasing diversity, so " + "switchroom ships no opinion; and " + "HINDSIGHT_MCP_RECALL_BUDGET_MODE \u2014 the rollback knob for switchroom's " + "mcp-recall-token-budget image patch; `legacy` restores upstream's " + "exact pre-patch recall returns, anything else or unset is the " + "honest-envelope mode; and " + "HINDSIGHT_API_LLM_TEMPERATURE_REFLECT \u2014 upstream's own per-op reflect " + "temperature knob, made live by switchroom's reflect-temperature image " + "patch; a float, or `none` to omit the kwarg (provider default, " + "upstream's accidental pre-patch behaviour); unset means the image's " + "baked default 0.1; and " + "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT \u2014 the background " + "half of switchroom's recall-admission split (#3660): of the " + "RECALL_MAX_CONCURRENT admission slots, at most this many may be held " + "by background consolidation recalls at once, so foreground per-turn " + "recall always keeps the remainder; must be >= 1 and strictly less " + "than RECALL_MAX_CONCURRENT or the engine refuses to boot; unset " + "means the image's derived default min(2, RECALL_MAX_CONCURRENT - 1); " + "1 biases hard toward the interactive lane while a consolidation " + "backlog drains; and " + "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S \u2014 the rollback/tuning knob for " + "switchroom's MM-refresh-debounce image patch: the minimum seconds " + "between consolidation-triggered refreshes of one mental model; unset " + "means the image's baked 3600, 0 restores upstream's " + "refresh-every-round behaviour; explicit and cron-scheduled refreshes " + "are never debounced; and " + "HINDSIGHT_API_TEMPORAL_LANGUAGES \u2014 the language set dateparser is " + "restricted to during temporal query analysis, made live by switchroom's " + "temporal-language image patch (which ended a 200+-locale auto-detection " + "pass that blocked the shared asyncio loop on every recall); " + "comma-separated, unset means the image's baked `en`, set e.g. `en,es` to " + "restore i18n parsing), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
+    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_RESERVED_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, GRAPH_SEED_MIN_SIMILARITY, " + "LLM_SUPPORTS_MAX_ITEMS, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_RESERVED_SLOTS reserves out of; " + "unset means upstream's own default; and " + "HINDSIGHT_API_WORKER_RETAIN_RESERVED_SLOTS \u2014 the reserved slot FLOOR for the " + "retain (memory write) lane, carved from that same total; unset means " + "upstream's own 0, i.e. no floor and retain competes for the shared " + "pool; and " + "the pre-0.8.6 name HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS is still " + "accepted for every operation type and normalised to " + "..._RESERVED_SLOTS on the way in, because setting both names for " + "one type is a hard boot failure in the engine and switchroom " + "therefore emits only the canonical name; and " + "HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY \u2014 the cosine-similarity floor a " + "candidate must reach to be returned by the semantic retrieval arm at " + "all (0..1); unset means upstream's own 0.3, and where it should sit " + "depends on the bank's embedding model and phrasing diversity, so " + "switchroom ships no opinion; and " + "HINDSIGHT_MCP_RECALL_BUDGET_MODE \u2014 the rollback knob for switchroom's " + "mcp-recall-token-budget image patch; `legacy` restores upstream's " + "exact pre-patch recall returns, anything else or unset is the " + "honest-envelope mode; and " + "HINDSIGHT_API_LLM_TEMPERATURE_REFLECT \u2014 upstream's own per-op reflect " + "temperature knob, made live by switchroom's reflect-temperature image " + "patch; a float, or `none` to omit the kwarg (provider default, " + "upstream's accidental pre-patch behaviour); unset means the image's " + "baked default 0.1; and " + "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT \u2014 the background " + "half of switchroom's recall-admission split (#3660): of the " + "RECALL_MAX_CONCURRENT admission slots, at most this many may be held " + "by background consolidation recalls at once, so foreground per-turn " + "recall always keeps the remainder; must be >= 1 and strictly less " + "than RECALL_MAX_CONCURRENT or the engine refuses to boot; unset " + "means the image's derived default min(2, RECALL_MAX_CONCURRENT - 1); " + "1 biases hard toward the interactive lane while a consolidation " + "backlog drains; and " + "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S \u2014 the rollback/tuning knob for " + "switchroom's MM-refresh-debounce image patch: the minimum seconds " + "between consolidation-triggered refreshes of one mental model; unset " + "means the image's baked 3600, 0 restores upstream's " + "refresh-every-round behaviour; explicit and cron-scheduled refreshes " + "are never debounced; and " + "HINDSIGHT_API_TEMPORAL_LANGUAGES \u2014 the language set dateparser is " + "restricted to during temporal query analysis, made live by switchroom's " + "temporal-language image patch (which ended a 200+-locale auto-detection " + "pass that blocked the shared asyncio loop on every recall); " + "comma-separated, unset means the image's baked `en`, set e.g. `en,es` to " + "restore i18n parsing; and " + "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS \u2014 the max chars of query text " + "dateparser.search_dates() is handed during temporal analysis (0 = " + "unlimited), made live by switchroom's temporal-offload image patch " + "(which moved the synchronous extraction off the shared asyncio loop onto " + "a single-worker thread and bounds its input, ending multi-second loop " + "stalls on multi-KB consolidation queries); unset means the image's baked " + "2000, set 0 to restore an unbounded full scan), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
   });
   MicrosoftWorkspaceConfigSchema = exports_external.object({
     microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL \u2014 omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
@@ -82242,6 +82242,9 @@ function closeFlushCompletionWindows(registry, now) {
   registry?.completeAll?.(now);
   return closed;
 }
+function parkedTurnStartCount() {
+  return parkedTurnStarts.length;
+}
 function drainParkedTurnStartsForChat(deps, chatId, threadId) {
   const wantThread = envThreadIdNum(threadId);
   const drained = [];
@@ -87376,7 +87379,8 @@ var HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS = new Set([
   "HINDSIGHT_API_RETAIN_WALL_TIMEOUT",
   "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT",
   "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S",
-  "HINDSIGHT_API_TEMPORAL_LANGUAGES"
+  "HINDSIGHT_API_TEMPORAL_LANGUAGES",
+  "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS"
 ]);
 var HINDSIGHT_WORKER_SLOT_TYPES = [
   "consolidation",
@@ -92780,7 +92784,24 @@ function redeliverBufferedInbound(buffer, agent, send, spool, onDelivered) {
   const pending = buffer.drain(agent);
   let redelivered = 0;
   let rebuffered = 0;
+  let retracted = 0;
   for (const { merged, originals } of planBufferedRedelivery(pending)) {
+    let proceed = true;
+    if (buffer.beforeRedeliver != null) {
+      try {
+        proceed = buffer.beforeRedeliver(merged);
+      } catch (e) {
+        proceed = true;
+        process.stderr.write(`redeliver beforeRedeliver threw \u2014 failing open (deliver): ${String(e)}
+`);
+      }
+    }
+    if (!proceed) {
+      for (const o of originals)
+        spool?.ack(o);
+      retracted += originals.length;
+      continue;
+    }
     let delivered = false;
     try {
       delivered = send(merged);
@@ -92798,7 +92819,7 @@ function redeliverBufferedInbound(buffer, agent, send, spool, onDelivered) {
       rebuffered += originals.length;
     }
   }
-  return { drained: pending.length, redelivered, rebuffered };
+  return { drained: pending.length, redelivered, rebuffered, retracted };
 }
 function isMergeableUserInbound(msg) {
   return msg.type === "inbound" && (msg.meta == null || msg.meta.source == null && msg.meta.button_callback == null);
@@ -92915,7 +92936,62 @@ function createPendingInboundBuffer(opts = {}) {
       for (const q of queues.values())
         n += q.length;
       return n;
+    },
+    beforeRedeliver: opts.beforeRedeliver
+  };
+}
+
+// gateway/represent-guard.ts
+function shouldSuppressRepresent(o, deps) {
+  if (!deps.historyEnabled)
+    return false;
+  if (o.lastRepresentedAt == null) {
+    if (o.openedAt == null)
+      return false;
+    return deps.hasOutboundDeliveredSince(o.chatId, o.openedAt, o.threadId);
+  }
+  return deps.hasOutboundDeliveredSince(o.chatId, o.lastRepresentedAt, o.threadId);
+}
+
+// gateway/represent-delivery-guard.ts
+function makeRepresentRedeliveryGuard(deps) {
+  return (msg) => {
+    if (!deps.enabled)
+      return true;
+    if (msg.meta?.source !== "obligation_represent")
+      return true;
+    const originTurnId = msg.meta?.origin_turn_id;
+    if (originTurnId == null)
+      return true;
+    const o = deps.ledger.get(originTurnId);
+    if (o == null) {
+      deps.log(`telegram gateway: represent retracted at delivery \u2014 obligation already ` + `closed since decision (no re-fire) origin=${originTurnId}
+`);
+      return false;
+    }
+    const suppress = shouldSuppressRepresent(o, {
+      historyEnabled: deps.historyEnabled,
+      hasOutboundDeliveredSince: (chatId, sinceMs, threadId) => deps.hasOutboundDeliveredSince(chatId, sinceMs, threadId, deps.minReplyChars)
+    });
+    if (suppress) {
+      deps.ledger.close(originTurnId);
+      deps.log(`telegram gateway: represent retracted at delivery \u2014 reply landed since ` + `decision (no re-fire) origin=${originTurnId}
+`);
+      return false;
     }
+    return true;
+  };
+}
+function makeSessionBusyDrainDeferral(boundMs) {
+  let deferringSince = null;
+  return (busy, now) => {
+    if (!busy || boundMs <= 0) {
+      deferringSince = null;
+      return false;
+    }
+    if (deferringSince == null)
+      deferringSince = now;
+    return now - deferringSince < boundMs;
   };
 }
 
@@ -92987,6 +93063,9 @@ class ObligationLedger {
   isOpen(originTurnId) {
     return this.open.has(originTurnId);
   }
+  get(originTurnId) {
+    return this.open.get(originTurnId);
+  }
   hasOpen() {
     return this.open.size > 0;
   }
@@ -94512,7 +94591,24 @@ function redeliverBufferedInbound2(buffer, agent, send, spool, onDelivered) {
   const pending = buffer.drain(agent);
   let redelivered = 0;
   let rebuffered = 0;
+  let retracted = 0;
   for (const { merged, originals } of planBufferedRedelivery2(pending)) {
+    let proceed = true;
+    if (buffer.beforeRedeliver != null) {
+      try {
+        proceed = buffer.beforeRedeliver(merged);
+      } catch (e) {
+        proceed = true;
+        process.stderr.write(`redeliver beforeRedeliver threw \u2014 failing open (deliver): ${String(e)}
+`);
+      }
+    }
+    if (!proceed) {
+      for (const o of originals)
+        spool?.ack(o);
+      retracted += originals.length;
+      continue;
+    }
     let delivered = false;
     try {
       delivered = send(merged);
@@ -94530,7 +94626,7 @@ function redeliverBufferedInbound2(buffer, agent, send, spool, onDelivered) {
       rebuffered += originals.length;
     }
   }
-  return { drained: pending.length, redelivered, rebuffered };
+  return { drained: pending.length, redelivered, rebuffered, retracted };
 }
 function isMergeableUserInbound2(msg) {
   return msg.type === "inbound" && (msg.meta == null || msg.meta.source == null && msg.meta.button_callback == null);
@@ -95425,6 +95521,9 @@ class ObligationLedger2 {
   isOpen(originTurnId) {
     return this.open.has(originTurnId);
   }
+  get(originTurnId) {
+    return this.open.get(originTurnId);
+  }
   hasOpen() {
     return this.open.size > 0;
   }
@@ -95587,23 +95686,24 @@ function driveEscalation(args) {
   });
 }
 
-// gateway/represent-guard.ts
-function shouldSuppressRepresent(o, deps) {
-  if (!deps.historyEnabled)
-    return false;
-  if (o.lastRepresentedAt == null) {
-    if (o.openedAt == null)
-      return false;
-    return deps.hasOutboundDeliveredSince(o.chatId, o.openedAt, o.threadId);
-  }
-  return deps.hasOutboundDeliveredSince(o.chatId, o.lastRepresentedAt, o.threadId);
-}
-
 // gateway/escalation-bridge-gate.ts
 function shouldDeferEscalationForBridge(deps) {
   return !deps.bridgeAlive;
 }
 
+// gateway/stream-render.ts
+init_history();
+init_rich_send();
+var PARKED_TURN_START_TTL_MS2 = 30 * 60000;
+var QUEUED_CARD_ENABLED2 = process.env.SWITCHROOM_QUEUED_CARD !== "0";
+var BUZZ_ENABLED2 = process.env.BUZZ_ENABLED === "1" || process.env.BUZZ_ENABLED === "true";
+var BUZZ_ORIGIN_STAMP_ACTIVE2 = BUZZ_ENABLED2 && isBuzzTurnRoutingEnabled();
+var parkedTurnStarts2 = [];
+var flushCompletionTracker2 = new FlushCompletionTracker;
+function parkedTurnStartCount2() {
+  return parkedTurnStarts2.length;
+}
+
 // gateway/obligation-wiring.ts
 function createObligationWiring(deps) {
   const {
@@ -95682,7 +95782,9 @@ function createObligationWiring(deps) {
       return;
     const agent = process.env.SWITCHROOM_AGENT_NAME ?? "";
     const now = Date.now();
-    const backgroundWorkActive = OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now);
+    const liveTurn = getCurrentTurn();
+    const sessionBusy = liveTurn != null && liveTurn.endedAt == null || parkedTurnStartCount2() > 0;
+    const backgroundWorkActive = OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && (agentHasInFlightBackgroundWork(now) || sessionBusy);
     const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 || backgroundWorkActive || OBLIGATION_REPRESENT_GRACE_MS > 0 ? {
       now,
       graceMs: OBLIGATION_ESCALATE_GRACE_MS,
@@ -95694,7 +95796,7 @@ function createObligationWiring(deps) {
     if (decision.action === "none" || o == null) {
       if (backgroundWorkActive && obligationLedger.hasOpen() && now - lastBgWorkDeferLogMs > 60000) {
         lastBgWorkDeferLogMs = now;
-        process.stderr.write(`telegram gateway: obligation sweep deferred \u2014 in-flight autonomous sub-agent work ` + `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60000)}m from receipt)
+        process.stderr.write(`telegram gateway: obligation sweep deferred \u2014 in-flight autonomous sub-agent work ` + `or busy CLI session behind a poke-cleared turn ` + `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60000)}m from receipt)
 `);
       }
       return;
@@ -102479,10 +102581,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.20.6";
-var COMMIT_SHA = "4b1ad9b1";
-var COMMIT_DATE = "2026-08-04T07:34:19Z";
-var LATEST_PR = 4340;
+var VERSION2 = "0.20.7";
+var COMMIT_SHA = "bc107185";
+var COMMIT_DATE = "2026-08-04T10:20:28Z";
+var LATEST_PR = 4343;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -108501,7 +108603,8 @@ var pendingInboundBuffer = createPendingInboundBuffer({
     const threadOpts = evThread != null ? { message_thread_id: evThread } : {};
     swallowingApiCall(() => bot.api.sendMessage(chat, "\u23F3 Messages are arriving faster than I can process them. Your messages are saved and will be handled once I finish the current turn \u2014 if any can't be picked up, I'll ask you to resend it.", { ...threadOpts }), { chat_id: chat, verb: "inbound-buffer-eviction" });
   },
-  onHandbackEnqueue: (chatId, threadId, ts) => subagentHandbackMarker.record(chatId, threadId, ts)
+  onHandbackEnqueue: (chatId, threadId, ts) => subagentHandbackMarker.record(chatId, threadId, ts),
+  beforeRedeliver: makeRepresentRedeliveryGuard({ enabled: OBLIGATION_LEDGER_ENABLED, historyEnabled: HISTORY_ENABLED, ledger: obligationLedger, hasOutboundDeliveredSince, minReplyChars: OBLIGATION_REPRESENT_GUARD_MIN_REPLY_CHARS, log: (l) => process.stderr.write(l) })
 });
 function agentHasInFlightBackgroundWork(now) {
   if (countRunningWorkers() > 0)
@@ -109532,12 +109635,16 @@ if (isGatewayMain)
     }
   })();
 var IDLE_DRAIN_INTERVAL_MS = 5000;
+var idleDrainBusyDefer = makeSessionBusyDrainDeferral(OBLIGATION_BACKGROUND_WORK_GRACE_MS);
 if (isGatewayMain && !STATIC) {
   setInterval(() => {
     const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? "";
     const r = idleDrainTick(pendingInboundBuffer, selfAgent, () => {
       if (turnInFlightForGate())
         return false;
+      const sessionBusy = currentTurn != null && currentTurn.endedAt == null || parkedTurnStartCount() > 0;
+      if (idleDrainBusyDefer(sessionBusy, Date.now()))
+        return false;
       const c = ipcServer.getClient(selfAgent);
       return c != null && c.isAlive();
     }, (m) => ipcServer.sendToAgent(selfAgent, m), inboundSpool, trackRedeliveredInbound);

package/telegram-plugin/gateway/gateway.ts

@@ -461,7 +461,7 @@ import {
   type SendReplyGatewayDeps,
   type DeliverCapturedProseDeps,
 } from './outbound-send-path.js'
-import { handleSessionEvent as handleSessionEventCore, drainParkedTurnStartsForChat, closeFlushCompletionWindows } from './stream-render.js'
+import { handleSessionEvent as handleSessionEventCore, drainParkedTurnStartsForChat, closeFlushCompletionWindows, parkedTurnStartCount } from './stream-render.js'
 import { createNarrativeLane } from './narrative-lane.js'
 import {
   parseAgentCallback,
@@ -659,6 +659,7 @@ 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 { makeRepresentRedeliveryGuard, makeSessionBusyDrainDeferral } from './represent-delivery-guard.js'
 import { isCronIdentity, isCronInjectFire, deliverInjectWithFallback, replyCallerIsForeignSession } from './cron-session.js'
 import {
   ObligationLedger,
@@ -9788,6 +9789,11 @@ const pendingInboundBuffer = createPendingInboundBuffer({
   // enqueue chokepoint so a boot-replayed handback (not just the live synthesis
   // push) populates it. Every `subagent_handback` push funnels through here.
   onHandbackEnqueue: (chatId, threadId, ts) => subagentHandbackMarker.record(chatId, threadId, ts),
+  // F1 (fix/represent-double-send-delivery-recheck) — delivery-time represent
+  // retract. Every drain path hands its buffered inbounds through this gate; a
+  // stale `obligation_represent` (its reply landed since the sweep decided it) is
+  // dropped here rather than duplicated into the CLI queue. See represent-delivery-guard.ts.
+  beforeRedeliver: makeRepresentRedeliveryGuard({ enabled: OBLIGATION_LEDGER_ENABLED, historyEnabled: HISTORY_ENABLED, ledger: obligationLedger, hasOutboundDeliveredSince, minReplyChars: OBLIGATION_REPRESENT_GUARD_MIN_REPLY_CHARS, log: (l) => process.stderr.write(l) }),
 })
 
 // PR2 obligation-ledger idle sweep. Re-present an OPEN obligation only at a
@@ -11742,30 +11748,19 @@ if (isGatewayMain) (() => {  // #2996 P0c: gated — starts webhook-ingest UDS s
 })()
 
 // ─── Opportunistic idle-drain of pendingInboundBuffer ─────────────────────
-// pendingInboundBuffer otherwise drains only on (a) bridge re-register
-// (onClientRegistered) or (b) the silence-poke framework fallback
-// clearing a wedged turn (#1546). NEITHER fires when a message is
-// buffered during a bridge-IPC flap that then settles with no
-// subsequent clean re-register AND claude is idle (no active turn →
-// silence-poke never arms). The message orphans until a manual restart
-// (finn, 2026-05-19 — buffered "verify with mff-query.py cashflow"
-// while idle; last `bridge registered` predated the buffer push, so
-// onClientRegistered's drain never ran for it).
-//
-// This is the third drain trigger. It's gated to be zero-cost and
-// zero-churn: skip entirely when nothing is buffered (one Map.get, no
-// log), when the bridge isn't alive (exactly sendToAgent's own guard —
-// so we never drain into a dead bridge and re-buffer/log-spin), OR
-// when a turn is in flight. The turn gate is #1556: a message
-// delivered while a turn is active is NOT safely queued by the bridge
-// — claude types it into its TUI composer and the auto-submit races
-// turn-completion, stranding it (the lawgpt wedge). Draining only at
-// `activeTurnStartedAt.size === 0` guarantees the channel notification
-// lands at an idle prompt and submits as a fresh turn. Only when there
-// IS a buffered message AND a live bridge AND no active turn do we
-// reuse the #1546 `redeliverBufferedInbound` (lossless: re-buffers any
-// per-message miss).
+// The THIRD drain trigger, beside bridge re-register (onClientRegistered) and
+// the silence-poke framework fallback (#1546): neither fires when a message is
+// buffered during a bridge-IPC flap that settles with no clean re-register while
+// claude is idle, so it orphans until a manual restart (finn, 2026-05-19). Gated
+// zero-cost/zero-churn: skip when nothing is buffered, when the bridge is dead,
+// or when a turn is in flight (#1556 — a message delivered mid-turn is typed into
+// claude's TUI composer and the auto-submit races turn-completion, stranding it).
 const IDLE_DRAIN_INTERVAL_MS = 5000
+// F2 (drain half) — bounded busy-defer. A ~5-min poke can clear the machine turn
+// while the CLI is still producing the answer; draining a represent into that busy
+// session re-queues it BEHIND the real reply → a duplicate. Defer while busy,
+// bounded so a wedged session still drains (F1 then retracts it post-reply).
+const idleDrainBusyDefer = makeSessionBusyDrainDeferral(OBLIGATION_BACKGROUND_WORK_GRACE_MS)
 if (isGatewayMain && !STATIC) {
   setInterval(() => {
     const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
@@ -11775,8 +11770,11 @@ if (isGatewayMain && !STATIC) {
       () => {
         // #1556: never drain mid-turn — that re-creates the composer
         // wedge this buffer exists to prevent. Gate reads the delivery
-        // machine (turnInFlightForGate).
+        // machine (turnInFlightForGate) AND, per F2, stream-render's live-turn
+        // mirror (a poke can clear the former while the latter is still busy).
         if (turnInFlightForGate()) return false
+        const sessionBusy = (currentTurn != null && currentTurn.endedAt == null) || parkedTurnStartCount() > 0
+        if (idleDrainBusyDefer(sessionBusy, Date.now())) return false
         const c = ipcServer.getClient(selfAgent)
         return c != null && c.isAlive()
       },

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

@@ -178,6 +178,15 @@ export class ObligationLedger {
     return this.open.has(originTurnId)
   }
 
+  /** The open obligation for `originTurnId`, or undefined if none is open. Read-
+   *  only accessor for the delivery-time represent re-check (represent-delivery-
+   *  guard.ts): a represent buffered while the obligation was open must be re-
+   *  evaluated against the obligation's CURRENT cutoff at the moment it is handed
+   *  to the CLI bridge, since a reply may have landed between decision and drain. */
+  get(originTurnId: string): Obligation | undefined {
+    return this.open.get(originTurnId)
+  }
+
   hasOpen(): boolean {
     return this.open.size > 0
   }

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

@@ -23,6 +23,7 @@ import { buildObligationRepresentInbound, type Obligation } from './obligation-l
 import { driveEscalation } from './escalation-drive.js'
 import { shouldSuppressRepresent } from './represent-guard.js'
 import { shouldDeferEscalationForBridge } from './escalation-bridge-gate.js'
+import { parkedTurnStartCount } from './stream-render.js'
 
 export function createObligationWiring(deps: ObligationWiringDeps) {
   const {
@@ -161,13 +162,26 @@ function obligationSweep(): void {
   if (turnInFlightForGate()) return // a turn is running — let it finish/answer
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
   const now = Date.now()
+  // Session-busy signal (F2, decision half). A ~5-min silence poke can clear the
+  // machine turn (`turnInFlightForGate()` above → false) while the CLI session is
+  // STILL producing the answer — stream-render's live-turn mirror (`currentTurn`
+  // whose endedAt is null, or a parked turn-start) still knows it is busy. Without
+  // this, the sweep decides + buffers a represent mid-answer; the real reply lands
+  // seconds later and the model consumes the queued represent → a duplicate answer
+  // (the two-authorities-disagree defect). We treat a busy mirror the SAME as
+  // in-flight background work: defer the represent, BOUNDED by the same grace, so a
+  // wedged/hung session cannot silence a genuinely-unanswered turn forever.
+  const liveTurn = getCurrentTurn()
+  const sessionBusy = (liveTurn != null && liveTurn.endedAt == null) || parkedTurnStartCount() > 0
   // Background-work grace: while genuine autonomous sub-agent work is in flight
   // (a running worker, or an orphaned foreground sub-agent — neither visible to
-  // the turn machine), an obligation younger than the ceiling is NOT re-presented
-  // /escalated. Bounded by OBLIGATION_BACKGROUND_WORK_GRACE_MS so escalation
-  // always eventually fires. =0 disables it.
+  // the turn machine), OR the CLI session is still busy behind a poke-cleared
+  // machine turn, an obligation younger than the ceiling is NOT re-presented
+  // /escalated. Bounded by OBLIGATION_BACKGROUND_WORK_GRACE_MS (measured from
+  // openedAt in decideAtIdle) so escalation always eventually fires. =0 disables it.
   const backgroundWorkActive =
-    OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now)
+    OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 &&
+    (agentHasInFlightBackgroundWork(now) || sessionBusy)
   // Grace window: skip an obligation whose handling turn ended < grace ago — its
   // trailing slow/worker answer may still be landing (over-escalation fix).
   // Per-represent grace: skip an obligation re-presented < grace ago — prevents
@@ -189,6 +203,7 @@ function obligationSweep(): void {
       lastBgWorkDeferLogMs = now
       process.stderr.write(
         `telegram gateway: obligation sweep deferred — in-flight autonomous sub-agent work ` +
+          `or busy CLI session behind a poke-cleared turn ` +
           `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60_000)}m from receipt)\n`,
       )
     }

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -49,6 +49,16 @@ export interface PendingInboundBuffer {
   depth: (agent: string) => number
   /** Test-only: total depth across all agents. */
   totalDepth: () => number
+  /**
+   * Delivery-time gate consulted by `redeliverBufferedInbound` for EVERY message
+   * it is about to hand to the bridge. Returns TRUE to proceed, FALSE to RETRACT
+   * (drop) the message (the spool entry is acked so it is not boot-replayed, and
+   * it is NOT re-buffered). The gateway wires this to the represent delivery
+   * re-check (represent-delivery-guard.ts): a represent buffered while its
+   * obligation was open must be re-evaluated at drain time, since a reply may have
+   * landed between the sweep's decision and this drain. Undefined ⇒ never retract.
+   */
+  beforeRedeliver?: (msg: InboundMessage) => boolean
 }
 
 export interface PendingInboundBufferOptions {
@@ -94,6 +104,13 @@ export interface PendingInboundBufferOptions {
    * breaks the push hot path.
    */
   onHandbackEnqueue?: (chatId: string, threadId: number | undefined, ts: number) => void
+  /**
+   * Delivery-time retract gate — see `PendingInboundBuffer.beforeRedeliver`. The
+   * gateway supplies the represent delivery re-check here so EVERY drain path
+   * (idle-drain, bridge re-register, silence-poke fallback, turn-end) inherits it
+   * by construction rather than by per-call-site discipline.
+   */
+  beforeRedeliver?: (msg: InboundMessage) => boolean
 }
 
 /**
@@ -123,16 +140,38 @@ export function redeliverBufferedInbound(
   // silently dropped (clerk 2026-06-03). `send` returning true only means
   // the bytes reached the bridge, NOT that claude consumed them.
   onDelivered?: (merged: InboundMessage, originals: InboundMessage[]) => void,
-): { drained: number; redelivered: number; rebuffered: number } {
+): { drained: number; redelivered: number; rebuffered: number; retracted: number } {
   const pending = buffer.drain(agent)
   let redelivered = 0
   let rebuffered = 0
+  let retracted = 0
   // Collapse consecutive same-sender Telegram user messages into one turn
   // (see planBufferedRedelivery) so a forwarded burst that spanned a turn
   // boundary doesn't fan out into N sequential replies. System inbounds
   // (vault grants, approvals, cron, handbacks — anything with meta.source)
   // are never merged and are delivered individually exactly as before.
   for (const { merged, originals } of planBufferedRedelivery(pending)) {
+    // Delivery-time retract (F1): a buffered `obligation_represent` whose reply
+    // has landed since the sweep decided it is stale — drop it rather than hand
+    // a duplicate to the CLI queue. Ack the spool so it is not boot-replayed and
+    // do NOT re-buffer. The gateway closure closes the ledger + logs the retract.
+    // FAIL-OPEN: a throwing predicate must never silence or lose a real message,
+    // nor abort the drain loop (which would strand every following message and
+    // crash the setInterval tick). On throw we treat it as "deliver".
+    let proceed = true
+    if (buffer.beforeRedeliver != null) {
+      try {
+        proceed = buffer.beforeRedeliver(merged)
+      } catch (e) {
+        proceed = true
+        process.stderr.write(`redeliver beforeRedeliver threw — failing open (deliver): ${String(e)}\n`)
+      }
+    }
+    if (!proceed) {
+      for (const o of originals) spool?.ack(o)
+      retracted += originals.length
+      continue
+    }
     let delivered = false
     try {
       delivered = send(merged)
@@ -157,7 +196,7 @@ export function redeliverBufferedInbound(
       rebuffered += originals.length
     }
   }
-  return { drained: pending.length, redelivered, rebuffered }
+  return { drained: pending.length, redelivered, rebuffered, retracted }
 }
 
 /** True when `msg` is an ordinary Telegram user message eligible to be
@@ -312,7 +351,7 @@ export function idleDrainTick(
   // enrols redelivered inbounds in the deliver-until-acked queue (parity with
   // the bridgeUp drain — clerk lost-message incident, 2026-06-03).
   onDelivered?: (merged: InboundMessage, originals: InboundMessage[]) => void,
-): { drained: number; redelivered: number; rebuffered: number } | null {
+): { drained: number; redelivered: number; rebuffered: number; retracted: number } | null {
   if (!agent) return null
   if (buffer.depth(agent) === 0) return null
   if (!isBridgeAlive()) return null
@@ -412,5 +451,6 @@ export function createPendingInboundBuffer(
       for (const q of queues.values()) n += q.length
       return n
     },
+    beforeRedeliver: opts.beforeRedeliver,
   }
 }