@indigoai-us/hq-cli 5.345.178 → 5.345.180

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

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.104","bundleSha256":"40c72e049db21ee4551fa737676d8022cd090149ede9e3c9e53a9fae3f28dadc","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.105","bundleSha256":"f57aa12671cdfcf08ce39f11ce6885d6e52d5478f2ae77a75d38d79162194ce5","formatVersion":1}

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

@@ -1,6 +1,7 @@
 /**
  * bot.json — non-secret per-bot configuration (local-bots US-003/US-005).
  */
+import type { BotRuntimeAuthMap } from "./runtime-auth.js";
 export declare const BOT_RUNTIMES: readonly ["claude", "codex", "grok"];
 export type BotRuntimeId = (typeof BOT_RUNTIMES)[number];
 export declare const HQ_FLEET_RUNTIME_ENGINE_ID: "hq-fleet-runtime";
@@ -167,6 +168,13 @@ export interface BotConfig {
      * setup bots, which only need files and shell commands.
      */
     lean?: boolean;
+    /**
+     * Which model login each runtime uses (see runtime-auth.ts): unset = the
+     * owner's default sign-in; { mode: "own" } = the bot's own login under
+     * ~/.hq/bots/<name>/auth/<runtime>; { mode: "account", account } = a
+     * capacity account home. Names only, never a credential.
+     */
+    runtimeAuth?: BotRuntimeAuthMap;
 }
 export declare function readBotConfig(dir: string): BotConfig | null;
 export declare function writeBotConfig(dir: string, config: BotConfig): void;

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

@@ -133,7 +133,7 @@ export interface FleetLocalRemovalResult {
     credentialsRemoved: number;
 }
 export declare const HQ_FLEET_LOCAL_RELEASE: FleetLocalReleasePin;
-export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAOOL7NRKQgjMYI5cWxLY+HGppXf2AtwpQbCg5v+nBksM=\n-----END PUBLIC KEY-----\n";
+export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEARXr2I8RNcw2c0Ep77XkYGwylresXBFn8dm9pxN2Zq/U=\n-----END PUBLIC KEY-----\n";
 export declare function fleetHome(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function verifyFleetLocalRelease(files: FleetLocalReleaseFiles, release?: FleetLocalReleasePin, publicKey?: string): void;
 export declare function resolveFleetReleaseToken(env?: NodeJS.ProcessEnv): string;

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

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { HQ_FLEET_RUNTIME_ENGINE_ID, } from "./config.js";
+import { withBotLock } from "./lock.js";
 import { ensureFleetPython, fleetUvEnv } from "./fleet-python.js";
 import { ensureCognitoToken } from "../../utils/cognito-session.js";
 import { vaultApiFetch } from "../../utils/vault-api.js";
@@ -35,18 +36,18 @@ export function fleetProviderNeedsSignIn(provider) {
 }
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.12",
-    version: "0.4.12",
-    artifact: "hq-fleet-local-0.4.12.zip",
-    artifactSha256: "2a07e79b1740e8ef68b19078b73b10cdf9377065a2fd1f53287b7e353099c577",
+    tag: "v0.4.14",
+    version: "0.4.14",
+    artifact: "hq-fleet-local-0.4.14.zip",
+    artifactSha256: "9ff6ad4f7235988468e1913008c5650f5d064210078d6d20c407b17120310f47",
     runtimeArtifact: "hq-fleet-runtime-abccac13bd9e.tar",
     runtimeArtifactSha256: "29bcfe718ad7fbd3636afd00623772f2a25bc84c4f6f10d8d57f38e549d528d5",
-    manifestSha256: "cdac590bdcebea6629de0c164c42c7baf30c025a299ff5829380989dd22a9ff1",
-    signatureSha256: "f07911dd3187393cd325fc8f88ddaa6a7568825aee6d8748a992cea822d5d9b1",
+    manifestSha256: "88e71a733a5f57089764cbf9947fb88025c2263c5f3d62a2c6f5ab3635538871",
+    signatureSha256: "b892b54d6fcb2aaca86d049d7662fe5549a250d81877d6c529288e79ae1565d9",
     runtimeCommit: "abccac13bd9ea593b24c8cd9c0ba28d5c6050cc9",
 };
 export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAOOL7NRKQgjMYI5cWxLY+HGppXf2AtwpQbCg5v+nBksM=
