@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/bot.js

@@ -0,0 +1,1982 @@
+import { withLocalJobs } from "../lib/bot/local-jobs.js";
+import { OwnerContextCache, lookupOwnerContext } from "../lib/bot/owner-context.js";
+import { hasActivePromotion } from "../lib/bot/promotion-receipt.js";
+import { readInflightTurns } from "../lib/bot/inflight.js";
+import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hold.js";
+/**
+ * `hq bot` — personal local bots (local-bots US-003/US-004/US-005).
+ *
+ *   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 [--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]
+ *   hq bot run <name>                     (the resident process; launchd runs this)
+ *   hq bot daemon install|uninstall|status <name>
+ *   hq bot rm <name> [--yes]
+ *   hq bot intro <name>                   (re-send the introduction DM)
+ *   hq bot jobs <name> [--add "…" --every "…"] [--rm <jobId>] [--json]
+ *
+ * The bot's own identity (agt_) authenticates with 0600 machine creds under
+ * ~/.hq/bots/<name>/; the OWNER's cached session is used only for create,
+ * list (online flag), and rm. Secrets are never printed.
+ */
+import { promoteLocalBot } from "../lib/bot/promote.js";
+import { CLI_UPDATE_DISABLE_ENV, createCliUpdateWatcher, handOffToUpdatedCli } from "../lib/bot/cli-update.js";
+import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
+import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
+import { registerBotContinuityCommand } from "./bot-continuity.js";
+import { registerBotJobsCommand } from "./bot-jobs.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";
+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 { askDaemonToStart, askDaemonToStop, daemonOwnsProcess, daemonSupervises, daemonWillSupervise, handOffInstallHere, } from "../lib/daemon/handoff.js";
+import { daemonPaths } from "../lib/daemon/paths.js";
+import { launchdLabel } from "../lib/bot/paths.js";
+import { isAncestorProcess } from "../lib/bot/self-process.js";
+import { runtimeDisplayName } from "../lib/bot/runtime-sign-in.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";
+function collectRepeated(value, previous) {
+    return [...previous, value];
+}
+function fail(message) {
+    console.error(chalk.red(message));
+    process.exit(1);
+}
+function wrap(action) {
+    return async () => {
+        try {
+            await action();
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    };
+}
+/** Real launchctl; every failure is a non-ok result, never a throw. */
+export const defaultLaunchctl = (args) => {
+    try {
+        const stdout = execFileSync("launchctl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        return { ok: true, stdout, stderr: "" };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, stdout: String(e.stdout ?? ""), stderr: String(e.stderr ?? e.message ?? "") };
+    }
+};
+/** The desktop app creates HQ's setup bot under this name, always from the `setup` worker. */
+export const RESERVED_SETUP_BOT_NAME = "setup";
+function daemonDeps() {
+    return process.platform === "darwin" ? { launchctl: defaultLaunchctl } : {};
+}
+/** Install the bot's LaunchAgent, unless `hq daemon` runs local bots on this machine. */
+function installBotAgent(p) {
+    const handedOff = handOffInstallHere(["bots"]);
+    if (handedOff)
+        return { platform: detectBotPlatform(), action: "install", installed: true, loaded: true, message: handedOff };
+    return installBotDaemon(p, daemonDeps());
+}
+export function listBotNames(root) {
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && readBotConfig(path.join(root, d.name)) !== null)
+        .map((d) => d.name)
+        .sort();
+}
+function requireBot(name) {
+    const valid = validateBotName(name);
+    const dir = botDir(valid);
+    const config = readBotConfig(dir);
+    if (!config) {
+        // 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 };
+}
+/** Bot-identity token supplier: per-bot creds + per-bot token cache dir. */
+export function botTokenSupplier(dir) {
+    process.env.HQ_MACHINE_CREDS_FILE = botCredsPath(dir);
+    process.env.HQ_MACHINE_TOKEN_STATE_DIR = botTokenStateDir(dir);
+    return () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+}
+async function ownerToken(interactive = process.stdin.isTTY === true) {
+    if (peekHqApiKey()) {
+        throw Object.assign(new Error("hq bot needs your HQ login session (HQ_API_KEY is not supported here). Run `hq login`."), {
+            expected: true,
+        });
+    }
+    // Bots belong to a person, so `hq bot` always acts as the signed-in person,
+    // even when a bot runs it: a bot's own process exports its machine
+    // credentials, and a machine identity can own no bot ("No person entity
+    // found"), which left a setup bot unable to create its owner's first bot.
+    // Under the desktop app (no TTY) never open a browser login; the app owns
+    // sign-in and shares the same cached session file.
+    return ensureCognitoToken({ tokenSource: "person", interactive });
+}
+function rowFor(name, opts = {}) {
+    const dir = botDir(name);
+    const config = readBotConfig(dir);
+    const status = readBotStatus(dir);
+    const pid = status?.pid ?? null;
+    const processAlive = pid !== null && isPidAlive(pid) && status?.state === "running";
+    // Turns this bot has taken and not finished: what "thinking" means.
+    const inflightTurns = readInflightTurns(dir);
+    let daemonInstalled = false;
+    let daemonLoaded = false;
+    let daemonNodeMissing = null;
+    if (opts.withDaemon !== false) {
+        try {
+            const d = botDaemonStatus(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
+            daemonInstalled = d.installed;
+            daemonLoaded = d.loaded;
+            if (d.nodeProblem === "missing" && d.nodeBinary)
+                daemonNodeMissing = d.nodeBinary;
+        }
+        catch {
+            /* hq binary unresolvable in odd environments — daemon status unknown */
+        }
+    }
+    return {
+        name,
+        agentUid: config.agentUid,
+        ownerUid: config.ownerUid,
+        runtime: config.runtime,
+        model: config.model,
+        effort: effectiveBotEffort(config),
+        effortIsDefault: !config.effort,
+        state: processAlive ? "running" : status?.state === "failed" ? "failed" : "stopped",
+        pid: processAlive ? pid : null,
+        processAlive,
+        hosting: hasActivePromotion(dir, config.agentUid, config.ownerUid) ? "cloud" : "local",
+        promotionHold: promotionHoldSummary(dir, config.agentUid, config.ownerUid),
+        online: null,
+        lastHeartbeatAt: status?.lastHeartbeatAt ?? null,
+        lastHeartbeatOk: status?.lastHeartbeatOk ?? null,
+        lastInboxPollAt: status?.lastInboxPollAt ?? null,
+        lastInboxPollOk: status?.lastInboxPollOk ?? null,
+        busy: processAlive && inflightTurns.length > 0,
+        busySince: processAlive ? (inflightTurns[0]?.startedAt ?? null) : null,
+        runtimeSignIn: status?.runtimeSignIn ?? null,
+        daemonInstalled,
+        daemonLoaded,
+        daemonNodeMissing,
+        dir,
+        introSentAt: config.introSentAt,
+        kind: effectiveBotKind(config),
+        companies: effectiveBotCompanies(config),
+        workerSource: config.workerSource ?? "scaffold",
+        workerDir: config.workerDir,
+        ...(config.workerId ? { workerId: config.workerId } : {}),
+        ...(config.companySlug ? { companySlug: config.companySlug } : {}),
+        memory: botMemoryMode(config),
+        memoryDir: resolveBotMemoryDir(config),
+        ...(config.displayName ? { displayName: config.displayName } : {}),
+        ...(config.intro ? { intro: config.intro } : {}),
+        ...(config.kickoff ? { kickoff: config.kickoff } : {}),
+    };
+}
+async function decorateOnline(rows) {
+    if (rows.length === 0)
+        return;
+    let token;
+    try {
+        token = await ownerToken(false);
+    }
+    catch {
+        return;
+    }
+    const api = new BotApi({ token: async () => token });
+    await Promise.all(rows.map(async (row) => {
+        try {
+            const rec = await api.getAgent(row.agentUid);
+            row.online = rec.online === true;
+            row.lastHeartbeatAt = rec.runtime?.lastHeartbeat?.at ?? row.lastHeartbeatAt;
+        }
+        catch {
+            row.online = null;
+        }
+    }));
+}
+function humanOnline(row) {
+    if (row.lastHeartbeatOk === false)
+        return chalk.red("unreachable");
+    if (row.online === true)
+        return chalk.green("online");
+    if (row.online === false)
+        return chalk.gray("offline");
+    return chalk.gray("unknown");
+}
+/** Spawn `hq bot run <name>` detached (no launchd). */
+export function spawnDetachedRun(name, dir) {
+    const entry = process.argv[1] && fs.existsSync(process.argv[1]) ? process.argv[1] : resolveHqBinary();
+    fs.mkdirSync(path.dirname(botLogPath(dir)), { recursive: true, mode: 0o700 });
+    const fd = fs.openSync(botLogPath(dir), "a");
+    const child = spawn(process.execPath, [entry, "bot", "run", name], {
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", fd, fd],
+        env: { ...process.env, HQ_NO_UPDATE_CHECK: "1" },
+    });
+    fs.closeSync(fd);
+    child.unref();
+    if (!child.pid)
+        throw new Error("Unable to start the bot process");
+    return child.pid;
+}
+async function waitFor(pred, timeoutMs, stepMs = 250) {
+    const until = Date.now() + timeoutMs;
+    while (Date.now() < until) {
+        if (pred())
+            return true;
+        await new Promise((r) => setTimeout(r, stepMs));
+    }
+    return pred();
+}
+function stopProcess(dir) {
+    const status = readBotStatus(dir);
+    if (!status || !isPidAlive(status.pid))
+        return false;
+    try {
+        process.kill(status.pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `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)
+        patchBotConfig(dir, { enabled: true });
+    const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
+    const d = botDaemonStatus(paths, daemonDeps());
+    const hqDaemon = daemonPaths();
+    let how;
+    // A bot created since the daemon last read its plan is the daemon's too,
+    // unless its own LaunchAgent runs it.
+    if (daemonSupervises(hqDaemon, `bots:${name}`) || (!d.installed && daemonWillSupervise(hqDaemon, `bots:${name}`))) {
+        // `hq daemon` runs this bot; starting a copy here would run it twice.
+        const before = readBotStatus(dir);
+        if (before && isPidAlive(before.pid) && before.state === "running") {
+            how = `already running under hq daemon (pid ${before.pid})`;
+        }
+        else {
+            askDaemonToStart(hqDaemon, `bots:${name}`);
+            how = "started by hq daemon";
+        }
+    }
+    else if (d.installed && process.platform === "darwin") {
+        // A repair reloads the job; from inside one of the bot's own turns that
+        // bootout would kill the turn and this command with it.
+        const self = readBotStatus(dir);
+        if (!(self && isPidAlive(self.pid) && selfStopProbe(self.pid)))
+            repairBotDaemonIfStale(paths, daemonDeps());
+        const r = startBotDaemon(paths, daemonDeps());
+        how = r.message;
+    }
+    else {
+        const before = readBotStatus(dir);
+        if (before && isPidAlive(before.pid) && before.state === "running") {
+            how = `already running (pid ${before.pid})`;
+        }
+        else {
+            how = `started pid ${spawnDetachedRun(name, dir)}`;
+        }
+    }
+    const running = await waitFor(() => {
+        const s = readBotStatus(dir);
+        return !!s && s.state === "running" && isPidAlive(s.pid);
+    }, 15_000);
+    const status = readBotStatus(dir);
+    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 { running, how };
+    }
+    if (running)
+        console.log(chalk.green(`${name} is running`) + chalk.dim(` (${how})`));
+    else {
+        console.log(chalk.yellow(`${name} did not report running within 15s`) + chalk.dim(` (${how})`));
+        if (status?.lastError)
+            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
+ * when stop is a step inside rm/restart, whose own JSON must be the only
+ * document on stdout (the desktop app parses it; a second object made it
+ * "unreadable output: trailing characters").
+ */
+/** Seams for the self-stop path, replaced in tests. */
+export const botStopSeams = {
+    /** True when this process runs inside the bot process `botPid` (one of its turns). */
+    isInsideBot: (botPid) => isAncestorProcess(botPid),
+    /** Ask the bot to finish its running turns and exit 0 (the drain signal). */
+    signalDrain: (botPid) => {
+        try {
+            process.kill(botPid, "SIGUSR2");
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+function selfStopProbe(botPid) {
+    try {
+        return botStopSeams.isInsideBot(botPid);
+    }
+    catch {
+        return false;
+    }
+}
+function requestSelfStopDrain(botPid) {
+    return botStopSeams.signalDrain(botPid);
+}
+async function stopBot(name, dir, config, output) {
+    if (hasPromotionHold(dir))
+        throw new Error("This bot is held for cloud promotion. Continue its promotion before changing local settings or lifecycle.");
+    const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
+    const hqDaemon = daemonPaths();
+    const before = readBotStatus(dir);
+    const wasRunning = !!before && isPidAlive(before.pid);
+    const supervised = daemonSupervises(hqDaemon, `bots:${name}`);
+    // Stopping itself from inside one of its own turns: a bootout or a kill would
+    // take down this command and the turn with it, so the reply is lost and the
+    // job is left unloaded. Ask the bot to drain instead — finish the running
+    // turn (reply and ack included), then exit 0, which launchd's
+    // KeepAlive{SuccessfulExit:false} leaves down. `hq bot start` brings it back.
+    if (!supervised && wasRunning && selfStopProbe(before.pid)) {
+        const drained = requestSelfStopDrain(before.pid);
+        if (output === "silent")
+            return;
+        const how = drained ? "stops after this turn finishes" : "could not signal the bot";
+        if (output === "json") {
+            console.log(JSON.stringify({ ok: drained, name, signalled: drained, stopped: false, how, self: true }, null, 2));
+            return;
+        }
+        console.log(drained
+            ? chalk.green(`${name} will stop once this turn finishes`) + chalk.dim(` (stopping itself; start again with: hq bot start ${name})`)
+            : chalk.yellow(`${name} could not be asked to stop (pid ${before.pid})`));
+        return;
+    }
+    // Keep the daemon's copy down either way, so it does not start one as soon as this bot is gone.
+    if (supervised)
+        askDaemonToStop(hqDaemon, `bots:${name}`);
+    // A bot started before the daemon is not the daemon's child; stop it directly below.
+    if (supervised && (!wasRunning || daemonOwnsProcess(hqDaemon, `bots:${name}`, before.pid))) {
+        // The daemon stops it (escalating to SIGKILL itself) and keeps it down; a
+        // kill from here would look like a crash and be restarted.
+        const gone = await waitFor(() => {
+            const s = readBotStatus(dir);
+            return !s || !isPidAlive(s.pid);
+        }, 20_000);
+        if (output === "silent")
+            return;
+        if (output === "json") {
+            console.log(JSON.stringify({ ok: gone, name, signalled: wasRunning, stopped: gone, how: "stopped by hq daemon" }, null, 2));
+            return;
+        }
+        if (gone)
+            console.log(chalk.green(`${name} stopped`) + chalk.dim(" (by hq daemon)"));
+        else
+            console.log(chalk.yellow(`${name} did not stop within 20s`) + chalk.dim(` (logs: hq daemon logs bots:${name})`));
+        return;
+    }
+    if (process.platform === "darwin")
+        stopBotDaemon(paths, daemonDeps());
+    const signalled = stopProcess(dir);
+    const gone = await waitFor(() => {
+        const s = readBotStatus(dir);
+        return !s || !isPidAlive(s.pid);
+    }, 10_000);
+    if (!gone) {
+        const s = readBotStatus(dir);
+        if (s) {
+            try {
+                process.kill(s.pid, "SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (output === "silent")
+        return;
+    if (output === "json") {
+        console.log(JSON.stringify({ ok: true, name, signalled, stopped: gone }, null, 2));
+        return;
+    }
+    console.log(signalled || gone ? chalk.green(`${name} stopped`) : chalk.dim(`${name} was not running`));
+}
+// ── create ───────────────────────────────────────────────────────────────────
+/** "personal (acts as you)" / "company (acts as itself; member of a, b)". */
+function describeKind(kind, companies) {
+    return kind === "company"
+        ? `company (acts as itself; member of ${companies.length ? companies.join(", ") : "no company"})`
+        : "personal (acts as you)";
+}
+/**
+ * The kind a new bot gets, before anything is provisioned. Personal unless
+ * `--kind company` is given (the desktop app always passes --kind). A company
+ * bot needs at least one company: `--company`, or the company worker's own
+ * company when created from one. A personal bot takes no `--company`, and
+ * HQ's setup bot is always personal.
+ */
+export function resolveCreateKind(opts, worker) {
+    const given = opts.kind?.trim().toLowerCase();
+    if (given !== undefined && given !== "" && !isBotKind(given)) {
+        throw Object.assign(new Error(`--kind must be one of ${BOT_KINDS.join(", ")}`), { expected: true });
+    }
+    const requested = normalizeBotCompanies(opts.company);
+    const isSetup = worker?.id === SETUP_BOT_WORKER_ID;
+    const kind = isBotKind(given) ? given : "personal";
+    if (kind === "personal") {
+        if (requested.length > 0) {
+            throw Object.assign(new Error("--company only applies to a company bot (a personal bot acts as you, in every company you belong to). Add --kind company, or drop --company."), { expected: true });
+        }
+        return { kind, companies: [] };
+    }
+    if (isSetup) {
+        throw Object.assign(new Error("HQ's setup bot is always a personal bot; drop --kind company."), { expected: true });
+    }
+    const companies = requested.length > 0 ? requested : normalizeBotCompanies(worker?.company ? [worker.company] : []);
+    if (companies.length === 0) {
+        throw Object.assign(new Error("A company bot needs at least one company: add --company <slug> (repeat it for several), or create the bot from a company worker."), { expected: true });
+    }
+    return { kind, companies };
+}
+export async function runBotCreate(nameArg, opts) {
+    const name = validateBotName(nameArg);
+    const runtime = opts.runtime ?? "claude";
+    if (!isBotRuntimeId(runtime)) {
+        throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
+    }
+    const memoryMode = opts.memory ?? "synced";
+    if (!isBotMemoryMode(memoryMode)) {
+        throw Object.assign(new Error(`--memory must be one of ${BOT_MEMORY_MODES.join(", ")}`), { expected: true });
+    }
+    const intro = opts.intro !== undefined ? validateBotIntro(opts.intro) : undefined;
+    const displayName = opts.displayName !== undefined ? validateBotDisplayName(opts.displayName) : undefined;
+    const kickoff = opts.kickoff !== undefined ? validateBotKickoff(opts.kickoff) : undefined;
+    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)) {
+        throw Object.assign(new Error(`Bot "${name}" already exists (${dir}). Use hq bot start ${name} or hq bot rm ${name}.`), {
+            expected: true,
+        });
+    }
+    const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
+    // Resolve the company worker before provisioning anything (a typo must not
+    // cost an identity).
+    const worker = opts.worker?.trim() ? resolveBotWorker(hqRoot, opts.worker) : null;
+    const { kind, companies } = resolveCreateKind(opts, worker);
+    const isSetupBot = name === RESERVED_SETUP_BOT_NAME && kind === "personal" && worker?.id === SETUP_BOT_WORKER_ID;
+    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 token = await ownerToken();
+    const owner = await resolveCallerPersonUid(token);
+    if (!owner)
+        throw Object.assign(new Error("Your HQ login has no person entity yet; open the HQ desktop app once, then retry."), { expected: true });
+    const api = new BotApi({ token: async () => token });
+    const adoptOwnedSetupBot = async (allowUnsupportedListing) => {
+        let mine;
+        try {
+            mine = await api.listMine({ local: true });
+        }
+        catch (err) {
+            const failure = remoteBotsUnavailable(err);
+            if (allowUnsupportedListing && failure.reason === "server-unsupported")
+                return false;
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, ...failure }, null, 2));
+            throw Object.assign(new Error(failure.message), { expected: true });
+        }
+        const matches = matchRemoteBots(mine, name);
+        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 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 });
+        }
+        if (slugMatches.length === 0)
+            return false;
+        const remote = slugMatches[0];
+        if (!isReservedSetupBotRecord(remote, owner)) {
+            throw Object.assign(new Error(`HQ lists an agent with the setup slug "${setupSlug}", but its record does not identify it as your setup bot. The CLI cannot safely adopt it; check it with your HQ admin before retrying.`), { expected: true });
+        }
+        const { result, config } = await adoptRemoteBot({
+            bot: remote,
+            name,
+            api,
+            hqRoot,
+            overrides: { ...(model ? { model } : {}) },
+            daemon: opts.daemon !== false,
+            preserveFirstStart: true,
+        });
+        const recovered = {
+            agentUid: result.agentUid,
+            kind: effectiveBotKind(config),
+            companies: effectiveBotCompanies(config),
+            runtime: config.runtime,
+            dir: result.dir,
+            worker: config.workerSource === "worker" ? path.join(hqRoot, config.workerDir) : result.worker,
+            workerId: config.workerId ?? null,
+            companySlug: config.companySlug ?? null,
+            memory: botMemoryMode(config),
+            memoryDir: result.memoryDir,
+            displayName: config.displayName ?? null,
+            intro: config.intro ?? null,
+            kickoff: config.kickoff ?? null,
+            model: config.model ?? null,
+            effort: config.effort ?? DEFAULT_BOT_EFFORT,
+        };
+        if (!opts.json) {
+            console.log(chalk.green(`Created bot ${chalk.bold(name)}`) + chalk.dim(` (${result.agentUid}, ${result.runtime})`));
+            console.log(chalk.dim(`  kind:   ${describeKind(recovered.kind, recovered.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}`));
+        }
+        if (opts.start !== false) {
+            await startBot(name, result.dir, config, opts.json ? "json" : "text", { ...recovered, daemon: result.daemon });
+            return true;
+        }
+        if (opts.json)
+            console.log(JSON.stringify({ ok: true, name, ...recovered, daemon: result.daemon, running: false }, null, 2));
+        return true;
+    };
+    // HQ adds the owner suffix to the setup bot slug. If a create reached the
+    // server but its response was lost, recover the caller-owned bot instead
+    // of sending another create that the entity store will reject.
+    if (isSetupBot && (await adoptOwnedSetupBot(true)))
+        return;
+    // A company bot's companies are resolved first (a typo must not cost an
+    // identity) and sent with the create: the server makes the bot a member of
+    // each and refuses the whole create if the owner cannot add agents there.
+    const companyUids = [];
+    for (const slug of companies) {
+        try {
+            companyUids.push(await getCompanyUid(token, slug));
+        }
+        catch (err) {
+            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) } : {}),
+        ...(displayName ? { displayName } : {}),
+    });
+    let created;
+    try {
+        created = await api.createLocalBot({
+            // HQ shows the entity's name, so a display name goes there. The slug is
+            // pinned to the handle the way the server would derive it, so every
+            // slug-keyed lookup (the reserved setup bot, adopt, restore) is unchanged.
+            name: displayName ?? name,
+            ...(displayName ? { slug: `${name}-${owner.slice(-8).toLowerCase()}` } : {}),
+            kind,
+            ...(kind === "company" ? { companyUid: companyUids[0], companyMemberships: companyUids.slice(1) } : {}),
+            localConfig,
+        });
+    }
+    catch (err) {
+        if (err instanceof BotApiError && err.code === "COMPANY_BOT_CREATE_NOT_ALLOWED") {
+            throw Object.assign(new Error(`The server refused to create ${name}: ${err.message} Only an owner or admin of each company can create a company bot there.`), {
+                expected: true,
+            });
+        }
+        if (err instanceof BotApiError && err.code === "LOCAL_BOT_CAP_REACHED") {
+            // Only an older server still enforces a cap; current hq-pro-agents has none.
+            throw Object.assign(new Error("The server refused another bot (its bot limit is reached). Remove one with hq bot rm <name>, or update the server."), {
+                expected: true,
+            });
+        }
+        if (err instanceof BotApiError && err.status === 409) {
+            if (isSetupBot) {
+                if (await adoptOwnedSetupBot(false))
+                    return;
+                throw Object.assign(new Error(`HQ could not create the reserved ${name} bot. If you created it on another computer, bring it back with: ` +
+                    `hq bot adopt ${name}. Otherwise, choose a different name or ask your HQ admin.`), { expected: true });
+            }
+            // 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;
+    writeBotCreds(dir, {
+        username: created.identity.cognitoUsername,
+        secret: created.identity.secret,
+        entityType: "agent",
+        entityUid: agentUid,
+        clientId: DEFAULT_COGNITO.clientId,
+        region: DEFAULT_COGNITO.region,
+    });
+    const config = {
+        v: 1,
+        name,
+        agentUid,
+        ownerUid: created.agent.ownerUid ?? owner,
+        runtime,
+        kind,
+        // A company bot's list is filled in below, with the invites that went through.
+        ...(kind === "company" ? { companies: [] } : {}),
+        ...(model ? { model } : {}),
+        ...(effort ? { effort } : {}),
+        ...(opts.autoApprove === false ? { autoApprove: false } : {}),
+        hqRoot,
+        ...(worker
+            ? {
+                workerDir: worker.path,
+                workerSource: "worker",
+                workerId: worker.id,
+                ...(worker.company ? { companySlug: worker.company } : {}),
+            }
+            : { workerDir: botWorkerRelDir(name) }),
+        // "local" memory is an absolute path outside the synced HQ tree; "synced"
+        // memory is hqRoot-relative (and, for a worker-sourced bot, the bot's own
+        // personal/workers/<name>/memory so the shared company tree is never
+        // written to).
+        ...(memoryMode === "local"
+            ? { memoryDir: botLocalMemoryDir(dir) }
+            : worker
+                ? { memoryDir: path.join(botWorkerRelDir(name), "memory") }
+                : {}),
+        ...(displayName ? { displayName } : {}),
+        ...(intro ? { intro } : {}),
+        ...(kickoff ? { kickoff } : {}),
+        createdAt: new Date().toISOString(),
+        enabled: true,
+    };
+    writeBotConfig(dir, config);
+    // A company bot acts as itself, so it must be a member of each of its
+    // companies. Only the companies it actually joined are recorded, so after a failed invite the identity
+    // and bot.json stay on disk and `hq bot companies <name> --add <slug>`
+    // retries exactly the missing ones (or `hq bot rm <name>` undoes it all).
+    if (kind === "company") {
+        // The server already made it a member of the companies it reports back;
+        // only the rest (an older server reports none) are invited here.
+        const joined = new Set(created.agent.companyMemberships ?? []);
+        const already = companies.filter((_, i) => joined.has(companyUids[i]));
+        const missing = companies.filter((_, i) => !joined.has(companyUids[i]));
+        const outcome = await addBotToCompanies({ agentUid, companies: missing, token });
+        config.companies = [...already, ...outcome.done];
+        writeBotConfig(dir, config);
+        if (outcome.failed.length > 0) {
+            createBotLogger(dir)("error", `created ${name} (${agentUid}) but could not add it to: ${describeCompanyFailures(outcome.failed)}`);
+            throw Object.assign(new Error(`Created the bot identity ${agentUid} but could not add it to ${outcome.failed.length === 1 ? "a company" : `${outcome.failed.length} companies`}: ${describeCompanyFailures(outcome.failed)}. ` +
+                `Fix the cause and run \`hq bot companies ${name} --add ${outcome.failed.map((f) => f.slug).join(" --add ")}\`, or remove the bot with \`hq bot rm ${name}\`.`), { expected: true });
+        }
+    }
+    // A worker-sourced bot never writes into the company tree: only its own
+    // memory folder is scaffolded.
+    const scaffoldOpts = { memoryDir: config.memoryDir };
+    const scaffold = worker
+        ? scaffoldBotMemory(hqRoot, name, undefined, scaffoldOpts)
+        : 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_ = {
+        agentUid,
+        kind,
+        companies,
+        runtime,
+        dir,
+        worker: worker ? path.join(hqRoot, worker.path) : scaffold.dir,
+        workerId: worker?.id ?? null,
+        companySlug: worker?.company ?? null,
+        memory: memoryMode,
+        memoryDir: scaffold.memoryDir,
+        displayName: displayName ?? null,
+        intro: intro ?? null,
+        kickoff: kickoff ?? null,
+        model: model ?? null,
+        effort: effort ?? DEFAULT_BOT_EFFORT,
+    };
+    let daemonMessage = null;
+    if (opts.daemon !== false && process.platform === "darwin") {
+        const r = installBotAgent(buildBotDaemonPaths({ name, botDir: dir, hqRoot }));
+        daemonMessage = r.message;
+    }
+    if (!opts.json) {
+        console.log(chalk.green(`Created bot ${chalk.bold(name)}`) + chalk.dim(` (${agentUid}, ${runtime})`));
+        console.log(chalk.dim(`  kind:   ${describeKind(kind, companies)}`));
+        if (worker)
+            console.log(chalk.dim(`  worker: ${worker.id}${worker.company ? ` (${worker.company})` : ""} — ${path.join(hqRoot, worker.path)}`));
+        if (!worker)
+            console.log(chalk.dim(`  worker: ${scaffold.dir}`));
+        console.log(chalk.dim(`  memory: ${scaffold.memoryDir} (${memoryMode})`));
+        console.log(chalk.dim(`  state:  ${dir}`));
+        if (daemonMessage)
+            console.log(chalk.dim(`  ${daemonMessage}`));
+    }
+    if (opts.start !== false) {
+        if (daemonMessage && /loaded\)/.test(daemonMessage)) {
+            // RunAtLoad already started it.
+            const running = await waitFor(() => readBotStatus(dir)?.state === "running", 20_000);
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, name, ...created_, daemon: daemonMessage, running }, null, 2));
+            }
+            else if (running)
+                console.log(chalk.green(`${name} is online — it will DM you an introduction shortly.`));
+            else
+                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 });
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, name, ...created_, daemon: daemonMessage, running: false }, null, 2));
+    }
+}
+// ── companies ────────────────────────────────────────────────────────────────
+export async function runBotCompanies(nameArg, opts) {
+    const { name, dir, config } = requireBot(nameArg);
+    const kind = effectiveBotKind(config);
+    const add = normalizeBotCompanies(opts.add);
+    const remove = normalizeBotCompanies(opts.remove);
+    if (kind !== "company") {
+        throw Object.assign(new Error(`${name} is a personal bot: it acts as you, in every company you belong to, so it has no company list of its own. Create a company bot with: hq bot create <name> --kind company --company <slug>`), { expected: true });
+    }
+    const current = effectiveBotCompanies(config);
+    const both = add.filter((c) => remove.includes(c));
+    if (both.length > 0) {
+        throw Object.assign(new Error(`--add and --remove name the same company: ${both.join(", ")}`), { expected: true });
+    }
+    const toAdd = add.filter((c) => !current.includes(c));
+    const toRemove = remove.filter((c) => current.includes(c));
+    const unknown = remove.filter((c) => !current.includes(c));
+    if (unknown.length > 0) {
+        throw Object.assign(new Error(`${name} is not in ${unknown.join(", ")} (its companies: ${current.join(", ") || "none"}).`), { expected: true });
+    }
+    const next = [...current.filter((c) => !toRemove.includes(c)), ...toAdd];
+    if (next.length === 0) {
+        throw Object.assign(new Error(`A company bot needs at least one company; ${name} would be left with none. Remove the bot instead with: hq bot rm ${name}`), { expected: true });
+    }
+    const failed = [];
+    let added = [];
+    let removed = [];
+    if (toAdd.length > 0 || toRemove.length > 0) {
+        const token = await ownerToken();
+        if (toAdd.length > 0) {
+            const r = await addBotToCompanies({ agentUid: config.agentUid, companies: toAdd, token });
+            added = r.done;
+            failed.push(...r.failed);
+        }
+        if (toRemove.length > 0) {
+            const r = await removeBotFromCompanies({ agentUid: config.agentUid, companies: toRemove, token });
+            removed = r.done;
+            failed.push(...r.failed);
+        }
+    }
+    const companies = [...current.filter((c) => !removed.includes(c)), ...added];
+    if (added.length > 0 || removed.length > 0)
+        patchBotConfig(dir, { kind: "company", companies });
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: failed.length === 0, name, kind, companies, added, removed, failed }, null, 2));
+    }
+    else {
+        console.log(`${chalk.bold(name)}  company bot, member of: ${companies.join(", ")}`);
+        if (added.length > 0)
+            console.log(chalk.green(`  added:   ${added.join(", ")}`));
+        if (removed.length > 0)
+            console.log(chalk.green(`  removed: ${removed.join(", ")}`));
+        if (companies.length > 0 && (added.length > 0 || removed.length > 0)) {
+            console.log(chalk.dim(`  restart the bot so its instructions pick this up: hq bot restart ${name}`));
+        }
+    }
+    if (failed.length > 0) {
+        throw Object.assign(new Error(`Could not change ${name}'s membership in: ${describeCompanyFailures(failed)}`), { expected: true });
+    }
+}
+// ── workers ──────────────────────────────────────────────────────────────────
+export async function runBotWorkers(opts) {
+    const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
+    const workers = listBotWorkerOptions(hqRoot);
+    if (opts.json) {
+        console.log(JSON.stringify({ workers }, null, 2));
+        return;
+    }
+    if (workers.length === 0) {
+        console.log(chalk.gray("No workers in this HQ (a worker needs a worker.yaml under companies/<co>/workers/<id>/ or core/workers/)."));
+        return;
+    }
+    for (const w of workers) {
+        console.log(`${chalk.bold(w.id.padEnd(28))} ${(w.company ?? (w.source === "core" ? "core" : "-")).padEnd(14)} ${w.type.padEnd(12)} ${chalk.dim(w.summary.slice(0, 80))}`);
+    }
+    console.log(chalk.dim(`\nCreate a bot from one: hq bot create <name> --worker <id>`));
+}
+// ── run (resident) ───────────────────────────────────────────────────────────
+async function runBotResident(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;
+    }
+    if (healNodePathFromJob(name, dir, config))
+        return;
+    const token = botTokenSupplier(dir);
+    // The bot's own schedule lives in its folder and fires from this loop.
+    const api = withLocalJobs(new BotApi({ token }), 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(),
+        // Chat attachments are fetched with the bot's own machine identity against
+        // the same API its inbox and posts use (BotApi has no baseUrl override either).
+        downloadAttachment: createVaultObjectDownloader({ getToken: token }),
+        // Reload onto an updated hq-cli: the watched path is the script this
+        // process was launched with, which is what its supervisor launches next.
+        ...(process.env[CLI_UPDATE_DISABLE_ENV] === "1"
+            ? {}
+            : { cliUpdate: createCliUpdateWatcher({ dir, entry: process.argv[1] ?? null }) }),
+        onCliUpdateRestart: (_update, log) => {
+            handOffToUpdatedCli(name, log, { spawnReplacement: () => spawnDetachedRun(name, dir) });
+        },
+    });
+    await handle.done;
+    void name;
+}
+/**
+ * When this run IS the bot's launchd job and its plist names node by a
+ * versioned path (/opt/homebrew/Cellar/node/<v>/bin/node, removed by the next
+ * `brew upgrade node`), rewrite it to the stable alias and reload the job from
+ * a detached shell. Returns true when the caller should exit now (0, so
+ * KeepAlive leaves it alone) and let the reloaded job take over.
+ */
+function healNodePathFromJob(name, dir, config) {
+    // Only the job's own main process (launchd, pid 1, is its parent): a copy
+    // spawned by the bot inherits XPC_SERVICE_NAME but is not the job.
+    if (process.platform !== "darwin" || process.env.XPC_SERVICE_NAME !== launchdLabel(name) || process.ppid !== 1)
+        return false;
+    try {
+        const healed = healBotDaemonNodeFromJob(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
+        if (!healed)
+            return false;
+        createBotLogger(dir)("info", `startup agent ran node from ${healed.from}, which the next node upgrade removes; rewrote it to ${healed.to} and reloading`);
+        return true;
+    }
+    catch (err) {
+        createBotLogger(dir)("warn", `could not rewrite the startup agent's node path: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+// ── 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) {
+        console.log(JSON.stringify({ bots: rows }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(chalk.gray("No local bots yet. Create one with: hq bot create assistant"));
+        return;
+    }
+    for (const r of rows) {
+        console.log(`${chalk.bold(r.name.padEnd(16))} ${r.agentUid}  ${r.runtime.padEnd(6)}  ${humanOnline(r).padEnd(8)}  ${r.processAlive ? chalk.green(`pid ${r.pid}`) : chalk.gray(r.state)}${chalk.dim(`  ${r.kind === "company" ? `company bot: ${r.companies.join(", ") || "no company"}` : "personal"}`)}${r.daemonInstalled ? chalk.dim("  launchd") : ""}${r.daemonNodeMissing ? chalk.red(`  node missing (hq bot start ${r.name})`) : ""}${r.workerId ? chalk.dim(`  worker ${r.workerId}${r.companySlug ? ` (${r.companySlug})` : ""}`) : ""}`);
+    }
+}
+async function runBotStatus(nameArg, opts) {
+    const { name, dir } = requireBot(nameArg);
+    const row = rowFor(name);
+    await decorateOnline([row]);
+    const status = readBotStatus(dir);
+    const creds = readBotCredsIdentity(dir);
+    if (opts.json) {
+        console.log(JSON.stringify({ ...row, credsPresent: !!creds, status }, null, 2));
+        return;
+    }
+    console.log(`${chalk.bold(name)}  ${row.agentUid}`);
+    console.log(`  kind:       ${describeKind(row.kind, row.companies)}`);
+    console.log(`  runtime:    ${row.runtime}  model ${row.model ?? "default"}  thinking ${row.effort}${row.effortIsDefault ? " (default)" : ""}`);
+    if (row.workerId)
+        console.log(`  worker:     ${row.workerId}${row.companySlug ? ` (company ${row.companySlug})` : ""}  ${chalk.dim(row.workerDir)}`);
+    console.log(`  memory:     ${row.memory}  ${chalk.dim(row.memoryDir)}`);
+    console.log(`  process:    ${row.processAlive ? chalk.green(`running (pid ${row.pid})`) : chalk.gray(row.state)}`);
+    console.log(`  HQ online:  ${humanOnline(row)}${row.lastHeartbeatAt ? chalk.dim(`  last heartbeat ${row.lastHeartbeatAt}`) : ""}${row.lastHeartbeatOk === false && status?.lastHeartbeatError ? chalk.dim(`  (${status.lastHeartbeatError})`) : ""}`);
+    if (status?.lastInboxPollOk === false) {
+        console.log(`  inbox:      ${chalk.red("cannot receive")}${status.lastInboxError ? chalk.dim(`  ${status.lastInboxError}`) : ""}`);
+    }
+    else if (status?.lastInboxPollAt) {
+        console.log(`  inbox:      last poll ${status.lastInboxPollAt}`);
+    }
+    console.log(`  answering:  ${row.busy ? chalk.green(`yes${row.busySince ? `, since ${row.busySince}` : ""}`) : chalk.gray("no")}`);
+    console.log(`  launchd:    ${row.daemonInstalled ? (row.daemonLoaded ? "installed, loaded" : "installed, not loaded") : "not installed"}`);
+    if (row.daemonNodeMissing) {
+        console.log(`  ${chalk.red(`node missing: ${row.daemonNodeMissing}`)} — launchd cannot start ${name}; fix with: hq bot start ${name}`);
+    }
+    console.log(`  creds:      ${creds ? `present for ${creds.entityUid}` : chalk.red("missing")}`);
+    if (status) {
+        console.log(`  started:    ${status.startedAt}   restarts: ${status.restarts}   replies: ${status.repliesSent}`);
+        if (status.cliVersion)
+            console.log(`  hq-cli:     ${status.cliVersion}`);
+        if (status.runtimeSignIn?.state === "expired") {
+            const tool = runtimeDisplayName(status.runtimeSignIn.runtime);
+            console.log(`  ${chalk.yellow(`${tool} needs to sign in again`)} — sign in from HQ, or run \`${status.runtimeSignIn.runtime} ${status.runtimeSignIn.runtime === "claude" ? "auth login" : "login"}\`, then \`hq bot restart ${name}\``);
+        }
+        if (status.lastError)
+            console.log(`  last error: ${chalk.yellow(status.lastError)}`);
+    }
+    console.log(chalk.dim(`  state dir:  ${dir}`));
+}
+async function runBotLogs(nameArg, opts) {
+    const { dir } = requireBot(nameArg);
+    const file = botLogPath(dir);
+    const n = Math.max(1, Number.parseInt(opts.lines ?? "50", 10) || 50);
+    if (!fs.existsSync(file)) {
+        console.log(chalk.gray("No log yet."));
+        return;
+    }
+    const initial = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    for (const line of initial.slice(-n))
+        console.log(line);
+    if (!opts.follow)
+        return;
+    let size = fs.statSync(file).size;
+    await new Promise(() => {
+        fs.watchFile(file, { interval: 500 }, (curr) => {
+            if (curr.size < size)
+                size = 0;
+            if (curr.size > size) {
+                const fd = fs.openSync(file, "r");
+                const buf = Buffer.alloc(curr.size - size);
+                fs.readSync(fd, buf, 0, buf.length, size);
+                fs.closeSync(fd);
+                process.stdout.write(buf.toString());
+                size = curr.size;
+            }
+        });
+    });
+}
+// ── rm ───────────────────────────────────────────────────────────────────────
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/**
+ * `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.");
+    if (!opts.yes) {
+        const ok = await confirm(`Remove bot "${name}" (${config.agentUid}), its identity, and its local state? [y/N] `);
+        if (!ok) {
+            console.log(chalk.dim("Cancelled."));
+            return;
+        }
+    }
+    await stopBot(name, dir, config, "silent").catch(() => { });
+    const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
+    const daemon = uninstallBotDaemon(paths, daemonDeps());
+    const token = await ownerToken();
+    const api = new BotApi({ token: async () => token });
+    let identity;
+    try {
+        identity = await api.deleteLocalBot(config.agentUid);
+    }
+    catch (err) {
+        if (err instanceof BotApiError && err.status === 404)
+            identity = { alreadyGone: true };
+        else
+            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);
+    // 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,
+            ...(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) {
+        console.log(chalk.yellow(`  could not remove ${name} from ${f.slug}: ${f.reason}`) + chalk.dim(` — remove it by hand: hq members --company ${f.slug} revoke ${config.agentUid}`));
+    }
+    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;
+    }
+    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
+ * 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, 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.effort !== undefined) {
+        const effort = validateBotEffort(config.runtime, opts.effort);
+        if (effort)
+            next.effort = effort;
+        else
+            delete next.effort;
+    }
+    writeBotConfig(dir, next);
+    createBotLogger(dir)("info", `settings: model=${next.model ?? "default"} effort=${effectiveBotEffort(next)}${next.effort ? "" : " (default)"}`);
+    const result = {
+        ok: true,
+        name,
+        runtime: config.runtime,
+        model: next.model ?? null,
+        effort: effectiveBotEffort(next),
+        effortIsDefault: !next.effort,
+        effortLevels: BOT_EFFORT_LEVELS[config.runtime],
+    };
+    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).`));
+}
+async function runBotIntro(nameArg) {
+    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.");
+    const api = new BotApi({ token: botTokenSupplier(dir) });
+    await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }) });
+    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);
+}
+/** A name match alone does not prove that a remote record is HQ's setup bot. */
+function isReservedSetupBotRecord(bot, ownerUid) {
+    const owner = ownerUid.trim();
+    const local = parseBotLocalConfig(bot.localConfig);
+    return (!!owner &&
+        bot.ownerUid === owner &&
+        bot.slug === `${RESERVED_SETUP_BOT_NAME}-${owner.slice(-8).toLowerCase()}` &&
+        bot.botKind === "personal" &&
+        bot.computeMode === "local" &&
+        local?.workerSource === "worker" &&
+        local.workerId === SETUP_BOT_WORKER_ID);
+}
+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?.displayName ? { displayName: local.displayName } : {}),
+        ...(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. Recovery after a create response was lost is different:
+        // this machine has not started the bot yet, so its first intro/kickoff
+        // must still run.
+        ...(input.preserveFirstStart ? {} : { 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 } : {}),
+        ...(input.preserveFirstStart ? { preserveFirstStart: true } : {}),
+    });
+    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 = installBotAgent(buildBotDaemonPaths({ name, botDir: dir, hqRoot: input.hqRoot })).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") {
+        installBotAgent(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }));
+    }
+    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
+        .command("bot")
+        .description("Personal local bots that run on this computer with your own model login");
+    registerBotContinuityCommand(bot);
+    registerBotJobsCommand(bot, { requireBot, botTokenSupplier });
+    bot.command("promote <name>")
+        .description("Move this local bot to cloud compute, preserving its identity and private context")
+        .requiredOption("--company <uid>", "Destination company identity")
+        .option("--json", "Print promotion progress as JSON")
+        .action((name, opts) => wrap(async () => {
+        const { dir, config } = requireBot(name);
+        const token = await ownerToken(false);
+        const api = new BotApi({ token: async () => token });
+        const result = await promoteLocalBot({ dir, config, companyUid: opts.company, api });
+        const details = result.pending ? await api.promotionDetails(config.agentUid, opts.company) : null;
+        if (opts.json)
+            console.log(JSON.stringify({ ...result, pairing: details?.pairing ?? null, ...(details?.failure ? { failure: details.failure } : {}) }));
+        else if (details?.failure)
+            console.log(`${name}: ${details.failure}`);
+        else if (details?.pairing)
+            console.log(`${name}: connect the cloud bot to your ChatGPT subscription at ${details.pairing.url}, using code ${details.pairing.code}. Then run the same command to continue.`);
+        else
+            console.log(`${name}: ${result.promotion.phase}.${result.pending ? " Run the same command to continue promotion." : ""}`);
+    })());
+    bot
+        .command("create <name>")
+        .description("Provision a local bot identity, scaffold its worker folder, install its launchd agent, and start it")
+        .option("--kind <kind>", `personal (acts as you, everywhere you are) or company (acts as itself, as a member of its companies). Default: personal, or company when created from a company worker`)
+        .option("--company <slug>", "Company bots: a company the bot is a member of (repeat for several); the owner invites it on creation", collectRepeated, [])
+        .option("--runtime <runtime>", `Model CLI to run the bot with: ${BOT_RUNTIMES.join("|")}`, "claude")
+        .option("--model <model>", "Model override passed to the runtime CLI")
+        .option("--effort <level>", `Thinking level: claude ${BOT_EFFORT_LEVELS.claude.join("|")}; codex ${BOT_EFFORT_LEVELS.codex.join("|")}; grok ${BOT_EFFORT_LEVELS.grok.join("|")} (default ${DEFAULT_BOT_EFFORT})`)
+        .option("--no-auto-approve", "Keep the runtime's permission gates (default: everything pre-approved; a headless bot cannot answer prompts)")
+        .option("--worker <workerId>", "Run an existing company or core worker (see hq bot workers): its instructions, skills, context, and company policies; a company worker binds the bot to that company on every turn")
+        .option("--display-name <name>", `The human name people see for the bot in HQ (e.g. Maya; up to ${BOT_DISPLAY_NAME_MAX_CHARS} chars). The handle stays <name>`)
+        .option("--intro <text>", `The hello the bot DMs you when it first comes online (verbatim, up to ${BOT_INTRO_MAX_CHARS} chars)`)
+        .option("--kickoff <prompt>", `A first task the bot starts on by itself right after its hello: one model turn run as if you had sent it, answered in your DM, once (up to ${BOT_KICKOFF_MAX_CHARS} chars)`)
+        .option("--memory <where>", "Where the bot keeps its memory: synced (personal/workers/<name>/memory in HQ) or local (~/.hq/bots/<name>/memory, this computer only)", "synced")
+        .option("--no-daemon", "Do not install the launchd agent (macOS)")
+        .option("--no-start", "Create without starting")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotCreate(name, opts))());
+    bot
+        .command("companies <name>")
+        .description("Show or change which companies a company bot is a member of (you invite or remove it; a personal bot has no list of its own)")
+        .option("--add <slug>", "Add the bot to this company (repeatable)", collectRepeated, [])
+        .option("--remove <slug>", "Remove the bot from this company (repeatable)", collectRepeated, [])
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotCompanies(name, opts))());
+    bot
+        .command("workers")
+        .description("List the workers (templates) a bot can be created from (hq bot create <name> --worker <id>)")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runBotWorkers(opts))());
+    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, opts.json ? "json" : "text");
+    })());
+    bot
+        .command("stop <name>")
+        .description("Stop the bot process (it starts again at next login while its launchd agent is installed)")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(async () => {
+        const b = requireBot(name);
+        await stopBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
+    })());
+    bot
+        .command("restart <name>")
+        .description("Stop then start the bot")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(async () => {
+        const b = requireBot(name);
+        const running = readBotStatus(b.dir);
+        if (running && isPidAlive(running.pid) && selfStopProbe(running.pid)) {
+            // The stop half would end this turn (and this command) before the
+            // start half ran, leaving the bot down. Say so instead.
+            throw new Error(`${b.name} cannot restart itself from inside one of its own turns: the stop would end this turn before the start ran. Run \`hq bot restart ${b.name}\` from outside the bot, or \`hq bot stop ${b.name}\` to stop it after this turn.`);
+        }
+        await stopBot(b.name, b.dir, b.config, "silent");
+        await startBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
+    })());
+    bot
+        .command("status <name>")
+        .description("Show the bot's process, heartbeat, launchd, and credential state")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotStatus(name, opts))());
+    bot
+        .command("logs <name>")
+        .description("Show the bot's log")
+        .option("-f, --follow", "Keep printing new lines")
+        .option("-n, --lines <n>", "Number of trailing lines", "50")
+        .action((name, opts) => wrap(() => runBotLogs(name, opts))());
+    bot
+        .command("run <name>")
+        .description("Run the bot in the foreground (this is what launchd runs)")
+        .action((name) => wrap(() => runBotResident(name))());
+    bot
+        .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
+        .command("set <name>")
+        .description("Change the model and thinking level a bot uses (applies from its next message)")
+        .option("--model <model>", "Model id for the runtime CLI, or default for the CLI's own default")
+        .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))());
+    bot
+        .command("intro <name>")
+        .description("Have the bot re-send its introduction DM to you")
+        .action((name) => wrap(() => runBotIntro(name))());
+    const daemon = bot.command("daemon").description("Manage the bot's launchd user agent (macOS)");
+    daemon
+        .command("install <name>")
+        .description("Install and load the LaunchAgent so the bot starts at login and restarts on crash")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(async () => {
+        const b = requireBot(name);
+        const r = installBotAgent(buildBotDaemonPaths({ name: b.name, botDir: b.dir, hqRoot: b.config.hqRoot }));
+        console.log(opts.json ? JSON.stringify({ ok: r.installed, ...r }, null, 2) : r.message);
+    })());
+    daemon
+        .command("uninstall <name>")
+        .description("Unload and remove the LaunchAgent")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(async () => {
+        const b = requireBot(name);
+        const r = uninstallBotDaemon(buildBotDaemonPaths({ name: b.name, botDir: b.dir, hqRoot: b.config.hqRoot }), daemonDeps());
+        console.log(opts.json ? JSON.stringify({ ok: true, ...r }, null, 2) : r.message);
+    })());
+    daemon
+        .command("status <name>")
+        .description("Show whether the LaunchAgent is installed and loaded")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(async () => {
+        const b = requireBot(name);
+        const r = botDaemonStatus(buildBotDaemonPaths({ name: b.name, botDir: b.dir, hqRoot: b.config.hqRoot }), daemonDeps());
+        console.log(opts.json ? JSON.stringify({ ok: true, ...r }, null, 2) : r.message);
+    })());
+}
+//# sourceMappingURL=bot.js.map