@wardby/cli 0.5.2 → 0.6.0

package/docs/code-review-agents.md

@@ -262,6 +262,17 @@ it starts a fresh review, and if that review requests changes, it starts a
 fix round the same way any other review would (subject to the cap and to no
 earlier round still running).
 
+With Wardby 0.6.0 or later, a round whose coding run ends with no change —
+the agent concluded the review's finding was wrong rather than pushing a
+fix — gets one fresh review instead, of the pull request's current
+(unchanged) head, run by the reviewer whose check requested the changes.
+The fix round's own summary is passed to that reviewer as untrusted
+context: information about what was decided and why, never instructions to
+follow. This happens once per review that requested changes, counts toward
+the pull request's round cap the same as a round that pushed a change, and
+at the cap posts the usual cap comment instead of re-reviewing — since no
+push happened, nothing else would otherwise replace the failed check.
+
 If a repository already forwards wardby's reviews to a webhook through a
 hand-written CI workflow to fix them automatically, replace that workflow
 with `review_fix`: link the trigger, then delete the workflow and its
@@ -444,6 +455,50 @@ A GitHub App has exactly one webhook URL. Register a **separate App** for
 local development or a staging environment rather than pointing your
 production App's webhook at a dev host.
 
+### Which accounts the App serves (`WARDBY_GITHUB_ALLOWED_ACCOUNTS`)
+
+A GitHub App has one webhook URL, so every account that installs it sends its
+events to your server. wardby serves only trusted accounts:
+
+- **The App's owner** (the user or organization that owns the App), always.
+- **Accounts in `WARDBY_GITHUB_ALLOWED_ACCOUNTS`**, comma-separated logins:
+
+      WARDBY_GITHUB_ALLOWED_ACCOUNTS=acme-labs
+
+Every other account is refused: its events are answered `202` and ignored before
+anything is recorded, and `link_repository` and coding profiles refuse its
+repositories with `github_account_not_allowed`, even with `adminOverride`.
+There is no setting that serves every account.
+
+wardby removes the App from another account's installation only when that
+account installs the App or changes the installation's repository selection.
+Installations that already exist on other accounts stay installed (their
+events are ignored); remove them by hand in the App's settings under
+**Install App**.
+
+**When you upgrade**, existing repository links and scheduled runs on
+repositories of accounts that are not served start failing with
+`github_account_not_allowed`. List those accounts in the variable first if they
+should keep working.
+
+A private App can only be installed on its owner, so it needs nothing here. Set
+the variable when the App must be installable by other accounts, for example
+when an organization owns the App and a user's repositories should be served
+too. Logins are matched case-insensitively; a malformed value stops the server
+at startup.
+
+wardby reads the App's owner login from GitHub (`GET /app`, with the App's own
+credentials) and remembers it until it restarts. If it cannot read the owner,
+it refuses rather than guesses. After you transfer the App to another owner or
+rename the owner account, list the new owner in
+`WARDBY_GITHUB_ALLOWED_ACCOUNTS` (or restart wardby) before relying on it:
+until then, events from the new owner are ignored. Before removing the App
+from an installation, wardby re-reads the owner, so it never removes the App
+from its current owner.
+
+Each wardby server should have its own GitHub App: never point other people at
+yours; give them the setup steps above instead.
+
 ### `GITHUB_APP_WEBHOOK_SECRET`
 
 Set alongside `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`
