@wardby/cli 0.5.3 → 0.7.0

package/docs/agent-recipes.md

@@ -231,22 +231,32 @@ to include secrets or internal details. See
 <details>
 <summary>Builder (coding agent) fields that matter</summary>
 
-| Field (`codingProfile`) | What to set                                                                                                                                                  |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `model` (agent field)   | A capable coding model the chosen provider supports, for example `gpt-5.6-terra` with `codex` or `claude-sonnet-5` with `claude-code`; a mismatch is refused |
-| `provider`              | `codex` or `claude-code`; the agent's `model` must be one that provider supports                                                                             |
-| `repository`            | `your-org/your-repo`; your linked GitHub account needs write access                                                                                          |
-| `baseRef`               | The branch runs start from, usually your default branch                                                                                                      |
-| `toolchain`             | `node` or `node-python` (per language below)                                                                                                                 |
-| `toolchainVersion`      | `"3.12"` for `node-python`; omit for `node`                                                                                                                  |
-| `packageAllowlist`      | Top-level packages per ecosystem (`npm`, `pypi`). Needs `packages:approve` or `agents:admin`                                                                 |
-| `packagePolicy`         | Optional `minReleaseAgeDays` (0 to 30)                                                                                                                       |
-| `services`              | Catalog service names the agent may start, for example `["postgres"]`; see [Services](coding-services.md)                                                    |
-| `protectedPaths`        | Globs a run may not change, for example `[".github/**", "CODEOWNERS"]`. `.wardby/**` is always protected except `.wardby/services.yaml`                      |
-| `timeoutSec`            | 60 to 7200; for example `1800`                                                                                                                               |
-| `workerImageRef`        | Digest-pinned custom image; needs `agents:admin` (see "Other languages")                                                                                     |
-| `defaultTask`           | Needed only to schedule the agent                                                                                                                            |
-| Agent `budgetUsd`       | Per-run budget, reserved at dispatch, for example `5`                                                                                                        |
+| Field (`codingProfile`)       | What to set                                                                                                                                                                                                                                                                                                                                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model` (agent field)         | A capable coding model the chosen provider supports, for example `gpt-5.6-terra` with `codex` or `claude-sonnet-5` with `claude-code`; a mismatch is refused                                                                                                                                                                                                                                      |
+| `provider`                    | `codex` or `claude-code`; the agent's `model` must be one that provider supports                                                                                                                                                                                                                                                                                                                  |
+| `repository`                  | `your-org/your-repo`; your linked GitHub account needs write access                                                                                                                                                                                                                                                                                                                               |
+| `baseRef`                     | The branch runs start from, usually your default branch                                                                                                                                                                                                                                                                                                                                           |
+| `toolchain`                   | `node` or `node-python` (per language below)                                                                                                                                                                                                                                                                                                                                                      |
+| `toolchainVersion`            | `"3.12"` for `node-python`; omit for `node`                                                                                                                                                                                                                                                                                                                                                       |
+| `packageAllowlist`            | Top-level packages per ecosystem (`npm`, `pypi`). Needs `packages:approve` or `agents:admin`                                                                                                                                                                                                                                                                                                      |
+| `packagePolicy`               | Optional `minReleaseAgeDays` (0 to 30)                                                                                                                                                                                                                                                                                                                                                            |
+| `services`                    | Catalog service names the agent may start, for example `["postgres"]`; see [Services](coding-services.md)                                                                                                                                                                                                                                                                                         |
+| `protectedPaths`              | Globs a run may not change, for example `[".github/**", "CODEOWNERS"]`. `.wardby/**` is always protected except `.wardby/services.yaml`                                                                                                                                                                                                                                                           |
+| `timeoutSec`                  | 60 to 7200; for example `1800`                                                                                                                                                                                                                                                                                                                                                                    |
+| `workerImageRef`              | Digest-pinned custom image; needs `agents:admin` (see "Other languages")                                                                                                                                                                                                                                                                                                                          |
+| `defaultTask`                 | Needed only to schedule the agent                                                                                                                                                                                                                                                                                                                                                                 |
+| Agent `budgetUsd`             | Per-run budget, reserved at dispatch, for example `5`                                                                                                                                                                                                                                                                                                                                             |
+| Agent `allowedOverrunPercent` | Optional whole percent (0 to 100, default 0) beyond `budgetUsd`, for example `10`. On a coding agent it raises each run's limit; on a lead agent that delegates, it raises its run tree's ceiling for coding sub-agents. It is never reserved: a run is topped up past its base only from room its budget group and run tree have when it needs it. Native runs' own model calls are not affected |
+
+To allow a small overrun on an existing coding agent, call `update_agent`
+(it needs the same permission as changing `budgetUsd`):
+
+```json
+{ "id": "<coding agent id>", "allowedOverrunPercent": 10 }
+```
+
+See [Budgets](coding-agent-setup.md#budgets).
 
 The agent's `systemPrompt` is placed ahead of each request as standing
 instructions. The template below is generic.
@@ -336,7 +346,9 @@ toolchain, build your own image on Wardby's driver base image and point the
 agent at it with `workerImageRef`, a digest-pinned reference (a mutable tag is
 rejected). Setting it needs the `agents:admin` scope and the admin role. The
 Dockerfile shape, the driver image, and what Wardby does and does not verify are
-in [Bring-your-own worker images](coding-worker-byo-images.md).
+in [Bring-your-own worker images](coding-worker-byo-images.md). For a Claude
+Code agent, build the image on the release's tool runner image instead; see
+[Codex and Claude Code](coding-worker-byo-images.md#codex-and-claude-code).
 
 ```json
 {
@@ -405,8 +417,10 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
 - Each coding sub-agent's result tells the lead its `status`, its summary
   (`finalText`), cost and tokens, and, when it opened or pushed to a pull
   request, `pullRequest` (`outcome` `opened` or `updated`, `repository`,
-  `number`, `url`) taken from Wardby's own record of the run. A lead prompt can
-  ask the agent to report those links.
+  `number`, `url`) taken from Wardby's own record of the run. A failed builder's
+  result also carries `errorCode`, the leading code of its error (such as
+  `coding_queue_timeout`); the full error stays on the run (`get_run`). A lead
+  prompt can ask the agent to report those links and codes.
 - The whole run tree shares one budget: give the lead a `budgetUsd` that
   covers every builder it may start, plus its own planning. Builders started
   together each reserve their own `budgetUsd` up front, so the ones admitted
@@ -422,15 +436,70 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
   boundary (routes, field names and types, error codes), word for word the same.
 - Wardby adds a **Related pull requests** section to each pull request the
   builders open, listing the others with links, states (open, draft, merged,
-  closed) and the originating issue. With a Jira issue, the list covers every
-  pull request recorded for that issue in any run. Open ones are numbered as a
+  closed) and the originating issue. With a Jira or GitHub issue, the list
+  covers every pull request recorded for that issue in any run. When no pull request in the
+  set carries a `mergeOrder` (see below), open ones are numbered as a
   **Suggested merge order** — the order the lead delegated in, not a
-  guarantee; merged and closed ones are listed separately as context. A pull
-  request lists the ones opened before it as soon as it is opened; when the
-  lead run finishes, and whenever a later run pushes to one of them, every
-  open one is rewritten with the full list. Text you add inside the section is
-  replaced; the rest of the description is not touched. Only pull requests the
-  App opened and that are still open are edited.
+  guarantee. When any pull request in the set carries one (open, merged or
+  closed), the open ones that have a `mergeOrder` are numbered under
+  **Merge order (set by the delegating agent; equal steps can merge in either
+  order)** and labelled "step k of n" (equal values share a step), and any
+  open pull request without one is listed after under **Not ordered**. If
+  only merged or closed pull requests carry a `mergeOrder`, the open ones are
+  all listed under **Not ordered**, with no **Merge order** heading. Steps
+  are counted over the whole set, merged and closed pull requests included,
+  so a label stays the same as earlier steps merge. Merged and closed pull
+  requests are always listed separately as context, with their step label
+  when they have one. A pull request lists the ones opened before it as
+  soon as it is opened; when the lead run finishes, and whenever a later run
+  pushes to one of them, every open one is rewritten with the full list. Text
+  you add inside the section is replaced; the rest of the description is not
+  touched. Only pull requests the App opened and that are still open are
+  edited. With Wardby 0.6.0 or later, a reviewer linked to one of these repositories
+  also holds its review of such a pull request until the lead run finishes,
+  however it ends, so every pull request of the request is open by the time
+  any of them is reviewed. When the lead finishes normally the section above
+  has been rewritten by then; when it is ended another way (for example,
+  cancelled), reviews start without that rewrite, and reviewers use
+  `repo_pr_read`'s `relatedPullRequests` either way — see
+  [Reviewing a pull request a delegated run
+  opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
+- Each `delegate_to_<name>` call to a coding sub-agent can carry a
+  `mergeOrder`: an integer from 1 to 99, where 1 merges first. Give a
+  repository that other repositories' changes depend on a lower number than
+  the ones that call it — for example a service `1`, the API in front of it
+  `2`, the client `3` — and give two changes the same number when there is no
+  order between them. Set it whenever one change spans several repositories
+  and the pull requests must land in a particular sequence; leave it unset
+  and the set keeps the delegation-order "Suggested merge order" above. A
+  native sub-agent has no pull request to order, so it ignores `mergeOrder`
+  and the tool result notes that it did. Each pull request shows the value
+  most recently set for it, by the run that opened it or a later
+  continuation of it: a `continuePriorRun` call that omits `mergeOrder`
+  keeps that value, and one that sets `mergeOrder` replaces it. A
+  bad value (not an integer, or outside 1-99) is refused as a tool error
+  rather than silently ignored.
+- With Wardby 0.6.0 or later, once a set has more than one distinct
+  `mergeOrder`, each open or draft pull request Wardby opened in it also
+  gets a check run named exactly `wardby merge order`: `in_progress` while
+  an earlier step hasn't merged, `success` once every earlier step has
+  (or there is none), and `failure` if an earlier step was closed without
+  merging. Above the set's lowest step, a would-be `success` stays
+  `in_progress` ("waiting for the delegating run to finish") while the
+  delegating (lead) agent's run is still running — it may still add or
+  reorder steps. A coding run that continues one of the pull requests on
+  its own (a review fix round, an `@` mention) never holds it. Posting it never
+  blocks a merge by itself: add `wardby merge order` as a required status
+  check in branch protection to gate on it. See
+  [The wardby merge order check](../help/merge-order-check.md).
+- With Wardby 0.7.0 or later, set `markReadyWhenPassing: true` on the
+  lead's write link (`link_repository`) to have Wardby mark the draft pull
+  requests its builders open ready for review once they pass, instead of
+  leaving that to a person; the coding builders need no link of their own.
+  With a `mergeOrder` set, a later step only becomes ready this way once the
+  `wardby merge order` check above reports `success` on it — that is, once
+  the steps it depends on have merged. See [Mark ready
+  when passing](code-review-agents.md#mark-ready-when-passing-markreadywhenpassing).
 - The section, and the follow-up hints below, list every pull request in the
   set by repository name and number. A request that spans repositories of
   different visibility can therefore show a private repository's name in a
@@ -463,6 +532,11 @@ fails with category `continuation_closed` and pushes nothing — see
 
 #### Limits
 
+- If two executions of one delegation step overlap (for example a stalled
+  process and the process that took the run over) and the call id is already
+  held by a run of a different sub-agent, the call returns
+  `delegation_conflict` to the lead without starting a run or failing it; see
+  [Delegation conflict](../help/errors/delegation-conflict.md).
 - Cancelling the lead run does not stop a native sub-agent that is already
   running; it keeps running to completion. A coding sub-agent is stopped.
 - If Wardby restarts mid-batch, the batch's delegation calls replay and each
@@ -497,6 +571,19 @@ the run; the pull request description says which. A person
 reviews and merges; Wardby never merges for you. A later mention on that pull
 request continues the same branch.
 
+When a mention run finishes without opening a pull request or failing a
+sub-run and its reply is longer than about 2,000 characters (for example a
+plan), the status comment does not cut the reply short. It says "✅ Finished
+without opening a pull request. The full reply follows in the next
+comment(s)." (in a review thread: "...follows in this pull request's
+conversation."), and the reply is posted in up to four numbered comments
+("Reply, part i of n") of about 60,000 characters each, split at headings,
+paragraphs or lines. Anything beyond four parts is cut with a note; the full
+text stays on the run (`get_run`, `finalText`). `@`-mentions in the reply are
+defused. Each part is posted once; if one cannot be posted, the rest are
+skipped. Shorter replies, and runs that opened a pull request or had a failed
+sub-run, keep the status comment that quotes up to 2,000 characters.
+
 ## Next steps
 
 - [Architecture knowledge bundles](knowledge.md)

package/docs/architecture-runtime.md

@@ -73,10 +73,14 @@ credentials, still reaches only the proxy, and the proxy still owns the ledger.
 
 | `JOB_LAUNCHER` | Worker runs in                   | Isolation                                            |
 | -------------- | -------------------------------- | ---------------------------------------------------- |
-| `local`        | a child process on this host     | development only, no isolation                       |
+| `local`        | nowhere: no coding launcher      | native agents only; coding runs fail before starting |
 | `docker`       | a container on a per-run network | the diagram above                                    |
 | `kubernetes`   | a pod in a namespace             | per-run NetworkPolicy, attested pod, optional gVisor |
 
+`local` is the default. It composes no coding launcher, so a coding run ends
+with "Coding agents need a container executor"; set `docker` or `kubernetes`
+to run coding agents.
+
 Under `kubernetes` the shape is the same with different nouns: the per-run
 Docker network becomes a NetworkPolicy, the keeper and worker share a pod
 instead of a volume, and the proxy is a Service rather than a container name.
@@ -88,3 +92,14 @@ or not anything enforces it. See
 [coding-worker-isolation.md](coding-worker-isolation.md) for the mechanics and
 the [Kubernetes deployment guide](../deploy/kind-coding/README.md) for the local
 and GKE Autopilot overlays.
+
+### Native agents in a sandbox
+
+Native sandbox requires Wardby 0.5.4 or later.
+
+Native agents run in the server process by default. A native agent set to
+`nativeExecutionMode=sandbox` instead runs its turn loop and user tools in a
+single-use credential-free container whose only path out is a separate native
+gateway, enabled with `NATIVE_SANDBOX_LAUNCHER=docker` or `kubernetes` (a pod
+per run, including on GKE Autopilot under gVisor; independent of
+`JOB_LAUNCHER`). See [native-sandbox.md](native-sandbox.md).