@indigoai-us/hq-cli 5.345.198 → 5.345.199

package/dist/lib/bot/jobs/signal-to-lane.js

@@ -0,0 +1,169 @@
+/** Source-independent action-item consumer for the personal Executive. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { readBotConfig } from "../config.js";
+import { botsRoot } from "../paths.js";
+import { fleetProfileOwnerCompanies } from "../fleet-local.js";
+import { fleetHotSignalSyncCompanies } from "../fleet-cron.js";
+import { readActiveCompanySlug, readBuiltinJobsMarker, writeBuiltinJobsMarker } from "./hot-signal-sync.js";
+import { isExecutiveBot } from "./meeting-rider.js";
+import { readLocalJobsStrict, writeLocalJobs, withJobsLock } from "../local-jobs.js";
+import { emitBotEvent } from "../events.js";
+import { isLanesError } from "../../lanes/errors.js";
+import { lookupSignal } from "../../lanes/signal-lane.js";
+export const SIGNAL_TO_LANE_JOB_KIND = "signal-to-lane";
+export function signalLaneCompanies(config) {
+    return fleetHotSignalSyncCompanies(config, readActiveCompanySlug(config.hqRoot) ?? null, fleetProfileOwnerCompanies(config.agentUid));
+}
+export function ensureSignalToLaneJobs(dir, config, companies = signalLaneCompanies(config), home) {
+    if (!isExecutiveBot(config, home))
+        return [];
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        const marker = readBuiltinJobsMarker(dir);
+        for (const company of new Set(companies)) {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(company) || company === "personal")
+                continue;
+            const key = `${SIGNAL_TO_LANE_JOB_KIND}:${company}`;
+            if (marker.registered[key])
+                continue;
+            if (!jobs.some(job => job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND && job.context.company === company)) {
+                jobs.push({ jobId: `job_${randomUUID().replaceAll("-", "").slice(0, 20)}`,
+                    prompt: "Open a conductor lane from an action item in-process.", timezone: "UTC",
+                    trigger: { kind: "event", event: "signal.written", filter: { type: "action_item", company } },
+                    context: { jobKind: SIGNAL_TO_LANE_JOB_KIND, company }, createdAt: new Date().toISOString() });
+            }
+            marker.registered[key] = new Date().toISOString();
+        }
+        writeLocalJobs(dir, jobs);
+        writeBuiltinJobsMarker(dir, marker);
+        return jobs.filter(job => job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND);
+    });
+}
+/** Only new locally extracted signals reach here; cloud upload/garden is separate. */
+export function emitExecutiveSignalWritten(hqRoot, company, payload, root = botsRoot(), home) {
+    if (!fs.existsSync(root))
+        return false;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        const config = readBotConfig(dir);
+        if (!config || typeof config.hqRoot !== "string" || path.resolve(config.hqRoot) !== path.resolve(hqRoot) || !isExecutiveBot(config, home))
+            continue;
+        if (!signalLaneCompanies(config).includes(company))
+            continue;
+        emitBotEvent(dir, "signal.written", { ...payload, company }, new Date(), prior => prior.event === "signal.written" && prior.payload.company === company && prior.payload.signal_id === payload.signal_id);
+        return true;
+    }
+    return false;
+}
+function publicationDir(hqRoot, company) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(company))
+        throw new Error("Invalid signal publication company");
+    return path.join(hqRoot, "workspace", "signal-publications", company);
+}
+/** Persist intent before publishing a new signal file; ordinary redo creates none. */
+export function prepareSignalPublication(hqRoot, company, payload) {
+    const dir = publicationDir(hqRoot, company);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, createHash("sha256").update(payload.signal_id).digest("hex") + ".json");
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(payload), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** A pre-append crash retries; a post-append crash uses the event journal's dedupe. */
+export function flushSignalPublications(hqRoot, company, emit = emitExecutiveSignalWritten) {
+    const dir = publicationDir(hqRoot, company);
+    if (!fs.existsSync(dir))
+        return;
+    for (const name of fs.readdirSync(dir).filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+        const file = path.join(dir, name);
+        let payload;
+        try {
+            payload = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
+            ["signal_id", "type", "source_ref", "audience_key", "origin"].some(key => typeof payload[key] !== "string")) {
+            throw new Error("Invalid signal publication intent");
+        }
+        try {
+            lookupSignal(hqRoot, company, payload.signal_id);
+        }
+        catch (error) {
+            if (isLanesError(error) && error.error === "signal_not_found")
+                continue;
+            throw error;
+        }
+        if (emit(hqRoot, company, payload)) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+}
+const createDefault = async (input) => {
+    // Load the CLI admission graph only when a signal actually needs a lane.
+    const { createLaneFromSignal } = await import("../../../commands/lanes.js");
+    return createLaneFromSignal(input);
+};
+export async function runSignalToLane(input) {
+    if (!isExecutiveBot(input.config, input.home))
+        return { status: "skipped-precondition", output: "Not the Executive" };
+    const payload = input.payload;
+    const company = input.company;
+    if (!payload || payload.type !== "action_item" || typeof payload.signal_id !== "string" || !payload.signal_id.trim() ||
+        typeof company !== "string" || payload.company !== company || !(input.companies ?? signalLaneCompanies(input.config)).includes(company)) {
+        return { status: "skipped-precondition", output: "Signal outside the served company or action-item scope" };
+    }
+    // Persist deferred IDs before acknowledging; the next matching event retries.
+    const file = path.join(input.dir, "signal-to-lane-pending.json");
+    const read = () => {
+        try {
+            const value = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value) ||
+                Object.values(value).some(ids => !Array.isArray(ids) || ids.some(id => typeof id !== "string"))) {
+                throw new Error("Invalid pending signal lane state");
+            }
+            return Object.assign(Object.create(null), value);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return Object.create(null);
+            throw err;
+        }
+    };
+    const update = (change) => withJobsLock(input.dir, () => {
+        const pending = read();
+        change(pending);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(pending), { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return pending;
+    });
+    const pending = update(p => { p[company] = [...new Set([...(p[company] ?? []), payload.signal_id])]; });
+    for (const signal_id of pending[company] ?? []) {
+        try {
+            const result = await (input.create ?? createDefault)({ hqRoot: input.config.hqRoot, company, signal_id });
+            input.log(JSON.stringify(result));
+            update(p => { p[company] = (p[company] ?? []).filter(id => id !== signal_id); });
+        }
+        catch (err) {
+            if (!isLanesError(err) || err.error !== "no_conductor_link")
+                throw err;
+            input.log(JSON.stringify({ error: "no_conductor_link", company, signal_id }));
+        }
+    }
+    return { status: "succeeded", output: "Signal lane processing finished; deferred signals retry on the next matching event" };
+}
+//# sourceMappingURL=signal-to-lane.js.map

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

