@wardby/cli 0.7.0 → 0.9.0

package/docs/debugging-agent-runs.md

@@ -0,0 +1,354 @@
+# Debugging an agent run
+
+You can triage most agent problems yourself with the Wardby MCP and GitHub. Only
+some failures need someone with server logs.
+
+## Start here
+
+Find the run with `list_runs`, then read it with `get_run`. Then go to the section
+for what you see.
+
+```mermaid
+flowchart TD
+    start["Find the run: list_runs, then get_run"]
+    start --> none["No run started<br/>Check the repo links and triggers"]
+    start --> failed["Failed or refused<br/>Read failureCategory and the final text"]
+    start --> nopr["Succeeded, no PR<br/>Read outcome in codingResult"]
+    start --> missed["PR, but it missed<br/>Read the diff and the review"]
+    none --> nopull["See: No pull request appeared"]
+    nopr --> nopull
+    failed --> runfailed["See: The run failed"]
+    missed --> didntfix["See: The agent didn't fix what you expected"]
+    runfailed -- still unexplained --> operator["See: When you need an operator"]
+    nopr -- why it decided that --> transcript["See: Run transcripts"]
+    missed -- why it decided that --> transcript
+```
+
+## What you can use without server access
+
+These all work through the Wardby MCP or GitHub, and you only see runs you have
+access to.
+
+| Tool                                                                                                            | What it tells you                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_runs` (agent id, optional `status`)                                                                       | An agent's recent runs: status, trigger, cost, turns, final text, and which run started it                                                                                                                                                                                                                                                                                               |
+| `list_runs` without an agent id (from 0.8.0)                                                                    | Your runs across every agent, each with `agentName`; no final text. `active: true` or `since` (ISO time) narrow it                                                                                                                                                                                                                                                                       |
+| `get_run` (run id)                                                                                              | One run in full, adding `failureCategory`, `diagnosticId`, `codingResult.outcome`, `request`, budget events and package refusals                                                                                                                                                                                                                                                         |
+| `triggerInfo`, `outcomes`, `serviceReadiness` (from 0.8.0, on `get_run` and on `list_runs` without an agent id) | What started the run (the pull request and whether it was a review or a mention, the issue, the schedule or the lead), what it produced (pull requests opened, comments, checks) and each service's state, in the admin viewer API's shapes. Follow a pull request from the run that opened it through its review and fix rounds by matching one run's outcome to the next run's trigger |
+| `get_agent`, `list_repositories`, `list_subagents`                                                              | How the agent is set up: prompt, model, budget, repo links and triggers, sub-agents                                                                                                                                                                                                                                                                                                      |
+| `search_help`, `get_help_article`                                                                               | Help for an error code or failure category                                                                                                                                                                                                                                                                                                                                               |
+| `cost_report`                                                                                                   | What runs cost, when spend is the question                                                                                                                                                                                                                                                                                                                                               |
+| `get_run_steps` (from 0.9.0)                                                                                    | The run's steps, one line per tool call or model message, live while it runs; see [Run steps](#run-steps)                                                                                                                                                                                                                                                                                |
+| `get_run_transcript`                                                                                            | The run's conversation, for Claude Code runs with `sessionResume` on                                                                                                                                                                                                                                                                                                                     |
+| `stop_run`                                                                                                      | Stops a run that's stuck                                                                                                                                                                                                                                                                                                                                                                 |
+| The PR, issue or Jira ticket                                                                                    | The diff, CI, the review, and the comment the run posted                                                                                                                                                                                                                                                                                                                                 |
+
+From Wardby 0.8.0, `list_agents` with `summary: true` returns each agent's id,
+name, kind, model, coding provider, budget, owner and your access, without the
+prompt and coding profile. Admins (the `admin` role, `admin:view` scope) can add
+`all: true` to `list_agents` or `list_runs` to see every agent or run in the
+deployment.
+
+Admins can also use the [Wardby Viewer](viewer-api.md), a desktop app showing runs,
+sub-agent trees, triggers and outcomes for every owner.
+
+## The run failed
+
+Call `get_run` and read `status`, `error`, `failureCategory` and the final text. A
+failed coding run's `error` looks like
+`coding_failure_repo_access:coding_diag_…`: the middle part is the stage that
+failed, and the ID is what an operator searches for.
+
+| What you see                    | Likely cause                                              | What to do                                                           |
+| ------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------- |
+| `repo_access`                   | The agent's owner lost access, or a repo link was removed | Check `list_repositories` and the owner's GitHub access              |
+| `repo_access_unavailable`       | GitHub couldn't be reached reliably                       | Try again later                                                      |
+| `workspace`                     | Often a workspace disk size above the server's limit      | Lower `workspaceDiskMb`, or ask an operator to raise the limit       |
+| `executor` while running checks | The run may have run out of memory, among other causes    | Reduce what the checks run; send the ID to an operator if it repeats |
+| `merge_conflict`                | The branch conflicts with its target                      | Read the `merge-conflict` help article                               |
+| `service_unready`               | A service the run needs, such as Postgres, didn't start   | Check `.wardby/services.yaml` and the agent's `services`             |
+| `coding_turn_limit`             | The run used all its turns                                | Raise `maxTurns` or narrow the task                                  |
+| `budgetEvents`, or `refused`    | The run, run tree or budget group ran out of money        | Raise the budget or check spend with `cost_report`                   |
+| `packageRefusals`               | A package isn't allowed or is too new                     | Add it to `packageAllowlist`, or wait out the release age limit      |
+
+For anything else, call `search_help` with the code or category. If that doesn't
+explain it, see [When you need an operator](#when-you-need-an-operator).
+
+**Prompt for Claude Code:**
+
+```
+Wardby run <run id> failed. Why, and what can I do about it?
+If it needs server logs, give me the diagnosticId.
+```
+
+## No pull request appeared
+
+First find out whether a run started, using `list_runs` on the lead or router,
+then on the coding agent.
+
+| What `list_runs` shows           | What it means                                                                                              | What to do                                                                                      |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| No new run                       | The request never started anything: nothing is linked with that trigger, or the person doesn't have access | Check `list_repositories` on the router. Only one agent per repo can hold the `mention` trigger |
+| Lead ran, no coding run under it | The lead chose not to delegate                                                                             | Read the lead's final text, which should say why                                                |
+| Coding run failed or was refused | See [The run failed](#the-run-failed)                                                                      |                                                                                                 |
+| Coding run succeeded, with no PR | Check `codingResult.outcome` in `get_run`                                                                  | See below                                                                                       |
+
+| `outcome`          | Meaning                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `no_changes`       | The agent changed nothing. Its final text should say why: the request may be vague or already done. On Claude Code, the transcript shows how it decided |
+| `budget_exhausted` | It ran out of money before finishing. Raise the budget or narrow the task                                                                               |
+| `branch_pushed`    | A local repo: there's a branch, and no PR by design                                                                                                     |
+
+A mention can also get no reply at all. If a server sets
+`WARDBY_MENTION_EXPLANATIONS=false`, a mention that starts nothing stays silent. An
+operator can look for `mention ignored` or `mention declined` in the server log.
+
+**Prompt for Claude Code:**
+
+```
+I asked Wardby agent <agent name> to <request> in <your-org/your-repo>,
+and no pull request appeared. Why?
+```
+
+## The agent didn't fix what you expected
+
+The run succeeded, so most of what you need is on the PR and the run, with no
+server logs involved. Check these in order:
+
+1. **The diff:** what actually changed.
+2. **The PR description:** the run's final text, including what it says it tested.
+   If it says the tests weren't run, trust CI.
+3. **The review:** whether your review check caught the miss.
+4. **The request:** whether the issue or mention said what you meant.
+5. **The task the agent received:** `request` in `get_run` (from Wardby 0.8.0). On a
+   delegated run, this shows what the lead told the coding agent.
+6. **The transcript:** why it decided that. This is only for Claude Code runs with
+   `sessionResume` on.
+
+The usual causes are a vague request, a lead that dropped something when it rewrote
+the request, a repo rule missing from `AGENTS.md`, or a fix aimed at the symptom it
+was told about.
+
+**To fix it,** comment on the PR, mentioning the App, with what's wrong. The
+follow-up pushes to the same branch and PR, so you don't start again. If the same
+miss keeps happening, add the rule to `AGENTS.md` so future runs follow it.
+
+**Prompt for Claude Code:**
+
+```
+PR <PR URL> from Wardby didn't do what I expected: <what you expected>.
+Where did it go wrong? Draft a follow-up comment, but don't post it.
+```
+
+## Run steps
+
+While a run runs, Wardby records its steps: one line for each tool call (the
+tool, and its command, file or first argument, cut to about 100 characters) with
+its status once the result is back (`ok`, `error`, or `exit N`), and one line for
+what the model said (cut to about 120 characters). At the default level, tool
+output and full text are never recorded; see Levels below. Steps are recorded
+for native runs (in the control plane and on the native sandbox) and for Claude Code and Codex runs. Every agent's
+shell command shows as `Bash` (a native `run_command`, Claude Code's command tool,
+Codex's `exec_command`, `shell`, `local_shell` and `shell_command`), another tool
+under its own name (for example `apply_patch`), and a remote MCP tool as
+`mcp:<tool>`. A Claude Code or Codex run's final answer is one `said` step: the
+start of the summary it returned, or `Finished` with the outcome (for example
+`Finished: changes ready`) when it returned none.
+
+For Claude Code and Codex, the coding proxy reads the steps from the model's
+replies after relaying them and posts them to the server's run-steps listener
+(`POST /internal/run-steps`). A slow or unreachable listener loses steps, never
+slows the run. Without the two settings in the table below, coding runs record no
+steps; native runs are unaffected. Steps for a Claude Code or Codex run need the
+listener, which only `wardby serve` runs.
+
+**Levels.**
+
+| Level     | Tool input           | Tool result                             | Model text           |
+| --------- | -------------------- | --------------------------------------- | -------------------- |
+| `off`     | -                    | -                                       | -                    |
+| `summary` | about 100 characters | status only (`ok`, `error`, `exit N`)   | about 120 characters |
+| `detail`  | up to about 4 KB     | status and the last ~2 KB of its output | up to about 8 KB     |
+
+At `summary`, the default, tool output is never recorded. At `detail` each step
+also keeps a **detail** text, at most 16 KB. When the output is cut at the
+start, the partial first line is dropped if it ends within 256 characters;
+otherwise only the first 256 characters are dropped, so a long single-line
+output, such as a JSON result, keeps about its last 1.8 KB. At every level,
+terminal escape sequences (colour codes, links, clipboard writes, title changes)
+and every other control character except line breaks and tabs are removed from
+step text before it is stored.
+
+A run's level is the lower of two settings, fixed when the run is dispatched (a
+change reaches later runs only; lowering the ceiling also stops detail for runs
+already in flight):
+
+- the instance's ceiling, `WARDBY_RUN_STEPS` (default `summary`);
+- the agent's `runSteps` (`off`, `summary` or `detail`), set by the agent's
+  owner with `create_agent` or `update_agent`. Unset counts as `summary`. Set
+  `null` to clear it.
+
+So `detail` needs both the operator and the agent's owner. If `runSteps` asks
+for more than the instance allows, the value is stored, `update_agent` and
+`get_agent` say so in `warnings`, and runs record at the ceiling.
+
+> **Warning: `detail` stores tool output.** Before a step is stored, every
+> secret value the run was given is removed and anything shaped like a token or
+> key is masked. A secret that exists only inside a repository file, or another
+> source the run read, and that matches no known shape, is not known to Wardby
+> and can remain in the detail text. That is why detail is off unless both the
+> operator and the agent's owner ask for it. Turn it on only for agents whose
+> tool output you are prepared to keep for the retention period.
+
+**Reading them.** `get_run_steps` (`runId`, optional `after` and `limit`) lists
+them oldest first, 50 at a time and at most 200; pass the last `seq` you have as
+`after` to get only newer ones. `get_run` and `list_runs` without `agentId`
+include `lastStep`, the newest step as one line. Access is the same as
+`get_run`'s. At `detail`, `get_run_steps` also returns each step's `detail` to the agent's
+owner and to the person who started the run (and to the stdio operator); anyone
+else, including an admin who does not own the agent, gets the lines only.
+`lastStep`, the admin viewer API and its `step` events never include detail.
+The `wardby-runs` Claude Code pane shows them (see
+[Claude Code plugin](claude-code-plugin.md#using-the-pane)); the admin viewer API
+sends a `step` event for each one and lists a run's newest 200 in its detail
+(see [Viewer API](viewer-api.md)), and the Wardby Viewer app shows them in a
+**Steps** section.
+
+**Limits.** A run records at most 2,000 steps; `dropped` in `get_run_steps`
+counts the rest.
+
+**Secrets.** Every step is redacted before it is stored: every secret value of
+the run's agent (attached secrets, readable or brokered, and its MCP servers'
+secrets), the run's own capability and its registry token are replaced with
+`[REDACTED]`, then anything shaped like a token or key.
+If the agent's secrets can't be read at that moment, the step is not stored.
+
+**Retention.** Steps are deleted `RUN_STEP_RETENTION_DAYS` after they are
+recorded. The scheduler leader deletes expired steps at most every ten minutes. `get_run_steps` reports
+`expired` when a run finished more than `RUN_STEP_RETENTION_DAYS` ago and has no
+steps left.
+
+| Variable                  | Read by                                                                                                   | Default   | Meaning                                                                                                                                                                                          |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WARDBY_RUN_STEPS`        | `wardby serve`, `wardby scheduler`, `wardby run`, `wardby mcp`, `wardby native-gateway`, the coding proxy | `summary` | `off` records nothing; `summary` records the lines above; `detail` allows agents whose `runSteps` is `detail` to record detail. The ceiling for every run. Any other value stops start-up.       |
+| `RUN_STEP_RETENTION_DAYS` | `wardby serve`, `wardby scheduler`, `wardby run`, `wardby mcp`, `wardby native-gateway`                   | `30`      | Days to keep a step, a whole number from 1 to 3650. A change applies to steps recorded after it. Any other value stops start-up.                                                                 |
+| `WARDBY_RUN_STEPS_LISTEN` | `wardby serve`                                                                                            | unset     | `host:port` or `:port` of the run-steps listener the coding proxy posts coding runs' steps to. Unset: no listener. An invalid value stops start-up.                                              |
+| `WARDBY_RUN_STEPS_URL`    | the coding proxy                                                                                          | unset     | The listener's origin, for example `http://<server host>:8792`: `http` or `https`, no credentials, path, query or fragment. Unset: coding runs record no steps. An invalid value stops start-up. |
+
+The coding proxy also reads `WARDBY_RUN_STEPS`: with `off`, or with
+`WARDBY_RUN_STEPS_URL` unset, no step text leaves the proxy. For coding runs at
+`detail`, set `WARDBY_RUN_STEPS=detail` on the proxy too: below `detail`, the
+proxy never sends any tool output to the server. Set `WARDBY_RUN_STEPS=detail`
+on every process that writes steps (`wardby serve`, the scheduler, the native
+gateway and `wardby run`). The listener is a
+second network path into the server; see
+[Run steps in Security deployment](security-deployment.md#run-steps) for how to
+restrict it.
+
+**Upgrading.** The release adds the `RunStep` table, the `Run.stepsDropped`
+column, `Agent.runSteps`, `Run.runStepsLevel` and
+`CodingProxySession.runStepsLevel`; apply the migrations with
+`prisma migrate deploy` as with any upgrade. Runs started before the upgrade
+record at most `summary`.
+
+## Run transcripts
+
+A transcript is the run's conversation: the messages, the tool calls and their
+results, and the files and skills the agent loaded. You can get it yourself,
+without server access, on Claude Code agents.
+
+**To turn it on,** set `codingProfile.sessionResume` to `true` with `update_agent`.
+It's off by default and has to be turned on for each agent. It only applies to runs
+started afterward, so an earlier failure has no transcript. The server also needs a
+blob store, set in the environment of the process that launches coding runs:
+`BLOB_STORE` set to `local`, `gcs` or `s3`, plus `BLOB_STORE_LOCAL_DIR`,
+`BLOB_STORE_GCS_BUCKET`, or `BLOB_STORE_S3_BUCKET` and `BLOB_STORE_S3_REGION`.
+Without `BLOB_STORE`, no transcript is stored.
+
+**To read one,** call `get_run_transcript` with the run ID. It returns a download
+link that works for 10 minutes and a command. Run `npx @wardby/cli@latest resume -`
+in a clone of the repo and paste the link, which also lets you continue the session
+on your machine.
+
+| Transcripts        |                                                                                |
+| ------------------ | ------------------------------------------------------------------------------ |
+| **Who can read**   | Anyone who can read the run: the person who triggered it and the agent's owner |
+| **Stored for**     | Runs that finish, fail, or stop at their budget                                |
+| **Not stored for** | Runs stopped with `stop_run` or ended by their timeout                         |
+| **Removed**        | Thinking blocks, the system prompt, the worker's environment, account details  |
+| **Redacted**       | The agent's attached secrets and the run's own tokens                          |
+| **Not available**  | On Codex agents                                                                |
+
+Redaction removes secret values, not other sensitive text, so a transcript includes
+what the agent saw in the repo and in command output. Turn this on only for agents
+whose runs you're comfortable sharing with everyone who can read them.
+
+**Prompts for Claude Code:**
+
+To turn it on:
+
+```
+Turn on transcripts for Wardby agent <agent name>.
+```
+
+To get one:
+
+```
+Get me the transcript for Wardby run <run id>.
+```
+
+See [Resume Claude Code runs locally](../help/resume-runs-locally.md) for more.
+
+## When you need an operator
+
+Ask someone with server access when `get_run` and help don't explain a failure. The
+specific reason for a failed coding run is written only to the server log, under
+its `diagnosticId`.
+
+**Send them:** the run ID, the `diagnosticId`, the repo, and what you expected to
+happen.
+
+**What the operator can do:**
+
+1. Search the control-plane log for the `diagnosticId`, which holds the real reason.
+2. If that isn't enough, turn on the
+   [debug trace](coding-worker-isolation.md#debug-trace) with `debugTraceMinutes`
+   and reproduce the failure.
+
+The debug trace won't help you directly. Only admins can turn it on, it only covers
+runs started afterward, and its output goes to the run's worker log, which you can't
+read. It can include prompts and repo content, so it isn't exposed through MCP.
+
+**What the trace holds:** the agent's whole stream, the commands it ran with their
+output (Claude Code), final usage and duration, and stream failures in full.
+Token-shaped values are redacted. It stops at 2 MiB per run by default.
+
+**What MCP gives you:** the trace itself isn't available through MCP. You can only
+turn it on or off with `update_agent` (admin role), see when it expires with
+`get_agent` (`debugTraceUntil`), and see whether a run was traced with `get_run`
+(`debugTrace: true`).
+
+**Prompt to try first.** Paste this into any client connected to the Wardby MCP:
+
+```
+Wardby run <run id> didn't do what I expected. What happened, and what can I do?
+If it needs server logs, give me the diagnosticId.
+```
+
+## Known gaps
+
+Two things can't be answered without server access yet.
+
+| Gap                                     | Why it matters                                                       | What you can do                                                     |
+| --------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| The specific reason a coding run failed | You get the stage, such as `executor`, but not why                   | Send the `diagnosticId` to an operator                              |
+| Why a mention got no reply              | With explanations off, a declined mention leaves no reply and no run | Turn explanations on where that's acceptable: `true` is the default |
+
+**To turn explanations on,** an operator removes
+`WARDBY_MENTION_EXPLANATIONS=false` from the server's settings, or sets it to
+`true`, then redeploys. Once on, the GitHub App replies to say why a mention started
+nothing. On a public repo, anyone who can read that comment can see what is or isn't
+linked there.
+
+Run transcripts are limited to Claude Code runs with `sessionResume` on, so they
+don't help on Codex agents.

package/docs/getting-started-gke.md

@@ -218,6 +218,13 @@ App replying to say why a mention started nothing; pass it to `up.sh` on every
 run, the same way. See
 [What a linked review agent does](code-review-agents.md#what-a-linked-review-agent-does).
 
+`WARDBY_RUN_STEPS` (`off`, `summary` or `detail`) and `RUN_STEP_RETENTION_DAYS`
+(1 to 3650) are optional, not secrets. Pass them to `up.sh` on every run, the
+same way; unset keeps the server defaults (`summary`, 30 days). `up.sh` adds the
+ceiling to the control plane, the coding proxy and the native gateway, and the
+retention to the control plane and the native gateway. See
+[Run steps](debugging-agent-runs.md#run-steps).
+
 Generate `SECRET_APP_KEY` with:
 
 ```sh
@@ -401,9 +408,10 @@ server answers `415`, because it checks the content type before the token.
 Create the first self-hosted login credential. It is printed once.
 `--role admin` makes this operator account an admin. Only admins can use all
 the privileged operations: `make_owner`, BYO `workerImageRef`, package
-approval, service catalog changes, and model catalog changes. A
-`package-approver` can approve packages only, a `service-manager` can change
-the service catalog only, and a `model-manager` can change the model catalog
+approval, service catalog changes, model catalog changes, and host providers
+(`hosts:admin`). 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, and a `host-manager` can manage host providers
 only. Users created without `--role` have no roles. See
 [roles and privileged operations](security-deployment.md#roles-and-privileged-operations).
 
@@ -454,6 +462,14 @@ Desktop includes it). The images build concurrently, and the stages that only
 compile JavaScript run on your machine's own architecture, so building the
 `linux/amd64` images from an arm64 machine emulates only what actually ships.
 
+`up.sh` adds the cluster to your kubeconfig and makes it the current context, as
+`gcloud container clusters get-credentials` does. From then on it works from its
+own one-cluster copy of that context, so switching contexts in another terminal
+while a deploy runs doesn't send its later steps to a different cluster. The
+copy is readable only by you and is removed when `up.sh` exits. Don't run two
+deploys of the same cluster at once: the second stops at its first Helm step
+with `another operation (install/upgrade/rollback) is in progress`.
+
 A control-plane restart is designed not to drop requests, at the cost of a
 slower rollout. A new pod must stay Ready for three minutes before the old one
 is retired, because the load balancer can take well over a minute to start
@@ -585,7 +601,7 @@ delete the class and re-run `up.sh` to change them.
 
 ### Native sandbox
 
-Native sandbox requires Wardby 0.5.4 or later.
+Native sandbox requires Wardby 0.6.0 or later.
 
 `up.sh` deploys everything the [native sandbox](native-sandbox.md) needs on
 this cluster. It builds and pushes the `native-worker` image, checks it (Node is
@@ -655,8 +671,9 @@ control plane 1.
 **Sleeping.** Every minute the scheduler leader scales the coding proxy
 (`wardby-coding-proxy`) to 0 when no coding run is pending or running and none
 finished within the idle window. It scales the native gateway
-(`wardby-native-gateway`) to 0 when no sandbox native run is pending, running or
-recently finished and the gateway has no active session. Either target sleeps
+(`wardby-native-gateway`) to 0 when no sandbox native run and no coding run with
+MCP tools is pending, running or recently finished, and the gateway has no
+active session. Either target sleeps
 only once at least one idle window has passed since it was last woken (recorded
 in its `wardby.io/power-woke-at` annotation) and since the control plane
 started, whichever is later. The condition is checked again immediately before
@@ -664,10 +681,14 @@ scaling. The control plane
 logs `power: proxy slept (idle 30m)`.
 
 **Waking.** Starting a coding run scales the proxy to 1 and waits for a ready
-endpoint. Starting a sandbox run does the same for the gateway. The wait is at
+endpoint. Starting a sandbox run does the same for the gateway, and so does starting a
+coding run with MCP tools, whose MCP calls go through the gateway (0.9.0 and later): it wakes the
+proxy and gateway at once and fails before launch with
+[`coding_failure_mcp_gateway_unavailable`](../help/errors/coding-mcp-gateway-unavailable.md)
+if the gateway does not wake. The wait is at
 least 5 minutes, because a cold Autopilot node can add 1 to 2 minutes of
-start-up; a `KUBERNETES_READY_TIMEOUT_MS` (proxy) or
-`NATIVE_SANDBOX_READY_TIMEOUT_MS` (gateway) above 5 minutes, set on the
+start-up; a `KUBERNETES_READY_TIMEOUT_MS` (the proxy, and the gateway wake of a coding run) or
+`NATIVE_SANDBOX_READY_TIMEOUT_MS` (the gateway wake of a sandbox run) above 5 minutes, set on the
 control-plane Deployment, raises it to that value. The first coding run after a
 control-plane restart also runs the cluster preflight canary, because start-up
 preflight is deferred while the proxy sleeps (`kubernetes_preflight_deferred`).
@@ -689,8 +710,9 @@ the Viewer shows any such leftover as an old replica rather than a failure.
 **Sleeping now.** To skip the idle window (for example right after a test), an
 admin calls the MCP tool `power_sleep`, optionally with `target` set to `proxy`
 or `gateway` (default both). It scales the target to 0 at once, but never stops
-a run: a target with a pending or running run, or for the gateway an active
-gateway session, is left up and its run ids are returned under `blocked`.
+a run: a target with a pending or running run (for the gateway, a sandbox run
+or a coding run with MCP tools), or for the gateway an active gateway session,
+is left up and its run ids are returned under `blocked`.
 Recently finished runs do not block it. The next run wakes the target as usual.
 `power_status` shows each target's replicas, readiness, last wake time and
 blocking run ids. Both tools need the `power:manage` scope, which only the

package/docs/getting-started-identity-provider.md

@@ -54,26 +54,27 @@ access tokens for that audience.
 
 Create these scopes in the provider:
 
-| Scope                 | Capability                                                         |
-| --------------------- | ------------------------------------------------------------------ |
-| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.      |
-| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.  |
-| `runs:trigger`        | Start agent runs.                                                  |
-| `tools:write`         | Create, attach, and manage tools.                                  |
-| `datastore:write`     | Create, attach, query, and modify datastores.                      |
-| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                |
-| `webhooks:write`      | Create and manage webhook triggers.                                |
-| `budget_groups:write` | Create and manage shared budget groups.                            |
-| `packages:approve`    | Approve coding agents' package allowlists.                         |
-| `services:manage`     | Create, update and delete coding-run service catalog entries.      |
-| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.          |
-| `memory:write`        | Set and delete agent memory entries.                               |
-| `admin:view`          | Read every owner's runs through the admin viewer API; admins only. |
-| `models:admin`        | Add, override, disable and reset model catalog entries.            |
-| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only. |
+| Scope                 | Capability                                                                      |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `agents:read`         | Inspect agents, models, runs, memory, and attached resources.                   |
+| `agents:write`        | Create and modify agents, schedules, and sub-agent relationships.               |
+| `runs:trigger`        | Start agent runs.                                                               |
+| `tools:write`         | Create, attach, and manage tools.                                               |
+| `datastore:write`     | Create, attach, query, and modify datastores.                                   |
+| `secrets:write`       | Create, attach, rotate, and remove secret bindings.                             |
+| `webhooks:write`      | Create and manage webhook triggers.                                             |
+| `budget_groups:write` | Create and manage shared budget groups.                                         |
+| `packages:approve`    | Approve coding agents' package allowlists.                                      |
+| `services:manage`     | Create, update and delete coding-run service catalog entries.                   |
+| `agents:admin`        | Reassign agent ownership, BYO worker images; admins only.                       |
+| `memory:write`        | Set and delete agent memory entries.                                            |
+| `admin:view`          | Read every owner's runs through the admin viewer API; admins only.              |
+| `models:admin`        | Add, override, disable and reset model catalog entries.                         |
+| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only.              |
+| `hosts:admin`         | Register host providers and approve their tools; admins and host managers only. |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all fifteen in the provider even when
+may request every advertised scope. Define all sixteen in the provider even when
 policy grants a particular client or user only a subset. Ensure granted scopes
 are emitted in the access token's `scope` or `scp` claim; defining them only in
 the provider UI is not sufficient.
@@ -97,24 +98,29 @@ every advertised scope fail with `invalid_scope`.
 deployment, define it in the provider too and map it like `agents:admin`;
 otherwise clients that request every advertised scope fail with `invalid_scope`.
 
+`hosts:admin` was added after `power:manage`. When you upgrade an existing
+deployment, define it in the provider too and map it like `agents:admin`;
+otherwise clients that request every advertised scope fail with `invalid_scope`.
+
 ### Wardby roles
 
 A scope only delegates. `agents:admin`, `packages:approve`, `services:manage`,
-`admin:view`, `models:admin` and `power:manage` take effect only for a caller who also holds a Wardby role that grants them:
+`admin:view`, `models:admin`, `power:manage` and `hosts:admin` take effect only for a caller who also holds a Wardby role that grants them:
 
-| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
-| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                     |
-| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                         |
-| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                |
+| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog), `hosts:admin` (host providers) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
+| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                                                     |
+| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                                                         |
+| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                                                |
+| `host-manager`     | `hosts:admin` (`register_host_provider`, `approve_host_provider_tools`, `test_host_provider`; see [host-providers.md](host-providers.md))                                                                                                                                                                                                                      |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
 
 ```dotenv
 AUTH_ROLE_CLAIM=groups   # claim name or dotted path
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Wardby looks up `AUTH_ROLE_CLAIM` in two steps:
@@ -162,20 +168,20 @@ their next token.
 
 Provider examples:
 
-- **Okta** (custom authorization server): create four groups, `wardby-admin`,
-  `wardby-packages`, `wardby-services` and `wardby-models`. Add a `groups` claim
+- **Okta** (custom authorization server): create five groups, `wardby-admin`,
+  `wardby-packages`, `wardby-services`, `wardby-models` and `wardby-hosts`. Add a `groups` claim
   to the access token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage`.
-- **FusionAuth:** create four application roles, `admin`,
-  `package-approver`, `service-manager` and `model-manager`. They appear in the
+  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin`.
+- **FusionAuth:** create five application roles, `admin`,
+  `package-approver`, `service-manager`, `model-manager` and `host-manager`. They appear in the
   access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
-  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager`.
+  `AUTH_ROLE_MAP=admin=admin,package-approver=package-approver,service-manager=service-manager,model-manager=model-manager,host-manager=host-manager`.
 - **Keycloak:** create realm roles such as `wardby-admin`, `wardby-packages`,
-  `wardby-services` and `wardby-models`. Realm roles appear under
+  `wardby-services`, `wardby-models` and `wardby-hosts`. Realm roles appear under
   `realm_access.roles`. Set `AUTH_ROLE_CLAIM=realm_access.roles` and
-  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
+  `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager`.
   For client roles, use `resource_access.<client-id>.roles`. The
   [local Keycloak harness](../deploy/keycloak-test/README.md) sets this up.
 - **Auth0:** add the user's roles to the access token as a namespaced custom
@@ -236,7 +242,7 @@ AUTH_JWKS_URI=https://identity.example.com/your-tenant/.well-known/jwks.json
 AUTH_AUDIENCE=https://wardby.example.com/mcp
 # Optional: Wardby roles (see "Wardby roles" above).
 AUTH_ROLE_CLAIM=groups
-AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager
+AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager,wardby-hosts=host-manager
 ```
 
 Copy `AUTH_ISSUER` exactly from the token's `iss` claim or the provider's
@@ -272,7 +278,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all fifteen Wardby scopes.
+- `scopes_supported` contains all sixteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.

package/docs/getting-started.md

@@ -238,6 +238,13 @@ After connecting, try:
 > List my Wardby agents, show the latest run and its actual cost, then create a
 > new agent with a maximum budget of $0.50. Do not run it yet.
 
+From Wardby 0.8.0, Claude Code can also show your runs in a pane beside the
+chat. With `--client claude` or `both`, quickstart offers to install it
+(`--claude-plugin` installs it unattended, `--no-claude-plugin` skips the
+question); otherwise run `npx @wardby/cli@latest claude-plugin install`, then
+`/wardby-runs`. `wardby doctor` reports whether it is set up. See the
+[Claude Code plugin](claude-code-plugin.md) guide.
+
 ### Reasoning effort
 
 A native agent can set `effort` (`low`, `medium`, `high`, `xhigh`, or `max`)
@@ -464,6 +471,7 @@ help article.
 ## Next steps
 
 - [Agent recipes](agent-recipes.md)
+- [Claude Code plugin](claude-code-plugin.md): your runs beside the chat (0.8.0+)
 - [Runtime architecture](architecture-runtime.md)
 - [Coding-agent setup](coding-agent-setup.md) and its
   [local repositories](coding-agent-setup.md#local-repositories) section