@hunt-labs/bytekit-cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -10,6 +10,74 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-08-07
+
+### Breaking
+
+- **A not-ready `screenshots get -o` / `screenshots create -o` now exits `2` and prints the bare
+  `ss_` id, instead of exiting `1` with `not ready yet: screenshot is pending`.** The two poll
+  commands disagreed: `scrape get --raw` on a still-queued scrape already wrote the bare `sc_` id
+  to stdout and exited `2` — a distinct, scriptable "accepted but not ready" signal — while the
+  screenshots side reported the same state as a failure and threw the handle away, so a polling
+  script could branch on "queued" for one command and not the other. The screenshots branch now
+  mirrors scrape exactly: bare `ss_` id on stdout, a poll note on stderr, exit `2`, and (as before)
+  no file written. A script that treated any non-zero exit as "this screenshot failed" now sees `2`
+  for a job that is merely still running — branch on the code (`2` = poll again, `1` = failed)
+  rather than on non-zero. Three states deliberately do **not** move: a terminally `failed`
+  screenshot stays exit `1` with its error surfaced (it will never complete, so a "poll again"
+  signal would loop a script forever), an envelope carrying no `ss_` id stays exit `1` (there is no
+  handle to hand back), and `--json` keeps the envelope at exit `0`.
+- **`--json` on a `fetch` command now emits `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` and
+  `X-Fetch-Url`.** The metadata keys were derived by a generic segment-wise Title-Caser, which
+  lowercases every non-initial character of a segment — so the two acronym-bearing headers came out
+  in a spelling the API reference never uses, and a `jq '."X-Fetch-ID"'` filter written from the
+  docs returned `null`. All 16 `X-Fetch-*` keys now match the spec names byte-for-byte. The
+  **values** are unchanged, the non-`X-Fetch-*` headers stay filtered out, and every other key
+  (`X-Fetch-Waf-Vendor`, `X-Fetch-Duration-Ms`, `X-Fetch-Fast-Path`, …) is spelled exactly as
+  before. A consumer reading `.["X-Fetch-Id"]` must switch to `.["X-Fetch-ID"]`.
+
+### Fixed
+
+- **A `screenshots get -o` / `screenshots create -o` poll only says "poll again" for a `pending` or
+  `processing` screenshot.** The not-ready predicate decided from the presence of an `image_url`,
+  an `id` and a nested error alone — `status` was read only to phrase the message — so a
+  `completed` screenshot whose `image_url` never materialized, a status outside the closed enum,
+  and the flat `error_code`/`error_message` failed shape all received exit `2` and "no image
+  artifact is available yet. Poll it with: …" for a job that would never complete. Those states now
+  exit `1`: a terminal failure prints `screenshot failed: …`, and any other artifact-less state
+  prints `no image artifact available: screenshot is <status>`. Genuine `pending` / `processing`
+  polls keep the bare `ss_` id, the poll note and exit `2` exactly as before — **including** a
+  poll whose envelope carries an `error_code` from an attempt that failed and is being retried,
+  since the status, not the error, decides whether polling can still help. `--json` still prints
+  the envelope at exit `0`.
+- **A terminally failed screenshot reported through the spec's flat `error_code`/`error_message`
+  fields now reaches stderr.** Only the nested `{error:{code,message}}` envelope was read, so the
+  shape `ScreenshotResponse` actually declares surfaced neither code nor message. It now prints
+  `screenshot failed: <message> (<code>)` — the formatting `scrape get --raw` already uses for a
+  failed scrape. The nested envelope's own message is unchanged.
+- **`scrape get --raw` on a terminally failed scrape now reports why it failed.** It printed
+  `--raw: response contains no formats` — technically true of a `ScrapeErrorEnvelope`, and the one
+  diagnostic that cannot explain anything — while the envelope's own `error.code` and
+  `error.message` never reached the caller. Both now go to stderr (exit `1`, unchanged). The
+  failure is reported ahead of the format diagnostics, so an envelope carrying both a failure and
+  an empty `formats: {}` still says why it failed rather than pointing at a `--format` choice that
+  cannot help.
+- **An empty-formats success now names the warning that explains it.** A completed scrape whose
+  persisted artifact could not be rehydrated comes back with `formats: {}` and an
+  `artifact_unavailable` warning; `--raw` rendered that as `--raw requires --format when the
+response contains multiple formats`, which is false on both counts. It now names the warning's
+  code and message, or says plainly that the formats map is empty when no warning explains it.
+- **Error paths no longer risk losing their own diagnostic.** `handleError` and the missing-API-key
+  path each wrote to stderr and then immediately hard-`process.exit(1)`. Node's stderr is
+  asynchronous when it points at a pipe, and `process.exit` discards whatever is still queued — so
+  the one line a script greps was the line most at risk of being thrown away, which is exactly the
+  defect this package's flush policy exists to prevent. Both now set `process.exitCode` and let the
+  process end naturally once stderr has drained. The exit codes and the rendered messages are
+  byte-identical.
+- `--headers`, `--custom` and `--metadata` said `must be valid JSON (a object)` on a malformed
+  value; the article now agrees — `an object` / `an array`.
+- The `[0.6.0]` link reference, missing from the bottom of this file, is restored.
+
 ## [0.6.0] - 2026-07-29
 
 ### Breaking
@@ -65,7 +133,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 - `--metadata` on `monitors create`, and `--metadata` + `--url` on `monitors update`. `--type`
   remains deliberately absent from `update` — it is immutable server-side.
 
-## [0.5.1] - 2026-07-28
+## [0.5.1] - 2026-07-28 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.5.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.5.1` fails. Everything below shipped to users in
+> **0.6.0**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Fixed
 
