openmausbot 0.1.73 → 0.1.75

package/dist-server/permission-proxy.js

@@ -1,6 +1,80 @@
 // server/permission-proxy.ts
 import { connect } from "node:net";
 import { randomUUID } from "node:crypto";
+
+// shared/ask-question.ts
+var MAX_QUESTIONS = 6;
+var MAX_OPTIONS = 12;
+var MAX_QUESTION_TEXT = 400;
+var MAX_LABEL = 120;
+var MAX_DESCRIPTION = 400;
+function text(value, limit) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, limit) : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseOption(value) {
+  if (typeof value === "string") {
+    const label2 = text(value, MAX_LABEL);
+    return label2 ? { label: label2 } : null;
+  }
+  if (!isRecord(value)) return null;
+  const label = text(value.label, MAX_LABEL);
+  if (!label) return null;
+  const description = text(value.description, MAX_DESCRIPTION);
+  return description ? { label, description } : { label };
+}
+function parseQuestion(value) {
+  if (!isRecord(value)) return null;
+  const question = text(value.question, MAX_QUESTION_TEXT);
+  if (!question) return null;
+  const options = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of Array.isArray(value.options) ? value.options : []) {
+    const option = parseOption(raw);
+    if (!option || seen.has(option.label)) continue;
+    seen.add(option.label);
+    options.push(option);
+    if (options.length === MAX_OPTIONS) break;
+  }
+  const header = text(value.header, MAX_LABEL);
+  return {
+    question,
+    ...header ? { header } : {},
+    ...value.multiSelect === true ? { multiSelect: true } : {},
+    options
+  };
+}
+function parseAskQuestions(input) {
+  if (!isRecord(input) || !Array.isArray(input.questions)) return null;
+  const questions = [];
+  for (const raw of input.questions) {
+    const question = parseQuestion(raw);
+    if (!question) continue;
+    questions.push(question);
+    if (questions.length === MAX_QUESTIONS) break;
+  }
+  return questions.length ? questions : null;
+}
+function questionAnswersByQuestion(message, questions) {
+  const answers = {};
+  const known = new Map(questions.map((entry) => [entry.question, entry.question]));
+  for (const block of message.split("\n\n")) {
+    const match = /^Q: ([\s\S]+?)\nA: ([\s\S]+)$/.exec(block.trim());
+    if (!match) continue;
+    const question = known.get(match[1].trim());
+    if (question) answers[question] = match[2].trim();
+  }
+  if (Object.keys(answers).length) return answers;
+  const only = questions.length === 1 ? questions[0] : void 0;
+  const flat = message.trim();
+  return only && flat ? { [only.question]: flat } : {};
+}
+
+// server/permission-proxy.ts
 var socketPath = process.argv[2] ?? "";
 var waiting = /* @__PURE__ */ new Map();
 var conn = connect(socketPath);
@@ -32,6 +106,40 @@ conn.on("data", (chunk) => {
   }
 });
 var send = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
