@indigoai-us/hq-cli 5.162.0 → 5.163.0

package/dist/lib/daemon/updater.js

@@ -0,0 +1,103 @@
+/**
+ * One run of the `updater` service (`hq daemon service self-update`), which
+ * replaces the boxes' `hq-cli-update.timer` and `*-codex-update.timer`:
+ *
+ * 1. Update the hq CLI through the shared self-update path (same install
+ *    routing, lock and convergence check as every other CLI update).
+ * 2. Update Codex when it is installed as a global npm package and behind.
+ * 3. After a CLI update, ask the daemon to restart itself so the supervisor and
+ *    every service run the new version.
+ */
+import { spawnSync } from "node:child_process";
+import semver from "semver";
+export const CODEX_PACKAGE = "@openai/codex";
+export async function runDaemonUpdater(deps) {
+    let ok = true;
+    const cli = await deps.updateCli();
+    // The restart stops this process too, so it is requested only once all the
+    // updater's work (including a global npm install of Codex) is done.
+    let restart = false;
+    switch (cli.action) {
+        case "updated":
+            deps.log(`hq CLI updated to ${cli.latest ?? "the latest version"}; the daemon restarts onto it once Codex is checked`);
+            restart = true;
+            break;
+        case "update-failed":
+        case "update-ineffective":
+            deps.log(`hq CLI update to ${cli.latest ?? "latest"} did not take effect (${cli.action})`);
+            ok = false;
+            break;
+        default:
+            deps.log(`hq CLI: ${cli.action === "current" ? "up to date" : cli.action}`);
+    }
+    if (!updateCodex(deps))
+        ok = false;
+    if (restart)
+        deps.requestDaemonRestart();
+    return { ok };
+}
+/** Update Codex when it is a global npm install and behind; false when that update failed. */
+function updateCodex(deps) {
+    const installed = deps.codex.installedVersion();
+    if (installed === null)
+        return true;
+    const latest = deps.codex.latestVersion();
+    if (latest === null || !semver.valid(installed) || !semver.valid(latest) || !semver.gt(latest, installed)) {
+        deps.log(`Codex ${installed}: nothing to update`);
+        return true;
+    }
+    const result = deps.codex.install();
+    if (result.ok) {
+        deps.log(`Codex updated ${installed} -> ${latest}`);
+        return true;
+    }
+    deps.log(`Codex update ${installed} -> ${latest} failed: ${result.detail ?? "unknown error"}`);
+    return false;
+}
+/**
+ * The variables for the updater's own CLI update. Every supervised service
+ * gets HQ_NO_UPDATE_CHECK=1 so it never updates itself; the updater is the one
+ * process that must, so it drops that opt-out.
+ */
+export function updaterEnv(vars) {
+    const copy = { ...vars };
+    delete copy.HQ_NO_UPDATE_CHECK;
+    return copy;
+}
+function npm(args) {
+    const r = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", args, {
+        encoding: "utf8",
+        timeout: 10 * 60_000,
+        windowsHide: true,
+        shell: process.platform === "win32",
+    });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+/** Codex through the global npm install, the way the boxes install it. */
+export function npmCodexUpdater() {
+    return {
+        installedVersion: () => {
+            const r = npm(["ls", "-g", CODEX_PACKAGE, "--depth=0", "--json"]);
+            try {
+                const parsed = JSON.parse(r.stdout);
+                return parsed.dependencies?.[CODEX_PACKAGE]?.version ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+        latestVersion: () => {
+            const r = npm(["view", CODEX_PACKAGE, "version"]);
+            const v = r.status === 0 ? r.stdout.trim() : "";
+            return v || null;
+        },
+        install: () => {
+            const r = npm(["install", "-g", `${CODEX_PACKAGE}@latest`]);
+            if (r.status === 0)
+                return { ok: true };
+            const tail = r.stderr.trim().split("\n").slice(-3).join(" ").slice(0, 400);
+            return { ok: false, detail: tail || `npm exited ${r.status ?? "by signal"}` };
+        },
+    };
+}
+//# sourceMappingURL=updater.js.map

package/dist/lib/flag-registry.d.ts

@@ -6,7 +6,7 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { type WorkerOptions } from "node:worker_threads";
-import { type FlagClient, type FlagLookupOptions } from "@indigoai-us/hq-flags-client";
+import { type FlagClient, type FlagLookupOptions, type FlagSnapshot } from "@indigoai-us/hq-flags-client";
 /** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
 export declare const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
 /** The synchronous capability that command gate call sites need. */
@@ -38,6 +38,12 @@ export declare function kickFlagRegistryReadiness(dependencies?: FlagRegistryDep
 export declare function resolveFlagGate(reader: FlagReader | null | undefined, flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
 /** Resolve a process gate against the shared snapshot reader, when configured. */
 export declare function resolveProcessFlagGate(flagKey: string, lookup: FlagLookupOptions, legacyFallback: () => boolean): boolean;
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export declare function currentFlagSnapshot(): FlagSnapshot | null;
 /** Test-only reset for process-global readiness state. */
 export declare function _resetFlagRegistryForTests(): void;
 export {};

package/dist/lib/flag-registry.js

@@ -83,6 +83,14 @@ export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
 export function resolveProcessFlagGate(flagKey, lookup, legacyFallback) {
     return resolveFlagGate(processReader, flagKey, lookup, legacyFallback);
 }
+/**
+ * The registry snapshot held by this process, or null when none has arrived
+ * (no endpoint configured, offline, or still fetching). Callers that must
+ * distinguish "unreachable" from "off" read this instead of a gate.
+ */
+export function currentFlagSnapshot() {
+    return heldSnapshot;
+}
 /** Test-only reset for process-global readiness state. */
 export function _resetFlagRegistryForTests() {
     heldSnapshot = null;

package/dist/lib/mesh/live/backoff.d.ts

@@ -6,11 +6,11 @@ export declare const BACKOFF_BASE_MS = 1000;
 export declare const BACKOFF_CAP_MS = 60000;
 export declare const FLUSH_MAX_ATTEMPTS = 5;
 export type RandomFn = () => number;
-export type SleepFn = (ms: number) => Promise<void>;
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
 export declare function fullJitterDelayMs(attempt: number, opts?: {
     baseMs?: number;
     capMs?: number;
     random?: RandomFn;
 }): number;
-export declare function defaultSleep(ms: number): Promise<void>;
+export declare function defaultSleep(ms: number, signal?: AbortSignal): Promise<void>;
 //# sourceMappingURL=backoff.d.ts.map

package/dist/lib/mesh/live/backoff.js

@@ -12,9 +12,22 @@ export function fullJitterDelayMs(attempt, opts = {}) {
     const exp = Math.min(cap, base * 2 ** attempt);
     return Math.floor(random() * exp);
 }
-export async function defaultSleep(ms) {
-    if (ms <= 0)
+export async function defaultSleep(ms, signal) {
+    if (ms <= 0 || signal?.aborted)
         return;
-    await new Promise((resolve) => setTimeout(resolve, ms));
+    await new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            finish();
+        };
+        const finish = () => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
 }
 //# sourceMappingURL=backoff.js.map

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -45,8 +45,8 @@ export interface DaemonRunDeps {
     timers?: TimerHost;
     fetchCredentials?: CredentialsFetcher;
     mqttConnect?: MqttConnectFn;
-    /** Injected flush (tests). */
-    flush?: () => Promise<FlushSummary>;
+    /** Injected flush (tests). Receives the daemon shutdown signal. */
+    flush?: (signal?: AbortSignal) => Promise<FlushSummary>;
     /** Injected outbox replay (tests). */
     replayOutbox?: () => Promise<{
         delivered: number;

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

@@ -330,8 +330,9 @@ export async function runMeshDaemon(deps = {}) {
     };
     /** In-memory held re-attempt throttle (survives watch-triggered flushes). */
     let lastHeldRetryAtMs = 0;
+    const shutdownController = new AbortController();
     const flushFn = deps.flush ??
-        (async () => {
+        (async (signal) => {
             const t = await getToken();
             const poster = deps.poster ?? createSessionEventsPoster({
                 token: t,
@@ -341,6 +342,7 @@ export async function runMeshDaemon(deps = {}) {
                 workMeshRoot: meshRoot,
                 workContextRoot: ctxRoot,
                 poster,
+                signal,
                 heldRetryIntervalMs: HELD_RETRY_INTERVAL_MS,
                 lastHeldRetryAtMs,
                 onHeldClaimed: (atMs) => {
@@ -628,7 +630,7 @@ export async function runMeshDaemon(deps = {}) {
                 const at = now().getTime();
                 noteHookSessionsFromSpoolFile(workMeshSpoolPath(meshRoot), lastHookEventAt, at);
                 noteHookSessionsFromSpoolFile(workMeshHeldPath(meshRoot), lastHookEventAt, at);
-                const summary = await flushFn();
+                const summary = await flushFn(shutdownController.signal);
                 try {
                     const replay = await replayFn();
                     const delivered = replay.delivered ?? 0;
@@ -794,6 +796,7 @@ export async function runMeshDaemon(deps = {}) {
         if (stopped)
             return;
         stopped = true;
+        shutdownController.abort();
         log(dir, "daemon stopping");
         if (debounceHandle !== null)
             timers.clearTimeout(debounceHandle);

package/dist/lib/mesh/live/flush.d.ts

@@ -2,8 +2,8 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
@@ -32,6 +32,7 @@ export interface FlushDeps {
     workMeshRoot: string;
     workContextRoot: string;
     poster: SessionEventsPoster;
+    signal?: AbortSignal;
     now?: () => Date;
     sleep?: SleepFn;
     random?: RandomFn;

package/dist/lib/mesh/live/flush.js

@@ -2,8 +2,8 @@
  * Flush spool + held session events (US-008).
  *
  * Claim-by-rename → group by sessionId → read work-context state →
- * drop untracked / hold unverified / strip local-only → POST batches of ≤100
- * with bounded full-jitter retries. Never touches sessions-bind.json.
+ * drop untracked / hold unverified / strip local-only → POST at most 25 events
+ * per session per flush. Throttles honor Retry-After and preserve the backlog.
  *
  * Orphan `*.claimed` files from a prior crash are recovered first.
  * 2xx responses are accounted per eventId (accepted / duplicates / rejected).
@@ -21,6 +21,10 @@ import { LOCAL_ONLY_FIELDS, stripLocalOnlyFields } from "./format-spool-line.js"
 import { SESSION_EVENTS_BATCH_MAX, WRITABLE_CONTEXT_STATUSES, parseSessionEventsBatchAck, } from "./session-events-client.js";
 import { appendDeadLetterLine, appendDroppedReceipt, appendHeldLine, appendSpoolLine, claimHeld, claimSpool, countJsonlLines, ensureSpoolFile, recoverOrphanClaims, removeClaimFile, } from "./spool.js";
 import { workMeshHeldPath, workMeshRoot } from "./paths.js";
+/** Bound a replayed session backlog so one flush cannot burst hundreds of events. */
+const SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH = 25;
+/** Never keep a flush blocked on a Retry-After value for more than five minutes. */
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000;
 export const HELD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 /** Re-attempt held events at most this often (spool still flushes every cycle). */
 export const HELD_RETRY_INTERVAL_MS = 5 * 60 * 1000;
@@ -126,18 +130,32 @@ async function postBatchWithRetries(poster, body, deps) {
     let lastStatus = 0;
     let lastBody = {};
     for (let attempt = 0; attempt < deps.maxAttempts; attempt += 1) {
+        if (deps.signal?.aborted) {
+            return { ok: false, retryable: true, status: lastStatus, body: lastBody };
+        }
         const res = await poster(body);
         lastStatus = res.status;
         lastBody = res.body;
         if (res.ok)
             return { ok: true, body: res.body };
+        if (res.status === 429 || res.status === 503) {
+            const retryAfterMs = typeof res.retryAfterMs === "number" &&
+                Number.isFinite(res.retryAfterMs) &&
+                res.retryAfterMs >= 0
+                ? Math.min(res.retryAfterMs, MAX_RETRY_AFTER_MS)
+                : 0;
+            const jitterMs = fullJitterDelayMs(attempt, { random: deps.random });
+            await deps.sleep(Math.min(MAX_RETRY_AFTER_MS, Math.max(retryAfterMs, jitterMs)), deps.signal);
+            // A throttled batch stays queued for a later flush; do not hot-loop it.
+            return { ok: false, retryable: true, status: res.status, body: res.body };
+        }
         if (!res.retryable) {
             return { ok: false, retryable: false, status: res.status, body: res.body };
         }
         if (attempt + 1 >= deps.maxAttempts)
             break;
         const delay = fullJitterDelayMs(attempt, { random: deps.random });
-        await deps.sleep(delay);
+        await deps.sleep(delay, deps.signal);
     }
     return { ok: false, retryable: true, status: lastStatus, body: lastBody };
 }
@@ -230,7 +248,9 @@ export async function flushSessionEvents(deps) {
             pendingRestore.delete(event);
         };
         const loggedProject404 = new Set();
-        for (const [sessionId, items] of bySession) {
+        sessionLoop: for (const [sessionId, items] of bySession) {
+            if (deps.signal?.aborted)
+                break sessionLoop;
             let state = readSessionState(sessionId, deps.workContextRoot);
             if (state?.companyConfidence === "device_default" &&
                 deps.authorizeDeviceDefaultTenant) {
@@ -273,11 +293,13 @@ export async function flushSessionEvents(deps) {
                 }
                 continue;
             }
-            // Post path: strip local-only, batch ≤100, retry.
-            const stripped = items.map((item) => stripLocalOnlyFields(item.event));
+            // Post a bounded portion of this session's backlog. Untouched events
+            // remain in pendingRestore and are put back on the spool below.
+            const flushItems = items.slice(0, SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH);
+            const stripped = flushItems.map((item) => stripLocalOnlyFields(item.event));
             for (let i = 0; i < stripped.length; i += SESSION_EVENTS_BATCH_MAX) {
                 const chunk = stripped.slice(i, i + SESSION_EVENTS_BATCH_MAX);
-                const originalChunk = items.slice(i, i + SESSION_EVENTS_BATCH_MAX);
+                const originalChunk = flushItems.slice(i, i + SESSION_EVENTS_BATCH_MAX);
                 const body = {
                     contractVersion: 1,
                     companyUid: decision.companyUid,
@@ -296,6 +318,7 @@ export async function flushSessionEvents(deps) {
                     maxAttempts,
                     sleep,
                     random,
+                    signal: deps.signal,
                 });
                 if (result.ok) {
                     accountBatchSuccess(result.body, originalChunk, deps.workMeshRoot, now, summary, markDisposed);
@@ -347,6 +370,10 @@ export async function flushSessionEvents(deps) {
                     summary.restored += 1;
                     markDisposed(item.event);
                 }
+                if (result.status === 429 || result.status === 503)
+                    break;
+                if (deps.signal?.aborted)
+                    break sessionLoop;
             }
         }
     }

package/dist/lib/mesh/live/session-events-client.d.ts

@@ -23,6 +23,7 @@ export interface SessionEventsPostResult {
     body: unknown;
     ok: boolean;
     retryable: boolean;
+    retryAfterMs?: number;
     networkError?: boolean;
 }
 /** Contract §2.3 batch ingest ack (parsed from a 2xx body). */
@@ -51,6 +52,7 @@ export declare function createSessionEventsPoster(opts: {
     post?: (path: string, body: SessionEventsBatchBody) => Promise<{
         status: number;
         body: unknown;
+        headers?: Pick<Headers, "get">;
     }>;
 }): SessionEventsPoster;
 /** Resolve API base: HQ_VAULT_API_URL overrides DEFAULT_VAULT_API_URL. */

package/dist/lib/mesh/live/session-events-client.js

@@ -15,6 +15,27 @@ export const WRITABLE_CONTEXT_STATUSES = new Set([
     "bound",
     "migration_pending",
 ]);
+/** Parse the Retry-After delta-seconds or HTTP-date form into milliseconds. */
+function parseRetryAfterMs(value, nowMs = Date.now()) {
+    if (value === null || !value.trim())
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const delayMs = Number(trimmed) * 1_000;
+        return Number.isSafeInteger(delayMs) ? delayMs : undefined;
+    }
+    if (/^[+-]/.test(trimmed))
+        return undefined;
+    const retryAtMs = Date.parse(trimmed);
+    if (!Number.isFinite(retryAtMs))
+        return undefined;
+    return Math.max(0, retryAtMs - nowMs);
+}
+function retryAfterForStatus(status, headers) {
+    if (status !== 429 && status !== 503)
+        return undefined;
+    return parseRetryAfterMs(headers?.get("retry-after") ?? null);
+}
 /**
  * Parse a batch ingest response body. Returns null when the body is not an
  * object (caller should retain events rather than treating them as posted).
@@ -65,9 +86,11 @@ export function createSessionEventsPoster(opts) {
         try {
             if (opts.post) {
                 const res = await opts.post(SESSION_EVENTS_PATH, body);
+                const retryAfterMs = retryAfterForStatus(res.status, res.headers);
                 return {
                     status: res.status,
                     body: res.body,
+                    ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
                     ...classifySessionEventsResponse(res.status),
                 };
             }
@@ -88,9 +111,11 @@ export function createSessionEventsPoster(opts) {
                     parsed = { raw: text };
                 }
             }
+            const retryAfterMs = retryAfterForStatus(res.status, res.headers);
             return {
                 status: res.status,
                 body: parsed,
+                ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
                 ...classifySessionEventsResponse(res.status),
             };
         }

package/dist/lib/service-manager/systemd.d.ts

@@ -10,8 +10,8 @@ import { type ServiceHostPaths, type ServiceSpec } from "./types.js";
 import type { RunCommand } from "./launchd.js";
 export declare const SYSTEMD_PATH_ENV = "/usr/local/bin:/usr/bin:/bin";
 export declare function systemdUserDir(home: string): string;
-export declare function systemdUnitName(spec: Pick<ServiceSpec, "name">): string;
-export declare function systemdUnitPath(home: string, spec: Pick<ServiceSpec, "name">): string;
+export declare function systemdUnitName(spec: Pick<ServiceSpec, "name" | "unitName">): string;
+export declare function systemdUnitPath(home: string, spec: Pick<ServiceSpec, "name" | "unitName">): string;
 export declare function renderSystemdUserUnit(spec: ServiceSpec, host: ServiceHostPaths): string;
 export declare function activateSystemd(unitName: string, run: RunCommand): void;
 export declare function deactivateSystemd(unitName: string, run: RunCommand): void;

package/dist/lib/service-manager/systemd.js

@@ -13,7 +13,7 @@ export function systemdUserDir(home) {
     return path.join(home, ".config", "systemd", "user");
 }
 export function systemdUnitName(spec) {
-    return `hq-agent-${spec.name}.service`;
+    return spec.unitName ?? `hq-agent-${spec.name}.service`;
 }
 export function systemdUnitPath(home, spec) {
     return path.join(systemdUserDir(home), systemdUnitName(spec));

package/dist/lib/service-manager/types.d.ts

@@ -19,6 +19,8 @@ export interface ServiceSpec {
     env: Record<string, string>;
     /** Seconds to wait before a restart after exit. */
     restartSec: number;
+    /** systemd unit file name; defaults to `hq-agent-<name>.service`. */
+    unitName?: string;
 }
 export interface ServiceHostPaths {
     home: string;

package/dist/main.d.ts

@@ -5,6 +5,7 @@
 import "./node-preflight.js";
 import "./node-network-compat.js";
 import { Sentry } from "./sentry.js";
+import { upgradeToTeam } from "./utils/team-upgrade.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
  * the hard version decision, pre-action observability, and release-health
@@ -21,6 +22,11 @@ export type TopLevelErrorDependencies = {
     sentry: Pick<typeof Sentry, "captureException">;
     stderr: Pick<typeof process.stderr, "write">;
     setExitCode: (code: number) => void;
+    interactive?: boolean;
+    argv?: readonly string[];
+    ask?: (question: string) => Promise<string>;
+    openUrl?: (url: string) => Promise<void>;
+    upgradeToTeam?: typeof upgradeToTeam;
 };
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export declare function handleTopLevelError(err: unknown, deps?: TopLevelErrorDependencies): Promise<void>;

package/dist/main.js

@@ -35,7 +35,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, } from "./utils/plan-gate-error.js";
+import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, offerUpgradeLink, } 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";
@@ -379,20 +379,60 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.setExitCode(1);
     }
     else if (isPlanGateError(err)) {
-        // hq-pro's plan denials are expected product limits, never a CLI crash.
-        // The shared vault client has already decoded and typed the small safe
-        // envelope; do not expose its raw body or retry a rejected creation.
-        deps.stderr.write(`hq: ${formatPlanGateError(err)}\n`);
+        // 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.
+        const interactive = deps.interactive ?? canOfferTeamUpgrade(deps.argv);
+        const message = formatPlanGateError(err, { urlOnly: !interactive });
+        deps.stderr.write(interactive ? `hq: ${message}\n` : `${message}\n`);
         deps.setExitCode(1);
-        if (canOfferTeamUpgrade()) {
-            try {
-                await offerTeamUpgrade(async () => {
-                    await upgradeToTeam({ companyUid: err.details.companyUid });
-                });
+        if (interactive && err.details.upgradeUrl) {
+            const companyUid = err.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");
+            if (isCompanyWorkforceCheckout && companyUid) {
+                try {
+                    await offerTeamUpgrade(async () => {
+                        await (deps.upgradeToTeam ?? upgradeToTeam)({ companyUid });
+                    }, {
+                        interactive: true,
+                        argv: deps.argv,
+                        ask: deps.ask,
+                    });
+                }
+                catch (upgradeErr) {
+                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
+                    deps.stderr.write(`hq: ${message}\n`);
+                    try {
+                        await offerUpgradeLink(err.details.upgradeUrl, {
+                            interactive: true,
+                            argv: deps.argv,
+                            ask: deps.ask,
+                            openUrl: deps.openUrl,
+                        });
+                    }
+                    catch (linkErr) {
+                        const linkMessage = linkErr instanceof Error ? linkErr.message : String(linkErr);
+                        deps.stderr.write(`hq: ${linkMessage}\n`);
+                    }
+                }
             }
-            catch (upgradeErr) {
-                const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
-                deps.stderr.write(`hq: ${message}\n`);
+            else {
+                try {
+                    await offerUpgradeLink(err.details.upgradeUrl, {
+                        interactive: true,
+                        argv: deps.argv,
+                        ask: deps.ask,
+                        openUrl: deps.openUrl,
+                    });
+                }
+                catch (upgradeErr) {
+                    const message = upgradeErr instanceof Error ? upgradeErr.message : String(upgradeErr);
+                    deps.stderr.write(`hq: ${message}\n`);
+                }
             }
         }
     }

package/dist/utils/cognito-session.d.ts

@@ -81,6 +81,10 @@ export declare const DEFAULT_VAULT_API_URL: string;
  */
 export declare function resolveDefaultHqRoot(opts?: {
     onMissing?: "throw" | "fallback";
+    /** Defaults to process.env, process.cwd() and os.homedir(). */
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    home?: string;
 }): string;
 export declare const DEFAULT_HQ_ROOT: string;
 /**

package/dist/utils/cognito-session.js

@@ -102,22 +102,24 @@ export const DEFAULT_VAULT_API_URL = process.env.HQ_VAULT_API_URL ?? "https://hq
  * Re-importable as a function for command-time resolution and tests.
  */
 export function resolveDefaultHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
     // Tier 1: explicit override.
-    if (process.env.HQ_ROOT)
-        return path.resolve(process.env.HQ_ROOT);
+    if (env.HQ_ROOT)
+        return path.resolve(env.HQ_ROOT);
     // Tier 2: working-tree walk-up — operate on the HQ tree you're inside.
-    let cur = path.resolve(process.cwd());
+    let cur = path.resolve(opts.cwd ?? process.cwd());
     while (cur !== path.dirname(cur)) {
         if (isHqRoot(cur))
             return cur;
         cur = path.dirname(cur);
     }
     // Tiers 3–4: the installer/menubar's canonical "where is HQ" records.
-    const fromConfig = readHqRootFromHqConfig(path.join(os.homedir(), ".hq"));
+    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
     if (fromConfig)
         return path.resolve(fromConfig);
     // Tier 5: discover a valid HQ root in the well-known locations.
-    const discovered = discoverHqRootViaCoreYaml();
+    const discovered = discoverHqRootViaCoreYaml(home);
     if (discovered)
         return discovered;
     // Tier 6: nothing resolved.
@@ -127,7 +129,7 @@ export function resolveDefaultHqRoot(opts = {}) {
             "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
             "its location.");
     }
-    return path.join(os.homedir(), "hq");
+    return path.join(home, "hq");
 }
 /**
  * Read the configured HQ root from the installer/menubar records under
@@ -156,8 +158,7 @@ function readJsonStringField(file, field) {
     }
 }
 /** Well-known parent locations an HQ tree commonly lives in (mirrors hq-sync). */
-function hqDiscoveryCandidates() {
-    const home = os.homedir();
+function hqDiscoveryCandidates(home = os.homedir()) {
     return [
         path.join(home, "HQ"),
         path.join(home, "hq"),
@@ -172,8 +173,8 @@ function hqDiscoveryCandidates() {
  * signature. First match wins; returns undefined if none qualify. Cheap — a
  * few stats plus one small YAML parse on a hit.
  */
-function discoverHqRootViaCoreYaml() {
-    return hqDiscoveryCandidates().find(isValidHqRootSignature);
+function discoverHqRootViaCoreYaml(home) {
+    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
 }
 /**
  * True iff `dir` carries a valid hq-core `core.yaml` — canonical