@@ -23,7 +23,12 @@ export interface LocalJob {
     jobId: string;
     prompt: string;
     /** Standard 5-field cron, evaluated in `timezone`. */
-    cron: string;
+    cron?: string;
+    trigger?: {
+        kind: "event";
+        event: string;
+        filter?: Record<string, string>;
+    };
     timezone: string;
     context?: Record<string, unknown>;
     createdAt: string;
@@ -45,6 +50,12 @@ export interface LocalJob {
     runCount?: number;
 }
 export declare function readLocalJobs(dir: string): LocalJob[];
+/**
+ * `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.
+ */
+export declare function readLocalJobsStrict(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
@@ -74,9 +85,11 @@ export declare function parseCron(expr: string): CronMatcher | null;
 export declare function latestDueFire(job: LocalJob, now: Date): Date | null;
 /** The next time this job is due after `now`, within a week; null otherwise. */
 export declare function nextDueFire(job: LocalJob, now: Date): Date | null;
+export declare function toJobRecord(job: LocalJob, now?: Date): BotJobRecord;
 export declare function addLocalJob(dir: string, input: {
     prompt: string;
-    cron: string;
+    cron?: string;
+    trigger?: LocalJob["trigger"];
     timezone: string;
     context?: Record<string, unknown>;
 }, now?: Date): LocalJob;

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

@@ -22,6 +22,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { BotApiError } from "./api.js";
+import { ackBotEvent } from "./events.js";
 const LOCAL_JOBS_FILE = "jobs.json";
 const LOCAL_JOB_MESSAGE_PREFIX = "localjob-";
 /** How far back a missed fire is still looked for (one week). */
@@ -47,7 +48,7 @@ export function readLocalJobs(dir) {
  * 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) {
+export function readLocalJobsStrict(dir) {
     let text;
     try {
         text = fs.readFileSync(localJobsPath(dir), "utf8");
@@ -270,6 +271,8 @@ function scheduleOrigin(job) {
     return Date.parse(job.scheduledFrom ?? job.createdAt);
 }
 export function latestDueFire(job, now) {
+    if (job.trigger || !job.cron)
+        return null;
     const interval = rateIntervalMs(job.cron);
     if (interval) {
         const origin = scheduleOrigin(job);
@@ -294,6 +297,8 @@ export function latestDueFire(job, now) {
 }
 /** The next time this job is due after `now`, within a week; null otherwise. */
 export function nextDueFire(job, now) {
+    if (job.trigger || !job.cron)
+        return null;
     const interval = rateIntervalMs(job.cron);
     if (interval) {
         const origin = scheduleOrigin(job);
@@ -313,13 +318,13 @@ export function nextDueFire(job, now) {
     return null;
 }
 // ─── The job list (what `hq bot jobs` reads and writes) ──────────────────────
-function toJobRecord(job, now = new Date()) {
+export function toJobRecord(job, now = new Date()) {
     const next = nextDueFire(job, now);
     return {
         jobId: job.jobId,
         prompt: job.prompt,
         status: "active",
-        schedule: { kind: "recurring", cron: job.cron, timezone: job.timezone },
+        ...(job.trigger ? { trigger: job.trigger } : { schedule: { kind: "recurring", cron: job.cron, timezone: job.timezone } }),
         ...(job.context ? { context: job.context } : {}),
         createdAt: job.createdAt,
         ...(next ? { nextRunAt: next.toISOString() } : {}),
@@ -329,17 +334,24 @@ function toJobRecord(job, now = new Date()) {
     };
 }
 export function addLocalJob(dir, input, now = new Date()) {
-    if (!isRunnableSchedule(input.cron))
+    if (input.trigger && (!input.trigger.event.trim() || input.trigger.kind !== "event" || input.cron))
+        throw new Error("An event job needs an event and no cron schedule.");
+    if (!input.trigger && (!input.cron || !isRunnableSchedule(input.cron)))
         throw new Error(`"${input.cron}" is not a schedule this bot can run.`);
     const job = {
         jobId: `job_${randomUUID().replace(/-/g, "").slice(0, 20)}`,
         prompt: input.prompt,
-        cron: input.cron,
+        ...(input.trigger ? { trigger: input.trigger } : { cron: input.cron }),
         timezone: input.timezone,
         ...(input.context ? { context: input.context } : {}),
         createdAt: now.toISOString(),
     };
-    withJobsLock(dir, () => writeLocalJobs(dir, [...readLocalJobsForAdd(dir), job]));
+    withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        if (jobs.length >= MAX_LOCAL_JOBS)
+            throw new BotApiError(409, "local jobs", "JOB_QUOTA_EXCEEDED", `at most ${MAX_LOCAL_JOBS} jobs`);
+        writeLocalJobs(dir, [...jobs, job]);
+    });
     return job;
 }
 /**
@@ -350,7 +362,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 = readLocalJobsForAdd(dir);
+        const jobs = readLocalJobsStrict(dir);
         const existing = jobs.find(matches);
         if (existing)
             return { job: existing, created: false };
@@ -386,6 +398,7 @@ schedule, now = new Date()) {
             timezone: schedule.timezone ?? jobs[index].timezone,
             scheduledFrom: now.toISOString(),
         };
+        delete updated.trigger;
         jobs[index] = updated;
         writeLocalJobs(dir, jobs);
         return updated;
@@ -517,6 +530,10 @@ export function withLocalJobs(api, dir, clock = () => new Date()) {
         return [...cloud, ...takeDueLocalJobRuns(dir, clock())];
     };
     local.ackInbox = async (agentUid, messageId) => {
+        if (messageId.startsWith("localjob-event-")) {
+            ackBotEvent(dir, messageId);
+            return;
+        }
         if (isLocalJobMessage(messageId))
             return;
         await api.ackInbox(agentUid, messageId);

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

@@ -1,52 +1,3 @@
-/**
- * The resident bot process: `hq bot run <name>` (local-bots US-003/US-004).
- *
- * - pid lock in ~/.hq/bots/<name>/pid; status.json is the observable state
- * - refuses to start unless the creds file names this bot's agt_ AND the
- *   server-side record is owned by the configured owner
- * - heartbeat every 30s (POST /v1/agents/{uid}/heartbeat, agent JWT)
- * - inbox poll every 2s: DMs go to ONE headless model turn (resumed by
- *   session id); a new session (restart, or a resume id the runtime no longer
- *   has) is given the recent DM thread as a "Recent messages:" block so a
- *   one-word reply still has the question it answers; the reply is sent as
- *   the bot; the message is acked only after the reply is sent; processed ids
- *   persist so a crash between reply and ack never answers twice
- * - any correspondent can message the bot; each sender has a separate session
- * - first start only: the intro DM, then (when bot.json has `kickoff`) ONE
- *   model turn on that prompt as if the owner sent it, answered in the DM, so
- *   a guided bot starts working without waiting for the owner to type
- * - job items (channel "job"): a scheduled run, fired by the bot's own loop
- *   from its jobs.json (lib/bot/local-jobs.ts) or, for a hosted agent, by
- *   the cloud. No system scheduler is used on this computer. The run is one model turn
- *   in its own session (one per jobId), reported in the owner's DM with a
- *   "scheduled job" header through the same split/recovery path as every other
- *   reply, and reported back to the cloud EXACTLY ONCE — nothing else clears
- *   the job's in-progress flag. A run whose staleAfter has passed still runs,
- *   once, labelled a catch-up; older pending runs of the same job are reported
- *   skipped-precondition instead of piling up.
- * - delivered room items (channels / group chats) are eligible for replies; claimed
- *   first (first-claim-wins), one session per room, reply posted in the room
- * - conversations run side by side: up to MAX_PARALLEL_TURNS turns at once,
- *   one lane per model session (one DM correspondent, or one room). Messages
- *   in the same lane run in order, so a session is never resumed by two turns
- *   at once and a thread's answers never arrive out of sequence.
- * - while a turn runs, each finished assistant message is posted as its own
- *   message (progress.ts); turns have no time limit
- * - every received message gets a reply: a turn that fails after the model
- *   started (error, crash, owner stop, restart) posts one "did not finish"
- *   message and is NOT run again — it may already have done outward things.
- *   inflight.json marks the turn in progress so a restart can say so.
- * - a turn that fails because the coding tool's sign-in no longer works
- *   (runtime-sign-in.ts) is not a failure of the message: the bot says once
- *   per conversation that it needs a sign-in, keeps the message un-acked,
- *   holds new turns, and tries again every SIGN_IN_RETRY_MS (and at once
- *   after a restart). A turn that works clears it.
- * - failures before the model starts (missing binary) retry with backoff;
- *   5 model failures in 10 minutes → state `failed` and a clean exit (launchd
- *   does not respawn a clean exit). Owner stops never count.
- *
- * Everything with a side effect is injectable so the loop is unit-testable.
- */
 import { type OwnerContext } from "./owner-context.js";
 import { type BotApi, type InboxItem } from "./api.js";
 import type { BotConfig, BotKind } from "./config.js";
@@ -57,6 +8,7 @@ import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "
 import { type BotSessionScope } from "./paths.js";
 import { type DecisionDmClient } from "./decisions.js";
 import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
+import type { JobRunCompletion } from "./api.js";
 import { type RuntimeSignInCheck } from "./runtime-sign-in.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
@@ -325,6 +277,12 @@ export declare function inboxLaneKey(item: InboxItem, config: Pick<BotConfig, "o
  */
 export declare function dmTurnSessionScope(item: Pick<InboxItem, "fromPersonUid" | "text">, ownerUid: string): BotSessionScope;
 export declare function preflightCreds(dir: string, config: BotConfig): string | null;
+/** Register source-independent in-process jobs by their context.jobKind. */
+export declare const builtinEventHandlers: Record<string, (input: {
+    dir: string;
+    config: BotConfig;
+    item: InboxItem;
+}) => Promise<JobRunCompletion>>;
 export declare function runBot(deps: BotRunDeps): Promise<BotHandle>;
 /** True for a setup note the desktop app sent, not words the person typed. */
 export declare function isAppSetupNote(text: string): boolean;

package/dist/lib/bot/run.js

@@ -1,3 +1,4 @@
+import { ensureSignalToLaneJobs, runSignalToLane, SIGNAL_TO_LANE_JOB_KIND } from "./jobs/signal-to-lane.js";
 /**
  * The resident bot process: `hq bot run <name>` (local-bots US-003/US-004).
  *
@@ -47,6 +48,9 @@
  *
  * Everything with a side effect is injectable so the loop is unit-testable.
  */
+import { createMeetingRider, defaultMeetingRiderDeps, ensureMeetingRiderJob, MEETING_RIDER_JOB_KIND } from "./jobs/meeting-rider.js";
+import { executiveRiderEnabled, isExecutiveBot } from "./executive-settings.js";
+import { createMeetingDetect, defaultMeetingDetectDeps, resolveDetectedMeeting } from "./jobs/meeting-detect.js";
 import { botAuthEnv, describeBotAuth, formatBotAuth } from "./runtime-auth.js";
 import { ownerContextBlock } from "./owner-context.js";
 import { randomUUID } from "node:crypto";
@@ -86,6 +90,7 @@ import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOut
 import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
 import { currentHotSignalSyncCompany, hotSignalSyncJobCompany, readActiveCompanySlug, removeStaleHotSignalSyncJobs } from "./jobs/hot-signal-sync.js";
 import { isLocalJobMessage, isLocalJobRetryMessage, localJobRetryMessageId, readLocalJobs } from "./local-jobs.js";
+import { drainBotEvents } from "./events.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";
@@ -407,6 +412,8 @@ export function preflightCreds(dir, config) {
     }
     return null;
 }
+/** Register source-independent in-process jobs by their context.jobKind. */
+export const builtinEventHandlers = Object.create(null);
 export async function runBot(deps) {
     const now = deps.now ?? (() => new Date());
     const sleep = deps.sleep ?? defaultSleep;
@@ -414,6 +421,23 @@ export async function runBot(deps) {
     const log = deps.log ?? createBotLogger(deps.dir, now);
     const pid = deps.pid ?? process.pid;
     const { dir, config, api, runtime } = deps;
+    const meetingRider = createMeetingRider(defaultMeetingRiderDeps(config, dir, (message) => log("info", message)));
+    const meetingDetectDeps = defaultMeetingDetectDeps(config, dir, (message) => log("info", message));
+    const meetingDetect = createMeetingDetect(meetingDetectDeps);
+    const eventHandlers = Object.create(builtinEventHandlers);
+    eventHandlers[MEETING_RIDER_JOB_KIND] = async ({ item }) => {
+        if (!isExecutiveBot(config))
+            return { status: "skipped-precondition", output: "Not the Executive" };
+        if (!executiveRiderEnabled())
+            return { status: "skipped-precondition", output: "rider disabled" };
+        meetingRider.start(await resolveDetectedMeeting(config.hqRoot, typeof item.context === "object" ? item.context?.payload : undefined, meetingDetectDeps.list));
+        return { status: "succeeded", output: "Meeting rider accepted" };
+    };
+    eventHandlers[SIGNAL_TO_LANE_JOB_KIND] = async ({ item }) => runSignalToLane({
+        dir, config, payload: typeof item.context === "object" ? item.context?.payload : undefined,
+        company: typeof item.context === "object" ? item.context?.company : undefined,
+        log: message => log("info", message),
+    });
     const runTurn = deps.runTurn ?? ((rt, input) => runRuntimeTurn(rt, input));
     const inboxIntervalMs = deps.inboxIntervalMs ?? INBOX_POLL_INTERVAL_MS;
     const inboxPollBackoffEnabled = deps.inboxPollBackoffEnabled ?? createInboxPollBackoffFlagReader(config);
@@ -554,9 +578,13 @@ export async function runBot(deps) {
         ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
     });
     const finish = async (final, code, reason, beforeExit) => {
-        if (state === "stopped" || state === "failed")
+        if (state === "stopped" || state === "failed") {
+            await done;
             return;
+        }
         state = final;
+        await meetingDetect.stop();
+        await meetingRider.stop();
         closeInboxWakeWatcher();
         setStatus({ state: final, ...(final === "failed" ? { lastError: reason.slice(0, 400) } : {}) });
         log(final === "failed" ? "error" : "info", `bot ${final}: ${reason}`);
@@ -1031,6 +1059,8 @@ export async function runBot(deps) {
         activeInboxWait?.abort();
     };
     const waitForInbox = async (delayMs, adaptive, useMqttWake = false) => {
+        if (readLocalJobs(dir).some((job) => job.trigger))
+            delayMs = Math.min(delayMs, inboxIntervalMs);
         if (!adaptive) {
             await sleep(delayMs);
             return;
@@ -1040,9 +1070,14 @@ export async function runBot(deps) {
         while (remainingMs > 0 && !stopping && state === "running") {
             const controller = new AbortController();
             activeInboxWait = controller;
-            const chunkMs = useMqttWake ? remainingMs : Math.min(inboxIntervalMs, remainingMs);
+            const chunkMs = Math.min(inboxIntervalMs, remainingMs);
             if (useMqttWake) {
-                await getInboxWakeWatcher().wait(chunkMs, controller.signal);
+                const wake = await getInboxWakeWatcher().wait(chunkMs, controller.signal);
+                if (wake === "wake") {
+                    if (activeInboxWait === controller)
+                        activeInboxWait = null;
+                    return;
+                }
             }
             else {
                 await sleep(chunkMs, controller.signal);
@@ -1053,6 +1088,9 @@ export async function runBot(deps) {
                 break;
             if (hasPromotionHold(dir))
                 break;
+            // The first event job can be added while an otherwise idle bot waits.
+            if (readLocalJobs(dir).some((job) => job.trigger))
+                break;
             if (observedGeneration !== inboxWaitGeneration || controller.signal.aborted) {
                 observedGeneration = inboxWaitGeneration;
                 remainingMs = inboxIntervalMs;
@@ -2017,6 +2055,31 @@ export async function runBot(deps) {
         const id = item.messageId;
         const { job, jobId } = target;
         const peerUid = target.peerUid;
+        const eventHandler = item.messageId.startsWith("localjob-event-") && typeof job.context === "object" && typeof job.context?.jobKind === "string"
+            ? eventHandlers[job.context.jobKind] : undefined;
+        if (eventHandler) {
+            // Recoverable built-ins persist intent before acknowledging the event.
+            // Signal lane creation is idempotent, so a pre-ack crash can replay.
+            const durableEvent = typeof job.context === "object" && (job.context?.jobKind === MEETING_RIDER_JOB_KIND || job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND);
+            if (!durableEvent)
+                markProcessed(dir, id, now().toISOString());
+            let completion;
+            try {
+                completion = await eventHandler({ dir, config, item });
+                // Durable intent is stored before acknowledging; a pre-effect crash replays.
+                if (durableEvent)
+                    markProcessed(dir, id, now().toISOString());
+            }
+            catch (error) {
+                if (durableEvent)
+                    throw error;
+                completion = { status: "failed", output: error instanceof Error ? error.message : String(error) };
+            }
+            await completeJobRun(jobId, id, completion);
+            await api.ackInbox(config.agentUid, id);
+            log("info", `event job ${jobId} run ${id} ${completion.status}`);
+            return;
+        }
         // An older pending run of this job: a newer one runs instead. Reported so
         // the cloud releases the slot and the history says what happened.
         if (supersededJobRuns.has(id)) {
@@ -2821,6 +2884,21 @@ export async function runBot(deps) {
     // up below: end here, before the kickoff can send a "needs a sign-in" DM.
     if (stopping)
         return await stoppedDuringStartup();
+    try {
+        ensureSignalToLaneJobs(dir, config);
+    }
+    catch {
+        log("warn", "Signal-to-lane registration failed");
+    }
+    if (isExecutiveBot(config)) {
+        try {
+            if (ensureMeetingRiderJob(dir) && executiveRiderEnabled())
+                meetingRider.resume();
+        }
+        catch {
+            log("warn", "Meeting rider registration or recovery failed");
+        }
+    }
     // The kickoff runs alongside the heartbeat, before the first inbox poll, so
     // an owner message sent meanwhile is answered after it in the same session.
     const kickoff = kickoffAfterIntro
@@ -2937,6 +3015,14 @@ export async function runBot(deps) {
             kickCompletionRetries();
             // A failed signals run's automatic retry, once due (no model turn).
             enqueueDueSignalsRetries();
+            if (isExecutiveBot(config)) {
+                try {
+                    meetingDetect.tick();
+                }
+                catch {
+                    log("warn", "meeting detection settings unreadable");
+                }
+            }
             // Holding after repeated model failures: no inbox pulls until the
             // cooldown is over (the update watcher above keeps running meanwhile).
             if (modelHoldUntil > now().getTime()) {
@@ -2945,6 +3031,15 @@ export async function runBot(deps) {
             }
             if (modelHoldUntil)
                 liftModelHold();
+            // Local events are available even when the cloud inbox is unavailable.
+            try {
+                for (const item of drainBotEvents(dir))
+                    enqueue(item);
+                pump();
+            }
+            catch (error) {
+                log("warn", `event drain failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
             // While the tool says it is signed out, ask it again on a timer (cheap,
             // no turn): the moment it is signed in, the held messages run.
             if (signInIssue && busyLanes.size === 0 && now().getTime() >= nextSignInCheckAt) {
@@ -3002,7 +3097,8 @@ export async function runBot(deps) {
                 log("warn", `inbox poll failed: ${message}`);
                 if (stopping || state !== "running")
                     break;
-                await sleep(apiPollDelayMs({ err, attempt: inboxFails - 1, intervalMs: inboxIntervalMs, random }));
+                const retryDelay = apiPollDelayMs({ err, attempt: inboxFails - 1, intervalMs: inboxIntervalMs, random });
+                await sleep(readLocalJobs(dir).some((job) => job.trigger) ? Math.min(retryDelay, inboxIntervalMs) : retryDelay);
                 continue;
             }
             if (stopping || state !== "running")

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

@@ -85,8 +85,29 @@ export interface BotStatusFile {
     } | null;
     /** hq-cli version this process loaded (a bot keeps it until it restarts). */
     cliVersion?: string;
+    /**
+     * HQ Fleet Runtime bots: the last turn that ended in the canned away line,
+     * as the bot reported it to HQ and to the owner (written by the HQ DM
+     * adapter in hq-fleet-local).
+     */
+    lastFailure?: BotLastFailure;
     updatedAt: string;
 }
+export interface BotLastFailure {
+    at: string;
+    /** auth | billing | rate_limit | outage | runtime_error | generic */
+    class: string;
+    site?: string;
+    provider?: string | null;
+    /** Plain-language cause, as the owner was told. */
+    cause: string;
+    /** Plain-language fix, as the owner was told. */
+    fix: string;
+    /** The HQ failure report id, when the upload succeeded. */
+    reportId?: string | null;
+    uploaded?: boolean;
+    ownerNotified?: boolean;
+}
 export declare function defaultBotStatus(pid: number, runtime: BotRuntimeId, now?: () => Date): BotStatusFile;
 export declare function readBotStatus(dir: string): BotStatusFile | null;
 export declare function writeBotStatus(dir: string, status: BotStatusFile): void;

package/dist/lib/doctor/checks/bots.d.ts

@@ -1,3 +1,5 @@
+import { type ClaudeLoginCheck } from "../../bot/claude-login.js";
+import { type BotStatusFile } from "../../bot/status.js";
 import { type NodeBinaryIo } from "../../node-binary.js";
 import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
 export declare const BOTS_FAMILY_ID = "bots";
@@ -7,7 +9,11 @@ export interface BotsDoctorDeps {
     root: (home?: string) => string;
     /** Filesystem view used to judge the startup agent's node path (tests). */
     nodeIo?: NodeBinaryIo;
+    /** The Claude Code login read the way the HQ Fleet Runtime reads it (tests). */
+    claudeLogin?: () => ClaudeLoginCheck;
 }
+/** The last reported failure, unless a later turn worked. */
+export declare function unresolvedLastFailure(status: BotStatusFile | null): BotStatusFile["lastFailure"] | null;
 export declare const botsFamily: CheckFamily;
 export declare function checkBots(_context: CheckContext, deps?: BotsDoctorDeps): CheckResult[];
 //# sourceMappingURL=bots.d.ts.map