@defrex/autobuild 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defrex/autobuild",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Agent-driven software delivery from groomed ticket to merged PR",
   "repository": {
     "type": "git",
@@ -37,10 +37,15 @@
       "import": "./packages/core/src/store/remote/index.ts",
       "default": "./packages/core/src/store/remote/index.ts"
     },
-    "./operator-api": {
-      "types": "./packages/core/src/operator/index.ts",
-      "import": "./packages/core/src/operator/index.ts",
-      "default": "./packages/core/src/operator/index.ts"
+    "./hosted-tickets": {
+      "types": "./packages/core/src/ports/tickets/hosted-index.ts",
+      "import": "./packages/core/src/ports/tickets/hosted-index.ts",
+      "default": "./packages/core/src/ports/tickets/hosted-index.ts"
+    },
+    "./testing": {
+      "types": "./packages/core/src/testing/index.ts",
+      "import": "./packages/core/src/testing/index.ts",
+      "default": "./packages/core/src/testing/index.ts"
     },
     "./operator-presentation": {
       "types": "./packages/core/src/operator/presentation.ts",
@@ -52,11 +57,6 @@
       "import": "./packages/core/src/ports/tickets/update.ts",
       "default": "./packages/core/src/ports/tickets/update.ts"
     },
-    "./remote-tickets": {
-      "types": "./packages/core/src/ports/tickets/remote-index.ts",
-      "import": "./packages/core/src/ports/tickets/remote-index.ts",
-      "default": "./packages/core/src/ports/tickets/remote-index.ts"
-    },
     "./origin": {
       "types": "./packages/core/src/kernel/origin.ts",
       "import": "./packages/core/src/kernel/origin.ts",
@@ -76,12 +76,32 @@
       "types": "./packages/core/src/ports/workspace/distribution-archive.ts",
       "import": "./packages/core/src/ports/workspace/distribution-archive.ts",
       "default": "./packages/core/src/ports/workspace/distribution-archive.ts"
+    },
+    "./operator": {
+      "types": "./packages/core/src/operator/index.ts",
+      "import": "./packages/core/src/operator/index.ts",
+      "default": "./packages/core/src/operator/index.ts"
+    },
+    "./operator-sandbox-host": {
+      "types": "./packages/core/src/operator/sandbox-host.ts",
+      "import": "./packages/core/src/operator/sandbox-host.ts",
+      "default": "./packages/core/src/operator/sandbox-host.ts"
     }
   },
   "files": [
     "bin",
     "packages/core/src",
     "!packages/core/src/**/*.test.ts",
+    "!packages/core/src/**/*.test.tsx",
+    "!packages/core/src/**/*.spec.ts",
+    "!packages/core/src/**/*.spec.tsx",
+    "!packages/core/src/testing/store-failures.ts",
+    "!packages/core/src/testing/packed-install.ts",
+    "!packages/core/src/cli/testkit.ts",
+    "!packages/core/src/cli/store-opening.contract.ts",
+    "!packages/core/src/ports/runner/live-contract-fixture.ts",
+    "!packages/core/src/cli/dashboard/frame-image.ts",
+    "!packages/core/src/markdown.ts",
     "skills",
     "templates",
     "LICENSE",
@@ -90,24 +110,25 @@
     "docs"
   ],
   "scripts": {
-    "dev": "bun run --bun next dev",
     "dev:cli": "bun --hot --no-clear-screen bin/ab-dev.ts",
-    "build": "bun run --bun next build",
-    "deploy:build": "bun packages/hosted-store-service/src/bin.ts pack-distribution && bun run postgres:migrate && bun run build && bun tools/ship-packed-distribution.ts",
-    "start": "bun run --bun next start",
-    "hosted-store": "bun server.ts",
     "capture:dashboard": "bun tools/dashboard-capture.ts",
-    "capture:web-dashboard": "bun tools/web-dashboard-capture.tsx",
+    "capture:web-dashboard": "bun packages/web-dashboard-capture/src/web-dashboard-capture.tsx",
+    "capture:website": "bun tools/website-capture.ts",
+    "website:dev": "bun packages/website/src/dev.ts",
+    "website:build": "bun packages/website/src/build.ts",
     "capture:readme-headline": "bun tools/readme-headline.ts",
+    "capture:website-hero": "bun tools/website-hero.ts",
+    "capture:website-og": "bun tools/website-og.ts",
     "release": "bun tools/release.ts",
     "postgres:migrate": "bun packages/postgres-store/src/bin.ts migrate",
-    "check": "bun tools/biome-check.ts && bun tools/product-name-check.ts && bun tools/docs-asset-check.ts && bun tools/readme-headline.ts --check && bun tools/workspace-manifest-check.ts",
+    "check": "bun tools/biome-check.ts && bun tools/product-name-check.ts && bun tools/docs-asset-check.ts && bun tools/skill-docs-asset-check.ts && bun tools/readme-headline.ts --check && bun tools/website-hero.ts --check && bun tools/workspace-manifest-check.ts && bun tools/package-boundary-check.ts && bun tools/bin-mode-check.ts && bun tools/publish-contents-check.ts && bun tools/publish-imports-check.ts",
     "format:staged": "git-format-staged --formatter './node_modules/.bin/biome format --stdin-file-path {}' '*.js' '*.jsx' '*.ts' '*.tsx' '*.json' '*.jsonc' '*.css' '*.graphql' '*.gql'",
     "prepare": "husky",
-    "test": "bun test packages/*/src tools bin app",
+    "test": "bun test packages/*/src tools bin packages/hosted-store-service/app",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@ai-sdk/gateway": "4.0.82",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@vercel/sandbox": "^3.1.0",
     "ai": "^7.0.101",
@@ -118,18 +139,19 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
+    "@defrex/autobuild-postgres-store": "0.9.0",
+    "@defrex/autobuild-vercel-sandbox": "0.9.0",
     "@resvg/resvg-js": "2.6.2",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.0.0",
-    "@types/pg": "8.16.0",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
     "@types/semver": "^7.7.1",
     "dejavu-fonts-ttf": "2.37.0",
     "drizzle-kit": "^0.31.10",
     "git-format-staged": "4.0.1",
     "husky": "9.1.7",
-    "typescript": "5.9.3",
-    "vercel": "^59.11.2"
+    "typescript": "5.9.3"
+  },
+  "patchedDependencies": {
+    "better-auth@1.4.18": "patches/better-auth@1.4.18.patch"
   }
 }

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

