@wardby/cli 0.5.3 → 0.7.0

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

@@ -0,0 +1,31 @@
+---
+id: errors/native-sandbox-requires-catalog
+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"
+---
+
+# Sandbox run has no model catalog entry
+
+`native_sandbox_requires_catalog` means a sandbox-mode run reached its worker
+launch without a model catalog entry. The worker prices every model call and
+enforces the run's budget from that entry, so Wardby fails the run before
+starting a worker or spending anything.
+
+Every run records its model's catalog entry when it first starts. A model
+that is unknown, disabled, or has no configured provider fails earlier with
+its own model error, not this one. This error only appears when the process
+executing the run does not use Wardby's catalog-backed model router, for
+example a modified build or an embedding that supplies its own LLM provider.
+
+1. Run sandbox-mode agents on a standard `wardby serve` (or `wardby
+scheduler` / `wardby mcp`) process, which always uses the catalog.
+2. If you supply your own LLM provider, route it through the model catalog,
+   or keep the agent on `control-plane` with `update_agent` or
+   `wardby agent mode <name> control-plane`.
+3. Trigger the run again. A failed run is not retried on its own.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and
+[Models and the model catalog](../models.md).

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

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-unavailable
+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"
+---
+
+# Native execution mode unavailable
+
+`native_sandbox_unavailable` means the agent's `nativeExecutionMode` is `sandbox` but this deployment has no native sandbox configured. Wardby fails the run before any spend rather than running it unisolated.
+
+1. To use the sandbox, set `NATIVE_SANDBOX_LAUNCHER=docker`, `NATIVE_SANDBOX_WORKER_IMAGE`, and `NATIVE_GATEWAY_CONTAINER` on the server that executes runs (`wardby serve` or `wardby scheduler`), start the native gateway, and restart the server.
+2. Otherwise set the agent back to `control-plane` with `update_agent`.
+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-warm-delivery-failed.md

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-warm-delivery-failed
+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"
+---
+
+# Native sandbox warm worker could not take the run
+
+`native_sandbox_warm_delivery_failed` means a sandbox run claimed an idle worker from the warm pool (`NATIVE_SANDBOX_WARM_POOL_SIZE`), but writing the run's input into that worker failed. The worker may already hold the run's one-time gateway capability, so Wardby removes it and waits up to 30 seconds for it to be confirmed gone before starting a cold worker. This error means it could not be confirmed gone in that time, so the run failed rather than risk two workers holding the same capability. If the worker is confirmed gone, the run cold-launches and you see no error (the log has a `fallback` event).
+
+1. Trigger the run again. Most failures are transient.
+2. Check that the worker is gone: `kubectl get pods -n <namespace> -l wardby.io/pool=warm` (Kubernetes) or `docker ps --all --filter label=io.wardby.pool=warm` (Docker). Pool upkeep removes leftovers, but a stuck pod usually means the node or Docker host is unhealthy.
+3. Look for `native-warm-pool` log entries with `event` `fallback`, and check that the server may exec into pods in the run namespace.
+4. To bypass the pool while you investigate, set `NATIVE_SANDBOX_WARM_POOL_SIZE=0`; every run then cold-starts.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md#warm-pool). A related error is
+[native_sandbox_capacity](native-sandbox-capacity.md).

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

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-worker-exited
+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"
+---
+
+# Native worker exited without a result
+
+`native_sandbox_worker_exited` means the worker container stopped without reporting a result; the message includes its exit code. Common causes are a tool that exhausted the worker's memory or process limit, or a crash in tool code.
+
+1. Read the exit code in the run's error (`get_run`). Code 137 usually means the memory limit was hit.
+2. If limits are the cause, raise `NATIVE_SANDBOX_MEMORY_MB`, `NATIVE_SANDBOX_PIDS`, or `NATIVE_SANDBOX_CPUS` on the server and restart it.
+3. Read the server log line `native worker exited non-zero` (Docker and Kubernetes): its `stderrTail` is the end of the worker's output. The server masks the run's gateway capability and every secret value the agent's tools can read (six characters or longer, as in tool console output) as `[REDACTED]`. If the line has `stderrTailOmitted` instead, there is no tail: `secrets_unavailable` means the server could not read one of those secrets (check the secret store and the tools' attached secrets); `log_read_failed` means it could not read the worker pod's log on Kubernetes (check that the server's Role allows `get` on `pods/log`).
+4. Otherwise test the agent's tools with `dry_run_tool` and fix the failing code.
+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-worker-lost.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-worker-lost
+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"
+---
+
+# Native worker lost
+
+`native_sandbox_worker_lost` means the run's worker container (or Kubernetes pod) is gone and left no result, for example because the Docker host restarted or an operator removed the container. Wardby never relaunches a worker, because a relaunch could repeat tool side effects.
+
+1. Check whether the Docker host or daemon restarted around the run's time.
+2. List workers with `docker ps --all --filter label=io.wardby.component=native-worker`; do not remove workers of running runs by hand.
+3. On Kubernetes, check whether the node was drained or preempted, and list pods with `kubectl get pods -n <namespace> -l wardby.io/component=native-run`.
+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-worker-unready.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-worker-unready
+title: Native worker pod did not start
+summary: On Kubernetes, the sandbox worker pod did not reach the Running state in time, so the run failed before starting.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_worker_unready]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker pod did not start
+
+`native_sandbox_worker_unready` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the worker pod stayed pending past the start-up limit (`NATIVE_SANDBOX_READY_TIMEOUT_MS`, default two minutes). Nothing ran.
+
+1. Describe the pod while it waits: `kubectl describe pod -n <namespace> -l wardby.io/component=native-run`. Look at the events for image pull errors, unschedulable reasons, or an unknown runtime class.
+2. Image pull: the cluster must be able to pull `NATIVE_SANDBOX_WORKER_IMAGE` (a registry digest) without interactive credentials; add a pull secret to the namespace's default service account if the registry is private.
+3. Scheduling: raise node capacity or lower `NATIVE_SANDBOX_CPUS` and `NATIVE_SANDBOX_MEMORY_MB`, and check namespace ResourceQuotas.
+4. Runtime class: confirm `NATIVE_SANDBOX_RUNTIME_CLASS` (or `KUBERNETES_RUNTIME_CLASS`) exists on the cluster. On Amazon EKS (`KUBERNETES_PLATFORM=eks`) the `gvisor` RuntimeClass must use handler `runsc` and its scheduling block must match your sandbox nodes (label `wardby.dev/sandbox=gvisor`, taint `sandbox=gvisor:NoSchedule`); a mismatch leaves the pod pending.
+5. On a cold node, such as a first gVisor pod on GKE Autopilot (about two minutes), raise `NATIVE_SANDBOX_READY_TIMEOUT_MS` (1000 to 1800000; about 600000 on Autopilot).
+6. 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/package-not-allowed-pending.md

