@wardby/cli 0.6.0 → 0.8.0

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-launch-abandoned.md

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

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

@@ -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
@@ -13,8 +13,9 @@ appliesTo: ">=0.5.4"
 
 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. Otherwise test the agent's tools with `dry_run_tool` and fix the failing code.
-4. Trigger the run again.
+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

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

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

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

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/repository-not-listed.md

@@ -0,0 +1,36 @@
+---
+id: errors/repository-not-listed
+title: Repository not on the agent's list (repository_not_listed)
+summary: The repository named for a coding run is not the agent's default or one of its write links; name a listed one, or add it with link_repository.
+audience: operator
+tags: [error, coding-agents, repository_not_listed, invalid_repository, link_repository]
+appliesTo: ">=0.8.0"
+---
+
+# Repository not on the agent's list
+
+`repository_not_listed` means the `repository` given to `trigger_agent` or to a
+`delegate_to_<name>` call is neither the coding agent's default
+(`codingProfile.repository`) nor one of its repository links (write access, no
+triggers). No run was started. The message lists the repositories that are
+allowed and never repeats the value that was sent.
+
+A webhook that sends `wardbyRepository` gets the same refusal as a 400
+`{ "error": "invalid_repository" }` when
+`codingProfile.allowWebhookTaskOverride` is on. A malformed value (not a string,
+empty, or over 300 characters) is that same 400 with the flag on or off. With
+the flag off, a well-formed value is refused with 403 `{ "error": "disabled" }`
+before it is compared with the list, whoever created the webhook.
+
+## What to do
+
+- Name one of the listed repositories, spelled as `your-org/your-repo`.
+- To add a repository, the agent's owner calls `link_repository` with
+  `access: "write"`, no triggers and, optionally, a `baseRef`. The owner needs
+  write access to it on the host, or an admin approves it.
+- If a native (non-coding) sub-agent is the target, `repository` is refused
+  with `repository_requires_coding_agent`: drop the argument.
+
+See [Repository required](repository-required.md),
+[Agent recipes](../agent-recipes.md) and the operator guide
+`docs/coding-agent-setup.md`, section "A coding agent's repositories".

package/help/errors/repository-required.md

