@indigoai-us/hq-cli 5.108.26 → 5.109.1

package/dist/commands/cloud.js

@@ -12,6 +12,7 @@
  *   hq sync pull              — pull all permitted files from the vault
  *   hq sync status            — show local journal summary
  */
+import { isAccessDeniedError, accessDeniedKeyOf, formatAccessDenied, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
@@ -44,6 +45,14 @@ export class SyncExitError extends Error {
  * CLI are released independently.
  */
 export function formatSyncFailure(err) {
+    if (isAccessDeniedError(err)) {
+        const key = accessDeniedKeyOf(err);
+        const base = err instanceof Error ? err.message : String(err);
+        if (key) {
+            return formatAccessDenied(`Access denied for '${key}': ${base}`, key);
+        }
+        return formatAccessDenied(base);
+    }
     if (typeof err === "object" && err !== null) {
         const diagnostic = err;
         if (diagnostic.code === "POLICY_WRITE_SCOPE_TRUNCATED") {
@@ -978,7 +987,8 @@ export function registerCloudCommands(program) {
         catch (err) {
             if (syncHealth)
                 await syncHealth.failed();
-            console.error(chalk.red("\n✗ Pull failed:"), err instanceof Error ? err.message : String(err));
+            const message = formatSyncFailure(err);
+            console.error(chalk.red("\n✗ Pull failed:"), message);
             process.exit(1);
         }
     });

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

@@ -35,7 +35,7 @@
  */
 import { Command } from "commander";
 import { ListObjectsV2Command, GetObjectCommand, type ListObjectsV2CommandOutput, type GetObjectCommandOutput } from "@aws-sdk/client-s3";
-import { type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { VaultClient, type ExplicitGrant } from "@indigoai-us/hq-cloud";
 /** STS-vended credential set the browse/cat path consumes. */
 export interface BrowseCredentials {
     accessKeyId: string;
@@ -433,7 +433,18 @@ export declare const PRESIGN_BUFFER_MAX_BYTES: number;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;
+    /**
+     * Company slug the client is scoped to. Attached as `company` on every 403
+     * so the access ladder targets THIS tenant rather than the active company
+     * (keys on these errors are bucket-relative and carry no slug).
+     */
+    companySlug?: string;
 }): FilesBrowseS3Client;
+/**
+ * Production company-mode client factory — closes over the caller's token and
+ * (when known) the company slug, so 403s are tenant-anchored.
+ */
+export declare function makeCompanyPresignFactory(token: string, companySlug?: string): CompanyBrowseClientFactory;
 /**
  * `FilesBrowseVaultClient` for a Bearer `hqk_` key.
  *
@@ -455,6 +466,19 @@ export declare function createCompanyPresignClient(input: {
  * roll-up) throw a fail-closed error naming the Cognito requirement.
  */
 export declare function createApiKeyBrowseVaultClient(token: string): FilesBrowseVaultClient & FilesSharedWithMeVaultClient;
+/**
+ * The caller's credential plus the vault client that can carry it.
+ *
+ * `cognito` is undefined under HQ_API_KEY: `VaultClient` speaks only the JWT
+ * routes, so the keyed adapter stands in for the company path — and the
+ * personal path, which needs `VaultClient.entity.listByType` plus an STS vend,
+ * has nothing to run on and must fail closed at its branch.
+ */
+export declare function resolveBrowseSession(): Promise<{
+    token: string;
+    client: FilesBrowseVaultClient & FilesSharedWithMeVaultClient;
+    cognito?: VaultClient;
+}>;
 /**
  * Wire `hq files browse` + `hq files cat` onto an existing `files`
  * Commander group. `registerFilesCommand` in files.ts builds the group

package/dist/commands/files-browse.js

@@ -33,6 +33,7 @@
  * Cross-package note: depends on the `VaultClient.sts.vend`/`.vendSelf`
  * methods and `grantPathToPrefix` from hq-cloud.
  */
+import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -595,7 +596,13 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * `send(...)` as if it held an S3 client.
  */
 export function createCompanyPresignClient(input) {
-    const { token, companyUid } = input;
+    const { token, companyUid, companySlug } = input;
+    const denied = (message, key, extra) => Object.assign(new Error(message), {
+        status: 403,
+        key,
+        ...(companySlug ? { company: companySlug } : {}),
+        ...(extra ?? {}),
+    });
     async function listObjects(cmd) {
         const prefix = cmd.input.Prefix ?? "";
         const query = { company: companyUid };
@@ -606,7 +613,11 @@ export function createCompanyPresignClient(input) {
         const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
-            throw new Error(body.message ?? body.error ?? `files list failed (${res.status})`);
+            const message = body.message ?? body.error ?? `files list failed (${res.status})`;
+            if (res.status === 403) {
+                throw denied(message, prefix);
+            }
+            throw new Error(message);
         }
         const body = (await res.json());
         return {
@@ -636,13 +647,21 @@ export function createCompanyPresignClient(input) {
         });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
-            throw new Error(body.message ?? body.error ?? `presign failed (${res.status})`);
+            const message = body.message ?? body.error ?? `presign failed (${res.status})`;
+            if (res.status === 403) {
+                throw denied(message, key);
+            }
+            throw new Error(message);
         }
         const body = (await res.json());
         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 message = first?.error ?? `No presigned URL returned for '${key}'`;
+            if (first?.code === "FILES_PRESIGN_FORBIDDEN") {
+                throw denied(message, key, { code: "FILES_PRESIGN_FORBIDDEN" });
+            }
+            throw new Error(message);
         }
         const dl = await fetch(first.url);
         if (!dl.ok) {
@@ -687,9 +706,21 @@ export function createCompanyPresignClient(input) {
     }
     return { send };
 }
-/** Production company-mode client factory — closes over the caller's token. */
-function makeCompanyPresignFactory(token) {
-    return ({ companyUid }) => createCompanyPresignClient({ token, companyUid });
+/**
+ * Production company-mode client factory — closes over the caller's token and
+ * (when known) the company slug, so 403s are tenant-anchored.
+ */
+export function makeCompanyPresignFactory(token, companySlug) {
+    return ({ companyUid }) => createCompanyPresignClient({ token, companyUid, companySlug });
+}
+/**
+ * Tenant anchor for the access ladder in a CLI catch block: prefer the slug
+ * the failing client stamped on the 403, else the `--company` flag. `hqRoot`
+ * rides along so `hq access` reads the same tree the command was run against.
+ */
+function accessLadderContextFor(err, command, hqRoot) {
+    const flag = command.optsWithGlobals().company;
+    return { company: accessDeniedCompanyOf(err) ?? flag, hqRoot };
 }
 // ── HQ_API_KEY vault client (keyed routes only) ──────────────────────────────
 /** Fail-closed error the top-level handler prints without a Sentry report. */
@@ -793,7 +824,7 @@ function personalVaultNeedsCognito() {
  * personal path, which needs `VaultClient.entity.listByType` plus an STS vend,
  * has nothing to run on and must fail closed at its branch.
  */
-async function resolveBrowseSession() {
+export async function resolveBrowseSession() {
     const cred = await resolveVaultCredential();
     if (cred.kind === "api-key") {
         return {
@@ -882,7 +913,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 pathPrefix: pathArg,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(result.rows));
@@ -895,7 +926,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? pathArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -959,7 +996,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             if (result.destination.kind === "file") {
@@ -967,7 +1004,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? keyArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1003,7 +1046,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             console.log(formatSharedWithMeTable(rows));
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err), accessLadderContextFor(err, command));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1049,13 +1098,22 @@ export function registerFilesBrowseCommands(filesCmd) {
                 query,
                 companySlug: company,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, company),
                 region: DEFAULT_COGNITO.region,
             });
             console.log(formatBrowseTable(rows));
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ??
+                    (command.optsWithGlobals().company
+                        ? `companies/${command.optsWithGlobals().company}`
+                        : undefined), accessLadderContextFor(err, command));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });
@@ -1091,7 +1149,7 @@ export function registerFilesBrowseCommands(filesCmd) {
                 hqRoot: options.hqRoot,
                 companySlug: slug,
                 vaultClient: client,
-                companyClient: makeCompanyPresignFactory(accessToken),
+                companyClient: makeCompanyPresignFactory(accessToken, slug),
                 region: DEFAULT_COGNITO.region,
             });
             console.error(chalk.green("✓"), `Materialized ${result.filesWritten} file(s), ${result.bytesWritten} bytes.`);
@@ -1100,7 +1158,13 @@ export function registerFilesBrowseCommands(filesCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("Error:") + " " + message, accessDeniedKeyOf(err) ?? pathArg, accessLadderContextFor(err, command, options.hqRoot));
+            }
+            else {
+                console.error(chalk.red("Error:"), message);
+            }
             process.exit(1);
         }
     });

