@indigoai-us/hq-cli 5.345.183 → 5.345.188

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

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.106","bundleSha256":"ae4c7a7b3040977faff6e9ea7f302bc9e46cf77675347788642e362c3337e3fe","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.107","bundleSha256":"0df48ddf2618cac4801b8abefa1d2a4b4a915f368bf7d1b2823bcdd104044325","formatVersion":1}

package/dist/lib/agent-kit/inbox-fetch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import type { MergedInbox } from "./inbox-state.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export declare const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export declare const AGENT_INBOX_RETRY_BASE_MS = 1500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export declare const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export declare const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5000;
+/** Total attempts: the first read plus one retry. */
+export declare const AGENT_INBOX_MAX_ATTEMPTS = 2;
+export interface InboxFetchResponse {
+    status: number;
+    /** Decoded JSON body, or `undefined` when it did not decode. Never a raw string of response bytes. */
+    body: unknown;
+    /** Parsed numeric `Retry-After` header in seconds, when the server sent one. */
+    retryAfterSeconds?: number;
+}
+export interface FetchServerInboxDeps {
+    /** Mint (or fetch from cache) the machine token. Called again for the retry. */
+    mint: (signal: AbortSignal) => Promise<string>;
+    /** GET the inbox with `token`. Must not throw on a non-2xx status. */
+    fetch: (token: string, signal: AbortSignal) => Promise<InboxFetchResponse>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Uniform [0, 1) source for the jitter. */
+    random?: () => number;
+    /** Per-attempt deadline covering mint plus GET. */
+    timeoutMs?: number;
+}
+export type FetchServerInboxOutcome = {
+    ok: true;
+    response: {
+        status: number;
+        body: unknown;
+    };
+    attempts: number;
+} | {
+    ok: false;
+    error: unknown;
+    attempts: number;
+};
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export declare function resolveAgentInboxTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** Whether a thrown first attempt is worth one more try. */
+export declare function isRetryableInboxError(err: unknown): boolean;
+export declare function isRetryableInboxStatus(status: number): boolean;
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export declare function parseRetryAfterSeconds(header: string | null | undefined): number | undefined;
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export declare function fetchServerInboxWithRetry(deps: FetchServerInboxDeps): Promise<FetchServerInboxOutcome>;
+/** Suffix added to the degradation note when the retry also failed. */
+export declare const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = " (after 2 attempts)";
+export interface AnnotatedInbox extends MergedInbox {
+    /** True whenever the answer is not a complete server read. */
+    stale: boolean;
+    /** Present when more than one attempt was made, so a hard failure is distinct from a single blip. */
+    attempts?: number;
+}
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export declare function annotateInboxAttempts(merged: MergedInbox, attempts: number): AnnotatedInbox;
+//# sourceMappingURL=inbox-fetch.d.ts.map

package/dist/lib/agent-kit/inbox-fetch.js