@@ -0,0 +1,36 @@
+---
+id: errors/repository-required
+title: Repository required (repository_required)
+summary: A coding agent with several repositories was asked to work without being told which one; pass repository, or use continuePriorRun.
+audience: operator
+tags: [error, coding-agents, repository_required, repository, link_repository, delegation]
+appliesTo: ">=0.8.0"
+---
+
+# Repository required
+
+`repository_required` means a coding agent has more than its default repository
+(it has write links without triggers added with `link_repository`), and the
+request did not say which one to work in. Nothing was started.
+
+A `delegate_to_<name>` call to such a sub-agent must name a repository. The
+exception is a follow-up: with `continuePriorRun`, the run works in the
+repository of the run it continues. The message lists the repositories on the
+agent's list.
+
+## What to do
+
+- Pass `repository` on the call, using one of the listed repositories, for
+  example `your-org/your-repo`.
+- Tell the lead agent in its system prompt which repository each kind of
+  change belongs to.
+- If the agent should only work in one repository, remove the extra ones with
+  `unlink_repository`.
+
+On `trigger_agent` and webhooks, leaving `repository` out uses the default
+repository (`codingProfile.repository`) and is not an error. Webhooks use the
+body field `wardbyRepository`.
+
+See [Repository not on the agent's list](repository-not-listed.md),
+[Agent recipes](../agent-recipes.md) and the operator guide
+`docs/coding-agent-setup.md`, section "A coding agent's repositories".

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-in-value.md

@@ -0,0 +1,69 @@
+---
+id: errors/secret-in-value
+title: A value was not stored because it contains a secret (secret_in_value)
+summary: A datastore or agent memory write was refused because the value contains the value of a secret attached to the agent; store the secret's name and read it when needed.
+audience: operator
+tags: [error, secrets, datastore, memory, secret_in_value, secret_check_unavailable, datastore set, memory set]
+appliesTo: ">=0.7.0"
+---
+
+# A value was not stored because it contains a secret (secret_in_value)
+
+`secret_in_value` means a write to a datastore or agent memory contained the
+value of a secret attached to the agent, in the value or in the key. The write
+came from a tool's `datastore.set` (or a shared datastore's `set`), from the
+`memory_set` tool, from the `datastore_set` or `set_agent_memory` MCP tools, or
+from a bundle import. The error names the secret. Nothing was stored.
+
+Secret values are never stored in datastores or agent memory, because anything
+stored there can be read back by other tools and later runs that were never
+given the secret, and can be printed.
+
+## What to do
+
+Store the secret's **name**, not its value, and read the secret when you need it:
+
+- `secrets.get("NAME")` in a tool that is allowed to read the secret, or
+- `fetch(url, { secrets: ["NAME"] })` for a brokered secret.
+
+See [Secrets and tools](../../docs/tool-secrets.md#secret-values-are-never-stored).
+
+## `secret_check_unavailable`
+
+The agent's secrets could not be read, so the value could not be checked and was
+not stored. Try the write again. If it keeps happening, check the database
+connection and the secret encryption configuration on the server.
+
+## Bundle imports
+
+A seeded datastore entry in an imported bundle, per-agent or shared, whose key
+or value contains an attached secret's value is skipped, and the import reports
+a warning that names the secret (the entry's key is withheld from the warning).
+The rest of the bundle is still imported.
+
+## Also masked
+
+Secret values are also kept out of other output:
+
+- A native run's final text and error have attached secret values replaced with
+  `[REDACTED]`.
+- The task text of a `delegate_to_*` call has the delegating agent's attached
+  secret values replaced with `[REDACTED]` before the sub-agent's run is created.
+- Comments, reviews, and Jira posts made through built-in tools have attached
+  secret values replaced with `[REDACTED]`.
+- If the secrets cannot be read when a run ends, both its stored final text and
+  its stored error are
+  `[withheld: this text could not be checked for secret values]`.
+- If the secrets cannot be read when a posting tool or a `delegate_to_*` call
+  runs, the tool returns `secret_check_unavailable` and posts nothing or creates
+  no sub-agent run.
+
+## Limits
+
+Matching is by exact value, including its JSON-escaped forms and, for brokered
+secrets, the encoded forms that the broker scrubs. Values shorter than 6
+characters are not matched. A value that is split, re-encoded, or otherwise
+transformed is not detected. Values stored before this check existed are not
+scanned.
+
+See also [Brokered secrets](../brokered-secrets.md).

package/help/errors/target-merge.md

@@ -0,0 +1,40 @@
+---
+id: errors/target-merge
+title: Target branch could not be merged
+summary: A follow-up run could not fetch or merge its pull request's target branch, so it stopped before the agent started.
+audience: operator
+tags: [error, coding-agents, vcs, merge-conflict, target-branch, pull-requests]
+appliesTo: ">=0.7.0"
+---
+
+# Target branch could not be merged
+
+Before a follow-up run on a wardby pull request starts its agent, wardby
+merges the branch the pull request currently targets into the workspace (see
+[Fix merge conflicts on a wardby pull request](../fix-merge-conflicts.md)).
+A run stops with failure category `target_merge` (error
+`vcs_target_merge_failed`) when that could not be done:
+
+- the target branch could not be fetched from the repository (it was deleted,
+  or the fetch failed);
+- the pull request's branch and its target share no history wardby could
+  find: the branches are unrelated, or their common commit is more than about
+  5,000 commits back;
+- the merge itself failed for a reason other than a content conflict (content
+  conflicts are handed to the agent, not failed);
+- the git on the machine that runs wardby is older than 2.38, which does not
+  support the `merge-tree --write-tree` form the merge uses.
+
+Nothing is pushed and no agent work is lost, since the agent had not started.
+
+## What to do
+
+- Check the pull request's base branch on GitHub. Retarget it if the branch
+  it names no longer exists or is not the one it should merge into.
+- For unrelated histories, merge the branches by hand once; later follow-ups
+  then find the merge base.
+- A transient fetch failure succeeds on the next request.
+- Upgrade the machine's git to 2.38 or newer (`git --version` shows it).
+
+Related: [Conflict markers remain](merge-conflict.md),
+[Continuation's pull request is no longer open](continuation-closed.md).

package/help/errors/tool-timeout.md

@@ -0,0 +1,38 @@
+---
+id: errors/tool-timeout
+title: A tool call ran out of time (timeout, fetch_cancelled_or_timeout)
+summary: A sandboxed tool call hit its time limit; raise the tool's timeoutMs, up to the server's WARDBY_TOOL_MAX_TIMEOUT_MS.
+audience: developer
+tags: [timeout, timeoutMs, wall-time, fetch_cancelled_or_timeout, sleep_limit, WARDBY_TOOL_MAX_TIMEOUT_MS]
+appliesTo: ">=0.8.0"
+---
+
+# A tool call ran out of time
+
+## What happened
+
+A tool's result was `{"error":"timeout","message":"Exceeded the 10000ms wall-time limit. ..."}`.
+The call ran longer than the tool's time limit, so it was stopped. The run goes on: only this call
+failed. The message names the limit. Without `timeoutMs` a tool has 10 seconds.
+
+Related results:
+
+- `fetch_cancelled_or_timeout` from inside the tool: a `fetch` was aborted because the call ran
+  out of time or the run stopped.
+- `sleep_limit`: the tool asked to wait longer than its own limit.
+- `{"error":"cancelled"}`: the run was stopped while the call was running.
+
+## What to do
+
+1. Check how long the API the tool calls really takes.
+2. Give the tool a longer limit with `update_tool` (`timeoutMs`, in milliseconds), or
+   `wardby tool update <tool> --timeout-ms <ms>`.
+3. Test it with `dry_run_tool` and the same `timeoutMs`.
+
+`timeoutMs` can't exceed the server's `WARDBY_TOOL_MAX_TIMEOUT_MS` (default `300000`); a larger
+value is refused with an error naming the ceiling. If you need more, ask the operator to raise it.
+If the operator lowers the ceiling, a tool with a larger `timeoutMs` runs with the ceiling.
+
+Runs that started before the change keep the limit they loaded; the next run uses the new one.
+
+See [Use native agents, tools, and data](../native-capabilities.md#tool-time-limits).