@indigoai-us/hq-cli 5.345.183 → 5.345.188

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [5.345.188] — 2026-10-30
+- `hq agent inbox` and the `hq_inbox_read` MCP tool now bound the server read (token mint plus GET) at 30 s
+  (`HQ_AGENT_INBOX_TIMEOUT_MS`, floor 1000) and retry it once after a short delay, honouring the server's
+  numeric `Retry-After` up to 5 s, when the token mint is held by another process, the request times out or
+  fails in transport, or the server answers 408, 425, 429, 500, 502 or 503. A 504 is left to the existing
+  single retry inside the API client, and a 401, 403, 404 or an invalid 200 body is not retried. The
+  deadline now reaches the hq-cloud mint, so a retry no longer queues behind a first mint that is still
+  waiting on another process's lock. The list command sets `HQ_MACHINE_CREDS_FILE`,
+  `HQ_REQUIRE_MACHINE_IDENTITY` and `HQ_VAULT_API_URL` before minting, as `hq agent inbox done` already did.
+  The JSON output gains `stale: true|false` next to `source`; whenever a retry happened, including one that
+  succeeded, it also carries `attempts: 2`, and a note that still reports a fallback ends with
+  "(after 2 attempts)", so automation can tell a hard failure from a single blip (DEV-4065).
+- Keep downloaded revisions current and retry locally deleted files until the cloud confirms their removal.
+
+## [5.345.187] — 2026-10-30
+- The HQ Anywhere person gate now follows the desktop Settings key `hq-anywhere-opt-out`. Turning HQ Anywhere on in the app enables `hq mcp serve` without a separate `hq-anywhere` write. Older servers that only have `hq-anywhere` still work.
+
+- `hq version` and the desktop HQ Core row now send your GitHub token when they ask GitHub for the latest HQ Core release. Without it, GitHub's anonymous cap made the check fail and the app showed Not checked. A stale or revoked token falls back to the anonymous public lookup once.
+- Repairing an existing local bot now installs the CLI's pinned HQ Fleet Runtime release before restarting it.
+- Local bots now keep each HQ DM thread in its own conversation, so a reply cannot use context from another thread.
+- Updating an existing local bot now imports its refreshed machine credential exactly once.
+- Updating an existing local bot now records the HQ Fleet Runtime release it actually installed.
+- The hot-channel sync now honours the channels, issues and records you picked for each connection. Slack lands only threads in picked channels, Linear only picked issues (by id or identifier such as ENG-123) and Attio only picked records. An empty pick on a Slack, Linear or Attio connection counts as no choice yet and syncs everything; saving an empty pick on every meeting recorder leaves meetings out. A connection with no saved pick syncs everything. When a saved pick may exist but cannot be read (an error, no answer within 5 seconds, or a malformed file), that connection is skipped for the run and its run-ledger line is marked failed with reason `selection-unreadable`; the other connections still sync. Gmail does not use picks yet.
+- A bot with no company of its own, such as the personal bot first-run setup creates, now registers the daily hot-channel sync for your active company (`activeCompany` in the HQ config, the company `hq sources sync` uses). Only one local bot registers it per company, and a job you removed is not added back. When the job is first created the bot runs one sync right away in the background, marked `firstRun` in the run ledger, so a new install does not wait for the first scheduled time.
+- New `hq sources schedule` shows when the bot's daily hot-channel sync runs, on which bot, and the latest run of each adapter over the last 7 days. `--at HH:MM` moves it to that time each day in the job's own time zone; `--json` prints `{ company, job, lastRuns }`.
+- Adding a job to a local bot no longer replaces an unreadable `jobs.json` with a list holding only the new job; it stops with an error and leaves the file as it is.
+
 ## [5.345.183] — 2026-10-30
 - New local Grok bots now reuse an existing encrypted Grok login on the same computer instead of asking you to sign in again.
 

package/dist/command-catalog.generated.d.ts

