@defrex/autobuild 0.12.0 → 0.13.0

package/README.md

@@ -24,7 +24,7 @@ needs an authenticated [`gh` CLI](https://cli.github.com) or an exported
 <!-- release-install:start -->
 
 ```sh
-bun add -g @defrex/autobuild@0.12.0
+bun add -g @defrex/autobuild@0.13.0
 ```
 
 <!-- release-install:end -->

package/SPEC.md

@@ -432,6 +432,13 @@ body file leaves the pinned assets unchanged. The one case this cannot cover is
 a record an older dispatcher created with an empty stream: recovery can only
 sample the ticket's current assets for it.
 
+For hosted tickets, exact sampled revisions are copied into immutable repository
+artifacts in the destination build store before pins are published. Pins carry
+explicit manifest references; bounded binary chunks preserve files and empty
+directories without contacting the ticket service during build reads. Original
+ticket revision numbers are preserved. Old pins without snapshot references
+continue reading their existing ticket rows.
+
 ## 7. The build store
 
 The v1 repo-bloat and no-observability problems share one root cause: the
@@ -618,15 +625,23 @@ resume or turn — no second turn, no concurrent turns, no subagents.
 
 A **ticket asset** is a named, versioned bundle of files attached to a ticket —
 a design export, a reference screenshot, a sample payload — that shapes a change
-but belongs neither in the repository (where it goes stale once the change
-ships) nor in the ticket tool (which build agents cannot reach). It is keyed by
+but belongs outside the repository, where it would go stale once the change ships. It is keyed by
 `(repo, ticketId, kind, name)` and works identically whichever ticket source is
 configured. It is a fourth resource family beside builds, repository journals,
 and sessions, but a deliberately thin one: no event log, because nothing here
 needs reduction, and no retention pruning, because assets live as long as the
 ticket's other durable data and never expire on their own.
 
-Each put creates a new 0-based **revision**; earlier revisions stay retrievable.
+Hosted ticket assets live in the ticket service's repository-keyed storage,
+regardless of where builds run or which BuildStore is selected. File tickets use
+native portable storage composed with legacy BuildStore attachments; Linear
+tickets retain BuildStore storage. Existing service assets need no migration;
+old local hosted-ticket attachments are not moved or used as a fallback.
+
+Each put creates a new increasing **revision**; earlier revisions stay retrievable.
+Adapters normally start at 0. Native file assets reserve revisions from
+1,000,000,000 upward so explicit reads of old BuildStore revisions remain
+unambiguous when native and legacy assets are composed.
 An asset is a `file` (exactly one file) or a `tree` (a folder: its root is
 implicit, so a tree with zero entries is a valid empty folder). The manifest is
 a list of entries — `file` entries with size and content address, and `dir`
@@ -1071,9 +1086,9 @@ kind and operation.
 
 Ticket admission uses the credential project. Hosted tickets, comments, blockers, creation-key
 deduplication and assets are partitioned by registered repository, never team.
-Lifecycle comes from that project's latest durable effective configuration
-(triage Backlog, claim Doing, completion Done by default; configurable
-`doneState`). Owner admin ticket requests explicitly select a registered
+Lifecycle comes from independent project ticket policy (triage, ready, doing, done
+by default; configurable doneState). Legacy projects without independent policy
+use their uploaded configuration with Backlog / Doing / Done defaults. Owner admin ticket requests explicitly select a registered
 repository. The service has no Linear ticket backend: external tracker and
 file sources remain dispatcher-side, and service ticket surfaces refuse those
 projects with actionable source feedback. Legacy team queues migrate atomically
@@ -1273,9 +1288,10 @@ implementer:  ab context   (findings.json now materialized) → …
 
 Human/pre-build ticket grooming uses one configured-source namespace
 (`ab ticket create|update|block|unblock|list|show|move`, plus the ticket-asset
-forms below). These commands are
+forms below). Migration adds `ab ticket export <dir>` and `ab ticket import <dir>`
+(see [Ticket source migration](#ticket-source-migration)). These commands are
 sessionless, source-agnostic, and never available as a mid-build spec
-mutation path. Every subcommand accepts `--json` and then writes exactly one
+mutation path. The CRUD subcommands accept `--json` and then writes exactly one
 bare value: `list` emits `Ticket[]`; every other form emits the complete
 created, read, or post-mutation `Ticket`. Human-readable confirmations are not
 a data format and callers must not parse ids from them.
@@ -1290,8 +1306,10 @@ creates tickets directly in its ready state must therefore create a dependency
 chain in dependency order, carrying each predecessor id into the next create,
 before a later ticket can be claimed.
 
-**Ticket assets** (§7.1) attach files to a ticket without touching the ticket
-source's storage:
+**Ticket assets** (§7.1) attach files to a ticket. Hosted tickets use their
+ticket service storage independently of the selected build store; file tickets use
+native storage with legacy fallback, and sources without native assets use the
+selected BuildStore:
 
 - `ab ticket attach <id> <kind> <path> [--name <name>] [--store <ref>] [--json]`
   stores a file or a whole folder (its relative tree preserved) as an asset.
@@ -1762,9 +1780,10 @@ event-level mechanics live in the repository catalog and reducer tests):
 repository; an owner selects a registered repository explicitly. Team and state
 fields from clients convey no authority or lifecycle policy. Tickets, comments,
 blockers, creation-key deduplication and assets are isolated by repository.
-The project's latest effective configuration supplies hosted lifecycle names:
-triage Backlog, claimed Doing, completion Done (`doneState`) and create/proposal
-equal to triage by default; `readyState` is required. Configured roles may overlap.
+Independent project ticket policy supplies hosted lifecycle names: triage, ready,
+doing, done (`doneState`), and create/proposal equal to triage by default. Hosted
+readyState defaults to ready; other sources require it. Legacy clients without
+independent policy use uploaded dispatcher config and its old defaults. Configured roles may overlap.
 The service has no Linear backend and never relays external ticket sources.
 Projects using Linear, files or plugins keep their direct dispatcher connection;
 service ticket surfaces refuse with project/source feedback instead of empty data.
@@ -1780,14 +1799,16 @@ This keeps the abstraction honest: a file-based TicketSource with nowhere to
 put blobs must be fully workable.
 
 **Ticket assets follow the same rule.** The contents of a ticket asset (§7.1)
-live in the BuildStore and the ticket source never stores them. Attaching,
+live in the ticket service for hosted tickets, independently of build storage;
+file sources keep portable bundles and source-local history, while sources without
+native assets keep them in the BuildStore. Attaching,
 replacing, or removing an asset instead leaves a note on the ticket through the
 existing `comment()` port — the outward projection every source, including the
 plugin surface, already supports. The note names the asset, its revision, file
 count, and size, and gives the `ab ticket asset get` command that fetches it, so
 a person reading the ticket in Linear, the hosted service, or a local file knows
 the asset exists. The note is a projection outward only; nothing reads it back,
-and no TicketSource port or plugin-protocol change is needed.
+and existing sources and plugins need no asset capability.
 
 **Claim lifecycle.** Claim acquires nonterminal work: it returns `true` and
 moves a claimable ticket to the source's claimed state. It returns `false` for
@@ -2230,6 +2251,21 @@ adapter never re-cuts it from a newer base (§7.4). `ab context` rehydrates
 scratch from the store into a fresh session. Uncommitted round-2 work is lost by
 design (§7.3 — phase boundaries are the resume points).
 
+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.
+
 Two liveness rules complete the picture. Within one dispatcher process,
 build-runner launches are single-flighted by slug through supervised process
 liveness — execution completion means the complete environment has been reaped,
@@ -2781,3 +2817,71 @@ or installs releases in the foreground or background.
    enforcement and will colocate later session-authenticated human routes.
    Artifacts remain content-by-value for now; direct-to-blob references are a
    possible later protocol revision, not a second current deployment path.
+
+## 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.
+
+### 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.
+
+### Ticket source migration
+
+`ab ticket export <dir>` enumerates all states through TicketSource and writes a
+portable file tracker atomically to an absent or empty destination.
+`ab ticket import <dir>` preflights the entire tracker and target inventory, then
+creates or adopts tickets, maps blockers, deduplicates comments by exact body and
+restores current attachments. Both run sessionless without forge access.
+
+TicketCreateOptions includes optional `requestedId`. Unsupported sources reject
+it. File keeps safe ids exactly; hosted preserves canonical own-team positive
+numbers and advances its counter above every occupied number. Creation-key
+adoption precedes collision checks. Known kept-number clashes stop import before
+any target mutation. Stable migration identities and atomic mapping files make
+interrupted imports resumable without content-based adoption.
+
+File frontmatter additionally supports optional structured `comments` (body,
+createdAt, optional author) and `attachments` (kind, name, layout, entries with
+file base64 bytes or directory paths). Legacy absent fields retain old behavior;
+new creates use structured comments. Native file assets retain historical
+revisions in hidden source-local metadata and compose with legacy BuildStore
+assets. Build claims and spec re-pins freeze native assets into durable snapshots.
+
+State normalization and the complete operator procedure are documented in
+[Ticket migration](docs/ticket-migration.md). The same reference is delivered in
+the installed guide. Export keeps lifecycle membership without inferring roles;
+import reuses unique case-insensitive states and creates normalized missing ones.

package/docs/architecture.md

@@ -364,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
@@ -771,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
@@ -938,3 +949,48 @@ 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

@@ -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.13.0",
+    "@defrex/autobuild": "0.13.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

@@ -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

@@ -485,6 +485,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