@defrex/autobuild 0.11.0 → 0.13.0

package/packages/core/src/ports/tickets/portable-assets.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { validateTicketAssetInput, type TicketAssetInput } from '../../store/ticket-assets'
+
+export const portableAssetSchema = z
+  .strictObject({
+    kind: z.string(),
+    name: z.string(),
+    layout: z.enum(['file', 'tree']),
+    entries: z.array(
+      z.discriminatedUnion('type', [
+        z.strictObject({ type: z.literal('dir'), path: z.string() }),
+        z.strictObject({
+          type: z.literal('file'),
+          path: z.string(),
+          base64: z
+            .string()
+            .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/),
+        }),
+      ]),
+    ),
+  })
+  .superRefine((value, ctx) => {
+    try {
+      validateTicketAssetInput(decodePortableAsset(value))
+    } catch (error) {
+      ctx.addIssue({ code: 'custom', message: String(error) })
+    }
+  })
+export type PortableAsset = z.infer<typeof portableAssetSchema>
+export function decodePortableAsset(value: PortableAsset): TicketAssetInput {
+  return {
+    kind: value.kind,
+    name: value.name,
+    layout: value.layout,
+    entries: value.entries.map((entry) =>
+      entry.type === 'dir'
+        ? entry
+        : { type: 'file', path: entry.path, content: Buffer.from(entry.base64, 'base64') },
+    ),
+  }
+}
+export function encodePortableAsset(input: TicketAssetInput): PortableAsset {
+  validateTicketAssetInput(input)
+  return {
+    kind: input.kind,
+    name: input.name,
+    layout: input.layout,
+    entries: input.entries.map((entry) =>
+      entry.type === 'dir'
+        ? entry
+        : { type: 'file', path: entry.path, base64: Buffer.from(entry.content).toString('base64') },
+    ),
+  }
+}

package/packages/core/src/ports/tickets/remote-protocol.ts

@@ -1,16 +1,33 @@
 import { z } from 'zod'
 import { ticketRefSchema } from '../../ontology'
 
+/** Explicit opt-in: released clients through 0.12 use strict decoders without revisions.
+ * Source checkouts can share their release version, so version alone is insufficient. */
+export const TICKET_REVISIONS_HEADER = 'x-autobuild-ticket-revisions'
+export const TICKET_REVISIONS_CAPABILITY = '1'
+
 /** Repository-owned policy sent with every hosted ticket operation. */
 export const hostedTicketContextSchema = z.strictObject({
   teamKey: z.string().min(1),
+  repo: z.string().min(1).optional(),
   claimedState: z.string().min(1).optional(),
   createState: z.string().min(1).optional(),
 })
 export type HostedTicketContext = z.infer<typeof hostedTicketContextSchema>
 
