switchroom 0.16.29 → 0.16.38

package/telegram-plugin/tests/permission-card-store.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { createPermissionCardStore } from '../gateway/permission-card-store.js'
+
+function makeTmpDir() {
+  return mkdtempSync(join(tmpdir(), 'perm-card-store-test-'))
+}
+
+describe('createPermissionCardStore', () => {
+  let dir: string
+
+  beforeEach(() => { dir = makeTmpDir() })
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }) })
+
+  it('starts empty', () => {
+    const store = createPermissionCardStore(dir)
+    expect(store.loadAll()).toEqual([])
+  })
+
+  it('add and loadAll returns the entry', () => {
+    const store = createPermissionCardStore(dir)
+    const entry = {
+      requestId: 'aabcd',
+      chatId: '12345',
+      messageId: 999,
+      startedAt: Date.now(),
+      toolName: 'mcp__shell__run',
+      cardText: 'Run shell command',
+    }
+    store.add(entry)
+    expect(store.loadAll()).toEqual([entry])
+  })
+
+  it('add multiple entries for same requestId (different messageIds)', () => {
+    const store = createPermissionCardStore(dir)
+    store.add({ requestId: 'aabcd', chatId: '111', messageId: 1, startedAt: 1000, toolName: 't', cardText: 'c' })
+    store.add({ requestId: 'aabcd', chatId: '222', messageId: 2, startedAt: 1000, toolName: 't', cardText: 'c' })
+    const all = store.loadAll()
+    expect(all.length).toBe(2)
+  })
+
+  it('does not duplicate same requestId+messageId', () => {
+    const store = createPermissionCardStore(dir)
+    const entry = { requestId: 'aabcd', chatId: '111', messageId: 1, startedAt: 1000, toolName: 't', cardText: 'c' }
+    store.add(entry)
+    store.add(entry)
+    expect(store.loadAll().length).toBe(1)
+  })
+
+  it('remove clears all entries for a requestId', () => {
+    const store = createPermissionCardStore(dir)
+    store.add({ requestId: 'aabcd', chatId: '111', messageId: 1, startedAt: 1000, toolName: 't', cardText: 'c' })
+    store.add({ requestId: 'aabcd', chatId: '222', messageId: 2, startedAt: 1000, toolName: 't', cardText: 'c' })
+    store.add({ requestId: 'xyzab', chatId: '333', messageId: 3, startedAt: 1000, toolName: 't', cardText: 'c' })
+    store.remove('aabcd')
+    const all = store.loadAll()
+    expect(all.length).toBe(1)
+    expect(all[0].requestId).toBe('xyzab')
+  })
+
+  it('remove is idempotent when entry not present', () => {
+    const store = createPermissionCardStore(dir)
+    expect(() => store.remove('nonexistent')).not.toThrow()
+  })
+
+  it('clear empties the store', () => {
+    const store = createPermissionCardStore(dir)
+    store.add({ requestId: 'aabcd', chatId: '111', messageId: 1, startedAt: 1000, toolName: 't', cardText: 'c' })
+    store.clear()
+    expect(store.loadAll()).toEqual([])
+  })
+
+  it('survives re-instantiation (data persists across instances)', () => {
+    createPermissionCardStore(dir).add({
+      requestId: 'aabcd', chatId: '111', messageId: 1, startedAt: 1000, toolName: 't', cardText: 'c',
+    })
+    const all = createPermissionCardStore(dir).loadAll()
+    expect(all.length).toBe(1)
+    expect(all[0].requestId).toBe('aabcd')
+  })
+})

package/telegram-plugin/tests/permission-timeout.test.ts

