@indigoai-us/hq-cli 5.342.8 → 5.342.10

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.342.10] — 2026-10-04
+- Attach bounded status, gateway error-class, and integrations subcommand tags to captured gateway faults.
+
+## [5.342.9] — 2026-10-04
+- Child wrappers now release their package-use lease after startup modules are preloaded, so long-running child processes do not block CLI updates.
+- Keep nested HQ child leases and materialize core-job post-exit helpers before releasing the parent package lease.
+- Run the core migration differential check on pull requests only when migration, build, or differential inputs change, while retaining it on main pushes.
+- Reduce startup work on the fast `hq secrets env` route while keeping the server authorization request on every call.
+
 ## [5.342.8] — 2026-10-04
 - Keep blocker escalation failures visible on the lane and stop retrying the same failed fallback every watcher turn.
 - Release the daemon's hq-cli package-use lease after all reachable lazy runtime modules preload successfully, allowing CLI updates while preserving the existing restart-on-update path.

package/dist/commands/core-job-post-exit-assets.d.ts

@@ -0,0 +1,8 @@
+export interface CoreJobPostExitHelpers {
+    notifyBin: string;
+    remediateBin: string;
+    cleanup(): void;
+}
+/** Copy package-backed helpers before the runner releases its package-use lease. */
+export declare function materializeCoreJobPostExitHelpers(scriptPath: string, env: NodeJS.ProcessEnv): CoreJobPostExitHelpers;
+//# sourceMappingURL=core-job-post-exit-assets.d.ts.map

