switchroom 0.15.0 → 0.15.2

package/telegram-plugin/gateway/gateway.ts

@@ -157,7 +157,7 @@ import {
   formatModelUnavailableCard,
   resolveModelUnavailableFromOperatorEvent,
 } from '../model-unavailable.js'
-import { runFleetAutoFallback } from '../auto-fallback-fleet.js'
+import { runFleetAutoFallback, renderFallbackFailureNotice, evaluateFallbackFailureNotice, type FallbackFailureNoticeState } from '../auto-fallback-fleet.js'
 import { startRestartWatchdog } from './restart-watchdog.js'
 import { validateStringArray } from './access-validator.js'
 
@@ -258,6 +258,7 @@ import { DEFAULT_SLOT } from '../../src/auth/accounts.js'
 import { currentActiveSlot, type AuthCodeOutcome } from '../../src/auth/manager.js'
 import { injectSlashCommand as injectSlashCommandImpl } from '../../src/agents/inject.js'
 import { handleInjectCommand } from './inject-handler.js'
+import { parseModelCommand, handleModelCommand } from './model-command.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig, findConfigFile as findSwitchroomConfigFile } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
@@ -422,6 +423,9 @@ import {
   saveQuotaWatchState,
   patchQuotaWatchState,
   emptyAccountState,
+  resolveQuotaWatchTuning,
+  buildQuotaClaimKey,
+  QUOTA_WATCH_CLAIM_WINDOW_MS,
 } from '../quota-watch.js'
 import { buildSnapshotsFromState, buildSnapshotsFromCachedState } from '../auth-snapshot-format.js'
 import {
@@ -13918,6 +13922,30 @@ bot.command('inject', async ctx => {
   })
 })
 
+// /model — show or switch the Claude model for this agent's live
+// session. The argument form rides the same allowlisted inject
+// primitive as /inject (claude's native `/model <name>` REPL command);
+// the bare form never injects (the no-arg picker is an undriveable TUI
+// modal from Telegram). Implementation in model-command.ts so it's
+// unit-testable without booting the bot.
+bot.command('model', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
+  const parsed = parseModelCommand(text) ?? { kind: 'show' as const }
+  const reply = await handleModelCommand(parsed, {
+    inject: injectSlashCommandImpl,
+    getAgentName: getMyAgentName,
+    getConfiguredModel: () => {
+      type AgentListResp = { agents: Array<{ name: string; model?: string | null }> }
+      const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
+      return data?.agents?.find(a => a.name === getMyAgentName())?.model ?? null
+    },
+    escapeHtml: escapeHtmlForTg,
+    preBlock,
+  })
+  await switchroomReply(ctx, reply.text, { html: reply.html })
+})
+
 bot.command('agentstart', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
@@ -14804,6 +14832,51 @@ async function fireFleetAutoFallback(triggerAgent: string, untilMs?: number): Pr
   )
 }
 
