@indigoai-us/hq-cli 5.345.86 → 5.345.87

package/dist/commands/bot.js

@@ -51,7 +51,7 @@ import { isAncestorProcess } from "../lib/bot/self-process.js";
 import { runtimeDisplayName } from "../lib/bot/runtime-sign-in.js";
 import { classifyRuntimeFailure, runtimeFailureReason } from "../lib/bot/runtime-failure.js";
 import { PROBE_DEFAULT_TIMEOUT_MS, probeBotRuntime } from "../lib/bot/probe.js";
-import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, repairBotDaemonIfStale, healBotDaemonNodeFromJob, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotDisplayName, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, localNameForRemoteBot, remoteBotRunnability, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_DISPLAY_NAME_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, detectBotPlatform, } from "../lib/bot/index.js";
+import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, repairBotDaemonIfStale, healBotDaemonNodeFromJob, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotDisplayName, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, localNameForRemoteBot, remoteBotRunnability, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_DISPLAY_NAME_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, detectBotPlatform, withBotLock, localBotRole, remoteBotRole, remoteBotDisplayName, personFacingName, writeCloudDisplayName, setupSlugFor, ASSISTANT_ROLE, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -191,6 +191,7 @@ function rowFor(name, opts = {}) {
         memory: botMemoryMode(config),
         memoryDir: resolveBotMemoryDir(config),
         ...(config.displayName ? { displayName: config.displayName } : {}),
+        role: localBotRole(config),
         ...(config.intro ? { intro: config.intro } : {}),
         ...(config.kickoff ? { kickoff: config.kickoff } : {}),
     };
