@greatwait/cli 0.3.1 → 0.3.3

package/dist/args.js

@@ -29,7 +29,7 @@ const SECRET_BEARING_FLAGS = new Set(["--api-key"]);
  * repeats the value back.
  */
 export function secretArgumentAdvice(programName) {
-    return `A credential given as an argument is visible to every process on this machine and is written to your shell history — treat the one you just typed as exposed and replace it. Run the command with a bare --api-key and paste the secret when asked, or pipe it in: printf %s "$KEY" | ${programName} login --api-key`;
+    return `A key passed as an argument is visible to every process on this machine and lands in your shell history, so treat it as exposed and replace it. Next time, run the command with a bare --api-key and paste the key when asked, or pipe it in: printf %s "$KEY" | ${programName} login --api-key`;
 }
 export function parseArguments(argv, 
 /**

package/dist/bulk.js

@@ -71,10 +71,10 @@ const confirm = async (runtime, args) => {
     const active = await session(runtime, args);
     const current = parseResponse("bulk.read", await active.client.request("bulk_read", id));
     if (!current.complete || current.intentDigest !== parsed.data.intentDigest)
-        throw new CliError("The job is incomplete or the intent digest differs; refresh the preview", "validation");
+        throw new CliError("The job isn't finished, or the preview changed. Make a new preview", "validation");
     if (current.intent.operation === "retry" &&
         !parsed.data.acknowledgeDuplicateEffects)
-        throw new CliError("Retry requires --acknowledge-duplicate-effects", "usage", "A receiver may already have acted; explicit redelivery can repeat external effects.");
+        throw new CliError("Retry requires --acknowledge-duplicate-effects", "usage", "Your server may already have acted. Redelivering can make it act twice.");
     const confirmation = await confirmChange(runtime, args, {
         action: `Confirm ${current.intent.operation} for frozen bulk job ${id}.`,
         effect: [
@@ -84,7 +84,7 @@ const confirm = async (runtime, args) => {
             `parameters ${JSON.stringify(current.intent.parameters)}`,
             `matched ${String(current.counts.matched)}; eligible ${String(current.counts.eligible)}; ineligible ${String(current.counts.ineligible)}`,
             ...current.warnings,
-            "Already-sent requests cannot be recalled and ordinary quotas and per-attempt billing apply.",
+            "Requests already sent can't be recalled, and each attempt is billed as usual.",
         ],
     });
     const key = args.options["--idempotency-key"] ??
@@ -114,7 +114,7 @@ function control(action) {
             action: `${action} remaining work in bulk job ${id}.`,
             effect: [
                 `operation ${current.intent.operation}; state ${current.state}; expected version ${String(parsed.data.expectedVersion)}`,
-                "This controls the job, not selected schedules. Already-started items may finish; committed effects remain.",
+                "This controls the job, not the schedules in it. Items already started may finish.",
             ],
         });
         const job = parseResponse(`bulk.${action}`, await active.client.request(`bulk_${action}`, id, parsed.data));

package/dist/catalog.js

@@ -282,7 +282,7 @@ export const COMMAND_CATALOG = [
     {
         group: "Bulk operations",
         words: "bulk preview",
-        summary: "Prepare an exact all-matching or selected-ID preview for retry, cancel, reschedule, pause or resume.",
+        summary: "Preview a retry, cancel, reschedule, pause or resume across matching or chosen items.",
         operations: ["bulk.preview"],
         positionals: [],
         options: [
@@ -290,14 +290,14 @@ export const COMMAND_CATALOG = [
             {
                 flag: "--intent",
                 value: "<json|@file|->",
-                summary: "Canonical bulk request: operation, target, selection and operation-specific parameters. Preview never sends deliveries or changes schedules.",
+                summary: "The bulk request: operation, target, selection and parameters. A preview never sends anything or changes schedules.",
             },
         ],
     },
     {
         group: "Bulk operations",
         words: "bulk confirm",
-        summary: "Confirm the exact frozen preview and start its bounded asynchronous job.",
+        summary: "Confirm a preview and start its job.",
         operations: ["bulk.read", "bulk.confirm"],
         confirms: true,
         positionals: [
@@ -314,7 +314,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 flag: "--acknowledge-duplicate-effects",
-                summary: "Explicitly acknowledge retry's potential duplicate receiver effects; required for retry.",
+                summary: "Confirm you understand a retry may reach your server twice. Required for retry.",
             },
         ],
     },
@@ -331,7 +331,7 @@ export const COMMAND_CATALOG = [
     {
         group: "Bulk operations",
         words: "bulk list",
-        summary: "List authorized retained bulk jobs in this project and environment.",
+        summary: "List bulk jobs in this project and environment.",
         operations: ["bulk.list"],
         positionals: [],
         options: [
@@ -703,7 +703,7 @@ export const COMMAND_CATALOG = [
             {
                 flag: "--diagnostic",
                 value: "<category>",
-                summary: "A classified attempt diagnostic, including transport failures without a response.",
+                summary: "Why an attempt failed, including network failures with no response.",
             },
             {
                 flag: "--endpoint",
@@ -754,12 +754,42 @@ export const COMMAND_CATALOG = [
                 value: "<instant>",
                 summary: "Only schedules with an unsettled run before this RFC 3339 instant.",
             },
+            {
+                flag: "--due-after",
+                value: "<instant>",
+                summary: "Only schedules whose next run is at or after this RFC 3339 instant.",
+            },
+            {
+                flag: "--order",
+                value: "<order>",
+                summary: "created (the default) or due. due lists what runs next first, and leaves out schedules with no next run.",
+            },
+            {
+                flag: "--direction",
+                value: "<direction>",
+                summary: "asc (the default) or desc: newest created, or latest due, first. Keep it when you carry on with --cursor.",
+            },
             ...PAGE_OPTIONS,
         ],
         positionals: [],
         summary: "List this project's schedules.",
         words: "schedules list",
     },
+    {
+        group: "Schedules",
+        operations: ["schedules.summary"],
+        options: [
+            API_URL,
+            {
+                flag: "--time-zone",
+                value: "<zone>",
+                summary: "IANA time zone the daily counts are taken in, such as Europe/London. Defaults to UTC.",
+            },
+        ],
+        positionals: [],
+        summary: "Count this project's schedules by status, and those created and finished each day for 30 days.",
+        words: "schedules summary",
+    },
     {
         group: "Schedules",
         operations: ["schedules.read"],
@@ -826,7 +856,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 flag: "--latency-class",
-                summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
+                summary: "auto, realtime or bulk. realtime goes first when both are due. auto, the default, makes a call due within a minute realtime and everything else bulk.",
                 value: "<class>",
             },
             {
@@ -923,7 +953,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 flag: "--latency-class",
-                summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
+                summary: "auto, realtime or bulk. realtime goes first when both are due. auto, the default, makes a call due within a minute realtime and everything else bulk.",
                 value: "<class>",
             },
             {
@@ -960,7 +990,7 @@ export const COMMAND_CATALOG = [
                 summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
             },
         ],
-        summary: "Change when a schedule runs. Destination, data, HTTP and delivery settings stay unless you give new ones. Timing is replaced; latency class and lateness policy are re-derived; pending occurrences are discarded. A concurrent edit can refuse this change.",
+        summary: "Change when a schedule runs. Destination, data, HTTP and delivery settings stay unless you give new ones. Priority and late-run policy are worked out again, and pending runs are dropped. Refused if someone else changed it first.",
         words: "schedules replace",
     },
     {
@@ -1041,7 +1071,9 @@ export const COMMAND_CATALOG = [
     {
         group: "Data exports",
         operations: ["exports.part"],
-        options: [API_URL, PAGE_OPTIONS[0]],
+        // The cursor, not the page size: a part is one bounded file, and the
+        // command carries on from the cursor the previous part printed.
+        options: [API_URL, PAGE_OPTIONS[1]],
         positionals: [
             {
                 name: "<export>",
@@ -1824,6 +1856,11 @@ export const COMMAND_CATALOG = [
  * control plane refuses on purpose.
  */
 export const OPERATION_OMISSIONS = [
+    {
+        because: "Dismiss answers the delivery-failure line a member sees in the workspace chrome (W9-79); a terminal has no such line to clear. `billing notices` lists the notices, and the MCP tool provides the automation path.",
+        ground: "declared",
+        operation: "billing.noticesdismiss",
+    },
     {
         because: "Organization lifecycle authority belongs to a signed-in organization administrator in a browser session. A CLI credential is deliberately project-bound and cannot acquire or widen itself to organization authority.",
         ground: "principal-unreachable",
@@ -1889,6 +1926,11 @@ export const OPERATION_OMISSIONS = [
         ground: "principal-unreachable",
         operation: "projects.create",
     },
+    {
+        because: "The counted project read is the deletion preview a signed-in person sees in Project General before deleting; a credential is not accepted.",
+        ground: "principal-unreachable",
+        operation: "projects.read",
+    },
     {
         because: "Project General is the accepted rename surface in this story. The generated SDK and MCP expose the operation to automation; adding a second interactive CLI design is outside it.",
         ground: "declared",

package/dist/commands.js

@@ -1,7 +1,7 @@
 import { readPrivateJsonOption } from "./support.js";
 import { MEMBER_IMPLEMENTATIONS } from "./member-commands.js";
-import { GreatwaitClientError, createGreatwaitClient, } from "@greatwait/api-client";
-import { endpointHeaderChangesSchema, isTerminalOccurrenceState, responseSchemaFor, } from "@greatwait/contracts";
+import { GreatwaitClientError, WAIT_ATTEMPT_PAGES_CEILING, createGreatwaitClient, } from "@greatwait/api-client";
+import { PAGE_SIZE, endpointHeaderChangesSchema, isTerminalOccurrenceState, responseSchemaFor, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { COMMAND_CATALOG, REQUESTED_SCOPES } from "./catalog.js";
 import { confirmChange } from "./confirm.js";
@@ -12,7 +12,7 @@ import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
 import { anonymousClient, ENVIRONMENT_NAMES, openCredential, openSession, resolveOrigin, storeFor, } from "./session.js";
 import { OPERATE_COMMANDS, destinationLines, scheduleRequest } from "./operate.js";
-import { apiUrlOption, expectNoExtraArguments, parseResponse, positionals, } from "./support.js";
+import { apiUrlOption, continuationNote, drainPages, expectNoExtraArguments, pageFlagsCommand, pageRequest, parseResponse, positionals, shellQuote, } from "./support.js";
 /* -------------------------------------------------------------------------- */
 /* Signing in                                                                 */
 /* -------------------------------------------------------------------------- */
@@ -186,7 +186,7 @@ const login = async (runtime, args) => {
             },
             human: described.known
                 ? `Signed in to ${origin}, in project ${described.context.project} (${described.context.environmentKind}).`
-                : `Signed in to ${origin}. The grant is real — the service issued it — but it cannot say what it reaches.`,
+                : `Signed in to ${origin}, but the service couldn't say what this sign-in can reach.`,
             ...(described.known ? {} : { nextMove: described.reason }),
         };
     }
@@ -232,7 +232,7 @@ async function describeThrough(client, origin, programName) {
         if (error.status === 404) {
             return {
                 known: false,
-                reason: `${origin} does not publish GET /v1/context, so it cannot say which project this credential acts in. It is running a build from before that operation existed.`,
+                reason: `${origin} is running an older build without GET /v1/context, so it can't say which project this credential acts in.`,
             };
         }
         // **Anything else is the service having a moment, not a bad credential.**
@@ -767,12 +767,26 @@ const schedulesCreate = async (runtime, args) => {
             })(),
         };
     }
-    const attempts = parseResponse("attempts.list", await session.client.request("attempts_list", schedule, occurrence)).data;
+    // Every attempt page, bounded the way the SDK's wait is (W9-80): the first
+    // page alone settled a long retry history looking complete.
+    const { attempts, nextCursor } = await settledAttempts(session, schedule, occurrence);
     const delivered = watched.occurrence.state === "succeeded";
+    const more = nextCursor === undefined
+        ? undefined
+        : `More attempts than this wait reads. Continue with: ${runtime.programName} attempts list ${schedule} ${occurrence}${pageFlagsCommand(args)} --cursor ${nextCursor}`;
+    const failedMove = delivered
+        ? undefined
+        : recoveryFor("read-attempt", "attempt-failed");
+    const moves = [failedMove, more].filter((move) => move !== undefined);
     return {
         data: {
             ...data,
-            wait: { attempts, occurrence: watched.occurrence, settled: true },
+            wait: {
+                attempts,
+                ...(nextCursor === undefined ? {} : { attemptsNextCursor: nextCursor }),
+                occurrence: watched.occurrence,
+                settled: true,
+            },
         },
         human: [
             delivered
@@ -785,14 +799,28 @@ const schedulesCreate = async (runtime, args) => {
                 : [``, ...attempts.map(attemptLine)]),
             ...repeating,
         ].join("\n"),
-        ...(delivered
-            ? {}
-            : (() => {
-                const nextMove = recoveryFor("read-attempt", "attempt-failed");
-                return nextMove === undefined ? {} : { nextMove };
-            })()),
+        ...(moves.length === 0 ? {} : { nextMove: moves.join("\n") }),
     };
 };
