@indigoai-us/hq-cli 5.345.128 → 5.345.130

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);

package/dist/lib/bot/runtime/messages-stream.js

@@ -87,7 +87,7 @@ export function messagesStreamResult(stdout, runtimeName) {
     if (!sawJson)
         throw new RuntimeError(`${runtimeName} returned non-JSON output`, stdout.trim().slice(-400), null, { excerptIsOutputTail: true });
     if (result?.is_error === true) {
-        const detail = typeof result.result === "string" && result.result ? result.result : String(result.subtype ?? "error");
+        const detail = typeof result.result === "string" && result.result ? result.result : (resultErrors(result) ?? String(result.subtype ?? "error"));
         throw new RuntimeError(`${runtimeName} reported an error: ${detail.slice(0, 200)}`, detail.slice(0, 400), null);
     }
     const text = (typeof result?.result === "string" && result.result.trim() ? result.result : lastText) ?? "";
@@ -143,8 +143,12 @@ export function messagesStreamFailure(stdout) {
     let reason;
     for (const line of stdout.split("\n")) {
         const ev = parseJsonLine(line);
-        if (ev?.type === "result" && ev.is_error === true && typeof ev.result === "string" && ev.result.trim())
-            reason = ev.result.trim();
+        if (ev?.type === "result" && ev.is_error === true) {
+            if (typeof ev.result === "string" && ev.result.trim())
+                reason = ev.result.trim();
+            else
+                reason = resultErrors(ev) ?? reason;
+        }
         if (ev?.type === "error" && typeof ev.message === "string" && ev.message.trim())
             reason = ev.message.trim();
     }
@@ -187,8 +191,32 @@ export function prettyJsonFailure(stdout) {
         return ev.result.trim();
     if (typeof ev.message === "string" && ev.message.trim())
         return ev.message.trim();
+    const errors = resultErrors(ev);
+    if (errors)
+        return errors;
     if (typeof ev.subtype === "string" && ev.subtype.trim() && ev.subtype !== "success")
         return ev.subtype.trim();
     return undefined;
 }
+/**
+ * The `errors` array on a Claude result envelope. A failed `--resume` ends
+ * with `{"subtype":"error_during_execution","is_error":true,"errors":["No
+ * conversation found with session ID: …"]}` and no `result` text; without
+ * this the failure reads as the bare subtype, the stale-session check never
+ * matches, and every turn on that scope fails the same way.
+ */
+function resultErrors(ev) {
+    if (!Array.isArray(ev.errors))
+        return undefined;
+    const parts = ev.errors.flatMap((e) => {
+        if (typeof e === "string")
+            return e.trim() ? [e.trim()] : [];
+        if (e && typeof e === "object" && typeof e.message === "string") {
+            const m = e.message.trim();
+            return m ? [m] : [];
+        }
+        return [];
+    });
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
 //# sourceMappingURL=messages-stream.js.map

package/dist/lib/core-utils/workflow-runner-schema.d.ts

@@ -0,0 +1,7 @@
+/** Port of pipeline-envelope.sh normalize, including its candidate selection rules. */
+export declare function normalizeWorkflowRunnerEnvelope(raw: string): string;
+/** Makes a copy in Codex's strict structured-output dialect. */
+export declare function strictifySchemaForCodex(schema: unknown): unknown;
+/** Removes nulls that Codex had to add for originally optional properties. */
+export declare function stripStrictNulls(value: unknown, schema: unknown): unknown;
+//# sourceMappingURL=workflow-runner-schema.d.ts.map

package/dist/lib/core-utils/workflow-runner-schema.js

@@ -0,0 +1,259 @@
+function isJsonObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function jsonDumps(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(jsonDumps).join(", ")}]`;
+    const entries = Object.entries(value);
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}: ${jsonDumps(child)}`).join(", ")}}`;
+}
+function balancedJsonEnd(text, start) {
+    let depth = 0;
+    let inString = false;
+    for (let i = start; i < text.length; i += 1) {
+        const char = text[i];
+        if (inString) {
+            if (char === "\\")
+                i += 1;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "{" || char === "[")
+            depth += 1;
+        else if (char === "}" || char === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return i + 1;
+            if (depth < 0)
+                return -1;
+        }
+    }
+    return -1;
+}
+/** Port of pipeline-envelope.sh normalize, including its candidate selection rules. */
+export function normalizeWorkflowRunnerEnvelope(raw) {
+    const text = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+    const candidates = [];
+    const fence = /```[A-Za-z0-9_-]*\s*\n([\s\S]*?)```/g;
+    let match;
+    while ((match = fence.exec(text)) !== null) {
+        try {
+            const parsed = JSON.parse(match[1]?.trim() ?? "");
+            if (isJsonObject(parsed))
+                candidates.push(parsed);
+        }
+        catch { /* malformed fences are skipped by the shell normalizer */ }
+    }
+    if (candidates.length === 0) {
+        let offset = 0;
+        while (offset < text.length) {
+            const start = text.indexOf("{", offset);
+            if (start < 0)
+                break;
+            const end = balancedJsonEnd(text, start);
+            if (end > 0) {
+                try {
+                    const parsed = JSON.parse(text.slice(start, end));
+                    if (isJsonObject(parsed))
+                        candidates.push(parsed);
+                    offset = end;
+                    continue;
+                }
+                catch { /* continue scanning after this opening brace */ }
+            }
+            offset = start + 1;
+        }
+    }
+    if (candidates.length === 0)
+        throw new Error("normalize: no JSON object found");
+    if (candidates.length > 1) {
+        const tagged = candidates.filter((candidate) => candidate.schema === "hq-phase-handoff/v1" || candidate.schema === "hq-phase-envelope/v1");
+        if (tagged.length !== 1)
+            throw new Error(`normalize: ${candidates.length} JSON objects found, expected exactly one`);
+        return `${jsonDumps(tagged[0])}\n`;
+    }
+    return `${jsonDumps(candidates[0])}\n`;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function typesOf(node) {
+    if (node.type === undefined)
+        return [];
+    return Array.isArray(node.type) ? [...node.type] : [node.type];
+}
+function isObjectNode(node) {
+    const types = typesOf(node);
+    return types.length ? types.includes("object") : isRecord(node.properties);
+}
+const MAP_KEYS = ["properties", "$defs", "definitions"];
+const LIST_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"];
+const SINGLE_KEYS = ["items", "not", "if", "then", "else", "contains", "propertyNames"];
+function schemaError(at, message) {
+    return new Error(`codex output schema at ${at}: ${message}`);
+}
+function widenToNullable(node, at) {
+    if (!isRecord(node))
+        return;
+    const types = typesOf(node);
+    if (types.length) {
+        if (!types.includes("null"))
+            node.type = [...types, "null"];
+        if (Array.isArray(node.enum) && !node.enum.includes(null))
+            node.enum = [...node.enum, null];
+        return;
+    }
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = node[key];
+        if (!Array.isArray(branches) || branches.length === 0)
+            continue;
+        if (!branches.some((branch) => isRecord(branch) && typesOf(branch).includes("null")))
+            branches.push({ type: "null" });
+        return;
+    }
+    if (typeof node.$ref === "string" || Array.isArray(node.allOf)) {
+        const inner = { ...node };
+        for (const key of Object.keys(node))
+            delete node[key];
+        node.anyOf = [inner, { type: "null" }];
+        return;
+    }
+    if (isRecord(node.properties)) {
+        node.type = ["object", "null"];
+        return;
+    }
+    throw schemaError(at, "this property is optional (absent from `required`) but its schema declares neither a type nor a composition, so there is no way to express \"no answer\" in the strict dialect. Give it a type, or list it in `required`.");
+}
+function strictifyInPlace(node, at) {
+    if (Array.isArray(node)) {
+        node.forEach((child, index) => strictifyInPlace(child, `${at}[${index}]`));
+        return node;
+    }
+    if (!isRecord(node))
+        return node;
+    for (const key of MAP_KEYS) {
+        if (!isRecord(node[key]))
+            continue;
+        for (const [name, child] of Object.entries(node[key]))
+            strictifyInPlace(child, `${at}.${key}.${name}`);
+    }
+    for (const key of LIST_KEYS) {
+        if (Array.isArray(node[key]))
+            node[key].forEach((child, index) => strictifyInPlace(child, `${at}.${key}[${index}]`));
+    }
+    for (const key of SINGLE_KEYS)
+        if (node[key] !== undefined)
+            strictifyInPlace(node[key], `${at}.${key}`);
+    if (!isObjectNode(node))
+        return node;
+    if (node.additionalProperties !== undefined && node.additionalProperties !== false) {
+        throw schemaError(at, "strict structured output permits no dynamic keys, so `additionalProperties` must be false (got "
+            + `${JSON.stringify(node.additionalProperties)}). Model a map as an array of {key, value} entries, or run this agent on the grok or claude engine, which have no strict-schema flag.`);
+    }
+    node.additionalProperties = false;
+    if (typesOf(node).length === 0)
+        node.type = "object";
+    const props = isRecord(node.properties) ? node.properties : null;
+    if (!props)
+        return node;
+    const keys = Object.keys(props);
+    const declared = Array.isArray(node.required) ? node.required.filter((key) => typeof key === "string") : [];
+    const orphans = declared.filter((key) => !keys.includes(key));
+    if (orphans.length)
+        throw schemaError(at, `\`required\` lists ${orphans.map((key) => JSON.stringify(key)).join(", ")} with no matching property. Strict rejects a required name that is not in \`properties\`, and dropping it would leave the result validator demanding a key the model can no longer emit. Add the property, or remove the name from \`required\`.`);
+    const required = [];
+    for (const key of declared)
+        if (!required.includes(key))
+            required.push(key);
+    for (const key of keys) {
+        if (required.includes(key))
+            continue;
+        widenToNullable(props[key], `${at}.properties.${key}`);
+        required.push(key);
+    }
+    node.required = required;
+    return node;
+}
+/** Makes a copy in Codex's strict structured-output dialect. */
+export function strictifySchemaForCodex(schema) {
+    if (!isRecord(schema) && !Array.isArray(schema))
+        return schema;
+    return strictifyInPlace(JSON.parse(JSON.stringify(schema)), "<root>");
+}
+const MAX_REF_DEPTH = 16;
+function resolveRef(node, root, depth = 0) {
+    if (!isRecord(node) || typeof node.$ref !== "string" || depth >= MAX_REF_DEPTH || !isRecord(root))
+        return node;
+    const match = /^#\/(\$defs|definitions)\/([^/]+)$/.exec(node.$ref);
+    if (!match)
+        return node;
+    const bucket = root[match[1] ?? ""];
+    const target = isRecord(bucket) ? bucket[match[2] ?? ""] : undefined;
+    return isRecord(target) ? resolveRef(target, root, depth + 1) : node;
+}
+function allowsNull(node, root, depth = 0) {
+    const resolved = resolveRef(node, root, depth);
+    if (!isRecord(resolved))
+        return true;
+    const types = typesOf(resolved);
+    if (types.length)
+        return types.includes("null");
+    for (const key of ["anyOf", "oneOf"]) {
+        if (Array.isArray(resolved[key]))
+            return resolved[key].some((branch) => depth < MAX_REF_DEPTH && allowsNull(branch, root, depth + 1));
+    }
+    return isRecord(resolved.properties) ? false : true;
+}
+function effectiveSchema(node, root, depth = 0) {
+    const resolved = resolveRef(node, root, depth);
+    if (!isRecord(resolved))
+        return null;
+    for (const key of ["anyOf", "oneOf"]) {
+        if (!Array.isArray(resolved[key]))
+            continue;
+        const branches = resolved[key].map((branch) => resolveRef(branch, root, depth + 1))
+            .filter(isRecord).filter((branch) => !(typesOf(branch).length === 1 && typesOf(branch)[0] === "null"));
+        if (branches.length !== 1 || depth >= MAX_REF_DEPTH)
+            return null;
+        return effectiveSchema(branches[0], root, depth + 1);
+    }
+    return resolved;
+}
+function stripInPlace(value, schema, root, depth = 0) {
+    const effective = effectiveSchema(schema, root, depth);
+    if (!effective)
+        return value;
+    if (Array.isArray(value)) {
+        if (effective.items !== undefined)
+            value.forEach((item) => stripInPlace(item, effective.items, root, depth + 1));
+        return value;
+    }
+    if (!isRecord(value))
+        return value;
+    const props = isRecord(effective.properties) ? effective.properties : null;
+    if (!props)
+        return value;
+    const required = Array.isArray(effective.required) ? effective.required : [];
+    for (const [key, sub] of Object.entries(props)) {
+        if (!(key in value))
+            continue;
+        if (value[key] === null && !required.includes(key) && !allowsNull(sub, root)) {
+            delete value[key];
+            continue;
+        }
+        stripInPlace(value[key], sub, root, depth + 1);
+    }
+    return value;
+}
+/** Removes nulls that Codex had to add for originally optional properties. */
+export function stripStrictNulls(value, schema) {
+    if (!isRecord(schema) || value === null || typeof value !== "object")
+        return value;
+    return stripInPlace(JSON.parse(JSON.stringify(value)), schema, schema);
+}
+//# sourceMappingURL=workflow-runner-schema.js.map

