@indigoai-us/hq-cli 5.162.0 → 5.164.0

package/dist/utils/plan-gate-error.js

@@ -4,19 +4,74 @@
  * message instead of every command parsing and printing a server response.
  */
 import { renderPersonalPlanFeatureNotice } from "../lib/plan-limit-nag.js";
-const TEAM_UPGRADE_HINT = "Run `hq billing upgrade` to move to HQ Workforce.";
+function planGateReason(code, details) {
+    if (details.reason?.trim())
+        return details.reason.trim();
+    if (code === "PLAN_LIMIT_EXCEEDED" &&
+        typeof details.resource === "string" &&
+        typeof details.used === "number" &&
+        typeof details.limit === "number") {
+        return `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`;
+    }
+    if (code === "PERSONAL_PLAN_REQUIRED") {
+        return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", null);
+    }
+    if (code === "MEETING_PLAN_REQUIRED") {
+        return "HQ Workforce plan required to invite a meeting bot.";
+    }
+    if (code === "BILLING_REQUIRED") {
+        return "Upgrade the company plan before enrolling an external agent.";
+    }
+    return "HQ Workforce plan required for this feature.";
+}
+/** One renderer for server-selected upgrade links across CLI plan refusals. */
+export function formatUpgradeRefusal(reason, upgradeUrl, options = {}) {
+    const safeUrl = safeUpgradeUrl(upgradeUrl);
+    if (options.urlOnly && safeUrl)
+        return safeUrl;
+    if (!safeUrl)
+        return reason;
+    return `${reason}\nUpgrade: ${safeUrl}`;
+}
+function safeUpgradeUrl(value) {
+    if (typeof value !== "string" ||
+        value.trim() !== value ||
+        !/^https:\/\//i.test(value)) {
+        return undefined;
+    }
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            !url.hostname ||
+            url.username ||
+            url.password) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return value;
+}
+/** Recover a company UID only from the server's UID-keyed billing callback. */
+export function companyUidFromPlanUpgradeUrl(value) {
+    const safeUrl = safeUpgradeUrl(value);
+    if (!safeUrl)
+        return undefined;
+    const callbackUrl = new URL(safeUrl).searchParams.get("callbackUrl");
+    if (!callbackUrl)
+        return undefined;
+    const match = /^\/api\/companies\/(cmp_[A-Za-z0-9_-]+)\/billing\/upgrade\/?$/.exec(callbackUrl);
+    return match?.[1];
+}
+function formatPlanGateErrorText(code, details) {
+    return formatUpgradeRefusal(planGateReason(code, details), details.upgradeUrl);
+}
 export class PlanGateError extends Error {
     code;
     details;
     constructor(code, details) {
-        // Commands with their own expected-error boundary commonly print
-        // `err.message`. Keeping the friendly copy here means those boundaries
-        // retain the same plan-gate voice as main.ts without per-command handling.
-        // The HQ Workforce hint is company advice; a personal denial ends at its
-        // own notice, which already names the Individual plan and its checkout.
-        super(code === "PERSONAL_PLAN_REQUIRED"
-            ? formatPlanGateDetails(code, details)
-            : [formatPlanGateDetails(code, details), TEAM_UPGRADE_HINT].join("\n"));
+        super(formatPlanGateErrorText(code, details));
         this.code = code;
         this.details = details;
         this.name = "PlanGateError";
@@ -26,56 +81,52 @@ export function isPlanGateError(err) {
     return err instanceof PlanGateError;
 }
 /** Plain, stable CLI copy for plan-gated resource creation. */
-function formatPlanGateDetails(code, details) {
-    const existingResourcesNote = "Existing resources will keep working.";
-    if (code === "PLAN_LIMIT_EXCEEDED" &&
-        typeof details.resource === "string" &&
-        typeof details.used === "number" &&
-        typeof details.limit === "number") {
-        const upgrade = typeof details.upgradeUrl === "string"
-            ? `Upgrade to HQ Workforce ($500/mo) to remove limits: ${details.upgradeUrl}`
-            : "Upgrade to HQ Workforce ($500/mo) to remove limits.";
-        return [
-            `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`,
-            upgrade,
-            existingResourcesNote,
-        ].join("\n");
-    }
-    // A personal scope is not a workspace: it has no members to trim, no $500
-    // tier to buy, and nothing of its own is paused. One line, the plan's own
-    // copy, and no company remedy.
-    if (code === "PERSONAL_PLAN_REQUIRED") {
-        return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", details.upgradeUrl ?? null);
-    }
-    const upgrade = typeof details.upgradeUrl === "string"
-        ? `Upgrade to HQ Workforce ($500/mo) to remove limits: ${details.upgradeUrl}`
-        : "Upgrade to HQ Workforce ($500/mo) to remove limits.";
-    return [
-        "HQ Workforce plan required for this feature.",
-        upgrade,
-        existingResourcesNote,
-    ].join("\n");
-}
-export function formatPlanGateError(err) {
-    if (err.code === "PERSONAL_PLAN_REQUIRED") {
-        return formatPlanGateDetails(err.code, err.details);
-    }
-    return [
-        formatPlanGateDetails(err.code, err.details),
-        TEAM_UPGRADE_HINT,
-    ].join("\n");
+export function formatPlanGateError(err, options = {}) {
+    return formatUpgradeRefusal(planGateReason(err.code, err.details), err.details.upgradeUrl, options);
 }
 export function canOfferTeamUpgrade(argv = process.argv) {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY) &&
         !process.env.CI &&
         !argv.includes("--json");
 }
-/** Ask once, only on a real interactive terminal. */
+/** Ask before opening the exact URL returned by the server. */
+export async function offerUpgradeLink(url, deps = {}) {
+    const safeUrl = safeUpgradeUrl(url);
+    if (!safeUrl)
+        return false;
+    if (!(deps.interactive ?? canOfferTeamUpgrade(deps.argv)))
+        return false;
+    let answer;
+    if (deps.ask) {
+        answer = await deps.ask("Open upgrade link now? [y/N] ");
+    }
+    else {
+        const { createInterface } = await import("node:readline/promises");
+        const readline = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            answer = await readline.question("Open upgrade link now? [y/N] ");
+        }
+        finally {
+            readline.close();
+        }
+    }
+    if (!/^y(?:es)?$/i.test(answer.trim()))
+        return false;
+    if (deps.openUrl) {
+        await deps.openUrl(safeUrl);
+    }
+    else {
+        const { default: open } = await import("open");
+        await open(safeUrl);
+    }
+    return true;
+}
+/** Legacy checkout callback retained for callers outside the shared refusal paths. */
 export async function offerTeamUpgrade(onConfirm, deps = {}) {
     if (!(deps.interactive ?? canOfferTeamUpgrade(deps.argv)))
         return false;
     if (deps.ask) {
-        const answer = await deps.ask("Upgrade to HQ Workforce ($500/mo) now? [y/N] ");
+        const answer = await deps.ask("Upgrade now? (opens checkout) [y/N] ");
         if (!/^y(?:es)?$/i.test(answer.trim()))
             return false;
         await onConfirm();
@@ -84,7 +135,7 @@ export async function offerTeamUpgrade(onConfirm, deps = {}) {
     const { createInterface } = await import("node:readline/promises");
     const readline = createInterface({ input: process.stdin, output: process.stderr });
     try {
-        const answer = await readline.question("Upgrade to HQ Workforce ($500/mo) now? [y/N] ");
+        const answer = await readline.question("Upgrade now? (opens checkout) [y/N] ");
         if (!/^y(?:es)?$/i.test(answer.trim()))
             return false;
         await onConfirm();
@@ -106,28 +157,52 @@ export function planGateErrorFromPayload(status, body, companyUid) {
     // through to the company path below (defensive consumer).
     if (payload.error === "plan_feature_unavailable" &&
         payload.scope === "personal") {
+        const upgradeUrl = safeUpgradeUrl(payload.upgradeUrl);
         return new PlanGateError("PERSONAL_PLAN_REQUIRED", {
             ...(typeof payload.feature === "string"
                 ? { feature: payload.feature }
                 : {}),
-            ...(typeof payload.upgradeUrl === "string"
-                ? { upgradeUrl: payload.upgradeUrl }
-                : {}),
+            ...(upgradeUrl ? { upgradeUrl } : {}),
         });
     }
-    if (payload.code !== "PLAN_LIMIT_EXCEEDED" && payload.code !== "PLAN_REQUIRED") {
+    const code = payload.code;
+    const upgradeUrl = safeUpgradeUrl(payload.upgradeUrl);
+    const targetCompanyUid = companyUid ?? companyUidFromPlanUpgradeUrl(upgradeUrl);
+    const planLimit = payload.planLimit !== null &&
+        typeof payload.planLimit === "object" &&
+        !Array.isArray(payload.planLimit)
+        ? payload.planLimit
+        : undefined;
+    const isTeamPlanBillingRequired = code === "BILLING_REQUIRED" && planLimit?.requiredPlan === "team";
+    if (code === "BILLING_REQUIRED") {
+        if (!isTeamPlanBillingRequired ||
+            !targetCompanyUid ||
+            !/^cmp_[A-Za-z0-9_-]+$/.test(targetCompanyUid)) {
+            return null;
+        }
+    }
+    else if (code !== "PLAN_LIMIT_EXCEEDED" &&
+        code !== "PLAN_REQUIRED" &&
+        code !== "MEETING_PLAN_REQUIRED") {
         return null;
     }
-    return new PlanGateError(payload.code, {
+    const reason = typeof payload.message === "string"
+        ? payload.message
+        : typeof payload.error === "string" && payload.error !== payload.code
+            ? payload.error
+            : undefined;
+    return new PlanGateError(code, {
         ...(typeof payload.resource === "string" ? { resource: payload.resource } : {}),
+        ...(typeof payload.feature === "string" ? { feature: payload.feature } : {}),
         ...(typeof payload.used === "number" ? { used: payload.used } : {}),
         ...(typeof payload.limit === "number" ? { limit: payload.limit } : {}),
-        ...(typeof payload.upgradeUrl === "string" ? { upgradeUrl: payload.upgradeUrl } : {}),
-        ...(companyUid ? { companyUid } : {}),
+        ...(upgradeUrl ? { upgradeUrl } : {}),
+        ...(reason ? { reason } : {}),
+        ...(targetCompanyUid ? { companyUid: targetCompanyUid } : {}),
     });
 }
 /**
- * Decode only the two deliberate plan-gate envelopes. Malformed, unrelated,
+ * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.
  */
 export async function planGateErrorFromResponse(response, companyUid) {

package/dist/utils/self-update.d.ts

@@ -83,6 +83,8 @@ export type SelfUpdateAction =
  | "update-ineffective"
 /** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
  | "reexec"
+/** Updated with no re-exec (the `hq daemon` updater restarts the daemon instead). */
+ | "updated"
 /**
  * Unattended caller: replacing the CLI in place is unsafe here, so nothing
  * was attempted and the command runs on the current version. An attended
@@ -171,4 +173,11 @@ export declare function autoUpdateAndReexec(argv: readonly string[], latest: str
  * are preserved.
  */
 export declare function selfUpdateAndReexec(argv: readonly string[], deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
+/**
+ * `hq daemon` updater service: update to npm latest with nobody at a terminal
+ * and no re-exec. It runs as its own short-lived child of the daemon, so no
+ * user command is waiting on the package being replaced; after an "updated"
+ * outcome the daemon restarts itself onto the new version.
+ */
+export declare function daemonSelfUpdate(deps?: SelfUpdateDeps): Promise<SelfUpdateOutcome>;
 //# sourceMappingURL=self-update.d.ts.map

package/dist/utils/self-update.js

@@ -292,6 +292,10 @@ async function updateAndReexec(argv, flavor, known, deps) {
     catch {
         // Defensive only; the default helper already absorbs manager failures.
     }
+    if (!flavor.reexec) {
+        console.error(chalk.dim(`✓ hq-cli updated to ${latest}.`));
+        return { action: "updated", latest };
+    }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
     const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
     if (status === null) {
@@ -309,7 +313,7 @@ async function updateAndReexec(argv, flavor, known, deps) {
  * this resolve it from the registry.
  */
 export async function autoUpdateAndReexec(argv, latest, deps = {}) {
-    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true, onlyWhenAttended: true }, latest, deps);
+    return updateAndReexec(argv, { noun: "command", verbose: false, lock: true, onlyWhenAttended: true, reexec: true }, latest, deps);
 }
 /**
  * Rescue path: update to npm latest and re-exec the rescue on the new version.
@@ -318,6 +322,15 @@ export async function autoUpdateAndReexec(argv, latest, deps = {}) {
  * are preserved.
  */
 export async function selfUpdateAndReexec(argv, deps = {}) {
-    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true, onlyWhenAttended: false }, null, deps);
+    return updateAndReexec(argv, { noun: "rescue", verbose: true, lock: true, onlyWhenAttended: false, reexec: true }, null, deps);
+}
+/**
+ * `hq daemon` updater service: update to npm latest with nobody at a terminal
+ * and no re-exec. It runs as its own short-lived child of the daemon, so no
+ * user command is waiting on the package being replaced; after an "updated"
+ * outcome the daemon restarts itself onto the new version.
+ */
+export async function daemonSelfUpdate(deps = {}) {
+    return updateAndReexec([], { noun: "daemon update", verbose: false, lock: true, onlyWhenAttended: false, reexec: false }, null, deps);
 }
 //# sourceMappingURL=self-update.js.map

package/dist/utils/sentry-fingerprint.d.ts

@@ -9,6 +9,12 @@ export interface SentryMcpCollisionContext {
 }
 /** Return bounded, value-free Sentry context for an instrumented Codex name collision. */
 export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCollisionContext | null;
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export declare function installTreeTornSentryTagsFor(err: unknown): Record<string, string> | null;
 /**
  * Return a bounded `event.fingerprint` array for `err`, or `null` when `err`
  * carries no discriminator from the closed allowlist (in which case the caller
@@ -23,7 +29,7 @@ export declare function sentryMcpCollisionContextFor(err: unknown): SentryMcpCol
  * The InstallTreeTornError branch is the deliberate exception: it returns a
  * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
  * DEFAULT_GROUPING lead, because its chained loader cause makes the default
- * component unbounded (see the module header — HQ-CLI-21/22/23).
+ * component unbounded.
  *
  * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
  * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets

package/dist/utils/sentry-fingerprint.js

@@ -38,7 +38,9 @@
 //     in three different groups (hashes a4289a5e530e166ebdedea9d34dcad0a,
 //     b563c1b891bd975bdc605efc86034b44, b4ee254473ea249758617de1a98848fa —
 //     HQ-CLI-21/22/23). So that branch returns a FULLY EXPLICIT key with no
-//     default lead: ["InstallTreeTornError", "outcome:<token>"].
+//     default lead: ["InstallTreeTornError", "outcome:<token>"]. This PR keeps
+//     the existing explicit key so the new stale-tree outcome extends the current
+//     groups without splitting them.
 //
 // Genuinely different failure classes therefore form distinct, PREDICTABLE
 // groups, and everything with no bounded discriminator is left to default
@@ -156,17 +158,96 @@ const KNOWN_ERROR_NAMES = new Set([
     "QmdWorkdirMissingError",
     // A torn-install failure the bounded settle-wait + single re-exec could not
     // recover (HQ-CLI-1G/1H/1J/1K, HQ-CLI-1Y). Fingerprinted on its own branch below
-    // by the bounded `diagnostics.outcome`, so the whole family groups into ≤4 issues.
+    // by the normalized recovery result, so the family groups into two stable buckets.
     "InstallTreeTornError",
 ]);
 /**
- * The CLOSED set of InstallTreeTornError recovery outcomes worth their own
- * group. Anything else collapses to `outcome:other`, so the axis stays finite;
- * the carrier's message is fixed, so this outcome IS the only discriminator.
+ * The closed loader dialects accepted for the install_tree_phase tag. Anything
+ * outside this set collapses to unknown, so tags stay safe to aggregate.
  */
+const INSTALL_TREE_PHASES = new Set([
+    "cjs-enoent",
+    "cjs-package",
+    "cjs-path",
+    "cjs-relative",
+    "esm-enoent",
+    "esm-package",
+    "esm-path",
+    "eval-throw",
+    "resolve-enoent",
+    "unknown",
+]);
+const KNOWN_INSTALL_TREE_UPDATERS = new Map([
+    ["hq-cli-self-update", "cli-self-update"],
+    ["hq-cli-update", "box-timer"],
+    ["hq-cli-version-gate", "cli-version-gate"],
+    ["hq-desktop-app-cli-update", "desktop-app"],
+]);
 const KNOWN_INSTALL_TREE_OUTCOMES = new Set([
-    "guarded", "unsettled", "reexec-failed", "lock-held",
+    "guarded",
+    "unsettled",
+    "reexec-failed",
+    "lock-held",
+    "stale_tree",
 ]);
+function installTreeRecoveryOutcomeTag(value) {
+    return typeof value === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(value)
+        ? value
+        : null;
+}
+function installTreeStateTag(value) {
+    return value === "stale" ? "stale" : "in_flight";
+}
+function installTreePhaseTag(value) {
+    if (typeof value !== "string" || !INSTALL_TREE_PHASES.has(value))
+        return "unknown";
+    if (value === "esm-enoent" || value === "cjs-enoent")
+        return "loader_read";
+    if (value === "eval-throw")
+        return "module_evaluation";
+    if (value === "esm-package" || value === "cjs-package")
+        return "package_resolution";
+    if (value === "unknown")
+        return "unknown";
+    return "path_resolution";
+}
+function installTreeOsTag(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+/**
+ * Bounded, aggregatable tags for an unrecovered install-tree failure. Phase,
+ * outcome, state, and OS are closed values. Paths and raw lock-tool strings stay
+ * in context; only a known updater source becomes a tag.
+ */
+export function installTreeTornSentryTagsFor(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "InstallTreeTornError")
+        return null;
+    const diagnostics = record.diagnostics !== null && typeof record.diagnostics === "object"
+        ? record.diagnostics
+        : {};
+    const recoveryOutcome = installTreeRecoveryOutcomeTag(diagnostics.outcome);
+    const tags = {
+        install_tree_phase: installTreePhaseTag(diagnostics.dialect),
+        tree_state: installTreeStateTag(diagnostics.treeState),
+        os: installTreeOsTag(process.platform),
+    };
+    if (recoveryOutcome)
+        tags.recovery_outcome = recoveryOutcome;
+    const lockTool = diagnostics.lockTool;
+    const updaterSource = typeof lockTool === "string" ? KNOWN_INSTALL_TREE_UPDATERS.get(lockTool) : undefined;
+    if (updaterSource)
+        tags.updater_source = updaterSource;
+    return tags;
+}
 /** Fixed bucket for any error name outside the closed allowlist. */
 const FALLBACK_ERROR_NAME = "other";
 /**
@@ -241,7 +322,7 @@ function qmdDispositionToken(status, signal) {
  * The InstallTreeTornError branch is the deliberate exception: it returns a
  * fully explicit `["InstallTreeTornError", "outcome:<token>"]` with NO
  * DEFAULT_GROUPING lead, because its chained loader cause makes the default
- * component unbounded (see the module header — HQ-CLI-21/22/23).
+ * component unbounded.
  *
  * `rpcCode` is checked first so a gateway JSON-RPC fault groups by its protocol
  * code; the two carriers are disjoint in practice (the JSON-RPC throw site sets
@@ -284,10 +365,9 @@ export function sentryFingerprintFor(err) {
         ];
     }
     // A torn-install failure carries neither an rpcCode nor an HTTP status; its
-    // only bounded discriminator is the recovery `diagnostics.outcome`. Keyed
+    // only bounded discriminator is the existing recovery outcome. Keyed
     // BEFORE the rpc/status branches so the family groups into a bounded set of
-    // predictable issues (guarded / unsettled / reexec-failed / lock-held, plus the
-    // `outcome:other` fallback) rather than one fungible bucket.
+    // predictable issues rather than one fungible bucket.
     //
     // The key is FULLY EXPLICIT — it does NOT lead with DEFAULT_GROUPING. Leading
     // with the placeholder salts the appended tokens with Sentry's default grouping
@@ -300,16 +380,16 @@ export function sentryFingerprintFor(err) {
     // a4289a5e530e166ebdedea9d34dcad0a, b563c1b891bd975bdc605efc86034b44 and
     // b4ee254473ea249758617de1a98848fa (HQ-CLI-21/22/23) — defeating the very bound
     // this branch exists to enforce. The explicit key collapses them to one stable
-    // group per outcome, independent of machine, install path and which module tore.
+    // group per recovery outcome, independent of machine, install path and module.
     if (rawName === "InstallTreeTornError") {
         const diagnostics = record.diagnostics;
         const outcome = diagnostics !== null && typeof diagnostics === "object"
             ? diagnostics.outcome
             : undefined;
-        const token = typeof outcome === "string" && KNOWN_INSTALL_TREE_OUTCOMES.has(outcome)
-            ? `outcome:${outcome}`
-            : "outcome:other";
-        return ["InstallTreeTornError", token];
+        return [
+            "InstallTreeTornError",
+            `outcome:${installTreeRecoveryOutcomeTag(outcome) ?? "other"}`,
+        ];
     }
     const name = KNOWN_ERROR_NAMES.has(rawName) ? rawName : FALLBACK_ERROR_NAME;
     const rpcCode = record.rpcCode;

package/package.json

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