@defrex/autobuild 0.11.0 → 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
@@ -212,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. |
@@ -357,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`.
@@ -631,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
@@ -757,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
@@ -776,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 -->
@@ -1132,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. |
@@ -1139,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
@@ -1189,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. |
 
@@ -1303,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.
 
@@ -1494,6 +1542,7 @@ sessionBudgetSeconds = 7200
 sessionBudgetSeconds = 3600
 stallRounds = 3
 maxVerifyAttempts = 3
+maxDispatchAttempts = 3
 maxSetupAttempts = 3
 maxInfrastructureAttempts = 3
 maxReconcileAttempts = 3
@@ -1653,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
@@ -1795,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

package/docs/operator-api.md

@@ -6,17 +6,48 @@ Every request must send `X-Autobuild-Version`,
 `X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
 
-Mint a token offline; the signed user is used as the human actor on every write:
+Project credentials are opaque `abp_1_<id>_<secret>` bearer values bound to one
+registered normalized repository. The service stores only a SHA-256 digest of
+the random secret, plus project, creator, creation time, last use, expiry and
+revocation metadata. It checks credential status and project registration on
+every request. Revocation takes effect on the next request without affecting
+other credentials. Unknown, expired or revoked credentials receive `401 auth`;
+removed projects receive `403 auth` with `project not registered`.
+
+The deployment owner runs these commands locally with database access:
 
 ```sh
-AB_STORE_SECRET='…' bun packages/hosted-store-service/src/bin.ts mint operator \
-  --user 'Ada Lovelace' --ttl-seconds 3600
+ab-hosted-store credentials issue https://github.com/acme/app --user owner@example.com
+ab-hosted-store credentials list https://github.com/acme/app
+ab-hosted-store credentials revoke https://github.com/acme/app --id ID --user owner@example.com
 ```
 
-Admin, build, repository, and deployment (`{ "operator": true, … }`) tokens
-have no attributed operator authority. Human-operator tokens have no raw
-`/builds`, `/repos`, `/sessions`, or `/tickets` authority. Encode repository,
-build, session, and artifact kind as separate URL path segments.
+Issue prints the secret once; list contains metadata only. Issue optionally
+accepts `--ttl-seconds N` or `--expires-at ISO-8601`. For administrative/non-interactive issuance, set the returned token as
+`AB_TOKEN`. Interactive project onboarding uses `ab connect <service-url>`;
+it saves the credential outside the repository and commits no secret. Previous `AB_TOKEN` values and `mint operator` / `mint build` are
+retired: the service responds that the credential format changed and points
+to `credentials issue`. Supported old protocol shapes still work with a new
+credential; protocol compatibility does not restore retired authentication.
+
+`mint admin --ttl-seconds N` creates an explicit versioned, attributed owner
+break-glass credential. It can cross project boundaries. Keep it owner-only:
+never give it or `AB_STORE_SECRET` to a dispatcher or build agent.
+
+Owner-purpose project credentials attribute every write to their recorded creator.
+Dispatcher-purpose credentials are refused. Signed-in owners in the dashboard
+and MCP receive short-lived internal signatures with an explicit version,
+selected repository, signed user, expiry and MCP `via`. Only the service holds
+the signing key. These signatures authorize operator routes only and require a
+registered project; replay against another project is refused.
+
+The path project is checked before registry lookup, body parsing and generic
+tool execution. Body repositories and secondary build/session identifiers are
+also checked inside that project. Explicit project mismatches return `403 auth:
+wrong project`; removal returns `403 auth: project not registered`. Encode each
+repository, build, session and artifact kind as a separate URL path segment.
+Registration changes use the database-local `projects list|add|remove` owner
+commands; see [owner workflow](setup.md#connected-projects).
 
 ## Operator sessions
 
@@ -201,3 +232,55 @@ identity, plus the usual repo/build/state/cursor fields. It invents no durable
 sequence or actor. Retain the cursor to avoid repeat reports across invocations.
 No lease alone is not evidence of death. SIGINT, SIGHUP and SIGTERM drain dispatch,
 record the first signal in the stop fact, and release its lease before exit.
+
+### CLI attention monitoring
+
+The default watch reports actionable conditions only:
+
+- Build `escalation.raised`, or `build.merge-decision`: a finalized open PR
+  with auto-merge off or a current actionable merge-gate deferral. Armed consent
+  awaiting application is silent. One merge decision is reported per build/PR.
+- Repository `harvest.escalated`, `harvest.recovery-exhausted`,
+  `dispatcher.config-rejected`, `dispatcher.config-reloaded` with nonempty
+  `restartRequired`, abnormal `dispatcher.run-stopped`, and `dispatcher.lost`.
+- `dispatcher.ticket-source-persistent`: degradation past its advertised
+  reset time, once a tick started at or after reset has completed or failed
+  with the episode still open; crossing reset alone is silent. Without a reset,
+  the deadline is 15 minutes after onset. Repeated evidence never postpones
+  the deadline; recovery ends the episode.
+- `dispatcher.tick-failure-persistent`: continuously failing completed ticks
+  for five minutes in one run. A successful tick, new run, or matching stop
+  ends the episode. Source grace and cooldown-driven failures do not start
+  this clock; after grace, the first qualifying failure starts a new five-minute
+  interval. Each persistence episode is reported once.
+
+Repository conditions are included with no slugs or with `--repository`.
+Routine outcomes and self-healing failures are silent. Repeatable
+`--event <glob>` replaces the default and selects exactly matching catalog
+events (plus the existing `dispatcher.lost` observation); use explicit globs
+to opt into failures, finalize, merge, or completion events.
+
+Derived records use `observation` instead of `event`, without inventing a
+durable sequence or actor. Merge observations carry `type`, `pr`, `reason`,
+and `observedAt`, plus the build slug and normal reduced state. Persistence
+observations carry source/cause/message/resetAt when advertised (or
+run/firstFailure/error), `episodeSeq`, and `observedAt`; repository records
+have `repo` and null build/state. Source observations also report
+`dependencyLimited`.
+
+Every record carries a cursor, including timer-only records. Resuming suppresses
+delivered merge decisions and persistence episodes even when stream positions
+did not advance. Old v1 cursors remain valid: historical eligible merge
+decisions are treated as consumed; active overdue repository episodes may
+report because old watches had no persistence notification. Fresh attachment
+silently baselines historical direct events and merge decisions, but retains
+active repository timers. Reconcile existing conditions through status after
+arming the watch. Named watches still end when every named build is terminal;
+learn their outcomes from status reconciliation at exit.
+
+`ab wait --for attention` is build-only and uses the same build conditions:
+an open escalation or a merge decision. Existing conditions return immediately,
+even with `--since`; live and backlog matches ignore routine outcomes and
+self-healing failures. A merge match uses the watch observation with
+`condition: "attention"`. Explicit `--event` globs remain event-only.
+Watch and wait preserve each other's cursor notification metadata.