@defrex/autobuild 0.11.0 → 0.13.0

package/docs/remote-ticket-protocol.md

@@ -2,22 +2,81 @@
 
 The hosted ticket protocol exposes the complete `TicketSource` port without
 exposing backend credentials. It shares the Autobuild and remote protocol
-version headers with the remote BuildStore. Both must exactly match the service;
-this release uses remote protocol version `3`.
+version headers with the remote BuildStore. The version must be in the
+published service window and the protocol must
+match its known release-line identity (`3` for 0.9, 0.10, and 0.11).
+
+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.
 
 ## Authentication and context
 
-Every request is `POST /tickets/<operation>`, has `Content-Type:
-application/json`, and requires `Authorization: Bearer <token>`. Only a signed,
-unexpired **deployment operator** token (`{ "operator": true, … }`) is accepted.
-Attributed human-operator, legacy admin, build, repository, and session tokens
-remain valid for their own routes but are denied on `/tickets`. Mint a deployment
-operator token offline with:
+Every request is `POST /tickets/<operation>`, has `Content-Type: application/json`,
+and requires `Authorization: Bearer <project credential>`. Authentication and
+registration checks precede body parsing and source construction. Owner admin
+is the explicit cross-project exception; internal operator signatures have no
+ticket authority.
+
+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='…' ab-hosted-store mint operator --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
 ```
 
+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.
+
+Hosted tickets, comments, blockers, creation-key deduplication and assets belong
+to exactly one registered project, even when projects use the same team key.
+Project credentials select that repository. An optional `context.repo` selector
+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
@@ -31,12 +90,51 @@ The strict request envelope is:
 }
 ```
 
-`teamKey` is required. The state overrides are optional. They come from the
-requesting repository's `[tickets]` configuration and are applied only to that
-request; the service does not cache a team-bound adapter. `list-ready` also
-receives that repository's exact ready state and label criteria in `input`.
-Backend credentials, including `LINEAR_API_KEY`, are service environment only
-and never occur in this envelope or any response.
+`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 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.
+
+`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
+MCP ticket surfaces refuse with a message naming that project and source: its
+tickets live in its own source, accessed directly by its dispatcher. This is a
+409 conflict, not an empty queue. The dispatcher's direct adapters are unchanged.
+
+`AB_TICKET_BACKEND` and `LINEAR_API_KEY` are removed service settings. Their
+presence (even blank or unknown values) is ignored and emits one startup removal
+message. `AB_TICKET_TRIAGE_STATE`, `AB_TICKET_READY_STATE`,
+`AB_TICKET_DOING_STATE` and `AB_TICKET_DONE_STATE` are removed and ignored,
+including malformed values. These retired settings do not prevent startup.
 
 ## Operations
 
@@ -44,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}` |
@@ -65,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" |
@@ -74,11 +203,112 @@ environment values, or credentials. Client 401/403 responses become
 `AuthError`; other backend messages remain actionable.
 
 The shared `TicketSource` contract is normative for the database adapter and
-the hosted client/server pair. External pass-through is tested with a fake
-source behind HTTP. The existing opt-in live Linear contract remains the proof
-of Linear's GraphQL behavior; the hosted service uses that adapter unchanged.
+the hosted client/server pair. PostgreSQL migration and isolation tests prove
+project partitions. The direct Linear client retains its separate opt-in
+GraphQL contract; no Linear adapter ships through the hosted ticket entry point.
 
 Every ticket returned by list, get, or create requires a boolean `resolved`,
 with the same source-native completion semantics as `DependencyState.resolved`.
 The client preserves it when remapping ticket references. Missing or non-boolean
-values fail wire validation. Client and service still require exact version matches.
+values fail wire validation. Client and service follow the published compatibility window.
+
+Legacy 0.9.x and 0.10.x ticket responses omit `resolved` and `blockersResolved`
+because those clients use strict decoders without these fields. This projection
+applies to list-ready, get, and create responses. Current clients retain the
+current required resolution fields; domain and storage types are unchanged.
+
+## Delegated execution credentials
+
+Build and harvest runners exchange project authority for signed, project-bound
+execution and phase credentials through `/credentials/delegate` (see the remote
+store protocol). Build-runner and build-phase credentials cannot call any ticket
+operation. Harvest-phase credentials permit only list-ready, get and
+dependency-states. Harvest-runner credentials permit those reads plus create
+for filing proposals. Claim, comment, transition, update, add-blocker and
+remove-blocker require project or admin authority; their access is unchanged.
+Denied delegated calls return 403 with an error naming the grant kind and
+operation before body parsing or source construction. Lifecycle retirement and
+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

@@ -28,7 +28,7 @@ maintainer before selecting it:
 - a dispatcher-side push-capable `GITHUB_TOKEN` or `GH_TOKEN`;
 - for a private repository, a separate read-only clone identity named by
   `gitUsernameEnv` and `gitPasswordEnv`;
-- an HTTPS hosted `AB_STORE` reachable from Vercel and a scoped `AB_TOKEN`;
+- an HTTPS hosted service reachable from Vercel, configured through `ab connect <url>`;
 - each selected role and alternate's runtime/model, its pinned
   `[workspace.config.runtimeProvisioning.<runtime>]` commands, and the API
   credential names it needs in `[workspace.config].environmentVariables`.
@@ -177,7 +177,7 @@ ab dispatch --repository https://github.com/owner/repository \\
 ```
 
 `--repository` (or `AB_REPOSITORY`) is the normalized origin. Origin mode
