@indigoai-us/hq-cli 5.345.176 → 5.345.178

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [5.345.178] — 2026-10-29
+- `hq dm send --attach` now uploads the bytes it read with their exact length, so a file changed after the size check no longer stalls and fails with `Upload failed (HTTP 400)`. A refused upload now names the storage error (for example `RequestTimeout`).
+- `hq daemon disable mesh` now keeps `mesh` off on machines where it is not on by default,
+  such as an agent kit with `sync-core` turned on. In 5.345.176 the disable was not saved
+  there, so `sync-core` turned `mesh` back on; the 5.345.176 note that disabling `mesh`
+  still turns it off held only for machine types that run `mesh` by default.
+- `hq run` now skips `# @optional` secrets the caller cannot read or that are missing, instead of failing the whole run. Required secrets still fail.
+- The company-gated HQ Fleet default now supports new personal Claude, Codex and Grok bots. Codex and Grok bots stay stopped until their own provider sign-in succeeds; creation and status show the sign-in command. Cancelled sign-in can be retried without creating another bot. Existing bots and the explicit legacy runner are preserved.
+- Where the company flag `agents.local-bots-hq-fleet-default` is on, `hq bot create`
+  makes personal Claude bots (the setup bot included) on the HQ Fleet Runtime.
+  These bots run on the owner's Claude Code login and need no sign-in of their own.
+  `--legacy-runtime` keeps the model-CLI runner, and Codex and Grok bots keep it
+  unless `--hq-fleet-runtime` is passed. `--hq-fleet-runtime` now takes
+  `--runtime claude|codex|grok` and `--model` to choose the bot's model login.
+- HQ Fleet Runtime bots send their intro and run their kickoff on first start.
+  `hq bot status` and `hq bot list` read their status file.
+  `hq bot adopt` and `hq bot restore` bring them back on the runtime instead of as
+  Claude CLI bots. The bot's saved settings now keep the model login it uses.
+- Pins hq-fleet-local v0.4.12. On that release a bot gives its owner the owner's
+  companies that turned the flag on, and gives a teammate only the ones the
+  teammate also belongs to. A tool call is blocked when an HQ check cannot run.
+- The fleet-default flag is read for the owner's own active memberships, and a
+  bot is given only the companies that turned it on. `HQ_BOT_FLEET_DEFAULT=1`
+  skips the flag and gives the bot every active membership whose company
+  folder is on the computer.
+- HQ Fleet Runtime bots install a smaller runtime (the mcp and anthropic extras
+  only), so creating one takes less time and disk space.
+- `hq sync pull`, `push` and `now` (including `pull --all` and the first sync after setup) now refresh the HQ session when the access token expires during a long run and retry the rejected request once. Before, the sync read the token once at the start, so a run that outlasted the one-hour token failed every remaining target with 401 Unauthorized. If the session is rejected, the sync stops with "Run `hq login`, then rerun the sync". A network or server failure during the refresh gets its own message. The refreshed token must belong to the account that started the run: if a mid-run `hq login` or the machine-identity fallback changes the account, the sync stops instead of continuing as a different account. Feedback 3d3fab0b-9475-472d-91ce-9e7aa5a7443c.
+- A sync run's account is now fixed once the run starts. If the session would switch to another account mid-run, including a fallback to this computer's machine credentials after a rejected refresh, the sync stops with an explanation instead of continuing as that account. A run whose starting token does not identify an account does not start.
+- The daemon now records the newest change number the server announced for each vault, so the sync engine can skip background requests when it already has that change once it reads this.
+
+## [5.345.177] — 2026-10-28
+- The new sync engine now installs as release v0.1.21, and company vaults move to full mode only on v0.1.21 or later. A remote delete the server refuses because the file changed now re-reads the server's changes within seconds instead of waiting for the hourly check. Deleting a file that is already gone on the server now counts as done instead of stopping the sync until someone repairs it, and a held remote delete no longer stops the rest of the sync. A file this machine just replaced is no longer downloaded again or turned into a conflict copy while the server catches up.
+
 ## [5.345.176] — 2026-10-28
 - `hq bot list --json` rows carry `runtimeCrash`. It is set when the bot's coding tool crashed before a turn started, the crash came after the bot last started, and no turn has worked since; otherwise it is null. It gives the time, exit code, how long the tool ran, and the first line of what the tool printed. A restart or a working turn clears it. HQ uses it to warn before sending the bot work it would fail, for example the Daily Brief's Create brief.
 - A local bot started by the HQ app on macOS now restarts itself, between turns, when an HQ app update replaces the app's launcher. Before this, macOS stopped letting the bot's coding tool read the Documents folder after the update, and every message failed within milliseconds ("Claude Code stopped with an error") until the bot was restarted by hand.

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

