@wardby/cli 0.5.3 → 0.7.0

package/docs/observability.md

@@ -49,5 +49,9 @@ the coding-proxy coverage, so verify required signals before production use.
 - Alert on request failures, budget cutoffs, cleanup failures, stalled runs,
   and sustained latency or memory growth.
 - Confirm alerts reach an owned channel and rehearse one response path.
+- Watch the logs for package audit mode: the control plane logs
+  `coding.package_audit.set` when an owner turns it on, off or extends it, and
+  the coding proxy logs `registry.audited` for each package it installs
+  because of it (see [Package audit mode](coding-packages.md#package-audit-mode)).
 - Treat telemetry as operational evidence, not as a replacement for Wardby's
   accounting database.

package/docs/release-verification.md

@@ -40,6 +40,15 @@ repository-scoped GitHub App installation, and a deliberately small budget.
 Verify the requested diff, terminal outcome, cost, resource cleanup, and branch
 cleanup. See [local coding-agent setup](coding-agent-setup.md).
 
+The bundled help catalog is built for the version in `package.json`.
+`appliesTo` on each help article must name its minimum release; later articles
+stay in source but are omitted from that release's CLI and MCP help. The build
+fails when an included article links to an omitted one. When adding a newer
+feature to an older article, move its guidance into a suitably versioned
+article or update the older article so it remains accurate for its stated
+minimum release. Mark newer features in the public `docs/` guides with their
+minimum release as well.
+
 Before production deployment, review [runtime architecture](architecture-runtime.md),
 [coding-worker isolation](coding-worker-isolation.md), and the
 [security deployment guide](security-deployment.md). A self-hosted operator is

package/docs/security-deployment.md

@@ -79,15 +79,15 @@ Scopes and roles do different jobs:
 - **Roles authorize.** A user has a set of roles. With no roles, the user is a
   member:
 
-| Role               | Grants                                                                                 |
-| ------------------ | -------------------------------------------------------------------------------------- |
-| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view` and `models:admin` |
-| `package-approver` | `packages:approve`                                                                     |
-| `service-manager`  | `services:manage`                                                                      |
-| `model-manager`    | `models:admin`                                                                         |
-| (none)             | nothing privileged; every other scope works as the token allows                        |
+| Role               | Grants                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage` |
+| `package-approver` | `packages:approve`                                                                                     |
+| `service-manager`  | `services:manage`                                                                                      |
+| `model-manager`    | `models:admin`                                                                                         |
+| (none)             | nothing privileged; every other scope works as the token allows                                        |
 
-Seven operations are privileged:
+Eight operations are privileged:
 
 - `make_owner`, which reassigns any agent's owner, including another
   principal's private agent (see [Sharing agents](#sharing-agents) for what
@@ -104,7 +104,10 @@ Seven operations are privileged:
   (`set_model`, `disable_model`, `reset_model`; reading the catalog is
   `agents:read`, see [models.md](models.md));
 - reading every owner's runs through the admin viewer API (see
-  [viewer-api.md](viewer-api.md)).
+  [viewer-api.md](viewer-api.md));
+- reading low-power state and scaling the coding proxy and native gateway to
+  zero now (`power_status`, `power_sleep`; see
+  [Low-power mode](getting-started-gke.md#low-power-mode)).
 
 Each needs **both** its scope on the token **and** a role that grants that
 permission:
@@ -114,10 +117,12 @@ permission:
 - Service catalog changes need `services:manage`.
 - Model catalog changes need `models:admin`.
 - The admin viewer API needs `admin:view`, which only the `admin` role grants.
+- `power_status` and `power_sleep` need `power:manage`, which only the `admin`
+  role grants.
 
 In practice:
 
-- an `admin` can do all seven;
+- an `admin` can do all eight;
 - a `package-approver` can approve packages only;
 - a `service-manager` can change the service catalog only;
 - a `model-manager` can change the model catalog only;
@@ -190,7 +195,10 @@ See the [Fetch standard](https://fetch.spec.whatwg.org/#append-a-request-origin-
 
 Clients must re-register as public clients (`token_endpoint_auth_method=none`).
 Only S256 PKCE and exact registered redirect strings are accepted. Redirects
-must be HTTPS or loopback HTTP, without credentials or fragments. Registration
+must be HTTPS or loopback HTTP, or, only with `WARDBY_MOBILE_ENABLED=true`,
+exactly the configured mobile redirect (`WARDBY_MOBILE_REDIRECT_URI`, default
+`com.wardby.mobile:/oauth`; see the `mobile-app` help article), without
+credentials or fragments. Registration
 allows 1-10 redirects and a bounded client name. `AUTH_MAX_CLIENTS` defaults to
 1000; PostgreSQL serializes capacity checks and shares rate limits across
 processes. There is no confidential-client support or client secret.
@@ -258,8 +266,17 @@ so a tool a write-grantee attaches runs with none until you re-run
 the coding profile, kind and budget group; and sub-agents, since an edge
 would hand every run's data to another agent.
 
-**Everyone** can be granted at most `execute`: everyone-write would let
-anyone rewrite an agent that holds your tools and secrets.
+**Everyone** (any signed-in principal) can be granted up to `write`, a
+public agent anyone can list, run and edit, but only while the agent holds
+none of its owner's bindings: secrets, datastores, repositories, sub-agents,
+tool capabilities, or a coding repository (so a coding agent is never
+public-write). `grant_access` refuses everyone-`write` on an agent that has
+any, and the binding tools (`attach_secret`, `attach_datastore`,
+`link_repository` including an admin's `adminOverride`, `attach_subagent`,
+and `attach_tool` with capabilities) refuse to add one to an agent everyone
+can write, as `update_agent` refuses making it a coding agent. Otherwise anyone could
+rewrite the prompt of an agent that uses your secrets. Detach the bindings
+first, or grant everyone `execute` instead.
 
 **Nothing crosses owners without a grant on that exact resource**, checked
 when bindings are written and again at run time, so rows written before this
@@ -456,6 +473,15 @@ stale, whichever executor id owns it. Set a fixed id only for a single,
 long-lived process that should re-drive its own runs at launch rather than
 after the heartbeat timeout.
 
+An owner that is stalled but still alive (event-loop or database-pool
+starvation long enough for its heartbeat to go stale) can overlap the attempt
+another process adopted. The first attempt to record a step keeps the run; the
+other stops at that step without writing the run or sending any
+notifications, and DBOS parks it as a duplicate execution. That stopped step's
+model spend is discarded rather than counted against the run, so look for the
+`run_ownership_lost` warning in the server logs (it carries the run id, the
+step, and the discarded usage when known) to see how often this happens.
+
 **New data at rest.** Durable execution checkpoints every step's result into
 `dbos.operation_outputs`: each turn's assistant text, every tool call's
 arguments, every tool result in full, and the `load` step's pinned agent
@@ -499,8 +525,10 @@ records. Delete them (see pruning above) if you want the rollback to be final.
 | Surface                        | Limit                                             |
 | ------------------------------ | ------------------------------------------------- |
 | MCP/webhook bodies             | 1 MiB raw bytes                                   |
+| MCP tool-call arguments        | 100,000 array elements and object members         |
 | Auth bodies                    | 64 KiB raw bytes                                  |
 | Request completion / headers   | 15 seconds / 10 seconds                           |
+| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds              |
 | Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects, 8 seconds |
 | Bridge input / output          | 1 MiB / 12 MiB                                    |
 | Parser input / console payload | 256 KiB / 16 KiB                                  |
@@ -518,6 +546,26 @@ and pins the validated DNS result to the connection while retaining Host and
 TLS verification. Cross-origin redirects remove credentials, including custom
 API-key headers; forwarding a request body across origins is rejected.
 
+Every sandbox invocation, including the one that validates a custom tool's
+call arguments against its `paramsZod`, runs in a fresh QuickJS runtime with the
+heap, stack, and time limits above. One that hits a limit fails that tool call
+only: the model receives a `validation_failed` or sandbox error result and the
+run continues. The invocation runs on the thread of the process that hosts the
+run (the server, or the run's worker with the native sandbox), so a call that
+runs to the time limit holds that thread for up to 10 seconds.
+
+For this release only, a custom tool's `paramsZod` is compiled with Zod 4's
+built-in Zod 3 API (`zod/v3`) so that existing tools keep working; see
+[native capabilities](../help/native-capabilities.md). `zod/v3` does not have
+the fix for GHSA-mrhx-c7xc-m3w5: given an array, set, or map larger than its
+`.max()`, it still checks every element and records an issue for each bad one.
+For a tool's arguments that work stays inside the sandbox limits above, the same
+limits that bound the tool's own code. Wardby's own validation uses Zod 4. A
+tool whose schema the next release (Zod 4 only) would reject is flagged with a
+`warnings` list in `create_tool`, `update_tool`, `dry_run_tool`, `list_tools`
+and `get_agent` results (on tools the caller owns) and in one server log line
+per tool at startup; a warning names only the tool and the removed Zod 3 methods.
+
 Every resolved address must be global. A tool's own `allowedHosts` only
 narrows egress; it never opens a private, loopback or link-local destination.
 Only the operator's `WARDBY_FETCH_ALLOWED_HOSTS` (exact normalized hosts) can,
@@ -543,6 +591,23 @@ bound connection pools and concurrent invocations, and review a cancellable
 database adapter or isolated worker if strict immediate termination is required.
 Do not claim these per-invocation caps establish a whole-process memory ceiling.
 
+## Slack workflow notifications
+
+This integration requires Wardby 0.6.0 or later.
+
+Optional Slack workflow notifications add no inbound endpoint: wardby only
+ever calls out to Slack's `chat.postMessage`/`chat.update`/`conversations.info`,
+and the app manifest requests no event subscriptions or interactivity, so
+nothing posted in Slack can start or affect a run. What reaches Slack is
+limited to issue keys/titles and their links, pull request numbers and
+links, agent names, review verdicts, fix-round numbers, a failed run's
+reason (its first line, at most 200 characters), and (only when a link opts
+in) the run's spend line — never code, diffs, review bodies, or run output.
+Issue titles are posted regardless of Jira issue security, so link a project
+only to a channel whose members may see every issue in it. The bot token is a provider credential like any other and never
+reaches a sandboxed tool or coding-run worker. See
+[Send workflow updates to Slack](slack-notifications.md).
+
 ## Coding runs on Kubernetes
 
 `JOB_LAUNCHER=kubernetes` runs each coding agent in its own pod instead of a
@@ -565,7 +630,7 @@ connects from inside the pod to a destination that must be blocked and requires
 three consecutive refusals. A cluster that does not enforce policy, or has not
 yet programmed this pod's rules, never reaches the point of running agent code.
 The same check runs at startup against a throwaway canary pod, which also
-verifies the pod cannot reach DNS, the internet or the cloud metadata endpoint.
+verifies the pod cannot reach DNS, the internet or the cloud metadata endpoints.
 
 **RBAC.** The control plane needs a namespace Role (`pods`, `pods/exec`,
 `pods/log`, `secrets`, `configmaps`, `networkpolicies`, `services`) and a
@@ -579,6 +644,15 @@ has none, so that configuration is development-only and says so. Set
 `KUBERNETES_RUNTIME_CLASS` to the cluster's sandboxed runtime class in
 production; the launcher warns loudly when it is unset.
 
+The `eks` platform profile (Amazon EKS with a gVisor node group) also requires
+the `gvisor` runtime class. The cluster supplies a RuntimeClass `gvisor`
+(handler `runsc`) whose scheduling block targets nodes labelled
+`wardby.dev/sandbox=gvisor` and tainted `sandbox=gvisor:NoSchedule`; coding-pod attestation
+forgives that node selector and toleration and nothing else. The startup canary
+and the native sandbox gate probe the cloud metadata endpoints
+`169.254.169.254`, `169.254.170.23` and `fd00:ec2::23` (EKS Pod Identity agent, IPv4 and IPv6) and
+`fd00:ec2::254` (EC2 IPv6), all on port 80, and require every one to be unreachable.
+
 The `gke-autopilot` platform profile contains narrow admission allowances
 captured from a real cluster and requires the `gvisor` runtime class. A dry-run
 capture cannot observe labels added after pod scheduling, so live-run behavior
@@ -592,6 +666,52 @@ Per-run record ConfigMaps currently require operator-managed garbage collection,
 and the real-cluster suite does not yet cover every Docker containment
 scenario.
 
+## Database authentication
+
+By default `DATABASE_URL` carries the database password. On Amazon RDS (or
+Aurora) for PostgreSQL, set `DATABASE_AUTH=rds-iam` to authenticate with IAM
+database authentication instead: the password is a short-lived token signed with
+the workload's AWS credentials (for example EKS Pod Identity), minted when a
+connection opens. Any other value is refused with
+[`database_auth_invalid`](../help/errors/database-auth-invalid.md).
+
+Under `rds-iam`:
+
+- `DATABASE_URL` must be `postgresql://` (or `postgres://`) with the database
+  user and no password, and must contain `sslmode=verify-full` and
+  `sslrootcert=<path to the RDS CA bundle>`. The port defaults to 5432.
+- The region comes from `DATABASE_AWS_REGION`, else `AWS_REGION`.
+- The database user must be granted `rds_iam` and the workload's IAM role must
+  allow `rds-db:connect` for it.
+- Tokens are valid for 15 minutes and only for opening a connection; Wardby
+  reuses one for 10 minutes, and open connections outlive their token.
+- It applies to every app connection: the Prisma clients (server, scheduler,
+  coding proxy, native gateway), the DBOS system database
+  (`DBOS_SYSTEM_DATABASE_URL`, else `DATABASE_URL`, under the same rules) and
+  the viewer's LISTEN connection. The DBOS system pool holds up to 10
+  connections; count it in the database's connection budget.
+- URL parameters that are carried over: `application_name`,
+  `fallback_application_name`, `options`, `client_encoding`,
+  `statement_timeout`, `lock_timeout`, `idle_in_transaction_session_timeout`,
+  `query_timeout`. `connection_limit` and `pool_timeout` still size and bound
+  the pool, `connect_timeout` (seconds) applies to the DBOS pool, and `schema`
+  is accepted with no run-time effect, as in password mode. Every other
+  parameter is refused by name, including `sslcert`, `sslkey`, `ssl`, `host` and
+  `pgbouncer`; the Cloud SQL `sslcert=` advice does not apply to RDS.
+- A misconfigured setup fails at process start, for every `wardby` command,
+  because the database module is loaded at start.
+- `prisma migrate deploy` and `dbos schema` take a URL, not a connection
+  config, so they are not covered. Mint a short-lived URL with the helper
+  shipped in the migration image and run them within its 15 minutes:
+
+  ```bash
+  DATABASE_URL="$(node scripts/rds-iam-url.mjs)" && export DATABASE_URL && npm run prisma:migrate && npm run dbos:migrate
+  ```
+
+  The helper reads `DATABASE_URL`, `DATABASE_AWS_REGION`/`AWS_REGION` and the
+  ambient AWS credentials, and prints a URL containing a credential: never log
+  its output. `wardby quickstart` does not support `rds-iam`.
+
 ## Coding package registry
 
 Enabling a coding agent's package allowlist widens the trusted proxy's own
@@ -613,6 +733,18 @@ guarantee; and the OSV vulnerability audit fails **closed**
 operator explicitly sets `REGISTRY_AUDIT_FAIL_OPEN=true` to allow installs
 through unaudited during an OSV outage.
 
+## Native sandbox
+
+A native agent set to `nativeExecutionMode=sandbox` runs its turn loop and user
+tools in a single-use container with no credentials, database access, Docker
+socket, or network except the native gateway. The gateway is a trusted
+component: it holds the LLM credentials and integration settings, so give it
+the database and provider settings it needs and nothing else, never the Docker
+socket, and do not publish its port outside the Docker host. Only the server,
+which launches workers, needs Docker access (or, on Kubernetes, permission to
+create pods in the run namespace). See
+[Native sandbox](native-sandbox.md).
+
 ## Images and dependencies
 
 ```sh

package/docs/slack-notifications.md

@@ -0,0 +1,268 @@
+# Send workflow updates to Slack
+
+> **Requires Wardby 0.6.0 or later.**
+
+Link a Slack channel to a Jira project or to an agent (native or coding), and wardby posts
+that project's or agent's workflow updates there: a card picked up, a pull
+request opened, a review verdict, fix rounds, and the merge — one thread per
+card. This is outbound only: nothing in Slack starts or affects a run, and
+wardby exposes no new inbound endpoint for it.
+
+## What it does
+
+### Events
+
+Eight kinds of lifecycle event can post to a linked channel:
+
+| Kind               | Posts when                                                                                                                                     | Content                                                                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issue_picked_up`  | A Jira event starts a run on a linked issue                                                                                                    | Issue key, title, and link; agent name; trigger kind                                                                                                     |
+| `run_failed`       | A top-level run ends `failed`, `refused`, `budget_exhausted`, `cancelled`, or `lost`                                                           | Agent name, status, a short first-line reason (never the full error)                                                                                     |
+| `run_blocked`      | A top-level run succeeds without a pull request, but a coding child refused packages and made no changes or failed                             | ⛔ Blocked status, refused packages, and code-specific fixes                                                                                             |
+| `pr_opened`        | A coding run opens a pull request                                                                                                              | Repository#number and link, the issue it is for, any Jira status move                                                                                    |
+| `review_posted`    | wardby's own review check posts a verdict                                                                                                      | `APPROVE` / `CHANGES_REQUESTED` / `COMMENT`, the reviewer agent, the PR link                                                                             |
+| `review_fix`       | An automatic [fix round](../help/review-fix-rounds.md) starts or hits the cap                                                                  | Round number of the cap, started or capped                                                                                                               |
+| `pr_closed`        | A pull request is merged or closed                                                                                                             | Merged or closed, any Jira status move                                                                                                                   |
+| `packages_audited` | A top-level run ends (any status) and its coding children installed anything under [package audit mode](coding-packages.md#package-audit-mode) | The mode, up to ten package names to approve, any names of unknown relation listed apart, and counts of their dependencies and of advisories served past |
+
+A successful run normally shows up as `pr_opened` or `review_posted`. A run
+blocked by package refusals instead emits `run_blocked`, once per run, using
+the same rule and guidance as [status comments](../help/status-comments.md): a
+run that answered, or worked around a refusal, is not blocked. Child
+coding runs surface through their parent's events.
+
+Some runs do not post `run_failed` at all:
+
+- a coding agent's run triggered directly (rather than as a child of a
+  native agent's run),
+- a review verdict or failure from a coding agent acting as the reviewer, and
+- runs started from the `wardby run` CLI command.
+
+`pr_opened` and `pr_closed` also post for a pull request opened from a GitHub
+issue mention, the same as for a Jira issue: GitHub issues record the pull
+requests opened for them. The thread is the issue's, one per GitHub issue
+(`issue:github:owner/repo#N`) however many pull requests it has, not one per
+pull request. Once a pull request is recorded for the issue, its
+`review_posted` and `review_fix` events reply in that thread too. The run
+events (`run_failed`, `run_blocked`, `packages_audited`) of a run a GitHub
+issue mention started are not tied to the issue and post in a thread of
+their own.
+
+A pull request linked to several issues posts `pr_opened` and `pr_closed`
+only to the first linked issue's thread.
+
+### Threads
+
+Each channel gets one thread per card: one per issue (a Jira issue, or the
+GitHub issue a pull request was opened from) when the event has one, else one
+per pull request. The first event for a card
+posts a parent message naming the issue or pull request; every later event
+for the same card is a reply in that thread, and the parent is kept updated
+with a short status line. The statuses are:
+
+| Status                 | Set by                                                           |
+| ---------------------- | ---------------------------------------------------------------- |
+| `picked up`            | `issue_picked_up` on a new thread, or after `merged ✅`/`closed` |
+| `PR open`              | `pr_opened`                                                      |
+| `changes requested`    | a `CHANGES_REQUESTED` review                                     |
+| `approved`             | an `APPROVE` review                                              |
+| `fixing`               | a fix round starting (the round number is in the thread reply)   |
+| `fix rounds exhausted` | fix rounds reaching the cap with changes still requested         |
+| `merged ✅`            | the pull request merged                                          |
+| `closed`               | the pull request closed without merging                          |
+| `blocked ⛔`           | `run_blocked`                                                    |
+| `failed ❌`            | `run_failed`                                                     |
+
+A `COMMENT` review and `packages_audited` leave the status as it was. `merged ✅` and `closed` stick:
+a late review, fix round, failure, or repeated close does not change them.
+Only a new start does — the card picked up again, or a new pull request
+opened for it — which sets `picked up` or `PR open` again.
+
+Most events only post as a thread reply. A merge, a blocked run, and a top-level run failure
+also post to the channel itself, so they are visible without opening the
+thread.
+
+### What is never sent
+
+wardby never posts code, diffs, review bodies, or run output to Slack. Error
+messages shown in Slack are a short first line only (at most 200 characters),
+never a full error or stack trace.
+
+## 1. Create the Slack app
+
+Use the manifest in [`deploy/slack/app-manifest.yaml`](../deploy/slack/app-manifest.yaml):
+
+1. Open [api.slack.com/apps](https://api.slack.com/apps), choose **Create New
+   App → From a manifest**, pick your workspace, and paste the manifest.
+2. On **OAuth & Permissions**, click **Install to Workspace** and approve the
+   requested scopes.
+3. Copy the **Bot User OAuth Token** (starts `xoxb-`).
+
+See [`deploy/slack/README.md`](../deploy/slack/README.md) for the full
+walkthrough, including the optional per-agent display-name scope.
+
+## 2. Configure wardby
+
+| Variable                    | Value                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `WARDBY_SLACK_BOT_TOKEN`    | The bot token from step 1 (`xoxb-…`). Unset = Slack notifications are disabled.                   |
+| `WARDBY_SLACK_API_BASE_URL` | Optional. Overrides the Slack Web API base URL (`https://slack.com/api`); must be `https`.        |
+| `WARDBY_SLACK_CUSTOMIZE`    | Optional, `true` or `false` (default `false`). Needs `chat:write.customize` in the installed app. |
+
+Store `WARDBY_SLACK_BOT_TOKEN` in your secrets backend the same way you store
+other provider credentials (`GITHUB_APP_PRIVATE_KEY`, `WARDBY_JIRA_API_TOKEN`)
+— never in a committed file. On the GKE reference deployment, see
+[Getting started on GKE](getting-started-gke.md). Restart wardby after setting
+it. The startup log line `chat notifications acting as` names the Slack team
+and bot user id wardby authenticated as. If that check fails instead, wardby
+only logs an error and still starts: it does not fail to boot, and delivery
+is not paused up front. Delivery pauses when the first actual delivery fails
+authentication (see [Failure modes](#failure-modes)).
+
+With `WARDBY_SLACK_CUSTOMIZE=true`, a message about an event that names an
+agent (`issue_picked_up`, `run_failed`, `run_blocked`, `review_posted`, `packages_audited`) is posted under that
+agent's name; every other message, and every message when the option is off,
+posts as `wardby`. A thread's parent message uses the name of the event that
+started the thread. wardby sets no icon.
+
+Without `WARDBY_SLACK_BOT_TOKEN`, `link_notification_channel` and
+`test_notification_channel` are refused and the dispatcher does not start;
+`unlink_notification_channel` and `list_notification_channels` still work, so
+you can clean up old links. See
+[`errors/slack-not-configured`](../help/errors/slack-not-configured.md).
+
+## Scopes and why
+
+| Scope                  | Required    | Used for                                                                                                  |
+| ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
+| `chat:write`           | Yes         | Posting and updating the bot's own messages, including threaded replies                                   |
+| `chat:write.public`    | Recommended | Posting to public channels without inviting the bot first                                                 |
+| `channels:read`        | Recommended | Validating a channel id and recording its name when linking                                               |
+| `groups:read`          | Recommended | The same, for private channels                                                                            |
+| `chat:write.customize` | Optional    | Posting under the name of the agent an event is about instead of `wardby` (`WARDBY_SLACK_CUSTOMIZE=true`) |
+
+Without `channels:read`/`groups:read`, linking still accepts a raw channel id
+but skips validating it. Any other authentication error while linking (an
+invalid or revoked token) refuses the link; see
+[`errors/slack-auth-failed`](../help/errors/slack-auth-failed.md). Private channels always need `/invite @wardby` (or
+whatever you named the app) regardless of scopes — Slack never lets a bot see
+or post to a private channel it hasn't been invited to. `chat.postMessage` is
+rate-limited to about one message per second per channel; wardby's dispatcher
+paces its own posts to stay under that.
+
+## Link channels
+
+Use the `link_notification_channel` MCP tool. It needs `agents:admin` with
+the admin role, the same trust model as `link_issue_project`: wardby cannot
+verify a caller's own Slack workspace access, so an administrator approves
+every link.
+
+Link a channel to a Jira project:
+
+```json
+{
+  "channel": "C0123456789",
+  "projectKey": "PAY",
+  "issueProvider": "jira",
+  "events": ["issue_picked_up", "pr_opened", "review_posted", "pr_closed"],
+  "includeCost": true
+}
+```
+
+Link a channel to an agent instead (every event for that agent's runs, no
+filter):
+
+```json
+{
+  "channel": "C0123456789",
+  "agentId": "<agent id>"
+}
+```
+
+- Give exactly one of `projectKey` (with optional `issueProvider`, default
+  `jira`) or `agentId`.
+- `channel` is the Slack channel id — `C…` for a public channel, `G…` for a
+  private one — never a `#name`. Find it in the channel's details in Slack
+  (**View channel details**, near the bottom). Passing a `#name` is refused.
+- `events` narrows which of the six kinds post to this link; omit it (or pass
+  an empty list) for all six.
+- `includeCost` appends the run's spend line to messages for this link.
+- Invite the bot to any private channel before linking it:
+  `/invite @wardby` in that channel.
+- Re-linking the same channel and subject replaces `events` and
+  `includeCost` and clears any previously recorded delivery error — send the
+  full desired state each time.
+
+Then confirm delivery works before relying on it:
+
+```json
+{ "id": "<link id from link_notification_channel>" }
+```
+
+`test_notification_channel` posts "✅ wardby is connected to this channel." —
+if the bot can't write there, you get the error immediately instead of
+finding out when the first real event is dropped. A successful test also
+clears the link's `lastError`.
+
+`list_notification_channels` shows every link's `lastError` and its pending
+and failed delivery counts (counted per channel: two links to the same
+channel show the same counts); filter by `projectKey`, `agentId`, or `channel`.
+Listing your own agent's links needs read access to that agent; listing
+everything (or filtering by `projectKey`) needs `agents:admin` with the admin
+role. `unlink_notification_channel` removes a link by `id`.
+
+## Failure modes
+
+- **Channel not found, bot not in channel, or channel archived.** That
+  channel's pending deliveries fail immediately and are never retried, and
+  every link to it shows the error in `lastError`. Invite the bot
+  (`/invite @wardby`) or otherwise fix the channel in Slack. New events
+  deliver as soon as the bot can post there again; the deliveries that
+  already failed are not resent. Re-linking the channel (or a successful
+  `test_notification_channel`) clears `lastError`. See
+  [`errors/slack-channel-unreachable`](../help/errors/slack-channel-unreachable.md).
+- **Invalid or revoked token.** Delivery pauses for every linked channel (no
+  deliveries are lost — they stay pending), and wardby re-checks the token
+  every five minutes with Slack's `auth.test`; it resumes automatically once
+  the check succeeds. See
+  [`errors/slack-auth-failed`](../help/errors/slack-auth-failed.md).
+- **A missing scope.** Delivery pauses the same way, but `auth.test` needs no
+  scope, so the five-minute check succeeds, the next delivery fails again,
+  and delivery pauses again. It does not fix itself: add the scope to the app
+  and reinstall it to the workspace (and if Slack issues a new token, set it
+  and restart wardby). Pending deliveries are kept and sent once it works.
+- **Rate limits.** wardby paces its own posts to about one per second per
+  channel; if Slack still responds with a rate-limit error, that delivery is
+  retried after the delay Slack specifies, with no attempt counted against
+  the retry limit below.
+- **Transient errors** (network issues, Slack 5xx responses) are retried with
+  increasing back-off, up to 10 attempts, before the delivery is marked
+  failed.
+- **Events while Slack isn't configured.** An event recorded before
+  `WARDBY_SLACK_BOT_TOKEN` is set is not queued and is not delivered once you
+  configure it — only events recorded after Slack notifications are enabled
+  reach Slack.
+- **Duplicates.** Delivery is at least once: if wardby crashes or loses its
+  database connection right after Slack accepts a message, that message can
+  be posted again. A rare duplicate thread reply is possible.
+- **Retention.** Delivery records are kept for 30 days and then pruned.
+
+## Security
+
+Phase 1 is outbound only: wardby requests no event subscriptions and no
+interactivity in the manifest, so there is no new inbound endpoint and
+nothing posted in Slack can start or affect a run.
+
+What leaves to Slack: issue keys, titles, and their links; pull request
+numbers and links; agent names; review verdicts; fix-round numbers; a failed
+run's reason (its first line, at most 200 characters); and, only when a
+link's `includeCost` is on, the run's spend line. wardby never posts code,
+diffs, review bodies, or run output, and an error message shown in Slack is a
+short first line only, never a full error or stack trace.
+
+Issue titles go to the linked channel regardless of Jira issue security: an
+issue restricted by a Jira security level still has its key and title posted.
+Link a project only to a channel whose members may see every issue in it.
+
+The bot token stays on the wardby server; agents, sandboxed tools, and
+coding-run workers never see it.