switchroom 0.18.3 → 0.18.7

package/telegram-plugin/tests/button-tap-turn-gated.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Regression guard — agent-authored inline-keyboard button taps (`agent:`
+ * callback_data) are turn-safe (#271 button path, the mid-turn-strand).
+ *
+ * THE BUG: the `agent:` callback handler delivered the synthesized tap
+ * inbound with a bare `ipcServer.sendToAgent` + busy-mark, and buffered
+ * ONLY when the bridge was offline (`delivered=false`). It never ran the
+ * #1556 turn gate the normal inbound path uses. So a tap landing WHILE a
+ * turn was in flight fired the MCP channel notification mid-turn, the
+ * unmodified CLI typed it into its TUI composer, and the auto-submit raced
+ * turn-completion — the tap stranded in the composer with nothing to rescue
+ * it (the buffer only catches bridge-offline). It also skipped the pre-send
+ * composer clear and the deliver-until-acked tracking, so a stranded tap was
+ * never sweep-redelivered.
+ *
+ * THE FIX: the tap routes through `deliverButtonTapInbound`, which consults
+ * the SAME turn gate (mid-turn → `buffer-until-idle`, flushed at turn-end),
+ * clears the composer before sending, and enrols the delivery in the
+ * deliver-until-acked queue so the sweep rescues a strand. Bridge-offline
+ * still spools + shows the restart notice (unchanged UX).
+ *
+ * gateway.ts is a large side-effecting module (top-level `bot.on`, ipc
+ * server, timers) that can't be imported into a unit test, so this file
+ * pins (a) the gate decision for a button tap's shape via the pure gate, and
+ * (b) that the handler + helper wire the turn-safe machinery structurally —
+ * exactly the strategy `vault-resume-turn-gated.test.ts` uses for the resume
+ * synthetics.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decideInboundDelivery } from "../gateway/inbound-delivery-gate.js";
+import { shouldTrackDelivery } from "../gateway/inbound-delivery-confirm.js";
+import { planBufferedRedelivery } from "../gateway/pending-inbound-buffer.js";
+import type { InboundMessage } from "../gateway/ipc-protocol.js";
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, "..", "gateway", "gateway.ts"),
+  "utf-8",
+);
+
+describe("agent button taps use the turn-gate (mid-turn → buffer)", () => {
+  it("a button tap's gate shape buffers mid-turn, delivers when idle", () => {
+    // A button tap is never steering and never an interrupt — the exact
+    // inputs deliverButtonTapInbound passes to the gate.
+    const shape = { isSteering: false as const, isInterrupt: false as const };
+    // Tap lands WHILE a turn is in flight → held until claude goes idle
+    // (the mid-turn strand the raw sendToAgent used to cause).
+    expect(decideInboundDelivery({ ...shape, turnInFlight: true })).toBe(
+      "buffer-until-idle",
+    );
+    // Tap lands at an idle prompt → delivered immediately.
+    expect(decideInboundDelivery({ ...shape, turnInFlight: false })).toBe(
+      "deliver",
+    );
+  });
+
+  it("a button tap is enrolled by shouldTrackDelivery (no source, non-empty body)", () => {
+    // The tap inbound carries no meta.source and a non-empty
+    // `[user tapped button: …]` body, so it IS tracked — the strand it can
+    // suffer must be re-deliverable by the sweep.
+    expect(
+      shouldTrackDelivery({
+        isSteering: false,
+        isInterrupt: false,
+        hasSource: false,
+        effectiveText: "[user tapped button: approve_pr_547]",
+      }),
+    ).toBe(true);
+  });
+
+  describe("deliverButtonTapInbound helper", () => {
+    const start = gatewaySrc.indexOf(
+      "async function deliverButtonTapInbound",
+    );
+    // Bound the helper body by the next top-level declaration — it carries the
+    // gate, composer-clear, send, tracking, and bridge-offline branches.
+    const body = gatewaySrc.slice(
+      start,
+      gatewaySrc.indexOf("const pendingRestarts", start),
+    );
+
+    it("exists and is async (composer-clear await)", () => {
+      expect(start, "deliverButtonTapInbound helper missing").toBeGreaterThan(0);
+      expect(body).toMatch(
+        /async function deliverButtonTapInbound\(\s*agent: string,\s*inbound: InboundMessage,\s*\): Promise<ButtonTapDeliveryOutcome>/,
+      );
+    });
+
+    it("consults the turn gate BEFORE any send, buffering mid-turn", () => {
+      const gateIdx = body.indexOf("reserveInboundDelivery(");
+      const bufIdx = body.indexOf("pendingInboundBuffer.push(");
+      const sendIdx = body.indexOf("ipcServer.sendToAgent(");
+      expect(gateIdx, "gate must be consulted").toBeGreaterThan(0);
+      expect(sendIdx, "helper must still deliver in the idle branch").toBeGreaterThan(gateIdx);
+      // The buffer-until-idle branch buffers BEFORE the send branch — the tap
+      // is never delivered mid-turn.
+      expect(bufIdx, "must buffer in the mid-turn branch").toBeGreaterThan(gateIdx);
+      expect(bufIdx, "buffer-until-idle precedes the send").toBeLessThan(sendIdx);
+      expect(body).toMatch(/decision === 'buffer-until-idle'/);
+      expect(body).toMatch(/return 'buffered-mid-turn'/);
+    });
+
+    it("clears the composer before the send (the marko wedge)", () => {
+      const clearIdx = body.indexOf("clearAgentComposer");
+      const sendIdx = body.indexOf("ipcServer.sendToAgent(");
+      expect(clearIdx, "must import clearAgentComposer").toBeGreaterThan(0);
+      expect(clearIdx, "composer clear precedes the send").toBeLessThan(sendIdx);
+    });
+
+    it("tracks the delivery so the deliver-until-acked sweep rescues a strand", () => {
+      expect(body).toMatch(/DELIVERY_CONFIRM_ENABLED/);
+      expect(body).toMatch(/shouldTrackDelivery\(/);
+      expect(body).toMatch(/trackDelivery\(deliveryQueue,/);
+    });
+
+    it("buffers + spools on bridge-offline (existing behaviour intact)", () => {
+      // The idle-branch send missed → the reservation is released in lockstep
+      // and the tap is spooled to the pending-inbound buffer for replay.
+      expect(body).toMatch(/claudeBusyKeys\.delete\(reservedBusyKey\)/);
+      expect(body).toMatch(/return 'buffered-bridge-offline'/);
+      // The bridge-offline buffer push is the LAST push (after the send miss),
+      // so it always spools before returning the offline outcome.
+      const offlineIdx = body.indexOf("return 'buffered-bridge-offline'");
+      const lastBufIdx = body.lastIndexOf("pendingInboundBuffer.push(");
+      expect(lastBufIdx).toBeGreaterThan(0);
+      expect(lastBufIdx, "spool precedes the offline return").toBeLessThan(offlineIdx);
+    });
+  });
+
+  describe("the agent: callback handler routes through the helper", () => {
+    it("delivers the tap via deliverButtonTapInbound, not a raw sendToAgent", () => {
+      // Locate the agent-callback handler block.
+      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
+      expect(anchor, "agent-callback handler missing").toBeGreaterThan(0);
+      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      // The tap is routed through the turn-safe helper...
+      expect(handler).toMatch(/await deliverButtonTapInbound\(selfAgentBtn, inboundMsg\)/);
+      // ...and NOT via a raw ungated sendToAgent of the tap inbound (the
+      // regressed path that stranded the tap mid-turn).
+      expect(handler).not.toMatch(/ipcServer\.sendToAgent\(selfAgentBtn, inboundMsg\)/);
+    });
+
+    it("still shows the restart notice only on bridge-offline", () => {
+      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
+      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      // The restart notice is gated on the bridge-offline outcome — a mid-turn
+      // buffered tap must NOT nag the user (it will be actioned at idle).
+      expect(handler).toMatch(/btnOutcome === 'buffered-bridge-offline'/);
+      expect(handler).toMatch(/button-tap-restarting-notice/);
+    });
+
+    it("preserves the ack toast and single-use keyboard strip (UX unchanged)", () => {
+      const anchor = gatewaySrc.indexOf("const agentCb = parseAgentCallback(data)");
+      const handler = gatewaySrc.slice(anchor, gatewaySrc.indexOf("// Permission request buttons.", anchor));
+      // Ack toast fires FIRST (before delivery) so the tap always registers…
+      const ackIdx = handler.indexOf("answerCallbackQuery({ text: ackText })");
+      const deliverIdx = handler.indexOf("deliverButtonTapInbound(");
+      expect(ackIdx, "ack toast must fire").toBeGreaterThan(0);
+      expect(ackIdx, "ack toast fires before delivery").toBeLessThan(deliverIdx);
+      // …and the single-use keyboard strip still runs after.
+      expect(handler).toMatch(/keyboardIsSingleUse\(metaForMessage\)/);
+      expect(handler).toMatch(/editMessageReplyMarkup/);
+    });
+  });
+
+  describe("flush-path anti-storm guard (trackRedeliveredInbound)", () => {
+    it("skips tracking an id-less button tap, mirroring the immediate path", () => {
+      // The immediate path (deliverButtonTapInbound) refuses to enrol a tap
+      // without a real meta.message_id — the `enqueue` ack could never match
+      // it, so the never-drop sweep would re-fire until TTL. A tap that
+      // buffered mid-turn and flushed through trackRedeliveredInbound must be
+      // skipped by the SAME rule, or the storm exists on one path only.
+      const start = gatewaySrc.indexOf("function trackRedeliveredInbound");
+      expect(start, "trackRedeliveredInbound missing").toBeGreaterThan(0);
+      const body = gatewaySrc.slice(
+        start,
+        gatewaySrc.indexOf("\n}", start) + 2,
+      );
+      // The guard: button_callback-tagged AND no meta.message_id → return
+      // before trackDelivery.
+      const guardIdx = body.indexOf("merged.meta?.button_callback === 'true'");
+      const trackIdx = body.indexOf("trackDelivery(");
+      expect(guardIdx, "button-tap message_id guard missing").toBeGreaterThan(0);
+      expect(guardIdx, "guard must precede trackDelivery").toBeLessThan(trackIdx);
+      expect(body).toMatch(
+        /merged\.meta\.message_id == null \|\| merged\.meta\.message_id === ''/,
+      );
+    });
+  });
+});
+
+describe("buffered button taps never merge with adjacent user messages", () => {
+  const userMsg = (text: string, ts: number): InboundMessage => ({
+    type: "inbound",
+    chatId: "c1",
+    messageId: ts,
+    user: "u",
+    userId: 42,
+    ts,
+    text,
+    meta: { chat_id: "c1", user: "u", user_id: "42", ts: String(ts) },
+  });
+  // A tap inbound as the agent: callback handler builds it — same chat/user
+  // as the surrounding texts, no meta.source, button_callback tagged.
+  const tapMsg = (raw: string, ts: number): InboundMessage => ({
+    type: "inbound",
+    chatId: "c1",
+    messageId: ts,
+    user: "u",
+    userId: 42,
+    ts,
+    text: `[user tapped button: ${raw}]`,
+    meta: {
+      chat_id: "c1",
+      message_id: String(ts),
+      user: "u",
+      user_id: "42",
+      ts: String(ts),
+      button_callback: "true",
+      button_callback_data: raw,
+      button_text: "Approve",
+    },
+  });
+
+  it("a mid-turn tap buffered between user texts delivers individually", () => {
+    // Without the exclusion, the source-less tap merged with the adjacent
+    // texts and mergeRun kept only the anchor (last) message's meta —
+    // silently dropping button_callback_data/button_text whenever a text was
+    // last. The agent then saw the human-readable tap line without the
+    // machine-readable payload.
+    const plan = planBufferedRedelivery([
+      userMsg("first", 1),
+      tapMsg("approve_pr_547", 2),
+      userMsg("second", 3),
+    ]);
+    expect(plan.map((p) => p.merged.text)).toEqual([
+      "first",
+      "[user tapped button: approve_pr_547]",
+      "second",
+    ]);
+    // The tap keeps its full button meta intact.
+    const tap = plan[1]!.merged;
+    expect(tap.meta.button_callback).toBe("true");
+    expect(tap.meta.button_callback_data).toBe("approve_pr_547");
+    expect(tap.meta.button_text).toBe("Approve");
+  });
+
+  it("a tap followed by a user text does not merge (text-last would drop the payload)", () => {
+    const plan = planBufferedRedelivery([
+      tapMsg("hold", 1),
+      userMsg("also do the thing", 2),
+    ]);
+    expect(plan).toHaveLength(2);
+    expect(plan[0]!.merged.meta.button_callback_data).toBe("hold");
+  });
+
+  it("plain user texts still merge around the exclusion (no regression)", () => {
+    const plan = planBufferedRedelivery([userMsg("a", 1), userMsg("b", 2)]);
+    expect(plan).toHaveLength(1);
+    expect(plan[0]!.merged.text).toBe("a\nb");
+  });
+});

package/telegram-plugin/tests/gateway-boot-marker-clear.test.ts

@@ -43,7 +43,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // window to ~5KB so we don't pick up the unrelated
     // `removeTurnActiveMarker` call in the onTurnComplete handler
     // way down at the bottom of the file.
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 7000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
     const clearMatches = setupWindow.match(/removeTurnActiveMarker\s*\(\s*STATE_DIR\s*\)/g) ?? []
     expect(clearMatches.length).toBe(1)
   })
