@defrex/autobuild 0.11.0 → 0.12.0

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

@@ -69,6 +69,20 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'locally. --validate cannot be combined with --force.',
     ]),
   },
+  {
+    name: 'connect',
+    audience: 'human',
+    summary: 'Connect this project to a hosted service with browser approval.',
+    detail:
+      'Usage: ab connect [url]\nWith a URL, approve the printed URL and code in your browser. Stores the credential in user configuration and adds [store] url to autobuild.toml. Without a URL, reports the saved credential status. Runs outside sessions.',
+  },
+  {
+    name: 'disconnect',
+    audience: 'human',
+    summary: 'Revoke and remove this project’s saved credential.',
+    detail:
+      'Usage: ab disconnect\nRevokes the saved credential remotely before removing it locally. Keeps project registration, data and [store] url. Runs outside sessions.',
+  },
   {
     name: 'upgrade',
     audience: 'human',
@@ -311,12 +325,23 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '                     flushed as soon as it is written.',
       '  --store <ref>      Override the BuildStore path or URL.',
       '',
-      'Default filter — the attention set. For builds: 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,',
-      'dispatcher.ticket-source-degraded, dispatcher.ticket-source-recovered.',
+      'Default filter — actionable attention only. Builds: escalation.raised and',
+      'build.merge-decision (finalized open PR, auto-merge off or currently deferred).',
+      'Armed consent awaiting application is silent; one merge decision per build/PR.',
+      'Repository: harvest.escalated, harvest.recovery-exhausted, dispatcher.config-rejected,',
+      'dispatcher.config-reloaded with restartRequired, abnormal dispatcher.run-stopped,',
+      'and dispatcher.lost. dispatcher.ticket-source-persistent reports degradation past',
+      'resetAt after a tick started at or after reset completes or fails while still degraded,',
+      'or 15 minutes without a reset; dispatcher.tick-failure-persistent reports',
+      'five minutes of continuous tick failure outside source grace or cooldown. Each episode',
+      'reports once; recovery ends it. Cooldown failures do not start the tick-failure clock.',
+      '--event replaces defaults with exactly matching catalog events (or dispatcher.lost).',
+      'Routine failures, finalize and terminal outcomes require explicit --event globs.',
+      'Derived records carry observation instead of event, with observedAt and PR/reason',
+      'or source/cause/message/resetAt or run/firstFailure/error plus episodeSeq.',
+      'Cursors suppress delivered observations, including timer-only records. Old v1',
+      'cursors remain valid. Fresh watches baseline history and retain repository timers;',
+      'reconcile existing build attention through status after arming.',
       '',
       'Record shape (--json): build (slug, or null for a repository event), repo (repository',
       'id, present only for repository events), event (the complete durable envelope: build,',
@@ -364,19 +389,23 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'Conditions (--for, repeatable): 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). An unknown value is rejected before',
+      'attention (an open escalation or a build waiting for a merge decision). Merge attention',
+      'requires a finalized open PR with auto-merge off or a current actionable gate deferral;',
+      'armed pending consent, routine outcomes and self-healing failures stay silent.',
+      'An unknown condition value is rejected before',
       'any store access. Repeatable --event globs follow the ab watch rules. Multiple --for',
       'values and --event globs are alternatives: the first one satisfied ends the wait — all',
       '--for values in supply order first (each checked against the state after an event and',
-      'the event’s attention membership), then all --event globs in supply order.',
+      'the actionable build projection), then all --event globs in supply order.',
       '',
       'A status, PR-lifecycle, or phase condition is satisfied when a targeted build’s reduction',
       'has that status, PR state, or current phase. If any targeted build already satisfies',
       'such a condition when the command starts, the command returns immediately — in the',
       'manner of kubectl wait — with that build’s latest event; --since does not suppress this.',
       'Otherwise the condition is satisfied by the first later event whose reduction produces',
-      'it. attention and --event conditions are satisfied only by events appended after the',
-      'command started (or, on a cursor-resumed backlog, after --since).',
+      'it. attention also recognizes existing conditions immediately, even with --since.',
+      '--event conditions match only events appended after the command started, or a',
+      'cursor-resumed backlog after --since; use --event to opt into other event types.',
       '',
       'Record shape (--json): the ab watch record — build, event (the complete durable',
       'envelope), state (the reduction after this event: status, phase, round, openEscalations,',

package/packages/core/src/cli/init-validation.ts

@@ -1,3 +1,5 @@
+import { projectToken } from './project-credentials'
+import { resolveRepoOrigin } from './repo-state'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
@@ -390,7 +392,31 @@ export async function validateInitReadiness(opts: {
   const configPath = join(repo, 'autobuild.toml')
   const configBytes = await readFile(configPath, 'utf8')
   const config = await loadConfig(configPath)
-  const state = resolveRepoStatePaths({ repo, envStore: opts.env.AB_STORE })
+  hostPreflight(config, opts.env)
+  const selectedRemote = opts.env.AB_STORE?.trim() || config.store?.url
+  const identity =
+    selectedRemote && isRemoteStoreRef(selectedRemote) && !opts.env.AB_TOKEN
+      ? ((await resolveRepoOrigin(repo, exec)) ?? repo)
+      : repo
+  const state = resolveRepoStatePaths({
+    repo: identity,
+    checkout: repo,
+    envStore: opts.env.AB_STORE,
+    configStore: config.store?.url,
+  })
+  opts = {
+    ...opts,
+    env: {
+      ...opts.env,
+      AB_STORE: state.storeRef,
+      ...(isRemoteStoreRef(state.storeRef)
+        ? { AB_TOKEN: projectToken(state.storeRef, identity, opts.env) }
+        : {}),
+    },
+  }
+  if (config.store?.url === state.storeRef && !opts.env.AB_TOKEN) {
+    throw new Error('No project credential for this service; run ab connect')
+  }
   // Pre-registry parse and redaction come from the builtin capability table;
   // after plugin load the registration's own declarations take over (AUT-516).
   const builtinCaps = builtinWorkspaceProviderCapabilities(config.workspace.provider)
@@ -405,7 +431,6 @@ export async function validateInitReadiness(opts: {
   let caps: WorkspaceProviderCapabilities | undefined
   let assigneeLine: string | undefined
   try {
-    hostPreflight(config, opts.env)
     // Ticket acquisition is a host responsibility for both workspace providers.
     // Exercise its read surface before allocating disposable infrastructure.
     const hostPlugins = await loadPlugins(config.plugins, repo, { packageRoot: repo })

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

@@ -1,3 +1,4 @@
+import { abConnect, abDisconnect } from './connect'
 /**
  * `ab` — the only channel between agents and the store, and the enforcement
  * point of the entire ontology (SPEC §8). This module is pure routing: every
@@ -16,7 +17,7 @@ import type { Clock } from '../store/types'
 import type { BuildStore } from '../store/types'
 import { textContent } from '../store/types'
 import type { Forge } from '../ports/types'
-import type { Exec } from '../ports/workspace/git-worktree'
+import { spawnExec, type Exec } from '../ports/workspace/git-worktree'
 import type { IdSource } from '../ids'
 import { reduceBuild } from '../kernel/reducer'
 import { artifactDownload, artifactDownloadStream, artifactGet, artifactPut } from './artifact'
@@ -44,7 +45,6 @@ import { recognizeHelpRequest, renderCommandHelp, renderTopLevelHelp } from './h
 import { observe } from './observe'
 import { abPlugin, type PluginContractSubprocess } from './plugin'
 import { preparePrAttachments } from './pr-attachments'
-import { renderPrSummary } from './pr-summary'
 import { abBuildAssetGet, abBuilds, abBuildStatus } from './status'
 import { abRepositoryStatus } from './repository-status'
 import { abWatch, WATCH_USAGE } from './watch'
@@ -53,6 +53,7 @@ import { abMcp, AB_MCP_USAGE } from './mcp'
 import type { StoreOpener } from './store-opening'
 import { done, escalate, verdict } from './terminals'
 import { abTicket, openTicketSource } from './ticket'
+import { checkUpgradeCompatibility, type CompatibilityFetch } from './upgrade-compatibility'
 import { abUpgrade, type ResolveConflict } from './upgrade'
 import { withUpgradeProgress } from './upgrade-progress'
 import {
@@ -95,6 +96,8 @@ import {
  */
 export const SESSIONLESS_COMMANDS = new Set([
   'init',
+  'connect',
+  'disconnect',
   'upgrade',
   'update',
   'ticket',
@@ -186,6 +189,7 @@ export interface SessionlessCliDeps {
    * to the running module, independent of the current repository. */
   distributionRoot?: string
   /** Self-update seams keep release/package-manager orchestration testable. */
+  compatibilityFetch?: CompatibilityFetch
   selfUpdateCommand?: SelfUpdateCommand
   selfUpdate?: (options: SelfUpdateOptions) => Promise<SelfUpdateResult>
   /** Production supplies the tool-free upgrade agent; tests inject a fake.
@@ -444,6 +448,22 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
 
     // init and upgrade run OUTSIDE build sessions (§16.3): they operate on a
     // repo, not a build, so they route before any store/env requirement.
+    case 'connect':
+    case 'disconnect': {
+      const usage = command === 'connect' ? 'usage: ab connect [url]' : 'usage: ab disconnect'
+      const parsed = parseArgs(rest, {}, usage)
+      if (parsed.positionals.length > (command === 'connect' ? 1 : 0)) throw new Error(usage)
+      const options = {
+        cwd: deps.workspacePath,
+        env: deps.processEnv ?? process.env,
+        exec: deps.exec ?? spawnExec,
+        print: stdout,
+        ...(deps.signal ? { signal: deps.signal } : {}),
+      }
+      if (command === 'connect') await abConnect(parsed.positionals[0], options)
+      else await abDisconnect(options)
+      return 0
+    }
     case 'init': {
       const usage = 'usage: ab init [target] [--force | --validate] (§16.3)'
       const removed = [
@@ -515,6 +535,14 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
       }
       const targetRepo = parsed.positionals[0] ?? deps.workspacePath
       const noCommit = parsed.flags.has('no-commit')
+      const compatibilityWarnings = new Set<string>()
+      const upgradeStderr = (line: string): void => {
+        if (line.startsWith('warning:')) {
+          if (compatibilityWarnings.has(line)) return
+          compatibilityWarnings.add(line)
+        }
+        stderr(line)
+      }
       const handoff = deps.processEnv?.[SELF_UPDATE_HANDOFF_ENV] === '1'
       let commitContext: UpgradeCommitContext | undefined
       if (!noCommit) {
@@ -543,9 +571,10 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         if (!parsed.flags.has('no-self-update') && !handoff) {
           const update = await (deps.selfUpdate ?? selfUpdate)({
             targetRepo,
+            compatibilityFetch: deps.compatibilityFetch,
             stdout,
-            stderr,
-            env: deps.processEnv ?? {},
+            stderr: upgradeStderr,
+            env: deps.processEnv ?? process.env,
             noCommit: noCommit || commitContext === undefined,
             ...(commitContext === undefined
               ? {}
@@ -559,6 +588,13 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
           if (update.kind === 'handoff') return update.exitCode
           if (update.kind === 'failed') return 1
         }
+        await checkUpgradeCompatibility({
+          targetRepo,
+          distRoot: deps.distributionRoot,
+          env: deps.processEnv,
+          stderr: upgradeStderr,
+          fetch: deps.compatibilityFetch,
+        })
         const resolverFactory = deps.upgradeResolverFactory
         let resolver: ResolveConflict | undefined
         const resolveConflict: ResolveConflict | undefined =
@@ -1314,7 +1350,7 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         const meta = await artifactPut(session, kind, file, { attach })
 
         // A designation made after the PR exists (verify after reconcile or a
-        // finalize post-step) republishes the same complete projection. Every
+        // finalize post-step) prepares hosted attachments. Every
         // external side effect is best-effort after the atomic designation.
         if (attach) {
           try {
@@ -1328,16 +1364,6 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
                 // asset identity before throwing. Keep going so its hosting
                 // failure cannot suppress the complete text projection.
               }
-              try {
-                await session.forge.commentOnPr(
-                  session.workspacePath,
-                  pr.number,
-                  renderPrSummary(session.env, await session.store.getEvents(session.env.build)),
-                )
-              } catch {
-                // The exact artifact and designation are already durable. A
-                // comment refresh cannot turn the agent's deposit into failure.
-              }
             }
           } catch {
             // Reading the optional PR projection is best-effort too.

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

@@ -107,12 +107,13 @@ export async function buildMcpTicketBackend(
         config.tickets.readyState,
         config.tickets.claimedState,
         config.tickets.createState,
+        config.tickets.doneState,
       ].filter((state): state is string => state !== undefined),
     ),
   ]
   return {
     sourceFor: async (context) => {
-      if (config.tickets.teamKey !== context.teamKey) {
+      if ((config.tickets.teamKey ?? '') !== context.teamKey) {
         throw new Error(
           `the repository's effective ticket config names team "${context.teamKey}", but this checkout's autobuild.toml names team "${String(config.tickets.teamKey)}"; refusing to serve tickets across that drift — run ab mcp from the checkout dispatch uses`,
         )
@@ -200,6 +201,11 @@ export async function abMcp(opts: AbMcpOpts): Promise<number> {
   try {
     const backend = await buildMcpTicketBackend({
       ...opts,
+      env: {
+        ...opts.env,
+        AB_STORE: context.storeRef,
+        ...(context.token !== undefined ? { AB_TOKEN: context.token } : {}),
+      },
       checkout: context.checkout,
       localStateRoot: context.localStateRoot,
     })

package/packages/core/src/cli/pr-summary-publication.ts

@@ -0,0 +1,220 @@
+import { summaryBoundary, pendingSummaryRequests } from '../kernel/pr-summary'
+export { summaryBoundary, pendingSummaryRequests } from '../kernel/pr-summary'
+import type { AbEvent } from '../events/catalog'
+import { KERNEL } from '../events/envelope'
+import { isRemoteWorkspace } from '../events/workspace-remote'
+import { reduceBuild } from '../kernel/reducer'
+import { currentPrAttachments } from '../kernel/pr-attachments'
+import { openExecution } from '../processes/execution-settlement'
+import type { Forge } from '../ports/types'
+import { githubRateLimitUntil } from '../ports/forge/github-transport'
+import { summaryMarker } from '../ports/forge/summary-marker'
+import type { BuildStore, Clock } from '../store/types'
+import { html, shellQuote, renderPrSummary } from './pr-summary'
+
+export const SUMMARY_LIMIT = 65_536
+
+interface SummaryDeps {
+  store: BuildStore
+  forge: Forge
+  slug: string
+  workspacePath: string
+  storeRef: string
+  clock: Clock
+}
+
+/** No credentials are accepted by the renderer. The full oversized projection
+ * is deliberately not designated, avoiding recursive growth. */
+export async function boundedSummary(
+  deps: SummaryDeps,
+  events: readonly AbEvent[],
+): Promise<string> {
+  const env = {
+    build: deps.slug,
+    store: deps.storeRef,
+    phase: 'finalize' as const,
+    round: 1,
+    session: '',
+  }
+  const full = renderPrSummary(env, events)
+  if (full.length <= SUMMARY_LIMIT) return full
+  const meta = await deps.store.putArtifact(deps.slug, {
+    kind: 'pr-summary',
+    content: full,
+    metadata: {},
+  })
+  const command = `ab artifact download ${shellQuote(deps.slug)} ${shellQuote(`pr-summary@${meta.revision}`)} --store ${shellQuote(deps.storeRef)} --output pr-summary.md`
+  const compact = [
+    summaryMarker(deps.slug),
+    `## Autobuild: ${html(deps.slug)}`,
+    '',
+    `The full summary exceeds the comment limit. It includes ${currentPrAttachments(events).length} PR attachments.`,
+    `Store: <code>${html(deps.storeRef)}</code>`,
+    '',
+    'Download the complete summary, including all pinned artifact commands and hosted links:',
+    `<pre><code>${html(command)}</code></pre>`,
+  ].join('\n')
+  if (compact.length > SUMMARY_LIMIT) throw new Error('Summary locator exceeds comment limit')
+  return compact
+}
+
+/** Caller owns the exclusive build lease and has fenced guest execution.
+ * Claim-before-effect plus CAS also fences overlapping refresh triggers. */
+export async function publishSummary(
+  deps: SummaryDeps,
+  boundary: { occurrence: number; boundary: number },
+): Promise<'attempted' | 'skipped' | 'deferred'> {
+  try {
+    const events = await deps.store.getEvents(deps.slug)
+    const pr = reduceBuild(events).pr
+    if (pr === undefined) return 'skipped'
+    if (
+      events.some(
+        (event) =>
+          event.type === 'pr-summary.attempted' && event.payload.occurrence === boundary.occurrence,
+      )
+    )
+      return 'attempted'
+    if (
+      events.some(
+        (event) =>
+          event.type === 'pr-summary.result' &&
+          event.payload.eligibleAfter !== undefined &&
+          Date.parse(event.payload.eligibleAfter) > deps.clock().getTime(),
+      )
+    )
+      return 'deferred'
+    const claim = await deps.store.appendIfCurrent(deps.slug, events.at(-1)?.seq ?? 0, {
+      actor: KERNEL,
+      type: 'pr-summary.attempted',
+      payload: { ...boundary, pr: pr.number },
+    })
+    if (claim === null) return 'skipped'
+    let outcome: 'success' | 'failure' | 'rate-limited' = 'success'
+    let eligibleAfter: string | undefined
+    try {
+      const body = await boundedSummary(deps, await deps.store.getEvents(deps.slug))
+      await deps.forge.commentOnPr(deps.workspacePath, pr.number, body)
+    } catch (error) {
+      eligibleAfter = githubRateLimitUntil(error, deps.clock().getTime())
+      outcome = eligibleAfter === undefined ? 'failure' : 'rate-limited'
+    }
+    await deps.store.append(deps.slug, {
+      actor: KERNEL,
+      type: 'pr-summary.result',
+      payload: {
+        attempt: claim.seq,
+        outcome,
+        ...(eligibleAfter === undefined ? {} : { eligibleAfter }),
+      },
+    })
+    return 'attempted'
+  } catch {
+    return 'skipped'
+  }
+}
+
+/** Local boundary or durable guest handoff. Optional refresh failures never
+ * prevent pipeline progress, including a failed request deposit. */
+export async function refreshSummaryBoundary(deps: SummaryDeps): Promise<boolean> {
+  try {
+    const events = await deps.store.getEvents(deps.slug)
+    const boundary = summaryBoundary(events)
+    if (boundary === undefined) return false
+    const workspace = events.findLast((event) => event.type === 'workspace.provisioned')
+    if (workspace?.type === 'workspace.provisioned' && isRemoteWorkspace(workspace.payload)) {
+      const request = events.find(
+        (event) =>
+          event.type === 'pr-summary.requested' && event.payload.occurrence === boundary.occurrence,
+      )
+      if (request !== undefined) {
+        // A lost result/disposition append must not repeatedly park a guest.
+        if (
+          events.some(
+            (event) =>
+              event.type === 'pr-summary.attempted' &&
+              event.payload.occurrence === boundary.occurrence,
+          )
+        )
+          return false
+        if (
+          events.some(
+            (event) =>
+              event.type === 'pr-summary.result' &&
+              event.payload.eligibleAfter !== undefined &&
+              Date.parse(event.payload.eligibleAfter) > deps.clock().getTime(),
+          )
+        )
+          return false
+        return pendingSummaryRequests(events).some((event) => event.seq === request.seq)
+      }
+      if (
+        reduceBuild(events).pr === undefined &&
+        !events.some(
+          (event) =>
+            event.type === 'publication.requested' && event.payload.operation === 'finalize',
+        )
+      )
+        return false
+      const written = await deps.store.appendIfCurrent(deps.slug, events.at(-1)?.seq ?? 0, {
+        actor: KERNEL,
+        type: 'pr-summary.requested',
+        payload: boundary,
+      })
+      return written !== null
+    }
+    await publishSummary(deps, boundary)
+  } catch {
+    /* Optional publication cannot fail phase execution. */
+  }
+  return false
+}
+
+/** Host-only, after execution settlement. Reuse a launch reservation only
+ * before execution.start; otherwise acquire and release our own lease. */
+export async function settleSummaryRequests(
+  deps: SummaryDeps & { holder: string; reservation?: string },
+): Promise<void> {
+  let acquired = false
+  let heartbeat: ReturnType<typeof setInterval> | undefined
+  try {
+    let events = await deps.store.getEvents(deps.slug)
+    if (openExecution(events) !== null) return
+    // Repair a crash after terminal/session completion but before guest handoff.
+    const workspace = events.findLast((event) => event.type === 'workspace.provisioned')
+    if (workspace?.type !== 'workspace.provisioned' || !isRemoteWorkspace(workspace.payload)) return
+    const holder = deps.reservation ?? deps.holder
+    acquired = await deps.store.claimLease(deps.slug, holder, 60_000)
+    if (!acquired) return
+    heartbeat = setInterval(() => {
+      void deps.store.heartbeat(deps.slug, holder).catch(() => {})
+    }, 15_000)
+    events = await deps.store.getEvents(deps.slug)
+    if (openExecution(events) !== null) return
+    await refreshSummaryBoundary(deps)
+    events = await deps.store.getEvents(deps.slug)
+    const requests = pendingSummaryRequests(events)
+    const latest = requests.at(-1)
+    for (const request of requests) {
+      if (request.type !== 'pr-summary.requested') continue
+      const disposition =
+        request === latest ? await publishSummary(deps, request.payload) : 'skipped'
+      await deps.store.append(deps.slug, {
+        actor: KERNEL,
+        type: 'pr-summary.settled',
+        payload: { request: request.seq, disposition },
+      })
+    }
+  } catch {
+    /* Best effort, separate from branch publication and phase outcome. */
+  } finally {
+    if (heartbeat !== undefined) clearInterval(heartbeat)
+    if (acquired && deps.reservation === undefined) {
+      try {
+        await deps.store.releaseLease(deps.slug, deps.holder)
+      } catch {
+        /* lease expires */
+      }
+    }
+  }
+}

package/packages/core/src/cli/pr-summary.ts

@@ -1,3 +1,4 @@
+import { summaryMarker } from '../ports/forge/summary-marker'
 import type { AbEvent } from '../events/catalog'
 import {
   currentPrAttachments,
@@ -106,6 +107,7 @@ export function renderPrSummary(env: CliEnv, events: readonly AbEvent[]): string
   }
 
   return [
+    summaryMarker(env.build),
     `## Autobuild: ${html(env.build)}`,
     '',
     '### Verdict history',

package/packages/core/src/cli/project-credentials.ts

@@ -0,0 +1,132 @@
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  constants,
+  fstatSync,
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  closeSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { normalizeServiceURL } from '../connection'
+import { normalizeGitRemoteUrl } from '../kernel/origin'
+
+export interface ProjectCredential {
+  service: string
+  repo: string
+  id: string
+  token: string
+}
+export class ProjectCredentials {
+  readonly directory: string
+  constructor(env: Record<string, string | undefined> = process.env) {
+    const root = env.XDG_CONFIG_HOME
+    if (root && !isAbsolute(root))
+      throw new Error('XDG_CONFIG_HOME must be absolute for project credentials')
+    this.directory = join(
+      root ||
+        (env.HOME && isAbsolute(env.HOME) ? join(env.HOME, '.config') : join(homedir(), '.config')),
+      'autobuild',
+      'credentials',
+    )
+  }
+  private path(service: string, repo: string): string {
+    return join(
+      this.directory,
+      `${createHash('sha256')
+        .update(JSON.stringify([normalizeServiceURL(service), normalizeGitRemoteUrl(repo)]))
+        .digest('hex')}.json`,
+    )
+  }
+  private guard(path: string): boolean {
+    try {
+      const info = lstatSync(path)
+      if (!info.isFile() || info.isSymbolicLink()) throw new Error('unsafe credential file')
+      return true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+      throw error
+    }
+  }
+  load(service: string, repo: string): ProjectCredential | undefined {
+    try {
+      const path = this.path(service, repo)
+      if (!this.guard(path)) return undefined
+      const directory = lstatSync(this.directory)
+      if (directory.isSymbolicLink() || (directory.mode & 0o777) !== 0o700) throw new Error()
+      const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+      let entry: ProjectCredential
+      try {
+        if ((fstatSync(fd).mode & 0o777) !== 0o600) throw new Error()
+        entry = JSON.parse(readFileSync(fd, 'utf8'))
+      } finally {
+        closeSync(fd)
+      }
+      if (
+        entry.service !== normalizeServiceURL(service) ||
+        entry.repo !== normalizeGitRemoteUrl(repo) ||
+        typeof entry.id !== 'string' ||
+        typeof entry.token !== 'string' ||
+        !/^[a-f0-9]{32}$/.test(entry.id) ||
+        !new RegExp(`^abp_1_${entry.id}_[a-f0-9]{64}$`).test(entry.token)
+      )
+        throw new Error()
+      return entry
+    } catch {
+      throw new Error(
+        'Cannot read project credential; repair user credential storage and run ab connect',
+      )
+    }
+  }
+  save(entry: ProjectCredential): void {
+    const path = this.path(entry.service, entry.repo)
+    let temporary: string | undefined
+    try {
+      mkdirSync(this.directory, { recursive: true, mode: 0o700 })
+      if (lstatSync(this.directory).isSymbolicLink()) throw new Error()
+      chmodSync(this.directory, 0o700)
+      this.guard(path)
+      temporary = `${path}.${randomUUID()}`
+      const fd = openSync(temporary, 'wx', 0o600)
+      try {
+        writeFileSync(fd, `${JSON.stringify(entry)}\n`)
+      } finally {
+        closeSync(fd)
+      }
+      renameSync(temporary, path)
+    } catch {
+      throw new Error('Cannot save project credential; check user credential directory permissions')
+    } finally {
+      if (temporary) {
+        try {
+          unlinkSync(temporary)
+        } catch {
+          /* renamed or absent */
+        }
+      }
+    }
+  }
+  remove(service: string, repo: string): void {
+    const path = this.path(service, repo)
+    if (this.guard(path)) unlinkSync(path)
+  }
+}
+export function projectToken(
+  service: string,
+  repo: string,
+  env: Record<string, string | undefined>,
+): string | undefined {
+  if (env.AB_TOKEN !== undefined && env.AB_TOKEN !== '') return env.AB_TOKEN
+  try {
+    normalizeServiceURL(service)
+  } catch {
+    return undefined
+  }
+  return new ProjectCredentials(env).load(service, repo)?.token
+}