switchroom 0.18.3 → 0.18.7

package/telegram-plugin/dist/server.js

@@ -17160,6 +17160,21 @@ function createToolLabelSidecar(opts) {
 }
 var init_tool_label_sidecar = () => {};
 
+// model-label.ts
+function isModelSentinel(model) {
+  if (typeof model !== "string")
+    return true;
+  const m = model.trim();
+  if (m.length === 0)
+    return true;
+  if (m.startsWith("<"))
+    return true;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(m))
+    return true;
+  return false;
+}
+var init_model_label = () => {};
+
 // session-tail.ts
 import {
   closeSync,
@@ -17300,6 +17315,10 @@ function projectTranscriptLine(line) {
     if (!Array.isArray(content))
       return [];
     const events = [];
+    const mainModel = message?.model;
+    if (typeof mainModel === "string" && !isModelSentinel(mainModel)) {
+      events.push({ kind: "model", model: mainModel });
+    }
     const textEvents = projectAssistantTextBlocks(content, (text, blockIndex, lastInMessage) => ({ kind: "text", text, blockIndex, lastInMessage }));
     content.forEach((c, i) => {
       const ct = c.type;
@@ -17402,6 +17421,10 @@ function projectSubagentLine(line, agentId, state) {
     if (!Array.isArray(content))
       return [];
     const events = [];
+    const subModel = message?.model;
+    if (typeof subModel === "string" && !isModelSentinel(subModel)) {
+      events.push({ kind: "sub_agent_model", agentId, model: subModel });
+    }
     const textEvents = projectAssistantTextBlocks(content, (text, blockIndex, lastInMessage) => ({
       kind: "sub_agent_text",
       agentId,
@@ -17903,6 +17926,7 @@ var MAX_JSONL_LINE_BYTES, MAX_ERROR_TEXT_CHARS = 500;
 var init_session_tail = __esm(() => {
   init_operator_events();
   init_tool_label_sidecar();
+  init_model_label();
   MAX_JSONL_LINE_BYTES = 2 * 1024 * 1024;
 });
 

package/telegram-plugin/gateway/always-allow-persist-queue.ts

@@ -0,0 +1,438 @@
+/**
+ * Durable retry queue for the "🔁 Always allow" durable-persist flow
+ * (#1977, hardened in #2973).
+ *
+ * Problem (#2973): a `config_propose_edit` dispatch for an always-allow
+ * rule can fail for RETRYABLE reasons (a transient hostd error, a stale
+ * container-side config view producing `E_PATCH_APPLY_FAILED`, a rate
+ * limit with a structured `retry_after`) — today that failure is simply
+ * reported to the operator ("did NOT save") and the tap is lost; the rule
+ * only lands if the operator notices and re-taps after the next restart.
+ *
+ * Fix: on a retryable dispatch failure, enqueue `{agent, rule, ...}` here
+ * BEFORE giving up. The gateway drains this queue at boot (so a restart
+ * mid-persist doesn't lose the entry) and on a periodic timer. Each drain
+ * pass:
+ *   1. re-checks `isRulePersisted` against a FRESH config read first — if
+ *      the rule already landed (e.g. the original attempt actually
+ *      succeeded server-side but the ack was lost), dequeue as a no-op;
+ *   2. otherwise re-synthesizes the diff from that fresh read (fixes the
+ *      stale-view failure class) and redispatches;
+ *   3. on success, dequeues; on failure, backs off exponentially (honoring
+ *      a structured `retryAfterMs` when the failure supplies one) and
+ *      re-tries later;
+ *   4. once `attempts` reaches {@link MAX_ATTEMPTS} or the entry has aged
+ *      past {@link MAX_AGE_MS}, the entry is dropped and the caller is
+ *      told to post a LOUD terminal-failure notice (a new message, not a
+ *      card edit — card edits don't ping).
+ *
+ * HARD RULE (standing fleet rule, restated in #2973): nothing here may
+ * retry indefinitely. Bounds are enforced structurally, not just by
+ * convention — see {@link MAX_ATTEMPTS}, {@link MAX_AGE_MS}, and
+ * {@link MAX_QUEUE_SIZE} below, and the tests that pin them.
+ *
+ * File format mirrors `missed-approvals-store.ts`: a single bounded JSON
+ * array, written synchronously, mode 0o600.
+ *
+ * Failure semantics (hardened post-#2973 adversarial review): a failed
+ * READ degrades to an empty list — a corrupt/missing queue file is not
+ * fatal, it just means "nothing queued yet". A failed WRITE is a
+ * different story: silently swallowing it would mean `enqueue()` tells
+ * its caller "queued for retry" when nothing was actually persisted to
+ * disk, and a concurrent `recordAttempt()`/`remove()` would silently
+ * fail to advance the queue's on-disk state. So `write()` PROPAGATES
+ * (throws) on failure, and `enqueue()` / `recordAttempt()` / `remove()`
+ * let that throw reach their own caller rather than pretending the
+ * mutation landed. `drainAlwaysAllowPersistQueue` below catches around
+ * each entry so one entry's write failure can't take down the rest of
+ * the drain pass; callers in the gateway (the interactive "Always
+ * allow" tap path) are responsible for catching enqueue() failures and
+ * reflecting them in the operator-facing message rather than claiming
+ * success.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Hard cap on retry attempts per entry — never retry indefinitely. */
+export const MAX_ATTEMPTS = 5
+
+/** Hard cap on how long an entry may live in the queue before being
+ * dropped as terminally failed, regardless of attempts made. */
+export const MAX_AGE_MS = 24 * 60 * 60 * 1000 // 24h
+
+/** Bound the on-disk file even under a pathological failure storm. */
+export const MAX_QUEUE_SIZE = 50
+
+/** Base backoff for attempt 1; doubles each subsequent attempt (capped). */
+export const BASE_BACKOFF_MS = 60_000 // 1 minute
+
+/** Ceiling on the computed backoff, independent of attempt count. */
+export const MAX_BACKOFF_MS = 30 * 60_000 // 30 minutes
+
+export interface AlwaysAllowPersistEntry {
+  /** Dedup key — one live queue entry per (agent, rule) pair. */
+  id: string
+  agentName: string
+  rule: string
+  /** Human-readable grant description, for the terminal-failure notice. */
+  grantPhrase: string
+  /** Origin chat/thread, so a terminal-failure notice can be targeted
+   * (falls back to the operator broadcast allowlist if absent). */
+  chatId?: string
+  threadId?: number | null
+  attempts: number
+  createdAt: number
+  nextAttemptAt: number
+  lastError?: string
+}
+
+interface FileShape {
+  entries: AlwaysAllowPersistEntry[]
+}
+
+export interface AlwaysAllowPersistQueue {
+  /** Enqueue (or refresh) a failed persist for retry. Idempotent on
+   * `(agentName, rule)` — an existing entry is updated in place rather
+   * than duplicated. Serialized (via an in-process lock) relative to
+   * every other read-modify-write on the queue file, and REJECTS if the
+   * underlying write fails — callers must not treat a settled promise
+   * as "persisted" without checking for rejection. */
+  enqueue(entry: {
+    agentName: string
+    rule: string
+    grantPhrase: string
+    chatId?: string
+    threadId?: number | null
+    error?: string
+  }): Promise<void>
+  /** All entries currently due for a retry attempt (nextAttemptAt <= now),
+   * oldest first. Does NOT filter by attempts/age — callers should apply
+   * {@link isExhausted} to decide terminal-failure vs. retry. */
+  listDue(now?: number): AlwaysAllowPersistEntry[]
+  /** Every entry in the queue, regardless of due-ness. */
+  listAll(): AlwaysAllowPersistEntry[]
+  /** Record the outcome of a retry attempt for `id`. Serialized relative
+   * to `enqueue`/`remove`/other `recordAttempt` calls on the same queue
+   * file — never races a concurrent mutation into a lost update.
+   *  - `success: true` → dequeue.
+   *  - `success: false` → increment attempts, compute the next backoff
+   *    (honoring `retryAfterMs` when supplied), and re-persist — UNLESS
+   *    the entry is now exhausted (see {@link isExhausted}), in which case
+   *    it is dropped and the caller should have already emitted the
+   *    terminal-failure notice.
+   * REJECTS if the underlying write fails — the caller must not assume
+   * the state change was durably persisted just because this returned.
+   */
+  recordAttempt(
+    id: string,
+    outcome: { success: true } | { success: false; error: string; retryAfterMs?: number },
+  ): Promise<void>
+  /** Remove an entry outright (e.g. after emitting its terminal notice).
+   * Serialized like the other mutators; REJECTS if the write fails. */
+  remove(id: string): Promise<void>
+  /** Delete the backing file entirely. */
+  clear(): void
+}
+
+/** Stable id for a (agent, rule) pair — one live retry entry per pair. */
+export function makeEntryId(agentName: string, rule: string): string {
+  return `${agentName}::${rule}`
+}
+
+/** True when `entry` has exhausted its retry budget — attempts maxed OR
+ * aged out — and should be dropped with a terminal-failure notice rather
+ * than retried again. Pure so callers/tests can reason about the bound
+ * without needing the store. */
+export function isExhausted(entry: Pick<AlwaysAllowPersistEntry, 'attempts' | 'createdAt'>, now = Date.now()): boolean {
+  return entry.attempts >= MAX_ATTEMPTS || now - entry.createdAt >= MAX_AGE_MS
+}
+
+/**
+ * Exponential backoff with a hard ceiling, honoring a structured
+ * `retry_after` hint when the failure supplied one (never retries SOONER
+ * than that hint, but still respects {@link MAX_BACKOFF_MS}).
+ */
+export function computeBackoffMs(attempts: number, retryAfterMs?: number): number {
+  const exp = Math.min(BASE_BACKOFF_MS * 2 ** Math.max(0, attempts - 1), MAX_BACKOFF_MS)
+  if (retryAfterMs != null && retryAfterMs > 0) {
+    return Math.min(Math.max(exp, retryAfterMs), MAX_BACKOFF_MS)
+  }
+  return exp
+}
+
+export function createAlwaysAllowPersistQueue(
+  stateDir: string,
+  /** Injectable for tests to force a write failure (disk full / permissions /
+   * read-only fs) without real filesystem faults — we run as root in CI/
+   * containers, so chmod-based permission tricks don't reliably fail, and
+   * bun's test runner doesn't support mocking node:fs built-ins. */
+  writeFileSyncFn: typeof writeFileSync = writeFileSync,
+): AlwaysAllowPersistQueue {
+  const filePath = join(stateDir, 'always-allow-persist-queue.json')
+
+  // ── In-process mutex ──────────────────────────────────────────────────
+  // enqueue / recordAttempt / remove are each a read-modify-write cycle
+  // against the SAME file. Node is single-threaded, but these operations
+  // are exposed as async (their callers `await` a hostd round trip, a
+  // drain pass, etc.), so two calls CAN interleave across a microtask/
+  // macrotask boundary — a naive "read, mutate, write" per call is a
+  // classic lost-update race (#2973 pt.3): call A reads, call B reads the
+  // same pre-A-write snapshot, B writes, A writes — B's update vanishes.
+  // Fix: every read-modify-write against `filePath` is queued through this
+  // single promise chain, so at most one is ever in flight at a time,
+  // regardless of how many callers invoke enqueue/recordAttempt/remove
+  // "concurrently".
+  let lock: Promise<unknown> = Promise.resolve()
+  function withLock<T>(fn: () => T): Promise<T> {
+    const result = lock.then(fn, fn) // run fn even if the previous link rejected
+    // Swallow the rejection on the CHAIN (not on `result`) so one failed
+    // mutation doesn't wedge the lock for everything queued after it.
+    lock = result.catch(() => {})
+    return result
+  }
+
+  function read(): FileShape {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw) as Partial<FileShape>
+      return { entries: Array.isArray(parsed?.entries) ? parsed.entries : [] }
+    } catch {
+      return { entries: [] }
+    }
+  }
+
+  /** Unlike `read()`, a write failure is NOT swallowed — it propagates so
+   * the caller (enqueue/recordAttempt/remove) finds out its mutation did
+   * not actually land on disk (disk full, permissions, etc.) instead of
+   * silently proceeding as if it had. */
+  function write(f: FileShape): void {
+    writeFileSyncFn(filePath, JSON.stringify(f), { encoding: 'utf-8', mode: 0o600 })
+  }
+
+  return {
+    enqueue(args) {
+      return withLock(() => {
+        const id = makeEntryId(args.agentName, args.rule)
+        const f = read()
+        const now = Date.now()
+        const idx = f.entries.findIndex(e => e.id === id)
+        if (idx >= 0) {
+          // Already queued (e.g. a second tap failed the same way) — keep
+          // its attempt history/createdAt (age bound is from FIRST failure),
+          // just refresh the description fields and last error.
+          f.entries[idx] = {
+            ...f.entries[idx]!,
+            grantPhrase: args.grantPhrase,
+            chatId: args.chatId,
+            threadId: args.threadId,
+            lastError: args.error,
+          }
+        } else {
+          if (f.entries.length >= MAX_QUEUE_SIZE) {
+            // Bounded — drop the oldest to make room rather than growing
+            // without limit under a failure storm.
+            f.entries.sort((a, b) => a.createdAt - b.createdAt)
+            f.entries = f.entries.slice(f.entries.length - MAX_QUEUE_SIZE + 1)
+          }
+          f.entries.push({
+            id,
+            agentName: args.agentName,
+            rule: args.rule,
+            grantPhrase: args.grantPhrase,
+            chatId: args.chatId,
+            threadId: args.threadId,
+            attempts: 1,
+            createdAt: now,
+            nextAttemptAt: now + computeBackoffMs(1),
+            lastError: args.error,
+          })
+        }
+        write(f)
+      })
+    },
+
+    listDue(now = Date.now()) {
+      return read()
+        .entries.filter(e => e.nextAttemptAt <= now)
+        .sort((a, b) => a.nextAttemptAt - b.nextAttemptAt)
+    },
+
+    listAll() {
+      return read().entries
+    },
+
+    recordAttempt(id, outcome) {
+      return withLock(() => {
+        const f = read()
+        const idx = f.entries.findIndex(e => e.id === id)
+        if (idx === -1) return
+        if (outcome.success) {
+          f.entries.splice(idx, 1)
+          write(f)
+          return
+        }
+        const entry = f.entries[idx]!
+        const attempts = entry.attempts + 1
+        const updated: AlwaysAllowPersistEntry = {
+          ...entry,
+          attempts,
+          lastError: outcome.error,
+          nextAttemptAt: Date.now() + computeBackoffMs(attempts, outcome.retryAfterMs),
+        }
+        if (isExhausted(updated)) {
+          // Exhausted — drop it. The caller is responsible for having
+          // emitted (or being about to emit) the terminal-failure notice;
+          // this store only owns the bounded-retry bookkeeping.
+          f.entries.splice(idx, 1)
+        } else {
+          f.entries[idx] = updated
+        }
+        write(f)
+      })
+    },
+
+    remove(id) {
+      return withLock(() => {
+        const f = read()
+        const filtered = f.entries.filter(e => e.id !== id)
+        if (filtered.length !== f.entries.length) {
+          f.entries = filtered
+          write(f)
+        }
+      })
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — fine.
+      }
+    },
+  }
+}
+
+// ─── Drain ──────────────────────────────────────────────────────────────────
+
+/** Injected dependencies for {@link drainAlwaysAllowPersistQueue} — kept
+ * abstract so the drain loop is unit-testable without gateway/network/hostd
+ * deps. The gateway wires the real implementations at call sites. */
+export interface AlwaysAllowDrainDeps {
+  /** Read the CURRENT (fresh, not cached) config file text. Throwing here
+   * is treated as a retryable failure for the entry being processed. */
+  readConfigText(): string
+  /** Resolve the agent's current, fully-merged `tools.allow` list from the
+   * freshly-read config — used to no-op a retry whose rule already
+   * landed (e.g. the original dispatch actually succeeded). */
+  resolveAllowList(configText: string, agentName: string): string[]
+  isRulePersisted(allowList: string[], rule: string): boolean
+  /** Re-synthesize the diff from the fresh config text. Returns null if
+   * the agent block can no longer be located (treated as retryable —
+   * config may be mid-edit). */
+  synthesizeDiff(agentName: string, rule: string, configText: string): string | null
+  /** Dispatch the (re-synthesized) diff for durable persistence. */
+  dispatchConfigEdit(
+    entry: AlwaysAllowPersistEntry,
+    unifiedDiff: string,
+  ): Promise<{ ok: true } | { ok: false; error: string; retryAfterMs?: number }>
+  /** Called once for an entry that has exhausted its retry budget — the
+   * "loud terminal failure" requirement (#2973 pt.3). Must not throw. */
+  notifyTerminalFailure(entry: AlwaysAllowPersistEntry, reason: string): void
+  /** Optional logger sink (defaults to a no-op) — kept separate from
+   * stderr writes so tests can assert on it without capturing stdio. */
+  log?(line: string): void
+}
+
+/**
+ * Process every currently-due entry once. Safe to call at gateway boot
+ * (drains anything left over from a mid-persist restart) and on a
+ * periodic timer (~10 min in the gateway). Each entry is handled
+ * independently — one entry's dispatch throwing never blocks its
+ * siblings, and this function itself never throws.
+ */
+export async function drainAlwaysAllowPersistQueue(
+  queue: AlwaysAllowPersistQueue,
+  deps: AlwaysAllowDrainDeps,
+): Promise<void> {
+  const log = deps.log ?? (() => {})
+  const due = queue.listDue()
+  for (const entry of due) {
+    try {
+      let configText: string
+      try {
+        configText = deps.readConfigText()
+      } catch (err) {
+        recordFailure(entry, `config read failed: ${(err as Error).message}`)
+        continue
+      }
+
+      // Re-check FIRST: if the rule already landed (original attempt
+      // actually succeeded, or a concurrent tap persisted it), this is a
+      // no-op dequeue — never re-append and risk a duplicate rule.
+      const allowList = deps.resolveAllowList(configText, entry.agentName)
+      if (deps.isRulePersisted(allowList, entry.rule)) {
+        log(
+          `always-allow-persist-queue: rule already persisted, no-op dequeue agent=${entry.agentName} rule=${entry.rule}\n`,
+        )
+        await recordAttemptSafely(entry, { success: true })
+        continue
+      }
+
+      const diff = deps.synthesizeDiff(entry.agentName, entry.rule, configText)
+      if (diff == null) {
+        await recordFailure(entry, 'could not re-synthesize diff from fresh config read')
+        continue
+      }
+
+      const result = await deps.dispatchConfigEdit(entry, diff)
+      if (result.ok) {
+        log(
+          `always-allow-persist-queue: retry succeeded agent=${entry.agentName} rule=${entry.rule} attempts=${entry.attempts}\n`,
+        )
+        await recordAttemptSafely(entry, { success: true })
+      } else {
+        await recordFailure(entry, result.error, result.retryAfterMs)
+      }
+    } catch (err) {
+      // Never let one entry's unexpected throw take down the drain pass.
+      await recordFailure(entry, `unexpected error: ${(err as Error).message}`)
+    }
+  }
+
+  /** `queue.recordAttempt` now REJECTS on a write failure (disk full,
+   * permissions, …) rather than silently pretending the state change
+   * persisted. The drain loop must not let that reject take down the
+   * whole pass (or the other due entries) — log it and move on; the
+   * entry stays in whatever state the last successful write left it in,
+   * and will be picked up again on the next drain pass. */
+  async function recordAttemptSafely(
+    entry: AlwaysAllowPersistEntry,
+    outcome: { success: true } | { success: false; error: string; retryAfterMs?: number },
+  ): Promise<void> {
+    try {
+      await queue.recordAttempt(entry.id, outcome)
+    } catch (err) {
+      log(
+        `always-allow-persist-queue: recordAttempt write failed (state change NOT persisted) agent=${entry.agentName} rule=${entry.rule}: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  async function recordFailure(entry: AlwaysAllowPersistEntry, error: string, retryAfterMs?: number): Promise<void> {
+    const willBeExhausted = isExhausted({ attempts: entry.attempts + 1, createdAt: entry.createdAt })
+    log(
+      `always-allow-persist-queue: retry failed agent=${entry.agentName} rule=${entry.rule} attempts=${entry.attempts + 1} exhausted=${willBeExhausted} error=${error}\n`,
+    )
+    if (willBeExhausted) {
+      try {
+        deps.notifyTerminalFailure(entry, error)
+      } catch (notifyErr) {
+        log(
+          `always-allow-persist-queue: notifyTerminalFailure threw agent=${entry.agentName} rule=${entry.rule}: ${(notifyErr as Error).message}\n`,
+        )
+      }
+    }
+    await recordAttemptSafely(entry, { success: false, error, retryAfterMs })
+  }
+}

package/telegram-plugin/gateway/approval-timeout-inbound-builders.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure builders for the synthetic inbounds the gateway injects when an
+ * agent-initiated approval card TTL-expires with no operator tap — one per
+ * family: `vault_request_access`, `vault_request_save`, `request_secret`,
+ * `mental_model_propose`.
+ *
+ * Before this, the only way these families woke the parked agent was an
+ * explicit tap. A card that expired unanswered left the agent (which ended its
+ * turn to wait) parked forever. These builders mirror the tap-outcome builders
+ * in `vault-grant-inbound-builders.ts`, but carry TIMEOUT wording:
+ *
+ *   "This is a TIMEOUT, not a denial — you may re-request or degrade
+ *    gracefully."
+ *
+ * matching the permission-card timeout philosophy (#2411 / #2862) so the model
+ * can tell an expiry from a real denial and NOT spam an identical re-request
+ * into an absent operator.
+ *
+ * The `meta.source` string is load-bearing (the bridge keys on it) and each is
+ * distinct from its tap-outcome sibling. Pinned by
+ * `approval-timeout-inbound-builders.test.ts`.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+interface TimeoutInboundBase {
+  agent: string
+  /** Chat the card lived in — keeps the resumed turn on the same conversation. */
+  chatId: string
+  /** Forum topic, if the request came from one — so the resumed reply routes back. */
+  threadId?: number
+  stageId: string
+  /** TTL window in whole minutes, for the message copy. */
+  timeoutMinutes: number
+  nowMs?: number
+}
+
+function envelope(opts: {
+  chatId: string
+  threadId?: number
+  ts: number
+  text: string
+  source: string
+  agent: string
+  stageId: string
+  extraMeta?: Record<string, string>
+}): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: opts.chatId,
+    ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+    messageId: opts.ts,
+    user: 'vault-broker',
+    userId: 0,
+    ts: opts.ts,
+    text: opts.text,
+    meta: {
+      source: opts.source,
+      agent: opts.agent,
+      ...(opts.threadId != null ? { message_thread_id: String(opts.threadId) } : {}),
+      stage_id: opts.stageId,
+      ...(opts.extraMeta ?? {}),
+    },
+  }
+}
+
+/** `vault_request_access` card expired unanswered. */
+export function buildVaultAccessTimeoutInbound(
+  opts: TimeoutInboundBase & { key: string; scope: 'read' | 'write' },
+): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return envelope({
+    chatId: opts.chatId,
+    threadId: opts.threadId,
+    ts,
+    source: 'vault_grant_timeout',
+    agent: opts.agent,
+    stageId: opts.stageId,
+    extraMeta: { key: opts.key, scope: opts.scope },
+    text:
+      `⌛ Your vault access request for \`${opts.key}\` (scope=${opts.scope}) ` +
+      `timed out after ${opts.timeoutMinutes} min — the operator did not tap. ` +
+      `This is a TIMEOUT, not a denial. Pick a fallback for the original task ` +
+      `(tell the user, try a different approach, or skip the feature), or ` +
+      `re-request later if it still matters. Do NOT re-request in a loop.`,
+  })
+}
+
+/** `vault_request_save` card expired unanswered. */
+export function buildVaultSaveTimeoutInbound(
+  opts: TimeoutInboundBase & { key: string },
+): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return envelope({
+    chatId: opts.chatId,
+    threadId: opts.threadId,
+    ts,
+    source: 'vault_save_timeout',
+    agent: opts.agent,
+    stageId: opts.stageId,
+    extraMeta: { key: opts.key },
+    text:
+      `⌛ Your vault_request_save for \`${opts.key}\` timed out after ` +
+      `${opts.timeoutMinutes} min — the operator did not tap, so the secret was ` +
+      `NOT stored and \`vault:${opts.key}\` will not resolve. This is a TIMEOUT, ` +
+      `not a denial. Pick a fallback or re-request the save later. Do NOT loop.`,
+  })
+}
+
+/** `request_secret` card expired unanswered. */
+export function buildSecretRequestTimeoutInbound(
+  opts: TimeoutInboundBase & { key: string },
+): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return envelope({
+    chatId: opts.chatId,
+    threadId: opts.threadId,
+    ts,
+    source: 'secret_request_timeout',
+    agent: opts.agent,
+    stageId: opts.stageId,
+    extraMeta: { key: opts.key },
+    text:
+      `⌛ Your request_secret for \`${opts.key}\` timed out after ` +
+      `${opts.timeoutMinutes} min — the operator did not provide it. This is a ` +
+      `TIMEOUT, not a denial. Proceed without it, ask the user how they want to ` +
+      `handle the task, or re-request later. Do NOT re-request in a loop.`,
+  })
+}
+
+/** `mental_model_propose` card expired unanswered. */
+export function buildMentalModelProposeTimeoutInbound(
+  opts: TimeoutInboundBase & { name: string },
+): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return envelope({
+    chatId: opts.chatId,
+    threadId: opts.threadId,
+    ts,
+    source: 'mental_model_propose_timeout',
+    agent: opts.agent,
+    stageId: opts.stageId,
+    extraMeta: { name: opts.name },
+    text:
+      `⌛ Your mental_model_propose for \`${opts.name}\` timed out after ` +
+      `${opts.timeoutMinutes} min — the operator did not tap, so nothing was ` +
+      `declared. This is a TIMEOUT, not a denial. Re-propose later if it still ` +
+      `stands. Do NOT re-propose in a loop.`,
+  })
+}