@indigoai-us/hq-cli 5.26.0 → 5.28.0

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

@@ -205,6 +205,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

@@ -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]="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]="102456e4-666a-5484-b432-7f0b73275818")}catch(e){}}();
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -283,6 +283,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 +520,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=102456e4-666a-5484-b432-7f0b73275818

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[];
     /**

package/dist/lib/local-tree-diff.js

@@ -24,7 +24,7 @@
  * for the destructive side effects (delete, tombstone, PUT sync-config).
  */
 
-!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]="77563dec-63f2-52df-9138-c88bfd1600b9")}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]="20a280f3-0fed-5868-9ad4-fcc562253486")}catch(e){}}();
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { hashFile, isCoveredByAny, } from "@indigoai-us/hq-cloud";
@@ -55,7 +55,16 @@ export function buildNarrowPlan(input) {
     if (!fs.existsSync(walkRoot)) {
         return emptyPlan();
     }
-    walkLocal(walkRoot, hqRoot, (file) => {
+    // Walk with `walkRoot` as the rel-root so each file's `relPath` is
+    // COMPANY-RELATIVE (e.g. `meetings/a.md`) — the same namespace as the
+    // server's explicit-grant paths, the per-company journal keys, and the
+    // hq-cloud sync engine's `RemoteFile.key`. Computing it relative to `hqRoot`
+    // (the old behavior) produced `companies/<slug>/meetings/a.md`, which
+    // matched neither the company-relative grants nor the journal keys — so
+    // every file fell out of `prospectivePrefixSet` AND missed its journal
+    // entry, making narrow flag the entire tree as dirty orphans. See the
+    // namespace contract in hq-cloud `scope-shrink.ts` / `prefix-coalesce.ts`.
+    walkLocal(walkRoot, walkRoot, (file) => {
         if (isCoveredByAny(file.relPath, prospectivePrefixSet)) {
             staying.push(file);
             return;
@@ -100,7 +109,10 @@ function emptyPlan() {
  * Uses `lstat` rather than `stat` so a symlink's size doesn't follow the
  * target chain (matches the share-engine convention).
  */
-function walkLocal(dir, hqRoot, emit) {
+function walkLocal(dir, 
+// Rel-root for `relPath` — the company walk root (`<hqRoot>/companies/<slug>`),
+// so emitted `relPath`s are company-relative. Fixed across recursion.
+relRoot, emit) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -115,7 +127,7 @@ function walkLocal(dir, hqRoot, emit) {
     }
     for (const entry of entries) {
         const absPath = path.join(dir, entry.name);
-        const relPath = path.relative(hqRoot, absPath);
+        const relPath = path.relative(relRoot, absPath);
         if (entry.isSymbolicLink()) {
             // Record the link as a file-like entry. Don't descend — narrow is
             // about pruning files that the LOCAL tree has materialized here; a
@@ -132,7 +144,7 @@ function walkLocal(dir, hqRoot, emit) {
             continue;
         }
         if (entry.isDirectory()) {
-            walkLocal(absPath, hqRoot, emit);
+            walkLocal(absPath, relRoot, emit);
             continue;
         }
         if (entry.isFile()) {
@@ -241,4 +253,4 @@ export function formatBytes(n) {
     return `${v.toFixed(2)} ${units[i]}`;
 }
 //# sourceMappingURL=local-tree-diff.js.map
-//# debugId=77563dec-63f2-52df-9138-c88bfd1600b9
+//# debugId=20a280f3-0fed-5868-9ad4-fcc562253486

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.26.0",
+  "version": "5.28.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.39.0",
+    "@indigoai-us/hq-cloud": "~5.42.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/files-browse.test.ts

@@ -27,8 +27,11 @@ import {
   parseCompanySlugFromPath,
   runBrowse,
   runCat,
+  runSharedWithMe,
+  formatSharedWithMeTable,
   type FilesBrowseS3Client,
   type FilesBrowseVaultClient,
+  type FilesSharedWithMeVaultClient,
   type S3ClientFactory,
 } from "./files-browse.js";
 import type { ExplicitGrant, VendResult } from "@indigoai-us/hq-cloud";
@@ -685,3 +688,89 @@ describe("runCat", () => {
     ).rejects.toThrow(/personalMode requires personalUid/);
   });
 });
+
+// ── runSharedWithMe ──────────────────────────────────────────────────────────
+
+function sharedWithMeClient(opts: {
+  memberships?: Array<{ companyUid: string }>;
+  grantsByCompany?: Record<string, ExplicitGrant[]>;
+  slugByUid?: Record<string, string>;
+}): FilesSharedWithMeVaultClient {
+  return {
+    listMyMemberships: async () => opts.memberships ?? [],
+    listMyExplicitGrants: async (companyUid: string) =>
+      opts.grantsByCompany?.[companyUid] ?? [],
+    entity: {
+      get: async (uid: string) => ({
+        uid,
+        slug: opts.slugByUid?.[uid] ?? uid,
+      }),
+    },
+  };
+}
+
+describe("runSharedWithMe", () => {
+  it("lists explicit grants for a single company (companyUid supplied)", async () => {
+    const rows = await runSharedWithMe({
+      vaultClient: sharedWithMeClient({
+        grantsByCompany: {
+          cmp_indigo: [fakeGrant("knowledge/"), fakeGrant("reports/q3.pdf")],
+        },
+      }),
+      companyUid: "cmp_indigo",
+      companySlug: "indigo",
+    });
+    expect(rows).toEqual([
+      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
+      { companySlug: "indigo", path: "reports/q3.pdf", permission: "read", source: "person" },
+    ]);
+  });
+
+  it("rolls up across every membership when no company is supplied", async () => {
+    const rows = await runSharedWithMe({
+      vaultClient: sharedWithMeClient({
+        memberships: [{ companyUid: "cmp_b" }, { companyUid: "cmp_a" }],
+        slugByUid: { cmp_a: "acme", cmp_b: "beta" },
+        grantsByCompany: {
+          cmp_a: [fakeGrant("docs/")],
+          cmp_b: [fakeGrant("shared/")],
+        },
+      }),
+    });
+    // Sorted by company slug, then path.
+    expect(rows.map((r) => [r.companySlug, r.path])).toEqual([
+      ["acme", "docs/"],
+      ["beta", "shared/"],
+    ]);
+  });
+
+  it("skips a company whose grant fetch throws (best-effort roll-up)", async () => {
+    const client: FilesSharedWithMeVaultClient = {
+      listMyMemberships: async () => [{ companyUid: "cmp_ok" }, { companyUid: "cmp_bad" }],
+      listMyExplicitGrants: async (uid: string) => {
+        if (uid === "cmp_bad") throw new Error("boom");
+        return [fakeGrant("ok/")];
+      },
+      entity: { get: async (uid: string) => ({ uid, slug: uid }) },
+    };
+    const rows = await runSharedWithMe({ vaultClient: client });
+    expect(rows).toEqual([
+      { companySlug: "cmp_ok", path: "ok/", permission: "read", source: "person" },
+    ]);
+  });
+
+  it("formats an empty result with the role-bypass caveat", () => {
+    const out = formatSharedWithMeTable([]);
+    expect(out).toContain("Nothing is explicitly shared with you");
+    expect(out).toContain("role-bypass");
+  });
+
+  it("formats rows as a table with company + path + permission + source", () => {
+    const out = formatSharedWithMeTable([
+      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
+    ]);
+    expect(out).toContain("COMPANY");
+    expect(out).toContain("indigo");
+    expect(out).toContain("knowledge/");
+  });
+});

package/src/commands/files-browse.ts

@@ -484,6 +484,125 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   return { bytesWritten, destination: { kind: "stdout" }, vend };
 }
 
+// ── shared-with-me ────────────────────────────────────────────────────────
+
+/**
+ * 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 async function runSharedWithMe(
+  input: RunSharedWithMeInput,
+): Promise<SharedWithMeRow[]> {
+  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: Array<{ uid: string; slug: string }>;
+  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: SharedWithMeRow[] = [];
+  for (const t of targets) {
+    let grants: ExplicitGrant[];
+    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: SharedWithMeRow[]): string {
+  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: string[]): string =>
+    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: S3ClientFactory = ({ region, credentials }) =>
@@ -736,4 +855,42 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
         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: { company?: string }) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const vaultConfig = buildVaultConfig(accessToken);
+        const client = new VaultClient(vaultConfig);
+
+        let companyUid: string | undefined;
+        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);
+      }
+    });
 }

package/src/commands/sync-narrow.test.ts

@@ -291,18 +291,24 @@ describe("resolveNarrowTarget", () => {
 
 describe("computeNarrowPlan", () => {
   it("coalesces grants and returns a partitioned plan", async () => {
+    // Files live on disk at their hq-root-relative path…
     writeFile("companies/acme/meetings/notes.md", "stays");
     writeFile("companies/acme/scratch/old.md", "clean orphan");
 
+    // …but the journal keys + grant paths are COMPANY-RELATIVE — the
+    // namespace the real server + engine use. (The old fixtures used
+    // full `companies/acme/...` grant paths, which never matched the
+    // company-relative keys buildNarrowPlan emits — masking the namespace
+    // bug this test now guards against.)
     const journal = journalFromFiles([
-      { rel: "companies/acme/meetings/notes.md", contents: "stays" },
-      { rel: "companies/acme/scratch/old.md", contents: "clean orphan" },
+      { rel: "meetings/notes.md", contents: "stays" },
+      { rel: "scratch/old.md", contents: "clean orphan" },
     ]);
 
     const { client } = makeStubClient({
       grants: [
-        fakeGrant("companies/acme/meetings/"),
-        fakeGrant("companies/acme/meetings/2026/"), // collapsed by coalesce
+        fakeGrant("meetings/"),
+        fakeGrant("meetings/2026/"), // collapsed by coalesce
       ],
     });
 
@@ -316,13 +322,67 @@ describe("computeNarrowPlan", () => {
       journalIO: journalIO.io,
     });
 
-    expect(result.prospectivePrefixSet).toEqual([
-      "companies/acme/meetings/",
+    expect(result.prospectivePrefixSet).toEqual(["meetings/"]);
+    expect(result.plan.totalStayingCount).toBe(1);
+    expect(result.plan.totalCleanCount).toBe(1);
+    expect(result.plan.totalDirtyCount).toBe(0);
+  });
+
+  it("normalizes real-world anchored + glob grant paths (grantPathToPrefix)", async () => {
+    writeFile("companies/acme/design-pack/logo.svg", "svg");
+    writeFile("companies/acme/scratch/old.md", "clean orphan");
+
+    const journal = journalFromFiles([
+      { rel: "design-pack/logo.svg", contents: "svg" },
+      { rel: "scratch/old.md", contents: "clean orphan" },
     ]);
+
+    // The exact messy shapes the live vault returns: full-anchored + glob,
+    // and slug-anchored + glob — neither startsWith-matches the
+    // company-relative local keys until grantPathToPrefix de-anchors them.
+    const { client } = makeStubClient({
+      grants: [
+        fakeGrant("companies/acme/design-pack/*"),
+        fakeGrant("acme/design-pack/2026/*"), // subsumed after normalize+coalesce
+      ],
+    });
+
+    const result = await computeNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      companyUid: "cmp_acme",
+      vaultClient: client,
+      journalIO: makeStubJournalIO(journal).io,
+    });
+
+    expect(result.prospectivePrefixSet).toEqual(["design-pack/"]);
+    // design-pack/logo.svg stays (covered); scratch/old.md is a clean orphan.
     expect(result.plan.totalStayingCount).toBe(1);
     expect(result.plan.totalCleanCount).toBe(1);
     expect(result.plan.totalDirtyCount).toBe(0);
   });
+
+  it("a wildcard '*' grant keeps everything (no orphans)", async () => {
+    writeFile("companies/acme/a.md", "a");
+    writeFile("companies/acme/sub/b.md", "b");
+
+    const { client } = makeStubClient({ grants: [fakeGrant("*")] });
+
+    const result = await computeNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      companyUid: "cmp_acme",
+      vaultClient: client,
+      journalIO: makeStubJournalIO(journalFromFiles([])).io,
+    });
+
+    // "*" → "" → guarded to [""] (covers everything) so narrowing keeps the
+    // whole tree rather than collapsing to "nothing" and proposing deletes.
+    expect(result.prospectivePrefixSet).toEqual([""]);
+    expect(result.plan.totalCleanCount).toBe(0);
+    expect(result.plan.totalDirtyCount).toBe(0);
+    expect(result.plan.totalStayingCount).toBe(2);
+  });
 });
 
 // ── applyNarrow ─────────────────────────────────────────────────────────────

package/src/commands/sync-narrow.ts

@@ -45,6 +45,7 @@ import * as fs from "node:fs";
 import {
   VaultClient,
   coalescePrefixes,
+  grantPathToPrefix,
   readJournal,
   writeJournal,
   tombstoneEntry,
@@ -218,7 +219,20 @@ export async function computeNarrowPlan(
   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({

package/src/lib/local-tree-diff.test.ts

@@ -4,6 +4,13 @@
  * Uses a tmpdir fixture (same pattern as cloud-demote.test.ts) — vitest +
  * real fs — so the symmetric-diff + dirty-classification logic is exercised
  * end-to-end against an actual journal + filesystem.
+ *
+ * NAMESPACE CONTRACT (the bug these tests previously encoded): files are
+ * written on disk at their hq-root-relative path (`companies/<slug>/...`),
+ * but `buildNarrowPlan` emits — and the journal + grants endpoint use —
+ * COMPANY-RELATIVE keys (`meetings/a.md`). The `key()` helper derives the
+ * company-relative form from the on-disk path so journals, prefix sets, and
+ * expectations all speak the same namespace the real server does.
  */
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -30,11 +37,23 @@ function writeFile(rel: string, contents: string): { abs: string; rel: string }
   return { abs, rel };
 }
 
+/**
+ * Strip the `companies/<slug>/` prefix from an on-disk hq-root-relative path
+ * to get the COMPANY-RELATIVE key — the namespace `buildNarrowPlan` emits and
+ * the journal + grants endpoint use.
+ */
+function key(rel: string): string {
+  return rel.replace(/^companies\/[^/]+\//, "");
+}
+
 function sha256(s: string): string {
   return crypto.createHash("sha256").update(s).digest("hex");
 }
 
-/** Build a journal that "knows about" the given files at their current hash + mtime. */
+/**
+ * Build a journal that "knows about" the given files at their current hash +
+ * mtime. Journal keys are COMPANY-RELATIVE (via `key()`), matching the engine.
+ */
 function journalFromFiles(
   files: Array<{ rel: string; contents: string; syncedAt?: string }>,
 ): SyncJournal {
@@ -45,7 +64,7 @@ function journalFromFiles(
     pulls: [],
   };
   for (const f of files) {
-    j.files[f.rel] = {
+    j.files[key(f.rel)] = {
       hash: sha256(f.contents),
       size: Buffer.byteLength(f.contents),
       // Stamp syncedAt slightly in the future so on-disk mtime <= syncedAt
@@ -97,13 +116,13 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/meetings/"],
+      prospectivePrefixSet: ["meetings/"],
       journal,
     });
 
-    expect(plan.staying.map((f) => f.relPath)).toEqual([staying.rel]);
-    expect(plan.clean.map((f) => f.relPath)).toEqual([cleanOrphan.rel]);
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([dirtyOrphan.rel]);
+    expect(plan.staying.map((f) => f.relPath)).toEqual([key(staying.rel)]);
+    expect(plan.clean.map((f) => f.relPath)).toEqual([key(cleanOrphan.rel)]);
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(dirtyOrphan.rel)]);
     expect(plan.dirty[0].reason).toBe("hash-mismatch");
 
     expect(plan.totalStayingCount).toBe(1);
@@ -117,10 +136,10 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/meetings/"],
+      prospectivePrefixSet: ["meetings/"],
       journal: journalFromFiles([]),
     });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
     expect(plan.dirty[0].reason).toBe("not-in-journal");
   });
 
@@ -130,16 +149,16 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
       { rel: orphan.rel, contents: "still here" },
     ]);
     // Mark the entry tombstoned post-hoc.
-    journal.files[orphan.rel]!.removedAt = new Date().toISOString();
-    journal.files[orphan.rel]!.removedReason = "scope_shrink";
+    journal.files[key(orphan.rel)]!.removedAt = new Date().toISOString();
+    journal.files[key(orphan.rel)]!.removedReason = "scope_shrink";
 
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/meetings/"],
+      prospectivePrefixSet: ["meetings/"],
       journal,
     });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
     expect(plan.dirty[0].reason).toBe("not-in-journal");
   });
 
