switchroom 0.15.20 → 0.15.22

package/dist/cli/switchroom.js

@@ -50477,8 +50477,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.15.20";
-var COMMIT_SHA = "0b63ab9e";
+var VERSION = "0.15.22";
+var COMMIT_SHA = "a6c13429";
 
 // src/cli/agent.ts
 init_source();

package/dist/host-control/main.js

@@ -20817,6 +20817,85 @@ function stripCallerAllow(cfg, caller) {
   return clone;
 }
 
+// src/host-control/config-blast-radius.ts
+function toObject2(v) {
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+function changedConfigPaths(before, after, prefix = "") {
+  if (deepEqual(before, after))
+    return [];
+  const bObj = before && typeof before === "object" && !Array.isArray(before);
+  const aObj = after && typeof after === "object" && !Array.isArray(after);
+  if (bObj && aObj) {
+    const keys = new Set([
+      ...Object.keys(before),
+      ...Object.keys(after)
+    ]);
+    const out = [];
+    for (const k of keys) {
+      out.push(...changedConfigPaths(before[k], after[k], prefix ? `${prefix}.${k}` : k));
+    }
+    return out;
+  }
+  return [prefix || "<root>"];
+}
+function deepEqual(a, b) {
+  if (a === b)
+    return true;
+  if (typeof a !== typeof b)
+    return false;
+  if (a && b && typeof a === "object") {
+    if (Array.isArray(a) !== Array.isArray(b))
+      return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length)
+        return false;
+      return a.every((x, i) => deepEqual(x, b[i]));
+    }
+    const ao = a;
+    const bo = b;
+    const keys = new Set([...Object.keys(ao), ...Object.keys(bo)]);
+    for (const k of keys)
+      if (!deepEqual(ao[k], bo[k]))
+        return false;
+    return true;
+  }
+  return false;
+}
+function classifyBlastRadius(beforeYaml, afterYaml) {
+  let before;
+  let after;
+  try {
+    before = toObject2($parse(beforeYaml));
+    after = toObject2($parse(afterYaml));
+  } catch {
+    return { agents: [], fleetWide: true, changedPaths: ["<unparseable>"] };
+  }
+  const changedPaths = changedConfigPaths(before, after).sort();
+  if (changedPaths.length === 0) {
+    return { agents: [], fleetWide: false, changedPaths: [] };
+  }
+  const agents = new Set;
+  let fleetWide = false;
+  for (const path2 of changedPaths) {
+    if (path2 === "<root>") {
+      fleetWide = true;
+      continue;
+    }
+    const segs = path2.split(".");
+    if (segs[0] === "agents" && segs.length >= 2) {
+      agents.add(segs[1]);
+    } else {
+      fleetWide = true;
+    }
+  }
+  return {
+    agents: fleetWide ? [] : [...agents].sort(),
+    fleetWide,
+    changedPaths
+  };
+}
+
 // src/host-control/server.ts
 function resolveDigests(imageRefs) {
   const out = new Map;
@@ -21509,7 +21588,12 @@ class HostdServer {
       const runner = this.opts.runReconcile ?? (async () => this.runSwitchroom(["apply"]));
       const recRes = await runner({ requestId: approvalId });
       if (recRes.exit_code === 0) {
-        await approval.finalize({ outcome: "applied" });
+        const blast = classifyBlastRadius(snapshot, postApply);
+        await approval.finalize({
+          outcome: "applied",
+          affectedAgents: blast.agents,
+          fleetWide: blast.fleetWide
+        });
         return {
           v: 1,
           request_id: req.request_id,
@@ -21893,7 +21977,9 @@ class SocketApprovalGateway {
             type: "request_config_finalize",
             requestId: req.requestId,
             outcome: outcome.outcome,
-            ...outcome.detail ? { detail: outcome.detail } : {}
+            ...outcome.detail ? { detail: outcome.detail } : {},
+            ...outcome.affectedAgents ? { affectedAgents: outcome.affectedAgents } : {},
+            ...outcome.fleetWide !== undefined ? { fleetWide: outcome.fleetWide } : {}
           }) + `
 `);
           client2.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.15.20",
+  "version": "0.15.22",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -31013,6 +31013,7 @@ __export(exports_config_approval_handler, {
   parseConfigApprovalCallback: () => parseConfigApprovalCallback,
   handleRequestConfigFinalize: () => handleRequestConfigFinalize,
   handleRequestConfigApproval: () => handleRequestConfigApproval,
+  buildLiveNote: () => buildLiveNote,
   buildConfigApprovalCardBody: () => buildConfigApprovalCardBody,
   _resetPendingConfigApprovalsForTest: () => _resetPendingConfigApprovalsForTest,
   _peekPendingConfigApprovalForTest: () => _peekPendingConfigApprovalForTest,
@@ -31156,6 +31157,22 @@ async function resolvePendingConfigApproval(requestId, verdict, deps) {
   }
   return true;
 }
+function buildLiveNote(affectedAgents, fleetWide) {
+  if (fleetWide) {
+    return `
+
+\u26a0\ufe0f Shared config changed \u2014 affects all agents. Not live until they ` + `restart: run <code>switchroom rollout</code> (or <code>/update apply</code>).`;
+  }
+  const agents = (affectedAgents ?? []).filter((a) => typeof a === "string" && a.length > 0);
+  if (agents.length === 0)
+    return "";
+  const list2 = agents.map(escapeHtml12).join(", ");
+  const cmds = agents.map((a) => `/restart ${escapeHtml12(a)}`).join(" \u00b7 ");
+  return `
+
+\uD83D\uDD04 Not live until restart \u2014 affects: <b>${list2}</b>
+${cmds}`;
+}
 async function handleRequestConfigFinalize(_client, msg, deps) {
   const entry = pending.get(msg.requestId);
   if (!entry) {
@@ -31163,8 +31180,9 @@ async function handleRequestConfigFinalize(_client, msg, deps) {
     return;
   }
   pending.delete(msg.requestId);
+  const liveNote = msg.outcome === "applied" ? buildLiveNote(msg.affectedAgents, msg.fleetWide) : "";
   const body = msg.outcome === "applied" ? `\u2705 <b>Applied</b>${msg.detail ? `
-${escapeHtml12(msg.detail)}` : ""}` : `\u26a0\ufe0f <b>Reconcile failed; rolled back</b>${msg.detail ? `
+${escapeHtml12(msg.detail)}` : ""}${liveNote}` : `\u26a0\ufe0f <b>Reconcile failed; rolled back</b>${msg.detail ? `
 ${escapeHtml12(msg.detail)}` : ""}`;
   try {
     await deps.editCard({
@@ -45454,43 +45472,32 @@ async function handleEffortCommand(parsed, deps) {
   const verbHtml = `<code>/effort ${deps.escapeHtml(parsed.level)}</code>`;
   let result;
   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: `\u274c ${verbHtml} \u2014 inject failed: ${deps.escapeHtml(msg)}`, html: true };
+    return { text: `\u274c ${verbHtml} \u2014 failed: ${deps.escapeHtml(msg)}`, html: true };
   }
-  if (result.outcome === "ok") {
-    return {
-      text: [
-        `${verbHtml}`,
-        deps.preBlock(result.output),
-        ...result.truncated ? ["<i>truncated</i>"] : [],
-        PERSIST_NOTE2
-      ].join(`
-`),
-      html: true
-    };
+  return { text: applyResultText(parsed.level, result, deps), html: true };
+}
+function applyResultText(level, result, deps) {
+  const verbHtml = `<code>/effort ${deps.escapeHtml(level)}</code>`;
+  if (result.ok) {
+    const lines = [`\u2705 ${verbHtml} \u2014 ${deps.escapeHtml(result.output)}`];
+    if (result.confirmed) {
+      lines.push("<i>Switched mid-conversation \u2014 your next turn re-reads the cached history (slower, one time).</i>");
+    }
+    lines.push(PERSIST_NOTE2);
+    return lines.join(`
+`);
   }
-  if (result.outcome === "ok_no_output") {
-    return {
-      text: [
-        `${verbHtml} \u2014 sent, but no response captured. The agent may be mid-turn; check <code>/inject /status</code> to confirm the active effort.`,
-        PERSIST_NOTE2
-      ].join(`
-`),
-      html: true
-    };
+  if (result.reason === "session_missing") {
+    return "\u274c tmux session not found \u2014 the agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.";
   }
-  if (result.errorCode === "session_missing") {
-    return {
-      text: "\u274c tmux session not found \u2014 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 === "confirm_failed") {
+    const wedged = result.wedged ? " The confirmation prompt may still be open on the pane \u2014 check it." : " The change was cancelled and the pane left as it was.";
+    return `\u274c ${verbHtml} \u2014 couldn't confirm the switch.${wedged}`;
   }
-  return {
-    text: `\u274c ${verbHtml} \u2014 ${deps.escapeHtml(result.errorMessage ?? "inject failed")}`,
-    html: true
-  };
+  return `\u274c ${verbHtml} \u2014 sent, but couldn't confirm it applied. The agent may be mid-turn; check <code>/inject /status</code>.`;
 }
 var EFFORT_CALLBACK_PREFIX = "eff:";
 var EFFORT_CALLBACK_SELECT = "eff:s:";
@@ -45531,18 +45538,20 @@ async function handleEffortMenuCallback(data, deps) {
   let banner;
   let selected;
   try {
-    const result = await deps.inject(deps.getAgentName(), `/effort ${level}`);
-    if (result.outcome === "ok" || result.outcome === "ok_no_output") {
-      banner = `\u2705 Effort \u2192 <code>${deps.escapeHtml(level)}</code> for this session`;
+    const result = await deps.applyEffort(deps.getAgentName(), level);
+    if (result.ok) {
+      banner = result.confirmed ? `\u2705 Effort \u2192 <code>${deps.escapeHtml(level)}</code> (mid-conversation: next turn re-reads history)` : `\u2705 Effort \u2192 <code>${deps.escapeHtml(level)}</code> for this session`;
       selected = level;
-    } else if (result.errorCode === "session_missing") {
+    } else if (result.reason === "session_missing") {
       banner = "\u274c tmux session not found \u2014 is the agent running under the supervisor?";
+    } else if (result.reason === "confirm_failed") {
+      banner = result.wedged ? "\u26a0\ufe0f Couldn\u2019t confirm the switch \u2014 the prompt may still be open on the pane." : "\u274c Couldn\u2019t confirm the switch \u2014 cancelled, effort unchanged.";
     } else {
-      banner = `\u274c couldn't set effort: ${deps.escapeHtml(result.errorMessage ?? "inject failed")}`;
+      banner = "\u274c Sent, but couldn\u2019t confirm it applied (agent may be mid-turn).";
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    banner = `\u274c inject failed: ${deps.escapeHtml(msg)}`;
+    banner = `\u274c failed: ${deps.escapeHtml(msg)}`;
   }
   const menu = buildEffortMenu(deps, selected);
   return {
@@ -45552,6 +45561,80 @@ ${menu.text}` },
   };
 }
 
+// ../src/agents/effort-picker.ts
+var CONFIRM_RE = /Change effort level\?/i;
+function appliedRe(level) {
+  return new RegExp(`${level}\\s*\\u00b7\\s*/effort`);
+}
+function applyLine(pane, level) {
+  const re = new RegExp(`Set effort level to ${level}\\b.*`, "i");
+  for (const line of pane.split(`
+`)) {
+    const m = line.match(re);
+    if (m)
+      return m[0].trim();
+  }
+  return `Set effort level to ${level}`;
+}
+var realSleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+async function applyEffort(agentName3, level, opts = {}) {
+  const runner = opts._runner ?? makeTmuxRunner2(opts.tmuxBin ?? "tmux");
+  const socket = opts.socketName ?? `switchroom-${agentName3}`;
+  const session = opts.sessionName ?? agentName3;
+  const stepMs = opts.stepMs ?? 600;
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const sleep2 = opts._sleep ?? realSleep2;
+  const log = opts._log ?? ((line) => process.stderr.write(`${line}
+`));
+  if (!runner.hasSession(socket, session)) {
+    return { ok: false, reason: "session_missing" };
+  }
+  return withPaneLock(`${socket}:${session}`, async () => {
+    const startedAt = Date.now();
+    const expired2 = () => Date.now() - startedAt >= timeoutMs;
+    try {
+      runner.send(socket, session, ["send-keys", "-l", `/effort ${level}`]);
+      runner.send(socket, session, ["send-keys", "Enter"]);
+      let confirmed = false;
+      let confirmKeys = 0;
+      while (!expired2()) {
+        await sleep2(stepMs);
+        const pane = runner.capture(socket, session) ?? "";
+        if (CONFIRM_RE.test(pane)) {
+          if (confirmKeys >= 2) {
+            runner.send(socket, session, ["send-keys", "Escape"]);
+            await sleep2(stepMs);
+            const after = runner.capture(socket, session) ?? "";
+            log(`effort-picker: confirm modal would not dismiss for ${agentName3} ` + `(socket=${socket}) \u2014 cancelled`);
+            return { ok: false, reason: "confirm_failed", wedged: CONFIRM_RE.test(after) };
+          }
+          runner.send(socket, session, ["send-keys", "Enter"]);
+          confirmed = true;
+          confirmKeys += 1;
+          continue;
+        }
+        if (appliedRe(level).test(pane)) {
+          return { ok: true, level, confirmed, output: applyLine(pane, level) };
+        }
+      }
+      const final = runner.capture(socket, session) ?? "";
+      if (CONFIRM_RE.test(final)) {
+        runner.send(socket, session, ["send-keys", "Escape"]);
+        log(`effort-picker: timeout with modal open for ${agentName3} \u2014 cancelled`);
+        return { ok: false, reason: "confirm_failed", wedged: true };
+      }
+      return { ok: false, reason: "apply_unverified" };
+    } finally {
+      try {
+        const pane = runner.capture(socket, session) ?? "";
+        if (CONFIRM_RE.test(pane)) {
+          runner.send(socket, session, ["send-keys", "Escape"]);
+        }
+      } catch {}
+    }
+  });
+}
+
 // ../src/config/loader.ts
 init_dist();
 init_zod();
@@ -47576,6 +47659,16 @@ function validateClientMessage(msg) {
         return false;
       if (m.detail !== undefined && (typeof m.detail !== "string" || m.detail.length > 500))
         return false;
+      if (m.affectedAgents !== undefined) {
+        if (!Array.isArray(m.affectedAgents) || m.affectedAgents.length > 64)
+          return false;
+        for (const a of m.affectedAgents) {
+          if (typeof a !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(a))
+            return false;
+        }
+      }
+      if (m.fleetWide !== undefined && typeof m.fleetWide !== "boolean")
+        return false;
       return true;
     }
     case "request_drive_approval": {
@@ -54327,11 +54420,11 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.15.20";
-var COMMIT_SHA = "0b63ab9e";
-var COMMIT_DATE = "2026-06-14T10:58:14+10:00";
-var LATEST_PR = null;
-var COMMITS_AHEAD_OF_TAG = 5;
+var VERSION = "0.15.22";
+var COMMIT_SHA = "a6c13429";
+var COMMIT_DATE = "2026-06-14T03:27:21Z";
+var LATEST_PR = 2349;
+var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -55829,6 +55922,23 @@ function formatFeedElapsed(ms) {
 function turnInFlightForGate() {
   return isDeliveryCutoverEnabled() ? isMachineInTurn() : claudeBusyKeys.size > 0;
 }
+function deliverResumeSyntheticOrBuffer(agent, inbound) {
+  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;
+}
 var pendingRestarts = new Map;
 var lastSessionActiveFile = null;
 var compactState = initialCompactState();
@@ -59311,11 +59421,7 @@ async function captureProvidedSecret(ctx, chat_id, msgId, value) {
         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;
   }
   await switchroomReply(ctx, `\u2705 saved as <code>vault:${escapeHtmlForTg(armed.key)}</code> (masked: <code>${escapeHtmlForTg(maskToken2(value))}</code>). The agent can now reference it.`, { html: true });
@@ -59337,11 +59443,7 @@ async function captureProvidedSecret(ctx, chat_id, msgId, value) {
       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}
 `);
   return true;
@@ -59403,11 +59505,7 @@ async function handleSecretRequestCallback(ctx, data) {
         stage_id: stageId
       }
     };
-    const delivered = ipcServer.sendToAgent(pending2.agent, synthetic);
-    if (delivered)
-      markClaudeBusyForInbound(synthetic);
-    else
-      pendingInboundBuffer.push(pending2.agent, synthetic);
+    deliverResumeSyntheticOrBuffer(pending2.agent, synthetic);
     return;
   }
   await ctx.answerCallbackQuery().catch(() => {});
@@ -62334,14 +62432,13 @@ bot.command("model", async (ctx) => {
 });
 function buildEffortDeps() {
   return {
-    inject: injectSlashCommand,
+    applyEffort: (agent, level) => applyEffort(agent, level),
     getAgentName: getMyAgentName,
     getConfiguredEffort: () => {
       const data = switchroomExecJson(["agent", "list"]);
       return data?.agents?.find((a) => a.name === getMyAgentName())?.thinking_effort ?? null;
     },
-    escapeHtml: escapeHtmlForTg,
-    preBlock
+    escapeHtml: escapeHtmlForTg
   };
 }
 function effortMenuReplyMarkup(reply) {
@@ -63608,14 +63705,9 @@ async function performVaultAccessApproval(ctx, pending2, stageId, senderId, atte
     stageId,
     operatorId: senderId
   });
-  const delivered = ipcServer.sendToAgent(pending2.agent, synthetic);
-  if (delivered)
-    markClaudeBusyForInbound(synthetic);
+  const delivered = deliverResumeSyntheticOrBuffer(pending2.agent, synthetic);
   process.stderr.write(`telegram gateway: vault_grant_approved injection agent=${pending2.agent} key=${pending2.key} stage=${stageId} delivered=${delivered}
 `);
-  if (!delivered) {
-    pendingInboundBuffer.push(pending2.agent, synthetic);
-  }
 }
 async function handleVaultRequestAccessCallback(ctx, data) {
   const senderId = String(ctx.from?.id ?? "");
@@ -63657,14 +63749,9 @@ async function handleVaultRequestAccessCallback(ctx, data) {
       stageId,
       operatorId: senderId
     });
-    const denyDelivered = ipcServer.sendToAgent(pending2.agent, denyInbound);
-    if (denyDelivered)
-      markClaudeBusyForInbound(denyInbound);
+    const denyDelivered = deliverResumeSyntheticOrBuffer(pending2.agent, denyInbound);
     process.stderr.write(`telegram gateway: vault_grant_denied injection agent=${pending2.agent} key=${pending2.key} stage=${stageId} delivered=${denyDelivered}
 `);
-    if (!denyDelivered) {
-      pendingInboundBuffer.push(pending2.agent, denyInbound);
-    }
     return;
   }
   if (action === "approve") {
@@ -63756,13 +63843,9 @@ async function handleVaultRequestSaveCallback(ctx, data) {
       stageId,
       operatorId: senderId
     });
-    const dDelivered = ipcServer.sendToAgent(pending2.agent, discardInbound);
-    if (dDelivered)
-      markClaudeBusyForInbound(discardInbound);
+    const dDelivered = deliverResumeSyntheticOrBuffer(pending2.agent, discardInbound);
     process.stderr.write(`telegram gateway: vault_save_discarded injection agent=${pending2.agent} key=${pending2.key} stage=${stageId} delivered=${dDelivered}
 `);
-    if (!dDelivered)
-      pendingInboundBuffer.push(pending2.agent, discardInbound);
     return;
   }
   if (action === "rename") {
@@ -63823,13 +63906,9 @@ async function handleVaultRequestSaveCallback(ctx, data) {
         operatorId: senderId,
         reason: failReason
       });
-      const fDelivered = ipcServer.sendToAgent(pending2.agent, failInbound);
-      if (fDelivered)
-        markClaudeBusyForInbound(failInbound);
+      const fDelivered = deliverResumeSyntheticOrBuffer(pending2.agent, failInbound);
       process.stderr.write(`telegram gateway: vault_save_failed injection agent=${pending2.agent} key=${pending2.key} stage=${stageId} delivered=${fDelivered}
 `);
-      if (!fDelivered)
-        pendingInboundBuffer.push(pending2.agent, failInbound);
       return;
     }
     pendingVaultRequestSaves.delete(stageId);
@@ -63847,13 +63926,9 @@ async function handleVaultRequestSaveCallback(ctx, data) {
       stageId,
       operatorId: senderId
     });
-    const okDelivered = ipcServer.sendToAgent(pending2.agent, okInbound);
-    if (okDelivered)
-      markClaudeBusyForInbound(okInbound);
+    const okDelivered = deliverResumeSyntheticOrBuffer(pending2.agent, okInbound);
     process.stderr.write(`telegram gateway: vault_save_completed injection agent=${pending2.agent} key=${pending2.key} stage=${stageId} delivered=${okDelivered}
 `);
-    if (!okDelivered)
-      pendingInboundBuffer.push(pending2.agent, okInbound);
     return;
   }
   await ctx.answerCallbackQuery({ text: "Unknown action" }).catch(() => {});

package/telegram-plugin/gateway/config-approval-handler.test.ts

@@ -13,6 +13,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import {
   buildConfigApprovalCardBody,
+  buildLiveNote,
   handleRequestConfigApproval,
   handleRequestConfigFinalize,
   parseConfigApprovalCallback,
@@ -266,6 +267,29 @@ describe("timeout path", () => {
   });
 });
 
+describe("buildLiveNote", () => {
+  it("names specific affected agents + the per-agent restart command", () => {
+    const note = buildLiveNote(["clerk", "gymbro"], false);
+    expect(note).toContain("clerk, gymbro");
+    expect(note).toContain("/restart clerk");
+    expect(note).toContain("/restart gymbro");
+    expect(note).toContain("Not live until restart");
+  });
+  it("guides to a full rollout when fleet-wide (no per-agent list)", () => {
+    const note = buildLiveNote([], true);
+    expect(note).toContain("all agents");
+    expect(note).toContain("switchroom rollout");
+    expect(note).not.toContain("/restart");
+  });
+  it("is empty when nothing is runtime-affected", () => {
+    expect(buildLiveNote([], false)).toBe("");
+    expect(buildLiveNote(undefined, undefined)).toBe("");
+  });
+  it("HTML-escapes agent names", () => {
+    expect(buildLiveNote(["a<b>"], false)).toContain("a&lt;b&gt;");
+  });
+});
+
 describe("handleRequestConfigFinalize", () => {
   it("edits the card to '✅ Applied' on success", async () => {
     const { client, deps, editCalls } = fakeDeps();

package/telegram-plugin/gateway/config-approval-handler.ts

@@ -377,6 +377,27 @@ export async function resolvePendingConfigApproval(
   return true;
 }
 
+/**
+ * The "make it live" note appended to an Applied card. claude loads config at
+ * boot, so an applied edit is inert in the running agents until they restart —
+ * this names exactly what must bounce (and the command) instead of letting the
+ * change silently not take effect. Fleet-wide (shared config) → guide to a full
+ * rollout, never a per-agent list. Empty when nothing runtime-affected.
+ */
+export function buildLiveNote(affectedAgents?: string[], fleetWide?: boolean): string {
+  if (fleetWide) {
+    return (
+      `\n\n⚠️ Shared config changed — affects all agents. Not live until they ` +
+      `restart: run <code>switchroom rollout</code> (or <code>/update apply</code>).`
+    );
+  }
+  const agents = (affectedAgents ?? []).filter((a) => typeof a === "string" && a.length > 0);
+  if (agents.length === 0) return "";
+  const list = agents.map(escapeHtml).join(", ");
+  const cmds = agents.map((a) => `/restart ${escapeHtml(a)}`).join(" · ");
+  return `\n\n🔄 Not live until restart — affects: <b>${list}</b>\n${cmds}`;
+}
+
 /** IPC `request_config_finalize` handler — edits the card to the terminal outcome. */
 export async function handleRequestConfigFinalize(
   _client: Pick<IpcClient, "send">,
@@ -393,9 +414,15 @@ export async function handleRequestConfigFinalize(
   // Clean up the pending entry — finalize is the terminal transition.
   pending.delete(msg.requestId);
 
+  // On apply, tell the operator what must restart for the edit to go LIVE —
+  // claude loads config at boot, so an applied edit is inert until restart.
+  // Specific agents → name them + the one-liner to bounce them; shared config
+  // → guide to a full rollout (never silently leave the change un-live).
+  const liveNote =
+    msg.outcome === "applied" ? buildLiveNote(msg.affectedAgents, msg.fleetWide) : "";
   const body =
     msg.outcome === "applied"
-      ? `✅ <b>Applied</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}`
+      ? `✅ <b>Applied</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}${liveNote}`
       : `⚠️ <b>Reconcile failed; rolled back</b>${msg.detail ? `\n${escapeHtml(msg.detail)}` : ""}`;
   try {
     await deps.editCard({