@@ -9,10 +9,11 @@ import { basename, dirname, resolve } from 'node:path'
 import { agentActor } from '../events/envelope'
 import { prAttachmentSchema } from '../ontology'
 import type { Exec } from '../ports/workspace/git-worktree'
-import type { Artifact, ArtifactMeta, BuildStore } from '../store/types'
+import type { Artifact, ArtifactMeta, BuildStore, RepositoryArtifact } from '../store/types'
 import type { CliEnv } from './env'
-import { buildInRepository } from './repo-state'
-import { withAmbientReadStore, type StoreOpener } from './store-opening'
+import { resolveAmbientReadSession } from './env'
+import { buildInRepository, streamInRepository } from './repo-state'
+import { withAmbientReadStore, withSessionlessStore, type StoreOpener } from './store-opening'
 
 export interface ArtifactDeps {
   store: BuildStore
@@ -174,9 +175,132 @@ export async function artifactDownload(
       )
     }
 
-    const outputPath = resolve(opts.targetRepo, opts.outputPath)
-    await mkdir(dirname(outputPath), { recursive: true })
-    await writeFile(outputPath, artifact.content)
+    const outputPath = await writeArtifactBytes(opts.targetRepo, opts.outputPath, artifact.content)
     return { artifact, outputPath }
   })
 }
