@wardby/cli 0.5.2 → 0.6.0

package/help/local-repositories.md

@@ -135,14 +135,41 @@ then:
   `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;
+- detects Python projects: if the repository's committed root holds
+  `pyproject.toml`, `setup.py`, `setup.cfg`, `Pipfile` or a `requirements*.txt`,
+  `local-builder` gets a Node + Python 3.12 workspace (`toolchain: node-python`)
+  for Codex and Claude Code, with `pytest` and `ruff`, so it can run the tests.
+  The images come from `CODING_WORKER_IMAGE_NODE_PYTHON_3_12` (Codex) and
+  `CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` (Claude Code); set them to
+  override. If this version has no Python image, quickstart says so and the
+  builder uses the Node workspace (it can edit but not run Python tests). Other
+  languages need a bring-your-own image via `workerImageRef`. See the BYO
+  worker images guide in the long-form docs;
 - 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;
+- offers the packages the repository declares (`package.json` dependencies,
+  `pyproject.toml` dependencies including optional groups and Poetry, with
+  Poetry's legacy `[tool.poetry.dev-dependencies]`, the `[build-system]
+requires` build packages (or `setuptools` and `wheel` when there is no
+  `[build-system]` table), and
+  `requirements*.txt`, read from the committed root) as `local-builder`'s
+  package allowlist: names without versions (Python extras such as
+  `psycopg[binary]` are kept), up to 200 per ecosystem. It lists them
+  and asks "Allow local-builder to install these packages through Wardby's
+  registry? [Y/n]"; every registry safeguard still applies. If you decline, or
+  run non-interactively without `--allow-repo-packages`, the allowlist stays
+  empty: add packages later with `update_agent` and
+  `codingProfile.packageAllowlist`. A re-run replaces the allowlist with what
+  the repository declares now. A manifest quickstart cannot read is skipped
+  with a note. See [Approve packages for coding agents](coding-packages.md);
 - 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
+  (a review agent, $1.50 budget, on Claude Sonnet 5 or `gpt-5.6-terra` by
+  default, with the thorough review prompt quoted in
+  [Set up an architecture agent](architecture-agent.md#reviewer-system-prompt))
+  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
@@ -151,11 +178,14 @@ then:
   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
+(repeatable), `--coding-provider codex|claude-code`,
+`--starter-services postgres,redis|none` and `--allow-repo-packages` (or
+`--no-allow-repo-packages`). 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.
+agent's repository, and `down` stops the proxy with the database. Quickstart
+ends with a menu of next things to ask your assistant, each naming the help
+article it follows; see [Get started](getting-started.md).
 
 ## Errors
 

package/help/low-power-mode.md

@@ -0,0 +1,125 @@
+---
+id: low-power-mode
+title: Low power mode on GKE
+summary: Low power mode: scale the coding proxy and native gateway to zero when idle to cut the cost of a lightly used GKE deployment, and what changes when they wake.
+audience: operator
+tags: [gke, cost, low-power, scale-to-zero, kubernetes, autoscaling, idle, power_sleep, power_status, sleep now, power:manage]
+appliesTo: ">=0.6.0"
+---
+
+# Low-power mode on GKE
+
+Low-power mode reduces the cost of a GKE Autopilot deployment that runs agents
+only occasionally. When it is on, the coding proxy and the native gateway scale
+to zero replicas after an idle window and wake when a run needs them. The
+headroom placeholder is off, and the control plane runs 1 copy that scales to 2
+under load.
+
+It needs `JOB_LAUNCHER=kubernetes`. Without it Wardby logs `low_power_ignored`
+and the mode does nothing.
+
+## Turn it on or off
+
+```sh
+WARDBY_HOSTNAME=wardby.example.com WARDBY_LOW_POWER=1 deploy/gke/up.sh
+```
+
+Re-running `up.sh` without `WARDBY_LOW_POWER=1` turns it off: it removes the
+autoscaler `wardby-control-plane` and the Role and RoleBinding `wardby-power`
+and restores proxy 1, gateway 2, headroom 1, control plane 1.
+
+`WARDBY_LOW_POWER` accepts only unset, `0` or `1`; anything else fails `up.sh`
+and stops the control plane at start-up. `LOW_POWER_IDLE_MINUTES` is an integer
+from 5 to 1440 (default 30) set on the control-plane Deployment; it is read
+only when `WARDBY_LOW_POWER=1`.
+
+## How it behaves
+
+- **Sleep.** Every minute the scheduler leader scales the coding proxy
+  (`wardby-coding-proxy`) or native gateway (`wardby-native-gateway`) to 0 when
+  nothing is pending or running for it and nothing finished within the idle
+  window. The gateway also needs no active session. Either target sleeps only
+  once at least one idle window has passed since it was last woken (annotation
+  `wardby.io/power-woke-at`) and since the control plane started, whichever is
+  later. The check repeats just before scaling. Log: `power: proxy slept (idle 30m)`.
+- **Wake.** A coding run scales the proxy to 1 and waits for a ready endpoint;
+  a sandbox run does the same for the gateway. The wait is at least 5 minutes.
+  A `KUBERNETES_READY_TIMEOUT_MS` (proxy) or `NATIVE_SANDBOX_READY_TIMEOUT_MS`
+  (gateway) above that, set on the control-plane Deployment, raises it. Expect
+  about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`.
+- **Preflight.** The first coding run after a control-plane restart also runs
+  the cluster preflight canary, because start-up preflight is deferred while the
+  proxy sleeps (`kubernetes_preflight_deferred`).
+- **Deploys.** Every `up.sh` run, including one that turns the mode off, marks
+  the proxy and gateway as just woken before it brings them back up, so the
+  control plane being replaced cannot scale them down mid-deploy. With the mode
+  on they stay up through the deploy (its database checks need them) and sleep
+  one idle window later.
+- **Control plane.** It scales 1 to 2 on CPU (20% target, scale down
+  after 10 minutes). A run executes on the copy that started it, so scheduled
+  runs stay on the scheduler leader; webhook and MCP-started runs spread. The
+  autoscaler owns the replica count while the mode is on.
+
+## Sleep now
+
+To skip the idle window, for example right after a test, call `power_sleep`.
+Pass `target: "proxy"` or `target: "gateway"` to sleep one; omit it for both.
+
+- It scales the target to 0 at once, ignoring the idle window and the woke-at
+  grace.
+- It never stops a run. A target with a pending or running run, or for the
+  gateway an active gateway session, stays up, and its run ids are returned:
+  `{ "slept": ["proxy"], "blocked": [{ "target": "gateway", "runIds": ["..."] }] }`.
+  Recently finished runs do not block it.
+- The next run wakes the target as usual.
+- Each call is logged with `event: "power.sleep"` and the caller's principal.
+
+`power_status` returns, for each target, `replicas`, `ready`, `wokeAt` and
+`blockers` (the run ids keeping it busy).
+
+Both tools need the `power:manage` scope, which only the `admin` role grants
+(see [Identity and access](identity-and-access.md)). With the mode off,
+`power_sleep` fails with
+[`409 low_power_disabled`](errors/low-power-disabled.md) and `power_status`
+returns `{ "enabled": false }`.
+
+## Trade-offs and requirements
+
+- With headroom off, the control plane has less protection against preemption.
+- The gateway runs 1 replica instead of 2 while awake: no redundancy.
+- `NATIVE_SANDBOX_WARM_POOL_SIZE` must be 0, or the control plane refuses to
+  start.
+- The gateway must be in the same namespace as `KUBERNETES_NAMESPACE`.
+
+## Cost
+
+Autopilot bills Pod requests while a Pod exists. At us-central1 list prices
+($0.0445 per vCPU-hour, $0.0049225 per GiB-hour, 730 hours a month; use your
+region's rates), always-on cost per workload is: control plane (1.1 vCPU / 2.125
+GiB) $43.37, coding proxy (1.1 / 3.125) $46.96, native gateway (0.35 / 0.625 per
+replica, two replicas) $27.23, headroom (0.25 / 0.5) $9.92. In low-power mode
+the proxy costs $0.0643 an hour and a gateway replica $0.0187 an hour only
+while awake, and headroom costs nothing. See
+[Getting started on GKE](../docs/getting-started-gke.md#low-power-mode) for the
+full table.
+
+## Errors and log lines
+
+- [`low_power_wake_timeout`](errors/low-power-wake-timeout.md): the target did
+  not become ready in time, or its Deployment does not exist.
+- [`low_power_disabled`](errors/low-power-disabled.md): `power_sleep` was
+  called while the mode is off.
+- [`low_power_scale_forbidden`](errors/low-power-scale-forbidden.md): the
+  control plane may not read or scale a Deployment or read its Endpoints
+  (Role `wardby-power` missing or out of date).
+- Also: `power_sleep_failed`, `low_power_access_check_failed`,
+  `low_power_ignored`.
+
+## Local kind
+
+`WARDBY_LOW_POWER=1 deploy/kind-coding/up.sh` applies the Role. The kind control
+plane runs on your host, so set `WARDBY_LOW_POWER=1` (and optionally
+`LOW_POWER_IDLE_MINUTES`) in the environment of `wardby serve` too.
+
+Related: [Deploy Wardby on GKE Autopilot](deploy-gke.md),
+[Run native agents in a sandbox](native-sandbox.md).

package/help/merge-order-check.md

@@ -0,0 +1,117 @@
+---
+id: merge-order-check
+title: The wardby merge order check
+summary: A per-pull-request `wardby merge order` check that tracks whether the pull requests a step depends on, by mergeOrder, have merged yet.
+audience: operator
+tags: [github, checks, branch protection, merge order, delegation, mergeOrder, pull-requests, related-pull-requests]
+appliesTo: ">=0.6.0"
+---
+
+# The wardby merge order check
+
+> **Requires Wardby 0.6.0 or later.**
+
+When a delegating agent sets a `mergeOrder` on a request's pull requests
+(see [Setting a merge
+order](related-pull-requests.md#setting-a-merge-order)), Wardby posts a
+check run named exactly **`wardby merge order`** on each open or draft pull
+request of that [related set](related-pull-requests.md) that its own GitHub
+App opened. The check tells you, per pull request, whether the steps it
+depends on have merged yet — so you can tell at a glance, or gate a merge
+on it, without reading every sibling pull request's state by hand.
+
+## When it is posted
+
+Only when the pull request's related set has **more than one distinct
+`mergeOrder` value** across its members, merged and closed ones included.
+A request whose pull requests all share one `mergeOrder`, or carry none at
+all, gets no check. A pull request without a `mergeOrder` is never checked
+itself, and is never any other pull request's dependency either.
+
+A member with order _k_ depends on every other member of the set with a
+strictly lower, non-null order. Members that share the same `mergeOrder`
+have no order between them — neither is the other's dependency, and either
+may merge first.
+
+## The three states
+
+- **Waiting for earlier steps (`in_progress`)** — one or more dependencies
+  (strictly lower `mergeOrder`) have not merged yet. The title reads
+  "Waiting for _N_ earlier pull request(s) to merge", and the summary lists
+  them by link.
+- **Every earlier step has merged (`success`)** — every dependency has
+  merged, or the pull request is the set's lowest step and has nothing to
+  wait for. The check completes with conclusion `success`.
+- **An earlier step was closed without merging (`failure`)** — a dependency
+  was closed and never merged. The check completes with conclusion
+  `failure` and names the closed pull request(s) in the summary.
+
+Every state's summary also carries a step label, "Step _k_ of _n_ in the
+merge order set by the delegating agent," counted over the whole set
+(merged and closed pull requests included), so a pull request's step
+number doesn't change as earlier steps merge.
+
+### Waiting for the delegating run to finish
+
+While the delegating (lead) agent's run that produced this set is still
+running, it may still add or reorder steps. So, for every pull request
+above the set's **lowest** step, a would-be `success` is held back: the
+check stays `in_progress` with the title "Waiting for the delegating run
+to finish" until that run ends, however it ends. Only a lead agent's run
+holds later steps this way: a coding run that continues one of the set's
+pull requests on its own (a review fix round, or an `@` mention picked up
+by a coding link) never does, and its pushes update the check as they
+land. The lowest step still
+reports `success` right away ("First step: nothing to wait for") — it has
+no dependency this hold could change. A pull request already `in_progress`
+on an unmerged dependency, or `failure` on a closed one, is reported as
+such regardless of whether the delegating run is still running.
+
+## When it is updated
+
+The check is recomputed and reposted, reading every member's current state
+live from GitHub:
+
+- when the delegating (lead) agent's run finishes;
+- when any pull request in the set is closed or merged;
+- on a new head or a reopen of any pull request in
+  the set, on every open or draft pull request Wardby's own GitHub App
+  opened; and
+- by Wardby's own reconciliation sweep (below), for events the first three
+  points might have missed.
+
+Reopening a closed, unmerged dependency moves any pull request that was
+reported `failure` because of it back to `in_progress` — once that
+dependency merges (or another dependency is still unmerged or closed), the
+check moves on from there as usual.
+
+### The reconciliation sweep
+
+As a fallback for a missed GitHub event, Wardby periodically re-checks
+merge-ordered sets in the background: at most once every 10 minutes per
+process, covering the 50 most recently updated coding runs that carry a
+`mergeOrder` and were updated within the last 7 days, resolved to their
+request's run tree and synced a bounded number at a time, least-recently
+swept first, so every covered set is revisited eventually. A set whose
+pull requests haven't changed in over 7 days relies on its GitHub events
+alone.
+
+## Requiring it in branch protection
+
+Posting the check never blocks a merge by itself — that's opt-in. To make
+GitHub refuse a merge until a pull request's earlier steps have merged,
+add `wardby merge order` as a required status check in the repository's
+branch protection rules (or, on a repository using rulesets, its ruleset's
+required status checks): **Settings → Branches** (or **Rules → Rulesets**)
+**→ require status checks to pass → `wardby merge order`**. GitHub matches
+required checks by name, so it must be exactly that string. Also set the
+required check's expected source to your Wardby GitHub App, so a check of
+the same name reported by anything else (another App, or a workflow in the
+repository — any workflow with `checks: write`, such as one running on a
+pull request author's `GITHUB_TOKEN`) cannot satisfy it. A request
+without a `mergeOrder` on more than one pull request never posts this
+check, so don't require it on a repository whose pull requests are never
+ordered this way — GitHub would then wait on a check that never arrives.
+
+See also [Branch protection](../docs/code-review-agents.md#branch-protection)
+for requiring a passing _review_ the same way.

package/help/mobile-app.md

@@ -0,0 +1,54 @@
+---
+id: mobile-app
+title: Use the wardby mobile app
+summary: Let admins sign in to the wardby mobile app for a read-only live view of runs; enable it with WARDBY_MOBILE_ENABLED on self-hosted auth or register the redirect URI in your IdP.
+audience: operator
+tags: [mobile, ios, android, sign-in, oauth, WARDBY_MOBILE_ENABLED]
+appliesTo: ">=0.6.0"
+---
+
+# Use the wardby mobile app
+
+The mobile app is a read-only live view of runs for admins, built on the admin
+viewer API (see `admin-viewer`). Sign-in needs the `admin` role and the
+`admin:view` scope.
+
+## Enable it with self-hosted auth
+
+Mobile sign-in is off by default. Set `WARDBY_MOBILE_ENABLED=true` on the
+control plane and restart it. The OAuth server then accepts exactly one extra
+redirect URI, `com.wardby.mobile:/oauth`, by exact match only. On GKE, pass
+`WARDBY_MOBILE_ENABLED=true` to `deploy/gke/up.sh` on every run; a run without it
+turns mobile sign-in off.
+
+`WARDBY_MOBILE_REDIRECT_URI` is for white-label builds only. It must be a
+reverse-domain private-use URI, for example `com.example.app:/oauth`: a
+lowercase scheme with at least one dot, then `:/`, then a path of letters,
+digits, `/`, `_` or `-`, with no host, query or fragment. Changing it signs out
+app clients registered under the old value; they must sign in again. A
+malformed `WARDBY_MOBILE_ENABLED` or `WARDBY_MOBILE_REDIRECT_URI` stops startup
+in every auth mode.
+
+## Enable it with an external identity provider
+
+Wardby needs no setting. Register `com.wardby.mobile:/oauth` (or your
+white-label redirect) as an allowed redirect URI on the IdP client that
+requests `admin:view`, and make sure the `admin:view` scope is defined and
+mapped. See [Configure identity and privileged access](identity-and-access.md).
+
+## Turning it off
+
+Set `WARDBY_MOBILE_ENABLED=false` (or unset it). New sign-ins and token
+refreshes are refused. Access tokens already issued keep working until they
+expire, at most 10 minutes. Turning it back on lets existing sessions refresh
+again; nothing is revoked.
+
+## Troubleshooting
+
+If the app's registration or sign-in is refused with `mobile_disabled`, see
+[Mobile sign-in is not enabled](errors/mobile-disabled.md).
+
+## See also
+
+- [Watch live runs with the admin viewer API](admin-viewer.md)
+- The viewer API reference in `docs/viewer-api.md`.

package/help/native-sandbox.md

@@ -0,0 +1,136 @@
+---
+id: native-sandbox
+title: Run native agents in a sandbox
+summary: Turn on sandbox mode so a native agent's turn loop and tools run in a single-use, credential-free Docker container or Kubernetes pod behind a native gateway.
+audience: operator
+tags: [native-agents, sandbox, isolation, docker, kubernetes, native-gateway, security, warm-pool]
+appliesTo: ">=0.5.4"
+---
+
+# Run native agents in a sandbox
+
+By default a native agent runs inside the Wardby server. Set its
+`nativeExecutionMode` to `sandbox` and its whole turn loop and user tools run in
+a single-use Docker container or Kubernetes pod (the `wardby-native-worker`
+image) instead. The
+container has no credentials, no database access, no Docker socket, and no
+network except the **native gateway**, a separate trusted container that holds
+the LLM credentials and enforces each tool attachment's grants. The server and
+gateway are trusted; the agent loop and user tool code are not.
+
+## Turn it on
+
+1. Run the gateway: `wardby native-gateway` in a container with the server's
+   database, LLM, secrets, and integration settings, listening on
+   `NATIVE_GATEWAY_LISTEN` (default `0.0.0.0:8790`; `GET /healthz`). Give it no
+   Docker socket.
+2. On the server (`wardby serve` or `wardby scheduler`) set
+   `NATIVE_SANDBOX_LAUNCHER=docker`, `NATIVE_SANDBOX_WORKER_IMAGE` (a
+   `repo@sha256:...` digest or local image id), and `NATIVE_GATEWAY_CONTAINER`
+   (the gateway container's name). Optional: `NATIVE_GATEWAY_URL`,
+   `NATIVE_SANDBOX_CPUS` (1), `NATIVE_SANDBOX_MEMORY_MB` (512),
+   `NATIVE_SANDBOX_PIDS` (128).
+3. Set the mode with `create_agent` or `update_agent` (`nativeExecutionMode`:
+   `control-plane` or `sandbox`; native agents only), or from the CLI with
+   `wardby agent create ... --native-execution-mode sandbox` or
+   `wardby agent mode <name> sandbox`. `sandbox` is refused when the server
+   (or, for the CLI, its environment) has no native sandbox configured. Each
+   run keeps the mode it started with; `get_run` shows it.
+
+### Kubernetes
+
+Set `NATIVE_SANDBOX_LAUNCHER=kubernetes` instead and the server starts one pod
+per run. Run the gateway as a Deployment in the run namespace with a ClusterIP
+Service that exposes both 8790 and the deny port 8791, and a NetworkPolicy that
+admits `wardby.io/component: native-run` pods on both ports (keep the 8791
+rule). On the server set `NATIVE_SANDBOX_WORKER_IMAGE` to a registry digest
+(`repo@sha256:...`; a local image id is not accepted), and optionally
+`NATIVE_SANDBOX_NAMESPACE` (default `KUBERNETES_NAMESPACE`, else
+`wardby-coding`), `KUBERNETES_CONTEXT`, `NATIVE_SANDBOX_RUNTIME_CLASS` (for
+example gVisor), `NATIVE_GATEWAY_SERVICE` (default `wardby-native-gateway`),
+`NATIVE_SANDBOX_PRIORITY_CLASS` (not a `system-` class),
+`NATIVE_SANDBOX_MAX_CONCURRENT` (cap on simultaneous sandbox runs across all
+replicas; unset means no cap), `NATIVE_SANDBOX_READY_TIMEOUT_MS` (default 120000) and `NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS` (default 30000).
+`NATIVE_SANDBOX_PIDS` applies to Docker only. On GKE Autopilot also set
+`KUBERNETES_PLATFORM=gke-autopilot`: pod resources are conformed to Autopilot's
+rules and the gVisor runtime class is required. On Amazon EKS with a gVisor node
+group set `KUBERNETES_PLATFORM=eks`, which also requires the gVisor runtime class. The shipped GKE deployment
+runs the gateway for you; see the GKE guide. The
+server needs permission in that namespace to create, get, and delete pods,
+Secrets, and NetworkPolicies, list pods, exec into pods, and get Services.
+
+Each run starts "not ready": the gateway refuses the worker until the server
+has verified the pod and its NetworkPolicy and proven from inside the pod that
+the gateway answers while the deny port, the outside world, and the cloud
+metadata endpoints do not. Failures
+there are
+[native_sandbox_network_unenforced](errors/native-sandbox-network-unenforced.md),
+[native_sandbox_isolation_mismatch](errors/native-sandbox-isolation-mismatch.md),
+[native_sandbox_gateway_unavailable](errors/native-sandbox-gateway-unavailable.md),
+and [native_sandbox_worker_unready](errors/native-sandbox-worker-unready.md).
+A start past the concurrent cap or the namespace quota fails with
+[native_sandbox_capacity](errors/native-sandbox-capacity.md).
+
+The full procedure, topology, and local compose overlay are in
+[Native sandbox](../docs/native-sandbox.md).
+
+### Warm pool
+
+Set `NATIVE_SANDBOX_WARM_POOL_SIZE` (0 to 50, default 0 = off) to keep that many
+idle, already-isolated workers ready, with either launcher. A run claims one
+atomically through the database; its input and one-time gateway capability are
+delivered over exec stdin only after the claim, and the worker is still
+single-use. `NATIVE_SANDBOX_WARM_MAX_AGE_MS` (60000 to 21600000, default 1800000) replaces idle workers older than that. With no idle worker, or one that
+fails the claim-time re-check, the run cold-launches as usual. If delivery fails
+and the worker cannot be confirmed gone within 30 seconds, the run fails with
+[native_sandbox_warm_delivery_failed](errors/native-sandbox-warm-delivery-failed.md).
+
+Idle workers are extra pods or containers: the Kubernetes ResourceQuota needs
+room for `NATIVE_SANDBOX_MAX_CONCURRENT` plus the pool size, and each idle
+worker reserves its CPU and memory (billed on GKE Autopilot). Rebuild the worker
+image so it can be a pool worker. Pool workers are named `wardby-nwarm-<token>`
+and labelled `wardby.io/pool=warm`; logs use module `native-warm-pool`. Details
+are in [Native sandbox](../docs/native-sandbox.md#warm-pool).
+
+## What to expect
+
+- The worker is read-only, non-root (uid 10001), has all capabilities dropped, a
+  size-capped `/tmp`, and CPU, memory, and PID limits. Each run gets its own
+  internal network shared only with the gateway.
+- The gateway is the budget authority: it reserves each model call's worst-case
+  cost first and settles at actual usage. A call the budget cannot cover ends the
+  run `budget_exhausted`.
+- Sub-agents of a sandboxed run are managed runs started by the scheduler
+  leader on its next tick (about every 10 seconds), so the server or scheduler
+  must be running.
+- A sandbox run has a 60-minute maximum lifetime.
+
+## Roll back
+
+Set the agent back to `control-plane`. Only new runs are affected: runs
+already started in sandbox mode finish there.
+
+## Troubleshooting
+
+Check the gateway with `GET /healthz`, list worker containers with
+`docker ps --all --filter label=io.wardby.component=native-worker`, and read the
+run's error with `get_run`. On Kubernetes list worker pods with
+`kubectl get pods -n <namespace> -l wardby.io/component=native-run`. Error
+codes:
+
+- [native_sandbox_unavailable](errors/native-sandbox-unavailable.md)
+- [native_sandbox_worker_exited](errors/native-sandbox-worker-exited.md)
+- [native_sandbox_deadline_exceeded](errors/native-sandbox-deadline-exceeded.md)
+- [native_sandbox_worker_lost](errors/native-sandbox-worker-lost.md)
+- [native_sandbox_image_not_pinned](errors/native-sandbox-image-not-pinned.md)
+- [native_sandbox_docker_failed](errors/native-sandbox-docker-failed.md)
+- [native_sandbox_network_unenforced](errors/native-sandbox-network-unenforced.md)
+- [native_sandbox_isolation_mismatch](errors/native-sandbox-isolation-mismatch.md)
+- [native_sandbox_gateway_unavailable](errors/native-sandbox-gateway-unavailable.md)
+- [native_sandbox_worker_unready](errors/native-sandbox-worker-unready.md)
+- [native_sandbox_capacity](errors/native-sandbox-capacity.md)
+- [native_sandbox_warm_delivery_failed](errors/native-sandbox-warm-delivery-failed.md)
+- [native_sandbox_requires_catalog](errors/native-sandbox-requires-catalog.md)
+
+See also [Use native agents, tools, and data](native-capabilities.md) and
+[Understand Wardby security boundaries](security.md).

package/help/observability.md

@@ -37,5 +37,13 @@ Alert on proxy failures, budget cutoffs, cleanup failures, stalled runs, and
 sustained latency or memory growth. Wardby's database remains the source of
 truth for runs, budgets, and accounting.
 
+With the durable executor (`EXECUTOR=dbos`), also watch the server logs for
+the `run_ownership_lost` warning. It means a run's owner stalled long enough
+for another process to adopt the run, and the stalled attempt stopped without
+writing the run; the step it stopped at had its model spend discarded. The run
+itself is unaffected. Repeated warnings point at event-loop or database-pool
+starvation. See the durable executor section of
+[`docs/security-deployment.md`](../docs/security-deployment.md).
+
 Read [`docs/observability.md`](../docs/observability.md) for configuration and
 the full production checklist.

package/help/related-pull-requests.md

@@ -1,7 +1,7 @@
 ---
 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.
+summary: Wardby lists the other pull requests from the same request in each pull request's description, in the merge order the delegating agent set (mergeOrder) or else a suggested merge order.
 audience: operator
 tags: [github, pull-requests, multi-repo, merge-order, related, siblings, continuePriorRun, coding-agents, jira]
 appliesTo: ">=0.4.2"
@@ -14,7 +14,7 @@ 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.
+merge order: the one the delegating agent set, or else a suggested one.
 
 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
@@ -30,13 +30,33 @@ included, plus that run tree's own siblings.
   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
+  With Wardby 0.6.0 or later, a reviewer linked to one of these pull requests does
+  not review it until that same lead run finishes, however it ends. When the
+  lead finishes normally the section has already been rewritten by then;
+  when it is ended another way, such as being cancelled, reviews start
+  without that rewrite, so reviewers should rely on `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).
+- **Merge order.** Without a `mergeOrder` (see below) on any pull request in
+  the set, open (and draft) pull requests are numbered as a **Suggested merge
+  order (the order Wardby's agent opened them in)** — delegation order, not a
+  dependency analysis, and 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.
+  When any pull request in the set has a `mergeOrder` (open, merged or
+  closed), the open ones that have one 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 merge in either
+  order relative to each other), and any open pull request without one is
+  listed after under "Not ordered:". If only merged or closed pull requests
+  have a `mergeOrder`, every open one is listed under "Not ordered:" and the
+  "Merge order" heading is left out. Steps are counted over the whole set,
+  merged and closed pull requests included, so "step 2 of 3" keeps its label
+  after step 1 merges. Either way, check it before merging — neither is a
+  guarantee. Merged and closed pull requests follow in a separate "Already
+  merged or closed" list, as context only, with their step label when they
+  have one.
 - 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.
@@ -49,9 +69,50 @@ included, plus that run tree's own siblings.
 
 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
+a sibling pull request rather than missing. Because the description is only
+rewritten at the points above, a sibling opened (or merged, or closed) since
+then can be missing from it or shown with an old state. With Wardby 0.6.0 or later,
+`repo_pr_read`'s `relatedPullRequests` field lists the request's pull
+requests fresh on every call instead, so a reviewer should prefer it over
+the description's section when they disagree. Its entry for the pull request
+just read always carries that pull request's live state; another entry
+carries a state only when Wardby has one stored (pull requests linked to an
+issue) and omits it otherwise, so call `repo_pr_read` on that pull request
+for its live state. `relatedPullRequests` is empty for a pull request on a
+local repository, which has no App-authored marker to resolve the request
+from. See the
+reviewer step in
 [Run GitHub code-review agents](code-review-agents.md#ci-and-sibling-pull-requests).
 
+## Setting a merge order
+
+A lead agent sets the order explicitly by passing `mergeOrder` on its
+`delegate_to_<name>` call to a coding sub-agent: 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 use it — for example a shared
+service `1`, the API that calls it `2`, the client that calls the API `3`.
+Give two changes the same number when there is no order between them; they
+share a step and either can merge first. A bad value (not an integer, or
+outside 1-99) is refused as a tool error, not silently dropped or clamped.
+
+Set it whenever one request's change spans several repositories and the
+pull requests need to land in a specific sequence; leave it out and the set
+keeps the delegation-order suggestion above. `mergeOrder` applies only to
+coding sub-agents, since only a coding run's pull request can be ordered: a
+native sub-agent ignores it, and its 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 current value, so a follow-up does not need to
+repeat it to keep a pull request in its place; one that sets `mergeOrder`
+replaces it.
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+open or draft pull request Wardby opened in it also gets a check run named
+`wardby merge order`, tracking whether the pull requests it depends on have
+merged yet. It's an informational check by default; search help for "merge
+order check" for its states and for requiring it in branch protection.
+
 ## Follow-up runs and sibling pull requests
 
 When someone asks for a follow-up on one of these pull requests (an