@@ -0,0 +1,52 @@
+---
+id: errors/package-not-allowed-pending
+title: Package not reached (wardby_package_not_allowed_pending)
+summary: The dependency-graph walk stopped before reaching the requested package; the owner should allowlist it directly because retrying rarely helps.
+audience: operator
+tags: [error, coding-agents, packages, allowlist, wardby_package_not_allowed_pending]
+appliesTo: ">=0.7.0"
+---
+
+# Package not reached
+
+`wardby_package_not_allowed_pending` (HTTP 403) means the registry's
+dependency-graph walk ended before it reached the requested package. The
+package may still be reachable from an allowlisted one, but the walk was cut
+short (by `REGISTRY_GRAPH_TIMEOUT_MS`), so it was not proven allowed. The error message shows
+how many packages were walked and how many were still queued. 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. Otherwise a metadata request gets
+`wardby_package_not_allowed` at once instead.
+
+The answer is final for the agent and is not transient: the walk resumes
+within the run, but each request continues the walk for at most
+`REGISTRY_GRAPH_TIMEOUT_MS`, so a large allowlist can take several requests or
+never finish in time. Retrying rarely helps; allowlisting the package directly
+is the reliable fix.
+
+## What the agent should do
+
+Stop retrying. Report the package name so its owner can allowlist it.
+
+## 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.
+
+Large frameworks (for example Expo) can have a very large graph, because the
+walk follows every in-range version plus optional and peer dependencies.
+Allowlisting the packages the project needs directly avoids the walk for them.
+
+## Operator knobs
+
+`REGISTRY_GRAPH_TIMEOUT_MS` is the time one request's walk may take. See
+[Operator limits](../../docs/coding-packages.md#operator-limits).
+
+## Related
+
+- [Not allowed: `wardby_package_not_allowed`](package-not-allowed.md)
+- [Graph limit: `wardby_graph_limit`](graph-limit.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](../coding-packages.md)

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

@@ -0,0 +1,51 @@
+---
+id: errors/package-not-allowed
+title: Package not allowed (wardby_package_not_allowed)
+summary: The coding package registry refused a package because it is not on the agent's allowlist, or is only reachable through a refused package.
+audience: operator
+tags: [error, coding-agents, packages, allowlist, wardby_package_not_allowed]
+appliesTo: ">=0.7.0"
+---
+
+# Package not allowed
+
+`wardby_package_not_allowed` (HTTP 403) is a final answer from the package
+registry: the package is not on the agent's `packageAllowlist`, and nothing
+the run has resolved allows it. It is also returned for a package reachable
+only through a package that was itself refused (for example one with a
+high-severity advisory).
+
+- When npm resolves a package (a metadata request), the package is refused at
+  once unless it is allowlisted, was declared as a dependency by a package
+  already resolved in the run, or was approved by the run's lockfile plan. So
+  a new top-level package must be allowlisted, even if an allowlisted
+  package's dependency graph contains it. (After a lockfile plan of the run
+  failed or refused an entry, the metadata request walks the dependency graph
+  first, as a download does.)
+- When npm downloads a tarball the run has not resolved (a lockfile install),
+  it is refused once the dependency-graph walk finds no allowlisted package
+  that reaches it.
+
+## What the agent should do
+
+Stop. Do not retry, and do not look for a way around the refusal. Pick an
+already-approved alternative, or report that the package needs approval.
+
+## What the owner does
+
+1. Open the agent with `get_agent`, then add the package to `codingProfile.packageAllowlist` with `update_agent`. This needs `packages:approve` or `agents:admin`. For a package the project adds directly, allowlist the package itself; allowlisting a dependent only helps for a package something already in the project depends on.
+2. Run the request again. Allowing a package name allows all of its kept versions, subject to the release-age and vulnerability checks.
+
+For a PyPI package pulled in by an extra (`psycopg-binary` for
+`psycopg[binary]`), name the extra on the entry instead.
+
+If the package is only reachable through a refused one, allowlisting more
+packages will not help; change or drop the refused dependency.
+
+## Related
+
+- [Pending answer: `wardby_package_not_allowed_pending`](package-not-allowed-pending.md): the walk stopped before reaching the name.
+- [Graph limit: `wardby_graph_limit`](graph-limit.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](../coding-packages.md): the allowlist, the walk and the full error table.

