@indigoai-us/hq-cli 5.345.189 → 5.345.190

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [5.345.190] — 2026-11-01
+- `hq files purge <path> --version-id <id>` permanently deletes one old version of a vault file, after a confirmation prompt.
+- `hq bot create` / `hq bot start` on Windows: the shared HQ Fleet Runtime now
+  installs under `%USERPROFILE%\.hq-fleet\runtimes\<16 hex>\{v,s\r,s\d}` instead
+  of the 64-character identity plus `sources\runtime`, so the runtime's deepest
+  files stay under the 260-character Windows path limit when long paths are
+  off. Before, extraction stopped partway with "HQ Fleet Local runtime
+  extraction failed." Runtimes already installed under the old layout keep
+  working, and a half-extracted old one is removed. macOS and Linux paths are
+  unchanged.
+- HQ Fleet Local install steps now include the last lines of the failing
+  command's stderr in their error, and on Windows the CLI checks the runtime
+  archive's longest path before extracting and names the path limit and
+  `LongPathsEnabled` setting when it would not fit.
+- The CLI now warns on stderr when the HQ Fleet Local release manifest's
+  `compatibility.minimum_hq_cli_version` is newer than the running CLI. It does
+  not block the install.
+- `hq-hook`: the `block-credential-file-read` port follows the fixed bash guard
+  (hq-core-staging #1753, sha256 7c6a8cfa) and its pin moves to that version.
+  Zero-padded brace ranges are read in base 10 and long or stepped ranges
+  block; letter ranges expand exactly; the mktemp scan replacement is literal
+  (no `patsub_replacement`) with capped loops; `function name { ... }` bodies
+  are analysed; extglob groups are an unknown word part; and `ls`, `stat` and
+  the other metadata commands are not trusted after an alias, hash, enable,
+  PATH change, a write into a bin directory, or when named by a path outside
+  /bin, /usr/bin, /sbin and /usr/sbin. The port also picks up the guard's
+  cygpath and `upstream-pin.env` changes. The vendored fixture and corpus are
+  refreshed. The port flag stays off.
+- `hq sync now`: when the push leg holds files after an account sign-in change
+  on this computer, the push line now shows the held count, prints how to
+  release them (`hq sync held`, `hq sync release-held`), skips the "Sync now
+  complete" line and exits 1. Before, it printed "0 uploaded, 0 skipped" and a
+  success line (feedback_2356e54f).
+
 ## [5.345.189] — 2026-11-01
 - A local bot that cannot reach HQ when it starts now retries the identity check up to five times
   (waits of 5 s, 15 s, 45 s and 2 min) on a network error (connection refused, reset, DNS failure,

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

@@ -3243,6 +3243,35 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly hidden: false;
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "purge";
+        readonly description: "Permanently delete ONE retained (noncurrent) version of an exact vault key, for example a version that held data which must not live in HQ. Owner only; audited; cannot be undone. Delete the file first if the version is current. Use --personal for your personal vault.";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] <path>";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "path";
+            readonly required: true;
+            readonly variadic: false;
+            readonly description: "";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--personal";
+            readonly description: "Target your own personal vault instead of a company vault (mutually exclusive with --company)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--version-id <id>";
+            readonly description: "Exact version ID to purge (see `hq files versions`)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "-y, --yes";
+            readonly description: "Skip the confirmation prompt (for scripts)";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "trash";
         readonly description: "List deleted vault keys retained as tombstones. Use --personal for your personal vault.";

package/dist/command-catalog.generated.js

@@ -3912,6 +3912,42 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "purge",
+                "description": "Permanently delete ONE retained (noncurrent) version of an exact vault key, for example a version that held data which must not live in HQ. Owner only; audited; cannot be undone. Delete the file first if the version is current. Use --personal for your personal vault.",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] <path>",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "path",
+                        "required": true,
+                        "variadic": false,
+                        "description": ""
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--personal",
+                        "description": "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--version-id <id>",
+                        "description": "Exact version ID to purge (see `hq files versions`)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "-y, --yes",
+                        "description": "Skip the confirmation prompt (for scripts)",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "trash",
                 "description": "List deleted vault keys retained as tombstones. Use --personal for your personal vault.",

