@vigilbase/cli 0.2.2 → 0.2.3

package/CLOUDFLARE.md

@@ -2,7 +2,7 @@
 
 `vigilbase cf` and `vigilbase cloudflare` use the authenticated Vigilbase One API. Run `vigilbase login` first (signing in isn't supported on Windows yet). Your organization, permissions, customer links, and allowed zones determine access. The CLI never requires a Cloudflare API key.
 
-`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md)).
+`cf checkup` runs on One's servers. `cloudflare-checkup` (also `local cloudflare-checkup`) runs on your machine with Cloudflare's own `cf` CLI and needs no Vigilbase login: one command, `npx @vigilbase/cli cloudflare-checkup`, verifies your work email with a code, installs cf if needed, signs in read-only, collects and uploads after you confirm. It works while vigilbase.com has local checkups switched on; otherwise it says so before asking for your email and points you to the checkup in your browser at https://vigilbase.com/tools/cloudflare-checkup (see [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md)).
 
 Customer provider access requires an `active` or `trialing` Cloudflare service
 entitlement for the selected account. Historical/inactive rows and legacy account

package/COMMANDS.md

@@ -10,11 +10,11 @@ below omit `--json`, which every command supports.
 
 | Area | Complete command and API reference |
 | --- | --- |
-| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) |
-| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) |
-| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) |
-| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) |
-| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) |
+| Cloudflare | [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md) |
+| Security | [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/SECURITY.md) |
+| Customers, organizations, monitoring, support | [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/ONE.md) |
+| Local Cloudflare Checkup (cf on your machine) | [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md) |
+| Sign-in, credentials, configuration, troubleshooting | [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/README.md) |
 
 The references list the supported operations, filters, response and pagination
 behaviour, API endpoints and access requirements of the CLI.
@@ -141,7 +141,19 @@ credentials file is there.
 When a public scan fails and vigilbase.com explains why with a known error
 code, the CLI prints `Error: <message> (<code>)` (JSON: `error`, `code`,
 `status`), with the message cleaned to one line of at most 300 characters.
-Otherwise it prints `Request failed (HTTP <status>).`
+Otherwise it prints a message of its own, never the server's text.
+
+When a scan run through Vigilbase One fails (One answers 422), the CLI prints
+`Error: The scan couldn't be completed. Try again later.` and exits 1. JSON
+has `success: false`, that `error`, `status: 422` and the `toolRunId` One
+recorded, for `vigilbase runs get <toolRunId>`.
+
+When the scanner ran but couldn't assess the target, for example because the
+site answered with a bot verification challenge or an error page, the CLI
+prints `✗ <tool> · <target> · n/a` and the scanner's reason on the next line,
+cleaned to one line of at most 300 characters, and exits 1. JSON has
+`success: false`, that reason as `error`, `grade: null`, the scanner's
+`result`, `status: 422`, `code: "scan_unassessed"` and the `toolRunId`.
 
 ## Account and billing
 
@@ -158,7 +170,7 @@ Otherwise it prints `Request failed (HTTP <status>).`
 | `billing` | `summary`, `show`, `status` | GET `/api/account/billing` |
 | `billing portal` | `open`; `--no-open` prints the portal URL without opening a browser | POST `/api/billing/portal` |
 
-Invitations need a One browser session: Identity's management API doesn't accept CLI sign-ins, so `account invites` and `account invites create` answer 403 (`browser_session_required`) and the CLI points you to https://one.vigilbase.com.
+Invitations need a One browser session: Identity's management API doesn't accept CLI sign-ins, so `account invites` and `account invites create` answer 403 (`browser_session_required`): the CLI prints `You don't have access to this.` and points you to https://one.vigilbase.com.
 
 Creating an invitation sends it; `billing portal` starts a Stripe portal
 session. Both are explicit actions. Billing data comes from One's Stripe
@@ -226,14 +238,21 @@ the uploaded data and the error codes.
 
 Exit codes: **0** success, **1** validation, API, network or sign-in failure,
 **2** HTTP 429 rate limiting. A completed scan whose result is unsuccessful
-also exits 1. A signed-out `whoami` is not a failure, and a healthy `doctor`
+also exits 1. So does a scan the scanner could not grade (result `status`
+`"error"`, no grade): it prints `✗ <tool> · <target> · n/a` and the scanner's
+message, cleaned to one line of at most 300 characters, and JSON has
+`success: false` with that message as `error`. A signed-out `whoami` is not a
+failure, and a healthy `doctor`
 does not need a sign-in. API error JSON keeps the status, code and retry delay
 when available.
 
 Vigilbase One's error messages are never shown, because they can describe
-One's configuration: the CLI prints `Request failed (HTTP <status>).` When it
-recognises the failure from the route, the status and One's error code, it adds
-a hint of its own (`Hint: …` in text, `hint` in JSON):
+One's configuration. The CLI prints its own message for the status instead:
+``Authentication required. Run `vigilbase login`.`` (401),
+`You don't have access to this.` (403), `Rate limit exceeded.` (429) and
+`Request failed (HTTP <status>).` otherwise. When it recognises the failure
+from the route, the status and One's error code, it adds a hint of its own
+(`Hint: …` in text, `hint` in JSON):
 
 | One answers | Hint |
 | --- | --- |

package/LOCAL.md

@@ -15,7 +15,7 @@ before it asks for your email; when local mode is off it stops with
 your browser at <https://vigilbase.com/tools/cloudflare-checkup>.
 
 `vigilbase cf checkup` runs on Vigilbase One's servers with stored credentials
-(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md));
+(see [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md));
 `vigilbase cloudflare-checkup` runs on your machine and needs no Vigilbase
 login.
 
