@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/reminder-runner.ts

@@ -1,1559 +0,0 @@
-/**
- * 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";