@wardby/cli 0.6.0 → 0.7.0

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/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-gateway-error.md

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

package/help/errors/native-sandbox-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-worker-exited.md

@@ -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/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-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/fix-merge-conflicts.md

@@ -0,0 +1,73 @@
+---
+id: fix-merge-conflicts
+title: Fix merge conflicts on a wardby pull request
+summary: Follow-up runs merge the PR's current target branch first and resolve its conflicts; ask to update a PR that fell behind.
+audience: operator
+tags: [github, pull-requests, merge-conflict, update-pr, target-branch, continuation, review_fix]
+appliesTo: ">=0.7.0"
+---
+
+# Fix merge conflicts on a wardby pull request
+
+Every follow-up run on a pull request a wardby coding run opened (a mention on
+the PR, a delegated `continuePriorRun`, a review fix round) first brings the
+branch up to date with the branch the pull request **currently** targets:
+
+1. Before the agent starts, wardby asks GitHub for the pull request's base
+   branch. A pull request retargeted since it opened (a stacked PR whose
+   parent merged, a release branch) merges its new base, not the one the
+   first run used.
+2. wardby fetches that branch from the same repository (never a fork) and
+   merges it into the workspace, in trusted code, before the agent sees it.
+   A branch that already contains its target is left exactly as it was.
+3. **No conflicts:** the agent works on the updated branch as usual.
+   **Conflicts:** the agent's task lists the conflicted files and which side
+   is which (this pull request's branch, then the target). It is asked to
+   resolve every conflict keeping both sides' intent, fix the tests the
+   combination broke, and run the repository's checks.
+4. The push is one merge commit authored by Wardby, with the pull request's
+   head and the target as its parents. It is pushed even when the agent
+   changed nothing else, so asking a wardby agent on the pull request to
+   "update this PR" or "fix the merge conflicts" is enough.
+5. The run's status comment on the pull request says what was merged, for
+   example "Merged `main` @ `1a2b3c4` into this branch; resolved conflicts
+   in 2 files."
+
+## Ask to update this PR
+
+Mention the wardby agent on the pull request with "please update this PR" or
+"please fix the merge conflicts". The follow-up merges the target branch,
+resolves any conflicts, and pushes the merge commit.
+
+## What is checked
+
+- **Conflict markers.** A file the merge left conflicted that still holds
+  conflict markers when the run finishes stops the push: the run fails with
+  category `merge_conflict` and nothing is pushed — see
+  [Conflict markers remain](errors/merge-conflict.md).
+- **Protected paths and size limits** apply to the agent's own changes,
+  measured against the automatic merge: a change the target branch made to a
+  protected path is merged as it is, while resolving a conflict in a protected
+  path, or reverting the target's change to one, is an edit by the agent and
+  is refused as usual (see [Protected path](errors/protected-path.md)).
+- **Someone else pushed meanwhile.** The push is still a fast-forward of the
+  head the run started from, so a push by anyone else in the meantime fails
+  the run the same way it did before, with nothing pushed.
+- **No merge base.** A target branch that cannot be fetched, or shares no
+  history with the pull request, fails the run before the agent starts — see
+  [Target branch could not be merged](errors/target-merge.md).
+
+## Limits
+
+- Local repositories (`local:`) have no pull requests, so a continuation there
+  is not merged with anything.
+- A conflicted file with no markers (a binary file, or one deleted on one side
+  and changed on the other) holds one side's version, or the changed version.
+  The agent is told to check it, but nothing stops it from leaving that version
+  as it is.
+- A conflict in a protected path cannot be resolved by the agent: resolving it
+  is an edit to that path, which is refused. Resolve that file by hand and push.
+
+Related: [Run GitHub code-review agents](code-review-agents.md),
+[Automatic review fix rounds](review-fix-rounds.md),
+[Related pull requests across repositories](related-pull-requests.md).