@greatwait/cli 0.3.0 → 0.3.2

package/README.md

@@ -43,6 +43,13 @@ directory, readable by you and nobody else. A staging credential is never
 presented to production, because the two are separate entries rather than one
 current context.
 
+For a short script that needs a bearer token, `greatwait token` prints the
+credential for the selected API origin, refreshing an expiring OAuth sign-in
+first. Add `--api-url <origin>` to choose an origin explicitly. `--json` prints
+`{token, origin, expiresAt}`; an API key is returned unchanged with `null` expiry.
+This output is a secret: keep it out of logs, shell tracing and shared files.
+Use a scoped API key for unattended automation.
+
 ## First callback
 
 Use a public HTTPS receiver you control. Once signed in, schedule directly to
@@ -99,6 +106,8 @@ grant and remove local credentials.
 ## Output and exit codes
 
 `--json` is a versioned machine shape, not a serialization of the human text.
+The deliberate secret-output command `token --json` returns the credential object
+described above.
 The exit status is a class rather than a code per failure:
 
 | code | meaning                                                                |

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: [
@@ -493,6 +493,14 @@ export const COMMAND_CATALOG = [
         summary: "Sign out, and forget the credential stored on this machine.",
         words: "logout",
     },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [],
+        summary: "Print the credential for the selected origin, refreshing OAuth first when needed. Output is a secret: keep it out of logs and shell tracing. --json prints token, origin and expiresAt (null for API keys).",
+        words: "token",
+    },
     {
         group: "Session",
         operations: ["context.read"],
@@ -695,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",
@@ -746,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"],
@@ -818,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>",
             },
             {
@@ -831,10 +869,20 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
             {
                 flag: "--delivery-timeout",
                 value: "<duration>",
-                summary: "How long the receiver may take, such as 20s or 5m (whole seconds). Defaults to 5s on create; replace keeps the stored timeout. Response completion allows up to 30m; longer needs existing callback completion. Separate from --timeout for --wait.",
+                summary: "How long the receiver may take, such as 20s or 5m (whole seconds). Defaults to 5s on create; replace keeps the stored timeout. Response completion allows up to 30m; callback completion allows up to 24h. Separate from --timeout for --wait.",
             },
             IDEMPOTENCY,
             {
@@ -905,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>",
             },
             {
@@ -918,6 +966,16 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
             {
                 flag: "--delivery-timeout",
                 value: "<duration>",
@@ -932,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",
     },
     {
@@ -1013,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>",
@@ -1796,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",
@@ -1861,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";
@@ -10,9 +10,9 @@ import { awaitRedirect, buildAuthorization, codeFrom, discover, exchangeCode, re
 import { redactSecret } from "./output.js";
 import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
-import { anonymousClient, ENVIRONMENT_NAMES, openSession, resolveOrigin, storeFor, } from "./session.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.**
@@ -317,6 +317,13 @@ const CREDENTIAL_LABELS = {
     "environment-key": `an API credential from ${ENVIRONMENT_NAMES.apiKey}`,
     oauth: "an OAuth grant",
 };
+const token = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, `${runtime.programName} token [--api-url <origin>]`);
+    const { token, origin, expiresAt } = await openCredential(runtime, {
+        apiUrl: apiUrlOption(args),
+    });
+    return { human: token, data: { token, origin, expiresAt } };
+};
 const whoami = async (runtime, args) => {
     expectNoExtraArguments(args, 0, `${runtime.programName} whoami [--api-url <origin>]`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
@@ -677,6 +684,7 @@ const schedulesCreate = async (runtime, args) => {
     const schedule = created.schedule.id;
     const occurrence = created.occurrence.id;
     const data = {
+        delivery: created.schedule.delivery,
         ...(created.endpointSigningSecret === undefined
             ? {}
             : {
@@ -759,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
@@ -777,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}`}`;
 }
@@ -887,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,
@@ -1001,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") }),
     };
 };
 /* -------------------------------------------------------------------------- */
@@ -1052,6 +1105,7 @@ const IMPLEMENTATIONS = {
     "occurrences wait": occurrencesWait,
     "schedules create": schedulesCreate,
     "schedules read": schedulesRead,
+    token,
     whoami,
 };
 /**

package/dist/operate.d.ts

@@ -34,7 +34,7 @@ type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandRe
  * machine's would make the same expression mean different things on a laptop
  * and on a build runner.
  */
-declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string): Promise<Readonly<Record<string, unknown>>>;
+declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string, mode?: "create" | "replace"): Promise<Readonly<Record<string, unknown>>>;
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.

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, 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") }),
     };
 }