package/dist/commands/core-job-post-exit-assets.js

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Copy package-backed helpers before the runner releases its package-use lease. */
+export function materializeCoreJobPostExitHelpers(scriptPath, env) {
+    const sourceDir = path.dirname(scriptPath);
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-job-post-exit-"));
+    const materialize = (name, override) => {
+        if (override)
+            return override;
+        const source = path.join(sourceDir, name);
+        const target = path.join(tempDir, name);
+        fs.copyFileSync(source, target);
+        fs.chmodSync(target, fs.statSync(source).mode & 0o777);
+        return target;
+    };
+    try {
+        const notifyBin = materialize("hq-job-notify.sh", env.HQ_JOB_NOTIFY_BIN);
+        const remediateBin = materialize("hq-job-remediate.sh", env.HQ_JOB_REMEDIATE_BIN);
+        let cleaned = false;
+        return {
+            notifyBin,
+            remediateBin,
+            cleanup() {
+                if (cleaned)
+                    return;
+                cleaned = true;
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=core-job-post-exit-assets.js.map

package/dist/commands/core-job-run-native.d.ts

@@ -15,6 +15,7 @@ export type ProcessRequest = {
     env: NodeJS.ProcessEnv;
     logPath?: string;
     timeoutMs?: number;
+    onChildStart?: () => void;
 };
 type LockLease = {
     release(): Promise<void>;

package/dist/commands/core-job-run-native.js

@@ -9,6 +9,8 @@ import { resolveLiveRoot, resolveBundledAsset } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 import { describeCoreCommand } from "./core-command-catalog.js";
 import { coreNativeJobsEnabled } from "./core-native-jobs-flag.js";
+import { releaseChildWrapperPackageUseLeaseAfterStart } from "../utils/child-wrapper-lease.js";
+import { materializeCoreJobPostExitHelpers } from "./core-job-post-exit-assets.js";
 const RUN_ASSET = "core/scripts/hq-job-run.sh";
 const RUNNER_NAME = "hq-job-run";
 export const OUTPOST_IDENTITY_FILE = "/etc/outpost/codex-identity.env";
@@ -152,6 +154,8 @@ export async function spawnProcess(request) {
             if (exitFile)
                 fs.writeFileSync(exitFile, `EXIT=${request.env.HQ_JOB_RUN_STUB_EXIT_CODE ?? "0"}\n`);
         }
+        if (nestedAgent || (request.file === "tmux" && request.args[0] === "new-session"))
+            request.onChildStart?.();
         const diagnostic = request.env.HQ_JOB_RUN_STUB_DIAGNOSTIC || "";
         if (nestedAgent && request.logPath && diagnostic)
             appendLog(request.logPath, `${diagnostic}\n`);
@@ -179,6 +183,8 @@ export async function spawnProcess(request) {
             stdio: ["ignore", "pipe", "pipe"],
             detached: processGroup,
         });
+        if (request.onChildStart)
+            child.once("spawn", request.onChildStart);
         child.once("error", reject);
         child.stdout.on("data", (chunk) => {
             if (request.logPath) {
@@ -685,8 +691,8 @@ async function ingestRunStatus(jobId, runAt, runId, exit, failureClass, actions,
         emitLog(`run status ingest failed job=${jobId} http=${status} (logged; not failing run)`);
     void logFile;
 }
-async function runHelper(binary, args, cwd, env, deps, logPath, timeoutMs) {
-    return await deps.runProcess({ file: binary, args, cwd, env, ...(logPath ? { logPath } : {}), ...(timeoutMs ? { timeoutMs } : {}) });
+async function runHelper(binary, args, cwd, env, deps, logPath, timeoutMs, onChildStart) {
+    return await deps.runProcess({ file: binary, args, cwd, env, ...(logPath ? { logPath } : {}), ...(timeoutMs ? { timeoutMs } : {}), ...(onChildStart ? { onChildStart } : {}) });
 }
 async function callNotify(jobId, jobName, outcome, summary, duration, logPath, failureClass, nextAction, owner, notifyMode, hqRoot, notifyBin, deps) {
     if (deps.env.HQ_JOB_RUN_NO_NOTIFY === "1") {
@@ -876,7 +882,7 @@ function bashPrintfQuote(value) {
     }
     return [...value].map((character) => safe.test(character) ? character : `\\${character}`).join("");
 }
-async function runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, stamp, logDir, logFile, deps) {
+async function runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, stamp, logDir, logFile, deps, onChildStart) {
     if (!pathExecutable("tmux", deps.env) && deps.env.HQ_JOB_RUN_STUBS !== "1") {
         deps.appendFile(logFile, "remote surface requested but tmux missing — falling back to headless\n");
         return 99;
@@ -900,7 +906,7 @@ async function runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, s
     const tmuxEnv = deps.env.HQ_JOB_RUN_STUBS === "1"
         ? { ...deps.env, HQ_JOB_RUN_REMOTE_DONE_FILE: doneFile, HQ_JOB_RUN_REMOTE_EXIT_FILE: exitFile }
         : deps.env;
-    const runTmux = async (args) => await runHelper("tmux", args, deps.cwd, tmuxEnv, deps);
+    const runTmux = async (args) => await runHelper("tmux", args, deps.cwd, tmuxEnv, deps, undefined, undefined, args[0] === "new-session" ? onChildStart : undefined);
     await runTmux(["kill-session", "-t", session]);
     await runTmux(["new-session", "-d", "-s", session, "-x", "120", "-y", "40", "-c", runCwd, tmuxCommand]);
     let elapsedSeconds = 0;
@@ -945,13 +951,16 @@ async function runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, s
     await runTmux(["kill-session", "-t", session]);
     return code;
 }
-async function runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps) {
+async function runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps, canReleasePackageLease = true) {
     if (deps.env.HQ_JOB_RUN_SKIP_EXEC === "1") {
         deps.appendFile(logFile, "(HQ_JOB_RUN_SKIP_EXEC=1 — not invoking runtime CLI)\n");
         return 0;
     }
     if (runtime === "claude" && surface === "remote") {
-        const remoteCode = await runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, stamp, logDir, logFile, deps);
+        const remoteCode = await runRemoteClaude(jobId, runtime, prompt, runCwd, timeoutSeconds, stamp, logDir, logFile, deps, () => {
+            if (canReleasePackageLease)
+                releaseChildWrapperPackageUseLeaseAfterStart("coreJobRun");
+        });
         if (remoteCode !== 99)
             return remoteCode;
     }
@@ -979,7 +988,10 @@ async function runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secret
     else if (secretNames.length > 0) {
         deps.appendFile(logFile, "warning: requirements.secrets set but hq CLI missing — running without secrets exec\n");
     }
-    const result = await runHelper(file, args, runCwd, deps.env, deps, logFile, timeoutMs);
+    const result = await runHelper(file, args, runCwd, deps.env, deps, logFile, timeoutMs, () => {
+        if (canReleasePackageLease)
+            releaseChildWrapperPackageUseLeaseAfterStart("coreJobRun", file === "hq");
+    });
     return result.code;
 }
 async function recordSkip(jobId, jobName, runtime, skipReason, failureClass, action, statusSuffix, notifyOutcome, owner, notifyMode, company, hqRoot, logFile, statusFile, startedAt, startedEpoch, logDir, stamp, notifyBin, remediateBin, deps, authStatus = "") {
@@ -1089,12 +1101,19 @@ export async function runJob(argv, hqRootOverride, injected) {
     catch (error) {
         return emitDie(`failed to acquire global run lock: ${lockPath}${error instanceof Error && error.message.includes("flock") ? ` (${error.message})` : ""}`);
     }
+    let postExitHelpers = null;
     try {
         const startedAt = isoNow(deps);
         const startedEpoch = deps.epochNow();
         deps.appendFile(logFile, `=== hq-job-run ${jobId} ===\nstarted_at=${startedAt}\nruntime=${runtime}\ntimeout_seconds=${timeoutSeconds}\nsurface=${surface}\njob_file=${jobFile}\nhq_root=${hqRoot}\n`);
-        const notifyBin = env.HQ_JOB_NOTIFY_BIN || path.join(path.dirname(deps.scriptPath), "hq-job-notify.sh");
-        const remediateBin = env.HQ_JOB_REMEDIATE_BIN || path.join(path.dirname(deps.scriptPath), "hq-job-remediate.sh");
+        try {
+            postExitHelpers = materializeCoreJobPostExitHelpers(deps.scriptPath, env);
+        }
+        catch (error) {
+            deps.appendFile(logFile, `post_exit_helpers_unavailable=${error instanceof Error ? error.name : "Error"}; package lease retained\n`);
+        }
+        const notifyBin = postExitHelpers?.notifyBin ?? env.HQ_JOB_NOTIFY_BIN ?? path.join(path.dirname(deps.scriptPath), "hq-job-notify.sh");
+        const remediateBin = postExitHelpers?.remediateBin ?? env.HQ_JOB_REMEDIATE_BIN ?? path.join(path.dirname(deps.scriptPath), "hq-job-remediate.sh");
         const authStatus = readAuthStatus(runtime, env, deps.home, deps);
         if (authStatus !== "ok") {
             const reason = authStatus === "no_cli"
@@ -1116,7 +1135,7 @@ export async function runJob(argv, hqRootOverride, injected) {
             return emitDie(error instanceof Error ? error.message : String(error));
         }
         const secretNames = jobSecretNames(job);
-        let exitCode = await runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps);
+        let exitCode = await runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps, postExitHelpers !== null);
         let failureClass = "";
         let nextAction = "";
         let retried = 0;
@@ -1138,7 +1157,7 @@ export async function runJob(argv, hqRootOverride, injected) {
                 retried = 1;
                 deps.appendFile(logFile, "remediate_retry=1\n");
                 emitLog(`self-remediate recommended retry for ${failureClass} — retrying once`);
-                exitCode = await runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps);
+                exitCode = await runAgent(runtime, surface, prompt, runCwd, timeoutSeconds, secretNames, company, logFile, stamp, jobId, logDir, deps, postExitHelpers !== null);
                 if (exitCode !== 0) {
                     failureClass = classifyFailure(exitCode, logFile, "", deps);
                     deps.appendFile(logFile, `failure_class_after_retry=${failureClass}\n`);
@@ -1172,6 +1191,7 @@ export async function runJob(argv, hqRootOverride, injected) {
     }
     finally {
         await lease.release();
+        postExitHelpers?.cleanup();
     }
 }
 export function registerCoreJobRunCommand(job) {

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

@@ -150,6 +150,8 @@ export declare class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     readonly rpcCode?: number;
+    /** Fixed vocabulary for the integrations subcommand that called the gateway. */
+    readonly gatewaySubcommand?: "tools_list" | "tools_call" | "other";
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -164,6 +166,7 @@ export declare class IntegrationsCliError extends Error {
         status?: number;
         oauthProtected?: boolean;
         rpcCode?: number;
+        gatewaySubcommand?: "tools_list" | "tools_call" | "other";
         redirectUri?: string;
     });
 }

package/dist/commands/integrations-core.js

@@ -55,6 +55,8 @@ export class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     rpcCode;
+    /** Fixed vocabulary for the integrations subcommand that called the gateway. */
+    gatewaySubcommand;
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -75,6 +77,8 @@ export class IntegrationsCliError extends Error {
             this.oauthProtected = opts.oauthProtected;
         if (opts.rpcCode !== undefined)
             this.rpcCode = opts.rpcCode;
+        if (opts.gatewaySubcommand !== undefined)
+            this.gatewaySubcommand = opts.gatewaySubcommand;
         if (opts.redirectUri !== undefined) {
             Object.defineProperty(this, "redirectUri", {
                 value: opts.redirectUri,
@@ -175,6 +179,18 @@ const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602, -32050]);
 function isExpectedGatewayError(code) {
     return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
 }
+function expectedGatewayErrorFallback(code) {
+    switch (code) {
+        case -32003:
+            return "You do not have access to this integration. Ask its owner to share it with you.";
+        case -32602:
+            return "The integration rejected this request. Check the tool name and arguments.";
+        case -32050:
+            return "The connected provider could not complete this request. Wait a moment and try again.";
+        default:
+            return undefined;
+    }
+}
 // A 401 from ANY integration-gateway vault call means the caller's HQ session
 // is expired or missing — an expected auth state fixed by `hq login`, not an
 // hq-cli defect. Raise the same typed AuthError the vault company-resolution
@@ -399,7 +415,18 @@ export async function resolveConnection(token, companyUid, app, opts, recoveryOp
     }
     return selectConnection(connections, opts);
 }
+function gatewaySubcommandFor(params) {
+    const name = params.name;
+    if (typeof name !== "string")
+        return "other";
+    if (name.endsWith(".mcp.tools.list"))
+        return "tools_list";
+    if (name.endsWith(".mcp.tools.call"))
+        return "tools_call";
+    return "other";
+}
 export async function callGateway(token, params, idempotencyKey) {
+    const gatewaySubcommand = gatewaySubcommandFor(params);
     const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
     const res = await vaultApiFetch({
         token,
@@ -414,6 +441,7 @@ export async function callGateway(token, params, idempotencyKey) {
     });
     const message = (await res.json().catch(() => null));
     let terminalMessage = message;
+    let terminalStatus = res.status;
     if (res.status === 202) {
         const accepted = message;
         const jobId = accepted && typeof accepted.jobId === "string" ? accepted.jobId : "";
@@ -427,7 +455,9 @@ export async function callGateway(token, params, idempotencyKey) {
         if (!idempotencyKey) {
             throw new IntegrationsCliError(`Integration gateway accepted async job ${jobId} without an idempotency key.`, { expected: false, status: 202 });
         }
-        terminalMessage = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+        const terminal = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+        terminalMessage = terminal.message;
+        terminalStatus = terminal.status;
     }
     if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
@@ -437,7 +467,7 @@ export async function callGateway(token, params, idempotencyKey) {
         // reaches the Sentry fingerprint's HTTP bucket instead of colliding under
         // default grouping. Same reasoning as raiseForResponse, which already sets
         // `status`. This does not change the `expected` decision above.
-        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status, gatewaySubcommand });
     }
     if (terminalMessage?.error) {
         // The gateway's error text is minted UPSTREAM (hq-pro, the integration
@@ -449,8 +479,11 @@ export async function callGateway(token, params, idempotencyKey) {
         // no-op. This preserves PR #298's user-visible diagnostic; it only makes
         // it safe on the newly-expected path.
         throw new IntegrationsCliError(redactErrorText(terminalMessage.error.message ?? "") ||
+            expectedGatewayErrorFallback(terminalMessage.error.code) ||
             "Integration gateway returned an error.", {
             expected: isExpectedGatewayError(terminalMessage.error.code),
+            status: terminalStatus,
+            gatewaySubcommand,
             // Carry the protocol code to the capture site as a bounded grouping
             // discriminator (HQ-CLI collision, Sentry 7642756130). This does not
             // alter the `expected` decision above; it only labels the error.
@@ -518,7 +551,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             if (!hasJsonRpcOutcome) {
                 throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid JSON-RPC response.`, { expected: false });
             }
-            return response;
+            return { message: response, status: res.status };
         }
         if (poll.status !== "pending") {
             throw new IntegrationsCliError(`Integration job ${jobId} returned unknown status '${String(poll.status)}'.`, { expected: true });

package/dist/commands/run.js

@@ -12,6 +12,8 @@ import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
 import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
 import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
 import { withRunSecretReadTelemetry } from './run-feature-telemetry.js';
+import { isHqCliChild, releaseChildWrapperPackageUseLeaseAfterStart } from '../utils/child-wrapper-lease.js';
+import { runChildWrapperExitCode } from '../utils/child-wrapper-exit.js';
 const SECRET_LOAD_TIMEOUT_MS = 30_000;
 export async function buildRunUsage(scriptPath, scriptId) {
     if (scriptId && !scriptPath) {
@@ -165,6 +167,7 @@ export function registerRunCommand(program) {
                 stdio: 'inherit',
                 env: { ...process.env, ...resolvedEnv },
             });
+            child.once('spawn', () => releaseChildWrapperPackageUseLeaseAfterStart("childWrapper", isHqCliChild(childCmd, restArgs)));
             child.on('error', (err) => {
                 process.stderr.write(`Error: failed to start command '${childCmd}': ${err.message}\n`);
                 process.exit(1);
@@ -177,7 +180,7 @@ export function registerRunCommand(program) {
                 // which this explicit exit would otherwise erase. Force a non-zero
                 // code so such a rejection is never masked by a child that exited 0,
                 // while still propagating a genuine non-zero child status.
-                process.exit(hadFatalRejection() ? (code || 1) : (code ?? 1));
+                process.exit(runChildWrapperExitCode(code, hadFatalRejection()));
             });
         }
         catch (err) {

package/dist/commands/secrets.js

@@ -3,6 +3,8 @@ export { buildSecretUsage, emitEnvExportsAndExit, loadRevealedSecrets, parseSecr
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { removeCacheEntry, clearAllCache } from "../utils/secrets-cache.js";
+import { isHqCliChild, releaseChildWrapperPackageUseLeaseAfterStart } from "../utils/child-wrapper-lease.js";
+import { secretsExecChildExitCode } from "../utils/child-wrapper-exit.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
@@ -1136,6 +1138,7 @@ export function registerSecretsCommand(program) {
                 stdio: "inherit",
                 env: { ...process.env, ...secretEnv },
             });
+            child.once("spawn", () => releaseChildWrapperPackageUseLeaseAfterStart("childWrapper", isHqCliChild(childCmd, childCmdArgs)));
             child.on("error", (err) => {
                 console.error(chalk.red(`Failed to start command '${childCmd}': ${err.message}`));
                 process.exit(1);
@@ -1144,7 +1147,7 @@ export function registerSecretsCommand(program) {
                 if (signal) {
                     process.kill(process.pid, signal);
                 }
-                process.exit(code ?? 1);
+                process.exit(secretsExecChildExitCode(code));
             });
         }
         catch (err) {

package/dist/main.js

@@ -335,6 +335,39 @@ function qmdSpawnFailureCaptureContext(err) {
         return undefined;
     return { contexts: { qmd_spawn_failure: diagnostics } };
 }
+const GATEWAY_RPC_CODE_TAGS = new Map([
+    [-32603, "internal_error"],
+    [-32009, "conflict"],
+    [-32003, "unauthorized"],
+    [-32602, "invalid_params"],
+    [-32050, "provider_error"],
+]);
+function integrationsGatewayCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const record = err;
+    const subcommand = record.gatewaySubcommand;
+    if (subcommand === undefined)
+        return undefined;
+    const subcommandTag = subcommand === "tools_list" || subcommand === "tools_call"
+        ? subcommand
+        : "other";
+    const status = record.status;
+    const statusTag = typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599
+        ? String(status)
+        : status === undefined ? "unknown" : "other";
+    const rpcCode = record.rpcCode;
+    const codeTag = typeof rpcCode === "number" && Number.isInteger(rpcCode)
+        ? GATEWAY_RPC_CODE_TAGS.get(rpcCode) ?? "other"
+        : rpcCode === undefined ? "missing" : "other";
+    return {
+        tags: {
+            integration_gateway_status: statusTag,
+            integration_gateway_code: codeTag,
+            integration_subcommand: subcommandTag,
+        },
+    };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
@@ -853,9 +886,11 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
             const qmdContext = qmdExitCaptureContext(err);
-            if (spawnContext || installContext || qmdContext) {
+            const gatewayContext = integrationsGatewayCaptureContext(err);
+            if (spawnContext || installContext || qmdContext || gatewayContext) {
                 deps.sentry.captureException(err, {
                     ...qmdContext,
+                    ...(gatewayContext ? { tags: gatewayContext.tags } : {}),
                     ...((spawnContext || installContext)
                         ? { contexts: { ...spawnContext?.contexts, ...installContext } }
                         : {}),

package/dist/utils/child-wrapper-exit.d.ts

@@ -0,0 +1,5 @@
+/** Preserve the existing hq run child-exit policy for use by the close handler. */
+export declare function runChildWrapperExitCode(code: number | null, fatalRejection: boolean): number;
+/** Preserve hq secrets exec's direct child exit-code propagation. */
+export declare function secretsExecChildExitCode(code: number | null): number;
+//# sourceMappingURL=child-wrapper-exit.d.ts.map

package/dist/utils/child-wrapper-exit.js

@@ -0,0 +1,9 @@
+/** Preserve the existing hq run child-exit policy for use by the close handler. */
+export function runChildWrapperExitCode(code, fatalRejection) {
+    return fatalRejection ? (code || 1) : (code ?? 1);
+}
+/** Preserve hq secrets exec's direct child exit-code propagation. */
+export function secretsExecChildExitCode(code) {
+    return code ?? 1;
+}
+//# sourceMappingURL=child-wrapper-exit.js.map

package/dist/utils/child-wrapper-lease.d.ts

@@ -0,0 +1,5 @@
+import { type ResidentPackagePath } from "./resident-package-preload.js";
+export declare function isHqCliChild(command: string, args?: readonly string[]): boolean;
+/** A child wrapper can release its own lease only after its child has started. */
+export declare function releaseChildWrapperPackageUseLeaseAfterStart(residentPath: ResidentPackagePath, childIsHqCli?: boolean): void;
+//# sourceMappingURL=child-wrapper-lease.d.ts.map

package/dist/utils/child-wrapper-lease.js

@@ -0,0 +1,18 @@
+import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload } from "./package-use-lease.js";
+import { preloadResidentPackageModules, reportResidentPackagePreloadFailure } from "./resident-package-preload.js";
+import path from "node:path";
+export function isHqCliChild(command, args = []) {
+    const base = path.basename(command).toLowerCase();
+    if (base === "hq" || base === "hq.exe" || base === "hq.cmd" || base === "hq.bat")
+        return true;
+    return /(?:^|[\\/])(?:dist[\\/]bin[\\/]hq|hq)\.(?:c|m)?js$/i.test(args[0] ?? "");
+}
+/** A child wrapper can release its own lease only after its child has started. */
+export function releaseChildWrapperPackageUseLeaseAfterStart(residentPath, childIsHqCli = false) {
+    // Nested HQ commands must acquire their own lease before an updater can
+    // replace the tree. Keep this process's lease through that child's lifetime.
+    if (childIsHqCli)
+        return;
+    void releasePackageUseLeaseAfterResidentPreload(() => preloadResidentPackageModules(residentPath), reportResidentPackagePreloadFailure, releaseCurrentPackageUseLease);
+}
+//# sourceMappingURL=child-wrapper-lease.js.map

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

@@ -1,4 +1,4 @@
-export type ResidentPackagePath = "bot" | "mcp" | "daemon";
+export type ResidentPackagePath = "bot" | "mcp" | "daemon" | "childWrapper" | "coreJobRun";
 /** Package imports reachable lazily from each resident command's runtime graph. */
 export declare const RESIDENT_PACKAGE_MODULES: Record<ResidentPackagePath, readonly string[]>;
 export declare class ResidentPackagePreloadError extends Error {

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

@@ -1,10 +1,21 @@
 /** Package imports reachable lazily from each resident command's runtime graph. */
 export const RESIDENT_PACKAGE_MODULES = {
-    bot: ["../lib/flag-registry.js", "../commands/access.js", "../sentry.js", "open"],
+    bot: [
+        "../lib/flag-registry.js",
+        "../commands/access.js",
+        "../sentry.js",
+        "../lib/plan-limit-nag.js",
+        "../utils/plan-gate-error.js",
+        "open",
+    ],
     mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js"],
+    childWrapper: ["../main.js"],
+    coreJobRun: ["../lib/flag-registry.js"],
     daemon: [
         "../sentry.js",
         "../utils/cognito-session.js",
+        "../lib/plan-limit-nag.js",
+        "../utils/plan-gate-error.js",
         "../lib/daemon/mcp-oauth.js",
         "@modelcontextprotocol/sdk/client/index.js",
         "@modelcontextprotocol/sdk/client/streamableHttp.js",
@@ -20,18 +31,28 @@ const LOADERS = {
             const { preloadSentrySdk } = await import("../sentry.js");
             preloadSentrySdk();
         },
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
         () => import("open"),
     ],
     mcp: [
         () => import("../lib/mcp/tools.js"),
         () => import("../lib/mcp/prompts.js"),
     ],
+    childWrapper: [
+        () => import("../main.js"),
+    ],
+    coreJobRun: [
+        () => import("../lib/flag-registry.js"),
+    ],
     daemon: [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
             preloadSentrySdk();
         },
         () => import("../utils/cognito-session.js"),
+        () => import("../lib/plan-limit-nag.js"),
+        () => import("../utils/plan-gate-error.js"),
         () => import("../lib/daemon/mcp-oauth.js"),
         () => import("@modelcontextprotocol/sdk/client/index.js"),
         () => import("@modelcontextprotocol/sdk/client/streamableHttp.js"),

package/dist/utils/vault-api.js

@@ -1,11 +1,8 @@
 import { DEFAULT_VAULT_API_URL, cognitoCachePrincipalUid } from './cognito-session.js';
 import { CLI_VERSION } from '../cli-version.js';
-import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
-import { recordPlanLimitStatus } from '../lib/plan-limit-nag.js';
 import { networkTransportErrorCode } from './network-transport-error.js';
-import { planGateErrorFromResponse } from './plan-gate-error.js';
 import { markExpectedUserError } from './expected-cli-error.js';
 import { redactErrorText } from './redact-error-text.js';
 import { isSecretLoadUnavailable, isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError } from './secret-load-availability.js';
@@ -24,6 +21,10 @@ import { readCachedScopeUid, writeCachedScopeUid } from './secrets-cache.js';
  */
 const IDENTITY_LOOKUP_TIMEOUT_MS = 15_000;
 const LAMBDA_INVOKE_RETRY_MAX_DELAY_MS = 100;
+async function addVaultBreadcrumb(breadcrumb) {
+    const { Sentry } = await import('../sentry.js');
+    Sentry.addBreadcrumb(breadcrumb);
+}
 function isLambdaInvokeServiceError(response, bodyText) {
     if (response.status !== 504) {
         return false;
@@ -128,7 +129,11 @@ async function peekPlanLimitStatus(response, options = {}) {
         try {
             const text = new TextDecoder().decode(buf);
             try {
-                recordPlanLimitStatus(JSON.parse(text));
+                const parsed = JSON.parse(text);
+                if (hasPlanLimitStatusPayload(parsed)) {
+                    const { recordPlanLimitStatus } = await import('../lib/plan-limit-nag.js');
+                    recordPlanLimitStatus(parsed);
+                }
             }
             catch {
                 // Malformed JSON must be ignored silently.
@@ -162,6 +167,12 @@ async function peekPlanLimitStatus(response, options = {}) {
         return response;
     }
 }
+function hasPlanLimitStatusPayload(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return false;
+    }
+    return Object.hasOwn(body, 'planLimits') || Object.hasOwn(body, 'thresholdCrossings');
+}
 /**
  * Map Cognito JWT paths onto parallel Bearer `hqk_` routes under `/v1/keys/…`.
  * Returns null when no keyed route exists (caller must fail closed).
@@ -252,7 +263,7 @@ export async function vaultApiFetch(opts) {
     const { path, url } = resolveVaultApiRequestTarget(opts);
     const method = opts.method ?? 'GET';
     const safeUrl = url.search ? `${url.origin}${url.pathname}?<redacted>` : `${url.origin}${url.pathname}`;
-    Sentry.addBreadcrumb({
+    await addVaultBreadcrumb({
         category: "http",
         message: `${method} ${path}`,
         level: "info",
@@ -282,7 +293,7 @@ export async function vaultApiFetch(opts) {
             // Keep the original transport failure and its bounded, redacted trail on
             // both the first request and the single retry.
             const code = networkTransportErrorCode(err);
-            Sentry.addBreadcrumb({
+            await addVaultBreadcrumb({
                 category: "http",
                 message: `${method} ${path} → transport error`,
                 level: "warning",
@@ -293,7 +304,7 @@ export async function vaultApiFetch(opts) {
     };
     const response = await fetchWithLambdaInvokeRetry(fetchWithTransportBreadcrumb, method.toUpperCase() === 'GET' && opts.body === undefined, opts.signal);
     if (!response.ok) {
-        Sentry.addBreadcrumb({
+        await addVaultBreadcrumb({
             category: "http",
             message: `${method} ${path} → ${response.status}`,
             level: "warning",
@@ -308,7 +319,9 @@ export async function vaultApiFetch(opts) {
         const companyUid = typeof opts.body?.companyUid === "string"
             ? opts.body.companyUid
             : /\/(cmp_[^/?]+)/.exec(opts.path)?.[1];
-        const planGate = await planGateErrorFromResponse(response, companyUid);
+        const planGate = response.status === 402
+            ? await (await import('./plan-gate-error.js')).planGateErrorFromResponse(response, companyUid)
+            : { error: null, response };
         if (planGate.error)
             throw planGate.error;
         return planGate.response;
@@ -346,7 +359,7 @@ export async function vaultApiFetchPublic(opts) {
     const safeUrl = url.search
         ? `${url.origin}${url.pathname}?<redacted>`
         : `${url.origin}${url.pathname}`;
-    Sentry.addBreadcrumb({
+    await addVaultBreadcrumb({
         category: 'http',
         message: `GET ${opts.path}`,
         level: 'info',
@@ -357,7 +370,7 @@ export async function vaultApiFetchPublic(opts) {
         headers: { 'Content-Type': 'application/json' },
     }), true);
     if (!response.ok) {
-        Sentry.addBreadcrumb({
+        await addVaultBreadcrumb({
             category: 'http',
             message: `GET ${opts.path} → ${response.status}`,
             level: 'warning',

package/package.json

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