@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/commands/agent-kit.js

@@ -153,7 +153,7 @@ export function buildKitRuntime(service) {
     process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
     process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
     const log = createKitLogger(paths, service, { echo: process.stdout.isTTY === true });
-    const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    const getToken = (signal) => ensureCognitoToken({ tokenSource: "machine", interactive: false, ...(signal ? { signal } : {}) });
     return { paths, creds, config, getToken, log, credsSource };
 }
 export async function runKitService(service, rt) {
@@ -177,6 +177,7 @@ export async function runKitService(service, rt) {
                 },
                 apiBaseUrl: rt.creds.apiBaseUrl,
                 intervalMs: rt.config.heartbeatIntervalMs,
+                requestTimeoutMs: rt.config.requestTimeoutMs,
                 getToken: rt.getToken,
                 log: rt.log,
                 components: enabledKitComponents(rt.config),
@@ -192,6 +193,7 @@ export async function runKitService(service, rt) {
                     agentUid: rt.creds.entityUid,
                     apiBaseUrl: rt.creds.apiBaseUrl,
                     pollMs: rt.config.inboxPollMs,
+                    requestTimeoutMs: rt.config.requestTimeoutMs,
                     ack: rt.config.inboxAck,
                     getToken: rt.getToken,
                     log: rt.log,

package/dist/commands/agents.js

@@ -43,6 +43,7 @@ import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSe
 import { peekIdToken } from "../utils/id-token.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
 import { AGENT_UID_PATTERN, defaultAudienceFor, isAgentUid } from "../lib/notify-recipient.js";
+import { callerIsMachinePrincipal } from "../lib/caller-principal.js";
 import { AGENT_MODEL_PROVIDERS, modelSelectionErrorMessage, readAgentModelCatalog, validateAgentModelSelection, } from "../lib/agents/model-catalog.js";
 import { fetchCompanyPricingPlan, isUsageOnly, usageOnlyBoxSentence, usageOnlyCardRequiredLines, } from "../lib/billing/usage-only.js";
 import { BUNDLED_USAGE_CARD, fetchUsageCard, } from "../lib/billing/usage-card.js";
@@ -1139,7 +1140,7 @@ export async function sendAgentDm(token, agentUid, message) {
         token,
         path: "/v1/notify/dm",
         method: "POST",
-        body: { toPersonUid: agentUid, body: message, audience: defaultAudienceFor("agent") },
+        body: { toPersonUid: agentUid, body: message, audience: defaultAudienceFor("agent", callerIsMachinePrincipal()) },
     });
 }
 /** Read the two-way DM conversation with an agent (most recent `limit`). */

package/dist/commands/bot.d.ts

@@ -109,6 +109,7 @@ export declare function resolveCreateKind(opts: {
 };
 export interface BotCreateOptions {
     runtime?: string;
+    hqFleetRuntime?: boolean;
     model?: string;
     effort?: string;
     autoApprove?: boolean;
@@ -343,6 +344,8 @@ export interface RemoteBotRow {
     displayName: string | null;
     /** "assistant" for HQ's setup assistant, else null. */
     role: BotRole;
+    /** The owner's person uid exactly as GET /v1/agents/mine sends it; null when the server omits it. */
+    ownerUid: string | null;
 }
 export declare function registerBotCommand(program: Command): void;
 //# sourceMappingURL=bot.d.ts.map

package/dist/commands/bot.js

@@ -52,7 +52,7 @@ import { isAncestorProcess } from "../lib/bot/self-process.js";
 import { runtimeDisplayName } 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, 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, } 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, 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";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -114,6 +114,48 @@ function requireBot(name) {
     }
     return { name: valid, dir, config };
 }
