@indigoai-us/hq-cli 5.345.86 → 5.345.88

package/dist/lib/bot/lock.js

@@ -0,0 +1,313 @@
+/**
+ * One writer per bot at a time.
+ *
+ * `hq bot create`, `adopt`, `restore`, `rm` and `set` all change the same
+ * bot's folder, and an adopt also rotates the bot's machine secret. Two of
+ * them running at once for the same bot (the desktop's automatic restore and
+ * its first-run create, a minute after sign-in) used to race on a
+ * check-then-write of bot.json: the loser either threw "already set up on this
+ * computer" or, worse, wrote a credential the winner had already rotated away.
+ *
+ * The lock is a file under the bots folder, `~/.hq/bots/.locks/<name>.lock`,
+ * created with O_CREAT|O_EXCL. It sits beside the bot's folder rather than in
+ * it: a folder that exists only to hold a lock would read as "a different bot
+ * already has this name" to the code that picks a restored bot's folder, and
+ * as "something is left here" to `hq bot rm`. Its body names the holder (pid,
+ * host, start time, a random token), so:
+ *   - a holder whose process is gone, or that has held it for longer than
+ *     {@link BOT_LOCK_STALE_MS}, is reclaimed;
+ *   - release only removes the lock it took (the token must match), so a
+ *     reclaim by another process never makes this process remove someone
+ *     else's lock.
+ *
+ * The lock is re-entrant within one async call chain (AsyncLocalStorage):
+ * create holds it and calls the shared adopt path, which takes it again
+ * without waiting on itself. Two separate chains in one process still
+ * serialize, exactly like two processes.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { botsRoot } from "./paths.js";
+/** Not a valid bot name (it starts with a dot), so no bot can collide with it. */
+export const BOT_LOCKS_DIRNAME = ".locks";
+/** A holder older than this is treated as crashed, whatever its pid says. */
+export const BOT_LOCK_STALE_MS = 10 * 60 * 1000;
+/** How long a second writer waits for the first before giving up. */
+export const BOT_LOCK_WAIT_MS = 3 * 60 * 1000;
+/** A lock file with no readable body yet: its creator may still be writing it. */
+const UNREADABLE_GRACE_MS = 5_000;
+export class BotLockBusyError extends Error {
+    botName;
+    holder;
+    expected = true;
+    constructor(botName, holder) {
+        super(`Another hq bot command is changing "${botName}" right now${holder?.command ? ` (${holder.command})` : ""}. Try again in a moment.`);
+        this.botName = botName;
+        this.holder = holder;
+        this.name = "BotLockBusyError";
+    }
+}
+export function botLockPath(name, root) {
+    return path.join(root ?? botsRoot(), BOT_LOCKS_DIRNAME, `${name}.lock`);
+}
+/** Alive unless the OS says there is no such process. EPERM is a live process we may not signal. */
+function defaultIsPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function parseHolder(raw) {
+    try {
+        const v = JSON.parse(raw);
+        if (typeof v.pid !== "number" || typeof v.startedAt !== "string" || typeof v.token !== "string")
+            return null;
+        return {
+            pid: v.pid,
+            host: typeof v.host === "string" ? v.host : "",
+            startedAt: v.startedAt,
+            token: v.token,
+            command: typeof v.command === "string" ? v.command : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why an existing lock may be taken over, or null while its holder is live.
+ * Exported for tests.
+ */
+export function botLockStaleReason(raw, mtimeMs, opts) {
+    const holder = parseHolder(raw);
+    if (!holder) {
+        // Created but not yet written, or torn by a crash. Give a live creator a
+        // moment to finish writing before calling it abandoned.
+        return opts.now - mtimeMs > UNREADABLE_GRACE_MS ? "unreadable lock" : null;
+    }
+    const started = Date.parse(holder.startedAt);
+    if (Number.isNaN(started))
+        return "unreadable start time";
+    if (opts.now - started > opts.staleMs)
+        return `held since ${holder.startedAt}`;
+    // ~/.hq/bots is per machine, so the pid is this machine's. The host name is
+    // not compared: macOS changes it with the network, which would leave a
+    // crashed holder blocking for the whole stale age.
+    if (!opts.isPidAlive(holder.pid))
+        return `holder pid ${holder.pid} has exited`;
+    return null;
+}
+const heldStorage = new AsyncLocalStorage();
+/** Locks this process holds, so a hard exit (process.exit in a failure path) still lets go. */
+const heldByProcess = new Map();
+let exitHookInstalled = false;
+function installExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", releaseAllHeldBotLocks);
+}
+/**
+ * Let go of every lock this process holds. Runs on process exit, so a command
+ * that ends through process.exit (every `hq bot` failure does) frees its bot
+ * at once instead of leaving it to the stale-holder reclaim.
+ */
+export function releaseAllHeldBotLocks() {
+    for (const [file, token] of [...heldByProcess])
+        releaseFile(file, token);
+}
+function releaseFile(file, token) {
+    // Moved aside before it is judged, so a lock someone else took after
+    // reclaiming ours (a very long hold) is put back rather than deleted.
+    const aside = `${file}.release-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+        const raw = fs.readFileSync(aside, "utf8");
+        if (parseHolder(raw)?.token !== token) {
+            try {
+                fs.linkSync(aside, file);
+            }
+            catch {
+                /* a newer holder is already in place */
+            }
+        }
+    }
+    catch {
+        /* already gone, or unreadable: nothing of ours to remove */
+    }
+    fs.rmSync(aside, { force: true });
+    heldByProcess.delete(file);
+    // Leave the bots folder as it was when no lock is held. A concurrent
+    // acquirer that loses its folder here gets ENOENT and makes it again.
+    try {
+        fs.rmdirSync(path.dirname(file));
+    }
+    catch {
+        /* other locks are held, or it is already gone */
+    }
+}
+function tryCreate(file, body) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "wx", 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return false;
+        // Windows refuses to open a file that is pending deletion (a release in
+        // progress) with EPERM/EACCES rather than EEXIST: that is contention too.
+        if (process.platform === "win32" && (code === "EPERM" || code === "EACCES"))
+            return false;
+        if (code === "ENOENT") {
+            // The locks folder went away between mkdir and open (a wiped ~/.hq).
+            // Make it again and let the caller retry.
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            return false;
+        }
+        throw err;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Remove a stale lock, but only the one that was judged stale: it is renamed
+ * aside first, and if what was renamed is not what was read (a new holder got
+ * in between), it is put back.
+ */
+function reclaim(file, staleRaw) {
+    // Another waiter may have reclaimed it and taken its own lock since we read
+    // it: only the lock judged stale is ever moved. Either way the file changed,
+    // so the caller may try again at once.
+    try {
+        if (fs.readFileSync(file, "utf8") !== staleRaw)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const aside = `${file}.stale-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+    }
+    catch (err) {
+        // Gone already (someone else reclaimed or released it): try again. Any
+        // other refusal leaves the stale lock in place: wait before trying again.
+        return err.code === "ENOENT";
+    }
+    let moved = "";
+    try {
+        moved = fs.readFileSync(aside, "utf8");
+    }
+    catch {
+        /* treat as different */
+    }
+    if (moved !== staleRaw) {
+        // A live holder's lock: restore it. link fails if yet another holder now
+        // exists, which still leaves exactly one lock in place.
+        try {
+            fs.linkSync(aside, file);
+        }
+        catch {
+            try {
+                fs.writeFileSync(file, moved, { flag: "wx", mode: 0o600 });
+            }
+            catch {
+                /* another holder is in place */
+            }
+        }
+    }
+    fs.rmSync(aside, { force: true });
+    return true;
+}
+/** Take the bot's lock (waiting for a live holder), run `fn`, and let go. */
+export async function withBotLock(name, fn, opts = {}) {
+    const current = heldStorage.getStore();
+    const depth = current?.names.get(name) ?? 0;
+    if (depth > 0) {
+        current.names.set(name, depth + 1);
+        try {
+            return await fn();
+        }
+        finally {
+            current.names.set(name, depth);
+        }
+    }
+    const file = botLockPath(name, opts.root);
+    const now = opts.now ?? Date.now;
+    const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
+    const staleMs = opts.staleMs ?? BOT_LOCK_STALE_MS;
+    const waitMs = opts.waitMs ?? BOT_LOCK_WAIT_MS;
+    const pollMs = opts.pollMs ?? 150;
+    const host = os.hostname();
+    const token = randomUUID();
+    const body = JSON.stringify({
+        pid: process.pid,
+        host,
+        startedAt: new Date(now()).toISOString(),
+        token,
+        command: opts.command ?? "",
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const deadline = now() + waitMs;
+    let waited = false;
+    let lastHolder = null;
+    for (;;) {
+        if (tryCreate(file, body))
+            break;
+        let raw;
+        let mtimeMs = now();
+        try {
+            raw = fs.readFileSync(file, "utf8");
+            mtimeMs = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            raw = null; // released between our create and our read: just retry
+        }
+        if (raw !== null) {
+            lastHolder = parseHolder(raw);
+            const why = botLockStaleReason(raw, mtimeMs, { now: now(), staleMs, isPidAlive, host });
+            // Retry at once only when the stale lock is really gone. A reclaim that
+            // could not move it (Windows refusing a rename, a read-only folder) falls
+            // through to the deadline and the poll wait, so this never spins.
+            if (why) {
+                opts.onReclaim?.(lastHolder, why);
+                if (reclaim(file, raw))
+                    continue;
+            }
+            if (!waited) {
+                waited = true;
+                opts.onWait?.(lastHolder);
+            }
+        }
+        if (now() >= deadline)
+            throw new BotLockBusyError(name, lastHolder);
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    installExitHook();
+    heldByProcess.set(file, token);
+    const held = { names: new Map(current?.names ?? []) };
+    held.names.set(name, 1);
+    try {
+        return await heldStorage.run(held, fn);
+    }
+    finally {
+        // Work that `fn` started and left running no longer holds the lock.
+        held.names.set(name, 0);
+        releaseFile(file, token);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -101,6 +101,12 @@ export interface PresenceClientOptions {
  * backoff counters.
  */
 export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number, previousMs?: number, minMs?: number): number;
+/**
+ * Stable episode key for transport failures so a network drop logs once
+ * instead of once per reconnect/error event (those Error objects otherwise
+ * pin the heap while the daemon crash-loops).
+ */
+export declare function networkErrorEpisodeKey(err: unknown): string | null;
 export declare function buildPresencePayload(input: {
     status: "online" | "offline";
     actorUid: string;
@@ -129,6 +135,10 @@ export declare class PresenceClient {
     private publishedTopics;
     /** Last refusal code we logged via onError (episode dedupe). */
     private loggedRefusalKey;
+    /** Last transport-failure episode logged via onError (network-drop dedupe). */
+    private loggedNetworkErrorKey;
+    /** Serialize connect/vend so a drop cannot stack MQTT clients or fetches. */
+    private connectPromise;
     private refusal;
     private preferredHandle;
     private preferredSnapshot;
@@ -163,6 +173,9 @@ export declare class PresenceClient {
     /** Force a reconnect cycle (network change / sleep-wake). */
     reconnectNow(): void;
     private teardownClient;
+    private emitError;
+    private clearNetworkErrorEpisode;
+    private enqueueConnect;
     private onCredentialsRenewed;
     private handleRenewalError;
     private refusalKey;

package/dist/lib/mesh/live/daemon/presence.js

@@ -54,6 +54,27 @@ export function backoffDelayMs(attempt, baseMs, maxMs, random, previousMs = 0, m
     const raw = Math.max(0, random() * cap);
     return Math.min(maxMs, Math.max(previousMs, raw, minMs));
 }
+const NETWORK_ERROR_RE = /fetch failed|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ENETUNREACH|ECONNRESET|ENETDOWN|EHOSTUNREACH/i;
+/**
+ * Stable episode key for transport failures so a network drop logs once
+ * instead of once per reconnect/error event (those Error objects otherwise
+ * pin the heap while the daemon crash-loops).
+ */
+export function networkErrorEpisodeKey(err) {
+    const code = err !== null && typeof err === "object" && "code" in err &&
+        typeof err.code === "string"
+        ? err.code
+        : "";
+    const msg = err instanceof Error ? err.message : String(err);
+    if (code && NETWORK_ERROR_RE.test(code))
+        return code;
+    if (!NETWORK_ERROR_RE.test(msg))
+        return null;
+    if (/fetch failed/i.test(msg))
+        return "fetch_failed";
+    const match = msg.match(/ETIMEDOUT|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ENETUNREACH|ECONNRESET|ENETDOWN|EHOSTUNREACH/i);
+    return match ? match[0].toUpperCase() : "network";
+}
 export function buildPresencePayload(input) {
     return {
         v: 1,
@@ -92,6 +113,10 @@ export class PresenceClient {
     publishedTopics = [];
     /** Last refusal code we logged via onError (episode dedupe). */
     loggedRefusalKey = null;
+    /** Last transport-failure episode logged via onError (network-drop dedupe). */
+    loggedNetworkErrorKey = null;
+    /** Serialize connect/vend so a drop cannot stack MQTT clients or fetches. */
+    connectPromise = null;
     refusal = null;
     preferredHandle = null;
     preferredSnapshot = [];
@@ -202,7 +227,7 @@ export class PresenceClient {
         if (this.stopped)
             throw new Error("PresenceClient already stopped");
         this.setState("connecting");
-        await this.connectOnce();
+        await this.enqueueConnect();
     }
     /**
      * Graceful stop: disconnect cleanly (MQTT DISCONNECT so the broker emits
@@ -234,13 +259,20 @@ export class PresenceClient {
         }
         // Backoff counters reset only after a stable connection — not here.
         this.clearReconnect();
-        void this.connectOnce();
+        void this.enqueueConnect();
     }
     teardownClient(force) {
         const client = this.client;
         if (!client)
             return;
         this.client = null;
+        try {
+            const removable = client;
+            removable.removeAllListeners?.();
+        }
+        catch {
+            /* best-effort */
+        }
         try {
             if (force) {
                 client.end(true);
@@ -253,22 +285,43 @@ export class PresenceClient {
             /* best-effort */
         }
     }
+    emitError(err) {
+        const key = networkErrorEpisodeKey(err);
+        if (key) {
+            if (this.loggedNetworkErrorKey === key)
+                return;
+            this.loggedNetworkErrorKey = key;
+        }
+        this.options.onError?.(err);
+    }
+    clearNetworkErrorEpisode() {
+        this.loggedNetworkErrorKey = null;
+    }
+    enqueueConnect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = this.connectOnce().finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
     async onCredentialsRenewed(bundle) {
         this.bundle = bundle;
         this.notePreferredVend();
         // Successful vend ends a refusal episode (renewal skips connectOnce's vend path).
         this.clearRefusal(true);
+        this.clearNetworkErrorEpisode();
         if (this.stopped)
             return;
         // Reconnect with the new presigned URL; backoff resets only after stable connect.
-        await this.connectOnce();
+        await this.enqueueConnect();
     }
     handleRenewalError(err, info) {
         if (err instanceof CredentialVendError && err.kind === "refused") {
             this.noteRefusal(err, info?.nextRetryAt);
             return;
         }
-        this.options.onError?.(err);
+        this.emitError(err);
     }
     refusalKey(err) {
         return err.code ?? `HTTP_${err.status}`;
@@ -314,6 +367,7 @@ export class PresenceClient {
                 this.bundle = await this.options.fetchCredentials();
                 // Successful vend ends a refusal episode (even before MQTT connects).
                 this.clearRefusal(true);
+                this.clearNetworkErrorEpisode();
                 this.renewal.schedule(this.bundle);
                 this.notePreferredVend();
                 this.armPreferredWatch();
@@ -334,7 +388,7 @@ export class PresenceClient {
                 });
             }
             catch (err) {
-                this.options.onError?.(err);
+                this.emitError(err);
                 this.scheduleReconnect();
                 return;
             }
@@ -342,6 +396,7 @@ export class PresenceClient {
             client.on("connect", () => {
                 if (this.stopped || generation !== this.generation)
                     return;
+                this.clearNetworkErrorEpisode();
                 // Do not reset attempt here — broker may accept then close immediately
                 // (denied publish / policy). Reset only after CONNECT_STABLE_GRACE_MS.
                 this.connectedAtMs = this.timers.now();
@@ -362,7 +417,7 @@ export class PresenceClient {
             client.on("error", (err) => {
                 if (this.stopped || generation !== this.generation)
                     return;
-                this.options.onError?.(err);
+                this.emitError(err);
             });
             client.on("close", () => {
                 if (this.stopped || generation !== this.generation)
@@ -381,7 +436,7 @@ export class PresenceClient {
                 this.scheduleReconnect({ refused: err });
                 return;
             }
-            this.options.onError?.(err);
+            this.emitError(err);
             this.scheduleReconnect();
         }
     }
@@ -401,7 +456,7 @@ export class PresenceClient {
         for (const company of bundle.companies) {
             const topic = company.presenceTopic;
             if (!isOwnPresenceTopic(topic, bundle.actorUid, companyUids)) {
-                this.options.onError?.(new Error(`refusing to publish to non-presence topic`));
+                this.emitError(new Error(`refusing to publish to non-presence topic`));
                 continue;
             }
             await new Promise((resolve) => {
@@ -412,7 +467,7 @@ export class PresenceClient {
                     }
                 }
                 catch (err) {
-                    this.options.onError?.(err);
+                    this.emitError(err);
                     resolve();
                 }
             });
@@ -451,7 +506,7 @@ export class PresenceClient {
             if (opts?.refused) {
                 this.bundle = null;
             }
-            void this.connectOnce();
+            void this.enqueueConnect();
         }, delay);
         return delay;
     }

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -24,6 +24,9 @@ export declare const FLUSH_INTERVAL_MS = 10000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export declare const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
 export declare const DEVICE_DEFAULT_MEMBERSHIP_TIMEOUT_MS = 2000;
+/** Skip further membership probes after a transport failure so a network drop
+ *  cannot fan out one hanging lookup per held session. */
+export declare const DEVICE_DEFAULT_MEMBERSHIP_UNAVAILABLE_COOLDOWN_MS = 30000;
 /** Three sequential async shutdown steps must finish within six seconds. */
 export declare const SHUTDOWN_STEP_TIMEOUT_MS = 2000;
 /** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */

package/dist/lib/mesh/live/daemon/run.js

@@ -45,6 +45,9 @@ export const FLUSH_INTERVAL_MS = 10_000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
 export const DEVICE_DEFAULT_MEMBERSHIP_TIMEOUT_MS = 2_000;
+/** Skip further membership probes after a transport failure so a network drop
+ *  cannot fan out one hanging lookup per held session. */
+export const DEVICE_DEFAULT_MEMBERSHIP_UNAVAILABLE_COOLDOWN_MS = 30_000;
 /** Three sequential async shutdown steps must finish within six seconds. */
 export const SHUTDOWN_STEP_TIMEOUT_MS = 2_000;
 /** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */
@@ -172,6 +175,9 @@ export async function runMeshDaemon(deps = {}) {
     const resolveMembership = deps.resolveMembership ?? resolveActiveMembershipCompany;
     const machineIdentity = deps.machineIdentity ?? isMachineIdentity();
     /** The sole authorization seam for daemon tenant I/O derived from a device default. */
+    let membershipUnavailableUntilMs = 0;
+    let membershipUnavailableError = "membership lookup unavailable";
+    let membershipUnavailableLogged = false;
     const tenantGate = {
         authorize: async (input) => {
             const state = input.state ?? (input.sessionId
@@ -190,6 +196,9 @@ export async function runMeshDaemon(deps = {}) {
             const lookupKey = slug || state?.companyUid || (usingDefaultFallback
                 ? (defaultCompany?.slug || defaultCompany?.uid)
                 : undefined);
+            if (lookupKey && now().getTime() < membershipUnavailableUntilMs) {
+                return { status: "unavailable", error: membershipUnavailableError };
+            }
             let authorization;
             if (!lookupKey) {
                 authorization = { status: "denied" };
@@ -240,14 +249,21 @@ export async function runMeshDaemon(deps = {}) {
                 }
             }
             if (authorization.status === "unavailable") {
-                const prior = readDaemonState(dir)?.deviceDefaultMembershipLookupFailures ?? 0;
-                patchDaemonState(dir, {
-                    lastErrorCode: "DEVICE_DEFAULT_MEMBERSHIP_LOOKUP_FAILED",
-                    deviceDefaultMembershipLookupFailures: prior + 1,
-                }, now);
-                log(dir, `device-default membership lookup unavailable${slug ? ` company=${slug}` : ""}: ${authorization.error.slice(0, 160)}`);
+                membershipUnavailableUntilMs = now().getTime() + DEVICE_DEFAULT_MEMBERSHIP_UNAVAILABLE_COOLDOWN_MS;
+                membershipUnavailableError = authorization.error;
+                if (!membershipUnavailableLogged) {
+                    membershipUnavailableLogged = true;
+                    const prior = readDaemonState(dir)?.deviceDefaultMembershipLookupFailures ?? 0;
+                    patchDaemonState(dir, {
+                        lastErrorCode: "DEVICE_DEFAULT_MEMBERSHIP_LOOKUP_FAILED",
+                        deviceDefaultMembershipLookupFailures: prior + 1,
+                    }, now);
+                    log(dir, `device-default membership lookup unavailable${slug ? ` company=${slug}` : ""}: ${authorization.error.slice(0, 160)}`);
+                }
                 return authorization;
             }
+            membershipUnavailableUntilMs = 0;
+            membershipUnavailableLogged = false;
             if (!input.deviceDefault)
                 return authorization;
             if (authorization.status === "authorized" &&
@@ -351,12 +367,17 @@ export async function runMeshDaemon(deps = {}) {
                     lastHeldRetryAtMs = atMs;
                 },
                 log: (message) => log(dir, message),
-                authorizeDeviceDefaultTenant: async (state) => (await tenantGate.authorize({
-                    state,
-                    companySlug: state.companySlug,
-                    companyUid: state.companyUid,
-                    deviceDefault: true,
-                })).status === "authorized",
+                authorizeDeviceDefaultTenant: async (state) => {
+                    const authorization = await tenantGate.authorize({
+                        state,
+                        companySlug: state.companySlug,
+                        companyUid: state.companyUid,
+                        deviceDefault: true,
+                    });
+                    if (authorization.status === "unavailable")
+                        return "unavailable";
+                    return authorization.status === "authorized";
+                },
             });
         });
     const replayFn = deps.replayOutbox ??

package/dist/lib/mesh/live/flush.d.ts

@@ -45,8 +45,11 @@ export interface FlushDeps {
     heldMaxLines?: number;
     /** Optional logger (daemon wires this); used once per overflow trim. */
     log?: (message: string) => void;
-    /** Authoritative gate for state derived from a device default. */
-    authorizeDeviceDefaultTenant?: (state: SessionStateFile) => Promise<boolean>;
+    /** Authoritative gate for state derived from a device default.
+     *  `true` allow, `false` deny (hold NEEDS_COMPANY), `"unavailable"` skip the
+     *  network this cycle and keep the original held envelope.
+     */
+    authorizeDeviceDefaultTenant?: (state: SessionStateFile) => Promise<boolean | "unavailable">;
     /** Passed through to bind-best (catalog cache root and HQ_WORK_MESH_CACHE). */
     env?: NodeJS.ProcessEnv;
     home?: string;