@indigoai-us/hq-cli 5.345.199 → 5.345.200

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.345.200] — 2026-11-04
+- `hq creators apply`, `hq library` (search, add, describe, link, rm),
+  `hq sync held`, and `hq lanes` no longer open a browser sign-in when no
+  person is at a terminal (a lane worker, daemon, bot, launchd task, or piped
+  child). They print the `hq login` remedy instead. The headless `hq login`
+  URL path now uses a registered callback port, and a stray
+  `HQ_COGNITO_CALLBACK_PORT` warning prints once per process.
+- The stray callback-port warning no longer prints on commands that never
+  sign in; the port is read when a sign-in starts. `hq bot` and `hq secrets`
+  sign-ins now go through the same interactive-caller gate.
+- `hq bot runtime install` downloads and builds the HQ Fleet Runtime once for
+  this computer, with progress, so `hq bot create` afterwards takes seconds.
+  `hq bot runtime status` says which of the three steps (download, Python,
+  environment) are done. `--json` prints one event per line for the desktop app.
+- The runtime download streams to disk, continues where it stopped after a
+  stall or a dropped connection, and no longer has a 20 minute cap. Creates and
+  adopts started at the same time share one download through a machine-wide
+  lock instead of each fetching the same archive. A gzip runtime archive is
+  accepted alongside the plain tar, and a matching archive from any installed
+  release is reused without a download.
+- `hq bot create`, `hq bot adopt` and `hq bot restore` print what the runtime
+  install is doing on stderr (download percentage, then each build step)
+  unless `--json` is given.
+- Personal and unattributed conversations are no longer assigned from a device default company or sent as Work Mesh summaries. Reporting respects the HQ Anywhere off setting.
+- Validate session capability documents before reading company grants.
+
 ## [5.345.199] — 2026-11-04
 - `hq bot status <name>` shows the bot's last reported failure: when, the
   failure class, the plain-language cause and fix the owner was sent, the HQ

package/assets/scaffold/core/scripts/lib/session-scope-capability.sh

@@ -53,8 +53,8 @@ session_scope_read() {
   local root="${1:-}" sid="${2:-}" aid="${3:-}" cap
   cap="$(session_scope_capability_path "$root" "$sid" "$aid")" || return 0
   [ -f "$cap" ] || return 0
-  jq -r --arg sid "$sid" --arg aid "$aid" \
-    'select(.session_id == $sid and (.agent_id // "") == $aid) | .company_slug // empty' \
+  jq -sr --arg sid "$sid" --arg aid "$aid" \
+    'if length == 1 and (.[0] | type) == "object" then .[0] else error("capability must contain one object") end | select(.session_id == $sid and (.agent_id // "") == $aid) | .company_slug // empty' \
     "$cap" 2>/dev/null || true
 }
 
