@indigoai-us/hq-cli 5.119.10 → 5.119.11

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.119.11] — 2026-09-18
+
+### Added
+
+- On a personal account, My Telemetry is part of the paid Individual plan
+  ($50/mo). When the server withholds it, the CLI now prints a short notice
+  naming the plan and where to upgrade, instead of the raw refusal. Company
+  plans are unaffected, and the notice has nothing to do with the plan-limit
+  nags — it is a plan fact, printed once, where it happened.
+
+### Fixed
+
+- `hq files … --company prs_<person-uid>` now reaches that person's vault
+  instead of failing with "Company slug ... was not found". This is how a DM
+  recipient reads a file attached to a message: the attachment lives in the
+  sender's personal vault, so naming the sender is the only scope that works.
+
 ## [5.119.10] — 2026-09-18
 
 ### Added

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

@@ -83,6 +83,28 @@ export declare function recordPlanLimitStatus(body: unknown, opts?: {
  * never claims the workspace has stopped working.
  */
 export declare function buildOverLine(overEntries: Array<[string, PlanLimitEntry]>, upgradeUrl: string): string;
+/**
+ * My Telemetry is an Individual-plan feature on a personal scope (owner
+ * decision 9 / us-044-individual-plan-design.md §11). When hq-pro refuses it,
+ * the CLI prints this notice INSTEAD of telemetry output.
+ *
+ * It lives beside the nag copy so plan wording stays in one file, but it is
+ * NOT part of the nag model: no persistence, no throttle, no episode state. It
+ * is rendered once, on the spot, by whoever received the refusal. The refusal
+ * is a plan fact, so it neither counts toward the nag bands nor is silenced by
+ * the nag cadence.
+ *
+ * Copy names the plan and its price only — no Outposts, no bot pricing (owner
+ * decisions 10 and 11).
+ */
+export declare const INDIVIDUAL_PLAN_NAME = "Individual";
+export declare const INDIVIDUAL_PRICE_LABEL = "$50/mo";
+/**
+ * The notice a personal feature refusal prints. `upgradeUrl` is the server's
+ * own checkout target; an older hq-pro sends none, and the line then names the
+ * plan without a link rather than inventing one.
+ */
+export declare function renderPersonalPlanFeatureNotice(feature: string, upgradeUrl?: string | null): string;
 /**
  * One line per crossing.
  *

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

@@ -326,6 +326,42 @@ export function buildOverLine(overEntries, upgradeUrl) {
     return (`⚠ HQ Starter: ${facts}. New files and new secrets are paused. ` +
         `Upgrade: ${upgradeUrl}`);
 }
+// ---------------------------------------------------------------------------
+// Individual-plan feature notice (US-054)
+// ---------------------------------------------------------------------------
+/**
+ * My Telemetry is an Individual-plan feature on a personal scope (owner
+ * decision 9 / us-044-individual-plan-design.md §11). When hq-pro refuses it,
+ * the CLI prints this notice INSTEAD of telemetry output.
+ *
+ * It lives beside the nag copy so plan wording stays in one file, but it is
+ * NOT part of the nag model: no persistence, no throttle, no episode state. It
+ * is rendered once, on the spot, by whoever received the refusal. The refusal
+ * is a plan fact, so it neither counts toward the nag bands nor is silenced by
+ * the nag cadence.
+ *
+ * Copy names the plan and its price only — no Outposts, no bot pricing (owner
+ * decisions 10 and 11).
+ */
+export const INDIVIDUAL_PLAN_NAME = "Individual";
+export const INDIVIDUAL_PRICE_LABEL = "$50/mo";
+/** Human names for the features a personal scope can be refused. */
+const PERSONAL_FEATURE_LABELS = {
+    telemetry: "My Telemetry",
+};
+/**
+ * The notice a personal feature refusal prints. `upgradeUrl` is the server's
+ * own checkout target; an older hq-pro sends none, and the line then names the
+ * plan without a link rather than inventing one.
+ */
+export function renderPersonalPlanFeatureNotice(feature, upgradeUrl) {
+    const label = PERSONAL_FEATURE_LABELS[feature] ?? feature;
+    const headline = `${label} is included with the HQ ${INDIVIDUAL_PLAN_NAME} plan (${INDIVIDUAL_PRICE_LABEL}).`;
+    const action = typeof upgradeUrl === "string" && upgradeUrl.trim().length > 0
+        ? `Upgrade: ${upgradeUrl.trim()}`
+        : "Upgrade in your HQ billing settings.";
+    return `${headline} Your personal account is on the free tier. ${action}`;
+}
 /** `"{resource}:{band}"` — the persisted key, matching the server's own. */
 function crossingKey(crossing) {
     return `${crossing.resource}:${crossing.band}`;

package/dist/utils/plan-gate-error.d.ts

@@ -1,11 +1,15 @@
+export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED"
 /**
- * A deliberate subscription denial returned by hq-pro. Keeping its structured
- * fields on a typed error lets the CLI boundary render one safe, consistent
- * message instead of every command parsing and printing a server response.
+ * US-054: a PERSONAL scope asked for a feature the paid Individual plan
+ * includes and the free tier does not. A different plan, a different price
+ * and a different remedy from the company codes above, so it is its own
+ * code rather than a reuse of `PLAN_REQUIRED` with company copy.
  */
-export type PlanGateCode = "PLAN_LIMIT_EXCEEDED" | "PLAN_REQUIRED";
+ | "PERSONAL_PLAN_REQUIRED";
 export interface PlanGateDetails {
     resource?: string;
+    /** The refused feature, on a `PERSONAL_PLAN_REQUIRED` denial. */
+    feature?: string;
     used?: number;
     limit?: number;
     upgradeUrl?: string;

package/dist/utils/plan-gate-error.js

@@ -1,3 +1,9 @@
+/**
+ * A deliberate subscription denial returned by hq-pro. Keeping its structured
+ * fields on a typed error lets the CLI boundary render one safe, consistent
+ * message instead of every command parsing and printing a server response.
+ */
+import { renderPersonalPlanFeatureNotice } from "../lib/plan-limit-nag.js";
 const TEAM_UPGRADE_HINT = "Run `hq billing upgrade` to move to HQ Workforce.";
 export class PlanGateError extends Error {
     code;
@@ -6,7 +12,11 @@ export class PlanGateError extends Error {
         // Commands with their own expected-error boundary commonly print
         // `err.message`. Keeping the friendly copy here means those boundaries
         // retain the same plan-gate voice as main.ts without per-command handling.
-        super([formatPlanGateDetails(code, details), TEAM_UPGRADE_HINT].join("\n"));
+        // The HQ Workforce hint is company advice; a personal denial ends at its
+        // own notice, which already names the Individual plan and its checkout.
+        super(code === "PERSONAL_PLAN_REQUIRED"
+            ? formatPlanGateDetails(code, details)
+            : [formatPlanGateDetails(code, details), TEAM_UPGRADE_HINT].join("\n"));
         this.code = code;
         this.details = details;
         this.name = "PlanGateError";
@@ -31,6 +41,12 @@ function formatPlanGateDetails(code, details) {
             existingResourcesNote,
         ].join("\n");
     }
+    // A personal scope is not a workspace: it has no members to trim, no $500
+    // tier to buy, and nothing of its own is paused. One line, the plan's own
+    // copy, and no company remedy.
+    if (code === "PERSONAL_PLAN_REQUIRED") {
+        return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", details.upgradeUrl ?? null);
+    }
     const upgrade = typeof details.upgradeUrl === "string"
         ? `Upgrade to HQ Workforce ($500/mo) to remove limits: ${details.upgradeUrl}`
         : "Upgrade to HQ Workforce ($500/mo) to remove limits.";
@@ -41,6 +57,9 @@ function formatPlanGateDetails(code, details) {
     ].join("\n");
 }
 export function formatPlanGateError(err) {
+    if (err.code === "PERSONAL_PLAN_REQUIRED") {
+        return formatPlanGateDetails(err.code, err.details);
+    }
     return [
         formatPlanGateDetails(err.code, err.details),
         TEAM_UPGRADE_HINT,
@@ -80,6 +99,22 @@ export function planGateErrorFromPayload(status, body, companyUid) {
     if (status !== 402 || !body || typeof body !== "object")
         return null;
     const payload = body;
+    // US-054: the personal feature denial. hq-pro identifies it with
+    // `error: "plan_feature_unavailable"` plus `scope: "personal"`; both the
+    // `scope` and `requiredPlan` fields are OPTIONAL on the wire, so an hq-pro
+    // that predates US-054 sends a company-shaped denial and keeps falling
+    // through to the company path below (defensive consumer).
+    if (payload.error === "plan_feature_unavailable" &&
+        payload.scope === "personal") {
+        return new PlanGateError("PERSONAL_PLAN_REQUIRED", {
+            ...(typeof payload.feature === "string"
+                ? { feature: payload.feature }
+                : {}),
+            ...(typeof payload.upgradeUrl === "string"
+                ? { upgradeUrl: payload.upgradeUrl }
+                : {}),
+        });
+    }
     if (payload.code !== "PLAN_LIMIT_EXCEEDED" && payload.code !== "PLAN_REQUIRED") {
         return null;
     }

package/dist/utils/vault-api.d.ts

@@ -59,6 +59,7 @@ export declare function vaultApiFetchPublic(opts: {
     query?: Record<string, string>;
 }): Promise<Response>;
 export declare function looksLikeCompanyUid(ref: string): boolean;
+export declare function looksLikePersonVaultUid(ref: string): boolean;
 export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
 export declare function resolveCallerPersonUid(token: string, baseUrl?: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {

package/dist/utils/vault-api.js

@@ -285,6 +285,24 @@ const COMPANY_UID_PREFIX = 'cmp_';
 export function looksLikeCompanyUid(ref) {
     return ref.startsWith(COMPANY_UID_PREFIX);
 }
+/**
+ * A `--company` value beginning with `prs_` names a PERSON'S vault, not a
+ * company. It is the only way to reach a DM attachment: the file lives in the
+ * SENDER's personal vault under
+ * `chat/attachments/dm/<uidA>--<uidB>/…`, and the vault API authorizes either
+ * member of that pair to `get` it (hq-pro #3571). The recipient has no
+ * personal vault of their own (so `--personal` cannot work) and the key is not
+ * in any company bucket (so a slug 404s on the object), which left the read
+ * with no expressible scope at all.
+ *
+ * Routed straight through as the scope uid: person entities have no slug
+ * namespace, so there is nothing to resolve, and the server's own per-key gate
+ * — not the CLI — decides whether the caller may read it.
+ */
+const PERSON_VAULT_UID_PREFIX = 'prs_';
+export function looksLikePersonVaultUid(ref) {
+    return ref.startsWith(PERSON_VAULT_UID_PREFIX);
+}
 // A 401 from ANY vault resolution call means the caller's HQ session is
 // expired or missing — an expected auth state fixed by `hq login`, not a
 // code defect. Raise a typed AuthError so the top-level handler prints an
@@ -351,6 +369,12 @@ async function resolveCompanyUid(token, ref) {
     if (looksLikeCompanyUid(ref)) {
         return resolveCompanyByUid(token, ref);
     }
+    // A `prs_` ref names a person's vault (DM attachments). There is no slug to
+    // resolve and no company lookup that could succeed; pass it through as the
+    // scope and let the vault API's per-key authorization answer.
+    if (looksLikePersonVaultUid(ref)) {
+        return ref;
+    }
     // PRIMARY PATH — caller-scoped slug resolution. Resolves the slug to the
     // caller's OWN company (unique within their namespace by the invariant
     // above), making a stranger's same-slug company invisible.

package/package.json

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