+export const TICKET_COMMENTS_HEADER = 'x-autobuild-ticket-comments'
+export const TICKET_COMMENTS_CAPABILITY = '1'
+
+export const ticketCommentWireSchema = z.strictObject({
+  body: z.string(),
+  createdAt: z.string(),
+  author: z.string().optional(),
+})
+
 export const ticketWireSchema = z.strictObject({
+  revision: z.string().min(1),
   ref: ticketRefSchema,
+  comments: z.array(ticketCommentWireSchema).optional(),
   creationKey: z.string().optional(),
   title: z.string(),
   body: z.string(),
@@ -46,6 +63,7 @@ const draftSchema = z.strictObject({
   blockedBy: z.array(z.string()).optional(),
 })
 const createOptionsSchema = z.strictObject({
+  requestedId: z.string().min(1).optional(),
   state: z.string().optional(),
   idempotencyKey: z.string().optional(),
 })
@@ -61,8 +79,27 @@ function envelope<T extends z.ZodType>(input: T) {
   return z.strictObject({ context: hostedTicketContextSchema, input })
 }
 
+const mutationSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('update'), patch: updateSchema }),
+  z.strictObject({ kind: z.literal('transition'), state: z.string().min(1) }),
+  z.strictObject({
+    kind: z.literal('blockers'),
+    operation: z.enum(['block', 'unblock']),
+    ids: z.array(z.string().min(1)),
+  }),
+])
+
 export const hostedTicketRequestSchemas = {
+  'mutate-if-revision': envelope(
+    z.strictObject({
+      id: z.string().min(1),
+      expectedRevision: z.string().refine((v) => v.trim().length > 0),
+      mutation: mutationSchema,
+    }),
+  ),
   'list-ready': envelope(criteriaSchema),
+  states: envelope(z.strictObject({})),
+  'add-state': envelope(z.strictObject({ name: z.string(), about: z.string().optional() })),
   get: envelope(idSchema),
   claim: envelope(idSchema),
   comment: envelope(z.strictObject({ id: z.string().min(1), body: z.string() })),
@@ -80,3 +117,62 @@ export type HostedTicketOperation = keyof typeof hostedTicketRequestSchemas
 export const HOSTED_TICKET_OPERATIONS = Object.keys(
   hostedTicketRequestSchemas,
 ) as HostedTicketOperation[]
+
+/** Project policy is separate from CRUD context and cannot be supplied by delegates. */
+export const hostedTicketPolicySchema = z.strictObject({
+  version: z.literal(1),
+  tickets: z.strictObject({
+    source: z.literal('hosted'),
+    teamKey: z.string().min(1),
+    readyState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    triageState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    claimedState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    doneState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    createState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    proposalState: z
+      .string()
+      .min(1)
+      .refine((value) => value.trim().length > 0, 'state must be nonblank'),
+    readyLabels: z.array(z.string().min(1)).optional(),
+  }),
+})
+export type HostedTicketPolicy = z.infer<typeof hostedTicketPolicySchema>
+
+export const ticketGrantSchema = z.strictObject({
+  id: z.string().min(1),
+  repo: z.string().min(1),
+  execution: z.string().min(1),
+  kind: z.enum(['runner', 'phase']),
+  parent: z.string().nullable(),
+  expiresAt: z.string().datetime(),
+})
+export const ticketGrantResponseSchema = z.strictObject({
+  token: z.string().startsWith('abt_'),
+  grant: ticketGrantSchema,
+})
+
+export const ticketStateWireSchema = z.strictObject({
+  name: z.string(),
+  tickets: z.number().int().nonnegative(),
+  about: z.string().optional(),
+})
+export const ticketStatesWireSchema = z.array(ticketStateWireSchema)
+export const ticketStateCreateWireSchema = z.strictObject({
+  state: ticketStateWireSchema,
+  created: z.boolean(),
+})

package/packages/core/src/ports/tickets/remote.ts

@@ -1,3 +1,5 @@
+import { hostedRequestedIds } from './requested-id'
+import { TicketRevisionConflict } from './revision'
 import type {
   DependencyState,
   Ticket,
@@ -6,16 +8,25 @@ import type {
   TicketListing,
   TicketSource,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
-import { AuthError } from '../../store/remote/client'
+import { RemoteBuildStore, AuthError } from '../../store/remote/client'
 import { errorBodySchema } from '../../store/remote/protocol'
 import {
   claimWireSchema,
+  TICKET_REVISIONS_HEADER,
+  TICKET_REVISIONS_CAPABILITY,
+  hostedTicketPolicySchema,
+  type HostedTicketPolicy,
+  TICKET_COMMENTS_HEADER,
+  TICKET_COMMENTS_CAPABILITY,
   dependencyStatesWireSchema,
   type HostedTicketContext,
   successWireSchema,
   ticketListingWireSchema,
   ticketWireSchema,
+  ticketStatesWireSchema,
+  ticketStateCreateWireSchema,
 } from './remote-protocol'
 import {
   AUTOBUILD_VERSION,
@@ -38,22 +49,42 @@ export interface HostedTicketSourceOptions extends HostedTicketContext {
 /** Full TicketSource client for a hosted Autobuild service. */
 export class HostedTicketSource implements TicketSource {
   readonly name = 'hosted'
+  readonly requestedIds: ReturnType<typeof hostedRequestedIds>
+  readonly assets: import('../types').TicketAssetStore
   private readonly base: string
   private readonly token: string
   private readonly fetchFn: HostedTicketFetch
   private readonly context: HostedTicketContext
 
   constructor(options: HostedTicketSourceOptions) {
+    this.requestedIds = hostedRequestedIds(options.teamKey)
+    const client = new RemoteBuildStore({
+      url: options.url,
+      token: options.token,
+      ...(options.fetchFn ? { fetchFn: options.fetchFn as typeof fetch } : {}),
+    })
+    this.assets = {
+      ticketAssetLimits: client.ticketAssetLimits.bind(client),
+      putTicketAsset: client.putTicketAsset.bind(client),
+      getTicketAsset: client.getTicketAsset.bind(client),
+      listTicketAssets: client.listTicketAssets.bind(client),
+      removeTicketAsset: client.removeTicketAsset.bind(client),
+    }
     this.base = options.url.replace(/\/+$/, '')
     this.token = options.token
     this.fetchFn = options.fetchFn ?? fetch
     this.context = {
       teamKey: options.teamKey,
+      ...(options.repo !== undefined ? { repo: options.repo } : {}),
       ...(options.claimedState !== undefined ? { claimedState: options.claimedState } : {}),
       ...(options.createState !== undefined ? { createState: options.createState } : {}),
     }
   }
 
+  async synchronizePolicy(policy: HostedTicketPolicy): Promise<void> {
+    await this.request('policy', hostedTicketPolicySchema.parse(policy), successWireSchema)
+  }
+
   private project(ticket: Ticket): Ticket {
     return { ...ticket, ref: { ...ticket.ref, source: this.name } }
   }
@@ -67,7 +98,9 @@ export class HostedTicketSource implements TicketSource {
       method: 'POST',
       headers: {
         'content-type': 'application/json',
+        [TICKET_COMMENTS_HEADER]: TICKET_COMMENTS_CAPABILITY,
         authorization: `Bearer ${this.token}`,
+        [TICKET_REVISIONS_HEADER]: TICKET_REVISIONS_CAPABILITY,
         [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
         [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
       },
@@ -76,8 +109,17 @@ export class HostedTicketSource implements TicketSource {
     if (!response.ok) {
       let message = `ticket service responded ${response.status}`
       try {
-        message = errorBodySchema.parse(await response.json()).error
-      } catch {
+        const body = (await response.json()) as Record<string, unknown>
+        if (
+          response.status === 409 &&
+          typeof body.currentRevision === 'string' &&
+          typeof body.expectedRevision === 'string' &&
+          typeof body.id === 'string'
+        )
+          throw new TicketRevisionConflict(body.id, body.expectedRevision, body.currentRevision)
+        message = errorBodySchema.parse(body).error
+      } catch (error) {
+        if (error instanceof TicketRevisionConflict) throw error
         // Keep the status-only safe fallback for non-protocol responses.
       }
       if (response.status === 401 || response.status === 403) throw new AuthError(message)
@@ -98,6 +140,14 @@ export class HostedTicketSource implements TicketSource {
     return { ...listing, tickets: listing.tickets.map((ticket) => this.project(ticket)) }
   }
 
+  async listStates() {
+    return this.request('states', {}, ticketStatesWireSchema)
+  }
+
+  async addState(name: string, opts: { about?: string } = {}) {
+    return this.request('add-state', { name, ...opts }, ticketStateCreateWireSchema)
+  }
+
   async get(id: string): Promise<Ticket | null> {
     const ticket = await this.request('get', { id }, ticketWireSchema.nullable())
     return ticket === null ? null : this.project(ticket)
@@ -119,6 +169,14 @@ export class HostedTicketSource implements TicketSource {
     return this.project(await this.request('create', { draft, options }, ticketWireSchema))
   }
 
+  async mutateIfRevision(
+    id: string,
+    expectedRevision: string,
+    mutation: TicketMutation,
+  ): Promise<void> {
+    await this.request('mutate-if-revision', { id, expectedRevision, mutation }, successWireSchema)
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     await this.request('update', { id, patch }, successWireSchema)
   }

package/packages/core/src/ports/tickets/requested-id.ts

@@ -0,0 +1,46 @@
+/** Requested-id policies shared by adapter writes and migration preflight. */
+export interface RequestedIdPolicy {
+  preserve(id: string): string | undefined
+  allocate(occupied: string[]): string
+}
+
+export function validateFileTicketId(id: string): string {
+  if (!id || id === '.' || /[/\\\0]/.test(id) || id.includes('..'))
+    throw new Error(`file ticket source: invalid ticket id "${id}"`)
+  return id
+}
+
+export const fileRequestedIds: RequestedIdPolicy = {
+  preserve: validateFileTicketId,
+  allocate(occupied) {
+    let n = 1
+    while (occupied.includes(`file-${n}`)) n++
+    return `file-${n}`
+  },
+}
+
+export const MAX_TICKET_NUMBER = 9223372036854775807n
+export function hostedRequestedIds(teamKey: string): RequestedIdPolicy {
+  const numberOf = (id: string): bigint | undefined => {
+    if (!id.startsWith(`${teamKey}-`)) return undefined
+    const suffix = id.slice(teamKey.length + 1)
+    if (!/^[1-9][0-9]*$/.test(suffix)) return undefined
+    const n = BigInt(suffix)
+    if (n > MAX_TICKET_NUMBER) throw new Error(`ticket number exceeds PostgreSQL bigint: ${id}`)
+    return n
+  }
+  return {
+    preserve(id) {
+      return numberOf(id) === undefined ? undefined : id
+    },
+    allocate(occupied) {
+      let max = 0n
+      for (const id of occupied) {
+        const n = numberOf(id)
+        if (n !== undefined && n > max) max = n
+      }
+      if (max === MAX_TICKET_NUMBER) throw new Error('ticket numbers exhausted')
+      return `${teamKey}-${max + 1n}`
+    },
+  }
+}

package/packages/core/src/ports/tickets/revision.ts

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto'
+import type { Ticket, TicketMutation, TicketSource } from '../types'
+
+/** Content versions intentionally return to the same value after an exact revert. */
+export function ticketRevision(
+  ticket: Pick<Ticket, 'title' | 'body' | 'labels' | 'state' | 'blockedBy'> & {
+    comments?: Ticket['comments']
+    attachments?: unknown
+  },
+): string {
+  return createHash('sha256')
+    .update(
+      JSON.stringify([
+        ticket.title,
+        ticket.body,
+        [...new Set(ticket.labels)].sort(),
+        ticket.state ?? null,
+        [...new Set(ticket.blockedBy ?? [])].sort(),
+        ...(ticket.comments !== undefined || ticket.attachments !== undefined
+          ? [ticket.comments ?? null, ticket.attachments ?? null]
+          : []),
+      ]),
+    )
+    .digest('hex')
+}
+
+export class TicketRevisionConflict extends Error {
+  constructor(
+    readonly id: string,
+    readonly expectedRevision: string,
+    readonly currentRevision: string,
+  ) {
+    super(
+      `ticket "${id}" changed: expected revision ${expectedRevision}, current revision ${currentRevision}`,
+    )
+    this.name = 'TicketRevisionConflict'
+  }
+}
+
+export class TicketRevisionUnsupported extends Error {
+  constructor(source: string) {
+    super(`${source} ticket source does not support revision-checked writes`)
+    this.name = 'TicketRevisionUnsupported'
+  }
+}
+
+export function checkTicketRevision(ticket: Ticket, expected: string): void {
+  if (!expected.trim()) throw new Error('expected revision must be nonblank')
+  if (ticket.revision !== expected)
+    throw new TicketRevisionConflict(ticket.ref.id, expected, ticket.revision)
+}
+
+export async function mutateTicketIfRevision(
+  source: TicketSource,
+  id: string,
+  expected: string,
+  mutation: TicketMutation,
+): Promise<void> {
+  if (!expected.trim()) throw new Error('expected revision must be nonblank')
+  if (!source.mutateIfRevision) throw new TicketRevisionUnsupported(source.name)
+  await source.mutateIfRevision(id, expected, mutation)
+}

package/packages/core/src/ports/tickets/states.ts

@@ -0,0 +1,61 @@
+/** Shared state rules; configured names are deliberately not create-validated. */
+export const STATE_NAME_RULE =
+  'a state name is one to forty characters of lowercase letters, digits, and hyphens, starting with a letter'
+
+export function validateStateName(name: string, source = 'file ticket source'): void {
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(name)) {
+    throw new Error(`${source}: invalid state name "${name}" — ${STATE_NAME_RULE}`)
+  }
+}
+
+export function validateStatePurpose(
+  value: string | undefined,
+  source = 'file ticket source',
+): string | undefined {
+  const about = value?.trim()
+  if (about !== undefined && (about === '' || /[\r\n]/.test(about))) {
+    throw new Error(`${source}: a state purpose must be one nonblank line`)
+  }
+  return about
+}
+
+export function orderStates(names: string[], lifecycle: readonly string[]): string[] {
+  const first = [...new Set(lifecycle)].filter((name) => names.includes(name))
+  return [...first, ...names.filter((name) => !first.includes(name)).sort()]
+}
+
+export function resolveState(
+  name: string,
+  existing: string[],
+  source = 'file ticket source',
+): string {
+  if (existing.includes(name)) return name
+  const matches = existing.filter((s) => s.toLowerCase() === name.toLowerCase())
+  if (matches.length === 1) return matches[0] as string
+  const directories = source === 'file ticket source'
+  if (matches.length > 1) {
+    throw new Error(
+      `${source}: ambiguous state "${name}" — it matches the ${directories ? 'directories' : 'states'} ${matches.join(', ')}`,
+    )
+  }
+  throw new Error(
+    `${source}: unknown state "${name}" — this tracker's states are ${directories ? 'the directories: ' : ''}${existing.join(', ')}`,
+  )
+}
+
+/** Portable directory vocabulary, without guessing lifecycle roles. */
+export function normalizeStateName(name: string): string {
+  if (/^[a-z][a-z0-9-]{0,39}$/.test(name)) return name
+  const candidate = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+  try {
+    validateStateName(candidate)
+  } catch {
+    throw new Error(`invalid state "${name}" (normalized: "${candidate}")`)
+  }
+  return candidate
+}

package/packages/core/src/ports/types.ts

@@ -1,3 +1,4 @@
+import type { BuildStore } from '../store/types'
 /**
  * Ports (SPEC §3.2): interfaces to the world, each with swappable adapters.
  * The kernel and processes depend only on these types; adapters live in
@@ -49,7 +50,19 @@ export interface SessionStreamSink extends SessionStreamEmitter {
 // never consulted mid-build and never used as artifact storage. A file-based
 // adapter with nowhere to put blobs must be fully workable.
 
+/** A recorded comment, with its exact body and source timestamp. */
+export interface TicketComment {
+  body: string
+  createdAt: string
+  author?: string
+}
+
 export interface Ticket {
+  /** Opaque source version of title, body, labels, state and blockers. */
+  revision: string
+  /** Complete history oldest first when exposed by this read. Absent means
+   * unsupported; an empty array means no comments. Bodies are unchanged. */
+  comments?: TicketComment[]
   ref: TicketRef
   /** Stable source-native key used to correlate an externally created ticket
    * with Autobuild's durable creation reservation. It is separate from the
@@ -106,6 +119,8 @@ export interface DependencyState {
 }
 
 export interface TicketCreateOptions {
+  /** Requested source id. Unsupported adapters must reject it. */
+  requestedId?: string
   /** Explicit workflow state for this create (harvest always targets Triage). */
   state?: string
   /** Source-level adoption key for crash-safe external creation. File and fake
@@ -148,7 +163,29 @@ export class TicketSourceRateLimitError extends Error {
   }
 }
 
+export type TicketAssetStore = {
+  /** Native ownership, including tombstones, prevents resurrection from legacy stores. */
+  hasTicketAssetHistory?(repo: string, id: string, kind: string, name: string): Promise<boolean>
+} & Pick<
+  BuildStore,
+  | 'ticketAssetLimits'
+  | 'putTicketAsset'
+  | 'getTicketAsset'
+  | 'listTicketAssets'
+  | 'removeTicketAsset'
+>
+
+export type TicketMutation =
+  | { kind: 'update'; patch: TicketUpdate }
+  | { kind: 'transition'; state: string }
+  | { kind: 'blockers'; operation: 'block' | 'unblock'; ids: string[] }
+
 export interface TicketSource {
+  /** Import support: the same pure id policy used by create, for mutation-free preflight. */
+  readonly requestedIds?: import('./tickets/requested-id').RequestedIdPolicy
+  readonly assets?: TicketAssetStore
+  /** Check and mutate at the source boundary; absent means checks are unsupported. */
+  mutateIfRevision?(id: string, expectedRevision: string, mutation: TicketMutation): Promise<void>
   readonly name: string
   /** Ready tickets matching the dispatch criteria (label/state — §3.3), plus
    * actionable diagnostics for individual source records excluded as invalid.
@@ -193,9 +230,9 @@ export interface TicketSource {
    */
   listStates?(): Promise<TicketStateInfo[]>
   /**
-   * Optional state creation (`ab ticket state create`). Idempotent: an existing
-   * state is reported with `created: false`, and a supplied `about` replaces its
-   * purpose. Rejects a malformed or case-colliding name without creating anything.
+   * Optional state creation (`ab ticket state create`). Duplicate policy is
+   * adapter-specific: file creation is idempotent and can replace purpose;
+   * hosted creation refuses existing names in any case. Rejects malformed names.
    * Named `addState` because adapters already hold a `createState` option field.
    */
   addState?(

package/packages/core/src/ports/workspace/build-execution.ts

@@ -114,8 +114,13 @@ export type ExecutionObservation =
  * provider may implement this by starting the fixed build process beside its
  * checkout; the kernel need not know where that is. Every provider owns full
  * teardown of the environment and descendants it starts before completion. */
+export interface ExecutionLaunchAuth {
+  token: string
+  tickets?: { url: string; token: string }
+}
+
 export interface BuildExecution {
-  start(input: BuildExecutionStart): Promise<BuildExecutionHandle>
+  start(input: BuildExecutionStart, auth?: ExecutionLaunchAuth): Promise<BuildExecutionHandle>
   /** Optional liveness observation of a previously recorded execution, from
    * provider state alone. Absent = this provider cannot observe; callers
    * supervise exactly as before ("cannot observe" never means "act"). */

package/packages/core/src/ports/workspace/create.ts

@@ -1,3 +1,4 @@
+import { delegateCredential } from '../../store/remote/credentials'
 import { resolve } from 'node:path'
 import { SANDBOX_FORBIDDEN_ENV } from './operator-sandbox'
 import type { WorkspaceConfig } from '../../config/schema'
@@ -131,10 +132,22 @@ export async function createWorkspaceProvider(
     // receives through `opts` reach the plugin factory through the context.
     return await factory({
       config: config.config,
-      env: opts.env,
+      env: Object.fromEntries(
+        Object.entries(opts.env).filter(
+          ([key]) => !['AB_TOKEN', 'AB_TICKET_TOKEN', 'AB_TICKET_URL'].includes(key),
+        ),
+      ),
       repoRoot: resolve(opts.repoRoot),
       ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
-      ...(opts.storeToken !== undefined ? { storeToken: opts.storeToken } : {}),
+      ...(opts.storeRef !== undefined && opts.storeToken !== undefined
+        ? {
+            delegateCredential: (
+              _ref: string,
+              _token: string | undefined,
+              target: Parameters<typeof delegateCredential>[2],
+            ) => delegateCredential(opts.storeRef!, opts.storeToken, target),
+          }
+        : {}),
       ...(opts.runtimeReferences !== undefined
         ? { runtimeReferences: opts.runtimeReferences }
         : {}),

package/packages/core/src/ports/workspace/distribution-archive.ts

@@ -18,11 +18,9 @@
  * version in both modes: origin mode's release-asset tag is the running
  * version by construction, and source mode packs `distributionRoot()`, whose
  * package.json is the same file `readDistributionIdentity()` reads. The hosted
- * remote store enforces exact version lockstep — a client whose
- * `x-autobuild-version` or `x-autobuild-protocol-version` differs from the
- * server's is rejected (409) — so guest, store, and dispatcher versions must
- * move together through a release cut (`tools/release.ts`) plus
- * store/dispatcher upgrades; there is no code path that safely mixes versions.
+ * remote store accepts only its published client release-line window and known
+ * protocol identities (409 outside that contract). Upgrade the service before
+ * a dispatcher moves beyond its window; projects can then upgrade independently.
  * Provisioning records the installed distribution's identity stamp
  * (`readDistributionIdentityStamp()`) in the guest's `.distribution-version`
  * marker and reinstalls the archive on a later mismatch, so an upgraded

package/packages/core/src/ports/workspace/harvest-execution.ts

@@ -2,6 +2,7 @@ import type {
   BuildExecutionHandle,
   BuildExecutionIdentity,
   ExecutionObservation,
+  ExecutionLaunchAuth,
 } from './build-execution'
 
 /** Guest environment variable carrying the serialized harvest launch
@@ -23,6 +24,7 @@ export interface HarvestExecutionEnvironment {
  * advisory. Run state, config, and outcomes are obtained only through the
  * repository journal in the Store. */
 export interface HarvestExecutionStart {
+  preparedRun?: { run: string }
   storeRef: string
   /** Repository identity (normalized origin) the guest serves. */
   repo: string
@@ -101,7 +103,7 @@ export function parseHarvestRunnerLaunch(value: unknown): HarvestRunnerLaunch |
  * observation types so supervision semantics (long-poll wait, teardown
  * outcome, provider liveness) are identical to builds. */
 export interface HarvestExecution {
-  start(input: HarvestExecutionStart): Promise<BuildExecutionHandle>
+  start(input: HarvestExecutionStart, auth?: ExecutionLaunchAuth): Promise<BuildExecutionHandle>
   /** Optional liveness observation of a previously recorded execution, from
    * provider state alone. Absent = this provider cannot observe; callers
    * supervise exactly as before ("cannot observe" never means "act"). */

package/packages/core/src/ports/workspace/local-build-execution.ts

@@ -8,6 +8,7 @@ import type {
   BuildExecutionExit,
   BuildExecutionHandle,
   BuildExecutionStart,
+  ExecutionLaunchAuth,
 } from './build-execution'
 
 export const BUILD_RUNNER_OPTIONS_ENV = 'AB_BUILD_RUNNER_OPTIONS'
@@ -34,10 +35,16 @@ export class LocalBuildExecution implements BuildExecution {
     this.spawn = opts.spawn ?? Bun.spawn
   }
 
-  async start(input: BuildExecutionStart): Promise<BuildExecutionHandle> {
+  async start(
+    input: BuildExecutionStart,
+    auth?: ExecutionLaunchAuth,
+  ): Promise<BuildExecutionHandle> {
+    if (/^https?:/i.test(input.storeRef) && !auth)
+      throw new Error('remote build launch requires delegated authority')
     const child = this.spawn([process.execPath, this.entrypoint], {
       env: {
         ...this.env,
+        AB_TOKEN: auth?.token,
         [BUILD_RUNNER_OPTIONS_ENV]: JSON.stringify({
           ...input,
           supervision: { kind: 'local-parent', parentPid: process.pid },