@@ -501,6 +556,11 @@ the full desired state. Two common shapes:
 }
 ```
 
+With Wardby 0.6.0 or later, a `pull_request` reviewer's review of a pull request
+opened by a delegated coding run is held until the run that delegated it
+finishes, whether or not this link sets `waitForCi` — see [Reviewing a pull request a delegated run
+opened](#reviewing-a-pull-request-a-delegated-run-opened) below.
+
 Add `"waitForCi": true` to a `pull_request` link to hold the reviewer's
 review of a pushed head until that head's own CI finishes, instead of racing
 it — see [Review after CI (`waitForCi`)](#review-after-ci-waitforci) below.
@@ -570,6 +630,53 @@ The errors you may get while linking:
 | 409    | Another agent already holds the `mention` or `review_fix` trigger, or this `checkName`, on the repository.        |
 | 503    | GitHub could not be asked (e.g. the App isn't installed on the repository). Nothing was changed.                  |
 
+### Reviewing a pull request a delegated run opened
+
+> **Requires Wardby 0.6.0 or later.** Earlier releases review a delegated
+> run's pull request on its first push, like any other.
+
+A coding run can be delegated: a lead agent's `delegate_to_<name>` call
+starts a coding sub-agent that pushes the branch and opens the pull request
+(see [Fanning out to several builders](agent-recipes.md#fanning-out-to-several-builders)).
+While the lead run that delegated it is still running, every reviewer linked
+with the `pull_request` trigger holds its review of that pull request instead
+of starting on the first push — including a reviewer with no `waitForCi` set.
+The review starts once the lead run finishes, however it ends (including
+failing, being cancelled or being lost).
+
+Holding the review this way means the request's other pull requests, if any,
+have also been opened by the time any of them is reviewed. When the lead run
+finishes normally, the **Related pull requests** section on each of them has
+also been rewritten with the full list (see [Related pull requests across
+repositories](../help/related-pull-requests.md)). When it is ended another
+way (for example, cancelled), the held reviews start without that section
+having been rewritten, so it can be incomplete. Either way, a reviewer should
+use `repo_pr_read`'s `relatedPullRequests`, which is computed from Wardby's
+own records on every call, so it does not report a field, route, or schema as
+missing only because a sibling repository's pull request had not been opened
+yet.
+
+- A reviewer linked with `waitForCi` then also waits for CI on the head, once
+  the lead run finishes, exactly as described below — with its own full
+  15-minute fallback, counted from that point, not from the original push.
+- If the deployment cannot tell whether the pull request's opening run was
+  delegated (for example, the host call to read its origin fails), the
+  review starts immediately instead, exactly as it would without this
+  behaviour.
+- These pull requests are never held by this: one opened directly by a
+  coding run that was not delegated, one opened by a human, and one on a
+  local repository (which has no origin to read).
+- A later request that continues an already-open pull request is not held
+  again: the request that opened it has already finished. A push that
+  continues the pull request inside the same, still-running request is held
+  like the first one.
+- As with the CI fallback below, a hold here does not depend on the
+  instance that started it still running when the lead run finishes:
+  Wardby's reconciliation sweep reconsiders every review held for at least
+  15 minutes and releases it once the lead run has finished or no longer
+  exists, wherever the scheduler process runs. A held review is dropped
+  unreleased after 24 hours, the same as a review held for CI.
+
 ### Review after CI (`waitForCi`)
 
 `waitForCi` (boolean, default `false`, only on a `pull_request` link — 400
@@ -666,7 +773,20 @@ internal marker to the model:
   `note` telling the agent to follow CI over the description's **Tests**.
   Reading CI never makes `repo_pr_read` fail: an unreadable result is
   `state: "unavailable"` with `unavailableReason`. At most 50 results are
-  listed; names are capped at 100 characters.
+  listed; names are capped at 100 characters. With Wardby 0.6.0 or later it also
+  returns `relatedPullRequests`: this request's pull requests (`repository`,
+  `number`, `state`, `mergeOrder`, `self`), computed fresh at call time from
+  Wardby's own run records; empty on a human pull request, one with no
+  recognized Wardby marker, or a pull request on a local repository (which
+  has no origin marker to look up). The `self` entry (the pull request just
+  read) always has a `state` — `draft`, `open`, `merged`, or `closed` — taken
+  from that same read. Another entry has a `state` (`open`, `merged`, or
+  `closed`) only when Wardby has it stored, which it does for pull requests
+  linked to an issue; otherwise `state` is omitted. Siblings are never read
+  from the host for this: call `repo_pr_read` on a sibling when you need its
+  live state. The list of pull requests is current; the PR body's **Related
+  pull requests** section can be stale (see
+  [Related pull requests across repositories](../help/related-pull-requests.md)).
 - **Re-review when CI finishes.** When a review publishes `COMMENT` on its
   own check while CI on that head is `pending` or `none`, Wardby records it.
   When a CI check suite (not Wardby's own) completes on that head and no CI
@@ -728,10 +848,15 @@ request's **Related pull requests** section correctly:
     Reviewer step (CI and related pull requests). Read `ci` from repo_pr_read.
     When `ci` and the description's Tests disagree, follow CI and say so; never
     ask for a fix only because a sandbox test failed while CI passed. Report
-    pending checks as pending. If the description has a "Related pull requests"
-    section, a field, route or schema the change relies on may be added by one
-    of those pull requests: do not report it as missing; note the dependency
-    and the suggested merge order instead.
+    pending checks as pending. If repo_pr_read's relatedPullRequests is
+    non-empty, a field, route or schema the change relies on may be added by
+    one of those pull requests: do not report it as missing; note the
+    dependency and the listed merge order instead. relatedPullRequests is
+    current; the PR body's "Related pull requests" section can be stale.
+
+On a release before 0.6.0, `repo_pr_read` has no `relatedPullRequests`: use
+the description's **Related pull requests** section in its place in that
+step.
 
 Check names and the description are repository content: treat them as data,
 as for every `repo_*` result.
@@ -751,6 +876,15 @@ the PR's author controls and can use to steer the model. Treat it as one
 signal, not the only merge gate: keep a human approval (or another
 independent check) required alongside it.
 
+A related set with more than one `mergeOrder` (see [Setting a merge
+order](../help/related-pull-requests.md#setting-a-merge-order)) also gets a
+check named exactly `wardby merge order` on each pull request, independent
+of any reviewer link, tracking whether the pull requests it depends on have
+merged yet. Require it the same way — add `wardby merge order` as a
+required status check, with its expected source set to the wardby GitHub
+App — to block a merge until they have. See
+[The wardby merge order check](../help/merge-order-check.md).
+
 ## Accepted gap: a run that fails outside its normal finish path leaves its check open
 
 A run's in-progress check is only closed (completed `failure`, "Use Re-run

package/docs/coding-agent-setup.md

@@ -104,8 +104,8 @@ JOB_LAUNCHER=docker
   folder as missing. The machine needs git 2.24 or newer.
 - **Worker images.** Use worker images from the same release as the control
   plane. An older worker image rejects `local:` repositories (the run fails with
-  `worker_input_failed`), including a bring-your-own `workerImageRef` image,
-  which must be rebuilt on a current driver image.
+  `worker_input_failed`), including a Codex agent's bring-your-own
+  `workerImageRef` image, which must be rebuilt on a current driver image.
 
 ### What a coding run does
 
@@ -133,6 +133,23 @@ same branch; if the branch has moved, or is checked out, the run fails with
 Result branches accumulate, and wardby does not delete them. Clean up with
 `git branch -D wardby/run-<run id>`.
 
+### Toolchains for local repositories
+
+The default workspace is Node. A coding agent whose `codingProfile` sets
+`toolchain: "node-python"` and `toolchainVersion: "3.12"` runs in a Node +
+Python 3.12 workspace with `pytest` and `ruff`, for Codex and for Claude Code.
+The server selects the image from `CODING_WORKER_IMAGE_NODE_PYTHON_3_12`
+(Codex) or `CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` (Claude Code); a
+`node-python` agent is refused when the variable for its provider is unset.
+`quickstart` sets this up for you when the repository has a Python marker file
+(`pyproject.toml`, `setup.py`, `setup.cfg`, `Pipfile` or `requirements*.txt`)
+at its committed root; see
+[Python projects](getting-started.md#python-projects).
+
+For any other language, use `codingProfile.workerImageRef` (admin only). It is
+a custom image for the container that runs the agent's commands, for Codex and
+for Claude Code; see [Bring-your-own worker images](coding-worker-byo-images.md).
+
 ### Review agents
 
 Link a native review agent with `link_repository` (`provider: "local"`,
@@ -202,6 +219,8 @@ GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVA
 `npm run claude:images:local` builds the Claude agent image and both tool-runner
 images (`wardby-claude-tool-runner:phase5`, and
 `wardby-claude-tool-runner:phase5-node-python` for the `node-python` toolchain).
+It also builds `wardby-claude-tool-runner-custom:phase5`, a test-only custom
+tool runner that `npm run test:claude-docker` needs.
 This local, immutable-`sha256:` ID form of the `CODING_CLAUDE_*` images is only
 accepted by the Docker launcher.
 `JOB_LAUNCHER=kubernetes` needs both images pushed to a registry and set as
@@ -245,6 +264,112 @@ See [release verification](release-verification.md) for the complete gate.
 If the repository has `docs/knowledge/index.md`, every coding run's prompt
 includes it. See [Architecture knowledge bundles](knowledge.md).
 
+## Repository instructions
+
+Every coding run loads the repository's own instructions; there is no
+`codingProfile` setting to turn this off. Codex reads the repository's
+`AGENTS.md` itself, directly from the checkout. Claude Code is handed
+`CLAUDE.md`, `.claude/CLAUDE.md`, and whatever either file pulls in with
+`@path` imports, up to 5 import levels deep; a repository that only has
+`AGENTS.md` gets a one-line `CLAUDE.md` that imports it, so a repository
+written for another coding agent still has its instructions in Claude Code.
+Subdirectory `CLAUDE.md` files (anything other than the repository root and
+`.claude/CLAUDE.md`) are not loaded unless an imported file pulls them in.
+
+Claude Code's instructions and skills are read from the checkout and bounded:
+at most 64 KiB per file, 200 files, and 256 KiB combined; symlinks and
+non-UTF-8 files are refused. A file that doesn't pass, or that would push
+the run's input past its 512 KiB size limit once encoded (skills and the
+deepest imports are dropped first), is left out and logged as
+`coding.claude_context_skipped` (the first 50 individually, then one
+aggregate line with an overflow count); when the repository's context can't
+be read at all, the run continues without it and logs
+`coding.claude_context_unavailable`. A run never fails because its
+repository context couldn't be loaded.
+
+Claude Code never receives the repository's `.claude/settings.json`, hooks,
+`.mcp.json`, agents, or commands — only Markdown instruction files and
+`.claude/skills/<name>/SKILL.md` files pass the allowlist, whatever an
+instruction file imports. Repository instructions and skills are untrusted
+guidance: they can shape a run's work but never relax the worker's sandbox
+rules.
+
+## Claude Code loading mode
+
+`codingProfile.claudeBareMode` controls how Claude Code uses the repository
+instructions above. It defaults to `true` and only affects Claude Code
+agents.
+
+- **`true` (default, bare mode).** Claude Code keeps its hardened bare mode.
+  Wardby adds the repository's instruction files to the system prompt in
+  full, and lists each skill by name, description, and path; the model reads
+  a skill's full `SKILL.md` itself with `run_command`.
+- **`false`.** Bare mode is off. Claude Code loads `CLAUDE.md` and skills
+  itself, through its native Skill tool, instead of reading them from the
+  system prompt. Repository settings, hooks, MCP configuration, agents, and
+  commands are still never loaded in either mode; native loading also locks
+  Claude Code's own hooks to wardby's managed set.
+
+If the worker can't write the native-mode context to disk for a run, that
+run falls back to bare mode instead of failing, and the worker logs a
+`claude_context_unavailable` warning.
+
+The agent owner or an admin can change it:
+
+```json
+{ "id": "<agent-id>", "codingProfile": { "claudeBareMode": false } }
+```
+
+## Repository skills
+
+`codingProfile.repoSkills` loads the repository's own agent skills into a
+run. It defaults to `true`.
+
+| Builder     | Reads skills from                   | `repoSkills: true` (default)                        | `repoSkills: false`                |
+| ----------- | ----------------------------------- | --------------------------------------------------- | ---------------------------------- |
+| Codex       | `.agents/skills/`, `.codex/skills/` | Repository skills load                              | Every repository skill is disabled |
+| Claude Code | `.claude/skills/<name>/SKILL.md`    | Repository skills load (bare or native mode, above) | No skill context is collected      |
+
+Codex's own four built-in skills (`imagegen`, `openai-docs`, `skill-creator`,
+`skill-installer`) are always disabled, whatever `repoSkills` is set to —
+wardby's coding runs never offer them. With `repoSkills: false`, the Codex
+worker scans both roots for the skill names to disable; that scan stops after
+2000 directory entries, to bound the work an adversarial skills tree could
+cause, logs `codex_skill_scan_truncated`, and disables whatever names it found
+so far rather than failing the run.
+
+Claude Code skills ship to the worker as their `SKILL.md` only. A skill's
+other files (scripts, references, data) stay in the repository checkout and
+are read or run through the command runner at
+`/workspace/.claude/skills/<name>/`.
+
+Turn repository skills off for an agent:
+
+```json
+{ "id": "<agent-id>", "codingProfile": { "repoSkills": false } }
+```
+
+**Upgrading.** `repoSkills` and `claudeBareMode` both default to `true`, so
+upgrading changes behavior for existing agents: Claude Code agents start
+loading `CLAUDE.md` and `.claude/skills/` (previously neither was loaded),
+and Codex agents stop getting Codex's own built-in skills (previously always
+offered). Set `repoSkills: false` on an agent to keep its repository's
+skills out of its runs; there is no setting that keeps repository
+instructions themselves out, for either builder.
+
+Use the worker images (`CODING_WORKER_IMAGE` and `CODING_CLAUDE_WORKER_IMAGE`)
+from the same release as the control plane. On an older Claude Code worker
+image, runs fail with `worker_input_failed` once the repository has a
+`CLAUDE.md`, `AGENTS.md`, or skill to load, or the agent sets `repoSkills` or
+`claudeBareMode` to `false`; on an older Codex worker image, runs of agents with
+`repoSkills: false` fail the same way. A `workerImageRef` image must also be
+rebuilt for this release: on this release's driver image for a Codex agent, or
+on this release's tool runner image for a Claude Code agent. On a Claude Code
+agent, `workerImageRef` replaces only the tool runner (the container that runs
+the agent's commands); Claude Code itself always runs on
+`CODING_CLAUDE_WORKER_IMAGE`. See
+[Bring-Your-Own Coding-Worker Images](coding-worker-byo-images.md).
+
 ## Budgets
 
 A coding run's budget is reserved when it is dispatched: the agent's own

package/docs/coding-packages.md

@@ -42,8 +42,10 @@ request never names the internal proxy.
    image to build or maintain; the agent installs what it needs at run time.
 2. **A custom `workerImageRef` with dependencies baked in.** Still supported:
    point the agent's profile at your own image, built on wardby's driver base
-   image (see [Bring-your-own worker images](coding-worker-byo-images.md)),
-   with everything preinstalled. Setting `workerImageRef` needs `agents:admin`
+   image for a Codex agent, or `FROM` the same release's tool runner image for
+   a Claude Code agent (see
+   [Bring-your-own worker images](coding-worker-byo-images.md)), with
+   everything preinstalled. Setting `workerImageRef` needs `agents:admin`
    and the admin role, and the image must be pinned by digest.
 3. **Both together.** Use a custom image for a toolchain or system libraries
    the registry can't provide (a compiler, a non-Node/Python runtime, apt
@@ -69,14 +71,15 @@ it widens what the agent can download.
 
 `packageAllowlist` is keyed by ecosystem (`npm`, `pypi`), each an array of
 approved top-level entries. An entry is a bare package name, a name with a
-version range in that ecosystem's own syntax, or (npm only) a scope wildcard:
+version range in that ecosystem's own syntax, (PyPI only) a name with extras,
+or (npm only) a scope wildcard:
 
 ```json
 {
   "codingProfile": {
     "packageAllowlist": {
       "npm": ["react@^19", "@testing-library/*"],
-      "pypi": ["flask>=3"]
+      "pypi": ["flask>=3", "psycopg[binary]>=3.2"]
     }
   }
 }