+/**
+ * Broadcast a fleet-fallback FAILURE notice to every authorized chat.
+ *
+ * Why this exists: the model-unavailable card renders "Auto-failover in
+ * progress — see the announcement below" BEFORE the dispatcher's outcome
+ * is known. When the dispatcher errors (broker down, listState throw,
+ * markExhausted failure), the success announcement never lands and the
+ * card's promise is broken — the 2026-06-06→07 incident sent 12 such
+ * broken-promise cards while every fallback errored "set-active requires
+ * admin". The admin-gating root cause is fixed (#2206), but ANY future
+ * dispatcher error reproduces the broken promise. This notice closes the
+ * loop deterministically: card promised an announcement → an
+ * announcement ALWAYS arrives, success or failure.
+ *
+ * Disable with SWITCHROOM_FLEET_FALLBACK_FAILURE_NOTICE=0 (log-only,
+ * pre-fix behaviour).
+ */
+let fallbackFailureNoticeState: FallbackFailureNoticeState = { lastSentAtMs: 0 }
+
+function broadcastFleetFallbackFailure(triggerAgent: string, reason: string): void {
+  if (process.env.SWITCHROOM_FLEET_FALLBACK_FAILURE_NOTICE === '0') return
+  // Notice-level cooldown (30 min, per gateway). The fleetFallbackGate's
+  // dedup window only arms on SUCCESSFUL swaps, so it bounds nothing
+  // here — and the card-less quota_wall_detected trigger re-fires every
+  // ~60s during a wall. Without this, a persistent broker outage would
+  // stream failure notices for days. See evaluateFallbackFailureNotice.
+  const verdict = evaluateFallbackFailureNotice(fallbackFailureNoticeState, Date.now())
+  if (!verdict.send) {
+    process.stderr.write(
+      `telegram gateway: [fleet-fallback] failure notice suppressed (cooldown) agent=${triggerAgent}: ${reason}\n`,
+    )
+    return
+  }
+  fallbackFailureNoticeState = verdict.next
+  const access = loadAccess()
+  if (access.allowFrom.length === 0) return
+  const html = renderFallbackFailureNotice(triggerAgent, reason)
+  for (const chat_id of access.allowFrom) {
+    void swallowingApiCall(
+      () => bot.api.sendMessage(chat_id, html, { parse_mode: 'HTML' as const }),
+      { chat_id, verb: 'fleet-fallback:failure-notify' },
+    )
+  }
+}
+
 /** Returns true iff the dispatcher actually performed a swap (and the
  *  user-visible announcement was broadcast). False on no-op /
  *  error / idempotent-skip — caller uses this to decide whether to
@@ -14815,6 +14888,9 @@ async function doFireFleetAutoFallback(triggerAgent: string, untilMs?: number):
       process.stderr.write(
         `telegram gateway: [fleet-fallback] skipped agent=${triggerAgent} reason=no-broker-client\n`,
       )
+      // The model-unavailable card may have promised an announcement —
+      // keep the promise even though nothing could run.
+      broadcastFleetFallbackFailure(triggerAgent, 'auth-broker unreachable (no client).')
       return false
     }
     const state = await client.listState()
@@ -14878,6 +14954,10 @@ async function doFireFleetAutoFallback(triggerAgent: string, untilMs?: number):
     process.stderr.write(
       `telegram gateway: [fleet-fallback] error agent=${triggerAgent}: ${(err as Error)?.message ?? err}\n`,
     )
+    // Keep the card's "see the announcement below" promise on the error
+    // path — the 06-06→07 incident sent 12 cards whose promised
+    // announcement never arrived because this catch was log-only.
+    broadcastFleetFallbackFailure(triggerAgent, (err as Error)?.message ?? String(err))
     return false
   }
 }
@@ -14969,9 +15049,34 @@ async function runCreditWatch(): Promise<void> {
  * State persists across restarts via `<stateDir>/quota-watch.json`.
  * Mirrors runCreditWatch's structure and notification routing.
  */
