@indigoai-us/hq-cli 5.289.0 → 5.291.0

package/dist/lib/mesh/live/daemon/state.js

@@ -29,13 +29,45 @@ export function readDaemonState(dir) {
         return null;
     }
 }
-export function writeDaemonState(dir, state) {
+const DAEMON_STATE_RENAME_RETRY_DELAYS_MS = [20, 50, 100];
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)), 0, 0, ms);
+}
+function isTransientRenameContention(err) {
+    return err !== null && typeof err === "object" && "code" in err &&
+        (err.code === "EPERM" || err.code === "EBUSY");
+}
+export function writeDaemonState(dir, state, options = {}) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     const dest = daemonStatePath(dir);
     const tmp = path.join(dir, `.state.tmp.${process.pid}.${Date.now()}`);
     const body = `${JSON.stringify(state, null, 2)}\n`;
     fs.writeFileSync(tmp, body, { mode: 0o600 });
-    fs.renameSync(tmp, dest);
+    const renameSync = options.renameSync ?? fs.renameSync;
+    const waitSync = options.sleepSync ?? sleepSync;
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                renameSync(tmp, dest);
+                break;
+            }
+            catch (err) {
+                const delay = DAEMON_STATE_RENAME_RETRY_DELAYS_MS[attempt];
+                if (!isTransientRenameContention(err) || delay === undefined)
+                    throw err;
+                waitSync(delay);
+            }
+        }
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* Preserve the rename failure; the destination remains the prior complete state. */
+        }
+        throw err;
+    }
     try {
         fs.chmodSync(dest, 0o600);
     }

package/dist/main.js

