@defrex/autobuild 0.11.0 → 0.13.0

package/docs/architecture.md

@@ -333,7 +333,19 @@ head is a no-op; Git/Forge failures stay failure-tolerant observations.
 **Verify gating.** `packages/core/src/ontology.ts` owns the canonical
 `pass | fail | skipped` outcome (only `fail` routes back to implement or
 consumes attempts; a skip satisfies one step without being passing
-evidence). Two kernel-authored skip sources narrow the configured universe:
+evidence). Three kernel-authored skip sources narrow the configured universe:
+post-reconcile policy, approved plan selection, and changed paths.
+The engine captures the ordered effective `afterReconcile` policy in
+`verify.reconcile-policy-captured` at the action after reconciliation completes,
+before verification starts. Log-index replay keeps it scoped to that completion;
+subsequent config changes cannot replace it mid-cycle. Historical already-started
+cycles without a snapshot retain rerun-all behavior. A later code-review approval
+restores ordinary verification. Policy exclusions precede plan/path applicability
+and carry `skipCause: "post-reconcile-policy"` plus a setting-specific reason.
+The shared dashboard model renders that reason, as does the PR summary.
+Excluded steps do not re-verify merged code, so combination-only breakage can
+land; forge requirements and reconcile budgets remain independent.
+For enabled steps,
 `packages/core/src/kernel/plan-verify-selection.ts` resolves an approved plan's front-matter
 selection (applied at the planner's `ab done` in `packages/core/src/cli/terminals.ts`,
 snapshotted by the engine at approval), and
@@ -341,7 +353,7 @@ snapshotted by the engine at approval), and
 selectors, resolved by the build runner via `git diff` against the initial
 branch-cut base (or the refreshed base promoted by a completed reconcile).
 This verify-only base is deliberately independent from implementation's
-focused review range. Both narrowing mechanisms produce the ordinary
+focused review range. All narrowing mechanisms produce the ordinary
 queryable skipped outcome; Git failure is infrastructure and fails closed,
 never a synthetic skip. Verify escalation routing is also explicit in the
 engine: guidance answering an agent verifier's own `ab escalate` returns to the
@@ -352,6 +364,10 @@ once. Guidance answering the policy escalation after failed-report exhaustion
 instead routes to `implement` and outranks the pending report. A bare retry carries no
 feedback.
 
+The dispatcher launch boundary uses `processes/execution-no-progress.ts` to
+project clean empty execution streaks through `RepoViewStore` snapshots and
+conditionally raise an ordinary setup policy escalation before a fourth launch.
+
 **Launch ownership.** `packages/core/src/cli/dispatch.ts` is the kernel owner and
 single-flights supervised build executions per slug within its process. It
 publishes effective config into the build artifact namespace, claims the exact
@@ -579,7 +595,7 @@ slug routing. Upgrade performs the same composition lazily at its first merge
 conflict.
 
 `packages/core/src/cli/repo-state.ts` owns repository identity and store precedence
-(`--store` > `AB_STORE` > `.autobuild/`); `packages/core/src/cli/store-opening.ts` is the
+(`--store` > `AB_STORE` > `[store] url` > `.autobuild/`); `packages/core/src/cli/store-opening.ts` is the
 production store composition boundary shared by finite sessionless queries and
 phase sessions. Its shared scoping primitive preserves remote token composition
 and adds local ambient authority only for filesystem stores. The dedicated
@@ -599,7 +615,15 @@ phase-only commands report their complete runner context when run by hand.
 correlations, and pending cleanup without coupling to a producer or verify-step
 name. `packages/core/src/cli/pr-attachments.ts` performs optional image hosting through the
 narrow Forge capability, while `packages/core/src/cli/pr-summary.ts` renders the same complete
-text projection for finalize and late designations. The GitHub release transport
+text projection for finalize and late designations. `cli/pr-summary-publication.ts`
+coalesces these at completed phase boundaries with durable attempt, result,
+cooldown, request, and disposition facts. Built-in forges upsert one hidden
+per-build marker; legacy plugins keep the existing bounded `commentOnPr` API.
+Oversized bodies become a compact pinned download of a full `pr-summary`
+store artifact. Local runners publish under their lease; remote guests request
+and yield, and dispatcher settlement fences ended execution and owns the
+publication lease before launching replacement work. Summary failure never
+changes phase outcomes. The GitHub release transport
 lives in `packages/core/src/ports/forge/github-pr-attachments.ts`; terminal-build reclamation
 and retry facts remain dispatcher janitor duty.
 
