@indigoai-us/hq-cli 5.26.0 → 5.29.0

package/src/commands/files-browse.ts

@@ -17,16 +17,21 @@
  *                 `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";
@@ -46,7 +51,7 @@ import {
 
 import {
   VaultClient,
-  type VendResult,
+  grantPathToPrefix,
   type ExplicitGrant,
 } from "@indigoai-us/hq-cloud";
 
@@ -61,17 +66,40 @@ import { resolveCanonicalPersonUid } from "./cloud.js";
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+/** 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<{ uid: string; slug: string; name?: string; bucketName?: string }>;
@@ -138,20 +166,48 @@ export 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 function toBucketRelative(pathOrPrefix: string, slug: string): string {
+  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: string, slug: string): string {
+  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: string,
-  grants: ExplicitGrant[],
+  bucketRelKey: string,
+  grantPrefixes: string[],
 ): AclSource {
-  for (const g of grants) {
-    if (g.path && key.startsWith(g.path)) return "shared-with-you";
+  for (const p of grantPrefixes) {
+    if (p === "" || bucketRelKey.startsWith(p)) return "shared-with-you";
   }
   return "role-bypass";
 }
@@ -242,7 +298,7 @@ export interface RunBrowseInput {
 
 export interface RunBrowseResult {
   rows: BrowseRow[];
-  vend: VendResult;
+  vend: BrowseVendResult;
 }
 
 /**
@@ -250,8 +306,10 @@ export interface RunBrowseResult {
  *
  *   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.
@@ -262,10 +320,11 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
   // 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: string;
   let entityUid: string;
+  let slug: string | undefined;
+  let vend: BrowseVendResult;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -281,8 +340,9 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     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(
@@ -296,19 +356,12 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     }
     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: {
@@ -318,13 +371,25 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     },
   });
 
+  // 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
-    ? ([] as ExplicitGrant[])
-    : await vaultClient.listMyExplicitGrants(entityUid);
+  // 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)).map((g) =>
+          grantPathToPrefix(g.path, slug as string),
+        );
 
   const rows: BrowseRow[] = [];
   let continuationToken: string | undefined;
@@ -332,7 +397,7 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
     const resp = (await s3.send(
       new ListObjectsV2Command({
         Bucket: bucket,
-        Prefix: pathPrefix,
+        Prefix: listPrefix,
         ContinuationToken: continuationToken,
       }),
     )) as ListObjectsV2CommandOutput;
@@ -342,11 +407,18 @@ export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult>
       // 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),
       });
     }
 
@@ -384,7 +456,7 @@ export interface RunCatInput {
 export interface RunCatResult {
   bytesWritten: number;
   destination: { kind: "stdout" } | { kind: "file"; absPath: string };
-  vend: VendResult;
+  vend: BrowseVendResult;
 }
 
 /**
@@ -405,6 +477,8 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   // Same branch logic as runBrowse — see that function's doc-block for
   // the personal-vs-company rationale.
   let bucket: string;
+  let s3Key: string;
+  let vend: BrowseVendResult;
   if (personalMode) {
     if (!input.personalUid) {
       throw new Error(
@@ -419,6 +493,8 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
       );
     }
     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);
     const entity = await vaultClient.entity.findInMyNamespace("company", slug);
@@ -433,14 +509,11 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
       );
     }
     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: {
@@ -451,7 +524,7 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   });
 
   const resp = (await s3.send(
-    new GetObjectCommand({ Bucket: bucket, Key: key }),
+    new GetObjectCommand({ Bucket: bucket, Key: s3Key }),
   )) as GetObjectCommandOutput;
 
   if (!resp.Body) {
@@ -484,6 +557,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 +928,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({