switchroom 0.18.24 → 0.18.26

package/telegram-plugin/gateway/model-command.ts

@@ -24,7 +24,7 @@
  * unit-testable without booting the bot.
  */
 
-import type { InjectResult } from '../../src/agents/inject.js'
+import type { InjectResult, InjectOpts } from '../../src/agents/inject.js'
 import {
   labelTag,
   type DiscoverResult,
@@ -185,8 +185,17 @@ export function modelCommandReceiptLine(
 }
 
 export interface ModelCommandDeps {
-  /** Inject primitive — wired to injectSlashCommand in the gateway. */
-  inject: (agent: string, command: string) => Promise<InjectResult>
+  /**
+   * Inject primitive — wired to injectSlashCommand in the gateway. The optional
+   * third argument forwards the #3241 poll-until-signal opts (successPattern /
+   * errorPattern / settleBeforeSendMs); the set path passes them so the `/model`
+   * confirmation scrape is deterministic instead of racing a fixed window.
+   */
+  inject: (
+    agent: string,
+    command: string,
+    opts?: Pick<InjectOpts, 'successPattern' | 'errorPattern' | 'settleBeforeSendMs'>,
+  ) => Promise<InjectResult>
   /**
    * True while the agent is mid-turn. A typed `/model <name>` switch drives
    * claude's session (either an inject into the input box, or a carrier-backed
@@ -248,6 +257,17 @@ export interface ModelCommandReply {
    * lies to `/status`.
    */
   selectedModel?: string
+  /**
+   * True when `selectedModel` was recorded OPTIMISTICALLY (#3241 part B): the
+   * inject SEND succeeded and NO explicit error line was scraped, but claude's
+   * confirmation line was not read either. Poll-until-signal already waited the
+   * full window, so a missing line means a silent switch (or a confirmation
+   * that scrolled off) — NOT a failure — and we record the requested model so
+   * `/status` is right. The switch is retracted (no `selectedModel`) only when
+   * an error line IS scraped. Purely a wording hint; the gateway records
+   * `selectedModel` the same way whether confirmed or optimistic.
+   */
+  optimistic?: boolean
 }
 
 const PERSIST_NOTE =
@@ -379,7 +399,18 @@ export async function handleModelCommand(
   const verbHtml = `\`/model ${deps.escapeHtml(model)}\``
   let result: InjectResult
   try {
-    result = await deps.inject(deps.getAgentName(), `/model ${model}`)
+    // #3241 part A — poll-until-signal. Hand the inject primitive the exact
+    // confirmation / error line shapes so its capture loop keeps polling until
+    // claude's "Set model to …" (or an error) actually lands, instead of
+    // breaking at a fixed settle window on the first pane change (which the
+    // async access banner tripped, capturing the banner and missing the
+    // confirmation). settleBeforeSendMs waits for a clean prompt so the keys
+    // aren't typed into a still-animating pane (symptom 2's silent no-op).
+    result = await deps.inject(deps.getAgentName(), `/model ${model}`, {
+      successPattern: MODEL_SWITCH_CONFIRMATION_PREFIX,
+      errorPattern: MODEL_SWITCH_ERROR_RE,
+      settleBeforeSendMs: 1500,
+    })
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     return {
@@ -388,33 +419,43 @@ export async function handleModelCommand(
     }
   }
 
-  if (result.outcome === 'ok') {
-    // claude's `/model <name>` either prints a "Set model to X" acknowledgement
-    // or switches SILENTLY (no line). `result.output` on the silent path is just
-    // whatever pane scrollback sat below the command echo (the agent's previous
-    // prose answer) — NOT a confirmation. We MUST NOT claim success on that
-    // scrollback, and we must never dump it back as a code block (screenshot-
+  if (result.outcome === 'ok' || result.outcome === 'ok_no_output') {
+    // claude's `/model <name>` prints a "Set model to X" acknowledgement, an
+    // error line ("Model not found"), a "Kept model as X" no-op, or (rarely)
+    // switches with the confirmation scrolled off. `result.output` on a silent
+    // path is just pane scrollback (the agent's previous prose) — NEVER a
+    // confirmation, and it must not be dumped back as a code block (screenshot-
     // confirmed leak on klanker, v0.16.47).
     //
-    // Honest reporting: (1) if claude printed an error ("Model not found" /
-    // "Invalid model"), the switch FAILED — say so. (2) if an anchored
-    // confirmation line is present, the switch is verified — relay it and record
-    // the live model for /status. (3) otherwise we cannot positively verify the
-    // switch (silent success or nothing) — say "sent, but couldn't confirm" and
-    // record NOTHING, so /status is never lied to.
-    const errLine = modelSwitchErrorLine(result.output)
-    if (errLine) {
-      return {
-        text: [
-          `❌ ${verbHtml} — the switch did not take:`,
-          deps.preBlock(errLine),
-          'Check \`/model\` for valid model names.',
-        ].join('\n'),
-        html: true,
-      }
-    }
-    const confirmation = modelSwitchConfirmationLine(result.output)
+    // Honest reporting (#3241 part B inverts the old "record nothing unless
+    // confirmed" to "record optimistically, retract only on a scraped error").
+    // Order matters (#3242 review MEDIUM 1): check the CONFIRMATION line FIRST —
+    // a genuine switch always prints one, so it can never be flipped to a failure
+    // by a stray availability/denial word (the widened MODEL_SWITCH_ERROR_RE) in
+    // the same region. Then:
+    //   (1) "Kept model as X" → genuine no-op; report it, record NOTHING.
+    //   (2) other confirmation → verified switch; relay it, record the display
+    //       name for /status.
+    //   (3) error/denial line scraped (bad id OR access denial) → switch FAILED.
+    //       Report it; record NOTHING (the retract — /status keeps the prior model).
+    //   (4) no line either way → poll-until-signal already waited the full
+    //       window, so this is a SILENT success, not a failure. Record the
+    //       requested model OPTIMISTICALLY (normalized to display form) so
+    //       /status is right, and say so.
+    const confirmation = result.outcome === 'ok' ? modelSwitchConfirmationLine(result.output) : null
     if (confirmation) {
+      if (isKeptModelConfirmation(confirmation)) {
+        // "Kept model as X" — nothing changed. Relay it, record no override.
+        return {
+          text: [
+            `${verbHtml}`,
+            deps.preBlock(confirmation),
+            ...(result.truncated ? ['_truncated_'] : []),
+            PERSIST_NOTE,
+          ].join('\n'),
+          html: true,
+        }
+      }
       const confirmed = sessionModelFromConfirmation(confirmation) ?? model
       return {
         text: [
@@ -424,27 +465,35 @@ export async function handleModelCommand(
           PERSIST_NOTE,
         ].join('\n'),
         html: true,
-        // Only record when the confirmation carries a real switch (Set/Switched);
-        // a "Kept model as" line means no change — don't overwrite the override.
-        ...(isKeptModelConfirmation(confirmation) ? {} : { selectedModel: confirmed }),
+        selectedModel: confirmed,
       }
     }
-    return {
-      text: [
-        `${verbHtml} — sent, but couldn't confirm the switch — check \`/status\`.`,
-        PERSIST_NOTE,
-      ].join('\n'),
-      html: true,
+    const errLine = result.outcome === 'ok' ? modelSwitchErrorLine(result.output) : null
+    if (errLine) {
+      return {
+        text: [
+          `❌ ${verbHtml} — the switch did not take:`,
+          deps.preBlock(errLine),
+          'Check \`/model\` for a valid, available model.',
+        ].join('\n'),
+        html: true,
+      }
     }
-  }
-
-  if (result.outcome === 'ok_no_output') {
+    // No confirmation and no error — optimistic record (#3241 part B). The
+    // Telegram copy stays PROVISIONAL (#3242 review FIX 2): we couldn't read a
+    // confirmation, and if the CLI denied the switch with wording our error
+    // regex misses, an affirmative "recorded X" would be a lie that never
+    // self-corrects. `/status` DOES self-heal (the override is reclaimed by the
+    // next transcript line), so point the user there rather than assert success.
+    const optimisticLabel = optimisticModelRecordLabel(model)
     return {
       text: [
-        `${verbHtml} — sent, but no response captured. The agent may be mid-turn; check \`/inject /status\` to confirm the active model.`,
+        `${verbHtml} — sent, but couldn't read a confirmation line. \`/status\` will show the live model once it's confirmed.`,
         PERSIST_NOTE,
       ].join('\n'),
       html: true,
+      selectedModel: optimisticLabel,
+      optimistic: true,
     }
   }
 
@@ -617,6 +666,32 @@ export function srFriendlyLabel(srName: string): string {
   return SR_MODEL_LABELS[srName] ?? srName.replace(/^sr-/, '').replace(/-/g, ' ')
 }
 
+/**
+ * #3242 review LOW 4 — display normalization for the OPTIMISTIC `/status` record.
+ * The confirmed path records the display name claude printed (e.g. "Fable 5" via
+ * `sessionModelFromConfirmation`); the optimistic path only has the requested
+ * arg. Without a confirmation we can't know the version suffix, so we normalize
+ * a bare Claude alias to the same DISPLAY style — Title-case ("fable" → "Fable")
+ * — and leave a full `claude-*` id as-is (already canonical).
+ *
+ * #3242 review FIX 1 (MEDIUM) — sr-* tokens are returned UNCHANGED (with the
+ * `sr-` prefix). The stored `selectedModel` doubles as the sr-*→Claude sentinel:
+ * `gateway.ts` `isSrToClaudeTransition` checks `prevModel?.startsWith('sr-')` to
+ * decide whether a later Claude switch needs the graceful restart that tears
+ * down LiteLLM routing. De-prefixing here (as the earlier LOW-4 pass did via
+ * `srFriendlyLabel`) would silently break that restart. So this helper never
+ * de-prefixes: the caller normalizes only the DISPLAY text separately (see
+ * `srFriendlyLabel`), never the stored token.
+ */
+export function optimisticModelRecordLabel(token: string): string {
+  if (isSrModel(token)) return token
+  const lower = token.toLowerCase()
+  if ((MODEL_ALIASES as readonly string[]).includes(lower)) {
+    return lower.charAt(0).toUpperCase() + lower.slice(1)
+  }
+  return token
+}
+
 /**
  * Split picker-discovered options into native Claude options and sr-*
  * (LiteLLM non-Anthropic) options. Options with "/" in the label or
@@ -973,7 +1048,14 @@ export async function handleModelMenuCallback(
     }
     let aliasResult: InjectResult
     try {
-      aliasResult = await deps.inject(deps.getAgentName(), `/model ${alias}`)
+      // #3241 part A — same poll-until-signal + clean-prompt opts as the typed
+      // set path so the alias (e.g. Fable) confirmation scrape is deterministic
+      // and immune to the async access banner.
+      aliasResult = await deps.inject(deps.getAgentName(), `/model ${alias}`, {
+        successPattern: MODEL_SWITCH_CONFIRMATION_PREFIX,
+        errorPattern: MODEL_SWITCH_ERROR_RE,
+        settleBeforeSendMs: 1500,
+      })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       return {
@@ -981,20 +1063,54 @@ export async function handleModelMenuCallback(
         reply: await menuWithBanner(deps, `❌ Switch to **${deps.escapeHtml(alias)}** failed: ${deps.escapeHtml(msg)}`),
       }
     }
-    if (aliasResult.outcome === 'ok') {
-      // Anchored confirmation only — a loose /set model|switched/ match false-
-      // positives on ordinary scrollback prose ("I switched the deploy…").
-      const confirmation =
-        modelSwitchConfirmationLine(aliasResult.output) ?? `Switched to ${alias} (session)`
-      // "Kept model as X" means no change — don't overwrite the override.
-      const kept = isKeptModelConfirmation(confirmation)
+    // #3242 review MEDIUM 2 — the alias BUTTON (the primary Fable UI, the exact
+    // async-banner scenario) must be symmetric with the typed set path: handle
+    // BOTH `ok` and `ok_no_output` with record-on-send / retract-on-scraped-error.
+    // Previously `ok_no_output` fell through to "Switch failed — agent may be
+    // mid-turn" and dropped the override, so a silent successful button-switch
+    // was reported as a failure while the identical typed command recorded.
+    if (aliasResult.outcome === 'ok' || aliasResult.outcome === 'ok_no_output') {
+      // Confirmation first (a genuine switch always prints one) so a stray
+      // availability/denial word can't flip it to a failure.
+      const confirmation = aliasResult.outcome === 'ok'
+        ? modelSwitchConfirmationLine(aliasResult.output)
+        : null
+      if (confirmation) {
+        // "Kept model as X" means no change — don't overwrite the override.
+        const kept = isKeptModelConfirmation(confirmation)
+        return {
+          answer: confirmation,
+          reply: await menuWithBannerStatic(deps, `✅ ${deps.escapeHtml(confirmation)}`),
+          ...(kept ? {} : {
+            selectedModel: sessionModelFromConfirmation(confirmation) ?? optimisticModelRecordLabel(alias),
+            selectedModelToken: alias,
+          }),
+        }
+      }
+      // Scraped error/denial (bad id OR access denial) → genuine failure, record
+      // nothing (retract).
+      const aliasErr = aliasResult.outcome === 'ok' ? modelSwitchErrorLine(aliasResult.output) : null
+      if (aliasErr) {
+        return {
+          answer: 'Switch failed',
+          reply: await menuWithBanner(
+            deps,
+            `❌ Switch to **${deps.escapeHtml(alias)}** did not take: ${deps.escapeHtml(aliasErr)}`,
+          ),
+        }
+      }
+      // Silent success (no confirmation, no error) → optimistic record, same as
+      // the typed path. PROVISIONAL copy (#3242 review FIX 2): don't assert the
+      // switch succeeded — we couldn't read a confirmation, and /status self-heals.
+      const optimisticLabel = optimisticModelRecordLabel(alias)
       return {
-        answer: confirmation,
-        reply: await menuWithBannerStatic(deps, `✅ ${deps.escapeHtml(confirmation)}`),
-        ...(kept ? {} : {
-          selectedModel: sessionModelFromConfirmation(confirmation) ?? alias,
-          selectedModelToken: alias,
-        }),
+        answer: `Sent /model ${alias} — check /status`,
+        reply: await menuWithBannerStatic(
+          deps,
+          `Sent \`/model ${deps.escapeHtml(alias)}\` — couldn’t read a confirmation line. \`/status\` will show the live model once it’s confirmed.`,
+        ),
+        selectedModel: optimisticLabel,
+        selectedModelToken: alias,
       }
     }
     return {
@@ -1185,9 +1301,25 @@ export function modelSwitchConfirmationLine(output: string): string | null {
  * 2026-07-10): `/model claude-bogus-99` prints
  * `⎿  Model 'claude-bogus-99' not found` — glyph prefix `⎿`, quoted model
  * name between "Model" and "not found". Both shapes are covered.
+ *
+ * #3242 review MEDIUM 1 — ACCESS/ENTITLEMENT DENIAL. A bad-id shape is not the
+ * only failure: `/model fable` on a plan that lacks it prints an availability /
+ * access-denial line ("Fable is not available on your plan", "access denied",
+ * "requires a subscription", "not enabled for your account", "no access to …").
+ * Those match neither the bad-id shapes nor the confirmation prefix, so the poll
+ * loop would expire and the optimistic branch would falsely record the switch —
+ * exactly the Fable-entitlement case this PR is about. The second alternation
+ * group covers those phrasings. It allows up to four leading words (a model
+ * name + a linking adverb etc.) BEFORE the denial phrase — unlike the bad-id
+ * branches, which keep
+ * their original tight line-start anchoring so ordinary scrollback that merely
+ * says "model not found" mid-sentence still can't false-fail a silent switch.
+ * The handler checks the confirmation line FIRST (below), so a genuine switch —
+ * which always prints a confirmation — is never flipped to a failure by a stray
+ * availability word in the same region.
  */
 const MODEL_SWITCH_ERROR_RE =
-  /^\s*[⏺●•>⎿-]?\s*(?:Error:\s*)?(?:Model(?:\s+'[^']+')?\s+not found|Invalid model|Unknown model|No such model)\b/i
+  /^\s*[⏺●•>⎿-]?\s*(?:Error:\s*)?(?:Model(?:\s+'[^']+')?\s+not found|Invalid model|Unknown model|No such model|(?:[\w'’.\-]+\s+){0,4}(?:(?:is |are )?(?:not available|unavailable|not enabled|not supported)|access denied|requires\b[^\n]{0,40}\b(?:subscription|plan)|no access)\b)/i
 
 /** The single capture line that reads as a claude model-switch error, or null. */
 export function modelSwitchErrorLine(output: string): string | null {

package/telegram-plugin/gateway/redelivery-decision.ts

@@ -0,0 +1,139 @@
+/**
+ * Crash-survival redelivery — the PURE decision predicate.
+ *
+ * When the gateway process crashes (or the hang-watchdog kills it) BEFORE the
+ * in-memory flush timer fires, the model's completed final answer — captured
+ * only in the in-memory buffer — is lost, and the user gets permanent silence.
+ * The answer text is, however, still durable on disk in the claude session
+ * transcript. On the next boot we can re-project that trailing text and re-send
+ * it. This module owns the "should we re-send, and how" decision so it is
+ * unit-testable without booting a gateway (the boot block only wires I/O to it).
+ *
+ * The delivery oracle is DURABLE TEXT-IDENTITY, not a chat+time window: we
+ * redeliver only if the PROJECTED final-answer text was NOT already delivered
+ * (matched against delivered `messages` rows — see `hasOutboundWithText`). A
+ * time-windowed "any assistant row since started_at" oracle is UNSOUND here:
+ * an interim `progress_update` or a streamed partial chunk lands a mid-turn
+ * `role='assistant'` row and would false-positive "delivered", suppressing a
+ * genuinely-undelivered final answer (the exact MISS this fix exists to close).
+ *
+ * The redelivered text is FRAMED as a recovered/interrupted draft rather than
+ * presented as a clean final answer: the transcript cannot durably distinguish
+ * "final answer complete" from "answer-so-far, more tools intended", so we never
+ * assert it is the finished answer.
+ */
+
+/** The short preamble that frames a redelivered draft. */
+export const REDELIVERY_PREFIX = 'Recovered from an interrupted turn:'
+
+export interface RedeliverDecisionInput {
+  /**
+   * The trailing assistant text re-projected from the interrupted turn's own
+   * transcript (after the last tool_use). Empty string when the transcript had
+   * no trailing text to redeliver.
+   */
+  capturedText: string
+  /**
+   * True when the trailing transcript content AFTER the last tool_use is text
+   * (not a dangling tool_use). Bounds the preamble-vs-final ambiguity (R2): a
+   * turn whose last on-disk event was a tool_use is mid-stream, not a finished
+   * answer, so we do not redeliver it.
+   */
+  trailingIsText: boolean
+  /**
+   * Result of the DURABLE text-identity oracle: true iff the projected answer
+   * text was already delivered to this chat/thread (`hasOutboundWithText`).
+   */
+  hasDeliveredText: boolean
+  /** True iff `answer_redelivered_at` is already stamped (at-most-once ledger). */
+  alreadyRedelivered: boolean
+  /** Age of the interrupted turn in ms (`now - started_at`). */
+  ageMs: number
+  /** Staleness failsafe (`RESUME_MAX_AGE_MS`, default 3h). */
+  maxAgeMs: number
+}
+
+export type RedeliverSkipReason =
+  | 'empty-text'
+  | 'trailing-not-text'
+  | 'already-delivered'
+  | 'already-redelivered'
+  | 'stale'
+
+export interface RedeliverDecision {
+  redeliver: boolean
+  /** Present iff `redeliver` is true — the framed text to send. */
+  framedText?: string
+  /** Present iff `redeliver` is false — why we declined. */
+  skipReason?: RedeliverSkipReason
+}
+
+/**
+ * Whether to CAPTURE an interrupted turn as a redelivery candidate at boot.
+ * This is the mutual-exclusion gate against the resume synthetic — decided
+ * BEFORE any transcript projection, purely from the boot-resume outcome.
+ */
+export interface RedeliverCaptureInput {
+  /**
+   * True iff the boot-resume path will RE-RUN this turn's work in a fresh
+   * session (bootResumeKind === 'resume'). A resumed turn emits a fresh answer
+   * that supersedes any recovered draft, so redelivering as well is a
+   * double-send. Every non-resume outcome (watchdog report, defer-suppressed,
+   * defer-loop, none) does NOT auto-re-answer, so redelivery is the correct and
+   * only recovery send there.
+   */
+  willBeResumed: boolean
+  /**
+   * True iff the interrupted turn has a durably-pinned `session_id`. Without it
+   * we cannot resolve the exact transcript to re-project, so we cannot redeliver.
+   */
+  hasSessionId: boolean
+}
+
+export type RedeliverCaptureSkip = 'will-be-resumed' | 'no-session-id'
+
+export interface RedeliverCaptureDecision {
+  capture: boolean
+  /** Present iff `capture` is false — why we declined to stage redelivery. */
+  skipReason?: RedeliverCaptureSkip
+}
+
+/**
+ * Decide whether to stage an interrupted turn for crash-survival redelivery.
+ * Pure: the mutual-exclusion rule with resume lives here so it is testable
+ * without booting a gateway. `will-be-resumed` takes precedence over the
+ * session-id check because a to-be-resumed turn must never redeliver even if it
+ * has a session_id — the fresh re-answer is the send.
+ */
+export function decideRedeliverCapture(input: RedeliverCaptureInput): RedeliverCaptureDecision {
+  if (input.willBeResumed) return { capture: false, skipReason: 'will-be-resumed' }
+  if (!input.hasSessionId) return { capture: false, skipReason: 'no-session-id' }
+  return { capture: true }
+}
+
+/**
+ * Frame a captured draft for redelivery — a short recovered-draft preamble
+ * above the model's own words. Pure; exported for the boot wiring + tests.
+ */
+export function frameRedelivery(capturedText: string): string {
+  return `${REDELIVERY_PREFIX}\n\n${capturedText.trim()}`
+}
+
+/**
+ * Decide whether — and with what framed text — to redeliver an interrupted
+ * turn's captured-but-undelivered final answer. Pure: no clock, no I/O.
+ *
+ * Precedence of skip reasons is deliberate (most-specific first): a turn with
+ * no trailing text can never redeliver regardless of delivery/age; a delivered
+ * or already-redelivered answer is skipped before the age failsafe so the
+ * at-most-once guarantee never depends on staleness.
+ */
+export function decideRedeliver(input: RedeliverDecisionInput): RedeliverDecision {
+  const text = input.capturedText.trim()
+  if (text.length === 0) return { redeliver: false, skipReason: 'empty-text' }
+  if (!input.trailingIsText) return { redeliver: false, skipReason: 'trailing-not-text' }
+  if (input.alreadyRedelivered) return { redeliver: false, skipReason: 'already-redelivered' }
+  if (input.hasDeliveredText) return { redeliver: false, skipReason: 'already-delivered' }
+  if (input.ageMs > input.maxAgeMs) return { redeliver: false, skipReason: 'stale' }
+  return { redeliver: true, framedText: frameRedelivery(text) }
+}

package/telegram-plugin/gateway/vault-grant-inbound-builders.ts

@@ -149,21 +149,62 @@ export function buildVaultGrantDeniedInbound(opts: {
  * @param key           Vault key (rendered inline-code).
  * @param days          Grant TTL in whole days.
  * @param grantId       Broker-returned grant id.
+ * @param reasonEscaped Optional original request reason the agent gave,
+ *                      already run through `escapeHtmlForTg` (it is
+ *                      agent-supplied free text). Rendered as a trailing
+ *                      italic clause for audit visibility. Omitted when
+ *                      absent/empty so no dangling "Reason:" label shows.
+ *                      Placed BEFORE the footer so the auth-mode note
+ *                      stays last.
  * @param footer        Optional trailing footer (e.g. the telegram-id
  *                      auth-mode note). Empty string when absent.
  */
+/** Max characters of agent-supplied reason rendered on the grant card.
+ *  Keeps the edited card well under Telegram's 4096-char editMessageText
+ *  limit — the edit is fire-and-forget (`.catch(() => {})`), so an
+ *  over-long reason would silently fail the edit and leave the pending
+ *  approve/deny buttons showing even though the grant already succeeded. */
+export const MAX_GRANT_REASON_CHARS = 300
+
+/**
+ * Normalize an agent-supplied grant reason for single-line rendering
+ * inside the GFM italic clause `_Reason: …_`:
+ *   - collapse ALL whitespace runs to a single space (a newline breaks
+ *     the `_…_` emphasis — the opening `_` renders literal),
+ *   - trim, so a whitespace-only reason cleanly no-ops (returns ''),
+ *   - cap length with a trailing ellipsis so the card edit can't blow
+ *     past Telegram's message-length limit.
+ *
+ * Returns UNescaped text — the caller MUST HTML-escape the result before
+ * rendering (it is agent-supplied free text). Returns '' for
+ * empty/whitespace-only/undefined input so the caller can skip the clause.
+ */
+export function normalizeGrantReason(raw: string | undefined | null): string {
+  if (raw == null) return ''
+  const collapsed = raw.replace(/\s+/g, ' ').trim()
+  if (collapsed.length === 0) return ''
+  return collapsed.length > MAX_GRANT_REASON_CHARS
+    ? collapsed.slice(0, MAX_GRANT_REASON_CHARS - 1) + '…'
+    : collapsed
+}
+
 export function buildVaultGrantApprovedCardText(opts: {
   agentEscaped: string
   scope: 'read' | 'write'
   key: string
   days: number
   grantId: string
+  reasonEscaped?: string
   footer?: string
 }): string {
+  const reasonClause =
+    opts.reasonEscaped != null && opts.reasonEscaped.length > 0
+      ? ` _Reason: ${opts.reasonEscaped}_`
+      : ''
   return (
     `✅ Granted **${opts.agentEscaped}** ${opts.scope} access to ` +
     `\`${opts.key}\` for ${opts.days}d. ` +
-    `(grant \`${opts.grantId}\`)` + (opts.footer ?? '')
+    `(grant \`${opts.grantId}\`)` + reasonClause + (opts.footer ?? '')
   )
 }
 

package/telegram-plugin/history.ts

@@ -740,6 +740,124 @@ export function hasOutboundDeliveredSince(
   }
 }
 
+/**
+ * DURABLE text-identity delivery oracle for crash-survival redelivery.
+ *
+ * Returns true iff a substantive outbound (`role='assistant'`) row whose text
+ * matches `text` has been delivered to `chatId` (and optionally `threadId`).
+ * Unlike `hasOutboundDeliveredSince`, this keys on the ANSWER TEXT itself, not
+ * a chat+time window — so an interim `progress_update` ("on it…") or a streamed
+ * partial chunk sent earlier in the same turn does NOT false-positive as "the
+ * final answer was delivered" (the exact MISS bug that would otherwise suppress
+ * a genuinely-undelivered final answer and re-open the permanent-silence hole).
+ *
+ * Matching is on the NORMALIZED first chunk (see `normalizeDeliveryText`): a
+ * multi-chunk answer's chunk-1 is compared against delivered rows so a crash
+ * after chunk-1 is detected as delivered (avoids double-sending chunk-1). Both
+ * sides are normalized identically. Empty/whitespace text never matches.
+ *
+ * Durable (reads committed SQLite), survives restart — unlike the in-memory
+ * `outboundDedup` ring, whose window is destroyed by the crash.
+ *
+ * SCOPING (crash-redelivery diff-review defect #1). Two guards keep a match from
+ * being over-broad and suppressing a genuine redelivery (a MISS = permanent
+ * silence):
+ *   1. `sinceMs` — when provided (the interrupted turn's `started_at`), only
+ *      rows delivered AT/AFTER that instant are considered, so an UNRELATED
+ *      earlier turn's message can never satisfy the match. This is the primary
+ *      scope: a redelivery candidate only cares whether THIS turn's own answer
+ *      already went out.
+ *   2. Short-text exactness — the bidirectional-prefix rule (which lets a
+ *      delivered multi-chunk chunk-1 satisfy a longer projected answer) is only
+ *      applied when the shorter side is at least `MIN_PREFIX_MATCH_CHARS`. For a
+ *      SHORT final answer (e.g. "Done.") a prefix match against a longer row
+ *      ("Done, deploying now.") would false-positive; short texts therefore
+ *      require full normalized EQUALITY. Real answer chunks are far longer than
+ *      the floor, so multi-chunk detection is unaffected.
+ *
+ * Falls back to false (safe: never suppresses a needed redelivery) if history
+ * is not initialised or the query fails — the `answer_redelivered_at` marker is
+ * the second guard against a double-send in that degraded case.
+ */
+export function hasOutboundWithText(
+  chatId: string,
+  text: string,
+  threadId?: number | null,
+  sinceMs?: number,
+): boolean {
+  const needle = normalizeDeliveryText(text)
+  if (needle.length === 0) return false
+  try {
+    // Compare on the normalized prefix so trailing-whitespace / spacer
+    // differences between the rendered outbound and the re-projected answer do
+    // not defeat the match. We fetch candidate assistant rows and normalize in
+    // JS (SQLite lacks the same normalize) — bounded by chat/thread scope.
+    const params: unknown[] = [chatId]
+    let sql = "SELECT text FROM messages WHERE chat_id = ? AND role = 'assistant'"
+    if (threadId !== undefined) {
+      if (threadId === null) {
+        sql += ' AND thread_id IS NULL'
+      } else {
+        sql += ' AND thread_id = ?'
+        params.push(threadId)
+      }
+    }
+    if (sinceMs != null && Number.isFinite(sinceMs)) {
+      // history `ts` is unix SECONDS (recordOutbound); started_at is wall-clock
+      // ms. Scope out any prior turn's rows so an unrelated earlier message can
+      // never satisfy the match.
+      sql += ' AND ts >= ?'
+      params.push(Math.floor(sinceMs / 1000))
+    }
+    // Newest first: a redelivery candidate's match is almost always recent.
+    sql += ' ORDER BY ts DESC LIMIT 500'
+    const rows = requireDb()
+      .prepare(sql)
+      .all(...(params as [unknown, ...unknown[]])) as { text: string | null }[]
+    for (const r of rows) {
+      const hay = normalizeDeliveryText(r.text ?? '')
+      if (hay.length === 0) continue
+      if (deliveryTextMatch(hay, needle)) return true
+    }
+    return false
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Normalize outbound text for durable text-identity delivery matching. Collapses
+ * all whitespace runs to single spaces and trims — so paragraph-spacer / render
+ * differences between a stored outbound and a re-projected transcript answer do
+ * not defeat an otherwise-identical match. Pure; shared by the redelivery path.
+ */
+export function normalizeDeliveryText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Minimum length (of the SHORTER side) at which the bidirectional-prefix rule is
+ * allowed. Below this, a delivery match requires full normalized equality — so a
+ * short final answer can't be falsely suppressed by an unrelated longer row that
+ * merely shares a prefix. Real answer chunks (chunk-1 of a multi-chunk send) are
+ * far longer than this floor, so multi-chunk detection is unaffected.
+ */
+export const MIN_PREFIX_MATCH_CHARS = 40
+
+/**
+ * Text-identity match for the delivery oracle. Exact normalized equality always
+ * matches. The bidirectional-prefix relaxation (which lets a delivered chunk-1
+ * satisfy a longer projected answer, and vice-versa) applies ONLY when the
+ * shorter side is at least `MIN_PREFIX_MATCH_CHARS` — otherwise a short answer
+ * would false-positive against any longer row sharing its prefix. Pure.
+ */
+export function deliveryTextMatch(hay: string, needle: string): boolean {
+  if (hay === needle) return true
+  const shorter = Math.min(hay.length, needle.length)
+  if (shorter < MIN_PREFIX_MATCH_CHARS) return false
+  return hay.startsWith(needle) || needle.startsWith(hay)
+}
+
 export function query(opts: QueryOptions): RecordedMessage[] {
   const limit = Math.min(MAX_LIMIT, Math.max(1, opts.limit ?? DEFAULT_LIMIT))
   const params: unknown[] = [opts.chat_id]