@@ -53,7 +53,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // must not prevent the gateway from coming up. Pin the try-wrapping
     // to make sure a future refactor doesn't drop it.
     const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 7000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
     expect(setupWindow).toMatch(/try\s*\{\s*removeTurnActiveMarker\(STATE_DIR\)\s*\}\s*catch/)
   })
 
@@ -62,7 +62,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // Clearing the marker first means the watchdog sees a clean slate
     // immediately, even if pin sweep takes 30s+ to finish.
     const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 7000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
     const clearIdx = setupWindow.indexOf('removeTurnActiveMarker(STATE_DIR)')
     const pinSweepIdx = setupWindow.indexOf('Boot-time pin sweep')
     expect(clearIdx).toBeGreaterThan(0)

package/telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts

@@ -36,6 +36,7 @@ import {
   clearCleanShutdownMarker,
   shouldSuppressRecoveryBanner,
   shouldSuppressBootResume,
+  parseBootResumeMode,
   resolveShutdownMarker,
   DEFAULT_MAX_AGE_MS,
   EXTERNAL_RESTART_FALLBACK_REASON,
@@ -350,77 +351,117 @@ describe("resolveShutdownMarker (SIGTERM-handler sequencing)", () => {
 // ---------------------------------------------------------------------------
 
 describe("shouldSuppressBootResume", () => {
-  // Core contract: clean shutdown (fresh marker) → suppress; crash (no marker
-  // or stale) → do not suppress; forceAlways override → never suppress.
+  // Product decision 2026-07 (supersedes #2585): the DEFAULT mode is
+  // 'in-flight' — a genuinely in-flight turn resumes even after a clean /
+  // deliberate restart, so a fresh clean marker NO LONGER suppresses by
+  // default. Suppression survives only as the opt-in 'never' mode.
+
+  it("DEFAULT (in-flight): fresh clean marker does NOT suppress — in-flight work resumes", () => {
+    // This is the core regression fix: a deliberate restart landing mid-turn
+    // must not silently drop the work.
+    const now = 1_700_000_000_000;
+    const marker: CleanShutdownMarker = { ts: now - 5_000, signal: "SIGTERM" };
+    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+    // Explicit 'in-flight' behaves identically to the default.
+    expect(shouldSuppressBootResume(marker, now, { mode: "in-flight" })).toBe(false);
+  });
 
-  it("returns false when no marker is present (crash/OOM — resume as before)", () => {
-    expect(shouldSuppressBootResume(null, Date.now())).toBe(false);
+  it("mode 'never': returns false when no marker is present (crash/OOM — resume)", () => {
+    expect(shouldSuppressBootResume(null, Date.now(), { mode: "never" })).toBe(false);
   });
 
-  it("returns true for a fresh clean-shutdown marker (operator/roll restart — suppress)", () => {
+  it("mode 'never': returns true for a fresh clean-shutdown marker (suppress)", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - 5_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(true);
   });
 
-  it("returns true at age=0 (marker written right before boot)", () => {
+  it("mode 'never': returns true at age=0 (marker written right before boot)", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(true);
   });
 
-  it("returns false when marker age equals maxAgeMs (boundary is exclusive)", () => {
+  it("mode 'never': false when marker age equals maxAgeMs (boundary is exclusive)", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - DEFAULT_MAX_AGE_MS, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(false);
   });
 
-  it("returns false for a stale marker (drain took >60s — treat as crash)", () => {
+  it("mode 'never': false for a stale marker (drain took >60s — slow rollout resumes)", () => {
+    // Preserves the ">60s already resumes" behaviour even under 'never'.
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - 90_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(false);
   });
 
-  it("treats clock skew (future ts) as stale to avoid false suppression", () => {
+  it("mode 'never': treats clock skew (future ts) as stale to avoid false suppression", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now + 10_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now)).toBe(false);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(false);
   });
 
-  it("respects a custom maxAgeMs", () => {
+  it("mode 'never': respects a custom maxAgeMs", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - 30_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now, { maxAgeMs: 60_000 })).toBe(true);
-    expect(shouldSuppressBootResume(marker, now, { maxAgeMs: 10_000 })).toBe(false);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never", maxAgeMs: 60_000 })).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never", maxAgeMs: 10_000 })).toBe(false);
   });
 
-  it("forceAlways=true disables suppression even for a fresh clean marker (escape hatch)", () => {
+  it("forceAlways=true disables suppression even under 'never' + fresh marker (escape hatch)", () => {
     // SWITCHROOM_BOOT_RESUME_ALWAYS=1 must restore unconditional resume.
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - 1_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now, { forceAlways: true })).toBe(false);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never", forceAlways: true })).toBe(false);
   });
 
-  it("forceAlways=false has no effect (default behaviour is the gate)", () => {
+  it("mode 'always': never suppresses, even with a fresh clean marker", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = { ts: now - 1_000, signal: "SIGTERM" };
-    expect(shouldSuppressBootResume(marker, now, { forceAlways: false })).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { mode: "always" })).toBe(false);
   });
 
-  it("works for SIGTERM and SIGINT (signal value is opaque)", () => {
+  it("mode 'never': works for SIGTERM and SIGINT (signal value is opaque)", () => {
     const now = 1_700_000_000_000;
-    expect(shouldSuppressBootResume({ ts: now, signal: "SIGTERM" }, now)).toBe(true);
-    expect(shouldSuppressBootResume({ ts: now, signal: "SIGINT" }, now)).toBe(true);
+    expect(shouldSuppressBootResume({ ts: now, signal: "SIGTERM" }, now, { mode: "never" })).toBe(true);
+    expect(shouldSuppressBootResume({ ts: now, signal: "SIGINT" }, now, { mode: "never" })).toBe(true);
   });
 
-  it("works with a marker that carries a reason field (rollout attribution is preserved)", () => {
+  it("mode 'never': works with a marker that carries a reason field", () => {
     const now = 1_700_000_000_000;
     const marker: CleanShutdownMarker = {
       ts: now - 2_000,
       signal: "SIGTERM",
       reason: "operator: switchroom update",
     };
-    expect(shouldSuppressBootResume(marker, now)).toBe(true);
+    expect(shouldSuppressBootResume(marker, now, { mode: "never" })).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Boot-resume mode parsing
+// ---------------------------------------------------------------------------
+
+describe("parseBootResumeMode", () => {
+  it("defaults to 'in-flight' for undefined/null/empty/unknown", () => {
+    expect(parseBootResumeMode(undefined)).toBe("in-flight");
+    expect(parseBootResumeMode(null)).toBe("in-flight");
+    expect(parseBootResumeMode("")).toBe("in-flight");
+    expect(parseBootResumeMode("bogus")).toBe("in-flight");
+  });
+
+  it("parses the three canonical values", () => {
+    expect(parseBootResumeMode("always")).toBe("always");
+    expect(parseBootResumeMode("in-flight")).toBe("in-flight");
+    expect(parseBootResumeMode("never")).toBe("never");
+  });
+
+  it("is case- and separator-insensitive", () => {
+    expect(parseBootResumeMode("ALWAYS")).toBe("always");
+    expect(parseBootResumeMode("In-Flight")).toBe("in-flight");
+    expect(parseBootResumeMode("in_flight")).toBe("in-flight");
+    expect(parseBootResumeMode("inflight")).toBe("in-flight");
+    expect(parseBootResumeMode("  never  ")).toBe("never");
   });
 });
 
@@ -446,9 +487,14 @@ describe("gateway.ts boot-resume clean-shutdown gate (source-level)", () => {
     expect(gatewaySource).toContain("readCleanShutdownMarker(bootResumeMarkerPath)");
   });
 
-  it("calls shouldSuppressBootResume with the marker, now, and forceAlways", () => {
+  it("calls shouldSuppressBootResume with the marker, now, forceAlways, and mode", () => {
     expect(gatewaySource).toContain("shouldSuppressBootResume(bootResumeCleanMarker, Date.now()");
     expect(gatewaySource).toContain("forceAlways: bootResumeForceAlways");
+    expect(gatewaySource).toContain("mode: bootResumeMode");
+  });
+
+  it("parses the boot-resume mode from SWITCHROOM_BOOT_RESUME", () => {
+    expect(gatewaySource).toContain("parseBootResumeMode(process.env.SWITCHROOM_BOOT_RESUME)");
   });
 
   it("provides the SWITCHROOM_BOOT_RESUME_ALWAYS escape hatch", () => {
@@ -459,6 +505,18 @@ describe("gateway.ts boot-resume clean-shutdown gate (source-level)", () => {
   it("logs a diagnostic when boot-resume is suppressed", () => {
     expect(gatewaySource).toContain("boot-resume suppressed (clean shutdown");
   });
+
+  it("still delivers a passive report (never silence) when resume is suppressed", () => {
+    // Requirement: silence is never acceptable when work was in flight.
+    // The suppressed path builds a deferred-report inbound, not nothing.
+    expect(gatewaySource).toContain("defer-suppressed");
+    expect(gatewaySource).toContain("buildResumeDeferredReportInbound");
+  });
+
+  it("caps the resume chain with a loop-guard (no unbounded resume-of-resume)", () => {
+    expect(gatewaySource).toContain("decideBootResumeKind");
+    expect(gatewaySource).toContain("defer-loop");
+  });
 });
 
 describe("gateway.ts shutdown-handler wiring (source-level)", () => {

package/telegram-plugin/tests/gateway-session-model-relaunch.test.ts

@@ -26,10 +26,12 @@ describe('gateway: scheduleModelRelaunch dep', () => {
     expect(win).toMatch(/writeFileSync\(\s*join\(agentDir, '\.session-model-override'\),\s*`\$\{model\}\\n`/)
   })
 
-  it('sets the in-memory activeSessionModelOverride before dispatching the restart', () => {
+  it('sets the in-memory session-model override before dispatching the restart', () => {
     const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
     const win = GATEWAY_SRC.slice(idx, idx + 900)
-    const setIdx = win.indexOf('activeSessionModelOverride = model')
+    // The override now lives on the freshness-aware sessionModelSource
+    // (session-model-source.ts) rather than a bare module-level variable.
+    const setIdx = win.indexOf('sessionModelSource.setOverride(model)')
     const restartIdx = win.indexOf('deps.scheduleRestart(reason)')
     expect(setIdx).toBeGreaterThan(0)
     expect(restartIdx).toBeGreaterThan(setIdx)

package/telegram-plugin/tests/ipc-server-query-pending-permission.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Issue #2971 — gateway-side handler for `query_pending_permission`, the
+ * read-only wedge-watchdog probe that lets the permission-prompt branch
+ * defer to a live Telegram approval card instead of racing it with Esc.
+ *
+ * Exercises the REAL createIpcServer over a real (tmp) unix socket with a
+ * raw `net.createConnection` client — the same transport the sidecar's
+ * `permission-pending-query.ts` module uses (no bridge/register handshake
+ * required; this message can be sent by ANY process inside the container,
+ * same trust model as `quota_wall_detected`).
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createConnection } from "node:net";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createIpcServer, type IpcServer, type IpcClient } from "../gateway/ipc-server.js";
+import { validateClientMessage } from "../gateway/ipc-server.js";
+import type { QueryPendingPermissionMessage } from "../gateway/ipc-protocol.js";
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ipc-qpp-test-"));
+  return join(dir, "test.sock");
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Send one query and collect every `pending_permission_status` reply line. */
+function queryOnce(socketPath: string, agentName: string, correlationId: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const sock = createConnection(socketPath);
+    let buffer = "";
+    sock.on("connect", () => {
+      sock.write(JSON.stringify({ type: "query_pending_permission", agentName, correlationId } as QueryPendingPermissionMessage) + "\n");
+    });
+    sock.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const idx = buffer.indexOf("\n");
+      if (idx >= 0) {
+        const line = buffer.slice(0, idx);
+        sock.end();
+        resolve(JSON.parse(line));
+      }
+    });
+    sock.on("error", reject);
+  });
+}
+
+describe("validateClientMessage — query_pending_permission (#2971)", () => {
+  it("accepts a well-formed query", () => {
+    expect(
+      validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "abc" }),
+    ).toBe(true);
+  });
+
+  it("rejects missing/malformed agentName", () => {
+    expect(validateClientMessage({ type: "query_pending_permission", correlationId: "abc" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "", correlationId: "abc" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "Bad Name", correlationId: "abc" })).toBe(false);
+  });
+
+  it("rejects missing/oversized correlationId", () => {
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "carrie" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "" })).toBe(false);
+    expect(
+      validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "x".repeat(65) }),
+    ).toBe(false);
+  });
+});
+
+describe("ipc-server — onQueryPendingPermission handler (#2971)", () => {
+  const servers: IpcServer[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) await s.close();
+    servers.length = 0;
+  });
+
+  it("fails CLOSED (pending:false) when no handler is wired — mixed-version-safe default", async () => {
+    const socketPath = tmpSocket();
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      // onQueryPendingPermission intentionally omitted.
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-1");
+    expect(reply).toEqual({ type: "pending_permission_status", correlationId: "corr-1", pending: false });
+  });
+
+  it("invokes the wired handler with the query, and relays its reply", async () => {
+    const socketPath = tmpSocket();
+    let received: QueryPendingPermissionMessage | null = null;
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      onQueryPendingPermission: (client: IpcClient, msg: QueryPendingPermissionMessage) => {
+        received = msg;
+        client.send({
+          type: "pending_permission_status",
+          correlationId: msg.correlationId,
+          pending: true,
+          requestId: "req-live-1",
+        });
+      },
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-2");
+    expect(received).toEqual({ type: "query_pending_permission", agentName: "carrie", correlationId: "corr-2" });
+    expect(reply).toEqual({
+      type: "pending_permission_status",
+      correlationId: "corr-2",
+      pending: true,
+      requestId: "req-live-1",
+    });
+  });
+
+  it("relays pending:false from a wired handler when nothing is live", async () => {
+    const socketPath = tmpSocket();
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      onQueryPendingPermission: (client: IpcClient, msg: QueryPendingPermissionMessage) => {
+        client.send({ type: "pending_permission_status", correlationId: msg.correlationId, pending: false });
+      },
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-3");
+    expect(reply).toEqual({ type: "pending_permission_status", correlationId: "corr-3", pending: false });
+  });
+});