@@ -5239,6 +5239,35 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly defaultValue: "<runtime-path>";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "schedule";
+        readonly description: "Show when the bot's daily hot-channel sync runs, or set it with --at HH:MM";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Company slug (defaults to .hq/config.json activeCompany)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--at <HH:MM>";
+            readonly description: "Run the sync daily at this 24-hour time, in the job's time zone";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print the schedule and last runs as JSON";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--hq-root <path>";
+            readonly description: "Local HQ tree root (default: <runtime-path>)";
+            readonly hidden: false;
+            readonly defaultValue: "<runtime-path>";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "sync";
         readonly description: "Run every hot channel now: each adapter once per connection you can use";

package/dist/command-catalog.generated.js

@@ -6353,6 +6353,41 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "schedule",
+                "description": "Show when the bot's daily hot-channel sync runs, or set it with --at HH:MM",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company slug (defaults to .hq/config.json activeCompany)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--at <HH:MM>",
+                        "description": "Run the sync daily at this 24-hour time, in the job's time zone",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print the schedule and last runs as JSON",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--hq-root <path>",
+                        "description": "Local HQ tree root (default: <runtime-path>)",
+                        "hidden": false,
+                        "defaultValue": "<runtime-path>"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "sync",
                 "description": "Run every hot channel now: each adapter once per connection you can use",

package/dist/commands/agent-inbox.js

@@ -8,6 +8,7 @@ import chalk from "chalk";
 import * as os from "node:os";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { annotateInboxAttempts, fetchServerInboxWithRetry, parseRetryAfterSeconds, resolveAgentInboxTimeoutMs } from "../lib/agent-kit/inbox-fetch.js";
 import { redactAgentInboxItem } from "../lib/agent-kit/inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
@@ -23,25 +24,56 @@ export function registerAgentInboxCommand(agent) {
         const paths = agentKitPaths(os.homedir(), process.env);
         const creds = requireExternalCreds(paths);
         const done = readDoneIds(paths);
+        // Pin the enrolled machine identity and API, as `done` does below, so the
+        // mint cannot fall through to a person session or another API base.
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
         // Merged with the server, never the local mirror alone: a dead kit
         // poller would otherwise make this command answer confidently with
-        // yesterday's mail and no sign anything was wrong.
-        const { entries, note, source } = await mergeAgentInbox(paths, async () => {
-            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
-            const res = await vaultApiFetch({
-                token,
-                baseUrl: creds.apiBaseUrl,
-                path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
+        // yesterday's mail and no sign anything was wrong. The server read is
+        // bounded and retried once (inbox-fetch.ts) so a shared-lock mint, a
+        // 503 with Retry-After or a hung socket does not become a fallback.
+        let attempts = 1;
+        const merged = await mergeAgentInbox(paths, async () => {
+            const outcome = await fetchServerInboxWithRetry({
+                timeoutMs: resolveAgentInboxTimeoutMs(process.env),
+                mint: (signal) => ensureCognitoToken({ tokenSource: "machine", interactive: false, signal }),
+                fetch: async (token, signal) => {
+                    const res = await vaultApiFetch({
+                        token,
+                        baseUrl: creds.apiBaseUrl,
+                        path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
+                        signal,
+                    });
+                    const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.("retry-after"));
+                    // Preserve a decode failure as an invalid body for mergeAgentInbox to
+                    // classify. Parser errors can contain response bytes: do not echo them.
+                    return {
+                        status: res.status,
+                        body: await res.json().catch(() => undefined),
+                        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+                    };
+                },
             });
-            // Preserve a decode failure as an invalid body for mergeAgentInbox to
-            // classify. Parser errors can contain response bytes: do not echo them.
-            return { status: res.status, body: await res.json().catch(() => undefined) };
+            attempts = outcome.attempts;
+            if (!outcome.ok)
+                throw outcome.error;
+            return outcome.response;
         });
+        const { entries, note, source, stale, attempts: attemptsMade } = annotateInboxAttempts(merged, attempts);
         const rows = entries
             .filter((e) => opts.all || !done.has(e.id))
             .map((e) => summarizeInboxEntry(redactAgentInboxItem(e), done.has(e.id)));
         if (opts.json) {
-            console.log(JSON.stringify({ count: rows.length, source, messages: rows, ...(note ? { note } : {}) }, null, 2));
+            console.log(JSON.stringify({
+                count: rows.length,
+                source,
+                stale,
+                ...(attemptsMade !== undefined ? { attempts: attemptsMade } : {}),
+                messages: rows,
+                ...(note ? { note } : {}),
+            }, null, 2));
             return;
         }
         if (note)

package/dist/commands/agent-mcp.js

@@ -13,6 +13,7 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { parseRetryAfterSeconds } from "../lib/agent-kit/inbox-fetch.js";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
@@ -59,7 +60,7 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
         HQ_VAULT_API_URL: creds.apiBaseUrl,
         NO_COLOR: "1",
     };
-    const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    const getToken = (signal) => ensureCognitoToken({ tokenSource: "machine", interactive: false, signal });
     let companyUid;
     return {
         creds,
@@ -89,9 +90,11 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
                 method: init?.method,
                 body: init?.body,
                 query: init?.query,
+                signal: init?.signal,
             });
             const body = await res.json().catch(() => ({}));
-            return { status: res.status, body };
+            const retryAfterSeconds = parseRetryAfterSeconds(res.headers.get("retry-after"));
+            return { status: res.status, body, ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}) };
         },
     };
 }