-requires an HTTPS `AB_STORE` plus `AB_TOKEN`, an exported `GITHUB_TOKEN` or
+requires an HTTPS service selected through `[store] url` or `AB_STORE`, a saved project credential or `AB_TOKEN`, an exported `GITHUB_TOKEN` or
 `GH_TOKEN`, and `forge = "github"`; the interactive dashboard is unavailable
 (`--plain` or no TTY). Origin mode never consults the gh CLI: a checkout-less
 host has no gh and no keyring, and the only workspace provider it can run,
@@ -208,17 +208,34 @@ sources agree with the running system by construction:
   **running dispatcher's version** (read from the deployed distribution's
   `package.json`), so the guest runs the dispatcher's own release.
 
-The hosted remote store enforces exact **version lockstep**: every client
-request must carry an `x-autobuild-version` equal to the server's, and any
-mismatch — a guest older *or* newer than the store — is rejected with a 409
-`remote store version mismatch`. Guest, store, and dispatcher versions
-therefore cannot be mixed: a distribution fix reaches guests only after
-`tools/release.ts` cuts a release (credential-gated; requires GitHub
-credentials — a documented delivery dependency, not an automatic propagation)
-**and** the hosted store and dispatcher are upgraded to that release in the
-same lockstep window. If the release is cut but the store upgrade lags, guests
-carrying the new distribution fail loudly against the old store (409) rather
-than running silently stale.
+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.
+
+`ab upgrade` probes this public range before installation or project changes.
+It warns and continues when the target is outside the range, naming the
+required service upgrade for a newer target or a compatible project range for
+an older one. An unavailable or malformed probe warns that connectivity may
+fail after upgrade. Legacy health without a range means exact-version matching;
+upgrade that service to the compatibility-window release first.
+
+A distribution fix reaches origin-mode guests after a release is cut and the
+dispatcher is upgraded. Guests continue to run the dispatcher's own version;
+the hosted service must support that release line.
 
 Provisioning records the installed distribution's identity — package version
 and remote-store protocol version — in the guest's
@@ -229,10 +246,10 @@ against the identity the current system would deliver and, when they disagree
 (which includes every guest provisioned before the marker existed), refreshes
 it in place (archive re-fetched, extracted, and production-installed) first,
 so an upgraded dispatcher retrofits its existing guests instead of resuming a
-stale distribution the hosted store would reject. A refresh failure deletes
+stale distribution. A refresh failure deletes
 the sandbox so the next provisioning pass rematerializes it from scratch.
 
-After a lockstep upgrade, confirm a fix-bearing guest from the guest
+After a dispatcher upgrade, confirm a fix-bearing guest from the guest
 perspective:
 
 1. `ab build status <slug> --json` with the ambient build identity for a
@@ -250,7 +267,7 @@ apart from the identity change, `ab dispatch` behaves as it did.
 A hosted-store deployment configures its web/auth variables once — see the
 hosted service README and the complete environment reference in the pinned
 distribution checkout: `BETTER_AUTH_URL`, `AB_WEB_ALLOWED_EMAILS`,
-`AB_WEB_REPOSITORIES`, and the optional `AB_WEB_MCP_RESOURCE` — the protected
+and the optional `AB_WEB_MCP_RESOURCE` — the protected
 resource the hosted MCP server (docs/mcp.md) binds its OAuth tokens to,
 defaulting to `<BETTER_AUTH_URL>/mcp`. Set it only when a proxy or custom
 domain fronts the deployment under a different public URL than
@@ -258,6 +275,93 @@ domain fronts the deployment under a different public URL than
 production) or every MCP client's discovery binds tokens to the wrong
 resource.
 
