@pithy-sh/cloudflare 0.1.0

package/src/workflows/stepFailure.ts

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ErrorPayload, kitErrorStatus } from "@pithy-sh/core/src/error/payload";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import {
+  decodeWorkflowStepMessage,
+  MAX_WORKFLOW_STEP_TEXT,
+  splitWorkflowStepCode,
+} from "@pithy-sh/core/src/workflow/stepMessage";
+import { z } from "zod";
+
+/**
+ * **The step's sentence, recovered from an instance the engine has already written its own over.**
+ *
+ * A Workflow instance carries two failure texts. The instance-level `error` is the *platform's*: when a
+ * step raises `NonRetryableError`, the engine replaces whatever was thrown with
+ * `"The execution of the Workflow instance was terminated, as a step threw an NonRetryableError…"`.
+ * The step's own entry in `steps[]` still holds the text the kit raised. Reporting the first is how
+ * `pithy secrets create` on a name that already exists started answering with a sentence about durable
+ * execution instead of one about the secret (pithy-sh/pithy#349), the day #338 made that refusal terminal.
+ *
+ * So this reads the step, and it is read *here* rather than at a call site: every dispatch that polls a
+ * Workflow — secrets write and probe, payments reconcile, vector reprocess — goes through one
+ * `dispatchAndPoll`, and a rule that lives in the primitive cannot be missed by the next caller.
+ *
+ * ## What may cross into an operator's `message`, and what may not
+ *
+ * A `PithyError`'s `message` is public and its `detail` is stripped at the HTTP boundary — that is the
+ * security boundary, and this function is on the wrong side of it: the text arrives from a Worker whose
+ * code we did not write, over an API, and it could say anything. So a step's text is promoted into the
+ * operator's `message` **only when it is demonstrably a sentence the kit itself authored as public**:
+ *
+ * - `PithyError: <text>` — the throw's own name is the proof. `PithyError.message` *is*
+ *   `payload.message`, the field already written to be safe for a client.
+ * - The encoding core's `classifiedSteps` writes, inside the platform's terminal envelope. **This file
+ *   does not restate that encoding**; it calls `decodeWorkflowStepMessage`, which is the same module
+ *   the writer calls, for the reason in its own doc comment: two packages agreeing about a string by
+ *   each writing it down is a coincidence, not a contract (pithy-sh/pithy#353).
+ *
+ * Anything else — a foreign throw, a bare string, the engine's own prose — stays in `detail`, where it
+ * always was. Nothing that was not already public becomes public here.
+ *
+ * `action` rides that encoding and is promoted with the sentence, because it is already the operator's
+ * field: the CLI prints it under the problem line and `operatorError` includes it. `detail` does not
+ * cross, has no encoding, and is not read here.
+ *
+ * ## The literals are captured, not guessed
+ *
+ * Every platform string below was read off a real Workflows engine — the shipped Workflow class driven
+ * under `wrangler dev` (wrangler 4.123.0, 2026-08-14), instance detail fetched from the local dev
+ * session's own instance endpoint. They are frozen so the gate in `stepFailure.test.ts` polices a fixed
+ * set rather than whatever this file happens to believe today.
+ */
+
+/** A failure as the Workflows API records one: a class name and its text. Instance-level and per-step alike. */
+export const WorkflowFailureDetail = z
+  .object({
+    name: z.string().optional().describe("The thrown value's class name, as the engine recorded it."),
+    message: z
+      .string()
+      .optional()
+      .describe("The failure text — the engine's own for a terminal step, else the throw's."),
+  })
+  .describe("One failure the Workflows API reports, on an instance or on a step attempt.");
+export type WorkflowFailureDetail = z.output<typeof WorkflowFailureDetail>;
+
+/** One attempt at a step. The engine appends one per retry, so the last failed one is the answer. */
+export const WorkflowStepAttempt = z
+  .object({
+    success: z.boolean().nullish().describe("Whether this attempt returned; `false` once it threw."),
+    error: WorkflowFailureDetail.nullish().describe("What this attempt threw, absent when it returned."),
+  })
+  .describe("One attempt at a Workflow step, as the instance-detail endpoint reports it.");
+export type WorkflowStepAttempt = z.output<typeof WorkflowStepAttempt>;
+
+/**
+ * One entry in an instance's `steps[]`.
+ *
+ * The API's four step shapes (`step`, `sleep`, `waitForEvent`, `termination`) differ in where the
+ * failure lives — a `step` keeps one per attempt, the others keep one on the entry — so both are
+ * optional here and the reader takes whichever is present. Unknown fields (`config`, `output`,
+ * timestamps) are stripped rather than refused: this is a diagnostic read, and a step shape nobody
+ * anticipated must not turn a failed Workflow into a parse error about the failure report.
+ */
+export const WorkflowStepRecord = z
+  .object({
+    name: z.string().optional().describe("The step's name, as `step.do` was called with it."),
+    type: z.string().optional().describe("Which of the API's step shapes this is — `step`, `sleep`, `waitForEvent`."),
+    success: z.boolean().nullish().describe("Whether the step completed; `false` once every attempt failed."),
+    error: WorkflowFailureDetail.nullish().describe("The failure, for the shapes that record one on the entry."),
+    attempts: z.array(WorkflowStepAttempt).optional().describe("Each attempt at the step, oldest first."),
+  })
+  .describe("One step of a Workflow instance, narrowed to the fields a failure report reads.");
+export type WorkflowStepRecord = z.output<typeof WorkflowStepRecord>;
+
+/** What a failed instance's steps say about why, once the platform's own prose is set aside. */
+export interface WorkflowStepFailure {
+  /** The failed step's name, when the engine reported one. */
+  step?: string;
+  /** The step's recorded text, verbatim, platform envelope and all. For `detail` — never for `message`. */
+  raw: string;
+  /** The `PithyError` code the step raised, when its text carries one. */
+  code?: string;
+  /** The step's own public sentence — present only when the text is one the kit authored. */
+  sentence?: string;
+  /** The remedy the raising error stated, when it stated one. The CLI's action line. */
+  action?: string;
+}
+
+/**
+ * The envelope the engine wraps a terminal step throw in, captured verbatim. The inner text is *not*
+ * JSON-quoted — a message containing a `"` is embedded raw — so this is a prefix/suffix strip and never
+ * a `JSON.parse`.
+ */
+const TERMINAL_STEP_ENVELOPE = Object.freeze({
+  prefix: 'Step threw a NonRetryableError with message "',
+  suffix: '"',
+});
+
+/**
+ * The throw names a kit step error can arrive under. `PithyError` is core's one throw vehicle;
+ * `NonRetryableError` is what `classifiedSteps` re-throws a terminal fault as. A name outside this set
+ * is somebody else's error, and its text stays in `detail`.
+ */
+const KIT_THROW_NAMES: readonly string[] = Object.freeze(["PithyError", "NonRetryableError"]);
+
+/**
+ * The kit-authored public sentence inside a step's recorded text, and the remedy riding with it —
+ * `null` when there is none.
+ *
+ * Exported for the gate, which drives captured engine output through it: a platform sentence reaching an
+ * operator is a test failure, and the test has to be able to ask this question directly.
+ */
+export function kitSentence(raw: string): { code?: string; message: string; action?: string } | null {
+  let text = raw.trim();
+  if (text.startsWith(TERMINAL_STEP_ENVELOPE.prefix) && text.endsWith(TERMINAL_STEP_ENVELOPE.suffix)) {
+    text = text.slice(TERMINAL_STEP_ENVELOPE.prefix.length, -TERMINAL_STEP_ENVELOPE.suffix.length);
+  }
+  const thrown = KIT_THROW_NAMES.map((name) => `${name}: `).find((prefix) => text.startsWith(prefix));
+  if (thrown === undefined) return null;
+  text = text.slice(thrown.length);
+
+  // A `NonRetryableError` is `classifiedSteps`' vehicle, so its text is core's encoding or it is
+  // somebody else's — anyone may throw one with anything inside, and the code prefix is the only proof.
+  if (thrown === "NonRetryableError: ") return decodeWorkflowStepMessage(text);
+
+  // A `PithyError` name is proof on its own. Its recorded text is `payload.message` and carries no
+  // encoding at all — no action ever rode here — so the sentence is taken as it stands, and a newline
+  // in it is still declined rather than reshaped: it would forge the CLI's action line.
+  const { code, rest } = splitWorkflowStepCode(text);
+  const message = rest.trim();
+  if (message === "" || message.length > MAX_WORKFLOW_STEP_TEXT) return null;
+  if (/[\n\r]/.test(message)) return null;
+  return code === undefined ? { message } : { code, message };
+}
+
+/** The recorded failure text of one step entry, from its last failed attempt or its own error. */
+function failureTextOf(step: WorkflowStepRecord): string | undefined {
+  for (let index = (step.attempts?.length ?? 0) - 1; index >= 0; index -= 1) {
+    const attempt = step.attempts?.[index];
+    if (attempt?.success === true) continue;
+    const message = attempt?.error?.message;
+    if (message !== undefined && message !== "") return message;
+  }
+  const own = step.error?.message;
+  return own === undefined || own === "" ? undefined : own;
+}
+
+/**
+ * The last step that failed, and what it said. `null` when no step reports a failure — an instance the
+ * platform failed on its own (a timeout, a terminate) has steps that all succeeded, or none at all.
+ *
+ * Read from the end: the failing step is the last one the instance reached, and an earlier step that
+ * failed and was retried into success has nothing to say about why the instance ended.
+ *
+ * Each entry is validated on its way in and an entry that will not parse is skipped rather than thrown
+ * on. The caller is already reporting a failure; refusing to describe it because one step of the report
+ * had an unfamiliar shape trades a useful sentence for a useless one.
+ */
+export function stepFailure(steps: readonly unknown[] | undefined): WorkflowStepFailure | null {
+  if (steps === undefined) return null;
+  for (let index = steps.length - 1; index >= 0; index -= 1) {
+    const parsed = WorkflowStepRecord.safeParse(steps[index]);
+    if (!parsed.success) continue;
+    if (parsed.data.success === true) continue;
+    const raw = failureTextOf(parsed.data);
+    if (raw === undefined) continue;
+    const kit = kitSentence(raw);
+    return {
+      ...(parsed.data.name === undefined ? {} : { step: parsed.data.name }),
+      raw,
+      ...(kit?.code === undefined ? {} : { code: kit.code }),
+      ...(kit === null ? {} : { sentence: kit.message }),
+      // Absent, not `undefined`: a step that stated no remedy must leave nothing for the CLI to print
+      // under the problem line — no empty line, no trailing separator, no `undefined`.
+      ...(kit?.action === undefined ? {} : { action: kit.action }),
+    };
+  }
+  return null;
+}
+
+/**
+ * The code a terminal Workflow failure falls back to when the fault that ended the run cannot be
+ * attributed. Stated here because two things must agree on it: the thrower below, and the gate that
+ * proves this code is not one a transport failure can arrive under.
+ */
+export const WORKFLOW_FAILED_CODE = "core/workflow_failed" as const;
+
+/** The status pinned to {@link WORKFLOW_FAILED_CODE}, restated so the throw cannot drift off it. */
+export const WORKFLOW_FAILED_STATUS = 500 as const;
+
+/**
+ * **The error an operator is handed for a Workflow that ran and did not complete** (pithy-sh/pithy#365).
+ *
+ * `#353` fixed the sentence and the remedy. The `code` and the `status` were still the *transport's*:
+ * `dispatchAndPoll` threw `CloudflareRequestError`, which fixes `cloudflare/request_failed` and 502 by
+ * construction, so a step that raised `secrets/already_exists` with 409 reached the CLI as a 502 —
+ * "the far side is broken, try later" for a request that was delivered, ran, and was permanently
+ * refused. Anything branching on the pair rather than reading the prose was told the opposite of what
+ * happened.
+ *
+ * ## The distinction that has to survive, and where it lives
+ *
+ * A Workflow whose *step raised* is not the same event as a dispatch that could not be delivered, and
+ * the difference is now in the two machine-readable fields rather than in the message:
+ *
+ * - **The step raised, and the kit pins a status for its code** → that code, that status. Terminal by
+ *   the code's own definition; `secrets/already_exists` is a 409 wherever it is raised.
+ * - **The run ended and nothing is attributable** — a foreign throw, the platform's own prose, an
+ *   `unclassified` fault, an adopter code the kit pins no status for → {@link WORKFLOW_FAILED_CODE},
+ *   500. Terminal, and deliberately not 502.
+ * - **The dispatch itself failed** — the REST call was refused, timed out, or answered with a shape
+ *   nobody expected → `cloudflare/request_failed` / `cloudflare/invalid_response`, 502, thrown by
+ *   `cloudflareRequest` exactly as before. This function is never reached for one.
+ *
+ * So the reader tells them apart on `code` alone, and the three sets are disjoint.
+ *
+ * ## Why the status is recovered from the code rather than carried on the wire
+ *
+ * Nothing but `code`, `message` and `action` crosses a durable step boundary — the engine records the
+ * throw's text and discards the throw. A fourth field could have been encoded, at the cost of
+ * reopening a format `#353` froze against a measurement. It is not needed: **every kit member pins
+ * `status` to one literal**, so the code *is* the status (`kitErrorStatus`). A code the kit does not
+ * define has no pinned status, and rather than invent one this says so with its own code.
+ *
+ * ## `detail` still does not cross
+ *
+ * `detail` is composed here from the platform's raw text and the instance id — the operator's side of
+ * the boundary — and nothing derived from the step's own `detail` is in it, because the step's
+ * `detail` never left the step. The only fields promoted from the far side are `message` and `action`,
+ * both already public, both already proved kit-authored by `kitSentence`.
+ */
+export function terminalWorkflowError(args: {
+  /** What the instance's steps said, or `null` when no step reported a failure. */
+  failure: WorkflowStepFailure | null;
+  /** The sentence to use when the step authored none — the caller's own, about the instance. */
+  fallbackMessage: string;
+  /** The operator's context line. Raw platform text and the instance id; never the dispatched params. */
+  detail: string;
+}): PithyError {
+  const { failure, fallbackMessage, detail } = args;
+  // A remedy travels only alongside the sentence it is a remedy for. An action line under a general
+  // fallback about durable execution is a fix for a problem nobody was told about.
+  const message = failure?.sentence ?? fallbackMessage;
+  const action = failure?.sentence === undefined ? undefined : failure.action;
+
+  const status = failure?.code === undefined ? undefined : kitErrorStatus(failure.code);
+  if (failure?.sentence !== undefined && failure.code !== undefined && status !== undefined) {
+    const candidate = { code: failure.code, status, message, action, detail };
+    // Parsed rather than trusted. A recovered code is a string from a Worker we did not write, and one
+    // kit member (`validation/invalid_input`) requires a field this boundary has no way to supply — so
+    // a payload that would not validate must not be thrown from the error path. It falls through to
+    // the general terminal code below, keeping the step's own sentence.
+    const parsed = ErrorPayload.safeParse(candidate);
+    if (parsed.success) return new PithyError(parsed.data);
+  }
+
+  return new PithyError({ code: WORKFLOW_FAILED_CODE, status: WORKFLOW_FAILED_STATUS, message, action, detail });
+}

