primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/log-inspection.js

@@ -0,0 +1,816 @@
+/**
+ * Shared inspection-output library for the CLI's log/event commands
+ * (issue #1967, Phase A1).
+ *
+ * The platform keeps "what happened in my app" in four disconnected stores —
+ * integration invocations, workflow runs, workflow step runs, webhook events,
+ * and activity events. Each has its own CLI command with its own ad-hoc output
+ * shape. This module gives all of them one consistent, platform-vocabulary
+ * inspection model:
+ *
+ *   1. A **source-keyed discriminated union** (`LogEntry`) with a common
+ *      envelope `{ source, timestamp, outcome, nativeStatus, correlation }`
+ *      plus a typed, per-source `detail`. Workflow runs and workflow steps are
+ *      **separate variants** (`workflow-run` / `workflow-step`) — there is no
+ *      `kind` sub-discriminator.
+ *   2. An **outcome normalizer** that maps each source's native status onto a
+ *      small platform vocabulary (`ok` / `error` / `pending` / `neutral`) via a
+ *      documented policy, while preserving the raw value verbatim in
+ *      `nativeStatus`.
+ *   3. CLI-owned **per-source adapters** (`toIntegrationInspectionRow`, …) that
+ *      project each source record into its `LogEntry` variant. `detail` is a
+ *      deliberate **allowlist** projection — never the whole native record — so
+ *      stack-bearing error details, large-payload storage keys, step config/IO,
+ *      and infrastructure-internal activity fields never leak into `--json` by
+ *      default.
+ *   4. `--json` **envelope builders** per source, so every log view emits the
+ *      normalized item shape inside its endpoint's own pagination envelope —
+ *      never a bare array. This normalization is `--json`-only: the human
+ *      tables stay per-source, because each carries columns the generic shape
+ *      has no room for (a run's queue delay, a step's inter-step gap and token
+ *      counts, a webhook event's id). All four already share one definition of
+ *      time/duration/status formatting — `cli/src/lib/output.ts` — so there is
+ *      no second copy to reconcile, and no server-side projection
+ *      (`BlockRunSummary`, `IntegrationProxy.LogEntry`) is moved or imported
+ *      here.
+ *   5. A small **unsupported-flag rejection helper** so a filter a command
+ *      cannot serve fails with a clear message instead of being silently
+ *      ignored.
+ *
+ * Nothing here reaches the network; adapters are pure functions over records
+ * the caller already fetched (one upstream call per command invocation).
+ */
+import { normalizeCliListEnvelope } from "./paginate.js";
+// ── Outcome normalizers (documented policy table, behavior 2) ─────────
+/** HTTP status → outcome: `<400` ok, `>=400` error, absent neutral. */
+export function integrationOutcome(httpStatus) {
+    if (httpStatus === null || httpStatus === undefined)
+        return "neutral";
+    return httpStatus < 400 ? "ok" : "error";
+}
+/**
+ * Workflow *run* status → outcome:
+ *   completed → ok; failed/terminated → error;
+ *   queued/running/apply_pending/apply_claimed → pending;
+ *   missing → neutral; else neutral.
+ *
+ * The cases cover the full canonical run-status vocabulary (`lib/run-status.ts`,
+ * #2348) — since that change the server reconciles every status surface onto
+ * those eight values, so nothing else should reach the default. `missing` (no
+ * live instance to report on) stays neutral rather than error: it says the
+ * platform lost sight of the run, not that the run failed. That matches the
+ * outcome table published in
+ * `primitive-docs/guides/latest/AGENT_GUIDE_TO_PRIMITIVE_INSPECTION.template.md`.
+ */
+export function workflowRunOutcome(status) {
+    switch (status) {
+        case "completed":
+            return "ok";
+        case "failed":
+        case "terminated":
+            return "error";
+        case "queued":
+        case "running":
+        case "apply_pending":
+        case "apply_claimed":
+            return "pending";
+        case "missing":
+            return "neutral";
+        // #2636 — an elided run (its declarative lock was held and the definition
+        // declared `onContention: "ignore"`) did not run and did not fail, so it
+        // is neutral rather than an error. An operator measuring contention volume
+        // lists these; an alerting consumer ignores them.
+        case "skipped":
+            return "neutral";
+        default:
+            return "neutral";
+    }
+}
+/**
+ * Workflow *step* status → outcome:
+ *   completed → ok; failed/error_captured → error; skipped → neutral.
+ */
+export function workflowStepOutcome(status) {
+    switch (status) {
+        case "completed":
+            return "ok";
+        case "failed":
+        case "error_captured":
+            return "error";
+        case "skipped":
+            return "neutral";
+        default:
+            return "neutral";
+    }
+}
+/**
+ * Webhook event status → outcome. Documented policy table:
+ *   accepted / duplicate / handshake / workflow_inactive → ok
+ *   rejected / error → error
+ *   (anything else) → neutral
+ *
+ * `workflow_inactive` maps to `ok` on purpose: the event was accepted, it
+ * just wasn't dispatched to a live workflow. Treating it as an error would
+ * mislead a debugging session into reading a non-dispatch as a failure.
+ */
+export function webhookOutcome(status) {
+    switch (status) {
+        case "accepted":
+        case "duplicate":
+        case "handshake":
+        case "workflow_inactive":
+            return "ok";
+        case "rejected":
+        case "error":
+            return "error";
+        default:
+            return "neutral";
+    }
+}
+// ── Per-source adapters (allowlist projection) ───────────────────────
+/**
+ * Drop keys with no value. `null` counts as "no value": the admin routes
+ * serialize unset optional fields as `null`, and an allowlist entry that isn't
+ * set should be absent from `--json`, not present-and-null.
+ */
+function omitEmpty(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined && v !== null)
+            out[k] = v;
+    }
+    return out;
+}
+export function toIntegrationInspectionRow(raw) {
+    const status = raw.status ?? null;
+    return {
+        source: "integration",
+        timestamp: raw.timestamp ?? null,
+        outcome: integrationOutcome(status),
+        nativeStatus: status,
+        durationMs: raw.durationMs ?? null,
+        correlation: omitEmpty({
+            // #3691 — a workflow step's run, or a function run's. Both are on the
+            // row under the same name, because a call belongs to one run either
+            // way; the id the CLI prints is the one the run surfaces take.
+            runId: raw.runId,
+            stepId: raw.stepId,
+            traceId: raw.traceId,
+            workflowKey: raw.workflowKey,
+            functionId: raw.functionId,
+            integrationKey: raw.integrationKey,
+            userId: raw.actorId,
+        }),
+        detail: omitEmpty({
+            method: raw.method,
+            path: raw.path,
+            callSource: raw.source,
+            functionKey: raw.functionKey,
+            requestBytes: raw.requestBytes,
+            responseBytes: raw.responseBytes,
+            errorCode: raw.errorCode,
+            actorType: raw.actorType,
+            actorEmail: raw.actorEmail,
+        }),
+    };
+}
+export function toWorkflowRunInspectionRow(raw) {
+    const status = raw.status ?? null;
+    return {
+        source: "workflow-run",
+        timestamp: raw.startedAt ?? null,
+        outcome: workflowRunOutcome(status),
+        nativeStatus: status,
+        durationMs: null,
+        correlation: omitEmpty({
+            runId: raw.runId,
+            // #2074 — the failed step is the row an operator pivots to next
+            // (`runs steps` / `runs error`), so it rides in the correlation block
+            // like every other cross-store key.
+            stepId: raw.failedStepId,
+            workflowId: raw.workflowId,
+            workflowKey: raw.workflowKey,
+            userId: raw.startedByUserId,
+        }),
+        detail: omitEmpty({
+            workflowKey: raw.workflowKey,
+            isPreview: raw.isPreview,
+            queueDelayMs: raw.queueDelayMs,
+            createCallDurationMs: raw.createCallDurationMs,
+            executionStartedAt: raw.executionStartedAt,
+            endedAt: raw.endedAt,
+            initiatorKind: raw.initiatorKind,
+            errorMessage: raw.errorMessage,
+            // #2636 — the run-level classification an operator branches on instead of
+            // matching the message, and the reason an elided run did not run.
+            errorCode: raw.errorCode,
+            skipReason: raw.skipReason,
+            // #2074 — failure summary. `errorDetails` is deliberately absent: the
+            // step-detail policy is the message only, never the stack-bearing field.
+            errorTitle: raw.errorTitle,
+            failedStepId: raw.failedStepId,
+            failedStepKind: raw.failedStepKind,
+            failedStepErrorTitle: raw.failedStepErrorTitle,
+        }),
+    };
+}
+/**
+ * The CLI's single answer to "which step failed this run" (#2074).
+ *
+ * The server denormalizes the failed step onto the run row using one selector
+ * (`src/workflows/failed-step.ts`: lowest `stepIndex` with `status: "failed"`).
+ * When that attribution is present, this returns exactly that row, so the STEP
+ * column in `runs failures` and the drill-down in `runs error` can never name
+ * different steps for the same run. Runs written before that change (or by a
+ * launch-time failure that held no step results) carry no `failedStepId`; the
+ * fallback applies the same rule locally — lowest `stepIndex` first — instead
+ * of trusting whatever order the step-run query returned.
+ */
+export function selectFailedStepRow(steps, failedStepId) {
+    if (!steps || steps.length === 0)
+        return null;
+    if (failedStepId) {
+        const named = steps.find((s) => s?.stepId === failedStepId);
+        if (named)
+            return named;
+    }
+    let best = null;
+    let bestIndex = Number.POSITIVE_INFINITY;
+    for (const step of steps) {
+        if (!step || step.status !== "failed")
+            continue;
+        const index = typeof step.stepIndex === "number" && Number.isFinite(step.stepIndex)
+            ? step.stepIndex
+            : Number.POSITIVE_INFINITY;
+        if (best === null || index < bestIndex) {
+            best = step;
+            bestIndex = index;
+        }
+    }
+    return best;
+}
+/** Longest ERROR cell the `runs failures` table prints before truncating. */
+export const FAILURE_ERROR_CELL_MAX_LENGTH = 50;
+/**
+ * The STEP cell of `workflows runs failures` (#2074). `-` is a routine
+ * outcome, not a bug: every launch-time failure (a run that aborted before any
+ * step ran, a reclaimed run, an output-schema violation after all steps
+ * completed) legitimately has no failed step to name, as do runs written before
+ * the attribution shipped.
+ */
+export function formatFailureStepCell(failedStepId) {
+    return failedStepId || "-";
+}
+/**
+ * The CODE cell of `workflows runs failures` / `runs error` (#2636). `-` is the
+ * routine case: the platform classifies only the failures it owns (a lost
+ * declarative-lock race, an exhausted lock wait), so every other failure — and
+ * every run written before the codes — reads `-`.
+ */
+export function formatFailureCodeCell(errorCode) {
+    return errorCode || "-";
+}
+/**
+ * The ERROR cell of `workflows runs failures` (#2074). The full untruncated
+ * message stays available in `--json` and in `runs error <runId>`; the table
+ * truncates so the row still fits a terminal.
+ */
+export function formatFailureErrorCell(errorMessage) {
+    if (!errorMessage)
+        return "-";
+    return errorMessage.length > FAILURE_ERROR_CELL_MAX_LENGTH
+        ? `${errorMessage.slice(0, FAILURE_ERROR_CELL_MAX_LENGTH - 3)}...`
+        : errorMessage;
+}
+export function toWorkflowStepInspectionRow(raw) {
+    const status = raw.status ?? null;
+    return {
+        source: "workflow-step",
+        timestamp: raw.startedAt ?? null,
+        outcome: workflowStepOutcome(status),
+        nativeStatus: status,
+        durationMs: raw.durationMs ?? null,
+        correlation: omitEmpty({
+            runId: raw.runId,
+            stepId: raw.stepId,
+            // The row's own id: an inspection view keeps the key of the row it
+            // prints so a follow-up lookup has something to key on.
+            stepRunId: raw.stepRunId,
+        }),
+        // Deliberate allowlist: `error` is the message only. The stack-bearing
+        // error details / cause chain, the rendered/raw step config, the resolved
+        // input and output blobs (and their large-payload storage keys), and the
+        // per-execution script metrics are all omitted so no stack trace or
+        // storage key reaches `--json`.
+        detail: omitEmpty({
+            stepId: raw.stepId,
+            stepIndex: raw.stepIndex,
+            stepKind: raw.stepKind,
+            inputTokens: raw.inputTokens,
+            outputTokens: raw.outputTokens,
+            totalTokens: raw.totalTokens,
+            error: raw.error,
+        }),
+    };
+}
+export function toWebhookInspectionRow(raw) {
+    const status = raw.status ?? null;
+    return {
+        source: "webhook",
+        timestamp: raw.createdAt ?? null,
+        outcome: webhookOutcome(status),
+        nativeStatus: status,
+        durationMs: raw.processingDurationMs ?? null,
+        correlation: omitEmpty({
+            // The row's own id first: the human table prints it as EVENT ID and it
+            // is the key an operator uses for the follow-up lookup.
+            eventId: raw.eventId,
+            webhookId: raw.webhookId,
+            workflowRunId: raw.workflowRunId,
+        }),
+        // Allowlist: `sourceIp`, `headersReceived`, and `payloadHash` are omitted.
+        detail: omitEmpty({
+            externalEventId: raw.externalEventId,
+            dedupKey: raw.dedupKey ?? undefined,
+            httpStatus: raw.httpStatus,
+            rejectionReason: raw.rejectionReason,
+            workflowRunId: raw.workflowRunId,
+            payloadSummary: raw.payloadSummary,
+            processingDurationMs: raw.processingDurationMs,
+        }),
+    };
+}
+/**
+ * Activity events have no success/failure status, so `outcome` is `neutral`
+ * (never a fabricated `ok`) and `nativeStatus` is null. `detail` is a strict
+ * allowlist of the operator-facing fields (what happened, plus the app's own
+ * `context_json` and the recorded token counts) — every infrastructure-shaped
+ * field present on the wire (`colo`, `connection_id`, `region_code`,
+ * `entity_key`, …) is dropped by construction, not enumerated as a denylist.
+ */
+export function toActivityInspectionRow(raw) {
+    const invoke = functionInvokeStatus(raw);
+    return {
+        source: "activity",
+        timestamp: raw.timestamp ?? null,
+        // Activity events are counts, and reading one as a success or a failure
+        // would be fabricating a signal — with ONE exception (#3287). See
+        // `functionInvokeStatus`.
+        outcome: activityOutcome(invoke),
+        nativeStatus: invoke,
+        durationMs: raw.duration_ms ?? null,
+        correlation: omitEmpty({
+            userId: raw.user_ulid,
+        }),
+        detail: omitEmpty({
+            action: raw.action,
+            feature: raw.feature,
+            route: raw.route,
+            country: raw.country,
+            // The app's own event context rides through as `unknown` — it is
+            // caller-supplied, not an infrastructure field.
+            context: raw.context_json,
+            inputTokens: raw.input_tokens,
+            outputTokens: raw.output_tokens,
+            totalTokens: raw.total_tokens,
+        }),
+    };
+}
+/**
+ * An invocation record's status → outcome — #3287.
+ *
+ * `completed` is the only success. Everything else that names a settled
+ * invocation is a failure an operator has to be able to COUNT: the function
+ * threw (`failed`), it ran out of wall clock (`timeout`), or the platform
+ * refused the dispatch before any code ran and recorded its own code
+ * (`FUNCTION_BUNDLE_MISSING` and friends). A status nobody has taught this
+ * function is `neutral`, never fabricated as `ok`.
+ */
+export function functionLogOutcome(status) {
+    if (!status)
+        return "neutral";
+    if (status === "completed")
+        return "ok";
+    if (status === "failed" || status === "timeout")
+        return "error";
+    // A slice that is still running has printed something and settled nothing.
+    if (status === "running")
+        return "pending";
+    // The platform's own refusal codes are SHOUTED, which is what tells them
+    // apart from a settled status without enumerating a list that would go
+    // stale the moment a code is added.
+    if (/^[A-Z][A-Z0-9_]*$/.test(status))
+        return "error";
+    return "neutral";
+}
+/**
+ * One invocation record in the SHARED inspection item shape — #3287,
+ * DSO3287-007.
+ *
+ * The guide requires every log view's JSON and follow output to carry
+ * `source`/`timestamp`/`outcome`/`nativeStatus`/`correlation`, so a consumer
+ * can classify and pivot without knowing which store answered. Projecting the
+ * native record straight out would have left function logs the one view that
+ * shared consumers could not read.
+ *
+ * `detail` is an allowlist, as every other adapter's is: the correlation keys
+ * move to `correlation`, and what stays is what the invocation did.
+ */
+/** The run a trigger descriptor names, when the record itself names none. */
+function triggerRunId(raw) {
+    const runId = raw.trigger?.runId;
+    return typeof runId === "string" && runId.length > 0 ? runId : undefined;
+}
+export function toFunctionLogInspectionRow(raw) {
+    const status = raw.status ?? null;
+    return {
+        source: "function-log",
+        timestamp: raw.startedAt ?? null,
+        outcome: functionLogOutcome(status),
+        nativeStatus: status,
+        durationMs: raw.durationMs ?? null,
+        correlation: omitEmpty({
+            // A trigger fire and a task slice name their run; a request invocation
+            // has none, and its own id is its key.
+            //
+            // The `workflow.call` bridge is the case that needs saying (CR3287-010):
+            // its record carries `runId: null` on purpose — the leaf has no run row
+            // of its own — and names the PARENT's run inside the trigger. Reading
+            // only `raw.runId` there dropped the one correlation that leads a failing
+            // leaf back to the run that called it, while keeping the workflow key
+            // and the step id beside it.
+            runId: raw.runId ?? triggerRunId(raw) ?? undefined,
+            workflowRunId: raw.runId ?? triggerRunId(raw) ?? undefined,
+            workflowKey: typeof raw.trigger?.workflowKey === "string"
+                ? raw.trigger.workflowKey
+                : undefined,
+            stepId: typeof raw.trigger?.stepId === "string"
+                ? raw.trigger.stepId
+                : undefined,
+            eventId: raw.invocationId,
+            userId: raw.attributionUserId ?? undefined,
+        }),
+        detail: omitEmpty({
+            functionKey: raw.functionKey ?? undefined,
+            configId: raw.configId ?? undefined,
+            contentHash: raw.contentHash ?? undefined,
+            triggerKind: raw.trigger?.kind,
+            // #3482 — `triggerKind` says which DOOR fired it; this says whether the
+            // platform ran the code inside the request or as a task run. Additive,
+            // and absent on a record written before the column.
+            runtime: raw.runtime ?? undefined,
+            errorCode: raw.errorCode ?? undefined,
+            errorMessage: raw.errorMessage ?? undefined,
+            errorStack: raw.errorStack ?? undefined,
+            stdout: raw.stdout,
+            stderr: raw.stderr,
+            truncated: raw.truncated,
+            logsUnavailable: raw.logsUnavailable,
+            // The console and the error fields were dropped because the platform
+            // could not load the secrets it redacts against — a record that is
+            // deliberately short, not a function that was quiet (CR3287-003).
+            contentSuppressed: raw.contentSuppressed,
+        }),
+    };
+}
+// ── Unsupported-flag rejection helper ────────────────────────────────
+/**
+ * The settled status a `function.invoke` activity row carries — #3287, D-2.
+ *
+ * The intent keeps the event a COUNT and adds no blob: the emit already puts
+ * the settled status in the event's context, so nothing on the write side
+ * moves. What moved is this — the shared inspection contract reported a failed
+ * invocation as `neutral`, which meant an operator could not count failures at
+ * all, and the count was the one thing the event was for.
+ *
+ * `context_json` arrives as an object or as a JSON STRING depending on the
+ * store, and an unparseable one is not a reason to guess: it answers null and
+ * the row stays `neutral`, exactly as every other action does.
+ */
+export function functionInvokeStatus(raw) {
+    if (raw.action !== "function.invoke")
+        return null;
+    let context = raw.context_json;
+    if (typeof context === "string") {
+        try {
+            context = JSON.parse(context);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!context || typeof context !== "object")
+        return null;
+    const status = context.status;
+    return typeof status === "string" && status.length > 0 ? status : null;
+}
+/**
+ * `function.invoke`'s status → outcome; every other action stays `neutral`.
+ *
+ * `started` is `pending` on purpose: a task start is in flight when the row is
+ * written, and its terminal outcome lives on the run row, which the
+ * `workflow-run` source already maps.
+ */
+export function activityOutcome(status) {
+    if (!status)
+        return "neutral";
+    if (status === "completed")
+        return "ok";
+    if (status === "failed" || status === "timeout")
+        return "error";
+    if (status === "started")
+        return "pending";
+    return "neutral";
+}
+/** Build the "flag not supported for this source" message (behavior 12). */
+export function unsupportedFlagMessage(flag, source, supported) {
+    const list = supported.length > 0 ? supported.join(", ") : "(none)";
+    return `--${flag} is not supported for ${source}. Supported filters: ${list}.`;
+}
+/**
+ * Reject any provided flag that the source cannot serve, with a clear message
+ * listing the supported flags — never a silent no-op. `provided` maps flag
+ * names to their (possibly undefined) values; only flags with a defined value
+ * are checked. Throws on the first unsupported flag.
+ */
+export function assertSupportedFlags(source, provided, supported) {
+    const allowed = new Set(supported);
+    for (const [flag, value] of Object.entries(provided)) {
+        if (value === undefined || value === null)
+            continue;
+        if (!allowed.has(flag)) {
+            throw new Error(unsupportedFlagMessage(flag, source, supported));
+        }
+    }
+}
+function paginationOf(page) {
+    const nextCursor = page.nextCursor ?? page.cursor ?? null;
+    return {
+        nextCursor,
+        hasMore: page.hasMore ?? !!nextCursor,
+        cursor: nextCursor,
+        // #2237 — pass through only when the server reported it, so the envelope
+        // against an older server is unchanged rather than carrying `scanned: 0`
+        // (which would read as "searched nothing").
+        ...(typeof page.scanned === "number" ? { scanned: page.scanned } : {}),
+    };
+}
+export function buildIntegrationEnvelope(raw) {
+    return { items: raw.map(toIntegrationInspectionRow) };
+}
+export function buildWorkflowRunEnvelope(raw, page = {}) {
+    return { items: raw.map(toWorkflowRunInspectionRow), ...paginationOf(page) };
+}
+/**
+ * The `workflows runs list --json` envelope (#3646).
+ *
+ * `runs list` is a `list` verb, so what it prints is the CLI's one list
+ * envelope — `{items, hasMore, nextCursor?}`, with `nextCursor` OMITTED on the
+ * last page and the deprecated `cursor` alias not re-emitted — rather than the
+ * endpoint's #1316 envelope passed through, which is what
+ * {@link buildWorkflowRunEnvelope} still does for `runs failures` (a sweep, not
+ * a `list`). The rows are the same inspection shape either way, and `scanned`
+ * (#2237) survives as a key beside the envelope's three because it describes
+ * how far the filtered read got, which is not a pagination claim.
+ */
+export function buildWorkflowRunListEnvelope(raw, page = {}) {
+    const envelope = normalizeCliListEnvelope({
+        items: raw.map(toWorkflowRunInspectionRow),
+        hasMore: page.hasMore,
+        nextCursor: page.nextCursor ?? page.cursor,
+    });
+    return typeof page.scanned === "number"
+        ? { ...envelope, scanned: page.scanned }
+        : envelope;
+}
+export function buildWorkflowStepEnvelope(raw) {
+    return { items: raw.map(toWorkflowStepInspectionRow) };
+}
+export function buildWebhookEnvelope(raw, page = {}) {
+    return { items: raw.map(toWebhookInspectionRow), ...paginationOf(page) };
+}
+/**
+ * Normalize the `analytics/events` response into the activity envelope:
+ * `{page_size, rows}` → `{pageSize, items}`, `total_rows` → `totalRows`, and
+ * every row projected through the activity allowlist so infrastructure-shaped
+ * fields (`colo`, `connection_id`, …) are dropped by construction (behavior 9).
+ */
+export function buildActivityEnvelope(resp) {
+    return {
+        items: (resp.rows ?? []).map((row) => toActivityInspectionRow(row)),
+        page: resp.page ?? 0,
+        pageSize: resp.page_size ?? 0,
+        totalRows: resp.total_rows ?? 0,
+    };
+}
+// ─── #2237: collect-N-failures sweep ────────────────────────────────────────
+/** Server cap on `limit` for the run-list routes. */
+export const RUN_LIST_MAX_LIMIT = 200;
+/**
+ * Default ceiling on index rows a single `runs failures` sweep will examine.
+ *
+ * The ceiling is checked between requests, against the `scanned` the server
+ * reports — the server has no public per-request scan-budget parameter, so the
+ * CLI cannot bound a request before issuing it. A sweep therefore stops at the
+ * first request boundary at or past `--max-scan`, which means it can examine up
+ * to one server request's worth of extra rows (the filtered read is bounded at
+ * {@link SERVER_SCAN_ROWS_PER_REQUEST}). `--max-scan 100` really examines that
+ * many rows, not 100 — so the bound is documented as "to the nearest request"
+ * in the help text, the docs page and the agent guide rather than left to
+ * surprise the caller (#2237 review; #2280 tracks a real per-request budget
+ * parameter). The count the command *reports* is always the true `scanned`, so
+ * nothing it prints is wrong — only the flag's granularity is coarse.
+ */
+export const DEFAULT_FAILURE_SWEEP_MAX_SCAN = 5000;
+/**
+ * Rows a single filtered server request examines at most
+ * (`BOUNDED_SCAN_MAX_SCANNED` in `src/app-api/helpers/bounded-index-scan.ts`).
+ * Documented here because it is the granularity of `--max-scan`.
+ */
+export const SERVER_SCAN_ROWS_PER_REQUEST = 1000;
+/**
+ * Hard ceiling on requests per sweep. `--max-scan` is the user-facing bound,
+ * but it is enforced from the server's `scanned` field — an older server that
+ * does not report it would otherwise let the loop run until the index ended.
+ *
+ * It is independent of `--max-scan`, so a sweep that stops here reports its own
+ * stop reason (`"request-ceiling"`): telling a user who already passed
+ * `--max-scan 0` to raise `--max-scan` is advice they cannot act on (#2237
+ * review).
+ */
+export const FAILURE_SWEEP_MAX_REQUESTS = 200;
+/**
+ * Walk the bounded server-side scan until `limit` FAILURES are collected,
+ * history is exhausted, or `maxScan` index rows have been examined (#2237).
+ *
+ * `--limit N` has always been documented as "Number of failures to show", but
+ * it was passed straight through as the server's `limit` — and the server's
+ * filtered read is bounded, so a workflow with a long success streak answered
+ * with an empty page plus a cursor and the CLI printed "No failures found."
+ * The bound has to live somewhere: keeping it in the server would either make
+ * every filtered request expensive or still lie one streak deeper, so it lives
+ * here, where it is explicit (`--max-scan`), tunable and interruptible.
+ *
+ * Extracted from the command so the loop is unit-testable without a server:
+ * the aggregation of `scanned` across resumed pages is exactly the thing a
+ * future caller would get wrong, and the repeated-cursor guard (borrowed from
+ * `paginateAll`) is what keeps a non-advancing server cursor from hanging the
+ * command.
+ */
+export async function collectWorkflowFailures(fetchPage, options) {
+    const limit = Math.max(1, options.limit);
+    const maxScan = options.maxScan ?? DEFAULT_FAILURE_SWEEP_MAX_SCAN;
+    const maxRequests = options.maxRequests ?? FAILURE_SWEEP_MAX_REQUESTS;
+    const items = [];
+    const seenCursors = new Set();
+    let cursor = options.startCursor;
+    let scanned = 0;
+    let scannedKnown = false;
+    let requests = 0;
+    // Every other exit is an explicit `break` that sets its own reason, so the
+    // initializer is the reason for the one exit that is NOT a break: the `while`
+    // condition failing on the request ceiling.
+    let stoppedBecause = "request-ceiling";
+    while (requests < maxRequests) {
+        if (options.shouldStop?.()) {
+            stoppedBecause = "interrupted";
+            break;
+        }
+        const page = await fetchPage({
+            cursor,
+            // The server caps `limit` at 200; ask only for what is still missing so
+            // the last request does not over-fetch.
+            limit: Math.min(limit - items.length, RUN_LIST_MAX_LIMIT),
+        });
+        requests++;
+        for (const item of page.items ?? []) {
+            if (items.length >= limit)
+                break;
+            items.push(item);
+        }
+        if (typeof page.scanned === "number") {
+            scanned += page.scanned;
+            scannedKnown = true;
+        }
+        options.onProgress?.(scanned, items.length);
+        const next = page.nextCursor ?? page.cursor ?? undefined;
+        if (!next) {
+            cursor = undefined;
+            stoppedBecause = "exhausted";
+            break;
+        }
+        if (seenCursors.has(next)) {
+            throw new Error(`Pagination cursor did not advance (cursor ${next} repeated); aborting to avoid an infinite loop.`);
+        }
+        seenCursors.add(next);
+        cursor = next;
+        if (items.length >= limit) {
+            stoppedBecause = "collected";
+            break;
+        }
+        // Checked after the response, because the row budget is only knowable from
+        // the server's `scanned` and there is no public parameter to bound a
+        // request before issuing it. The overshoot is therefore at most one
+        // request's worth of rows — the granularity `--max-scan` is documented
+        // with (#2237 review).
+        if (maxScan > 0 && scanned >= maxScan) {
+            stoppedBecause = "max-scan";
+            break;
+        }
+    }
+    return {
+        items,
+        scanned,
+        scannedKnown,
+        nextCursor: cursor ?? null,
+        requests,
+        resumed: !!options.startCursor,
+        stoppedBecause,
+    };
+}
+/**
+ * The empty-state line for a run-list PAGE (`runs list`) (#2237).
+ *
+ * `runs list` stays a pager — its `--limit` is a page size and it does not
+ * auto-resume (that would make one flag mean two different things depending on
+ * whether `--status` was passed). But a filtered page comes from the same
+ * bounded index walk, so "No runs found." asserts the same absence it cannot
+ * back up. This says how far the read got and how to continue instead.
+ *
+ * `resumed` is true when the caller passed `--cursor`: the rows this page
+ * examined then start at that position rather than at the head of the index, so
+ * calling them "the most recent runs" would be false (#2237 review).
+ */
+export function describeEmptyRunPage(page, resumed = false) {
+    const nextCursor = page.nextCursor ?? page.cursor ?? null;
+    if (nextCursor) {
+        const where = typeof page.scanned === "number"
+            ? resumed
+                ? ` in ${page.scanned} runs from this position`
+                : ` in the ${page.scanned} most recent runs`
+            : " so far";
+        return `No matching runs${where}. More history remains — re-run with --cursor ${nextCursor}.`;
+    }
+    if (typeof page.scanned === "number") {
+        return resumed
+            ? `No matching runs in the remaining ${page.scanned} runs from this position.`
+            : `No matching runs. Searched all ${page.scanned} runs.`;
+    }
+    return "No runs found.";
+}
+/**
+ * The line `runs failures` prints under (or instead of) its table (#2237).
+ *
+ * The unconditional "No failures found." was the defect the issue named as
+ * "the worst possible failure mode for a triage command": a bounded search
+ * that stopped early asserted the absence of failures it had never reached.
+ * Every form below either states the search was complete or says how far it
+ * got and how to continue — and none of them claims absence it cannot back up.
+ *
+ * Returns `null` when the result speaks for itself (a full set of failures
+ * from a completed search).
+ */
+export function describeFailureSweep(result, limit) {
+    const found = result.items.length;
+    const complete = result.stoppedBecause === "exhausted";
+    // Against a server that does not report `scanned` we still say what we know
+    // ("more history remains") — we just do not invent a row count. And on a
+    // resumed sweep the rows examined start at the supplied cursor, so they are
+    // NOT "the most recent runs" (#2237 review).
+    const window = !result.scannedKnown
+        ? "the runs searched"
+        : result.resumed
+            ? `${result.scanned} runs from this position`
+            : `the ${result.scanned} most recent runs`;
+    // The request ceiling is independent of `--max-scan`, so a sweep that stopped
+    // there must not tell the user to raise a flag that cannot move it.
+    const ceiling = result.stoppedBecause === "request-ceiling";
+    const resume = result.nextCursor
+        ? ceiling
+            ? ` re-run with --cursor ${result.nextCursor} to continue.`
+            : ` re-run with --cursor ${result.nextCursor} (or raise --max-scan).`
+        : ceiling
+            ? " re-run to continue the search."
+            : " raise --max-scan to keep searching.";
+    if (complete) {
+        if (found > 0)
+            return null;
+        if (!result.scannedKnown) {
+            return result.resumed
+                ? "No failures in the rest of this workflow's history from this position."
+                : "No failures. Searched all of this workflow's history.";
+        }
+        return result.resumed
+            ? `No failures in the remaining ${result.scanned} runs from this position.`
+            : `No failures. Searched all ${result.scanned} runs.`;
+    }
+    const interrupted = result.stoppedBecause === "interrupted" ? "Interrupted. " : "";
+    if (found === 0) {
+        return `${interrupted}No failures in ${window}. More history remains —${resume}`;
+    }
+    if (found >= limit) {
+        return `${interrupted}${found} failures found in ${window}. More history remains —${resume}`;
+    }
+    return `${interrupted}${found} of ${limit} requested failures found in ${window}. More history remains —${resume}`;
+}
+//# sourceMappingURL=log-inspection.js.map