@indigoai-us/hq-cli 5.50.2 → 5.52.0

package/dist/index.d.ts

@@ -2,5 +2,5 @@
 /**
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
-export {};
+import "./node-preflight.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,8 +2,11 @@
 /**
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 
-!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]="34e9e978-4c0a-5113-82af-9a33e30686c6")}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]="82c44c14-a953-5644-9bf2-dd2c6d487d63")}catch(e){}}();
+import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -47,12 +50,18 @@ import { registerRescueCommand } from "./commands/rescue.js";
 import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isEpipe } from "./utils/epipe.js";
+import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
+// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
+// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
+// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
+// console.log inside a command) is handled in the top-level catch below; both
+// share `isEpipe` (HQ-6B).
 const onPipeError = (err) => {
-    if (err.code === "EPIPE") {
+    if (isEpipe(err)) {
         process.exit(0);
     }
     throw err;
@@ -182,19 +191,40 @@ registerMcpCommand(program);
         await program.parseAsync();
     }
     catch (err) {
-        // A full disk / exhausted quota / read-only filesystem is the user's
-        // machine, not an HQ code defect. Surface a clear, actionable message and
-        // skip Sentry capture so one full disk doesn't flood the tracker with
-        // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-        // to Sentry and still exit 1.
-        const envMsg = environmentalFsErrorMessage(err);
-        if (envMsg) {
-            process.stderr.write(`hq: ${envMsg}\n`);
+        // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
+        // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
+        // Unix behavior with no user-facing degradation — exit cleanly (0) and
+        // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
+        // `write EPIPE` thrown out of console.log lands here rather than on the
+        // stream 'error' listener above.
+        if (isEpipe(err)) {
+            process.exitCode = 0;
+        }
+        else if (isInterceptedProcessExit(err)) {
+            // A security/audit FUZZ harness replaced `process.exit` with a throw so it
+            // can keep exercising the binary. Commander calling `process.exit` for
+            // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
+            // here as that synthetic marker. It is a test-harness artifact, NOT an
+            // hq-cli defect — a real user's `process.exit` just exits, so nothing is
+            // thrown or captured. Skip Sentry capture (no signal, no user-facing
+            // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
+            process.exitCode = 1;
         }
         else {
-            Sentry.captureException(err);
+            // A full disk / exhausted quota / read-only filesystem is the user's
+            // machine, not an HQ code defect. Surface a clear, actionable message and
+            // skip Sentry capture so one full disk doesn't flood the tracker with
+            // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+            // to Sentry and still exit 1.
+            const envMsg = environmentalFsErrorMessage(err);
+            if (envMsg) {
+                process.stderr.write(`hq: ${envMsg}\n`);
+            }
+            else {
+                Sentry.captureException(err);
+            }
+            process.exitCode = 1;
         }
-        process.exitCode = 1;
     }
     finally {
         // Release health: finalize the per-run session before the flush.
@@ -203,4 +233,4 @@ registerMcpCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=34e9e978-4c0a-5113-82af-9a33e30686c6
+//# debugId=82c44c14-a953-5644-9bf2-dd2c6d487d63

package/dist/node-preflight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime Node.js version guard for the hq CLI.
+ *
+ * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
+ * the CLI dies with cryptic failures long before reaching any of its own code:
+ * a native-module ABI mismatch from a prebuilt dependency, and a missing
+ * `util.styleText` (added in Node 20). Those errors give the user no hint that
+ * the real problem is just an old Node.
+ *
+ * This module exists to fail fast with an actionable message instead. It is
+ * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
+ * so the check runs before commander, Sentry, or any dependency that needs a
+ * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
+ * imports in source order, so as long as this is the first import in the entry
+ * module, the guard short-circuits an unsupported runtime cleanly.
+ *
+ * Keep this file dependency-free — it must not import anything that could itself
+ * fail to load on the very runtime it is trying to detect.
+ */
+export declare const MIN_NODE_MAJOR = 20;
+export interface NodeVersionCheck {
+    ok: boolean;
+    major: number;
+    message?: string;
+}
+/**
+ * Pure check: is the given Node version string (e.g. "18.19.0") supported?
+ * Defaults to the running runtime's version. An unparseable version is treated
+ * as supported so we never block a user on a version string we can't read.
+ */
+export declare function checkNodeVersion(versionString?: string): NodeVersionCheck;
+/**
+ * Side-effecting guard run on import: prints the upgrade message to stderr and
+ * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
+ * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
+ * runs on a supported Node).
+ */
+export declare function enforceNodeVersion(): void;
+//# sourceMappingURL=node-preflight.d.ts.map

