@indigoai-us/hq-cli 5.116.0 → 5.117.0

package/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 ## [Unreleased]
 
+## [5.117.0] — 2026-09-16
+
+### Added
+
+- Your local bots can come back after a reinstall. A bot is an identity HQ
+  keeps for you plus the state that runs it on one computer; wiping that
+  computer's HQ folder, or moving to a new Mac, used to leave every bot dead
+  with no way back — making a new one was refused, because the old one still
+  existed. Now `hq bot restore` brings back every bot you own that is missing
+  from this computer, with its own settings, memory folder and startup agent,
+  keeping the same identity and the same conversation. `hq bot adopt <name>`
+  does one bot, `hq bot list --remote` shows every bot you own and which of
+  them are set up here, and trying to create a bot you already own now says so
+  and points at adopting it instead. Bots made before this shipped come back on
+  sensible defaults, and HQ tells you it did that.
+
+### Fixed
+
+- `hq bot restore` no longer brings back a bot this Mac cannot run. A company
+  bot — one that acts for a company rather than as you — was being set up here
+  as a personal bot: it got credentials, a folder, a memory folder and a startup
+  entry, was counted as restored with nothing reported as failed, and then died
+  at every start and at every login, while the Mac offered "check that Claude
+  Code is signed in" as the remedy, which could never help. Restore, `hq bot
+  adopt` and `hq bot list --remote` now ask exactly the question the bot's own
+  startup asks, before anything is written or any password is rotated. A bot
+  that cannot run here is listed plainly, counted as skipped rather than
+  restored, and refused by adopt with one sentence saying where it does run —
+  and nothing is left behind on this computer.
+- Bringing a bot back no longer leaves a second copy of it. A bot you created
+  here as `qa-x` is `qa-x-<your suffix>` in HQ, and bringing it back built a
+  whole second folder under that longer name: a second startup entry, a second
+  memory folder, and the original folder left behind holding the live password
+  of a bot nothing could reach any more. HQ now recognises the folder a bot
+  already has on this computer — by the identity inside it, even when a wipe
+  left only its credentials — and repairs that one in place. A bot that is not
+  here at all comes back under the name you created it with. If that name
+  already belongs to a different bot, both are kept, under names that tell them
+  apart.
+- `hq bot list --remote --json` now says `ok: true` when it worked. Every
+  failure said `ok: false`, and the success document had no `ok` at all, so
+  anything that learned to check it read a good listing as a failure.
+- A bot's long answer now reaches you, in several messages. HQ Cloud refuses any
+  single message over 4000 characters, and nothing split one up: an answer over
+  that length was refused, saved, and sent again unchanged on every check — a
+  test machine recorded the same rejection 231 times in eight minutes while the
+  person saw no reply and no error at all, and the bot's 44 seconds of work was
+  thrown away. A reply that is too long is now cut into numbered parts — on
+  paragraph breaks where it can, on sentences otherwise, and never leaving a
+  block of code half-open — and posted in order. If something goes wrong partway
+  through, only the parts you have not seen are sent again. And if a message
+  truly cannot be delivered, the bot stops after five tries and tells you so in
+  one short line, instead of asking the server to do the impossible for as long
+  as it runs.
+- A bot's startup entry no longer outlives the bot. When a bot's local setup was
+  gone, the startup entry macOS keeps for it relaunched it every five seconds,
+  forever, filling its log with the same failure (one test machine recorded 267
+  of them in a row). HQ now says once what happened, tells you how to bring the
+  bot back, removes the startup entry it no longer needs, and stops cleanly so
+  nothing relaunches it. This works when macOS itself is the one running the
+  bot, which is the case that matters: the first version did its tidying in an
+  order that had macOS shut the bot down before it could finish, so the startup
+  entry survived and brought the same dead bot back at every login, and the
+  explanation never reached the bot's log. HQ now writes the explanation and
+  removes the entry first, and lets go of itself last.
+
+- You can remove a bot whose settings this computer has already lost. A wiped
+  HQ folder could leave a bot half-here — a folder and a startup entry, no
+  settings — and nothing could clear it: removing it said there was no such
+  bot and suggested creating one, and creating one said you already had it.
+  `hq bot rm <name>` now clears whatever is actually left on this computer, and
+  `hq bot rm <name> --remote` also removes the bot HQ still holds under that
+  name. It checks with HQ before it deletes anything local, so a service that
+  cannot answer leaves nothing half-done.
+
+- Removing a bot now tells the truth when HQ only gets part of the way. When
+  HQ's own teardown of a bot's cloud identity stopped half-way, the
+  machine-readable form said the removal had failed but gave no reason and no
+  explanation, reported success to anything checking the exit code, and printed
+  the raw cloud error — including internal infrastructure addresses — straight
+  at you. It now says one plain sentence, names the reason in the same
+  vocabulary as everything else, and exits non-zero, and no internal detail is
+  repeated anywhere. It also stops making you run the command twice for
+  nothing: when the part HQ could not finish would fail the same way every
+  time, the bot is removed from this computer and you are told the leftover is
+  HQ's to clear; when it is something HQ may yet finish, your settings are kept
+  exactly as they were so running the same command again picks the job back up.
+
+- Bringing bots back now fails in plain language when HQ Cloud is too old for
+  it. `hq bot adopt`, `hq bot restore`, and `hq bot list --remote` all ask HQ
+  which bots you own; against an HQ Cloud without that capability, the raw
+  network error was printed at you, and the machine-readable form printed
+  nothing at all — so the desktop app had nothing it could read. Each now says
+  one plain sentence, and `--json` always returns a result naming the reason,
+  so the app can quietly fall back to showing the bots that are on this
+  computer.
+
 ## [5.116.0] — 2026-09-16
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -6374,6 +6374,61 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly usage: "[options]";
         readonly arguments: readonly [];
         readonly options: readonly [{
+            readonly flags: "--remote";
+            readonly description: "List the local bots your HQ account owns instead, with a here column saying which are set up on this computer";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "adopt";
+        readonly description: "Bring a bot you already own back to this computer: new machine credentials, its saved settings, worker folder, and startup agent";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <name>";
+        readonly arguments: readonly [{
+            readonly name: "name";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--runtime <runtime>";
+            readonly description: "Model CLI to run it with, overriding its saved one: claude|codex|grok";
+        }, {
+            readonly flags: "--model <model>";
+            readonly description: "Model override passed to the runtime CLI, replacing its saved one";
+        }, {
+            readonly flags: "--no-daemon";
+            readonly description: "Do not install the launchd agent (macOS)";
+        }, {
+            readonly flags: "--no-start";
+            readonly description: "Bring it back without starting it";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "restore";
+        readonly 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)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--all";
+            readonly description: "Also re-issue credentials and reinstall the startup agent for the bots already set up here";
+        }, {
+            readonly flags: "--dry-run";
+            readonly description: "Show what would be brought back, change nothing";
+        }, {
+            readonly flags: "--no-daemon";
+            readonly description: "Do not install the launchd agents (macOS)";
+        }, {
+            readonly flags: "--no-start";
+            readonly description: "Bring them back without starting them";
+        }, {
             readonly flags: "--json";
             readonly description: "Print machine-readable JSON";
         }];
@@ -6488,6 +6543,9 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly options: readonly [{
             readonly flags: "-y, --yes";
             readonly description: "Skip the confirmation prompt";
+        }, {
+            readonly flags: "--remote";
+            readonly description: "When the bot's local settings are already gone, also delete the bot HQ still has under that name";
         }, {
             readonly flags: "--json";
             readonly description: "Print machine-readable JSON";

package/dist/command-catalog.generated.js

@@ -8237,6 +8237,78 @@ export const COMMAND_CATALOG = [
                 "usage": "[options]",
                 "arguments": [],
                 "options": [
+                    {
+                        "flags": "--remote",
+                        "description": "List the local bots your HQ account owns instead, with a here column saying which are set up on this computer"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "adopt",
+                "description": "Bring a bot you already own back to this computer: new machine credentials, its saved settings, worker folder, and startup agent",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <name>",
+                "arguments": [
+                    {
+                        "name": "name",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--runtime <runtime>",
+                        "description": "Model CLI to run it with, overriding its saved one: claude|codex|grok"
+                    },
+                    {
+                        "flags": "--model <model>",
+                        "description": "Model override passed to the runtime CLI, replacing its saved one"
+                    },
+                    {
+                        "flags": "--no-daemon",
+                        "description": "Do not install the launchd agent (macOS)"
+                    },
+                    {
+                        "flags": "--no-start",
+                        "description": "Bring it back without starting it"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "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)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--all",
+                        "description": "Also re-issue credentials and reinstall the startup agent for the bots already set up here"
+                    },
+                    {
+                        "flags": "--dry-run",
+                        "description": "Show what would be brought back, change nothing"
+                    },
+                    {
+                        "flags": "--no-daemon",
+                        "description": "Do not install the launchd agents (macOS)"
+                    },
+                    {
+                        "flags": "--no-start",
+                        "description": "Bring them back without starting them"
+                    },
                     {
                         "flags": "--json",
                         "description": "Print machine-readable JSON"
@@ -8387,6 +8459,10 @@ export const COMMAND_CATALOG = [
                         "flags": "-y, --yes",
                         "description": "Skip the confirmation prompt"
                     },
+                    {
+                        "flags": "--remote",
+                        "description": "When the bot's local settings are already gone, also delete the bot HQ still has under that name"
+                    },
                     {
                         "flags": "--json",
                         "description": "Print machine-readable JSON"

package/dist/commands/bot.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { type RuntimeSignInIssue } from "../lib/bot/runtime-sign-in.js";
-import { type BotKind, type BotMemoryMode, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
+import { type BotLocalConfig, type MyLocalBot, type BotKind, type BotMemoryMode, type BotNotRunnableReason, type BotConfig, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
 /** Real launchctl; every failure is a non-ok result, never a throw. */
 export declare const defaultLaunchctl: LaunchctlExec;
 /** The desktop app creates HQ's setup bot under this name, always from the `setup` worker. */
@@ -101,5 +101,144 @@ export declare function runBotSet(nameArg: string, opts: {
     effort?: string;
     json?: boolean;
 }): Promise<void>;
+/**
+ * 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 declare function matchRemoteBots(bots: readonly MyLocalBot[], wanted: string): MyLocalBot[];
+export declare function resolveRemoteBot(bots: readonly MyLocalBot[], wanted: string): MyLocalBot;
+/**
+ * Why HQ could not say which bots the account owns. The desktop app switches
+ * on these values, so they are contract, not prose:
+ *
+ *   server-unsupported  the HQ Cloud in front of us has no listing route
+ *   auth                the sign-in was refused
+ *   network             HQ could not be reached at all
+ *   server-error        HQ answered 5xx
+ *   error               anything else
+ */
+export type RemoteBotsUnavailableReason = "server-unsupported" | "auth" | "network" | "server-error" | "error";
+export interface RemoteBotsUnavailable {
+    reason: RemoteBotsUnavailableReason;
+    message: string;
+}
+/**
+ * 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 declare function remoteBotsUnavailable(err: unknown): RemoteBotsUnavailable;
+/**
+ * A cloud teardown that only got part of the way, said in the same vocabulary
+ * the desktop switches on, plus the one decision that follows from it.
+ *
+ * `DELETE /v1/agents/{uid}` answers 200 with `terminal:false` and a per-step
+ * `failures` map when it could do only part of the job. Those strings are raw
+ * infrastructure: one real answer carried the AWS account id, an assumed-role
+ * ARN and a DynamoDB table ARN. They are classified here and never repeated —
+ * `detail` is a plain clause, `steps` is the server's own step names and
+ * nothing of what they said.
+ *
+ * `retryable` is the local-state decision. Running `hq bot rm` again can only
+ * finish the job when the step that failed might behave differently next time.
+ * A refusal, or a step whose target was already gone, answers the same way
+ * forever, so the local copy goes and the message says the leftover is HQ's.
+ *
+ * `reason` reuses {@link RemoteBotsUnavailableReason}: `auth` for a refused
+ * step (a permission problem, on either side of the call), `error` for a step
+ * whose target was already gone, `server-error` for anything HQ may yet
+ * finish.
+ */
+export interface BotRemovalIncomplete {
+    reason: RemoteBotsUnavailableReason;
+    /** One plain clause naming what stopped. Never a transport string. */
+    detail: string;
+    /** Whether running the same command again can still finish the removal. */
+    retryable: boolean;
+    /** The server's step names only — no ids, ARNs or messages. */
+    steps: string[];
+}
+export declare function botRemovalIncomplete(failures?: Record<string, string>): BotRemovalIncomplete;
+/**
+ * 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 declare function configFromLocalConfig(input: {
+    name: string;
+    agentUid: string;
+    ownerUid: string;
+    hqRoot: string;
+    dir: string;
+    local: BotLocalConfig | null;
+    overrides?: {
+        runtime?: BotRuntimeId;
+        model?: string;
+    };
+    now?: () => Date;
+}): {
+    config: BotConfig;
+    notes: string[];
+};
+export interface BotAdoptResult {
+    name: string;
+    agentUid: string;
+    runtime: BotRuntimeId;
+    kind: BotKind;
+    companies: string[];
+    dir: string;
+    worker: string;
+    memory: BotMemoryMode;
+    memoryDir: string;
+    /** True when the cloud had no saved settings and defaults were used. */
+    defaulted: boolean;
+    notes: string[];
+    daemon: string | null;
+}
+export declare function runBotAdopt(nameArg: string, opts: {
+    runtime?: string;
+    model?: string;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface BotRestoreRow {
+    name: string;
+    agentUid: string;
+    /** restored = brought back here; repaired = new credentials for one already here. */
+    action: "restored" | "repaired" | "skipped" | "failed" | "would-restore" | "would-repair" | "would-skip";
+    detail: string;
+    /** Present only on a bot skipped because this computer cannot run it. */
+    reason?: BotNotRunnableReason;
+}
+/**
+ * `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 declare function runBotRestore(opts: {
+    all?: boolean;
+    dryRun?: boolean;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface RemoteBotRow {
+    name: string;
+    agentUid: string;
+    kind: string;
+    online: boolean;
+    lastHeartbeatAt: string | null;
+    /** True when this bot is set up on this computer. */
+    here: boolean;
+    settings: string;
+    /** False when this computer cannot run it, whatever the listing says. */
+    runnable: boolean;
+    /** Why not, when `runnable` is false: the same vocabulary adopt and restore use. */
+    reason: BotNotRunnableReason | null;
+}
 export declare function registerBotCommand(program: Command): void;
 //# sourceMappingURL=bot.d.ts.map