@defrex/autobuild 0.12.0 → 0.14.0

package/packages/core/src/testing/reduced-read-budget.ts

@@ -0,0 +1,462 @@
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { abDispatch } from '../cli/dispatch'
+import { randomUuids } from '../ids'
+import { ScriptedAgentRunner, defaultTurnResult } from '../ports/runner/fake'
+import { Dispatcher } from '../processes/dispatcher'
+import { FakeTicketSource } from '../ports/tickets/fake'
+import { FakeWorkspaceProvider } from '../ports/workspace/fake'
+import { FakeForge } from '../ports/forge/fake'
+import { sequentialIds } from '../ids'
+import { parseConfig } from '../config/load'
+import {
+  getOperatorDashboard,
+  listOperatorBuilds,
+  getOperatorBuild,
+  getRepositoryStatus,
+} from '../operator/query'
+import { buildRegistry } from '../operator/registry'
+import { expect } from 'bun:test'
+import type { BuildStore } from '../store/types'
+import { KERNEL, DISPATCHER, humanActor } from '../events/envelope'
+import {
+  readBuildFacts,
+  readBuildStreamSeed,
+  readRepositoryFacts,
+  readRepositoryAttention,
+  readBuildDigests,
+  readDispatcherRunFacts,
+  readOpenTick,
+} from '../store/reduced-reads'
+import { RepoViewStore } from '../processes/repo-view'
+import { abWatch, decodeCursor } from '../cli/watch'
+import { abWait } from '../cli/wait'
+import type { Exec } from '../ports/workspace/git-worktree'
+
+export interface ReducedReadCosts {
+  events: number
+  metadata: number
+  bytes: number
+  historicalEvents: number
+  history?: { repo: string; through: number }
+}
+const repo = '/reduced-read-budget'
+const slug = 'reduced-budget'
+const exec: Exec = async (args) =>
+  args[1] === 'remote'
+    ? { stdout: '', stderr: 'no origin', exitCode: 2 }
+    : { stdout: `${repo}/.git\n${repo}/.git\n${repo}\n`, stderr: '', exitCode: 0 }
+
+/** Shared actual-consumer scenario. Costs must instrument SQL statement results,
+ * including private reducer storage, rather than just public getEvents calls. */
+export async function reducedReadBudget(opts: {
+  store: BuildStore
+  costs: ReducedReadCosts
+  fresh: () => Promise<BuildStore>
+  storeRef?: string
+}) {
+  const { store, costs } = opts
+  await store.ensureRepo(repo)
+  const config = parseConfig(
+    '[tickets]\nsource="file"\nreadyState="ready"\n[verify]\nsteps=[]\n[finalize]\nsteps=[]',
+  )
+  const { verify: _verify, finalize: _finalize, ...root } = config
+  const configArtifact = await store.putRepoArtifact(repo, {
+    kind: 'dispatcher-effective-config',
+    content: JSON.stringify({ ...root, verify: { steps: [] }, finalize: { steps: [] } }),
+  })
+  await store.appendRepo(repo, {
+    actor: DISPATCHER,
+    type: 'dispatcher.run-started',
+    payload: {
+      run: 'budget-run',
+      pid: 1,
+      roleWarnings: [],
+      effectiveConfig: { kind: configArtifact.kind, rev: configArtifact.revision },
+    },
+  })
+  await store.createBuild({ slug, repo })
+  await store.append(slug, {
+    actor: KERNEL,
+    type: 'runner.attached',
+    payload: { instance: 'budget', host: 'host' },
+  })
+  await store.append(slug, {
+    actor: KERNEL,
+    type: 'finalize.completed',
+    payload: { pr: { number: 7, url: 'https://example.test/7', headSha: 'abc' } },
+  })
+  await store.append(slug, {
+    actor: humanActor('human'),
+    type: 'build.auto-merge-requested',
+    payload: {},
+  })
+  const reset = () => {
+    costs.events = 0
+    costs.metadata = 0
+    costs.bytes = 0
+  }
+  let repositoryBytes: number | undefined
+  for (const length of [32, 256]) {
+    for (let i = 0; i < length; i++) {
+      await store.append(slug, {
+        actor: humanActor('human'),
+        type: 'build.auto-merge-requested',
+        payload: {},
+      })
+      await store.appendRepo(repo, {
+        actor: humanActor('human'),
+        type: 'dispatcher.intake-set',
+        payload: { enabled: true },
+      })
+      const run = `old-${length}-${String(i).padStart(4, '0')}`
+      await store.appendRepo(repo, {
+        actor: DISPATCHER,
+        type: 'dispatcher.run-started',
+        payload: {
+          run,
+          pid: 1,
+          roleWarnings: [],
+          effectiveConfig: { kind: configArtifact.kind, rev: configArtifact.revision },
+        },
+      })
+      await store.appendRepo(repo, {
+        actor: DISPATCHER,
+        type: 'dispatcher.run-stopped',
+        payload: { run, outcome: 'normal' },
+      })
+    }
+    await store.appendRepo(repo, {
+      actor: DISPATCHER,
+      type: 'dispatcher.run-started',
+      payload: {
+        run: 'budget-run',
+        pid: 1,
+        roleWarnings: [],
+        effectiveConfig: { kind: configArtifact.kind, rev: configArtifact.revision },
+      },
+    })
+    const factsBytes = Buffer.byteLength(
+      JSON.stringify((await readRepositoryFacts(store, repo)).value),
+    )
+    if (repositoryBytes !== undefined) expect(factsBytes).toBeLessThan(repositoryBytes + 512)
+    repositoryBytes = factsBytes
+    // Warm persisted values independently of any consumer instance.
+    await readBuildStreamSeed(store, slug)
+    await readBuildFacts(store, slug)
+    await readRepositoryFacts(store, repo)
+    await readBuildDigests(store, repo)
+    await readRepositoryAttention(store, repo)
+    const handle = await opts.fresh()
+    const cold = new Proxy(handle, {
+      get(target, key) {
+        if (key === 'close') return async () => {}
+        const value = Reflect.get(target, key, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      },
+    })
+    await coldDispatchOnceBudget(store, cold, length, costs)
+    reset()
+    const view = new RepoViewStore(cold, { repo })
+    await view.refresh()
+    expect((await view.buildFacts(slug)).state.pr?.number).toBe(7)
+    expect((await view.buildState(slug)).status).toBe('running')
+    expect(costs.events).toBe(0)
+    expect(costs.metadata).toBeLessThan(100)
+
+    const dispatcher = () =>
+      new Dispatcher({
+        store: cold,
+        repo,
+        config,
+        tickets: new FakeTicketSource([]),
+        workspaces: new FakeWorkspaceProvider({ root: '/budget-workspaces', mode: 'logical' }),
+        forge: new FakeForge(),
+        ids: sequentialIds(),
+        clock: () => new Date(1000),
+        exec,
+        launchRunner: async () => 'scheduled',
+      })
+    await dispatcher().tick({ acceptNewWork: false })
+    await getOperatorDashboard({ store: cold, repo, clock: () => new Date(1000) })
+    reset()
+    await dispatcher().tick({ acceptNewWork: false })
+    await getOperatorDashboard({ store: cold, repo, clock: () => new Date(1000) })
+    await listOperatorBuilds({ store: cold, repo, scope: 'all', now: new Date(1000) })
+    await getOperatorBuild({ store: cold, repo, slug, now: new Date(1000) })
+    await getRepositoryStatus(cold, repo, new Date(1000))
+    await buildRegistry({ store: cold, clock: () => new Date(1000) }).call('builds.get', {
+      repo,
+      slug,
+    })
+    expect(costs.events).toBe(0)
+    expect(costs.metadata).toBeLessThan(400)
+    expect(costs.bytes).toBeLessThan(1_000_000)
+
+    // A fresh watch must suppress historical PR eligibility despite armed
+    // consent at registration, including its first event-bearing poll.
+    reset()
+    let ticks = 0
+    let time = 0
+    const out: string[] = []
+    await abWatch({
+      targetRepo: repo,
+      env: {},
+      exec,
+      storeRef: opts.storeRef ?? '/budget',
+      openStore: () => cold,
+      slugs: [slug],
+      json: true,
+      timeout: '2',
+      now: () => new Date(time),
+      stdout: (line) => out.push(line),
+      stderr: () => {},
+      delay: async () => {
+        time += 1000
+        if (++ticks === 1)
+          await store.append(slug, {
+            actor: humanActor('human'),
+            type: 'build.auto-merge-cancelled',
+            payload: {},
+          })
+      },
+    })
+    expect(out).toHaveLength(1)
+    const cursor = JSON.parse(out[0]!).cursor
+    expect(
+      decodeCursor(cursor, { store: opts.storeRef ?? '/budget', repo }).deliveredAttention,
+    ).toEqual([JSON.stringify([slug, 7])])
+    expect(costs.events).toBeLessThanOrEqual(4)
+    expect(costs.metadata).toBeLessThan(100)
+
+    await store.append(slug, {
+      actor: humanActor('human'),
+      type: 'build.auto-merge-requested',
+      payload: {},
+    })
+    await readBuildStreamSeed(store, slug)
+    reset()
+    let discoveryTick = 0
+    time = 0
+    const discovered = new Proxy(cold, {
+      get(target, key) {
+        if (key === 'listBuilds')
+          return async () => (discoveryTick === 0 ? [] : target.listBuilds())
+        const value = Reflect.get(target, key, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      },
+    })
+    const discoveryOut: string[] = []
+    await abWatch({
+      targetRepo: repo,
+      env: {},
+      exec,
+      storeRef: opts.storeRef ?? '/budget',
+      openStore: () => discovered,
+      json: true,
+      timeout: '3',
+      now: () => new Date(time),
+      stdout: (line) => discoveryOut.push(line),
+      stderr: () => {},
+      delay: async () => {
+        time += 1000
+        if (++discoveryTick === 2)
+          await store.append(slug, {
+            actor: humanActor('human'),
+            type: 'build.auto-merge-cancelled',
+            payload: {},
+          })
+      },
+    })
+    expect(discoveryOut).toHaveLength(1)
+    expect(costs.events).toBeLessThanOrEqual(6)
+    expect(costs.metadata).toBeLessThan(180)
+
+    // Wait applies its current-attention policy instead of watch suppression.
+    await readBuildStreamSeed(store, slug)
+    reset()
+    const waitOut: string[] = []
+    const result = await abWait({
+      targetRepo: repo,
+      env: {},
+      exec,
+      storeRef: opts.storeRef ?? '/budget',
+      openStore: () => cold,
+      slugs: [slug],
+      forValues: ['attention'],
+      json: true,
+      now: () => new Date(time),
+      stdout: (line) => waitOut.push(line),
+      stderr: () => {},
+    })
+    expect(result).toBe(0)
+    expect(JSON.parse(waitOut[0]!).observation.pr.number).toBe(7)
+    expect(costs.events).toBe(0)
+    expect(costs.metadata).toBeLessThan(40)
+    await store.append(slug, {
+      actor: humanActor('human'),
+      type: 'build.auto-merge-requested',
+      payload: {},
+    })
+    await readBuildStreamSeed(store, slug)
+    reset()
+    let waitTick = 0
+    time = 0
+    const polled: string[] = []
+    const waited = await abWait({
+      targetRepo: repo,
+      env: {},
+      exec,
+      storeRef: opts.storeRef ?? '/budget',
+      openStore: () => cold,
+      slugs: [slug],
+      forValues: ['attention'],
+      json: true,
+      timeout: '4',
+      now: () => new Date(time),
+      stdout: (line) => polled.push(line),
+      stderr: () => {},
+      delay: async () => {
+        time += 1000
+        // The first pass stays idle; the next delivers the first event batch.
+        if (++waitTick === 1) {
+          expect(costs.events).toBe(0)
+          expect(costs.metadata).toBeLessThan(40)
+        }
+        if (waitTick === 2) {
+          expect(costs.events).toBe(0)
+          await store.append(slug, {
+            actor: humanActor('human'),
+            type: 'build.auto-merge-cancelled',
+            payload: {},
+          })
+        }
+      },
+    })
+    expect(waited).toBe(0)
+    expect(waitTick).toBe(2)
+    expect(JSON.parse(polled[0]!).observation.pr.number).toBe(7)
+    expect(costs.events).toBeLessThanOrEqual(2)
+    expect(costs.metadata).toBeLessThan(50)
+  }
+}
+
+/** Exercise the real outer DispatchLoop with a new invocation identity. Only
+ * shared values are warmed: no parameterized run value may hide a cold replay. */
+async function coldDispatchOnceBudget(
+  store: BuildStore,
+  cold: BuildStore,
+  length: number,
+  costs: ReducedReadCosts,
+) {
+  const onceRepo = 'https://github.com/budget/cold-once'
+  await store.ensureRepo(onceRepo)
+  for (let i = 0; i < length; i++)
+    await store.appendRepo(onceRepo, {
+      actor: humanActor('human'),
+      type: 'dispatcher.intake-set',
+      payload: { enabled: false },
+    })
+  const boundary = (await readRepositoryFacts(store, onceRepo)).cursor
+  const directory = await mkdtemp(join(tmpdir(), 'ab-cold-once-'))
+  try {
+    await writeFile(
+      join(directory, 'autobuild.toml'),
+      `[roles.default]
+runtime = "claude"
+[tickets]
+source = "file"
+readyState = "ready"
+[verify]
+steps = []
+[finalize]
+steps = []
+`,
+    )
+    const checked = new Proxy(cold, {
+      get(target, key) {
+        if (key === 'getReducerValue')
+          return (...args: Parameters<BuildStore['getReducerValue']>) => {
+            expect(['dispatcherRunFacts', 'openTick']).not.toContain(args[1].reducer)
+            return target.getReducerValue(...args)
+          }
+        const value = Reflect.get(target, key, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      },
+    })
+    costs.events = 0
+    costs.metadata = 0
+    costs.bytes = 0
+    costs.historicalEvents = 0
+    costs.history = { repo: onceRepo, through: boundary }
+    const run = `never-read-once-${length}`
+    await abDispatch({
+      targetRepo: directory,
+      repo: onceRepo,
+      env: {},
+      exec: async (args) =>
+        args[1] === 'remote'
+          ? { stdout: `${onceRepo}.git\n`, stderr: '', exitCode: 0 }
+          : {
+              stdout: `${directory}/.git\n${directory}/.git\n${directory}\n`,
+              stderr: '',
+              exitCode: 0,
+            },
+      stdout: () => {},
+      stderr: () => {},
+      once: true,
+      plain: true,
+      kernelRunId: run,
+      storeRef: '/budget',
+      wire: () => ({
+        store: checked,
+        storeRef: '/budget',
+        tickets: new FakeTicketSource([]),
+        forge: new FakeForge(),
+        workspaces: new FakeWorkspaceProvider({ root: '/once-workspaces', mode: 'logical' }),
+        buildExecution: {
+          start: () => {
+            throw new Error('no builds in once budget')
+          },
+        },
+        runtimes: {
+          claude: {
+            runner: new ScriptedAgentRunner({ script: () => defaultTurnResult() }),
+            servesModels: [],
+          },
+        },
+        ids: sequentialIds(),
+        uuids: randomUuids(),
+        clock: () => new Date(1000),
+      }),
+    })
+    const finished = (await readRepositoryFacts(checked, onceRepo)).value.recentRuns.find(
+      ([id]) => id === run,
+    )?.[1]
+    expect(finished?.completed?.type).toBe('dispatcher.tick-completed')
+    expect(finished?.stop?.type).toBe('dispatcher.run-stopped')
+    // The same fresh invocation may fail before writing its start fact.
+    expect(
+      (await readDispatcherRunFacts(checked, onceRepo, `never-started-${length}`, false)).value,
+    ).toEqual({})
+    expect(await readOpenTick(checked, onceRepo, `never-started-${length}`, false)).toBe(false)
+    expect(costs.historicalEvents).toBe(0)
+    expect(costs.events).toBeLessThanOrEqual(32)
+    expect(costs.metadata).toBeLessThan(300)
+    expect(costs.bytes).toBeLessThan(1_000_000)
+  } finally {
+    delete costs.history
+    await rm(directory, { recursive: true, force: true })
+  }
+}
+
+/** SQL result instrumentation handles both raw object rows and Drizzle values. */
+export function countHistoricalRows(costs: ReducedReadCosts, rows: unknown): number {
+  if (!costs.history || !Array.isArray(rows)) return 0
+  return rows.filter((row) => {
+    const repo = Array.isArray(row) ? row[0] : row?.repo
+    const seq = Number(Array.isArray(row) ? row[1] : row?.seq)
+    return repo === costs.history!.repo && seq <= costs.history!.through
+  }).length
+}

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** —
@@ -737,6 +755,21 @@ 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
@@ -788,13 +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` and `hosted`, 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. |
+| `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/hosted: 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. |
 
@@ -1214,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
@@ -1235,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.
@@ -1783,7 +1823,12 @@ cursor from a different repository or store is rejected.
 Dispatcher liveness is also visible through `ab repository status --json`:
 `dispatcher.holder` identifies the unexpired repository lease owner, independently
 of `latestRun`. Heartbeat age measures attributable renewals; tick age measures
-durable progress. Missing historical evidence is null. The liveness query uses
+actual tick completion. Successful unchanged ticks leave no journal pair; bounded,
+lease-fenced repository telemetry still records each actual completion and its
+outcome. Last-tick age refreshes independently of the event cursor and never uses
+heartbeat as completion evidence. Open telemetry protects unsafe work during
+shutdown; historical journals retain their boundary fallback. Missing historical
+evidence is null. The liveness query uses
 bounded repository facts first, with a full-history fallback when a later
 invocation hides the holder start or the latest stop. Other state reads retain
 their bounded semantics.
@@ -2038,3 +2083,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`.

package/skills/guide/references/operator-api.md

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