@shivaedev/work-fleet 0.0.0 → 0.1.0

package/README.md

@@ -1,3 +1,364 @@
 # @shivaedev/work-fleet
 
-Placeholder. The first real release follows.
+Work Fleet launches approved Work Board items and keeps execution receipts in PostgreSQL. Use its command to schedule workers and inspect progress, or compose its Effect services with your own result, validation and delivery integrations.
+
+## Keep approved work moving
+
+Approve an item in Board, then let Fleet admit it and observe its worker. Waiting views name who must act: the maintainer, the orchestrator or automation. The host tests exercise this loop without launching an external worker.
+
+```sh
+work-fleet serve <board-dir>
+```
+
+## Use the command
+
+Board owns authored work and its revision. Fleet stores preparation, attempts and outcomes against that identity in PostgreSQL. A terminal worker turn is execution evidence; accepted completion also needs result adoption, independent review, checks and an observed human merge of the reviewed head, or validated no-change. The core tests exercise those completion paths with synthetic integrations.
+
+### Configure the host
+
+Put `fleet.config.json` in the Board folder. For `serve`, `--config <file>` selects another configuration file. A Cloud host needs both `cloud` and `worker` settings:
+
+```json
+{
+  "provider": "cloud",
+  "cloud": {
+    "environmentId": "<environment-config-id>",
+    "cwd": "<workspace-path>"
+  },
+  "worker": {
+    "branchPrefix": "<branch-prefix>",
+    "sharedEnvironment": "<environment-script-path>"
+  },
+  "database": {
+    "url": "<postgresql-url>"
+  },
+  "launch": {
+    "model": "<model>",
+    "effort": "<reasoning-effort>",
+    "serviceTier": "<service-tier>"
+  }
+}
+```
+
+Replace the placeholders with trusted host settings. `cloud.environmentId` identifies the Cloud environment configuration, and `cloud.cwd` identifies its workspace. The Cloud transport confirms the returned environment before starting a turn. It rejects work prepared for a different workspace and rejects an echoed service tier that differs from the requested tier. `worker` supplies the branch prefix and environment script path used in the generated worker instructions.
+
+Set optional `worker.workerGuidance` to repository-specific worker instructions. It accepts inline text or `{ "file": "worker.md" }` with the same validation as `worker.reviewerGuidance`; file paths resolve from the Board folder. An unreadable file fails host policy creation. Fleet includes the text in every worker prompt, including first turns, review and check repairs, manual continuations and report corrections. When unset, Fleet adds no worker guidance.
+
+Set optional `worker.reviewerGuidance` to repository-specific review instructions. It accepts inline text or `{ "file": "reviewer.md" }`; file paths resolve from the Board folder. An unreadable file fails host policy creation. The host includes the text in initial reviewer prompts and verdict follow-ups. Omitted guidance leaves the default prompt repository-independent.
+
+For this repository, configure the `worker` section in `.work/fleet.config.json` with the Platform guidance:
+
+```json
+{
+  "worker": {
+    "branchPrefix": "<branch-prefix>",
+    "sharedEnvironment": "<environment-script-path>",
+    "reviewerGuidance": "To check that PostgreSQL tests are not skipped without job logs, read .github/workflows/ci.yml at the reviewed head and follow its test job database setup and environment configuration. In this repository, pnpm db:setup provisions PostgreSQL and pnpm test supplies PLATFORM_EFFECT_*_TEST_DATABASE_URL through script/test.ts and script/lib/postgres-test-environment.ts. Inspect those files at the same head; the checkout may differ."
+  }
+}
+```
+
+The host defaults to `concurrency: 100`, `backlog: 100`, `namespace: "work_fleet"`, `quota: "codex"` and an empty `launch`. `concurrency` limits execution; `backlog` limits undelivered adopted changes. The Codex quota policy uses ordinary-usage eligibility and caches observations for a minute; `quota: "unlimited"` admits without that provider limit. An unknown quota response fails rather than granting capacity.
+
+`stallMinutes` is a positive integer, defaulting to 30. Fleet records each running turn's item count and statuses; added items or changed statuses reset its progress timer. One idle interval sends a Codex steer asking the worker to continue or stop with a question. A second idle interval interrupts the turn; after observing it interrupted, Fleet continues the same thread with the retry prompt. A third idle interval publishes an orchestrator decision. Progress times and recovery stages persist across host restart. CLI status and the generated status page show each turn's last progress time and Fleet's steer and interrupt timestamps. PostgreSQL specs with a synthetic Codex server and test clock in `src/engine/stallRecovery.spec.ts`, `src/engine/stallProgress.spec.ts` and `src/engine/stalledReviewer.spec.ts` prove the recovery sequence, timer resets, restart handling and read-only reviewer continuation.
+
+A missing acknowledged turn stays under observation for five minutes after its first absence or the latest thread progress. Changed items or statuses on an older or newer running turn extend this grace period. If the turn remains invisible without progress, Fleet resumes its existing thread once. Observing that resumed turn clears the consecutive-loss count; a second consecutive loss asks the orchestrator. The grace timer and retry count persist across restart. `src/engine/unobservableTurn.spec.ts` proves delayed visibility, thread liveness, bounded recovery, restart handling and release after a second loss against PostgreSQL and a synthetic Codex server.
+
+Missing or invalid configuration fails. Configuration and Cloud request tests are in `src/host/config.test.ts`, `src/host/guidance.test.ts`, `src/engine/workerGuidance.spec.ts`, `src/engine/reportCorrection.spec.ts`, `src/host/quota.test.ts` and `src/providers/codexCloud.test.ts`; they prove parsing, worker and reviewer guidance propagation and synthetic provider behavior, not live Cloud computation.
+
+Scheduler dispatch submits prepared items in sequence and stops the pass after a transient provider rejection. Worker and repair launches wait up to one second for acknowledgement after persisting their intent; missing replies retain execution ownership while the pass continues dispatching. The provider request continues in the service scope so late replies are persisted, and reconciliation waits for that request to finish before recovering the operation. Explicit caller interruption still cancels the submission. Rejected work releases execution capacity and retries on later passes with durable delays of 30, 60, 120 and 240 seconds. Queue-full, structured provider capacity failures and the explicit “Selected model is at capacity” rejection receive at most five attempts. Failed worker and reviewer turns with those capacity failures use the same retry budget. When it runs out, Fleet parks the item with the provider failure and the number of attempts. The waiting item is tried before the rest of the prepared backlog, so provider capacity backoff also pauses that backlog. `work-fleet status` shows waiting for provider capacity with the last rejection time and next retry time. Rejected credentials and refused policy still require a human decision; ambiguous submissions retain their existing ownership for reconciliation. A retry after an explicitly rejected first turn reuses the acknowledged thread. PostgreSQL tests with synthetic providers in `src/engine/launchPacing.spec.ts`, `src/engine/launchBackpressure.spec.ts`, `src/engine/providerTransient.spec.ts`, `src/engine/providerTerminal.spec.ts` and `src/engine/workerContinuation.spec.ts` cover acknowledgement pacing, late replies, recovery, interruption, capacity backoff and thread reuse.
+
+A capacity rejection while reading or reconciling a turn does not establish that its submission failed. Fleet backs off those reads on the existing operation, retaining the attempt, receipt and execution reservation across restart. Reads use a separate five-attempt budget with delays of 30, 60, 120 and 240 seconds; a successful observation clears that wait. Exhaustion parks with the provider read failure and attempt count while retaining execution ownership. A human retry reconciles that operation; it does not launch a replacement. `src/engine/providerReadRetry.spec.ts` proves recovery after a lost acknowledgement and an acknowledged running turn against real PostgreSQL with synthetic providers. The recovery matrix covers read exhaustion, retry and safe release.
+
+A review with a lost thread acknowledgement or an unobservable submitted turn is safe to repeat because it changes no code. When its provider read budget runs out, or reconciliation reports `session-turn-missing` without a pending read retry, Fleet retires the unacknowledged review and queues a fresh read-only thread for the same head under the shared five-attempt provider retry budget. Late acknowledgements of the retired attempt are rejected. Lost worker and repair threads still retain execution ownership and require a human decision after read exhaustion. PostgreSQL tests with synthetic providers in `src/engine/lostReview.spec.ts`, `src/engine/missingReview.spec.ts` and `src/engine/lostExecution.spec.ts` cover automatic review recovery through ready-to-merge, shared budget exhaustion, late acknowledgements and worker/repair ownership.
+
+### Start the local daemon
+
+`work-fleet serve <board-dir>` binds to `127.0.0.1:3457`; `--port <port>` selects another port. The daemon composes `Fleet.layer`, the host and scheduler once for its lifetime. Its HTTP clients share one PostgreSQL pool, bounded by `database.maxConnections` (20 by default, at least 2), and one provider connection set. One connection is reserved for the PostgreSQL change listener; the remaining connections serve queries and transactions. Fleet record commits notify followers through PostgreSQL, including followers in another host runtime. A listener resync refreshes their stored-state snapshots. Work Board runs independently.
+
+Native Effect HTTP RPC uses NDJSON at `/_fleet/rpc`. Import `DaemonContract` from `@shivaedev/work-fleet/host/daemonContract.ts` and provide `RpcClient.layerProtocolHttp` with `RpcSerialization.layerNdjson` and an HTTP client. The contract exposes Fleet's existing prepare, dispatch, continue, reconcile, resolve, reassign, get and views operations, plus `daemon.dispatch` for explicit Board preparation and dispatch, `daemon.status` for filtered views and the `daemon.follow` snapshot stream. Platform's `RequestTracing` supplies a request id for each call, preserving valid `x-request-id` values. Only loopback Host values and missing or same-origin transport Origin headers are accepted; requests must use `application/ndjson`.
+
+Compose `daemonLayer(host, parts, port)` in a scoped host, or launch it with `serveFleet(host, parts, port)`, both from `@shivaedev/work-fleet/host/daemon.ts`. The daemon uses Platform’s `appHost` with the loopback policy and its existing RPC path. Its shared `appDatabase` layer completes Fleet migrations in the namespace ledger before acquiring application services. The listener starts before scheduling. Closing the scope stops scheduling and HTTP, then closes the provider services and pool. Restart recovery reuses saved launch intents and acknowledged threads; retry or release fences late acknowledgements and retires an intent without a persisted thread acknowledgement before a turn can start. The PostgreSQL and real HTTP tests in `src/host/daemon.test.ts` cover a completed item, concurrent clients, pool/provider lifetime and request ids. `src/host/migrationStartup.spec.ts` proves that a migration failure prevents provider acquisition and scheduling. `src/host/cloudRestart.spec.ts` kills and restarts the daemon at launch boundaries against a synthetic Cloud backend without creating a second thread or accepted turn. These tests do not launch live Cloud workers.
+
+### Approve work and override launch settings
+
+Set the exact `fleet: approved` value in the item's frontmatter. Missing approval or `fleet: draft` does not approve it. The optional `fleet-launch` object overrides host `launch` settings per field:
+
+```yaml
+---
+id: <work-id>
+kind: task
+fleet: approved
+fleet-launch:
+  model: <model>
+  effort: <reasoning-effort>
+  serviceTier: <service-tier>
+---
+```
+
+The launch fields are strings. Omitted fields inherit the host settings; without host settings or an override, they inherit provider defaults. An invalid override fails before dispatch. The selected settings also apply to repair turns. `src/board/fleetField.test.ts`, `src/host/commands.test.ts` and `src/engine/launchSettings.spec.ts` cover these rules.
+
+The worker brief is the authored content in the item's own Markdown source. Editing a linked goal, plan, report or decision, or an unrelated item, does not change that brief. When prepared or active work has no open decision, Fleet approves an edited brief in place on the next pass if it still has `fleet: approved`, its owner is omitted or `codex`, and its status is not `done`, `superseded` or `deferred`. The worker keeps its session, turn and PR without a Board context changed decision. A changed brief that fails these conditions still stops for a human. `work-fleet dispatch <id>` can explicitly approve the current approved brief in place, even while its worker turn runs. Retry on the context decision approves the brief that decision was published against; an answer to a decision from before an edit cannot approve the new brief. Approval updates the stored context and prompt, supersedes the decision, and preserves the current attempts, thread and PR. The running turn remains observed, then independent review uses the new criteria and repairs continue the same worker thread. Removing approval stops further execution. Changing the item's `status`, including `done`, preserves work that has started and its open decisions. That work completes through the normal execution, review and delivery path; only an explicit release answer releases unfinished execution ownership. Uncertain provider receipts retain ownership for reconciliation. `src/engine/approvedBrief.spec.ts`, `src/engine/contextScope.spec.ts`, `src/engine/contextAuthority.spec.ts` and `src/host/approvedRevision.spec.ts`, `src/host/approveBrief.spec.ts`, `src/engine/briefApproval.spec.ts` and `src/engine/staleDecisions.spec.ts` cover these transitions against PostgreSQL with Markdown Board fixtures and a synthetic provider.
+
+Cloud hosts compute the Board directory's repository-relative path only when that directory is inside the repository and git-ignored. Before launching, Fleet checks each criterion's text for that path. A match publishes an orchestrator decision naming the criteria and explaining that Cloud workers cannot read local-only Board data, without starting a session. Edit the criteria to use data available to the worker, then dispatch again. Local workers, Board directories outside the repository, directories that are not ignored, and paths mentioned only in the body do not trigger this guard. `src/host/localOnlyCriteria.spec.ts` covers these cases and dispatch after an edit against PostgreSQL with a synthetic repository and provider.
+
+### Schedule areas and dependencies
+
+Use `areas` to name the code areas a task changes. Area names are exact shared labels, such as `work-fleet/host`; they do not expand into filesystem paths. Fleet admits one task per area, while disjoint areas and tasks without areas can run concurrently within the existing capacity and quota limits.
+
+```yaml
+---
+id: task.follow-up
+kind: task
+fleet: approved
+areas: [work-fleet/host, work-board/ui]
+relationships:
+  - kind: depends_on
+    target: task.foundation
+---
+# Add the follow-up behavior
+```
+
+An overlapping task remains prepared, waiting on automation, with a reason such as `waiting for area work-fleet/host held by task.foundation`. Areas are held through execution, review and validation, and are freed on completion or safe release. For a reviewed, green PR ready for a human merge, `areaMergeWaitMs` in Fleet policy or `fleet.config.json` defaults to `1800000` (30 minutes), counted from that readiness event. Once the wait expires, other tasks can use its areas while Fleet continues observing the PR for delivery. PostgreSQL preserves admission order across restarts; eligible overlapping tasks wait behind earlier prepared work.
+
+Fleet identifies work by its authored brief: the Markdown title and body, criteria, Board kind, deliverable kind and authored relationships. Bookkeeping fields such as `status`, `next_action` and `owner` do not change that revision. Editing them on executing or reviewing work preserves the attempts; editing them on work with an open decision preserves the question and its recorded answers. Criteria or body edits refresh eligible prepared and active work in place. Work waiting on a human decision still stops with Board context changed; an answer to the earlier decision cannot authorize execution against the changed brief. This revision rule applies to every status, including `done`: marking executing work done leaves its original work and decision intact and resolvable. Completed work can be prepared again only after its authored brief changes; unchanged source or bookkeeping edits leave its accepted outcome intact. Saved whole-file revisions are compared through their exact saved source without rewriting records or publication receipts; records without that source still need renewed preparation when their revision differs. Approval remains a separate execution requirement. `src/board/briefRevision.test.ts`, `src/engine/briefBookkeeping.spec.ts`, `briefChanges.spec.ts`, `doneBookkeeping.spec.ts`, `completedRenewal.spec.ts` and `dependencySavedRevision.spec.ts` cover the revision rule, restart and decision resolution with real PostgreSQL and synthetic providers.
+
+A `depends_on` relationship waits on automation for an accepted Fleet outcome on the target's current brief revision: an observed merge or validated no-change completion. Bookkeeping edits on the target preserve that acceptance before dispatch and while dependents execute, review or wait on a decision. Changes to the target's authored brief still need a new accepted outcome. If the target has no Fleet record, its authored `status: done` also qualifies. A prepared, released or unfinished Fleet record does not qualify through Board status alone. Missing or ambiguous targets and criterion-specific references remain blocked. Status, wait timeout summaries and the generated Board view show the stored reason. Real PostgreSQL regressions in `src/engine/areaScheduling.spec.ts`, `areaMergeWait.spec.ts`, `areaDeliveryObservation.spec.ts`, `dependencyScheduling.spec.ts`, `dependencies.spec.ts`, `dependencyBookkeeping.spec.ts`, `dependencyDecisionBookkeeping.spec.ts` and `src/host/schedulingViews.spec.ts` cover admission, release, ordered restart, dependency acceptance and those views with synthetic provider integrations.
+
+Before launching prepared work, Fleet rereads its Markdown source for the current Board status, including changes made during preparation assessment in the same scheduler pass. A `done`, `superseded` or `deferred` item moves to `released` with a durable `releaseReason`, clears its admission blocker and leaves the waiting list. PostgreSQL regressions in `src/engine/closedDispatch.spec.ts` cover closing a prepared item while it waits for an area lock or a dependency, freeing the wait without starting a worker, and preserving release across restart.
+
+### Run, dispatch and inspect
+
+| Command | Behavior |
+|---|---|
+| `work-fleet serve <board-dir> [--port <port>]` | Starts the local HTTP RPC daemon, admits approved work, dispatches prepared items and reconciles running work. |
+| `work-fleet dispatch <work-id> [--port <port>]` | Prepares and dispatches one approved item; explicit dispatch can re-approve an edited revision. |
+| `work-fleet status [--port <port>]` | Prints Active, owner-grouped waiting and Completed views from stored records. |
+| `work-fleet status <work-id> --json [--port <port>]` | Filters to one item and prints the views as JSON. |
+| `work-fleet release <work-id>... [--port <port>]` | Releases terminal needs-human items and records closing responses on their Board decisions. |
+| `work-fleet reassign <work-id> <decision-id> <owner> [--port <port>]` | Reassigns the exact current question to maintainer, orchestrator or automation. |
+| `work-fleet wait <work-id> --timeout <seconds> [--port <port>]` | Subscribes to daemon snapshots until an outcome or timeout. |
+| `work-fleet watch [work-ids...] [--follow] [--port <port>]` | Reports outcomes once, or keeps reporting transitions with `--follow`. |
+| `work-fleet continue <work-id> [message] [--port <port>]` | Continues terminal work on its existing worker thread; reads stdin when the message is omitted. |
+| `work-fleet answer <work-id> [text] [--release] [--port <port>]` | Answers the waiting worker question or Fleet decision; reads text from stdin when omitted. |
+| `work-fleet name-threads [--port <port>]` | Names existing Cloud threads from Fleet records and reports each rename or failure. |
+
+Automatic reconciliation refreshes eligible edited briefs in place. Explicit dispatch can re-approve work waiting on a context decision; renewal still requires safe execution and result ownership. Keep `serve` active to reconcile worker progress. All commands except `serve` connect to its loopback port (3457 by default) over RPC and open no PostgreSQL connection. Their retained `--board` and `--config` flags do not select a host; the running daemon owns its Board and configuration. Without a daemon, they exit 1 with the address and a command to start it. The host loop and approval behavior are exercised against PostgreSQL in `src/host/commands.test.ts` and `src/host/cloudRestart.spec.ts`; `src/host/statusProcess.spec.ts` exercises status output and flags.
+
+`answer` records an orchestrator response on Board and resolves what the item waits on. Worker questions require nonempty text and continue on the same thread. Fleet decisions receive retry with the text as the overall response; for a reviewed, ready PR, nonempty text requests changes on the same branch and PR. Use `--release` to release terminal ownership instead. The command refreshes the managed decision and registers its current question before answering, including after a changed template was republished. If reconciliation replaces a decision with another of the same kind during the command, the answer applies to the current decision. A different kind or a move out of needs-human returns `Decision changed` with the current reason. Nonempty text sent during execution or repair is stored for the next worker turn, survives daemon restart and prints `queued for the next turn`; release requests still require terminal waiting work. Items waiting on nothing return a typed error naming their stage. `status` prints each waiting question or reason, with `work-fleet answer <work-id>` in the maintainer and orchestrator lanes. Automation waits have no answer command. `src/host/daemonCommands.spec.ts`, `src/host/answerWorker.spec.ts`, `src/host/answerPublication.spec.ts`, `src/host/answerReplacement.spec.ts`, `src/host/answerQueue.spec.ts` and `src/host/approvedRework.spec.ts` prove these paths through daemon HTTP against PostgreSQL and synthetic Board directories.
+
+`wait` prints a summary and exits with these codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | Completed. |
+| `1` | Error, including an unavailable daemon. |
+| `2` | Waiting on the named owner. |
+| `3` | Released. |
+| `4` | The requested timeout expired. |
+
+`--interval <seconds>` controls reconnect delay and defaults to 15. An item not yet recorded keeps waiting. `src/host/wait.test.ts` exercises the actual process, terminal summaries, timeout and delayed creation against PostgreSQL over HTTP. `src/host/watchFailures.spec.ts` covers every client command's missing-daemon message.
+
+`watch` prints one line per item when that item is completed, needs-human or released, then exits 0 after every item has reported. Duplicate IDs report once; unknown IDs remain pending. With no IDs, it follows the active items found by its first successful read and exits when those items have reported. Existing completed, needs-human and released items are excluded from that initial active set.
+
+`watch --follow` keeps running even when no work is active or every item has reported. With no IDs, it watches all items, including items launched later; explicit IDs restrict it to those items. Its first snapshot reports current needs-human waits and records completed or released history without printing it, then it prints one line when an item enters completed, needs-human or released. Human waits include the owner and reason; a reviewed PR ready for a human merge is a needs-human wait on the maintainer. A new decision prints again, even if its reason is unchanged. An item that leaves needs-human for repair and returns with the same reason reports again. Repeated snapshots of the same outcome do not print again. Reconnecting after a daemon restart preserves those states: unchanged history stays quiet, and an outcome that changed during the gap prints once. Stop the follower with Ctrl-C, or set an explicit `--timeout`. `src/host/watchFollow.spec.ts` covers a late HTTP dispatch, completion, repeated decisions, ready-to-merge summaries, releases, explicit selection and a follower that remains running against real PostgreSQL. `src/host/watchReview.spec.ts` drives real reviewer completion before and during a follow watch, then repairs and reviews the same PR again. `src/host/watchReconnect.spec.ts` covers quiet completed and released history, current needs-human waits, unchanged HTTP restarts and a transition during the reconnect gap for all items and explicit IDs.
+
+`watch --follow` accepts unfamiliar decision codes, stages and extra fields from a newer daemon. It prints unfamiliar codes and stages as text; an entry whose display fields cannot decode prints its raw data without stopping other entries or later snapshots. Fatal watch errors exit 1 and print one cause line on stderr. `src/host/watchSkew.spec.ts` proves these behaviors through a synthetic HTTP stream and real CLI subprocesses.
+
+`wait` and `watch` each use one scoped RPC subscription. The daemon is the only store writer. Record and foreign-occupancy writes run through effect-sql `transact` and record table hints inside that transaction. The daemon shares one summary stream across followers. It subscribes to committed record hints before reading compact fields through its existing pool, then reads again only when a record commit arrives; it does not poll PostgreSQL. New followers receive the last good snapshot; after the last follower leaves, the next subscription starts with a fresh read. PostgreSQL read failures retain the last good snapshot and retry every half second; 20 consecutive failed attempts end all current followers with a clear message and exit 1. A reconnect receives a snapshot of the original selected set, or all items for `watch --follow` without IDs; printed outcomes remain deduplicated. Connection loss retries up to 20 consecutive attempts before exit 1. `--timeout <seconds>` exits 4 and writes a timeout message to stderr. `src/host/watch.test.ts`, `src/host/daemonClients.spec.ts`, `src/host/snapshotStream.test.ts` and `src/host/daemonFollow.spec.ts` cover output, HTTP restart resync, initial selection, PostgreSQL read recovery and failure bounds, the commit-subscription lifecycle and rollback silence. `src/host/daemonCommit.spec.ts` proves a daemon command reaches a CLI follower without periodic reads and a rolled-back store write sends neither a snapshot nor a refresh query. Client subprocess fixtures reject direct PostgreSQL connections, so the command tests fail if a client opens the store itself.
+
+### Read the generated heading board
+
+The CLI host writes `fleet/status.md` inside the Board folder. It derives Active, Waiting on maintainer, Waiting on orchestrator, Waiting on automation and Done columns from the same Fleet views, with one card per current unreleased item, retaining released items while a blocker remains. Cards link to the task's Board identity and its adopted PR when available. The file contains execution stages and blockers, not worker prompts, session receipts or authored task status.
+
+After the first scheduler cycle creates the file, select it as Work Board's home:
+
+```sh
+work-board ./notes --home fleet/status.md
+```
+
+The host refreshes the view on scheduler reads and after preparation, dispatch, reconciliation, reassignment and resolution. Work Board's existing file watcher refreshes an open page. Identical content leaves the file untouched. Publication failures are reported and retried on the next cycle without changing execution outcomes. The writer refuses authored content or symlinks at the generated destination. Board remains usable without Fleet; the generated file is an optional projection of SQL records. A composed headless runtime can opt into the same publication behavior by providing `statusLayer(boardRoot)` from `@shivaedev/work-fleet/host/statusLayer.ts` over its Fleet Layer and Node filesystem services. `src/board/statusMarkdown.test.ts`, `src/board/writeStatus.test.ts` and `src/host/statusLayer.test.ts` cover rendering, file boundaries and publication retry.
+
+### Identify who must act
+
+Waiting records and views carry `attentionOwner`: `maintainer` for scope decisions or merging a reviewed PR, `orchestrator` for routine worker questions, result inspection and retry, and `automation` for unfinished dependencies, missing host integrations, occupied capacity or pending checks. Prepared dependency waits stay in automation even when their stored owner is orchestrator; `src/host/statusProcess.spec.ts` covers this through PostgreSQL and the status CLI. `FleetViews.waiting` contains separate `maintainer`, `orchestrator` and `automation` arrays. Items with blockers also appear in waiting groups while retaining their stage, including released work awaiting a Board acknowledgement. `work-fleet status`, its JSON output and the generated Board views use these groups; wait and watch summaries name the owner while retaining their exit codes.
+
+Reassign the exact current question with `fleet.reassign(workId, decisionId, attentionOwner)`, the native `Reassign` RPC command, or the CLI:
+
+```sh
+work-fleet reassign sample-task sample-decision maintainer --board ./notes
+```
+
+Retrying the original decision ID for the same committed reassignment recovers publication and acknowledgement without creating another question; a competing change reports a typed stale decision. Legacy waits keep the maintainer as the recipient of their published question, and reconciliation reads a recorded answer before changing an owner. `src/engine/legacyAttention.spec.ts` and `src/engine/reassignRecovery.spec.ts` cover upgrade answer adoption, lost acknowledgements and concurrent reassignment/resolution against PostgreSQL.
+
+Reassignment publishes a new question for the assigned owner and acknowledges the old question as superseded, preserving both reviewed sources. Answers to the old question cannot continue the worker. Reconciliation retries publication and acknowledgement after failure or restart. Existing unowned decisions recover their original publication before publishing a replacement for the assigned owner. Owner labels do not grant runtime approval or delivery authority.
+
+The CLI host also atomically publishes `fleet/health.json`, using Board's versioned `FleetHealth` schema from `@shivaedev/work-board/diagnostics/health.ts`. Running counts work with submitting, accepted or running attempts; queued counts prepared work; waiting counts group every wait by maintainer, orchestrator and automation, including capacity and quota blockers and pending checks. The snapshot uses version 2. The snapshot carries the configured concurrency cap, publication time and freshness threshold, last completed scheduler pass and last observed structured provider capacity rejection. A host restart reloads the two last observations. Status-board and health publication failures do not change execution outcomes; the next publication retries. The daemon retains the same health observation in memory and serves it through the shared `daemon.diagnostics` HTTP RPC query, together with Codex and GitHub rate-limit observations cached for one minute. Board's Diagnostics view reads this RPC query without Fleet or database dependencies; it does not read the health file. Health observations retain their publication time so a stalled runtime remains visibly stale. `src/host/boardDiagnostics.spec.ts` covers Board-to-daemon HTTP reads against PostgreSQL after the health file is removed.
+
+A composed runtime enables health publication with `statusLayer(boardRoot, { concurrency, staleAfterMs })`, provides `healthLayer(boardRoot)` from `@shivaedev/work-fleet/host/healthLayer.ts`, and wraps its provider with `providerHealth` from `@shivaedev/work-fleet/host/providerHealth.ts`. Capacity comes only from structured `rateLimitExceeded`, `flexUnavailable` or `serverOverloaded` errors; unclassified rejection text is not treated as capacity. A repeatedly observed terminal turn does not refresh the same rejection's timestamp.
+
+### Release waiting work
+
+Every new Fleet decision records a stable `code` beside its human `reason`. Import the Schema literal union `DecisionCode` from `@shivaedev/work-fleet/DecisionCode.ts`; Platform integration errors carry a code through `withFailureContext(error, { code })` from `@shivaedev/work-fleet/engine/failureContext.ts`; uncoded errors receive a code from their Platform error tag. Session and Board failures retain their optional code fields. Release-only actions, report-correction retries, conflict repair and merge-ready reconciliation use codes. Conflict decisions use `pr-conflicting`; the recovery matrix rewords their text and proves retry still repairs the same PR. Decision fields remain optional for existing stored records; Fleet assigns codes when it publishes decisions. PostgreSQL migration backfills saved current and archived decisions. `src/engine/reasonCodes.spec.ts` proves that rewording a release-only reason preserves its answer options and rejects retry after restart. `src/engine/recoveryMatrix.spec.ts` requires recovery coverage for every Schema code.
+
+The guided actions offer retry when Fleet can launch a new turn, review or delivery observation. Incompatible preparation, changed result identity, invalid adopted GitHub identity, oversized immutable reports, unconfigured stock-host no-change validation and report workers that published to GitHub offer only release, with a sentence explaining what must happen outside retry. Closing a published PR and deleting its branch retain publication evidence. Worker questions accept a recorded answer to continue the same thread, or a guided release answer to free terminal ownership.
+
+`src/engine/recoveryMatrix.spec.ts` inventories production decision creation sites and requires a recovery row for every code in `DecisionCode`. Human-decision rows check retry progress and release after restart against real PostgreSQL with synthetic providers and GitHub readers, production host checks, Board report publication, attachment and payload boundaries, and the PostgreSQL session journal. Automatic-capacity rows reword queue-full and quota failures, preserve their waits across restart, and resume without a human decision. Separate rows record an answer while the HTTP daemon is closed, then restart it against the same records. New decision sites or Schema codes without a matrix row fail the suite. Mutation regressions add a decision site and remove a code’s recovery rows to prove this guard.
+
+Codex RPC overload code `-32001` produces a `SessionFailure` with code `session-queue-full`; launch backoff uses that code and the rejected failure kind. Quota admission produces a platform `Forbidden` with `provider-quota-unavailable` in its failure context, which reconciliation keeps waiting on automation. Rewording either failure message leaves its retry or waiting behavior unchanged. Custom integrations supply these codes for the same behavior. `src/providers/capacityWire.spec.ts` checks the protocol classification independently of wording; `src/engine/recoveryMatrix.spec.ts` proves both waits and their recovery against PostgreSQL.
+
+A guided release answer frees Fleet ownership even when the task content or location changed, or the task is now done, deferred or unapproved. Fleet still checks the exact decision source, question and response. Before release it reconciles unresolved receipts without submitting a turn and observes pending attempts; running, unreadable or mismatched execution evidence keeps ownership. When the provider reports `session-turn-missing`, or confirms the acknowledged turn is absent with no active thread progress, reconciliation releases a needs-human item whose Board status is done, superseded or deferred. For an open task, `work-fleet answer --release <id>` releases it. Both paths retire the lost attempt, preserve its recorded receipt and mark its session unusable without replaying or resuming the turn. `src/engine/closedHuman.spec.ts` and `src/host/missingTurnRelease.spec.ts` prove these paths against PostgreSQL and the Codex adapter over synthetic provider responses; `src/engine/missingTurnSafety.spec.ts` proves that an uncoded ambiguous failure or unreadable provider evidence cannot authorize release by its wording. A retry answer resumes the prepared brief only while its authored identity still matches; changed criteria or body require renewed preparation. Repeated resolution and restart recover the same response and acknowledgement. After release, explicit dispatch prepares a fresh cycle under the same item ID, preserves the released cycle and known PR reservations, and starts a new worker session.
+
+```sh
+work-fleet release sample-one sample-two --board ./notes
+```
+
+The command records an explicit release response for each current waiting decision, including worker questions, then uses the same resolution path as a release answer. It supersedes an existing unambiguous response, refuses changed decision sources or competing responses, and can be repeated to recover a pending acknowledgement. `src/engine/staleDecisions.spec.ts` and `src/host/bulkRelease.spec.ts` prove changed-task release, concurrent rejection of retries for changed briefs, Board Inbox closure and bulk release of done and deferred tasks against PostgreSQL. `src/host/releasedDispatch.spec.ts` proves release followed by dispatch under the same ID when the prior worker has a session but no adoptable result.
+
+### Continue a worker with new instructions
+
+Use `work-fleet continue <id> <message>` to send instructions to the existing worker thread of terminal work waiting on an owner or completed work. Omit the message argument to read it from stdin. The current Board revision still needs approval; running or released work is refused. Work waiting on a human merge can continue on the same worker thread; its reviewed head stays in history and its PR ownership remains until the new result is adopted.
+
+```sh
+work-fleet continue work-id "Fix the failed checks on the existing PR"
+printf '%s\n' "Check the remaining criterion" | work-fleet continue work-id
+work-fleet wait work-id --board .work
+```
+
+The command persists the message and thread identity before submission and returns the item to Active. Keep `work-fleet serve` observing the Board: `wait` only reads PostgreSQL. A lost acknowledgement retains the attempt for reconciliation without replay. The prior cycle remains in history, including its decision and result; reconciliation supersedes the prior open decision. The new turn's output follows the first-launch adoption path, including report publication or PR review, validation and delivery, and replaces the prior current result. `Fleet.continue(workId, message)` and the native `Continue` command expose the same path to composed hosts.
+
+A failed worker or repair attempt without a receipt is never adopted. Review refresh ignores that attempt and uses the preceding worker receipt for the retained result, including a prior cycle with the same Board revision and result identity. Retrying the failed follow-up starts a fresh independent review before validation and delivery. `src/engine/failedFollowup.spec.ts` covers a completed repair, rejected receiptless follow-up, restart, retry, fresh review and observed delivery against real PostgreSQL with a synthetic provider.
+
+Codex protocol rejections with no specific cause retry the same method and parameters, including the saved operation ID and thread, after 30 and 60 seconds. A third rejection reaches the existing failure handling and publishes a decision for a turn submission. Generic messages are “Something went wrong”, “Internal error”, “Internal server error” or an absent message, with an optional request ID. Invalid request, permission and quota messages do not use these retries or contention replay. Structured capacity failures keep their separate retry budget. `src/engine/genericRejection.spec.ts` proves same-thread recovery, the three-rejection limit and immediate decisions for specific causes through a synthetic Codex WebSocket server and real PostgreSQL. `src/providers/genericRejection.test.ts` covers generic wording and exclusion of structured capacity and uncertain submissions.
+
+When an otherwise unclassified definite Codex turn rejection has an active turn in the provider's paginated turn state, Fleet classifies it with code `session-active-turn`. The retry rule uses that code, polls until the thread is idle, then submits the same saved operation, prompt and settings. Rewording the rejection leaves this behavior unchanged. An idle thread or unreadable state cannot authorize contention replay; distinct coded failures retain their own handling. Polling starts immediately, with delays doubling from two seconds to a maximum of thirty seconds. The attempt stays submitting with its execution ownership while waiting. The wait has a five-minute deadline across classification and busy rejections and permits at most three resubmissions. Reaching the wait deadline retains `session-active-turn`; exhausting resubmissions records `session-active-turn-exhausted`. Both mark the receiptless attempt failed, release execution capacity and queue a fresh thread with the saved instructions on the same branch and PR. The explicit “turn already active for thread” rejection uses that fallback even when the turn state appears idle. Fresh-thread retries share the five-attempt provider budget and persist their backoff across restart; exhaustion parks with the failure and attempt count. Credential and policy rejections cannot authorize contention replay even when the provider has an active turn. `src/engine/activeTurn.spec.ts` covers reworded contention across paginated turn observations, continuation and delivery; `src/engine/activeTurnDeadline.spec.ts` covers polling backoff, a hung active turn reaching the deadline and automatic recovery after restart. Both use real PostgreSQL with a synthetic provider. `src/providers/activeTurn.spec.ts` covers rewording, idle and unreadable state, and the resubmission cap through the Codex wire boundary; the recovery matrix covers retry and release after the provider retry budget is exhausted. `src/engine/wedgedRetry.spec.ts` proves a busy repair automatically starts a fresh thread on the same PR after restart.
+
+### Answer a worker question
+
+Cloud worker prompts instruct workers to stop for a decision with `FLEET_QUESTION: <question>` and include the context and choices needed to answer. Fleet recognizes this marker in a completed worker or repair turn, publishes the question through Board's response writer, and keeps the work in `needs-human`, waiting on the orchestrator by default. Only `FLEET_MAINTAINER_QUESTION: <question>` escalates a worker question to the maintainer; mentioning the maintainer in ordinary question text does not escalate it. `work-fleet wait <id>` exits with code 2 while that question is open. Questions must use one of these explicit markers; Fleet does not infer questions from prose.
+
+Record a nonempty answer through Board's response page or response API. Reconciliation continues the exact worker thread with the answer body under current approval, quota and capacity policy. The response receipt and continuation intent commit together before submission. Concurrent resolution, repeated resolution and restart do not submit the answer again; a lost acknowledgement reconciles the stored operation. If a crash occurs before submission and no authoritative receipt is available, Fleet retains the uncertain operation for human inspection. Clarification and deferral keep the question open. An answer cannot authorize edits to the authored brief; changed criteria or body require renewed preparation. Responses from the same author use the newest recorded response, ordered by recorded time and then response ID; different authors still need explicit supersession to resolve competing responses. Answer text supplies task input and does not grant delivery authority. `src/engine/workerQuestion.spec.ts`, `src/engine/workerContinuation.spec.ts` and `src/host/workerQuestion.spec.ts` cover these rules with a synthetic provider and real PostgreSQL.
+
+### Return a research report
+
+Declare `fleet-deliverable: report` on an approved task to request research. Report workers leave repository sources unchanged and return the whole report in the final message. They may create new uncommitted report attachments, but must never commit, push, create branches or open PRs. Omit the field to keep the PR workflow.
+
+```markdown
+---
+id: research.example
+kind: task
+fleet: approved
+fleet-deliverable: report
+---
+# Compare the available approaches
+```
+
+After a completed worker turn, Fleet publishes an ordinary `kind: result` item under `responses/fleet-report.<digest>.md`, with an `informs` relationship to the task. The result preserves the whole final output and records the exact session, turn and task revision in its worker receipt. The Markdown gateway uses Board's durable publisher; custom gateways implement `BoardGateway.report` with the same immutable, idempotent boundary. Before writing attachments or publishing, the CLI host saves the complete report text, retrieval warnings and attachment bytes in an immutable payload under `.fleet-reports/`, outside Board’s source index. Publication retries read that payload without recollecting files, preserving the same identity and bytes after restart or a lost acknowledgement even when Cloud retrieval changes. `src/host/reportBoard.test.ts`, `src/board/reportPayloadFile.test.ts` and `src/engine/reportRecovery.spec.ts` cover these boundaries, including concurrent payload writes, symlink refusal and completion after restart against PostgreSQL.
+
+The CLI host reconstructs report attachments from the completed turn’s paginated `thread/items/list` file changes. Workers must create every attachment with the file-edit/apply_patch tool under `/tmp/fleet-report/attachments/`, and use that tool for later edits. Adds contain UTF-8 file content; update hunks and deletes replay in item order to obtain each file’s final bytes. Files created or changed through shell commands are not exposed as file changes. Binary evidence must be attached as a base64 text file with its encoding stated. List every promised file on a separate final-report line, `FLEET_ATTACHMENT: <relative-path>`, so Fleet can record missing files. Files from other directories and earlier turns are excluded. `src/providers/codexReportAttachments.test.ts` covers authenticated pagination across 193 synthetic items; `src/host/reportFileChanges.test.ts` covers ordered replay, moves, deletes and missing files.
+
+Retrieved files are saved in `responses/fleet-report.<digest>.attachments/` beside the result, with links in the report. Markdown attachments receive a `.attachment` suffix so Board does not index them as authored items. Reconstruction uses only new regular scratch files, with normalized relative paths, `lstat`, resolved-path containment and no-follow opens. Turn item downloads are limited to 16 MiB of cumulative UTF-8 JSON, attachment changes to 8 MiB, attachment count to 64 and aggregate attachment bytes to 32 MiB. Unsafe paths, missing adds, mismatched update hunks, unavailable retrieval and collection-limit failures publish report text with an Unavailable attachments section; they do not create a decision. Other retrievable files survive per-file reconstruction failures. Existing saved attachment bytes are never replaced. `src/host/reportAttachmentSafety.spec.ts` proves publication and recorded failures against PostgreSQL and a synthetic Codex WebSocket server. `src/host/reportAttachmentFiles.test.ts` and `src/board/reportFiles.test.ts` cover regular-file safety and immutable attachment storage.
+
+After a terminal report turn, the host checks the configured GitHub remote for the exact `<branchPrefix><workId>` ref and all PRs opened from that branch, including closed PRs. A published branch or PR makes the work wait on the orchestrator with the reason `Report worker published to GitHub`; Fleet never deletes the branch. Unavailable remote evidence also blocks completion. The host rechecks before result publication on retry. Custom headless runtimes provide their report inspection and collection boundaries; the Markdown gateway alone publishes report text.
+
+Local attachment validation and saved-payload failures park the completed attempt with the failed file path and cause. Report file errors stay tagged in the Effect channel until the Board or platform boundary maps them. `src/engine/reportFileFailures.spec.ts` proves distinct reasons for a path escape, an oversized payload and a file replaced after validation against PostgreSQL. `src/board/reportPayload.test.ts` covers platform error mapping without losing the failed path.
+
+Successful publication records the report in the current Board read pass and completes the Fleet attempt without PR adoption, independent review, checks or delivery. Empty or whitespace-only output, or a complete report document over Board’s 256 KiB UTF-8 context limit, creates an orchestrator decision with a concrete reason instead of a result. The size check includes metadata, the worker receipt and attachment links, and runs before writing attachment files. Oversized reports leave no attachment folder. `src/host/attachmentSize.spec.ts` covers rejection before attachment writes, including a report that fits the limit until attachment links are added. `wait` and the status views expose the same terminal states and result path. A retry after a publication failure republishes the existing completed attempt; a retry after empty output prepares another worker attempt. Oversized output offers only release because retry cannot shorten a completed report; prepare a worker to produce a shorter report after release. Scheduler passes do not repeat publication. `src/engine/recoveryMatrix.spec.ts` proves release after restart and recovery when report publication evidence becomes available. `src/board/publishReport.test.ts` and `src/host/reportSize.spec.ts` cover the size boundary, immediate visibility and durable orchestrator decision. These prompts direct worker behavior; runtime policy still owns execution authority.
+
+### Cloud provider
+
+The hosted Codex transport sends the configured environment and launch fields, then reads the final answer from a terminal turn. It authenticates from a Codex login file and can run a configured refresh command for an expired login. Failed refresh remains unavailable. These boundaries are tested with a synthetic WebSocket backend in `src/providers/codexCloud.test.ts`.
+
+Cloud host configuration accepts `cloud.threadNamePrefix` (default `Fleet: `), `cloud.projectId` for an existing project, and `cloud.archiveThreads` (default `true`). Names use `<prefix><work-id>: <title>` from the prepared Board context's first heading. Titles have normalized whitespace and at most 80 Unicode characters, with an ellipsis when trimmed; a missing heading falls back to the work ID. Separate reviewer and repair threads add `(review)` or `(repair)` after the work ID. A repair that continues the worker thread retains its name. The Fleet session journal resolves names from persisted operation intents, so review integrations that start through the same session service receive reviewer names automatically.
+
+Fleet persists the session acknowledgement before naming it. Launch naming retains the acknowledged work ID and loads only that record; `src/engine/sessionNaming.spec.ts` proves one lookup with both one and 1,000 stored records, and rejection of missing or ambiguous intents without scanning other records. Naming is best-effort: a rejected or failed request logs a warning with the session ID and cause, then Fleet starts the turn. Project assignment is sent with `thread/start`. `work-fleet name-threads` reads all stored Fleet records, including archived cycles and acknowledged sessions without turns, and renames threads whose current names differ from their Fleet names. It reports each rename to stdout and each read or rename failure to stderr, then continues other sessions. Shared threads are visited once and retain their original role and context. Repeating the command skips successful names and retries failures. `src/engine/threadNames.test.ts`, `src/providers/cloudMetadataFlow.spec.ts` and `src/host/cloudThreadNamesFlow.spec.ts` cover formatting, startup ordering, best-effort failures and backfill idempotence with real PostgreSQL and a synthetic Cloud backend.
+
+Restart the host with the same SQL namespace. An attempt intent commits before `thread/start`, its session acknowledgement commits before `turn/start`, and its turn acknowledgement commits before observation. SIGKILL tests against real PostgreSQL and a synthetic Cloud server cover both sides of these mutations and recovery of 100 concurrent attempts with lost turn acknowledgements. These tests prove host persistence and Cloud adapter wire behavior; they do not prove live hosted execution.
+
+If the session ID is known, reconciliation searches all provider turn pages for the persisted operation ID and adopts the exact existing receipt. For an acknowledged Cloud thread with no turns, Fleet polls for up to five seconds to allow late acceptance to appear. If the thread remains empty, Fleet confirms its environment and starts the saved turn on that same thread, retaining the attempt and operation ID. Retry on a missing-turn decision uses the same recovery, including prepared prompts from older worker records. Recovery requires the current Board revision to remain approved. Missing or incomplete thread evidence, unrelated turns and duplicate operation matches stay blocked. If the thread acknowledgement itself was lost, the current protocol cannot locate that thread by operation ID: Fleet retains the attempt and reservation and raises a human blocker. Recovery never starts another thread for that attempt. `src/host/cloudRestart.spec.ts` proves empty-thread recovery, late acceptance and guided retry after SIGKILL against real PostgreSQL and a synthetic Cloud server; `src/providers/recoverTurn.test.ts` covers the grace period and uncertain evidence. Provider unavailability after session acknowledgement and a mismatched setting after thread creation also retain unresolved ownership.
+
+Fleet cleans up worker, repair and reviewer threads after accepted completion or explicit safe release, and after renewal makes a prior conversation unusable for further repair. Terminal provider turns alone do not trigger cleanup: review, checks and human retry can still require the conversation. Cleanup deduplicates shared repair threads, includes acknowledged sessions without a turn, and persists completion markers. Archive failures leave the Fleet outcome accepted; scheduler reconciliation retries pending cleanup, including after restart or renewal, without repeating delivery. `cloud.archiveThreads: false` retains sessions and settles cleanup for that cycle. Transports without an archive capability also retain their sessions.
+
+The adapter sends `thread/archive` and `thread/name/set`; grouping uses `thread/start.projectId`. The generated experimental app-server protocol also declares `thread/metadata/update.projectId` and `thread/list.projectId`, but Fleet does not call those methods. PostgreSQL regressions prove the cleanup lifecycle, and a synthetic WebSocket backend verifies the host configuration and wire requests. These fixtures do not prove hosted acceptance or removal from the ChatGPT and Codex sidebars.
+
+Cloud worker instructions include startup waiting, the configured environment script, fetching current main to start the branch, repository checks and one pull request for human review. Workers watch CI after every push, repair failures on the same branch and report once CI is green on their exact head. The merge queue re-runs CI against latest main before merging. Workers merge main only when GitHub reports a conflict or their change needs something that landed there; a conflict-free branch behind main does not require a merge, fresh review or revalidation. Workers state the exact head's CI result before the final `FLEET_PR: <url>` or `FLEET_PR: none` line. The parser requires exactly one marker on the final line; missing or malformed reports yield no result. `src/prompt/worker.test.ts` and `src/prompt/reviewer.test.ts` cover these instructions and the parser. A report line is not proof of an adopted result or accepted delivery.
+
+### Adopt a worker result
+
+Select `"result": "github"` in the host's `fleet.config.json` to adopt a completed worker report through the authenticated `gh` CLI. The final two report lines are one `FLEET_HEAD: <sha>` line with the full head SHA and one `FLEET_PR: https://github.com/<owner>/<repo>/pull/<number>` line. Both markers tolerate surrounding whitespace and backticks around their values. Adoption records the GitHub PR number, exact head and all paginated changed paths, including both paths of a rename. The PR must be open or merged in the host repository and target its configured branch; a different reported head or base/path movement during observation fails with a typed platform `BadRequest` or `Conflict`. A PR closed without merging waits on the orchestrator.
+
+A PR merged before adoption or during review still requires independent approval and checks for its reported head before Fleet accepts the observed merge as delivery. Retrying a failed adoption resumes the completed worker receipt; retrying after review reuses that review session. `src/engine/mergedAdoption.spec.ts`, `src/engine/mergedReview.spec.ts` and `src/engine/mergedReviewRecovery.spec.ts` cover these transitions against real PostgreSQL and a synthetic HTTP GitHub server.
+
+A final `FLEET_PR: none` claims no change at the reported `FLEET_HEAD`. Fleet retains that head and the report as evidence, and passes the result through independent review and required checks. Main movement does not invalidate the report; a changed task revision prevents adoption. Fixture tests exercise GitHub responses and the PostgreSQL adoption path, not live GitHub or worker execution.
+
+When GitHub adoption rejects a completed worker or repair report's format, Fleet requests one corrected report on the same worker thread, with the exact required ending. A second malformed report needs a human; answering `retry` starts a new correction turn. Reports whose PR head moved also receive a correction turn on the existing worker thread; a second stale report needs a human retry. `src/engine/recoveryMatrix.spec.ts` covers moved-head report correction after restart. Reports rejected for repository identity or PR state still need a human decision. Correction attempts retain launch settings, persist before submission and reconcile lost acknowledgements after restart. `src/engine/reportCorrection.spec.ts` and `src/engine/workerReportRecovery.spec.ts` cover these paths with real PostgreSQL and a synthetic provider.
+
+`src/host/githubResult.test.ts`, `src/host/githubResultFailures.spec.ts` and `src/engine/resultAdoption.spec.ts` cover these adoption boundaries.
+
+### Independent review
+
+After adopting a result, Fleet starts an independent reviewer through the same `SessionService`, provider and durable journal as workers. Reviewers receive the Board task and criteria plus the adopted result at its exact head, without the worker conversation or preparation prompt. They use `FleetPolicy.launch` from host configuration; task launch overrides remain worker and repair settings. `FleetPolicy.reviewerGuidance` supplies repository-specific validation instructions, resolved by the command host from `worker.reviewerGuidance`. The Codex adapters request read-only execution with shell network access for read-only PR and exact-head CI inspection, and no escalation. Reviewers use existing exact-head repository objects, read-only repository tools or `gh pr view`, `gh pr diff` and `gh api --method GET`; network writes are prohibited. When the exact-head diff and check results are readable, the prompt requires a verdict. Passing required checks at that head are CI evidence even when job logs or artifacts are unavailable; reviewers record that limitation in their evidence.
+
+The reviewer ends with `FLEET_REVIEW:` followed by JSON containing `head`, `verdict` (`approve` or `changes`), nonempty `evidence` and `findings`. Changes require concrete findings; approval requires an empty findings array. Fleet accepts this verdict only after the exact turn completes and records it with that revision and receipt. Accepted or running turns keep their execution slot without a verdict. A lost acknowledgement reconciles the existing operation. Failed turns with transient capacity failures use the bounded provider retry path; other failed turns produce a decision waiting on the orchestrator. A malformed completed verdict gets one automatic follow-up on the same read-only reviewer thread requesting the required format. Fleet persists that attempt before submission and reconciles its receipt after restart; a second malformed reply produces a decision waiting on the orchestrator. Retry after that decision starts a fresh independent reviewer instead of parsing the same completed verdict again. When delivery observation finds a moved PR head after approval, Fleet verifies the current PR and its reserved paths, retains the prior result and review, clears stale checks and automatically starts a fresh independent reviewer before checks or delivery. The new result and review stage are persisted before reviewer launch so reconciliation can resume after restart. Retrying a stored moved-head decision observes the current PR and starts that review without re-parsing the old worker report, including when the prior review evidence is missing or stale. `src/engine/recoveryMatrix.spec.ts` covers both cases after restart.
+
+`src/engine/reviewerSession.spec.ts`, `src/engine/reviewerEvidence.spec.ts`, `src/engine/recovery.spec.ts`, `src/prompt/reviewer.test.ts` and `src/providers/readOnly.spec.ts` cover these boundaries with real PostgreSQL and synthetic providers; they do not prove live Cloud review.
+
+### Required checks
+
+The command host reads GitHub check runs and commit statuses through an authenticated `gh` CLI for the adopted PR's exact commit SHA, including all pages. It reads required status check contexts from `GET repos/{owner}/{repo}/rules/branches/{branch}` for the configured repository branch. Only required checks gate validation and send failures to repair; other checks remain in the evidence labelled non-required. Pending or absent required checks keep work in validation. With no required contexts configured, every observed check must succeed, be neutral or be skipped, and absent checks remain pending. A newer push does not replace the adopted head's evidence. If a check still fails after three consecutive completed check repairs, Fleet publishes an orchestrator decision naming it instead of launching another repair. The repair history survives restart; review repairs and changed failing check names do not count toward that check's limit. These observations do not establish merge authority. `src/host/githubChecks.test.ts` and `src/engine/validation.spec.ts` cover these rules with synthetic GitHub responses and real PostgreSQL.
+
+For built capabilities and open host integrations, see the [roadmap](https://github.com/ShivaeDev/platform/blob/main/packages/work-fleet/docs/roadmap.md).
+
+### Human delivery
+
+Fleet never submits a merge. Reviewed, green PRs wait on the maintainer as ready to merge. Reconciliation keeps observing the adopted PR through `gh pr view` with the host's existing CLI authentication, accepts only a merge of the reviewed head and records the PR head and merge commit. A PR closed without merging waits on the orchestrator with that fact. A head moved after approval goes through fresh independent review and checks automatically. A temporary observation failure preserves the current Board decision and ownership until GitHub evidence is available again. `src/host/githubDelivery.test.ts`, `src/engine/humanDelivery.spec.ts`, `src/engine/deliveryObservation.spec.ts`, `src/engine/movedHeadDelivery.spec.ts` and `src/engine/movedHeadRecovery.spec.ts` cover these rules with synthetic GitHub responses and real PostgreSQL.
+
+A ready-to-merge decision answered with `retry` and a nonempty overall response sends those requested changes to the existing worker thread on the same branch and PR. Fleet clears approval and checks before repair, then independently reviews and checks the worker's next result. A retry with an empty or whitespace-only overall response retains the approved head and republishes merge readiness. GitHub's explicit `CONFLICTING` mergeability observation sends an approved PR to its worker to merge main once per observed main revision; durable revision receipts prevent repeated automatic repair across restart. A conflict that remains after that repair waits on the orchestrator. `src/host/approvedRework.spec.ts` and `src/host/approvedConflict.spec.ts` cover these transitions through the HTTP daemon with real PostgreSQL and synthetic provider and GitHub responses.
+
+Main advancing alone does not invalidate adoption, review or validation of an unchanged PR head. `src/host/githubResult.test.ts` covers adoption while the base SHA moves without changes to the reported head or paths. `src/engine/behindMain.spec.ts` uses synthetic GitHub responses and real PostgreSQL to prove an approved, green, conflict-free head behind main stays ready through reconciliation and restart, then accepts its human merge without repeating review or validation.
+
+## Compose the Effect core
+
+Each scheduler pass shares a Board snapshot and identity index across admission, dispatch and reconciliation. Launch authorization calls `BoardGateway.get(workId, { fresh: true })` to reread the selected source and refresh its entry in that snapshot. Other item lookups retain their shared reads; the next pass reads changed, added and removed files again. `src/board/freshRead.spec.ts` proves the selected-source refresh and read failure behavior; `src/engine/closedDispatch.spec.ts` proves that a status change during preparation assessment inside a scheduler cycle prevents launch. Work revisions follow the authored brief read; approval is read separately, and decision publications retain their exact source revisions. Fleet's own publications enter the current snapshot after they are recorded; reconciliation that outlives the pass reads fresh sources.
+
+Fleet excludes files with invalid metadata or unreadable sources from admission, records a Board problem with the file and diagnostic, and retries them on the next pass. An unrelated invalid file leaves running work executing. A lookup of an invalid or missing work source still blocks that work; when metadata cannot supply its identity, the missing-identity diagnostic includes the Board file problems. The named problem reaches the execution status and the published decision, using the original approved context for publication. `src/host/boardReadErrors.spec.ts` proves admission, recovery, running-work isolation and named diagnostics against real PostgreSQL.
+
+Provide `BoardGateway`, `FleetRepository`, `FleetPolicy`, `FleetIntegrations` and `SessionService` to `Fleet.layer`. The Markdown gateway reads Board context, and `postgresFleetRepository(namespace?)` supplies durable SQL attachments on a native `SqlClient`. Fleet stores each record field in an effect-sql model column and persists foreign occupancy through a separate model repository. Versioned repository writes reject stale updates; the adapter retains Fleet’s one-based record versions. Startup migrates existing JSONB records into those columns, preserving nested values, record versions and admission order. `src/storage/modelMigration.spec.ts` reads every migrated record back unchanged and exercises updates and requeueing; `src/host/modelMigration.spec.ts` covers daemon HTTP reads and writes after startup migration.
+
+A session journal persists intents and acknowledged turns before further remote mutation. `src/session/service.test.ts` and `src/engine/recovery.spec.ts` cover receipt ordering and recovery without duplicate launch.
+
+```ts
+import { Fleet } from "@shivaedev/work-fleet/fleet.ts";
+import { cycle } from "@shivaedev/work-fleet/engine/scheduler.ts";
+
+const fleet = yield* Fleet;
+yield* fleet.prepare({ workId, preparation, prompt, cwd });
+yield* cycle;
+```
+
+Run this Effect program with your composed Fleet Layer. `FleetIntegrations` supplies source observations, actual result adoption, required checks and delivery observation. Its `result` implementation must re-read current result ownership and head each time it is called. Review and checks must name the exact adopted head; the reviewer must use a different session from the worker. `src/engine/completion.spec.ts` tests those requirements, repair and validated no-change with real PostgreSQL and synthetic integrations.
+
+Dependencies require accepted outcomes for their current authored brief revisions. Criterion-specific references remain blocked. `src/engine/dependencies.spec.ts` and `dependencyBookkeeping.spec.ts` cover those boundaries. The core's native RPC commands and derived views are covered by `src/engine/rpc.spec.ts` and `src/engine/activeViews.spec.ts`. These library tests do not prove live provider execution or delivery.
+
+### Errors and service declarations
+
+Fleet commands and daemon streams declare `BadRequest`, `Conflict`, `Forbidden`, `NotFound` and `ServiceUnavailable` from `@shivaedev/platform/errors/taxonomy.ts`. Invalid input, stale state, denied actions, missing records and unavailable integrations use those tags respectively. The RPC boundary maps storage conflicts to `Conflict` and admission failures to `Forbidden`; clients retain declared tags and messages in the error channel. Internal recovery metadata carries moved PR heads, conflicting main revisions and attention ownership without adding fields to platform errors. `src/host/errorChannels.spec.ts` checks all five tags through real daemon HTTP; `src/host/streamErrors.spec.ts` checks subscription errors through in-process native RPC; `src/exposeFailure.test.ts` checks storage translation, internal ownership, defects and interruption. The moved-head and attention-owner engine specs cover their recovery behavior against PostgreSQL.
+
+`Fleet`, `SessionService`, `MarkdownBoard`, `PostgresFleetRepository`, `FleetSessionJournal`, `GitMainSource`, `HostIntegrations`, `CodexLocal`, `CodexCloud`, `ReportBoard`, `ProviderHealth` and `StatusPublication` use `defineService`. Their Layers declare dependencies and keep initialization state private. The daemon, provider, journal, Board publication and status tests exercise those implementations through the existing ports.
+
+The following native Context services remain hand-written:
+
+| Services | Why |
+| --- | --- |
+| `BoardGateway`, `FleetRepository`, `FleetIntegrations`, `SessionTransport`, `SessionJournal`, `MainSource`, `ReportInspection` | Interchangeable ports for host adapters and test fixtures. The implementations declare their dependencies through `defineService`; the ports do not own initialization. |
+| `FleetPolicy`, `CodexLocalConfig`, `CodexCloudConfig`, `BoardRoot`, `RepositoryNamespace`, `ReportInputs`, `ProviderHealthState`, `StatusHealth` | Configuration and supplied values, including optional health state and bound integration callbacks. |
+| `Health`, `HealthSnapshot`, `HealthPublication` | Shared references and Effects consumed by scheduler and diagnostics composition. |
+| `Scheduler` | A scoped fiber handle. The daemon Layer controls listener-before-scheduler startup and joins that fiber. |
+
+## PostgreSQL test fixtures
+
+Fleet's PostgreSQL tests use `makeEffectIt` with effect-test-sql. `src/test-support/postgres.ts` prepares Fleet's migrations once for each worker fixture; `postgresTests("test")` uses the test clock and `postgresTests("live")` uses the live clock. Ordinary tests run inside `withTestTransaction`, so Fleet records, reservations and scope-finalizer writes roll back. `src/storage/fixtureIsolation.spec.ts` proves these boundaries against real PostgreSQL.
+
+Use `postgresTests("live", "isolated")` or its test-clock equivalent for concurrent database operations, migration tests and exact sequence state. These scenarios need separate native transaction connections or real commits. `withHost` acquires a clone through `withIsolatedDatabase` and supplies its URL to the daemon and subprocesses. Host connections and processes close before the kit drops that clone. Storage race, migration, daemon and restart tests exercise these paths.
+
+The tests use `PLATFORM_EFFECT_SQL_TEST_DATABASE_URL`, prepared by repository setup and CI. Local runs skip when it is absent; CI rejects its absence. Run `./script/update` to prepare the checkout, then `pnpm ready` for the complete PostgreSQL and packed-consumer checks.

package/dist/DecisionCode.d.ts

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+export declare const DecisionCode: Schema.Literals<readonly ["approval-required", "board-failure", "checks-repair-exhausted", "checks-result-invalid", "delivery-head-mismatch", "delivery-pr-required", "duplicate-turns", "empty-report", "fleet-denied", "fleet-integration", "fleet-invalid", "fleet-missing", "fleet-stale", "foreign-pr", "incomplete-context", "incomplete-observation", "integration-failure", "no-change-checks-unconfigured", "not-ancestor", "pr-conflicting", "pr-head-moved", "provider-quota-unavailable", "relevant-change", "report-published", "report-too-large", "result-identity-changed", "reviewed-pr-ready", "reviewer-terminal", "session-active-turn", "session-active-turn-exhausted", "session-ambiguous", "session-persistence", "session-protocol", "session-queue-full", "session-rejected", "session-stalled", "session-turn-missing", "session-unavailable", "worker-question", "worker-receipt-missing", "worker-report-head-invalid", "worker-report-head-moved", "worker-report-merged-head-mismatch", "worker-report-pr-invalid", "worker-terminal"]>;
+export type DecisionCode = typeof DecisionCode.Type;
+//# sourceMappingURL=DecisionCode.d.ts.map

package/dist/DecisionCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionCode.d.ts","sourceRoot":"","sources":["../src/DecisionCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,YAAY,wgCA8CvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAC"}

package/dist/DecisionCode.js

@@ -0,0 +1,49 @@
+import { Schema } from "effect";
+export const DecisionCode = Schema.Literals([
+    "approval-required",
+    "board-failure",
+    "checks-repair-exhausted",
+    "checks-result-invalid",
+    "delivery-head-mismatch",
+    "delivery-pr-required",
+    "duplicate-turns",
+    "empty-report",
+    "fleet-denied",
+    "fleet-integration",
+    "fleet-invalid",
+    "fleet-missing",
+    "fleet-stale",
+    "foreign-pr",
+    "incomplete-context",
+    "incomplete-observation",
+    "integration-failure",
+    "no-change-checks-unconfigured",
+    "not-ancestor",
+    "pr-conflicting",
+    "pr-head-moved",
+    "provider-quota-unavailable",
+    "relevant-change",
+    "report-published",
+    "report-too-large",
+    "result-identity-changed",
+    "reviewed-pr-ready",
+    "reviewer-terminal",
+    "session-active-turn",
+    "session-active-turn-exhausted",
+    "session-ambiguous",
+    "session-persistence",
+    "session-protocol",
+    "session-queue-full",
+    "session-rejected",
+    "session-stalled",
+    "session-turn-missing",
+    "session-unavailable",
+    "worker-question",
+    "worker-receipt-missing",
+    "worker-report-head-invalid",
+    "worker-report-head-moved",
+    "worker-report-merged-head-mismatch",
+    "worker-report-pr-invalid",
+    "worker-terminal",
+]);
+//# sourceMappingURL=DecisionCode.js.map

package/dist/DecisionCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionCode.js","sourceRoot":"","sources":["../src/DecisionCode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC3C,mBAAmB;IACnB,eAAe;IACf,yBAAyB;IACzB,uBAAuB;IACvB,wBAAwB;IACxB,sBAAsB;IACtB,iBAAiB;IACjB,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,eAAe;IACf,eAAe;IACf,aAAa;IACb,YAAY;IACZ,oBAAoB;IACpB,wBAAwB;IACxB,qBAAqB;IACrB,+BAA+B;IAC/B,cAAc;IACd,gBAAgB;IAChB,eAAe;IACf,4BAA4B;IAC5B,iBAAiB;IACjB,kBAAkB;IAClB,kBAAkB;IAClB,yBAAyB;IACzB,mBAAmB;IACnB,mBAAmB;IACnB,qBAAqB;IACrB,+BAA+B;IAC/B,mBAAmB;IACnB,qBAAqB;IACrB,kBAAkB;IAClB,oBAAoB;IACpB,kBAAkB;IAClB,iBAAiB;IACjB,sBAAsB;IACtB,qBAAqB;IACrB,iBAAiB;IACjB,wBAAwB;IACxB,4BAA4B;IAC5B,0BAA0B;IAC1B,oCAAoC;IACpC,0BAA0B;IAC1B,iBAAiB;CACjB,CAAC,CAAC"}