@indigoai-us/hq-cli 5.345.198 → 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,15 +80,15 @@ export function sharedRuntimeLayout(root, id, platform) {
 }
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.22",
-    version: "0.4.22",
-    artifact: "hq-fleet-local-0.4.22.zip",
-    artifactSha256: "b12c01d48c8add7609de557f02987eaa7570223751446915835f52dc9b69d1db",
-    runtimeArtifact: "hq-fleet-runtime-f17ab10aa598.tar",
-    runtimeArtifactSha256: "a2296305a82af7f834804f4240705d791f0c08fa52257955dae3dce091d39ee8",
-    manifestSha256: "f3c62e4e64f91e0aeab32d0999a106c89122144c83757874c81781fb417c0392",
-    signatureSha256: "f07502b61b35431292c9d656f9e602f5230f8fb8ca093993ec92d4353077b4ba",
-    runtimeCommit: "f17ab10aa598d5915f47bf0b83d332a5cc243f98",
+    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). */
 export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
@@ -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,13 +1777,14 @@ 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 });
 }
 function writeNativeProfileMarker(profileDir, shared, engine) {
     const marker = path.join(profileDir, "bootstrap.json");
     const temporary = `${marker}.${process.pid}.${crypto.randomUUID()}`;
-    fs.writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 2, runtimeId: shared.id, engine }, null, 2)}\n`, { mode: 0o600 });
+    fs.writeFileSync(temporary, `${JSON.stringify({ schemaVersion: 2, runtimeId: shared.id, engine, cliVersion: CLI_VERSION }, null, 2)}\n`, { mode: 0o600 });
     fs.renameSync(temporary, marker);
 }
 function removeEmbeddedRuntime(profileDir, platform = process.platform) {
@@ -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/bot/job-run.js

@@ -215,7 +215,7 @@ export function planJobRuns(items, handled) {
     const byJob = new Map();
     for (const item of items) {
         const job = readJobRun(item);
-        if (!job)
+        if (!job || item.messageId.startsWith("localjob-event-"))
             continue;
         const list = byJob.get(job.jobId);
         if (list)

package/dist/lib/bot/jobs/hot-signal-sync.d.ts

@@ -48,6 +48,12 @@ export declare const HOT_SIGNAL_SYNC_JOB_KIND = "hot-signal-sync";
  * own schedule in `jobs.json` is the one that runs.
  */
 export declare const HOT_SIGNAL_SYNC_DEFAULT_CRON = "cron(30 6 * * ? *)";
+interface BuiltinJobsMarker {
+    v: 1;
+    registered: Record<string, string>;
+}
+declare function readMarker(dir: string): BuiltinJobsMarker;
+declare function writeMarker(dir: string, marker: BuiltinJobsMarker): void;
 export declare function hotSignalSyncRegistered(dir: string, company: string): boolean;
 export declare function fleetHotSignalSyncRegistered(dir: string, company: string): boolean;
 export declare function markFleetHotSignalSyncRegistered(dir: string, company: string, now?: Date): void;
@@ -210,4 +216,6 @@ export interface HotSignalSyncRunOutcome {
 /** Run the scheduled sync once and describe it in plain words. Never throws. */
 export declare function runHotSignalSyncJob(input: HotSignalSyncRunInput): Promise<HotSignalSyncRunOutcome>;
 export declare function describeSyncReport(company: string, report: OnDemandSyncReport): string;
+/** Shared registration marker for additive built-in event jobs. */
+export { readMarker as readBuiltinJobsMarker, writeMarker as writeBuiltinJobsMarker };
 //# sourceMappingURL=hot-signal-sync.d.ts.map

package/dist/lib/bot/jobs/hot-signal-sync.js

@@ -430,4 +430,6 @@ export function describeSyncReport(company, report) {
         lines.push(notice);
     return lines.join("\n");
 }
+/** Shared registration marker for additive built-in event jobs. */
+export { readMarker as readBuiltinJobsMarker, writeMarker as writeBuiltinJobsMarker };
 //# sourceMappingURL=hot-signal-sync.js.map

package/dist/lib/bot/jobs/meeting-detect.d.ts

@@ -0,0 +1,28 @@
+import { type LiveMeetingBot } from "../../live-meetings.js";
+import type { BotConfig } from "../config.js";
+export declare function detectIntervalSeconds(hqRoot: string): number;
+/** Desktop events carry company UIDs; local rider files use manifest slugs. */
+export declare function normalizeDetectedCompany(hqRoot: string, payload: unknown): unknown;
+export interface MeetingDetectDeps {
+    hqRoot: string;
+    dir: string;
+    enabled: () => boolean;
+    companies: () => string[];
+    list: (company: string, signal: AbortSignal) => Promise<{
+        companyId: string;
+        bots: LiveMeetingBot[];
+    }>;
+    intervalSeconds?: () => number;
+    now?: () => Date;
+    log: (message: string) => void;
+}
+/** Live reads are keyed by Recall ID; the desktop may emit a saved meeting ID or SDK window ID. */
+export declare function resolveDetectedMeeting(hqRoot: string, payload: unknown, list: MeetingDetectDeps["list"]): Promise<unknown>;
+export declare function createMeetingDetect(deps: MeetingDetectDeps): {
+    /** Called by the inbox loop; network work never holds up inbox delivery. */
+    tick(): void;
+    settled(): Promise<void>;
+    stop(): Promise<void>;
+};
+export declare function defaultMeetingDetectDeps(config: BotConfig, dir: string, log: (message: string) => void): MeetingDetectDeps;
+//# sourceMappingURL=meeting-detect.d.ts.map