+/**
+ * A settled occurrence's attempts: every page at the contract's largest size,
+ * up to the SDK's own ceiling, and the cursor if that stopped the read.
+ */
+async function settledAttempts(session, schedule, occurrence) {
+    const attempts = [];
+    let cursor;
+    for (let pages = 0; pages < WAIT_ATTEMPT_PAGES_CEILING; pages += 1) {
+        const page = parseResponse("attempts.list", await session.client.request("attempts_list", schedule, occurrence, {
+            ...(cursor === undefined ? {} : { cursor }),
+            limit: PAGE_SIZE.max,
+        }));
+        attempts.push(...page.data);
+        cursor = page.nextCursor;
+        if (cursor === undefined)
+            break;
+    }
+    return { attempts, nextCursor: cursor };
+}
 function attemptLine(attempt) {
     return `${attempt.state.padEnd(20)}${attempt.responseStatus === undefined ? "no response" : `answered ${String(attempt.responseStatus)}`}${attempt.diagnostic === undefined ? "" : `  ${attempt.diagnostic}`}${attempt.remediation === undefined ? "" : ` / ${attempt.remediation}`}`;
 }
@@ -895,11 +923,12 @@ const exportsRead = async (runtime, args) => {
 };
 const exportsPart = async (runtime, args) => {
     const [exportId] = positionals(args, ["<export>"], `${runtime.programName} exports part <export> [--cursor <cursor>]`);
-    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const apiUrl = apiUrlOption(args);
+    const session = await openSession(runtime, { apiUrl });
     const cursor = args.options["--cursor"];
     const part = parseResponse("exports.part", await session.client.request("exports_part", exportId, cursor === undefined ? {} : { cursor }));
     if (part.nextCursor !== undefined && !args.booleans.has("--json")) {
-        runtime.stderr(`More to export. Append the next bounded part with: ${runtime.programName} exports part ${exportId} --cursor '${part.nextCursor}' >> ${part.fileName}\n`);
+        runtime.stderr(`More to export. Append the next bounded part with: ${runtime.programName} exports part ${exportId}${apiUrl === undefined ? "" : ` --api-url ${shellQuote(apiUrl)}`} --cursor ${shellQuote(part.nextCursor)} >> ${part.fileName}\n`);
     }
     return {
         data: part,
@@ -1009,25 +1038,41 @@ const attemptsList = async (runtime, args) => {
     }
     expectNoExtraArguments(args, 2, `${runtime.programName} attempts list <schedule> <occurrence>`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    const page = responseSchemaFor("attempts.list")?.parse(await session.client.request("attempts_list", schedule, occurrence));
-    const failed = page.data.find((attempt) => attempt.state !== "succeeded");
+    // **One page, `--limit`, `--cursor` and `--all`, like every other listing**
+    // (W9-80). This read only ever fetched the first page and ignored the page
+    // flags its own help declared, so an occurrence retried past one page
+    // showed its earliest tries and never said there were more.
+    const drained = await drainPages(runtime, args, pageRequest(args), async (request) => parseResponse("attempts.list", await session.client.request("attempts_list", schedule, occurrence, request)));
+    const attempts = drained.rows;
+    const failed = attempts.find((attempt) => attempt.state !== "succeeded");
+    const continuation = continuationNote(drained, `${runtime.programName} attempts list ${schedule} ${occurrence}${pageFlagsCommand(args)}`);
+    // **The journey's own sentence, not a paraphrase of the code.**
+    // `diagnostic` and `remediation` are closed vocabularies rather than prose
+    // — the step's `observe` says to read them, and its recovery entry is the
+    // sentence written for a person meeting a failed attempt. Inventing a
+    // second one here would be this command maintaining its own copy of every
+    // delivery failure the service can classify.
+    const recovery = failed === undefined
+        ? undefined
+        : recoveryFor("read-attempt", "attempt-failed");
+    const notes = [recovery, continuation].filter((note) => note !== undefined);
     return {
-        data: { attempts: page.data, occurrence, schedule },
-        human: page.data.length === 0
+        // The keys this always had, plus the page bookkeeping every listing
+        // reports; `nextCursor` only when there is more to read.
+        data: {
+            attempts,
+            ceilingReached: drained.ceilingReached,
+            ...(drained.nextCursor === undefined
+                ? {}
+                : { nextCursor: drained.nextCursor }),
+            occurrence,
+            pages: drained.pages,
+            schedule,
+        },
+        human: attempts.length === 0
             ? "No attempt has been made yet."
-            : page.data.map(attemptLine).join("\n"),
-        // **The journey's own sentence, not a paraphrase of the code.**
-        // `diagnostic` and `remediation` are closed vocabularies rather than prose
-        // — the step's `observe` says to read them, and its recovery entry is the
-        // sentence written for a person meeting a failed attempt. Inventing a
-        // second one here would be this command maintaining its own copy of every
-        // delivery failure the service can classify.
-        ...(failed === undefined
-            ? {}
-            : (() => {
-                const nextMove = recoveryFor("read-attempt", "attempt-failed");
-                return nextMove === undefined ? {} : { nextMove };
-            })()),
+            : attempts.map(attemptLine).join("\n"),
+        ...(notes.length === 0 ? {} : { nextMove: notes.join("\n") }),
     };
 };
 /* -------------------------------------------------------------------------- */

package/dist/operate.js

@@ -1,12 +1,12 @@
 import { BULK_COMMANDS } from "./bulk.js";
 import { writeFile } from "node:fs/promises";
-import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, deliveryDurationSecondsSchema, deliveryCompletionModeSchema, deliveryOverlapPolicySchema, scheduleRequestSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, scheduleSelectionSchema, normalizeScheduleSelection, projectAttemptSearchRequestSchema, normalizeAttemptSelection, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, deliveryDurationSecondsSchema, deliveryCompletionModeSchema, deliveryOverlapPolicySchema, scheduleRequestSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, scheduleSelectionSchema, normalizeScheduleSelection, timeZoneSchema, SCHEDULE_DIRECTIONS, SCHEDULE_ORDERS, projectAttemptSearchRequestSchema, normalizeAttemptSelection, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { confirmChange } from "./confirm.js";
 import { redactSecret } from "./output.js";
 import { CliError } from "./runtime.js";
 import { openSession } from "./session.js";
-import { apiUrlOption, conditionalHeaders, continuationNote, drainPages, freshnessNote, pageRequest, parseInstant, parseResponse, positionals, readJsonOption, readPrivateJsonOption, table, } from "./support.js";
+import { apiUrlOption, conditionalHeaders, continuationNote, drainPages, freshnessNote, pageFlagsCommand, pageRequest, parseInstant, parseResponse, positionals, readJsonOption, readPrivateJsonOption, shellQuote, table, } from "./support.js";
 /* -------------------------------------------------------------------------- */
 /* Shared plumbing                                                            */
 /* -------------------------------------------------------------------------- */
@@ -24,7 +24,7 @@ async function session(runtime, args) {
 async function listing(runtime, args, options) {
     const drained = await drainPages(runtime, args, pageRequest(args), options.read);
     const notes = [
-        continuationNote(drained, options.command),
+        continuationNote(drained, `${options.command}${pageFlagsCommand(args)}`),
         freshnessNote(drained.freshness),
     ].filter((note) => note !== undefined);
     return {
@@ -37,7 +37,11 @@ async function listing(runtime, args, options) {
             pages: drained.pages,
             rows: drained.rows,
         },
-        human: table(options.columns, drained.rows.map(options.row), options.empty),
+        // An empty read that still carries a cursor is not the answer (W9-90):
+        // a filtered page can come back empty with more to read.
+        human: table(options.columns, drained.rows.map(options.row), drained.nextCursor === undefined
+            ? options.empty
+            : "Nothing matched in the part read so far; more remains to be read."),
         ...(notes.length === 0 ? {} : { nextMove: notes.join("\n") }),
     };
 }
@@ -451,6 +455,16 @@ const attemptsSearch = async (runtime, args) => {
         ],
     });
 };
