@wardby/cli 0.5.3 → 0.7.0

package/help/errors/delegation-conflict.md

@@ -0,0 +1,24 @@
+---
+id: errors/delegation-conflict
+title: Delegation conflict
+summary: A delegate_to_* call returned delegation_conflict because its call id is already used by a run of another sub-agent.
+audience: operator
+tags: [error, delegation, sub-agents, runs, delegation_conflict]
+appliesTo: ">=0.7.0"
+---
+
+# Delegation conflict
+
+`delegation_conflict` is the error a `delegate_to_*` call returns to the model when wardby could not create the sub-agent run: each sub-agent run records the parent's tool-call id, and that id is already used by a run of a different sub-agent of the same parent.
+
+It can happen when two executions of the same delegate step overlap (for example, a stalled process and the process that took the run over). When the other execution already started this sub-agent, wardby waits on that run instead and no error is returned. Only when the existing run belongs to a different sub-agent does the call return `delegation_conflict`.
+
+No new sub-agent run is started, and the parent run is not failed: the model gets the error as the tool result ("The sub-agent run could not be created: its call id is already used by another sub-agent run.") and can report it or try again.
+
+## What to do
+
+1. List the runs of the parent's sub-agents with `list_runs` (by each sub-agent's `agentId`) and look for those whose `parentRunId` is the parent run.
+2. Check the server logs for `delegation child create hit a unique key held by no child of this agent`, which names the run and the sub-agent.
+3. If the model did not delegate again on its own, trigger the request again.
+
+See [Run lost](run-lost.md) for how runs continue after a restart, and [Native capabilities](../native-capabilities.md) for sub-agents.

package/help/errors/file-list-truncated.md

