@indigoai-us/hq-cli 5.175.0 → 5.177.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.177.0] — 2026-09-24
+
+### Added
+
+- `hq lanes create --hire-grant`, `hq lanes grant`, and `hq lanes backfill-grants`
+  manage alive child-lane grants. `lanes.hire-grants` defaults off; lane list and
+  show include grant and alive-child counts. Terminal child resume, message, and
+  account-move paths recheck occupancy and remaining grant allocation. The
+  backfill defaults to dry-run.
+
+- When `lanes.hire-grants` is enabled, `hq lanes list` and `hq lanes show` use counts
+  from the owning Outpost for active remote lanes. If the Outpost does not return
+  counts, both commands show local counts and a warning.
+
+## [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
@@ -26,6 +46,7 @@
 - Bot LaunchAgents and systemd units, the Work Mesh daemon unit, the `hq daemon` unit, and the lanes and agent-kit units now name node by its upgrade-stable path (`/opt/homebrew/bin/node` or `/opt/homebrew/opt/<formula>/bin/node`, or nvm's `current` link) instead of the versioned `/opt/homebrew/Cellar/node/<version>/bin/node`. Before, `brew upgrade node` deleted that path and launchd could no longer start the bots. The stable path is used only when it resolves to the same node binary; otherwise the unit keeps the resolved path as before.
 - Installed bot LaunchAgents that still name a versioned or missing node are repaired: `hq bot start` rewrites and reloads the agent, a bot started by launchd rewrites its own agent and reloads it from a detached shell before it takes any message, and `hq doctor` reports it (`bots.<name>.daemon-node`), with `hq doctor --fix` rewriting only the plist file and not reloading launchd. `hq bot list` and `hq bot status` flag a missing node binary. `hq mesh daemon install --if-stale` also reinstalls a same-version unit whose node path is missing or versioned.
 
+
 ## [5.172.0] — 2026-09-24
 
 ### Changed

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

@@ -6886,6 +6886,9 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--senior <ref>";
             readonly description: "session:<id> | lane:<id> | user";
+        }, {
+            readonly flags: "--hire-grant <n>";
+            readonly description: "Maximum alive direct child lanes assigned to this lane; set by its senior";
         }, {
             readonly flags: "--timeout <secs>";
             readonly description: "Deadline in seconds (warns, does not kill)";
@@ -6906,6 +6909,43 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "grant";
+        readonly description: "Set a lane's alive child-lane grant as its senior";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <lane-id>";
+        readonly arguments: readonly [{
+            readonly name: "lane-id";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--hire <n>";
+            readonly description: "Non-negative safe integer hire grant";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "backfill-grants";
+        readonly description: "Preview or apply missing hire grants for alive manager lanes";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--dry-run";
+            readonly description: "Print proposed values without writing (default)";
+        }, {
+            readonly flags: "--apply";
+            readonly description: "Write missing hire grants; only run before enforcement is enabled";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "list";
         readonly description: "List lanes";

package/dist/command-catalog.generated.js

@@ -8898,6 +8898,10 @@ export const COMMAND_CATALOG = [
                         "flags": "--senior <ref>",
                         "description": "session:<id> | lane:<id> | user"
                     },
+                    {
+                        "flags": "--hire-grant <n>",
+                        "description": "Maximum alive direct child lanes assigned to this lane; set by its senior"
+                    },
                     {
                         "flags": "--timeout <secs>",
                         "description": "Deadline in seconds (warns, does not kill)"
@@ -8925,6 +8929,54 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "grant",
+                "description": "Set a lane's alive child-lane grant as its senior",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <lane-id>",
+                "arguments": [
+                    {
+                        "name": "lane-id",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--hire <n>",
+                        "description": "Non-negative safe integer hire grant"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "backfill-grants",
+                "description": "Preview or apply missing hire grants for alive manager lanes",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--dry-run",
+                        "description": "Print proposed values without writing (default)"
+                    },
+                    {
+                        "flags": "--apply",
+                        "description": "Write missing hire grants; only run before enforcement is enabled"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "list",
                 "description": "List lanes",

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/dist/commands/lanes.d.ts

@@ -9,9 +9,10 @@ import { Command } from "commander";
 import type { OutpostIdentity } from "../lib/lanes/admission-host.js";
 export { OUTPOST_DIR, OUTPOST_ID_PATH, readOutpostIdentity } from "../lib/lanes/admission-host.js";
 export type { OutpostIdentity } from "../lib/lanes/admission-host.js";
+export { LANE_HIRE_GRANTS_FLAG };
 import { type OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
 import { emitLaneDecisionEvents, type LaneMesh } from "../lib/lanes/mesh-events.js";
-import { MAX_LANE_DEPTH, type LaneCompanyRef, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type MonitorEvidenceReader, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
+import { LANE_HIRE_GRANTS_FLAG, MAX_LANE_DEPTH, type LaneCompanyRef, type LaneRecord, type QuestionRecord, type ResolvedLaneWorker, type SeniorRef, type LivenessDeps, type MachineIdentity, type MonitorEvidenceReader, type RunCommand, type ThrottleDeps } from "../lib/lanes/index.js";
 import { questionBodyAbsPath } from "../lib/lanes/questions.js";
 import { type RunCompactionFn } from "../lib/lanes/compaction.js";
 import { type KnownModelsDeps, type ProbeCommand } from "../lib/lanes/models.js";
@@ -77,6 +78,8 @@ export interface LanesCommandDeps {
     monitorEvidence?: MonitorEvidenceReader;
     /** Test seam for the default-off outpost placement rollout flag. */
     lanePlacementEnabled?: () => boolean;
+    /** Test seam for the default-off lane hire-grants rollout gate. */
+    laneHireGrantsEnabled?: () => boolean;
 }
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 export declare function parseSeniorRef(raw: string): SeniorRef;