@ours.network/fleet 1.2.0-nightly.65 → 1.2.0-nightly.66

package/dist/docs.js

@@ -877,6 +877,56 @@ selection.
 Inspect \`ours-fleet status Name\`, \`peek Name\`, role logs, and
 \`~/.ours-fleet/agents/Name/.monitor-status\` when diagnosing delivery.
 
+## Self-reminders
+
+Every managed agent (\`session: acp\` or \`codex-app-server\`, Claude or Codex,
+persistent, temporary or task-owned) can schedule one-time wakes for ITSELF.
+The tools are on the agent's own fixed-identity ours MCP server, so there is no
+agent, identity or recipient argument and no setup, worker, service, chat or key:
+
+- \`fleet_reminder_create\` — \`request_key\` (stable per decision; a repeat with
+  the same input returns the same reminder, different input is refused),
+  \`title\`, optional \`note\`, \`local_time\` (date and time WITHOUT an offset, e.g.
+  \`2027-01-20T16:00\`), \`time_zone\` (IANA, e.g. \`Europe/London\`, \`UTC\`), optional
+  \`fold\` (0/1, required only for a time that occurs twice when clocks go back;
+  times skipped by a spring-forward gap are refused) and \`late_window_seconds\`
+  (60..604800, default 3600).
+- \`fleet_reminder_list\` — \`state\` \`open\` (default) | \`closed\` | \`all\`, \`limit\`, \`after\`.
+- \`fleet_reminder_update\` / \`fleet_reminder_cancel\` — \`id\` + \`expected_revision\`;
+  every change bumps the revision and voids any wake issued for the old one.
+- \`fleet_reminder_inspect\` — \`event_id\` from a wake: the note and whether the
+  wake is still current and eligible.
+- \`fleet_reminder_ack\` — \`event_id\` + \`expected_revision\`: records that the
+  wake was handled. Idempotent; sends nothing and claims no external action.
+
+When a reminder is due the supervisor starts one turn beginning \`[fleet-reminder]\`
+with the event id. It is the agent's own stored reminder, not an owner
+instruction or ours mail, and grants no authority. Fleet never sends anything
+on the agent's behalf; whether to message anyone is the agent's own decision
+under its existing tools and authorization.
+
+Delivery: the supervisor process that runs the agent owns the timer — an idle
+agent with no open reminders costs nothing, and only a due reminder creates a
+model turn. A wake never interrupts or queues behind work: it is admitted at the
+next idle turn boundary after its due time and after the agent's startup turn.
+If the host, Fleet or the agent is down, paused or busy, a reminder is still
+delivered when it comes back within its late window, and otherwise expires
+without a turn. Reminders survive supervisor, Fleet and host restarts and
+ordinary stop/start. They do not survive the agent: removing or retiring an
+agent or its task cancels them and deletes their state, and a replaced identity
+or same-named successor never inherits them.
+
+Guarantees are at most once per reminder revision. Queue acceptance, release to
+the model, the agent's ack, and any external action are distinct facts. A wake
+is marked dispatched durably at the moment it is handed to the model; if the
+supervisor stops before that, the same event is retried. If it stops after, the
+event is held \`uncertain\` (shown by \`list\`/\`inspect\`, never re-sent): check your
+own records, then ack it or schedule something new.
+
+Operators can read an agent's reminders with
+\`ours-fleet ours call Name fleet_reminder_list\`. Full guide, examples and the
+migration from the standalone \`self-reminders\` worker skill: \`docs/self-reminders.md\`.
+
 ## Trusted owner channel
 
 Any managed role may declare a separate ours identity which fleet — never the agent —

package/dist/reminders/manager.d.ts

@@ -0,0 +1,68 @@
+import type { ReminderAttempt } from '../session/arbiter.js';
+import type { PromptOrigin } from '../session/types.js';
+import type { ReminderEvent, ReminderRecord, ReminderStore } from './store.js';
+/** The admission seam: the role's RoleTurnArbiter in production. */
+export interface ReminderAdmitter {
+    tryReminder(text: string, origin: Extract<PromptOrigin, {
+        kind: 'self-reminder';
+    }>, beforeQueue: () => boolean, releaseGuard: () => boolean): Promise<ReminderAttempt>;
+}
+export interface ReminderManagerDeps {
+    now(): number;
+    setTimer(callback: () => void, ms: number): unknown;
+    clearTimer(timer: unknown): void;
+    log(line: string): void;
+}
+/**
+ * The dispatcher never sleeps longer than this while reminders are open, so a
+ * wall-clock jump (host suspend, NTP step) is noticed within a minute. With
+ * nothing open it arms no timer at all: an idle agent costs nothing.
+ */
+export declare const REMINDER_POLL_CEILING_MS = 60000;
+export interface ReminderManagerHandle {
+    start(): void;
+    stop(): void;
+    /** Called after an agent tool changed the schedule so the timer reflects it. */
+    changed(): void;
+}
+/**
+ * Turns due self-reminders into wakes for the agent that owns them.
+ *
+ * Runs inside that agent's runner, beside the role's turn arbiter. It starts
+ * only after the role's startup turn has succeeded and stops before the runner
+ * releases its runtime binding. Admission is idle-only: a wake never
+ * interrupts or queues behind work, and the session's release guard makes the
+ * durable `dispatched` claim at the moment the prompt reaches the model.
+ */
+export declare class ReminderManager implements ReminderManagerHandle {
+    private readonly role;
+    private readonly store;
+    private readonly admitter;
+    private readonly deps;
+    private timer?;
+    private started;
+    private stopping;
+    private polling;
+    private busyStreak;
+    /** Consecutive re-arms with work already overdue; drives the spin backoff. */
+    private overdueStreak;
+    private readonly inFlight;
+    constructor(role: string, store: ReminderStore, admitter: ReminderAdmitter, deps: ReminderManagerDeps);
+    start(): void;
+    /** Synchronous: after this returns no timer is armed and every release guard refuses. */
+    stop(): void;
+    get isStopping(): boolean;
+    changed(): void;
+    /** Public fake-clock seam; the timer calls the same transition. */
+    poll(): Promise<void>;
+    private admit;
+    private guard;
+    private retryAt;
+    private schedule;
+}
+/**
+ * The wake text. It carries the agent's own title so the wake is legible, but
+ * the note is only returned by `fleet_reminder_inspect`, which also re-checks
+ * eligibility at the moment the agent acts.
+ */
+export declare function wakePrompt(event: ReminderEvent, reminder: ReminderRecord, now: number, retry: boolean): string;

package/dist/reminders/manager.js

@@ -0,0 +1,212 @@
+/**
+ * The dispatcher never sleeps longer than this while reminders are open, so a
+ * wall-clock jump (host suspend, NTP step) is noticed within a minute. With
+ * nothing open it arms no timer at all: an idle agent costs nothing.
+ */
+export const REMINDER_POLL_CEILING_MS = 60_000;
+/** Busy role: re-check at the next idle boundary within these bounds. */
+const BUSY_RETRY_MIN_MS = 2_000;
+const BUSY_RETRY_MAX_MS = 30_000;
+/** Admission refused before reaching the model: bounded backoff, inside the late window. */
+const UNAVAILABLE_RETRY_MS = [5_000, 15_000, 30_000, 60_000];
+/**
+ * Turns due self-reminders into wakes for the agent that owns them.
+ *
+ * Runs inside that agent's runner, beside the role's turn arbiter. It starts
+ * only after the role's startup turn has succeeded and stops before the runner
+ * releases its runtime binding. Admission is idle-only: a wake never
+ * interrupts or queues behind work, and the session's release guard makes the
+ * durable `dispatched` claim at the moment the prompt reaches the model.
+ */
+export class ReminderManager {
+    role;
+    store;
+    admitter;
+    deps;
+    timer;
+    started = false;
+    stopping = false;
+    polling = false;
+    busyStreak = 0;
+    /** Consecutive re-arms with work already overdue; drives the spin backoff. */
+    overdueStreak = 0;
+    inFlight = new Set();
+    constructor(role, store, admitter, deps) {
+        this.role = role;
+        this.store = store;
+        this.admitter = admitter;
+        this.deps = deps;
+    }
+    start() {
+        if (this.started || this.stopping)
+            return;
+        this.started = true;
+        this.schedule(0);
+    }
+    /** Synchronous: after this returns no timer is armed and every release guard refuses. */
+    stop() {
+        this.stopping = true;
+        if (this.timer !== undefined)
+            this.deps.clearTimer(this.timer);
+        this.timer = undefined;
+    }
+    get isStopping() { return this.stopping; }
+    changed() {
+        if (this.started && !this.stopping && !this.polling)
+            this.schedule();
+    }
+    /** Public fake-clock seam; the timer calls the same transition. */
+    async poll() {
+        if (!this.started || this.stopping || this.polling)
+            return;
+        this.polling = true;
+        let delay;
+        try {
+            const ready = this.store.sweep(this.inFlight);
+            for (const event of ready) {
+                if (this.stopping)
+                    return;
+                const outcome = await this.admit(event);
+                if (outcome === 'busy') {
+                    this.busyStreak++;
+                    delay = Math.min(BUSY_RETRY_MAX_MS, BUSY_RETRY_MIN_MS * 2 ** Math.min(this.busyStreak - 1, 4));
+                    break;
+                }
+                this.busyStreak = 0;
+                // One wake per turn boundary: the next due reminder waits for the
+                // following poll, by which time this one's turn has claimed the role.
+                if (outcome === 'admitted') {
+                    delay = 0;
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            this.deps.log(`[${this.role}] self-reminder dispatch failed: ${error?.name ?? 'Error'}; retrying`);
+            delay = UNAVAILABLE_RETRY_MS[0];
+        }
+        finally {
+            this.polling = false;
+        }
+        this.schedule(delay);
+    }
+    async admit(event) {
+        const summary = this.store.eventSummary(event.id);
+        if (!summary)
+            return 'skipped';
+        const { reminder } = summary;
+        const origin = {
+            kind: 'self-reminder', eventId: event.id, reminderId: reminder.id, revision: event.revision,
+        };
+        const text = wakePrompt(event, reminder, this.deps.now(), event.attempts > 0);
+        this.inFlight.add(event.id);
+        let attempt;
+        try {
+            attempt = await this.admitter.tryReminder(text, origin, () => !this.stopping && this.store.markAdmitting(event.id), () => this.guard(event.id));
+        }
+        catch (error) {
+            this.inFlight.delete(event.id);
+            this.store.releaseUndispatched(event.id, this.retryAt(event));
+            throw error;
+        }
+        if (attempt.state === 'busy') {
+            this.inFlight.delete(event.id);
+            return 'busy';
+        }
+        if (attempt.state === 'unavailable') {
+            this.inFlight.delete(event.id);
+            this.store.releaseUndispatched(event.id, this.retryAt(event));
+            this.deps.log(`[${this.role}] self-reminder ${event.id.slice(0, 12)} not admitted; will retry within its window`);
+            return 'skipped';
+        }
+        // Own the completion before anything else can throw: the queued prompt
+        // ends this admission whatever happens to the receipt write below.
+        const settled = () => {
+            this.inFlight.delete(event.id);
+            // Settled without the guard dispatching it (offline session, refused at
+            // release while stopping): still undispatched, so it may be retried.
+            // A failed write leaves it admitting with no owner; sweep recovers that.
+            try {
+                this.store.releaseUndispatched(event.id, this.retryAt(event));
+            }
+            catch { /* recovered by sweep */ }
+            this.changed();
+        };
+        void attempt.queued.completion.then(settled, settled);
+        // The receipt is diagnostic only; dispatch state is the release guard's.
+        try {
+            this.store.recordReceipt(event.id, attempt.queued.promptId);
+        }
+        catch {
+            this.deps.log(`[${this.role}] self-reminder ${event.id.slice(0, 12)} receipt not recorded`);
+        }
+        this.deps.log(`[${this.role}] self-reminder ${event.id.slice(0, 12)} admitted`);
+        return 'admitted';
+    }
+    guard(eventId) {
+        const result = this.store.claimDispatch(eventId, this.stopping);
+        if (!result.dispatch)
+            this.deps.log(`[${this.role}] self-reminder ${eventId.slice(0, 12)} not dispatched at release (${result.reason})`);
+        return result.dispatch;
+    }
+    retryAt(event) {
+        const step = UNAVAILABLE_RETRY_MS[Math.min(event.attempts, UNAVAILABLE_RETRY_MS.length - 1)];
+        return this.deps.now() + step;
+    }
+    schedule(delayMs) {
+        if (this.timer !== undefined)
+            this.deps.clearTimer(this.timer);
+        this.timer = undefined;
+        if (this.stopping)
+            return;
+        let delay = delayMs;
+        if (delay === undefined) {
+            const next = this.store.nextWorkAt(this.inFlight);
+            if (next === undefined) {
+                this.overdueStreak = 0;
+                return;
+            }
+            delay = Math.max(0, next - this.deps.now());
+            // Work that is already overdue after a full poll means the poll could
+            // not move it (storage refusing writes, say). Back off instead of
+            // re-arming at once; any real progress resets the streak.
+            if (delay === 0) {
+                delay = this.overdueStreak ? Math.min(REMINDER_POLL_CEILING_MS, 1_000 * 2 ** Math.min(this.overdueStreak - 1, 6)) : 0;
+                this.overdueStreak++;
+            }
+            else
+                this.overdueStreak = 0;
+        }
+        delay = Math.min(delay, REMINDER_POLL_CEILING_MS);
+        this.timer = this.deps.setTimer(() => {
+            this.timer = undefined;
+            void this.poll();
+        }, delay);
+    }
+}
+/**
+ * The wake text. It carries the agent's own title so the wake is legible, but
+ * the note is only returned by `fleet_reminder_inspect`, which also re-checks
+ * eligibility at the moment the agent acts.
+ */
+export function wakePrompt(event, reminder, now, retry) {
+    const lateBy = Math.max(0, now - Date.parse(reminder.dueAt));
+    return [
+        '[fleet-reminder]',
+        `event_id: ${event.id}`,
+        `reminder_id: ${reminder.id}`,
+        `revision: ${event.revision}`,
+        `title: ${JSON.stringify(reminder.title)}`,
+        `due: ${reminder.localTime} ${reminder.timeZone} (${reminder.dueAt})`,
+        ...(lateBy >= 60_000 ? [`late_by_minutes: ${Math.floor(lateBy / 60_000)}`] : []),
+        ...(retry ? ['note: an earlier admission of this wake never reached you; this is the same event'] : []),
+        '',
+        'This is a reminder you scheduled for yourself through Fleet. It is not an owner message,',
+        'not ours mail, and grants no new authority.',
+        'Call fleet_reminder_inspect with this event_id to read the note and confirm it is still eligible,',
+        'then decide what to do within your existing instructions and authority; doing nothing is fine.',
+        'When handled, call fleet_reminder_ack with event_id and revision. Ack records only that you',
+        'handled this wake; it sends nothing. To postpone instead, call fleet_reminder_update with a new',
+        'local_time. Fleet never messages anyone on your behalf.',
+    ].join('\n');
+}

package/dist/reminders/runtime.d.ts

@@ -0,0 +1,27 @@
+import { ReminderManager, type ReminderAdmitter, type ReminderManagerDeps } from './manager.js';
+import type { ReminderToolBackend } from './tools.js';
+export interface RoleReminderBinding {
+    role: string;
+    stateDir: string;
+    /** The managed runtime's own record; nothing here comes from the agent. */
+    runtime: {
+        instance?: string;
+        cid?: string;
+        action?: string;
+        lifetime?: 'permanent' | 'temporary';
+    };
+    /** Whether this session backend accepts supervisor-submitted prompts. */
+    promptInput: boolean;
+    admitter: ReminderAdmitter;
+    service: {
+        setReminders?(backend: ReminderToolBackend | undefined): void;
+    };
+    deps: ReminderManagerDeps;
+}
+/**
+ * Bind self-reminders for one runner attempt: load the store for exactly this
+ * runtime instance and identity, expose it behind the agent's own MCP tools,
+ * and return the (not yet started) dispatcher. Any doubt leaves reminders
+ * unavailable rather than guessing an owner.
+ */
+export declare function bindRoleReminders(binding: RoleReminderBinding): ReminderManager | undefined;

package/dist/reminders/runtime.js

@@ -0,0 +1,32 @@
+import { ReminderManager } from './manager.js';
+import { ReminderStore } from './store.js';
+/**
+ * Bind self-reminders for one runner attempt: load the store for exactly this
+ * runtime instance and identity, expose it behind the agent's own MCP tools,
+ * and return the (not yet started) dispatcher. Any doubt leaves reminders
+ * unavailable rather than guessing an owner.
+ */
+export function bindRoleReminders(binding) {
+    const { role, runtime, deps } = binding;
+    if (!binding.promptInput || !binding.service.setReminders)
+        return undefined;
+    if (!runtime.instance || !runtime.action || !/^[A-Fa-f0-9]{64}$/.test(runtime.cid ?? '')
+        || (runtime.lifetime !== 'permanent' && runtime.lifetime !== 'temporary')) {
+        deps.log(`[${role}] self-reminders unavailable: managed runtime identity is not established`);
+        return undefined;
+    }
+    const owner = {
+        role, lifetime: runtime.lifetime, instance: runtime.instance, cid: runtime.cid, action: runtime.action,
+    };
+    let store;
+    try {
+        store = new ReminderStore(binding.stateDir, owner, deps.now, deps.log);
+    }
+    catch (error) {
+        deps.log(`[${role}] self-reminders unavailable: state could not be opened (${error?.name ?? 'Error'})`);
+        return undefined;
+    }
+    const manager = new ReminderManager(role, store, binding.admitter, deps);
+    binding.service.setReminders({ store, changed: () => manager.changed() });
+    return manager;
+}

package/dist/reminders/schedule.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Wall-clock schedule resolution for self-reminders.
+ *
+ * A reminder is stated the way a person states it — a calendar date, a time of
+ * day and the IANA zone it is meant in — and stored as the one UTC instant that
+ * statement denotes. Nothing is inferred from the host's own zone: a time with
+ * an offset, a missing date or an unknown zone is refused rather than guessed.
+ *
+ * Daylight-saving transitions are the two places a wall time is not one
+ * instant. A time skipped by a spring-forward gap does not exist and is
+ * refused. A time repeated by a fall-back overlap exists twice, and the caller
+ * must say which with `fold` (0 = the first occurrence, 1 = the second), the
+ * same convention as Python's `datetime.fold`.
+ */
+export declare class ReminderScheduleError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Canonical IANA zone name, or a typed refusal. Host defaults never apply. */
+export declare function canonicalTimeZone(raw: unknown): string;
+export interface ResolvedSchedule {
+    /** Canonical `YYYY-MM-DDTHH:MM:SS`, as the caller meant it. */
+    localTime: string;
+    timeZone: string;
+    /** Present only when the wall time was ambiguous and the caller chose. */
+    fold?: 0 | 1;
+    dueAt: number;
+}
+/**
+ * Resolve a wall time in a zone to its instant. Every offset the zone uses in
+ * the surrounding two days is a candidate; a candidate survives only if it
+ * reads back as the requested wall time. Zero survivors is a gap, two is an
+ * overlap. Zones change offset at most once in any such window in practice,
+ * and a reading that does not round-trip is never accepted, so the answer is
+ * never a guess.
+ */
+export declare function resolveSchedule(localTime: unknown, timeZone: unknown, fold?: unknown): ResolvedSchedule;

package/dist/reminders/schedule.js

@@ -0,0 +1,104 @@
+/**
+ * Wall-clock schedule resolution for self-reminders.
+ *
+ * A reminder is stated the way a person states it — a calendar date, a time of
+ * day and the IANA zone it is meant in — and stored as the one UTC instant that
+ * statement denotes. Nothing is inferred from the host's own zone: a time with
+ * an offset, a missing date or an unknown zone is refused rather than guessed.
+ *
+ * Daylight-saving transitions are the two places a wall time is not one
+ * instant. A time skipped by a spring-forward gap does not exist and is
+ * refused. A time repeated by a fall-back overlap exists twice, and the caller
+ * must say which with `fold` (0 = the first occurrence, 1 = the second), the
+ * same convention as Python's `datetime.fold`.
+ */
+export class ReminderScheduleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ReminderScheduleError';
+    }
+}
+const LOCAL_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/;
+const HOUR_MS = 60 * 60 * 1000;
+const formatters = new Map();
+function formatter(timeZone) {
+    let value = formatters.get(timeZone);
+    if (!value) {
+        value = new Intl.DateTimeFormat('en-US', {
+            timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit',
+            hour: '2-digit', minute: '2-digit', second: '2-digit', era: 'short',
+        });
+        formatters.set(timeZone, value);
+    }
+    return value;
+}
+/** Canonical IANA zone name, or a typed refusal. Host defaults never apply. */
+export function canonicalTimeZone(raw) {
+    if (typeof raw !== 'string' || !raw.trim() || raw.length > 64 || !/^[A-Za-z0-9_+\-/]+$/.test(raw))
+        throw new ReminderScheduleError('invalid_time_zone', 'time_zone must be an IANA zone name such as Europe/London or UTC');
+    try {
+        return new Intl.DateTimeFormat('en-US', { timeZone: raw }).resolvedOptions().timeZone;
+    }
+    catch {
+        throw new ReminderScheduleError('invalid_time_zone', `unknown IANA time zone '${raw}'`);
+    }
+}
+function parseLocalTime(raw) {
+    const match = typeof raw === 'string' ? LOCAL_TIME_RE.exec(raw) : null;
+    if (!match)
+        throw new ReminderScheduleError('invalid_local_time', 'local_time must be a calendar date and time without an offset, e.g. 2027-01-20T16:00 or 2027-01-20T16:00:00');
+    const [year, month, day, hour, minute, second] = match.slice(1).map(part => Number(part ?? 0));
+    const wall = { year: year, month: month, day: day, hour: hour, minute: minute, second: second };
+    // Date.UTC normalizes overflow (Feb 30 -> Mar 2); a round trip rejects it.
+    const probe = new Date(wallMs(wall));
+    if (wall.year < 1970 || wall.year > 9999 || probe.getUTCFullYear() !== wall.year
+        || probe.getUTCMonth() + 1 !== wall.month || probe.getUTCDate() !== wall.day
+        || wall.hour > 23 || wall.minute > 59 || wall.second > 59)
+        throw new ReminderScheduleError('invalid_local_time', `local_time '${String(raw)}' is not a real calendar date and time`);
+    return wall;
+}
+function wallMs(wall) {
+    return Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second);
+}
+/** The wall-clock reading of `instant` in `timeZone`, expressed as naive UTC milliseconds. */
+function wallAt(instant, timeZone) {
+    const parts = Object.fromEntries(formatter(timeZone).formatToParts(new Date(instant))
+        .map(part => [part.type, part.value]));
+    if (parts.era !== 'AD')
+        throw new ReminderScheduleError('invalid_local_time', 'dates before the common era are not supported');
+    return Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute), Number(parts.second));
+}
+/**
+ * Resolve a wall time in a zone to its instant. Every offset the zone uses in
+ * the surrounding two days is a candidate; a candidate survives only if it
+ * reads back as the requested wall time. Zero survivors is a gap, two is an
+ * overlap. Zones change offset at most once in any such window in practice,
+ * and a reading that does not round-trip is never accepted, so the answer is
+ * never a guess.
+ */
+export function resolveSchedule(localTime, timeZone, fold) {
+    const zone = canonicalTimeZone(timeZone);
+    const wall = parseLocalTime(localTime);
+    if (fold !== undefined && fold !== null && fold !== 0 && fold !== 1)
+        throw new ReminderScheduleError('invalid_fold', 'fold must be 0 (first occurrence) or 1 (second occurrence)');
+    const naive = wallMs(wall);
+    const offsets = new Set();
+    for (let probe = -48; probe <= 48; probe += 6) {
+        const instant = naive + probe * HOUR_MS;
+        offsets.add(wallAt(instant, zone) - instant);
+    }
+    const matches = [...new Set([...offsets].map(offset => naive - offset))]
+        .filter(instant => wallAt(instant, zone) === naive)
+        .sort((a, b) => a - b);
+    const canonical = new Date(naive).toISOString().slice(0, 19);
+    if (!matches.length)
+        throw new ReminderScheduleError('nonexistent_local_time', `${canonical} does not exist in ${zone} (skipped by a daylight-saving change); choose another time`);
+    if (matches.length > 1) {
+        if (fold !== 0 && fold !== 1)
+            throw new ReminderScheduleError('ambiguous_local_time', `${canonical} occurs twice in ${zone}; pass fold 0 for the first occurrence or 1 for the second`);
+        return { localTime: canonical, timeZone: zone, fold, dueAt: matches[fold] };
+    }
+    return { localTime: canonical, timeZone: zone, dueAt: matches[0] };
+}