@wardby/cli 0.5.3 → 0.7.0

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

@@ -70,9 +70,10 @@ Create these scopes in the provider:
 | `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. |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all fourteen in the provider even when
+may request every advertised scope. Define all fifteen 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.
@@ -92,17 +93,21 @@ otherwise clients that request every advertised scope fail with `invalid_scope`.
 deployment, define it in the provider too; otherwise clients that request
 every advertised scope fail with `invalid_scope`.
 
+`power:manage` was added after `models:admin`. 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` and `models:admin` take effect only for a caller who also holds a Wardby role that grants them:
+`admin:view`, `models:admin` and `power:manage` 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)) and `models:admin` (model catalog) |
-| `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) 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))                                                                                                                                                                                                                |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
@@ -162,7 +167,7 @@ Provider examples:
   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`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve`, `services:manage`, `admin:view` and `models:admin`.
+  `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
   access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
@@ -185,9 +190,17 @@ that case, register the MCP client manually as a **public/native application**:
 
 - require authorization code flow with PKCE S256;
 - do not issue or embed a client secret in a desktop client;
-- register the client's exact loopback callback URI; and
+- register the client's exact loopback callback URI;
+- enable the refresh-token grant and allow the `offline_access` scope, so the
+  client receives a refresh token (desktop clients need one to keep a session);
+  and
 - allow it to request the Wardby audience and scopes.
 
+To let the Wardby mobile app sign in, also register its private-use redirect
+URI, `com.wardby.mobile:/oauth` (or your white-label build's redirect, such as
+`com.example.app:/oauth`), as an allowed redirect URI on the IdP client that
+requests `admin:view`. Wardby needs no setting for this in delegating mode.
+
 For Claude Code, a fixed callback port makes the redirect URI predictable:
 
 ```sh
@@ -202,6 +215,12 @@ public client ID. If a client supports only dynamic registration, either enable
 that feature with suitable provider-side restrictions or use Wardby's
 self-hosted authentication mode.
 
+The Wardby viewer desktop app signs in on a fixed loopback callback,
+`http://127.0.0.1:8585/callback`; register that exact URI on its public/native
+client. Some providers match a loopback redirect by its exact port rather than
+the port-agnostic rule of RFC 8252 §7.3 — for those, this precise port must be
+registered, because a port-less or wildcard loopback entry will not match it.
+
 ## 4. Configure Wardby
 
 Inject these settings through the deployment's secret/configuration mechanism:
@@ -253,7 +272,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all fourteen Wardby scopes.
+- `scopes_supported` contains all fifteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.
@@ -310,6 +329,7 @@ test procedure and cleanup.
 | Wardby returns `403 insufficient_scope`       | The token is valid but `scope`/`scp` lacks the operation's required permission.      |
 | Client registration returns `403`             | Anonymous dynamic registration is disabled; pre-register a public client.            |
 | Browser flow rejects the redirect             | The provider's registered loopback callback does not exactly match the client.       |
+| Mobile sign-in fails with a redirect error    | The IdP client doesn't list the mobile redirect URI.                                 |
 | Wardby cannot validate any newly issued token | The control plane cannot reach the JWKS URI, or provider key rotation is incomplete. |
 | One person appears as multiple principals     | The provider is emitting different or pairwise `sub` values for different clients.   |
 

package/docs/getting-started.md

@@ -162,8 +162,9 @@ any local branch.
 Wardby's worker images have Node, or Node and Python 3.12. For a Go, Java, Rust
 or other project, build a worker image with that toolchain on Wardby's driver
 base image, and point the builder at it with `codingProfile.workerImageRef`.
-This works for **Codex** agents only today: a Claude Code agent runs its
-commands in its tool runner, which a custom worker image does not change.
+These steps are for a **Codex** builder. For a Claude Code builder, the image
+starts from Wardby's tool runner image instead; see
+[Codex and Claude Code](coding-worker-byo-images.md#codex-and-claude-code).
 
 1. Complete path A with Codex (`--coding-provider codex`).
 2. Run `npx @wardby/cli@latest doctor`. It prints the base image to build on:
@@ -347,8 +348,8 @@ Python tests. Upgrade, or set the variable above.
 Other languages (Go, Rust, Java and so on) are not detected. Use a
 bring-your-own image through `workerImageRef`; see
 [Path D](#path-d-another-language-build-your-own-image) and
-[Bring-your-own worker images](coding-worker-byo-images.md). That is Codex-only
-today: a Claude Code agent cannot use a custom toolchain yet.
+[Bring-your-own worker images](coding-worker-byo-images.md), for Codex or
+Claude Code.
 
 #### Packages the repository declares
 
@@ -421,6 +422,15 @@ along with the database. See
 run does, its requirements (the server must run on the same machine as the
 folders) and its limits (no submodules or Git LFS).
 
+#### Faster installs: the dependency cache
+
+For an npm repository, the coding proxy can keep `node_modules` snapshots so a
+run starts with its dependencies already installed. Add
+`WARDBY_DEPENDENCY_CACHE=true` to `.wardby/.env`, restart the stack, then set
+`codingProfile.dependencyCache` to `true` on the agent with `update_agent`. This
+needs wardby 0.7.0 or later; snapshots live on a Docker volume that
+`down -v` removes. See [Dependency cache](coding-packages.md#dependency-cache).
+
 ## Your first agents
 
 [Agent recipes](agent-recipes.md) gives two complete, copyable setups: an

package/docs/jira-agents.md

@@ -24,7 +24,7 @@ Jira Cloud only. One Jira site per wardby deployment.
   properties are not allowlisted.
 - **Status comments.** When an event starts a run, wardby posts a short
   "working on it" comment on the issue and edits it with the outcome when the
-  run ends, including a line such as `Agent spend: $0.0123` for the run and
+  run ends, including a line such as `Agent spend: $0.012` for the run and
   its direct sub-runs. That one comment is the reply: when the run succeeds
   it shows the agent's final answer, so the agent is told not to post the
   answer again with `jira_comment` (it uses `jira_comment` only for other
@@ -466,9 +466,12 @@ What happens:
   the same branch instead of opening a second pull request. The run message
   lists up to ten open pull requests recorded for the issue this way — any
   agent's, not only the triggered agent's own — each with its own run id, so
-  a follow-up can continue every one the change touches.
+  a follow-up can continue every one the change touches. GitHub issues behave
+  the same way; see
+  [Follow-ups on an issue](code-review-agents.md#follow-ups-on-an-issue).
 - **Several repositories.** When the issue leads to pull requests in more
-  than one repository (in the same run, or in later runs for the same issue),
+  than one repository (in the same run, or in later runs for the same issue,
+  Jira or GitHub),
   each pull request's description gets a **Related pull requests** section
   naming the issue and every pull request recorded for it, merged and closed
   ones included as context; see
@@ -478,6 +481,10 @@ What happens:
   [`code-review-agents.md`](code-review-agents.md)). Without them the pull
   request is still linked, but the issue is not updated on merge.
 
+To mirror this lifecycle in Slack — picked up, pull request open, review
+verdict, merge — link a channel to the project or agent; see
+[Send workflow updates to Slack](slack-notifications.md).
+
 ## Recipe: scheduled JQL sweeps
 
 An agent linked to a project can also run on a schedule with no issue event:
@@ -570,8 +577,16 @@ A run is attributed when:
 - its parent run is attributed (sub-agents and coding runs inherit, and cannot
   change it).
 
+GitHub issues are attributed the same way, to a work item with provider
+`github` and key `owner/repo#N`: a run started by a mention on the issue (and
+every sub-agent and coding run it starts), and runs on a pull request opened
+from it. `cost_report` lists them like any other work item
+(`provider: "github"` narrows to them).
+
 When a run is attributed to an issue, whatever the source, coding runs it
-starts name that issue in their pull request's title and body. The issue total
+starts name that issue in their pull request's title and body. A GitHub issue
+is named only in the body, as `From issue #N`, on a pull request in the
+issue's own repository. The issue total
 in a Jira comment's spend line covers every run attributed to that issue,
 whichever agent ran it.
 
@@ -598,11 +613,9 @@ How to read the numbers:
 - You see the runs of agents you own and runs you triggered, the same as
   `list_runs` and `get_run`.
 
-On GKE, existing deployments must re-run the database grants bootstrap
-(`deploy/gke/bootstrap-database-iam.sh`) after upgrading, so the coding proxy
-can write per-model usage for coding runs. Until then coding runs still work,
-but their per-model breakdown isn't recorded. See
-[Getting started on GKE](getting-started-gke.md).
+On GKE, the coding proxy needs a database grant to write per-model usage for
+coding runs; `deploy/gke/up.sh` applies it when you upgrade. See
+[Upgrading an existing deployment](getting-started-gke.md#upgrading-an-existing-deployment).
 
 ### Company-managed projects using Epic Link
 

package/docs/knowledge/blob-not-found-semantics.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Blob absence must distinguish missing infrastructure
+description: Mapping a storage outage to not_found can delete valid dependency snapshot metadata.
+tags: [storage, cache, providers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: missing
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/storage/s3.ts#L26-L32
+  - id: cleanup
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/coding-proxy/dependency-cache/service.ts#L275-L295
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/providers/storage/**", "src/providers/coding-proxy/dependency-cache/service.ts"]
+  citations:
+    - id: missing
+      repo: github:wardby/wardby
+      path: src/providers/storage/s3.ts
+      lines: [26, 32]
+      symbol: isNotFound
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:686cdad150c8c0d58e6b9acc5a2cd0bdf2e65b07b5ce8740938f43747f1408b7
+    - id: cleanup
+      repo: github:wardby/wardby
+      path: src/providers/coding-proxy/dependency-cache/service.ts
+      lines: [275, 295]
+      symbol: download
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:02d4e058438d562ba55b6681e0267e890eed1ef82159a3b332d214f2fd066427
+  confidence: high
+---
+
+The cache deletes snapshot metadata when getStream raises BlobStoreError with code not_found. The S3 adapter therefore maps missing keys, including the bare HeadObject NotFound response, but leaves NoSuchBucket and other failures as errors.[^missing][^cleanup]
+
+**Why:** not_found authorizes metadata cleanup; it is not a generic unavailable response. New storage adapters must preserve this distinction so an infrastructure failure cannot masquerade as a dangling snapshot.
+
+[^missing]: src/providers/storage/s3.ts, lines 26-32.
+
+[^cleanup]: src/providers/coding-proxy/dependency-cache/service.ts, lines 275-295.

package/docs/knowledge/bounded-file-descriptor.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Untrusted file bounds belong to the open descriptor
+description: Checking a path before reading it leaves file substitution and growth races across worker boundaries.
+tags: [coding, isolation, files]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: read
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/coding-worker/artifact.ts#L12-L48
+  - id: skills
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/coding-worker/skills.ts#L43-L54
+  - id: result
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/providers/jobs/docker.ts#L1263-L1277
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/coding-worker/artifact.ts", "src/coding-worker/skills.ts", "src/providers/jobs/docker.ts"]
+  citations:
+    - id: read
+      repo: github:wardby/wardby
+      path: src/coding-worker/artifact.ts
+      lines: [12, 48]
+      symbol: readBoundedRegularFile
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:ce5173dc2723b798c03e33fcb780c5c4da5b2dd15f2b517c4db77fec841f788d
+    - id: skills
+      repo: github:wardby/wardby
+      path: src/coding-worker/skills.ts
+      lines: [43, 54]
+      symbol: skillNameFromFile
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:022ed743f1ccb279f73e4520bf458ad28eeace035ae695853c9e5f7ee52087d4
+    - id: result
+      repo: github:wardby/wardby
+      path: src/providers/jobs/docker.ts
+      lines: [1263, 1277]
+      symbol: readResultArtifact
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:da6466b5dc44b1de79f473668648048b3f3ef3f82a6cce61516e8bfa76efb996
+  confidence: high
+---
+
+The bounded reader opens without following a final symlink and without blocking on a FIFO, checks the opened descriptor against the path inode, and reads at most one byte beyond the limit to detect growth. Both repository skill scanning and Docker result collection use it.[^read][^skills][^result]
+
+**What to do:** preserve descriptor checks and the bounded read together. Replacing them with a path stat followed by readFile reopens substitution and growth races even when the initial size was safe.
+
+[^read]: src/coding-worker/artifact.ts, lines 12-48.
+
+[^skills]: src/coding-worker/skills.ts, lines 43-54.
+
+[^result]: src/providers/jobs/docker.ts, lines 1263-1277.

package/docs/knowledge/delegation-admission-slots.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Budget-waiting delegations retain admission slots
+description: Releasing the delegation gate during a budget wait must preserve duplicate-child and delegation-limit accounting.
+tags: [delegation, concurrency, budgets]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T10:20:14.397Z }
+sources:
+  - id: admission
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L1071-L1089
+  - id: wait
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L1098-L1121
+  - id: persist
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/core/runner.ts#L1175-L1182
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/core/runner.ts", "src/core/serial-gate.ts", "src/core/delegation*", "src/core/dispatch.ts"]
+  citations:
+    - id: admission
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [1071, 1089]
+      symbol: createNativeRunTools
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:3b01bdf1c2104b1ce1256bff22b131b94943ce8fae5ff755da9b1ecabb225734
+    - id: wait
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [1098, 1121]
+      symbol: createNativeRunTools
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:095375a8e7a54af34aa1e4661fce4b44a2e500487c164d1c5c4dcd8d577e9bd5
+    - id: persist
+      repo: github:wardby/wardby
+      path: src/core/runner.ts
+      lines: [1175, 1182]
+      symbol: onPersisted
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:dbee201f976e3b74fffa64b5812e39c55bf86481e47abba414772f2deeb3c085
+  confidence: high
+---
+
+Parallel delegation uses a per-attempt admission gate to keep the prior-child and delegation-limit checks together with child creation. Waiting child IDs participate in those checks even before they have a persisted run.[^admission] A budget waiter registers its child ID before releasing the gate, then reacquires the gate before removing that registration.[^wait] Coding dispatch releases the gate when the child row is persisted, allowing execution to overlap without overlapping admission.[^persist]
+
+**What to do:** preserve the waiting-child reservation when changing retry or dispatch paths; releasing it early can admit the same child twice or exceed the delegation count. Holding the gate through child execution instead serializes the batch. [Coding-agent setup, budgets](../coding-agent-setup.md) already describes sibling budget waits; this concept records the admission consequence rather than repeating that behavior.
+
+[^admission]: src/core/runner.ts, lines 1071-1089.
+
+[^wait]: src/core/runner.ts, lines 1098-1121.
+
+[^persist]: src/core/runner.ts, lines 1175-1182.

package/docs/knowledge/http-dispatcher-bootstrap.md

@@ -0,0 +1,61 @@
+---
+type: invariant
+title: HTTP compatibility depends on bootstrap order
+description: A Kubernetes client import can change built-in fetch behavior even when jobs use Docker.
+tags: [bootstrap, http, providers]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-17T08:24:27.356Z }
+sources:
+  - id: compatibility
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/http-runtime.ts#L5-L28
+  - id: install
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/core/http-runtime.ts#L92-L109
+  - id: bootstrap
+    url: https://github.com/wardby/wardby/blob/f4ac917fb05fd1118053462c98379c51289fed46/src/env.ts#L11-L27
+wardby:
+  schema: 1
+  roles: [planner, builder, reviewer]
+  affects:
+    [
+      "src/env.ts",
+      "src/core/http-runtime.ts",
+      "src/providers/executor/composition.ts",
+      "src/cli.ts",
+      "src/coding-proxy/main.ts",
+    ]
+  citations:
+    - id: compatibility
+      repo: github:wardby/wardby
+      path: src/core/http-runtime.ts
+      lines: [5, 28]
+      symbol: HTTP dispatcher compatibility
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:de45288094aaa10edabef6a2d28ee308536acda9d0a4b9cedb84794c6b4ee72d
+    - id: install
+      repo: github:wardby/wardby
+      path: src/core/http-runtime.ts
+      lines: [92, 109]
+      symbol: installHttpRuntime
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:9799d701991e03e908d4a357cad85121fe8bcd147259d03be6e1c95345a0471c
+    - id: bootstrap
+      repo: github:wardby/wardby
+      path: src/env.ts
+      lines: [11, 27]
+      symbol: bootstrap imports
+      sha: f4ac917fb05fd1118053462c98379c51289fed46
+      spanHash: sha256:71c46404eb01aceb2d30a7617bff1df60437a1ded819b7016fd9d8bc08a08363
+  confidence: high
+---
+
+Importing the Kubernetes client loads a different Undici generation, whose compatibility dispatcher can expose HTTP/2 headers in a shape Node's built-in fetch does not understand. The result is loss of response headers, affecting decompression and redirects across unrelated adapters. Executor composition imports that client even outside Kubernetes deployments.[^compatibility]
+
+The shared environment bootstrap installs an HTTP/1-only dispatcher before other runtime work. Its installed marker makes repeated calls a no-op; it does not continuously enforce which dispatcher remains installed.[^install][^bootstrap]
+
+**What to do:** keep the environment import first in runtime entry points and do not replace the global dispatcher later without preserving compatibility. Keep this bootstrap in the control-plane dependency tree; isolated coding-worker images have their own dependencies. See [configuration](overview-config.md) for the startup flow.
+
+[^compatibility]: src/core/http-runtime.ts, lines 5-28.
+
+[^install]: src/core/http-runtime.ts, lines 92-109.
+
+[^bootstrap]: src/env.ts, lines 11-27.

package/docs/knowledge/import-rename-target.md

@@ -0,0 +1,52 @@
+---
+type: invariant
+title: Import rename targets must be checked before creation
+description: Renaming a colliding entity onto another existing name would silently adopt that entity through idempotent creation.
+tags: [import, ownership, identity]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-16T18:34:00.557Z }
+sources:
+  - id: rename
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/preflight.ts#L38-L61
+  - id: abort
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/index.ts#L98-L106
+  - id: upsert
+    url: https://github.com/wardby/wardby/blob/744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be/src/import/create.ts#L134-L155
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/import/**"]
+  citations:
+    - id: rename
+      repo: github:wardby/wardby
+      path: src/import/preflight.ts
+      lines: [38, 61]
+      symbol: resolveCollision
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:c9d7a0099b2a8da51423969af1f92d314287f0ae32fb708ebec731b2796fbee5
+    - id: abort
+      repo: github:wardby/wardby
+      path: src/import/index.ts
+      lines: [98, 106]
+      symbol: runImport
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:e7463bf861fefd8157eaa21c951c8f635fe2b41d25f80e4d77c500eae82021a4
+    - id: upsert
+      repo: github:wardby/wardby
+      path: src/import/create.ts
+      lines: [134, 155]
+      symbol: createFromBundle
+      sha: 744d27eb926ccf7eafe52c98ac2af7f9bcd5c1be
+      spanHash: sha256:010d97c925923a101c0cedb4d148e39f6ba70aec7b0f4e1d2355fddb4855e6a8
+  confidence: high
+---
+
+Preflight treats an occupied prefixed rename target as fatal even under the rename policy. The orchestrator returns before creation on fatal collisions; creation later upserts agents with an empty update branch.[^rename][^abort][^upsert]
+
+**Why:** a free-looking rename that lands on an existing name can return the existing agent without changing it, after which import attachments would target that identity. Preserve target validation before idempotent creation; it is an identity boundary, not just nicer collision reporting.
+
+[^rename]: src/import/preflight.ts, lines 38-61.
+
+[^abort]: src/import/index.ts, lines 98-106.
+
+[^upsert]: src/import/create.ts, lines 134-155.

package/docs/knowledge/index.md

@@ -0,0 +1,57 @@
+# Architecture knowledge
+
+## Overviews
+
+- [MCP management and authorization](overview-mcp.md) — Transport identity becomes scoped management calls over owned resources and explicit grants.
+- [Configuration and process bootstrap](overview-config.md) — Environment loading precedes typed feature settings and provider composition.
+- [Run admission and execution](overview-core.md) — Dispatch persists admitted work before executors drive native or coding runs and recovery settles orphans.
+- [Coding inputs and isolated workers](overview-coding.md) — Shared protocols connect trusted run preparation to Codex or Claude Code workers and host finalization.
+- [Coding proxy and package mediation](overview-coding-proxy.md) — Run capabilities gate model reservations, package policy and optional dependency snapshots.
+- [Native tool and worker isolation](overview-sandbox.md) — QuickJS evaluates user tools while a run-bound gateway retains privileged effects and native worker authority.
+- [Provider composition and routing](overview-providers.md) — Interfaces separate orchestration from concrete model, execution, identity, persistence and source-control adapters.
+- [Durable data and migration boundaries](overview-prisma.md) — Relational definitions and migrations persist identity, run lifecycle, accounting and integration state.
+- [Deployment topology and infrastructure](overview-deploy.md) — Terraform, Compose and Kubernetes assets connect trusted services to isolated workers and durable storage.
+- [CLI bootstrap and bundle import](overview-cli.md) — Command entry points assemble local installations, invoke runtime services and reconcile imported resources.
+- [Viewer, observability and knowledge tooling](overview-surfaces.md) — Read projections, metrics and cited knowledge expose runtime state and architecture without owning execution.
+
+## Invariants
+
+- [HTTP compatibility depends on bootstrap order](http-dispatcher-bootstrap.md) — A Kubernetes client import can change built-in fetch behavior even when jobs use Docker.
+- [Pricing races must use the persisted winner](run-pricing-first-writer.md) — Concurrent native attempts must reuse the catalog terms that won the conditional pricing write.
+- [Private datastore wrappers must reject shared methods](private-datastore-shared-boundary.md) — Prefix restrictions on private keys cannot authorize the provider shared-store methods.
+- [Failed workspace fills must remain untrusted](workspace-staging-failure.md) — Collection failure must not expose a partially materialized worker tree to validation or trusted replacement.
+- [Import rename targets must be checked before creation](import-rename-target.md) — Renaming a colliding entity onto another existing name would silently adopt that entity through idempotent creation.
+- [Viewer notifications must not abort authoritative writes](viewer-notify-write-isolation.md) — The viewer trigger contains notification errors so event delivery cannot fail run persistence.
+- [Blob absence must distinguish missing infrastructure](blob-not-found-semantics.md) — Mapping a storage outage to not_found can delete valid dependency snapshot metadata.
+- [Warm input publication must refuse replacement](warm-input-publication.md) — Atomic visibility alone is insufficient when one warm worker may receive its capability only once.
+- [Proxy usage projections must not govern settlement](proxy-settlement-projections.md) — Run totals are rebuilt from settled requests while per-model reporting failures are isolated by a savepoint.
+- [Untrusted file bounds belong to the open descriptor](bounded-file-descriptor.md) — Checking a path before reading it leaves file substitution and growth races across worker boundaries.
+- [Agent authorization must share the mutation transaction](transactional-agent-authorization.md) — Using the default access client inside a transaction disconnects grant reads from mutation isolation.
+- [Budget-waiting delegations retain admission slots](delegation-admission-slots.md) — Releasing the delegation gate during a budget wait must preserve duplicate-child and delegation-limit accounting.
+- [Schedule deduplication belongs to the transaction](schedule-claim-transaction.md) — A scheduler lease cannot replace the atomic schedule-window claim and run creation.
+- [Terminal run state belongs to the first writer](terminal-run-first-writer.md) — Run completion must conditionally write pending or running rows and read back the persisted winner.
+- [Task cancellation takes precedence over run status](mcp-cancelled-task-precedence.md) — A cancelled task remains cancelled even if its underlying run finishes with a different terminal outcome.
+- [Secret entry replicas must share token verification](secret-entry-replica-contract.md) — A shared outcome database cannot complete a secret-entry round trip when replicas use independent signing keys.
+
+## Decisions
+
+- [MCP schemas cross the SDK boundary as JSON](mcp-schema-module-boundary.md) — Using the SDK schema converter avoids incompatible Zod instances at tool registration.
+
+## Pitfalls
+
+- [Nullable tool ownership leaves a uniqueness gap](nullable-tool-uniqueness.md) — The owner-and-name unique index does not deduplicate ownerless tools in PostgreSQL.
+- [HTTP prompt discovery cannot use per-call identity](mcp-http-prompt-discovery.md) — The HTTP factory exposes everyone-readable agent prompts rather than the authenticated caller’s full agent set.
+
+## Coverage
+
+1. src/mcp/ (tools, auth, access, grants): covered 2026-10-17 (6 concepts)
+2. src/config/ and env handling: covered 2026-10-17 (2 concepts)
+3. src/core/ runner, scheduler, dispatch, budgets, delegation: covered 2026-10-17 (7 concepts)
+4. src/coding/ and src/coding-worker/, src/claude-*/ (coding runs, workers): covered 2026-10-17 (2 concepts)
+5. src/providers/coding-proxy/ (proxy, package registry): covered 2026-10-17 (3 concepts)
+6. src/sandbox/ and src/native-worker/ (native sandbox, isolation): covered 2026-10-17 (3 concepts)
+7. src/providers/ other seams (LLM, auth, storage, VCS, executors): covered 2026-10-17 (7 concepts)
+8. prisma/ (schema, migrations): covered 2026-10-17 (3 concepts)
+9. deploy/ (Terraform, Kubernetes, scripts): covered 2026-10-17 (2 concepts)
+10. src/quickstart/, src/import/, the CLI files in src/: covered 2026-10-17 (4 concepts)
+11. src/viewer/, src/observability/, src/knowledge/, src/tools/: covered 2026-10-17 (2 concepts)

package/docs/knowledge/log.md

@@ -0,0 +1,9 @@
+# Knowledge changes
+
+- 2026-10-15: Created the bundle index; added invariants for transactional agent authorization, delegation admission slots, transactional schedule claims, and first-writer terminal run state.
+
+- 2026-10-15: Added the coverage map, retaining existing MCP and core coverage; completed MCP and config discovery, added schema-boundary, HTTP prompt-discovery, task-cancellation and secret-entry replica contracts, and re-anchored three moved delegation citations. Later uncovered areas remain for the next coverage run.
+
+- 2026-10-16: Completed coverage discovery for areas 4–11; added descriptor-bound file reads, proxy settlement projections, warm input publication, blob absence semantics, nullable tool uniqueness, viewer notification isolation, and import rename-target contracts. Re-anchored eight moved citations across delegation admission, schedule claims, terminal run state, and transactional authorization; existing claims remain current.
+
+- 2026-10-17: Added one overview for each of the eleven coverage areas and completed discovery across all areas; added HTTP dispatcher bootstrap, first-writer pricing, private/shared datastore separation and failed workspace staging contracts. Existing citations and claims remain unchanged; refreshed coverage dates and counts, including overviews and cross-area concepts.

package/docs/knowledge/mcp-cancelled-task-precedence.md

@@ -0,0 +1,41 @@
+---
+type: invariant
+title: Task cancellation takes precedence over run status
+description: A cancelled task remains cancelled even if its underlying run finishes with a different terminal outcome.
+tags: [mcp, execution, cancellation]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: read
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tasks/manager.ts#L108-L144
+  - id: cancel
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/tasks/manager.ts#L155-L171
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/tasks/**", "src/mcp/tools/trigger.ts"]
+  citations:
+    - id: read
+      repo: github:wardby/wardby
+      path: src/mcp/tasks/manager.ts
+      lines: [108, 144]
+      symbol: getTask
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:57fcf902067b811f63548e01e7008a5dfadd4504156904dc96ad26c68c323ea8
+    - id: cancel
+      repo: github:wardby/wardby
+      path: src/mcp/tasks/manager.ts
+      lines: [155, 171]
+      symbol: cancelTask
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:68e640003a1eb74a96bab385cde0c8a658df6a2902ca10cb76a39d35ad5f60b7
+  confidence: high
+---
+
+Ordinary task reads derive status from the run, but first return a persisted task cancellation without reading that run. Cancellation checks that the run is active, invokes the stop hook, then stamps the task cancelled; it does not stamp tasks whose runs were already terminal.[^read][^cancel]
+
+**Why:** the run can finish between the active-state check and cancellation. Preserve the task-level precedence rather than synchronizing its status back from the run: cancellation of the task and the authoritative run outcome are separate facts. [Native sandbox](../native-sandbox.md) describes stopping execution; this concept records the task projection consequence.
+
+[^read]: src/mcp/tasks/manager.ts, lines 108-144.
+
+[^cancel]: src/mcp/tasks/manager.ts, lines 155-171.

package/docs/knowledge/mcp-http-prompt-discovery.md

@@ -0,0 +1,41 @@
+---
+type: pitfall
+title: HTTP prompt discovery cannot use per-call identity
+description: The HTTP factory exposes everyone-readable agent prompts rather than the authenticated caller’s full agent set.
+tags: [mcp, access, discovery]
+status: stable
+generated: { by: wardby-architect/gpt-6.1-sol, at: 2026-10-15T11:18:44.473Z }
+sources:
+  - id: context
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L211-L235
+  - id: prompts
+    url: https://github.com/wardby/wardby/blob/0cd83fece6e5dafbb229aee4c293953e354cb42d/src/mcp/server.ts#L300-L332
+wardby:
+  schema: 1
+  roles: [builder, reviewer]
+  affects: ["src/mcp/server.ts", "src/mcp/transport/**"]
+  citations:
+    - id: context
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [211, 235]
+      symbol: resolveCtx
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:e44772fb56c6bd94fe80f9a217ad26e1a5a580cd380f363db476fa206d4ba288
+    - id: prompts
+      repo: github:wardby/wardby
+      path: src/mcp/server.ts
+      lines: [300, 332]
+      symbol: factory
+      sha: 0cd83fece6e5dafbb229aee4c293953e354cb42d
+      spanHash: sha256:e2b7273522836d35f55b7bf068062a488b1eae0cd47520d35a67f89acd0f731f
+  confidence: high
+---
+
+HTTP identity is resolved from each dispatched call, after the server factory builds the prompt list. The factory therefore registers only agents granted at least read to everyone; stdio can use its already established fixed context. Failure to build this optional list does not prevent tool registration.[^context][^prompts]
+
+**What to do:** do not treat a missing HTTP prompt as proof that the caller lacks agent access, or widen the factory’s query to all agents. Caller-specific discovery needs request identity before prompt registration.
+
+[^context]: src/mcp/server.ts, lines 211-235.
+
+[^prompts]: src/mcp/server.ts, lines 300-332.