package/dist/node-preflight.js

@@ -0,0 +1,55 @@
+/**
+ * Runtime Node.js version guard for the hq CLI.
+ *
+ * HQ tooling requires Node.js 20 or newer. On older runtimes (notably Node 18)
+ * the CLI dies with cryptic failures long before reaching any of its own code:
+ * a native-module ABI mismatch from a prebuilt dependency, and a missing
+ * `util.styleText` (added in Node 20). Those errors give the user no hint that
+ * the real problem is just an old Node.
+ *
+ * This module exists to fail fast with an actionable message instead. It is
+ * imported FIRST by every CLI entry point (`index.ts`, `bin/hq-auth-refresh.ts`)
+ * so the check runs before commander, Sentry, or any dependency that needs a
+ * Node 20+ API or a newer native ABI is evaluated. ES modules evaluate their
+ * imports in source order, so as long as this is the first import in the entry
+ * module, the guard short-circuits an unsupported runtime cleanly.
+ *
+ * Keep this file dependency-free — it must not import anything that could itself
+ * fail to load on the very runtime it is trying to detect.
+ */
+
+!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]="7d63229d-ff96-5511-9601-53c556487763")}catch(e){}}();
+export const MIN_NODE_MAJOR = 20;
+/**
+ * Pure check: is the given Node version string (e.g. "18.19.0") supported?
+ * Defaults to the running runtime's version. An unparseable version is treated
+ * as supported so we never block a user on a version string we can't read.
+ */
+export function checkNodeVersion(versionString = process.versions.node) {
+    const major = Number.parseInt(String(versionString).split(".")[0] ?? "", 10);
+    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR) {
+        return { ok: true, major };
+    }
+    const message = `hq requires Node.js ${MIN_NODE_MAJOR} or newer — you are running Node ${versionString}.\n` +
+        `Older versions fail with native-module ABI mismatches and missing APIs.\n` +
+        `Please upgrade to Node ${MIN_NODE_MAJOR}+ (https://nodejs.org/) and run hq again.`;
+    return { ok: false, major, message };
+}
+/**
+ * Side-effecting guard run on import: prints the upgrade message to stderr and
+ * exits 1 on an unsupported runtime. A no-op on Node 20+. Set
+ * `HQ_SKIP_NODE_PREFLIGHT=1` to bypass (used by the test runner, which already
+ * runs on a supported Node).
+ */
+export function enforceNodeVersion() {
+    if (process.env.HQ_SKIP_NODE_PREFLIGHT)
+        return;
+    const result = checkNodeVersion();
+    if (!result.ok && result.message) {
+        process.stderr.write(`${result.message}\n`);
+        process.exit(1);
+    }
+}
+enforceNodeVersion();
+//# sourceMappingURL=node-preflight.js.map
+//# debugId=7d63229d-ff96-5511-9601-53c556487763

package/dist/sentry.d.ts

@@ -1,4 +1,16 @@
 import * as Sentry from "@sentry/node";
+import type { ErrorEvent, EventHint } from "@sentry/node";
+/**
+ * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
+ * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
+ * Unix behavior with no user-facing degradation — never a defect to report.
+ * This is the path-independent catch-all for HQ-6B: whichever way an EPIPE
+ * surfaces (a synchronous throw into the command catch, an async stream
+ * 'error', or a write outside the top-level try), it never ships a fatal. The
+ * clean-exit handlers in index.ts still keep exit code 0 for the common paths.
+ * Consistent with the swallow-EPIPE posture established in #138.
+ */
+export declare function epipeAwareBeforeSend(event: ErrorEvent, hint: EventHint): ErrorEvent | null;
 export declare function initSentry(): void;
 export { Sentry };
 //# sourceMappingURL=sentry.d.ts.map

package/dist/sentry.js

@@ -1,11 +1,27 @@
 
-!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]="a260ea42-f6d8-52d0-90c6-6e586de5efd6")}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]="a2ba6d5a-af8a-5512-9ce8-ced925ad5505")}catch(e){}}();
 import * as Sentry from "@sentry/node";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
