@indigoai-us/hq-cli 5.342.15 → 5.342.16

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [5.342.16] — 2026-10-04
+- Keep resident command leases until monitor, agent, OAuth, bot, daemon and lane-watch runtime modules and their transitive Cognito, first-sync, hq-cloud and local-file dependencies are preloaded.
+- CI now runs the core utility parity assertions on Ubuntu, macOS, and Windows.
+- Retry permission-denied flag snapshot cache writes and reads in a uid-owned private fallback, while preserving captures with bounded fallback tags when recovery is unsafe or fails.
+
 ## [5.342.15] — 2026-10-04
 - Preserve bounded integration subcommand and RPC error context on asynchronous gateway failures, and retain diagnostics for malformed HTTP 200 gateway errors (HQ-CLI-C8/C9).
 - Claude admission can prioritize lanes that are seniors of live lanes and keep configurable per-host capacity reserved for them when `lanes.lead-admission-priority` is enabled.

package/dist/commands/agents.d.ts

@@ -28,6 +28,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 import { Command } from "commander";
+import { type ResidentCommandLeaseOptions } from "../utils/resident-package-preload.js";
 import { type TerminalSessionPayload } from "@indigoai-us/hq-cloud/outposts/node";
 import { type AgentModelProvider, type AgentModelCatalog } from "../lib/agents/model-catalog.js";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
@@ -403,6 +404,7 @@ export declare function sendAgentDm(token: string, agentUid: string, message: st
 export declare function readAgentThread(token: string, agentUid: string, limit?: number): Promise<DmThreadMessage[]>;
 /** Render one thread message as a labeled line for the terminal. */
 export declare function formatThreadMessage(m: DmThreadMessage, agentLabel: string): string;
+export declare function waitForAgentMessageWithPackageLease<T>(waitForReply: () => Promise<T>, leaseOptions?: ResidentCommandLeaseOptions): Promise<T>;
 export interface EnrollmentIssue {
     code: string;
     expiresAt: string;

package/dist/commands/agents.js

@@ -27,6 +27,8 @@
  * (`hq agents list --company acme`); when omitted, resolution falls back to
  * the caller's single active membership (same as `members.ts`).
  */
+import { runResidentCommandWithPackageLease, } from "../utils/resident-package-preload.js";
+import { waitForAgentTerminalSession } from "../lib/agents/terminal-wait.js";
 import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import * as readline from "node:readline";
@@ -37,7 +39,7 @@ import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { consoleOrigin } from "./integrations-connect.js";
-import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
+import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
 import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
@@ -1114,6 +1116,9 @@ function shortTime(iso) {
     const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}:\d{2})/);
     return m ? `${m[2]}-${m[3]} ${m[4]}` : iso;
 }
