@wardby/cli 0.4.1 → 0.5.1

package/help/getting-started.md

@@ -19,6 +19,34 @@ The quickstart creates local state under `.wardby/`, starts the local services,
 applies the required database migrations, and can register Wardby with Codex or
 Claude Code. Run `wardby doctor` afterwards to verify the local installation.
 
+## Coding and review agents: pick a path
+
+- **A. Try them locally, no GitHub App.** Run
+  `npx --yes @wardby/cli@latest quickstart --coding --trust <repo-or-folder>`
+  (or answer yes to the coding step). It creates `local-builder` and
+  `local-reviewer` for a git repository on your machine. Run the builder with
+  `trigger_agent {"agentId": "<id>", "task": "..."}`. It pushes a branch
+  `wardby/run-<run id>` into your repository and leaves your checkout alone.
+  Review that branch with
+  `trigger_agent {"agentId": "<reviewer id>", "review": {"branch": "wardby/run-<run id>"}}`.
+  You need Docker and an OpenAI key (Codex) or an Anthropic key (Claude Code).
+  See [Use local git repositories](local-repositories.md).
+- **B. A coding agent that opens GitHub pull requests.** Do A first. Then
+  install a GitHub App on the repository (Contents and Pull requests: read and
+  write), add `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` to `.wardby/.env`,
+  and create a coding agent for `owner/name`. You trigger it yourself, so
+  GitHub doesn't need to reach your machine. See
+  [GitHub integration](github.md).
+- **C. A review agent on GitHub pull requests.** Reviews start from GitHub
+  webhooks, so Wardby must be reachable over public HTTPS. Register the App
+  with webhooks, link a native agent to the repository with the `pull_request`
+  trigger, and open a pull request. See [Code review agents](code-review-agents.md).
+
+The full step-by-step guide is "Choose what to set up next" in
+[`docs/getting-started.md`](../docs/getting-started.md).
+
+## Next
+
 Use [Operate agents](operating-agents.md) to create and supervise managed work.
 Read [Choose a native or coding agent](creating-agents.md) before creating your
 first agent.

package/help/github.md

@@ -23,6 +23,13 @@ Workers do not receive the GitHub App private key. A trusted component validates
 the changes, pushes a controlled branch, and opens at most one draft pull
 request. Wardby does not auto-merge coding-agent output.
 
+Set the App's credentials as `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` on
+the wardby server. Without them, a coding run on a GitHub repository fails with
+[`vcs_github_not_configured`](errors/vcs-github-not-configured.md).
+
+No GitHub App is needed for a git repository on the wardby host. See
+[Use local git repositories](local-repositories.md).
+
 Read [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) for coding
 agent setup and [`docs/code-review-agents.md`](../docs/code-review-agents.md)
 for pull-request review agents and webhook configuration.
@@ -35,14 +42,24 @@ Link a native agent to a repository with `link_repository`. Each trigger needs
 its GitHub App event ticked in the App's event settings; every event is a
 separate checkbox.
 
