switchroom 0.19.1 → 0.19.3

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

@@ -188,6 +188,293 @@ export function classifyModelSwitchConfirmation(input: {
   return { kind: 'default', launched: revertedTo }
 }
 
+/**
+ * Diagnostic stderr lines for a /model apply-boot rehydration.
+ * Pure strings so gateway.ts stays thin (line-ratchet #2996).
+ */
+export function formatModelRelaunchDiagLog(input: {
+  agent: string
+  launched: string
+  configured: string
+  confirmation: ModelSwitchConfirmation | null
+  isApplyBoot: boolean
+}): string {
+  const { agent, launched, configured, confirmation, isApplyBoot } = input
+  const L = launched || '(none)'
+  if (confirmation == null) {
+    return (
+      'telegram gateway: gw /model relaunch applied agent=' +
+      agent +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' override=' +
+      (isApplyBoot ? 'set' : 'cleared') +
+      '\n'
+    )
+  }
+  if (confirmation.kind === 'not-applied') {
+    return (
+      'telegram gateway: gw /model relaunch NOT-APPLIED agent=' +
+      agent +
+      ' target=' +
+      confirmation.target +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' revertedTo=' +
+      confirmation.revertedTo +
+      '\n'
+    )
+  }
+  if (confirmation.kind === 'applied') {
+    return (
+      'telegram gateway: gw /model relaunch applied agent=' +
+      agent +
+      ' launched=' +
+      L +
+      ' configured=' +
+      configured +
+      ' override=set outcome=applied\n'
+    )
+  }
+  return (
+    'telegram gateway: gw /model relaunch applied agent=' +
+    agent +
+    ' launched=' +
+    L +
+    ' configured=' +
+    configured +
+    ' override=cleared outcome=default\n'
+  )
+}
+
+/** Telegram body for the single switch-confirmation card (F1/N4). */
+export function formatModelSwitchConfirmationBody(
+  confirmation: ModelSwitchConfirmation,
+): string {
+  if (confirmation.kind === 'applied') {
+    return (
+      '✅ Now running `' +
+      confirmation.launched +
+      '` — session-only, reverts to the configured model on the next restart. Fresh session; memory and the handoff briefing carry the context.'
+    )
+  }
+  if (confirmation.kind === 'not-applied') {
+    return (
+      "⚠️ Your switch to `" +
+      confirmation.target +
+      "` didn't apply — the agent reverted to `" +
+      confirmation.revertedTo +
+      "` (the apply-boot didn't complete). Re-issue `/model " +
+      confirmation.target +
+      "` to try again."
+    )
+  }
+  return (
+    '✅ Now running `' +
+    confirmation.launched +
+    '` (the configured default) — fresh session; memory and the handoff briefing carry the context.'
+  )
+}
+
+export function formatModelRelaunchSuppressNotAppliedLog(input: {
+  agent: string
+  target: string
+}): string {
+  return (
+    'telegram gateway: gw /model relaunch NOT-APPLIED — suppressing not-applied confirmation (a .session-model-alert is present and will be relayed) agent=' +
+    input.agent +
+    ' target=' +
+    input.target +
+    '\n'
+  )
+}
+
+/**
+ * The single boot-time notification decision for a classified /model switch
+ * (#3427 item 2): either the ONE confirmation card (green applied/default or
+ * the ⚠️ not-applied warn), or — LOW-2 dedup — a suppress log when start.sh
+ * wrote a TAILORED `.session-model-alert` for this boot that already explains
+ * why the switch didn't apply (the alert relay is the more specific message,
+ * so the generic not-applied card would double-warn). Pure so the decision is
+ * unit-testable end-to-end (classify → notice) without booting the gateway;
+ * gateway.ts only sends `card` bodies / writes `suppress` logs.
+ */
+export type ModelSwitchBootNotice =
+  | { kind: 'card'; body: string }
+  | { kind: 'suppress'; log: string }
+
+export function resolveModelSwitchBootNotice(input: {
+  agent: string
+  confirmation: ModelSwitchConfirmation
+  hasSessionModelAlert: boolean
+}): ModelSwitchBootNotice {
+  const { agent, confirmation, hasSessionModelAlert } = input
+  if (confirmation.kind === 'not-applied' && hasSessionModelAlert) {
+    return {
+      kind: 'suppress',
+      log: formatModelRelaunchSuppressNotAppliedLog({ agent, target: confirmation.target }),
+    }
+  }
+  return { kind: 'card', body: formatModelSwitchConfirmationBody(confirmation) }
+}
+
+/**
+ * Requested-vs-served divergence gate (#3427 item 4). `--fallback-model` masks
+ * a shape-valid but UNKNOWN requested Claude id: claude silently serves the
+ * fallback while `.active-session-model` (and the boot confirmation) carry the
+ * requested token, until the first assistant transcript line reclaims /status.
+ * That window used to self-heal SILENTLY — the operator was never told their
+ * requested id was bogus. This comparator lets the session-model source flag
+ * the divergence deterministically at the FIRST possible post-launch signal
+ * (the first assistant line's `message.model`).
+ *
+ * Deliberately conservative — return true ("matches") whenever the pair is not
+ * DETERMINISTICALLY comparable, so a false accusation is impossible:
+ *   - served non-`claude-*` ids (sr-* / LiteLLM-mapped names) are skipped: the
+ *     proxy may echo an alias, a mapped id, or the raw route name;
+ *   - a requested alias (opus/sonnet/haiku/fable) family-matches its resolved
+ *     full id (`sonnet` ≡ `claude-sonnet-5-…`) via modelFamilyToken;
+ *   - a requested full `claude-*` id must be served exactly, or as a
+ *     date-stamped descendant (`claude-sonnet-5` ≡ `claude-sonnet-5-20260203`);
+ *   - anything else (sr-* requests, legacy friendly labels like "Opus 4.8")
+ *     is not comparable → true.
+ */
+export function servedModelMatchesRequested(requested: string, served: string): boolean {
+  const req = requested.trim().toLowerCase()
+  const srv = served.trim().toLowerCase()
+  if (!srv.startsWith('claude-')) return true
+  if ((MODEL_ALIASES as readonly string[]).includes(req)) {
+    if (req === 'default') return true
+    if (modelFamilyToken(srv) === req) return true
+    // L3 (#3437 review): legacy id shapes put the family AFTER the version
+    // (`claude-3-opus-20240229` → first segment "3", not "opus"). Accept any
+    // dash-segment equal to the alias — widens toward "match" only, so it can
+    // suppress a real accusation in weird shapes but never create a false one.
+    return srv.slice('claude-'.length).split('-').includes(req)
+  }
+  if (req.startsWith('claude-')) {
+    return srv === req || srv.startsWith(req + '-')
+  }
+  return true
+}
+
+/**
+ * Greppable stderr line for a requested-vs-served divergence (#3427 item 4).
+ * Names BOTH candidate causes (M2): `--fallback-model` substitutes for an
+ * invalid/unknown id AND for a transiently-unavailable one — the signal alone
+ * cannot distinguish them, so the log must not assert "invalid".
+ */
+export function formatServedModelDivergenceLog(input: {
+  agent: string
+  requested: string
+  served: string
+}): string {
+  return (
+    'telegram gateway: gw /model served-model DIVERGENCE agent=' +
+    input.agent +
+    ' requested=' +
+    input.requested +
+    ' served=' +
+    input.served +
+    ' (--fallback-model substituted: requested id invalid/unknown OR model transiently unavailable)\n'
+  )
+}
+
+/** Operator card for a requested-vs-served divergence (#3427 item 4, M2-softened). */
+export function formatServedModelDivergenceCard(input: {
+  requested: string
+  served: string
+}): string {
+  return (
+    '⚠️ The first reply was served by `' +
+    input.served +
+    '`, not the requested `' +
+    input.requested +
+    '` — claude substituted the fallback model. Either the requested id is invalid/unknown, or the model was temporarily unavailable for that call (a transient substitution self-corrects on later replies). If it persists, re-issue `/model <valid id>` or `/model default`. `/status` always shows the model actually serving calls.'
+  )
+}
+
+/** The boot marker chat that initiated a /model switch (thread-aware). */
+export interface ModelBootCardTarget {
+  chatId: string
+  threadId: number | null
+}
+
+/**
+ * Injected side-effect surface for the boot-time /model cards (#3427): the
+ * served-model divergence warn and the switch confirmation share ONE raw
+ * Markdown send closure plus a stderr log sink. Lives here (not inline in
+ * gateway.ts's boot IIFE) so gateway.ts does not inflate (#2996 ratchet).
+ */
+export interface ModelBootCardDeps {
+  agent: string
+  /** null → no initiating chat known; cards are skipped, logs still write. */
+  chat: ModelBootCardTarget | null
+  log: (line: string) => void
+  sendCard: (
+    chatId: string,
+    body: string,
+    opts: { parse_mode: 'Markdown'; message_thread_id?: number },
+  ) => Promise<unknown>
+}
+
+/** One-shot fire-and-forget card to the marker chat; send failures log, never throw. */
+function sendModelBootCard(deps: ModelBootCardDeps, chat: ModelBootCardTarget, body: string, failLabel: string): void {
+  void deps
+    .sendCard(chat.chatId, body, {
+      parse_mode: 'Markdown',
+      ...(chat.threadId != null ? { message_thread_id: chat.threadId } : {}),
+    })
+    .catch((err: unknown) =>
+      deps.log(`telegram gateway: ${failLabel} send failed: ${(err as Error)?.message ?? String(err)}\n`),
+    )
+}
+
+/**
+ * Build the divergence-tripwire handler gateway.ts registers at the boot
+ * rehydration site (#3427 item 4): the first LIVE assistant line serving a
+ * different model (invalid id OR transient unavailability — --fallback-model
+ * substituted) logs + warns the operator. The override is KEPT (M2): freshness
+ * rules already make /status show the served model, and a transient
+ * substitution self-corrects without destroying the switch record.
+ */
+export function buildServedModelDivergenceHandler(
+  deps: ModelBootCardDeps,
+): (d: { requested: string; served: string }) => void {
+  return (d) => {
+    deps.log(formatServedModelDivergenceLog({ agent: deps.agent, requested: d.requested, served: d.served }))
+    if (deps.chat == null) return
+    sendModelBootCard(deps, deps.chat, formatServedModelDivergenceCard(d), 'served-model divergence')
+  }
+}
+
+/**
+ * Deliver the boot-time model-switch confirmation (#3427 item 2): resolve the
+ * card-vs-suppress decision (pure — resolveModelSwitchBootNotice) and either
+ * log the suppress line or send the card. No-op when no initiating chat is
+ * known — matching the pre-extraction inline gateway.ts behavior (the
+ * suppress log only ever wrote when a marker chat existed).
+ */
+export function deliverModelSwitchBootNotice(
+  deps: ModelBootCardDeps & { confirmation: ModelSwitchConfirmation; hasSessionModelAlert: boolean },
+): void {
+  if (deps.chat == null) return
+  const notice = resolveModelSwitchBootNotice({
+    agent: deps.agent,
+    confirmation: deps.confirmation,
+    hasSessionModelAlert: deps.hasSessionModelAlert,
+  })
+  if (notice.kind === 'suppress') {
+    deps.log(notice.log)
+    return
+  }
+  sendModelBootCard(deps, deps.chat, notice.body, 'model-switch confirmation')
+}
+
 export type ParsedModelCommand =
   | { kind: 'show' }
   | { kind: 'set'; model: string }
@@ -528,6 +815,23 @@ function relaunchErrorReply(
   return { text: `❌ Could not schedule model switch: ${deps.escapeHtml(msg)}`, html: true }
 }
 
+/**
+ * Fail-fast caveat (#3427 item 4) for a free-text full `claude-*` id: the
+ * gateway cannot pre-validate an arbitrary id against the API (Claude-native
+ * constraint — no raw API probes), so if the id is bogus `--fallback-model`
+ * silently serves the fallback. Say so IMMEDIATELY in the switch ack, and
+ * point at the first-reply tripwire that will catch it. Aliases and sr-* ids
+ * are vouched by their own gates (MODEL_ALIASES / the LiteLLM route probe),
+ * so only typed `claude-*` ids carry the caveat. Exported for tests.
+ */
+export function unvalidatedIdCaveat(
+  deps: Pick<ModelCommandDeps, 'escapeHtml'>,
+  model: string,
+): string | null {
+  if (!model.trim().toLowerCase().startsWith('claude-')) return null
+  return `_\`${deps.escapeHtml(model)}\` can't be validated before launch — if it isn't a real Claude model id, claude will silently serve the configured fallback model instead. I check the first reply and will warn if that happens._`
+}
+
 /** Schedule a carrier relaunch onto `model`, returning the deterministic ack. */
 async function scheduleRelaunchReply(
   deps: ModelCommandDeps,
@@ -539,7 +843,11 @@ async function scheduleRelaunchReply(
   } catch (err) {
     return relaunchErrorReply(deps, model, err)
   }
-  return { text: [switchingLine(deps, model), PERSIST_NOTE].join('\n'), html: true }
+  const caveat = unvalidatedIdCaveat(deps, model)
+  return {
+    text: [switchingLine(deps, model), ...(caveat ? [caveat] : []), PERSIST_NOTE].join('\n'),
+    html: true,
+  }
 }
 
 /** Schedule the `/model default` clear + revert relaunch, returning its ack. */

package/telegram-plugin/gateway/narrative-lane.ts

@@ -389,7 +389,18 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
             // 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.
+            // behaviour, never blocks the card opening (writeActivityCardRecord
+            // → persistActivityCards swallows write errors — it never throws).
+            //
+            // F6 (persist-intent-first ordering): this write is the FIRST action
+            // taken after the send resolves and BEFORE the status-pin reconcile
+            // below — no `await` sits between the send and this persist, so the
+            // crash window in which a sent card has no durable record (and is
+            // thus unreapable by the boot reaper) is the minimum achievable. A
+            // true pre-send provisional record is impossible: the reaper keys
+            // its finalizing edit on `activityMessageId`, which only exists once
+            // sendRichMessage returns. Keep this persist synchronous and ahead
+            // of the pin; do not move it after an await.
             if (activityCardPersistEnabled) {
               writeActivityCardRecord(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs, {
                 turnKey: statusKey(chat, thread),
@@ -397,15 +408,18 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
                 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
+                // F5 (persist-intent honesty): 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 persist is intentionally
+                // written BEFORE the fire-and-forget pin resolves (intent, not
+                // outcome); the reaper's unpin is idempotent defense-in-depth
                 // (`statusPinBootCleanup` owns the primary unpin), so tracking
-                // the flag honestly is what matters here.
+                // the DECISION honestly — pinned iff we will actually attempt a
+                // pin — is what matters here, not the async pin's result.
                 pinned: PIN_STATUS_WHILE_WORKING,
               })
             }

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -53,7 +53,11 @@ import { resolveChatIdFallback } from './chat-id-fallback.js'
 import { isFinalAnswerReply, isSubstantiveFinalReply } from '../final-answer-detect.js'
 import { decideOverPing, type OverPingDecision } from '../over-ping-safety-net.js'
 import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
-import { decideSupersedeCorrection, type FlushedTurnSupersedeRegistry } from '../flushed-turn-supersede.js'
+import {
+  decideSupersedeCorrection,
+  flushedAnswerMatchesReply,
+  type FlushedTurnSupersedeRegistry,
+} from '../flushed-turn-supersede.js'
 import { decideAnswerLatchSuppression } from '../reply-owner-resolve.js'
 import { deriveTelegraphTitle } from '../telegraph.js'
 import {
@@ -872,10 +876,16 @@ export async function sendReply(
     // resolvers agree and the late-reply supersede fires by identity.
     const ownerTurn = resolveReplyOwnerTurn(turn, chat_id, args)
     const resolvedTurnId = ownerTurn?.turnId ?? null
+    // #3429 — pass the (normalized) reply text so the registry can apply the
+    // new-content gate: identity match + TTL alone also fits an async handback
+    // that merely resolved this flush-delivered ENDED turn as its owner via
+    // the latest-ended tier. Editing the flushed message in place with that
+    // handback's text does not re-notify client-side (Telegram edits never
+    // push) — the observed silent non-surfacing of msgs 10482/10486.
     const decision = flushedTurnSupersede.take(
       chat_id,
       replyThreadId,
-      { liveTurnId: resolvedTurnId, now: Date.now() },
+      { liveTurnId: resolvedTurnId, replyText: text, now: Date.now() },
     )
     if (decision.supersede) {
       process.stderr.write(
@@ -899,20 +909,31 @@ export async function sendReply(
       // resolves the same ended owner turn, sees the latch, and is suppressed —
       // exactly one message ever ships. The latch is idempotent and the normal
       // (no-throw) path is unaffected: the correction below still ships B once.
-      if (ownerTurn != null) ownerTurn.answerDelivered = true
+      // Tagged 'flush' (#3426): a flush record existed for this turn (take()
+      // just consumed it), so the flushed message A is what the suppression
+      // protects against duplicating. #3429: stash the record's flushed text
+      // alongside, so the retry's latch check can discriminate by content —
+      // the retry of THIS superseding reply matches and stays suppressed, while
+      // a later genuinely-new handback does not and delivers.
+      if (ownerTurn != null) {
+        ownerTurn.answerDelivered = 'flush'
+        if (decision.recordText != null) ownerTurn.flushedAnswerText = decision.recordText
+      }
     } else {
       // 2026-07 double-reply-on-DM fix (Part 2) — answer-delivered race latch.
       // Supersede found no record. Either there was no flush (normal reply), or
       // the flush FIRED but has not yet recorded its message ids (the residual
       // pre-record race Part 1's supersede cannot reach). The flush sets
-      // `answerDelivered = true` synchronously at fire time (before its async
-      // send AND before `record`), and it persists on the ended turn — so when
-      // this LATE, substantive reply resolves its owner turn and sees the latch
-      // already set, the flush's message A is already on its way out and this
-      // reply would ship a duplicate. Suppress it. Scoped to the substantive
-      // ≥`FLUSH_SUBSTANTIVE_MIN_CHARS` floor and the late-reply case so an
-      // interim sub-floor ack, a chunked multi-part answer, or a legitimate
-      // second in-turn substantive reply (live `currentTurn`) is never
+      // `answerDelivered = 'flush'` synchronously at fire time (before its
+      // async send AND before `record`), and it persists on the ended turn — so
+      // when this LATE, substantive reply resolves its owner turn and sees the
+      // FLUSH-armed latch, the flush's message A is already on its way out and
+      // this reply would ship a duplicate. Suppress it. Scoped to the
+      // substantive ≥`FLUSH_SUBSTANTIVE_MIN_CHARS` floor, the late-reply case,
+      // AND the 'flush' latch source (#3426) so an interim sub-floor ack, a
+      // chunked multi-part answer, a legitimate second in-turn substantive
+      // reply (live `currentTurn`), or an async sub-agent handback landing
+      // after a reply-delivered turn ended (latch = 'reply') is never
       // suppressed. `isSubstantiveFinalReply` reduces to the ≥200-char test on
       // the `reply` path (no `done`); pass the model's original notification
       // intent to mirror the #2533 decoupling call shape.
@@ -920,12 +941,33 @@ export async function sendReply(
         text: rawText,
         disableNotification: args.disable_notification === true,
       })
+      // #3429 — content evidence for the latch. `'new-content'` is the
+      // registry's POSITIVE determination that this reply differs from the
+      // flushed answer (record present, identity matched, text did not);
+      // otherwise compare against the owner turn's stashed `flushedAnswerText`
+      // (covers the post-fire pre-record race window, where no record exists
+      // yet but the fire site already stamped what it is delivering). Null —
+      // no flushed text to compare — keeps the conservative pre-#3429
+      // flush-armed suppression.
+      const replyMatchesFlushedAnswer: boolean | null =
+        decision.reason === 'new-content'
+          ? false
+          : ownerTurn?.flushedAnswerText != null
+            ? flushedAnswerMatchesReply(ownerTurn.flushedAnswerText, text)
+            : null
       const suppressByLatch = decideAnswerLatchSuppression({
         superseded: false,
         replySubstantive,
         isLateReply: turn == null,
         ownerAnswerDelivered: ownerTurn?.answerDelivered ?? false,
+        replyMatchesFlushedAnswer,
       })
+      if (decision.reason === 'new-content') {
+        process.stderr.write(
+          `telegram gateway: reply: flush supersede declined — new content (#3429) ` +
+          `chatId=${chat_id} ownerTurnId=${JSON.stringify(resolvedTurnId)}; sending fresh\n`,
+        )
+      }
       if (suppressByLatch) {
         process.stderr.write(
           `telegram gateway: reply: suppressed by answer-delivered latch ` +
@@ -934,11 +976,22 @@ export async function sendReply(
         )
         return { content: [{ type: 'text', text: 'sent (deduped — answer already delivered via turn-flush)' }] }
       }
-      // A substantive answer is going out via this reply — set the latch on its
-      // owner turn so a later bridge-replayed / reworded duplicate of the same
-      // answer is caught by the branch above.
+      // A substantive answer is going out via this reply — record it on the
+      // owner turn, tagged 'reply' (#3426). The 'reply' tag does NOT trip the
+      // late-reply suppression above: a later reply attributed to this turn
+      // after it ends (the async sub-agent handback pattern — dispatch, interim
+      // ack, turn_end, handback with no live gateway turn) is genuinely new
+      // content and must deliver. Byte-identical replays of THIS answer are
+      // deduped by the content-keyed #546 cache at the top of this function.
+      // Honest bound: the dedup TTL (60 s) is anchored at reply RECORD time,
+      // while the latest-ended owner tier's 60 s is anchored at `endedAt` —
+      // later by the reply→turn_end gap. A byte-identical replay landing >60 s
+      // after record but ≤60 s after endedAt is evicted from dedup yet still
+      // resolves this ended turn, so it now DELIVERS as a duplicate message.
+      // Conscious trade: a rare duplicate beats the silent handback drop the
+      // boolean latch caused (#3426).
       if (replySubstantive && ownerTurn != null) {
-        ownerTurn.answerDelivered = true
+        ownerTurn.answerDelivered = 'reply'
       }
     }
   }

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

@@ -20,6 +20,28 @@
  * whichever was observed last. A fresh assistant line always reclaims the
  * transcript as the source; a confirmed switch always beats an older
  * transcript line. Pinned by tests/session-model-source.test.ts.
+ *
+ * Divergence tripwire (#3427 item 4): `--fallback-model` masks an invalid
+ * requested model id — claude silently serves the fallback while the override
+ * carries the requested token. The FIRST live transcript observation of the
+ * post-relaunch session is therefore the earliest deterministic verification
+ * point: when the injected comparator says the served id does NOT satisfy the
+ * requested token, the registered divergence handler fires (once per armed
+ * override) so the gateway can log + warn instead of self-healing silently.
+ *
+ * Two false-positive guards (#3437 review H1/H2 — "a false accusation must be
+ * impossible" is the contract, enforced HERE, not by caller discipline):
+ *   - H1: verification arms ONLY on an explicit `setOverride(model,
+ *     { verify: true })` — the boot-rehydration site, where the override IS
+ *     the launched token of the session now serving. A command-time
+ *     `setOverride(model)` (the pre-restart status-honesty record in
+ *     scheduleModelRelaunch) must NOT arm: an assistant line landing in the
+ *     pre-restart window is served by the OLD model and would false-mismatch
+ *     the NEW requested token.
+ *   - H2: observations flagged `replayed: true` (the session-tail's
+ *     first-attach replay of a prior session's in-flight turn — OLD-model
+ *     lines delivered AFTER boot) neither consume nor fire verification;
+ *     the tripwire waits for the first LIVE observation.
  */
 
 export interface SessionModelResolution {
@@ -30,14 +52,45 @@ export interface SessionModelResolution {
   source: 'transcript' | 'override'
 }
 
+/** The first live post-override assistant line served a different model (#3427). */
+export interface SessionModelDivergence {
+  /** The override token the operator requested (`/model <token>`). */
+  requested: string
+  /** The transcript's `message.model` — the model actually serving calls. */
+  served: string
+}
+
+export interface SessionModelSourceOptions {
+  /**
+   * Comparator for the divergence tripwire: does `served` (a resolved
+   * transcript id) satisfy `requested` (the override token)? Must be
+   * CONSERVATIVE — return true when the pair is not deterministically
+   * comparable (see servedModelMatchesRequested in model-command.ts).
+   * Absent → the tripwire never fires (verification is skipped).
+   */
+  servedMatchesRequested?: (requested: string, served: string) => boolean
+}
+
 export interface SessionModelSource {
-  /** Record a transcript observation (an assistant line's `message.model`,
-   *  already sentinel-filtered by the session-tail projection). */
-  noteTranscriptModel(model: string): void
-  /** Record an override set (a positively-confirmed /model switch), or clear
-   *  it with null. Setting stamps a fresh sequence, so the override wins over
-   *  every EARLIER transcript observation until a new assistant line lands. */
-  setOverride(model: string | null): void
+  /**
+   * Record a transcript observation (an assistant line's `message.model`,
+   * already sentinel-filtered by the session-tail projection). Pass
+   * `replayed: true` for lines delivered by the session-tail's first-attach
+   * replay (a PRIOR session's in-flight turn): they still update /status
+   * freshness exactly as before, but are excluded from divergence
+   * verification (H2 — they carry the pre-relaunch model).
+   */
+  noteTranscriptModel(model: string, opts?: { replayed?: boolean }): void
+  /**
+   * Record an override set (a positively-confirmed /model switch), or clear
+   * it with null. Setting stamps a fresh sequence, so the override wins over
+   * every EARLIER transcript observation until a new assistant line lands.
+   * `verify: true` additionally ARMS divergence verification for this
+   * override — pass it ONLY when the override is the launched token of the
+   * session currently serving (the boot-rehydration site). Default: not
+   * armed (H1 — command-time/rollback sets must never arm).
+   */
+  setOverride(model: string | null, opts?: { verify?: boolean }): void
   /** Current override value (the #2982 in-memory record), independent of
    *  freshness — for callers that need the override itself (e.g. the model
    *  menu's "session" marker), not the /status resolution. */
@@ -45,18 +98,42 @@ export interface SessionModelSource {
   /** The freshest observation across both sources, or null when neither has
    *  reported yet. */
   resolve(): SessionModelResolution | null
+  /** Register the handler fired when the first LIVE transcript observation
+   *  after an ARMED override fails the comparator (#3427 item 4). At most
+   *  once per armed override; null unregisters. Replaces any prior handler. */
+  setDivergenceHandler(handler: ((d: SessionModelDivergence) => void) | null): void
 }
 
-export function createSessionModelSource(): SessionModelSource {
+export function createSessionModelSource(
+  options: SessionModelSourceOptions = {},
+): SessionModelSource {
   let seq = 0
   let transcript: { model: string; seq: number } | null = null
   let override: { model: string; seq: number } | null = null
+  // True while an ARMED ({ verify: true }) non-null override awaits its first
+  // LIVE transcript observation. Consumed (set false) on that observation
+  // whether or not it diverges, so the handler fires at most once per armed
+  // override. Replayed observations neither consume nor fire (H2).
+  let overrideUnverified = false
+  let onDivergence: ((d: SessionModelDivergence) => void) | null = null
   return {
-    noteTranscriptModel(model: string): void {
+    noteTranscriptModel(model: string, opts?: { replayed?: boolean }): void {
       transcript = { model, seq: ++seq }
+      if (opts?.replayed === true) return // H2: pre-relaunch line — no verification
+      if (override != null && overrideUnverified) {
+        overrideUnverified = false
+        const matches = options.servedMatchesRequested
+        if (matches != null && !matches(override.model, model)) {
+          onDivergence?.({ requested: override.model, served: model })
+        }
+      }
     },
-    setOverride(model: string | null): void {
+    setOverride(model: string | null, opts?: { verify?: boolean }): void {
       override = model == null ? null : { model, seq: ++seq }
+      // H1: only an explicit verify-arm (the boot-rehydration site) starts
+      // verification; a plain set (command-time record, rollback restore)
+      // clears any pending arm — its token is NOT what is serving right now.
+      overrideUnverified = model != null && opts?.verify === true
     },
     getOverride(): string | null {
       return override?.model ?? null
@@ -69,5 +146,8 @@ export function createSessionModelSource(): SessionModelSource {
       }
       return { model: transcript.model, source: 'transcript' }
     },
+    setDivergenceHandler(handler: ((d: SessionModelDivergence) => void) | null): void {
+      onDivergence = handler
+    },
   }
 }