switchroom 0.20.10 → 0.20.12

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()
+    })
+  })
+})

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

@@ -0,0 +1,206 @@
+/**
+ * Per-session privacy state — the gateway side of the `/private` `/public`
+ * feature (switchroom private-mode).
+ *
+ * The operator can pause Hindsight auto-retain for a stretch of a session with
+ * `/private`, then resume it with `/public`. The pause is recorded here as a
+ * list of half-open time intervals in a small JSON state file that the Python
+ * retain side (`vendor/hindsight-memory`) reads to EXCLUDE any turn whose
+ * timestamp falls inside an interval from memory.
+ *
+ * ── The state-file contract (MUST match the Python reader exactly) ──────────
+ * Path: `${TELEGRAM_STATE_DIR}/privacy-state.json` (dir resolved the same way
+ * `src/cli/self-improve-stop.ts:resolveStateDir()` does). Schema:
+ *
+ *   { "version": 1,
+ *     "intervals": [
+ *       { "start": "2026-08-06T02:00:25.558Z", "end": "2026-08-06T02:05:10.100Z" },
+ *       { "start": "2026-08-06T02:10:00.000Z", "end": null }
+ *     ] }
+ *
+ * `end: null` = an OPEN interval = "private right now". At most one is open at
+ * a time. A missing file (or `{"intervals":[]}`) means public — the default.
+ * Timestamps are ISO-8601 via `new Date().toISOString()`.
+ *
+ * ── Invariants ──────────────────────────────────────────────────────────────
+ *   - All writes are ATOMIC (tmp + fsync + rename via `atomicWriteFileSync`),
+ *     so a crash mid-write can never leave the Python reader a torn file.
+ *   - All reads are BEST-EFFORT and never throw: a missing, unreadable, or
+ *     corrupt file resolves to the public default. Losing this state is
+ *     fail-safe (memory records rather than drops), so — unlike the security
+ *     stores — a corrupt file here is tolerated silently rather than
+ *     quarantined.
+ *   - `openPrivateInterval` / `closePrivateInterval` are IDEMPOTENT: a second
+ *     `/private` while already private is a no-op, and `/public` while already
+ *     public is a no-op.
+ */
+
+import { readFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { atomicWriteFileSync } from '../../src/util/atomic.js'
+
+/** One half-open privacy interval. `end: null` = still open ("private now"). */
+export interface PrivacyInterval {
+  start: string
+  end: string | null
+}
+
+/** The on-disk shape of `privacy-state.json`. */
+export interface PrivacyState {
+  version: 1
+  intervals: PrivacyInterval[]
+}
+
+/** The public (default) state — no private intervals. */
+export function emptyPrivacyState(): PrivacyState {
+  return { version: 1, intervals: [] }
+}
+
+// ── Loud, verbatim operator-facing strings ──────────────────────────────────
+// Exported so the gateway command handlers and the boot alert use the exact
+// wording the spec pins (and so tests assert against a single source).
+
+/** Reply to `/private`. */
+export const PRIVATE_ON_REPLY =
+  '🔒 Private mode ON — memory writing paused. Nothing said until /public is stored.'
+
+/** Reply to `/public`. */
+export const PUBLIC_REPLY =
+  '🔓 Public mode — memory writing resumed. The private stretch was excluded from memory.'
+
+/** Loud alert posted when a genuine session start reset a leftover open interval. */
+export const SESSION_RESET_ALERT =
+  '🔓 New session — memory writing is ON by default. Private mode from the previous session was reset.'
+
+/**
+ * Agent state dir — set by start.sh; resolved identically to
+ * `self-improve-stop.ts:resolveStateDir()` so the gateway writer and the
+ * Python reader agree on where `privacy-state.json` lives.
+ */
+export function resolvePrivacyStateDir(): string {
+  return (
+    process.env.TELEGRAM_STATE_DIR ??
+    join(homedir(), '.claude', 'channels', 'telegram')
+  )
+}
+
+/** Absolute path to the shared state file. */
+export function privacyStatePath(stateDir: string = resolvePrivacyStateDir()): string {
+  return join(stateDir, 'privacy-state.json')
+}
+
+/** True iff `v` is a well-formed interval object. */
+function isInterval(v: unknown): v is PrivacyInterval {
+  if (v === null || typeof v !== 'object') return false
+  const o = v as Record<string, unknown>
+  if (typeof o.start !== 'string') return false
+  return o.end === null || typeof o.end === 'string'
+}
+
+/**
+ * Read the current privacy state. BEST-EFFORT: a missing / unreadable /
+ * corrupt file resolves to the public default and NEVER throws. Only
+ * well-formed intervals survive; a partially-corrupt array is filtered down to
+ * its valid members rather than discarded wholesale.
+ */
+export function readPrivacyState(stateDir: string = resolvePrivacyStateDir()): PrivacyState {
+  try {
+    const raw = readFileSync(privacyStatePath(stateDir), 'utf8')
+    const parsed: unknown = JSON.parse(raw)
+    if (parsed === null || typeof parsed !== 'object') return emptyPrivacyState()
+    const rawIntervals = (parsed as Record<string, unknown>).intervals
+    if (!Array.isArray(rawIntervals)) return emptyPrivacyState()
+    return { version: 1, intervals: rawIntervals.filter(isInterval) }
+  } catch {
+    return emptyPrivacyState()
+  }
+}
+
+/**
+ * Atomically persist `state`. BEST-EFFORT: a write failure is logged to stderr
+ * and swallowed so a transient fs error can never crash a command handler or
+ * the boot path. (Losing the write is fail-safe — memory records the turn.)
+ */
+function writePrivacyState(state: PrivacyState, stateDir: string): void {
+  try {
+    mkdirSync(stateDir, { recursive: true })
+  } catch {
+    /* dir may already exist / be unwritable — the write below reports */
+  }
+  try {
+    atomicWriteFileSync(privacyStatePath(stateDir), JSON.stringify(state), 0o600)
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: privacy-state write failed: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+  }
+}
+
+/** True iff an interval is currently open ("private right now"). */
+export function isPrivate(state: PrivacyState): boolean {
+  return state.intervals.some(i => i.end === null)
+}
+
+/**
+ * Start a private stretch. IDEMPOTENT: if an interval is already open this is a
+ * no-op (a second `/private` doesn't stack).
+ */
+export function openPrivateInterval(
+  now: Date = new Date(),
+  stateDir: string = resolvePrivacyStateDir(),
+): void {
+  const state = readPrivacyState(stateDir)
+  if (isPrivate(state)) return
+  state.intervals.push({ start: now.toISOString(), end: null })
+  writePrivacyState(state, stateDir)
+}
+
+/**
+ * End the current private stretch. IDEMPOTENT: if no interval is open (already
+ * public) this is a no-op.
+ */
+export function closePrivateInterval(
+  now: Date = new Date(),
+  stateDir: string = resolvePrivacyStateDir(),
+): void {
+  const state = readPrivacyState(stateDir)
+  const open = state.intervals.find(i => i.end === null)
+  if (!open) return
+  open.end = now.toISOString()
+  writePrivacyState(state, stateDir)
+}
+
+/** Truncate the state file back to the public default. */
+export function resetToPublic(stateDir: string = resolvePrivacyStateDir()): void {
+  writePrivacyState(emptyPrivacyState(), stateDir)
+}
+
+/** Outcome of a session-start reset. */
+export interface SessionResetResult {
+  /** True iff an OPEN interval existed and was reset (a private→public transition). */
+  hadOpenInterval: boolean
+}
+
+/**
+ * Reset privacy to public at a GENUINE session start (cold boot / crash /
+ * planned restart / `/clear`). Always truncates the state file. If — and only
+ * if — an OPEN interval existed (the previous session ended still private),
+ * `onOpenIntervalReset` is invoked so the caller can post the loud alert. When
+ * the previous session was already public there is no transition, so no alert
+ * fires (silent reset).
+ *
+ * The alert is delegated to a callback rather than sent here so this module
+ * stays free of gateway/bot dependencies and unit-testable in isolation.
+ */
+export function resetPrivacyOnGenuineSessionStart(opts: {
+  stateDir?: string
+  onOpenIntervalReset?: () => void
+} = {}): SessionResetResult {
+  const stateDir = opts.stateDir ?? resolvePrivacyStateDir()
+  const hadOpenInterval = isPrivate(readPrivacyState(stateDir))
+  resetToPublic(stateDir)
+  if (hadOpenInterval) opts.onOpenIntervalReset?.()
+  return { hadOpenInterval }
+}