+
+/** Shared download tail: exact bytes under the resolved output path (parent
+ * directories created), used by both the build-scoped and stream-addressed
+ * forms so neither can drift on byte handling. */
+async function writeArtifactBytes(
+  targetRepo: string,
+  outputPath: string,
+  content: Uint8Array,
+): Promise<string> {
+  const resolved = resolve(targetRepo, outputPath)
+  await mkdir(dirname(resolved), { recursive: true })
+  await writeFile(resolved, content)
+  return resolved
+}
+
+export interface ArtifactDownloadStreamOpts {
+  /** Current checkout; repository identity resolves to its main worktree. */
+  targetRepo: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  /** `stream:<id>` or `stream:<id>@<rev>`; rev pins the finalized artifact. */
+  spec: string
+  outputPath: string
+  /** Explicit --store; precedence remains flag > AB_STORE > local default. */
+  storeRef?: string
+  /** Adapter seam for local/remote selection tests. */
+  openStore?: StoreOpener
+}
+
+export interface ArtifactDownloadStreamResult {
+  artifact: RepositoryArtifact
+  outputPath: string
+}
+
+/** Operator retrieval of a finalized, repo-scoped stream artifact (the harvest
+ * session analog of the build-scoped form). A stream id is store-assigned and
+ * globally unique, so no build or repo argument is needed: the command reads
+ * the stream record, checks its scope, then fetches the close-deposited
+ * repository artifact.
+ *
+ * Authorization is the operator-wide read rule only (§8.2): this form requires
+ * a sessionless invocation and fails closed under any complete ambient phase
+ * identity — repository-scoped targets are never reachable by ambient
+ * own-build or own-harvest authority. The check runs here, before any store
+ * call, because local harvest-ambient handles would permit own-repo
+ * `getRepoArtifact` while remote handles rely on the core to enforce scope. */
+export async function artifactDownloadStream(
+  opts: ArtifactDownloadStreamOpts,
+): Promise<ArtifactDownloadStreamResult> {
+  const ambient = resolveAmbientReadSession(opts.env)
+  if (ambient !== undefined) {
+    throw new Error(
+      'repo-scoped stream downloads are operator reads (§8.2): ambient phase ' +
+        'identity (build or Harvest) never extends to repository-scoped targets — ' +
+        'run this command without agent identity markers',
+    )
+  }
+  const { kind, rev } = parseArtifactSpec(opts.spec)
+  const streamId = kind.startsWith('stream:') ? kind.slice('stream:'.length) : ''
+  if (streamId.trim() === '') {
+    throw new Error(
+      `invalid stream ref "${opts.spec}" — expected 'stream:<id>' or 'stream:<id>@<rev>'`,
+    )
+  }
+  return withSessionlessStore(
+    {
+      targetRepo: opts.targetRepo,
+      env: opts.env,
+      exec: opts.exec,
+      ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+      ...(opts.openStore !== undefined ? { openStore: opts.openStore } : {}),
+    },
+    async (context) => {
+      const record = await context.store.getStream(streamId)
+      if (record === null) {
+        throw new Error(
+          `no stream "${streamId}" in this store — run 'ab harvest status' to find ` +
+            'session stream ids, or pass --store <ref>',
+        )
+      }
+      if (record.scope.kind === 'build') {
+        throw new Error(
+          `stream "${streamId}" is build-scoped — download it with ` +
+            `'ab artifact download ${record.scope.build} stream:${streamId}'`,
+        )
+      }
+      if (record.scope.kind === 'session') {
+        throw new Error(
+          `stream "${streamId}" is session-scoped — read it through the operator ` +
+            `session stream surface (GET /sessions/${record.scope.session}/streams/${streamId})`,
+        )
+      }
+      // Origin-aware membership, mirroring the build-scoped path above.
+      // Unlike a BuildRecord, StreamScope carries no `repoOrigin`, so a legacy
+      // physical-path scope.repo stays rejected here (see
+      // `streamInRepository` for the documented AUT-314-class divergence).
+      if (!streamInRepository(record.scope.repo, context.repo)) {
+        throw new Error(
+          `stream "${streamId}" belongs to repository "${record.scope.repo}", not "${context.repo}"`,
+        )
+      }
+      if (record.status === 'open') {
+        throw new Error(
+          `stream "${streamId}" is open — its finalized artifact exists only after ` +
+            'the stream closes (§7.6)',
+        )
+      }
+      const artifact = await context.store.getRepoArtifact(record.scope.repo, kind, rev)
+      if (artifact === null) {
+        const available = await context.store.listRepoArtifacts(record.scope.repo, kind)
+        const refs = available.map((meta) => `${meta.kind}@${meta.revision}`)
+        throw new Error(
+          `no "${kind}" artifact${rev !== undefined ? ` at rev ${rev}` : ''} in ` +
+            `repository "${record.scope.repo}" — available refs: ${refs.join(', ') || '(none)'}`,
+        )
+      }
+      const outputPath = await writeArtifactBytes(
+        opts.targetRepo,
+        opts.outputPath,
+        artifact.content,
+      )
+      return { artifact, outputPath }
+    },
+  )
+}

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

