switchroom 0.5.0

package/telegram-plugin/gateway/boot-reason.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure helpers for determining boot reason and resolving the target chat
+ * on every gateway start.
+ *
+ * Kept in a separate module so unit tests can import them without pulling
+ * in the full gateway.ts side-effect tree (bot setup, DB init, etc.).
+ */
+
+import type { RestartReason } from './boot-card.js'
+import type { CleanShutdownMarker } from './clean-shutdown-marker.js'
+import { DEFAULT_MAX_AGE_MS as CLEAN_SHUTDOWN_MAX_AGE_MS } from './clean-shutdown-marker.js'
+import type { SessionMarker } from './session-marker.js'
+
+// Re-export so tests can import from a single path
+export type { RestartReason }
+
+/**
+ * Determine why this gateway is starting up.
+ *
+ * Priority order:
+ *   1. restart-pending.json present + fresh (<5 min) → 'planned'
+ *   2. clean-shutdown.json present + fresh (<60s default) → 'graceful'
+ *   3. gateway-session.json present (prior process existed) → 'crash'
+ *   4. Otherwise → 'fresh'
+ */
+export function determineRestartReason(opts: {
+  marker: { ts: number } | null
+  cleanMarker: CleanShutdownMarker | null
+  sessionMarker: SessionMarker | null
+  now: number
+  cleanMaxAgeMs?: number
+  markerMaxAgeMs?: number
+}): RestartReason {
+  const {
+    marker,
+    cleanMarker,
+    sessionMarker,
+    now,
+    cleanMaxAgeMs = CLEAN_SHUTDOWN_MAX_AGE_MS,
+    markerMaxAgeMs = 5 * 60_000,
+  } = opts
+  if (marker != null && now - marker.ts < markerMaxAgeMs) return 'planned'
+  if (
+    cleanMarker != null &&
+    now - cleanMarker.ts >= 0 &&
+    now - cleanMarker.ts < cleanMaxAgeMs
+  )
+    return 'graceful'
+  if (sessionMarker != null) return 'crash'
+  return 'fresh'
+}

package/telegram-plugin/gateway/boot-sweep-filter.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { shouldSweepChatAtBoot } from "./boot-sweep-filter";
+
+describe("shouldSweepChatAtBoot", () => {
+  // User DM IDs — positive integers. Bot has no chat record until the user
+  // messages first. getChat() returns `400 chat not found`.
+  it("returns false for a typical user ID (positive integer string)", () => {
+    expect(shouldSweepChatAtBoot("123456789")).toBe(false);
+    expect(shouldSweepChatAtBoot("1")).toBe(false);
+    expect(shouldSweepChatAtBoot("999999999999")).toBe(false);
+  });
+
+  // Group/supergroup IDs — negative integers. Bot is a member and getChat works.
+  it("returns true for a typical group ID (negative integer string)", () => {
+    expect(shouldSweepChatAtBoot("-100123456789")).toBe(true);
+    expect(shouldSweepChatAtBoot("-1")).toBe(true);
+    expect(shouldSweepChatAtBoot("-987654321")).toBe(true);
+  });
+
+  // Edge cases — malformed / zero input should NOT be swept.
+  it("returns false for zero", () => {
+    expect(shouldSweepChatAtBoot("0")).toBe(false);
+  });
+
+  it("returns false for non-numeric strings", () => {
+    expect(shouldSweepChatAtBoot("")).toBe(false);
+    expect(shouldSweepChatAtBoot("abc")).toBe(false);
+    expect(shouldSweepChatAtBoot("undefined")).toBe(false);
+    expect(shouldSweepChatAtBoot("NaN")).toBe(false);
+  });
+
+  it("returns false for floating-point strings (non-integer chat IDs don't exist)", () => {
+    expect(shouldSweepChatAtBoot("1.5")).toBe(false);
+    expect(shouldSweepChatAtBoot("-1.5")).toBe(false);
+  });
+
+  it("returns false for Infinity / -Infinity strings", () => {
+    expect(shouldSweepChatAtBoot("Infinity")).toBe(false);
+    expect(shouldSweepChatAtBoot("-Infinity")).toBe(false);
+  });
+
+  // Table-driven summary to make PR review easy.
+  it.each([
+    // [chatId, expected, description]
+    ["111111111", false, "user DM — positive"],
+    ["-1001234567890", true, "supergroup — large negative"],
+    ["0", false, "zero — invalid"],
+    ["not-a-number", false, "non-numeric"],
+    ["-100000000000", true, "valid negative group"],
+    ["2", false, "small positive user id"],
+  ])("shouldSweepChatAtBoot(%s) === %s (%s)", (chatId, expected) => {
+    expect(shouldSweepChatAtBoot(chatId)).toBe(expected);
+  });
+});

