@indigoai-us/hq-cli 5.119.8 → 5.119.9

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [5.119.9] — 2026-09-17
+
+### Added
+
+- The CLI now prints a one-time notice when your workspace crosses a plan
+  threshold — reaching 80% of a Starter limit, or going past one. The server
+  decides when a threshold has been crossed and sends it with the response, so
+  a session you already have open surfaces the notice on its next API call
+  rather than on its next launch. Each `{resource}:{band}` is printed exactly
+  once per episode, remembered in `~/.hq/plan-limit-nag.json`; a dimension that
+  drops back under the threshold and climbs again is announced again.
+  `HQ_NO_PLAN_LIMIT_NAG=1` silences it along with the other plan-limit lines.
+
+### Fixed
+
+- A file attached to a DM is now visible to a bot reading its mail. `hq dm
+  inbox`, `hq dm thread`, `hq dm channel` and `hq agent inbox` print each
+  attached file's name, type and vault path under the message body; the JSON
+  forms carry an `attachments[]` field. Previously only the body text was
+  rendered, so an agent sent a screenshot answered "no image came through".
+
 ## [5.119.8] — 2026-09-17
 
 ### Fixed
@@ -44,6 +65,15 @@
   on Starter: 1", and tells you to "disconnect integrations until you are at 1
   or fewer"; the per-turn line reads "over its 1-integration limit". Nothing in
   the CLI says Starter has no integrations any more.
+- Plan-limit messages now say what is actually happening. Going over a Starter
+  limit never stopped the workspace, and the copy no longer implies it did:
+  the words "locked" and "read-only" are gone from every line `hq` prints, and
+  the notice states the two things that do pause — adding new files and adding
+  new secrets — while everything else keeps working. A test scans every
+  rendered string for both words so the copy cannot drift back.
+- The over-limit per-turn nag is one line instead of a box, and it repeats at
+  most once every 6 hours (was once a day). `HQ_NO_PLAN_LIMIT_NAG=1` still
+  silences it.
 
 ## [5.119.4] — 2026-09-17
 

package/dist/commands/agent-inbox.js

@@ -52,6 +52,12 @@ export function registerAgentInboxCommand(agent) {
             console.log(`${chalk.bold(r.id)}${state}  ${r.channel ?? "?"}  from ${r.from}${r.fromUid ? ` <${r.fromUid}>` : ""}  ${r.at ?? ""}`);
             if (r.text)
                 console.log(`  ${r.text.replace(/\n/g, "\n  ")}`);
+            for (const f of r.attachments ?? []) {
+                const label = f.name ?? f.vaultPath.split("/").pop() ?? "file";
+                const type = f.contentType ? ` (${f.contentType})` : "";
+                console.log(`  ${chalk.dim("[file]")} ${label}${type}`);
+                console.log(`    ${chalk.dim(`vault: ${f.vaultPath}`)}`);
+            }
         }
         if (!opts.all)
             console.log(chalk.dim(`\nReply with hq dm <uid> "…", then: hq agent inbox done <id>`));

package/dist/commands/dm.d.ts