+MCowBQYDK2VwAyEARXr2I8RNcw2c0Ep77XkYGwylresXBFn8dm9pxN2Zq/U=
 -----END PUBLIC KEY-----
 `;
 function digest(value) {
@@ -162,7 +163,7 @@ function trustedReleaseLink(url) {
         return false;
     }
 }
-async function downloadFleetLocalReleaseFromHq(release, fetcher, links) {
+async function downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime) {
     const get = async (name, timeoutMs) => {
         const url = links.get(name);
         if (!url)
@@ -178,7 +179,7 @@ async function downloadFleetLocalReleaseFromHq(release, fetcher, links) {
     };
     const [archive, runtimeArchive, manifest, signature] = await Promise.all([
         get(release.artifact, FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS),
-        get(release.runtimeArtifact, FLEET_LOCAL_RUNTIME_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),
     ]);
@@ -193,7 +194,7 @@ async function responseBytes(response, label) {
 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) {
+async function downloadFleetLocalRelease(release, fetcher, token, cachedRuntime) {
     const headers = {
         Accept: "application/vnd.github+json",
         Authorization: `Bearer ${token}`,
@@ -223,7 +224,7 @@ async function downloadFleetLocalRelease(release, fetcher, token) {
     };
     const [archive, runtimeArchive, manifest, signature] = await Promise.all([
         get(release.artifact, FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS),
-        get(release.runtimeArtifact, FLEET_LOCAL_RUNTIME_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),
     ]);
@@ -274,6 +275,24 @@ function installFiles(target, files, release, publicKey) {
             fs.rmSync(staging, { recursive: true, force: true });
     }
 }
+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);
+        for (const file of fs.readdirSync(directory, { withFileTypes: true })) {
+            if (!file.isFile() || !file.name.startsWith("hq-fleet-runtime-") || !file.name.endsWith(".tar"))
+                continue;
+            const bytes = fs.readFileSync(path.join(directory, file.name));
+            if (digest(bytes) === release.runtimeArtifactSha256)
+                return bytes;
+        }
+    }
+    return null;
+}
 export async function installPinnedFleetLocalDistribution(deps = {}) {
     const release = deps.release ?? HQ_FLEET_LOCAL_RELEASE;
     const publicKey = deps.publicKey ?? HQ_FLEET_LOCAL_PUBLIC_KEY;
@@ -286,9 +305,10 @@ export async function installPinnedFleetLocalDistribution(deps = {}) {
     else {
         const fetcher = deps.fetch ?? fetch;
         const links = await (deps.hqReleaseLinks ?? fetchHqFleetReleaseLinks)(release);
+        const cachedRuntime = cachedRuntimeArchive(root, release);
         const files = links
-            ? await downloadFleetLocalReleaseFromHq(release, fetcher, links)
-            : await downloadFleetLocalRelease(release, fetcher, (deps.token ?? resolveFleetReleaseToken)());
+            ? await downloadFleetLocalReleaseFromHq(release, fetcher, links, cachedRuntime)
+            : await downloadFleetLocalRelease(release, fetcher, (deps.token ?? resolveFleetReleaseToken)(), cachedRuntime);
         verifyFleetLocalRelease(files, release, publicKey);
         installFiles(dir, files, release, publicKey);
     }
@@ -744,21 +764,30 @@ export function importFleetLocalMachineCredential(agentUid, machineCredentials,
     ], { input: machineValue, stdio: ["pipe", "ignore", "pipe"] }, "machine credential import");
     fs.rmSync(machineCredentials, { force: true });
 }
-export async function bootstrapFleetLocalBot(input, deps = {}) {
-    const run = deps.run ?? execFileSync;
-    const platform = deps.platform ?? process.platform;
-    const root = deps.fleetHome ?? fleetHome();
-    const python = deps.python ?? await ensureFleetPython({ fleetHome: root, platform, run });
-    const profileDir = profileRoot(input.agentUid, root);
-    const sources = path.join(profileDir, "sources");
-    const distributionSource = path.join(sources, "distribution");
-    const runtimeSource = path.join(sources, "runtime");
-    const runtimeDir = path.join(profileDir, "runtime");
-    const marker = path.join(profileDir, "bootstrap.json");
-    fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
-    if (!fs.existsSync(marker)) {
-        fs.rmSync(sources, { recursive: true, force: true });
-        fs.rmSync(runtimeDir, { recursive: true, force: true });
+async function installSharedFleetRuntime(installation, root, python, platform, run) {
+    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 shared = path.join(root, "runtimes", identity);
+    return withBotLock(identity, async () => {
+        const marker = path.join(shared, "ready.json");
+        const sources = path.join(shared, "sources");
+        const distributionSource = path.join(sources, "distribution");
+        const runtimeSource = path.join(sources, "runtime");
+        const runtimeDir = path.join(shared, "runtime");
+        const executables = ["python", "hq-fleet", "hq-fleet-local"];
+        if (fs.existsSync(marker)) {
+            if (!executables.every((name) => fs.existsSync(venvExecutable(runtimeDir, name, platform)))) {
+                throw expectedError("The shared HQ Fleet Runtime is incomplete. Reinstall it before creating another bot.");
+            }
+            return shared;
+        }
+        fs.rmSync(shared, { recursive: true, force: true });
         fs.mkdirSync(distributionSource, { recursive: true, mode: 0o700 });
         fs.mkdirSync(runtimeSource, { recursive: true, mode: 0o700 });
         const uvEnv = fleetUvEnv(python.pythonDir);
@@ -766,14 +795,14 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
             "-m",
             "zipfile",
             "-e",
-            input.installation.archive,
+            installation.archive,
             distributionSource,
         ], { stdio: "ignore" }, "distribution extraction");
         checkedRun(run, python.python, [
             "-m",
             "tarfile",
             "-e",
-            input.installation.runtimeArchive,
+            installation.runtimeArchive,
             runtimeSource,
         ], { stdio: "ignore" }, "runtime extraction");
         checkedRun(run, python.uv, [
@@ -794,6 +823,29 @@ export async function bootstrapFleetLocalBot(input, deps = {}) {
             `${runtimeSource}[mcp,anthropic]`,
             distributionSource,
         ], { stdio: ["ignore", 2, 2], env: uvEnv }, "package installation");
+        if (!executables.every((name) => fs.existsSync(venvExecutable(runtimeDir, name, platform)))) {
+            throw expectedError("HQ Fleet Local installed without its runtime executables.");
+        }
+        fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, engine: installation.engine })}\n`, { mode: 0o600 });
+        return shared;
+    }, { root: path.join(root, "runtimes"), command: "HQ Fleet Runtime installation", waitMs: 20 * 60_000, staleMs: 2 * 60 * 60_000 });
+}
+export async function bootstrapFleetLocalBot(input, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const platform = deps.platform ?? process.platform;
+    const root = deps.fleetHome ?? fleetHome();
+    const python = deps.python ?? await ensureFleetPython({ fleetHome: root, platform, run });
+    const profileDir = profileRoot(input.agentUid, root);
+    const runtimeDir = path.join(profileDir, "runtime");
+    const marker = path.join(profileDir, "bootstrap.json");
+    fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(marker)) {
+        const shared = await installSharedFleetRuntime(input.installation, root, python, platform, run);
+        for (const name of ["sources", "runtime"]) {
+            const target = path.join(profileDir, name);
+            fs.rmSync(target, { recursive: true, force: true });
+            fs.symlinkSync(path.join(shared, name), target, platform === "win32" ? "junction" : "dir");
+        }
         fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, engine: input.installation.engine }, null, 2)}\n`, { mode: 0o600 });
     }
     const { systemPrompt, ...profileInput } = input;

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

@@ -0,0 +1,109 @@
+/**
+ * The bot's built-in hot-signal-sync job.
+ *
+ * A local bot that is bound to a company registers one recurring job in its
+ * own `jobs.json` the first time it starts (`ensureHotSignalSyncJob`). The job
+ * fires from the bot's inbox loop like every other local job
+ * (lib/bot/local-jobs.ts): no crontab, launchd or systemd entry is written.
+ * The default schedule is 06:30 daily in the machine's time zone, ahead of a
+ * morning brief; the owner changes it with
+ * `hq bot jobs <bot> --reschedule <jobId> --every "<when>"`, or removes it with
+ * `--rm`, and a removed job is not added back on the next start.
+ *
+ * When the job fires the bot runs the sync in-process, with no model turn
+ * (`runHotSignalSyncJob`): the same hot-channel sync `hq sources sync` runs,
+ * with `trigger: "scheduled"` and `catchUp` set when the run fired late after
+ * a missed window. Catch-up is bounded by each adapter's `catchUpWindow`, and
+ * per-connection cursors keep a redelivered run from landing anything twice.
+ * The claude signals pass (US-011) runs after each adapter when the bot wires
+ * one in; with none the signals count is 0.
+ */
+import type { HotChannelRunResult, WriteGuard } from "../../hot-channels/loop.js";
+import type { RunTrigger } from "../../hot-channels/ledger.js";
+import type { OnDemandSyncReport } from "../../hot-channels/run.js";
+import { type BotConfig } from "../config.js";
+import { type LocalJob } from "../local-jobs.js";
+export declare const HOT_SIGNAL_SYNC_JOB_KIND = "hot-signal-sync";
+/**
+ * 06:30 every day, in the job's time zone (the stored EventBridge form of
+ * "30 6 * * *"). Only the first registration uses it; after that the job's
+ * own schedule in `jobs.json` is the one that runs.
+ */
+export declare const HOT_SIGNAL_SYNC_DEFAULT_CRON = "cron(30 6 * * ? *)";
+/** The private context that marks a job as this built-in, for one company. */
+export declare function hotSignalSyncJobContext(company: string): Record<string, unknown>;
+/** The company a job item syncs, when its context marks it as this built-in; else null. */
+export declare function hotSignalSyncJobCompany(context: unknown): string | null;
+/**
+ * The company a bot's hot-signal-sync job syncs: the bot's own company, else
+ * the first company it serves. Null = none, and no job is registered. There is
+ * no fallback to the HQ's active company: a personal bot syncs a company only
+ * when it was given one explicitly (`--company`), so the job never writes into
+ * a vault the bot does not belong to. Checked again each time the job fires.
+ */
+export declare function currentHotSignalSyncCompany(config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId">): string | null;
+/**
+ * Remove every hot-signal-sync job whose company is not `current` (all of them
+ * when `current` is null), and forget their registration so the company can be
+ * registered again if the bot is given it back. Returns the removed jobs.
+ */
+export declare function removeStaleHotSignalSyncJobs(dir: string, current: string | null): LocalJob[];
+export interface EnsureHotSignalSyncJobResult {
+    /** The job, or null when the owner removed it after it was first registered. */
+    job: LocalJob | null;
+    created: boolean;
+}
+/**
+ * Register the hot-signal-sync job for `company` once. Safe to call on every
+ * bot start: an existing job is left as it is (including a changed schedule),
+ * and a job the owner removed is not added again.
+ */
+export declare function ensureHotSignalSyncJob(dir: string, input: {
+    company: string;
+    timezone: string;
+}, now?: Date): EnsureHotSignalSyncJobResult;
+/**
+ * The signals pass over one adapter's landed sources: how many signals it
+ * generated. The bot wires the local `claude -p` pass
+ * (`createClaudeSignalsPass`); `noLocalSignalsPass` is the default when no
+ * pass is given.
+ */
+export type LocalSignalsPass = (result: HotChannelRunResult, guard?: WriteGuard) => Promise<number>;
+export declare const noLocalSignalsPass: LocalSignalsPass;
+/** One company's hot-channel sync, as `runCompanyHotChannelSync` runs it (minus the HQ root). */
+export type HotSignalSyncFn = (input: {
+    company: string;
+    trigger: RunTrigger;
+    catchUp: boolean;
+    signalsGenerated: LocalSignalsPass;
+    now: () => Date;
+    /** The owner DM for the signals-failure alert (US-012); unset = no alert check. */
+    signalsAlert?: {
+        sendOwnerDm: (text: string) => Promise<void>;
+        log?: (message: string) => void;
+    };
+}) => Promise<OnDemandSyncReport>;
+export interface HotSignalSyncRunInput {
+    company: string;
+    /** The run fired late, after a missed window (job-run.ts `isCatchUpRun`). */
+    catchUp: boolean;
+    now: () => Date;
+    sync: HotSignalSyncFn;
+    signalsPass?: LocalSignalsPass;
+    /**
+     * Sends the signals-failure alert to the owner as its own message, even when
+     * the job is quiet. Throws when the message was not delivered.
+     */
+    sendAlert?: (text: string) => Promise<void>;
+    log?: (message: string) => void;
+}
+export interface HotSignalSyncRunOutcome {
+    ok: boolean;
+    /** Plain report for the owner's DM and the job's run output. */
+    text: string;
+    report: OnDemandSyncReport | null;
+}
+/** 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;
+//# sourceMappingURL=hot-signal-sync.d.ts.map

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

@@ -0,0 +1,177 @@
+/**
+ * The bot's built-in hot-signal-sync job.
+ *
+ * A local bot that is bound to a company registers one recurring job in its
+ * own `jobs.json` the first time it starts (`ensureHotSignalSyncJob`). The job
+ * fires from the bot's inbox loop like every other local job
+ * (lib/bot/local-jobs.ts): no crontab, launchd or systemd entry is written.
+ * The default schedule is 06:30 daily in the machine's time zone, ahead of a
+ * morning brief; the owner changes it with
+ * `hq bot jobs <bot> --reschedule <jobId> --every "<when>"`, or removes it with
+ * `--rm`, and a removed job is not added back on the next start.
+ *
+ * When the job fires the bot runs the sync in-process, with no model turn
+ * (`runHotSignalSyncJob`): the same hot-channel sync `hq sources sync` runs,
+ * with `trigger: "scheduled"` and `catchUp` set when the run fired late after
+ * a missed window. Catch-up is bounded by each adapter's `catchUpWindow`, and
+ * per-connection cursors keep a redelivered run from landing anything twice.
+ * The claude signals pass (US-011) runs after each adapter when the bot wires
+ * one in; with none the signals count is 0.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { JOB_RUN_OPTIONS_CONTEXT_KEY } from "../job-run.js";
+import { effectiveBotCompanies } from "../config.js";
+import { ensureLocalJob, readLocalJobs, removeLocalJobsWhere, withJobsLock } from "../local-jobs.js";
+export const HOT_SIGNAL_SYNC_JOB_KIND = "hot-signal-sync";
+/**
+ * 06:30 every day, in the job's time zone (the stored EventBridge form of
+ * "30 6 * * *"). Only the first registration uses it; after that the job's
+ * own schedule in `jobs.json` is the one that runs.
+ */
+export const HOT_SIGNAL_SYNC_DEFAULT_CRON = "cron(30 6 * * ? *)";
+/** Which built-in jobs this bot has registered once, so a removed one stays removed. */
+const BUILTIN_JOBS_FILE = "builtin-jobs.json";
+function markerKey(company) {
+    return `${HOT_SIGNAL_SYNC_JOB_KIND}:${company}`;
+}
+function readMarker(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, BUILTIN_JOBS_FILE), "utf-8"));
+        if (parsed && parsed.v === 1 && parsed.registered && typeof parsed.registered === "object") {
+            return { v: 1, registered: { ...parsed.registered } };
+        }
+    }
+    catch {
+        // Missing or unreadable: nothing registered yet.
+    }
+    return { v: 1, registered: {} };
+}
+function writeMarker(dir, marker) {
+    const file = path.join(dir, BUILTIN_JOBS_FILE);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** The private context that marks a job as this built-in, for one company. */
+export function hotSignalSyncJobContext(company) {
+    return { [JOB_RUN_OPTIONS_CONTEXT_KEY]: { builtin: HOT_SIGNAL_SYNC_JOB_KIND, company } };
+}
+/** The company a job item syncs, when its context marks it as this built-in; else null. */
+export function hotSignalSyncJobCompany(context) {
+    if (!context || typeof context !== "object" || Array.isArray(context))
+        return null;
+    const options = context[JOB_RUN_OPTIONS_CONTEXT_KEY];
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        return null;
+    const { builtin, company } = options;
+    if (builtin !== HOT_SIGNAL_SYNC_JOB_KIND)
+        return null;
+    return typeof company === "string" && company.trim() ? company.trim() : null;
+}
+/**
+ * The company a bot's hot-signal-sync job syncs: the bot's own company, else
+ * the first company it serves. Null = none, and no job is registered. There is
+ * no fallback to the HQ's active company: a personal bot syncs a company only
+ * when it was given one explicitly (`--company`), so the job never writes into
+ * a vault the bot does not belong to. Checked again each time the job fires.
+ */
+export function currentHotSignalSyncCompany(config) {
+    return config.companySlug ?? effectiveBotCompanies(config)[0] ?? null;
+}
+/**
+ * Remove every hot-signal-sync job whose company is not `current` (all of them
+ * when `current` is null), and forget their registration so the company can be
+ * registered again if the bot is given it back. Returns the removed jobs.
+ */
+export function removeStaleHotSignalSyncJobs(dir, current) {
+    const removed = removeLocalJobsWhere(dir, (job) => {
+        const company = hotSignalSyncJobCompany(job.context);
+        return company !== null && company !== current;
+    });
+    const keep = current ? markerKey(current) : null;
+    withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        let changed = false;
+        for (const key of Object.keys(marker.registered)) {
+            if (key.startsWith(HOT_SIGNAL_SYNC_JOB_KIND + ":") && key !== keep) {
+                delete marker.registered[key];
+                changed = true;
+            }
+        }
+        if (changed)
+            writeMarker(dir, marker);
+    });
+    return removed;
+}
+/**
+ * Register the hot-signal-sync job for `company` once. Safe to call on every
+ * bot start: an existing job is left as it is (including a changed schedule),
+ * and a job the owner removed is not added again.
+ */
+export function ensureHotSignalSyncJob(dir, input, now = new Date()) {
+    const key = markerKey(input.company);
+    const matches = (job) => hotSignalSyncJobCompany(job.context) === input.company;
+    if (readMarker(dir).registered[key]) {
+        return { job: readLocalJobs(dir).find(matches) ?? null, created: false };
+    }
+    const { job, created } = ensureLocalJob(dir, matches, {
+        prompt: `Sync hot channels for ${input.company} and run the signals pass (runs in the bot, no model turn).`,
+        cron: HOT_SIGNAL_SYNC_DEFAULT_CRON,
+        timezone: input.timezone,
+        context: hotSignalSyncJobContext(input.company),
+    }, now);
+    withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        if (!marker.registered[key]) {
+            marker.registered[key] = now.toISOString();
+            writeMarker(dir, marker);
+        }
+    });
+    return { job, created };
+}
+export const noLocalSignalsPass = async () => 0;
+/** Run the scheduled sync once and describe it in plain words. Never throws. */
+export async function runHotSignalSyncJob(input) {
+    const signalsPass = input.signalsPass ?? noLocalSignalsPass;
+    let report;
+    try {
+        report = await input.sync({
+            company: input.company,
+            trigger: "scheduled",
+            catchUp: input.catchUp,
+            signalsGenerated: signalsPass,
+            now: input.now,
+            ...(input.sendAlert
+                ? { signalsAlert: { sendOwnerDm: input.sendAlert, ...(input.log ? { log: input.log } : {}) } }
+                : {}),
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, text: `The hot-channel sync for ${input.company} failed: ${reason}`, report: null };
+    }
+    return { ok: report.exitCode === 0 && !report.signInRequired, text: describeSyncReport(input.company, report), report };
+}
+export function describeSyncReport(company, report) {
+    if (report.signInRequired) {
+        return `The hot-channel sync for ${company} did not run: ${report.notices.join(" ")}`;
+    }
+    if (report.skipped)
+        return report.notices.join(" ");
+    const landed = report.outcomes.reduce((sum, o) => sum + o.landed, 0);
+    const signals = report.entries.reduce((sum, e) => sum + e.signalsGenerated, 0);
+    const lines = [
+        `Hot-channel sync for ${company}: ${landed} new source${landed === 1 ? "" : "s"}, ${signals} signal${signals === 1 ? "" : "s"}.`,
+    ];
+    for (const outcome of report.outcomes) {
+        if (outcome.status === "ok")
+            continue;
+        const label = outcome.appName ?? outcome.adapter;
+        lines.push(`- ${label}: ${outcome.reconnect?.prompt ?? outcome.message ?? outcome.status}`);
+    }
+    for (const notice of report.notices)
+        lines.push(notice);
+    return lines.join("\n");
+}
+//# sourceMappingURL=hot-signal-sync.js.map

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

@@ -18,7 +18,7 @@
  * - A fire is recorded before it is handed over, so a crash never runs the
  *   same due time twice.
  */
-import { type BotApi, type InboxItem } from "./api.js";
+import { type BotApi, type BotJobRecord, type InboxItem } from "./api.js";
 export interface LocalJob {
     jobId: string;
     prompt: string;
@@ -27,6 +27,12 @@ export interface LocalJob {
     timezone: string;
     context?: Record<string, unknown>;
     createdAt: string;
+    /**
+     * When the schedule was last changed (`hq bot jobs --reschedule`). Fire
+     * times before it are never treated as missed, so a new schedule does not
+     * fire a catch-up for a time that only matches the new expression.
+     */
+    scheduledFrom?: string;
     /** The newest due time already handed to the bot. */
     lastFiredAt?: string;
     /** The run in progress, if any. */
@@ -72,6 +78,29 @@ export declare function addLocalJob(dir: string, input: {
     timezone: string;
     context?: Record<string, unknown>;
 }, now?: Date): LocalJob;
+/**
+ * Add a job unless one already matches, as one locked read-and-write, so two
+ * bot starts racing each other still leave a single job.
+ */
+export declare function ensureLocalJob(dir: string, matches: (job: LocalJob) => boolean, input: {
+    prompt: string;
+    cron: string;
+    timezone: string;
+    context?: Record<string, unknown>;
+}, now?: Date): {
+    job: LocalJob;
+    created: boolean;
+};
+/**
+ * Change a job's schedule in place, keeping its id, instruction, context and
+ * run history. Returns null when the bot has no job with that id.
+ */
+export declare function rescheduleLocalJob(dir: string, jobId: string, schedule: {
+    cron: string;
+    timezone: string;
+}, now?: Date): LocalJob | null;
+/** Remove every job `matches` picks, as one locked read-and-write. Returns the removed jobs. */
+export declare function removeLocalJobsWhere(dir: string, matches: (job: LocalJob) => boolean): LocalJob[];
 /** Forget the once-per-minute check (tests, and a bot restarted in-process). */
 export declare function resetLocalJobChecks(): void;
 export declare function takeDueLocalJobRuns(dir: string, now?: Date): InboxItem[];
@@ -81,9 +110,16 @@ export declare function takeDueLocalJobRuns(dir: string, now?: Date): InboxItem[
  * locally instead of being sent to the cloud.
  */
 export declare function withLocalJobs(api: BotApi, dir: string, clock?: () => Date): BotApi;
+/** What `hq bot jobs` uses: list, add, remove, and (local bots) reschedule. */
+export type LocalJobsApi = Pick<BotApi, "listJobs" | "createJob" | "cancelJob"> & {
+    rescheduleJob?(agentUid: string, jobId: string, schedule: {
+        cron: string;
+        timezone: string;
+    }): Promise<BotJobRecord>;
+};
 /**
- * `hq bot jobs` against the bot's own folder: the same three calls the cloud
- * client offers, answered from `jobs.json`.
+ * `hq bot jobs` against the bot's own folder: the same calls the cloud client
+ * offers, plus reschedule, answered from `jobs.json`.
  */
-export declare function localJobsClient(dir: string, clock?: () => Date): Pick<BotApi, "listJobs" | "createJob" | "cancelJob">;
+export declare function localJobsClient(dir: string, clock?: () => Date): Required<LocalJobsApi>;
 //# sourceMappingURL=local-jobs.d.ts.map