@defrex/autobuild 0.12.0 → 0.14.0

package/docs/configuration.md

@@ -202,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 |
@@ -210,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. |
@@ -1185,6 +1189,21 @@ 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
@@ -1224,21 +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; `"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. |
+| `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/hosted: `"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. |
 
@@ -1257,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
@@ -1279,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
@@ -1703,7 +1735,7 @@ 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"`; 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_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

package/docs/hosted-service.md

@@ -17,8 +17,8 @@ package's `deployment/` directory and in `templates/hosted-service/`).
     "build": "ab-hosted-service-build"
   },
   "dependencies": {
-    "@defrex/autobuild-hosted-store-service": "0.12.0",
-    "@defrex/autobuild": "0.12.0",
+    "@defrex/autobuild-hosted-store-service": "0.14.0",
+    "@defrex/autobuild": "0.14.0",
     "next": "16.1.6",
     "react": "19.2.4",
     "react-dom": "19.2.4"
@@ -153,9 +153,9 @@ 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,
+project. Independent ticket policy selects lifecycle; `ab connect --tickets URL`
+publishes it before dispatch. Older clients retain uploaded dispatcher configuration
+as a fallback. See the [ticket protocol](remote-ticket-protocol.md). 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.
@@ -212,3 +212,29 @@ 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.
+
+## Local builds with hosted tickets
+
+Hosted tickets do not require hosted builds. Set `[tickets] source = "hosted"`
+and `teamKey = "ENG"`, then run `ab connect --tickets https://your-service.example`.
+Approve the project in the browser. This saves a service-scoped credential and
+`[tickets] url` while leaving `[store]` unchanged. Ticket commands work immediately,
+before any dispatcher runs. `ab connect` reports every service and whether it serves
+builds, tickets, or both. Use `ab disconnect --tickets` to revoke ticket access;
+when services differ use `--builds` to select build access. Shared uses share one
+credential, so disconnecting either shared use affects both.
+
+Ticket URL selection is `[tickets] url`, then the selected build service (including
+AB_STORE or a supported --store override). With local builds, `[tickets] url` is
+required. Builds, events, artifacts, and harvest journals remain in the local store.
+The service stores ticket records, project ticket policy, and restricted ticket
+grants. Normal project clients synchronize current `[tickets]` policy before use;
+failed synchronization fails the operation. Harvest grants can read and create;
+phase grants can only read. Neither can change policy or access BuildStore routes.
+
+New hosted policy defaults to `triage`, `ready`, `doing`, `done`, with creation and
+harvest proposals in `triage`. Explicit state names preserve their spelling.
+To retain earlier names configure `triageState = "Backlog"`,
+`claimedState = "Doing"`, `doneState = "Done"`, and the desired `readyState`.
+Existing ticket rows are never renamed. Older combined-service clients continue
+using the uploaded dispatcher configuration until independent policy is published.

package/docs/operator-api.md

@@ -1,7 +1,7 @@
 # Operator API v1
 
 The hosted service exposes the polling-oriented operator surface at
-`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **3**.
+`/operator/v1/repos/{repo}`. It is versioned with remote store protocol **4**.
 Every request must send `X-Autobuild-Version`,
 `X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
@@ -87,6 +87,7 @@ turn runner (a later ticket) is the only producer of turn facts.
 | `GET …/harvest/status` | Harvest gate, runs, steps, recovery, and attention projection. |
 | `GET …/builds/{slug}/artifacts/{kind}?rev=N` | Raw bytes (`application/octet-stream`) plus content-disposition and `X-Autobuild-Artifact-*` metadata headers. Omit `rev` for latest. |
 | `GET …/tickets?state=S&label=L` | `{states,tickets,diagnostics,criteria,triageState,readyState}`. The two lifecycle names come from effective repository configuration (including provider fallback). With no `state`, `criteria.state` is `triageState`; repeated `label` parameters narrow that state with AND filters. An explicit `state` selects that exact backend workflow state. |
+| `GET …/tickets/states` | Full state metadata `{name,tickets,about?}[]`, including empty states (`tickets.states` in MCP). |
 | `GET …/tickets/{id}` | `{ticket,blockers,build}`. Blockers include native `exists`/`resolved` status; `build` prefers an active matching repository build, otherwise the most recently updated one. |
 
 For artifact reads, an absent `rev` selects the latest revision. A supplied value
@@ -119,6 +120,7 @@ JSON bodies are strict: unknown fields are rejected.
 | `POST …/settings/auto-merge-default/toggle` | Empty body. |
 | `POST …/bulk-control` | `{"action":"pause"\|"resume"}`. The hold fact, intake fact, then eligible build events are written in that order. |
 | `POST …/harvest/control` | `{"action":"toggle-gate"}` or `{"action":"run","run":"…"}`. A run action is bound to that concrete projected run. |
+| `POST …/tickets/states` | `{name,about?}` → `{state,created}`; requires attributed operator identity (`tickets.state.create` in MCP). Hosted duplicate names are refused case-insensitively. |
 | `POST …/tickets` | `{"title":"…","body":"…","labels"?:[],"state"?:"…","blockedBy"?:[]}`; omitted state preserves the backend default. |
 | `PATCH …/tickets/{id}` | Any nonempty subset of `title`, `body`, and complete-replacement `labels`. Body bytes are not normalized. |
 | `POST …/tickets/{id}/move` | `{"state":"backend state name"}`. |
@@ -284,3 +286,8 @@ 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.
+
+Hosted ticket tools resolve independent project ticket policy before legacy uploaded
+configuration. Queue, detail, state discovery and mutations work before any build
+or dispatcher run; detail reports a null matching build. Ticket policy publication
+never creates synthetic build or repository history.

package/docs/remote-store-protocol.md

@@ -37,7 +37,7 @@ headers, or available backend.
   `[store] url` (in that precedence order, before the local default); the shipped client appends the routes below.
 - Every `/builds`, `/repos`, and `/sessions` request sends
   `X-Autobuild-Version` with the exact client package version and
-  `X-Autobuild-Protocol-Version` with the remote protocol version (`3` in this
+  `X-Autobuild-Protocol-Version` with the remote protocol version (`4` in this
   distribution). Before authentication,
   body parsing, or resource lookup, the server validates the release-line window and known protocol identity.
   Unsupported or missing values receive `409 {"kind":"conflict","error":"…"}`;
@@ -355,6 +355,74 @@ part of this protocol. Retention is enforced server-side inside the store at
 deposit time (bounded pruning of dispatcher run/config artifact revisions),
 not through any endpoint.
 
+### Named reducer values
+
+`POST /builds/{slug}/reducer-values` and
+`POST /repos/{repo}/reducer-values` accept at most 4 KiB of JSON:
+
+```json
+{"reducer":"dispatchStatus","args":{"run":"run-a"}}
+```
+
+The response is `200 {"version":2,"cursor":123,"value":{...}}`. Only the
+finished JSON answer is returned, with no accumulator or raw-log bundle. `cursor`
+is the authoritative prefix included in the answer, not a guarantee to include
+appends concurrent with the request. Every call checks durable progress and
+persisted state; parallel instances may safely advance the same checkpoint.
+Snapshots are disposable caches: deletion, corruption, wrong versions and
+unreadable cache storage cause replay. Log read failures remain errors.
+
+The executable catalog is `kernel/reducer-registry.ts`. All requests reject
+unknown names, excluded reducers, wrong scopes and invalid/extra arguments with
+`400 validation`. A missing resource is `404`, project and delegated authority
+checks are the same as other reads, and unsupported methods remain unavailable.
+The operation is read-only authority even though its HTTP verb is POST and its
+internal cache may advance. It does not accept caller-supplied state. This is an
+additive protocol route: historical snapshot and event handlers and the supported
+client version window are unchanged.
+
+| Scope | Reducers with no arguments |
+| --- | --- |
+| Build | `executionNoProgress`, `summaryRequests`, `build`, `buildDigest`, `currentPrAttachments`, `pendingPrAttachmentReclaims`, `openExecution`, `lastExecutionOutcome`, `infrastructureFailureReset`, `openWorkspace`, `setupStreak`, `openBuildWorkspace`, `currentDeferralObservation`, `dashboardFacts`, `pinnedAssets`, `buildDelegation` |
+| Repository | `harvest`, `dispatchSettings`, `sandboxStates`, `openHarvestExecutions`, `autoMergeDefault`, `effectiveConfig`, `harvestDelegation` |
+
+| Reducer | Scope | Required arguments |
+| --- | --- | --- |
+| `dispatchStatus`, `openTick` | Repository | `run`: nonempty string |
+| `dispatchFailureBudget` | Build | `infrastructureOwnsWorkspace`: boolean |
+| `phaseFailures` | Build | `phase`: valid phase name; `round`: nonnegative integer |
+
+Arguments are canonicalized into the cache identity; variants never reuse one
+another's accumulator. `effectiveConfig` returns an object with optional `run`
+and `reference: {kind, rev}`. Absence is distinct from an unreadable referenced
+artifact. Delegation values contain semantic lifecycle facts indexed by prefixed
+identifiers, not authorization decisions; request time and grace expiry are
+always evaluated against those facts on the service.
+
+Each remaining registered reducer is explicitly excluded:
+
+| Reducers | Reason |
+| --- | --- |
+| `journalView`, `repositoryStateEvents`, `dispatchFrontend` | Raw repository event lists |
+| `session` | Operator-session log scope |
+| `publicationState` | Selector functions in finished value |
+| `logIndex` | Maps and Sets in finished value |
+| `hostedPrAttachments` | Map as finished value |
+| `summaryBoundary`, `ticketSourceHealth`, `frozenPrImageHost`, `publishedBranchHead`, `verifyDiffBase`, `recordedBaseSha`, `baseBranch`, `provisionMarker`, `recoveryCheckpoint` | Existing finished contract can return top-level `undefined`, which is not JSON |
+
+`GET /repos/{repo}/state-events` is **deprecated**. Its response remains unchanged
+for supported clients, including the current dispatcher run's event tail. It is
+the compatibility exception to flat event-row reads; new callers should request
+named values. The current product no longer loads or writes raw-tail snapshots.
+
+The `value.*` snapshot namespace is reserved for the adapter's private value
+checkpoint hooks. Public snapshot GET and PUT requests for this prefix return
+`400 validation`, including requests made with delegated or administrator
+credentials. Adapter snapshot APIs reject the same names. Ordinary snapshot
+names retain their existing behavior. The value cache key format is versioned;
+checkpoints from the former publicly writable format are ignored and rebuilt
+from the log after upgrading.
+
 ### Reducer snapshots
 
 A reducer snapshot is one registered reducer's serialized state as of a log
@@ -485,6 +553,16 @@ does not apply. `{repo}` and `{id}` are percent-encoded path segments. Token
 authorization requires a credential for that registered project, or owner admin.
 The family is additive, so `REMOTE_STORE_PROTOCOL_VERSION` did not change.
 
+Hosted ticket attachments use the ticket service's existing repository-keyed
+asset routes with the ticket connection's URL and credential, independently
+of the build store. Names, revisions, tombstones and service limits are
+unchanged. Existing service attachments need no migration; old local
+attachments are not moved or used as a fallback. A claim or ticket spec re-pin
+copies exact revisions into immutable chunked repository artifacts in the
+destination build store. Build pins reference explicit snapshot manifests;
+build-scoped asset reads need no ticket credentials. Old pins without snapshot
+references keep their existing ticket-row lookup.
+
 A build also reads the assets it froze at its claim through its own build-scoped
 routes, authorized against the build's actual project. The
 server reduces the build's events to find the pinned revision, then returns that
@@ -1126,7 +1204,7 @@ Four shipped behaviors do not add `BuildStore` routes:
   store lifecycle; there is no close endpoint.
 - `GET /health` is outside the `BuildStore` interface. It is always open and
   returns exactly `200 {"ok":true,"autobuildVersion":"<package>",
-  "protocolVersion":"3", "supportedClientRange":{"minVersion":"0.9.0",
+  "protocolVersion":"4", "supportedClientRange":{"minVersion":"0.9.0",
   "maxVersionExclusive":"0.12.0"}}`. It reports HTTP-process availability and identity,
   not a deeper backing-store transaction or migration check.
 
@@ -1203,3 +1281,17 @@ require a project credential and operate only on its own identity; admin and
 internal operator credentials cannot impersonate self-service. All protocol
 responses are no-store/no-referrer. Connection commands are unavailable in
 build/harvest sessions.
+
+### Repository tick telemetry (protocol 4)
+
+`POST /repos/:repo/tick/begin` accepts `{holder}` and returns the actual start
+ timestamp, or null when the unexpired repository lease does not match.
+`POST /repos/:repo/tick/finish` accepts `{holder, completion, events}`. Completion
+is `{outcome:"completed", counters}` or `{outcome:"failed", error}`; events is
+empty for a quiet success or a matching dispatcher start/terminal pair for that
+holder. The validated batch and finished telemetry commit atomically. The reply
+is `{observation, events}` with assigned envelopes, or null on fencing failure.
+These operations never renew the lease. Repository records optionally expose
+`tick: {run, open?: {startedAt}, finished?: {run, startedAt, completedAt, ...completion}}`.
+They retain the previous completion while a new tick is open and after lease
+release. Build and session credentials cannot mutate repository ticks.

package/docs/remote-ticket-protocol.md

@@ -67,6 +67,16 @@ must match the credential's project; mismatches are 403. Owner admin requests
 require this selector and registration is checked before configuration is read.
 Internal operator credentials remain forbidden on machine ticket routes.
 
+Hosted ticket attachments use the ticket service's existing repository-keyed
+asset routes with the ticket connection's URL and credential, independently
+of the build store. Names, revisions, tombstones and service limits are
+unchanged. Existing service attachments need no migration; old local
+attachments are not moved or used as a fallback. A claim or ticket spec re-pin
+copies exact revisions into immutable chunked repository artifacts in the
+destination build store. Build pins reference explicit snapshot manifests;
+build-scoped asset reads need no ticket credentials. Old pins without snapshot
+references keep their existing ticket-row lookup.
+
 The strict request envelope is:
 
 ```json
@@ -82,16 +92,37 @@ The strict request envelope is:
 
 `teamKey` remains required for older client compatibility. It and the optional
 `claimedState` / `createState` fields are ignored as policy inputs. The service
-loads the project's latest effective configuration from its repository journal
-and artifact bytes for every operation. Missing or invalid configuration returns
-an actionable 409; run the project's dispatcher to publish its configuration.
-There is no deployment-wide lifecycle fallback.
+loads the project's durable independent ticket policy. Project authority publishes
+version 1 policy through `POST /tickets/policy`, using the usual context/input
+envelope. The input contains only `version` and `tickets`: source, teamKey,
+readyState, triageState, claimedState, doneState, createState, proposalState and
+optional readyLabels. URL, secrets, and pipeline configuration are rejected.
+Only project or owner authority can publish. This does not append BuildStore
+history. Registration removal invalidates policy and grants from that registration.
+
+For compatibility, projects without independent policy use their latest uploaded
+dispatcher configuration with the old `Backlog`, `Doing`, `Done` defaults.
+New policy defaults are `triage`, `ready`, `doing`, `done`; create/proposal follow
+triage. States are persistent project data, including empty states and optional
+one-line purposes. Configured role names always exist; removed roles remain as
+custom states and keep their tickets. Explicit settings preserve state spelling.
+State lookup prefers an exact match, then a unique case-insensitive match;
+unknown or ambiguous names are refused. Lists order configured triage, ready,
+doing, done first (deduplicated), then other names alphabetically.
+
+`[tickets] url` selects the ticket service independently of the build store;
+otherwise the selected remote build store is used. A local build store requires
+an explicit ticket URL. Credentials are resolved for that selected service.
+`ab connect --tickets URL` registers and publishes policy before any dispatcher run.
 
-Hosted lifecycle defaults are triage `Backlog`, claimed `Doing`, done `Done`,
-and create/proposal equal to triage. `readyState` is required. The allowed states
-are the distinct union of these configured roles, including custom create and
-proposal states; roles may overlap. Historical states remain readable unchanged.
-`tickets.doneState` controls completion and the dispatcher's merged transition.
+`POST /tickets/grants` issues, renews or revokes short-lived, digest-stored ticket
+grants. Project authority issues runner grants scoped to project and execution;
+runners may issue only read-only phase children bound to themselves. Runner grants
+allow read and create; phase grants allow read only. Policy, claim, moves, comments,
+updates, blocker changes, BuildStore, and credential administration are denied.
+AB_TICKET_URL and AB_TICKET_TOKEN carry this authority separately from AB_STORE and
+AB_TOKEN. Revocation, expiry, parent revocation and registration changes invalidate
+grants. Existing combined-service BuildStore delegation remains supported.
 
 The service never contacts Linear or relays external trackers. If the project's
 source is Linear, file or another non-hosted source, machine HTTP, operator and
@@ -111,6 +142,8 @@ The operation names and `input` values are:
 
 | Operation | Input | Successful response |
 |---|---|---|
+| `states` | `{}` | `{name, tickets, about?}[]`, including empty states |
+| `add-state` | `{name, about?: string}` | `{state: {name,tickets,about?}, created: boolean}` |
 | `list-ready` | `{labels?: string[], state?: string}` | `TicketListing` |
 | `get` | `{id}` | `Ticket \| null` |
 | `claim` | `{id}` | `{claimed: boolean}` |
@@ -132,6 +165,35 @@ Ticket body strings are opaque. Clients, JSON handling, the service, and the
 database backend must not trim or normalize bytes, newlines, Unicode, blank
 lines, or trailing whitespace.
 
+## Readable ticket identity
+
+New hosted tickets use `<teamKey>-<n>`, for example `ENG-1`. The effective
+project configuration supplies the literal prefix; the request's `teamKey`
+does not choose it. Numbers start at 1 in each project, increase atomically
+across concurrent creates, and are never reused after deletion. Projects sharing
+a team key have independent counters. Changing `teamKey` affects only future
+ids and continues the same numbering; existing ids retain their captured prefix.
+
+Every ticket operation, CLI command, MCP tool and blocker input accepts readable
+ids in any letter case. Legacy storage ids (such as `ticket-<uuid>`) remain
+aliases, including references in existing builds, harvest records and assets.
+Current ticket and blocker output uses the canonical readable id. The exception
+is `dependency-states`: each result's `id` echoes the requested id for correlation,
+while its `blockedBy` edges are canonical. Raw historical events and artifacts
+remain unchanged. These rules apply only to hosted tickets, not file or Linear ids.
+
+Upgrade the service with its environment-aware migration command before serving
+requests. The transactional migration preserves storage keys and assigns existing
+tickets numbers in `(created_at, id)` order within each project. It first resolves
+legacy team ownership, then reads each populated project's current independent
+ticket policy. Projects without that policy use their selected effective
+configuration through the configured blob backend. Independent-policy projects
+need no uploaded config or blob access. Missing or invalid fallback config,
+missing `teamKey`, or inaccessible required blobs abort the entire migration
+unchanged with a project diagnostic. Restore that config/blob access and rerun;
+an ownership assignment alone cannot supply a readable prefix. Empty projects
+need no config lookup. Re-running a completed migration does not renumber tickets.
+
 ## Errors and conformance
 
 Errors are JSON `{ "error": string, "kind": "validation" | "not-found" |
@@ -170,3 +232,83 @@ project removal are also checked before parsing or source construction.
 
 Ticket admission and assets use the authenticated project, including for
 delegated harvest grants.
+
+Custom state creation uses `/^[a-z][a-z0-9-]{0,39}$/`; an optional purpose must
+be one nonblank line. A duplicate in any letter case is refused without
+changing purpose. `add-state` requires project or owner machine authority;
+ticket grants and harvest delegations can read states but cannot create them.
+Request context cannot supply lifecycle policy or insert another project's
+states. These operations use the existing wire version and strict envelopes.
+
+## 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 revisions also
+cover structured comments and portable attachments. Legacy file comments change
+the body; structured comments preserve it. Separate hosted comments do not change
+ticket revisions. 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.
+
+### Guarded mutation transport
+
+`POST /tickets/mutate-if-revision` accepts the usual authenticated context and
+`input: { id, expectedRevision, mutation }`. Mutation is one of
+`{ kind: "update", patch: { title?, body?, labels? } }`,
+`{ kind: "transition", state }`, or
+`{ kind: "blockers", operation: "block" | "unblock", ids: string[] }`.
+Unknown keys and empty patches are refused. Success returns `{ ok: true }`.
+A revision conflict returns HTTP 409 with `kind: "conflict"`, `error`, `id`,
+`expectedRevision` and `currentRevision`. Delegated credentials retain existing
+permissions: none of the guarded mutation variants grants additional access.
+Ticket responses include `revision` only when the request advertises
+`x-autobuild-ticket-revisions: 1`. The current hosted client sends this header
+on every request and requires revision-bearing responses. Released clients
+through 0.12.x omit the header and retain their strict decoder's original
+response shape on get, list-ready and create. This explicit capability also
+supports new source checkouts that still report version 0.12.0; version alone
+cannot distinguish them from released clients. Unknown capability values do
+not opt in. Clients before 0.11 also omit the existing resolution projections.
+The capability does not change authentication, authorization or the remote
+BuildStore protocol version.
+
+## Requested ids for migration
+
+Create options accept optional `requestedId: string` alongside `state` and
+`idempotencyKey`. Older clients omit it and responses are unchanged. Unsupported
+sources reject supplied ids; Linear is not an import target. File sources keep
+filesystem-safe ids exactly and never overwrite an occupied id.
+
+Hosted sources preserve only literal own-team `<teamKey>-<n>` ids, where `n` is a
+positive canonical decimal within PostgreSQL bigint bounds. For example,
+`AUT-706` in team `AUT` keeps 706; `OTHER-706`, `AUT-01` and `AUT-0` use ordinary
+allocation. Overflow canonical numbers are rejected. A matching creation key is
+adopted before occupancy checks. A kept number belonging to a different ticket
+fails without replacing it. Creation and counter advancement share the existing
+project transaction and counter lock. Later automatic numbers exceed both the
+counter and highest occupied number; importing a lower number never lowers the
+counter. Requested ids require project or owner authority. Ticket grants and
+delegated credentials receive 403 for create options containing `requestedId`,
+before source construction. Their ordinary create grants remain unchanged.
+
+See the [migration procedure](ticket-migration.md) for preflight, state mapping,
+resumption and portable file records.

package/docs/setup.md

@@ -398,13 +398,13 @@ the verifier does not fix it.
 ### Project-scoped hosted tickets
 
 Hosted ticket queues belong to the credential's registered repository, even
-when projects share a team key. The latest uploaded effective `[tickets]`
-configuration owns lifecycle: hosted defaults are Backlog / Doing / Done,
-`readyState` is required, `doneState` customizes completion, and create/proposal
-default to triage. The union of configured roles is allowed; roles may overlap.
-Owner admin requests require an explicit registered `context.repo`; project
-credentials cannot select another project. Missing effective configuration is
-an actionable refusal: run the project's dispatcher to publish it.
+when projects share a team key. Independent project ticket policy owns lifecycle:
+new defaults are triage / ready / doing / done, with create/proposal following
+triage. Explicit names retain their spelling; doneState customizes completion.
+`ab connect --tickets URL` publishes policy before dispatch. Older clients without
+independent policy retain their uploaded dispatcher configuration and legacy defaults.
+Owner admin requests require an explicit registered context.repo; project credentials
+cannot select another project. See [local builds with hosted tickets](#local-builds-with-hosted-tickets).
 
 The service never contacts Linear. Projects with external sources (including
 file and Linear) keep using those sources directly through their dispatcher;
@@ -447,3 +447,29 @@ require the running service's blob backend, access mode, credentials and prefix
 (`AB_BLOB_PREFIX`), not just PostgreSQL access. `deploy:build` inherits this
 environment and migration failure stops Next build. Fresh databases, empty v1
 queues and v2 reruns stay SQL-only and do not initialize blob storage.
+
+## Local builds with hosted tickets
+
+Hosted tickets do not require hosted builds. Set `[tickets] source = "hosted"`
+and `teamKey = "ENG"`, then run `ab connect --tickets https://your-service.example`.
+Approve the project in the browser. This saves a service-scoped credential and
+`[tickets] url` while leaving `[store]` unchanged. Ticket commands work immediately,
+before any dispatcher runs. `ab connect` reports every service and whether it serves
+builds, tickets, or both. Use `ab disconnect --tickets` to revoke ticket access;
+when services differ use `--builds` to select build access. Shared uses share one
+credential, so disconnecting either shared use affects both.
+
+Ticket URL selection is `[tickets] url`, then the selected build service (including
+AB_STORE or a supported --store override). With local builds, `[tickets] url` is
+required. Builds, events, artifacts, and harvest journals remain in the local store.
+The service stores ticket records, project ticket policy, and restricted ticket
+grants. Normal project clients synchronize current `[tickets]` policy before use;
+failed synchronization fails the operation. Harvest grants can read and create;
+phase grants can only read. Neither can change policy or access BuildStore routes.
+
+New hosted policy defaults to `triage`, `ready`, `doing`, `done`, with creation and
+harvest proposals in `triage`. Explicit state names preserve their spelling.
+To retain earlier names configure `triageState = "Backlog"`,
+`claimedState = "Doing"`, `doneState = "Done"`, and the desired `readyState`.
+Existing ticket rows are never renamed. Older combined-service clients continue
+using the uploaded dispatcher configuration until independent policy is published.