@wardby/cli 0.5.3 → 0.6.0

package/help/errors/slack-channel-unreachable.md

@@ -0,0 +1,39 @@
+---
+id: errors/slack-channel-unreachable
+title: Channel unreachable — bot not invited or archived
+summary: wardby's bot can no longer post to a linked Slack channel — it was removed, archived, or never invited — and that channel's pending deliveries have failed.
+audience: operator
+tags: [error, notifications, channel, channel-error, not_in_channel, channel_not_found, is_archived]
+appliesTo: ">=0.6.0"
+---
+
+# Channel unreachable — bot not invited or archived
+
+Slack returned `channel_not_found`, `not_in_channel`, or `is_archived` when
+wardby tried to post or update a message. This means the bot genuinely
+cannot write to that channel right now — the channel was deleted or
+archived, or (most commonly) the bot was never invited to a private
+channel.
+
+wardby fails that channel's pending deliveries immediately rather than
+retrying forever, and stamps the error on every `NotificationChannel` link
+pointing at it. `list_notification_channels` shows it in `lastError` until
+you fix it.
+
+## What to do
+
+1. In Slack, confirm the channel still exists and isn't archived.
+2. If it's private, invite the bot: `/invite @wardby` (or whatever you named
+   the app) in that channel.
+3. Confirm it worked with `test_notification_channel` — it posts "✅ wardby
+   is connected to this channel."
+4. New events deliver as soon as the bot can post there again. Deliveries
+   that already failed are not resent. To clear `lastError`, re-link the
+   channel with `link_notification_channel` using the same arguments as
+   before (a successful `test_notification_channel` in step 3 also clears it).
+
+If the channel is gone for good, remove the link with
+`unlink_notification_channel` instead.
+
+See [Send workflow updates to Slack](../../docs/slack-notifications.md) for
+the full guide.

package/help/errors/slack-not-configured.md

@@ -0,0 +1,33 @@
+---
+id: errors/slack-not-configured
+title: Notification bot token not configured
+summary: link_notification_channel and test_notification_channel are refused because wardby has no Slack bot token configured.
+audience: operator
+tags: [error, notifications, configuration, config, setup, WARDBY_SLACK_BOT_TOKEN]
+appliesTo: ">=0.6.0"
+---
+
+# Notification bot token not configured
+
+`link_notification_channel` and `test_notification_channel` are refused when
+the wardby server has no `WARDBY_SLACK_BOT_TOKEN` set. Without it, Slack workflow notifications are
+entirely disabled: the notification dispatcher does not start, and any event
+that would otherwise post to Slack is skipped — none are queued or
+backfilled once you do configure it.
+
+`list_notification_channels` and `unlink_notification_channel` still work,
+so you can see and remove links created earlier, but nothing is delivered to
+them while Slack is unconfigured.
+
+## What to do
+
+1. Create the Slack app from
+   [`deploy/slack/app-manifest.yaml`](../../deploy/slack/app-manifest.yaml)
+   and install it to your workspace.
+2. Copy the Bot User OAuth Token (`xoxb-…`) and set
+   `WARDBY_SLACK_BOT_TOKEN`, stored like any other provider credential.
+3. Restart wardby. The startup log line `chat notifications acting as`
+   confirms which Slack workspace and bot it authenticated as.
+
+See [Send workflow updates to Slack](../../docs/slack-notifications.md) for
+the full setup.

package/help/getting-started.md

@@ -47,11 +47,10 @@ Claude Code. Run `wardby doctor` afterwards to verify the local installation.
   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).
 
-- **D. Another language (Go, Java, Rust…).** Do A with Codex, then build a
-  worker image with that toolchain on the base image `wardby doctor` prints,
-  and set the builder's `codingProfile.workerImageRef`. Ask your assistant
-  "Help me build a Wardby worker image for Go"; it follows
-  [Build a custom worker image](build-worker-image.md). Codex agents only.
+- **D. Another language (Go, Java, Rust…).** Do A, then build an image with
+  that toolchain and set the builder's `codingProfile.workerImageRef`. Ask your
+  assistant "Help me build a Wardby worker image for Go"; it follows
+  [Build a custom worker image](build-worker-image.md).
 
 The quickstart ends with a menu of next steps to ask your assistant: run the
 builder and reviewer, allow more packages, build a worker image, schedule an

package/help/github.md

@@ -3,7 +3,7 @@ id: github-integration
 title: Connect GitHub repositories
 summary: Authorize repository access and configure Wardby coding or review agents through a scoped GitHub App.
 audience: operator
-tags: [github, repositories, coding-agents, code-review]
+tags: [github, repositories, coding-agents, code-review, WARDBY_GITHUB_ALLOWED_ACCOUNTS]
 appliesTo: >=0.2.1
 ---
 
@@ -27,6 +27,17 @@ 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).
 
+From Wardby 0.6.0, wardby serves only trusted GitHub accounts through the App:
+the App's owner, plus any accounts listed in `WARDBY_GITHUB_ALLOWED_ACCOUNTS`
+(comma-separated logins). Other accounts' events are ignored and their
+repositories are refused with `github_account_not_allowed` (help article
+`errors/github-account-not-allowed`), including existing links and scheduled
+runs after an upgrade. wardby removes the App when another account installs it
+or changes its repository selection; remove installations that already exist
+on other accounts by hand (App settings, **Install App**). After transferring
+the App or renaming its owner, list the new owner in the variable or restart
+wardby.
+
 No GitHub App is needed for a git repository on the wardby host. See
 [Use local git repositories](local-repositories.md).
 
@@ -62,4 +73,10 @@ opened. See [Automatic review fix rounds](review-fix-rounds.md).
 finishes, and gates its ability to approve on CI passing. See
 [Review after CI (`waitForCi`)](code-review-agents.md#review-after-ci-waitforci).
 
+With Wardby 0.6.0 or later, a `pull_request` reviewer also holds its review, with or without
+`waitForCi`, until the pull request's own delegating run finishes, when its
+opening coding run was delegated by a lead agent. See [Reviewing a pull
+request a delegated run
+opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
+
 For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/identity-and-access.md

@@ -21,7 +21,7 @@ audience, and the granted Wardby scopes in `scope` or `scp`.
 
 Scopes authorize normal operations such as managing agents, runs, tools,
 datastores, secrets, webhooks, budgets, packages, services, memory, and
-models. Five sensitive permissions have an additional role requirement:
+models. Six sensitive permissions have an additional role requirement:
 
 - `agents:admin` requires the Wardby `admin` role.
 - `packages:approve` requires the `admin` or `package-approver` role.
@@ -31,6 +31,10 @@ models. Five sensitive permissions have an additional role requirement:
 - `models:admin` requires the `admin` or `model-manager` role. It adds,
   overrides, disables, and resets model catalog entries; see
   [Models and pricing](models.md).
+- `power:manage` requires the `admin` role. It reads low-power state and
+  sleeps the coding proxy and native gateway now (`power_status`,
+  `power_sleep`); see
+  [Low-power mode](../docs/getting-started-gke.md#low-power-mode).
 
 Map roles only from an IdP claim that users cannot self-assign. Removing a
 role affects the next token the caller receives.

package/help/local-repositories.md

@@ -143,9 +143,8 @@ then:
   `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`, which is
-  Codex-only today: Claude Code agents cannot use a custom toolchain yet. See
-  the BYO worker images guide in the long-form docs;
+  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

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.