@indigoai-us/hq-cli 5.345.199 → 5.345.201

package/dist/commands/bot.js

@@ -1,5 +1,8 @@
 import { withLocalJobs } from "../lib/bot/local-jobs.js";
-import { fleetMoveFailurePath, fleetMoveRecentlyFailed, legacyConversionDecision, writeFleetMoveFailure } from "../lib/bot/legacy-convert.js";
+import { clearFleetMoveRecords, fleetMoveHoldPath, fleetMoveRecentlyFailed, holdReportDue, legacyConversionDecision, legacyHoldFailureReport, legacyHoldNotice, legacyHoldNotifiesOwner, legacyMoveState, ownerHoldNoticeDue, readFleetMoveFailure, readFleetMoveHold, writeFleetMoveFailure, writeFleetMoveHold, } from "../lib/bot/legacy-convert.js";
+import { legacyProviderLoginProbe } from "../lib/bot/legacy-provider-login.js";
+import { randomUUID } from "node:crypto";
+import { CLI_VERSION } from "../cli-version.js";
 import { runSignals } from "../lib/signals/engine.js";
 import { BOT_SIGNALS_ENGINE_JOB_FLAG, signalsEngineForJob } from "../lib/bot/signals-engine-flag.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
@@ -70,7 +73,9 @@ import { unresolvedLastFailure } from "../lib/doctor/checks/bots.js";
 import { classifyRuntimeFailure, runtimeFailureReason } from "../lib/bot/runtime-failure.js";
 import { PROBE_DEFAULT_TIMEOUT_MS, probeBotRuntime } from "../lib/bot/probe.js";
 import { BOT_LOGIN_RUNTIMES, botAuthEnv, botRuntimeAuth, capacityAccountHome, describeBotAuth, formatBotAuth, isBotLoginRuntime, restoreBotSessions, setAsideBotSessions, signInBotRuntime, signOutBotRuntime, withRuntimeAuth, } from "../lib/bot/runtime-auth.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, HQ_FLEET_LOCAL_RELEASE, authenticateFleetLocalBot, bootstrapFleetLocalBot, buildSystemPrompt, controlFleetLocalBot, ensureFleetPython, fleetLocalGatewayPid, fleetLocalProfileNeedsAdoption, fleetLocalServiceInstalled, fleetProviderForRuntime, importFleetLocalMachineCredential, fleetProviderNeedsSignIn, fleetOwnerCompanies, refreshFleetLocalInstructions, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, installTargetFleetLocalDistribution, resolveFleetLocalPointerTarget, resolveFleetLocalTargetRelease, fleetLocalProfileDir, fleetProfileOwnerCompanies, fleetLocalChannels, readFleetLocalGatewayState, 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, HQ_FLEET_LOCAL_RELEASE, authenticateFleetLocalBot, bootstrapFleetLocalBot, buildSystemPrompt, controlFleetLocalBot, ensureFleetPython, fleetLocalGatewayPid, fleetLocalProfileNeedsAdoption, fleetLocalServiceInstalled, fleetProviderForRuntime, importFleetLocalMachineCredential, importFleetLocalProviderLogin, fleetProviderNeedsSignIn, fleetOwnerCompanies, refreshFleetLocalInstructions, fleetLocalPromotionRuntime, installPinnedFleetLocalDistribution, installTargetFleetLocalDistribution, resolveFleetLocalPointerTarget, resolveFleetLocalTargetRelease, fleetLocalProfileDir, fleetProfileOwnerCompanies, fleetLocalChannels, readFleetLocalGatewayState, readPromptSources, removeFleetLocalBot, } from "../lib/bot/index.js";
+import { gatedInteractiveLogin } from "../utils/interactive-caller.js";
+import { fleetInstallProgressReporter, runBotRuntimeInstall, runBotRuntimeStatus } from "./bot-runtime.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -332,7 +337,15 @@ export function botTokenSupplier(dir) {
     process.env.HQ_MACHINE_TOKEN_STATE_DIR = botTokenStateDir(dir);
     return () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
 }