@@ -13,7 +13,9 @@ import {
   timeoutDenyMessage,
   duplicateDenyMessage,
   isRecentTimeoutDuplicate,
+  approvalTtlMs,
   PERMISSION_TTL_MS,
+  PERMISSION_TTL_DEFAULT_MS,
   HOSTD_PERMISSION_TTL_MS,
   ttlForTool,
   buildTimedOutCardEdits,
@@ -22,6 +24,35 @@ import {
   TIMED_OUT_FOOTER,
 } from '../gateway/permission-timeout.js'
 
+describe('approvalTtlMs (config-driven approval-card lifetime)', () => {
+  it('defaults to 60 minutes when unset', () => {
+    expect(approvalTtlMs({})).toBe(60 * 60_000)
+    expect(PERMISSION_TTL_DEFAULT_MS).toBe(60 * 60_000)
+  })
+
+  it('honours a configured value (threaded as SWITCHROOM_TG_APPROVAL_TIMEOUT_MS ms)', () => {
+    expect(approvalTtlMs({ SWITCHROOM_TG_APPROVAL_TIMEOUT_MS: '1800000' })).toBe(1_800_000)
+  })
+
+  it('falls back to the 60-min default on blank / garbage / non-positive', () => {
+    const d = 60 * 60_000
+    expect(approvalTtlMs({ SWITCHROOM_TG_APPROVAL_TIMEOUT_MS: '' })).toBe(d)
+    expect(approvalTtlMs({ SWITCHROOM_TG_APPROVAL_TIMEOUT_MS: 'abc' })).toBe(d)
+    expect(approvalTtlMs({ SWITCHROOM_TG_APPROVAL_TIMEOUT_MS: '0' })).toBe(d)
+    expect(approvalTtlMs({ SWITCHROOM_TG_APPROVAL_TIMEOUT_MS: '-5' })).toBe(d)
+  })
+
+  it('the default permission-card lifetime is at least 60 min', () => {
+    // With no env override at module load, PERMISSION_TTL_MS is the default.
+    expect(PERMISSION_TTL_MS).toBeGreaterThanOrEqual(60 * 60_000)
+  })
+
+  it('hostd verbs never get a shorter window than the default card', () => {
+    expect(HOSTD_PERMISSION_TTL_MS).toBeGreaterThanOrEqual(PERMISSION_TTL_MS)
+    expect(HOSTD_PERMISSION_TTL_MS).toBeGreaterThanOrEqual(30 * 60_000)
+  })
+})
+
 describe('permissionSignature', () => {
   it('is stable for the same tool + input', () => {
     expect(permissionSignature('mcp__meta_ads__set_budget', '{"id":"1","budget":1400}'))
@@ -96,7 +127,7 @@ describe('isRecentTimeoutDuplicate', () => {
 // ─── Bug 2 — per-tool TTL, timed-out card hygiene, stale-tap honesty ────────
 
 describe('ttlForTool (Bug 2 fix #2)', () => {
-  it('gives hostd gated verbs a 30-min window', () => {
+  it('gives hostd gated verbs at least a 30-min window (>= the default card)', () => {
     for (const tool of [
       'mcp__hostd__rollout',
       'mcp__hostd__update_apply',
@@ -105,20 +136,20 @@ describe('ttlForTool (Bug 2 fix #2)', () => {
       'mcp__hostd__config_propose_edit',
     ]) {
       expect(ttlForTool(tool)).toBe(HOSTD_PERMISSION_TTL_MS)
-      expect(ttlForTool(tool)).toBe(30 * 60_000)
+      expect(ttlForTool(tool)).toBeGreaterThanOrEqual(30 * 60_000)
     }
   })
 
-  it('keeps the 10-min default for non-hostd tools', () => {
+  it('applies the config-driven default (60 min) to non-hostd tools', () => {
     expect(ttlForTool('Bash')).toBe(PERMISSION_TTL_MS)
-    expect(ttlForTool('Bash')).toBe(10 * 60_000)
+    expect(ttlForTool('Bash')).toBe(60 * 60_000)
     expect(ttlForTool('mcp__perplexity__search')).toBe(PERMISSION_TTL_MS)
     expect(ttlForTool('mcp__agent-config__schedule_add')).toBe(PERMISSION_TTL_MS)
     expect(ttlForTool(undefined)).toBe(PERMISSION_TTL_MS)
   })
 
-  it('hostd TTL is strictly longer than the default', () => {
-    expect(HOSTD_PERMISSION_TTL_MS).toBeGreaterThan(PERMISSION_TTL_MS)
+  it('hostd TTL is never shorter than the default (the 60-min raise subsumes the old 30-min floor)', () => {
+    expect(HOSTD_PERMISSION_TTL_MS).toBeGreaterThanOrEqual(PERMISSION_TTL_MS)
   })
 })
 

package/telegram-plugin/tests/permission-verdict-resume-guard.test.ts

@@ -65,12 +65,31 @@ const dispatchCallsites = LINES.flatMap((line, i) =>
 const isSilentNoCardVerdict = (idx: number): boolean =>
   LINES.slice(Math.max(0, idx - 3), idx + 1).some((l) => /no-card-verdict/.test(l))
 
+// A CARD-FOLDED-RESUME path (the "Allow once" tap, card-ux fix 3) does NOT
+// post a separate `postPermissionResumeMessage()` — the agent-voiced "got it,
+// continuing: <work>" line is folded INTO the same card edit (below the ✅
+// label) via `finalizeCallback`, collapsing the old split second message. The
+// turn still resumes (`dispatchPermissionVerdict` + `resumeReactionAfterVerdict`
+// both fire) and the operator still sees the continuation — it just rides the
+// tapped card instead of fanning out to every card target. Such callsites carry
+// the `card-folded-resume` sentinel within the RESUME_WINDOW below the dispatch
+// and are exempt ONLY from the post-message pairing (still required to flip the
+// glyph). The invariant the guard protects (a verdict that un-parks a card must
+// visibly resume it) still holds — the resume is in the card body.
+const isCardFoldedResume = (idx: number): boolean =>
+  LINES.slice(idx, idx + POST_WINDOW + 1).some((l) => /card-folded-resume/.test(l))
+
 // How far below the dispatch the resume call is allowed to live. The
 // widest real gap today is ~9 lines (the slash-command path); 15 gives
 // refactor headroom without letting an unrelated resume "cover" a
 // dispatch from a different block.
 const RESUME_WINDOW = 15
 
+// postPermissionResumeMessage rides ~1–2 lines after resumeReactionAfterVerdict
+// on every path, so it can sit a touch further from the dispatch than the
+// resume call — give it a little more headroom.
+const POST_WINDOW = 20
+
 describe('permission verdict → resume reaction wiring', () => {
   it('there is at least one verdict-dispatch path to guard', () => {
     expect(dispatchCallsites.length).toBeGreaterThan(0)
@@ -102,15 +121,13 @@ describe('permission verdict → resume reaction wiring', () => {
     )
   })
 
-  // postPermissionResumeMessage rides ~1–2 lines after resumeReactionAfterVerdict
-  // on every path, so it can sit a touch further from the dispatch than the
-  // resume call — give it a little more headroom.
-  const POST_WINDOW = 20
-
-  it('every dispatchPermissionVerdict() callsite posts the agent-voiced resume message via postPermissionResumeMessage()', () => {
+  it('every dispatchPermissionVerdict() callsite posts the agent-voiced resume message via postPermissionResumeMessage() or folds it into the card', () => {
     const unpaired: number[] = []
     for (const idx of dispatchCallsites) {
       if (isSilentNoCardVerdict(idx)) continue
+      // Exempt: card-ux fix 3 folds the resume line into the card edit
+      // instead of a separate message (still visibly resumes the operator).
+      if (isCardFoldedResume(idx)) continue
       const window = LINES.slice(idx, idx + POST_WINDOW + 1).join('\n')
       if (!/\bpostPermissionResumeMessage\s*\(/.test(window)) {
         unpaired.push(idx + 1)

package/telegram-plugin/tests/quota-check.test.ts

@@ -92,11 +92,18 @@ describe('formatQuotaBlock', () => {
       now,
     )
     expect(block).toContain('**Claude plan quota**')
-    expect(block).toContain('**5h window**  29% · resets in 2h 30m')
-    expect(block).toContain('**7d window**  33% · resets in 3d')
+    expect(block).toContain('**5h window**  `29%` · `resets in 2h 30m`')
+    expect(block).toContain('**7d window**  `33%` · `resets in 3d`')
     expect(block).toContain('Binding window: five hour')
     // overage=allowed should not be surfaced
     expect(block).not.toContain('Overage:')
+    // Both windows: the **bold label** stays bold AND the percentage +
+    // reset ETA are each wrapped in a `code` span. Locks the nit-fix that
+    // the value moved into backticks without dropping the label markup.
+    const fiveLine = block.split('\n').find((l) => l.includes('5h window'))!
+    const sevenLine = block.split('\n').find((l) => l.includes('7d window'))!
+    expect(fiveLine).toMatch(/^\*\*5h window\*\*\s+`\d+%` · `resets in .+?`$/)
+    expect(sevenLine).toMatch(/^\*\*7d window\*\*\s+`\d+%` · `resets in .+?`$/)
   })
 
   it('surfaces overage status when not allowed', () => {

package/telegram-plugin/tests/quota-watch.test.ts

@@ -249,11 +249,11 @@ describe("evaluateQuotaWatchAccount — message content", () => {
     expect(d.message).toContain("30%");
   });
 
-  it("throttling message markdown-escapes the account label (#2669)", () => {
-    // The label is interpolated inside a code span — the renderer escapes
-    // inline-markdown specials (\ ` * _ ~ = [ ] |), not HTML entities. A label
-    // with an emphasis special (e.g. an underscore) is backslash-escaped; the
-    // literal `<` / `>` pass through (they are not markdown specials).
+  it("throttling message renders the account label literally in a code span (#2695)", () => {
+    // The label is interpolated INSIDE a `code span`, where content is literal
+    // and backslash escaping is WRONG (#2695 regression: escapeMarkdown here
+    // emitted a visible `ev\_il@…`). The correct rendering is via codeSpanSafe,
+    // so an underscore label appears verbatim with no stray backslash.
     const d = evaluateQuotaWatchAccount({
       agentName: "lawgpt",
       snap: makeSnap("ev_il@example.com", makeQuota(85, 40)),
@@ -262,8 +262,8 @@ describe("evaluateQuotaWatchAccount — message content", () => {
     });
     expect(d.kind).toBe("notify");
     if (d.kind !== "notify") return;
-    // The underscore is escaped so it can't open an italic run inside the span.
-    expect(d.message).toContain("ev\\_il@example.com");
+    expect(d.message).toContain("`ev_il@example.com`");
+    expect(d.message).not.toContain("ev\\_il@example.com");
   });
 
   it("throttling message for active account mentions /auth use", () => {

package/telegram-plugin/tests/rollout-status-wiring.test.ts

@@ -0,0 +1,81 @@
+/**
+ * #2726 — structural wiring guard for the rollout status IPC verbs. The
+ * gateway handlers live in the createIpcServer({...}) IIFE block, which can't
+ * be imported in a unit test (same constraint as the send_outbound /
+ * inject_inbound wiring tests), so the load-bearing invariants are pinned by
+ * reading the source:
+ *   1. ipc-server routes rollout_status_post → onRolloutStatusPost and
+ *      rollout_status_edit → onRolloutStatusEdit, with validator arms.
+ *   2. the POST handler fences agent (agentName === self), posts to the
+ *      OPERATOR chat (allowFrom[0]) as an ORDINARY message (no pin, no
+ *      inline_keyboard card), and replies with the message_id.
+ *   3. the EDIT handler edits in place via the wrapped retry path
+ *      (swallowingApiCall) — fire-and-forget, never a raw bot.api call.
+ *   4. NEITHER handler pins a message — this is in-chat narration, not the
+ *      retired pinned card (chat-is-the-single-source-of-truth).
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+
+const gw = readFileSync(new URL("../gateway/gateway.ts", import.meta.url), "utf8");
+const ipcServer = readFileSync(new URL("../gateway/ipc-server.ts", import.meta.url), "utf8");
+
+describe("rollout_status_* — ipc-server routing", () => {
+  it("validates + dispatches rollout_status_post", () => {
+    expect(ipcServer).toMatch(/case "rollout_status_post": \{/); // validator arm
+    expect(ipcServer).toMatch(/onRolloutStatusPost\(client, msg as RolloutStatusPostMessage\)/);
+  });
+  it("validates + dispatches rollout_status_edit", () => {
+    expect(ipcServer).toMatch(/case "rollout_status_edit": \{/);
+    expect(ipcServer).toMatch(/onRolloutStatusEdit\(client, msg as RolloutStatusEditMessage\)/);
+  });
+});
+
+describe("onRolloutStatusPost — gateway handler invariants", () => {
+  const start = gw.indexOf("async onRolloutStatusPost(client: IpcClient, msg: RolloutStatusPostMessage)");
+  const next = gw.indexOf("onRolloutStatusEdit(", start);
+  const handler = gw.slice(start, next > start ? next : start + 2600);
+
+  it("the handler exists", () => {
+    expect(start).toBeGreaterThan(0);
+  });
+  it("fences the agent (agentName must match this gateway's own)", () => {
+    expect(handler).toMatch(/msg\.agentName !== self/);
+  });
+  it("posts to the OPERATOR chat (allowFrom[0])", () => {
+    expect(handler).toMatch(/loadAccess\(\)\.allowFrom\[0\]/);
+  });
+  it("posts through the wrapped retry path, NOT a raw bot.api", () => {
+    expect(handler).toMatch(/robustApiCall\(/);
+    expect(handler).toMatch(/bot\.api\.sendRichMessage\(operator/);
+  });
+  it("replies with the message_id so hostd can EDIT it later", () => {
+    expect(handler).toMatch(/rollout_status_posted/);
+    expect(handler).toMatch(/messageId/);
+  });
+  it("does NOT pin the message and renders NO inline-keyboard card (narration, not the retired card)", () => {
+    expect(handler).not.toMatch(/pinChatMessage/);
+    expect(handler).not.toMatch(/reply_markup/);
+    expect(handler).not.toMatch(/InlineKeyboard/);
+  });
+});
+
+describe("onRolloutStatusEdit — gateway handler invariants", () => {
+  const start = gw.indexOf("onRolloutStatusEdit(_client: IpcClient, msg: RolloutStatusEditMessage)");
+  const next = gw.indexOf("onInjectInbound(", start);
+  const handler = gw.slice(start, next > start ? next : start + 2000);
+
+  it("the handler exists", () => {
+    expect(start).toBeGreaterThan(0);
+  });
+  it("fences the agent", () => {
+    expect(handler).toMatch(/msg\.agentName !== self/);
+  });
+  it("edits in place via the wrapped retry path (fire-and-forget)", () => {
+    expect(handler).toMatch(/swallowingApiCall\(/);
+    expect(handler).toMatch(/bot\.api\.editMessageText\(operator, msg\.messageId/);
+  });
+  it("does NOT pin (edits an ordinary message)", () => {
+    expect(handler).not.toMatch(/pinChatMessage/);
+  });
+});

package/telegram-plugin/tests/status-pin-boot-recovery.test.ts

@@ -0,0 +1,294 @@
+/**
+ * status-pin boot-recovery — the HEADLINE crash-recovery path, exercised against
+ * the REAL store + reconcile wrapper the gateway wires up (not just the pure
+ * decision fn). It reproduces the full sequence the gateway performs:
+ *
+ *   reconcile a pin → persist (persist-before-pin) → simulate a crash (SKIP the
+ *   clean SIGTERM sweep `unpinAllStatusPins`) → boot a "new gateway" (fresh
+ *   Maps, same on-disk store) → runStatusPinBootCleanup → assert the orphan pin
+ *   is unpinned AND the store is emptied.
+ *
+ * We cannot import gateway.ts directly (its module top-level runs the whole boot
+ * IIFE incl. the startup mutex + bot.start). Instead we model the gateway's
+ * status-pin subsystem faithfully with the SAME functions gateway.ts calls
+ * (reconcileAndPersistStatusPin, reconcilePin, runStatusPinBootCleanup) over an
+ * in-memory fs + a fake Telegram whose pin set we can inspect — so a regression
+ * in the ordering / cleanup contract reds here.
+ *
+ * Two variants:
+ *   (A) confirmed pin → crash before the clean sweep → recovered next boot.
+ *   (B) pending pin (crash INSIDE the persist-after-pin window, Fix 1) →
+ *       recovered next boot.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  loadStatusPins,
+  persistStatusPins,
+  reconcileAndPersistStatusPin,
+  runStatusPinBootCleanup,
+  type PersistedStatusPin,
+  type StatusPinStoreFsSeam,
+} from "../gateway/status-pin-store.js";
+import { reconcilePin } from "../status-pin-driver.js";
+import type { PinState, DesiredPin } from "../status-pin.js";
+import { decidePinAction } from "../status-pin.js";
+
+const PATH = "/state/agent/telegram/status-pins.json";
+
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed));
+  const fs: StatusPinStoreFsSeam = {
+    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),
+  };
+  return { fs, files };
+}
+
+/** A fake Telegram that records the current pinned message set per chat, so we
+ *  can assert an orphan is left pinned after a crash and unpinned after boot. */
+function fakeTelegram() {
+  const pinned = new Set<string>(); // `${chatId}:${messageId}`
+  return {
+    pinned,
+    api: {
+      pinChatMessage: async (chat_id: string | number, message_id: number) => {
+        pinned.add(`${chat_id}:${message_id}`);
+      },
+      unpinChatMessage: async (chat_id: string | number, message_id: number) => {
+        pinned.delete(`${chat_id}:${message_id}`);
+      },
+    },
+  };
+}
+
+/**
+ * A faithful stand-in for the gateway's status-pin subsystem — the SAME wiring
+ * as gateway.ts's `reconcileStatusPin` / `unpinAllStatusPins` / boot cleanup,
+ * with injectable fs + api so a single test can span a "crash" and a fresh boot.
+ */
+function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegram>) {
+  const statusPinState = new Map<string, PinState>();
+  const statusPinChatIds = new Map<string, string>();
+
+  const snapshotExcept = (exceptKey: string): PersistedStatusPin[] => {
+    const out: PersistedStatusPin[] = [];
+    for (const [pinKey, st] of statusPinState) {
+      if (pinKey === exceptKey) continue;
+      const chatId = statusPinChatIds.get(pinKey);
+      if (chatId == null) continue;
+      out.push({ pinKey, chatId, messageId: st.messageId });
+    }
+    return out;
+  };
+
+  async function reconcileStatusPin(pinKey: string, chatId: string, desired: DesiredPin) {
+    const prev = statusPinState.get(pinKey) ?? null;
+    const action = decidePinAction(prev, desired);
+    const op =
+      action.kind === "pin"
+        ? ({ kind: "pin", messageId: action.messageId } as const)
+        : ({ kind: "clear" } as const);
+    const next = await reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey,
+      chatId,
+      op,
+      snapshotOthers: () => snapshotExcept(pinKey),
+      applyPin: () =>
+        reconcilePin({ api: tg.api, chatId, prevState: prev, desired }),
+      log: () => {},
+    });
+    if (next == null) {
+      statusPinState.delete(pinKey);
+      statusPinChatIds.delete(pinKey);
+    } else {
+      statusPinState.set(pinKey, next);
+      statusPinChatIds.set(pinKey, chatId);
+    }
+  }
+
+  async function bootCleanup() {
+    return runStatusPinBootCleanup({
+      path: PATH,
+      fs,
+      unpin: (chatId, messageId) => tg.api.unpinChatMessage(chatId, messageId),
+      log: () => {},
+    });
+  }
+
+  return { statusPinState, reconcileStatusPin, bootCleanup };
+}
+
+describe("status-pin boot recovery (gateway wiring)", () => {
+  it("(A) confirmed pin → crash skips the clean sweep → next boot unpins the orphan + empties the store", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // ── Session 1: reconcile a pin. persist-before-pin runs; pin lands. ──
+    const gw1 = makeGateway(fs, tg);
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: true, messageId: 715 });
+
+    // Pin is live in Telegram and recorded on disk (confirmed).
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "fg:c:3", chatId: "-100123", messageId: 715 },
+    ]);
+
+    // ── CRASH: we deliberately DO NOT run the clean SIGTERM sweep
+    //    (unpinAllStatusPins). The pin stays live; gw1's Maps vanish. ──
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+
+    // ── Session 2: brand-new gateway, empty Maps, SAME on-disk store. ──
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has("-100123:715")).toBe(false); // orphan unpinned
+    expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
+  });
+
+  it("(B) pending pin (crash inside the persist-after-pin window) → recovered next boot", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // Simulate the exact Fix-1 crash window: the pin API lands, then the
+    // process is SIGKILLed before the confirming rewrite. We model that by
+    // reconcileAndPersistStatusPin whose applyPin pins then throws.
+    await expect(
+      reconcileAndPersistStatusPin({
+        path: PATH,
+        fs,
+        pinKey: "fg:c:3",
+        chatId: "-100123",
+        op: { kind: "pin", messageId: 715 },
+        snapshotOthers: () => [],
+        applyPin: async () => {
+          await tg.api.pinChatMessage("-100123", 715); // pin lands in Telegram
+          throw new Error("SIGKILL before confirm rewrite");
+        },
+        log: () => {},
+      }),
+    ).rejects.toThrow("SIGKILL");
+
+    // Orphan is live in Telegram; a PENDING record is on disk.
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "fg:c:3", chatId: "-100123", messageId: 715, pending: true },
+    ]);
+
+    // Fresh boot recovers it from the pending record.
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has("-100123:715")).toBe(false);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+  });
+
+  it("clean shutdown (sweep DID run) leaves nothing for boot cleanup to do", async () => {
+    // Contrast: when the SIGTERM sweep runs (unpin each key), the store is
+    // emptied and the pin removed — boot cleanup is a no-op. This guards the
+    // ordering the other way: normal shutdown must NOT rely on boot cleanup.
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+    const gw1 = makeGateway(fs, tg);
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: true, messageId: 715 });
+    // Clean sweep: unpin the key.
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: false });
+    expect(tg.pinned.size).toBe(0);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+
+    const gw2 = makeGateway(fs, tg);
+    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, total: 0 });
+  });
+});
+
+/**
+ * Mutex-gating (P2). The boot cleanup issues real unpins against a SHARED
+ * per-agent store, so a LOSING double-boot must NOT run it — else it would strip
+ * a still-alive sibling gateway's legitimate pins. gateway.ts gates the call
+ * inside the won-lock branch (only the boot that wins acquireStartupLock calls
+ * statusPinBootCleanup; the loser process.exit(1)s first).
+ *
+ * A full held-lock integration test is impractical (gateway.ts's boot IIFE runs
+ * the mutex + bot.start at import). So we assert STRUCTURALLY that the cleanup
+ * call sits inside the won-lock branch and never at the top-level import scope,
+ * and that the loser (blocked) branch exits before it.
+ */
+describe("status-pin boot cleanup is mutex-gated (structural)", () => {
+  const gatewaySrc = readFileSync(
+    fileURLToPath(new URL("../gateway/gateway.ts", import.meta.url)),
+    "utf8",
+  );
+
+  it("does NOT invoke statusPinBootCleanup at module import scope", () => {
+    // The invocation must be gated on winning the mutex, never fired eagerly at
+    // import. A bare top-level `statusPinBootCleanup()` (not inside the lock
+    // block) would let a losing double-boot strip a live sibling's pins.
+    // The definition + the deliberate DO-NOT-invoke note are allowed; assert
+    // there is a note explaining the gating, and that every actual call is
+    // preceded (in source order) by the acquireStartupLock outcome check.
+    expect(gatewaySrc).toContain("acquireStartupLock");
+    // The comment documenting WHY it isn't invoked at import time.
+    expect(gatewaySrc).toMatch(
+      /NOT invoked here at import time|gated on winning the startup mutex/,
+    );
+  });
+
+  it("every statusPinBootCleanup() call site follows the won-lock check", () => {
+    // Find each *invocation* (with parens), excluding the declaration.
+    const lines = gatewaySrc.split("\n");
+    const lockIdx = lines.findIndex((l) => l.includes("acquireStartupLock({"));
+    expect(lockIdx).toBeGreaterThan(-1);
+
+    const declIdx = lines.findIndex((l) =>
+      /async function statusPinBootCleanup/.test(l),
+    );
+    expect(declIdx).toBeGreaterThan(-1);
+
+    const callIdxs = lines
+      .map((l, i) => ({ l, i }))
+      .filter(
+        ({ l, i }) =>
+          i !== declIdx &&
+          /statusPinBootCleanup\(\)/.test(l) &&
+          !l.trimStart().startsWith("//") &&
+          !l.includes("statusPinBootCleanup() is deliberately NOT"),
+      )
+      .map(({ i }) => i);
+
+    // There must be at least one real call, and every real call must come
+    // AFTER the acquireStartupLock outcome is available (i.e. inside the boot
+    // block that only the winner reaches).
+    expect(callIdxs.length).toBeGreaterThan(0);
+    for (const idx of callIdxs) {
+      expect(idx).toBeGreaterThan(lockIdx);
+    }
+  });
+
+  it("the blocked (losing) boot exits before reaching cleanup", () => {
+    // In the mutex block, `outcome.status === 'blocked'` must lead to
+    // process.exit(1) BEFORE any statusPinBootCleanup() call in that block —
+    // so a loser never touches the shared store.
+    const blockedIdx = gatewaySrc.indexOf("outcome.status === 'blocked'");
+    expect(blockedIdx).toBeGreaterThan(-1);
+    const afterBlocked = gatewaySrc.slice(blockedIdx);
+    const exitIdx = afterBlocked.indexOf("process.exit(1)");
+    const cleanupIdx = afterBlocked.indexOf("void statusPinBootCleanup()");
+    expect(exitIdx).toBeGreaterThan(-1);
+    expect(cleanupIdx).toBeGreaterThan(-1);
+    // The exit for the blocked branch appears before the winner's cleanup call.
+    expect(exitIdx).toBeLessThan(cleanupIdx);
+  });
+});