dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/subsystems/schedule.md

@@ -2,440 +2,140 @@
 
 English | [中文](schedule.zh.md)
 
-Schedule stores reminders independently of Session activation and delivers them to their original Session. This page records the durable and model-facing types from [`types.ts`](../../packages/schedule/schedule/src/types.ts); the [package README](../../packages/schedule/schedule/README.md) owns composition and reminder framing.
-
-## Durable records
-
-`ScheduleId` is a globally unique [branded id](core.md#branded-ids). The version-1 `schedule` storage domain owns a `tasks` table whose entries bind a `ScheduleRecord` to its original `sessionId`, with stored `status: 'active' | 'inactive'` and optional `lastDelivery`. Records lacking status normalize to `active` without scanning or recreating historical Sessions. Creation canonicalizes the target into RFC 3339 UTC `scheduledAt`; `after` retains the submitted delay, `every` retains its fixed interval, `daily` and `weekly` retain normalized local `time` and their explicit `timeZone`, and `cron` retains its canonical five-field `expression` and explicit `timeZone`. Daily, weekly, and cron decoding preserve the committed instant and stored zone spelling. The stored task record declares a required `title`, the short name the task surfaces show; creation requires it and never derives it from the instruction. No stored record may omit its title: a record whose `title` is missing, blank after trimming, untrimmed, or longer than 120 characters fails durable decoding with `ScheduleLogError`, and the schedule domain declares no backup-and-skip policy, so one such stored task rejects the whole domain open instead of being dropped. Only explicit deletion removes a task; previously physically deleted tasks are not restored or fabricated.
-
-```ts type-equiv
-/** Durable one-shot reminder created from a positive delay. */
-interface AfterScheduleRecord {
-  /** Globally unique task identity. */
-  readonly id: ScheduleId
-  /** Rule discriminator for a delayed one-shot reminder. */
-  readonly kind: 'after'
-  /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
-  readonly title: string
-  /** Trimmed reminder content supplied at creation. */
-  readonly prompt: string
-  /** Positive safe-integer delay accepted at creation. */
-  readonly afterSeconds: number
-  /** Four-digit-year RFC 3339 UTC target. */
-  readonly scheduledAt: string
-}
-```
+Schedule stores Host tasks independently of Session activation. One management API addresses tasks by id, and one evaluator handles seven authoritative timing kinds: `after`, `at`, `every`, `daily`, `weekly`, `cron`, and `rrule`. Targets reuse an existing Session, create one Session and reuse it, or create a Session for each delivery. The [package README](../../packages/schedule/schedule/README.md) owns composition and reminder framing; [`types.ts`](../../packages/schedule/schedule/src/types.ts) owns the complete value and request types.
 
-```ts type-equiv
-/** Durable one-shot reminder created from an absolute instant. */
-interface AtScheduleRecord {
-  /** Globally unique task identity. */
-  readonly id: ScheduleId
-  /** Rule discriminator for an absolute one-shot reminder. */
-  readonly kind: 'at'
-  /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
-  readonly title: string
-  /** Trimmed reminder content supplied at creation. */
-  readonly prompt: string
-  /** Four-digit-year RFC 3339 UTC target. */
-  readonly scheduledAt: string
-}
-```
+<a id="durable-tasks"></a>
+## Durable tasks
 
-```ts type-equiv
-/** Durable fixed-rate reminder aligned to creation or its most recent interval edit. */
-interface EveryScheduleRecord {
-  /** Globally unique task identity. */
-  readonly id: ScheduleId
-  /** Rule discriminator for a fixed-rate recurring reminder. */
-  readonly kind: 'every'
-  /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
-  readonly title: string
-  /** Trimmed reminder content supplied at creation. */
-  readonly prompt: string
-  /** Fixed safe-integer interval, never below one minute. */
-  readonly everySeconds: number
-  /** Next anchor-aligned occurrence while active, or final occurrence when inactive. */
-  readonly scheduledAt: string
-}
-```
+The plugin README owns the current [v2 task schema, v1 defaults, and persisted JSON example](../../packages/schedule/schedule/README.md#storage-format). The domain retains its name, routing, and whole-unit layout. All seven timing kinds remain authoritative; normalization preserves committed occurrences and does not convert Cron into RRULE.
 
-```ts type-equiv
-/** Durable daily wall-clock reminder; gaps skip a date and overlaps use the earlier instant. */
-interface DailyScheduleRecord {
-  /** Globally unique task identity. */
-  readonly id: ScheduleId
-  /** Rule discriminator for a daily wall-clock reminder. */
-  readonly kind: 'daily'
-  /** Required stored task name; already trimmed, non-empty, and at most 120 characters. */
-  readonly title: string
-  /** Trimmed reminder content supplied at creation. */
-  readonly prompt: string
-  /** Local time normalized to HH:mm:ss.SSS. */
-  readonly time: string
-  /** Explicit IANA zone; equivalent timing edits retain the stored spelling. */
-  readonly timeZone: string
-  /** Committed next UTC instant while active, or final occurrence when inactive. */
-  readonly scheduledAt: string
-}
-```
+Malformed storage, invalid rows, mismatched task keys, and unsupported versions reject before tasks activate. Failed opening leaves the medium unchanged. An absent file starts empty. Missing target Sessions remain visible in management; reading a task never activates its Session.
 
-```ts type-equiv
-/** One-shot task variants. */
-type OneShotScheduleRecord = AfterScheduleRecord | AtScheduleRecord
-```
+<a id="storage-versioning"></a>
+## Storage versioning
 
-```ts type-equiv
-/** Recurring Host task variants. */
-type RecurringScheduleRecord = EveryScheduleRecord | DailyScheduleRecord | WeeklyScheduleRecord | CronScheduleRecord
-```
+The README defines [when tasks upgrade](../../packages/schedule/schedule/README.md#storage-format), SQLite's unchanged physical schema, mutation costs, and a future compatible v3. `compatibleVersions` admits old unit stamps for current decoding; normal edits and delivery persist current rows. Reads leave storage unchanged. The shared [domain version policy](storage.md#domain-versioning) applies to both JSON and SQLite.
 
-```ts type-equiv
-/** Reminder rule and target, stored with its original Session binding. */
-type ScheduleRecord = OneShotScheduleRecord | RecurringScheduleRecord
-```
+<a id="recurrence-rules"></a>
+## Recurrence rules
 
-## Absolute-time input
+[`dsh-util-time`](../../packages/util/time/README.md) owns reusable `Cron` and `RRule` parsing and bounded occurrence arithmetic. Both parsed values expose their authoritative expression and zone, `next(after)`, and `resolve(scheduledAt, acceptedAt)`. Parsers return an accepted value or a rejection reason; Schedule maps reasons to its own input errors and owns record validation, admission limits, persistence, and dispatch.
 
-The `at` selector is either a strict offset-bearing RFC 3339 string or an exact local-calendar object. The local form keeps its interpretation explicit at the tool boundary:
-
-```ts type-equiv
-/** Structured local-calendar input accepted by creation and timing edits. */
-interface LocalAtInput {
-  /** Four-digit ISO calendar date. */
-  readonly date: string
-  /** Local wall-clock time with optional one-to-three digit milliseconds. */
-  readonly time: string
-  /** Explicit UTC or IANA Area/Location zone. */
-  readonly time_zone: string
-}
-```
+Every stored `scheduledAt` is a canonical RFC 3339 UTC instant with millisecond precision and a year from 0001 through 9999. Decoding never recalculates it from current zone data. Latest-only catch-up preserves that committed floor, delivers the latest due occurrence once, and commits the first future occurrence. Exhaustion leaves the task stored as `ended`.
 
-```ts type-equiv
-/** Absolute selector accepted by creation and timing edits. */
-type AtInput = string | LocalAtInput
-```
+| Kind | Authoritative timing |
+|---|---|
+| `after` | Positive integer `afterSeconds` and the committed one-shot UTC target. |
+| `at` | Committed one-shot UTC target. Input accepts an explicit-offset instant or a local date, time, and explicit zone. |
+| `every` | Integer `everySeconds` of at least 60; occurrences stay aligned to their committed interval anchor. |
+| `daily` | Local `time` as `HH:mm:ss.SSS` and explicit `timeZone`. |
+| `weekly` | Daily fields plus a nonempty, unique, ascending ISO `weekdays` set, Monday 1 through Sunday 7. |
+| `cron` | Canonical five-field `expression` and explicit `timeZone`. |
+| `rrule` | One normalized `DTSTART` line and one `RRULE` line in `rrule`; `DTSTART` supplies the anchor and zone. |
 
-The shipped Web composition mounts the `schedule` service and the `ui-schedule` task page. The clock reading and the four reminder tools are preset-owned: `standard`, `cordis`, and `ptc` declare `time-context` and `@deepseek-ai/dsh-tool-schedule` together, and `minimal` declares neither. The `tool-subagent` and `tool-subagent-fork` rows in those three presets deny the four tools, and each tool refuses a delegated caller with `subagent_session`, so a delegated child neither sees the tools nor has a call accepted. Time-context tells the model to interpret otherwise-unqualified natural-language dates and times in that request-local zone when the open turn has one unambiguous browser zone; mixed or missing browser-zone records tell the model to ask. That guidance is not a durable Session default: the model must still pass an offset in the string form or `time_zone` in the local form, and Schedule never reads browser, Session, process, or model context.
+Local calendar rules skip missing wall times and choose the earlier instant of an overlap. Fixed intervals retain their elapsed-time meaning. A one-shot delay may be shorter than a minute; the per-task delivery floor still applies after its first delivery.
 
-Schedule rejects invalid offsets and zones, offset-free strings, non-future targets, and local times inside daylight-saving gaps. A daylight-saving overlap chooses its first, earlier instant. Successful creation stores only canonical UTC `scheduledAt`, so replay never depends on ambient time-zone state.
+<a id="absolute-time-input"></a>
+## Absolute-time input
 
-<a id="daily-wall-clock-input"></a>
-## Daily wall-clock input
-
-`daily` is one of the mutually exclusive creation selectors, alongside `after_seconds`, `at`, `every_seconds`, the weekly selector, and the cron selector. For example, `daily: { time: '23:00:00', time_zone: 'Asia/Shanghai' }` selects 23:00 in that zone on each eligible local date. The exact object has no date, offset, or interval field:
-
-```ts type-equiv
-/** Daily local-time selector accepted by creation and timing edits. */
-interface DailyInput {
-  /** Local HH:mm:ss time with optional one-to-three fractional digits. */
-  readonly time: string
-  /** Explicit UTC or IANA Area/Location zone. */
-  readonly time_zone: string
-}
-```
+An `at` selector accepts an RFC 3339 instant with an explicit `Z` or numeric offset, or `{ date, time, time_zone }`. Local dates use `YYYY-MM-DD`; local times use `HH:mm:ss` with optional one-to-three fractional digits. Ambiguous or nonexistent calendar values are validated through the shared time utilities. A new absolute target must be strictly future and representable.
 
-Creation requires `HH:mm:ss` with optional one-to-three fractional digits, rejects leap seconds and `24:00`, canonicalizes the explicit IANA zone, and stores `time` as `HH:mm:ss.SSS`. The first `scheduledAt` is strictly after creation time. A nonexistent local time or entire date is skipped; an overlap selects the earlier instant once per local date. If that earlier instant has passed, the later duplicate is not eligible. Only UTC target years 0001–9999 are constrained; local dates at the UTC range edges may fall in year 0 or 10000.
+<a id="daily-wall-clock-input"></a>
+## Daily and weekly input
 
-A saved next target is a committed UTC instant. The Host decoder and restart preserve that instant without resolving it against time-zone rules again, and valid stored zone aliases remain readable when canonical names change. Subsequent targets use the Host's current IANA data. The next target must be both after the delivery decision and on a local date later than the selected occurrence's date. Creation fails with `time_out_of_range` when no future UTC target is representable.
+Daily input supplies `{ time, time_zone }`; Weekly adds explicit `weekdays`. Creation chooses the first strictly future actual occurrence. Catch-up chooses the latest actual due occurrence and advances to a later matching local date. Equivalent edits retain the stored IANA alias and pinned UTC target, including milliseconds.
 
+<a id="fixed-rate-input-and-catch-up"></a>
 ## Fixed-rate input and catch-up
 
-`every_seconds` is a safe-integer interval of at least 60 seconds, aligned to creation time. It measures elapsed time, not daily wall-clock time: `every_seconds: 86400` cannot substitute for `daily` across offset changes. The protocol provides no shared cooldown or cross-record admission rule; the cron selector described below is wall-clock timing, not a fixed-rate interval.
-
-When the Host starts with an overdue Every, Daily, Weekly, or Cron record, it sends only the latest due occurrence. Every advances to the first target aligned to its current interval anchor after the delivery decision; Daily, Weekly, and Cron follow the local-date rules above and below. Missed occurrences do not accumulate. If no next UTC target is representable, delivery retains the record as inactive with its latest receipt.
-
-One-shots produce individual follow-ups. Recurring records due in the same scan for the same Session share one follow-up rendered by `renderRecurringReminderBatchFraming`, with one latest occurrence per record. The one-minute minimum applies only to fixed-rate intervals; delivery does not wait for the target Agent to become idle.
+Every input supplies `every_seconds`. A new interval starts from acceptance time; a changed interval establishes a new anchor at edit acceptance. An unchanged interval or a name/prompt edit keeps the old anchor. Downtime coalesces missed intervals instead of replaying each occurrence.
 
 <a id="cron-wall-clock-input"></a>
-## Cron wall-clock input
+## Cron input
 
-`cron` is one of the mutually exclusive creation selectors. Its exact object carries only the strict five-field Vixie expression `minute hour day-of-month month day-of-week` and an explicit IANA zone, for example `cron: { expression: '*/15 9-17 * * 1-5', time_zone: 'Asia/Shanghai' }`. The field bounds are:
+Cron input supplies `{ expression, time_zone }`. Its five numeric fields are minute, hour, day-of-month, month, and day-of-week. Supported atoms are `*`, a value, an inclusive range, a star or range step, and comma-separated lists. Sunday accepts 0 or 7 and canonicalizes to 0. Names, macros, a seconds field, and a value followed by a step are rejected.
 
-| Field | Accepted range | Notes |
-|---|---|---|
-| minute | 0-59 | |
-| hour | 0-23 | |
-| day-of-month | 1-31 | |
-| month | 1-12 | |
-| day-of-week | 0-7 | Both `0` and `7` mean Sunday. |
+Cron keeps Vixie day matching: when both day fields are restricted, day-of-month **or** day-of-week may match; when either field starts with `*`, including a stepped star, both matched sets must match. Canonicalization preserves that distinction. Searches are bounded by one 400-year Gregorian cycle and the four-digit UTC range. A rule with no representable future occurrence is refused when armed.
 
-Every field accepts `*`, a single value, an `a-b` range, a `*/n` or `a-b/n` step with `n >= 1`, and a comma-separated list of those forms. Everything else is rejected with `invalid_rule` and a message naming the offending field: `L`, `W`, and `#` operators, `JAN`/`MON` names, `@daily`-style macros, six-field expressions with a seconds field, out-of-range values, inverted ranges, zero steps, and empty fields. Because the dialect has five fields, the smallest interval is one minute; sub-minute scheduling stays unsupported.
+Cron records are never converted into RRULE. Their saved expression and zone remain authoritative through reads, descriptive edits, retargeting, and restart. The Custom editor accepts a five-field Cron expression and exposes its explicit zone selector.
 
-Creation canonicalizes the expression before storing it. Canonicalization expands each field into its matched value set and re-encodes that set deterministically: repeated values collapse, adjacent values and ranges merge, a uniform step is written as `a-b/n` or, for a field that started with `*`, as a star-step (`*` for every value, otherwise the widest star-step walk plus any remaining values), a step of `1` is dropped, and Sunday is written as `0`. A field that did not start with `*` never becomes a star-step. Preserving each field's star flag is what keeps the day-of-month/day-of-week rule below Vixie-faithful across the stored expression. The durable decoder rejects a stored expression that is not canonical.
+<a id="rrule-input"></a>
+## RRULE input
 
-The first target is the first strictly future instant whose local date and time in the zone match. It reuses the Daily and Weekly local-time resolution: a non-existent local time is skipped, and an ambiguous one takes the earlier occurrence once for that date. The committed UTC `scheduledAt` is never recomputed on restart.
+RRULE accepts a bounded RFC 5545 subset, defined by the shared [`rrule.ts` parser](../../packages/util/time/src/rrule.ts). Input has exactly two nonempty content lines: `DTSTART` followed by `RRULE`. The start is a real `YYYYMMDDTHHMMSS` date-time with UTC `Z` or an explicit IANA `TZID`; floating local time, numeric offsets, date-only values, and extra content lines are rejected. The engine uses `rrule` 2.8.1 and supports `MINUTELY`, `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, and `YEARLY`. A one-shot uses `COUNT=1`.
 
-Day-of-month and day-of-week follow Vixie semantics. A field is a star when its text starts with `*`, independently of the values it matches, so `*/1` and `*/2` are stars while `1-31` and `0-7` are restricted. When either field is a star, a local date matches only when both fields match; when neither is a star, it matches when either field matches.
+Only `FREQ`, `INTERVAL`, `COUNT`, `UNTIL`, `WKST`, `BYSECOND`, `BYMINUTE`, `BYHOUR`, `BYDAY`, `BYMONTHDAY`, `BYYEARDAY`, `BYWEEKNO`, `BYMONTH`, and `BYSETPOS` are accepted; names and list values must be unique. `INTERVAL` is a positive safe integer. `WKST` is a weekday from `MO` through `SU` and defaults to `MO`. Numeric lists must fit the parser's ranges. Minute/hour rules accept no `BY` parts. `BYMONTHDAY` and ordinal `BYDAY` require Monthly or Yearly; `BYYEARDAY` and `BYWEEKNO` require Yearly. Ordinal `BYDAY` cannot combine with `BYWEEKNO`, and `BYSETPOS` requires another `BY` part.
 
-Cron decoding preserves the committed instant and the stored zone spelling, and rejects a non-canonical stored expression. Cron belongs only to the current Host `ScheduleRecord`; the frozen historical Session decoder does not admit it.
+Validation precedes enumeration. `SECONDLY`, multiple `BYSECOND` values, and more than 10,080 possible candidates per frequency period are rejected. `COUNT` is 1 through 1,000 and cannot coexist with `UNTIL`; `UNTIL` is an absolute UTC date-time ending in `Z`. Starts and limits use years 0100 through 9999. At most 31 set positions are accepted, each from −366 through −1 or 1 through 366 and within its bounded period. The stricter new-rule authoring profile also rejects `BYSETPOS` when a period has at most one candidate; decoding and resuming an unchanged supported rule use its normal evaluator.
 
-## Historical Session changes
+A nonexistent local `DTSTART` is rejected. Later missing local occurrences are skipped without consuming `COUNT`; overlaps choose the earlier instant. `COUNT` counts each actual occurrence once, including when positive and negative set positions select the same occurrence.
 
-Version-1 `schedule/change` events remain decodable as historical Session data. Their create and fold types use `LegacyScheduleRecord`, which admits only After, At, and Every; Daily, Weekly, and Cron belong only to the current Host `ScheduleRecord`. The Host record decoder is separate from the frozen historical decoder. A create record written before titles existed carries no `title`, so the historical decoder admits that absent member while the Host decoder still requires it. Historical events do not populate the storage domain or schedule delivery. Existing reminders in these events require explicit recreation through `schedule_create`; no implicit Session migration or conversion of old `at` records occurs.
+Custom RRULE text retains its `DTSTART` zone. The model-facing tools continue to teach and accept RRULE; the shared management API accepts each timing kind explicitly.
 
-```ts type-equiv
-/**
- * Frozen Session event and fold vocabulary; daily rules belong only to Host storage.
- *
- * A version-1 event written before titles existed persists no `title` member, so
- * `after`, `at`, and `every` decode without one and stay readable. The Host task
- * record requires the member and never persists a record without it.
- */
-type LegacyScheduleRecord =
-  | LegacyAfterScheduleRecord
-  | LegacyAtScheduleRecord
-  | LegacyEveryScheduleRecord
-```
+<a id="delivery-targets"></a>
+## Delivery targets
 
-```ts type-equiv
-/** Creates one durable reminder record. */
-interface ScheduleCreateChange {
-  readonly version: 1
-  readonly operation: 'create'
-  readonly schedule: LegacyScheduleRecord
-}
-```
+| Target | Delivery behavior |
+|---|---|
+| `session` | Deliver to one existing Session. Arming checks inside the management FIFO that it exists, is not archived, and is not a delegated child. Delivery rechecks archived destinations. |
+| `new_once` | Reserve a Session id before first delivery, create that exact Session when needed, then store `session` and reuse it. Retries and restart keep the reservation. |
+| `new` | Create a Session per delivery. Persist `pendingDelivery.targetSessionId` before creation so a failed attempt retries the same Session. |
 
-```ts type-equiv
-/** Deletes one currently active reminder. */
-interface ScheduleDeleteChange {
-  readonly version: 1
-  readonly operation: 'delete'
-  readonly id: ScheduleId
-}
-```
+An omitted creation target defaults to `new_once`. Adding or replacing a `new` or `new_once` target requires the embedding's Session creation provider. SDK compositions without it reject those requests with `invalid_rule` before saving; existing `session` targets remain available. Creation values `cwd` and `agentPreset` are optional and use Host defaults. A created Session joins the Workspace registered at its directory, if any, and takes the task title while untitled; `new` adds its creation minute in the rule's zone. Join or rename failures are logged without blocking delivery.
 
-```ts type-equiv
-/** Records that one active one-shot reminder entered the durable dispatch history. */
-interface OneShotScheduleDispatchChange {
-  readonly version: 1
-  readonly operation: 'dispatch'
-  readonly id: ScheduleId
-}
-```
+<a id="task-management"></a>
+## Task management
 
-```ts type-equiv
-/** Records one fixed-rate decision and advances directly past missed occurrences. */
-interface EveryScheduleDispatchChange {
-  readonly version: 1
-  readonly operation: 'dispatch'
-  readonly id: ScheduleId
-  /** Wall-clock decision time used to select the latest due occurrence. */
-  readonly acceptedAt: string
-}
-```
+All callers use the same `ScheduleCreateRequest`, `ScheduleCatalogEntry`, `ScheduleTiming`, and `ScheduleEditRequest`. Browser-safe types come from `@deepseek-ai/dsh-schedule/client`. There is no Session-bound management surface or second family of type aliases.
 
-```ts type-equiv
-/** Durable dispatch shapes supported by the current rule set. */
-type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange
-```
-
-```ts type-equiv
-/** Strict version-1 durable Schedule mutation union. */
-type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
-```
-
-The historical decoder and fold reject unknown versions, extra fields, reused ids, and invalid transitions. The event remains indexed in the [persistence catalog](../persistence-catalog.md#schedulechange--log-only). Session history is not the authority for active tasks.
-
-## Active views and management
-
-Tool values combine the stored record with timing derived from the current wall clock. The Host restores the original Session when delivery requires it; listing and deleting tasks do not activate that Session.
-
-```ts type-equiv
-/** Current delivery timing derived from the durable record and wall clock. */
-type ScheduleState = 'scheduled' | 'overdue'
-```
-
-```ts type-equiv
-/** Host-driven delivery resumes the original Session when needed. */
-type ScheduleDeliveryMode = 'host'
-```
-
-```ts type-equiv
-/** Complete model-facing view of one active reminder. */
-type ScheduleView = ScheduleRecord & {
-  /** Whether the target remains in the future. */
-  readonly state: ScheduleState
-  /** Reminder delivery never leaves the owning session. */
-  readonly deliveryMode: ScheduleDeliveryMode
-}
-```
+| Operation | Behavior |
+|---|---|
+| `create(request, actorSessionId?, signal?)` | Allocate the id and store title, prompt, typed `timing`, and optional target. |
+| `list(request?)` | Read a page; default 100, maximum 500, optional `active` filter and nonnegative `offset`. |
+| `catalog()` / `view({ id })` | Read all tasks without a page limit, or one task. |
+| `history({ id, limit, before? })` | Read saved deliveries without Session activation; limit is 1 through 100. |
+| `edit(request, actorSessionId?, signal?)` | Apply an `update` patch or `delete` atomically by id. |
+| `deleteInactive()` | Remove only `ended` tasks in one batch, preserve active and paused tasks, and return `{ deleted }`. An empty set performs no write. |
+| `run({ id }, signal?)` | Deliver now through normal admission without changing the scheduled occurrence or lifecycle. |
+| `deliveryLimits()` | Read the configured minimum spacing for `new` targets. |
 
-The [tool catalog](../tool-catalog.md#deepseek-aidsh-tool-schedule) owns schemas for `schedule_create`, `schedule_list`, `schedule_delete`, and `schedule_update`, which [`@deepseek-ai/dsh-tool-schedule`](../../packages/schedule/tool-schedule/README.md) contributes to each preset that mounts it; the Host service owns storage and delivery. Create, delete, and update acknowledge the storage-domain write. A Host-wide queue serializes these mutations against due delivery; deleting a task does not remove an already queued message. Model tools address the current Session, while the shared Host create, list, update, and delete methods accept an explicit Session binding. `create` and `update` refuse a Session a delegated child owns with `subagent_session` when its delegation depth is above zero, and delivery cannot reach such a Session. The four model tools refuse a delegated caller in the tool layer, while `list`, `catalog`, `history`, and `delete` still serve that Session. Creation requires a `title` that must be non-empty after trimming and at most 120 characters; a missing, blank, or over-long title is rejected with `invalid_prompt`, and creation never derives one from the instruction. Create and list views carry the stored `title` alongside the instruction, and a stored record whose `title` is missing or invalid is rejected at decode.
-
-```ts type-equiv
-/** Reminder creation selector, shared by the model consumer and Host service. */
-interface ScheduleCreateRequest {
-  /** Non-empty reminder text. */
-  prompt: string
-  /** Required task name of at most 120 characters, non-empty after trimming; names the card, detail heading, and task lists. */
-  title: string
-  /** Relative one-shot delay in seconds. */
-  after_seconds?: number
-  /** Absolute one-shot target. */
-  at?: AtInput
-  /** Fixed recurrence interval in seconds. */
-  every_seconds?: number
-  /** Daily wall-clock time in an explicit IANA zone. */
-  daily?: DailyInput
-  /** Weekly wall-clock time and explicit ISO weekday set in an IANA zone. */
-  weekly?: WeeklyInput
-  /** Five-field cron expression evaluated in an explicit IANA zone. */
-  cron?: CronInput
-}
-```
-
-```ts type-equiv
-/** Session-scoped task list, without Agent activation. */
-interface ScheduleListRequest {
-  /** Original Session binding. */
-  sessionId: SessionId
-}
-```
-
-```ts type-equiv
-/** Delete request identifying a task within its original Session binding. */
-interface ScheduleDeleteRequest extends ScheduleListRequest {
-  /** Task to remove. */
-  id: ScheduleId
-}
-```
-
-```ts type-equiv
-/** Successful `schedule_delete` value, including the non-mutating not-found result. */
-type ScheduleDeleteResult =
-  | { readonly id: ScheduleId; readonly deleted: true }
-  | { readonly id: ScheduleId; readonly deleted: false; readonly code: 'schedule_not_found' }
-```
-
-## Web catalog
-
-The Remote `schedule.catalog()` method returns active and inactive Host tasks with their original Session bindings, ordered by `scheduledAt` ascending and then lexicographically by `id`. It reads only the Schedule domain, without activating Sessions or reading their history. Browser consumers receive this browser-safe type:
+Remote routes expose `create`, `list`, `catalog`, `view`, `history`, `edit`, `deleteInactive`, `run`, and `deliveryLimits`; the transport wrappers delegate to the same management methods. Remote validation failures use `schedule/input-invalid` with the Schedule input code. Native callers receive `ScheduleInputError`.
 
-```ts type-equiv
-/** Durable Session inbox delivery acknowledgment, not model execution completion. */
-interface ScheduleDeliveryReceipt {
-  /** Canonical UTC target of the delivered occurrence. */
-  readonly scheduledAt: string
-  /** Canonical UTC time sampled after Session persistence acknowledged delivery. */
-  readonly deliveredAt: string
-  /** Identity of the delivered message, shared by tasks in one recurring batch. */
-  readonly messageId: MessageId
-}
-```
-
-```ts type-equiv
-/** Browser-safe retained reminder with its original Session binding. */
-type ScheduleCatalogEntry = ScheduleRecord & {
-  /** Session receiving this reminder when it becomes due. */
-  readonly sessionId: SessionId
-  /** Inactive reminders remain visible but never schedule another delivery. */
-  readonly status: 'active' | 'inactive'
-  /** Most recent durably acknowledged inbox delivery, when available. */
-  readonly lastDelivery?: ScheduleDeliveryReceipt
-}
-```
+A successful nonempty `deleteInactive` batch emits `schedule/changed` for readers to refresh; it queues no Agent notices. A rejected batch also emits that event so readers discard stale state. A normal failure preserves all rows; an `unknown-state` failure can have removed rows and quarantines the domain until reopening. The failed call rejects instead of reporting a deletion count.
 
-The Remote `schedule.list({ sessionId })`, model `schedule_list`, and Session-header catalog return only active tasks. A model view's derived timing `state` remains distinct from stored lifecycle `status`. Deletion uses `schedule.delete({ sessionId, id })` with the entry's original binding; a mismatched binding returns not found. Model tools supply the current Agent's Session, whereas the global user interface supplies the selected task's binding. The binding check alone does not establish caller authorization. The payload-free `schedule/changed` event invalidates client lists; reconnecting clients fetch current state again.
+An update may replace title, prompt, typed timing, target, or activity. Omitted fields keep their values. A changed rule or explicit resume computes a future occurrence at FIFO acceptance; equivalent timing and descriptive edits keep the committed target. A delivered one-shot needs new future timing to resume. Retargeting does not require converting its timing kind.
 
-The shipped Web composition mounts `ui-schedule` with the Host capability. The [client package](../../packages/client/ui-schedule/README.md) owns the catalog, empty state, and deletion controls. The page separately filters all, active, and inactive tasks, retains inactive details and an original-Session control in the detail tab strip, and requires explicit confirmed deletion. The Rules and Records tabs separate task settings from lazily paged saved receipts. Neither a receipt nor inactive status confirms model execution.
+`expectedUpdatedAt` is an optional optimistic comparison. A string compares with the saved revision; explicit `null` compares with an absent revision. Mismatch returns `schedule_conflict`. An edit of a row without a revision creates one; later revisions advance monotonically even if the clock rolls back. Cancellation is checked before the write begins, and a started durable write is not rolled back.
 
+<a id="timing-edits"></a>
 ## Timing edits
 
-`schedule.update({ sessionId, id, expected, change })` edits an active task without activating its Session. `expected` is the complete observed `ScheduleRecord`, not a catalog entry with extra metadata. The Host compares it to the current record inside the same FIFO used by dispatch and deletion. Normal delivery can advance the target during editing; that stale snapshot returns `schedule_conflict` instead of overwriting the current rule. Missing or mismatched bindings return `schedule_not_found`, and inactive tasks return `schedule_ended`.
-
-```ts type-equiv
-/** Timing-only edit; it may select a different recurrence kind than the stored record, and one-shot targets use an absolute `at`. */
-type ScheduleTimingChange =
-  | { readonly kind: 'at'; readonly at: AtInput }
-  | { readonly kind: 'every'; readonly every_seconds: number }
-  | { readonly kind: 'daily'; readonly daily: DailyInput }
-  | { readonly kind: 'weekly'; readonly weekly: WeeklyInput }
-  | { readonly kind: 'cron'; readonly cron: CronInput }
-```
-
-```ts type-equiv
-/** Compare-and-update request within the original Session binding. */
-interface ScheduleUpdateRequest extends ScheduleDeleteRequest, ScheduleUpdateContent {
-  /** Complete record observed when editing began, including the committed target. */
-  readonly expected: ScheduleRecord
-  /** New timing; its kind may differ from the stored record's kind, and an omitted value keeps the committed target. */
-  readonly change?: ScheduleTimingChange
-}
-```
-
-```ts type-equiv
-/** Successful current record, non-mutating lookup/conflict failure, or invalid name/instruction/timing. */
-type ScheduleUpdateResult =
-  | { readonly id: ScheduleId; readonly updated: boolean; readonly record: ScheduleRecord }
-  | ScheduleUpdateMiss
-  | ScheduleToolError
-```
-
-A changed Daily rule computes its first strictly future target using the saved local time and zone semantics. A changed Cron rule canonicalizes its expression and computes its first strictly future target under the same local-date, gap, and earlier-overlap rules. A changed Every interval starts a new anchor at accepted save time plus that interval. An After or At task can receive a different absolute target as an At record with the same id. These operations preserve the stored `title`, the prompt, original Session binding, lifecycle status, and all saved receipts. A change may also select a different recurrence kind, which recomputes the target from the new rule with the same id, title, prompt, Session binding, status, and saved receipts. An equivalent normalized rule returns `updated: false` with its unchanged record; it does not rewrite storage, reset the target, or emit a change event. A differently spelled but equivalent Cron expression is such a no-op, because the comparison uses the canonical expression and the canonical zone.
-
-Input validation uses existing timing errors. A changed absolute target must still be future when its FIFO slot runs. The successful task put precedes the change notification and timer recomputation. Storage and lifecycle failures reject; cancellation is checked after queue and initialization waits but cannot roll back an in-flight write. One-shot records retain a UTC instant rather than the editing form's IANA zone. Timing edits append no historical Session event: the model reaches the same in-place update through `schedule_update`, which compares the record it read with the stored one instead of deleting and recreating the task.
+The `timing` discriminant selects exactly its matching payload, for example `{ kind: "cron", cron: { expression: "0 9 * * 1-5", time_zone: "Asia/Shanghai" } }` or `{ kind: "rrule", rrule: "DTSTART:20990101T090000Z\nRRULE:FREQ=DAILY" }`. Other selectors use `after_seconds`, `at`, `every_seconds`, `daily`, or `weekly`. Invalid combinations are refused before persistence. The UI saves typed Cron/RRULE input through this same API and preserves untouched timing.
 
+<a id="saved-delivery-records"></a>
 ## Saved delivery records
 
-`schedule.history({ sessionId, id, limit })` reads saved receipts without activating a Session. The explicit limit is a safe integer from 1 through 100. Pages follow reverse append order, not wall-clock sorting; the optional message-id cursor excludes the oldest record from the preceding page. New arrivals do not shift that cursor. A missing task or wrong Session binding returns `schedule_not_found`; an unknown cursor returns `delivery_cursor_not_found`, not an empty successful page.
+A receipt records `scheduledAt`, `deliveredAt`, `messageId`, and `targetSessionId`; it acknowledges a durable Session inbox write, not model completion. A saved record may also have its immutable sent `prompt`. Old receipts without a target id use their resolved reusable destination before any retargeting edit, so a later target cannot rewrite their history. A receipt without either an explicit destination or a known reusable target rejects decoding; a new default reservation cannot establish a historical destination.
 
-```ts type-equiv
-/** Saved inbox delivery with its immutable sent prompt when recorded by this Host. */
-interface ScheduleDeliveryRecord extends ScheduleDeliveryReceipt {
-  /** Prompt sent for this occurrence; unavailable for legacy receipts. */
-  readonly prompt?: string
-}
-```
+New tasks start with known empty history. An old row without `deliveryHistory` exposes its latest receipt, if present, and sets `earlierRecordsUnavailable: true`; it does not invent lost history or prompt snapshots. An omitted `earlierRecordsPruned` reads as false. Duplicate message ids or disagreement between the latest saved record and `lastDelivery` reject decoding.
 
-```ts type-equiv
-/** Explicitly bounded saved-delivery query within one Session binding. */
-interface ScheduleDeliveryHistoryRequest extends ScheduleDeleteRequest {
-  /** Required safe-integer page size from 1 through 100. */
-  limit: number
-  /** Message identity of the oldest entry in the previous page; excluded from this page. */
-  before?: MessageId
-}
-```
+History follows append order despite clock rollback. Acknowledgment appends and prunes in the same task commit, keeping at most 200 records and 30 days by default while retaining the latest receipt. Query pages are newest first and use an exclusive message-id cursor. Hard deletion removes the task and its history without removing already queued Session messages.
 
-```ts type-equiv
-/** Configured limits applied when appending one task's delivery receipt. */
-interface DeliveryRetentionBounds {
-  /** Retained window in days, measured back from the acknowledgment being appended. */
-  readonly days: number
-  /** Maximum retained records per task; the newest survive. */
-  readonly records: number
-}
-```
+<a id="host-delivery"></a>
+## Host delivery
 
-```ts type-equiv
-/** Newest-first saved deliveries, or a non-mutating task/cursor lookup failure. */
-type ScheduleDeliveryHistoryResult =
-  | {
-    readonly id: ScheduleId
-    readonly records: ScheduleDeliveryRecord[]
-    /** Whether earlier delivery records may be unavailable; missing receipts are never reconstructed. */
-    readonly earlierRecordsUnavailable: boolean
-    /** True only after an append removed saved records; absent legacy evidence is false. */
-    readonly earlierRecordsPruned: boolean
-    /** Current Host retention configuration, also used by the delivery writer. */
-    readonly retention: DeliveryRetentionBounds
-    /** Oldest returned message identity, present only when older saved records remain. */
-    readonly nextBefore?: MessageId
-  }
-  | { readonly id: ScheduleId; readonly code: 'schedule_not_found' | 'delivery_cursor_not_found' }
-```
+One Host timer drives active tasks. Runtime and management writes share one FIFO. Existing and reserved Sessions resolve through `schedule/resolve-agent`, so the embedding owns activation and the injected Web controller is the fallback. Reused-Session tasks hold their execution slot until the target Agent becomes idle; intervening occurrences coalesce. A `new` target permits executions beside one another. Due recurring records targeting the same existing Session share one message; `after` and `at` deliver separately.
 
-New tasks initialize an empty history. Older task rows without history expose only their existing latest receipt, mark earlier records unavailable, and are not rewritten by reads. Future acknowledgments preserve that receipt and append actual new receipts with instruction snapshots. Lost history and missing legacy instruction snapshots are never reconstructed. The same task-row write commits history, latest receipt, status, and next target; explicit task deletion stops future delivery, removes the task row together with its saved receipts, and takes it out of `list` and `catalog`; conversation messages are unaffected. Saved delivery records are pruned on append to the configured `deliveryHistoryDays` window, measured back from each receipt's `deliveredAt`, and to the `deliveryHistoryRecords` cap; the appended latest receipt always survives, and a pruned window marks earlier records unavailable. Pagination bounds returned record count rather than storage size or instruction bytes.
+Timed and manual deliveries obey a per-task minimum interval of 60 seconds. `newSessionIntervalSeconds` can raise it for `new` targets, up to one week. The floor uses the last occurrence when the saved successor preserves the interval, otherwise the last acknowledgment, so delivery latency does not move the rule's anchor. Reads expose `executionActive` and `deliveryFloorEndsAt` only while applicable.
 
-## Host delivery
+Session inbox persistence precedes the task receipt write, so a crash between stores can repeat a delivery. The Host must be running. An active task targeting a Session contributes archive-admission activity; an archive stop deletes those active tasks.
 
-The Host reads persisted tasks at startup and sets its timer to the earliest active target. Inactive tasks remain queryable but never schedule another delivery. At delivery it resolves the original Session through the Session controller, including cold Sessions. After restoration it samples the wall clock again and excludes members that are no longer due after a rollback; those tasks retain their timer obligation. Neither a Goal nor a separate Run completion record participates in dispatch.
+After a committed management change, Schedule queues a best-effort notice to each involved loaded Agent except the actor. Notices join the next model step without opening a turn, and their Session I/O does not hold the management/delivery queue. New-per-delivery Sessions are not accumulated in involvement metadata.
 
-Plugin-sourced `followup()` synchronously appends the message to the Session inbox. After a successful Session flush, one task-record put appends a saved delivery with its instruction snapshot and stores the latest `ScheduleDeliveryReceipt` together with the one-shot's `inactive` status or the recurring task's next target and status. Recurring tasks in the same batch share the receipt's `messageId`; each receipt retains that task's delivered occurrence time. Delivery never steers or cancels the current turn and does not wait for model completion.
+<a id="historical-session-changes"></a>
+## Historical Session changes
 
-A failure to resolve the Session, enqueue the message, or confirm persistence leaves the task stored and reports a Host warning. A later management change or Host restart retries it. Session persistence and the task put are not atomic across stores. A crash after inbox persistence but before the task put can repeat delivery; the receipt does not close this gap. Schedule provides no model-result acknowledgement, execution cancellation, or external notification channel.
+Historical version-1 `schedule/change` events retain the frozen `LegacyScheduleRecord` types: `after`, `at`, and `every`, including old optional titles. They remain recorded Session data without a Schedule interpreter, warning hook, importer, or timer. Existing Host tasks in `schedule.json` still use the normal decoder and evaluator.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -449,80 +149,124 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.schedule` — `ScheduleService`
 
-Shared management service; reads, deletion, and timing edits never activate a Session.
+Shared management service; reads and management writes never activate a Session, and only delivery creates or resumes one.
 
-`sessionPersistence` is a load-order requirement rather than a directly called service: a delivery commits only when `ctx.sessions.flush()` reports that a `session/flush` listener participated, and the persistence backend providing this service is the plugin that registers that listener.
+`sessionPersistence` supplies header-only target validation and the `session/flush` listener that acknowledges durable inbox delivery through `ctx.sessions.flush()`.
 
 ```ts cordis-catalog
+/** Read effective delivery limits without loading or activating a task.
+ * @returns The configured minimum spacing between deliveries that each create a Session, in seconds.
+ */
+@Remote('deliveryLimits') deliveryLimits(): { readonly newSessionIntervalSeconds: number }
+
+/**
+ * Create one task with a Host-generated identity for a human Remote caller.
+ * @param request - Title, prompt, recurrence, and delivery destination.
+ * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+ * @returns The stored task. Cancellation does not roll back an in-flight write.
+ */
+@Remote('create') async remoteCreate(request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleCatalogEntry>
+
 /**
- * Create a reminder bound to the caller-selected Session without activating it.
+ * Create one task and record the acting Agent's Session as involved; the Remote form omits that Session.
  *
- * The request must supply a title; a missing, blank-after-trim, or over-long
- * title rejects with `invalid_prompt` instead of deriving one from the prompt.
- * A Session a delegated child owns rejects with `subagent_session`, because delivery
- * can never reach it: the child is one whose delegation depth is above zero.
- * The record is built from the clock reading taken before the request joins the
- * serialized queue, so a create that waits behind a longer operation keeps its
- * request-time anchor and may already be due when the queue reaches it.
- * @param sessionId - Original Session receiving the reminder.
- * @param request - Validated tool selector, required title, and reminder content.
- * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
- * @returns The durably stored schedule. Cancellation does not roll back an in-flight write.
+ * The record is built from the clock reading taken before the request joins the serialized queue. A `session`
+ * target must exist and must not belong to a delegated child; a `new_once` target reserves its Session identity.
+ * @param request - Title, prompt, recurrence, and delivery destination.
+ * @param actorSessionId - Session of the acting Agent, or undefined for a human caller.
+ * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+ * @returns The stored task. Cancellation does not roll back an in-flight write.
+ */
+async create( request: ScheduleCreateRequest, actorSessionId?: SessionId, signal?: AbortSignal, ): Promise<ScheduleCatalogEntry>
+
+/**
+ * Read one page of Host tasks without activating target Sessions.
+ * @param request - Optional activity filter, page size, and offset.
+ * @returns The requested page and total matching task count.
  */
-async create(sessionId: SessionId, request: ScheduleCreateRequest, signal?: AbortSignal): Promise<ScheduleRecord>
+async list(request: ScheduleListRequest = {}): Promise<ScheduleListResult>
 
 /**
- * Read the selected Session's active tasks without resuming its Agent.
- * @param request - Session whose task list is requested.
- * @returns Persisted reminders in storage order.
+ * Remote form of the shared Host-wide list.
+ * @param request - Optional activity filter, page size, and offset.
+ * @returns The requested page and total matching task count.
  */
-@Remote('list') async list(request: ScheduleListRequest): Promise<ScheduleRecord[]>
+@Remote('list') async remoteList(request: ScheduleListRequest): Promise<ScheduleListResult>
 
 /**
- * Read all active and inactive Host reminders with their original Session bindings.
- * A deleted reminder has no row, so it is absent here.
- * Does not activate Sessions or read Session history.
- * @returns Reminders ordered by scheduledAt ascending, then lexicographically by id.
+ * Read every Host task without a page bound or Session activation.
+ * @returns All tasks, active first, with target and execution metadata.
  */
 @Remote('catalog') async catalog(): Promise<ScheduleCatalogEntry[]>
 
 /**
- * Read saved inbox deliveries without activating or reading the original Session.
- * The task's own row supplies its binding, so its records stay readable through this lookup.
- * @param request - Session binding, task identity, explicit limit, and optional exclusive message cursor.
+ * Read one task without activating its target Sessions.
+ * @param request - Task identity.
+ * @returns The task, or a non-mutating miss.
+ */
+@Remote('view') async view(request: ScheduleViewRequest): Promise<ScheduleViewResult>
+
+/**
+ * Read one page of saved deliveries without activating or reading a target Session.
+ * @param request - Task identity, explicit page size, and optional exclusive cursor.
+ * @returns Newest-first saved deliveries, or a task/cursor lookup failure.
+ */
+async history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>
+
+/**
+ * Remote form of the target-based {@link ScheduleService.history}; an invalid limit rejects with
+ * `schedule/input-invalid`.
+ * @param request - Task identity, explicit limit, and optional exclusive message cursor.
  * @returns Newest-first deliveries in append order, or a task/cursor lookup failure.
- * @throws ScheduleInputError when limit is not a safe integer from 1 through 100.
  */
-@Remote('history') async history(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>
+@Remote('history') async remoteHistory(request: ScheduleDeliveryHistoryRequest): Promise<ScheduleDeliveryHistoryResult>
 
 /**
- * Delete one task belonging to the selected Session, leaving queued messages intact.
+ * Deliver one task now without consuming or moving its scheduled occurrence; an archived destination Session rejects
+ * with `schedule/target-archived`.
+ * @param request - Task identity.
+ * @param signal - Cancellation checked after entering the delivery transaction and before delivery.
+ * @returns Task state after Session persistence acknowledged the delivery, `schedule_execution_pending` while
+ * another execution of the task is queued, running, or inside its delivery floor, or a non-mutating miss.
+ */
+@Remote('run') async run(request: ScheduleRunRequest, signal?: AbortSignal): Promise<ScheduleRunResult>
+
+/**
+ * Delete every ended Host task, leaving active tasks armed.
  *
- * The row is removed: the task no longer schedules, leaves `list` and `catalog`, and its
- * saved delivery records go with it. A task bound to a Session a delegated child owns
- * stays deletable even though creation and timing edits refuse that binding, so a task
- * stored before that rule existed remains removable.
- * @param request - Session and exact task identity.
- * @param signal - Optional cancellation checked before persistence begins, including after FIFO waits.
- * @returns Whether that Session owned a deleted task. Cancellation does not roll back an in-flight write.
+ * Ended tasks never schedule another delivery, so the removal changes no pending
+ * target and no timer is recomputed. Rows are enumerated and removed in one FIFO
+ * slot, so a delivery ordered behind this call ends its task after the
+ * enumeration rather than during it. The batch is one domain write: a normal
+ * failure rejects with every listed row still stored, while a backend
+ * `unknown-state` failure may have removed rows and quarantines the Host
+ * domain, so later schedule operations reject until the domain is reopened.
+ * A successful nonempty batch emits `schedule/changed` without Agent notices.
+ * A rejected batch announces `schedule/changed` because it does not establish
+ * which rows landed, and clients then re-read the catalog.
+ * @returns Count of removed rows; zero when the Host held no ended task.
+ */
+@Remote('deleteInactive') async deleteInactive(): Promise<ScheduleDeleteInactiveResult>
+
+/**
+ * Update or delete one task for a human Remote caller; an invalid patch rejects with `schedule/input-invalid`.
+ * @param request - Task identity and one update or delete operation.
+ * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+ * @returns The updated task, the deletion outcome, or a non-mutating miss or conflict.
  */
-@Remote('delete') async delete(request: ScheduleDeleteRequest, signal?: AbortSignal): Promise<ScheduleDeleteResult>
+@Remote('edit') async remoteEdit(request: ScheduleEditRequest, signal?: AbortSignal): Promise<ScheduleEditResult>
 
 /**
- * Update the name, instruction, and timing of an active task within the original Session
- * binding without activating the Session or changing saved deliveries.
+ * Update or delete one task and record the acting Agent's Session as involved; the Remote form omits that Session.
  *
- * Each supplied field replaces its stored value; an omitted field keeps it. A name or
- * instruction change alone does not reset the committed target. A Session a delegated
- * child owns returns the non-mutating `subagent_session` result, so an edit cannot
- * re-arm a task bound to a Session delivery can never reach, and the Web editor can
- * explain the refusal through the ordinary result it already renders.
- * @param request - Task binding, complete observed record, and any combination of timing, name, and instruction.
- * @param signal - Cancellation checked after domain readiness and FIFO waits, before persistence begins.
- * @returns The committed record, unchanged record for a no-op, or a non-mutating input/lookup/conflict/refusal result.
- * Storage and lifecycle failures reject; cancellation after a write starts does not roll it back.
+ * An update applies every patch field in one write and recomputes the next occurrence when the rule changes or
+ * the task resumes. A supplied `expectedUpdatedAt` that differs from the stored value returns `schedule_conflict`.
+ * @param request - Task identity and one update or delete operation.
+ * @param actorSessionId - Session of the acting Agent, or undefined for a human caller.
+ * @param signal - Cancellation checked before the durable write begins, including after FIFO waits.
+ * @returns The updated task, the deletion outcome, or a non-mutating miss or conflict.
  */
-@Remote('update') async update(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<ScheduleUpdateResult>
+async edit( request: ScheduleEditRequest, actorSessionId?: SessionId, signal?: AbortSignal, ): Promise<ScheduleEditResult>
 ```
 
 Types: [SessionId](core.md)
@@ -547,4 +291,24 @@ Durable task set changed; clients refetch global task and Session-active catalog
 ```
 
 Source: [`packages/schedule/schedule/src/types.ts`](../../packages/schedule/schedule/src/types.ts)
+
+<a id="scheduleresolve-agent--waterfall"></a>
+
+#### `schedule/resolve-agent` — waterfall
+
+Restore a reminder's Session through its embedding's owning controller. Call next() to use the Web Session controller.
+
+```ts cordis-catalog
+/**
+ * Restore a reminder's Session through its embedding's owning controller.
+ * Call next() to use the Web Session controller.
+ * @param sessionId - Original Session receiving the reminder.
+ * @mode waterfall
+ */
+'schedule/resolve-agent'(sessionId: SessionId, next: () => Promise<Agent>): Promise<Agent>
+```
+
+Types: [Agent](core.md) · [SessionId](core.md)
+
+Source: [`packages/schedule/schedule/src/index.ts`](../../packages/schedule/schedule/src/index.ts)
 <!-- END GENERATED cordis-surface -->