@indigoai-us/hq-cli 5.18.3 → 5.20.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.20.0] — 2026-05-21
+
+### Added
+
+- **`hq sync {push,pull,now} --all --no-personal`** — skip the
+  canonical-person leg of the `--all` fanout (companies-only sync).
+  Mirrors the upstream `hq-sync-runner --skip-personal` flag added in
+  `@indigoai-us/hq-cloud@5.25.0`. Wired so the AppBar HQ Sync menubar
+  can drop personal sync via a toggle, and so CLI users can opt out
+  one-off. Plumbed through `pullAll` / `pushAll` / `runNowAll` via a
+  new `skipPersonal` option; outside `--all` mode the flag is a no-op.
+- Bumps `@indigoai-us/hq-cloud` to `~5.25.0` (currency-gated personal-
+  vault default exclusions + skip-personal CLI/env surface).
+
 ## [5.18.3] — 2026-05-21
 
 ### Fixed

package/dist/commands/cloud.d.ts

@@ -77,6 +77,17 @@ export interface PullAllOptions {
      * legacy behavior for this run via `--mode-all`.
      */
     modeAllOverride?: boolean;
+    /**
+     * When `true`, skip the canonical-person-entity leg entirely — the
+     * fanout only visits the caller's company memberships. Mirrors the
+     * `--skip-personal` flag and `HQ_SYNC_SKIP_PERSONAL` env var that
+     * `@indigoai-us/hq-cloud`'s `sync-runner` exposes in `--companies`
+     * mode (see hq-cloud 5.25.0 `resolveSkipPersonal`). Surfaced on the
+     * CLI as `hq sync pull --all --no-personal` so the AppBar HQ Sync
+     * menubar toggle (and CLI users opting out one-off) can drop the
+     * personal vault from the run without touching the rest of the plan.
+     */
+    skipPersonal?: boolean;
 }
 export interface PullAllRow {
     slug: string;
@@ -110,6 +121,13 @@ export interface PushAllOptions {
     hqRoot: string;
     onConflict?: ConflictStrategy;
     message?: string;
+    /**
+     * When `true`, skip the canonical-person-entity leg entirely — the
+     * fanout only visits the caller's company memberships. Symmetric with
+     * `PullAllOptions.skipPersonal`; surfaced on the CLI as
+     * `hq sync push --all --no-personal`.
+     */
+    skipPersonal?: boolean;
 }
 export interface PushAllRow {
     slug: string;
@@ -153,6 +171,23 @@ export declare function pushAll(options: PushAllOptions, deps: PushAllDeps): Pro
  * no person entity (typically means they haven't run `hq onboard`).
  */
 export declare function resolveCanonicalPersonUid(vaultClient: PullAllVaultClient): Promise<string>;
+/**
+ * Refuse `hq sync push --personal <path>` — the combination silently
+ * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
+ * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
+ * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
+ * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
+ * objects to a personal vault before being killed. Cleanup required a
+ * hand-rolled S3 sweep. Closes hq-cli#25.
+ *
+ * Refusal — not silent filtering — is intentional: explicit is better than
+ * implicit guesswork, and the legitimate "I want to push a subset of my
+ * personal vault" use case has a clean workaround (drop `--personal`, the
+ * subset upload targets the active company via standard semantics).
+ */
+export declare function assertNoPersonalPositionalPaths(opts: {
+    personal?: boolean;
+}, paths: string[] | undefined): void;
 /**
  * Refuse ambiguous selector combinations. `--all`, `--personal`, and
  * `--company` are mutually exclusive — at most one may be set per

package/dist/commands/cloud.js

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4672d875-1dc8-56a2-bef1-49c7f4ff6c76")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bdaf154f-b17d-5482-9e4d-feaebe606a1b")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -60,7 +60,7 @@ export async function pullAll(options, deps) {
             },
         });
     }
-    const personal = pickCanonicalPerson(persons);
+    const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
     if (personal) {
         plan.push({
             slug: "personal",
@@ -176,7 +176,7 @@ export async function pushAll(options, deps) {
             },
         });
     }
-    const personal = pickCanonicalPerson(persons);
+    const personal = options.skipPersonal ? null : pickCanonicalPerson(persons);
     if (personal) {
         plan.push({
             slug: "personal",
@@ -234,6 +234,30 @@ export async function resolveCanonicalPersonUid(vaultClient) {
     }
     return pick.uid;
 }
+/**
+ * Refuse `hq sync push --personal <path>` — the combination silently
+ * bypasses `PERSONAL_VAULT_EXCLUDED_TOP_LEVEL` (which is only applied by
+ * `computePersonalVaultPaths`), risking cross-scope upload of `companies/`,
+ * `repos/`, `workspace/`, or `.git/` content to the personal vault. Real
+ * incident (2026-05-21): a single command uploaded 196 `companies/{slug}/**`
+ * objects to a personal vault before being killed. Cleanup required a
+ * hand-rolled S3 sweep. Closes hq-cli#25.
+ *
+ * Refusal — not silent filtering — is intentional: explicit is better than
+ * implicit guesswork, and the legitimate "I want to push a subset of my
+ * personal vault" use case has a clean workaround (drop `--personal`, the
+ * subset upload targets the active company via standard semantics).
+ */
+export function assertNoPersonalPositionalPaths(opts, paths) {
+    if (opts.personal && paths && paths.length > 0) {
+        throw new Error("`--personal` cannot be combined with explicit [paths]: " +
+            "positional paths bypass the PERSONAL_VAULT_EXCLUDED_TOP_LEVEL " +
+            "guard (skips .git/, companies/, repos/, workspace/), risking " +
+            "cross-scope upload of company data to the personal vault. " +
+            "Use bare `--personal` to push the whole personal scope, OR " +
+            "drop `--personal` to push specific paths to the active company.");
+    }
+}
 /**
  * Refuse ambiguous selector combinations. `--all`, `--personal`, and
  * `--company` are mutually exclusive — at most one may be set per
@@ -330,6 +354,12 @@ export function registerCloudCommands(program) {
         "every top-level entry under <hq-root> minus the excluded set " +
         "(.git, companies, repos, workspace) — same scope as `--all`'s " +
         "personal slot. Mutually exclusive with --company and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only push to the caller's company memberships. Mirrors the " +
+        "upstream `hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0); " +
+        "wired so the AppBar HQ Sync menubar can drop personal sync via " +
+        "a toggle, and so CLI users can opt out one-off. Ignored outside " +
+        "`--all`.")
         .action(async (paths, options) => {
         try {
             assertSingleSelector(options, "push");
@@ -352,7 +382,13 @@ export function registerCloudCommands(program) {
                     "target instead.");
                 process.exit(1);
             }
-            await runPushAll(options.hqRoot, options.message, options.onConflict);
+            // `options.personal === false` happens when the user passed
+            // `--no-personal` (Commander's auto-negation of the `--personal`
+            // selector). In `--all` mode that means "skip the personal leg of
+            // the fanout" — wired through to `pushAll.skipPersonal`. Outside
+            // `--all` the flag has no effect (logged above as part of the
+            // option's help text).
+            await runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false);
             return;
         }
         const jsonMode = options.json === true;
@@ -372,6 +408,8 @@ export function registerCloudCommands(program) {
                     "Cognito session, while --creds-from-stdin expects the caller " +
                     "to have already resolved entity + credentials. Pick one.");
             }
+            // Closes hq-cli#25 — see `assertNoPersonalPositionalPaths` doc-block.
+            assertNoPersonalPositionalPaths(options, paths);
             log(chalk.bold("\nHQ Sync — Push"));
             log(`  HQ root:  ${options.hqRoot}`);
             // Resolve credentials. Two paths:
@@ -505,6 +543,10 @@ export function registerCloudCommands(program) {
         "(no companies/<slug>/ prefix). Resolves the person UID automatically " +
         "from the cached Cognito session. Mutually exclusive with --company " +
         "and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of the fanout — " +
+        "only pull the caller's company memberships. Mirrors the upstream " +
+        "`hq-sync-runner --skip-personal` flag (hq-cloud 5.25.0). Ignored " +
+        "outside `--all`.")
         .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
         "Has no effect today (default narrow-hint level is 'hint'); " +
         "wired so future hq-core-staging releases can flip the default to " +
@@ -518,7 +560,10 @@ export function registerCloudCommands(program) {
             process.exit(1);
         }
         if (options.all) {
-            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true);
+            // `options.personal === false` is Commander's auto-negation of
+            // `--personal`; in `--all` mode that means "drop the personal
+            // leg from the fanout" (see `--no-personal` option above).
+            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false);
             return;
         }
         if (options.personal) {
@@ -641,6 +686,10 @@ export function registerCloudCommands(program) {
         "--personal.")
         .option("--personal", "Sync the caller's canonical personal vault bidirectionally. " +
         "Mutually exclusive with --company and --all.")
+        .option("--no-personal", "In `--all` mode, skip the canonical-person leg of both the push " +
+        "and pull fanouts — only sync the caller's company memberships. " +
+        "Mirrors the upstream `hq-sync-runner --skip-personal` flag " +
+        "(hq-cloud 5.25.0). Ignored outside `--all`.")
         .option("--mode-all", "US-011: opt out of the strict narrow-hint refusal for this run. " +
         "No-op today; wired so future hq-core-staging releases can flip " +
         "the default narrow-hint level to 'strict'.")
@@ -648,7 +697,11 @@ export function registerCloudCommands(program) {
         try {
             assertSingleSelector(options, "now");
             if (options.all) {
-                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true);
+                // `options.personal === false` is Commander's auto-negation
+                // of `--personal`; in `--all` mode that means "drop the
+                // personal leg from both legs of the bidirectional fanout"
+                // (see `--no-personal` option above).
+                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false);
                 return;
             }
             await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true);
@@ -659,10 +712,14 @@ export function registerCloudCommands(program) {
         }
     });
 }
-async function runPullAll(hqRoot, onConflict, modeAllOverride) {
+async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Pull (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     let result;
     try {
         const accessToken = await ensureCognitoToken();
@@ -686,6 +743,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride) {
             ...(onConflict ? { onConflict } : {}),
             narrowHintLevel: resolveBannerLevel(),
             ...(modeAllOverride ? { modeAllOverride: true } : {}),
+            ...(skipPersonal ? { skipPersonal: true } : {}),
         }, {
             vaultClient: adapter,
             sync: (opts) => sync({
@@ -759,10 +817,14 @@ async function runPullPersonal(hqRoot, onConflict) {
         process.exit(1);
     }
 }
-async function runPushAll(hqRoot, message, onConflict) {
+async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Push (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     let result;
     try {
         const accessToken = await ensureCognitoToken();
@@ -785,6 +847,7 @@ async function runPushAll(hqRoot, message, onConflict) {
             hqRoot,
             ...(onConflict ? { onConflict } : {}),
             ...(message ? { message } : {}),
+            ...(skipPersonal ? { skipPersonal: true } : {}),
         }, {
             vaultClient: adapter,
             share: (opts) => share({
@@ -976,20 +1039,24 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         process.exit(1);
     }
 }
-async function runNowAll(hqRoot, message, onConflict, modeAllOverride) {
+async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPersonal) {
     console.log(chalk.bold("\nHQ Sync — Now (all)"));
     console.log(`  HQ root:  ${hqRoot}`);
-    console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    console.log(`  Strategy: ${onConflict ?? "(interactive)"}`);
+    if (skipPersonal) {
+        console.log(`  Personal: skipped (--no-personal)`);
+    }
+    console.log("");
     // Push first (matches runner), then pull. Re-uses the per-leg orchestrators
     // so the per-target rendering, error isolation, and exit codes are
     // identical to running `push --all` then `pull --all` back-to-back.
     console.log(chalk.dim("→ push --all"));
-    await runPushAll(hqRoot, message, onConflict);
+    await runPushAll(hqRoot, message, onConflict, skipPersonal);
     console.log(chalk.dim("\n→ pull --all"));
     // US-011: forward --mode-all so the strict refusal applies to the
     // pull leg (push doesn't need a narrow-hint — the narrow ritual is
     // pull-side).
-    await runPullAll(hqRoot, onConflict, modeAllOverride);
+    await runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal);
 }
 /**
  * Best-effort read of the active company slug from `<hqRoot>/.hq/config.json`.
@@ -1063,4 +1130,4 @@ function resolveUploadAuthorFromCache() {
     }
 }
 //# sourceMappingURL=cloud.js.map
-//# debugId=4672d875-1dc8-56a2-bef1-49c7f4ff6c76
+//# debugId=bdaf154f-b17d-5482-9e4d-feaebe606a1b

package/dist/commands/files-browse.d.ts

@@ -72,8 +72,17 @@ export type S3ClientFactory = (input: {
         sessionToken: string;
     };
 }) => FilesBrowseS3Client;
-/** ACL provenance for a single listed key. */
-export type AclSource = "shared-with-you" | "role-bypass";
+/**
+ * ACL provenance for a single listed key.
+ *   - `shared-with-you`: an explicit grant the caller holds covers the key.
+ *   - `role-bypass`: the caller has no covering explicit grant, but
+ *      owner/admin role widened the browse-vend policy to include it.
+ *   - `personal-vault`: the key lives in the caller's own person-entity
+ *      vault, where no grants graph applies — the caller is the only
+ *      principal with access by construction. Emitted only when
+ *      `runBrowse({ personalMode: true })`.
+ */
+export type AclSource = "shared-with-you" | "role-bypass" | "personal-vault";
 export interface BrowseRow {
     key: string;
     size: number;
@@ -112,10 +121,30 @@ export declare function assertOutPathOutsideCompanies(outPath: string, hqRoot: s
  */
 export declare function formatBrowseTable(rows: BrowseRow[]): string;
 export interface RunBrowseInput {
-    /** Vault path prefix, e.g. `companies/indigo/scratch/`. */
+    /**
+     * Vault path prefix.
+     *   - Company mode (`personalMode: false | undefined`): must start with
+     *     `companies/<slug>/`, e.g. `companies/indigo/scratch/`.
+     *   - Personal mode (`personalMode: true`): bucket-relative; empty string
+     *     lists the whole personal vault root.
+     */
     pathPrefix: string;
-    /** Caller-overridden company slug (defaults to slug parsed from path). */
+    /** Caller-overridden company slug (defaults to slug parsed from path). Ignored under `personalMode`. */
     companySlug?: string;
+    /**
+     * Personal-vault mode. Skips the `companies/<slug>/` path requirement,
+     * resolves the entity via `entity.get(personalUid)` instead of the
+     * company namespace, omits the explicit-grants fetch (no grants graph
+     * on a person bucket), and marks every row's `aclSource` as
+     * `"personal-vault"`. Closes hq-cli#26 (audit gap for personal vault).
+     */
+    personalMode?: boolean;
+    /**
+     * Canonical person-entity UID (e.g. `prs_…`). Required when
+     * `personalMode: true`; ignored otherwise. Caller resolves via
+     * `resolveCanonicalPersonUid` to keep this orchestrator pure.
+     */
+    personalUid?: string;
     vaultClient: FilesBrowseVaultClient;
     s3Factory: S3ClientFactory;
     region: string;
@@ -137,7 +166,11 @@ export interface RunBrowseResult {
  */
 export declare function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>;
 export interface RunCatInput {
-    /** Single vault key, e.g. `companies/indigo/scratch/foo.txt`. */
+    /**
+     * Single vault key.
+     *   - Company mode: must be a `companies/<slug>/...` path.
+     *   - Personal mode: bucket-relative, e.g. `.claude/CLAUDE.md`.
+     */
     key: string;
     /**
      * Where to write the body. `undefined` ⇒ stdout. Bright-line-guarded
@@ -146,6 +179,10 @@ export interface RunCatInput {
     out?: string;
     hqRoot: string;
     companySlug?: string;
+    /** Personal-vault mode — see `RunBrowseInput.personalMode`. */
+    personalMode?: boolean;
+    /** Canonical person-entity UID; required when `personalMode: true`. */
+    personalUid?: string;
     vaultClient: FilesBrowseVaultClient;
     s3Factory: S3ClientFactory;
     region: string;

package/dist/commands/files-browse.js

@@ -29,7 +29,7 @@
  * `pnpm.overrides` until that release ships to npm.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7a4467c5-bef0-5f15-99f9-9db157497caa")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="55a4ece7-6b33-5809-97c0-475c423bc012")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -38,6 +38,7 @@ import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/clie
 import { VaultClient, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, DEFAULT_COGNITO, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
+import { resolveCanonicalPersonUid } from "./cloud.js";
 // ── Pure helpers ────────────────────────────────────────────────────────────
 /**
  * Parse the company slug from a vault prefix. Vault paths are anchored at
@@ -122,19 +123,43 @@ export function formatBrowseTable(rows) {
  * Pure-ish: no console output, no process.exit — caller renders + exits.
  */
 export async function runBrowse(input) {
-    const { pathPrefix, vaultClient, s3Factory, region } = input;
-    const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
-    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.`);
+    const { pathPrefix, vaultClient, s3Factory, region, personalMode } = input;
+    // Branch by mode. Company mode parses slug from path and looks up by
+    // namespace; personal mode resolves the entity directly by the supplied
+    // person UID and skips the slug + grants machinery (a person bucket has
+    // no grants graph — the owner is the only principal). The vend call is
+    // identical for both modes once we have the entity in hand.
+    let bucket;
+    let entityUid;
+    if (personalMode) {
+        if (!input.personalUid) {
+            throw new Error("runBrowse: personalMode requires personalUid. Resolve via " +
+                "resolveCanonicalPersonUid() before calling.");
+        }
+        const entity = await vaultClient.entity.get(input.personalUid);
+        if (!entity.bucketName) {
+            throw new Error(`Personal entity '${input.personalUid}' has no provisioned bucket.`);
+        }
+        entityUid = entity.uid;
+        bucket = entity.bucketName;
     }
-    if (!entity.bucketName) {
-        throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+    else {
+        const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
+        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.`);
+        }
+        entityUid = entity.uid;
+        bucket = entity.bucketName;
     }
-    const companyUid = entity.uid;
-    const bucket = entity.bucketName;
     // Distinct vend call from sync — `purpose: 'browse'` opts the request
-    // into the role-bypass-allowed code path on the server (US-009).
+    // into the role-bypass-allowed code path on the server (US-009). The
+    // personal mode vends against the person entity which is owner-only by
+    // construction; the vend response shape is identical so downstream
+    // S3Client construction doesn't branch.
     const vend = await vaultClient.vend({
         paths: [pathPrefix],
         operations: "read-only",
@@ -149,8 +174,12 @@ export async function runBrowse(input) {
         },
     });
     // Pull the caller's explicit-grant graph once so per-key classification
-    // is O(grants) without N round-trips.
-    const grants = await vaultClient.listMyExplicitGrants(companyUid);
+    // is O(grants) without N round-trips. Skipped in personal mode — the
+    // grants graph is a company concept; a person bucket marks every row
+    // as `"personal-vault"` directly.
+    const grants = personalMode
+        ? []
+        : await vaultClient.listMyExplicitGrants(entityUid);
     const rows = [];
     let continuationToken;
     do {
@@ -169,7 +198,7 @@ export async function runBrowse(input) {
                 key: obj.Key,
                 size: obj.Size ?? 0,
                 lastModified: obj.LastModified,
-                aclSource: classifyAclSource(obj.Key, grants),
+                aclSource: personalMode ? "personal-vault" : classifyAclSource(obj.Key, grants),
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -182,20 +211,37 @@ export async function runBrowse(input) {
  * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
  */
 export async function runCat(input) {
-    const { key, vaultClient, s3Factory, region, hqRoot } = input;
-    const slug = input.companySlug ?? parseCompanySlugFromPath(key);
+    const { key, vaultClient, s3Factory, region, hqRoot, personalMode } = input;
     // Acceptance 5: refuse BEFORE vending — no point pulling credentials
     // for a request we're already going to abort.
     let absOut;
     if (input.out !== undefined) {
         absOut = assertOutPathOutsideCompanies(input.out, hqRoot);
     }
-    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.`);
+    // Same branch logic as runBrowse — see that function's doc-block for
+    // the personal-vs-company rationale.
+    let bucket;
+    if (personalMode) {
+        if (!input.personalUid) {
+            throw new Error("runCat: personalMode requires personalUid. Resolve via " +
+                "resolveCanonicalPersonUid() before calling.");
+        }
+        const entity = await vaultClient.entity.get(input.personalUid);
+        if (!entity.bucketName) {
+            throw new Error(`Personal entity '${input.personalUid}' has no provisioned bucket.`);
+        }
+        bucket = entity.bucketName;
     }
-    if (!entity.bucketName) {
-        throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+    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 (!entity.bucketName) {
+            throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
+        }
+        bucket = entity.bucketName;
     }
     const vend = await vaultClient.vend({
         paths: [key],
@@ -210,7 +256,7 @@ export async function runCat(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
-    const resp = (await s3.send(new GetObjectCommand({ Bucket: entity.bucketName, Key: key })));
+    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
     }
@@ -247,15 +293,47 @@ const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, cre
  */
 export function registerFilesBrowseCommands(filesCmd) {
     filesCmd
-        .command("browse <path>")
-        .description("List vault objects under <path> without syncing them locally. Uses the browse-vend path (role-bypass allowed).")
+        .command("browse [path]")
+        .description("List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.")
         .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>)")
+        .option("--personal", "Browse the caller's canonical personal vault. [path] is treated as " +
+        "bucket-relative (omit it to list the vault root). Mutually exclusive " +
+        "with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .action(async (pathArg, options) => {
         try {
+            if (options.personal && options.company) {
+                throw new Error("--personal and --company are mutually exclusive. Pick one.");
+            }
             const accessToken = await ensureCognitoToken();
             const vaultConfig = buildVaultConfig(accessToken);
             const client = new VaultClient(vaultConfig);
+            if (options.personal) {
+                // Personal-vault path. Resolve the caller's canonical person
+                // entity once; the orchestrator does the bucket lookup + vend.
+                // Empty [path] → list bucket root.
+                const personalUid = await resolveCanonicalPersonUid({
+                    listMyMemberships: () => client.listMyMemberships(),
+                    listPersonEntities: () => client.entity.listByType("person"),
+                    getEntity: async () => null,
+                });
+                const result = await runBrowse({
+                    pathPrefix: pathArg ?? "",
+                    personalMode: true,
+                    personalUid,
+                    vaultClient: client,
+                    s3Factory: defaultS3Factory,
+                    region: DEFAULT_COGNITO.region,
+                });
+                console.log(formatBrowseTable(result.rows));
+                return;
+            }
+            // Company path. [path] is required here — the slug parse needs it.
+            if (!pathArg) {
+                throw new Error("browse: [path] is required when --personal is not set. " +
+                    "Pass a companies/<slug>/... path, or add --personal to " +
+                    "browse your personal vault.");
+            }
             // Resolve slug — CLI flag wins, otherwise parse from path arg.
             const slug = options.company ?? parseCompanySlugFromPath(pathArg);
             // If the user passed `--company` AND the path doesn't begin with
@@ -301,15 +379,41 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
     filesCmd
         .command("cat <path>")
-        .description("Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path.")
+        .description("Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path. Pass --personal to read from the caller's personal vault.")
         .option("--out <file>", "Write the object body to <file> instead of stdout. Refused under <hqRoot>/companies/.")
         .option("--company <slug>", "Company slug (defaults to the slug parsed from <path>)")
+        .option("--personal", "Read from the caller's canonical personal vault. <path> is treated as " +
+        "bucket-relative. Mutually exclusive with --company.")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .action(async (keyArg, options) => {
         try {
+            if (options.personal && options.company) {
+                throw new Error("--personal and --company are mutually exclusive. Pick one.");
+            }
             const accessToken = await ensureCognitoToken();
             const vaultConfig = buildVaultConfig(accessToken);
             const client = new VaultClient(vaultConfig);
+            if (options.personal) {
+                const personalUid = await resolveCanonicalPersonUid({
+                    listMyMemberships: () => client.listMyMemberships(),
+                    listPersonEntities: () => client.entity.listByType("person"),
+                    getEntity: async () => null,
+                });
+                const result = await runCat({
+                    key: keyArg,
+                    out: options.out,
+                    hqRoot: options.hqRoot,
+                    personalMode: true,
+                    personalUid,
+                    vaultClient: client,
+                    s3Factory: defaultS3Factory,
+                    region: DEFAULT_COGNITO.region,
+                });
+                if (result.destination.kind === "file") {
+                    console.error(chalk.green("✓"), `Wrote ${result.bytesWritten} bytes to ${result.destination.absPath}`);
+                }
+                return;
+            }
             const slug = options.company ?? parseCompanySlugFromPath(keyArg);
             if (options.company !== undefined) {
                 const fromPath = (() => {
@@ -345,4 +449,4 @@ export function registerFilesBrowseCommands(filesCmd) {
     });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=7a4467c5-bef0-5f15-99f9-9db157497caa
+//# debugId=55a4ece7-6b33-5809-97c0-475c423bc012

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.18.3",
+  "version": "5.20.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^5.23.0",
+    "@indigoai-us/hq-cloud": "~5.25.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",