@@ -66,8 +66,10 @@ session_scope_read_companies() {
   local -a slugs
   cap="$(session_scope_capability_path "$root" "$sid" "$aid")" || return 0
   [ -f "$cap" ] || return 0
-  lock_info="$(jq -er --arg sid "$sid" --arg aid "$aid" '
-    select(.session_id == $sid and (.agent_id // "") == $aid)
+  lock_info="$(jq -ser --arg sid "$sid" --arg aid "$aid" '
+    if length == 1 and (.[0] | type) == "object" then .[0]
+    else error("capability must contain one object") end
+    | select(.session_id == $sid and (.agent_id // "") == $aid)
     | if (.company_slug | type) != "string" or (.company_slug | test("^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$") | not) then error("invalid primary")
       elif has("company_slugs") then
         if (.company_slugs | type) == "array" and all(.company_slugs[]; type == "string" and test("^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"))

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

@@ -19810,6 +19810,50 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly options: readonly [];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "runtime";
+        readonly description: "The HQ Fleet Runtime every local bot on this computer shares";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: true;
+        readonly usage: "[options] [command]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "install";
+            readonly 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";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: true;
+            readonly helpCommand: false;
+            readonly usage: "[options]";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print one JSON object per line: progress events, then { ok, event: \"done\", release, runtimeDir }";
+                readonly hidden: false;
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "status";
+            readonly description: "Say whether the runtime is installed on this computer, step by step";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly helpOption: true;
+            readonly helpCommand: false;
+            readonly usage: "[options]";
+            readonly helpText: readonly [];
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+                readonly hidden: false;
+            }];
+            readonly subcommands: readonly [];
+        }];
     }, {
         readonly name: "daemon";
         readonly description: "Manage the bot's launchd user agent (macOS)";

package/dist/command-catalog.generated.js

@@ -24159,6 +24159,58 @@ export const COMMAND_CATALOG = [
                 "options": [],
                 "subcommands": []
             },
+            {
+                "name": "runtime",
+                "description": "The HQ Fleet Runtime every local bot on this computer shares",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": true,
+                "usage": "[options] [command]",
+                "helpText": [],
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "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",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": true,
+                        "helpCommand": false,
+                        "usage": "[options]",
+                        "helpText": [],
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print one JSON object per line: progress events, then { ok, event: \"done\", release, runtimeDir }",
+                                "hidden": false
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "status",
+                        "description": "Say whether the runtime is installed on this computer, step by step",
+                        "aliases": [],
+                        "hidden": false,
+                        "helpOption": true,
+                        "helpCommand": false,
+                        "usage": "[options]",
+                        "helpText": [],
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON",
+                                "hidden": false
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            },
             {
                 "name": "daemon",
                 "description": "Manage the bot's launchd user agent (macOS)",

package/dist/commands/bot-runtime.d.ts

@@ -0,0 +1,35 @@
+import { type FleetInstallProgress, type FleetInstallProgressListener, type FleetLocalTargetRelease } from "../lib/bot/fleet-local.js";
+export type FleetProgressMode = "text" | "json" | "silent";
+interface ProgressOutput {
+    write(text: string): void;
+    isTTY: boolean;
+}
+/** The sentence for a phase, for people. */
+export declare function describeFleetInstallPhase(event: FleetInstallProgress): string;
+/**
+ * Progress for a terminal (stderr, one line that rewrites itself on a TTY and
+ * prints at each tenth otherwise), for a program (one JSON object per line on
+ * stdout), or nothing.
+ */
+export declare function fleetInstallProgressReporter(mode: FleetProgressMode, output?: ProgressOutput, stdout?: (line: string) => void): FleetInstallProgressListener;
+export interface FleetRuntimeStatus {
+    ready: boolean;
+    release: {
+        version: string;
+        source: FleetLocalTargetRelease["source"];
+    };
+    steps: {
+        distribution: boolean;
+        python: boolean;
+        runtime: boolean;
+    };
+}
+export declare function fleetRuntimeStatus(): Promise<FleetRuntimeStatus>;
+export declare function runBotRuntimeInstall(opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function runBotRuntimeStatus(opts: {
+    json?: boolean;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=bot-runtime.d.ts.map

package/dist/commands/bot-runtime.js

@@ -0,0 +1,115 @@
+import chalk from "chalk";
+import { ensureFleetRuntimeInstalled, fleetLocalDistributionInstalled, fleetRuntimeReady, installTargetFleetLocalDistribution, resolveFleetLocalTargetRelease, } from "../lib/bot/fleet-local.js";
+import { installedFleetPython } from "../lib/bot/fleet-python.js";
+function megabytes(bytes) {
+    return `${(bytes / 1_048_576).toFixed(1)} MB`;
+}
+/** The sentence for a phase, for people. */
+export function describeFleetInstallPhase(event) {
+    switch (event.phase) {
+        case "download": {
+            const name = event.file.startsWith("hq-fleet-runtime-") ? "the HQ Fleet Runtime" : event.file;
+            if (event.total === null)
+                return `Downloading ${name}: ${megabytes(event.received)}`;
+            const percent = Math.min(100, Math.floor((event.received / Math.max(event.total, 1)) * 100));
+            return `Downloading ${name}: ${megabytes(event.received)} of ${megabytes(event.total)} (${percent}%)`;
+        }
+        case "verify":
+            return "Checking the download against its signed release";
+        case "python":
+            return "Preparing the runtime's private Python";
+        case "extract":
+            return "Unpacking the runtime";
+        case "environment":
+            return "Creating the runtime environment";
+        case "packages":
+            return "Installing the runtime's packages (a minute or two)";
+        case "ready":
+            if (event.step === "download")
+                return event.cached ? "The runtime download is already on this computer" : "The runtime download is complete";
+            return event.cached ? "The runtime is already installed on this computer" : "The runtime is ready";
+    }
+}
+/**
+ * Progress for a terminal (stderr, one line that rewrites itself on a TTY and
+ * prints at each tenth otherwise), for a program (one JSON object per line on
+ * stdout), or nothing.
+ */
+export function fleetInstallProgressReporter(mode, output = { write: (text) => { process.stderr.write(text); }, isTTY: process.stderr.isTTY === true }, stdout = (line) => { process.stdout.write(`${line}\n`); }) {
+    if (mode === "silent")
+        return () => undefined;
+    if (mode === "json") {
+        return (event) => {
+            const percent = event.phase === "download" && event.total !== null
+                ? Math.min(100, Math.floor((event.received / Math.max(event.total, 1)) * 100))
+                : null;
+            stdout(JSON.stringify({ event: "progress", ...event, percent, message: describeFleetInstallPhase(event) }));
+        };
+    }
+    let lastTenth = -1;
+    let lineOpen = false;
+    return (event) => {
+        const text = describeFleetInstallPhase(event);
+        if (event.phase === "download" && event.total !== null) {
+            const tenth = Math.floor((event.received / Math.max(event.total, 1)) * 10);
+            if (output.isTTY) {
+                output.write(`\r${text}${event.received >= event.total ? "\n" : ""}`);
+                lineOpen = event.received < event.total;
+                return;
+            }
+            if (tenth === lastTenth && event.received < event.total)
+                return;
+            lastTenth = tenth;
+            output.write(`${text}\n`);
+            return;
+        }
+        if (lineOpen) {
+            output.write("\n");
+            lineOpen = false;
+        }
+        output.write(`${text}\n`);
+    };
+}
+export async function fleetRuntimeStatus() {
+    const target = await resolveFleetLocalTargetRelease();
+    const distribution = fleetLocalDistributionInstalled(target.release);
+    const python = installedFleetPython();
+    const runtime = distribution && python ? fleetRuntimeReady({ release: target.release }, { python }) : false;
+    return {
+        ready: distribution && python !== null && runtime,
+        release: { version: target.release.version, source: target.source },
+        steps: { distribution, python: python !== null, runtime },
+    };
+}
+export async function runBotRuntimeInstall(opts) {
+    const report = fleetInstallProgressReporter(opts.json ? "json" : "text");
+    const target = await resolveFleetLocalTargetRelease();
+    const installation = await installTargetFleetLocalDistribution({ target, onProgress: report });
+    const result = await ensureFleetRuntimeInstalled(installation, { onProgress: report });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            event: "done",
+            release: { version: result.release.version, source: target.source },
+            distributionDir: result.distributionDir,
+            runtimeDir: result.runtimeDir,
+        }));
+        return;
+    }
+    console.log(`${chalk.green("HQ Fleet Runtime " + result.release.version + " is ready on this computer.")} ${chalk.dim(result.runtimeDir)}`);
+}
+export async function runBotRuntimeStatus(opts) {
+    const current = await fleetRuntimeStatus();
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, ...current }, null, 2));
+        return;
+    }
+    const mark = (done) => (done ? chalk.green("ready") : chalk.yellow("missing"));
+    console.log(`HQ Fleet Runtime ${current.release.version}  ${current.ready ? chalk.green("ready") : chalk.yellow("not installed yet")}`);
+    console.log(`  download:     ${mark(current.steps.distribution)}`);
+    console.log(`  python:       ${mark(current.steps.python)}`);
+    console.log(`  environment:  ${mark(current.steps.runtime)}`);
+    if (!current.ready)
+        console.log(chalk.dim("  Run `hq bot runtime install` to get it ready before creating a bot."));
+}
+//# sourceMappingURL=bot-runtime.js.map

