switchroom 0.18.6 → 0.18.8

package/telegram-plugin/gateway/pending-card-store.ts

@@ -0,0 +1,173 @@
+/**
+ * Persistence store for in-flight AGENT-INITIATED approval cards that park
+ * the requesting agent until the operator taps: `vault_request_access`,
+ * `vault_request_save`, `request_secret`, and `mental_model_propose`.
+ *
+ * Problem (mirror of the permission-card `permission-card-store.ts` bug): the
+ * gateway holds each staged request in an in-memory Map only
+ * (`pendingVaultRequestAccesses`, `pendingVaultRequestSaves`,
+ * `pendingSecretRequests`, `pendingMentalModelProposes`). When the gateway
+ * restarts (crash OR container restart), every entry is lost. The card in
+ * Telegram keeps its live inline keyboard, so when the operator taps it later
+ * they hit the "Card expired — ask the agent to re-request" tombstone: no
+ * grant, no injected inbound, and the agent that ended its turn to WAIT on the
+ * card stays parked forever.
+ *
+ * Fix: persist the METADATA for every posted card to a JSON file in STATE_DIR.
+ * On each resolution (tap / TTL-expire) remove the entry. On gateway boot,
+ * restore surviving entries into the in-memory maps so a post-restart tap on a
+ * still-valid (unexpired) card works exactly like a pre-restart tap.
+ *
+ * SECRETS HYGIENE — LOAD-BEARING: this file is written to disk unencrypted.
+ * It MUST NOT carry any secret VALUE. `vault_request_save` stages a secret
+ * value in gateway memory; only its key/metadata is persisted here (never the
+ * value), so a restored save card is re-associated with a tap but cannot
+ * complete the write — the caller degrades gracefully (tells the agent the
+ * value was lost to a restart). `request_secret` never holds a value at
+ * staging time (the value arrives after the tap), so its metadata is safe to
+ * persist. The "no value field" invariant is enforced by the record types
+ * below (PersistedVaultSaveCard has no `value` member, so a callsite can't
+ * compile one in) and pinned by the on-disk sentinel test in
+ * pending-card-store.test.ts.
+ *
+ * File format: JSON array of PersistedApprovalCard objects. Written
+ * synchronously (mode 0o600) to avoid interleaving on concurrent card posts;
+ * production rate is a handful of cards, so the file stays tiny.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The four agent-initiated approval-card families we persist. */
+export type ApprovalCardFamily =
+  | 'vault_request_access'
+  | 'vault_request_save'
+  | 'request_secret'
+  | 'mental_model_propose'
+
+interface BasePersistedCard {
+  family: ApprovalCardFamily
+  /** The staging id embedded in the card's callback_data (dedup + re-associate). */
+  stageId: string
+  /** Agent that requested (process.env.SWITCHROOM_AGENT_NAME). */
+  agent: string
+  /** Chat the card was rendered into; edited on tap / expiry. */
+  chatId: string
+  /** Card message id (filled after the card is sent). */
+  cardMessageId?: number
+  /** Forum topic the agent was working in, if any. */
+  threadId?: number
+  /** Unix-ms staging timestamp — the TTL clock. Preserved across restart. */
+  stagedAt: number
+}
+
+export interface PersistedVaultAccessCard extends BasePersistedCard {
+  family: 'vault_request_access'
+  key: string
+  scope: 'read' | 'write'
+  reason?: string
+  ttlSeconds: number
+}
+
+export interface PersistedVaultSaveCard extends BasePersistedCard {
+  family: 'vault_request_save'
+  key: string
+  kind: 'string' | 'binary'
+  why?: string
+  // NOTE: NO `value` — the staged secret never touches disk.
+}
+
+export interface PersistedSecretRequestCard extends BasePersistedCard {
+  family: 'request_secret'
+  key: string
+  reason?: string
+}
+
+export interface PersistedMentalModelCard extends BasePersistedCard {
+  family: 'mental_model_propose'
+  spec: {
+    name: string
+    source_query: string
+    refresh_after_consolidation?: boolean
+    max_tokens?: number
+  }
+  reason?: string
+}
+
+export type PersistedApprovalCard =
+  | PersistedVaultAccessCard
+  | PersistedVaultSaveCard
+  | PersistedSecretRequestCard
+  | PersistedMentalModelCard
+
+export interface PendingCardStore {
+  /** Record a newly-posted card. Idempotent on stageId (replaces in place). */
+  add(entry: PersistedApprovalCard): void
+  /** Remove the entry for this stageId (resolved — tap or TTL). */
+  remove(stageId: string): void
+  /** All persisted entries (for boot-time restore). */
+  loadAll(): PersistedApprovalCard[]
+  /** Delete the backing file entirely. */
+  clear(): void
+}
+
+export function createPendingCardStore(stateDir: string): PendingCardStore {
+  const filePath = join(stateDir, 'pending-approval-cards.json')
+
+  function read(): PersistedApprovalCard[] {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? (parsed as PersistedApprovalCard[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  function write(entries: PersistedApprovalCard[]): void {
+    try {
+      writeFileSync(filePath, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
+      // `mode` only applies when writeFileSync CREATES the file; an existing
+      // file keeps its prior perms. Re-assert 0600 on every write so the file
+      // can never stay laxer than intended.
+      chmodSync(filePath, 0o600)
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: pending-card-store write failed: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  return {
+    add(entry) {
+      const entries = read()
+      const idx = entries.findIndex(e => e.stageId === entry.stageId)
+      if (idx >= 0) {
+        entries[idx] = entry
+      } else {
+        entries.push(entry)
+      }
+      write(entries)
+    },
+
+    remove(stageId) {
+      const entries = read()
+      const filtered = entries.filter(e => e.stageId !== stageId)
+      if (filtered.length !== entries.length) {
+        write(filtered)
+      }
+    },
+
+    loadAll() {
+      return read()
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — that's fine.
+      }
+    },
+  }
+}

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -150,9 +150,19 @@ export function redeliverBufferedInbound(
  *  approvals, subagent handbacks, warmup, reaction triggers) all tag a
  *  `meta.source`; the user-message inbound built in gateway.ts sets none.
  *  Restricting to source-less inbounds keeps merge-on-drain away from the
- *  #1150 wake-up class entirely. */
+ *  #1150 wake-up class entirely.
+ *
+ *  Button taps (#271, `meta.button_callback`) are ALSO excluded even though
+ *  they carry no `meta.source`: `mergeRun` keeps only the anchor (last)
+ *  message's meta, so a tap merged with an adjacent buffered user text would
+ *  silently drop its `button_callback_data`/`button_text` whenever the text
+ *  is last — the agent would see the `[user tapped button: …]` line without
+ *  the machine-readable payload. Taps deliver individually. */
 function isMergeableUserInbound(msg: InboundMessage): boolean {
-  return msg.type === 'inbound' && (msg.meta == null || msg.meta.source == null)
+  return (
+    msg.type === 'inbound' &&
+    (msg.meta == null || (msg.meta.source == null && msg.meta.button_callback == null))
+  )
 }
 
 function inboundHasMedia(msg: InboundMessage): boolean {

package/telegram-plugin/gateway/resume-inbound-builder.ts

@@ -49,12 +49,127 @@ export function humanizeElapsed(ms: number): string {
   return `~${days} day${days === 1 ? '' : 's'}`
 }
 
+/**
+ * A sub-agent that was still in flight when the turn was interrupted. The
+ * gateway derives these from the registry (`listNonTerminalSubagentsForTurn`)
+ * — every non-terminal (`running` / `stalled`) worker of the interrupted turn.
+ * Kept to just the display fields so the builder stays pure (no SQLite import).
+ */
+export interface InterruptedSubagent {
+  /** Agent type / label (e.g. 'worker', 'researcher'). */
+  agentType?: string | null
+  /** Human-readable dispatch prompt / task description. */
+  description?: string | null
+  /** Current registry status ('running' | 'stalled'). Informational only. */
+  status?: string | null
+}
+
+/** Max chars of each sub-agent's dispatch prompt included in the inbound. */
+const SUBAGENT_PROMPT_MAX = 200
+/** Max number of sub-agents listed (the rest are summarised as a count). */
+const SUBAGENT_LIST_CAP = 10
+
+function truncatePrompt(s: string, max: number): string {
+  const t = s.trim()
+  if (t.length <= max) return t
+  // Codepoint-safe truncation: slice by code POINTS, not UTF-16 code units —
+  // a naive `.slice()` can split a surrogate pair (emoji, astral-plane CJK)
+  // and leave a lone surrogate that renders as U+FFFD in the inbound.
+  const points = Array.from(t)
+  if (points.length <= max) return t
+  return points.slice(0, max - 1).join('').trimEnd() + '…'
+}
+
+/**
+ * Render the compact "these workers died with the restart" block appended to
+ * an interrupted-turn inbound. Empty string when there were no in-flight
+ * sub-agents (so the inbound is unchanged in the common case). Bounded: at
+ * most `SUBAGENT_LIST_CAP` entries, each prompt truncated to
+ * `SUBAGENT_PROMPT_MAX` chars, with an overflow count for the remainder.
+ *
+ * The closing instruction is mode-aware, mirroring the two builders'
+ * contracts:
+ *   - `assertive: true` (the `resume_interrupted` path, whose inbound already
+ *     says "just resume") → imperative: re-dispatch the ones still needed
+ *     before declaring the task done.
+ *   - `assertive: false` (the `resume_watchdog_timeout` path — an ask-first
+ *     contract: "Do NOT silently resume … ask whether to retry") → deferred:
+ *     IF the user asks to retry, the workers will need re-dispatching. An
+ *     unconditional re-dispatch imperative here would contradict that
+ *     hang-safety gate.
+ */
+export function renderInterruptedSubagentsBlock(
+  subs: InterruptedSubagent[] | undefined,
+  opts: { assertive: boolean } = { assertive: true },
+): string {
+  if (!subs || subs.length === 0) return ''
+  const shown = subs.slice(0, SUBAGENT_LIST_CAP)
+  const lines = shown.map((s, i) => {
+    const type = s.agentType?.trim() ? s.agentType.trim() : 'sub-agent'
+    const desc = s.description?.trim()
+      ? truncatePrompt(s.description, SUBAGENT_PROMPT_MAX)
+      : '(no task description recorded)'
+    return `  ${i + 1}. [${type}] ${desc}`
+  })
+  const overflow =
+    subs.length > SUBAGENT_LIST_CAP
+      ? `\n  …and ${subs.length - SUBAGENT_LIST_CAP} more.`
+      : ''
+  const count = subs.length
+  const closing = opts.assertive
+    ? `\nRe-dispatch the ones still needed before declaring the task done — ` +
+      `don't assume their work landed.`
+    : `\nIf the user asks you to retry, they'll need re-dispatching — ` +
+      `don't assume their work landed.`
+  return (
+    `\n\nWhen the restart hit, ${count} sub-agent${count === 1 ? ' was' : 's were'} still ` +
+    `in flight. These sub-agents were killed by the restart and did NOT complete:\n` +
+    lines.join('\n') +
+    overflow +
+    closing
+  )
+}
+
 export interface ResumeInboundContext {
   /** The interrupted turn, straight from the registry. */
   turn: Turn
   /** Wall-clock ms. Drives `ts`, `messageId`, and the elapsed framing.
    *  Defaults to Date.now(). */
   nowMs?: number
+  /** Sub-agents that were still non-terminal when the turn was interrupted.
+   *  Rendered into the inbound so the resumed session knows what to
+   *  re-dispatch. Omitted / empty → the inbound is unchanged. */
+  subagents?: InterruptedSubagent[]
+}
+
+/**
+ * Machine-stable leading token shared by EVERY synthetic boot inbound this
+ * module mints (resume, watchdog-report, deferred-report). It is the anchor
+ * the loop-guard keys on: a turn whose `user_prompt_preview` starts with
+ * this string was itself started by a synthetic boot inbound, so building
+ * ANOTHER resume for it would replay already-resumed work and could chain
+ * unboundedly across repeated restarts.
+ *
+ * `extractUserPromptPreview` strips the `<channel …>` wrapper before storing
+ * the preview, so the stored text begins with this prose prefix (not the
+ * `meta.source` attribute, which the preview drops). Every builder below
+ * MUST keep this as the first characters of its `text`; `resume-inbound-
+ * builder.test.ts` pins that contract so a prose edit can't silently break
+ * the loop-guard.
+ */
+export const RESUME_SYNTHETIC_PROMPT_PREFIX = 'You just restarted.'
+
+/**
+ * Loop-guard predicate: was this interrupted turn ITSELF started by one of
+ * this module's synthetic boot inbounds? Detected via the stored
+ * `user_prompt_preview` prefix. Used at boot to cap the auto-resume chain at
+ * depth 1 — a resume turn that is itself interrupted is NOT re-resumed
+ * (which would double-execute the resumed side effects and could loop
+ * forever); the caller downgrades to a passive deferred-report instead.
+ */
+export function isResumeSyntheticTurn(turn: Turn): boolean {
+  const p = turn.user_prompt_preview
+  return typeof p === 'string' && p.startsWith(RESUME_SYNTHETIC_PROMPT_PREFIX)
 }
 
 function threadIdNum(turn: Turn): number | undefined {
@@ -131,7 +246,8 @@ export function buildResumeInterruptedInbound(ctx: ResumeInboundContext): Inboun
       `plain language) so they're not left wondering — then carry on with the ` +
       `actual task. Do not ask whether to resume; just resume. If even after ` +
       `reading the recent messages you genuinely can't tell what the work was, ` +
-      `say so and ask.`,
+      `say so and ask.` +
+      renderInterruptedSubagentsBlock(ctx.subagents),
     meta,
   }
 }
@@ -190,7 +306,129 @@ export function buildResumeWatchdogReportInbound(
       `after ${idle} of no progress, and roughly what it was doing. Then ask ` +
       `whether they want you to retry it or take a different angle. Report ` +
       `only the honest cause — no observable progress for that long — don't ` +
-      `speculate about a deeper root cause you can't see.`,
+      `speculate about a deeper root cause you can't see.` +
+      // Deferred (non-assertive) form: this is the ask-first path — the killed
+      // workers are listed as facts, but re-dispatch waits on the user's call.
+      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }),
+    meta,
+  }
+}
+
+/** Why an auto-resume was declined in favour of a passive notice. */
+export type ResumeDeferReason = 'clean-restart-suppressed' | 'loop-guard'
+
+/**
+ * The inbound the boot-resume block should mint for an interrupted turn:
+ *   - 'resume'           → active resume (buildResumeInterruptedInbound)
+ *   - 'report'           → watchdog report (buildResumeWatchdogReportInbound)
+ *   - 'defer-loop'       → loop-guard passive notice (deferred-report)
+ *   - 'defer-suppressed' → boot_resume:never passive notice (deferred-report)
+ *   - null               → nothing (turn finished cleanly)
+ */
+export type BootResumeKind = 'resume' | 'report' | 'defer-loop' | 'defer-suppressed' | null
+
+/**
+ * Pure boot-resume decision, extracted from the gateway so the precedence
+ * (esp. the bounded resume-chain loop-guard) is unit-testable without
+ * booting a gateway. Precedence, highest first:
+ *
+ *   1. loop-guard — the interrupted turn was ITSELF a synthetic resume/report
+ *      turn (`isResumeSyntheticTurn`). NEVER mint another resume for it: that
+ *      would replay already-partly-executed work and could chain
+ *      restart→resume→restart forever. The at-most-once `resumed_at` ledger
+ *      bounds each individual turn, but each resume spawns a NEW turn, so
+ *      without this the CHAIN is unbounded. Cap it at one auto-resume by
+ *      downgrading to a passive deferred-report ('defer-loop').
+ *   2. suppressed — `boot_resume: never` on a fresh clean restart. Downgrade
+ *      to a passive deferred-report ('defer-suppressed') — a notice, never
+ *      silence.
+ *   3. otherwise — the normal age/ended_via policy (`selectResumeBuilder`).
+ */
+export function decideBootResumeKind(args: {
+  pending: Turn
+  suppressed: boolean
+  ageMs: number
+  maxAgeMs: number
+}): BootResumeKind {
+  if (isResumeSyntheticTurn(args.pending)) return 'defer-loop'
+  if (args.suppressed) return 'defer-suppressed'
+  return selectResumeBuilder(args.pending.ended_via, {
+    ageMs: args.ageMs,
+    maxAgeMs: args.maxAgeMs,
+  })
+}
+
+/**
+ * Build the `resume_deferred` inbound — a passive notice delivered when the
+ * framework declines to AUTO-resume interrupted work but must NOT stay
+ * silent (silence when work was in flight is never acceptable). Two reasons:
+ *
+ *   - 'clean-restart-suppressed' — `session_continuity.boot_resume: never`
+ *     is set and the prior shutdown was a fresh, deliberate restart. Per
+ *     that opt-in posture we don't replay the work unprompted, but we still
+ *     tell the user what was in flight so they can ask us to continue.
+ *
+ *   - 'loop-guard' — the interrupted turn was ITSELF a synthetic resume/
+ *     report turn (see `isResumeSyntheticTurn`). Auto-resuming a resume that
+ *     was interrupted again risks an unbounded restart→resume→restart chain
+ *     and double-executed side effects, so we cap the chain: report instead
+ *     of resuming, and let the user decide whether to keep going.
+ *
+ * Like the watchdog report, this is a REPORT (source `resume_deferred`), not
+ * a resume: the agent must not silently pick the work back up. The text
+ * starts with RESUME_SYNTHETIC_PROMPT_PREFIX so a further restart during
+ * THIS turn is itself detected as a synthetic turn and stays capped.
+ */
+export function buildResumeDeferredReportInbound(
+  ctx: ResumeInboundContext & { reason: ResumeDeferReason },
+): InboundMessage {
+  const ts = ctx.nowMs ?? Date.now()
+  const elapsed = humanizeElapsed(ts - ctx.turn.started_at)
+  const threadId = threadIdNum(ctx.turn)
+  const meta: Record<string, string> = {
+    source: 'resume_deferred',
+    // Origin chat/topic as channel attributes so the report turn gets a
+    // currentTurn (progress card + silence-poke) and the notice lands in the
+    // topic the work lived in. Same rationale as the other builders.
+    chat_id: ctx.turn.chat_id,
+    ...(threadId != null ? { message_thread_id: String(threadId) } : {}),
+    resume_turn_key: ctx.turn.turn_key,
+    interrupted_via: ctx.turn.ended_via ?? 'restart',
+    defer_reason: ctx.reason,
+    started_at: String(ctx.turn.started_at),
+  }
+  if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  const cause =
+    ctx.reason === 'loop-guard'
+      ? `Your previous turn was ALREADY a resume of earlier interrupted work, ` +
+        `and it was interrupted again by another restart ${elapsed} ago. To ` +
+        `avoid an endless restart→resume loop (and re-running work that may ` +
+        `have already partly executed), the framework has stopped ` +
+        `auto-resuming this chain.`
+      : `Your previous turn was interrupted ${elapsed} ago by a deliberate ` +
+        `restart, before it finished. This agent is configured NOT to ` +
+        `auto-resume work across deliberate restarts (boot_resume: never), so ` +
+        `it was not replayed automatically.`
+  return {
+    type: 'inbound',
+    chatId: ctx.turn.chat_id,
+    ...(threadId != null ? { threadId } : {}),
+    messageId: ts,
+    user: 'switchroom',
+    userId: 0,
+    ts,
+    text:
+      `${RESUME_SYNTHETIC_PROMPT_PREFIX} ${cause}` +
+      promptClause(ctx.turn) +
+      ` Do NOT silently resume it. Instead, briefly tell the user what was in ` +
+      `flight (call get_recent_messages for this chat if you need the full ` +
+      `original request — the quoted preview is only the first ~200 ` +
+      `characters), then ask whether they want you to pick it back up or drop ` +
+      `it. If you genuinely can't tell what the work was, say so and ask.` +
+      // Deferred (non-assertive) form, same as the watchdog path: this is an
+      // ask-first inbound — killed workers are named as facts, but
+      // re-dispatch waits on the user's call.
+      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }),
     meta,
   }
 }

package/telegram-plugin/gateway/session-model-file.ts

@@ -0,0 +1,198 @@
+/**
+ * Durable session-model stickiness — file helpers shared by the gateway.
+ *
+ * Two files in the bind-mounted agent state dir carry the contract
+ * (reference/rfcs/session-model-stickiness.md):
+ *
+ *   - `.session-model` — the DURABLE session override written on every
+ *     positively-confirmed `/model` switch. One-line JSON
+ *     `{"model","configuredDefaultAtWrite","ts"}`. It is NOT consumed by a
+ *     keep-path boot; start.sh deletes it on revert / invalidation /
+ *     corruption / 7-day staleness, and the gateway deletes it on
+ *     `/model default`.
+ *
+ *   - `.relaunch-model-intent` — the ONE-SHOT intent bit for the next boot.
+ *     One-line JSON `{"intent":"keep"|"revert","reason","ts"}`, atomic
+ *     write, last-writer-wins. Boot default is REVERT (operator decision:
+ *     a raw `docker restart` / host reboot / crash must revert to the yaml
+ *     model), so every switchroom-managed KEEP path must stamp keep-intent
+ *     BEFORE the bounce. start.sh consumes it (rm -f) every boot; a stale
+ *     (>10 min by the embedded ts) or corrupt intent counts as no intent.
+ *
+ * The `model` token is always a canonical `claude --model` token (alias,
+ * `claude-*` id, or `sr-*` id) — NEVER a display label like "Opus 4.8".
+ * Shape-gated on write with the same regex start.sh greps with.
+ */
+
+import { readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { isValidModelArg } from './model-command.js'
+
+export const SESSION_MODEL_FILE = '.session-model'
+export const RELAUNCH_MODEL_INTENT_FILE = '.relaunch-model-intent'
+export const CONFIGURED_DEFAULT_MODEL_FILE = '.configured-default-model'
+
+export type RelaunchModelIntent = 'keep' | 'revert'
+
+export interface SessionModelRecord {
+  model: string
+  configuredDefaultAtWrite: string
+  ts: number
+}
+
+/**
+ * Restart reasons whose semantics are "revert the session model to the
+ * configured default". Everything else `triggerSelfRestart` fires with is a
+ * switchroom-managed relaunch (watchdog recovery, drain-cap bounce,
+ * turn-complete deferred restart, fleet-fallback resume, sr-to-claude model
+ * switch, grant restarts) and KEEPS the override — the whole point of the
+ * stickiness contract. Enumerated in the RFC §3; default-keep here is safe
+ * because only gateway code calls triggerSelfRestart, and a bounce nobody
+ * stamped (crash, raw docker restart, deploy) reverts by boot default anyway.
+ */
+const REVERT_RESTART_REASONS: ReadonlySet<string> = new Set(['inline-button-restart'])
+
+/** Classify a triggerSelfRestart reason into the intent the boot should honor. */
+export function intentForRestartReason(reason: string): RelaunchModelIntent {
+  return REVERT_RESTART_REASONS.has(reason) ? 'revert' : 'keep'
+}
+
+function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmp, content, 'utf8')
+  renameSync(tmp, path)
+}
+
+/** Serialize a `.session-model` record (one line + trailing newline). */
+export function serializeSessionModel(rec: SessionModelRecord): string {
+  return `${JSON.stringify({
+    model: rec.model,
+    configuredDefaultAtWrite: rec.configuredDefaultAtWrite,
+    ts: rec.ts,
+  })}\n`
+}
+
+/**
+ * Parse `.session-model` content. Returns null on corrupt JSON, a missing /
+ * non-string field, or a model token that fails the MODEL_ARG_RE shape gate
+ * (never trust an unvalidated string near `claude --model`).
+ */
+export function parseSessionModel(text: string): SessionModelRecord | null {
+  try {
+    const raw = JSON.parse(text) as Partial<SessionModelRecord>
+    if (
+      typeof raw.model !== 'string' ||
+      typeof raw.configuredDefaultAtWrite !== 'string' ||
+      typeof raw.ts !== 'number' ||
+      !isValidModelArg(raw.model)
+    ) {
+      return null
+    }
+    return { model: raw.model, configuredDefaultAtWrite: raw.configuredDefaultAtWrite, ts: raw.ts }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write the durable session override. Throws on a non-canonical token —
+ * callers must pass a `claude --model` token, never a display label
+ * (regression guard for the "Opus 4.5 persisted" class).
+ */
+export function writeSessionModelFile(
+  agentDir: string,
+  model: string,
+  configuredDefaultAtWrite: string,
+): void {
+  if (!isValidModelArg(model)) {
+    throw new Error(`refusing to persist non-canonical session model token: ${JSON.stringify(model)}`)
+  }
+  atomicWrite(
+    join(agentDir, SESSION_MODEL_FILE),
+    serializeSessionModel({ model, configuredDefaultAtWrite, ts: Date.now() }),
+  )
+}
+
+/** Raw file text (for rollback snapshots), or null when absent/unreadable. */
+export function readSessionModelFileRaw(agentDir: string): string | null {
+  try {
+    return readFileSync(join(agentDir, SESSION_MODEL_FILE), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** Parsed durable override, or null when absent/corrupt. */
+export function readSessionModelFile(agentDir: string): SessionModelRecord | null {
+  const raw = readSessionModelFileRaw(agentDir)
+  return raw == null ? null : parseSessionModel(raw)
+}
+
+/** Delete the durable override (`/model default`, rollback). Best-effort. */
+export function clearSessionModelFile(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Restore a rollback snapshot taken with readSessionModelFileRaw. */
+export function restoreSessionModelFileRaw(agentDir: string, raw: string | null): void {
+  if (raw == null) {
+    clearSessionModelFile(agentDir)
+    return
+  }
+  try {
+    atomicWrite(join(agentDir, SESSION_MODEL_FILE), raw)
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Stamp the one-shot relaunch intent. MUST be called synchronously BEFORE
+ * the restart signal/dispatch it describes (write-before-kill invariant —
+ * the next start.sh boot reads this to decide keep vs revert). Best-effort:
+ * a failed write means the boot falls back to the default (revert), which
+ * is the safe side.
+ */
+export function writeRelaunchModelIntent(
+  agentDir: string,
+  intent: RelaunchModelIntent,
+  reason: string,
+): void {
+  try {
+    atomicWrite(
+      join(agentDir, RELAUNCH_MODEL_INTENT_FILE),
+      `${JSON.stringify({ intent, reason, ts: Date.now() })}\n`,
+    )
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: relaunch-model-intent write failed (boot will revert): ${(err as Error)?.message ?? String(err)}\n`,
+    )
+  }
+}
+
+/** Remove a stamped intent (rollback of a failed dispatch). Best-effort. */
+export function clearRelaunchModelIntent(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * The resolved configured default start.sh recorded this boot
+ * (`.configured-default-model`, written before override resolution — the
+ * same resolver output the invalidation compare uses). Null when missing.
+ */
+export function readConfiguredDefaultModel(agentDir: string): string | null {
+  try {
+    const v = readFileSync(join(agentDir, CONFIGURED_DEFAULT_MODEL_FILE), 'utf8').trim()
+    return v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}