switchroom 0.17.6 → 0.17.10

package/telegram-plugin/gateway/gateway.ts

@@ -12,7 +12,7 @@
 import { Bot, GrammyError, InlineKeyboard, InputFile, type Context, type Api } from 'grammy'
 import { run, type RunnerHandle } from '@grammyjs/runner'
 import type { ReactionTypeEmoji } from 'grammy/types'
-import { randomBytes } from 'crypto'
+import { randomBytes, createHash } from 'crypto'
 import { execFileSync, execSync, spawn } from 'child_process'
 import {
   readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync,
@@ -93,6 +93,20 @@ import {
 import { StatusReactionController } from '../status-reactions.js'
 import { DeferredDoneReactions } from '../reaction-defer.js'
 import { createWorkerActivityFeed, isWorkerActivityFeedEnabled } from '../worker-activity-feed.js'
+import {
+  detectMemoryLegibilityEvent,
+  isMemoryLegibilityEnabled,
+  renderMemoryLegibilityLine,
+  MemoryLegibilityStager,
+} from '../memory-legibility.js'
+import {
+  ConsolidationRateLimiter,
+  consolidationSignature,
+  detectConsolidationEvent,
+  isConsolidationLegibilityEnabled,
+  renderConsolidationLine,
+} from '../consolidation-legibility.js'
+import type { WebhookGatewayRecord } from '../../src/web/webhook-gateway-record.js'
 import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
 import type { PinState, DesiredPin } from '../status-pin.js'
 import { decidePinAction } from '../status-pin.js'
@@ -111,10 +125,25 @@ import {
   type PermissionCardRef,
 } from './permission-timeout.js'
 import { renderVaultRequestAccessCard } from './vault-request-access-card.js'
-import { createPermissionCardStore } from './permission-card-store.js'
+import { createPermissionCardStore, type PersistedPermCard } from './permission-card-store.js'
+import {
+  isPermissionRearmEnabled,
+  permissionRearmGraceMs,
+  classifyPermissionRequest,
+  computeBootSweepStripTargets,
+  distinctRequestIds,
+} from './permission-rearm.js'
+import { createMissedApprovalsStore, type MissedApproval } from './missed-approvals-store.js'
+import {
+  renderMissedApprovalsDigest,
+  missedApprovalsKeyboard,
+  parseMissedApprovalCallback,
+  buildMissedApprovalRetryInbound,
+} from './missed-approvals-card.js'
 import { pickRecoveredPermissionOrigin } from './permission-card-origin.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { appendActivityLabel, clipNarrative, renderActivityFeedWithNested, formatStepSuffix, type SessionActivityHeader } from '../tool-activity-summary.js'
+import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { REPLY_TOOLS, isDraftOfReply } from '../narrative-dedup.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
@@ -144,7 +173,7 @@ import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
 import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
 import * as pendingProgress from '../pending-work-progress.js'
-import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd } from '../silent-end.js'
+import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd, silentEndFallbackText, type SilentEndDeps } from '../silent-end.js'
 import { isFinalAnswerReply, isSubstantiveFinalReply, FINAL_ANSWER_MIN_CHARS } from '../final-answer-detect.js'
 import { deriveTurnRole, decideTerminalReason, parsePostAnswerLivenessMs, evaluatePostAnswerLiveness, type LoopRole } from '../turn-liveness-floor.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
@@ -224,15 +253,9 @@ import { validateStringArray } from './access-validator.js'
  */
 const REPLY_TO_TEXT_MAX = 200
 
-/**
- * #1161 — user-facing fallback delivered when a user-message turn ends
- * with zero outbound messages AND the deterministic Stop-hook re-prompt
- * has already been exhausted. Without this the user only sees the
- * progress card vanish; silence must never be the failure mode.
- */
-const SILENT_END_FALLBACK_TEXT =
-  '⚠️ The agent finished working but didn’t send a reply — your last ' +
-  'message may not have been answered. Please try asking again.'
+// #1161 silent-end fallback text now lives in ../silent-end.ts
+// (`silentEndFallbackText`, imported above) so the transport-boundary
+// tests exercise the real string — see PR #2892.
 import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
@@ -392,6 +415,13 @@ import {
   type StatusPinPersistOp,
   type TrackedStatusPin,
 } from './status-pin-store.js'
+import {
+  writeActivityCardRecord,
+  clearActivityCardRecord,
+  runActivityCardBootReaper,
+  restartOrphanCardFinalizeText,
+  type ActivityCardStoreFsSeam,
+} from './activity-card-store.js'
 import { driveEscalation } from './escalation-drive.js'
 import { shouldSuppressRepresent } from './represent-guard.js'
 import { shouldDeferEscalationForBridge } from './escalation-bridge-gate.js'
@@ -448,6 +478,12 @@ import {
   buildVaultSaveFailedInbound,
   buildVaultSaveDiscardedInbound,
 } from './vault-grant-inbound-builders.js'
