@indigoai-us/hq-cli 5.345.188 → 5.345.190

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.107","bundleSha256":"0df48ddf2618cac4801b8abefa1d2a4b4a915f368bf7d1b2823bcdd104044325","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.107","bundleSha256":"4ffaf3a579e9222aa2e9a1850e355d4a152d6d3323cf0583154cf28e1d45459a","formatVersion":1}

package/dist/lib/bot/fleet-local.d.ts

@@ -99,8 +99,34 @@ export interface FleetLocalBootstrapDeps {
     start?: boolean;
     python?: FleetPython;
 }
+interface SharedFleetRuntime {
+    id: string;
+    root: string;
+    runtimeDir: string;
+    sourcesDir: string;
+    /** Extracted runtime source tree (`sources/runtime`, or `s/r` on Windows). */
+    runtimeSource: string;
+    /** Extracted distribution tree (`sources/distribution`, or `s/d` on Windows). */
+    distributionSource: string;
+}
+/**
+ * Hex characters of the runtime identity used for the shared runtime
+ * directory name on Windows. The full 64-character identity plus
+ * `sources\runtime` pushed the runtime's deepest files past MAX_PATH (260).
+ */
+export declare const WINDOWS_RUNTIME_DIR_ID_LENGTH = 16;
+/** Longest path Windows accepts when long paths are turned off (MAX_PATH minus the terminator). */
+export declare const WINDOWS_MAX_PATH_CHARS = 259;
+/**
+ * Where a shared runtime lives. macOS and Linux keep the original layout
+ * (`runtimes/<64 hex>/{runtime,sources/runtime,sources/distribution}`).
+ * Windows uses `runtimes/<16 hex>/{v,s\r,s\d}` so deep runtime files stay
+ * under MAX_PATH; `ready.json` records the full identity.
+ */
+export declare function sharedRuntimeLayout(root: string, id: string, platform: NodeJS.Platform): SharedFleetRuntime;
 type FleetLocalProfileDeps = Pick<FleetLocalBootstrapDeps, "fleetHome" | "platform"> & {
     runtimeRoot?: string;
+    runtime?: SharedFleetRuntime;
 };
 export interface FleetLocalBootstrapResult {
     profile: string;
@@ -139,7 +165,15 @@ export declare const HQ_FLEET_LOCAL_RELEASE: FleetLocalReleasePin;
 export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=\n-----END PUBLIC KEY-----\n";
 export declare function fleetHome(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function verifyFleetLocalRelease(files: FleetLocalReleaseFiles, release?: FleetLocalReleasePin, publicKey?: string): void;
-export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv): string;
+/**
+ * Warning text when the signed manifest asks for a newer hq CLI than this
+ * one, or null. Advisory only: the pinned runtime is still installed, since
+ * blocking would strand every user until that CLI version is published.
+ */
+export declare function fleetLocalCliCompatibilityWarning(manifest: Buffer, release?: FleetLocalReleasePin, cliVersion?: string): string | null;
+/** `gh auth token` fallback for the release download token. */
+export declare const FLEET_RELEASE_TOKEN_TIMEOUT_MS = 15000;
+export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv, run?: FleetLocalExec): string;
 export declare function fetchHqFleetReleaseLinks(release: FleetLocalReleasePin): Promise<Map<string, string> | null>;
 export declare const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30000;
 export declare const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS: number;