+import { isEpipe } from "./utils/epipe.js";
+/**
+ * Drop broken-pipe (EPIPE) crashes before scrubbing/send. A closed downstream
+ * reader (`hq … | head`, `source <(hq …)`, a parent that exited) is normal
+ * Unix behavior with no user-facing degradation — never a defect to report.
+ * This is the path-independent catch-all for HQ-6B: whichever way an EPIPE
+ * surfaces (a synchronous throw into the command catch, an async stream
+ * 'error', or a write outside the top-level try), it never ships a fatal. The
+ * clean-exit handlers in index.ts still keep exit code 0 for the common paths.
+ * Consistent with the swallow-EPIPE posture established in #138.
+ */
+export function epipeAwareBeforeSend(event, hint) {
+    if (isEpipe(hint?.originalException))
+        return null;
+    return beforeSend(event, hint);
+}
 export function initSentry() {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
@@ -20,7 +36,7 @@ export function initSentry() {
         initialScope: {
             tags: { repo: "hq-cli" },
         },
-        beforeSend,
+        beforeSend: epipeAwareBeforeSend,
         beforeBreadcrumb,
     });
     // Attribute events to the logged-in HQ identity (best-effort; null when not
@@ -35,4 +51,4 @@ export function initSentry() {
 }
 export { Sentry };
 //# sourceMappingURL=sentry.js.map
-//# debugId=a260ea42-f6d8-52d0-90c6-6e586de5efd6
+//# debugId=a2ba6d5a-af8a-5512-9ce8-ced925ad5505

package/dist/utils/epipe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True when `err` is a Node EPIPE error — the pipe `hq` was writing to was
+ * closed by its reader. Callers should treat this as a clean, expected exit
+ * (code 0) and SKIP Sentry capture: there is no defect and no user-facing
+ * degradation to fix.
+ */
+export declare function isEpipe(err: unknown): boolean;
+//# sourceMappingURL=epipe.d.ts.map

package/dist/utils/epipe.js

@@ -0,0 +1,30 @@
+// src/utils/epipe.ts
+//
+// Classify the "broken pipe" (EPIPE) error: a downstream reader closed the
+// pipe before the CLI finished writing to stdout/stderr. This is normal,
+// expected Unix behavior — `hq … | head`, `source <(hq …)`, or a parent
+// process that exits while `hq` is still printing — NOT an HQ code defect.
+//
+// HQ-6B: a synchronous `write EPIPE` thrown from `console.log` (the Sentry
+// console-instrumentation wraps it) propagated out of an awaited command into
+// the CLI's top-level `catch`, which captured it via `Sentry.captureException`
+// and shipped a fatal — even though the only thing that happened is the
+// consumer of `hq`'s output went away. The async path (an emitted stream
+// 'error' event) was already handled by the stdout/stderr listeners in
+// index.ts; this predicate closes the synchronous-throw path too, mirroring
+// the environmental-error carve-out (HQ-CLI-2).
+/**
+ * True when `err` is a Node EPIPE error — the pipe `hq` was writing to was
+ * closed by its reader. Callers should treat this as a clean, expected exit
+ * (code 0) and SKIP Sentry capture: there is no defect and no user-facing
+ * degradation to fix.
+ */
+
+!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]="3305e402-0237-55ac-a6d4-11143bc69b83")}catch(e){}}();
+export function isEpipe(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "EPIPE");
+}
+//# sourceMappingURL=epipe.js.map
+//# debugId=3305e402-0237-55ac-a6d4-11143bc69b83

package/dist/utils/intercepted-process-exit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True when `err` is a fuzz/audit harness's intercepted-`process.exit` marker
+ * rather than a genuine fault. Callers should SKIP Sentry capture (no defect, no
+ * user-facing degradation) while preserving the intended exit code.
+ */
+export declare function isInterceptedProcessExit(err: unknown): boolean;
+//# sourceMappingURL=intercepted-process-exit.d.ts.map

package/dist/utils/intercepted-process-exit.js

