@defrex/autobuild 0.10.1 → 0.12.0

package/docs/configuration.md

@@ -14,6 +14,18 @@ and sessionless `ab init --validate` readiness check. Examples labelled as
 fragments are intended to be added to an existing file; the [complete
 example](#complete-example) is valid on its own.
 
+## `[store]`
+
+| Key | Required | Values / purpose |
+|---|---|---|
+| `url` | When `[store]` exists | Absolute HTTPS service base URL; loopback HTTP is allowed for development. No credentials, query or fragment. Trailing slashes are normalized. |
+
+Selection is explicit `--store` > nonblank `AB_STORE` > `[store] url` > the main
+checkout's `.autobuild/`. A configured service without a user credential fails
+with `ab connect` guidance. `AB_TOKEN` overrides the saved service/project
+credential. See [connecting a project](hosted-service.md#connect-a-project).
+Changing the store requires restarting dispatch.
+
 ## Hosted service and PostgreSQL BuildStore environment
 
 The optional `@defrex/autobuild-hosted-store-service` and its
@@ -59,14 +71,14 @@ separate signed-user token described by the [operator API](operator-api.md).
 | `AB_HOST` | Optional, ordinary Bun host | Bind hostname; defaults to `0.0.0.0`. Vercel supplies its own listener. |
 | `PORT` | Optional, ordinary Bun host | Integer 1–65535; defaults to `3000`. Vercel supplies its own listener. |
 | `AB_STORE` | Remote client | Hosted service base URL used by the kernel, phase commands, and dashboard. |
-| `AB_TOKEN` | Authenticated remote client | Offline-minted bearer token; this is not the signing secret. |
+| `AB_TOKEN` | Authenticated remote client | Explicit project bearer credential override for CI; otherwise use ab connect. This is not the signing secret. |
 | `BETTER_AUTH_SECRET` | Web dashboard | Independent server-only session secret with at least 32 high-entropy characters. |
 | `BETTER_AUTH_URL` | Web dashboard | Exact HTTP(S) origin, without credentials or a path; HTTPS is mandatory in production. |
 | `GITHUB_CLIENT_ID` | GitHub sign-in | OAuth application client id. |
 | `GITHUB_CLIENT_SECRET` | GitHub sign-in | Server-only OAuth application secret. |
 | `AB_WEB_AUTH_PROVIDERS` | Web dashboard | Comma-separated provider set; currently exactly `github`. |
 | `AB_WEB_ALLOWED_EMAILS` | Web dashboard | Nonempty comma-separated operator email allowlist; matching is case-insensitive. |
-| `AB_WEB_REPOSITORIES` | Web dashboard | Nonempty comma-separated repository allowlist exposed to signed-in operators. Entries are repository identities — normalized `https://` origins (ssh-like spellings such as `git@github.com:owner/repo.git` are accepted and normalized); they must match the Store's identity for the repository. |
+| `AB_WEB_REPOSITORIES` | Hosted service | Deprecated once-per-database bootstrap CSV for the durable project registry. Use owner commands thereafter; see [connected projects](setup.md#connected-projects). |
 
 GitHub's callback is `{BETTER_AUTH_URL}/api/auth/callback/github`; the app needs
 the `user:email` scope (or GitHub App read-only email permission). Sessions are
@@ -168,7 +180,7 @@ the branch head never carried the file — the deposit records the source
 provenance declines to attribute them to any commit. **Deployment-owned** sections — `[roles]`
 (runtime, model, args, alternates, per-role `sessionBudgetSeconds`) and
 `[policy]` — keep flowing live. **Dispatcher-owned** sections (`baseBranch`,
-`capacity`, `forge`, `plugins`, `pr`, `tickets`, `orchestrator`) configure the
+`capacity`, `ticketScanIntervalSeconds`, `forge`, `plugins`, `pr`, `tickets`, `orchestrator`) configure the
 dispatcher itself and are never interpreted by the build runner.
 
 Consequently, an accepted base-branch reload re-deposits only the
@@ -195,6 +207,7 @@ These fields hot-reload:
 | Field or table | Boundary where a new value applies |
 |---|---|
 | `baseBranch` | Next dispatch or base fallback decision; existing `build.created` facts remain immutable. |
+| `ticketScanIntervalSeconds` | Next tick; evaluates elapsed time against the new interval. |
 | `capacity` | Next dispatcher tick. |
 | `[pr]` | Next build creation. |
 | `[commands]` | Next setup, verify check, or finalize check selected for a build whose OWN branch carries it. A base-branch reload does not retarget an in-flight build. |
@@ -211,6 +224,7 @@ remain pinned to their startup values and are reported explicitly:
 
 | Restart-required field | Reason |
 |---|---|
+| `store` | Store selection and project authority are fixed when dispatch starts. |
 | `plugins` | Plugin modules and registration catalogs load before wiring. |
 | `forge` | Selects the constructed Forge adapter. |
 | `workspace.provider`, `workspace.config` | Select and configure the constructed workspace provider. |
@@ -229,10 +243,24 @@ any table header.
 | Field | Default | Constraints | Purpose |
 |---|---:|---|---|
 | `baseBranch` | `"main"` | nonempty string | Branch used to cut builds, target PRs, and merge during reconciliation. |
+| `ticketScanIntervalSeconds` | `60` | positive integer seconds | Ticket-source ready scan cadence; tick spacing is the effective minimum. |
 | `capacity` | `1` | positive integer | Maximum concurrent nonterminal builds for this repository. Paused and blocked builds still occupy capacity. |
 | `forge` | `"github"` | nonblank string | Forge adapter name. Shipped values are `github` and `local-git`; configured plugins may register other names. |
 | `plugins` | `[]` | array of unique nonblank module specifiers | Trusted Bun plugin modules loaded by dispatch, `ab ticket`, and scoped phase CLI processes. |
 
+Ticket-source ready scans run immediately when no completed measurement exists,
+then every
+`ticketScanIntervalSeconds` (default 60 seconds, a positive integer). Actual
+tick spacing is the floor when the configured interval is shorter. A
+same-repository `pr.merged`, `build.completed`, or `build.aborted` fact forces
+another scan on the next tick; changed ready criteria also force a scan.
+Housekeeping keeps its ordinary tick cadence. Between scans, queue depth and
+standing diagnostics repeat the last completed measurement, including across
+process restarts. Tickets groomed directly in the tracker are picked up within
+one scan interval plus one tick when capacity permits. Observation while intake
+is off shares the cadence; an observation measurement cannot suppress a fresh
+admission scan when intake is enabled.
+
 ### Plugin modules
 
 <!-- config-fragment:plugins -->
@@ -313,7 +341,12 @@ without adding a runtime Autobuild dependency to the plugin. That entry point
 exports the manifest/factory types, port types, fake adapters, and reusable
 TicketSource, AgentRunner, WorkspaceProvider, Forge, BuildStore, and BlobStore
 contract suites. Adapter values may use the backward-compatible bare factory or
-carry a contract fixture descriptor. Ticket sources may also declare
+carry a contract fixture descriptor.
+TicketSource adapters must populate the required `Ticket.resolved` boolean on
+listReady, get, and create projections, using the same native lifecycle rules as
+`dependencyStates`. Plugin authors upgrading older adapters must add this field;
+ready-state membership does not imply that a ticket is unresolved. Dispatch
+reuses these facts only within the current tick. Ticket sources may also declare
 `requiredEnv`; the host checks every declared variable for a nonempty value
 before invoking the adapter factory. Plugins using Forge abort-cleanup and
 AgentRunner turn-cancellation capabilities introduced in API 1.2 should require
@@ -337,7 +370,7 @@ manifest parse), and each `capabilities.requiredEnv` group must declare at
 least one of `dispatchMessage` / `validationMessage` — a group with neither is
 rejected at manifest parse, because the host would silently skip it at both
 enforcement sites. API 1.7 extends the workspace-provider factory context with
-the host-derived seams: `storeRef` and `storeToken` (guaranteed present under
+the host-derived seams: `storeRef` and `delegateCredential` (guaranteed present under
 `capabilities.storeRequirements`), `runtimeReferences`, and the checkout-less
 `origin` and `remoteBranchHead` readers, all optional and ignored by factories
 that do not read them. A plugin reading the new seams should require `^1.7.0`.
@@ -611,7 +644,7 @@ no longer matches the identity the current system would deliver is refreshed
 by reinstalling the archive before reuse, so an upgraded dispatcher retrofits
 its persistent guests (see "Guest distribution version selection and delivery"
 in docs/setup.md for the release-and-upgrade delivery path and the hosted
-store's version-lockstep gate). Immediately
+store's supported client window). Immediately
 before every build-child launch, the adapter verifies the
 provisioned absolute Bun executable and every referenced runtime again. A
 failure names the runtime, selecting role/alternate, stage, and provisioning
@@ -737,6 +770,28 @@ as written.
 
 ## `[verify]` and `[verify.<step>]`
 
+Post-reconcile verification defaults to enabled: `[verify].afterReconcile = true`.
+Set it to `false` to retain pre-reconcile verification and skip all steps after
+reconciliation. An optional boolean `[verify.<step>].afterReconcile` overrides
+the repository setting in either direction; overrides require a configured step.
+For example, set `afterReconcile = false` in `[verify]` and
+`afterReconcile = true` in `[verify.types]` to keep only that step re-running.
+
+The kernel freezes the resolved ordered policy in
+`verify.reconcile-policy-captured` at the next engine action after reconcile
+completion. Live configuration changes apply at that boundary; a cycle already
+started keeps its policy through recovery. Historical cycles already started
+without a captured policy retain the rerun-all behavior. Initial verification
+and verification after subsequent code review always use ordinary applicability.
+Policy exclusion precedes plan selection and paths, including `always = true`.
+Enabled steps still follow plan selection and path rules. Excluded steps record
+`verify.completed` with outcome `skipped`, `skipCause = "post-reconcile-policy"`,
+and a reason naming the setting. Dashboards and PR summaries call this
+"skipped by post-reconcile policy"; it is never a pass. Forge-side required
+checks and branch protections still gate merge. For excluded steps, merged code
+is not re-verified, so breakage that only exists in the combination can land.
+
+
 `[verify].steps` defines the configured universe and execution order. It is
 optional and defaults to no verify phases. Every listed name needs one matching
 subtable, and every named subtable must be listed; a defined-but-unlisted step
@@ -756,6 +811,7 @@ There are two strict step variants:
 | `command` | — | required for check; nonempty key in `[commands]` | Deterministic shell verb to run. Forbidden for agent steps. |
 | `skill` | — | required for agent; nonempty string | Exact installed verifier skill. Forbidden for check steps. |
 | `paths` | omitted (unconditional) | optional nonempty array of positive repository-relative globs | Apply only when at least one changed path matches. Available to both variants. |
+| `afterReconcile` | repository: `true`; step: inherited | boolean | Step override wins over `[verify].afterReconcile`; false skips this step after reconciliation only. |
 | `always` | omitted (`false`) | optional boolean | `true` makes the step mandatory in plan selection and bypasses path gating. Available to both variants. |
 
 <!-- config-fragment:verify -->
@@ -1112,6 +1168,7 @@ Optional. Every field receives its own default. All are positive integers except
 | `sessionBudgetSeconds` | `3600` | positive integer | Wall-clock bound for each build agent session unless its logical role overrides it. |
 | `stallRounds` | `3` | positive integer | Escalate when the same review finding survives this many rounds. |
 | `maxVerifyAttempts` | `3` | positive integer | Bound failure-driven verify → implement retry cycles. |
+| `maxDispatchAttempts` | `3` | positive integer | Bound consecutive dispatch failures before human escalation. |
 | `maxSetupAttempts` | `3` | positive integer | Bound consecutive workspace setup failures before human escalation. |
 | `maxInfrastructureAttempts` | `3` | positive integer | Bound consecutive provision/start/wait/cleanup failures before a setup-targeted policy escalation; a human `retry` answer re-arms this budget. |
 | `maxReconcileAttempts` | `3` | positive integer | Bound completed reconciles that leave the PR conflicted against an unchanged authoritative base. Moving-base races do not consume the bound. |
@@ -1119,6 +1176,15 @@ Optional. Every field receives its own default. All are positive integers except
 | `harvestThreshold` | `5` | positive integer | New unclaimed observation occurrences needed to start one harvest run. |
 | `harvestMaxDrift` | `3` | nonnegative integer | Other builds merged after the oldest unclaimed observation needed to start a run; `0` disables drift. |
 
+Dispatch failures share a `[policy].maxDispatchAttempts` budget (default 3) across
+create, workspace, spec, comment, and launch stages. Exhaustion raises one
+`dispatch-failure-limit` policy escalation naming the latest stage and error,
+and parks dispatch until answered. Both bare `ab answer <slug>` retries and
+text guidance grant a fresh budget; abort does not. Confirmed runner attachment
+clears the streak. Recovery-provider workspace failures belong exclusively to
+the infrastructure budget. Exhaustion is repaired from durable facts on restart
+before further dispatch work.
+
 For each repeat conflict, Autobuild compares the base merged by the most recent
 completed reconcile with a fresh authoritative base snapshot. An advanced base
 proves the attempt lost a race and permits another reconcile regardless of the
@@ -1169,9 +1235,10 @@ state. Within a present table, `source` and `readyState` are required.
 | `readyState` | — | required nonblank string | The one workflow state eligible for dispatch. |
 | `readyAssignee` | — | optional; `"me"` or an email address; Linear only (rejected for file, hosted, and plugin sources) | Require the ticket to be assigned to one Linear user, in addition to the state and label gates. |
 | `teamKey` | — | required for Linear and hosted; forbidden for file; optional for plugins | Backend team key such as `"ENG"`, or an existing plugin config field. |
-| `claimedState` | `"In Progress"` for direct Linear; hosted backend default otherwise | optional nonempty string; forbidden for file; allowed for plugins | Workflow state entered when a ticket is claimed. |
+| `claimedState` | `"In Progress"` for direct Linear; `"Doing"` for hosted | optional nonempty string; forbidden for file; allowed for plugins | Workflow state entered when a ticket is claimed. |
+| `doneState` | `"Done"` | optional nonblank string; hosted | Project completion state and merged-ticket transition. |
 | `createState` | provider default | optional nonempty string | Default state for newly created tickets when `ab ticket create` omits `--state`. |
-| `triageState` | Linear: `"Backlog"`; file/plugin: `"Triage"` | optional nonempty string | State used for spec-gate bounces, aborts, and closed-unmerged PRs. |
+| `triageState` | Linear/hosted: `"Backlog"`; file/plugin: `"Triage"` | optional nonempty string | State used for spec-gate bounces, aborts, and closed-unmerged PRs. |
 | `proposalState` | the resolved `triageState` | optional nonempty string | State harvest files its synthesized proposals into. Setting it to `readyState` waives the human grooming gate, not dependency eligibility. |
 | `dir` | file: selected local state root's `tickets/`; plugin: omitted | optional nonempty path; forbidden for Linear; allowed for plugins | Root containing file-source state directories, or an existing plugin config field. Relative file paths resolve from the repository. |
 
@@ -1259,6 +1326,15 @@ triageState = "Backlog"
 Linear credentials do not belong in this table. Set `LINEAR_API_KEY` in the
 environment or local `.env` file described below.
 
+[Linear's request budget](https://linear.app/developers/rate-limiting) is shared
+by every dispatcher and `ab ticket` command using the API key, and by other keys
+belonging to the same authenticated user. A rate-limited ready scan or dependency
+read fails the evaluation tick without new intake claims or synthetic
+dependency-blocked counts. That source instance suppresses requests until the
+reported reset time; the next call then runs normally. Missing, invalid or expired
+reset headers use a conservative 60-second cooldown. Cooldowns are local to the
+instance: processes and restarts do not coordinate their budgets.
+
 For a hosted backend, repository policy remains local while credentials remain
 at the service:
 
@@ -1274,17 +1350,18 @@ createState = "Triage"
 triageState = "Triage"
 ```
 
-Set `AB_STORE` to the service's HTTP(S) URL and `AB_TOKEN` to a deployment
-operator token (`mint operator` without `--user`). The same source-agnostic wiring powers dispatch, harvest, ticket-aware
+Set `AB_STORE` to the service's HTTP(S) URL and `AB_TOKEN` to a stored credential
+for that registered project (`credentials issue REPOSITORY --user IDENTITY`). The same source-agnostic wiring powers dispatch, harvest, ticket-aware
 skills, and all seven command families: `ab ticket create`, `update`, `block`,
 `unblock`, `list`, `show`, and `move`. See the
-[hosted ticket protocol](remote-ticket-protocol.md). In hosted Linear mode,
-`LINEAR_API_KEY` is configured only on the service; direct Linear remains
-supported.
+[hosted ticket protocol](remote-ticket-protocol.md). Tickets are partitioned by
+the credential's registered project; lifecycle comes from its latest effective
+configuration. The service has no Linear backend and refuses ticket operations
+for projects using external sources. Direct Linear remains dispatcher-side.
 
 When filing dependent tickets into the ready state, follow the
-[safe blocker-filing workflow](ticket-dependencies.md). Direct and hosted Linear
-create the issue before recording its blockers, so `create --blocked-by` is not
+[safe blocker-filing workflow](ticket-dependencies.md). Direct Linear
+creates the issue before recording its blockers, so `create --blocked-by` is not
 an atomic publication guarantee. Stage outside ready, verify the relationships,
 then move to the intended ready state last.
 
@@ -1323,7 +1400,7 @@ restart-classified as a whole.
 | `model` | — | nonblank string, required when `enabled = true` | Provider-qualified model string for the turn runner, in the same vocabulary as `[roles]` model strings (a leading `vercel-ai-gateway/` prefix is accepted and stripped). Resolved through the deployment's gateway credential. |
 | `invocationBudgetSeconds` | `240` | positive integer, clamped to 300 | Wall-clock budget for one turn invocation. A larger value is clamped — not rejected — to the 300-second hosted function limit the runner executes under (`ORCHESTRATOR_ROUTE_LIMIT_SECONDS`, the same number the operator route pins as `maxDuration`). |
 | `approvals` | see below | array of `tool` or `tool:qualifier` strings | Registry tool names whose calls suspend a turn until the operator answers. Default: `["builds.control:abort", "builds.control:discard", "builds.answer:revise-spec", "sandbox.publish", "tickets.move:ready"]`. Empty (`[]`) means none — autonomous operation. An entry naming an absent or unknown tool is **inert by design**, never a config error: the list stays stable while the registry grows, and a tool's removal cannot break parsing. A `tool:qualifier` entry applies to the named discriminator value only (for example `tickets.move:ready` approves moving a ticket to `ready`); for a tool without a discriminator, only the bare form matches. |
-| `wake` | inherits the default | array of event-type globs | The attention events a **new** session wakes for. Kept schema-optional so absent (inherit the default attention set — the build events `ab watch` filters on by default plus the repository-journal events `ab watch --repository` follows) and `[]` (never wake; message-only) stay distinct. Each glob must match at least one build or repository-journal event type, validated with the same compiler `ab watch` uses. Existing sessions never retroactively inherit; an explicit `PUT .../wake` always wins. |
+| `wake` | inherits the default | array of event-type globs | The attention events a **new** session wakes for. Kept schema-optional so absent (inherit the default attention set — the build events `ab watch` filters on by default plus the repository-journal events `ab watch` follows) and `[]` (never wake; message-only) stay distinct. Each glob must match at least one build or repository-journal event type, validated with the same compiler `ab watch` uses. Existing sessions never retroactively inherit; an explicit `PUT .../wake` always wins. |
 | `sandbox` | — | strict subtable; absence reads as the defaults | Sandbox behavior knobs. |
 
 `[orchestrator.sandbox]` fields:
@@ -1465,6 +1542,7 @@ sessionBudgetSeconds = 7200
 sessionBudgetSeconds = 3600
 stallRounds = 3
 maxVerifyAttempts = 3
+maxDispatchAttempts = 3
 maxSetupAttempts = 3
 maxInfrastructureAttempts = 3
 maxReconcileAttempts = 3
@@ -1624,9 +1702,9 @@ Secrets and store selection accompany the file through environment variables:
 
 | Variable | Used for | Notes |
 |---|---|---|
-| `LINEAR_API_KEY` | Direct Linear ticket source | Required and nonempty when `tickets.source = "linear"`; in hosted Linear mode it is service-only. |
-| `AB_STORE` | BuildStore and hosted ticket selection | A local path or HTTP(S) remote-store URL. `tickets.source = "hosted"` requires a nonblank HTTP(S) URL. A command's explicit `--store` wins for BuildStore selection, then nonblank `AB_STORE`, then the main checkout's `.autobuild/`. Relative local paths resolve from the main checkout. |
-| `AB_TOKEN` | Protected remote BuildStore and hosted tickets | Bearer credential forwarded to the service. Hosted tickets require deployment operator scope (`mint operator` without `--user`). Empty means no token; nonempty token bytes are treated as opaque. |
+| `LINEAR_API_KEY` | Direct Linear ticket source | Required and nonempty when `tickets.source = "linear"`; never used by the hosted service. |
+| `AB_STORE` | BuildStore and hosted ticket selection | A local path or HTTP(S) remote-store URL. `tickets.source = "hosted"` requires a nonblank HTTP(S) URL. A command's explicit `--store` wins for BuildStore selection, then nonblank `AB_STORE`, then `[store] url`, then the main checkout's `.autobuild/`. Relative local paths resolve from the main checkout. |
+| `AB_TOKEN` | Protected remote BuildStore and hosted tickets | Bearer credential forwarded to the service. Hosted tickets require a stored credential for a registered project. Owner admin is an explicit break-glass exception. Empty means no token; nonempty token bytes are treated as opaque. |
 
 A local store selection relocates the state database, blobs, worktrees, and the
 default file-ticket directory together. With a remote store, Git worktrees and
@@ -1766,3 +1844,43 @@ progress is not shown. Harvest does not consume build capacity.
 - **Remote BuildStore:** confirm the effective `AB_STORE` URL and `AB_TOKEN`.
   A protected store reports 401 for a missing, invalid, or expired token and
   403 when the token is valid but scoped to another build/session.
+
+### Hosted project selection
+
+The durable PostgreSQL project registry controls dashboard, MCP and operator
+API access. Every allowlisted user sees every active entry. Administer it with
+`ab-hosted-store projects list|add|remove` using deployment database credentials;
+mutations require `--user IDENTITY` for declared attribution. See
+[connected projects](setup.md#connected-projects) for migration and retention.
+`AB_DISPATCHER_REPOSITORIES` optionally selects an ordered subset of current
+registrations. When unset, each authorized tick queries all active entries.
+Removed credential override keys are inert in dynamic mode; explicit-list
+configuration still rejects unknown override keys.
+
+## Hosted service client compatibility
+
+A service accepts stable clients from its own `major.minor` release line and
+the two preceding minor lines in the same major. A major starts a new family:
+X.0 accepts only X.0, X.1 accepts X.0/X.1, and X.2 onward accepts three lines.
+Patch versions are interchangeable in both directions and must never change
+the protocol. Upgrade the service first, then projects independently within
+its window. Supported release lines retain their wire handlers and known
+protocol identities; an unknown protocol is refused independently of version.
+Malformed, missing, and prerelease identities are refused with HTTP 409.
+A newer client is told to upgrade the service; a client below the window is
+told to upgrade the project's Autobuild. Diagnostics name the service version
+and supported range.
+
+Unauthenticated `GET /health` publishes `ok`, `autobuildVersion`,
+`protocolVersion`, and `supportedClientRange: { minVersion, maxVersionExclusive }`.
+The range is inclusive at the minimum and exclusive at the maximum; a 0.11.x
+service publishes `>=0.9.0 <0.12.0`. Health needs no credentials, version
+headers, or available backend.
+
+Remote workspace factories must use `delegateCredential(storeRef, undefined,
+target)` to obtain per-resource grants before provisioning or launching guests.
+The callback keeps parent authority in host composition. `storeToken` is retired
+and is never supplied; factory environments also exclude `AB_TOKEN`. Launch
+credentials travel through the separate transient execution-auth argument, never
+through serialized execution identity. Existing plugins that forwarded
+`storeToken` must migrate to this callback and fail closed if it is unavailable.

package/docs/hosted-dispatcher.md

@@ -14,6 +14,16 @@ it once a minute by default), so builds no longer depend on a maintainer's
 machine. A deployment that does not install the package serves the hosted
 store, ticket, operator, and web endpoints and never attempts a dispatch tick.
 
+The [minimal hosted service deployment](hosted-service.md) defaults to store-only
+mode and supplies no cron. The source-checkout deployment below retains the
+opt-in dispatcher packing and shipping pipeline.
+
+For a dispatcher running as a local user or service manager, first
+[connect the project](hosted-service.md#connect-a-project). Origin-mode dispatch
+can read the committed `[store] url` and the same user credential by origin.
+A deployment running under another identity needs its own project credential;
+`AB_TOKEN` remains the explicit CI override.
+
 ## Enabling the schedule
 
 1. Deploy the hosted service with the dispatcher package installed and the
@@ -255,6 +265,11 @@ 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
+stored project credential the dispatcher issues for each repository tick
 (`AB_DISPATCHER_TOKEN_TTL_SECONDS`, default 7 days — keep it longer than your
-largest `timeoutSeconds` guest lifetime).
+largest `timeoutSeconds` guest lifetime). Its immutable dispatcher purpose
+permits raw Store and hosted tickets only, never operator controls. The service
+checks registration and revocation on each request. Tick return does not revoke
+it; spawned builds may outlive the tick. Owner-issued project credentials and
+the owner-only break-glass admin are documented in the
+[remote Store protocol](remote-store-protocol.md#7-authentication-and-project-authority).

package/docs/hosted-service.md

@@ -0,0 +1,214 @@
+# Deploy a hosted service
+
+A service hosts the BuildStore, tickets, dashboard, sign-in, and MCP endpoint.
+The default deployment stores state while dispatch runs on another machine.
+You need Bun 1.4.x, a Git repository, a Vercel project, PostgreSQL, a blob
+backend, and a GitHub OAuth application.
+
+Create a new directory containing these two files (also shipped in the hosted
+package's `deployment/` directory and in `templates/hosted-service/`).
+
+`package.json`:
+
+```json
+{
+  "private": true,
+  "scripts": {
+    "build": "ab-hosted-service-build"
+  },
+  "dependencies": {
+    "@defrex/autobuild-hosted-store-service": "0.12.0",
+    "@defrex/autobuild": "0.12.0",
+    "next": "16.1.6",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  }
+}
+```
+
+`vercel.json`:
+
+```json
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "installCommand": "bun install --frozen-lockfile",
+  "buildCommand": "bun run build",
+  "bunVersion": "1.4.x"
+}
+```
+
+Run `bun install`, then commit both files and `bun.lock`. Add `.gitignore`
+entries for `node_modules/`, `.next/`, `.vercel/`, `app/`, `next.config.ts`,
+`next-env.d.ts`, `tsconfig.json`, and `.autobuild-service-assets.json`.
+These application assets are generated during each build. Keep your own files
+outside those names; the builder refuses to overwrite consumer-owned files.
+Do not commit generated application sources or edit them to customize deployment.
+
+Push the directory to your Git host. Import it in Vercel with the repository
+root as Root Directory and Next.js as the framework. The checked-in platform
+configuration installs the lockfile and runs `bun run build`. Each build stages
+the installed package, runs its idempotent database migrations against the
+configured database, then builds Next into the root `.next/`. Missing database
+configuration, incompatible schema, or a failed migration stops the build.
+Provide database access from the build environment as well as runtime.
+
+## Connect a project
+
+From a checkout with an origin remote, run `ab connect https://YOUR_ORIGIN`.
+The CLI prints a verification URL and short code and attempts to open a browser.
+Sign in as an allowed owner, check the full repository identity and code, and
+approve or deny. Another device can open the printed URL, or visit `/connect`
+and enter the code. Approval requires the web-enabled service origin; a
+standalone machine-only listener cannot present browser consent. Requests
+expire after ten minutes. Denial and timeout leave local configuration unchanged.
+
+On approval the service registers the project and issues a project credential.
+The CLI keeps it in `$XDG_CONFIG_HOME/autobuild/credentials` (or
+`~/.config/autobuild/credentials`), keyed by normalized service and origin,
+with directory mode 0700 and file mode 0600. Credentials never belong in the
+repository. It adds the non-secret `[store] url` to `autobuild.toml` when
+absent; review and commit that change yourself. An existing different URL
+must be changed explicitly before connecting. Reconnecting replaces the saved
+credential only after approval and revokes the previous credential.
+
+All worktrees share the main checkout's configuration and the user's saved
+credential. A service manager running as that user uses the same HOME and
+XDG_CONFIG_HOME, with no AB_STORE or AB_TOKEN exports. A fresh clone with
+committed store configuration but no saved credential fails with `ab connect`
+guidance; it never silently creates local state. Run connect on each host/user.
+
+`ab connect` without a URL reports service, project, and credential status:
+accepted, rejected, missing, or unreachable. `ab disconnect` revokes the saved
+credential remotely before removing it locally, keeping the project registered,
+its data, and store configuration. A network/server failure retains the local
+entry for retry; an already revoked credential can be removed. If saving a new
+connection fails, the CLI cancels/revokes it and retains the previous entry.
+If remote cleanup cannot be confirmed, check the printed credential id with
+the owner's administrative tools before retrying.
+
+Store selection is `--store` > nonblank `AB_STORE` > `[store] url` > the
+main checkout's `.autobuild/`. `AB_TOKEN` overrides the exact service/project's
+saved credential for CI and other non-interactive hosts. A service override
+never borrows another service's credential. Build and harvest sessions keep
+their explicit scoped authority.
+
+## Environment
+
+Set these server-side variables in every Vercel environment you deploy:
+
+- `AB_POSTGRES_URL` or `DATABASE_URL`: PostgreSQL connection URL. The explicit
+  `AB_POSTGRES_URL` takes precedence; use the same database at build and runtime.
+- `AB_STORE_SECRET`: a high-entropy secret for machine token signing.
+- `AB_BLOB_BACKEND=vercel` with `BLOB_READ_WRITE_TOKEN`, or `AB_BLOB_BACKEND=s3`
+  with `AB_S3_BUCKET`, `AB_S3_REGION`, `AB_S3_ACCESS_KEY_ID`, and
+  `AB_S3_SECRET_ACCESS_KEY` (and optional endpoint for compatible storage).
+- `BETTER_AUTH_SECRET`: an independent high-entropy secret of at least 32 characters.
+- `BETTER_AUTH_URL`: the exact production HTTPS origin, with no path.
+- `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`: GitHub OAuth application credentials.
+- `AB_WEB_AUTH_PROVIDERS=github`.
+- `AB_WEB_ALLOWED_EMAILS`: comma-separated operator email allowlist.
+- `AB_WEB_REPOSITORIES`: comma-separated repository origins visible to operators.
+
+Register `https://YOUR_ORIGIN/api/auth/callback/github` as the GitHub callback
+and allow read-only email access (`user:email`). Sign-in must use the configured
+production origin. Do not expose secrets through `NEXT_PUBLIC_` variables.
+See the [complete environment reference](configuration.md) for storage,
+project ticket lifecycle, credential administration, and optional MCP resource configuration.
+
+## Check the deployment
+
+`GET /health` returns service and protocol versions. Open `/sign-in` and sign
+in; `/` redirects unauthenticated browsers to sign-in. Machine routes
+require a machine token; `/mcp` challenges an unauthenticated client with OAuth
+resource metadata. Check both discovery documents:
+
+```sh
+curl https://YOUR_ORIGIN/.well-known/oauth-protected-resource
+curl https://YOUR_ORIGIN/.well-known/oauth-authorization-server
+```
+
+The authorization-server document advertises a reachable `/api/auth/jwks`
+URI and `/api/auth/mcp/register` dynamic registration endpoint. MCP clients
+register with `redirect_uris` as an array of strings and
+`token_endpoint_auth_method: "none"`; treat the returned `client_id` as opaque.
+See [MCP](mcp.md) for authorization and client setup.
+
+Without the optional hosted dispatcher installed, `GET /api/dispatch` returns
+503 JSON: `{"error":"dispatch runs elsewhere for this deployment"}`. The
+template has no cron and installs no dispatcher/provider package. Run dispatch
+from a connected project or follow the separate, opt-in
+[hosted dispatcher procedure](hosted-dispatcher.md), which retains its
+source-checkout packaging and cron setup.
+
+## Upgrade
+
+Bump the exact hosted-service and core package pins in `package.json` to the
+same new release, run `bun install` to refresh `bun.lock`, commit, and push.
+Vercel's Git integration migrates and builds the pinned package automatically.
+Upgrade the service **before connected projects**: that is the order expected
+by the protocol compatibility window. No source extraction, patch application,
+or manual production deployment is required.
+
+## Hosted ticket projects and v1 migration
+
+Hosted queues are partitioned by registered repository. Credentials select the
+project, and its latest uploaded effective `[tickets]` configuration selects the
+lifecycle; see the [ticket protocol](remote-ticket-protocol.md). If configuration
+is unavailable, run that project's dispatcher to publish it. Projects using file,
+Linear or another external source continue to access it directly through their
+dispatcher. Service ticket surfaces refuse those projects with source feedback.
+The service never connects to Linear.
+
+The removed `AB_TICKET_BACKEND` and `LINEAR_API_KEY` settings are ignored for
+all values, including blanks, with one startup message asking for removal.
+The removed `AB_TICKET_TRIAGE_STATE`, `AB_TICKET_READY_STATE`,
+`AB_TICKET_DOING_STATE` and `AB_TICKET_DONE_STATE` settings are ignored even if
+malformed. Lifecycle now comes only from project configuration.
+
+The environment-aware migration first imports `AB_WEB_REPOSITORIES` into the
+registry once, including upgrades from released main schema v9 where registry
+tables do not yet exist. This import and the main-schema promotion share the
+ticket transaction: a stopped ticket migration rolls them back too. The owner
+`projects add` and `tickets assign-team` commands can independently bootstrap
+the registry while that old main marker remains, so recovery does not require
+a successful ticket migration. If the retired environment is unavailable,
+register the intended project with `ab-hosted-store projects add REPOSITORY
+--user IDENTITY` before assigning its legacy team. Once the import succeeds,
+later changes to the retired environment are ignored.
+
+Fresh databases install ticket schema v2 directly. Existing team-keyed v1
+queues migrate in one transaction. For each registered project, migration reads
+the effective configuration selected by its latest dispatcher run and reloads,
+including the actual immutable artifact bytes in blob storage. A legacy team
+must have one claimant, or an explicit owner assignment. A registered project
+with no dispatcher run or no selected effective-config reference makes no team
+claim and does not block other projects. Unclaimed teams still stop unchanged.
+When ownership must be inferred, a selected but missing, inaccessible or invalid
+configuration fails closed with the project and remaining teams in the message.
+Restore those bytes or explicitly assign every remaining legacy team, then
+rerun; complete assignments to registered projects settle ownership without
+reading unrelated configurations. Conflicting claimants and asset ownership
+conflicts also stop without changing schema markers or tickets.
+Historical ids, states, timestamps, blockers, comments and asset rows remain
+unchanged. Review the named projects and resolve a shared legacy team locally:
+
+```sh
+ab-hosted-store tickets assign-team ENG https://github.com/acme/app --user owner@example.com
+ab-postgres-store migrate
+```
+
+The assignment command works before the v2 migration succeeds and records the
+actor in an append-only journal. The latest assignment moves the whole legacy
+team once; it grants no future cross-project access. It must name a registered
+project. Rerun migration after resolving every named team or configuration error.
+
+For populated-v1 upgrades, both the owner migration CLI and `deploy:build` need
+the same blob backend, access, credentials and `AB_BLOB_PREFIX` as the running
+service: S3 bucket/region/credentials (and endpoint/path style when configured),
+or Vercel access mode and token/OIDC store identity. The deployment build inherits
+these variables and runs the environment-aware migration before Next build.
+Missing blob configuration or denied reads stop deployment before Next builds;
+diagnostics never print credentials. SQL-only fresh installs, empty-v1 upgrades
+and already-v2 reruns do not open blob storage and keep their existing database
+requirements. Migration reruns are idempotent.

package/docs/mcp.md

@@ -110,8 +110,14 @@ the standard surface the endpoint serves.
   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).
+- `AB_WEB_REPOSITORIES` (deprecated): optional once-per-database registry
+  bootstrap, never an ongoing allowlist. `repositories.list` queries current
+  active registrations on every call, and every tool checks current membership.
+
+Every allowlisted user sees every registered project. Database-authorized
+owners use the [project commands](setup.md#connected-projects) to add or remove
+projects without redeploying. Removal hides retained data until re-registration;
+registry failures never authorize a call.
 
 The endpoint requires no additional variables beyond the hosted service's
 existing web/auth set. Note that consent renders when the client sends