@indigoai-us/hq-cli 5.345.190 → 5.345.193

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

@@ -1,8 +1,9 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as zlib from "node:zlib";
 import { HQ_FLEET_RUNTIME_ENGINE_ID, } from "./config.js";
 import { withBotLock } from "./lock.js";
 import { ensureFleetPython, fleetUvEnv } from "./fleet-python.js";
@@ -78,20 +79,47 @@ export function sharedRuntimeLayout(root, id, platform) {
 }
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.17",
-    version: "0.4.17",
-    artifact: "hq-fleet-local-0.4.17.zip",
-    artifactSha256: "d2c5c49d4ef47da6003f4c2f3be7dcd2d8a287523c8577dfe0239e6e0705e4b4",
+    tag: "v0.4.20",
+    version: "0.4.20",
+    artifact: "hq-fleet-local-0.4.20.zip",
+    artifactSha256: "5c49402f17408f3eaf99d27b3c2d4d0f59a24f33946aa8dfc3098a3d09e13798",
     runtimeArtifact: "hq-fleet-runtime-abccac13bd9e.tar",
     runtimeArtifactSha256: "29bcfe718ad7fbd3636afd00623772f2a25bc84c4f6f10d8d57f38e549d528d5",
-    manifestSha256: "63663ffe8c6bef4f2aefa587d20431156cab4170a0f23533cdab7aab444a7d35",
-    signatureSha256: "bb4af0b453ae03fdbc18e6335ca23e2f0de42bd9e322dba7c4f31d0c8dc08aa7",
+    manifestSha256: "3cec47eb7f47af13e66d4ad29669d3c103e1ca452661f5eaad760243118ce214",
+    signatureSha256: "5504c3a956f36d148f3cdf2212a9b171d852098c82eb199c7c415ad3545e3b05",
     runtimeCommit: "abccac13bd9ea593b24c8cd9c0ba28d5c6050cc9",
 };
