@indigoai-us/hq-cli 5.345.128 → 5.345.129

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.345.129] — 2026-10-14
+
+- Claude Remote Control account pools now stay connected across Claude CLI updates. The daemon still restarts a pool if its host exits, but no longer kills busy pool sessions after the two-hour update deadline.
+
+- The resident daemon now preloads the lane reconcile module that its in-process lane watcher loads. Main CI had been failing the resident preload coverage test since the idle-wakeup change (#1920).
+- Session-start health no longer files a stale personal sync-manifest warning (`sync.manifest.personal`) as an unrepaired problem after `hq doctor --fix`. `--fix` cannot upload personal manifests, so `hq doctor --json` and `--client-health-report` now omit that WARN the same way they omit the leftover personal-journal WARN. A FAIL on that row still shows, and plain `hq doctor` still prints the WARN.
+- Local bots now recover on their own when a saved Claude conversation no longer
+  exists. Before, every message in that chat failed with
+  `error_during_execution` until the bot's session file was removed by hand.
+- Fix mesh project ensure dropping PRD stories in the queued state. PRD files without a userStories array now fail before Board writes, and unsupported ledger states cannot produce a partial projection.
+- Idle local bots now wake from Work Mesh inbox notifications with a 60-second recovery pull. The daemon watches lane and child-handoff files, scans for sync processes only when its unit is missing, and leaves post-sync reindexing to compatible hq-cloud 6.18.75 or later runners.
+
 ## [5.345.128] — 2026-10-14
 - `hq auth refresh` now says which identity it ensured and where its token file is, for example `HQ session ensured (machine identity <name>; token file: <path>)` or `HQ session ensured (person session; token file: <path>)`. The identity is read after the refresh, so a fallback to the machine identity is reported as machine. Token values are never printed.
 - `hq auth refresh --json` prints `{refreshed, tokenSource, tokenFile, reason?}` on stdout and exits 1 when no session was refreshed.

package/dist/commands/core-bucket-c-work-mesh-offer-native.js

@@ -37,8 +37,14 @@ function cloudUid(root, company) {
         }
         if (inCompany && /^ {2}[^\s#]/.test(line))
             break;
-        if (inCompany && /^\s+cloud_uid:/.test(line))
-            return (line.split(":")[1] ?? "").trim().replace(/["']/g, "");
+        if (inCompany) {
+            // Match the shell's awk field contract: `$1 == "cloud_uid:"` and use
+            // only `$2`. A value must be separated from the key by whitespace;
+            // trailing comments and later fields do not become part of the UID.
+            const [key, value] = line.trim().split(/\s+/);
+            if (key === "cloud_uid:")
+                return (value ?? "").replace(/["']/g, "");
+        }
     }
     return "";
 }

package/dist/commands/daemon.js

@@ -907,6 +907,7 @@ async function runTmuxService(d, opts) {
             cwd: hqRoot,
             argv: opts.argv,
             label: opts.label,
+            restartOnToolUpdate: opts.restartOnToolUpdate,
             // Only a new version of the tool restarts the session: not a same-version
             // reinstall, and not an hq-cli release (the host's own code rarely matters).
             binaryFingerprint: () => toolFingerprint(opts.watch),
@@ -1094,6 +1095,7 @@ async function runServiceRemoteControlPoolHost(d, accountId) {
         argv: [claude, ...remoteControlPoolArgs(pool)],
         label: `claude remote-control pool ${accountId}`,
         watch: claude,
+        restartOnToolUpdate: false,
         signal: controller.signal,
         sessionEnv: {
             HOME: d.home,

package/dist/commands/lanes.js

@@ -24,6 +24,7 @@ export { resolveAnswerChoice } from "./lanes-questions.js";
 import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneKpisCommand } from "./lanes-kpis.js";
 import { registerLaneKeepAliveAuditCommand } from "./lanes-keep-alive-audit.js";
+import { finishReconcilePass } from "../lib/lanes/reconcile-result.js";
 import { registerLaneAutopilotReportCommand } from "./lanes-autopilot.js";
 import { registerLaneChecksCommand } from "./lanes-checks.js";
 import { registerLaneDropboxRepairCommand } from "./lanes-dropbox-repair.js";
@@ -41,6 +42,7 @@ import { runResidentCommandWithPackageLease } from "../utils/resident-package-pr
 import { codexEnvEvidence, grokEnvEvidence } from "../lib/doctor/platform.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff, readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
 import { readLaneStatusRowFields } from "../lib/lanes/status-fields.js";
+import { registerDaemonLanesReconcileHandler } from "../lib/lanes/daemon-reconcile.js";
 import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
 import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "../lib/lanes/flag-keys.js";
@@ -9538,21 +9540,21 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
         summary.errors.push({ code: error instanceof LanesError ? error.error : "lead_autopilot_failed", message });
         process.stderr.write(`hq lanes autopilot: ${message}\n`);
     }
-    printJson({
-        ...summary,
-        ...(autopilotRegistrySync ? { autopilot_registry_sync: autopilotRegistrySync } : {}),
-        ...(autopilot ? { autopilot } : {}),
-        ...(remoteLost.length > 0 ? { remote_lost: remoteLost } : {}),
-        ...(mirrorRefresh.unverifiedRemote.size > 0
-            ? {
-                unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()]
-                    .filter((id) => !terminalizedRemoteIds.has(id)),
-            }
-            : {}),
-    });
-    if (!summary.ok) {
-        process.exit(1);
+    if (!opts.inProcess) {
+        printJson({
+            ...summary,
+            ...(autopilotRegistrySync ? { autopilot_registry_sync: autopilotRegistrySync } : {}),
+            ...(autopilot ? { autopilot } : {}),
+            ...(remoteLost.length > 0 ? { remote_lost: remoteLost } : {}),
+            ...(mirrorRefresh.unverifiedRemote.size > 0
+                ? {
+                    unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()]
+                        .filter((id) => !terminalizedRemoteIds.has(id)),
+                }
+                : {}),
+        });
     }
+    finishReconcilePass(summary, opts.inProcess ? "daemon" : "cli");
 }
 async function runReconcileInstall(ctx, opts) {
     // `hq daemon` runs lanes-reconcile on this machine; a separate timer would run it twice.
@@ -9757,6 +9759,16 @@ export function registerLanesCommand(parent, deps = {}) {
         withResumeHireAdmission,
     };
     const messageHandlers = createLaneMessageHandlers(messageHandlerDeps);
+    const daemonReconcileCtx = { ...ctx, env: { ...ctx.env } };
+    registerDaemonLanesReconcileHandler(async () => {
+        const hqRoot = daemonReconcileCtx.hqRoot();
+        daemonReconcileCtx.env.HQ_ROOT = hqRoot;
+        daemonReconcileCtx.cwd = () => hqRoot;
+        daemonReconcileCtx.callerCwd = () => hqRoot;
+        await runReconcile(daemonReconcileCtx, { inProcess: true }, async (lane) => {
+            await messageHandlers.recoverQueuedMessages(daemonReconcileCtx, lane.lane_id);
+        });
+    });
     monitorLaneMessageApis.set(parent, (laneId, payload) => messageHandlers.deliverMonitorLaneMessage(ctx, laneId, payload));
     const resumeHandlers = createLaneResumeHandlers({
         onLaneWorkerStarted: deps.onLaneWorkerStarted,

package/dist/commands/mesh.js

@@ -307,16 +307,21 @@ function parseProjectReposJson(raw, source) {
         throw err;
     }
 }
-function projectStoriesFromJson(value, source) {
+function projectStoriesFromJson(value, source, options = {}) {
     const plan = Array.isArray(value) ? null : record(value);
-    const rawStories = Array.isArray(value)
-        ? value
-        : Array.isArray(plan?.userStories)
-            ? plan.userStories
-            : Array.isArray(plan?.stories)
-                ? plan.stories
-                : null;
-    if (!rawStories) {
+    if (options.requireUserStories && (!plan || !Array.isArray(plan.userStories))) {
+        fail(`${source} must be a PRD object with a userStories array.`);
+    }
+    const rawStories = options.requireUserStories
+        ? plan?.userStories ?? null
+        : Array.isArray(value)
+            ? value
+            : Array.isArray(plan?.userStories)
+                ? plan.userStories
+                : Array.isArray(plan?.stories)
+                    ? plan.stories
+                    : null;
+    if (!Array.isArray(rawStories)) {
         fail(`${source} must be a JSON story array or an object with userStories.`);
     }
     const rejectedStories = [];
@@ -398,7 +403,7 @@ function failProjectStoryStates(rejected, json) {
 }
 function parseProjectPlan(raw, source, options = {}) {
     try {
-        const plan = projectStoriesFromJson(JSON.parse(raw), source);
+        const plan = projectStoriesFromJson(JSON.parse(raw), source, options);
         if (plan.rejectedStories.length && !options.allowRejectedStories) {
             throw new RejectedProjectStoryStatesError(plan.rejectedStories);
         }
@@ -431,7 +436,7 @@ async function runProjectSet(projectId, opts) {
         fail("Pass only one of --repos-json or --repo.");
     }
     const source = opts.storiesFile
-        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile)
+        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true })
         : opts.storiesJson
             ? parseProjectPlan(opts.storiesJson, "--stories-json")
             : undefined;
@@ -588,12 +593,17 @@ async function runProjectMemberAdd(projectId, personUid, opts) {
 async function runProjectEnsure(projectId, opts) {
     if (!opts.storiesFile?.trim())
         fail("`--stories-file <prd.json>` is required.");
-    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
-    const { token, company } = await withCompany(opts);
-    if (source.rejectedStories.length && source.stories.length === 0) {
-        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+    let source;
+    try {
+        source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { requireUserStories: true });
+    }
+    catch (err) {
+        if (!(err instanceof RejectedProjectStoryStatesError) || !opts.json)
+            throw err;
+        failProjectStoryStates(err.rejected, true);
         return;
     }
+    const { token, company } = await withCompany(opts);
     let current;
     try {
         current = await getProjectView(token, company.companyUid, projectId);
@@ -738,7 +748,10 @@ async function runProjectEnsure(projectId, opts) {
 async function runProjectReconcile(projectId, opts) {
     if (!opts.storiesFile?.trim())
         fail("`--stories-file <prd.json>` is required.");
-    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, {
+        requireUserStories: true,
+        allowRejectedStories: true,
+    });
     const { token, company } = await withCompany(opts);
     let current;
     try {
@@ -852,7 +865,7 @@ async function runPrdSync(opts) {
             return;
         }
         try {
-            const source = parseProjectPlan(readFileSync(file, "utf8"), file);
+            const source = parseProjectPlan(readFileSync(file, "utf8"), file, { requireUserStories: true });
             await ensureMissingBoardStories({
                 token,
                 company: {
@@ -1091,7 +1104,7 @@ async function runBindProject(target, opts) {
         }
         if (!current.companyUid)
             fail(`Session ${sessionId} has no company. Bind a company first.`);
-        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath, { requireUserStories: true });
         const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
         await ensureProjectBoard({
             token,
@@ -1234,7 +1247,7 @@ async function runContextReconcile(opts) {
         validateMembership,
         ensureProjectBoard: token
             ? async ({ companyUid, projectId, prdPath }) => {
-                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath, { requireUserStories: true });
                 await ensureProjectBoard({
                     token,
                     company: { companyUid, companySlug: companyUid },

package/dist/lib/bot/inbox-poll-backoff-flag.d.ts

@@ -2,6 +2,8 @@ import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-c
 import { type BotConfig } from "./config.js";
 export declare const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
 export declare const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export declare const INBOX_MQTT_WAKE_FLAG = "agents.bot-inbox-mqtt-wake";
+export declare const INBOX_MQTT_WAKE_FLAG_FALLBACK = true;
 export declare const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 2000;
 export declare const INBOX_POLL_BACKOFF_FLAG_CACHE_MS: number;
 type InboxPollBackoffFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
@@ -14,11 +16,7 @@ export interface InboxPollBackoffFlagReaderDependencies {
     reportFailure?: (error: unknown) => void;
 }
 export declare function safeErrorClass(error: unknown): string;
-/**
- * Create a per-bot reader. The flag client is opened at most once per three
- * minutes; a missing identity, failed request, or malformed snapshot keeps
- * idle polling at its existing two-second interval.
- */
 export declare function createInboxPollBackoffFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
+export declare function createInboxMqttWakeFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
 export {};
 //# sourceMappingURL=inbox-poll-backoff-flag.d.ts.map

package/dist/lib/bot/inbox-poll-backoff-flag.js

@@ -5,6 +5,8 @@ import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
 import { effectiveBotCompanies, effectiveBotKind } from "./config.js";
 export const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
 export const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export const INBOX_MQTT_WAKE_FLAG = "agents.bot-inbox-mqtt-wake";
+export const INBOX_MQTT_WAKE_FLAG_FALLBACK = true;
 // One read every three minutes on a fresh connection. From a home network the
 // TCP and TLS handshakes plus the resolve call take about 250-400 ms, so a
 // 150 ms budget timed out on every read and kept the gate off.
@@ -15,8 +17,8 @@ export function safeErrorClass(error) {
     const name = error instanceof Error ? error.name : "UnknownError";
     return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
 }
-function reportFlagFailure(error) {
-    process.stderr.write(`HQ local bot inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+function reportFlagFailure(error, fallback) {
+    process.stderr.write(`HQ local bot inbox flag lookup failed (${safeErrorClass(error)}); using default ${fallback ? "on" : "off"}.\n`);
 }
 function companyContexts(config, env) {
     if (effectiveBotKind(config) !== "company")
@@ -44,9 +46,9 @@ function companyContexts(config, env) {
 /**
  * Create a per-bot reader. The flag client is opened at most once per three
  * minutes; a missing identity, failed request, or malformed snapshot keeps
- * idle polling at its existing two-second interval.
+ * registered fallback.
  */
-export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
+function createInboxFlagReader(config, flagKey, fallback, dependencies = {}) {
     const env = dependencies.env ?? process.env;
     const contexts = companyContexts(config, env);
     const endpoint = resolveFlagRegistryEndpoint(undefined, env);
@@ -54,15 +56,15 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
     const createClient = dependencies.createClient ?? createFlagClient;
     const getToken = dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? "");
     const doFetch = dependencies.fetch ?? globalThis.fetch;
-    const report = dependencies.reportFailure ?? reportFlagFailure;
-    let cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+    const report = dependencies.reportFailure ?? ((error) => reportFlagFailure(error, fallback));
+    let cachedValue = fallback;
     let lastReadAt = Number.NEGATIVE_INFINITY;
     let pending = null;
     const readContext = async (context) => {
         let client;
         let failed = false;
         let failureReported = false;
-        let enabled = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+        let enabled = fallback;
         const reportFailureOnce = (error) => {
             failed = true;
             if (failureReported)
@@ -84,7 +86,7 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
             });
             await client.ready();
             if (!failed) {
-                enabled = resolveFlagGate(client, INBOX_POLL_BACKOFF_FLAG, { fallback: INBOX_POLL_BACKOFF_FLAG_FALLBACK }, () => INBOX_POLL_BACKOFF_FLAG_FALLBACK);
+                enabled = resolveFlagGate(client, flagKey, { fallback }, () => fallback);
             }
         }
         catch (error) {
@@ -98,12 +100,12 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
                 reportFailureOnce(error);
             }
         }
-        return failed ? INBOX_POLL_BACKOFF_FLAG_FALLBACK : enabled;
+        return failed ? fallback : enabled;
     };
     const read = async () => {
         if (!contexts || contexts.length === 0) {
-            report(new Error("local bot inbox poll backoff flag has no resolvable company identity"));
-            return INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+            report(new Error("local bot inbox flag has no resolvable company identity"));
+            return fallback;
         }
         const values = await Promise.all(contexts.map(readContext));
         return values.every(Boolean);
@@ -123,7 +125,7 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
         })
             .catch((error) => {
             report(error);
-            cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+            cachedValue = fallback;
             return cachedValue;
         })
             .finally(() => {
@@ -132,4 +134,10 @@ export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
         return pending;
     };
 }
+export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
+    return createInboxFlagReader(config, INBOX_POLL_BACKOFF_FLAG, INBOX_POLL_BACKOFF_FLAG_FALLBACK, dependencies);
+}
+export function createInboxMqttWakeFlagReader(config, dependencies = {}) {
+    return createInboxFlagReader(config, INBOX_MQTT_WAKE_FLAG, INBOX_MQTT_WAKE_FLAG_FALLBACK, dependencies);
+}
 //# sourceMappingURL=inbox-poll-backoff-flag.js.map

package/dist/lib/bot/inbox-wake.d.ts

@@ -0,0 +1,18 @@
+import * as fs from "node:fs";
+export { AGENT_INBOX_PUSH_STATE_BASENAME } from "../mesh/live/paths.js";
+type WakeEvent = "wake" | "timeout" | "aborted";
+type Watcher = Pick<fs.FSWatcher, "close"> & {
+    on?: (event: "error", listener: (error: Error) => void) => unknown;
+};
+export interface InboxWakeWatcher {
+    wait(delayMs: number, signal?: AbortSignal): Promise<WakeEvent>;
+    isLiveFor?(agentUid: string): boolean;
+    close(): void;
+}
+/** Watches the content-free Work Mesh inbox sequence, with a bounded poll fallback. */
+export declare function createInboxWakeWatcher(root: string, options?: {
+    watch?: (root: string, listener: (event: string, filename: string | Buffer | null) => void) => Watcher;
+    onError?: (error: unknown) => void;
+    now?: () => number;
+}): InboxWakeWatcher;
+//# sourceMappingURL=inbox-wake.d.ts.map

package/dist/lib/bot/inbox-wake.js

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AGENT_INBOX_PUSH_STATE_BASENAME } from "../mesh/live/paths.js";
+export { AGENT_INBOX_PUSH_STATE_BASENAME } from "../mesh/live/paths.js";
+const INBOX_PUSH_SUBSCRIPTION_STALE_MS = 15_000;
+function readWakeState(root, onError) {
+    const target = path.join(root, AGENT_INBOX_PUSH_STATE_BASENAME);
+    try {
+        const info = fs.lstatSync(target);
+        if (!info.isFile() || info.isSymbolicLink())
+            return { wakeSequence: 0, connected: false, heartbeatAtMs: 0 };
+        const parsed = JSON.parse(fs.readFileSync(target, "utf8"));
+        return {
+            wakeSequence: Number.isSafeInteger(parsed.wakeSequence) && Number(parsed.wakeSequence) >= 0
+                ? Number(parsed.wakeSequence)
+                : 0,
+            connected: parsed.connected === true,
+            heartbeatAtMs: typeof parsed.heartbeatAtMs === "number" && Number.isFinite(parsed.heartbeatAtMs)
+                ? parsed.heartbeatAtMs
+                : 0,
+            ...(typeof parsed.agentUid === "string" ? { agentUid: parsed.agentUid } : {}),
+        };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            onError?.(error);
+        return { wakeSequence: 0, connected: false, heartbeatAtMs: 0 };
+    }
+}
+/** Watches the content-free Work Mesh inbox sequence, with a bounded poll fallback. */
+export function createInboxWakeWatcher(root, options = {}) {
+    const now = options.now ?? Date.now;
+    let lastState = readWakeState(root, options.onError);
+    let lastSequence = lastState.wakeSequence;
+    let closed = false;
+    let pendingWake = false;
+    const waiters = new Set();
+    let watcher;
+    const signalWake = () => {
+        pendingWake = waiters.size === 0;
+        for (const resolve of waiters)
+            resolve("wake");
+        waiters.clear();
+    };
+    try {
+        watcher = (options.watch ?? ((directory, listener) => fs.watch(directory, listener)))(root, (_event, filename) => {
+            if (filename !== null && filename.toString() !== AGENT_INBOX_PUSH_STATE_BASENAME)
+                return;
+            const nextState = readWakeState(root, options.onError);
+            const sequenceAdvanced = nextState.wakeSequence > lastSequence;
+            const subscriptionChanged = nextState.connected !== lastState.connected || nextState.agentUid !== lastState.agentUid;
+            lastState = nextState;
+            if (sequenceAdvanced) {
+                lastSequence = nextState.wakeSequence;
+                signalWake();
+            }
+            else if (subscriptionChanged) {
+                signalWake();
+            }
+        });
+        watcher.on?.("error", (error) => {
+            options.onError?.(error);
+            const failedWatcher = watcher;
+            watcher = undefined;
+            try {
+                failedWatcher?.close();
+            }
+            catch (closeError) {
+                options.onError?.(closeError);
+            }
+        });
+        // Close the read/register race: a writer can advance the sequence after
+        // the baseline read but before fs.watch is attached.
+        const currentState = readWakeState(root, options.onError);
+        if (currentState.wakeSequence > lastSequence) {
+            lastSequence = currentState.wakeSequence;
+            signalWake();
+        }
+    }
+    catch (error) {
+        options.onError?.(error);
+    }
+    return {
+        wait(delayMs, signal) {
+            if (closed || signal?.aborted)
+                return Promise.resolve("aborted");
+            if (pendingWake) {
+                pendingWake = false;
+                return Promise.resolve("wake");
+            }
+            return new Promise((resolve) => {
+                let settled = false;
+                const finish = (event) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    waiters.delete(finish);
+                    signal?.removeEventListener("abort", abort);
+                    resolve(event);
+                };
+                const abort = () => finish("aborted");
+                const timer = setTimeout(() => finish("timeout"), Math.max(0, delayMs));
+                waiters.add(finish);
+                signal?.addEventListener("abort", abort, { once: true });
+            });
+        },
+        isLiveFor(agentUid) {
+            const state = readWakeState(root, options.onError);
+            const ageMs = now() - state.heartbeatAtMs;
+            return state.connected && state.agentUid === agentUid &&
+                ageMs >= 0 && ageMs <= INBOX_PUSH_SUBSCRIPTION_STALE_MS;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            watcher?.close();
+            for (const resolve of waiters)
+                resolve("aborted");
+            waiters.clear();
+        },
+    };
+}
+//# sourceMappingURL=inbox-wake.js.map

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

@@ -58,7 +58,9 @@ import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js"
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
 import { type CliUpdate, type CliUpdateWatch } from "./cli-update.js";
+import { createInboxWakeWatcher } from "./inbox-wake.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
+export declare const INBOX_MQTT_WAKE_FALLBACK_MS = 60000;
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
 /** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
 export declare const API_BACKOFF_BASE_MS = 4000;
@@ -154,6 +156,12 @@ export interface BotRunDeps {
     signInRetryMs?: number;
     /** How long model turns are held after FAILURE_LIMIT failures in a window (default FAILURE_WINDOW_MS). */
     modelHoldMs?: number;
+    /** Kill-switch reader for the Work Mesh MQTT inbox wake path. */
+    inboxMqttWakeEnabled?: () => Promise<boolean>;
+    /** Work Mesh state directory; tests use a scratch directory. */
+    inboxWakeRoot?: string;
+    /** Test seam for the inbox wake source. */
+    createInboxWakeWatcher?: typeof createInboxWakeWatcher;
     /**
      * Downloads a chat attachment's bytes with the bot's own machine identity
      * (vault presign). Unset = attachments are listed with a "cannot download"

package/dist/lib/bot/run.js

@@ -89,8 +89,11 @@ import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 import { CLI_VERSION } from "../../cli-version.js";
 import { CLI_UPDATE_RESTART_EXIT_CODE } from "./cli-update.js";
-import { createInboxPollBackoffFlagReader, safeErrorClass } from "./inbox-poll-backoff-flag.js";
+import { createInboxMqttWakeFlagReader, createInboxPollBackoffFlagReader, safeErrorClass } from "./inbox-poll-backoff-flag.js";
+import { createInboxWakeWatcher } from "./inbox-wake.js";
+import { workMeshRoot } from "../mesh/live/paths.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
+export const INBOX_MQTT_WAKE_FALLBACK_MS = 60_000;
 export const HEARTBEAT_INTERVAL_MS = 30_000;
 /** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
 export const API_BACKOFF_BASE_MS = 4_000;
@@ -337,6 +340,21 @@ export async function runBot(deps) {
     const runTurn = deps.runTurn ?? ((rt, input) => runRuntimeTurn(rt, input));
     const inboxIntervalMs = deps.inboxIntervalMs ?? INBOX_POLL_INTERVAL_MS;
     const inboxPollBackoffEnabled = deps.inboxPollBackoffEnabled ?? createInboxPollBackoffFlagReader(config);
+    const inboxMqttWakeEnabled = deps.inboxMqttWakeEnabled ?? createInboxMqttWakeFlagReader(config);
+    const makeInboxWakeWatcher = deps.createInboxWakeWatcher ?? createInboxWakeWatcher;
+    const inboxWakeWatcherRef = { current: null };
+    const getInboxWakeWatcher = () => {
+        const watcher = inboxWakeWatcherRef.current ?? makeInboxWakeWatcher(deps.inboxWakeRoot ?? workMeshRoot(), {
+            onError: (error) => log("warn", `Work Mesh inbox wake unavailable (${safeErrorClass(error)}); retaining the fallback inbox poll`),
+        });
+        inboxWakeWatcherRef.current = watcher;
+        return watcher;
+    };
+    const closeInboxWakeWatcher = () => {
+        const watcher = inboxWakeWatcherRef.current;
+        watcher?.close();
+        inboxWakeWatcherRef.current = null;
+    };
     const jobQuietOptionEnabled = deps.jobQuietOptionEnabled ?? botJobQuietOptionEnabled;
     const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
     const exit = deps.exit ?? ((code) => process.exit(code));
@@ -443,6 +461,7 @@ export async function runBot(deps) {
         if (state === "stopped" || state === "failed")
             return;
         state = final;
+        closeInboxWakeWatcher();
         setStatus({ state: final, ...(final === "failed" ? { lastError: reason.slice(0, 400) } : {}) });
         log(final === "failed" ? "error" : "info", `bot ${final}: ${reason}`);
         if (!deps.skipPidLock)
@@ -771,7 +790,7 @@ export async function runBot(deps) {
         inboxWaitGeneration += 1;
         activeInboxWait?.abort();
     };
-    const waitForInbox = async (delayMs, adaptive) => {
+    const waitForInbox = async (delayMs, adaptive, useMqttWake = false) => {
         if (!adaptive) {
             await sleep(delayMs);
             return;
@@ -781,8 +800,13 @@ export async function runBot(deps) {
         while (remainingMs > 0 && !stopping && state === "running") {
             const controller = new AbortController();
             activeInboxWait = controller;
-            const chunkMs = Math.min(inboxIntervalMs, remainingMs);
-            await sleep(chunkMs, controller.signal);
+            const chunkMs = useMqttWake ? remainingMs : Math.min(inboxIntervalMs, remainingMs);
+            if (useMqttWake) {
+                await getInboxWakeWatcher().wait(chunkMs, controller.signal);
+            }
+            else {
+                await sleep(chunkMs, controller.signal);
+            }
             if (activeInboxWait === controller)
                 activeInboxWait = null;
             if (stopping || state !== "running")
@@ -795,9 +819,8 @@ export async function runBot(deps) {
                 continue;
             }
             remainingMs -= chunkMs;
-            // Keep the install watcher at its original two-second cadence even when
-            // the inbox itself is waiting longer between empty polls.
-            if (remainingMs > 0 && pollForCliUpdate())
+            // The MQTT wake or bounded fallback also checks for CLI updates.
+            if (remainingMs > 0 && !useMqttWake && pollForCliUpdate())
                 break;
         }
     };
@@ -2332,6 +2355,18 @@ export async function runBot(deps) {
                 log("warn", `inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default-off`);
                 return false;
             });
+            const useMqttWake = await inboxMqttWakeEnabled().catch((error) => {
+                log("warn", `inbox MQTT wake flag lookup failed (${safeErrorClass(error)}); using default-on`);
+                return true;
+            });
+            // Arm before pulling so a wake arriving between the pull and wait is not
+            // lost. The watcher also checks the sequence again after registration.
+            if (useMqttWake) {
+                getInboxWakeWatcher();
+            }
+            else {
+                closeInboxWakeWatcher();
+            }
             let items;
             try {
                 items = await api.pullInbox(config.agentUid);
@@ -2361,6 +2396,15 @@ export async function runBot(deps) {
             }
             if (stopping || state !== "running")
                 break;
+            if (useMqttWake) {
+                const hasLiveInboxSubscription = items.length === 0 &&
+                    getInboxWakeWatcher().isLiveFor?.(config.agentUid) === true;
+                const delayMs = items.length > 0 || !hasLiveInboxSubscription
+                    ? inboxIntervalMs
+                    : INBOX_MQTT_WAKE_FALLBACK_MS;
+                await waitForInbox(delayMs, true, true);
+                continue;
+            }
             if (!useInboxBackoff) {
                 inboxBackoffIndex = 0;
                 await waitForInbox(inboxIntervalMs, false);