@indigoai-us/hq-cli 5.115.6 → 5.117.0

package/dist/commands/bot.js

@@ -7,7 +7,9 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  *   hq bot create <name> [--kind personal|company] [--company slug]... [--runtime claude|codex|grok] [--model m] [--effort level] [--worker id] [--intro text] [--kickoff prompt] [--memory synced|local] [--no-daemon]
  *   hq bot companies <name> [--add slug]... [--remove slug]...   (a company bot's memberships)
  *   hq bot workers [--json]              (company + core workers a bot can be created from)
- *   hq bot list [--json]
+ *   hq bot list [--remote] [--json]
+ *   hq bot adopt <name> [--runtime r] [--model m]   (a bot you own, back on this computer)
+ *   hq bot restore [--all] [--dry-run]    (every bot you own that is missing here)
  *   hq bot start|stop|restart <name>
  *   hq bot status <name> [--json]
  *   hq bot logs <name> [--follow] [-n N]
@@ -26,6 +28,7 @@ import { registerBotContinuityCommand } from "./bot-continuity.js";
 import chalk from "chalk";
 import { execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { DEFAULT_COGNITO, ensureCognitoToken, resolveDefaultHqRoot, } from "../utils/cognito-session.js";
@@ -33,7 +36,7 @@ import { peekHqApiKey } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, resolveCallerPersonUid } from "../utils/vault-api.js";
 import { resolveHqBinary } from "../lib/mesh/live/daemon/install.js";
 import { runtimeDisplayName } from "../lib/bot/runtime-sign-in.js";
-import { BotApi, BotApiError, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, validateBotKickoff, validateBotEffort, validateBotModel, effectiveBotEffort, BOT_EFFORT_LEVELS, DEFAULT_BOT_EFFORT, BOT_MEMORY_MODES, BOT_KINDS, isBotKind, effectiveBotKind, effectiveBotCompanies, normalizeBotCompanies, SETUP_BOT_WORKER_ID, isBotRuntimeId, isPidAlive, listBotWorkerOptions, patchBotConfig, readBotConfig, readBotCredsIdentity, readBotStatus, resolveBotWorker, runBot, runtimeFor, scaffoldBotMemory, scaffoldBotWorker, startBotDaemon, stopBotDaemon, uninstallBotDaemon, validateBotName, writeBotConfig, writeBotCreds, BOT_RUNTIMES, BOT_INTRO_MAX_CHARS, BOT_KICKOFF_MAX_CHARS, } 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, introDmText, isBotMemoryMode, botLocalMemoryDir, botMemoryMode, resolveBotMemoryDir, validateBotIntro, 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_KICKOFF_MAX_CHARS, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -81,9 +84,10 @@ function requireBot(name) {
     const dir = botDir(valid);
     const config = readBotConfig(dir);
     if (!config) {
-        throw Object.assign(new Error(`No bot named "${valid}". Create one with: hq bot create ${valid}`), {
-            expected: true,
-        });
+        // Never point at `create` alone: after a wiped ~/.hq the cloud still has
+        // the bot, so creating it refuses with a 409 and sends the person straight
+        // back here. Adopting is the move that works.
+        throw Object.assign(new Error(`No bot named "${valid}" is set up on this computer. Bring it back with: hq bot adopt ${valid}   (or make a new one: hq bot create ${valid})`), { expected: true });
     }
     return { name: valid, dir, config };
 }
@@ -223,7 +227,12 @@ function stopProcess(dir) {
         return false;
     }
 }
-async function startBot(name, dir, config, json, extra = {}) {
+/**
+ * `output`: "json" | "text" print the result; "silent" prints nothing — a
+ * restore brings several bots back and its own JSON must be the only document
+ * on stdout (the desktop app parses it whole).
+ */
+async function startBot(name, dir, config, output, extra = {}) {
     if (hasPromotionHold(dir))
         throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
     if (config.enabled === false)
@@ -249,9 +258,11 @@ async function startBot(name, dir, config, json, extra = {}) {
         return !!s && s.state === "running" && isPidAlive(s.pid);
     }, 15_000);
     const status = readBotStatus(dir);
-    if (json) {
+    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));
-        return;
+        return { running, how };
     }
     if (running)
         console.log(chalk.green(`${name} is running`) + chalk.dim(` (${how})`));
@@ -261,6 +272,7 @@ async function startBot(name, dir, config, json, extra = {}) {
             console.log(chalk.dim(`  last error: ${status.lastError}`));
         console.log(chalk.dim(`  logs: hq bot logs ${name}`));
     }