@@ -80,7 +84,7 @@ const RECURRENCE_FLAGS = ["--in", "--at", "--every", "--cron"];
  * machine's would make the same expression mean different things on a laptop
  * and on a build runner.
  */
-async function scheduleRequest(runtime, args, usage) {
+async function scheduleRequest(runtime, args, usage, mode = "create") {
     const given = RECURRENCE_FLAGS.filter((flag) => args.options[flag] !== undefined);
     if (given.length !== 1) {
         throw new CliError(given.length === 0
@@ -132,6 +136,27 @@ async function scheduleRequest(runtime, args, usage) {
         : deliveryDurationSecondsSchema.safeParse(parseDuration(timeoutInput));
     if (timeout !== undefined && !timeout.success)
         throw new CliError("--delivery-timeout is invalid", "usage", timeout.error.issues.map((issue) => issue.message).join("; "));
+    const completionInput = args.options["--completion"];
+    const completion = completionInput === undefined
+        ? undefined
+        : deliveryCompletionModeSchema.safeParse(completionInput);
+    if (completion !== undefined && !completion.success)
+        throw new CliError('--completion (delivery.completion) must be "response" or "callback"', "usage");
+    const overlapInput = args.options["--on-overlap"];
+    const overlap = overlapInput === undefined
+        ? undefined
+        : deliveryOverlapPolicySchema.safeParse(overlapInput);
+    if (overlap !== undefined && !overlap.success)
+        throw new CliError('--on-overlap (delivery.onOverlap) must be "skip" or "queue"', "usage");
+    const delivery = {
+        ...(timeout?.success ? { maxDurationSeconds: timeout.data } : {}),
+        ...(completion?.success ? { completion: completion.data } : {}),
+        ...(overlap?.success ? { onOverlap: overlap.data } : {}),
+    };
+    // Replacement validates the resulting pair after reading the stored settings.
+    // An omitted completion there can mean a retained callback, not response.
+    if (mode === "create")
+        validateDelivery(delivery);
     const external_identifier = args.options["--external-identifier"];
     if (external_identifier !== undefined &&
         !externalIdentifierSchema.safeParse(external_identifier).success)
@@ -145,9 +170,7 @@ async function scheduleRequest(runtime, args, usage) {
         ...(external_identifier === undefined ? {} : { external_identifier }),
         ...(parsedTags?.success ? { tags: parsedTags.data } : {}),
         ...(http?.success ? { http: http.data } : {}),
-        ...(timeout?.success
-            ? { delivery: { maxDurationSeconds: timeout.data } }
-            : {}),
+        ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
@@ -157,6 +180,14 @@ async function scheduleRequest(runtime, args, usage) {
         ...recurrence,
     };
 }
+/** Use the canonical contract's relation between completion and timeout. */
+function validateDelivery(delivery) {
+    const parsed = scheduleRequestSchema.safeParse({ delaySeconds: 1, delivery });
+    if (!parsed.success)
+        throw new CliError(parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "), "usage");
+}
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.
@@ -424,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),
@@ -434,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")
@@ -456,6 +518,8 @@ const schedulesList = async (runtime, args) => {
             ...request,
             ...(endpoint === undefined ? {} : { endpoint }),
             ...filters,
+            ...(order === undefined ? {} : { order }),
+            ...(direction === undefined ? {} : { direction }),
         })),
         row: (schedule) => [
             schedule.status,
@@ -466,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.
  *
@@ -518,35 +640,30 @@ async function scheduleChange(runtime, args, options) {
 const schedulesReplace = async (runtime, args) => {
     const usage = `${runtime.programName} schedules replace <schedule> (--endpoint <destination> | --url <https url>) (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
     const [id] = positionals(args, ["<schedule>"], usage);
-    const request = await scheduleRequest(runtime, args, usage);
+    const request = await scheduleRequest(runtime, args, usage, "replace");
     return scheduleChange(runtime, args, {
         act: (active, scheduleId, current) => {
             if (current === undefined)
                 throw new CliError("Replacement needs its schedule read", "internal");
-            const delivery = current.schedule.delivery;
-            const timeout = args.options["--delivery-timeout"];
-            if (timeout !== undefined &&
+            const delivery = {
+                ...current.schedule.delivery,
+                ...request["delivery"],
+            };
+            const changesDelivery = request["delivery"] !== undefined;
+            validateDelivery(delivery);
+            if (changesDelivery &&
                 current.schedule.endpoint === undefined &&
                 request["endpoint"] === undefined &&
                 request["url"] === undefined)
-                throw new CliError("--delivery-timeout needs a callback destination", "usage", "Give --endpoint or --url when attaching a callback to a timer-only schedule.");
+                throw new CliError("Delivery settings need a callback destination", "usage", "Give --endpoint or --url when attaching a callback to a timer-only schedule.");
             // The API replaces delivery settings with defaults when callback fields
             // are supplied. Carry all stored settings, including completion/overlap.
-            // Naming the retained endpoint also makes a timeout-only change reach
+            // Naming the retained endpoint also makes a delivery-only change reach
             // that callback replacement path. Fence the read against concurrent edits.
             return active.client.requestDetailed("schedules_replace", scheduleId, {
                 ...request,
-                ...(delivery === undefined
-                    ? {}
-                    : {
-                        delivery: {
-                            ...delivery,
-                            ...(timeout === undefined
-                                ? {}
-                                : { maxDurationSeconds: parseDuration(timeout) }),
-                        },
-                    }),
-                ...(timeout !== undefined &&
+                ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
+                ...(changesDelivery &&
                     request["endpoint"] === undefined &&
                     request["url"] === undefined &&
                     current.schedule.endpoint !== undefined
@@ -611,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,
@@ -713,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);
@@ -1890,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"),
@@ -2018,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/output.js

@@ -27,6 +27,9 @@ export function renderResult(command, result, json) {
             ? `${result.human}\n`
             : `${result.human}\n\n${result.nextMove}\n`;
     }
+    // The token command is a shell credential primitive with a bare JSON shape.
+    if (command === "token")
+        return `${JSON.stringify(result.data)}\n`;
     return `${JSON.stringify({
         command,
         data: result.data,

package/dist/session.d.ts

@@ -49,9 +49,20 @@ export declare function anonymousClient(runtime: CliRuntime, origin: string): De
  * reason nothing on their machine explains. Persisting first costs one write
  * and removes the whole failure.
  */
+export interface SessionCredential {
+    readonly token: string;
+    readonly expiresAt: string | null;
+    readonly credentialKind: Session["credentialKind"];
+    readonly origin: string;
+    readonly originSource: ResolvedOrigin["source"];
+}
 export declare function openSession(runtime: CliRuntime, options: {
     readonly apiUrl?: string | undefined;
 }): Promise<Session>;
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export declare function openCredential(runtime: CliRuntime, options: {
+    readonly apiUrl?: string | undefined;
+}): Promise<SessionCredential>;
 /**
  * How long before expiry a grant is refreshed rather than presented.
  *

package/dist/session.js

@@ -69,31 +69,28 @@ export function anonymousClient(runtime, origin) {
         fetch: runtime.fetch,
     });
 }
-/**
- * An authenticated session, refreshing an expired grant on the way.
- *
- * **The rotated pair is written back before the token is used.** A refresh
- * exchange invalidates the refresh token it was given, so a process that
- * refreshed, made its call, and crashed would leave a stored refresh token the
- * service no longer honours — and the person would have to sign in again for a
- * reason nothing on their machine explains. Persisting first costs one write
- * and removes the whole failure.
- */
 export async function openSession(runtime, options) {
+    const credential = await openCredential(runtime, options);
+    return {
+        client: createGreatwaitClient({
+            baseUrl: credential.origin,
+            credential: credential.token,
+            fetch: runtime.fetch,
+        }),
+        credentialKind: credential.credentialKind,
+        origin: credential.origin,
+        originSource: credential.originSource,
+    };
+}
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export async function openCredential(runtime, options) {
     const store = storeFor(runtime);
     const resolved = await resolveOrigin(runtime, store, options.apiUrl);
-    // **The environment wins, and only for an API key.** Non-interactive
-    // automation is the case this exists for, and the journey's own variable is
-    // the one it already exports. A stored OAuth grant is a person's, and a cron
-    // job that silently used one would be acting as them.
     const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
     if (fromEnvironment !== undefined && fromEnvironment !== "") {
         return {
-            client: createGreatwaitClient({
-                baseUrl: resolved.origin,
-                credential: fromEnvironment,
-                fetch: runtime.fetch,
-            }),
+            token: fromEnvironment,
+            expiresAt: null,
             credentialKind: "environment-key",
             origin: resolved.origin,
             originSource: resolved.source,
@@ -101,15 +98,11 @@ export async function openSession(runtime, options) {
     }
     const stored = await store.read(resolved.origin);
     if (stored === undefined) {
-        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in — ${runtime.programName} login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
+        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in with ${runtime.programName} login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
     }
-    const credential = await presentableSecret(runtime, store, resolved.origin, stored);
+    const secret = await presentableSecret(runtime, store, resolved.origin, stored);
     return {
-        client: createGreatwaitClient({
-            baseUrl: resolved.origin,
-            credential,
-            fetch: runtime.fetch,
-        }),
+        ...secret,
         credentialKind: stored.kind,
         origin: resolved.origin,
         originSource: resolved.source,
@@ -132,26 +125,35 @@ async function presentableSecret(runtime, store, origin, stored) {
         if (stored.secret === undefined) {
             throw new CliError(`the stored credential for ${origin} carries no secret`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin} --api-key`);
         }
-        return stored.secret;
+        return { token: stored.secret, expiresAt: null };
     }
     const { accessToken, clientId, expiresAtMs, refreshToken } = stored;
     if (accessToken === undefined || clientId === undefined) {
         throw new CliError(`the stored grant for ${origin} is incomplete`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin}`);
     }
     if (expiresAtMs === undefined ||
-        expiresAtMs - REFRESH_MARGIN_MS > runtime.now() ||
-        refreshToken === undefined) {
-        return accessToken;
+        expiresAtMs - REFRESH_MARGIN_MS > runtime.now()) {
+        return {
+            token: accessToken,
+            expiresAt: expiresAtMs === undefined ? null : new Date(expiresAtMs).toISOString(),
+        };
+    }
+    if (refreshToken === undefined) {
+        throw new CliError(`the stored grant for ${origin} needs refreshing but carries no refresh token`, "authentication", `Sign in with ${runtime.programName} login --api-url ${origin}`);
     }
     const server = await discover(runtime, origin);
     const rotated = await refresh(runtime, server, { clientId, refreshToken });
+    const refreshedExpiresAtMs = runtime.now() + rotated.expiresInSeconds * 1000;
     await store.write(origin, {
         accessToken: rotated.accessToken,
         clientId,
-        expiresAtMs: runtime.now() + rotated.expiresInSeconds * 1000,
+        expiresAtMs: refreshedExpiresAtMs,
         kind: "oauth",
         refreshToken: rotated.refreshToken,
         scope: rotated.scope,
     });
-    return rotated.accessToken;
+    return {
+        token: rotated.accessToken,
+        expiresAt: new Date(refreshedExpiresAtMs).toISOString(),
+    };
 }

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.0",
-    "@greatwait/contracts": "0.3.0"
+    "@greatwait/api-client": "0.3.2",
+    "@greatwait/contracts": "0.3.2"
   },
   "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.0"
+  "version": "0.3.2"
 }