@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/src/lib/plan-limit-nag.ts

@@ -1,264 +0,0 @@
-/**
- * `plan-limit-nag` (US-016) — non-blocking plan-limit warning surface.
- *
- * hq-pro shallow-merges a `planLimits` status payload into the top level of
- * some 2xx JSON response bodies (US-012). This module:
- *
- *   1. Best-effort records the last-seen status from decoded JSON bodies
- *      (`recordPlanLimitStatus`).
- *   2. Emits a stderr nag at command completion (`emitPlanLimitNag`):
- *      - entries present, none over (≥80% warning): one-line yellow warning,
- *        once per process session
- *      - any resource over: boxed notice, at most once per day (persisted in
- *        `~/.hq/plan-limit-nag.json`) and once per session
- *
- * Additive only — never throws, never touches `process.exitCode`, never
- * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
- */
-
-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";
-
-const DAY_MS = 24 * 60 * 60 * 1000;
-
-export interface PlanLimitEntry {
-  used: number;
-  limit: number;
-  over: boolean;
-}
-
-/** Validated map of resource key → entry. */
-export type PlanLimitsMap = Record<string, PlanLimitEntry>;
-
-interface LastSeenStatus {
-  limits: PlanLimitsMap;
-  anyOver: boolean;
-}
-
-interface NagStateFile {
-  shownAt: number;
-}
-
-/** Module-level last-seen cell — overwritten by each successful parse. */
-let lastSeen: LastSeenStatus | null = null;
-
-/** Session dedupe for the ≥80% one-line warning. */
-let warningShownThisSession = false;
-
-/** Session dedupe for the over-limit boxed notice. */
-let overShownThisSession = false;
-
-function defaultStatePath(): string {
-  return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
-}
-
-function isOptedOut(): boolean {
-  return process.env.HQ_NO_PLAN_LIMIT_NAG === "1";
-}
-
-/**
- * Defensively parse a single planLimits entry. Returns null if the shape is
- * not well-formed (non-numeric used/limit, non-boolean over, etc.).
- */
-function parseEntry(value: unknown): PlanLimitEntry | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  const rec = value as Record<string, unknown>;
-  if (
-    typeof rec.used !== "number" ||
-    !Number.isFinite(rec.used) ||
-    typeof rec.limit !== "number" ||
-    !Number.isFinite(rec.limit) ||
-    typeof rec.over !== "boolean"
-  ) {
-    return null;
-  }
-  return { used: rec.used, limit: rec.limit, over: rec.over };
-}
-
-/**
- * Defensively parse a decoded JSON body for a well-formed top-level
- * `planLimits` object. Malformed or absent → null. Never throws.
- */
-function parsePlanLimits(body: unknown): PlanLimitsMap | null {
-  if (body === null || typeof body !== "object" || Array.isArray(body)) {
-    return null;
-  }
-  const planLimits = (body as Record<string, unknown>).planLimits;
-  if (
-    planLimits === null ||
-    typeof planLimits !== "object" ||
-    Array.isArray(planLimits)
-  ) {
-    return null;
-  }
-
-  const out: PlanLimitsMap = {};
-  let anyValid = false;
-  for (const [key, value] of Object.entries(
-    planLimits as Record<string, unknown>,
-  )) {
-    const entry = parseEntry(value);
-    if (entry === null) continue;
-    out[key] = entry;
-    anyValid = true;
-  }
-  return anyValid ? out : null;
-}
-
-/**
- * Record plan-limit status from a decoded JSON response body.
- * Never throws. Overwrites the last-seen cell when a well-formed
- * `planLimits` object is present; ignores malformed / absent payloads.
- */
-export function recordPlanLimitStatus(body: unknown): void {
-  try {
-    const limits = parsePlanLimits(body);
-    if (limits === null) return;
-    const anyOver = Object.values(limits).some((e) => e.over);
-    lastSeen = { limits, anyOver };
-  } catch {
-    // Never throw from record path.
-  }
-}
-
-function usageRatio(entry: PlanLimitEntry): number {
-  if (entry.limit <= 0) return entry.used > 0 ? Infinity : 0;
-  return entry.used / entry.limit;
-}
-
-/** Pick the resource with the highest used/limit ratio (worst headroom). */
-function worstResource(
-  limits: PlanLimitsMap,
-): { key: string; entry: PlanLimitEntry } | null {
-  let best: { key: string; entry: PlanLimitEntry; ratio: number } | null =
-    null;
-  for (const [key, entry] of Object.entries(limits)) {
-    const ratio = usageRatio(entry);
-    if (best === null || ratio > best.ratio) {
-      best = { key, entry, ratio };
-    }
-  }
-  return best ? { key: best.key, entry: best.entry } : null;
-}
-
-function formatPct(entry: PlanLimitEntry): string {
-  if (entry.limit <= 0) return entry.used > 0 ? "∞" : "0%";
-  return `${Math.round((entry.used / entry.limit) * 100)}%`;
-}
-
-function formatEntryLine(key: string, entry: PlanLimitEntry): string {
-  return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})`;
-}
-
-function readShownAt(statePath: string): number | null {
-  try {
-    const raw = fs.readFileSync(statePath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<NagStateFile>;
-    if (typeof parsed.shownAt !== "number" || !Number.isFinite(parsed.shownAt)) {
-      return null;
-    }
-    return parsed.shownAt;
-  } catch {
-    return null;
-  }
-}
-
-function writeShownAt(statePath: string, shownAt: number): void {
-  try {
-    fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    const payload: NagStateFile = { shownAt };
-    fs.writeFileSync(statePath, JSON.stringify(payload));
-  } catch {
-    // best-effort; never break the CLI on cache write failure
-  }
-}
-
-function withinDayWindow(shownAt: number, nowMs: number): boolean {
-  return nowMs - shownAt < DAY_MS;
-}
-
-function buildOverBox(overEntries: Array<[string, PlanLimitEntry]>): string {
-  const title = "⚠ HQ plan limit exceeded";
-  const upgrade = `Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
-  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,
-  );
-  const top = `┌${"─".repeat(innerWidth + 2)}┐`;
-  const bot = `└${"─".repeat(innerWidth + 2)}┘`;
-  const mid = contentLines
-    .map((l) => `│ ${l.padEnd(innerWidth)} │`)
-    .join("\n");
-  return `${top}\n${mid}\n${bot}`;
-}
-
-/**
- * Emit a plan-limit nag to stderr at command completion.
- *
- * Never throws, never touches `process.exitCode`. Default sink is
- * `process.stderr.write`. Tests inject `write`, `now`, and `statePath`.
- */
-export function emitPlanLimitNag(
-  opts: {
-    write?: (s: string) => void;
-    now?: () => Date;
-    statePath?: string;
-  } = {},
-): void {
-  try {
-    if (isOptedOut()) return;
-    if (lastSeen === null) return;
-
-    const write =
-      opts.write ?? ((s: string) => process.stderr.write(s));
-    const now = opts.now ?? (() => new Date());
-    const statePath = opts.statePath ?? defaultStatePath();
-    const { limits, anyOver } = lastSeen;
-    const entries = Object.entries(limits);
-    if (entries.length === 0) return;
-
-    if (anyOver) {
-      if (overShownThisSession) return;
-      const nowMs = now().getTime();
-      const prev = readShownAt(statePath);
-      if (prev !== null && withinDayWindow(prev, nowMs)) return;
-
-      overShownThisSession = true;
-      const overEntries = entries.filter(([, e]) => e.over);
-      const box = buildOverBox(overEntries);
-      write(chalk.yellow(box) + "\n");
-      writeShownAt(statePath, nowMs);
-      return;
-    }
-
-    // Warning path: entries present, none over (≥80% resources only appear).
-    if (warningShownThisSession) return;
-    const worst = worstResource(limits);
-    if (worst === null) return;
-
-    warningShownThisSession = true;
-    const line = `⚠ HQ free plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${PLAN_LIMIT_UPGRADE_URL}`;
-    write(chalk.yellow(line) + "\n");
-  } catch {
-    // Never throw from emit path.
-  }
-}
-
-/** Test-only helper — clears last-seen status and session dedupe flags. */
-export function _resetForTests(): void {
-  lastSeen = null;
-  warningShownThisSession = false;
-  overShownThisSession = false;
-}