@@ -34,7 +34,7 @@ of the CLI (0.1.x) is running instead: `npx` prefers an installed global
 update the global install with `npm install -g @vigilbase/cli@latest`. With
 Yarn 4.15+ or pnpm 11+, `yarn dlx` and `pnpm dlx` run an older release for a
 day after each release; use `npx` (see
-[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md#troubleshooting)).
+[Troubleshooting](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/README.md#troubleshooting)).
 
 The command does everything, in this order, and stops at the first problem
 before any slower step:

package/ONE.md

@@ -95,4 +95,4 @@ vigilbase support tickets [--all] [--limit 1..100] [--customer-id <uuid>] [--jso
 
 ## Related commands and validation
 
-See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.
+See [README.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/README.md) for sign-in and configuration, [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/COMMANDS.md) for account, billing, public scanners, run history and Watchdog, [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md) for `cf`/`cloudflare`, and [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/SECURITY.md) for security commands. The read operations above do not replace the existing explicitly confirmed write commands.

package/README.md

@@ -28,11 +28,11 @@ supported on Windows yet; public tools and `cloudflare-checkup` still work there
 
 | Reference | Covers |
 | --- | --- |
-| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
-| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
-| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
-| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
-| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
+| [COMMANDS.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/COMMANDS.md) | Core commands, aliases, global options, API mapping, sign-in, output |
+| [CLOUDFLARE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/CLOUDFLARE.md) | Accounts, zones, DNS, WAF, analytics, Zero Trust, Workers/Pages, audit, checkups |
+| [SECURITY.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/SECURITY.md) | Incidents, logs, intelligence, analytics, assets, connections, policies, notifications, reports |
+| [ONE.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/ONE.md) | Customer records, billing, reports, investigations, organizations, monitoring, support |
+| [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md) | `cloudflare-checkup`: verifies your work email, collects your Cloudflare configuration on your machine with Cloudflare's `cf` and uploads it after you confirm |
 
 These files ship with the package. Built-in help: `vigilbase <command> --help`
 or `vigilbase help <command>`; `vigilbase help <tool>` shows how to run a tool.
@@ -143,7 +143,7 @@ read-only Cloudflare API token instead. When you are done:
 npx @vigilbase/cli cloudflare-checkup logout   # removes the read-only cf login and the cf it installed
 ```
 
-See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.2/files/LOCAL.md) for
+See [LOCAL.md](https://app.unpkg.com/@vigilbase/cli@0.2.3/files/LOCAL.md) for
 every step, what is uploaded and the error codes.
 
 ## Public tools and sign-in
@@ -191,9 +191,12 @@ fails and vigilbase.com explains why, the CLI shows that reason:
 `Error: <message> (<code>)` in text, and `error` plus `code` in JSON. The
 reason is shown only when vigilbase.com sends it as a known error code, and it
 is cleaned to one line of at most 300 characters. Anything else, and every
-Vigilbase One error, prints only `Request failed (HTTP <status>).` without the
-server's text. Hints (`Hint: …`, `hint` in JSON) are always written by the CLI;
-COMMANDS.md lists the One errors that get one.
+Vigilbase One error, prints a message the CLI wrote (for example
+`You don't have access to this.` or `Request failed (HTTP <status>).`), never
+the server's text. The exception is a One scan the scanner couldn't assess
+(for example a bot verification challenge): the CLI prints the scanner's
+reason, cleaned the same way. Hints (`Hint: …`, `hint` in JSON) are always written by the
+CLI; COMMANDS.md lists the One errors that get one.
 
 Commands use named One APIs and One's own authorization. They never take
 Cloudflare or other provider secrets, delegated identity claims or an arbitrary

package/SECURITY.md

@@ -99,7 +99,7 @@ Provider events map `--provider` to `provider_id`, `--dataset` to `dataset_id`,
 | `settings broadcast-emails` | None | `/settings/broadcast-emails` |
 | `settings applications` | None | `/integrations/grants` |
 
-Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `Request failed (HTTP 403).` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.
+Intel lookup input is trimmed and limited to 512 characters; the server validates the indicator and applies lookup quota. Personal settings show existing preferences and authorized application grants. They do not change preferences or revoke grants. Personal settings and `notifications preferences` belong to each user: with `--customer-id` (View-as), a refusal prints `You don't have access to this.` with the hint `Personal settings belong to each user, so View-as (--customer-id) cannot read them.` Reports are fetched on demand; this CLI does not persist report or billing records.
 
 ## Limits and pagination
 

package/dist/auth/device-auth.d.ts

@@ -14,10 +14,13 @@ export declare class DeviceAuthError extends Error {
     readonly code?: string;
     readonly status: number;
     readonly body: unknown;
+    /** The message is the CLI's own text, never the server's (see VigilbaseApiError). */
+    readonly isCliAuthored: boolean;
     constructor(message: string, options: {
         status: number;
         code?: string;
         body?: unknown;
+        isCliAuthored?: boolean;
     });
 }
 export declare function requestDeviceCode(config: CliConfig, options?: {

package/dist/auth/device-auth.js

@@ -8,12 +8,15 @@ export class DeviceAuthError extends Error {
     code;
     status;
     body;
+    /** The message is the CLI's own text, never the server's (see VigilbaseApiError). */
+    isCliAuthored;
     constructor(message, options) {
         super(message);
         this.name = 'DeviceAuthError';
         this.status = options.status;
         this.code = options.code;
         this.body = options.body;
+        this.isCliAuthored = options.isCliAuthored ?? false;
     }
 }
 function authBase(config) {
@@ -139,7 +142,7 @@ export async function pollDeviceToken(config, deviceCode) {
             },
         };
     }
-    throw new DeviceAuthError(`Device token request failed (HTTP ${status})`, { status, code, body: errorBody });
+    throw new DeviceAuthError(`Device token request failed (HTTP ${status})`, { status, code, body: errorBody, isCliAuthored: true });
 }
 export async function sleep(ms, signal) {
     await new Promise((resolve, reject) => {
@@ -198,14 +201,19 @@ export async function waitForDeviceAuthorization(config, device, options) {
                 consecutiveTransient += 1;
                 lastTransientStatus = result.httpStatus;
                 if (consecutiveTransient >= maxTransient) {
+                    // After an HTTP error the description is the server's, so only a network failure's
+                    // own (CLI-authored) description joins the message.
+                    const detail = (!lastTransientStatus && result.error.error_description) ||
+                        'Retry `vigilbase login` once One is healthy.';
                     throw new DeviceAuthError(`Lost contact with device authorization on ${config.oneBaseUrl} while waiting for approval` +
                         (lastTransientStatus
                             ? ` (HTTP ${lastTransientStatus})`
                             : '') +
-                        `. ${result.error.error_description ?? 'Retry `vigilbase login` once One is healthy.'}`, {
+                        `. ${detail}`, {
                         status: lastTransientStatus,
                         code: 'unreachable',
                         body: result.error,
+                        isCliAuthored: true,
                     });
                 }
                 break;
@@ -214,9 +222,10 @@ export async function waitForDeviceAuthorization(config, device, options) {
                     status: 403,
                     code: 'access_denied',
                     body: result.error,
+                    isCliAuthored: true,
                 });
             case 'expired':
-                throw new DeviceAuthError('The device code expired. Run `vigilbase login` again.', { status: 400, code: 'expired_token', body: result.error });
+                throw new DeviceAuthError('The device code expired. Run `vigilbase login` again.', { status: 400, code: 'expired_token', body: result.error, isCliAuthored: true });
             default: {
                 const _exhaustive = result;
                 throw new DeviceAuthError(`Unexpected poll result: ${JSON.stringify(_exhaustive)}`, {

package/dist/commands/public-tools.js

@@ -4,7 +4,7 @@ import { NetworkError } from '../lib/network.js';
 import { PUBLIC_TOOLS_PATH, VigilbaseApiError } from '../lib/client.js';
 import { getOneAccessToken, getOptionalOneAccessToken, hasUsableSignIn, readCredentials } from '../auth/index.js';
 import { SignInUnsupportedError } from '../auth/store.js';
-import { formatExecuteResult, formatToolDescription, formatToolsList, } from '../lib/format.js';
+import { formatExecuteResult, formatToolDescription, formatToolsList, isSuccessfulScan, } from '../lib/format.js';
 import { isOneAuthRequiredTool, isOneExecutableTool, ONE_AUTH_REQUIRED_TOOLS, resolveToolDefinition, VigilbaseOneClient, } from '../lib/one-client.js';
 import { EXIT, ok, outputJson, withSpinner, } from './helpers.js';
 const ONE_SIGN_IN_REQUIRED = 'This tool needs a Vigilbase One sign-in: run `vigilbase login`.';
@@ -99,21 +99,27 @@ export const handleRun = async (ctx) => {
         }
         const oneClient = new VigilbaseOneClient(ctx.config, accessToken, true);
         const oneResult = await withSpinner(ctx, `Running ${toolName} against ${target}`, () => oneClient.executeTool(toolName, target));
-        formatExecuteResult({
-            success: Boolean(oneResult.success),
+        const unassessed = oneResult.code === 'scan_unassessed';
+        const toolRunId = oneResult.data?.toolRunId;
+        const result = {
+            success: oneResult.success === true,
             toolName,
             target,
             grade: oneResult.data?.grade ?? null,
             gradeScore: oneResult.data?.gradeScore ?? null,
-            result: oneResult.data?.result ?? null,
-            error: oneResult.error ?? null,
+            // Only a completed scan, or one the scanner could not assess, carries the scanner's result.
+            result: oneResult.success === true || unassessed ? oneResult.data?.result ?? null : null,
+            // One's error text is server text; a failed scan prints the CLI's own message.
+            error: null,
             uiUrl: `${ctx.config.oneBaseUrl}/dashboard/tools/${toolName}`,
-        }, ctx.mode, ctx.writer);
-        return oneResult.success ? ok() : EXIT.ERROR;
+            ...(unassessed ? { status: 422, code: 'scan_unassessed', ...(toolRunId ? { toolRunId } : {}) } : {}),
+        };
+        formatExecuteResult(result, ctx.mode, ctx.writer);
+        return isSuccessfulScan(result) ? ok() : EXIT.ERROR;
     }
     const result = await withSpinner(ctx, `Running ${toolName} against ${target}`, () => ctx.publicClient.executeTool(toolName, target));
     formatExecuteResult(result, ctx.mode, ctx.writer);
-    return result.success ? ok() : EXIT.ERROR;
+    return isSuccessfulScan(result) ? ok() : EXIT.ERROR;
 };
 export const handleDescribe = async (ctx) => {
     validateArguments(ctx, 1, ['isNoSkill'], 'vigilbase describe <tool>');

package/dist/lib/client.d.ts

@@ -9,6 +9,13 @@ export declare class VigilbaseApiError extends Error {
     readonly reason?: string;
     /** CLI-authored remediation, never server text (see one-error-hints.ts). */
     readonly hint?: string;
+    /**
+     * The message is the CLI's own text, never the server's, so formatError prints it although the
+     * error carries a body. Unmarked errors with a body print only a generic `Request failed`.
+     */
+    readonly isCliAuthored: boolean;
+    /** The One tool run a failed scan recorded. */
+    readonly toolRunId?: string;
     constructor(message: string, options: {
         status: number;
         body?: unknown;
@@ -16,6 +23,8 @@ export declare class VigilbaseApiError extends Error {
         code?: string;
         reason?: string;
         hint?: string;
+        isCliAuthored?: boolean;
+        toolRunId?: string;
     });
 }
 export declare function retryAfterSeconds(response: Response, body: unknown): number | undefined;

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { singleLine } from './format.js';
+import { SCAN_FAILED_MESSAGE, singleLine } from './format.js';
 import { parseJsonResponse, requestText } from './network.js';
 import { fetchSkillText } from './skill-fetch.js';
 import { AGENT_API_ERROR_CODES, } from '../types.js';
@@ -12,6 +12,13 @@ export class VigilbaseApiError extends Error {
     reason;
     /** CLI-authored remediation, never server text (see one-error-hints.ts). */
     hint;
+    /**
+     * The message is the CLI's own text, never the server's, so formatError prints it although the
+     * error carries a body. Unmarked errors with a body print only a generic `Request failed`.
+     */
+    isCliAuthored;
+    /** The One tool run a failed scan recorded. */
+    toolRunId;
     constructor(message, options) {
         super(message);
         this.name = 'VigilbaseApiError';
@@ -21,6 +28,8 @@ export class VigilbaseApiError extends Error {
         this.code = options.code;
         this.reason = options.reason;
         this.hint = options.hint;
+        this.isCliAuthored = options.isCliAuthored ?? false;
+        this.toolRunId = options.toolRunId;
     }
 }
 export function retryAfterSeconds(response, body) {
@@ -61,6 +70,7 @@ function problemReason(response, body) {
     const message = singleLine(problem.data.error.message);
     return message ? { code: code.data, message } : undefined;
 }
+/** `fallback` is the CLI's own message, used when com gave no reason it accepts. */
 function publicApiError(fallback, response, body) {
     const reason = problemReason(response, body);
     return new VigilbaseApiError(reason?.message ?? fallback, {
@@ -69,6 +79,7 @@ function publicApiError(fallback, response, body) {
         retryAfterSec: retryAfterSeconds(response, body),
         code: reason?.code,
         reason: reason?.message,
+        isCliAuthored: !reason,
     });
 }
 /** The versioned public tools API. The unversioned /api/agent/tools aliases sunset on 2027-09-01. */
@@ -131,7 +142,7 @@ export class VigilbaseClient {
             throw new VigilbaseApiError('Invalid tool execution response. Check the API URL or retry later.', { status: response.status });
         }
         if (!parsed.success) {
-            throw publicApiError('Tool execution was unsuccessful.', response, body);
+            throw publicApiError(SCAN_FAILED_MESSAGE, response, body);
         }
         return parsed;
     }

package/dist/lib/format.d.ts

@@ -3,6 +3,8 @@ export type Writer = {
     stdout: (line?: string) => void;
     stderr: (line?: string) => void;
 };
+/** A scan that ended without a result: com's copy (apps/com/lib/tools/execute-internal-scan.ts). */
+export declare const SCAN_FAILED_MESSAGE = "The scan couldn't be completed. Try again later.";
 /** Untrusted API data must never become terminal control sequences or bidi overrides. */
 export declare function sanitizeTerminal(value: string): string;
 /** One sanitised line, cut to `maxLength` characters with an ellipsis. */
@@ -16,5 +18,7 @@ export declare function formatToolsList(catalog: AgentToolsCatalogResponse, mode
     isAuthenticated?: boolean;
 }): void;
 export declare function formatToolDescription(tool: AgentToolDefinition, mode: CliOutputMode, writer: Writer, skillMarkdown?: string): void;
+/** Whether a scan produced a result; the exit code follows it. */
+export declare function isSuccessfulScan(result: AgentToolExecuteResponse): boolean;
 export declare function formatExecuteResult(result: AgentToolExecuteResponse, mode: CliOutputMode, writer: Writer): void;
 export declare function formatError(error: unknown, mode: CliOutputMode, writer: Writer): void;

package/dist/lib/format.js

@@ -1,4 +1,7 @@
 import { stripVTControlCharacters } from 'node:util';
+/** A scan that ended without a result: com's copy (apps/com/lib/tools/execute-internal-scan.ts). */
+export const SCAN_FAILED_MESSAGE = "The scan couldn't be completed. Try again later.";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Untrusted API data must never become terminal control sequences or bidi overrides. */
 export function sanitizeTerminal(value) {
     return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
@@ -245,27 +248,42 @@ export function formatToolDescription(tool, mode, writer, skillMarkdown) {
         writer.stdout(skillMarkdown.trimEnd());
     }
 }
+/**
+ * Why a scan failed, or null when it has a result. A scan com could not grade comes back
+ * inside a successful response as `status: "error"` with a message and no grade.
+ */
+function scanFailure(result) {
+    if (result.success && result.result?.status !== 'error')
+        return null;
+    const message = result.result?.status === 'error'
+        ? result.result.message
+        : result.success ? undefined : typeof result.error === 'string' ? result.error : result.error?.message;
+    // Vigilbase's scanner wrote it, but it is bounded like any server reason.
+    return (typeof message === 'string' && singleLine(message)) || SCAN_FAILED_MESSAGE;
+}
+/** Whether a scan produced a result; the exit code follows it. */
+export function isSuccessfulScan(result) {
+    return scanFailure(result) === null;
+}
 export function formatExecuteResult(result, mode, writer) {
+    const failure = scanFailure(result);
     if (mode === 'json') {
-        printJson(writer, result);
+        // A scan without a result fails in JSON as in the exit code.
+        // A failed scan has no grade, whatever placeholder the scanner used.
+        printJson(writer, failure === null ? result : { ...result, success: false, error: failure, grade: null, gradeScore: null });
         return;
     }
     const tool = result.toolName ?? 'tool';
     const target = result.target ?? '';
-    const grade = result.grade != null
+    const grade = failure === null && result.grade != null
         ? `${result.grade}${result.gradeScore != null ? ` ${result.gradeScore}` : ''}`
         : 'n/a';
-    const head = result.success
-        ? `✓ ${tool} · ${target} · ${grade}`
-        : `✗ ${tool} · ${target} · ${grade}`;
-    if (result.success)
-        writer.stdout(head);
-    else
-        writer.stderr(head);
-    const error = typeof result.error === 'string' ? result.error : result.error?.message;
-    if (error) {
-        writer.stderr(`  ${error}`);
+    if (failure !== null) {
+        writer.stderr(`✗ ${tool} · ${target} · ${grade}`);
+        writer.stderr(`  ${failure}`);
+        return;
     }
+    writer.stdout(`✓ ${tool} · ${target} · ${grade}`);
     for (const line of summarizeResultCompact(result.result)) {
         writer.stdout(`  ${line}`);
     }
@@ -273,7 +291,8 @@ export function formatExecuteResult(result, mode, writer) {
 export function formatError(error, mode, writer) {
     let message = error instanceof Error ? error.message : String(error);
     let reason = '';
-    // Server bodies can contain credentials, customer data, or arbitrary error text.
+    // Server bodies can contain credentials, customer data, or arbitrary error text, so an error that
+    // carries one shows only text the CLI wrote, or the reason the public client accepted.
     if (error && typeof error === 'object' && 'body' in error && error.body != null && 'status' in error && typeof error.status === 'number') {
         if ('code' in error && error.code === 'FLAREHAWK_VIEW_AS_REQUIRED') {
             message = 'Select a customer with --customer-id <customer UUID> for security commands.';
@@ -281,7 +300,8 @@ export function formatError(error, mode, writer) {
         else {
             // Only the reason the public client accepted from a known problem+json error is shown.
             reason = 'reason' in error && typeof error.reason === 'string' ? singleLine(error.reason) : '';
-            message = reason || `Request failed (HTTP ${error.status}).`;
+            const isCliAuthored = 'isCliAuthored' in error && error.isCliAuthored === true;
+            message = reason || (isCliAuthored ? message : `Request failed (HTTP ${error.status}).`);
         }
     }
     const payload = {
@@ -310,6 +330,10 @@ export function formatError(error, mode, writer) {
             if (hint)
                 payload.hint = hint;
         }
+        // The One tool run a failed scan recorded, for `vigilbase runs get`.
+        if ('toolRunId' in error && typeof error.toolRunId === 'string' && UUID.test(error.toolRunId)) {
+            payload.toolRunId = error.toolRunId;
+        }
     }
     if (mode === 'json') {
         printJson(writer, payload);

package/dist/lib/one-client.d.ts

@@ -7,6 +7,8 @@ import type { CliConfig } from './config.js';
 export type OneToolExecuteResponse = {
     success: boolean;
     error?: string;
+    /** `scan_unassessed`: the scanner ran but could not assess the target. */
+    code?: string;
     data?: {
         toolRunId?: string;
         status?: string;

package/dist/lib/one-client.js

@@ -7,6 +7,7 @@ import { validateOneOrigin } from './config.js';
 import { validateStripePortalUrl } from './open-url.js';
 import { parseJsonResponse, requestText } from './network.js';
 import { oneErrorHint } from './one-error-hints.js';
+import { SCAN_FAILED_MESSAGE } from './format.js';
 import { retryAfterSeconds, VigilbaseApiError } from './client.js';
 /**
  * Tools that require Vigilbase One authentication (auth-required scanners).
@@ -133,9 +134,12 @@ export class VigilbaseOneClient {
         const hint = response.ok ? undefined : oneErrorHint({
             method: init?.method ?? 'GET', path, status: response.status, code: errorDetails.code, hasCustomerScope: options?.hasCustomerScope,
         });
+        // Every message below is the CLI's own; One's error text stays in the body, which is never printed.
         if (response.status === 401 || response.status === 403) {
-            throw new VigilbaseApiError(message ||
-                'Authentication required. Run `vigilbase login`.', { status: response.status, body: parsed, code: errorDetails.code, hint });
+            throw new VigilbaseApiError(message || (response.status === 401
+                ? 'Authentication required. Run `vigilbase login`.'
+                // Signed in, but One refuses this user or this request: logging in again won't help.
+                : "You don't have access to this."), { status: response.status, body: parsed, code: errorDetails.code, hint, isCliAuthored: true });
         }
         if (response.status === 429) {
             throw new VigilbaseApiError(message || 'Rate limit exceeded.', {
@@ -143,18 +147,21 @@ export class VigilbaseOneClient {
                 body: parsed,
                 retryAfterSec: retryAfterSeconds(response, body),
                 code: errorDetails.code,
+                isCliAuthored: true,
             });
         }
         const allowed = options?.allowStatuses ?? [];
         if (!response.ok && !allowed.includes(response.status)) {
             throw new VigilbaseApiError(message ||
-                `Request failed (HTTP ${response.status})`, { status: response.status, body: parsed, code: errorDetails.code, hint });
+                `Request failed (HTTP ${response.status}).`, { status: response.status, body: parsed, code: errorDetails.code, hint, isCliAuthored: true });
         }
         if (!z.record(z.string(), z.unknown()).safeParse(body).success) {
             throw new VigilbaseApiError('Invalid One API response. Expected a JSON object.', { status: response.status });
         }
         if (parsed.success === false || ('ok' in parsed && parsed.ok === false)) {
-            throw new VigilbaseApiError('One API reported an unsuccessful operation.', { status: response.status, body: parsed, code: errorDetails.code });
+            throw new VigilbaseApiError('One API reported an unsuccessful operation.', {
+                status: response.status, body: parsed, code: errorDetails.code, isCliAuthored: true,
+            });
         }
         return parsed;
     }
@@ -188,7 +195,7 @@ export class VigilbaseOneClient {
         }
         const { response, body } = await this.request('/api/auth/get-session');
         if (!response.ok) {
-            throw new VigilbaseApiError(`Failed to load One session (HTTP ${response.status})`, { status: response.status, body });
+            throw new VigilbaseApiError(`Failed to load One session (HTTP ${response.status})`, { status: response.status, body, isCliAuthored: true });
         }
         const schema = z.object({
             session: z.record(z.string(), z.unknown()).nullable().optional(),
@@ -283,10 +290,70 @@ export class VigilbaseOneClient {
         return this.requestJson(`/api/tool-runs/${encodeURIComponent(id)}`);
     }
     async executeTool(toolName, target) {
-        return this.requestJson(`/api/tools/${encodeURIComponent(toolName)}/execute`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ target }),
-        }, { allowStatuses: [422] });
+        try {
+            return await this.requestJson(`/api/tools/${encodeURIComponent(toolName)}/execute`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ target }),
+            }, { allowStatuses: [422] });
+        }
+        catch (error) {
+            const unassessed = unassessedScan(error);
+            if (unassessed)
+                return unassessed;
+            throw failedScanError(error) ?? error;
+        }
     }
 }
+/** One's answer when the scan itself failed, for example when com ran out of memory. */
+const failedScanSchema = z.object({
+    success: z.literal(false),
+    data: z.object({ status: z.literal('failed'), toolRunId: z.unknown().optional() }).passthrough(),
+}).passthrough();
+const unassessedScanSchema = z.object({
+    code: z.literal('scan_unassessed'),
+    data: z.object({
+        toolRunId: z.unknown().optional(),
+        result: z.object({ status: z.literal('error'), message: z.string() }).passthrough(),
+    }),
+});
+/**
+ * A scan the scanner ran but could not assess (a bot verification challenge, an
+ * error page). The result carries the scanner's message, which the formatter
+ * prints bounded like any scanner result; One's error text stays unused.
+ */
+function unassessedScan(error) {
+    if (!(error instanceof VigilbaseApiError) || error.status !== 422)
+        return undefined;
+    const unassessed = unassessedScanSchema.safeParse(error.body);
+    if (!unassessed.success)
+        return undefined;
+    const toolRunId = z.string().uuid().safeParse(unassessed.data.data.toolRunId);
+    return {
+        success: false,
+        code: 'scan_unassessed',
+        data: {
+            toolRunId: toolRunId.success ? toolRunId.data : undefined,
+            status: 'failed',
+            grade: null,
+            gradeScore: null,
+            result: unassessed.data.data.result,
+        },
+    };
+}
+/** com's copy for a 422 failed scan, with the run One recorded; One's error text stays hidden. */
+function failedScanError(error) {
+    if (!(error instanceof VigilbaseApiError) || error.status !== 422)
+        return undefined;
+    const failed = failedScanSchema.safeParse(error.body);
+    if (!failed.success)
+        return undefined;
+    const toolRunId = z.string().uuid().safeParse(failed.data.data.toolRunId);
+    return new VigilbaseApiError(SCAN_FAILED_MESSAGE, {
+        status: 422,
+        body: error.body,
+        code: error.code,
+        isCliAuthored: true,
+        toolRunId: toolRunId.success ? toolRunId.data : undefined,
+    });
+}

package/dist/types.d.ts

@@ -53,6 +53,10 @@ export type AgentToolExecuteResponse = {
     error?: AgentApiError | string | null;
     uiUrl?: string;
     skillUrl?: string;
+    /** A One scan the scanner could not assess: One's status and code, and the run it recorded. */
+    status?: number;
+    code?: string;
+    toolRunId?: string;
     retryAfterSec?: number;
     toolsUrl?: string;
     skillsIndex?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vigilbase/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Vigilbase CLI — security scanners, agent tools, and Vigilbase One from the terminal.",
   "keywords": [
     "vigilbase",