+export function waitForAgentMessageWithPackageLease(waitForReply, leaseOptions = {}) {
+    return runResidentCommandWithPackageLease("agents-message-wait", waitForReply, leaseOptions);
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1307,14 +1312,17 @@ export function registerAgentsCommand(program) {
             const deadline = Date.now() + timeoutMs;
             if (!opts.json)
                 console.log(chalk.dim(`Sent — waiting for ${agent} to reply…`));
-            let reply;
-            while (Date.now() < deadline) {
-                await sleep(3000);
-                const msgs = await readAgentThread(token, agentUid, 10);
-                reply = msgs.find((m) => m.direction === "in" && m.createdAt > lastBeforeAt);
-                if (reply)
-                    break;
-            }
+            const reply = await waitForAgentMessageWithPackageLease(async () => {
+                let received;
+                while (Date.now() < deadline) {
+                    await sleep(3000);
+                    const msgs = await readAgentThread(token, agentUid, 10);
+                    received = msgs.find((m) => m.direction === "in" && m.createdAt > lastBeforeAt);
+                    if (received)
+                        break;
+                }
+                return received;
+            });
             if (opts.json) {
                 process.stdout.write(JSON.stringify({ agentUid, sent: message, reply: reply ?? null }, null, 2) + "\n");
                 return;
@@ -1391,7 +1399,7 @@ export function registerAgentsCommand(program) {
             // registration after a cold start takes ~30-90s. Status lines go to
             // stderr (once per state) so stdout stays the session's.
             let lastState;
-            const session = await waitForTerminalSession(async () => {
+            const session = await runResidentCommandWithPackageLease("agents-terminal", () => waitForAgentTerminalSession(async () => {
                 const result = await openAgentTerminal(token, agentUid, body);
                 if (result.ok)
                     return { kind: "ready", session: result };
@@ -1411,7 +1419,7 @@ export function registerAgentsCommand(program) {
                         ? `${agent}'s box is starting — waiting for it to come online (Ctrl-C to cancel)…`
                         : `${agent}'s box is up — waiting for its agent to register (Ctrl-C to cancel)…`));
                 },
-            });
+            }));
             console.error(chalk.dim(forwardPort !== undefined
                 ? `Forwarding box port ${forwardPort} to localhost:${localPort ?? forwardPort} — Ctrl-C to end.`
                 : `Connected to ${agent}'s box — type 'exit' or Ctrl-D to leave.`));

package/dist/commands/bot.js

@@ -27,7 +27,8 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
 import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
-import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "../utils/resident-package-preload.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure, runResidentCommandWithPackageLease, } from "../utils/resident-package-preload.js";
+import { followLogFile } from "../lib/log-follow.js";
 import { CLI_UPDATE_DISABLE_ENV, createCliUpdateWatcher, handOffToUpdatedCli } from "../lib/bot/cli-update.js";
 import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
@@ -1011,21 +1012,8 @@ async function runBotLogs(nameArg, opts) {
         console.log(line);
     if (!opts.follow)
         return;
-    let size = fs.statSync(file).size;
-    await new Promise(() => {
-        fs.watchFile(file, { interval: 500 }, (curr) => {
-            if (curr.size < size)
-                size = 0;
-            if (curr.size > size) {
-                const fd = fs.openSync(file, "r");
-                const buf = Buffer.alloc(curr.size - size);
-                fs.readSync(fd, buf, 0, buf.length, size);
-                fs.closeSync(fd);
-                process.stdout.write(buf.toString());
-                size = curr.size;
-            }
-        });
-    });
+    const size = fs.statSync(file).size;
+    await runResidentCommandWithPackageLease("bot-logs-follow", () => followLogFile(file, size, (chunk) => process.stdout.write(chunk)));
 }
 // ── rm ───────────────────────────────────────────────────────────────────────
 async function confirm(question) {

package/dist/commands/daemon.d.ts

@@ -64,6 +64,10 @@ export declare function resolveDaemonHqRoot(flag: string | undefined, where: {
     cwd: string;
     home: string;
 }): string | undefined;
+export declare function runLogs(d: DaemonCommandDeps, unit: string | undefined, opts: {
+    follow?: boolean;
+    lines?: string;
+}): Promise<void>;
 export declare function registerDaemonCommand(program: Command, over?: Partial<DaemonCommandDeps>): Command;
 export {};
 //# sourceMappingURL=daemon.d.ts.map

package/dist/commands/daemon.js

@@ -36,7 +36,8 @@ import { hqdRequest, hqdSocketPath, HqdClientError } from "../lib/daemon/protoco
 import { parseStdinMachineCredentials } from "../lib/daemon/machine-login.js";
 import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
 import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "../utils/package-use-lease.js";
-import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "../utils/resident-package-preload.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure, runResidentCommandWithPackageLease, } from "../utils/resident-package-preload.js";
+import { followLogFile } from "../lib/log-follow.js";
 /** Load every lazy daemon runtime module before releasing its package-use lease. */
 export async function loadDaemonRunner(release = releaseCurrentPackageUseLease, load = () => import("../lib/daemon/run.js"), preload = () => preloadResidentPackageModules("daemon"), reportPreloadFailure = reportResidentPackagePreloadFailure) {
     const { runDaemon } = await load();
@@ -401,7 +402,7 @@ function tailLines(file, lines) {
     const text = fs.readFileSync(file, "utf8");
     return text.split("\n").filter((l, i, all) => i < all.length - 1 || l !== "").slice(-lines);
 }
-async function runLogs(d, unit, opts) {
+export async function runLogs(d, unit, opts) {
     const { paths } = currentHost(d);
     const file = unit ? paths.unitLogPath(unit) : paths.supervisorLogPath;
     if (!fs.existsSync(file))
@@ -411,22 +412,8 @@ async function runLogs(d, unit, opts) {
         d.out(line);
     if (!opts.follow)
         return;
-    let offset = fs.statSync(file).size;
-    await new Promise(() => {
-        setInterval(() => {
-            const size = fs.statSync(file).size;
-            if (size < offset)
-                offset = 0;
-            if (size === offset)
-                return;
-            const fd = fs.openSync(file, "r");
-            const buf = Buffer.alloc(size - offset);
-            fs.readSync(fd, buf, 0, buf.length, offset);
-            fs.closeSync(fd);
-            offset = size;
-            process.stdout.write(buf.toString("utf8"));
-        }, 500);
-    });
+    const offset = fs.statSync(file).size;
+    await runResidentCommandWithPackageLease("daemon-logs-follow", () => followLogFile(file, offset, (chunk) => process.stdout.write(chunk)));
 }
 function queueRequest(d, request, what) {
     const host = currentHost(d);

package/dist/commands/integrations-connect.d.ts

@@ -17,6 +17,7 @@
  * "key" but is really OAuth-protected still connects on the first try.
  */
 import { Command } from "commander";
+import { type ResidentCommandLeaseOptions } from "../utils/resident-package-preload.js";
 import { consoleOrigin } from "../utils/console-origin.js";
 export { consoleOrigin };
 import type { AdminConnection } from "./integrations-core.js";
@@ -62,6 +63,17 @@ interface ConnectTarget {
     /** Human label for prompts and success lines. */
     label: string;
 }
+/**
+ * Run the browser sign-in and finish the install.
+ *
+ * The loopback listener is bound BEFORE `/oauth/start` because its port is
+ * part of the redirect URI hq-pro registers with the remote authorization
+ * server. If hq-pro refuses that URI (its loopback flag is off, or it predates
+ * the feature), the flow degrades to the console handoff rather than failing:
+ * `/oauth/start` is retried with no `redirectUri`, and the caller is told to
+ * finish in the browser where the console callback completes it.
+ */
+export declare function waitForIntegrationOAuthWithPackageLease<T>(waitForCode: () => Promise<T>, leaseOptions?: ResidentCommandLeaseOptions): Promise<T>;
 /**
  * The console's Integrations page for a company, the console root when the
  * caller never named one (a single-membership session resolves the company

package/dist/commands/integrations-connect.js

@@ -19,6 +19,7 @@
 import chalk from "chalk";
 import open from "open";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
+import { runResidentCommandWithPackageLease, } from "../utils/resident-package-preload.js";
 import { consoleOrigin } from "../utils/console-origin.js";
 export { consoleOrigin };
 import { getCompanyUid } from "../utils/vault-api.js";
@@ -458,6 +459,9 @@ async function assertTargetResolvable(token, companyUid, target) {
  * `/oauth/start` is retried with no `redirectUri`, and the caller is told to
  * finish in the browser where the console callback completes it.
  */
+export function waitForIntegrationOAuthWithPackageLease(waitForCode, leaseOptions = {}) {
+    return runResidentCommandWithPackageLease("integrations-oauth-wait", waitForCode, leaseOptions);
+}
 async function connectViaOAuth(token, companyUid, target, opts) {
     const timeoutMs = opts.timeout ? Number(opts.timeout) * 1000 : undefined;
     if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
@@ -529,7 +533,7 @@ async function connectViaOAuth(token, companyUid, target, opts) {
         }
         let code;
         try {
-            code = await pendingCode;
+            code = await waitForIntegrationOAuthWithPackageLease(() => pendingCode);
         }
         catch (err) {
             if (err instanceof IntegrationsCliError &&

package/dist/commands/monitor.d.ts

@@ -40,6 +40,7 @@ export interface RunSupervisorDeps {
     reportPreloadFailure?: (error: unknown) => void;
     createLaneMessageApi?: typeof createMonitorLaneMessageApi;
 }
+/** Preload every monitor runtime; only lane targets need the in-process message API. */
 export declare function preloadMonitorLaneMessageApi(hqRoot: string, meta: MonitorMetadata, deps?: Pick<RunSupervisorDeps, "preloadResidentModules" | "releasePackageUseLease" | "reportPreloadFailure" | "createLaneMessageApi">): Promise<MonitorLaneMessageApi | undefined>;
 export declare function runSupervisor(id: string, deps?: RunSupervisorDeps): Promise<void>;
 interface MonitorHookResult {

package/dist/commands/monitor.js

@@ -575,13 +575,14 @@ function activeTargetMeta(hqRoot, targetKey) {
         return meta?.target_key === targetKey && state?.status === "running" && state.pid !== null && readMonitorPidLiveness(state.pid, state.starttime) ? [meta] : [];
     });
 }
+/** Preload every monitor runtime; only lane targets need the in-process message API. */
 export async function preloadMonitorLaneMessageApi(hqRoot, meta, deps = {}) {
-    if (meta.target.kind !== "lane")
-        return undefined;
     let laneMessageApi;
     await releasePackageUseLeaseAfterResidentPreload(async () => {
         await (deps.preloadResidentModules ?? (() => preloadResidentPackageModules("monitor-run")))();
-        laneMessageApi = (deps.createLaneMessageApi ?? createMonitorLaneMessageApi)(hqRoot, meta.cwd, process.env);
+        if (meta.target.kind === "lane") {
+            laneMessageApi = (deps.createLaneMessageApi ?? createMonitorLaneMessageApi)(hqRoot, meta.cwd, process.env);
+        }
     }, deps.reportPreloadFailure ?? reportResidentPackagePreloadFailure, deps.releasePackageUseLease ?? releaseCurrentPackageUseLease);
     return laneMessageApi;
 }

package/dist/lib/agents/terminal-wait.d.ts

@@ -0,0 +1,4 @@
+import type { TerminalSessionAttempt, TerminalSessionPayload, WaitForTerminalSessionOptions } from "@indigoai-us/hq-cloud/outposts/node";
+/** Keep the terminal poll loop behind a small, auditable resident preload root. */
+export declare function waitForAgentTerminalSession<T extends TerminalSessionPayload>(attempt: () => Promise<TerminalSessionAttempt<T>>, options?: WaitForTerminalSessionOptions): Promise<T>;
+//# sourceMappingURL=terminal-wait.d.ts.map

package/dist/lib/agents/terminal-wait.js

@@ -0,0 +1,6 @@
+import { waitForTerminalSession } from "@indigoai-us/hq-cloud/outposts/node";
+/** Keep the terminal poll loop behind a small, auditable resident preload root. */
+export function waitForAgentTerminalSession(attempt, options) {
+    return waitForTerminalSession(attempt, options);
+}
+//# sourceMappingURL=terminal-wait.js.map

package/dist/lib/flag-registry.js

@@ -11,7 +11,7 @@ import { resolveFlagRegistryEndpoint, } from "./flag-registry-endpoint.js";
 import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.generated.js";
 import { resolveProcessFlagCompanyContext } from "./process-flag-company-context.js";
 import { registerFlagRegistryRefreshWaiter } from "./flag-registry-refresh-wait.js";
-import { writeFlagSnapshotFile } from "./flag-snapshot-file.js";
+import { flagSnapshotWriteFailureTags, writeFlagSnapshotFile } from "./flag-snapshot-file.js";
 function captureFlagRegistryException(error, tags, sentry) {
     if (!sentry)
         return;
@@ -63,6 +63,7 @@ export async function waitForFlagRegistryRefresh(timeoutMs = 500, companyUid) {
             captureFlagRegistryException(error instanceof Error ? error : new Error(String(error)), {
                 component: "flag-snapshot-cache-write",
                 company_uid_present: "true",
+                ...flagSnapshotWriteFailureTags(error),
             }, refreshSentry);
         }
         refreshPendingSnapshot = null;
@@ -215,6 +216,7 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
                         captureFlagRegistryException(error instanceof Error ? error : new Error(String(error)), {
                             component: "flag-snapshot-cache-write",
                             company_uid_present: "true",
+                            ...flagSnapshotWriteFailureTags(error),
                         }, sentry);
                     }
                     refreshPendingSnapshot = null;

package/dist/lib/flag-snapshot-file.d.ts

@@ -1,10 +1,13 @@
 /** Private, synchronous, offline snapshot used by the native CLI fast route. */
 export declare const FLAG_SNAPSHOT_MAX_AGE_MS: number;
+export type FlagSnapshotWriteStep = "mkdir" | "chmod_dir" | "open_tmp" | "write_tmp" | "rename" | "chmod_file";
+export declare function flagSnapshotWriteFailureTags(error: unknown): Record<string, string>;
 export interface PersistedFlagSnapshot {
     company_uid: string;
     fetched_at: string;
     flags: Record<string, boolean>;
 }
+export declare function _resetFlagSnapshotCacheForTests(): void;
 export declare function flagSnapshotPath(companyUid: string, env?: NodeJS.ProcessEnv): string | undefined;
 /** Write just the validated flag decisions and company scope, never auth data. */
 export declare function writeFlagSnapshotFile(companyUid: string, flags: Readonly<Record<string, unknown>>, options?: {

package/dist/lib/flag-snapshot-file.js

@@ -4,6 +4,104 @@ import * as os from "node:os";
 import * as path from "node:path";
 export const FLAG_SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+function markWriteFailure(error, context) {
+    if (!error || (typeof error !== "object" && typeof error !== "function"))
+        return;
+    const failure = error;
+    let dirOwnerMatchesUid = "unknown";
+    if (typeof process.getuid === "function") {
+        try {
+            dirOwnerMatchesUid = fs.statSync(context.directory).uid === process.getuid()
+                ? "true"
+                : "false";
+        }
+        catch {
+            // A missing or inaccessible directory has no safely knowable owner.
+        }
+    }
+    try {
+        Object.defineProperties(failure, {
+            flagSnapshotStep: { value: context.step, configurable: true },
+            cacheRootKind: { value: context.cacheRootKind, configurable: true },
+            dirOwnerMatchesUid: { value: dirOwnerMatchesUid, configurable: true },
+        });
+    }
+    catch {
+        // Preserve the original filesystem error if it cannot carry diagnostics.
+    }
+}
+function atWriteStep(context, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        markWriteFailure(error, context);
+        throw error;
+    }
+}
+export function flagSnapshotWriteFailureTags(error) {
+    const failure = error;
+    const code = failure && typeof failure.code === "string" ? failure.code : "";
+    const allowedCodes = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC"]);
+    const step = failure?.flagSnapshotStep;
+    const rootKind = failure?.cacheRootKind;
+    const owner = failure?.dirOwnerMatchesUid;
+    const tags = {
+        flag_snapshot_step: step && ["mkdir", "chmod_dir", "open_tmp", "write_tmp", "rename", "chmod_file"].includes(step)
+            ? step
+            : "other",
+        errno_code: allowedCodes.has(code) ? code : "other",
+        cache_root_kind: rootKind === "xdg" || rootKind === "home" ? rootKind : "unknown",
+        dir_owner_matches_uid: owner === "true" || owner === "false" ? owner : "unknown",
+    };
+    if (fallbackCacheUsed)
+        tags.cache_root = "fallback";
+    if (failure?.fallbackFailed)
+        tags.fallback = "failed";
+    return tags;
+}
+let fallbackCacheUsed = false;
+export function _resetFlagSnapshotCacheForTests() {
+    fallbackCacheUsed = false;
+}
+function markFallbackFailed(error) {
+    if (!error || (typeof error !== "object" && typeof error !== "function"))
+        return;
+    try {
+        Object.defineProperty(error, "fallbackFailed", { value: true, configurable: true });
+    }
+    catch {
+        // Keep the original filesystem error intact if it cannot carry diagnostics.
+    }
+}
+function isPermissionFailure(error) {
+    const code = error?.code;
+    return code === "EACCES" || code === "EPERM";
+}
+function fallbackSnapshotPath(companyUid, create) {
+    if (typeof process.getuid !== "function")
+        return undefined;
+    const uid = process.getuid();
+    const root = path.join(os.tmpdir(), `hq-cli-flag-snapshots-${uid}`);
+    const directories = [root, path.join(root, "hq"), path.join(root, "hq", "flags")];
+    for (const directory of directories) {
+        try {
+            if (create)
+                fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== uid)
+                return undefined;
+            if (create)
+                fs.chmodSync(directory, 0o700);
+            else if ((stat.mode & 0o077) !== 0)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.join(directories[2], `snapshot-${companyUid}.json`);
+}
 export function flagSnapshotPath(companyUid, env = process.env) {
     if (!COMPANY_UID_RE.test(companyUid))
         return undefined;
@@ -12,7 +110,8 @@ export function flagSnapshotPath(companyUid, env = process.env) {
 }
 /** Write just the validated flag decisions and company scope, never auth data. */
 export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
-    const file = flagSnapshotPath(companyUid, options.env);
+    const env = options.env ?? process.env;
+    const file = flagSnapshotPath(companyUid, env);
     if (!file)
         throw new Error("Cannot persist a flag snapshot without a valid company uid");
     const normalizedFlags = Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
@@ -24,39 +123,78 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
     if (!Number.isFinite(Date.parse(snapshot.fetched_at))) {
         throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
     }
-    const directory = path.dirname(file);
-    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-    fs.chmodSync(directory, 0o700);
-    const temporary = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    let fd;
-    try {
-        fd = fs.openSync(temporary, "wx", 0o600);
-        fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
-        fs.fsyncSync(fd);
-        fs.closeSync(fd);
-        fd = undefined;
-        fs.renameSync(temporary, file);
-        fs.chmodSync(file, 0o600);
-    }
-    catch (error) {
-        if (fd !== undefined)
-            fs.closeSync(fd);
+    const cacheRootKind = env.XDG_CACHE_HOME?.trim() ? "xdg" : "home";
+    const writeAt = (destination) => {
+        const directory = path.dirname(destination);
+        const context = (step) => ({
+            step,
+            cacheRootKind,
+            directory,
+        });
+        atWriteStep(context("mkdir"), () => fs.mkdirSync(directory, { recursive: true, mode: 0o700 }));
+        const temporary = `${destination}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        let fd;
         try {
-            fs.unlinkSync(temporary);
+            fd = atWriteStep(context("open_tmp"), () => fs.openSync(temporary, "wx", 0o600));
+            atWriteStep(context("write_tmp"), () => {
+                fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
+                fs.fsyncSync(fd);
+                fs.closeSync(fd);
+                fd = undefined;
+            });
+            atWriteStep(context("rename"), () => fs.renameSync(temporary, destination));
         }
-        catch (cleanupError) {
-            if (cleanupError.code !== "ENOENT")
-                throw cleanupError;
+        catch (error) {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== "ENOENT")
+                    throw cleanupError;
+            }
+            throw error;
         }
-        throw error;
+        return destination;
+    };
+    const writeFallback = (originalError) => {
+        const fallbackFile = fallbackSnapshotPath(companyUid, true);
+        if (!fallbackFile) {
+            if (originalError) {
+                markFallbackFailed(originalError);
+                throw originalError;
+            }
+            const error = Object.assign(new Error("Flag snapshot fallback directory is unavailable"), { code: "EACCES" });
+            markFallbackFailed(error);
+            throw error;
+        }
+        try {
+            const written = writeAt(fallbackFile);
+            fallbackCacheUsed = true;
+            return written;
+        }
+        catch (fallbackError) {
+            if (originalError) {
+                markFallbackFailed(originalError);
+                throw originalError;
+            }
+            markFallbackFailed(fallbackError);
+            throw fallbackError;
+        }
+    };
+    if (fallbackCacheUsed)
+        return writeFallback();
+    try {
+        return writeAt(file);
+    }
+    catch (error) {
+        if (!isPermissionFailure(error))
+            throw error;
+        return writeFallback(error);
     }
-    return file;
 }
-/** Return null for every miss, malformed file, company mismatch, or stale file. */
-export function readFlagSnapshotFile(companyUid, options = {}) {
-    const file = flagSnapshotPath(companyUid, options.env);
-    if (!file)
-        return null;
+function parseSnapshotFile(companyUid, file, options) {
     let parsed;
     try {
         parsed = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -71,7 +209,7 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
         value.company_uid !== companyUid ||
         typeof value.fetched_at !== "string" ||
         !value.flags || typeof value.flags !== "object" || Array.isArray(value.flags))
-        return null; // Expected on missing, malformed, unreadable, or cross-company cache data.
+        return null;
     const fetchedAt = Date.parse(value.fetched_at);
     const age = (options.now ?? Date.now()) - fetchedAt;
     if (!Number.isFinite(fetchedAt) || age < 0 || age > (options.maxAgeMs ?? FLAG_SNAPSHOT_MAX_AGE_MS)) {
@@ -88,4 +226,26 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
         flags: flags,
     };
 }
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export function readFlagSnapshotFile(companyUid, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        return null;
+    if (fallbackCacheUsed) {
+        const fallback = fallbackSnapshotPath(companyUid, false);
+        const snapshot = fallback ? parseSnapshotFile(companyUid, fallback, options) : null;
+        if (snapshot)
+            return snapshot;
+    }
+    const primary = parseSnapshotFile(companyUid, file, options);
+    if (primary)
+        return primary;
+    const fallback = fallbackSnapshotPath(companyUid, false);
+    if (!fallback)
+        return null;
+    const snapshot = parseSnapshotFile(companyUid, fallback, options);
+    if (snapshot)
+        fallbackCacheUsed = true;
+    return snapshot;
+}
 //# sourceMappingURL=flag-snapshot-file.js.map

package/dist/lib/log-follow.d.ts

@@ -0,0 +1,3 @@
+/** Follow append-only log bytes without importing package code after startup. */
+export declare function followLogFile(file: string, initialOffset: number, write: (chunk: string) => void): Promise<void>;
+//# sourceMappingURL=log-follow.d.ts.map

package/dist/lib/log-follow.js

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+/** Follow append-only log bytes without importing package code after startup. */
+export async function followLogFile(file, initialOffset, write) {
+    let offset = initialOffset;
+    await new Promise(() => {
+        fs.watchFile(file, { interval: 500 }, (curr) => {
+            if (curr.size < offset)
+                offset = 0;
+            if (curr.size === offset)
+                return;
+            const fd = fs.openSync(file, "r");
+            const buf = Buffer.alloc(curr.size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            fs.closeSync(fd);
+            offset = curr.size;
+            write(buf.toString("utf8"));
+        });
+    });
+}
+//# sourceMappingURL=log-follow.js.map

package/dist/utils/resident-package-preload.d.ts

@@ -1,5 +1,5 @@
-export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "bot" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run";
-/** Package imports reachable lazily from each resident command's runtime graph. */
+export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "agents-terminal" | "bot" | "bot-logs-follow" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon" | "daemon-logs-follow" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run" | "agents-message-wait" | "integrations-oauth-wait";
+/** Runtime modules that resident commands may need after a wait starts. */
 export declare const RESIDENT_PACKAGE_MODULES: Record<ResidentPackagePath, readonly string[]>;
 export declare class ResidentPackagePreloadError extends Error {
     readonly moduleSpecifier: string;

package/dist/utils/resident-package-preload.js

@@ -1,8 +1,8 @@
 import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload, } from "./package-use-lease.js";
-/** Package imports reachable lazily from each resident command's runtime graph. */
+/** Runtime modules that resident commands may need after a wait starts. */
 export const RESIDENT_PACKAGE_MODULES = {
-    "agent-kit": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open"],
-    "agent-mcp": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../commands/access.js", "open"],
+    "agent-kit": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "agent-mcp": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../commands/access.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "../utils/local-files-overview.js", "@indigoai-us/hq-cloud"],
     login: [
         "../lib/mesh/api.js",
         "../lib/work-context/config.js",
@@ -12,6 +12,9 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../utils/plan-gate-error.js",
         "../sentry.js",
         "open",
+        "../utils/cognito-session.js",
+        "../lib/first-sync-next-step.js",
+        "@indigoai-us/hq-cloud",
     ],
     "auth-login": [
         "../lib/auth-login-provider-state.js",
@@ -20,7 +23,10 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../utils/plan-gate-error.js",
         "../sentry.js",
         "open",
+        "../utils/cognito-session.js",
+        "@indigoai-us/hq-cloud",
     ],
+    "agents-terminal": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
     bot: [
         "../lib/flag-registry.js",
         "../commands/access.js",
@@ -28,7 +34,12 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
         "open",
+        "../utils/cognito-session.js",
+        "../lib/first-sync-next-step.js",
+        "../utils/local-files-overview.js",
+        "@indigoai-us/hq-cloud",
     ],
+    "bot-logs-follow": [],
     mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js"],
     childWrapper: ["../main.js"],
     coreJobRun: ["../lib/flag-registry.js"],
@@ -42,11 +53,16 @@ export const RESIDENT_PACKAGE_MODULES = {
         "@modelcontextprotocol/sdk/client/streamableHttp.js",
         "../utils/staged-npm-install.js",
         "open",
+        "../lib/first-sync-next-step.js",
+        "@indigoai-us/hq-cloud",
     ],
-    "mesh-daemon": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open"],
-    "lanes-watch": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open"],
-    "monitor-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open"],
-    "monitor-run": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "open"],
+    "daemon-logs-follow": [],
+    "mesh-daemon": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "lanes-watch": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "monitor-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "monitor-run": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "agents-message-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "integrations-oauth-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
 };
 const LOADERS = {
     "agent-kit": [
@@ -57,6 +73,9 @@ const LOADERS = {
         () => import("../lib/plan-limit-nag.js"),
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     "agent-mcp": [
         async () => {
@@ -67,6 +86,10 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         () => import("../commands/access.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("../utils/local-files-overview.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     login: [
         () => import("../lib/mesh/api.js"),
@@ -80,6 +103,9 @@ const LOADERS = {
             preloadSentrySdk();
         },
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     "auth-login": [
         () => import("../lib/auth-login-provider-state.js"),
@@ -91,6 +117,20 @@ const LOADERS = {
             preloadSentrySdk();
         },
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("@indigoai-us/hq-cloud"),
+    ],
+    "agents-terminal": [
+        async () => {
+            const { preloadSentrySdk } = await import("../sentry.js");
+            preloadSentrySdk();
+        },
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
+        () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     bot: [
         () => import("../lib/flag-registry.js"),
@@ -102,7 +142,12 @@ const LOADERS = {
         () => import("../lib/plan-limit-nag.js"),
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("../utils/local-files-overview.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
+    "bot-logs-follow": [],
     mcp: [
         () => import("../lib/mcp/tools.js"),
         () => import("../lib/mcp/prompts.js"),
@@ -126,7 +171,10 @@ const LOADERS = {
         () => import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
         () => import("../utils/staged-npm-install.js"),
         () => import("open"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
+    "daemon-logs-follow": [],
     "mesh-daemon": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
@@ -135,6 +183,9 @@ const LOADERS = {
         () => import("../lib/plan-limit-nag.js"),
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     "lanes-watch": [
         async () => {
@@ -144,6 +195,9 @@ const LOADERS = {
         () => import("../lib/plan-limit-nag.js"),
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     "monitor-wait": [
         async () => {
@@ -153,6 +207,9 @@ const LOADERS = {
         () => import("../lib/plan-limit-nag.js"),
         () => import("../utils/plan-gate-error.js"),
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
     "monitor-run": [
         () => import("../commands/lanes.js"),
@@ -163,6 +220,33 @@ const LOADERS = {
             preloadSentrySdk();
         },
         () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
+    ],
+    "agents-message-wait": [
+        async () => {
+            const { preloadSentrySdk } = await import("../sentry.js");
+            preloadSentrySdk();
+        },
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
+        () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
+    ],
+    "integrations-oauth-wait": [
+        async () => {
+            const { preloadSentrySdk } = await import("../sentry.js");
+            preloadSentrySdk();
+        },
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
+        () => import("open"),
+        () => import("../utils/cognito-session.js"),
+        () => import("../lib/first-sync-next-step.js"),
+        () => import("@indigoai-us/hq-cloud"),
     ],
 };
 export class ResidentPackagePreloadError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.342.15",
+  "version": "5.342.16",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {