@ours.network/fleet 1.2.0-nightly.9 → 2.0.0

package/dist/reminders/manager.d.ts

@@ -0,0 +1,75 @@
+import type { ReminderAttempt, UrgentReminderHooks } 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>;
+    /** Urgent admission (see `RoleTurnArbiter.tryUrgentReminder`). Absent: urgent reminders are idle-only. */
+    tryUrgentReminder?(origin: Extract<PromptOrigin, {
+        kind: 'self-reminder';
+    }>, hooks: UrgentReminderHooks): 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 by default: 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. A reminder created with `interrupt: true` is considered first and may
+ * ask an interruptible busy turn to stop once (`tryUrgentReminder`); the
+ * release guard is still the only path to 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,278 @@
+/**
+ * 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 by default: 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. A reminder created with `interrupt: true` is considered first and may
+ * ask an interruptible busy turn to stop once (`tryUrgentReminder`); the
+ * release guard is still the only path to 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 {
+            // Urgent events that may still interrupt come first, so neither a busy
+            // ordinary event nor an urgent one whose single interruption is spent
+            // (now idle-only) can hide them. Earliest-due order is kept within each
+            // group; ordinary and spent events keep the idle-only default.
+            const ready = this.store.sweep(this.inFlight);
+            const rank = (id) => {
+                const summary = this.store.eventSummary(id);
+                return summary?.reminder.interrupt === true && !summary.event.interrupt ? 0 : 1;
+            };
+            const ranks = new Map(ready.map(event => [event.id, rank(event.id)]));
+            ready.sort((a, b) => ranks.get(a.id) - ranks.get(b.id));
+            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 = () => {
+            const current = this.store.eventSummary(event.id)?.event ?? event;
+            return wakePrompt(current, reminder, this.deps.now(), event.attempts > 0);
+        };
+        const beforeQueue = () => !this.stopping && this.store.markAdmitting(event.id);
+        const releaseGuard = () => this.guard(event.id);
+        this.inFlight.add(event.id);
+        let attempt;
+        try {
+            attempt = reminder.interrupt === true && this.admitter.tryUrgentReminder
+                ? await this.admitter.tryUrgentReminder(origin, {
+                    beforeQueue, releaseGuard, text,
+                    mayInterrupt: () => !this.stopping && this.store.mayInterrupt(event.id),
+                    markRequested: target => !this.stopping && this.store.markInterruptRequested(event.id, target),
+                    recordOutcome: report => {
+                        this.store.recordInterruptOutcome(event.id, report.outcome, report.reason);
+                        this.deps.log(`[${this.role}] self-reminder ${event.id.slice(0, 12)} interrupt ${report.outcome}`
+                            + ` (${report.target.source} turn)`);
+                    },
+                    deferred: reason => this.store.recordInterruptDeferred(event.id, reason),
+                    stillAdmitting: () => !this.stopping && this.store.stillAdmitting(event.id),
+                })
+                : await this.admitter.tryReminder(text(), origin, beforeQueue, releaseGuard);
+        }
+        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);
+            // An urgent attempt may have claimed the event before finding the role
+            // busy again (owner input won the boundary after an interruption).
+            this.store.releaseUndispatched(event.id, this.deps.now());
+            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'] : []),
+        ...(reminder.interrupt ? ['urgent: true'] : []),
+        ...interruptLines(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');
+}
+/**
+ * What the wake may truthfully say about its interruption. Only a correlated
+ * cancellation is called one; everything else is reported as what it was.
+ */
+function interruptLines(event) {
+    const interrupt = event.interrupt;
+    if (!interrupt)
+        return [];
+    const source = interrupt.target.source;
+    const resume = `Your session and its context were kept; re-check that ${source} work and resume it if it still matters.`;
+    switch (interrupt.outcome) {
+        case 'cancelled': return [
+            `interrupt: your previous ${source} turn was cancelled for this wake.`, resume
+        ];
+        case 'ended': return [
+            `interrupt: Fleet asked your previous ${source} turn to stop; it ended, but whether it was cancelled`
+                + ' or finished on its own is not confirmed.', resume
+        ];
+        case 'forced': return [
+            `interrupt: your previous ${source} turn ignored the stop request and the adapter was restarted;`
+                + ' this wake arrived later than its urgent time. Check what that turn left unfinished.'
+        ];
+        case 'failed':
+        case 'unknown':
+        case 'requested': return [
+            `interrupt: Fleet asked your previous ${source} turn to stop but the outcome is unknown (${interrupt.outcome});`
+                + ' this wake was delivered at the next idle boundary instead.'
+        ];
+    }
+}

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] };
+}