switchroom 0.15.19 → 0.15.21

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

@@ -22,7 +22,7 @@
  * unit-testable without booting the bot.
  */
 
-import type { InjectResult } from '../../src/agents/inject.js'
+import type { EffortApplyResult } from '../../src/agents/effort-picker.js'
 
 /**
  * The effort levels the installed CLI accepts (`claude --help`:
@@ -66,8 +66,14 @@ export function parseEffortCommand(text: string): ParsedEffortCommand | null {
 }
 
 export interface EffortCommandDeps {
-  /** Inject primitive — wired to injectSlashCommand in the gateway. */
-  inject: (agent: string, command: string) => Promise<InjectResult>
+  /**
+   * Apply an effort level to the live session. Wired to `applyEffort`
+   * (src/agents/effort-picker.ts), which types `/effort <level>` AND drives
+   * the "Change effort level?" confirmation modal that claude shows when the
+   * switch would invalidate a cached conversation — so it never wedges the
+   * pane the way a bare inject would.
+   */
+  applyEffort: (agent: string, level: string) => Promise<EffortApplyResult>
   getAgentName: () => string
   /**
    * The agent's cascade-resolved `thinking_effort` from
@@ -76,7 +82,6 @@ export interface EffortCommandDeps {
    */
   getConfiguredEffort: () => string | null
   escapeHtml: (s: string) => string
-  preBlock: (s: string) => string
 }
 
 export interface EffortCommandReply {
@@ -127,52 +132,48 @@ export async function handleEffortCommand(
     return helpText(deps, `not a valid effort level: ${parsed.level}`)
   }
   const verbHtml = `<code>/effort ${deps.escapeHtml(parsed.level)}</code>`
-  let result: InjectResult
+  let result: EffortApplyResult
   try {
-    result = await deps.inject(deps.getAgentName(), `/effort ${parsed.level}`)
+    result = await deps.applyEffort(deps.getAgentName(), parsed.level)
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    return { text: `❌ ${verbHtml} — inject failed: ${deps.escapeHtml(msg)}`, html: true }
+    return { text: `❌ ${verbHtml} — failed: ${deps.escapeHtml(msg)}`, html: true }
   }
+  return { text: applyResultText(parsed.level, result, deps), 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 effort.`,
-        PERSIST_NOTE,
-      ].join('\n'),
-      html: true,
+/**
+ * Render an effort-apply outcome. `confirmed` means a "Change effort level?"
+ * modal was answered — switching mid-conversation re-reads the history, so we
+ * say so honestly rather than just claiming success.
+ */
+function applyResultText(level: string, result: EffortApplyResult, deps: EffortCommandDeps): string {
+  const verbHtml = `<code>/effort ${deps.escapeHtml(level)}</code>`
+  if (result.ok) {
+    const lines = [`✅ ${verbHtml} — ${deps.escapeHtml(result.output)}`]
+    if (result.confirmed) {
+      lines.push('<i>Switched mid-conversation — your next turn re-reads the cached history (slower, one time).</i>')
     }
+    lines.push(PERSIST_NOTE)
+    return lines.join('\n')
   }
-  // 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,
-    }
+  if (result.reason === 'session_missing') {
+    return '❌ tmux session not found — the agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.'
   }
-  return {
-    text: `❌ ${verbHtml} — ${deps.escapeHtml(result.errorMessage ?? 'inject failed')}`,
-    html: true,
+  if (result.reason === 'confirm_failed') {
+    const wedged = result.wedged
+      ? ' The confirmation prompt may still be open on the pane — check it.'
+      : ' The change was cancelled and the pane left as it was.'
+    return `❌ ${verbHtml} — couldn't confirm the switch.${wedged}`
   }
+  // apply_unverified
+  return `❌ ${verbHtml} — sent, but couldn't confirm it applied. The agent may be mid-turn; check <code>/inject /status</code>.`
 }
 
 // ---------------------------------------------------------------------------
 // Button menu — five fixed levels, the live one marked ✅. No live discovery
