@defrex/autobuild 0.11.0 → 0.12.0

package/packages/core/src/store/remote/compatibility.ts

@@ -0,0 +1,90 @@
+import semver from 'semver'
+import { z } from 'zod'
+import { AUTOBUILD_VERSION, REMOTE_STORE_PROTOCOL_VERSION } from './version'
+
+/** Stable releases only: prefixes, whitespace, prereleases and build suffixes are not identities. */
+export function stableVersion(value: unknown): semver.SemVer | undefined {
+  if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value)) return undefined
+  const parsed = semver.parse(value)
+  return parsed && parsed.version === value ? parsed : undefined
+}
+
+const stableVersionSchema = z.string().refine((value) => stableVersion(value) !== undefined)
+export const supportedClientRangeSchema = z
+  .strictObject({
+    minVersion: stableVersionSchema,
+    maxVersionExclusive: stableVersionSchema,
+  })
+  .refine((range) => semver.lt(range.minVersion, range.maxVersionExclusive))
+export type SupportedClientRange = z.infer<typeof supportedClientRangeSchema>
+
+/** A major starts a new family: X.0 has one line, X.1 two, X.2+ three. */
+export function supportedClientRange(serviceVersion = AUTOBUILD_VERSION): SupportedClientRange {
+  const version = stableVersion(serviceVersion)
+  if (!version) throw new Error('service must have a stable release version')
+  return {
+    minVersion: `${version.major}.${Math.max(0, version.minor - 2)}.0`,
+    maxVersionExclusive: `${version.major}.${version.minor + 1}.0`,
+  }
+}
+
+export function classifyClient(
+  version: unknown,
+  range: SupportedClientRange,
+): 'supported' | 'older' | 'newer' | 'invalid' {
+  const parsed = stableVersion(version)
+  if (!parsed) return 'invalid'
+  if (semver.lt(parsed, range.minVersion)) return 'older'
+  if (semver.gte(parsed, range.maxVersionExclusive)) return 'newer'
+  return 'supported'
+}
+
+export function formatClientRange(range: SupportedClientRange): string {
+  return `>=${range.minVersion} <${range.maxVersionExclusive}`
+}
+
+export function compatibilityAdvice(
+  client: unknown,
+  serviceVersion: string,
+  range: SupportedClientRange,
+): string | undefined {
+  const classification = classifyClient(client, range)
+  const description = `service Autobuild ${serviceVersion} supports clients ${formatClientRange(range)}`
+  if (classification === 'supported') return undefined
+  if (classification === 'newer') {
+    const version = stableVersion(client)!
+    return `${description}; upgrade the service to at least ${version.major}.${version.minor}.0 before upgrading projects (service first)`
+  }
+  if (classification === 'older')
+    return `${description}; upgrade the project's Autobuild into ${formatClientRange(range)}`
+  return `${description}; supply a stable Autobuild client version`
+}
+
+/** Retain these wire identities and handlers until their lines leave the window.
+ * Historical lines require explicit entries; the service's own line uses its
+ * current protocol identity. Unknown historical protocols fail closed. */
+export const RELEASE_LINE_PROTOCOLS: Readonly<Record<string, string>> = {
+  '0.9': '3',
+  '0.10': '3',
+  '0.11': '3',
+  '0.12': '3',
+}
+
+export function clientIdentityError(
+  client: string | null,
+  protocol: string | null,
+  serviceVersion = AUTOBUILD_VERSION,
+  serviceProtocol = REMOTE_STORE_PROTOCOL_VERSION,
+): string | undefined {
+  const range = supportedClientRange(serviceVersion)
+  const service = stableVersion(serviceVersion)!
+  const advice = compatibilityAdvice(client, serviceVersion, range)
+  const parsed = stableVersion(client)
+  const expected =
+    parsed &&
+    (parsed.major === service.major && parsed.minor === service.minor
+      ? serviceProtocol
+      : RELEASE_LINE_PROTOCOLS[`${parsed.major}.${parsed.minor}`])
+  if (!advice && expected !== undefined && protocol === expected) return undefined
+  return `remote store version mismatch: client Autobuild ${client ?? '(missing)'} protocol ${protocol ?? '(missing)'}; server Autobuild ${serviceVersion} protocol ${serviceProtocol}; ${advice ?? `supported clients ${formatClientRange(range)}; unsupported protocol identity`}`
+}

package/packages/core/src/store/remote/credentials.ts

