@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/events/catalog.ts

@@ -67,6 +67,7 @@ export const allowedActorKinds: Record<EventType, readonly ActorKind[]> = {
   'build.discard-requested': ['human'],
   'build.auto-merge-requested': ['human'],
   'build.auto-merge-cancelled': ['human'],
+  'build.auto-merge-default-observed': ['dispatcher'],
   'build.paused': ['kernel'],
   'build.resumed': ['kernel'],
   'build.aborted': ['kernel', 'dispatcher'],

package/packages/core/src/events/globs.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared event-glob compilation (§15.3, AUT-342): the anchored glob matcher
+ * `ab watch`, `ab wait`, and the `[orchestrator].wake` configuration use.
+ * `*` matches any run of characters, `?` exactly one, everything else
+ * verbatim (so the dots inside event type names are escaped). Every glob
+ * must match at least one event type in one of the given catalogs, else a
+ * validation error naming the glob is thrown.
+ */
+import { EVENT_TYPES } from './payloads'
+import { REPOSITORY_EVENT_TYPES } from './repository'
+
+export interface CompileEventGlobsOptions {
+  /** Also accept matches in the repository-journal catalog (the `--repository`
+   * behavior of `ab watch`/`ab wait`). */
+  repository?: boolean
+  usage: string
+}
+
+export function compileEventGlobs(
+  globs: readonly string[],
+  opts: CompileEventGlobsOptions,
+): RegExp[] {
+  return globs.map((glob) => {
+    const source =
+      '^' +
+      [...glob]
+        .map((char) => {
+          if (char === '*') return '.*'
+          if (char === '?') return '.'
+          return char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        })
+        .join('') +
+      '$'
+    const regex = new RegExp(source)
+    const inBuildCatalog = EVENT_TYPES.some((type) => regex.test(type))
+    const inRepositoryCatalog =
+      opts.repository === true && REPOSITORY_EVENT_TYPES.some((type) => regex.test(type))
+    if (!inBuildCatalog && !inRepositoryCatalog) {
+      throw new Error(
+        `--event "${glob}" matches no known event type${
+          opts.repository ? ' in the build or repository catalogs' : ' in the build event catalog'
+        } — ${opts.usage}`,
+      )
+    }
+    return regex
+  })
+}

package/packages/core/src/events/payloads.ts

@@ -36,6 +36,23 @@ import {
 
 const empty = z.strictObject({})
 const reasonOnly = z.strictObject({ reason: z.string().optional() })
+/** Fan-out provenance shared by the auto-merge command facts: the repository
+ * seq of the `dispatcher.auto-merge-default-set` fact that caused the command,
+ * when one did. Per-build commands omit it. `{}` stays valid, so existing
+ * producers and logs replay unchanged. */
+const autoMergeCommand = z.strictObject({
+  defaultSeq: z.number().int().positive().optional(),
+})
+/** A fan-out reconciliation marker: the repository seq of the newest
+ * `dispatcher.auto-merge-default-set` fact a build has observed when that fact
+ * already matched the build's requested state. It advances the build's
+ * provenance without appending a duplicate request/cancel command, so a later
+ * per-build toggle stands until a strictly newer default fact arrives
+ * (f_28b3fba1). Dispatcher-authored: it records a reconciliation, not a
+ * human command. */
+const autoMergeDefaultObserved = z.strictObject({
+  defaultSeq: z.number().int().positive(),
+})
 const round = z.number().int().positive()
 const attempt = z.number().int().positive()
 const dispatchStage = z.enum(['create', 'workspace', 'spec', 'comment', 'launch'])
@@ -175,6 +192,20 @@ const finalizeStepCompletedPayloadSchema = z.discriminatedUnion('ok', [
   }),
 ])
 