@@ -0,0 +1,38 @@
+// src/utils/intercepted-process-exit.ts
+//
+// Classify the "intercepted process.exit" synthetic error (HQ-CLI-3).
+//
+// Security/audit FUZZ harnesses (e.g. `/opt/audit/fuzz-exports.js`) monkey-patch
+// `process.exit` to THROW a marker instead of actually terminating, so the
+// fuzzer can keep exercising a binary's entrypoints. When such a harness drives
+// `hq` (e.g. `hq <unknown-command>`), commander legitimately calls
+// `process.exit(1)` — and the patched exit turns that normal CLI control-flow
+// into a thrown `Error: fuzz-intercepted-process-exit` that propagates out of
+// `program.parseAsync()` into the CLI's top-level catch, which then shipped it to
+// Sentry as a fatal.
+//
+// This is a test-harness artifact, NOT an hq-cli defect: a real user's
+// `process.exit` exits the process and nothing is ever thrown or captured.
+// There is no user-facing degradation to fix, so the top-level catch skips
+// Sentry capture for it — the genuine "expected, non-actionable" carve-out,
+// mirroring the EPIPE (HQ-6B) and environmental-FS (HQ-CLI-2) carve-outs.
+/** The marker a fuzz/audit harness throws in place of a real `process.exit`. */
+
+!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]="55c7e3b5-a8bc-50fd-835b-127a19172aa1")}catch(e){}}();
+const INTERCEPTED_PROCESS_EXIT_MARKER = "fuzz-intercepted-process-exit";
+/**
+ * True when `err` is a fuzz/audit harness's intercepted-`process.exit` marker
+ * rather than a genuine fault. Callers should SKIP Sentry capture (no defect, no
+ * user-facing degradation) while preserving the intended exit code.
+ */
+export function isInterceptedProcessExit(err) {
+    if (typeof err === "object" && err !== null) {
+        const message = err.message;
+        if (typeof message === "string" && message.includes(INTERCEPTED_PROCESS_EXIT_MARKER)) {
+            return true;
+        }
+    }
+    return typeof err === "string" && err.includes(INTERCEPTED_PROCESS_EXIT_MARKER);
+}
+//# sourceMappingURL=intercepted-process-exit.js.map
+//# debugId=55c7e3b5-a8bc-50fd-835b-127a19172aa1

package/e2e/cli.test.ts

@@ -41,6 +41,31 @@ function runHq(args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv
   });
 }
 
+// Spawn the built CLI with its stdout read-end closed immediately, so the
+// child's first write to stdout hits EPIPE — the `hq … | head` / `source <(hq
+// …)` scenario behind HQ-6B. Returns the child's own exit code + stderr.
+function runHqWithClosedStdout(args: string[]) {
+  return new Promise<{ code: number | null; stderr: string }>(
+    (resolve, reject) => {
+      const child = spawn(process.execPath, [cliEntry, ...args], {
+        env: { ...process.env, HQ_NO_UPDATE_CHECK: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let stderr = "";
+      child.stderr.setEncoding("utf8");
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+      });
+      // Close the read end up front (and again on any byte that slips through)
+      // so subsequent writes by the child fail with EPIPE.
+      child.stdout.on("data", () => child.stdout.destroy());
+      child.stdout.destroy();
+      child.on("error", reject);
+      child.on("close", (code) => resolve({ code, stderr }));
+    },
+  );
+}
+
 async function makeTempDir(prefix: string) {
   const dir = await mkdtemp(path.join(tmpdir(), prefix));
   tempDirs.push(dir);
@@ -62,6 +87,16 @@ describe("built hq CLI", () => {
     expect(result.stdout).toContain("whoami");
   });
 
+  it("exits cleanly when the downstream reader closes the pipe (HQ-6B)", async () => {
+    // Regression for HQ-6B: a closed stdout reader must NOT crash the CLI with
+    // a fatal `write EPIPE`. The process should exit 0 with no EPIPE traceback.
+    const { code, stderr } = await runHqWithClosedStdout(["--help"]);
+
+    expect(code).toBe(0);
+    expect(stderr).not.toMatch(/EPIPE/);
+    expect(stderr).not.toMatch(/Error:/);
+  });
+
   it("prints the package version from the built entrypoint", async () => {
     const result = await runHq(["--version"]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.50.2",
+  "version": "5.52.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/bin/hq-auth-refresh.ts

@@ -12,6 +12,9 @@
  * non-interactively.
  */
 
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
+import "../node-preflight.js";
 import { initSentry, Sentry } from "../sentry.js";
 import { refreshCachedSession } from "../utils/cognito-session.js";
 

package/src/commands/files.test.ts

@@ -501,6 +501,136 @@ describe("hq files share — direct-grant fork (with --with)", () => {
     expect(errs).toMatch(/--permission is required/);
     expect(fetchSpy).not.toHaveBeenCalled();
   });
+
+  it("--full --with email grants the '*' wildcard at the default write permission (no glob to quote)", async () => {
+    // 1) /membership/me for company resolution
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/acl/grant
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { acl: { path: "*" } }),
+    );
+
+    const program = buildProgram();
+    // No positional path, no --permission — --full supplies prefix '*' and
+    // defaults permission to write.
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com"],
+      { from: "user" },
+    );
+
+    const mintCalls = fetchSpy.mock.calls.filter((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCalls).toHaveLength(0);
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    expect(grantCall).toBeDefined();
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "write",
+    });
+
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/ENTIRE vault/);
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("--full honors an explicit --permission read (read-only full vault)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com", "--permission", "read"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "read",
+    });
+  });
+
+  it("--full composes with @all (whole vault for the whole company → company-wide '*')", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "@all"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "company-wide",
+      granteeId: "",
+      permission: "write",
+    });
+  });
+
+  it("rejects --full without --with (and never calls the network)", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "share", "--full"], { from: "user" }),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/--full.*requires --with/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects --full when file paths are also passed", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "somePath", "--full", "--with", "user@example.com"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/entire vault; do not also pass file paths/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/commands/files.ts