@@ -751,17 +775,24 @@ selected through the plugin ticket-source registry, the real filesystem and
 local-git adapters, the injected Claude and Codex CLI subprocess contracts,
 and the injected Pi CLI/RPC contract.
 Ticket assets (SPEC §7.1.3) are files attached to a ticket and kept in the
-BuildStore, never in the ticket source. `packages/core/src/store/ticket-assets.ts`
+ticket service for hosted tickets, independently of build storage, and in the
+BuildStore for other sources. `packages/core/src/store/ticket-assets.ts`
 holds the types, the limits, and the one validator every adapter calls;
 `packages/core/src/cli/ticket-assets.ts` holds the filesystem walk, the download
 writer, and the note builder; `ab ticket attach`, `asset get`, and `asset rm`
-live in `packages/core/src/cli/ticket.ts`. The only thing a ticket source sees is
-a note through `comment()`, so no source or plugin protocol changed.
+live in `packages/core/src/cli/ticket.ts`. The optional hosted source asset
+capability reuses RemoteBuildStore transport with the ticket URL and credential.
+Other sources retain the existing store path.
 A claim freezes the ticket's current assets into the build (SPEC §6.3):
 `build.created.assets` (and, when a spec is revised from the ticket,
 `spec.revised.assets`) record the pinned revisions, `state.pinnedAssets` in the
 reducer projects them, `getPinnedTicketAsset` reads them back by pinned revision,
 and `ab context` writes them under `.ab/assets/`.
+For hosted tickets, `store/ticket-asset-snapshots.ts` copies exact revisions
+into chunked immutable repository artifacts in the build store before pinning.
+Reads use explicit manifest/chunk revisions without a ticket connection. Old
+pins retain ticket-row reads; existing service attachments need no migration,
+and attachments in old local stores are not moved.
 
 Both `ab dispatch` and sessionless `ab ticket` load the repository's plugins
 before selecting their TicketSource; dispatch passes that one adapter instance
@@ -876,3 +907,90 @@ because they cannot be manufactured safely against a live account.
 
 Provisioning or scheduling these credentials/resources in CI is deliberately
 out of scope; live runs remain explicit.