-async function runQuotaWatch(): Promise<void> {
+
+/**
+ * Ask the broker for the fleet-wide dedup claim on one notification key.
+ * FAIL-OPEN on any error: a broker that predates the `claim-notification`
+ * op (skewed rollout) rejects at the protocol layer, and a transient IPC
+ * failure must degrade to duplicated notifications, never dropped ones.
+ */
+async function claimQuotaNotification(
+  brokerClient: NonNullable<Awaited<ReturnType<typeof getAuthBrokerClient>>>,
+  key: string,
+): Promise<boolean> {
+  try {
+    const res = await brokerClient.claimNotification(key, QUOTA_WATCH_CLAIM_WINDOW_MS)
+    return res.granted
+  } catch (err) {
+    process.stderr.write(`telegram gateway: quota-watch: claim failed (fail-open): ${err}\n`)
+    return true
+  }
+}
+
+async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
   const agentName = getMyAgentName()
   const stateDir = STATE_DIR
+  const bootTick = opts.bootTick ?? false
+  // Hardening knobs (2026-06-09 incident: fleet bounce released stale
+  // recovery latches on all 11 agents at once → 26 duplicate sends).
+  // See QuotaWatchTuning in quota-watch.ts for the env contract.
+  const tuning = resolveQuotaWatchTuning(process.env)
 
   // Read broker state. The listState response now includes last_quota
   // per account — the broker's in-memory cache from previous probeQuota
@@ -15019,6 +15124,20 @@ async function runQuotaWatch(): Promise<void> {
     })
     if (fleetDecision.kind === 'notify') {
       for (const chat_id of access.allowFrom) {
+        // Fleet-level dedup: all 11 gateways detect this same edge within
+        // one poll cycle — only the broker-claim winner sends per chat.
+        if (tuning.fleetDedup) {
+          const granted = await claimQuotaNotification(
+            brokerClient,
+            buildQuotaClaimKey(FLEET_ALL_EXHAUSTED_KEY, fleetDecision.transition, chat_id),
+          )
+          if (!granted) {
+            process.stderr.write(
+              `telegram gateway: quota-watch: fleet-all-exhausted claim denied chat=${chat_id} — another agent notified\n`,
+            )
+            continue
+          }
+        }
         await swallowingApiCall(
           () =>
             bot.api.sendMessage(chat_id, fleetDecision.message, {
@@ -15056,10 +15175,21 @@ async function runQuotaWatch(): Promise<void> {
     snapshots.map((s, i) => [s.label, i]),
   )
 
+  // Reconciled transitions: state advances (latch clears) but nothing is
+  // sent — boot-tick and late recoveries (see QuotaWatchDecision docs).
+  let reconciledCount = 0
+  let mutatedState = watchState
+
   for (const snap of snapshots) {
     const prev = watchState[snap.label] ?? emptyAccountState()
-    const decision = evaluateQuotaWatchAccount({ agentName, snap, prev, now })
-    if (decision.kind !== 'skip') {
+    const decision = evaluateQuotaWatchAccount({ agentName, snap, prev, now, bootTick, tuning })
+    if (decision.kind === 'reconcile') {
+      mutatedState = patchQuotaWatchState(mutatedState, decision.accountLabel, decision.newAccountState)
+      reconciledCount++
+      process.stderr.write(
+        `telegram gateway: quota-watch: reconciled ${decision.transition} for account=${decision.accountLabel} (${decision.reason}) — no notification\n`,
+      )
+    } else if (decision.kind !== 'skip') {
       pendingTransitions.push({
         accountLabel: snap.label,
         snapIndex: labelToSnapIndex.get(snap.label) ?? -1,
@@ -15069,7 +15199,16 @@ async function runQuotaWatch(): Promise<void> {
   }
 
   if (pendingTransitions.length === 0) {
-    return // Steady-state: no notifications, no probes, no state write.
+    // Steady-state: no notifications, no probes. Persist only if a
+    // reconcile advanced the latch (otherwise no state write at all).
+    if (reconciledCount > 0) {
+      try {
+        saveQuotaWatchState(stateDir, mutatedState)
+      } catch (err) {
+        process.stderr.write(`telegram gateway: quota-watch state persist failed: ${err}\n`)
+      }
+    }
+    return
   }
 
   // Transition detected: probe ONLY the crossing accounts to get fresh
@@ -15083,16 +15222,31 @@ async function runQuotaWatch(): Promise<void> {
       freshProbeMap.set(entry.label, entry.result)
     }
   } catch (err) {
-    // Probe failed — still send notifications using cached data.
-    // Don't abort: the user should know about the threshold crossing
-    // even if the message body shows slightly stale numbers.
     process.stderr.write(`telegram gateway: quota-watch: probe for crossing accounts failed: ${err}\n`)
+    if (!tuning.sendOnProbeFail) {
+      // A quota notification must never carry numbers we could not verify
+      // live. Leave the crossing accounts' state untouched — the
+      // transition re-evaluates (and re-probes) on the next 15-min tick.
+      // Persist any reconciles already applied, then bail.
+      if (reconciledCount > 0) {
+        try {
+          saveQuotaWatchState(stateDir, mutatedState)
+        } catch (saveErr) {
+          process.stderr.write(`telegram gateway: quota-watch state persist failed: ${saveErr}\n`)
+        }
+      }
+      process.stderr.write(
+        `telegram gateway: quota-watch: deferring ${pendingTransitions.length} notification(s) until probe succeeds\n`,
+      )
+      return
+    }
+    // Legacy (SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL=1): fall through
+    // and send from cached data.
   }
 
   // Build final notifications, enriching the snapshot with fresh probe
   // data where available.
-  let mutatedState = watchState
-  const notifications: Array<{ message: string; accountLabel: string }> = []
+  const notifications: Array<{ message: string; accountLabel: string; transition: string }> = []
 
   for (const { accountLabel, snapIndex, decision } of pendingTransitions) {
     // Re-evaluate with fresh probe data to get an accurate message body.
@@ -15100,37 +15254,88 @@ async function runQuotaWatch(): Promise<void> {
     const freshResult = freshProbeMap.get(accountLabel)
     let enrichedDecision = decision
     // pendingTransitions only ever holds notify decisions (pushed under
-    // `decision.kind !== 'skip'`). Narrow explicitly so `decision.transition`
-    // type-checks below; this continue never fires at runtime.
+    // `decision.kind !== 'skip'` / `!== 'reconcile'`). Narrow explicitly so
+    // `decision.transition` type-checks below; this continue never fires
+    // at runtime.
     if (decision.kind !== 'notify') continue
     if (freshResult && freshResult.ok && snapIndex >= 0) {
-      const enrichedSnap = { ...snapshots[snapIndex]!, quota: freshResult.data }
+      // Live numbers replace the cache — and capturedAtMs is cleared so the
+      // staleness gate never misfires on data we JUST probed.
+      const enrichedSnap = { ...snapshots[snapIndex]!, quota: freshResult.data, capturedAtMs: undefined }
       const prev = watchState[accountLabel] ?? emptyAccountState()
-      const re = evaluateQuotaWatchAccount({ agentName, snap: enrichedSnap, prev, now })
+      const re = evaluateQuotaWatchAccount({ agentName, snap: enrichedSnap, prev, now, bootTick, tuning })
       // If the fresh probe still shows the same transition, use the
       // enriched message. If it no longer shows a transition (e.g. the
       // account recovered in the 100ms between listState and probe),
       // fall through to skip this notification.
       if (re.kind === 'notify' && re.transition === decision.transition) {
         enrichedDecision = re
+      } else if (re.kind === 'reconcile') {
+        // Fresh data confirms the transition but it isn't news (boot-tick /
+        // late recovery) — advance the latch silently.
+        mutatedState = patchQuotaWatchState(mutatedState, accountLabel, re.newAccountState)
+        reconciledCount++
+        process.stderr.write(
+          `telegram gateway: quota-watch: reconciled ${re.transition} for account=${accountLabel} (${re.reason}) — no notification\n`,
+        )
+        continue
       } else if (re.kind === 'skip') {
         // State normalised by the time of the probe — don't notify.
         continue
       }
+    } else if (!tuning.sendOnProbeFail) {
+      // No verified fresh data for this account (per-account probe failure
+      // or label missing from the batch result). Same rule as the batch
+      // throw above: never send unverified numbers. State untouched —
+      // re-evaluated (and re-probed) next tick.
+      process.stderr.write(
+        `telegram gateway: quota-watch: probe unavailable for account=${accountLabel} — deferring notification\n`,
+      )
+      continue
     }
 
     if (enrichedDecision.kind !== 'notify') continue
-    notifications.push({ message: enrichedDecision.message, accountLabel })
+    notifications.push({
+      message: enrichedDecision.message,
+      accountLabel,
+      transition: enrichedDecision.transition,
+    })
     mutatedState = patchQuotaWatchState(mutatedState, accountLabel, enrichedDecision.newAccountState)
   }
 
   if (notifications.length === 0) {
-    return // All transitions resolved by the time of the live probe.
+    // All transitions resolved/deferred by the time of the live probe.
+    // Reconciles may still have advanced the latch — persist those.
+    if (reconciledCount > 0) {
+      try {
+        saveQuotaWatchState(stateDir, mutatedState)
+      } catch (err) {
+        process.stderr.write(`telegram gateway: quota-watch state persist failed: ${err}\n`)
+      }
+    }
+    return
   }
 
   // Send all notifications (one message per crossing account).
-  for (const { message, accountLabel } of notifications) {
+  for (const { message, accountLabel, transition } of notifications) {
     for (const chat_id of access.allowFrom) {
+      // Fleet-level dedup: every agent gateway independently detects the
+      // same account transition within one poll cycle. The broker claim
+      // grants exactly one sender per (account, transition, chat) per
+      // window — the other ten agents advance their local state silently.
+      // Fail-open on claim error (see claimQuotaNotification).
+      if (tuning.fleetDedup) {
+        const granted = await claimQuotaNotification(
+          brokerClient,
+          buildQuotaClaimKey(accountLabel, transition, chat_id),
+        )
+        if (!granted) {
+          process.stderr.write(
+            `telegram gateway: quota-watch: claim denied account=${accountLabel} chat=${chat_id} — another agent notified\n`,
+          )
+          continue
+        }
+      }
       // Quota-watch notify — best-effort. Wrap via swallowingApiCall so
       // flood-wait / deleted-chat / not-found surface as a stderr log
       // rather than a thrown exception that aborts the loop and leaves
@@ -15260,9 +15465,11 @@ bot.command('connect', async ctx => {
   let isAdmin = false
   try {
     const cfg = loadSwitchroomConfig()
-    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean }> })
+    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean; root?: boolean }> })
       ?.agents?.[getMyAgentName()]
-    isAdmin = me?.admin === true
+    // `root: true` (the root-tier debugging agent) is above admin and
+    // carries admin authority — see docs/root-agent.md.
+    isAdmin = me?.admin === true || me?.root === true
   } catch { /* non-admin is the safe default */ }
   if (!isAuthAdmin({ isAdmin })) {
     await switchroomReply(
@@ -15422,8 +15629,10 @@ bot.command("auth", async ctx => {
   let isAdmin = false
   try {
     const cfg = loadSwitchroomConfig()
-    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean }> })?.agents?.[currentAgent]
-    isAdmin = me?.admin === true
+    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean; root?: boolean }> })?.agents?.[currentAgent]
+    // `root: true` (the root-tier debugging agent) is above admin and
+    // carries admin authority — see docs/root-agent.md.
+    isAdmin = me?.admin === true || me?.root === true
   } catch { /* best-effort — non-admin is the safe default */ }
 
   // `/auth add` and `/auth cancel` are gateway-routed (drive a
@@ -20453,7 +20662,12 @@ void (async () => {
           // settle after boot (avoids a probe race with the boot-card
           // quota probe that fires in the first few seconds).
           setTimeout(() => {
-            void runQuotaWatch().catch((err) => {
+            // bootTick: recovery edges observed on the FIRST post-boot tick
+            // reconcile silently — a fleet bounce synchronizes all agents'
+            // first ticks, and a just-booted gateway can't tell "just
+            // recovered" from "recovered while we were down" (the
+            // 2026-06-09 26-message flood). Warnings still notify.
+            void runQuotaWatch({ bootTick: true }).catch((err) => {
               process.stderr.write(`telegram gateway: quota-watch initial run failed: ${err}\n`)
             })
           }, 30_000)

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

@@ -0,0 +1,182 @@
+/**
+ * Telegram `/model` command — show or switch the Claude model for this
+ * agent's live session.
+ *
+ * `/model` (bare) shows the configured model and the switch options.
+ * It deliberately NEVER injects the bare `/model` verb into the claude
+ * pane: with no argument the CLI renders an interactive picker modal
+ * that nothing on the Telegram side can drive (no arrow keys, no Esc),
+ * which would wedge the pane — the same TUI-modal class of wedge as
+ * the /rate-limit-options incident. Only the argument form is ever
+ * injected.
+ *
+ * `/model <alias|full-id>` types claude's own `/model <name>` into the
+ * agent's tmux pane via the existing allowlisted inject primitive
+ * (`src/agents/inject.ts` — `/model` is already on the allowlist) and
+ * relays the captured response. This is the Claude-native mechanism:
+ * the unmodified CLI's REPL command, no API, no SDK, no config
+ * mutation. The switch is session-scoped — it lasts until the agent
+ * restarts; persisting requires `model:` in switchroom.yaml (cascade)
+ * and a restart, which the reply spells out.
+ *
+ * Split parser/handler shape mirrors `auth-command.ts` so the logic is
+ * unit-testable without booting the bot.
+ */
+
+import type { InjectResult } from '../../src/agents/inject.js'
+
+/**
+ * Aliases the claude CLI resolves natively. Listed in help text only —
+ * the handler does NOT restrict to these (a full model id like
+ * `claude-opus-4-8` passes through and claude itself validates it, so
+ * new aliases/models work without a switchroom release).
+ */
+export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'default'] as const
+
+/**
+ * Shape gate for the model argument. This string is typed literally
+ * into the agent's tmux pane, so the gate is strict by construction:
+ * one token, alphanumeric start, then alphanumerics plus the chars
+ * that appear in real model ids (`.` `_` `-` and the `[1m]`-style
+ * variant brackets). No whitespace means no second token can ride
+ * along; no control characters means no newline/Enter smuggling.
+ */
+const MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._\[\]-]{0,99}$/
+
+export function isValidModelArg(arg: string): boolean {
+  return MODEL_ARG_RE.test(arg)
+}
+
+export type ParsedModelCommand =
+  | { kind: 'show' }
+  | { kind: 'set'; model: string }
+  | { kind: 'help'; reason?: string }
+
+/**
+ * Parse a `/model` message. Returns null when the text isn't a /model
+ * command at all (caller bug — bot.command should pre-filter).
+ */
+export function parseModelCommand(text: string): ParsedModelCommand | null {
+  const m = text.match(/^\/model(?:@[A-Za-z0-9_]+)?(?:\s+([\s\S]*))?$/)
+  if (!m) return null
+  const rest = (m[1] ?? '').trim()
+  if (rest.length === 0) return { kind: 'show' }
+  const parts = rest.split(/\s+/)
+  if (parts.length > 1) {
+    return { kind: 'help', reason: 'model takes a single argument' }
+  }
+  const arg = parts[0]
+  if (arg.toLowerCase() === 'help') return { kind: 'help' }
+  if (!isValidModelArg(arg)) {
+    return { kind: 'help', reason: `not a valid model name: ${arg}` }
+  }
+  return { kind: 'set', model: arg }
+}
+
+export interface ModelCommandDeps {
+  /** Inject primitive — wired to injectSlashCommand in the gateway. */
+  inject: (agent: string, command: string) => Promise<InjectResult>
+  getAgentName: () => string
+  /**
+   * The agent's configured model from `switchroom agent list` (the
+   * cascade-resolved `model:` field). Null when unset / unreadable —
+   * rendered as "default".
+   */
+  getConfiguredModel: () => string | null
+  escapeHtml: (s: string) => string
+  preBlock: (s: string) => string
+}
+
+export interface ModelCommandReply {
+  text: string
+  html: true
+}
+
+const PERSIST_NOTE =
+  '<i>Session-only — lasts until restart. To persist, set <code>model:</code> in switchroom.yaml and restart.</i>'
+
+function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
+  const lines: string[] = []
+  if (reason) lines.push(`⚠️ ${deps.escapeHtml(reason)}`)
+  lines.push(
+    '<b>/model</b> — show or switch the Claude model',
+    '<code>/model</code> — show the configured model',
+    `<code>/model &lt;name&gt;</code> — switch the live session (${MODEL_ALIASES.map(a => `<code>${a}</code>`).join(' · ')} or a full model id)`,
+    PERSIST_NOTE,
+  )
+  return { text: lines.join('\n'), html: true }
+}
+
+export async function handleModelCommand(
+  parsed: ParsedModelCommand,
+  deps: ModelCommandDeps,
+): Promise<ModelCommandReply> {
+  if (parsed.kind === 'help') return helpText(deps, parsed.reason)
+
+  if (parsed.kind === 'show') {
+    const configured = deps.getConfiguredModel()
+    const shown = configured && configured.length > 0 ? configured : 'default'
+    return {
+      text: [
+        `<b>Model — ${deps.escapeHtml(deps.getAgentName())}</b>`,
+        `Configured: <code>${deps.escapeHtml(shown)}</code>`,
+        `Switch the live session: ${MODEL_ALIASES.map(a => `<code>/model ${a}</code>`).join(' · ')}`,
+        'or <code>/model &lt;full-model-id&gt;</code>',
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+
+  // kind === 'set' — re-gate at the seam so a caller that skipped the
+  // parser can't type arbitrary keys into the pane.
+  if (!isValidModelArg(parsed.model)) {
+    return helpText(deps, `not a valid model name: ${parsed.model}`)
+  }
+  const verbHtml = `<code>/model ${deps.escapeHtml(parsed.model)}</code>`
+  let result: InjectResult
+  try {
+    result = await deps.inject(deps.getAgentName(), `/model ${parsed.model}`)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      text: `❌ ${verbHtml} — inject failed: ${deps.escapeHtml(msg)}`,
+      html: true,
+    }
+  }
+
+  if (result.outcome === 'ok') {
+    return {
+      text: [
+        `${verbHtml}`,
+        deps.preBlock(result.output),
+        ...(result.truncated ? ['<i>truncated</i>'] : []),
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+
+  if (result.outcome === 'ok_no_output') {
+    return {
+      text: [
+        `${verbHtml} — sent, but no response captured. The agent may be mid-turn; check <code>/inject /status</code> to confirm the active model.`,
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+    }
+  }
+
+  // outcome === 'failed'
+  if (result.errorCode === 'session_missing') {
+    return {
+      text:
+        '❌ tmux session not found — the agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.',
+      html: true,
+    }
+  }
+  return {
+    text: `❌ ${verbHtml} — ${deps.escapeHtml(result.errorMessage ?? 'inject failed')}`,
+    html: true,
+  }
+}