@indigoai-us/hq-cli 5.26.0 → 5.29.0

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

@@ -17,31 +17,57 @@
  *                 `hq sync` owns, and writing a peeked object there would
  *                 silently re-import it into the sync envelope.
  *
- * Both subcommands vend via the new `purpose: 'browse'` path
- * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
- * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
- * keeping browse on its own vend call is the acceptance-criteria-1
- * separation we need.
+ * Both subcommands vend through the multi-tenant STS routes —
+ * `VaultClient.sts.vend` (`/sts/vend`, company) and `.sts.vendSelf`
+ * (`/sts/vend-self`, personal). These resolve the caller's per-entity bucket
+ * and apply role/ACL scoping server-side (owner/admin → full access; member/
+ * guest → per-prefix). The legacy `POST /vend` is deliberately NOT used: it
+ * assumes a single static `BUCKET_ARN` that is unset in multi-tenant prod, so
+ * it builds an invalid policy and STS rejects it (`MalformedPolicyDocument`).
  *
- * Cross-package note: depends on `VendInput`/`VendResult` + the
- * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
- * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
- * `pnpm.overrides` until that release ships to npm.
+ * Namespace note: company vault keys are company-relative (no
+ * `companies/<slug>/` prefix). The CLI speaks the anchored form for user
+ * familiarity and translates at the S3 boundary via `toBucketRelative` /
+ * `toCompanyAnchored`.
+ *
+ * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
+ * methods and `grantPathToPrefix` from hq-cloud.
  */
 import { Command } from "commander";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
