switchroom 0.18.7 → 0.18.9

package/telegram-plugin/tests/render/render-outbound-chunks.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Regression tests for the chunk-boundary cap bug (fix/rich-render-chunk-boundary-cap).
+ *
+ * THE BUG: the outbound safe renderer (`renderSafe`) re-escapes GFM-special
+ * characters, which GROWS a body. A raw chunk sized just under the wire cap can
+ * escape PAST it. `renderSafe`'s only oversize recourse is to degrade the WHOLE
+ * document to `mode:"plain"` (raw source, no rich wrapper) — it never re-splits
+ * a multi-block body. The send path then ships that plain body through the
+ * 4096-char plain `sendMessage` endpoint, so a ~32k plain body is rejected by
+ * Telegram (`message is too long`) and the answer is dropped.
+ *
+ * `renderOutboundChunks` closes the gap: every returned piece fits its own wire
+ * cap (rich `<= maxLen`, plain `<= plainMax`) and is cut only at
+ * `splitMarkdownChunks`' safe boundaries (never bisecting a fence / table row).
+ */
+import { describe, it, expect } from "vitest";
+import { renderOutboundChunks, PLAIN_TEXT_MAX_CHARS } from "../../render/rich-render.js";
+import { RICH_MESSAGE_MAX_CHARS } from "../../format.js";
+
+const ON = { SWITCHROOM_RICH_RENDER: "1" } as NodeJS.ProcessEnv;
+const OFF = {} as NodeJS.ProcessEnv;
+
+/** Count fenced-code delimiter lines (```) in a body. A piece that bisects a
+ *  fenced block has an ODD count. */
+function fenceCount(s: string): number {
+  return (s.match(/^```/gm) ?? []).length;
+}
+
+describe("renderOutboundChunks", () => {
+  it("flag OFF is a single passthrough piece (byte-for-byte)", () => {
+    const raw = "**bold** and _italic_ | a | table |";
+    const pieces = renderOutboundChunks(raw, OFF);
+    expect(pieces).toHaveLength(1);
+    expect(pieces[0].text).toBe(raw);
+    expect(pieces[0].mode).toBe("markdown");
+  });
+
+  it("flag ON, body that fits is a single piece (common case)", () => {
+    const pieces = renderOutboundChunks("just some plain prose", ON);
+    expect(pieces).toHaveLength(1);
+    expect(pieces[0].text.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS);
+  });
+
+  it("REGRESSION: a near-cap escapable body splits into cap-respecting pieces", () => {
+    // Prose whose escaping (`_ * |` each gain a leading `\`) grows it past the
+    // cap. Use small caps so the test is fast; the invariant is cap-agnostic.
+    const maxLen = 200;
+    const plainMax = 80;
+    const unit = "a_b*c|d ";
+    const raw = unit.repeat(40); // 320 raw chars, ~1.5x after escaping
+    const pieces = renderOutboundChunks(raw, ON, maxLen, plainMax);
+
+    // The whole body did NOT fit as one message — it was re-split.
+    expect(pieces.length).toBeGreaterThan(1);
+    for (const p of pieces) {
+      if (p.mode === "plain") {
+        // A plain piece rides the plain `sendMessage` endpoint — must fit its cap.
+        expect(p.text.length).toBeLessThanOrEqual(plainMax);
+      } else {
+        expect(p.text.length).toBeLessThanOrEqual(maxLen);
+      }
+    }
+  });
+
+  it("REGRESSION: never bisects a fenced code block when splitting", () => {
+    const maxLen = 300;
+    const plainMax = 250; // >= the fence size, so a fence never needs a hard slice.
+    // A fenced block big enough that a naive length cut would land inside it,
+    // wrapped in prose so the whole document overflows and must be re-split.
+    const fence = "```\n" + "code line here\n".repeat(8) + "```";
+    const prose = "word ".repeat(40);
+    const raw = `${prose}\n\n${fence}\n\n${prose}`;
+    const pieces = renderOutboundChunks(raw, ON, maxLen, plainMax);
+
+    expect(pieces.length).toBeGreaterThan(1);
+    for (const p of pieces) {
+      // Every emitted piece has BALANCED fence delimiters — no piece opens a
+      // fence it doesn't close (which would swallow the next piece's text).
+      expect(fenceCount(p.text) % 2).toBe(0);
+      const cap = p.mode === "plain" ? plainMax : maxLen;
+      expect(p.text.length).toBeLessThanOrEqual(cap);
+    }
+  });
+
+  it("REAL-CAP: a ~32k escapable body never yields an over-4096 plain piece", () => {
+    // The production failure: raw just under RICH_MESSAGE_MAX_CHARS, escaping
+    // pushes the rendered form over it. On the buggy path this became ONE
+    // ~32k plain body sent through the 4096 plain endpoint. Here every plain
+    // piece is <= 4096 and every rich piece <= 32768.
+    const unit = "a_b*c|d ";
+    const raw = unit.repeat(Math.floor((RICH_MESSAGE_MAX_CHARS - 20) / unit.length));
+    const pieces = renderOutboundChunks(raw, ON);
+    for (const p of pieces) {
+      const cap = p.mode === "plain" ? PLAIN_TEXT_MAX_CHARS : RICH_MESSAGE_MAX_CHARS;
+      expect(p.text.length).toBeLessThanOrEqual(cap);
+    }
+  }, 30000);
+});

package/telegram-plugin/tests/retry-api-call.test.ts

@@ -15,6 +15,8 @@ import {
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
   isHtmlParseRejectError,
+  isLocalResourceError,
+  LOCAL_RESOURCE_EXHAUSTED,
   type RetryObserver,
 } from '../retry-api-call.js'
 import { errors, makeGrammyError } from './fake-bot-api.js'
@@ -512,3 +514,60 @@ describe('isHtmlParseRejectError', () => {
     ).toBe(true)
   })
 })
+
+describe('#2923 — LOCAL resource exhaustion is NOT retried (avoids flood ban)', () => {
+  it('classifies ENOSPC / EDQUOT / EIO / ENOMEM by errno code', () => {
+    expect(isLocalResourceError(Object.assign(new Error('x'), { code: 'ENOSPC' }))).toBe(true)
+    expect(isLocalResourceError(Object.assign(new Error('x'), { code: 'EDQUOT' }))).toBe(true)
+    expect(isLocalResourceError(Object.assign(new Error('x'), { code: 'EIO' }))).toBe(true)
+    expect(isLocalResourceError(Object.assign(new Error('x'), { code: 'ENOMEM' }))).toBe(true)
+  })
+
+  it('classifies by message when no code is present (incl. EIO, word-boundaried)', () => {
+    expect(isLocalResourceError(new Error('ENOSPC: no space left on device, write'))).toBe(true)
+    expect(isLocalResourceError(new Error('disk quota exceeded'))).toBe(true)
+    expect(isLocalResourceError(new Error('EIO: i/o error, write'))).toBe(true)
+    // No false match on a substring (e.g. a word containing the letters).
+    expect(isLocalResourceError(new Error('DENOSPCX not a real code'))).toBe(false)
+  })
+
+  it('does NOT classify a remote GrammyError or ordinary error', () => {
+    expect(isLocalResourceError(errors.floodWait(10))).toBe(false)
+    expect(isLocalResourceError(new Error('fetch failed'))).toBe(false)
+  })
+
+  it('throws LOCAL_RESOURCE_EXHAUSTED immediately without retrying', async () => {
+    // Before the fix: an ENOSPC thrown by the send-staging step fell through
+    // to the network-retry branch pattern OR was rethrown but only after the
+    // caller kept re-driving sends — the storm that tripped the flood ban.
+    // Now it must fail FAST on the first attempt with a distinct marker.
+    const sleep = vi.fn(async () => {})
+    let calls = 0
+    const retry = createRetryApiCall({ maxRetries: 3, sleep })
+    await expect(
+      retry(async () => {
+        calls++
+        throw Object.assign(new Error('ENOSPC: no space left on device'), { code: 'ENOSPC' })
+      }),
+    ).rejects.toThrow(LOCAL_RESOURCE_EXHAUSTED)
+    expect(calls).toBe(1) // no retry
+    expect(sleep).not.toHaveBeenCalled() // no backoff-into-flood
+  })
+
+  it('fires onFloodWait with the retry_after when a 429 is seen', async () => {
+    const seen: number[] = []
+    const sleep = vi.fn(async () => {})
+    let n = 0
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep,
+      onFloodWait: (s) => seen.push(s),
+    })
+    const out = await retry(async () => {
+      if (n++ === 0) throw errors.floodWait(42)
+      return 'ok'
+    })
+    expect(out).toBe('ok')
+    expect(seen).toEqual([42])
+  })
+})

package/telegram-plugin/tests/run-hook-wrapper.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * #2555 — run-hook.sh must tolerate a Node exit-134 (uv_thread_create abort
+ * under memory pressure): retry once, and if it still aborts, skip cleanly
+ * (exit 0) rather than propagating 134. Real non-134 statuses pass through.
+ *
+ * We drive the wrapper with a fake command (a tiny sh script) whose exit code
+ * is scripted via a counter file, so we exercise the exact control flow
+ * without needing a real memory-pressured Node.
+ */
+const wrapper = resolve(
+  fileURLToPath(new URL('../hooks/run-hook.sh', import.meta.url)),
+)
+
+describe('#2555 run-hook.sh exit-134 tolerance', () => {
+  let dir: string
+  let fake: string
+  let counter: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'run-hook-'))
+    fake = join(dir, 'fake.sh')
+    counter = join(dir, 'n')
+    writeFileSync(counter, '0')
+  })
+  afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+  /** Fake command: exits `codes[attemptIndex]`, records each invocation. */
+  function writeFake(codes: number[]): void {
+    writeFileSync(
+      fake,
+      [
+        '#!/bin/sh',
+        `n=$(cat "${counter}")`,
+        `echo "$((n + 1))" > "${counter}"`,
+        'case "$n" in',
+        ...codes.map((c, i) => `  ${i}) exit ${c} ;;`),
+        `  *) exit ${codes[codes.length - 1]} ;;`,
+        'esac',
+      ].join('\n'),
+    )
+  }
+
+  const run = (input = '') =>
+    spawnSync('sh', [wrapper, 'sh', fake], { encoding: 'utf-8', input })
+
+  const attempts = () => Number(readFileSync(counter, 'utf-8').trim())
+
+  it('passes a clean exit 0 through without retrying', () => {
+    writeFake([0])
+    const r = run()
+    expect(r.status).toBe(0)
+    expect(attempts()).toBe(1)
+  })
+
+  it('passes a real non-134 failure through unchanged (no retry, not masked)', () => {
+    writeFake([2])
+    const r = run()
+    expect(r.status).toBe(2)
+    expect(attempts()).toBe(1)
+  })
+
+  it('retries ONCE on a 134 abort and succeeds on the second attempt', () => {
+    writeFake([134, 0])
+    const r = run()
+    expect(r.status).toBe(0)
+    expect(attempts()).toBe(2)
+  })
+
+  it('skips cleanly (exit 0) when it aborts 134 twice — no crash card', () => {
+    writeFake([134, 134])
+    const r = run()
+    expect(r.status).toBe(0) // skipped cleanly, NOT 134
+    expect(attempts()).toBe(2)
+    expect(r.stderr).toMatch(/skipping hook cleanly/)
+  })
+
+  it('exports a shrunk UV_THREADPOOL_SIZE to the child', () => {
+    writeFileSync(fake, `#!/bin/sh\necho "$UV_THREADPOOL_SIZE"\nexit 0\n`)
+    const r = run()
+    expect(r.stdout.trim()).toBe('1')
+  })
+
+  it('replays the SAME stdin payload on the retry (scanner never sees empty input)', () => {
+    // Fake: attempt 0 reads stdin then aborts 134; attempt 1 reads stdin and
+    // records it, then exits 0. If stdin were not preserved, the recorded
+    // payload on the retry would be empty.
+    const seen = join(dir, 'seen-stdin')
+    writeFileSync(
+      fake,
+      [
+        '#!/bin/sh',
+        `n=$(cat "${counter}")`,
+        `echo "$((n + 1))" > "${counter}"`,
+        'data=$(cat)', // drain stdin (the abort-after-read scenario)
+        `echo "$data" > "${seen}.$n"`,
+        '[ "$n" = "0" ] && exit 134',
+        'exit 0',
+      ].join('\n'),
+    )
+    const r = run('SECRET-PAYLOAD-123')
+    expect(r.status).toBe(0)
+    expect(attempts()).toBe(2)
+    // The RETRY (attempt 1) must have received the full payload, not empty.
+    expect(readFileSync(`${seen}.1`, 'utf-8').trim()).toBe('SECRET-PAYLOAD-123')
+  })
+
+  it('FAILS CLOSED (propagates 134) for a security hook that aborts twice', () => {
+    // A genuinely broken secret scanner must NOT silently pass — exit 0 after
+    // two aborts would be a silent security bypass.
+    const secFake = join(dir, 'secret-guard-pretool.mjs')
+    writeFileSync(
+      secFake,
+      [
+        '#!/bin/sh',
+        `n=$(cat "${counter}")`,
+        `echo "$((n + 1))" > "${counter}"`,
+        'exit 134',
+      ].join('\n'),
+    )
+    const r = spawnSync('sh', [wrapper, 'sh', secFake], { encoding: 'utf-8', input: '{}' })
+    expect(r.status).toBe(134) // fail closed — NOT skipped
+    expect(attempts()).toBe(2)
+    expect(r.stderr).toMatch(/FAILING CLOSED/)
+  })
+})