package/src/main.ts

@@ -1,371 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * HQ CLI - Module management, package management, and cloud sync for HQ
- */
-
-// MUST be first: guard the Node version before any dependency that needs a
-// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
-import "./node-preflight.js";
-import { Command } from "commander";
-import { initSentry, Sentry } from "./sentry.js";
-import { registerAddCommand } from "./commands/add.js";
-import { registerSyncCommand } from "./commands/sync.js";
-import { registerListCommand } from "./commands/list.js";
-import { registerUpdateCommand } from "./commands/update.js";
-import { registerCloudCommands } from "./commands/cloud.js";
-import { registerSyncModeCommand } from "./commands/sync-mode.js";
-import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
-import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
-import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
-import { registerLoginCommand } from "./commands/login.js";
-import { registerLogoutCommand } from "./commands/logout.js";
-import { registerWhoamiCommand } from "./commands/whoami.js";
-import { registerOnboardCommand } from "./commands/onboard.js";
-import { registerPackageInstallCommand } from "./commands/pkg-install.js";
-import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
-import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
-import { registerPackageListCommand } from "./commands/pkg-list.js";
-import { registerPacksCommand } from "./commands/packs.js";
-import { registerPublishCommand } from "./commands/publish.js";
-import { registerCreatorsCommand } from "./commands/creators.js";
-import { registerTeamSyncCommand } from "./commands/team-sync.js";
-import { registerAuthCommands } from "./commands/auth.js";
-import { registerApiKeysCommand } from "./commands/api-keys.js";
-import { registerSecretsCommand } from "./commands/secrets.js";
-import { registerRunCommand } from "./commands/run.js";
-import { registerGroupsCommand } from "./commands/groups.js";
-import { registerWorkersCommand } from "./commands/workers.js";
-import { registerGroupGrantsCommand } from "./commands/group-grants.js";
-import { registerFilesCommand } from "./commands/files.js";
-import { registerFilesBrowseCommands } from "./commands/files-browse.js";
-import { registerSkillCommand } from "./commands/skill.js";
-import { registerMembersCommand } from "./commands/members.js";
-import { registerPeopleCommand } from "./commands/people.js";
-import { registerDmCommand } from "./commands/dm.js";
-import { registerChannelsCommand } from "./commands/channels.js";
-import { registerFeedbackCommand } from "./commands/feedback.js";
-import { registerMeetingsCommand } from "./commands/meetings.js";
-import { registerSourcesCommand } from "./commands/sources.js";
-import { registerSignalsCommand } from "./commands/signals.js";
-import { registerIntegrationsCommand } from "./commands/integrations.js";
-import { registerReindexCommand } from "./commands/reindex.js";
-import { registerRescueCommand } from "./commands/rescue.js";
-import { registerMcpCommand } from "./commands/mcp-status.js";
-import { registerCrmCommand } from "./commands/crm.js";
-import { registerCompanyCommand } from "./commands/company.js";
-import { registerAgentsCommand } from "./commands/agents.js";
-import { registerOutpostsCommand } from "./commands/outposts.js";
-import { registerBillingCommand } from "./commands/billing.js";
-import { registerDbCommand } from "./commands/db.js";
-import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
-import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
-import { isExpectedUserError } from "./utils/expected-cli-error.js";
-import { isEpipe } from "./utils/epipe.js";
-import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
-import { isAuthError } from "./utils/auth-error.js";
-import { isCompanySelectionError } from "./utils/company-selection-error.js";
-import {
-  maybeWarnNewVersion,
-  refreshVersionCache,
-} from "./utils/version-check.js";
-import {
-  enforceVersionGate,
-  shouldSkipGate,
-} from "./utils/version-gate.js";
-import { CLI_VERSION } from "./cli-version.js";
-import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
-import { settleWithin } from "./utils/settle-with-timeout.js";
-import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
-
-/** Hard upper bound for non-user-visible release-health finalization. */
-const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
-
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
-// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
-// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
-// console.log inside a command) is handled in the top-level catch below; both
-// share `isEpipe` (HQ-6B).
-const onPipeError = (err: NodeJS.ErrnoException): void => {
-  if (isEpipe(err)) {
-    process.exit(0);
-  }
-  throw err;
-};
-process.stdout.on("error", onPipeError);
-process.stderr.on("error", onPipeError);
-
-initSentry();
-maybeWarnNewVersion();
-
-const program = new Command();
-
-program
-  .name("hq")
-  .description("HQ management CLI — modules, packages, and cloud sync")
-  .version(CLI_VERSION);
-
-// Module management subcommand group
-const modulesCmd = program
-  .command("modules")
-  .description("Module management commands");
-
-registerAddCommand(modulesCmd);
-registerSyncCommand(modulesCmd);
-registerListCommand(modulesCmd);
-registerUpdateCommand(modulesCmd);
-
-// Package management subcommand group
-const packagesCmd = program
-  .command("packages")
-  .description("Package management commands");
-
-registerPackageInstallCommand(packagesCmd);
-registerPackageRemoveCommand(packagesCmd);
-registerPackageUpdateCommand(packagesCmd);
-registerPackageListCommand(packagesCmd);
-
-// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
-// `packages` system above. Available as both `hq packages packs …` (grouped)
-// and `hq packs …` (top-level convenience).
-registerPacksCommand(packagesCmd);
-registerPacksCommand(program);
-
-// Top-level shortcuts for package commands
-// "hq install <slug>" = "hq packages install <slug>"
-// "hq remove <slug>"  = "hq packages remove <slug>"
-registerPackageInstallCommand(program);
-registerPackageRemoveCommand(program);
-
-// Marketplace publish (top-level — packer + authenticated upload, US-004)
-// "hq publish <skill-or-worker-path>" packages and submits a pack to the
-// marketplace via POST /v1/listings.
-registerPublishCommand(program);
-// `hq creators apply` — request verified-creator access (required to publish).
-registerCreatorsCommand(program);
-
-// Cloud sync subcommand group
-const syncCmd = program
-  .command("sync")
-  .description("Cloud sync commands — sync HQ to S3 for mobile access");
-
-registerCloudCommands(syncCmd);
-registerSyncModeCommand(syncCmd);
-registerSyncNarrowCommand(syncCmd);
-
-// Cloud provisioning subcommand group (entity + bucket + initial sync)
-// Distinct from `hq sync` which assumes provisioning has already happened.
-const cloudCmd = program
-  .command("cloud")
-  .description(
-    "Cloud commands — provision entities and manage cloud-backed companies",
-  );
-
-registerCloudProvisionCommands(cloudCmd);
-registerCloudDemoteCommands(cloudCmd);
-
-// Team commands (top-level)
-registerTeamSyncCommand(program);
-
-// Auth commands (top-level — Cognito OAuth)
-registerLoginCommand(program);
-registerLogoutCommand(program);
-registerWhoamiCommand(program);
-registerAuthCommands(program);
-
-// Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
-registerSecretsCommand(program);
-
-// Vault databases (subcommand group — hq db status|sql|migrate|provision)
-registerDbCommand(program);
-
-// API key management (subcommand group — hq api-keys create|list|revoke)
-registerApiKeysCommand(program);
-
-// Schema-driven dev runner — hq run [options] -- <cmd>
-registerRunCommand(program);
-
-// Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
-registerGroupsCommand(program);
-
-// Worker discovery + sharing (subcommand group — hq workers list|share)
-registerWorkersCommand(program);
-
-// Cross-company group grants (subcommand group —
-// hq group-grants grant|revoke|outbound|inbound)
-registerGroupGrantsCommand(program);
-
-// Files ACL management (subcommand group — hq files share|unshare|acl)
-// `registerFilesCommand` returns the `files` group so we can attach the
-// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
-const filesCmd = registerFilesCommand(program);
-registerFilesBrowseCommands(filesCmd);
-
-// Skill collaboration loop (subcommand group — hq skill suggest|list-suggestions|review).
-// A thin terminal front-end over the SAME wired hq-pro skill suggestion + merge
-// routes the MCP (US-007) and console merge (US-009) surfaces use — no forked logic.
-registerSkillCommand(program);
-
-// Membership management (subcommand group — hq members invite|list|revoke)
-registerMembersCommand(program);
-// People directory (subcommand group — hq people list|search|resolve), reading
-// the local companies/<co>/people store scoped to one company.
-registerPeopleCommand(program);
-registerDmCommand(program);
-registerChannelsCommand(program);
-
-// Onboarding (top-level — Cognito + vault-service provisioning)
-registerOnboardCommand(program);
-
-// Feedback (subcommand group — hq feedback bug|feature)
-registerFeedbackCommand(program);
-
-// Meetings (subcommand group — hq meetings list|get|search|transcript|notes)
-registerMeetingsCommand(program);
-
-// Sources read surface (subcommand group — hq sources list|get|channels|entities)
-registerSourcesCommand(program);
-
-// Signals read surface (subcommand group — hq signals list|get|types|entities)
-registerSignalsCommand(program);
-
-// Company-connected apps via the governed integration gateway
-// (subcommand group — hq integrations list|tools|call|approve|reject)
-registerIntegrationsCommand(program);
-
-// Skill/personal-overlay mirroring + workers-registry regen. Invoked by the
-// hq-core reindex hook shim (Stop / PostToolUse) and by sync()/rescue() after
-// they change on-disk sources. Keeps a `master-sync` alias for one release.
-// Implementation lives in @indigoai-us/hq-cloud.
-registerReindexCommand(program);
-
-// Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
-// the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
-// shipped from @indigoai-us/hq-cloud.
-registerRescueCommand(program);
-
-// MCP pack observability (subcommand group — `hq mcp status`). Read-only
-// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
-// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
-registerMcpCommand(program);
-
-// Native CRM entity upsert (subcommand group — `hq crm entity upsert`). Wraps
-// POST /crm/entities (the ontology write gate) so an authenticated company
-// member can create/update canonical CRM entities in the company vault.
-registerCrmCommand(program);
-
-// Company settings (subcommand group — `hq company settings set`). Owner-only
-// toggles for crmEnabled / ontologyEnabled via PUT /company-settings.
-registerCompanyCommand(program);
-
-// Cloud agent management (subcommand group — `hq agents …`). Rename, reconfigure,
-// start/stop, and tear down a company's fleet agents via the hq-pro /v1/agents
-// control plane — the same routes the web console's agents panel calls.
-registerAgentsCommand(program);
-
-// Personal Outpost management (subcommand group — `hq outposts …`). List, inspect,
-// enable Codex on, refresh login for, and destroy your EC2 boxes via the hq-pro
-// /outpost/* control plane.
-registerOutpostsCommand(program);
-
-// Billing (subcommand group — `hq billing …`). Check subscription/card state and
-// mint a shareable Stripe card-capture link — the client side of the paid-
-// provisioning gate for agents & Outposts.
-registerBillingCommand(program);
-
-program.hook("preAction", async () => {
-  await emitCliSessionStarted();
-});
-
-export async function runCli(): Promise<void> {
-  try {
-    Sentry.addBreadcrumb({
-      category: "command",
-      message: sanitizeArgv(process.argv.slice(2)).join(" "),
-      level: "info",
-    });
-    // Hard version gate: ask hq-pro whether this CLI is below the floor and
-    // auto-update if so (exits the process on update). Skipped for inspection
-    // flags (`--version`, `--help`) so users debugging a broken install can
-    // still introspect what they have. Silent on any failure — never blocks
-    // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
-    if (!shouldSkipGate(process.argv)) {
-      await enforceVersionGate();
-    }
-    await program.parseAsync();
-  } catch (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
-    // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
-    // `write EPIPE` thrown out of console.log lands here rather than on the
-    // stream 'error' listener above.
-    if (isEpipe(err)) {
-      process.exitCode = 0;
-    } else if (isInterceptedProcessExit(err)) {
-      // A security/audit FUZZ harness replaced `process.exit` with a throw so it
-      // can keep exercising the binary. Commander calling `process.exit` for
-      // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
-      // here as that synthetic marker. It is a test-harness artifact, NOT an
-      // hq-cli defect — a real user's `process.exit` just exits, so nothing is
-      // thrown or captured. Skip Sentry capture (no signal, no user-facing
-      // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
-      process.exitCode = 1;
-    } else if (isCompanySelectionError(err)) {
-      // The user has multiple (or zero) active company memberships and ran a
-      // command that needs exactly one without `--company`, or a `--company`
-      // slug collided across companies. That's an expected, user-actionable
-      // disambiguation prompt — the message already tells them exactly how to
-      // proceed (re-run with `--company <slug-or-uid>`) — not an hq-cli defect.
-      // The CLI can't pick a company for them. Print the actionable message and
-      // exit non-zero, but skip Sentry capture so a normal "pick a company"
-      // prompt doesn't flood the tracker with unfixable "crashes" (HQ-CLI-7).
-      process.stderr.write(`hq: ${(err as Error).message}\n`);
-      process.exitCode = 1;
-    } else if (isAuthError(err)) {
-      // HQ-CLI-8: the vault API returned 401 Unauthorized — the caller's HQ
-      // session is expired or missing. That's an expected auth state the user
-      // fixes with `hq login`, not an hq-cli defect. Print the actionable
-      // message and skip Sentry so an expired login doesn't flood the tracker
-      // with identical, unfixable "crashes".
-      process.stderr.write(`hq: ${(err as Error).message}\n`);
-      process.exitCode = 1;
-    } else if (isExpectedUserError(err)) {
-      // HQ-CLI-6: a user-facing, client-caused error (a non-owner running
-      // `hq integrations approve`, a stale queueId, a bad --args, an unknown
-      // connection) is the caller's request/state/permission, not an hq-cli
-      // defect. Print the actionable message and skip Sentry so a correctly-
-      // denied 4xx doesn't flood the tracker with identical, unfixable crash
-      // reports. Genuine server (5xx) / unknown failures still capture below.
-      process.stderr.write(`hq: ${err.message}\n`);
-      process.exitCode = 1;
-    } else {
-      // A full disk / exhausted quota / read-only filesystem is the user's
-      // machine, not an HQ code defect. Surface a clear, actionable message and
-      // skip Sentry capture so one full disk doesn't flood the tracker with
-      // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-      // to Sentry and still exit 1.
-      const envMsg = environmentalFsErrorMessage(err);
-      if (envMsg) {
-        process.stderr.write(`hq: ${envMsg}\n`);
-      } else {
-        Sentry.captureException(err);
-      }
-      process.exitCode = 1;
-    }
-  } finally {
-    // Plan-limit nag (US-016): stderr-only, never throws, never touches
-    // process.exitCode — safe to run after exit codes have been set.
-    emitPlanLimitNag();
-    // Release health: finalize the per-run session before the flush.
-    Sentry.endSession();
-    // Neither task may turn a successful command into Node's
-    // `unsettled top-level await` exit. They are observability-only after the
-    // command has completed, so a bounded best-effort wait is the terminal
-    // lifecycle boundary for this invocation.
-    await settleWithin(
-      [refreshVersionCache(), Sentry.flush(2000)],
-      RELEASE_HEALTH_SETTLE_TIMEOUT_MS,
-    );
-  }
-}

