@defrex/autobuild 0.10.1 → 0.12.0

package/skills/guide/SKILL.md

@@ -234,6 +234,19 @@ Every other known table is closed to unknown keys. The removed `[dashboardFrames
 `[dispatcher]`, `[harvest]`, and `[outer]` tables have no aliases or migration
 shims; they fail as ordinary unknown top-level keys.
 
+Ticket-source ready scans run immediately when no completed measurement exists,
+then every
+`ticketScanIntervalSeconds` (default 60 seconds, a positive integer). Actual
+tick spacing is the floor when the configured interval is shorter. A
+same-repository `pr.merged`, `build.completed`, or `build.aborted` fact forces
+another scan on the next tick; changed ready criteria also force a scan.
+Housekeeping keeps its ordinary tick cadence. Between scans, queue depth and
+standing diagnostics repeat the last completed measurement, including across
+process restarts. Tickets groomed directly in the tracker are picked up within
+one scan interval plus one tick when capacity permits. Observation while intake
+is off shares the cadence; an observation measurement cannot suppress a fresh
+admission scan when intake is enabled.
+
 ### Root scalars
 
 Root scalars must appear before the first TOML table; TOML otherwise nests them
@@ -242,6 +255,7 @@ under the preceding table.
 | Field | Default | Allowed / constraints | Effect |
 |---|---|---|---|
 | `baseBranch` | `"main"` | nonempty string | The branch builds branch from and target with their PR; what `reconcile` merges into the build branch. |
+| `ticketScanIntervalSeconds` | `60` | positive integer seconds | Hot-reloaded ready scan cadence; tick spacing is the floor, and same-repository merge/completion/abort forces an early scan. |
 | `capacity` | `1` | positive integer | Maximum concurrent builds for this repository. |
 | `forge` | `"github"` | nonblank string | Selects shipped `github` or `local-git`, or a plugin-registered Forge adapter. `github` authenticates with `GITHUB_TOKEN`, then `GH_TOKEN`, then the gh CLI's stored login. |
 | `plugins` | `[]` | array of unique nonblank module specifiers | Trusted Bun plugin modules loaded before dispatch, `ab ticket`, and scoped phase wiring. |
@@ -269,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.
@@ -394,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.
@@ -405,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
@@ -474,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>`.
@@ -674,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. |
@@ -681,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
@@ -698,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
@@ -734,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. |
 
@@ -815,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:
@@ -1035,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,
@@ -1043,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
@@ -1097,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
@@ -1159,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.
@@ -1493,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`
@@ -1539,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.
@@ -1622,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,
@@ -1650,6 +1779,23 @@ matching event after that cursor is delivered exactly once, in per-stream
 sequence order — including events that landed while no watch was running. A
 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
+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.
+
+Repository-following `ab watch` additionally emits a read-only `dispatcher.lost`
+observation when an observed lease expires without a matching stop. JSON carries
+`observation` instead of `event`, with run, observedAt, leaseExpiresAt and available
+identity, plus the usual repo/build/state/cursor fields. It invents no durable
+sequence or actor. Retain the cursor to avoid repeat reports across invocations.
+No lease alone is not evidence of death. SIGINT, SIGHUP and SIGTERM drain dispatch,
+record the first signal in the stop fact, and release its lease before exit.
+
 The watch ends with exit 0 when `--timeout` elapses (30 minutes by default;
 `0` unbounded), after `--count <n>` records, or when named builds have all
 gone terminal; with no slugs named, an empty set of active builds does not end
@@ -1714,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.
@@ -1725,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

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

@@ -6,17 +6,48 @@ Every request must send `X-Autobuild-Version`,
 `X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
 
-Mint a token offline; the signed user is used as the human actor on every write:
+Project credentials are opaque `abp_1_<id>_<secret>` bearer values bound to one
+registered normalized repository. The service stores only a SHA-256 digest of
+the random secret, plus project, creator, creation time, last use, expiry and
+revocation metadata. It checks credential status and project registration on
+every request. Revocation takes effect on the next request without affecting
+other credentials. Unknown, expired or revoked credentials receive `401 auth`;
+removed projects receive `403 auth` with `project not registered`.
+
+The deployment owner runs these commands locally with database access:
 
 ```sh
-AB_STORE_SECRET='…' bun packages/hosted-store-service/src/bin.ts mint operator \
-  --user 'Ada Lovelace' --ttl-seconds 3600
+ab-hosted-store credentials issue https://github.com/acme/app --user owner@example.com
+ab-hosted-store credentials list https://github.com/acme/app
+ab-hosted-store credentials revoke https://github.com/acme/app --id ID --user owner@example.com
 ```
 