@@ -165,12 +165,20 @@ export async function runBinary(
   // A scoped phase process is composed from the build worktree's immutable
   // configuration just like dispatch. Load and select the forge before opening
   // the store so plugin failures cannot partially execute terminal plumbing.
+  // Guest tolerance (AUT-517), always on here: in checkout mode `ab dispatch`
+  // already failed startup if a configured plugin did not resolve, and
+  // origin-mode phase processes only run inside guests — so an unresolvable
+  // bare specifier here can only be the provider-plugin case, which a phase
+  // process (never constructing workspace providers) may skip.
   let forge: Awaited<ReturnType<typeof createForge>>
   try {
     const repoRoot = process.cwd()
     const packageRoot = await resolveMainRepo(repoRoot, spawnExec)
     const config = await loadConfig(join(repoRoot, 'autobuild.toml'))
-    const plugins = await loadPlugins(config.plugins, repoRoot, { packageRoot })
+    const plugins = await loadPlugins(config.plugins, repoRoot, {
+      packageRoot,
+      guest: true,
+    })
     forge = await createForge({
       name: config.forge,
       registry: plugins,

package/packages/core/src/cli/build-control.ts

@@ -7,11 +7,18 @@
  * normal runner and dispatcher consume them.
  */
 import type { AbEvent } from '../events/catalog'
+import type { PinnedAsset } from '../events/payloads'
 import { humanActor, KERNEL, type Via } from '../events/envelope'
-import { reduceBuild, type BuildState, type OpenEscalation } from '../kernel/reducer'
+import {
+  reduceBuild,
+  discardInFlight,
+  type BuildState,
+  type OpenEscalation,
+} from '../kernel/reducer'
 import type { ArtifactRef, BuildOutcome, BuildStatus, TicketRef } from '../ontology'
 import type { Exec } from '../ports/workspace/git-worktree'
 import { specConformance } from '../spec-standard'
+import { samplePinnedAssets } from '../store/ticket-assets'
 import type { BuildStore } from '../store/types'
 import { withSessionlessStore, type StoreOpener } from './store-opening'
 
@@ -107,6 +114,7 @@ export type BuildControlErrorCode =
   | 'missing-authorization'
   | 'no-longer-active'
   | 'abort-pending'
+  | 'discard-pending'
   | 'review-round-ceiling-unavailable'
   | 'incompatible-answer-options'
 
@@ -226,6 +234,78 @@ function hasPendingAbort(state: BuildState): boolean {
   return state.pendingCommands.some((command) => command.command === 'abort')
 }
 
+function discardPending(slug: string): BuildControlError {
+  return new BuildControlError(
+    'discard-pending',
+    `build "${slug}" has an outstanding discard request; auto-merge consent was not recorded. ` +
+      'The discard settles only when the build terminalizes — nothing was appended. ' +
+      'If the discard raced with runner attachment and you still want the change, ' +
+      'merge the PR manually.',
+  )
+}
+
+/** Record or withdraw per-build auto-merge consent — the write path for
+ * `auto-merge-on`, `auto-merge-off`, and `toggle-auto-merge`.
+ *
+ * Ruling (AUT-445): recording consent on a build with an outstanding discard
+ * request is rejected — the fan-out's discard exclusion
+ * (`autoMergeDefaultEligible`'s discard clause, AUT-418) applied to explicit
+ * consent. Both controls call the same `discardInFlight` predicate from
+ * kernel/reducer.ts, so they cannot diverge silently. Withdrawing consent (OFF)
+ * is deliberately still allowed: `checkPr` honors revocation before anything
+ * else, so an OFF strictly shrinks the merge set, and it is the only way to
+ * withdraw consent recorded before the discard (a fan-out or claim-time seed) —
+ * refusing it would leave that discard-contradicting consent driving the merge
+ * anyway. The fan-out is direction-blind because it is a queue cleaner that
+ * withdraws nothing that survives the settlement; this guard is directional on
+ * purpose, and the divergence is stated here rather than left accidental.
+ *
+ * The guard runs inside a compare-and-append loop (the `appendIfCurrent` idiom
+ * the fan-out's dispatcher loop and `bulkControlRepository` already use), so a
+ * discard request that lands between the guard's read and this append cannot
+ * slip past it: the CAS misses, the loop re-reduces the log, and the guard
+ * fires on the fresh state. The toggle's direction is re-resolved from the
+ * re-read state each attempt. `activeState` runs before the guard on every
+ * attempt: a queued build (where the discard normally sits) still reports the
+ * existing `inactive` error. */
+async function appendConsentCommand(
+  store: BuildStore,
+  slug: string,
+  user: string,
+  action: 'auto-merge-on' | 'auto-merge-off' | 'toggle-auto-merge',
+  via?: Via,
+): Promise<BuildControlResult> {
+  while (true) {
+    const state = reduceBuild(await store.getEvents(slug))
+    activeState(slug, state)
+    const command =
+      action === 'toggle-auto-merge'
+        ? state.autoMerge.requested
+          ? 'auto-merge-off'
+          : 'auto-merge-on'
+        : action
+    if (command === 'auto-merge-on' && discardInFlight(state)) throw discardPending(slug)
+    const actor = humanActor(user, via)
+    // Written out rather than selected into a variable so `appendIfCurrent`'s
+    // `T extends EventType` infers a concrete payload type in each branch.
+    const appended =
+      command === 'auto-merge-on'
+        ? await store.appendIfCurrent(slug, state.lastSeq, {
+            actor,
+            type: 'build.auto-merge-requested',
+            payload: {},
+          })
+        : await store.appendIfCurrent(slug, state.lastSeq, {
+            actor,
+            type: 'build.auto-merge-cancelled',
+            payload: {},
+          })
+    if (appended !== null) return { kind: 'command', slug, command, event: appended }
+    // The stream advanced under us (a racing discard, a fan-out write, a
+    // runner acknowledgement): loop to re-read and re-check before writing.
+  }
+}
+
 function abortPending(slug: string): BuildControlError {
   return new BuildControlError(
     'abort-pending',
@@ -254,6 +334,9 @@ export type ReviseDecision =
   | {
       kind: 'complete'
       artifact: ArtifactRef
+      /** The assets sampled with the authorization; absent for a supplied body
+       * and for authorizations recorded before assets were pinned. */
+      assets?: PinnedAsset[]
       open: OpenEscalation[]
       escalationSeq: number
     }
@@ -289,7 +372,13 @@ export function decideRevise(
       }
     }
     const escalationSeq = Math.max(...[...open, ...pending].map((item) => item.seq))
-    return { kind: 'complete', artifact: authorized.artifact, open, escalationSeq }
+    return {
+      kind: 'complete',
+      artifact: authorized.artifact,
+      ...(authorized.assets !== undefined ? { assets: authorized.assets } : {}),
+      open,
+      escalationSeq,
+    }
   }
   if (open.length === 0) {
     const paused =
@@ -425,9 +514,14 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
   switch (opts.action.kind) {
     case 'pause':
     case 'resume':
+      return appendCommand(opts.store, opts.slug, user, opts.action.kind, opts.via)
+
     case 'auto-merge-on':
     case 'auto-merge-off':
-      return appendCommand(opts.store, opts.slug, user, opts.action.kind, opts.via)
+    case 'toggle-auto-merge':
+      // Consent has its own guarded, compare-and-append write path; the
+      // outer `activeState` above only short-circuits the common inactive case.
+      return appendConsentCommand(opts.store, opts.slug, user, opts.action.kind, opts.via)
 
     case 'dashboard-pause': {
       const pendingPause = state.pendingCommands.some((command) => command.command === 'pause')
@@ -464,15 +558,6 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
       return appendCommand(opts.store, opts.slug, user, 'resume', opts.via)
     }
 
-    case 'toggle-auto-merge':
-      return appendCommand(
-        opts.store,
-        opts.slug,
-        user,
-        state.autoMerge.requested ? 'auto-merge-off' : 'auto-merge-on',
-        opts.via,
-      )
-
     case 'answer': {
       const captured =
         opts.action.escalationIds === undefined ? undefined : new Set(opts.action.escalationIds)
@@ -510,11 +595,16 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
         if (initial.kind === 'refuse') throwRefusal(initial)
 
         let artifact: ArtifactRef
+        // From-ticket revisions re-pin the ticket's assets; a supplied body
+        // leaves the pinned set alone (`undefined`). Sampled once, with the
+        // body, and persisted on the answers so a retry reuses it.
+        let assets: PinnedAsset[] | undefined
         let authorizedEarlier = initial.kind === 'complete'
         if (initial.kind === 'complete') {
           // Completion rule: recorded authorization wins before the caller's
           // lazy body source is opened, regardless of remaining blockers.
           artifact = initial.artifact
+          assets = initial.assets
         } else {
           let body: string
           const source = opts.action.resolve.body
@@ -534,6 +624,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
               )
             }
             body = await opts.readTicketBody(record.ticket)
+            assets = await samplePinnedAssets(opts.store, record.repo, record.ticket.id)
           }
           const conformance = specConformance(body)
           if (!conformance.conforms) {
@@ -564,6 +655,7 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
         if (decision.kind === 'refuse') throwRefusal(decision)
         if (decision.kind === 'complete') {
           artifact = decision.artifact
+          assets = decision.assets
           authorizedEarlier = true
         }
         const answer = guidance === '' ? SPEC_REVISION_ANSWER : guidance
@@ -580,13 +672,18 @@ export async function controlBuild(opts: ControlBuildOpts): Promise<BuildControl
               answer,
               resolution: 'revise-spec',
               artifact,
+              ...(assets !== undefined ? { assets } : {}),
             },
           })
         }
         await opts.store.append(opts.slug, {
           actor: KERNEL,
           type: 'spec.revised',
-          payload: { artifact, escalation: decision.escalationSeq },
+          payload: {
+            artifact,
+            escalation: decision.escalationSeq,
+            ...(assets !== undefined ? { assets } : {}),
+          },
         })
         if (alsoPaused) {
           await opts.store.append(opts.slug, {

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

@@ -44,6 +44,7 @@ import {
 } from '../ports/workspace/phase-scratch'
 import type { Exec } from '../ports/workspace/git-worktree'
 import type { BuildStore } from '../store/types'
+import { writeAssetTo } from './ticket-assets'
 import type { CliEnv } from './env'
 
 export interface ContextDeps {
@@ -81,6 +82,16 @@ export interface ContextManifest {
   notesPath?: string
   /** relPath (under .ab/) → source artifact ref, or 'derived'. */
   materialized: Record<string, MaterializedEntry>
+  /** The ticket assets this build froze (SPEC §6.3), each written to `path`
+   * (relative to the workspace). Omitted when the build pinned none. */
+  assets?: {
+    kind: string
+    name: string
+    revision: number
+    layout: 'file' | 'tree'
+    size: number
+    path: string
+  }[]
   /** From the latest `implement.completed` (§8.3 code-review/verify inputs). */
   commitRange?: CommitRange
   /** Reconcile: `{baseSha}` freshly recorded by this attempt's phase start (§15.7). */
@@ -276,6 +287,41 @@ export async function buildContext(deps: ContextDeps): Promise<ContextManifest>
     }
   }
 
+  if (inputs.assets === true && state.pinnedAssets.length > 0) {
+    // The pin, not the ticket's current state: the revisions `build.created`
+    // (or the latest re-pinning `spec.revised`) recorded, fetched by explicit
+    // revision so a later attach/replace/remove cannot change what a phase sees.
+    const root = locate('assets')
+    manifest.assets = []
+    for (const pinned of state.pinnedAssets) {
+      const asset = await store.getPinnedTicketAsset(
+        build,
+        pinned.kind,
+        pinned.name,
+        pinned.revision,
+      )
+      if (asset === null) {
+        throw new Error(
+          `pinned ticket asset ${pinned.kind}/${pinned.name} revision ${pinned.revision} is missing from the store`,
+        )
+      }
+      const relPath = `${root}/${pinned.kind}/${pinned.name}`
+      const target = join(abDir, relPath)
+      // A file asset lands inside its directory as `<filename>`; a tree asset
+      // keeps its relative tree, empty directories included.
+      await mkdir(target, { recursive: true })
+      await writeAssetTo(asset, target)
+      manifest.assets.push({
+        kind: pinned.kind,
+        name: pinned.name,
+        revision: pinned.revision,
+        layout: pinned.layout,
+        size: pinned.size,
+        path: `.ab/${relPath}`,
+      })
+    }
+  }
+
   if (inputs.spec === true) {
     // §6.3 immutability: the spec a phase sees is the rev the spec.* events
     // anchor (spec.imported/authored/revised → state.specRev), never the