@indigoai-us/hq-cli 5.345.183 → 5.345.188

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

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

@@ -15,6 +15,7 @@
 import type { CatchUpWindow, HotTransport, SuggestionRule, TokenScope } from "./contract.js";
 import { type RunLedgerEntry, type RunTrigger, type SignalsGeneratedFn } from "./ledger.js";
 import type { HotChannelRegistry } from "./registry.js";
+import { type SelectionLoader } from "./selection.js";
 /** One item of the catalog API's top-level `hotChannels` array (hq-pro US-002). */
 export interface HotChannelCatalogItem {
     entryId?: string;
@@ -96,10 +97,17 @@ export interface OnDemandSyncInput {
     trigger?: RunTrigger;
     /** A scheduled run that fired late, after a missed window. */
     catchUp?: boolean;
+    /** The first run after the bot registered its hot-signal-sync job. */
+    firstRun?: boolean;
     /** The signals pass over each adapter's landed sources (US-011); 0 when absent. */
     signalsGenerated?: SignalsGeneratedFn;
     /** Checked before each document write (sync-lock ownership); a throw stops the run. */
     beforeWrite?: () => Promise<void>;
+    /**
+     * The person's saved hot-channel selections for this run (one loader per
+     * run, so nothing is cached across runs). Absent = land everything.
+     */
+    selections?: SelectionLoader;
 }
 export type SyncOutcomeStatus = "ok" | "failed" | "unavailable" | "no-connection" | "gated";
 export interface SyncOutcome {

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

@@ -18,6 +18,7 @@ import { bareProvider } from "../integrations/provider-slug.js";
 import { createVaultCursorStore } from "./cursors.js";
 import { cursorFilePath } from "./cursors.js";
 import { runHotChannelSync } from "./ledger.js";
+import { connectionSelection, meetingsSelection } from "./selection.js";
 /** Token-scope providers served from the HQ vault: no external connection. */
 /**
  * The bare, lowercased provider id used to match a connection against a
@@ -174,6 +175,22 @@ function sourcesOnlyCursorStore(vaultRoot, now) {
         },
     };
 }
+/**
+ * The saved selection for one planned entry: the entry's own connection (an
+ * empty list counts as no choice), or for a connectionless channel with companions (meetings) the include/exclude
+ * choice saved on its recorder connections.
+ */
+function selectionFor(load) {
+    return async (entry) => {
+        // An empty saved list on a connection means no choice yet: land everything.
+        if (entry.connectionId)
+            return connectionSelection(await load(entry.connectionId));
+        const companions = entry.companionConnectionIds ?? [];
+        if (companions.length === 0)
+            return undefined;
+        return meetingsSelection(await Promise.all(companions.map((id) => load(id))));
+    };
+}
 export async function runOnDemandSync(input) {
     const report = {
         runId: null,
@@ -276,6 +293,7 @@ export async function runOnDemandSync(input) {
         const sync = await runHotChannelSync({
             trigger: input.trigger ?? "on-demand",
             ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
+            ...(input.firstRun ? { firstRun: true } : {}),
             ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
             ...(input.beforeWrite ? { beforeWrite: input.beforeWrite } : {}),
             registry: input.registry,
@@ -284,6 +302,7 @@ export async function runOnDemandSync(input) {
             personUid: input.personUid,
             personKey: input.personKey,
             cursorStore: sourcesOnlyCursorStore(input.vaultRoot, input.now),
+            ...(input.selections ? { selectionFor: selectionFor(input.selections) } : {}),
             gatewayFor: (entry) => {
                 const app = entry.connectionId ? appsByConnection.get(entry.connectionId) : undefined;
                 return app ? gatewayFor(app, input.deps, reconnects) : undefined;