package/telegram-plugin/tests/session-model-file.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Durable session-model file helpers (session-model-file.ts) — the gateway
+ * side of the stickiness contract (reference/rfcs/session-model-stickiness.md).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import {
+  serializeSessionModel,
+  parseSessionModel,
+  writeSessionModelFile,
+  readSessionModelFile,
+  readSessionModelFileRaw,
+  restoreSessionModelFileRaw,
+  clearSessionModelFile,
+  writeRelaunchModelIntent,
+  clearRelaunchModelIntent,
+  readConfiguredDefaultModel,
+  intentForRestartReason,
+  SESSION_MODEL_FILE,
+  RELAUNCH_MODEL_INTENT_FILE,
+  CONFIGURED_DEFAULT_MODEL_FILE,
+} from '../gateway/session-model-file.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'switchroom-sm-file-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+describe('serialize/parse round-trip', () => {
+  it('round-trips a record', () => {
+    const rec = { model: 'sr-glm-5', configuredDefaultAtWrite: 'claude-sonnet-5', ts: 1783948123456 }
+    expect(parseSessionModel(serializeSessionModel(rec))).toEqual(rec)
+  })
+
+  it('rejects corrupt JSON, missing fields, and non-canonical model tokens', () => {
+    expect(parseSessionModel('{broken')).toBeNull()
+    expect(parseSessionModel('{"model":"opus"}')).toBeNull()
+    expect(parseSessionModel('{"model":"Opus 4.8","configuredDefaultAtWrite":"x","ts":1}')).toBeNull()
+    expect(parseSessionModel('{"model":42,"configuredDefaultAtWrite":"x","ts":1}')).toBeNull()
+  })
+})
+
+describe('writeSessionModelFile — canonical-token guard (review finding 7)', () => {
+  it('writes a canonical token with the current default + a fresh ts', () => {
+    writeSessionModelFile(dir, 'claude-opus-4-8', 'claude-sonnet-5')
+    const rec = readSessionModelFile(dir)!
+    expect(rec.model).toBe('claude-opus-4-8')
+    expect(rec.configuredDefaultAtWrite).toBe('claude-sonnet-5')
+    expect(Math.abs(Date.now() - rec.ts)).toBeLessThan(5000)
+  })
+
+  it('THROWS on a display label — "Opus 4.5" must never be persisted', () => {
+    expect(() => writeSessionModelFile(dir, 'Opus 4.5', 'claude-sonnet-5')).toThrow(/non-canonical/)
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+  })
+})
+
+describe('rollback snapshot (scheduleModelRelaunch dispatch failure)', () => {
+  it('restores prior content when a file existed', () => {
+    writeSessionModelFile(dir, 'claude-opus-4-8', 'claude-sonnet-5')
+    const snapshot = readSessionModelFileRaw(dir)
+    writeSessionModelFile(dir, 'sr-glm-5', 'claude-sonnet-5')
+    restoreSessionModelFileRaw(dir, snapshot)
+    expect(readSessionModelFile(dir)!.model).toBe('claude-opus-4-8')
+  })
+
+  it('deletes the file when there was none before', () => {
+    const snapshot = readSessionModelFileRaw(dir) // null
+    writeSessionModelFile(dir, 'sr-glm-5', 'claude-sonnet-5')
+    restoreSessionModelFileRaw(dir, snapshot)
+    expect(existsSync(join(dir, SESSION_MODEL_FILE))).toBe(false)
+  })
+})
+
+describe('relaunch intent', () => {
+  it('writes one-line JSON with intent, reason, and embedded ts (the freshness clock)', () => {
+    writeRelaunchModelIntent(dir, 'keep', 'user: /new from chat')
+    const raw = readFileSync(join(dir, RELAUNCH_MODEL_INTENT_FILE), 'utf8')
+    const parsed = JSON.parse(raw)
+    expect(parsed.intent).toBe('keep')
+    expect(parsed.reason).toBe('user: /new from chat')
+    expect(Math.abs(Date.now() - parsed.ts)).toBeLessThan(5000)
+  })
+
+  it('last-writer-wins and clearable', () => {
+    writeRelaunchModelIntent(dir, 'keep', 'a')
+    writeRelaunchModelIntent(dir, 'revert', 'b')
+    expect(JSON.parse(readFileSync(join(dir, RELAUNCH_MODEL_INTENT_FILE), 'utf8')).intent).toBe('revert')
+    clearRelaunchModelIntent(dir)
+    expect(existsSync(join(dir, RELAUNCH_MODEL_INTENT_FILE))).toBe(false)
+  })
+})
+
+describe('intentForRestartReason — the triggerSelfRestart per-reason table (RFC §3)', () => {
+  it.each([
+    'schedule-restart-immediate',
+    'restart-drain-cap-forced',
+    'turn-complete-pending-restart',
+    'fleet-fallback-resume',
+    'sr-to-claude-model-switch',
+  ])('switchroom-managed relaunch %s → keep', (reason) => {
+    expect(intentForRestartReason(reason)).toBe('keep')
+  })
+
+  it('inline-button-restart (operator-deliberate) → revert', () => {
+    expect(intentForRestartReason('inline-button-restart')).toBe('revert')
+  })
+
+  it('unknown gateway reasons default to keep (only gateway code calls triggerSelfRestart; crashes never do)', () => {
+    expect(intentForRestartReason('some-future-recovery-path')).toBe('keep')
+  })
+})
+
+describe('readConfiguredDefaultModel', () => {
+  it('reads the trimmed value; null when absent or empty', () => {
+    expect(readConfiguredDefaultModel(dir)).toBeNull()
+    writeFileSync(join(dir, CONFIGURED_DEFAULT_MODEL_FILE), 'claude-sonnet-5\n')
+    expect(readConfiguredDefaultModel(dir)).toBe('claude-sonnet-5')
+    writeFileSync(join(dir, CONFIGURED_DEFAULT_MODEL_FILE), '\n')
+    expect(readConfiguredDefaultModel(dir)).toBeNull()
+  })
+
+  it('clearSessionModelFile is a safe no-op when absent', () => {
+    expect(() => clearSessionModelFile(dir)).not.toThrow()
+  })
+})

