@indigoai-us/hq-cli 5.111.2 → 5.112.0

package/dist/lazy-commands.js

@@ -1,68 +1,67 @@
+import { Command } from "commander";
+import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+const commandCatalog = COMMAND_CATALOG;
 /**
- * Hot-command manifest for the entrypoint's lazy registration.
- *
- * main.ts used to import the entire ~60-module command graph at module scope,
- * so every invocation paid for every command. That is fine for a human typing
- * one command and ruinous for the calls automation makes in a loop: the
- * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
- * (each worker resolves credentials before every external command it executes),
- * and each of those processes spent ~0.75 CPU-seconds importing commands it
- * never ran — around half a core, continuously. Measured on Outpost 2
- * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
- *
- * A command listed here registers ITSELF and nothing else. Anything not listed
- * — `--help`, a bare `hq`, an unknown command, every other command — falls back
- * to `registerAllCommands`, the complete unchanged graph. That fallback is what
- * makes this safe to extend one command at a time: an entry is a performance
- * opt-in, never a behaviour change, and a command that is absent here is simply
- * as fast as it was before.
- *
- * This mirrors commands/scaffold-fast.ts, which does the same thing for the
- * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
- * parity test registers each entry BOTH ways and asserts the resulting command
- * shape is identical, so a manifest entry cannot silently diverge from the real
- * registration.
- *
- * TO ADD A COMMAND: it must register exactly one top-level command, be
- * registered onto `program` (not onto a subcommand group), and have no other
- * module contributing subcommands to it. The parity test enforces the shape;
- * these three conditions are what make the entry correct in the first place.
+ * One entry for every root, including groups that are assembled by several
+ * registrar modules. The routing metadata itself is generated from the eager
+ * command graph and checked in tests and the build.
  */
+export const LAZY_COMMANDS = commandCatalog.map((command) => ({
+    name: command.name,
+    register: async (program) => {
+        const registered = await registerCommandRoot(program, command.name);
+        if (!registered)
+            throw new Error(`No registration plan for '${command.name}'`);
+    },
+}));
 /**
- * The hot paths, in descending order of how often automation calls them.
- *
- * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
- * loop: every fleet worker shells through one of them before each external
- * command, which is exactly the shape that makes eager import expensive.
+ * Keep the registration seam at register-all.js. Besides making one place own
+ * the graph, this lets the torn-install recovery wrap failures while an update
+ * replaces the installed tree between startup and command registration.
  */
-export const LAZY_COMMANDS = [
-    {
-        name: "secrets",
-        register: async (program) => {
-            const { registerSecretsCommand } = await import("./commands/secrets.js");
-            registerSecretsCommand(program);
-        },
-    },
-    {
-        name: "run",
-        register: async (program) => {
-            const { registerRunCommand } = await import("./commands/run.js");
-            registerRunCommand(program);
-        },
-    },
-];
+export async function registerCommandRoot(program, root) {
+    const registration = await import("./register-all.js");
+    return registration.registerCommandRoot(program, root);
+}
+function commandDefinition(command) {
+    const stub = new Command(command.name)
+        .description(command.description);
+    for (const alias of command.aliases)
+        stub.alias(alias);
+    for (const argument of command.arguments) {
+        const name = `${argument.name}${argument.variadic ? "..." : ""}`;
+        stub.argument(argument.required ? `<${name}>` : `[${name}]`);
+    }
+    for (const option of command.options)
+        stub.option(option.flags, option.description);
+    if (command.hidden)
+        stub._hidden = true;
+    return stub;
+}
 /**
- * Resolve `process.argv` to a manifest entry, or null to use the full graph.
- *
- * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
- * before the command name, so argv[2] is the command token when there is one;
- * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
- * fallback, which is the intended behaviour — help must list every command.
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export function registerCommandCatalog(program) {
+    for (const command of commandCatalog)
+        program.addCommand(commandDefinition(command));
+}
+function commandForToken(token) {
+    return commandCatalog.find((candidate) => candidate.name === token || candidate.aliases.includes(token));
+}
+/**
+ * Resolve the root requested by Commander argv. Root help, a bare invocation,
+ * and unknown tokens deliberately return null so the lightweight catalog can
+ * preserve the complete help and unknown-command recovery surfaces.
  */
 export function findLazyCommand(argv) {
-    const name = argv[2];
-    if (typeof name !== "string")
+    const first = argv[2];
+    const token = first === "help" ? argv[3] : first;
+    if (typeof token !== "string" || token.startsWith("-"))
+        return null;
+    const command = commandForToken(token);
+    if (!command)
         return null;
-    return LAZY_COMMANDS.find((candidate) => candidate.name === name) ?? null;
+    return LAZY_COMMANDS.find((candidate) => candidate.name === command.name) ?? null;
 }
 //# sourceMappingURL=lazy-commands.js.map

