@wardby/cli 0.7.0 → 0.8.0

package/help/agent-recipes.md

@@ -162,8 +162,8 @@ yourself.`
 A router delegates once per run by default. For one native agent that splits a
 request across several repositories, attach one builder per repository and set
 the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
-`update_agent`. Each `delegate_to_<name>` call must go to a different
-sub-agent; the calls run one after another unless you also set
+`update_agent`. A run delegates to each sub-agent and repository at most
+once; the calls run one after another unless you also set
 `parallelDelegations: true`, which starts only the **consecutive**
 `delegate_to_*` calls of one turn together — a non-delegation call between
 two delegations splits them, nothing is reordered, and results return to the
@@ -208,6 +208,37 @@ pull request in it also gets a `wardby merge order` check run showing
 whether its earlier steps have merged yet; search help for "merge order
 check" for its states and for requiring it in branch protection.
 
+**One coding agent across several repositories.** Instead of one builder per
+repository, give one coding builder a list: its default in
+`codingProfile.repository`, and each other repository with `link_repository`
+(`access: "write"`, no triggers). The lead then names the repository on each
+call, and may delegate to the same builder once per repository:
+
+```json
+{ "task": "Add the /quotes endpoint the client will call.", "repository": "your-org/api", "mergeOrder": 1 }
+```
+
+```json
+{ "task": "Add the quotes page that calls /quotes.", "repository": "your-org/web", "mergeOrder": 2 }
+```
+
+Set `maxDelegationsPerRun` (up to 20) for the number of calls, and use
+`mergeOrder` where the pull requests must land in order. A call without
+`repository` is refused with `repository_required` (unless it continues a prior
+run with `continuePriorRun`), and a repository not on the list with
+`repository_not_listed`. A native sub-agent refuses `repository` with
+`repository_requires_coding_agent`. The lead sees the list in the tool
+definition only when it has the same owner as the builder, or another owner
+with execute access to a builder that sets `allowWebhookTaskOverride`. All
+repositories share the builder's toolchain, budget and prompt.
+
+Being on the list lets a run work in a repository; it starts nothing there. Link
+the lead and the reviewer on each listed GitHub repository with the triggers
+they need, or a pull request opened there gets no review, mention follow-up, fix
+round or mark-ready.
+
+Search help for `repository_required` or `repository_not_listed` for what to do about those refusals.
+
 ## Step 3: confirm
 
 Summarize what you created: each agent's name and id, the sub-agent bindings,

package/help/brokered-secrets.md

@@ -67,6 +67,9 @@ alone never removes it. Every change is audited.
 
 ## Related
 
+- [Host providers](../docs/host-providers.md): a provider's credentials must be brokered
+  secrets
+- [Remote MCP servers](../docs/mcp-servers.md) (0.8.0+): a server's credentials are brokered secrets
 - Full guide: [`docs/tool-secrets.md`](../docs/tool-secrets.md)
 - [Use native agents, tools, and data](native-capabilities.md)
 - Errors: [`secret_brokered`](errors/secret-brokered.md),

package/help/build-claude-code-image.md

@@ -4,7 +4,7 @@ title: Build a tool runner image for a Claude Code agent
 summary: A procedure an MCP assistant follows to build a custom image for a Claude Code coding agent (Ruby, Go, Java or another language) FROM the release's tool runner image, check it, and set it with workerImageRef.
 audience: operator
 tags: [claude-code, custom-image, workerImageRef, tool-runner, worker-image, other-language, ruby, toolchain]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Build a tool runner image for a Claude Code agent

package/help/claude-code-run-pane.md

@@ -0,0 +1,40 @@
+---
+id: claude-code-run-pane
+title: See your runs in Claude Code (the wardby-runs plugin)
+summary: Install the wardby-runs Claude Code plugin to see your runs beside the chat, grouped by pull request, with run details and Continue locally.
+audience: operator
+tags: [claude code, plugin, wardby-runs, pane, claude-plugin, runs, desktop, auto mode, permissions]
+appliesTo: ">=0.8.0"
+---
+
+# See your runs in Claude Code
+
+The `wardby-runs` plugin opens a pane in Claude Code that lists your wardby
+runs, grouped by pull request, and shows each run's details. It uses the
+`wardby` MCP server your session already has and only reads.
+
+Install it, and allow its read-only tools for auto mode, with:
+
+```sh
+npx @wardby/cli@latest claude-plugin install
+```
+
+Add `--server-url https://<your wardby host>/mcp` if Claude Code has no MCP
+server named `wardby` yet. Or install it yourself with
+`/plugin install wardby-runs --marketplace wardby/wardby`. Then run
+`/wardby-runs`.
+
+If the pane says auto mode refused a call, allow `mcp__wardby__list_runs`,
+`mcp__wardby__list_agents`, `mcp__wardby__get_run` and
+`mcp__wardby__get_run_transcript` in `/permissions`.
+
+In the terminal, the pane takes clicks and sits beside the chat only in Claude
+Code's fullscreen view (`"tui": "fullscreen"`); otherwise use ctrl+x tab and the
+keys it shows. The desktop app needs no setting.
+
+`wardby quickstart` offers the pane when it connects Claude Code, and
+`wardby doctor` and `wardby claude-plugin status` check the setup; `wardby claude-plugin
+uninstall` removes the plugin and the rules install added. To continue a run
+from the pane, see `resume-runs-locally`.
+
+The full guide is [Claude Code plugin](../docs/claude-code-plugin.md).

package/help/errors/coding-mcp-pins-unavailable.md

@@ -0,0 +1,35 @@
+---
+id: errors/coding-mcp-pins-unavailable
+title: A coding run failed before launch because its MCP tools could not be read
+summary: The run failed with coding_failure_mcp_pins_unavailable because wardby could not read the agent's MCP server attachments when it launched the run.
+audience: operator
+tags: [error, mcp, coding-agents, coding_failure_mcp_pins_unavailable, coding_mcp_pins_unavailable]
+appliesTo: ">=0.8.0"
+---
+
+# A coding run failed before launch because its MCP tools could not be read
+
+## What happened
+
+The run's error starts with `coding_failure_mcp_pins_unavailable`, followed by
+a diagnostic id. When wardby launches a coding run, it reads the MCP server
+tools attached to the agent and fixes them for that run. That read failed, so
+wardby failed the run rather than launch it without the tools it expected.
+Nothing was launched, so the run made no changes.
+
+The run's error contains only the code and the diagnostic id. The control
+plane log has the real cause at `warn`, under the same diagnostic id, with
+the internal code `coding_mcp_pins_unavailable`.
+
+## What to do
+
+1. Search the control plane log for the diagnostic id. The cause is usually
+   the database: a lost connection, a timeout, or a migration that has not
+   been applied.
+2. Fix the database problem, then trigger the agent again. A run that hit a
+   brief database outage usually works the next time.
+3. If it keeps happening and you don't need MCP tools on this agent, detach
+   its MCP servers with `detach_mcp_server`, or turn MCP servers off with
+   `WARDBY_MCP_SERVERS=off`. Either way, the run no longer reads them.
+
+See [Remote MCP servers for coding agents](../../docs/mcp-servers.md#coding-agents).

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Database authentication is misconfigured

package/help/errors/host-provider-error.md

@@ -0,0 +1,40 @@
+---
+id: errors/host-provider-error
+title: Host provider refused (host_provider_*)
+summary: Registering a host provider, approving its tools or rotating its secrets was refused with a host_provider_ code. Each code has one cause and one fix.
+audience: operator
+tags: [host_provider_not_found, host_provider_in_use, host_provider_webhook_secret_short, host provider, error]
+appliesTo: >=0.8.0
+---
+
+# Host provider refused
+
+Nothing was changed. The message holds a code and secret or tool names, never a value.
+
+## Registering or approving
+
+- `host_provider_not_found`: no provider has that name. Check it, or register it.
+- `host_provider_missing_operation`: a required operation has no tool. Bind it in `tools`.
+- `host_provider_operation_not_bound`: that isn't a known operation, or this provider doesn't bind it. Check the name.
+- `host_provider_tool_not_found`: you own no tool with that name. Create it, or fix the name.
+- `host_provider_tool_deleted`: the tool behind this operation was deleted, so there's nothing to approve. Bind a new one by registering again.
+- `host_provider_secret_not_found`: you own no secret with that name. Create it, or fix the name.
+- `host_provider_secret_not_brokered`: a credential isn't brokered. Broker it with `set_secret_broker`.
+- `host_provider_secret_hosts`: its broker config misses a host. Allow every API host, and the git host for a repository credential.
+- `host_provider_secret_placement`: it isn't placed in a header or query parameter. Change its placement.
+- `host_provider_permission_secret_shared`: the permission secret is also a credential, or is used by another provider. Give it its own secret.
+- `host_provider_webhook_secret_shared`: the webhook secret is also a credential or permission secret, or is attached to an agent. Give it its own secret, and detach it.
+- `host_provider_webhook_secret_short`: the webhook secret is under 16 characters. Store a longer one.
+- `host_provider_username_is_secret`: `gitUsername` equals a credential's value. Use the host's token username.
+
+## Using a provider's secrets
+
+- `host_provider_webhook_secret_attached`: `attach_secret` or `wardby import` tried to attach a webhook secret to an agent. Don't: no tool may read it.
+- `host_provider_secret_link_stale`: the browser link was requested before a provider used this secret. Request a new one with `hosts:admin`.
+- `host_provider_webhook_secret_short` also refuses a rotation to a value under 16 characters. Enter a longer one; the same link still works.
+
+## Deleting
+
+- `host_provider_in_use`: an agent links to one of its repositories. Remove those links first.
+
+See [Host providers](../host-providers.md).

package/help/errors/host-tool-failed.md

@@ -0,0 +1,36 @@
+---
+id: errors/host-tool-failed
+title: A host provider tool failed (host_tool_*, host_*)
+summary: test_host_provider reports a fixed code for each failed operation; a tool's own message is dropped on purpose, so test the tool with dry_run_tool.
+audience: operator
+tags: [host_tool_failed, host_tool_timeout, host_tool_request_denied, host_tool_no_credential, host_forbidden]
+appliesTo: >=0.8.0
+---
+
+# A host provider tool failed
+
+## What happened
+
+A tool's own text never reaches a report, a model or a comment, in case it holds something
+private. So `test_host_provider` gives a fixed code for each operation.
+
+## What to do
+
+- `host_unauthorized` or `host_forbidden`: the host refused the credential. Check the token and
+  its scopes. On the permission lookup, a repository token is often not enough.
+- `host_not_found`, `host_conflict`, `host_rate_limited` or `host_unavailable`: the host answered
+  with that state. Check the repository, pull request or ref you named, or try again later.
+- `host_tool_no_credential`: no `credentials` entry covers this repository, the secret can't be
+  decrypted, or the secret is no longer brokered or no longer allows every API host.
+- `host_tool_request_denied`: the tool left its API hosts or repository path, used the wrong
+  method, set a header other than `accept`, `content-type`, `if-match` or `if-none-match`, sent a
+  `_method` or `x-http-method*` query key, sent a path a server could read as something else (dot-only segments, encoded separators), or made
+  more than three requests. No request follows a redirect: fetch the `Location` yourself.
+- `host_tool_invalid_result` or `host_tool_invalid_params`: the tool doesn't match its
+  operation's shape.
+- `host_tool_failed`: the tool threw an error. `dry_run_tool` shows errors that don't involve the request, for example with a stubbed response. It has no `host` credential, so a tool using `secrets: ["host"]` fails there for another reason.
+- `host_tool_timeout`: it ran out of time or instructions.
+
+To fix a tool, call `update_tool`, then `approve_host_provider_tools`.
+
+See [Host providers](../host-providers.md).

package/help/errors/mcp-call-limit.md

@@ -0,0 +1,22 @@
+---
+id: errors/mcp-call-limit
+title: A coding run used up its remote tool calls (mcp_call_limit)
+summary: A Claude Code or Codex run made more remote MCP tool calls than WARDBY_MCP_MAX_CALLS_PER_RUN allows, so further calls are refused.
+audience: operator
+tags: [mcp, mcp_call_limit, WARDBY_MCP_MAX_CALLS_PER_RUN, coding agent, claude code, codex, call limit]
+appliesTo: ">=0.8.0"
+---
+
+# A coding run used up its remote tool calls
+
+## What happened
+
+A call to a remote MCP tool returned `mcp_call_limit`. Each coding run (Claude Code or Codex) may make a fixed number of remote MCP tool calls, `100` by default. Every call counts, including calls that failed or timed out. Once the run reaches the limit, further calls are refused; the agent sees the refusal as the tool's result and the run goes on.
+
+## What to do
+
+1. Check whether the agent is looping on a tool, for example retrying a call that keeps failing. Fix the cause, or tighten the agent's instructions.
+2. If the run really needs more calls, ask the operator to raise `WARDBY_MCP_MAX_CALLS_PER_RUN` on the native gateway, which counts the calls, and on the server so both agree (a positive whole number; any other value stops start-up). Restart them to apply it.
+3. Native agents are not limited by this setting.
+
+See [Remote MCP servers](../mcp-servers.md) and [Remote MCP servers for coding agents](../../docs/mcp-servers.md#coding-agents).

package/help/errors/mcp-call-timeout.md

@@ -0,0 +1,22 @@
+---
+id: errors/mcp-call-timeout
+title: A remote tool call ran out of time (mcp_call_timeout)
+summary: A remote tool call hit its callTimeoutMs or the run's deadline, or was stopped.
+audience: operator
+tags: [mcp, mcp_call_timeout, callTimeoutMs, timeout, stop_run, WARDBY_TOOL_MAX_TIMEOUT_MS]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool call ran out of time
+
+## What happened
+
+A call returned `mcp_call_timeout`: the server did not answer within the call's limit, the run's own time limit was reached, or `stop_run` stopped the call. Only this call failed.
+
+## What to do
+
+1. If the server is slow, raise `callTimeoutMs` with `attach_mcp_server` (default `30000`).
+2. The limit can't exceed `WARDBY_TOOL_MAX_TIMEOUT_MS`; ask the operator to raise that if needed.
+3. A call is also cut to the run's deadline; give the agent a longer run time if needed.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-server-auth-failed.md

@@ -0,0 +1,22 @@
+---
+id: errors/mcp-server-auth-failed
+title: A remote tool server refused the credentials (mcp_server_auth_failed)
+summary: The MCP server answered 401 or 403; fix the brokered secret or its placement.
+audience: operator
+tags: [mcp, mcp_server_auth_failed, 401, 403, brokered, set_secret_broker]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool server refused the credentials
+
+## What happened
+
+A call, or a register or refresh, failed with `mcp_server_auth_failed`: the server answered HTTP 401 or 403 to the credentials Wardby sent.
+
+## What to do
+
+1. Check that the token behind the server's `secretNames` is current and has access to the tool.
+2. Check the secret's placement with `set_secret_broker`, for example header `Authorization` with format `Bearer {value}`.
+3. Update the secret, then `refresh_mcp_server` to confirm. Secret values are never shown in the error.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-server-credentials-unavailable.md

@@ -0,0 +1,45 @@
+---
+id: errors/mcp-server-credentials-unavailable
+title: A remote tool server's credentials can't be decrypted (mcp_server_credentials_unavailable)
+summary: A brokered secret of an MCP server exists but this Wardby server can't decrypt it; check SECRET_APP_KEY.
+audience: operator
+tags: [mcp, mcp_server_credentials_unavailable, credentials, decrypt, SECRET_APP_KEY, register_mcp_server]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool server's credentials can't be decrypted
+
+## What happened
+
+An agent's MCP tool call returned `mcp_server_credentials_unavailable`, or `register_mcp_server`,
+`update_mcp_server` or `refresh_mcp_server` failed with it (as an HTTP 500 error). The server's
+brokered secret exists, but the Wardby process that made the call could not decrypt its stored value.
+Wardby did not contact the MCP server. The same cause has knock-on effects elsewhere in the run:
+posting and `delegate_to_*` tools return `secret_check_unavailable`, the run's final text and error
+are withheld, and `get_run` withholds the request (see [Secrets and tools](../../docs/tool-secrets.md)).
+
+The usual causes:
+
+- The Wardby processes don't share one `SECRET_APP_KEY`. The control plane, the scheduler and the
+  native gateway each decrypt secrets, so a process started with another key can't read a secret
+  the others saved.
+- `SECRET_APP_KEY` was changed after the secret was saved.
+- The stored value is damaged.
+
+An agent that uses another owner's server through a grant sees the same code with a generic
+message: "The MCP server's credentials can't be used; ask its owner to check it."
+
+## What to do
+
+1. Check that every Wardby process (control plane, scheduler, native gateway) gets the same
+   `SECRET_APP_KEY`. Fix the one that differs and restart it.
+2. If the key really changed, set the secret again with its new value (`create_secret` with the same
+   name), then run `refresh_mcp_server`.
+3. Operator logs carry one `warn` line per failure with `reason: "mcp_secret_decrypt_failed"`, the
+   server and the secret name (never the value or the cipher's error).
+
+A secret that is missing, not brokered, or not brokered to the server's host is an input problem
+instead and returns [`mcp_server_error`](mcp-server-error.md) or a 400 error from the register,
+update and refresh tools.
+
+See [Remote MCP servers](../mcp-servers.md) and [Secrets and tools](../../docs/tool-secrets.md).

package/help/errors/mcp-server-error.md

@@ -0,0 +1,28 @@
+---
+id: errors/mcp-server-error
+title: A remote tool server returned an error (mcp_server_error)
+summary: The MCP server answered with an HTTP error or a bad reply, asked for something Wardby doesn't support, or the tool reported an error.
+audience: operator
+tags: [mcp, mcp_server_error, isError, tools/call, credentials]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool server returned an error
+
+## What happened
+
+A call returned `mcp_server_error`. One of these happened:
+
+- the server answered with an HTTP status other than 2xx (not 401 or 403), or sent a reply Wardby could not read;
+- the server's reply carried only a request of its own (sampling, elicitation or roots) and no answer: Wardby supports none of them, so the call fails;
+- the tool ran and reported an error; the server's message is passed on with secret values removed;
+- the server's secrets could not be loaded (missing, not brokered, or not brokered to the server's host). The server's owner sees which secret; an agent using a server shared with its owner sees only "The MCP server's credentials can't be used; ask its owner to check it."
+
+## What to do
+
+1. Read the message: a tool-reported error usually says what was wrong with the arguments.
+2. If the HTTP status is a 5xx, retry later or ask the server's operator.
+3. If the tool's input changed, `refresh_mcp_server` and review `get_mcp_server`.
+4. For a credentials message on a shared server, ask the server's owner to check its secrets with `get_mcp_server` and `list_secrets`.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-server-unreachable.md

@@ -0,0 +1,22 @@
+---
+id: errors/mcp-server-unreachable
+title: A remote tool server could not be reached (mcp_server_unreachable)
+summary: Wardby could not connect to a remote MCP server; check the URL, the server and its network path.
+audience: operator
+tags: [mcp, mcp_server_unreachable, unreachable, register_mcp_server, update_mcp_server]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool server could not be reached
+
+## What happened
+
+An agent's MCP tool call returned `mcp_server_unreachable`, or `register_mcp_server` / `refresh_mcp_server` failed with it. Wardby could not open a connection to the server's URL (DNS, TLS, refused or reset connection). Only this call failed.
+
+## What to do
+
+1. Check the URL with `get_mcp_server` (the owner sees it) and that the server is up.
+2. Check that Wardby's network can reach the host over HTTPS on the default port.
+3. Fix the URL with `update_mcp_server`, then `refresh_mcp_server`.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-servers-off.md

@@ -0,0 +1,21 @@
+---
+id: errors/mcp-servers-off
+title: Remote tool servers are turned off (mcp_servers_off)
+summary: WARDBY_MCP_SERVERS=off: MCP server tools are refused and attached servers are left out of runs.
+audience: operator
+tags: [mcp, mcp_servers_off, WARDBY_MCP_SERVERS, off, admins]
+appliesTo: ">=0.8.0"
+---
+
+# Remote tool servers are turned off
+
+## What happened
+
+The Wardby MCP-server tools answered `mcp_servers_off` (403), or a run's MCP call did. The server has `WARDBY_MCP_SERVERS=off`. Attached servers' tools are left out of new runs. `detach_mcp_server` and `delete_mcp_server` still work, so you can clean up while the feature is off.
+
+## What to do
+
+1. Ask the operator to set `WARDBY_MCP_SERVERS` to `owners` or `admins` and restart.
+2. With `admins`, registering, updating and refreshing need `hosts:admin`.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-tool-not-allowed.md

@@ -0,0 +1,26 @@
+---
+id: errors/mcp-tool-not-allowed
+title: A remote tool is no longer allowed (mcp_tool_not_allowed)
+summary: The agent's MCP server was detached, the tool left its allowlist, or the agent's owner lost use access to a shared server.
+audience: operator
+tags: [mcp, mcp_tool_not_allowed, attach_mcp_server, detach_mcp_server, allowedTools, revoke_access]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool is no longer allowed
+
+## What happened
+
+A call returned `mcp_tool_not_allowed`. Wardby checks the agent's attachment on every call, and since the run began one of these happened:
+
+- the server was detached, or the tool left `allowedTools`;
+- the server's owner deleted the server;
+- the server is shared with the agent's owner, and its owner revoked that grant or lowered it to `read`. The agent's owner must own the server or hold `use` on it; when that ends, Wardby detaches the server from the agent too.
+
+## What to do
+
+1. Check `get_agent` for `mcpServers`.
+2. Re-attach with `attach_mcp_server` and include the tool in `allowedTools`. For a shared server, ask its owner for `use` again first.
+3. A run that started before the change still lists the tool, but every call re-checks the attachment, so the call is refused with this error.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-tool-removed.md

@@ -0,0 +1,22 @@
+---
+id: errors/mcp-tool-removed
+title: A remote tool is no longer on the server (mcp_tool_removed)
+summary: The server's saved tool list no longer has the tool; check missingTools in get_agent.
+audience: operator
+tags: [mcp, mcp_tool_removed, missingTools, refresh_mcp_server]
+appliesTo: ">=0.8.0"
+---
+
+# A remote tool is no longer on the server
+
+## What happened
+
+A call returned `mcp_tool_removed`. After a `refresh_mcp_server`, the server's saved list no longer includes a tool the agent allows, so calls to it are refused. `get_agent` lists it under `missingTools`.
+
+## What to do
+
+1. Check `get_mcp_server` for the tool's current name; servers sometimes rename tools.
+2. Re-attach with `attach_mcp_server` using the new name.
+3. If the tool is back on the server, `refresh_mcp_server` makes it callable again.
+
+See [Remote MCP servers](../mcp-servers.md).

package/help/errors/mcp-unavailable.md

@@ -0,0 +1,25 @@
+---
+id: errors/mcp-unavailable
+title: Remote MCP tools are unavailable to a coding run (mcp_unavailable)
+summary: The coding proxy's MCP route has no native gateway to forward to, or could not reach it, so coding agents get no remote MCP tools.
+audience: operator
+tags: [mcp, mcp_unavailable, WARDBY_MCP_GATEWAY_URL, coding proxy, native gateway, coding agent]
+appliesTo: ">=0.8.0"
+---
+
+# Remote MCP tools are unavailable to a coding run
+
+## What happened
+
+The coding proxy's `/mcp` route answered `503` or `502` with `mcp_unavailable`. A coding worker reaches its MCP tools only through that route, which forwards to the native gateway. It fails in one of two ways:
+
+- `WARDBY_MCP_GATEWAY_URL` is not set on the proxy (`503`). The coding agent then runs without MCP tools; the run does not fail.
+- The gateway could not be reached, timed out or answered too much (`502`). Only that request fails.
+
+## What to do
+
+1. Set `WARDBY_MCP_GATEWAY_URL` on the coding proxy to the native gateway's base URL, for example `http://<gateway host>:<port>`. The kind and GKE manifests set it to the in-cluster gateway.
+2. Check that the native gateway is running and that the proxy's network policy allows it to reach the gateway's HTTP port.
+3. Restart the proxy after changing the variable. An invalid value stops start-up.
+
+See [Remote MCP servers for coding agents](../../docs/mcp-servers.md#coding-agents).

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native sandbox is at capacity

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native run deadline exceeded

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker Docker command failed

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker's gateway call failed

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native gateway Service unavailable

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker image not pinned

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker pod differs from what Wardby built

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

@@ -4,7 +4,7 @@ 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"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker network isolation not proven

package/help/errors/native-sandbox-requires-catalog.md

@@ -4,7 +4,7 @@ title: Sandbox run has no model catalog entry
 summary: A sandbox-mode run could not start because no model catalog entry was recorded for it.
 audience: operator
 tags: [error, native-agents, sandbox, model-catalog, native_sandbox_requires_catalog]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Sandbox run has no model catalog entry

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

@@ -4,7 +4,7 @@ title: Native execution mode unavailable
 summary: A run failed with native_sandbox_unavailable because its agent is in sandbox mode but the server has no native sandbox configured.
 audience: operator
 tags: [error, native-agents, sandbox, native_sandbox_unavailable]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Native execution mode unavailable

package/help/errors/native-sandbox-warm-delivery-failed.md

@@ -4,7 +4,7 @@ title: Native sandbox warm worker could not take the run
 summary: A run claimed an idle warm-pool worker, delivering its input failed, and the worker could not be confirmed stopped within 30 seconds, so the run failed instead of cold-launching.
 audience: operator
 tags: [error, native-agents, sandbox, warm-pool, kubernetes, docker, native_sandbox_warm_delivery_failed]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Native sandbox warm worker could not take the run

package/help/errors/native-sandbox-worker-exited.md

@@ -4,7 +4,7 @@ title: Native worker exited without a result
 summary: The sandbox worker container ended without producing a result.
 audience: operator
 tags: [error, native-agents, sandbox, native_sandbox_worker_exited]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker exited without a result

package/help/errors/native-sandbox-worker-lost.md

@@ -4,7 +4,7 @@ title: Native worker lost
 summary: The sandbox worker container disappeared and was not relaunched.
 audience: operator
 tags: [error, native-agents, sandbox, native_sandbox_worker_lost]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Native worker lost