@@ -0,0 +1,28 @@
+import { delegateCredentialResponseSchema, type DelegateCredentialTarget } from './protocol'
+import {
+  AUTOBUILD_VERSION,
+  AUTOBUILD_VERSION_HEADER,
+  REMOTE_STORE_PROTOCOL_VERSION,
+  REMOTE_STORE_PROTOCOL_VERSION_HEADER,
+} from './version'
+
+/** Fail closed: a remote execution must never fall back to its parent token. */
+export async function delegateCredential(
+  storeRef: string,
+  token: string | undefined,
+  target: DelegateCredentialTarget,
+): Promise<string> {
+  if (!token) throw new Error('credential delegation requires parent authority')
+  const response = await fetch(`${storeRef.replace(/\/$/, '')}/credentials/delegate`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json',
+      [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
+      [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
+    },
+    body: JSON.stringify(target),
+  })
+  if (!response.ok) throw new Error(`credential delegation refused (${response.status})`)
+  return delegateCredentialResponseSchema.parse(await response.json()).token
+}

package/packages/core/src/store/remote/index.ts

@@ -4,7 +4,13 @@
 export { AuthError, RemoteBuildStore } from './client'
 export type { RemoteBuildStoreOptions, RemoteStoreIdentity } from './client'
 export { mintToken, tokenResource, verifyToken } from './token'
-export type { OperatorTokenScope, TokenScope } from './token'
+export type {
+  OperatorTokenScope,
+  InternalOperatorTokenScope,
+  AdminTokenScope,
+  TokenScope,
+  DelegatedTokenScope,
+} from './token'
 export {
   AUTOBUILD_VERSION,
   AUTOBUILD_VERSION_HEADER,
@@ -22,3 +28,10 @@ export type { SessionEvent, SessionEventWrite } from '../../events/sessions'
 export type { RepositoryEvent, RepositoryEventWrite } from '../../events/repository'
 export { SNAPSHOT_REDUCER_NAME } from '../snapshots'
 export type { ReducerSnapshot, SnapshotScope } from '../snapshots'
+
+export * from './compatibility'
+
+export { delegateCredential } from './credentials'
+
+export { reduceBuild } from '../../kernel/reducer'
+export { reduceHarvest } from '../../kernel/harvest'

package/packages/core/src/store/remote/protocol.ts

@@ -450,3 +450,28 @@ export function substitutePlaceholderRefs(
   }
   return value
 }
+
+/** Issuance is an authentication operation, separate from the BuildStore port. */
+export const delegateCredentialBodySchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('build-runner'), id: z.string().min(1) }),
+  z.strictObject({
+    kind: z.literal('build-phase'),
+    id: z.string().min(1),
+    session: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal('harvest-runner'),
+    execution: z.string().min(1),
+    repo: z.string().min(1),
+    id: z.string().min(1),
+    leaseHolder: z.string().min(1),
+  }),
+  z.strictObject({
+    kind: z.literal('harvest-phase'),
+    repo: z.string().min(1),
+    id: z.string().min(1),
+    session: z.string().min(1),
+  }),
+])
+export type DelegateCredentialTarget = z.infer<typeof delegateCredentialBodySchema>
+export const delegateCredentialResponseSchema = z.strictObject({ token: z.string().min(1) })

package/packages/core/src/store/remote/token.ts

@@ -1,13 +1,7 @@
-/**
- * HMAC-scoped store tokens (SPEC §8.1 [D8]): "the token is scoped to this
- * build and session — an agent physically cannot append to another build's
- * log or read another build's artifacts". Least privilege comes from the
- * runner minting a narrow token, not from prompt instructions.
- *
- * A token is `base64url(JSON scope) + '.' + base64url(hmac-sha256(secret,
- * payload))`. The scope IS the token — the server keeps no session state;
- * it verifies the signature (timing-safe) and the expiry, then trusts the
- * embedded scope.
+/** Signed lifecycle-bound execution grants, internal owner delegation and admin.
+ * Historical resource/deployment/operator scopes remain decodable for tests
+ * and migration diagnostics; hosted machine gates reject those retired forms.
+ * Project credentials are opaque stored secrets, not these stateless tokens.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto'
 import { z } from 'zod'
@@ -52,8 +46,35 @@ export interface DeploymentTokenScope {
   exp: number
 }
 
-/** Legacy scopes remain valid on their existing routes. */
+/** Includes retired wire shapes for recognition, never server authorization. */
+export interface InternalOperatorTokenScope {
+  version: 1
+  internalOperator: { user: string; repo: string }
+  exp: number
+  via?: Via
+}
+export interface AdminTokenScope {
+  version: 1
+  ownerAdmin: { user: string }
+  exp: number
+}
+export interface DelegatedTokenScope {
+  version: 2
+  delegation: {
+    repo: string
+    kind: 'build-runner' | 'build-phase' | 'harvest-runner' | 'harvest-phase'
+    id: string
+    anchor: number
+    session?: string
+    execution?: string
+    leaseHolder?: string
+  }
+}
+
 export type TokenScope =