package/dist/lib/core-utils/sentry-report.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics and never reads a
+ * hook payload or the process environment. The owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected rather
+ * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
+ * not a caller version match, determines what may leave the machine.
+ */
+import type { CaptureContext, SeverityLevel } from "@sentry/node";
+export declare const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+export declare const MAX_SENTRY_REPORT_TIMEOUT_MS = 5000;
+export declare const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2048;
+export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average"];
+export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
+export type SentryReportMetadata = Record<string, string | number | boolean>;
+export type SentryReportEvent = {
+    type: string;
+    message: string;
+    fingerprint: string;
+    level: SeverityLevel;
+    metadata: SentryReportMetadata;
+};
+export type SentryReportOptions = {
+    dryRun?: boolean;
+    /** Total time reserved for the report flush after validation. */
+    timeoutMs?: number;
+};
+export type SentryReportDependencies = {
+    sentry: {
+        captureMessage: (message: string, context?: CaptureContext | SeverityLevel) => string;
+        flush: (timeout?: number) => PromiseLike<boolean>;
+    };
+    stdout: Pick<NodeJS.WriteStream, "write">;
+    stderr: Pick<NodeJS.WriteStream, "write">;
+};
+export type SentryReportResult = {
+    code: 0 | 1;
+    event?: SentryReportEvent;
+    droppedMetadataKeys?: number;
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export declare function readSentryReportStdin(stdin: AsyncIterable<Buffer | string>): Promise<string | null>;
+/** Unknown metadata is ignored before this cap is evaluated. */
+export declare function exceedsSentryReportMetadataKeyCap(keys: Iterable<string>): boolean;
+/**
+ * Parse and validate the closed report schema without touching Sentry. The
+ * function intentionally returns an ordinary result instead of throwing so a
+ * hook can ignore the CLI exit code without creating an unhandled rejection.
+ */
+export declare function parseSentryReportEvent(stdin: string): SentryReportResult;
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export declare function reportSentryEvent(stdin: string, options?: SentryReportOptions, dependencies?: SentryReportDependencies): Promise<SentryReportResult>;
+//# sourceMappingURL=sentry-report.d.ts.map

package/dist/lib/core-utils/sentry-report.js

@@ -0,0 +1,255 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics and never reads a
+ * hook payload or the process environment. The owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected rather
+ * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
+ * not a caller version match, determines what may leave the machine.
+ */
+import * as Sentry from "@sentry/node";
+import { beforeSend } from "../../sentry-before-send.js";
+export const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+export const MAX_SENTRY_REPORT_TIMEOUT_MS = 5_000;
+export const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2_048;
+export const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+const MAX_SENTRY_REPORT_TYPE_BYTES = 64;
+const MAX_SENTRY_REPORT_MESSAGE_BYTES = 1_024;
+const MAX_SENTRY_REPORT_FINGERPRINT_BYTES = 128;
+const SENTRY_REPORT_LEVELS = new Set([
+    "fatal",
+    "error",
+    "warning",
+    "log",
+    "info",
+    "debug",
+]);
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export const ALLOWED_SENTRY_REPORT_METADATA_KEYS = [
+    "hook_name",
+    "hook_path",
+    "hook_event",
+    "tool_name",
+    "session_id",
+    "declared_timeout_ms",
+    "elapsed_ms",
+    "remaining_ms",
+    "watchdog_timeout_ms",
+    "hook_timeout_ms",
+    "hq_version",
+    "platform",
+    "load_average",
+];
+const ALLOWED_METADATA_KEYS = new Set(ALLOWED_SENTRY_REPORT_METADATA_KEYS);
+const SENTRY_REPORT_METADATA_KEY_HEADROOM = 2;
+// This tracks the schema rather than a separately-maintained literal. A caller
+// can send every recognised key with room for two later recognised fields,
+// while unknown keys are deliberately dropped.
+export const MAX_SENTRY_REPORT_METADATA_KEYS = ALLOWED_SENTRY_REPORT_METADATA_KEYS.length + SENTRY_REPORT_METADATA_KEY_HEADROOM;
+const defaultDependencies = {
+    sentry: Sentry,
+    stdout: process.stdout,
+    stderr: process.stderr,
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export async function readSentryReportStdin(stdin) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        totalBytes += bytes.length;
+        if (totalBytes > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+            return null;
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function isBoundedString(value, maxBytes) {
+    return typeof value === "string" && value.length > 0 && byteLength(value) <= maxBytes;
+}
+function isScalarMetadataValue(value) {
+    if (typeof value === "string")
+        return byteLength(value) <= MAX_SENTRY_REPORT_METADATA_VALUE_BYTES;
+    if (typeof value === "boolean")
+        return true;
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isAllowedMetadataValue(key, value) {
+    if (!isScalarMetadataValue(value))
+        return false;
+    if (key === "tool_name" || key === "session_id" || key === "hook_path") {
+        return typeof value === "string";
+    }
+    return true;
+}
+/** Unknown metadata is ignored before this cap is evaluated. */
+export function exceedsSentryReportMetadataKeyCap(keys) {
+    let recognisedKeys = 0;
+    for (const key of keys) {
+        if (!ALLOWED_METADATA_KEYS.has(key))
+            continue;
+        recognisedKeys++;
+        if (recognisedKeys > MAX_SENTRY_REPORT_METADATA_KEYS)
+            return true;
+    }
+    return false;
+}
+function invalidInput() {
+    return { code: 1 };
+}
+/**
+ * Parse and validate the closed report schema without touching Sentry. The
+ * function intentionally returns an ordinary result instead of throwing so a
+ * hook can ignore the CLI exit code without creating an unhandled rejection.
+ */
+export function parseSentryReportEvent(stdin) {
+    if (byteLength(stdin) > MAX_SENTRY_REPORT_PAYLOAD_BYTES)
+        return invalidInput();
+    let parsed;
+    try {
+        parsed = JSON.parse(stdin);
+    }
+    catch {
+        return invalidInput();
+    }
+    if (!isRecord(parsed))
+        return invalidInput();
+    const allowedTopLevel = new Set(["type", "message", "fingerprint", "level", "metadata"]);
+    if (Object.keys(parsed).some((key) => !allowedTopLevel.has(key)))
+        return invalidInput();
+    if (!isBoundedString(parsed.type, MAX_SENTRY_REPORT_TYPE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.message, MAX_SENTRY_REPORT_MESSAGE_BYTES))
+        return invalidInput();
+    if (!isBoundedString(parsed.fingerprint, MAX_SENTRY_REPORT_FINGERPRINT_BYTES))
+        return invalidInput();
+    if (typeof parsed.level !== "string" || !SENTRY_REPORT_LEVELS.has(parsed.level)) {
+        return invalidInput();
+    }
+    const rawMetadata = "metadata" in parsed ? parsed.metadata : {};
+    if (!isRecord(rawMetadata))
+        return invalidInput();
+    const metadataKeys = Object.keys(rawMetadata);
+    if (exceedsSentryReportMetadataKeyCap(metadataKeys))
+        return invalidInput();
+    const metadata = {};
+    let droppedMetadataKeys = 0;
+    for (const key of metadataKeys) {
+        if (!isScalarMetadataValue(rawMetadata[key]))
+            return invalidInput();
+        if (!ALLOWED_METADATA_KEYS.has(key)) {
+            droppedMetadataKeys++;
+            continue;
+        }
+        if (!isAllowedMetadataValue(key, rawMetadata[key]))
+            return invalidInput();
+        metadata[key] = rawMetadata[key];
+    }
+    return {
+        code: 0,
+        event: {
+            type: parsed.type,
+            message: parsed.message,
+            fingerprint: parsed.fingerprint,
+            level: parsed.level,
+            metadata,
+        },
+        droppedMetadataKeys,
+    };
+}
+function resolveTimeout(timeoutMs) {
+    const timeout = timeoutMs ?? DEFAULT_SENTRY_REPORT_TIMEOUT_MS;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_SENTRY_REPORT_TIMEOUT_MS)
+        return null;
+    return timeout;
+}
+function sentryEnvelope(event) {
+    return {
+        level: event.level,
+        fingerprint: [event.fingerprint],
+        tags: { sentry_event_type: event.type },
+        extra: event.metadata,
+    };
+}
+/** Build the same scrubbed event projection that the live SDK path uses. */
+function scrubbedSentryEnvelope(event) {
+    return beforeSend({
+        message: event.message,
+        ...sentryEnvelope(event),
+    }, {});
+}
+/**
+ * Resolve true only when the local transport queue drains within the budget.
+ * This does not confirm that the ingest service accepted the event.
+ */
+async function flushWithin(sentry, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        void Promise.resolve()
+            .then(() => sentry.flush(timeoutMs))
+            .then((flushed) => {
+            clearTimeout(timer);
+            resolve(flushed === true);
+        }, () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export async function reportSentryEvent(stdin, options = {}, dependencies = defaultDependencies) {
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+    const result = parseSentryReportEvent(stdin);
+    if (timeoutMs === null || result.code !== 0 || !result.event) {
+        dependencies.stderr.write("Invalid Sentry report input.\n");
+        return invalidInput();
+    }
+    if (result.droppedMetadataKeys) {
+        const noun = result.droppedMetadataKeys === 1 ? "key" : "keys";
+        dependencies.stderr.write(`Dropped ${result.droppedMetadataKeys} unsupported Sentry report metadata ${noun}.\n`);
+    }
+    const envelope = sentryEnvelope(result.event);
+    if (options.dryRun) {
+        const scrubbed = scrubbedSentryEnvelope(result.event);
+        if (scrubbed)
+            dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
+        return result;
+    }
+    try {
+        dependencies.sentry.captureMessage(result.event.message, envelope);
+        if (await flushWithin(dependencies.sentry, timeoutMs))
+            return result;
+    }
+    catch {
+        // Report failure below without exposing event fields or transport details.
+    }
+    dependencies.stderr.write("Sentry report failed.\n");
+    return invalidInput();
+}
+//# sourceMappingURL=sentry-report.js.map

package/dist/main.d.ts

@@ -5,6 +5,12 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
+/**
+ * Total time one CLI invocation may await foreground network work. This spans
+ * the hard version decision, pre-action observability, and release-health
+ * finalization; command execution itself does not consume this allowance.
+ */
+export declare const FOREGROUND_NETWORK_BUDGET_MS = 1500;
 export type StreamErrorDependencies = {
     stderr: Pick<typeof process.stderr, "write">;
     exit: (code: number) => void;

package/dist/main.js

@@ -9,7 +9,7 @@ import "./node-network-compat.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { initSentry, Sentry } from "./sentry.js";
+import { finishSentrySession, initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
@@ -41,7 +41,7 @@ import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
-import { findLazyCommand } from "./lazy-commands.js";
+import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
@@ -52,8 +52,57 @@ import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
-/** Hard upper bound for non-user-visible release-health finalization. */
-const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
+/**
+ * Total time one CLI invocation may await foreground network work. This spans
+ * the hard version decision, pre-action observability, and release-health
+ * finalization; command execution itself does not consume this allowance.
+ */
+export const FOREGROUND_NETWORK_BUDGET_MS = 1_500;
+/**
+ * Release health must always have a chance to flush an already-captured error
+ * and refresh the cache after a command. Reserve this before earlier work.
+ */
+const FINALIZATION_FOREGROUND_WAIT_MS = 500;
+/**
+ * A stalled version endpoint must leave the invocation heartbeat a chance to
+ * send. A timely blocked response is still enforced exactly as before.
+ */
+const VERSION_GATE_FOREGROUND_WAIT_MS = 750;
+/** Existing telemetry/health cap, now also bounded by the shared deadline. */
+const OBSERVABILITY_FOREGROUND_WAIT_MS = 1_200;
+/**
+ * Shared accounting for awaited foreground network work. Each lifecycle phase
+ * debits only the bounded await it performs; ordinary command runtime leaves
+ * the allowance untouched. Earlier phases reserve the finalization floor, so
+ * error flushing cannot disappear after a long command.
+ */
+class ForegroundNetworkBudget {
+    budgetMs;
+    now;
+    consumedMs = 0;
+    constructor(budgetMs = FOREGROUND_NETWORK_BUDGET_MS, now = () => performance.now()) {
+        this.budgetMs = budgetMs;
+        this.now = now;
+    }
+    timeoutFor(phaseMaximumMs, reservedMs = 0) {
+        return Math.max(0, Math.min(phaseMaximumMs, Math.floor(this.budgetMs - reservedMs - this.consumedMs)));
+    }
+    async waitFor(phaseMaximumMs, reservedMs, work) {
+        const timeoutMs = this.timeoutFor(phaseMaximumMs, reservedMs);
+        if (timeoutMs === 0)
+            return undefined;
+        const startedAt = this.now();
+        try {
+            return await work(timeoutMs);
+        }
+        finally {
+            // A timer cannot interrupt synchronous work. Do not let a blocked event
+            // loop consume the finalization reserve as though it were network wait.
+            this.consumedMs += Math.min(timeoutMs, Math.max(0, this.now() - startedAt));
+        }
+    }
+}
+let activeForegroundNetworkBudget;
 /**
  * The RUNNING install's own entrypoint (`<pkg>/dist/index.js`), used as the
  * torn-install recovery re-exec target. It must be this resolved path — never
@@ -110,17 +159,23 @@ program
     .version(CLI_VERSION);
 program.hook("preAction", async () => {
     // Both are best-effort and fully swallowed: neither can change the command's
-    // result or exit code. The 1.2s bound they carry is a TIMER, so it only
-    // preempts asynchronous work — synchronous work inside them runs to
-    // completion regardless, because the timer cannot be serviced while the
-    // event loop is blocked. Keep anything added here asynchronous, or
-    // separately cheap: this hook is on the path of EVERY hq command.
-    await Promise.all([
-        emitCliSessionStarted(),
-        reportCliClientHealthInvocation(),
-    ]);
+    // result or exit code. They receive only the shared pre-finalization
+    // allowance (up to 1.2s), and that bound is a TIMER, so it only preempts
+    // asynchronous work — synchronous work inside them runs to completion
+    // regardless, because the timer cannot be serviced while the event loop is
+    // blocked. Keep anything added here asynchronous, or separately cheap: this
+    // hook is on the path of EVERY hq command.
+    const budget = activeForegroundNetworkBudget;
+    if (!budget)
+        return;
+    await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
+        emitCliSessionStarted(timeoutMs),
+        reportCliClientHealthInvocation({ timeoutMs }),
+    ]));
 });
 export async function runCli() {
+    const foregroundNetworkBudget = new ForegroundNetworkBudget();
+    activeForegroundNetworkBudget = foregroundNetworkBudget;
     // Begin one registry refresh without awaiting it. Every command gate reads
     // only the client's held snapshot and falls back locally, so an offline or
     // slow registry cannot delay command parsing or alter a command failure.
@@ -149,12 +204,12 @@ export async function runCli() {
         //    `version-check.ts`); whichever fires first re-execs, and the child
         //    carries a guard env so it can never update again.
         if (!shouldSkipGate(process.argv)) {
-            const gate = await enforceVersionGate(async (decision) => {
+            const gate = (await foregroundNetworkBudget.waitFor(VERSION_GATE_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => enforceVersionGate(async (decision) => {
                 const outcome = await autoUpdateAndReexec(process.argv, decision.latestVersion);
                 if (outcome.action === "reexec")
                     reexecStatus = outcome.reexecStatus ?? 0;
                 return outcome.action === "reexec";
-            });
+            }, { timeoutMs }))) ?? "continue";
             if (gate === "reexec")
                 return;
             const cachedLatest = staleAgainstCachedLatest();
@@ -166,15 +221,11 @@ export async function runCli() {
                 }
             }
         }
-        // Register only what this invocation needs. A hot command named in the
-        // lazy manifest imports its own module and nothing else; everything else —
-        // `--help`, a bare `hq`, an unknown command, any command not on the
-        // manifest — falls back to the complete graph, so its behaviour is
-        // unchanged. See register-all.ts for the measurements that motivated this.
-        // The same lazy/full registration as before, wrapped so it recovers ONCE if
-        // a global reinstall is tearing the install tree out from under these
-        // deferred imports (Sentry HQ-CLI-1G/1H/1J/1K). Which modules are imported,
-        // and in what order, is unchanged — only the failure handling is added.
+        // Register every contributor for the selected root only. Root help and
+        // unknown-command recovery use generated metadata, so they keep the full
+        // Commander surface without evaluating every command implementation.
+        // Registration remains inside the torn-install recovery boundary: deferred
+        // import failures still receive the same one-shot settled-tree re-exec.
         const registration = await registerCommandsWithRecovery({
             register: async () => {
                 const lazy = findLazyCommand(process.argv);
@@ -182,8 +233,7 @@ export async function runCli() {
                     await lazy.register(program);
                 }
                 else {
-                    const { registerAllCommands } = await import("./register-all.js");
-                    registerAllCommands(program);
+                    registerCommandCatalog(program);
                 }
             },
             argv: process.argv,
@@ -207,16 +257,24 @@ export async function runCli() {
         // process.exitCode — safe to run after exit codes have been set.
         emitPlanLimitNag();
         // Release health: finalize the per-run session before the flush.
-        Sentry.endSession();
+        finishSentrySession();
         // Neither task may turn a successful command into Node's
         // `unsettled top-level await` exit. They are observability-only after the
         // command has completed, so a bounded best-effort wait is the terminal
-        // lifecycle boundary for this invocation.
-        await settleWithin([refreshVersionCache(), Sentry.flush(2000)], RELEASE_HEALTH_SETTLE_TIMEOUT_MS);
+        // lifecycle boundary for this invocation. The budget reserves this 500 ms
+        // slice even when the command itself was long-running.
+        const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+        await settleWithin([
+            refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+            Sentry.flush(releaseHealthTimeoutMs),
+        ], releaseHealthTimeoutMs);
         // Last, so it wins over anything the (skipped) command path would have
         // set: the re-exec'd child's status IS this invocation's result.
         if (reexecStatus !== null)
             process.exitCode = reexecStatus;
+        if (activeForegroundNetworkBudget === foregroundNetworkBudget) {
+            activeForegroundNetworkBudget = undefined;
+        }
     }
 }
 const defaultTopLevelErrorDependencies = {