@@ -36,7 +36,7 @@ import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js
 import { callbackPortBusyMessage, DEFAULT_CALLBACK_PORT } from "./utils/callback-port-busy.js";
 import { DEFAULT_COGNITO } from "./utils/cognito-session.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, offerUpgradeLink, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, offerTeamUpgrade, offerUpgradeLink, planGateErrorFromVaultError, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
 import { refreshVersionCache, staleAgainstCachedLatest, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
@@ -344,6 +344,9 @@ function qmdSpawnFailureCaptureContext(err) {
 }
 /** 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
+    // refusal (402 / PLAN_LIMIT_* from a sync, share or skill upload).
+    const planGate = planGateErrorFromVaultError(err);
     // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
     // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
     // Unix behavior with no user-facing degradation — exit cleanly (0) and
@@ -416,24 +419,32 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${callbackPortBusyMessage(err, DEFAULT_COGNITO.port ?? DEFAULT_CALLBACK_PORT)}\n`);
         deps.setExitCode(1);
     }
-    else if (isPlanGateError(err)) {
+    else if (planGate) {
         // Plan denials are expected product limits, never a CLI crash. The
         // server URL is always shown. Company refusals that the Workforce
         // checkout satisfies retain the direct Stripe checkout action.
+        //
+        // A plan-limit refusal (a Starter hard stop) always prints its reason,
+        // usage and fix options, even non-interactively: the user can fix it
+        // without upgrading, and an agent or script reading stderr needs the
+        // reason to act on it. Feature refusals keep the URL-only
+        // non-interactive form, because upgrading is their only fix.
         const interactive = deps.interactive ?? canOfferTeamUpgrade(deps.argv);
-        const message = formatPlanGateError(err, { urlOnly: !interactive });
+        const message = formatPlanGateError(planGate, {
+            urlOnly: !interactive && planGate.code !== "PLAN_LIMIT_EXCEEDED",
+        });
         deps.stderr.write(interactive ? `hq: ${message}\n` : `${message}\n`);
-        const promptExposure = isCliLimitResourceKind(err.details.resource ?? "")
-            ? queueCliLimitNoticeExposure(err.details.resource, "refusal", err.details.companyUid)
+        const promptExposure = isCliLimitResourceKind(planGate.details.resource ?? "")
+            ? queueCliLimitNoticeExposure(planGate.details.resource, "refusal", planGate.details.companyUid)
             : null;
         deps.setExitCode(1);
-        if (interactive && err.details.upgradeUrl) {
-            const companyUid = err.details.companyUid;
+        if (interactive && planGate.details.upgradeUrl) {
+            const companyUid = planGate.details.companyUid;
             const isCompanyWorkforceCheckout = typeof companyUid === "string" &&
                 /^cmp_[A-Za-z0-9_-]+$/.test(companyUid) &&
-                (err.code === "PLAN_REQUIRED" ||
-                    err.code === "MEETING_PLAN_REQUIRED" ||
-                    err.code === "BILLING_REQUIRED");
+                (planGate.code === "PLAN_REQUIRED" ||
+                    planGate.code === "MEETING_PLAN_REQUIRED" ||
+                    planGate.code === "BILLING_REQUIRED");
             if (isCompanyWorkforceCheckout && companyUid) {
                 try {
                     const upgraded = await offerTeamUpgrade(async () => {
@@ -450,7 +461,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
                     const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
                     deps.stderr.write(`hq: ${message}\n`);
                     try {
-                        const opened = await offerUpgradeLink(err.details.upgradeUrl, {
+                        const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
                             interactive: true,
                             argv: deps.argv,
                             ask: deps.ask,
@@ -467,7 +478,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             }
             else {
                 try {
-                    const opened = await offerUpgradeLink(err.details.upgradeUrl, {
+                    const opened = await offerUpgradeLink(planGate.details.upgradeUrl, {
                         interactive: true,
                         argv: deps.argv,
                         ask: deps.ask,

package/dist/utils/plan-gate-error.d.ts

@@ -1,8 +1,15 @@
+import { type PlanLimitFreeMonth } from "../lib/billing/free-month.js";
 export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED" | "MEETING_PLAN_REQUIRED"
 /** A PERSONAL scope asked for a feature the paid Individual plan includes. */
  | "PERSONAL_PLAN_REQUIRED"
 /** External agent enrollment was denied by the company plan. */
  | "BILLING_REQUIRED";
+/** One over-limit dimension, as hq-pro's hard-stop 402 body names it. */
+export interface PlanGateResourceUsage {
+    resource: string;
+    used: number;
+    limit: number;
+}
 export interface PlanGateDetails {
     resource?: string;
     feature?: string;
@@ -12,6 +19,14 @@ export interface PlanGateDetails {
     reason?: string;
     /** Company target from request context or the server's UID-keyed billing URL. */
     companyUid?: string;
+    /** Hard-stop 402: the create action the server refused, e.g. `secrets.create`. */
+    blocked?: string;
+    /** Hard-stop 402: every over-limit dimension, in server order. */
+    resources?: PlanGateResourceUsage[];
+    /** Hard-stop 402: how far back each over resource must come, keyed by resource. */
+    fixOptions?: Record<string, number>;
+    /** Hard-stop 402: the free-month offer, present only when it stands. */
+    freeMonth?: PlanLimitFreeMonth;
 }
 /** One renderer for server-selected upgrade links across CLI plan refusals. */
 export declare function formatUpgradeRefusal(reason: string, upgradeUrl: string | undefined, options?: {
@@ -46,6 +61,15 @@ export declare function offerTeamUpgrade(onConfirm: () => Promise<void>, deps?:
 }): Promise<boolean>;
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export declare function planGateErrorFromPayload(status: number, body: unknown, companyUid?: string): PlanGateError | null;
+/**
+ * Recognise a plan-limit refusal carried by an `@indigoai-us/hq-cloud`
+ * `VaultClientError` (sync, share, skill upload). Duck-typed so hq-cli keeps
+ * working across hq-cloud releases: the error exposes `statusCode`, `code`,
+ * `upgradeUrl` and the raw response `body`. The raw body is decoded first so
+ * the server's message, fix options and free month survive; a bare code (a
+ * personal presign row has no body) still becomes a refusal with its link.
+ */
+export declare function planGateErrorFromVaultError(err: unknown): PlanGateError | null;
 /**
  * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.

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

@@ -3,17 +3,93 @@
  * fields on a typed error lets the CLI boundary render one safe, consistent
  * message instead of every command parsing and printing a server response.
  */
-import { renderPersonalPlanFeatureNotice } from "../lib/plan-limit-nag.js";
+import { PLAN_LIMIT_DIMENSION_LABELS, renderPersonalPlanFeatureNotice, } from "../lib/plan-limit-nag.js";
 import { withCliLimitEntrySurface } from "../lib/billing/plan-limit-upgrade-url.js";
+import { parseFreeMonth, } from "../lib/billing/free-month.js";
+const GIB = 1024 ** 3;
+const MIB = 1024 ** 2;
+const KIB = 1024;
+function formatStorageBytes(bytes) {
+    const round = (value) => String(Math.round(value * 10) / 10);
+    if (bytes >= GIB)
+        return `${round(bytes / GIB)} GB`;
+    if (bytes >= MIB)
+        return `${round(bytes / MIB)} MB`;
+    if (bytes >= KIB)
+        return `${round(bytes / KIB)} KB`;
+    return `${bytes} bytes`;
+}
+function formatResourceAmount(resource, amount) {
+    return resource === "storageBytes" ? formatStorageBytes(amount) : String(amount);
+}
+function resourceLabel(resource) {
+    const label = PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource;
+    return label.charAt(0).toUpperCase() + label.slice(1);
+}
+/** The trim-back action for one resource, phrased as what the user does. */
+function resourceFixAction(resource) {
+    switch (resource) {
+        case "users":
+            return "Remove members";
+        case "secrets":
+            return "Delete secrets";
+        case "integrations":
+            return "Disconnect integrations";
+        case "storageBytes":
+            return "Delete files";
+        case "agents":
+            return "Deprovision agents";
+        case "deployments":
+            return "Remove deployments";
+        default:
+            return `Reduce ${PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource}`;
+    }
+}
+/**
+ * Render a plan-limit refusal: the server's sentence, where each over
+ * resource stands, then every way out the server offered. Only the fix options
+ * the server actually sent are listed, so the CLI never suggests trimming a
+ * dimension nobody measured.
+ */
+function planLimitRefusalText(head, details) {
+    const lines = [head];
+    for (const row of details.resources ?? []) {
+        lines.push(`  ${resourceLabel(row.resource)}: ` +
+            `${formatResourceAmount(row.resource, row.used)} of ` +
+            `${formatResourceAmount(row.resource, row.limit)} used.`);
+    }
+    const fixes = [];
+    const freeMonthUrl = safeUpgradeUrl(details.freeMonth?.url);
+    if (details.freeMonth?.eligible && freeMonthUrl) {
+        fixes.push(`Start your free month — add a card, first month free: ${freeMonthUrl}`);
+    }
+    for (const [resource, target] of Object.entries(details.fixOptions ?? {})) {
+        fixes.push(`${resourceFixAction(resource)} to make room (your plan allows ` +
+            `${formatResourceAmount(resource, target)}).`);
+    }
+    if (fixes.length > 0) {
+        fixes.push("Upgrade your plan.");
+        lines.push("  Ways to sort it:");
+        fixes.forEach((fix, index) => lines.push(`    ${index + 1}. ${fix}`));
+    }
+    return lines.join("\n");
+}
 function planGateReason(code, details) {
+    if (code === "PLAN_LIMIT_EXCEEDED") {
+        const head = details.reason?.trim()
+            ? details.reason.trim()
+            : typeof details.resource === "string" &&
+                typeof details.used === "number" &&
+                typeof details.limit === "number"
+                ? `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`
+                : details.resources?.length || details.fixOptions || details.freeMonth
+                    ? "Your plan limit has been reached."
+                    : undefined;
+        if (head)
+            return planLimitRefusalText(head, 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);
     }
@@ -171,6 +247,17 @@ export function planGateErrorFromPayload(status, body, companyUid) {
     const code = payload.code;
     const upgradeUrl = safeUpgradeUrl(payload.upgradeUrl);
     const targetCompanyUid = companyUid ?? companyUidFromPlanUpgradeUrl(upgradeUrl);
+    // Starter hard stops. The canonical body is `{ error: "plan_limit_reached",
+    // code: "PLAN_LIMIT_EXCEEDED", blocked, resources, message, fixOptions,
+    // freeMonth?, upgradeUrl }`; older servers send the body without `code`, the
+    // membership gate's legacy `{ code: "PLAN_LIMIT_EXCEEDED", resource, used,
+    // limit }`, or a personal presign row `{ code: "PLAN_LIMIT_REACHED" }`. All
+    // of them are the same refusal to the user, so they share one code.
+    if (payload.error === PLAN_LIMIT_REACHED_ERROR ||
+        code === "PLAN_LIMIT_EXCEEDED" ||
+        code === "PLAN_LIMIT_REACHED") {
+        return planLimitRefusalFromPayload(payload, upgradeUrl, targetCompanyUid);
+    }
     const planLimit = payload.planLimit !== null &&
         typeof payload.planLimit === "object" &&
         !Array.isArray(payload.planLimit)
@@ -184,8 +271,7 @@ export function planGateErrorFromPayload(status, body, companyUid) {
             return null;
         }
     }
-    else if (code !== "PLAN_LIMIT_EXCEEDED" &&
-        code !== "PLAN_REQUIRED" &&
+    else if (code !== "PLAN_REQUIRED" &&
         code !== "MEETING_PLAN_REQUIRED") {
         return null;
     }
@@ -204,6 +290,130 @@ export function planGateErrorFromPayload(status, body, companyUid) {
         ...(targetCompanyUid ? { companyUid: targetCompanyUid } : {}),
     });
 }
+/** Wire value of `error` on hq-pro's hard-stop 402 body. Never shown to users. */
+const PLAN_LIMIT_REACHED_ERROR = "plan_limit_reached";
+function finiteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function parseResources(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const rows = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const row = raw;
+        const used = finiteNonNegative(row.used);
+        const limit = finiteNonNegative(row.limit);
+        if (typeof row.resource !== "string" || used === undefined || limit === undefined) {
+            continue;
+        }
+        rows.push({ resource: row.resource, used, limit });
+    }
+    return rows.length > 0 ? rows : undefined;
+}
+function parseFixOptions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const fix = {};
+    for (const [resource, target] of Object.entries(value)) {
+        const amount = finiteNonNegative(target);
+        if (amount !== undefined)
+            fix[resource] = amount;
+    }
+    return Object.keys(fix).length > 0 ? fix : undefined;
+}
+function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
+    // `message` is the customer sentence. A legacy `error` string is prose only
+    // when it is not a machine token (`plan_limit_reached`, or the code itself).
+    const reason = typeof payload.message === "string" && payload.message.trim()
+        ? payload.message
+        : typeof payload.error === "string" &&
+            payload.error.trim() &&
+            payload.error !== PLAN_LIMIT_REACHED_ERROR &&
+            payload.error !== payload.code
+            ? payload.error
+            : undefined;
+    const resources = parseResources(payload.resources);
+    const fixOptions = parseFixOptions(payload.fixOptions);
+    const parsedFreeMonth = parseFreeMonth(payload.freeMonth);
+    const freeMonthUrl = safeUpgradeUrl(parsedFreeMonth?.url);
+    const freeMonth = parsedFreeMonth
+        ? {
+            eligible: true,
+            ...(parsedFreeMonth.trialDays !== undefined
+                ? { trialDays: parsedFreeMonth.trialDays }
+                : {}),
+            ...(freeMonthUrl ? { url: freeMonthUrl } : {}),
+        }
+        : undefined;
+    const used = finiteNonNegative(payload.used);
+    const limit = finiteNonNegative(payload.limit);
+    return new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+        ...(typeof payload.resource === "string" ? { resource: payload.resource } : {}),
+        ...(used !== undefined ? { used } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(typeof payload.blocked === "string" ? { blocked: payload.blocked } : {}),
+        ...(resources ? { resources } : {}),
+        ...(fixOptions ? { fixOptions } : {}),
+        ...(freeMonth ? { freeMonth } : {}),
+        ...(upgradeUrl ? { upgradeUrl } : {}),
+        ...(reason ? { reason } : {}),
+        ...(companyUid ? { companyUid } : {}),
+    });
+}
+/** Wire codes that mark a vault/sync error as a plan-limit refusal. */
+const PLAN_LIMIT_ERROR_CODES = new Set([
+    "PLAN_LIMIT_EXCEEDED",
+    "PLAN_LIMIT_REACHED",
+    PLAN_LIMIT_REACHED_ERROR,
+]);
+/**
+ * Recognise a plan-limit refusal carried by an `@indigoai-us/hq-cloud`
+ * `VaultClientError` (sync, share, skill upload). Duck-typed so hq-cli keeps
+ * working across hq-cloud releases: the error exposes `statusCode`, `code`,
+ * `upgradeUrl` and the raw response `body`. The raw body is decoded first so
+ * the server's message, fix options and free month survive; a bare code (a
+ * personal presign row has no body) still becomes a refusal with its link.
+ */
+export function planGateErrorFromVaultError(err) {
+    if (isPlanGateError(err))
+        return err;
+    if (!err || typeof err !== "object")
+        return null;
+    const candidate = err;
+    const code = typeof candidate.code === "string" ? candidate.code : undefined;
+    const isPlanLimitCode = code !== undefined && PLAN_LIMIT_ERROR_CODES.has(code);
+    if (candidate.statusCode !== 402 && !isPlanLimitCode)
+        return null;
+    if (typeof candidate.body === "string" && candidate.body.trim()) {
+        try {
+            const decoded = planGateErrorFromPayload(402, JSON.parse(candidate.body));
+            if (decoded) {
+                if (!decoded.details.upgradeUrl) {
+                    const upgradeUrl = safeUpgradeUrl(candidate.upgradeUrl);
+                    if (upgradeUrl) {
+                        return new PlanGateError(decoded.code, { ...decoded.details, upgradeUrl });
+                    }
+                }
+                return decoded;
+            }
+        }
+        catch {
+            // Not JSON: fall through to the structured fields on the error itself.
+        }
+    }
+    if (!isPlanLimitCode)
+        return null;
+    return planLimitRefusalFromPayload({
+        code,
+        ...(typeof candidate.message === "string"
+            ? { error: candidate.message }
+            : {}),
+    }, safeUpgradeUrl(candidate.upgradeUrl), undefined);
+}
 /**
  * Decode the supported plan-gate envelopes. Malformed, unrelated,
  * or non-402 responses retain their existing command-specific handling.

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

@@ -56,6 +56,7 @@
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
+import * as fs from "node:fs";
 import { type RunningInstall, type UpdateResult } from "./version-gate.js";
 import { type RestartDaemonResult } from "../lib/mesh/live/daemon/install.js";
 /**
@@ -136,6 +137,8 @@ export interface SelfUpdateDeps {
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;
+    /** Same-filesystem install rename, injectable for rollback tests. */
+    renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;