@defrex/autobuild 0.11.0 → 0.12.0

package/docs/setup.md

@@ -28,7 +28,7 @@ maintainer before selecting it:
 - a dispatcher-side push-capable `GITHUB_TOKEN` or `GH_TOKEN`;
 - for a private repository, a separate read-only clone identity named by
   `gitUsernameEnv` and `gitPasswordEnv`;
-- an HTTPS hosted `AB_STORE` reachable from Vercel and a scoped `AB_TOKEN`;
+- an HTTPS hosted service reachable from Vercel, configured through `ab connect <url>`;
 - each selected role and alternate's runtime/model, its pinned
   `[workspace.config.runtimeProvisioning.<runtime>]` commands, and the API
   credential names it needs in `[workspace.config].environmentVariables`.
@@ -177,7 +177,7 @@ ab dispatch --repository https://github.com/owner/repository \\
 ```
 
 `--repository` (or `AB_REPOSITORY`) is the normalized origin. Origin mode
-requires an HTTPS `AB_STORE` plus `AB_TOKEN`, an exported `GITHUB_TOKEN` or
+requires an HTTPS service selected through `[store] url` or `AB_STORE`, a saved project credential or `AB_TOKEN`, an exported `GITHUB_TOKEN` or
 `GH_TOKEN`, and `forge = "github"`; the interactive dashboard is unavailable
 (`--plain` or no TTY). Origin mode never consults the gh CLI: a checkout-less
 host has no gh and no keyring, and the only workspace provider it can run,
@@ -208,17 +208,34 @@ sources agree with the running system by construction:
   **running dispatcher's version** (read from the deployed distribution's
   `package.json`), so the guest runs the dispatcher's own release.
 
-The hosted remote store enforces exact **version lockstep**: every client
-request must carry an `x-autobuild-version` equal to the server's, and any
-mismatch — a guest older *or* newer than the store — is rejected with a 409
-`remote store version mismatch`. Guest, store, and dispatcher versions
-therefore cannot be mixed: a distribution fix reaches guests only after
-`tools/release.ts` cuts a release (credential-gated; requires GitHub
-credentials — a documented delivery dependency, not an automatic propagation)
-**and** the hosted store and dispatcher are upgraded to that release in the
-same lockstep window. If the release is cut but the store upgrade lags, guests
-carrying the new distribution fail loudly against the old store (409) rather
-than running silently stale.
+A service accepts stable clients from its own `major.minor` release line and
+the two preceding minor lines in the same major. A major starts a new family:
+X.0 accepts only X.0, X.1 accepts X.0/X.1, and X.2 onward accepts three lines.
+Patch versions are interchangeable in both directions and must never change
+the protocol. Upgrade the service first, then projects independently within
+its window. Supported release lines retain their wire handlers and known
+protocol identities; an unknown protocol is refused independently of version.
+Malformed, missing, and prerelease identities are refused with HTTP 409.
+A newer client is told to upgrade the service; a client below the window is
+told to upgrade the project's Autobuild. Diagnostics name the service version
+and supported range.
+
+Unauthenticated `GET /health` publishes `ok`, `autobuildVersion`,
+`protocolVersion`, and `supportedClientRange: { minVersion, maxVersionExclusive }`.
+The range is inclusive at the minimum and exclusive at the maximum; a 0.11.x
+service publishes `>=0.9.0 <0.12.0`. Health needs no credentials, version
+headers, or available backend.
+
+`ab upgrade` probes this public range before installation or project changes.
+It warns and continues when the target is outside the range, naming the
+required service upgrade for a newer target or a compatible project range for
+an older one. An unavailable or malformed probe warns that connectivity may
+fail after upgrade. Legacy health without a range means exact-version matching;
+upgrade that service to the compatibility-window release first.
+
+A distribution fix reaches origin-mode guests after a release is cut and the
+dispatcher is upgraded. Guests continue to run the dispatcher's own version;
+the hosted service must support that release line.
 
 Provisioning records the installed distribution's identity — package version
 and remote-store protocol version — in the guest's
@@ -229,10 +246,10 @@ against the identity the current system would deliver and, when they disagree
 (which includes every guest provisioned before the marker existed), refreshes
 it in place (archive re-fetched, extracted, and production-installed) first,
 so an upgraded dispatcher retrofits its existing guests instead of resuming a
-stale distribution the hosted store would reject. A refresh failure deletes
+stale distribution. A refresh failure deletes
 the sandbox so the next provisioning pass rematerializes it from scratch.
 
-After a lockstep upgrade, confirm a fix-bearing guest from the guest
+After a dispatcher upgrade, confirm a fix-bearing guest from the guest
 perspective:
 
 1. `ab build status <slug> --json` with the ambient build identity for a
@@ -250,7 +267,7 @@ apart from the identity change, `ab dispatch` behaves as it did.
 A hosted-store deployment configures its web/auth variables once — see the
 hosted service README and the complete environment reference in the pinned
 distribution checkout: `BETTER_AUTH_URL`, `AB_WEB_ALLOWED_EMAILS`,
-`AB_WEB_REPOSITORIES`, and the optional `AB_WEB_MCP_RESOURCE` — the protected
+and the optional `AB_WEB_MCP_RESOURCE` — the protected
 resource the hosted MCP server (docs/mcp.md) binds its OAuth tokens to,
 defaulting to `<BETTER_AUTH_URL>/mcp`. Set it only when a proxy or custom
 domain fronts the deployment under a different public URL than
@@ -258,6 +275,93 @@ domain fronts the deployment under a different public URL than
 production) or every MCP client's discovery binds tokens to the wrong
 resource.
 
+
+## 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.
+
+## Connected projects
+
+Migrate PostgreSQL from the pinned release before deploying (`bun run
+postgres:migrate`). The service keeps an independent, durable project registry;
+existing build or ticket data does not register a project. An administrator
+with deployment database credentials manages it without redeploying:
+
+```sh
+ab-hosted-store projects list
+ab-hosted-store projects add https://github.com/owner/project --user owner@example.com
+ab-hosted-store projects remove https://github.com/owner/project --user owner@example.com
+```
+
+From a source checkout, substitute `bun packages/hosted-store-service/src/bin.ts`
+for `ab-hosted-store`. Configure `AB_POSTGRES_URL` or `DATABASE_URL` in that
+process. Database possession grants administration; `--user` is declared audit
+attribution, not a verified login. Ordinary project/store tokens cannot manage
+registrations. Each entry records the normalized origin URL, addition time,
+and adding identity. SSH git spellings normalize to HTTPS; local paths and
+credential-bearing HTTPS URLs are rejected. Duplicate adds preserve metadata;
+remove is idempotent, and re-adding records a fresh addition.
+
+Every allowlisted signed-in user owns every registered project. The dashboard,
+MCP discovery and calls, and every operator API route consult current
+registration. Removal hides a project from all these surfaces and subsequent
+hosted dispatcher invocations; builds, events, artifacts and tickets remain,
+and re-registration restores access. Already-started work is not cancelled.
+Project credentials issued by connect authorize only their registered project. Administrative credential issuance remains available for non-interactive hosts.
+
+Link directly to `/?repo=<URL-encoded normalized origin>`. The page selects the
+first registered origin when the requested one is missing or removed, and an
+empty registry shows no project data or controls. Registry errors fail closed;
+there is no environment fallback on database failure.
+
+`AB_WEB_REPOSITORIES` is deprecated. A nonempty CSV is imported exactly once per
+database, on the first registry initialization with that variable configured,
+with actor `system:AB_WEB_REPOSITORIES`. The import and durable marker commit
+atomically across concurrent starts. An absent variable does not consume the
+marker. Later restarts or edits to the variable never re-add removed projects;
+use the owner commands for subsequent administration.
+
+The hosted dispatcher queries current registrations on every authorized
+invocation. With `AB_DISPATCHER_REPOSITORIES` unset, it serves all registered
+projects; an explicit list preserves its order and is intersected with current
+registration. An empty registry is a successful zero-project invocation.
+
 ## Authoring an agent verifier
 
 A repository-owned agent-verify skill is a verifier, not a reviewer: it drives
@@ -290,3 +394,56 @@ explanation, never a skip or silent pass. Use `skip` only when the complete step
 does not apply. If guidance still cannot make a verdict possible, escalate and
 explain what remains unresolved. Record out-of-scope work with `ab observe`;
 the verifier does not fix it.
+
+### Project-scoped hosted tickets
+
+Hosted ticket queues belong to the credential's registered repository, even
+when projects share a team key. The latest uploaded effective `[tickets]`
+configuration owns lifecycle: hosted defaults are Backlog / Doing / Done,
+`readyState` is required, `doneState` customizes completion, and create/proposal
+default to triage. The union of configured roles is allowed; roles may overlap.
+Owner admin requests require an explicit registered `context.repo`; project
+credentials cannot select another project. Missing effective configuration is
+an actionable refusal: run the project's dispatcher to publish it.
+
+The service never contacts Linear. Projects with external sources (including
+file and Linear) keep using those sources directly through their dispatcher;
+service ticket HTTP, operator and MCP surfaces refuse with project/source
+feedback rather than returning an empty queue. Removed `AB_TICKET_BACKEND` and
+`LINEAR_API_KEY` values are ignored with one startup removal message, including
+blank/unknown values. Removed `AB_TICKET_TRIAGE_STATE`, `AB_TICKET_READY_STATE`,
+`AB_TICKET_DOING_STATE` and `AB_TICKET_DONE_STATE` values are ignored even when
+malformed. None of these retired settings prevents startup.
+
+The environment-aware migration imports `AB_WEB_REPOSITORIES` once before
+ownership preflight, including released main-v9 deployments without registry
+tables. A failed migration rolls back the import, main-schema promotion and
+ticket changes together. Owner `projects add` and `tickets assign-team` commands
+bootstrap only the registry/recovery journals and work while the main marker
+is still v9. Without the retired environment, first register the intended
+project with `ab-hosted-store projects add REPOSITORY --user IDENTITY`, then
+assign the team and rerun migration. A successful one-time import is never
+reapplied from later environment edits.
+
+Ticket schema v1 migration assigns each whole legacy team to its sole claimant
+among registered projects' latest effective configs, reading their actual blob
+bytes. Projects with no dispatcher run or no effective-config reference make
+no team claim and do not block other projects. Unclaimed teams still fail closed.
+When inferring ownership, a selected configuration whose revision/blob is missing,
+unreadable or invalid stops unchanged with recovery guidance. Restore the selected
+configuration or assign every remaining legacy team explicitly; complete owner
+assignments to registered projects bypass unrelated configuration reads. Conflicts
+and asset ownership mismatches also stop unchanged. Resolve ownership, then rerun:
+
+```sh
+ab-hosted-store tickets assign-team TEAM https://github.com/acme/app --user owner@example.com
+ab-postgres-store migrate
+```
+
+The assignment journal works before v2 assertion, retains the actor, and grants
+no future cross-project access. Migration preserves ids, states, comments,
+blockers, timestamps and assets. Populated-v1 migration and deployment builds
+require the running service's blob backend, access mode, credentials and prefix
+(`AB_BLOB_PREFIX`), not just PostgreSQL access. `deploy:build` inherits this
+environment and migration failure stops Next build. Fresh databases, empty v1
+queues and v2 reruns stay SQL-only and do not initialize blob storage.

package/docs/ticket-dependencies.md

@@ -2,7 +2,7 @@
 
 `ab ticket create --blocked-by` validates prerequisite ids and records blocking
 relationships, but a single CLI command is **not an atomic publication guarantee**.
-In particular, direct Linear and hosted Linear create the issue first and add
+In particular, direct Linear creates the issue first and adds
 its blocker relationships in separate requests. If the issue is already in the
 ready state, a dispatcher can see it before those relationships exist. A
 successful create response containing every blocker does not prove that no build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Agent-driven software delivery from groomed ticket to merged PR",
   "repository": {
     "type": "git",
@@ -86,6 +86,10 @@
       "types": "./packages/core/src/operator/sandbox-host.ts",
       "import": "./packages/core/src/operator/sandbox-host.ts",
       "default": "./packages/core/src/operator/sandbox-host.ts"
+    },
+    "./connection": {
+      "types": "./packages/core/src/connection.ts",
+      "import": "./packages/core/src/connection.ts"
     }
   },
   "files": [
@@ -139,8 +143,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
-    "@defrex/autobuild-postgres-store": "0.10.1",
-    "@defrex/autobuild-vercel-sandbox": "0.10.1",
+    "@defrex/autobuild-postgres-store": "0.11.0",
+    "@defrex/autobuild-vercel-sandbox": "0.11.0",
     "@resvg/resvg-js": "2.6.2",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.0.0",
@@ -150,8 +154,5 @@
     "git-format-staged": "4.0.1",
     "husky": "9.1.7",
     "typescript": "5.9.3"
-  },
-  "patchedDependencies": {
-    "better-auth@1.4.18": "patches/better-auth@1.4.18.patch"
   }
 }

package/packages/core/src/cli/attention.ts

@@ -0,0 +1,209 @@
+import type { AbEvent } from '../events/catalog'
+import type { RepositoryEvent } from '../events/repository'
+import { currentAutoMergeDeferral } from '../kernel/auto-merge'
+import { reduceBuild, type BuildState } from '../kernel/reducer'
+
+export interface MergeDecision {
+  type: 'build.merge-decision'
+  pr: { number: number; url: string; headSha: string }
+  reason: string
+  observedAt: string
+}
+
+/** Consent pending application is armed; only a current actionable deferral
+ * or withdrawn consent needs a person. Currency is owned by the kernel. */
+export function mergeDecision(
+  events: AbEvent[],
+  now: Date,
+  state = reduceBuild(events),
+): MergeDecision | null {
+  if (
+    !state.finalizeCompletedSeq ||
+    !state.pr ||
+    state.prState !== 'open' ||
+    state.status === 'done' ||
+    state.status === 'aborted'
+  )
+    return null
+  const deferral = currentAutoMergeDeferral(events, state)
+  if (state.autoMerge.requested && deferral === undefined) return null
+  return {
+    type: 'build.merge-decision',
+    pr: state.pr,
+    reason: deferral ?? 'Auto-merge is not armed',
+    observedAt: now.toISOString(),
+  }
+}
+
+export function buildNeedsAttention(events: AbEvent[], state: BuildState): boolean {
+  return (
+    (state.openEscalations?.length ?? 0) > 0 || mergeDecision(events, new Date(0), state) !== null
+  )
+}
+
+export function mergeIdentity(slug: string, pr: number): string {
+  return JSON.stringify([slug, pr])
+}
+
+export function repositoryNeedsAttention(event: RepositoryEvent): boolean {
+  switch (event.type) {
+    case 'harvest.escalated':
+    case 'harvest.recovery-exhausted':
+    case 'dispatcher.config-rejected':
+      return true
+    case 'dispatcher.config-reloaded':
+      return event.payload.restartRequired.length > 0
+    case 'dispatcher.run-stopped':
+      return event.payload.outcome === 'abnormal'
+    default:
+      return false
+  }
+}
+
+type Degraded = Extract<RepositoryEvent, { type: 'dispatcher.ticket-source-degraded' }>
+type Failed = Extract<RepositoryEvent, { type: 'dispatcher.tick-failed' }>
+export type PersistenceObservation =
+  | {
+      type: 'dispatcher.ticket-source-persistent'
+      source: string
+      cause: string
+      message: string
+      resetAt?: string
+      episodeSeq: number
+      observedAt: string
+      dependencyLimited: boolean
+    }
+  | {
+      type: 'dispatcher.tick-failure-persistent'
+      run: string
+      firstFailure: string
+      error: string
+      episodeSeq: number
+      observedAt: string
+    }
+
+/** Incremental journal projection. Episode starts survive run anchors and
+ * repeated evidence can strengthen, but never postpone, an existing deadline. */
+export class RepositoryAttention {
+  private sources = new Map<
+    string,
+    {
+      event: Degraded
+      deadline: number
+      dependencyLimited: boolean
+      requiresRetry: boolean
+      retryObserved: boolean
+    }
+  >()
+  private failure: Failed | undefined
+  private tickStarts = new Map<string, number>()
+
+  private sourceDefersTick(now: number): boolean {
+    return [...this.sources.values()].some(
+      (source) => now < source.deadline || (source.requiresRetry && !source.retryObserved),
+    )
+  }
+
+  /** Crossing resetAt alone does not prove persistence: the dispatcher must
+   * finish a tick that could actually retry after the provider cooldown. */
+  private observeRetry(run: string): void {
+    const startedAt = this.tickStarts.get(run)
+    this.tickStarts.delete(run)
+    if (startedAt === undefined) return
+    for (const source of this.sources.values()) {
+      if (startedAt >= source.deadline) source.retryObserved = true
+    }
+  }
+  fold(event: RepositoryEvent): void {
+    switch (event.type) {
+      case 'dispatcher.ticket-source-degraded': {
+        const existing = this.sources.get(event.payload.source)
+        const deadline =
+          'resetAt' in event.payload
+            ? Date.parse(event.payload.resetAt)
+            : Date.parse(event.ts) + 15 * 60_000
+        if (existing) {
+          existing.deadline = Math.min(existing.deadline, deadline)
+          existing.requiresRetry ||= 'resetAt' in event.payload
+        } else
+          this.sources.set(event.payload.source, {
+            event,
+            deadline,
+            dependencyLimited: false,
+            requiresRetry: 'resetAt' in event.payload,
+            retryObserved: false,
+          })
+        // Cooldown-driven failures are not an independent dispatcher outage.
+        if (this.sourceDefersTick(Date.parse(event.ts))) this.failure = undefined
+        break
+      }
+      case 'dispatcher.ticket-source-dependency-limited': {
+        const source = this.sources.get(event.payload.source)
+        if (source) source.dependencyLimited = true
+        break
+      }
+      case 'dispatcher.ticket-source-recovered':
+        this.sources.delete(event.payload.source)
+        break
+      case 'dispatcher.run-started':
+        this.failure = undefined
+        this.tickStarts.clear()
+        break
+      case 'dispatcher.run-stopped':
+        this.tickStarts.delete(event.payload.run)
+        if (this.failure?.payload.run === event.payload.run) this.failure = undefined
+        break
+      case 'dispatcher.tick-started':
+        this.tickStarts.set(event.payload.run, Date.parse(event.ts))
+        break
+      case 'dispatcher.tick-completed':
+        this.observeRetry(event.payload.run)
+        if (this.failure?.payload.run === event.payload.run) this.failure = undefined
+        break
+      case 'dispatcher.tick-failed':
+        this.observeRetry(event.payload.run)
+        if (this.sourceDefersTick(Date.parse(event.ts))) this.failure = undefined
+        else if (this.failure?.payload.run !== event.payload.run) this.failure = event
+        break
+    }
+  }
+  pending(now: Date): { identity: string; observation: PersistenceObservation }[] {
+    const results: { identity: string; observation: PersistenceObservation }[] = []
+    for (const {
+      event,
+      deadline,
+      dependencyLimited,
+      requiresRetry,
+      retryObserved,
+    } of this.sources.values()) {
+      if (now.getTime() < deadline || (requiresRetry && !retryObserved)) continue
+      results.push({
+        identity: `source:${event.seq}`,
+        observation: {
+          type: 'dispatcher.ticket-source-persistent',
+          ...event.payload,
+          episodeSeq: event.seq,
+          observedAt: now.toISOString(),
+          dependencyLimited,
+        },
+      })
+    }
+    const event = this.failure
+    if (
+      event &&
+      !this.sourceDefersTick(now.getTime()) &&
+      now.getTime() >= Date.parse(event.ts) + 5 * 60_000
+    )
+      results.push({
+        identity: `tick:${event.seq}`,
+        observation: {
+          type: 'dispatcher.tick-failure-persistent',
+          ...event.payload,
+          firstFailure: event.ts,
+          episodeSeq: event.seq,
+          observedAt: now.toISOString(),
+        },
+      })
+    return results
+  }
+}

package/packages/core/src/cli/configured-store.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parse } from 'smol-toml'
+import { storeSchema } from '../config/schema'
+
+/** Store selection happens before full dispatch configuration is loaded. */
+export function configuredStore(checkout: string): string | undefined {
+  let text: string
+  try {
+    text = readFileSync(join(checkout, 'autobuild.toml'), 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+  const table = parse(text)
+  return table.store === undefined ? undefined : storeSchema.parse(table.store).url
+}