switchroom 0.20.9 → 0.20.11

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -573,6 +573,48 @@ export interface PostSkillProposalMessage {
   evidence: string;
   /** Full drafted skill bundle (SKILL.md + optional files). */
   draft: Record<string, string>;
+  /**
+   * Provenance of the proposal — `"skill-synthesis"` (the weekly cron) or
+   * `"failure-synthesis"` (a skill drafted from an observed failure). Absent
+   * ⇒ the store defaults it to `"skill-synthesis"` (back-compat). Provenance
+   * is orthogonal to tier routing.
+   */
+  origin?: "skill-synthesis" | "failure-synthesis";
+}
+
+/**
+ * `switchroom self-improve add-eval-case` asks the caller agent's gateway to
+ * persist an eval-case proposal and post a one-tap Approve/Dismiss card (RFC
+ * amendment §"corrections as eval cases"). Unlike a skill proposal, the
+ * Approve tap does NOT inject a model turn — the gateway runs the
+ * DETERMINISTIC `apply-eval-case` applier so the case lands byte-exact.
+ *
+ * Trust model identical to post_skill_proposal: per-agent socket, agentName
+ * validated, chat fenced to the agent's own chat.
+ */
+export interface PostEvalCaseProposalMessage {
+  type: "post_eval_case_proposal";
+  agentName: string;
+  /** Agent's own chat id (fenced server-side). */
+  chatId: string;
+  threadId?: number;
+  /** Target skill slug. */
+  skillSlug: string;
+  /** Absolute path to the owned skill bundle dir (resolved by the CLI). */
+  skillDir: string;
+  /** The eval case to append (prompt + optional expected/expectations/etc). */
+  case: {
+    prompt: string;
+    expected_output?: string;
+    files?: string[];
+    expectations?: string[];
+    source?: string;
+    id?: string;
+  };
+  /** Prompt fingerprint (dedup + provenance). */
+  fingerprint: string;
+  /** Route the case to the held-out sink instead of evals.json. */
+  heldOut: boolean;
 }
 
 /**
@@ -766,6 +808,7 @@ export type ClientToGateway =
   | QuotaWallDetectedMessage
   | SendOutboundMessage
   | PostSkillProposalMessage
+  | PostEvalCaseProposalMessage
   | RolloutStatusPostMessage
   | RolloutStatusEditMessage
   | QueryPendingPermissionMessage

package/telegram-plugin/gateway/ipc-server.ts

@@ -9,6 +9,7 @@ import type {
   QueryPendingPermissionMessage,
   CheckPreApprovedMessage,
   PostSkillProposalMessage,
+  PostEvalCaseProposalMessage,
   OperatorEventForward,
   PermissionRequestForward,
   PtyPartialForward,
@@ -101,6 +102,12 @@ export interface IpcServerOptions {
    * chat. Optional; gateways that don't surface proposals ignore it.
    */
   onPostSkillProposal?: (client: IpcClient, msg: PostSkillProposalMessage) => void;
