@cursor/bdk 0.2.1

package/src/internal/reminder-runner.ts

@@ -0,0 +1,1559 @@
+/**
+ * Per-session reminder runner: durable wake subscriptions with
+ * prompt XOR named handler XOR run, every/cron/delay/at schedules, and
+ * until as function XOR prompt.
+ */
+
+import { randomBytes } from "node:crypto";
+import type {
+  AuthContext,
+  ChannelSession,
+  DiscoveredReminder,
+  HostOtelApi,
+  JsonObject,
+  JsonValue,
+  ReminderCreateInput,
+  ReminderDefinition,
+  ReminderFireContext,
+  ReminderFireResult,
+  ReminderFollowupOptions,
+  ReminderInfo,
+  ReminderStatus,
+  ReminderUntilContext,
+  TurnOutcome,
+} from "../types.js";
+import { channelContinuationIdentity, httpContinuationIdentity } from "./continuation-channel.js";
+import { continuationSource } from "./continuation-identity.js";
+import { NAME_PATTERN } from "./discovery/names.js";
+import { parseDuration } from "./duration.js";
+import type { PlatformTimers } from "./platform-timers.js";
+import {
+  REMINDER_CP_PROTOCOL_VERSION,
+  type ReminderControlPlane,
+  type ReminderCreateIntent,
+  type ReminderExecutionOutcome,
+  type ReminderFireDescriptor,
+  scheduleSpecFromCreateInput,
+  toWireReschedule,
+} from "./reminder-control-plane-protocol.js";
+import {
+  defaultBusyPolicy,
+  MAX_TIMER_MS,
+  nextCronFireMs,
+  ReminderValidationError,
+  resolveSchedule,
+} from "./reminder-schedule.js";
+import type { ReminderBusyPolicy, ReminderRecord } from "./reminder-store.js";
+import { APP_AUTH } from "./schedule-runner.js";
+import {
+  type EngineSendOptions,
+  HTTP_CHANNEL_ID,
+  SessionAuthError,
+  SessionBusyError,
+  type SessionEngine,
+} from "./session-engine.js";
+
+export { ReminderValidationError } from "./reminder-schedule.js";
+
+/** Max UTF-8 byte length of `JSON.stringify(args)` on named-handler create. */
+export const REMINDER_ARGS_MAX_BYTES: number = 32 * 1024;
+
+export class UnknownReminderError extends Error {
+  constructor(
+    reminderId: string,
+    readonly availableReminderIds: string[],
+  ) {
+    super(`Unknown reminder "${reminderId}"`);
+    this.name = "UnknownReminderError";
+  }
+}
+
+interface LiveHandlers {
+  run?: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
+  untilFn?: (ctx: ReminderUntilContext) => Promise<boolean>;
+}
+
+export interface ReminderRunnerOptions {
+  /** Discovered `agent/reminders/*` handlers, keyed by module stem. */
+  namedHandlers?: readonly DiscoveredReminder[];
+  /**
+   * Architecture v2: reject anonymous `run` and function `until` at create
+   * (named `handler` + prompt remain), whether local or hosted.
+   */
+  rejectAnonymousHandlers?: boolean;
+  /**
+   * When set (local self-hosted architecture v2), create/cancel/rekey go
+   * through the control-plane protocol and fires are guest executions of
+   * immutable descriptors.
+   */
+  controlPlane?: ReminderControlPlane;
+  /** Agent architecture; used with {@link controlPlane} for v2 protocol path. */
+  architecture?: "v1" | "v2";
+  /**
+   * Hosted v2 guest (`--no-control-plane`, architecture v2). A pod starts
+   * for one delivery and stops when it settles, so a fire usually lands on
+   * a pod that holds no session for the reminder's continuation, and the
+   * pod may stop as soon as the fire's outcome is applied. The runner then
+   * opens a session on the stored continuation key and waits for the turn.
+   */
+  hostedGuest?: ReminderHostedGuestOptions;
+}
+
+export interface ReminderHostedGuestOptions {
+  /**
+   * Principal for the session a prompt fire opens when the pod holds none.
+   * Hosted admissions open sessions with the same value, so a session the
+   * engine restores from durable storage keeps its principal. Return
+   * `undefined` when no principal applies; the fire then skips with a
+   * reschedule so the control plane keeps the reminder armed.
+   */
+  fireAuth: () => AuthContext | null | undefined;
+}
+
+/**
+ * Reschedule applied when a hosted fire cannot open a session (no
+ * principal). A one-shot `skipped` outcome without a reschedule completes
+ * the reminder, which would lose the check-in for good.
+ */
+export const REMINDER_SESSION_OPEN_RETRY_DELAY = "5m";
+
+/**
+ * `reason` tag on `agent_sdk.reminder.fire_outcome`. Prompt fires report
+ * how the session was reached: `session_joined` (held by this pod),
+ * `session_restored` (read back from durable storage), `session_opened`
+ * (fresh session on the stored key), `session_gone` (no session and none
+ * could be opened). `fire_threw` pairs with kind `error`: the fire raised
+ * and the hosted admission retries it.
+ */
+export type ReminderFireOutcomeReason =
+  | "session_gone"
+  | "session_opened"
+  | "session_restored"
+  | "session_joined"
+  | "handler_missing"
+  | "handler_lost_on_restart"
+  | "missing_handler"
+  | "run_stop"
+  | "run_skip"
+  | "run_delivered"
+  | "until_fn"
+  | "busy"
+  | "followup_failed"
+  | "fire_threw";
+
+export const REMINDER_FIRE_OUTCOME_METRIC = "agent_sdk.reminder.fire_outcome";
+
+/** What one `executeFire` reports: the CP outcome plus the telemetry tags. */
+interface FireExecution {
+  outcome: ReminderExecutionOutcome;
+  reason: ReminderFireOutcomeReason;
+  /** Set when the hosted guest awaited the turn before reporting. */
+  turnStatus?: TurnOutcome["status"];
+}
+
+interface PromptDelivery {
+  result: ReminderFireResult;
+  reason: ReminderFireOutcomeReason;
+  turnStatus?: TurnOutcome["status"];
+}
+
+/** Out-params `sendFollowup` fills in for the fire's telemetry. */
+interface FollowupSettle {
+  turnStatus?: TurnOutcome["status"];
+  skipReason?: Extract<ReminderFireOutcomeReason, "busy" | "followup_failed">;
+}
+
+/** How a prompt fire reached (or failed to reach) its session. */
+type FollowupTarget =
+  | {
+      auth: AuthContext | null;
+      reached: Extract<ReminderFireOutcomeReason, "session_joined" | "session_restored">;
+    }
+  | {
+      auth: undefined;
+      /**
+       * `session_gone`: no session anywhere. `session_unreadable`: the durable
+       * index has one but the local re-read missed; never open a fresh
+       * session over it.
+       */
+      reached: "session_gone" | "session_unreadable";
+    };
+
+/** Guest-side read surface shared by v1 timed-work and the v2 CP client. */
+interface ReminderReader {
+  getReminder(id: string): Promise<ReminderRecord | undefined>;
+  listReminders(): Promise<ReminderRecord[]>;
+}
+
+/**
+ * Server wiring for {@link ReminderRunnerOptions.rejectAnonymousHandlers}:
+ * architecture v2 always rejects anonymous run/until (local or hosted).
+ */
+export function rejectAnonymousReminderHandlers(options: {
+  noControlPlane?: boolean;
+  architecture?: string;
+}): boolean {
+  return options.architecture === "v2";
+}
+
+function newReminderId(): string {
+  return `rem_${randomBytes(8).toString("hex")}`;
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value as Record<string, unknown>).every(isJsonValue)
+  );
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value);
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  return isJsonObject(value);
+}
+
+/** Same stem rules as `agent/reminders/<name>.ts` discovery. */
+function isValidReminderHandlerName(name: string): boolean {
+  return NAME_PATTERN.test(name) && !name.includes("__");
+}
+
+function assertReminderArgsSize(args: JsonObject): void {
+  const bytes = Buffer.byteLength(JSON.stringify(args), "utf8");
+  if (bytes > REMINDER_ARGS_MAX_BYTES) {
+    throw new ReminderValidationError(
+      `reminders.create args exceed ${REMINDER_ARGS_MAX_BYTES} bytes (got ${bytes})`,
+    );
+  }
+}
+
+function toInfo(record: ReminderRecord): ReminderInfo {
+  return {
+    id: record.id,
+    purpose: record.purpose,
+    channelId: record.channelId,
+    continuationToken: record.continuationToken,
+    target: record.target,
+    scheduleKind: record.scheduleKind,
+    scheduleValue: record.scheduleValue,
+    prompt: record.prompt,
+    handler: record.handler,
+    args: record.args,
+    untilPrompt: record.untilPrompt,
+    busyPolicy: record.busyPolicy,
+    status: record.status === "firing" ? "armed" : record.status,
+    disarmReason: record.disarmReason,
+    fireCount: record.fireCount,
+    nextFireAt: new Date(record.nextFireAtMs).toISOString(),
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    hasRunHandler: record.hasRunHandler === true,
+    hasUntilFn: record.hasUntilFn === true,
+  };
+}
+
+function stopFire(
+  reason: Extract<
+    ReminderFireOutcomeReason,
+    "handler_missing" | "handler_lost_on_restart" | "missing_handler" | "until_fn"
+  >,
+): FireExecution {
+  return { outcome: { kind: "stop", reason }, reason };
+}
+
+function runReason(result: ReminderFireResult): ReminderFireOutcomeReason {
+  switch (result.action) {
+    case "stop":
+      return "run_stop";
+    case "skip":
+      return "run_skip";
+    case "delivered":
+      return "run_delivered";
+  }
+}
+
+function buildFirePrompt(record: ReminderRecord): string {
+  const recurring = record.scheduleKind === "every" || record.scheduleKind === "cron";
+  const lines = [
+    `[reminder] id=${record.id} purpose=${record.purpose}`,
+    record.prompt ?? "Reminder fired. Check current state and only act if needed.",
+  ];
+  if (record.untilPrompt !== undefined && record.untilPrompt.trim() !== "") {
+    lines.push("", `Stop condition: ${record.untilPrompt}`);
+    if (recurring) {
+      lines.push(`When the stop condition is met, call reminders_cancel with id=${record.id}.`);
+    } else {
+      lines.push(
+        "This is a one-shot reminder (auto-completes after this fire); no cancel needed unless you armed a separate recurring reminder.",
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export class ReminderRunner {
+  private readonly records = new Map<string, ReminderRecord>();
+  private readonly handlers = new Map<string, LiveHandlers>();
+  private readonly namedHandlers = new Map<string, ReminderDefinition>();
+  private readonly namedHandlerNames = new Map<ReminderDefinition, string>();
+  private readonly timers = new Map<string, NodeJS.Timeout>();
+  private readonly firing = new Set<string>();
+  /** Single-flight idle gates keyed by `channelId:continuationToken`. */
+  private readonly idleGates = new Map<string, Promise<void>>();
+  private started = false;
+  private readonly rejectAnonymousHandlers: boolean;
+  private readonly controlPlane: ReminderControlPlane | undefined;
+  private readonly architecture: "v1" | "v2" | undefined;
+  private readonly hostedGuest: ReminderHostedGuestOptions | undefined;
+  /**
+   * A control-plane read failure is logged once per outage, not per call.
+   * The next successful read re-arms the log.
+   */
+  private controlPlaneReadFailureLogged = false;
+
+  constructor(
+    private readonly engine: SessionEngine,
+    private readonly logger: (line: string) => void = () => {},
+    private readonly platformTimers?: PlatformTimers,
+    options: ReminderRunnerOptions = {},
+  ) {
+    this.rejectAnonymousHandlers = options.rejectAnonymousHandlers === true;
+    this.controlPlane = options.controlPlane;
+    this.architecture = options.architecture;
+    this.hostedGuest = options.hostedGuest;
+    for (const reminder of options.namedHandlers ?? []) {
+      this.namedHandlers.set(reminder.name, reminder.definition);
+      this.namedHandlerNames.set(reminder.definition, reminder.name);
+    }
+  }
+
+  /** True when create/cancel/rekey/fire go through the CP protocol. */
+  private get usesControlPlaneProtocol(): boolean {
+    return this.controlPlane !== undefined && this.architecture === "v2";
+  }
+
+  /**
+   * Where reminder documents are read from. Under the CP protocol that is
+   * the v2 control-plane client; the v1 timed-work route answers 405 for a
+   * v2 deployment, which used to leave `list()` with only this process's
+   * in-memory map (breaking arm idempotence and `cancelForContinuation`).
+   */
+  private get reminderReader(): ReminderReader | undefined {
+    if (this.usesControlPlaneProtocol) {
+      return this.controlPlane;
+    }
+    return this.platformTimers;
+  }
+
+  private logControlPlaneReadFailure(what: string, error: unknown): void {
+    if (this.usesControlPlaneProtocol && this.controlPlaneReadFailureLogged) {
+      return;
+    }
+    this.controlPlaneReadFailureLogged = true;
+    this.logger(
+      `[agent-sdk] reminders: control-plane ${what} failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  /**
+   * Load reminder documents from the control plane into memory. Does not
+   * arm in-process timers — the CP owns clocks.
+   */
+  async hydrate(): Promise<void> {
+    const reader = this.reminderReader;
+    if (reader === undefined) {
+      return;
+    }
+    let remote: ReminderRecord[] = [];
+    try {
+      remote = await reader.listReminders();
+    } catch (error) {
+      this.logControlPlaneReadFailure("list", error);
+      return;
+    }
+    this.controlPlaneReadFailureLogged = false;
+    this.records.clear();
+    for (const record of remote) {
+      this.records.set(record.id, record);
+    }
+    if (this.usesControlPlaneProtocol) {
+      // The CP owns status; a fire whose handler is missing reports `stop`
+      // from executeFire instead of the guest writing a disarm.
+      if (remote.length > 0) {
+        this.logger(
+          `[agent-sdk] reminders: hydrated ${remote.length} reminder(s) from control plane`,
+        );
+      }
+      return;
+    }
+    let disarmedOrphan = 0;
+    for (const record of [...this.records.values()]) {
+      if (record.status !== "armed") {
+        continue;
+      }
+      if (record.handler !== undefined) {
+        if (this.namedHandlers.get(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          disarmedOrphan += 1;
+        }
+        continue;
+      }
+      if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        this.handlers.get(record.id) === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        disarmedOrphan += 1;
+      }
+    }
+    if (remote.length > 0 || disarmedOrphan > 0) {
+      this.logger(
+        `[agent-sdk] reminders: hydrated ${remote.length} reminder(s) from control plane` +
+          (disarmedOrphan > 0 ? `; disarmed ${disarmedOrphan} without live handlers` : ""),
+      );
+    }
+  }
+
+  /** Start deadline timers for armed reminders (tests / no control plane). */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    await this.hydrate();
+    if (this.platformTimers !== undefined) {
+      return;
+    }
+    const armed = [...this.records.values()].filter(r => r.status === "armed");
+    let restored = 0;
+    let disarmedOrphan = 0;
+    for (const record of armed) {
+      if (record.handler !== undefined) {
+        if (this.namedHandlers.get(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          disarmedOrphan += 1;
+          continue;
+        }
+        this.armTimer(record);
+        restored += 1;
+        continue;
+      }
+      if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        this.handlers.get(record.id) === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        disarmedOrphan += 1;
+        continue;
+      }
+      this.armTimer(record);
+      restored += 1;
+    }
+    if (restored > 0 || disarmedOrphan > 0) {
+      this.logger(
+        `[agent-sdk] reminders: restored ${restored} armed reminder(s)` +
+          (disarmedOrphan > 0 ? `; disarmed ${disarmedOrphan} without live handlers` : ""),
+      );
+    }
+  }
+
+  private async persist(record: ReminderRecord): Promise<void> {
+    if (this.platformTimers !== undefined) {
+      await this.platformTimers.putReminder(record);
+    }
+    this.records.set(record.id, record);
+  }
+
+  private async getRecord(id: string): Promise<ReminderRecord | undefined> {
+    const reader = this.reminderReader;
+    if (reader !== undefined) {
+      try {
+        const remote = await reader.getReminder(id);
+        this.controlPlaneReadFailureLogged = false;
+        if (remote === undefined) {
+          this.records.delete(id);
+          return undefined;
+        }
+        this.records.set(id, remote);
+        return remote;
+      } catch (error) {
+        this.logControlPlaneReadFailure(`get for ${id}`, error);
+        return this.records.get(id);
+      }
+    }
+    return this.records.get(id);
+  }
+
+  /**
+   * Under the CP protocol a list failure propagates: the in-memory map is
+   * only what this process created, and returning it would let a caller
+   * arm duplicates or miss rows to cancel. v1 keeps the best-effort form.
+   */
+  private async allRecords(): Promise<ReminderRecord[]> {
+    const reader = this.reminderReader;
+    if (reader !== undefined) {
+      try {
+        const remote = await reader.listReminders();
+        this.controlPlaneReadFailureLogged = false;
+        this.records.clear();
+        for (const record of remote) {
+          this.records.set(record.id, record);
+        }
+      } catch (error) {
+        this.logControlPlaneReadFailure("list", error);
+        if (this.usesControlPlaneProtocol) {
+          throw error;
+        }
+      }
+    }
+    return [...this.records.values()];
+  }
+
+  stop(): void {
+    this.started = false;
+    for (const timer of this.timers.values()) {
+      clearTimeout(timer);
+    }
+    this.timers.clear();
+    this.idleGates.clear();
+  }
+
+  async create(input: ReminderCreateInput): Promise<ReminderInfo> {
+    const hasPrompt = input.prompt !== undefined;
+    const hasRun = input.run !== undefined;
+    const hasHandler = input.handler !== undefined;
+    const formCount = [hasPrompt, hasRun, hasHandler].filter(Boolean).length;
+    if (formCount !== 1) {
+      throw new ReminderValidationError(
+        "reminders.create requires exactly one of prompt, handler, or run",
+      );
+    }
+    if (input.continuationToken.trim() === "") {
+      throw new ReminderValidationError("continuationToken is required");
+    }
+    if (input.channelId.trim() === "") {
+      throw new ReminderValidationError("channelId is required");
+    }
+    if (input.purpose.trim() === "") {
+      throw new ReminderValidationError("purpose is required");
+    }
+
+    const untilPrompt = typeof input.until === "string" ? input.until : undefined;
+    const untilFn = typeof input.until === "function" ? input.until : undefined;
+
+    if (hasHandler && input.until !== undefined) {
+      throw new ReminderValidationError(
+        "reminders.create: until is not valid with handler; encode the stop condition in args and the handler body",
+      );
+    }
+
+    if (this.rejectAnonymousHandlers) {
+      if (hasRun) {
+        throw new ReminderValidationError(
+          "reminders.create: anonymous run handlers are not durable on architecture v2; author reminders/<name>.ts under the project root and pass handler + args",
+        );
+      }
+      if (untilFn !== undefined) {
+        throw new ReminderValidationError(
+          "reminders.create: function until is not durable on architecture v2; use a string until prompt",
+        );
+      }
+    }
+
+    let handlerName: string | undefined;
+    let handlerArgs: JsonObject | undefined;
+    if (hasHandler) {
+      const handler = input.handler!;
+      const name =
+        typeof handler === "string" ? handler.trim() : this.namedHandlerNames.get(handler);
+      if (name === undefined) {
+        throw new ReminderValidationError(
+          "Unknown reminder handler definition (expected a default export discovered under reminders/)",
+        );
+      }
+      if (name === "") {
+        throw new ReminderValidationError("handler name is required");
+      }
+      if (!isValidReminderHandlerName(name)) {
+        throw new ReminderValidationError(
+          name.includes("__")
+            ? `Invalid reminder handler name "${name}": may not contain "__"`
+            : `Invalid reminder handler name "${name}": must match ${NAME_PATTERN}`,
+        );
+      }
+      if (this.namedHandlers.get(name) === undefined) {
+        throw new ReminderValidationError(
+          `Unknown reminder handler "${name}" (expected reminders/${name}.ts under the project root)`,
+        );
+      }
+      if (input.args !== undefined && !isJsonObject(input.args)) {
+        throw new ReminderValidationError("reminders.create args must be a JSON object");
+      }
+      handlerName = name;
+      handlerArgs = input.args ?? {};
+      assertReminderArgsSize(handlerArgs);
+    } else if (input.args !== undefined) {
+      throw new ReminderValidationError("reminders.create args is only valid with handler");
+    }
+
+    const schedule = resolveSchedule(input);
+    const busyPolicy: ReminderBusyPolicy = input.busyPolicy ?? defaultBusyPolicy(schedule.kind);
+    const hasRunHandler = input.run !== undefined;
+    const hasUntilFn = untilFn !== undefined;
+
+    let record: ReminderRecord;
+    if (this.usesControlPlaneProtocol) {
+      const intent: ReminderCreateIntent = {
+        protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+        purpose: input.purpose,
+        channelId: input.channelId,
+        continuationToken: input.continuationToken,
+        target: input.target,
+        // CP recalculates nextFireAtMs / intervalMs from the raw schedule.
+        schedule: scheduleSpecFromCreateInput(input),
+        prompt: input.prompt,
+        handler: handlerName,
+        args: handlerArgs,
+        hasRunHandler,
+        hasUntilFn,
+        untilPrompt,
+        busyPolicy,
+      };
+      record = await this.controlPlane!.createReminder(intent);
+      this.records.set(record.id, record);
+    } else {
+      const now = new Date().toISOString();
+      const id = newReminderId();
+      record = {
+        version: 1,
+        id,
+        purpose: input.purpose,
+        channelId: input.channelId,
+        continuationToken: input.continuationToken,
+        target: input.target,
+        scheduleKind: schedule.kind,
+        scheduleValue: schedule.value,
+        intervalMs: schedule.intervalMs,
+        prompt: input.prompt,
+        handler: handlerName,
+        args: handlerArgs,
+        hasRunHandler,
+        hasUntilFn,
+        untilPrompt,
+        busyPolicy,
+        status: "armed",
+        fireCount: 0,
+        nextFireAtMs: schedule.nextFireAtMs,
+        generation: 0,
+        createdAt: now,
+        updatedAt: now,
+      };
+      await this.persist(record);
+    }
+
+    this.handlers.set(record.id, {
+      run: input.run,
+      untilFn,
+    });
+    if (this.started && this.platformTimers === undefined && !this.usesControlPlaneProtocol) {
+      this.armTimer(record);
+    }
+
+    return toInfo(record);
+  }
+
+  async list(filter?: {
+    status?: ReminderStatus;
+    purpose?: string;
+    continuationToken?: string;
+  }): Promise<ReminderInfo[]> {
+    const all = await this.allRecords();
+    return all
+      .filter(r => {
+        if (filter?.status !== undefined) {
+          const publicStatus = r.status === "firing" ? "armed" : r.status;
+          if (publicStatus !== filter.status) {
+            return false;
+          }
+        }
+        if (filter?.purpose !== undefined && r.purpose !== filter.purpose) {
+          return false;
+        }
+        if (
+          filter?.continuationToken !== undefined &&
+          r.continuationToken !== filter.continuationToken
+        ) {
+          return false;
+        }
+        return true;
+      })
+      .map(r => {
+        const live = this.handlers.get(r.id);
+        const info = toInfo(r);
+        if (live === undefined) return info;
+        return {
+          ...info,
+          hasRunHandler: live.run !== undefined || info.hasRunHandler,
+          hasUntilFn: live.untilFn !== undefined || info.hasUntilFn,
+        };
+      });
+  }
+
+  async cancel(id: string, reason = "explicit_cancel"): Promise<ReminderInfo | undefined> {
+    if (this.usesControlPlaneProtocol) {
+      const updated = await this.controlPlane!.cancelReminder(id, reason);
+      if (updated === undefined) {
+        this.records.delete(id);
+        this.handlers.delete(id);
+        return undefined;
+      }
+      this.records.set(id, updated);
+      this.handlers.delete(id);
+      return toInfo(updated);
+    }
+    const record = await this.getRecord(id);
+    if (record === undefined) {
+      return undefined;
+    }
+    if (record.status !== "armed" && record.status !== "firing") {
+      return toInfo(record);
+    }
+    this.clearTimer(id);
+    const updated: ReminderRecord = {
+      ...record,
+      status: "cancelled",
+      disarmReason: reason,
+      generation: (record.generation ?? 0) + 1,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.persist(updated);
+    this.handlers.delete(id);
+    return toInfo(updated);
+  }
+
+  /** Cancel all armed reminders matching a continuation token (e.g. PR closed). */
+  async cancelForContinuation(continuationToken: string, reason: string): Promise<number> {
+    const armed = (await this.allRecords()).filter(r => r.status === "armed");
+    let n = 0;
+    for (const record of armed) {
+      if (record.continuationToken === continuationToken) {
+        await this.cancel(record.id, reason);
+        n += 1;
+      }
+    }
+    return n;
+  }
+
+  /**
+   * Re-key armed reminders when a channel rotates a session's continuation
+   * token (the built-in HTTP channel rotates after every follow-up). Without
+   * this, a reminder armed before the rotation misses its session at fire
+   * time and disarms as `session_gone`.
+   */
+  async rekeyContinuation(channelId: string, oldToken: string, newToken: string): Promise<number> {
+    if (this.usesControlPlaneProtocol) {
+      return this.controlPlane!.rekeyReminders(channelId, oldToken, newToken);
+    }
+    const armed = (await this.allRecords()).filter(
+      r => r.status === "armed" || r.status === "firing",
+    );
+    let n = 0;
+    for (const record of armed) {
+      if (record.channelId !== channelId || record.continuationToken !== oldToken) {
+        continue;
+      }
+      await this.persist({
+        ...record,
+        continuationToken: newToken,
+        generation: (record.generation ?? 0) + 1,
+        updatedAt: new Date().toISOString(),
+      });
+      n += 1;
+    }
+    return n;
+  }
+
+  /** Fire one reminder immediately (dev / hillclimb / control plane). */
+  async dispatch(
+    reminderId: string,
+    opts: { expectedFireCount?: number } = {},
+  ): Promise<{
+    reminderId: string;
+    outcome: "fired" | "noop";
+    reason?: string;
+  }> {
+    const record = await this.getRecord(reminderId);
+    if (record === undefined) {
+      const ids = (await this.allRecords()).map(r => r.id);
+      throw new UnknownReminderError(reminderId, ids);
+    }
+    if (opts.expectedFireCount !== undefined && record.fireCount !== opts.expectedFireCount) {
+      return {
+        reminderId,
+        outcome: "noop",
+        reason: "stale_fire_count",
+      };
+    }
+    const result = await this.fire(record.id, { force: true });
+    return { reminderId, ...result };
+  }
+
+  /**
+   * Architecture v2 / CP protocol guest entrypoint: execute an immutable fire
+   * descriptor and return an outcome. Does not mint ids or mutate
+   * authoritative status/fireCount — the control plane applies the outcome.
+   */
+  async executeFire(descriptor: ReminderFireDescriptor): Promise<ReminderExecutionOutcome> {
+    const record = this.recordFromDescriptor(descriptor);
+    this.records.set(record.id, record);
+    let fire: FireExecution;
+    try {
+      fire = await this.runFire(record);
+    } catch (error) {
+      // The hosted admission maps the throw to a retryable failure; count
+      // it so the retry loop is visible beside the settled outcomes.
+      this.recordFireOutcome(record, {
+        kind: "error",
+        reason: "fire_threw",
+        detail: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+    this.recordFireOutcome(record, {
+      kind: fire.outcome.kind,
+      reason: fire.reason,
+      turnStatus: fire.turnStatus,
+    });
+    return fire.outcome;
+  }
+
+  private async runFire(record: ReminderRecord): Promise<FireExecution> {
+    const live = this.handlers.get(record.id) ?? {};
+    if (record.handler !== undefined) {
+      if (this.resolveNamedHandler(record.handler) === undefined) {
+        return stopFire("handler_missing");
+      }
+    } else if (
+      (record.hasRunHandler === true || record.hasUntilFn === true) &&
+      live.run === undefined &&
+      live.untilFn === undefined
+    ) {
+      return stopFire("handler_lost_on_restart");
+    }
+
+    if (live.untilFn !== undefined) {
+      try {
+        const done = await live.untilFn(this.buildUntilContext(record));
+        if (done) {
+          return stopFire("until_fn");
+        }
+      } catch (error) {
+        this.logger(
+          `[agent-sdk] reminder "${record.id}" until() failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+
+    if (await this.isSessionBusy(record.channelId, record.continuationToken)) {
+      if (record.busyPolicy === "skipIfBusy") {
+        return { outcome: { kind: "skipped" }, reason: "busy" };
+      }
+      await this.whenSessionIdle(record.channelId, record.continuationToken);
+    }
+
+    let result: ReminderFireResult;
+    let reason: ReminderFireOutcomeReason;
+    let turnStatus: TurnOutcome["status"] | undefined;
+    if (record.handler !== undefined) {
+      const named = this.resolveNamedHandler(record.handler);
+      if (named === undefined) {
+        return stopFire("handler_missing");
+      }
+      result = await named.run(this.buildFireContext(record));
+      reason = runReason(result);
+    } else if (live.run !== undefined) {
+      result = await live.run(this.buildFireContext(record));
+      reason = runReason(result);
+    } else if (record.prompt !== undefined) {
+      const delivery = await this.deliverPromptFire(record);
+      result = delivery.result;
+      reason = delivery.reason;
+      turnStatus = delivery.turnStatus;
+    } else {
+      return stopFire("missing_handler");
+    }
+
+    if (result.action === "stop") {
+      return { outcome: { kind: "stop", reason }, reason };
+    }
+    const reschedule =
+      result.reschedule !== undefined ? toWireReschedule(result.reschedule) : undefined;
+    return {
+      outcome: {
+        kind: result.action === "skip" ? "skipped" : "delivered",
+        reschedule,
+      },
+      reason,
+      turnStatus,
+    };
+  }
+
+  /**
+   * One structured line and one `agent_sdk.reminder.fire_outcome` count per
+   * fire. Emitted through the host OTel meter, the same path hosted v2
+   * exports turn/tool metrics on, so a fire that ends in `stop` is visible
+   * beside the control plane's `timed_work.fire` count.
+   */
+  private recordFireOutcome(
+    record: ReminderRecord,
+    fire: {
+      kind: ReminderExecutionOutcome["kind"] | "error";
+      reason: ReminderFireOutcomeReason;
+      turnStatus?: TurnOutcome["status"];
+      detail?: string;
+    },
+  ): void {
+    this.logger(
+      `[agent-sdk] reminder fire_outcome kind=${fire.kind} reason=${fire.reason}` +
+        ` reminderId=${record.id} purpose=${record.purpose}` +
+        ` channelId=${record.channelId} fireCount=${record.fireCount}` +
+        (fire.turnStatus === undefined ? "" : ` turn=${fire.turnStatus}`) +
+        (fire.detail === undefined ? "" : ` detail=${JSON.stringify(fire.detail)}`),
+    );
+    // Test doubles may omit `host.otel`; the metric is best-effort.
+    const otel: HostOtelApi | undefined = this.engine.host.otel;
+    if (otel === undefined) {
+      return;
+    }
+    try {
+      otel.increment(REMINDER_FIRE_OUTCOME_METRIC, {
+        kind: fire.kind,
+        reason: fire.reason,
+        purpose: record.purpose,
+      });
+    } catch (error) {
+      this.logger(
+        `[agent-sdk] reminder fire_outcome metric failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  private recordFromDescriptor(descriptor: ReminderFireDescriptor): ReminderRecord {
+    const now = new Date().toISOString();
+    return {
+      version: 1,
+      id: descriptor.id,
+      purpose: descriptor.purpose,
+      channelId: descriptor.channelId,
+      continuationToken: descriptor.continuationToken,
+      target: descriptor.target,
+      scheduleKind: descriptor.scheduleKind,
+      scheduleValue: descriptor.scheduleValue,
+      intervalMs: descriptor.intervalMs,
+      prompt: descriptor.prompt,
+      handler: descriptor.handler,
+      args: descriptor.args,
+      hasRunHandler: descriptor.hasRunHandler,
+      hasUntilFn: descriptor.hasUntilFn,
+      untilPrompt: descriptor.untilPrompt,
+      busyPolicy: descriptor.busyPolicy,
+      status: "firing",
+      fireCount: descriptor.fireCount,
+      nextFireAtMs: descriptor.nextFireAtMs,
+      generation: descriptor.generation,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+
+  private armTimer(record: ReminderRecord): void {
+    this.clearTimer(record.id);
+    if (!this.started || record.status !== "armed") return;
+    const nextFireAtMs = Number.isFinite(record.nextFireAtMs) ? record.nextFireAtMs : Date.now();
+    const delay = Math.min(MAX_TIMER_MS, Math.max(0, nextFireAtMs - Date.now()));
+    const timer = setTimeout(() => {
+      void this.fire(record.id).catch(async error => {
+        this.logger(
+          `[agent-sdk] reminder "${record.id}" fire failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        // Keep recurring reminders alive after unexpected throws.
+        // One-shots stay armed so a failed wake can be retried / dispatched.
+        try {
+          const current = await this.getRecord(record.id);
+          if (current === undefined || current.status !== "armed") return;
+          const oneShot = current.scheduleKind === "delay" || current.scheduleKind === "at";
+          if (oneShot) {
+            this.armTimer(current);
+            return;
+          }
+          await this.afterFire(current, "skip");
+        } catch (rescheduleError) {
+          this.logger(
+            `[agent-sdk] reminder "${record.id}" reschedule after failure failed: ${
+              rescheduleError instanceof Error ? rescheduleError.message : String(rescheduleError)
+            }`,
+          );
+        }
+      });
+    }, delay);
+    timer.unref?.();
+    this.timers.set(record.id, timer);
+  }
+
+  private clearTimer(id: string): void {
+    const timer = this.timers.get(id);
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+    }
+  }
+
+  private resolveNamedHandler(name: string): ReminderDefinition | undefined {
+    return this.namedHandlers.get(name);
+  }
+
+  private async fire(
+    id: string,
+    opts: { force?: boolean } = {},
+  ): Promise<{ outcome: "fired" | "noop"; reason?: string }> {
+    if (this.firing.has(id)) {
+      return { outcome: "noop", reason: "already_firing" };
+    }
+    this.firing.add(id);
+    try {
+      const record = await this.getRecord(id);
+      if (record === undefined || record.status !== "armed") {
+        this.clearTimer(id);
+        return { outcome: "noop", reason: "not_armed" };
+      }
+
+      if (!opts.force && record.nextFireAtMs > Date.now() + 50) {
+        // Spurious early wake — re-arm.
+        this.armTimer(record);
+        return { outcome: "noop", reason: "not_due" };
+      }
+
+      const live = this.handlers.get(id) ?? {};
+      if (record.handler !== undefined) {
+        if (this.resolveNamedHandler(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          return { outcome: "noop", reason: "handler_missing" };
+        }
+      } else if (
+        (record.hasRunHandler === true || record.hasUntilFn === true) &&
+        live.run === undefined &&
+        live.untilFn === undefined
+      ) {
+        await this.disarm(record, "handler_lost_on_restart");
+        return { outcome: "noop", reason: "handler_lost_on_restart" };
+      }
+
+      const untilCtx = this.buildUntilContext(record);
+
+      if (live.untilFn !== undefined) {
+        try {
+          const done = await live.untilFn(untilCtx);
+          if (done) {
+            await this.disarm(record, "until_fn");
+            return { outcome: "fired", reason: "until_fn" };
+          }
+        } catch (error) {
+          this.logger(
+            `[agent-sdk] reminder "${id}" until() failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      }
+
+      if (await this.isSessionBusy(record.channelId, record.continuationToken)) {
+        if (record.busyPolicy === "skipIfBusy") {
+          await this.afterFire(record, "skip");
+          this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) skipped: session busy`);
+          return { outcome: "fired", reason: "skipped_busy" };
+        }
+        await this.whenSessionIdle(record.channelId, record.continuationToken);
+        const still = await this.getRecord(id);
+        if (still === undefined || still.status !== "armed") {
+          return { outcome: "noop", reason: "disarmed_while_waiting" };
+        }
+      }
+
+      let result: ReminderFireResult;
+      if (record.handler !== undefined) {
+        const named = this.resolveNamedHandler(record.handler);
+        if (named === undefined) {
+          await this.disarm(record, "handler_missing");
+          return { outcome: "noop", reason: "handler_missing" };
+        }
+        result = await named.run(this.buildFireContext(record));
+      } else if (live.run !== undefined) {
+        result = await live.run(this.buildFireContext(record));
+      } else if (record.prompt !== undefined) {
+        result = await this.deliverPrompt(record);
+      } else {
+        await this.disarm(record, "missing_handler");
+        return { outcome: "noop", reason: "missing_handler" };
+      }
+
+      // Cancel / disarm during the handler must win over reschedule.
+      const latest = await this.getRecord(id);
+      if (result.action === "stop") {
+        if (latest !== undefined && latest.status === "armed") {
+          await this.disarm(latest, "run_stop");
+          this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) disarmed: run_stop`);
+          return { outcome: "fired", reason: "run_stop" };
+        }
+        return {
+          outcome: "fired",
+          reason: latest?.disarmReason ?? "run_stop",
+        };
+      }
+      if (latest === undefined || latest.status !== "armed") {
+        return { outcome: "noop", reason: "disarmed_during_fire" };
+      }
+
+      if (result.action === "skip") {
+        await this.afterFire(latest, "skip", result.reschedule);
+        this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) skipped`);
+        return { outcome: "fired", reason: "skipped" };
+      }
+      await this.afterFire(latest, "delivered", result.reschedule);
+      this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) fired`);
+      return { outcome: "fired", reason: "delivered" };
+    } finally {
+      this.firing.delete(id);
+    }
+  }
+
+  private async isSessionBusy(channelId: string, continuationToken: string): Promise<boolean> {
+    const existing = await this.engine.sessions.findByContinuation(channelId, continuationToken);
+    if (existing === undefined) return false;
+    return this.engine.isTurnRunning(existing.sessionId);
+  }
+
+  private whenSessionIdle(channelId: string, continuationToken: string): Promise<void> {
+    const sessionKey = `${channelId}:${continuationToken}`;
+    const existing = this.idleGates.get(sessionKey);
+    if (existing !== undefined) return existing;
+
+    const gate = (async () => {
+      const session = await this.engine.sessions.findByContinuation(channelId, continuationToken);
+      if (session === undefined) return;
+      await this.engine.waitForCompletion(session.sessionId);
+    })().finally(() => {
+      this.idleGates.delete(sessionKey);
+    });
+    this.idleGates.set(sessionKey, gate);
+    return gate;
+  }
+
+  /**
+   * Follow-ups must use the bound session's principal. If the session is gone,
+   * disarm rather than creating a fresh APP_AUTH conversation.
+   */
+  private async resolveFollowupAuth(
+    channelId: string,
+    continuationToken: string,
+  ): Promise<AuthContext | null | undefined> {
+    const existing = await this.engine.sessions.findByContinuation(channelId, continuationToken);
+    if (existing !== undefined) {
+      return existing.auth;
+    }
+    return undefined;
+  }
+
+  private async deliverPrompt(record: ReminderRecord): Promise<ReminderFireResult> {
+    return (await this.deliverPromptFire(record)).result;
+  }
+
+  /**
+   * Where a prompt fire joins. The pod's own store first; on a hosted guest
+   * the durable mirror next, because the pod that armed the reminder is
+   * usually gone and the session lives only in storage. A restored session
+   * keeps its own principal (channel admissions may carry a sender), so the
+   * fire joins under that, never under {@link ReminderHostedGuestOptions.fireAuth}.
+   */
+  private async resolveFollowupTarget(record: ReminderRecord): Promise<FollowupTarget> {
+    const local = await this.resolveFollowupAuth(record.channelId, record.continuationToken);
+    if (local !== undefined) {
+      return { auth: local, reached: "session_joined" };
+    }
+    if (this.hostedGuest === undefined) {
+      return { auth: undefined, reached: "session_gone" };
+    }
+    // Materializes the durable record locally; a storage error propagates
+    // and the hosted admission retries the fire.
+    const restored = await this.engine.hasContinuationSession(
+      record.channelId,
+      record.continuationToken,
+    );
+    if (!restored) {
+      return { auth: undefined, reached: "session_gone" };
+    }
+    const auth = await this.resolveFollowupAuth(record.channelId, record.continuationToken);
+    return auth === undefined
+      ? { auth: undefined, reached: "session_unreadable" }
+      : { auth, reached: "session_restored" };
+  }
+
+  private async deliverPromptFire(record: ReminderRecord): Promise<PromptDelivery> {
+    const target = await this.resolveFollowupTarget(record);
+    if (target.auth !== undefined) {
+      return this.promptDelivery(record, target.auth, target.reached);
+    }
+    if (target.reached === "session_unreadable") {
+      this.logger(
+        `[agent-sdk] reminder "${record.id}" (${record.purpose}) durable session did not materialize locally; not opening a new one`,
+      );
+      return { result: { action: "stop" }, reason: "session_gone" };
+    }
+    if (
+      this.hostedGuest !== undefined &&
+      this.channelUsesControlPlaneContinuation(record.channelId)
+    ) {
+      // No session on this pod and none in durable storage. Open one on the
+      // stored key the way an inbound event on a fresh key does, instead of
+      // consuming the fire with no turn.
+      const fireAuth = this.hostedGuest.fireAuth();
+      if (fireAuth === undefined) {
+        return {
+          result: {
+            action: "skip",
+            reschedule: { delay: REMINDER_SESSION_OPEN_RETRY_DELAY },
+          },
+          reason: "session_gone",
+        };
+      }
+      try {
+        return await this.promptDelivery(record, fireAuth, "session_opened");
+      } catch (error) {
+        if (!(error instanceof SessionAuthError)) {
+          throw error;
+        }
+        // A session landed on this key under another principal between the
+        // lookup and the send. That does not change on retry, so stop
+        // rather than let the control plane re-admit until its attempt cap.
+        this.logger(
+          `[agent-sdk] reminder "${record.id}" (${record.purpose}) cannot join session on its continuation: ${error.message}`,
+        );
+        return { result: { action: "stop" }, reason: "session_gone" };
+      }
+    }
+    // Under CP protocol, return stop and let the CP apply/CAS; do not
+    // mutate authoritative status from the guest mid-fire.
+    if (!this.usesControlPlaneProtocol) {
+      await this.disarm(record, "session_gone");
+    }
+    return { result: { action: "stop" }, reason: "session_gone" };
+  }
+
+  private async promptDelivery(
+    record: ReminderRecord,
+    auth: AuthContext | null,
+    delivered: Extract<
+      ReminderFireOutcomeReason,
+      "session_joined" | "session_restored" | "session_opened"
+    >,
+  ): Promise<PromptDelivery> {
+    const settle: FollowupSettle = {};
+    const result = await this.sendFollowup(record, buildFirePrompt(record), auth, settle);
+    return {
+      result,
+      reason: result.action === "skip" ? (settle.skipReason ?? "busy") : delivered,
+      turnStatus: settle.turnStatus,
+    };
+  }
+
+  /**
+   * Join the reminder's existing session. Control-plane (`/v2`) channels
+   * refuse authored `continuationToken`; pass the stored key as
+   * {@link EngineSendOptions.mailboxContinuation} so the engine reuses the
+   * CP-selected identity without channel admission.
+   */
+  private followupSendOptions(record: ReminderRecord, auth: AuthContext | null): EngineSendOptions {
+    if (this.channelUsesControlPlaneContinuation(record.channelId)) {
+      return {
+        auth,
+        mailboxContinuation: { key: record.continuationToken },
+      };
+    }
+    return {
+      auth,
+      continuationToken: record.continuationToken,
+    };
+  }
+
+  private channelUsesControlPlaneContinuation(channelId: string): boolean {
+    const project = this.engine.project;
+    // Test doubles may omit `project`; keep the legacy continuationToken path.
+    if (project === undefined) {
+      return false;
+    }
+    const identity =
+      channelId === HTTP_CHANNEL_ID
+        ? httpContinuationIdentity(project.httpChannel)
+        : channelContinuationIdentity(
+            project.channels.find(channel => channel.id === channelId)?.definition,
+          );
+    return continuationSource(identity) === "control-plane";
+  }
+
+  /**
+   * Local and v1 track the turn in the background: the process outlives the
+   * fire. A hosted v2 guest waits for the turn and its durable writes first,
+   * because the control plane may stop the pod as soon as the fire's
+   * outcome is applied, and `delivered` must mean the turn ran.
+   */
+  private async settleFollowup(
+    session: ChannelSession,
+    settle: FollowupSettle | undefined,
+  ): Promise<void> {
+    const completion = this.engine.waitForCompletion(session.id);
+    if (this.hostedGuest === undefined) {
+      this.engine.trackBackground(completion);
+      return;
+    }
+    const outcome = await completion;
+    await this.engine.drainSessionDurability(session.id);
+    if (settle !== undefined) {
+      settle.turnStatus = outcome.status;
+    }
+  }
+
+  private async sendFollowup(
+    record: ReminderRecord,
+    message: string,
+    auth: AuthContext | null,
+    settle?: FollowupSettle,
+    extra?: ReminderFollowupOptions,
+  ): Promise<ReminderFireResult> {
+    const sendOptions: EngineSendOptions = {
+      ...this.followupSendOptions(record, auth),
+      state: extra?.state,
+      refreshState: extra?.refreshState,
+      title: extra?.title,
+      clearCloudOverride: extra?.clearCloudOverride,
+    };
+    try {
+      const session = await this.engine.send(record.channelId, message, sendOptions);
+      await this.settleFollowup(session, settle);
+      return { action: "delivered" };
+    } catch (error) {
+      if (error instanceof SessionBusyError) {
+        if (record.busyPolicy === "skipIfBusy") {
+          if (settle !== undefined) {
+            settle.skipReason = "busy";
+          }
+          return { action: "skip" };
+        }
+        await this.whenSessionIdle(record.channelId, record.continuationToken);
+        try {
+          const session = await this.engine.send(record.channelId, message, sendOptions);
+          await this.settleFollowup(session, settle);
+          return { action: "delivered" };
+        } catch (retryError) {
+          this.logger(
+            `[agent-sdk] reminder "${record.id}" followup failed after wait: ${
+              retryError instanceof Error ? retryError.message : String(retryError)
+            }`,
+          );
+          if (settle !== undefined) {
+            settle.skipReason = "followup_failed";
+          }
+          return { action: "skip" };
+        }
+      }
+      throw error;
+    }
+  }
+
+  private buildFireContext(record: ReminderRecord): ReminderFireContext {
+    const self = this;
+    return {
+      id: record.id,
+      purpose: record.purpose,
+      fireCount: record.fireCount,
+      target: {
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        ...(record.target ?? {}),
+      },
+      args: record.args ?? {},
+      host: this.engine.host,
+      mcp: this.engine.host.mcp,
+      appAuth: APP_AUTH,
+      artifacts: this.engine.artifacts,
+      async followup(args: { message: string } & ReminderFollowupOptions) {
+        const target = await self.resolveFollowupTarget(record);
+        let auth = target.auth;
+        // `openAuth` opens only when nothing exists anywhere: an unreadable
+        // durable session must not be shadowed by a second one on the same
+        // key (prompt-fire parity).
+        if (
+          auth === undefined &&
+          target.reached === "session_gone" &&
+          args.openAuth !== undefined
+        ) {
+          auth = args.openAuth;
+        }
+        if (auth === undefined) {
+          // Under the CP protocol the guest never writes reminder status;
+          // the fire's `stop` outcome carries the reason instead.
+          if (!self.usesControlPlaneProtocol) {
+            await self.disarm(record, "session_gone");
+          }
+          throw new Error(`Reminder "${record.id}" followup: session gone for continuation`);
+        }
+        const result = await self.sendFollowup(record, args.message, auth, undefined, args);
+        if (result.action === "skip") {
+          throw new Error(`Reminder "${record.id}" followup skipped: session busy`);
+        }
+        const existing = await self.engine.sessions.findByContinuation(
+          record.channelId,
+          record.continuationToken,
+        );
+        if (existing === undefined) {
+          throw new Error(`Reminder "${record.id}" followup: session not found for continuation`);
+        }
+        const session = await self.engine.getChannelSession(record.channelId, existing.sessionId);
+        if (session === null) {
+          throw new Error(`Reminder "${record.id}" followup: channel session missing`);
+        }
+        return session;
+      },
+      async cancel(reason = "handler_cancel") {
+        await self.cancel(record.id, reason);
+      },
+    };
+  }
+
+  private buildUntilContext(record: ReminderRecord): ReminderUntilContext {
+    return {
+      id: record.id,
+      purpose: record.purpose,
+      fireCount: record.fireCount,
+      target: {
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        ...(record.target ?? {}),
+      },
+      host: this.engine.host,
+      mcp: this.engine.host.mcp,
+    };
+  }
+
+  private async disarm(record: ReminderRecord, reason: string): Promise<void> {
+    this.clearTimer(record.id);
+    const updated: ReminderRecord = {
+      ...record,
+      status: "disarmed",
+      disarmReason: reason,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.persist(updated);
+    this.handlers.delete(record.id);
+  }
+
+  private async afterFire(
+    record: ReminderRecord,
+    _outcome: "skip" | "delivered",
+    reschedule?: { delay?: string | number; at?: Date | string },
+  ): Promise<void> {
+    const current = await this.getRecord(record.id);
+    if (current === undefined || current.status !== "armed") {
+      return;
+    }
+
+    const now = Date.now();
+    const oneShot = current.scheduleKind === "delay" || current.scheduleKind === "at";
+
+    if (reschedule !== undefined) {
+      let nextFireAtMs: number;
+      if (reschedule.delay !== undefined) {
+        nextFireAtMs = now + parseDuration(reschedule.delay);
+      } else if (reschedule.at !== undefined) {
+        nextFireAtMs =
+          reschedule.at instanceof Date
+            ? reschedule.at.getTime()
+            : Date.parse(String(reschedule.at));
+        if (!Number.isFinite(nextFireAtMs)) {
+          throw new ReminderValidationError(`Invalid reschedule.at for reminder "${current.id}"`);
+        }
+      } else {
+        throw new ReminderValidationError(
+          `reschedule requires delay or at for reminder "${current.id}"`,
+        );
+      }
+      const updated: ReminderRecord = {
+        ...current,
+        fireCount: current.fireCount + 1,
+        nextFireAtMs,
+        // Promote to one-shot-from-now semantics if they rescheduled
+        scheduleKind: reschedule.delay !== undefined ? "delay" : "at",
+        scheduleValue:
+          reschedule.delay !== undefined ? String(reschedule.delay) : String(reschedule.at),
+        updatedAt: new Date().toISOString(),
+      };
+      await this.persist(updated);
+      if (this.platformTimers === undefined) {
+        this.armTimer(updated);
+      }
+      return;
+    }
+
+    if (oneShot) {
+      this.clearTimer(current.id);
+      const updated: ReminderRecord = {
+        ...current,
+        fireCount: current.fireCount + 1,
+        status: "completed",
+        disarmReason: "one_shot_complete",
+        updatedAt: new Date().toISOString(),
+      };
+      await this.persist(updated);
+      this.handlers.delete(current.id);
+      return;
+    }
+
+    // Recurring
+    let nextFireAtMs: number;
+    if (current.scheduleKind === "every" && current.intervalMs !== undefined) {
+      nextFireAtMs = now + current.intervalMs;
+    } else if (current.scheduleKind === "cron") {
+      nextFireAtMs = nextCronFireMs(current.scheduleValue, now);
+    } else {
+      throw new Error(
+        `Reminder "${current.id}" has recurring status with scheduleKind=${current.scheduleKind}`,
+      );
+    }
+    const updated: ReminderRecord = {
+      ...current,
+      fireCount: current.fireCount + 1,
+      nextFireAtMs,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.persist(updated);
+    if (this.platformTimers === undefined) {
+      this.armTimer(updated);
+    }
+  }
+}
+
+// Re-export store record type for tests
+export type { ReminderRecord } from "./reminder-store.js";