@skrr-ai/cli 0.1.128 → 0.1.130

package/dist/lib/reflection.js

@@ -1,11 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFLECTION_PROMPT = exports.MAX_REFLECTION_CADENCE_MINUTES = exports.MIN_REFLECTION_CADENCE_MINUTES = exports.DEFAULT_REFLECTION_CADENCE_MINUTES = exports.REFLECTION_LABEL = void 0;
+exports.InvalidCadenceError = exports.REFLECTION_PROMPT = exports.MAX_REFLECTION_CADENCE_MINUTES = exports.MIN_REFLECTION_CADENCE_MINUTES = exports.DEFAULT_REFLECTION_CADENCE_MINUTES = exports.REFLECTION_LABEL = void 0;
 exports.parseCadenceToMinutes = parseCadenceToMinutes;
 exports.clampCadenceMinutes = clampCadenceMinutes;
+exports.applyCadenceBounds = applyCadenceBounds;
+exports.describeCadenceClamp = describeCadenceClamp;
 exports.describeCadenceMinutes = describeCadenceMinutes;
 exports.findReflectionTrigger = findReflectionTrigger;
 exports.reflectionCadenceMinutes = reflectionCadenceMinutes;
+exports.reflectionNextRunLabel = reflectionNextRunLabel;
+exports.reflectionAutonomy = reflectionAutonomy;
+exports.reflectionAutonomyNote = reflectionAutonomyNote;
+exports.reflectionAutonomyFields = reflectionAutonomyFields;
 exports.buildReflectionTriggerPayload = buildReflectionTriggerPayload;
 /**
  * reflection.ts — the agent self-reflection ("meta cadence") loop.
@@ -52,9 +58,42 @@ exports.REFLECTION_PROMPT = `[Self-reflection] Step back and review your own sch
 4. Fix what is slipping: reschedule, create, or cancel triggers and tasks so your plan matches reality.
 
 Be deliberate and minimal. Every trigger you keep spends the user's compute — keep only what earns its place. If nothing needs changing, do nothing and end the turn.`;
+/**
+ * A cadence the caller got wrong: unparseable, empty, or not a positive number of
+ * minutes. Mirrors `InvalidCadenceError` in the server copy, minus its 4xx `status`:
+ * that field is how an MCP server tells the caller's mistake from its own failure,
+ * and on the CLI the same field would make `handleApiError` read this as an HTTP
+ * response. Commands catch it and report it as a usage error.
+ */
+class InvalidCadenceError extends Error {
+    code = 'INVALID_CADENCE';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCadenceError';
+    }
+}
+exports.InvalidCadenceError = InvalidCadenceError;
+/**
+ * A cadence must be a positive, finite number of minutes. `0` is not "off" and not "the
+ * minimum": rounding it up to the floor turned an attempt to switch the loop off into one
+ * that wakes the agent 96 times a day (OSK-21493).
+ */
+function requirePositiveMinutes(minutes, raw) {
+    if (!Number.isFinite(minutes)) {
+        throw new InvalidCadenceError(`That cadence is too large to be a number of minutes. Pick between ${describeCadenceMinutes(exports.MIN_REFLECTION_CADENCE_MINUTES)} and ${describeCadenceMinutes(exports.MAX_REFLECTION_CADENCE_MINUTES)}.`);
+    }
+    if (minutes <= 0) {
+        const shown = raw.length > 24 ? `${raw.slice(0, 24)}…` : raw;
+        throw new InvalidCadenceError(`"${shown}" is not a cadence — it cannot mean "off". To pause the loop, disable it instead ` +
+            '(skrr agents reflect <agent> --disable, or the self_reflection_disable tool); otherwise ' +
+            `pick between ${describeCadenceMinutes(exports.MIN_REFLECTION_CADENCE_MINUTES)} and ${describeCadenceMinutes(exports.MAX_REFLECTION_CADENCE_MINUTES)}.`);
+    }
+    return minutes;
+}
 /**
  * Parse a human cadence into minutes. Accepts `6h`, `90m`, `2h30m`, `1d`, or a
- * bare number (interpreted as minutes). Throws on unparseable input.
+ * bare number (interpreted as minutes). Throws `InvalidCadenceError` on
+ * unparseable input.
  */
 // Longest-first alternation, and CADENCE_FULL is anchored so the WHOLE string
 // must be consumed. Without the anchor, "1 month" matches `1` + `m` and silently