@@ -151,10 +170,10 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/meetings/"],
+      prospectivePrefixSet: ["meetings/"],
       journal,
     });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
     expect(plan.dirty[0].reason).toBe("modified-after-sync");
   });
 
@@ -166,7 +185,7 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/meetings/"],
+      prospectivePrefixSet: ["meetings/"],
       journal: journalFromFiles([
         { rel: a.rel, contents: "a" },
         { rel: b.rel, contents: "b" },
@@ -175,15 +194,15 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     });
 
     const stayingPaths = plan.staying.map((f) => f.relPath).sort();
-    expect(stayingPaths).toEqual([a.rel, b.rel].sort());
-    expect(plan.clean.map((f) => f.relPath)).toEqual([c.rel]);
+    expect(stayingPaths).toEqual([key(a.rel), key(b.rel)].sort());
+    expect(plan.clean.map((f) => f.relPath)).toEqual([key(c.rel)]);
   });
 
   it("returns an empty plan when the company folder is missing", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "ghost",
-      prospectivePrefixSet: ["companies/ghost/"],
+      prospectivePrefixSet: [""],
       journal: journalFromFiles([]),
     });
     expect(plan.totalStayingCount).toBe(0);
@@ -214,7 +233,8 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     const plan = buildNarrowPlan({
       hqRoot: tmpRoot,
       companySlug: "acme",
-      prospectivePrefixSet: ["companies/acme/"],
+      // Empty-string prefix = "covers everything" per isCoveredByAny.
+      prospectivePrefixSet: [""],
       journal: journalFromFiles([]),
     });
     expect(plan.totalStayingCount).toBe(2);
