@indigoai-us/hq-cli 5.345.169 → 5.345.171

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

@@ -26,6 +26,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  * list (online flag), and rm. Secrets are never printed.
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
+import { DecisionsClient } from "../lib/decisions/client.js";
 import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
 import { preloadResidentPackageModules, reportResidentPackagePreloadFailure, runResidentCommandWithPackageLease, } from "../utils/resident-package-preload.js";
 import { followLogFile } from "../lib/log-follow.js";
@@ -51,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, controlFleetLocalBot, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, removeFleetLocalBot, } from "../lib/bot/index.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -113,6 +114,18 @@ function requireBot(name) {
     }
     return { name: valid, dir, config };
 }
+function isFleetRuntimeBot(config) {
+    return config.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID;
+}
+function runFleetRuntimeControl(name, config, action, json) {
+    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);
@@ -604,6 +617,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 });
@@ -639,6 +656,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 });
@@ -653,6 +675,9 @@ async function runBotCreateLocked(name, opts) {
             expected: true,
         });
     }
+    const fleetInstallation = useFleetRuntime
+        ? await installPinnedFleetLocalDistribution()
+        : null;
     const token = await ownerToken();
     const owner = await resolveCallerPersonUid(token, undefined, { command: "hq bot create" });
     if (!owner)
@@ -762,6 +787,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 } : {}),
@@ -828,6 +854,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: [] } : {}),
@@ -884,8 +911,20 @@ 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);
+    const fleetBootstrap = fleetInstallation
+        ? bootstrapFleetLocalBot({
+            agentUid,
+            ownerUid: config.ownerUid,
+            hqRoot,
+            botDir: dir,
+            installation: fleetInstallation,
+            machineCredentials: botCredsPath(dir),
+        }, { start: opts.start !== false })
+        : 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),
@@ -894,7 +933,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,
@@ -905,15 +946,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)}`));
@@ -921,9 +962,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.
@@ -1063,6 +1112,9 @@ async function runBotResident(nameArg) {
         api,
         runtime: runtimeFor(config.runtime),
         ownerContext: () => owner.get(),
+        // US-005: decision picks in the owner DM, with the bot's own machine token
+        // (never the owner's login).
+        decisions: new DecisionsClient(token),
         // Chat attachments are fetched with the bot's own machine identity against
         // the same API its inbox and posts use (BotApi has no baseUrl override either).
         downloadAttachment: createVaultObjectDownloader({ getToken: token }),
@@ -1123,7 +1175,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);
@@ -1322,6 +1378,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
@@ -1344,9 +1409,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;
@@ -1376,8 +1445,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
@@ -1568,6 +1640,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
@@ -1577,6 +1653,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
@@ -2086,6 +2186,7 @@ async function runBotListRemote(opts) {
             reason: runnable.reason,
             displayName: remoteBotDisplayName(bot, name),
             role: remoteBotRole(bot),
+            ownerUid: bot.ownerUid ?? null,
         };
     });
     if (opts.json) {
@@ -2120,7 +2221,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 } : {}) }));
@@ -2136,7 +2243,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)")
@@ -2192,6 +2300,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
@@ -2200,6 +2312,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
@@ -2212,6 +2328,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
@@ -67,6 +115,26 @@ export declare function withSyncHealthReport<T>(run: () => Promise<T>): Promise<
  */
 export declare function scopeExcludedExitCode(count: number): 0 | 1;
 export declare function scopeExcludedWarning(count: number): string | null;
+/**
+ * Counts the files share() held back because this sync scope is fenced after an account
+ * switch on this computer (feedback_a69e12ba). share() reports the hold only as
+ * an `identity-switch-push-held` event and leaves the files out of every
+ * result counter, so without this the push printed "Pushed 0 file(s) (0 B,
+ * 0 skipped)" as a success while the vault kept the old copy.
+ *
+ * Each event carries the size of one fenced hold, so the tracker keeps the
+ * largest count it sees instead of a sum: a repeated emit for the same hold
+ * cannot inflate the total. A missing, non-numeric or negative count reads as 0.
+ */
+export declare function createIdentityHeldTracker(): {
+    observe: (event: {
+        type: string;
+        count?: unknown;
+    }) => void;
+    count: () => number;
+};
+/** Recovery lines for files held by the account-switch push fence. */
+export declare function identityHeldLines(count: number): string[];
 /** Actionable recovery for files refused because the vault baseline is stale. */
 export declare function staleUploadRefusalLines(count: number, paths?: readonly string[]): string[];
 /**
@@ -108,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