@wardby/cli 0.6.0 → 0.7.0

package/help/github-app-setup.md

@@ -0,0 +1,132 @@
+---
+id: github-app-setup
+title: Set up the GitHub App
+summary: Step by step, create Wardby's GitHub App, choose its events and permissions, install it on your repositories, and give the server its credentials.
+audience: operator
+tags: [github, github-app, setup, permissions, webhooks, GITHUB_APP_ID, GITHUB_APP_WEBHOOK_SECRET, link_host_account]
+appliesTo: ">=0.2.1"
+---
+
+# Set up the GitHub App
+
+Wardby reaches GitHub through a GitHub App that you create and own. Each Wardby
+server needs its own App, because an App has exactly one webhook URL. For an
+overview of how Wardby uses the App, see
+[Connect GitHub repositories](github.md).
+
+Decide first what the App is for:
+
+- **Coding agents only**, triggered with `trigger_agent` or on a schedule:
+  GitHub never calls your server, so you can skip the webhook (step 2) and the
+  events (step 4).
+- **Review agents, `@`-mentions, review fix rounds, merge watchers, or
+  marking pull requests ready**: these start from GitHub webhooks, so your
+  server must be reachable over public HTTPS at the host of
+  `MCP_CANONICAL_URI`.
+
+## 1. Create the App
+
+In the GitHub settings of the user or organization that will own it, open
+**Developer settings**, then **GitHub Apps**, then **New GitHub App**. Give
+it a name and a homepage URL. The owner matters: Wardby always serves the
+App's owner, and other accounts only when you list them (step 7).
+
+## 2. Webhook
+
+- **Webhook URL**: `https://<your-host>/hosts/github/events`, where
+  `<your-host>` is the host of `MCP_CANONICAL_URI`. Requests naming any other
+  host are rejected.
+- **Webhook secret**: a random value, for example from `openssl rand -hex 32`.
+  The same value goes into `GITHUB_APP_WEBHOOK_SECRET` (step 7). Until that
+  variable is set, the endpoint answers 404.
+
+For coding agents only, untick **Active** under Webhook instead.
+
+## 3. Repository permissions
+
+| Permission      | Access                                             |
+| --------------- | -------------------------------------------------- |
+| Contents        | Read and write (Read for an App that only reviews) |
+| Pull requests   | Read and write                                     |
+| Checks          | Read and write                                     |
+| Issues          | Read and write                                     |
+| Commit statuses | Read (optional)                                    |
+
+- **Contents: Read and write** lets coding agents push a branch for each pull
+  request. A review-only App can have Read, but its reviewers then can't
+  resolve their own fixed review threads.
+- **Checks** carries the `wardby review` and `wardby merge order` checks.
+- **Issues** covers mentions in issues and the labels used by
+  [automatic review fix rounds](review-fix-rounds.md).
+- **Commit statuses** lets reviewers see CI that reports commit statuses
+  rather than check runs.
+
+If you change permissions later, every installation must accept the new set
+before its webhooks resume.
+
+## 4. Events
+
+Tick each one; every event is its own checkbox.
+
+| Event                       | Needed for                                                                                                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Pull request                | `pull_request` reviewers and `review_fix`                                                                   |
+| Check run                   | Re-running the review check                                                                                 |
+| Check suite                 | Reviews that wait for CI (`waitForCi`), and `markReadyWhenPassing` marking a draft ready once CI goes green |
+| Issue comment               | `@`-mentions in issue and pull request comments                                                             |
+| Issues                      | `@`-mentions in a newly opened or edited issue                                                              |
+| Pull request review comment | `@`-mentions in inline review threads                                                                       |
+| Push                        | The `push` trigger (merge-watcher agents)                                                                   |
+
+Missing an event fails quietly: the matching trigger never starts. A common
+case is leaving out Check suite, so drafts that should be marked ready stay
+drafts.
+
+## 5. Account linking
+
+`link_host_account` lets a Wardby user prove which GitHub account they are, so
+Wardby can check their repository access. In the App's **General** settings:
+
+- **Callback URL**: `https://<your-host>/hosts/github/user-callback`.
+- Leave **Request user authorization (OAuth) during installation** unticked.
+- Note the **Client ID** (not the numeric App ID) and generate a **client
+  secret**.
+
+## 6. Private key and installation
+
+1. Save the App, note its numeric **App ID**, and generate a **private key**
+   (a `.pem` file).
+2. Under **Install App**, install it on your account or organization and
+   choose **Only select repositories**: pick only the repositories your agents
+   may use.
+
+## 7. Configure Wardby
+
+| Variable                         | Value                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------- |
+| `GITHUB_APP_ID`                  | The numeric App ID                                                          |
+| `GITHUB_APP_PRIVATE_KEY`         | The contents of the `.pem` file                                             |
+| `GITHUB_APP_WEBHOOK_SECRET`      | The webhook secret from step 2                                              |
+| `GITHUB_APP_CLIENT_ID`           | The Client ID from step 5 (set together with the client secret, or neither) |
+| `GITHUB_APP_CLIENT_SECRET`       | The client secret from step 5                                               |
+| `WARDBY_GITHUB_ALLOWED_ACCOUNTS` | Optional: accounts other than the App's owner to serve, comma-separated     |
+| `WARDBY_MENTION_EXPLANATIONS`    | Optional: `false` = no reply saying why a mention started nothing           |
+
+Restart the server after setting them. Without `GITHUB_APP_ID` and
+`GITHUB_APP_PRIVATE_KEY`, coding runs on GitHub repositories fail with
+[`vcs_github_not_configured`](errors/vcs-github-not-configured.md).
+Repositories of accounts that aren't served are refused with
+[`github_account_not_allowed`](errors/github-account-not-allowed.md).
+
+## 8. Check it
+
+- Run `link_host_account` and finish the GitHub sign-in it opens.
+- Link an agent with `link_repository`, or create a coding agent on the
+  repository (see [builder agents](builder-agent.md) and
+  [Run GitHub code-review agents](code-review-agents.md)).
+- In the App's **Advanced** settings, **Recent Deliveries** should show your
+  server answering webhooks with a 2xx status. A signature failure there means
+  the webhook secret and `GITHUB_APP_WEBHOOK_SECRET` differ.
+
+The full reference, including rollout order on Kubernetes deployments, is
+[Registering the GitHub App](../docs/code-review-agents.md#registering-the-github-app).

package/help/github.md

@@ -23,6 +23,8 @@ Workers do not receive the GitHub App private key. A trusted component validates
 the changes, pushes a controlled branch, and opens at most one draft pull
 request. Wardby does not auto-merge coding-agent output.
 
+To create and install the App, follow [Set up the GitHub App](github-app-setup.md).
+
 Set the App's credentials as `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` on
 the wardby server. Without them, a coding run on a GitHub repository fails with
 [`vcs_github_not_configured`](errors/vcs-github-not-configured.md).
@@ -69,6 +71,19 @@ The `review_fix` trigger lets Wardby fix its own review's findings
 automatically, up to a round cap, on pull requests its own coding runs
 opened. See [Automatic review fix rounds](review-fix-rounds.md).
 
+When a mention run finishes without opening a pull request or failing a
+sub-run and its reply is longer than about 2,000 characters (for example a
+plan), the status comment does not cut the reply short. It says "✅ Finished
+without opening a pull request. The full reply follows in the next
+comment(s)." (in a review thread: "...follows in this pull request's
+conversation."), and the reply is posted in up to four numbered comments
+("Reply, part i of n") of about 60,000 characters each, split at headings,
+paragraphs or lines. Anything beyond four parts is cut with a note; the full
+text stays on the run (`get_run`, `finalText`). `@`-mentions in the reply are
+defused. Each part is posted once; if one cannot be posted, the rest are
+skipped. Shorter replies, and runs that opened a pull request or had a failed
+sub-run, keep the status comment that quotes up to 2,000 characters.
+
 `waitForCi` holds a reviewer's review until that pull request's own CI
 finishes, and gates its ability to approve on CI passing. See
 [Review after CI (`waitForCi`)](code-review-agents.md#review-after-ci-waitforci).
@@ -79,4 +94,11 @@ opening coding run was delegated by a lead agent. See [Reviewing a pull
 request a delegated run
 opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
 
+With Wardby 0.7.0 or later, `markReadyWhenPassing` on the write link of the
+agent the event triggers (a builder, or a lead that delegates to a coding
+builder) has Wardby mark the draft pull requests it opens here ready for review
+on its own, once every Wardby reviewer check and CI on the head are green
+and, for a merge-ordered set, the steps it depends on have merged. See [Mark
+ready when passing](code-review-agents.md#mark-ready-when-passing).
+
 For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/identity-and-access.md

@@ -46,3 +46,5 @@ that request every advertised scope otherwise fail with `invalid_scope`.
 Read [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
 for the required claims, scope list, role mapping, provider examples, and
 client registration.
+
+From Wardby 0.7.0, to share an agent with one person or with everyone signed in, see the help article `sharing-agents`.

package/help/jira.md

@@ -65,13 +65,24 @@ the `Jira acting as` startup line to confirm the account.
 Beyond reading, searching and commenting, linked agents get
 `jira_list_transitions`, `jira_transition`, `jira_update_fields`,
 `jira_link_issues`, and `jira_get_property` / `jira_set_property` for
-per-issue state, plus `jira_create_issue` and `jira_read_attachment`. Each authorizes against the issue's own project and the
-agent's live link. Properties are not allowlisted: any `write` link can set
-them and any link can read them. They are stored as `wardby.<agentId>.<name>`,
-and anyone with Jira API access to the issue can read or overwrite them, so
-never store secrets there. Run status comments include an `Agent spend: $...`
-line. To see what work on a card, epic, or project cost, read
+per-issue state, plus `jira_create_issue` and `jira_read_attachment`. Each
+authorizes against the issue's own project and the agent's live link.
+Properties are not allowlisted: any `write` link can set them and any link can
+read them. They are stored as `wardby.<agentId>.<name>`, and anyone with Jira
+API access to the issue can read or overwrite them, so never store secrets
+there. Run status comments include an `Agent spend: $...` line. To see what
+work on a card, epic, or project cost, read
 [Attribute agent spend to issues](cost-attribution.md).
+
+When a run succeeds, opens no pull request, has no failed sub-run, and its
+reply is longer than about 2,000 characters (for example a plan), the status
+comment says "✅ The full reply follows in the next comment(s)." and the reply
+follows in up to four numbered comments ("Reply, part i of n") of about 15,000
+characters each, split at headings, paragraphs or lines. Anything beyond is
+cut with a note, and the full text stays on the run (`get_run`, `finalText`).
+`@`-mentions are defused. Each part is posted once; if one cannot be posted,
+the rest are skipped. Shorter replies stay in the status comment.
+
 If the token belongs to a person, Wardby refuses to act: startup logs an error
 and the webhook answers 503 `jira_personal_account`. Deliveries with a
 timestamp older than two hours (or more than five minutes ahead) are ignored.
@@ -125,6 +136,12 @@ agent how to continue each open one; see
 [Related pull requests across repositories](related-pull-requests.md). See
 the full guide for the recipe.
 
+To have a code reviewer check such a pull request against the ticket's own
+acceptance criteria, link the reviewer to the Jira project too (read access
+is enough): it then reads the ticket with `jira_get_issue`. Without that link
+it can only judge the criteria from the pull request's description; see
+[Run GitHub code-review agents](code-review-agents.md#reading-the-issue-a-pull-request-resolves).
+
 ## Trust rules
 
 Only people (not customers, apps, or the service account itself) can trigger

package/help/knowledge.md

@@ -1,9 +1,9 @@
 ---
 id: knowledge
 title: Architecture knowledge bundles
-summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
+summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ (or a folder you pick in .wardby/knowledge.yaml) so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
 audience: operator
-tags: [knowledge, architecture, coding-agents, okf, cli, drift, push]
+tags: [knowledge, architecture, coding-agents, okf, cli, drift, push, knowledge.yaml, bundle-path]
 appliesTo: >=0.4.0
 ---
 
@@ -16,9 +16,18 @@ their reasons, and cross-module contracts. It uses the Open Knowledge Format
 for, the paths it affects, and citations to the code it describes. Each citation
 carries a commit `sha` and a `spanHash` so staleness can be detected.
 
-- `docs/knowledge/index.md` lists every concept in one line; `log.md` records
-  changes to the bundle.
-- When `docs/knowledge/index.md` exists on a coding run's base branch, the run's
+- `index.md` lists every concept in one line; `log.md` records changes to the
+  bundle.
+- **Pick your own folder:** add `.wardby/knowledge.yaml` with one line,
+  `path: .okf` (any repo-relative folder outside `.wardby/` and `.git/`). Wardby
+  then reads the bundle there for the coding-run note, merge-watcher drift runs,
+  and `wardby knowledge check`. Without the file it uses `docs/knowledge/`; an
+  invalid file is ignored with a warning (`knowledge_config_invalid` from the
+  check). Or skip wardby's reading entirely: tell your agents where knowledge
+  lives in their prompts or `AGENTS.md`, and they use that folder; you lose
+  only the automatic note and drift scoping on merge. Update any prompt that
+  names `docs/knowledge/` to your folder.
+- When the bundle's `index.md` exists on a coding run's base branch, the run's
   task includes the index automatically (up to 8 KiB). It never fails a
   dispatch; an unreadable index just means no note.
 - When the run's commit is known (it always is for a normal clone) and the
@@ -26,8 +35,8 @@ carries a commit `sha` and a `spanHash` so staleness can be detected.
   has no git metadata, so use that value for citation `sha` fields.
 - Validate the bundle with `wardby knowledge check` (add `--strict` to fail on
   warnings, `--json` for machine output, `--root` to point at the repository).
-  Errors are `concept_invalid`, `concept_secret`, `index_missing`, and
-  `index_link_broken`; warnings are `concept_not_indexed`,
+  Errors are `concept_invalid`, `concept_secret`, `index_missing`,
+  `index_link_broken`, and `knowledge_config_invalid`; warnings are `concept_not_indexed`,
   `citation_unverifiable`, and `citation_stale`.
 - Builders may edit concept prose. Citations can go stale afterward; the
   architecture agent re-anchors them.

package/help/local-repositories.md

@@ -50,7 +50,7 @@ The easiest way to try it is the optional coding step of
   machine cannot see the folder: it ignores a trusted folder that does not
   exist, so the repository fails with `local_repo_not_allowed`, and `doctor`
   reports the folder as missing.
-- **git 2.24 or newer** on the machine that runs the wardby server.
+- **git 2.38 or newer** on the machine that runs the wardby server.
 - **Worker images from this release or later.** An older worker image rejects
   a `local:` repository and the run fails with `worker_input_failed`. That
   includes a bring-your-own `workerImageRef` image: rebuild it on a current

package/help/low-power-mode.md

@@ -46,7 +46,11 @@ only when `WARDBY_LOW_POWER=1`.
   a sandbox run does the same for the gateway. The wait is at least 5 minutes.
   A `KUBERNETES_READY_TIMEOUT_MS` (proxy) or `NATIVE_SANDBOX_READY_TIMEOUT_MS`
   (gateway) above that, set on the control-plane Deployment, raises it. Expect
-  about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`.
+  about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`. A
+  sandbox run woken this way may then wait for a gVisor node for its worker
+  pod, so its first model call can come several minutes after it started. From
+  0.7.0 it shows as running the whole time and is not reaped as orphaned; only
+  the wake and pod-start limits above can fail it.
 - **Preflight.** 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`).
@@ -107,6 +111,8 @@ full table.
 
 - [`low_power_wake_timeout`](errors/low-power-wake-timeout.md): the target did
   not become ready in time, or its Deployment does not exist.
+- `native_sandbox_launch_abandoned` (0.7.0 and later): a sandbox run was
+  stopped while the gateway woke, so no worker pod was made.
 - [`low_power_disabled`](errors/low-power-disabled.md): `power_sleep` was
   called while the mode is off.
 - [`low_power_scale_forbidden`](errors/low-power-scale-forbidden.md): the

package/help/merge-order-check.md

@@ -51,6 +51,11 @@ merge order set by the delegating agent," counted over the whole set
 (merged and closed pull requests included), so a pull request's step
 number doesn't change as earlier steps merge.
 
+With Wardby 0.7.0 or later, when the delegating lead is linked with
+`markReadyWhenPassing`, later steps become ready for review only once this
+check is `success`. See
+[Mark ready when passing](code-review-agents.md#mark-ready-when-passing).
+
 ### Waiting for the delegating run to finish
 
 While the delegating (lead) agent's run that produced this set is still

package/help/native-capabilities.md

@@ -3,7 +3,7 @@ id: native-capabilities
 title: Use native agents, tools, and data
 summary: Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.
 audience: developer
-tags: [agents, tools, secrets, datastores, memory, schedules, subagents]
+tags: [agents, tools, secrets, datastores, memory, schedules, subagents, zod, paramsZod, create_tool, dry_run_tool]
 appliesTo: >=0.2.1
 ---
 
@@ -20,6 +20,34 @@ checkout. Give each agent only the capabilities its job needs:
 - **Schedules and webhooks** to start event-driven work.
 - **Sub-agents** for delegated, bounded work with their own capability set.
 
+A tool's parameters are a Zod schema written as source text (`paramsZod` on
+`create_tool` and `update_tool`). Wardby compiles it inside the sandbox, both to
+derive the JSON Schema the model sees and to validate each call's arguments.
+
+Wardby itself now uses Zod 4. For this release only, a tool's `paramsZod` is
+still compiled with Zod 3 (Zod 4's built-in `zod/v3` API), so existing tools keep
+working unchanged; a schema Zod 3 can't compile, such as one using `z.email()`,
+is compiled with Zod 4. **Zod 3 schemas stop working in the next release**,
+which compiles `paramsZod` with Zod 4 only. A schema that calls something Zod 4
+removed, such as `.nonstrict()`, `.deepPartial()`, `z.ostring()` or
+`z.string().ip()`, will then fail every call's validation.
+
+Wardby warns about each such tool now:
+
+- `create_tool`, `update_tool` and `dry_run_tool` results include a `warnings`
+  list naming the tool and the removed methods;
+- in `list_tools` and in `get_agent`'s attached tools, each tool you own that is
+  affected carries the same `warnings` list;
+- `wardby tool create` and bundle imports print the same warning;
+- the server logs one warning per affected tool at startup.
+
+To check a schema before the next release, call `dry_run_tool` with the tool's
+`paramsZod` and sample arguments. With no `warnings` in the result, the schema
+compiles with Zod 4 and Zod 4 treats those arguments the same way. Otherwise,
+rewrite the schema with the Zod 4 API (for example `z.looseObject()` for
+`.nonstrict()`, `z.string().optional()` for `z.ostring()`, and `z.ipv4()` or
+`z.ipv6()` for `.ip()`), dry-run it again, and save it with `update_tool`.
+
 Use a budget or shared budget group on every agent, and inspect runs before
 expanding its access. An access grant is intentional delegation: use it only
 when an owner permits one agent to use another resource. Creating or changing

package/help/native-sandbox.md

@@ -102,8 +102,21 @@ are in [Native sandbox](../docs/native-sandbox.md#warm-pool).
   run `budget_exhausted`.
 - Sub-agents of a sandboxed run are managed runs started by the scheduler
   leader on its next tick (about every 10 seconds), so the server or scheduler
-  must be running.
+  must be running. A coding agent child is resolved by the server when it
+  starts (worker image, services, knowledge), so the gateway needs no `CODING_*`
+  settings; a problem there (such as a `workerImageRef` that is not pinned by digest)
+  shows as the child run `failed` or `refused`; the parent's `delegate_to_*`
+  call receives `status: "failed"` with the `errorCode`, or for a refused child
+  the refusal sentence, and the full error is on the child run (`get_run`).
+  Upgrade `wardby serve` and `wardby scheduler` before or together with the
+  gateway: an older server starts the child unresolved (a Codex child on the
+  default image without its instructions, a Claude Code child failing with
+  `coding_provider_not_configured:claude-code`).
 - A sandbox run has a 60-minute maximum lifetime.
+- `stop_run` stops a sandbox run: its gateway session ends so the worker exits
+  at its next call, and a worker still running after 5 seconds is killed and
+  removed (a warm pool worker is discarded, never reused). Search help for
+  "stop run" (article `stop-run`, Wardby 0.7.0 and later).
 
 ## Roll back
 
@@ -120,6 +133,7 @@ codes:
 
 - [native_sandbox_unavailable](errors/native-sandbox-unavailable.md)
 - [native_sandbox_worker_exited](errors/native-sandbox-worker-exited.md)
+- [native_sandbox_gateway_error](errors/native-sandbox-gateway-error.md)
 - [native_sandbox_deadline_exceeded](errors/native-sandbox-deadline-exceeded.md)
 - [native_sandbox_worker_lost](errors/native-sandbox-worker-lost.md)
 - [native_sandbox_image_not_pinned](errors/native-sandbox-image-not-pinned.md)

package/help/operating-agents.md

@@ -32,5 +32,10 @@ A running run's cost, token counts, and turn count update after each model
 call, so `get_run` and `list_runs` show spend so far rather than zero until the
 run finishes.
 
+To stop a run that is pending, queued, or running (for example one a schedule
+started that you did not want), call `stop_run` with its id. It ends as
+`cancelled`, along with the sub-agent runs it still has in flight. Search help
+for "stop run" (article `stop-run`, Wardby 0.7.0 and later).
+
 For the full lifecycle and the controls applied to every managed run, read
 [`README.md`](../README.md).

package/help/package-audit-mode.md

@@ -0,0 +1,91 @@
+---
+id: package-audit-mode
+title: Package audit mode
+summary: Let a coding agent install packages outside its allowlist for a limited time, recorded for approval afterwards; full mode also installs versions with high-severity advisories. Malware and the release-age limit are always enforced.
+audience: operator
+tags: [coding-agents, packages, allowlist, package audit, package audit mode, audit mode, packageAuditMode, packageAuditMinutes, approve_audited_packages, packages_audited, npm, pypi, supply-chain]
+appliesTo: >=0.7.0
+---
+
+# Package audit mode
+
+From Wardby 0.7.0, a coding agent's registry can run in package audit mode for
+a limited time. Instead of refusing a package that is not on the agent's
+allowlist, the registry installs it and records it. Use it to find out which
+packages a task needs, then approve them and turn the mode off.
+
+## Modes
+
+| Mode    | Packages outside the allowlist | High or critical advisories | Malware | Release age |
+| ------- | ------------------------------ | --------------------------- | ------- | ----------- |
+| off     | refused                        | withheld unless accepted    | refused | enforced    |
+| `audit` | installed and recorded         | withheld unless accepted    | refused | enforced    |
+| `full`  | installed and recorded         | installed and recorded      | refused | enforced    |
+
+Everything else still applies in every mode: integrity checks, source
+distributions, size and file limits, and a version outside an allowlist
+entry's own range (`foo@^1` never serves `foo@2`).
+
+## Turn it on and off
+
+The agent's owner sets it with `update_agent` (needs `packages:approve` or
+`agents:admin`):
+
+```json
+{ "id": "<agent id>", "codingProfile": { "packageAuditMode": "audit", "packageAuditMinutes": 1440 } }
+```
+
+- `packageAuditMinutes` defaults to 1440 (24 hours); the most is 10080 (7 days).
+- `packageAuditMinutes` alone re-arms the stored mode for that long.
+- `"packageAuditMode": null` turns it off.
+- `create_agent` does not accept it.
+
+`get_agent` shows `packageAuditActive` and a warning while the window is
+open. Each coding run takes the mode when it is dispatched and keeps it for
+its whole life, so a run that starts just before the window ends still runs
+with it.
+
+## Where audited packages show up
+
+- `get_run`: `packageAuditMode` and `packageAudit`, one entry per version
+  with its `relation` (`top-level`, `transitive` with `via`, `unknown`, or
+  `allowed`) and, in `full` mode, its `advisories` (the high and critical ones it was served despite).
+- The pull request body: a caution banner, **Packages outside the
+  allowlist**, and in `full` mode **Served despite advisories**.
+- The run's status comment on GitHub or Jira, and a `packages_audited` Slack
+  message on linked channels (see [Slack notifications](slack-notifications.md)).
+- The proxy log: one `registry.audited` line per version.
+
+A lockfile plan in audit mode approves what passes every other check, and the
+dependency cache never restores or saves a lockfile whose plan audited
+anything.
+
+## Keep the packages
+
+Approve the names a run recorded with `approve_audited_packages`
+(`{ "runId": "<run id>" }`), or add them to `codingProfile.packageAllowlist`
+with `update_agent`. Then turn the mode off.
+
+Without `names`, the tool adds only `top-level` packages. A package recorded
+as `unknown` (installed with no metadata or plan to show its parent) may be a
+dependency of an allowlisted package, so every report lists it apart as
+"Relation unknown — may be a dependency; approve only if needed directly".
+Add one only if the project uses it directly, by listing it in `names`.
+
+## Risks
+
+Audit mode weakens the supply-chain guard while it is on. `audit` keeps the
+malware, advisory and release-age checks; `full` keeps only malware and
+release age. A confused or prompt-injected agent could install a lookalike
+package that has no advisory yet. Install scripts stay off, but tests and
+builds still run what was installed. Keep the window short, review the
+caution banner on every affected pull request, and never leave it on.
+
+## Related
+
+- [Coding packages](coding-packages.md)
+- [Not allowed: `wardby_package_not_allowed`](errors/package-not-allowed.md)
+- [Package not reached: `wardby_package_not_allowed_pending`](errors/package-not-allowed-pending.md)
+- [Graph limit: `wardby_graph_limit`](errors/graph-limit.md)
+- [Still being checked: `wardby_graph_incomplete`](errors/graph-incomplete.md)
+- [Package audit mode guide](../docs/coding-packages.md#package-audit-mode)

package/help/related-pull-requests.md

@@ -11,16 +11,19 @@ appliesTo: ">=0.4.2"
 
 When one request produces pull requests in several repositories — a lead
 agent that delegates to one coding agent per repository, or several runs for
-the same Jira issue — Wardby adds a **Related pull requests** section to each
+the same Jira or GitHub issue — Wardby adds a **Related pull requests** section to each
 of those pull requests' descriptions. It lists the others with links and
 their state, names the originating issue when there is one, and gives a
 merge order: the one the delegating agent set, or else a suggested one.
 
-Without a tracked Jira issue, the list covers the pull requests opened by
-runs in the same delegation tree (the same lead run and everything it
-started). With a tracked issue, the list covers every pull request Wardby
-has recorded for that issue across every run, merged and closed ones
-included, plus that run tree's own siblings.
+Without a tracked issue, the list covers the pull requests opened by runs in
+the same delegation tree (the same lead run and everything it started). With
+a tracked issue (a Jira issue, or a GitHub issue whose `@<app-slug>` mention
+started the request), the list covers every pull request Wardby has recorded
+for that issue across every run, merged and closed ones included, plus that
+run tree's own siblings. The section names the issue the same way for both,
+for example "for Jira issue PROJ-123" or "for GitHub issue owner/repo#7",
+linked to the issue.
 
 - **Written by Wardby, not the model.** The list comes from Wardby's own run
   records, never from the agent's text. Edits you make inside the section
@@ -65,7 +68,7 @@ included, plus that run tree's own siblings.
   name and number, so a request that spans repositories of different
   visibility can show a private repository's name in a public repository's
   pull request. If you mix public and private repositories, keep such work in
-  separate requests: separate Jira issues, or separate lead agents.
+  separate requests: separate issues, or separate lead agents.
 
 Reviewers see the section in the pull request description, so a reviewer
 agent can tell that a field, route, or schema a change relies on is added by