@wardby/cli 0.6.0 → 0.8.0

package/docs/security-deployment.md

@@ -79,15 +79,16 @@ Scopes and roles do different jobs:
 - **Roles authorize.** A user has a set of roles. With no roles, the user is a
   member:
 
-| Role               | Grants                                                                                                 |
-| ------------------ | ------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage` |
-| `package-approver` | `packages:approve`                                                                                     |
-| `service-manager`  | `services:manage`                                                                                      |
-| `model-manager`    | `models:admin`                                                                                         |
-| (none)             | nothing privileged; every other scope works as the token allows                                        |
+| Role               | Grants                                                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin` |
+| `package-approver` | `packages:approve`                                                                                                    |
+| `service-manager`  | `services:manage`                                                                                                     |
+| `model-manager`    | `models:admin`                                                                                                        |
+| `host-manager`     | `hosts:admin`                                                                                                         |
+| (none)             | nothing privileged; every other scope works as the token allows                                                       |
 
-Eight operations are privileged:
+Nine kinds of operation are privileged:
 
 - `make_owner`, which reassigns any agent's owner, including another
   principal's private agent (see [Sharing agents](#sharing-agents) for what
@@ -107,7 +108,15 @@ Eight operations are privileged:
   [viewer-api.md](viewer-api.md));
 - reading low-power state and scaling the coding proxy and native gateway to
   zero now (`power_status`, `power_sleep`; see
-  [Low-power mode](getting-started-gke.md#low-power-mode)).
+  [Low-power mode](getting-started-gke.md#low-power-mode));
+- registering, approving, testing and deleting host providers
+  (`register_host_provider`, `approve_host_provider_tools`,
+  `test_host_provider`, `delete_host_provider`; reading one with
+  `get_host_provider` needs the same permission). Approved tools run on the
+  control plane with the provider's credentials, so grant `hosts:admin` like
+  `agents:admin`. Any host manager can read and re-register any provider,
+  including its tool code, whoever owns the tools; see
+  [host-providers.md](host-providers.md).
 
 Each needs **both** its scope on the token **and** a role that grants that
 permission:
@@ -119,13 +128,16 @@ permission:
 - The admin viewer API needs `admin:view`, which only the `admin` role grants.
 - `power_status` and `power_sleep` need `power:manage`, which only the `admin`
   role grants.
+- Host provider tools need `hosts:admin`, which the `admin` and `host-manager`
+  roles grant.
 
 In practice:
 
-- an `admin` can do all eight;
+- an `admin` can do all of them;
 - a `package-approver` can approve packages only;
 - a `service-manager` can change the service catalog only;
 - a `model-manager` can change the model catalog only;
+- a `host-manager` can manage host providers only;
 - a member can do none of them.
 
 Callers who fail the check get `403`:
@@ -266,8 +278,17 @@ so a tool a write-grantee attaches runs with none until you re-run
 the coding profile, kind and budget group; and sub-agents, since an edge
 would hand every run's data to another agent.
 
-**Everyone** can be granted at most `execute`: everyone-write would let
-anyone rewrite an agent that holds your tools and secrets.
+**Everyone** (any signed-in principal) can be granted up to `write`, a
+public agent anyone can list, run and edit, but only while the agent holds
+none of its owner's bindings: secrets, datastores, repositories, sub-agents,
+tool capabilities, or a coding repository (so a coding agent is never
+public-write). `grant_access` refuses everyone-`write` on an agent that has
+any, and the binding tools (`attach_secret`, `attach_datastore`,
+`link_repository` including an admin's `adminOverride`, `attach_subagent`,
+and `attach_tool` with capabilities) refuse to add one to an agent everyone
+can write, as `update_agent` refuses making it a coding agent. Otherwise anyone could
+rewrite the prompt of an agent that uses your secrets. Detach the bindings
+first, or grant everyone `execute` instead.
 
 **Nothing crosses owners without a grant on that exact resource**, checked
 when bindings are written and again at run time, so rows written before this
@@ -303,7 +324,7 @@ someone else's agent (it can adopt the agent first). An HTTP user whose
 subject equals `LOCAL_PRINCIPAL` is not the operator. **Admins** get no
 implicit access to others' agents: they can `list_access` any agent (incident
 response) and reassign one with `make_owner`, which removes bindings the new
-owner doesn't own, suspends tool capabilities the new owner never granted,
+owner doesn't own (secrets, datastores and MCP server attachments), suspends tool capabilities the new owner never granted,
 cuts sub-agent edges the new owner can't delegate, and, between two owners,
 resets every grant. Adopting an owner-less agent keeps its grants but lowers
 an everyone grant to `read` unless `keepEveryoneExecute` is set.
@@ -338,7 +359,7 @@ without their tools' capabilities. Operator runbook:
    printed for review, with the `attach_tool` call that re-grants any
    capabilities it had. The subject must already exist.
 4. `wardby grants prune-bindings` removes, and prints, every remaining
-   binding of one owner's secret or datastore to another owner's agent
+   binding of one owner's secret, datastore or MCP server to another owner's agent
    (already inert).
 5. `wardby grants migration-report > after.txt`.
 
@@ -371,6 +392,15 @@ Trust assumptions:
   owner enabled `allowWebhookTaskOverride`; the owner controls the tools,
   secrets and repository. A repository is a binding: only the owner (or an
   admin's explicit approval) sets it, never a `write`-grantee.
+- **A task can steer a coding agent to any repository on its list.** A caller
+  who may pass `repository` (for `trigger_agent`, the owner, or anyone when
+  `allowWebhookTaskOverride` is on; for a webhook, whoever created it, and only
+  when `allowWebhookTaskOverride` is on), and a lead that delegates to the
+  agent, can pick any listed repository, and the agent's one toolchain,
+  services and package allowlist apply to all of them. Keep the list small, and keep
+  repositories with different trust levels on separate agents. Refusals never
+  repeat the requested value, and a lead sees a sub-agent's list only when it
+  has the same owner or may choose (execute access and the opt-in).
 - **Owner-less agents never hold a repository**, even admin-approved: there is
   no owner whose GitHub access can be checked. Assign an owner first.
 - **Checked where it's used.** Every coding run (before its workspace is
@@ -513,20 +543,22 @@ records. Delete them (see pruning above) if you want the rollback to be final.
 
 ## Resource and networking limits
 
-| Surface                        | Limit                                             |
-| ------------------------------ | ------------------------------------------------- |
-| MCP/webhook bodies             | 1 MiB raw bytes                                   |
-| Auth bodies                    | 64 KiB raw bytes                                  |
-| Request completion / headers   | 15 seconds / 10 seconds                           |
-| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects, 8 seconds |
-| Bridge input / output          | 1 MiB / 12 MiB                                    |
-| Parser input / console payload | 256 KiB / 16 KiB                                  |
-| HTML links extracted           | 1000, with incremental result-byte accounting     |
-| Random bytes                   | 65,536 bytes                                      |
-| Host calls                     | 256 per invocation, at most 8 pending             |
-| Datastore value / keys listed  | 1 MiB / 1000                                      |
-| Datastore key / secret name    | 1024 bytes                                        |
-| New secret plaintext           | 64 KiB                                            |
+| Surface                        | Limit                                            |
+| ------------------------------ | ------------------------------------------------ |
+| MCP/webhook bodies             | 1 MiB raw bytes                                  |
+| MCP tool-call arguments        | 100,000 array elements and object members        |
+| Auth bodies                    | 64 KiB raw bytes                                 |
+| Request completion / headers   | 15 seconds / 10 seconds                          |
+| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds (see below) |
+| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects           |
+| Bridge input / output          | 1 MiB / 12 MiB                                   |
+| Parser input / console payload | 256 KiB / 16 KiB                                 |
+| HTML links extracted           | 1000, with incremental result-byte accounting    |
+| Random bytes                   | 65,536 bytes                                     |
+| Host calls                     | 256 per invocation, at most 8 pending            |
+| Datastore value / keys listed  | 1 MiB / 1000                                     |
+| Datastore key / secret name    | 1024 bytes                                       |
+| New secret plaintext           | 64 KiB                                           |
 
 Oversized or malformed input fails explicitly. Existing oversized datastore
 values/keys and secret ciphertext fail instead of entering Node allocations.
@@ -535,6 +567,27 @@ and pins the validated DNS result to the connection while retaining Host and
 TLS verification. Cross-origin redirects remove credentials, including custom
 API-key headers; forwarding a request body across origins is rejected.
 
+Every sandbox invocation, including the one that validates a custom tool's
+call arguments against its `paramsZod`, runs in a fresh QuickJS runtime with the
+heap, stack, and time limits above. One that hits a limit fails that tool call
+only: the model receives a `validation_failed` or sandbox error result and the
+run continues. The invocation runs on the thread of the process that hosts the
+run (the server, or the run's worker with the native sandbox). Code that keeps
+the thread busy is also stopped by the instruction budget, so a long time limit
+mostly lets a call wait on slow requests.
+
+For this release only, a custom tool's `paramsZod` is compiled with Zod 4's
+built-in Zod 3 API (`zod/v3`) so that existing tools keep working; see
+[native capabilities](../help/native-capabilities.md). `zod/v3` does not have
+the fix for GHSA-mrhx-c7xc-m3w5: given an array, set, or map larger than its
+`.max()`, it still checks every element and records an issue for each bad one.
+For a tool's arguments that work stays inside the sandbox limits above, the same
+limits that bound the tool's own code. Wardby's own validation uses Zod 4. A
+tool whose schema the next release (Zod 4 only) would reject is flagged with a
+`warnings` list in `create_tool`, `update_tool`, `dry_run_tool`, `list_tools`
+and `get_agent` results (on tools the caller owns) and in one server log line
+per tool at startup; a warning names only the tool and the removed Zod 3 methods.
+
 Every resolved address must be global. A tool's own `allowedHosts` only
 narrows egress; it never opens a private, loopback or link-local destination.
 Only the operator's `WARDBY_FETCH_ALLOWED_HOSTS` (exact normalized hosts) can,
@@ -547,7 +600,7 @@ The network layer cannot back this up for the control plane on GKE, because
 Workload Identity needs the metadata server.
 Sandbox code can explicitly log secrets it has been given; log size limits do
 not provide automatic redaction. Keep tool-authoring privileges restricted.
-Public/non-owner tool listings expose only id/name/description; owners retain
+Public/non-owner tool listings expose only id/name/description/timeoutMs; owners retain
 their source and schema. Private agents are indistinguishable from missing IDs.
 
 Cancellation stops bridge delivery, sleep timers, and in-flight network work.
@@ -560,6 +613,57 @@ bound connection pools and concurrent invocations, and review a cancellable
 database adapter or isolated worker if strict immediate termination is required.
 Do not claim these per-invocation caps establish a whole-process memory ceiling.
 
+### Tool time limits
+
+A tool call has 10 seconds unless the tool sets its own `timeoutMs`
+(`create_tool`, `update_tool`, `dry_run_tool`, `wardby tool create|update
+--timeout-ms`, or `timeoutMs` in a bundle's `config/tools.json`). The limit
+covers the whole call: each `fetch` may run until it, and a timer can't be set
+for longer. A call never outlasts its run: stopping the run aborts it, and a
+sandboxed run's deadline cuts it off.
+
+| Variable                     | Default  | Meaning                                                                                                                                                                                                                                 |
+| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_TOOL_MAX_TIMEOUT_MS` | `300000` | The longest `timeoutMs` a tool may set, in milliseconds (at least `10000`). A larger value is refused when the tool is saved. A run uses the lower of the tool's `timeoutMs` and this value, so lowering it also covers existing tools. |
+
+Set it on every process that runs tools or serves the native sandbox gateway:
+`wardby serve`, `wardby scheduler` and the gateway. An invalid value stops
+start-up. On the native sandbox the gateway gives each of a tool's host calls
+its limit plus 20 seconds, never past the run's deadline. A long limit lets one
+call hold its run (and a sandboxed run's worker) for longer, so raise the
+ceiling only as far as your tools need.
+
+**Upgrading:** the release adds the nullable `Tool.timeoutMs` and
+`HostProviderOperation.timeoutMs` columns; apply the migration with
+`prisma migrate deploy` as with any upgrade. A sandboxed run passes a tool's
+`timeoutMs` to its worker, so update the native worker image together with the
+server: an older image refuses the run of an agent that has a tool with
+`timeoutMs`. Tools without `timeoutMs` run on either image.
+
+### Remote MCP servers
+
+Owners can register a remote MCP server (Streamable HTTP, HTTPS only) and attach
+an allowlisted subset of its tools to a native agent, which then calls them
+through Wardby's control plane. `WARDBY_MCP_SERVERS` decides who may register
+servers: `owners` (the default), `admins` (only `hosts:admin` holders), or `off`
+to disable the feature. An agent can use a server only while its owner owns it or
+holds `use` on it through a grant; revoking or lowering that grant detaches it. Secret values for a server are never sent to the model,
+stored in run records, or returned by Wardby's MCP tools. See [Remote MCP servers](mcp-servers.md) for the
+full guide.
+
+Claude Code and Codex agents can use attached servers too. Their workers reach
+the tools only through the coding proxy's `/mcp` route, which forwards to the
+native sandbox gateway's `/coding-mcp` route; the proxy never sees a server's URL
+or secrets. Codex agents get only tools the server marks `readOnlyHint: true`
+(see [Coding worker isolation](coding-worker-isolation.md#remote-mcp-tools)).
+
+| Variable                       | Read by                                                                                                  | Default       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_MCP_SERVERS`           | the server processes and the gateway                                                                     | `owners`      | Who may register remote MCP servers: `owners` (the default: owners may register servers), `admins` (registering, updating and refreshing a server needs `hosts:admin`), or `off` (every MCP-server tool except `detach_mcp_server` and `delete_mcp_server` is refused with a 403 that names this variable, and attached servers' tools are left out of runs). Any other value stops start-up.                                                                                                                 |
+| `WARDBY_MCP_MAX_CALLS_PER_RUN` | the native gateway, which counts calls; also checked at start-up by the server processes and the gateway | `100`         | The most remote MCP tool calls one coding run (Claude Code or Codex) may make. Every call to one of the run's MCP tools counts, whatever its outcome; a call past the limit is refused with the [`mcp_call_limit`](../help/errors/mcp-call-limit.md) error, which the agent sees as the tool's result. A positive whole number; any other value stops start-up.                                                                                                                                               |
+| `WARDBY_MCP_GATEWAY_URL`       | the coding proxy                                                                                         | unset         | The native sandbox gateway's base URL, for example `http://<gateway host>:<port>`. The proxy's `/mcp` route, which a coding run's worker uses as its MCP server, forwards each request to the gateway's `/coding-mcp` route; the proxy never sees an MCP server's URL or credentials. Unset, coding runs get no MCP tools: `/mcp` answers `503` with [`mcp_unavailable`](../help/errors/mcp-unavailable.md). An `http` or `https` URL without credentials, query or fragment; any other value stops start-up. |
+| `WARDBY_MCP_TOKEN`             | the coding worker                                                                                        | set by Wardby | Don't set it. Wardby gives each coding run whose agent has MCP tools its own MCP token in this worker variable. It is valid only for the proxy's `/mcp` route, and only while the run is active and before its deadline; only its hash is stored, and it is never logged.                                                                                                                                                                                                                                     |
+
 ## Slack workflow notifications
 
 This integration requires Wardby 0.6.0 or later.
@@ -748,6 +852,12 @@ packages, both forced to patched versions by `overrides` in `package.json`:
   re-run `prisma generate`, `prisma validate`, the `migrate diff` drift check,
   and the migration image's `migrate deploy`.
 
+ESLint and `typescript-eslint` still ask for `minimatch` 10, which is flagged
+(GHSA-g3hv-75wg-m249, moderate, fixed in 11.0.1), so `overrides` also forces
+`minimatch` to 11.0.3. It is development-only and never reaches a production
+image. After changing it, confirm `npm run lint` checks the same files and
+still reports problems.
+
 `scripts/security-audit.mjs` carries no exceptions: with the overrides the full
 and production audits are clean, and if a lockfile change ever dropped one, the
 advisory would reappear and the security job would fail.

package/docs/slack-notifications.md

@@ -12,20 +12,24 @@ wardby exposes no new inbound endpoint for it.
 
 ### Events
 
-Six kinds of lifecycle event can post to a linked channel:
-
-| Kind              | Posts when                                                                           | Content                                                                      |
-| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| `issue_picked_up` | A Jira event starts a run on a linked issue                                          | Issue key, title, and link; agent name; trigger kind                         |
-| `run_failed`      | A top-level run ends `failed`, `refused`, `budget_exhausted`, `cancelled`, or `lost` | Agent name, status, a short first-line reason (never the full error)         |
-| `pr_opened`       | A coding run opens a pull request                                                    | Repository#number and link, the issue it is for, any Jira status move        |
-| `review_posted`   | wardby's own review check posts a verdict                                            | `APPROVE` / `CHANGES_REQUESTED` / `COMMENT`, the reviewer agent, the PR link |
-| `review_fix`      | An automatic [fix round](../help/review-fix-rounds.md) starts or hits the cap        | Round number of the cap, started or capped                                   |
-| `pr_closed`       | A pull request is merged or closed                                                   | Merged or closed, any Jira status move                                       |
-
-A run finishing successfully is not its own event — on the workflow it shows
-up as `pr_opened` or `review_posted` already. Child coding runs started by a
-parent surface through the parent's own `run_failed`, not their own.
+Eight kinds of lifecycle event can post to a linked channel:
+
+| Kind               | Posts when                                                                                                                                     | Content                                                                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issue_picked_up`  | A Jira event starts a run on a linked issue                                                                                                    | Issue key, title, and link; agent name; trigger kind                                                                                                     |
+| `run_failed`       | A top-level run ends `failed`, `refused`, `budget_exhausted`, `cancelled`, or `lost`                                                           | Agent name, status, a short first-line reason (never the full error)                                                                                     |
+| `run_blocked`      | A top-level run succeeds without a pull request, but a coding child refused packages and made no changes or failed                             | ⛔ Blocked status, refused packages, and code-specific fixes                                                                                             |
+| `pr_opened`        | A coding run opens a pull request                                                                                                              | Repository#number and link, the issue it is for, any Jira status move                                                                                    |
+| `review_posted`    | wardby's own review check posts a verdict                                                                                                      | `APPROVE` / `CHANGES_REQUESTED` / `COMMENT`, the reviewer agent, the PR link                                                                             |
+| `review_fix`       | An automatic [fix round](../help/review-fix-rounds.md) starts or hits the cap                                                                  | Round number of the cap, started or capped                                                                                                               |
+| `pr_closed`        | A pull request is merged or closed                                                                                                             | Merged or closed, any Jira status move                                                                                                                   |
+| `packages_audited` | A top-level run ends (any status) and its coding children installed anything under [package audit mode](coding-packages.md#package-audit-mode) | The mode, up to ten package names to approve, any names of unknown relation listed apart, and counts of their dependencies and of advisories served past |
+
+A successful run normally shows up as `pr_opened` or `review_posted`. A run
+blocked by package refusals instead emits `run_blocked`, once per run, using
+the same rule and guidance as [status comments](../help/status-comments.md): a
+run that answered, or worked around a refusal, is not blocked. Child
+coding runs surface through their parent's events.
 
 Some runs do not post `run_failed` at all:
 
@@ -34,13 +38,24 @@ Some runs do not post `run_failed` at all:
 - a review verdict or failure from a coding agent acting as the reviewer, and
 - runs started from the `wardby run` CLI command.
 
+`pr_opened` and `pr_closed` also post for a pull request opened from a GitHub
+issue mention, the same as for a Jira issue: GitHub issues record the pull
+requests opened for them. The thread is the issue's, one per GitHub issue
+(`issue:github:owner/repo#N`) however many pull requests it has, not one per
+pull request. Once a pull request is recorded for the issue, its
+`review_posted` and `review_fix` events reply in that thread too. The run
+events (`run_failed`, `run_blocked`, `packages_audited`) of a run a GitHub
+issue mention started are not tied to the issue and post in a thread of
+their own.
+
 A pull request linked to several issues posts `pr_opened` and `pr_closed`
 only to the first linked issue's thread.
 
 ### Threads
 
-Each channel gets one thread per card: one per Jira issue (when the event has
-one) or one per pull request (when it doesn't). The first event for a card
+Each channel gets one thread per card: one per issue (a Jira issue, or the
+GitHub issue a pull request was opened from) when the event has one, else one
+per pull request. The first event for a card
 posts a parent message naming the issue or pull request; every later event
 for the same card is a reply in that thread, and the parent is kept updated
 with a short status line. The statuses are:
@@ -55,14 +70,15 @@ with a short status line. The statuses are:
 | `fix rounds exhausted` | fix rounds reaching the cap with changes still requested         |
 | `merged ✅`            | the pull request merged                                          |
 | `closed`               | the pull request closed without merging                          |
+| `blocked ⛔`           | `run_blocked`                                                    |
 | `failed ❌`            | `run_failed`                                                     |
 
-A `COMMENT` review leaves the status as it was. `merged ✅` and `closed` stick:
+A `COMMENT` review and `packages_audited` leave the status as it was. `merged ✅` and `closed` stick:
 a late review, fix round, failure, or repeated close does not change them.
 Only a new start does — the card picked up again, or a new pull request
 opened for it — which sets `picked up` or `PR open` again.
 
-Most events only post as a thread reply. A merge and a top-level run failure
+Most events only post as a thread reply. A merge, a blocked run, and a top-level run failure
 also post to the channel itself, so they are visible without opening the
 thread.
 
@@ -104,7 +120,7 @@ is not paused up front. Delivery pauses when the first actual delivery fails
 authentication (see [Failure modes](#failure-modes)).
 
 With `WARDBY_SLACK_CUSTOMIZE=true`, a message about an event that names an
-agent (`issue_picked_up`, `run_failed`, `review_posted`) is posted under that
+agent (`issue_picked_up`, `run_failed`, `run_blocked`, `review_posted`, `packages_audited`) is posted under that
 agent's name; every other message, and every message when the option is off,
 posts as `wardby`. A thread's parent message uses the name of the event that
 started the thread. wardby sets no icon.

package/docs/tool-secrets.md

@@ -157,6 +157,9 @@ or that the tool is not granted, fails with
 [`secret_brokered`](../help/errors/secret-brokered.md), so update tools that read
 the value to use `fetch` instead.
 
+A host provider's credentials must be brokered secrets, placed in a header or
+query parameter. See [host-providers.md](host-providers.md).
+
 ## What the host enforces
 
 - **https only**, to the default port. Any other scheme or port is refused with
@@ -235,18 +238,50 @@ request. Choose destinations with that in mind:
 - Brokering does not change who can attach tools or grant secrets. Keep
   `allowedSecrets` and `allowedHosts` narrow on each attachment.
 
+## Secret values are never stored
+
+Wardby refuses to store a secret's value anywhere it could be read back. A
+datastore or agent memory write (from a tool in either run mode, from the MCP
+`datastore_set` or `set_agent_memory` tools, or from a bundle import) is refused
+with [`secret_in_value`](../help/errors/secret-in-value.md) when the value or the key
+contains the value of a secret attached to the agent. The error names the
+secret, and nothing is stored. Store the secret's name and read the secret when
+it is needed, with `secrets.get` or `fetch(url, { secrets })`.
+
+- Matching is by exact value, including JSON-escaped forms and, for brokered
+  secrets, the encoded forms the broker scrubs. Values shorter than 6
+  characters are not matched.
+- If the agent's secrets cannot be read to check a value, the write is refused
+  with [`secret_check_unavailable`](../help/errors/secret-in-value.md) and nothing
+  is stored.
+- A bundle import skips a seeded datastore entry (per-agent or shared) whose key
+  or value contains an attached secret's value and reports a warning that names
+  the secret; the entry's key is withheld from the warning.
+- A native run's final text and error, and comments, reviews, and Jira posts
+  made through built-in tools, have attached secret values replaced with
+  `[REDACTED]`. So does the task text of a `delegate_to_*` call, using the
+  delegating agent's secrets, before the sub-agent's run is created, in both run
+  modes. If the secrets cannot be read when a run ends, its stored final text
+  and error are `[withheld: this text could not be checked for secret values]`.
+  A posting tool or `delegate_to_*` call that cannot read the secrets returns
+  `secret_check_unavailable` and posts nothing or creates no sub-agent run.
+- Values that are split, re-encoded, or otherwise transformed are not detected,
+  and values stored before this check existed are not scanned.
+
 ## Errors
 
-| Code                                                                                     | Meaning                                                                 |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [`secret_brokered`](../help/errors/secret-brokered.md)                                   | A tool read a brokered secret with `secrets.get`.                       |
-| [`secret_not_brokered`](../help/errors/secret-not-brokered.md)                           | `fetch` named a secret that is not brokered or not granted to the tool. |
-| [`secret_broker_destination_denied`](../help/errors/secret-broker-destination-denied.md) | The URL is not https, or its host, port, or path is outside the config. |
-| [`secret_broker_conflict`](../help/errors/secret-broker-conflict.md)                     | The request sets what a broker places, or brokers collide.              |
-| [`secret_broker_body_invalid`](../help/errors/secret-broker-body-invalid.md)             | Body placement needs a JSON-object or form-encoded body.                |
-| [`secret_broker_value_invalid`](../help/errors/secret-broker-value-invalid.md)           | The value is too short, or is not the JSON a SigV4 secret needs.        |
-| [`secret_broker_changed`](../help/errors/secret-broker-changed.md)                       | A removal link was created before the broker config last changed.       |
-| [`secret_broker_config_invalid`](../help/errors/secret-broker-config-invalid.md)         | The broker config failed validation.                                    |
+| Code                                                                                     | Meaning                                                                    |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [`secret_brokered`](../help/errors/secret-brokered.md)                                   | A tool read a brokered secret with `secrets.get`.                          |
+| [`secret_not_brokered`](../help/errors/secret-not-brokered.md)                           | `fetch` named a secret that is not brokered or not granted to the tool.    |
+| [`secret_broker_destination_denied`](../help/errors/secret-broker-destination-denied.md) | The URL is not https, or its host, port, or path is outside the config.    |
+| [`secret_broker_conflict`](../help/errors/secret-broker-conflict.md)                     | The request sets what a broker places, or brokers collide.                 |
+| [`secret_broker_body_invalid`](../help/errors/secret-broker-body-invalid.md)             | Body placement needs a JSON-object or form-encoded body.                   |
+| [`secret_broker_value_invalid`](../help/errors/secret-broker-value-invalid.md)           | The value is too short, or is not the JSON a SigV4 secret needs.           |
+| [`secret_broker_changed`](../help/errors/secret-broker-changed.md)                       | A removal link was created before the broker config last changed.          |
+| [`secret_broker_config_invalid`](../help/errors/secret-broker-config-invalid.md)         | The broker config failed validation.                                       |
+| [`secret_in_value`](../help/errors/secret-in-value.md)                                   | A datastore or memory write contains an attached secret's value.           |
+| [`secret_check_unavailable`](../help/errors/secret-in-value.md)                          | The write or posting could not be checked because secrets were unreadable. |
 
 See also the short help article
 [Brokered secrets](../help/brokered-secrets.md).

package/docs/viewer-api.md

@@ -13,6 +13,12 @@ the `admin` role.
 
 ## Access
 
+From an MCP client, an admin gets a deployment-wide listing without this API:
+`list_agents` and `list_runs` with `all: true` (Wardby 0.8.0 and later) need the
+same `admin:view` scope and `admin` role, and are refused otherwise. Their
+`triggerInfo` and `outcomes` fields have the same shapes as a graph run's
+`trigger` and `outcomes` here; `serviceReadiness` is `services` without `reason`.
+
 A caller needs an access token for the Wardby MCP resource that carries the
 `admin:view` scope, and the Wardby `admin` role. Send it as
 `Authorization: Bearer <token>`.

package/docs/viewer-api.openapi.yml

@@ -2,7 +2,7 @@
 openapi: 3.1.0
 info:
   title: wardby admin viewer API
-  version: 0.6.0
+  version: 0.8.0
   description: "Read-only admin API behind the wardby viewer: graph, run detail, infrastructure info and a live event stream. Response objects may gain new fields in later releases; clients should ignore unknown fields. See docs/viewer-api.md for the prose contract."
 servers:
   - url: https://{host}

package/help/admin-viewer.md

@@ -3,7 +3,7 @@ id: admin-viewer
 title: Watch live runs with the admin viewer API
 summary: Read-only, deployment-wide live view of runs, sub-agent trees, triggers, outcomes and coding-run services for admins (admin:view).
 audience: operator
-tags: [viewer, admin, runs, live, desktop, infrastructure, kubernetes, download, openapi, api contract]
+tags: [viewer, admin, runs, live, desktop, infrastructure, kubernetes, download, openapi, api contract, sign-in]
 appliesTo: ">=0.4.0"
 ---
 
@@ -19,6 +19,10 @@ It requires the Wardby `admin` role and the `admin:view` scope, which only the
 provider and map it like `agents:admin`. See
 [Configure identity and privileged access](identity-and-access.md).
 
+From an MCP client, an admin gets the same deployment-wide listing with
+`list_agents` and `list_runs` and `all: true` (Wardby 0.8.0 and later; also
+`admin:view`). Without the role the call is refused.
+
 Endpoints, all `GET`:
 
 - `/admin/api/graph?since=1h&limit=500`: a snapshot of runs in a time window.
@@ -36,6 +40,25 @@ your server's canonical URI, sign in with an `admin` user in the browser, and it
 shows the live graph. Each GitHub release has an unsigned macOS build of the viewer attached (see the README for opening it past Gatekeeper). Its README covers setup, and what an external identity
 provider client needs when the server runs in delegating mode.
 
+## Viewer sign-in with an external identity provider
+
+In delegating mode, the viewer signs in through your identity provider's
+public (native) client. That client must:
+
+- register the exact redirect URI `http://127.0.0.1:8585/callback`. The viewer
+  always listens on port 8585, and some providers (Okta, for example) match a
+  loopback redirect by its exact port, so a port-less or wildcard loopback
+  entry may not match;
+- allow the `admin:view` scope for the Wardby resource;
+- enable the refresh-token grant and allow the `offline_access` scope. The
+  viewer requests it so the provider returns a refresh token, and sign-in
+  fails with "server issued no refresh token" without one.
+
+The viewer prints its callback URL to stderr at startup. If sign-in reports
+that it could not open the local callback listener on `127.0.0.1:8585`,
+another program is using that port: close it and sign in again. In
+self-hosted mode the viewer registers itself, so there is no client to set up.
+
 From Wardby 0.6.0, admins can also sign in to a mobile app for the same read-only live view; see the help article `mobile-app`.
 
 The Infrastructure tab shows the Kubernetes pods where your deployment runs
@@ -44,7 +67,10 @@ requires a minimal read-only Kubernetes role. See the Infrastructure view
 section of the [viewer README](../apps/viewer/README.md#infrastructure-view) for
 setup. Its Map shows the request path (entry, protection layer such as Cloud
 Armor, routes), each NetworkPolicy with a plain-English summary, and on GKE a
-link from each pod to the Google Cloud console. The run graph's zoom controls
+link from each pod to the Google Cloud console. In low-power mode the sleeping
+coding proxy and native gateway show as asleep (with when they last woke), and
+a failed old replica next to a healthy one is greyed out rather than shown as a
+failure. The run graph's zoom controls
 include **Fit width**, which fills the canvas with the graph's width.
 
 From Wardby 0.6.0 the API is also published as OpenAPI 3.1 (`docs/viewer-api.openapi.yml` in the package), an API contract you can feed to client generators such as `openapi-typescript`.

package/help/agent-recipes.md

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