@indigoai-us/hq-cli 5.345.191 → 5.345.194

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

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

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

@@ -39,8 +39,9 @@ export interface InboxItem {
     memberCount?: number;
     senderTrust?: "member";
     /**
-     * Scheduled-job run items only (channel === "job"). The cloud fires the job
-     * on its own schedule and writes this durable item; the run carries its own
+     * Scheduled-job run items only (channel === "job"). A local bot's own loop
+     * builds them from its jobs.json (lib/bot/local-jobs.ts); for a hosted agent
+     * the cloud fires the job and writes this durable item. The run carries its own
      * prompt instead of `text` (server: hq-pro-agents jobs/run-record.ts
      * `JobRunInboxItem`).
      */

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

@@ -93,6 +93,8 @@ export interface BotConfig {
     engine?: BotEngineMetadata;
     fleetAuthPending?: boolean;
     fleetServiceInstallPending?: boolean;
+    /** A newer HQ Fleet Local release is installed for this bot; the gateway restarts once the bot is idle. */
+    fleetRestartPending?: boolean;
     /**
      * "personal" (acts as its owner everywhere) or "company" (acts as itself,
      * member of `companies`). Missing on bots created before kinds existed:

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

@@ -0,0 +1,121 @@
+import { type BotConfig } from "./config.js";
+import { type FleetLocalControlDeps } from "./fleet-local.js";
+export interface FleetCronSchedule {
+    kind?: string;
+    expr?: string;
+    minutes?: number;
+    run_at?: string;
+    display?: string;
+}
+export interface FleetCronJob {
+    id: string;
+    name?: string;
+    prompt?: string;
+    script?: string | null;
+    no_agent?: boolean;
+    schedule?: FleetCronSchedule;
+    schedule_display?: string;
+    enabled?: boolean;
+    state?: string;
+    created_at?: string;
+    next_run_at?: string | null;
+    last_run_at?: string | null;
+    last_status?: string | null;
+    repeat?: {
+        times?: number | null;
+        completed?: number;
+    };
+    deliver?: string;
+    origin?: Record<string, unknown> | null;
+    workdir?: string | null;
+    fire_claim?: unknown;
+}
+export interface FleetCronOrigin {
+    platform: "hqdm";
+    chat_id: string;
+    user_id: string;
+    chat_name?: string;
+}
+export interface FleetCronCreateInput {
+    prompt: string;
+    schedule: string;
+    origin: FleetCronOrigin;
+    name?: string;
+    script?: string;
+    noAgent?: boolean;
+    workdir?: string;
+}
+export interface FleetCronOps {
+    list(): FleetCronJob[];
+    create(input: FleetCronCreateInput): FleetCronJob;
+    remove(id: string): boolean;
+    reschedule(id: string, schedule: string): FleetCronJob | null;
+}
+export type FleetCronRunner = (executable: string, args: string[], options: Record<string, unknown>) => Buffer | string;
+export interface FleetCronDeps extends Pick<FleetLocalControlDeps, "fleetHome" | "platform"> {
+    run?: FleetCronRunner;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const FLEET_CRON_BRIDGE: string;
+export declare function runFleetCronRequest(agentUid: string, request: Record<string, unknown>, deps?: FleetCronDeps): unknown;
+export declare function fleetCronOps(agentUid: string, deps?: FleetCronDeps): FleetCronOps;
+export declare function fleetOwnerOrigin(ownerUid: string, jobs?: readonly FleetCronJob[]): FleetCronOrigin;
+export declare function fleetScheduleFromLegacy(expr: string): string;
+export interface FleetJobsMigrationResult {
+    imported: number;
+    alreadyPresent: number;
+    skipped: string[];
+    /** Where the old list went. Null when some jobs could not move: jobs.json then stays. */
+    renamedTo: string | null;
+}
+export declare function migrateLegacyJobsToFleet(dir: string, config: Pick<BotConfig, "ownerUid" | "hqRoot">, ops: FleetCronOps, now?: Date): FleetJobsMigrationResult | null;
+export declare const FLEET_HOT_SIGNAL_SYNC_NAME = "hot-signal-sync";
+export declare const FLEET_HOT_SIGNAL_SYNC_SCHEDULE = "30 6 * * *";
+export declare function fleetHotSignalSyncScript(company: string): string;
+export declare function companyOfHotSignalSyncJob(job: FleetCronJob): string | null;
+export declare function renderFleetHotSignalSyncScript(input: {
+    nodeBinary: string;
+    hqBinary: string;
+    company: string;
+    hqRoot: string;
+    logFile: string;
+    /**
+     * cli.bot-signals-engine-job. On (the default here): the script runs the
+     * signals engine. Off: it runs the plain hot-channel sync (`hq sources sync`),
+     * the job these bots ran before the engine.
+     */
+    signalsEngine?: boolean;
+}): string;
+export interface EnsureFleetHotSignalSyncInput {
+    dir: string;
+    config: Pick<BotConfig, "ownerUid" | "hqRoot" | "companySlug" | "kind" | "companies" | "workerId">;
+    ops: FleetCronOps;
+    profileDir: string;
+    activeCompany: string | null;
+    ownerCompanies?: readonly string[];
+    otherBotDirs: readonly string[];
+    nodeBinary: string;
+    hqBinary: string;
+    /**
+     * cli.bot-signals-engine-job (default off). Every company still gets the
+     * daily 06:30 hot-signal-sync job; the flag picks what its script runs: the
+     * signals engine when true, the plain hot-channel sync when false. The script
+     * is rewritten on every call, so flipping the flag takes effect on the next
+     * bot start without re-registering the job.
+     */
+    signalsJobEnabled: boolean;
+    now?: Date;
+}
+export interface FleetHotSignalSyncCompanyResult {
+    company: string;
+    created: boolean;
+    job: FleetCronJob | null;
+    heldBy?: string;
+}
+export interface EnsureFleetHotSignalSyncResult {
+    companies: FleetHotSignalSyncCompanyResult[];
+    removed: string[];
+}
+export declare function fleetHotSignalSyncCompanies(config: EnsureFleetHotSignalSyncInput["config"], activeCompany: string | null, ownerCompanies?: readonly string[]): string[];
+export declare function ensureFleetHotSignalSync(input: EnsureFleetHotSignalSyncInput): EnsureFleetHotSignalSyncResult;
+//# sourceMappingURL=fleet-cron.d.ts.map

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

@@ -0,0 +1,319 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { effectiveBotCompanies, effectiveBotKind } from "./config.js";
+import { fleetLocalRuntimePython, stderrTail } from "./fleet-local.js";
+import { readLocalJobs, withJobsLock, writeLocalJobs } from "./local-jobs.js";
+import { currentHotSignalSyncCompany, forgetHotSignalSyncRegistrationsExcept, hotSignalSyncJobCompany, fleetHotSignalSyncRegistered, markFleetHotSignalSyncRegistered, otherBotWithHotSignalSync, } from "./jobs/hot-signal-sync.js";
+const RESULT_MARKER = "@@HQ_FLEET_CRON@@";
+export const FLEET_CRON_BRIDGE = [
+    "import json, os, sys",
+    "sys.path.insert(0, sys.argv[1])",
+    "request = json.loads(sys.stdin.read())",
+    "def emit(value):",
+    `    sys.stdout.write("\\n${RESULT_MARKER}" + json.dumps(value, default=str) + "\\n")`,
+    "try:",
+    "    from cron import jobs as cron_jobs",
+    "    with cron_jobs.use_cron_store(os.environ['HQ_FLEET_HOME']):",
+    "        op = request.get('op')",
+    "        if op == 'list':",
+    "            result = cron_jobs.list_jobs(include_disabled=True)",
+    "        elif op == 'create':",
+    "            result = cron_jobs.create_job(**request['job'])",
+    "        elif op == 'remove':",
+    "            result = cron_jobs.remove_job(request['id'])",
+    "        elif op == 'reschedule':",
+    "            result = cron_jobs.update_job(request['id'], {'schedule': request['schedule']})",
+    "        else:",
+    "            raise ValueError('unknown operation ' + str(op))",
+    "    emit({'ok': True, 'result': result})",
+    "except Exception as exc:",
+    "    emit({'ok': False, 'error': str(exc), 'type': type(exc).__name__})",
+].join("\n");
+function expectedError(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+export function runFleetCronRequest(agentUid, request, deps = {}) {
+    const runtime = fleetLocalRuntimePython(agentUid, deps);
+    const run = deps.run ?? execFileSync;
+    let output;
+    try {
+        output = run(runtime.python, ["-I", "-c", FLEET_CRON_BRIDGE, runtime.source], {
+            input: JSON.stringify(request),
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...(deps.env ?? process.env), HQ_FLEET_HOME: runtime.profileDir, HQ_FLEET_ENABLE_PROJECT_PLUGINS: "0" },
+            timeout: 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+            windowsHide: true,
+        });
+    }
+    catch (error) {
+        const tail = stderrTail(error);
+        throw expectedError(`The HQ Fleet Runtime could not open the bot's scheduled jobs.${tail ? `\n${tail}` : ""}`);
+    }
+    const text = Buffer.isBuffer(output) ? output.toString("utf8") : output;
+    const line = text.split(/\r?\n/).reverse().find((entry) => entry.startsWith(RESULT_MARKER));
+    if (!line)
+        throw expectedError("The HQ Fleet Runtime returned no answer about the bot's scheduled jobs.");
+    let parsed;
+    try {
+        parsed = JSON.parse(line.slice(RESULT_MARKER.length));
+    }
+    catch {
+        throw expectedError("The HQ Fleet Runtime returned an unreadable answer about the bot's scheduled jobs.");
+    }
+    if (parsed.ok !== true) {
+        throw expectedError(typeof parsed.error === "string" && parsed.error ? parsed.error : "The HQ Fleet Runtime refused the change.");
+    }
+    return parsed.result;
+}
+function asJob(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    return typeof record.id === "string" && record.id ? record : null;
+}
+export function fleetCronOps(agentUid, deps = {}) {
+    return {
+        list() {
+            const result = runFleetCronRequest(agentUid, { op: "list" }, deps);
+            return Array.isArray(result) ? result.map(asJob).filter((job) => job !== null) : [];
+        },
+        create(input) {
+            const job = asJob(runFleetCronRequest(agentUid, {
+                op: "create",
+                job: {
+                    prompt: input.prompt,
+                    schedule: input.schedule,
+                    deliver: "origin",
+                    origin: input.origin,
+                    ...(input.name ? { name: input.name } : {}),
+                    ...(input.script ? { script: input.script } : {}),
+                    ...(input.noAgent ? { no_agent: true } : {}),
+                    ...(input.workdir ? { workdir: input.workdir } : {}),
+                },
+            }, deps));
+            if (!job)
+                throw expectedError("The HQ Fleet Runtime did not return the new job.");
+            return job;
+        },
+        remove(id) {
+            return runFleetCronRequest(agentUid, { op: "remove", id }, deps) === true;
+        },
+        reschedule(id, schedule) {
+            return asJob(runFleetCronRequest(agentUid, { op: "reschedule", id, schedule }, deps));
+        },
+    };
+}
+export function fleetOwnerOrigin(ownerUid, jobs = []) {
+    const known = jobs
+        .map((job) => job.origin)
+        .find((origin) => origin && origin.platform === "hqdm" && origin.chat_id === ownerUid && typeof origin.chat_name === "string" && origin.chat_name);
+    return {
+        platform: "hqdm",
+        chat_id: ownerUid,
+        user_id: ownerUid,
+        ...(known ? { chat_name: known.chat_name } : {}),
+    };
+}
+function throwSchedule(message) {
+    throw Object.assign(new Error(message), { expected: true });
+}
+function unshiftDayOfWeekTerm(term) {
+    const step = term.match(/^(.+)\/(\d+)$/);
+    if (step)
+        return `${unshiftDayOfWeekTerm(step[1])}/${step[2]}`;
+    if (term === "*")
+        return term;
+    const range = term.match(/^(\d+)-(\d+)$/);
+    if (range)
+        return `${Number(range[1]) - 1}-${Number(range[2]) - 1}`;
+    if (/^\d+$/.test(term))
+        return String(Number(term) - 1);
+    return term;
+}
+export function fleetScheduleFromLegacy(expr) {
+    const trimmed = expr.trim();
+    const rate = trimmed.match(/^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/i);
+    if (rate)
+        return `every ${rate[1]}${rate[2].toLowerCase()[0]}`;
+    const cron = trimmed.match(/^cron\(\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*\)$/i);
+    if (!cron)
+        throwSchedule(`"${trimmed}" is not a schedule the HQ Fleet Runtime can run.`);
+    const [minute, hour, dayOfMonth, month, dayOfWeek, year] = cron.slice(1);
+    if (year !== "*")
+        throwSchedule(`"${trimmed}" names a year; the HQ Fleet Runtime runs recurring schedules only.`);
+    const dom = dayOfMonth === "?" ? "*" : dayOfMonth;
+    const dow = dayOfWeek === "?" ? "*" : dayOfWeek.split(",").map((term) => unshiftDayOfWeekTerm(term.trim())).join(",");
+    return `${minute} ${hour} ${dom} ${month} ${dow}`;
+}
+function migratedJobsPath(dir, now) {
+    const first = path.join(dir, "jobs.migrated.json");
+    if (!fs.existsSync(first))
+        return first;
+    return path.join(dir, `jobs.migrated-${now.toISOString().replace(/[:.]/g, "-")}.json`);
+}
+export function migrateLegacyJobsToFleet(dir, config, ops, now = new Date()) {
+    const file = path.join(dir, "jobs.json");
+    if (!fs.existsSync(file))
+        return null;
+    return withJobsLock(dir, () => {
+        const legacy = readLocalJobs(dir).filter((job) => hotSignalSyncJobCompany(job.context) === null);
+        if (legacy.length === 0)
+            return null;
+        const existing = ops.list();
+        const origin = fleetOwnerOrigin(config.ownerUid, existing);
+        let imported = 0;
+        let alreadyPresent = 0;
+        const skipped = [];
+        const moved = new Set();
+        for (const job of legacy) {
+            let schedule;
+            try {
+                schedule = /^(cron|rate)\(/i.test(job.cron.trim()) ? fleetScheduleFromLegacy(job.cron) : job.cron.trim();
+            }
+            catch {
+                skipped.push(job.jobId);
+                continue;
+            }
+            const present = existing.some((candidate) => candidate.prompt === job.prompt && candidate.schedule?.expr === schedule);
+            if (present) {
+                alreadyPresent += 1;
+                moved.add(job.jobId);
+                continue;
+            }
+            existing.push(ops.create({ prompt: job.prompt, schedule, origin, workdir: config.hqRoot }));
+            imported += 1;
+            moved.add(job.jobId);
+        }
+        if (skipped.length > 0) {
+            // Some jobs could not move. jobs.json stays, with the jobs that could not
+            // move left in it; only the jobs now in the Fleet schedule leave it.
+            if (moved.size > 0) {
+                const all = readLocalJobs(dir);
+                writeLocalJobs(dir, all.filter((job) => !moved.has(job.jobId)));
+            }
+            return { imported, alreadyPresent, skipped, renamedTo: null };
+        }
+        const renamedTo = migratedJobsPath(dir, now);
+        fs.renameSync(file, renamedTo);
+        return { imported, alreadyPresent, skipped, renamedTo };
+    });
+}
+export const FLEET_HOT_SIGNAL_SYNC_NAME = "hot-signal-sync";
+export const FLEET_HOT_SIGNAL_SYNC_SCHEDULE = "30 6 * * *";
+export function fleetHotSignalSyncScript(company) {
+    return `hot-signal-sync-${company}.py`;
+}
+export function companyOfHotSignalSyncJob(job) {
+    if (job.name !== FLEET_HOT_SIGNAL_SYNC_NAME || typeof job.script !== "string")
+        return null;
+    const match = /^hot-signal-sync-([a-z0-9][a-z0-9_-]*)\.py$/i.exec(path.basename(job.script));
+    return match ? match[1] : null;
+}
+export function renderFleetHotSignalSyncScript(input) {
+    const args = input.signalsEngine === false
+        ? ["sources", "sync", "--company", input.company, "--hq-root", input.hqRoot]
+        : ["signals", "run", "--trigger", "job", "--company", input.company, "--hq-root", input.hqRoot, "--report-found"];
+    // The engine prints only when it finds new signals (--report-found), so its
+    // stdout goes to the owner's DM as is. The plain sync prints a report every
+    // run, so with the flag off its stdout goes to the log and the owner hears
+    // only about a run that failed (for example, nobody signed in).
+    const deliver = input.signalsEngine === false
+        ? [
+            "    with open(LOG, 'a', encoding='utf-8') as log:",
+            "        log.write(result.stdout)",
+            "    if result.returncode != 0:",
+            `        sys.stdout.write(${JSON.stringify(`The 06:30 hot-channel sync for ${input.company} did not finish. Details are in `)} + LOG + '\\n')`,
+        ]
+        : ["    sys.stdout.write(result.stdout)"];
+    return [
+        "import subprocess, sys",
+        `NODE = ${JSON.stringify(input.nodeBinary)}`,
+        `HQ = ${JSON.stringify(input.hqBinary)}`,
+        `ARGS = ${JSON.stringify(args)}`,
+        `LOG = ${JSON.stringify(input.logFile)}`,
+        "try:",
+        "    with open(LOG, 'a', encoding='utf-8') as log:",
+        "        result = subprocess.run([NODE, HQ, *ARGS], stdout=subprocess.PIPE, stderr=log, text=True)",
+        ...deliver,
+        "except OSError as exc:",
+        "    with open(LOG, 'a', encoding='utf-8') as log:",
+        "        log.write('hot-signal-sync could not run hq: ' + str(exc) + '\\n')",
+        "",
+    ].join("\n");
+}
+export function fleetHotSignalSyncCompanies(config, activeCompany, ownerCompanies = []) {
+    const single = currentHotSignalSyncCompany(config, activeCompany);
+    if (config.companySlug || effectiveBotCompanies(config).length > 0 || effectiveBotKind(config) === "company") {
+        return single ? [single] : [];
+    }
+    const owned = [...new Set(ownerCompanies.map((slug) => slug.trim()).filter((slug) => slug && slug !== "personal"))].sort();
+    if (owned.length > 0)
+        return owned;
+    return single ? [single] : [];
+}
+export function ensureFleetHotSignalSync(input) {
+    const companies = fleetHotSignalSyncCompanies(input.config, input.activeCompany, input.ownerCompanies);
+    const wanted = new Set(companies);
+    const jobs = input.ops.list();
+    const removed = [];
+    for (const job of jobs) {
+        const jobCompany = companyOfHotSignalSyncJob(job);
+        if (jobCompany !== null && !wanted.has(jobCompany) && input.ops.remove(job.id))
+            removed.push(job.id);
+    }
+    forgetHotSignalSyncRegistrationsExcept(input.dir, companies);
+    const results = [];
+    let remaining = jobs.filter((job) => !removed.includes(job.id));
+    for (const company of companies) {
+        const result = ensureFleetHotSignalSyncFor(input, company, remaining);
+        if (result.job && !remaining.some((job) => job.id === result.job.id))
+            remaining = [...remaining, result.job];
+        results.push(result);
+    }
+    return { companies: results, removed };
+}
+function ensureFleetHotSignalSyncFor(input, company, jobs) {
+    const scriptName = fleetHotSignalSyncScript(company);
+    const scriptsDir = path.join(input.profileDir, "scripts");
+    fs.mkdirSync(scriptsDir, { recursive: true, mode: 0o700 });
+    const logFile = path.join(input.dir, "logs", "hot-signal-sync.log");
+    fs.mkdirSync(path.dirname(logFile), { recursive: true, mode: 0o700 });
+    const scriptFile = path.join(scriptsDir, scriptName);
+    const temporary = `${scriptFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, renderFleetHotSignalSyncScript({
+        nodeBinary: input.nodeBinary,
+        hqBinary: input.hqBinary,
+        company,
+        hqRoot: input.config.hqRoot,
+        logFile,
+        signalsEngine: input.signalsJobEnabled === true,
+    }), { mode: 0o600 });
+    fs.renameSync(temporary, scriptFile);
+    const current = jobs.find((job) => companyOfHotSignalSyncJob(job) === company) ?? null;
+    if (fleetHotSignalSyncRegistered(input.dir, company))
+        return { company, created: false, job: current };
+    if (current) {
+        markFleetHotSignalSyncRegistered(input.dir, company, input.now);
+        return { company, created: false, job: current };
+    }
+    const heldBy = otherBotWithHotSignalSync(input.dir, company, input.otherBotDirs);
+    if (heldBy)
+        return { company, created: false, job: null, heldBy };
+    const job = input.ops.create({
+        name: FLEET_HOT_SIGNAL_SYNC_NAME,
+        prompt: input.signalsJobEnabled === true
+            ? `Run the signals engine for ${company} and post to the owner only when it finds new signals.`
+            : `Run the hot-channel sync for ${company}.`,
+        schedule: FLEET_HOT_SIGNAL_SYNC_SCHEDULE,
+        script: scriptName,
+        noAgent: true,
+        origin: fleetOwnerOrigin(input.config.ownerUid, [...jobs]),
+        workdir: input.config.hqRoot,
+    });
+    markFleetHotSignalSyncRegistered(input.dir, company, input.now);
+    return { company, created: true, job };
+}
+//# sourceMappingURL=fleet-cron.js.map

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

@@ -1,6 +1,7 @@
 import { type BotEngineMetadata } from "./config.js";
 import type { BotMachineCreds } from "./creds.js";
 import { type FleetPython } from "./fleet-python.js";
+import { vaultApiFetch } from "../../utils/vault-api.js";
 import type { LocalBotPromotionRuntime } from "./promote.js";
 export interface FleetLocalReleasePin {
     repository: string;
@@ -80,7 +81,7 @@ export interface FleetLocalProfileInput {
     };
     /** Companies the owner's own turns may use; other senders get none of them. */
     ownerCompanies?: string[];
-    /** False keeps the runtime's command approval prompts (`hq bot create --no-auto-approve`). */
+    /** True turns the runtime's command approval prompts off for every sender (`hq bot create --auto-approve`). */
     autoApprove?: boolean;
 }
 /** The model the HQ Fleet Runtime asks for when a Claude bot names none. */
@@ -95,10 +96,19 @@ export declare function fleetProviderForRuntime(runtime: string, model?: string)
 /** True when a bot with this provider still needs `hq bot auth` before it can answer. */
 export declare function fleetProviderNeedsSignIn(provider: FleetLocalProfile["provider"]): boolean;
 type FleetLocalExec = (executable: string, args: string[], options: Record<string, unknown>) => Buffer | string;
+/** spawnSync-shaped runner for steps whose output is copied through after they finish. */
+export type FleetLocalSpawn = (executable: string, args: string[], options: Record<string, unknown>) => {
+    status: number | null;
+    stdout?: Buffer | string | null;
+    stderr?: Buffer | string | null;
+    error?: Error;
+};
 export interface FleetLocalBootstrapDeps {
     fleetHome?: string;
     platform?: NodeJS.Platform;
     run?: FleetLocalExec;
+    /** Runs the install steps whose output is copied through. Defaults to spawnSync, or to `run` when only `run` is given. */
+    spawn?: FleetLocalSpawn;
     start?: boolean;
     python?: FleetPython;
 }
@@ -169,12 +179,23 @@ export declare const HQ_FLEET_LOCAL_RELEASE: FleetLocalReleasePin;
 export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=\n-----END PUBLIC KEY-----\n";
 /** hq-fleet-local trust/release-public-v2.pem (added 2026-11-01; signs v0.4.18). */
 export declare const HQ_FLEET_LOCAL_PUBLIC_KEY_V2 = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAmgUi7pKTJUmf3yzwcuH65wSvn1NyJrDfZHZUX08sGN8=\n-----END PUBLIC KEY-----\n";
+/** hq-fleet-local trust/release-public-v3.pem (added 2026-11-02; signs v0.4.20 and later). */
+export declare const HQ_FLEET_LOCAL_PUBLIC_KEY_V3 = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA2NUo6F38D4Kjxmy5qz5ytKRVRwocEvPk8lXqfwB2kS0=\n-----END PUBLIC KEY-----\n";
 /** Every key a release manifest may be signed with. Any one must verify it. */
 export declare const HQ_FLEET_LOCAL_PUBLIC_KEYS: readonly string[];
 /** True when any trusted Ed25519 key verifies the manifest signature. */
 export declare function fleetLocalManifestSignatureValid(manifest: Buffer, signature: Buffer, publicKey?: string | readonly string[]): boolean;
 export declare function fleetHome(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function verifyFleetLocalRelease(files: FleetLocalReleaseFiles, release?: FleetLocalReleasePin, publicKey?: string | readonly string[]): void;
+/**
+ * Check an extracted distribution against the signed manifest: every payload
+ * file present with its hash, and nothing else but the release metadata.
+ */
+export declare function verifyExtractedDistribution(dir: string, manifest: Buffer, version: string): void;
+/** Write a ZIP archive's files under `target` with the same reader that verified it. */
+export declare function extractZipEntries(archive: Buffer, target: string, version: string): void;
+/** Every file in a ZIP archive by name (stored and deflated entries only; directories skipped). */
+export declare function readZipEntries(archive: Buffer): Map<string, Buffer>;
 /**
  * Warning text when the signed manifest asks for a newer hq CLI than this
  * one, or null. Advisory only: the pinned runtime is still installed, since
@@ -185,6 +206,45 @@ export declare function fleetLocalCliCompatibilityWarning(manifest: Buffer, rele
 export declare const FLEET_RELEASE_TOKEN_TIMEOUT_MS = 15000;
 export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv, run?: FleetLocalExec): string;
 export declare function fetchHqFleetReleaseLinks(release: FleetLocalReleasePin): Promise<Map<string, string> | null>;
+export declare const FLEET_LOCAL_LATEST_TIMEOUT_MS = 5000;
+export declare const FLEET_LOCAL_LATEST_CACHE_MS: number;
+export interface FleetLocalReleasePointer {
+    release: FleetLocalReleasePin;
+    minimumHqCli: string | null;
+    links: Map<string, string> | null;
+    linksExpireAt: number | null;
+}
+export interface FleetLocalTargetRelease {
+    release: FleetLocalReleasePin;
+    source: "pointer" | "compiled";
+    links: Map<string, string> | null;
+    linksExpireAt: number | null;
+}
+export declare function parseFleetLocalReleasePin(value: unknown): FleetLocalReleasePin | null;
+export declare function parseFleetLocalReleasePointer(body: unknown, now?: number): FleetLocalReleasePointer | null;
+export declare function chooseFleetLocalTargetRelease(pointer: FleetLocalReleasePointer | null, compiled?: FleetLocalReleasePin, cliVersion?: string): FleetLocalTargetRelease;
+export declare function fetchFleetLocalReleasePointer(deps?: {
+    token?: () => Promise<string>;
+    fetchApi?: typeof vaultApiFetch;
+    now?: () => number;
+}): Promise<FleetLocalReleasePointer | null>;
+export declare function resetFleetLocalReleasePointerCache(): void;
+interface FleetLocalPointerDeps {
+    fleetHome?: string;
+    now?: () => number;
+    fetchPointer?: () => Promise<FleetLocalReleasePointer | null>;
+}
+export declare function resolveFleetLocalTargetRelease(deps?: FleetLocalPointerDeps & {
+    compiled?: FleetLocalReleasePin;
+    cliVersion?: string;
+}): Promise<FleetLocalTargetRelease>;
+export declare function resolveFleetLocalPointerTarget(deps?: FleetLocalPointerDeps & {
+    cliVersion?: string;
+}): Promise<FleetLocalTargetRelease | null>;
+export declare function installTargetFleetLocalDistribution(deps?: Omit<FleetLocalInstallDeps, "release"> & {
+    target?: FleetLocalTargetRelease;
+    now?: () => number;
+}): Promise<FleetLocalInstallation>;
 export declare const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30000;
 export declare const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS: number;
 export declare const FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS: number;
@@ -221,10 +281,42 @@ export declare function writeFleetLocalSoul(agentUid: string, systemPrompt: stri
  * the bot's own interpreter, says beforehand what it would refuse.
  */
 export declare function scanFleetLocalInstructions(agentUid: string, text: string, deps?: FleetLocalControlDeps): string[];
+export declare function fleetLocalRuntimePython(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome" | "platform">): {
+    python: string;
+    source: string;
+    profileDir: string;
+};
+export declare function fleetProfileOwnerCompanies(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): string[];
+export declare function fleetLocalProfileDir(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): string;
+export interface FleetLocalGatewayState {
+    pid: number | null;
+    gatewayState: string | null;
+    activeAgents: number;
+    platforms: Record<string, string>;
+}
+export declare function readFleetLocalGatewayState(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): FleetLocalGatewayState | null;
+export declare function fleetLocalChannels(state: FleetLocalGatewayState | null, gatewayAlive: boolean): {
+    slack: string;
+    telegram: string;
+};
+export declare function fleetLocalBusyReason(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome"> & {
+    isAlive?: (pid: number) => boolean;
+}): string | null;
 /** Checks the instructions with the runtime's scanner, then makes them the bot's persona. */
 export declare function refreshFleetLocalInstructions(agentUid: string, systemPrompt: string, deps?: FleetLocalControlDeps): string;
 /** Last few non-empty stderr lines of a failed child process, trimmed for an error message. */
 export declare function stderrTail(error: unknown): string;
+/** A FleetLocalSpawn backed by an execFileSync-shaped runner (stderr is only known on failure). */
+export declare function spawnFromRun(run: FleetLocalExec): FleetLocalSpawn;
+/**
+ * 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 declare function pipeInheritedStdio(stdio: unknown): {
+    stdio: unknown;
+    forward: boolean;
+};
 /**
  * Message for a Windows extraction that cannot fit under MAX_PATH, or null
  * when it fits or long paths are on. `longest` is the longest member name in