@indigoai-us/hq-cli 5.111.1 → 5.112.0

package/dist/lazy-commands.d.ts

@@ -1,55 +1,31 @@
-/**
- * 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.
- */
-import type { Command } from "commander";
+import { Command } from "commander";
 export type LazyCommand = {
-    /** The top-level token this matches — `hq <name> …`. */
+    /** Canonical top-level name; aliases resolve to this name. */
     name: string;
-    /** Registers this one command onto `program`, importing only its module. */
+    /** Registers every contributor for this root and no unrelated root. */
     register: (program: Command) => Promise<void>;
 };
 /**
- * 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.
+ * 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 declare const LAZY_COMMANDS: readonly LazyCommand[];
 /**
- * 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.
+ * 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 declare function registerCommandRoot(program: Command, root: string): Promise<boolean>;
+/**
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export declare function registerCommandCatalog(program: Command): void;
+/**
+ * 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 declare function findLazyCommand(argv: readonly string[]): LazyCommand | null;
 //# sourceMappingURL=lazy-commands.d.ts.map

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/lib/plan-limit-nag.d.ts

@@ -15,7 +15,7 @@
  * Additive only — never throws, never touches `process.exitCode`, never
  * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
  */
-export declare const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
+export declare const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
 export interface PlanLimitEntry {
     used: number;
     limit: number;

package/dist/lib/plan-limit-nag.js

@@ -19,7 +19,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-export const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
+export const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** Module-level last-seen cell — overwritten by each successful parse. */
 let lastSeen = null;
@@ -58,9 +58,24 @@ function parseEntry(value) {
     }
     return { used: rec.used, limit: rec.limit, over: rec.over };
 }
+/** Validate the server-provided optional upgrade URL without throwing. */
+function parseUpgradeUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = new URL(value);
+        // hq-pro permits an environment-configured console base URL, so stages
+        // cannot use a production-host allowlist. HTTPS is the trust boundary.
+        return parsed.protocol === "https:" ? parsed.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Defensively parse a decoded JSON body for a well-formed top-level
- * `planLimits` object. Malformed or absent → null. Never throws.
+ * `planLimits` object and its optional `upgradeUrl`. Malformed or absent →
+ * null. Never throws.
  */
 function parsePlanLimits(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body)) {
@@ -81,7 +96,12 @@ function parsePlanLimits(body) {
         out[key] = entry;
         anyValid = true;
     }
-    return anyValid ? out : null;
+    return anyValid
+        ? {
+            limits: out,
+            upgradeUrl: parseUpgradeUrl(planLimits.upgradeUrl),
+        }
+        : null;
 }
 /**
  * Record plan-limit status from a decoded JSON response body.
@@ -90,11 +110,11 @@ function parsePlanLimits(body) {
  */
 export function recordPlanLimitStatus(body) {
     try {
-        const limits = parsePlanLimits(body);
-        if (limits === null)
+        const status = parsePlanLimits(body);
+        if (status === null)
             return;
-        const anyOver = Object.values(limits).some((e) => e.over);
-        lastSeen = { limits, anyOver };
+        const anyOver = Object.values(status.limits).some((e) => e.over);
+        lastSeen = { ...status, anyOver };
     }
     catch {
         // Never throw from record path.
@@ -150,9 +170,9 @@ function writeShownAt(statePath, shownAt) {
 function withinDayWindow(shownAt, nowMs) {
     return nowMs - shownAt < DAY_MS;
 }
-function buildOverBox(overEntries) {
+function buildOverBox(overEntries, upgradeUrl) {
     const title = "⚠ HQ plan limit exceeded";
-    const upgrade = `Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
+    const upgrade = `Upgrade: ${upgradeUrl}`;
     const resourceLines = overEntries.map(([key, entry]) => `  ${key}: ${entry.used}/${entry.limit}`);
     const contentLines = [title, "", ...resourceLines, "", upgrade];
     const innerWidth = Math.max(...contentLines.map((l) => l.length), 40);
@@ -178,7 +198,8 @@ export function emitPlanLimitNag(opts = {}) {
         const write = opts.write ?? ((s) => process.stderr.write(s));
         const now = opts.now ?? (() => new Date());
         const statePath = opts.statePath ?? defaultStatePath();
-        const { limits, anyOver } = lastSeen;
+        const { limits, anyOver, upgradeUrl } = lastSeen;
+        const resolvedUpgradeUrl = upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL;
         const entries = Object.entries(limits);
         if (entries.length === 0)
             return;
@@ -191,7 +212,7 @@ export function emitPlanLimitNag(opts = {}) {
                 return;
             overShownThisSession = true;
             const overEntries = entries.filter(([, e]) => e.over);
-            const box = buildOverBox(overEntries);
+            const box = buildOverBox(overEntries, resolvedUpgradeUrl);
             write(chalk.yellow(box) + "\n");
             writeShownAt(statePath, nowMs);
             return;
@@ -203,7 +224,7 @@ export function emitPlanLimitNag(opts = {}) {
         if (worst === null)
             return;
         warningShownThisSession = true;
-        const line = `⚠ HQ free plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
+        const line = `⚠ HQ free plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${resolvedUpgradeUrl}`;
         write(chalk.yellow(line) + "\n");
     }
     catch {

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;