@@ -211,6 +212,13 @@ async function decorateOnline(rows) {
             const rec = await api.getAgent(row.agentUid);
             row.online = rec.online === true;
             row.lastHeartbeatAt = rec.runtime?.lastHeartbeat?.at ?? row.lastHeartbeatAt;
+            // The cloud holds the name people see; bot.json is this computer's copy.
+            const cloudName = personFacingName(rec.name, [row.name, `${row.name}-${row.ownerUid.slice(-8).toLowerCase()}`, row.agentUid]);
+            // A rename HQ could not take yet is newer than HQ's copy.
+            if (cloudName && !(row.displayName && readBotConfig(row.dir)?.displayNameLocalOnly))
+                row.displayName = cloudName;
+            if (rec.agentRole === ASSISTANT_ROLE)
+                row.role = ASSISTANT_ROLE;
         }
         catch {
             row.online = null;
@@ -317,7 +325,7 @@ async function startBot(name, dir, config, output, extra = {}) {
     if (output === "silent")
         return { running, how };
     if (output === "json") {
-        console.log(JSON.stringify({ ok: running, name, ...extra, how, state: status?.state ?? "unknown", pid: status?.pid ?? null, lastError: status?.lastError ?? null }, null, 2));
+        console.log(JSON.stringify({ ok: running, name, ...extra, running, how, state: status?.state ?? "unknown", pid: status?.pid ?? null, lastError: status?.lastError ?? null }, null, 2));
         return { running, how };
     }
     if (running)
@@ -475,8 +483,124 @@ export function resolveCreateKind(opts, worker) {
     }
     return { kind, companies };
 }
+/**
+ * `hq bot create`. Runs under the bot's lock, so a create racing an adopt,
+ * restore, rm or set of the same bot waits for it instead of tripping over
+ * its half-written folder.
+ */
 export async function runBotCreate(nameArg, opts) {
     const name = validateBotName(nameArg);
+    await withBotLock(name, () => runBotCreateLocked(name, opts), { command: "hq bot create" });
+}
+/**
+ * Write a bot's new name to the cloud. Never fails the caller's command when
+ * `tolerant`: a server without the name route, or any other failure, leaves
+ * the name on this computer only and says so in the result and the bot's log.
+ */
+async function saveCloudName(api, dir, agentUid, displayName, tolerant) {
+    const log = createBotLogger(dir);
+    let saved;
+    try {
+        const r = await writeCloudDisplayName(api, agentUid, displayName);
+        if (r.saved === "local-only")
+            log("info", `name "${displayName}" kept on this computer only: ${r.detail}`);
+        else
+            log("info", `name "${displayName}" saved in HQ`);
+        saved = r.saved;
+    }
+    catch (err) {
+        if (!tolerant)
+            throw err;
+        log("warn", `could not save the name "${displayName}" in HQ, kept it on this computer: ${err instanceof Error ? err.message : String(err)}`);
+        saved = "local-only";
+    }
+    // Remember a name HQ does not have yet, so list keeps showing it over HQ's older one.
+    if (readBotConfig(dir))
+        patchBotConfig(dir, { displayNameLocalOnly: saved === "local-only" ? true : undefined });
+    return saved;
+}
+/**
+ * Bring a running bot up on its current bot.json, so a changed name reaches
+ * its system prompt (built once at start). From inside one of the bot's own
+ * turns a stop would end that turn, so the restart is left for later and the
+ * result says so.
+ */
+async function restartForNewSettings(name, dir, config, output, extra) {
+    const status = readBotStatus(dir);
+    const running = !!status && isPidAlive(status.pid) && status.state === "running";
+    if (running && selfStopProbe(status.pid)) {
+        const r = await startBot(name, dir, config, output, { ...extra, restarted: false, restartPending: true });
+        return { ...r, restarted: false, restartPending: true };
+    }
+    if (running) {
+        await stopBot(name, dir, config, "silent");
+        // A bot that did not go down is still on its old system prompt: starting
+        // now would find it "already running" and call that a restart.
+        const down = await waitFor(() => {
+            const s = readBotStatus(dir);
+            return !s || !isPidAlive(s.pid);
+        }, 3_000);
+        if (!down) {
+            const r = await startBot(name, dir, config, output, { ...extra, restarted: false, restartPending: true });
+            return { ...r, restarted: false, restartPending: true };
+        }
+    }
+    const r = await startBot(name, dir, config, output, { ...extra, restarted: running, restartPending: false });
+    return { ...r, restarted: running, restartPending: false };
+}
+/** `hq bot create setup` when the assistant is already set up on this computer: apply the name, make sure it runs. */
+async function finishExistingSetupBot(name, dir, config, displayName, opts) {
+    let nameSaved = null;
+    let current = config;
+    let nameChanged = false;
+    if (displayName) {
+        // The assistant is already here, so nothing about the cloud may turn this
+        // into a failure: without a login the name stays on this computer.
+        const api = new BotApi({ token: () => ownerToken() });
+        nameSaved = await saveCloudName(api, dir, config.agentUid, displayName, true);
+        if (config.displayName !== displayName) {
+            patchBotConfig(dir, { displayName });
+            current = readBotConfig(dir) ?? { ...config, displayName };
+            nameChanged = true;
+        }
+    }
+    const extra = {
+        outcome: "existing",
+        agentUid: current.agentUid,
+        displayName: current.displayName ?? null,
+        role: localBotRole(current),
+        nameSaved,
+    };
+    if (!opts.json)
+        console.log(chalk.green(`${name} is already set up on this computer`) + chalk.dim(` (${current.agentUid})`));
+    let started;
+    if (opts.start === false) {
+        const status = readBotStatus(dir);
+        const running = !!status && isPidAlive(status.pid) && status.state === "running";
+        started = { running, how: null, restarted: false, restartPending: nameChanged && running };
+    }
+    else if (nameChanged) {
+        started = await restartForNewSettings(name, dir, current, "silent", {});
+    }
+    else {
+        started = { ...(await startBot(name, dir, current, "silent")), restarted: false, restartPending: false };
+    }
+    // The assistant is set up, so this succeeded whether or not it reported
+    // running within the wait; `running` says which. The desktop reads state
+    // from the bot list, never from a create's ok.
+    const status = readBotStatus(dir);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, name, ...extra, ...started, state: status?.state ?? "unknown", pid: status?.pid ?? null, lastError: status?.lastError ?? null }, null, 2));
+        return;
+    }
+    if (started.restartPending)
+        console.log(chalk.dim(`  it uses the new name after its next restart (hq bot restart ${name})`));
+    else if (started.running)
+        console.log(chalk.green(`${name} is running`) + (started.how ? chalk.dim(` (${started.how})`) : ""));
+    else if (opts.start !== false)
+        console.log(chalk.yellow(`${name} did not report running within 15s`) + chalk.dim(`  logs: hq bot logs ${name}`));
+}
+async function runBotCreateLocked(name, opts) {
     const runtime = opts.runtime ?? "claude";
     if (!isBotRuntimeId(runtime)) {
         throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
@@ -491,11 +615,22 @@ export async function runBotCreate(nameArg, opts) {
     const model = opts.model !== undefined ? validateBotModel(opts.model) : undefined;
     const effort = opts.effort !== undefined ? validateBotEffort(runtime, opts.effort) : undefined;
     const dir = botDir(name);
-    if (readBotConfig(dir)) {
+    const existingBeforeRoot = readBotConfig(dir);
+    // Only HQ's setup assistant is idempotent; any other bot keeps failing fast.
+    const maybeSetup = name === RESERVED_SETUP_BOT_NAME &&
+        opts.worker?.trim() === SETUP_BOT_WORKER_ID &&
+        (opts.kind === undefined || opts.kind.trim().toLowerCase() === "personal");
+    if (existingBeforeRoot && !maybeSetup) {
         throw Object.assign(new Error(`Bot "${name}" already exists (${dir}). Use hq bot start ${name} or hq bot rm ${name}.`), {
             expected: true,
         });
     }
+    // The assistant is already here: nothing else (the HQ folder, the setup
+    // worker's files) has to resolve for this to succeed.
+    if (existingBeforeRoot && localBotRole(existingBeforeRoot) === ASSISTANT_ROLE) {
+        await finishExistingSetupBot(name, dir, existingBeforeRoot, displayName, opts);
+        return;
+    }
     const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
     // Resolve the company worker before provisioning anything (a typo must not
     // cost an identity).
@@ -505,6 +640,16 @@ export async function runBotCreate(nameArg, opts) {
     if (name === RESERVED_SETUP_BOT_NAME && kind === "personal" && !isSetupBot) {
         throw Object.assign(new Error(`The name ${RESERVED_SETUP_BOT_NAME} is reserved for HQ's setup bot; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
     }
+    const existing = readBotConfig(dir);
+    if (existing) {
+        if (isSetupBot && localBotRole(existing) === ASSISTANT_ROLE) {
+            await finishExistingSetupBot(name, dir, existing, displayName, opts);
+            return;
+        }
+        throw Object.assign(new Error(`Bot "${name}" already exists (${dir}). Use hq bot start ${name} or hq bot rm ${name}.`), {
+            expected: true,
+        });
+    }
     const token = await ownerToken();
     const owner = await resolveCallerPersonUid(token, undefined, { command: "hq bot create" });
     if (!owner)
@@ -527,7 +672,7 @@ export async function runBotCreate(nameArg, opts) {
         if (matches.length > 1) {
             throw Object.assign(new Error(`You own more than one bot called "${name}": ${matches.map((bot) => bot.agentUid).join(", ")}. Name the one you mean by its id.`), { expected: true });
         }
-        const setupSlug = `${RESERVED_SETUP_BOT_NAME}-${owner.slice(-8).toLowerCase()}`;
+        const setupSlug = setupSlugFor(owner);
         const slugMatches = mine.filter((bot) => (bot.slug ?? "").trim().toLowerCase() === setupSlug);
         if (slugMatches.length > 1) {
             throw Object.assign(new Error(`HQ returned more than one agent with the setup slug "${setupSlug}". The CLI cannot safely choose one; ask your HQ admin to inspect the duplicate records.`), { expected: true });
@@ -543,11 +688,21 @@ export async function runBotCreate(nameArg, opts) {
             name,
             api,
             hqRoot,
-            overrides: { ...(model ? { model } : {}) },
+            // The person's choices for this start win over yesterday's saved ones.
+            overrides: {
+                ...(model ? { model } : {}),
+                ...(displayName ? { displayName } : {}),
+                ...(intro ? { intro } : {}),
+                ...(kickoff ? { kickoff } : {}),
+            },
             daemon: opts.daemon !== false,
             preserveFirstStart: true,
         });
+        const nameSaved = displayName ? await saveCloudName(api, result.dir, result.agentUid, displayName, true) : null;
         const recovered = {
+            outcome: "adopted",
+            role: localBotRole(config),
+            nameSaved,
             agentUid: result.agentUid,
             kind: effectiveBotKind(config),
             companies: effectiveBotCompanies(config),
@@ -574,7 +729,8 @@ export async function runBotCreate(nameArg, opts) {
                 console.log(chalk.dim(`  ${result.daemon}`));
         }
         if (opts.start !== false) {
-            await startBot(name, result.dir, config, opts.json ? "json" : "text", { ...recovered, daemon: result.daemon });
+            // The assistant is set up either way: ok, with `running` saying whether it came up in time.
+            await startBot(name, result.dir, config, opts.json ? "json" : "text", { ok: true, ...recovered, daemon: result.daemon });
             return true;
         }
         if (opts.json)
@@ -727,6 +883,10 @@ export async function runBotCreate(nameArg, opts) {
         : scaffoldBotWorker(hqRoot, name, agentUid, runtime, undefined, scaffoldOpts);
     createBotLogger(dir)("info", `created ${name} (${agentUid}) kind=${kind}${companies.length ? ` companies=${companies.join(",")}` : ""} runtime=${runtime}${worker ? ` worker=${worker.id} company=${worker.company ?? "-"}` : ""} memory=${memoryMode}`);
     const created_ = {
+        outcome: "created",
+        role: localBotRole(config),
+        // The create itself carried the name to HQ (entity name and saved settings).
+        nameSaved: (displayName ? "cloud" : null),
         agentUid,
         kind,
         companies,
@@ -773,7 +933,7 @@ export async function runBotCreate(nameArg, opts) {
                 console.log(chalk.yellow(`${name} has not reported running yet; check hq bot logs ${name}`));
             return;
         }
-        await startBot(name, dir, config, opts.json ? "json" : "text", { ...created_, daemon: daemonMessage });
+        await startBot(name, dir, config, opts.json ? "json" : "text", { ...(isSetupBot ? { ok: true } : {}), ...created_, daemon: daemonMessage });
         return;
     }
     if (opts.json) {
@@ -1160,6 +1320,12 @@ async function runBotRmOrphan(name, opts) {
 }
 async function runBotRm(nameArg, opts) {
     const validated = validateBotName(nameArg);
+    // Under the bot's lock: an rm racing a create, adopt or restore of the same
+    // bot runs before or after it, never through the middle of it.
+    await withBotLock(validated, () => runBotRmLocked(validated, opts), { command: "hq bot rm" });
+}
+async function runBotRmLocked(validated, opts) {
+    const nameArg = validated;
     if (readBotConfig(botDir(validated)) === null) {
         await runBotRmOrphan(validated, opts);
         return;
@@ -1245,49 +1411,116 @@ async function runBotRm(nameArg, opts) {
         console.log(chalk.dim(`  HQ did not finish: ${incomplete.steps.join(", ")}`));
     throw Object.assign(new Error(message), { expected: true });
 }
-/**
- * `hq bot set <name> --model <id|default> --effort <level|default>`: change
- * what the bot thinks with. bot.json is re-read on every turn, so the next
- * message uses it; no restart.
- */
 export async function runBotSet(nameArg, opts) {
+    const name = validateBotName(nameArg);
+    await withBotLock(name, () => runBotSetLocked(name, opts), { command: "hq bot set" });
+}
+/** A sentence for a refused name write: the status only, never the server's text. */
+function nameWriteRefused(name, err) {
+    const status = err instanceof BotApiError ? err.status : null;
+    const code = err instanceof BotApiError ? err.code : undefined;
+    // Only a busy record, a server error or no answer can pass on a retry.
+    const retryable = status === null || status === 409 || status >= 500;
+    const why = code === "NOT_A_LOCAL_BOT"
+        ? "it runs in HQ, not on this computer, so rename it in HQ"
+        : status === 401
+            ? "your HQ sign-in has expired; sign in again"
+            : status === 404
+                ? "HQ has no record of this bot"
+                : status === 403
+                    ? "HQ says this bot is not yours to rename"
+                    : status === 400
+                        ? "HQ did not accept that name"
+                        : status === 409
+                            ? "its record in HQ kept changing"
+                            : status === null
+                                ? "HQ could not be reached"
+                                : `HQ answered ${status}`;
+    return Object.assign(new Error(`Could not rename ${name}: ${why}. Nothing was changed${retryable ? "; try again in a moment" : ""}.`), {
+        expected: true,
+    });
+}
+async function runBotSetLocked(nameArg, opts) {
     const { name, dir, config } = requireBot(nameArg);
     if (hasPromotionHold(dir))
         throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
-    if (opts.model === undefined && opts.effort === undefined) {
-        throw Object.assign(new Error("Nothing to change: pass --model <id|default> and/or --effort <level|default>."), { expected: true });
-    }
-    const next = { ...config };
-    if (opts.model !== undefined) {
-        const model = validateBotModel(opts.model);
-        if (model)
-            next.model = model;
-        else
-            delete next.model;
+    if (opts.model === undefined && opts.effort === undefined && opts.displayName === undefined) {
+        throw Object.assign(new Error("Nothing to change: pass --model <id|default>, --effort <level|default> and/or --display-name <name>."), { expected: true });
+    }
+    // Only the keys this command changes are written, onto a fresh read of
+    // bot.json: the running bot writes it too (introSentAt, kickoff state), and
+    // the cloud write below can take a while.
+    const patch = {};
+    if (opts.model !== undefined)
+        patch.model = validateBotModel(opts.model) || undefined;
+    if (opts.effort !== undefined)
+        patch.effort = validateBotEffort(config.runtime, opts.effort) || undefined;
+    const displayName = opts.displayName !== undefined ? validateBotDisplayName(opts.displayName) : undefined;
+    let nameSaved = null;
+    if (displayName !== undefined) {
+        try {
+            // Also records displayNameLocalOnly in bot.json.
+            nameSaved = await saveCloudName(new BotApi({ token: () => ownerToken() }), dir, config.agentUid, displayName, false);
+        }
+        catch (err) {
+            // Status and code only: the server's own text stays out of the log too.
+            const what = err instanceof BotApiError ? `HTTP ${err.status}${err.code ? ` ${err.code}` : ""}` : "no answer from HQ";
+            createBotLogger(dir)("warn", `rename to "${displayName}" refused: ${what}`);
+            throw nameWriteRefused(name, err);
+        }
+        patch.displayName = displayName;
     }
-    if (opts.effort !== undefined) {
-        const effort = validateBotEffort(config.runtime, opts.effort);
-        if (effort)
-            next.effort = effort;
-        else
-            delete next.effort;
+    const next = patchBotConfig(dir, patch);
+    createBotLogger(dir)("info", `settings: model=${next.model ?? "default"} effort=${effectiveBotEffort(next)}${next.effort ? "" : " (default)"}${displayName !== undefined ? ` name="${displayName}"` : ""}`);
+    const status = readBotStatus(dir);
+    let running = !!status && isPidAlive(status.pid) && status.state === "running";
+    let restarted = false;
+    let restartPending = false;
+    // Only a name change needs a restart, and only a running bot gets one.
+    if (displayName !== undefined && displayName !== config.displayName && running) {
+        const r = await restartForNewSettings(name, dir, next, "silent", {});
+        running = r.running;
+        restarted = r.restarted;
+        restartPending = r.restartPending;
     }
-    writeBotConfig(dir, next);
-    createBotLogger(dir)("info", `settings: model=${next.model ?? "default"} effort=${effectiveBotEffort(next)}${next.effort ? "" : " (default)"}`);
     const result = {
-        ok: true,
+        // A restart that did not bring the bot back is the one failure left.
+        ok: !(restarted && !running),
         name,
+        agentUid: config.agentUid,
         runtime: config.runtime,
         model: next.model ?? null,
         effort: effectiveBotEffort(next),
         effortIsDefault: !next.effort,
         effortLevels: BOT_EFFORT_LEVELS[config.runtime],
+        displayName: next.displayName ?? null,
+        role: localBotRole(next),
+        nameSaved,
+        running,
+        restarted,
+        restartPending,
     };
+    // A bot the restart left down is a failure the exit code has to carry too.
+    if (!result.ok)
+        process.exitCode = 1;
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    console.log(chalk.green(`${name} now thinks with ${result.model ?? "the default model"} at ${result.effort} effort (from its next message).`));
+    if (opts.model !== undefined || opts.effort !== undefined) {
+        console.log(chalk.green(`${name} now thinks with ${result.model ?? "the default model"} at ${result.effort} effort (from its next message).`));
+    }
+    if (displayName !== undefined) {
+        const where = nameSaved === "local-only" ? " (kept on this computer; HQ does not take names yet)" : "";
+        const how = restarted
+            ? running
+                ? "; restarted so it uses the new name"
+                : `; it did not come back after the restart, check: hq bot logs ${name}`
+            : restartPending
+                ? `; it uses the new name after its next restart (hq bot restart ${name})`
+                : "";
+        console.log(chalk.green(`${name} is now called ${displayName}`) + chalk.dim(`${where}${how}`));
+    }
 }
 /** `hq bot probe`: exit code 0 when the runtime answered, 1 when it did not. */
 export async function runBotProbe(opts, deps = {}) {
@@ -1352,7 +1585,7 @@ function isReservedSetupBotRecord(bot, ownerUid) {
     const local = parseBotLocalConfig(bot.localConfig);
     return (!!owner &&
         bot.ownerUid === owner &&
-        bot.slug === `${RESERVED_SETUP_BOT_NAME}-${owner.slice(-8).toLowerCase()}` &&
+        bot.slug === setupSlugFor(owner) &&
         bot.botKind === "personal" &&
         bot.computeMode === "local" &&
         local?.workerSource === "worker" &&
@@ -1521,9 +1754,9 @@ export function configFromLocalConfig(input) {
             : workerSource === "worker"
                 ? { memoryDir: path.join(botWorkerRelDir(name), "memory") }
                 : {}),
-        ...(local?.displayName ? { displayName: local.displayName } : {}),
-        ...(local?.intro ? { intro: local.intro } : {}),
-        ...(local?.kickoff ? { kickoff: local.kickoff } : {}),
+        ...(input.overrides?.displayName ?? local?.displayName ? { displayName: input.overrides?.displayName ?? local?.displayName } : {}),
+        ...(input.overrides?.intro ?? local?.intro ? { intro: input.overrides?.intro ?? local?.intro } : {}),
+        ...(input.overrides?.kickoff ?? local?.kickoff ? { kickoff: input.overrides?.kickoff ?? local?.kickoff } : {}),
         createdAt: (input.now ?? (() => new Date()))().toISOString(),
         enabled: true,
         // A restore is not a first start: the bot's one-off kickoff task already
@@ -1541,6 +1774,12 @@ export function configFromLocalConfig(input) {
  * folders, and its launchd agent.
  */
 async function adoptRemoteBot(input) {
+    // Every adopter (create, adopt, restore) holds the bot's lock, so the
+    // check below and the secret rotation after it happen once, in order. A
+    // caller that already holds it re-enters without waiting.
+    return withBotLock(input.name, () => adoptRemoteBotLocked(input), { command: "hq bot adopt" });
+}
+async function adoptRemoteBotLocked(input) {
     const { bot, name } = input;
     const dir = botDir(name);
     if (readBotConfig(dir)) {
@@ -1604,6 +1843,8 @@ async function adoptRemoteBot(input) {
             memory: botMemoryMode(config),
             memoryDir: scaffold.memoryDir,
             defaulted: local === null,
+            displayName: config.displayName ?? null,
+            role: localBotRole(config),
             notes,
             daemon: daemonMessage,
         },
@@ -1635,40 +1876,42 @@ export async function runBotAdopt(nameArg, opts) {
         }
         throw Object.assign(new Error(runnable.message), { expected: true });
     }
-    if (readBotConfig(dir)) {
-        throw Object.assign(new Error(`Bot "${name}" is already set up on this computer (${dir}). Start it with: hq bot start ${name}`), {
-            expected: true,
+    await withBotLock(name, async () => {
+        if (readBotConfig(dir)) {
+            throw Object.assign(new Error(`Bot "${name}" is already set up on this computer (${dir}). Start it with: hq bot start ${name}`), {
+                expected: true,
+            });
+        }
+        const { result, config } = await adoptRemoteBot({
+            bot,
+            name,
+            api,
+            hqRoot,
+            overrides: {
+                ...(isBotRuntimeId(opts.runtime) ? { runtime: opts.runtime } : {}),
+                ...(model ? { model } : {}),
+            },
+            daemon: opts.daemon !== false,
         });
-    }
-    const { result, config } = await adoptRemoteBot({
-        bot,
-        name,
-        api,
-        hqRoot,
-        overrides: {
-            ...(isBotRuntimeId(opts.runtime) ? { runtime: opts.runtime } : {}),
-            ...(model ? { model } : {}),
-        },
-        daemon: opts.daemon !== false,
-    });
-    if (!opts.json) {
-        console.log(chalk.green(`Brought back bot ${chalk.bold(name)}`) + chalk.dim(` (${result.agentUid}, ${result.runtime})`));
-        console.log(chalk.dim(`  kind:   ${describeKind(result.kind, result.companies)}`));
-        console.log(chalk.dim(`  worker: ${result.worker}`));
-        console.log(chalk.dim(`  memory: ${result.memoryDir} (${result.memory})`));
-        console.log(chalk.dim(`  state:  ${result.dir}`));
-        if (result.daemon)
-            console.log(chalk.dim(`  ${result.daemon}`));
-        for (const note of result.notes)
-            console.log(chalk.yellow(`  ${note}`));
-        console.log(chalk.dim(`  Have it say hello again with: hq bot intro ${name}`));
-    }
-    if (opts.start !== false) {
-        await startBot(name, result.dir, config, opts.json ? "json" : "text", { ...result });
-        return;
-    }
-    if (opts.json)
-        console.log(JSON.stringify({ ok: true, ...result, running: false }, null, 2));
+        if (!opts.json) {
+            console.log(chalk.green(`Brought back bot ${chalk.bold(name)}`) + chalk.dim(` (${result.agentUid}, ${result.runtime})`));
+            console.log(chalk.dim(`  kind:   ${describeKind(result.kind, result.companies)}`));
+            console.log(chalk.dim(`  worker: ${result.worker}`));
+            console.log(chalk.dim(`  memory: ${result.memoryDir} (${result.memory})`));
+            console.log(chalk.dim(`  state:  ${result.dir}`));
+            if (result.daemon)
+                console.log(chalk.dim(`  ${result.daemon}`));
+            for (const note of result.notes)
+                console.log(chalk.yellow(`  ${note}`));
+            console.log(chalk.dim(`  Have it say hello again with: hq bot intro ${name}`));
+        }
+        if (opts.start !== false) {
+            await startBot(name, result.dir, config, opts.json ? "json" : "text", { ...result });
+            return;
+        }
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, ...result, running: false }, null, 2));
+    }, { command: "hq bot adopt" });
 }
 /** New credentials + a reinstalled startup agent for a bot that IS already here. */
 async function repairLocalBot(name, api, bot, daemon) {
@@ -1712,8 +1955,9 @@ export async function runBotRestore(opts) {
     const rows = [];
     for (const bot of bots) {
         const name = localNameForRemoteBot(bot);
+        const shown = { displayName: remoteBotDisplayName(bot, name), role: remoteBotRole(bot) };
         if (!name) {
-            rows.push({ name: bot.name ?? bot.agentUid, agentUid: bot.agentUid, action: "failed", detail: "its name cannot be a folder name here; rename it in HQ" });
+            rows.push({ name: bot.name ?? bot.agentUid, agentUid: bot.agentUid, action: "failed", detail: "its name cannot be a folder name here; rename it in HQ", ...shown });
             continue;
         }
         // A bot this computer cannot run is never brought back: it would get
@@ -1727,41 +1971,45 @@ export async function runBotRestore(opts) {
                 action: opts.dryRun ? "would-skip" : "skipped",
                 reason: runnable.reason,
                 detail: runnable.message,
+                ...shown,
             });
             continue;
         }
-        const here = readBotConfig(botDir(name)) !== null;
         const settings = describeBotLocalConfig(parseBotLocalConfig(bot.localConfig));
-        if (here && hasPromotionHold(botDir(name))) {
-            rows.push({ name, agentUid: bot.agentUid, action: opts.dryRun ? "would-skip" : "skipped", detail: "held for cloud promotion" });
-            continue;
-        }
-        if (here && !opts.all) {
-            rows.push({ name, agentUid: bot.agentUid, action: opts.dryRun ? "would-skip" : "skipped", detail: "already set up here" });
-            continue;
-        }
-        if (opts.dryRun) {
-            rows.push({ name, agentUid: bot.agentUid, action: here ? "would-repair" : "would-restore", detail: here ? "new credentials" : settings });
-            continue;
-        }
-        try {
-            if (here) {
-                rows.push({ name, agentUid: bot.agentUid, action: "repaired", detail: await repairLocalBot(name, api, bot, opts.daemon !== false) });
+        // Decided and done under the bot's lock: a create or adopt of the same bot
+        // running at the same moment either finished first (and this skips it as
+        // already here) or waits for this one.
+        const restoreOne = async () => {
+            const here = readBotConfig(botDir(name)) !== null;
+            if (here && hasPromotionHold(botDir(name))) {
+                return { name, agentUid: bot.agentUid, action: opts.dryRun ? "would-skip" : "skipped", detail: "held for cloud promotion", ...shown };
             }
-            else {
-                const { result, config } = await adoptRemoteBot({ bot, name, api, hqRoot, daemon: opts.daemon !== false });
-                // Silent: this command's own JSON has to be the only document on stdout.
-                const started = opts.start === false ? null : await startBot(name, result.dir, config, "silent").catch(() => null);
-                rows.push({
-                    name,
-                    agentUid: bot.agentUid,
-                    action: "restored",
-                    detail: [settings, ...result.notes, ...(started ? [started.running ? "started" : "not running yet — hq bot logs " + name] : [])].join("; "),
-                });
+            if (here && !opts.all) {
+                return { name, agentUid: bot.agentUid, action: opts.dryRun ? "would-skip" : "skipped", detail: "already set up here", ...shown };
+            }
+            if (opts.dryRun) {
+                return { name, agentUid: bot.agentUid, action: here ? "would-repair" : "would-restore", detail: here ? "new credentials" : settings, ...shown };
+            }
+            if (here) {
+                return { name, agentUid: bot.agentUid, action: "repaired", detail: await repairLocalBot(name, api, bot, opts.daemon !== false), ...shown };
             }
+            const { result, config } = await adoptRemoteBot({ bot, name, api, hqRoot, daemon: opts.daemon !== false });
+            // Silent: this command's own JSON has to be the only document on stdout.
+            const started = opts.start === false ? null : await startBot(name, result.dir, config, "silent").catch(() => null);
+            return {
+                name,
+                agentUid: bot.agentUid,
+                action: "restored",
+                detail: [settings, ...result.notes, ...(started ? [started.running ? "started" : "not running yet (see hq bot logs " + name + ")"] : [])].join("; "),
+                displayName: shown.displayName ?? result.displayName,
+                role: shown.role ?? result.role,
+            };
+        };
+        try {
+            rows.push(opts.dryRun ? await restoreOne() : await withBotLock(name, restoreOne, { command: "hq bot restore" }));
         }
         catch (err) {
-            rows.push({ name, agentUid: bot.agentUid, action: "failed", detail: err instanceof Error ? err.message : String(err) });
+            rows.push({ name, agentUid: bot.agentUid, action: "failed", detail: err instanceof Error ? err.message : String(err), ...shown });
         }
     }
     const counted = (action) => rows.filter((r) => r.action === action).length;
@@ -1816,6 +2064,8 @@ async function runBotListRemote(opts) {
             settings: describeBotLocalConfig(parseBotLocalConfig(bot.localConfig)),
             runnable: runnable.runnable,
             reason: runnable.reason,
+            displayName: remoteBotDisplayName(bot, name),
+            role: remoteBotRole(bot),
         };
     });
     if (opts.json) {
@@ -1970,8 +2220,9 @@ export function registerBotCommand(program) {
         .action((name, opts) => wrap(() => runBotRm(name, opts))());
     bot
         .command("set <name>")
-        .description("Change the model and thinking level a bot uses (applies from its next message)")
+        .description("Change the model and thinking level a bot uses (applies from its next message), or the name people see for it (saved in HQ; a running bot restarts to use it)")
         .option("--model <model>", "Model id for the runtime CLI, or default for the CLI's own default")
+        .option("--display-name <name>", `The name people see for the bot in HQ (up to ${BOT_DISPLAY_NAME_MAX_CHARS} chars). The handle stays <name>`)
         .option("--effort <level>", `Thinking level (claude ${BOT_EFFORT_LEVELS.claude.join("|")}; codex ${BOT_EFFORT_LEVELS.codex.join("|")}; grok ${BOT_EFFORT_LEVELS.grok.join("|")}), or default (${DEFAULT_BOT_EFFORT})`)
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(() => runBotSet(name, opts))());