+import { renderMentalModelProposeCard } from './mental-model-propose-card.js'
+import {
+  resolveMentalModelProposal,
+  type MentalModelPendingProposal,
+} from './mental-model-propose-resolve.js'
+import { readDeclaredMentalModelNames } from './mental-model-propose-diff.js'
 import {
   parseSkillProposalCallback,
   buildSkillProposalApplyInbound,
@@ -531,6 +567,8 @@ import {
   startSubagentWatcher,
   type SubagentWatcherHandle,
 } from '../subagent-watcher.js'
+import { listRecords as listWorktreeRecords } from '../../src/worktree/registry.js'
+import { ownedWorktreeCwds } from '../worktree-watch-cwds.js'
 import {
   startBootCard,
   resolvePersonaName,
@@ -551,7 +589,9 @@ import {
   recordScopedGrant,
   lookupScopedGrant,
   sweepScopedGrants,
+  countScopedGrants,
 } from '../scoped-approval.js'
+import { createScopedGrantStore } from './scoped-grant-store.js'
 import { grantRestartDecision, type GrantRestartDecision } from './grant-restart.js'
 import { synthesizeAllowRuleDiff, extractAddedAllowRule } from '../permission-diff.js'
 import {
@@ -666,6 +706,12 @@ process.on('beforeExit', () => {
 // ─── Env + state dir ──────────────────────────────────────────────────────
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const permCardStore = createPermissionCardStore(STATE_DIR)
+// #2862 — missed-approvals re-offer. Persisted list of approvals that
+// TTL-expired while the operator was away; a digest card is posted on the
+// operator's next activity. Kill switch: SWITCHROOM_MISSED_APPROVAL_REOFFER=0.
+const missedApprovalsStore = createMissedApprovalsStore(STATE_DIR)
+const MISSED_APPROVAL_REOFFER_ENABLED =
+  process.env.SWITCHROOM_MISSED_APPROVAL_REOFFER !== '0'
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
@@ -4579,6 +4625,131 @@ function clearPermissionTimeoutSuppression(reason: string): void {
     `telegram gateway: permission no-repeat suppression cleared (${n} sig(s)) — ${reason}\n`,
   )
 }
+
+// #2862 — missed-approvals re-offer digest. Called from every operator-activity
+// path that clears no-repeat suppression (inbound, /approve|/deny, card verdict):
+// on the FIRST activity after ≥1 approval TTL-expired while the operator was
+// away, post ONE compact digest card per origin surface listing the misses,
+// then promote those pending entries into a delivered-digest record (the posted
+// card is now the durable record in chat). Best-effort + fire-and-forget: never
+// blocks or throws into the hot inbound/callback path. Kill switch (=0) makes
+// this a no-op AND the auto-deny append below a no-op, so the whole feature is off.
+function maybePostMissedApprovalDigest(reason: string): void {
+  if (!MISSED_APPROVAL_REOFFER_ENABLED) return
+  const pending = missedApprovalsStore.listPending()
+  if (pending.length === 0) return
+  // Group by origin surface so each card lands where its cards were posted.
+  const groups = new Map<string, MissedApproval[]>()
+  for (const e of pending) {
+    const key = `${e.chatId}::${e.threadId ?? ''}`
+    const g = groups.get(key)
+    if (g) g.push(e)
+    else groups.set(key, [e])
+  }
+  for (const entries of groups.values()) {
+    const first = entries[0]
+    const chatId = first.chatId
+    const threadId = first.threadId ?? undefined
+    const digestId = randomBytes(4).toString('hex')
+    const text = renderMissedApprovalsDigest(entries, {
+      agentName: process.env.SWITCHROOM_AGENT_NAME ?? null,
+    })
+    void swallowingApiCall(
+      () =>
+        // allow-raw-bot-api: routed through swallowingApiCall retry policy; thread-aware digest card
+        bot.api.sendMessage(chatId, text, {
+          parse_mode: 'HTML',
+          reply_markup: missedApprovalsKeyboard(digestId),
+          ...(threadId != null && threadId !== 1 ? { message_thread_id: threadId } : {}),
+        }),
+      { chat_id: chatId, verb: 'missed-approval-digest', ...(threadId != null ? { threadId } : {}) },
+    )
+    // Promote synchronously (before the async send resolves) so a second
+    // operator-activity event racing in sees an empty pending list and can't
+    // double-post — "one card per accumulated batch" holds.
+    missedApprovalsStore.promoteToDigest({
+      digestId,
+      chatId,
+      threadId: first.threadId ?? null,
+      entries,
+      deliveredAt: Date.now(),
+    })
+  }
+  process.stderr.write(
+    `telegram gateway: missed-approval digest posted (${pending.length} entr(y/ies), ` +
+    `${groups.size} surface(s)) — ${reason}\n`,
+  )
+}
+
+// #2862 — handle a Retry / Dismiss tap on a missed-approvals digest card.
+//   missre:retry:<id>   — inject a synthetic inbound asking the agent to
+//                         re-attempt the actions (claude-native; re-raises a
+//                         fresh approval card). NEVER a verdict / re-execution.
+//   missre:dismiss:<id> — clear the record + edit the card closed.
+async function handleMissedApprovalCallback(ctx: Context, data: string): Promise<void> {
+  const senderId = String(ctx.from?.id ?? '')
+  const access = loadAccess()
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return
+  }
+  const parsed = parseMissedApprovalCallback(data)
+  if (parsed == null) {
+    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
+    return
+  }
+  const digest = missedApprovalsStore.getDigest(parsed.digestId)
+  if (digest == null) {
+    await ctx.answerCallbackQuery({ text: 'This digest already actioned or expired.' }).catch(() => {})
+    if (ctx.callbackQuery?.message) {
+      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
+    }
+    return
+  }
+
+  if (parsed.action === 'dismiss') {
+    missedApprovalsStore.removeDigest(parsed.digestId)
+    await ctx.answerCallbackQuery({ text: '🚫 Dismissed — cleared.' }).catch(() => {})
+    if (ctx.callbackQuery?.message && 'text' in ctx.callbackQuery.message) {
+      await ctx
+        .editMessageText(
+          `${escapeHtmlForTg(ctx.callbackQuery.message.text ?? '')}\n\n🚫 <i>Dismissed.</i>`,
+          { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  // Retry — consume the record, then inject a synthetic inbound to the ORIGIN
+  // surface asking the agent to re-attempt. This rides the same synthesized-
+  // inbound path cron uses; the agent naturally re-raises a fresh approval card.
+  missedApprovalsStore.removeDigest(parsed.digestId)
+  const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  const synthetic = buildMissedApprovalRetryInbound({
+    ctx: {
+      agent,
+      chat_id: digest.chatId,
+      ...(digest.threadId != null ? { threadId: digest.threadId } : {}),
+    },
+    actions: digest.entries.map(e => e.action),
+    operatorId: senderId,
+  })
+  const delivered = deliverResumeSyntheticOrBuffer(agent, synthetic)
+  await ctx.answerCallbackQuery({ text: '🔁 Asking the agent to retry…' }).catch(() => {})
+  if (ctx.callbackQuery?.message && 'text' in ctx.callbackQuery.message) {
+    await ctx
+      .editMessageText(
+        `${escapeHtmlForTg(ctx.callbackQuery.message.text ?? '')}\n\n🔁 <i>Retrying — asked the agent.</i>`,
+        { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+      )
+      .catch(() => {})
+  }
+  process.stderr.write(
+    `telegram gateway: missed-approval retry injection agent=${agent} ` +
+    `digest=${parsed.digestId} actions=${digest.entries.length} delivered=${delivered}\n`,
+  )
+}
 // Permission/approval-card origin recovery (marko Rentals-budget, 2026-06-17).
 // When `currentTurn` was force-closed by the orphaned-reply backstop but the
 // claude session kept running into a permission-gated tool, recover the card's
@@ -4612,13 +4783,54 @@ function sweepStaleAlwaysAllowCorrelations(now = Date.now()): void {
   }
 }
 
+// Sibling of pendingAlwaysAllowCorrelations for the agent-proposes →
+// human-approves MENTAL MODEL flow (hindsight Phase 5). When the operator
+// taps Approve on a mental-model PROPOSAL card, the gateway dispatches a
+// `config_propose_edit` appending the model to memory.mental_models[]; hostd
+// then calls back for operator approval. We pre-register the exact diff here
+// so that callback auto-approves WITHOUT a second card (the operator already
+// approved on the proposal card). Forge-resistance: the auto-resolve match is
+// an EXACT byte-match of the inbound diff against the diff the gateway itself
+// synthesized and queued — an agent-forged edit finds no entry and falls
+// through to a real operator card. Single-shot + a dedicated TTL sweep.
+//
+// TTL: this correlation must outlive the WHOLE config-edit approval budget,
+// NOT the 30s "always allow" window. The mental-model resolve dispatches
+// `config_propose_edit` to hostd with a 720s timeout (see the 720_000 dispatch
+// budgets below); hostd's approval callback can legitimately arrive any time
+// within that window if the operator taps slowly. Reusing the 30s
+// ALWAYS_ALLOW_CORRELATION_TTL_MS would sweep the correlation out from under a
+// slow-but-valid tap, dropping the auto-approve and surfacing a SECOND card
+// for an edit the operator already approved. Size it to the hostd budget.
+const MENTAL_MODEL_CORRELATION_TTL_MS = 720_000
+const pendingMentalModelCorrelations = new Map<string, { agentName: string; unifiedDiff: string; createdAt: number }>()
+function mentalModelCorrelationKey(agentName: string, unifiedDiff: string): string {
+  return `${agentName}::${createHash('sha256').update(unifiedDiff).digest('hex')}`
+}
+function sweepStaleMentalModelCorrelations(now = Date.now()): void {
+  for (const [key, entry] of pendingMentalModelCorrelations) {
+    if (now - entry.createdAt > MENTAL_MODEL_CORRELATION_TTL_MS) {
+      pendingMentalModelCorrelations.delete(key)
+    }
+  }
+}
+
 // Scoped-approval store: the 30-min window that backs the "✅ Allow" tap for
 // narrow non-destructive scopes (not a separate button — it IS what Allow
 // means for those). Operator-tapped, gateway-side ONLY (never pushed to the
 // bridge's untimed sessionAllowRules), fixed-window, fail-closed. Keyed by
 // agent name for per-agent isolation. All policy lives in
 // ../scoped-approval.ts (pure + unit-tested); this gateway only wires it.
-const scopedGrants: ScopedGrantStore = new Map()
+//
+// Persisted across gateway restarts (#2863): a bounce (fleet roll / config
+// apply / failover probe) used to wipe every window, re-carding an action the
+// operator allowed minutes ago. The store mirrors to a tiny STATE_DIR JSON
+// file; reload drops entries already past their ABSOLUTE expiry (a restart
+// never extends a window). Kill switch SWITCHROOM_SCOPED_GRANT_PERSIST=0 boots
+// empty and never writes. Fail-closed lookup semantics are unchanged — a
+// reloaded grant runs the same lookupScopedGrant gate as an in-memory one.
+const scopedGrantStore = createScopedGrantStore(STATE_DIR)
+const scopedGrants: ScopedGrantStore = scopedGrantStore.load(Date.now())
 const selfAgentName = (): string => process.env.SWITCHROOM_AGENT_NAME ?? ''
 
 // `ask_user` MCP tool — open prompts awaiting a user button-tap.
@@ -4944,6 +5156,81 @@ function sweepPendingVaultRequestAccesses(): void {
   }
 }
 
+/**
+ * Staged agent-initiated MENTAL MODEL proposal (hindsight Phase 5). The agent
+ * calls `mental_model_propose`; the operator taps Approve/Deny on the card.
+ * Mirrors PendingVaultRequestAccess — no memory content is staged here, only
+ * the proposed DECLARATION (name + source_query + optional knobs). On Approve
+ * the model becomes a first-class declared model in memory.mental_models[] via
+ * the operator-approved config-edit path; on Deny nothing is written.
+ */
+interface PendingMentalModelPropose {
+  agent: string
+  chat_id: string
+  card_message_id?: number
+  threadId?: number
+  /** Proposed declaration, snake_case (matches memory.mental_models[] schema). */
+  spec: {
+    name: string
+    source_query: string
+    refresh_after_consolidation?: boolean
+    max_tokens?: number
+  }
+  reason?: string
+  staged_at: number
+}
+const pendingMentalModelProposes = new Map<string, PendingMentalModelPropose>()
+const MENTAL_MODEL_PROPOSE_TTL_MS = approvalTtlMs()
+// Sweep expired pending proposals. For any entry past its TTL we ALSO edit the
+// posted card's keyboard away, so a stale card left in the chat can't be tapped
+// into a "Card expired" answer — the operator sees the ⌛ expiry inline instead.
+// Best-effort: card edits are fire-and-forget (the entry is removed regardless).
+function sweepPendingMentalModelProposes(): void {
+  const cutoff = Date.now() - MENTAL_MODEL_PROPOSE_TTL_MS
+  for (const [k, v] of pendingMentalModelProposes) {
+    if (v.staged_at < cutoff) {
+      pendingMentalModelProposes.delete(k)
+      if (v.card_message_id != null) {
+        void lockedBot.api
+          .editMessageText(
+            v.chat_id,
+            v.card_message_id,
+            richMessage('⌛ _This mental-model proposal card expired. Ask the agent to re-propose if it still stands._'),
+            { reply_markup: { inline_keyboard: [] } },
+          )
+          .catch(() => {})
+      }
+    }
+  }
+}
+
+// Sliding-window rate limit for mental-model proposals: at most
+// MENTAL_MODEL_PROPOSE_MAX_PER_WINDOW cards per MENTAL_MODEL_PROPOSE_WINDOW_MS.
+// The window is per-gateway-process, and since each agent runs its own gateway
+// process (keyed by $SWITCHROOM_AGENT_NAME), one process == one agent — so this
+// throttle is effectively per-agent. A candidate model is a deliberate, rare
+// curation act — an agent that re-proposes in a loop should be throttled so the
+// operator is never spammed.
+const mentalModelProposeTimes: number[] = []
+const MENTAL_MODEL_PROPOSE_WINDOW_MS = 60 * 60 * 1000
+const MENTAL_MODEL_PROPOSE_MAX_PER_WINDOW = 5
+// Mirror the memory.mental_models[] schema caps (src/config/schema.ts): a
+// source_query capped at 2000 chars and max_tokens capped at 8192. Enforced
+// up-front in executeMentalModelPropose so a proposal that would fail hostd
+// config validation never reaches an approval card.
+const MENTAL_MODEL_SOURCE_QUERY_MAX = 2000
+const MENTAL_MODEL_MAX_TOKENS_CAP = 8192
+function checkMentalModelProposeRate(now = Date.now()): { ok: true } | { ok: false; retryAtMs: number } {
+  const cutoff = now - MENTAL_MODEL_PROPOSE_WINDOW_MS
+  while (mentalModelProposeTimes.length > 0 && mentalModelProposeTimes[0]! < cutoff) {
+    mentalModelProposeTimes.shift()
+  }
+  if (mentalModelProposeTimes.length >= MENTAL_MODEL_PROPOSE_MAX_PER_WINDOW) {
+    return { ok: false, retryAtMs: mentalModelProposeTimes[0]! + MENTAL_MODEL_PROPOSE_WINDOW_MS }
+  }
+  return { ok: true }
+}
+
 /**
  * Mint an approval-kernel decision row for a deferred-secret card
  * (MIGRATION.md §1). Best-effort: if the kernel/broker is unreachable, we
@@ -5238,6 +5525,23 @@ const pendingStateReaper = setInterval(() => {
           now,
         )
       }
+      // #2862 — record the miss so it can be re-offered when the operator
+      // returns. Anchor to the card's own origin surface (where the operator
+      // would have tapped), so the digest lands in the same topic — not a
+      // fanned-out DM. Skip if the card was never posted anywhere.
+      if (MISSED_APPROVAL_REOFFER_ENABLED) {
+        const origin = v.cards[0]
+        if (origin != null) {
+          missedApprovalsStore.add({
+            requestId: k,
+            toolName: v.tool_name,
+            action: naturalAction(v.tool_name, v.input_preview),
+            chatId: origin.chatId,
+            threadId: origin.threadId ?? null,
+            timedOutAt: now,
+          })
+        }
+      }
       process.stderr.write(
         `telegram gateway: permission TTL expired — auto-deny request=${k} ` +
         `tool=${v.tool_name} (no operator response in ` +
@@ -5256,8 +5560,14 @@ const pendingStateReaper = setInterval(() => {
     if (now > v.expiresAt) vaultPassphraseCache.delete(k)
   }
   // Drop expired "⏱ 30 min" scoped grants. (Lookup already fails closed on
-  // expiry; this just keeps the map from accumulating dead entries.)
+  // expiry; this just keeps the map from accumulating dead entries.) Persist
+  // the removal so a restart between sweeps can't resurrect a swept grant —
+  // only write when the sweep actually changed something (sweeps only remove).
+  const scopedGrantsBefore = countScopedGrants(scopedGrants)
   sweepScopedGrants(scopedGrants, now)
+  if (countScopedGrants(scopedGrants) !== scopedGrantsBefore) {
+    scopedGrantStore.save(scopedGrants)
+  }
   for (const [k, v] of deferredSecrets) {
     if (now - v.staged_at > DEFERRED_SECRET_TTL_MS) deferredSecrets.delete(k)
   }
@@ -5754,6 +6064,22 @@ const statusPinStoreFs = {
 }
 const statusPinPersistEnabled = !STATIC && PIN_STATUS_WHILE_WORKING
 
+// Durable card-handle snapshot for the mid-turn activity card (Known Gap 1,
+// `reference/rfcs/deterministic-turn-liveness.md`). Persisted on card OPEN,
+// cleared on normal close/finalize; a boot-time reaper (wired alongside
+// `statusPinBootCleanup`, same startup-mutex ordering constraint) finalizes
+// any leftover record with one honest edit so a gateway restart mid-turn can
+// never leave the card frozen forever. STATIC mode skips disk (dry-run, no
+// durable volume) — same gate as the status-pin store.
+const ACTIVITY_CARD_STORE_PATH = join(STATE_DIR, 'activity-cards-pending.json')
+const activityCardStoreFs: ActivityCardStoreFsSeam = {
+  readFileSync: (p: string) => readFileSync(p, 'utf8'),
+  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  renameSync: (a: string, b: string) => renameSync(a, b),
+  existsSync: (p: string) => existsSync(p),
+}
+const activityCardPersistEnabled = !STATIC
+
 // Slot-banner pin persistence (#421 crash-recovery). The slot banner is pinned
 // in the owner chat when the agent is on a non-default OAuth slot. Rather than a
 // parallel store + second boot hook, its pin is persisted in the SAME
@@ -5835,6 +6161,75 @@ async function statusPinBootCleanup(): Promise<void> {
     )
   }
 }
+/**
+ * Boot-time orphan-card reaper (Known Gap 1,
+ * `reference/rfcs/deterministic-turn-liveness.md`). Thin gateway wrapper over
+ * the pure `runActivityCardBootReaper` — binds the live fs seam, a real
+ * Telegram edit, and the gateway logger. Finalizes ANY card left open by a
+ * prior (crashed/restarted) session with ONE honest edit — never a new
+ * message, so no ping. Guarantee is AT-MOST-ONCE: the pure routine deletes each
+ * record before attempting its edit and does not retry, so a failed edit
+ * forfeits that orphan rather than risk a double-finalize on a later boot (see
+ * the module doc in activity-card-store.ts for the full tradeoff). A benign-400
+ * (card already gone) is reported as `vanished`, not `finalized`.
+ *
+ * MUST run ONLY after this gateway wins the startup mutex (the store is a
+ * shared per-agent file; a losing double-boot would finalize a card the
+ * still-alive holder's in-flight turn still legitimately owns) — identical
+ * ordering constraint to `statusPinBootCleanup`.
+ *
+ * Deliberately does NOT attempt to resume climbing the old card: the resumed
+ * turn (if any) opens its own fresh card. Honest finalization, not
+ * resumption, is the goal (see the module doc in activity-card-store.ts).
+ *
+ * After the finalizing edit, also unpins the card, but ONLY for a record whose
+ * persisted `pinned` flag is true — i.e. the card was actually pin-eligible on
+ * open (`PIN_STATUS_WHILE_WORKING`). This unpin is DEFENSE-IN-DEPTH, not the
+ * primary unpin path: `statusPinBootCleanup` already unpins orphaned status
+ * pins from its own durable store on boot. The reaper's unpin is belt-and-
+ * braces for the case where the two stores disagree; the record's `pinned`
+ * flag must therefore reflect the ACTUAL pin outcome (see the open path), not
+ * an unconditional `true`, or the reaper would attempt an unpin on a card that
+ * was never pinned.
+ */
+async function activityCardBootReaper(): Promise<void> {
+  if (!activityCardPersistEnabled) return
+  const { finalized, vanished, unpinned, total } = await runActivityCardBootReaper({
+    path: ACTIVITY_CARD_STORE_PATH,
+    fs: activityCardStoreFs,
+    finalizeCard: (record) =>
+      robustApiCall(
+        () =>
+          lockedBot.api.editMessageText(
+            record.chatId,
+            record.activityMessageId,
+            richMessage(restartOrphanCardFinalizeText(record.startedAt)),
+            {},
+          ),
+        {
+          chat_id: record.chatId,
+          ...(record.threadId != null ? { threadId: record.threadId } : {}),
+          verb: 'activity-card.boot-reap-finalize',
+        },
+      ),
+    unpinCard: (record) =>
+      robustApiCall(
+        () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId),
+        {
+          chat_id: record.chatId,
+          ...(record.threadId != null ? { threadId: record.threadId } : {}),
+          verb: 'activity-card.boot-reap-unpin',
+        },
+      ),
+  })
+  if (total > 0) {
+    process.stderr.write(
+      `telegram gateway: activity-card: finalized ${finalized}/${total} ` +
+        `(vanished ${vanished}/${total}), unpinned ${unpinned}/${total} ` +
+        `orphaned card(s) from a prior session (at-most-once)\n`,
+    )
+  }
+}
 // NOTE: statusPinBootCleanup() is deliberately NOT invoked here at import time.
 // The status-pin store is a SHARED per-agent file, and cleanup issues real
 // unpinChatMessage calls. On a double-boot the losing gateway must NOT touch
@@ -6140,6 +6535,7 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
     // LOSING double-boot never unpins the live holder's legitimate pins.
     // Fire-and-forget: cleanup is best-effort and must not block boot.
     void statusPinBootCleanup()
+    void activityCardBootReaper()
   } catch (err) {
     process.stderr.write(
       `telegram gateway: boot.lock_acquire_failed err=${(err as Error).message} agent=${SWITCHROOM_AGENT_NAME}\n`,
@@ -6156,6 +6552,7 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
       // successful writePidFile here means no live holder was detected, so
       // running orphan cleanup is consistent with the pre-mutex behaviour.
       void statusPinBootCleanup()
+      void activityCardBootReaper()
     } catch (writeErr) {
       process.stderr.write(`telegram gateway: writePidFile failed: ${writeErr}\n`)
     }
@@ -6201,11 +6598,15 @@ function parsePositiveMsEnv(name: string, fallbackMs: number): number {
 }
 const SILENCE_FALLBACK_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FALLBACK_MS', 300_000)
 const SILENCE_FALLBACK_HARD_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FALLBACK_HARD_MS', 900_000)
-// #2527 — mid-turn liveness floor threshold (default 45s). The early, quiet
-// beat: a `user` turn working silently this long without a substantive answer
-// gets ONE honest "still on it" interim, so the ambient 👀 never masquerades
-// as "done". Strictly below SILENCE_FALLBACK_MS (the loud 300s unwedge).
-// Whole floor is kill-switchable via SWITCHROOM_TG_LIVENESS_FLOOR=0.
+// #2527 — mid-turn liveness floor threshold (default 45s). Still gates the
+// decision (`decideMidTurnFloor`, role + delivery + fire-once + timing) for a
+// `user` turn working silently this long without a substantive answer.
+// Phase 3 (deterministic-turn-liveness.md): the busy-but-silent case no
+// longer sends TEXT at this threshold — the climbing card (Phase 1) covers
+// it. The ONE surviving delivery gated by this threshold is the
+// approval-blocked re-ping (see `onMidTurnFloor` below). Strictly below
+// SILENCE_FALLBACK_MS (the loud 300s unwedge). Whole floor is
+// kill-switchable via SWITCHROOM_TG_LIVENESS_FLOOR=0.
 const SILENCE_FLOOR_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FLOOR_MS', 45_000)
 // #2527 — role-aware terminal reaction honesty (the "thumbs-up false done"
 // fix). Default ON; SWITCHROOM_TG_TERMINAL_HONESTY=0 reverts to always-👍.
@@ -6222,6 +6623,25 @@ const SILENCE_DEFER_INFLIGHT_TOOLS = process.env.SWITCHROOM_SILENCE_DEFER_INFLIG
 // and null currentTurn mid-work. Default ON; SWITCHROOM_SILENCE_LIVENESS_PRODUCTION=0
 // restores the legacy "only a real reply resets the clock" behaviour.
 const SILENCE_LIVENESS_PRODUCTION = process.env.SWITCHROOM_SILENCE_LIVENESS_PRODUCTION !== '0'
+// Sparse chat-legible memory (#2849, hindsight Phase 4). Surface ONE terse
+// line in the originating chat/topic when the interactive session materially
+// changes what it remembers (create_directive / invalidate / demote) — never
+// on ordinary recall or routine consolidation. Default ON;
+// SWITCHROOM_MEMORY_LEGIBILITY=0 disables it.
+const MEMORY_LEGIBILITY_ENABLED = isMemoryLegibilityEnabled(process.env.SWITCHROOM_MEMORY_LEGIBILITY)
+// Consolidation-driven legibility (#2849 follow-up, hindsight Phase 4). The
+// "updated what I know about Y" side, driven by the background
+// `consolidation.completed` webhook rather than a foreground tool call.
+// OPT-IN (default OFF), unlike MEMORY_LEGIBILITY_ENABLED above: this path is
+// fed by an unbounded background engine + a webhook the pinned hindsight image
+// does not yet emit, so the RFC keeps it "sparse … clearly gated".
+const CONSOLIDATION_LEGIBILITY_ENABLED = isConsolidationLegibilityEnabled(
+  process.env.SWITCHROOM_CONSOLIDATION_LEGIBILITY,
+)
+// One long-lived limiter across all consolidation events — collapses a burst
+// of material consolidations to at most one line per interval, and suppresses
+// an identical "updated about X" line inside the dedup window.
+const consolidationRateLimiter = new ConsolidationRateLimiter()
 
 /**
  * Feed-survival predicate — the single source of truth for "is this turn
@@ -6290,10 +6710,19 @@ silencePoke.startTimer({
     if (statusKey(turn.sessionChatId, turn.sessionThreadId) !== key) return null
     return { role: turn.role, finalAnswerDelivered: turn.finalAnswerDelivered }
   },
-  // #2527 — the early, quiet liveness beat. Honest text from the longest
-  // in-flight tool (model-free, claude-native), routed through the SAME send
-  // path as the 300s fallback; pings OFF (this is the gentle beat, not the
-  // loud unwedge) and the turn is NOT torn down — it keeps working.
+  // Phase 3 (reference/rfcs/deterministic-turn-liveness.md): the busy-but-
+  // silent TEXT floor is retired. The climbing card (Phase 1 — the 0-label
+  // branch of `feedHeartbeatTick` / `runSilentTurnHeartbeatTick` above) IS
+  // the mid-turn floor now: it edits the already-open activity card's
+  // elapsed clock every `FEED_HEARTBEAT_MIN_STALE_MS`, model-independent, no
+  // ping. This handler still decides/fires via `decideMidTurnFloor` (the
+  // timing + role + fire-once machinery in `silence-poke.ts` /
+  // `turn-liveness-floor.ts` is unchanged and still load-bearing — see
+  // below), but its ONLY surviving delivery is the approval-blocked re-ping.
+  // Do not re-add a generic "still working…" text send here believing this
+  // path covers the silent-tool case; it does not, and re-adding one would
+  // reintroduce the exact banned cadence ping `conversational-pacing.md`
+  // retired in #2667.
   onMidTurnFloor: async (ctx) => {
     // Late-fire guard, mirroring the fallback: a clean turn-end can race the
     // tick. If the turn is gone, stay silent.
@@ -6301,19 +6730,19 @@ silencePoke.startTimer({
     const blockedOnApproval = activeStatusReactions
       .get(statusKey(ctx.chatId, ctx.threadId))
       ?.isAwaiting() ?? false
+    // The one surviving text case: the turn is parked on an approval card
+    // waiting for YOUR tap. That's not a stall — it names the real blocker —
+    // so it keeps this quiet re-ping (`conversational-pacing.md` § Silence-
+    // poke fallback names this one of the two surviving honest cases). The
+    // busy-but-silent (non-approval) case sends nothing here; the card climb
+    // (Phase 1) is its only signal now.
+    if (!blockedOnApproval) return
     const text = silencePoke.formatFrameworkFallbackText(
       'working',
       ctx.silenceMs,
       ctx.inFlightTools,
       blockedOnApproval,
     )
-    // The stall-notice stop-gap is retired: `formatFrameworkFallbackText`
-    // returns null for the pure-liveness "still working / running <Tool>"
-    // beat (the only string it still emits is the approval-blocked re-ping).
-    // The early quiet floor beat existed ONLY to surface that stall notice, so
-    // with the notice gone there is nothing to send here unless the turn is
-    // parked on an approval card. Skip silently otherwise; the live draft +
-    // the model's own pacing beats carry progress.
     if (text == null) return
     try {
       await robustApiCall(
@@ -7283,6 +7712,81 @@ function dispatchPermissionVerdict(ev: PermissionEvent): void {
   }
 }
 
+/**
+ * #2861 re-arm: a `permission_request` re-sent by the bridge after a gateway
+ * restart, for a request_id that's NO LONGER in `pendingPermissions` but is
+ * still in the persisted card store. Restore the in-memory pending entry with
+ * the ORIGINAL `startedAt` (so the existing TTL clock keeps running from the
+ * original ask — an already-expired re-arm drops straight into the TTL
+ * auto-deny sweep, which correctly unwedges claude) and re-attach the inline
+ * keyboard on the EXISTING message(s) via editMessageText — never a new card.
+ *
+ * NEVER answers the card: only the question is restored (no-self-escalation).
+ */
+function rearmPermissionFromStore(
+  msg: PermissionRequestForward,
+  persisted: PersistedPermCard[],
+): void {
+  const { requestId, toolName, description, inputPreview } = msg
+  // Original clock: take the earliest persisted startedAt (all entries for one
+  // request share it, but be defensive).
+  const startedAt = persisted.reduce(
+    (min, c) => (c.startedAt < min ? c.startedAt : min),
+    persisted[0].startedAt,
+  )
+  const cardText = persisted[0].cardText
+  const cards = persisted.map(c => ({ chatId: c.chatId, messageId: c.messageId }))
+  pendingPermissions.set(requestId, {
+    tool_name: toolName,
+    description,
+    input_preview: inputPreview,
+    startedAt,
+    card_text: cardText,
+    cards,
+  })
+  process.stderr.write(
+    `telegram gateway: re-arming permission card(s) for request=${requestId} ` +
+    `tool=${toolName} (${cards.length} card(s), original startedAt preserved)\n`,
+  )
+  // Re-attach the keyboard on each surviving card message. Message-id-targeted
+  // edit — no thread needed, so THREAD_NOT_FOUND is not in the blast radius.
+  const showAlways = resolveScopedAllowChoices(toolName, inputPreview) != null
+  const keyboard = buildPermissionActionRow(requestId, showAlways)
+  for (const c of cards) {
+    void swallowingApiCall(
+      // allow-raw-bot-api: routed through swallowingApiCall (retry policy); message-id-targeted edit (no thread to lose). Re-attaches the Allow/Deny keyboard on the persisted card after a gateway restart.
+      () => bot.api.editMessageText(c.chatId, c.messageId, richMessage(cardText), { reply_markup: keyboard }),
+      { chat_id: c.chatId, verb: 'permission_request.rearm' },
+    )
+  }
+}
+
+/**
+ * Strip a single stale permission card: drop its keyboard and show the
+ * "gateway restarted" notice. Shared by the boot-sweep (immediate legacy path
+ * and the #2861 grace-period path). Best-effort — a deleted/inaccessible card
+ * is swallowed, never fatal.
+ */
+async function stripStalePermissionCard(card: PersistedPermCard): Promise<void> {
+  const toolLabel = card.toolName ?? 'unknown tool'
+  const notice = `🔒 **${toolLabel}**\n\n⚠️ *Gateway restarted — this request is no longer active. Ask your agent to try again if needed.*`
+  try {
+    // allow-raw-bot-api: targeted by message_id; no thread needed; fire-and-forget boot sweep
+    await bot.api.editMessageText(
+      card.chatId,
+      card.messageId,
+      richMessage(notice),
+      { reply_markup: { inline_keyboard: [] } },
+    )
+  } catch (err) {
+    // Card may already be deleted, edited, or in an inaccessible chat — benign
+    process.stderr.write(
+      `telegram gateway: boot-sweep: stale-card strip failed ` +
+      `${card.chatId}:${card.messageId}: ${(err as Error).message}\n`,
+    )
+  }
+}
+
 const ipcServer: IpcServer = createIpcServer({
   socketPath: SOCKET_PATH,
 
@@ -7652,6 +8156,38 @@ const ipcServer: IpcServer = createIpcServer({
 
   onPermissionRequest(_client: IpcClient, msg: PermissionRequestForward) {
     const { requestId, toolName, description, inputPreview } = msg
+    // #2861 idempotent re-send handling. The bridge re-sends every outstanding
+    // permission_request on each IPC (re)connect, so the same request_id can
+    // arrive more than once. Disposition:
+    //   duplicate → already live in pendingPermissions; ignore (no 2nd card).
+    //   rearm     → gone from memory (gateway restarted) but the persisted card
+    //               store still has it; restore + re-attach keyboard in place.
+    //   fresh     → new ask; fall through to the normal card-posting path.
+    // Either re-claim marks the id so the grace-period boot-sweep won't strip
+    // it. Kill switch SWITCHROOM_PERMISSION_REARM=0 skips this entirely (legacy
+    // behavior: a re-send would post a duplicate card, as before this fix).
+    if (isPermissionRearmEnabled()) {
+      const persisted = pendingPermissions.has(requestId)
+        ? []
+        : permCardStore.loadAll().filter(e => e.requestId === requestId)
+      const disposition = classifyPermissionRequest({
+        hasPending: pendingPermissions.has(requestId),
+        persistedCount: persisted.length,
+      })
+      if (disposition === 'duplicate') {
+        process.stderr.write(
+          `telegram gateway: permission_request duplicate re-send ignored ` +
+          `request=${requestId} (already pending)\n`,
+        )
+        return
+      }
+      if (disposition === 'rearm') {
+        // Re-arm restores the pending entry; the grace-period boot-sweep
+        // preserves anything live in pendingPermissions, so it won't strip it.
+        rearmPermissionFromStore(msg, persisted)
+        return
+      }
+    }
     // "⏱ 30 min" short-circuit: if the operator tapped a live scoped grant
     // covering this exact request, auto-allow without posting a card. CRITICAL:
     // dispatch WITHOUT a `rule` so the bridge does NOT cache it untimed
@@ -8180,11 +8716,24 @@ const ipcServer: IpcServer = createIpcServer({
         // field, or any other byte difference) won't match → falls
         // through to a real operator approval card.
         const added = extractAddedAllowRule(msg.unifiedDiff)
-        if (!added) return null
-        const key = `${msg.agentName}::${added}`
-        const entry = pendingAlwaysAllowCorrelations.get(key)
-        if (entry && entry.unifiedDiff === msg.unifiedDiff) {
-          pendingAlwaysAllowCorrelations.delete(key)
+        if (added) {
+          const key = `${msg.agentName}::${added}`
+          const entry = pendingAlwaysAllowCorrelations.get(key)
+          if (entry && entry.unifiedDiff === msg.unifiedDiff) {
+            pendingAlwaysAllowCorrelations.delete(key)
+            return 'approve'
+          }
+        }
+        // hindsight Phase 5: a mental-model PROPOSAL the operator already
+        // approved on the proposal card. The gateway pre-registered the EXACT
+        // diff; auto-approve on a byte-exact match (the security gate), so no
+        // second card is posted. Any forged/other edit finds no entry and
+        // falls through to a real operator card.
+        sweepStaleMentalModelCorrelations()
+        const mmKey = mentalModelCorrelationKey(msg.agentName, msg.unifiedDiff)
+        const mmEntry = pendingMentalModelCorrelations.get(mmKey)
+        if (mmEntry && mmEntry.unifiedDiff === msg.unifiedDiff) {
+          pendingMentalModelCorrelations.delete(mmKey)
           return 'approve'
         }
         return null
@@ -8317,11 +8866,45 @@ const ipcServer: IpcServer = createIpcServer({
     // frequent cron, or a crashed cron session) falls back to the MAIN agent
     // bridge so the fire lands now; it routes cheap again once the session is
     // up. See deliverInjectWithFallback.
+    // #2793 part B — durable cron boot-replay. A fire the scheduler is
+    // REPLAYING across a restart carries `meta.replay_fire_ms`; route it
+    // through the durable inbound spool so accept and consume are ledgered
+    // separately (mirrors the real-inbound path). The scheduler's own
+    // scheduler.jsonl records the fire at socket-accept, which stops
+    // findMissedFires from re-firing it — but a socket accept is NOT proof
+    // the session consumed it. Spooling here means: if the session isn't up
+    // (accepted-but-not-consumed), the entry stays un-acked and the spool's
+    // boot-replay re-delivers it on the next gateway boot (closes the
+    // silent-loss window); and the stable `spoolId` (keyed on the replayed
+    // fire) dedups a re-replay so it lands at most once (closes the
+    // double-fire window). Live cron ticks never set replay_fire_ms, so they
+    // keep the fire-and-forget path unchanged. STATIC mode has no spool —
+    // fall through to the legacy path.
+    const isDurableReplay =
+      inboundSpool != null &&
+      typeof msg.inbound.meta?.replay_fire_ms === 'string' &&
+      msg.inbound.meta.replay_fire_ms.length > 0
+    if (isDurableReplay && inboundSpool != null) {
+      // Durable ACCEPT: put before delivery so a crash between accept and
+      // consume leaves the entry recoverable (boot-replay re-delivers).
+      // Idempotent by stable spoolId — a re-replay of the same missed fire
+      // is a no-op while the prior entry is still un-acked.
+      inboundSpool.put(msg.agentName, msg.inbound as unknown as InboundMessage)
+    }
     const { target, delivered, fellBackToMain } = deliverInjectWithFallback(
       msg.agentName,
       msg.inbound.meta,
       (t) => ipcServer.sendToAgent(t, msg.inbound),
     )
+    if (isDurableReplay && inboundSpool != null && delivered) {
+      // Durable CONSUME: the fire reached a live bridge, so tombstone the
+      // spool entry (same "delivered to a live registered bridge" ack
+      // semantics the inbound spool uses — see its v1 scope note). On a
+      // miss we leave it un-acked: the pendingInboundBuffer.push below
+      // buffers it for the reconnect drain, and the durable spool copy is
+      // re-delivered on the next boot if this process dies first.
+      inboundSpool.ack(msg.inbound as unknown as InboundMessage)
+    }
     if (fellBackToMain) {
       process.stderr.write(
         `telegram gateway: cron fire fell back to main session (no cron bridge) agent=${msg.agentName} prompt_key=${promptKey}\n`,
@@ -8560,6 +9143,7 @@ const ipcServer: IpcServer = createIpcServer({
           {
             inject: webhookInject,
             log: (s) => process.stderr.write(`telegram gateway: ${s}`),
+            onConsolidation: surfaceConsolidationLegibility,
           },
         ),
     })
@@ -8681,6 +9265,7 @@ const ALLOWED_TOOLS = new Set([
   'vault_request_save',
   'vault_request_access',
   'request_secret',
+  'mental_model_propose',
   'linear_agent_activity',
   'linear_create_issue',
   'linear_agent_setup',
@@ -8727,6 +9312,8 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeVaultRequestAccess(args)
     case 'request_secret':
       return executeRequestSecret(args)
+    case 'mental_model_propose':
+      return executeMentalModelPropose(args)
     case 'linear_agent_activity':
       return executeLinearAgentActivity(args)
     case 'linear_create_issue':
@@ -11355,6 +11942,182 @@ async function executeVaultRequestAccess(args: Record<string, unknown>): Promise
   }
 }
 
+/** Read the live switchroom.yaml bytes for diff/dup-check. Mirrors the
+ *  always-allow persistence path's config read. */
+function readLiveSwitchroomConfigText(): string {
+  const cfgPath = process.env.SWITCHROOM_CONFIG ?? findSwitchroomConfigFile()
+  return readFileSync(cfgPath, 'utf8')
+}
+
+const MENTAL_MODEL_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/
+
+function buildMentalModelProposeKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Approve', callback_data: `mmp:approve:${stageId}` },
+        { text: '🚫 Deny', callback_data: `mmp:deny:${stageId}` },
+      ],
+    ],
+  }
+}
+
+/**
+ * `mental_model_propose` tool (hindsight Phase 5) — the agent surfaces a
+ * candidate mental model for the operator to approve. Mirrors the
+ * `vault_request_access` shape: the agent can only PROPOSE; the [Approve]/[Deny]
+ * tap is operator-gated (handleMentalModelProposeCallback), so an agent can
+ * never self-approve. On Approve the proposal is DECLARED — appended to the
+ * agent's memory.mental_models[] via the operator-approved config-edit path
+ * (reusing config_propose_edit apply+reconcile) — and ensured in the bank. On
+ * Deny nothing is written. Guardrails enforced here BEFORE any card:
+ * duplicate-name rejection against the agent's already-declared models, and a
+ * per-agent rate limit so proposals stay non-spammy.
+ */
+async function executeMentalModelPropose(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  const chat_id = String(args.chat_id ?? '')
+  if (!chat_id) throw new Error('mental_model_propose: chat_id is required')
+  const name = typeof args.name === 'string' ? args.name.trim() : ''
+  if (!name) throw new Error('mental_model_propose: name is required')
+  if (!MENTAL_MODEL_NAME_REGEX.test(name)) {
+    throw new Error('mental_model_propose: name must be a slug (letters/digits/_/-, ≤64 chars, e.g. `training-plan-state`)')
+  }
+  const source_query = typeof args.source_query === 'string' ? args.source_query.trim() : ''
+  if (!source_query) throw new Error('mental_model_propose: source_query is required')
+  // Enforce the memory.mental_models[] schema cap (src/config/schema.ts) up-front
+  // so the operator never approves a card that then fails hostd config validation.
+  // The 2000-char ceiling also keeps the rendered card under Telegram's 4096-char
+  // message limit.
+  if (source_query.length > MENTAL_MODEL_SOURCE_QUERY_MAX) {
+    throw new Error(
+      `mental_model_propose: source_query is ${source_query.length} chars; the schema caps it at ${MENTAL_MODEL_SOURCE_QUERY_MAX} (a standing reflection query, not a document). Shorten it.`,
+    )
+  }
+  // Accept `why` as an alias for `reason` (mirrors the vault tools).
+  const reason =
+    typeof args.reason === 'string' ? args.reason : typeof args.why === 'string' ? args.why : undefined
+  let refresh_after_consolidation: boolean | undefined
+  if (args.refresh_after_consolidation !== undefined) {
+    if (typeof args.refresh_after_consolidation !== 'boolean') {
+      throw new Error('mental_model_propose: refresh_after_consolidation must be a boolean')
+    }
+    refresh_after_consolidation = args.refresh_after_consolidation
+  }
+  let max_tokens: number | undefined
+  if (args.max_tokens !== undefined) {
+    const n = Number(args.max_tokens)
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error('mental_model_propose: max_tokens must be a positive integer')
+    }
+    // Enforce the schema ceiling (src/config/schema.ts) here so the card can't be
+    // approved into a config-validation failure downstream.
+    if (n > MENTAL_MODEL_MAX_TOKENS_CAP) {
+      throw new Error(
+        `mental_model_propose: max_tokens ${n} exceeds the schema cap of ${MENTAL_MODEL_MAX_TOKENS_CAP} (a mental model is a standing summary, not a corpus).`,
+      )
+    }
+    max_tokens = n
+  }
+  assertAllowedChat(chat_id)
+
+  const agentSlug = process.env.SWITCHROOM_AGENT_NAME || 'agent'
+
+  // Rate limit: a proposal is a rare, deliberate curation act — throttle so a
+  // looping agent can never spam the operator with cards.
+  const rate = checkMentalModelProposeRate()
+  if (!rate.ok) {
+    const retryAtIso = new Date(rate.retryAtMs).toISOString()
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `mental_model_propose: RATE-LIMITED (max ${MENTAL_MODEL_PROPOSE_MAX_PER_WINDOW} proposals/hour). ` +
+            `No card was posted. Next slot opens at ${retryAtIso}. Proposing mental models is meant to be ` +
+            `rare — batch or wait rather than re-firing.`,
+        },
+      ],
+    }
+  }
+
+  // Duplicate-name guard: reject a proposal for a model already DECLARED for
+  // this agent, BEFORE posting a card (the name is the idempotent-ensure key).
+  try {
+    const configText = readLiveSwitchroomConfigText()
+    const declared = readDeclaredMentalModelNames(configText, agentSlug)
+    if (declared.includes(name)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `mental_model_propose: '${name}' is ALREADY a declared mental model for ${agentSlug} ` +
+              `(memory.mental_models[]). No card was posted — it already exists and is ensured in your ` +
+              `bank. Pick a different name if you meant a NEW model, or just use the existing one.`,
+          },
+        ],
+      }
+    }
+  } catch (err) {
+    // Config read failed (transient) — fall through to the card. The approve
+    // path re-reads and re-checks (dupe guard is defense-in-depth), so a
+    // redundant card is harmless; suppressing a needed card is not.
+    process.stderr.write(`telegram gateway: mental_model_propose dup pre-check read failed: ${(err as Error).message}\n`)
+  }
+
+  const stageId = randomBytes(4).toString('hex')
+  const pending: PendingMentalModelPropose = {
+    agent: agentSlug,
+    chat_id,
+    spec: {
+      name,
+      source_query,
+      ...(refresh_after_consolidation !== undefined ? { refresh_after_consolidation } : {}),
+      ...(max_tokens !== undefined ? { max_tokens } : {}),
+    },
+    ...(reason ? { reason } : {}),
+    staged_at: Date.now(),
+  }
+  pendingMentalModelProposes.set(stageId, pending)
+  sweepPendingMentalModelProposes()
+
+  const text = renderMentalModelProposeCard({
+    agent: agentSlug,
+    name,
+    source_query,
+    ...(reason ? { reason } : {}),
+    ...(refresh_after_consolidation !== undefined ? { refresh_after_consolidation } : {}),
+  })
+  const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+  if (threadId != null) pending.threadId = threadId
+  const sent = await retryWithThreadFallback<{ message_id: number }>(
+    robustApiCall,
+    (tid) =>
+      lockedBot.api.sendRichMessage(chat_id, richMessage(text), {
+        reply_markup: buildMentalModelProposeKeyboard(stageId),
+        ...(tid != null && Number.isFinite(tid) ? { message_thread_id: tid } : {}),
+      }),
+    { threadId, chat_id, verb: 'mental_model_propose.card' },
+  )
+  pending.card_message_id = sent.message_id
+  // Only count a proposal against the rate budget once its card actually
+  // posted (validation errors / dupes don't consume the budget).
+  mentalModelProposeTimes.push(Date.now())
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text:
+          `mental_model_propose: card sent (stage_id=${stageId}, name=${name}). Wait for the operator to tap ` +
+          `Approve or Deny — END YOUR TURN cleanly. A fresh inbound arrives with the outcome ` +
+          `(source=mental_model_proposal_applied / mental_model_proposal_denied). Do NOT re-propose this ` +
+          `model while the card is open.`,
+      },
+    ],
+  }
+}
+
 async function executeReact(args: Record<string, unknown>): Promise<unknown> {
   if (!args.chat_id) throw new Error('react: chat_id is required')
   if (!args.message_id) throw new Error('react: message_id is required')
@@ -11924,6 +12687,31 @@ async function drainActivitySummary(
           )
           turn.activityMessageId = sent.message_id
           turn.activityEverOpened = true
+          // Known Gap 1 (deterministic-turn-liveness.md) — persist the
+          // minimal card handle the moment it opens, so a gateway restart
+          // mid-turn has something to finalize on next boot instead of
+          // leaving this card frozen forever. Fire-and-forget/best-effort:
+          // a failed persist degrades to the pre-fix (in-memory-only)
+          // behaviour, never blocks the card opening.
+          if (activityCardPersistEnabled) {
+            writeActivityCardRecord(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs, {
+              turnKey: statusKey(chat, thread),
+              chatId: chat,
+              threadId: thread ?? null,
+              activityMessageId: sent.message_id,
+              startedAt: turn.startedAt,
+              // Mirror the ACTUAL pin decision, not an unconditional `true`:
+              // the OPEN below silently-pins the fresh card only when
+              // `PIN_STATUS_WHILE_WORKING` is on (`reconcileStatusPin` no-ops
+              // when it's off, and can also fail on missing supergroup
+              // rights). Persisting `pinned: true` regardless would make the
+              // boot reaper attempt an unpin on a card that was never pinned.
+              // The reaper's unpin is defense-in-depth anyway
+              // (`statusPinBootCleanup` owns the primary unpin), so tracking
+              // the flag honestly is what matters here.
+              pinned: PIN_STATUS_WHILE_WORKING,
+            })
+          }
           // Status-pin: the per-turn status message just opened — it's the
           // in-flight "what it's doing" surface. Silently pin it so the turn
           // stays in view when the feed scrolls past. Keyed to the same
@@ -11968,11 +12756,15 @@ async function drainActivitySummary(
 }
 
 /**
- * Open (or climb) the minimal "Working…" liveness card for a 0-label turn once
- * it has been alive >= FEED_LIVENESS_OPEN_MS. The ONE place the liveness card
- * may OPEN — both the enqueue-time early-open timer
- * (`scheduleEarlyLivenessOpen`) and the 6 s heartbeat call through here, so a
- * card opened by one caller is a clean no-op for the other:
+ * OPEN the minimal "Working…" liveness card for a 0-label turn once it has been
+ * alive >= FEED_LIVENESS_OPEN_MS. The ONE place the liveness card may OPEN — both
+ * the enqueue-time early-open timer (`scheduleEarlyLivenessOpen`) and the 6 s
+ * heartbeat call through here, so a card opened by one caller is a clean no-op
+ * for the other. This function OPENS only; it does NOT climb an already-open card
+ * (its WHEN-gate `shouldEarlyOpenLiveness` returns false once `activityMessageId`
+ * is set). The 0-label CLIMB of an already-open card lives at the heartbeat call
+ * site via `silentTurnClimbRender` (deterministic-turn-liveness.md Phase 1) — so
+ * BOTH the labelled and the 0-label branches now keep the card visibly climbing.
  *   - `drainActivitySummary` OPENs when `activityMessageId == null` and EDITs
  *     once it is set, so a second call after an open just maintains the card;
  *   - the `mirrorLines.length === 0` guard at the heartbeat call site (and the
@@ -12157,13 +12949,45 @@ function feedHeartbeatTick(): void {
   // sends (opens) when activityMessageId is null and edits (maintains) once set
   // — so this one branch handles both the open and the climb.
   //
-  // The open/climb logic lives in ONE place (`openLivenessFeedIfDue`) so the
+  // The OPEN logic lives in ONE place (`openLivenessFeedIfDue`) so the
   // enqueue-time early-open timer (`scheduleEarlyLivenessOpen`) and this 6 s
   // heartbeat both reach the same drain — there is exactly one path that can
   // OPEN the liveness card, so the two callers can never double-open or race.
-  if (turn.mirrorLines.length === 0) {
-    openLivenessFeedIfDue(turn)
-    return
+  //
+  // Phase 1 climb (deterministic-turn-liveness.md): once the card IS open, the
+  // OPEN path no-ops (its WHEN-gate `shouldEarlyOpenLiveness` returns false for
+  // an already-open card) — which is exactly how the 0-label card used to FREEZE
+  // during a long silent tool. So split the two cases: OPEN when no card exists,
+  // and otherwise re-render the "Working…" card with a fresh wall-clock elapsed
+  // through the SAME cardDrainGate / mayDrain / liveness EDIT path the labelled
+  // branch below uses. Model-independent (reads only `now - startedAt`), so a
+  // blocked tool call can't starve it; edit-only, so it never push-notifies.
+  //
+  // The tick BODY lives in feed-heartbeat-climb.ts (`runSilentTurnHeartbeatTick`)
+  // so the shipped decision logic is directly under the outcome-based regression
+  // test (tests/silent-turn-climb-transport.test.ts) — this gateway IIFE cannot
+  // be imported in-process. This call site only wires the REAL deps; the wiring
+  // shape is pinned structurally by tests/feed-heartbeat-liveness-open.test.ts.
+  {
+    const ea = emissionAuthorityFor(turn)
+    const handled = runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: turn.mirrorLines.length,
+        activityMessageId: turn.activityMessageId,
+        labeledToolCount: turn.labeledToolCount,
+        ageMs: Date.now() - turn.startedAt,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      {
+        openLivenessFeedIfDue: () => openLivenessFeedIfDue(turn),
+        setPendingRender: (rendered) => { turn.activityPendingRender = rendered },
+        cardDrainGate: (run) => cardDrainGate(turn, ea, run),
+        mayDrain: () => ea.mayDrain(turn),
+        openOrEditCard: (apply) => ea.openOrEditCard('liveness', apply),
+        drain: () => { turn.activityInFlight = drainActivitySummary(turn, 'liveness') },
+      },
+    )
+    if (handled) return
   }
 
   // Labelled-feed heartbeat: keep a stale in-progress step visibly advancing.
@@ -12228,6 +13052,21 @@ function clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | nu
     if (turn.activityMessageId == null) return
     const id = turn.activityMessageId
     turn.activityMessageId = null
+    // Known Gap 1 (deterministic-turn-liveness.md) — the card is closing
+    // normally (about to be deleted or finalized below), so drop its durable
+    // handle too: a normal close must never leave a stale record for the
+    // boot reaper to "finalize" a message that's already been handled.
+    if (activityCardPersistEnabled) {
+      clearActivityCardRecord(
+        ACTIVITY_CARD_STORE_PATH,
+        activityCardStoreFs,
+        statusKey(chat, thread),
+        // Scope to this card's exact id (reap-race guard): only drop the row
+        // for the card THIS turn is closing, never a fresher card another
+        // turn may have already upserted under the same topic key.
+        id,
+      )
+    }
     if (CLEAR_STATUS_ON_COMPLETION) {
       try {
         await robustApiCall(
@@ -12269,6 +13108,175 @@ function clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | nu
   })
 }
 
+/**
+ * #2849 hindsight Phase 4 — sparse chat-legible memory.
+ *
+ * Fire-and-forget: if this main-agent tool call is a material memory
+ * operation (create_directive → 📌 remembered; invalidate/demote → ✂️
+ * forgot), send ONE terse real message into the turn's originating
+ * chat/topic. Routes on `turn.sessionChatId` / `turn.sessionThreadId`
+ * (the originating topic, never the operator DM), through
+ * `retryWithThreadFallback` so a deleted forum topic can't crash the
+ * gateway. Non-material tool calls return silently — no line on ordinary
+ * recall or routine consolidation. Kill-switch: SWITCHROOM_MEMORY_LEGIBILITY=0.
+ */
+/**
+ * Fix 1.3 (#2903): a memory-legibility line must render only AFTER the write
+ * is confirmed. We stage the detected event on `tool_use` (keyed by
+ * `toolUseId`) and flush the 📌/✂️ line on the matching SUCCESSFUL
+ * `tool_result` — a failed write (engine down / isError envelope) drops the
+ * staged line, so chat never claims "remembered" for a write that errored.
+ *
+ * A hindsight `tools/call` returns HTTP 200 + `is_error:true` on failure, and
+ * Claude Code surfaces that on the transcript `tool_result` block, which
+ * `session-tail` projects onto `ev.isError`. That is the confirmed-success
+ * signal we gate on.
+ */
+interface MemoryLegibilityRoute {
+  chatId: string
+  threadId: number | undefined
+  toolName: string
+}
+const memoryLegibilityStager = new MemoryLegibilityStager<MemoryLegibilityRoute>()
+
+function sendMemoryLegibilityLine(
+  event: NonNullable<ReturnType<typeof detectMemoryLegibilityEvent>>,
+  chatId: string,
+  threadId: number | undefined,
+): void {
+  const line = renderMemoryLegibilityLine(event)
+  void retryWithThreadFallback(
+    robustApiCall,
+    (tid) =>
+      bot.api.sendMessage(chatId, line, {
+        parse_mode: 'HTML',
+        // Status surface, not the user's answer — never ping the device.
+        disable_notification: true,
+        ...(tid != null ? { message_thread_id: tid } : {}),
+      }),
+    { threadId, chat_id: chatId, verb: 'memory-legibility.sendMessage' },
+  ).catch((err) => {
+    process.stderr.write(
+      `telegram gateway: memory-legibility send failed: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    )
+  })
+}
+
+/** Stage a material memory event observed on `tool_use`. Nothing is sent yet;
+ *  the line is flushed by `confirmMemoryLegibility` on a successful result. */
+function surfaceMemoryLegibility(
+  turn: CurrentTurn,
+  toolName: string,
+  toolUseId: string | null | undefined,
+  input: Record<string, unknown> | undefined,
+): void {
+  if (!MEMORY_LEGIBILITY_ENABLED) return
+  const event = detectMemoryLegibilityEvent(toolName, input)
+  if (event == null) return
+  const chatId = turn.sessionChatId
+  const threadId = turn.sessionThreadId
+  // Without a toolUseId we cannot correlate a result to confirm success. This
+  // effectively never happens (Claude Code always stamps a tool_use id), so
+  // rather than claim an unconfirmed "remembered", we skip and log.
+  if (toolUseId == null || toolUseId.length === 0) {
+    process.stderr.write(
+      `telegram gateway: memory-legibility ${event.kind} SKIPPED (no toolUseId) ` +
+        `chat=${chatId} tool=${toolName}\n`,
+    )
+    return
+  }
+  memoryLegibilityStager.stage(toolUseId, event, { chatId, threadId, toolName })
+  process.stderr.write(
+    `telegram gateway: memory-legibility ${event.kind} STAGED chat=${chatId} ` +
+      `thread=${threadId ?? '-'} tool=${toolName} id=${toolUseId}\n`,
+  )
+}
+
+/** Flush (or drop) a staged memory-legibility line on its matching
+ *  `tool_result`. Sends only on confirmed success; a failed write is dropped
+ *  so chat never claims "remembered" for a write that errored. */
+function confirmMemoryLegibility(
+  toolUseId: string | null | undefined,
+  isError: boolean | undefined,
+): void {
+  const resolved = memoryLegibilityStager.confirm(toolUseId, isError)
+  if (resolved == null) {
+    if (isError === true) {
+      process.stderr.write(
+        `telegram gateway: memory-legibility DROPPED (write errored) id=${toolUseId}\n`,
+      )
+    }
+    return
+  }
+  const { event, meta } = resolved
+  process.stderr.write(
+    `telegram gateway: memory-legibility ${event.kind} CONFIRMED chat=${meta.chatId} ` +
+      `thread=${meta.threadId ?? '-'} tool=${meta.toolName} id=${toolUseId}\n`,
+  )
+  sendMemoryLegibilityLine(event, meta.chatId, meta.threadId)
+}
+
+/**
+ * #2849 hindsight Phase 4 (follow-up) — consolidation-driven legibility.
+ *
+ * The gateway-side sink for a verified `hindsight` / `consolidation.completed`
+ * webhook. `recordWebhookEvent` has already logged the event for audit and
+ * resolved the agent's channel target; this decides whether it is MATERIAL
+ * (a genuine store/correct — else nothing), rate-limits it hard, and — only
+ * if it clears both gates — sends ONE terse "🧠 updated what I know about Y"
+ * real message with notifications suppressed. Never injects a model turn.
+ * OPT-IN via SWITCHROOM_CONSOLIDATION_LEGIBILITY.
+ */
+function surfaceConsolidationLegibility(
+  rec: WebhookGatewayRecord,
+  target: { chatId: string; threadId?: number },
+): void {
+  if (!CONSOLIDATION_LEGIBILITY_ENABLED) return
+  const event = detectConsolidationEvent(rec.payload)
+  if (event == null) return // routine no-op consolidation — surface nothing
+  const agent = rec.agent
+  // Rate-limiter clock MUST be wall-clock (Date.now()), never rec.ts: rec.ts
+  // can be derived from the (attacker-influenceable) webhook payload, and a
+  // spoofed far-past / far-future timestamp would poison the per-agent
+  // min-interval gate — either permanently opening it (stale ts always older
+  // than the window) or jamming it shut. The limiter only cares about "how
+  // long since the last surface on THIS gateway", which is a local wall-clock
+  // question.
+  if (!consolidationRateLimiter.allow(agent, consolidationSignature(event), Date.now())) {
+    process.stderr.write(
+      `telegram gateway: consolidation-legibility ${event.kind} rate-limited ` +
+        `agent=${agent} topic='${event.topic}'\n`,
+    )
+    return
+  }
+  const chatId = target.chatId
+  const threadId = target.threadId
+  const line = renderConsolidationLine(event)
+  process.stderr.write(
+    `telegram gateway: consolidation-legibility ${event.kind} chat=${chatId} ` +
+      `thread=${threadId ?? '-'} agent=${agent}\n`,
+  )
+  void retryWithThreadFallback(
+    robustApiCall,
+    (tid) =>
+      bot.api.sendMessage(chatId, line, {
+        parse_mode: 'HTML',
+        // Status surface, not the user's answer — never ping the device.
+        disable_notification: true,
+        ...(tid != null ? { message_thread_id: tid } : {}),
+      }),
+    { threadId, chat_id: chatId, verb: 'consolidation-legibility.sendMessage' },
+  ).catch((err) => {
+    process.stderr.write(
+      `telegram gateway: consolidation-legibility send failed: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    )
+  })
+}
+
 function handleSessionEvent(ev: SessionEvent): void {
   switch (ev.kind) {
     case 'enqueue': {
@@ -12567,6 +13575,14 @@ function handleSessionEvent(ev: SessionEvent): void {
       // of dropping. The answer-stream's own dedup handles overlap
       // with the reply tool's payload.
       preambleSuppressor.onTool({ isReplyTool: isTelegramSurfaceTool(ev.toolName) })
+      // #2849 Phase 4 — sparse chat-legible memory. Surface ONE terse line in
+      // the originating chat/topic when this tool call materially changes what
+      // the agent remembers (create_directive / invalidate / demote). Fires
+      // BEFORE the `if (!ctrl) return` status-reaction gate below so it works
+      // on turns with no active status-reaction controller. Deterministic
+      // tool-call observation — no model call, no polling; ordinary recall and
+      // routine consolidation never reach here (they aren't material tools).
+      surfaceMemoryLegibility(turn, ev.toolName, ev.toolUseId, ev.input)
       const ctrl = activeStatusReactions.get(statusKey(turn.sessionChatId, turn.sessionThreadId))
       const name = ev.toolName
       // Phase tracking removed in #553 PR 5 — phases only fed the
@@ -12997,6 +14013,9 @@ function handleSessionEvent(ev: SessionEvent): void {
     }
     case 'tool_result': {
       if (ev.toolUseId) typingWrapper.onToolResult(ev.toolUseId)
+      // Fix 1.3 (#2903): flush a staged 📌/✂️ memory-legibility line only on a
+      // CONFIRMED-successful write; a failed write (ev.isError) drops it.
+      confirmMemoryLegibility(ev.toolUseId, ev.isError)
       return
     }
     case 'sub_agent_tool_use': {
@@ -13753,11 +14772,28 @@ function handleSessionEvent(ev: SessionEvent): void {
         // this path. The turn-flush 'flush' branch also returns earlier
         // (and sets finalAnswerDelivered=true defensively).
         if (turn.finalAnswerDelivered === false) {
-          const silentEnd = recordUndeliveredTurnEnd({
-            chatId,
-            threadId: threadId ?? null,
-            turnKey: tKey,
-          })
+          // PR #2892 (deterministic-turn-liveness RFC Phase 2) hardening:
+          // wire the represent-guard-style staleness
+          // check (`recordSilentTurnEnd`'s `hasOutboundDeliveredSince` dep) so
+          // an exhausted-looking record left over from a PRIOR, already-
+          // answered turn on this same chat/thread (statusKey is not a
+          // per-turn nonce) can never be misread as this turn's spent
+          // re-prompt budget. Falls back to the pre-existing turnKey/
+          // retryCount-only check when history is unavailable.
+          const silentEndDeps: SilentEndDeps | undefined = HISTORY_ENABLED
+            ? {
+                hasOutboundDeliveredSince: (cid, sinceMs, tid) =>
+                  hasOutboundDeliveredSince(cid, sinceMs, tid, 1),
+              }
+            : undefined
+          const silentEnd = recordUndeliveredTurnEnd(
+            {
+              chatId,
+              threadId: threadId ?? null,
+              turnKey: tKey,
+            },
+            silentEndDeps,
+          )
           if (silentEnd.exhausted) {
             process.stderr.write(
               `telegram gateway: WARN silent-end fallback — agent stayed ` +
@@ -13769,7 +14805,7 @@ function handleSessionEvent(ev: SessionEvent): void {
               (tid) =>
                 bot.api.sendMessage(
                   chatId,
-                  SILENT_END_FALLBACK_TEXT,
+                  silentEndFallbackText(turnDurationMs),
                   tid != null ? { message_thread_id: tid } : {},
                 ),
               { threadId, chat_id: chatId, verb: 'silent-end-fallback.sendMessage' },
@@ -14289,6 +15325,8 @@ async function handleInbound(
   // present, so reset any no-repeat suppression: the next time the agent asks
   // for something that timed out earlier, they should see a fresh card.
   clearPermissionTimeoutSuppression('operator inbound')
+  // #2862 — operator is back; re-offer any approvals that timed out meanwhile.
+  maybePostMissedApprovalDigest('operator inbound')
 
   // Capture wall-clock receive time for inbound_ack metric (#203).
   // Must be after gate() so early-exit paths (drop/pair) don't skew the delta.
@@ -18041,6 +19079,8 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
   }
   // Operator answered via slash ⇒ present; reset no-repeat suppression.
   clearPermissionTimeoutSuppression('operator answered via /approve|/deny')
+  // #2862 — operator is present; re-offer any approvals that timed out meanwhile.
+  maybePostMissedApprovalDigest('operator answered via /approve|/deny')
   // Forward to connected bridges — same IPC the button handler uses.
   dispatchPermissionVerdict({ type: 'permission', requestId: request_id, behavior })
   resumeReactionAfterVerdict()
@@ -19898,6 +20938,185 @@ async function handleSkillProposalCallback(ctx: Context, data: string): Promise<
   )
 }
 
+/**
+ * hindsight Phase 5 — handle a tap on the mental-model PROPOSAL card.
+ *   mmp:approve:<stageId> — declare the model: append it to the agent's
+ *                           memory.mental_models[] via the operator-approved
+ *                           config-edit path (reused config_propose_edit
+ *                           apply+reconcile; reconcile ensures it), then wake
+ *                           the agent with an "applied" inbound.
+ *   mmp:deny:<stageId>    — drop the proposal; NOTHING is written; wake the
+ *                           agent with a "denied" inbound.
+ *
+ * Authorization: the tapper MUST be on the gateway's allowFrom list — an agent
+ * can PROPOSE but can never self-approve (identical gate to the vault flow).
+ */
+async function handleMentalModelProposeCallback(ctx: Context, data: string): Promise<void> {
+  const senderId = String(ctx.from?.id ?? '')
+  const access = loadAccess()
+  if (!access.allowFrom.includes(senderId)) {
+    // Self-approve is impossible: only an allow-listed operator can resolve
+    // the card. A tap from anyone else (incl. a compromised agent identity) is
+    // refused here.
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return
+  }
+  const parts = data.split(':')
+  if (parts.length < 3) {
+    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
+    return
+  }
+  const action = parts[1]
+  const stageId = parts.slice(2).join(':')
+  const pending = pendingMentalModelProposes.get(stageId)
+  if (!pending) {
+    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-propose.' }).catch(() => {})
+    if (ctx.callbackQuery?.message) {
+      await ctx.api
+        .editMessageText(
+          ctx.callbackQuery.message.chat.id,
+          ctx.callbackQuery.message.message_id,
+          richMessage('⌛ _This mental-model proposal card expired before you tapped. Ask the agent to re-propose if it still stands._'),
+          { reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+  if (action !== 'approve' && action !== 'deny') {
+    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
+    return
+  }
+  // Enforce the TTL at TAP time, not just on the next propose's sweep. Without
+  // this, a card left untapped past its TTL is still resolvable if no fresh
+  // proposal has run the sweep — an operator could approve a stale proposal.
+  if (Date.now() - pending.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS) {
+    pendingMentalModelProposes.delete(stageId)
+    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-propose.' }).catch(() => {})
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          richMessage('⌛ _This mental-model proposal card expired before you tapped. Ask the agent to re-propose if it still stands._'),
+          { reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+  // Single-shot: remove the pending entry immediately so a double-tap can't
+  // resolve twice.
+  pendingMentalModelProposes.delete(stageId)
+
+  const proposal: MentalModelPendingProposal = {
+    agent: pending.agent,
+    chat_id: pending.chat_id,
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    spec: pending.spec,
+    ...(pending.reason ? { reason: pending.reason } : {}),
+  }
+
+  const resolveDeps = {
+    readConfigText: () => readLiveSwitchroomConfigText(),
+    registerPreApproval: (agent: string, diff: string) => {
+      pendingMentalModelCorrelations.set(mentalModelCorrelationKey(agent, diff), {
+        agentName: agent,
+        unifiedDiff: diff,
+        createdAt: Date.now(),
+      })
+    },
+    clearPreApproval: (agent: string, diff: string) => {
+      pendingMentalModelCorrelations.delete(mentalModelCorrelationKey(agent, diff))
+    },
+    dispatchConfigEdit: async (a: { agent: string; diff: string; reason: string }) => {
+      const req: HostdRequest = {
+        v: 1,
+        op: 'config_propose_edit',
+        request_id: hostdRequestId('gw-mental-model'),
+        args: {
+          unified_diff: a.diff,
+          reason: a.reason,
+          target_path: '/state/config/switchroom.yaml',
+        },
+      }
+      // config_propose_edit blocks on validate→approve→apply→reconcile
+      // (5-10 min on a busy host) — allow 12 min. The operator already
+      // approved on the proposal card, so hostd's config-approval callback
+      // auto-resolves via the pre-registered correlation (no second card).
+      const resp = await tryHostdDispatch(a.agent, req, 720_000)
+      if (resp === 'not-configured') {
+        return { state: 'error' as const, reason: 'hostd config-edit is not configured (host_control disabled or socket absent)' }
+      }
+      if (resp.result === 'completed') return { state: 'applied' as const }
+      if (resp.result === 'denied') return { state: 'denied' as const, reason: resp.error ?? 'operator/host denied the edit' }
+      return { state: 'error' as const, reason: resp.error ?? `hostd returned '${resp.result}'` }
+    },
+    // Ensure is delegated to reconcile: config_propose_edit's apply triggers a
+    // reconcile which runs ensureDeclaredMentalModels (#2874) for the newly
+    // declared model — the authoritative, correctly-scoped ensure. We
+    // deliberately do NOT add a redundant gateway-side ensure (it would need
+    // the agent's bank id + a reachable Hindsight endpoint from the gateway).
+    injectInbound: (inbound: InboundMessage) => {
+      deliverResumeSyntheticOrBuffer(pending.agent, inbound)
+    },
+    log: (m: string) => process.stderr.write(`telegram gateway: ${m}\n`),
+  }
+
+  if (action === 'deny') {
+    await ctx.answerCallbackQuery({ text: '🚫 Denied' }).catch(() => {})
+    await resolveMentalModelProposal('deny', proposal, stageId, senderId, resolveDeps)
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          richMessage(`🚫 _Denied. **${escapeHtmlForTg(pending.agent)}**'s mental model \`${pending.spec.name}\` was not declared._`),
+          { reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  // Approve. Ack immediately + show an interim state, then persist in the
+  // background (config_propose_edit can take minutes), then edit the card with
+  // the real outcome. The turn resumes via the synthetic inbound injected by
+  // resolveMentalModelProposal — not by this card edit.
+  await ctx.answerCallbackQuery({ text: '✅ Declaring the model…' }).catch(() => {})
+  if (pending.card_message_id != null) {
+    await ctx.api
+      .editMessageText(
+        pending.chat_id,
+        pending.card_message_id,
+        richMessage(`⏳ _Declaring **${escapeHtmlForTg(pending.agent)}**'s mental model \`${pending.spec.name}\` — appending to config + ensuring…_`),
+        { reply_markup: { inline_keyboard: [] } },
+      )
+      .catch(() => {})
+  }
+  void (async () => {
+    let result
+    try {
+      result = await resolveMentalModelProposal('approve', proposal, stageId, senderId, resolveDeps)
+    } catch (err) {
+      process.stderr.write(`telegram gateway: mental_model_propose approve threw: ${(err as Error).message}\n`)
+      result = { outcome: 'failed' as const, reason: (err as Error).message }
+    }
+    if (pending.card_message_id != null) {
+      const label =
+        result.outcome === 'applied'
+          ? `✅ **Declared** ${escapeHtmlForTg(pending.agent)}'s mental model \`${pending.spec.name}\` — appended to \`memory.mental_models[]\` and ensured. Restart the agent to load it if it isn't picked up automatically.`
+          : `⚠️ **Did NOT declare** \`${pending.spec.name}\`${'reason' in result && result.reason ? ` — ${escapeHtmlForTg(result.reason)}` : ''}. Nothing was written.`
+      await ctx.api
+        .editMessageText(pending.chat_id, pending.card_message_id, richMessage(label), {
+          reply_markup: { inline_keyboard: [] },
+          link_preview_options: { is_disabled: true },
+        })
+        .catch(() => {})
+    }
+  })()
+}
+
 async function handleVaultRequestAccessCallback(ctx: Context, data: string): Promise<void> {
   const senderId = String(ctx.from?.id ?? '')
   const access = loadAccess()
@@ -22439,6 +23658,15 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // hindsight Phase 5: agent-proposes → human-approves mental-model card.
+  //   mmp:approve:<stageId> — declare the model (append memory.mental_models[]
+  //                           via operator-approved config edit) + ensure it
+  //   mmp:deny:<stageId>    — drop the proposal; NOTHING is written
+  if (data.startsWith('mmp:')) {
+    await handleMentalModelProposeCallback(ctx, data)
+    return
+  }
+
   // #2670: one-tap skill-improvement proposal card.
   //   skprop:approve:<id> — apply the stored draft via the personal-skill
   //                         write pipeline (inject a turn; agent writes it)
@@ -22449,6 +23677,15 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // #2862: missed-approvals re-offer digest.
+  //   missre:retry:<id>   — inject a synthetic inbound asking the agent to
+  //                         re-attempt (re-raises a fresh approval card)
+  //   missre:dismiss:<id> — clear the record + edit the card closed
+  if (data.startsWith('missre:')) {
+    await handleMissedApprovalCallback(ctx, data)
+    return
+  }
+
   // Issue #969 P2b: vault recent-denial one-tap approval.
   //   vrd:<agent>:<key> — mint a 30-day read-grant for the agent + key
   // Posted by /vault audit <agent> in the "Recent denials" section.
@@ -23095,6 +24332,8 @@ bot.on('callback_query:data', async ctx => {
   // Operator tapped a verdict ⇒ they are present; reset no-repeat suppression
   // so a later identical ask is shown fresh rather than silently short-circuited.
   clearPermissionTimeoutSuppression('operator answered a permission card')
+  // #2862 — operator is present; re-offer any approvals that timed out meanwhile.
+  maybePostMissedApprovalDigest('operator answered a permission card')
   const pd = pendingPermissions.get(request_id)
   const resumeAction = pd ? naturalAction(pd.tool_name, pd.input_preview) : ''
   const scopedTtl = scopedApprovalTtlMs()
@@ -23106,6 +24345,9 @@ bot.on('callback_query:data', async ctx => {
   permCardStore.remove(request_id)
   if (timeBox && grantAgent) {
     recordScopedGrant(scopedGrants, grantAgent, timeBox.rule, Date.now(), scopedTtl)
+    // Write-through so the window survives a gateway restart (#2863). Absolute
+    // expiry is baked into the entry, so a reload can't extend it.
+    scopedGrantStore.save(scopedGrants)
     process.stderr.write(
       `telegram gateway: scoped-approval granted via Allow rule="${timeBox.rule}" ` +
       `agent=${grantAgent} ttl_ms=${scopedTtl} (request_id=${request_id})\n`,
@@ -24874,39 +26116,68 @@ void (async () => {
         // tracks the live turn from there.
         try { removeTurnActiveMarker(STATE_DIR) } catch { /* best-effort */ }
 
-        // Strip stale permission cards from prior gateway session. Any entry
-        // still in the store was never resolved (gateway died before the
-        // operator tapped or the reaper ran). The operator might have seen
-        // those cards and tapped them — if so, they got STALE_TAP_NOTICE
-        // ("already resolved") which is misleading. Edit the messages to
-        // remove the keyboard and show a clear "restarted" notice instead.
-        void (async () => {
-          const stale = permCardStore.loadAll()
-          if (stale.length === 0) return
-          process.stderr.write(
-            `telegram gateway: boot-sweep: stripping ${stale.length} stale permission card(s) from prior gateway session\n`,
-          )
-          for (const card of stale) {
-            const toolLabel = card.toolName ?? 'unknown tool'
-            const notice = `🔒 **${toolLabel}**\n\n⚠️ *Gateway restarted — this request is no longer active. Ask your agent to try again if needed.*`
-            try {
-              // allow-raw-bot-api: targeted by message_id; no thread needed; fire-and-forget boot sweep
-              await bot.api.editMessageText(
-                card.chatId,
-                card.messageId,
-                richMessage(notice),
-                { reply_markup: { inline_keyboard: [] } },
-              )
-            } catch (err) {
-              // Card may already be deleted, edited, or in an inaccessible chat — benign
-              process.stderr.write(
-                `telegram gateway: boot-sweep: stale-card strip failed ` +
-                `${card.chatId}:${card.messageId}: ${(err as Error).message}\n`,
-              )
-            }
+        // Boot-sweep for permission cards from a prior gateway session. Any
+        // entry still in the store was never resolved (gateway died before the
+        // operator tapped or the reaper ran).
+        //
+        // #2861: DON'T strip immediately. A still-live claude session's bridge
+        // re-sends its outstanding permission_requests on IPC reconnect within
+        // a few seconds — re-arming the persisted card instead of losing the
+        // suspended turn. So we wait a grace window (~90 s) and only strip
+        // entries that were NOT re-claimed by a bridge re-send in the meantime.
+        // A genuinely dead session (container recreate → new bridge, empty
+        // ledger) never re-sends, so those still get the "restarted" notice.
+        //
+        // Kill switch SWITCHROOM_PERMISSION_REARM=0 reverts to the legacy
+        // immediate strip-everything sweep.
+        if (!isPermissionRearmEnabled()) {
+          void (async () => {
+            const stale = permCardStore.loadAll()
+            if (stale.length === 0) return
+            process.stderr.write(
+              `telegram gateway: boot-sweep: stripping ${stale.length} stale permission card(s) from prior gateway session\n`,
+            )
+            for (const card of stale) await stripStalePermissionCard(card)
+            permCardStore.clear()
+          })()
+        } else {
+          const bootStale = permCardStore.loadAll()
+          if (bootStale.length > 0) {
+            const graceMs = permissionRearmGraceMs()
+            process.stderr.write(
+              `telegram gateway: boot-sweep: ${bootStale.length} pending permission card(s) from prior ` +
+              `session; deferring strip ${graceMs}ms to allow bridge re-arm (#2861)\n`,
+            )
+            setTimeout(() => {
+              void (async () => {
+                // Reload — some entries may have been resolved (tap/TTL) during
+                // the grace window, which removes them from the store.
+                const remaining = permCardStore.loadAll()
+                // Preserve anything currently LIVE in pendingPermissions: that
+                // covers both re-armed cards (a bridge re-send restored them)
+                // AND fresh cards born during the grace window (a new approval
+                // posted after boot). Only cards with no live pending entry —
+                // a genuinely dead session that never reconnected — are stripped.
+                const liveRequestIds = new Set(pendingPermissions.keys())
+                const toStrip = computeBootSweepStripTargets(remaining, liveRequestIds)
+                if (toStrip.length === 0) {
+                  process.stderr.write(
+                    `telegram gateway: boot-sweep: all pending permission cards re-armed or still live — nothing to strip\n`,
+                  )
+                  return
+                }
+                process.stderr.write(
+                  `telegram gateway: boot-sweep: stripping ${toStrip.length} dead-session permission card(s) ` +
+                  `after ${graceMs}ms grace (of ${remaining.length} still persisted, ${liveRequestIds.size} live)\n`,
+                )
+                for (const card of toStrip) await stripStalePermissionCard(card)
+                // Remove ONLY the stripped request_ids — re-armed entries stay
+                // persisted so a subsequent restart re-arms them again.
+                for (const id of distinctRequestIds(toStrip)) permCardStore.remove(id)
+              })()
+            }, graceMs).unref?.()
           }
-          permCardStore.clear()
-        })()
+        }
 
         // Boot-time pin sweep
         try {
@@ -25300,6 +26571,29 @@ void (async () => {
               // accident no longer pollute the watcher with phantom
               // registrations + ENOENT log spam + false stalls.
               agentCwd: watcherAgentDir,
+              // Gap 2 (deterministic-turn-liveness.md "Known gaps"): a
+              // sub-agent dispatched into a `switchroom worktree claim`
+              // cwd runs under a different project-dir slug than
+              // `agentCwd` above, so the #1116 foreign-slug filter would
+              // otherwise skip it forever — no activity stamp, no `🛠
+              // Worker` feed for the entire run. Re-derive, fresh on every
+              // rescan tick, the set of worktree paths this agent itself
+              // currently owns (registry records are the deterministic
+              // source of truth for "cwds this agent's sub-agents may run
+              // in") and let the watcher also watch those slugs.
+              // Best-effort: a registry read failure (e.g. no worktree dir
+              // on an agent that never claims one) must not affect the
+              // primary agentCwd watch.
+              extraWatchCwdsProvider: () =>
+                // Fail-CLOSED ownership filter (unset identity ⇒ nothing;
+                // ownerless records excluded; registry throw ⇒ []). Extracted
+                // to telegram-plugin/worktree-watch-cwds.ts so the #1116 /
+                // Gap-2 ownership predicate is under direct unit test — see
+                // telegram-plugin/tests/worktree-watch-cwds.test.ts.
+                ownedWorktreeCwds({
+                  self: process.env.SWITCHROOM_AGENT_NAME,
+                  listRecords: listWorktreeRecords,
+                }),
               // Bug 0 fix: previously omitted, leaving the watcher unable to
               // write liveness/stall/turn_end updates to the registry DB.
               // Liveness writes are now persisted across the gateway lifetime.