package/help/errors/package-refusals.md

@@ -0,0 +1,43 @@
+---
+id: errors/package-refusals
+title: Package registry refused an install
+summary: Understand package refusal codes and unblock a coding run's blocked status.
+audience: operator
+tags: [error, packages, allowlist, wardby_graph_incomplete, wardby_graph_limit, wardby_package_not_allowed, wardby_package_not_allowed_pending, wardby_version_filtered, wardby_lockfile_entry_unsupported]
+appliesTo: >=0.2.1
+---
+
+# Package registry refused an install
+
+A coding run can finish successfully after restoring its changes because a
+needed package was refused. When no pull request or pushed changes result,
+the parent status says ⛔ **Blocked by the package registry: no changes were
+made.** With a pull request, the link stays and a ⚠️ warning lists refusals.
+
+- `wardby_package_not_allowed`, `wardby_package_not_allowed_pending`, and
+  `wardby_graph_limit`: add the needed package to the coding agent's
+  `codingProfile.packageAllowlist` with `update_agent`.
+- `wardby_graph_incomplete`, `wardby_upstream_error`,
+  `wardby_upstream_unavailable`, `wardby_audit_unavailable`, and
+  `wardby_download_idle`: the registry could not finish checking the package,
+  usually because an upstream was slow or failing. Mention `@wardby` again to
+  retry.
+- `wardby_version_filtered`: no version passed the release-age, advisory, or
+  malware checks. For release age, wait or adjust
+  `codingProfile.packagePolicy.minReleaseAgeDays`. For an advisory, upgrade
+  to a safe version or accept the advisory after reviewing exposure using
+  `codingProfile.packagePolicy.acceptedAdvisories`. Malware is never waivable:
+  use a safe alternative, never bypass the malware check. The code alone
+  does not distinguish which check blocked the version.
+- `wardby_lockfile_entry_unsupported`: the lock file installs the package
+  from git or a URL, which the registry cannot verify. Depend on a registry
+  version instead.
+- Other codes: inspect the registry error and package policy before retrying.
+
+Changing allowlists or policy needs `packages:approve` or `agents:admin`.
+`update_agent` replaces the whole package policy, so send all intended fields.
+After fixing the refusal, mention `@wardby` again. An existing run's package
+policy does not change.
+
+See [Approve packages for coding agents](../coding-packages.md) and
+[Run status comments](../status-comments.md).