+function isFleetRuntimeBot(config) {
+    return config.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID;
+}
+/**
+ * The standing HQ instructions an HQ Fleet Runtime bot runs under: the same
+ * text a legacy local bot gets, read fresh from its worker folder, with the
+ * runtime's own way of labelling senders.
+ */
+function fleetBotSystemPrompt(name, config, overrides = {}) {
+    return buildSystemPrompt({
+        botName: name,
+        ...(config.displayName ? { displayName: config.displayName } : {}),
+        agentUid: config.agentUid,
+        ownerUid: config.ownerUid,
+        hqRoot: config.hqRoot,
+        workerDir: config.workerDir,
+        workerSource: config.workerSource,
+        workerId: config.workerId,
+        companySlug: config.companySlug,
+        kind: overrides.kind ?? effectiveBotKind(config),
+        companies: overrides.companies ?? effectiveBotCompanies(config),
+        memoryDir: config.memoryDir,
+        fleetRuntime: true,
+        sources: readPromptSources(config.hqRoot, config.workerDir, undefined, {
+            memoryDir: config.memoryDir,
+            workerSource: config.workerSource,
+            companySlug: config.companySlug,
+        }),
+    });
+}
+function runFleetRuntimeControl(name, config, action, json) {
+    if (action === "start" || action === "restart") {
+        refreshFleetLocalInstructions(config.agentUid, fleetBotSystemPrompt(name, config));
+    }
+    const result = controlFleetLocalBot(config.agentUid, action);
+    if (json) {
+        console.log(JSON.stringify({ name, runtime: HQ_FLEET_RUNTIME_ENGINE_ID, ...result }, null, 2));
+        return;
+    }
+    const summary = typeof result.summary === "string" ? result.summary : `${action} completed`;
+    console.log(chalk.green(`${name}: ${summary}`));
+}
 /** Bot-identity token supplier: per-bot creds + per-bot token cache dir. */
 export function botTokenSupplier(dir) {
     process.env.HQ_MACHINE_CREDS_FILE = botCredsPath(dir);
@@ -137,15 +179,16 @@ async function ownerToken(interactive = process.stdin.isTTY === true) {
 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";
+    const fleet = isFleetRuntimeBot(config);
+    const status = fleet ? null : 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.
     const inflightTurns = readInflightTurns(dir);
     let daemonInstalled = false;
     let daemonLoaded = false;
     let daemonNodeMissing = null;
-    if (opts.withDaemon !== false) {
+    if (opts.withDaemon !== false && !fleet) {
         try {
             const d = botDaemonStatus(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
             daemonInstalled = d.installed;
@@ -605,6 +648,10 @@ 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 runtime = opts.runtime ?? "claude";
     if (!isBotRuntimeId(runtime)) {
         throw Object.assign(new Error(`--runtime must be one of ${BOT_RUNTIMES.join(", ")}`), { expected: true });
@@ -640,6 +687,11 @@ async function runBotCreateLocked(name, opts) {
     // cost an identity).
     const worker = opts.worker?.trim() ? resolveBotWorker(hqRoot, opts.worker) : null;
     const { kind, companies } = resolveCreateKind(opts, worker);
+    if (useFleetRuntime && kind !== "personal") {
+        throw Object.assign(new Error("--hq-fleet-runtime creates a personal bot. Drop --kind company and --company."), {
+            expected: true,
+        });
+    }
     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 assistant; create it with --worker ${RESERVED_SETUP_BOT_NAME}.`), { expected: true });
@@ -654,6 +706,10 @@ async function runBotCreateLocked(name, opts) {
             expected: true,
         });
     }
+    const fleetInstallation = useFleetRuntime
+        ? await installPinnedFleetLocalDistribution()
+        : null;
+    const fleetPython = fleetInstallation ? await ensureFleetPython() : null;
     const token = await ownerToken();
     const owner = await resolveCallerPersonUid(token, undefined, { command: "hq bot create" });
     if (!owner)
@@ -763,6 +819,7 @@ async function runBotCreateLocked(name, opts) {
     // instead of creating a new one. The machine secret never travels.
     const localConfig = buildBotLocalConfig({
         runtime,
+        ...(fleetInstallation ? { engine: fleetInstallation.engine } : {}),
         kind,
         ...(kind === "company" ? { companies } : {}),
         ...(model ? { model } : {}),
@@ -829,6 +886,7 @@ async function runBotCreateLocked(name, opts) {
         agentUid,
         ownerUid: created.agent.ownerUid ?? owner,
         runtime,
+        ...(fleetInstallation ? { engine: fleetInstallation.engine } : {}),
         kind,
         // A company bot's list is filled in below, with the invites that went through.
         ...(kind === "company" ? { companies: [] } : {}),
@@ -885,8 +943,23 @@ async function runBotCreateLocked(name, opts) {
     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}`);
+        : scaffoldBotWorker(hqRoot, name, agentUid, fleetInstallation ? HQ_FLEET_RUNTIME_ENGINE_ID : runtime, undefined, scaffoldOpts);
+    if (fleetInstallation)
+        fs.rmSync(path.join(dir, "status.json"), { force: true });
+    const fleetBootstrap = fleetInstallation && fleetPython
+        ? await bootstrapFleetLocalBot({
+            agentUid,
+            ownerUid: config.ownerUid,
+            hqRoot,
+            botDir: dir,
+            installation: fleetInstallation,
+            machineCredentials: botCredsPath(dir),
+            systemPrompt: fleetBotSystemPrompt(name, config, { kind, companies }),
+        }, { start: opts.start !== false, python: fleetPython })
+        : null;
+    const fleetProfile = fleetBootstrap?.profile ?? null;
+    const runtimeLabel = fleetInstallation ? HQ_FLEET_RUNTIME_ENGINE_ID : runtime;
+    createBotLogger(dir)("info", `created ${name} (${agentUid}) kind=${kind}${companies.length ? ` companies=${companies.join(",")}` : ""} runtime=${runtimeLabel}${worker ? ` worker=${worker.id} company=${worker.company ?? "-"}` : ""} memory=${memoryMode}`);
     const created_ = {
         outcome: "created",
         role: localBotRole(config),
@@ -895,7 +968,9 @@ async function runBotCreateLocked(name, opts) {
         agentUid,
         kind,
         companies,
-        runtime,
+        runtime: runtimeLabel,
+        engine: fleetInstallation?.engine ?? null,
+        profile: fleetProfile,
         dir,
         worker: worker ? path.join(hqRoot, worker.path) : scaffold.dir,
         workerId: worker?.id ?? null,
@@ -906,15 +981,15 @@ async function runBotCreateLocked(name, opts) {
         intro: intro ?? null,
         kickoff: kickoff ?? null,
         model: model ?? null,
-        effort: effort ?? DEFAULT_BOT_EFFORT,
+        effort: fleetInstallation ? null : effort ?? DEFAULT_BOT_EFFORT,
     };
     let daemonMessage = null;
-    if (opts.daemon !== false && process.platform === "darwin") {
+    if (!fleetInstallation && 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.green(`Created bot ${chalk.bold(name)}`) + chalk.dim(` (${agentUid}, ${runtimeLabel})`));
         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)}`));
@@ -922,9 +997,17 @@ async function runBotCreateLocked(name, opts) {
             console.log(chalk.dim(`  worker: ${scaffold.dir}`));
         console.log(chalk.dim(`  memory: ${scaffold.memoryDir} (${memoryMode})`));
         console.log(chalk.dim(`  state:  ${dir}`));
+        if (fleetProfile)
+            console.log(chalk.dim(`  profile: ${fleetProfile}`));
         if (daemonMessage)
             console.log(chalk.dim(`  ${daemonMessage}`));
     }
+    if (fleetInstallation) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, name, ...created_, daemon: null, running: fleetBootstrap?.running ?? false }, null, 2));
+        }
+        return;
+    }
     if (opts.start !== false) {
         if (daemonMessage && /loaded\)/.test(daemonMessage)) {
             // RunAtLoad already started it.
@@ -1028,6 +1111,9 @@ async function runBotResident(nameArg) {
     const name = validateBotName(nameArg);
     const dir = botDir(name);
     const config = readBotConfig(dir);
+    if (config && isFleetRuntimeBot(config)) {
+        throw Object.assign(new Error(`${name} runs on the HQ Fleet Runtime under its own background service. Use hq bot start ${name}, hq bot status ${name} or hq bot logs ${name}.`), { expected: true });
+    }
     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
@@ -1127,7 +1213,11 @@ async function runBotList(opts) {
     }
 }
 async function runBotStatus(nameArg, opts) {
-    const { name, dir } = requireBot(nameArg);
+    const { name, dir, config } = requireBot(nameArg);
+    if (isFleetRuntimeBot(config)) {
+        runFleetRuntimeControl(name, config, "status", opts.json === true);
+        return;
+    }
     const row = rowFor(name);
     await decorateOnline([row]);
     const status = readBotStatus(dir);
@@ -1326,6 +1416,15 @@ async function runBotRmOrphan(name, opts) {
     else
         console.log(chalk.dim(`  HQ may still have a bot named "${name}". Remove that too with: hq bot rm ${name} --remote`));
 }
+function stopFleetRuntimeBotQuietly(agentUid) {
+    try {
+        controlFleetLocalBot(agentUid, "stop");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function runBotRm(nameArg, opts) {
     const validated = validateBotName(nameArg);
     // Under the bot's lock: an rm racing a create, adopt or restore of the same
@@ -1348,9 +1447,13 @@ async function runBotRmLocked(validated, opts) {
             return;
         }
     }
-    await stopBot(name, dir, config, "silent").catch(() => { });
-    const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
-    const daemon = uninstallBotDaemon(paths, daemonDeps());
+    if (isFleetRuntimeBot(config))
+        stopFleetRuntimeBotQuietly(config.agentUid);
+    else
+        await stopBot(name, dir, config, "silent").catch(() => { });
+    const daemon = isFleetRuntimeBot(config)
+        ? { message: "managed by HQ Fleet Runtime" }
+        : uninstallBotDaemon(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot }), daemonDeps());
     const token = await ownerToken();
     const api = new BotApi({ token: async () => token });
     let identity;
@@ -1380,8 +1483,11 @@ async function runBotRmLocked(validated, opts) {
     // 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)
+    if (localStateRemoved) {
+        if (isFleetRuntimeBot(config))
+            removeFleetLocalBot(config.agentUid);
         fs.rmSync(dir, { recursive: true, force: true });
+    }
     const message = incomplete
         ? `HQ removed what it could of "${name}", but ${incomplete.detail}.` +
             (incomplete.retryable
@@ -1572,6 +1678,10 @@ export function botExists(name) {
 /** `hq bot restart <name>`: stop, then start (launchd when installed). */
 export async function runBotRestart(nameArg, opts = {}) {
     const b = requireBot(nameArg);
+    if (isFleetRuntimeBot(b.config)) {
+        runFleetRuntimeControl(b.name, b.config, "restart", opts.json === true || opts.output === "json");
+        return;
+    }
     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
@@ -1581,6 +1691,30 @@ export async function runBotRestart(nameArg, opts = {}) {
     await stopBot(b.name, b.dir, b.config, "silent");
     await startBot(b.name, b.dir, b.config, opts.output ?? (opts.json ? "json" : "text"));
 }
+async function runBotAuth(nameArg, opts) {
+    const b = requireBot(nameArg);
+    if (!isFleetRuntimeBot(b.config)) {
+        throw Object.assign(new Error(`hq bot auth is for bots created with --hq-fleet-runtime. ${b.name} uses ${b.config.runtime}.`), { expected: true });
+    }
+    const apiKey = opts.apiKey ? fs.readFileSync(0, "utf8").trim() : undefined;
+    if (opts.apiKey && !apiKey) {
+        throw Object.assign(new Error("No API key was received on stdin."), { expected: true });
+    }
+    const result = authenticateFleetLocalBot({
+        agentUid: b.config.agentUid,
+        provider: opts.provider,
+        ...(opts.model ? { model: opts.model } : {}),
+        ...(apiKey ? { apiKey } : {}),
+        ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
+        ...(opts.transport ? { transport: opts.transport } : {}),
+        openBrowser: opts.browser !== false,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, name: b.name, runtime: HQ_FLEET_RUNTIME_ENGINE_ID, ...result }, null, 2));
+        return;
+    }
+    console.log(chalk.green(`${b.name} is signed in to ${result.provider} and running ${result.model}.`));
+}
 // ── 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
@@ -2090,6 +2224,7 @@ async function runBotListRemote(opts) {
             reason: runnable.reason,
             displayName: remoteBotDisplayName(bot, name),
             role: remoteBotRole(bot),
+            ownerUid: bot.ownerUid ?? null,
         };
     });
     if (opts.json) {
@@ -2124,7 +2259,13 @@ export function registerBotCommand(program) {
         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 result = await promoteLocalBot({
+            dir,
+            config,
+            companyUid: opts.company,
+            api,
+            ...(isFleetRuntimeBot(config) ? { runtime: fleetLocalPromotionRuntime(config.agentUid) } : {}),
+        });
         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 } : {}) }));
@@ -2140,7 +2281,8 @@ export function registerBotCommand(program) {
         .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("--runtime <runtime>", `Model CLI to run the bot with: ${BOT_RUNTIMES.join("|")}`)
+        .option("--hq-fleet-runtime", "Create this personal bot with the local HQ Fleet Runtime")
         .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)")
@@ -2196,6 +2338,10 @@ export function registerBotCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(async () => {
         const b = requireBot(name);
+        if (isFleetRuntimeBot(b.config)) {
+            runFleetRuntimeControl(b.name, b.config, "start", opts.json === true);
+            return;
+        }
         await startBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
     })());
     bot
@@ -2204,6 +2350,10 @@ export function registerBotCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action((name, opts) => wrap(async () => {
         const b = requireBot(name);
+        if (isFleetRuntimeBot(b.config)) {
+            runFleetRuntimeControl(b.name, b.config, "stop", opts.json === true);
+            return;
+        }
         await stopBot(b.name, b.dir, b.config, opts.json ? "json" : "text");
     })());
     bot
@@ -2216,6 +2366,17 @@ export function registerBotCommand(program) {
         .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("auth <name>")
+        .description("Sign a runtime-backed personal bot in to ChatGPT, Grok, Claude, or another supported provider")
+        .requiredOption("--provider <provider>", "Provider: chatgpt, grok, claude, or a runtime provider id")
+        .option("--model <model>", "Model id; required for providers without a built-in personal-bot default")
+        .option("--api-key", "Read an API key from stdin instead of starting device authorization")
+        .option("--base-url <url>", "Provider API base URL; required for custom runtime providers")
+        .option("--transport <transport>", "Provider transport: chat_completions, anthropic_messages, or codex_responses")
+        .option("--no-browser", "Do not open a browser during device authorization")
+        .option("--json", "Print machine-readable JSON")
+        .action((name, opts) => wrap(() => runBotAuth(name, opts))());
     bot
         .command("logs <name>")
         .description("Show the bot's log")

package/dist/commands/cloud.d.ts

@@ -14,6 +14,7 @@
  */
 import { Command } from "commander";
 import { type ConflictStrategy, type EntityContext, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant, type ShareOptions, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { withSyncWatchdog, type SyncWatchdogLimits } from "../utils/sync-watchdog.js";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 import { type PlanLimitRefusalSummary } from "../lib/billing/plan-limit-refusals.js";
 /**
@@ -45,7 +46,54 @@ export declare class SyncExitError extends Error {
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
-export declare function formatSyncFailure(err: unknown): string;
+export declare function formatSyncFailure(err: unknown, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string;
+/**
+ * The `.hqinclude` line that admits a named path: its HQ-relative spelling,
+ * with a trailing slash for a folder. Resolved the way the push resolver
+ * reads a named path (absolute, HQ root, the company folder, then the current
+ * directory); a path that resolves nowhere inside the HQ tree is suggested as
+ * typed.
+ */
+export declare function hqincludeEntryFor(namedPath: string, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string;
+/**
+ * Re-render hq-cloud's UnreachablePushPathsError with the real blocker per
+ * path (feedback_6afa6ce4). The upstream message always ends with advice
+ * about symlinks, so a path left out of `.hqinclude` read as a symlink
+ * problem. This names the `.hqinclude` line to add, and keeps the symlink
+ * advice only for reasons that are about links or paths outside the company
+ * folder. Returns null for any other error.
+ */
+export declare function formatUnreachablePushPaths(err: unknown, ctx?: {
+    hqRoot?: string;
+    cwd?: string;
+    companySlug?: string;
+}): string | null;
+/**
+ * Lines naming the blocker when a push with user-named paths uploaded nothing
+ * and every not-uploaded file fell outside write scope (feedback_5baccb9e).
+ * The summary before this gave a count and the granted prefixes; this names
+ * each requested path as the thing no write grant covers and points at
+ * `hq access`, which reports the ACL row that blocks it.
+ */
+export declare function explicitPushBlockedLines(input: {
+    userNamedPaths: boolean;
+    namedPaths: readonly string[];
+    filesUploaded: number;
+    filesExcludedByScope: number;
+    otherNotUploaded: number;
+    prefixSet: readonly string[] | undefined;
+    hqRoot: string;
+    cwd?: string;
+    companySlug?: string;
+}): string[];
 /**
  * US-003: run one sync fanout under a client-health attempt/outcome report.
  * The report is best-effort, bounded, and swallowed — it can only append a
@@ -128,6 +176,15 @@ export declare function scopeExcludedPrefixDetail(prefixSet: readonly string[] |
  * folder foo/ — and grant advice would point the reader the wrong way.
  */
 export declare function scopeExcludedLines(count: number, prefixSet: readonly string[] | undefined): string[];
+/**
+ * feedback_b7c00a62: run a `sync now` runner under the watchdog (see
+ * `utils/sync-watchdog.ts` for the limits). A timeout prints a clear message
+ * and unwinds as a failed {@link SyncExitError}, so {@link withSyncHealthReport}
+ * records the failure and exits 124. The failure report gets at most
+ * {@link SYNC_WATCHDOG_REPORT_GRACE_MS}; after that the process exits 124
+ * regardless, and the worker backstop stays armed behind both.
+ */
+export declare function runUnderSyncWatchdog<T>(limits: SyncWatchdogLimits, label: string, run: () => Promise<T>, watchdog?: typeof withSyncWatchdog, exit?: (code: number) => void): Promise<T>;
 /**
  * Bound foreground waits for a watcher/manual sync that currently owns the
  * per-root operation lock. The cloud engine reads this environment value on