+  /**
+   * RFC amendment §"corrections as eval cases" — `add-eval-case` asks the
+   * gateway to persist an eval-case proposal and post its one-tap card.
+   * Optional; gateways that don't surface proposals ignore it.
+   */
+  onPostEvalCaseProposal?: (client: IpcClient, msg: PostEvalCaseProposalMessage) => void;
   /**
    * RFC E §4.2 Cut 2 — Drive-write PreToolUse hook asks the gateway
    * to register a kernel approval request + post a diff-preview
@@ -379,6 +386,23 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
         && (typeof m.threadId !== "number" || !Number.isInteger(m.threadId as number))) return false;
       return true;
     }
+    case "post_eval_case_proposal": {
+      // RFC amendment §"corrections as eval cases" — validate the wire shape;
+      // the gateway handler fences chatId to the agent's own chat.
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.chatId !== "string" || (m.chatId as string).length === 0) return false;
+      if (typeof m.skillSlug !== "string" || (m.skillSlug as string).length === 0) return false;
+      if (typeof m.skillDir !== "string" || (m.skillDir as string).length === 0) return false;
+      if (typeof m.fingerprint !== "string" || (m.fingerprint as string).length === 0) return false;
+      if (typeof m.heldOut !== "boolean") return false;
+      if (typeof m.case !== "object" || m.case === null || Array.isArray(m.case)) return false;
+      if (typeof (m.case as Record<string, unknown>).prompt !== "string"
+        || ((m.case as Record<string, unknown>).prompt as string).length === 0) return false;
+      if (m.threadId !== undefined
+        && (typeof m.threadId !== "number" || !Number.isInteger(m.threadId as number))) return false;
+      return true;
+    }
     case "quota_wall_detected": {
       // wedge-watchdog detected the /rate-limit-options weekly-quota menu.
       if (typeof m.agentName !== "string"
@@ -565,6 +589,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onQueryPendingPermission,
     onCheckPreApproved,
     onPostSkillProposal,
+    onPostEvalCaseProposal,
     onRequestDriveApproval,
     onRequestMs365Approval,
     onRequestConfigApproval,
@@ -733,6 +758,9 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       case "post_skill_proposal":
         if (onPostSkillProposal) onPostSkillProposal(client, msg as PostSkillProposalMessage);
         break;
+      case "post_eval_case_proposal":
+        if (onPostEvalCaseProposal) onPostEvalCaseProposal(client, msg as PostEvalCaseProposalMessage);
+        break;
       case "quota_wall_detected":
         if (onQuotaWallDetected) onQuotaWallDetected(client, msg as QuotaWallDetectedMessage);
         break;

package/telegram-plugin/gateway/narrative-lane.ts

@@ -56,7 +56,7 @@ import {
   appendActivityLabel, clipNarrative, formatStepSuffix, renderActivityFeedWithNested,
 } from '../tool-activity-summary.js'
 import { evaluatePostAnswerLiveness } from '../turn-liveness-floor.js'
-import { isSilentSentinelCardOutcome } from '../turn-flush-safety.js'
+import { isHollowGhostCardOutcome, isSilentSentinelCardOutcome } from '../turn-flush-safety.js'
 import { clearActivityCardRecord, writeActivityCardRecord } from './activity-card-store.js'
 import { chatKeyWithSuffix } from './chat-key.js'
 import {
@@ -455,10 +455,18 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
             // stays in view when the feed scrolls past. Keyed to the same
             // status-key the canonical turn-end (purgeReactionTracking) unpins.
             // Fire-and-forget; the single-owner reconcile keeps state consistent.
+            // Pass `thread` as the 4th arg so the persisted row keeps the forum
+            // topic (D4): without it a forum-topic foreground card orphaned by a
+            // crash lands a threadId-less row, and the sweep cannot aim
+            // `unpinAllForumTopicMessages` at the right topic. Mirrors the worker
+            // feed's `reconcilePin` (gateway.ts). It does NOT change the pinKey —
+            // `statusKey(chat, thread)` already folds the topic into the key; the
+            // 4th arg only threads the topic into the claim + durable row.
             void reconcileStatusPin(
               `fg:${statusKey(chat, thread)}`,
               chat,
               { pinned: true, messageId: sent.message_id },
+              thread,
             )
           } else {
             const id = turn.activityMessageId
@@ -900,7 +908,30 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
         capturedText: turn.capturedText,
         finalAnswerEverDelivered: turn.finalAnswerEverDelivered,
       })
-      if (CLEAR_STATUS_ON_COMPLETION || silentSentinelTurn) {
+      // #45 — hollow-ghost suppression. The sibling to the #4348 sentinel gate:
+      // a turn that ended having done ZERO surfaced tool work, never called
+      // reply, delivered no final answer, surfaced NO narration, and emitted no
+      // captured/reply text adopted an activity card at turn start that never
+      // got any content — the contentless `🤖 Agent · done · 0 tools · Ns`
+      // record Ken reported (a card opened by the liveness timer that stayed
+      // empty). The sentinel gate can't catch it (there is no NO_REPLY/
+      // HEARTBEAT_OK text to match; the flush classifies it `empty-text`, not
+      // `silent-marker`), so DELETE the empty card here instead of finalizing
+      // it. Deterministic (pure predicate over already-tracked turn fields) and
+      // normal-case-safe: any surfaced tool step, any rendered narrative line
+      // (`mirrorLines` — content the user actually saw), any reply, any captured
+      // text, or a delivered answer keeps the card. The `finalHtmlOverride`
+      // finalize path is only taken by the foreground handoff-clear (which fires
+      // on a delivered final answer), so this gate never contends with it.
+      const hollowGhostTurn = isHollowGhostCardOutcome({
+        replyCalled: turn.replyCalled,
+        labeledToolCount: turn.labeledToolCount,
+        mirrorLines: turn.mirrorLines,
+        capturedText: turn.capturedText,
+        lastReplyText: turn.lastReplyText,
+        finalAnswerEverDelivered: turn.finalAnswerEverDelivered,
+      })
+      if (CLEAR_STATUS_ON_COMPLETION || silentSentinelTurn || hollowGhostTurn) {
         try {
           await robustApiCall(
             () => bot.api.deleteMessage(chat, id),

package/telegram-plugin/gateway/privacy-reset.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Unit tests for the session-start privacy reset (PR3 of `/private` `/public`).
+ *
+ * Covers the two collaborating pieces:
+ *   - `resetPrivacyOnGenuineSessionStart` (privacy-state.ts): always truncates
+ *     to public; fires `onOpenIntervalReset` ONLY on a private→public
+ *     transition (a leftover OPEN interval).
+ *   - `makePrivacyResetForNewSession` (privacy-reset.ts): binds the loud-send
+ *     primitive so the alert is emitted exactly when — and only when — that
+ *     transition happened.
+ *
+ * The three spec scenarios:
+ *   1. leftover open interval  → file reset to empty AND loud alert emitted
+ *   2. already public          → file reset, NO alert
+ *   3. compact / no-reset path → state PRESERVED unchanged, NO alert
+ *
+ * Run with: npx vitest run telegram-plugin/gateway/privacy-reset.test.ts
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  openPrivateInterval,
+  readPrivacyState,
+  resetPrivacyOnGenuineSessionStart,
+  emptyPrivacyState,
+  privacyStatePath,
+  SESSION_RESET_ALERT,
+} from './privacy-state.js'
+import {
+  makePrivacyResetForNewSession,
+  bootRestoresTranscript,
+  isContinueRestoreBoot,
+} from './privacy-reset.js'
+
+describe('privacy session-start reset', () => {
+  let dir: string
+  let stderrSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'privacy-reset-'))
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  })
+
+  afterEach(() => {
+    stderrSpy.mockRestore()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  const onDisk = () => JSON.parse(readFileSync(privacyStatePath(dir), 'utf8'))
+
+  describe('resetPrivacyOnGenuineSessionStart', () => {
+    it('scenario 1: a leftover OPEN interval → file reset to empty AND callback fired', () => {
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      const onReset = vi.fn()
+      const result = resetPrivacyOnGenuineSessionStart({ stateDir: dir, onOpenIntervalReset: onReset })
+      expect(result.hadOpenInterval).toBe(true)
+      expect(onReset).toHaveBeenCalledTimes(1)
+      expect(onDisk()).toEqual(emptyPrivacyState())
+    })
+
+    it('scenario 2: already public → file reset (idempotent), NO callback', () => {
+      const onReset = vi.fn()
+      const result = resetPrivacyOnGenuineSessionStart({ stateDir: dir, onOpenIntervalReset: onReset })
+      expect(result.hadOpenInterval).toBe(false)
+      expect(onReset).not.toHaveBeenCalled()
+      expect(onDisk()).toEqual(emptyPrivacyState())
+    })
+
+    it('scenario 2b: a CLOSED-only history is treated as public → NO callback, reset to empty', () => {
+      writeFileSync(
+        privacyStatePath(dir),
+        JSON.stringify({
+          version: 1,
+          intervals: [{ start: '2026-08-06T02:00:00.000Z', end: '2026-08-06T02:05:00.000Z' }],
+        }),
+        'utf8',
+      )
+      const onReset = vi.fn()
+      const result = resetPrivacyOnGenuineSessionStart({ stateDir: dir, onOpenIntervalReset: onReset })
+      expect(result.hadOpenInterval).toBe(false)
+      expect(onReset).not.toHaveBeenCalled()
+      expect(onDisk().intervals).toEqual([])
+    })
+
+    it('scenario 3: a NON-reset path (compact / resume) preserves state — no reset is called', () => {
+      // The compact/resume paths are EXEMPT by construction: the gateway simply
+      // never calls the reset there. This asserts the invariant that, absent a
+      // reset, an open private interval survives untouched.
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      const before = readPrivacyState(dir)
+      // ...compaction happens here in the real gateway; privacy is not touched...
+      const after = readPrivacyState(dir)
+      expect(after).toEqual(before)
+      expect(after.intervals).toEqual([{ start: '2026-08-06T02:00:00.000Z', end: null }])
+    })
+  })
+
+  describe('makePrivacyResetForNewSession (loud-send binding)', () => {
+    // The factory uses the DEFAULT state-dir resolver (no stateDir param), so
+    // point TELEGRAM_STATE_DIR at the temp dir for the duration of this test.
+    let prevEnv: string | undefined
+    beforeEach(() => {
+      prevEnv = process.env.TELEGRAM_STATE_DIR
+      process.env.TELEGRAM_STATE_DIR = dir
+    })
+    afterEach(() => {
+      if (prevEnv === undefined) delete process.env.TELEGRAM_STATE_DIR
+      else process.env.TELEGRAM_STATE_DIR = prevEnv
+    })
+
+    it('emits the loud SESSION_RESET_ALERT to the chat only on a private→public transition', () => {
+      const send = vi.fn<(chatId: string, threadId: number | undefined, text: string) => void>()
+      const reset = makePrivacyResetForNewSession(send)
+
+      // Already public: no alert.
+      reset('chat-1', undefined)
+      expect(send).not.toHaveBeenCalled()
+      expect(onDisk()).toEqual(emptyPrivacyState())
+
+      // Now go private, then reset: exactly one loud alert with the pinned text.
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'))
+      reset('chat-1', 77)
+      expect(send).toHaveBeenCalledTimes(1)
+      expect(send).toHaveBeenCalledWith('chat-1', 77, SESSION_RESET_ALERT)
+      expect(onDisk()).toEqual(emptyPrivacyState())
+    })
+  })
+
+  describe('boot reset gating on --continue transcript-restore (MAJOR fix)', () => {
+    it('bootRestoresTranscript: continue/auto restore; handoff/none/undefined do not; force-fresh overrides', () => {
+      expect(bootRestoresTranscript({ resumeMode: 'continue', forceFresh: false })).toBe(true)
+      expect(bootRestoresTranscript({ resumeMode: 'auto', forceFresh: false })).toBe(true)
+      expect(bootRestoresTranscript({ resumeMode: 'handoff', forceFresh: false })).toBe(false)
+      expect(bootRestoresTranscript({ resumeMode: 'none', forceFresh: false })).toBe(false)
+      expect(bootRestoresTranscript({ resumeMode: undefined, forceFresh: false })).toBe(false)
+      // A /new /reset force-fresh boot is genuinely fresh even under continue/auto.
+      expect(bootRestoresTranscript({ resumeMode: 'continue', forceFresh: true })).toBe(false)
+      expect(bootRestoresTranscript({ resumeMode: 'auto', forceFresh: true })).toBe(false)
+    })
+
+    it('isContinueRestoreBoot reads SWITCHROOM_RESUME_MODE / SWITCHROOM_FORCE_FRESH', () => {
+      const saved = { ...process.env }
+      try {
+        delete process.env.SWITCHROOM_FORCE_FRESH
+        process.env.SWITCHROOM_RESUME_MODE = 'continue'
+        expect(isContinueRestoreBoot(null)).toBe(true)
+        process.env.SWITCHROOM_RESUME_MODE = 'handoff'
+        expect(isContinueRestoreBoot(null)).toBe(false)
+        // force-fresh env override wins over continue.
+        process.env.SWITCHROOM_RESUME_MODE = 'continue'
+        process.env.SWITCHROOM_FORCE_FRESH = '1'
+        expect(isContinueRestoreBoot(null)).toBe(false)
+      } finally {
+        process.env = saved
+      }
+    })
+
+    // Emulates the guarded boot call site: `if (target && !isContinueRestoreBoot(dir)) reset(...)`.
+    // This is the exact failure scenario the reviewer flagged.
+    function guardedBootReset(reset: (c: string, t: number | undefined) => void): void {
+      if (!isContinueRestoreBoot(null)) reset('boot-chat', undefined)
+    }
+
+    it('continue-restore boot: NO reset, NO alert, open interval PRESERVED', () => {
+      const saved = { ...process.env }
+      try {
+        process.env.TELEGRAM_STATE_DIR = dir
+        delete process.env.SWITCHROOM_FORCE_FRESH
+        process.env.SWITCHROOM_RESUME_MODE = 'continue'
+        openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'))
+        const send = vi.fn<(chatId: string, threadId: number | undefined, text: string) => void>()
+        guardedBootReset(makePrivacyResetForNewSession(send))
+        expect(send).not.toHaveBeenCalled()
+        expect(onDisk().intervals).toEqual([{ start: '2026-08-06T02:00:00.000Z', end: null }])
+      } finally {
+        process.env = saved
+      }
+    })
+
+    it('fresh (handoff) boot: reset FIRES, loud alert emitted, interval cleared', () => {
+      const saved = { ...process.env }
+      try {
+        process.env.TELEGRAM_STATE_DIR = dir
+        delete process.env.SWITCHROOM_FORCE_FRESH
+        process.env.SWITCHROOM_RESUME_MODE = 'handoff'
+        openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'))
+        const send = vi.fn<(chatId: string, threadId: number | undefined, text: string) => void>()
+        guardedBootReset(makePrivacyResetForNewSession(send))
+        expect(send).toHaveBeenCalledTimes(1)
+        expect(send).toHaveBeenCalledWith('boot-chat', undefined, SESSION_RESET_ALERT)
+        expect(onDisk()).toEqual(emptyPrivacyState())
+      } finally {
+        process.env = saved
+      }
+    })
+
+    it('continue-mode /new force-fresh boot: reset FIRES (genuinely fresh)', () => {
+      const saved = { ...process.env }
+      try {
+        process.env.TELEGRAM_STATE_DIR = dir
+        process.env.SWITCHROOM_RESUME_MODE = 'continue'
+        process.env.SWITCHROOM_FORCE_FRESH = '1'
+        openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'))
+        const send = vi.fn<(chatId: string, threadId: number | undefined, text: string) => void>()
+        guardedBootReset(makePrivacyResetForNewSession(send))
+        expect(send).toHaveBeenCalledTimes(1)
+        expect(onDisk()).toEqual(emptyPrivacyState())
+      } finally {
+        process.env = saved
+      }
+    })
+  })
+})

package/telegram-plugin/gateway/privacy-reset.ts

@@ -0,0 +1,87 @@
+/**
+ * Gateway-owned session-start privacy reset (PR3 of the `/private` `/public`
+ * feature).
+ *
+ * A genuine new session — cold boot / crash / planned restart, and a `/clear`
+ * (which starts a new logical session) — must return memory writing to its
+ * PUBLIC default. If the previous session ended while still private (an OPEN
+ * interval was left behind), the operator is told loudly, so they are never
+ * silently surprised that a stretch they thought was private is now being
+ * recorded again.
+ *
+ * The gateway is the SINGLE owner of this reset+announce (the Python
+ * `session_start.py` is deliberately NOT wired to it), which eliminates the
+ * two-owner clear/announce race. Reconnect paths (`bridge-reconnect`) and the
+ * compaction / resume / continue paths are EXEMPT by construction: they
+ * reattach to a PERSISTING session, so this is simply never called from them —
+ * there is no `source`-string branch to get wrong.
+ *
+ * This thin factory exists so gateway.ts holds only the loud-send primitive
+ * (which needs the bot handle) and the call sites stay one-liners; the
+ * reset/announce decision lives in `privacy-state.ts` and is unit-tested there.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resetPrivacyOnGenuineSessionStart, SESSION_RESET_ALERT } from './privacy-state.js'
+
+/** Posts the loud (notification-ON) reset alert. Provided by the gateway. */
+export type LoudResetSender = (
+  chatId: string,
+  threadId: number | undefined,
+  text: string,
+) => void
+
+/**
+ * Bind the loud-send primitive into a `(chatId, threadId)` reset function.
+ * Calling the returned function always resets privacy to public; it invokes
+ * `send` (the loud alert) only when a private→public transition actually
+ * happened.
+ */
+export function makePrivacyResetForNewSession(
+  send: LoudResetSender,
+): (chatId: string, threadId: number | undefined) => void {
+  return (chatId, threadId) => {
+    resetPrivacyOnGenuineSessionStart({
+      onOpenIntervalReset: () => send(chatId, threadId, SESSION_RESET_ALERT),
+    })
+  }
+}
+
+/**
+ * Does this boot RESTORE the previous Claude transcript (via `--continue`)?
+ *
+ * The boot reset must NOT fire when the transcript persists: a `continue`/`auto`
+ * agent whose container restarts mid-`/private` task replays the SAME transcript,
+ * so flipping privacy to public would resume storing that very task (the FIX-3
+ * mid-task-reset shape). Mirrors `decideBootBriefing` (boot-briefing-builder.ts):
+ * `continue` always replays; `auto` MAY replay (only when the JSONL is under
+ * `resume_max_bytes`) — the gateway can't see the inner CONTINUE_FLAG, so `auto`
+ * is treated conservatively as a restore (privacy persists; safe direction — an
+ * over-retained private interval merely excludes more, never leaks). A `/new`
+ * `/reset` force-fresh boot is genuinely fresh even under continue/auto.
+ */
+export function bootRestoresTranscript(opts: {
+  resumeMode: string | undefined
+  forceFresh: boolean
+}): boolean {
+  if (opts.forceFresh) return false
+  return opts.resumeMode === 'continue' || opts.resumeMode === 'auto'
+}
+
+/**
+ * Env/marker-reading convenience over `bootRestoresTranscript` for the gateway
+ * boot site. Reads `SWITCHROOM_RESUME_MODE` and the force-fresh signal
+ * (`SWITCHROOM_FORCE_FRESH`, hoisted by start.sh, with the `.force-fresh-session`
+ * marker as the non-docker fallback — same pair `boot-briefing-wiring.ts` uses).
+ */
+export function isContinueRestoreBoot(agentDir: string | null): boolean {
+  const forceFresh =
+    process.env.SWITCHROOM_FORCE_FRESH === '1' ||
+    (agentDir != null && existsSync(join(agentDir, '.force-fresh-session')))
+  return bootRestoresTranscript({
+    resumeMode: process.env.SWITCHROOM_RESUME_MODE,
+    forceFresh,
+  })
+}

