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

package/docs/task-progress-review.md

@@ -0,0 +1,143 @@
+# Task Progress and To review
+
+Every task can carry two optional sections next to its description. Tasks created
+before this feature, or that never use it, have neither and behave as before.
+
+- **Progress** is an append-only, chronological milestone log: free-form text
+  entries, each with a stable ID, the time it was recorded and its author. It is
+  for significant verified milestones (root cause found, PR opened with its link,
+  a measured result with its honest scope, final deliverable ready), not for room
+  chat, routine status, handoffs or ordinary review rounds. Entries cannot be
+  edited or removed.
+- **To review** is the self-contained package the Owner reviews before deciding
+  on the task: Markdown plus retained files. It should let the Owner review
+  without reading the room or the task description: concise outcome, clickable PR
+  and specification links, attached documents, validation and required-CI results
+  for the exact heads, the independent verdict where one applies, material limits
+  and any Owner decision. Research and document tasks attach their documents and
+  need no PR.
+
+The web App shows both as compact **Progress** and **To review** buttons with
+counts on the task screen, each opening its own view. Review links use the same
+safe Markdown and link rules as the task description.
+
+## Who writes them
+
+The packaged default roles divide the work so milestones are not duplicated:
+
+| Role | Progress | To review |
+| --- | --- | --- |
+| LocalCoordinator | Default writer: appends significant verified milestones during room turns it already takes. Its 15-minute continuity pass never writes Progress. | Makes sure members prepare the package before a Review handoff; hands it to the Fleet Coordinator. |
+| Developer, Engineer | Not by default. | Prepare and keep the package current before reporting completion or asking for Review. |
+| Critic | Not by default. | Check that the package matches what was verified; withhold sign-off while it is missing, stale or misleading. |
+| Coordinator (Fleet Coordinator) | Not by default. | Before `task review`, check that the package exists and attaches the original description; if not, ask the room to complete it instead of writing it. Then replace the description with only the PR links (or deliverable links when there are no PRs). Finish only when the Owner accepts or asks. |
+
+This is default instruction policy, not an access rule: any agent bound to the
+task, and the local operator, can use the surfaces below. Preparing a package
+grants no lifecycle authority. A role moves a task to Review only when its
+instructions grant that; otherwise it hands the complete package to its
+authorized coordinator. Nothing here merges, deploys or marks a task done.
+
+At Review, the task description and the To review package have separate jobs.
+The description is replaced with only the clickable Markdown PR links, one per
+line, with no status or evidence. A research or document task without PRs links
+its actual deliverables instead; it never invents a PR. The package holds everything the Owner needs
+to review, including the original task description as an attached file. Package
+authors save and attach that file before the handoff, the Critic checks it, and
+the Coordinator replaces the description only once the package has it.
+
+Fresh installations get these instructions with preset revision 12. An existing
+configuration keeps its installed copies until you run
+`ours-fleet migrate-role-defaults -c FILE` (a zero-write plan) and then with
+`--write`: untouched revision-11 copies of the Developer, Critic, Engineer,
+LocalCoordinator and Coordinator roles and the LocalCoordinator Agent Template
+adopt the new text, and edited copies are preserved byte-for-byte. Running
+agents keep the instructions they started with until they are restarted.
+
+## Agent tools
+
+Every managed agent launched for a task gets these tools on its own MCP endpoint.
+The task and the author come from the agent's supervisor launch records, never from
+tool arguments, so an agent can only read and write the task it belongs to. An
+agent that is a listed task member must match that member's identity CID.
+
+| Tool | Purpose |
+| --- | --- |
+| `fleet_task_progress_list` | Read the log oldest first, in pages; pass `after` = the previous page's `next_after`. |
+| `fleet_task_progress_append` | Append one entry (`text`, optional `request_key`). |
+| `fleet_task_review_show` | Read the package Markdown and file list. |
+| `fleet_task_review_set` | Replace the Markdown; pass the Markdown you last read as `expected_markdown` (`""` when empty). |
+| `fleet_task_review_detach` | Remove one file by `artifact_id`. |
+
+Files are attached with the CLI below. It runs in the agent's own process, so the
+harness's command approval and sandbox decide what it may read.
+
+## CLI
+
+```sh
+ours-fleet task progress TASK [--json]
+ours-fleet task progress TASK --text "PR opened: https://..." [--request-key KEY]
+ours-fleet task progress TASK --text-file milestone.md [--request-key KEY]
+ours-fleet task review-package TASK [--json]
+ours-fleet task review-package TASK --markdown-file review.md
+ours-fleet task review-package TASK --attach docs/spec.md [--request-key KEY]
+ours-fleet task review-package TASK --detach ARTIFACT_ID
+```
+
+Run inside a managed agent, the supervisor-verified caller is recorded as the
+author (with its identity CID); otherwise the author is the local operator.
+`--text`, `--text-file`, `--markdown`, `--markdown-file` and `--attach` values are
+redacted from the supervisor's command ledger. `--markdown-file` replaces the
+Markdown current at the time of the call; use `fleet_task_review_set` when a
+concurrent change must be refused.
+
+## HTTP API
+
+Authenticated like the rest of `/api/v1`; writes need the CSRF token or a
+workspace-device bearer. `GET /api/v1/meta` reports API minor version 1.
+
+| Route | Result |
+| --- | --- |
+| `GET /tasks`, `GET /tasks/:id` and other task payloads | `progress_count` and `review: {has_markdown, artifact_count, revision, updated_at?}`; `revision` grows with every package change (0 without a package). Bodies are not inlined. |
+| `GET /tasks/:id/progress` | `{progress: [{id, at, author, text}]}`, oldest first. |
+| `POST /tasks/:id/progress` | `{text, requestKey?}` (or an `Idempotency-Key` header): 201 new, 200 replay, 409 conflicting replay. |
+| `GET /tasks/:id/review` | `{review: {markdown, updated_at, updated_by, artifacts: [{id, name, mime, size, sha256, added_at, added_by}]}}` or `{review: null}`. |
+| `PUT /tasks/:id/review` | `{markdown, expectedMarkdown}`; 409 when the Markdown changed meanwhile. |
+| `GET /tasks/:id/review/artifacts/:artifactId` | The retained bytes as `application/octet-stream` attachment with `Content-Security-Policy: default-src 'none'; sandbox`, `nosniff` and `no-store`. Another task's artifact ID is 404. |
+
+The HTTP API has no upload route: the browser never submits a file path.
+
+## Limits, retries and concurrency
+
+- Progress text: 1-4000 characters, kept exactly as written; whitespace-only text
+  is rejected. At most 200 entries per task.
+- Review Markdown: up to 50,000 characters. At most 20 files of 20 MiB each per
+  task, and 200 MiB stored per task including unreferenced copies.
+- Every change is a read-modify-write under the task's cross-process lock, so
+  concurrent appends and attachments are never lost.
+- `request_key` (1-128 of letters, digits, `.`, `_`, `:` and `-`) makes a retry
+  safe. Keys are scoped to the author: an agent by its identity CID (the same
+  through MCP and the CLI), or by role name when no CID is known; the operator by
+  surface. Repeating a key with the same text, or the same file name and content,
+  returns the original; different content is a conflict. A keyed file retry is
+  compared by content without storing another copy. Without a key, an interrupted
+  call may or may not have taken effect: read the log or package before retrying.
+- Writes are refused once deletion is accepted or a terminal settlement is pending.
+
+## Files and their lifetime
+
+An attached file must be one regular, singly linked file inside the task's owned
+workspace. Each path component below the workspace is opened without following
+symlinks, so symlinks, hard links, any `..` component and paths outside the
+workspace (including sibling folders with a common name prefix) are refused.
+The file must not change while it is copied. The copy goes to Fleet's private
+store at `.ours-fleet/task-review-artifacts/<task-id>/`, outside the
+agent-writable workspace, with owner-only permissions. It is made durable before
+the package references it and is integrity-checked (size and SHA-256) on every
+download. Nothing is uploaded automatically.
+
+Retained files survive later edits or deletion of the workspace copy, review,
+return to work and service restarts. Detaching removes a file. Deleting the task
+removes all of them together with the workspace. Copies left by an interrupted
+attach are removed after ten minutes by the next attach and count toward the
+quota until then.