-import { type VendResult, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type ExplicitGrant } from "@indigoai-us/hq-cloud";
+/** STS-vended credential set the browse/cat path consumes. */
+export interface BrowseCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+}
+/** Minimal STS-vend response shape (both `/sts/vend` and `/sts/vend-self`). */
+export interface BrowseVendResult {
+    credentials: BrowseCredentials;
+}
 /**
  * Subset of `VaultClient` this command actually uses — exposed so tests
  * can stub vend + grants without standing up a real `VaultClient`.
+ *
+ * Browse/cat vend through the multi-tenant `/sts/vend` (company) and
+ * `/sts/vend-self` (personal) routes — NOT the legacy `POST /vend`, which
+ * assumes a single static bucket and is non-functional in multi-tenant
+ * production (it builds a policy against an undefined `BUCKET_ARN`, so STS
+ * rejects it with `MalformedPolicyDocument`). The STS routes resolve the
+ * caller's per-entity bucket and apply role/ACL scoping server-side.
  */
 export interface FilesBrowseVaultClient {
-    vend(input: {
-        paths: string[];
-        operations: "read-only" | "read-write" | "staged-write";
-        purpose: "sync" | "browse";
-        duration?: number;
-    }): Promise<VendResult>;
+    sts: {
+        vend(input: {
+            companyUid: string;
+            durationSeconds?: number;
+        }): Promise<BrowseVendResult>;
+        vendSelf(input: {
+            personUid: string;
+            durationSeconds?: number;
+        }): Promise<BrowseVendResult>;
+    };
     listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
     entity: {
         get(uid: string): Promise<{
@@ -96,15 +122,33 @@ export interface BrowseRow {
  */
 export declare function parseCompanySlugFromPath(prefix: string): string;
 /**
- * Classify a single S3 key against the caller's explicit-grant list. Any
- * grant whose `path` is a prefix of the key contributes `shared-with-you`;
- * otherwise the key is only visible via role-bypass on the vend call.
+ * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
+ * the vault bucket actually stores. Company vault buckets are already
+ * company-scoped, so their keys carry NO `companies/<slug>/` prefix (e.g.
+ * `knowledge/foo.md`, not `companies/indigo/knowledge/foo.md`). The CLI speaks
+ * the anchored form for user familiarity; we strip the anchor at the S3
+ * boundary. A path without the anchor (or personal-mode, bucket-relative
+ * paths) passes through unchanged.
+ */
+export declare function toBucketRelative(pathOrPrefix: string, slug: string): string;
+/**
+ * Re-attach the `companies/<slug>/` anchor to a company-relative bucket key
+ * for display + `hq files cat` round-trip, so the CLI surface keeps speaking
+ * the anchored form the user passed in.
+ */
+export declare function toCompanyAnchored(bucketRelKey: string, slug: string): string;
+/**
+ * Classify a single company-relative S3 key against the caller's
+ * (already-normalized) explicit-grant prefixes. Any prefix that covers the
+ * key contributes `shared-with-you`; otherwise the key is visible only via
+ * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
+ * prefix is a company-wide grant and matches everything.
  *
- * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
- * `coalescePrefixes` would shrink the list further but isn't required for
- * correctness — `startsWith` already short-circuits on the first match.
+ * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
+ * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
+ * calling this — keeping this helper pure and trivially testable.
  */
-export declare function classifyAclSource(key: string, grants: ExplicitGrant[]): AclSource;
+export declare function classifyAclSource(bucketRelKey: string, grantPrefixes: string[]): AclSource;
 /**
  * Bright-line guard for `--out`: refuse to write any byte beneath
  * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
@@ -151,15 +195,17 @@ export interface RunBrowseInput {
 }
 export interface RunBrowseResult {
     rows: BrowseRow[];
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files browse <path>` orchestrator.
  *
  *   1. Parse slug from prefix (or use override).
  *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
- *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   3. Vend read creds via the multi-tenant STS route (`/sts/vend` company,
+ *      `/sts/vend-self` personal) — resolves the per-entity bucket + role/ACL.
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2 over the
+ *      company-relative key space.
  *   5. Fetch explicit grants once, classify each key.
  *
  * Pure-ish: no console output, no process.exit — caller renders + exits.
@@ -197,7 +243,7 @@ export interface RunCatResult {
         kind: "file";
         absPath: string;
     };
-    vend: VendResult;
+    vend: BrowseVendResult;
 }
 /**
  * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
@@ -205,6 +251,55 @@ export interface RunCatResult {
  * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
  */
 export declare function runCat(input: RunCatInput): Promise<RunCatResult>;
+/**
+ * Subset of `VaultClient` the `shared-with-me` orchestrator uses. No vend / S3
+ * — this is a pure read of the caller's explicit-grant graph, so it never
+ * touches the credential/browse vend surface.
+ */
+export interface FilesSharedWithMeVaultClient {
+    listMyMemberships(): Promise<Array<{
+        companyUid: string;
+    }>>;
+    listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
+    entity: {
+        get(uid: string): Promise<{
+            uid: string;
+            slug: string;
+            name?: string;
+        }>;
+    };
+}
+export interface SharedWithMeRow {
+    companySlug: string;
+    /** Company-relative grant path (e.g. `knowledge/`, `reports/q3.pdf`). */
+    path: string;
+    permission: ExplicitGrant["permission"];
+    source: ExplicitGrant["source"];
+}
+export interface RunSharedWithMeInput {
+    vaultClient: FilesSharedWithMeVaultClient;
+    /**
+     * Scope to a single company by UID. When omitted, rolls up across every
+     * company the caller has a membership in (the cross-company "what's shared
+     * with me everywhere" view).
+     */
+    companyUid?: string;
+    /** Display slug for the single-company case (avoids an extra entity.get). */
+    companySlug?: string;
+}
+/**
+ * `hq files shared-with-me` orchestrator. Lists the caller's EXPLICIT
+ * file-ACL grants — the canonical "what's been shared with me" surface.
+ * Role-bypass access (owner/admin) is intentionally excluded server-side by
+ * `listMyExplicitGrants`, so this shows real grants, not role-implied reach.
+ *
+ * Pure data — no console output, no S3, no vend. The caller renders + exits.
+ */
+export declare function runSharedWithMe(input: RunSharedWithMeInput): Promise<SharedWithMeRow[]>;
+/**
+ * Render `shared-with-me` rows as a padded table. Mirrors `formatBrowseTable`.
+ */
+export declare function formatSharedWithMeTable(rows: SharedWithMeRow[]): string;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group

package/dist/commands/files-browse.js

@@ -17,25 +17,30 @@
  *                 `hq sync` owns, and writing a peeked object there would
  *                 silently re-import it into the sync envelope.
  *
- * Both subcommands vend via the new `purpose: 'browse'` path
- * (`VaultClient.vend`) shipped in hq-cloud US-009. The server treats that
- * purpose as the role-bypass-allowed surface — sync vends NEVER widen, so
- * keeping browse on its own vend call is the acceptance-criteria-1
- * separation we need.
+ * Both subcommands vend through the multi-tenant STS routes —
+ * `VaultClient.sts.vend` (`/sts/vend`, company) and `.sts.vendSelf`
+ * (`/sts/vend-self`, personal). These resolve the caller's per-entity bucket
+ * and apply role/ACL scoping server-side (owner/admin → full access; member/
+ * guest → per-prefix). The legacy `POST /vend` is deliberately NOT used: it
+ * assumes a single static `BUCKET_ARN` that is unset in multi-tenant prod, so
+ * it builds an invalid policy and STS rejects it (`MalformedPolicyDocument`).
  *
- * Cross-package note: depends on `VendInput`/`VendResult` + the
- * `VaultClient.vend` method from hq-cloud US-009 (commit 2f790c5).
- * hq-cli pins `@indigoai-us/hq-cloud` to `file:../hq-cloud` via
- * `pnpm.overrides` until that release ships to npm.
+ * Namespace note: company vault keys are company-relative (no
+ * `companies/<slug>/` prefix). The CLI speaks the anchored form for user
+ * familiarity and translates at the S3 boundary via `toBucketRelative` /
+ * `toCompanyAnchored`.
+ *
+ * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
+ * methods and `grantPathToPrefix` from hq-cloud.
  */
 
-!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){}}();
+!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]="e2f338ce-5871-59ad-ae56-99bd29e1711c")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { S3Client, ListObjectsV2Command, GetObjectCommand, } from "@aws-sdk/client-s3";
-import { VaultClient, } from "@indigoai-us/hq-cloud";
+import { VaultClient, grantPathToPrefix, } 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";
@@ -54,17 +59,43 @@ export function parseCompanySlugFromPath(prefix) {
     return parts[1];
 }
 /**
- * Classify a single S3 key against the caller's explicit-grant list. Any
- * grant whose `path` is a prefix of the key contributes `shared-with-you`;
- * otherwise the key is only visible via role-bypass on the vend call.
+ * Translate a CLI `companies/<slug>/…` path into the company-relative S3 key
+ * the vault bucket actually stores. Company vault buckets are already
+ * company-scoped, so their keys carry NO `companies/<slug>/` prefix (e.g.
+ * `knowledge/foo.md`, not `companies/indigo/knowledge/foo.md`). The CLI speaks
+ * the anchored form for user familiarity; we strip the anchor at the S3
+ * boundary. A path without the anchor (or personal-mode, bucket-relative
+ * paths) passes through unchanged.
+ */
+export function toBucketRelative(pathOrPrefix, slug) {
+    const anchor = `companies/${slug}/`;
+    const normalized = pathOrPrefix.replace(/^\/+/, "");
+    return normalized.startsWith(anchor)
+        ? normalized.slice(anchor.length)
+        : normalized;
+}
+/**
+ * Re-attach the `companies/<slug>/` anchor to a company-relative bucket key
+ * for display + `hq files cat` round-trip, so the CLI surface keeps speaking
+ * the anchored form the user passed in.
+ */
+export function toCompanyAnchored(bucketRelKey, slug) {
+    return `companies/${slug}/${bucketRelKey}`;
+}
+/**
+ * Classify a single company-relative S3 key against the caller's
+ * (already-normalized) explicit-grant prefixes. Any prefix that covers the
+ * key contributes `shared-with-you`; otherwise the key is visible only via
+ * the owner/admin role-bypass the `/sts/vend` policy applied. An empty-string
+ * prefix is a company-wide grant and matches everything.
  *
- * Grant paths and S3 keys live in the same canonical form ("companies/<slug>/…");
- * `coalescePrefixes` would shrink the list further but isn't required for
- * correctness — `startsWith` already short-circuits on the first match.
+ * Grant `path`s arrive in inconsistent/glob form; the caller normalizes them
+ * to company-relative `startsWith` prefixes via `grantPathToPrefix` before
+ * calling this — keeping this helper pure and trivially testable.
  */