package/help/errors/patch-cursor-malformed.md

@@ -0,0 +1,31 @@
+---
+id: errors/patch-cursor-malformed
+title: Patch cursor is malformed
+summary: A repo_pr_read call passed a patchCursor that is not a well-formed cursor for the pull request (edited, truncated, retyped or too long).
+audience: operator
+tags: [error, code-review-agents, repo_pr_read, patchCursor, patch_cursor_malformed, patch_cursor_stale]
+appliesTo: ">=0.7.0"
+---
+
+# Patch cursor is malformed
+
+`repo_pr_read` returns `patch_cursor_malformed` to a review agent when the
+`patchCursor` it passed is not a well-formed cursor for this pull request: the
+value was edited, truncated, damaged in transit, retyped by the model, or is
+over-long. No page is returned or recorded as read, and nothing else changes;
+the call can be made again.
+
+A cursor is also tied to the pull request's head and compare. When the pull
+request has moved on since the cursor was issued, the call returns
+`patch_cursor_stale` instead.
+
+## What to do
+
+- Pass `nextPatchCursor` back exactly as `repo_pr_read` returned it, with the
+  same arguments as the call that produced it.
+- After `patch_cursor_stale`, or if no valid cursor is at hand, call
+  `repo_pr_read` again without `patchCursor` to start from the first page.
+- If a model keeps rewriting the cursor, tell it in the agent's prompt to copy
+  `nextPatchCursor` verbatim.
+
+See [Code review agents](../code-review-agents.md) for how patch pages work.

package/help/errors/run-lost.md