package/dist/commands/cloud.js

@@ -2351,12 +2351,19 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         }
         const pushProgressCompany = personalMode ? null : (pushSlug ?? null);
         const planLimitTracker = createPlanLimitRefusalTracker(companySlugForBilling(pushProgressCompany));
+        // feedback_2356e54f: the push leg held files after an account switch and
+        // still printed "0 uploaded, 0 skipped" and "Sync now complete".
+        const pushIdentityHeld = createIdentityHeldTracker();
+        const pushRecord = trackingProgressRecorder(planLimitTracker, pushProgressCompany);
         const pushResult = await share({
             paths: pushPaths,
             company: targetCompany,
             vaultConfig,
             hqRoot,
-            progressRecorder: trackingProgressRecorder(planLimitTracker, pushProgressCompany),
+            progressRecorder: (event) => {
+                pushIdentityHeld.observe(event);
+                pushRecord(event);
+            },
             skipUnchanged: true,
             serverOwnedPathPolicy: "skip",
             propagateDeletes: true,
@@ -2370,7 +2377,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         });
         const pushRefused = planLimitTracker.summary();
         const pushUploadFailed = readUploadFailures(pushResult);
+        const pushHeldCount = pushIdentityHeld.count();
         const pushStatus = pushResult.aborted ||
+            pushHeldCount > 0 ||
             pushResult.filesExcludedByScope > 0 ||
             (pushResult.filesRefusedStale ?? 0) > 0 ||
             pushUploadFailed.count > 0 ||