@@ -18787,10 +18787,18 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--runtime <runtime>";
             readonly description: "Model CLI to run the bot with: claude|codex|grok";
             readonly hidden: false;
+        }, {
+            readonly flags: "--provider <provider>";
+            readonly description: "HQ Fleet provider: claude|codex|grok (interactive Fleet creation prompts when omitted)";
+            readonly hidden: false;
         }, {
             readonly flags: "--hq-fleet-runtime";
             readonly description: "Create this personal bot with the local HQ Fleet Runtime";
             readonly hidden: false;
+        }, {
+            readonly flags: "--legacy-runtime";
+            readonly description: "Run this bot with the model CLI even where the HQ Fleet Runtime is the default";
+            readonly hidden: false;
         }, {
             readonly flags: "--model <model>";
             readonly description: "Model override passed to the runtime CLI";

package/dist/command-catalog.generated.js

@@ -22893,11 +22893,21 @@ export const COMMAND_CATALOG = [
                         "description": "Model CLI to run the bot with: claude|codex|grok",
                         "hidden": false
                     },
+                    {
+                        "flags": "--provider <provider>",
+                        "description": "HQ Fleet provider: claude|codex|grok (interactive Fleet creation prompts when omitted)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--hq-fleet-runtime",
                         "description": "Create this personal bot with the local HQ Fleet Runtime",
                         "hidden": false
                     },
+                    {
+                        "flags": "--legacy-runtime",
+                        "description": "Run this bot with the model CLI even where the HQ Fleet Runtime is the default",
+                        "hidden": false
+                    },
                     {
                         "flags": "--model <model>",
                         "description": "Model override passed to the runtime CLI",

package/dist/commands/bot.d.ts

@@ -12,6 +12,9 @@ export interface BotRow {
     agentUid: string;
     ownerUid: string;
     runtime: BotRuntimeId;
+    needsSignIn?: boolean;
+    authCommand?: string;
+    serviceInstallPending?: boolean;
     model?: string;
     /** Thinking level the bot runs with (its setting, or the default). */
     effort: string;
@@ -135,7 +138,9 @@ export declare function resolveCreateKind(opts: {
 };
 export interface BotCreateOptions {
     runtime?: string;
+    provider?: string;
     hqFleetRuntime?: boolean;
+    legacyRuntime?: boolean;
     model?: string;
     effort?: string;
     autoApprove?: boolean;

package/dist/commands/bot.js

@@ -52,7 +52,7 @@ import { isAncestorProcess } from "../lib/bot/self-process.js";
 import { runtimeDisplayName, signInCommand } from "../lib/bot/runtime-sign-in.js";
 import { classifyRuntimeFailure, runtimeFailureReason } from "../lib/bot/runtime-failure.js";
 import { PROBE_DEFAULT_TIMEOUT_MS, probeBotRuntime } from "../lib/bot/probe.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, runtimeCrashSinceStart, 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, withBotLock, localBotRole, remoteBotRole, remoteBotDisplayName, personFacingName, writeCloudDisplayName, setupSlugFor, ASSISTANT_ROLE, HQ_FLEET_RUNTIME_ENGINE_ID, authenticateFleetLocalBot, bootstrapFleetLocalBot, buildSystemPrompt, controlFleetLocalBot, ensureFleetPython, fleetLocalGatewayPid, refreshFleetLocalInstructions, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, readPromptSources, removeFleetLocalBot, } from "../lib/bot/index.js";
+import { BotApi, BotApiError, BOT_RESTORE_DEFAULTS, buildBotLocalConfig, describeBotLocalConfig, orphanBotRunMessage, parseBotLocalConfig, removeOrphanBotDaemon, botDaemonStatus, botDir, botCredsPath, botLogPath, botsRoot, botTokenStateDir, botWorkerRelDir, buildBotDaemonPaths, createBotLogger, deleteBotCreds, installBotDaemon, 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, runtimeCrashSinceStart, 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, withBotLock, localBotRole, remoteBotRole, remoteBotDisplayName, personFacingName, writeCloudDisplayName, setupSlugFor, ASSISTANT_ROLE, HQ_FLEET_RUNTIME_ENGINE_ID, authenticateFleetLocalBot, bootstrapFleetLocalBot, buildSystemPrompt, controlFleetLocalBot, ensureFleetPython, fleetLocalGatewayPid, fleetProviderForRuntime, importFleetLocalMachineCredential, fleetProviderNeedsSignIn, fleetDefaultCompanies, fleetOwnerCompanies, fleetRuntimeIsDefault, refreshFleetLocalInstructions, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, readPromptSources, removeFleetLocalBot, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -144,11 +144,25 @@ function fleetBotSystemPrompt(name, config, overrides = {}) {
         }),
     });
 }
+function fleetAuthCommand(name, config) {
+    return `hq bot auth ${name} --provider ${config.runtime === "grok" ? "grok" : config.runtime === "codex" ? "chatgpt" : "claude"}`;
+}
 function runFleetRuntimeControl(name, config, action, json) {
+    if ((action === "start" || action === "restart") && config.fleetAuthPending === true) {
+        const authCommand = fleetAuthCommand(name, config);
+        if (json)
+            console.log(JSON.stringify({ ok: false, name, running: false, state: "stopped", needsSignIn: true, authCommand }, null, 2));
+        else
+            throw Object.assign(new Error(`Sign this bot in first: ${authCommand}`), { expected: true });
+        return;
+    }
     if (action === "start" || action === "restart") {
         refreshFleetLocalInstructions(config.agentUid, fleetBotSystemPrompt(name, config));
     }
-    const result = controlFleetLocalBot(config.agentUid, action);
+    const installService = config.fleetServiceInstallPending === true && (action === "start" || action === "restart");
+    const result = controlFleetLocalBot(config.agentUid, installService ? "install" : action);
+    if (installService && result.ok)
+        patchBotConfig(botDir(name), { fleetServiceInstallPending: false, enabled: true });
     if (json) {
         console.log(JSON.stringify({ name, runtime: HQ_FLEET_RUNTIME_ENGINE_ID, ...result }, null, 2));
         return;
@@ -192,7 +206,7 @@ function rowFor(name, opts = {}) {
     const dir = botDir(name);
     const config = readBotConfig(dir);
     const fleet = isFleetRuntimeBot(config);
-    const status = fleet ? null : readBotStatus(dir);
+    const status = readBotStatus(dir);
     const pid = fleet ? fleetLocalGatewayPid(config.agentUid) : (status?.pid ?? null);
     const processAlive = pid !== null && isPidAlive(pid) && (fleet || status?.state === "running");
     // Turns this bot has taken and not finished: what "thinking" means.
@@ -220,7 +234,7 @@ function rowFor(name, opts = {}) {
         model: config.model,
         effort: effectiveBotEffort(config),
         effortIsDefault: !config.effort,
-        state: processAlive ? "running" : status?.state === "failed" ? "failed" : "stopped",
+        state: processAlive ? "running" : !fleet && status?.state === "failed" ? "failed" : "stopped",
         pid: processAlive ? pid : null,
         processAlive,
         hosting: hasActivePromotion(dir, config.agentUid, config.ownerUid) ? "cloud" : "local",
@@ -234,8 +248,10 @@ function rowFor(name, opts = {}) {
         busySince: processAlive ? (inflightTurns[0]?.startedAt ?? null) : null,
         runtimeSignIn: status?.runtimeSignIn ?? null,
         runtimeSignInCheck: status?.runtimeSignInCheck ?? null,
-        runtimeSignedIn: runtimeSignedIn(status, processAlive),
-        signInCommand: signInCommand(config.runtime),
+        runtimeSignedIn: config.fleetAuthPending === true ? false : runtimeSignedIn(status, processAlive),
+        ...(fleet && config.fleetAuthPending === true ? { needsSignIn: true, authCommand: fleetAuthCommand(name, config) } : {}),
+        ...(fleet && config.fleetServiceInstallPending === true ? { needsSignIn: false, serviceInstallPending: true } : {}),
+        signInCommand: fleet ? fleetAuthCommand(name, config) : signInCommand(config.runtime),
         runtimeCrash: processAlive ? runtimeCrashSinceStart(status) : null,
         daemonInstalled,
         daemonLoaded,
@@ -340,6 +356,8 @@ function stopProcess(dir) {
 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 (isFleetRuntimeBot(config))
+        return startFleetRuntimeBot(name, dir, config, output, extra);
     if (config.enabled === false)
         patchBotConfig(dir, { enabled: true });
     const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
@@ -401,6 +419,41 @@ async function startBot(name, dir, config, output, extra = {}) {
     }
     return { running, how };
 }
+/** Start (or restart) an HQ Fleet Runtime bot under its own service, with fresh instructions. */
+async function startFleetRuntimeBot(name, dir, config, output, extra) {
+    if (config.fleetAuthPending === true) {
+        const authCommand = fleetAuthCommand(name, config);
+        if (output === "json")
+            console.log(JSON.stringify({ ok: false, name, running: false, needsSignIn: true, authCommand }, null, 2));
+        else if (output !== "silent")
+            throw Object.assign(new Error(`Sign this bot in first: ${authCommand}`), { expected: true });
+        return { running: false, how: "waiting for sign-in" };
+    }
+    refreshFleetLocalInstructions(config.agentUid, fleetBotSystemPrompt(name, config));
+    const before = readBotStatus(dir);
+    const alreadyRunning = !!before && before.state === "running" && isPidAlive(before.pid);
+    const installService = config.fleetServiceInstallPending === true;
+    const result = controlFleetLocalBot(config.agentUid, installService ? "install" : alreadyRunning ? "restart" : "start");
+    if (installService && result.ok)
+        patchBotConfig(dir, { fleetServiceInstallPending: false, enabled: true });
+    const how = alreadyRunning ? "restarted by the HQ Fleet Runtime" : "started by the HQ Fleet Runtime";
+    const running = result.ok === true && (await waitFor(() => {
+        const s = readBotStatus(dir);
+        return !!s && s.state === "running" && isPidAlive(s.pid);
+    }, 45_000));
+    const status = readBotStatus(dir);
+    if (output === "silent")
+        return { running, how };
+    if (output === "json") {
+        console.log(JSON.stringify({ ok: running, name, ...extra, running, how, state: status?.state ?? "unknown", pid: status?.pid ?? null, 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 45s`) + chalk.dim(`  logs: ~/.hq-fleet/profiles/${config.agentUid}/logs`));
+    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
@@ -436,6 +489,14 @@ function requestSelfStopDrain(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.");
+    if (isFleetRuntimeBot(config)) {
+        const result = controlFleetLocalBot(config.agentUid, "stop");
+        if (output === "json")
+            console.log(JSON.stringify({ ok: result.ok === true, name, stopped: result.ok === true, how: "stopped by the HQ Fleet Runtime" }, null, 2));
+        else if (output === "text")
+            console.log(chalk.green(`${name} stopped`));
+        return;
+    }
     const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
     const hqDaemon = daemonPaths();
     const before = readBotStatus(dir);
@@ -546,6 +607,28 @@ export function resolveCreateKind(opts, worker) {
     }
     return { kind, companies };
 }
+async function promptFleetProvider() {
+    if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+        throw Object.assign(new Error("--provider is required with --hq-fleet-runtime in a non-interactive command (claude, codex, or grok)."), { expected: true });
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question("Provider: 1) Codex  2) Claude  3) Grok [1]: ", resolve);
+        });
+        const selected = answer.trim().toLowerCase();
+        if (selected === "" || selected === "1" || selected === "codex")
+            return "codex";
+        if (selected === "2" || selected === "claude")
+            return "claude";
+        if (selected === "3" || selected === "grok")
+            return "grok";
+        throw Object.assign(new Error("Provider must be claude, codex, or grok."), { expected: true });
+    }
+    finally {
+        rl.close();
+    }
+}
 /**
  * `hq bot create`. Runs under the bot's lock, so a create racing an adopt,
  * restore, rm or set of the same bot waits for it instead of tripping over
@@ -664,11 +747,21 @@ async function finishExistingSetupBot(name, dir, config, displayName, opts) {
         console.log(chalk.yellow(`${name} did not report running within 15s`) + chalk.dim(`  logs: hq bot logs ${name}`));
 }
 async function runBotCreateLocked(name, opts) {
-    const useFleetRuntime = opts.hqFleetRuntime === true;
-    if (useFleetRuntime && (opts.runtime || opts.model || opts.effort || opts.lean)) {
-        throw Object.assign(new Error("--hq-fleet-runtime selects the local HQ runtime. Do not combine it with --runtime, --model, --effort, or --lean."), { expected: true });
+    const requestedFleetRuntime = opts.hqFleetRuntime === true;
+    if (requestedFleetRuntime && opts.legacyRuntime) {
+        throw Object.assign(new Error("Pick one of --hq-fleet-runtime and --legacy-runtime."), { expected: true });
+    }
+    if (requestedFleetRuntime && (opts.effort || opts.lean)) {
+        throw Object.assign(new Error("--hq-fleet-runtime sets its own thinking level. Do not combine it with --effort or --lean."), { expected: true });
     }
-    const runtime = opts.runtime ?? "claude";
+    if (opts.provider && !isBotRuntimeId(opts.provider)) {
+        throw Object.assign(new Error(`--provider must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
+    }
+    if (opts.provider && opts.runtime && opts.provider !== opts.runtime) {
+        throw Object.assign(new Error("--provider and --runtime must name the same provider when both are used."), { expected: true });
+    }
+    const selectedProvider = opts.provider ?? opts.runtime ?? (requestedFleetRuntime ? await promptFleetProvider() : undefined);
+    const runtime = selectedProvider ?? "claude";
     if (!isBotRuntimeId(runtime)) {
         throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
     }
@@ -703,6 +796,15 @@ async function runBotCreateLocked(name, opts) {
     // cost an identity).
     const worker = opts.worker?.trim() ? resolveBotWorker(hqRoot, opts.worker) : null;
     const { kind, companies } = resolveCreateKind(opts, worker);
+    // Companies with the fleet-default flag get their personal bots on
+    // the HQ Fleet Runtime; --legacy-runtime keeps the model-CLI runner.
+    const fleetCandidate = requestedFleetRuntime ||
+        (!opts.legacyRuntime && kind === "personal" && !opts.effort && !opts.lean);
+    // Owner turns on the bot may use only these companies: the owner's own,
+    // and only where the company turned the flag on.
+    const flaggedCompanies = fleetCandidate && kind === "personal" ? await fleetDefaultCompanies(hqRoot) : [];
+    const useFleetRuntime = requestedFleetRuntime || (fleetCandidate && fleetRuntimeIsDefault(flaggedCompanies));
+    const ownerCompanies = useFleetRuntime && kind === "personal" ? await fleetOwnerCompanies() : [];
     if (useFleetRuntime && kind !== "personal") {
         throw Object.assign(new Error("--hq-fleet-runtime creates a personal bot. Drop --kind company and --company."), {
             expected: true,
@@ -726,6 +828,8 @@ async function runBotCreateLocked(name, opts) {
         ? await installPinnedFleetLocalDistribution()
         : null;
     const fleetPython = fleetInstallation ? await ensureFleetPython() : null;
+    const fleetProvider = fleetInstallation ? fleetProviderForRuntime(runtime, model) : null;
+    const fleetAuthPending = fleetProvider !== null && fleetProviderNeedsSignIn(fleetProvider);
     const token = await ownerToken();
     const owner = await resolveCallerPersonUid(token, undefined, { command: "hq bot create" });
     if (!owner)
@@ -932,7 +1036,8 @@ async function runBotCreateLocked(name, opts) {
         ...(kickoff ? { kickoff } : {}),
         ...(opts.lean && runtime === "claude" ? { lean: true } : {}),
         createdAt: new Date().toISOString(),
-        enabled: true,
+        enabled: !fleetAuthPending,
+        ...(fleetAuthPending ? { fleetAuthPending: true } : {}),
     };
     writeBotConfig(dir, config);
     // A company bot acts as itself, so it must be a member of each of its
@@ -971,7 +1076,13 @@ async function runBotCreateLocked(name, opts) {
             installation: fleetInstallation,
             machineCredentials: botCredsPath(dir),
             systemPrompt: fleetBotSystemPrompt(name, config, { kind, companies }),
-        }, { start: opts.start !== false, python: fleetPython })
+            provider: fleetProvider,
+            ownerCompanies,
+            firstStart: {
+                intro: introDmText(name, runtime, intro, { kind, companies }),
+                ...(kickoff ? { kickoff } : {}),
+            },
+        }, { start: opts.start !== false && !fleetAuthPending, python: fleetPython })
         : null;
     const fleetProfile = fleetBootstrap?.profile ?? null;
     const runtimeLabel = fleetInstallation ? HQ_FLEET_RUNTIME_ENGINE_ID : runtime;
@@ -998,6 +1109,7 @@ async function runBotCreateLocked(name, opts) {
         kickoff: kickoff ?? null,
         model: model ?? null,
         effort: fleetInstallation ? null : effort ?? DEFAULT_BOT_EFFORT,
+        ...(fleetProvider ? { provider: fleetProvider.id, needsSignIn: fleetAuthPending, ...(fleetAuthPending ? { authCommand: fleetAuthCommand(name, config) } : {}) } : {}),
     };
     let daemonMessage = null;
     if (!fleetInstallation && opts.daemon !== false && process.platform === "darwin") {
@@ -1015,6 +1127,9 @@ async function runBotCreateLocked(name, opts) {
         console.log(chalk.dim(`  state:  ${dir}`));
         if (fleetProfile)
             console.log(chalk.dim(`  profile: ${fleetProfile}`));
+        if (fleetProvider && fleetProviderNeedsSignIn(fleetProvider)) {
+            console.log(chalk.yellow(`  sign it in before it can answer: hq bot auth ${name} --provider ${runtime === "grok" ? "grok" : "chatgpt"}`));
+        }
         if (daemonMessage)
             console.log(chalk.dim(`  ${daemonMessage}`));
     }
@@ -1232,25 +1347,26 @@ async function runBotList(opts) {
 }
 async function runBotStatus(nameArg, opts) {
     const { name, dir, config } = requireBot(nameArg);
-    if (isFleetRuntimeBot(config)) {
-        runFleetRuntimeControl(name, config, "status", opts.json === true);
-        return;
-    }
+    const fleet = isFleetRuntimeBot(config);
     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));
+        console.log(JSON.stringify({ ...row, ...(fleet ? { engine: config.engine } : {}), credsPresent: fleet || !!creds, status }, null, 2));
         return;
     }
     console.log(`${chalk.bold(name)}  ${row.agentUid}`);
+    if (fleet)
+        console.log(`  engine:     HQ Fleet Runtime ${config.engine?.version ?? ""}  ${chalk.dim(`logs ~/.hq-fleet/profiles/${config.agentUid}/logs`)}`);
     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)}`);
+    if (row.needsSignIn)
+        console.log(`  sign-in:    required (${row.authCommand})`);
     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}`) : ""}`);
@@ -1263,7 +1379,7 @@ async function runBotStatus(nameArg, opts) {
     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")}`);
+    console.log(`  creds:      ${fleet ? "in the system keychain" : creds ? `present for ${creds.entityUid}` : chalk.red("missing")}`);
     if (status) {
         console.log(`  started:    ${status.startedAt}   restarts: ${status.restarts}   replies: ${status.repliesSent}`);
         if (status.cliVersion)
@@ -1729,17 +1845,30 @@ async function runBotAuth(nameArg, opts) {
     const result = authenticateFleetLocalBot({
         agentUid: b.config.agentUid,
         provider: opts.provider,
+        ...(b.config.fleetAuthPending === true ? { installService: true } : {}),
         ...(opts.model ? { model: opts.model } : {}),
         ...(apiKey ? { apiKey } : {}),
         ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
         ...(opts.transport ? { transport: opts.transport } : {}),
         openBrowser: opts.browser !== false,
     });
+    const signedInRuntime = result.runtimeProvider === "anthropic" ? "claude" : result.runtimeProvider === "xai-oauth" ? "grok" : result.runtimeProvider === "openai-codex" ? "codex" : null;
+    if (result.authenticated !== true)
+        throw Object.assign(new Error("The provider has not completed sign-in."), { expected: true });
+    patchBotConfig(b.dir, {
+        ...(signedInRuntime ? { runtime: signedInRuntime } : {}),
+        model: result.model,
+        ...(b.config.fleetAuthPending === true ? { fleetAuthPending: false, fleetServiceInstallPending: !result.restarted, enabled: result.restarted } : {}),
+    });
+    const pid = fleetLocalGatewayPid(b.config.agentUid);
+    const running = pid !== null && isPidAlive(pid);
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, name: b.name, runtime: HQ_FLEET_RUNTIME_ENGINE_ID, ...result }, null, 2));
+        console.log(JSON.stringify({ ok: true, name: b.name, runtime: HQ_FLEET_RUNTIME_ENGINE_ID, ...result, needsSignIn: false, running, serviceInstallPending: b.config.fleetAuthPending === true && !result.restarted }, null, 2));
         return;
     }
-    console.log(chalk.green(`${b.name} is signed in to ${result.provider} and running ${result.model}.`));
+    console.log(running
+        ? chalk.green(`${b.name} is signed in to ${result.provider} and running ${result.model}.`)
+        : chalk.yellow(`${b.name} is signed in to ${result.provider}, but did not start. Run hq bot start ${b.name}.`));
 }
 // ── adopt / restore (bring a bot you own back to this computer) ──────────────
 /**
@@ -1993,6 +2122,9 @@ async function adoptRemoteBotLocked(input) {
         region: DEFAULT_COGNITO.region,
     });
     const local = parseBotLocalConfig(reissued.localConfig ?? bot.localConfig);
+    const fleetEngine = local?.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID;
+    if (fleetEngine && local && !local.runtime)
+        local.runtime = "codex";
     const { config, notes } = configFromLocalConfig({
         name,
         agentUid: bot.agentUid,
@@ -2003,14 +2135,40 @@ async function adoptRemoteBotLocked(input) {
         ...(input.overrides ? { overrides: input.overrides } : {}),
         ...(input.preserveFirstStart ? { preserveFirstStart: true } : {}),
     });
+    // A bot made on the HQ Fleet Runtime comes back on it, on the release this CLI pins.
+    const fleetInstallation = fleetEngine ? await installPinnedFleetLocalDistribution() : null;
+    const fleetPython = fleetInstallation ? await ensureFleetPython() : null;
+    if (fleetInstallation)
+        config.engine = fleetInstallation.engine;
     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);
+    if (fleetInstallation && fleetPython) {
+        await bootstrapFleetLocalBot({
+            agentUid: bot.agentUid,
+            ownerUid: config.ownerUid,
+            hqRoot: input.hqRoot,
+            botDir: dir,
+            installation: fleetInstallation,
+            machineCredentials: botCredsPath(dir),
+            systemPrompt: fleetBotSystemPrompt(name, config),
+            provider: fleetProviderForRuntime(config.runtime, config.model),
+            ownerCompanies: await fleetOwnerCompanies(),
+            ...(input.preserveFirstStart
+                ? {
+                    firstStart: {
+                        intro: introDmText(name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }),
+                        ...(config.kickoff ? { kickoff: config.kickoff } : {}),
+                    },
+                }
+                : {}),
+        }, { python: fleetPython, start: false });
+    }
     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") {
+    if (!fleetInstallation && input.daemon && process.platform === "darwin") {
         daemonMessage = installBotAgent(buildBotDaemonPaths({ name, botDir: dir, hqRoot: input.hqRoot })).message;
     }
     return {
@@ -2118,6 +2276,11 @@ async function repairLocalBot(name, api, bot, daemon) {
         region: DEFAULT_COGNITO.region,
     });
     createBotLogger(dir)("info", `re-issued machine credentials for ${name} (${bot.agentUid}) on ${localMachineId()}`);
+    if (isFleetRuntimeBot(config)) {
+        importFleetLocalMachineCredential(bot.agentUid, botCredsPath(dir));
+        const restarted = controlFleetLocalBot(bot.agentUid, "restart").ok === true;
+        return restarted ? "new credentials, HQ Fleet Runtime restarted" : "new credentials; the HQ Fleet Runtime did not restart (hq bot start " + name + ")";
+    }
     if (daemon && process.platform === "darwin") {
         installBotAgent(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }));
     }
@@ -2308,7 +2471,9 @@ export function registerBotCommand(program) {
         .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("|")}`)
+        .option("--provider <provider>", `HQ Fleet provider: ${BOT_RUNTIMES.join("|")} (interactive Fleet creation prompts when omitted)`)
         .option("--hq-fleet-runtime", "Create this personal bot with the local HQ Fleet Runtime")
+        .option("--legacy-runtime", "Run this bot with the model CLI even where the HQ Fleet Runtime is the default")
         .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)")

package/dist/commands/cloud.d.ts

@@ -41,6 +41,50 @@ export declare class SyncExitError extends Error {
         health?: "failed" | "succeeded";
     });
 }
+/** Shown when the session expires during a sync and cannot be renewed. */
+export declare const SYNC_SESSION_EXPIRED_MESSAGE = "Your HQ session expired during sync and could not be refreshed. Run `hq login`, then rerun the sync.";
+/** Shown when the refresh failed for a network or server reason. */
+export declare const SYNC_REFRESH_UNAVAILABLE_MESSAGE = "Could not refresh your HQ session during sync because the sign-in service did not respond. Check your connection, then rerun the sync.";
+/** Shown when the start token carries no principal to bind the run to. */
+export declare const SYNC_NO_IDENTITY_MESSAGE = "The HQ session token does not identify an account, so the sync did not start. Run `hq login`, then rerun the sync.";
+/** Shown when the token would change to a different account mid-run. */
+export declare const SYNC_IDENTITY_CHANGED_MESSAGE = "The signed-in HQ account changed while this sync was running, so the sync stopped instead of continuing as a different account. Rerun the sync as the account you want.";
+/**
+ * The session token expired during a sync run and the non-interactive
+ * refresh failed. `kind` separates a rejected session (sign in again) from a
+ * network or server failure (retry later).
+ */
+export declare class SyncSessionExpiredError extends Error {
+    readonly kind: "reauth" | "unavailable";
+    readonly reason?: string | undefined;
+    constructor(kind: "reauth" | "unavailable", reason?: string | undefined);
+}
+export interface SyncVaultConfigDeps {
+    /** Non-interactive token resolver: returns the cached token or refreshes it. */
+    ensureToken?: () => Promise<string>;
+}
+/** The last token failure recorded by a {@link buildSyncVaultConfig} config. */
+export declare function syncAuthFailureFor(config: VaultServiceConfig | undefined): Error | null;
+/**
+ * Vault config for a sync run whose token stays valid for the whole run.
+ *
+ * `initialToken` is resolved (and, on a TTY, logged in) before the run starts.
+ * The config carries a getter instead of that string, so every vault request
+ * re-reads the cached session and refreshes it when it is close to expiry.
+ * When a request still gets a 401, hq-cloud's VaultClient calls the getter
+ * once more and retries once if the token changed (no loop). A multi-company
+ * `hq sync pull --all` can outlast the one-hour Cognito access token; a
+ * captured string made every later target fail with 401 (feedback_3d3fab0b).
+ *
+ * The getter is bound to the principal of `initialToken`. If a later token
+ * belongs to a different principal (a mid-run `hq login` as another account,
+ * or the machine-identity fallback after a rejected person refresh), it throws
+ * an {@link IdentitySwapRefusal} and the run stops. It never continues as a
+ * different principal.
+ *
+ * Mid-run refreshes never open a browser.
+ */
+export declare function buildSyncVaultConfig(initialToken: string, deps?: SyncVaultConfigDeps): VaultServiceConfig;
 /**
  * Preserve the vault's typed write-scope refusal at the CLI boundary. This is
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
@@ -50,6 +94,7 @@ export declare function formatSyncFailure(err: unknown, ctx?: {
     hqRoot?: string;
     cwd?: string;
     companySlug?: string;
+    vaultConfig?: VaultServiceConfig;
 }): string;
 /**
  * The `.hqinclude` line that admits a named path: its HQ-relative spelling,
@@ -259,6 +304,8 @@ export interface SyncCallResult {
     aborted: boolean;
 }
 export interface PullAllDeps {
+    /** Formats a per-target failure; the real path binds the run's vault config. */
+    formatFailure?: (err: unknown) => string;
     vaultClient: PullAllVaultClient;
     sync: (options: SyncCallOptions) => Promise<SyncCallResult>;
     /**
@@ -352,6 +399,8 @@ export interface ShareCallResult {
     planLimit?: PlanLimitRefusalSummary | null;
 }
 export interface PushAllDeps {
+    /** Formats a per-target failure; the real path binds the run's vault config. */
+    formatFailure?: (err: unknown) => string;
     vaultClient: PullAllVaultClient;
     share: (options: ShareCallOptions) => Promise<ShareCallResult>;
     beforeShare?: (input: {