-Admin, build, repository, and deployment (`{ "operator": true, … }`) tokens
-have no attributed operator authority. Human-operator tokens have no raw
-`/builds`, `/repos`, `/sessions`, or `/tickets` authority. Encode repository,
-build, session, and artifact kind as separate URL path segments.
+Issue prints the secret once; list contains metadata only. Issue optionally
+accepts `--ttl-seconds N` or `--expires-at ISO-8601`. For administrative/non-interactive issuance, set the returned token as
+`AB_TOKEN`. Interactive project onboarding uses `ab connect <service-url>`;
+it saves the credential outside the repository and commits no secret. Previous `AB_TOKEN` values and `mint operator` / `mint build` are
+retired: the service responds that the credential format changed and points
+to `credentials issue`. Supported old protocol shapes still work with a new
+credential; protocol compatibility does not restore retired authentication.
+
+`mint admin --ttl-seconds N` creates an explicit versioned, attributed owner
+break-glass credential. It can cross project boundaries. Keep it owner-only:
+never give it or `AB_STORE_SECRET` to a dispatcher or build agent.
+
+Owner-purpose project credentials attribute every write to their recorded creator.
+Dispatcher-purpose credentials are refused. Signed-in owners in the dashboard
+and MCP receive short-lived internal signatures with an explicit version,
+selected repository, signed user, expiry and MCP `via`. Only the service holds
+the signing key. These signatures authorize operator routes only and require a
+registered project; replay against another project is refused.
+
+The path project is checked before registry lookup, body parsing and generic
+tool execution. Body repositories and secondary build/session identifiers are
+also checked inside that project. Explicit project mismatches return `403 auth:
+wrong project`; removal returns `403 auth: project not registered`. Encode each
+repository, build, session and artifact kind as a separate URL path segment.
+Registration changes use the database-local `projects list|add|remove` owner
+commands; see [owner workflow](setup.md#connected-projects).
 
 ## Operator sessions
 
@@ -66,7 +97,11 @@ supplied forms return `400 validation`.
 Dashboard reads use the latest durable, run-correlated `effectiveConfig`
 repository artifact. Missing, corrupt, or invalid configuration returns a typed
 `409 effective-config-unavailable`; the service never guesses from a checkout.
-Clients poll these reads; streaming is not provided. `triageState`, `readyState`,
+Clients poll these reads — the operator HTTP API exposes no push or long-poll
+event transport. Streaming is provided as a CLI read surface: `ab watch`
+streams build and repository events by polling the same event logs client-side
+(the store protocol's `GET /builds/{slug}/events` and `GET /repos/{repo}/events`
+reads), not as a transport on this API. `triageState`, `readyState`,
 and every entry in `states` are backend state names and must be sent back verbatim
 when used with the move control.
 
@@ -105,12 +140,25 @@ The retry object is deliberately bare: adding `text` is a `400 validation`
 rather than silently changing the resolution to guidance. A revision object may
 also carry `ceiling` only to receive the shared `incompatible-answer-options`
 refusal; a ceiling and spec revision cannot be performed together.
-
 The hosted service has no ticket-provider credentials. For ticket-origin
 revision, a trusted caller fetches the current ticket body and supplies it; the
 build must still have a recorded ticket. Revision conformance, lazy retry,
 artifact metadata, event ordering, and refusal rules are the same as the CLI.
 
+## The registry's protocol face: `POST …/tools/{tool}`
+
+One generic route executes any entry of the agent tool registry (the same
+closed table `ab mcp` serves over stdio and the hosted `/mcp` endpoint serves
+over Streamable HTTP): the body is the tool's validated input — `repo`
+included and required to equal the URL's repository — and the response is the
+registry result verbatim. The verified operator token supplies the acting
+identity and, when minted with one, the `via` attribution marker; the body
+never does. Failures keep the shared `{kind,error,code?,progress?}` shape:
+validation is `400`, auth `403`, not-found `404`, conflict and refusal `409`,
+internal `500`. The route adds no authority of its own — it is the registry
+behind the token check — so a tool available here is exactly the tool table,
+and the table's contract suite is the single gate.
+
 ### Success results
 
 Build control returns one of:
@@ -157,8 +205,82 @@ headers with a server-minted token that expires after 30 seconds and carries
 the normalized signed-in email. Consequently every durable control event has
 the browser user's human actor while no token or signing secret reaches client
 code. Responses are private/no-store; a 401 sends the application back to sign
-in. Browser clients poll the visible dashboard every two seconds; live transcript
-streaming is not provided. Delegated bearer tokens remain server-side.
+in. Browser clients poll the visible dashboard every two seconds; the browser
+surface offers no streaming of its own — live transcript streaming remains
+absent here, and the streaming read surface is the CLI's `ab watch`, which
+polls the store's event reads client-side. Delegated bearer tokens remain
+server-side.
+
+The API does not expose phase-session commands, runner startup, a push or
+long-poll streaming transport, or a generic event-append operation; event
+streaming is composed client-side by `ab watch`, which polls the store's
+event reads.
+
+
+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
+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.
+
+Repository-following `ab watch` additionally emits a read-only `dispatcher.lost`
+observation when an observed lease expires without a matching stop. JSON carries
+`observation` instead of `event`, with run, observedAt, leaseExpiresAt and available
+identity, plus the usual repo/build/state/cursor fields. It invents no durable
+sequence or actor. Retain the cursor to avoid repeat reports across invocations.
+No lease alone is not evidence of death. SIGINT, SIGHUP and SIGTERM drain dispatch,
+record the first signal in the stop fact, and release its lease before exit.
+
+### CLI attention monitoring
+
+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.
 
-The API does not expose phase-session commands, runner startup, live streaming,
-or a generic event-append operation.
+`ab wait --for attention` is build-only and uses the same build conditions:
+an open escalation or a merge decision. Existing conditions return immediately,
+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.

package/skills/guide/references/plugin-authoring.md

@@ -40,7 +40,7 @@ should declare an API range containing `^1.5.0`.
 
 Plugin API 1.7 extends the workspace-provider factory context with the
 host-derived seams a store-requiring remote provider needs. Workspace-provider
-factories additionally receive `storeRef` and `storeToken` (guaranteed present
+factories additionally receive `storeRef` and `delegateCredential` (guaranteed present
 when the registration declares `capabilities.storeRequirements`),
 `runtimeReferences` (the host's effective runtime routes; absent at call sites
 that reference no runtimes), and the checkout-less `origin` and
@@ -125,7 +125,7 @@ Every module must default-export one strict `AutobuildPluginManifest`:
   `[tickets]` fields, workspace providers receive `[workspace.config]`, and
   runtime and forge factories currently receive an empty `config` object.
   Workspace providers additionally receive the host-derived seams (API 1.7):
-  `storeRef` and `storeToken` — guaranteed strings when the registration
+  `storeRef` and `delegateCredential` — guaranteed URL and exchange callback when the registration
   declares `capabilities.storeRequirements` — plus `runtimeReferences`,
   `origin`, and `remoteBranchHead`. Each seam is optional and absent when the
   host call site supplies no such value; absent `origin`/`remoteBranchHead`
@@ -369,3 +369,11 @@ policy says otherwise.
 Official npm references: [`package.json` fields](https://docs.npmjs.com/cli/v11/configuring-npm/package-json),
 [`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack), and
 [`npm publish`](https://docs.npmjs.com/cli/v11/commands/npm-publish).
+
+Remote workspace factories must use `delegateCredential(storeRef, undefined,
+target)` to obtain per-resource grants before provisioning or launching guests.
+The callback keeps parent authority in host composition. `storeToken` is retired
+and is never supplied; factory environments also exclude `AB_TOKEN`. Launch
+credentials travel through the separate transient execution-auth argument, never
+through serialized execution identity. Existing plugins that forwarded
+`storeToken` must migrate to this callback and fail closed if it is unavailable.