@wardby/cli 0.5.3 → 0.7.0

package/help/knowledge.md

@@ -1,9 +1,9 @@
 ---
 id: knowledge
 title: Architecture knowledge bundles
-summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
+summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ (or a folder you pick in .wardby/knowledge.yaml) so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
 audience: operator
-tags: [knowledge, architecture, coding-agents, okf, cli, drift, push]
+tags: [knowledge, architecture, coding-agents, okf, cli, drift, push, knowledge.yaml, bundle-path]
 appliesTo: >=0.4.0
 ---
 
@@ -16,9 +16,18 @@ their reasons, and cross-module contracts. It uses the Open Knowledge Format
 for, the paths it affects, and citations to the code it describes. Each citation
 carries a commit `sha` and a `spanHash` so staleness can be detected.
 
-- `docs/knowledge/index.md` lists every concept in one line; `log.md` records
-  changes to the bundle.
-- When `docs/knowledge/index.md` exists on a coding run's base branch, the run's
+- `index.md` lists every concept in one line; `log.md` records changes to the
+  bundle.
+- **Pick your own folder:** add `.wardby/knowledge.yaml` with one line,
+  `path: .okf` (any repo-relative folder outside `.wardby/` and `.git/`). Wardby
+  then reads the bundle there for the coding-run note, merge-watcher drift runs,
+  and `wardby knowledge check`. Without the file it uses `docs/knowledge/`; an
+  invalid file is ignored with a warning (`knowledge_config_invalid` from the
+  check). Or skip wardby's reading entirely: tell your agents where knowledge
+  lives in their prompts or `AGENTS.md`, and they use that folder; you lose
+  only the automatic note and drift scoping on merge. Update any prompt that
+  names `docs/knowledge/` to your folder.
+- When the bundle's `index.md` exists on a coding run's base branch, the run's
   task includes the index automatically (up to 8 KiB). It never fails a
   dispatch; an unreadable index just means no note.
 - When the run's commit is known (it always is for a normal clone) and the
@@ -26,8 +35,8 @@ carries a commit `sha` and a `spanHash` so staleness can be detected.
   has no git metadata, so use that value for citation `sha` fields.
 - Validate the bundle with `wardby knowledge check` (add `--strict` to fail on
   warnings, `--json` for machine output, `--root` to point at the repository).
-  Errors are `concept_invalid`, `concept_secret`, `index_missing`, and
-  `index_link_broken`; warnings are `concept_not_indexed`,
+  Errors are `concept_invalid`, `concept_secret`, `index_missing`,
+  `index_link_broken`, and `knowledge_config_invalid`; warnings are `concept_not_indexed`,
   `citation_unverifiable`, and `citation_stale`.
 - Builders may edit concept prose. Citations can go stale afterward; the
   architecture agent re-anchors them.

package/help/local-repositories.md

@@ -50,7 +50,7 @@ The easiest way to try it is the optional coding step of
   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.