@@ -0,0 +1,39 @@
+---
+id: errors/run-lost
+title: Run lost
+summary: A run ended as lost, usually because a deploy replaced the version that was executing it.
+audience: operator
+tags: [error, runs, deploy, lost]
+appliesTo: ">=0.7.0"
+---
+
+# Run lost
+
+A run with status `lost` stopped without finishing and without a result. Read its `error` with `get_run`. The usual cause is a deploy that changed the application version while the run was still going.
+
+## When a deploy does not lose a run
+
+A native run that is waiting in a `delegate_to_*` call on a coding sub-agent, or on a native sub-agent running in `sandbox` mode, is taken over by the new version. It continues when the sub-agent finishes, and the turns it already took are not repeated.
+
+## Reasons
+
+- `Durable workflow belongs to application version <old>; this process runs <new>.` The run was mid-turn, waiting on a tool that is not a delegation, or waiting on a control-plane native sub-agent, so the new version could not take it over.
+- `Could not continue across versions: the run's steps changed in the new version.` The run was waiting on a sub-agent, but the new code no longer matches the steps the run had recorded.
+- `Durable workflow could not be re-driven after 3 adoption attempts…` Wardby tried three times to resume the run and gave up.
+- `Orphaned: no heartbeat/progress since before <time>.` Nothing was executing the run and it stopped reporting progress, for example because its process was killed.
+
+## Sub-agents of a lost run
+
+When a run is marked lost, sub-agent runs it started that are still going are stopped with the reason `parent run lost`. They are not left running for nobody.
+
+A run that continues after a restart of the same version cannot continue a control-plane native sub-agent it was waiting on: that sub-agent ran inside the process that stopped. (After a deploy, a run waiting on such a sub-agent is not taken over at all; it is marked lost, as above.) The sub-agent run is stopped with the reason `parent resumed without it`, and no new one is started. The parent run goes on, and its `delegate_to_*` call returns the error `subagent_interrupted` ("The sub-agent was interrupted by a restart and cannot be resumed; no new sub-agent run was started."), so the model can report it.
+
+If two executions of the same `delegate_to_*` step overlap and the call id is already held by a run of a different sub-agent, the call returns `delegation_conflict` instead; see [Delegation conflict](delegation-conflict.md).
+
+## What to do
+
+1. Read the reason with `get_run`.
+2. Trigger the request again. If an `@`-mention started the run, its status comment says the request was interrupted and should be repeated.
+3. To lose fewer runs, deploy when few runs are executing. The old version first waits for its runs to finish, up to `SHUTDOWN_DRAIN_SECONDS`; only runs still going after that limit are affected.
+
+See [Operating agents](../operating-agents.md) and the [GKE guide](../../docs/getting-started-gke.md).

package/help/errors/run-transcript-download.md

@@ -0,0 +1,44 @@
+---
+id: errors/run-transcript-download
+title: Run transcript download refused
+summary: What each refusal from a get_run_transcript download link means (link_invalid, not_found, transcript_expired, transcript_unavailable, transcript_corrupt, local_repository_refused) and what to do.
+audience: operator
+tags: [wardby resume, get_run_transcript, link_invalid, transcript_expired, local_repository_refused, download]
+appliesTo: ">=0.7.0"
+---
+
+# Run transcript download refused
+
+`wardby resume` downloads a run's transcript from the link
+`get_run_transcript` returned. When the server refuses, it answers with JSON
+`{ "error": "<code>" }`, and `wardby resume` prints what the code means.
+Nothing is written to your machine.
+
+| Code                     | HTTP | Meaning and what to do                                                                                                                                                                                                                                                   |
+| ------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `link_invalid`           | 403  | The link is malformed, was changed, was made by another server (or by a stdio server, on the HTTP route), or is older than 10 minutes. Call `get_run_transcript` again for a new link. Every HTTP instance must share `SECRET_APP_KEY` (or `REQUEST_STATE_KEY`, if set). |
+| `not_found`              | 404  | The person the link was made for can no longer read the run, or the run has no stored transcript.                                                                                                                                                                        |
+| `transcript_expired`     | 410  | The transcript was deleted after `RUN_TRANSCRIPT_RETENTION_DAYS`.                                                                                                                                                                                                        |
+| `transcript_unavailable` | 503  | The server has no blob store configured (`BLOB_STORE`), or could not read the object. Check the blob store settings on the server process.                                                                                                                               |
+| `transcript_corrupt`     | 500  | The stored object no longer matches the SHA-256 recorded when it was stored, so the server refused to send it.                                                                                                                                                           |
+
+`wardby resume` also refuses a download whose bytes do not match the
+server's SHA-256 header, a response larger than it accepts or with an invalid
+length, and run details with control characters, and never writes a partial
+file.
+
+## local_repository_refused
+
+Printed by `wardby resume`, not the server. The run's repository is a
+`local:` folder, which names a path on the server's machine, but the link
+comes from another machine. Checking it out would let that server choose any
+repository on yours, so nothing was written. Run the command on the server's
+machine with a link from its stdio MCP server, or pass `--here` to continue
+in the current directory, or `--dir <path>` to check the run out from that
+folder anyway.
+
+Over stdio, the link points at a local port the MCP server opens while links
+are in use: if `wardby resume` cannot reach it, keep your MCP client
+connected and request a new link.
+
+See [Resume Claude Code runs locally](../resume-runs-locally.md).