+function askBroker(ask) {
+  return new Promise((resolve) => {
+    waiting.set(String(ask.id), resolve);
+    if (conn.destroyed) return dead();
+    try {
+      conn.write(JSON.stringify(ask) + "\n");
+    } catch {
+      dead();
+    }
+  });
+}
+var ASK_USER_QUESTION = "AskUserQuestion";
+var asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+async function answerNativeQuestions(input) {
+  const questions = parseAskQuestions(input);
+  if (!questions?.length) {
+    return JSON.stringify({
+      behavior: "deny",
+      message: "OpenMausBot: this AskUserQuestion call had no answerable question (each one needs question text), so nobody was shown it. Ask again with a well-formed call, or continue without it."
+    });
+  }
+  const answer = await askBroker({
+    t: "ask",
+    id: randomUUID(),
+    kind: "question",
+    tool: ASK_USER_QUESTION,
+    input: { questions }
+  });
+  if (answer.behavior === "deny") {
+    return JSON.stringify({ behavior: "deny", message: answer.message || "Denied from OpenMausBot" });
+  }
+  const answers = answer.source === "user" && typeof answer.message === "string" ? questionAnswersByQuestion(answer.message, questions) : {};
+  return JSON.stringify({ behavior: "allow", updatedInput: { ...asRecord(input), answers } });
+}
 var TOOLS = [
   {
     name: "approve",
@@ -79,30 +187,27 @@ async function handle(msg) {
   if (msg.method === "tools/call") {
     const name = msg.params?.name;
     const args = msg.params?.arguments ?? {};
+    const reply = (text3) => send({ jsonrpc: "2.0", id: msg.id, result: { content: [{ type: "text", text: text3 }] } });
+    if (name === "approve" && args.tool_name === ASK_USER_QUESTION) {
+      return reply(await answerNativeQuestions(args.input));
+    }
     const askId = randomUUID();
     const isQuestion = name === "ask_user";
     const suggestions = Array.isArray(args.permission_suggestions) ? args.permission_suggestions : Array.isArray(args.suggestions) ? args.suggestions : null;
-    const answer = await new Promise((resolve) => {
-      waiting.set(askId, resolve);
-      if (conn.destroyed) return dead();
-      const ask = isQuestion ? { t: "ask", id: askId, kind: "question", tool: "ask_user", input: { question: args.question, choices: args.choices } } : { t: "ask", id: askId, tool: args.tool_name, input: args.input };
-      try {
-        conn.write(JSON.stringify(ask) + "\n");
-      } catch {
-        dead();
-      }
-    });
-    let text = answer.message || "No answer was given \u2014 use your best judgment.";
+    const answer = await askBroker(
+      isQuestion ? { t: "ask", id: askId, kind: "question", tool: "ask_user", input: { question: args.question, choices: args.choices } } : { t: "ask", id: askId, tool: args.tool_name, input: args.input }
+    );
+    let text2 = answer.message || "No answer was given \u2014 use your best judgment.";
     if (!isQuestion) {
       if (answer.behavior === "allow") {
         const result = { behavior: "allow", updatedInput: args.input ?? {} };
         if (answer.always && suggestions) result.updatedPermissions = suggestions;
-        text = JSON.stringify(result);
+        text2 = JSON.stringify(result);
       } else {
-        text = JSON.stringify({ behavior: "deny", message: answer.message || "Denied from OpenMausBot" });
+        text2 = JSON.stringify({ behavior: "deny", message: answer.message || "Denied from OpenMausBot" });
       }
     }
-    return send({ jsonrpc: "2.0", id: msg.id, result: { content: [{ type: "text", text }] } });
+    return reply(text2);
   }
   if (String(msg.method ?? "").startsWith("notifications/")) return;
   if (msg.id != null) {

package/dist-server/server/auto-approve.js

@@ -1,237 +1,76 @@
-// Auto mode: when a bot may answer its own permission requests.
+// What the harness does with a provider's permission request.
 //
-// Safe Auto and remembered grants stop at the destructive/sensitive and
-// unattended boundaries below. Full access is a separate, explicitly
-// acknowledged mode: it answers every permission request, including those
-// guards, while questions remain outside this module and always reach a human.
-//
-// The guard is deliberately tiny and literal. It is NOT a security
-// boundary (an agent set on damage has a thousand spellings for `rm`);
-// it is a "you probably didn't mean to hand THIS one over unattended"
-// backstop for the obvious catastrophes. Real containment is the
-// sandbox and the bot's own computer, not a regex.
-import { approvalModeFor } from "../shared/approval-mode.js";
+// Nothing here decides whether an action is safe. Each approval level is a
+// provider's own permission mode passed straight through (Claude `auto`,
+// Grok `--permission-mode`, Codex `approvalsReviewer`, …), and a request that
+// reaches this process is one the provider left for a person. The only
+// verdict the app synthesizes is Full access, because that level is the
+// person's explicit, separately confirmed grant to answer every prompt.
+// Questions never come through here: a bot's question always reaches a human.
 /** Full access is the person's explicit grant to this receiving bot, including
  * delegated work. It never inherits the sender's mode or elevates another bot.
  * Custom is a provider-config choice rather than an app Full-access grant, so
- * peer-started Custom turns still use Auto and its unattended downgrade.
- * Provider support and grant confirmation are checked by the caller. */
+ * peer-started Custom turns use Auto. Provider support and grant confirmation
+ * are checked by the caller. */
 export function approvalModeForOrigin(mode, origin) {
     if (mode === "custom" && origin.peerInitiated)
         return "auto";
     return mode;
 }
-const DESTRUCTIVE = [
-    /\brm\s+(-[a-z]*\s+)*-[a-z]*[rf]/i, // rm -rf, rm -fr, rm -r -f
-    /\bmkfs\b|\bdiskutil\s+erase|\bdd\s+[^|]*\bof=\/dev\//i,
-    /\bshutdown\b|\breboot\b|\bhalt\b/i,
-    /:\(\)\s*\{.*\}\s*;?\s*:/, // fork bomb
-    /\bgit\s+push\s+[^|]*--force(-with-lease)?\b|\bgit\s+reset\s+--hard\b/i,
-    /\bDROP\s+(TABLE|DATABASE)\b|\bTRUNCATE\s+TABLE\b/i,
-    /\bsudo\s+rm\b|\bchmod\s+-R\s+777\s+\//i,
-];
-// Not destructive, but exactly what you don't hand over unattended: a
-// bot reading your keys is quiet, permanent, and unrecoverable.
-const SENSITIVE = [
-    /(^|[\s/"'])\.env(\.|$|["'\s])/i,
-    /\.ssh\/|id_rsa|id_ed25519|authorized_keys/i,
-    /\.aws\/credentials|\.netrc|\.npmrc|\.pypirc|\.docker\/config\.json/i,
-    /security\s+find-(generic|internet)-password|\bkeychain\b/i,
-    /\bcredentials?\.json\b|\bserviceaccount\b/i,
-];
-/** First matching pattern's source, so a verdict can NAME the rule that
- * made it — the decision log's whole value is "which rule", and deriving
- * the match a second time at the call site is how the log and the verdict
- * drift apart. */
-function matchFirst(rules, text) {
-    for (const re of rules)
-        if (re.test(text))
-            return re.source;
-    return null;
-}
-export function looksSensitive(text) {
-    return matchFirst(SENSITIVE, text) !== null;
-}
-export function looksDestructive(text) {
-    return matchFirst(DESTRUCTIVE, text) !== null;
-}
-/** The key an "Always allow" remembers.
- *
- * A bare tool name is far too coarse for a command runner: remembering
- * "Bash" would hand the bot a permanent unattended shell, which is the
- * opposite of what someone pressing "always allow" on `git status`
- * intends. Command tools are therefore keyed by their program —
- * `Bash:git`, `Bash:npm` — so the grant is as narrow as the thing you
- * actually looked at. Computed once, server-side, and echoed back by the
- * client so the two sides can never disagree about what was granted. */
-const COMMAND_TOOLS = new Set(["bash", "shell", "execute", "run_command", "computer_exec", "terminal"]);
-export function approvalKey(tool, summary, scope) {
-    const bare = tool.replace(/^mcp__[^_]+__/, "").toLowerCase();
-    if (!COMMAND_TOOLS.has(bare))
-        return scope ? `${scope}:${tool}` : tool;
-    // first bare word of the command, skipping env assignments and sudo
-    const words = summary.trim().split(/\s+/);
-    let i = 0;
-    while (i < words.length && (/^[A-Z_][A-Z0-9_]*=/.test(words[i]) || words[i] === "sudo"))
-        i += 1;
-    const program = (words[i] ?? "").split("/").pop()?.replace(/[^\w.-]/g, "") ?? "";
-    const key = program ? `${tool}:${program}` : tool;
-    return scope ? `${scope}:${key}` : key;
-}
-/** A durable "Always allow" choice is offered only when that exact grant
- * would be honored on the next identical request. Custom delegates approval
- * semantics to config.toml, while guards and provider-sandbox changes are
- * intentionally never bypassed by remembered app grants. */
-export function rememberableApprovalKey(bot, tool, summary, context) {
-    if (!bot ||
-        approvalModeFor(bot) === "custom" ||
-        context.source !== "no-grant" ||
-        context.scope ||
-        context.requiresExplicitApproval) {
-        return undefined;
-    }
-    return approvalKey(tool, summary, context.scope);
-}
-/** The verdict AND its provenance. The decision itself is unchanged from
- * autoDecision below — this exists so the decision log can record which
- * rule decided without the call site re-deriving (and eventually
- * mis-deriving) the match. */
-export function autoVerdict(bot, tool, summary, context) {
-    const mode = approvalModeFor(bot);
-    if (context?.nativeApproval)
-        return { approve: null, source: "native-approval" };
-    // This branch intentionally precedes every guard. Entering Full access is
-    // separately consent-gated by the bot PATCH endpoint, and its promise is
-    // literal: even destructive, sensitive, unattended, and host-computer
-    // permission requests are approved. The request.opened caller invokes this
-    // function for permissions only, never for provider questions.
-    if (mode === "full") {
-        return {
-            approve: `approved ${tool} (full access)`,
-            source: "full-access",
-        };
-    }
-    if (context?.requiresExplicitApproval) {
-        return { approve: null, source: "explicit-approval-block" };
-    }
-    // the guards outrank the grants, so an "always allow" can never widen
-    // into them
-    const destructive = matchFirst(DESTRUCTIVE, summary) ?? matchFirst(DESTRUCTIVE, tool);
-    const sensitive = destructive ? null : matchFirst(SENSITIVE, summary);
-    // The grant is computed even when a hard block will refuse it: the row
-    // worth auditing is "this WOULD have auto-approved, and only the block
-    // stood in the way", which cannot be told apart from an ordinary
-    // "nobody granted this" card without knowing both halves.
-    const key = approvalKey(tool, summary, context?.scope);
-    const grant = destructive || sensitive
-        ? null
-        : mode !== "custom" && bot.alwaysAllow?.includes(key)
-            ? { approve: `auto-approved ${key} (always allowed)`, source: "always-allow", rule: key }
-            : mode === "auto"
-                ? { approve: `auto-approved ${tool}`, source: "auto-mode", rule: undefined }
-                : null;
-    if (context?.unattended) {
-        // Auto mode is something a person switched on for turns they are present
-        // for. A webhook turn begins with nobody watching, on a payload someone
-        // else wrote, so it does not inherit that decision — the guard above is a
-        // pattern list its own comment calls "not a security boundary", and it
-        // must not stand in for a human at 3am. A guard that would have carded
-        // anyway keeps its own name; the block is only the story when it is the
-        // thing that changed the outcome.
-        if (grant)
-            return { approve: null, source: "unattended-block", rule: grant.rule };
-        if (destructive)
-            return { approve: null, source: "destructive-guard", rule: destructive };
-        if (sensitive)
-            return { approve: null, source: "sensitive-guard", rule: sensitive };
+// Tools that ask a PERSON something. A question exists so that a human
+// decides; any mode answering one on their behalf defeats the only reason
+// it was asked. They normally arrive typed as questions and never reach a
+// verdict at all — this is the backstop for the path where one arrives
+// mis-typed as a permission (a malformed AskUserQuestion call falls back to
+// the permission path in permission-proxy). Approving it there does not
+// produce an answer: the CLI runs the tool with none and the model is told
+// "The user did not answer the questions." — a question silently lost.
+const ASKS_A_PERSON = new Set(["askuserquestion", "ask_user"]);
+export function autoVerdict(mode, tool, context) {
+    // A question is for a person, whatever channel it arrived on — and
+    // whatever the mode: even Full has no answer to give, only an approval
+    // that would run the tool with none.
+    if (ASKS_A_PERSON.has(tool.replace(/^mcp__[^_]+__/, "").toLowerCase())) {
         return { approve: null, source: "no-grant" };
     }
-    if (context?.scope === "local-computer" && mode !== "auto") {
-        // Host control is not covered by a remembered always-allow grant.
-        // After the Auto-on-this-computer warning, unclassified GUI actions
-        // (click/type) may auto-approve; destructive/sensitive still card.
-        if (grant)
-            return { approve: null, source: "local-computer-block", rule: grant.rule };
-        if (destructive)
-            return { approve: null, source: "destructive-guard", rule: destructive };
-        if (sensitive)
-            return { approve: null, source: "sensitive-guard", rule: sensitive };
-        return { approve: null, source: "no-grant" };
-    }
-    if (destructive)
-        return { approve: null, source: "destructive-guard", rule: destructive };
-    if (sensitive)
-        return { approve: null, source: "sensitive-guard", rule: sensitive };
-    if (grant)
-        return { approve: grant.approve, source: grant.source, rule: grant.rule };
+    // Full's promise is literal: even a sandbox widening is approved. Entering
+    // Full is separately consent-gated by the bot PATCH endpoint, and the
+    // request.opened caller invokes this for permissions only, never questions.
+    if (mode === "full")
+        return { approve: `approved ${tool} (full access)`, source: "full-access" };
+    if (context?.requiresExplicitApproval)
+        return { approve: null, source: "explicit-approval-block" };
+    if (mode === "auto" || mode === "custom")
+        return { approve: null, source: "native-approval" };
     return { approve: null, source: "no-grant" };
 }
-/** Why this request may be answered without the human, or null to ask. */
-export function autoDecision(bot, tool, summary, context) {
-    return autoVerdict(bot, tool, summary, context).approve;
-}
-/** The note a card shows above its buttons, explaining why the bot stopped
- * rather than answering for itself.
- *
- * The unattended case is the one users misread. A turn a webhook or another
- * bot started never runs Auto at all — approvalModeForTurn downgrades it to
- * Ask before the provider spawns — so "this action needs you" would name the
- * wrong cause and imply the next action might pass. It will not: with a fleet
- * delegating between bots, every card looks like this until someone answers.
- * Say that plainly, and name the mode that keeps running. */
-export function approvalHeldReason(context) {
-    const key = approvalHeldNote(context);
-    return key && HELD_NOTE[key];
-}
 /** Every fixed note a held card can show, by catalog key.
  *
  * The card is the last thing between a bot and someone's filesystem, so the
  * one line explaining why it stopped should not be the one line still in
  * English. The client translates by key and falls back to this text, which
  * the server keeps sending: cards saved before the key existed still render,
- * and so do the free-text apply errors that have no key at all.
- *
- * The unattended hint is a whole second sentence rather than a suffix. A
- * translator needs the sentence, not two halves to reassemble. */
+ * and so do the free-text apply errors that have no key at all. */
 export const HELD_NOTE = {
     "approval.held.native": "The provider requires your approval for this action.",
     "approval.held.sandbox": "This changes the provider sandbox, so only Full access can approve it automatically.",
-    "approval.held.localComputer": "Controlling your computer is never covered by Always allow, so this needs you.",
-    "approval.held.unattended": "A webhook or another bot started this turn, so Approve for me is paused and every action asks.",
-    "approval.held.unattendedFullAccess": "A webhook or another bot started this turn, so Approve for me is paused and every action asks. Full access keeps working unattended.",
-    "approval.held.destructive": "This looks destructive, so Approve for me stopped to ask.",
-    "approval.held.sensitive": "This touches credentials, so Approve for me stopped to ask.",
-    "approval.held.needsYou": "This action needs you, so Approve for me stopped to ask.",
     "approval.held.undeliveredFull": "Full access couldn't deliver this approval.",
     "approval.held.undelivered": "Approve for me couldn't answer this one.",
 };
 /** Which note, as a key. approvalHeldReason is this plus the English text, so
  * the branching that decides the note lives in exactly one place. */
 export function approvalHeldNote(context) {
-    if (context.source === "native-approval")
-        return "approval.held.native";
     if (!context.permission)
         return undefined;
-    if (context.requiresExplicitApproval)
+    if (context.source === "explicit-approval-block")
         return "approval.held.sandbox";
-    // Host control reaches this only over a grant that would otherwise have
-    // fired, in a mode that explains nothing else. "I pressed Always allow and
-    // it asked anyway" is the whole confusion, so answer that and not the mode.
-    if (context.source === "local-computer-block")
-        return "approval.held.localComputer";
-    if (context.mode !== "auto")
-        return undefined;
-    if (context.unattended) {
-        return context.fullAccessAvailable
-            ? "approval.held.unattendedFullAccess"
-            : "approval.held.unattended";
-    }
-    // A guard names itself. Both stop the same mode, but one is about damage
-    // and the other about secrets, and a read-only .env card that says
-    // "destructive" teaches people to stop reading these.
-    if (context.source === "destructive-guard")
-        return "approval.held.destructive";
-    if (context.source === "sensitive-guard")
-        return "approval.held.sensitive";
-    return "approval.held.needsYou";
+    if (context.source === "native-approval")
+        return "approval.held.native";
+    return undefined;
+}
+/** The note a card shows above its buttons, explaining why the bot stopped
+ * rather than answering for itself. */
+export function approvalHeldReason(context) {
+    const key = approvalHeldNote(context);
+    return key && HELD_NOTE[key];
 }

package/dist-server/server/channel-queue.js

@@ -6,7 +6,20 @@
 // operation settles so the current responder cannot appear to answer words it
 // never saw.
 import { newId } from "./contracts.js";
+import { chatFollowups, saveChatFollowup, settleChatFollowups } from "./message-db.js";
 const queues = new Map(); // threadId -> waiting sends
+export function restoreChannelMessages() {
+    queues.clear();
+    for (const row of chatFollowups("channel")) {
+        if (row.status !== "pending")
+            continue;
+        const entry = queues.get(row.threadId) ?? { groupId: row.ownerId, items: [] };
+        if (entry.groupId !== row.ownerId)
+            throw new Error("queued task belongs to another channel");
+        entry.items.push({ ...row.payload, id: row.id, mode: row.payload.mode ?? "chat" });
+        queues.set(row.threadId, entry);
+    }
+}
 export function queueChannelMessage(groupId, threadId, text, options = {}) {
     const entry = queues.get(threadId) ?? { groupId, items: [] };
     if (entry.groupId !== groupId)
@@ -19,6 +32,7 @@ export function queueChannelMessage(groupId, threadId, text, options = {}) {
         mode: options.mode ?? "chat",
         via: options.via,
     };
+    saveChatFollowup({ id: item.id, kind: "channel", ownerId: groupId, threadId, payload: item });
     entry.items.push(item);
     queues.set(threadId, entry);
     return { id: item.id };
@@ -38,6 +52,7 @@ export function cancelChannelMessage(groupId, queueId) {
         const items = entry.items.filter((item) => item.id !== queueId);
         if (items.length === entry.items.length)
             continue;
+        settleChatFollowups([queueId], "cancelled");
         if (items.length === 0)
             queues.delete(threadId);
         else
@@ -55,14 +70,17 @@ export function drainChannelMessages(isWorking, run) {
     for (const [threadId, entry] of queues) {
         if (isWorking(entry.groupId))
             continue;
-        const item = entry.items.shift();
+        const item = entry.items[0];
         if (!item) {
             queues.delete(threadId);
             continue;
         }
+        settleChatFollowups([item.id], "dispatching");
+        entry.items.shift();
         if (entry.items.length === 0)
             queues.delete(threadId);
-        run({ ...item, groupId: entry.groupId, threadId });
+        const running = run({ ...item, groupId: entry.groupId, threadId });
+        void Promise.resolve(running).then(() => settleChatFollowups([item.id], null), () => settleChatFollowups([item.id], "interrupted")).catch((error) => console.warn("channel-queue: could not settle durable follow-up", error));
     }
 }
 /** Test helper. */

package/dist-server/server/config.js

@@ -209,6 +209,18 @@ const featureConfigSchema = z.object({
      * also has its own switch. */
     browser: z.boolean().optional(),
 });
+/** First-run progress. Kept in the workspace config rather than a browser so
+ * it survives cleared site data and is shared by every paired client. Hint
+ * ids are short renderer-chosen slugs; the list is capped so a buggy client
+ * cannot grow the file without bound. */
+const onboardingConfigSchema = z.object({
+    /** ISO timestamp of finishing (or skipping to the end of) the welcome flow. */
+    completedAt: z.string().trim().max(40).optional(),
+    /** Which welcome flow was completed; a newer flow may re-show itself. */
+    version: z.number().int().min(0).max(1000).optional(),
+    reelSeen: z.boolean().optional(),
+    hintsSeen: z.array(z.string().trim().min(1).max(60)).max(100).optional(),
+}).strict();
 const instanceConfigSchema = z.object({
     driver: z.string().min(1),
     displayName: optionalText,
@@ -306,6 +318,7 @@ const appConfigSchema = z.object({
     threads: z.object({ maxConcurrentPerBot: z.number().int().min(1).max(MAX_CONCURRENT_BOT_THREADS) }).strict().optional(),
     localVm: localVmConfigSchema.optional(),
     features: featureConfigSchema.optional(),
+    onboarding: onboardingConfigSchema.optional(),
     browserProfiles: browserProfilesSchema.optional(),
     instances: instanceConfigMapSchema.optional(),
     /** User-configured MCP servers, mounted into every capable engine. Kept
@@ -422,6 +435,28 @@ export function showToolCallsEnabled(cfg) {
 export function builtInBrowserEnabled(cfg) {
     return cfg.features?.browser === true;
 }
+/** Config sections no provider driver reads. A write that touches only
+ * these must not rebuild the fleet: rebuilding disposes every engine child
+ * and reloads it, seconds of work that would also interrupt in-flight
+ * turns. The guided tour writes `onboarding` on every step, so it in
+ * particular has to stay cheap. */
+export const FLEET_NEUTRAL_KEYS = new Set([
+    "profile",
+    "language",
+    "tts",
+    "imageGen",
+    "vps",
+    "rooms",
+    "threads",
+    "localVm",
+    "features",
+    "browserProfiles",
+    "onboarding",
+]);
+/** The keys of a config patch that require the provider fleet to reload. */
+export function providerReloadKeys(patch) {
+    return Object.keys(patch).filter((key) => !FLEET_NEUTRAL_KEYS.has(key));
+}
 // OMB_DATA_DIR isolates test/soak rigs from the user's real fleet.
 export const DATA_DIR = process.env.OMB_DATA_DIR ?? join(homedir(), ".openmausbot");
 const LEGACY_DATA_DIR = join(homedir(), ".opengrokbot");
@@ -648,7 +683,7 @@ export function saveConfig(patch, options = {}) {
     const storedProfiles = storedBrowserProfilesSchema.safeParse(disk.browserProfiles);
     if (storedProfiles.success)
         disk.browserProfiles = storedProfiles.data;
-    for (const key of ["xai", "anthropic", "openaiCompat", "composio", "box", "opencodeGo", "tts", "imageGen", "profile", "rooms", "threads", "localVm", "features", "budgets", "billing"]) {
+    for (const key of ["xai", "anthropic", "openaiCompat", "composio", "box", "opencodeGo", "tts", "imageGen", "profile", "rooms", "threads", "localVm", "features", "budgets", "billing", "onboarding"]) {
         const section = checkedPatch[key];
         if (!section)
             continue;