@wardby/cli 0.6.0 → 0.7.0

package/docs/getting-started-gke.md

@@ -50,6 +50,7 @@ Install and authenticate:
 - `kubectl`
 - Helm 3 or later (installs External Secrets Operator)
 - Node.js 24 and npm
+- `curl`, `openssl` and `base64` (the database grants step uses them)
 
 You also need:
 
@@ -200,7 +201,9 @@ refuses to start with either one set and no token.
 `WARDBY_GITHUB_ALLOWED_ACCOUNTS` (optional, not a secret) adds GitHub accounts
 the App serves besides its owner. Pass it to `up.sh` on every run, for example
 `WARDBY_GITHUB_ALLOWED_ACCOUNTS=acme-labs WARDBY_HOSTNAME=app.example.com deploy/gke/up.sh`;
-a run without it serves only the App's owner. See
+a run without it serves only the App's owner. `up.sh` gives the same value to
+the control plane and to the native sandbox gateway, which runs sandboxed
+agents' repository tools. See
 [Which accounts the App serves](code-review-agents.md#which-accounts-the-app-serves-wardby_github_allowed_accounts).
 
 `WARDBY_MOBILE_ENABLED=true` (optional, not a secret) lets the Wardby mobile app
@@ -210,6 +213,11 @@ sign-in off. It works for normal and low-power deploys. White-label builds that
 use their own redirect URI add `WARDBY_MOBILE_REDIRECT_URI` to the control
 plane's `env` themselves. See the help article `mobile-app`.
 
+`WARDBY_MENTION_EXPLANATIONS=false` (optional, not a secret) stops the GitHub
+App replying to say why a mention started nothing; pass it to `up.sh` on every
+run, the same way. See
+[What a linked review agent does](code-review-agents.md#what-a-linked-review-agent-does).
+
 Generate `SECRET_APP_KEY` with:
 
 ```sh
@@ -315,10 +323,9 @@ Allow DNS and the managed certificate to converge before treating an HTTPS
 failure as an application failure.
 
 On a brand-new project, run `terraform apply` and then
-`bootstrap-database-iam.sh` before `up.sh`: the bootstrap has to grant the
-migrator before any migration can run. See "Database login" below for the
-exact order, including the database check `up.sh` doesn't pass until a second
-bootstrap run has granted the coding proxy too.
+`bootstrap-database-iam.sh` once before the first `up.sh`: the bootstrap has to
+grant the migrator before any migration can run. See "Database login" below
+for the exact order.
 
 ### Database login
 
@@ -327,20 +334,19 @@ through the Cloud SQL Auth Proxy, via Workload Identity from one Kubernetes
 service account. What each may do inside the database comes from a `NOLOGIN`
 group role in `deploy/gke/database-grants.sql`:
 
-| Workload       | Google service account   | Kubernetes service account | May do                                                                                                                                                                                          |
-| -------------- | ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Control plane  | `<name_prefix>-app`      | `wardby-control-plane`     | `wardby_app`: read/write every table, including the durable executor's in schema `dbos`; never change a schema                                                                                  |
-| Coding proxy   | `<name_prefix>-proxy`    | `wardby-coding-proxy`      | `wardby_proxy`: only its budget ledger — `CodingProxySession`/`CodingProxyRequest`/`RunModelUsage`, plus update `tokensIn`, `tokensOut`, `costUsd` and `turns` on `Run`, and read only its `id` |
-| Native gateway | `<name_prefix>-gateway`  | `wardby-native-gateway`    | Member of `wardby_app`: the same data access as the control plane, under its own login (see [Native sandbox](#native-sandbox))                                                                  |
-| Migrations     | `<name_prefix>-migrator` | `wardby-migrator`          | Acts as the table owner (`SET ROLE`), so `prisma migrate deploy` and `dbos schema` can alter and create tables                                                                                  |
+| Workload       | Google service account   | Kubernetes service account | May do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------- | ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Control plane  | `<name_prefix>-app`      | `wardby-control-plane`     | `wardby_app`: read/write every table, including the durable executor's in schema `dbos`; never change a schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Coding proxy   | `<name_prefix>-proxy`    | `wardby-coding-proxy`      | `wardby_proxy`: its budget ledger (`CodingProxySession`/`CodingProxyRequest`/`RunModelUsage`: read, insert, update), the package registry's tables (`RegistryAllowance`, `RegistryFetch`, `RegistryAuditRecord`, `RegistryVersionFact`, `RegistryApprovedVersion`, `RegistryPlanRefusal`: read and insert only), the dependency cache's `DependencySnapshot` (read, insert, update, delete), update `tokensIn`, `tokensOut`, `costUsd` and `turns` on `Run` and read only its `id`, and read only the `runId`, `packageAllowlist`, `packagePolicy`, `repository`, `workerImage`, `toolImage`, `dependencyCache` and `packageAuditMode` columns of `CodingRun` |
+| Native gateway | `<name_prefix>-gateway`  | `wardby-native-gateway`    | Member of `wardby_app`: the same data access as the control plane, under its own login (see [Native sandbox](#native-sandbox))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Migrations     | `<name_prefix>-migrator` | `wardby-migrator`          | Acts as the table owner (`SET ROLE`), so `prisma migrate deploy` and `dbos schema` can alter and create tables                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 `deploy/gke/bootstrap-database-iam.sh` applies the grants as the built-in
-owner, from a short-lived Job inside the cluster. Run it whenever
-`database-grants.sql` changes, before deploying the release that needs the new
-grants (`bootstrap-database-iam.sh --check`, then `bootstrap-database-iam.sh`,
-then `up.sh`), and as part of the orders below. A release deployed ahead of its
-grants fails with "permission denied" wherever it uses one it doesn't have yet.
-The grants run in one transaction, so a statement the database refuses leaves
+owner, from a short-lived Job inside the cluster. `up.sh` runs it on every
+deploy, after the migrations and before the rollout (see
+[Upgrading an existing deployment](#upgrading-an-existing-deployment)); you
+run it by hand only on a brand-new project, below, or with `--check`. The
+grants run in one transaction, so a statement the database refuses leaves
 nothing applied.
 
 The built-in owner is not a Terraform resource: `bootstrap-database-iam.sh`
@@ -349,119 +355,28 @@ SQL Admin API, uses that password once to apply the grants, and resets it to
 a value nobody holds on every exit, including a failed grant. No password is
 ever stored, printed, or passed as a process argument.
 
-A deployment that already runs and then gains the native gateway identity from
-`terraform apply` runs `deploy/gke/bootstrap-database-iam.sh` once, so the
-gateway's user gets its `wardby_app` membership, and then `deploy/gke/up.sh`.
-`up.sh`'s database check also tests the native gateway and says so if the
-grant is missing.
-
 A brand-new project runs, in this order:
 
 1. `terraform -chdir=deploy/gke apply` — creates the cluster, the instance
    and the four IAM database users. Run it yourself rather than through
    `up.sh`, which would go on to the migrations before the migrator has its
    grants.
-2. `deploy/gke/bootstrap-database-iam.sh` (default mode) — fetches the
-   cluster's kubectl credentials if you don't have them yet, creates the
-   owner, and applies the migrator's (and the app's) grants. The coding
-   proxy's ledger tables don't exist yet, so its grants are skipped: expected.
-3. `deploy/gke/up.sh` — applies the migrations and rolls out, then stops at
-   the database check: the coding proxy's grants are on tables that did not
-   exist in step 2.
-4. `deploy/gke/bootstrap-database-iam.sh` again — now that the tables exist,
-   also applies the coding proxy's ledger grants.
-5. `deploy/gke/up.sh` — rolls out again and passes every check.
-
-Two bootstrap runs, not one: a grant on a named table can't apply before the
-migration that creates that table has run.
-
-The same applies to every later release that adds a table the coding proxy
-uses: run `bootstrap-database-iam.sh` again after its migration. `up.sh`
-checks this for you. After the rollout it asks the database, as the proxy's
-own role, for every privilege `database-grants.sql` gives `wardby_proxy`
-(`deploy/gke/proxy-grant-checks.mjs`), and stops with the list of missing
-grants instead of letting the proxy fail registry requests with "permission
-denied".
-
-After upgrading an existing deployment to a release with cost attribution,
-re-run `bootstrap-database-iam.sh` so the coding proxy can record per-model
-usage for coding runs (used by the `cost_report` tool's `model` grouping).
-Until then coding runs still work, but their per-model breakdown isn't
-recorded.
+2. `deploy/gke/bootstrap-database-iam.sh` — fetches the cluster's kubectl
+   credentials if you don't have them yet, creates the owner, and applies the
+   migrator's (and the app's) grants. Grants on tables that don't exist yet
+   are skipped: expected.
+3. `deploy/gke/up.sh` — applies the migrations, then the grants again (now
+   that every table exists), then rolls out and passes every check.
 
 `bootstrap-database-iam.sh --check` runs the grants inside a transaction that
 is then rolled back, and reports success or the exact statement the database
-refused, without changing anything. Run it before the real run on a live
-deployment.
+refused, without changing any grant. Use it to see why a grants step failed.
 
 `connector_enforcement` (the Cloud SQL instance setting) defaults to
 `REQUIRED`: it refuses any connection that does not come through the Auth
 Proxy or a Cloud SQL connector, and with port 5432 to the instance closed in
 every NetworkPolicy, there's no route left for a plain Postgres connection to
-even attempt. Leave it at the default; an older deployment still on password
-login moves off it on an earlier revision of this module, below.
-
-### Moving an older deployment
-
-A deployment still on password login — from before this module retired it —
-can't adopt this revision directly: this revision no longer syncs the
-password `DATABASE_URL`, closes port 5432 and refuses non-Auth-Proxy
-connections, which would cut off pods still logging in with the password.
-It moves over in stages, because real pods are already serving traffic
-throughout.
-
-**1–2. Cut the running pods to IAM login, on the revision before this one.**
-Check out the revision of this module that added IAM login, before the
-password was retired: the merge of pull request #83 into `main`.
-`git log --oneline --first-parent main -- deploy/gke` lists the merges that
-changed this module, newest first; it's the one titled
-`Merge pull request #83 ...`, just below the merge that retired the password
-(`git log --oneline --merges --grep='#83' main` finds it directly). Then
-`git checkout <that commit>` and follow that revision's own
-`docs/getting-started-gke.md`, "Database login", and its order for "an
-existing deployment still on password login": `bootstrap-database-iam.sh
---password-from-stdin --check`, the same without `--check`, then `up.sh`.
-That rolls out password-less pods while the password still works as a
-fallback, and proves the control plane and the coding proxy each read the
-database through their own IAM login. That revision's
-`connector_enforcement` default is still `NOT_REQUIRED`, so nothing that
-still uses the password is cut off. Then return to this revision
-(`git checkout main`) for the last stage.
-
-**3. Retire the password**, once every pod speaks IAM login and this change
-has merged to `main`:
-
-1. Confirm nothing still uses the password: both Deployments' pods log in as
-   IAM users, and no pod has a password `DATABASE_URL` in its effective env.
-2. Delete the `database-url` Secret Manager secret:
-   `gcloud secrets delete <name_prefix>-database-url --quiet` — this module no
-   longer creates or reads it. Deleting it by hand first, before the next
-   step, is what lets Terraform drop it from state instead of trying to
-   destroy it.
-3. Remove any `connector_enforcement` line from `terraform.tfvars` (or set
-   it to `REQUIRED`), so the new default takes effect. Then `terraform plan`:
-   expect the generated password destroyed, the `database-url` secret and
-   its IAM binding gone from state (already deleted by hand), the old
-   password-login user forgotten (not destroyed), `connector_enforcement`
-   moving to `REQUIRED` on the instance (updated in place, not replaced),
-   and no other destroy. Review
-   the plan, then apply only once it matches that. If apply still fails
-   trying to destroy the `database-url` secret, the secret wasn't actually
-   deleted in step 2 — delete it and re-apply. Never turn off
-   `secrets_deletion_protection` to get past that error: it unprotects every
-   other secret in the same set, including `SECRET_APP_KEY` and the auth
-   keys, and losing `SECRET_APP_KEY` makes every credential already stored
-   in the database unreadable.
-4. `deploy/gke/up.sh` — new ExternalSecrets carry no `DATABASE_URL`,
-   NetworkPolicies no longer allow 5432, migrations, rollout, and the
-   database and endpoint checks.
-5. `deploy/gke/bootstrap-database-iam.sh` (default mode) — the guard now
-   passes, since the Secret no longer has a `DATABASE_URL`: it sets a
-   one-time owner password, reapplies the grants, and resets the password to
-   a value nobody holds.
-6. Verify: a direct password connection is refused (NetworkPolicy blocks
-   5432, and the instance refuses it too), the pods still log in through
-   IAM, and the Terraform state holds no database password.
+even attempt. Leave it at the default.
 
 ## 7. Verify
 
@@ -552,6 +467,38 @@ roll; if it fails, `up.sh` prints the `migrate` and `cloud-sql-proxy` container
 logs (and, if those are empty or the Job timed out, the Job's and pod's
 events), then stops.
 
+### Upgrading an existing deployment
+
+To upgrade, check out the new release and re-run `deploy/gke/up.sh`. No
+manual database step is needed: `up.sh` applies the migrations, then the
+database grants (`deploy/gke/bootstrap-database-iam.sh`, which applies
+`deploy/gke/database-grants.sql`), and only then rolls out the new pods. A
+release that adds a table, a column, or a workload that needs a new grant
+therefore never runs without it.
+
+- **If the migrations fail**, `up.sh` stops before the grants and the
+  rollout; the running version is untouched.
+- **If the grants fail**, `up.sh` stops before the rollout with a non-zero
+  exit; the running version keeps serving. The migrations already applied
+  are additive, so the running version tolerates them. Run
+  `deploy/gke/bootstrap-database-iam.sh --check` to see the exact statement
+  the database refused without changing anything, fix the cause, and re-run
+  `up.sh`.
+- **After the rollout**, `up.sh` checks that each new pod can read the
+  database, and asks the database, as the coding proxy's own role, for every
+  privilege `database-grants.sql` gives it
+  (`deploy/gke/proxy-grant-checks.mjs`). A missing grant stops the deploy
+  with a non-zero exit and the list of what's missing, rather than letting
+  the proxy fail registry requests with "permission denied".
+
+Never run two `up.sh` deploys against the same project at once: both would
+run migrations, set and reset the database owner's password, and roll out
+over each other. Nothing locks against it, so wait for one to finish.
+
+You run `bootstrap-database-iam.sh` by hand only on a brand-new project,
+between `terraform apply` and the first `up.sh` (see
+[Database login](#database-login)), or as `--check` for a dry run.
+
 ### Durable executor
 
 The control plane runs native runs on the durable executor (`EXECUTOR=dbos`):
@@ -576,24 +523,33 @@ the step that was in flight runs again. Coding runs are Kubernetes Jobs and are
   `up.sh` re-run whose source did not change, runs continue. When you deploy
   new code, the old pod first **drains**: after its 30-second `preStop` it
   stops the scheduler and waits for the runs it is executing to finish, up to
-  `SHUTDOWN_DRAIN_SECONDS` (default 600), while the new pod serves traffic.
-  An idle pod exits at once. A run still going after that limit is marked
-  `lost`; if an `@`-mention started it, its status comment on GitHub says the
-  request was interrupted and should be repeated. The manifest's
-  `terminationGracePeriodSeconds` (720) must stay above the drain limit plus
-  the `preStop` delay.
+  `SHUTDOWN_DRAIN_SECONDS` (540 in the GKE manifest), while the new pod
+  serves traffic. Open HTTP connections, such as a connected MCP client's
+  stream, get 10 seconds to finish and are then closed; clients reconnect to
+  the new pod.
+  An idle pod exits at once. A native run that is waiting in a `delegate_to_*`
+  call on a coding sub-agent or a sandbox-mode native sub-agent is taken over
+  by the new version: it continues when the sub-agent finishes, without
+  repeating the turns it already took. A run that was mid-turn, waiting on
+  another tool, or waiting on a control-plane native sub-agent is marked
+  `lost` rather than taken over, as is a taken-over run whose recorded steps
+  no longer match the new code, and a run still going after the drain limit.
+  The sub-agent runs a lost run started are stopped (reason
+  `parent run lost`). If an `@`-mention started a lost run, its status comment
+  on GitHub says the request was interrupted and should be repeated. The
+  manifest's `terminationGracePeriodSeconds` (600) must stay above the drain
+  limit plus the `preStop` delay. Autopilot does not allow more than 600: a
+  larger value is lowered to 600, so to change the budget, lower
+  `SHUTDOWN_DRAIN_SECONDS` rather than raising the grace period.
 - **Data at rest and retention.** `dbos.operation_outputs` holds every step's
   output — prompts, model responses and full tool results — with no retention
   limit. Pruning finished workflows is the operator's job; see
   [Durable executor](security-deployment.md#durable-executor) for what is
   stored and how to prune it with `DBOS.deleteWorkflow`.
 
-**Enabling it on an existing deployment.** The grants changed, so apply them
-before deploying: run `deploy/gke/bootstrap-database-iam.sh --check`, then
-`deploy/gke/bootstrap-database-iam.sh`, then `deploy/gke/up.sh`. Without the
-grants the new control-plane pod crash-loops with "permission denied" while
-the old one keeps serving, and `up.sh` stops at the rollout. On a brand-new
-project the order under "Database login" already covers it.
+**Enabling it on an existing deployment.** Re-run `deploy/gke/up.sh`: it
+applies the durable executor's grants before the rollout (see
+[Upgrading an existing deployment](#upgrading-an-existing-deployment)).
 
 **Switching back** to the in-process executor: set `EXECUTOR` to `in-process`
 in `deploy/kind-coding/manifests/overlays/gke-autopilot/control-plane.yaml`
@@ -643,10 +599,10 @@ control plane is configured with `NATIVE_SANDBOX_LAUNCHER=kubernetes`,
 `NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS=60000`. Worker pods use the gVisor runtime
 class, `KUBERNETES_PLATFORM=gke-autopilot`, and the run priority class.
 
-- **One-time bootstrap.** The gateway has its own database login. After
-  `terraform apply` adds its identity to an existing deployment, run
-  `deploy/gke/bootstrap-database-iam.sh` once, then `deploy/gke/up.sh`; see
-  [Database login](#database-login).
+- **Database login.** The gateway has its own database login. `up.sh`
+  applies its `wardby_app` membership before the rollout, so adding its
+  identity to an existing deployment needs no manual step; see
+  [Upgrading an existing deployment](#upgrading-an-existing-deployment).
 - **Enable per agent.** Nothing runs in the sandbox until you opt an agent in:
   set its `nativeExecutionMode` to `sandbox` with the `update_agent` MCP tool
   (native agents only).
@@ -723,6 +679,13 @@ low-power mode until its rollout ends, and the mark stops it scaling them back
 down. With the mode on they stay up through the deploy (its database checks
 need them) and sleep one idle window later if nothing uses them.
 
+**Failed replicas.** Without the headroom placeholder, a rollout is more likely
+to hit Autopilot's admission race: the node rejects a new pod with `OutOfcpu`
+and the Deployment starts a replacement. The rejected pod stays behind as a
+Failed pod. After the rollouts, `up.sh` deletes Failed pods of the control
+plane, coding proxy and native gateway (never coding-run or sandbox pods), and
+the Viewer shows any such leftover as an old replica rather than a failure.
+
 **Sleeping now.** To skip the idle window (for example right after a test), an
 admin calls the MCP tool `power_sleep`, optionally with `target` set to `proxy`
 or `gateway` (default both). It scales the target to 0 at once, but never stops
@@ -792,6 +755,32 @@ that schedules onto a fresh node — one that has never pulled the image before
 cached. Raise `KUBERNETES_READY_TIMEOUT_MS` if you see runs fail
 `service_unready` only on new nodes.
 
+### Run dependency cache
+
+Off by default. To keep npm `node_modules` snapshots for coding runs
+(see [Dependency cache](coding-packages.md#dependency-cache)), set
+`dependency_cache_enabled = true` and a unique `dependency_cache_bucket_name` in
+`terraform.tfvars`, and deploy with `WARDBY_DEPENDENCY_CACHE=true
+deploy/gke/up.sh` (it grants the coding proxy's role the `DependencySnapshot`
+table before the rollout; see
+[Upgrading an existing deployment](#upgrading-an-existing-deployment)). Keep
+`dependency_cache_max_age_days` equal to the proxy's
+`WARDBY_DEPENDENCY_CACHE_MAX_AGE_DAYS` (default 14). Details:
+[`deploy/gke/README.md`](../deploy/gke/README.md#run-dependency-cache).
+
+### Session transcripts
+
+Off by default. To keep the transcripts of Claude Code agents with
+`sessionResume` on (see
+[Resume a run locally](coding-agent-setup.md#resume-a-run-locally)), set
+`session_transcripts_enabled = true` and a unique
+`session_transcripts_bucket_name` in `terraform.tfvars`, and deploy with
+`WARDBY_SESSION_TRANSCRIPTS=true deploy/gke/up.sh`. The bucket is separate from
+the dependency cache bucket and only the control plane can use it; its
+lifecycle rule and the control plane's `RUN_TRANSCRIPT_RETENTION_DAYS` both
+come from `session_transcripts_retention_days` (default 30). Details:
+[`deploy/gke/README.md`](../deploy/gke/README.md#session-transcripts).
+
 ### Roll back
 
 Images are pinned by digest, so undoing a rollout restores exactly what ran
@@ -803,11 +792,9 @@ kubectl -n wardby-coding rollout undo deploy/wardby-coding-proxy
 kubectl -n wardby-coding rollout undo deploy/wardby-native-gateway
 ```
 
-`rollout undo` restores only the Deployments' images and pod templates — there
-is no password path to fall back to any more, so a rollback is safe only for
-a version that still speaks IAM login. It does not touch any NetworkPolicy: a
-change to the database egress rules themselves is not undone by `rollout
-undo`.
+`rollout undo` restores only the Deployments' images and pod templates. It
+does not touch the database grants or any NetworkPolicy: a change to the
+database egress rules themselves is not undone by `rollout undo`.
 
 Database migrations only go forward: a rollback does not undo a schema change.
 That is safe while every migration is additive (new tables, nullable columns,

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

@@ -190,7 +190,10 @@ 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
@@ -212,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:

package/docs/getting-started.md

@@ -422,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

@@ -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
@@ -574,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.
 
@@ -602,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.