package/telegram-plugin/gateway/boot-sweep-filter.ts

@@ -0,0 +1,32 @@
+/**
+ * Boot-sweep filter for `sweepBotAuthoredPins`.
+ *
+ * At first boot the gateway enumerates every chat ID in `access.allowFrom`
+ * and calls `getChat()` to discover pinned messages. Telegram's Bot API
+ * returns `400 chat not found` for user DM chat IDs (positive integers)
+ * when the user has never previously sent a message to the bot — the bot
+ * has no "chat" record for them yet.
+ *
+ * Group/supergroup IDs are negative and don't have this restriction — the
+ * bot can call `getChat` on any group it's a member of.
+ *
+ * This helper gates which IDs the boot sweep should attempt to probe.
+ * Skipping positive IDs eliminates the `chat not found` noise on startup
+ * and defers the per-user sweep until the user actually messages the bot.
+ */
+
+/**
+ * Returns `true` if the given chat ID should be included in the boot
+ * pin sweep, `false` if it should be skipped.
+ *
+ * Rules:
+ * - Negative IDs  → group/supergroup → always sweep (bot is a member).
+ * - Positive IDs  → user DM         → skip (user may never have DMed).
+ * - Zero or non-numeric → malformed → skip (defensive).
+ */
+export function shouldSweepChatAtBoot(chatId: string): boolean {
+  const n = Number(chatId);
+  if (!Number.isFinite(n) || n === 0 || !Number.isInteger(n)) return false;
+  // Negative IDs are groups/supergroups — safe to sweep.
+  return n < 0;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Clean-shutdown marker — a sentinel written by the SIGTERM/SIGINT
+ * handler so the NEXT gateway process knows the previous shutdown was
+ * deliberate, not a crash.
+ *
+ * Why this exists:
+ *   The boot path posts a "⚡ Recovered from unexpected restart"
+ *   banner whenever it doesn't find a /restart user-marker — assuming
+ *   any unannounced restart was a crash. But planned restarts
+ *   (`systemctl --user restart switchroom-clerk-gateway`,
+ *   `switchroom agent restart`, Coolify/CI redeploys, etc.) had no way
+ *   to signal "this was planned" without claiming the user-ACK marker
+ *   (RestartMarker), which carries chat_id + ack_message_id and is the
+ *   wrong shape for non-user-initiated paths.
+ *
+ *   This is a SECOND, separate marker — purpose-built for "the OS told
+ *   us to stop". It is intentionally simpler than RestartMarker: no
+ *   chat_id, no ack_message_id, just `{ ts, signal }` so the next boot
+ *   can verify the signal is fresh and suppress the recovery banner.
+ *
+ * Lifecycle:
+ *   1. SIGTERM/SIGINT handler writes the marker BEFORE invoking the
+ *      drain coordinator. (If the drain hangs and the +5s force-exit
+ *      kills the process, the marker is already on disk.)
+ *   2. Next gateway boot reads the marker. Fresh (<60s) → suppress the
+ *      recovery banner + clear the marker. Stale (>=60s) → clear it but
+ *      treat as a real crash anyway (a clean shutdown that took >60s
+ *      almost certainly stalled mid-drain — operator probably wants the
+ *      banner).
+ *   3. The existing /restart user-marker (RestartMarker) is untouched
+ *      by this module; that path remains the source of truth for "I
+ *      was asked to restart by THIS user, post a quote-reply ack".
+ */
+
+import { writeFileSync, readFileSync, renameSync, unlinkSync } from "node:fs";
+
+export interface CleanShutdownMarker {
+  /** Wall-clock ms when the SIGTERM/SIGINT was received. */
+  ts: number;
+  /** "SIGTERM" | "SIGINT" — kept as string to allow future signals. */
+  signal: string;
+  /** Optional free-form note (unused today; reserved for tagging
+   *  caller intent like "deploy" or "agent-restart"). */
+  reason?: string;
+}
+
+/** Default age cap. A clean shutdown that takes longer than this almost
+ *  certainly stalled mid-drain; the operator probably wants to see the
+ *  banner anyway. */
+export const DEFAULT_MAX_AGE_MS = 60_000;
+
+export function writeCleanShutdownMarker(
+  path: string,
+  marker: CleanShutdownMarker,
+): void {
+  // Atomic write via tmp + rename so a partial write can't ever be read
+  // back as malformed JSON by the next boot.
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(marker), "utf-8");
+  renameSync(tmp, path);
+}
+
+export function readCleanShutdownMarker(
+  path: string,
+): CleanShutdownMarker | null {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<CleanShutdownMarker>;
+    if (
+      typeof parsed.ts === "number" &&
+      Number.isFinite(parsed.ts) &&
+      typeof parsed.signal === "string" &&
+      parsed.signal.length > 0
+    ) {
+      const out: CleanShutdownMarker = { ts: parsed.ts, signal: parsed.signal };
+      if (typeof parsed.reason === "string") out.reason = parsed.reason;
+      return out;
+    }
+    return null;
+  } catch {
+    // Missing file OR malformed JSON — both are "no usable marker", and
+    // a malformed marker MUST NOT crash boot.
+    return null;
+  }
+}
+
+export function clearCleanShutdownMarker(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    /* best effort — file may already be gone */
+  }
+}
+
+/**
+ * Pure decision: should the boot path SUPPRESS the "recovered from
+ * unexpected restart" banner because we found a fresh clean-shutdown
+ * marker?
+ *
+ * Returns true ONLY when:
+ *   - a marker is present, AND
+ *   - the marker is younger than maxAgeMs (default 60s).
+ *
+ * Returns false when:
+ *   - no marker (true crash or first boot — fire the banner), OR
+ *   - marker is stale (clean shutdown initiated but never completed
+ *     within maxAgeMs — almost certainly a crash mid-drain, fire the
+ *     banner anyway).
+ *
+ * Keeping this pure makes the boot decision unit-testable without
+ * having to spin up a real Bot/Context.
+ */
+export function shouldSuppressRecoveryBanner(
+  marker: CleanShutdownMarker | null,
+  now: number,
+  maxAgeMs: number = DEFAULT_MAX_AGE_MS,
+): boolean {
+  if (marker === null) return false;
+  const age = now - marker.ts;
+  if (age < 0) return false; // clock skew defence — treat as stale
+  return age < maxAgeMs;
+}
+
+/** Maximum age for a pre-stamped reason to be considered "fresh" and
+ *  worth preserving across a SIGTERM-triggered marker rewrite. Matches
+ *  the cooperative-race window in `writeRestartReasonMarker`
+ *  (src/agents/lifecycle.ts): CLI/user/watchdog initiators stamp the
+ *  marker immediately before issuing the systemctl restart, so the
+ *  SIGTERM handler runs well within 30s. */
+export const REASON_PRESERVE_MAX_AGE_MS = 30_000;
+
+/** Fallback reason stamped when the gateway receives SIGTERM/SIGINT and
+ *  no other initiator (CLI, watchdog, user slash) pre-stamped a reason.
+ *  Covers the "bare `systemctl restart switchroom-<name>-gateway`" path
+ *  that PR #58 did not thread through. Without this, those restarts
+ *  produced a reasonless marker and the greeting's Restarted row was
+ *  silently omitted — which is exactly what Ken hit on 2026-04-24
+ *  when applying an EnvironmentFile change via systemctl. */
+export const EXTERNAL_RESTART_FALLBACK_REASON = "systemctl: external restart";
+
+/**
+ * Pure decision: compute the marker the SIGTERM/SIGINT handler should
+ * write, given any prior marker already on disk (e.g. stamped by a CLI
+ * restart, watchdog, or user slash BEFORE systemd sent the signal).
+ *
+ * Three outcomes:
+ *
+ *   1. Prior marker exists AND carries a reason AND is fresh (<30s):
+ *      preserve the reason, refresh `ts` to now and set `signal` to the
+ *      incoming signal. This is the cooperative-race case — every CLI
+ *      path writes its reason microseconds before issuing the
+ *      `systemctl restart` that delivers SIGTERM, and we must not clobber
+ *      that attribution.
+ *
+ *   2. Prior marker exists but is stale, has no reason, or is missing
+ *      a required field: write a fresh marker with the fallback reason
+ *      `"systemctl: external restart"`. This is the bare-`systemctl
+ *      restart` path (no CLI wrapping, no watchdog, no slash command)
+ *      which otherwise leaves the greeting silent about WHY the
+ *      restart happened.
+ *
+ *   3. No prior marker at all: same as case 2 — fresh marker with the
+ *      fallback reason. Staying silent would regress the user-visible
+ *      contract that every planned shutdown produces a Restarted row.
+ *
+ * Pure so we can unit-test the sequencing without racing a real gateway
+ * shutdown. Keeping `now` and `prior` as arguments removes the hidden
+ * time + fs dependency.
+ */
+export function resolveShutdownMarker(
+  prior: CleanShutdownMarker | null,
+  signal: string,
+  now: number,
+  maxPreserveAgeMs: number = REASON_PRESERVE_MAX_AGE_MS,
+): CleanShutdownMarker {
+  if (prior && typeof prior.reason === "string" && prior.reason.length > 0) {
+    const age = now - prior.ts;
+    if (age >= 0 && age < maxPreserveAgeMs) {
+      return { ts: now, signal, reason: prior.reason };
+    }
+  }
+  return { ts: now, signal, reason: EXTERNAL_RESTART_FALLBACK_REASON };
+}

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -0,0 +1,109 @@
+/**
+ * Post-disconnect flush helper for the gateway IPC server.
+ *
+ * Why this exists as its own function:
+ *
+ * `onClientDisconnected` was firing for EVERY client disconnect, including
+ * anonymous one-shot connections from `recall.py` that send a single legacy
+ * `update_placeholder` IPC message and then close. The old code
+ * unconditionally:
+ *
+ *   - flushed every active StatusReactionController to 👍 ("done")
+ *   - disposed the progress driver (recreating turn state)
+ *   - finalized every open draft stream
+ *
+ * The intent of that flush was "an actual agent (claude bridge) crashed —
+ * clean up so the user's pinned 🤔/🔥/⚡ doesn't sit there forever". But the
+ * effect was: every recall.py IPC handshake fired 👍 on the inbound message
+ * mid-turn, then the redrawn driver caused a duplicate edited-message bug.
+ *
+ * Anonymous clients never call `register` so `agentName` stays null. The
+ * fix is to scope the flush to clients that actually registered as an
+ * agent — those are the only ones whose disconnect implies a real agent
+ * crash/restart. Anonymous one-shots are no-ops here.
+ *
+ * Extracted into a pure function so the gating contract has its own unit
+ * test (`telegram-plugin/tests/gateway-disconnect-flush.test.ts`) without
+ * needing to spin up the whole gateway.
+ */
+
+export interface DisconnectFlushDeps<Ctrl extends { setDone: () => void }, Stream extends { isFinal: () => boolean; finalize: () => Promise<void> }> {
+  /** The disconnecting client's agentName. `null` ⇒ anonymous (never registered). */
+  agentName: string | null
+
+  /** In-flight status-reaction controllers keyed by chat:thread:msgId. */
+  activeStatusReactions: Map<string, Ctrl>
+  /** Mirror map: same keys → message metadata. */
+  activeReactionMsgIds: Map<string, { chatId: string; messageId: number }>
+  /** Mirror map: same keys → turn-start timestamps. */
+  activeTurnStartedAt: Map<string, number>
+
+  /** Open draft-stream handles keyed by chat:thread:replyId. */
+  activeDraftStreams: Map<string, Stream>
+  /** Mirror map: same keys → parse mode. */
+  activeDraftParseModes: Map<string, 'HTML' | 'MarkdownV2' | undefined>
+
+  /** Persist-side reaction registry (per-agent on-disk state). */
+  clearActiveReactions: () => void
+  /** Progress driver — disposed with `preservePending: true` for sub-agent JTBDs (#393). */
+  disposeProgressDriver: () => void
+
+  /** Logger — receives the one-line decision trace. */
+  log: (msg: string) => void
+}
+
+/**
+ * Apply the disconnect-flush policy. Returns `true` when the flush ran
+ * (registered agent disconnected), `false` when it was skipped (anonymous
+ * client). The boolean is for tests + observability — callers can ignore it.
+ */
+export function flushOnAgentDisconnect<
+  Ctrl extends { setDone: () => void },
+  Stream extends { isFinal: () => boolean; finalize: () => Promise<void> },
+>(deps: DisconnectFlushDeps<Ctrl, Stream>): boolean {
+  const {
+    agentName,
+    activeStatusReactions,
+    activeReactionMsgIds,
+    activeTurnStartedAt,
+    activeDraftStreams,
+    activeDraftParseModes,
+    clearActiveReactions,
+    disposeProgressDriver,
+    log,
+  } = deps
+
+  if (agentName == null) {
+    // Anonymous client — never registered, almost certainly a one-shot
+    // recall.py IPC handshake. Do NOT touch turn state.
+    log('telegram gateway: anonymous client disconnect — skipping reaction/driver flush')
+    return false
+  }
+
+  // Real agent disconnect (e.g. the claude bridge crashed/restarted). Flush
+  // all in-flight status reactions to 👍 so user messages don't stay stuck on
+  // intermediate emoji (🤔, 🔥, etc.) after an agent crash/restart.
+  for (const [key, ctrl] of activeStatusReactions.entries()) {
+    ctrl.setDone()
+    activeStatusReactions.delete(key)
+    activeReactionMsgIds.delete(key)
+    activeTurnStartedAt.delete(key)
+  }
+  clearActiveReactions()
+
+  // Stop coalesce timers that could emit into a finalized draft stream, but
+  // preserve chats with pendingCompletion=true — those have background
+  // sub-agents that legitimately outlive the parent bridge disconnect. The
+  // heartbeat continues for preserved chats so elapsed-time ticks and the
+  // deferred-completion-timeout path remain active. Fix for #393.
+  disposeProgressDriver()
+
+  // Finalize any open draft streams so they don't hang mid-edit.
+  for (const [key, stream] of activeDraftStreams.entries()) {
+    if (!stream.isFinal()) void stream.finalize().catch(() => {})
+    activeDraftStreams.delete(key)
+    activeDraftParseModes.delete(key)
+  }
+
+  return true
+}