+/** hq-fleet-local trust/release-public.pem (rotated 2026-10-30; signed v0.4.17). */
 export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
 MCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=
 -----END PUBLIC KEY-----
 `;
+/** hq-fleet-local trust/release-public-v2.pem (added 2026-11-01; signs v0.4.18). */
+export const HQ_FLEET_LOCAL_PUBLIC_KEY_V2 = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAmgUi7pKTJUmf3yzwcuH65wSvn1NyJrDfZHZUX08sGN8=
+-----END PUBLIC KEY-----
+`;
+/** hq-fleet-local trust/release-public-v3.pem (added 2026-11-02; signs v0.4.20 and later). */
+export const HQ_FLEET_LOCAL_PUBLIC_KEY_V3 = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEA2NUo6F38D4Kjxmy5qz5ytKRVRwocEvPk8lXqfwB2kS0=
+-----END PUBLIC KEY-----
+`;
+/** Every key a release manifest may be signed with. Any one must verify it. */
+export const HQ_FLEET_LOCAL_PUBLIC_KEYS = [HQ_FLEET_LOCAL_PUBLIC_KEY, HQ_FLEET_LOCAL_PUBLIC_KEY_V2, HQ_FLEET_LOCAL_PUBLIC_KEY_V3];
+function publicKeyList(publicKey) {
+    return typeof publicKey === "string" ? [publicKey] : publicKey;
+}
+/** True when any trusted Ed25519 key verifies the manifest signature. */
+export function fleetLocalManifestSignatureValid(manifest, signature, publicKey = HQ_FLEET_LOCAL_PUBLIC_KEYS) {
+    return publicKeyList(publicKey).some((key) => {
+        try {
+            return crypto.verify(null, manifest, crypto.createPublicKey(key), signature);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 function digest(value) {
     return crypto.createHash("sha256").update(value).digest("hex");
 }
@@ -110,7 +138,7 @@ function engineMetadata(release) {
 export function fleetHome(home = os.homedir(), env = process.env) {
     return env.HQ_FLEET_HOME?.trim() || path.join(home, ".hq-fleet");
 }
-export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE, publicKey = HQ_FLEET_LOCAL_PUBLIC_KEY) {
+export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE, publicKey = HQ_FLEET_LOCAL_PUBLIC_KEYS) {
     if (digest(files.archive) !== release.artifactSha256) {
         throw expectedError(`HQ Fleet Local ${release.version} archive hash did not match the release pin.`);
     }
@@ -142,10 +170,180 @@ export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE,
     if (signature.algorithm !== "ed25519" || typeof signature.signature !== "string") {
         throw expectedError(`HQ Fleet Local ${release.version} signature record is invalid.`);
     }
-    const valid = crypto.verify(null, files.manifest, crypto.createPublicKey(publicKey), Buffer.from(signature.signature, "base64"));
+    const valid = fleetLocalManifestSignatureValid(files.manifest, Buffer.from(signature.signature, "base64"), publicKey);
     if (!valid) {
         throw expectedError(`HQ Fleet Local ${release.version} manifest signature is invalid.`);
     }
+    if (typeof runtime.archive_sha256 !== "string" || runtime.archive_sha256 !== digest(files.runtimeArchive)) {
+        throw expectedError(`HQ Fleet Local ${release.version} runtime archive does not match the signed manifest.`);
+    }
+    verifyArchiveAgainstManifest(files, manifest, release);
+}
+const RELEASE_METADATA_ENTRIES = new Set(["release-manifest.json", "release-manifest.sig", "release-public.pem"]);
+const MAX_ARCHIVE_ENTRIES = 20_000;
+const MAX_ARCHIVE_ENTRY_BYTES = 64 * 1024 * 1024;
+function verifyArchiveAgainstManifest(files, manifest, release) {
+    const payload = manifest.payload;
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).length === 0) {
+        throw expectedError(`HQ Fleet Local ${release.version} manifest lists no payload files.`);
+    }
+    let entries;
+    try {
+        entries = readZipEntries(files.archive);
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local ${release.version} archive could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const [name, expected] of Object.entries(payload)) {
+        const entry = entries.get(name);
+        const sha = expected && typeof expected === "object" ? expected.sha256 : undefined;
+        if (!entry || typeof sha !== "string" || digest(entry) !== sha) {
+            throw expectedError(`HQ Fleet Local ${release.version} archive file ${name} does not match the signed manifest.`);
+        }
+    }
+    for (const [name, entry] of entries) {
+        if (Object.prototype.hasOwnProperty.call(payload, name))
+            continue;
+        if (!RELEASE_METADATA_ENTRIES.has(name)) {
+            throw expectedError(`HQ Fleet Local ${release.version} archive has a file the signed manifest does not list: ${name}`);
+        }
+        if (name === "release-manifest.json" && !entry.equals(files.manifest)) {
+            throw expectedError(`HQ Fleet Local ${release.version} archive carries a different manifest.`);
+        }
+    }
+}
+/**
+ * Check an extracted distribution against the signed manifest: every payload
+ * file present with its hash, and nothing else but the release metadata.
+ */
+export function verifyExtractedDistribution(dir, manifest, version) {
+    let payload;
+    try {
+        const parsed = JSON.parse(manifest.toString("utf8"));
+        if (!parsed.payload || typeof parsed.payload !== "object" || Array.isArray(parsed.payload))
+            throw new Error("no payload");
+        payload = parsed.payload;
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local ${version} manifest has no payload list: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const seen = new Set();
+    const walk = (current, prefix) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = path.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                throw expectedError(`HQ Fleet Local ${version} extracted a link the signed manifest does not list: ${relative}`);
+            if (entry.isDirectory()) {
+                walk(full, relative);
+                continue;
+            }
+            if (Object.prototype.hasOwnProperty.call(payload, relative)) {
+                const expected = payload[relative];
+                const sha = expected && typeof expected === "object" ? expected.sha256 : undefined;
+                if (typeof sha !== "string" || digest(fs.readFileSync(full)) !== sha) {
+                    throw expectedError(`HQ Fleet Local ${version} extracted file ${relative} does not match the signed manifest.`);
+                }
+                seen.add(relative);
+                continue;
+            }
+            if (!RELEASE_METADATA_ENTRIES.has(relative)) {
+                throw expectedError(`HQ Fleet Local ${version} extracted a file the signed manifest does not list: ${relative}`);
+            }
+        }
+    };
+    walk(dir, "");
+    for (const name of Object.keys(payload)) {
+        if (!seen.has(name))
+            throw expectedError(`HQ Fleet Local ${version} extracted distribution is missing ${name}.`);
+    }
+}
+/** Write a ZIP archive's files under `target` with the same reader that verified it. */
+export function extractZipEntries(archive, target, version) {
+    let entries;
+    try {
+        entries = readZipEntries(archive);
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local ${version} archive could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const root = path.resolve(target);
+    for (const [name, content] of entries) {
+        const parts = name.split("/");
+        if (name.includes("\\") || name.startsWith("/") || /^[A-Za-z]:/.test(name) || parts.some((part) => part === "" || part === "." || part === "..")) {
+            throw expectedError(`HQ Fleet Local ${version} archive has an unsafe file name: ${name}`);
+        }
+        const destination = path.join(root, ...parts);
+        if (!destination.startsWith(root + path.sep))
+            throw expectedError(`HQ Fleet Local ${version} archive has an unsafe file name: ${name}`);
+        fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(destination, content, { mode: 0o644 });
+    }
+}
+/** Every file in a ZIP archive by name (stored and deflated entries only; directories skipped). */
+export function readZipEntries(archive) {
+    const eocdSignature = 0x06054b50;
+    let eocd = -1;
+    for (let at = archive.length - 22; at >= Math.max(0, archive.length - 22 - 0xffff); at -= 1) {
+        if (archive.readUInt32LE(at) === eocdSignature) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error("no end of central directory");
+    const count = archive.readUInt16LE(eocd + 10);
+    const directorySize = archive.readUInt32LE(eocd + 12);
+    const directoryOffset = archive.readUInt32LE(eocd + 16);
+    if (count === 0xffff || directoryOffset === 0xffffffff || count > MAX_ARCHIVE_ENTRIES)
+        throw new Error("unsupported archive size");
+    if (directoryOffset + directorySize !== eocd)
+        throw new Error("central directory is not where the archive end says");
+    if (eocd >= 20 && archive.readUInt32LE(eocd - 20) === 0x07064b50)
+        throw new Error("zip64 archives are not supported");
+    if (count > 0 && archive.readUInt32LE(0) !== 0x04034b50)
+        throw new Error("data before the first entry");
+    const entries = new Map();
+    let at = directoryOffset;
+    for (let index = 0; index < count; index += 1) {
+        if (at + 46 > eocd || archive.readUInt32LE(at) !== 0x02014b50)
+            throw new Error("bad central directory entry");
+        const flags = archive.readUInt16LE(at + 8);
+        const method = archive.readUInt16LE(at + 10);
+        const compressedSize = archive.readUInt32LE(at + 20);
+        const size = archive.readUInt32LE(at + 24);
+        const nameLength = archive.readUInt16LE(at + 28);
+        const extraLength = archive.readUInt16LE(at + 30);
+        const commentLength = archive.readUInt16LE(at + 32);
+        const localOffset = archive.readUInt32LE(at + 42);
+        const name = archive.subarray(at + 46, at + 46 + nameLength).toString("utf8");
+        at += 46 + nameLength + extraLength + commentLength;
+        if (name.endsWith("/"))
+            continue;
+        if ((flags & 0x1) !== 0)
+            throw new Error(`encrypted entry ${name}`);
+        if (size > MAX_ARCHIVE_ENTRY_BYTES || compressedSize > MAX_ARCHIVE_ENTRY_BYTES)
+            throw new Error(`entry too large: ${name}`);
+        if (entries.has(name))
+            throw new Error(`duplicate entry ${name}`);
+        if (localOffset + 30 > directoryOffset || archive.readUInt32LE(localOffset) !== 0x04034b50)
+            throw new Error(`bad local header for ${name}`);
+        const dataStart = localOffset + 30 + archive.readUInt16LE(localOffset + 26) + archive.readUInt16LE(localOffset + 28);
+        if (dataStart + compressedSize > directoryOffset)
+            throw new Error(`entry out of range: ${name}`);
+        const data = archive.subarray(dataStart, dataStart + compressedSize);
+        let content;
+        if (method === 0)
+            content = Buffer.from(data);
+        else if (method === 8)
+            content = zlib.inflateRawSync(data, { maxOutputLength: MAX_ARCHIVE_ENTRY_BYTES });
+        else
+            throw new Error(`unsupported compression for ${name}`);
+        if (content.length !== size)
+            throw new Error(`size mismatch for ${name}`);
+        entries.set(name, content);
+    }
+    return entries;
 }
 /**
  * Warning text when the signed manifest asks for a newer hq CLI than this
@@ -225,6 +423,196 @@ export async function fetchHqFleetReleaseLinks(release) {
     }
     return links.size > 0 ? links : null;
 }
+export const FLEET_LOCAL_LATEST_TIMEOUT_MS = 5_000;
+export const FLEET_LOCAL_LATEST_CACHE_MS = 10 * 60_000;
+const FLEET_LOCAL_LATEST_CACHE_FILE = "release-pointer.json";
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const COMMIT_RE = /^[0-9a-f]{40}$/;
+export function parseFleetLocalReleasePin(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const keys = [
+        "repository",
+        "tag",
+        "version",
+        "artifact",
+        "artifactSha256",
+        "runtimeArtifact",
+        "runtimeArtifactSha256",
+        "manifestSha256",
+        "signatureSha256",
+        "runtimeCommit",
+    ];
+    if (!keys.every((key) => typeof record[key] === "string" && record[key].length > 0))
+        return null;
+    const pin = Object.fromEntries(keys.map((key) => [key, record[key]]));
+    if (pin.repository !== HQ_FLEET_LOCAL_RELEASE.repository)
+        return null;
+    if (!semver.valid(pin.version) || semver.clean(pin.version) !== pin.version)
+        return null;
+    if (pin.tag !== `v${pin.version}` || pin.artifact !== `hq-fleet-local-${pin.version}.zip`)
+        return null;
+    if (!COMMIT_RE.test(pin.runtimeCommit))
+        return null;
+    if (pin.runtimeArtifact !== `hq-fleet-runtime-${pin.runtimeCommit.slice(0, 12)}.tar`)
+        return null;
+    if (![pin.artifactSha256, pin.runtimeArtifactSha256, pin.manifestSha256, pin.signatureSha256].every((hash) => SHA256_RE.test(hash))) {
+        return null;
+    }
+    return pin;
+}
+export function parseFleetLocalReleasePointer(body, now = Date.now()) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const record = body;
+    const release = parseFleetLocalReleasePin(record.release);
+    if (!release || record.version !== release.version)
+        return null;
+    const minimumHqCli = typeof record.minimumHqCli === "string" && semver.valid(semver.coerce(record.minimumHqCli))
+        ? record.minimumHqCli
+        : null;
+    if (record.minimumHqCli !== undefined && record.minimumHqCli !== null && minimumHqCli === null)
+        return null;
+    const links = new Map();
+    for (const asset of Array.isArray(record.assets) ? record.assets : []) {
+        const entry = asset;
+        if (typeof entry?.name === "string" && typeof entry.url === "string")
+            links.set(entry.name, entry.url);
+    }
+    const expires = typeof record.expiresInSeconds === "number" && record.expiresInSeconds > 0 ? record.expiresInSeconds : 0;
+    return {
+        release,
+        minimumHqCli,
+        links: links.size > 0 && expires > 0 ? links : null,
+        linksExpireAt: links.size > 0 && expires > 0 ? now + expires * 1000 : null,
+    };
+}
+export function chooseFleetLocalTargetRelease(pointer, compiled = HQ_FLEET_LOCAL_RELEASE, cliVersion = CLI_VERSION) {
+    const fallback = { release: compiled, source: "compiled", links: null, linksExpireAt: null };
+    if (!pointer || !semver.gt(pointer.release.version, compiled.version))
+        return fallback;
+    if (pointer.minimumHqCli) {
+        const required = semver.valid(semver.coerce(pointer.minimumHqCli));
+        const current = semver.valid(semver.coerce(cliVersion));
+        if (!required || !current || semver.lt(current, required))
+            return fallback;
+    }
+    return { release: pointer.release, source: "pointer", links: pointer.links, linksExpireAt: pointer.linksExpireAt };
+}
+export async function fetchFleetLocalReleasePointer(deps = {}) {
+    const token = await (deps.token ?? (() => ensureCognitoToken({ tokenSource: "person", interactive: false })))();
+    const response = await (deps.fetchApi ?? vaultApiFetch)({
+        token,
+        path: "/v1/fleet-local/releases/latest",
+        signal: AbortSignal.timeout(FLEET_LOCAL_LATEST_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        return null;
+    return parseFleetLocalReleasePointer(await response.json(), (deps.now ?? Date.now)());
+}
+let memoryPointer = null;
+export function resetFleetLocalReleasePointerCache() {
+    memoryPointer = null;
+}
+function readPointerCache(root, now) {
+    if (memoryPointer && memoryPointer.root === root && now - memoryPointer.fetchedAt < FLEET_LOCAL_LATEST_CACHE_MS) {
+        return { body: memoryPointer.body };
+    }
+    try {
+        const cached = JSON.parse(fs.readFileSync(path.join(root, FLEET_LOCAL_LATEST_CACHE_FILE), "utf8"));
+        if (typeof cached.fetchedAt === "number" && now - cached.fetchedAt >= 0 && now - cached.fetchedAt < FLEET_LOCAL_LATEST_CACHE_MS) {
+            memoryPointer = { root, fetchedAt: cached.fetchedAt, body: cached.pointer };
+            return { body: cached.pointer };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function writePointerCache(root, now, body) {
+    memoryPointer = { root, fetchedAt: now, body };
+    try {
+        fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+        const file = path.join(root, FLEET_LOCAL_LATEST_CACHE_FILE);
+        const temporary = `${file}.${process.pid}.${crypto.randomUUID()}`;
+        fs.writeFileSync(temporary, `${JSON.stringify({ fetchedAt: now, pointer: body })}\n`, { mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    catch {
+        return;
+    }
+}
+function pointerToCache(pointer) {
+    if (!pointer)
+        return null;
+    return {
+        release: pointer.release,
+        minimumHqCli: pointer.minimumHqCli,
+        links: pointer.links ? [...pointer.links.entries()] : null,
+        linksExpireAt: pointer.linksExpireAt,
+    };
+}
+function pointerFromCache(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const release = parseFleetLocalReleasePin(record.release);
+    if (!release)
+        return null;
+    const links = Array.isArray(record.links)
+        ? new Map(record.links.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "string"))
+        : null;
+    return {
+        release,
+        minimumHqCli: typeof record.minimumHqCli === "string" ? record.minimumHqCli : null,
+        links: links && links.size > 0 ? links : null,
+        linksExpireAt: typeof record.linksExpireAt === "number" ? record.linksExpireAt : null,
+    };
+}
+async function loadFleetLocalReleasePointer(deps) {
+    const root = deps.fleetHome ?? fleetHome();
+    const now = (deps.now ?? Date.now)();
+    const cached = readPointerCache(root, now);
+    if (cached)
+        return pointerFromCache(cached.body);
+    try {
+        const pointer = await (deps.fetchPointer ?? (() => fetchFleetLocalReleasePointer()))();
+        writePointerCache(root, now, pointerToCache(pointer));
+        return pointer;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveFleetLocalTargetRelease(deps = {}) {
+    const pointer = await loadFleetLocalReleasePointer(deps);
+    return chooseFleetLocalTargetRelease(pointer, deps.compiled ?? HQ_FLEET_LOCAL_RELEASE, deps.cliVersion ?? CLI_VERSION);
+}
+export async function resolveFleetLocalPointerTarget(deps = {}) {
+    const pointer = await loadFleetLocalReleasePointer(deps);
+    if (!pointer)
+        return null;
+    if (pointer.minimumHqCli) {
+        const required = semver.valid(semver.coerce(pointer.minimumHqCli));
+        const current = semver.valid(semver.coerce(deps.cliVersion ?? CLI_VERSION));
+        if (!required || !current || semver.lt(current, required))
+            return null;
+    }
+    return { release: pointer.release, source: "pointer", links: pointer.links, linksExpireAt: pointer.linksExpireAt };
+}
+export async function installTargetFleetLocalDistribution(deps = {}) {
+    const target = deps.target ?? await resolveFleetLocalTargetRelease({ ...(deps.fleetHome ? { fleetHome: deps.fleetHome } : {}) });
+    const now = (deps.now ?? Date.now)();
+    const freshLinks = target.links && target.linksExpireAt !== null && target.linksExpireAt - now > 60_000 ? target.links : null;
+    const { target: _target, now: _now, ...installDeps } = deps;
+    return installPinnedFleetLocalDistribution({
+        ...installDeps,
+        release: target.release,
+        ...(freshLinks && !installDeps.hqReleaseLinks ? { hqReleaseLinks: async () => freshLinks } : {}),
+    });
+}
 function trustedReleaseLink(url) {
     try {
         const parsed = new URL(url);
@@ -326,7 +714,7 @@ function installFiles(target, files, release, publicKey) {
         fs.writeFileSync(path.join(staging, release.runtimeArtifact), files.runtimeArchive, { mode: 0o644 });
         fs.writeFileSync(path.join(staging, "release-manifest.json"), files.manifest, { mode: 0o644 });
         fs.writeFileSync(path.join(staging, "release-manifest.sig"), files.signature, { mode: 0o644 });
-        fs.writeFileSync(path.join(staging, "release-public.pem"), publicKey, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, "release-public.pem"), publicKeyList(publicKey).join(""), { mode: 0o644 });
         fs.writeFileSync(path.join(staging, "install.json"), `${JSON.stringify({ schemaVersion: 1, release, engine: engineMetadata(release) }, null, 2)}\n`, { mode: 0o644 });
         if (fs.existsSync(target))
             fs.renameSync(target, backup);
@@ -366,7 +754,7 @@ function cachedRuntimeArchive(root, release) {
 }
 export async function installPinnedFleetLocalDistribution(deps = {}) {
     const release = deps.release ?? HQ_FLEET_LOCAL_RELEASE;
-    const publicKey = deps.publicKey ?? HQ_FLEET_LOCAL_PUBLIC_KEY;
+    const publicKey = deps.publicKey ?? HQ_FLEET_LOCAL_PUBLIC_KEYS;
     const root = deps.fleetHome ?? fleetHome();
     const dir = path.join(root, "distributions", "hq-fleet-local", release.version);
     const current = installedFiles(dir, release);
@@ -471,11 +859,15 @@ function profileEngineMatchesRelease(profileDir, release) {
     try {
         const marker = JSON.parse(fs.readFileSync(path.join(profileDir, "bootstrap.json"), "utf8"));
         const expected = engineMetadata(release);
-        return marker.engine?.id === expected.id &&
-            marker.engine.distribution === expected.distribution &&
-            marker.engine.version === expected.version &&
+        if (marker.engine?.id !== expected.id || marker.engine.distribution !== expected.distribution)
+            return false;
+        if (marker.engine.version === expected.version &&
             marker.engine.artifactSha256 === expected.artifactSha256 &&
-            marker.engine.runtimeCommit === expected.runtimeCommit;
+            marker.engine.runtimeCommit === expected.runtimeCommit) {
+            return true;
+        }
+        const installed = typeof marker.engine.version === "string" ? semver.valid(marker.engine.version) : null;
+        return installed !== null && semver.valid(expected.version) !== null && semver.gt(installed, expected.version);
     }
     catch {
         return false;
@@ -513,7 +905,8 @@ function fleetLocalExecutables(agentUid, deps) {
 function runJson(run, executable, args, options, label) {
     let output;
     try {
-        output = run(executable, args, { windowsHide: true, encoding: "utf8", ...options });
+        // windowsHide last: a helper, uv or Python child never opens a console window on Windows.
+        output = run(executable, args, { encoding: "utf8", ...options, windowsHide: true });
     }
     catch {
         throw expectedError(`HQ Fleet Local ${label} failed.`);
@@ -541,6 +934,31 @@ export function fleetLocalGatewayPid(agentUid, deps = {}) {
         return null;
     }
 }
+/** The first hq-fleet-local release whose profile schema accepts `autoApprove`; older ones reject unknown fields. */
+const AUTO_APPROVE_RELEASE = [0, 4, 19];
+function releaseKnowsAutoApprove(release) {
+    const parts = release.version.split(".").map((part) => Number.parseInt(part, 10));
+    for (let i = 0; i < AUTO_APPROVE_RELEASE.length; i += 1) {
+        const have = Number.isFinite(parts[i]) ? parts[i] : 0;
+        if (have !== AUTO_APPROVE_RELEASE[i])
+            return have > AUTO_APPROVE_RELEASE[i];
+    }
+    return true;
+}
+/**
+ * Whether the bot's HQ Fleet gateway is installed as a login service. The
+ * runtime registers it with launchd as `ai.hq-fleet.gateway-<profile>`; null
+ * on platforms where hq-cli does not know the service layout.
+ */
+export function fleetLocalServiceInstalled(agentUid, deps = {}) {
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid))
+        return null;
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "darwin")
+        return null;
+    const home = deps.home ?? os.homedir();
+    return fs.existsSync(path.join(home, "Library", "LaunchAgents", `ai.hq-fleet.gateway-${profileName(agentUid)}.plist`));
+}
 export function fleetLocalProfileNeedsAdoption(agentUid, deps = {}) {
     if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid))
         return true;
@@ -842,6 +1260,7 @@ export function writeFleetLocalProfile(input, deps = {}) {
         botId: input.agentUid,
         ownerUid: input.ownerUid,
         ...(input.ownerCompanies?.length ? { ownerCompanies: [...new Set(input.ownerCompanies)].sort() } : {}),
+        ...(input.autoApprove === true && releaseKnowsAutoApprove(input.installation.release) ? { autoApprove: true } : {}),
         provider: input.provider ?? { id: "custom:personal-chatgpt", model: "gpt-5.6-sol" },
         hqRoot: path.resolve(input.hqRoot),
         profileDir: path.resolve(dir),
@@ -934,6 +1353,97 @@ export function scanFleetLocalInstructions(agentUid, text, deps = {}) {
         throw failure;
     return parsed;
 }
+export function fleetLocalRuntimePython(agentUid, deps = {}) {
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid)) {
+        throw expectedError(`Cannot use an HQ Fleet profile for invalid bot id ${agentUid}.`);
+    }
+    const root = deps.fleetHome ?? fleetHome();
+    const profileDir = profileRoot(agentUid, root);
+    const platform = deps.platform ?? process.platform;
+    const shared = sharedRuntimeFromMarker(profileDir, root, platform);
+    const runtimeDir = shared?.runtimeDir ?? path.join(profileDir, "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 ${agentUid}.`);
+    }
+    return { python, source, profileDir };
+}
+export function fleetProfileOwnerCompanies(agentUid, deps = {}) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(fleetLocalProfileDir(agentUid, deps), "profile.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const companies = raw && typeof raw === "object" ? raw.ownerCompanies : undefined;
+    return Array.isArray(companies) ? companies.filter((slug) => typeof slug === "string" && /^[a-z0-9][a-z0-9_-]*$/i.test(slug)) : [];
+}
+export function fleetLocalProfileDir(agentUid, deps = {}) {
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid)) {
+        throw expectedError(`Cannot use an HQ Fleet profile for invalid bot id ${agentUid}.`);
+    }
+    return profileRoot(agentUid, deps.fleetHome ?? fleetHome());
+}
+export function readFleetLocalGatewayState(agentUid, deps = {}) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(fleetLocalProfileDir(agentUid, deps), "gateway_state.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const platforms = {};
+    if (raw.platforms && typeof raw.platforms === "object" && !Array.isArray(raw.platforms)) {
+        for (const [name, value] of Object.entries(raw.platforms)) {
+            const state = value?.state;
+            if (typeof state === "string" && state)
+                platforms[name] = state;
+        }
+    }
+    const active = Number(raw.active_agents);
+    return {
+        pid: typeof raw.pid === "number" && Number.isInteger(raw.pid) && raw.pid > 0 ? raw.pid : null,
+        gatewayState: typeof raw.gateway_state === "string" ? raw.gateway_state : null,
+        activeAgents: Number.isFinite(active) && active > 0 ? Math.floor(active) : 0,
+        platforms,
+    };
+}
+export function fleetLocalChannels(state, gatewayAlive) {
+    const lane = (name) => (gatewayAlive && state?.platforms[name]) || "not_connected";
+    return { slack: lane("slack"), telegram: lane("telegram") };
+}
+export function fleetLocalBusyReason(agentUid, deps = {}) {
+    const state = readFleetLocalGatewayState(agentUid, deps);
+    const alive = deps.isAlive ?? ((pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    });
+    if (!state || state.pid === null || !alive(state.pid))
+        return null;
+    if (state.activeAgents > 0)
+        return `${state.activeAgents} turn${state.activeAgents === 1 ? "" : "s"} in progress`;
+    if (state.gatewayState === "draining" || state.gatewayState === "starting")
+        return `gateway is ${state.gatewayState}`;
+    try {
+        const store = JSON.parse(fs.readFileSync(path.join(fleetLocalProfileDir(agentUid, deps), "cron", "jobs.json"), "utf8"));
+        const running = (store.jobs ?? []).find((job) => job && job.fire_claim !== null && job.fire_claim !== undefined);
+        if (running)
+            return typeof running.name === "string" && running.name ? `scheduled job "${running.name}" is running` : "a scheduled job is running";
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
 /** Checks the instructions with the runtime's scanner, then makes them the bot's persona. */
 export function refreshFleetLocalInstructions(agentUid, systemPrompt, deps = {}) {
     const findings = scanFleetLocalInstructions(agentUid, systemPrompt, deps);
@@ -952,23 +1462,79 @@ export function stderrTail(error) {
     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) {
+function checkedRun(run, executable, args, options, label, spawn) {
     // 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;
+    const requested = options.stdio === "ignore" ? ["ignore", "ignore", "pipe"] : options.stdio;
+    // Node only applies CREATE_NO_WINDOW when no stdio slot is inherited
+    // (libuv src/win/process.c), so windowsHide alone does not hide a child
+    // given an fd or "inherit". Pipe those slots and copy the output through.
+    const { stdio, forward } = pipeInheritedStdio(requested);
+    const spawnOptions = {
+        maxBuffer: 16 * 1024 * 1024,
+        ...options,
+        ...(stdio === undefined ? {} : { stdio }),
+        // Last, so no caller can turn it off: no console window flashes on Windows.
+        windowsHide: true,
+    };
+    if (forward) {
+        // spawnSync keeps stderr on success too (execFileSync drops it once stdio
+        // is set), so uv warnings and "Installed N packages" still reach the user.
+        const result = (spawn ?? spawnFromRun(run))(executable, args, spawnOptions);
+        copyChildOutput(result.stdout);
+        if (!result.error && result.status === 0) {
+            copyChildOutput(result.stderr);
+            return;
+        }
+        // On failure stderr appears once, as the tail in the error message.
+        const tail = stderrTail(result);
+        throw expectedError(`HQ Fleet Local ${label} failed.${tail ? `\n${tail}` : ""}`);
+    }
     try {
-        run(executable, args, {
-            windowsHide: true,
-            maxBuffer: 16 * 1024 * 1024,
-            ...options,
-            ...(stdio === undefined ? {} : { stdio }),
-        });
+        run(executable, args, spawnOptions);
     }
     catch (error) {
         const tail = stderrTail(error);
         throw expectedError(`HQ Fleet Local ${label} failed.${tail ? `\n${tail}` : ""}`);
     }
 }
+/** A FleetLocalSpawn backed by an execFileSync-shaped runner (stderr is only known on failure). */
+export function spawnFromRun(run) {
+    return (executable, args, options) => {
+        try {
+            return { status: 0, stdout: run(executable, args, options), stderr: "" };
+        }
+        catch (error) {
+            const failed = (error ?? {});
+            return { status: typeof failed.status === "number" ? failed.status : 1, stdout: failed.stdout ?? null, stderr: failed.stderr ?? null };
+        }
+    };
+}
+/**
+ * Replaces inherited stdio slots (an fd number or "inherit") with "pipe".
+ * `forward` is true when any slot was replaced, so the caller copies the
+ * captured output to this process's stderr.
+ */
+export function pipeInheritedStdio(stdio) {
+    if (stdio === "inherit")
+        return { stdio: ["ignore", "pipe", "pipe"], forward: true };
+    if (!Array.isArray(stdio))
+        return { stdio, forward: false };
+    let forward = false;
+    const piped = stdio.map((slot, index) => {
+        if (typeof slot === "number" || slot === "inherit") {
+            forward = true;
+            return index === 0 ? "ignore" : "pipe";
+        }
+        return slot;
+    });
+    return { stdio: piped, forward };
+}
+function copyChildOutput(output) {
+    const text = Buffer.isBuffer(output) ? output.toString("utf8") : typeof output === "string" ? output : "";
+    if (text)
+        process.stderr.write(text);
+}
 const FLEET_TAR_PATH_PROBE = [
     "import json, sys, tarfile",
     "longest = 0",
@@ -1036,7 +1602,7 @@ export function importFleetLocalMachineCredential(agentUid, machineCredentials,
     ], { input: machineValue, stdio: ["pipe", "ignore", "pipe"] }, "machine credential import");
     fs.rmSync(machineCredentials, { force: true });
 }
-async function installSharedFleetRuntime(installation, root, python, platform, run) {
+async function installSharedFleetRuntime(installation, root, python, platform, run, spawn) {
     const identity = digest(Buffer.from(JSON.stringify({
         version: installation.release.version,
         distribution: installation.release.artifactSha256,
@@ -1081,13 +1647,8 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
         fs.mkdirSync(distributionSource, { recursive: true, mode: 0o700 });
         fs.mkdirSync(runtimeSource, { recursive: true, mode: 0o700 });
         const uvEnv = fleetUvEnv(python.pythonDir);
-        checkedRun(run, python.python, [
-            "-m",
-            "zipfile",
-            "-e",
-            installation.archive,
-            distributionSource,
-        ], { stdio: "ignore" }, "distribution extraction");
+        extractZipEntries(fs.readFileSync(installation.archive), distributionSource, installation.release.version);
+        verifyExtractedDistribution(distributionSource, fs.readFileSync(installation.manifest), installation.release.version);
         if (platform === "win32")
             assertWindowsExtractionFits(run, python.python, installation.runtimeArchive, runtimeSource);
         checkedRun(run, python.python, [
@@ -1114,7 +1675,7 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             "--editable",
             `${runtimeSource}[mcp,anthropic]`,
             distributionSource,
-        ], { stdio: ["ignore", 2, 2], env: uvEnv }, "package installation");
+        ], { stdio: ["ignore", 2, 2], env: uvEnv }, "package installation", spawn);
         if (!executables.every((name) => fs.existsSync(venvExecutable(runtimeDir, name, platform)))) {
             throw expectedError("HQ Fleet Local installed without its runtime executables.");
         }
@@ -1140,7 +1701,8 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
     const python = deps.python ?? await ensureFleetPython({ fleetHome: root, platform, run });
     const profileDir = adoptLegacyProfileDirectory(input.agentUid, root);
     fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
-    const shared = await installSharedFleetRuntime(input.installation, root, python, platform, run);
+    const spawn = deps.spawn ?? (deps.run ? spawnFromRun(deps.run) : spawnSync);
+    const shared = await installSharedFleetRuntime(input.installation, root, python, platform, run, spawn);
     writeNativeProfileMarker(profileDir, shared, input.installation.engine);
     const { systemPrompt, machineCredentials, ...profileInput } = input;
     if (systemPrompt !== undefined)
@@ -1170,7 +1732,7 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
     checkedRun(run, helper, ["doctor-profile", "--profile", profileDir, "--runtime", runtime], { stdio: "ignore" }, "profile validation");
     const start = deps.start !== false;
     if (start) {
-        checkedRun(run, helper, ["service", "install", "--profile", profileDir, "--runtime", runtime], { stdio: ["ignore", 2, 2] }, "service installation");
+        checkedRun(run, helper, ["service", "install", "--profile", profileDir, "--runtime", runtime], { stdio: ["ignore", 2, 2] }, "service installation", spawn);
         removeEmbeddedRuntime(profileDir, platform);
     }
     return { profile, runtime, helper, running: start };