package/telegram-plugin/tests/slot-banner-boot-recovery.test.ts

@@ -170,7 +170,7 @@ describe("slot-banner boot recovery (gateway wiring)", () => {
     const gw2 = makeGateway(fs, tg);
     const res = await gw2.bootCleanup();
 
-    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has(`${OWNER}:${msgId}`)).toBe(false); // orphan unpinned
     expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
   });
@@ -220,7 +220,7 @@ describe("slot-banner boot recovery (gateway wiring)", () => {
     // 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(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has(`${OWNER}:${rec[0].messageId}`)).toBe(false);
     expect(loadStatusPins(PATH, fs)).toEqual([]);
   });
@@ -241,6 +241,6 @@ describe("slot-banner boot recovery (gateway wiring)", () => {
     expect(loadStatusPins(PATH, fs)).toEqual([]);
 
     const gw2 = makeGateway(fs, tg);
-    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, total: 0 });
+    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, retained: 0, kept: 0, total: 0 });
   });
 });

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

@@ -141,7 +141,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     const gw2 = makeGateway(fs, tg);
     const res = await gw2.bootCleanup();
 
-    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has("-100123:715")).toBe(false); // orphan unpinned
     expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
   });
@@ -177,7 +177,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     // 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(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has("-100123:715")).toBe(false);
     expect(loadStatusPins(PATH, fs)).toEqual([]);
   });
