@ours.network/fleet 1.2.0-nightly.7 → 1.2.0-nightly.71

package/docs/room-layouts.md

@@ -0,0 +1,227 @@
+# YAML Room Layouts
+
+Room Layout describes room goals, participants and their shared or independent
+sessions. Rooms and agents have independent lifecycles.
+
+Place a layout at `fleet/room_layouts/<name>.yaml` beside the split configuration
+for `fleet.yaml`. Agent Templates remain in `fleet/agent_templates/`.
+
+```yaml
+version: 1
+participants:
+  product: {agent_template: Product}
+  developer: {agent_template: Developer}
+  qa: {agent_template: QA}
+rooms:
+  discovery:
+    goal: Clarify the problem and acceptance criteria
+    members: [product, developer, qa]
+  design:
+    goal: Review implementation choices
+    members: [developer, qa]
+  amigos:
+    goal: Resolve a concrete acceptance question
+    members: [product, developer, qa]
+    roles: {product: product, developer: developer, qa: qa}
+```
+
+Participant `instance_scope` controls instance reuse:
+
+- `layout` (default): repeating a participant key reuses its exact running instance
+  and session within this layout run.
+- `room`: each room using the key gets its own identity and session, lazily created
+  when that room opens. Repeated opens of the same active room reuse that instance.
+
+For example, one shared process doctor and one independent critic per room:
+
+```yaml
+version: 1
+participants:
+  doctor: {agent_template: ProcessDoctor, instance_scope: layout}
+  critic: {agent_template: Critic, instance_scope: room}
+rooms:
+  discovery:
+    goal: Agree on the problem
+    members: [doctor, critic]
+  design:
+    goal: Review the design
+    members: [doctor, critic]
+```
+
+Different keys using the same Agent Template still create independent instances.
+See the [shared](../examples/room-layouts/shared.yaml) and
+[fresh](../examples/room-layouts/fresh.yaml) examples, and the mixed
+[scoped](../examples/room-layouts/scoped.yaml) example. All choices can coexist.
+Fresh agents receive their room context. Supply relevant evidence through ordinary
+room messages or existing project documents when needed.
+
+A participant without `agent_template` requires a binding. `layout instance`
+returns a local exact reference (supervisor, agent, launch, CID and session).
+Pass participant-to-reference YAML to `create --bindings`. A stopped or replaced instance is rejected. Cross-Fleet bindings require
+an explicit owner grant, as described below.
+Room-scoped participants require `agent_template`; an explicit binding for them
+is rejected before creating resources. Bindings for layout-scoped participants
+keep their existing behavior.
+
+```sh
+ours-fleet layout validate work
+ours-fleet layout create work --id example
+ours-fleet layout open example design
+ours-fleet layout open example discovery
+ours-fleet layout open example amigos
+ours-fleet layout close-room example amigos
+ours-fleet layout status example
+ours-fleet layout close example
+```
+
+Any declared room may open first. `create` only saves the definition and resolved
+Agent Templates; `open` lazily starts missing participants and admits all members
+before sending their room context. The membership notification is informational. Existing room rules govern when
+an agent contributes. Each room opens through an explicit command.
+
+`close-room` archives a room and keeps agents available to other rooms. `close`
+archives opened rooms and stops only temporary participants created by this layout
+instance. Explicitly bound participants survive. Cleanup processes existing resources. A 3-Amigos room is an ordinary room with
+complementary members.
+Room-scoped instances follow the same cleanup rules: closing a room does not
+retire them, and a closed room cannot reopen. A new layout run creates new instances.
+
+Private state keeps the authorable definition unchanged. Its `participants` map
+uses the original key for shared instances and `<room>:<participant>` for
+room-scoped instances, with `participant` and `room` metadata. Declared but unopened
+rooms have no running instance. Status and task read models distinguish these
+entries and resolve their original Agent Template. Existing snapshots without
+`instance_scope` retain their original keys and require no migration. Snapshots
+using `room` require a Fleet version that supports this field; they are not a
+downgrade format for older Fleet versions.
+
+Supported room fields: `goal`, `members`, optional `roles`, `contract`,
+`quiet_membership`, `anonymous`. `contract` is briefing text.
+Top-level fields: `version: 1`, optional `description`, `participants`, `rooms`.
+Participant fields: optional `agent_template`, `instance_scope: layout|room`.
+Unknown fields, ambiguous YAML and invalid member references are rejected.
+Existing templates and tasks keep their behavior.
+
+Local Fleet control uses the existing authenticated control socket,
+agent runtime, `spawnTemp` and session queue. Cross-Fleet bindings delegate
+membership operations to their owning Fleet as described below. Private state
+snapshots template definitions; public status hides their environment values.
+Existing owner settings apply; owner CID/invite fingerprint are pinned. Unknown
+mutation outcomes stop new work for inspection rather than blindly replaying a
+spawn or room creation. `close` and `close-room` can still clean known resources.
+Cleanup continues after individual errors and does not stop replacement or borrowed
+instances. Confirmed stopped workers need no live control socket. An unknown
+original outcome remains recorded, and cleanup reports incomplete until inspected;
+it never claims that unknown resources were found or removed. Retrying cleanup
+checks known resources and skips completed cleanup. Reopening an active layout room
+checks its native state, CID and required seats and reports drift without repairing it.
+
+
+Shared sessions retain available conversation context, not guaranteed perfect
+recall or isolation between rooms. Compaction and model judgment still matter.
+Rooms keep their existing turn scheduling.
+
+Each layout instance creates distinct native room names, so several instances can
+open the same declared room key. Participant roles must differ from the attached
+owner role; a collision is rejected before creating resources.
+
+Definitions are loaded for authoring commands. Retained instances use their saved
+layout and Agent Templates. Status and cleanup operate on saved resources even
+when the source YAML is broken or removed. New agent launches continue to use
+Fleet's normal configuration and launch checks.
+
+## Borrowing an instance from another Fleet on the same host
+
+Fleet A can open rooms using standalone temporary or persistent agents supervised
+by Fleet B under another OS user. Both must select the same daemon instance and
+Cowork gateway. An agent's original Fleet keeps its session, identity and lifecycle
+control. This extends layout bindings; it does not add bindings to legacy
+`room create` / RoomTemplate provisioning.
+
+On the agent owner's Fleet B, use its existing web server and grant access to an
+exact live standalone instance:
+
+```sh
+ours-fleet web serve --port 49272 --no-open
+# In another terminal belonging to Fleet B's owner:
+ours-fleet layout share Architect --temporary --participant architect \
+  --server-url http://127.0.0.1:49272 --output ./architect.binding.yaml
+```
+
+The command prints the grant ID and output path. It creates a binding YAML and
+an adjacent `.token` file, both owner-only. The private owner record stores a
+SHA-256 token digest, not the token. `share` never overwrites an existing export.
+Transfer both files explicitly to Fleet A's user through your existing secure
+file-transfer method, keeping the receiving credential file owned by that user
+with mode `0600`. Do not share Fleet B's console session, client profile, daemon
+credential, private state directory or supervisor socket. This feature creates
+no additional server; Fleet B's existing web server must remain available.
+
+Export each specialist under its logical layout participant key, then merge the
+YAML mappings into one bindings document. Keep every adjacent token filename
+unique. Relative credential paths resolve against the bindings file's directory.
+The reusable layout contains participant factories or empty participant mappings,
+never concrete credentials or running-instance references:
+
+```yaml
+version: 1
+participants:
+  architect: {}
+  developer: {}
+  doctor: {}
+rooms:
+  product: {goal: Scope, members: [architect, doctor]}
+  design: {goal: Design, members: [architect, developer, doctor]}
+  delivery: {goal: Delivery, members: [developer, doctor]}
+```
+
+On Fleet A:
+
+```sh
+ours-fleet layout create project --id project-run --bindings ./bindings.yaml
+ours-fleet layout open project-run product
+ours-fleet layout open project-run design
+ours-fleet layout open project-run delivery
+ours-fleet layout close-room project-run product
+ours-fleet layout close project-run
+```
+
+The exact CID, launch and harness session are reused. Reopening an active room
+checks existing membership without delivering duplicate context. Closing rooms
+archives Cowork history and never stops borrowed instances. After acceptance,
+the original Fleet B owner explicitly retires its standalone temporary specialists
+using the existing lifecycle commands. Persistent specialists keep their ordinary
+lifecycle. Mixed local-created and borrowed participants are supported.
+
+An exported reference adds `remote` to the existing instance reference:
+
+```yaml
+remote:
+  url: http://127.0.0.1:49272
+  grant_id: 11111111-1111-4111-8111-111111111111
+  credential_file: architect.binding.yaml.token
+  daemon_instance_id: 22222222-2222-4222-8222-222222222222
+```
+
+The grant authorizes only `verify`, `join`, and `assign` for that exact instance.
+Room admission validates the requested room ID and CID against shared Cowork and
+uses an invite issued by Cowork on the owner side; caller-supplied contact invites
+are rejected before contact mutation. Context delivery also requires its active seat, expected room CID and role in
+Cowork. It cannot inspect inventory, spawn, stop, reconfigure, export identities,
+or authenticate browser console routes. It grants the holder room admission and
+room-context delivery, so transfer it only to the intended room creator.
+
+Owner-side revocation does not stop the agent or remove existing memberships:
+
+```sh
+ours-fleet layout revoke-binding <grant-id>
+```
+
+Stopped/replaced sessions, a different daemon, revoked grants or unavailable
+owner transport produce errors; no replacement is spawned. A lost response to a
+membership/context mutation retains the existing layout `uncertain` marker.
+Inspect the native room and owning Fleet before retrying; no mutation is blindly
+replayed. Only direct loopback HTTP origins (`127.0.0.1`) are supported;
+redirects, external hosts and forwarded requests are rejected. No cross-host
+support, discovery protocol, mission service, or room conversation limits are
+introduced.