+- **git 2.38 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
@@ -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,131 @@
+---
+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`. A
+  sandbox run woken this way may then wait for a gVisor node for its worker
+  pod, so its first model call can come several minutes after it started. From
+  0.7.0 it shows as running the whole time and is not reaped as orphaned; only
+  the wake and pod-start limits above can fail it.
+- **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.
+- `native_sandbox_launch_abandoned` (0.7.0 and later): a sandbox run was
+  stopped while the gateway woke, so no worker pod was made.
+- [`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,122 @@
+---
+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.
+
+With Wardby 0.7.0 or later, when the delegating lead is linked with
+`markReadyWhenPassing`, later steps become ready for review only once this
+check is `success`. See
+[Mark ready when passing](code-review-agents.md#mark-ready-when-passing).
+
+### 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-capabilities.md

@@ -3,7 +3,7 @@ id: native-capabilities
 title: Use native agents, tools, and data
 summary: Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.
 audience: developer
-tags: [agents, tools, secrets, datastores, memory, schedules, subagents]
+tags: [agents, tools, secrets, datastores, memory, schedules, subagents, zod, paramsZod, create_tool, dry_run_tool]
 appliesTo: >=0.2.1
 ---
 
@@ -20,6 +20,34 @@ checkout. Give each agent only the capabilities its job needs:
 - **Schedules and webhooks** to start event-driven work.
 - **Sub-agents** for delegated, bounded work with their own capability set.
 
+A tool's parameters are a Zod schema written as source text (`paramsZod` on
+`create_tool` and `update_tool`). Wardby compiles it inside the sandbox, both to
+derive the JSON Schema the model sees and to validate each call's arguments.
+
+Wardby itself now uses Zod 4. For this release only, a tool's `paramsZod` is
+still compiled with Zod 3 (Zod 4's built-in `zod/v3` API), so existing tools keep
+working unchanged; a schema Zod 3 can't compile, such as one using `z.email()`,
+is compiled with Zod 4. **Zod 3 schemas stop working in the next release**,
+which compiles `paramsZod` with Zod 4 only. A schema that calls something Zod 4
+removed, such as `.nonstrict()`, `.deepPartial()`, `z.ostring()` or
+`z.string().ip()`, will then fail every call's validation.
+
+Wardby warns about each such tool now:
+
+- `create_tool`, `update_tool` and `dry_run_tool` results include a `warnings`
+  list naming the tool and the removed methods;
+- in `list_tools` and in `get_agent`'s attached tools, each tool you own that is
+  affected carries the same `warnings` list;
+- `wardby tool create` and bundle imports print the same warning;
+- the server logs one warning per affected tool at startup.
+
+To check a schema before the next release, call `dry_run_tool` with the tool's
+`paramsZod` and sample arguments. With no `warnings` in the result, the schema
+compiles with Zod 4 and Zod 4 treats those arguments the same way. Otherwise,
+rewrite the schema with the Zod 4 API (for example `z.looseObject()` for
+`.nonstrict()`, `z.string().optional()` for `z.ostring()`, and `z.ipv4()` or
+`z.ipv6()` for `.ip()`), dry-run it again, and save it with `update_tool`.
+
 Use a budget or shared budget group on every agent, and inspect runs before
 expanding its access. An access grant is intentional delegation: use it only
 when an owner permits one agent to use another resource. Creating or changing

package/help/native-sandbox.md

@@ -0,0 +1,150 @@
+---
+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 coding agent child is resolved by the server when it
+  starts (worker image, services, knowledge), so the gateway needs no `CODING_*`
+  settings; a problem there (such as a `workerImageRef` that is not pinned by digest)
+  shows as the child run `failed` or `refused`; the parent's `delegate_to_*`
+  call receives `status: "failed"` with the `errorCode`, or for a refused child
+  the refusal sentence, and the full error is on the child run (`get_run`).
+  Upgrade `wardby serve` and `wardby scheduler` before or together with the
+  gateway: an older server starts the child unresolved (a Codex child on the
+  default image without its instructions, a Claude Code child failing with
+  `coding_provider_not_configured:claude-code`).
+- A sandbox run has a 60-minute maximum lifetime.
+- `stop_run` stops a sandbox run: its gateway session ends so the worker exits
+  at its next call, and a worker still running after 5 seconds is killed and
+  removed (a warm pool worker is discarded, never reused). Search help for
+  "stop run" (article `stop-run`, Wardby 0.7.0 and later).
+
+## 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_gateway_error](errors/native-sandbox-gateway-error.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/operating-agents.md

@@ -32,5 +32,10 @@ A running run's cost, token counts, and turn count update after each model
 call, so `get_run` and `list_runs` show spend so far rather than zero until the
 run finishes.
 
+To stop a run that is pending, queued, or running (for example one a schedule
+started that you did not want), call `stop_run` with its id. It ends as
+`cancelled`, along with the sub-agent runs it still has in flight. Search help
+for "stop run" (article `stop-run`, Wardby 0.7.0 and later).
+
 For the full lifecycle and the controls applied to every managed run, read
 [`README.md`](../README.md).