@@ -85,6 +88,9 @@ version range in that ecosystem's own syntax, or (npm only) a scope wildcard:
 - `react@^19` — npm semver range syntax.
 - `@testing-library/*` — every package under that npm scope.
 - `flask>=3` — PEP 440 specifier syntax for PyPI.
+- `psycopg[binary]>=3.2` — a PyPI package with the extras it is installed
+  with, in PEP 508 form: `name[extra1,extra2]`, optionally followed by a
+  specifier. See [PyPI extras](#pypi-extras).
 - A bare name with no range (`"lodash"`) allows any version, subject to the
   other safeguards below.
 - npm names are matched exactly, including case. npm treats some legacy
@@ -100,6 +106,100 @@ metadata and grows the run's allowance automatically as npm or pip requests
 each dependency's metadata, so you don't have to enumerate transitive
 dependencies yourself.
 
+### PyPI extras
+
+A PyPI package can declare optional dependencies under named _extras_:
+`pip install "psycopg[binary]"` also installs `psycopg-binary`, which
+`psycopg` declares only under its `binary` extra. Without the extra on the
+allowlist, the proxy follows only a package's plain dependencies, so
+`psycopg-binary` would be refused with `wardby_package_not_allowed` even
+though `psycopg` is allowed.
+
+Name the extras on the entry, exactly as you would to pip:
+
+```json
+{ "pypi": ["psycopg[binary]", "uvicorn[standard]>=0.30", "celery[redis,msgpack]"] }
+```
+
+- Each extra must be a valid extra name (letters, digits, and `.`, `_` or `-`
+  between them), at most 32 per entry. Extras are compared after PEP 685
+  normalization (lower case, runs of `-`, `_` and `.` become `-`), so
+  `[Foo_Bar]` and `[foo-bar]` are the same extra.
+- An extra allows only the dependencies the package's own metadata declares
+  under that extra (`Requires-Dist: psycopg-binary==3.2.3; implementation_name
+!= "pypy" and extra == "binary"`). The rest of such a line's environment
+  marker is not evaluated, so the extra's dependencies are allowed on every
+  platform; pip still installs only what applies. Dependencies under any
+  other extra stay refused.
+- An entry without brackets follows no extras at all — neither its own nor
+  its dependencies'. When a plain entry's metadata asks for a dependency with
+  extras (`fastapi` declaring `uvicorn[standard]>=0.30`), the dependency is
+  allowed as the bare package, exactly as for any plain dependency, and the
+  packages under its extra stay refused. To allow them, name the extra on the
+  allowlist: `fastapi[standard]`, or `uvicorn[standard]` directly.
+- Dependencies' extras are followed only below a package the run allows with
+  extras: an entry that names extras, or a dependency such a package's
+  metadata asks for with extras. Below `fastapi[standard]`, a
+  `uvicorn[standard]` dependency line allows `uvicorn`'s `standard` packages
+  too. A dependency reached that way without extras of its own gets only its
+  plain dependencies.
+- The same package may appear in several entries; their extras are combined.
+- An extra that a dependency line asks for is followed only once the proxy has
+  served that parent's metadata. If pip reads the dependency before its parent
+  (for example because the dependency is also an allowlist entry) and the
+  extra's packages are refused with `403 wardby_package_not_allowed`, name the
+  extra on the allowlist directly, e.g. `uvicorn[standard]`.
+- The extra markers the proxy recognises are `extra == "name"`,
+  `extra === "name"`, and the reversed forms `"name" == extra` and
+  `"name" === extra` (single or double quotes, inside `and`/`or` and
+  parentheses).
+- A marker that mentions `extra` in any other form (`"name" in extra`,
+  `extra in "a b"`, a bare `extra`, or a marker with an unbalanced quote) is
+  treated as gated on no extra: that line is never followed, for any entry,
+  plain or not. Allowlist the package it names directly if you need it.
+- The proxy reads a wheel's `METADATA` only up to the end of its headers (the
+  first empty line); `Requires-Dist` text in the package description after
+  them is ignored.
+
+The last two rules apply to every PyPI allowlist, including ones without any
+extras, and are deliberately fail-closed: a dependency line the proxy cannot
+read with certainty is not followed. If a package that installed before is now
+refused with `403 wardby_package_not_allowed` because its parent declares it
+that way, add it to the allowlist directly.
+
+Extras on allowlist entries need the coding proxy and the control plane at the
+same Wardby version. A proxy from before extras support cannot parse a
+`name[extra]` entry at all: the whole allowlist fails to load, so **every**
+registry request of a run with such an entry fails, not just that package.
+Upgrade the proxy before (or with) the control plane. For the same reason,
+once any coding profile stores an extras entry, downgrading the control plane
+or proxy below the release that added extras is unsafe; remove the extras
+entries first.
+
+Every safeguard below (release age, advisories, wheels only, the record of
+what was fetched) applies to packages reached through an extra.
+
+### The quickstart offers a repository's declared packages
+
+The quickstart's coding step (see
+[Get started](getting-started.md#packages-the-repository-declares)) reads the
+dependencies the chosen local repository declares at the root of its base
+commit — `package.json` (`dependencies`, `devDependencies`,
+`optionalDependencies`), `pyproject.toml` (`[project]` dependencies, optional
+dependency groups, Poetry dependencies and groups, and Poetry's legacy
+`[tool.poetry.dev-dependencies]`, plus its `[build-system] requires` build
+packages, or `setuptools` and `wheel` when there is no `[build-system]` table)
+and `requirements*.txt` —
+and offers them as `local-builder`'s allowlist: names without versions (PyPI
+names PEP 503-normalized, keeping the extras a requirement names, such as
+`psycopg[binary]`, merged per package), invalid names dropped, at most 200 per
+ecosystem. It asks
+before adding them; a `--non-interactive` run adds them only with
+`--allow-repo-packages`. Every safeguard on this page still applies to those
+entries. A re-run of the quickstart replaces the builder's allowlist with the
+repository's current set (or an empty one if declined), so make lasting
+additions on a builder you created yourself, or re-apply them after a re-run.
+
 ### Lockfile installs: verified, then approved exactly
 
 `npm ci` (or `npm install` with a complete `package-lock.json`) skips