package/docs/self-reminders.md

@@ -0,0 +1,374 @@
+# Self-reminders
+
+A Fleet-managed agent can schedule a one-time reminder that wakes **itself** at a
+later date and time. When the reminder is due, the agent's own supervisor starts
+a turn for it; the agent reads the reminder and decides what to do.
+
+A reminder is not a message. It has no recipient, chat, route, API key or
+Telegram setting, and Fleet never sends anything on the agent's behalf. If the
+agent decides someone should hear about it, it uses its ordinary messaging tools
+under its existing instructions and authorization.
+
+It works for every managed session (`session: acp` or `session: codex-app-server`,
+Claude or Codex) and every lifetime: persistent, temporary and task-owned. There
+is nothing to install or enable.
+
+## When to use it
+
+- Come back to something at a known time: "check whether the release CI finished
+  at 16:00", "follow up on the review on Monday morning".
+- Replace polling or sleeping inside a turn. A reminder costs nothing while it
+  waits; a turn that sleeps or a loop that polls costs model time every tick.
+- Wait for a peer without forgetting the task: see [Waiting on a peer](#waiting-on-a-peer).
+- Not for recurring maintenance: use configured `loops` for that.
+
+## Tools
+
+The tools are served by the agent's own fixed-identity ours MCP server. No
+argument names an agent or identity: every call acts on the caller's own
+reminders, and an id that belongs to another agent is simply not found.
+
+| Tool | Arguments | Result |
+| --- | --- | --- |
+| `fleet_reminder_create` | `request_key`, `title`, `note`?, `local_time`, `time_zone`, `fold`?, `late_window_seconds`?, `interrupt`? | the reminder (`id`, `revision`, `due_at`, `expires_at`, `interrupt`, …) and `created` |
+| `fleet_reminder_list` | `state`? (`open` default, `closed`, `all`), `limit`? (1–100), `after`? | a page of reminders, `more`, `after`, `uncertain_events` |
+| `fleet_reminder_update` | `id`, `expected_revision`, any of the schedule fields | the reminder at its new revision |
+| `fleet_reminder_cancel` | `id`, `expected_revision` | the cancelled reminder |
+| `fleet_reminder_inspect` | `event_id` | the event (with `interrupt` / `interrupt_deferred` for an urgent one), its reminder (with `note`), `current`, `eligible` |
+| `fleet_reminder_ack` | `event_id`, `expected_revision` | `acknowledged` (repeat calls return `duplicate: true`) |
+
+### Time
+
+`local_time` is a calendar date and wall-clock time **without** an offset
+(`2027-01-20T16:00` or `2027-01-20T16:00:00`); `time_zone` is an IANA zone such
+as `Europe/London`, `America/New_York` or `UTC`. Use the zone of the person or
+task the reminder is about; Fleet never assumes the host's zone. "Tomorrow at
+nine" must be resolved by the agent to a real date first.
+
+Daylight-saving changes are explicit:
+
+- A time skipped when clocks go forward (`2027-03-28T01:30` in `Europe/London`)
+  does not exist and is refused (`nonexistent_local_time`).
+- A time that occurs twice when clocks go back (`2027-10-31T01:30` in
+  `Europe/London`) needs `fold`: `0` for the first occurrence, `1` for the second
+  (`ambiguous_local_time` otherwise).
+- Invalid dates (`2027-02-30`) are refused. The time must be in the future and
+  within five years.
+
+`late_window_seconds` (60–604800, default 3600) is how late the wake may still
+arrive if the agent, Fleet or the host was down, paused or busy at the due time.
+After the window the reminder expires without a turn.
+
+`interrupt` (default `false`) marks a reminder as urgent; see
+[Urgent reminders](#urgent-reminders-interrupt-true). Leave it out for ordinary
+reminders.
+
+### Idempotency and revisions
+
+`request_key` identifies one scheduling decision. Repeating `create` with the same
+key and the same input returns the existing reminder, so a retried call after a
+timeout never creates a second one; the same key with different input is refused
+(`request_key_conflict`). Keys are remembered while the reminder is retained (the
+200 most recent closed reminders are kept; at most 100 can be open).
+
+An urgent request differs from an ordinary one: repeating a call made without
+`interrupt` (or with `interrupt: false`) matches the original, while the same key
+with `interrupt: true` is a `request_key_conflict`. `update` can turn urgency on or
+off; it keeps its current value when not given.
+
+Every `update` and `cancel` names the revision it expects (`stale_revision`
+otherwise) and bumps it. A wake issued for an older revision is void: if it is
+still waiting it is dropped before it reaches the model, and if it was already
+delivered it can no longer be acknowledged.
+
+## Example
+
+```json
+fleet_reminder_create {
+  "request_key": "release-ci-check-2027-01-20",
+  "title": "Check release CI",
+  "note": "PR #412 on prerelease. If CI is green, post the result in the task room; do not merge.",
+  "local_time": "2027-01-20T16:00",
+  "time_zone": "Europe/London"
+}
+```
+
+At 16:00 London time the agent receives a turn like:
+
+```text
+[fleet-reminder]
+event_id: rev_7c0d…
+reminder_id: rem_1b9e…
+revision: 1
+title: "Check release CI"
+due: 2027-01-20T16:00:00 Europe/London (2027-01-20T16:00:00.000Z)
+
+This is a reminder you scheduled for yourself through Fleet. …
+```
+
+It then calls `fleet_reminder_inspect {"event_id": "rev_7c0d…"}`, does the work
+(or decides nothing is needed), and calls
+`fleet_reminder_ack {"event_id": "rev_7c0d…", "expected_revision": 1}`. To
+postpone instead, it calls `fleet_reminder_update` with a new `local_time`; the
+current wake becomes void and a new one is issued at the new time.
+
+## Delivery guarantees and limits
+
+- **Who keeps time.** The supervisor process that runs the agent owns the timer
+  and the private state (`.self-reminders.json`, mode 0600, in the agent's state
+  directory). With no open reminders it arms no timer; otherwise it checks at the
+  next due time and at least once a minute. Only a due reminder creates a model
+  turn.
+- **When it arrives.** By default, at the first idle turn boundary after the
+  due time, and only after the agent's startup turn has succeeded. An ordinary
+  wake never interrupts the agent and never waits in a queue behind other work;
+  a busy agent receives it when its current work finishes. An urgent reminder may
+  instead stop interruptible busy work once (next section). A reminder wake always
+  runs as its own turn and is never combined with owner or mail input.
+- **Offline.** Nothing runs while the host is off or asleep, or while Fleet or the
+  agent is stopped. Reminders are kept, and those still inside their late window
+  are delivered when the agent is back; the rest expire without a turn. Pause and
+  restart keep reminders; they never start a stopped agent.
+- **Deletion.** Removing or retiring an agent, or deleting or finishing its task,
+  cancels its reminders and deletes their state, including from retained
+  evidence. A replaced identity or a new agent with the same name never inherits
+  them: a store is bound to the agent's role and identity (and, for a temporary
+  or task agent, its runtime instance), and a store that does not match is set
+  aside and nothing in it is delivered.
+- **At most once.** Four facts are separate: the supervisor queued the wake, the
+  wake was released to the model, the agent acknowledged it, and any external
+  action the agent took. A wake is recorded as dispatched, durably, at the moment
+  it is handed to the model; if that record cannot be written, it is not handed
+  over. After a crash, an event that was never released is retried as the same
+  event; an event that may have reached the model is held as `uncertain` and is
+  never sent again. `list` reports `uncertain_events`; the agent checks its own
+  records, then acknowledges it or schedules something new.
+- **Privacy.** Titles and notes are visible only through the agent's own tools.
+  The wake text contains the title, not the note, and the conversation ledger
+  stores only a digest of the wake. Logs carry event ids, never reminder text.
+
+## Urgent reminders (`interrupt: true`)
+
+An ordinary reminder waits for the agent to be idle, so a long busy turn delays
+it. For a return that is genuinely bound to a time — a deadline, a meeting, a
+window that closes — the agent can create the reminder with `interrupt: true`.
+When it is due and the agent is busy, the supervisor may ask the current turn to
+stop and then start the wake in the same session, instead of waiting.
+
+What happens, as separate recorded facts:
+
+1. **Due.** The reminder reaches its time (nothing happens before it).
+2. **Interruption requested.** Only if the busy turn is interruptible (below).
+   The request and its exact target (the turn's source, prompt id and session
+   generation; `inspect` shows them as `interrupt.target`) are durably recorded
+   *before* the session is asked to stop. Each reminder revision may request
+   this **once**. Urgent reminders that may still interrupt are considered
+   before ordinary ones and before urgent ones whose interruption is spent.
+3. **Terminal.** How the stop ended, shown by `inspect` as `interrupt.state`:
+   `cancelled` (the target turn's own result confirms this request cancelled it),
+   `ended` (the session reported it settled, but cancellation is not confirmed),
+   `forced` (the adapter ignored the stop and was restarted), `failed` (the
+   control call failed) or `unknown` (Fleet restarted before the outcome).
+4. **Released.** The wake is handed to the model through the same release fence
+   as every reminder. After `forced` or `failed` it is not queued; it is
+   delivered later, idle-only, within its late window.
+5. **Acknowledged**, and any **external action** the agent then takes, are the
+   agent's own and remain separate facts.
+
+The session and its context are kept: nothing is reset, no second agent and no
+parallel model turn is started. The wake tells the agent what it interrupted so
+it can re-check and resume that work. It sends nothing to anyone and grants no
+authority.
+
+An urgent reminder **never** stops, and instead waits like an ordinary one:
+
+- an owner-channel request or an owner admin-console turn (owner commands keep
+  priority, and cancelling one would end the owner's request and its reply);
+- the startup turn, a stall-recovery turn, or another reminder's wake;
+- a turn with a pending permission decision;
+- work queued behind the current turn, or another admission waiting for the role;
+- a turn Fleet cannot identify exactly (for example one started by adapter-side
+  steering, which reports the role idle).
+
+Interruptible turns are mail wakes, scheduled loops and local-console prompts.
+When the reminder defers, `inspect` shows why in `event.interrupt_deferred`, and it
+interrupts at a later boundary if one becomes interruptible. A mail wake that was
+stopped is retried by the monitor and queued behind the reminder; it cannot stop
+the reminder in turn.
+
+Limits:
+
+- Not a hard real-time alarm: the dispatcher checks at least once a minute, and
+  stopping a turn and starting a model turn both take time.
+- Nothing happens while the host is off or asleep, or Fleet or the agent is down.
+- One interruption per revision: after it (whatever its outcome) the wake is
+  idle-only. A failed or forced stop means the urgency was lost for that event,
+  and `inspect` says so; it never reports a successful interruption.
+- Use it sparingly. Ordinary coordination waits stay `interrupt: false`.
+
+## Waiting on a peer
+
+In paired work (Developer and Critic, Engineer and Critic) an agent that stops to
+wait for a review, answer, artifact or check schedules **one** idle-only reminder
+about 20 minutes out (or at the agreed time), naming the task or room and the
+exact expectation:
+
+```json
+fleet_reminder_create {
+  "request_key": "pr-412-wait-critic-final-1",
+  "title": "PR 412: Critic FINAL on head 1a2b3c",
+  "note": "Task room for PR 412: waiting for the Critic's FINAL on head 1a2b3c. If it arrived, just ack.",
+  "local_time": "2027-01-20T16:20",
+  "time_zone": "UTC"
+}
+```
+
+- The answer arrives, the state changes or the work is finished: `cancel` (or
+  `update`) the reminder with its current revision.
+- On the wake: `inspect`, re-check the task. Resolved or closed: `ack`, nothing
+  else. Still waiting: one concise follow-up in the same room, `ack`, and at most
+  one more reminder; if that one finds no progress either, report the
+  nonresponse or blocker once through the configured routes and stop reminding.
+- Never a short polling interval, a recurring chain of reminders, repeated
+  follow-ups or acknowledgements, or a "done" status because a reminder fired.
+- A deleted or finished task removes the agent's reminders, so a closed task
+  produces no wake.
+
+Operators can see an agent's reminders through the existing supervisor tool
+route, which acts as that agent's supervisor:
+
+```sh
+ours-fleet ours call DeveloperA fleet_reminder_list
+```
+
+## Migrating from the standalone `self-reminders` worker
+
+The standalone skill ran one Python worker, its own SQLite ledger and a user
+service per agent. Built-in reminders replace it; the worker is deprecated.
+Personal-assistant reminder, source and outbound messaging stores are separate
+systems and are not touched by this procedure. Migration is a deliberate,
+separately authorized operation per agent; nothing migrates automatically.
+
+Reminder data is handled **by the agent itself** with both tool sets, so its text
+never passes through an operator. The operator only fences and later removes the
+old service.
+
+### 1. Preconditions
+
+- The agent runs a Fleet release with built-in reminders:
+  `ours-fleet ours tools Name` lists `fleet_reminder_create`.
+- `fleet_reminder_list {"state": "all"}` (every page) shows each reminder's
+  `request_key`. Any key starting with `legacy:` belongs to an earlier attempt:
+  reconcile it with the rollback table below before starting again. Keys map
+  back to old ids (`legacy:<old id>:r<old revision>`), so an interrupted run
+  is always resumable from the two lists.
+
+### 2. Fence the old producer persistently
+
+A `stop` alone is not a fence: an enabled unit starts again at the next login or
+boot. The operator records the unit's prior state and its unit file, then
+disables it. The old setup enabled a generated unit by absolute path outside the
+unit search path, so disabling removes its only link; keep the recorded path and
+do not delete that file until step 6:
+
+```sh
+systemctl --user is-enabled self-reminders-Name.service   # record: enabled/linked/...
+systemctl --user is-active  self-reminders-Name.service   # record: active/inactive
+systemctl --user show -p FragmentPath self-reminders-Name.service   # record the absolute unit file
+systemctl --user disable --now self-reminders-Name.service
+systemctl --user is-enabled self-reminders-Name.service   # must not be enabled
+systemctl --user is-active  self-reminders-Name.service   # must be inactive
+```
+
+From here on no old wake can be produced, across worker, Fleet or host
+restarts, until someone deliberately re-enables the unit. Do not run the old
+`tick` or `serve` commands during the cutover.
+
+### 3. Classify every old reminder
+
+The old CLI lists reminders but not events, and its `cancel` leaves earlier
+events in whatever state they had. Classification therefore uses the old
+system's own eligibility rule, not raw event states: an event is **live** only
+if its reminder is still `active`, the event's revision equals the reminder's
+current revision, and its state is `submitting`, `queued` or `uncertain`.
+Anything else is historical: superseded by an update or cancellation, or
+belonging to a reminder that is already `handled`, `cancelled` or `expired`.
+
+The operator supplies the metadata with a read-only query that selects no
+title or context:
+
+```sh
+sqlite3 -readonly /path/to/old/ledger.sqlite "
+  SELECT r.id, r.revision, r.state,
+         datetime(r.due, 'unixepoch'), datetime(r.expires, 'unixepoch'),
+         e.id, e.revision, e.state
+  FROM self_reminders r LEFT JOIN self_events e
+    ON e.reminder_id = r.id AND e.revision = r.revision
+  ORDER BY r.due, r.id"
+```
+
+Each old reminder falls into exactly one row:
+
+| Old reminder (current revision) | Meaning | Action |
+| --- | --- | --- |
+| `handled`, `cancelled` or `expired` | finished; its events are historical | nothing |
+| `active`, `expires` already passed | lapsed while fenced; the old worker would expire it | old `cancel`, nothing to migrate |
+| `active`, due in the future, no event | not yet fired | **migrate** (step 4), then old `cancel` (step 5) |
+| `active`, already due, no event or event `pending` | due, never submitted | **decide**: migrate to a new future time, or old `cancel`; never both |
+| `active`, event `submitting`, `queued` or `uncertain` | live: may already have reached the agent | **hold**: check the conversation and your own records. If handled and still inside its window, old `complete`. Otherwise old `cancel`, which makes the event historical, and create a new reminder only if one is still useful. Never re-create the old event as-is |
+| `active`, event `handled`, `failed` or `invalidated` | finished for this revision | old `cancel` |
+
+**Stop condition:** do not continue to step 6 while any old reminder is still
+`active`. When every row above has been applied, nothing is active and no
+event is live.
+
+### 4. Re-create the reminders that migrate
+
+For each reminder marked *migrate*, the agent calls `fleet_reminder_create` with:
+
+- `request_key` `legacy:<old id>:r<old revision>`;
+- the same title, with the old `context` as `note`;
+- the same `local_time`, `timezone` and `fold`;
+- the old window (`expires − due`) as `late_window_seconds`.
+
+The key makes this step safe to repeat. A reminder whose time has meanwhile
+passed is refused as not in the future. It is then a *decide* row: pick a new
+time, using `request_key` `legacy:<old id>:r<old revision>:retimed`, or let it
+lapse.
+
+### 5. Verify, then retire the old entries
+
+`fleet_reminder_list` shows exactly one `legacy:` reminder per migrated old id.
+The agent then cancels each migrated old reminder with the old `cancel` (`id`,
+`expected_revision`). Afterwards the old `list` shows no `active` reminders and
+no unsettled events.
+
+### 6. Remove the old service
+
+Only after step 5 is verified, the operator removes the user unit and the
+worker's config (it is already disabled and stopped). Keep or delete the old
+ledger according to the owner's retention policy; never point Fleet at it.
+
+### Rollback
+
+Rollback is a reconciliation, not a restart. While the old unit stays disabled,
+the agent goes through each `legacy:` Fleet reminder:
+
+| Fleet reminder state | Action before the old producer may run again |
+| --- | --- |
+| open, no event or event `pending` | First check the old reminder named by the key (`legacy:<old id>:…`). Only if it is still `active` in the old system, `fleet_reminder_cancel` the Fleet copy. If the old one is no longer active, the Fleet copy is the only schedule: keep it |
+| event `dispatched` or `uncertain`, or `acknowledged` | the wake already happened in Fleet: **cancel the old reminder** so it cannot fire again, and keep the Fleet record |
+| `cancelled` or `expired` | nothing; make sure the old reminder is not active either unless that is intended |
+
+Only when every `legacy:` reminder has been reconciled may the operator restore
+the unit to its recorded prior state from the recorded unit file, for example
+`systemctl --user enable --now /recorded/FragmentPath/self-reminders-Name.service`
+if it was enabled and active. Never have both producers active for the same
+reminder.
+
+### Instructions to update
+
+Remove instructions that tell the agent to run the worker script, and replace
+them with: "Use the `fleet_reminder_*` tools to schedule wakes for yourself. A
+due wake is an internal event: inspect it, decide, then acknowledge it. Message
+anyone only through your normal configured channels."