package/src/node-preflight.test.ts

@@ -1,60 +0,0 @@
-/**
- * Unit tests for the runtime Node version guard.
- *
- * The guard fails the CLI fast on Node < 20 (where prebuilt native modules hit
- * an ABI mismatch and `util.styleText` is missing) with an actionable upgrade
- * message, and is a no-op on Node 20+.
- */
-
-import { describe, expect, it } from "vitest";
-
-import { MIN_NODE_MAJOR, checkNodeVersion } from "./node-preflight.js";
-
-describe("checkNodeVersion", () => {
-  it("rejects Node 18 with an actionable upgrade message", () => {
-    const result = checkNodeVersion("18.19.0");
-
-    expect(result.ok).toBe(false);
-    expect(result.major).toBe(18);
-    expect(result.message).toContain(`Node.js ${MIN_NODE_MAJOR} or newer`);
-    expect(result.message).toContain("18.19.0");
-    expect(result.message).toMatch(/upgrade/i);
-  });
-
-  it("rejects every major below the minimum", () => {
-    for (const version of ["14.21.3", "16.20.2", "19.9.0"]) {
-      const result = checkNodeVersion(version);
-      expect(result.ok).toBe(false);
-      expect(result.message).toBeDefined();
-    }
-  });
-
-  it("accepts Node 20 (the minimum) without a message", () => {
-    const result = checkNodeVersion("20.11.1");
-
-    expect(result.ok).toBe(true);
-    expect(result.major).toBe(20);
-    expect(result.message).toBeUndefined();
-  });
-
-  it("accepts newer majors (22, 24)", () => {
-    for (const version of ["22.3.0", "24.0.0"]) {
-      const result = checkNodeVersion(version);
-      expect(result.ok).toBe(true);
-      expect(result.message).toBeUndefined();
-    }
-  });
-
-  it("treats an unparseable version as supported (never blocks on a bad string)", () => {
-    const result = checkNodeVersion("not-a-version");
-
-    expect(result.ok).toBe(true);
-    expect(result.message).toBeUndefined();
-  });
-
-  it("defaults to the running runtime, which is supported in CI", () => {
-    // The test runner itself must be on a supported Node, so the default-arg
-    // path returns ok — also proving importing this module did not exit.
-    expect(checkNodeVersion().ok).toBe(true);
-  });
-});