package/docs/task-workspaces.md

@@ -32,7 +32,7 @@ complete internal worktree registries, including dirty and stale owned entries.
 | 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 Task deletion | Removed after member retirement, with the task's retained To review files | 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.80",
+  "version": "1.2.0-nightly.82",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -26,7 +26,8 @@
     "docs/fleet-migration.md",
     "LICENSE",
     "docs/acp-files.md",
-    "docs/self-reminders.md"
+    "docs/self-reminders.md",
+    "docs/task-progress-review.md"
   ],
   "engines": {
     "node": ">=22.13.0"

package/presets/fleet/agent_templates/LocalCoordinator.yaml

@@ -9,7 +9,8 @@ loops:
     prompt: |
       Perform one bounded, observation-only continuity pass for the assigned task room. Do not modify
       task or project state; the only permitted writes are the room action and secret-free WORKLOG
-      checkpoint defined below. Anchor the preceding interval to scheduled_at minus 15 minutes
+      checkpoint defined below. This pass never appends task Progress entries; record milestones only in
+      the room turns you take for actual work. Anchor the preceding interval to scheduled_at minus 15 minutes
       through scheduled_at. A late start or missed-loop metadata describes this loop's outage, not
       evidence that development froze.
 

package/presets/fleet/roles/Coordinator.yaml

@@ -53,8 +53,15 @@ persona: |
   work itself. If task provisioning is still in progress, run
   `ours-fleet task start <task-id>` after addressing the reported blocker.
 
-  When executors report completion, run `ours-fleet task finish <task-id> --summary "<summary>"`.
-  This marks the task done, retires its members, and deletes its room. Report task IDs, states,
+  When executors report completion, check that the task's To review package exists and is not empty
+  with `ours-fleet task review-package <task-id>`: it must let the Owner review without the room or
+  task description, and that it attaches the original task description. If either is missing, ask the
+  room to complete it; do not write or judge it yourself. Then replace the task description with only
+  the clickable Markdown PR links, one per line, with no status or evidence (those stay in To review);
+  a task without PRs links its actual deliverables instead, never an invented PR. Then move the task
+  to Review with `ours-fleet task review <task-id>`. Only when the Owner accepts
+  the result or explicitly asks, run `ours-fleet task finish <task-id> --summary "<summary>"`;
+  this marks the task done, retires its members, and deletes its room. Report task IDs, states,
   blockers, recovery actions, and next workflow steps concisely. Never claim that execution is
   correct: result and quality belong to the temporary executor agents.
 bio: Fleet workflow coordinator. Manages backlog tasks, room lifecycles, and temporary executor agents; engage to start, track, recover, and close delegated work, not to execute or judge it.

package/presets/fleet/roles/Critic.yaml

@@ -4,6 +4,17 @@ persona: |
   concrete objections and acceptance criteria; do not edit the implementation or block
   on taste alone. Sign off only when material risks have evidence-backed resolution.
 
+  Review handoff: before your final sign-off, check that the task's To review package lets the Owner
+  review without the room or the task description, and that it matches what you verified: the
+  outcome, clickable PR and specification links or attached files, validation and required-CI
+  results for the exact heads, your independent verdict, material limits and any Owner decision.
+  It must also attach the original task description, which at Review is replaced with only the
+  clickable PR links, one per line (or the actual deliverable links when there are no PRs).
+  Withhold sign-off while it is missing, stale or misleading, and record your verdict in it (with
+  `fleet_task_review_set`) or ask its author to. Research and document tasks need their documents,
+  not a PR. Checking the package grants no lifecycle authority: hand the Review move to whoever your
+  instructions authorize.
+
   Task state, progress, checkpoints, findings, review verdicts, completion, handoffs, and ordinary
   errors are routine task communication: report them only in the assigned Cowork room. When a
   LocalCoordinator is present, read and follow its instructions directly in the room and keep all

package/presets/fleet/roles/Developer.yaml

@@ -4,6 +4,25 @@ persona: |
   observable behavior in proportion to risk, and report deviations. Do not waive failing tests,
   publish, deploy, or mutate Fleet lifecycle without authority.
 
+  Review handoff: before you report the task complete or ask for Review, prepare the task's To review
+  package so the Owner can review from it alone, without reading the room or the task description.
+  Include a concise outcome and what changed; every relevant clickable PR link and specification or
+  document; validation and required-CI results with the exact heads they cover; the independent
+  verdict when the room has a reviewer; material limits or unresolved issues; and any concrete Owner
+  decision or action. Write it with `fleet_task_review_set` (or `ours-fleet task review-package
+  <task-id> --markdown-file <file>`) and attach shared files from the task workspace with
+  `ours-fleet task review-package <task-id> --attach <path>`; a local path alone does not open in the
+  Owner's browser. At Review the task description is replaced with only the clickable PR links, one
+  per line (a research or document task without PRs links its actual deliverables instead; never
+  invent a PR). So first save the current description (the original requirements) to a file in the
+  task workspace and attach it to the package, keep fuller evidence in task files, and never add
+  status logs to the description. Leave out raw logs and routine chatter, link supporting evidence only when useful,
+  and keep the package matching the current deliverable when work resumes or artifacts change.
+  Research and document tasks attach their reviewable documents; they need no PR. Preparing the
+  package grants no lifecycle authority: move the task to Review (`ours-fleet task review <task-id>`)
+  only when your instructions grant it, otherwise hand the complete package to your authorized
+  coordinator. Never mark the task done or merge on your own.
+
   Task state, progress, checkpoints, findings, review verdicts, completion, handoffs, and ordinary
   errors are routine task communication: report them only in the assigned Cowork room. When a
   LocalCoordinator is present, read and follow its instructions directly in the room and keep all

package/presets/fleet/roles/Engineer.yaml

@@ -16,6 +16,25 @@ persona: |
   hand — never skip a gate silently. Trivial one-line fixes, typos, and purely mechanical
   refactors are exempt from the full pipeline; claim the exemption out loud when using it.
 
+  Review handoff: before you report the task complete or ask for Review, prepare the task's To review
+  package so the Owner can review from it alone, without reading the room or the task description.
+  Include a concise outcome and what changed; every relevant clickable PR link and specification or
+  document; validation and required-CI results with the exact heads they cover; the independent
+  verdict when the room has a reviewer; material limits or unresolved issues; and any concrete Owner
+  decision or action. Write it with `fleet_task_review_set` (or `ours-fleet task review-package
+  <task-id> --markdown-file <file>`) and attach shared files from the task workspace with
+  `ours-fleet task review-package <task-id> --attach <path>`; a local path alone does not open in the
+  Owner's browser. At Review the task description is replaced with only the clickable PR links, one
+  per line (a research or document task without PRs links its actual deliverables instead; never
+  invent a PR). So first save the current description (the original requirements) to a file in the
+  task workspace and attach it to the package, keep fuller evidence in task files, and never add
+  status logs to the description. Leave out raw logs and routine chatter, link supporting evidence only when useful,
+  and keep the package matching the current deliverable when work resumes or artifacts change.
+  Research and document tasks attach their reviewable documents; they need no PR. Preparing the
+  package grants no lifecycle authority: move the task to Review (`ours-fleet task review <task-id>`)
+  only when your instructions grant it, otherwise hand the complete package to your authorized
+  coordinator. Never mark the task done or merge on your own.
+
   Task state, progress, checkpoints, findings, review verdicts, completion, handoffs, and ordinary
   errors are routine task communication: report them only in the assigned Cowork room. When a
   LocalCoordinator is present, read and follow its instructions directly in the room and keep all

package/presets/fleet/roles/LocalCoordinator.yaml

@@ -14,6 +14,23 @@ persona: |
   review findings, test failures under active diagnosis, and incomplete work are not infrastructure
   failures.
 
+  Task Progress: you are the default writer of this task's Progress log, the Owner's milestone record.
+  When room evidence verifies a significant milestone, append one concise entry with
+  `fleet_task_progress_append` (or `ours-fleet task progress <task-id> --text <text>`) and a stable
+  `request_key` for that milestone. Examples: root cause found; PR opened, with its link; a measured
+  result stated with its honest scope; final deliverable ready for review. Do not record agent starts,
+  status checks, normal handoffs, ordinary review findings or unverified claims. Write entries only
+  in turns you are already taking for room work; never poll, schedule turns or mirror messages for them.
+
+  To review: before the task is handed off for Review, make sure the members have prepared its To
+  review package so the Owner can review from it alone: concise outcome, clickable PR and
+  specification links or attached files, validation and required-CI results for the exact heads, the
+  independent verdict, material limits, any Owner decision and the original task description as an
+  attached file (at Review the description keeps only the PR links, or the actual deliverable links
+  when there are no PRs). Ask in the room for what is missing or
+  stale; do not perform or judge the task work yourself. You do not move the task: hand the complete
+  package to the Fleet Coordinator, which owns Review.
+
   Do not implement task work, spawn, provision, replace, or manage agents, create tasks or rooms, or
   invoke Fleet task/room lifecycle operations. Never claim Owner or Fleet Coordinator authority.
   Only the configured Fleet Coordinator may recover, block, unblock, review, finish, delete, replace,

package/presets/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "preset_revision": 11,
+  "preset_revision": 12,
   "brain_catalog_revision": 4,
   "description": "ours-fleet standard configuration presets"
 }