@@ -196,7 +196,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     expect(loadStatusPins(PATH, fs)).toEqual([]);
 
     const gw2 = makeGateway(fs, tg);
-    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, total: 0 });
+    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, retained: 0, kept: 0, total: 0 });
   });
 });
 

package/telegram-plugin/tests/status-pin-store.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
 import {
+  BOOT_UNPIN_MAX_ATTEMPTS,
   loadStatusPins,
   mutateStatusPinRow,
   persistStatusPins,
@@ -195,12 +196,12 @@ describe("runStatusPinBootCleanup", () => {
       ["-100123", 715],
       ["-100999", 42],
     ]);
-    expect(res).toEqual({ cleared: 2, total: 2 });
+    expect(res).toEqual({ cleared: 2, retained: 0, kept: 0, total: 2 });
     // Store empty afterwards → no re-attempt next boot.
     expect(loadStatusPins(PATH, fs)).toEqual([]);
   });
 
-  it("a failing unpin is non-fatal and the store is still emptied", async () => {
+  it("retry-safe (#3001): a failing unpin is non-fatal, RETAINS the row with an attempt counter, and drops only the succeeded one", async () => {
     const { fs } = memFs();
     persistStatusPins(PATH, fs, [
       pin({ pinKey: "fg:c:1", chatId: "-100123", messageId: 5 }),
@@ -216,11 +217,66 @@ describe("runStatusPinBootCleanup", () => {
       log: () => {},
     });
 
-    // One failed, one succeeded — still non-fatal, store still emptied.
-    expect(res).toEqual({ cleared: 1, total: 2 });
+    // One failed, one succeeded — the failure is retained for a next-boot
+    // retry instead of forfeiting the orphan (the pre-#3001 behaviour).
+    expect(res).toEqual({ cleared: 1, retained: 1, kept: 0, total: 2 });
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "fg:c:1", chatId: "-100123", messageId: 5, attempts: 1 },
+    ]);
+  });
+
+  it("retry-safe (#3001): a row is forfeited once its attempts reach BOOT_UNPIN_MAX_ATTEMPTS", async () => {
+    const { fs } = memFs();
+    persistStatusPins(PATH, fs, [
+      pin({
+        pinKey: "fg:c:1",
+        chatId: "-100123",
+        messageId: 5,
+        attempts: BOOT_UNPIN_MAX_ATTEMPTS - 1,
+      }),
+    ]);
+    const res = await runStatusPinBootCleanup({
+      path: PATH,
+      fs,
+      unpin: async () => {
+        throw new Error("chat gone forever");
+      },
+      log: () => {},
+    });
+    // Final attempt failed too — forfeited, not retained: a permanently-
+    // undeliverable unpin must not re-fail on every future boot.
+    expect(res).toEqual({ cleared: 0, retained: 0, kept: 0, total: 1 });
     expect(loadStatusPins(PATH, fs)).toEqual([]);
   });
 
+  it("tool pins (#3001): an UNEXPIRED `tool:` row survives the boot untouched; an EXPIRED one is unpinned and dropped", async () => {
+    const { fs } = memFs();
+    const now = 1_750_000_000_000;
+    persistStatusPins(PATH, fs, [
+      pin({ pinKey: "tool:-100123:70", chatId: "-100123", messageId: 70, expiresAt: now + 1 }),
+      pin({ pinKey: "tool:-100123:71", chatId: "-100123", messageId: 71, expiresAt: now }),
+      pin({ pinKey: "wk:agent-x", chatId: "-100123", messageId: 72 }),
+    ]);
+    const unpinned: number[] = [];
+    const res = await runStatusPinBootCleanup({
+      path: PATH,
+      fs,
+      unpin: async (_c, messageId) => {
+        unpinned.push(messageId);
+      },
+      now,
+      log: () => {},
+    });
+    // The expired tool pin and the work-scoped wk: pin are unpinned; the
+    // unexpired tool pin is kept for a future boot (restart ≠ reset for a
+    // deliberate agent pin with no "work finished" event).
+    expect(unpinned).toEqual([71, 72]);
+    expect(res).toEqual({ cleared: 2, retained: 0, kept: 1, total: 3 });
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "tool:-100123:70", chatId: "-100123", messageId: 70, expiresAt: now + 1 },
+    ]);
+  });
+
   it("no-op on a fresh boot with no persisted pins (no unpin calls)", async () => {
     const { fs } = memFs();
     let calls = 0;
@@ -232,7 +288,7 @@ describe("runStatusPinBootCleanup", () => {
       },
       log: () => {},
     });
-    expect(res).toEqual({ cleared: 0, total: 0 });
+    expect(res).toEqual({ cleared: 0, retained: 0, kept: 0, total: 0 });
     expect(calls).toBe(0);
   });
 
@@ -254,7 +310,7 @@ describe("runStatusPinBootCleanup", () => {
       log: () => {},
     });
     expect(unpinned).toEqual([["-100777", 314]]);
-    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(loadStatusPins(PATH, fs)).toEqual([]);
   });
 });