@defrex/autobuild 0.8.0

package/docs/hosted-dispatcher-cutover-validation.md

@@ -0,0 +1,178 @@
+# Hosted dispatcher cutover validation — AUT-320
+
+- **Validation run:** 2026-09-11, window 19:06:24Z – 19:41:52Z; verification re-derived from fresh Store snapshots at 22:41Z and again at 23:29Z after the implement phase re-ran in a fresh workspace (the durable log below is live and keeps accumulating)
+- **Build:** `validate-hosted-dispatcher` on `https://autobuild.defrex.com` (durable event log: `GET /builds/validate-hosted-dispatcher/events` or the web dashboard)
+- **Branch:** `ab/validate-hosted-dispatcher` (PR publication requested with auto-merge; publication and merge happen after the implement session — the build slug carries the final merged state)
+- **Tickets:** [AUT-320](https://linear.app/issue/AUT-320) (this validation), [AUT-304](https://linear.app/issue/AUT-304) (acceptance evidence attached to its body)
+- **Method note:** all numbers below were re-derived from fresh Store snapshots at implement time, at the guidance round (repository journal seq 1–926, build event log seq 1–45, as of 2026-09-11T22:41Z), and again at 23:29Z on the re-run implement session (journal seq 1–1117, build event log seq 1–60). Snapshots are labeled as-of; the durable event log is authoritative.
+
+## Checklist verdicts
+
+| Checklist item | Verdict | Evidence |
+| --- | --- | --- |
+| Environment variables set | ✅ | Hosted ticks deposit `dispatcher-effective-config` artifacts (rev 50 as of 19:54:50Z) declaring workspace provider `vercel-sandbox`, env var `AI_GATEWAY_API_KEY`, AI-gateway model sessions (`vercel-ai-gateway/zai/glm-5.3-flash`, `vercel-ai-gateway/meta/muse-spark-1.3`), and runtime provisioning with preflight checks. Every hosted tick since 19:06 completes and deposits the artifact. |
+| Cron live | ✅ | 265 `dispatcher.run-started` events at ≈60 s median cadence from 19:06:24Z through 23:28:50Z (latest snapshot), all run ids `hosted-dispatcher-<uuid>`, all 265 ending `run-stopped outcome=normal`. |
+| Harvest gate off | ✅ | Last `harvest.completed` at 03:05:04Z (journal seq 59); no `harvest.*` event since. |
+| Local `ab-dispatch-kernel` stopped on every maintainer machine | ✅ (store-side layers + maintainer attestation with attached evidence) | Three-layer verification below. The store-side layers prove no interactive local dispatcher ever wrote to this repository and no dispatcher of any mode claimed build work in the window; the process-level residue on maintainer machines is covered by the maintainer's attestation with attached command output (see Process evidence). |
+
+## Three-layer verification
+
+The journal alone cannot prove absence of local dispatchers: only the interactive
+frontend's child kernel carries a `kernelRunId`, so a headless local run
+(`ab dispatch --once --plain`) writes no `dispatcher.run-started`/tick events at
+all. The verification therefore stacks three bounded layers.
+
+### Layer 1 — Repository journal (proves: hosted cadence live; no *interactive* local dispatcher)
+
+Journal seq 1–1117, complete from 2026-09-11T02:17:59Z (no gaps; the hosted
+repository store came up that morning). Re-derived 22:41Z and again 23:29Z.
+Findings:
+
+- 265 `dispatcher.run-started` events — **every one** with run id prefixed
+  `hosted-dispatcher-`; zero bare-UUID (interactive local) run ids in the
+  entire journal history.
+- Cadence ≈60 s median (min 11 s, max 63 s; first 19:06:24Z, last in snapshot
+  23:28:50Z); 265/265 `run-stopped` with `outcome=normal`.
+- The only two `dispatcher.tick-yielded` events (seq 144, 19:25:50Z; seq 1111,
+  23:27:52Z) are both hosted→hosted (run/holder ids all `hosted-dispatcher-*`).
+- No `harvest.*` event after 03:05:04Z (none after the window opened).
+- Zero journal events mention any maintainer hostname (`aron-desktop` does not
+  appear anywhere in the journal).
+
+**Bound:** proves nothing about headless local dispatchers, which never write
+journal events.
+
+### Layer 2 — Build-scoped execution facts (proves: no dispatcher of *any* mode claimed work in the window)
+
+A dispatcher that actually claims and works a build writes build-scoped facts
+regardless of interactive/headless mode: `workspace.provision-started` and,
+decisively, `execution.started` whose `instance` is
+`${hostname()}-${slug}-inst_<id>` — a plain store append, never gated on
+`kernelRunId`. The hosted deployment stamps the Vercel function's hostname
+(link-local `169.254.x.x` form); a maintainer machine's dispatcher would stamp
+its own hostname.
+
+- Build census (store `GET /builds`): the only build created after the window
+  opened is `validate-hosted-dispatcher` (19:06:33Z); no older build was
+  updated during the window (re-derived 22:41Z and again 23:29Z).
+- This build's `execution.started` events both stamp hosted instances:
+  seq 21 (19:26:06Z, generation 0)
+  `instance=169.254.67.163-validate-hosted-dispatcher-inst_e031dd81`,
+  `provider=vercel-sandbox`, `sessionId=sbx_d4pBpd0TAJQyKxBW0setr3e8F7sE`;
+  seq 56 (23:28:09Z, generation 1)
+  `instance=169.254.30.93-validate-hosted-dispatcher-inst_d69843ce` —
+  the hosted host component in both cases.
+- Zero `execution.started` events with a foreign hostname in the window;
+  zero `workspace.provision-started` events anywhere in the store's builds
+  outside this build during the window.
+
+**Bound:** an idle local dispatcher that claims nothing still leaves no trace;
+that residue is covered by Layer 3.
+
+**Recovery-fact caveat (recorded for honesty):** `infrastructure.failed`
+recovery facts carry the fixed instance name `dispatcher-recovery` and are
+attributed to the supervising (hosted) tick, so they are bounded by the hosted
+tick cadence rather than their own instance string. This build's three
+`infrastructure.failed` events are all provision failures of the incident
+below.
+
+### Layer 3 — Maintainer-machine process evidence (supplied by the maintainer)
+
+An idle local `ab dispatch` process that claims nothing leaves no store trace,
+so this layer cannot be derived from the Store. The implementer escalated
+(`esc_e93b2831`, raised from this build) asking the maintainer to run, on every
+maintainer machine during the window, `pgrep -fl "ab-dispatch-kernel|ab
+dispatch"` plus scheduler listings (launchd/cron/systemd user timers) and
+attach the output to the escalation answer. The maintainer answered with a
+full attestation **and attached command output**, folded into the Process
+evidence section below.
+
+## Process evidence (maintainer attestation, escalation esc_e93b2831)
+
+The maintainer collected the evidence at 2026-09-11T19:49Z on **aron-desktop**
+— the **only** maintainer machine (Linux; there is no macOS or Windows
+maintainer machine, so launchd/launchctl and PowerShell checks do not apply).
+Summary of the attached evidence:
+
+1. **Processes.** `pgrep -fl "ab-dispatch-kernel|ab dispatch"` found exactly
+   two processes (1096539 `bun …/bin/ab.ts dispatch`, 1096573
+   `bun …/bin/ab-dispatch-kernel.ts`), both started 19:39:54Z, both with
+   working directory `/home/defrex/code/parakeeto` — a **different
+   repository's checkout** with its own Store repository identity. They cannot
+   claim or supervise builds for `https://github.com/defrex/autobuild`. No `ab
+   dispatch` process with cwd `/home/defrex/code/autobuild` exists.
+2. **Last local dispatcher for this repository.** A headless `ab dispatch
+   --plain --auto-merge` (kernel run id prefix `aron-desktop-*`) exited at
+   18:06:13Z — its log ends "dispatcher superseded by another invocation —
+   detaching / ab dispatch stopped" — 60 minutes **before** the validation
+   window opened at 19:06Z. It was never restarted.
+3. **User schedulers.** `crontab -l` → crontab is not installed on the machine
+   (no user cron entries possible); `systemctl --user list-timers --all` → "0
+   timers listed". No launchd (not macOS).
+4. **Corroborating durable evidence.** Every `dispatcher.run-started` /
+   tick / `run-stopped` fact for this repository from 19:06:24Z onward carries
+   a `hosted-dispatcher-<uuid>` run id (first:
+   `hosted-dispatcher-c5fa724f-fa11-4250-8dbb-3274510a2022`); no
+   `aron-desktop-*` holder appears in the journal after 18:06Z. This build's
+   own `execution.started` (seq 21) names instance
+   `169.254.67.163-validate-hosted-dispatcher-inst_e031dd81` — a hosted
+   function address, not a maintainer host.
+
+**Maintainer conclusion (verbatim intent):** no local `ab dispatch` process for
+this repository was running during 19:06–19:42Z, and none is running now.
+Recorded as maintainer attestation with the attached outputs; the store-side
+Layers 1–2 independently prove no dispatcher of any mode claimed or executed
+build work in the window.
+
+## Provision incident (honest record)
+
+The first three provision attempts failed with
+`Executable not found in $PATH: "bun"` (19:06–19:15Z) — the exact symptom
+`docs/hosted-dispatcher.md` documents for a deployment that skipped
+`pack-distribution`. After `maxInfrastructureAttempts` (3) was exhausted the
+kernel raised escalation `esc_84b0cddf` (19:15:51Z, policy guard
+`infrastructure-failure-limit`); the operator answered with a bare retry at
+19:24:37Z, and provisioning succeeded at 19:25:51Z on the next hosted tick.
+The generation-1 re-provision (23:26:54Z → 23:27:53Z, after the publication
+note below) succeeded with no operator intervention.
+**Verdict: the cutover works, with one operator intervention.** A follow-up
+observation was recorded for the deployment's build/pack step.
+
+## Publication note (honest record)
+
+The implement phase requested publication at 22:43:01Z (event seq 49,
+`publication.requested`; auto-merge had been requested at build creation,
+seq 2). That first publication did not complete before the implement
+workspace's environment lifetime ended: `execution.ended` at 23:26:51Z
+(seq 51), the workspace was released, and a fresh generation-1 workspace was
+provisioned for the re-run implement session. The prior workspace's un-pushed
+commits were lost with it; store-side deposits (build artifacts, observations,
+the escalation answer, the AUT-304 evidence section) persisted. This session
+re-committed the repository deliverable (this document) and re-requests
+publication. Publication, verify, review, and merge happen after this
+session; the build slug `validate-hosted-dispatcher` carries the final state.
+A follow-up observation was recorded for the publication path.
+
+## Cutover outcome (as of implement time)
+
+- Ticket moved to Todo → claimed and built by the hosted deployment alone:
+  **confirmed** (Layers 1–2; single active build, hosted execution instances).
+- Published as a PR, and merged: PR publication is **requested** (auto-merge
+  requested at build creation; publication re-requested by this session) from
+  branch `ab/validate-hosted-dispatcher` into `main`; verify, review,
+  publication, and merge happen after this session, and the build slug
+  `validate-hosted-dispatcher` on the dashboard carries the final state. This
+  document deliberately does not claim "published" or "merged".
+
+## Evidence index
+
+- Build event log (durable, live): `https://autobuild.defrex.com` → build
+  `validate-hosted-dispatcher` (API: `GET /builds/validate-hosted-dispatcher/events`)
+- Repository journal (durable, live): `GET /repos/https%3A%2F%2Fgithub.com%2Fdefrex%2Fautobuild/events`
+- Deposited build artifacts: `cutover-build-event-log`, `cutover-repository-journal`,
+  `cutover-validation-report` (attached to the PR description at finalize)
+- Dispatcher effective config: repository artifact kind
+  `dispatcher-effective-config`, rev 50 as of 2026-09-11T19:54:50Z
+- Branch: `ab/validate-hosted-dispatcher` → PR into `main` (auto-merge requested)
+- Tickets: [AUT-320](https://linear.app/issue/AUT-320),
+  [AUT-304](https://linear.app/issue/AUT-304) (evidence section appended to body)

package/docs/hosted-dispatcher.md

@@ -0,0 +1,204 @@
+# The hosted dispatcher
+
+The optional [hosted service](../packages/hosted-store-service/README.md) can
+own the dispatch kernel. One authenticated HTTP endpoint — `GET /api/dispatch`
+— runs, for each configured repository, one bounded origin-mode dispatcher
+tick: the kernel claims ready tickets, provisions and launches sandboxes,
+observes running builds, settles publications, opens and merges PRs, and runs
+the janitor, exactly as a local `ab dispatch --once --repository <origin>`
+pass does. The schedule is what you attach to that endpoint (Vercel Cron calls
+it once a minute by default), so builds no longer depend on a maintainer's
+machine.
+
+## Enabling the schedule
+
+1. Deploy the hosted service with the dispatcher variables from
+   [its README](../packages/hosted-store-service/README.md#hosted-dispatcher)
+   — `AB_DISPATCHER_ORIGIN`, the repository set, `CRON_SECRET`, and the forge
+   credentials the kernel needs (`GITHUB_TOKEN` or `GH_TOKEN`, plus any
+   guest-forwarded variables such as `AI_GATEWAY_API_KEY`). A deployment
+   serving repositories across GitHub identities configures per-repository
+   tokens with `AB_DISPATCHER_GITHUB_TOKENS`; repositories without an
+   override keep using the shared credential. A served repository with
+   neither fails its tick: origin-mode dispatch requires an exported token
+   and never falls back to the gh CLI login of whoever runs the service.
+2. Schedule the route by adding a `crons` entry to the deployment's
+   `vercel.json` and redeploying. Vercel issues a plain GET with
+   `Authorization: Bearer <CRON_SECRET>` once per minute:
+
+   ```json
+   {
+     "crons": [{ "path": "/api/dispatch", "schedule": "* * * * *" }]
+   }
+   ```
+
+3. Verify: `curl -H "Authorization: Bearer $CRON_SECRET" https://YOUR_ORIGIN/api/dispatch`
+   returns `200 {"ok":true,"repositories":[{"repository":"…","outcome":"ticked","runId":"hosted-dispatcher-…"}]}`.
+   Unauthenticated or wrongly authorized calls are rejected (401) and do no
+   work; a deployment without `CRON_SECRET` answers 403 with the endpoint
+   disabled. One repository's failure never prevents another's tick.
+
+## Shipping the guest distribution
+
+Every sandbox installs the Autobuild distribution the launching dispatcher
+runs. A local dispatcher packs it from its source checkout with `bun pm pack`;
+a bundled deployment has neither `bun` nor a source tree at runtime, so it
+must pack the archive while both exist — in its build step — and carry it into
+the function bundle:
+
+```json
+{ "scripts": { "deploy:build": "bun packages/hosted-store-service/src/bin.ts pack-distribution && bun run postgres:migrate && bun run build && bun tools/ship-packed-distribution.ts" } }
+```
+
+`pack-distribution` writes `.autobuild-dist/autobuild-<version>.tgz` under the
+distribution root (`--root DIR` overrides). The Next.js config's
+`outputFileTracingIncludes: { '/api/dispatch': ['./.autobuild-dist/**'] }`
+records the intent to include that directory in the cron route's bundle, but
+Next 16's default Turbopack builds never apply `outputFileTracingIncludes`
+(only webpack builds do), so a deployment cannot rely on the config alone. The
+autobuild-api pipeline therefore ends `deploy:build` with a post-build trace
+step (`bun tools/ship-packed-distribution.ts`) that appends the archive to the
+dispatch route's `route.js.nft.json` — the trace file Vercel's Next builder
+consumes when assembling the function bundle — and fails the deploy loudly if
+nothing was packed or the trace file is missing. A deployment using this
+pipeline cannot ship without the archive; deployments that skip both packing
+and the trace step still fail at runtime.
+
+At runtime the kernel takes, in order: `AB_DISTRIBUTION_ARCHIVE` (an explicit
+archive path), the single archive under `.autobuild-dist/` of the
+distribution root or working directory, a source checkout packed on the spot,
+and finally the running version's published distribution — the npm registry
+tarball, else the GitHub release asset. A tick that
+reports `Executable not found in $PATH: "bun"` during `provision` is a
+deployment that skipped the pack step (or, outside this pipeline, the trace
+step that ships the archive).
+
+## Bounding the invocation
+
+The endpoint is pinned to `maxDuration = 300` seconds (Vercel Pro's default
+function duration). `AB_DISPATCHER_BUDGET_SECONDS` (default 240) bounds the
+kernel's work inside that: an already-expired budget skips the tick, a budget
+reached mid-drain stops awaiting running builds, and a repository whose budget
+no longer covers a minimum-remaining floor is answered as `skipped`. Unfinished
+work resumes on the next invocation: guests keep running while the supervising
+function detaches, and the next tick settles their completion from the Store
+plus provider liveness. Raise `maxDuration` and the budget **together** (e.g.
+`"maxDuration": 800` with a budget of 780 — the parser clamps 10–780); keep the
+budget at least ~20 s below the function duration so the response always
+returns.
+
+## Overlap and missed ticks
+
+Invocations are serialized by the durable repository supervisor lease: a second
+overlapping invocation yields (it records `dispatcher.tick-yielded` naming the
+holder in the repository journal and performs no claims, launches, or
+publications), and the loser's response still answers 200. A missed or late
+invocation is never incorrect: a build whose guest finished while no invocation
+ran is settled — completion facts, lease, publication — by the next
+invocation's settlement stage, and a build whose sandbox timed out is recovered
+by the lease sweep as with any dispatcher.
+
+One provider behavior matters for that settlement: Vercel's plain command
+lookup reports no exit code for a command that finished while no client was
+waiting on it, and keeps reporting none until some client issues a wait on the
+command. The dispatcher's execution observation therefore issues one bounded
+(~5 s) wait on the recorded command whenever the lookup shows no exit: a wait
+that resolves proves the guest's end (with its exit code) and the build settles
+in that same tick, while a timed-out wait leaves the guest running — one
+observation never approaches the tick's operation timeout, and the next tick
+retries. Settlement of a guest that exited after the launching invocation
+detached is expected within one tick of its exit.
+
+## Pausing during an incident
+
+- **Stop the schedule**: remove the `crons` entry (or disable the cron in the
+  Vercel dashboard) and redeploy.
+- **Revoke the credential**: rotate `CRON_SECRET` — every in-flight schedule
+  call starts answering 401.
+- **Soft stop**: turn repository intake OFF (operator API `PUT
+  /operator/v1/repos/{repo}/settings/intake` with `{"enabled": false}`, or the
+  web dashboard) — running builds finish their current phases but no new ticket
+  is claimed. A repository-wide or per-build pause holds queued work the same
+  way and takes effect on the next invocation.
+
+## Observing the hosted dispatcher
+
+Every invocation is durable: tick reports
+(`dispatcher.tick-started`/`-completed`/`-yielded`), run boundaries
+(`dispatcher.run-started`/`-stopped`), and a per-minute
+`dispatcher-effective-config` artifact deposit all carry the
+`hosted-dispatcher-<uuid>` run id, so the web dashboard's repository journal
+and the operator API show hosted activity exactly as they show a local
+dispatcher. Expect the repository journal to grow by roughly one config
+artifact per minute per repository; the dispatcher run/config artifacts
+themselves are retention-bounded (see below), while the journal's events keep
+accumulating by design.
+
+This is true of *every* dispatcher, not only the hosted one. A local `ab
+dispatch` pointed at the hosted Store — a watch, an operator cron on a host,
+a manual one-shot — synthesizes its own `<host>-dispatch-<id>` run id and
+journals the same run boundaries and tick facts under it. That makes cutover
+verification answerable from the journal alone:
+
+- Every `dispatcher.*` event with a non-`hosted-dispatcher` run id is direct
+  evidence that another dispatcher was writing to the hosted Store.
+- A journal window with no `dispatcher.*` events at all means no dispatcher
+  ran against the Store in that window.
+- The launch-flag facts (`dispatcher.intake-set`,
+  `dispatcher.auto-merge-default-set`) carry the writing invocation's run id
+  alongside their human actor, so even those writes identify the dispatcher
+  that performed them.
+
+### Runtime logs
+
+Every invocation also writes to the deployment's runtime logs (Vercel's
+**Logs** tab, or `vercel logs`), which is where to look first when the journal
+shows no hosted activity at all — a rejected or misconfigured invocation never
+reaches the journal. Every line starts with `hosted-dispatcher <invocation id>`
+so one invocation's lines can be filtered together:
+
+- the request line (`GET /api/dispatch agent="vercel-cron/1.0"`) — the user
+  agent tells a cron call apart from an operator's curl;
+- `rejected 401|403|405 <kind>: <reason>` at error level, with whether the
+  authorization header was absent or present-but-wrong (never its value);
+- `500 configuration invalid: <error>` naming the offending variable;
+- `tick start repositories=N budgetSeconds=S origin=…`, then per repository
+  `tick run=hosted-dispatcher-…`, `ticked … ms=…`, `skipped`, or
+  `failed … : <error with stack>` at error level, then
+  `tick complete ticked=… failed=… skipped=…` and `200 ok ms=…`;
+- the kernel's own report lines (the same lines `ab dispatch --plain` prints
+  locally) prefixed `<repository> [kernel]`, warnings at error level.
+
+Secrets, forge tokens, and minted guest tokens never appear in any line.
+
+## Artifact retention
+
+Dispatcher-generated run/config artifacts — the repository-scoped
+`dispatcher-effective-config` and `dispatcher-config` kinds and the
+build-scoped `build-runner-effective-config` kind — keep the **latest 200
+revisions per kind** (per repository, respectively per build). When a new
+revision of one of these kinds is deposited, the store prunes the older
+revisions past the bound at deposit time, inside the same transaction.
+Events and journal entries are never pruned, so historical event payloads may
+reference a pruned revision; the current run's snapshot is always among the
+newest deposits and stays retrievable, and every existing read surface
+(latest-by-default artifact reads, listings) works unchanged. The bound is
+overridable per deployment with `AB_ARTIFACT_RETENTION_MAX_REVISIONS` (a
+positive integer; see the store environment documentation). All other
+artifact kinds (build logs, `pr-description`, phase artifacts) are not
+subject to retention.
+
+## Sandbox authentication
+
+Inside a Vercel Function the Sandbox SDK authenticates with the deployment's
+own OIDC identity: Vercel hands each invocation its token on the
+`x-vercel-oidc-token` request header (not as a `VERCEL_OIDC_TOKEN` environment
+variable), and the endpoint passes it to the kernel under that name for the
+duration of the tick. The tick log line reports which credential the kernel
+presents (`sandboxAuth=oidc-header`, `oidc-env`, `token`, or `none`); `none`
+means the project has OIDC federation disabled (Settings → Security). No
+long-lived `VERCEL_TOKEN` belongs on the service. Guests never receive a Vercel
+token or forge credential; they authenticate to the Store with the short-TTL
+deployment operator token the dispatcher mints for the tick
+(`AB_DISPATCHER_TOKEN_TTL_SECONDS`, default 7 days — keep it longer than your
+largest `timeoutSeconds` guest lifetime).

package/docs/mcp.md

@@ -0,0 +1,119 @@
+# The hosted MCP server
+
+The hosted service exposes the agent tool registry over [Streamable HTTP](https://modelcontextprotocol.io) at
+`/mcp`, on the same origin as the operator dashboard. External agents — Claude
+web, Claude Desktop, Claude Code, Codex, or any harness with an MCP client —
+get the same operator surface the embedded orchestrator has, at parity by
+construction: tool names, descriptions, JSON schemas, and annotations are read
+from the registry's closed table, and every execution goes through the
+operator API's token-verified protocol.
+
+## What the endpoint serves
+
+- **Every registry tool**, with its schema and annotations, plus
+  **`repositories.list`** — a read-only tool returning the repository
+  identities this deployment serves (the values every tool's `repo` field
+  accepts). The binding is data-driven: when a future ticket adds registry
+  entries, they appear on the endpoint with no change to the deployment.
+- **Server instructions** summarizing how Autobuild works (dispatcher, builds,
+  tickets, harvest, notes) and pointing clients at `repositories.list`.
+- A **stateless transport**: fresh transport and server per request, JSON
+  responses, no session ids. Every request is authenticated independently, so
+  cold starts behave identically to warm instances.
+
+## Authentication: OAuth 2.1 through Better Auth
+
+The endpoint is an OAuth 2.1 **protected resource**; the deployment's Better
+Auth instance is the **authorization server**. An unauthenticated request to
+`/mcp` receives `401` with an RFC 9728 `WWW-Authenticate` challenge pointing at
+`/.well-known/oauth-protected-resource`. From there a client:
+
+1. Reads the protected-resource metadata (served at the origin root and under
+   `/api/auth`) to discover the authorization server.
+2. Reads the authorization-server metadata
+   (`/.well-known/oauth-authorization-server`) — authorization, token, and
+   dynamic-registration endpoints, plus the `jwks_uri`.
+3. Registers dynamically (`POST /api/auth/mcp/register`, RFC 7591); the
+   registered `client_name` becomes the `via` marker recorded on writes.
+4. Runs the authorization-code flow with PKCE through `GET /api/auth/mcp/authorize`.
+   A signed-out person is redirected to the deployment's sign-in page (the
+   existing GitHub sign-in and email allowlist); the flow resumes after
+   sign-in. A person outside the allowlist cannot complete the flow — and the
+   resource re-checks the allowlist on every tool call, so a person dropped
+   from the list has their live tokens refused immediately (`403`).
+5. Exchanges the code at `/api/auth/mcp/token`; access tokens are short-lived
+   and refresh tokens rotate. Consent renders only when the client sends
+   `prompt=consent` (the plugin's designed behavior); clients that omit it
+   receive a code directly.
+
+Every tool call resolves the token's subject to the signed-in operator, mints
+the same 30-second attributed operator token the web gateway mints — stamped
+with `via: {kind: "mcp", client}` — and executes the named tool through the
+operator server. A mutating tool's durable event therefore names the person
+who authorized the client and which client executed it:
+
+```json
+{ "kind": "human", "user": "ada@example.com", "via": { "kind": "mcp", "client": "Claude web" } }
+```
+
+Tool calls naming a repository outside the deployment's served set are refused
+(`kind: "validation"`).
+
+## Duration limits
+
+The MCP route's `maxDuration` is 300 s (Vercel Pro default) — the same pairing
+the [dispatcher route](hosted-dispatcher.md) documents. Tool-requested bounded
+waits (`builds.events`' `waitSeconds`) are clamped to **`MCP_MAX_WAIT_SECONDS`
+= 240 s** at the binding, so no single MCP request outlives the route's limit;
+the registry's own schema currently caps that tool's waits lower, and the
+clamp is the guard that holds if that cap rises.
+
+## Connecting clients
+
+### Claude web (custom connector)
+
+Settings → Connectors → **Add custom connector**, enter the deployment URL
+plus `/mcp` (e.g. `https://operator.example/mcp`). Claude discovers the
+authorization server from the protected-resource metadata, registers
+dynamically, and sends the person through GitHub sign-in and the consent page;
+the OAuth callback is `https://claude.ai/api/mcp/auth_callback` (allowed by
+dynamic registration — no configuration needed on the deployment).
+
+### Claude Code
+
+```sh
+claude mcp add --transport http autobuild https://operator.example/mcp
+```
+
+Claude Code runs the same OAuth 2.1 flow in the terminal (it opens a browser
+for sign-in and consent).
+
+### Codex
+
+```sh
+codex mcp add autobuild --url https://operator.example/mcp
+```
+
+### Any MCP client
+
+Point the client at `<deployment>/mcp` over Streamable HTTP. A client only
+needs RFC 9728 discovery, dynamic client registration, PKCE, and refresh —
+the standard surface the endpoint serves.
+
+## Operational variables
+
+- `AB_WEB_MCP_RESOURCE` (optional): the protected resource the plugin binds
+  tokens to. Defaults to `<BETTER_AUTH_URL>/mcp`, which is correct for the
+  standard deployment; override only when a proxy or custom domain fronts the
+  function. Must be an absolute http(s) URL (https in production).
+- `BETTER_AUTH_URL`: the public origin — the authorization-server issuer and
+  the default MCP resource's base.
+- `AB_WEB_ALLOWED_EMAILS`: the operator allowlist. Sign-in admission and every
+  MCP tool call are checked against it.
+- `AB_WEB_REPOSITORIES`: the served repository identities (the
+  `repositories.list` payload and the per-call `repo` scope).
+
+The endpoint requires no additional variables beyond the hosted service's
+existing web/auth set. Note that consent renders when the client sends
+`prompt=consent`; a client that omits it gets a code directly (the plugin's
+designed behavior).