+/** One ticket asset revision a build froze (SPEC §6.3): the identity and
+ * shape of what `listTicketAssets` returned at the pinning moment. */
+export const pinnedAssetSchema = z.strictObject({
+  kind: z.string().min(1),
+  name: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+  layout: z.enum(['file', 'tree']),
+  size: z.number().int().nonnegative(),
+  fileCount: z.number().int().nonnegative(),
+  dirCount: z.number().int().nonnegative(),
+})
+
+export type PinnedAsset = z.infer<typeof pinnedAssetSchema>
+
 /** Shared by `plan-review.verdict` and `code-review.verdict` (symmetric by design). */
 const reviewVerdictPayload = z.strictObject({
   round,
@@ -194,12 +225,20 @@ export const eventPayloadSchemas = {
     /** Claim-time auto-merge intent retained across dispatch recovery until the
      * ordinary human-authored command fact can be materialized. */
     autoMergeRequestedBy: z.string().min(1).optional(),
+    /** Claim-time auto-merge intent provenance: the repository seq of the
+     * `dispatcher.auto-merge-default-set` fact the claim sampled. Retained for
+     * the same recovery window as `autoMergeRequestedBy`; omitted when the
+     * claim sampled no default fact. */
+    autoMergeDefaultSeq: z.number().int().positive().optional(),
     /** Frozen at claim time. Historical logs and disabled installs omit it. */
     pr: z
       .strictObject({
         imageHost: prImageHostSchema.optional(),
       })
       .optional(),
+    /** Ticket assets frozen at claim time. Omitted when the ticket had none
+     * and in historical logs. */
+    assets: z.array(pinnedAssetSchema).optional(),
   }),
   'build.completed': z.strictObject({ outcome: buildOutcomeSchema }),
   'runner.attached': z.strictObject({
@@ -223,6 +262,10 @@ export const eventPayloadSchemas = {
     path: z.string().min(1).optional(),
     /** Dispatcher-reachable path. Remote providers intentionally omit it. */
     localPath: z.string().min(1).optional(),
+    /** True when the provider reported a remote publication capability at
+     * provision time. Absent ⇒ local (historical journals). AUT-505 removes
+     * the legacy fallback that reads absent as the provider name. */
+    remote: z.boolean().optional(),
     branch: z.string().min(1),
     base: workspaceBaseSchema,
   }),
@@ -363,8 +406,9 @@ export const eventPayloadSchemas = {
   'build.resume-requested': reasonOnly,
   'build.abort-requested': reasonOnly,
   'build.discard-requested': empty,
-  'build.auto-merge-requested': empty,
-  'build.auto-merge-cancelled': empty,
+  'build.auto-merge-requested': autoMergeCommand,
+  'build.auto-merge-cancelled': autoMergeCommand,
+  'build.auto-merge-default-observed': autoMergeDefaultObserved,
   'build.paused': empty,
   'build.resumed': empty,
   'build.aborted': empty,
@@ -382,6 +426,9 @@ export const eventPayloadSchemas = {
     artifact: artifactRefSchema,
     /** seq of the `escalation.raised` event that forced the revision. */
     escalation: z.number().int().positive(),
+    /** Present (possibly empty) when the revision re-pins the build to the
+     * ticket's then-current assets; absent leaves the pinned set unchanged. */
+    assets: z.array(pinnedAssetSchema).optional(),
   }),
 
   // ── Sessions (every agent run is bracketed by these) ──────────────────────
@@ -552,6 +599,9 @@ export const eventPayloadSchemas = {
     resolution: escalationResolutionSchema,
     /** Exact replacement spec authorized by a `revise-spec` answer. */
     artifact: artifactRefSchema.optional(),
+    /** The ticket's assets sampled with a revise-from-ticket authorization, so a
+     * retry re-pins the set that was authorized. Absent otherwise. */
+    assets: z.array(pinnedAssetSchema).optional(),
     /** Absolute per-loop/current-spec review budget selected by the operator. */
     reviewRoundCeiling: z.number().int().positive().optional(),
   }),

package/packages/core/src/events/repository.ts

@@ -76,6 +76,10 @@ const tickCountersSchema = z.strictObject({
   sandboxIdleStops: z.number().int().nonnegative().optional(),
   /** Contained idle-settlement failures this tick; retried next tick. */
   sandboxSettleFailures: z.number().int().nonnegative().optional(),
+  /** Contained sandbox-backend construction failures this tick; re-reported
+   * every tick until the config is repaired. Optional so historical tick
+   * facts replay. */
+  orchestratorSandboxFailures: z.number().int().nonnegative().optional(),
   harvestStarted: z.number().int().nonnegative(),
   harvestResumed: z.number().int().nonnegative(),
   harvestCompleted: z.number().int().nonnegative(),
@@ -264,13 +268,20 @@ export const harvestEventPayloadSchemas = {
  * `processes/sandbox-state.ts`, mirroring harvest execution settlement. */
 export const orchestratorSandboxEventPayloadSchemas = {
   /** First use of one operator's environment for this repository, or a
-   * post-reset reprovision. Carries the full environment identity. */
+   * post-reset reprovision. Carries the full environment identity, plus the
+   * base branch head the fresh provision selected — the publication
+   * precondition's reference point (a publish must be a descendant of it).
+   * Optional so historical journals replay unchanged. */
   'orchestrator.sandbox.provisioned': z.strictObject({
     operator: z.string().min(1),
     environmentId: z.string().min(1),
     provider: z.string().min(1),
     sessionId: z.string().min(1).optional(),
     workspacePath: z.string().min(1),
+    baseSha: z
+      .string()
+      .regex(/^[0-9a-f]{40,64}$/i)
+      .optional(),
   }),
   /** A stopped environment resumed for a later tool call. */
   'orchestrator.sandbox.resumed': z.strictObject({
@@ -311,6 +322,34 @@ export const orchestratorSandboxEventPayloadSchemas = {
     operator: z.string().min(1),
     environmentId: z.string().min(1),
   }),
+  /** One PR-only publication from an operator sandbox: the operator, the
+   * delegated orchestrator session when one triggered the tool, the
+   * deterministic branch the commit was pushed to, the published commit, and
+   * the opened-or-adopted PR. Written after both the push and the forge call
+   * succeed; the push-before-fact discipline makes a retry complete the
+   * journal rather than re-push. */
+  'orchestrator.sandbox.published': z.strictObject({
+    operator: z.string().min(1),
+    environmentId: z.string().min(1),
+    branch: z.string().min(1),
+    sha: z.string().regex(/^[0-9a-f]{40,64}$/i),
+    session: z.string().min(1).optional(),
+    pr: z.strictObject({
+      number: z.number().int().positive(),
+      url: z.string().min(1),
+      headSha: z.string().min(1),
+    }),
+  }),
+  /** A refused or failed publication attempt. `stage` names where it stopped
+   * (the precondition checks, the push, or the forge PR call); `message` is
+   * the provider's or forge's text, redacted of credential values by the
+   * service. */
+  'orchestrator.sandbox.publish-failed': z.strictObject({
+    operator: z.string().min(1),
+    environmentId: z.string().min(1),
+    stage: z.enum(['checks', 'push', 'pr']),
+    message: z.string().min(1),
+  }),
 } as const
 
 export const dispatcherStatusEventPayloadSchemas = {
@@ -421,6 +460,16 @@ export type RepositoryEventType = keyof typeof repositoryEventPayloadSchemas
 export const REPOSITORY_EVENT_TYPES = Object.keys(
   repositoryEventPayloadSchemas,
 ) as RepositoryEventType[]
+
+/** The repository-journal attention set, followed only under `--repository`
+ * by `ab watch` and scanned by the orchestrator wake pass. */
+export const REPOSITORY_ATTENTION_EVENTS = [
+  'harvest.escalated',
+  'harvest.failed',
+  'dispatcher.tick-failed',
+  'dispatcher.config-rejected',
+  'dispatcher.harvest-runner-failed',
+] as const satisfies readonly RepositoryEventType[]
 export type RepositoryEventPayload<T extends RepositoryEventType> = z.infer<
   (typeof repositoryEventPayloadSchemas)[T]
 >
@@ -487,6 +536,8 @@ const allowedActorKinds: Record<RepositoryEventType, readonly ActorKind[]> = {
   // `harvest.execution.released` is dispatcher-authored.
   'orchestrator.sandbox.released': ['human', 'dispatcher'],
   'orchestrator.sandbox.reset': ['human'],
+  'orchestrator.sandbox.published': ['human'],
+  'orchestrator.sandbox.publish-failed': ['human'],
   'dispatcher.run-started': ['dispatcher'],
   'dispatcher.run-stopped': ['dispatcher'],
   'dispatcher.tick-yielded': ['dispatcher'],

package/packages/core/src/events/sessions.ts

@@ -24,24 +24,62 @@ const positiveInt = z.number().int().positive()
 
 const empty = z.strictObject({})
 
-/** The trigger that started a turn: a human message or a wake event. */
-const turnTriggerSchema = z.discriminatedUnion('kind', [
-  z.strictObject({ kind: z.literal('message'), messageSeq: positiveInt }),
-  z.strictObject({
+/** The trigger that started a turn: a human message or a wake event. A wake
+ * trigger names exactly one source — a build (the build-log attention scan)
+ * or the repository journal — enforced by the schema's `.check()` below even
+ * though the static type (one object with optional fields) cannot express it:
+ * a two-member union or a nested discriminated union is not a valid
+ * discriminated-union option on zod 4 (both constructions throw at first
+ * parse), so the wake variant stays a single object and call sites branch on
+ * `journal === true`. */
+const turnWakeTriggerSchema = z
+  .strictObject({
     kind: z.literal('wake'),
-    build: z.string().min(1),
+    build: z.string().min(1).optional(),
+    journal: z.literal(true).optional(),
     seq: positiveInt,
     type: z.string().min(1),
-  }),
+  })
+  .check((ctx) => {
+    const hasBuild = ctx.value.build !== undefined
+    const hasJournal = ctx.value.journal === true
+    if (hasBuild === hasJournal) {
+      ctx.issues.push({
+        code: 'custom',
+        input: ctx.value,
+        message: 'a wake trigger names exactly one of build or journal',
+      })
+    }
+  })
+
+const turnTriggerSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('message'), messageSeq: positiveInt }),
+  turnWakeTriggerSchema,
 ])
 
-/** Matches the transcript usage shape (harvest.session.ended, §15.3). */
+/** Matches the transcript usage shape (harvest.session.ended, §15.3). The
+ * turn runner records the AI SDK's totalUsage token counts plus the step
+ * count. Old `turn.completed` events without `steps` still reduce. */
 const usageSchema = z.strictObject({
   inputTokens: z.number().int().nonnegative(),
   outputTokens: z.number().int().nonnegative(),
+  steps: z.number().int().nonnegative(),
   turns: z.number().int().nonnegative().optional(),
 })
 
+/** The typed model-failure vocabulary (AUT-342): provider availability,
+ * exhaustion, credentials, and configuration are distinguished so a failed
+ * turn's class is visible in the session's reduced state and nothing is ever
+ * retried unboundedly. `internal` covers non-model failures — the dispatcher
+ * tick's crash reaper among them. */
+const turnFailureKindSchema = z.enum([
+  'provider-unavailable',
+  'exhausted',
+  'credentials',
+  'configuration',
+  'internal',
+])
+
 export const sessionEventPayloadSchemas = {
   /** The fact of creation; the session record carries the same title. */
   'session.created': z.strictObject({ title: z.string().min(1).optional() }),
@@ -52,11 +90,27 @@ export const sessionEventPayloadSchemas = {
   'session.wake-set': z.strictObject({
     globs: z.array(z.string().min(1)).max(100),
   }),
-  /** The (later) turn runner's start of one turn on its stream. */
+  /** The (later turn runner's) start of one turn on its stream. A wake
+   * turn additionally carries the delivered input — the attention event
+   * record and, for a build wake, the build's reduced state, frozen at wake
+   * time — so a later invocation reconstructs the identical user message
+   * from durable state alone (live build state keeps moving; the frozen
+   * snapshot does not). A journal wake delivers the event record only. */
   'turn.started': z.strictObject({
     turn: z.string().min(1),
     stream: z.string().min(1),
     trigger: turnTriggerSchema,
+    wake: z
+      .strictObject({
+        event: z.strictObject({
+          seq: positiveInt,
+          ts: z.string().min(1),
+          type: z.string().min(1),
+          payload: z.record(z.string(), z.unknown()),
+        }),
+        buildState: z.record(z.string(), z.unknown()).optional(),
+      })
+      .optional(),
   }),
   /** A turn was suspended for budget or for an approval. */
   'turn.suspended': z.strictObject({
@@ -80,8 +134,13 @@ export const sessionEventPayloadSchemas = {
   }),
   /** One turn finished. */
   'turn.completed': z.strictObject({ turn: z.string().min(1), usage: usageSchema }),
-  /** One turn failed. */
-  'turn.failed': z.strictObject({ turn: z.string().min(1), error: z.string().min(1) }),
+  /** One turn failed: `kind` is the typed failure class, `error` the
+   * human-readable message surfaced in the session's reduced state. */
+  'turn.failed': z.strictObject({
+    turn: z.string().min(1),
+    kind: turnFailureKindSchema,
+    error: z.string().min(1),
+  }),
   /** Terminal. The session is read-only afterwards. */
   'session.archived': empty,
 } as const

package/packages/core/src/events/workspace-remote.ts

@@ -0,0 +1,12 @@
+import type { EventPayload } from './payloads'
+
+/** Whether the workspace this payload records publishes remotely, per the
+ * marker recorded at provision. Journals written before the marker existed
+ * fall back to the legacy provider-name reading — the only name comparison
+ * among the remote/local decisions (removed in AUT-505). */
+export function isRemoteWorkspace(
+  payload: Pick<EventPayload<'workspace.provisioned'>, 'provider' | 'remote'>,
+): boolean {
+  if (payload.remote !== undefined) return payload.remote
+  return payload.provider === 'vercel-sandbox'
+}

package/packages/core/src/integration/harness.ts

@@ -347,7 +347,8 @@ export async function makeHarness(opts: {
     gatePresence: opts.gatePresence ?? 'present',
     ...(opts.pluginForge?.prAttachments === true ? { prAttachments: true } : {}),
   })
-  let selectedForge: Forge = opts.localGitForge === true ? new LocalGitForge() : forge
+  let selectedForge: Forge =
+    opts.localGitForge === true ? new LocalGitForge({ repoRoot: origin }) : forge
   let plugins: PluginRegistry | undefined
   if (opts.pluginForge !== undefined) {
     plugins = createPluginRegistry()

package/packages/core/src/kernel/auto-merge-default.ts

@@ -0,0 +1,123 @@
+/**
+ * The repository auto-merge default as a bulk action over in-flight builds.
+ *
+ * The durable `dispatcher.auto-merge-default-set` fact has always been the
+ * claim-time seed; it now also fans out onto every current non-terminal build
+ * of the repository, attributed to the operator who toggled it. The fan-out is
+ * a dispatcher-tick reconciliation driven by the durable fact — never a
+ * write-time walk — so a build claimed concurrently with the toggle and a
+ * build observed by a second dispatcher polling the same repository converge
+ * on the same state.
+ *
+ * Idempotency vs. per-build overrides: each answering command records the
+ * repository `seq` of the default fact that caused it (`defaultSeq`). A tick
+ * applies the default to a build only when the newest fact's seq is strictly
+ * newer than the build's recorded `defaultSeq`. When the build's requested
+ * state already matches the fact, the tick records a provenance-only
+ * `build.auto-merge-default-observed` marker instead of appending a duplicate
+ * command, so a later per-build toggle is not mistaken for staleness and
+ * reverted. A global toggle therefore re-applies over a per-build choice, a
+ * per-build toggle in between is stable, and pressing the toggle twice appends
+ * no duplicate request.
+ *
+ * Eligibility is expressed against `BuildState`, not `effectiveStatus`
+ * (dashboard/model.ts), whose contract is "DISPLAY-ONLY — nothing consults
+ * this"; a durable write path must not become its first consumer — the same
+ * precedent `bulk-control.ts` set for the pause/resume walk.
+ */
+import type { RepositoryEvent } from '../events/repository'
+import { discardInFlight, type BuildState } from './reducer'
+
+/** One `dispatcher.auto-merge-default-set` fact, resolved. `actor` is the
+ * event's actor — the human who toggled, `via` marker included — and is the
+ * attribution every fan-out command carries. */
+export interface AutoMergeDefaultFact {
+  enabled: boolean
+  /** The repository event's seq — the fan-out's comparison marker. */
+  seq: number
+  actor: RepositoryEvent['actor']
+}
+
+/** The newest `dispatcher.auto-merge-default-set` fact in the repository
+ * journal, or undefined when no default was ever set (the scan runs from the
+ * tail because seqs are monotonic, so the first hit is the newest). With
+ * `enabled`, the newest fact *matching that value* — the fact a claim-time
+ * seed built on a stale pre-tick sample must cite, so a newer opposite fact
+ * stays strictly newer than the seed's provenance and the next tick's
+ * fan-out can reconcile it (f_b851c0e8). */
+export function latestAutoMergeDefault(
+  events: RepositoryEvent[],
+  enabled?: boolean,
+): AutoMergeDefaultFact | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (
+      event?.type === 'dispatcher.auto-merge-default-set' &&
+      (enabled === undefined || event.payload.enabled === enabled)
+    ) {
+      return { enabled: event.payload.enabled, seq: event.seq, actor: event.actor }
+    }
+  }
+  return undefined
+}
+
+/**
+ * A build the default may still act on: not terminal, and not on its way out.
+ * A pending abort (an explicit request or an accepted escalation answer) must
+ * never receive consent — a merge landing mid-abort is exactly the race this
+ * clause exists to close. The same holds for an outstanding discard request:
+ * `discardRequest` is present exactly while the build is non-terminal and its
+ * discard is unsettled, and the reducer settles it only by terminal completion
+ * — consent recorded inside that window can merge a build the operator already
+ * asked to discard (in the raced-runner-attachment case the discard is inert
+ * for a running build, and the recorded consent later drives the merge in
+ * `checkPr`). Direction-blind like the abort clause: the build terminalizes
+ * imminently either way. If discard ever grows a mid-flight settlement event,
+ * this predicate must be revisited.
+ */
+export function autoMergeDefaultEligible(state: BuildState): boolean {
+  if (state.status === 'done' || state.status === 'aborted') return false
+  // An empty log is a record whose `build.created` has not landed yet (the
+  // crash or one-await window between `createBuild` and the first append):
+  // writing an auto-merge command ahead of the immutable facts would leave the
+  // log unrecoverable — dispatch recovery rejects a log that does not start
+  // with `build.created` (f_647d40be). `lastSeq === 0` is exactly that log.
+  if (state.lastSeq === 0) return false
+  // An outstanding discard request is the same "on its way out" shape as a
+  // pending abort: it settles only by terminal completion (reducer.ts), so
+  // consent recorded inside that window can merge a build the operator
+  // already asked to discard. Direction-blind, like the abort clause — an
+  // OFF fan-out skipping it withdraws nothing that survives the settlement.
+  // Shared predicate: the per-build consent guard (build-control.ts) applies
+  // the same exclusion to consent-recording writes. A per-build OFF withdrawal
+  // stays available there — revocation only shrinks the merge set — which is a
+  // stated, directional divergence, not a silent one.
+  if (discardInFlight(state)) return false
+  return !state.pendingCommands.some((command) => command.command === 'abort')
+}
+
+/** What one default fact asks of one build: a real command, a pure provenance
+ * advance, or `undefined` for "nothing". */
+export type AutoMergeDefaultTarget = 'request' | 'cancel' | 'observed'
+
+/** What one default fact asks of one build, or undefined for "nothing".
+ *
+ * Seq-first: a build whose recorded provenance is already this fact (or newer)
+ * has had its day in court — a per-build toggle made after the fan-out stands
+ * until the default moves again. A build that sampled the default at claim time
+ * carries the fact's seq too, so a fresh claim is not re-fanned on the next
+ * tick.
+ *
+ * When the requested state already matches the fact, the fact still has to be
+ * *recorded* as observed (`'observed'`) so the next tick does not mistake a
+ * later per-build command for staleness: the marker advances `defaultSeq`
+ * without a duplicate request/cancel (f_28b3fba1). */
+export function autoMergeDefaultTarget(
+  state: BuildState,
+  fact: AutoMergeDefaultFact,
+): AutoMergeDefaultTarget | undefined {
+  if (!autoMergeDefaultEligible(state)) return undefined
+  if ((state.autoMerge.defaultSeq ?? 0) >= fact.seq) return undefined
+  if (state.autoMerge.requested === fact.enabled) return 'observed'
+  return fact.enabled ? 'request' : 'cancel'
+}

package/packages/core/src/kernel/phases.ts

@@ -52,6 +52,9 @@ export interface ContextInputs {
    * loop routing (loopOfPhase → 'other') relies on this input existing.
    */
   answeredGuidance?: boolean
+  /** The ticket assets the build froze at claim (SPEC §6.3), written under
+   * `.ab/assets/`. Every phase receives them. */
+  assets?: boolean
 }
 
 export interface PhaseSpec {
@@ -91,6 +94,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
       spec: true,
       priorOwnArtifacts: true,
       findings: 'current',
+      assets: true,
     },
   },
   'plan-review': {
@@ -102,7 +106,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
     terminalEvent: 'plan-review.verdict',
     requiredArtifact: 'plan-review',
     verdictVocabulary: ['approve', 'revise', 'escalate'],
-    inputs: { spec: true, plan: 'latest', findings: 'all-rounds' },
+    inputs: { spec: true, plan: 'latest', findings: 'all-rounds', assets: true },
   },
   implement: {
     name: 'implement',
@@ -120,6 +124,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
       findings: 'current',
       verifyReports: true,
       priorOwnArtifacts: true,
+      assets: true,
     },
   },
   'code-review': {
@@ -137,6 +142,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
       commitRange: true,
       findings: 'all-rounds',
       implementNotes: true,
+      assets: true,
     },
   },
   verify: {
@@ -147,7 +153,13 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
     terminal: 'verdict',
     terminalEvent: 'verify.completed',
     verdictVocabulary: ['pass', 'fail', 'skip'],
-    inputs: { spec: true, stepConfig: true, commitRange: true, currentFeedback: true },
+    inputs: {
+      spec: true,
+      stepConfig: true,
+      commitRange: true,
+      currentFeedback: true,
+      assets: true,
+    },
   },
   finalize: {
     name: 'finalize',
@@ -164,6 +176,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
       verifyReports: true,
       prTemplate: true,
       answeredGuidance: true,
+      assets: true,
     },
   },
   reconcile: {
@@ -181,6 +194,7 @@ export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
       implementNotes: true,
       conflict: true,
       answeredGuidance: true,
+      assets: true,
     },
   },
 }