switchroom 0.5.0

package/telegram-plugin/tests/gateway-startup-network-retry.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Tests for the gateway startup network-retry helper.
+ *
+ * Regression guard for the 2026-04-29 incident where all five switchroom
+ * gateways silently failed at boot because `api.telegram.org` was unreachable
+ * for ~27 minutes. The process logged an error and returned (stayed alive,
+ * didn't poll) rather than exiting, so systemd's `Restart=always` never fired.
+ *
+ * These tests pin:
+ *   - `isBootNetworkError` correctly classifies grammy HttpErrors and raw errors
+ *   - `gatewayStartupRetry` retries on network errors with backoff
+ *   - When retries are exhausted, `onExhausted` is called (simulating exit)
+ *   - Non-network errors are NOT retried (rethrown immediately)
+ *   - Success on a later attempt resolves the returned promise
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import {
+  isBootNetworkError,
+  gatewayStartupRetry,
+  STARTUP_RETRY_DELAYS_MS,
+} from '../gateway/startup-network-retry'
+
+// ── isBootNetworkError ────────────────────────────────────────────────────────
+
+describe('isBootNetworkError', () => {
+  it('returns true for an error with name HttpError (grammy wrapper)', () => {
+    const err = Object.assign(new Error('Network request for getMe failed!'), {
+      name: 'HttpError',
+    })
+    expect(isBootNetworkError(err)).toBe(true)
+  })
+
+  it('returns true for ECONNRESET', () => {
+    expect(isBootNetworkError(new Error('ECONNRESET'))).toBe(true)
+  })
+
+  it('returns true for ETIMEDOUT', () => {
+    expect(isBootNetworkError(new Error('connect ETIMEDOUT 149.154.167.220:443'))).toBe(true)
+  })
+
+  it('returns true for ENOTFOUND', () => {
+    expect(isBootNetworkError(new Error('getaddrinfo ENOTFOUND api.telegram.org'))).toBe(true)
+  })
+
+  it('returns true for ECONNREFUSED', () => {
+    expect(isBootNetworkError(new Error('connect ECONNREFUSED 127.0.0.1:443'))).toBe(true)
+  })
+
+  it('returns true for "fetch failed"', () => {
+    expect(isBootNetworkError(new Error('fetch failed'))).toBe(true)
+  })
+
+  it('returns true for "Network request" messages', () => {
+    expect(
+      isBootNetworkError(new Error("Network request for 'deleteWebhook' failed!")),
+    ).toBe(true)
+  })
+
+  it('returns false for a GrammyError 403 (not a network error)', () => {
+    const err = Object.assign(new Error('Forbidden: bot was kicked'), {
+      name: 'GrammyError',
+      error_code: 403,
+    })
+    expect(isBootNetworkError(err)).toBe(false)
+  })
+
+  it('returns false for a generic application error', () => {
+    expect(isBootNetworkError(new Error('some unrelated error'))).toBe(false)
+  })
+
+  it('returns false for non-Error values', () => {
+    expect(isBootNetworkError('string error')).toBe(false)
+    expect(isBootNetworkError(null)).toBe(false)
+    expect(isBootNetworkError(42)).toBe(false)
+  })
+})
+
+// ── gatewayStartupRetry ───────────────────────────────────────────────────────
+
+describe('gatewayStartupRetry', () => {
+  const noopLog = () => {}
+
+  it('resolves immediately when fn() succeeds on first attempt', async () => {
+    const fn = vi.fn().mockResolvedValue('ok')
+    const result = await gatewayStartupRetry(fn, { log: noopLog })
+    expect(result).toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries on network error and resolves when fn eventually succeeds', async () => {
+    const networkErr = Object.assign(new Error('Network request failed'), {
+      name: 'HttpError',
+    })
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(networkErr)
+      .mockRejectedValueOnce(networkErr)
+      .mockResolvedValue('recovered')
+
+    const sleep = vi.fn().mockResolvedValue(undefined)
+    const result = await gatewayStartupRetry(fn, {
+      delaysMs: [100, 200, 400],
+      sleep,
+      log: noopLog,
+    })
+
+    expect(result).toBe('recovered')
+    expect(fn).toHaveBeenCalledTimes(3)
+    expect(sleep).toHaveBeenCalledTimes(2)
+    expect(sleep).toHaveBeenNthCalledWith(1, 100)
+    expect(sleep).toHaveBeenNthCalledWith(2, 200)
+  })
+
+  it('calls onExhausted (not returns) when all retries are exhausted', async () => {
+    const networkErr = Object.assign(new Error('Network request failed'), {
+      name: 'HttpError',
+    })
+    const fn = vi.fn().mockRejectedValue(networkErr)
+    const onExhausted = vi.fn(() => { throw new Error('__exited__') }) as unknown as (err: unknown) => never
+
+    const sleep = vi.fn().mockResolvedValue(undefined)
+
+    await expect(
+      gatewayStartupRetry(fn, {
+        delaysMs: [1, 2],  // 3 total attempts (delays.length + 1)
+        sleep,
+        onExhausted,
+        log: noopLog,
+      }),
+    ).rejects.toThrow('__exited__')
+
+    expect(fn).toHaveBeenCalledTimes(3)
+    expect(onExhausted).toHaveBeenCalledTimes(1)
+    expect(onExhausted).toHaveBeenCalledWith(networkErr)
+  })
+
+  it('does NOT retry non-network errors — rethrows immediately', async () => {
+    const appErr = new Error('bad token')
+    const fn = vi.fn().mockRejectedValue(appErr)
+    const sleep = vi.fn()
+    const onExhausted = vi.fn()
+
+    await expect(
+      gatewayStartupRetry(fn, {
+        delaysMs: [100, 200],
+        sleep,
+        onExhausted: onExhausted as unknown as (err: unknown) => never,
+        log: noopLog,
+      }),
+    ).rejects.toThrow('bad token')
+
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(sleep).not.toHaveBeenCalled()
+    expect(onExhausted).not.toHaveBeenCalled()
+  })
+
+  it('uses STARTUP_RETRY_DELAYS_MS by default (7 delays → 8 total attempts)', () => {
+    expect(STARTUP_RETRY_DELAYS_MS).toHaveLength(7)
+    // Verify the schedule is monotonically increasing and ends at 64 s
+    expect(STARTUP_RETRY_DELAYS_MS[0]).toBe(1_000)
+    expect(STARTUP_RETRY_DELAYS_MS[STARTUP_RETRY_DELAYS_MS.length - 1]).toBe(64_000)
+  })
+
+  it('logs retry progress before each sleep', async () => {
+    const networkErr = Object.assign(new Error('Network request failed'), {
+      name: 'HttpError',
+    })
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(networkErr)
+      .mockResolvedValue('ok')
+
+    const sleep = vi.fn().mockResolvedValue(undefined)
+    const log = vi.fn()
+
+    await gatewayStartupRetry(fn, { delaysMs: [50], sleep, log })
+
+    expect(log).toHaveBeenCalledTimes(1)
+    const logMsg: string = log.mock.calls[0][0]
+    expect(logMsg).toMatch(/startup network error/)
+    expect(logMsg).toMatch(/attempt 1\/2/)
+    expect(logMsg).toMatch(/retrying in 0.05s/)
+  })
+})

package/telegram-plugin/tests/gateway-startup-reset.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi } from "vitest";
+import { clearStaleTelegramPollingState } from "../startup-reset";
+
+/**
+ * Regression guard for the 409 Conflict loop seen on 2026-04-21.
+ *
+ * Incident: klanker's gateway died with systemd result=timeout at 16:35
+ * while holding an active long-poll on Telegram's side. Every subsequent
+ * gateway startup raced that orphaned slot on getUpdates and got back
+ * 409 Conflict indefinitely. Grammy's retry backoff didn't break out of
+ * the loop; the gateway polled, failed, retried, polled, failed for
+ * roughly two hours until someone manually called deleteWebhook.
+ *
+ * Fix: call deleteWebhook(drop_pending_updates=true) unconditionally at
+ * gateway startup, before grammy starts polling.
+ *
+ * These tests pin that behaviour so we don't accidentally remove the
+ * call during a future refactor and reintroduce the silent-respawn
+ * anti-pattern from reference/restart-and-know-what-im-running.md.
+ */
+
+describe("clearStaleTelegramPollingState", () => {
+  it("calls deleteWebhook with drop_pending_updates: true", async () => {
+    const deleteWebhook = vi.fn().mockResolvedValue(true);
+    const api = { deleteWebhook };
+
+    await clearStaleTelegramPollingState(api);
+
+    expect(deleteWebhook).toHaveBeenCalledTimes(1);
+    expect(deleteWebhook).toHaveBeenCalledWith({ drop_pending_updates: true });
+  });
+
+  it("does not throw if deleteWebhook fails (best-effort)", async () => {
+    const deleteWebhook = vi.fn().mockRejectedValue(new Error("network down"));
+    const api = { deleteWebhook };
+
+    // Should complete without throwing so the startup loop can carry on
+    // and fall back to grammy's built-in 409 handling.
+    await expect(clearStaleTelegramPollingState(api)).resolves.toBeUndefined();
+    expect(deleteWebhook).toHaveBeenCalledTimes(1);
+  });
+
+  it("is idempotent when called multiple times", async () => {
+    const deleteWebhook = vi.fn().mockResolvedValue(true);
+    const api = { deleteWebhook };
+
+    await clearStaleTelegramPollingState(api);
+    await clearStaleTelegramPollingState(api);
+    await clearStaleTelegramPollingState(api);
+
+    expect(deleteWebhook).toHaveBeenCalledTimes(3);
+    // Every call uses the same args \u2014 no state accumulation.
+    for (const call of deleteWebhook.mock.calls) {
+      expect(call[0]).toEqual({ drop_pending_updates: true });
+    }
+  });
+
+  it("forwards the rejection reason to stderr as a log line (not throwing)", async () => {
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const deleteWebhook = vi.fn().mockRejectedValue(new Error("test-only: simulated 429"));
+    const api = { deleteWebhook };
+
+    await clearStaleTelegramPollingState(api);
+
+    expect(stderrWrite).toHaveBeenCalled();
+    const logged = stderrWrite.mock.calls.map(c => String(c[0])).join("\n");
+    expect(logged).toMatch(/deleteWebhook.*failed/);
+    expect(logged).toMatch(/simulated 429/);
+
+    stderrWrite.mockRestore();
+  });
+});