+
+## 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.
+
+## Connected projects
+
+Migrate PostgreSQL from the pinned release before deploying (`bun run
+postgres:migrate`). The service keeps an independent, durable project registry;
+existing build or ticket data does not register a project. An administrator
+with deployment database credentials manages it without redeploying:
+
+```sh
+ab-hosted-store projects list
+ab-hosted-store projects add https://github.com/owner/project --user owner@example.com
+ab-hosted-store projects remove https://github.com/owner/project --user owner@example.com
+```
+
+From a source checkout, substitute `bun packages/hosted-store-service/src/bin.ts`
+for `ab-hosted-store`. Configure `AB_POSTGRES_URL` or `DATABASE_URL` in that
+process. Database possession grants administration; `--user` is declared audit
+attribution, not a verified login. Ordinary project/store tokens cannot manage
+registrations. Each entry records the normalized origin URL, addition time,
+and adding identity. SSH git spellings normalize to HTTPS; local paths and
+credential-bearing HTTPS URLs are rejected. Duplicate adds preserve metadata;
+remove is idempotent, and re-adding records a fresh addition.
+
+Every allowlisted signed-in user owns every registered project. The dashboard,
+MCP discovery and calls, and every operator API route consult current
+registration. Removal hides a project from all these surfaces and subsequent
+hosted dispatcher invocations; builds, events, artifacts and tickets remain,
+and re-registration restores access. Already-started work is not cancelled.
+Project credentials issued by connect authorize only their registered project. Administrative credential issuance remains available for non-interactive hosts.
+
+Link directly to `/?repo=<URL-encoded normalized origin>`. The page selects the
+first registered origin when the requested one is missing or removed, and an
+empty registry shows no project data or controls. Registry errors fail closed;
+there is no environment fallback on database failure.
+
+`AB_WEB_REPOSITORIES` is deprecated. A nonempty CSV is imported exactly once per
+database, on the first registry initialization with that variable configured,
+with actor `system:AB_WEB_REPOSITORIES`. The import and durable marker commit
+atomically across concurrent starts. An absent variable does not consume the
+marker. Later restarts or edits to the variable never re-add removed projects;
+use the owner commands for subsequent administration.
+
+The hosted dispatcher queries current registrations on every authorized
+invocation. With `AB_DISPATCHER_REPOSITORIES` unset, it serves all registered
+projects; an explicit list preserves its order and is intersected with current
+registration. An empty registry is a successful zero-project invocation.
+
 ## Authoring an agent verifier
 
 A repository-owned agent-verify skill is a verifier, not a reviewer: it drives
@@ -290,3 +394,82 @@ explanation, never a skip or silent pass. Use `skip` only when the complete step
 does not apply. If guidance still cannot make a verdict possible, escalate and
 explain what remains unresolved. Record out-of-scope work with `ab observe`;
 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. 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;
+service ticket HTTP, operator and MCP surfaces refuse with project/source
+feedback rather than returning an empty queue. Removed `AB_TICKET_BACKEND` and
+`LINEAR_API_KEY` values are ignored with one startup removal message, including
+blank/unknown values. Removed `AB_TICKET_TRIAGE_STATE`, `AB_TICKET_READY_STATE`,
+`AB_TICKET_DOING_STATE` and `AB_TICKET_DONE_STATE` values are ignored even when
+malformed. None of these retired settings prevents startup.
+
+The environment-aware migration imports `AB_WEB_REPOSITORIES` once before
+ownership preflight, including released main-v9 deployments without registry
+tables. A failed migration rolls back the import, main-schema promotion and
+ticket changes together. Owner `projects add` and `tickets assign-team` commands
+bootstrap only the registry/recovery journals and work while the main marker
+is still v9. Without the retired environment, first register the intended
+project with `ab-hosted-store projects add REPOSITORY --user IDENTITY`, then
+assign the team and rerun migration. A successful one-time import is never
+reapplied from later environment edits.
+
+Ticket schema v1 migration assigns each whole legacy team to its sole claimant
+among registered projects' latest effective configs, reading their actual blob
+bytes. Projects with no dispatcher run or no effective-config reference make
+no team claim and do not block other projects. Unclaimed teams still fail closed.
+When inferring ownership, a selected configuration whose revision/blob is missing,
+unreadable or invalid stops unchanged with recovery guidance. Restore the selected
+configuration or assign every remaining legacy team explicitly; complete owner
+assignments to registered projects bypass unrelated configuration reads. Conflicts
+and asset ownership mismatches also stop unchanged. Resolve ownership, then rerun:
+
+```sh
+ab-hosted-store tickets assign-team TEAM https://github.com/acme/app --user owner@example.com
+ab-postgres-store migrate
+```
+
+The assignment journal works before v2 assertion, retains the actor, and grants
+no future cross-project access. Migration preserves ids, states, comments,
+blockers, timestamps and assets. Populated-v1 migration and deployment builds
+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.