-| Trigger        | Starts a run when                                                   | App event to subscribe                                                                 |
-| -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `pull_request` | A pull request is opened or pushed to; a re-run of the review check | Pull request, Check run (re-runs of the review check)                                  |
-| `mention`      | Someone with write access `@`-mentions the App                      | Issue comment, Issues, Pull request review comment (mentions in inline review threads) |
-| `push`         | A commit lands on the repository's default branch                   | Push                                                                                   |
+| Trigger                         | Starts a run when                                                                                                                                                            | App event to subscribe                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `pull_request`                  | A pull request is opened or pushed to; a re-run of the review check; CI finishing after a review that waited for it                                                          | Pull request, Check run (re-runs of the review check), Check suite (CI finishing)      |
+| `pull_request` with `waitForCi` | Same, but the review of a pushed head is held until that head's own CI finishes (or 15 minutes pass), and an approve verdict is refused while CI is failing or still running | Same events as `pull_request`                                                          |
+| `mention`                       | Someone with write access `@`-mentions the App                                                                                                                               | Issue comment, Issues, Pull request review comment (mentions in inline review threads) |
+| `push`                          | A commit lands on the repository's default branch                                                                                                                            | Push                                                                                   |
+| `review_fix`                    | Wardby's own review check requests changes on a PR it opened                                                                                                                 | Same events as `pull_request` (it reacts to that check's own verdict, no extra event)  |
 
 The `push` trigger starts a merge-watcher agent; only default-branch pushes
 count (tags, other branches, and deletions are ignored). See
 [Keep the knowledge bundle current on merge](help://architecture-agent).
 
+The `review_fix` trigger lets Wardby fix its own review's findings
+automatically, up to a round cap, on pull requests its own coding runs
+opened. See [Automatic review fix rounds](review-fix-rounds.md).
+
+`waitForCi` holds a reviewer's review until that pull request's own CI
+finishes, and gates its ability to approve on CI passing. See
+[Review after CI (`waitForCi`)](code-review-agents.md#review-after-ci-waitforci).
+
 For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/jira.md

@@ -41,7 +41,10 @@ the `Jira acting as` startup line to confirm the account.
    `WARDBY_JIRA_WEBHOOK_SECRET`, then restart. The startup log line
    `Jira acting as` shows which account Wardby uses; confirm it is the service
    account. Optionally set `WARDBY_JIRA_API_TOKEN_EXPIRES_AT` to get a warning
-   14 days before expiry.
+   14 days before expiry. On the GKE reference deployment, put all five in
+   `.env.local` (all or none) and run `deploy/gke/up.sh`: it seeds them into
+   Secret Manager and syncs the optional `wardby-jira-env` Secret for the
+   control plane. See [Deploy on GKE](deploy-gke.md).
 6. A Wardby administrator links the agent with `link_issue_project`, for
    example `projectKey: "PROJ"`, `access: "write"`,
    `triggers: ["transitioned", "mention"]`,
@@ -116,7 +119,11 @@ precise task, and for follow-ups pass the run id from the run message as
 issue gets a web link to it (needs Link issues); Jira's development panel
 shows it only if the Jira and GitHub integration is installed. Merge and close
 comments and the merged status move need the GitHub App to deliver
-`pull_request` events. See the full guide for the recipe.
+`pull_request` events. When one issue leads to pull requests in several
+repositories, each lists the others, and a later event on the issue tells the
+agent how to continue each open one; see
+[Related pull requests across repositories](related-pull-requests.md). See
+the full guide for the recipe.
 
 ## Trust rules
 

package/help/local-repositories.md

@@ -0,0 +1,182 @@
+---
+id: local-repositories
+title: Use local git repositories without a GitHub App
+summary: Point coding and review agents at a git folder on the wardby host (local:/abs/path), with no GitHub App and no git worktree. Results land as branches in that repository. Needs LOCAL_REPO_ROOTS trusted folders and the Docker or Kubernetes job launcher.
+audience: operator
+tags: [local, local-repo, worktree, git, quickstart, review, coding, LOCAL_REPO_ROOTS]
+appliesTo: ">=0.5.0"
+---
+
+# Use local git repositories without a GitHub App
+
+A coding or review agent can work on a git folder on the machine that runs the
+wardby server instead of a GitHub repository. You write the repository as
+`local:/absolute/path`. No GitHub App, GitHub account link or webhook is needed.
+
+- A **coding agent** clones the repository's committed history, works in the
+  sandbox as usual, and wardby pushes the result into your repository as a new
+  branch `wardby/run-<run id>`. Wardby clones; it does not create a git
+  worktree in your repository.
+- A **review agent** reviews a branch of the repository against a base branch
+  when you ask for it with `trigger_agent`.
+
+The easiest way to try it is the optional coding step of
+`npx --yes @wardby/cli@latest quickstart` (see
+[Quickstart coding step](#quickstart-coding-step)).
+
+## Requirements
+
+- **A single-user or personal server.** Set `LOCAL_REPO_ROOTS` only on a
+  server that you alone use. 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.
+- **Trusted folders.** Set `LOCAL_REPO_ROOTS` on the wardby server to the
+  folders wardby may use, separated by the platform's path delimiter (`:` on
+  macOS and Linux, `;` on Windows). While it is unset, every `local:` repository
+  is refused with `local_repo_not_allowed`. A repository must be 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. It checks the folders again
+  when you create or update an agent, link a repository, trigger a run, and
+  while a run uses the repository. Restart the server after changing the
+  variable.
+- **The Docker or Kubernetes job launcher.** Coding agents run in an isolated
+  worker, so set `JOB_LAUNCHER=docker` (or `kubernetes`). With
+  `JOB_LAUNCHER=local` a coding run ends with "Coding agents need a container
+  executor". Review agents are native agents and need no worker.
+- **The server on the same machine as the folders.** Wardby reads and writes
+  your repository directly. A control plane in a container, a pod or on another
+  machine cannot see the folder: it ignores a trusted folder that does not
+  exist, so the repository fails with `local_repo_not_allowed`, and `doctor`
+  reports the folder as missing.
+- **git 2.24 or newer** on the machine that runs the wardby server.
+- **Worker images from this release or later.** An older worker image rejects
+  a `local:` repository and the run fails with `worker_input_failed`. That
+  includes a bring-your-own `workerImageRef` image: rebuild it on a current
+  driver image.
+
+## Coding agents
+
+Create a coding agent with `create_agent` and
+`codingProfile.repository: "local:/abs/path"`, or change an existing agent with
+`update_agent`. Start it with `trigger_agent {agentId, task, baseRef?}`.
+`baseRef` defaults to the profile's base ref.
+
+What happens:
+
+1. Wardby clones the repository's **committed** history. Untracked and
+   uncommitted files, such as a `.env.local`, never leave your machine.
+2. The worker makes its changes in the sandbox, as it does for GitHub.
+3. Wardby validates the result and pushes a single commit to the branch
+   `wardby/run-<run id>` in your repository. Your working tree, index and
+   checked-out branch are never modified.
+4. `get_run` shows `resultBranch` and `baseSha` (the commit the run started
+   from). Merge the branch the way you merge any branch.
+
+Things to know:
+
+- Your repository's own receive-side hooks (for example `pre-receive` and
+  `update`) run when wardby pushes. A hook that rejects the push fails the run.
+- `trigger_agent` returns `warnings` when the repository has uncommitted files,
+  submodules or Git LFS files. The run still starts, but uncommitted files are
+  not included and submodules and LFS are **not supported**: submodules are not
+  initialized and LFS files are not fetched.
+- A run can start from an earlier result: pass `baseRef: "wardby/run-<run id>"`
+  to build on that branch. A continuation of a run (a lead agent revising its
+  earlier work) fast-forwards the same branch. If that branch has moved, or is
+  checked out in your repository, the run fails with `local_branch_conflict`.
+- Wardby never deletes result branches. Remove one you no longer need with
+  `git branch -D wardby/run-<run id>`.
+- `.wardby/services.yaml` works for local runs. It is read from the committed
+  file at the run's base ref, never from your working tree, and fails with the
+  same errors as on GitHub (for example `service_declaration_invalid`). See
+  [Give coding runs the services their tests need](coding-services.md).
+
+## Review agents
+
+1. Create a native review agent (a normal agent with a review prompt that uses
+   the `repo_*` tools) and link it with `link_repository` using
+   `provider: "local"`, `repository: "local:/abs/path"` and `access: "write"`
+   (publishing a review needs write). A local link is manual only: give it no
+   `triggers` and no `checkName`.
+2. Start a review with
+   `trigger_agent {agentId, review: {repository?, branch, base?}}`. Only the
+   agent's owner can. `repository` defaults to the agent's only local link, and
+   `base` defaults to the branch checked out in the repository.
+3. The `repo_pr_read`, `repo_read_file`, `repo_list_files`, `repo_publish_review`
+   and `repo_comment` tools work unchanged, reading committed content at the
+   branch and never your working tree.
+4. `get_run` returns the result in `review`: `number`, `branch`, `base` and
+   `reviews`, each with `verdict`, `summary`, `body` and `comments`.
+
+There are no check runs and no CI results for a local review, and event
+triggers (`pull_request`, `push`, `mention`, `review_fix`) are rejected for
+local repositories.
+
+A typical loop: trigger the coding agent, read `resultBranch` from `get_run`,
+then trigger the review agent with `review: {branch: "<resultBranch>"}`.
+
+## Quickstart coding step
+
+`quickstart` asks "Set up coding + review agents against a local git repo?"
+after the sample agent. It needs Docker and, for the coding provider you
+choose, an `OPENAI_API_KEY` (Codex) or `ANTHROPIC_API_KEY` (Claude Code). It
+then:
+
+- asks which folders to trust (offering the git root of the current directory)
+  and writes `LOCAL_REPO_ROOTS` and `JOB_LAUNCHER=docker` to `.wardby/.env`;
+- gets only the chosen provider's images, pulled by digest from a release or
+  built from a wardby source checkout: the runtime image plus the Codex worker
+  for Codex, or the runtime image plus the Claude worker and tool-runner images
+  for Claude Code. A Claude-only setup does not need or set
+  `CODING_WORKER_IMAGE`; images another provider set up on an earlier run are
+  kept. `WARDBY_RUNTIME_IMAGE` together with `CODING_WORKER_IMAGE`, or
+  `CODING_CLAUDE_WORKER_IMAGE` plus `CODING_CLAUDE_TOOL_RUNNER_IMAGE`, override
+  them with your own digests;
+- starts the coding proxy and runs the coding preflight;
+- finds the repository: a trusted folder that is a git repository, or the
+  repositories directly inside a trusted folder (hidden folders are skipped).
+  With several it asks which to use; non-interactively it uses the first in
+  sorted order and prints the choice. Re-run with `--trust <repo>` to pick
+  another: folders passed on a run take precedence over saved ones;
+- creates `local-builder` (a coding agent, $2 budget) and `local-reviewer`
+  (a review agent, $1 budget) for the repository and prints the two
+  `trigger_agent` calls to try; and
+- if the repository has no `.wardby/services.yaml`, offers a starter one with
+  PostgreSQL and/or Redis. It is committed to the branch
+  `wardby/quickstart-services` without touching your working tree. Merge that
+  branch, or set the agent's `baseRef` to it. When a services file exists
+  already, quickstart shows what it declares or why it is invalid. The "default
+  branch" is whichever branch is checked out when quickstart runs.
+
+Flags: `--coding` (run the step), `--no-coding` (skip it), `--trust <dir>`
+(repeatable), `--coding-provider codex|claude-code` and
+`--starter-services postgres,redis|none`. In `--non-interactive` mode the step
+only runs with `--coding`, and it needs at least one `--trust`. `doctor` and
+`status` report the trusted folders, worker image, coding proxy and each local
+agent's repository, and `down` stops the proxy with the database.
+
+## Errors
+
+- [`local_repo_not_allowed`](errors/local-repo-not-allowed.md): outside every
+  trusted folder, `LOCAL_REPO_ROOTS` is unset, or the server cannot see the
+  trusted folder.
+- [`local_repo_not_found`](errors/local-repo-not-found.md): missing, not a git
+  work tree, or not readable by the server.
+- [`local_ref_not_found`](errors/local-ref-not-found.md): the branch or base
+  does not exist.
+- [`local_ref_invalid`](errors/local-ref-invalid.md): not a valid branch name.
+- [`local_path_invalid`](errors/local-path-invalid.md): an unsafe file path in
+  a repository read.
+- [`local_branch_conflict`](errors/local-branch-conflict.md): the result branch
+  moved or is checked out.
+- [`vcs_github_not_configured`](errors/vcs-github-not-configured.md): a coding
+  agent uses a GitHub repository on a server with only local repositories
+  configured.
+
+Related: [Get started](getting-started.md),
+[Connect GitHub repositories](github.md) (the alternative to a local
+repository), [Run GitHub code-review agents](code-review-agents.md) and
+[Give coding runs the services their tests need](coding-services.md). Operator
+guide: [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md).

package/help/related-pull-requests.md

@@ -0,0 +1,89 @@
+---
+id: related-pull-requests
+title: Related pull requests across repositories
+summary: Wardby lists the other pull requests from the same request in each pull request's description, with a suggested merge order.
+audience: operator
+tags: [github, pull-requests, multi-repo, merge-order, related, siblings, continuePriorRun, coding-agents, jira]
+appliesTo: ">=0.4.2"
+---
+
+# Related pull requests across repositories
+
+When one request produces pull requests in several repositories — a lead
+agent that delegates to one coding agent per repository, or several runs for
+the same Jira issue — Wardby adds a **Related pull requests** section to each
+of those pull requests' descriptions. It lists the others with links and
+their state, names the originating issue when there is one, and gives a
+suggested merge order.
+
+Without a tracked Jira issue, the list covers the pull requests opened by
+runs in the same delegation tree (the same lead run and everything it
+started). With a tracked issue, the list covers every pull request Wardby
+has recorded for that issue across every run, merged and closed ones
+included, plus that run tree's own siblings.
+
+- **Written by Wardby, not the model.** The list comes from Wardby's own run
+  records, never from the agent's text. Edits you make inside the section
+  are replaced on the next rewrite; text outside it is left alone.
+- **When.** A pull request already lists the ones opened earlier in the same
+  request when it is opened. When the lead run finishes, Wardby rewrites the
+  section on every open pull request of the request with the full list and
+  current states. A later run that pushes to any pull request in the set
+  refreshes the section on all of them the same way, and never removes it.
+- **Suggested merge order (the order Wardby's agent opened them in)** numbers
+  the open (and draft) pull requests in delegation order. It is not a
+  dependency analysis — it is only reliable when the lead delegates
+  repositories that own shared data first (see
+  [Fanning out to several builders](../docs/agent-recipes.md#fanning-out-to-several-builders)).
+  Check it before merging. Merged and closed pull requests follow in a
+  separate "Already merged or closed" list, as context only.
+- Only open pull requests that Wardby's own GitHub App opened are edited;
+  merged or closed ones are listed but never changed, and a pull request
+  from a different Wardby deployment sharing the same App is never touched.
+- **Repository names are visible across the set.** The section (and the
+  follow-up hints below) lists every pull request in the set by repository
+  name and number, so a request that spans repositories of different
+  visibility can show a private repository's name in a public repository's
+  pull request. If you mix public and private repositories, keep such work in
+  separate requests: separate Jira issues, or separate lead agents.
+
+Reviewers see the section in the pull request description, so a reviewer
+agent can tell that a field, route, or schema a change relies on is added by
+a sibling pull request rather than missing. See the reviewer step in
+[Run GitHub code-review agents](code-review-agents.md#ci-and-sibling-pull-requests).
+
+## Follow-up runs and sibling pull requests
+
+When someone asks for a follow-up on one of these pull requests (an
+`@<app-slug>` mention, or a new Jira event on the issue), the task given to
+the agent also lists every **open** sibling pull request in the set, with
+its link and the exact `continuePriorRun` value that continues it, together
+with guidance not to open a duplicate pull request in a repository that
+already has one open for this request. Automatic review fix rounds get no
+such hints: a fix round's task names only its own pull request. Merged and
+closed pull requests are never listed as continuable: a change there needs a
+new pull request, which joins the set once it is recorded.
+
+Give your own delivery or router agent's system prompt a line such as:
+
+    Continue the pull request you were asked about, and any listed open
+    sibling the change requires; never open a new pull request in a
+    repository that already has an open sibling for this request.
+
+The usual limits still apply: `maxDelegationsPerRun` and never delegating to
+the same sub-agent twice in one run; every push to a sibling pull request
+gets its own review; fix rounds are capped per pull request and only one
+runs at a time on a pull request; and a continuation only ever reaches a
+sub-agent that shares the same owner as the one asked to continue it.
+
+A continuation never pushes to a pull request that has been merged or closed
+in the meantime: the coding run stops before it starts work (or right before
+it pushes) with failure category `continuation_closed`, and the delegating
+agent is told to make the change as a new pull request instead. See
+[Continuation's pull request is no longer open](errors/continuation-closed.md).
+
+Wardby also keeps the recorded state of issue-linked pull requests current
+even when GitHub's merge or close webhook delivery was missed: it re-checks
+open ones in the background, at most ten at a time, each at most every ten
+minutes, and applies the same comment and status move a normal webhook would
+have triggered.

package/help/review-fix-rounds.md

@@ -0,0 +1,69 @@
+---
+id: review-fix-rounds
+title: Automatic review fix rounds
+summary: Let wardby fix its own review's findings on pull requests its coding runs opened, with a round cap.
+audience: operator
+tags: [github, code-review, review_fix, autofix, fix-round, pull-requests]
+appliesTo: ">=0.4.2"
+---
+
+# Automatic review fix rounds
+
+Link an agent with the `review_fix` trigger and wardby will try to fix its
+own code review's findings automatically, instead of waiting for a human to
+ask. Use `link_repository` with `access: "write"`, `triggers` including
+`review_fix`, and an optional `reviewFixMaxRounds` (1–10, default 2); only
+one agent per repository may hold this trigger.
+
+A round starts when wardby's own review check on a pull request comes back
+`CHANGES_REQUESTED` and the pull request is still open, not from a fork,
+still at the commit that was reviewed, and was opened by a wardby coding run
+of this same deployment. No human comment is involved — it runs on the
+`review_fix` link's own authorization. The agent is asked to fix only the
+CRITICAL/MAJOR findings and MUST_FIX recommendations and change nothing
+else; what it actually changes, and how much budget it uses, is still up to
+the agent's own instructions.
+
+The review is passed to the agent as untrusted context — information about
+what to fix, never instructions to follow. Only the review's summary and
+body reach the agent, not its inline comments, so write your reviewer's
+prompt to list every finding in the review body. A review that is wrong
+about CI or about a sibling pull request starts a round that changes
+nothing; give your reviewer the CI and related-pull-requests step from
+[Run GitHub code-review agents](code-review-agents.md#ci-and-sibling-pull-requests).
+
+A round isn't started while an earlier round on the same pull request is
+still running. Clicking **Re-run** on the review check isn't counted as a
+round itself; if the re-run's review requests changes, that starts a round
+like any other review.
+
+Rounds are tracked with labels on the pull request:
+
+- `wardby-autofix-<N>` — one per round, added before that round's run
+  starts.
+- `wardby-autofix-limit` — added once the cap is reached; wardby posts one
+  comment and stops.
+- `wardby-autofix-off` — add this by hand to opt a pull request out
+  entirely.
+
+To let a capped pull request have more rounds, remove the round labels
+together with `wardby-autofix-limit` (a leftover
+`wardby-autofix-limit` means there's no comment when the cap is reached
+again). A pull request opened by a different wardby
+deployment gets one refusal comment and `wardby-autofix-limit` instead of a
+round, since this deployment can't continue a branch it has no record of
+opening.
+
+A round's run also double-checks with GitHub that the pull request is still
+open right before it pushes; one merged or closed in the time the round was
+working fails with no push made — see
+[Continuation's pull request is no longer open](errors/continuation-closed.md).
+
+If a repository already forwards reviews to a webhook through a
+hand-written CI workflow to fix them automatically, turn on `review_fix` and
+then remove that workflow and its webhook, so a review doesn't trigger two
+fix rounds at once.
+
+See [`docs/code-review-agents.md`](../docs/code-review-agents.md#automatic-review-fix-rounds)
+for the full trigger rules, the App's required permissions, and the related
+[code-review-agents](code-review-agents.md) article.

package/help/troubleshooting/budgets.md

@@ -29,4 +29,15 @@ what the parent (and any earlier sub-agents) have already spent, so a parent
 that spends heavily before delegating can leave a sub-agent refused with
 `run_tree_exhausted`.
 
+Sub-agents started together (a lead with `parallelDelegations`) also count each
+other's unspent reservations, so the last one admitted can be refused with
+`run_tree_exhausted` even though no sub-agent has spent much yet. If a
+sibling is still running when that happens, the refused sub-agent waits for
+it to finish and retries instead of failing immediately — up to roughly
+twice its normal wait bound in total; with no sibling running, the refusal is
+immediate. A sub-agent that is waiting for budget still counts toward the
+lead's `maxDelegationsPerRun`, so a delegation beyond the limit is refused
+with `already_dispatched` and a message naming how many delegations were
+made and how many are waiting for budget.
+
 For a shared-group refusal, read [Budget group exhausted](../errors/budget-group-exhausted.md).

package/help/troubleshooting/coding-workers.md

@@ -23,6 +23,28 @@ Review the deployment guide for your target before assigning a coding profile.
 
 For the specific isolation refusal, read [Coding-worker isolation unavailable](../errors/docker-isolation-unsupported.md).
 
+## Runs that stop at the turn limit
+
+A Claude Code run whose failure category is `turn_limit` reached its agent's
+turn limit (worker error `coding_turn_limit`): 200 model calls by default. The
+work was too large for the limit, or the agent was looping. Read the run's
+summary and debug trace (`codingProfile.debugTraceMinutes`) to tell which;
+raise `codingProfile.maxTurns` (up to 1000) with `update_agent` for the first,
+or narrow the task for the second. Codex runs have no turn limit. See
+[Coding run reached its turn limit](../errors/coding-turn-limit.md).
+
+## Runs that wait for cluster capacity
+
+On Kubernetes with `KUBERNETES_RESOURCE_QUOTA` set, a run whose pod would not
+fit the namespace quota stays `pending` with `codingQueuedAt` set, like a run
+over `CODING_MAX_CONCURRENT`, and starts once other runs finish. A run still
+waiting after `CODING_QUEUE_TIMEOUT_SEC` fails with `coding_queue_timeout`:
+raise the quota, lower the run pods' size, or lower `CODING_MAX_CONCURRENT` so
+fewer runs compete.
+
+A lead agent with `parallelDelegations` starts several coding runs together;
+expect some of them to queue when the lead fans out wider than the free slots.
+
 ## Service refusals and failures
 
 A repository can declare services such as PostgreSQL in `.wardby/services.yaml`

package/help/troubleshooting/repository-access.md

@@ -25,3 +25,8 @@ and re-run the work later.
 
 Read [Repository access refused](../errors/repo-access.md) for the safe
 remediation sequence.
+
+The same authorization check gates an [automatic review fix
+round](../review-fix-rounds.md): a `review_fix` link that fails it simply
+skips starting that round, with no comment on the pull request, until
+access is restored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardby/cli",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Self-hosted control plane for budget-guarded AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/wardby/wardby#readme",
@@ -36,6 +36,7 @@
     "NOTICE",
     "bin/",
     "docs/",
+    "deploy/local/docker-compose.quickstart-coding.yml",
     "deploy/local/docker-compose.yml",
     "dist/",
     "help/",
@@ -95,7 +96,7 @@
     "@anthropic-ai/sdk": "^0.124.0",
     "@dbos-inc/dbos-sdk": "4.27.6",
     "@kubernetes/client-node": "^2.0.0",
-    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@prisma/adapter-pg": "7.10.0",

package/prisma/migrations/20261004100000_delegations_and_coding_turns/migration.sql

@@ -0,0 +1,12 @@
+-- Sub-agent fan-out and Claude Code turn limits (docs/agent-recipes.md, docs/coding-agent-setup.md).
+-- Additive: two new columns. Every existing agent keeps one delegation per run;
+-- every existing coding profile and run keeps the worker's default turn limit.
+
+-- AlterTable
+ALTER TABLE "Agent" ADD COLUMN "maxDelegationsPerRun" INTEGER NOT NULL DEFAULT 1;
+
+-- AlterTable
+ALTER TABLE "CodingAgentProfile" ADD COLUMN "maxTurns" INTEGER;
+
+-- AlterTable
+ALTER TABLE "CodingRun" ADD COLUMN "maxTurns" INTEGER;

package/prisma/migrations/20261005000000_review_fix_rounds/migration.sql

@@ -0,0 +1,5 @@
+-- Automatic review fix rounds: a per-link round cap, and the verdict and
+-- review text a reviewer run published on its own check.
+ALTER TABLE "AgentRepository" ADD COLUMN "reviewFixMaxRounds" INTEGER;
+ALTER TABLE "RunHostCheck" ADD COLUMN "verdict" TEXT;
+ALTER TABLE "RunHostCheck" ADD COLUMN "reviewBody" TEXT;

package/prisma/migrations/20261006000000_parallel_delegations/migration.sql

@@ -0,0 +1,6 @@
+-- Parallel delegations (docs/agent-recipes.md): a native lead's delegate_to_*
+-- calls made in one model turn run at the same time. Additive: every existing
+-- agent keeps running its delegations one after another.
+
+-- AlterTable
+ALTER TABLE "Agent" ADD COLUMN "parallelDelegations" BOOLEAN NOT NULL DEFAULT false;

package/prisma/migrations/20261007000000_ci_rereview/migration.sql

@@ -0,0 +1,4 @@
+-- A review that published COMMENT while CI on its head was unfinished is
+-- re-run once when CI finishes on that head.
+ALTER TABLE "RunHostCheck" ADD COLUMN "ciPendingAtReview" BOOLEAN;
+ALTER TABLE "RunHostCheck" ADD COLUMN "ciRereviewAt" TIMESTAMP(3);

package/prisma/migrations/20261008000000_review_after_ci/migration.sql

@@ -0,0 +1,33 @@
+-- Additive: a repository link can hold its review until that head's own CI
+-- finishes (AgentRepository.waitForCi), and DeferredReview records a review
+-- held that way until the ci_completed event or the reconciler's fallback
+-- sweep starts it.
+
+-- AlterTable
+ALTER TABLE "AgentRepository" ADD COLUMN "waitForCi" BOOLEAN NOT NULL DEFAULT false;
+
+-- CreateTable
+CREATE TABLE "DeferredReview" (
+    "id" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "repository" TEXT NOT NULL,
+    "prNumber" INTEGER NOT NULL,
+    "headSha" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "checkName" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "DeferredReview_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "DeferredReview_provider_repository_prNumber_headSha_agentId_key" ON "DeferredReview"("provider", "repository", "prNumber", "headSha", "agentId");
+
+-- CreateIndex
+CREATE INDEX "DeferredReview_provider_repository_headSha_idx" ON "DeferredReview"("provider", "repository", "headSha");
+
+-- CreateIndex
+CREATE INDEX "DeferredReview_createdAt_idx" ON "DeferredReview"("createdAt");
+
+-- AddForeignKey
+ALTER TABLE "DeferredReview" ADD CONSTRAINT "DeferredReview_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "Agent"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261009000001_coding_run_local_branch/migration.sql

@@ -0,0 +1,7 @@
+-- Additive: a coding run on a local repository pushes a branch instead of
+-- opening a pull request, so CodingRun records that branch (resultBranch) and
+-- the commit the run started from (baseSha, recorded for every outcome).
+
+-- AlterTable
+ALTER TABLE "CodingRun" ADD COLUMN "resultBranch" TEXT,
+ADD COLUMN "baseSha" TEXT;