@indigoai-us/hq-cli 5.345.199 → 5.345.200

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

@@ -6,6 +6,7 @@ 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 { downloadFleetFile, fileSha256 } from "./fleet-download.js";
 import { ensureFleetPython, fleetUvEnv } from "./fleet-python.js";
 import semver from "semver";
 import { CLI_VERSION } from "../../cli-version.js";
@@ -79,14 +80,14 @@ export function sharedRuntimeLayout(root, id, platform) {
 }
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.24",
-    version: "0.4.24",
-    artifact: "hq-fleet-local-0.4.24.zip",
-    artifactSha256: "daa74b7aaf7f26d8c069f33aa94a453369fb2d7ae8c122e7fbe48a5b38e73f31",
-    runtimeArtifact: "hq-fleet-runtime-d257fdd1171f.tar",
-    runtimeArtifactSha256: "8262c5f28773d35c04f7f9ce6f61ed19a88e601847f9d12d5ab11fb5d8e87fb0",
-    manifestSha256: "302d2206957b815a846db583a49e7862948fd8a8a36aaff8e0e8a6e0aa7a1b9c",
-    signatureSha256: "efee90b00c6eb1d0f53a76e93a756435975c9da6c70c9c0b505aafcce79a586a",
+    tag: "v0.4.25",
+    version: "0.4.25",
+    artifact: "hq-fleet-local-0.4.25.zip",
+    artifactSha256: "4d32e04f992600ab0f1656de3536358dfdba77bfccdc23e1b01ba7a0de4ea38d",
+    runtimeArtifact: "hq-fleet-runtime-d257fdd1171f.tar.gz",
+    runtimeArtifactSha256: "4d26d250eb100efff280bcd254e06e3a2993875c1fff4eec1733eaf99e52cd70",
+    manifestSha256: "d7e3a3309bf60e6366b192c9131d44166edf63cb5a60ca7923fe30145fc890f0",
+    signatureSha256: "1b018c39e69aefa26a0b1f95ed5d97388fd4747851643c8a53cae3069c670c0a",
     runtimeCommit: "d257fdd1171f1edd5e381b3bad7baacab0cb00d3",
 };
 /** hq-fleet-local trust/release-public.pem (rotated 2026-10-30; signed v0.4.17). */