@@ -429,7 +529,7 @@ see on a failed install:
 
 | Code                                 | Status | Meaning / what to do                                                                                                                                                                                                                                                                                                               |
 | ------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `wardby_package_not_allowed`         | 403    | The package isn't on the allowlist and isn't reachable from an allowlisted package's dependency graph. Add it (or its top-level dependent) to `packageAllowlist`.                                                                                                                                                                  |
+| `wardby_package_not_allowed`         | 403    | The package isn't on the allowlist and isn't reachable from an allowlisted package's dependency graph. Add it (or its top-level dependent) to `packageAllowlist`. For a PyPI package an extra pulls in (`psycopg-binary` for `psycopg[binary]`), name the extra on the entry instead.                                              |
 | `wardby_file_not_allowed`            | 403    | The specific file type is never served for this ecosystem (for example a PyPI sdist). Nothing to configure; use a wheel.                                                                                                                                                                                                           |
 | `wardby_version_filtered`            | 404    | Every matching version is too new (younger than `minReleaseAgeDays`) or withheld by the vulnerability audit. Wait for it to age past the threshold, or lower `minReleaseAgeDays` if you understand the risk.                                                                                                                       |
 | `wardby_package_not_found`           | 404    | The upstream registry has no such package name. Check the spelling (npm names are case-sensitive).                                                                                                                                                                                                                                 |

package/docs/coding-services.md

@@ -194,7 +194,9 @@ to an agent that allows at least one service.
 
 A [bring-your-own worker image](coding-worker-byo-images.md) must be built on
 driver v11 or later to run with services; an agent whose `workerImageRef`
-predates driver v11 rejects the run input once services are on it.
+predates driver v11 rejects the run input once services are on it. For a
+Claude Code agent, build the custom image `FROM` the tool runner image of the
+same wardby release.
 
 ## Letting a coding agent change the declaration