@@ -201,6 +201,9 @@ export interface DmInboxEvent {
     details?: string;
     prompt?: string;
     acknowledgedAt?: string;
+    /** US-007 file references. Singular `attachment` is the legacy form. */
+    attachments?: DmAttachment[];
+    attachment?: DmAttachment;
 }
 /** One message in a 1:1 thread as returned by GET /v1/notify/thread. */
 export interface DmThreadMessage {
@@ -213,6 +216,8 @@ export interface DmThreadMessage {
     direction: "in" | "out";
     details?: string;
     prompt?: string;
+    attachments?: DmAttachment[];
+    attachment?: DmAttachment;
 }
 /** One channel/group message from GET /v1/notify/channels/{id}/messages. */
 export interface ChannelMessageItem {
@@ -223,7 +228,33 @@ export interface ChannelMessageItem {
     fromDisplayName?: string;
     body: string;
     createdAt: string;
+    attachments?: DmAttachment[];
+    attachment?: DmAttachment;
 }
+/**
+ * One file attached to a DM (US-007 `attachments[]` on the read endpoints). The
+ * server returns a vault path, not bytes: a reader fetches it with
+ * a presigned read of that key.
+ */
+export interface DmAttachment {
+    vaultPath: string;
+    name?: string;
+    sizeBytes?: number;
+    contentType?: string;
+    kind?: string;
+    companyUid?: string;
+}
+/**
+ * Render the attachment lines for one message. An agent reading its DMs through
+ * the CLI only ever sees this text, so the vault path AND the command that
+ * fetches it both have to be on screen — a bare "[image]" marker is why a bot
+ * answers "no image came through". Returns "" when there is nothing attached.
+ * Pure → unit-testable.
+ */
+export declare function formatAttachments(m: {
+    attachments?: DmAttachment[];
+    attachment?: DmAttachment;
+}, indent?: string): string;
 /**
  * Human label for a message sender — display name, else email, else uid. Pure →
  * unit-testable.

package/dist/commands/dm.js

@@ -693,6 +693,27 @@ async function runDmRequests() {
         process.exit(1);
     }
 }
+/**
+ * Render the attachment lines for one message. An agent reading its DMs through
+ * the CLI only ever sees this text, so the vault path AND the command that
+ * fetches it both have to be on screen — a bare "[image]" marker is why a bot
+ * answers "no image came through". Returns "" when there is nothing attached.
+ * Pure → unit-testable.
+ */
+export function formatAttachments(m, indent = "    ") {
+    const files = (m.attachments?.length ? m.attachments : m.attachment ? [m.attachment] : [])
+        .filter((f) => Boolean(f?.vaultPath));
+    if (files.length === 0)
+        return "";
+    return files
+        .map((f) => {
+        const label = f.name?.trim() || f.vaultPath.split("/").pop() || "file";
+        const type = f.contentType ? ` ${chalk.dim(f.contentType)}` : "";
+        const company = f.companyUid ? chalk.dim(` company=${f.companyUid}`) : "";
+        return `\n${indent}${chalk.dim("[file]")} ${label}${type}\n${indent}   ${chalk.dim(`vault: ${f.vaultPath}`)}${company}`;
+    })
+        .join("");
+}
 /**
  * Human label for a message sender — display name, else email, else uid. Pure →
  * unit-testable.
@@ -773,20 +794,20 @@ export function formatInboxEvent(e, nowMs) {
     const when = chalk.dim(formatRelativeTime(e.createdAt, nowMs));
     const who = chalk.bold(senderLabel(e));
     const email = e.fromEmail && e.fromDisplayName ? chalk.dim(` <${e.fromEmail}>`) : "";
-    return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}`;
+    return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}${formatAttachments(e)}`;
 }
 /** Render one 1:1 thread line, tagged by direction. */
 export function formatThreadMessage(m, nowMs) {
     const arrow = m.direction === "out" ? chalk.dim("→") : chalk.cyan("←");
     const who = m.direction === "out" ? "you" : senderLabel(m);
     const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-    return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}`;
+    return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}${formatAttachments(m)}`;
 }
 /** Render one channel/group message line. */
 export function formatChannelMessage(m, nowMs) {
     const who = chalk.bold(senderLabel(m));
     const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-    return `${who} ${when}\n    ${firstLine(m.body)}`;
+    return `${who} ${when}\n    ${firstLine(m.body)}${formatAttachments(m)}`;
 }
 /** POST /v1/notify/inbox/ack — idempotently mark messages read. */
 async function ackEvents(token, eventIds) {

package/dist/commands/whoami.d.ts

@@ -21,9 +21,9 @@ export interface WhoamiDisplayIdentity {
  */
 export declare function resolveWhoamiIdentity(identity: WhoamiTokenIdentity): WhoamiDisplayIdentity;
 /**
- * Human rendering of the plan state: the full WORKSPACE LOCKED block when the
- * workspace is locked, the one-line `Plan: Starter — …` orientation when it is
- * Starter and healthy, and nothing at all otherwise.
+ * Human rendering of the plan state: the full over-limit block when the
+ * workspace is over its Starter limits, the one-line `Plan: Starter — …`
+ * orientation when it is Starter and healthy, and nothing at all otherwise.
  */
 export declare function renderWhoamiPlanBlock(status: PlanLockStatus): string | null;
 export declare function registerWhoamiCommand(program: Command): void;

package/dist/commands/whoami.js

@@ -5,7 +5,7 @@ import chalk from 'chalk';
 import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
 import { ensureCognitoToken, loadMachineCachedTokens, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
-import { colorizePlanLockNotice, fetchPlanLockStatus, renderPlanLine, renderPlanLockNotice, } from "../lib/billing/plan-lock.js";
+import { colorizePlanLimitNotice, fetchPlanLockStatus, renderPlanLine, renderPlanLimitNotice, } from "../lib/billing/plan-lock.js";
 /**
  * Resolves the person represented by an ID token without pairing a delegated
  * email with the token subject of the delegating machine.
@@ -69,13 +69,13 @@ async function readPlanLock(company) {
     }
 }
 /**
- * Human rendering of the plan state: the full WORKSPACE LOCKED block when the
- * workspace is locked, the one-line `Plan: Starter — …` orientation when it is
- * Starter and healthy, and nothing at all otherwise.
+ * Human rendering of the plan state: the full over-limit block when the
+ * workspace is over its Starter limits, the one-line `Plan: Starter — …`
+ * orientation when it is Starter and healthy, and nothing at all otherwise.
  */
 export function renderWhoamiPlanBlock(status) {
     if (status.lock.locked) {
-        return colorizePlanLockNotice(renderPlanLockNotice(status));
+        return colorizePlanLimitNotice(renderPlanLimitNotice(status));
     }
     return renderPlanLine(status);
 }

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -21,15 +21,35 @@ export declare function markInboxDone(paths: Pick<AgentKitPaths, "inboxDir">, id
 /** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
 export declare function readMirroredInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
 export declare function pendingInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
-/** Compact view for bots: who, when, which channel, and the text. */
+/** One file reference carried on an inbox item (US-007 chat attachments). */
+export interface InboxAttachment {
+    vaultPath: string;
+    name?: string;
+    contentType?: string;
+    sizeBytes?: number;
+    companyUid?: string;
+}
+/**
+ * The file references on an inbox entry, plural `attachments[]` first and the
+ * legacy singular `attachment` as a fallback. Entries without a `vaultPath` are
+ * dropped: a reference the bot cannot fetch is worse than none. Pure.
+ */
+export declare function inboxEntryAttachments(e: MirroredInboxEntry): InboxAttachment[];
+/**
+ * Compact view for bots: who, when, which channel, the text, and any attached
+ * files. The attachments belong here because this summary IS the message as far
+ * as a bot is concerned — omitting them made an agent answer "no image came
+ * through" for a DM that carried a screenshot.
+ */
 export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean): {
+    done: boolean;
+    attachments?: InboxAttachment[] | undefined;
     id: string;
     channel: string | undefined;
     from: string;
     fromUid: string | undefined;
     at: string | undefined;
     text: string | undefined;
-    done: boolean;
 };
 /**
  * The agent's inbox as the bot should see it: the kit's local mirror merged

package/dist/lib/agent-kit/inbox-state.js

@@ -65,7 +65,44 @@ export function pendingInbox(paths) {
     const done = readDoneIds(paths);
     return readMirroredInbox(paths).filter((e) => !done.has(e.id));
 }
-/** Compact view for bots: who, when, which channel, and the text. */
+/**
+ * The file references on an inbox entry, plural `attachments[]` first and the
+ * legacy singular `attachment` as a fallback. Entries without a `vaultPath` are
+ * dropped: a reference the bot cannot fetch is worse than none. Pure.
+ */
+export function inboxEntryAttachments(e) {
+    const raw = Array.isArray(e.attachments)
+        ? e.attachments
+        : e.attachment
+            ? [e.attachment]
+            : [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const rec = entry;
+        const vaultPath = typeof rec.vaultPath === "string" ? rec.vaultPath.trim() : "";
+        if (!vaultPath)
+            continue;
+        const str = (k) => typeof rec[k] === "string" && rec[k].trim()
+            ? rec[k].trim()
+            : undefined;
+        out.push({
+            vaultPath,
+            ...(str("name") ? { name: str("name") } : {}),
+            ...(str("contentType") ? { contentType: str("contentType") } : {}),
+            ...(typeof rec.sizeBytes === "number" ? { sizeBytes: rec.sizeBytes } : {}),
+            ...(str("companyUid") ? { companyUid: str("companyUid") } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Compact view for bots: who, when, which channel, the text, and any attached
+ * files. The attachments belong here because this summary IS the message as far
+ * as a bot is concerned — omitting them made an agent answer "no image came
+ * through" for a DM that carried a screenshot.
+ */
 export function summarizeInboxEntry(e, done) {
     const pick = (...keys) => {
         for (const k of keys)
@@ -73,6 +110,7 @@ export function summarizeInboxEntry(e, done) {
                 return e[k];
         return undefined;
     };
+    const attachments = inboxEntryAttachments(e);
     return {
         id: e.id,
         channel: pick("channel"),
@@ -80,6 +118,7 @@ export function summarizeInboxEntry(e, done) {
         fromUid: pick("fromPersonUid"),
         at: pick("receivedAt", "createdAt", "mirroredAt"),
         text: pick("text", "body"),
+        ...(attachments.length ? { attachments } : {}),
         done,
     };
 }

package/dist/lib/billing/plan-lock.d.ts

@@ -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
@@ -18,7 +23,7 @@
  */
 /**
  * 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.
@@ -106,29 +111,39 @@ export declare function selectMemberUsage(body: unknown): PlanLockMembers | null
 export declare function fetchPlanLockStatus(token: string, companyRef: string, opts?: {
     timeoutMs?: number;
 }): Promise<PlanLockStatus | null>;
-/** Why the workspace locked, one clause per reason. */
+/** Why the workspace is over, one clause per reason. */
 export declare function reasonLabel(reason: PlanLockReason): string;
 /**
- * The full WORKSPACE LOCKED block: why it locked, where the workspace stands
+ * 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 declare const HARD_STOP_SENTENCE: string;
+/**
+ * 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 declare function renderPlanLockNotice(status: PlanLockStatus): string;
+export declare function renderPlanLimitNotice(status: PlanLockStatus): string;
 /**
- * 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 declare function renderPlanLockLine(status: PlanLockStatus): string;
+export declare function renderPlanLimitLine(status: PlanLockStatus): string;
 /**
  * The `Plan: …` orientation line. Starter only: a paid or enterprise
  * workspace — and an UNKNOWN plan — gets no line at all.
  */
 export declare function renderPlanLine(status: PlanLockStatus): string | null;
-/** Colourised block for interactive output. */
-export declare function colorizePlanLockNotice(notice: string): string;
+/**
+ * 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 declare function colorizePlanLimitNotice(notice: string): string;
 //# sourceMappingURL=plan-lock.d.ts.map

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.9",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {