@wardby/cli 0.6.0 → 0.8.0

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

@@ -19,6 +19,10 @@ existing link to it are refused.
 
 - **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.
 

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/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/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/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

@@ -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.6.0"
+---
+
+# 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).