+    return { running, how };
 }
 /**
  * `output`: "json" | "text" print a result; "silent" prints nothing — used
@@ -380,12 +392,28 @@ export async function runBotCreate(nameArg, opts) {
             throw Object.assign(new Error(`Cannot create ${name}: ${err instanceof Error ? err.message : String(err)} (company "${slug}").`), { expected: true });
         }
     }
+    // The bot's non-secret settings travel with its cloud identity, so a
+    // reinstall (or a second Mac) can rebuild the same bot with `hq bot adopt`
+    // instead of creating a new one. The machine secret never travels.
+    const localConfig = buildBotLocalConfig({
+        runtime,
+        kind,
+        ...(kind === "company" ? { companies } : {}),
+        ...(model ? { model } : {}),
+        ...(effort ? { effort } : {}),
+        ...(opts.autoApprove === false ? { autoApprove: false } : {}),
+        ...(worker
+            ? { workerSource: "worker", workerId: worker.id, ...(worker.company ? { companySlug: worker.company } : {}) }
+            : { workerSource: "scaffold" }),
+        ...(memoryMode === "local" ? { memoryDir: botLocalMemoryDir(dir) } : {}),
+    });
     let created;
     try {
         created = await api.createLocalBot({
             name,
             kind,
             ...(kind === "company" ? { companyUid: companyUids[0], companyMemberships: companyUids.slice(1) } : {}),
+            localConfig,
         });
     }
     catch (err) {
@@ -400,6 +428,13 @@ export async function runBotCreate(nameArg, opts) {
                 expected: true,
             });
         }
+        if (err instanceof BotApiError && err.status === 409) {
+            // The cloud already has this bot; it is simply not set up on this
+            // computer (a reinstall, or a second Mac). Re-creating it is the wrong
+            // move — adopting brings the existing one back, memory and all.
+            throw Object.assign(new Error(`You already have a bot named "${name}" in HQ — it is just not set up on this computer. ` +
+                `Bring it back with: hq bot adopt ${name}   (or restore every bot you own: hq bot restore)`), { expected: true });
+        }
         throw err;
     }
     const agentUid = created.agent.uid;
@@ -519,7 +554,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, Boolean(opts.json), { ...created_, daemon: daemonMessage });
+        await startBot(name, dir, config, opts.json ? "json" : "text", { ...created_, daemon: daemonMessage });
         return;
     }
     if (opts.json) {
@@ -605,7 +640,33 @@ export async function runBotWorkers(opts) {
 }
 // ── run (resident) ───────────────────────────────────────────────────────────
 async function runBotResident(nameArg) {
-    const { name, dir, config } = requireBot(nameArg);
+    const name = validateBotName(nameArg);
+    const dir = botDir(name);
+    const config = readBotConfig(dir);
+    if (!config) {
+        // A LaunchAgent that outlived its bot: exiting non-zero here made launchd
+        // relaunch this every five seconds forever. Say so once, take the stale
+        // registration away, and exit 0 (KeepAlive{SuccessfulExit:false} leaves a
+        // clean exit alone).
+        //
+        // Under launchd this process IS the job, so the order is load-bearing: the
+        // line lands in bot.log and the plist is unlinked while we are still
+        // alive, and only then is the `bootout` — which kills us — asked for, in a
+        // detached session that outlives us. Printing after the removal, as this
+        // did, produced an empty log and a surviving plist on a real Mac.
+        let said = false;
+        const outcome = removeOrphanBotDaemon({
+            name,
+            botDir: dir,
+            announce: (o) => {
+                said = true;
+                console.log(orphanBotRunMessage(name, o));
+            },
+        }, daemonDeps());
+        if (!said)
+            console.log(orphanBotRunMessage(name, outcome));
+        return;
+    }
     const api = new BotApi({ token: botTokenSupplier(dir) });
     const owner = new OwnerContextCache(() => lookupOwnerContext(config.ownerUid), Date.now, undefined, config.ownerUid);
     const handle = await runBot({ dir, config, api, runtime: runtimeFor(config.runtime), ownerContext: () => owner.get() });
@@ -614,6 +675,10 @@ async function runBotResident(nameArg) {
 }
 // ── list / status / logs ─────────────────────────────────────────────────────
 async function runBotList(opts) {
+    if (opts.remote) {
+        await runBotListRemote(opts);
+        return;
+    }
     const rows = listBotNames(botsRoot()).map((n) => rowFor(n));
     await decorateOnline(rows);
     if (opts.json) {
@@ -698,7 +763,134 @@ async function confirm(question) {
         });
     });
 }
+/**
+ * `hq bot rm <name>` for a bot whose bot.json is gone — a wiped ~/.hq, a
+ * half-finished reinstall, a folder deleted by hand. Without this the
+ * leftovers were unreachable: `rm` refused because there was no config, and
+ * the message it gave pointed at `create`, which refuses in turn because the
+ * cloud still has the bot. Remove what is actually on this computer, and with
+ * --remote the bot HQ still holds under that name.
+ */
+async function runBotRmOrphan(name, opts) {
+    const dir = botDir(name);
+    const hadDir = fs.existsSync(dir);
+    let plistPath = null;
+    try {
+        plistPath = buildBotDaemonPaths({ name, botDir: dir, hqBinary: "hq", nodeBinary: process.execPath }).plistPath;
+    }
+    catch {
+        /* no resolvable home: there is nothing to say about a startup agent */
+    }
+    const hadDaemon = plistPath !== null && fs.existsSync(plistPath);
+    // Ask HQ before touching anything local, so a server that cannot answer does
+    // not leave the removal half done.
+    let api = null;
+    let remote = null;
+    if (opts.remote) {
+        const token = await ownerToken();
+        api = new BotApi({ token: async () => token });
+        const mine = await listMyBotsOrExplain(api, {
+            json: opts.json,
+            emptyResult: { name, orphan: true, localStateRemoved: false, remoteRemoved: false },
+        });
+        const hits = matchRemoteBots(mine, name);
+        if (hits.length > 1) {
+            throw Object.assign(new Error(`You own more than one bot called "${name}": ${hits.map((h) => h.agentUid).join(", ")}. Name the one you mean by its id.`), {
+                expected: true,
+            });
+        }
+        remote = hits[0] ?? null;
+    }
+    if (!hadDir && !hadDaemon && !remote) {
+        throw Object.assign(new Error(opts.remote
+            ? `Nothing named "${name}" is left on this computer, and HQ has no bot by that name either.`
+            : `Nothing named "${name}" is left on this computer. If HQ still has a bot by that name, remove that too with: hq bot rm ${name} --remote`), { expected: true });
+    }
+    if (!opts.yes) {
+        const ok = await confirm(`"${name}" has no settings left on this computer. Remove what is left of it${remote ? `, and the bot HQ still has by that name (${remote.agentUid})` : ""}? [y/N] `);
+        if (!ok) {
+            console.log(chalk.dim("Cancelled."));
+            return;
+        }
+    }
+    // Inline bootout: unlike the self-heal, this process is not the launchd job.
+    const daemon = removeOrphanBotDaemon({ name, botDir: dir }, { ...daemonDeps(), bootout: "inline" });
+    if (hadDir)
+        fs.rmSync(dir, { recursive: true, force: true });
+    let remoteRemoved = false;
+    let remoteDetail = null;
+    let remoteSteps = [];
+    let failure = null;
+    if (remote && api) {
+        try {
+            const identity = await api.deleteLocalBot(remote.agentUid);
+            remoteRemoved = identity.terminal;
+            if (identity.terminal) {
+                remoteDetail = "removed from HQ";
+            }
+            else {
+                const incomplete = botRemovalIncomplete(identity.failures);
+                remoteDetail = incomplete.detail;
+                remoteSteps = incomplete.steps;
+                failure = {
+                    reason: incomplete.reason,
+                    message: `"${name}" is gone from this computer, but ${incomplete.detail}.` +
+                        (incomplete.retryable ? ` Run the same command again to finish clearing it from HQ.` : ` The leftover is HQ's to clear.`),
+                };
+            }
+        }
+        catch (err) {
+            if (err instanceof BotApiError && err.status === 404) {
+                remoteRemoved = true;
+                remoteDetail = "it was already gone from HQ";
+            }
+            else {
+                // Never the transport string: one plain sentence, and the reason the
+                // desktop switches on.
+                const refused = botRemoteDeleteRefused(name, err);
+                remoteDetail = refused.detail;
+                failure = { reason: refused.reason, message: refused.message };
+            }
+        }
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: remote === null || remoteRemoved,
+            ...(failure ? { reason: failure.reason, message: failure.message } : {}),
+            name,
+            orphan: true,
+            agentUid: remote?.agentUid ?? null,
+            daemon: daemon.message,
+            localStateRemoved: hadDir,
+            remoteRemoved,
+            remoteDetail,
+            remoteStepsUnfinished: remoteSteps,
+        }, null, 2));
+        if (failure)
+            throw Object.assign(new Error(failure.message), { expected: true });
+        return;
+    }
+    console.log(chalk.green(`Removed what was left of "${name}" on this computer`) + chalk.dim(" (its settings were already gone)."));
+    console.log(chalk.dim(`  startup agent: ${daemon.message}`));
+    console.log(chalk.dim(`  local folder:  ${hadDir ? `removed ${dir}` : "there was none left"}`));
+    if (failure) {
+        if (remoteSteps.length > 0)
+            console.log(chalk.dim(`  in HQ:         did not finish ${remoteSteps.join(", ")}`));
+        throw Object.assign(new Error(failure.message), { expected: true });
+    }
+    if (remote)
+        console.log(chalk.green(`  in HQ:         ${remoteDetail}`));
+    else if (opts.remote)
+        console.log(chalk.dim(`  in HQ:         HQ has no bot named "${name}", so there was nothing to remove there.`));
+    else
+        console.log(chalk.dim(`  HQ may still have a bot named "${name}". Remove that too with: hq bot rm ${name} --remote`));
+}
 async function runBotRm(nameArg, opts) {
+    const validated = validateBotName(nameArg);
+    if (readBotConfig(botDir(validated)) === null) {
+        await runBotRmOrphan(validated, opts);
+        return;
+    }
     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.");
@@ -725,15 +917,48 @@ async function runBotRm(nameArg, opts) {
             throw err;
     }
     const terminal = "alreadyGone" in identity ? true : identity.terminal;
+    // A teardown HQ could only half-finish. Classified here so neither branch
+    // below ever repeats what the server said: one real answer carried the AWS
+    // account id, an assumed-role ARN and a DynamoDB table ARN.
+    const incomplete = terminal ? null : botRemovalIncomplete("failures" in identity ? identity.failures : undefined);
     // A company bot is a member of its companies: leave them too. Best effort —
     // a stale membership row must not keep the bot's local state around.
     const memberships = effectiveBotCompanies(config);
     const left = memberships.length > 0 ? await removeBotFromCompanies({ agentUid: config.agentUid, companies: memberships, token }) : { done: [], failed: [] };
     deleteBotCreds(dir);
-    if (terminal)
+    // The local-state decision. A refusal, or a step whose target was already
+    // gone, answers the same way forever — and by then the steps that did
+    // succeed have left a bot that can no longer sign in, so keeping its folder
+    // only strands the person with something that cannot run and cannot be
+    // re-created under the same name. Everything else keeps the folder, so the
+    // same command can pick the job back up.
+    const localStateRemoved = terminal || incomplete.retryable === false;
+    if (localStateRemoved)
         fs.rmSync(dir, { recursive: true, force: true });
+    const message = incomplete
+        ? `HQ removed what it could of "${name}", but ${incomplete.detail}.` +
+            (incomplete.retryable
+                ? ` Its settings are kept on this computer, so run the same command again to finish it.`
+                : ` It is gone from this computer; the leftover is HQ's to clear.`)
+        : null;
     if (opts.json) {
-        console.log(JSON.stringify({ ok: terminal, name, agentUid: config.agentUid, daemon: daemon.message, identity, companiesLeft: left.done, companiesNotLeft: left.failed, localStateRemoved: terminal, workerKept: path.join(config.hqRoot, config.workerDir) }, null, 2));
+        console.log(JSON.stringify({
+            ok: terminal,
+            ...(incomplete && message ? { reason: incomplete.reason, message } : {}),
+            name,
+            orphan: false,
+            agentUid: config.agentUid,
+            daemon: daemon.message,
+            companiesLeft: left.done,
+            companiesNotLeft: left.failed,
+            localStateRemoved,
+            remoteRemoved: terminal,
+            remoteDetail: incomplete ? incomplete.detail : "alreadyGone" in identity ? "it was already gone from HQ" : "removed from HQ",
+            remoteStepsUnfinished: incomplete?.steps ?? [],
+            workerKept: path.join(config.hqRoot, config.workerDir),
+        }, null, 2));
+        if (message)
+            throw Object.assign(new Error(message), { expected: true });
         return;
     }
     for (const f of left.failed) {
@@ -741,15 +966,11 @@ async function runBotRm(nameArg, opts) {
     }
     if (terminal) {
         console.log(chalk.green(`Removed bot ${name}`) + chalk.dim(` (${config.agentUid}${left.done.length ? `; left ${left.done.join(", ")}` : ""}); worker folder kept at ${path.join(config.hqRoot, config.workerDir)}`));
+        return;
     }
-    else {
-        console.log(chalk.yellow(`Bot ${name} is stopped locally but its cloud identity is not fully removed yet.`));
-        if ("failures" in identity && identity.failures) {
-            for (const [step, msg] of Object.entries(identity.failures))
-                console.log(chalk.dim(`  ${step}: ${msg}`));
-        }
-        console.log(chalk.dim(`  Re-run: hq bot rm ${name} --yes`));
-    }
+    if (incomplete.steps.length > 0)
+        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
@@ -804,6 +1025,500 @@ async function runBotIntro(nameArg) {
     patchBotConfig(dir, { introSentAt: new Date().toISOString() });
     console.log(chalk.green(`${name} introduced itself to you.`));
 }
+// ── adopt / restore (bring a bot you own back to this computer) ──────────────
+/**
+ * Which computer a re-issue is for. Never a secret and never an identifier the
+ * server needs to trust — it only shows up in the bot's audit trail so its
+ * owner can see where it was last brought back.
+ */
+function localMachineId() {
+    const host = os.hostname().trim();
+    return host || "unknown-machine";
+}
+/**
+ * The one bot the caller means. Matches the local folder name, the cloud slug,
+ * the display name, or the agt_ uid; an ambiguous name is refused rather than
+ * guessed at.
+ */
+export function matchRemoteBots(bots, wanted) {
+    const needle = wanted.trim().toLowerCase();
+    return bots.filter((b) => b.agentUid === wanted.trim() ||
+        (b.slug ?? "").trim().toLowerCase() === needle ||
+        (b.name ?? "").trim().toLowerCase() === needle ||
+        localNameForRemoteBot(b) === needle);
+}
+export function resolveRemoteBot(bots, wanted) {
+    const hits = matchRemoteBots(bots, wanted);
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length > 1) {
+        throw Object.assign(new Error(`You own more than one bot called "${wanted}": ${hits.map((h) => h.agentUid).join(", ")}. Name the one you mean by its id.`), { expected: true });
+    }
+    const known = bots.map((b) => localNameForRemoteBot(b) ?? b.agentUid);
+    throw Object.assign(new Error(known.length > 0
+        ? `You have no bot called "${wanted}" in HQ. Bots you own: ${known.join(", ")}.`
+        : `You have no local bots in HQ yet. Create one with: hq bot create ${wanted}`), { expected: true });
+}
+/** Turn a BotApiError from the credential route into a sentence a person can act on. */
+function credentialError(err, name) {
+    if (err instanceof BotApiError && err.status === 403) {
+        return Object.assign(new Error(`HQ will not hand out credentials for "${name}": it is either not yours, or it is a cloud agent rather than a local bot.`), { expected: true });
+    }
+    if (err instanceof BotApiError && err.status === 404) {
+        return Object.assign(new Error(`HQ no longer has a bot called "${name}". Create a new one with: hq bot create ${name}`), {
+            expected: true,
+        });
+    }
+    return err;
+}
+/**
+ * Turn any failure of `GET /v1/agents/mine` into one plain sentence plus a
+ * stable reason. Production HQ Cloud does not serve that route yet, and an
+ * uncaught 404 reached the person verbatim as "HQ API /v1/agents/mine → 404:
+ * Not found" — and, under --json, as no document at all.
+ */
+export function remoteBotsUnavailable(err) {
+    if (err instanceof BotApiError) {
+        if (err.status === 404 || err.status === 501) {
+            return {
+                reason: "server-unsupported",
+                message: "Your HQ Cloud cannot list the bots you own yet, so there is nothing to bring back from here. Update HQ Cloud, or try again later.",
+            };
+        }
+        if (err.status === 401 || err.status === 403) {
+            return { reason: "auth", message: "HQ did not accept your sign-in, so it would not say which bots you own. Sign in again with: hq login" };
+        }
+        if (err.status >= 500) {
+            return { reason: "server-error", message: "HQ Cloud had trouble listing the bots you own. Try again in a minute." };
+        }
+        return { reason: "error", message: "HQ could not say which bots you own, so there is nothing to bring back from here. Try again in a minute." };
+    }
+    const text = err instanceof Error ? err.message : String(err);
+    if (/fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|EAI_AGAIN|EHOSTUNREACH|ETIMEDOUT|network|socket hang up|timed? ?out/i.test(text)) {
+        return { reason: "network", message: "HQ could not be reached, so it could not say which bots you own. Check your connection and try again." };
+    }
+    return { reason: "error", message: "HQ could not say which bots you own, so there is nothing to bring back from here. Try again in a minute." };
+}
+const REFUSED_TEARDOWN_STEP = /access\s?denied|not authori[sz]ed|unauthori[sz]ed|forbidden|identity-based policy|permission/i;
+const ALREADY_GONE_TEARDOWN_STEP = /not\s?found|no such|does not exist|already (?:gone|deleted|removed)/i;
+/**
+ * Step names are fixed server vocabulary (`delete-creator-owner`). Anything
+ * that is not plainly one is dropped rather than echoed.
+ */
+function safeTeardownSteps(failures) {
+    return Object.keys(failures ?? {}).filter((step) => /^[a-z0-9][a-z0-9._-]{0,39}$/i.test(step));
+}
+export function botRemovalIncomplete(failures) {
+    const steps = safeTeardownSteps(failures);
+    const texts = Object.values(failures ?? {});
+    const refused = texts.some((text) => REFUSED_TEARDOWN_STEP.test(text));
+    const permanent = texts.length > 0 && texts.every((text) => REFUSED_TEARDOWN_STEP.test(text) || ALREADY_GONE_TEARDOWN_STEP.test(text));
+    if (permanent) {
+        return refused
+            ? { reason: "auth", detail: "HQ was not allowed to finish clearing its cloud identity, and would be refused the same way next time", retryable: false, steps }
+            : { reason: "error", detail: "HQ found part of its cloud identity already gone, and would find the same next time", retryable: false, steps };
+    }
+    return { reason: "server-error", detail: "HQ has not finished removing it from the cloud", retryable: true, steps };
+}
+/**
+ * A cloud delete that threw. Reuses {@link remoteBotsUnavailable}'s
+ * classification of the transport, with a sentence about removal rather than
+ * listing — and, as there, the transport string never reaches the person.
+ * A 404 is not routed here: for a delete it means the bot was already gone.
+ */
+function botRemoteDeleteRefused(name, err) {
+    const { reason } = remoteBotsUnavailable(err);
+    const next = reason === "auth" ? "Sign in again with: hq login, then run this again." : reason === "network" ? "Check your connection and run this again." : "Try again in a minute.";
+    return {
+        reason,
+        detail: reason === "auth" ? "HQ did not accept your sign-in" : reason === "network" ? "HQ could not be reached" : "HQ could not remove it just now",
+        message: `"${name}" is gone from this computer, but HQ could not remove the bot it still has under that name. ${next}`,
+    };
+}
+/**
+ * The account's own local bots, or a refusal shaped for both audiences: one
+ * plain sentence for a person (via the thrown expected error, exit 1), and —
+ * under --json — a document on stdout that always parses, carrying the reason
+ * the desktop keys off plus whatever empty fields its success shape promises.
+ */
+async function listMyBotsOrExplain(api, opts) {
+    try {
+        return await api.listMine({ local: true });
+    }
+    catch (err) {
+        const failure = remoteBotsUnavailable(err);
+        if (opts.json)
+            console.log(JSON.stringify({ ok: false, ...failure, ...(opts.emptyResult ?? {}) }, null, 2));
+        throw Object.assign(new Error(failure.message), { expected: true });
+    }
+}
+/**
+ * Rebuild a bot.json from the settings the cloud kept for it. A bot created
+ * before HQ saved settings comes back on defaults, and anything this HQ can no
+ * longer provide (a worker that is not here, a thinking level the chosen
+ * runtime does not accept) is reported rather than silently kept.
+ */
+export function configFromLocalConfig(input) {
+    const { name, local } = input;
+    const notes = [];
+    if (!local) {
+        notes.push(`${name} was created before HQ kept a bot's settings in the cloud, so it comes back on defaults (${describeBotLocalConfig(null)}). Change them with: hq bot set ${name} --model <id> --effort <level>`);
+    }
+    const runtime = input.overrides?.runtime ?? local?.runtime ?? BOT_RESTORE_DEFAULTS.runtime;
+    const kind = local?.kind ?? BOT_RESTORE_DEFAULTS.kind;
+    const memory = local?.memory ?? BOT_RESTORE_DEFAULTS.memory;
+    const model = input.overrides?.model ?? local?.model;
+    let effort = local?.effort;
+    if (effort && !BOT_EFFORT_LEVELS[runtime].includes(effort)) {
+        notes.push(`${runtime} has no "${effort}" thinking level, so ${name} comes back on the default (${DEFAULT_BOT_EFFORT}).`);
+        effort = undefined;
+    }
+    let workerSource = "scaffold";
+    let workerDir = botWorkerRelDir(name);
+    let workerId;
+    let companySlug = local?.companySlug;
+    if (local?.workerSource === "worker" && local.workerId) {
+        try {
+            const worker = resolveBotWorker(input.hqRoot, local.workerId);
+            workerSource = "worker";
+            workerDir = worker.path;
+            workerId = worker.id;
+            companySlug = worker.company ?? undefined;
+        }
+        catch {
+            notes.push(`the worker "${local.workerId}" is not in this HQ, so ${name} comes back with its own scaffolded worker folder instead.`);
+            companySlug = undefined;
+        }
+    }
+    const config = {
+        v: 1,
+        name,
+        agentUid: input.agentUid,
+        ownerUid: input.ownerUid,
+        runtime,
+        kind,
+        ...(kind === "company" ? { companies: local?.companies ?? [] } : {}),
+        ...(model ? { model } : {}),
+        ...(effort ? { effort } : {}),
+        ...(local?.autoApprove === false ? { autoApprove: false } : {}),
+        hqRoot: input.hqRoot,
+        workerDir,
+        ...(workerSource === "worker" && workerId ? { workerSource, workerId } : {}),
+        ...(companySlug ? { companySlug } : {}),
+        ...(memory === "local"
+            ? { memoryDir: botLocalMemoryDir(input.dir) }
+            : workerSource === "worker"
+                ? { memoryDir: path.join(botWorkerRelDir(name), "memory") }
+                : {}),
+        ...(local?.intro ? { intro: local.intro } : {}),
+        ...(local?.kickoff ? { 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
+        // ran on the machine it was created on, and `runs once` has to keep
+        // meaning once. `hq bot intro <name>` has it say hello again.
+        introSentAt: (input.now ?? (() => new Date()))().toISOString(),
+    };
+    return { config, notes };
+}
+/**
+ * The tail of the create path, run against a bot that already exists in the
+ * cloud: fresh machine credentials, a rebuilt bot.json, its worker/memory
+ * folders, and its launchd agent.
+ */
+async function adoptRemoteBot(input) {
+    const { bot, name } = input;
+    const dir = botDir(name);
+    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,
+        });
+    }
+    // The last gate before anything is written or any secret is rotated: the
+    // runtime's own rule, so nothing is ever adopted that could not then start.
+    const runnable = remoteBotRunnability(bot, name);
+    if (!runnable.runnable) {
+        throw Object.assign(new Error(runnable.message), { expected: true });
+    }
+    let reissued;
+    try {
+        reissued = await input.api.reissueCredentials(bot.agentUid, { machineId: localMachineId(), reason: "reinstall" });
+    }
+    catch (err) {
+        throw credentialError(err, name);
+    }
+    writeBotCreds(dir, {
+        username: reissued.identity.cognitoUsername,
+        secret: reissued.identity.secret,
+        entityType: "agent",
+        entityUid: bot.agentUid,
+        clientId: DEFAULT_COGNITO.clientId,
+        region: DEFAULT_COGNITO.region,
+    });
+    const local = parseBotLocalConfig(reissued.localConfig ?? bot.localConfig);
+    const { config, notes } = configFromLocalConfig({
+        name,
+        agentUid: bot.agentUid,
+        ownerUid: reissued.agent.ownerUid ?? bot.ownerUid ?? "",
+        hqRoot: input.hqRoot,
+        dir,
+        local,
+        ...(input.overrides ? { overrides: input.overrides } : {}),
+    });
+    writeBotConfig(dir, config);
+    const scaffoldOpts = { memoryDir: config.memoryDir };
+    const scaffold = config.workerSource === "worker"
+        ? scaffoldBotMemory(input.hqRoot, name, undefined, scaffoldOpts)
+        : scaffoldBotWorker(input.hqRoot, name, bot.agentUid, config.runtime, undefined, scaffoldOpts);
+    createBotLogger(dir)("info", `adopted ${name} (${bot.agentUid}) on ${localMachineId()} kind=${config.kind}${local ? "" : " (no saved settings; defaults)"} runtime=${config.runtime}`);
+    let daemonMessage = null;
+    if (input.daemon && process.platform === "darwin") {
+        daemonMessage = installBotDaemon(buildBotDaemonPaths({ name, botDir: dir, hqRoot: input.hqRoot }), daemonDeps()).message;
+    }
+    return {
+        config,
+        dir,
+        result: {
+            name,
+            agentUid: bot.agentUid,
+            runtime: config.runtime,
+            kind: effectiveBotKind(config),
+            companies: effectiveBotCompanies(config),
+            dir,
+            worker: scaffold.dir,
+            memory: botMemoryMode(config),
+            memoryDir: scaffold.memoryDir,
+            defaulted: local === null,
+            notes,
+            daemon: daemonMessage,
+        },
+    };
+}
+export async function runBotAdopt(nameArg, opts) {
+    const asked = validateBotName(nameArg);
+    if (readBotConfig(botDir(asked))) {
+        throw Object.assign(new Error(`Bot "${asked}" is already set up on this computer (${botDir(asked)}). Start it with: hq bot start ${asked}`), {
+            expected: true,
+        });
+    }
+    if (opts.runtime !== undefined && !isBotRuntimeId(opts.runtime)) {
+        throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
+    }
+    const model = opts.model !== undefined ? validateBotModel(opts.model) : undefined;
+    const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
+    const token = await ownerToken();
+    const api = new BotApi({ token: async () => token });
+    const bot = resolveRemoteBot(await listMyBotsOrExplain(api, { json: opts.json }), asked);
+    // One bot, one directory: a bot created here as `qa-x` and slugged
+    // `qa-x-<owner>` in the cloud comes back to ~/.hq/bots/qa-x/, not beside it.
+    const name = localNameForRemoteBot(bot) ?? asked;
+    const dir = botDir(name);
+    const runnable = remoteBotRunnability(bot, name);
+    if (!runnable.runnable) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, reason: "not-runnable-here", notRunnable: runnable.reason, name, agentUid: bot.agentUid, message: runnable.message }, null, 2));
+        }
+        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,
+        });
+    }
+    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));
+}
+/** New credentials + a reinstalled startup agent for a bot that IS already here. */
+async function repairLocalBot(name, api, bot, daemon) {
+    const dir = botDir(name);
+    const config = readBotConfig(dir);
+    let reissued;
+    try {
+        reissued = await api.reissueCredentials(bot.agentUid, { machineId: localMachineId(), reason: "reinstall" });
+    }
+    catch (err) {
+        throw credentialError(err, name);
+    }
+    writeBotCreds(dir, {
+        username: reissued.identity.cognitoUsername,
+        secret: reissued.identity.secret,
+        entityType: "agent",
+        entityUid: bot.agentUid,
+        clientId: DEFAULT_COGNITO.clientId,
+        region: DEFAULT_COGNITO.region,
+    });
+    createBotLogger(dir)("info", `re-issued machine credentials for ${name} (${bot.agentUid}) on ${localMachineId()}`);
+    if (daemon && process.platform === "darwin") {
+        installBotDaemon(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
+    }
+    return "new credentials, startup agent reinstalled";
+}
+/**
+ * `hq bot restore` — every local bot this account owns that is not set up on
+ * this computer comes back. This is what the desktop app and a post-install
+ * hook call after a reinstall or on a new Mac.
+ */
+export async function runBotRestore(opts) {
+    const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
+    const token = await ownerToken();
+    const api = new BotApi({ token: async () => token });
+    const bots = (await listMyBotsOrExplain(api, {
+        json: opts.json,
+        emptyResult: { dryRun: opts.dryRun === true, restored: 0, repaired: 0, skipped: 0, failed: 0, bots: [] },
+    }));
+    const rows = [];
+    for (const bot of bots) {
+        const name = localNameForRemoteBot(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" });
+            continue;
+        }
+        // A bot this computer cannot run is never brought back: it would get
+        // credentials, a folder and a startup agent, and then fail at every start.
+        // It is counted as skipped and says why, rather than being silently absent.
+        const runnable = remoteBotRunnability(bot, name);
+        if (!runnable.runnable) {
+            rows.push({
+                name,
+                agentUid: bot.agentUid,
+                action: opts.dryRun ? "would-skip" : "skipped",
+                reason: runnable.reason,
+                detail: runnable.message,
+            });
+            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) });
+            }
+            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("; "),
+                });
+            }
+        }
+        catch (err) {
+            rows.push({ name, agentUid: bot.agentUid, action: "failed", detail: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    const counted = (action) => rows.filter((r) => r.action === action).length;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: counted("failed") === 0,
+            dryRun: opts.dryRun === true,
+            restored: counted("restored") + counted("would-restore"),
+            repaired: counted("repaired") + counted("would-repair"),
+            skipped: counted("skipped") + counted("would-skip"),
+            failed: counted("failed"),
+            bots: rows,
+        }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(chalk.gray("You have no local bots in HQ. Create one with: hq bot create assistant"));
+        return;
+    }
+    for (const row of rows) {
+        const colour = row.action === "failed" ? chalk.red : row.action.startsWith("would") || row.action === "skipped" ? chalk.gray : chalk.green;
+        console.log(`${chalk.bold(row.name.padEnd(16))} ${colour(row.action.padEnd(14))} ${chalk.dim(row.detail)}`);
+    }
+    const summary = `${counted("restored") + counted("would-restore")} to bring back, ${counted("repaired") + counted("would-repair")} to repair, ${counted("skipped") + counted("would-skip")} already here, ${counted("failed")} failed`;
+    console.log(chalk.dim(opts.dryRun ? `\nDry run — nothing changed. ${summary}.` : `\n${summary}.`));
+    if (counted("failed") > 0) {
+        throw Object.assign(new Error(`Could not bring back ${counted("failed")} of your bots (see the list above).`), { expected: true });
+    }
+}
+/** The one clause the table shows instead of an adopt command it must not offer. */
+function notRunnableHint(reason) {
+    if (reason === "cloud-compute")
+        return "runs in the cloud, not on a computer";
+    if (reason === "company-bot")
+        return "a company bot: runs in HQ Cloud, not on this Mac";
+    return "not a bot this computer can run";
+}
+/** `hq bot list --remote` — the local bots this account owns, wherever they live. */
+async function runBotListRemote(opts) {
+    const token = await ownerToken();
+    const api = new BotApi({ token: async () => token });
+    const rows = (await listMyBotsOrExplain(api, { json: opts.json, emptyResult: { bots: [] } })).map((bot) => {
+        const name = localNameForRemoteBot(bot);
+        const runnable = remoteBotRunnability(bot);
+        return {
+            name: name ?? bot.name ?? bot.agentUid,
+            agentUid: bot.agentUid,
+            kind: bot.botKind ?? "personal",
+            online: bot.online === true,
+            lastHeartbeatAt: bot.lastHeartbeatAt ?? null,
+            here: name !== null && readBotConfig(botDir(name)) !== null,
+            settings: describeBotLocalConfig(parseBotLocalConfig(bot.localConfig)),
+            runnable: runnable.runnable,
+            reason: runnable.reason,
+        };
+    });
+    if (opts.json) {
+        // `ok` on success too: the failure document carries `ok: false`, and a
+        // consumer that learned to branch on it read a good listing as a failure.
+        console.log(JSON.stringify({ ok: true, bots: rows }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(chalk.gray("You have no local bots in HQ. Create one with: hq bot create assistant"));
+        return;
+    }
+    console.log(chalk.dim(`${"NAME".padEnd(16)} ${"AGENT".padEnd(26)} ${"KIND".padEnd(9)} ${"ONLINE".padEnd(8)} HERE`));
+    for (const row of rows) {
+        console.log(`${chalk.bold(row.name.padEnd(16))} ${row.agentUid.padEnd(26)} ${row.kind.padEnd(9)} ${row.online ? chalk.green("online".padEnd(8)) : chalk.gray("offline".padEnd(8))} ${row.here ? chalk.green("yes") : chalk.yellow("no")}${row.here ? "" : row.runnable ? chalk.dim(`  — hq bot adopt ${row.name}`) : chalk.dim(`  — ${notRunnableHint(row.reason)}`)}`);
+    }
+    if (rows.some((r) => !r.here && r.runnable))
+        console.log(chalk.dim(`\nBring them all back with: hq bot restore`));
+}
 // ── registration ─────────────────────────────────────────────────────────────
 export function registerBotCommand(program) {
     const bot = program
@@ -861,15 +1576,34 @@ export function registerBotCommand(program) {
     bot
         .command("list")
         .description("List local bots with runtime, online state, and pid")
+        .option("--remote", "List the local bots your HQ account owns instead, with a here column saying which are set up on this computer")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runBotList(opts))());
+    bot
+        .command("adopt <name>")
+        .description("Bring a bot you already own back to this computer: new machine credentials, its saved settings, worker folder, and startup agent")
+        .option("--runtime <runtime>", `Model CLI to run it with, overriding its saved one: ${BOT_RUNTIMES.join("|")}`)
+        .option("--model <model>", "Model override passed to the runtime CLI, replacing its saved one")
+        .option("--no-daemon", "Do not install the launchd agent (macOS)")
+        .option("--no-start", "Bring it back without starting it")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotAdopt(name, opts))());
+    bot
+        .command("restore")
+        .description("Bring back every local bot your HQ account owns that is not set up on this computer (after a reinstall, or on a new Mac)")
+        .option("--all", "Also re-issue credentials and reinstall the startup agent for the bots already set up here")
+        .option("--dry-run", "Show what would be brought back, change nothing")
+        .option("--no-daemon", "Do not install the launchd agents (macOS)")
+        .option("--no-start", "Bring them back without starting them")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runBotRestore(opts))());
     bot
         .command("start <name>")
         .description("Start the bot (via launchd when installed, else a detached process)")
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(async () => {
         const b = requireBot(name);
-        await startBot(b.name, b.dir, b.config, Boolean(opts.json));
+        await startBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
     })());
     bot
         .command("stop <name>")
@@ -886,7 +1620,7 @@ export function registerBotCommand(program) {
         .action((name, opts) => wrap(async () => {
         const b = requireBot(name);
         await stopBot(b.name, b.dir, b.config, "silent");
-        await startBot(b.name, b.dir, b.config, Boolean(opts.json));
+        await startBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
     })());
     bot
         .command("status <name>")
@@ -907,6 +1641,7 @@ export function registerBotCommand(program) {
         .command("rm <name>")
         .description("Stop the bot, remove its launchd agent, delete its cloud identity and local state")
         .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--remote", "When the bot's local settings are already gone, also delete the bot HQ still has under that name")
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(() => runBotRm(name, opts))());
     bot