@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/files-browse.ts

@@ -1,1506 +0,0 @@
-/**
- * `hq files browse <path>` + `hq files cat <path> [--out <file>]` (US-008).
- *
- * Peek at a company's vault files **without** ever materialising them under
- * `companies/{co}/` in the local HQ tree. Distinct from the sync path:
- *
- *   - `browse`  — `ListObjectsV2` under the given prefix, prints
- *                 `{key, size, lastModified, aclSource}` rows. The
- *                 `aclSource` hint distinguishes prefixes the caller can
- *                 see via an EXPLICIT grant (`shared-with-you`) from
- *                 prefixes they can see only because owner/admin
- *                 role-bypass widened the vended policy (`role-bypass`).
- *   - `cat`     — `GetObject`, stream the body to stdout. With `--out
- *                 <file>` write the body to a path the user picked, but
- *                 only after a bright-line guard refuses any destination
- *                 inside `<hqRoot>/companies/` — that's the exact tree
- *                 `hq sync` owns, and writing a peeked object there would
- *                 silently re-import it into the sync envelope.
- *
- * 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`).
- *
- * 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 chalk from "chalk";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-
-import {
-  S3Client,
-  ListObjectsV2Command,
-  GetObjectCommand,
-  type ListObjectsV2CommandOutput,
-  type GetObjectCommandOutput,
-} from "@aws-sdk/client-s3";
-
-import {
-  VaultClient,
-  grantPathToPrefix,
-  type ExplicitGrant,
-} from "@indigoai-us/hq-cloud";
-
-import {
-  DEFAULT_HQ_ROOT,
-  DEFAULT_COGNITO,
-  ensureCognitoToken,
-  buildVaultConfig,
-} from "../utils/cognito-session.js";
-import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-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 {
-  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 }>;
-    findInMyNamespace(
-      type: string,
-      slug: string,
-    ): Promise<{ uid: string; slug: string; name?: string; bucketName?: string } | null>;
-  };
-}
-
-/** Subset of `S3Client` this command actually uses — for test stubs. */
-export interface FilesBrowseS3Client {
-  send(
-    cmd: ListObjectsV2Command,
-  ): Promise<ListObjectsV2CommandOutput>;
-  send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
-}
-
-/** Factory for an S3 client given vended credentials. Injectable for tests. */
-export type S3ClientFactory = (input: {
-  region: string;
-  credentials: {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken: string;
-  };
-}) => FilesBrowseS3Client;
-
-/**
- * Factory for the COMPANY-mode browse client. Injectable for tests; the
- * production implementation is `createCompanyPresignClient`. Keyed by
- * `companyUid` (resolved by the orchestrator) — the access token is captured
- * by the closure at the CLI layer.
- */
-export type CompanyBrowseClientFactory = (input: {
-  companyUid: string;
-}) => FilesBrowseS3Client;
-
-/**
- * ACL provenance for a single listed key.
- *   - `shared-with-you`: an explicit grant the caller holds covers the key.
- *   - `role-bypass`: the caller has no covering explicit grant, but
- *      owner/admin role widened the browse-vend policy to include it.
- *   - `personal-vault`: the key lives in the caller's own person-entity
- *      vault, where no grants graph applies — the caller is the only
- *      principal with access by construction. Emitted only when
- *      `runBrowse({ personalMode: true })`.
- */
-export type AclSource = "shared-with-you" | "role-bypass" | "personal-vault";
-
-export interface BrowseRow {
-  key: string;
-  size: number;
-  lastModified: Date | undefined;
-  aclSource: AclSource;
-}
-
-// ── Pure helpers ────────────────────────────────────────────────────────────
-
-/**
- * Parse the company slug from a vault prefix. Vault paths are anchored at
- * `companies/<slug>/...`; anything else is rejected so we never try to
- * browse a non-company tree (e.g. `personal/`) with a company-vend.
- */
-export function parseCompanySlugFromPath(prefix: string): string {
-  const normalized = prefix.replace(/^\/+/, "");
-  const parts = normalized.split("/");
-  if (parts.length < 2 || parts[0] !== "companies" || !parts[1]) {
-    throw new Error(
-      `Invalid browse path '${prefix}'. Expected a path starting with 'companies/<slug>/'.`,
-    );
-  }
-  return parts[1];
-}
-
-/**
- * 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 `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(
-  bucketRelKey: string,
-  grantPrefixes: string[],
-): AclSource {
-  for (const p of grantPrefixes) {
-    if (p === "" || bucketRelKey.startsWith(p)) return "shared-with-you";
-  }
-  return "role-bypass";
-}
-
-/**
- * Bright-line guard for `--out`: refuse to write any byte beneath
- * `<hqRoot>/companies/`. We do NOT enumerate `companies/manifest.yaml`
- * slug-by-slug — `companies/` is the entire surface hq-sync owns, so a
- * containment check on that parent suffices and avoids drift with the
- * manifest file. Returns the resolved absolute output path on success;
- * throws when the destination would land inside the protected tree.
- */
-export function assertOutPathOutsideCompanies(
-  outPath: string,
-  hqRoot: string,
-): string {
-  const absOut = path.resolve(outPath);
-  const protectedRoot = path.resolve(hqRoot, "companies") + path.sep;
-  if (absOut === path.resolve(hqRoot, "companies") || absOut.startsWith(protectedRoot)) {
-    throw new Error(
-      `Refusing to write '${absOut}': bytes peeked via 'hq files cat' must not land under ` +
-        `'${path.resolve(hqRoot, "companies")}'. Pick an --out path outside the HQ companies tree.`,
-    );
-  }
-  return absOut;
-}
-
-/**
- * Render a browse listing as a padded table. Mirrors the chalk + padEnd
- * pattern used by `hq sync mode --show` so the CLI surface stays
- * stylistically consistent.
- */
-export function formatBrowseTable(rows: BrowseRow[]): string {
-  if (rows.length === 0) {
-    return "No objects under that prefix.";
-  }
-  const cols = ["KEY", "SIZE", "MODIFIED", "ACL"];
-  const data = rows.map((r) => [
-    r.key,
-    String(r.size),
-    r.lastModified ? r.lastModified.toISOString() : "—",
-    r.aclSource,
-  ]);
-  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("  ");
-  const lines = [
-    chalk.bold(renderRow(cols)),
-    chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
-    ...data.map(renderRow),
-  ];
-  return lines.join("\n");
-}
-
-// ── Orchestrators ───────────────────────────────────────────────────────────
-
-export interface RunBrowseInput {
-  /**
-   * Vault path prefix.
-   *   - Company mode (`personalMode: false | undefined`): must start with
-   *     `companies/<slug>/`, e.g. `companies/indigo/scratch/`.
-   *   - Personal mode (`personalMode: true`): bucket-relative; empty string
-   *     lists the whole personal vault root.
-   */
-  pathPrefix: string;
-  /** Caller-overridden company slug (defaults to slug parsed from path). Ignored under `personalMode`. */
-  companySlug?: string;
-  /**
-   * Personal-vault mode. Skips the `companies/<slug>/` path requirement,
-   * resolves the entity via `entity.get(personalUid)` instead of the
-   * company namespace, omits the explicit-grants fetch (no grants graph
-   * on a person bucket), and marks every row's `aclSource` as
-   * `"personal-vault"`. Closes hq-cli#26 (audit gap for personal vault).
-   */
-  personalMode?: boolean;
-  /**
-   * Canonical person-entity UID (e.g. `prs_…`). Required when
-   * `personalMode: true`; ignored otherwise. Caller resolves via
-   * `resolveCanonicalPersonUid` to keep this orchestrator pure.
-   */
-  personalUid?: string;
-  vaultClient: FilesBrowseVaultClient;
-  /** PERSONAL mode: builds a direct-S3 client from vended creds. */
-  s3Factory?: S3ClientFactory;
-  /**
-   * COMPANY mode (HQ-59): builds the presign/list-backed client. Company
-   * browse no longer talks to S3 directly and does not vend STS creds.
-   */
-  companyClient?: CompanyBrowseClientFactory;
-  region: string;
-}
-
-export interface RunBrowseResult {
-  rows: BrowseRow[];
-  /**
-   * Present ONLY for the PERSONAL (vendSelf + direct S3) path. Company mode
-   * goes through the presign/list API and does not vend, so this is undefined
-   * there.
-   */
-  vend?: BrowseVendResult;
-}
-
-/** Guard: the personal path needs an S3 factory. */
-function requirePersonalS3Factory(f?: S3ClientFactory): S3ClientFactory {
-  if (!f) {
-    throw new Error(
-      "Personal-vault browse requires an s3Factory (direct-S3 client).",
-    );
-  }
-  return f;
-}
-
-/** Guard: the company path needs the presign/list client factory. */
-function requireCompanyClient(
-  f?: CompanyBrowseClientFactory,
-): CompanyBrowseClientFactory {
-  if (!f) {
-    throw new Error(
-      "Company browse requires a companyClient (presign/list client).",
-    );
-  }
-  return f;
-}
-
-/**
- * `hq files browse <path>` orchestrator.
- *
- *   1. Parse slug from prefix (or use override).
- *   2. Resolve companyUid + bucketName via VaultClient.entity.
- *   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.
- */
-export async function runBrowse(input: RunBrowseInput): Promise<RunBrowseResult> {
-  const { pathPrefix, vaultClient, region, personalMode } = input;
-
-  // Branch by mode. Company mode parses slug from path and looks up by
-  // namespace; personal mode resolves the entity directly by the supplied
-  // person UID and skips the slug + grants machinery (a person bucket has
-  // no grants graph — the owner is the only principal).
-  let bucket: string;
-  let entityUid: string;
-  let slug: string | undefined;
-  let vend: BrowseVendResult | undefined;
-  let s3: FilesBrowseS3Client;
-  if (personalMode) {
-    if (!input.personalUid) {
-      throw new Error(
-        "runBrowse: personalMode requires personalUid. Resolve via " +
-          "resolveCanonicalPersonUid() before calling.",
-      );
-    }
-    const entity = await vaultClient.entity.get(input.personalUid);
-    if (!entity.bucketName) {
-      throw new Error(
-        `Personal entity '${input.personalUid}' has no provisioned bucket.`,
-      );
-    }
-    entityUid = entity.uid;
-    bucket = entity.bucketName;
-    // Personal vault keeps the direct-S3 path: vend self creds, build an S3
-    // client. (HQ-59 scopes the migration to COMPANY mode.)
-    vend = await vaultClient.sts.vendSelf({ personUid: entityUid });
-    s3 = requirePersonalS3Factory(input.s3Factory)({
-      region,
-      credentials: {
-        accessKeyId: vend.credentials.accessKeyId,
-        secretAccessKey: vend.credentials.secretAccessKey,
-        sessionToken: vend.credentials.sessionToken,
-      },
-    });
-  } else {
-    slug = input.companySlug ?? parseCompanySlugFromPath(pathPrefix);
-    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-    if (!entity) {
-      throw new Error(
-        `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
-      );
-    }
-    if (!entity.bucketName) {
-      throw new Error(
-        `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
-      );
-    }
-    entityUid = entity.uid;
-    bucket = entity.bucketName;
-    // COMPANY mode (HQ-59): list/get go through the presign/list API, which
-    // enforces the same per-file ACLs server-side. No STS vend, no direct S3.
-    s3 = requireCompanyClient(input.companyClient)({ companyUid: entityUid });
-  }
-
-  // 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. 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;
-  do {
-    const resp = (await s3.send(
-      new ListObjectsV2Command({
-        Bucket: bucket,
-        Prefix: listPrefix,
-        ContinuationToken: continuationToken,
-      }),
-    )) as ListObjectsV2CommandOutput;
-
-    for (const obj of resp.Contents ?? []) {
-      if (!obj.Key) continue;
-      // 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:
-          personalMode || slug === undefined
-            ? obj.Key
-            : toCompanyAnchored(obj.Key, slug),
-        size: obj.Size ?? 0,
-        lastModified: obj.LastModified,
-        aclSource: personalMode
-          ? "personal-vault"
-          : classifyAclSource(obj.Key, grantPrefixes),
-      });
-    }
-
-    continuationToken = resp.NextContinuationToken ?? undefined;
-  } while (continuationToken);
-
-  return { rows, vend };
-}
-
-export interface RunCatInput {
-  /**
-   * Single vault key.
-   *   - Company mode: must be a `companies/<slug>/...` path.
-   *   - Personal mode: bucket-relative, e.g. `.claude/CLAUDE.md`.
-   */
-  key: string;
-  /**
-   * Where to write the body. `undefined` ⇒ stdout. Bright-line-guarded
-   * against `<hqRoot>/companies/` by `assertOutPathOutsideCompanies`.
-   */
-  out?: string;
-  hqRoot: string;
-  companySlug?: string;
-  /** Personal-vault mode — see `RunBrowseInput.personalMode`. */
-  personalMode?: boolean;
-  /** Canonical person-entity UID; required when `personalMode: true`. */
-  personalUid?: string;
-  vaultClient: FilesBrowseVaultClient;
-  /** PERSONAL mode: builds a direct-S3 client from vended creds. */
-  s3Factory?: S3ClientFactory;
-  /** COMPANY mode (HQ-59): builds the presign/list-backed client. */
-  companyClient?: CompanyBrowseClientFactory;
-  region: string;
-  /** Destination stream for the stdout path. Injectable for tests. */
-  stdout?: NodeJS.WritableStream;
-}
-
-export interface RunCatResult {
-  bytesWritten: number;
-  destination: { kind: "stdout" } | { kind: "file"; absPath: string };
-  /** Present ONLY for the PERSONAL (vendSelf + direct S3) path. */
-  vend?: BrowseVendResult;
-}
-
-/**
- * `hq files cat <path>` orchestrator. Vends with `purpose: 'browse'`, then
- * streams the object body either to stdout or to `--out` (after the
- * containment guard). Refuses ahead of any I/O when `--out` is unsafe.
- */
-export async function runCat(input: RunCatInput): Promise<RunCatResult> {
-  const { key, vaultClient, region, hqRoot, personalMode } = input;
-
-  // Acceptance 5: refuse BEFORE vending — no point pulling credentials
-  // for a request we're already going to abort.
-  let absOut: string | undefined;
-  if (input.out !== undefined) {
-    absOut = assertOutPathOutsideCompanies(input.out, hqRoot);
-  }
-
-  // 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 | undefined;
-  let s3: FilesBrowseS3Client;
-  if (personalMode) {
-    if (!input.personalUid) {
-      throw new Error(
-        "runCat: personalMode requires personalUid. Resolve via " +
-          "resolveCanonicalPersonUid() before calling.",
-      );
-    }
-    const entity = await vaultClient.entity.get(input.personalUid);
-    if (!entity.bucketName) {
-      throw new Error(
-        `Personal entity '${input.personalUid}' has no provisioned bucket.`,
-      );
-    }
-    bucket = entity.bucketName;
-    s3Key = key; // personal-mode keys are already bucket-relative
-    vend = await vaultClient.sts.vendSelf({ personUid: entity.uid });
-    s3 = requirePersonalS3Factory(input.s3Factory)({
-      region,
-      credentials: {
-        accessKeyId: vend.credentials.accessKeyId,
-        secretAccessKey: vend.credentials.secretAccessKey,
-        sessionToken: vend.credentials.sessionToken,
-      },
-    });
-  } else {
-    const slug = input.companySlug ?? parseCompanySlugFromPath(key);
-    const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-    if (!entity) {
-      throw new Error(
-        `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
-      );
-    }
-    if (!entity.bucketName) {
-      throw new Error(
-        `Company '${slug}' (${entity.uid}) has no provisioned bucket.`,
-      );
-    }
-    bucket = entity.bucketName;
-    // Translate the anchored CLI key into the company-relative bucket key.
-    s3Key = toBucketRelative(key, slug);
-    // COMPANY mode (HQ-59): GetObject → presign GET. No STS vend, no direct S3.
-    s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
-  }
-
-  const resp = (await s3.send(
-    new GetObjectCommand({ Bucket: bucket, Key: s3Key }),
-  )) as GetObjectCommandOutput;
-
-  if (!resp.Body) {
-    throw new Error(`GetObject for '${key}' returned no body.`);
-  }
-
-  // The SDK Body type in node is a Readable (it can also be a
-  // ReadableStream/Blob in other runtimes but those don't apply to the
-  // CLI). Cast through unknown so the type checker accepts the narrowing.
-  const body = resp.Body as unknown as Readable;
-  let bytesWritten = 0;
-  body.on("data", (chunk: Buffer | string) => {
-    bytesWritten += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
-  });
-
-  if (absOut !== undefined) {
-    // Ensure the parent directory exists — but ONLY if it's also outside
-    // the protected tree (the guard already validated absOut itself; the
-    // parent of an outside-tree path is by definition outside too).
-    fs.mkdirSync(path.dirname(absOut), { recursive: true });
-    await pipeline(body, fs.createWriteStream(absOut));
-    return {
-      bytesWritten,
-      destination: { kind: "file", absPath: absOut },
-      vend,
-    };
-  }
-
-  await pipeline(body, input.stdout ?? process.stdout);
-  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");
-}
-
-// ── search ───────────────────────────────────────────────────────────────
-
-export interface RunSearchInput {
-  /** Case-insensitive substring matched against each object's full key. */
-  query: string;
-  /** Company slug to search (ignored under personalMode). */
-  companySlug: string;
-  personalMode?: boolean;
-  personalUid?: string;
-  vaultClient: FilesBrowseVaultClient;
-  /** PERSONAL mode: direct-S3 client factory. */
-  s3Factory?: S3ClientFactory;
-  /** COMPANY mode (HQ-59): presign/list client factory. */
-  companyClient?: CompanyBrowseClientFactory;
-  region: string;
-}
-
-/**
- * `hq files search <query>` orchestrator. Lists the company (or personal)
- * vault under its root via `runBrowse`, then filters to keys containing the
- * query (case-insensitive). v1 is a name/path search over the listing — no
- * content search. Rows carry the same ACL-source classification as browse.
- *
- * Pure-ish: no console output. The caller renders with `formatBrowseTable`.
- */
-export async function runSearch(input: RunSearchInput): Promise<BrowseRow[]> {
-  const prefix = input.personalMode ? "" : `companies/${input.companySlug}/`;
-  const { rows } = await runBrowse({
-    pathPrefix: prefix,
-    companySlug: input.companySlug,
-    personalMode: input.personalMode,
-    personalUid: input.personalUid,
-    vaultClient: input.vaultClient,
-    s3Factory: input.s3Factory,
-    companyClient: input.companyClient,
-    region: input.region,
-  });
-  const q = input.query.toLowerCase();
-  return rows.filter((r) => r.key.toLowerCase().includes(q));
-}
-
-// ── get (materialize + pin) ─────────────────────────────────────────────────
-
-interface PinFile {
-  version: number;
-  /** companySlug → sorted list of company-relative pinned prefixes. */
-  pins: Record<string, string[]>;
-}
-
-/** Per-machine pin set path: `<hqRoot>/.hq/pins.json`. */
-export function pinFilePath(hqRoot: string): string {
-  return path.join(hqRoot, ".hq", "pins.json");
-}
-
-/** Read the pin set, tolerating a missing or corrupt file (→ fresh). */
-export function readPins(hqRoot: string): PinFile {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(pinFilePath(hqRoot), "utf-8"));
-    if (parsed && typeof parsed === "object" && parsed.pins) {
-      return { version: parsed.version ?? 1, pins: parsed.pins };
-    }
-  } catch {
-    /* missing / unreadable / malformed → start fresh */
-  }
-  return { version: 1, pins: {} };
-}
-
-/**
- * Register a company-relative prefix in the per-machine pin set. Pins are what
- * keep an on-demand `hq files get` from being pruned by the next *scoped*
- * sync (`syncMode: shared|custom`): the sync runner unions the company's pins
- * into its pull scope. Idempotent + sorted for stable diffs.
- */
-export function addPin(hqRoot: string, companySlug: string, prefix: string): void {
-  const pf = readPins(hqRoot);
-  const list = pf.pins[companySlug] ?? [];
-  if (!list.includes(prefix)) list.push(prefix);
-  list.sort();
-  pf.pins[companySlug] = list;
-  const f = pinFilePath(hqRoot);
-  fs.mkdirSync(path.dirname(f), { recursive: true });
-  fs.writeFileSync(f, JSON.stringify(pf, null, 2) + "\n");
-}
-
-export interface RunGetInput {
-  /** Vault path to materialize: `companies/<slug>/...` (file or prefix). */
-  path: string;
-  /**
-   * Override destination directory. Default (omitted) writes in place under
-   * `<hqRoot>/companies/<slug>/...` — the tree `hq sync` manages — and
-   * registers a pin. `--into` writes outside that envelope and pins nothing.
-   */
-  into?: string;
-  hqRoot: string;
-  companySlug?: string;
-  vaultClient: FilesBrowseVaultClient;
-  /**
-   * COMPANY mode (HQ-59): presign/list client factory. `get` is company-only,
-   * so it always goes through the API — no direct S3, no STS vend.
-   */
-  companyClient?: CompanyBrowseClientFactory;
-  region: string;
-}
-
-export interface RunGetResult {
-  filesWritten: number;
-  bytesWritten: number;
-  destinations: string[];
-  /** Set only for in-place (no `--into`) materialization. */
-  pinned?: { companySlug: string; prefix: string };
-}
-
-/**
- * `hq files get <path>` orchestrator. Materializes a vault file or prefix into
- * the local HQ tree on demand. Unlike `cat` (which refuses to write under
- * `companies/`), `get` deliberately writes INTO `companies/<slug>/...` by
- * default — that's the point: pull a path you have access to but don't sync.
- * It then registers a pin so the next scoped sync keeps it.
- *
- * Company mode only in v1 — materializing a personal vault would target the
- * HQ root itself, which is too broad to do implicitly.
- */
-export async function runGet(input: RunGetInput): Promise<RunGetResult> {
-  const { path: vaultPath, vaultClient, hqRoot } = input;
-  const slug = input.companySlug ?? parseCompanySlugFromPath(vaultPath);
-
-  const entity = await vaultClient.entity.findInMyNamespace("company", slug);
-  if (!entity) {
-    throw new Error(
-      `No company found for slug '${slug}' in your namespace. Confirm you have an active membership.`,
-    );
-  }
-  if (!entity.bucketName) {
-    throw new Error(`Company '${slug}' (${entity.uid}) has no provisioned bucket.`);
-  }
-  const bucket = entity.bucketName;
-  // COMPANY mode (HQ-59): list + get through the presign/list API. No STS vend,
-  // no direct S3 — the server enforces the same per-file read ACLs.
-  const s3 = requireCompanyClient(input.companyClient)({ companyUid: entity.uid });
-
-  // Company-relative prefix to list/fetch (bucket keys carry no anchor).
-  const bucketPrefix = toBucketRelative(vaultPath, slug);
-
-  const keys: string[] = [];
-  let continuationToken: string | undefined;
-  do {
-    const resp = (await s3.send(
-      new ListObjectsV2Command({
-        Bucket: bucket,
-        Prefix: bucketPrefix,
-        ContinuationToken: continuationToken,
-      }),
-    )) as ListObjectsV2CommandOutput;
-    for (const obj of resp.Contents ?? []) {
-      if (!obj.Key) continue;
-      if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0) continue;
-      keys.push(obj.Key);
-    }
-    continuationToken = resp.NextContinuationToken ?? undefined;
-  } while (continuationToken);
-
-  if (keys.length === 0) {
-    throw new Error(`No objects under '${vaultPath}'.`);
-  }
-
-  const destinations: string[] = [];
-  let bytesWritten = 0;
-  for (const key of keys) {
-    // Default: in-place under companies/<slug>/<company-relative key>.
-    // --into: write the path relative to the requested prefix under <into>.
-    let destAbs: string;
-    if (input.into !== undefined) {
-      const rel = key.startsWith(bucketPrefix)
-        ? key.slice(bucketPrefix.length)
-        : key;
-      destAbs = path.resolve(input.into, rel || path.basename(key));
-    } else {
-      destAbs = path.join(hqRoot, "companies", slug, key);
-    }
-    const resp = (await s3.send(
-      new GetObjectCommand({ Bucket: bucket, Key: key }),
-    )) as GetObjectCommandOutput;
-    if (!resp.Body) {
-      throw new Error(`GetObject for '${key}' returned no body.`);
-    }
-    const body = resp.Body as unknown as Readable;
-    fs.mkdirSync(path.dirname(destAbs), { recursive: true });
-    await pipeline(body, fs.createWriteStream(destAbs));
-    bytesWritten += fs.statSync(destAbs).size;
-    destinations.push(destAbs);
-  }
-
-  // Pin only the in-place case — `--into` writes outside the sync envelope, so
-  // there's nothing for a scoped sync to prune.
-  let pinned: RunGetResult["pinned"];
-  if (input.into === undefined) {
-    addPin(hqRoot, slug, bucketPrefix);
-    pinned = { companySlug: slug, prefix: bucketPrefix };
-  }
-
-  return { filesWritten: keys.length, bytesWritten, destinations, pinned };
-}
-
-// ── CLI registration ────────────────────────────────────────────────────────
-
-const defaultS3Factory: S3ClientFactory = ({ region, credentials }) =>
-  new S3Client({ region, credentials });
-
-// ── Company-mode presign/list client (HQ-59) ────────────────────────────────
-//
-// The COMPANY browse/cat/get/search path no longer talks to S3 directly. Per
-// the HQ-59 directive ("no client talks to S3 directly"), it goes through the
-// server-side vault API, which enforces the SAME per-file ACLs the STS vend
-// policy used to — so the per-file STS scoping can be dropped later:
-//   - ListObjectsV2  → GET  /v1/files/list  (flat, ACL-filtered, paginated)
-//   - GetObject      → POST /v1/files/presign (op:'get') → fetch the URL
-//
-// It implements the existing `FilesBrowseS3Client` interface so the
-// orchestrators' S3-shaped calls are unchanged; the `Bucket` field on each
-// command is ignored (the server resolves the bucket from the companyUid).
-// The PERSONAL (vendSelf) path keeps using direct S3 via `defaultS3Factory`.
-
-/** Shape of one object in a GET /v1/files/list response. */
-interface FilesListObject {
-  key: string;
-  size: number;
-  lastModified: string | null;
-  etag: string | null;
-  permission: string;
-}
-
-/**
- * Build a COMPANY-mode browse client backed by the list + presign API. The
- * access token + companyUid are captured here; the orchestrator just calls
- * `send(...)` as if it held an S3 client.
- */
-export function createCompanyPresignClient(input: {
-  token: string;
-  companyUid: string;
-}): FilesBrowseS3Client {
-  const { token, companyUid } = input;
-
-  async function listObjects(
-    cmd: ListObjectsV2Command,
-  ): Promise<ListObjectsV2CommandOutput> {
-    const prefix = cmd.input.Prefix ?? "";
-    const query: Record<string, string> = { company: companyUid };
-    if (prefix.length > 0) query.prefix = prefix;
-    if (cmd.input.ContinuationToken) query.cursor = cmd.input.ContinuationToken;
-
-    const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
-    if (!res.ok) {
-      const body = (await res.json().catch(() => ({}))) as Record<string, string>;
-      throw new Error(
-        body.message ?? body.error ?? `files list failed (${res.status})`,
-      );
-    }
-    const body = (await res.json()) as {
-      objects?: FilesListObject[];
-      cursor?: string | null;
-      truncated?: boolean;
-    };
-    return {
-      // Map the API's company-relative objects onto the ListObjectsV2 shape the
-      // orchestrators read (Key / Size / LastModified / ETag). Re-quote the
-      // etag to match S3's quoted form, in case any caller compares it.
-      Contents: (body.objects ?? []).map((o) => ({
-        Key: o.key,
-        Size: o.size,
-        LastModified: o.lastModified ? new Date(o.lastModified) : undefined,
-        ETag: o.etag != null ? `"${o.etag}"` : undefined,
-      })),
-      NextContinuationToken: body.cursor ?? undefined,
-      IsTruncated: Boolean(body.truncated),
-      // $metadata is required by the SDK output type; the orchestrators never
-      // read it, so a minimal stub is sufficient.
-      $metadata: {},
-    } as ListObjectsV2CommandOutput;
-  }
-
-  async function getObject(
-    cmd: GetObjectCommand,
-  ): Promise<GetObjectCommandOutput> {
-    const key = cmd.input.Key as string;
-    const res = await vaultApiFetch({
-      token,
-      path: "/v1/files/presign",
-      method: "POST",
-      body: { company: companyUid, key, op: "get" },
-    });
-    if (!res.ok) {
-      const body = (await res.json().catch(() => ({}))) as Record<string, string>;
-      throw new Error(
-        body.message ?? body.error ?? `presign failed (${res.status})`,
-      );
-    }
-    const body = (await res.json()) as {
-      results?: Array<{ key: string; url?: string; error?: string; code?: string }>;
-    };
-    const first = body.results?.[0];
-    if (!first || !first.url) {
-      // Per-key denial/validation surfaces here (e.g. FILES_PRESIGN_FORBIDDEN).
-      throw new Error(first?.error ?? `No presigned URL returned for '${key}'`);
-    }
-
-    const dl = await fetch(first.url);
-    if (!dl.ok) {
-      throw new Error(`Failed to download '${key}' (HTTP ${dl.status})`);
-    }
-    // fetch() yields a web ReadableStream; the orchestrators consume Body as a
-    // Node Readable (body.on('data') + stream pipeline), so adapt it. An empty
-    // body (no stream) becomes an empty Readable.
-    const nodeBody = dl.body
-      ? Readable.fromWeb(dl.body as Parameters<typeof Readable.fromWeb>[0])
-      : Readable.from([]);
-    return { Body: nodeBody, $metadata: {} } as unknown as GetObjectCommandOutput;
-  }
-
-  function send(cmd: ListObjectsV2Command): Promise<ListObjectsV2CommandOutput>;
-  function send(cmd: GetObjectCommand): Promise<GetObjectCommandOutput>;
-  function send(
-    cmd: ListObjectsV2Command | GetObjectCommand,
-  ): Promise<ListObjectsV2CommandOutput | GetObjectCommandOutput> {
-    if (cmd instanceof ListObjectsV2Command) return listObjects(cmd);
-    if (cmd instanceof GetObjectCommand) return getObject(cmd);
-    throw new Error("createCompanyPresignClient: unsupported S3 command");
-  }
-
-  return { send };
-}
-
-/** Production company-mode client factory — closes over the caller's token. */
-function makeCompanyPresignFactory(token: string): CompanyBrowseClientFactory {
-  return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
-}
-
-interface FilesBrowseCliOptions {
-  company?: string;
-  hqRoot: string;
-  /**
-   * Personal-vault mode (hq-cli#26). Skips the `companies/<slug>/`
-   * requirement on the path arg, resolves the entity from the caller's
-   * canonical person UID, and emits rows tagged `personal-vault`.
-   * Mutually exclusive with `--company`.
-   */
-  personal?: boolean;
-}
-
-interface FilesCatCliOptions extends FilesBrowseCliOptions {
-  out?: string;
-}
-
-interface FilesSearchCliOptions {
-  company?: string;
-  personal?: boolean;
-}
-
-interface FilesGetCliOptions {
-  company?: string;
-  hqRoot: string;
-  into?: string;
-}
-
-/**
- * Wire `hq files browse` + `hq files cat` onto an existing `files`
- * Commander group. `registerFilesCommand` in files.ts builds the group
- * and registers `share`/`unshare`/`acl`; this function appends the two
- * new browse-vs-sync subcommands so they share the `--company` switch.
- */
-export function registerFilesBrowseCommands(filesCmd: Command): void {
-  filesCmd
-    .command("browse [path]")
-    .description(
-      "List vault objects under [path] without syncing them locally. Uses the browse-vend path (role-bypass allowed). Pass --personal to browse the caller's personal vault; otherwise [path] must start with companies/<slug>/.",
-    )
-    .option(
-      "--company <slug>",
-      "Company slug (defaults to the slug parsed from <path>)",
-    )
-    .option(
-      "--personal",
-      "Browse the caller's canonical personal vault. [path] is treated as " +
-        "bucket-relative (omit it to list the vault root). Mutually exclusive " +
-        "with --company.",
-    )
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (pathArg: string | undefined, options: FilesBrowseCliOptions, command: Command) => {
-      try {
-        // `--company` is declared on the parent `files` group, so commander
-        // binds it there — read merged opts to see it from the subcommand.
-        const company = command.optsWithGlobals().company as string | undefined;
-        if (options.personal && company) {
-          throw new Error(
-            "--personal and --company are mutually exclusive. Pick one.",
-          );
-        }
-
-        const accessToken = await ensureCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
-        const client = new VaultClient(vaultConfig);
-
-        if (options.personal) {
-          // Personal-vault path. Resolve the caller's canonical person
-          // entity once; the orchestrator does the bucket lookup + vend.
-          // Empty [path] → list bucket root.
-          const personalUid = await resolveCanonicalPersonUid({
-            listMyMemberships: () => client.listMyMemberships(),
-            listPersonEntities: () => client.entity.listByType("person"),
-            getEntity: async () => null,
-          });
-
-          const result = await runBrowse({
-            pathPrefix: pathArg ?? "",
-            personalMode: true,
-            personalUid,
-            vaultClient: client,
-            s3Factory: defaultS3Factory,
-            region: DEFAULT_COGNITO.region,
-          });
-
-          console.log(formatBrowseTable(result.rows));
-          return;
-        }
-
-        // Company path. [path] is required here — the slug parse needs it.
-        if (!pathArg) {
-          throw new Error(
-            "browse: [path] is required when --personal is not set. " +
-              "Pass a companies/<slug>/... path, or add --personal to " +
-              "browse your personal vault.",
-          );
-        }
-
-        // Resolve slug — CLI flag wins, otherwise parse from path arg.
-        const slug = company ?? parseCompanySlugFromPath(pathArg);
-
-        // If the user passed `--company` AND the path doesn't begin with
-        // companies/<that-slug>/, refuse — we'd otherwise vend creds for
-        // one company and list keys from another tree, which never makes
-        // sense (defense in depth against operator typos).
-        if (company !== undefined) {
-          const fromPath = (() => {
-            try {
-              return parseCompanySlugFromPath(pathArg);
-            } catch {
-              return undefined;
-            }
-          })();
-          if (fromPath && fromPath !== company) {
-            throw new Error(
-              `--company '${company}' disagrees with path slug '${fromPath}'.`,
-            );
-          }
-        }
-
-        // Confirm the slug resolves to a known membership — same pattern
-        // sync-mode/sync-narrow use to surface "you're not a member" early.
-        await getCompanyUid(accessToken, slug);
-
-        const result = await runBrowse({
-          pathPrefix: pathArg,
-          companySlug: slug,
-          vaultClient: client,
-          companyClient: makeCompanyPresignFactory(accessToken),
-          region: DEFAULT_COGNITO.region,
-        });
-
-        console.log(formatBrowseTable(result.rows));
-        if (result.rows.length > 0) {
-          const bypassCount = result.rows.filter(
-            (r) => r.aclSource === "role-bypass",
-          ).length;
-          if (bypassCount > 0) {
-            console.log("");
-            console.log(
-              chalk.yellow(
-                `Heads-up: ${bypassCount} object(s) visible only via role-bypass (no explicit grant covers them).`,
-              ),
-            );
-          }
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  filesCmd
-    .command("cat <path>")
-    .description(
-      "Stream a single vault object to stdout (or --out <file>) without syncing it. Uses the browse-vend path. Pass --personal to read from the caller's personal vault.",
-    )
-    .option(
-      "--out <file>",
-      "Write the object body to <file> instead of stdout. Refused under <hqRoot>/companies/.",
-    )
-    .option(
-      "--company <slug>",
-      "Company slug (defaults to the slug parsed from <path>)",
-    )
-    .option(
-      "--personal",
-      "Read from the caller's canonical personal vault. <path> is treated as " +
-        "bucket-relative. Mutually exclusive with --company.",
-    )
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (keyArg: string, options: FilesCatCliOptions, command: Command) => {
-      try {
-        // `--company` is bound on the parent `files` group — read merged opts.
-        const company = command.optsWithGlobals().company as string | undefined;
-        if (options.personal && company) {
-          throw new Error(
-            "--personal and --company are mutually exclusive. Pick one.",
-          );
-        }
-
-        const accessToken = await ensureCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
-        const client = new VaultClient(vaultConfig);
-
-        if (options.personal) {
-          const personalUid = await resolveCanonicalPersonUid({
-            listMyMemberships: () => client.listMyMemberships(),
-            listPersonEntities: () => client.entity.listByType("person"),
-            getEntity: async () => null,
-          });
-
-          const result = await runCat({
-            key: keyArg,
-            out: options.out,
-            hqRoot: options.hqRoot,
-            personalMode: true,
-            personalUid,
-            vaultClient: client,
-            s3Factory: defaultS3Factory,
-            region: DEFAULT_COGNITO.region,
-          });
-
-          if (result.destination.kind === "file") {
-            console.error(
-              chalk.green("✓"),
-              `Wrote ${result.bytesWritten} bytes to ${result.destination.absPath}`,
-            );
-          }
-          return;
-        }
-
-        const slug = company ?? parseCompanySlugFromPath(keyArg);
-        if (company !== undefined) {
-          const fromPath = (() => {
-            try {
-              return parseCompanySlugFromPath(keyArg);
-            } catch {
-              return undefined;
-            }
-          })();
-          if (fromPath && fromPath !== company) {
-            throw new Error(
-              `--company '${company}' disagrees with path slug '${fromPath}'.`,
-            );
-          }
-        }
-        await getCompanyUid(accessToken, slug);
-
-        const result = await runCat({
-          key: keyArg,
-          out: options.out,
-          hqRoot: options.hqRoot,
-          companySlug: slug,
-          vaultClient: client,
-          companyClient: makeCompanyPresignFactory(accessToken),
-          region: DEFAULT_COGNITO.region,
-        });
-
-        if (result.destination.kind === "file") {
-          console.error(
-            chalk.green("✓"),
-            `Wrote ${result.bytesWritten} bytes to ${result.destination.absPath}`,
-          );
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        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 }, command: Command) => {
-      try {
-        // `--company` is bound on the parent `files` group — read merged opts.
-        const company = command.optsWithGlobals().company as string | undefined;
-        const accessToken = await ensureCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
-        const client = new VaultClient(vaultConfig);
-
-        let companyUid: string | undefined;
-        if (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, company);
-        }
-
-        const rows = await runSharedWithMe({
-          vaultClient: client,
-          companyUid,
-          companySlug: company,
-        });
-
-        console.log(formatSharedWithMeTable(rows));
-      } catch (err) {
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  filesCmd
-    .command("search <query>")
-    .description(
-      "Search vault object keys (case-insensitive path/name match) under a company without downloading. Requires --company (or --personal). Content search is not supported in v1.",
-    )
-    .option("--company <slug>", "Company slug to search.")
-    .option(
-      "--personal",
-      "Search the caller's canonical personal vault. Mutually exclusive with --company.",
-    )
-    .action(async (query: string, options: FilesSearchCliOptions, command: Command) => {
-      try {
-        // `--company` is declared on the parent `files` group too, so commander
-        // binds it there; read the merged (global+local) opts to see it.
-        const company = command.optsWithGlobals().company as string | undefined;
-        if (options.personal && company) {
-          throw new Error(
-            "--personal and --company are mutually exclusive. Pick one.",
-          );
-        }
-
-        const accessToken = await ensureCognitoToken();
-        const client = new VaultClient(buildVaultConfig(accessToken));
-
-        if (options.personal) {
-          const personalUid = await resolveCanonicalPersonUid({
-            listMyMemberships: () => client.listMyMemberships(),
-            listPersonEntities: () => client.entity.listByType("person"),
-            getEntity: async () => null,
-          });
-          const rows = await runSearch({
-            query,
-            companySlug: "personal",
-            personalMode: true,
-            personalUid,
-            vaultClient: client,
-            s3Factory: defaultS3Factory,
-            region: DEFAULT_COGNITO.region,
-          });
-          console.log(formatBrowseTable(rows));
-          return;
-        }
-
-        if (!company) {
-          throw new Error(
-            "search: --company <slug> is required (or --personal to search your personal vault).",
-          );
-        }
-        await getCompanyUid(accessToken, company);
-
-        const rows = await runSearch({
-          query,
-          companySlug: company,
-          vaultClient: client,
-          companyClient: makeCompanyPresignFactory(accessToken),
-          region: DEFAULT_COGNITO.region,
-        });
-        console.log(formatBrowseTable(rows));
-      } catch (err) {
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  filesCmd
-    .command("get <path>")
-    .description(
-      "Download (materialize) a vault file or prefix into local HQ on demand. Default writes in place under <hqRoot>/companies/<slug>/<path> and registers a pin so a scoped sync (mode shared|custom) won't prune it. Use --into to write elsewhere (no pin). Company mode only.",
-    )
-    .option(
-      "--into <dir>",
-      "Write into this directory instead of the in-place companies/<slug>/ location. No pin is registered.",
-    )
-    .option(
-      "--company <slug>",
-      "Company slug (defaults to the slug parsed from <path>).",
-    )
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (pathArg: string, options: FilesGetCliOptions, command: Command) => {
-      try {
-        const accessToken = await ensureCognitoToken();
-        const client = new VaultClient(buildVaultConfig(accessToken));
-
-        // `--company` is bound on the parent `files` group — read merged opts.
-        const companyOpt = command.optsWithGlobals().company as string | undefined;
-        const slug = companyOpt ?? parseCompanySlugFromPath(pathArg);
-        if (companyOpt !== undefined) {
-          const fromPath = (() => {
-            try {
-              return parseCompanySlugFromPath(pathArg);
-            } catch {
-              return undefined;
-            }
-          })();
-          if (fromPath && fromPath !== companyOpt) {
-            throw new Error(
-              `--company '${companyOpt}' disagrees with path slug '${fromPath}'.`,
-            );
-          }
-        }
-        await getCompanyUid(accessToken, slug);
-
-        const result = await runGet({
-          path: pathArg,
-          into: options.into,
-          hqRoot: options.hqRoot,
-          companySlug: slug,
-          vaultClient: client,
-          companyClient: makeCompanyPresignFactory(accessToken),
-          region: DEFAULT_COGNITO.region,
-        });
-
-        console.error(
-          chalk.green("✓"),
-          `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`,
-        );
-        if (result.pinned) {
-          console.error(
-            chalk.dim(
-              `Pinned ${result.pinned.companySlug}:${result.pinned.prefix} — survives scoped sync.`,
-            ),
-          );
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-}