@indigoai-us/hq-cli 5.73.1 → 5.75.0

package/dist/commands/integrations.d.ts

@@ -45,7 +45,16 @@ interface GatewayMessage {
     };
 }
 export declare class IntegrationsCliError extends Error {
-    constructor(message: string);
+    /**
+     * True when the error is the caller's request/state/permission (a client 4xx
+     * or a local input/usage error) rather than an hq-cli defect. Expected errors
+     * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+     * to false so an unclassified error still reaches Sentry.
+     */
+    readonly expected: boolean;
+    constructor(message: string, opts?: {
+        expected?: boolean;
+    });
 }
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export declare function toolPrefixForProvider(provider: string): string;

package/dist/commands/integrations.js

@@ -29,12 +29,42 @@ import { randomUUID } from "node:crypto";
 import chalk from "chalk";
 import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { AuthError } from "../utils/auth-error.js";
 export class IntegrationsCliError extends Error {
-    constructor(message) {
+    /**
+     * True when the error is the caller's request/state/permission (a client 4xx
+     * or a local input/usage error) rather than an hq-cli defect. Expected errors
+     * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+     * to false so an unclassified error still reaches Sentry.
+     */
+    expected;
+    constructor(message, opts = {}) {
         super(message);
         this.name = "IntegrationsCliError";
+        this.expected = opts.expected ?? false;
     }
 }
+/**
+ * A client 4xx is the caller's request/state/permission (bad params, stale
+ * queueId, a non-owner approving) — expected and user-facing, not a bug. A 5xx
+ * (or a 2xx protocol violation) is a genuine server/unknown fault worth a Sentry
+ * crash report.
+ */
+function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+// A 401 from ANY integration-gateway vault call means the caller's HQ session
+// is expired or missing — an expected auth state fixed by `hq login`, not an
+// hq-cli defect. Raise the same typed AuthError the vault company-resolution
+// paths use (HQ-CLI-8) so the top-level handler prints one actionable message
+// and skips Sentry, instead of surfacing the opaque, unactionable
+// "Integration gateway request failed (HTTP 401)" that shipped as a fatal from
+// `callGateway` (HQ-CLI-9). Non-401 statuses keep their existing behavior:
+// other 4xx stay expected client errors, 5xx still report.
+function raiseIfUnauthorized(res) {
+    if (res.status === 401)
+        throw new AuthError();
+}
 /** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
 export function toolPrefixForProvider(provider) {
     return provider
@@ -50,8 +80,9 @@ export async function fetchConnections(token, companyUid) {
         query: { companyUid },
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
-        throw new IntegrationsCliError(body.error ?? `Failed to list integrations (HTTP ${res.status})`);
+        throw new IntegrationsCliError(body.error ?? `Failed to list integrations (HTTP ${res.status})`, { expected: isClientError(res.status) });
     }
     const data = (await res.json());
     return data.connections ?? [];
@@ -66,7 +97,7 @@ export function selectConnection(connections, opts) {
     if (opts.connection) {
         const match = connections.find((c) => c.id === opts.connection);
         if (!match) {
-            throw new IntegrationsCliError(`No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`);
+            throw new IntegrationsCliError(`No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`, { expected: true });
         }
         return match;
     }
@@ -81,17 +112,17 @@ export function selectConnection(connections, opts) {
                 .map((c) => c.provider.replace(/^factory:/, ""))
                 .join(", ");
             throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
-                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."));
+                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps on the console Integrations page."), { expected: true });
         }
         return match;
     }
     if (active.length === 1)
         return active[0];
     if (active.length === 0) {
-        throw new IntegrationsCliError("No connected apps yet. Connect one on the console Integrations page, then retry.");
+        throw new IntegrationsCliError("No connected apps yet. Connect one on the console Integrations page, then retry.", { expected: true });
     }
     throw new IntegrationsCliError(`Multiple apps are connected — pick one with --provider:\n` +
-        active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"));
+        active.map((c) => `  --provider ${c.provider.replace(/^factory:/, "")}`).join("\n"), { expected: true });
 }
 export async function callGateway(token, params) {
     const res = await vaultApiFetch({
@@ -107,7 +138,8 @@ export async function callGateway(token, params) {
     });
     const message = (await res.json().catch(() => null));
     if (!res.ok || !message) {
-        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`);
+        raiseIfUnauthorized(res);
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
     }
     if (message.error) {
         throw new IntegrationsCliError(message.error.message ?? "Integration gateway returned an error.");
@@ -232,7 +264,7 @@ export function registerIntegrationsCommand(program) {
             parsedArgs = raw;
         }
         catch {
-            throw new IntegrationsCliError(`--args must be a JSON object, e.g. --args '{"assignee":"me"}'`);
+            throw new IntegrationsCliError(`--args must be a JSON object, e.g. --args '{"assignee":"me"}'`, { expected: true });
         }
         const token = await ensureCognitoIdToken();
         const companyUid = await getCompanyUid(token, opts.company);
@@ -288,7 +320,8 @@ export function registerIntegrationsCommand(program) {
             });
             const body = (await res.json().catch(() => ({})));
             if (!res.ok) {
-                throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`);
+                raiseIfUnauthorized(res);
+                throw new IntegrationsCliError(body.error ?? `${decision} failed (HTTP ${res.status})`, { expected: isClientError(res.status) });
             }
             if (opts.json) {
                 printJson(body);

package/dist/commands/outposts.d.ts

@@ -120,6 +120,8 @@ export interface OutpostExecSubmission {
     instanceId: string;
     commandId: string;
     outputPrefix: string;
+    /** Shell budget applied server-side (AWS-RunShellScript executionTimeout). */
+    executionTimeoutSeconds?: number;
 }
 /** Poll response from `mode: "result"`; streams arrive only when terminal. */
 export interface OutpostExecAsyncResult {
@@ -134,7 +136,7 @@ export interface OutpostExecAsyncResult {
     truncated?: boolean;
 }
 export declare function stageExecInput(token: string, outpostId?: string): Promise<OutpostExecStage>;
-export declare function submitExec(token: string, command: string, outpostId?: string): Promise<OutpostExecSubmission>;
+export declare function submitExec(token: string, command: string, outpostId?: string, timeoutSeconds?: number): Promise<OutpostExecSubmission>;
 export declare function fetchExecResult(token: string, commandId: string, outpostId?: string): Promise<OutpostExecAsyncResult>;
 /** Preserve a single command string; safely join argv when Commander split it. */
 export declare function joinCommandParts(commandParts: string[]): string;
@@ -143,13 +145,14 @@ export declare function joinCommandParts(commandParts: string[]): string;
  * caller's command. `exec` runs over two transports with two different default
  * working directories — SSM runs as root with no `$HOME` (cwd `/usr/bin`) and
  * SSH lands in the login user's home — so without this, `hq outposts exec -- pwd`
- * printed an unhelpful, transport-dependent directory. We resolve the HQ folder
- * in-shell: `$HOME/hq` for the login/SSH user, falling back to ec2-user's home
- * for the SSM/root path. The trailing `|| true` keeps the command running from
- * the default directory when no HQ checkout is present, so exec never fails
- * merely because the box has no HQ folder.
+ * printed an unhelpful, transport-dependent directory. Initialize a real root
+ * home for the SSM case before resolving the HQ folder: tools run by the caller
+ * (notably `gh`) otherwise treat the HQ checkout as their home and can create
+ * root-owned machine state inside it. The trailing `|| true` keeps the command
+ * running from the default directory when no HQ checkout is present, so exec
+ * never fails merely because the box has no HQ folder.
  */
-export declare const REMOTE_HQ_DIR_PREFIX = "cd \"$HOME/hq\" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true";
+export declare const REMOTE_HQ_DIR_PREFIX = "export HOME=\"${HOME:-/root}\"; cd \"$HOME/hq\" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true";
 /** Wrap `command` so it runs from the box's HQ folder (see REMOTE_HQ_DIR_PREFIX). */
 export declare function withRemoteHqDir(command: string): string;
 /** SSH connection details vended by `POST /outpost/ssh-access`. */

package/dist/commands/outposts.js

@@ -162,12 +162,16 @@ export async function stageExecInput(token, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
-export async function submitExec(token, command, outpostId) {
+export async function submitExec(token, command, outpostId, timeoutSeconds) {
     return outpostRequest({
         token,
         path: "/outpost/exec",
         method: "POST",
-        body: { mode: "submit", command },
+        body: {
+            mode: "submit",
+            command,
+            ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+        },
         query: outpostId ? { outpostId } : undefined,
     });
 }
@@ -215,13 +219,14 @@ async function waitForExecResult(token, commandId, outpostId) {
  * caller's command. `exec` runs over two transports with two different default
  * working directories — SSM runs as root with no `$HOME` (cwd `/usr/bin`) and
  * SSH lands in the login user's home — so without this, `hq outposts exec -- pwd`
- * printed an unhelpful, transport-dependent directory. We resolve the HQ folder
- * in-shell: `$HOME/hq` for the login/SSH user, falling back to ec2-user's home
- * for the SSM/root path. The trailing `|| true` keeps the command running from
- * the default directory when no HQ checkout is present, so exec never fails
- * merely because the box has no HQ folder.
+ * printed an unhelpful, transport-dependent directory. Initialize a real root
+ * home for the SSM case before resolving the HQ folder: tools run by the caller
+ * (notably `gh`) otherwise treat the HQ checkout as their home and can create
+ * root-owned machine state inside it. The trailing `|| true` keeps the command
+ * running from the default directory when no HQ checkout is present, so exec
+ * never fails merely because the box has no HQ folder.
  */
-export const REMOTE_HQ_DIR_PREFIX = 'cd "$HOME/hq" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true';
+export const REMOTE_HQ_DIR_PREFIX = 'export HOME="${HOME:-/root}"; cd "$HOME/hq" 2>/dev/null || cd ~ec2-user/hq 2>/dev/null || true';
 /** Wrap `command` so it runs from the box's HQ folder (see REMOTE_HQ_DIR_PREFIX). */
 export function withRemoteHqDir(command) {
     return `${REMOTE_HQ_DIR_PREFIX}; ${command}`;
@@ -834,8 +839,18 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     });
     outposts
         .command("exec <command...>")
-        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)")
+        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). " +
+        "Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.")
         .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--async", "Submit via the async transport and wait for completion (bypasses the ~20s sync cap; shell budget defaults to 48h)")