+/** An option limited to a published set of words, refused before asking. */
+function oneOf(args, flag, values) {
+    const value = args.options[flag];
+    if (value === undefined)
+        return undefined;
+    if (!values.includes(value)) {
+        throw new CliError(`${flag} must be ${values.slice(0, -1).join(", ")} or ${values[values.length - 1]}`, "usage");
+    }
+    return value;
+}
 const schedulesList = async (runtime, args) => {
     const parsed = scheduleSelectionSchema.safeParse({
         ...correlationFilters(args),
@@ -461,17 +475,38 @@ const schedulesList = async (runtime, args) => {
         dueBefore: args.options["--due-before"] === undefined
             ? undefined
             : parseInstant(args.options["--due-before"], "--due-before"),
+        dueAfter: args.options["--due-after"] === undefined
+            ? undefined
+            : parseInstant(args.options["--due-after"], "--due-after"),
     });
     if (!parsed.success)
         throw new CliError("The schedule filters are invalid", "usage", parsed.error.issues
             .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
             .join("; "));
+    const order = oneOf(args, "--order", SCHEDULE_ORDERS);
+    const direction = oneOf(args, "--direction", SCHEDULE_DIRECTIONS);
     const filters = normalizeScheduleSelection(parsed.data);
     const active = await session(runtime, args);
     const endpoint = args.options["--endpoint"];
     return listing(runtime, args, {
         columns: ["STATUS", "NAME", "RECURRENCE", "DELIVERS TO", "SCHEDULE"],
-        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}${correlationCommand(args)}${["--status", "--recurrence", "--text", "--due-before"].flatMap((flag) => (args.options[flag] === undefined ? [] : [` ${flag} '${args.options[flag].replaceAll("'", "'\"'\"'")}'`])).join("")}`,
+        // Every flag that shaped the request is repeated, quoted: the service
+        // refuses a cursor under a different order, direction or filter, so a
+        // hint that dropped one could not be pasted (W9-80).
+        command: `${runtime.programName} schedules list${correlationCommand(args)}${[
+            "--endpoint",
+            "--status",
+            "--recurrence",
+            "--text",
+            "--due-before",
+            "--due-after",
+            "--order",
+            "--direction",
+        ]
+            .flatMap((flag) => args.options[flag] === undefined
+            ? []
+            : [` ${flag} ${shellQuote(args.options[flag])}`])
+            .join("")}`,
         // An empty filtered page answers the filter, not the project: "no
         // schedules yet" read as the project being empty when nothing matched.
         empty: Object.keys(filters).some((key) => key !== "endpoint")
@@ -483,6 +518,8 @@ const schedulesList = async (runtime, args) => {
             ...request,
             ...(endpoint === undefined ? {} : { endpoint }),
             ...filters,
+            ...(order === undefined ? {} : { order }),
+            ...(direction === undefined ? {} : { direction }),
         })),
         row: (schedule) => [
             schedule.status,
@@ -493,6 +530,64 @@ const schedulesList = async (runtime, args) => {
         ],
     });
 };
+/**
+ * Whole-project schedule counts (W9-80, FXO-3446).
+ *
+ * The counts a listing cannot give: `schedules list` reads one page, and a
+ * total taken from it is the page size. The service computes these over every
+ * retained schedule and reuses the answer for up to five minutes, so the age
+ * is printed beside them rather than presented as live.
+ */
+const schedulesSummary = async (runtime, args) => {
+    positionals(args, [], `${runtime.programName} schedules summary`);
+    const timeZone = args.options["--time-zone"];
+    if (timeZone !== undefined && !timeZoneSchema.safeParse(timeZone).success)
+        throw new CliError(`${timeZone} is not an IANA time zone`, "usage", "Write --time-zone as a zone name, such as Europe/London or America/Chicago.");
+    const active = await session(runtime, args);
+    const view = parseResponse("schedules.summary", await active.client.request("schedules_summary", timeZone === undefined ? {} : { timeZone }));
+    const { counts, pausedAfterFailures } = view;
+    const busyDays = view.days.filter((day) => day.created > 0 || day.finished > 0);
+    const total = (key) => view.days.reduce((sum, day) => sum + day[key], 0);
+    return {
+        data: view,
+        human: [
+            `As of        ${ageOf(view.freshness.lagSeconds)} (${view.freshness.asOf})`,
+            `Active       ${String(counts.active)}`,
+            `Paused       ${String(counts.paused)}${pausedAfterFailures.count === 0
+                ? ""
+                : `, ${String(pausedAfterFailures.count)} paused itself after repeated failures`}`,
+            `Completed    ${String(counts.completed)}`,
+            `Cancelled    ${String(counts.cancelled)}`,
+            ...(pausedAfterFailures.schedules.length === 0
+                ? []
+                : [
+                    ``,
+                    table(["PAUSED ITSELF", "AFTER", "WHY", "SCHEDULE"], pausedAfterFailures.schedules.map((schedule) => [
+                        schedule.name ?? "—",
+                        `${String(schedule.autoPauseReason.failedRuns)} failed runs`,
+                        schedule.autoPauseReason.diagnostic,
+                        schedule.id,
+                    ]), ""),
+                ]),
+            ``,
+            `${view.window.from} to ${view.window.to} (${view.window.timeZone}): ${String(total("created"))} created, ${String(total("finished"))} finished`,
+            // Thirty rows, most of them zero on a quiet project, would bury the
+            // days that had something in them; the zero days are in --json.
+            table(["DAY", "CREATED", "FINISHED"], busyDays.map((day) => [
+                day.date,
+                String(day.created),
+                String(day.finished),
+            ]), "No schedule was created or finished in these 30 days."),
+        ].join("\n"),
+        nextMove: "Counts cover retained schedules: retention removes cancelled schedules and one-off schedules that ran, once their history expires.",
+    };
+};
+/** How long ago, in the unit a person reads: seconds, then minutes. */
+function ageOf(seconds) {
+    if (seconds < 60)
+        return `${String(seconds)}s ago`;
+    return `${String(Math.floor(seconds / 60))} min ago`;
+}
 /**
  * A schedule lifecycle change: read, preview where one is owed, act, report.
  *
@@ -633,7 +728,9 @@ const occurrencesList = async (runtime, args) => {
     const active = await session(runtime, args);
     return listing(runtime, args, {
         columns: ["STATE", "PLANNED FOR", "OCCURRENCE", "ATTEMPTS"],
-        command: `${runtime.programName} occurrences list ${schedule}`,
+        // `--newest` is repeated because the service refuses a cursor issued for
+        // the other order: a hint without it could not be pasted (W9-80).
+        command: `${runtime.programName} occurrences list ${schedule}${args.booleans.has("--newest") ? " --newest" : ""}`,
         empty: "This schedule has no retained occurrences.",
         read: (request) => page("occurrences.list", () => active.client.request("occurrences_list", schedule, {
             ...request,
@@ -735,7 +832,7 @@ const attemptsRead = async (runtime, args) => {
     }
     diagnosticLines.push("What we sent");
     if (found.request === undefined)
-        diagnosticLines.push(requestCaptureSentence(found.requestState, found.state === undefined));
+        diagnosticLines.push(requestCaptureSentence(found.requestState, found.state === undefined, found.requestUnavailable));
     else
         diagnosticLines.push(`${found.request.method} ${found.request.url}`, ...found.request.headers.map((h) => `${h.name}: ${h.value}`), found.request.body === "" ? "We sent no body." : found.request.body);
     const guidance = attemptStatusGuidance(found.responseStatus);
@@ -1912,6 +2009,10 @@ function notificationPreferenceResult(settings) {
                 ? []
                 : [
                     `Events     ${webhook.events.join(", ")}`,
+                    // W9-84: the destination is an endpoint, whose key signs.
+                    ...(webhook.endpoint === undefined
+                        ? []
+                        : [`Endpoint   ${webhook.endpoint}`]),
                     `Signing key ${webhook.signingKey?.id ?? "not provisioned"}`,
                 ]),
         ].join("\n"),
@@ -2040,6 +2141,7 @@ export const OPERATE_COMMANDS = {
     "schedules archive": schedulesArchive,
     "schedules cancel": schedulesCancel,
     "schedules list": schedulesList,
+    "schedules summary": schedulesSummary,
     "executions list": executionsList,
     "attempts search": attemptsSearch,
     "schedules pause": schedulesPause,

package/dist/support.d.ts

@@ -103,6 +103,22 @@ export interface DrainedPages<TRow> {
 export declare function drainPages<TRow>(runtime: CliRuntime, args: ParsedArguments, request: PageRequest, read: (request: PageRequest) => Promise<Page<TRow>>): Promise<DrainedPages<TRow>>;
 /** The freshness of an answer, in a sentence, or nothing to say. */
 export declare function freshnessNote(freshness: Freshness): string | undefined;
+/**
+ * One argument, single-quoted for a POSIX shell, so a pasted hint means what
+ * it printed: `$`, backticks and spaces stay literal, and an embedded quote is
+ * closed, escaped and reopened.
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * The page flags a continuation hint must repeat (W9-80, FXO-3446).
+ *
+ * **A cursor is only valid with the request that issued it**, and the
+ * origin it came from. A hint that dropped `--api-url` sent the cursor to the
+ * signed-in default origin, and one that dropped `--limit` read the next page
+ * at a different size from the one the person chose. `--cursor` and `--all`
+ * are added by {@link continuationNote}.
+ */
+export declare function pageFlagsCommand(args: ParsedArguments): string;
 /**
  * What to say about a listing that stopped before the collection did.
  *

package/dist/support.js

@@ -216,6 +216,30 @@ export function freshnessNote(freshness) {
         return undefined;
     return `Read from a projection that was ${String(freshness.lagSeconds)}s behind at ${freshness.asOf}, so something newer than that may be missing.`;
 }
+/**
+ * One argument, single-quoted for a POSIX shell, so a pasted hint means what
+ * it printed: `$`, backticks and spaces stay literal, and an embedded quote is
+ * closed, escaped and reopened.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+/**
+ * The page flags a continuation hint must repeat (W9-80, FXO-3446).
+ *
+ * **A cursor is only valid with the request that issued it**, and the
+ * origin it came from. A hint that dropped `--api-url` sent the cursor to the
+ * signed-in default origin, and one that dropped `--limit` read the next page
+ * at a different size from the one the person chose. `--cursor` and `--all`
+ * are added by {@link continuationNote}.
+ */
+export function pageFlagsCommand(args) {
+    const limit = args.options["--limit"];
+    const apiUrl = args.options["--api-url"];
+    // `--limit` is a whole number by the time a page was read (`pageRequest`
+    // refuses anything else), so it needs no quoting; an origin might.
+    return `${limit === undefined ? "" : ` --limit ${limit}`}${apiUrl === undefined ? "" : ` --api-url ${shellQuote(apiUrl)}`}`;
+}
 /**
  * What to say about a listing that stopped before the collection did.
  *

package/package.json

@@ -7,8 +7,8 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.3.1",
-    "@greatwait/contracts": "0.3.1"
+    "@greatwait/api-client": "0.3.3",
+    "@greatwait/contracts": "0.3.3"
   },
   "description": "The GreatWait command line: sign in, schedule a call to a URL, and read its delivery outcome over the public API.",
   "engines": {
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.3.1"
+  "version": "0.3.3"
 }