package/telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Live-socket dispatch test for the legacy `update_placeholder` IPC
+ * (#553 hotfix).
+ *
+ * Uses bun:test (NOT vitest) because it exercises Bun.listen / Bun.connect
+ * through the real createIpcServer.
+ *
+ * Pins three properties recall.py needs from the gateway:
+ *
+ *   1. The gateway does NOT close the connection when it receives a
+ *      legacy `update_placeholder` line — anonymous one-shots are fine,
+ *      but a force-close would change the timing semantics that
+ *      `vendor/hindsight-memory/scripts/lib/gateway_ipc.py` relies on
+ *      (it sends one line and closes the socket itself).
+ *   2. The validator does NOT log "invalid IPC message shape" — that
+ *      log line was firing on every recall hook before this fix.
+ *   3. The dispatcher emits exactly one "legacy update_placeholder
+ *      ignored" log line per connection (rate-limited to one), so the
+ *      operator can correlate the no-op decision without log spam.
+ *
+ * Run with:
+ *   cd <repo-root> && bun test telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import { mkdtempSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { createIpcServer, type IpcServer } from '../gateway/ipc-server.js'
+import type { ScheduleRestartMessage } from '../gateway/ipc-protocol.js'
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'sr-update-ph-'))
+  return join(dir, 'test.sock')
+}
+
+function wait(ms: number): Promise<void> {
+  return Bun.sleep(ms)
+}
+
+const servers: IpcServer[] = []
+
+afterEach(async () => {
+  for (const s of servers) await s.close().catch(() => {})
+  servers.length = 0
+})
+
+function makeServer(socketPath: string, log: (m: string) => void, onDisconnect: () => void): IpcServer {
+  const server = createIpcServer({
+    socketPath,
+    onClientRegistered: () => {},
+    onClientDisconnected: () => onDisconnect(),
+    onToolCall: async () => ({ type: 'tool_call_result', id: 'x', success: true, result: null }),
+    onSessionEvent: () => {},
+    onPermissionRequest: () => {},
+    onHeartbeat: () => {},
+    onScheduleRestart: (_c, _m: ScheduleRestartMessage) => {},
+    log,
+  })
+  servers.push(server)
+  return server
+}
+
+describe('update_placeholder dispatch — live IpcServer (bun)', () => {
+  it('logs once and keeps the connection open across multiple legacy lines', async () => {
+    const socketPath = tmpSocket()
+    const logs: string[] = []
+    let disconnectFired = 0
+    makeServer(socketPath, (m) => logs.push(m), () => { disconnectFired++ })
+
+    // Open a raw socket — mimics recall.py's one-shot client.
+    const sock = await Bun.connect({
+      unix: socketPath,
+      socket: {
+        data: () => {},
+        open: () => {},
+        close: () => {},
+        error: () => {},
+      },
+    })
+
+    const line1 = JSON.stringify({ type: 'update_placeholder', chatId: '123', text: 'first' }) + '\n'
+    const line2 = JSON.stringify({ type: 'update_placeholder', chatId: '123', text: 'second' }) + '\n'
+    sock.write(line1)
+    sock.write(line2)
+
+    await wait(50)
+
+    // Connection still open from the gateway's perspective.
+    expect(disconnectFired).toBe(0)
+
+    // Negative log assertions — the two lines this fix is meant to silence.
+    expect(logs.some(l => l.includes('invalid IPC message shape'))).toBe(false)
+    expect(logs.some(l => l.includes('unknown IPC message type'))).toBe(false)
+
+    // Positive: exactly one "legacy ... ignored" log line (rate-limit per connection).
+    const legacy = logs.filter(l => l.includes('legacy update_placeholder ignored'))
+    expect(legacy.length).toBe(1)
+
+    sock.end()
+    await wait(50)
+  })
+
+  it('does not crash on a malformed legacy line (validator still rejects bad shapes)', async () => {
+    const socketPath = tmpSocket()
+    const logs: string[] = []
+    makeServer(socketPath, (m) => logs.push(m), () => {})
+
+    const sock = await Bun.connect({
+      unix: socketPath,
+      socket: { data: () => {}, open: () => {}, close: () => {}, error: () => {} },
+    })
+
+    // Missing chatId → validator must still reject (defence in depth).
+    sock.write(JSON.stringify({ type: 'update_placeholder', text: 'x' }) + '\n')
+    await wait(50)
+
+    // The shape-rejection log SHOULD fire here — we only soft-accept the
+    // well-formed shape, not arbitrary `update_placeholder` payloads.
+    expect(logs.some(l => l.includes('invalid IPC message shape'))).toBe(true)
+
+    sock.end()
+    await wait(50)
+  })
+})