@@ -135,6 +135,10 @@ export function registerFilesCommand(program: Command): Command {
       "Email address, group id, or '@all' to share with every active company member",
     )
     .option("--permission <level>", "Permission level (only with --with): read | write")
+    .option(
+      "--full",
+      "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.",
+    )
     .option(
       "--expires <duration>",
       "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.",
@@ -146,11 +150,45 @@ export function registerFilesCommand(program: Command): Command {
         opts: {
           with?: string;
           permission?: string;
+          full?: boolean;
           expires?: string;
           open: boolean;
         },
       ) => {
         try {
+          // Full-vault grant: a glob-safe affordance for "give this person the
+          // whole vault" so admins never have to quote a `*` (an unquoted glob
+          // expands to local filenames and instantly fails the one-prefix
+          // check). Maps to the single `*` wildcard grant, which the server
+          // coalesces to one policy entry — sidestepping the per-prefix STS
+          // session-policy budget. Defaults to write permission.
+          if (opts.full) {
+            if (opts.with === undefined) {
+              console.error(
+                chalk.red(
+                  "--full grants whole-vault access to a principal and requires --with <principal>.",
+                ),
+              );
+              process.exit(1);
+            }
+            if (paths && paths.length > 0) {
+              console.error(
+                chalk.red(
+                  "--full grants the entire vault; do not also pass file paths.",
+                ),
+              );
+              process.exit(1);
+            }
+            await runDirectGrant({
+              prefix: "*",
+              principal: opts.with,
+              permission: opts.permission ?? "write",
+              companySlug: files.opts().company as string | undefined,
+              fullVault: true,
+            });
+            return;
+          }
+
           if (!paths || paths.length === 0) {
             console.error(
               chalk.red("usage: hq files share <paths...> [--with <principal>]"),
@@ -472,6 +510,12 @@ interface DirectGrantParams {
   principal: string;
   permission: string | undefined;
   companySlug: string | undefined;
+  /**
+   * Set by the `--full` affordance: the grant targets the whole vault (the
+   * `*` wildcard prefix). Only affects the success message wording — the
+   * request shape is identical to any other prefix grant.
+   */
+  fullVault?: boolean;
 }
 
 async function runDirectGrant(params: DirectGrantParams): Promise<void> {
@@ -572,9 +616,17 @@ async function runDirectGrant(params: DirectGrantParams): Promise<void> {
   };
   const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
   const verb = autoCreated ? "Created ACL and granted" : "Granted";
-  console.log(
-    chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
-  );
+  if (params.fullVault) {
+    console.log(
+      chalk.green(
+        `${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`,
+      ),
+    );
+  } else {
+    console.log(
+      chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------