-export function classifyAclSource(key, grants) {
-    for (const g of grants) {
-        if (g.path && key.startsWith(g.path))
+export function classifyAclSource(bucketRelKey, grantPrefixes) {
+    for (const p of grantPrefixes) {
+        if (p === "" || bucketRelKey.startsWith(p))
             return "shared-with-you";
     }
     return "role-bypass";
@@ -116,8 +147,10 @@ export function formatBrowseTable(rows) {
  *
  *   1. Parse slug from prefix (or use override).
  *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   3. Vend with `purpose: 'browse'`, `operations: 'read-only'`, paths: [prefix].
- *   4. Construct S3Client from vended creds, paginate ListObjectsV2.
+ *   3. Vend read creds via the multi-tenant STS route (`/sts/vend` company,
+ *      `/sts/vend-self` personal) — resolves the per-entity bucket + role/ACL.
+ *   4. Construct S3Client from vended creds, paginate ListObjectsV2 over the
+ *      company-relative key space.
  *   5. Fetch explicit grants once, classify each key.
  *
  * Pure-ish: no console output, no process.exit — caller renders + exits.
@@ -127,10 +160,11 @@ export async function runBrowse(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.
+    // no grants graph — the owner is the only principal).
     let bucket;
     let entityUid;
+    let slug;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runBrowse: personalMode requires personalUid. Resolve via " +
@@ -142,9 +176,10 @@ export async function runBrowse(input) {
         }
         entityUid = entity.uid;
         bucket = entity.bucketName;
+        vend = await vaultClient.sts.vendSelf({ personUid: entityUid });
     }
     else {
-        const slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
+        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.`);
@@ -154,17 +189,11 @@ export async function runBrowse(input) {
         }
         entityUid = entity.uid;
         bucket = entity.bucketName;
+        // Multi-tenant vend: the server resolves this company's bucket + applies
+        // owner/admin role-bypass (full access) or member/guest ACL scoping. The
+        // legacy `POST /vend` is unused here — see FilesBrowseVaultClient docs.
+        vend = await vaultClient.sts.vend({ companyUid: entityUid });
     }
-    // Distinct vend call from sync — `purpose: 'browse'` opts the request
-    // 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",
-        purpose: "browse",
-    });
     const s3 = s3Factory({
         region,
         credentials: {
@@ -173,19 +202,26 @@ export async function runBrowse(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
+    // Company vault keys are company-relative (no `companies/<slug>/` prefix), so
+    // translate the CLI's anchored prefix into the bucket-relative form before
+    // listing. Personal-mode paths are already bucket-relative.
+    const listPrefix = personalMode || slug === undefined
+        ? pathPrefix
+        : toBucketRelative(pathPrefix, slug);
     // Pull the caller's explicit-grant graph once so per-key classification
-    // 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
+    // is O(grants) without N round-trips. Grant `path`s are normalized to
+    // company-relative `startsWith` prefixes (matching the bucket key space)
+    // via `grantPathToPrefix`. Skipped in personal mode — the grants graph is a
+    // company concept; a person bucket marks every row `"personal-vault"`.
+    const grantPrefixes = personalMode || slug === undefined
         ? []
-        : await vaultClient.listMyExplicitGrants(entityUid);
+        : (await vaultClient.listMyExplicitGrants(entityUid)).map((g) => grantPathToPrefix(g.path, slug));
     const rows = [];
     let continuationToken;
     do {
         const resp = (await s3.send(new ListObjectsV2Command({
             Bucket: bucket,
-            Prefix: pathPrefix,
+            Prefix: listPrefix,
             ContinuationToken: continuationToken,
         })));
         for (const obj of resp.Contents ?? []) {
@@ -194,11 +230,17 @@ export async function runBrowse(input) {
             // Skip S3 "directory marker" objects (0-byte, trailing slash).
             if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0)
                 continue;
+            // `obj.Key` is company-relative. Classify in that space, then re-anchor
+            // for display so the CLI keeps speaking `companies/<slug>/...`.
             rows.push({
-                key: obj.Key,
+                key: personalMode || slug === undefined
+                    ? obj.Key
+                    : toCompanyAnchored(obj.Key, slug),
                 size: obj.Size ?? 0,
                 lastModified: obj.LastModified,
-                aclSource: personalMode ? "personal-vault" : classifyAclSource(obj.Key, grants),
+                aclSource: personalMode
+                    ? "personal-vault"
+                    : classifyAclSource(obj.Key, grantPrefixes),
             });
         }
         continuationToken = resp.NextContinuationToken ?? undefined;
@@ -221,6 +263,8 @@ export async function runCat(input) {
     // Same branch logic as runBrowse — see that function's doc-block for
     // the personal-vs-company rationale.
     let bucket;
+    let s3Key;
+    let vend;
     if (personalMode) {
         if (!input.personalUid) {
             throw new Error("runCat: personalMode requires personalUid. Resolve via " +
@@ -231,6 +275,8 @@ export async function runCat(input) {
             throw new Error(`Personal entity '${input.personalUid}' has no provisioned bucket.`);
         }
         bucket = entity.bucketName;
+        s3Key = key; // personal-mode keys are already bucket-relative
+        vend = await vaultClient.sts.vendSelf({ personUid: entity.uid });
     }
     else {
         const slug = input.companySlug ?? parseCompanySlugFromPath(key);
@@ -242,12 +288,10 @@ export async function runCat(input) {
             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);
+        vend = await vaultClient.sts.vend({ companyUid: entity.uid });
     }
-    const vend = await vaultClient.vend({
-        paths: [key],
-        operations: "read-only",
-        purpose: "browse",
-    });
     const s3 = s3Factory({
         region,
         credentials: {
@@ -256,7 +300,7 @@ export async function runCat(input) {
             sessionToken: vend.credentials.sessionToken,
         },
     });
-    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key })));
+    const resp = (await s3.send(new GetObjectCommand({ Bucket: bucket, Key: s3Key })));
     if (!resp.Body) {
         throw new Error(`GetObject for '${key}' returned no body.`);
     }
@@ -283,6 +327,79 @@ export async function runCat(input) {
     await pipeline(body, input.stdout ?? process.stdout);
     return { bytesWritten, destination: { kind: "stdout" }, vend };
 }
+/**
+ * `hq files shared-with-me` orchestrator. Lists the caller's EXPLICIT
+ * file-ACL grants — the canonical "what's been shared with me" surface.
+ * Role-bypass access (owner/admin) is intentionally excluded server-side by
+ * `listMyExplicitGrants`, so this shows real grants, not role-implied reach.
+ *
+ * Pure data — no console output, no S3, no vend. The caller renders + exits.
+ */
+export async function runSharedWithMe(input) {
+    const { vaultClient } = input;
+    // Resolve the (companyUid, slug) pairs to query. Single-company when a UID
+    // was supplied; otherwise fan out across every membership.
+    let targets;
+    if (input.companyUid) {
+        targets = [{ uid: input.companyUid, slug: input.companySlug ?? input.companyUid }];
+    }
+    else {
+        const memberships = await vaultClient.listMyMemberships();
+        targets = await Promise.all(memberships.map(async (m) => {
+            try {
+                const ent = await vaultClient.entity.get(m.companyUid);
+                return { uid: m.companyUid, slug: ent.slug || m.companyUid };
+            }
+            catch {
+                // Entity not visible — fall back to the UID as the display label
+                // rather than dropping the company's grants entirely.
+                return { uid: m.companyUid, slug: m.companyUid };
+            }
+        }));
+    }
+    const rows = [];
+    for (const t of targets) {
+        let grants;
+        try {
+            grants = await vaultClient.listMyExplicitGrants(t.uid);
+        }
+        catch {
+            // A single company's grant fetch failing shouldn't sink the whole
+            // roll-up — skip it and continue (best-effort discovery view).
+            continue;
+        }
+        for (const g of grants) {
+            rows.push({
+                companySlug: t.slug,
+                path: g.path,
+                permission: g.permission,
+                source: g.source,
+            });
+        }
+    }
+    // Stable sort: company, then path — deterministic output for humans + tests.
+    rows.sort((a, b) => a.companySlug === b.companySlug
+        ? a.path.localeCompare(b.path)
+        : a.companySlug.localeCompare(b.companySlug));
+    return rows;
+}
+/**
+ * Render `shared-with-me` rows as a padded table. Mirrors `formatBrowseTable`.
+ */
+export function formatSharedWithMeTable(rows) {
+    if (rows.length === 0) {
+        return "Nothing is explicitly shared with you. (Owner/admin role-bypass access is not listed here — only explicit grants.)";
+    }
+    const cols = ["COMPANY", "PATH", "PERMISSION", "SOURCE"];
+    const data = rows.map((r) => [r.companySlug, r.path, r.permission, r.source]);
+    const widths = cols.map((c, i) => Math.max(c.length, ...data.map((row) => row[i].length)));
+    const renderRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    return [
+        chalk.bold(renderRow(cols)),
+        chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
+        ...data.map(renderRow),
+    ].join("\n");
+}
 // ── CLI registration ────────────────────────────────────────────────────────
 const defaultS3Factory = ({ region, credentials }) => new S3Client({ region, credentials });
 /**
@@ -447,6 +564,33 @@ export function registerFilesBrowseCommands(filesCmd) {
             process.exit(1);
         }
     });
+    filesCmd
+        .command("shared-with-me")
+        .description("List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).")
+        .option("--company <slug>", "Scope to a single company (defaults to a cross-company roll-up).")
+        .action(async (options) => {
+        try {
+            const accessToken = await ensureCognitoToken();
+            const vaultConfig = buildVaultConfig(accessToken);
+            const client = new VaultClient(vaultConfig);
+            let companyUid;
+            if (options.company) {
+                // Confirm membership + resolve UID, same early-failure pattern as
+                // browse/cat. Roll-up mode skips this and fans out internally.
+                companyUid = await getCompanyUid(accessToken, options.company);
+            }
+            const rows = await runSharedWithMe({
+                vaultClient: client,
+                companyUid,
+                companySlug: options.company,
+            });
+            console.log(formatSharedWithMeTable(rows));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
 }
 //# sourceMappingURL=files-browse.js.map
-//# debugId=55a4ece7-6b33-5809-97c0-475c423bc012
+//# debugId=e2f338ce-5871-59ad-ae56-99bd29e1711c

package/dist/commands/sync-narrow.js

@@ -37,11 +37,11 @@
  * `file:../hq-cloud` via `pnpm.overrides`.
  */
 
-!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]="a6c1e2b9-5d9a-57b2-a80b-adfdbce88206")}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]="8cdf980e-e3cf-585c-b2e5-1615765675a1")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import * as fs from "node:fs";
-import { VaultClient, coalescePrefixes, readJournal, writeJournal, tombstoneEntry, } from "@indigoai-us/hq-cloud";
+import { VaultClient, coalescePrefixes, grantPathToPrefix, readJournal, writeJournal, tombstoneEntry, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { readActiveCompanySlug } from "./sync-mode.js";
 import { buildNarrowPlan, formatBytes, formatNarrowPlanSummary, } from "../lib/local-tree-diff.js";
@@ -115,7 +115,18 @@ export async function computeNarrowPlan(input) {
     const { hqRoot, companySlug, companyUid, vaultClient } = input;
     const io = input.journalIO ?? realJournalIO;
     const grants = await vaultClient.listMyExplicitGrants(companyUid);
-    const prospectivePrefixSet = coalescePrefixes(grants.map((g) => g.path));
+    // Normalize each grant into a company-relative, startsWith-friendly prefix
+    // (grantPathToPrefix, hq-cloud ≥5.42.0): real grants are anchored
+    // (`companies/<slug>/x/*`, `<slug>/x/*`) and glob-style (`x/*`, bare `*`),
+    // none of which startsWith-match the company-relative local-tree keys
+    // buildNarrowPlan emits. A wildcard grant normalizes to "" (everything);
+    // coalescePrefixes drops empties, so guard it explicitly to `[""]` (which
+    // isCoveredByAny treats as covering everything → nothing orphaned) rather
+    // than letting it collapse to "nothing" and propose deleting the tree.
+    const normalizedPrefixes = grants.map((g) => grantPathToPrefix(g.path, companySlug));
+    const prospectivePrefixSet = normalizedPrefixes.some((p) => p === "")
+        ? [""]
+        : coalescePrefixes(normalizedPrefixes);
     const journal = io.read(companySlug);
     const plan = buildNarrowPlan({
         hqRoot,
@@ -324,4 +335,4 @@ export function registerSyncNarrowCommand(syncCmd) {
     });
 }
 //# sourceMappingURL=sync-narrow.js.map
-//# debugId=a6c1e2b9-5d9a-57b2-a80b-adfdbce88206
+//# debugId=8cdf980e-e3cf-585c-b2e5-1615765675a1

package/dist/lib/local-tree-diff.d.ts

@@ -26,7 +26,11 @@
 import { type SyncJournal } from "@indigoai-us/hq-cloud";
 export type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
 export interface NarrowFile {
-    /** Path relative to `hqRoot` (matches journal key + S3 key naming). */
+    /**
+     * COMPANY-RELATIVE path (e.g. `meetings/a.md`) — the canonical namespace
+     * shared by the per-company journal keys, the vault S3 keys, and the
+     * server's explicit-grant paths. NOT hq-root-relative.
+     */
     relPath: string;
     /** Absolute path on disk (convenience for the CLI delete loop). */
     absPath: string;
@@ -57,7 +61,8 @@ export interface BuildNarrowPlanInput {
     /**
      * Coalesced prospective `shared`-mode prefix set (the result of running
      * the caller's explicit grants through `coalescePrefixes`). Prefixes are
-     * hq-root-relative (e.g. `companies/indigo/meetings/`).
+     * COMPANY-RELATIVE (e.g. `meetings/`) — the namespace the grants endpoint
+     * returns and the namespace `relPath` is now computed in.
      */
     prospectivePrefixSet: readonly string[];
     /**