@@ -67,14 +106,14 @@ function parseCadenceToMinutes(input) {
         .trim()
         .toLowerCase();
     if (!raw) {
-        throw new Error('Empty cadence. Use a form like "6h", "90m", "2h30m", or "360".');
+        throw new InvalidCadenceError('Empty cadence. Use a form like "6h", "90m", "2h30m", or "360".');
     }
     // Bare number → minutes.
     if (/^\d+(\.\d+)?$/.test(raw)) {
-        return Math.round(Number(raw));
+        return requirePositiveMinutes(Math.round(Number(raw)), raw);
     }
     if (!CADENCE_FULL.test(raw)) {
-        throw new Error(`Could not parse cadence "${input}". Use minutes/hours/days — e.g. "6h", "90m", "2h30m", "360". ` +
+        throw new InvalidCadenceError(`Could not parse cadence "${input}". Use minutes/hours/days — e.g. "6h", "90m", "2h30m", "360". ` +
             '(Months and seconds are not units here.)');
     }
     let total = 0;
@@ -90,12 +129,39 @@ function parseCadenceToMinutes(input) {
         else
             total += n;
     }
-    return Math.round(total);
+    return requirePositiveMinutes(Math.round(total), raw);
 }
 /** Clamp a cadence to the allowed reflection window. */
 function clampCadenceMinutes(minutes) {
     return Math.max(exports.MIN_REFLECTION_CADENCE_MINUTES, Math.min(exports.MAX_REFLECTION_CADENCE_MINUTES, Math.round(minutes)));
 }
+/**
+ * Apply the reflection window to a requested cadence and SAY what happened, so every
+ * caller can report "asked 5m, applied 15m" instead of only the clamped number
+ * (OSK-21486, OSK-21493, OSK-21602). `bound` names the limit that moved it.
+ */
+function applyCadenceBounds(requestedMinutes) {
+    const requested = Math.round(requestedMinutes);
+    const minutes = clampCadenceMinutes(requested);
+    let bound = null;
+    if (minutes > requested)
+        bound = 'minimum';
+    else if (minutes < requested)
+        bound = 'maximum';
+    return { minutes, requestedMinutes: requested, clamped: bound !== null, bound };
+}
+/**
+ * One sentence for a clamp ("5m is below the 15m minimum; applied 15m."), or null when
+ * the request was inside the window. Shared by the MCP result `note` and the CLI line.
+ */
+function describeCadenceClamp({ minutes, requestedMinutes, bound, }) {
+    if (!bound)
+        return null;
+    const limit = bound === 'minimum' ? exports.MIN_REFLECTION_CADENCE_MINUTES : exports.MAX_REFLECTION_CADENCE_MINUTES;
+    const side = bound === 'minimum' ? 'below' : 'above';
+    return (`${describeCadenceMinutes(requestedMinutes)} is ${side} the ${describeCadenceMinutes(limit)} ` +
+        `${bound}; applied ${describeCadenceMinutes(minutes)}.`);
+}
 /** Render minutes back as a compact human cadence ("6h", "90m", "1d"). */
 function describeCadenceMinutes(minutes) {
     if (minutes > 0 && minutes % (60 * 24) === 0)
@@ -113,6 +179,49 @@ function reflectionCadenceMinutes(trigger) {
     const ms = trigger.schedule?.intervalMs;
     return typeof ms === 'number' && Number.isFinite(ms) ? Math.round(ms / 60_000) : undefined;
 }
+/**
+ * The loop's next run, for display: its scheduled time while it is enabled, else `-`. A
+ * paused loop has no next run, and a loop with nothing scheduled does not have its LAST fire
+ * promoted to one (the server copy keeps `nextRunAt` and `lastFiredAt` apart the same way).
+ */
+function reflectionNextRunLabel(trigger) {
+    return (0, triggers_1.scheduledRunAt)(trigger) ?? '-';
+}
+/**
+ * Whether the loop's fires run, as the SERVER says it (`GET /api/triggers?include=autonomy`), or
+ * null when it did not say. Nothing is derived here: the verdict depends on the agent's
+ * initiative mode and on which door created the loop, and a local copy of that judgement is free
+ * to disagree with the fire path (OSK-21606). A server that predates the field, or one that could
+ * not reach a verdict, sends nothing, and that is UNKNOWN, never `runs`.
+ */
+function reflectionAutonomy(trigger) {
+    if (trigger.enabled === false)
+        return null;
+    const { autonomy, autonomyNote } = trigger;
+    if (autonomy !== 'runs' && autonomy !== 'suggests_only')
+        return null;
+    const note = typeof autonomyNote === 'string' && autonomyNote.trim() ? autonomyNote.trim() : '';
+    return { autonomy, ...(note ? { note } : {}) };
+}
+/**
+ * The one plain sentence a text view prints under the loop when its fires will not run for the
+ * owner; null when they do, when the server did not say, or when the loop is paused (a paused
+ * loop fires nothing, so the gate is not what the reader needs to hear about).
+ */
+function reflectionAutonomyNote(trigger, bin) {
+    const verdict = reflectionAutonomy(trigger);
+    if (!verdict || verdict.autonomy !== 'suggests_only')
+        return null;
+    return (verdict.note ??
+        `This loop's fires only create an inbox suggestion. Run ${bin} triggers preflight ${trigger.id ?? '<trigger-id>'} to see why.`);
+}
+/** The `--json` fields for the same verdict: absent when unknown, so absence reads as unknown. */
+function reflectionAutonomyFields(trigger) {
+    const verdict = reflectionAutonomy(trigger);
+    if (!verdict)
+        return {};
+    return { autonomy: verdict.autonomy, ...(verdict.note ? { note: verdict.note } : {}) };
+}
 /**
  * Build the `POST /api/triggers` body for a fresh self-reflection loop. Uses the
  * proven `scope:agent + kind:schedule + mode:run_only` shape and coalesces so a

package/dist/lib/store-artifact-releases.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `/api/store/artifacts/skill/:entityId/releases` — the seller's own
+ * publication history for one skill, newest release first.
+ *
+ * It answers the question a headless seller has after `store artifacts release`:
+ * where did my releases land, and did a curator admit or refuse one (with the
+ * note they left)? The source snapshot and its private storage references are
+ * never in this projection. One release in full is `store artifacts receipt`.
+ *
+ * The route is written out at its own call site rather than composed from a
+ * builder, like the rest of the Store CLI: the parity checker reads the LITERAL
+ * at the call site.
+ */
+export type StoreArtifactReleaseSummary = {
+    releaseId: string;
+    releaseNumber: number;
+    versionLabel?: string;
+    status?: string;
+    admission?: {
+        state?: string;
+        review?: {
+            note?: string;
+            decidedAt?: string;
+        };
+    };
+    createdAt?: string;
+    updatedAt?: string;
+    publishedAt?: string;
+};
+export type StoreArtifactReleaseHistory = {
+    data: StoreArtifactReleaseSummary[];
+    /** Pass as `before` for the next (older) page; null when this is the last. */
+    nextBefore: number | null;
+};
+/** `GET /artifacts/skill/:entityId/releases` — `limit` 1-50 (default 10), `before` a release number. */
+export declare function listSkillArtifactReleases(entityId: string, params?: {
+    limit?: number;
+    before?: number;
+}): Promise<StoreArtifactReleaseHistory>;

package/dist/lib/store-artifact-releases.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSkillArtifactReleases = listSkillArtifactReleases;
+const api_fetch_1 = require("./api-fetch");
+const triggers_1 = require("./triggers");
+/** `GET /artifacts/skill/:entityId/releases` — `limit` 1-50 (default 10), `before` a release number. */
+async function listSkillArtifactReleases(entityId, params = {}) {
+    return (0, api_fetch_1.apiFetch)((0, triggers_1.withQuery)(`/api/store/artifacts/skill/${encodeURIComponent(entityId)}/releases`, {
+        limit: params.limit,
+        before: params.before,
+    }));
+}

package/dist/lib/store-library.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `/api/store/library/items` — the Skill, Action and Service copies the signed-in
+ * buyer holds in the active workspace, with whether each copy can still be used.
+ *
+ * Agent purchases are NOT here: `skrr store installs` reads those. This is the
+ * other three artifact kinds, which the web Library page lists and which had no
+ * headless read at all.
+ *
+ * The route is written out at its own call site rather than composed from a
+ * builder, like the rest of the Store CLI: the parity checker reads the LITERAL
+ * at the call site.
+ */
+/** One bought copy. `copyAvailable` is false once the copy is suspended, revoked or uninstalled. */
+export type StoreLibraryItem = {
+    /** The listing or release the buyer bought. */
+    sourceId: string;
+    /** The buyer's own installed copy; null while fulfillment has not produced one. */
+    copyId: string | null;
+    name: string | null;
+    copyAvailable: boolean;
+    /** The Agent the copy was installed onto (Skills and Actions only). */
+    targetAgentId?: string | null;
+    entitlementState?: string;
+    fulfillmentState?: string;
+    purchasedAt?: string;
+};
+export type StoreLibraryItems = {
+    skills: StoreLibraryItem[];
+    actions: StoreLibraryItem[];
+    services: StoreLibraryItem[];
+};
+/**
+ * `GET /library/items`. The workspace is required by the server (400
+ * `A workspace is required` without one), so it travels as the explicit
+ * header, the way `store installs` sends it.
+ */
+export declare function getStoreLibraryItems(workspaceId?: string): Promise<StoreLibraryItems>;

package/dist/lib/store-library.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStoreLibraryItems = getStoreLibraryItems;
+const api_fetch_1 = require("./api-fetch");
+/**
+ * `GET /library/items`. The workspace is required by the server (400
+ * `A workspace is required` without one), so it travels as the explicit
+ * header, the way `store installs` sends it.
+ */
+async function getStoreLibraryItems(workspaceId) {
+    return (0, api_fetch_1.apiFetch)('/api/store/library/items', workspaceId ? { headers: { 'X-Workspace-Id': workspaceId } } : undefined);
+}

package/dist/lib/task-calendar.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What `skrr tasks list --calendar` tells a person about the answer it printed.
+ *
+ * The calendar read used to end with "Note: calendar occurrence expansion reached its safety cap."
+ * whatever had been cut, and "No calendar occurrences." whatever had been missed (OSK-21382,
+ * OSK-21510): no limit, no cutoff, no Task, no remedy, and the server's warning codes were never
+ * shown. The server now says which bounds it reached (`truncations`) and which access warnings
+ * apply; this words them.
+ */
+import type { TaskCalendarResponse, TaskCalendarTruncation } from '@skrr-ai/data-provider';
+export declare function describeCalendarTruncation(truncation: TaskCalendarTruncation): string;
+export declare function describeCalendarWarning(code: string): string;
+/**
+ * The lines to print after a calendar answer: empty when the read was complete. A calendar that
+ * was cut short never reads as complete, and every cut says what it was.
+ */
+export declare function calendarNoticeLines(calendar: TaskCalendarResponse): string[];
+/** The window that was actually read, in UTC, and what a date-only range stood for. */
+export declare function calendarWindowLine(calendar: Pick<TaskCalendarResponse, 'from' | 'to'>): string;

package/dist/lib/task-calendar.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeCalendarTruncation = describeCalendarTruncation;
+exports.describeCalendarWarning = describeCalendarWarning;
+exports.calendarNoticeLines = calendarNoticeLines;
+exports.calendarWindowLine = calendarWindowLine;
+const who = (t) => t.ref || t.taskId || 'A task';
+/**
+ * One sentence per bound. A `Record` over the shared vocabulary, so a code added to
+ * `TASK_CALENDAR_TRUNCATION_CODES` cannot be forgotten here.
+ */
+const TRUNCATION_TEXT = {
+    task_occurrence_limit: (t) => `${who(t)} fires more than ${t.limit} times in this window (the limit is ${t.limit} per task)` +
+        `${t.cutoffAt ? `; its fires are listed up to ${t.cutoffAt} and later ones are not shown` : ''}. ` +
+        'Narrow the range to see the rest.',
+    task_skipped_receipt_limit: (t) => `${who(t)} has more than ${t.limit} skipped-fire receipts in this window; only the latest ${t.limit} are shown.`,
+    task_recurrence_walk_limit: (t) => `${who(t)} has a run limit too far from this window to count what remains of it (more than ${t.limit} fires walked), so its fires in this window are not shown. ` +
+        'Narrow the range to start closer to its next run.',
+    calendar_row_limit: (t) => `More than ${t.limit} rows matched${typeof t.omitted === 'number' ? `; ${t.omitted} are not shown` : ''}` +
+        `${t.cutoffAt ? `, and the rows are listed only up to ${t.cutoffAt}` : ''}. ` +
+        'Narrow the range, or add --space or --project.',
+    task_candidate_limit: (t) => `More than ${t.limit} tasks are candidates for this window and not all were read. Narrow the range, or add --space or --project.`,
+};
+function describeCalendarTruncation(truncation) {
+    const words = TRUNCATION_TEXT[truncation.code];
+    // A code a newer server sent: say it rather than drop it.
+    return words
+        ? words(truncation)
+        : `The server reached a limit (${String(truncation.code)}, ${truncation.limit}) and did not describe it.`;
+}
+const WARNING_TEXT = {
+    space_cascade_capped: 'You can reach more spaces than one read covers, so tasks you did not create in the rest are not listed. Narrow with --space.',
+    space_access_capped: 'You can reach more spaces than one read covers, so tasks in the rest are not listed. Narrow with --space.',
+};
+function describeCalendarWarning(code) {
+    if (WARNING_TEXT[code])
+        return WARNING_TEXT[code];
+    if (code.endsWith('_partial')) {
+        return 'An access lookup failed, so some tasks may be missing. Retry the command.';
+    }
+    return `The server flagged this answer (${code}); it may be incomplete.`;
+}
+/**
+ * The lines to print after a calendar answer: empty when the read was complete. A calendar that
+ * was cut short never reads as complete, and every cut says what it was.
+ */
+function calendarNoticeLines(calendar) {
+    const truncations = calendar.truncations ?? [];
+    const warnings = calendar.warnings ?? [];
+    const lines = [];
+    if (truncations.length > 0) {
+        lines.push('The calendar is incomplete:');
+        for (const truncation of truncations)
+            lines.push(`  - ${describeCalendarTruncation(truncation)}`);
+    }
+    else if (calendar.truncated && warnings.length === 0) {
+        // A server that predates `truncations` flagged the answer and said nothing more.
+        lines.push('The calendar is incomplete: the server cut it short but did not say which limit it reached. Narrow the range, or add --space.');
+    }
+    if (warnings.length > 0) {
+        if (lines.length === 0)
+            lines.push('The calendar may be incomplete:');
+        for (const code of warnings) {
+            lines.push(`  - Warning ${code}: ${describeCalendarWarning(code)}`);
+        }
+    }
+    return lines;
+}
+/** The window that was actually read, in UTC, and what a date-only range stood for. */
+function calendarWindowLine(calendar) {
+    return `Window (UTC): ${calendar.from} .. ${calendar.to}. A date-only range is a whole UTC day.`;
+}

package/dist/lib/task-operations.js

@@ -28,6 +28,8 @@ function taskActionCommand(action, taskId, targetId, bin = 'skrr', context = {})
         request_approval: `tasks approvals create ${task} --type <review|sign_off|deployment>`,
         resolve_approval: `tasks approvals resolve ${task} ${target} --status <approved|rejected>`,
         resolve_task_hold: `tasks move ${task} --status <status>`,
+        resume_schedule: `tasks resume-schedule ${task}`,
+        retry_schedule: `tasks retry-schedule ${task} --at <time>`,
         retry_task: `tasks retry ${task}`,
         set_execution_mode: `tasks update ${task} --execution-mode <agent|human>`,
         start_task: `tasks start ${task}`,

package/dist/lib/task-recurrence-outcome.js

@@ -22,7 +22,9 @@ function recurrenceRearmHint(code, taskRef = '<task-id>', bin = 'skrr') {
 }
 const ENDED_BECAUSE = {
     max_runs: 'it reached its maximum number of runs',
-    end_date: 'its end date has passed',
+    // The end date is exclusive: it ends the series when it has passed AND when the next slot would
+    // land on or after it, so "has passed" would be false for a series ended one day early (OSK-21552).
+    end_date: 'its end date leaves no further occurrence',
     no_next_occurrence: 'its pattern has no further occurrence',
 };
 /** One line, or null when the Task does not recur (or an older server did not say). */

package/dist/lib/task-recurrence-summary.d.ts

@@ -0,0 +1,15 @@
+export type CronReading = {
+    /** "at 09:00 on the 13th of the month or on Friday" */
+    text: string;
+    /** True when both a day of month and a weekday are set: cron fires on EITHER. */
+    dayOfMonthOrWeekday: boolean;
+};
+/**
+ * Plain language for a five-field cron pattern, or `null` when this reader cannot say it faithfully.
+ */
+export declare function describeCronPattern(pattern: string): CronReading | null;
+/**
+ * The block `tasks show` prints for a recurring Task: the rule, its zone, a plain reading, when it
+ * next fires, how many runs it has used, and when it ends. Empty for a Task that does not recur.
+ */
+export declare function recurrenceSummaryLines(task: Record<string, unknown>): string[];

package/dist/lib/task-recurrence-summary.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeCronPattern = describeCronPattern;
+exports.recurrenceSummaryLines = recurrenceSummaryLines;
+/**
+ * What `skrr tasks show` says about a Task that recurs (OSK-21531).
+ *
+ * The human view printed "it is scheduled for 2026-12-01" and nothing else: no word that the Task
+ * recurs, no pattern, no zone. The rule lived only in `--json` (`recurrence.pattern`, `.timezone`,
+ * `.runsCompleted`), so the cron semantics that surprise people - a day of month AND a weekday
+ * fire on EITHER, not both - were invisible exactly where someone checks what they just set up.
+ *
+ * `describeCronPattern` reads the five-field form the scheduler runs. It is deliberately modest: a
+ * pattern it cannot read plainly (names it does not know, `L`, `?`, six fields) returns `null` and
+ * the caller prints the raw pattern alone rather than a confident wrong sentence.
+ */
+const iso_instant_1 = require("./iso-instant");
+const WEEKDAYS = [
+    'Sunday',
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday',
+];
+const MONTHS = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const MINUTE = { min: 0, max: 59 };
+const HOUR = { min: 0, max: 23 };
+const DAY_OF_MONTH = { min: 1, max: 31 };
+const MONTH = {
+    min: 1,
+    max: 12,
+    names: MONTHS.map((m) => m.slice(0, 3).toUpperCase()),
+    nameBase: 1,
+};
+const DAY_OF_WEEK = {
+    min: 0,
+    max: 7,
+    names: WEEKDAYS.map((d) => d.slice(0, 3).toUpperCase()),
+    nameBase: 0,
+};
+/** The values a field names, or `null` when it is not a form this reader understands. */
+function expandField(raw, domain) {
+    const values = new Set();
+    for (const part of raw.split(',')) {
+        const [rangeText, stepText, extra] = part.split('/');
+        if (extra !== undefined || rangeText === undefined || rangeText === '')
+            return null;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            return null;
+        const toNumber = (token) => {
+            if (/^\d+$/.test(token))
+                return Number(token);
+            const index = domain.names?.indexOf(token.toUpperCase()) ?? -1;
+            return index >= 0 ? index + (domain.nameBase ?? 0) : null;
+        };
+        let from;
+        let to;
+        if (rangeText === '*') {
+            from = domain.min;
+            to = domain === DAY_OF_WEEK ? 6 : domain.max;
+        }
+        else if (rangeText.includes('-')) {
+            const [a, b, more] = rangeText.split('-');
+            if (more !== undefined)
+                return null;
+            from = toNumber(a);
+            to = toNumber(b);
+        }
+        else {
+            from = toNumber(rangeText);
+            // `5/10` runs from 5 to the top of the field.
+            to = stepText === undefined ? from : domain === DAY_OF_WEEK ? 6 : domain.max;
+        }
+        if (from === null || to === null || from > to)
+            return null;
+        if (from < domain.min || to > domain.max)
+            return null;
+        for (let value = from; value <= to; value += step)
+            values.add(domain === DAY_OF_WEEK && value === 7 ? 0 : value);
+    }
+    return [...values].sort((a, b) => a - b);
+}
+function ordinal(n) {
+    const tail = n % 100;
+    if (tail >= 11 && tail <= 13)
+        return `${n}th`;
+    return `${n}${{ 1: 'st', 2: 'nd', 3: 'rd' }[n % 10] ?? 'th'}`;
+}
+function joinList(items, word = 'and') {
+    if (items.length <= 1)
+        return items.join('');
+    return `${items.slice(0, -1).join(', ')} ${word} ${items[items.length - 1]}`;
+}
+const pad = (n) => String(n).padStart(2, '0');
+/** Evenly spaced from the field's start, e.g. 0,15,30,45 -> 15. */
+function evenStep(values, size) {
+    if (values.length < 2 || values[0] !== 0)
+        return null;
+    const step = values[1] - values[0];
+    if (step < 2 || size % step !== 0 || values.length !== size / step)
+        return null;
+    return values.every((v, i) => v === i * step) ? step : null;
+}
+function describeTime(minute, hour) {
+    const minutes = expandField(minute, MINUTE);
+    const hours = expandField(hour, HOUR);
+    if (!minutes || !hours)
+        return null;
+    const everyHour = hours.length === 24;
+    if (everyHour && minutes.length === 60)
+        return 'every minute';
+    if (everyHour) {
+        const step = evenStep(minutes, 60);
+        if (step)
+            return `every ${step} minutes`;
+        if (minutes.length === 1)
+            return minutes[0] === 0
+                ? 'at the start of every hour'
+                : `at minute ${minutes[0]} of every hour`;
+        return `at minutes ${joinList(minutes.map(String))} of every hour`;
+    }
+    if (minutes.length === 1 && hours.length <= 6) {
+        return `at ${joinList(hours.map((h) => `${pad(h)}:${pad(minutes[0])}`))}`;
+    }
+    const hourStep = evenStep(hours, 24);
+    if (minutes.length === 1 && hourStep) {
+        return `every ${hourStep} hours, at minute ${minutes[0]}`;
+    }
+    return `at minute${minutes.length > 1 ? 's' : ''} ${joinList(minutes.map(String))} past hour${hours.length > 1 ? 's' : ''} ${joinList(hours.map(String))}`;
+}
+function describeWeekdays(values) {
+    const key = values.join(',');
+    if (key === '1,2,3,4,5')
+        return 'Monday to Friday';
+    if (key === '0,6')
+        return 'Saturday and Sunday';
+    return joinList(values.map((d) => WEEKDAYS[d]));
+}
+/**
+ * Plain language for a five-field cron pattern, or `null` when this reader cannot say it faithfully.
+ */
+function describeCronPattern(pattern) {
+    const fields = String(pattern ?? '')
+        .trim()
+        .split(/\s+/);
+    if (fields.length !== 5)
+        return null;
+    const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+    const time = describeTime(minute, hour);
+    const months = month === '*' ? [] : expandField(month, MONTH);
+    const monthDays = dayOfMonth === '*' ? [] : expandField(dayOfMonth, DAY_OF_MONTH);
+    const weekdays = dayOfWeek === '*' ? [] : expandField(dayOfWeek, DAY_OF_WEEK);
+    if (!time || !months || !monthDays || !weekdays)
+        return null;
+    const dayParts = [];
+    if (monthDays.length > 0) {
+        dayParts.push(`on the ${joinList(monthDays.map(ordinal))} of the month`);
+    }
+    if (weekdays.length > 0) {
+        dayParts.push(`on ${describeWeekdays(weekdays)}`);
+    }
+    const dayText = dayParts.length === 0 ? 'every day' : dayParts.join(' OR ');
+    const monthText = months.length > 0 ? ` in ${joinList(months.map((m) => MONTHS[m - 1]))}` : '';
+    return {
+        text: `${time}, ${dayText}${monthText}`,
+        dayOfMonthOrWeekday: monthDays.length > 0 && weekdays.length > 0,
+    };
+}
+function instantText(value) {
+    if (typeof value !== 'string' && !(value instanceof Date))
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime())
+        ? typeof value === 'string'
+            ? value
+            : null
+        : (0, iso_instant_1.formatUtcInstant)(date);
+}
+/**
+ * The block `tasks show` prints for a recurring Task: the rule, its zone, a plain reading, when it
+ * next fires, how many runs it has used, and when it ends. Empty for a Task that does not recur.
+ */
+function recurrenceSummaryLines(task) {
+    const recurrence = task.recurrence;
+    const pattern = typeof recurrence?.pattern === 'string' ? recurrence.pattern.trim() : '';
+    if (!recurrence || !pattern)
+        return [];
+    const zone = typeof recurrence.timezone === 'string' && recurrence.timezone.trim()
+        ? recurrence.timezone.trim()
+        : 'UTC';
+    const reading = describeCronPattern(pattern);
+    const lines = [`Recurs:      ${pattern} (${zone})${reading ? ` - ${reading.text}` : ''}`];
+    const facts = [];
+    if (recurrence.paused === true)
+        facts.push('paused');
+    const next = instantText(recurrence.nextRunAt ?? task.scheduledFor);
+    if (next)
+        facts.push(`next ${next}`);
+    const used = Number.isFinite(Number(recurrence.runsCompleted))
+        ? Number(recurrence.runsCompleted)
+        : 0;
+    const cap = Number(recurrence.maxRuns);
+    facts.push(Number.isInteger(cap) && cap > 0 ? `${used} of ${cap} runs` : `${used} runs so far, no cap`);
+    const ends = instantText(recurrence.endDate);
+    if (ends)
+        facts.push(`ends ${ends}`);
+    lines.push(`             ${facts.join(', ')}`);
+    if (reading?.dayOfMonthOrWeekday) {
+        lines.push('             Cron note: with both a day of the month and a weekday, it fires when EITHER matches, not only when both do.');
+    }
+    return lines;
+}

package/dist/lib/task-reminder.d.ts

@@ -0,0 +1,28 @@
+export type ReminderOutcome = {
+    /** The Task already had a live reminder with these words, and that row was returned. */
+    reused?: boolean;
+    /** ...and it was moved to the requested time. */
+    moved?: boolean;
+    /** Where it was before it moved. */
+    previousRunAt?: string;
+};
+export type ReminderTrigger = {
+    id?: string;
+    once?: {
+        runAt?: string;
+    };
+    reminderOutcome?: ReminderOutcome;
+};
+/**
+ * The lines to print after a successful `POST /api/triggers`.
+ *
+ * `requested` is the instant the user asked for; the stored `once.runAt` wins when the
+ * server returned one, because that is the time that will fire.
+ */
+export declare function reminderReceiptLines(input: {
+    title: string;
+    trigger: ReminderTrigger | null | undefined;
+    requested: Date;
+    bin?: string;
+    timeZone?: string;
+}): string[];