@@ -170,6 +204,14 @@ export declare function writeFleetLocalSoul(agentUid: string, systemPrompt: stri
 export declare function scanFleetLocalInstructions(agentUid: string, text: string, deps?: FleetLocalControlDeps): string[];
 /** Checks the instructions with the runtime's scanner, then makes them the bot's persona. */
 export declare function refreshFleetLocalInstructions(agentUid: string, systemPrompt: string, deps?: FleetLocalControlDeps): string;
+/** Last few non-empty stderr lines of a failed child process, trimmed for an error message. */
+export declare function stderrTail(error: unknown): string;
+/**
+ * Message for a Windows extraction that cannot fit under MAX_PATH, or null
+ * when it fits or long paths are on. `longest` is the longest member name in
+ * the archive; members land at `<destination>\<name>`.
+ */
+export declare function windowsExtractionPathProblem(destination: string, longest: number, longPathsEnabled: number | null): string | null;
 /** Moves a fresh machine credential into the bot's secure store and deletes the file. */
 export declare function importFleetLocalMachineCredential(agentUid: string, machineCredentials: string, deps?: FleetLocalControlDeps): void;
 export declare function bootstrapFleetLocalBot(input: FleetLocalProfileInput & {

package/dist/lib/bot/fleet-local.js

@@ -6,6 +6,8 @@ import * as path from "node:path";
 import { HQ_FLEET_RUNTIME_ENGINE_ID, } from "./config.js";
 import { withBotLock } from "./lock.js";
 import { ensureFleetPython, fleetUvEnv } from "./fleet-python.js";
+import semver from "semver";
+import { CLI_VERSION } from "../../cli-version.js";
 import { ensureCognitoToken } from "../../utils/cognito-session.js";
 import { vaultApiFetch } from "../../utils/vault-api.js";
 /** The model the HQ Fleet Runtime asks for when a Claude bot names none. */
@@ -34,6 +36,46 @@ export function fleetProviderForRuntime(runtime, model) {
 export function fleetProviderNeedsSignIn(provider) {
     return provider.id !== "anthropic";
 }
+/**
+ * Hex characters of the runtime identity used for the shared runtime
+ * directory name on Windows. The full 64-character identity plus
+ * `sources\runtime` pushed the runtime's deepest files past MAX_PATH (260).
+ */
+export const WINDOWS_RUNTIME_DIR_ID_LENGTH = 16;
+/** Longest path Windows accepts when long paths are turned off (MAX_PATH minus the terminator). */
+export const WINDOWS_MAX_PATH_CHARS = 259;
+function legacySharedRuntimeLayout(root, id) {
+    const shared = path.join(root, "runtimes", id);
+    const sources = path.join(shared, "sources");
+    return {
+        id,
+        root: shared,
+        runtimeDir: path.join(shared, "runtime"),
+        sourcesDir: sources,
+        runtimeSource: path.join(sources, "runtime"),
+        distributionSource: path.join(sources, "distribution"),
+    };
+}
+/**
+ * Where a shared runtime lives. macOS and Linux keep the original layout
+ * (`runtimes/<64 hex>/{runtime,sources/runtime,sources/distribution}`).
+ * Windows uses `runtimes/<16 hex>/{v,s\r,s\d}` so deep runtime files stay
+ * under MAX_PATH; `ready.json` records the full identity.
+ */
+export function sharedRuntimeLayout(root, id, platform) {
+    if (platform !== "win32")
+        return legacySharedRuntimeLayout(root, id);
+    const shared = path.join(root, "runtimes", id.slice(0, WINDOWS_RUNTIME_DIR_ID_LENGTH));
+    const sources = path.join(shared, "s");
+    return {
+        id,
+        root: shared,
+        runtimeDir: path.join(shared, "v"),
+        sourcesDir: sources,
+        runtimeSource: path.join(sources, "r"),
+        distributionSource: path.join(sources, "d"),
+    };
+}
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
     tag: "v0.4.17",
@@ -105,18 +147,47 @@ export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE,
         throw expectedError(`HQ Fleet Local ${release.version} manifest signature is invalid.`);
     }
 }
-export function resolveFleetReleaseToken(env = process.env) {
+/**
+ * Warning text when the signed manifest asks for a newer hq CLI than this
+ * one, or null. Advisory only: the pinned runtime is still installed, since
+ * blocking would strand every user until that CLI version is published.
+ */
+export function fleetLocalCliCompatibilityWarning(manifest, release = HQ_FLEET_LOCAL_RELEASE, cliVersion = CLI_VERSION) {
+    let minimum;
+    try {
+        const parsed = JSON.parse(manifest.toString("utf8"));
+        minimum = parsed.compatibility?.minimum_hq_cli_version;
+    }
+    catch {
+        return null;
+    }
+    if (typeof minimum !== "string")
+        return null;
+    const required = semver.valid(semver.coerce(minimum));
+    const current = semver.valid(semver.coerce(cliVersion));
+    if (!required || !current || semver.gte(current, required))
+        return null;
+    return `HQ Fleet Local ${release.version} asks for hq CLI ${minimum} or newer; this is ${cliVersion}. ` +
+        "Update with `npm install -g @indigoai-us/hq-cli` if the bot misbehaves.";
+}
+/** `gh auth token` fallback for the release download token. */
+export const FLEET_RELEASE_TOKEN_TIMEOUT_MS = 15_000;
+export function resolveFleetReleaseToken(env = process.env, run = execFileSync) {
     for (const name of ["HQ_FLEET_RELEASE_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
         const value = env[name]?.trim();
         if (value)
             return value;
     }
     try {
-        const value = execFileSync("gh", ["auth", "token"], {
+        // gh can block on a keychain prompt; a create must fail, not hang.
+        const output = run("gh", ["auth", "token"], {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "ignore"],
             windowsHide: true,
-        }).trim();
+            timeout: FLEET_RELEASE_TOKEN_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
+        const value = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
         if (value)
             return value;
     }
@@ -299,8 +370,14 @@ export async function installPinnedFleetLocalDistribution(deps = {}) {
     const root = deps.fleetHome ?? fleetHome();
     const dir = path.join(root, "distributions", "hq-fleet-local", release.version);
     const current = installedFiles(dir, release);
+    const warnCompatibility = (manifest) => {
+        const warning = fleetLocalCliCompatibilityWarning(manifest, release);
+        if (warning)
+            process.stderr.write(`Warning: ${warning}\n`);
+    };
     if (current) {
         verifyFleetLocalRelease(current, release, publicKey);
+        warnCompatibility(current.manifest);
     }
     else {
         const fetcher = deps.fetch ?? fetch;
@@ -310,6 +387,7 @@ export async function installPinnedFleetLocalDistribution(deps = {}) {
             ? await downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime)
             : await downloadFleetLocalRelease(release, fetcher, (deps.token ?? resolveFleetReleaseToken)(), cachedRuntime);
         verifyFleetLocalRelease(files, release, publicKey);
+        warnCompatibility(files.manifest);
         installFiles(dir, files, release, publicKey);
     }
     return {
@@ -371,18 +449,19 @@ function venvExecutable(runtimeDir, name, platform) {
         ? path.join(runtimeDir, "Scripts", `${name}.exe`)
         : path.join(runtimeDir, "bin", name);
 }
-function sharedRuntimeFromMarker(profileDir, root) {
+function sharedRuntimeFromMarker(profileDir, root, platform = process.platform) {
     try {
         const marker = JSON.parse(fs.readFileSync(path.join(profileDir, "bootstrap.json"), "utf8"));
         if (marker.schemaVersion !== 2 || typeof marker.runtimeId !== "string" || !/^[a-f0-9]{64}$/.test(marker.runtimeId))
             return null;
-        const sharedRoot = path.join(root, "runtimes", marker.runtimeId);
-        return {
-            id: marker.runtimeId,
-            root: sharedRoot,
-            runtimeDir: path.join(sharedRoot, "runtime"),
-            sourcesDir: path.join(sharedRoot, "sources"),
-        };
+        const layout = sharedRuntimeLayout(root, marker.runtimeId, platform);
+        if (platform === "win32" && !fs.existsSync(path.join(layout.root, "ready.json"))) {
+            // Bots installed before the short Windows layout keep using their runtime.
+            const legacy = legacySharedRuntimeLayout(root, marker.runtimeId);
+            if (fs.existsSync(path.join(legacy.root, "ready.json")))
+                return legacy;
+        }
+        return layout;
     }
     catch {
         return null;
@@ -420,7 +499,7 @@ function fleetLocalExecutables(agentUid, deps) {
     const root = deps.fleetHome ?? fleetHome();
     const platform = deps.platform ?? process.platform;
     const profileDir = profileRoot(agentUid, root);
-    const shared = sharedRuntimeFromMarker(profileDir, root);
+    const shared = sharedRuntimeFromMarker(profileDir, root, platform);
     const runtimeDir = shared?.runtimeDir ?? path.join(profileDir, "runtime");
     const sourcesDir = shared?.sourcesDir ?? path.join(profileDir, "sources");
     const profile = path.join(profileDir, "profile.json");
@@ -478,12 +557,12 @@ export function fleetLocalProfileNeedsAdoption(agentUid, deps = {}) {
     if (!entries.includes(canonicalName))
         return true;
     const profileDir = path.join(profiles, canonicalName);
-    const shared = sharedRuntimeFromMarker(profileDir, root);
+    const platform = deps.platform ?? process.platform;
+    const shared = sharedRuntimeFromMarker(profileDir, root, platform);
     if (!shared)
         return true;
     if (!profileEngineMatchesRelease(profileDir, deps.release ?? HQ_FLEET_LOCAL_RELEASE))
         return true;
-    const platform = deps.platform ?? process.platform;
     if (!["hq-fleet", "hq-fleet-local", "python"].every((name) => fs.existsSync(venvExecutable(shared.runtimeDir, name, platform))))
         return true;
     if (hasEmbeddedRuntime(profileDir, platform) || fs.existsSync(path.join(profileDir, "sources")))
@@ -633,7 +712,7 @@ export function removeFleetLocalBot(agentUid, deps = {}) {
     }
     const platform = deps.platform ?? process.platform;
     const legacyRuntime = path.join(profileDir, "runtime");
-    const shared = sharedRuntimeFromMarker(profileDir, deps.fleetHome ?? fleetHome());
+    const shared = sharedRuntimeFromMarker(profileDir, deps.fleetHome ?? fleetHome(), platform);
     const installedRuntime = shared?.runtimeDir ?? legacyRuntime;
     if (!["hq-fleet", "hq-fleet-local"].every((name) => fs.existsSync(venvExecutable(installedRuntime, name, platform)))) {
         fs.rmSync(profileDir, { recursive: true, force: true });
@@ -751,9 +830,11 @@ export function writeFleetLocalProfile(input, deps = {}) {
     }
     const root = deps.fleetHome ?? fleetHome();
     const dir = profileRoot(input.agentUid, root);
-    const markerRuntime = sharedRuntimeFromMarker(dir, root);
-    const runtimeRoot = deps.runtimeRoot ?? markerRuntime?.root ?? dir;
-    const runtimeDir = path.join(runtimeRoot, "runtime");
+    const layout = deps.runtime ??
+        (deps.runtimeRoot ? undefined : sharedRuntimeFromMarker(dir, root, deps.platform ?? process.platform) ?? undefined);
+    const runtimeRoot = deps.runtimeRoot ?? dir;
+    const runtimeDir = layout?.runtimeDir ?? path.join(runtimeRoot, "runtime");
+    const distributionSource = layout?.distributionSource ?? path.join(runtimeRoot, "sources", "distribution");
     const destination = path.join(dir, "profile.json");
     const temporary = path.join(dir, `.profile-${process.pid}-${crypto.randomUUID()}`);
     const profile = {
@@ -766,7 +847,7 @@ export function writeFleetLocalProfile(input, deps = {}) {
         profileDir: path.resolve(dir),
         runtime: { commit: input.installation.release.runtimeCommit, path: path.resolve(runtimeDir) },
         paths: {
-            pluginSource: path.resolve(path.join(runtimeRoot, "sources", "distribution", "src", "hq_fleet_local", "plugins", "hqdm")),
+            pluginSource: path.resolve(path.join(distributionSource, "src", "hq_fleet_local", "plugins", "hqdm")),
             statusFile: path.resolve(path.join(input.botDir, "status.json")),
             logsDir: path.resolve(path.join(input.botDir, "logs")),
         },
@@ -827,11 +908,11 @@ export function scanFleetLocalInstructions(agentUid, text, deps = {}) {
     const run = deps.run ?? execFileSync;
     const root = deps.fleetHome ?? fleetHome();
     const profileDir = profileRoot(agentUid, root);
-    const shared = sharedRuntimeFromMarker(profileDir, root);
+    const platform = deps.platform ?? process.platform;
+    const shared = sharedRuntimeFromMarker(profileDir, root, platform);
     const runtimeDir = shared?.runtimeDir ?? path.join(profileDir, "runtime");
-    const sourcesDir = shared?.sourcesDir ?? path.join(profileDir, "sources");
-    const python = venvExecutable(runtimeDir, "python", deps.platform ?? process.platform);
-    const source = path.join(sourcesDir, "runtime");
+    const python = venvExecutable(runtimeDir, "python", platform);
+    const source = shared?.runtimeSource ?? path.join(profileDir, "sources", "runtime");
     if (!fs.existsSync(python) || !fs.existsSync(source)) {
         throw expectedError("HQ Fleet Local is not installed for this bot, so its instructions could not be checked.");
     }
@@ -861,13 +942,81 @@ export function refreshFleetLocalInstructions(agentUid, systemPrompt, deps = {})
     }
     return writeFleetLocalSoul(agentUid, systemPrompt, deps);
 }
+const STDERR_TAIL_LINES = 6;
+const STDERR_TAIL_CHARS = 800;
+/** Last few non-empty stderr lines of a failed child process, trimmed for an error message. */
+export function stderrTail(error) {
+    const raw = error?.stderr;
+    const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : typeof raw === "string" ? raw : "";
+    const lines = text.split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0);
+    const tail = lines.slice(-STDERR_TAIL_LINES).join("\n");
+    return tail.length > STDERR_TAIL_CHARS ? `...${tail.slice(-STDERR_TAIL_CHARS)}` : tail;
+}
 function checkedRun(run, executable, args, options, label) {
+    // Keep stdout quiet but capture stderr, so a failure names its cause
+    // (for example a path-too-long error during extraction).
+    const stdio = options.stdio === "ignore" ? ["ignore", "ignore", "pipe"] : options.stdio;
     try {
-        run(executable, args, { windowsHide: true, ...options });
+        run(executable, args, {
+            windowsHide: true,
+            maxBuffer: 16 * 1024 * 1024,
+            ...options,
+            ...(stdio === undefined ? {} : { stdio }),
+        });
     }
-    catch {
-        throw expectedError(`HQ Fleet Local ${label} failed.`);
+    catch (error) {
+        const tail = stderrTail(error);
+        throw expectedError(`HQ Fleet Local ${label} failed.${tail ? `\n${tail}` : ""}`);
+    }
+}
+const FLEET_TAR_PATH_PROBE = [
+    "import json, sys, tarfile",
+    "longest = 0",
+    "with tarfile.open(sys.argv[1]) as archive:",
+    "    for member in archive:",
+    "        longest = max(longest, len(member.name.rstrip('/')))",
+    "enabled = None",
+    "try:",
+    "    import winreg",
+    "    key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r'SYSTEM\\CurrentControlSet\\Control\\FileSystem')",
+    "    enabled = int(winreg.QueryValueEx(key, 'LongPathsEnabled')[0])",
+    "except Exception:",
+    "    pass",
+    "print(json.dumps({'longest': longest, 'longPathsEnabled': enabled}))",
+].join("\n");
+/**
+ * Message for a Windows extraction that cannot fit under MAX_PATH, or null
+ * when it fits or long paths are on. `longest` is the longest member name in
+ * the archive; members land at `<destination>\<name>`.
+ */
+export function windowsExtractionPathProblem(destination, longest, longPathsEnabled) {
+    const needed = destination.length + 1 + longest;
+    if (needed <= WINDOWS_MAX_PATH_CHARS || longPathsEnabled === 1)
+        return null;
+    return `The HQ Fleet Runtime cannot be extracted on this PC: its deepest file needs a ${needed}-character path under ${destination}, ` +
+        `over the Windows limit of ${WINDOWS_MAX_PATH_CHARS}, and Windows long paths are turned off (LongPathsEnabled = ${longPathsEnabled ?? "unset"}). ` +
+        "Ask an administrator to set HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem\\LongPathsEnabled to 1, or set HQ_FLEET_HOME to a shorter folder such as C:\\hqf, then retry.";
+}
+function assertWindowsExtractionFits(run, python, archive, destination) {
+    let probe;
+    try {
+        const output = run(python, ["-I", "-c", FLEET_TAR_PATH_PROBE, archive], {
+            windowsHide: true,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 1024 * 1024,
+        });
+        probe = JSON.parse((Buffer.isBuffer(output) ? output.toString("utf8") : output).trim());
     }
+    catch {
+        return; // The probe is advisory; extraction reports its own error.
+    }
+    if (typeof probe?.longest !== "number")
+        return;
+    const enabled = typeof probe.longPathsEnabled === "number" ? probe.longPathsEnabled : null;
+    const problem = windowsExtractionPathProblem(destination, probe.longest, enabled);
+    if (problem)
+        throw expectedError(problem);
 }
 /** Moves a fresh machine credential into the bot's secure store and deletes the file. */
 export function importFleetLocalMachineCredential(agentUid, machineCredentials, deps = {}) {
@@ -896,25 +1045,37 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
         platform,
         extras: ["mcp", "anthropic"],
     })));
-    const shared = path.join(root, "runtimes", identity);
-    const descriptor = () => ({
-        id: identity,
-        root: shared,
-        runtimeDir: path.join(shared, "runtime"),
-        sourcesDir: path.join(shared, "sources"),
-    });
+    const layout = sharedRuntimeLayout(root, identity, platform);
+    const shared = layout.root;
     return withBotLock(identity, async () => {
         const marker = path.join(shared, "ready.json");
-        const sources = path.join(shared, "sources");
-        const distributionSource = path.join(sources, "distribution");
-        const runtimeSource = path.join(sources, "runtime");
-        const runtimeDir = path.join(shared, "runtime");
+        const { distributionSource, runtimeSource, runtimeDir } = layout;
         const executables = ["python", "hq-fleet", "hq-fleet-local"];
+        if (platform === "win32") {
+            const legacy = legacySharedRuntimeLayout(root, identity);
+            if (fs.existsSync(path.join(legacy.root, "ready.json")) &&
+                executables.every((name) => fs.existsSync(venvExecutable(legacy.runtimeDir, name, platform)))) {
+                // A runtime installed before the short Windows layout keeps serving bots.
+                return legacy;
+            }
+            // A half-extracted long-path runtime is never usable; clear it.
+            fs.rmSync(legacy.root, { recursive: true, force: true });
+        }
         if (fs.existsSync(marker)) {
+            let recordedId;
+            try {
+                recordedId = JSON.parse(fs.readFileSync(marker, "utf8")).runtimeId;
+            }
+            catch {
+                recordedId = undefined;
+            }
+            if (recordedId !== undefined && recordedId !== identity) {
+                throw expectedError(`The shared HQ Fleet Runtime folder ${shared} belongs to a different runtime. Remove it and retry.`);
+            }
             if (!executables.every((name) => fs.existsSync(venvExecutable(runtimeDir, name, platform)))) {
                 throw expectedError("The shared HQ Fleet Runtime is incomplete. Reinstall it before creating another bot.");
             }
-            return descriptor();
+            return layout;
         }
         fs.rmSync(shared, { recursive: true, force: true });
         fs.mkdirSync(distributionSource, { recursive: true, mode: 0o700 });
@@ -927,6 +1088,8 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             installation.archive,
             distributionSource,
         ], { stdio: "ignore" }, "distribution extraction");
+        if (platform === "win32")
+            assertWindowsExtractionFits(run, python.python, installation.runtimeArchive, runtimeSource);
         checkedRun(run, python.python, [
             "-m",
             "tarfile",
@@ -955,8 +1118,8 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
         if (!executables.every((name) => fs.existsSync(venvExecutable(runtimeDir, name, platform)))) {
             throw expectedError("HQ Fleet Local installed without its runtime executables.");
         }
-        fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, engine: installation.engine })}\n`, { mode: 0o600 });
-        return descriptor();
+        fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, runtimeId: identity, engine: installation.engine })}\n`, { mode: 0o600 });
+        return layout;
     }, { root: path.join(root, "runtimes"), command: "HQ Fleet Runtime installation", waitMs: 20 * 60_000, staleMs: 2 * 60 * 60_000 });
 }
 function writeNativeProfileMarker(profileDir, shared, engine) {
@@ -982,7 +1145,7 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
     const { systemPrompt, machineCredentials, ...profileInput } = input;
     if (systemPrompt !== undefined)
         refreshFleetLocalInstructions(input.agentUid, systemPrompt, { fleetHome: root, platform, run });
-    const profile = writeFleetLocalProfile(profileInput, { fleetHome: root, platform, runtimeRoot: shared.root });
+    const profile = writeFleetLocalProfile(profileInput, { fleetHome: root, platform, runtime: shared });
     const helper = venvExecutable(shared.runtimeDir, "hq-fleet-local", platform);
     const runtime = venvExecutable(shared.runtimeDir, "hq-fleet", platform);
     if (!fs.existsSync(helper) || !fs.existsSync(runtime)) {

package/dist/lib/bot/fleet-python.d.ts

@@ -26,6 +26,12 @@ export interface FleetPython {
 export declare const HQ_FLEET_PYTHON_VERSION = "3.13.17";
 export declare const HQ_FLEET_PYTHON_TOOL: FleetPythonToolPin;
 export declare const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS: number;
+/** Unpacking the pinned installer archive. */
+export declare const FLEET_PYTHON_EXTRACT_TIMEOUT_MS: number;
+/** `uv python install`: downloads and unpacks the private Python. */
+export declare const FLEET_PYTHON_INSTALL_TIMEOUT_MS: number;
+/** `uv python find`: local lookup only. */
+export declare const FLEET_PYTHON_FIND_TIMEOUT_MS = 60000;
 /** One lock for the whole machine: the installer and the private Python are shared by every bot. */
 export declare const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
 /**

package/dist/lib/bot/fleet-python.js

@@ -18,6 +18,12 @@ export const HQ_FLEET_PYTHON_TOOL = {
     },
 };
 export const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** Unpacking the pinned installer archive. */
+export const FLEET_PYTHON_EXTRACT_TIMEOUT_MS = 2 * 60_000;
+/** `uv python install`: downloads and unpacks the private Python. */
+export const FLEET_PYTHON_INSTALL_TIMEOUT_MS = 15 * 60_000;
+/** `uv python find`: local lookup only. */
+export const FLEET_PYTHON_FIND_TIMEOUT_MS = 60_000;
 /** One lock for the whole machine: the installer and the private Python are shared by every bot. */
 export const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
 function expectedError(message) {
@@ -27,9 +33,13 @@ function toolBinaryName(platform) {
     return platform === "win32" ? "uv.exe" : "uv";
 }
 /** The last lines a failed child process wrote, or its exit code, so the user sees why. */
-function causeOf(error) {
+function causeOf(error, timeoutMs) {
     if (error && typeof error === "object") {
         const failure = error;
+        // A child killed by execFileSync's timeout: say so instead of a bare signal.
+        if (failure.code === "ETIMEDOUT") {
+            return timeoutMs !== undefined ? `timed out after ${Math.round(timeoutMs / 1000)}s` : "timed out";
+        }
         const stderr = failure.stderr === undefined ? "" : (Buffer.isBuffer(failure.stderr) ? failure.stderr.toString("utf8") : String(failure.stderr));
         const tail = stderr.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(" ");
         if (tail)
@@ -132,10 +142,15 @@ async function installTool(deps) {
         const extracted = path.join(staging, "extracted");
         fs.mkdirSync(extracted, { mode: 0o700 });
         try {
-            run(tarExecutable(platform, deps.env ?? process.env), ["-xf", archive, "-C", extracted], { stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+            run(tarExecutable(platform, deps.env ?? process.env), ["-xf", archive, "-C", extracted], {
+                stdio: ["ignore", "ignore", "pipe"],
+                windowsHide: true,
+                timeout: FLEET_PYTHON_EXTRACT_TIMEOUT_MS,
+                killSignal: "SIGKILL",
+            });
         }
         catch (error) {
-            throw expectedError(`HQ Fleet Local could not unpack its runtime installer (${causeOf(error)}).`);
+            throw expectedError(`HQ Fleet Local could not unpack its runtime installer (${causeOf(error, FLEET_PYTHON_EXTRACT_TIMEOUT_MS)}).`);
         }
         const unpacked = findFile(extracted, toolBinaryName(platform));
         if (!unpacked)
@@ -179,10 +194,12 @@ async function ensureFleetPythonLocked(root, deps) {
             stdio: ["ignore", "ignore", "pipe"],
             env,
             windowsHide: true,
+            timeout: FLEET_PYTHON_INSTALL_TIMEOUT_MS,
+            killSignal: "SIGKILL",
         });
     }
     catch (error) {
-        throw expectedError(`HQ Fleet Local could not install its private Python ${version} (${causeOf(error)}). If this mentions a download, check your internet connection and retry.`);
+        throw expectedError(`HQ Fleet Local could not install its private Python ${version} (${causeOf(error, FLEET_PYTHON_INSTALL_TIMEOUT_MS)}). If this mentions a download, check your internet connection and retry.`);
     }
     let found;
     try {
@@ -191,11 +208,13 @@ async function ensureFleetPythonLocked(root, deps) {
             env,
             encoding: "utf8",
             windowsHide: true,
+            timeout: FLEET_PYTHON_FIND_TIMEOUT_MS,
+            killSignal: "SIGKILL",
         });
         found = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
     }
     catch (error) {
-        throw expectedError(`HQ Fleet Local installed its private Python but could not locate it (${causeOf(error)}).`);
+        throw expectedError(`HQ Fleet Local installed its private Python but could not locate it (${causeOf(error, FLEET_PYTHON_FIND_TIMEOUT_MS)}).`);
     }
     const python = path.resolve(found);
     if (!found || !fs.existsSync(python) || !isInside(pythonDir, python, platform)) {

package/dist/lib/bot/probe.d.ts

@@ -20,7 +20,9 @@ export declare const PROBE_SYSTEM_PROMPT = "You are an HQ bot being checked befo
 /** A probe that has not answered by then is reported as `transient`. */
 export declare const PROBE_DEFAULT_TIMEOUT_MS = 120000;
 /** The plain sentence for a failed probe: what is wrong and the one fix. */
-export declare function probeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string): string;
+export declare function probeFailureText(cls: RuntimeFailureClass, runtime: BotRuntimeId | string, usageLimit?: {
+    resetsAt?: string;
+}): string;
 export interface RuntimeProbeResult {
     ok: boolean;
     /** null when ok; otherwise the same classes a bot's failure DM uses. */
@@ -30,6 +32,10 @@ export interface RuntimeProbeResult {
     runtime: BotRuntimeId;
     /** The model asked for; null = the runtime's own default. */
     model: string | null;
+    /** The tool's plan ran out of usage (class `transient`). */
+    usageLimit?: boolean;
+    /** When that limit resets, as the tool wrote it ("9pm (Asia/Dhaka)"). */
+    resetsAt?: string;
     /** The CLI was too old for `from`, and the probe answered on `to`. */
     modelFallback?: {
         from: string;

package/dist/lib/bot/probe.js

@@ -15,7 +15,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { classifyRuntimeError } from "./runtime-failure.js";
+import { classifyRuntimeError, isRuntimeUsageLimit, usageLimitResetsAt } from "./runtime-failure.js";
 import { runtimeDisplayName } from "./runtime-sign-in.js";
 import { RuntimeError, runRuntimeTurn, runtimeFor } from "./runtime/index.js";
 import { turnEnv } from "./run.js";
@@ -24,8 +24,12 @@ export const PROBE_SYSTEM_PROMPT = "You are an HQ bot being checked before it is
 /** A probe that has not answered by then is reported as `transient`. */
 export const PROBE_DEFAULT_TIMEOUT_MS = 120_000;
 /** The plain sentence for a failed probe: what is wrong and the one fix. */
-export function probeFailureText(cls, runtime) {
+export function probeFailureText(cls, runtime, usageLimit) {
     const tool = runtimeDisplayName(runtime);
+    if (cls === "transient" && usageLimit) {
+        const when = usageLimit.resetsAt ? ` It resets ${usageLimit.resetsAt}.` : "";
+        return `${tool} has hit its plan's usage limit.${when} Check again after it resets, or pick another tool.`;
+    }
     switch (cls) {
         case "signed-out":
             return `${tool} is not signed in on this computer. Sign in to ${tool} in HQ, then check again.`;
@@ -84,11 +88,15 @@ export async function probeBotRuntime(opts) {
         const raw = err instanceof RuntimeError ? `${err.message}\n${err.stderrExcerpt}` : err instanceof Error ? err.message : String(err);
         // Same rule as a bot turn: the runtime's reported error decides, never a tail of its output.
         const cls = classifyRuntimeError(err);
+        const limited = cls === "transient" && isRuntimeUsageLimit(raw);
+        const resetsAt = limited ? usageLimitResetsAt(raw) : undefined;
         return {
             ok: false,
             class: cls,
-            detail: probeFailureText(cls, opts.runtime),
+            detail: probeFailureText(cls, opts.runtime, limited ? { resetsAt } : undefined),
             ...base,
+            ...(limited ? { usageLimit: true } : {}),
+            ...(resetsAt ? { resetsAt } : {}),
             diagnostic: raw.slice(0, 400),
             durationMs: now() - started,
         };

package/dist/lib/bot/run.d.ts

@@ -71,6 +71,15 @@ export declare const API_BACKOFF_CAP_MS: number;
 /** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
 export declare const API_RETRY_AFTER_CAP_MS: number;
 export declare const API_RETRY_AFTER_FLOOR_MS = 1000;
+/**
+ * Delays between startup identity-check tries when HQ cannot be reached
+ * (five tries over about three minutes). After the last one the bot stops in
+ * a visible failed state the person can retry.
+ */
+export declare const STARTUP_VERIFY_RETRY_DELAYS_MS: readonly number[];
+export declare function isTransientApiError(err: unknown): boolean;
+/** Plain failed-state reason after the startup retries run out. */
+export declare function startupUnreachableReason(name: string): string;
 /**
  * How long to wait after a failed inbox poll or heartbeat.
  * 429/5xx (and transport errors) back off exponentially, honouring Retry-After