@indigoai-us/hq-cli 5.119.10 → 5.119.12

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.119.12] — 2026-09-18
+
+### Fixed
+
+- `hq files cat … --company prs_<person-uid>` now reads the file instead of
+  refusing with "No company found for slug". Reading a DM attachment needs the
+  sender's vault as the scope, and `cat` resolved that value as a company slug
+  of its own, after the same fix landed on the presign path.
+
+## [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/commands/files-browse.js

@@ -43,7 +43,7 @@ import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/clie
 import { VaultClient, grantPathToPrefix, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, buildVaultConfig, } from "../utils/cognito-session.js";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
-import { getCompanyUid, looksLikeCompanyUid, vaultApiFetch, } from "../utils/vault-api.js";
+import { getCompanyUid, looksLikeCompanyUid, looksLikePersonVaultUid, vaultApiFetch, } from "../utils/vault-api.js";
 import { resolveCanonicalPersonUid } from "./cloud.js";
 // ── Pure helpers ────────────────────────────────────────────────────────────
 /**
@@ -306,18 +306,37 @@ export async function runCat(input) {
     }
     else {
         const slug = input.companySlug ?? parseCompanySlugFromPath(key);
-        const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-        if (!entity) {
-            throw new Error(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
+        if (looksLikePersonVaultUid(slug)) {
+            // A `prs_` scope names a PERSON'S vault, which is where a DM attachment
+            // lives (`chat/attachments/dm/<uidA>--<uidB>/…`). There is no company
+            // entity to look up — `findInMyNamespace("company", …)` can only ever
+            // find a company, so it refuses the one scope the server accepts
+            // (hq-pro #3571 authorizes either member of the pair; hq-cli #644 made
+            // the presign path carry the ref). Go straight to the presign path and
+            // let the vault API's per-key gate decide.
+            //
+            // The key is already bucket-relative: a person vault has no
+            // `companies/<slug>/` anchor to strip. `Bucket` is inert on this path —
+            // the browse-vend company client presigns by companyUid + key and never
+            // reads it — so the scope ref is carried through for error messages.
+            bucket = slug;
+            s3Key = key;
+            s3 = requireCompanyClient(input.companyClient)({ companyUid: slug });
         }
-        if (!entity.bucketName) {
-            throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+        else {
+            const entity = await vaultClient.entity.findInMyNamespace("company", slug);
+            if (!entity) {
+                throw new Error(`No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`);
+            }
+            if (!entity.bucketName) {
+                throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+            }
+            bucket = entity.bucketName;
+            // Translate the anchored CLI key into the company-relative bucket key.
+            s3Key = toBucketRelative(key, slug);
+            // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
+            s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
         }
-        bucket = entity.bucketName;
-        // Translate the anchored CLI key into the company-relative bucket key.
-        s3Key = toBucketRelative(key, slug);
-        // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
-        s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
     }
     // HQ-CLI-5: when writing to --out, create the parent directory BEFORE issuing
     // the presigned GET, so no synchronous filesystem call sits between receiving

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