@wardby/cli 0.5.2 → 0.6.0

package/help/code-review-agents.md

@@ -43,6 +43,17 @@ from bots and people without write access. Repository links require the
 agent owner's linked GitHub access, or an explicitly recorded administrator
 approval.
 
+## When a review starts
+
+A push normally starts a review right away, but its timing can be held back
+by two independent things: from Wardby 0.6.0, the pull request's own
+delegating request still running (see [Reviewing a pull request a delegated run
+opened](#reviewing-a-pull-request-a-delegated-run-opened) below), and, on a
+link set up for it, CI on the pushed head still running (see [Review after
+CI (`waitForCi`)](#review-after-ci-waitforci) below). Either can delay the
+check that reports the review's result; neither changes what the review
+itself reports once it runs.
+
 ## CI and sibling pull requests
 
 `repo_pr_read` also returns `ci`: the CI check runs and commit statuses on the
@@ -65,6 +76,54 @@ on the review check instead.
 Commit statuses need the App's **Commit statuses: Read** permission; without
 it only check runs are shown.
 
+With Wardby 0.6.0 or later, `repo_pr_read` also returns `relatedPullRequests`: this
+request's pull requests (`repository`, `number`, `state`, `mergeOrder`,
+`self`), computed fresh at call time; empty on a human pull request, one
+with no recognized Wardby marker, or a pull request on a local repository
+(no origin marker to look up there). The `self` entry (the pull request just
+read) always has a `state` (`draft`, `open`, `merged`, or `closed`) from that
+same read. Another entry has a `state` (`open`, `merged`, or `closed`) only
+when Wardby has it stored, as it does for pull requests linked to an issue,
+and omits it otherwise; call `repo_pr_read` on that pull request when you
+need its live state. The list is current; the PR body's **Related pull
+requests** section can be stale — see
+[Related pull requests across repositories](related-pull-requests.md).
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+pull request in it also gets its own check run, named `wardby merge order`,
+independent of any reviewer link; search help for "merge order check" for
+its states and for requiring it in branch protection.
+
+## Reviewing a pull request a delegated run opened
+
+This requires Wardby 0.6.0 or later; earlier releases review such a pull
+request on its first push. When a lead agent delegates coding work and a sub-agent opens the pull
+request (see [Fanning out to several
+builders](../docs/agent-recipes.md#fanning-out-to-several-builders)), every
+reviewer linked with the `pull_request` trigger holds its review of that
+pull request until the delegating (lead) run finishes, however it ends
+(including failing, being cancelled or being lost), even if the link has no
+`waitForCi` set. This gives the request's other pull requests, if any, time
+to open before any of them is reviewed, so a reviewer does not report a
+field or route as missing only because a sibling pull request had not opened
+yet. When the lead run finishes normally, their **Related pull requests**
+sections have also been rewritten (see [Related pull requests across
+repositories](related-pull-requests.md)); when it is ended another way, such
+as being cancelled, held reviews start without that rewrite. Either way,
+reviewers should rely on `repo_pr_read`'s `relatedPullRequests`.
+
+A reviewer linked with `waitForCi` then waits for CI too, once the lead run
+finishes, with its own full 15-minute fallback counted from that point. A
+pull request opened directly, by a human, or on a local repository is never
+held this way. A later request that continues an already-open pull request
+is not held again: the request that opened it has already finished (a push
+inside the same, still-running request is held). If Wardby cannot tell
+whether the pull request's opening run was delegated, the review starts
+right away instead. A held review not released when its lead run finishes is
+reconsidered by Wardby's reconciliation sweep once it has been held for 15
+minutes and released when the lead run has finished, and dropped after 24
+hours like a review held for CI.
+
 ## Review after CI (`waitForCi`)
 
 A `pull_request` link can set `waitForCi: true` so this reviewer reviews a
@@ -105,12 +164,15 @@ Add this to a reviewer's system prompt:
     Reviewer step (CI and related pull requests). Read `ci` from repo_pr_read.
     When `ci` and the description's Tests disagree, follow CI and say so; never
     ask for a fix only because a sandbox test failed while CI passed. Report
-    pending checks as pending. If the description has a "Related pull requests"
-    section, a field, route or schema the change relies on may be added by one
-    of those pull requests: do not report it as missing; note the dependency
-    and the suggested merge order instead.
-
-Wardby also writes that section: see
+    pending checks as pending. If repo_pr_read's relatedPullRequests is
+    non-empty, a field, route or schema the change relies on may be added by
+    one of those pull requests: do not report it as missing; note the
+    dependency and the listed merge order instead. relatedPullRequests is
+    current; the PR body's "Related pull requests" section can be stale.
+
+On a release before 0.6.0, `repo_pr_read` has no `relatedPullRequests`:
+use the description's **Related pull requests** section in its place in that
+step. Wardby also writes that section: see
 [Related pull requests across repositories](related-pull-requests.md).
 
 For App permissions, webhook setup, trigger configuration, and security

package/help/coding-packages.md

@@ -3,7 +3,7 @@ id: coding-packages
 title: Approve packages for coding agents
 summary: Let Codex coding workers install vetted npm and PyPI dependencies through Wardby's registry proxy.
 audience: operator
-tags: [coding-agents, packages, npm, pypi, supply-chain, refusals, lockfile]
+tags: [coding-agents, packages, npm, pypi, supply-chain, refusals, lockfile, extras, pip-extras]
 appliesTo: >=0.2.1
 ---
 
@@ -35,8 +35,37 @@ if its own checks failed. A package reachable only through a refused one is
 refused too, so a high-severity advisory deep in a toolchain blocks every run
 that installs it.
 
+## PyPI extras
+
+A PyPI entry may name extras, as pip does: `psycopg[binary]`,
+`uvicorn[standard]>=0.30`. An extra allows only the dependencies that
+package's own metadata declares under that extra (for `psycopg[binary]`, the
+`psycopg-binary` wheel); a bare `psycopg` entry follows no extra, so
+`psycopg-binary` is refused with `wardby_package_not_allowed`. A plain entry
+follows no extras at all, its own or its dependencies': a plain `fastapi`
+whose metadata asks for `uvicorn[standard]` gets bare `uvicorn` only. Extras a
+dependency line names are followed only below an entry that names extras
+(`fastapi[standard]`), once the proxy has served that parent's metadata: if
+an extra's packages are still refused with `403 wardby_package_not_allowed`,
+name the extra on the allowlist directly (`uvicorn[standard]`). Every
+safeguard still applies to what an extra adds. Extras need the coding proxy
+and control plane on the same Wardby version: a proxy from before extras
+support cannot load an allowlist with a `name[extra]` entry, so every registry
+request of that run fails; and once a profile stores an extras entry, do not
+downgrade below the release that added extras.
+
+The quickstart's coding step offers the packages a local repository declares
+(`package.json`, `pyproject.toml` including its build-system packages,
+`requirements*.txt`, keeping Python extras such as `psycopg[binary]`) as
+`local-builder`'s allowlist after asking, or with `--allow-repo-packages` in a non-interactive
+run. See [Local repositories](local-repositories.md).
+
+> Re-running the quickstart replaces `local-builder`'s package allowlist with
+> what the repository declares (or empties it), discarding any packages you
+> added with `update_agent`; re-add them after a re-run.
+
 Review agents see the pull request's CI results in `repo_pr_read` and are
 told to trust CI over the sandbox's **Tests**.
 
 Read [`docs/coding-packages.md`](../docs/coding-packages.md) for allowlist
-syntax, package-policy controls, lockfile behavior, and refusal errors.
+syntax (including [PyPI extras](../docs/coding-packages.md#pypi-extras)), package-policy controls, lockfile behavior, and refusal errors.

package/help/creating-agents.md

@@ -59,6 +59,20 @@ separately; a missing one fails the run itself at dispatch, not
 `create_agent`/`update_agent`. See [Models and pricing](models.md) and
 [Model not available](errors/model-unavailable.md).
 
+## Run it on a schedule
+
+Give an agent a cron schedule with `set_schedule` (`agentId`, `schedule` such
+as `0 6 * * 1`, and `timezone`), and turn it off with `disable_schedule`. A
+coding agent needs a `codingProfile.defaultTask` first, since a scheduled run
+has no one to pass a task. A native agent's system prompt is its task. Trigger
+the agent once with `trigger_agent` and check the result before scheduling it.
+
+Schedules fire only while a Wardby scheduler runs: `wardby serve`, or
+`wardby scheduler` next to `wardby mcp`. On a quickstart install, start
+`npx @wardby/cli@latest scheduler` from the project directory and keep it
+running; the MCP server your assistant starts never fires schedules. See
+[Operate managed agents](operating-agents.md).
+
 ## Decision checklist
 
 Choose a native agent when all of these are true:

package/help/deploy-gke.md

@@ -11,8 +11,9 @@ appliesTo: >=0.2.1
 
 The supported Google Cloud deployment creates a GKE Autopilot cluster, private
 Cloud SQL for PostgreSQL, Artifact Registry, HTTPS Gateway, Google Secret
-Manager synchronization, and isolated gVisor-backed **Codex** coding-worker
-pods. It also applies namespace RBAC and default-deny network policies.
+Manager synchronization, and isolated gVisor-backed coding-worker pods for
+Codex and Claude Code. It also applies namespace RBAC and default-deny network
+policies.
 
 Use a dedicated billed project, a hostname you control, remote Terraform state,
 and a GitHub App installed only on repositories that agents need. Review
@@ -28,8 +29,12 @@ The deployment process is:
 3. Put first-time values in an untracked `.env.local`; `deploy/gke/up.sh`
    seeds Secret Manager without overwriting existing production values.
    Jira settings are optional there, all or none; see [Jira](jira.md).
-4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
+4. Run `WARDBY_HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
    certificate issuance, database IAM bootstrap, and service health.
+   Use `WARDBY_HOSTNAME`, not `HOSTNAME` (shells set that to the machine name);
+   the script refuses local names such as `*.lan` or `*.local`, and asks you
+   to confirm (or set `WARDBY_HOSTNAME_CHANGE=<new hostname>`) before moving
+   a deployment to a different hostname.
 
 When a release changes `deploy/gke/database-grants.sql`, re-run the database
 grants bootstrap **before** deploying that release, so the proxy role can
@@ -37,9 +42,35 @@ already write the tables and columns it adds (such as per-model usage for
 [cost attribution](cost-attribution.md), or a run's live turn count). Until the
 grants are applied, the coding proxy's writes are refused and coding runs fail.
 
-Claude Code's two-container executor is currently Docker-only; Kubernetes
-coding workers use the Codex path. Configure an identity provider and GitHub
-App before allowing people to use the public endpoint.
+The Kubernetes launcher runs Codex and Claude Code coding workers; a Claude
+Code pod adds a tool-runner sidecar with its own image. Configure an identity
+provider and GitHub App before allowing people to use the public endpoint.
+
+To lower the idle cost of a lightly used deployment, see
+[Low-power mode](../docs/getting-started-gke.md#low-power-mode) (Wardby 0.6.0 and later).
+
+## Plan it with your assistant
+
+If you are an assistant connected to Wardby over MCP and the user asked to plan
+a GKE deployment, produce a written plan; do not create cloud resources. Read
+[Choose a deployment target](deployment-targets.md) first and confirm GKE is
+the right target. Then ask for, one at a time, and record:
+
+1. The Google Cloud project (dedicated, with billing) and region, and who
+   holds the IAM roles to apply Terraform.
+2. The public hostname and who controls its DNS.
+3. The identity provider for people signing in (see
+   [Configure identity and privileged access](identity-and-access.md)).
+4. The GitHub App: which repositories it is installed on (see
+   [Connect GitHub repositories](github.md)).
+5. Which coding providers the agents use (Codex, Claude Code or both), and
+   which provider keys and worker images that needs.
+6. Where Terraform state lives, and the monthly cloud budget and alerts.
+7. Optional: Jira.
+
+The plan lists those answers, the ordered steps above with the values filled
+in, the commands the user will run themselves, and the open questions. Point
+the user to the full guide below for every step.
 
 Follow the complete, ordered guide at
 [`docs/getting-started-gke.md`](../docs/getting-started-gke.md). It includes

package/help/deployment-targets.md

@@ -1,7 +1,7 @@
 ---
 id: deployment-targets
 title: Choose a deployment target
-summary: Pick the supported Wardby deployment path and understand its operational boundary.
+summary: Compare local, self-hosted, and GKE deployment paths and their operational boundaries.
 audience: operator
 tags: [deployment, docker, gke, aws, production]
 appliesTo: >=0.2.1
@@ -9,31 +9,42 @@ appliesTo: >=0.2.1
 
 # Choose a deployment target
 
-Wardby has one local path and two production-ready deployment shapes:
+Wardby has a local development path, a self-hosted container deployment
+reference, and a supported GKE reference deployment. The references provide
+different parts of a production environment; operators must complete the
+remaining controls and verification before accepting production work.
 
 - **Local development:** `wardby quickstart` runs the control plane locally
   with its portable PostgreSQL container. It is the best place to evaluate,
   develop agents, and connect a local Codex or Claude Code client.
-- **Production container baseline:** run the published production image with
-  PostgreSQL, HTTPS ingress, durable storage, backups, and an operator-owned
-  identity provider. The Compose and Caddy configuration is a reference
-  baseline, not a managed platform.
+  `deploy/kind-coding` is a local Kubernetes proof harness, not a production
+  deployment.
+- **Self-hosted container deployment** (e.g., Docker Compose on a VM or
+  on-premises host): Wardby supplies runtime and migration images plus a
+  Compose/Caddy edge reference. The operator supplies PostgreSQL, secrets,
+  network and egress controls, backups and restore testing, monitoring, and a
+  separate coding-controller host. Configure authentication for the deployment.
 - **Google Kubernetes Engine Autopilot:** the supported Google Cloud path. It
-  provisions GKE, private-IP Cloud SQL, Artifact Registry, isolated Codex
-  workers, HTTPS Gateway, and GCP-native secret and network controls. See
+  provisions GKE, private-IP Cloud SQL with backups and point-in-time recovery,
+  Artifact Registry, isolated Codex and Claude Code workers, HTTPS Gateway, and
+  GCP-native secret and network controls. Operators still need to choose
+  availability, test recovery, and configure alerts and retention. See
   [Deploy on GKE](deploy-gke.md).
 
-AWS is supported as a portable runtime target and has a Bedrock Claude adapter,
-but Wardby does not ship a native AWS deployment module. Other cloud providers
+AWS can run the portable runtime and has a Bedrock Claude adapter, but a native
+AWS deployment module is planned and has not shipped. Other cloud providers
 can run the production container image with equivalent database, ingress,
 identity, secret, isolation, and observability controls; that infrastructure is
-operator-owned.
+operator-owned. On Amazon EKS, set `KUBERNETES_PLATFORM=eks` (gVisor node group
+required) and, for RDS, `DATABASE_AUTH=rds-iam`; see "Database
+authentication" in
+[`docs/security-deployment.md`](../docs/security-deployment.md).
 
 The older `deploy/gcp` Cloud Run module is deprecated. Do not choose it for a
 new installation.
 
-Before going live, complete the deployment security checklist and make a
-backup, upgrades, alerting, and incident-response plan. Read
+Before going live, complete the release verification and security deployment
+checks, and make plans for backups, upgrades, alerts, and incident response. Read
 [`docs/getting-started.md`](../docs/getting-started.md) for the local and
 container setup, and [`docs/security-deployment.md`](../docs/security-deployment.md)
 for the production controls.

package/help/errors/coding-provider-not-configured.md

@@ -26,8 +26,8 @@ runs recorded it) when `CODING_WORKER_IMAGE` has since been unset.
   a toolchain with its own image (such as `CODING_WORKER_IMAGE_NODE_PYTHON_3_12`),
   still runs without `CODING_WORKER_IMAGE`.
 - **`coding_provider_not_configured:claude-code`**: `CODING_CLAUDE_WORKER_IMAGE`
-  or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set. Claude Code needs both, and
-  even an agent's own `workerImageRef` doesn't replace the tool runner.
+  or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set. Claude Code needs both, even
+  for an agent with its own `workerImageRef`.
 
 This error is about images, not API keys. A missing or invalid model API key
 fails later, when the run calls the model.

package/help/errors/database-auth-invalid.md

@@ -0,0 +1,28 @@
+---
+id: errors/database-auth-invalid
+title: Database authentication is misconfigured
+summary: DATABASE_AUTH or the database URL does not meet the rules for the chosen authentication mode, so the process refused to start.
+audience: operator
+tags: [error, database, rds, iam, deploy, database_auth_invalid, rds-iam]
+appliesTo: ">=0.5.4"
+---
+
+# Database authentication is misconfigured
+
+`database_auth_invalid` means `DATABASE_AUTH` is not valid, or `DATABASE_AUTH=rds-iam` is set and `DATABASE_URL` (or `DBOS_SYSTEM_DATABASE_URL`) does not meet its rules. Wardby checks this when the process starts, so every `wardby` command fails with it, not only the server. The message names the problem; it never includes the URL, credentials, or parameter values.
+
+`DATABASE_AUTH` is `password` (the default; the password is in `DATABASE_URL`) or `rds-iam` (Amazon RDS IAM database authentication, where the password is a short-lived token signed with the workload's AWS credentials). Any other value is refused.
+
+Under `rds-iam` check each of these:
+
+1. `DATABASE_URL` starts with `postgresql://` or `postgres://`, has a user, and has no password.
+2. `AWS_REGION` or `DATABASE_AWS_REGION` is set (`DATABASE_AWS_REGION` wins).
+3. The URL has `sslmode=verify-full` and `sslrootcert=<path to the RDS CA bundle>`, and that file exists and is readable in the container. An unreadable file is reported with its error code, such as `ENOENT` for a missing file or `EACCES` for one the process cannot read.
+4. Only supported parameters are present: `sslmode`, `sslrootcert`, `application_name`, `fallback_application_name`, `options`, `client_encoding`, `statement_timeout`, `lock_timeout`, `idle_in_transaction_session_timeout`, `query_timeout`, `connection_limit`, `pool_timeout`, `connect_timeout`, `schema`. Anything else (`sslcert`, `sslkey`, `ssl`, `host`, `pgbouncer`, ...) is refused by name; remove it.
+5. User and database names in the URL are correctly percent-encoded.
+
+If the code is not raised but connections are rejected, the configuration is valid and the problem is on the AWS side: the workload's IAM role needs `rds-db:connect` for the database user, and that user needs the `rds_iam` role in the database.
+
+`prisma migrate deploy` and `dbos schema` take a URL and do not follow `DATABASE_AUTH`. Mint a short-lived URL with the migration image's helper: `DATABASE_URL="$(node scripts/rds-iam-url.mjs)" && export DATABASE_URL && npm run prisma:migrate && npm run dbos:migrate`. It reports the same `database_auth_invalid` errors for the checks it shares. `wardby quickstart` does not support `rds-iam`.
+
+See [Database authentication](../../docs/security-deployment.md#database-authentication).

package/help/errors/github-account-not-allowed.md

@@ -0,0 +1,25 @@
+---
+id: errors/github-account-not-allowed
+title: The repository's GitHub account is not served by this server
+summary: The repository belongs to a GitHub user or organization that is neither the GitHub App's owner nor listed in WARDBY_GITHUB_ALLOWED_ACCOUNTS, so wardby refuses to link or use it.
+audience: operator
+tags: [error, github, repositories, configuration, WARDBY_GITHUB_ALLOWED_ACCOUNTS, link_repository]
+appliesTo: ">=0.6.0"
+---
+
+# The repository's GitHub account is not served by this server
+
+`github_account_not_allowed` means the repository's owner is not one of the
+accounts this server serves through its GitHub App: the App's owner and the
+accounts in `WARDBY_GITHUB_ALLOWED_ACCOUNTS`. `link_repository` and coding
+profiles refuse such a repository, even with `adminOverride`, and runs on an
+existing link to it are refused.
+
+## What to do
+
+- **The repository should be served:** an operator adds its owner's login to
+  `WARDBY_GITHUB_ALLOWED_ACCOUNTS` and restarts the server, then links it again.
+- **It should not:** use a repository owned by a served account, or another
+  wardby server with its own GitHub App.
+
+Related: [Connect GitHub repositories](../github.md).

package/help/errors/low-power-disabled.md

@@ -0,0 +1,29 @@
+---
+id: errors/low-power-disabled
+title: Scale-down refused, mode not enabled
+summary: A request to put the coding proxy or native gateway to sleep was refused because WARDBY_LOW_POWER is not 1 on this deployment.
+audience: operator
+tags: [error, gke, kubernetes, low_power_disabled]
+appliesTo: ">=0.6.0"
+---
+
+# Sleep refused: low-power mode not enabled
+
+`low_power_disabled` (HTTP 409) means `power_sleep` was called, but low-power
+mode is not on for this deployment: `WARDBY_LOW_POWER` is not `1` on the
+control plane, or the control plane does not use `JOB_LAUNCHER=kubernetes` (it
+then logs `low_power_ignored` at start-up). Nothing was scaled.
+
+With the mode off, the coding proxy and native gateway always run, so there is
+nothing to put to sleep. `power_status` returns `{ "enabled": false }` in the
+same case.
+
+To turn the mode on:
+
+1. Deploy with the flag: `WARDBY_HOSTNAME=wardby.example.com WARDBY_LOW_POWER=1 deploy/gke/up.sh`.
+   On a local kind cluster, use `WARDBY_LOW_POWER=1 deploy/kind-coding/up.sh` and
+   also set `WARDBY_LOW_POWER=1` in the environment of `wardby serve`.
+2. Check that the control plane runs with `JOB_LAUNCHER=kubernetes`.
+3. Call `power_status`; it reports `"enabled": true` once the mode is on.
+
+See [Low-power mode on GKE](../low-power-mode.md).

package/help/errors/low-power-scale-forbidden.md

@@ -0,0 +1,35 @@
+---
+id: errors/low-power-scale-forbidden
+title: Scaling forbidden by RBAC
+summary: In low-power mode, the control plane is not allowed to read or scale the coding proxy or native gateway Deployment, or read its Endpoints, because the wardby-power Role is missing or out of date.
+audience: operator
+tags: [error, low-power, gke, kubernetes, rbac, low_power_scale_forbidden]
+appliesTo: ">=0.6.0"
+---
+
+# Low-power scale forbidden
+
+`low_power_scale_forbidden` means the Kubernetes API refused the control plane
+something low-power mode needs: reading or scaling the coding proxy or native
+gateway Deployment, or reading its Endpoints to see whether a woken target is
+ready. The message names the action and the object, for example
+`may not get Endpoints "wardby-native-gateway"`. It can come from a run waking a
+target, from `power_status`, or from `power_sleep`.
+
+Low-power mode needs the Role `wardby-power` (and its RoleBinding) in the
+namespace. It grants `get` and `patch` on the two Deployments and `get` on
+their Endpoints, by name. At start-up the control plane warns
+`low_power_scale_forbidden: missing ...` naming each missing permission (for
+example `get endpoints/wardby-native-gateway`); if the check itself fails it
+logs `low_power_access_check_failed`.
+
+1. Re-run the deploy with the mode on: `WARDBY_LOW_POWER=1 deploy/gke/up.sh`
+   (on kind, `WARDBY_LOW_POWER=1 deploy/kind-coding/up.sh`). It applies the
+   current Role, including the Endpoints rule an older Role may lack.
+2. Confirm: `kubectl -n wardby-coding describe role wardby-power` lists both
+   rules, and `kubectl -n wardby-coding get rolebinding wardby-power` exists.
+3. If you meant to turn the mode off, unset `WARDBY_LOW_POWER` on the control
+   plane too, then re-run `up.sh` without it.
+4. Trigger the run again.
+
+See [Low-power mode on GKE](../low-power-mode.md).

package/help/errors/low-power-wake-timeout.md

@@ -0,0 +1,30 @@
+---
+id: errors/low-power-wake-timeout
+title: Wake timed out (scale to zero)
+summary: When scaling from zero, the coding proxy or native gateway did not become ready after being scaled up, or its Deployment does not exist.
+audience: operator
+tags: [error, low-power, gke, kubernetes, scale-to-zero, low_power_wake_timeout]
+appliesTo: ">=0.6.0"
+---
+
+# Low-power wake timed out
+
+`low_power_wake_timeout` means a run needed the coding proxy (or, for a sandbox
+run, the native gateway), Wardby scaled it from 0 to 1, and no ready endpoint
+appeared within the bound. The bound is 5 minutes, or
+`KUBERNETES_READY_TIMEOUT_MS` for the proxy and
+`NATIVE_SANDBOX_READY_TIMEOUT_MS` for the gateway when that is higher. It is
+also raised when the target Deployment does not exist.
+
+1. Check the Deployment exists: `kubectl -n wardby-coding get deploy wardby-coding-proxy wardby-native-gateway`
+   (names follow `KUBERNETES_PROXY_SERVICE` and `NATIVE_GATEWAY_SERVICE`). If
+   one is missing, re-run `deploy/gke/up.sh`.
+2. If it exists, look at why its Pod is not ready: `kubectl -n wardby-coding describe pod -l app.kubernetes.io/name=wardby-coding-proxy`.
+   A cold Autopilot node can take 1 to 2 minutes; unschedulable Pods, image
+   pull errors or a failing sidecar are the usual causes.
+3. If the node is simply slow, raise the timeout for that target above 5
+   minutes (300000): set `KUBERNETES_READY_TIMEOUT_MS` (proxy) or
+   `NATIVE_SANDBOX_READY_TIMEOUT_MS` (gateway) on the control-plane Deployment.
+4. Trigger the run again.
+
+See [Low-power mode on GKE](../low-power-mode.md).

package/help/errors/mobile-disabled.md

@@ -0,0 +1,31 @@
+---
+id: errors/mobile-disabled
+title: Mobile sign-in is not enabled
+summary: The server refused the mobile app's sign-in or registration because WARDBY_MOBILE_ENABLED is not true.
+audience: operator
+tags: [error, mobile, sign-in, oauth, mobile_disabled, WARDBY_MOBILE_ENABLED]
+appliesTo: ">=0.6.0"
+---
+
+# Mobile sign-in is not enabled
+
+Mobile sign-in is switched off. An operator turns it on with
+`WARDBY_MOBILE_ENABLED`.
+
+Only client registration returns the reason: `400 invalid_redirect_uri` with the
+description `mobile_disabled: mobile sign-in is not enabled on this server
+(WARDBY_MOBILE_ENABLED)`. Sign-in (authorize) and token refresh return the
+generic `invalid_request` or `invalid_grant` with an `id`. The `mobile_disabled`
+reason appears only in the control-plane log line "self-hosted OAuth request
+rejected" for that `id`, so look the `id` up in the control-plane logs.
+
+1. Set `WARDBY_MOBILE_ENABLED=true` on the control plane and restart it. On GKE,
+   redeploy with `WARDBY_MOBILE_ENABLED=true` passed to `deploy/gke/up.sh`; a
+   run without it turns mobile sign-in off again.
+2. If you use a white-label build, check that `WARDBY_MOBILE_REDIRECT_URI`
+   matches the redirect URI the app uses.
+3. Sign in again from the app.
+
+With an external identity provider this error does not come from Wardby; check
+that the IdP client lists the mobile redirect URI. See
+[Use the wardby mobile app](../mobile-app.md).

package/help/errors/native-sandbox-capacity.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-capacity
+title: Native sandbox is at capacity
+summary: A sandbox run could not start because the concurrent sandbox run limit or the namespace ResourceQuota has no room; the run failed at start and was not queued.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, capacity, quota, native_sandbox_capacity]
+appliesTo: ">=0.5.4"
+---
+
+# Native sandbox is at capacity
+
+`native_sandbox_capacity` means a sandbox-mode run could not start because there was no room for it. The run failed at start; it is not queued. The message gives one of two reasons:
+
+- **"N sandbox runs are already active (NATIVE_SANDBOX_MAX_CONCURRENT)"**: the cap on concurrent sandbox runs, counted across all server replicas as active gateway sessions, has been reached.
+- **"the namespace's ResourceQuota has no room for another native worker pod"**: with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the run namespace's quota on pods, CPU, or memory is full.
+
+1. Wait for running sandbox runs to finish, then trigger the run again.
+2. To allow more at once, raise `NATIVE_SANDBOX_MAX_CONCURRENT` (unset means no cap) and raise the namespace ResourceQuota with it. Each worker pod needs its CPU and memory limits (`NATIVE_SANDBOX_CPUS`, `NATIVE_SANDBOX_MEMORY_MB`) from the quota, which coding runs and the gateway share. Idle warm-pool workers (`NATIVE_SANDBOX_WARM_POOL_SIZE`) take quota too, so leave room for `NATIVE_SANDBOX_MAX_CONCURRENT` plus the pool size.
+3. Check current usage with `kubectl describe resourcequota -n <namespace>` and `kubectl get pods -n <namespace> -l wardby.io/component=native-run`.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-deadline-exceeded.md

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-deadline-exceeded
+title: Native run deadline exceeded
+summary: A sandbox run passed its 60-minute maximum lifetime and its worker was stopped.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_deadline_exceeded]
+appliesTo: ">=0.5.4"
+---
+
+# Native run deadline exceeded
+
+`native_sandbox_deadline_exceeded` means the run was still going when it reached the sandbox's maximum lifetime of 60 minutes, so the worker was stopped and the run failed. The limit protects against stuck runs and is not configurable.
+
+1. Look for a tool that waits forever or a loop that does not converge.
+2. Split long work into smaller runs, or delegate parts to sub-agents (each is its own run).
+3. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-docker-failed.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-docker-failed
+title: Native worker Docker command failed
+summary: A Docker command Wardby ran to start or clean up a sandbox worker failed.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_docker_failed]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker Docker command failed
+
+`native_sandbox_docker_failed` means a Docker command needed to launch a worker (pull the image, create the run network, join the gateway to it, or start the container) failed. The message names the step and includes Docker's error output.
+
+1. Confirm the server can reach the Docker daemon (`docker info` as the server's user).
+2. For an image step, confirm the image exists on the host (a local id must already be present; a digest must be pullable without registry credentials, or pull it beforehand).
+3. For a network step, confirm `NATIVE_GATEWAY_CONTAINER` names a running gateway container on this Docker host.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-gateway-unavailable.md

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-gateway-unavailable
+title: Native gateway Service unavailable
+summary: On Kubernetes, Wardby could not find a usable native gateway Service, so a sandbox run could not start.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_gateway_unavailable]
+appliesTo: ">=0.5.4"
+---
+
+# Native gateway Service unavailable
+
+`native_sandbox_gateway_unavailable` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the Service named by `NATIVE_GATEWAY_SERVICE` (default `wardby-native-gateway`) does not exist in the sandbox namespace or has no ClusterIP. Workers dial the Service's ClusterIP, so Wardby needs one.
+
+1. Confirm the namespace: `NATIVE_SANDBOX_NAMESPACE`, else `KUBERNETES_NAMESPACE`, else `wardby-coding`.
+2. Create the Service there as a regular ClusterIP Service (not headless) that selects the gateway pods (`app.kubernetes.io/name: wardby-native-gateway`) and exposes both 8790 and the deny port 8791.
+3. Confirm the server's Role allows `get` on `services` in that namespace.
+4. Alternatively set `NATIVE_GATEWAY_URL` to an address workers can dial, and keep the gateway's NetworkPolicy and the workers' egress consistent with it.
+5. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-image-not-pinned.md

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-image-not-pinned
+title: Native worker image not pinned
+summary: NATIVE_SANDBOX_WORKER_IMAGE is a mutable tag, so Wardby refused to launch a sandbox worker.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_image_not_pinned]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker image not pinned
+
+`native_sandbox_image_not_pinned` means `NATIVE_SANDBOX_WORKER_IMAGE` is not immutable. Wardby only launches a worker from a digest (`repo@sha256:...`) or a local image id, so the code it isolates cannot change underneath it.
+
+1. Use the digest-pinned reference listed as `nativeWorker` in `dist/quickstart-images.json` for your version, or build locally with `npm run native-worker:image:local` and use the image id from `docker image inspect --format '{{.Id}}' wardby-native-worker:local`.
+2. On Kubernetes (`NATIVE_SANDBOX_LAUNCHER=kubernetes`) a local image id is not accepted: the image must be a registry digest, `repo@sha256:...`, that the cluster can pull. Push your build to a registry and use its digest.
+3. Set it as `NATIVE_SANDBOX_WORKER_IMAGE`, restart the server, and trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-isolation-mismatch.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-isolation-mismatch
+title: Native worker pod differs from what Wardby built
+summary: On Kubernetes, the sandbox pod or its NetworkPolicy as stored by the cluster differs from what Wardby created, so the run failed before starting.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_isolation_mismatch]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker pod differs from what Wardby built
+
+`native_sandbox_isolation_mismatch` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, Wardby read back the worker pod and NetworkPolicy it had just created and found a security-relevant difference: a service-account token, host networking, a different runtime class, priority class, image, container resources, or container security context or environment, an extra init container, or a changed NetworkPolicy. Something in the cluster modified the objects after creation, typically a mutating admission webhook, policy engine, or service mesh injector. The run is failed and the pod removed.
+
+1. Inspect an equivalent pod while a run is starting: `kubectl get pods -n <namespace> -l wardby.io/component=native-run -o yaml`.
+2. Find the admission controller that changes it (`kubectl get mutatingwebhookconfigurations`) and exempt pods labeled `wardby.io/component: native-run` and the run namespace's NetworkPolicies, for example by namespace or label selector. Do not disable sidecar-style injection by editing the pod after the fact.
+3. If `NATIVE_SANDBOX_RUNTIME_CLASS` or `NATIVE_SANDBOX_PRIORITY_CLASS` is set, confirm no policy overrides it. On GKE Autopilot set `KUBERNETES_PLATFORM=gke-autopilot` so pod resources are already in the form Autopilot admits and are not rewritten.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).