+  | DelegatedTokenScope
+  | InternalOperatorTokenScope
+  | AdminTokenScope
   | LegacyBuildTokenScope
   | ResourceTokenScope
   | OperatorTokenScope
@@ -63,7 +84,38 @@ const commonScope = {
   session: z.string().min(1),
   exp: z.number().int(),
 }
+const exactIdentity = z
+  .string()
+  .min(1)
+  .refine((value) => value !== '*')
+const delegatedClaims = z
+  .strictObject({
+    repo: exactIdentity,
+    kind: z.enum(['build-runner', 'build-phase', 'harvest-runner', 'harvest-phase']),
+    id: exactIdentity,
+    anchor: z.number().int().positive(),
+    session: exactIdentity.optional(),
+    execution: exactIdentity.optional(),
+    leaseHolder: exactIdentity.optional(),
+  })
+  .refine(
+    (claims) =>
+      claims.kind.endsWith('-phase') === (claims.session !== undefined) &&
+      claims.kind.startsWith('harvest') === (claims.execution !== undefined),
+  )
 const tokenScopeSchema = z.union([
+  z.strictObject({ version: z.literal(2), delegation: delegatedClaims }),
+  z.strictObject({
+    version: z.literal(1),
+    internalOperator: z.strictObject({ user: z.string().trim().min(1), repo: z.string().min(1) }),
+    exp: z.number().int(),
+    via: viaSchema.optional(),
+  }),
+  z.strictObject({
+    version: z.literal(1),
+    ownerAdmin: z.strictObject({ user: z.string().trim().min(1) }),
+    exp: z.number().int(),
+  }),
   z.strictObject({ build: z.string().min(1), ...commonScope }),
   z.strictObject({
     resource: z.strictObject({
@@ -85,6 +137,13 @@ export function tokenResource(scope: TokenScope): {
   kind: 'build' | 'repo' | 'session' | 'admin' | 'operator' | 'deployment'
   id: string
 } {
+  if ('delegation' in scope)
+    return {
+      kind: scope.delegation.kind.startsWith('build') ? 'build' : 'repo',
+      id: scope.delegation.kind.startsWith('build') ? scope.delegation.id : scope.delegation.repo,
+    }
+  if ('ownerAdmin' in scope) return { kind: 'admin', id: '*' }
+  if ('internalOperator' in scope) return { kind: 'operator', id: scope.internalOperator.user }
   if ('operator' in scope) {
     return scope.operator === true
       ? { kind: 'deployment', id: '*' }
@@ -108,7 +167,9 @@ export function mintToken(secret: string, scope: TokenScope): string {
 /**
  * Bad signature, malformed token, unparseable scope, or expired → null —
  * verification never explains itself to the caller (the server maps null to
- * 401). The signature compare is timing-safe via `crypto.timingSafeEqual`.
+ * 401). Version-2 grants deliberately have no fixed expiration: the service
+ * must additionally validate their registered project and durable lifecycle.
+ * The signature compare is timing-safe via `crypto.timingSafeEqual`.
  */
 export function verifyToken(secret: string, token: string, now: Date): TokenScope | null {
   const parts = token.split('.')
@@ -132,6 +193,6 @@ export function verifyToken(secret: string, token: string, now: Date): TokenScop
   }
   const scope = tokenScopeSchema.safeParse(raw)
   if (!scope.success) return null
-  if (scope.data.exp <= now.getTime()) return null
+  if ('exp' in scope.data && scope.data.exp <= now.getTime()) return null
   return scope.data
 }

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

@@ -283,6 +283,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 +421,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 +454,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 +524,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 +724,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 +732,11 @@ 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.
+
 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 +754,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
@@ -748,10 +790,11 @@ state eligible.
 | `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. |
 | `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"`) or an existing plugin configuration field. |
 | `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/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. |
 | `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 +872,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 +1092,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 +1100,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 +1194,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
@@ -1173,7 +1256,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 +1590,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 +1636,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 +1719,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 +1860,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 +1871,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