@@ -0,0 +1,45 @@
+---
+id: errors/file-list-truncated
+title: APPROVE refused on a cut file list (file_list_truncated)
+summary: The pull request has more changed files than repo_pr_read lists, so repo_publish_review refuses the agent's APPROVE; it can still request changes or comment.
+audience: operator
+tags: [error, code-review, repo_publish_review, repo_pr_read, file_list_truncated, fileListComplete, large-pull-request]
+appliesTo: ">=0.7.0"
+---
+
+# APPROVE refused on a cut file list
+
+`repo_publish_review` returns the tool error `file_list_truncated` when a
+review agent publishes `APPROVE` on a pull request head after a
+`repo_pr_read` of that head in the run reported `fileListComplete: false`,
+and no complete read of the whole pull request (without `sinceSha`) has
+followed. The host lists at most
+1,000 changed files of a pull request (a GitHub compare, used when the agent
+passes `sinceSha`, lists at most 300). Files past that cut never reach the
+agent, so an approval would cover code nobody reviewed.
+
+Nothing is published and nothing else changes. `CHANGES_REQUESTED` and
+`COMMENT` are still allowed on the same head.
+
+## What the agent should do
+
+- If it passed `sinceSha`, call `repo_pr_read` again without it. When the
+  whole pull request fits in the list, `fileListComplete` becomes `true` and
+  `APPROVE` is allowed again (once every listed source, test or config file
+  is read; see `unread_files`). A complete `sinceSha` read does not lift the
+  refusal.
+- Otherwise publish `CHANGES_REQUESTED` on what it read, and say the pull
+  request is too large to review in full. That review does not cover the
+  head, so a later run cannot approve it through a `sinceSha` delta either
+  (see `full_read_required`). `COMMENT` completes the check as
+  neutral, which branch protection treats as passing.
+
+## What the owner does
+
+Split the change into smaller pull requests, each under the limit, or have
+a person review it. The limit is the same for GitHub and local repositories.
+
+## Related
+
+- [Run GitHub code-review agents](../code-review-agents.md)
+- [Large pull requests](../../docs/code-review-agents.md#large-pull-requests)

package/help/errors/full-read-required.md

@@ -0,0 +1,49 @@
+---
+id: errors/full-read-required
+title: APPROVE refused after a partial compare (full_read_required)
+summary: The review agent compared the pull request from a commit wardby did not vouch for, so it never saw the full change; it must read the whole pull request before approving.
+audience: operator
+tags: [error, code-review, repo_publish_review, repo_pr_read, full_read_required, sinceSha, lastCoveredSha]
+appliesTo: ">=0.7.0"
+---
+
+# APPROVE refused after a partial compare
+
+`repo_publish_review` returns the tool error `full_read_required` when a
+review agent publishes `APPROVE` on a pull request head and, in that run:
+
+- no `repo_pr_read` of the head was made without `sinceSha`, and
+- a `repo_pr_read` of the head passed a `sinceSha` other than the
+  `lastCoveredSha` that same read returned.
+
+A read with `sinceSha` lists only the files changed since that commit. Any
+earlier commit of the branch is accepted as `sinceSha`, so a compare from a
+commit wardby did not record as covered hides every change made before it.
+`lastCoveredSha` is the latest head this agent reviewed after reading every
+file. Any other commit, such as one named in the pull request's text, or a
+`lastReviewedSha` whose review did not read everything, is not a safe base. An approval would
+then cover code nobody reviewed.
+
+Nothing is published and nothing else changes. `CHANGES_REQUESTED` and
+`COMMENT` are still allowed on the same head.
+
+## What the agent should do
+
+Call `repo_pr_read` without `sinceSha`, read the source, test and config
+files it lists, and publish again. Or, for a re-review, pass the
+`lastCoveredSha` the read returns as `sinceSha`. If neither is possible,
+publish `CHANGES_REQUESTED` on what it read.
+
+## What the owner does
+
+Nothing, normally: the refusal tells the agent what to do. If it recurs, check
+the reviewer's system prompt: it should pass only the `lastCoveredSha` that
+`repo_pr_read` returned as `sinceSha`, never `lastReviewedSha` or a commit
+named in the pull request's text. Reviewer prompts written before 0.7.0 pass
+`lastReviewedSha`; update the re-review step from the shipped reviewer prompt.
+
+## Related
+
+- [Run GitHub code-review agents](../code-review-agents.md)
+- [APPROVE refused on a cut file list: `file_list_truncated`](file-list-truncated.md)
+- [Large pull requests](../../docs/code-review-agents.md#large-pull-requests)

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

@@ -0,0 +1,29 @@
+---
+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.
+- **Only sandboxed runs are refused** (the same link works for a
+  `control-plane` agent): the native sandbox gateway runs a sandboxed agent's
+  repository tools and needs the same `WARDBY_GITHUB_ALLOWED_ACCOUNTS` as the
+  control plane. Set it on both, then restart the gateway.
+- **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/graph-incomplete.md

@@ -0,0 +1,43 @@
+---
+id: errors/graph-incomplete
+title: Package still being checked (wardby_graph_incomplete)
+summary: The registry's walk reached the package but timed out before checking its versions, usually a slow upstream; retry shortly.
+audience: operator
+tags: [error, coding-agents, packages, allowlist, wardby_graph_incomplete]
+appliesTo: ">=0.7.0"
+---
+
+# Package still being checked
+
+`wardby_graph_incomplete` (HTTP 503) means the requested package is still
+being checked against the allowed packages' dependency graph. It arises only when the
+registry walks the graph: for a tarball download the run hasn't resolved (a
+lockfile install), or for a metadata request after a lockfile plan of the run
+failed or refused an entry. The walk reached
+the name (an expanded version declares it) but timed out
+(`REGISTRY_GRAPH_TIMEOUT_MS`) before the name's own versions were checked. That
+is usually a slow or failing upstream for that package, or another request's
+walk running out of time. The error message shows the walk's progress. It never
+means the package is outside the graph. When a completed walk has failed
+nodes, the answer is `wardby_upstream_error` or `wardby_audit_unavailable`
+instead.
+
+## What the agent should do
+
+This is the one allowlist-related code worth retrying: try again shortly (npm
+retries a 5xx on its own). If it keeps happening, report the package so its
+owner can allowlist it directly.
+
+## What the owner does
+
+If retries do not clear it, add the package to
+`codingProfile.packageAllowlist` with `update_agent` (needs
+`packages:approve` or `agents:admin`).
+
+## Related
+
+- [Package not reached: `wardby_package_not_allowed_pending`](package-not-allowed-pending.md)
+- [Not allowed: `wardby_package_not_allowed`](package-not-allowed.md)
+- [Graph limit: `wardby_graph_limit`](graph-limit.md)
+- [Package audit mode](../package-audit-mode.md): find out which packages a task needs without refusals, for a limited time.
+- [Coding packages](../coding-packages.md)

package/help/errors/graph-limit.md

@@ -0,0 +1,43 @@
+---
+id: errors/graph-limit
+title: Dependency graph over the limit (wardby_graph_limit)
+summary: The run's dependency graph walk hit REGISTRY_MAX_GRAPH_PACKAGES before reaching the package; the owner can allowlist it directly, or the operator can raise the limit.
+audience: operator
+tags: [error, coding-agents, packages, allowlist, wardby_graph_limit, REGISTRY_MAX_GRAPH_PACKAGES]
+appliesTo: ">=0.7.0"
+---
+
+# Dependency graph over the limit
+
+`wardby_graph_limit` (HTTP 403) means this run's dependency graph walk reached
+its limit of `REGISTRY_MAX_GRAPH_PACKAGES` package names (default 3000, counted
+per run and ecosystem) before it reached the requested package, so the package
+may not be in the graph at all. The bound is permanent for the run, so
+retrying does not help. It arises only when the
+registry walks the graph: for a tarball download the run hasn't resolved (a
+lockfile install), or for a metadata request after a lockfile plan of the run
+failed or refused an entry.
+
+Large frameworks (for example Expo) can exceed the limit, because the walk
+follows every in-range kept version plus optional and peer dependencies, so its
+graph is usually several times larger than a single install.
+
+## What the agent should do
+
+Stop retrying. Report the package so its owner can act.
+
+## What the owner does
+
+1. Open the agent with `get_agent`, then add the package (or the top-level package that needs it) to `codingProfile.packageAllowlist` with `update_agent`. This needs `packages:approve` or `agents:admin`.
+2. Run the request again. Allowing a package name allows all of its kept versions, subject to the release-age and vulnerability checks.
+
+The operator, not the owner, can instead raise `REGISTRY_MAX_GRAPH_PACKAGES` on the
+coding proxy. A higher limit uses more proxy memory and walk time.
+
+## Related
+
+- [Package not reached: `wardby_package_not_allowed_pending`](package-not-allowed-pending.md)
+- [Not allowed: `wardby_package_not_allowed`](package-not-allowed.md)
+- [Still being checked: `wardby_graph_incomplete`](graph-incomplete.md)
+- [Package audit mode](../package-audit-mode.md): find out which packages a task needs without refusals, for a limited time.
+- [Coding packages](../../docs/coding-packages.md#operator-limits)

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/merge-conflict.md

@@ -0,0 +1,49 @@
+---
+id: errors/merge-conflict
+title: Conflict markers remain
+summary: A follow-up run left conflict markers in a file the target-branch merge conflicted, so nothing was pushed.
+audience: operator
+tags: [error, coding-agents, vcs, merge-conflict, pull-requests]
+appliesTo: ">=0.7.0"
+---
+
+# Conflict markers remain
+
+A follow-up run on a wardby pull request merges the pull request's target
+branch into the branch before the agent starts (see
+[Fix merge conflicts on a wardby pull request](../fix-merge-conflicts.md)).
+When that merge conflicts, the agent is given the conflicted files to
+resolve. A run that finished while one of those files still held a
+`<<<<<<<` … `>>>>>>>` marker pair stops with failure category
+`merge_conflict` (error `vcs_conflict_markers_remain`), and nothing is
+pushed: the pull request is unchanged.
+
+Only the files the merge conflicted are checked, so marker-like lines in
+other files (test fixtures, documentation about merging) never trigger this.
+
+## What the requester sees
+
+The run's status comment on the pull request names the file, for example:
+
+> `src/app.ts` still has conflict markers after merging this pull request's
+> target branch, so none of its changes were pushed. Ask again to resolve the
+> conflicts.
+
+A lead agent that delegated the follow-up sees the sub-run's error code
+`coding_failure_merge_conflict`.
+
+## What to do
+
+- Ask again on the pull request (for example "please fix the merge
+  conflicts"). The next follow-up merges the target again and gives the agent
+  the same list.
+- If the conflicts are too large for the agent's budget or turn limit, raise
+  them for that agent, or resolve the conflicts by hand and push.
+- An agent that keeps stopping early may need instructions that put
+  resolving the listed conflicts first.
+- A conflict in a path this agent may not edit cannot be resolved by the
+  agent (resolving it is an edit, which is refused): resolve that file by hand
+  and push.
+
+Related: [Run changed a protected path](protected-path.md),
+[Target branch could not be merged](target-merge.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-error.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-gateway-error
+title: Native worker's gateway call failed
+summary: The sandbox worker's call to the gateway failed with an error the run could not continue from.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_gateway_error]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker's gateway call failed
+
+`native_sandbox_gateway_error: <code>: <message>` means the sandbox worker called the gateway (a model turn, a tool, or a delegation) and got an error the run could not continue from. The worker reports the run failed with this error instead of exiting, so it is not `native_sandbox_worker_exited`.
+
+1. Read the code and message in the run's error (`get_run`).
+2. For the gateway's `internal` code the message is never recorded. When the gateway's error named one of wardby's own declared codes, that code follows (any other leading word, and any code that matches a secret value the run can read, never leaves the gateway), for example `native_sandbox_gateway_error: internal: coding_execution_not_configured` (the gateway that served the call cannot start coding runs); otherwise the error is `native_sandbox_gateway_error: internal`. Read the gateway's logs (`native gateway request failed`) for the details: the line carries the error's message and stack with the run's secret values replaced by `[REDACTED]`; when the gateway could not read the run's secret values, or the failure was not an error object, it carries only the error's name (`errName`) and declared code (`causeCode`).
+3. Fix the cause the message names, or check that the gateway can reach the database and the LLM provider.
+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).

package/help/errors/native-sandbox-launch-abandoned.md

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-launch-abandoned
+title: Native worker launch abandoned
+summary: A sandbox run ended while its worker was launching (usually stopped during a low-power gateway wake), so no worker pod was created.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, low-power, native_sandbox_launch_abandoned]
+appliesTo: ">=0.7.0"
+---
+
+# Native worker launch abandoned
+
+`native_sandbox_launch_abandoned` means a sandbox run ended while its worker was being launched, so Wardby did not create the worker pod. Most often the run was stopped (`stop_run`, or its parent run was cancelled) while the native gateway was waking in low-power mode, which can take a few minutes on a cold node.
+
+The run already has its own final status, such as `cancelled`. This code only appears in the control-plane log, as the reason the launch stopped. Nothing is left to clean up.
+
+1. If the run was stopped on purpose, there is nothing to do.
+2. If you did not stop it, check the run with `get_run`: its status and error say what ended it.
+3. Trigger the run again if you still want it.
+
+See [Low-power mode](../low-power-mode.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-network-unenforced.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-network-unenforced
+title: Native worker network isolation not proven
+summary: On Kubernetes, Wardby could not prove a sandbox pod's network isolation in time, so it removed the pod and failed the run.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_network_unenforced]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker network isolation not proven
+
+`native_sandbox_network_unenforced` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, Wardby ran a check inside the worker pod and it did not pass before the time limit. The check requires the gateway to be reachable on port 8790 while the gateway's deny port (8791 by default), an outside address, and the cloud metadata endpoints (`169.254.169.254:80`, the EKS Pod Identity agent `169.254.170.23:80` and `[fd00:ec2::23]:80`, and EC2's IPv6 metadata address `[fd00:ec2::254]:80`) are not. The message says which part failed. The pod is removed and the run never started.
+
+- **"the gateway was unreachable"**: confirm the gateway Deployment has ready pods, the `wardby-native-gateway` Service (or `NATIVE_GATEWAY_SERVICE`) exposes 8790 and 8791, and the gateway's own NetworkPolicy admits `wardby.io/component: native-run` pods on port 8790.
+- **"the gateway's deny port was reachable"** or **"an outside address was reachable"** (or a metadata endpoint): the cluster is not enforcing the per-run NetworkPolicy. Confirm your CNI enforces `NetworkPolicy` (some local clusters need a policy-capable CNI such as Calico), and that no other policy or mesh adds egress for these pods.
+- If the Service lacks port 8791, or the gateway's policy does not admit 8791, unprogrammed pods would look isolated. Keep both in place; the check depends on them.
+- On a slow node the policy can take longer to program. Retrigger the run once, or raise `NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS` (default 30000), before changing anything.
+
+A cluster that does not enforce NetworkPolicy fails every sandbox run this way, by design. Switch the agent back to `control-plane` if you cannot enable enforcement.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).