@defrex/autobuild 0.11.0 → 0.13.0

package/packages/core/src/store/ticket-assets.ts

@@ -1,13 +1,15 @@
 /**
  * Ticket assets (SPEC §7.1): named, versioned bundles of files attached to a
- * ticket and kept in the BuildStore, keyed by `(repo, ticketId, kind, name)`.
- * The ticket source never stores the contents; it only gets a note through
+ * ticket and kept in its service (hosted) or BuildStore (other sources), keyed by `(repo, ticketId, kind, name)`.
+ * Sources also get a human-readable note through
  * `TicketSource.comment()` (SPEC §13).
  *
  * This module is the shared, adapter-independent half: the types, the limits,
  * and the one validator every adapter calls before any write.
  */
 
+import { readAssetSnapshot, prepareAssetSnapshots } from './ticket-asset-snapshots'
+import type { TicketSource, TicketAssetStore } from '../ports/types'
 import type { AbEvent } from '../events/catalog'
 import type { PinnedAsset } from '../events/payloads'
 import { defineReducer } from '../kernel/incremental'
@@ -56,7 +58,8 @@ export interface TicketAssetMeta {
   ticketId: string
   kind: string
   name: string
-  /** 0-based per `(repo, ticketId, kind, name)`. A removal consumes a number
+  /** Increasing per `(repo, ticketId, kind, name)` (normally from zero; native
+   * file revisions reserve a separate range for legacy compatibility). A removal consumes a number
    * too (a tombstone), so revisions may skip. */
   revision: number
   layout: TicketAssetLayout
@@ -380,7 +383,27 @@ export async function samplePinnedAssets(
   return (await store.listTicketAssets(repo, ticketId)).map(pinnedAssetOf)
 }
 
-export const PINNED_ASSETS_REDUCER_VERSION = 1
+export async function preparePinnedAssets(
+  source: TicketSource,
+  store: BuildStore,
+  repo: string,
+  ticketId: string,
+): Promise<PinnedAsset[]> {
+  if (!source.assets) {
+    if (source.name === 'hosted') throw new Error('hosted ticket source has no asset capability')
+    return samplePinnedAssets(store, repo, ticketId)
+  }
+  const ticket = await source.get(ticketId)
+  return prepareAssetSnapshots(
+    composeTicketAssets(source, store),
+    store,
+    repo,
+    ticketId,
+    ticket?.ref.id ?? ticketId,
+  )
+}
+
+export const PINNED_ASSETS_REDUCER_VERSION = 2
 
 /** The asset sets recorded by every `build.created`/`spec.revised` pin event
  * that carries one, in array order. Each pin event replaces the set, so the
@@ -443,7 +466,7 @@ export function findPinnedRevision(
  * needed, so a finished build still answers. Null when the build never pinned
  * `kind/name` (or the revision). Rejects an unknown build. */
 export async function resolvePinnedAsset(
-  store: Pick<BuildStore, 'getBuild' | 'getEvents' | 'getTicketAsset'>,
+  store: Pick<BuildStore, 'getBuild' | 'getEvents' | 'getTicketAsset' | 'getRepoArtifact'>,
   slug: string,
   kind: string,
   name: string,
@@ -452,7 +475,62 @@ export async function resolvePinnedAsset(
   const record = await store.getBuild(slug)
   if (record === null) throw new Error(`unknown build "${slug}"`)
   if (record.ticket === undefined) return null
-  const revision = findPinnedRevision(await store.getEvents(slug), kind, name, rev)
-  if (revision === undefined) return null
-  return store.getTicketAsset(record.repo, record.ticket.id, kind, name, revision)
+  const events = await store.getEvents(slug)
+  const sets = pinnedAssetsReducer.reduce(events).pins
+  const pin =
+    rev === undefined
+      ? sets.at(-1)?.find((a) => a.kind === kind && a.name === name)
+      : sets.flat().find((a) => a.kind === kind && a.name === name && a.revision === rev)
+  if (!pin) return null
+  if (pin.snapshot) {
+    const created = events.find((event) => event.type === 'build.created')
+    const asset = await readAssetSnapshot(
+      store,
+      record.repo,
+      record.ticket.id,
+      pin,
+      created?.type === 'build.created' ? created.payload.ticket?.id : undefined,
+    )
+    return { ...asset, meta: { ...asset.meta, ticketId: record.ticket.id } }
+  }
+  return store.getTicketAsset(record.repo, record.ticket.id, kind, name, pin.revision)
+}
+
+/** Native writes; merged reads preserve legacy file attachments and recorded revisions. */
+export function composeTicketAssets(
+  source: TicketSource,
+  legacy: TicketAssetStore,
+): TicketAssetStore {
+  const native = source.assets
+  if (!native) return legacy
+  if (!native.hasTicketAssetHistory) return native
+  const owns = (repo: string, id: string, kind: string, name: string) =>
+    native.hasTicketAssetHistory!(repo, id, kind, name)
+  return {
+    ticketAssetLimits: native.ticketAssetLimits.bind(native),
+    putTicketAsset: native.putTicketAsset.bind(native),
+    async getTicketAsset(repo, id, kind, name, rev) {
+      if (rev !== undefined)
+        return (
+          (await native.getTicketAsset(repo, id, kind, name, rev)) ??
+          legacy.getTicketAsset(repo, id, kind, name, rev)
+        )
+      return (await owns(repo, id, kind, name))
+        ? native.getTicketAsset(repo, id, kind, name)
+        : legacy.getTicketAsset(repo, id, kind, name)
+    },
+    async listTicketAssets(repo, id) {
+      const current = await native.listTicketAssets(repo, id)
+      for (const item of await legacy.listTicketAssets(repo, id)) {
+        if (!(await owns(repo, id, item.kind, item.name))) current.push(item)
+      }
+      return current
+    },
+    async removeTicketAsset(repo, id, kind, name) {
+      const previous = await this.getTicketAsset(repo, id, kind, name)
+      if (!previous) return null
+      await native.removeTicketAsset(repo, id, kind, name)
+      return previous?.meta ?? null
+    },
+  }
 }

package/packages/core/src/store/types.ts

@@ -412,7 +412,7 @@ export interface BuildStore {
   listRepoArtifacts(repo: string, kind?: string): Promise<RepositoryArtifactMeta[]>
   // ── Ticket assets (SPEC §7.1 — files attached to a ticket) ─────────────
   // Keyed by (repo, ticketId, kind, name); revisions are 0-based. The store
-  // owns the bytes, the ticket source only ever gets a note (SPEC §13).
+  // owns these bytes; hosted current assets use the ticket service store (SPEC §13).
   /** The effective ceilings this store accepts for `repo` (a remote
    * deployment may advertise lower ones than the defaults). */
   ticketAssetLimits(repo: string): Promise<TicketAssetLimits>

package/packages/core/src/testing/index.ts

@@ -57,3 +57,10 @@ export {
   type E2eHarness,
   type SkillHandlers,
 } from '../integration/harness'
+
+// Harvest lifecycle and CLI seams for delegated-credential integration tests.
+export { HarvestRunner } from '../processes/harvest-runner'
+export { resolveHarvestCliEnv } from '../cli/env'
+export { buildHarvestContext, submitHarvestProposals, submitHarvestVerdict } from '../cli/harvest'
+export { abConnect, abDisconnect } from '../cli/connect'
+export { ProjectCredentials } from '../cli/project-credentials'

package/skills/guide/SKILL.md

@@ -197,7 +197,9 @@ The distinctions that change an administrator's answer:
   agent turn or command already running. Missing, unreadable, malformed, and
   routing-invalid candidates retain that snapshot with deduplicated operator
   notice, and restoring a valid file resumes reload. Scoped phase CLI processes
-  still read the build worktree's branch-owned file.
+  still read the build worktree's branch-owned file. Dispatcher merge readiness,
+  resume, and execution recovery use the runner's pinned commands, verify, and
+  finalize configuration; builds without a pin retain the live fallback.
 - **Workspaces** are provisioned per build and remain the locally reachable
   execution context for that build.
 - **Ticket providers** (`linear`, `file`) sit behind one port; the dispatcher
@@ -215,6 +217,22 @@ The distinctions that change an administrator's answer:
   guidance and later dispatcher ticks retry. Without consent it remains open for
   ordinary `git diff` inspection; it has no review UI or image host.
 
+For moving a project between sources, follow the [ticket migration procedure](references/ticket-migration.md).
+
+## Independent hosted tickets
+
+Hosted tickets support local builds. Configure `[tickets] source = "hosted"`,
+`teamKey`, and `url`, or run `ab connect --tickets URL` to register the project,
+save its credential and publish ticket policy without changing the build store.
+Without `tickets.url`, tickets use the selected remote build service; local builds
+require an explicit ticket URL. No dispatcher is needed for ticket commands.
+Hosted defaults are `triage`, `ready`, `doing`, `done`; create/proposal use triage.
+Other sources still require readyState. Explicit state names retain their spelling.
+Legacy clients without independent policy retain uploaded configuration defaults.
+Harvest ticket grants are service-bound read/create authority; child phases are
+read-only and cannot publish policy. See [setup](references/setup.md) and the
+[ticket protocol](references/remote-ticket-protocol.md).
+
 ## `autobuild.toml` reference
 
 One declarative file at the repo root. **Declarative, not executable** —
@@ -283,6 +301,19 @@ through the strict versioned manifest and environment-only secrets, to the
 unchanged shared contract suite and optional npm publication—read
 [`references/plugin-authoring.md`](references/plugin-authoring.md).
 
+### `[store]`
+
+| Key | Required | Values / purpose |
+|---|---|---|
+| `url` | When `[store]` exists | Absolute HTTPS service base URL; loopback HTTP is allowed for development. No credentials, query or fragment. Trailing slashes are normalized. |
+
+Selection is explicit `--store` > nonblank `AB_STORE` > `[store] url` > the main
+checkout's `.autobuild/`. A configured service without a user credential fails
+with `ab connect` guidance. `AB_TOKEN` overrides the saved service/project
+credential. See [repository setup](references/setup.md#connect-a-project).
+Changing the store requires restarting dispatch.
+
+
 ### `[pr]`
 
 Optional PR-projection settings. Omission leaves artifact attachments text-only.
@@ -408,6 +439,28 @@ manager.
 
 ### `[verify]`
 
+Post-reconcile verification defaults to enabled: `[verify].afterReconcile = true`.
+Set it to `false` to retain pre-reconcile verification and skip all steps after
+reconciliation. An optional boolean `[verify.<step>].afterReconcile` overrides
+the repository setting in either direction; overrides require a configured step.
+For example, set `afterReconcile = false` in `[verify]` and
+`afterReconcile = true` in `[verify.types]` to keep only that step re-running.
+
+The kernel freezes the resolved ordered policy in
+`verify.reconcile-policy-captured` at the next engine action after reconcile
+completion. Live configuration changes apply at that boundary; a cycle already
+started keeps its policy through recovery. Historical cycles already started
+without a captured policy retain the rerun-all behavior. Initial verification
+and verification after subsequent code review always use ordinary applicability.
+Policy exclusion precedes plan selection and paths, including `always = true`.
+Enabled steps still follow plan selection and path rules. Excluded steps record
+`verify.completed` with outcome `skipped`, `skipCause = "post-reconcile-policy"`,
+and a reason naming the setting. Dashboards and PR summaries call this
+"skipped by post-reconcile policy"; it is never a pass. Forge-side required
+checks and branch protections still gate merge. For excluded steps, merged code
+is not re-verified, so breakage that only exists in the combination can land.
+
+
 `steps` orders the verify phases; each entry `"<step>"` becomes a
 `verify:<step>` phase and needs its own `[verify.<step>]` subtable. Those
 subtables are part of this section — their fields are listed here.
@@ -419,6 +472,7 @@ subtables are part of this section — their fields are listed here.
 | `command` | — | **required when `kind = "check"`**, nonempty string | Ref into `[commands]` — the key, not a shell string. Pass/fail is the command's exit status. |
 | `skill` | — | **required when `kind = "agent"`**, nonempty string | Installed skill name to run (e.g. a repository-authored `"verify-app-e2e"`). |
 | `paths` | — | optional nonempty array of positive repository-relative globs | Makes either step kind apply when any changed path matches any selector. Omitted means unconditional. |
+| `afterReconcile` | repository: `true`; step: inherited | boolean | Step override wins over `[verify].afterReconcile`; false skips this step after reconciliation only. |
 | `always` | — | optional boolean | `true` makes the step unconditional and mandatory (a plan cannot deselect it); `false` is equivalent to omission. |
 
 A plan may begin with strict TOML front matter selecting the complete set of
@@ -488,7 +542,7 @@ A selected step's `paths` are evaluated immediately before the step against
 current `HEAD`, relative to the initial branch-cut SHA or the refreshed base
 from the latest completed reconcile. It uses a NUL-delimited, no-rename Git diff, so
 adds/modifications/deletions and both rename sides participate. A reconcile
-starts a fresh cycle and evaluation repeats; upstream-only merged paths are
+starts a fresh cycle and evaluation repeats for policy-enabled steps; upstream-only merged paths are
 excluded while build-owned resolutions remain visible. A miss starts no
 command, agent, or session and records `skipped` with
 `excluded by [verify.<step>].paths: no changed path matched <JSON paths>`.
@@ -688,6 +742,7 @@ nonnegative integer so zero can disable that trigger.
 | `sessionBudgetSeconds` | `3600` | positive integer | Wall-clock bound for each build agent session unless its logical role overrides it. |
 | `stallRounds` | `3` | positive integer | The same finding surviving this many review rounds auto-escalates to a human — the anti-loop guard. |
 | `maxVerifyAttempts` | `3` | positive integer | Caps the `verify → implement → verify` cycle before escalation. |
+| `maxDispatchAttempts` | `3` | positive integer | Caps consecutive dispatch failures before a setup-targeted `dispatch-failure-limit` escalation. |
 | `maxSetupAttempts` | `3` | positive integer | Caps consecutive `[commands].setup` failures before a setup-targeted human escalation. |
 | `maxInfrastructureAttempts` | `3` | positive integer | Caps consecutive remote provider lifecycle failures before a setup-targeted human escalation; a `retry` answer re-arms the budget. |
 | `maxReconcileAttempts` | `3` | positive integer | Caps completed reconciles that leave the PR conflicted against an unchanged authoritative base. Moving-base races do not consume the budget. |
@@ -695,6 +750,26 @@ nonnegative integer so zero can disable that trigger.
 | `harvestThreshold` | `5` | positive integer | Newly unclaimed `observation.recorded` occurrences required to start one repository harvest run. |
 | `harvestMaxDrift` | `3` | nonnegative integer | Other builds merged after the oldest unclaimed observation required to start a run; `0` disables drift. |
 
+Dispatch failures share one budget across stages until runner attachment. At
+exhaustion dispatch parks durably; bare `ab answer <slug>` and text guidance
+both grant a fresh budget, while abort terminates without retrying. Workspace
+failures owned by provider infrastructure recovery use only its existing budget.
+
+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 latest
 completed reconcile with a fresh authoritative base snapshot. An advanced base
 proves the attempt lost a race and permits another reconcile regardless of the
@@ -712,7 +787,7 @@ roundless no-progress answer. An already exhausted no-progress budget raises its
 matching cause separately before another reconcile. Cause-less historical
 raises retain their former round-shaped reset behavior, and roundless
 policy/reconcile raises retain their former no-progress meaning, on replay
-without migration. Post-reconcile verification still runs in full and remains
+without migration. Post-reconcile verification follows the captured policy and remains
 independently bounded by `maxVerifyAttempts`.
 
 `stallRounds` counts *persistence chains*, which reviewers mark and the kernel
@@ -746,12 +821,14 @@ state eligible.
 |---|---|---|---|
 | `source` | — | **required**, nonblank builtin or plugin registration name | Which provider backs all ticket operations. Unknown names report every available builtin and plugin source. |
 | `readyLabels` | — (source-aware) | optional; array of nonempty strings | A ticket must carry **every** listed label to be dispatchable. `[]` = **no label gate**. Absent uses the source default below. |
-| `readyState` | — | **required**, non-blank string | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file matches it case-insensitively to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `url` | selected build service | HTTPS URL (loopback HTTP allowed), no userinfo/query/fragment; hosted only | Ticket service independent of builds; required for local builds. |
+| `readyState` | hosted: `ready` | non-blank string; required for other sources | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file matches it case-insensitively to a state directory (`ready` → `ready/`). There is no any-state mode. |
 | `readyAssignee` | — | optional; `"me"` or an email; `linear` only | Also require the ticket to be assigned to that Linear user (`me` = owner of `LINEAR_API_KEY`); unassigned tickets are never ready. |
-| `teamKey` | — | required by `linear`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`) or an existing plugin configuration field. |
+| `teamKey` | — | required by `linear` and `hosted`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`), the captured prefix for new hosted ticket ids (`ENG-1`), or a plugin configuration field. Hosted numbers are project-local and continue across prefix changes; legacy ids remain aliases and readable inputs are case-insensitive. |
 | `claimedState` | — | optional nonempty string; forbidden by `file`, allowed for plugins | Workflow state `claim()` moves a ticket to when a build starts. |
+| `doneState` | hosted: `"done"` | optional nonblank string | Project completion state and merged-ticket transition; hosted tickets only. |
 | `createState` | — | optional, nonempty string | Default state for new tickets when a create does not name one. Absent = the provider's default (Linear: the team's default, e.g. Backlog; file: Triage). |
-| `triageState` | — | optional, nonempty string | State the dispatcher hands tickets back to for human triage — spec-gate bounces, aborted builds, closed-unmerged PRs. Absent = Linear: Backlog; file/plugin: Triage. Must name a state the tracker actually has — a Linear team only has "Triage" when its triage feature is enabled. |
+| `triageState` | — | optional, nonempty string | State the dispatcher hands tickets back to for human triage — spec-gate bounces, aborted builds, closed-unmerged PRs. Absent = Linear: Backlog; hosted: triage; file/plugin: Triage. Must name a state the tracker actually has — a Linear team only has "Triage" when its triage feature is enabled. |
 | `proposalState` | — | optional, nonempty string | State observation harvest files approved proposals into. Absent = the resolved `triageState`, which keeps the human grooming gate. Setting it to `readyState` waives that gate: harvested proposals dispatch without being read. Keep it distinct from `triageState` — see below. |
 | `dir` | file: `.autobuild/tickets`; plugin: — | optional nonempty string; forbidden by `linear`, allowed for plugins | Root holding file state directories, or an existing plugin configuration field. |
 
@@ -829,7 +906,7 @@ changing it requires a dispatcher restart.
 | `model` | — (required when `enabled = true`) | nonblank provider-qualified string, same vocabulary as `[roles]` | The turn runner's model, resolved through the deployment's gateway credential; a leading `vercel-ai-gateway/` prefix is accepted and stripped. |
 | `invocationBudgetSeconds` | `240` | positive integer, clamped to 300 | Wall-clock budget for one turn invocation. A larger value is clamped — not rejected — to the 300-second hosted function limit the runner executes under. |
 | `approvals` | `["builds.control:abort", "builds.control:discard", "builds.answer:revise-spec", "sandbox.publish", "tickets.move:ready"]` | array of `tool` or `tool:qualifier` strings | Registry tool calls that suspend a turn until the operator answers. Empty (`[]`) means none — autonomous operation. An entry naming an absent or unknown tool is **inert by design**, never an error. A qualified entry applies to one discriminator value only (`tickets.move:ready` approves moving a ticket to `ready`); for a tool without a discriminator, only the bare form matches. |
-| `wake` | inherits the default | array of event-type globs | The attention events a **new** session wakes for. Absent inherits the default attention set (the events `ab watch` filters on by default); an explicit `[]` means never wake — message-only. Each glob must match at least one build event type. Existing sessions never retroactively inherit; an explicit wake update always wins. |
+| `wake` | inherits the default | array of event-type globs | The attention events a **new** session wakes for. Absent inherits the legacy hosted wake event set, independent of CLI watch defaults; an explicit `[]` means never wake — message-only. Each glob must match at least one build event type. Existing sessions never retroactively inherit; an explicit wake update always wins. |
 | `sandbox` | — | strict subtable | The sandbox behavior knobs; absence reads as the defaults below. |
 
 `[orchestrator.sandbox]` fields:
@@ -1049,7 +1126,7 @@ There is no home-directory fallback: a repository with no state tree starts
 empty.
 
 Every command uses the same precedence: explicit `--store <ref>` > nonempty
-`AB_STORE` > `<main-repo>/.autobuild`. Relative local overrides are normalized
+`AB_STORE` > `[store] url` > `<main-repo>/.autobuild`. Relative local overrides are normalized
 against the main checkout. A local override relocates the whole state tree,
 including `worktrees/` and default file tickets; an explicit `[tickets].dir`
 remains repo-relative. An HTTP(S) URL still selects the remote store unchanged,
@@ -1057,6 +1134,46 @@ while worktrees and default file tickets remain under the repository-default
 `.autobuild/` directory. The dispatcher passes its normalized selection to
 every agent session as `AB_STORE`.
 
+## 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.
+
 ## Source-agnostic ticket operations
 
 The sessionless `ab ticket` namespace constructs whichever TicketSource the
@@ -1111,7 +1228,7 @@ to a ticket that has already been claimed into a build does not stop that build.
 For dependent tickets, follow the
 [safe blocker-filing workflow](references/ticket-dependencies.md): determine the
 intended final destination, stage outside ready, verify all blocker relationships,
-and move to ready last. Direct and hosted Linear create the issue and its blockers
+and move to ready last. Direct Linear creates the issue and its blockers
 in separate requests; one `create --blocked-by` call is not atomic publication.
 Harvest's creation reservations cover Harvest only, not interactive CLI creates.
 Dependency order and JSON id extraction are still required, but do not alone
@@ -1131,16 +1248,19 @@ transitions, so an invalid state fails with the
 source's known states. A missing id fails nonzero with an error naming both the
 id and configured source.
 
-Human-readable output is the default and must not be parsed for ids. Every
-subcommand accepts `--json`, which emits one bare JSON value and no prose: a
+Human-readable output is the default and must not be parsed for ids. The CRUD
+subcommands accept `--json`, which emits one bare JSON value and no prose: a
 `Ticket[]` for `list`, and the complete resulting `Ticket` for `create`,
 `update`, `block`, `unblock`, `show`, or `move`.
 
 ### Ticket assets
 
-A ticket asset is a file or folder attached to a ticket and stored in the
-BuildStore, never in the ticket source: a design export, reference screenshots,
-a sample payload. Each has a kind and a name.
+A ticket asset is a file or folder attached to a ticket: a design export,
+reference screenshots, or a sample payload. Hosted tickets store assets in their
+ticket service, independently of the build store; file tickets use native portable
+assets composed with legacy BuildStore attachments. Sources without native assets
+use the BuildStore. Existing service assets need no migration. Old local hosted-ticket
+assets are not moved and are not a fallback. Each has a kind and a name.
 
 - `ab ticket attach <id> <kind> <path> [--name <name>] [--json]` stores `<path>`
   (default name: its basename). Attaching the same kind and name again makes a
@@ -1152,7 +1272,10 @@ a sample payload. Each has a kind and a name.
 - `ab ticket asset get <id> <kind> <name> <dest> [--rev <n>]` downloads the
   exact bytes of the latest (or given) revision; `ab ticket asset rm <id> <kind>
   <name>` drops it from the current assets.
-- **Frozen at claim.** A claim pins the current revisions into the build. A
+- **Frozen at claim.** A claim pins the current revisions into the build.
+  Hosted revisions are copied into immutable snapshots in the build store,
+  preserving revision numbers and allowing reads without the ticket service.
+  Old pins without snapshots keep reading their original ticket rows. A
   later attach or remove leaves a running build alone; a human answer with
   `--revise-spec-from-ticket` pins again. `ab build asset get <slug> <kind>
   <name> <dest> [--rev <n>]` downloads what the build froze, also after it ends.
@@ -1173,7 +1296,7 @@ judge against it.
 is the read-only binary retrieval form. Operators need no session identity: it
 works after a build is terminal, writes exact bytes (creating parent
 directories), verifies that the build belongs to this repository, and uses the
-standard explicit `--store` > nonblank `AB_STORE` > repository-local selection.
+standard explicit `--store` > nonblank `AB_STORE` > `[store] url` > repository-local selection.
 Inside a phase, a complete ambient tuple permits only the ambient build; a
 foreign build or malformed/partial identity is rejected. Use the exact pinned
 `@rev` from a PR attachment command.
@@ -1507,7 +1630,7 @@ Every command requires the target to exist in this repository and be active
 `ab answer` additionally requires an open escalation. A stale, missing, done,
 aborted, or otherwise inapplicable target is an error and gets no new event. Attribution uses `USER`, then `USERNAME`, then the
 same stable fallback on both surfaces. All five commands run sessionless and
-accept `--store <ref>` with the usual explicit flag > `AB_STORE` > repository
+accept `--store <ref>` with the usual explicit flag > `AB_STORE` > `[store] url` > repository
 local precedence. If nonblank `AB_SESSION` and matching `AB_BUILD` identify the
 caller's own phase build, the command refuses it; a phase cannot pause, resume,
 auto-merge, answer, or abort itself. `ab pause --all` and `ab resume --all`
@@ -1553,7 +1676,7 @@ repository-wide pause (`paused`, default `false`), and the claim-time auto-merge
 default (`defaultAutoMerge`, default `false`). Those defaults also describe a
 repository with no journal row; the read does not create one. Human output is
 the default. `--json` emits one bare object with those exact fields plus the
-canonical `repo`, and `--store` follows the usual explicit flag > `AB_STORE` >
+canonical `repo`, and `--store` follows the usual explicit flag > `AB_STORE` > `[store] url` >
 repository-local precedence. The command uses the same reducer as the
 dispatcher and dashboard, writes no state, claims no ticket, attaches no runner,
 and starts no dispatcher work.
@@ -1636,19 +1759,51 @@ streams matching events as they land instead of answering once. With no slug it
 follows every nonterminal build in the repository — a build created while the
 watch runs joins it without a restart — and naming one or more slugs watches
 exactly those builds, ending the watch when all of them reach a terminal status.
-`--repository` additionally follows the repository journal; without it,
-repository events are never emitted.
-
-The default filter is the attention set — the events something must wake up
-for. For builds that is exactly: `escalation.raised`, `phase.failed`,
-`infrastructure.failed`, `runner.setup-failed`, `dispatch.failed`,
-`publication.lost`, `finalize.completed`, `pr.conflicted`, `pr.merged`,
-`pr.closed`, `build.completed`, `build.aborted`. For the repository journal:
-`harvest.escalated`, `harvest.failed`, `dispatcher.tick-failed`,
-`dispatcher.config-rejected`, `dispatcher.harvest-runner-failed`. A repeatable
-`--event <glob>` (`escalation.*`, `pr.*`, `*` — `*` matches any run of
-characters, `?` one) replaces that filter, and every glob must match at least
-one known event type or the command fails before reading the store.
+With no slugs the repository journal is included; named watches add it with
+`--repository`.
+
+The default watch reports actionable conditions only:
+
+- Build `escalation.raised`, or `build.merge-decision`: a finalized open PR
+  with auto-merge off or a current actionable merge-gate deferral. Armed consent
+  awaiting application is silent. One merge decision is reported per build/PR.
+- Repository `harvest.escalated`, `harvest.recovery-exhausted`,
+  `dispatcher.config-rejected`, `dispatcher.config-reloaded` with nonempty
+  `restartRequired`, abnormal `dispatcher.run-stopped`, and `dispatcher.lost`.
+- `dispatcher.ticket-source-persistent`: degradation past its advertised
+  reset time, once a tick started at or after reset has completed or failed
+  with the episode still open; crossing reset alone is silent. Without a reset,
+  the deadline is 15 minutes after onset. Repeated evidence never postpones
+  the deadline; recovery ends the episode.
+- `dispatcher.tick-failure-persistent`: continuously failing completed ticks
+  for five minutes in one run. A successful tick, new run, or matching stop
+  ends the episode. Source grace and cooldown-driven failures do not start
+  this clock; after grace, the first qualifying failure starts a new five-minute
+  interval. Each persistence episode is reported once.
+
+Repository conditions are included with no slugs or with `--repository`.
+Routine outcomes and self-healing failures are silent. Repeatable
+`--event <glob>` replaces the default and selects exactly matching catalog
+events (plus the existing `dispatcher.lost` observation); use explicit globs
+to opt into failures, finalize, merge, or completion events.
+
+Derived records use `observation` instead of `event`, without inventing a
+durable sequence or actor. Merge observations carry `type`, `pr`, `reason`,
+and `observedAt`, plus the build slug and normal reduced state. Persistence
+observations carry source/cause/message/resetAt when advertised (or
+run/firstFailure/error), `episodeSeq`, and `observedAt`; repository records
+have `repo` and null build/state. Source observations also report
+`dependencyLimited`.
+
+Every record carries a cursor, including timer-only records. Resuming suppresses
+delivered merge decisions and persistence episodes even when stream positions
+did not advance. Old v1 cursors remain valid: historical eligible merge
+decisions are treated as consumed; active overdue repository episodes may
+report because old watches had no persistence notification. Fresh attachment
+silently baselines historical direct events and merge decisions, but retains
+active repository timers. Reconcile existing conditions through status after
+arming the watch. Named watches still end when every named build is terminal;
+learn their outcomes from status reconciliation at exit.
 
 With `--json`, stdout is newline-delimited JSON — exactly one object per
 matching event, flushed as soon as it is written — with fields `build` (slug,
@@ -1745,7 +1900,7 @@ vocabulary is closed: `blocked`, `paused`, `running`, `done`, `aborted`,
 `terminal` (done or aborted), `pr=open`, `pr=merged`, `pr=closed`,
 `pr=conflicted`, `phase=<phase>` (a core phase — `plan`, `plan-review`,
 `implement`, `code-review`, `finalize`, `reconcile` — or `verify:<step>`), and
-`attention` (any event in the `ab watch` attention set). Repeatable `--event`
+`attention` (an open escalation or a build waiting for a merge decision). Repeatable `--event`
 globs follow the `ab watch` rules. Multiple values are alternatives: the first
 one satisfied ends the wait — all `--for` values in supply order, then all
 globs in supply order — and the record names what matched.
@@ -1756,8 +1911,11 @@ means an open escalation exactly as everywhere else. In the manner of `kubectl
 wait`, a condition that already holds when the command starts returns
 immediately with that build's latest event (`--since` does not suppress this);
 otherwise the first later event whose reduction produces it ends the wait.
-`attention` and `--event` conditions fire only on events appended after the
-command started, or on a cursor-resumed backlog after `--since`.
+`attention` is also a current-state condition: an already open escalation or
+merge decision returns immediately, including with `--since`. Merge matches
+use the same observation as watch. During replay, only new escalation events
+or undelivered eligible merge decisions satisfy attention. `--event` conditions
+fire only on new events or a cursor-resumed backlog.
 
 The record is the `ab watch` record plus a `condition` field naming the
 satisfied `--for` value or `--event` glob. Unlike `ab watch`, there is no
@@ -1920,3 +2078,43 @@ build phase, which is the criterion for membership (§16.3): `ab-spec` and
 `ab-tickets` are human/agent-facing pre-build surfaces, `ab-guide` is
 read-only reference including the setup handoff guidance, and `ab-operate` is
 the manual for the orchestrator role, which any agent may take on.
+
+## 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.
+
+Read before writing, and copy the opaque revision verbatim:
+
+```sh
+ab ticket show AUT-8 --json
+ab ticket update AUT-8 --title 'Revised title' --expected-revision '<revision from show>'
+ab ticket edit AUT-8
+```
+
+Use `expectedRevision` on MCP `tickets.update`, `tickets.move`, `tickets.block`
+and `tickets.unblock` with the revision from `tickets.get` or `tickets.list`.