package/telegram-plugin/gateway/privacy-state.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Unit tests for privacy-state.ts — the gateway side of the `/private`
+ * `/public` feature (PR2: open/close/read/reset + the state-file contract).
+ *
+ * These lock in the on-disk contract shared with the Python retain side
+ * (`vendor/hindsight-memory`): the exact schema, `end: null` = open interval,
+ * idempotent open/close, atomic writes (no torn file), and best-effort,
+ * corrupt-tolerant reads.
+ *
+ * Run with: npx vitest run telegram-plugin/gateway/privacy-state.test.ts
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  readPrivacyState,
+  openPrivateInterval,
+  closePrivateInterval,
+  resetToPublic,
+  isPrivate,
+  privacyStatePath,
+  emptyPrivacyState,
+  type PrivacyState,
+} from './privacy-state.js'
+
+describe('privacy-state', () => {
+  let dir: string
+  let stderrSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'privacy-state-'))
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  })
+
+  afterEach(() => {
+    stderrSpy.mockRestore()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  const path = () => privacyStatePath(dir)
+  const onDisk = (): PrivacyState => JSON.parse(readFileSync(path(), 'utf8'))
+
+  describe('readPrivacyState — best-effort, corrupt-tolerant', () => {
+    it('returns the public default when the file is missing', () => {
+      expect(readPrivacyState(dir)).toEqual(emptyPrivacyState())
+      expect(isPrivate(readPrivacyState(dir))).toBe(false)
+    })
+
+    it('does not throw and returns the default on corrupt JSON', () => {
+      writeFileSync(path(), '{ this is not json', 'utf8')
+      expect(() => readPrivacyState(dir)).not.toThrow()
+      expect(readPrivacyState(dir)).toEqual(emptyPrivacyState())
+    })
+
+    it('returns the default when intervals is not an array', () => {
+      writeFileSync(path(), JSON.stringify({ version: 1, intervals: 'nope' }), 'utf8')
+      expect(readPrivacyState(dir).intervals).toEqual([])
+    })
+
+    it('filters out malformed intervals but keeps valid ones', () => {
+      writeFileSync(
+        path(),
+        JSON.stringify({
+          version: 1,
+          intervals: [
+            { start: '2026-08-06T02:00:00.000Z', end: '2026-08-06T02:05:00.000Z' },
+            { start: 42, end: null }, // bad start
+            { end: null }, // missing start
+            { start: '2026-08-06T02:10:00.000Z', end: null }, // valid open
+          ],
+        }),
+        'utf8',
+      )
+      const state = readPrivacyState(dir)
+      expect(state.intervals).toHaveLength(2)
+      expect(state.intervals[1]).toEqual({ start: '2026-08-06T02:10:00.000Z', end: null })
+    })
+  })
+
+  describe('openPrivateInterval', () => {
+    it('appends a single open interval and writes the exact contract schema', () => {
+      const now = new Date('2026-08-06T02:00:25.558Z')
+      openPrivateInterval(now, dir)
+      expect(onDisk()).toEqual({
+        version: 1,
+        intervals: [{ start: '2026-08-06T02:00:25.558Z', end: null }],
+      })
+      expect(isPrivate(readPrivacyState(dir))).toBe(true)
+    })
+
+    it('is idempotent — a second /private while open does not stack', () => {
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      openPrivateInterval(new Date('2026-08-06T02:03:00.000Z'), dir)
+      const state = readPrivacyState(dir)
+      expect(state.intervals).toHaveLength(1)
+      expect(state.intervals[0]).toEqual({ start: '2026-08-06T02:00:00.000Z', end: null })
+    })
+
+    it('opens a fresh interval after a prior one was closed', () => {
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      closePrivateInterval(new Date('2026-08-06T02:05:00.000Z'), dir)
+      openPrivateInterval(new Date('2026-08-06T02:10:00.000Z'), dir)
+      const state = readPrivacyState(dir)
+      expect(state.intervals).toHaveLength(2)
+      expect(state.intervals[0].end).toBe('2026-08-06T02:05:00.000Z')
+      expect(state.intervals[1]).toEqual({ start: '2026-08-06T02:10:00.000Z', end: null })
+      expect(isPrivate(state)).toBe(true)
+    })
+  })
+
+  describe('closePrivateInterval', () => {
+    it('sets end on the open interval', () => {
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      closePrivateInterval(new Date('2026-08-06T02:05:10.100Z'), dir)
+      expect(onDisk().intervals[0]).toEqual({
+        start: '2026-08-06T02:00:00.000Z',
+        end: '2026-08-06T02:05:10.100Z',
+      })
+      expect(isPrivate(readPrivacyState(dir))).toBe(false)
+    })
+
+    it('is idempotent — /public while already public is a no-op (no throw, no file)', () => {
+      expect(() => closePrivateInterval(new Date(), dir)).not.toThrow()
+      // No open interval existed → nothing was written.
+      expect(existsSync(path())).toBe(false)
+    })
+
+    it('does not reopen or touch an already-closed interval', () => {
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      closePrivateInterval(new Date('2026-08-06T02:05:00.000Z'), dir)
+      closePrivateInterval(new Date('2026-08-06T02:09:00.000Z'), dir)
+      expect(onDisk().intervals[0].end).toBe('2026-08-06T02:05:00.000Z')
+    })
+  })
+
+  describe('resetToPublic', () => {
+    it('truncates to the empty public default', () => {
+      openPrivateInterval(new Date(), dir)
+      resetToPublic(dir)
+      expect(onDisk()).toEqual({ version: 1, intervals: [] })
+      expect(isPrivate(readPrivacyState(dir))).toBe(false)
+    })
+  })
+
+  describe('atomic writes', () => {
+    it('leaves no temp file behind after a write', () => {
+      openPrivateInterval(new Date(), dir)
+      closePrivateInterval(new Date(), dir)
+      // Exactly one file — the state file — no lingering `.tmp`/`.new` sibling.
+      const entries = readdirSync(dir)
+      expect(entries).toEqual(['privacy-state.json'])
+    })
+
+    it('a concurrent reader only ever sees a complete document', () => {
+      // Because the write is rename-based, the file at the destination path is
+      // always a fully-formed JSON doc — parsing it after any op never throws.
+      openPrivateInterval(new Date('2026-08-06T02:00:00.000Z'), dir)
+      expect(() => JSON.parse(readFileSync(path(), 'utf8'))).not.toThrow()
+      closePrivateInterval(new Date('2026-08-06T02:05:00.000Z'), dir)
+      expect(() => JSON.parse(readFileSync(path(), 'utf8'))).not.toThrow()
+    })
+  })
+})