@indigoai-us/hq-cli 5.345.182 → 5.345.187

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;

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

@@ -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
@@ -21,7 +26,7 @@
 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 { effectiveBotCompanies, effectiveBotKind } from "../config.js";
 import { ensureLocalJob, readLocalJobs, removeLocalJobsWhere, withJobsLock } from "../local-jobs.js";
 export const HOT_SIGNAL_SYNC_JOB_KIND = "hot-signal-sync";
 /**
@@ -69,15 +74,55 @@ export function hotSignalSyncJobCompany(context) {
         return null;
     return typeof company === "string" && company.trim() ? company.trim() : null;
 }
+const ACTIVE_COMPANY_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+/**
+ * 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 function readActiveCompanySlug(hqRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(hqRoot, ".hq", "config.json"), "utf-8"));
+        const slug = cfg?.activeCompany;
+        return typeof slug === "string" && slug.length > 0 ? slug : undefined;
+    }
+    catch {
+        return 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 function currentHotSignalSyncCompany(config) {
-    return config.companySlug ?? effectiveBotCompanies(config)[0] ?? null;
+export function currentHotSignalSyncCompany(config, activeCompany) {
+    const own = config.companySlug ?? effectiveBotCompanies(config)[0];
+    if (own)
+        return own;
+    // A company bot syncs only the companies it was given.
+    if (effectiveBotKind(config) === "company")
+        return null;
+    const active = activeCompany?.trim();
+    return active && ACTIVE_COMPANY_RE.test(active) ? active : 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 function otherBotWithHotSignalSync(dir, company, botDirs) {
+    const self = path.resolve(dir);
+    for (const other of botDirs) {
+        if (path.resolve(other) === self)
+            continue;
+        if (readMarker(other).registered[markerKey(company)])
+            return other;
+        if (readLocalJobs(other).some((job) => hotSignalSyncJobCompany(job.context) === company))
+            return other;
+    }
+    return null;
 }
 /**
  * Remove every hot-signal-sync job whose company is not `current` (all of them
@@ -115,6 +160,10 @@ export function ensureHotSignalSyncJob(dir, input, now = new Date()) {
     if (readMarker(dir).registered[key]) {
         return { job: readLocalJobs(dir).find(matches) ?? null, created: false };
     }
+    // One bot per company: a second local bot never adds its own copy.
+    const heldBy = otherBotWithHotSignalSync(dir, input.company, input.otherBotDirs ?? []);
+    if (heldBy)
+        return { job: null, created: false, heldBy };
     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,
@@ -130,6 +179,53 @@ export function ensureHotSignalSyncJob(dir, input, now = new Date()) {
     });
     return { job, created };
 }
+/**
+ * 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 function registerHotSignalSyncOnStart(input) {
+    const log = input.log ?? (() => undefined);
+    const company = currentHotSignalSyncCompany(input.config, input.activeCompany);
+    try {
+        for (const stale of removeStaleHotSignalSyncJobs(input.dir, company)) {
+            log("info", `Removed the hot-channel sync job ${stale.jobId}: this bot no longer syncs that company.`);
+        }
+    }
+    catch (err) {
+        log("warn", `Could not check the hot-channel sync jobs: ${errorMessage(err)}`);
+    }
+    if (!company)
+        return { company: null, ensured: null, firstRun: null };
+    let ensured;
+    try {
+        ensured = ensureHotSignalSyncJob(input.dir, { company, timezone: input.timezone, otherBotDirs: input.otherBotDirs ?? [] }, input.now ?? new Date());
+    }
+    catch (err) {
+        log("warn", `Could not register the hot-channel sync job for ${company}: ${errorMessage(err)}`);
+        return { company, ensured: null, firstRun: null };
+    }
+    if (ensured.heldBy) {
+        log("info", `Not adding a hot-channel sync job for ${company}: the bot in ${ensured.heldBy} already runs it.`);
+    }
+    if (!ensured.created)
+        return { company, ensured, firstRun: null };
+    log("info", `Registered the daily hot-channel sync for ${company}; running the first sync now.`);
+    const firstRun = (async () => {
+        try {
+            const outcome = await input.runFirst(company);
+            log(outcome.ok ? "info" : "warn", outcome.text);
+        }
+        catch (err) {
+            log("warn", `The first hot-channel sync for ${company} failed: ${errorMessage(err)}`);
+        }
+    })();
+    return { company, ensured, firstRun };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 export const noLocalSignalsPass = async () => 0;
 /** Run the scheduled sync once and describe it in plain words. Never throws. */
 export async function runHotSignalSyncJob(input) {
@@ -140,6 +236,7 @@ export async function runHotSignalSyncJob(input) {
             company: input.company,
             trigger: "scheduled",
             catchUp: input.catchUp,
+            ...(input.firstRun ? { firstRun: true } : {}),
             signalsGenerated: signalsPass,
             now: input.now,
             ...(input.sendAlert

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

@@ -95,9 +95,11 @@ export declare function ensureLocalJob(dir: string, matches: (job: LocalJob) =>
  * 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: {
+export declare function rescheduleLocalJob(dir: string, jobId: string, 
+/** `timezone` omitted keeps the job's own, read under the same lock. */
+schedule: {
     cron: string;
-    timezone: 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[];

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

@@ -42,6 +42,33 @@ export function readLocalJobs(dir) {
         return [];
     }
 }
+/**
+ * `jobs.json` for a write that adds a job: a missing file is an empty list,
+ * but a file that exists and cannot be read or parsed throws, so adding a job
+ * never writes back a list that drops every other job.
+ */
+function readLocalJobsForAdd(dir) {
+    let text;
+    try {
+        text = fs.readFileSync(localJobsPath(dir), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw new Error(`The bot's job list (${localJobsPath(dir)}) could not be read, so it was not changed: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`The bot's job list (${localJobsPath(dir)}) is not valid JSON, so it was not changed: ${err.message}`);
+    }
+    if (!parsed || !Array.isArray(parsed.jobs)) {
+        throw new Error(`The bot's job list (${localJobsPath(dir)}) has no jobs array, so it was not changed.`);
+    }
+    return parsed.jobs.filter((job) => !!job && typeof job.jobId === "string");
+}
 function writeLocalJobs(dir, jobs) {
     const file = localJobsPath(dir);
     const tmp = `${file}.${process.pid}.tmp`;
@@ -311,7 +338,7 @@ export function addLocalJob(dir, input, now = new Date()) {
         ...(input.context ? { context: input.context } : {}),
         createdAt: now.toISOString(),
     };
-    withJobsLock(dir, () => writeLocalJobs(dir, [...readLocalJobs(dir), job]));
+    withJobsLock(dir, () => writeLocalJobs(dir, [...readLocalJobsForAdd(dir), job]));
     return job;
 }
 /**
@@ -322,7 +349,7 @@ export function ensureLocalJob(dir, matches, input, now = new Date()) {
     if (!isRunnableSchedule(input.cron))
         throw new Error(`"${input.cron}" is not a schedule this bot can run.`);
     return withJobsLock(dir, () => {
-        const jobs = readLocalJobs(dir);
+        const jobs = readLocalJobsForAdd(dir);
         const existing = jobs.find(matches);
         if (existing)
             return { job: existing, created: false };
@@ -342,7 +369,9 @@ export function ensureLocalJob(dir, matches, input, now = new Date()) {
  * 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 function rescheduleLocalJob(dir, jobId, schedule, now = new Date()) {
+export function rescheduleLocalJob(dir, jobId, 
+/** `timezone` omitted keeps the job's own, read under the same lock. */
+schedule, now = new Date()) {
     if (!isRunnableSchedule(schedule.cron))
         throw new Error(`"${schedule.cron}" is not a schedule this bot can run.`);
     return withJobsLock(dir, () => {
@@ -353,7 +382,7 @@ export function rescheduleLocalJob(dir, jobId, schedule, now = new Date()) {
         const updated = {
             ...jobs[index],
             cron: schedule.cron,
-            timezone: schedule.timezone,
+            timezone: schedule.timezone ?? jobs[index].timezone,
             scheduledFrom: now.toISOString(),
         };
         jobs[index] = updated;

package/dist/lib/bot/run.js

@@ -83,7 +83,7 @@ import { isAgentSender, isDmItem, isMetaNonReply, resolveReplyTarget } from "./r
 import { resolveRoomMentionsForBot, roomPostHasMentionTokens, } from "./room-mentions.js";
 import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
 import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
-import { currentHotSignalSyncCompany, hotSignalSyncJobCompany, removeStaleHotSignalSyncJobs } from "./jobs/hot-signal-sync.js";
+import { currentHotSignalSyncCompany, hotSignalSyncJobCompany, readActiveCompanySlug, removeStaleHotSignalSyncJobs } from "./jobs/hot-signal-sync.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
 import { SIGN_IN_CHECK_FRESH_MS, SIGN_IN_CHECK_MS, SIGN_IN_RETRY_MS, signInNeededText, signedOutExcerpt, } from "./runtime-sign-in.js";
 import { checkRuntimeSignIn } from "./runtime-sign-in-check.js";
@@ -1978,7 +1978,7 @@ export async function runBot(deps) {
                 log("warn", `hot-signal-sync job ${jobId} run ${id} skipped: bot.json missing or unreadable`);
                 return;
             }
-            const currentCompany = currentHotSignalSyncCompany(freshConfig);
+            const currentCompany = currentHotSignalSyncCompany(freshConfig, readActiveCompanySlug(freshConfig.hqRoot) ?? null);
             if (currentCompany !== syncCompany) {
                 let removedNote = "";
                 try {

package/dist/lib/hot-channels/adapters/attio.js

@@ -306,6 +306,9 @@ export function createAttioAdapter(options) {
                 reasons.add("owner");
             if (reasons.size === 0)
                 continue;
+            // A saved record pick: only deliveries about a chosen record land.
+            if (ctx.selection && !(ref && ctx.selection.has(ref.recordId)))
+                continue;
             events.push(toEvent(d, [...reasons], actor, ref, ctx.personUid, options.identities));
         }
         const last = page[page.length - 1];

package/dist/lib/hot-channels/adapters/linear.js

@@ -290,6 +290,10 @@ export function createLinearAdapter(options = {}) {
             if (!issue || Date.parse(issue.updatedAt) <= watermarkMs)
                 continue;
             high = high === null ? issue.updatedAt : laterOf(high, issue.updatedAt);
+            // A saved issue pick (by issue id or identifier such as ENG-123): other
+            // issues still move the watermark but do not land.
+            if (ctx.selection && !ctx.selection.has(issue.uuid) && !ctx.selection.has(issue.identifier))
+                continue;
             events.push(toEvent(issue, ctx.personUid));
         }
         if (page.hasNextPage) {

package/dist/lib/hot-channels/adapters/meetings.js

@@ -463,6 +463,10 @@ export function createMeetingsAdapter(options) {
         return { events, watermark: mark ?? new Date(fromMs).toISOString(), hasMore, deduped };
     }
     async function fetch(cursor, ctx) {
+        // The person saved an empty meetings pick: meetings are excluded. Nothing
+        // is read or written and the cursor stays where it was.
+        if (ctx.selection && ctx.selection.size === 0)
+            return { events: [], cursor, hasMore: false };
         const state = parseMeetingsCursor(cursor);
         const vault = await fetchVault(state.vault, ctx);
         const gateways = (ctx.gateways ?? []).filter((g) => MEETING_PROVIDERS.has(g.provider.toLowerCase()));

package/dist/lib/hot-channels/adapters/slack.js

@@ -238,6 +238,9 @@ export function createSlackAdapter(options) {
             const owners = [nonEmptyString(fm.person_uid), nonEmptyString(fm.account_id)];
             if (!owners.some((id) => id !== undefined && me.has(id.toLowerCase())))
                 continue;
+            // A saved channel pick: only threads in a chosen channel land.
+            if (ctx.selection && !ctx.selection.has(t.channelId))
+                continue;
             candidates.push(t);
         }
         if (!Number.isNaN(pausedMs) && pausedMs > floorMs) {

package/dist/lib/hot-channels/contract.d.ts

@@ -85,6 +85,13 @@ export interface PollContext {
      * was lost.
      */
     beforeWrite?: () => Promise<void>;
+    /**
+     * The ids the person chose to watch on this connection (hq-pro saved
+     * selection). When set, an adapter lands only events about one of these
+     * ids (Slack channel, Linear issue, Attio record); an empty set lands
+     * nothing. Unset means no choice was saved: land everything.
+     */
+    selection?: ReadonlySet<string>;
 }
 export interface PollPage {
     events: HotEvent[];

package/dist/lib/hot-channels/ledger.d.ts

@@ -41,6 +41,12 @@ export interface RunLedgerEntry {
      * was asleep or the bot was stopped). Omitted for runs that were not marked.
      */
     catchUp?: boolean;
+    /**
+     * True on the one run the bot starts right after it registers its daily
+     * hot-signal-sync job, so a new install syncs without waiting for the first
+     * scheduled time. Omitted on every other run.
+     */
+    firstRun?: boolean;
 }
 /** The UTC calendar day of an instant, `YYYY-MM-DD`. Ledger files are per UTC day. */
 export declare function ledgerDay(at: Date): string;
@@ -77,6 +83,8 @@ export interface RunHotChannelSyncInput extends RunHotChannelLoopInput {
     runId?: string;
     /** Mark every ledger line of this run as a catch-up of a missed scheduled window. */
     catchUp?: boolean;
+    /** Mark every ledger line of this run as the job's first run (see RunLedgerEntry.firstRun). */
+    firstRun?: boolean;
     /**
      * The signals pass for this adapter's landed sources; returns the number of
      * signals it wrote. Any throw makes this adapter's line `failed` with a count

package/dist/lib/hot-channels/ledger.js

@@ -12,6 +12,7 @@ import { assertNotIntegrationSecretsPath, personDirName } from "./cursors.js";
 import { runHotChannelLoop } from "./loop.js";
 import { SyncLockLostError } from "./sync-lock.js";
 import { SignalsPassError } from "./signals-pass.js";
+import { SELECTION_UNREADABLE_REASON } from "./selection.js";
 export const RUN_TRIGGERS = ["scheduled", "on-demand"];
 const DAY = /^\d{4}-\d{2}-\d{2}$/;
 /** The UTC calendar day of an instant, `YYYY-MM-DD`. Ledger files are per UTC day. */
@@ -52,7 +53,8 @@ function isLedgerEntry(value) {
         typeof v.finishedAt === "string" &&
         (v.status === "ok" || v.status === "failed" || v.status === "skipped") &&
         (v.error === null || typeof v.error === "string") &&
-        (v.catchUp === undefined || typeof v.catchUp === "boolean"));
+        (v.catchUp === undefined || typeof v.catchUp === "boolean") &&
+        (v.firstRun === undefined || typeof v.firstRun === "boolean"));
 }
 /** Read one day's ledger. A missing file is an empty ledger. */
 export async function readRunLedger(vaultRoot, personKey, day) {
@@ -123,7 +125,7 @@ export async function runHotChannelSync(input) {
     }
     const now = input.now ?? (() => new Date());
     const runId = input.runId ?? `run_${randomUUID()}`;
-    const { trigger: _trigger, runId: _runId, catchUp, signalsGenerated, ...loopInput } = input;
+    const { trigger: _trigger, runId: _runId, catchUp, firstRun, signalsGenerated, ...loopInput } = input;
     const results = [];
     const entries = [];
     for (const entry of input.catalog) {
@@ -175,6 +177,8 @@ export async function runHotChannelSync(input) {
                 error: failure,
                 personUid: input.personUid,
                 catchUp: catchUp ?? false,
+                ...(result?.error?.code === SELECTION_UNREADABLE_REASON ? { reason: SELECTION_UNREADABLE_REASON } : {}),
+                ...(firstRun ? { firstRun: true } : {}),
                 ...(result && result.rejected > 0
                     ? { rejected: result.rejected, rejectedReasons: [...(result.rejectedReasons ?? [])] }
                     : {}),

package/dist/lib/hot-channels/loop.d.ts

@@ -57,6 +57,12 @@ export interface RunHotChannelLoopInput {
      * `PollContext.gateway`. Called only for entries with a `connectionId`.
      */
     gatewayFor?: (entry: CatalogEntry) => HotChannelGateway | undefined;
+    /**
+     * The person's saved selection for a poll entry, handed to the adapter as
+     * `PollContext.selection`. Undefined means land everything; a throw skips
+     * this entry (fail closed) and records it as failed.
+     */
+    selectionFor?: (entry: CatalogEntry) => Promise<ReadonlySet<string> | undefined>;
     now?: () => Date;
     maxPagesPerAdapter?: number;
     maxPushEventsPerAdapter?: number;

package/dist/lib/hot-channels/loop.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { createVaultCursorStore, cursorKey } from "./cursors.js";
 import { assertHotEvent, assertSafeSegment, eventKey, HotEventValidationError, landHotEvent } from "./landing.js";
 import { SyncLockLostError } from "./sync-lock.js";
+import { SELECTION_UNREADABLE_REASON } from "./selection.js";
 /** Default page cap per poll adapter per run (policy: bound every wait/loop). */
 export const DEFAULT_MAX_PAGES_PER_ADAPTER = 20;
 /** Default cap on buffered push events drained per adapter per run. */
@@ -118,7 +119,7 @@ async function drainPush(ctx, adapter, result) {
         await fs.rm(file, { force: true });
     }
 }
-async function runPoll(ctx, adapter, result, key, gateway, gateways = []) {
+async function runPoll(ctx, adapter, result, key, gateway, gateways = [], selection) {
     let cursor = result.cursorBefore;
     for (let page = 0; page < ctx.maxPages; page += 1) {
         const now = ctx.now();
@@ -129,6 +130,7 @@ async function runPoll(ctx, adapter, result, key, gateway, gateways = []) {
             beforeWrite: ctx.beforeWrite,
             ...(gateway ? { gateway } : {}),
             ...(gateways.length > 0 ? { gateways } : {}),
+            ...(selection ? { selection } : {}),
         });
         result.pages += 1;
         let lastEventKey;
@@ -206,7 +208,19 @@ export async function runHotChannelLoop(input) {
                 });
                 result.cursorBefore = await ctx.cursorStore.get(ctx.personKey, key);
                 result.cursorAfter = result.cursorBefore;
-                await runPoll(ctx, adapter, result, key, gateway, gateways);
+                let selection;
+                try {
+                    selection = await input.selectionFor?.(entry);
+                }
+                catch (err) {
+                    // Fail closed: a saved selection that may exist but cannot be read
+                    // skips this connection (nothing lands, the cursor stays) and the
+                    // run goes on to the next one.
+                    ctx.warn(`hot-channel ${adapter.id}: saved selection unreadable (${describeError(err)?.message}); skipping this connection`);
+                    result.error = { name: "SelectionUnreadableError", code: SELECTION_UNREADABLE_REASON, message: describeError(err)?.message ?? "unreadable" };
+                    continue;
+                }
+                await runPoll(ctx, adapter, result, key, gateway, gateways, selection);
             }
         }
         catch (err) {

package/dist/lib/hot-channels/person-vault-reader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Reads objects from the signed-in person's own vault bucket, the bucket
+ * hq-pro writes hot-channel selections to. Same path as
+ * `hq files cat --personal`: resolve the person entity, vend STS credentials
+ * through `/sts/vend-self`, then `GetObject`.
+ *
+ * The entity lookup and credential vend happen once per reader (one reader per
+ * run); a failed open is retried on the next read. A missing object resolves
+ * null; any other failure rejects, and the selection loader skips that
+ * connection (fail closed).
+ */
+import { GetObjectCommand, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
+import type { PersonVaultObjectReader } from "./selection.js";
+export interface PersonVaultReaderDeps {
+    /** The signed-in person's canonical person-entity uid. */
+    resolvePersonUid(): Promise<string>;
+    getEntity(uid: string): Promise<{
+        uid: string;
+        bucketName?: string;
+    }>;
+    vendSelf(personUid: string): Promise<{
+        credentials: {
+            accessKeyId: string;
+            secretAccessKey: string;
+            sessionToken: string;
+        };
+    }>;
+    s3Factory(input: {
+        region: string;
+        credentials: {
+            accessKeyId: string;
+            secretAccessKey: string;
+            sessionToken: string;
+        };
+    }): {
+        send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
+    };
+    region: string;
+}
+export declare function createPersonVaultReader(deps: PersonVaultReaderDeps): PersonVaultObjectReader;
+//# sourceMappingURL=person-vault-reader.d.ts.map

package/dist/lib/hot-channels/person-vault-reader.js

@@ -0,0 +1,59 @@
+/**
+ * Reads objects from the signed-in person's own vault bucket, the bucket
+ * hq-pro writes hot-channel selections to. Same path as
+ * `hq files cat --personal`: resolve the person entity, vend STS credentials
+ * through `/sts/vend-self`, then `GetObject`.
+ *
+ * The entity lookup and credential vend happen once per reader (one reader per
+ * run); a failed open is retried on the next read. A missing object resolves
+ * null; any other failure rejects, and the selection loader skips that
+ * connection (fail closed).
+ */
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+function isMissingObject(err) {
+    const name = err?.name;
+    const status = err?.$metadata?.httpStatusCode;
+    return name === "NoSuchKey" || name === "NotFound" || status === 404;
+}
+export function createPersonVaultReader(deps) {
+    let session;
+    const open = async () => {
+        const uid = await deps.resolvePersonUid();
+        const entity = await deps.getEntity(uid);
+        // No personal bucket means hq-pro has nowhere to have saved a pick.
+        if (!entity.bucketName)
+            return null;
+        const vend = await deps.vendSelf(entity.uid);
+        return { bucket: entity.bucketName, s3: deps.s3Factory({ region: deps.region, credentials: vend.credentials }) };
+    };
+    return async (key) => {
+        // One open per reader (one reader per run). A failed open is not kept:
+        // the next read tries again, so one bad vend does not cover the run.
+        const opening = (session ??= open());
+        let opened;
+        try {
+            opened = await opening;
+        }
+        catch (err) {
+            if (session === opening)
+                session = undefined;
+            throw err;
+        }
+        if (opened === null)
+            return null;
+        const { bucket, s3 } = opened;
+        let resp;
+        try {
+            resp = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+        }
+        catch (err) {
+            if (isMissingObject(err))
+                return null;
+            throw err;
+        }
+        if (!resp.Body)
+            return null;
+        return await resp.Body.transformToString();
+    };
+}
+//# sourceMappingURL=person-vault-reader.js.map