package/dist/commands/files.js

@@ -7,6 +7,7 @@ import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
 import { looksLikeCompanyUid } from "../utils/vault-api.js";
 import { AuthError } from "../utils/auth-error.js";
+import { formatAccessDenied, offerAccessLadder, } from "../utils/access-denied-hint.js";
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
@@ -75,9 +76,9 @@ export function formatShareSessionError(err) {
     }
     if (err.status === 403) {
         if (err.path) {
-            return `Not authorized to share '${err.path}' — you need read access on every path`;
+            return formatAccessDenied(`Not authorized to share '${err.path}' — you need read access on every path`, err.path);
         }
-        return "Not authorized — you need to be a company member with read access on every path";
+        return formatAccessDenied("Not authorized — you need to be a company member with read access on every path");
     }
     if (err.status === 400) {
         return `Invalid request: ${err.message}`;
@@ -236,6 +237,9 @@ export function registerFilesCommand(program) {
                 }
                 else if (res.status === 403) {
                     console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
+                    await offerAccessLadder(canonicalPrefix, {
+                        company: files.opts().company,
+                    });
                 }
                 else if (res.status === 404) {
                     // A 404 means ZERO rows were removed — never report a green success
@@ -304,6 +308,9 @@ export function registerFilesCommand(program) {
                 }
                 else if (treeRes.status === 403) {
                     console.error(chalk.red("Not authorized to view this file prefix's ACL"));
+                    await offerAccessLadder(canonicalPrefix, {
+                        company: files.opts().company,
+                    });
                 }
                 else if (treeRes.status >= 500) {
                     console.error(chalk.red(`Server error: ${body.error ?? treeRes.statusText}`));
@@ -566,6 +573,9 @@ async function runDirectGrant(params) {
         }
         else if (res.status === 403) {
             console.error(chalk.red("Not authorized to share this file prefix"));
+            await offerAccessLadder(canonicalPrefix, {
+                company: params.companySlug,
+            });
         }
         else if (res.status === 404) {
             console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
@@ -666,7 +676,7 @@ export function formatFilesDeleteError(err, prefix) {
         return "Not authenticated — please run `hq login`";
     }
     if (err.status === 403) {
-        return `Not authorized to delete '${prefix}' — you need write access on it`;
+        return formatAccessDenied(`Not authorized to delete '${prefix}' — you need write access on it`, prefix);
     }
     if (err.status === 400) {
         return `Invalid request: ${err.message}`;
@@ -1084,9 +1094,9 @@ function formatFilesRecoveryError(err, key) {
         return "Not authenticated — please run hq login";
     }
     if (err.status === 403) {
-        return key
+        return formatAccessDenied(key
             ? "Not authorized to modify '" + key + "' — you need write access on it"
-            : "Not authorized to view this vault path";
+            : "Not authorized to view this vault path", key);
     }
     if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
         return "That version is unavailable or is a delete marker.";

package/dist/commands/sync-mode.js

@@ -30,6 +30,7 @@
  * in package.json — revert that line to `^5.20.0` (or whatever the
  * published cut is) once US-004 ships to npm.
  */
+import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -242,7 +243,17 @@ export function registerSyncModeCommand(syncCmd) {
             }
         }
         catch (err) {
-            console.error(chalk.red("✗ sync mode failed:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("✗ sync mode failed:") + " " + message, accessDeniedKeyOf(err) ??
+                    (options.company ? `companies/${options.company}` : undefined), {
+                    company: accessDeniedCompanyOf(err) ?? options.company,
+                    hqRoot: options.hqRoot,
+                });
+            }
+            else {
+                console.error(chalk.red("✗ sync mode failed:"), message);
+            }
             process.exit(1);
         }
     });

package/dist/commands/sync-narrow.js

@@ -36,6 +36,7 @@
  * release is unpublished, hq-cli pins `@indigoai-us/hq-cloud` to
  * `file:../hq-cloud` via `pnpm.overrides`.
  */
+import { isAccessDeniedError, accessDeniedKeyOf, reportAccessDenied, accessDeniedCompanyOf, } from "../utils/access-denied-hint.js";
 import chalk from "chalk";
 import * as readline from "node:readline";
 import * as fs from "node:fs";
@@ -327,7 +328,17 @@ export function registerSyncNarrowCommand(syncCmd) {
             console.log(chalk.dim(`  audit: server-side MEMBERSHIP_SYNC_CONFIG_CHANGED row written by PUT /v1/memberships/${target.membership.membershipKey}/sync-config`));
         }
         catch (err) {
-            console.error(chalk.red("✗ sync narrow failed:"), err instanceof Error ? err.message : String(err));
+            const message = err instanceof Error ? err.message : String(err);
+            if (isAccessDeniedError(err)) {
+                await reportAccessDenied(chalk.red("✗ sync narrow failed:") + " " + message, accessDeniedKeyOf(err) ??
+                    (options.company ? `companies/${options.company}` : undefined), {
+                    company: accessDeniedCompanyOf(err) ?? options.company,
+                    hqRoot: options.hqRoot,
+                });
+            }
+            else {
+                console.error(chalk.red("✗ sync narrow failed:"), message);
+            }
             process.exit(1);
         }
     });