+
+## Hosted project registry
+
+`packages/postgres-store/src/projects.ts` owns a narrow project registry port
+beside BuildStore. Schema v10 adds an independent append-only project journal
+and singleton mutation/bootstrap lock and marker, with no build/ticket foreign
+keys. Active entries reduce the latest sequence per origin; timestamps are
+metadata, not ordering. Runtime opens assert schema and never run DDL.
+`ab-hosted-store projects` administers registrations using database authority.
+The service exposes one lazy live reader to the operator server, web gateway,
+MCP and server-rendered repository picker. Initialization failures clear the
+cached promise for retry. The dispatcher opens its own shared pool and queries
+membership each invocation. See [owner workflow](setup.md#connected-projects).
+
+## Delegated execution authority
+
+`store/remote/credentials.ts` owns the credential exchange client independently
+of the BuildStore persistence port. The hosted service's `delegated-authority.ts`
+validates issuance, durable lifecycle bindings and the 60-second terminal grace;
+`machine-auth.ts` authenticates these signed version-2 grants as delegated
+principals. `remote-store-server.ts` enforces resource mutations before deposits,
+including body-selected and addressed-stream resources. Operator routes reject
+these principals. Ticket routes deny build grants and allow harvest grants only the reads and
+runner filing operations they require. Ticket sources and assets are partitioned
+by the authenticated project.
+
+Dispatch prepares harvest claims using `HarvestRunner.run(true)` before issuing
+an execution grant. `harvest.execution.authorized` binds the selected run,
+execution and adopted lease holder; the guest resumes only that prepared run.
+Local completion records `harvest.execution.ended`; hosted completion retains
+its provider release fact. Recovery controls remain trusted dispatcher work.
+Execution launch auth is transient and separate from serialized identity. Runners
+request exact phase grants after session-start facts and before runtime calls.
+Workspace plugin factories receive an exchange callback and a scrubbed environment,
+while local children and sandbox bootstrap/launch replace inherited authority.
+Service requests reread durable state; detached executions need neither renewal
+secrets nor their original dispatcher. Local stores retain their existing path.
+Project onboarding uses `cli/connect.ts`, user-level `cli/project-credentials.ts`,
+the shared `connection.ts` wire types, and Postgres `connections.ts`. Approval
+commits registry membership, a credential digest, and the outcome atomically.
+The web connection routes authenticate the existing Better Auth session and
+reuse the sign-in/consent layout; CLI polling uses a separate private capability.
+
+## Revision-checked ticket writes
+
+Every ticket read includes an opaque `revision`. Pass it as `expectedRevision`
+(on MCP/operator requests) or `--expected-revision <opaque>` on `ab ticket update`,
+`move`, `block` and `unblock`. A stale write fails without changing anything and
+reports the current revision. Omission preserves unguarded behavior. Blocker
+checks cover the entire batch. Dispatcher moves remain unguarded and change the
+revision. Sources without guarded writes, including Linear, refuse supplied
+revisions rather than ignoring them.
+
+`ab ticket edit <id>` opens `$VISUAL`, falling back to `$EDITOR`, using TOML
+frontmatter and a Markdown body. Only title, body and labels are editable;
+id, blockers, creation key and reference comments are read-only. It saves only
+changed fields with the opening revision. Unchanged or formatting-only edits
+write nothing. On conflict, invalid input or editor failure, the error names an
+absolute file path containing the edited text. Read the current ticket and
+reapply the intended changes before retrying; conflicts are never merged.
+
+File and Linear revisions fingerprint title, body, canonical label/blocker sets
+and state; reverting identical content restores its fingerprint. File checks
+re-read immediately before writing, with the existing no-lock race window.
+Direct file edits and state-directory moves change revisions. File comments
+change the body and revision; separate hosted comments do not. Hosted revisions
+are monotonic decimal bigint strings, and checks run under the same row lock
+and transaction as all requested changes. Hosted reads return a coherent
+snapshot of fields, blockers and revision.
+
+### Independent hosted ticket service
+
+`[tickets] url` selects hosted ticket transport independently of BuildStore selection;
+without it, tickets use the selected remote build store. Local builds require an
+explicit ticket URL. Project registration and ticket policy publication through
+`ab connect --tickets URL` work before dispatch. Policy is a durable per-registration
+record, outside BuildStore events/artifacts; legacy uploaded configuration remains
+a compatibility fallback. Hosted lifecycle defaults are triage/ready/doing/done.
+Independent harvest uses revocable, expiring, service-bound ticket grants with
+read/create runner authority and read-only child authority. Build state and harvest
+journals remain exclusively in the selected BuildStore.
+
+Hosted ticket detail reads expose complete, oldest-first structured comments in
+`ticket.comments`, preserving exact bodies. Scans do not fetch comments. Hosted
+HTTP clients opt in with `x-autobuild-ticket-comments: 1` so historical strict
+decoders retain compatible responses. File comments remain embedded in the body;
+Linear comment reads are unchanged.

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
@@ -190,6 +202,10 @@ dashboard notice row or on plain-mode stderr, and suppresses repeats while the
 same failure remains. Restoring `autobuild.toml` with valid configuration clears
 the rejection and ordinary live reload resumes without a dispatcher restart.
 
+Dispatcher merge readiness, startup resume, and execution recovery use the same pinned
+commands, verify, and finalize configuration as the build runner. Missing pins retain
+the legacy live-configuration fallback.
+
 These fields hot-reload:
 
 | Field or table | Boundary where a new value applies |
@@ -198,8 +214,8 @@ These fields hot-reload:
 | `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. |
-| `[verify]` and `[finalize]` | Next engine step selection for a build whose OWN branch carries it. An approved plan's stored verify selection remains authoritative, and a base-branch reload does not retarget an in-flight build. |
+| `[commands]` | Next setup, verify check, or finalize check selected for a build whose OWN branch carries it. Dispatcher readiness, resume, and recovery use the same pin. A base-branch reload does not retarget an in-flight build. |
+| `[verify]` and `[finalize]` | Next engine step selection for a build whose OWN branch carries it. Dispatcher readiness, resume, and recovery use the same pin. An approved plan's stored verify selection remains authoritative, and a base-branch reload does not retarget an in-flight build. |
 | `[workspace]` provider and config (including `provisioning`) | Next launch of a build whose OWN branch carries it. A base-branch reload never re-provisions an in-flight build. |
 | `[roles]` | Next agent invocation for that role. Runtime, model, args, alternates, and the session budget are captured together and delivered live. |
 | `[policy]` | Next policy, convergence, or agent-session boundary, delivered live. A running session keeps its captured budget. |
@@ -212,6 +228,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 +374,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 +648,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 +774,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 +815,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 +1172,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 +1180,30 @@ 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.
+
+The dispatcher also applies a fixed, non-configurable limit of three consecutive
+executions that complete normally with exit code zero and no durable build
+progress. Execution start/end, runner attachment and workspace lifecycle
+bookkeeping do not count as progress. Pipeline, session, spec, publication/PR,
+observation and acknowledged operator facts reset the streak; infrastructure,
+budget and provider failures do not consume the allowance and retain their own
+retry limits. Before a fourth actionable launch, the dispatcher raises one
+setup-targeted `execution-no-progress` policy escalation naming the count and
+the next action it expected the runner to take. Waiting, paused and terminal
+builds are left parked, and pending operator commands remain executable.
+Answering that escalation with guidance or a bare `ab answer <slug>` retry grants
+three fresh executions. The guard is derived from durable facts, including on
+supervisor restart, and uses the ordinary watch, dashboard and operator API
+attention paths.
+
 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
@@ -1178,20 +1243,25 @@ invariants, not additional configuration fields.
 
 ## `[tickets]`
 
+To move an existing project between sources, follow the
+[ticket migration procedure](ticket-migration.md).
+
 Required in practice: `readyState` deliberately has no default, so omitting the
 table fails at `tickets.readyState` rather than allowing tickets from every
-state. Within a present table, `source` and `readyState` are required.
+state. Within a present table, `source` is required; hosted tickets default `readyState` to `ready`. Other sources require it.
 
 | Field | Default | Constraints | Purpose |
 |---|---:|---|---|
 | `source` | — | required nonblank builtin or plugin registration name | Select the ticket adapter after configured plugins load. |
 | `readyLabels` | source-aware | optional array of nonempty strings; `[]` allowed | Require every listed label in addition to the state gate. |
-| `readyState` | — | required nonblank string | The one workflow state eligible for dispatch. |
+| `url` | selected build service | HTTPS service URL; HTTP allowed on loopback; no credentials, query or fragment; hosted only | Ticket service independent of [store] url and AB_STORE. Required with local builds. |
+| `readyState` | hosted: `"ready"` | nonblank string; required for other sources | 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` | hosted: `"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: `"Backlog"`; hosted: `"triage"`; 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. |
 
@@ -1210,7 +1280,7 @@ When `readyLabels` is absent, direct Linear uses `["autobuild"]`; hosted, file,
 and plugin sources use `[]`, meaning no host-imposed label gate. An explicit value always
 wins. A nonempty list is
 conjunctive: every configured label must be present. `readyState` remains
-mandatory regardless of labels. Linear compares state and label names exactly
+mandatory regardless of labels (hosted defaults to `ready`). Linear compares state and label names exactly
 and case-sensitively. The file source matches state names case-insensitively against the directories
 under the tracker root: the four lifecycle directories (`triage/`, `ready/`,
 `doing/`, `done/`, always present) plus any directory the repository adds, such
@@ -1232,6 +1302,15 @@ Source-specific validation is strict:
 - Plugin sources receive the existing fields in this table unchanged and own
   any additional semantic validation. No untyped plugin-options table exists.
 
+Hosted states are durable service data scoped to a project. `ab ticket states`
+lists configured lifecycle roles first, then custom states alphabetically, with
+counts and optional purposes. `ab ticket state create <name> [--about <text>]`
+adds a state using the file source's lowercase name grammar. Hosted duplicates
+in any letter case are refused; file creation remains idempotent. Configured
+names always exist, preserve their spelling, and remain custom states after
+removal from config. Any existing state supports ticket create, move, and list;
+unknown names report the available states. Purposes must be one nonblank line.
+
 For Linear, omitting `createState` lets the team's default state apply. For the
 file source it defaults to `Triage`. A caller may override that default for one
 create with `ab ticket create --state <state>`; the value is passed unchanged to
@@ -1303,17 +1382,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 +1574,7 @@ sessionBudgetSeconds = 7200
 sessionBudgetSeconds = 3600
 stallRounds = 3
 maxVerifyAttempts = 3
+maxDispatchAttempts = 3
 maxSetupAttempts = 3
 maxInfrastructureAttempts = 3
 maxReconcileAttempts = 3
@@ -1653,9 +1734,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. Hosted tickets use this only when `[tickets] url` is absent; local builds with hosted tickets require `[tickets] 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 +1876,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).