@@ -0,0 +1,135 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import { networkTransportErrorCode } from "../../utils/network-transport-error.js";
+import { KIT_REQUEST_TIMEOUT_MIN_MS, KIT_REQUEST_TIMEOUT_MS, KitRequestTimeoutError, withRequestTimeout } from "./run/request-timeout.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export const AGENT_INBOX_RETRY_BASE_MS = 1_500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5_000;
+/** Total attempts: the first read plus one retry. */
+export const AGENT_INBOX_MAX_ATTEMPTS = 2;
+// 504 is absent on purpose: vaultApiFetch already retries a 504 once
+// (Lambda invoke errors), and a second outer retry would make three GETs.
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503]);
+const LOCK_HELD_RE = /held by another process/i;
+const TRANSPORT_MESSAGE_RE = /\b(fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/;
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export function resolveAgentInboxTimeoutMs(env = process.env) {
+    const raw = env[AGENT_INBOX_TIMEOUT_ENV]?.trim();
+    if (!raw)
+        return KIT_REQUEST_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return KIT_REQUEST_TIMEOUT_MS;
+    return Math.max(KIT_REQUEST_TIMEOUT_MIN_MS, Math.floor(n));
+}
+/** Whether a thrown first attempt is worth one more try. */
+export function isRetryableInboxError(err) {
+    if (err instanceof KitRequestTimeoutError)
+        return true;
+    if (!(err instanceof Error))
+        return false;
+    if (LOCK_HELD_RE.test(err.message))
+        return true;
+    if (networkTransportErrorCode(err) !== null)
+        return true;
+    if (err instanceof TypeError && err.message === "fetch failed")
+        return true;
+    return TRANSPORT_MESSAGE_RE.test(err.message);
+}
+export function isRetryableInboxStatus(status) {
+    return RETRYABLE_STATUSES.has(status);
+}
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export function parseRetryAfterSeconds(header) {
+    if (header === null || header === undefined)
+        return undefined;
+    const trimmed = header.trim();
+    if (!/^\d+(\.\d+)?$/.test(trimmed))
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function retryDelayMs(retryAfterSeconds, random) {
+    if (retryAfterSeconds !== undefined) {
+        return Math.min(AGENT_INBOX_RETRY_AFTER_CAP_MS, Math.round(retryAfterSeconds * 1000));
+    }
+    return AGENT_INBOX_RETRY_BASE_MS + Math.floor(random() * AGENT_INBOX_RETRY_JITTER_MS);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export async function fetchServerInboxWithRetry(deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const timeoutMs = deps.timeoutMs ?? KIT_REQUEST_TIMEOUT_MS;
+    let attempts = 0;
+    for (;;) {
+        attempts += 1;
+        const last = attempts >= AGENT_INBOX_MAX_ATTEMPTS;
+        let retryAfterSeconds;
+        try {
+            const res = await withRequestTimeout(timeoutMs, undefined, async (signal) => {
+                const token = await deps.mint(signal);
+                return deps.fetch(token, signal);
+            });
+            if (last || !isRetryableInboxStatus(res.status)) {
+                return { ok: true, response: { status: res.status, body: res.body }, attempts };
+            }
+            retryAfterSeconds = res.retryAfterSeconds;
+        }
+        catch (err) {
+            if (last || !isRetryableInboxError(err))
+                return { ok: false, error: err, attempts };
+        }
+        await sleep(retryDelayMs(retryAfterSeconds, random));
+    }
+}
+/** Suffix added to the degradation note when the retry also failed. */
+export const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = ` (after ${AGENT_INBOX_MAX_ATTEMPTS} attempts)`;
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export function annotateInboxAttempts(merged, attempts) {
+    const stale = merged.source !== "server";
+    const retried = attempts > 1;
+    const note = merged.note && retried && stale ? `${merged.note}${AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX}` : merged.note;
+    return {
+        entries: merged.entries,
+        source: merged.source,
+        stale,
+        ...(note ? { note } : {}),
+        ...(retried ? { attempts } : {}),
+    };
+}
+//# sourceMappingURL=inbox-fetch.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -16,6 +16,7 @@
  * tool result.
  */
 import type { ExternalMachineCreds } from "../creds.js";
+import { type FetchServerInboxDeps } from "../inbox-fetch.js";
 import type { AgentKitPaths } from "../paths.js";
 import { type McpTool } from "./jsonrpc.js";
 export interface HqRunResult {
@@ -32,7 +33,8 @@ export interface McpToolClients {
     paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
-    getToken: () => Promise<string>;
+    /** Machine token; `signal` cancels this caller's wait on a shared mint. */
+    getToken: (signal?: AbortSignal) => Promise<string>;
     /**
      * Whether this kit mirrors the vault to disk. Off by default, and it decides
      * what `hq_search` can honestly do: the local qmd index only exists when
@@ -47,15 +49,22 @@ export interface McpToolClients {
      * key through the presign API, as the machine identity.
      */
     downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
-    /** Authenticated JSON call against the control plane. */
+    /**
+     * Authenticated JSON call against the control plane. `retryAfterSeconds` is
+     * the server's numeric `Retry-After`, when it sent one.
+     */
     apiJson: (token: string, path: string, init?: {
         method?: string;
         body?: Record<string, unknown>;
         query?: Record<string, string>;
+        signal?: AbortSignal;
     }) => Promise<{
         status: number;
         body: unknown;
+        retryAfterSeconds?: number;
     }>;
+    /** Test seam for hq_inbox_read's bounded retry (sleep, jitter source, per-attempt deadline). */
+    inboxRetry?: Pick<FetchServerInboxDeps, "sleep" | "random" | "timeoutMs">;
 }
 export declare function clampOutput(text: string, max?: number): string;
 /** Vault paths are company-anchored and must not escape. */

package/dist/lib/agent-kit/mcp/tools.js

@@ -19,6 +19,7 @@ import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
 import { PERSON_AGENT_AUDIENCE_MESSAGE, callerMayUseAudience, defaultAudienceFor, isAgentUid, isRecipientUid } from "../../../lib/notify-recipient.js";
 import { tokenIsMachinePrincipal } from "../../../lib/caller-principal.js";
+import { annotateInboxAttempts, fetchServerInboxWithRetry, resolveAgentInboxTimeoutMs } from "../inbox-fetch.js";
 import { redactAgentInboxItem } from "../inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { AttachmentCompanyUnresolvedError, fetchChatAttachment } from "./attachments.js";
@@ -286,10 +287,21 @@ export function buildAgentMcpTools(clients) {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
                 const includeDone = args.include_done === true;
                 const done = readDoneIds(clients.paths);
-                const { entries, note: serverNote, source } = await mergeAgentInbox(clients.paths, async () => {
-                    const token = await clients.getToken();
-                    return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                // Same bounded, once-retried server read as `hq agent inbox`.
+                let attempts = 1;
+                const merged = await mergeAgentInbox(clients.paths, async () => {
+                    const outcome = await fetchServerInboxWithRetry({
+                        timeoutMs: resolveAgentInboxTimeoutMs(process.env),
+                        ...clients.inboxRetry,
+                        mint: (signal) => clients.getToken(signal),
+                        fetch: (token, signal) => clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`, { signal }),
+                    });
+                    attempts = outcome.attempts;
+                    if (!outcome.ok)
+                        throw outcome.error;
+                    return outcome.response;
                 });
+                const { entries, note: serverNote, source, stale, attempts: attemptsMade } = annotateInboxAttempts(merged, attempts);
                 const byId = new Map(entries.map((e) => [e.id, e]));
                 const rows = [...byId.values()]
                     .filter((e) => includeDone || !done.has(e.id))
@@ -299,6 +311,8 @@ export function buildAgentMcpTools(clients) {
                 return textResult(clampOutput(JSON.stringify({
                     count: rows.length,
                     source,
+                    stale,
+                    ...(attemptsMade !== undefined ? { attempts: attemptsMade } : {}),
                     messages: rows,
                     ...(serverNote ? { note: serverNote } : {}),
                     ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),

package/dist/lib/anywhere-person-setting.js

@@ -7,6 +7,20 @@ function hasPersonTokenCache(env, home) {
     const stateDir = env.HQ_STATE_DIR?.trim() || path.join(home, ".hq");
     return fs.existsSync(path.join(stateDir, "cognito-tokens.json"));
 }
+const HQ_ANYWHERE_OPT_OUT_KEY = "hq-anywhere-opt-out";
+const HQ_ANYWHERE_OPT_IN_KEY = "hq-anywhere";
+async function readPersonSettingEnvelope(fetchImpl, apiBaseUrl, token, key) {
+    const response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/v1/bot/auto-schedule?setting=${key}`, { method: "GET", headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(5_000) });
+    if (!response.ok)
+        return null;
+    const body = await response.json();
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return null;
+    const envelope = body;
+    if (envelope.key !== key || typeof envelope.value !== "boolean")
+        return null;
+    return { key: envelope.key, value: envelope.value };
+}
 /** Returns null when the person preference cannot be read; callers must fail closed. */
 export async function readHqAnywherePersonSetting(options = {}) {
     const env = options.env ?? process.env;
@@ -21,16 +35,16 @@ export async function readHqAnywherePersonSetting(options = {}) {
         });
         const token = await getPersonToken();
         const apiBaseUrl = options.apiBaseUrl ?? env.HQ_PRO_API_URL ?? env.HQ_API_URL ?? env.HQ_VAULT_API_URL ?? "https://hqapi.hq.computer";
-        const response = await (options.fetchImpl ?? fetch)(`${apiBaseUrl.replace(/\/$/, "")}/v1/bot/auto-schedule?setting=hq-anywhere`, { method: "GET", headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(5_000) });
-        if (!response.ok)
-            throw new Error(`Http${response.status}`);
-        const body = await response.json();
-        if (typeof body !== "object" || body === null || Array.isArray(body))
-            throw new Error("InvalidEnvelope");
-        const envelope = body;
-        if (envelope.key !== "hq-anywhere" || typeof envelope.value !== "boolean")
-            throw new Error("InvalidEnvelope");
-        return envelope.value;
+        const fetchImpl = options.fetchImpl ?? fetch;
+        // Desktop Settings writes hq-anywhere-opt-out (hq-pro #5241). true = opted
+        // out. A person who never chose reads false, which means Anywhere is on.
+        const optOut = await readPersonSettingEnvelope(fetchImpl, apiBaseUrl, token, HQ_ANYWHERE_OPT_OUT_KEY);
+        if (optOut)
+            return !optOut.value;
+        const optIn = await readPersonSettingEnvelope(fetchImpl, apiBaseUrl, token, HQ_ANYWHERE_OPT_IN_KEY);
+        if (optIn)
+            return optIn.value;
+        throw new Error("InvalidEnvelope");
     }
     catch (error) {
         const errorName = error instanceof Error && /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(error.name)

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

@@ -136,7 +136,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-----\nMCowBQYDK2VwAyEAAlGqxr0zWOUVIX7OnS1+7YQH2sJJAlulwL/VPSYlnUA=\n-----END PUBLIC KEY-----\n";
+export declare const HQ_FLEET_LOCAL_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=\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;
@@ -147,7 +147,9 @@ export declare const FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS: number;
 export declare function installPinnedFleetLocalDistribution(deps?: FleetLocalInstallDeps): Promise<FleetLocalInstallation>;
 /** The process id the bot's gateway recorded, when its file reads; the caller checks whether it is alive. */
 export declare function fleetLocalGatewayPid(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome">): number | null;
-export declare function fleetLocalProfileNeedsAdoption(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome" | "platform">): boolean;
+export declare function fleetLocalProfileNeedsAdoption(agentUid: string, deps?: Pick<FleetLocalControlDeps, "fleetHome" | "platform"> & {
+    release?: FleetLocalReleasePin;
+}): boolean;
 export declare function controlFleetLocalBot(agentUid: string, action: FleetLocalServiceAction, deps?: FleetLocalControlDeps): Record<string, unknown>;
 export declare function exportFleetLocalMachineCredential(agentUid: string, deps?: FleetLocalControlDeps): BotMachineCreds;
 export declare function fleetLocalPromotionRuntime(agentUid: string, deps?: FleetLocalControlDeps): LocalBotPromotionRuntime;

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

@@ -36,18 +36,18 @@ export function fleetProviderNeedsSignIn(provider) {
 }
 export const HQ_FLEET_LOCAL_RELEASE = {
     repository: "indigoai-us/hq-fleet-local",
-    tag: "v0.4.16",
-    version: "0.4.16",
-    artifact: "hq-fleet-local-0.4.16.zip",
-    artifactSha256: "36ff9ba72c333152dc19af18b298800d9f0aee24e11757d6e4c9f3e378e11c1a",
+    tag: "v0.4.17",
+    version: "0.4.17",
+    artifact: "hq-fleet-local-0.4.17.zip",
+    artifactSha256: "d2c5c49d4ef47da6003f4c2f3be7dcd2d8a287523c8577dfe0239e6e0705e4b4",
     runtimeArtifact: "hq-fleet-runtime-abccac13bd9e.tar",
     runtimeArtifactSha256: "29bcfe718ad7fbd3636afd00623772f2a25bc84c4f6f10d8d57f38e549d528d5",
-    manifestSha256: "baf11852057cc3c4e622576fcf159bea7daf7047f9642046d13f26d6d3f83710",
-    signatureSha256: "14df153280d7da496daac10d5d5fc1b8ad7b3bad500632b0deab6accc2606aba",
+    manifestSha256: "63663ffe8c6bef4f2aefa587d20431156cab4170a0f23533cdab7aab444a7d35",
+    signatureSha256: "bb4af0b453ae03fdbc18e6335ca23e2f0de42bd9e322dba7c4f31d0c8dc08aa7",
     runtimeCommit: "abccac13bd9ea593b24c8cd9c0ba28d5c6050cc9",
 };
 export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAAlGqxr0zWOUVIX7OnS1+7YQH2sJJAlulwL/VPSYlnUA=
+MCowBQYDK2VwAyEASJoapvo0WMTg+Wu3Jvt0nzlXLOBEr+G1aJRi0JkEb4A=
 -----END PUBLIC KEY-----
 `;
 function digest(value) {
@@ -388,6 +388,20 @@ function sharedRuntimeFromMarker(profileDir, root) {
         return null;
     }
 }
+function profileEngineMatchesRelease(profileDir, release) {
+    try {
+        const marker = JSON.parse(fs.readFileSync(path.join(profileDir, "bootstrap.json"), "utf8"));
+        const expected = engineMetadata(release);
+        return marker.engine?.id === expected.id &&
+            marker.engine.distribution === expected.distribution &&
+            marker.engine.version === expected.version &&
+            marker.engine.artifactSha256 === expected.artifactSha256 &&
+            marker.engine.runtimeCommit === expected.runtimeCommit;
+    }
+    catch {
+        return false;
+    }
+}
 function hasEmbeddedRuntime(profileDir, platform) {
     const runtimeDir = path.join(profileDir, "runtime");
     try {
@@ -467,6 +481,8 @@ export function fleetLocalProfileNeedsAdoption(agentUid, deps = {}) {
     const shared = sharedRuntimeFromMarker(profileDir, root);
     if (!shared)
         return true;
+    if (!profileEngineMatchesRelease(profileDir, deps.release ?? HQ_FLEET_LOCAL_RELEASE))
+        return true;
     const platform = deps.platform ?? process.platform;
     if (!["hq-fleet", "hq-fleet-local", "python"].every((name) => fs.existsSync(venvExecutable(shared.runtimeDir, name, platform))))
         return true;

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

@@ -1,8 +1,13 @@
 /**
  * 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
+ * A local bot registers one recurring job in its own `jobs.json` the first
+ * time it starts (`ensureHotSignalSyncJob`), for the bot's company, or, for a
+ * bot with no company (the personal bot first-run setup creates), for the
+ * HQ's active company (`.hq/config.json` `activeCompany`, the same company
+ * `hq sources sync` uses). Only one local bot registers it per company. Right
+ * after the job is created the bot runs the sync once, so a new install does
+ * not wait for the first scheduled time (`registerHotSignalSyncOnStart`). 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
@@ -34,14 +39,26 @@ export declare const HOT_SIGNAL_SYNC_DEFAULT_CRON = "cron(30 6 * * ? *)";
 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 HQ's active company from `{hqRoot}/.hq/config.json` (`activeCompany`),
+ * the same company `hq sources sync` falls back to. Undefined when the file is
+ * missing, unreadable, or the value is not a plain slug. Never throws.
+ */
+export declare function readActiveCompanySlug(hqRoot: string): string | undefined;
 /**
  * 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.
+ * the first company it serves, else (for a bot with no company at all, such as
+ * the personal bot first-run setup creates) `activeCompany`, the HQ's active
+ * company. Null = none, and no job is registered. Checked again each time the
+ * job fires, so a job for a company the bot no longer resolves to is removed.
  */
-export declare function currentHotSignalSyncCompany(config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId">): string | null;
+export declare function currentHotSignalSyncCompany(config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId">, activeCompany?: string | null): string | null;
+/**
+ * The local bot folder, other than `dir`, that already has the hot-signal-sync
+ * job for `company` (or registered it once, even if its owner removed it
+ * since). Null = none. Unreadable folders are skipped.
+ */
+export declare function otherBotWithHotSignalSync(dir: string, company: string, botDirs: readonly string[]): 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
@@ -52,6 +69,8 @@ export interface EnsureHotSignalSyncJobResult {
     /** The job, or null when the owner removed it after it was first registered. */
     job: LocalJob | null;
     created: boolean;
+    /** Set when another local bot already has this company's job; nothing was registered here. */
+    heldBy?: string;
 }
 /**
  * Register the hot-signal-sync job for `company` once. Safe to call on every
@@ -61,7 +80,34 @@ export interface EnsureHotSignalSyncJobResult {
 export declare function ensureHotSignalSyncJob(dir: string, input: {
     company: string;
     timezone: string;
+    otherBotDirs?: readonly string[];
 }, now?: Date): EnsureHotSignalSyncJobResult;
+export interface RegisterOnStartInput {
+    dir: string;
+    config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId">;
+    /** The HQ's active company, used only when the bot has no company. */
+    activeCompany?: string | null;
+    /** Every local bot folder (this one may be included); used for the one-bot-per-company check. */
+    otherBotDirs?: readonly string[];
+    timezone: string;
+    /** The first sync, run once right after the job is created. Errors are logged, never thrown. */
+    runFirst: (company: string) => Promise<HotSignalSyncRunOutcome>;
+    log?: (level: "info" | "warn", message: string) => void;
+    now?: Date;
+}
+export interface RegisterOnStartResult {
+    company: string | null;
+    ensured: EnsureHotSignalSyncJobResult | null;
+    /** The first run, when the job was created on this start; resolves (never rejects) when it ends. */
+    firstRun: Promise<void> | null;
+}
+/**
+ * What a bot does at start for the built-in job: remove jobs for a company it
+ * no longer syncs, register the job for its current company once, and, when
+ * the job was created just now, start one sync in the background. Never
+ * throws and never waits for the sync, so bot start cannot fail or stall here.
+ */
+export declare function registerHotSignalSyncOnStart(input: RegisterOnStartInput): RegisterOnStartResult;
 /**
  * The signals pass over one adapter's landed sources: how many signals it
  * generated. The bot wires the local `claude -p` pass
@@ -75,6 +121,8 @@ export type HotSignalSyncFn = (input: {
     company: string;
     trigger: RunTrigger;
     catchUp: boolean;
+    /** The one run started right after the job was registered; marked in the ledger. */
+    firstRun?: boolean;
     signalsGenerated: LocalSignalsPass;
     now: () => Date;
     /** The owner DM for the signals-failure alert (US-012); unset = no alert check. */
@@ -87,6 +135,8 @@ export interface HotSignalSyncRunInput {
     company: string;
     /** The run fired late, after a missed window (job-run.ts `isCatchUpRun`). */
     catchUp: boolean;
+    /** The one run started right after the job was registered (`registerHotSignalSyncOnStart`). */
+    firstRun?: boolean;
     now: () => Date;
     sync: HotSignalSyncFn;
     signalsPass?: LocalSignalsPass;