package/dist/register-all.js

@@ -57,6 +57,7 @@ import { registerWorkersCommand } from "./commands/workers.js";
 import { registerGroupGrantsCommand } from "./commands/group-grants.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
+import { registerAccessCommand } from "./commands/access.js";
 import { registerSkillCommand } from "./commands/skill.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerPeopleCommand } from "./commands/people.js";
@@ -157,6 +158,8 @@ export function registerAllCommands(program) {
     // browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
     const filesCmd = registerFilesCommand(program);
     registerFilesBrowseCommands(filesCmd);
+    // Top-level `hq access` — vault existence + ACL probe (self-healing ladder).
+    registerAccessCommand(program);
     // Comment-only skill improvement loop. Structured suggestion/review commands are
     // intentionally absent; live content changes remain governed by FILE_ACL sync.
     registerSkillCommand(program);

package/dist/utils/access-denied-hint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared 403 / access-denied formatter for `hq files` and `hq sync`.
+ *
+ * `src/commands/sync.ts` is the legacy modules-sync command and has no 403
+ * path — leave it untouched; this util is the only 403 hint surface.
+ */
+export declare const ACCESS_HINT_PREFIX = "Run: hq access";
+export declare function accessDeniedHint(path?: string): string;
+export declare function formatAccessDenied(message: string, path?: string): string;
+export declare function isAccessDeniedError(err: unknown): boolean;
+export declare function accessDeniedKeyOf(err: unknown): string | undefined;
+/**
+ * Company slug the denied operation was running against, when the thrower
+ * attached one (`createCompanyPresignClient` does). Keys on 403 errors are
+ * bucket-relative, so without this the ladder would fall back to the ACTIVE
+ * company and could probe/DM the wrong tenant.
+ */
+export declare function accessDeniedCompanyOf(err: unknown): string | undefined;
+/** Tenant anchor forwarded to `hq access` so it never guesses the company. */
+export interface AccessLadderContext {
+    company?: string;
+    hqRoot?: string;
+}
+export interface OfferAccessLadderOptions extends AccessLadderContext {
+    isTTY?: boolean;
+    ask?: (question: string) => Promise<boolean>;
+    run?: (path: string, ctx?: AccessLadderContext) => Promise<unknown>;
+    stderr?: (line: string) => void;
+}
+export declare function offerAccessLadder(path: string | undefined, opts?: OfferAccessLadderOptions): Promise<boolean>;
+export declare function reportAccessDenied(message: string, path: string | undefined, opts?: OfferAccessLadderOptions): Promise<void>;
+//# sourceMappingURL=access-denied-hint.d.ts.map

package/dist/utils/access-denied-hint.js

@@ -0,0 +1,139 @@
+/**
+ * Shared 403 / access-denied formatter for `hq files` and `hq sync`.
+ *
+ * `src/commands/sync.ts` is the legacy modules-sync command and has no 403
+ * path — leave it untouched; this util is the only 403 hint surface.
+ */
+import * as readline from "node:readline";
+export const ACCESS_HINT_PREFIX = "Run: hq access";
+export function accessDeniedHint(path) {
+    const target = path && path.length > 0 ? path : "<path>";
+    return `${ACCESS_HINT_PREFIX} ${target}`;
+}
+export function formatAccessDenied(message, path) {
+    return `${message}\n${accessDeniedHint(path)}`;
+}
+function errRecord(err) {
+    if (typeof err === "object" && err !== null)
+        return err;
+    return undefined;
+}
+function errMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    const rec = errRecord(err);
+    if (rec && typeof rec.message === "string")
+        return rec.message;
+    return "";
+}
+export function isAccessDeniedError(err) {
+    const rec = errRecord(err);
+    if (rec) {
+        if (rec.status === 403)
+            return true;
+        const meta = rec.$metadata;
+        if (typeof meta === "object" &&
+            meta !== null &&
+            meta.httpStatusCode === 403) {
+            return true;
+        }
+        if (rec.code === "FILES_PRESIGN_FORBIDDEN")
+            return true;
+    }
+    return /\b403\b|forbidden|not authorized|access denied/i.test(errMessage(err));
+}
+export function accessDeniedKeyOf(err) {
+    const rec = errRecord(err);
+    if (!rec)
+        return undefined;
+    if (typeof rec.key === "string" && rec.key.length > 0)
+        return rec.key;
+    if (typeof rec.path === "string" && rec.path.length > 0)
+        return rec.path;
+    return undefined;
+}
+/**
+ * Company slug the denied operation was running against, when the thrower
+ * attached one (`createCompanyPresignClient` does). Keys on 403 errors are
+ * bucket-relative, so without this the ladder would fall back to the ACTIVE
+ * company and could probe/DM the wrong tenant.
+ */
+export function accessDeniedCompanyOf(err) {
+    const rec = errRecord(err);
+    if (!rec)
+        return undefined;
+    if (typeof rec.company === "string" && rec.company.length > 0)
+        return rec.company;
+    return undefined;
+}
+function defaultIsTTY() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function defaultAsk(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} `, (line) => {
+            rl.close();
+            resolve(line);
+        });
+    });
+    const t = answer.trim().toLowerCase();
+    return t === "y" || t === "yes";
+}
+async function defaultRun(path, ctx) {
+    const m = await import("../commands/access.js");
+    return m.runAccessForPath(path, ctx);
+}
+function ladderContext(opts) {
+    if (!opts)
+        return undefined;
+    const ctx = {};
+    if (opts.company)
+        ctx.company = opts.company;
+    if (opts.hqRoot)
+        ctx.hqRoot = opts.hqRoot;
+    return Object.keys(ctx).length > 0 ? ctx : undefined;
+}
+export async function offerAccessLadder(path, opts) {
+    const stderr = opts?.stderr ?? ((line) => console.error(line));
+    stderr(accessDeniedHint(path));
+    const isTTY = opts?.isTTY ?? defaultIsTTY();
+    if (!isTTY || !path)
+        return false;
+    const ask = opts?.ask ?? defaultAsk;
+    const question = "Run it now? [y/N]";
+    let yes;
+    try {
+        yes = await ask(question);
+    }
+    catch {
+        return false;
+    }
+    if (!yes)
+        return false;
+    const run = opts?.run ?? defaultRun;
+    const ctx = ladderContext(opts);
+    try {
+        if (ctx)
+            await run(path, ctx);
+        else
+            await run(path);
+        return true;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderr(`Error: ${message}`);
+        return false;
+    }
+}
+export async function reportAccessDenied(message, path, opts) {
+    const stderr = opts?.stderr ?? ((line) => console.error(line));
+    stderr(message);
+    await offerAccessLadder(path, opts);
+}
+//# sourceMappingURL=access-denied-hint.js.map

package/dist/utils/access-outcomes.d.ts

@@ -0,0 +1,23 @@
+import type { AccessOutcome } from "../commands/access.js";
+/**
+ * One line of the `hq access` cause-mix ledger. Deliberately narrow: no path,
+ * requester, or grantor — only enough to review which outcomes users hit.
+ */
+export interface AccessOutcomeRecord {
+    outcome: AccessOutcome;
+    company: string;
+    ts: string;
+}
+export declare function accessOutcomesPath(hqRoot: string): string;
+/**
+ * Append one JSONL line. Best-effort by contract: callers are expected to
+ * catch and downgrade any failure, since telemetry must never change an
+ * `hq access` outcome or exit code.
+ */
+export declare function recordAccessOutcome(hqRoot: string, rec: AccessOutcomeRecord): void;
+/**
+ * Read the ledger. A missing file is the empty ledger; malformed lines are
+ * skipped so one bad append never hides the rest of the history.
+ */
+export declare function readAccessOutcomes(hqRoot: string): AccessOutcomeRecord[];
+//# sourceMappingURL=access-outcomes.d.ts.map