@indigoai-us/hq-cli 5.119.8 → 5.119.10

package/dist/lib/billing/plan-lock.js

@@ -1,14 +1,19 @@
 /**
- * `plan-lock` (starter-plan-hard-limits / US-011) — the CLI-side read + render
- * of the workspace plan lock.
+ * `plan-lock` (starter-plan-hard-limits / US-011, rewritten for US-036) — the
+ * CLI-side read + render of a workspace's Starter plan-limit state.
  *
- * Starter (free) workspaces are capped on four locking dimensions — members,
- * integrations, secrets and agents (owner decision 7, 2026-09-17; deployments
- * and storage nag but never lock). Going over locks the workspace immediately: it becomes read-only until the owner
- * trims back under the caps or upgrades to HQ Workforce. The lock decision is
- * NOT made here — hq-pro's `src/billing/plan-lock.ts` is the single source of
- * truth and ships the answer on `GET /membership/me` as a per-company
- * `planLock` object. This module only reads that field and renders it.
+ * Starter (free) workspaces are capped on members, integrations, secrets and
+ * agents (deployments and storage nag but never arm a stop). Going over does
+ * NOT stop the workspace working (US-033 owner decision 12): everything that
+ * exists keeps working, and the only two things that pause are adding new
+ * files to the vault and adding new secrets (owner decision 13). Every string
+ * this module renders is a nag, never a claim that HQ has stopped. The state
+ * is NOT decided here — hq-pro is the single source of truth and ships the
+ * answer on `GET /membership/me` as a per-company `planLock` object. This
+ * module only reads that field and renders it.
+ *
+ * Copy rule (US-036): no string a customer reads may contain "locked" or
+ * "read-only". `plan-lock.test.ts` scans every rendered string for both.
  *
  * Member counts are decoration, never a second opinion: the count comes from
  * `GET /v1/billing/usage-limits` on a best-effort basis and its absence only
@@ -20,7 +25,7 @@ import chalk from "chalk";
 import { vaultApiFetch } from "../../utils/vault-api.js";
 /**
  * Mirror of hq-pro's `PlanLockReason`. Owner decision 7 (2026-09-17) fixes the
- * locking set at these four: `deployments` and `storageBytes` are nag-only and
+ * nagging set at these four: `deployments` and `storageBytes` are nag-only and
  * never appear here. An unrecognised reason is dropped by `parsePlanLock`, so a
  * server that adds a fifth dimension renders as the generic line rather than as
  * a false claim about members.
@@ -204,7 +209,7 @@ export async function fetchPlanLockStatus(token, companyRef, opts = {}) {
         checkedAt: new Date().toISOString(),
     };
 }
-/** Why the workspace locked, one clause per reason. */
+/** Why the workspace is over, one clause per reason. */
 export function reasonLabel(reason) {
     switch (reason) {
         case "users":
@@ -261,23 +266,34 @@ function reasonDetail(reason, status) {
             return "agents are not included on Starter";
     }
 }
+/**
+ * The one sentence every over-limit surface says about the two hard stops
+ * (US-033 §3.3). Written once so the CLI, the console and the emails cannot
+ * drift into three different promises.
+ */
+export const HARD_STOP_SENTENCE = "Nothing has been deleted and everything keeps working, except that new " +
+    "files and new secrets are paused until this is sorted.";
+const HARD_STOP_SENTENCE_LINES = [
+    "  Nothing has been deleted and everything keeps working, except that new",
+    "  files and new secrets are paused until this is sorted.",
+];
 function capitalize(text) {
     return text.charAt(0).toUpperCase() + text.slice(1);
 }
 /**
- * The full WORKSPACE LOCKED block: why it locked, where the workspace stands
+ * The full over-limit block: why the workspace is over, where it stands
  * against the cap, and the ways out. Plain text — colour is applied by the
  * caller so scripts capturing stdout get a clean block.
  *
- * Every line is derived from `lock.reasons`. A workspace locked on secrets is
+ * Every line is derived from `lock.reasons`. A workspace over on secrets is
  * never told it has too many members, and an empty reason list (a server
  * dimension this CLI does not know) renders a generic line rather than a claim
  * about a dimension nobody measured.
  */
-export function renderPlanLockNotice(status) {
+export function renderPlanLimitNotice(status) {
     const { lock, members, companySlug } = status;
     const lines = [];
-    lines.push(`WORKSPACE LOCKED — ${companySlug} is over its Starter plan.`);
+    lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
     const reasons = lock.reasons.length
         ? lock.reasons.map(reasonLabel).join("; ")
         : "over the Starter plan limits";
@@ -297,9 +313,9 @@ export function renderPlanLockNotice(status) {
     if (lock.reasons.includes("agents")) {
         lines.push(`  Agents allowed on Starter: ${agentTarget(lock)}.`);
     }
-    lines.push("  Nothing has been deleted. This workspace is read-only until it is fixed:");
-    lines.push("  you can still delete things, but you cannot create, invite or upload.");
-    lines.push("  Two ways to fix it:");
+    lines.push(HARD_STOP_SENTENCE_LINES[0]);
+    lines.push(HARD_STOP_SENTENCE_LINES[1]);
+    lines.push("  Two ways to sort it:");
     const remedy = lock.reasons.length
         ? lock.reasons.map((reason) => reasonRemedy(reason, lock)).join(", and ")
         : "come back under the Starter plan limits";
@@ -309,17 +325,17 @@ export function renderPlanLockNotice(status) {
     return lines.join("\n");
 }
 /**
- * The one-line form injected on every turn while the workspace stays locked.
+ * The one-line form injected on every turn while the workspace stays over.
  * Kept to a single line on purpose — it repeats each turn.
  */
-export function renderPlanLockLine(status) {
+export function renderPlanLimitLine(status) {
     const detail = status.lock.reasons.length
         ? status.lock.reasons
             .map((reason) => reasonDetail(reason, status))
             .join("; ")
         : "over the Starter plan limits";
-    return (`Company ${status.companySlug} is locked on Starter (${detail}). ` +
-        `Writes to HQ cloud will fail until fixed: ${status.lock.upgradeUrl}`);
+    return (`Company ${status.companySlug} is over its Starter limits (${detail}). ` +
+        `New files and new secrets are paused until this is sorted: ${status.lock.upgradeUrl}`);
 }
 /**
  * The `Plan: …` orientation line. Starter only: a paid or enterprise
@@ -327,7 +343,7 @@ export function renderPlanLockLine(status) {
  */
 export function renderPlanLine(status) {
     if (status.lock.locked)
-        return "Plan: Starter — LOCKED";
+        return "Plan: Starter — over its limits";
     if (status.plan !== "free")
         return null;
     const target = status.lock.fixOptions.removeMembersTo;
@@ -336,8 +352,12 @@ export function renderPlanLine(status) {
     }
     return `Plan: Starter — ${target} members included`;
 }
-/** Colourised block for interactive output. */
-export function colorizePlanLockNotice(notice) {
-    return chalk.red(notice);
+/**
+ * Colourised block for interactive output. Yellow, not red: this is a nag, and
+ * an error colour would read as "HQ has stopped working", which is the exact
+ * impression US-033 removes.
+ */
+export function colorizePlanLimitNotice(notice) {
+    return chalk.yellow(notice);
 }
 //# sourceMappingURL=plan-lock.js.map

package/dist/lib/plan-limit-nag.d.ts

@@ -5,17 +5,41 @@
  * some 2xx JSON response bodies (US-012). This module:
  *
  *   1. Best-effort records the last-seen status from decoded JSON bodies
- *      (`recordPlanLimitStatus`).
+ *      (`recordPlanLimitStatus`), and prints the one-time threshold notice
+ *      right there — see below.
  *   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
+ *      - any resource over: one-line notice, at most once every 6 hours
+ *        (persisted in `~/.hq/plan-limit-nag.json`) and once per session
+ *
+ * The one-time threshold notice (US-035) is the third surface and the only one
+ * that does NOT wait for command completion. hq-pro attaches
+ * `thresholdCrossings: [{ resource, band, firstSeenAt, used, limit }]` beside
+ * `planLimits`, populated from the server's own threshold state, and this
+ * module prints each `{resource}:{band}` exactly once per EPISODE — persisted
+ * in `~/.hq/plan-limit-nag.json` under `notifiedThresholds`. It prints from the
+ * record path so a session that is already running surfaces the notice on its
+ * next API call rather than on its next launch, which is the whole point of
+ * carrying the crossing on the wire instead of recomputing it locally.
+ *
+ * "Once per episode", not once per lifetime: the stored value is the server's
+ * `firstSeenAt`, so a dimension that drops back under the threshold and climbs
+ * again arrives with a new timestamp and notifies again. The server decides
+ * when an episode ends; this module only remembers what it has printed.
  *
  * Additive only — never throws, never touches `process.exitCode`, never
- * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
+ * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1` silences all
+ * three surfaces, the threshold notice included.
  */
 export declare const PLAN_LIMIT_UPGRADE_URL = "https://hq.computer/billing/upgrade";
+/**
+ * Cadence of the over-limit per-turn line (US-036). Was once a day; the nag
+ * model wants it more often than that and still not on every turn, so the
+ * window is six hours — up to four lines in a day for someone working all day,
+ * and one for someone who runs a single command.
+ */
+export declare const OVER_NAG_INTERVAL_MS: number;
 /**
  * Plain-English name for each plan-limit resource key, so a nag line says which
  * dimension is tight rather than only the wire key. The key itself stays in the
@@ -31,12 +55,54 @@ export interface PlanLimitEntry {
 }
 /** Validated map of resource key → entry. */
 export type PlanLimitsMap = Record<string, PlanLimitEntry>;
+/** The two bands hq-pro reports. Anything else on the wire is ignored. */
+export declare const PLAN_LIMIT_BANDS: readonly ["warn", "over"];
+export type PlanLimitBand = (typeof PLAN_LIMIT_BANDS)[number];
+/** One server-announced threshold crossing, as it arrives on the wire. */
+export interface PlanLimitThresholdCrossing {
+    resource: string;
+    band: PlanLimitBand;
+    /** ISO time the server first recorded this band — the episode identity. */
+    firstSeenAt: string;
+    used: number;
+    limit: number;
+}
 /**
  * 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 declare function recordPlanLimitStatus(body: unknown): void;
+export declare function recordPlanLimitStatus(body: unknown, opts?: {
+    write?: (s: string) => void;
+    statePath?: string;
+}): void;
+/**
+ * The over-limit per-turn line (US-036 §2.2). One line, not the old box: it
+ * now repeats up to four times a day, and a multi-line box at that cadence
+ * reads as breakage rather than as a nag. It states the two paused things and
+ * never claims the workspace has stopped working.
+ */
+export declare function buildOverLine(overEntries: Array<[string, PlanLimitEntry]>, upgradeUrl: string): string;
+/**
+ * One line per crossing.
+ *
+ * The copy states the fact and the exit, nothing else. It deliberately does
+ * not describe consequences that have not shipped: the hard stops arrive with
+ * their own story, and a notice that announces a pause nobody is experiencing
+ * reads as a bug.
+ */
+export declare function renderThresholdNotice(crossing: PlanLimitThresholdCrossing, upgradeUrl: string): string;
+/**
+ * Print every crossing this machine has not already printed for this episode.
+ *
+ * Called from the record path, so a session already running prints on its next
+ * API call. Never throws; a state file it cannot read or write degrades to
+ * per-process dedupe rather than to silence or to repetition.
+ */
+export declare function emitPlanLimitThresholdNotice(crossings: readonly PlanLimitThresholdCrossing[], upgradeUrl: string | null, opts?: {
+    write?: (s: string) => void;
+    statePath?: string;
+}): void;
 /**
  * Emit a plan-limit nag to stderr at command completion.
  *

package/dist/lib/plan-limit-nag.js

@@ -5,22 +5,45 @@
  * some 2xx JSON response bodies (US-012). This module:
  *
  *   1. Best-effort records the last-seen status from decoded JSON bodies
- *      (`recordPlanLimitStatus`).
+ *      (`recordPlanLimitStatus`), and prints the one-time threshold notice
+ *      right there — see below.
  *   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
+ *      - any resource over: one-line notice, at most once every 6 hours
+ *        (persisted in `~/.hq/plan-limit-nag.json`) and once per session
+ *
+ * The one-time threshold notice (US-035) is the third surface and the only one
+ * that does NOT wait for command completion. hq-pro attaches
+ * `thresholdCrossings: [{ resource, band, firstSeenAt, used, limit }]` beside
+ * `planLimits`, populated from the server's own threshold state, and this
+ * module prints each `{resource}:{band}` exactly once per EPISODE — persisted
+ * in `~/.hq/plan-limit-nag.json` under `notifiedThresholds`. It prints from the
+ * record path so a session that is already running surfaces the notice on its
+ * next API call rather than on its next launch, which is the whole point of
+ * carrying the crossing on the wire instead of recomputing it locally.
+ *
+ * "Once per episode", not once per lifetime: the stored value is the server's
+ * `firstSeenAt`, so a dimension that drops back under the threshold and climbs
+ * again arrives with a new timestamp and notifies again. The server decides
+ * when an episode ends; this module only remembers what it has printed.
  *
  * Additive only — never throws, never touches `process.exitCode`, never
- * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
+ * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1` silences all
+ * three surfaces, the threshold notice included.
  */
 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://hq.computer/billing/upgrade";
-const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Cadence of the over-limit per-turn line (US-036). Was once a day; the nag
+ * model wants it more often than that and still not on every turn, so the
+ * window is six hours — up to four lines in a day for someone working all day,
+ * and one for someone who runs a single command.
+ */
+export const OVER_NAG_INTERVAL_MS = 6 * 60 * 60 * 1000;
 /**
  * Plain-English name for each plan-limit resource key, so a nag line says which
  * dimension is tight rather than only the wire key. The key itself stays in the
@@ -40,12 +63,22 @@ function dimensionSuffix(key) {
     const label = PLAN_LIMIT_DIMENSION_LABELS[key];
     return label && label !== key ? ` (${label})` : "";
 }
+/** The two bands hq-pro reports. Anything else on the wire is ignored. */
+export const PLAN_LIMIT_BANDS = ["warn", "over"];
 /** Module-level last-seen cell — overwritten by each successful parse. */
 let lastSeen = null;
 /** Session dedupe for the ≥80% one-line warning. */
 let warningShownThisSession = false;
-/** Session dedupe for the over-limit boxed notice. */
+/** Session dedupe for the over-limit line. */
 let overShownThisSession = false;
+/**
+ * `"{resource}:{band}"` → `firstSeenAt` already printed in THIS process.
+ *
+ * The persisted file is the durable dedupe; this map exists so a process that
+ * cannot write `~/.hq` (read-only home, sandboxed agent) still prints each
+ * crossing once rather than on every single API call.
+ */
+const thresholdsShownThisSession = new Map();
 function defaultStatePath() {
     return path.join(os.homedir(), ".hq", "plan-limit-nag.json");
 }
@@ -122,18 +155,67 @@ function parsePlanLimits(body) {
         }
         : null;
 }
+/**
+ * Defensively parse the top-level `thresholdCrossings` array.
+ *
+ * Every field is validated and a malformed ROW is dropped rather than failing
+ * the whole array — an older CLI must stay useful against a newer server that
+ * has added a band or a field. An unrecognised band is dropped for the same
+ * reason it is not guessed at: printing "you have reached critical of your
+ * secrets" is worse than printing nothing.
+ */
+function parseThresholdCrossings(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return [];
+    }
+    const raw = body.thresholdCrossings;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const value of raw) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            continue;
+        }
+        const rec = value;
+        if (typeof rec.resource !== "string" || rec.resource.length === 0)
+            continue;
+        if (typeof rec.band !== "string" ||
+            !PLAN_LIMIT_BANDS.includes(rec.band)) {
+            continue;
+        }
+        if (typeof rec.firstSeenAt !== "string" || rec.firstSeenAt.length === 0) {
+            continue;
+        }
+        if (typeof rec.used !== "number" || !Number.isFinite(rec.used))
+            continue;
+        if (typeof rec.limit !== "number" || !Number.isFinite(rec.limit))
+            continue;
+        out.push({
+            resource: rec.resource,
+            band: rec.band,
+            firstSeenAt: rec.firstSeenAt,
+            used: rec.used,
+            limit: rec.limit,
+        });
+    }
+    return out;
+}
 /**
  * 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) {
+export function recordPlanLimitStatus(body, opts = {}) {
     try {
         const status = parsePlanLimits(body);
-        if (status === null)
-            return;
-        const anyOver = Object.values(status.limits).some((e) => e.over);
-        lastSeen = { ...status, anyOver };
+        if (status !== null) {
+            const anyOver = Object.values(status.limits).some((e) => e.over);
+            lastSeen = { ...status, anyOver };
+        }
+        // Independent of `planLimits`: the server can announce a crossing on a
+        // response whose nag map this CLI could not parse, and the notice is the
+        // one surface that must land inside a session that is already running.
+        emitPlanLimitThresholdNotice(parseThresholdCrossings(body), status?.upgradeUrl ?? null, opts);
     }
     catch {
         // Never throw from record path.
@@ -163,44 +245,148 @@ function formatPct(entry) {
 function formatEntryLine(key, entry) {
     return `${key} at ${entry.used}/${entry.limit} (${formatPct(entry)})${dimensionSuffix(key)}`;
 }
-function readShownAt(statePath) {
+/**
+ * Read the whole state file. A missing, unreadable or malformed file is an
+ * empty state — the nag re-arms rather than being silenced by a bad write.
+ */
+function readNagState(statePath) {
     try {
         const raw = fs.readFileSync(statePath, "utf-8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.shownAt !== "number" || !Number.isFinite(parsed.shownAt)) {
-            return null;
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
         }
-        return parsed.shownAt;
+        const rec = parsed;
+        const state = {};
+        if (typeof rec.shownAt === "number" && Number.isFinite(rec.shownAt)) {
+            state.shownAt = rec.shownAt;
+        }
+        if (rec.notifiedThresholds !== null &&
+            typeof rec.notifiedThresholds === "object" &&
+            !Array.isArray(rec.notifiedThresholds)) {
+            const entries = Object.entries(rec.notifiedThresholds).filter((pair) => typeof pair[1] === "string");
+            if (entries.length > 0) {
+                state.notifiedThresholds = Object.fromEntries(entries);
+            }
+        }
+        return state;
     }
     catch {
-        return null;
+        return {};
     }
 }
-function writeShownAt(statePath, shownAt) {
+/**
+ * Merge `patch` into the state file and write it back.
+ *
+ * Read-modify-write rather than overwrite, so the over-limit box's `shownAt`
+ * and the threshold notice's `notifiedThresholds` — written by different
+ * surfaces at different moments — cannot erase each other.
+ */
+function updateNagState(statePath, patch) {
     try {
+        const current = readNagState(statePath);
+        const next = {
+            ...current,
+            ...patch,
+            ...(patch.notifiedThresholds
+                ? {
+                    notifiedThresholds: {
+                        ...current.notifiedThresholds,
+                        ...patch.notifiedThresholds,
+                    },
+                }
+                : {}),
+        };
         fs.mkdirSync(path.dirname(statePath), { recursive: true });
-        const payload = { shownAt };
-        fs.writeFileSync(statePath, JSON.stringify(payload));
+        fs.writeFileSync(statePath, JSON.stringify(next));
     }
     catch {
         // best-effort; never break the CLI on cache write failure
     }
 }
-function withinDayWindow(shownAt, nowMs) {
-    return nowMs - shownAt < DAY_MS;
+function readShownAt(statePath) {
+    return readNagState(statePath).shownAt ?? null;
+}
+function writeShownAt(statePath, shownAt) {
+    updateNagState(statePath, { shownAt });
+}
+function withinNagWindow(shownAt, nowMs) {
+    return nowMs - shownAt < OVER_NAG_INTERVAL_MS;
+}
+/**
+ * The over-limit per-turn line (US-036 §2.2). One line, not the old box: it
+ * now repeats up to four times a day, and a multi-line box at that cadence
+ * reads as breakage rather than as a nag. It states the two paused things and
+ * never claims the workspace has stopped working.
+ */
+export function buildOverLine(overEntries, upgradeUrl) {
+    const facts = overEntries
+        .map(([key, entry]) => `${PLAN_LIMIT_DIMENSION_LABELS[key] ?? key} ${entry.used} of ${entry.limit}`)
+        .join(", ");
+    return (`⚠ HQ Starter: ${facts}. New files and new secrets are paused. ` +
+        `Upgrade: ${upgradeUrl}`);
+}
+/** `"{resource}:{band}"` — the persisted key, matching the server's own. */
+function crossingKey(crossing) {
+    return `${crossing.resource}:${crossing.band}`;
+}
+/** Human dimension name, falling back to the wire key for an unknown resource. */
+function dimensionName(resource) {
+    return PLAN_LIMIT_DIMENSION_LABELS[resource] ?? resource;
+}
+/**
+ * One line per crossing.
+ *
+ * The copy states the fact and the exit, nothing else. It deliberately does
+ * not describe consequences that have not shipped: the hard stops arrive with
+ * their own story, and a notice that announces a pause nobody is experiencing
+ * reads as a bug.
+ */
+export function renderThresholdNotice(crossing, upgradeUrl) {
+    const name = dimensionName(crossing.resource);
+    const counts = `${crossing.used} of ${crossing.limit}`;
+    const headline = crossing.band === "over"
+        ? `HQ Starter: you are past your ${name} limit (${counts}).`
+        : `HQ Starter: you have reached 80% of your ${name} (${counts}).`;
+    return `${headline} Upgrade: ${upgradeUrl}`;
 }
-function buildOverBox(overEntries, upgradeUrl) {
-    const title = "⚠ HQ Starter plan limit exceeded";
-    const upgrade = `Upgrade: ${upgradeUrl}`;
-    const resourceLines = overEntries.map(([key, entry]) => `  ${key}: ${entry.used}/${entry.limit}${dimensionSuffix(key)}`);
-    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}`;
+/**
+ * Print every crossing this machine has not already printed for this episode.
+ *
+ * Called from the record path, so a session already running prints on its next
+ * API call. Never throws; a state file it cannot read or write degrades to
+ * per-process dedupe rather than to silence or to repetition.
+ */
+export function emitPlanLimitThresholdNotice(crossings, upgradeUrl, opts = {}) {
+    try {
+        if (!isPlanLimitNagEnabled())
+            return;
+        if (crossings.length === 0)
+            return;
+        const write = opts.write ?? ((s) => process.stderr.write(s));
+        const statePath = opts.statePath ?? defaultStatePath();
+        const stored = readNagState(statePath).notifiedThresholds ?? {};
+        const resolvedUpgradeUrl = upgradeUrl ?? PLAN_LIMIT_UPGRADE_URL;
+        const printed = {};
+        for (const crossing of crossings) {
+            const key = crossingKey(crossing);
+            // A DIFFERENT firstSeenAt is a different episode and prints again; the
+            // same one has already been said.
+            if (stored[key] === crossing.firstSeenAt)
+                continue;
+            if (thresholdsShownThisSession.get(key) === crossing.firstSeenAt)
+                continue;
+            thresholdsShownThisSession.set(key, crossing.firstSeenAt);
+            printed[key] = crossing.firstSeenAt;
+            write(chalk.yellow(renderThresholdNotice(crossing, resolvedUpgradeUrl)) + "\n");
+        }
+        if (Object.keys(printed).length > 0) {
+            updateNagState(statePath, { notifiedThresholds: printed });
+        }
+    }
+    catch {
+        // Never throw from the notice path.
+    }
 }
 /**
  * Emit a plan-limit nag to stderr at command completion.
@@ -227,12 +413,12 @@ export function emitPlanLimitNag(opts = {}) {
                 return;
             const nowMs = now().getTime();
             const prev = readShownAt(statePath);
-            if (prev !== null && withinDayWindow(prev, nowMs))
+            if (prev !== null && withinNagWindow(prev, nowMs))
                 return;
             overShownThisSession = true;
             const overEntries = entries.filter(([, e]) => e.over);
-            const box = buildOverBox(overEntries, resolvedUpgradeUrl);
-            write(chalk.yellow(box) + "\n");
+            const line = buildOverLine(overEntries, resolvedUpgradeUrl);
+            write(chalk.yellow(line) + "\n");
             writeShownAt(statePath, nowMs);
             return;
         }
@@ -243,7 +429,7 @@ export function emitPlanLimitNag(opts = {}) {
         if (worst === null)
             return;
         warningShownThisSession = true;
-        const line = `⚠ HQ Starter plan: ${formatEntryLine(worst.key, worst.entry)}. Upgrade: ${resolvedUpgradeUrl}`;
+        const line = `⚠ HQ Starter: ${formatEntryLine(worst.key, worst.entry)}. Add headroom before you hit the cap: ${resolvedUpgradeUrl}`;
         write(chalk.yellow(line) + "\n");
     }
     catch {
@@ -255,5 +441,6 @@ export function _resetForTests() {
     lastSeen = null;
     warningShownThisSession = false;
     overShownThisSession = false;
+    thresholdsShownThisSession.clear();
 }
 //# sourceMappingURL=plan-limit-nag.js.map

package/package.json

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