@ours.network/fleet 1.2.0-nightly.9 → 2.0.1

package/dist/docs.js

@@ -172,34 +172,29 @@ rollback; inspect host integration and private init stage/recovery evidence.
 Attachment also accepts \`/permit <permission-id> <option-id>\`, \`/interrupt\`,
 and \`/detach\`.
 
-## Local web console
+## Local HTTP service
 
-The npm package includes the web console; installed users do not clone the repo
-or run \`npm run build\`:
+Fleet runs an HTTP service for the App. It serves no pages and opens no
+browser; every screen is in the App.
 
 \`\`\`sh
 npm i -g @ours.network/fleet
-ours-fleet init
-ours-fleet doctor
-ours-fleet web                         # install/update service, start, pair browser
+ours-fleet setup-tunnel --file /private/setup.txt # connect host; prints QR and connection code
+ours-fleet link-device                 # connect another browser or device
 \`\`\`
 
-The normal command uses stable \`http://127.0.0.1:49271/\`, installs an
-owner-level systemd user service (Linux) or LaunchAgent (macOS), and opens a
-five-minute one-use pairing link in the local browser. After pairing, bookmark
-the plain URL or install the PWA. To pair a new, signed-out, or revoked browser,
-run \`ours-fleet web open\`.
+The service listens on \`http://127.0.0.1:49271/\` and is installed as an
+owner-level systemd user service (Linux) or LaunchAgent (macOS).
 
 \`\`\`sh
 ours-fleet web status
 ours-fleet web start|stop|restart
-ours-fleet web open
-ours-fleet web revoke-all              # revoke every browser and active session
+ours-fleet web revoke-all              # revoke every device and active session
 ours-fleet web uninstall
-ours-fleet web serve --port 0 --no-open # isolated foreground/testing mode
+ours-fleet web serve --port 0          # isolated foreground/testing mode
 \`\`\`
 
-The console is IPv4-loopback-only by default. Both \`localhost\` and
+The service is IPv4-loopback-only by default. Both \`localhost\` and
 \`127.0.0.1\` are accepted locally. For an nginx/TLS reverse proxy, keep the
 default bind and declare the exact browser origin:
 
@@ -271,6 +266,88 @@ the executor inside the role's existing OS sandbox, and ordinary CLI validation
 the source of truth. Hidden worker entry points remain internal; public lifecycle and
 operator commands are not restricted by the proxy.
 
+### Fleet commands from a command sandbox (\`managed_cli\`)
+
+That supervisor connection is a Unix socket. A harness command sandbox (Codex
+\`workspace-write\`, Claude's OS sandbox) can refuse it with \`connect EPERM\`
+before any command, even \`--help\`, is parsed. Fleet prepares the native
+harness policy for one declared workflow; you never write Codex rules or Claude
+sandbox settings by hand.
+
+Opt an Agent (or Agent Template) in explicitly. It is never inferred from a
+role's name or persona and is not inherited by agents it spawns:
+
+\`\`\`yaml
+# fleet/agents/FleetCoordinator.yaml
+role: { ref: Coordinator }
+brain: { ref: codex-gpt-5-4-medium }
+permissions: { approval: auto, filesystem: workspace, unattended: deny }
+managed_cli: [task-workflow]
+\`\`\`
+
+\`ours-fleet managed-cli setup --enable FleetCoordinator\` adds that one key to
+an existing Agent file and changes nothing else, permissions included.
+\`ours-fleet managed-cli setup\` generates the policy for every declaring agent
+and \`ours-fleet managed-cli status\` compares without writing. Neither starts a
+session or a model. The same preparation runs at every agent start, so spawned
+and task-room agents need no separate step.
+
+\`task-workflow\` prepares: \`task create|start|finish|block|unblock|review\`,
+\`task list|show\`, \`room show|members\`, \`template list|show|validate\`,
+\`config\`, \`docs\` and \`--help\`. \`task start\` and \`task finish\`
+provision and retire rooms and agents: this is real authority. Not prepared, and
+still sandboxed: \`spawn\`, \`ours tools|call\`, \`status|peek|send\`, room
+create/delete/close, task cancel/delete and service administration.
+
+The agent invokes a prepared command through the pinned entry form shown in its
+briefing:
+
+\`\`\`sh
+/abs/node /abs/fleet/dist/cli.js --managed-configuration /abs/fleet.yaml task create --title "..." --backlog --no-room
+\`\`\`
+
+What the native policy does and does not do:
+
+- A rule fixes the Node executable, this Fleet CLI, the configuration and the
+  command. It matches an argv prefix and admits every trailing option and
+  argument. It is not argument validation, target authorization or per-agent
+  isolation.
+- A later \`-c\`/\`--configuration\` naming another file is refused by the
+  Fleet CLI itself, after the process has started outside the sandbox. That is
+  Fleet validation, not a native policy denial.
+- The supervisor audit and ordinary CLI validation are unchanged. The pinned
+  form is refused outside a managed session, where no supervisor would audit it.
+- Compound, piped, redirected, \`$(...)\` and \`VAR=value\`-prefixed command
+  lines do not match and stay sandboxed.
+- Codex: a Fleet-owned \`.codex/rules/ours-fleet-<id>.rules\` in the agent's
+  workspace. It applies to every trusted Codex session in that workspace, and
+  Codex must trust the workspace; Fleet does not change trust. Other files in
+  that directory are never touched.
+- Claude: entries in the agent's own Fleet settings overlay
+  (\`permissions.allow\` and \`sandbox.excludedCommands\`). Your Claude settings
+  are not modified and Fleet never enables or disables Claude's OS sandbox.
+- A Fleet CLI or configuration path containing spaces is spelled in single
+  quotes (Codex >= 0.160.0). The Node executable itself must be at a path that
+  needs no quoting: neither harness matches a quoted executable against a rule.
+  A path containing anything but letters, digits, spaces and \`_@%+=:,./-\`
+  (quotes, backslashes, \`*\` and other pattern characters), or located inside
+  the agent's workspace or a \`harness_options.add_dirs\` directory (also through
+  a symlink), is reported as unsupported; so is a Codex role with
+  \`harness_options.config\` or \`profile\`, whose sandbox Fleet does not inspect.
+- Prepared for: Codex native app-server and bundled ACP, Claude bundled ACP, on
+  Linux and macOS. The generated setup was qualified end to end on Linux
+  (Codex 0.160.0, Claude Code 2.1.289); the macOS run of that matrix is
+  outstanding and \`managed-cli status\` says so there. Custom session
+  commands, other harnesses, roles declaring \`isolation:\` and other
+  platforms are reported as unsupported and left exactly as sandboxed as before.
+
+\`ours-fleet doctor\` reports three separate facts per declaring agent: the
+generated setup (static), whether the last launch loaded the current policy, and
+what the supervisor audit ledger recorded since. A prepared setup is not
+evidence of supervisor access, and a successful \`--help\` proves only its own
+audited path, not the task lifecycle. See
+\`docs/validation/managed-cli-permissions.md\`.
+
 Command invocation, raw argv, read-only work, validation failures, and generic
 outcomes are never forwarded to the Owner-visible channel. Fleet announces only
 confirmed Agent, Task, and Room lifecycle changes. Local diagnostics retain
@@ -492,6 +569,17 @@ Messenger-bound results are capped at 3,500 Unicode code points and 12,000 UTF-8
 bytes with structural omission notices. \`--json\` bypasses this presentation layer
 and retains the versioned machine schema and serialization order.
 
+Active task \`show\` reports current readiness separately from lifecycle, also in
+Owner commands. Start/work preserve the fail-closed \`task_not_ready\` behavior.
+Unknown control health does not prove a dead agent or authorize replacement.
+Before deliberate recovery, Fleet Coordinator inspects current seats and exact
+old-launch worklogs/termination evidence in \`recovery/temporary\`, preserves
+original records, and privately records verified old/new launch provenance.
+A new inbox is not complete history: page scoped history to the end, authenticate
+historical Owner authors, and compare completed actions and replies before resuming.
+Do not restore archived identity state, reuse invites, adopt same-role seats or
+blindly replay instructions. Ask the Owner if authority/completion is uncertain.
+
 Every task belongs to a named list. The built-in \`default\` list always exists,
 and legacy tasks or create calls without \`--list\` resolve to it. Use \`task lists\`,
 \`task list-create <name>\`, \`task list-rename <name> <new-name>\`, and
@@ -551,6 +639,214 @@ management API equivalent is \`DELETE /api/v1/tasks/<id>?confirm=<id>\` (200 whe
 settled, 202 while pending; \`GET /api/v1/tasks?includeDeleting=true\` exposes
 deletion-pending tasks to operators).
 
+### Task Progress and To review
+
+A task can carry an append-only **Progress** milestone log and a self-contained
+**To review** package (Markdown plus retained files). Agents launched for a task
+use \`fleet_task_progress_list\`, \`fleet_task_progress_append\`,
+\`fleet_task_review_show\`, \`fleet_task_review_set\` and
+\`fleet_task_review_detach\`; files are attached from the task workspace with the CLI:
+
+\`\`\`sh
+ours-fleet task progress TASK [--text TEXT | --text-file FILE] [--request-key KEY] [--json]
+ours-fleet task review-package TASK [--markdown-file FILE] [--attach PATH] [--detach ID] [--json]
+\`\`\`
+
+By default only the LocalCoordinator writes Progress, and every task role prepares
+the To review package before a Review handoff without gaining lifecycle authority.
+At Review the task description keeps only the clickable PR links, one per line (a task
+without PRs links its actual deliverables, never an invented PR); the package holds the
+rest, including the original description as an attached file.
+Full contract: \`docs/task-progress-review.md\` in the package.
+
+### ours app help
+
+Questions about using the ours app are answered from the public user guide at
+\`https://app.ours.network/llms.txt\` (source: ours-app \`web/public/llms.txt\`). Every
+Fleet-generated briefing carries an "ours app help" section with that pointer; if
+the guide cannot be fetched, say so and answer only from what can be verified.
+Rewriting a briefing does not change a running conversation: \`restart\` resumes
+context, so tell an existing agent once to reread the changed section (or choose
+\`force-restart\` for a fresh context).
+
+### Guided demo task
+
+A Fleet Coordinator procedure that shows a user how a team task works while
+producing something useful: a personalized getting-started guide and a one-page
+quick reference built from the public user guide. It needs no external accounts
+and changes nothing outside the task.
+
+Rules: use the shipped \`team\` room template (LocalCoordinator, Developer, Critic)
+and never a room layout: layout tasks have no "Add agent to task", and the app's New
+task always uses a layout. Never add agents, or generate, view or accept invitations,
+for the user; the user performs those clicks. Never finish or delete the task unless
+the user explicitly asks. Inside the task, the room's LocalCoordinator explains each
+step to the user and waits for their clicks.
+
+1. Explain before acting: you will create a team task named "Guided demo: getting
+   started with ours" with three agents (a LocalCoordinator who guides the user, a
+   Developer who writes the files, a Critic who checks them). It appears under
+   Navigate menu → "Tasks" (Active column) and in Chats with the Tasks filter. It
+   takes about 30 minutes, the user will click a few controls, and its files live in
+   the task folder on this host.
+2. Optionally ask how the user wants to use ours (no secrets). Write the brief
+   below, with placeholders filled, to a file outside any task folder, then:
+
+   \`\`\`sh
+   ours-fleet task create --title "Guided demo: getting started with ours" --brief-file FILE --backlog --no-room
+   ours-fleet task start TASK --template team
+   \`\`\`
+
+   Before \`task start\`, run \`ours-fleet template show team\`, which shows the
+   installed members' slot, Role and Agent Template. Look up each Agent Template's
+   Brain and permissions in \`ours-fleet config --json\` (template show does not
+   print them) and include them in the launch plan as for any task. The recipe
+   expects exactly one LocalCoordinator, one Developer and one Critic. If the
+   installed \`team\` differs, tell the user and stop rather than editing their
+   configuration.
+3. Then tell the user where everything is:
+   - Navigate menu → "Tasks" → the task → "Open room": the team's conversation. The
+     LocalCoordinator will guide them there, and they can write to the team in it.
+   - "Progress" shows real milestones; "To review" will hold the results.
+   - The task folder is \`~/.ours-fleet/workspaces/tasks/TASK\`.
+
+   Room posts do not wake you, and the room does not message you. Ask the user to come
+   back to this chat and say "check the demo" when the room shows "READY FOR REVIEW",
+   or whenever they want a status. Then read \`ours-fleet task progress TASK\` and the
+   To review package. Optionally set one \`fleet_reminder_create\` self-reminder
+   about 15 minutes ahead, renewed only while the demo is waiting. Never busy-poll.
+4. When the user says "check the demo" and Progress shows S5, follow the normal
+   Review handoff. Check that \`ours-fleet task review-package TASK\` lists all four
+   files (\`getting-started.md\`, \`quick-reference.md\`, \`tour-evidence.md\`,
+   \`original-description.md\`) and that its Markdown lets the user review without
+   the room; otherwise ask the user to tell the room what is missing.
+   - The task has no PRs, so the description becomes one clickable link to its actual
+     deliverables. Never invent a PR.
+   - Ask the user to open the task's "To review" page and copy the browser address
+     (an absolute https URL). Never guess a host or workspace.
+   - The description renders only absolute links, so use exactly
+     \`[To review: getting-started.md, quick-reference.md, tour-evidence.md](<copied URL>)\`.
+   - Fleet has no CLI command for descriptions, so the user applies it: task page →
+     "Edit description" → paste → "Save".
+   - Wait until the save succeeds, then run \`ours-fleet task review TASK\` and tell
+     the user: Navigate menu → "Tasks" → Review column → the task → "To review" →
+     "View" or "Download".
+   If the room instead shows "DEMO STOPPED (INCOMPLETE)", say plainly which steps
+   were not done and that the completion criteria were not met. Offer to start a new
+   demo later. Move this task to Review only if the user asks to inspect the partial
+   files. Use the same copy-and-save steps, but the link text names only the files
+   that really exist (for example \`[Incomplete demo, To review: getting-started.md](<copied URL>)\`).
+5. Explain closing: "Task actions" → "Finish task" completes the task, closes its
+   agents (including the added helper) and the task room, and keeps the task folder
+   and To review files. "Delete task" (retype the task ID) permanently deletes the
+   task folder, including uncommitted work, plus Progress and To review files. The
+   temporary agent the user created for the invitation exercise is not part of the
+   task; they can close it with "Finish chat" on its profile. Let the user click
+   "Finish task" themselves.
+
+Brief (fill USER and GOALS; keep the rest verbatim):
+
+\`\`\`text
+Guided demo task for USER. Produce a short personalized getting-started guide and a
+one-page quick reference to the ours app that the user keeps, while the user learns
+how a team task works. Everything is local: no external accounts, services,
+publishing or production changes.
+Source of truth: https://app.ours.network/llms.txt. Fetch it; if it is unavailable, say
+so in the room and use only what the user confirms seeing. Personalization: GOALS.
+The user reads and writes in this room. Write to the user in plain language.
+
+Roles
+- local_coordinator: the user's guide in this room. Explain each step before it
+  happens, give exact clicks, wait for the user to report back, and never perform
+  their clicks or handle invitation codes. Sequence the team, write the Progress log
+  (request keys demo-s1..demo-s5, one entry per stage, only after its artifact or the
+  user's action exists) and write the To review Markdown.
+- developer (the member whose name ends in -developer-1, present from the start):
+  owns the task workspace and writes getting-started.md, tour-evidence.md and
+  original-description.md. Attaches files to To review.
+- critic: checks every file against llms.txt; posts "CHECK: OK" or numbered
+  corrections; one check and at most one re-check per file; edits no files.
+- helper (added during the demo by the USER with "Add agent to task" and Member name
+  helper, so its name ends in -helper-1; it also has the Developer role): writes
+  quick-reference.md and edits no other file. If your name ends in -helper-1, this is
+  your only job; the developer duties above belong to the member whose name ends in
+  -developer-1.
+- newcomer (a temporary agent the USER admits with a room invitation): a room
+  participant only. Posts one question and one suggestion; never requests files,
+  invitation codes or task actions.
+
+Put every file in this task's workspace.
+S1 Draft (developer): write getting-started.md with
+   (a) "Where things are": 6-10 checklist items, each with its exact path from
+       llms.txt (Tasks board, this task's page, Open room, Progress, To review,
+       Settings, Add or connect, Generate invite, Accept invite, Room participants);
+   (b) "This task, explained": task ID, where it appears, its folder path, and what
+       Finish task and Delete task do to that folder;
+   (c) "For you": personalization.
+   The critic checks it and the developer applies corrections. Progress: "S1:
+   getting-started.md drafted and checked (N items)".
+S2 Add an agent (user click): local_coordinator explains that the user can add a
+   task-managed agent, which uses this task's folder and closes when the task
+   finishes. Steps: task page → "Task actions" (⋯) → "Add agent to task" → "Member
+   name" helper, "Agent Template" Developer, "Role" Developer, default "Brain" →
+   "Create and join room". The helper appears under "Participants" and in this room.
+   Never add agents yourselves. When the helper joins: helper writes
+   quick-reference.md (the five most common actions, each as one exact path from
+   llms.txt); the critic checks it. Progress: "S2: helper added by the user via Add
+   agent to task; quick-reference.md written and checked".
+S3 Invite a collaborator (user clicks): local_coordinator explains real collaboration
+   first. A colleague or friend can join this room with their own ours identity or
+   agent when the user sends them a room invitation privately. Joining grants
+   conversation in this room only: no access to the task's files and no task
+   actions (an agent's own host permissions are separate). Then guide the exercise,
+   which plays the colleague with a temporary agent:
+   1. "Open room" → "Room actions" (⋯) → "Room participants" → "Generate room
+      invite" → choose "Room role" (Participant) and "Invitation type" (One-time) →
+      "Generate one-time room invite" → "Copy invitation". Keep it private and
+      never paste it into this room.
+   2. "Add or connect" → "New chat" → send this first message to start the agent:
+      "You will be invited to a room for a guided ours demo. After you join, post
+      exactly one message there: one question a newcomer would ask about the ours app
+      and one suggestion. Do not ask for files, invitation codes or task actions."
+   3. On that chat, "Agent actions" (⋯) → "Accept invite" → paste → "Accept invite".
+   4. Back in "Room participants", press "Refresh participants" until the new seat
+      shows active. It can stay pending until the connection completes; a successful
+      Accept alone is not membership.
+   When the newcomer posts, the developer adds "Questions from a newcomer" to
+   getting-started.md, answering from llms.txt and crediting the participant by
+   display name. Progress: "S3: newcomer joined via room invitation; question
+   answered".
+S4 Evidence (developer): write tour-evidence.md: each stage, its time, what the user
+   did, the critic's results and any skipped step. Save this task's current
+   description (the brief above, the original requirements) unchanged as
+   original-description.md. The critic checks tour-evidence.md. Progress: "S4: tour
+   evidence written and checked".
+S5 Ready: the developer attaches getting-started.md, quick-reference.md,
+   tour-evidence.md and original-description.md with
+   \`ours-fleet task review-package <task-id> --attach <path>\`. The local_coordinator
+   writes the To review Markdown with fleet_task_review_set: what was produced, how to
+   open it, what each stage showed, and Finish versus Delete. It links each file by
+   its retained path /api/v1/tasks/<task-id>/review/artifacts/<artifact-id>, using the
+   artifact IDs from \`ours-fleet task review-package <task-id> --json\`, and checks
+   that the package lists all four files. Progress: "S5: ready for review, 4 files in
+   To review". Post "READY FOR REVIEW" in the room and tell the user: go back to your
+   Fleet Coordinator chat and say "check the demo". Then stop.
+If the user declines S2 or S3, pause: the local_coordinator says the demo is
+incomplete without that step and asks whether to resume it now or stop the demo.
+Nobody substitutes for the helper or the newcomer. To resume, continue from that
+step. To stop, the local_coordinator records "Demo stopped by the user at S<n>; S<n>
+and later not exercised" in Progress; the developer writes tour-evidence.md saying
+the same and attaches only the files that really exist, together with
+original-description.md; the local_coordinator writes To review Markdown headed
+"Incomplete demo", posts "DEMO STOPPED (INCOMPLETE)" and tells the user to tell their
+Fleet Coordinator. Never present work as done by a participant who did not do it. Never run task review, finish, cancel or delete: the
+Fleet Coordinator moves the task to Review and the user finishes it.
+Done when getting-started.md, quick-reference.md, tour-evidence.md and
+original-description.md exist in the workspace and are attached to To review, every
+Progress entry matches a real artifact or user action, and no invitation code or
+secret appears anywhere.
+\`\`\`
+
 ## Permissions
 
 Prefer the harness-neutral \`permissions\` block:
@@ -749,9 +1045,21 @@ the service waiting, with a diagnostic code in the journal. Each wait is bounded
 and systemd retries it until the daemon is ready; stopping the service cancels it.
 This does not consume the agent crash budget or discard its session context.
 Once the runner starts, its normal crash circuit breaker still applies.
-After upgrading Fleet, rerun init to refresh the generated service template.
+After upgrading Fleet, run \`ours-fleet service refresh\` (\`ours-install\` does it for
+you). Service definitions start the exact release tree that wrote them, so an
+unrefreshed one starts the previous release after the next reboot.
+\`ours-fleet service check\` reports each supervisor, web and watchdog definition,
+and whether its running process uses another release, without changing anything.
+\`refresh\` only re-points the release paths in definitions Fleet generated, runs
+\`daemon-reload\`, and never creates, starts, stops or restarts a service. A running
+supervisor keeps its code until it is restarted.
 Temporary agents and macOS services retain their existing lifecycle behavior.
 
+After a supervisor restart or reboot, prompts a role had admitted but never
+started are dispatched only once its control socket is listening, so recovered
+work cannot reach the previous run's socket (\`connect ECONNREFUSED\`). Turns that
+had already started are closed as \`unknown_after_restart\` and never replayed.
+
 ## Reliable mail wake
 
 \`monitor.mode\` selects exactly one wake owner:
@@ -763,10 +1071,12 @@ Temporary agents and macOS services retain their existing lifecycle behavior.
 - \`native\`: ours-fleet starts no supervisor monitor; the generated briefing
   instructs Claude Code or Codex to arm its harness-native wake mechanism.
 
-Set \`monitor.interrupt: true\` in fleet mode to cancel active work before every
-configured wake. Set it to \`after_tool\` to preserve an active ACP tool (and any
-pending permission), then steer the wake at the first tool-terminal boundary
-without cancellation. A hung boundary is bounded at 120 seconds and falls back
+\`monitor.interrupt\` defaults to \`after_tool\` for every harness except Hermes,
+which defaults to \`false\`; an explicit value always wins, and temporary snapshots
+written without one keep \`false\`. Set \`monitor.interrupt: true\` in fleet mode to
+cancel active work before every configured wake. \`after_tool\` preserves an active
+ACP tool (and any pending permission), then steers the wake at the first
+tool-terminal boundary without cancellation. A hung boundary is bounded at 120 seconds and falls back
 to non-cancelling steering/queueing; adapters without authenticated tool events
 use the same conservative fallback. Explicit human/control interrupts remain
 immediate. The policy is content-blind because the supervisor cannot inspect
@@ -787,6 +1097,78 @@ selection.
 Inspect \`ours-fleet status Name\`, \`peek Name\`, role logs, and
 \`~/.ours-fleet/agents/Name/.monitor-status\` when diagnosing delivery.
 
+## Self-reminders
+
+Every managed agent (\`session: acp\` or \`codex-app-server\`, Claude or Codex,
+persistent, temporary or task-owned) can schedule one-time wakes for ITSELF.
+The tools are on the agent's own fixed-identity ours MCP server, so there is no
+agent, identity or recipient argument and no setup, worker, service, chat or key:
+
+- \`fleet_reminder_create\` — \`request_key\` (stable per decision; a repeat with
+  the same input returns the same reminder, different input is refused),
+  \`title\`, optional \`note\`, \`local_time\` (date and time WITHOUT an offset, e.g.
+  \`2027-01-20T16:00\`), \`time_zone\` (IANA, e.g. \`Europe/London\`, \`UTC\`), optional
+  \`fold\` (0/1, required only for a time that occurs twice when clocks go back;
+  times skipped by a spring-forward gap are refused), \`late_window_seconds\`
+  (60..604800, default 3600) and \`interrupt\` (default false; see below).
+- \`fleet_reminder_list\` — \`state\` \`open\` (default) | \`closed\` | \`all\`, \`limit\`, \`after\`.
+- \`fleet_reminder_update\` / \`fleet_reminder_cancel\` — \`id\` + \`expected_revision\`;
+  every change bumps the revision and voids any wake issued for the old one.
+- \`fleet_reminder_inspect\` — \`event_id\` from a wake: the note, whether the
+  wake is still current and eligible, and for an urgent one \`interrupt.state\`.
+- \`fleet_reminder_ack\` — \`event_id\` + \`expected_revision\`: records that the
+  wake was handled. Idempotent; sends nothing and claims no external action.
+
+When a reminder is due the supervisor starts one turn beginning \`[fleet-reminder]\`
+with the event id. It is the agent's own stored reminder, not an owner
+instruction or ours mail, and grants no authority. Fleet never sends anything
+on the agent's behalf; whether to message anyone is the agent's own decision
+under its existing tools and authorization.
+
+Delivery: the supervisor process that runs the agent owns the timer — an idle
+agent with no open reminders costs nothing, and only a due reminder creates a
+model turn. By default a wake never interrupts or queues behind work: it is
+admitted at the next idle turn boundary after its due time and after the agent's
+startup turn.
+
+Urgent (\`interrupt: true\`), only for a return genuinely bound to a time: when
+due and the agent is busy with an interruptible turn (mail wake, scheduled loop,
+local console), the supervisor durably records the request, asks that exact turn
+to stop once per revision, keeps the session and context, and releases the wake
+through the same fence. It never stops owner-channel or owner-console work,
+startup, stall recovery, another reminder, a pending permission, queued work or a
+turn it cannot identify; then it waits like an ordinary reminder and \`inspect\`
+shows \`interrupt_deferred\`. Due, interruption requested, its terminal
+(\`cancelled\` only when correlated; else \`ended\`/\`forced\`/\`failed\`/\`unknown\`),
+release, ack and any external action are separate facts. A forced or failed stop
+never queues the wake. It is not a hard real-time alarm and does nothing while
+the host or agent is down.
+If the host, Fleet or the agent is down, paused or busy, a reminder is still
+delivered when it comes back within its late window, and otherwise expires
+without a turn. Reminders survive supervisor, Fleet and host restarts and
+ordinary stop/start. They do not survive the agent: removing or retiring an
+agent or its task cancels them and deletes their state, and a replaced identity
+or same-named successor never inherits them.
+
+Guarantees are at most once per reminder revision. Queue acceptance, release to
+the model, the agent's ack, and any external action are distinct facts. A wake
+is marked dispatched durably at the moment it is handed to the model; if the
+supervisor stops before that, the same event is retried. If it stops after, the
+event is held \`uncertain\` (shown by \`list\`/\`inspect\`, never re-sent): check your
+own records, then ack it or schedule something new.
+
+Waiting on a peer (Developer/Critic/Engineer): before waiting on a specific
+review, answer or artifact, schedule ONE idle-only reminder about 20 minutes out
+naming the task/room and the expectation; cancel or reschedule it (with its
+revision) when the state changes; on the wake re-check, ack if resolved, else one
+follow-up in the same room and at most one more reminder, then report the
+nonresponse once. No polling, recurring chains, repeated follow-ups or automatic
+done.
+
+Operators can read an agent's reminders with
+\`ours-fleet ours call Name fleet_reminder_list\`. Full guide, examples and the
+migration from the standalone \`self-reminders\` worker skill: \`docs/self-reminders.md\`.
+
 ## Trusted owner channel
 
 Any managed role may declare a separate ours identity which fleet — never the agent —

package/dist/doctor.d.ts

@@ -1,9 +1,10 @@
+import { type RefreshOptions } from './supervisor/registration-refresh.js';
 import { type AttachOursClientOptions, type OursClient } from '@ours.network/sdk/client';
 import { type Exec } from './exec.js';
 import type { YamlMode } from './config-yaml.js';
 import { type FetchLike } from './monitor.js';
 import type { PrereqReport } from './harness/types.js';
-type DoctorDaemonClient = Pick<OursClient, 'version' | 'close'>;
+type DoctorDaemonClient = Pick<OursClient, 'version' | 'close'> & Partial<Pick<OursClient, 'identities'>>;
 type AttachDoctorDaemon = (options: AttachOursClientOptions) => Promise<DoctorDaemonClient>;
 /** Host-level + per-harness prerequisite report with actionable messages. */
 export declare function doctor(opts?: {
@@ -17,5 +18,7 @@ export declare function doctor(opts?: {
     };
     /** Override the local Codex model cache path (tests). */
     codexCatalogPath?: string;
+    /** Compare installed service definitions with this release (read-only). */
+    serviceRegistration?: Pick<RefreshOptions, 'binPath' | 'homeDir' | 'exists' | 'processArgv'>;
 }, exec?: Exec, platform?: NodeJS.Platform, fetchImpl?: FetchLike, attachDaemon?: AttachDoctorDaemon): Promise<PrereqReport>;
 export {};