+        .option("--detach", "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)")
+        .option("--timeout-seconds <n>", "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.", (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+            throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+    })
         .option("--json", "Emit raw JSON")
         .action(async function (commandParts, opts) {
         try {
@@ -844,9 +859,94 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
                 process.exit(1);
             }
+            if (opts.async && opts.detach) {
+                console.error(chalk.red("Use either --async (submit + wait) or --detach (submit only), not both."));
+                process.exit(1);
+            }
+            // --timeout-seconds only applies to the async path; bare use implies --async.
+            const useAsync = Boolean(opts.async) ||
+                Boolean(opts.detach) ||
+                opts.timeoutSeconds !== undefined;
+            if (opts.timeoutSeconds !== undefined) {
+                if (!Number.isInteger(opts.timeoutSeconds) ||
+                    opts.timeoutSeconds < 1 ||
+                    opts.timeoutSeconds > 172_800) {
+                    console.error(chalk.red("--timeout-seconds must be an integer between 1 and 172800 (48h, the AWS-RunShellScript max)"));
+                    process.exit(1);
+                }
+            }
             const token = await ensureCognitoToken();
             // Run from the box's HQ folder by default (works over both SSM and SSH).
             const remoteCommand = withRemoteHqDir(command);
+            if (useAsync) {
+                try {
+                    const submitted = await submitExec(token, remoteCommand, opts.id, opts.timeoutSeconds);
+                    if (opts.detach) {
+                        const output = {
+                            commandId: submitted.commandId,
+                            ...(submitted.executionTimeoutSeconds !== undefined
+                                ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                                : opts.timeoutSeconds !== undefined
+                                    ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                                    : {}),
+                        };
+                        if (opts.json) {
+                            process.stdout.write(JSON.stringify(output) + "\n");
+                        }
+                        else {
+                            printKeyValues(output);
+                            console.error(chalk.dim("Submitted. Poll with: hq outposts exec-result --command-id " +
+                                submitted.commandId +
+                                (opts.id ? ` --id ${opts.id}` : "") +
+                                " --wait"));
+                        }
+                        return;
+                    }
+                    // --async (or --timeout-seconds without --detach): wait for terminal.
+                    if (!opts.json) {
+                        console.error(chalk.dim(`Submitted ${submitted.commandId}; waiting for completion…`));
+                    }
+                    const result = await waitForExecResult(token, submitted.commandId, opts.id);
+                    if (opts.json) {
+                        process.stdout.write(JSON.stringify({
+                            commandId: submitted.commandId,
+                            done: result.done,
+                            status: result.status,
+                            exitCode: result.exitCode ?? null,
+                            stdout: result.stdout ?? "",
+                            stderr: result.stderr ?? "",
+                            truncated: result.truncated ?? false,
+                        }, null, 2) + "\n");
+                    }
+                    else {
+                        if (result.stdout)
+                            process.stdout.write(result.stdout);
+                        if (result.stderr)
+                            process.stderr.write(result.stderr);
+                        if (result.truncated) {
+                            console.error(chalk.yellow("(output truncated — redirect to a file on the box for full output)"));
+                        }
+                        if (result.status !== "Success" && result.exitCode === null) {
+                            console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+                        }
+                    }
+                    process.exitCode =
+                        typeof result.exitCode === "number" ? result.exitCode : 0;
+                    return;
+                }
+                catch (err) {
+                    // Async requires EC2/SSM. Lightsail has no async channel — refuse
+                    // rather than silently falling back to a live SSH hold, which is
+                    // the exact timeout failure mode --async is meant to escape.
+                    if (err instanceof OutpostHttpError &&
+                        err.step === "platform-unsupported") {
+                        console.error(chalk.red("Async exec requires an EC2 Outpost (SSM). This box is Lightsail — " +
+                            "re-provision on EC2, or run a short sync command / SSH session instead."));
+                        process.exit(1);
+                    }
+                    throw err;
+                }
+            }
             try {
                 const result = await execOutpost(token, remoteCommand, opts.id);
                 if (opts.json) {
@@ -939,8 +1039,15 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     });
     outposts
         .command("exec-submit <command...>")
-        .description("Submit an asynchronous shell command to an Outpost")
+        .description("Submit an asynchronous shell command to an Outpost (returns immediately with commandId; shell budget defaults to 48h)")
         .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--timeout-seconds <n>", "Shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)", (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+            throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+    })
         .option("--json", "Emit raw JSON")
         .action(async function (commandParts, opts) {
         try {
@@ -949,9 +1056,27 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 console.error(chalk.red("No command given. Usage: hq outposts exec-submit -- <command>"));
                 process.exit(1);
             }
+            if (opts.timeoutSeconds !== undefined) {
+                if (!Number.isInteger(opts.timeoutSeconds) ||
+                    opts.timeoutSeconds < 1 ||
+                    opts.timeoutSeconds > 172_800) {
+                    console.error(chalk.red("--timeout-seconds must be an integer between 1 and 172800 (48h)"));
+                    process.exit(1);
+                }
+            }
             const token = await ensureCognitoToken();
-            const submitted = await submitExec(token, command, opts.id);
-            const output = { commandId: submitted.commandId };
+            // exec-submit is the raw fire-and-forget path — do NOT wrap with
+            // withRemoteHqDir here (callers that want the HQ cwd use `exec --async`
+            // or prefix their own cd). Matches the existing contract.
+            const submitted = await submitExec(token, command, opts.id, opts.timeoutSeconds);
+            const output = {
+                commandId: submitted.commandId,
+                ...(submitted.executionTimeoutSeconds !== undefined
+                    ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                    : opts.timeoutSeconds !== undefined
+                        ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                        : {}),
+            };
             if (opts.json) {
                 process.stdout.write(JSON.stringify(output) + "\n");
             }

package/dist/main.js

@@ -58,8 +58,10 @@ import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
+import { isAuthError } from "./utils/auth-error.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
@@ -266,6 +268,25 @@ export async function runCli() {
             process.stderr.write(`hq: ${err.message}\n`);
             process.exitCode = 1;
         }
+        else if (isAuthError(err)) {
+            // HQ-CLI-8: the vault API returned 401 Unauthorized — the caller's HQ
+            // session is expired or missing. That's an expected auth state the user
+            // fixes with `hq login`, not an hq-cli defect. Print the actionable
+            // message and skip Sentry so an expired login doesn't flood the tracker
+            // with identical, unfixable "crashes".
+            process.stderr.write(`hq: ${err.message}\n`);
+            process.exitCode = 1;
+        }
+        else if (isExpectedUserError(err)) {
+            // HQ-CLI-6: a user-facing, client-caused error (a non-owner running
+            // `hq integrations approve`, a stale queueId, a bad --args, an unknown
+            // connection) is the caller's request/state/permission, not an hq-cli
+            // defect. Print the actionable message and skip Sentry so a correctly-
+            // denied 4xx doesn't flood the tracker with identical, unfixable crash
+            // reports. Genuine server (5xx) / unknown failures still capture below.
+            process.stderr.write(`hq: ${err.message}\n`);
+            process.exitCode = 1;
+        }
         else {
             // A full disk / exhausted quota / read-only filesystem is the user's
             // machine, not an HQ code defect. Surface a clear, actionable message and

package/dist/utils/auth-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when the vault API reports the caller's HQ session is expired or
+ * missing. The `message` is user-facing and actionable; the top-level handler
+ * prints it verbatim and skips Sentry capture.
+ */
+export declare class AuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * True when `err` is an expected auth-state failure the user must resolve with
+ * `hq login`. Callers should print `err.message` and SKIP Sentry capture while
+ * preserving a non-zero exit. Genuine faults are plain `Error`s and return
+ * `false`, so real bugs still report.
+ */
+export declare function isAuthError(err: unknown): boolean;
+//# sourceMappingURL=auth-error.d.ts.map

package/dist/utils/auth-error.js

@@ -0,0 +1,39 @@
+// src/utils/auth-error.ts
+//
+// Classify expired or missing HQ session conditions surfaced by the vault API
+// (HQ-CLI-8). These are expected, user-actionable auth states — NOT hq-cli
+// defects — so the top-level catch prints the message and exits non-zero but
+// SKIPS Sentry capture, mirroring the company-selection (HQ-CLI-7),
+// expected-user-error (HQ-CLI-6), and environmental-FS (HQ-CLI-2) carve-outs.
+//
+// HQ-CLI-8: a user ran `hq integrations list --company liverecover --json`
+// with an expired HQ session. Company-slug resolution tried the caller-scoped
+// `/entity/check-slug/me` lookup and the global `/entity/by-slug/company/...`
+// fallback; both returned 401 Unauthorized. The plain Error that bubbled up
+// looked like a company-resolution defect and was shipped to Sentry as a fatal.
+// A 401 from vault resolution means the caller needs to run `hq login`; the
+// code cannot repair an expired token, so this is normal auth state, not a
+// crash to triage.
+/**
+ * Thrown when the vault API reports the caller's HQ session is expired or
+ * missing. The `message` is user-facing and actionable; the top-level handler
+ * prints it verbatim and skips Sentry capture.
+ */
+export class AuthError extends Error {
+    constructor(message = "Your HQ session has expired or you're not signed in. Run `hq login` and try again.") {
+        super(message);
+        this.name = "AuthError";
+        // Preserve `instanceof` across the TS→ES5/ES2015 transpile target.
+        Object.setPrototypeOf(this, AuthError.prototype);
+    }
+}
+/**
+ * True when `err` is an expected auth-state failure the user must resolve with
+ * `hq login`. Callers should print `err.message` and SKIP Sentry capture while
+ * preserving a non-zero exit. Genuine faults are plain `Error`s and return
+ * `false`, so real bugs still report.
+ */
+export function isAuthError(err) {
+    return err instanceof AuthError;
+}
+//# sourceMappingURL=auth-error.js.map

package/dist/utils/expected-cli-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An error the CLI should surface to the user (clear message, exit 1) but NOT
+ * report to Sentry. Carriers set `expected: true`.
+ */
+export interface ExpectedUserError extends Error {
+    expected: true;
+}
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export declare function isExpectedUserError(err: unknown): err is ExpectedUserError;
+//# sourceMappingURL=expected-cli-error.d.ts.map

package/dist/utils/expected-cli-error.js

@@ -0,0 +1,29 @@
+// src/utils/expected-cli-error.ts
+//
+// Classify errors that are the CALLER's request/state/permission rather than an
+// hq-cli code defect: a bad flag, malformed input, a correctly-denied client
+// 4xx (e.g. a non-owner running `hq integrations approve`). These are
+// user-facing and actionable — the CLI prints a clear message and does NOT
+// report them to Sentry, otherwise a correctly-enforced authorization denial
+// floods the tracker with identical, unfixable crash reports.
+//
+// This is the caller-side analog of hq-pro's `expectedDenialResponse`, and a
+// sibling of `environmental-error.ts` (HQ-CLI-2) and
+// `intercepted-process-exit.ts` (HQ-CLI-3): errors that are NOT hq-cli defects
+// are surfaced to the user but skipped for Sentry capture.
+//
+// HQ-CLI-6: `hq integrations approve|reject` by a non-owner got a correct 403
+// ("Only a company owner can approve or reject queued integration writes"); the
+// thrown error propagated to the top-level handler, which captured it to Sentry
+// as an error-level crash and printed nothing to the user.
+/**
+ * True when `err` is an Error explicitly marked `expected === true`. A non-null
+ * result means the top-level handler should print `err.message` and skip Sentry
+ * capture. Anything else (unmarked errors, non-Error values) returns false so
+ * genuine faults still reach Sentry.
+ */
+export function isExpectedUserError(err) {
+    return (err instanceof Error &&
+        err.expected === true);
+}
+//# sourceMappingURL=expected-cli-error.js.map

package/dist/utils/vault-api.js

@@ -1,5 +1,6 @@
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
 import { Sentry } from '../sentry.js';
+import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
 export async function vaultApiFetch(opts) {
     const url = new URL(opts.path, DEFAULT_VAULT_API_URL);
@@ -83,12 +84,21 @@ const COMPANY_UID_PREFIX = 'cmp_';
 export function looksLikeCompanyUid(ref) {
     return ref.startsWith(COMPANY_UID_PREFIX);
 }
+// A 401 from ANY vault resolution call means the caller's HQ session is
+// expired or missing — an expected auth state fixed by `hq login`, not a
+// code defect. Raise a typed AuthError so the top-level handler prints an
+// actionable message and skips Sentry capture (HQ-CLI-8).
+function raiseIfUnauthorized(res) {
+    if (res.status === 401)
+        throw new AuthError();
+}
 async function resolveCompanyByUid(token, uid) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/${encodeURIComponent(uid)}`,
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
         throw new Error(`Failed to resolve company '${uid}': ${body.error ?? res.statusText}`);
     }
@@ -120,11 +130,13 @@ async function resolveSlugInCallerNamespace(token, slug) {
         query: { type: 'company', slug },
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         // Namespace lookup unavailable (e.g. membership table not configured →
-        // 503, or the caller has no person entity). Signal "couldn't resolve here"
-        // and let the caller fall back to the global lookup. vaultApiFetch already
-        // recorded the non-2xx as a Sentry breadcrumb, so this is not a silent
-        // swallow.
+        // 503, or the caller has no person entity). A 401 short-circuits above
+        // because the token is bad and the global fallback would only 401 again;
+        // other non-2xx statuses signal "couldn't resolve here" and let the caller
+        // fall back to the global lookup. vaultApiFetch already recorded the
+        // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
         return null;
     }
     const data = (await res.json());
@@ -152,6 +164,7 @@ async function resolveCompanyUid(token, ref) {
         path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
     });
     if (!res.ok) {
+        raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
         // Residual true ambiguity: the slug matches multiple live companies and
         // NONE is in the caller's namespace (server returns 409 SlugNotUniqueError

package/package.json

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