-// (the levels don't churn) and no picker-driving (the inline `/effort <level>`
-// form sets it directly), so this is far simpler than the /model menu.
+// (the levels don't churn). A tap applies the level via applyEffort, which
+// drives the confirmation modal so it never wedges the pane.
 // ---------------------------------------------------------------------------
 
 export interface EffortMenuKeyboardButton {
@@ -231,9 +232,11 @@ export interface EffortCallbackOutcome {
 }
 
 /**
- * Handle an `eff:*` callback tap. `eff:s:<level>` injects claude's
- * `/effort <level>` and re-renders the menu with a one-line banner and the
- * new level checked. Never throws — failures render as a banner.
+ * Handle an `eff:*` callback tap. `eff:s:<level>` applies the level via
+ * applyEffort (which drives the confirmation modal, so a mid-conversation
+ * switch confirms cleanly instead of wedging the pane) and re-renders the
+ * menu with a one-line banner and the new level checked. Never throws —
+ * failures render as a banner.
  */
 export async function handleEffortMenuCallback(
   data: string,
@@ -249,21 +252,27 @@ export async function handleEffortMenuCallback(
   let banner: string
   let selected: string | undefined
   try {
-    const result = await deps.inject(deps.getAgentName(), `/effort ${level}`)
-    if (result.outcome === 'ok' || result.outcome === 'ok_no_output') {
-      banner = `✅ Effort → <code>${deps.escapeHtml(level)}</code> for this session`
+    const result = await deps.applyEffort(deps.getAgentName(), level)
+    if (result.ok) {
+      banner = result.confirmed
+        ? `✅ Effort → <code>${deps.escapeHtml(level)}</code> (mid-conversation: next turn re-reads history)`
+        : `✅ Effort → <code>${deps.escapeHtml(level)}</code> for this session`
       selected = level
-    } else if (result.errorCode === 'session_missing') {
+    } else if (result.reason === 'session_missing') {
       banner = '❌ tmux session not found — is the agent running under the supervisor?'
+    } else if (result.reason === 'confirm_failed') {
+      banner = result.wedged
+        ? '⚠️ Couldn’t confirm the switch — the prompt may still be open on the pane.'
+        : '❌ Couldn’t confirm the switch — cancelled, effort unchanged.'
     } else {
-      banner = `❌ couldn't set effort: ${deps.escapeHtml(result.errorMessage ?? 'inject failed')}`
+      banner = '❌ Sent, but couldn’t confirm it applied (agent may be mid-turn).'
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    banner = `❌ inject failed: ${deps.escapeHtml(msg)}`
+    banner = `❌ failed: ${deps.escapeHtml(msg)}`
   }
   // Re-render with the just-selected level checked (or the configured
-  // default if the inject failed) and the banner on top.
+  // default if it didn't apply) and the banner on top.
   const menu = buildEffortMenu(deps, selected)
   return {
     reply: { ...menu, text: `${banner}\n${menu.text}` },

package/telegram-plugin/gateway/gateway.ts

@@ -280,6 +280,7 @@ import {
   type EffortCommandDeps,
   type EffortMenuReply,
 } from './effort-command.js'
+import { applyEffort } from '../../src/agents/effort-picker.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'
@@ -438,6 +439,7 @@ import {
   lookupScopedGrant,
   sweepScopedGrants,
 } from '../scoped-approval.js'
+import { grantRestartDecision, type GrantRestartDecision } from './grant-restart.js'
 import { synthesizeAllowRuleDiff, extractAddedAllowRule } from '../permission-diff.js'
 import {
   readClaudeJsonOverage,
@@ -1717,6 +1719,53 @@ function formatFeedElapsed(ms: number): string {
 function turnInFlightForGate(): boolean {
   return isDeliveryCutoverEnabled() ? isMachineInTurn() : claudeBusyKeys.size > 0
 }
+
+/**
+ * Deliver a synthetic "resume" inbound — the wake-up the gateway sends
+ * after an operator approves/denies a vault grant, provides/declines a
+ * requested secret, or completes/fails/discards a vault save — turn-gated
+ * exactly like a real Telegram inbound.
+ *
+ * THE BUG (clerk `hotdoc/credentials`, 2026-06-13): these synthetics did a
+ * raw `ipcServer.sendToAgent` and buffered ONLY on `delivered=false`
+ * (bridge disconnected). But approvals routinely land WHILE the agent's
+ * grant-requesting turn is still finishing — the socket write succeeds
+ * (`delivered=true`) yet claude is mid-turn, so the channel notification
+ * is typed into its TUI composer and stranded by the turn-completion race
+ * (#1556, the lawgpt wedge). `delivered=true` → the buffer never rescued
+ * it → the agent sat idle until the operator manually poked it. Observed:
+ * injection 179ms BEFORE turn_end, then 2 minutes of silence.
+ *
+ * Fix: route through the SAME `decideInboundDelivery` gate the Telegram
+ * `handleInbound` path uses. Mid-turn → `buffer-until-idle` (the
+ * turn-complete hook `releaseTurnBufferGate → drainBufferedIfAllowed`,
+ * plus the idle-drain timer, flush it the instant claude goes idle, where
+ * it lands cleanly as a fresh turn). Idle → deliver now; buffer on a
+ * genuine delivery miss exactly as before. Unlike the cron `inject_inbound`
+ * path (deliberately ungated — at-least-once replay), a one-shot resume
+ * synthetic must never strand, so it IS gated.
+ *
+ * Returns true iff delivered to the bridge now (false = buffered/held;
+ * the caller's forensic log records this as `delivered=false`, which now
+ * means "held mid-turn OR bridge-down" — both are "will flush when idle",
+ * never "dropped").
+ */
+function deliverResumeSyntheticOrBuffer(agent: string, inbound: InboundMessage): boolean {
+  const decision = decideInboundDelivery({
+    turnInFlight: turnInFlightForGate(),
+    isSteering: false,
+    isInterrupt: false,
+  })
+  if (decision === 'buffer-until-idle') {
+    pendingInboundBuffer.push(agent, inbound)
+    return false
+  }
+  const delivered = ipcServer.sendToAgent(agent, inbound)
+  if (delivered) markClaudeBusyForInbound(inbound)
+  else pendingInboundBuffer.push(agent, inbound)
+  return delivered
+}
+
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
 
 // ─── Proactive context compaction (session.max_context_tokens) ──────────
@@ -8907,9 +8956,7 @@ async function captureProvidedSecret(
         stage_id: armed.stageId,
       },
     }
-    const fdelivered = ipcServer.sendToAgent(armed.agent, failMsg)
-    if (fdelivered) markClaudeBusyForInbound(failMsg)
-    else pendingInboundBuffer.push(armed.agent, failMsg)
+    deliverResumeSyntheticOrBuffer(armed.agent, failMsg)
     return true
   }
 
@@ -8942,9 +8989,7 @@ async function captureProvidedSecret(
       stage_id: armed.stageId,
     },
   }
-  const delivered = ipcServer.sendToAgent(armed.agent, synthetic)
-  if (delivered) markClaudeBusyForInbound(synthetic)
-  else pendingInboundBuffer.push(armed.agent, synthetic)
+  const delivered = deliverResumeSyntheticOrBuffer(armed.agent, synthetic)
   process.stderr.write(
     `telegram gateway: secret_provided injection agent=${armed.agent} key=${armed.key} stage=${armed.stageId} delivered=${delivered}\n`,
   )
@@ -9025,9 +9070,7 @@ async function handleSecretRequestCallback(ctx: Context, data: string): Promise<
         stage_id: stageId,
       },
     }
-    const delivered = ipcServer.sendToAgent(pending.agent, synthetic)
-    if (delivered) markClaudeBusyForInbound(synthetic)
-    else pendingInboundBuffer.push(pending.agent, synthetic)
+    deliverResumeSyntheticOrBuffer(pending.agent, synthetic)
     return
   }
 
@@ -13401,6 +13444,54 @@ async function sweepBeforeSelfRestart(): Promise<void> {
   }
 }
 
+/**
+ * Schedule a marker-safe, turn-deferred SELF-restart so a just-persisted
+ * config change ACTUALLY takes effect. claude loads tools / MCP servers /
+ * settings at process start, so a durable "Always allow" write is inert in
+ * the running session until the next restart — the old "restart agent for
+ * full effect" text asked the operator to do this by hand, and most never
+ * did (so the grant didn't stick and the same prompt reappeared). This
+ * completes the flow the operator already approved.
+ *
+ * CALLER-AGENT ONLY (an "Always allow" edits the calling agent's own
+ * `agents.<self>.tools.allow`, a provably single-agent blast radius). The
+ * restart fires when the CURRENT turn completes (via `pendingRestarts`),
+ * never mid-turn — so the operator-approved action finishes first. If no
+ * turn is in flight, it fires immediately after a short drain delay. A
+ * marker is written first so the post-restart greeting lands in the chat
+ * the operator tapped. Kill-switch: `SWITCHROOM_AUTORESTART_ON_GRANT=0`.
+ *
+ * Returns 'disabled' | 'deferred' | 'now'.
+ */
+function scheduleGrantRestart(
+  agentName: string,
+  chatId: string | number | undefined,
+  threadId: number | undefined,
+  reason: string,
+): GrantRestartDecision {
+  const decision = grantRestartDecision({
+    killSwitch: process.env.SWITCHROOM_AUTORESTART_ON_GRANT,
+    selfAgent: process.env.SWITCHROOM_AGENT_NAME,
+    agentName,
+    turnInFlight: turnInFlightForGate(),
+  })
+  if (decision === "disabled") return decision
+  // Marker first → the post-restart greeting lands in the chat the operator
+  // tapped, not the default operator DM.
+  if (chatId != null) {
+    writeRestartMarker({ chat_id: String(chatId), thread_id: threadId ?? null, ack_message_id: null, ts: Date.now() })
+  }
+  stampUserRestartReason(reason)
+  if (decision === "deferred") {
+    pendingRestarts.set(agentName, Date.now()) // fires at turn-complete (marker-safe)
+  } else {
+    // No turn to drain — restart now, after a short delay so this callback's
+    // card edit flushes first.
+    void sweepBeforeSelfRestart().finally(() => triggerSelfRestart(agentName, reason, 1500))
+  }
+  return decision
+}
+
 /**
  * Shape the `switchroom auth ...` CLI stdout into a Telegram-friendly
  * HTML block. Returns the body text AND the OAuth authorize URL (if
@@ -14237,7 +14328,7 @@ bot.command('model', async ctx => {
 // in effort-command.ts so it's unit-testable without booting the bot.
 function buildEffortDeps(): EffortCommandDeps {
   return {
-    inject: injectSlashCommandImpl,
+    applyEffort: (agent, level) => applyEffort(agent, level),
     getAgentName: getMyAgentName,
     getConfiguredEffort: () => {
       type AgentListResp = { agents: Array<{ name: string; thinking_effort?: string | null }> }
@@ -14245,7 +14336,6 @@ function buildEffortDeps(): EffortCommandDeps {
       return data?.agents?.find(a => a.name === getMyAgentName())?.thinking_effort ?? null
     },
     escapeHtml: escapeHtmlForTg,
-    preBlock,
   }
 }
 
@@ -16563,22 +16653,14 @@ async function performVaultAccessApproval(
     stageId,
     operatorId: senderId,
   })
-  const delivered = ipcServer.sendToAgent(pending.agent, synthetic)
-  if (delivered) markClaudeBusyForInbound(synthetic)
+  // Turn-gated via deliverResumeSyntheticOrBuffer: mid-turn → buffer
+  // (flushed at turn-end) so the resume never strands in claude's
+  // composer (#1556); idle → deliver; bridge-down → buffer (#1150).
+  const delivered = deliverResumeSyntheticOrBuffer(pending.agent, synthetic)
   process.stderr.write(
     `telegram gateway: vault_grant_approved injection agent=${pending.agent} ` +
     `key=${pending.key} stage=${stageId} delivered=${delivered}\n`,
   )
-  // #1150 root cause: if `delivered=false` the bridge wasn't connected
-  // at send-time (mid-reconnect, claude-session bouncing between
-  // turns, etc). Pre-fix this just logged + dropped — the agent stayed
-  // idle forever and the operator had to poke. Now we buffer the
-  // inbound so the next bridge-register call drains it. Bounded to
-  // 32 entries per agent (see pending-inbound-buffer.ts) — a never-
-  // reconnecting bridge can't fill memory.
-  if (!delivered) {
-    pendingInboundBuffer.push(pending.agent, synthetic)
-  }
 }
 
 async function handleVaultRequestAccessCallback(ctx: Context, data: string): Promise<void> {
@@ -16644,15 +16726,11 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
       stageId,
       operatorId: senderId,
     })
-    const denyDelivered = ipcServer.sendToAgent(pending.agent, denyInbound)
-    if (denyDelivered) markClaudeBusyForInbound(denyInbound)
+    const denyDelivered = deliverResumeSyntheticOrBuffer(pending.agent, denyInbound)
     process.stderr.write(
       `telegram gateway: vault_grant_denied injection agent=${pending.agent} ` +
       `key=${pending.key} stage=${stageId} delivered=${denyDelivered}\n`,
     )
-    if (!denyDelivered) {
-      pendingInboundBuffer.push(pending.agent, denyInbound)
-    }
     return
   }
 
@@ -16823,13 +16901,11 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
       stageId,
       operatorId: senderId,
     })
-    const dDelivered = ipcServer.sendToAgent(pending.agent, discardInbound)
-    if (dDelivered) markClaudeBusyForInbound(discardInbound)
+    const dDelivered = deliverResumeSyntheticOrBuffer(pending.agent, discardInbound)
     process.stderr.write(
       `telegram gateway: vault_save_discarded injection agent=${pending.agent} ` +
       `key=${pending.key} stage=${stageId} delivered=${dDelivered}\n`,
     )
-    if (!dDelivered) pendingInboundBuffer.push(pending.agent, discardInbound)
     return
   }
 
@@ -16952,13 +17028,11 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
         operatorId: senderId,
         reason: failReason,
       })
-      const fDelivered = ipcServer.sendToAgent(pending.agent, failInbound)
-      if (fDelivered) markClaudeBusyForInbound(failInbound)
+      const fDelivered = deliverResumeSyntheticOrBuffer(pending.agent, failInbound)
       process.stderr.write(
         `telegram gateway: vault_save_failed injection agent=${pending.agent} ` +
         `key=${pending.key} stage=${stageId} delivered=${fDelivered}\n`,
       )
-      if (!fDelivered) pendingInboundBuffer.push(pending.agent, failInbound)
       return
     }
 
@@ -16987,13 +17061,11 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
       stageId,
       operatorId: senderId,
     })
-    const okDelivered = ipcServer.sendToAgent(pending.agent, okInbound)
-    if (okDelivered) markClaudeBusyForInbound(okInbound)
+    const okDelivered = deliverResumeSyntheticOrBuffer(pending.agent, okInbound)
     process.stderr.write(
       `telegram gateway: vault_save_completed injection agent=${pending.agent} ` +
       `key=${pending.key} stage=${stageId} delivered=${okDelivered}\n`,
     )
-    if (!okDelivered) pendingInboundBuffer.push(pending.agent, okInbound)
     return
   }
 
@@ -18622,6 +18694,55 @@ bot.command('version', async ctx => {
 })
 
 
+// /whoami — the operator's view of THIS agent's sandbox (the same
+// `config whoami` the agent itself can call as an MCP tool, and the host CLI
+// exposes). Read-only, isAuthorizedSender-gated like /version — surfaces
+// tools / MCP / vault key-NAMES (never values) / powers so the operator can
+// see at a glance what this agent is authorized for.
+bot.command('whoami', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  try {
+    let raw: string
+    try { raw = switchroomExecCombined(['config', 'whoami'], 10000) }
+    catch (err: unknown) { raw = (err as any).stdout ?? (err as any).message ?? 'whoami failed' }
+    const trimmed = stripAnsi(raw).trim()
+    let card: string
+    try { card = formatWhoamiCard(JSON.parse(trimmed.split('\n').pop() ?? trimmed)) }
+    catch { card = preBlock(formatSwitchroomOutput(trimmed || 'whoami: no output')) }
+    await switchroomReply(ctx, card, { html: true })
+  } catch (err: unknown) {
+    await switchroomReply(ctx, `<b>whoami failed:</b>\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
+  }
+})
+
+/** Compact HTML card from the `config whoami` JSON view. Names/booleans only. */
+function formatWhoamiCard(v: {
+  name?: string; persona?: string | null; model?: string | null; tier?: string;
+  tools?: { allow?: string[]; deny?: string[] }; mcpServers?: string[]; skills?: string[];
+  vault?: { key: string; readable: boolean }[];
+  powers?: { admin?: boolean; root?: boolean; configEdit?: boolean; crossAgentHostVerbs?: boolean };
+  scheduleCount?: number; memoryBackend?: string | null;
+}): string {
+  const esc = escapeHtmlForTg
+  const yn = (b?: boolean) => (b ? '✓' : '✗')
+  const lines: string[] = []
+  lines.push(`👤 <b>${esc(v.name ?? '?')}</b> · ${esc(v.tier ?? 'standard')}`)
+  if (v.persona) lines.push(esc(v.persona))
+  if (v.model) lines.push(`Model: ${esc(v.model)}`)
+  const allow = v.tools?.allow ?? []
+  lines.push(`Tools: ${allow.length ? esc(allow.slice(0, 8).join(', ')) + (allow.length > 8 ? ` …(+${allow.length - 8})` : '') : '—'}`)
+  if ((v.tools?.deny ?? []).length) lines.push(`Denied: ${esc((v.tools!.deny!).join(', '))}`)
+  if ((v.mcpServers ?? []).length) lines.push(`MCP: ${esc(v.mcpServers!.join(', '))}`)
+  if ((v.skills ?? []).length) lines.push(`Skills: ${esc(v.skills!.join(', '))}`)
+  if ((v.vault ?? []).length) {
+    lines.push(`Vault keys (names only): ${v.vault!.map(k => `${esc(k.key)} ${yn(k.readable)}`).join(', ')}`)
+  }
+  const p = v.powers ?? {}
+  lines.push(`Powers: admin ${yn(p.admin)} · root ${yn(p.root)} · config-edit ${yn(p.configEdit)} · cross-agent verbs ${yn(p.crossAgentHostVerbs)}`)
+  lines.push(`Schedule: ${v.scheduleCount ?? 0} cron · Memory: ${esc(v.memoryBackend ?? 'none')}`)
+  return lines.join('\n')
+}
+
 bot.command('commands', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   await switchroomReply(ctx, buildSwitchroomHelpText(getMyAgentName()), { html: true })
@@ -19356,10 +19477,26 @@ bot.on('callback_query:data', async ctx => {
 
     const ok = durable
     const legacyNote = legacy && durable
+    // Make the durable grant LIVE: config_propose_edit's apply already
+    // regenerated the scaffold (settings.json with the new tools.allow), so a
+    // marker-safe, turn-deferred self-restart loads it — no more "restart by
+    // hand" hint that the operator ignores (leaving the grant inert until the
+    // next bounce). Only on the hostd-durable path (scaffold currency assured);
+    // legacy path keeps the manual hint. Self-agent only; kill-switch
+    // SWITCHROOM_AUTORESTART_ON_GRANT=0.
+    const restartScheduled =
+      ok && !legacy &&
+      scheduleGrantRestart(
+        agentName,
+        ctx.chat?.id,
+        (ctx.callbackQuery?.message as { message_thread_id?: number } | undefined)?.message_thread_id,
+        `always-allow: ${grantPhrase}`,
+      ) !== "disabled"
+    const liveSuffix = restartScheduled ? " — applying now (restarting to take effect)" : ""
     const ackText = ok
       ? (legacyNote
           ? `✅ Saved. ${agentName} can now ${grantPhrase} without asking (legacy path).`
-          : `✅ Saved. ${agentName} can now ${grantPhrase} without asking.`)
+          : `✅ Saved. ${agentName} can now ${grantPhrase} without asking.${liveSuffix}`)
       : (editLockHint
           ? `⚠️ Allowed for now — config edits are locked. Enable hostd.config_edit_enabled.`
           : `⚠️ Allowed for now, but "always" did NOT save — it will ask again after restart. Check gateway log.`)
@@ -19376,7 +19513,9 @@ bot.on('callback_query:data', async ctx => {
     const editLabel = ok
       ? (legacyNote
           ? `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking (legacy path); restart agent for full effect`
-          : `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking; restart agent for full effect`)
+          : restartScheduled
+            ? `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking — applying now (restarting to take effect).`
+            : `✅ <b>${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}</b> without asking; restart agent for full effect`)
       : (editLockHint
           ? `⚠️ <b>Allowed for now — "always" did NOT save.</b> Config edits are locked; enable <code>hostd.config_edit_enabled</code>.`
           : `⚠️ <b>Allowed for now — "always" did NOT save.</b> It will ask again after restart. Check gateway log.`)

package/telegram-plugin/gateway/grant-restart.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure decision for the "make a just-persisted grant LIVE" self-restart
+ * (the side-effecting `scheduleGrantRestart` in gateway.ts wraps this).
+ *
+ * Extracted so the gating — kill-switch, self-agent-only, and
+ * turn-deferred-vs-now — unit-tests without gateway.ts's boot side-effects
+ * (same pattern as scoped-approval.ts / admin-commands/index.ts).
+ *
+ * Contract (reference/access-model.md): the restart only ever follows an
+ * operator-approved, single-agent, additive `tools.allow` edit, and only
+ * ever bounces the CALLER's own agent — never a peer, never fleet-wide.
+ */
+export type GrantRestartDecision = "disabled" | "deferred" | "now";
+
+export function grantRestartDecision(opts: {
+  /** SWITCHROOM_AUTORESTART_ON_GRANT value ("0" disables; default on). */
+  killSwitch: string | undefined;
+  /** The gateway's own agent identity ($SWITCHROOM_AGENT_NAME). */
+  selfAgent: string | undefined;
+  /** The agent whose config was edited (must equal selfAgent — self only). */
+  agentName: string;
+  /** Whether a turn is currently in flight (defer the restart to its end). */
+  turnInFlight: boolean;
+}): GrantRestartDecision {
+  if ((opts.killSwitch ?? "") === "0") return "disabled";
+  // Self-only: an "Always allow" edits agents.<self>.tools.allow. We never
+  // bounce a peer or the fleet from this path.
+  if (!opts.selfAgent || opts.selfAgent !== opts.agentName) return "disabled";
+  return opts.turnInFlight ? "deferred" : "now";
+}