@@ -223,7 +243,7 @@ describe("buildNarrowPlan — partition by prefix coverage", () => {
     // both are staying, regardless of journal state
     expect(
       plan.staying.map((f) => f.relPath).sort(),
-    ).toEqual([a.rel, b.rel].sort());
+    ).toEqual([key(a.rel), key(b.rel)].sort());
   });
 });
 

package/src/lib/local-tree-diff.ts

@@ -43,7 +43,11 @@ export type DirtyReason =
   | "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;
@@ -79,7 +83,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[];
   /**
@@ -120,7 +125,16 @@ export function buildNarrowPlan(input: BuildNarrowPlanInput): NarrowPlan {
     return emptyPlan();
   }
 
-  walkLocal(walkRoot, hqRoot, (file) => {
+  // Walk with `walkRoot` as the rel-root so each file's `relPath` is
+  // COMPANY-RELATIVE (e.g. `meetings/a.md`) — the same namespace as the
+  // server's explicit-grant paths, the per-company journal keys, and the
+  // hq-cloud sync engine's `RemoteFile.key`. Computing it relative to `hqRoot`
+  // (the old behavior) produced `companies/<slug>/meetings/a.md`, which
+  // matched neither the company-relative grants nor the journal keys — so
+  // every file fell out of `prospectivePrefixSet` AND missed its journal
+  // entry, making narrow flag the entire tree as dirty orphans. See the
+  // namespace contract in hq-cloud `scope-shrink.ts` / `prefix-coalesce.ts`.
+  walkLocal(walkRoot, walkRoot, (file) => {
     if (isCoveredByAny(file.relPath, prospectivePrefixSet)) {
       staying.push(file);
       return;
@@ -170,7 +184,9 @@ function emptyPlan(): NarrowPlan {
  */
 function walkLocal(
   dir: string,
-  hqRoot: string,
+  // Rel-root for `relPath` — the company walk root (`<hqRoot>/companies/<slug>`),
+  // so emitted `relPath`s are company-relative. Fixed across recursion.
+  relRoot: string,
   emit: (file: NarrowFile) => void,
 ): void {
   let entries: fs.Dirent[];
@@ -186,7 +202,7 @@ function walkLocal(
 
   for (const entry of entries) {
     const absPath = path.join(dir, entry.name);
-    const relPath = path.relative(hqRoot, absPath);
+    const relPath = path.relative(relRoot, absPath);
 
     if (entry.isSymbolicLink()) {
       // Record the link as a file-like entry. Don't descend — narrow is
@@ -204,7 +220,7 @@ function walkLocal(
     }
 
     if (entry.isDirectory()) {
-      walkLocal(absPath, hqRoot, emit);
+      walkLocal(absPath, relRoot, emit);
       continue;
     }