@@ -188,7 +261,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   `sc_` id** on stdout with a note on stderr (it does not print the queued job
   envelope). (#2544)
 
-## [0.4.0] - 2026-07-23
+## [0.4.0] - 2026-07-23 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.4.0`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.4.0` fails. Everything below shipped to users in
+> **0.5.0**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Removed (**BREAKING**)
 
@@ -209,7 +287,13 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   **Replacement:** manage API keys from the dashboard at
   [app.bytekit.com](https://app.bytekit.com). (#2536)
 
-## [0.3.1] - 2026-07-22
+## [0.3.1] - 2026-07-22 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.3.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.3.1` fails. Everything below shipped to users in
+> **0.5.0**, which is the first published release containing it (0.4.0 was never published either —
+> see its heading above). Reconciled by issue #2680; the `release-drift` CI gate now blocks a new
+> phantom heading from being introduced.
 
 ### Fixed
 
@@ -292,7 +376,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   rebuilding the shared `dist`), which is now fixed. No consumer-facing changes
   beyond 0.2.1.
 
-## [0.2.1] - 2026-07-16
+## [0.2.1] - 2026-07-16 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-cli@0.2.1`
+> tarball exists — `npm i @hunt-labs/bytekit-cli@0.2.1` fails. Everything below shipped to users in
+> **0.2.2**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Changed
 
@@ -342,6 +431,8 @@ Additive, lower-risk release — no breaking changes to existing commands.
   subcommands, published under the original `rapidcrawl-cli` name.
 
 [Unreleased]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.7.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
+[0.6.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.5.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.5.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli
 [0.4.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/cli

package/README.md

@@ -172,6 +172,17 @@ response metadata instead of the body. `-o <file>` writes the body bytes to a
 file byte-for-byte (with `--json`, the metadata object goes to the file
 instead). `fetch bulk` returns an ordinary JSON job envelope.
 
+The `--json` metadata keys are the **spec header names exactly** as the API
+reference declares them, so a filter written from the docs works unchanged:
+
+```bash
+bytekit fetch get --url https://example.com --json | jq -r '."X-Fetch-ID"'
+```
+
+Note the acronym casing — `X-Fetch-ID` and `X-Fetch-URL`, not `X-Fetch-Id` /
+`X-Fetch-Url`. (Versions up to 0.6.0 emitted the Title-Cased spellings; see the
+CHANGELOG.)
+
 Both verbs accept `--country <cc>`, `--timeout-ms <n>`, and `--cache-ttl <ttl>`
 (`0`, `Nh`, or `Nd`), each omitted when absent. `--markdown-mode`
 (`article`, `raw`, `llm`) is `fetch create` only.
@@ -303,11 +314,34 @@ omitted when absent. `retry <id>` requeues a failed or exhausted delivery.
 
 ## Exit codes
 
-| Code | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `0`  | Success.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `1`  | Usage error, or an API/connection error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `2`  | The job was accepted but is still **queued**, so there is no content body or artifact to emit. Applies to `scrape create --async` with `--raw` or a bare `-o` (which writes the bare `sc_` id to stdout) and in human mode, and to `screenshots create --async` in human mode (including with `-o`, which deliberately writes no file). Not a failure: the job was accepted and billed. Poll it with `bytekit scrape get <id>` / `bytekit screenshots get <id>`. **`--json` keeps exit `0` in both cases** — the queued envelope is a complete machine-readable payload. |
+| Code | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0`  | Success.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `1`  | Usage error, or an API/connection error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `2`  | The job was accepted but is **not ready**, so there is no content body or artifact to emit. Applies to `scrape create --async` with `--raw` or a bare `-o` (which writes the bare `sc_` id to stdout) and in human mode; to `scrape get --raw`/`-o` on a still-queued job (bare `sc_` id to stdout); to `screenshots create --async` in human mode (including with `-o`, which deliberately writes no file); and to `screenshots create -o` / `screenshots get -o` on a pending or processing screenshot (bare `ss_` id to stdout, no file written). Not a failure: the job was accepted and billed. Poll it with `bytekit scrape get <id>` / `bytekit screenshots get <id>`. **`--json` keeps exit `0` in every case** — the envelope is a complete machine-readable payload. |
+
+A **terminally failed** job is NOT code `2` — it will never complete, so it is
+exit `1` with the reason on stderr. `scrape get --raw` on a failed scrape prints
+that scrape's own `error.code` and message, and `screenshots get -o` on a failed
+screenshot prints `screenshot failed: …`.
+
+Only `pending` and `processing` earn code `2`. Any other screenshot state that
+still has no artifact — a `completed` screenshot whose `image_url` never
+materialized, or a status this CLI build does not know — is exit `1` with
+`no image artifact available: screenshot is <status>` on stderr, because
+polling it again cannot change the outcome.
+
+The status is what decides, not the presence of an error. A `pending` or
+`processing` screenshot that reports an `error_code` from an attempt that failed
+and is being **retried** is still code `2` with its `ss_` id — the job has not
+finished, and abandoning it there would throw away a capture the server is still
+working on.
+
+A **human-mode poll without `-o`/`--raw`** stays exit `0` whatever the job's
+state: `bytekit scrape get <id>` and `bytekit screenshots get <id>` were asked
+for the envelope, and the envelope is exactly what they printed — the status
+field in it is the answer. Code `2` is reserved for the case where you asked for
+a **body or artifact** that does not exist yet.
 
 The stderr message for exit code `1` has two shapes, depending on where the
 error originates:
@@ -334,6 +368,18 @@ case $? in
 esac
 ```
 
+The same branch works for a screenshot poll, because both commands now signal
+"not ready" identically:
+
+```bash
+ss_id=$(bytekit screenshots get "$ss_id" -o shot.png)
+case $? in
+  0) echo "downloaded shot.png" ;;
+  2) echo "$ss_id not ready — poll again" ;;
+  *) exit 1 ;;                 # terminal failure, reason on stderr
+esac
+```
+
 ## Documentation
 
 Full API reference: [bytekit.com/docs](https://bytekit.com/docs).

package/dist/client.d.ts

@@ -167,7 +167,21 @@ export declare function createRetryingRequestWithResponse(apiKey: string, baseUr
  * Resolution order (explicit input beats environment):
  *   apiKey:  --key flag → BYTEKIT_API_KEY.
  *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
- * Exits with a descriptive error when no key is available.
+ *
+ * THROWS a plain `Error` when no key is available (#2686 item 4). It used to `console.error` and
+ * then hard-exit — an async stderr write followed immediately by the one call that discards
+ * the userspace stdio queue, which is exactly the defect the package's #2544 flush policy exists to
+ * prevent. Throwing stops just as hard (there is no client to return, E4) while routing the message
+ * through `handleError`, whose soft `process.exitCode` lets stderr drain first. The rendered stderr
+ * line is byte-identical: `handleError` supplies the `Error: ` prefix, and a plain Error carries
+ * neither a status nor a ByteKit code, so no parenthesised suffix is added.
+ *
+ * Because it throws, EVERY caller invokes it from inside its action's `try` block. `index.ts` drives
+ * commander with `.parse()`, not `.parseAsync()`, so nothing awaits an action's promise: a throw
+ * raised above the try would escape as an unhandled rejection and print a raw stack trace instead of
+ * the clean one-liner — the same constraint `commands/scrape.ts` already documents for
+ * `resolveOutputMode`. `error-exit-contract.test.ts` pins that placement structurally, across every
+ * call site at once.
  *
  * The returned client's `request`, `requestRaw`, AND `requestWithResponse` are all replaced by the
  * retrying transports, so every command inherits the 429 retry — JSON commands via `request`, the

package/dist/client.js

@@ -492,7 +492,21 @@ function normalizeBaseUrl(url) {
  * Resolution order (explicit input beats environment):
  *   apiKey:  --key flag → BYTEKIT_API_KEY.
  *   baseUrl: --base-url flag → BYTEKIT_BASE_URL → DEFAULT_BASE_URL.
- * Exits with a descriptive error when no key is available.
+ *
+ * THROWS a plain `Error` when no key is available (#2686 item 4). It used to `console.error` and
+ * then hard-exit — an async stderr write followed immediately by the one call that discards
+ * the userspace stdio queue, which is exactly the defect the package's #2544 flush policy exists to
+ * prevent. Throwing stops just as hard (there is no client to return, E4) while routing the message
+ * through `handleError`, whose soft `process.exitCode` lets stderr drain first. The rendered stderr
+ * line is byte-identical: `handleError` supplies the `Error: ` prefix, and a plain Error carries
+ * neither a status nor a ByteKit code, so no parenthesised suffix is added.
+ *
+ * Because it throws, EVERY caller invokes it from inside its action's `try` block. `index.ts` drives
+ * commander with `.parse()`, not `.parseAsync()`, so nothing awaits an action's promise: a throw
+ * raised above the try would escape as an unhandled rejection and print a raw stack trace instead of
+ * the clean one-liner — the same constraint `commands/scrape.ts` already documents for
+ * `resolveOutputMode`. `error-exit-contract.test.ts` pins that placement structurally, across every
+ * call site at once.
  *
  * The returned client's `request`, `requestRaw`, AND `requestWithResponse` are all replaced by the
  * retrying transports, so every command inherits the 429 retry — JSON commands via `request`, the
@@ -511,8 +525,7 @@ function normalizeBaseUrl(url) {
 export function buildClient(opts) {
     const apiKey = opts.key ?? process.env['BYTEKIT_API_KEY'];
     if (!apiKey) {
-        console.error('Error: API key required. Pass --key or set BYTEKIT_API_KEY.');
-        process.exit(1);
+        throw new Error('API key required. Pass --key or set BYTEKIT_API_KEY.');
     }
     const baseUrl = normalizeBaseUrl(opts.baseUrl ?? process.env['BYTEKIT_BASE_URL'] ?? DEFAULT_BASE_URL);
     const client = new ByteKit({ apiKey, baseUrl });

package/dist/commands/account.js

@@ -19,8 +19,9 @@ export function makeAccountCommand(getGlobal) {
         .description('Get the authenticated account')
         .action(async () => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.account.get();
             printResult(result, g.json);
         }

package/dist/commands/bulk.js

@@ -11,8 +11,9 @@ export function makeBulkCommand(getGlobal) {
         .description('List screenshots in a bulk job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.bulk.screenshots.list(id);
             printResult(result, g.json);
         }
@@ -33,8 +34,9 @@ export function makeBulkCommand(getGlobal) {
         // property (validators/bulk.ts:135), so the flag would 422 every call (#2596 drift D2).
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const lines = parseBulkLines(opts.file);
             // `urls` XOR `items` (validators/bulk.ts:136-155) — send exactly one. A file of only
             // url-only lines keeps the pre-#2596 `{ urls, webhook_url }` body, key order included,
@@ -60,8 +62,9 @@ export function makeBulkCommand(getGlobal) {
         .description('Get a bulk job status')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.bulk.get(id);
             printResult(result, g.json);
         }
@@ -74,8 +77,9 @@ export function makeBulkCommand(getGlobal) {
         .description('Cancel an in-flight bulk job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.bulk.cancel(id);
             printResult(result, g.json);
         }

package/dist/commands/fetch.js

@@ -41,8 +41,9 @@ export function makeFetchCommand(getGlobal) {
         // FetchBulkItemOverrideSchema reject unknown keys), so this top-level behavior is unchanged.
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // /v1/fetch/bulk has NO `items` property — its `urls` is a
             // `string | FetchBulkItemOverride` union (validators/fetch-bulk.ts:57), so both line
             // shapes ride there directly and no promotion step is needed (#2596 drift D3).
@@ -66,8 +67,9 @@ export function makeFetchCommand(getGlobal) {
         .description('Get a bulk fetch job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.fetch.bulk.get(id);
             printResult(result, g.json);
         }
@@ -101,7 +103,6 @@ export function makeFetchCommand(getGlobal) {
         .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Omit-when-absent body, in the `body: Record<string, unknown>` form every other command
         // file uses (scrape.ts:230-268 is the exemplar). The five pre-existing fields keep the
         // exact same wire output they had as inline spreads; a boolean is written ONLY on
@@ -140,6 +141,8 @@ export function makeFetchCommand(getGlobal) {
         if (opts.custom !== undefined)
             body['custom'] = opts.custom;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.fetch.create(body);
             emitFetchResult(result, g.json, { file: opts.output });
         }
@@ -158,8 +161,9 @@ export function makeFetchCommand(getGlobal) {
         .option('-o, --output <file>', 'Write the fetched body bytes to the given file path')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.fetch.get({
                 url: opts.url,
                 ...(opts.format !== undefined ? { format: opts.format } : {}),

package/dist/commands/monitors.js

@@ -24,7 +24,6 @@ export function makeMonitorsCommand(getGlobal) {
         .option('--cursor <cursor>', 'Pagination cursor from a previous page')
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Same omit-when-absent rule as `monitors list` (#2480): build the params object with
         // ONLY the flags the caller passed, and call captures.list with a single argument (never
         // captures.list(id, {}) / captures.list(id, undefined)) when no query flag is passed, so
@@ -35,6 +34,8 @@ export function makeMonitorsCommand(getGlobal) {
         if (opts.cursor !== undefined)
             params.cursor = opts.cursor;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.monitors.captures.list(id, params)
                 : await client.monitors.captures.list(id);
@@ -49,6 +50,14 @@ export function makeMonitorsCommand(getGlobal) {
         .command('create')
         .description('Create a page-change monitor')
         .requiredOption('--url <url>', 'URL to monitor')
+        // `--interval-type` is passed through VERBATIM and validated by the API, not locally — a
+        // deliberate choice recorded for #2686 item 5's open question, matching what `search`'s
+        // `--type`/`--date-range` already do. A local enum list is a second source of truth that
+        // drifts from the spec silently: the CLI would start rejecting a value the API has begun
+        // accepting, and the error text would come from a stale copy rather than the server. The
+        // siblings that DO validate locally (`--type`, `--markdown-mode`, `--device`, …) are the
+        // enums this package chose to pin; nothing here should be read as those being wrong, only as
+        // the pass-through being intentional rather than an oversight.
         .requiredOption('--interval-type <type>', 'Check interval: hourly, daily, weekly, or cron')
         .requiredOption('--webhook-url <url>', 'HTTPS webhook URL notified on change')
         .option('--cron <expr>', 'Cron expression (required when --interval-type is cron, e.g. "0 * * * *")')
@@ -64,7 +73,6 @@ export function makeMonitorsCommand(getGlobal) {
         .option('--metadata <json>', `Arbitrary metadata echoed on the monitor envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Omit-when-absent body (same rule as scrape.ts): each key is written ONLY when its flag is
         // present, so a bare create never materializes a server default (#2480 E1). Typed via an
         // assertion at the call site — the wire body is pinned by request-shapes.test.ts.
@@ -92,6 +100,8 @@ export function makeMonitorsCommand(getGlobal) {
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.create(body);
             printResult(result, g.json);
         }
@@ -110,7 +120,6 @@ export function makeMonitorsCommand(getGlobal) {
         // with no runtime change.
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Build the params object with the same omit-when-absent rule as the body builders. When NO
         // query flag is passed, call list() with ZERO arguments (never list({}) / list(undefined)) so
         // the inverse-case request-shape assertion `monitors.list` args length 0 stays green (#2480).
@@ -122,6 +131,8 @@ export function makeMonitorsCommand(getGlobal) {
         if (opts.status !== undefined)
             params.status = opts.status;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.monitors.list(params)
                 : await client.monitors.list();
@@ -136,8 +147,9 @@ export function makeMonitorsCommand(getGlobal) {
         .description('Get a monitor by ID')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.get(id);
             printResult(result, g.json);
         }
@@ -164,7 +176,6 @@ export function makeMonitorsCommand(getGlobal) {
         .option('--metadata <json>', `New metadata as a JSON object, e.g. '{"run":"7"}' (omitted → unchanged)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = {};
         // `url` IS settable on PATCH (openapi.yaml MonitorUpdateRequest) — unlike `type`, which
         // stays immutable and deliberately has no flag (#1984).
@@ -193,6 +204,8 @@ export function makeMonitorsCommand(getGlobal) {
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.update(id, body);
             printResult(result, g.json);
         }
@@ -205,8 +218,9 @@ export function makeMonitorsCommand(getGlobal) {
         .description('Delete a monitor')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.monitors.delete(id);
             printResult(result, g.json);
         }

package/dist/commands/scrape.js

@@ -55,8 +55,9 @@ export function makeScrapeCommand(getGlobal) {
         .option('--custom <json>', `User payload echoed on every scrape entry, as a JSON object, e.g. '{"job":"1"}' (omitted → none; a per-entry value in --file wins)`, (v) => parseJsonFlag('--custom', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // readFileSync throws ENOENT on missing file — caught by handleError below
             const lines = parseBulkLines(opts.file);
             // `urls` XOR `items` (validators/scrape-bulk.ts:91-98) — send exactly one, keeping the
@@ -84,8 +85,9 @@ export function makeScrapeCommand(getGlobal) {
         .description('Get a bulk scrape job')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.scrape.bulk.get(id);
             printResult(result, g.json);
         }
@@ -101,6 +103,12 @@ export function makeScrapeCommand(getGlobal) {
         // Repeatable AND CSV-aware: `--format raw_html --format markdown` and `--format raw_html,markdown`
         // both send formats: ['raw_html','markdown']. Sent as the `formats` array; omitted → server
         // default. `--raw`/`-o` require EXACTLY ONE format (validated pre-request; see the action).
+        //
+        // The format VALUES travel to the server unvalidated — deliberate, and recorded here for
+        // #2686 item 5's open question (same rationale as `monitors --interval-type` and `search`'s
+        // `--type`/`--date-range`). The persisted-format vocabulary grows with the spec, and a local
+        // enum list is a second source of truth that drifts silently: the CLI would reject a format
+        // the API has begun serving, and the error would come from a stale copy rather than the API.
         .option('--format <format>', 'Output format; repeat or comma-separate for multiple (e.g. --format raw_html --format markdown, or --format raw_html,markdown). Sent as the formats array; omitted → server default.', collectFormats)
         .option('--country <cc>', 'Two-letter country code to route the request through (e.g. us, de)')
         .option('--timeout-ms <n>', 'Per-request timeout in milliseconds', (v) => parseIntFlag('--timeout-ms', v))
@@ -137,7 +145,6 @@ export function makeScrapeCommand(getGlobal) {
         .option('-o, --output <file>', 'Write the output to the given file path (implies --raw unless --json is set)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = { url: opts.url };
         // The v1 scrape validator expects `formats` (array). The --format collector already
         // accumulates repeated/CSV occurrences into an array; write it verbatim, omitting the key
@@ -206,6 +213,8 @@ export function makeScrapeCommand(getGlobal) {
         if (opts.mobile === true)
             body['mobile'] = true;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // FIRST statement inside the try — deliberately NOT hoisted next to buildClient() where
             // the other handlers put pre-request logic. index.ts drives commander with .parse(), not
             // .parseAsync(), so nothing awaits this action's promise: a throw raised above the try
@@ -267,8 +276,9 @@ export function makeScrapeCommand(getGlobal) {
         .option('--format <format>', 'Which persisted format to emit — only takes effect with --raw/-o; ignored otherwise')
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // Mirror `scrape create`'s output path: resolveOutputMode FIRST inside the try (so a
             // --json/--raw conflict rejects before the request), then emitResult. The request body is
             // unchanged — scrape.get(id) takes no options — so the inverse-case arg-length assertion in

package/dist/commands/screenshots.js

@@ -37,16 +37,108 @@ export function parseClip(value) {
  * "queued" without parsing stderr.
  *
  * BREAKING (#2596): `screenshots create --async` previously exited 0. See the README exit-code
- * table and the CHANGELOG `[0.6.0]` note (this version's own section — `[Unreleased]` is kept
- * deliberately empty per `packaging.test.ts:203`; see #2620).
+ * table and the CHANGELOG `[0.6.0]` note (`[Unreleased]` is kept deliberately empty per
+ * `packaging.test.ts:203`; see #2620).
+ *
+ * Also carried by a NOT-READY `screenshots get -o` poll (#2686 item 1) — same meaning, same value:
+ * accepted and billed, artifact not materialized yet.
  */
 const QUEUED_EXIT_CODE = 2;
+/**
+ * The ONLY statuses a screenshot can still reach `completed` from, and therefore the only ones
+ * worth telling a caller to poll (#2792). Every other value of `status` — the terminal ones, and
+ * anything the server may add later — is a state polling cannot improve.
+ */
+const POLLABLE_STATUSES = ['pending', 'processing'];
+/**
+ * A still-pollable screenshot poll that can hand its `ss_` handle back, or undefined.
+ *
+ * "Not ready" is `status === 'pending' || status === 'processing'` and nothing else, plus a usable
+ * `ss_` handle and no materialized `image_url` (#2792). Before that gate existed the predicate
+ * decided from `error`/`image_url`/`id` alone and read `status` only to LABEL the message, so a
+ * `completed` envelope with a null `image_url`, a status outside the enum, and the FLAT
+ * `error_code`/`error_message` failed shape that `serializeScreenshot` emits all received "poll
+ * again" advice for a job that would never complete — the exact loop the exclusion exists to
+ * prevent.
+ *
+ * Two shapes are excluded deliberately rather than incidentally:
+ *
+ * - **No `status` at all (#2792 E1).** Not treated as pending. `serializeScreenshot`
+ *   (`gateway/src/routes/screenshots.ts:365`) always writes `status`, so a statusless envelope is
+ *   not something the server produces; and an envelope carrying no evidence that work is in
+ *   progress is exactly what must not be advertised as pollable. It takes the error path, which
+ *   names the state instead of promising an artifact.
+ * - **A status outside the enum (#2792 E3).** Same reasoning, stated as the closed-set gate: a new
+ *   server status is unknown to this build, so it is reported, never polled and never fallen
+ *   through into the download path.
+ *
+ * And one shape is deliberately NOT excluded: a pollable status carrying a flat `error_code`. That
+ * is the ordinary RETRY envelope, not a verdict — see {@link flatScreenshotFailure}. Excluding it
+ * would abandon a job the server is actively retrying (#2792 B1).
+ *
+ * An envelope with no string `id` is excluded too — there is no handle to emit, so the ordinary
+ * error path (which at least names the status) is the honest outcome.
+ */
+function notReadyScreenshot(result) {
+    if (typeof result !== 'object' || result === null)
+        return undefined;
+    const obj = result;
+    // The gate, not merely the label: `status` decides, and the closed list is the whole decision.
+    const status = POLLABLE_STATUSES.find((s) => s === obj.status);
+    if (status === undefined)
+        return undefined;
+    // The NESTED error envelope stays disqualifying, exactly as before this ticket. A flat
+    // `error_code` is NOT consulted here: on a pollable status it is a retry error (#2792 B1), and
+    // the nested shape can never co-occur with a pollable status to disagree — it is built only by
+    // `buildFailedScreenshotEnvelope`, under `status === 'failed'` (`routes/screenshots.ts:267`).
+    if (obj.error !== undefined && obj.error !== null)
+        return undefined;
+    if (typeof obj.image_url === 'string' && obj.image_url.length > 0)
+        return undefined;
+    if (typeof obj.id !== 'string' || obj.id.length === 0)
+        return undefined;
+    return { id: obj.id, status };
+}
+/**
+ * The failure carried by the FLAT `error_code`/`error_message` fields, or undefined (#2792).
+ *
+ * `serializeScreenshot` (gateway `routes/screenshots.ts:365`) — and therefore the spec's own
+ * `ScreenshotResponse` — reports a failure as top-level `error_code`/`error_message`, while
+ * `buildFailedScreenshotEnvelope` (`:295`, #2027) reports it NESTED as `{error:{code,message}}`.
+ * Only the nested one was ever read, so a flat failure surfaced neither code nor message.
+ *
+ * These two are NOT interchangeable, which is why this helper reads only one of them:
+ *
+ * - The nested envelope is built only under `status === 'failed'` (`routes/screenshots.ts:267`), so
+ *   it is always terminal.
+ * - The flat columns are ALSO written by the non-terminal retry path — `job-queue.ts:346-356` sets
+ *   `error_code`/`error_message` and `status = 'pending'` in one UPDATE, and `claim()` (`:276-284`)
+ *   carries them into the next `processing` attempt. On a pollable status they describe the attempt
+ *   that just failed, not the job's outcome (#2792 B1).
+ *
+ * So the caller consults this only once the status is no longer pollable.
+ */
+function flatScreenshotFailure(obj) {
+    const detail = {};
+    if (typeof obj.error_code === 'string' && obj.error_code.length > 0)
+        detail.code = obj.error_code;
+    if (typeof obj.error_message === 'string' && obj.error_message.length > 0)
+        detail.message = obj.error_message;
+    return detail.code === undefined && detail.message === undefined ? undefined : detail;
+}
 /**
  * Extract a non-empty string `image_url` from a screenshot envelope, or throw an actionable error.
  *
- * A pending/processing envelope has no `image_url` yet; a terminal-`failed` screenshot returns the
- * unified `Error` envelope on a 200 (#2027). Either way the artifact was never materialized, so we
- * throw rather than fetching `undefined` (#2480 E5).
+ * A pending/processing envelope has no `image_url` yet; a terminal-`failed` screenshot reports its
+ * failure either nested or flat. Either way the artifact was never materialized, so we throw rather
+ * than fetching `undefined` (#2480 E5).
+ *
+ * The NESTED shape's message is untouched by #2792 — the ticket's Specification pins it as an
+ * inverse case ("the nested-error failed shape keeps its current exit-1 message"), and it is now
+ * pinned by an exact-equality test rather than the substring assertions that would not have
+ * noticed. The FLAT shape, which previously reported nothing at all, names both of its fields as
+ * `<message> (<code>)` — `extractRawBody`'s format for a failed scrape, so the two poll commands
+ * read alike — degrading to whichever field exists.
  */
 function extractImageUrl(result) {
     if (typeof result === 'object' && result !== null) {
@@ -58,8 +150,28 @@ function extractImageUrl(result) {
             return obj.image_url;
         }
         const status = typeof obj.status === 'string' ? obj.status : 'unknown';
-        throw new Error(`not ready yet: screenshot is ${status}`);
+        // "not ready yet" is reserved for a genuinely pollable state (#2792). It is still reachable
+        // here for a pending/processing envelope carrying no `ss_` id — `notReadyScreenshot` rejects
+        // those for want of a handle, and this message stays their wording. Reached BEFORE the flat
+        // failure below, because on a pollable status those columns describe the attempt that just
+        // failed and is being retried, not the job's outcome (#2792 B1).
+        if (POLLABLE_STATUSES.includes(status)) {
+            throw new Error(`not ready yet: screenshot is ${status}`);
+        }
+        const flat = flatScreenshotFailure(obj);
+        if (flat !== undefined) {
+            const reason = flat.message !== undefined && flat.code !== undefined
+                ? `${flat.message} (${flat.code})`
+                : (flat.message ?? flat.code ?? 'unknown error');
+            throw new Error(`screenshot failed: ${reason}`);
+        }
+        // Every other artifact-less state says so rather than implying the artifact soon will exist: a
+        // `completed` row with a null `image_url`, and any status this build does not know.
+        throw new Error(`no image artifact available: screenshot is ${status}`);
     }
+    // The non-object arm keeps its original wording, pinned by #2480 cr-5
+    // (`screenshot-download.test.ts:287`): this is not a screenshot envelope at all, so neither the
+    // status gate above nor its vocabulary applies.
     throw new Error('not ready yet: screenshot is unknown');
 }
 /**
@@ -89,6 +201,25 @@ async function emitScreenshot(result, opts) {
         return;
     }
     if (opts.output !== undefined) {
+        // A not-ready poll has no artifact to download — but the job WAS accepted and billed, so
+        // losing the handle behind a generic exit 1 is the defect (#2686 item 1). Mirror
+        // `scrape get --raw` on a queued envelope EXACTLY: the bare id on STDOUT (so
+        // `ss=$(bytekit screenshots get … -o -)` still captures a usable handle), a human note on
+        // STDERR, and QUEUED_EXIT_CODE. The `-o` file is deliberately never written — there is no
+        // image yet, and a file holding a bare id would masquerade as an artifact.
+        //
+        // Soft `process.exitCode`, never `process.exit`: a hard exit runs before Node drains an async
+        // piped stdout and would discard the very id this branch exists to deliver (#2544). Execution
+        // therefore continues past the assignment, so this branch must `return` explicitly — falling
+        // through to `extractImageUrl` would throw `not ready yet` and clobber the signal with exit 1.
+        const notReady = notReadyScreenshot(result);
+        if (notReady !== undefined) {
+            console.error(`Note: screenshot ${notReady.id} is ${notReady.status} — no image artifact is available ` +
+                `yet. Poll it with: bytekit screenshots get ${notReady.id}`);
+            process.stdout.write(`${notReady.id}\n`);
+            process.exitCode = QUEUED_EXIT_CODE;
+            return;
+        }
         await downloadArtifact(extractImageUrl(result), opts.output);
         return;
     }
@@ -129,7 +260,6 @@ export function makeScreenshotsCommand(getGlobal) {
         .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const body = { url: opts.url };
         // Each optional flag maps 1:1 to its snake_case ScreenshotRequest field, written ONLY when
         // present — a boolean never serializes `false` (#2480 E1).
@@ -180,6 +310,8 @@ export function makeScreenshotsCommand(getGlobal) {
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             // Reject --json + -o BEFORE issuing the request: -o downloads BINARY artifact bytes, so
             // it can never coexist with --json (which must stay a text envelope). Thrown here so no
             // request — and therefore no download fetch — is ever issued (#2480 E2).
@@ -208,8 +340,9 @@ export function makeScreenshotsCommand(getGlobal) {
         .option('-o, --output <file>', 'Download the captured image to this file path (use - for stdout). Not valid with --json.')
         .action(async (id, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             if (g.json && opts.output !== undefined) {
                 throw new Error('-o cannot be used with --json');
             }

package/dist/commands/search.js

@@ -49,7 +49,6 @@ export function makeSearchCommand(getGlobal) {
         .option('--date-range <window>', 'Restrict results to a recency window: any (default), hour, day, week, month, or year')
         .action(async (query, opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Build SearchOpts from the positional arg plus any provided flags.
         // Omit absent optionals so we never send undefined/NaN over the wire.
         // type/date_range are passed through verbatim; the API validates the
@@ -66,6 +65,8 @@ export function makeSearchCommand(getGlobal) {
         if (opts.dateRange !== undefined)
             body.date_range = opts.dateRange;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.search.query(body);
             if (g.json) {
                 printResult(result, true);

package/dist/commands/sitemap.js

@@ -24,7 +24,6 @@ export function makeSitemapCommand(getGlobal) {
         .option('--metadata <json>', `Arbitrary metadata echoed on the job envelope, as a JSON object, e.g. '{"run":"7"}' (omitted → none)`, (v) => parseJsonFlag('--metadata', v, 'object'))
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         // Omit-when-absent body; the remaining SitemapRequest fields keep their server defaults.
         // The generated request type marks defaulted fields required, so the call needs an explicit
         // assertion — type-level only; the wire body is pinned by request-shapes.test.ts.
@@ -50,6 +49,8 @@ export function makeSitemapCommand(getGlobal) {
         if (opts.metadata !== undefined)
             body['metadata'] = opts.metadata;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.sitemap.create(body);
             printResult(result, g.json);
         }
@@ -62,8 +63,9 @@ export function makeSitemapCommand(getGlobal) {
         .description('Get a sitemap job by ID')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.sitemap.get(id);
             printResult(result, g.json);
         }

package/dist/commands/usage.js

@@ -16,8 +16,9 @@ export function makeUsageCommand(getGlobal) {
         .description('Get current billing-period usage summary')
         .action(async () => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.usage.get();
             printResult(result, g.json);
         }
@@ -33,7 +34,6 @@ export function makeUsageCommand(getGlobal) {
         .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.from !== undefined)
             params.from = opts.from;
@@ -42,6 +42,8 @@ export function makeUsageCommand(getGlobal) {
         if (opts.apiKey !== undefined)
             params.api_key = opts.apiKey;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.usage.daily(params)
                 : await client.usage.daily();
@@ -59,7 +61,6 @@ export function makeUsageCommand(getGlobal) {
         .option('--api-key <ak_id>', 'Filter by API key prefixed ID (omitted → all keys)')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.from !== undefined)
             params.from = opts.from;
@@ -68,6 +69,8 @@ export function makeUsageCommand(getGlobal) {
         if (opts.apiKey !== undefined)
             params.api_key = opts.apiKey;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.usage.byEndpoint(params)
                 : await client.usage.byEndpoint();

package/dist/commands/webhook-deliveries.js

@@ -21,7 +21,6 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         .option('--since <iso>', 'Only deliveries created after this ISO date-time')
         .action(async (opts) => {
         const g = getGlobal();
-        const client = buildClient(g);
         const params = {};
         if (opts.limit !== undefined)
             params.limit = opts.limit;
@@ -32,6 +31,8 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         if (opts.since !== undefined)
             params.since = opts.since;
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = Object.keys(params).length > 0
                 ? await client.webhooks.list(params)
                 : await client.webhooks.list();
@@ -46,8 +47,9 @@ export function makeWebhookDeliveriesCommand(getGlobal) {
         .description('Requeue a failed or exhausted webhook delivery')
         .action(async (id) => {
         const g = getGlobal();
-        const client = buildClient(g);
         try {
+            // Inside the try: buildClient() throws on a missing key (#2686 item 4) and the throw must reach handleError(). See its doc comment in client.ts.
+            const client = buildClient(g);
             const result = await client.webhooks.retry(id);
             printResult(result, g.json);
         }

package/dist/lib/download-artifact.js

@@ -82,8 +82,9 @@ export async function downloadArtifact(url, dest, timeoutMs = DEFAULT_TIMEOUT_MS
             // (mirroring client.ts's corrected 429-drain mechanism, cr-3), reasoning that a full
             // `text()` read lets undici return the connection to the pool. That reasoning does not
             // apply on THIS path: `commands/screenshots.ts` throws this error straight into
-            // `handleError`, which `process.exit(1)`s immediately after — there is no next request in
-            // this process for a reclaimed socket to serve. A drain here was bounded only by the FULL
+            // `handleError`, which is the last statement of the action's catch — the command then ends
+            // (signalling exit 1 via `process.exitCode` since #2686 item 4), so there is no next request
+            // in this process for a reclaimed socket to serve. A drain here was bounded only by the FULL
             // per-attempt abort budget (or, under `timeoutMs <= 0`, by nothing at all) for zero benefit,
             // so it is removed outright rather than merely capped.
             throw new Error(`artifact download failed: HTTP ${res.status}`);

package/dist/lib/parse-flags.js

@@ -69,7 +69,9 @@ export function parseJsonFlag(flag, value, expect) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new InvalidArgumentError(`${flag} must be valid JSON (a ${expect}), e.g. '${example}'.`);
+        // "an", not "a": both shape words (`object`, `array`) begin with a vowel, so a hardcoded
+        // article read `(a object)` / `(a array)` (#2686 item 5).
+        throw new InvalidArgumentError(`${flag} must be valid JSON (an ${expect}), e.g. '${example}'.`);
     }
     const matches = expect === 'array'
         ? Array.isArray(parsed)

package/dist/output.d.ts

@@ -72,6 +72,20 @@ export declare function resolveOutputMode(flags: OutputFlags): OutputMode;
  *
  * Errors — rather than guessing or stringifying — whenever the request is ambiguous or the body is
  * not text, so `--raw` can never print `[object Object]` or a format the caller did not ask for.
+ *
+ * Three states have no body but are NOT "the response contains no formats" (#2686 item 2), and each
+ * gets its own diagnostic ahead of the generic ones, because the caller's next action differs:
+ *
+ * - a terminal-FAILED scrape (`ScrapeErrorEnvelope`) → the envelope's own `error.code` + message.
+ *   This is the scrape twin of the screenshots extractor's error-envelope branch (#2027). It is
+ *   checked FIRST so a failure envelope that also carries `formats: {}` still reports why it failed
+ *   rather than a format-selection problem the caller cannot act on.
+ * - a completed scrape with an EMPTY `formats: {}` bag and a warning explaining it (the #2675
+ *   `artifact_unavailable` shape) → the warning's code and message.
+ * - an empty bag with no warning → says the bag is empty. It is not "no formats" (the key IS
+ *   there), and `--format` cannot help, so the multi-format diagnostic would be a false lead.
+ *
+ * A queued envelope never reaches here — {@link emitResult} diverts it to {@link emitQueuedRaw}.
  */
 export declare function extractRawBody(response: unknown, requestedFormat?: string): string;
 /**
@@ -133,6 +147,10 @@ export declare function emitResult(result: unknown, mode: OutputMode, target: Ou
 /**
  * Collect the `X-Fetch-*` response headers of a {@link FetchResult} into a Title-Cased object —
  * the documented `--json` payload for a fetch command.
+ *
+ * Key names are the SPEC names: {@link FETCH_HEADER_CASING} first, {@link titleCaseHeader}
+ * otherwise. `fetch-metadata-keys.test.ts` pins the emitted set against the spec's own exhaustive
+ * header list. Values are passed through verbatim, and non-`X-Fetch-*` headers stay filtered out.
  */
 export declare function collectFetchMetadata(headers: Headers): Record<string, string>;
 /**
@@ -158,7 +176,20 @@ export declare function emitFetchResult(result: unknown, jsonMode: boolean, targ
  */
 export declare function printResult(data: unknown, jsonMode: boolean): void;
 /**
- * Handle a CLI command error: print to stderr and exit 1.
+ * Handle a CLI command error: print to stderr and signal exit 1.
+ *
+ * The signal is a SOFT `process.exitCode`, never a hard `process.exit` (#2686 item 4, restoring the
+ * #2544 policy this site contradicted). Node documents `process.stderr` as ASYNCHRONOUS when it
+ * points at a pipe: a write that cannot be handed to the kernel in one go is queued in userspace
+ * and drained on a later event-loop turn, and `process.exit()` runs before any of those turns and
+ * DISCARDS the queue. The one line a script greps was therefore the line most at risk of being
+ * thrown away. Setting `process.exitCode` lets the process end naturally once stderr has drained,
+ * with the same observable exit code.
+ *
+ * Returns `void` (not `never`): the hard exit used to provide an implicit stop, so every caller
+ * must be the LAST statement of its `catch` block, or `return` immediately after (#2686 E4). Every
+ * call site in this package is the final statement of an action's `catch`, so the action returns
+ * and nothing further runs.
  *
  * The message always begins `Error: ` (a prefix scripts grep on) followed by the error message and
  * an optional parenthesised suffix built from the two diagnostic axes the ByteKit errors carry:
@@ -174,5 +205,5 @@ export declare function printResult(data: unknown, jsonMode: boolean): void;
  * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
  * placeholder — never `(, status: <n>)`.
  */
-export declare function handleError(err: unknown): never;
+export declare function handleError(err: unknown): void;
 export {};

package/dist/output.js

@@ -58,13 +58,77 @@ export function resolveOutputMode(flags) {
         return { kind: 'raw' };
     return { kind: 'human' };
 }
+/**
+ * The `error` of a spec `ScrapeErrorEnvelope` (`{status:'failed', id, error:{code, message, …}}`),
+ * or undefined when the response is not a failure envelope.
+ *
+ * Keyed on the presence of a well-formed `error` object rather than on `status === 'failed'`: the
+ * envelope is what a 200 GET returns for a terminally-failed job, and a producer that ships the
+ * error without the discriminator still owes the caller its reason.
+ */
+function scrapeErrorDetail(response) {
+    if (typeof response !== 'object' || response === null)
+        return undefined;
+    const err = response.error;
+    if (typeof err !== 'object' || err === null || Array.isArray(err))
+        return undefined;
+    const { code, message } = err;
+    const detail = {};
+    if (typeof code === 'string' && code.length > 0)
+        detail.code = code;
+    if (typeof message === 'string' && message.length > 0)
+        detail.message = message;
+    return detail;
+}
+/**
+ * The warning that best explains an empty `formats` bag — `artifact_unavailable` when present
+ * (the #2675 shape: a completed scrape whose persisted artifact could not be rehydrated),
+ * otherwise the first warning the envelope carries. Undefined when there are none.
+ */
+function emptyFormatsWarning(response) {
+    if (typeof response !== 'object' || response === null)
+        return undefined;
+    const raw = response.warnings;
+    if (!Array.isArray(raw))
+        return undefined;
+    const parsed = raw.flatMap((w) => {
+        if (typeof w !== 'object' || w === null)
+            return [];
+        const { code, message } = w;
+        if (typeof code !== 'string' || code.length === 0)
+            return [];
+        return typeof message === 'string' && message.length > 0 ? [{ code, message }] : [{ code }];
+    });
+    return parsed.find((w) => w.code === 'artifact_unavailable') ?? parsed[0];
+}
 /**
  * Narrow an SDK response (typed `unknown` today) down to the single format body to emit raw.
  *
  * Errors — rather than guessing or stringifying — whenever the request is ambiguous or the body is
  * not text, so `--raw` can never print `[object Object]` or a format the caller did not ask for.
+ *
+ * Three states have no body but are NOT "the response contains no formats" (#2686 item 2), and each
+ * gets its own diagnostic ahead of the generic ones, because the caller's next action differs:
+ *
+ * - a terminal-FAILED scrape (`ScrapeErrorEnvelope`) → the envelope's own `error.code` + message.
+ *   This is the scrape twin of the screenshots extractor's error-envelope branch (#2027). It is
+ *   checked FIRST so a failure envelope that also carries `formats: {}` still reports why it failed
+ *   rather than a format-selection problem the caller cannot act on.
+ * - a completed scrape with an EMPTY `formats: {}` bag and a warning explaining it (the #2675
+ *   `artifact_unavailable` shape) → the warning's code and message.
+ * - an empty bag with no warning → says the bag is empty. It is not "no formats" (the key IS
+ *   there), and `--format` cannot help, so the multi-format diagnostic would be a false lead.
+ *
+ * A queued envelope never reaches here — {@link emitResult} diverts it to {@link emitQueuedRaw}.
  */
 export function extractRawBody(response, requestedFormat) {
+    const failure = scrapeErrorDetail(response);
+    if (failure !== undefined) {
+        const reason = failure.message !== undefined && failure.code !== undefined
+            ? `${failure.message} (${failure.code})`
+            : (failure.message ?? failure.code ?? 'unknown error');
+        throw new Error(`--raw: scrape failed: ${reason}`);
+    }
     const formats = typeof response === 'object' && response !== null
         ? response.formats
         : undefined;
@@ -73,6 +137,13 @@ export function extractRawBody(response, requestedFormat) {
     }
     const bag = formats;
     const keys = Object.keys(bag);
+    if (keys.length === 0) {
+        const warning = emptyFormatsWarning(response);
+        throw new Error(warning === undefined
+            ? '--raw: the response carries an empty formats map — no body to emit'
+            : `--raw: the response carries an empty formats map — ${warning.code}` +
+                (warning.message !== undefined ? `: ${warning.message}` : ''));
+    }
     let key;
     if (requestedFormat !== undefined) {
         key = requestedFormat;
@@ -197,15 +268,39 @@ function titleCaseHeader(name) {
         .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).toLowerCase())
         .join('-');
 }
+/**
+ * Spec header names that segment-wise Title-Casing cannot produce (#2686 item 3).
+ *
+ * `titleCaseHeader` lowercases every non-initial character of a segment, so `x-fetch-id` came out
+ * `X-Fetch-Id` and `x-fetch-url` came out `X-Fetch-Url` — while `docs/api/openapi.yaml` declares
+ * `X-Fetch-ID` and `X-Fetch-URL` (the gateway's CORS expose list, `lib/cors-config.ts`, mirrors the
+ * same spellings). A `jq '."X-Fetch-ID"'` filter written from the API reference therefore got
+ * `null` off `bytekit fetch … --json`.
+ *
+ * The exception lives HERE, in a lookup keyed by the lowercase wire name, and deliberately NOT
+ * inside `titleCaseHeader` (#2686 E3). That helper is a generic contract — an acronym rule baked
+ * into it would silently re-case names for any future caller, and would have to guess at segments
+ * like `Waf` (which the spec really does spell `X-Fetch-Waf-Vendor`, not `WAF`). Every header
+ * outside this map keeps the generic Title-Cased spelling it has always had.
+ */
+const FETCH_HEADER_CASING = {
+    'x-fetch-id': 'X-Fetch-ID',
+    'x-fetch-url': 'X-Fetch-URL',
+};
 /**
  * Collect the `X-Fetch-*` response headers of a {@link FetchResult} into a Title-Cased object —
  * the documented `--json` payload for a fetch command.
+ *
+ * Key names are the SPEC names: {@link FETCH_HEADER_CASING} first, {@link titleCaseHeader}
+ * otherwise. `fetch-metadata-keys.test.ts` pins the emitted set against the spec's own exhaustive
+ * header list. Values are passed through verbatim, and non-`X-Fetch-*` headers stay filtered out.
  */
 export function collectFetchMetadata(headers) {
     const meta = {};
     headers.forEach((value, key) => {
-        if (key.toLowerCase().startsWith('x-fetch-')) {
-            meta[titleCaseHeader(key)] = value;
+        const lower = key.toLowerCase();
+        if (lower.startsWith('x-fetch-')) {
+            meta[FETCH_HEADER_CASING[lower] ?? titleCaseHeader(key)] = value;
         }
     });
     return meta;
@@ -304,7 +399,20 @@ function errorCode(err) {
     return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
 }
 /**
- * Handle a CLI command error: print to stderr and exit 1.
+ * Handle a CLI command error: print to stderr and signal exit 1.
+ *
+ * The signal is a SOFT `process.exitCode`, never a hard `process.exit` (#2686 item 4, restoring the
+ * #2544 policy this site contradicted). Node documents `process.stderr` as ASYNCHRONOUS when it
+ * points at a pipe: a write that cannot be handed to the kernel in one go is queued in userspace
+ * and drained on a later event-loop turn, and `process.exit()` runs before any of those turns and
+ * DISCARDS the queue. The one line a script greps was therefore the line most at risk of being
+ * thrown away. Setting `process.exitCode` lets the process end naturally once stderr has drained,
+ * with the same observable exit code.
+ *
+ * Returns `void` (not `never`): the hard exit used to provide an implicit stop, so every caller
+ * must be the LAST statement of its `catch` block, or `return` immediately after (#2686 E4). Every
+ * call site in this package is the final statement of an action's `catch`, so the action returns
+ * and nothing further runs.
  *
  * The message always begins `Error: ` (a prefix scripts grep on) followed by the error message and
  * an optional parenthesised suffix built from the two diagnostic axes the ByteKit errors carry:
@@ -337,5 +445,5 @@ export function handleError(err) {
     else {
         console.error(`Error: ${String(err)}`);
     }
-    process.exit(1);
+    process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.5.0"
+    "@hunt-labs/bytekit-sdk": "^0.6.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",