@@ -2380,6 +2389,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         console.log(`    ${pushStatus} ` +
             `${pushResult.filesUploaded} uploaded, ${pushResult.filesSkipped} skipped, ` +
             `${pushResult.filesDeleted} deleted, ${pushResult.filesExcludedByScope} scope-excluded` +
+            (pushHeldCount > 0 ? `, ${pushHeldCount} held` : "") +
             (pushResult.aborted ? " — aborted" : "") +
             (pushRefused
                 ? ` — ${describeRefusedCount(pushRefused)} refused (new files paused)`
@@ -2397,6 +2407,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         for (const line of uploadFailedLines(pushUploadFailed.count, pushUploadFailed.paths)) {
             console.log(chalk.yellow(line));
         }
+        for (const line of identityHeldLines(pushHeldCount)) {
+            console.log(chalk.yellow(line));
+        }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             throw new SyncExitError(1);
@@ -2519,7 +2532,8 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         }
         if (pushResult.filesExcludedByScope > 0 ||
             (pushResult.filesRefusedStale ?? 0) > 0 ||
-            pushUploadFailed.count > 0) {
+            pushUploadFailed.count > 0 ||
+            pushHeldCount > 0) {
             console.log(chalk.yellow("\n⚠ Sync now finished, but one or more requested uploads were refused."));
             throw new SyncExitError(1, { health: "succeeded" });
         }

package/dist/commands/files.d.ts

@@ -242,6 +242,24 @@ export declare function runFilesRestore(params: {
 }, deps?: {
     confirm?: ConfirmFn;
 }): Promise<FilesRestoreResponse | undefined>;
+export interface FilesPurgeResponse {
+    key: string;
+    purgedVersionId: string;
+}
+/**
+ * feedback_fc711fc3: permanently delete one noncurrent version. The server
+ * (hq-pro POST /v1/files/restore, action "purge") enforces owner-only access,
+ * refuses the current version and delete markers, and audits before deleting.
+ */
+export declare function runFilesPurge(params: {
+    key: string;
+    versionId: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+}, deps?: {
+    confirm?: ConfirmFn;
+}): Promise<FilesPurgeResponse | undefined>;
 export declare function runFilesTrash(params: {
     prefix: string;
     cursor?: string;

package/dist/commands/files.js

@@ -731,6 +731,30 @@ export function registerFilesCommand(program) {
             process.exit(1);
         }
     });
+    files
+        .command("purge <path>")
+        .description("Permanently delete ONE retained (noncurrent) version of an exact vault key, for example a version that held data which must not live in HQ. Owner only; audited; cannot be undone. Delete the file first if the version is current. Use --personal for your personal vault.")
+        .option("--personal", "Target your own personal vault instead of a company vault (mutually exclusive with --company)")
+        .requiredOption("--version-id <id>", "Exact version ID to purge (see `hq files versions`)")
+        .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+        .action(async (path, opts) => {
+        try {
+            const companySlug = files.opts().company;
+            const personal = opts.personal === true;
+            assertRecoveryScope(personal, companySlug);
+            await runFilesPurge({
+                key: path,
+                versionId: opts.versionId,
+                yes: opts.yes === true,
+                personal,
+                companySlug,
+            });
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     files
         .command("trash")
         .description("List deleted vault keys retained as tombstones. Use --personal for your personal vault.")
@@ -1767,6 +1791,55 @@ export async function runFilesRestore(params, deps = {}) {
     console.log(chalk.dim("New version: " + data.newVersionId));
     return data;
 }
+/**
+ * feedback_fc711fc3: permanently delete one noncurrent version. The server
+ * (hq-pro POST /v1/files/restore, action "purge") enforces owner-only access,
+ * refuses the current version and delete markers, and audits before deleting.
+ */
+export async function runFilesPurge(params, deps = {}) {
+    assertExactRecoveryKey(params.key);
+    if (typeof params.versionId !== "string" || params.versionId.trim() === "") {
+        throw new Error("--version-id is required and must not be empty.");
+    }
+    const confirm = deps.confirm ?? realConfirm;
+    if (!params.yes) {
+        const ok = await confirm("Permanently delete version '" + params.versionId + "' of '" + params.key + "'" +
+            (params.personal ? " in your personal vault" : "") +
+            "? This cannot be undone.");
+        if (!ok) {
+            console.log(chalk.dim("Aborted — nothing was purged."));
+            return undefined;
+        }
+    }
+    const scope = await resolveRecoveryScope(params);
+    const body = scope.personal
+        ? { personal: true, key: params.key }
+        : { company: scope.companyUid, key: params.key };
+    body.action = "purge";
+    body.purgeVersionId = params.versionId;
+    // Tripwire: a server without purge support rejects `versionId: null` with
+    // 400 instead of ignoring `action` and restoring (re-publishing) the version.
+    body.versionId = null;
+    const res = await vaultApiFetch({
+        token: scope.token,
+        path: "/v1/files/restore",
+        method: "POST",
+        body,
+    });
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => ({})));
+        const err = new FilesRecoveryHttpError(res.status, errBody.message ?? errBody.error ?? res.statusText, errBody.code);
+        throw new Error(formatFilesRecoveryError(err, params.key));
+    }
+    const data = (await res.json());
+    // Belt and braces with the tripwire above: only a server that echoes the
+    // purged version id has purged it.
+    if (data.purgedVersionId !== params.versionId) {
+        throw new Error("The server did not confirm the purge (it may not support purge yet). Check `hq files versions` before retrying.");
+    }
+    console.log(chalk.green("Purged version '" + data.purgedVersionId + "' of '" + params.key + "'."));
+    return { key: data.key ?? params.key, purgedVersionId: data.purgedVersionId };
+}
 export async function runFilesTrash(params) {
     if (params.prefix.includes("*")) {
         throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");

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,6 +165,12 @@ 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;
+/**
+ * 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;
@@ -172,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,6 +147,29 @@ export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE,
         throw expectedError(`HQ Fleet Local ${release.version} manifest signature is invalid.`);
     }
 }
+/**
+ * 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) {
@@ -305,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;
@@ -316,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 {
@@ -377,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;
@@ -426,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");
@@ -484,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")))
@@ -639,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 });
@@ -757,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 = {
@@ -772,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")),
         },
@@ -833,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.");
     }
@@ -867,14 +942,82 @@ 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 = {}) {
     const run = deps.run ?? execFileSync;
@@ -902,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 });
@@ -933,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",
@@ -961,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) {
@@ -988,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.189",
+  "version": "5.345.190",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.189",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.189",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.189",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.189",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.189",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.189"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.190",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.190",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.190",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.190",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.190",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.190"
   }
 }