package/dist/commands/bot.d.ts

@@ -101,6 +101,12 @@ export interface BotRow {
 export declare function listBotNames(root: string): string[];
 /** Bot-identity token supplier: per-bot creds + per-bot token cache dir. */
 export declare function botTokenSupplier(dir: string): () => Promise<string>;
+/**
+ * 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 declare function ownerSignInAllowed(): boolean;
 /**
  * The bot's word on its coding tool's sign-in. Only a running bot's report
  * counts: a stopped bot's last check may be from before a sign-in or a

package/dist/commands/bot.js

@@ -71,6 +71,8 @@ import { classifyRuntimeFailure, runtimeFailureReason } from "../lib/bot/runtime
 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 { gatedInteractiveLogin } from "../utils/interactive-caller.js";
+import { fleetInstallProgressReporter, runBotRuntimeInstall, runBotRuntimeStatus } from "./bot-runtime.js";
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
@@ -332,7 +334,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,
@@ -735,9 +745,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 +760,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 +777,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 +1240,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 +1402,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;
@@ -2776,7 +2790,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 +2822,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 +2887,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 +3001,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 +3191,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 +3289,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/creators.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { gatedInteractiveLogin } from "../utils/interactive-caller.js";
 /**
  * Testable core. Submits the application and maps the server response to a
  * single human-readable message. Throws on hard failures.
@@ -46,7 +47,7 @@ export function registerCreatorsCommand(program) {
         .action(async (options) => {
         try {
             const result = await runCreatorApply({ reason: options.reason, handle: options.handle }, {
-                getAccessToken: () => ensureCognitoToken({ interactive: true }),
+                getAccessToken: () => ensureCognitoToken({ interactive: gatedInteractiveLogin() }),
                 post: (token, body) => vaultApiFetch({
                     token,
                     path: "/v1/creators/request-access",

package/dist/commands/library-remove.js

@@ -44,6 +44,7 @@ import * as readline from "node:readline";
 import chalk from "chalk";
 import { isCloudPlaceholderName, parseCloudPlaceholder } from "@indigoai-us/hq-cloud";
 import { OFFLOAD_PREFIX, PLACEHOLDER_SUFFIX, digestFile, resolvePlaceholder } from "./storage-offload.js";
+import { gatedInteractiveLogin } from "../utils/interactive-caller.js";
 /** A company library blob key: `.hq-offload/blobs/<64 lowercase hex>`. */
 const BLOB_KEY_PATTERN = /^\.hq-offload\/blobs\/([0-9a-f]{64})$/;
 /** hq-pro caps an asset search at 50 hits. */
@@ -637,7 +638,7 @@ export function registerLibraryRemoveCommand(library) {
                 import("../utils/manifest.js"),
             ]);
             const credential = await resolveVaultCredentialForCapability("files:write", "library rm", {
-                interactive: true,
+                interactive: gatedInteractiveLogin(),
             });
             const { token } = credential;
             const apiKey = credential.kind === "api-key";