package/src/workflows/workflowsClient.ts

@@ -0,0 +1,213 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { UpstreamTimeoutError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { CloudflareInvalidResponseError, cloudflareRequest, isNotFoundError } from "../client/errors";
+import { CloudflareManager, type CloudflareManagerConfig } from "../client/manager";
+import { stepFailure, terminalWorkflowError, type WorkflowStepFailure } from "./stepFailure";
+
+/** Pause `ms` milliseconds between status polls. Injectable so tests run with no real delay. */
+export type Sleeper = (ms: number) => Promise<void>;
+
+export interface CloudflareWorkflowsClientConfig extends CloudflareManagerConfig {
+  /** Override the poll delay (tests). Defaults to a real `setTimeout`. */
+  sleeper?: Sleeper;
+}
+
+export const WorkflowInstanceStatus = z
+  .enum([
+    "queued",
+    "running",
+    "paused",
+    "errored",
+    "terminated",
+    "complete",
+    "waitingForPause",
+    "waiting",
+    "rollingBack",
+    "unknown",
+  ])
+  .describe("Lifecycle state of a Cloudflare Workflow instance, from the status endpoint.");
+export type WorkflowInstanceStatus = z.output<typeof WorkflowInstanceStatus>;
+
+export const WorkflowInstance = z
+  .object({
+    status: WorkflowInstanceStatus.describe("The instance's current lifecycle state."),
+    output: z.unknown().optional().describe("The Workflow's return value, present once `status` is `complete`."),
+    error: z
+      .union([
+        z.string(),
+        z
+          .object({ message: z.string().optional().describe("Failure message.") })
+          .describe("The structured form of the failure, when the API sends an object rather than a string."),
+        z.null(),
+      ])
+      .optional()
+      .describe("The instance-level failure, present when `status` is `errored` or `terminated`."),
+    steps: z
+      .array(z.unknown())
+      .optional()
+      .describe(
+        "The instance's steps, each validated where it is read (`stepFailure`). Held as `unknown` here on purpose: the API has four step shapes, this client reads one field of one of them, and a shape nobody anticipated must not turn a failed Workflow into a parse error about the failure report.",
+      ),
+  })
+  .describe("A Cloudflare Workflow instance's status, as returned by the instance-detail endpoint.");
+export type WorkflowInstance = z.output<typeof WorkflowInstance>;
+
+/** Terminal states a poll stops on. */
+const TERMINAL: ReadonlySet<WorkflowInstanceStatus> = new Set(["complete", "errored", "terminated"]);
+
+const defaultSleeper: Sleeper = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * A client over the Cloudflare Workflows API — the only sanctioned way to reach CF Workflows from
+ * outside a Worker (CLAUDE.md: no hand-rolled CF `fetch` outside `@pithy-sh/cloudflare`). The
+ * `pithy secrets` CLI uses it to trigger a per-env manager's Workflow and poll to completion: the
+ * CLI never runs secret logic locally, since the master key is worker-only.
+ *
+ * The SDK owns transport and envelope handling. Instance status is still re-validated through
+ * {@link WorkflowInstance} rather than taken from the SDK's types: the SDK narrows `output` to
+ * `string | number`, but a Workflow's return value is arbitrary JSON, and the status enum is a wire
+ * value we decode at the boundary like every other external input.
+ */
+export class CloudflareWorkflowsClient extends CloudflareManager {
+  readonly #sleeper: Sleeper;
+
+  constructor(config: CloudflareWorkflowsClientConfig) {
+    super(config);
+    this.#sleeper = config.sleeper ?? defaultSleeper;
+  }
+
+  getServiceType(): string {
+    return "Workflows";
+  }
+
+  /** Prove reach by listing the account's Workflows; never throws. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      for await (const _workflow of this.getClient().workflows.list({ account_id: this.accountId })) break;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Create (trigger) a Workflow instance and return its id. */
+  async createInstance(workflowName: string, params: unknown, instanceId?: string): Promise<string> {
+    return cloudflareRequest(`create instance of ${workflowName}`, async () => {
+      const created = await this.getClient().workflows.instances.create(workflowName, {
+        account_id: this.accountId,
+        params,
+        ...(instanceId ? { instance_id: instanceId } : {}),
+      });
+      if (!created.id) {
+        throw new CloudflareInvalidResponseError({ detail: `create instance of ${workflowName}: missing instance id` });
+      }
+      return created.id;
+    });
+  }
+
+  /** Fetch an instance's status. Returns `null` on a 404 (a just-created instance can briefly lag). */
+  async getInstanceStatus(workflowName: string, instanceId: string): Promise<WorkflowInstance | null> {
+    const operation = `get status of ${workflowName}/${instanceId}`;
+    return cloudflareRequest(operation, async () => {
+      let response: unknown;
+      try {
+        response = await this.getClient().workflows.instances.get(instanceId, {
+          account_id: this.accountId,
+          workflow_name: workflowName,
+        });
+      } catch (error) {
+        // The instance is not queryable yet — the caller keeps polling. Any other failure is real.
+        if (isNotFoundError(error)) return null;
+        throw error;
+      }
+      const parsed = WorkflowInstance.safeParse(response);
+      if (!parsed.success) {
+        throw new CloudflareInvalidResponseError({ detail: `${operation}: unexpected shape` });
+      }
+      return parsed.data;
+    });
+  }
+
+  /**
+   * Trigger a Workflow and poll until it reaches a terminal state. Resolves with the instance
+   * `output` on `complete`. The error never carries the dispatched params (which may be secret).
+   *
+   * **Three failures, three codes, and a caller can tell them apart without reading a word of prose**
+   * (pithy-sh/pithy#365):
+   *
+   * | What happened | Code | Status |
+   * |---|---|---|
+   * | A step raised, and the kit pins a status for its code | that code | that status |
+   * | The run ended terminally, nothing attributable | `core/workflow_failed` | 500 |
+   * | The dispatch or a poll could not be delivered | `cloudflare/request_failed` | 502 |
+   * | We stopped waiting; the instance may still finish | `core/upstream_timeout` | 504 |
+   *
+   * The first two are terminal — the run is over and re-driving it reaches the same end. The last two
+   * are not. Reporting all of them as 502 told an operator to wait for a recovery that would never
+   * come; see `terminalWorkflowError` for the argument in full.
+   */
+  async dispatchAndPoll(
+    workflowName: string,
+    params: unknown,
+    options: { pollIntervalMs?: number; maxPolls?: number; instanceId?: string } = {},
+  ): Promise<unknown> {
+    const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+    const maxPolls = options.maxPolls ?? 120;
+    const id = await this.createInstance(workflowName, params, options.instanceId);
+
+    for (let poll = 0; poll < maxPolls; poll++) {
+      await this.#sleeper(pollIntervalMs);
+      const instance = await this.getInstanceStatus(workflowName, id);
+      if (!instance) continue; // not queryable yet — keep polling
+      if (!TERMINAL.has(instance.status)) continue;
+      if (instance.status === "complete") return instance.output;
+      // The step's sentence, not the instance's. The engine writes its own prose over a terminal step's
+      // error, so the instance says "a step threw an NonRetryableError" where the step says what was
+      // actually wrong (pithy-sh/pithy#349). Only a sentence the kit demonstrably authored is promoted
+      // into `message`; everything else stays in `detail`, which the HTTP codec strips.
+      // …and under the step's own code and status, not the transport's (pithy-sh/pithy#365). The
+      // sentence, the remedy, the code and the status are all the raising error's; the fallbacks and
+      // `detail` are this client's. `terminalWorkflowError` owns which of the two answers, so there is
+      // one statement of it rather than a rule this call site remembers.
+      const failure = stepFailure(instance.steps);
+      throw terminalWorkflowError({
+        failure,
+        fallbackMessage: `Workflow ${workflowName} did not complete (${instance.status}).`,
+        detail: `instance ${id} ended ${instance.status}: ${describeFailure(failure, instance.error)}`,
+      });
+    }
+    // Not terminal, and it must not read as one: the budget is *ours*, and the instance is still
+    // running on the far side. `core/upstream_timeout` (504) is the kit's stated code for a dependency
+    // that did not answer inside a deadline and may yet apply the work — which is exactly this — and it
+    // is neither the transport's 502 nor a terminal Workflow's code.
+    throw new UpstreamTimeoutError({
+      message: `Workflow ${workflowName} did not finish in time.`,
+      action: `Check the instance in the Cloudflare dashboard; it may still complete.`,
+      detail: `instance ${id} still running after ${maxPolls} polls`,
+    });
+  }
+}
+
+/** The most specific instance-error text, for a failure `detail`. Never the dispatched params. */
+function describeError(error: WorkflowInstance["error"]): string {
+  if (!error) return "no error detail";
+  if (typeof error === "string") return error;
+  return error.message ?? "no error detail";
+}
+
+/**
+ * Everything known about why, for the `detail` line: the failed step's name and its recorded text
+ * verbatim, then the instance's own. Both, because they differ — that difference is the bug this
+ * function exists because of — and `detail` is the operator's side of the boundary, where the raw
+ * platform text belongs. Never the dispatched params.
+ */
+function describeFailure(failure: WorkflowStepFailure | null, error: WorkflowInstance["error"]): string {
+  const instance = describeError(error);
+  if (failure === null) return instance;
+  const step = failure.step === undefined ? "step" : `step '${failure.step}'`;
+  const code = failure.code === undefined ? "" : ` [${failure.code}]`;
+  return `${step} raised${code} ${failure.raw} — instance error: ${instance}`;
+}

package/src/zones/zonesManager.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { cloudflareRequest } from "../client/errors";
+import { CloudflareManager } from "../client/manager";
+
+/**
+ * The account's zones — the registrable domains a custom domain can attach to.
+ *
+ * **Nothing here listed zones before.** Every zone-scoped operation in this package takes a `zoneId` the
+ * caller already knows: `CloudflareCustomHostnamesManager` takes it as constructor config,
+ * `CloudflareEmailRoutingManager` takes it per method, `CloudflareWorkersManager.addRoute` takes it
+ * positionally — and `pithy email provision` makes a human paste one, telling them to "find it on the
+ * zone's Overview page". So the CLI never *discovered* a zone; it demanded one.
+ *
+ * That is what this exists to change. When `pithy init` and `pithy worker add` ask where a Worker will
+ * answer, offering the account's real zones means a typo fails at `init` with a list of what exists,
+ * rather than at `deploy` with a Cloudflare error to decode.
+ *
+ * Read-only, deliberately. Pithy attaches routes to zones and never creates, transfers, or deletes one —
+ * a zone is the adopter's relationship with their registrar, not a resource this toolset provisions. The
+ * scoped token needs only `Zone:Read`.
+ */
+
+/** One zone on the account. */
+export const ZoneInfo = z
+  .object({
+    id: z.string().describe("The CF-assigned zone id, which every zone-scoped API call is addressed by."),
+    name: z
+      .string()
+      .describe(
+        "The registrable domain, e.g. `example.com`. This is the value a Worker's `domains` declaration names as its `zone`, and what wrangler writes as `zone_name`.",
+      ),
+    status: z
+      .string()
+      .describe(
+        "The zone's lifecycle status — `active` once Cloudflare is serving it, otherwise `pending`, `initializing`, or `moved`. A non-active zone cannot carry a custom domain yet, so a picker shows it and says so rather than hiding it.",
+      ),
+  })
+  .describe("One Cloudflare zone: the registrable domain a custom domain can attach to, and whether it is live.");
+export type ZoneInfo = z.output<typeof ZoneInfo>;
+
+/** Read the account's zones. Never creates or deletes — a zone is the adopter's, not ours to provision. */
+export class CloudflareZonesManager extends CloudflareManager {
+  getServiceType(): string {
+    return "Cloudflare Zones";
+  }
+
+  /** Prove access by listing. A read, and never throws — the caller decides what an inaccessible account means. */
+  async validateServiceAccess(): Promise<boolean> {
+    try {
+      await this.listZones();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Every zone on this account, name-sorted so a picker is stable between runs.
+   *
+   * Filtered to the account, because a user-bound token can see zones on accounts this project has
+   * nothing to do with — offering those would invite someone to attach a Worker to a zone that another
+   * account owns, which fails at deploy with an error that names neither problem.
+   */
+  async listZones(): Promise<ZoneInfo[]> {
+    return cloudflareRequest("list zones", async () => {
+      const zones: ZoneInfo[] = [];
+      for await (const zone of this.getClient().zones.list({ account: { id: this.accountId } })) {
+        const parsed = ZoneInfo.safeParse(zone);
+        if (parsed.success) zones.push(parsed.data);
+      }
+      return zones.sort((a, b) => a.name.localeCompare(b.name));
+    });
+  }
+
+  /**
+   * The zone a hostname belongs to, or `null`.
+   *
+   * Matches the **longest** zone name that the hostname sits under, which is the only correct rule when
+   * an account holds both `example.com` and `eu.example.com`: `api.eu.example.com` belongs to the latter,
+   * and picking the first match would attach it to the wrong zone. A public-suffix guess is not used at
+   * all — a zone can itself be a subdomain, and the account's own list is the authority.
+   */
+  async findZoneForHostname(hostname: string): Promise<ZoneInfo | null> {
+    const zones = await this.listZones();
+    const candidates = zones.filter((zone) => hostname === zone.name || hostname.endsWith(`.${zone.name}`));
+    if (candidates.length === 0) return null;
+    return candidates.reduce((longest, zone) => (zone.name.length > longest.name.length ? zone : longest));
+  }
+}