package/dist/commands/bot.d.ts

@@ -409,10 +409,10 @@ export interface RemoteBotRow {
 export declare function registerBotCommand(program: Command): void;
 /**
  * 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.
+ * the first company it serves, else (for a bot with no company) the HQ's
+ * active company. Null = none, and no job is registered.
  */
-export declare function hotSignalSyncCompany(config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId">): string | null;
+export declare function hotSignalSyncCompany(config: Pick<BotConfig, "companySlug" | "kind" | "companies" | "workerId"> & {
+    hqRoot?: string;
+}): string | null;
 //# sourceMappingURL=bot.d.ts.map

package/dist/commands/bot.js

@@ -1,5 +1,5 @@
 import { withLocalJobs } from "../lib/bot/local-jobs.js";
-import { currentHotSignalSyncCompany, ensureHotSignalSyncJob, removeStaleHotSignalSyncJobs, runHotSignalSyncJob } from "../lib/bot/jobs/hot-signal-sync.js";
+import { currentHotSignalSyncCompany, readActiveCompanySlug, registerHotSignalSyncOnStart, runHotSignalSyncJob } from "../lib/bot/jobs/hot-signal-sync.js";
 import { createClaudeSignalsPass } from "../lib/hot-channels/signals-pass.js";
 import { machineTimeZone } from "../lib/bot/job-run.js";
 import { runCompanyHotChannelSync } from "./sources.js";
@@ -478,6 +478,7 @@ async function adoptFleetRuntimeProfile(name, dir, config) {
         provider: fleetProviderForRuntime(config.runtime, config.model),
         ownerCompanies: companyScope,
     }, { python, start: false });
+    patchBotConfig(dir, { engine: installation.engine });
     const credentials = botCredsPath(dir);
     if (fs.existsSync(credentials))
         importFleetLocalMachineCredential(config.agentUid, credentials);
@@ -1310,24 +1311,31 @@ async function runBotResident(nameArg) {
     // The built-in hot-signal-sync job, registered once in the bot's own
     // jobs.json (06:30 daily in this computer's time zone until the owner
     // reschedules it with `hq bot jobs`). It runs in-process, with no model turn.
-    const syncCompany = hotSignalSyncCompany(config);
+    // A bot with no company (the personal bot first-run setup creates) syncs the
+    // HQ's active company. Only one local bot registers the job per company, and
+    // the first sync starts in the background right after the job is created.
+    const runHotSignalSync = (input) => runHotSignalSyncJob({
+        ...input,
+        sync: (syncInput) => runCompanyHotChannelSync({ hqRoot: config.hqRoot, ...syncInput }),
+        // A new pass per run: the login preflight and the 20-document cap are per run.
+        signalsPass: createClaudeSignalsPass({ hqRoot: config.hqRoot, company: input.company }),
+    });
+    let otherBotDirs = [];
     try {
-        // A job for a company the bot no longer serves is removed before anything runs.
-        for (const stale of removeStaleHotSignalSyncJobs(dir, syncCompany)) {
-            console.log(`Removed the hot-channel sync job ${stale.jobId}: this bot no longer syncs that company.`);
-        }
-    }
-    catch (err) {
-        console.error(`Could not check the hot-channel sync jobs: ${err instanceof Error ? err.message : String(err)}`);
+        otherBotDirs = listBotNames(botsRoot()).map((n) => botDir(n));
     }
-    if (syncCompany) {
-        try {
-            ensureHotSignalSyncJob(dir, { company: syncCompany, timezone: machineTimeZone() });
-        }
-        catch (err) {
-            console.error(`Could not register the hot-channel sync job for ${syncCompany}: ${err instanceof Error ? err.message : String(err)}`);
-        }
+    catch {
+        // No other bots could be listed; this bot is the only one checked.
     }
+    registerHotSignalSyncOnStart({
+        dir,
+        config,
+        activeCompany: readActiveCompanySlug(config.hqRoot) ?? null,
+        otherBotDirs,
+        timezone: machineTimeZone(),
+        runFirst: (company) => runHotSignalSync({ company, catchUp: false, firstRun: true, now: () => new Date() }),
+        log: (level, message) => (level === "warn" ? console.error(message) : console.log(message)),
+    });
     const owner = new OwnerContextCache(() => lookupOwnerContext(config.ownerUid), Date.now, undefined, config.ownerUid);
     const handle = await runBot({
         dir,
@@ -1335,15 +1343,7 @@ async function runBotResident(nameArg) {
         api,
         runtime: runtimeFor(config.runtime),
         ownerContext: () => owner.get(),
-        hotSignalSync: ({ company, catchUp, now, sendAlert }) => runHotSignalSyncJob({
-            company,
-            catchUp,
-            now,
-            sendAlert,
-            sync: (input) => runCompanyHotChannelSync({ hqRoot: config.hqRoot, ...input }),
-            // A new pass per run: the login preflight and the 20-document cap are per run.
-            signalsPass: createClaudeSignalsPass({ hqRoot: config.hqRoot, company }),
-        }),
+        hotSignalSync: ({ company, catchUp, now, sendAlert }) => runHotSignalSync({ company, catchUp, now, sendAlert }),
         // US-005: decision picks in the owner DM, with the bot's own machine token
         // (never the owner's login).
         decisions: new DecisionsClient(token),
@@ -2556,7 +2556,8 @@ async function repairLocalBot(name, api, bot, daemon) {
     createBotLogger(dir)("info", `re-issued machine credentials for ${name} (${bot.agentUid}) on ${localMachineId()}`);
     if (isFleetRuntimeBot(config)) {
         const adopted = await adoptFleetRuntimeProfile(name, dir, config);
-        importFleetLocalMachineCredential(bot.agentUid, botCredsPath(dir));
+        if (!adopted)
+            importFleetLocalMachineCredential(bot.agentUid, botCredsPath(dir));
         const restarted = controlFleetLocalBot(bot.agentUid, adopted ? "install" : "restart").ok === true;
         return restarted ? "new credentials, HQ Fleet Runtime restarted" : "new credentials; the HQ Fleet Runtime did not restart (hq bot start " + name + ")";
     }
@@ -2937,12 +2938,10 @@ export function registerBotCommand(program) {
 }
 /**
  * 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.
+ * the first company it serves, else (for a bot with no company) the HQ's
+ * active company. Null = none, and no job is registered.
  */
 export function hotSignalSyncCompany(config) {
-    return currentHotSignalSyncCompany(config);
+    return currentHotSignalSyncCompany(config, config.hqRoot ? (readActiveCompanySlug(config.hqRoot) ?? null) : null);
 }
 //# sourceMappingURL=bot.js.map

package/dist/commands/sources.d.ts

@@ -13,6 +13,7 @@
  *   hq sources entities  List entities the caller has access to.
  *   hq sources runs      Show the local hot-channel run ledger for one day.
  *   hq sources sync      Run every hot channel now for the signed-in person.
+ *   hq sources schedule  Show or set when the bot's daily hot-channel sync runs.
  *
  * Defaults:
  *   --entity   falls back to .hq/config.json activeCompany (per sync.ts).
@@ -22,6 +23,8 @@
 import { Command } from "commander";
 import { type RunLedgerAdapterSummary, type RunLedgerEntry, type RunTrigger, type SignalsGeneratedFn } from "../lib/hot-channels/ledger.js";
 import type { HotChannelRegistry } from "../lib/hot-channels/registry.js";
+import { type SelectionLoader } from "../lib/hot-channels/selection.js";
+import { type ScheduleReport } from "../lib/hot-channels/schedule.js";
 import { type OnDemandSyncDeps, type OnDemandSyncReport } from "../lib/hot-channels/run.js";
 type ListFormat = "table" | "json";
 export interface RunsOptions {
@@ -58,6 +61,8 @@ export interface SyncOverrides {
     now?: () => Date;
     /** The signals pass; defaults to the local `claude -p` pass under the user's own login. */
     signalsGenerated?: SignalsGeneratedFn;
+    /** This run's saved-selection loader; defaults to the person's vault bucket. */
+    createSelections?: () => SelectionLoader | null;
 }
 /**
  * Network access for one sync: the catalog, the person's usable connections,
@@ -74,6 +79,8 @@ export interface CompanyHotChannelSyncInput {
     /** `scheduled` for the bot's hot-signal-sync job; `on-demand` by default. */
     trigger?: RunTrigger;
     catchUp?: boolean;
+    /** The first run after the bot registered its hot-signal-sync job; marked in the ledger. */
+    firstRun?: boolean;
     signalsGenerated?: SignalsGeneratedFn;
     /** The signed-in person's `prs_` person uid in this company; defaults to a roster lookup by email. */
     resolvePersonUid?: (token: string, companyUid: string, email: string) => Promise<string | null>;
@@ -83,6 +90,12 @@ export interface CompanyHotChannelSyncInput {
      * `settings/signals/preferences.yaml`, through the HQ integrations gateway.
      */
     signalsAlert?: SignalsAlertSenders;
+    /**
+     * Builds this run's saved-selection loader (one per run). Defaults to
+     * reading `integrations/hot-channels/<connectionId>.json` from the
+     * person's own vault bucket. Return null to sync without selections.
+     */
+    createSelections?: () => SelectionLoader | null;
 }
 export interface SignalsAlertSenders {
     /** The primary alert to the owner; throws when it was not delivered. */
@@ -106,6 +119,30 @@ export declare function runCompanyHotChannelSync(input: CompanyHotChannelSyncInp
  * line under `companies/{company}/sources/`, and nothing else.
  */
 export declare function runSync(options: SyncOptions, overrides?: SyncOverrides): Promise<OnDemandSyncReport>;
+export interface ScheduleOptions {
+    company?: string;
+    at?: string;
+    json?: boolean;
+    hqRoot: string;
+}
+export interface ScheduleOverrides {
+    now?: Date;
+    /** Where local bots live; defaults to `~/.hq/bots` (or HQ_BOTS_ROOT). */
+    botsRoot?: string;
+    /** Whose ledger to read; defaults to the signed-in person. */
+    email?: string;
+}
+export declare class NoHotSignalSyncJobError extends Error {
+    readonly company: string;
+    constructor(company: string);
+}
+/**
+ * Show the company's hot-signal-sync job (bot, schedule, next and last run)
+ * and each adapter's most recent ledger entry over the last 7 UTC days. With
+ * `--at HH:MM`, reschedule the job to daily at that time in its own time zone
+ * first. Exits non-zero when `--at` is given and no job exists.
+ */
+export declare function runSchedule(options: ScheduleOptions, overrides?: ScheduleOverrides): Promise<ScheduleReport>;
 export declare function registerSourcesCommand(program: Command): void;
 export {};
 //# sourceMappingURL=sources.d.ts.map

package/dist/commands/sources.js

@@ -13,6 +13,7 @@
  *   hq sources entities  List entities the caller has access to.
  *   hq sources runs      Show the local hot-channel run ledger for one day.
  *   hq sources sync      Run every hot channel now for the signed-in person.
+ *   hq sources schedule  Show or set when the bot's daily hot-channel sync runs.
  *
  * Defaults:
  *   --entity   falls back to .hq/config.json activeCompany (per sync.ts).
@@ -24,7 +25,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import chalk from "chalk";
 import { SOURCE_CHANNELS, assertSourceChannel, resolveEntity, listAvailableEntities, listSources, getSource, VaultClient, } from "@indigoai-us/hq-cloud";
-import { ensureCognitoToken, ensureCognitoIdToken, buildVaultConfig, DEFAULT_HQ_ROOT, } from "../utils/cognito-session.js";
+import { ensureCognitoToken, ensureCognitoIdToken, buildVaultConfig, DEFAULT_COGNITO, DEFAULT_HQ_ROOT, } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { isAuthError } from "../utils/auth-error.js";
 import { IntegrationsCliError, callGateway, fetchUsableApps, gatewayResultIsError, isBuiltInGatewayProvider, raiseForResponse, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
@@ -37,6 +38,12 @@ import { createClaudeSignalsPass } from "../lib/hot-channels/signals-pass.js";
 import { assertSafeSegment } from "../lib/hot-channels/landing.js";
 import { acquireSyncLock, SYNC_LOCK_BUSY_REASON } from "../lib/hot-channels/sync-lock.js";
 import { createBuiltinHotChannelRegistry } from "../lib/hot-channels/adapters/index.js";
+import { createSelectionLoader } from "../lib/hot-channels/selection.js";
+import { createPersonVaultReader } from "../lib/hot-channels/person-vault-reader.js";
+import { S3Client } from "@aws-sdk/client-s3";
+import { resolveCanonicalPersonUid } from "./cloud.js";
+import { botsRoot as defaultBotsRoot } from "../lib/bot/paths.js";
+import { findHotSignalSyncJobs, lastRunsPerAdapter, parseDailyAt, renderScheduleReport, rescheduleDaily, toJobView, } from "../lib/hot-channels/schedule.js";
 import { listActiveMembers } from "./members.js";
 import { runOnDemandSync, } from "../lib/hot-channels/run.js";
 // ---------------------------------------------------------------------------
@@ -376,6 +383,36 @@ async function signedInSession(company) {
         throw err;
     }
 }
+/**
+ * The default selection loader: reads each connection's saved pick from the
+ * signed-in person's vault bucket through the same STS vend-self path as
+ * `hq files cat --personal`. Read failures log to stderr and fall back to
+ * landing everything; they never fail the run.
+ */
+function defaultSelections() {
+    let client;
+    const vault = () => {
+        client ??= (async () => new VaultClient(buildVaultConfig(process.env.HQ_ACCESS_TOKEN || (await ensureCognitoToken({ interactive: false })))))();
+        return client;
+    };
+    const reader = createPersonVaultReader({
+        resolvePersonUid: async () => {
+            const c = await vault();
+            return resolveCanonicalPersonUid({
+                listMyMemberships: () => c.listMyMemberships(),
+                listPersonEntities: () => c.entity.listByType("person"),
+                getEntity: async () => null,
+            });
+        },
+        getEntity: async (uid) => (await vault()).entity.get(uid),
+        vendSelf: async (personUid) => (await vault()).sts.vendSelf({ personUid }),
+        s3Factory: ({ region, credentials }) => new S3Client({ region, credentials }),
+        region: DEFAULT_COGNITO.region,
+    });
+    return createSelectionLoader(reader, {
+        log: (message) => void process.stderr.write(chalk.yellow(`${message}\n`)),
+    });
+}
 /** The signed-in member's `prs_` uid from the company roster, or null when the roster is unavailable. */
 async function rosterPersonUid(token, companyUid, email) {
     try {
@@ -440,6 +477,7 @@ async function skippedReport(input, vaultRoot, personKey, personUid, now) {
         reason: SYNC_LOCK_BUSY_REASON,
         personUid,
         catchUp: input.catchUp ?? false,
+        ...(input.firstRun ? { firstRun: true } : {}),
     };
     await appendRunLedgerEntry(vaultRoot, personKey, line);
     return {
@@ -454,7 +492,10 @@ async function skippedReport(input, vaultRoot, personKey, personUid, now) {
 }
 async function runLockedCompanySync(input, vaultRoot, personKey, author, session, lockHeld) {
     const deps = gatewaySyncDeps(session.token, session.companyUid);
+    // A fresh loader per run: selections are cached for this run only.
+    const selections = input.createSelections ? input.createSelections() : defaultSelections();
     const report = await runOnDemandSync({
+        ...(selections ? { selections } : {}),
         deps,
         registry: input.registry ??
             createBuiltinHotChannelRegistry({ vaultRoot, identities: await meetingIdentities(input, session, author.email) }),
@@ -465,6 +506,7 @@ async function runLockedCompanySync(input, vaultRoot, personKey, author, session
         ...(input.now ? { now: input.now } : {}),
         ...(input.trigger ? { trigger: input.trigger } : {}),
         ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
+        ...(input.firstRun ? { firstRun: true } : {}),
         ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
         beforeWrite: lockHeld,
     });
@@ -500,6 +542,7 @@ export async function runSync(options, overrides = {}) {
         ...(options.adapter !== undefined ? { adapter: options.adapter } : {}),
         ...(overrides.registry ? { registry: overrides.registry } : {}),
         ...(overrides.now ? { now: overrides.now } : {}),
+        ...(overrides.createSelections ? { createSelections: overrides.createSelections } : {}),
         signalsGenerated: overrides.signalsGenerated ?? createClaudeSignalsPass({ hqRoot: options.hqRoot, company }),
         // The CLI has no owner-DM sender: the terminal is the primary alert here.
         signalsAlert: {
@@ -549,6 +592,56 @@ function renderSyncTable(company, report) {
     }
     return lines.join("\n");
 }
+export class NoHotSignalSyncJobError extends Error {
+    company;
+    constructor(company) {
+        super(`No hot-channel sync job for ${company} on any local bot, so there is nothing to reschedule. ` +
+            "Start a bot bound to this company (it adds the job on first start), then run this again.");
+        this.company = company;
+        this.name = "NoHotSignalSyncJobError";
+    }
+}
+/**
+ * Show the company's hot-signal-sync job (bot, schedule, next and last run)
+ * and each adapter's most recent ledger entry over the last 7 UTC days. With
+ * `--at HH:MM`, reschedule the job to daily at that time in its own time zone
+ * first. Exits non-zero when `--at` is given and no job exists.
+ */
+export async function runSchedule(options, overrides = {}) {
+    const now = overrides.now ?? new Date();
+    const company = options.company ?? readActiveCompanySlug(options.hqRoot);
+    if (!company) {
+        throw new Error("No company specified. Pass --company <slug> or set activeCompany in .hq/config.json.");
+    }
+    assertSafeSegment(company, "company");
+    // Validate before touching any job file.
+    if (options.at !== undefined)
+        parseDailyAt(options.at);
+    let found = findHotSignalSyncJobs(overrides.botsRoot ?? defaultBotsRoot(), company);
+    if (options.at !== undefined) {
+        if (found.length === 0)
+            throw new NoHotSignalSyncJobError(company);
+        found = rescheduleDaily(found, options.at, now);
+    }
+    const email = overrides.email ?? resolveUploadAuthor()?.email;
+    const lastRuns = email
+        ? await lastRunsPerAdapter(path.join(options.hqRoot, "companies", company), audienceKey([email]), now)
+        : [];
+    const report = {
+        company,
+        job: found[0] ? toJobView(found[0], now) : null,
+        lastRuns,
+    };
+    if (options.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(renderScheduleReport(report, found.slice(1).map((f) => f.botName)) + "\n");
+        if (!email)
+            process.stdout.write("Sign in (hq login) to see recent runs.\n");
+    }
+    return report;
+}
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -612,6 +705,16 @@ export function registerSourcesCommand(program) {
         .action(withErrorHandling(async (options) => {
         await runRuns(options);
     }));
+    sources
+        .command("schedule")
+        .description("Show when the bot's daily hot-channel sync runs, or set it with --at HH:MM")
+        .option("--company <slug>", "Company slug (defaults to .hq/config.json activeCompany)")
+        .option("--at <HH:MM>", "Run the sync daily at this 24-hour time, in the job's time zone")
+        .option("--json", "Print the schedule and last runs as JSON")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(withErrorHandling(async (options) => {
+        await runSchedule(options);
+    }));
     sources
         .command("sync")
         .description("Run every hot channel now: each adapter once per connection you can use")