package/help/errors/secret-broker-body-invalid.md

@@ -0,0 +1,26 @@
+---
+id: errors/secret-broker-body-invalid
+title: Secret broker body invalid
+summary: Body placement needs a JSON-object or form-encoded request body with a matching content-type.
+audience: operator
+tags: [error, secrets, secret_broker_body_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker body invalid
+
+`secret_broker_body_invalid` means a secret placed in the request body could not
+be added to the body the tool sent. Body placement needs one of:
+
+- a JSON object body with `content-type: application/json` (or a `+json` type);
+- a form body with `content-type: application/x-www-form-urlencoded`.
+
+The request must have a body, valid JSON that is an object (not an array or a
+scalar), and a matching `content-type` header.
+
+1. Send a body of a supported type and set the `content-type` header to match.
+2. If the API expects the credential elsewhere, change the placement with
+   `set_secret_broker` to `header` or `query`.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-changed.md

@@ -0,0 +1,20 @@
+---
+id: errors/secret-broker-changed
+title: Brokering changed since the link was created
+summary: A browser link to remove brokering was created before the secret's broker config changed, so it no longer applies.
+audience: operator
+tags: [error, secrets, secret_broker_changed]
+appliesTo: ">=0.6.0"
+---
+
+# Brokering changed since the link was created
+
+`secret_broker_changed` means the browser link for removing brokering was minted
+for a broker config that has since changed or been removed. A link only ever
+removes the exact config it was created for.
+
+1. Call `set_secret_broker` with `broker: null` again to get a new link.
+2. Check the config shown on the new page before confirming removal.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-config-invalid.md

@@ -0,0 +1,30 @@
+---
+id: errors/secret-broker-config-invalid
+title: Secret broker config invalid
+summary: A broker config failed validation: hosts, path prefixes, or placement are malformed.
+audience: operator
+tags: [error, secrets, secret_broker_config_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker config invalid
+
+`secret_broker_config_invalid` means the broker config passed to `create_secret`,
+`set_secret_broker`, or the browser form did not validate. The message lists
+each problem. Common causes:
+
+- `hosts` is empty, has more than 20 entries, or contains a scheme, port,
+  wildcard, or IP address (including short forms such as `127.1`), or a label
+  ending in `-`; use exact hostnames such as `api.example.com`;
+- a `pathPrefixes` entry does not start with `/`, or contains `?`, `#`, a
+  backslash, a control character, `%2F`, or `%5C`;
+- a header `format` does not contain `{value}` exactly once or contains a line
+  break, or the header name is not allowed (`Host`, `Content-Length` and similar);
+- an AWS `region` or `service` is malformed;
+- the config or its placement has fields it does not define.
+
+1. Fix the fields named in the message and retry.
+2. The config shape is `{ hosts, pathPrefixes?, placement }`.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-conflict.md

@@ -0,0 +1,27 @@
+---
+id: errors/secret-broker-conflict
+title: Secret broker placement conflict
+summary: The request already sets the header, parameter, or field a broker places, two brokers collide, or more than one SigV4 secret was named.
+audience: operator
+tags: [error, secrets, secret_broker_conflict]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker placement conflict
+
+`secret_broker_conflict` means the request would set the same spot twice. A
+brokered value is never merged with or overridden by one from the tool. It
+occurs when:
+
+- the tool sets the header, query parameter, or body field that a brokered
+  secret places (for SigV4: `authorization`, `x-amz-date`,
+  `x-amz-security-token`, or `x-amz-content-sha256`);
+- two named secrets place the same header, parameter, or field;
+- more than one AWS SigV4 secret is named in one request.
+
+1. Remove the conflicting header, parameter, or field from the tool's request.
+2. Send secrets that place the same spot in separate requests.
+3. Name at most one SigV4 secret per request.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-destination-denied.md

@@ -0,0 +1,28 @@
+---
+id: errors/secret-broker-destination-denied
+title: Secret broker destination denied
+summary: A fetch with a brokered secret targeted a URL that is not https, uses a non-default port, or is outside the allowed hosts or path prefixes.
+audience: operator
+tags: [error, secrets, secret_broker_destination_denied]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker destination denied
+
+`secret_broker_destination_denied` means a brokered secret may not be sent to
+the requested URL. The message says which check failed:
+
+- the URL is not `https`, or names a port other than the default;
+- the host is not in the secret's `hosts` (exact match, no wildcards);
+- the path does not start with any of the secret's `pathPrefixes`, or, for a
+  secret with `pathPrefixes`, contains an encoded slash or backslash (`%2F`,
+  `%5C`).
+
+1. Correct the URL in the tool.
+2. If the destination is intended, the secret's owner updates the config with
+   `set_secret_broker`, adding the host or path prefix.
+3. Make sure the tool attachment's `allowedHosts` also lists the host; a host
+   missing there is refused by the normal fetch policy.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-value-invalid.md

@@ -0,0 +1,28 @@
+---
+id: errors/secret-broker-value-invalid
+title: Secret broker value invalid
+summary: A brokered value is shorter than 6 characters, or an AWS SigV4 secret is not the expected JSON.
+audience: operator
+tags: [error, secrets, secret_broker_value_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker value invalid
+
+`secret_broker_value_invalid` means the stored value cannot be brokered under its
+config. It is returned when saving a config and when a tool uses the secret.
+
+- A brokered value must be at least 6 characters.
+- An AWS SigV4 secret's value must be JSON
+  `{"accessKeyId": "...", "secretAccessKey": "...", "sessionToken": "..."}` with
+  no other keys. `sessionToken` is optional; the secret access key and session
+  token must each be at least 6 characters.
+
+1. Re-enter the value with `create_secret` using the same name; it rotates the
+   value in place. Leave out `broker`: a rotation without one keeps the
+   existing broker config. In the browser form, correct the value and submit
+   the same link again.
+2. For SigV4, store the credentials as that JSON object.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-brokered.md

@@ -0,0 +1,24 @@
+---
+id: errors/secret-brokered
+title: Secret is brokered and cannot be read
+summary: A tool called secrets.get on a brokered secret; brokered secrets are only sent with fetch(url, { secrets }).
+audience: operator
+tags: [error, secrets, secret_brokered]
+appliesTo: ">=0.6.0"
+---
+
+# Secret is brokered and cannot be read
+
+`secret_brokered` means a tool called `secrets.get(name)` on a secret that is
+brokered. A brokered secret never exposes its value to tool code.
+
+1. Update the tool to send the secret with
+   `fetch(url, { secrets: ["NAME"] })`; the host places the value in the request.
+2. Or, if the tool really must read the value, have the secret owner remove
+   brokering with `set_secret_broker` and `broker: null`, confirmed in the
+   browser. This makes the value readable by every tool granted it.
+3. `attach_tool` and `set_secret_broker` warn when a granted tool calls
+   `secrets.get`; that scan is best-effort.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).