package/telegram-plugin/tests/handoff-continuity.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  resolveAgentDirFromEnv,
+  readHandoffTopic,
+  consumeHandoffTopic,
+  shouldShowHandoffLine,
+  formatHandoffLine,
+  readLastTurnSummary,
+  writeLastTurnSummary,
+  TOPIC_DISPLAY_MAX,
+  HANDOFF_TOPIC_FILENAME,
+  LAST_TURN_SUMMARY_FILENAME,
+} from "../handoff-continuity.js";
+
+describe("resolveAgentDirFromEnv", () => {
+  const prior = process.env.TELEGRAM_STATE_DIR;
+  afterEach(() => {
+    if (prior === undefined) delete process.env.TELEGRAM_STATE_DIR;
+    else process.env.TELEGRAM_STATE_DIR = prior;
+  });
+
+  it("returns dirname of TELEGRAM_STATE_DIR", () => {
+    process.env.TELEGRAM_STATE_DIR = "/foo/bar/agent/telegram";
+    expect(resolveAgentDirFromEnv()).toBe("/foo/bar/agent");
+  });
+
+  it("returns null when env unset", () => {
+    delete process.env.TELEGRAM_STATE_DIR;
+    expect(resolveAgentDirFromEnv()).toBeNull();
+  });
+
+  it("returns null when env is empty string", () => {
+    process.env.TELEGRAM_STATE_DIR = "   ";
+    expect(resolveAgentDirFromEnv()).toBeNull();
+  });
+});
+
+describe("readHandoffTopic", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "handoff-topic-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns null when the file is missing", () => {
+    expect(readHandoffTopic(tmp)).toBeNull();
+  });
+
+  it("returns null when the file is empty", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "");
+    expect(readHandoffTopic(tmp)).toBeNull();
+  });
+
+  it("returns the trimmed single-line topic", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "  debugging the plugin  ");
+    expect(readHandoffTopic(tmp)).toBe("debugging the plugin");
+  });
+
+  it("takes the first non-empty line when the file is multi-line", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "\n\nfirst topic\nsecond\n");
+    expect(readHandoffTopic(tmp)).toBe("first topic");
+  });
+
+  it("truncates topics longer than the display max", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "x".repeat(TOPIC_DISPLAY_MAX + 20));
+    const got = readHandoffTopic(tmp)!;
+    expect(got.endsWith("…")).toBe(true);
+    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
+  });
+});
+
+describe("consumeHandoffTopic", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "handoff-consume-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns the topic and deletes the file", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "once");
+    expect(consumeHandoffTopic(tmp)).toBe("once");
+    expect(existsSync(join(tmp, HANDOFF_TOPIC_FILENAME))).toBe(false);
+  });
+
+  it("returns null on the second call (one-shot)", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "once");
+    expect(consumeHandoffTopic(tmp)).toBe("once");
+    expect(consumeHandoffTopic(tmp)).toBeNull();
+  });
+
+  it("returns null when the file is missing", () => {
+    expect(consumeHandoffTopic(tmp)).toBeNull();
+  });
+
+  it("falls back to .last-turn-summary when no .handoff-topic exists", () => {
+    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "3 tools, 12s — fix the bug");
+    expect(consumeHandoffTopic(tmp)).toBe("3 tools, 12s — fix the bug");
+    // Fallback sidecar removed so a repeat call doesn't refire.
+    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
+  });
+
+  it("prefers .handoff-topic when both files exist", () => {
+    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), "llm summary");
+    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "card summary");
+    expect(consumeHandoffTopic(tmp)).toBe("llm summary");
+    // Both get removed so neither stays around to fire on a later restart.
+    expect(existsSync(join(tmp, HANDOFF_TOPIC_FILENAME))).toBe(false);
+    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
+  });
+});
+
+describe("readLastTurnSummary", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "handoff-lastturn-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("returns null when missing", () => {
+    expect(readLastTurnSummary(tmp)).toBeNull();
+  });
+
+  it("reads the first non-empty line", () => {
+    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "\n5 tools, 47s — run evals\nmore\n");
+    expect(readLastTurnSummary(tmp)).toBe("5 tools, 47s — run evals");
+  });
+
+  it("truncates long summaries", () => {
+    writeFileSync(join(tmp, LAST_TURN_SUMMARY_FILENAME), "x".repeat(TOPIC_DISPLAY_MAX + 10));
+    const got = readLastTurnSummary(tmp)!;
+    expect(got.endsWith("…")).toBe(true);
+    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
+  });
+});
+
+describe("writeLastTurnSummary", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "handoff-write-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("writes a round-trippable summary", () => {
+    writeLastTurnSummary(tmp, "7 tools, 02:04 — ship the progress card");
+    expect(readLastTurnSummary(tmp)).toBe("7 tools, 02:04 — ship the progress card");
+  });
+
+  it("overwrites on subsequent calls (always reflects the most-recent turn)", () => {
+    writeLastTurnSummary(tmp, "first turn");
+    writeLastTurnSummary(tmp, "second turn");
+    expect(readLastTurnSummary(tmp)).toBe("second turn");
+  });
+
+  it("writes only the first line even when input is multi-line", () => {
+    writeLastTurnSummary(tmp, "headline\nlots more context goes here\nstill more");
+    expect(readLastTurnSummary(tmp)).toBe("headline");
+  });
+
+  it("truncates over-long input at TOPIC_DISPLAY_MAX + ellipsis", () => {
+    writeLastTurnSummary(tmp, "x".repeat(TOPIC_DISPLAY_MAX + 50));
+    const got = readLastTurnSummary(tmp)!;
+    expect(got.length).toBe(TOPIC_DISPLAY_MAX + 1);
+    expect(got.endsWith("…")).toBe(true);
+  });
+
+  it("no-ops on empty / whitespace-only input (never writes an empty file)", () => {
+    writeLastTurnSummary(tmp, "   ");
+    expect(existsSync(join(tmp, LAST_TURN_SUMMARY_FILENAME))).toBe(false);
+  });
+});
+
+describe("shouldShowHandoffLine", () => {
+  const prior = process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
+  afterEach(() => {
+    if (prior === undefined) delete process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
+    else process.env.SWITCHROOM_HANDOFF_SHOW_LINE = prior;
+  });
+
+  it("defaults to true when unset", () => {
+    delete process.env.SWITCHROOM_HANDOFF_SHOW_LINE;
+    expect(shouldShowHandoffLine()).toBe(true);
+  });
+
+  it("returns true for 'true'", () => {
+    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "true";
+    expect(shouldShowHandoffLine()).toBe(true);
+  });
+
+  it("returns false for 'false' (case-insensitive)", () => {
+    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "FALSE";
+    expect(shouldShowHandoffLine()).toBe(false);
+  });
+
+  it("returns true for any other value (safe default)", () => {
+    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = "yes";
+    expect(shouldShowHandoffLine()).toBe(true);
+  });
+});
+
+describe("formatHandoffLine", () => {
+  it("wraps the topic in italic HTML with the return emoji", () => {
+    const line = formatHandoffLine("fixing the bug", "html");
+    expect(line).toBe("<i>↩️ Picked up where we left off — fixing the bug</i>\n\n");
+  });
+
+  it("escapes HTML-unsafe chars in the topic", () => {
+    const line = formatHandoffLine("<script> & ok", "html");
+    expect(line).toContain("&lt;script&gt; &amp; ok");
+    expect(line).not.toContain("<script>");
+  });
+
+  it("produces MarkdownV2 italic with escaped specials", () => {
+    const line = formatHandoffLine("a.b (c)", "markdownv2");
+    expect(line.startsWith("_")).toBe(true);
+    expect(line.endsWith("_\n\n")).toBe(true);
+    expect(line).toContain("a\\.b");
+    expect(line).toContain("\\(c\\)");
+  });
+
+  it("produces plain text for 'text' format", () => {
+    const line = formatHandoffLine("simple", "text");
+    expect(line).toBe("↩️ Picked up where we left off — simple\n\n");
+  });
+
+  it("always ends with a blank-line separator", () => {
+    for (const fmt of ["html", "markdownv2", "text"] as const) {
+      expect(formatHandoffLine("t", fmt).endsWith("\n\n")).toBe(true);
+    }
+  });
+});