@indigoai-us/hq-cli 5.77.8 → 5.77.9

package/dist/utils/version-gate.js

@@ -72,20 +72,95 @@ export function npmPrefixFromPackageDir(pkgDir) {
         return "/";
     return prefix || null;
 }
-export function resolveRunningPrefix() {
+/** `$PNPM_HOME/global`, normalised to forward slashes, when PNPM_HOME is set. */
+function pnpmHomeGlobalRoot() {
+    const home = process.env.PNPM_HOME;
+    if (!home)
+        return null;
+    const normalized = home.replace(/\\/g, "/").replace(/\/+$/, "");
+    return normalized ? `${normalized}/global` : null;
+}
+/**
+ * Whether the running package lives inside a pnpm-managed **global** install.
+ *
+ * pnpm does not use npm's `<prefix>/lib/node_modules` layout. A global
+ * `pnpm add -g` puts the package in a versioned content store under the
+ * `global/<store-layout-version>` root and exposes it through a generated shim
+ * on PATH:
+ *
+ *   $PNPM_HOME/hq                                        <- shim on PATH
+ *   $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli <- symlink
+ *   $PNPM_HOME/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/…
+ *
+ * Both the symlinked and the resolved (`.pnpm`) form are recognised, because
+ * whether `import.meta.url` reports the link or its target depends on how node
+ * resolved the entrypoint.
+ *
+ * A bare `.pnpm` segment is deliberately NOT enough. It also appears in a local
+ * project dependency (`<proj>/node_modules/.pnpm/@indigoai-us+hq-cli@…`) and in
+ * a `pnpm dlx` cache. Neither of those is what `pnpm add -g` updates, so
+ * treating them as global would mutate the user's global install as a side
+ * effect of a local invocation while the copy actually running stayed stale —
+ * i.e. the gate would re-fire and re-install globally on every subsequent run.
+ * Those layouts fall through to the ordinary npm-prefix/manual handling.
+ */
+export function isPnpmManagedPackageDir(pkgDir) {
+    const normalized = pkgDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/").filter(Boolean);
+    // `global/<digits>` — pnpm's global root, in either the symlinked or the
+    // resolved (`.pnpm`) form, and independent of where PNPM_HOME points.
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        if (segments[i] === "global" && /^\d+$/.test(segments[i + 1]))
+            return true;
+    }
+    // Belt-and-braces for a future pnpm layout whose store dir is not numeric:
+    // anything under `$PNPM_HOME/global` is global by construction. Still keyed
+    // on the `global` segment so `$PNPM_HOME/store/**` (dlx caches) stays out.
+    const globalRoot = pnpmHomeGlobalRoot();
+    if (globalRoot) {
+        if (normalized === globalRoot || normalized.startsWith(`${globalRoot}/`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function resolveRunningInstall() {
     try {
-        const pkgRoot = findRunningPackageRoot();
-        if (!pkgRoot)
-            return null;
-        return npmPrefixFromPackageDir(pkgRoot);
+        const packageRoot = findRunningPackageRoot();
+        if (!packageRoot)
+            return { manager: "npm", prefix: null, packageRoot: null };
+        if (isPnpmManagedPackageDir(packageRoot)) {
+            return { manager: "pnpm", prefix: null, packageRoot };
+        }
+        return {
+            manager: "npm",
+            prefix: npmPrefixFromPackageDir(packageRoot),
+            packageRoot,
+        };
     }
     catch {
-        return null;
+        return { manager: "npm", prefix: null, packageRoot: null };
     }
 }
+/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
+export function resolveRunningManager() {
+    return resolveRunningInstall().manager;
+}
+/** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
+export function resolveRunningPrefix() {
+    return resolveRunningInstall().prefix;
+}
 export function buildPrefixedInstallArgv(prefix) {
     return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
 }
+/**
+ * Argv for updating a pnpm-managed global install. `pnpm add -g` rewrites the
+ * PATH shim as part of the install, so the next invocation genuinely resolves
+ * the new version — which is the whole point of routing here instead of npm.
+ */
+export function buildPnpmInstallArgv() {
+    return ["add", "-g", LATEST_PACKAGE_SPEC];
+}
 const nodeStaleInstallFs = {
     readdirSync: (dir) => readdirSync(dir),
     existsSync,
@@ -205,9 +280,44 @@ async function fetchVersionDecision() {
         return null;
     }
 }
+/**
+ * Quote an argv entry for a Windows `cmd.exe` invocation. Needed because Node
+ * does NOT quote argv when spawning with `shell: true` on Windows — it joins
+ * the array with spaces — so an npm prefix like `C:\Program Files\…` would be
+ * split into two arguments.
+ */
+export function quoteForWindowsShell(arg) {
+    if (arg === "")
+        return '""';
+    if (!/[\s"^&|<>()]/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+/**
+ * How to hand `<cmd> <args…>` to `spawnSync` on this platform.
+ *
+ * On Windows both `npm` and `pnpm` are `.cmd` shims, and since the
+ * CVE-2024-27980 hardening Node refuses to spawn a `.cmd`/`.bat` file without
+ * a shell. Without this the update would fail with EINVAL/ENOENT on every
+ * Windows install — including the pnpm layouts this gate claims to detect.
+ */
+export function buildSpawnPlan(cmd, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { cmd, args: [...args], shell: false };
+    return { cmd, args: args.map(quoteForWindowsShell), shell: true };
+}
 function runUpdateCommand(cmd, args) {
     try {
-        const result = spawnSync(cmd, args, { stdio: "inherit" });
+        const plan = buildSpawnPlan(cmd, args);
+        const result = spawnSync(plan.cmd, plan.args, {
+            stdio: "inherit",
+            shell: plan.shell,
+        });
+        // spawnSync reports a missing executable via `error`, not a throw.
+        if (result.error) {
+            const code = result.error.code;
+            return { ok: false, code, detail: result.error.message };
+        }
         if (result.status !== 0) {
             return {
                 ok: false,
@@ -217,7 +327,11 @@ function runUpdateCommand(cmd, args) {
         return { ok: true };
     }
     catch (err) {
-        return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+        return {
+            ok: false,
+            code: err?.code,
+            detail: err instanceof Error ? err.message : String(err),
+        };
     }
 }
 function performUpdateCommand(cmd, args, runner = runUpdateCommand) {
@@ -231,15 +345,38 @@ function performUpdate(command, runner = runUpdateCommand) {
     const args = parts.slice(1);
     return performUpdateCommand(cmd, args, runner);
 }
+/**
+ * The command a user should run by hand for this install layout. hq-pro's
+ * `updateCommand` is npm-shaped for every client, so a pnpm-managed install
+ * must never be told to run it: `npm install -g …` drops a fresh copy under the
+ * npm global prefix while pnpm's PATH shim keeps resolving the old build. That
+ * is verbatim the reported symptom (a stale shim still reporting 5.61.0 after a
+ * "successful" update), so both the hard gate and the soft nudge below have to
+ * speak the running manager's language.
+ */
+function manualUpdateCommand(install, decision) {
+    if (install.manager === "pnpm")
+        return `pnpm ${buildPnpmInstallArgv().join(" ")}`;
+    if (install.prefix)
+        return `npm ${buildPrefixedInstallArgv(install.prefix).join(" ")}`;
+    return decision.updateCommand;
+}
 /**
  * Soft notify when the server says we're below `latestVersion` but still ≥
  * `minVersion`. Single chalk-yellow line on stderr; never blocks.
+ *
+ * This path fires for EVERY version below latest (the hard gate only fires
+ * below `minVersion`), so it is the far more frequently seen of the two and
+ * must be manager-aware for the same reason the gate is.
  */
-function nudgeUpdateRecommended(decision) {
+function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
     const msg = chalk.yellow(`⚠ A new version of hq-cli is available: ${decision.latestVersion} (current: ${decision.currentVersion}).`);
     console.error(msg);
-    if (decision.updateCommand) {
-        console.error(chalk.dim(`  Update: ${decision.updateCommand}`));
+    const command = install.manager === "pnpm"
+        ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
+        : decision.updateCommand;
+    if (command) {
+        console.error(chalk.dim(`  Update: ${command}`));
     }
 }
 /**
@@ -258,8 +395,14 @@ function enforceUpdateRequired(decision, deps = {}) {
     if (decision.message)
         console.error(chalk.dim(`  ${decision.message}`));
     const command = decision.updateCommand;
-    const prefix = (deps.resolvePrefix ?? resolveRunningPrefix)();
-    if (!command && !prefix) {
+    // ONE package-root walk decides both the manager and the prefix. A
+    // pnpm-managed install must be updated by pnpm; the server's `updateCommand`
+    // and any npm prefix are both wrong for that layout, so `resolveRunningInstall`
+    // already reports `prefix: null` there and neither is consulted below.
+    const install = (deps.resolveInstall ?? resolveRunningInstall)();
+    const isPnpm = install.manager === "pnpm";
+    const prefix = install.prefix;
+    if (!isPnpm && !command && !prefix) {
         console.error(chalk.red("  No updateCommand provided by hq-pro — see https://hq.indigo.ai/docs/cli-update for manual steps."));
         if (decision.downloadUrl) {
             console.error(chalk.dim(`  Download: ${decision.downloadUrl}`));
@@ -271,7 +414,11 @@ function enforceUpdateRequired(decision, deps = {}) {
     // the EXACT same command under elevation.
     let primaryCmd;
     let primaryArgs;
-    if (prefix) {
+    if (isPnpm) {
+        primaryCmd = "pnpm";
+        primaryArgs = buildPnpmInstallArgv();
+    }
+    else if (prefix) {
         primaryCmd = "npm";
         primaryArgs = buildPrefixedInstallArgv(prefix);
     }
@@ -280,18 +427,23 @@ function enforceUpdateRequired(decision, deps = {}) {
         primaryCmd = parts[0] ?? "";
         primaryArgs = parts.slice(1);
     }
-    let result = prefix
-        ? (() => {
-            console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
-            console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
-            return performUpdateCommand("npm", primaryArgs, runner);
-        })()
-        : (() => {
-            console.error(chalk.dim(`  Running: ${command}`));
-            return deps.performUpdateString
-                ? deps.performUpdateString(command)
-                : performUpdate(command, runner);
-        })();
+    let result;
+    if (isPnpm) {
+        console.error(chalk.dim("  Detected a pnpm-managed global install; updating with pnpm"));
+        console.error(chalk.dim(`  Running: pnpm ${primaryArgs.join(" ")}`));
+        result = performUpdateCommand("pnpm", primaryArgs, runner);
+    }
+    else if (prefix) {
+        console.error(chalk.dim(`  Installing into npm prefix: ${prefix}`));
+        console.error(chalk.dim(`  Running: npm ${primaryArgs.join(" ")}`));
+        result = performUpdateCommand("npm", primaryArgs, runner);
+    }
+    else {
+        console.error(chalk.dim(`  Running: ${command}`));
+        result = deps.performUpdateString
+            ? deps.performUpdateString(command)
+            : performUpdate(command, runner);
+    }
     // A partial/corrupt global install leaves npm unable to atomically rename its
     // freshly-unpacked package over a leftover directory, so the install above
     // fails with ENOTEMPTY (e.g. a prior interrupted `npm install -g` left a
@@ -316,7 +468,11 @@ function enforceUpdateRequired(decision, deps = {}) {
     // Homebrew on macOS, where the first attempt already succeeded anyway) fall
     // through to the manual path unchanged, while headless boxes with passwordless
     // sudo self-update cleanly.
-    if (!result.ok && primaryCmd) {
+    //
+    // Never for pnpm: `sudo -n pnpm add -g` installs into ROOT's PNPM_HOME, which
+    // leaves the user's shim untouched while reporting success — the same silent
+    // no-op this fix exists to remove. A failed pnpm update must surface instead.
+    if (!result.ok && primaryCmd && !isPnpm) {
         console.error(chalk.dim(`  Update failed unprivileged; retrying with: sudo -n ${primaryCmd} ${primaryArgs.join(" ")}`));
         const sudoResult = performUpdateCommand("sudo", ["-n", primaryCmd, ...primaryArgs], runner);
         if (sudoResult.ok)
@@ -324,10 +480,21 @@ function enforceUpdateRequired(decision, deps = {}) {
     }
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        const manual = prefix
-            ? `npm ${buildPrefixedInstallArgv(prefix).join(" ")}`
-            : command;
+        // The package manager itself is missing from this environment — the usual
+        // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
+        // never sourced the shell profile which puts PNPM_HOME (or nvm's npm) on
+        // PATH. Say so, because "exit 75" alone reads as a permissions problem.
+        if (result.code === "ENOENT") {
+            console.error(chalk.red(`  \`${primaryCmd}\` was not found on PATH in this environment (launchd, cron and other minimal-PATH parents commonly lack it).`));
+        }
+        const manual = manualUpdateCommand(install, decision) ?? command;
         console.error(chalk.dim(`  Try manually: ${manual}`));
+        // Only informational, and only when we could not run the right manager at
+        // all: hq-pro's command is npm-shaped, so following it on a pnpm layout is
+        // what produced the stale-shim loop in the first place.
+        if (isPnpm && result.code === "ENOENT" && command) {
+            console.error(chalk.dim(`  (hq-pro suggests \`${command}\` — that is for npm-managed installs; use it only if you have switched this install to npm.)`));
+        }
         process.exit(75);
     }
     console.error(chalk.green(`✓ Updated to hq-cli ${decision.latestVersion}. Rerun your command.`));
@@ -349,11 +516,16 @@ export async function enforceVersionGate() {
     const decision = await fetchVersionDecision();
     if (!decision)
         return; // best-effort: silent on any failure
+    if (!decision.updateRequired && !decision.updateRecommended)
+        return;
+    // Resolved once, here, so the up-to-date case never pays for the walk and
+    // neither downstream path repeats it.
+    const install = resolveRunningInstall();
     if (decision.updateRequired) {
-        enforceUpdateRequired(decision); // exits process
+        enforceUpdateRequired(decision, { resolveInstall: () => install }); // exits process
     }
     if (decision.updateRecommended) {
-        nudgeUpdateRecommended(decision);
+        nudgeUpdateRecommended(decision, install);
     }
 }
 /**
@@ -368,13 +540,20 @@ export const __test__ = {
     CLIENT_ID,
     ENDPOINT_PATH,
     FETCH_TIMEOUT_MS,
+    buildPnpmInstallArgv,
     buildPrefixedInstallArgv,
+    buildSpawnPlan,
     cleanStalePartialInstall,
     enforceUpdateRequired,
+    isPnpmManagedPackageDir,
     npmPrefixFromPackageDir,
+    nudgeUpdateRecommended,
     performUpdate,
     performUpdateCommand,
+    quoteForWindowsShell,
     runUpdateCommand,
+    resolveRunningInstall,
+    resolveRunningManager,
     resolveRunningPrefix,
 };
 //# sourceMappingURL=version-gate.js.map

package/package.json

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

package/src/commands/reindex.test.ts

@@ -42,7 +42,7 @@ function writeSettings(root: string, settings: unknown): void {
 }
 
 function makeHqRoot(settings: unknown = HEALTHY_SETTINGS): string {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-reindex-"));
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "hq-reindex-")));
   tempRoots.push(root);
   fs.mkdirSync(path.join(root, ".claude"), { recursive: true });
   fs.mkdirSync(path.join(root, "companies"), { recursive: true });

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

@@ -0,0 +1,317 @@
+/**
+ * Unit tests for `plan-limit-nag` (US-016).
+ *
+ * Coverage:
+ *   1. Warning renders when ≥80% metadata present; absent → no output.
+ *   2. Malformed planLimits ignored (no output, no throw).
+ *   3. Once-per-session: second emit prints nothing.
+ *   4. Over-limit boxed notice; same-day state suppresses; >24h re-prints.
+ *   5. HQ_NO_PLAN_LIMIT_NAG=1 disables all output.
+ *   6. emit never throws even when statePath unwritable.
+ *   7. Exit-code neutrality: emit does not touch process.exitCode.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  PLAN_LIMIT_UPGRADE_URL,
+  _resetForTests,
+  emitPlanLimitNag,
+  recordPlanLimitStatus,
+} from "./plan-limit-nag.js";
+
+function makeSink(): { lines: string[]; write: (s: string) => void } {
+  const lines: string[] = [];
+  return {
+    lines,
+    write: (s: string) => {
+      lines.push(s);
+    },
+  };
+}
+
+function tmpStatePath(): string {
+  return path.join(
+    os.tmpdir(),
+    `hq-plan-limit-nag-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+}
+
+/**
+ * Portable unwritable statePath: join under a plain FILE so
+ * mkdirSync/writeFileSync/readFileSync fail immediately with ENOTDIR
+ * on every platform (unlike /proc paths, which hang on Linux procfs).
+ */
+function unwritableStatePath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-nag-"));
+  const file = path.join(dir, "not-a-dir");
+  fs.writeFileSync(file, "x");
+  return path.join(file, "x", "plan-limit-nag.json");
+}
+
+const ENV_KEY = "HQ_NO_PLAN_LIMIT_NAG";
+let prevEnv: string | undefined;
+
+beforeEach(() => {
+  _resetForTests();
+  prevEnv = process.env[ENV_KEY];
+  delete process.env[ENV_KEY];
+});
+
+afterEach(() => {
+  if (prevEnv === undefined) {
+    delete process.env[ENV_KEY];
+  } else {
+    process.env[ENV_KEY] = prevEnv;
+  }
+  _resetForTests();
+});
+
+describe("recordPlanLimitStatus + emitPlanLimitNag (warning path)", () => {
+  it("renders a one-line warning when planLimits has a ≥80% entry", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      ok: true,
+      planLimits: {
+        users: { used: 9, limit: 10, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/HQ free plan/i);
+    expect(sink.lines[0]).toMatch(/users at 9\/10 \(90%\)/);
+    expect(sink.lines[0]).toContain(PLAN_LIMIT_UPGRADE_URL);
+  });
+
+  it("produces no output when planLimits metadata is absent", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({ ok: true, items: [] });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("produces no output when recordPlanLimitStatus was never called", () => {
+    const sink = makeSink();
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("lists the worst resource when multiple ≥80% entries exist", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 8, limit: 10, over: false },
+        secrets: { used: 19, limit: 20, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/secrets at 19\/20/);
+  });
+});
+
+describe("malformed planLimits", () => {
+  it("ignores wrong types — no output, no throw", () => {
+    const sink = makeSink();
+    expect(() =>
+      recordPlanLimitStatus({
+        planLimits: {
+          users: { used: "9", limit: 10, over: false },
+          secrets: { used: 5, limit: "10", over: true },
+          agents: null,
+          integrations: "nope",
+        },
+      }),
+    ).not.toThrow();
+    expect(() =>
+      emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() }),
+    ).not.toThrow();
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("ignores non-object planLimits", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({ planLimits: "not-an-object" });
+    recordPlanLimitStatus({ planLimits: [1, 2, 3] });
+    recordPlanLimitStatus({ planLimits: null });
+    recordPlanLimitStatus(null);
+    recordPlanLimitStatus("string");
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("accepts only well-formed entries and still emits when mixed", () => {
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        bad: { used: "x", limit: 1, over: false },
+        users: { used: 9, limit: 10, over: false },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/users at 9\/10/);
+  });
+});
+
+describe("once-per-session dedupe", () => {
+  it("second emit prints nothing for the warning path", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 9, limit: 10, over: false } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath });
+    emitPlanLimitNag({ write: sink.write, statePath });
+    expect(sink.lines).toHaveLength(1);
+  });
+});
+
+describe("over-limit boxed notice", () => {
+  it("prints a boxed over-limit notice listing over resources", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 11, limit: 10, over: true },
+        secrets: { used: 5, limit: 20, over: false },
+      },
+      requiredPlan: "agents-500",
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    expect(sink.lines).toHaveLength(1);
+    const out = sink.lines[0] ?? "";
+    expect(out).toMatch(/plan limit exceeded/i);
+    expect(out).toMatch(/users:\s*11\/10/);
+    expect(out).toContain(PLAN_LIMIT_UPGRADE_URL);
+    expect(out).toMatch(/[┌└│─]/);
+    // Non-over resources should not appear in the over box resource list.
+    expect(out).not.toMatch(/secrets:\s*5\/20/);
+  });
+
+  it("second emit same day (fresh shownAt in statePath) prints nothing", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    const now = new Date("2026-03-01T12:00:00.000Z");
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({ shownAt: now.getTime() - 60 * 60 * 1000 }),
+    );
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath, now: () => now });
+    expect(sink.lines).toHaveLength(0);
+  });
+
+  it("shownAt older than 24h prints again", () => {
+    const sink = makeSink();
+    const statePath = tmpStatePath();
+    const now = new Date("2026-03-02T13:00:00.000Z");
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({
+        shownAt: now.getTime() - 25 * 60 * 60 * 1000,
+      }),
+    );
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath, now: () => now });
+    expect(sink.lines).toHaveLength(1);
+    expect(sink.lines[0]).toMatch(/plan limit exceeded/i);
+  });
+
+  it("session-dedupes over notice even without state file", () => {
+    const sink = makeSink();
+    // Unwritable parent: skip persistence but still session-dedupe.
+    const statePath = unwritableStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 11, limit: 10, over: true } },
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    emitPlanLimitNag({
+      write: sink.write,
+      statePath,
+      now: () => new Date("2026-03-01T12:00:00.000Z"),
+    });
+    expect(sink.lines).toHaveLength(1);
+  });
+});
+
+describe("env off-switch", () => {
+  it("HQ_NO_PLAN_LIMIT_NAG=1 produces no output", () => {
+    process.env[ENV_KEY] = "1";
+    const sink = makeSink();
+    recordPlanLimitStatus({
+      planLimits: {
+        users: { used: 11, limit: 10, over: true },
+      },
+    });
+    emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+    expect(sink.lines).toHaveLength(0);
+  });
+});
+
+describe("resilience + exit-code neutrality", () => {
+  it("emit never throws even when statePath is unwritable", () => {
+    const sink = makeSink();
+    const statePath = unwritableStatePath();
+    recordPlanLimitStatus({
+      planLimits: { users: { used: 12, limit: 10, over: true } },
+    });
+    expect(() =>
+      emitPlanLimitNag({
+        write: sink.write,
+        statePath,
+        now: () => new Date("2026-03-01T12:00:00.000Z"),
+      }),
+    ).not.toThrow();
+    // Still attempted to print (write may succeed even if state write fails).
+    expect(sink.lines.length).toBeGreaterThanOrEqual(0);
+  });
+
+  it("does not touch process.exitCode", () => {
+    const prev = process.exitCode;
+    process.exitCode = 0;
+    try {
+      const sink = makeSink();
+      recordPlanLimitStatus({
+        planLimits: { users: { used: 9, limit: 10, over: false } },
+      });
+      emitPlanLimitNag({ write: sink.write, statePath: tmpStatePath() });
+      expect(process.exitCode).toBe(0);
+
+      process.exitCode = 1;
+      _resetForTests();
+      recordPlanLimitStatus({
+        planLimits: { users: { used: 11, limit: 10, over: true } },
+      });
+      emitPlanLimitNag({
+        write: sink.write,
+        statePath: tmpStatePath(),
+        now: () => new Date("2026-04-01T00:00:00.000Z"),
+      });
+      expect(process.exitCode).toBe(1);
+    } finally {
+      process.exitCode = prev;
+    }
+  });
+
+  it("recordPlanLimitStatus never throws on garbage input", () => {
+    expect(() => recordPlanLimitStatus(undefined)).not.toThrow();
+    expect(() => recordPlanLimitStatus(42)).not.toThrow();
+    expect(() => recordPlanLimitStatus([])).not.toThrow();
+  });
+});