package/dist/commands/library.js

@@ -41,6 +41,7 @@ import { defaultLibraryIo, resolveLibrarySyncScope, runLibraryAdd, runLibraryTag
 import { captionAddedAsset, extractCaptionFrames, runLibraryDescribe, runLocalClaude } from "./library-caption.js";
 import { LIBRARY_LINK_DEFAULT_MINUTES, LIBRARY_LINK_MAX_MINUTES, runLibraryLink } from "./library-link.js";
 import { registerLibraryRemoveCommand } from "./library-remove.js";
+import { gatedInteractiveLogin } from "../utils/interactive-caller.js";
 /** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
 export const MAX_LIBRARY_SEARCH_TAGS = 20;
 const MAX_TAG_LENGTH = 100;
@@ -445,7 +446,7 @@ export function registerLibraryCommand(program) {
             };
             const result = await runLibrarySearch(queryParts.join(" "), searchOptions, {
                 getToken: async () => (await resolveVaultCredentialForCapability("search:query", "library search", {
-                    interactive: true,
+                    interactive: gatedInteractiveLogin(),
                 })).token,
                 post: (token, body) => vaultApiFetch({ token, path: "/v1/search", method: "POST", body }),
                 searchLocal: (query, opts) => searchLocalAssets(query, opts, defaultLocalEnv()),
@@ -476,7 +477,7 @@ export function registerLibraryCommand(program) {
         .action(async (sources, options) => {
         try {
             const credential = await resolveVaultCredentialForCapability("files:write", "library add", {
-                interactive: true,
+                interactive: gatedInteractiveLogin(),
             });
             const { token } = credential;
             const hqRoot = findHqRoot();
@@ -561,7 +562,7 @@ export function registerLibraryCommand(program) {
         .action(async (target, options) => {
         try {
             const credential = await resolveVaultCredentialForCapability("files:read", "library describe", {
-                interactive: true,
+                interactive: gatedInteractiveLogin(),
             });
             const { token } = credential;
             const hqRoot = findHqRoot();
@@ -618,7 +619,7 @@ export function registerLibraryCommand(program) {
         .action(async (target, options) => {
         try {
             const credential = await resolveVaultCredentialForCapability("files:read", "library link", {
-                interactive: true,
+                interactive: gatedInteractiveLogin(),
             });
             const { token } = credential;
             const result = await runLibraryLink(target, { company: options.company, expiresMinutes: options.expires }, {

package/dist/commands/mesh.d.ts

@@ -1,10 +1,3 @@
-/**
- * `hq mesh` — work-mesh verbs for agents and local sessions.
- *
- * Native hq-cli: Cognito + hq-pro REST + ~/.hq/work-mesh/cache. Does not
- * require hq-pack-work-mesh on disk and does not start MQTT listen.
- * Distinct from `hq doctor` (hook guardrails).
- */
 import { Command } from "commander";
 import { type MeshCompany, type MeshProjectRepo, type MeshProjectStoryInput, type MeshThread } from "../lib/mesh/api.js";
 import { UnknownProjectStoryStateError } from "../lib/mesh/story-status.js";

package/dist/commands/mesh.js

@@ -1,3 +1,4 @@
+import { reportingRuntimeAllowed } from "../lib/mesh/live/reporting-privacy.js";
 /**
  * `hq mesh` — work-mesh verbs for agents and local sessions.
  *
@@ -1123,6 +1124,7 @@ async function runPrdSync(opts) {
     }));
     const poster = createEmitPoster({ token, baseUrl: resolveVaultApiBase(process.env) });
     const emitted = await emitEvents({
+        reportingAllowed: () => reportingRuntimeAllowed(isMachineIdentity()),
         workMeshRoot: meshRoot,
         poster,
         newEvents: events,
@@ -2534,6 +2536,7 @@ async function runSessionEnqueue(cliKind, opts) {
         baseUrl: resolveVaultApiBase(process.env),
     });
     const summary = await emitEvents({
+        reportingAllowed: () => reportingRuntimeAllowed(isMachineIdentity()),
         workMeshRoot: meshRoot,
         poster,
         newEvents: [event],
@@ -2617,7 +2620,7 @@ async function runMeshEmit(opts) {
         skipped = backlog.skipped;
         newEvents = backlog.events;
     }
-    const summary = await emitEvents({ workMeshRoot: meshRoot, poster, newEvents });
+    const summary = await emitEvents({ reportingAllowed: () => reportingRuntimeAllowed(isMachineIdentity()), workMeshRoot: meshRoot, poster, newEvents });
     const out = {
         ok: true,
         action: "emit",
@@ -2643,6 +2646,7 @@ async function runSessionFlush(opts) {
         baseUrl: resolveVaultApiBase(process.env),
     });
     const summary = await flushSessionEvents({
+        reportingAllowed: () => reportingRuntimeAllowed(isMachineIdentity()),
         workMeshRoot: workMeshHomeRoot(),
         workContextRoot: workContextHomeRoot(),
         poster,

package/dist/commands/sync-held.js

@@ -19,6 +19,7 @@ import { VaultClient, PERSONAL_VAULT_JOURNAL_SLUG, getStateDir } from "@indigoai
 import { buildVaultConfig, cognitoSubjectFromToken, ensureCognitoToken } from "../utils/cognito-session.js";
 import { decodeJwtPayload } from "../utils/person-token-cache.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
+import { gatedInteractiveLogin } from "../utils/interactive-caller.js";
 export const HELD_UNAVAILABLE_MESSAGE = "this HQ build cannot list or release held uploads yet; update HQ and try again";
 export function fenceExports(mod = hqCloud) {
     const list = mod.listPushIdentityFences;
@@ -157,11 +158,10 @@ export async function resolveHeldIdentity(options, io) {
     return { sub, personalUid };
 }
 export function createDefaultSyncHeldDeps() {
-    const tty = process.stdin.isTTY === true && process.stdout.isTTY === true;
     return {
         exports: fenceExports(),
         stateDir: getStateDir(),
-        identity: (options) => resolveHeldIdentity({ needPersonal: options.needPersonal, interactive: options.interactive && tty }, {
+        identity: (options) => resolveHeldIdentity({ needPersonal: options.needPersonal, interactive: gatedInteractiveLogin(options.interactive) }, {
             ensureToken: (interactive) => ensureCognitoToken({ interactive }),
             listPersons: async (token) => (await new VaultClient(buildVaultConfig(token)).entity.listByType("person")),
         }),