package/dist/lib/daemon/catalog.d.ts

@@ -109,6 +109,10 @@ export interface PlanContext {
     syncRunnerProcesses: readonly SyncRunnerProcess[] | null;
     /** PID recorded in the watch-owner status, when it is readable. */
     syncRunnerOwnerPid: number | null;
+    /** The daemon's in-process lane watcher owns reconcile while its kill switch is on. */
+    lanesReconcileInProcess?: boolean;
+    /** The active hq-cloud sync runner owns post-sync QMD indexing. */
+    searchIndexOwnedBySyncRunner?: boolean;
     /** Sync runner children already started by this daemon before their lease is written. */
     daemonSyncRunnerPids?: ReadonlySet<number>;
     /** The protocol-event heartbeat watchdog timeout for the sync runner. */

package/dist/lib/daemon/catalog.js

@@ -227,14 +227,15 @@ function planService(service, ctx) {
                 }),
             ];
         case "lanes-reconcile":
+            if (ctx.lanesReconcileInProcess)
+                return [];
             return [
                 base(service, {
                     kind: "scheduled",
                     // Polls every 15 s so local keep-alive resumes are admitted on time (#1396).
                     // Each pass is a fresh `hq` node process (~1.8 s CPU, ~200 MB RSS), so
-                    // desktops first check the lane store in-process
-                    // (lanes-reconcile-guard.ts) and fall back to the pre-#1396 60 s
-                    // cadence, or no run, when no lane can need the 15 s poll.
+                    // desktops reconcile in-process on lane-store changes with a bounded
+                    // timer for due keep-alive work, avoiding a fresh CLI process per poll.
                     intervalSec: 15,
                     initialDelaySec: 30,
                     command: { type: "hq", args: ["lanes", "reconcile"] },
@@ -246,6 +247,8 @@ function planService(service, ctx) {
                 }),
             ];
         case "search-index":
+            if (ctx.searchIndexOwnedBySyncRunner)
+                return [];
             return [
                 base(service, {
                     kind: "scheduled",

package/dist/lib/daemon/flag-monitor.d.ts

@@ -1,5 +1,7 @@
 export interface BoundedDaemonFlagMonitorOptions {
     read: () => Promise<boolean>;
+    /** Registry default, also used for absent rows and stale reads. */
+    fallback?: boolean;
     now?: () => number;
     onChange?: (enabled: boolean) => void;
     onReadError?: (error: unknown) => void;
@@ -15,7 +17,8 @@ export interface BoundedDaemonFlagMonitor {
 }
 /**
  * Refreshes a long-running daemon's flag independently of incoming requests.
- * A failed read keeps the last successful decision only until its 60s age limit.
+ * A failed read keeps a default-off setting only until its 60s age limit; a
+ * default-on kill switch immediately returns to its registered safe default.
  */
 export declare function createBoundedDaemonFlagMonitor(options: BoundedDaemonFlagMonitorOptions): BoundedDaemonFlagMonitor;
 //# sourceMappingURL=flag-monitor.d.ts.map

package/dist/lib/daemon/flag-monitor.js

@@ -3,11 +3,13 @@ const HQ_ANYWHERE_FLAG_REFRESH_INTERVAL_MS = 30_000;
 const HQ_ANYWHERE_FLAG_MAX_STALENESS_MS = 60_000;
 /**
  * Refreshes a long-running daemon's flag independently of incoming requests.
- * A failed read keeps the last successful decision only until its 60s age limit.
+ * A failed read keeps a default-off setting only until its 60s age limit; a
+ * default-on kill switch immediately returns to its registered safe default.
  */
 export function createBoundedDaemonFlagMonitor(options) {
     const now = options.now ?? (() => performance.now());
-    let value;
+    const fallback = options.fallback ?? false;
+    let value = fallback ? true : undefined;
     let lastSuccessAt;
     let lastAttemptAt;
     let lastReadFailed = false;
@@ -23,7 +25,7 @@ export function createBoundedDaemonFlagMonitor(options) {
     };
     const expireIfStale = () => {
         if (!closed && lastSuccessAt !== undefined && now() - lastSuccessAt >= HQ_ANYWHERE_FLAG_MAX_STALENESS_MS) {
-            publish(false);
+            publish(fallback);
         }
     };
     const refresh = () => {
@@ -44,13 +46,17 @@ export function createBoundedDaemonFlagMonitor(options) {
             // Expire from the elapsed timer itself, not a wall-clock comparison.
             expiryTimer = setTimeout(() => {
                 if (!closed && successVersion === thisSuccessVersion)
-                    publish(false);
+                    publish(fallback);
             }, HQ_ANYWHERE_FLAG_MAX_STALENESS_MS);
             expiryTimer.unref?.();
             return next;
         }).catch((error) => {
             lastReadFailed = true;
             options.onReadError?.(error);
+            if (fallback) {
+                publish(true);
+                return true;
+            }
             expireIfStale();
             return value ?? false;
         }).finally(() => {
@@ -69,7 +75,7 @@ export function createBoundedDaemonFlagMonitor(options) {
             expireIfStale();
             if (lastSuccessAt !== undefined && now() - lastSuccessAt >= HQ_ANYWHERE_FLAG_MAX_STALENESS_MS) {
                 void refresh();
-                return false;
+                return fallback;
             }
             if (value === undefined)
                 return refresh();
@@ -82,7 +88,7 @@ export function createBoundedDaemonFlagMonitor(options) {
             const age = lastSuccessAt === undefined ? null : Math.max(0, now() - lastSuccessAt);
             const fresh = age !== null && age < HQ_ANYWHERE_FLAG_MAX_STALENESS_MS;
             return {
-                enabled: value === true && fresh,
+                enabled: value === true && (fresh || fallback),
                 lastSuccessfulReadAgeMs: age,
                 heldThroughReadError: lastReadFailed && fresh,
             };

package/dist/lib/daemon/flag.d.ts

@@ -17,6 +17,8 @@ export interface DaemonFlagClient {
 }
 export interface ReadDaemonFlagOptions {
     env?: NodeJS.ProcessEnv;
+    /** Registry default for this key; new kill switches use true. */
+    fallback?: boolean;
     /** Controls how this read combines a local person setting with the registry value. */
     localOverrideMode?: "respect" | "off-only" | "ignore";
     createClient?: (options: FlagClientOptions) => DaemonFlagClient;

package/dist/lib/daemon/flag.js

@@ -17,7 +17,7 @@ export async function readDaemonFlag(flagKey, options = {}) {
     const env = options.env ?? process.env;
     if (flagKey === HQ_ANYWHERE_RUNTIME_FLAG && hqAnywhereRuntimeLocallyDisabled(env))
         return false;
-    const fallback = flagKey === HQ_ANYWHERE_RUNTIME_FLAG;
+    const fallback = options.fallback ?? flagKey === HQ_ANYWHERE_RUNTIME_FLAG;
     const override = readLocalOverride(flagKey, env);
     const localOverrideMode = options.localOverrideMode ?? "respect";
     if (override !== null && (localOverrideMode === "respect" || (localOverrideMode === "off-only" && !override)))
@@ -53,8 +53,11 @@ export async function readDaemonFlag(flagKey, options = {}) {
             onError(error);
         }
         const resolution = client.explain(flagKey, { fallback });
-        if (failed && options.throwOnError && !fallback) {
-            throw new Error("hq-flags registry read failed", { cause: reportedError });
+        if (failed) {
+            if (options.throwOnError && !fallback) {
+                throw new Error("hq-flags registry read failed", { cause: reportedError });
+            }
+            return fallback;
         }
         if (resolution.source === "snapshot")
             return resolution.value === true;
@@ -63,8 +66,11 @@ export async function readDaemonFlag(flagKey, options = {}) {
     catch (error) {
         if (!failed)
             onError(error);
-        if (options.throwOnError && failed && !fallback) {
-            throw new Error("hq-flags registry read failed", { cause: reportedError ?? error });
+        if (failed) {
+            if (options.throwOnError && !fallback) {
+                throw new Error("hq-flags registry read failed", { cause: reportedError ?? error });
+            }
+            return fallback;
         }
         return fallback;
     }