@indigoai-us/hq-cli 5.174.0 → 5.176.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.176.0] — 2026-09-24
+
+### Fixed
+
+- `hq bot create setup` restores the account's existing setup bot when the local copy is missing.
+
+## [5.175.0] — 2026-09-24
+
+### Fixed
+
+- `hq agent kit` now shows missing external credentials at a home-relative path and reports the missing enrollment as an actionable precondition.
+- Missing external agent credentials show an actionable error without creating a Sentry fault.
+
 ## [5.174.0] — 2026-09-24
 
 ### Fixed

package/dist/commands/agent-kit.js

@@ -37,6 +37,8 @@ import { buildWakeNotice, clearWakeConfig, currentWakeState, DEFAULT_WAKE_RETRY_
 import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
 import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
 import { installServices, servicesStatus, uninstallServices, } from "../lib/service-manager/index.js";
+import { markExpectedUserError } from "../utils/expected-cli-error.js";
+import { scrubHomeDirectoryPrefix } from "../utils/install-tree-torn.js";
 export class KitError extends Error {
     constructor(message) {
         super(message);
@@ -47,8 +49,9 @@ export class KitError extends Error {
 export function requireExternalCreds(paths) {
     const creds = readExternalMachineCreds(paths);
     if (!creds) {
-        throw new KitError(`No external agent credentials at ${paths.machineCredsPath}. Run ` +
-            `\`hq agent enroll <code>\` first (an admin creates the code in the HQ console).`);
+        const credentialsPath = scrubHomeDirectoryPrefix(paths.machineCredsPath, paths.home);
+        throw markExpectedUserError(new KitError(`No external agent credentials at ${credentialsPath}. Run ` +
+            `\`hq agent enroll <code>\` first (an admin creates the code in the HQ console).`));
     }
     return creds;
 }

package/dist/commands/bot.d.ts

@@ -209,6 +209,7 @@ export declare function configFromLocalConfig(input: {
         runtime?: BotRuntimeId;
         model?: string;
     };
+    preserveFirstStart?: boolean;
     now?: () => Date;
 }): {
     config: BotConfig;

package/dist/commands/bot.js

@@ -481,9 +481,6 @@ export async function runBotCreate(nameArg, opts) {
     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;
-    if (name === RESERVED_SETUP_BOT_NAME && opts.worker?.trim() !== RESERVED_SETUP_BOT_NAME) {
-        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 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}.`), {
@@ -495,11 +492,84 @@ export async function runBotCreate(nameArg, opts) {
     // 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 });
+        }
+        if (matches.length === 0)
+            return false;
+        const remote = matches[0];
+        if (!isReservedSetupBotRecord(remote, owner))
+            return false;
+        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,
+            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.
@@ -549,6 +619,12 @@ export async function runBotCreate(nameArg, opts) {
             });
         }
         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.
@@ -1223,6 +1299,18 @@ export function matchRemoteBots(bots, wanted) {
         (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)
@@ -1392,8 +1480,10 @@ export function configFromLocalConfig(input) {
         enabled: true,
         // A restore is not a first start: the bot's one-off kickoff task already
         // ran on the machine it was created on, and `runs once` has to keep
-        // meaning once. `hq bot intro <name>` has it say hello again.
-        introSentAt: (input.now ?? (() => new Date()))().toISOString(),
+        // 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 };
 }
@@ -1440,6 +1530,7 @@ async function adoptRemoteBot(input) {
         dir,
         local,
         ...(input.overrides ? { overrides: input.overrides } : {}),
+        ...(input.preserveFirstStart ? { preserveFirstStart: true } : {}),
     });
     writeBotConfig(dir, config);
     const scaffoldOpts = { memoryDir: config.memoryDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.174.0",
+  "version": "5.176.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {