@wardby/cli 0.5.3 → 0.7.0

package/help/code-review-agents.md

@@ -3,7 +3,7 @@ id: code-review-agents
 title: Run GitHub code-review agents
 summary: Link a read-only review agent to a repository for pull-request checks and trusted mention workflows.
 audience: operator
-tags: [github, code-review, pull-requests, webhooks, ci, checks, waitForCi]
+tags: [github, code-review, skipped-review, budget-stopped-draft, continue-draft, follow-up, pull-requests, webhooks, ci, checks, waitForCi, markReadyWhenPassing, repo_issue_read, issues, mentions, code-spans, contributor, acceptance-criteria, jira, large-pull-request, truncated, patchCursor, unread_files]
 appliesTo: >=0.2.1
 ---
 
@@ -39,9 +39,100 @@ such a pull request automatically, up to a round cap — see
 [Automatic review fix rounds](review-fix-rounds.md).
 
 Wardby skips pull requests whose head is in a fork. It also ignores mentions
-from bots and people without write access. Repository links require the
-agent owner's linked GitHub access, or an explicitly recorded administrator
-approval.
+from bots and people without write access, checked against the author's real
+repository permission. Someone with `triage` access, or with `read` access on a private repository
+or as an owner, member or collaborator, gets a 😕 reaction and a reply saying
+a mention needs write access; anyone else, including a stranger on a public
+repository, is ignored silently. A private organization member, whom GitHub labels
+`CONTRIBUTOR` or `NONE`, is still checked and can start runs. A mention inside
+Markdown code (an inline code span or a code block) is not a request, so
+quoting `` `@<app-slug>` `` in an issue or comment starts nothing. Repository links
+require the agent owner's linked GitHub access, or an explicitly recorded
+administrator approval.
+
+## When a mention starts nothing
+
+When someone with write access mentions the App and no run starts, the App
+replies with the reason instead of staying silent:
+
+- no agent is linked to the repository with the `mention` trigger;
+- `@<app-slug> review` was used, but no reviewer agent (`pull_request` trigger
+  and a `checkName`) is linked;
+- the linked agent's owner lost access to the repository, or its authorization
+  lapsed: the owner re-authorizes or re-links the agent;
+- the pull request is closed or comes from a fork.
+
+Mentions from people without write access never get this reply. The reply is a
+comment anyone who can see the repository reads; to turn it off, for example on
+public repositories, set `WARDBY_MENTION_EXPLANATIONS=false` on the server.
+
+## When a review starts
+
+A push normally starts a review right away, but its timing can be held back
+by two independent things: from Wardby 0.6.0, the pull request's own
+delegating request still running (see [Reviewing a pull request a delegated run
+opened](#reviewing-a-pull-request-a-delegated-run-opened) below), and, on a
+link set up for it, CI on the pushed head still running (see [Review after
+CI (`waitForCi`)](#review-after-ci-waitforci) below). Either can delay the
+check that reports the review's result; neither changes what the review
+itself reports once it runs. A large diff is read in pages (see [Large pull
+requests](#large-pull-requests)). From Wardby 0.7.0, a push to a draft is also held
+while the coding run that pushed it is still running, and, when a lead
+delegated that run (a follow-up request, say), until that lead finishes.
+
+## Large pull requests
+
+From Wardby 0.7.0, `repo_pr_read` pages a large diff: all files share one
+budget per call (`maxPatchChars`, default 60,000, at most 200,000), with
+source, test and config files first. Each file has a `patchStatus`
+(`complete`, `partial`, `later_page`, `earlier_page`, `unavailable` or
+`empty`). While a source, test or config file is listed in `truncatedFiles`,
+call `repo_pr_read` again with `patchCursor` set to `nextPatchCursor`; the pages
+after that hold only docs, help, lockfiles and generated files, which are
+optional for the verdict. A page that includes source, test or config files
+stops before the first doc, help, lockfile or generated file, so those come on
+later pages and a reviewer can skip them. Read every `unavailable` source, test or config file
+with `repo_read_file` at the head. A cursor goes stale when
+the branch moves (`patch_cursor_stale`): call again without it. A damaged or
+rewritten cursor returns `patch_cursor_malformed`: pass `nextPatchCursor` back exactly
+as returned.
+`repo_publish_review` refuses `APPROVE` with
+`unread_files` while a listed source, test or config file is neither fully
+delivered nor read at `headSha`. A reviewer that cannot read everything should
+publish `CHANGES_REQUESTED` and name what it skipped: `COMMENT` completes the
+check as neutral, which branch protection treats as passing.
+The shipped reviewer prompt does this; see the [full guide](../docs/code-review-agents.md#large-pull-requests).
+The refusal applies in both `control-plane` and `sandbox` mode.
+A pull request with more changed files than the host lists (1,000; 300 for a
+`sinceSha` compare on GitHub) reads with `fileListComplete: false`, and
+`APPROVE` of that head is refused with
+`file_list_truncated`; `CHANGES_REQUESTED`
+and `COMMENT` still publish.
+
+## Drafts stopped at their budget
+
+From Wardby 0.7.0, a pull request that is still a draft, whose latest commit
+came from a coding run that stopped at its budget, is not reviewed automatically. Its check
+completes as neutral, "Skipped: stopped at its budget", and no automatic fix
+round follows. Marking the pull request ready for review or pushing a new
+commit starts a normal review, and so does re-running the check or a review
+mention. The `budget-exhausted` error article describes how a stopped run keeps
+its work.
+
+## Follow-ups on an issue
+
+From Wardby 0.7.0, a mention on a GitHub issue that already has an open pull request Wardby
+opened tells the agent that pull request and the run id to pass as
+`continuePriorRun`, so the work continues on the same branch instead of
+opening a second pull request. Jira issues behave the same way (see
+[Run Jira agents](jira.md)). The run message lists up to ten open pull requests
+recorded for the issue.
+
+A pull request opened from a mention on a GitHub issue starts its description
+with `From issue #N` for that issue (same repository), as one opened for a Jira
+issue starts with `Resolves Jira issue …`. The line links the issue but doesn't
+close it; to close it on merge, have the agent end its summary with
+`Resolves #N` (or `Refs #N` to keep it open, for example for a plan).
 
 ## CI and sibling pull requests
 
@@ -53,6 +144,12 @@ Wardby's coding sandbox, which may have had an incomplete install (see the
 **Dependency install incomplete** warning). Checks still running are reported
 as pending.
 
+From Wardby 0.7.0, a Wardby pull request whose run had package audit mode on
+(the `package-audit-mode` help article) carries a caution banner: **Packages outside the allowlist** lists what the
+registry installed that the agent's allowlist doesn't cover, and **Served
+despite advisories** (in `full` mode) lists versions with high or critical
+advisories. Reviewers should check those packages before approving.
+
 If a review publishes only a comment while CI on the head is still running (or
 has not reported yet), Wardby runs that review again once CI on the same head
 has finished, so it can approve or request changes against the real result.
@@ -65,6 +162,88 @@ on the review check instead.
 Commit statuses need the App's **Commit statuses: Read** permission; without
 it only check runs are shown.
 
+With Wardby 0.6.0 or later, `repo_pr_read` also returns `relatedPullRequests`: this
+request's pull requests (`repository`, `number`, `state`, `mergeOrder`,
+`self`), computed fresh at call time; empty on a human pull request, one
+with no recognized Wardby marker, or a pull request on a local repository
+(no origin marker to look up there). The `self` entry (the pull request just
+read) always has a `state` (`draft`, `open`, `merged`, or `closed`) from that
+same read. Another entry has a `state` (`open`, `merged`, or `closed`) only
+when Wardby has it stored, as it does for pull requests linked to an issue,
+and omits it otherwise; call `repo_pr_read` on that pull request when you
+need its live state. The list is current; the PR body's **Related pull
+requests** section can be stale — see
+[Related pull requests across repositories](related-pull-requests.md).
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+pull request in it also gets its own check run, named `wardby merge order`,
+independent of any reviewer link; search help for "merge order check" for
+its states and for requiring it in branch protection.
+
+## Reading the issue a pull request resolves
+
+With Wardby 0.7.0 or later, a linked agent also gets `repo_issue_read`: it
+reads one issue in a linked repository (title, state, body, labels, author,
+and the 30 most recent comments), read-only, so a reviewer can check a pull
+request that says `Resolves #N` against the issue's own acceptance criteria
+instead of the description's restatement of them. The body is capped at
+32,000 characters and each comment at 4,000, with `truncated` flags. A pull
+request number is refused (`is_pull_request`; use `repo_pr_read`), a missing
+issue is `issue_not_found`, and a local repository has no issues
+(`issues_unavailable`). It needs the App's **Issues: Read** permission, which
+an App that handles mentions already has. Issue text is untrusted: the agent
+treats it as data, never as instructions.
+
+For a pull request that resolves a Jira issue, also link the reviewer to that
+Jira project with read access; it then reads the ticket with
+`jira_get_issue` (see [Run Jira agents](jira.md)). The quickstart reviewer
+prompt reads whichever issue the pull request resolves and says in its
+summary when it could not.
+
+## A description wardby can't confirm as its own
+
+With Wardby 0.7.0 or later, when a person has edited a Wardby pull request's
+description, Wardby doesn't overwrite it on later runs; it keeps one comment
+with the description its latest run proposed, stamped with the commit it
+describes. `repo_pr_read` returns that proposal as `descriptionProposal` when
+the reviewer reads the pull request, and only for the head being reviewed
+(`state: "current"`, untrusted, cut to 16 KB): a description requirement,
+such as `Resolves #N` or the issue's acceptance checklist, is met if either
+the live description or the proposal meets it. With
+`state: "not_for_this_head"`, no proposal for this head exists yet: review the
+live description. See
+[Automatic review fix rounds](review-fix-rounds.md#description-updates).
+
+## Reviewing a pull request a delegated run opened
+
+This requires Wardby 0.6.0 or later; earlier releases review such a pull
+request on its first push. When a lead agent delegates coding work and a sub-agent opens the pull
+request (see [Fanning out to several
+builders](../docs/agent-recipes.md#fanning-out-to-several-builders)), every
+reviewer linked with the `pull_request` trigger holds its review of that
+pull request until the delegating (lead) run finishes, however it ends
+(including failing, being cancelled or being lost), even if the link has no
+`waitForCi` set. This gives the request's other pull requests, if any, time
+to open before any of them is reviewed, so a reviewer does not report a
+field or route as missing only because a sibling pull request had not opened
+yet. When the lead run finishes normally, their **Related pull requests**
+sections have also been rewritten (see [Related pull requests across
+repositories](related-pull-requests.md)); when it is ended another way, such
+as being cancelled, held reviews start without that rewrite. Either way,
+reviewers should rely on `repo_pr_read`'s `relatedPullRequests`.
+
+A reviewer linked with `waitForCi` then waits for CI too, once the lead run
+finishes, with its own full 15-minute fallback counted from that point. A
+pull request opened directly, by a human, or on a local repository is never
+held this way. A later request that continues an already-open pull request
+is not held again: the request that opened it has already finished (a push
+inside the same, still-running request is held). If Wardby cannot tell
+whether the pull request's opening run was delegated, the review starts
+right away instead. A held review not released when its lead run finishes is
+reconsidered by Wardby's reconciliation sweep once it has been held for 15
+minutes and released when the lead run has finished, and dropped after 24
+hours like a review held for CI.
+
 ## Review after CI (`waitForCi`)
 
 A `pull_request` link can set `waitForCi: true` so this reviewer reviews a
@@ -96,22 +275,76 @@ a tool error instead of publishing anything:
 - `ci_pending` — CI is still running; comment instead. The re-review above
   then runs the review again once a CI check suite finishes.
 
-Requesting changes or commenting is never affected by this gate. When CI
+Requesting changes or commenting is never affected by the CI gate. When CI
 cannot be read at all, the gate is skipped and the review proceeds as it
 would without `waitForCi`.
 
+A separate guard applies per run: `repo_publish_review` refuses `APPROVE`
+with `unread_files` while a source, test or config file of the head
+was listed by `repo_pr_read` but not fully read. Page with `patchCursor`, or
+read the file with `repo_read_file` at `headSha`; if that is not possible,
+publish `CHANGES_REQUESTED` and name the files not reviewed. `APPROVE` is
+also refused with `file_list_truncated` while the head's file list is cut
+(`fileListComplete: false`), and with `full_read_required` when the run read
+the head only with a `sinceSha` other than the `lastCoveredSha` it returned
+(the latest head this agent reviewed after reading every file).
+
 Add this to a reviewer's system prompt:
 
     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.
 
-Wardby also writes that section: see
+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. Wardby also writes that section: see
 [Related pull requests across repositories](related-pull-requests.md).
 
+## Mark ready when passing
+
+With Wardby 0.7.0 or later, set `markReadyWhenPassing: true` on the write
+link (`link_repository`) of the agent the repository event triggers to have
+Wardby mark the draft pull requests it opens here ready for review on its
+own, once they pass, instead of leaving that to a person. For a lead that
+delegates to a coding builder sub-agent, set it on the lead's link: the
+builder needs no repository link of its own, and pull requests its coding
+runs open count for the lead. An opted-in agent outside that run tree never
+counts. Re-linking the repository without it clears it, like every other
+link setting.
+
+Wardby marks a pull request ready once it is open and a draft, Wardby's own
+App opened it (and its head isn't in a fork), every authorized reviewer
+linked with the `pull_request` trigger has approved the head with its own
+check, CI on the head is green (every check run and commit status that
+isn't Wardby's own has completed with success, neutral, or skipped, at
+least one with success, or there is no CI at all), and the `wardby merge order` check is `success` or
+isn't posted on it. Commit statuses only count if the App can read them:
+grant **Commit statuses: Read** if your CI reports statuses rather than
+check runs. A pull request with more checks and statuses than Wardby reads
+(about 50) is never marked ready automatically. Wardby marks a given pull
+request ready at most once; moving it back to draft by hand is final —
+Wardby never re-marks it.
+
+Wardby checks whether a pull request is ready to mark on any of these
+events: a reviewer run finishing, a CI check suite completing on its head,
+its `wardby merge order` check turning `success`, or (as a fallback) Wardby's
+own reconciliation sweep for a pull request that is part of a merge-ordered
+set. With a `mergeOrder` set, a later step becomes ready this way only once
+the steps it depends on have merged — see [The wardby merge order
+check](merge-order-check.md). CI that reports only commit statuses (no
+check suite) is not re-checked when it finishes; such a pull request is
+marked ready the next time one of those events fires, or stays in draft
+until then.
+
+It never approves, merges, or converts a pull request back to draft — a
+person's approval stays the gate wherever branch protection requires one.
+It needs no App permission beyond **Pull requests: Read and write**, which
+an App that opens pull requests already has.
+
 For App permissions, webhook setup, trigger configuration, and security
 details, follow [`docs/code-review-agents.md`](../docs/code-review-agents.md).

package/help/coding-packages.md

@@ -1,24 +1,33 @@
 ---
 id: coding-packages
 title: Approve packages for coding agents
-summary: Let Codex coding workers install vetted npm and PyPI dependencies through Wardby's registry proxy.
+summary: Let coding workers install vetted npm (also with pnpm or yarn) and PyPI dependencies through Wardby's registry proxy.
 audience: operator
-tags: [coding-agents, packages, npm, pypi, supply-chain, refusals, lockfile, extras, pip-extras]
+tags: [coding-agents, packages, npm, pnpm, yarn, pypi, uv, supply-chain, refusals, lockfile, extras, pip-extras]
 appliesTo: >=0.2.1
 ---
 
 # Approve packages for coding agents
 
-Coding workers have no direct registry network access. For **Codex** workers,
-Wardby's registry proxy can allow `npm install` and `pip install` from a
+Coding workers have no direct registry network access. Wardby's registry
+proxy can allow `npm install` (or `pnpm`/`yarn`) and `pip install` from a
 per-agent npm or PyPI allowlist. The proxy records what was fetched and applies
 supply-chain checks, including package graph validation, release-age policy,
 and vulnerability filtering.
 
 An empty allowlist keeps registry mode off. Approve only top-level packages;
 Wardby validates and permits the required transitive dependency graph for the
-run. Changing a package allowlist or policy needs `packages:approve` (or
-`agents:admin`) and a Wardby `admin` or `package-approver` role.
+run. A package the project adds as a new top-level dependency must itself be
+approved (or already be in the verified lockfile), even if an approved
+package depends on it: when npm asks for a package that is not approved and
+was not declared by a package already resolved in the run, Wardby refuses it
+at once with `wardby_package_not_allowed`. Changing a package allowlist or
+policy needs `packages:approve` (or `agents:admin`) and a Wardby `admin` or
+`package-approver` role.
+
+If the repository uses npm `overrides`, also approve each overridden package:
+an override installs a version its parent doesn't ask for, so Wardby approves
+it, and what it depends on, only when its name is on the allowlist.
 
 Registry mode works for Codex and Claude Code runs alike, on the `node`
 toolchain (npm) and the `node-python` toolchain (npm and pip). Claude Code runs
@@ -35,6 +44,55 @@ if its own checks failed. A package reachable only through a refused one is
 refused too, so a high-severity advisory deep in a toolchain blocks every run
 that installs it.
 
+## Allowlist refusals
+
+Four codes say a package could not be reached through the allowlist. The agent
+should stop on all of them except `wardby_graph_incomplete`; the owner fixes
+them by allowlisting the package directly (`update_agent`,
+`codingProfile.packageAllowlist`). Each code has an article under `errors/` (for example `errors/package-not-allowed-pending`), available from release 0.7.0.
+
+- `wardby_package_not_allowed`: not on the allowlist and not declared by a package already resolved in the run, or only reachable through a refused package.
+- `wardby_package_not_allowed_pending`: the dependency walk stopped before reaching it; retrying rarely helps.
+- `wardby_graph_limit`: the dependency graph is over `REGISTRY_MAX_GRAPH_PACKAGES`.
+- `wardby_graph_incomplete`: still being checked; retry shortly.
+
+The last three arise only when the proxy walks the dependency graph: for a
+tarball download the run hasn't resolved (a lockfile install the plan did not
+approve), or for a metadata request after a lockfile plan of the run failed
+or refused an entry. Otherwise a metadata request never walks. A
+lockfileVersion 1 lockfile can't be planned, so regenerate it with a current
+npm to avoid the slower walk.
+
+To find out which packages a task needs without a round of refusals for each
+one, turn on package audit mode for a limited time (from Wardby 0.7.0): the
+registry installs packages outside the allowlist and records them for you to
+approve. Read the `package-audit-mode` help article, "Package audit mode".
+
+## pnpm and yarn
+
+From Wardby 0.7.0, pnpm, yarn classic (1.x) and yarn 2 or later (Berry, with
+node-modules or Plug'n'Play) install from the same npm allowlist as npm, and
+their lockfiles are verified the same way: before `pnpm install`/`add` or
+`yarn`/`yarn install`/`yarn add`, the worker's shim sends `pnpm-lock.yaml`
+(lockfileVersion 6 or 9) or `yarn.lock` to the registry, which approves its
+exact versions, so `pnpm install --frozen-lockfile`, `yarn install
+--frozen-lockfile` and `yarn install --immutable` need no slow graph walk.
+
+- The stock images have npm, yarn classic and corepack. The shim runs pnpm,
+  and a yarn 2+ release a project pins in `packageManager`, through corepack,
+  which downloads it through the registry: allowlist `pnpm` or
+  `@yarnpkg/cli-dist` (or bake the tool into a custom worker image).
+- yarn 2+ records yarn's own `checksum`, not npm's integrity: its plan
+  approves exact versions, and each download is checked against the
+  registry's integrity.
+- yarn 2+ adds an implicit `node-gyp` dependency to packages with install
+  scripts (such as `fsevents`); allowlist `node-gyp` when the lockfile has it.
+- Install scripts stay off for every client, and lockfiles a run commits
+  name only public registry URLs.
+
+See [pnpm and yarn](../docs/coding-packages.md#pnpm-and-yarn) for each
+client's settings and the plan's rules.
+
 ## PyPI extras
 
 A PyPI entry may name extras, as pip does: `psycopg[binary]`,
@@ -54,6 +112,42 @@ support cannot load an allowlist with a `name[extra]` entry, so every registry
 request of that run fails; and once a profile stores an extras entry, do not
 downgrade below the release that added extras.
 
+## Python: pip and uv
+
+The `node-python` images ship pip (used in a virtual environment) and uv,
+and the worker points both at the registry (`PIP_INDEX_URL`, and
+`UV_DEFAULT_INDEX` with `UV_NO_BUILD=1` for wheels only). Top-level installs
+work with either: `pip install -r requirements.txt`, `uv pip install …`.
+
+- **Fully pinned requirements** (`pip-compile`, `pip freeze`) list
+  dependencies as top-level lines, so the file is verified first, like an
+  npm lockfile: `uv pip install -r` does it itself; for pip, run
+  `wardby-packages plan requirements.txt` first. Every pin the allowlist
+  reaches is then allowed; the rest are named with their reason (too new,
+  no wheel, not reachable).
+- **`uv sync`, `uv run`, `uv add` with a committed `uv.lock`** work: the
+  worker's `uv` verifies the lock and points its PyPI URLs at the registry
+  for the command, then puts the file back (a committed lock never names
+  the registry).
+- **Project installs** (`pip install .`, `uv sync`, `uv run`) need the build
+  backend from `[build-system] requires` (`hatchling`, `setuptools`, …)
+  allowlisted, plus what it asks for while building (hatchling: `editables`
+  for an editable install).
+- **Poetry** doesn't work in the sandbox, and a `poetry.lock` or
+  `pylock.toml` can't be verified (`wardby_lockfile_unsupported`): export a
+  pinned requirements file, or use uv.
+
+pip and uv don't print why the registry refused a package (pip says
+`from versions: none`, uv `403 Forbidden`). The agent is told to run
+`wardby-packages`, which lists the run's recent refusals with their codes
+and hints; a Claude Code agent also gets those lines after any failed
+command. The registry also records packages it hides from the index: one
+with only source distributions (`wardby_file_not_allowed`), or whose every
+wheel is too new (`wardby_version_filtered`). The installer may only have
+looked at that index, so such a refusal (`get_run` marks it `listingOnly`)
+adds nothing to a pull request, shows as a ⚠️ line on a run that made no
+changes, and blocks the status (⛔) only when a coding sub-run failed.
+
 The quickstart's coding step offers the packages a local repository declares
 (`package.json`, `pyproject.toml` including its build-system packages,
 `requirements*.txt`, keeping Python extras such as `psycopg[binary]`) as
@@ -67,5 +161,61 @@ run. See [Local repositories](local-repositories.md).
 Review agents see the pull request's CI results in `repo_pr_read` and are
 told to trust CI over the sandbox's **Tests**.
 
+## Accepting advisories
+
+From Wardby 0.7.0, a version withheld only by a high or critical advisory
+(refused with `wardby_version_filtered`) can be served for one agent once an
+approver accepts the advisory. Set `codingProfile.packagePolicy.acceptedAdvisories`
+with `create_agent` or `update_agent` (needs `packages:approve` or
+`agents:admin`):
+
+```json
+{
+  "codingProfile": {
+    "packagePolicy": { "minReleaseAgeDays": 3, "acceptedAdvisories": ["GHSA-xxxx-xxxx-xxxx"] }
+  }
+}
+```
+
+- `update_agent` replaces `packagePolicy` as a whole: send the full object
+  (omitting `minReleaseAgeDays` resets it to the default 3). To remove a
+  waiver, re-send the whole object without that id.
+
+- Up to 32 unique ids (`GHSA-…`, `CVE-…`, `PYSEC-…`), matched case-sensitively
+  against an advisory's id and its aliases.
+- A version is served only when every blocking advisory is accepted; the
+  refusal names the ones still blocking.
+- Malware is never waivable: `MAL-…` ids are rejected, and malware advisories
+  stay blocked even if listed.
+- Waivers show as `acceptedAdvisories` per package in `get_run` and in an
+  **Accepted advisories** section of the pull request. The policy is fixed
+  when a run starts.
+- Find the id from the package named in the refusal: `https://osv.dev/list?q=<package>`
+  or `npm audit`. Accept only after judging the exposure (for example, a
+  build-time-only dependency), and remove the entry once a fixed version ships.
+
 Read [`docs/coding-packages.md`](../docs/coding-packages.md) for allowlist
 syntax (including [PyPI extras](../docs/coding-packages.md#pypi-extras)), package-policy controls, lockfile behavior, and refusal errors.
+
+## Dependency cache
+
+From Wardby 0.7.0, a coding agent can start with `node_modules` already
+restored from a verified snapshot instead of running `npm ci`. Read the
+`dependency-cache` help article, "Dependency cache for coding runs".
+
+## Blocked status comments
+
+If a coding child records package refusals, reports no changes or fails, and no
+pull request or pushed changes result, GitHub and Jira status comments show
+⛔ **Blocked by the package registry: no changes were made.** Otherwise, the
+status keeps the agent's reply or answer, or the pull request link, and adds a
+⚠️ dependency install warning. Refusal lists show at most ten distinct entries and a count
+of the rest; `get_run` has the full list.
+A refusal the run got past does not count: when the registry later served the
+same package (or, for a refused version, that version) to the same coding run,
+for example after npm retried a temporary error, it is left out of the status,
+the warning and `get_run`. A package served to another sub-run doesn't clear it.
+
+For next steps, see [Package refusal errors](errors/package-refusals.md) and
+[Run status comments](status-comments.md). After an approver updates the
+agent's allowlist or policy, mention `@wardby` again to start a new attempt.

package/help/cost-attribution.md

@@ -1,9 +1,9 @@
 ---
 id: cost-attribution
 title: Attribute agent spend to issues
-summary: See what agent work on a Jira card, epic, or project cost, by model and token kind, with the cost_report MCP tool.
+summary: See what agent work on a Jira card, epic, or project, or on a GitHub issue, cost, by model and token kind, with the cost_report MCP tool.
 audience: operator
-tags: [cost, spend, attribution, jira, epic, reporting, cost_report, tokens]
+tags: [cost, spend, attribution, jira, github, github-issues, epic, reporting, cost_report, tokens]
 appliesTo: >=0.2.1
 ---
 
@@ -15,10 +15,15 @@ work on a card, an epic, or a whole project cost.
 A run is attributed to an issue when:
 
 - a Jira event on that issue started it;
+- an `@wardby` mention on a GitHub issue started it: it is attributed to a work
+  item with provider `github` and key `owner/repo#N`, like a Jira issue, so
+  `cost_report` shows the issue's total;
 - it reviews, or answers an `@wardby` mention on, a pull request Wardby opened
   for the issue — including a review that starts while the agent that asked
   for the pull request is still running, before the pull request is linked to
   the issue (Wardby then uses the issue of the coding run that opened it);
+- it reviews, or answers a mention on, a pull request opened from a GitHub
+  issue: it is attributed to that issue's `github` work item;
 - `trigger_agent` named an `issue`, or a webhook call's JSON body named a
   `wardbyIssue`, as `{ "provider": "jira", "key": "PROJ-123" }`, in a project
   the agent is linked to. Keys are matched without regard to case
@@ -62,8 +67,7 @@ cost per model.
 
 If a company-managed Jira site still uses the legacy Epic Link field, set
 `WARDBY_JIRA_EPIC_LINK_FIELD` (for example `customfield_10014`) so runs are
-grouped under their epic. On GKE, re-run the database grants bootstrap after
-upgrading so coding runs record their per-model usage; until then they still
-run and a warning is logged.
+grouped under their epic. On GKE, `deploy/gke/up.sh` applies the database
+grant coding runs need to record their per-model usage when you upgrade.
 
 For the full guide, follow [`docs/jira-agents.md`](../docs/jira-agents.md).

package/help/creating-agents.md

@@ -3,7 +3,7 @@ id: creating-agents
 title: Choose a native or coding agent
 summary: Decide whether a task should run as a native Wardby agent or an isolated Codex or Claude Code coding agent.
 audience: developer
-tags: [agents, native-agents, coding-agents, codex, claude-code]
+tags: [agents, native-agents, coding-agents, codex, claude-code, schedules, set_schedule]
 appliesTo: >=0.2.1
 ---
 
@@ -44,6 +44,12 @@ the trusted coding proxy, and a narrowly installed GitHub App. The agent owner
 must have the required repository access, or an administrator must explicitly
 approve the repository.
 
+A Claude Code agent can also keep a redacted transcript of each run with
+`codingProfile.sessionResume`, and continue a run on your machine with
+`get_run_transcript` and `npx @wardby/cli@latest resume`; see
+[Resume a run locally](../docs/coding-agent-setup.md#resume-a-run-locally)
+(from 0.7.0, the `resume-runs-locally` help article).
+
 ## Choosing a model
 
 Both agent types take a `model` field naming an entry in wardby's model
@@ -67,6 +73,13 @@ coding agent needs a `codingProfile.defaultTask` first, since a scheduled run
 has no one to pass a task. A native agent's system prompt is its task. Trigger
 the agent once with `trigger_agent` and check the result before scheduling it.
 
+A new schedule first fires at its next window after you set it, never for a
+window that already passed. A schedule of `0 6 * * 1` set on a Wednesday
+first runs the following Monday, so a manual run just before scheduling isn't
+followed by a duplicate. Changing the expression or timezone, or turning a
+disabled schedule back on, starts it again from that moment. If the scheduler
+was down and missed windows, it runs only the latest one, once.
+
 Schedules fire only while a Wardby scheduler runs: `wardby serve`, or
 `wardby scheduler` next to `wardby mcp`. On a quickstart install, start
 `npx @wardby/cli@latest scheduler` from the project directory and keep it