@@ -470,7 +471,8 @@ export function parseFleetLocalReleasePin(value) {
         return null;
     if (!COMMIT_RE.test(pin.runtimeCommit))
         return null;
-    if (pin.runtimeArtifact !== `hq-fleet-runtime-${pin.runtimeCommit.slice(0, 12)}.tar`)
+    const runtimeStem = `hq-fleet-runtime-${pin.runtimeCommit.slice(0, 12)}`;
+    if (pin.runtimeArtifact !== `${runtimeStem}.tar` && pin.runtimeArtifact !== `${runtimeStem}.tar.gz`)
         return null;
     if (![pin.artifactSha256, pin.runtimeArtifactSha256, pin.manifestSha256, pin.signatureSha256].every((hash) => SHA256_RE.test(hash))) {
         return null;
@@ -637,38 +639,67 @@ function trustedReleaseLink(url) {
         return false;
     }
 }
-async function downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime) {
-    const get = async (name, timeoutMs) => {
+export const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30_000;
+/** One machine-wide lock: concurrent creates and adopts share one download instead of repeating it. */
+export const FLEET_LOCAL_DISTRIBUTION_LOCK_NAME = "hq-fleet-local-distribution";
+export const FLEET_LOCAL_DISTRIBUTION_LOCK_WAIT_MS = 30 * 60_000;
+export const FLEET_LOCAL_DISTRIBUTION_LOCK_STALE_MS = 60 * 60_000;
+const RELEASE_FILE_NAMES = (release) => [
+    release.artifact,
+    release.runtimeArtifact,
+    "release-manifest.json",
+    "release-manifest.sig",
+];
+function downloadsDir(root, release) {
+    return path.join(root, "distributions", "hq-fleet-local", ".downloads", release.version);
+}
+function discardDownloads(target) {
+    fs.rmSync(target, { recursive: true, force: true });
+    try {
+        fs.rmdirSync(path.dirname(target));
+    }
+    catch {
+        return;
+    }
+}
+async function downloadReleaseFiles(release, fetcher, resolve, cachedRuntime, target, onProgress, stallMs) {
+    fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+    const downloaded = new Map();
+    for (const name of RELEASE_FILE_NAMES(release)) {
+        if (name === release.runtimeArtifact && cachedRuntime) {
+            downloaded.set(name, cachedRuntime);
+            continue;
+        }
+        const { url, headers } = resolve(name);
+        const file = await downloadFleetFile(url, path.join(target, name), {
+            fetch: fetcher,
+            ...(headers ? { headers } : {}),
+            ...(stallMs !== undefined ? { stallMs } : {}),
+            onProgress: (progress) => onProgress?.({ phase: "download", file: name, received: progress.received, total: progress.total }),
+        });
+        downloaded.set(name, file);
+    }
+    return {
+        archive: fs.readFileSync(downloaded.get(release.artifact)),
+        runtimeArchive: fs.readFileSync(downloaded.get(release.runtimeArtifact)),
+        manifest: fs.readFileSync(downloaded.get("release-manifest.json")),
+        signature: fs.readFileSync(downloaded.get("release-manifest.sig")),
+    };
+}
+async function downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime, target, onProgress, stallMs) {
+    for (const name of RELEASE_FILE_NAMES(release)) {
+        if (name === release.runtimeArtifact && cachedRuntime)
+            continue;
         const url = links.get(name);
         if (!url)
             throw expectedError(`HQ Fleet Local ${release.tag} is missing release asset ${name}.`);
         if (!trustedReleaseLink(url)) {
             throw expectedError(`HQ Fleet Local ${release.tag} returned an untrusted download link for ${name}.`);
         }
-        const response = await fetcher(url, { signal: AbortSignal.timeout(timeoutMs) });
-        if (!response.ok) {
-            throw expectedError(`Could not download ${name}: HQ storage returned HTTP ${response.status}.`);
-        }
-        return Buffer.from(await response.arrayBuffer());
-    };
-    const [archive, runtimeArchive, manifest, signature] = await Promise.all([
-        get(release.artifact, FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS),
-        cachedRuntime ?? get(release.runtimeArtifact, FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS),
-        get("release-manifest.json", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
-        get("release-manifest.sig", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
-    ]);
-    return { archive, runtimeArchive, manifest, signature };
-}
-async function responseBytes(response, label) {
-    if (!response.ok) {
-        throw expectedError(`Could not download ${label}: GitHub returned HTTP ${response.status}.`);
     }
-    return Buffer.from(await response.arrayBuffer());
+    return downloadReleaseFiles(release, fetcher, (name) => ({ url: links.get(name) }), cachedRuntime, target, onProgress, stallMs);
 }
-export const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30_000;
-export const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
-export const FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS = 20 * 60_000;
-async function downloadFleetLocalRelease(release, fetcher, token, cachedRuntime) {
+async function downloadFleetLocalRelease(release, fetcher, token, cachedRuntime, target, onProgress, stallMs) {
     const headers = {
         Accept: "application/vnd.github+json",
         Authorization: `Bearer ${token}`,
@@ -676,7 +707,7 @@ async function downloadFleetLocalRelease(release, fetcher, token, cachedRuntime)
         "X-GitHub-Api-Version": "2022-11-28",
     };
     const releaseUrl = `https://api.github.com/repos/${release.repository}/releases/tags/${release.tag}`;
-    const response = await fetcher(releaseUrl, { headers, signal: AbortSignal.timeout(30_000) });
+    const response = await fetcher(releaseUrl, { headers, signal: AbortSignal.timeout(FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS) });
     if (!response.ok) {
         throw expectedError(`Could not read HQ Fleet Local ${release.tag}: GitHub returned HTTP ${response.status}.`);
     }
@@ -684,25 +715,17 @@ async function downloadFleetLocalRelease(release, fetcher, token, cachedRuntime)
     const assets = new Map((body.assets ?? [])
         .filter((asset) => !!asset.name && !!asset.url)
         .map((asset) => [asset.name, asset.url]));
-    const get = async (name, timeoutMs) => {
+    for (const name of RELEASE_FILE_NAMES(release)) {
+        if (name === release.runtimeArtifact && cachedRuntime)
+            continue;
         const url = assets.get(name);
         if (!url)
             throw expectedError(`HQ Fleet Local ${release.tag} is missing release asset ${name}.`);
         if (new URL(url).origin !== "https://api.github.com") {
             throw expectedError(`HQ Fleet Local ${release.tag} returned an untrusted asset URL for ${name}.`);
         }
-        return responseBytes(await fetcher(url, {
-            headers: { ...headers, Accept: "application/octet-stream" },
-            signal: AbortSignal.timeout(timeoutMs),
-        }), name);
-    };
-    const [archive, runtimeArchive, manifest, signature] = await Promise.all([
-        get(release.artifact, FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS),
-        cachedRuntime ?? get(release.runtimeArtifact, FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS),
-        get("release-manifest.json", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
-        get("release-manifest.sig", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
-    ]);
-    return { archive, runtimeArchive, manifest, signature };
+    }
+    return downloadReleaseFiles(release, fetcher, (name) => ({ url: assets.get(name), headers: { ...headers, Accept: "application/octet-stream" } }), cachedRuntime, target, onProgress, stallMs);
 }
 function installedFiles(dir, release) {
     const archive = path.join(dir, release.artifact);
@@ -749,49 +772,83 @@ function installFiles(target, files, release, publicKey) {
             fs.rmSync(staging, { recursive: true, force: true });
     }
 }
+/** A runtime archive already on this machine whose bytes match the pin: any installed release, or a finished download. */
 function cachedRuntimeArchive(root, release) {
     const distributions = path.join(root, "distributions", "hq-fleet-local");
     if (!fs.existsSync(distributions))
         return null;
-    for (const entry of fs.readdirSync(distributions, { withFileTypes: true })) {
-        if (!entry.isDirectory() || entry.name.startsWith("."))
-            continue;
-        const directory = path.join(distributions, entry.name);
+    const candidates = [];
+    const visit = (directory) => {
         for (const file of fs.readdirSync(directory, { withFileTypes: true })) {
-            if (!file.isFile() || !file.name.startsWith("hq-fleet-runtime-") || !file.name.endsWith(".tar"))
+            const full = path.join(directory, file.name);
+            if (file.isDirectory()) {
+                if (file.name === ".downloads" || !file.name.startsWith("."))
+                    visit(full);
+                continue;
+            }
+            if (!file.isFile() || !file.name.startsWith("hq-fleet-runtime-"))
                 continue;
-            const bytes = fs.readFileSync(path.join(directory, file.name));
-            if (digest(bytes) === release.runtimeArtifactSha256)
-                return bytes;
+            if (!file.name.endsWith(".tar") && !file.name.endsWith(".tar.gz"))
+                continue;
+            candidates.push(full);
         }
+    };
+    visit(distributions);
+    for (const candidate of candidates) {
+        if (fileSha256(candidate) === release.runtimeArtifactSha256)
+            return candidate;
     }
     return null;
 }
+/** Whether the pinned release is installed on this machine (no download needed). */
+export function fleetLocalDistributionInstalled(release = HQ_FLEET_LOCAL_RELEASE, root = fleetHome()) {
+    return installedFiles(path.join(root, "distributions", "hq-fleet-local", release.version), release) !== null;
+}
 export async function installPinnedFleetLocalDistribution(deps = {}) {
     const release = deps.release ?? HQ_FLEET_LOCAL_RELEASE;
     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);
+    const onProgress = deps.onProgress;
     const warnCompatibility = (manifest) => {
         const warning = fleetLocalCliCompatibilityWarning(manifest, release);
         if (warning)
             process.stderr.write(`Warning: ${warning}\n`);
     };
+    const installation = () => ({
+        release,
+        dir,
+        archive: path.join(dir, release.artifact),
+        runtimeArchive: path.join(dir, release.runtimeArtifact),
+        manifest: path.join(dir, "release-manifest.json"),
+        signature: path.join(dir, "release-manifest.sig"),
+        engine: engineMetadata(release),
+    });
+    const current = installedFiles(dir, release);
     if (current) {
         verifyFleetLocalRelease(current, release, publicKey);
         warnCompatibility(current.manifest);
-    }
-    else {
+        onProgress?.({ phase: "ready", step: "download", cached: true });
+        return installation();
+    }
+    return withBotLock(FLEET_LOCAL_DISTRIBUTION_LOCK_NAME, async () => {
+        const again = installedFiles(dir, release);
+        if (again) {
+            verifyFleetLocalRelease(again, release, publicKey);
+            warnCompatibility(again.manifest);
+            onProgress?.({ phase: "ready", step: "download", cached: true });
+            return installation();
+        }
         const fetcher = deps.fetch ?? fetch;
         const lookup = deps.hqReleaseLinks
             ? { links: await deps.hqReleaseLinks(release), reason: null }
             : await (deps.hqReleaseLookup ?? lookupHqFleetReleaseLinks)(release);
         const links = lookup.links;
         const cachedRuntime = cachedRuntimeArchive(root, release);
+        const target = downloadsDir(root, release);
         let files;
         if (links) {
-            files = await downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime);
+            files = await downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime, target, onProgress, deps.downloadStallMs);
         }
         else {
             let githubToken;
@@ -799,24 +856,29 @@ export async function installPinnedFleetLocalDistribution(deps = {}) {
                 githubToken = (deps.token ?? resolveFleetReleaseToken)();
             }
             catch (error) {
-                // A customer has no GitHub token; say why HQ had no download instead of asking them to sign in again.
                 throw noReleaseSourceError(release, lookup.reason) ?? error;
             }
-            files = await downloadFleetLocalRelease(release, fetcher, githubToken, cachedRuntime);
+            files = await downloadFleetLocalRelease(release, fetcher, githubToken, cachedRuntime, target, onProgress, deps.downloadStallMs);
+        }
+        onProgress?.({ phase: "verify" });
+        try {
+            verifyFleetLocalRelease(files, release, publicKey);
+        }
+        catch (error) {
+            discardDownloads(target);
+            throw error;
         }
-        verifyFleetLocalRelease(files, release, publicKey);
         warnCompatibility(files.manifest);
         installFiles(dir, files, release, publicKey);
-    }
-    return {
-        release,
-        dir,
-        archive: path.join(dir, release.artifact),
-        runtimeArchive: path.join(dir, release.runtimeArtifact),
-        manifest: path.join(dir, "release-manifest.json"),
-        signature: path.join(dir, "release-manifest.sig"),
-        engine: engineMetadata(release),
-    };
+        discardDownloads(target);
+        onProgress?.({ phase: "ready", step: "download", cached: false });
+        return installation();
+    }, {
+        root: path.join(root, "distributions"),
+        command: "HQ Fleet Runtime download",
+        waitMs: FLEET_LOCAL_DISTRIBUTION_LOCK_WAIT_MS,
+        staleMs: FLEET_LOCAL_DISTRIBUTION_LOCK_STALE_MS,
+    });
 }
 function profileName(agentUid) {
     return agentUid.toLowerCase();
@@ -1633,7 +1695,7 @@ export function importFleetLocalMachineCredential(agentUid, machineCredentials,
     if (!opts.keepSource)
         fs.rmSync(machineCredentials, { force: true });
 }
-async function installSharedFleetRuntime(installation, root, python, platform, run, spawn) {
+async function installSharedFleetRuntime(installation, root, python, platform, run, spawn, onProgress) {
     const identity = digest(Buffer.from(JSON.stringify({
         version: installation.release.version,
         distribution: installation.release.artifactSha256,
@@ -1672,9 +1734,11 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             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.");
             }
+            onProgress?.({ phase: "ready", step: "runtime", cached: true });
             return layout;
         }
         fs.rmSync(shared, { recursive: true, force: true });
+        onProgress?.({ phase: "extract" });
         fs.mkdirSync(distributionSource, { recursive: true, mode: 0o700 });
         fs.mkdirSync(runtimeSource, { recursive: true, mode: 0o700 });
         const uvEnv = fleetUvEnv(python.pythonDir);
@@ -1689,6 +1753,7 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             installation.runtimeArchive,
             runtimeSource,
         ], { stdio: "ignore" }, "runtime extraction");
+        onProgress?.({ phase: "environment" });
         checkedRun(run, python.uv, [
             "venv",
             "--no-config",
@@ -1697,6 +1762,7 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             runtimeDir,
         ], { stdio: "ignore", env: uvEnv }, "environment creation");
         const runtimePython = venvExecutable(runtimeDir, "python", platform);
+        onProgress?.({ phase: "packages" });
         checkedRun(run, python.uv, [
             "pip",
             "install",
@@ -1711,6 +1777,7 @@ async function installSharedFleetRuntime(installation, root, python, platform, r
             throw expectedError("HQ Fleet Local installed without its runtime executables.");
         }
         fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, runtimeId: identity, engine: installation.engine })}\n`, { mode: 0o600 });
+        onProgress?.({ phase: "ready", step: "runtime", cached: false });
         return layout;
     }, { root: path.join(root, "runtimes"), command: "HQ Fleet Runtime installation", waitMs: 20 * 60_000, staleMs: 2 * 60 * 60_000 });
 }
@@ -1725,6 +1792,42 @@ function removeEmbeddedRuntime(profileDir, platform = process.platform) {
     if (hasEmbeddedRuntime(profileDir, platform))
         fs.rmSync(path.join(profileDir, "runtime"), { recursive: true, force: true });
 }
+/**
+ * Everything a bot needs that is shared by every bot on this machine: the
+ * pinned distribution and runtime archive, the private Python, and the built
+ * runtime environment. Safe to run any number of times; a complete install
+ * returns at once.
+ */
+export async function ensureFleetRuntimeInstalled(installation, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const platform = deps.platform ?? process.platform;
+    const root = deps.fleetHome ?? fleetHome();
+    deps.onProgress?.({ phase: "python" });
+    const python = deps.python ?? await ensureFleetPython({ fleetHome: root, platform, run });
+    const spawn = deps.spawn ?? (deps.run ? spawnFromRun(deps.run) : spawnSync);
+    const shared = await installSharedFleetRuntime(installation, root, python, platform, run, spawn, deps.onProgress);
+    return { release: installation.release, distributionDir: installation.dir, runtimeDir: shared.runtimeDir, runtimeId: shared.id };
+}
+/** Whether the shared runtime for this release is already built on this machine. */
+export function fleetRuntimeReady(installation, deps = {}) {
+    const root = deps.fleetHome ?? fleetHome();
+    const platform = deps.platform ?? process.platform;
+    const python = deps.python;
+    if (!python)
+        return false;
+    const identity = digest(Buffer.from(JSON.stringify({
+        version: installation.release.version,
+        distribution: installation.release.artifactSha256,
+        runtime: installation.release.runtimeArtifactSha256,
+        python: python.python,
+        platform,
+        extras: ["mcp", "anthropic"],
+    })));
+    const layout = sharedRuntimeLayout(root, identity, platform);
+    if (!fs.existsSync(path.join(layout.root, "ready.json")))
+        return false;
+    return ["python", "hq-fleet", "hq-fleet-local"].every((name) => fs.existsSync(venvExecutable(layout.runtimeDir, name, platform)));
+}
 export async function bootstrapFleetLocalBot(input, deps = {}) {
     const run = deps.run ?? execFileSync;
     const platform = deps.platform ?? process.platform;
@@ -1733,7 +1836,7 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
     const profileDir = adoptLegacyProfileDirectory(input.agentUid, root);
     fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
     const spawn = deps.spawn ?? (deps.run ? spawnFromRun(deps.run) : spawnSync);
-    const shared = await installSharedFleetRuntime(input.installation, root, python, platform, run, spawn);
+    const shared = await installSharedFleetRuntime(input.installation, root, python, platform, run, spawn, deps.onProgress);
     writeNativeProfileMarker(profileDir, shared, input.installation.engine);
     const { systemPrompt, machineCredentials, ...profileInput } = input;
     if (systemPrompt !== undefined)

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

@@ -43,6 +43,8 @@ export declare function fleetUvEnv(pythonDir: string, base?: NodeJS.ProcessEnv):
 /** The operating system's own tar when it is where it always is, so a `tar` on PATH or in the current folder is never run. */
 export declare function tarExecutable(platform: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;
 export declare function fleetPythonToolPath(deps?: FleetPythonDeps): string;
+/** The installer and private Python already on this machine, or null; never downloads anything. */
+export declare function installedFleetPython(deps?: FleetPythonDeps): FleetPython | null;
 /**
  * The pinned installer and private Python, installed once per machine under
  * the fleet folder and reused by every bot. Concurrent creates wait for each

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

@@ -222,6 +222,35 @@ async function ensureFleetPythonLocked(root, deps) {
     }
     return { uv, python, pythonDir };
 }
+/** The installer and private Python already on this machine, or null; never downloads anything. */
+export function installedFleetPython(deps = {}) {
+    const root = deps.fleetHome ?? fleetHome();
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? execFileSync;
+    const version = deps.pythonVersion ?? HQ_FLEET_PYTHON_VERSION;
+    const uv = fleetPythonToolPath(deps);
+    const pythonDir = path.join(root, "python");
+    if (!installedTool(uv) || !fs.existsSync(pythonDir))
+        return null;
+    try {
+        const output = run(uv, ["python", "find", version, "--managed-python", "--no-config"], {
+            stdio: ["ignore", "pipe", "ignore"],
+            env: fleetUvEnv(pythonDir, deps.env ?? process.env),
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: FLEET_PYTHON_FIND_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
+        const found = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
+        const python = path.resolve(found);
+        if (!found || !fs.existsSync(python) || !isInside(pythonDir, python, platform))
+            return null;
+        return { uv, python, pythonDir };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The pinned installer and private Python, installed once per machine under
  * the fleet folder and reused by every bot. Concurrent creates wait for each

package/dist/lib/lanes/mesh-events.js

@@ -45,6 +45,7 @@
 import { appendThreadEvent, clamp, ensureLaneMeshThread, ensureProjectThread, getProjectView, patchStoryStatus, putProjectView, requireToken, registerMeshProject, resolveMeshCompany, } from "../mesh/api.js";
 import { LanesError } from "./errors.js";
 import { terminalEnvelopeStoryStatus } from "./stories.js";
+import { gatedInteractiveLogin } from "../../utils/interactive-caller.js";
 export const LANE_MESH_EVENTS = [
     "lane_started",
     "lane_progress",
@@ -309,7 +310,8 @@ async function repairProjectView(input) {
 }
 export function createLaneMesh(opts = {}) {
     const interactive = opts.interactive ?? true;
-    const token = opts.token ?? (() => requireToken({ interactive }));
+    // Gated per call: the same mesh can serve a terminal and a detached watcher.
+    const token = opts.token ?? (() => requireToken({ interactive: gatedInteractiveLogin(interactive) }));
     const repair = opts.repairProjectView ?? repairProjectView;
     return {
         async ensureProjectThread(company, projectId) {

package/dist/lib/mesh/api.js

@@ -9,6 +9,7 @@ import { ensureCognitoToken, isMachineIdentity } from "../../utils/cognito-sessi
 import { peekIdToken } from "../../utils/id-token.js";
 import { getCompanyUid, vaultApiFetch } from "../../utils/vault-api.js";
 import { meshCacheRoot, removeSessionFallbackFiles, writeMeshCacheFile, } from "./cache.js";
+import { gatedInteractiveLogin } from "../../utils/interactive-caller.js";
 const PRINCIPAL_UID = /^(prs|agt)_/;
 export const STORY_STATUSES = new Set([
     "queued",
@@ -183,7 +184,7 @@ export async function requireToken(opts = {}) {
     // hard policy indigo-agent-caller-resolution-id-token, agent claims ride
     // the ID token only; the server is correct to require it. Humans keep the
     // person access token (unchanged).
-    const interactive = opts.interactive ?? true;
+    const interactive = gatedInteractiveLogin(opts.interactive ?? true);
     if (isMachineIdentity()) {
         return ensureCognitoToken({ tokenSource: "machine", interactive });
     }

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -1,13 +1,3 @@
-/**
- * hq mesh daemon run — single-instance resident process.
- *
- * - pid lock at ~/.hq/work-mesh/daemon/pid
- * - fs.watch spool + 2s debounce; flush at least every 10s (US-008 path)
- * - replay context outbox
- * - board.md refresh for bound sessions ≤ every 60s
- * - MQTT presence (contract-3)
- * - SIGTERM/SIGINT: flush once more, MQTT DISCONNECT (server derives offline), exit
- */
 import { type DeliverFn } from "../../../work-context/outbox.js";
 import { type SessionEventsPoster } from "../session-events-client.js";
 import { type FlushSummary } from "../flush.js";

package/dist/lib/mesh/live/daemon/run.js

@@ -1,3 +1,4 @@
+import { reportingRuntimeAllowed } from "../reporting-privacy.js";
 /**
  * hq mesh daemon run — single-instance resident process.
  *
@@ -380,6 +381,8 @@ export async function runMeshDaemon(deps = {}) {
                 baseUrl: resolveVaultApiBase(env),
             });
             return flushSessionEvents({
+                env,
+                reportingAllowed: () => reportingRuntimeAllowed(machineIdentity, env),
                 workMeshRoot: meshRoot,
                 workContextRoot: ctxRoot,
                 poster,

package/dist/lib/mesh/live/emit.d.ts

@@ -1,14 +1,3 @@
-/**
- * Direct-emit orchestration (owner decision 2026-09-08). One invocation:
- *   1. drains the local retry file (prior failures),
- *   2. appends the new event(s),
- *   3. POSTs /v1/mesh/events in batches with a short bounded retry,
- *   4. keeps only network/5xx/429-failed or unaccounted events for next time,
- *   5. records lastPostAt + per-event status counts for `hq mesh doctor`.
- *
- * accepted / unassigned / rejected are all terminal (rejected is dropped with a
- * count — never re-posted). No long-lived process, spool, or held queue.
- */
 import { type EmitPoster, type EmitEventStatus } from "./emit-client.js";
 import { type RandomFn, type SleepFn } from "./backoff.js";
 export interface EmitStateFile {
@@ -23,6 +12,8 @@ export interface EmitStateFile {
 export declare function emitStatePath(workMeshRoot: string): string;
 export declare function readEmitState(workMeshRoot: string): EmitStateFile | null;
 export interface EmitEventsDeps {
+    env?: NodeJS.ProcessEnv;
+    reportingAllowed?: () => Promise<boolean>;
     workMeshRoot: string;
     poster: EmitPoster;
     /** New events to emit this invocation (may be empty — just drain retry). */

package/dist/lib/mesh/live/emit.js

@@ -1,3 +1,4 @@
+import { reportingLocallyDisabled, mayEmitConversation } from "./reporting-privacy.js";
 /**
  * Direct-emit orchestration (owner decision 2026-09-08). One invocation:
  *   1. drains the local retry file (prior failures),
@@ -90,10 +91,27 @@ export async function emitEvents(deps) {
         statuses: { accepted: 0, unassigned: 0, rejected: 0 },
         rejections: [],
     };
+    const env = deps.env ?? process.env;
+    if (reportingLocallyDisabled(env) || (deps.reportingAllowed && !(await deps.reportingAllowed()))) {
+        const written = writeEmitRetry(deps.workMeshRoot, combined, retryMax);
+        return { ...summary, attempted: 0, retained: written.written,
+            retryDepth: written.written, droppedOverflow: written.dropped };
+    }
+    const allowed = combined.filter(event => {
+        if (mayEmitConversation(event, env))
+            return true;
+        summary.rejected += 1;
+        summary.statuses.rejected += 1;
+        const eventId = eventIdOf(event);
+        if (eventId)
+            summary.rejections.push({ eventId, code: "PERSONAL_OR_UNATTRIBUTED" });
+        return false;
+    });
+    summary.attempted = allowed.length;
     const keep = [];
     let anyPosted = false;
-    for (let i = 0; i < combined.length; i += MESH_EVENTS_BATCH_MAX) {
-        const chunk = combined.slice(i, i + MESH_EVENTS_BATCH_MAX);
+    for (let i = 0; i < allowed.length; i += MESH_EVENTS_BATCH_MAX) {
+        const chunk = allowed.slice(i, i + MESH_EVENTS_BATCH_MAX);
         summary.batches += 1;
         let result = await deps.poster(chunk);
         for (let attempt = 1; attempt < maxAttempts && !result.ok && result.retryable; attempt += 1) {

package/dist/lib/mesh/live/flush.d.ts

@@ -24,6 +24,8 @@ export declare const HELD_MAX_LINES = 20000;
 export declare const PROJECT_REBIND_INTERVAL_MS = 60000;
 export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "NEEDS_PROJECT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
 export interface FlushDeps {
+    /** Production callers re-read the shared person preference before each flush. */
+    reportingAllowed?: () => Promise<boolean>;
     workMeshRoot: string;
     workContextRoot: string;
     poster: SessionEventsPoster;