-async function ownerToken(interactive = process.stdin.isTTY === true) {
+/**
+ * Whether `hq bot` may open a browser sign-in for its owner: a TTY on stdin,
+ * and the shared interactive-caller gate (no lane, daemon, bot runtime, or
+ * HQ_NO_BROWSER_LOGIN child).
+ */
+export function ownerSignInAllowed() {
+    return gatedInteractiveLogin(process.stdin.isTTY === true);
+}
+async function ownerToken(interactive = ownerSignInAllowed()) {
     if (peekHqApiKey()) {
         throw Object.assign(new Error("hq bot needs your HQ login session (HQ_API_KEY is not supported here). Run `hq login`."), {
             expected: true,
@@ -358,11 +371,39 @@ export function runtimeSignedIn(status, processAlive) {
         return false;
     return status.runtimeSignInCheck?.signedIn ?? null;
 }
+/**
+ * Whether the bot's model provider must be signed in before it can run, from
+ * what this computer knows: the bot's settings, its last reported failure or
+ * sign-in check, and (legacy) why it has not moved to the HQ Fleet Runtime.
+ */
+export function brainSignInFor(name, config, status, legacy) {
+    const provider = config.runtime;
+    const command = fleetAuthCommand(name, config);
+    if (legacy && !legacy.decision.convert && legacyHoldNotifiesOwner(legacy.decision.reason)) {
+        return { provider, needed: true, reason: legacy.notice?.cause ?? legacy.decision.detail, command };
+    }
+    if (config.fleetAuthPending === true)
+        return { provider, needed: true, reason: `${name} has not signed in to ${runtimeDisplayName(provider)} yet.`, command };
+    // A legacy bot that moves at its next start needs no sign-in, whatever its old runner last reported.
+    if (legacy?.decision.convert)
+        return null;
+    const failure = unresolvedLastFailure(status);
+    if (failure?.class === "auth")
+        return { provider, needed: true, reason: failure.cause, command };
+    if (status?.runtimeSignIn)
+        return { provider, needed: true, reason: signedOutReason(name, status.runtimeSignIn), command };
+    return null;
+}
+function signedOutReason(name, issue) {
+    const tool = runtimeDisplayName(issue.runtime);
+    return issue.state === "signed-out" ? `${tool} is not signed in for ${name} on this computer.` : `${tool} needs ${name}'s owner to sign in again on this computer.`;
+}
 function rowFor(name, opts = {}) {
     const dir = botDir(name);
     const config = readBotConfig(dir);
     const fleet = isFleetRuntimeBot(config);
     const status = readBotStatus(dir);
+    const legacy = fleet ? null : opts.legacy ?? legacyMoveState(dir, config, legacyConvertSeams.providerLogin(dir, config));
     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.
@@ -409,6 +450,8 @@ function rowFor(name, opts = {}) {
         ...(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),
+        brainSignIn: brainSignInFor(name, config, status, legacy),
+        ...(legacy ? { legacy: legacyStatusJson(legacy) } : {}),
         runtimeCrash: processAlive ? runtimeCrashSinceStart(status) : null,
         daemonInstalled,
         daemonLoaded,
@@ -515,9 +558,12 @@ async function startBot(name, dir, config, output, extra = {}, opts = {}) {
         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);
-    const converted = opts.keepLegacy ? null : await convertLegacyBotToFleet(name, dir, config, "start");
-    if (converted)
-        return reportFleetBotStart(name, dir, converted, output, { ...extra, movedToFleet: true }, true, "started by the HQ Fleet Runtime");
+    const move = opts.keepLegacy ? null : await convertLegacyBotToFleet(name, dir, config, "start");
+    if (move?.fleet)
+        return reportFleetBotStart(name, dir, move.fleet, output, { ...extra, movedToFleet: true }, true, "started by the HQ Fleet Runtime");
+    // The app reads these to say the bot is still legacy and, when a sign-in is all it waits for, to offer it.
+    if (move?.state)
+        extra = { ...extra, movedToFleet: false, legacy: legacyStatusJson(move.state), brainSignIn: brainSignInFor(name, config, readBotStatus(dir), move.state) };
     if (config.enabled === false)
         patchBotConfig(dir, { enabled: true });
     const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
@@ -594,21 +640,37 @@ async function startBot(name, dir, config, output, extra = {}, opts = {}) {
  * itself starting (launchd, hq daemon or a detached run), before it polls:
  * its own startup agent is booted out last, detached.
  */
+/** Seams for the legacy move, replaced in tests. */
+export const legacyConvertSeams = {
+    /** Whether the provider sign-in a Codex or Grok legacy bot needs is readable here, as HQ Fleet Local imports it. */
+    providerLogin: (dir, config) => legacyProviderLoginProbe(dir, config),
+};
 async function convertLegacyBotToFleet(name, dir, config, from) {
-    if (!legacyConversionDecision(config).convert || hasPromotionHold(dir))
-        return null;
-    // A launchd or daemon restart loop would otherwise retry a failing install before every start.
+    if (hasPromotionHold(dir))
+        return { fleet: null, state: null };
+    // A launchd or daemon restart loop would otherwise retry a failing install (and probe the sign-in) before every start.
     if (from === "run" && fleetMoveRecentlyFailed(dir))
-        return null;
+        return { fleet: null, state: null };
+    const probe = legacyConvertSeams.providerLogin(dir, config);
+    const decision = legacyConversionDecision(config, process.env, probe);
+    if (!decision.convert) {
+        if (legacyHoldNotifiesOwner(decision.reason))
+            await holdLegacyBot(name, dir, config, decision);
+        return { fleet: null, state: { decision, notice: legacyHoldNotice(name, config.runtime, decision), lastFailure: readFleetMoveFailure(dir), hold: readFleetMoveHold(dir) } };
+    }
+    // The hold is over: whatever stops the move from here is a failure, not a hold.
+    fs.rmSync(fleetMoveHoldPath(dir), { force: true });
+    const ready = () => ({ fleet: null, state: { decision, notice: null, lastFailure: readFleetMoveFailure(dir), hold: null } });
     if (from === "start") {
         const running = readBotStatus(dir);
         if (running && isPidAlive(running.pid) && selfStopProbe(running.pid))
-            return null;
+            return ready();
     }
     const log = createBotLogger(dir);
     const keepLegacy = (step, err) => {
-        writeFleetMoveFailure(dir);
-        log("warn", `could not ${step} ${name} on the HQ Fleet Runtime (${err instanceof Error ? err.message : String(err)}); it runs on ${config.runtime} this time and tries again at its next start`);
+        const error = err instanceof Error ? err.message : String(err);
+        writeFleetMoveFailure(dir, new Date(), { step, error });
+        log("warn", `could not ${step} ${name} on the HQ Fleet Runtime (${error}); it runs on ${config.runtime} this time and tries again at its next start`);
     };
     let engine;
     try {
@@ -618,9 +680,27 @@ async function convertLegacyBotToFleet(name, dir, config, from) {
     }
     catch (err) {
         keepLegacy("install", err);
-        return null;
+        return ready();
     }
-    const fleet = { ...(readBotConfig(dir) ?? config), engine, enabled: true, fleetServiceInstallPending: false };
+    if (decision.signIn) {
+        try {
+            importFleetLocalProviderLogin(config.agentUid, decision.signIn.runtime, {}, decision.signIn.env ? { env: decision.signIn.env } : {});
+            log("info", `imported ${name}'s ${config.runtime} sign-in from this computer for the HQ Fleet Runtime`);
+        }
+        catch (err) {
+            keepLegacy("sign in", err);
+            return ready();
+        }
+    }
+    const current = readBotConfig(dir) ?? config;
+    const fleet = {
+        ...current,
+        engine,
+        enabled: true,
+        fleetServiceInstallPending: false,
+        // The imported login is the bot's Fleet sign-in now; the legacy own-login setting no longer applies.
+        ...(decision.signIn?.env ? { runtimeAuth: withRuntimeAuth(current.runtimeAuth, decision.signIn.runtime, null) } : {}),
+    };
     if (from === "start")
         await stopBot(name, dir, config, "silent");
     let failure = null;
@@ -641,16 +721,77 @@ async function convertLegacyBotToFleet(name, dir, config, from) {
             /* nothing was running */
         }
         keepLegacy("start", failure);
-        return null;
+        return ready();
     }
     writeBotConfig(dir, fleet);
-    fs.rmSync(fleetMoveFailurePath(dir), { force: true });
+    clearFleetMoveRecords(dir);
     // The legacy runner's copy of the machine credentials goes only now: a failed move above still needs it.
     fs.rmSync(botCredsPath(dir), { force: true });
     log("info", `moved ${name} to the HQ Fleet Runtime under the same identity; its ${config.runtime} runner is retired`);
     syncFleetRuntimeJobs(name, dir, fleet);
     retireLegacyBotAgent(name, dir, config, from === "run" ? "detached" : "inline");
-    return fleet;
+    return { fleet, state: null };
+}
+/**
+ * A legacy bot that cannot move yet: record why, and tell the owner once per
+ * reason through the bot's own DM, the way a Fleet bot reports a failed turn.
+ * The record is what `hq bot status` and `hq doctor` show.
+ */
+async function holdLegacyBot(name, dir, config, decision) {
+    const log = createBotLogger(dir);
+    const notice = legacyHoldNotice(name, config.runtime, decision);
+    const previous = readFleetMoveHold(dir);
+    const now = new Date().toISOString();
+    const hold = {
+        reason: decision.reason,
+        detail: decision.detail,
+        at: now,
+        ...(previous?.notifiedAt ? { notifiedAt: previous.notifiedAt } : {}),
+        ...(previous?.notifiedReason ? { notifiedReason: previous.notifiedReason } : {}),
+        ...(previous?.reportId ? { reportId: previous.reportId } : {}),
+        ...(previous?.reportedReason ? { reportedReason: previous.reportedReason } : {}),
+    };
+    writeFleetMoveHold(dir, hold);
+    log("warn", `${name} stays on its ${config.runtime} runner: ${notice.cause} ${notice.fix}`);
+    const reportDue = holdReportDue(previous, decision.reason);
+    const noticeDue = ownerHoldNoticeDue(previous, decision.reason);
+    if (!reportDue && !noticeDue)
+        return;
+    const api = new BotApi({ token: botTokenSupplier(dir) });
+    // One failure report per reason, the same route a Fleet bot files a failed turn through, so stuck legacy bots are visible in HQ.
+    if (reportDue) {
+        try {
+            const report = legacyHoldFailureReport({
+                reportId: randomUUID(),
+                createdAt: now,
+                name,
+                config,
+                decision,
+                notice,
+                machine: os.hostname().trim(),
+                hqCliVersion: CLI_VERSION,
+                os: `${process.platform} ${os.release()}`,
+                logPath: botLogPath(dir),
+            });
+            const { reportId } = await api.reportFailure(config.agentUid, report);
+            Object.assign(hold, { reportedReason: decision.reason, ...(reportId ? { reportId } : {}) });
+            writeFleetMoveHold(dir, hold);
+            log("info", `filed a failure report with HQ for ${name}'s held move (${decision.reason}${reportId ? `, report ${reportId}` : ""})`);
+        }
+        catch (err) {
+            log("warn", `could not file ${name}'s held move with HQ (${err instanceof Error ? err.message : String(err)}); the next start tries again`);
+        }
+    }
+    if (!noticeDue)
+        return;
+    try {
+        await api.sendDm({ toPersonUid: config.ownerUid, body: `${notice.cause} ${notice.fix}` });
+        writeFleetMoveHold(dir, { ...hold, notifiedAt: now, notifiedReason: decision.reason });
+        log("info", `told the owner once that ${name} has not moved to the HQ Fleet Runtime (${decision.reason})`);
+    }
+    catch (err) {
+        log("warn", `could not tell the owner why ${name} has not moved to the HQ Fleet Runtime (${err instanceof Error ? err.message : String(err)}); the next start tries again`);
+    }
 }
 /** Remove a legacy bot's own startup agent once the bot runs on the HQ Fleet Runtime. True when there was one. */
 function retireLegacyBotAgent(name, dir, config, bootout) {
@@ -735,9 +876,10 @@ async function installFleetRuntimeProfile(name, dir, config, opts = {}) {
         return null;
     if (!opts.force && !fleetLocalProfileNeedsAdoption(config.agentUid, { release: target.release }))
         return null;
+    const progress = opts.progress ?? fleetInstallProgressReporter("silent");
     let installation;
     try {
-        installation = await installTargetFleetLocalDistribution({ target });
+        installation = await installTargetFleetLocalDistribution({ target, onProgress: progress });
     }
     catch (err) {
         if (target.source !== "pointer")
@@ -749,8 +891,9 @@ async function installFleetRuntimeProfile(name, dir, config, opts = {}) {
         createBotLogger(dir)("warn", `could not install HQ Fleet Local ${target.release.version} (${err instanceof Error ? err.message : String(err)}); staying on ${HQ_FLEET_LOCAL_RELEASE.version}`);
         if (!opts.force && !fleetLocalProfileNeedsAdoption(config.agentUid, { release: HQ_FLEET_LOCAL_RELEASE }))
             return null;
-        installation = await installPinnedFleetLocalDistribution();
+        installation = await installPinnedFleetLocalDistribution({ onProgress: progress });
     }
+    progress({ phase: "python" });
     const python = await ensureFleetPython();
     const companyScope = effectiveBotKind(config) === "company"
         ? effectiveBotCompanies(config)
@@ -765,7 +908,7 @@ async function installFleetRuntimeProfile(name, dir, config, opts = {}) {
         provider: fleetProviderForRuntime(config.runtime, config.model),
         ownerCompanies: companyScope,
         ...(config.autoApprove === true ? { autoApprove: true } : {}),
-    }, { python, start: false });
+    }, { python, start: false, onProgress: progress });
     const credentials = botCredsPath(dir);
     if (fs.existsSync(credentials))
         importFleetLocalMachineCredential(config.agentUid, credentials, {}, { keepSource: opts.keepCredentials === true });
@@ -1228,7 +1371,9 @@ async function runBotCreateLocked(name, opts) {
     // of sending another create that the entity store will reject.
     if (isSetupBot && (await adoptOwnedSetupBot(true)))
         return;
-    const fleetInstallation = await installTargetFleetLocalDistribution();
+    const progress = fleetInstallProgressReporter(opts.json ? "silent" : "text");
+    const fleetInstallation = await installTargetFleetLocalDistribution({ onProgress: progress });
+    progress({ phase: "python" });
     const fleetPython = await ensureFleetPython();
     const ownerCompanies = kind === "personal" ? await fleetOwnerCompanies() : companies;
     // A company bot's companies are resolved first (a typo must not cost an
@@ -1388,7 +1533,7 @@ async function runBotCreateLocked(name, opts) {
         firstStart: toolOffer
             ? { intro: setupToolOfferText(toolOffer, setupWelcomeOpening(intro)) }
             : { intro: introText, ...(kickoff ? { kickoff } : {}) },
-    }, { start: opts.start !== false && !fleetAuthPending, python: fleetPython });
+    }, { start: opts.start !== false && !fleetAuthPending, python: fleetPython, onProgress: progress });
     syncFleetRuntimeJobs(name, dir, config);
     const fleetProfile = fleetBootstrap.profile;
     const runtimeLabel = HQ_FLEET_RUNTIME_ENGINE_ID;
@@ -1562,7 +1707,7 @@ async function runBotResident(nameArg) {
             console.log(orphanBotRunMessage(name, outcome));
         return;
     }
-    if (await convertLegacyBotToFleet(name, dir, config, "run"))
+    if ((await convertLegacyBotToFleet(name, dir, config, "run")).fleet)
         return;
     if (healNodePathFromJob(name, dir, config))
         return;
@@ -1680,18 +1825,28 @@ async function runBotList(opts) {
 async function runBotStatus(nameArg, opts) {
     const { name, dir, config } = requireBot(nameArg);
     const fleet = isFleetRuntimeBot(config);
-    const row = rowFor(name);
+    const legacy = fleet ? null : legacyMoveState(dir, config, legacyConvertSeams.providerLogin(dir, config));
+    const row = rowFor(name, { legacy });
     await decorateOnline([row]);
     const status = readBotStatus(dir);
     const creds = readBotCredsIdentity(dir);
     const channels = fleet ? fleetLocalChannels(readFleetLocalGatewayState(config.agentUid), row.processAlive) : null;
     if (opts.json) {
-        console.log(JSON.stringify({ ...row, executive: executiveStatus(config, dir), ...(fleet ? { engine: config.engine, channels } : {}), credsPresent: fleet || !!creds, login: describeBotAuth(dir, config), status }, null, 2));
+        console.log(JSON.stringify({
+            ...row,
+            executive: executiveStatus(config, dir),
+            ...(fleet ? { engine: config.engine, channels } : {}),
+            credsPresent: fleet || !!creds,
+            login: describeBotAuth(dir, config),
+            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`)}`);
+    else
+        console.log(`  engine:     ${chalk.yellow(`legacy ${runtimeDisplayName(config.runtime)} runner (not on the HQ Fleet Runtime)`)}`);
     console.log(`  kind:       ${describeKind(row.kind, row.companies)}`);
     const login = describeBotAuth(dir, config);
     console.log(`  runtime:    ${row.runtime}  model ${row.model ?? "default"}  thinking ${row.effort}${row.effortIsDefault ? " (default)" : ""}`);
@@ -1718,6 +1873,10 @@ async function runBotStatus(nameArg, opts) {
     else {
         console.log(`  launchd:    ${row.daemonInstalled ? (row.daemonLoaded ? "installed, loaded" : "installed, not loaded") : "not installed"}`);
     }
+    if (legacy) {
+        for (const line of legacyStatusLines(name, legacy))
+            console.log(`  ${line}`);
+    }
     if (row.daemonNodeMissing) {
         console.log(`  ${chalk.red(`node missing: ${row.daemonNodeMissing}`)} — launchd cannot start ${name}; fix with: hq bot start ${name}`);
     }
@@ -1767,6 +1926,37 @@ async function runBotStatus(nameArg, opts) {
     }
     console.log(chalk.dim(`  state dir:  ${dir}`));
 }
+/** The `legacy` object in `hq bot status --json` for a bot still on its legacy runner. */
+export function legacyStatusJson(state) {
+    const { decision } = state;
+    return {
+        moves: decision.convert,
+        ...(decision.convert ? {} : { reason: decision.reason, detail: decision.detail, cause: state.notice?.cause ?? null, fix: state.notice?.fix ?? null }),
+        lastMoveFailure: state.lastFailure,
+        ownerNotifiedAt: state.hold?.notifiedAt ?? null,
+        reportId: state.hold?.reportId ?? null,
+    };
+}
+/** The `fleet move:` lines of `hq bot status` for a bot still on its legacy runner. */
+export function legacyStatusLines(name, state) {
+    const lines = [];
+    const { decision } = state;
+    if (decision.convert) {
+        lines.push(`fleet move: ready; it moves to the HQ Fleet Runtime at its next start (hq bot start ${name})`);
+    }
+    else {
+        lines.push(`fleet move: ${chalk.yellow(`held (${decision.reason})`)}: ${state.notice?.cause ?? decision.detail}`);
+        if (state.notice?.fix)
+            lines.push(`  fix:      ${state.notice.fix}`);
+        if (legacyHoldNotifiesOwner(decision.reason))
+            lines.push(chalk.dim(`  owner DM: ${state.hold?.notifiedAt ? `sent ${state.hold.notifiedAt}` : "not sent yet"}`));
+    }
+    if (state.lastFailure) {
+        const f = state.lastFailure;
+        lines.push(`last move:  ${chalk.yellow(`failed ${f.at}${f.step ? ` (could not ${f.step})` : ""}${f.error ? `: ${f.error}` : ""}`)}; it tries again at its next start`);
+    }
+    return lines;
+}
 async function runBotLogs(nameArg, opts) {
     const { dir } = requireBot(nameArg);
     const file = botLogPath(dir);
@@ -2489,6 +2679,7 @@ async function runBotAuth(nameArg, opts) {
     if (legacy && engine) {
         const moved = { ...(readBotConfig(b.dir) ?? legacy), engine };
         writeBotConfig(b.dir, moved);
+        clearFleetMoveRecords(b.dir);
         fs.rmSync(botCredsPath(b.dir), { force: true });
         createBotLogger(b.dir)("info", `moved ${b.name} to the HQ Fleet Runtime with its ${opts.provider} sign-in; its ${legacy.runtime} runner is retired`);
         syncFleetRuntimeJobs(b.name, b.dir, moved);
@@ -2496,8 +2687,11 @@ async function runBotAuth(nameArg, opts) {
     }
     const signedInRuntime = result.runtimeProvider === "anthropic" ? "claude" : result.runtimeProvider === "xai-oauth" ? "grok" : result.runtimeProvider === "openai-codex" ? "codex" : null;
     const pending = b.config.fleetAuthPending === true || legacy !== null;
+    // A moved bot answers with the login it just signed in with; its legacy own-login setting no longer applies.
+    const runtimeAuth = legacy && signedInRuntime && legacy.runtimeAuth?.[signedInRuntime] !== undefined ? withRuntimeAuth(legacy.runtimeAuth, signedInRuntime, null) : undefined;
     patchBotConfig(b.dir, {
         ...(signedInRuntime ? { runtime: signedInRuntime } : {}),
+        ...(legacy && signedInRuntime && legacy.runtimeAuth?.[signedInRuntime] !== undefined ? { runtimeAuth } : {}),
         model: result.model,
         ...(pending ? { fleetAuthPending: false, fleetServiceInstallPending: !result.restarted, enabled: result.restarted } : {}),
     });
@@ -2776,7 +2970,10 @@ async function adoptRemoteBotLocked(input) {
         ...(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 progress = input.progress ?? fleetInstallProgressReporter("silent");
+    const fleetInstallation = fleetEngine ? await installPinnedFleetLocalDistribution({ onProgress: progress }) : null;
+    if (fleetInstallation)
+        progress({ phase: "python" });
     const fleetPython = fleetInstallation ? await ensureFleetPython() : null;
     if (fleetInstallation)
         config.engine = fleetInstallation.engine;
@@ -2805,7 +3002,7 @@ async function adoptRemoteBotLocked(input) {
                     },
                 }
                 : {}),
-        }, { python: fleetPython, start: false });
+        }, { python: fleetPython, start: false, onProgress: progress });
     }
     createBotLogger(dir)("info", `adopted ${name} (${bot.agentUid}) on ${localMachineId()} kind=${config.kind}${local ? "" : " (no saved settings; defaults)"} runtime=${config.runtime}`);
     let daemonMessage = null;
@@ -2870,6 +3067,7 @@ export async function runBotAdopt(nameArg, opts) {
             name,
             api,
             hqRoot,
+            progress: fleetInstallProgressReporter(opts.json ? "silent" : "text"),
             overrides: {
                 ...(isBotRuntimeId(opts.runtime) ? { runtime: opts.runtime } : {}),
                 ...(model ? { model } : {}),
@@ -2983,7 +3181,7 @@ export async function runBotRestore(opts) {
             if (here) {
                 return { name, agentUid: bot.agentUid, action: "repaired", detail: await repairLocalBot(name, api, bot, opts.daemon !== false), ...shown };
             }
-            const { result, config } = await adoptRemoteBot({ bot, name, api, hqRoot, daemon: opts.daemon !== false });
+            const { result, config } = await adoptRemoteBot({ bot, name, api, hqRoot, daemon: opts.daemon !== false, progress: fleetInstallProgressReporter(opts.json ? "silent" : "text") });
             // Silent: this command's own JSON has to be the only document on stdout.
             const started = opts.start === false ? null : await startBot(name, result.dir, config, "silent").catch(() => null);
             return {
@@ -3173,7 +3371,7 @@ export function registerBotCommand(program) {
         const b = requireBot(name);
         if (isFleetRuntimeBot(b.config)) {
             refuseHeldFleetBot(b.dir);
-            const adopted = await adoptFleetRuntimeProfile(b.name, b.dir, b.config);
+            const adopted = await adoptFleetRuntimeProfile(b.name, b.dir, b.config, { progress: fleetInstallProgressReporter(opts.json ? "silent" : "text") });
             runFleetRuntimeControl(b.name, b.config, adopted ? "install" : "start", opts.json === true);
             return;
         }
@@ -3271,6 +3469,17 @@ export function registerBotCommand(program) {
         .command("intro <name>")
         .description("Have the bot re-send its introduction DM to you")
         .action((name) => wrap(() => runBotIntro(name))());
+    const runtime = bot.command("runtime").description("The HQ Fleet Runtime every local bot on this computer shares");
+    runtime
+        .command("install")
+        .description("Download and build the runtime once for this computer, with progress, so creating a bot takes seconds. Safe to run again: a finished install returns at once, an interrupted download continues where it stopped")
+        .option("--json", "Print one JSON object per line: progress events, then { ok, event: \"done\", release, runtimeDir }")
+        .action((opts) => wrap(() => runBotRuntimeInstall(opts))());
+    runtime
+        .command("status")
+        .description("Say whether the runtime is installed on this computer, step by step")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runBotRuntimeStatus(opts))());
     const daemon = bot.command("daemon").description("Manage the bot's launchd user agent (macOS)");
     daemon
         .command("install <name>")

package/dist/commands/cloud.d.ts

@@ -59,10 +59,49 @@ export declare class SyncSessionExpiredError extends Error {
     readonly reason?: string | undefined;
     constructor(kind: "reauth" | "unavailable", reason?: string | undefined);
 }
+/** Shown when the vault rejected the session even after a forced refresh. */
+export declare const SYNC_SESSION_REJECTED_MESSAGE = "The HQ server rejected your session even after it was refreshed, so the saved sign-in is no longer accepted. `hq auth status` only checks the saved expiry, not the server. Run `hq login`, then rerun the sync.";
+/** Reason text when token acquisition does not settle within the bound. */
+export declare const SYNC_TOKEN_TIMEOUT_REASON = "timed out waiting for the sign-in service";
+/** Longest a single token acquisition or refresh may take before the sync fails. */
+export declare const SYNC_TOKEN_TIMEOUT_MS = 45000;
+/**
+ * The vault rejected the session after a forced refresh had already replaced
+ * the saved token. Retrying again cannot help; the user has to sign in again.
+ */
+export declare class SyncSessionRejectedError extends Error {
+    constructor();
+}
 export interface SyncVaultConfigDeps {
     /** Non-interactive token resolver: returns the cached token or refreshes it. */
     ensureToken?: () => Promise<string>;
+    /** Bound on one token acquisition (default {@link SYNC_TOKEN_TIMEOUT_MS}). */
+    tokenTimeoutMs?: number;
 }
+export interface RejectedSessionRecoveryDeps {
+    /** Refresh the saved session even though it looks valid. */
+    forceRefresh?: () => Promise<{
+        refreshed: boolean;
+        reason?: string;
+    }>;
+    /**
+     * The token-getter failure recorded for the latest attempt, if any. hq-cloud
+     * turns a getter error (network, refresh failure, identity swap) into a plain
+     * 401, so a 401 with a recorded failure is not a server rejection of a token.
+     */
+    recordedFailure?: () => Error | null;
+    /** Runs once, after a recoverable 401 and before the refresh and rerun. */
+    onRetry?: () => void | Promise<void>;
+}
+/**
+ * feedback_3d752910: the vault can reject a token that still looks valid in the
+ * local cache (revoked or replaced server-side). The cached expiry check never
+ * notices, and `hq auth refresh` is a no-op for a valid-looking token, so every
+ * sync kept presenting the same rejected token. On a vault 401, force one real
+ * refresh and rerun the sync once. A second rejection is reported as a rejected
+ * session (sign in again), never retried again.
+ */
+export declare function runWithRejectedSessionRecovery<T>(run: () => Promise<T>, deps?: RejectedSessionRecoveryDeps): Promise<T>;
 /** The last token failure recorded by a {@link buildSyncVaultConfig} config. */
 export declare function syncAuthFailureFor(config: VaultServiceConfig | undefined): Error | null;
 /**