@wardby/cli 0.4.1 → 0.5.0

package/docs/code-review-agents.md

@@ -7,6 +7,9 @@ GitHub App: reviewing pull requests automatically and responding to
 opens draft PRs — a review agent only reads a repository and posts comments,
 inline suggestions, and a check result.
 
+A review agent can also review a branch of a git repository on the wardby host,
+without a GitHub App; see [Local repositories](coding-agent-setup.md#local-repositories).
+
 ## What a linked review agent does
 
 Once an agent is linked to a repository with the `pull_request` trigger:
@@ -142,8 +145,23 @@ PR description:
   same GitHub App opened the PR), no run starts: the App replies that this
   deployment cannot continue the PR, so ask the deployment that opened it.
   If a router agent passes a `continuePriorRun` id that this deployment
-  cannot continue, the delegation returns a `continuation_refused` tool
-  error to the agent instead of failing its run.
+  cannot continue — a continuation is also refused when the run it names
+  was opened by another owner's agent, even if the lead and the continuing
+  sub-agent share an owner (see
+  [Nothing crosses owners without a grant](security-deployment.md#sharing-agents))
+  — the delegation returns a `continuation_refused` tool error to the agent
+  instead of failing its run.
+- A continuation never pushes to a pull request that is no longer open.
+  Wardby asks GitHub whether the pull request is still open before cloning,
+  and again right before it pushes. A pull request merged or closed before
+  the run starts is caught before cloning: the run is refused, having spent
+  nothing beyond setup. One merged or closed while the run was working is
+  caught right before the push: that run ends failed and its work is not
+  pushed. The category is `continuation_closed` either way. A transient
+  GitHub failure while checking (a timeout, rate limit, or 5xx) is retried
+  once, after a short wait, and failing that, the run proceeds rather than
+  being stopped on an unconfirmed answer — see
+  [Continuation's pull request is no longer open](../help/errors/continuation-closed.md).
 - The header reads `[GitHub issue #<n>]` on an issue. For a mention inside an
   inline review thread, the `Requested by` line ends with
   `(in review thread <id>)`.
@@ -170,6 +188,89 @@ PR description:
   agent can reach only the tools and access you would give that outsider's
   text.
 
+## Automatic review fix rounds
+
+Linking an agent with the `review_fix` trigger (`access: "write"`, at most
+one per repository) lets wardby fix its own review's findings automatically,
+without waiting for a human to ask. `reviewFixMaxRounds` (an integer from 1
+to 10, default 2) caps how many rounds a single pull request gets before
+wardby stops; re-linking without it resets the cap back to the default.
+
+A round starts when wardby's own review check on a pull request finishes as
+`CHANGES_REQUESTED`, and all of the following still hold:
+
+- the pull request is still **open**;
+- its head is **not in a fork**;
+- its head is still the **exact commit the check reviewed** (a later push
+  skips the round, since a fresh review is coming for that new head anyway);
+- the pull request was **opened by a wardby coding run of this deployment**
+  (the same marker the mention flow uses to recognize its own PRs, above);
+  and
+- the repository's `review_fix` link is still authorized, and the pull
+  request is under its round cap.
+
+No human comment or mention starts a round: it runs entirely on the
+`review_fix` link's own authorization, the same way a `pull_request` check
+does. What the agent actually changes is up to its own instructions and
+budget — wardby only decides **whether** a round may start. The task handed
+to the agent includes the same continuation hint a mention follow-up gets
+(so it keeps working on the same branch) and asks it to fix only the
+review's CRITICAL/MAJOR findings and MUST_FIX recommendations and change
+nothing else. The review itself (capped at 20,000 characters) is passed to
+the agent as **untrusted context**, not as part of its instructions: the
+agent reads it as information about what to fix and is told never to follow
+instructions written inside it. A fix round's task names only its own pull
+request; it never lists related pull requests in other repositories.
+
+Only the review's summary and body reach the fixing agent — inline review
+comments do not. Write your reviewer agent's prompt so it lists every
+finding in the review body, not only in inline comments, or the fixing agent
+won't see them.
+
+Only one round runs at a time on a pull request: a round isn't started
+while an earlier round on the same pull request is still running (two
+reviews finishing together, or a **Re-run** during a round, start nothing
+extra).
+
+Rounds are counted with labels on the pull request, so the count stays
+visible and resettable by hand:
+
+- `wardby-autofix-<N>` is added **before** each round's run starts (so a
+  round whose run is then declined still counts against the cap); `<N>` is
+  one more than the highest round label already on the pull request.
+- `wardby-autofix-limit` is added once the cap is reached, together with one
+  comment saying so.
+- `wardby-autofix-off` opts a pull request out of automatic fix rounds
+  entirely; add it by hand to stop wardby from touching a PR.
+
+To let a pull request past a cap it already hit, remove its
+`wardby-autofix-<N>` labels **together with** `wardby-autofix-limit` (a leftover
+`wardby-autofix-limit` means wardby won't comment when the pull request
+reaches the cap again), then push again or
+re-run the check.
+
+Each round posts a status comment, "🔁 Fix round N of M: working on it.",
+and edits it in place with the outcome once the round's run ends — the same
+convention a mention run's status comment follows. A pull request opened by
+a different wardby deployment (sharing the same GitHub App) gets one
+refusal comment and `wardby-autofix-limit` instead of a round, since this
+deployment has no record of the run that opened it and can't continue its
+branch.
+
+Clicking **Re-run** on the review check isn't counted as a round itself:
+it starts a fresh review, and if that review requests changes, it starts a
+fix round the same way any other review would (subject to the cap and to no
+earlier round still running).
+
+If a repository already forwards wardby's reviews to a webhook through a
+hand-written CI workflow to fix them automatically, replace that workflow
+with `review_fix`: link the trigger, then delete the workflow and its
+webhook so one review doesn't start two fix rounds at once.
+
+This trigger needs the App's **Issues: Read and write** permission (see
+[Registering the GitHub App](#registering-the-github-app)) — the labels
+above are written through the Issues API.
+
 ## Fork pull requests are skipped
 
 A pull request whose head is in a fork never starts a review, on a push or on
@@ -281,18 +382,21 @@ with:
   below) — generate it with `openssl rand -hex 32` or similar; the ingress
   endpoint answers 404 until this is set.
 - **Subscribe to events**: Pull request, Issue comment, Pull request review
-  comment, Check run, Issues (needed for mentions in a newly opened or
+  comment, Check run, Check suite (re-runs a review that was waiting for CI
+  once CI finishes, and starts a `waitForCi` reviewer's held review once CI
+  finishes), Issues (needed for mentions in a newly opened or
   edited issue; without it only comment mentions are seen), and Push (needed
   for the `push` trigger, which starts merge-watcher agents; it is its own
   checkbox, separate from the others, and must be ticked explicitly).
 - **Repository permissions**:
 
-  | Permission    | Access         |
-  | ------------- | -------------- |
-  | Contents      | Read           |
-  | Pull requests | Read and write |
-  | Checks        | Read and write |
-  | Issues        | Read and write |
+  | Permission      | Access          |
+  | --------------- | --------------- |
+  | Contents        | Read            |
+  | Pull requests   | Read and write  |
+  | Checks          | Read and write  |
+  | Issues          | Read and write  |
+  | Commit statuses | Read (optional) |
 
   To let review agents resolve their own fixed threads, set **Contents** to
   **Read and write**: GitHub gates resolving a review thread on that
@@ -300,6 +404,19 @@ with:
   only for the resolve call itself. An App that also opens coding pull
   requests already has it.
 
+  **Issues: Read and write** is also what lets wardby add and remove the
+  `wardby-autofix-*` labels used by [automatic review fix
+  rounds](#automatic-review-fix-rounds): GitHub serves pull-request labels
+  through the Issues API.
+
+  **Commit statuses: Read** is optional: with it, `repo_pr_read`'s `ci`
+  includes commit statuses (CI systems that report statuses rather than
+  check runs); without it, only check runs are listed and
+  `ci.statusesUnavailable` is `true`. Reading check runs uses the existing
+  **Checks** permission. Adding the permission to an installed App is an
+  upgrade step: every installation must accept the new permission set (see
+  the paragraph below).
+
 If you change these permissions on an App that is already installed, every
 installation must explicitly accept the new permission set before the App's
 webhooks resume working for it.
@@ -368,9 +485,9 @@ linking stays disabled there.
 First link your GitHub account (`link_host_account`, above). Then use the
 `link_repository` tool (agents:write) on a native agent you own. Calling it
 again for an already-linked repository replaces that link's `access`,
-`triggers`, and `checkName` — omitted fields are cleared, not kept — and
-checks your access again, so always send the full desired state. Two common
-shapes:
+`triggers`, `checkName`, `reviewFixMaxRounds`, and `waitForCi` — omitted
+fields are cleared, not kept — and checks your access again, so always send
+the full desired state. Two common shapes:
 
 **A reviewer**, which starts a check on every PR push:
 
@@ -384,6 +501,10 @@ shapes:
 }
 ```
 
+Add `"waitForCi": true` to a `pull_request` link to hold the reviewer's
+review of a pushed head until that head's own CI finishes, instead of racing
+it — see [Review after CI (`waitForCi`)](#review-after-ci-waitforci) below.
+
 **A responder**, which only answers `@<app-slug>` mentions that are not a
 review command:
 
@@ -408,21 +529,36 @@ branch (see [Drift runs on merge](knowledge.md#drift-runs-on-merge)):
 }
 ```
 
+**A review-fix agent**, which wardby starts automatically to fix its own
+review's findings (see [Automatic review fix rounds](#automatic-review-fix-rounds)):
+
+```json
+{
+  "agentId": "<agent-id>",
+  "repository": "owner/name",
+  "access": "write",
+  "triggers": ["review_fix"],
+  "reviewFixMaxRounds": 2
+}
+```
+
 The `push` trigger is for native agents only and takes no `checkName`. Unlike
 `mention`, several agents may hold it on one repository, but one watcher per
 repository is the recommended shape. Only pushes to the default branch start a
 run; tags, other branches, and branch deletions are ignored.
 
 Only one agent per repository may hold the `mention` trigger, and only one
-link per repository may use a given `checkName` (whatever its triggers; the
-database enforces it); linking a second agent the same way returns a 409
-conflict. A `checkName` is only allowed together with the `pull_request`
-trigger, which requires one. (The migration that introduced these rules
-cleared the `checkName` of every link without the `pull_request` trigger: if
-a branch-protection required check relied on such a name, it no longer
-reports.) `access: "read"` may be used without event triggers to let the
-agent's `repo_*` tools read a repository on demand without ever being
-dispatched by a webhook.
+agent per repository may hold the `review_fix` trigger; only one link per
+repository may use a given `checkName` (whatever its triggers; the database
+enforces it). The one-`mention`-agent and one-`review_fix`-agent rules above
+are enforced by `link_repository` itself. Violating any of the three returns
+a 409 conflict. A `checkName` is only allowed together with the
+`pull_request` trigger, which requires one. (The migration that introduced
+these rules cleared the `checkName` of every link without the
+`pull_request` trigger: if a branch-protection required check relied on
+such a name, it no longer reports.) `access: "read"` may be used without
+event triggers to let the agent's `repo_*` tools read a repository on
+demand without ever being dispatched by a webhook.
 
 The errors you may get while linking:
 
@@ -431,17 +567,118 @@ The errors you may get while linking:
 | 400    | `owner_required`: the agent has no owner. Or a malformed request (e.g. `checkName` without `pull_request`).       |
 | 403    | Your GitHub account is not linked (`link_host_account`), or its access to the repository is below what is needed. |
 | 403    | `adminOverride` from a caller without the `admin` role.                                                           |
-| 409    | Another agent already holds the `mention` trigger or this `checkName` on the repository.                          |
+| 409    | Another agent already holds the `mention` or `review_fix` trigger, or this `checkName`, on the repository.        |
 | 503    | GitHub could not be asked (e.g. the App isn't installed on the repository). Nothing was changed.                  |
 
+### Review after CI (`waitForCi`)
+
+`waitForCi` (boolean, default `false`, only on a `pull_request` link — 400
+otherwise) holds a reviewer's review of a pushed head until that head's own
+CI has finished, instead of racing it. "CI" means exactly what
+`repo_pr_read`'s `ci` field means: the repository's own check runs and
+commit statuses on the pull request's head commit, excluding every check
+wardby itself reports. It is decided per pull request — a `waitForCi`
+reviewer never waits on, or looks at, any other pull request's CI.
+
+**The flow.** On a push to the pull request (opened, a new commit,
+reopened, or marked ready for review), wardby reads CI on the new head
+before starting a `waitForCi` reviewer:
+
+- CI already `passing`, `failing`, `inconclusive`, or `unavailable` starts
+  the review immediately, exactly as without `waitForCi`.
+- CI `pending`, or nothing reported yet (`none` — normal right after the
+  pull request opens, before checks have registered), holds the review
+  instead of starting it. Wardby re-reads CI once more right after holding
+  it, in case it finished in the moment in between, and starts the review
+  then if so.
+- When a check suite completes on that head (the same **Check suite** event
+  used by [re-review when CI finishes](#the-repo_-tools) below — no extra App
+  configuration needed), wardby reads CI again for every review it is
+  holding on that head. If CI has finished, the held review starts; if
+  something is still pending, a later completion decides. CI that reports
+  only commit statuses (no check suites) never triggers this early release,
+  nor does a commit status still pending when the last check suite finishes
+  — a review held for either reason only starts at the fallback below.
+
+**Fallback: 15 minutes.** A review wardby is still holding 15 minutes after
+it was deferred starts anyway, without waiting further for CI — the
+APPROVE gate below still applies, so a verdict chosen while CI is still
+pending will usually come out as `COMMENT`. CI that never reports, or runs
+unusually long, cannot hold a review forever because of this fallback.
+Both the fallback and the 24-hour drop below run only where wardby's
+reconciliation sweep runs: the `wardby scheduler` process, or `wardby
+serve` with the scheduler started in the same process. An instance running
+only `wardby mcp`, with no scheduler, never applies either on its own — a
+review held there starts only once a **Check suite** event arrives, or once
+an instance that does run the sweep reaches it; with status-only CI (or no
+scheduler at all) such a review can wait indefinitely. A held review is
+dropped without starting if it is still waiting after 24 hours, or if the
+pull request's head has since moved on or the pull request closed (a newer
+push, if any, is held and decided on its own terms).
+
+**The APPROVE gate.** For a reviewer linked with `waitForCi`,
+`repo_publish_review` refuses an `APPROVE` verdict on the pull request its
+run owns the check for while CI on that head is not clearly passing:
+
+| Tool error   | When                            | What to do instead                                                           |
+| ------------ | ------------------------------- | ---------------------------------------------------------------------------- |
+| `ci_failing` | CI on the head is failing       | Publish `CHANGES_REQUESTED` (or `COMMENT`) describing the CI failure instead |
+| `ci_pending` | CI on the head is still running | Publish `COMMENT`; the review runs again once a CI check suite finishes      |
+
+Nothing is published when either error is returned — no inline comments, no
+summary, no check — so the model's next call is free to choose a different
+verdict. `CHANGES_REQUESTED` and `COMMENT` verdicts are never affected by
+this gate, on any link, and it never applies to a link without `waitForCi`.
+When CI cannot be read at all (the host has no CI reader, or reading it
+fails), the gate is skipped and the call proceeds as if `waitForCi` were
+off: a read failure fails toward letting a human-reviewable result through,
+not toward silently blocking an approval.
+
+**Interaction with re-review-when-CI-finishes.** The existing behaviour of
+re-running a review that published only `COMMENT` while CI was pending, once
+CI on that head finishes (see [re-review when CI finishes](#the-repo_-tools)
+below), keeps working the same way regardless of `waitForCi`. A `waitForCi`
+reviewer that the APPROVE gate above pushed into publishing `COMMENT`
+because CI was pending is re-run by that same mechanism once CI finishes,
+exactly like a reviewer without `waitForCi` that chose `COMMENT` for its own
+reasons. Both mechanisms may react to the same CI completion, but each only
+acts on the state it owns — a review still held and not yet started, versus
+one already published as `COMMENT` — so one reviewer is never run twice on
+the same head because of it.
+
+Turning `waitForCi` off (re-linking without it, or with it set to `false`)
+only changes how future pushes are handled; it never retroactively starts or
+drops a review already being held.
+
 ## The `repo_*` tools
 
 A linked agent gets these built-in tools automatically — they are not
 attached like ordinary tools, and never expose a token, check id, or
 internal marker to the model:
 
-- `repo_pr_read` — a pull request's metadata, per-file diff patches, and
-  the agent's own unresolved inline threads (`openThreads`).
+- `repo_pr_read` — a pull request's metadata, per-file diff patches, the
+  agent's own unresolved inline threads (`openThreads`), and `ci`: the head
+  commit's check runs and commit statuses, excluding every check the wardby
+  App itself reported (review checks, `wardby/continuation`), with `state`
+  (`passing`, `failing`, `pending`, `inconclusive`, `none`, `unavailable`),
+  `truncated`, `statusesUnavailable`, `sandboxInstallIncomplete` (the
+  description carries the **Dependency install incomplete** warning) and a
+  `note` telling the agent to follow CI over the description's **Tests**.
+  Reading CI never makes `repo_pr_read` fail: an unreadable result is
+  `state: "unavailable"` with `unavailableReason`. At most 50 results are
+  listed; names are capped at 100 characters.
+- **Re-review when CI finishes.** When a review publishes `COMMENT` on its
+  own check while CI on that head is `pending` or `none`, Wardby records it.
+  When a CI check suite (not Wardby's own) completes on that head and no CI
+  there is still running, Wardby runs the same reviewer again on the same
+  head. It does this at most once per head commit and reviewer, only while the pull
+  request is open and its head has not moved, and only for reviewers whose
+  repository access is still authorized. It needs the App's **Check suite**
+  event. CI that reports only commit statuses does not send check suite
+  events, so it never triggers a re-review; and when CI mixes check suites
+  with commit statuses, a status still pending as the last suite finishes
+  means no re-review happens. Use **Re-run** on the review check in both
+  cases.
 - `repo_read_file` / `repo_list_files` — read a file or list a directory at
   a ref.
 - `repo_publish_review` — publish inline comments, a summary, and the check
@@ -461,26 +698,44 @@ internal marker to the model:
 Every call names the `repository` explicitly; it must resolve to one of the
 agent's links. Failures are always a JSON result, never a thrown error:
 
-| `error` code                    | Meaning                                                                                                                                                |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `invalid_arguments_json`        | The tool call's arguments were not valid JSON.                                                                                                         |
-| `invalid_arguments`             | Arguments failed schema validation (missing/malformed field).                                                                                          |
-| `repository_not_linked`         | `repository` does not match one of this agent's links, or matches more than one and needs a `host/owner/name` prefix to disambiguate.                  |
-| `write_access_required`         | A write tool (`repo_publish_review`, `repo_comment`) was called on a read-only link.                                                                   |
-| `repository_access_denied`      | The link is no longer authorized: the agent has no owner, the owner's GitHub account is unlinked or lost access, or it could not be checked.           |
-| `repository_access_unavailable` | GitHub could not be reached (or rate-limited wardby) while re-checking access, even after one retry; the call was refused for safety. Try again later. |
-| `host_not_configured`           | No host provider is configured for this link on this deployment.                                                                                       |
-| `unknown_tool`                  | Not a recognized `repo_*` tool name.                                                                                                                   |
-| `host_not_installed`            | The GitHub App is not installed on this repository.                                                                                                    |
-| `host_permission_missing`       | The App installation is missing a required permission.                                                                                                 |
-| `host_invalid_response`         | The host returned something the client could not parse.                                                                                                |
-| `host_api_error`                | The request to GitHub failed (body-free: `github_api_error:<status>[:<request-id>]`).                                                                  |
+| `error` code                    | Meaning                                                                                                                                                                           |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid_arguments_json`        | The tool call's arguments were not valid JSON.                                                                                                                                    |
+| `invalid_arguments`             | Arguments failed schema validation (missing/malformed field).                                                                                                                     |
+| `repository_not_linked`         | `repository` does not match one of this agent's links, or matches more than one and needs a `host/owner/name` prefix to disambiguate.                                             |
+| `write_access_required`         | A write tool (`repo_publish_review`, `repo_comment`) was called on a read-only link.                                                                                              |
+| `repository_access_denied`      | The link is no longer authorized: the agent has no owner, the owner's GitHub account is unlinked or lost access, or it could not be checked.                                      |
+| `repository_access_unavailable` | GitHub could not be reached (or rate-limited wardby) while re-checking access, even after one retry; the call was refused for safety. Try again later.                            |
+| `host_not_configured`           | No host provider is configured for this link on this deployment.                                                                                                                  |
+| `unknown_tool`                  | Not a recognized `repo_*` tool name.                                                                                                                                              |
+| `host_not_installed`            | The GitHub App is not installed on this repository.                                                                                                                               |
+| `host_permission_missing`       | The App installation is missing a required permission.                                                                                                                            |
+| `host_invalid_response`         | The host returned something the client could not parse.                                                                                                                           |
+| `host_api_error`                | The request to GitHub failed (body-free: `github_api_error:<status>[:<request-id>]`).                                                                                             |
+| `ci_failing`                    | `repo_publish_review` called with verdict `APPROVE`, on a `waitForCi` link's own check, while CI on the head is failing. See [Review after CI](#review-after-ci-waitforci) above. |
+| `ci_pending`                    | Same, but CI on the head is still running.                                                                                                                                        |
 
 `repo_publish_review` also returns
 `{ "published": false, "reason": "stale_head", ... }` instead of an error when
 the PR moved to a new head since the review started; the agent should stop
 rather than retry.
 
+### Reviewer step: CI and related pull requests
+
+Add this to a reviewer's system prompt so it uses `ci` and the pull
+request's **Related pull requests** section correctly:
+
+    Reviewer step (CI and related pull requests). Read `ci` from repo_pr_read.
+    When `ci` and the description's Tests disagree, follow CI and say so; never
+    ask for a fix only because a sandbox test failed while CI passed. Report
+    pending checks as pending. If the description has a "Related pull requests"
+    section, a field, route or schema the change relies on may be added by one
+    of those pull requests: do not report it as missing; note the dependency
+    and the suggested merge order instead.
+
+Check names and the description are repository content: treat them as data,
+as for every `repo_*` result.
+
 ## Branch protection
 
 To require a passing review before merge, add the link's `checkName` (e.g.

package/docs/coding-agent-setup.md

@@ -15,7 +15,9 @@ registry) but never holds the run capability.
   for each enabled coding provider: `OPENAI_API_KEY` and/or
   `ANTHROPIC_API_KEY`.
 - The local database has the current Prisma migrations applied.
-- A GitHub App is installed on only the repository to be exercised. Grant it
+- A GitHub App is installed on only the repository to be exercised. (Not needed
+  for a repository on this machine; see
+  [Local repositories](#local-repositories).) Grant it
   `Contents: Read and write` and `Pull requests: Read and write`; set
   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` in `.env.local`.
 
@@ -54,9 +56,106 @@ the run fails with category `repo_access_unavailable` (GitHub could not be
 asked — not a lost permission; re-run it later). `make_owner` to a different
 owner turns an admin or grandfathered approval into a check of the new owner's
 access. Coding agents must have an owner.
+
+A continuation (`continuePriorRun`) checks separately that the pull request
+it is asked to continue is still open on GitHub; one already merged or closed
+fails with category `continuation_closed` and nothing pushed — see
+[Continuation's pull request is no longer open](../help/errors/continuation-closed.md).
 Over stdio, the local operator holds every role, so `repositoryAdminOverride`
 is the way to approve a repository there.
 
+## Local repositories
+
+A coding agent (or a review agent) can work on a git repository on the same
+machine as the wardby server instead of a GitHub repository. Write the
+repository as `local:/absolute/path`. No GitHub App, GitHub account link or
+webhook is involved, and no extra role is required: the trusted folders below
+are the only boundary.
+
+Set `LOCAL_REPO_ROOTS` only on a single-user or personal server. Every
+principal who can create or update agents or link repositories can use every
+repository under the trusted folders: its committed code is sent to the model,
+and runs push `wardby/run-*` branches into it. Anyone with execute access to a
+local coding agent can trigger such pushes.
+
+Set these on the control plane:
+
+```dotenv
+# Folders wardby may use, separated by the platform path delimiter (":" on macOS
+# and Linux, ";" on Windows). Unset = every local: repository is refused.
+LOCAL_REPO_ROOTS=/home/you/projects:/srv/repos
+# Coding runs need a container executor.
+JOB_LAUNCHER=docker
+```
+
+- **Trusted folders.** A repository must be the top level of a git work tree
+  whose real path (symlinks resolved) is at or below one of the folders.
+  Wardby stores the repository by that real path and checks the folders again
+  when an agent is created or updated, a repository is linked, a run is
+  triggered, and while a run uses the repository. A change to the variable takes
+  effect after a restart. An outside path fails with `local_repo_not_allowed`.
+- **Launcher.** With `JOB_LAUNCHER=local` a coding run ends with "Coding agents
+  need a container executor"; use `docker` or `kubernetes`. Review agents are
+  native agents and do not need a worker.
+- **The server runs on the host.** Wardby reads and writes the repository
+  directly, so the control plane must not run in a container, a pod or on
+  another machine. A trusted folder the server cannot see is ignored, so its
+  repositories fail with `local_repo_not_allowed`, and `doctor` reports the
+  folder as missing. The machine needs git 2.24 or newer.
+- **Worker images.** Use worker images from the same release as the control
+  plane. An older worker image rejects `local:` repositories (the run fails with
+  `worker_input_failed`), including a bring-your-own `workerImageRef` image,
+  which must be rebuilt on a current driver image.
+
+### What a coding run does
+
+1. Wardby clones the repository's **committed** history at the base ref
+   (`baseRef`, default the profile's). Untracked and uncommitted files, such as
+   `.env.local`, never leave the host. `trigger_agent` returns `warnings` when
+   the working tree is dirty or the repository uses submodules or Git LFS;
+   uncommitted changes are not included, and submodules and LFS are not
+   supported (submodules are not initialized, LFS files are not fetched).
+2. The worker runs in the usual sandbox. `.wardby/services.yaml` works: it is
+   read from the committed file at the base ref (never the working tree) and
+   fails with the same errors as on GitHub (see [coding-services.md](coding-services.md)).
+3. Wardby validates the result and pushes one commit to the branch
+   `wardby/run-<run id>` in the source repository. Your working tree, index
+   and checked-out branch are never modified. `get_run` reports `resultBranch`
+   and `baseSha`.
+4. The repository's own receive-side hooks (`pre-receive`, `update`,
+   `post-receive`) run on that push, as they would for any push.
+
+To build on an earlier result, trigger with `baseRef: "wardby/run-<run id>"`. A
+continuation of a run (a lead agent revising its earlier work) fast-forwards the
+same branch; if the branch has moved, or is checked out, the run fails with
+`local_branch_conflict` and nothing is pushed.
+
+Result branches accumulate, and wardby does not delete them. Clean up with
+`git branch -D wardby/run-<run id>`.
+
+### Review agents
+
+Link a native review agent with `link_repository` (`provider: "local"`,
+`repository: "local:/absolute/path"`, `access: "write"`). A local link is
+manual only: it takes no `triggers` and no `checkName`, and event triggers
+(`pull_request`, `push`, `mention`, `review_fix`) are rejected. The agent's
+owner starts a review with:
+
+```json
+{ "agentId": "<review agent id>", "review": { "branch": "wardby/run-<run id>", "base": "main" } }
+```
+
+`repository` defaults to the agent's only local link, and `base` to the branch
+checked out in the repository. The `repo_*` tools work unchanged and read
+committed content at the branch, never the working tree. `get_run` returns the
+result in `review` (`number`, `branch`, `base`, and `reviews` with `verdict`,
+`summary`, `body` and `comments`). There are no check runs and no CI results.
+
+### Quickstart
+
+`quickstart` can set all of this up. See the coding step in
+[Getting started](getting-started.md#coding-agents-on-a-local-repository).
+
 ## Start the trusted proxy
 
 Run these commands from the repository root:
@@ -72,10 +171,20 @@ The image commands create local tags. Resolve every enabled image with
 `sha256:...` ID in `.env.local`; do not use the mutable tag at runtime. Add the
 following values, replacing image IDs and GitHub values:
 
+Set the images for the providers you use: `CODING_WORKER_IMAGE` for Codex
+agents, and the `CODING_CLAUDE_*` pair for Claude Code agents. Each provider's
+images are optional, but at least one provider must be configured. A Claude-only
+deployment can leave `CODING_WORKER_IMAGE` unset (and skip
+`npm run worker:image:local`); a Codex agent there is then refused with
+`coding_provider_not_configured:codex` unless it names its own worker image
+(see [Coding provider not configured](../help/errors/coding-provider-not-configured.md)).
+
 ```dotenv
 # Leave this as local until every value below is set and reviewed.
 JOB_LAUNCHER=local
+# Codex agents only:
 CODING_WORKER_IMAGE=sha256:replace-with-worker-image-id
+# Claude Code agents only (both or neither):
 CODING_CLAUDE_WORKER_IMAGE=sha256:replace-with-claude-worker-image-id
 CODING_CLAUDE_TOOL_RUNNER_IMAGE=sha256:replace-with-claude-tool-runner-image-id
 # Only for Claude Code agents on the node-python toolchain (version 3.12):
@@ -107,7 +216,9 @@ change `JOB_LAUNCHER=docker` and run:
 npm run cli -- coding preflight
 ```
 
-The preflight checks that Docker can inspect the immutable worker image. A real
+The preflight checks that every configured worker image (the Codex worker and/or
+the Claude Code worker and tool runner) is immutable and that Docker can inspect
+it. A real
 run additionally verifies the proxy's isolated-network attachment immediately
 before launching the worker.
 
@@ -153,6 +264,16 @@ Native runs are served first come, first served: a native run only counts the
 holds of runs that started before it, so members dispatched on the same tick
 don't starve each other.
 
+Sub-agents dispatched together by a lead with `parallelDelegations` share the
+run tree the same way: each in-flight sibling's unspent reservation counts
+against the tree, so they can never jointly reserve more than the lead's
+budget. A sibling admitted after the tree is spent waits for another
+still-running sibling to finish and free its reservation, then retries, up to
+roughly its own normal wait bound — so the total wait can reach about twice
+that bound before it gives up. With no sibling still running, it is refused
+immediately with `run_tree_exhausted`. The check that triggers the wait is an
+estimate, so a retry can still end in the same refusal.
+
 A hold lapses by itself when the run stops showing signs of life, so a crashed
 process or an interrupted `wardby run` cannot pin a group for the rest of the
 period. A run holds while its last heartbeat (or its start, before the first
@@ -165,6 +286,24 @@ recorded cost always counts. `wardby run` records the run as `cancelled` on
 Ctrl-C or SIGTERM. If a row is still stuck in `running` for another reason,
 only its real cost counts once its hold lapses.
 
+## Turn limit (Claude Code)
+
+A Claude Code run stops after a fixed number of agent turns (model calls),
+200 by default. Every file it reads, command it runs and edit it makes is a
+turn, so raise the limit for agents that make large changes, or lower it to
+stop runaway loops sooner:
+
+```json
+{ "id": "<coding agent id>", "codingProfile": { "maxTurns": 400 } }
+```
+
+`maxTurns` is 1 to 1000; `null` restores the default. It is fixed on each run
+when the run is dispatched. A run that reaches it fails with failure category
+`turn_limit` (worker error `coding_turn_limit`) rather than a generic stream
+failure. The run's `budgetUsd` and `timeoutSec` still apply and are usually the
+better limits. Codex runs have no turn limit, so `maxTurns` does not affect
+them.
+
 ## Stop the setup
 
 ```sh

package/docs/coding-packages.md

@@ -401,6 +401,27 @@ and 100 refusals, followed by "…and N more — see get_run for the full list";
 `get_run` always has the complete list. If the report can't be loaded or
 rendered, the section is left out and the pull request is still opened.
 
+When the registry refused anything during the run, the pull request also
+opens with a **Dependency install incomplete** warning, above the agent's
+summary. It names the refused packages grouped by refusal code, says what
+each code means, and notes that failed checks under **Tests** may come from
+the sandbox rather than the change. If the run changed a lock file
+(`package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml`,
+`poetry.lock`, `uv.lock` or `Pipfile.lock`), the warning names it: the lock
+file may be missing entries, so a clean install in CI can fail until it is
+regenerated outside the sandbox. Wardby writes this from the registry's
+records and the run's diff, not from the agent's summary.
+
+Review agents see the pull request's CI results through `repo_pr_read`
+(`ci`), and its note tells them to trust CI over a sandbox **Tests**
+failure; see
+[code-review-agents.md](code-review-agents.md#the-repo_-tools).
+
+A package that is only reachable through a refused one is refused too, as
+`wardby_package_not_allowed`. When a dependency deep in a toolchain has a
+high-severity advisory and no fixed version, every run that installs that
+tree is refused at the same place; approving more packages won't help.
+
 ## Error codes
 
 npm and pip print the proxy's error body verbatim, so these are what you'll