@ours.network/fleet 1.2.0-nightly.8 → 1.2.0-nightly.80

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."

package/docs/task-workspaces.md

@@ -0,0 +1,225 @@
+# Task workspaces and artifact retention
+
+New Tasks allocate a private workspace at
+`$OURS_FLEET_HOME/.ours-fleet/workspaces/tasks/<task-id>` (the user's home is the
+default for `OURS_FLEET_HOME`). New standalone Rooms use
+`.ours-fleet/workspaces/rooms/<room-id>`. A linked Room shares its Task's workspace.
+The absolute path, owner kind/ID and random ownership token are stored in the
+record before directory allocation; `.fleet-workspace.json` proves ownership.
+The path is visible in Task/Room JSON from both CLI and API. A folder of the same
+name without the matching marker is never adopted.
+
+Every newly managed member starts at that exact workspace, including retries.
+An explicit template/member `cwd` remains in the sealed input execution plan as
+source context, but the owned workspace overrides the effective launch cwd.
+Copy or clone required source into the workspace; Fleet does not move or delete
+the configured source directory. Briefings explain this rule. Use separate
+per-agent branches/directories inside the workspace for concurrent edits.
+
+All execution artifacts, dependency checkouts and worktrees belong inside the
+workspace. Clone each repository there first, then use `git worktree add` with
+destinations inside the same workspace. Git's native worktree registry is the
+registry of record. Fleet audits `.git`, `commondir` and reverse `gitdir` links
+before deletion; both the common repository and all registered worktrees must
+be inside the workspace. An external repository's worktree inside the workspace,
+or an internal repository's worktree outside it, blocks deletion. No broad
+`git worktree prune`, branch deletion, reset or modification of unrelated Git
+metadata is performed. Removing the owned repositories also removes their
+complete internal worktree registries, including dirty and stale owned entries.
+
+| Operation | Workspace and execution artifacts | Member runtime evidence |
+| --- | --- | --- |
+| Complete, fail, cancel | Retained while Task is recorded | Retained in Fleet recovery archives |
+| Linked Room retirement or deletion | Task workspace retained | Retained |
+| Internal standalone Room retirement | Room workspace retained | Retained |
+| Explicit Task deletion | Removed after member retirement | All proven owned retired launches removed |
+| Explicit standalone Room deletion | Removed after member retirement | All proven owned retired launches removed |
+
+Internal room close means retirement, not destructive Task deletion.
+The existing CLI `room close ID ID` remains a deprecated alias for explicit
+`room delete ID ID`: it deletes standalone room-owned artifacts, but always
+retains a linked Task workspace. Its repeated-ID confirmation is unchanged. To remove a Task's
+artifacts, explicitly delete the Task. Cancellation is not deletion. Automatic
+compatibility cleanup of legacy closed Rooms skips records with owned workspaces.
+These choices reconcile close/remove wording with the requirement that completed,
+recorded Tasks retain all artifacts.
+
+Fleet's active member state (briefings, logs, session state and WORKLOG) remains
+under `.ours-fleet/tmp` while supervisors run, then in
+`.ours-fleet/recovery/temporary`. The launch stores the workspace descriptor.
+Explicit deletion first proves managed agents retired, then identifies all
+matching archived launches, including failed and replaced attempts, using the
+workspace descriptor plus role and termination/launch evidence. It preflights
+these archives and atomically transfers them to `.fleet-retired-agents` in the
+workspace before removal. Unrelated archives are not adopted by a name prefix.
+Explicit deletion also erases legacy archives with exact launch/action or room
+provenance, matching private supervisor journals and admission/launch descriptors,
+and the exact retired-launch rows in the global termination journal. It never
+infers ownership from an Agent's shared `cwd`. Artifact removal uses a durable
+manifest, ownership fingerprints and per-entry rename/removal checkpoints, so
+an interrupted deletion can resume without deleting a replacement at the old path.
+Task deletion acceptance receipts exist only during cleanup and are erased after
+settlement (including retry after a crash between Task unlink and receipt cleanup).
+Shared Fleet command audit and lifecycle delivery ledgers have exactly attributed
+target labels, configuration and command arguments removed; unrelated entries are
+preserved. Delivery/deduplication metadata and a content-free erased-resource ID
+registry remain so a running writer cannot resurrect erased content. Infrastructure
+logs without structured ownership, backups, and copies already delivered to other
+identities are external retention boundaries; this is not a claim to erase every
+external copy.
+
+Provisioning serializes Task operation then Room close locks, including bounded
+seat waits, so concurrent retries cannot publish competing members and deletion
+cannot race a member launch. Local published Rooms are reused if the Task link
+write was interrupted. Workspace allocation publishes a marked staging directory;
+restart reuses the durable token. Deletion renames the validated workspace to a
+token-specific sibling tombstone before removal. A crash during removal resumes
+that exact tombstone; the Task record is unlinked last. Before collecting archives,
+Task deletion durably checkpoints verified retirement evidence. Retries verify
+any remaining original archive and still refuse replacement live member state
+or a recreated identity even after the archive has been consumed. Failed deletion
+remains retryable with its recorded error.
+
+Explicit deletion restores missing owner read/write/traversal bits on real
+directories inside a proven owned workspace or retired archive before the Git
+audit and removal. This handles restrictive artifacts left by tests even when
+they belong to the same Unix user. It adds no group/other access, follows no
+artifact symlinks, crosses no mounted device boundary, and never changes the
+owner. Only Git pointer files that the audit must read may gain owner-read;
+hardlinked unreadable pointers are refused to avoid changing an outside alias.
+Permission changes target a verified open inode. Readable foreign-UID directories
+may be traversed unchanged; missing owner access is never repaired for another
+UID. On Linux, traversal and Git pointer reads use pinned directory/file
+descriptors, and a detected pathname replacement stops cleanup before descending.
+Unreadable entries
+use an `O_PATH` descriptor through `/proc/self/fd`; other platforms retain the
+error if they cannot open the entry safely. A restricted workspace root is
+temporarily accessible to verify its exact ownership marker; failed marker
+verification restores its original mode. Partial token-derived deletion
+tombstones resume directory cleanup without re-reading already-removed Git
+metadata. List, show, and ordinary Git audit do not repair permissions.
+
+An accepted deletion is hidden from ordinary task lists while cleanup settles.
+Use `ours-fleet task list --include-deleting --json` (or the API's
+`includeDeleting=true`) to include retained cleanup intents, and `task show ID`
+to see pending/error/retry information. Disappearance from the ordinary list is
+not proof of completed deletion; successful deletion removes the task record
+after workspace and member cleanup.
+Cowork HTTP transport failures record the RPC method, failing stage and a
+bounded error category in the cleanup intent. Credential rejection remains an
+explicit `unauthorized` protocol error. Transport diagnostics do not include
+request bodies, credentials, URLs or raw exception text, and failed mutations
+are never automatically replayed.
+
+Deletion rejects traversal, foreign recorded paths, changed markers and symlinked
+workspace ancestors. Ordinary artifact symlinks are unlinked without following
+their targets. Git control symlinks and foreign pointers are refused. As with
+Fleet's other filesystem lifecycle operations, a hostile same-UID process that
+mutates paths during validation requires OS isolation; application checks are
+not a security boundary against that process. Fleet enforces launch cwd and
+safe deletion; unrestricted agents can still write outside cwd, so the artifact
+placement rule also requires agent compliance and/or filesystem isolation.
+
+## Compatibility and limits
+
+Records from before this feature without `workspace` remain unmanaged. Existing
+agents retain their cwd and exact briefing/fingerprint so restart matching works.
+Fleet never claims an old cwd, an outcome artifact path, or a legacy recovery
+archive as owned merely because it was mentioned by a Task. Create a new managed
+Task and explicitly copy desired artifacts to migrate; deleting a legacy Task
+continues its previous lifecycle and does not delete arbitrary old files.
+
+Changing `OURS_FLEET_HOME` does not silently rebase recorded absolute ownership
+paths. Restore the original state root or explicitly migrate records and files
+with the supervisors stopped; mismatched paths fail closed. Archive transfer
+uses same-filesystem rename and reports a recoverable failure across mounts.
+
+Cowork's remote create operation has no idempotency key in this interface. A crash
+after remote creation but before local Room publication is an existing uncertain
+remote result; this change deduplicates locally recorded rooms and does not claim
+to solve that remote transaction window. Inspect remote room ownership before
+retrying ambiguous remote creation. No services or installed Fleet code are
+changed by building or testing this feature.
+
+
+## Broken provisioning and deletion recovery
+
+Deletion accepts every lifecycle state. Missing temporary directories, identities,
+remote rooms and already-erased artifacts are settled outcomes. Retry the same
+explicit delete after an interruption. A missing local member CID is recovered
+only from a matching authenticated seat in the pinned room (exact invite and
+role, uniquely matched), or a supervisor journal tied to the selected daemon,
+temporary instance and recorded creation action. These sources must agree.
+The recovered CID is persisted before retirement consumes the evidence.
+
+A contradictory CID, replacement launch, ambiguous seat, unreadable/corrupt
+record, or unreachable authority is not evidence of absence. Cleanup retains its
+cursor and reports the conflict instead of deleting an unrelated resource or
+claiming complete erasure. An identity with no recoverable authenticated binding
+requires restoring its actual ownership evidence; a name-only force removal is
+not supported. Room deletion removes the linked Task's dead room/member links and preserves its workspace; use explicit
+Task deletion when the request includes the associated Task and its artifacts.
+
+
+## Retained task agents
+
+Task agents use the common Fleet service and existing runners while remaining
+outside the standalone agent roster. Recovery retains their original identity,
+private runtime owner, launch, working directory, admitted room and supported
+backend conversation. `ours-fleet task recover-members TASK_ID` resumes proven
+stopped members or resets their held restart circuit; it never creates identities
+or invitations. See [upgrade and rollback](fleet-migration.md) for legacy tasks.
+
+Recovery delivers an undispatched assignment once, continues interrupted work,
+and sends no readiness/work prompt to a completed idle conversation. An uncertain
+dispatch gets a continuation instead of replaying the assignment. First-session
+retry requires proof that no readiness/work was submitted; established session
+loss requires restoration of the original context. Task agents require a resumable
+harness. Missing ownership, workspace or room evidence keeps recovery held.
+
+Parent shutdown suspends task agents. Explicit member stop terminally releases
+the exact saved owner and archives its launch; it does not complete the task.
+Finish/cancel/review retain their existing semantics. Task deletion stops and
+unregisters only owned members, verifies identity absence and retries cleanup
+before erasing task/room/workspace resources. Permanent siblings remain intact.
+Standalone CLI/web removal refuses `TASK_MEMBER_IS_TASK_OWNED`; use the owning
+task lifecycle. Lost/corrupt task or launch records require restoring original
+backup evidence or explicit ownership reconciliation before deletion can finish.
+
+## Owner lifecycle notifications
+
+A task mutation commits its notification event in the same atomic task record as
+its effective status. Creation, backlog, provisioning, active, review, done,
+cancelled and failed are covered; block/unblock and deletion are effective changes
+as well. Editing a description, list, block reason or saga checkpoint is not a
+status transition. Each event freezes the task identity, title, old/new status and
+navigation route at commit time, so several transitions between delivery polls
+remain separate. Legacy records begin emitting on their next actual change and
+are not retroactively announced as newly created.
+
+The Fleet manager drains committed task events without requiring the web console
+or restarting agents. Its notification producer uses the installation's existing
+owner-scoped credential; it grants no agent arbitrary-send capability. Missing
+configuration or service failure retains the events. Delivery acknowledgement
+runs under the task lock and removes only the accepted event, preserving newer
+changes. A corrupt/unreadable task record is isolated with a safe warning, so
+other tasks continue. Bounded rotating batches prevent one rejected task from
+blocking the entire sender. The built-in `default` task list is unchanged.
+
+Deleting is announced only after its intent commits. Before unlink, settlement
+prepares retained pending events plus a stable deleted event outside the task-owned
+workspace. The sender admits that retained copy only when the original task record
+is absent; an interrupted or failed unlink cannot announce deletion. The final
+event opens the task list and includes the removed task's identity. Earlier events
+keep their immutable detail routes, which may be absent after explicit deletion.
+
+A service restart or producer crash after acceptance may replay an event; the
+Notifications service must retain its acceptance receipts across read/delete to
+make that replay harmless. Upgrade Notifications alongside Fleet to obtain this
+stronger guarantee. The service's authenticated delivery diagnostics distinguish
+provider acceptance, retry, expired subscription and foreground suppression.
+Provider acceptance is not evidence of actual phone receipt. iPhone Web Push
+requires a supported Home Screen installation and granted device/browser permission;
+reopen the workspace to reconcile an expired subscription and explicitly re-enable
+permission if it was revoked. Every received push must display a notification to
+honor Safari's user-visible push requirement.