package/docs/ticket-dependencies.md

@@ -2,7 +2,7 @@
 
 `ab ticket create --blocked-by` validates prerequisite ids and records blocking
 relationships, but a single CLI command is **not an atomic publication guarantee**.
-In particular, direct Linear and hosted Linear create the issue first and add
+In particular, direct Linear creates the issue first and adds
 its blocker relationships in separate requests. If the issue is already in the
 ready state, a dispatcher can see it before those relationships exist. A
 successful create response containing every blocker does not prove that no build

package/docs/ticket-migration.md

@@ -0,0 +1,64 @@
+# Moving a project between ticket sources
+
+Export and import use the ordinary file ticket layout. They operate on tickets
+and current attachments through the ticket source; neither command contacts the
+forge. File and hosted sources support import. Linear supports export only.
+
+1. Pause intake and stop other ticket writers for the cutover. Import preflight
+   does not reserve numbers against concurrent writers.
+2. With the old `[tickets]` configuration, run `ab ticket export /path/to/export`.
+   The destination must be absent or empty. Export reads every state, including
+   archived Linear tickets and empty discoverable states, and publishes the
+   directory only after all reads succeed. Back up the target tracker too.
+3. Configure the new `[tickets]` source, or use `ab connect --tickets URL` for a
+   hosted ticket service. Keep the export directory intact.
+4. Run `ab ticket import /path/to/export`. Inspect its printed ticket and state
+   mappings and `/path/to/export/.ab-import-map.json`.
+5. Inspect ticket bodies, labels, blockers, comments and attachments in the new
+   source. Confirm lifecycle configuration and the ready gate, then resume intake.
+
+Both commands also accept
+`--store <ref>` to reach legacy BuildStore attachments. Keep the old store available
+through export when file or Linear tickets have attachments there.
+
+State directory names use lowercase letters, digits and hyphens, start with a
+letter and contain at most forty characters. Export maps `In Progress` to
+`in-progress`, `Backlog` to `backlog`, and `Done` to `done`. It retains each ticket's
+state rather than assigning lifecycle roles. Distinct names that collapse to the
+same directory fail before publication. The hidden `.ab-migration.json` records
+original display names and the state map. Import also accepts ordinary legacy
+file layouts: it reuses exact or unique case-insensitive target states before
+normalizing new names. A seeded `done` satisfies `Done`; absent `In Progress`
+creates `in-progress`. Ambiguous matches and colliding state maps fail preflight.
+
+File targets retain source ids. Hosted targets keep canonical own-team ids:
+`AUT-706` imported into team `AUT` stays `AUT-706`. Other ids receive numbers above
+all existing and preserved incoming numbers. Known clashes with unrelated tickets
+are reported together before any target state, ticket, comment or asset write.
+Content similarity and stale mapping files never establish identity.
+
+Creation keys establish identity. Exports retain existing keys and assign keys to
+legacy tickets. Importing an ordinary file layout first saves a hidden migration
+identity and keys in that input directory. Preserve this file and the input across
+retries. After interruption, rerun the same command: committed creates are adopted
+by key even if their mapping write failed. Adopted bodies and other fields are not
+overwritten. Missing blockers and comments are replayed, and unchanged attachments
+do not create another revision. Comments are deduplicated by exact body, so two
+identical source comment bodies produce one target comment. Original authors and
+timestamps remain in the export; imported comments use the target's metadata.
+
+Portable records use TOML frontmatter between `+++` fences and an unchanged
+Markdown body. Alongside `id`, `title`, `labels`, `blockedBy` and `idempotencyKey`,
+optional `comments` contain `body`, `createdAt` and optional `author`. Optional
+`attachments` contain `kind`, `name`, `layout` (`file` or `tree`) and `entries`:
+`{ type = "dir", path = "empty" }` or
+`{ type = "file", path = "image.png", base64 = "…" }`. Common asset limits and
+path validators apply. Only current attachment contents travel, including binary
+files and empty directories; historical revisions do not. The exported directory
+works directly as a file source, without its migration manifest or original store.
+File source revision history stays in its hidden `.ab-assets` directory.
+
+Legacy records without `comments` retain their Markdown comment append behavior;
+export never interprets Markdown headings as structured history. New file tickets
+use structured comments and preserve their body when a comment is added. There is
+no continuous sync, assignee migration, state history or build-history migration.