@indigoai-us/hq-cli 5.345.190 → 5.345.193

package/dist/lib/bot/fleet-owner-companies.d.ts

@@ -0,0 +1,12 @@
+export interface OwnerMembership {
+    companyUid: string;
+    companySlug?: string;
+    status: string;
+}
+export interface FleetOwnerCompaniesDependencies {
+    /** The signed-in owner's memberships; never prompts for sign-in. */
+    memberships?: () => Promise<OwnerMembership[]>;
+}
+/** Every active company the signed-in owner can access, independent of rollout flags or local folders. */
+export declare function fleetOwnerCompanies(dependencies?: FleetOwnerCompaniesDependencies): Promise<string[]>;
+//# sourceMappingURL=fleet-owner-companies.d.ts.map

package/dist/lib/bot/fleet-owner-companies.js

@@ -0,0 +1,30 @@
+import { ensureCognitoToken } from "../../utils/cognito-session.js";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+const MEMBERSHIP_TIMEOUT_MS = 10_000;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+async function signedInMemberships() {
+    const token = await ensureCognitoToken({ tokenSource: "person", interactive: false });
+    const res = await vaultApiFetch({ token, path: "/membership/me", signal: AbortSignal.timeout(MEMBERSHIP_TIMEOUT_MS) });
+    if (!res.ok)
+        throw new Error(`membership lookup returned ${res.status}`);
+    const data = (await res.json());
+    if (!Array.isArray(data.memberships))
+        throw new Error("membership lookup returned no list");
+    return data.memberships;
+}
+/** Every active company the signed-in owner can access, independent of rollout flags or local folders. */
+export async function fleetOwnerCompanies(dependencies = {}) {
+    const memberships = await (dependencies.memberships ?? signedInMemberships)();
+    const companies = new Set();
+    for (const membership of memberships) {
+        const slug = membership.companySlug?.trim() ?? "";
+        if (membership.status !== "active" || !COMPANY_UID_RE.test(membership.companyUid))
+            continue;
+        if (!COMPANY_SLUG_RE.test(slug) || slug === "personal")
+            continue;
+        companies.add(slug);
+    }
+    return [...companies].sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=fleet-owner-companies.js.map

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

@@ -0,0 +1,25 @@
+import { type BotConfig } from "./config.js";
+import type { FleetLocalReleasePin, FleetLocalTargetRelease } from "./fleet-local.js";
+export interface FleetWatchBot {
+    name: string;
+    dir: string;
+    config: BotConfig;
+}
+export interface FleetWatchDeps {
+    listBots(): FleetWatchBot[];
+    target(): Promise<FleetLocalTargetRelease | null>;
+    installed(bot: FleetWatchBot): boolean;
+    heldForPromotion(bot: FleetWatchBot): boolean;
+    needsAdoption(bot: FleetWatchBot, release: FleetLocalReleasePin): boolean;
+    busy(bot: FleetWatchBot): string | null;
+    update(bot: FleetWatchBot): Promise<"unchanged" | "updated" | "waiting">;
+    log(line: string): void;
+}
+export interface FleetWatchResult {
+    updated: string[];
+    waiting: string[];
+    failed: string[];
+}
+export declare function listFleetBots(root: string): FleetWatchBot[];
+export declare function runFleetBotsUpdate(deps: FleetWatchDeps): Promise<FleetWatchResult>;
+//# sourceMappingURL=fleet-watch.d.ts.map

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

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { HQ_FLEET_RUNTIME_ENGINE_ID, readBotConfig } from "./config.js";
+export function listFleetBots(root) {
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({ name: entry.name, dir: path.join(root, entry.name), config: readBotConfig(path.join(root, entry.name)) }))
+        .filter((bot) => bot.config !== null && bot.config.engine?.id === HQ_FLEET_RUNTIME_ENGINE_ID)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function runFleetBotsUpdate(deps) {
+    const result = { updated: [], waiting: [], failed: [] };
+    const candidates = deps
+        .listBots()
+        .filter((bot) => bot.config.fleetAuthPending !== true && !deps.heldForPromotion(bot) && deps.installed(bot));
+    if (candidates.length === 0)
+        return result;
+    const target = await deps.target();
+    const version = target?.release.version ?? "release";
+    for (const bot of candidates) {
+        if (bot.config.fleetRestartPending !== true && (!target || !deps.needsAdoption(bot, target.release)))
+            continue;
+        const busy = deps.busy(bot);
+        if (busy) {
+            deps.log(`${bot.name}: HQ Fleet Local ${version} is ready; waiting because ${busy}; trying again next run`);
+            result.waiting.push(bot.name);
+            continue;
+        }
+        try {
+            const outcome = await deps.update(bot);
+            if (outcome === "waiting") {
+                deps.log(`${bot.name}: HQ Fleet Local ${version} is installed; the restart waits until the bot is idle; trying again next run`);
+                result.waiting.push(bot.name);
+                continue;
+            }
+            if (outcome === "unchanged")
+                continue;
+            deps.log(`${bot.name}: moved to HQ Fleet Local ${version} and restarted`);
+            result.updated.push(bot.name);
+        }
+        catch (err) {
+            deps.log(`${bot.name}: could not move to HQ Fleet Local ${version}: ${err instanceof Error ? err.message : String(err)}`);
+            result.failed.push(bot.name);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=fleet-watch.js.map

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

@@ -26,6 +26,6 @@ export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
 export * from "./fleet-local.js";
-export * from "./fleet-default-flag.js";
+export * from "./fleet-owner-companies.js";
 export * from "./fleet-python.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -26,6 +26,6 @@ export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
 export * from "./fleet-local.js";
-export * from "./fleet-default-flag.js";
+export * from "./fleet-owner-companies.js";
 export * from "./fleet-python.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/job-run.d.ts

@@ -1,10 +1,11 @@
 /**
  * Scheduled job runs: the third kind of inbox item a bot can be handed.
  *
- * The cloud does all the scheduling. hq-pro-agents fires a job on an
- * EventBridge schedule and writes a DURABLE inbox item for the agent
- * (`channel: "job"`) carrying the job's own prompt. Nothing is scheduled on
- * this computer — there is no crontab, no launchd timer, no local clock.
+ * A local bot's jobs live in its own jobs.json and its inbox loop fires them
+ * (lib/bot/local-jobs.ts): a due job becomes a `channel: "job"` inbox item
+ * carrying the job's own prompt. A hosted agent's job arrives the same way,
+ * written by hq-pro-agents from its cloud schedule. Either way there is no
+ * crontab, no launchd timer and no system scheduler on this computer.
  *
  * Two rules shape everything here (owner decisions, 2026-09-15):
  *

package/dist/lib/bot/job-run.js

@@ -1,10 +1,11 @@
 /**
  * Scheduled job runs: the third kind of inbox item a bot can be handed.
  *
- * The cloud does all the scheduling. hq-pro-agents fires a job on an
- * EventBridge schedule and writes a DURABLE inbox item for the agent
- * (`channel: "job"`) carrying the job's own prompt. Nothing is scheduled on
- * this computer — there is no crontab, no launchd timer, no local clock.
+ * A local bot's jobs live in its own jobs.json and its inbox loop fires them
+ * (lib/bot/local-jobs.ts): a due job becomes a `channel: "job"` inbox item
+ * carrying the job's own prompt. A hosted agent's job arrives the same way,
+ * written by hq-pro-agents from its cloud schedule. Either way there is no
+ * crontab, no launchd timer and no system scheduler on this computer.
  *
  * Two rules shape everything here (owner decisions, 2026-09-15):
  *

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

@@ -15,8 +15,19 @@
  * `hq bot jobs <bot> --reschedule <jobId> --every "<when>"`, or removes it with
  * `--rm`, and a removed job is not added back on the next start.
  *
- * When the job fires the bot runs the sync in-process, with no model turn
- * (`runHotSignalSyncJob`): the same hot-channel sync `hq sources sync` runs,
+ * When the job fires the bot runs the signals engine in-process (US-006):
+ * `runSignals({ trigger: "job", catchUp })`, the same engine `hq signals run`
+ * uses (garden -> adapters -> extract -> garden -> upload, with the caps from
+ * core/settings/signals.yaml and a run record), and reports the run to the
+ * owner in the storyboarded reply format (lib/signals/reply.ts). When a run
+ * fails with a transient error, the run record carries `nextRetryAt` and the
+ * bot runs the job once more at that time, in-process (lib/bot/run.ts); only
+ * then does the failure reply offer to wait for the retry. The run started
+ * right after registration uses the `manual` trigger, so it never counts as
+ * the day's scheduled job. Extract
+ * spawns the member's own claude/codex under the bot's login, so the
+ * orchestration itself has no model turn. Without an engine wired in, the
+ * job falls back to the sync alone: the same hot-channel sync `hq sources sync` runs,
  * with `trigger: "scheduled"` and `catchUp` set when the run fired late after
  * a missed window. Catch-up is bounded by each adapter's `catchUpWindow`, and
  * per-connection cursors keep a redelivered run from landing anything twice.
@@ -26,15 +37,23 @@
 import type { HotChannelRunResult, WriteGuard } from "../../hot-channels/loop.js";
 import type { RunTrigger } from "../../hot-channels/ledger.js";
 import type { OnDemandSyncReport } from "../../hot-channels/run.js";
+import { type RunSignalsOptions, type RunSignalsResult } from "../../signals/engine.js";
+import { type FormattedReply } from "../../signals/reply.js";
 import { type BotConfig } from "../config.js";
 import { type LocalJob } from "../local-jobs.js";
 export declare const HOT_SIGNAL_SYNC_JOB_KIND = "hot-signal-sync";
 /**
- * 06:30 every day, in the job's time zone (the stored EventBridge form of
+ * 06:30 every day, in the job's time zone (the stored six-field form of
  * "30 6 * * *"). Only the first registration uses it; after that the job's
  * own schedule in `jobs.json` is the one that runs.
  */
 export declare const HOT_SIGNAL_SYNC_DEFAULT_CRON = "cron(30 6 * * ? *)";
+export declare function hotSignalSyncRegistered(dir: string, company: string): boolean;
+export declare function fleetHotSignalSyncRegistered(dir: string, company: string): boolean;
+export declare function markFleetHotSignalSyncRegistered(dir: string, company: string, now?: Date): void;
+export declare function markHotSignalSyncRegistered(dir: string, company: string, now?: Date): void;
+export declare function forgetHotSignalSyncRegistrations(dir: string, keep: string | null): string[];
+export declare function forgetHotSignalSyncRegistrationsExcept(dir: string, keep: readonly string[]): string[];
 /** The private context that marks a job as this built-in, for one company. */
 export declare function hotSignalSyncJobContext(company: string): Record<string, unknown>;
 /** The company a job item syncs, when its context marks it as this built-in; else null. */
@@ -146,12 +165,47 @@ export interface HotSignalSyncRunInput {
      */
     sendAlert?: (text: string) => Promise<void>;
     log?: (message: string) => void;
+    /**
+     * The signals engine (`runSignals`). When set, a fired job runs the whole
+     * engine for the company instead of the sync alone; `hqRoot` is required.
+     */
+    signals?: (options: SignalsEngineJobOptions) => Promise<RunSignalsResult>;
+    hqRoot?: string;
+    /** The job's zone, for the times in the reply. */
+    timeZone?: string;
+    /** When the run was due (the fired item's `firedAt`), for the catch-up line. */
+    scheduledFor?: string;
+    /** This run is the bot's automatic retry of a failed run; it never schedules another. */
+    retry?: boolean;
+    /**
+     * Asks the bot to run the job once more at `at` (the run record's
+     * `nextRetryAt`). Returns true when the retry is scheduled; only then does
+     * the failure reply say when it tries again. Unset = no automatic retry.
+     */
+    scheduleRetry?: (at: string) => boolean;
 }
+/**
+ * The engine options a fired job passes. `signalsAlert` is the owner-DM
+ * sender for the signals-failure alert (US-018, hq-cli #2314). Until #2314
+ * adds it to `RunSignalsOptions`, `runSignals` ignores the field; once it
+ * lands, the engine alerts when a run lands sources and produces no signals.
+ */
+export type SignalsEngineJobOptions = RunSignalsOptions & {
+    signalsAlert?: {
+        sendOwnerDm: (text: string) => Promise<void>;
+        log?: (message: string) => void;
+    };
+};
 export interface HotSignalSyncRunOutcome {
     ok: boolean;
     /** Plain report for the owner's DM and the job's run output. */
     text: string;
     report: OnDemandSyncReport | null;
+    /** The engine's result and the storyboarded reply, when the engine ran. */
+    signals?: RunSignalsResult;
+    reply?: FormattedReply;
+    /** When the bot runs the automatic retry (the record's nextRetryAt), if one was scheduled. */
+    retryAt?: string;
 }
 /** Run the scheduled sync once and describe it in plain words. Never throws. */
 export declare function runHotSignalSyncJob(input: HotSignalSyncRunInput): Promise<HotSignalSyncRunOutcome>;

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

@@ -15,8 +15,19 @@
  * `hq bot jobs <bot> --reschedule <jobId> --every "<when>"`, or removes it with
  * `--rm`, and a removed job is not added back on the next start.
  *
- * When the job fires the bot runs the sync in-process, with no model turn
- * (`runHotSignalSyncJob`): the same hot-channel sync `hq sources sync` runs,
+ * When the job fires the bot runs the signals engine in-process (US-006):
+ * `runSignals({ trigger: "job", catchUp })`, the same engine `hq signals run`
+ * uses (garden -> adapters -> extract -> garden -> upload, with the caps from
+ * core/settings/signals.yaml and a run record), and reports the run to the
+ * owner in the storyboarded reply format (lib/signals/reply.ts). When a run
+ * fails with a transient error, the run record carries `nextRetryAt` and the
+ * bot runs the job once more at that time, in-process (lib/bot/run.ts); only
+ * then does the failure reply offer to wait for the retry. The run started
+ * right after registration uses the `manual` trigger, so it never counts as
+ * the day's scheduled job. Extract
+ * spawns the member's own claude/codex under the bot's login, so the
+ * orchestration itself has no model turn. Without an engine wired in, the
+ * job falls back to the sync alone: the same hot-channel sync `hq sources sync` runs,
  * with `trigger: "scheduled"` and `catchUp` set when the run fired late after
  * a missed window. Catch-up is bounded by each adapter's `catchUpWindow`, and
  * per-connection cursors keep a redelivered run from landing anything twice.
@@ -26,11 +37,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { JOB_RUN_OPTIONS_CONTEXT_KEY } from "../job-run.js";
+import { localDate, runRecordRel } from "../../signals/engine.js";
+import { formatJobErrorReply, formatLockedReply, formatRunReply, timeInWords } from "../../signals/reply.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";
 /**
- * 06:30 every day, in the job's time zone (the stored EventBridge form of
+ * 06:30 every day, in the job's time zone (the stored six-field form of
  * "30 6 * * *"). Only the first registration uses it; after that the job's
  * own schedule in `jobs.json` is the one that runs.
  */
@@ -40,6 +53,9 @@ const BUILTIN_JOBS_FILE = "builtin-jobs.json";
 function markerKey(company) {
     return `${HOT_SIGNAL_SYNC_JOB_KIND}:${company}`;
 }
+function fleetMarkerKey(company) {
+    return `${HOT_SIGNAL_SYNC_JOB_KIND}:fleet:${company}`;
+}
 function readMarker(dir) {
     try {
         const parsed = JSON.parse(fs.readFileSync(path.join(dir, BUILTIN_JOBS_FILE), "utf-8"));
@@ -58,6 +74,64 @@ function writeMarker(dir, marker) {
     fs.writeFileSync(tmp, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
     fs.renameSync(tmp, file);
 }
+export function hotSignalSyncRegistered(dir, company) {
+    return Boolean(readMarker(dir).registered[markerKey(company)]);
+}
+export function fleetHotSignalSyncRegistered(dir, company) {
+    return Boolean(readMarker(dir).registered[fleetMarkerKey(company)]);
+}
+export function markFleetHotSignalSyncRegistered(dir, company, now = new Date()) {
+    withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        if (marker.registered[fleetMarkerKey(company)])
+            return;
+        marker.registered[fleetMarkerKey(company)] = now.toISOString();
+        writeMarker(dir, marker);
+    });
+}
+export function markHotSignalSyncRegistered(dir, company, now = new Date()) {
+    withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        if (marker.registered[markerKey(company)])
+            return;
+        marker.registered[markerKey(company)] = now.toISOString();
+        writeMarker(dir, marker);
+    });
+}
+export function forgetHotSignalSyncRegistrations(dir, keep) {
+    const keepKey = keep ? markerKey(keep) : null;
+    return withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        const forgotten = [];
+        for (const key of Object.keys(marker.registered)) {
+            if (key.startsWith(HOT_SIGNAL_SYNC_JOB_KIND + ":") && key !== keepKey) {
+                delete marker.registered[key];
+                forgotten.push(key.slice(HOT_SIGNAL_SYNC_JOB_KIND.length + 1));
+            }
+        }
+        if (forgotten.length > 0)
+            writeMarker(dir, marker);
+        return forgotten;
+    });
+}
+export function forgetHotSignalSyncRegistrationsExcept(dir, keep) {
+    const keepKeys = new Set(keep.flatMap((company) => [markerKey(company), fleetMarkerKey(company)]));
+    return withJobsLock(dir, () => {
+        const marker = readMarker(dir);
+        const forgotten = [];
+        for (const key of Object.keys(marker.registered)) {
+            if (key.startsWith(HOT_SIGNAL_SYNC_JOB_KIND + ":") && !keepKeys.has(key)) {
+                delete marker.registered[key];
+                const company = key.slice(HOT_SIGNAL_SYNC_JOB_KIND.length + 1).replace(/^fleet:/, "");
+                if (!forgotten.includes(company))
+                    forgotten.push(company);
+            }
+        }
+        if (forgotten.length > 0)
+            writeMarker(dir, marker);
+        return forgotten;
+    });
+}
 /** The private context that marks a job as this built-in, for one company. */
 export function hotSignalSyncJobContext(company) {
     return { [JOB_RUN_OPTIONS_CONTEXT_KEY]: { builtin: HOT_SIGNAL_SYNC_JOB_KIND, company } };
@@ -117,7 +191,8 @@ export function otherBotWithHotSignalSync(dir, company, botDirs) {
     for (const other of botDirs) {
         if (path.resolve(other) === self)
             continue;
-        if (readMarker(other).registered[markerKey(company)])
+        const registered = readMarker(other).registered;
+        if (registered[markerKey(company)] || registered[fleetMarkerKey(company)])
             return other;
         if (readLocalJobs(other).some((job) => hotSignalSyncJobCompany(job.context) === company))
             return other;
@@ -227,8 +302,92 @@ function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
 export const noLocalSignalsPass = async () => 0;
+/**
+ * Today's run record for the company, or null. The automatic retry reads it
+ * first: when another run (a "Try now", a brief run) already finished the day
+ * complete or partial since the failure, the retry has nothing to do.
+ */
+function readTodaysRecord(hqRoot, company, now) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(hqRoot, runRecordRel(localDate(now), company)), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function runSignalsEngineJob(input) {
+    if (!input.hqRoot) {
+        const reply = formatJobErrorReply(`Morning signals for ${input.company} did not run.`, "The bot has no HQ folder set, so it cannot find the company's files.");
+        return { ok: false, text: reply.text, report: null, reply };
+    }
+    const timeZone = input.timeZone ?? "UTC";
+    if (input.retry) {
+        const today = readTodaysRecord(input.hqRoot, input.company, input.now());
+        if (today && (today.status === "complete" || today.status === "partial")) {
+            const at = timeInWords(today.finishedAt, timeZone);
+            const text = `Morning signals for ${input.company} already finished${at ? ` at ${at}` : ""} after another run, so the automatic retry had nothing to do.`;
+            return { ok: true, text, report: null };
+        }
+    }
+    const options = {
+        hqRoot: input.hqRoot,
+        company: input.company,
+        // The run right after the job is registered is a setup run, not the day's
+        // scheduled run: a non-job trigger leaves jobRanAt alone, so the morning
+        // job still runs (a bot first started at 01:00 is not "already ran").
+        trigger: input.firstRun ? "manual" : "job",
+        catchUp: input.catchUp,
+        now: input.now,
+        // The signals-failure alert (US-018): the owner DM, sent even when the job is quiet.
+        ...(input.sendAlert
+            ? { signalsAlert: { sendOwnerDm: input.sendAlert, ...(input.log ? { log: input.log } : {}) } }
+            : {}),
+    };
+    let result;
+    try {
+        result = await input.signals(options);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        const reply = formatJobErrorReply(`Morning signals for ${input.company} failed.`, reason);
+        return { ok: false, text: reply.text, report: null, reply };
+    }
+    const replyOptions = {
+        timeZone,
+        ...(input.scheduledFor ? { scheduledFor: input.scheduledFor } : {}),
+    };
+    const record = result.records.find((r) => r.company === input.company) ?? result.records[0];
+    if (!record) {
+        const locked = (result.locked ?? []).find((l) => l.company === input.company);
+        if (locked) {
+            const reply = formatLockedReply(locked, replyOptions);
+            return { ok: true, text: reply.text, report: null, signals: result, reply };
+        }
+        const reply = formatJobErrorReply(`Morning signals for ${input.company} did not finish.`, "The run left no run record, so I cannot say what happened.");
+        return { ok: false, text: reply.text, report: null, signals: result, reply };
+    }
+    // One automatic retry per failed scheduled run, only when the engine set a
+    // retry time (a transient failure) and the bot really scheduled it. The
+    // retry itself never schedules another.
+    const retryScheduled = record.status === "failed" &&
+        !record.alreadyRanToday &&
+        typeof record.nextRetryAt === "string" &&
+        !input.retry &&
+        input.scheduleRetry !== undefined &&
+        input.scheduleRetry(record.nextRetryAt);
+    const reply = formatRunReply(record, result.summary, {
+        ...replyOptions,
+        ...(retryScheduled ? { retryScheduled: true } : {}),
+        ...(input.retry ? { wasRetry: true } : {}),
+    });
+    const ok = reply.variant !== "failed" && reply.variant !== "partial";
+    return { ok, text: reply.text, report: null, signals: result, reply, ...(retryScheduled ? { retryAt: record.nextRetryAt } : {}) };
+}
 /** Run the scheduled sync once and describe it in plain words. Never throws. */
 export async function runHotSignalSyncJob(input) {
+    if (input.signals)
+        return runSignalsEngineJob({ ...input, signals: input.signals });
     const signalsPass = input.signalsPass ?? noLocalSignalsPass;
     let report;
     try {

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

@@ -45,6 +45,7 @@ export interface LocalJob {
     runCount?: number;
 }
 export declare function readLocalJobs(dir: string): LocalJob[];
+export declare function writeLocalJobs(dir: string, jobs: LocalJob[]): void;
 /**
  * Run a read-change-write of `jobs.json` under an exclusive lock. The running
  * bot (firing, finishing) and `hq bot jobs` (add, remove) are separate
@@ -63,8 +64,9 @@ export interface CronMatcher {
 }
 /**
  * The job's schedule as a standard 5-field cron. Jobs are stored in the same
- * form the cloud uses (`cron(m h dom mon dow year)`, Sunday = 1, `?` for the
- * unused day field), so the same `hq bot jobs` input works for either home.
+ * six-field form hosted agent jobs use (`cron(m h dom mon dow year)`, Sunday =
+ * 1, `?` for the unused day field), so the same `hq bot jobs` input works for
+ * either home.
  */
 export declare function toStandardCron(expr: string): string | null;
 /** Parse a standard 5-field cron, or null when it is not one. */
@@ -106,6 +108,15 @@ export declare function removeLocalJobsWhere(dir: string, matches: (job: LocalJo
 /** Forget the once-per-minute check (tests, and a bot restarted in-process). */
 export declare function resetLocalJobChecks(): void;
 export declare function takeDueLocalJobRuns(dir: string, now?: Date): InboxItem[];
+/** A run of a job in this bot's own jobs.json (its ack and completion stay local). */
+export declare function isLocalJobMessage(messageId: string): boolean;
+/**
+ * The message id of the bot's one automatic retry of a local job run (the
+ * signals job after a transient failure). It keeps the local prefix, so its
+ * ack and completion stay on this computer like any other local run.
+ */
+export declare function localJobRetryMessageId(jobId: string, dueMs: number): string;
+export declare function isLocalJobRetryMessage(messageId: string): boolean;
 /**
  * The bot's cloud client, with its scheduled runs answered on this computer:
  * due local jobs join the inbox, and their ack and completion are recorded

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

@@ -69,7 +69,7 @@ function readLocalJobsForAdd(dir) {
     }
     return parsed.jobs.filter((job) => !!job && typeof job.jobId === "string");
 }
-function writeLocalJobs(dir, jobs) {
+export function writeLocalJobs(dir, jobs) {
     const file = localJobsPath(dir);
     const tmp = `${file}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify({ v: 1, jobs }, null, 2));
@@ -170,8 +170,9 @@ function replaceNames(field, names) {
 }
 /**
  * The job's schedule as a standard 5-field cron. Jobs are stored in the same
- * form the cloud uses (`cron(m h dom mon dow year)`, Sunday = 1, `?` for the
- * unused day field), so the same `hq bot jobs` input works for either home.
+ * six-field form hosted agent jobs use (`cron(m h dom mon dow year)`, Sunday =
+ * 1, `?` for the unused day field), so the same `hq bot jobs` input works for
+ * either home.
  */
 export function toStandardCron(expr) {
     const trimmed = expr.trim();
@@ -465,9 +466,21 @@ export function takeDueLocalJobRuns(dir, now = new Date()) {
         return items;
     });
 }
-function isLocalJobMessage(messageId) {
+/** A run of a job in this bot's own jobs.json (its ack and completion stay local). */
+export function isLocalJobMessage(messageId) {
     return messageId.startsWith(LOCAL_JOB_MESSAGE_PREFIX);
 }
+/**
+ * The message id of the bot's one automatic retry of a local job run (the
+ * signals job after a transient failure). It keeps the local prefix, so its
+ * ack and completion stay on this computer like any other local run.
+ */
+export function localJobRetryMessageId(jobId, dueMs) {
+    return `${LOCAL_JOB_MESSAGE_PREFIX}${jobId}-retry-${dueMs}`;
+}
+export function isLocalJobRetryMessage(messageId) {
+    return isLocalJobMessage(messageId) && /-retry-\d+$/.test(messageId);
+}
 /** Record how a local run finished and release the job for its next fire. */
 function finishLocalJobRun(dir, jobId, messageId, completion, now = new Date()) {
     withJobsLock(dir, () => {

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

@@ -70,6 +70,16 @@ export declare const PRE_TOOL_ASIDE_MAX_CHARS = 40;
  * your agency docs now, then I'll look at the client folders.") and run past
  * the limit; an hq-block is always content the desktop app must draw.
  */
+/**
+ * A heads-up the model writes right before a long piece of work ("Give me
+ * about two minutes to check what's on this computer, then I'll ask my
+ * first question."). A bot that drops every pre-tool message
+ * (`dropPreToolMessages`) still lets ONE of these through per turn, so the
+ * person hears what is happening and how long it takes instead of watching
+ * a spinner. Short, one or two sentences, names a wait, no hq-block.
+ */
+export declare const WAIT_HEADS_UP_MAX_CHARS = 240;
+export declare function isWaitHeadsUp(text: string): boolean;
 export declare function isPreToolAside(text: string): boolean;
 /** Whitespace-insensitive form used to recognise repeated text. */
 export declare function normalizeForCompare(text: string): string;
@@ -87,6 +97,8 @@ export declare class ProgressPoster {
     private readonly workingNoticeText;
     private readonly buffer;
     private readonly dropPreTool;
+    /** With dropPreToolMessages: one wait heads-up (isWaitHeadsUp) per turn is kept. */
+    private headsUpKept;
     private readonly onDropped;
     /**
      * Messages waiting to learn whether a tool call follows: every message when
@@ -119,6 +131,8 @@ export declare class ProgressPoster {
     constructor(opts: ProgressPosterOptions);
     /** Arm the one-time "working on it" note. Call when the turn starts. */
     start(): void;
+    /** Arm the still-working line again after a kept heads-up (start() skips a turn that said something). */
+    private rearmNoticeAfter;
     /** One finished assistant message from the model. */
     message(text: string): void;
     /** The model called a tool: whatever it wrote just before was a note to itself. */