@defrex/autobuild 0.8.0

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

@@ -0,0 +1,528 @@
+/**
+ * Ports (SPEC §3.2): interfaces to the world, each with swappable adapters.
+ * The kernel and processes depend only on these types; adapters live in
+ * `ports/<port>/` and fakes for seam tests in `ports/fakes/`.
+ */
+import type {
+  HostedPrAttachmentAsset,
+  PrAttachment,
+  PrImageHostTarget,
+  TicketRef,
+  WorkspaceBase,
+} from '../ontology'
+import type { StreamOutcome, StreamPart } from '../store/streams/types'
+import type { BuildExecution } from './workspace/build-execution'
+import type { HarvestExecution } from './workspace/harvest-execution'
+import type { OperatorSandboxExecution } from './workspace/operator-sandbox'
+
+// ── Session streams (SPEC §9) ─────────────────────────────────────────────
+//
+// The live, protocol-shaped view of a build session: a runner that holds the
+// optional streaming capability translates its harness's native output into
+// AI SDK UI Message Stream parts and appends them as they happen. Streams
+// are presentation, never routing; outcomes still travel only the typed CLI.
+
+/**
+ * The per-turn write side of a session stream. `append` NEVER throws: a
+ * failing stream path must never fail a turn. Adapters call it with the
+ * part vocabulary of `ai-ui-message-stream/v1` plus the `data-ab-*`
+ * extension parts.
+ */
+export interface SessionStreamEmitter {
+  append(parts: StreamPart[]): void
+}
+
+/**
+ * The bracket-scoped sink a runtime registration's `openSessionStream`
+ * capability receives: `open` creates the store stream and returns its id,
+ * after which the sink is also an emitter; `close` is idempotent (first
+ * outcome wins) and best-effort.
+ */
+export interface SessionStreamSink extends SessionStreamEmitter {
+  open(label: string): Promise<string>
+  close(outcome: StreamOutcome): Promise<void>
+}
+
+// ── TicketSource (SPEC §3.2, §13) ────────────────────────────────────────────
+//
+// Policy (§13): the TicketSource initiates and receives projections; it is
+// never consulted mid-build and never used as artifact storage. A file-based
+// adapter with nowhere to put blobs must be fully workable.
+
+export interface Ticket {
+  ref: TicketRef
+  /** Stable source-native key used to correlate an externally created ticket
+   * with Autobuild's durable creation reservation. It is separate from the
+   * operator-facing `ref.id` and optional for legacy/plugin projections. */
+  creationKey?: string
+  title: string
+  /** The ticket body — pre-build, the spec lives here (§6.3). */
+  body: string
+  state?: string
+  labels: string[]
+  /** Source-local ids of tickets declared as blockers. Absent ≡ none. */
+  blockedBy?: string[]
+}
+
+/** A partial source scan. Diagnostics name source records that were excluded
+ * from eligibility; infrastructure failures and source-wide invariants still
+ * reject `listReady` rather than appearing here. */
+export interface TicketListing {
+  tickets: Ticket[]
+  diagnostics: string[]
+}
+
+export interface TicketDraft {
+  title: string
+  body: string
+  /** Labels applied at creation. Names need not already exist in the source;
+   * adapters own any provider-side label-registry reconciliation. */
+  labels?: string[]
+  /** Source-local blocker ids, recorded natively at creation (§13). An
+   * adapter must record every one or throw — never discard silently. */
+  blockedBy?: string[]
+}
+
+/** One node of the dependency graph, as this source sees it. */
+export interface DependencyState {
+  /** The requested source-local id, echoed back. */
+  id: string
+  /** False = no such ticket in this source. */
+  exists: boolean
+  /**
+   * Complete per this source's NATIVE lifecycle semantics — the adapter owns
+   * this meaning and callers must not re-derive it from `state` (§13: the
+   * provider's taxonomy never leaks above the port). Linear: `state.type` in
+   * `completed | canceled`. File: state equals the source's done state.
+   */
+  resolved: boolean
+  /** This node's own declared blockers, so callers can close the graph. */
+  blockedBy: string[]
+}
+
+export interface TicketCreateOptions {
+  /** Explicit workflow state for this create (harvest always targets Triage). */
+  state?: string
+  /** Source-level adoption key for crash-safe external creation. File and fake
+   * sources treat it as opaque; Linear requires a durably reserved UUID v4,
+   * sends it verbatim as the issue id, and queries that id when adopting. */
+  idempotencyKey?: string
+}
+
+/** Editable ticket fields. Omitted fields are preserved; state is deliberately
+ * absent because `transition()` exclusively owns lifecycle changes. */
+export interface TicketUpdate {
+  /** Required when named: an update cannot clear the ticket's title. */
+  title?: string
+  /** Required when named: pre-build, this is the spec (§6.3). */
+  body?: string
+  /** A complete label replacement. An explicit empty array clears labels.
+   * Names need not already exist in the source; adapters own any
+   * provider-side label-registry reconciliation. */
+  labels?: string[]
+}
+
+export interface TicketSource {
+  readonly name: string
+  /** Ready tickets matching the dispatch criteria (label/state — §3.3), plus
+   * actionable diagnostics for individual source records excluded as invalid.
+   * Fatal source failures and invariants still reject the call. */
+  listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing>
+  get(id: string): Promise<Ticket | null>
+  /** Claim-before-launch (§12): acquires nonterminal work and returns true.
+   * Returns false for an unknown, already-claimed/contested, or terminal ticket.
+   * Refusing a terminal ticket leaves its state unchanged; claim never reopens
+   * completed work. An explicit transition to a nonterminal state permits a
+   * later claim. */
+  claim(id: string): Promise<boolean>
+  comment(id: string, body: string): Promise<void>
+  transition(id: string, state: string): Promise<void>
+  create(draft: TicketDraft, opts?: TicketCreateOptions): Promise<Ticket>
+  /** Partially replace editable fields. The patch must be nonempty and strict;
+   * omitted fields (including unmodeled provider metadata) remain untouched. */
+  update(id: string, patch: TicketUpdate): Promise<void>
+  /** Add one same-source blocker. Retries are idempotent; the target and
+   * blocker must exist, and a ticket may not block itself. */
+  addBlocker(id: string, blockerId: string): Promise<void>
+  /** Remove one same-source blocker. Missing relations are successful no-ops;
+   * only the target ticket is required to still exist. */
+  removeBlocker(id: string, blockerId: string): Promise<void>
+  /**
+   * Dependency-graph nodes for `ids`. The result covers EVERY requested id, in
+   * request order; a missing id comes back `{exists: false, resolved: false,
+   * blockedBy: []}`. Read at ticket creation and at dispatch time only — both
+   * are initiation, so §13's "never consulted mid-build" is untouched.
+   */
+  dependencyStates(ids: string[]): Promise<DependencyState[]>
+}
+
+// ── Workspace (SPEC §3.2, §7) ────────────────────────────────────────────────
+
+export interface WorkspaceHandle {
+  provider: string
+  /** Provider-scoped identifier (worktree path or sandbox name). */
+  ref: string
+  /** Absolute working-copy path in the provider's execution environment. It
+   * is not necessarily reachable from the dispatcher. */
+  path: string
+  /** Dispatcher-reachable path when one exists. Remote providers omit it. */
+  localPath?: string
+  branch: string
+}
+
+export interface WorkspaceProvisionResult extends WorkspaceHandle {
+  /** Durable evidence for the commit this provision selected or reused. */
+  base: WorkspaceBase
+}
+
+export interface WorkspacePublication {
+  /** Observe whether the exact requested commit already reached the durable
+   * remote branch after an interrupted acknowledgement. */
+  isPublished?(input: { sha: string; branch: string }): Promise<boolean>
+  /** Publish exactly one commit to exactly one branch; no arbitrary command
+   * surface is exposed to the dispatcher or build child. */
+  publish(input: { ref: string; sha: string; branch: string }): Promise<void>
+}
+
+/** Snapshot-purge evidence recorded with a workspace cleanup fact. Absence of
+ * leftover snapshots can be proven from these durable events without querying
+ * the provider. */
+export interface WorkspaceReapSnapshots {
+  outcome: 'confirmed' | 'absent' | 'unknown'
+  deleted?: number
+  error?: string
+}
+
+export interface WorkspaceReapOutcome {
+  outcome: 'confirmed' | 'absent'
+  snapshots: WorkspaceReapSnapshots
+}
+
+export interface WorkspaceRecovery {
+  /** Fence an unavailable environment. Unknown outcomes must reject so the
+   * dispatcher retains the lease/workspace fact and retries after its fence. */
+  reap(handle: WorkspaceHandle): Promise<WorkspaceReapOutcome>
+}
+
+export interface WorkspaceProvider {
+  readonly name: string
+  /** Optional workspace-adjacent executor. Remote providers substitute here;
+   * locally reachable providers use the shipped subprocess capability. */
+  readonly buildExecution?: BuildExecution
+  /** Optional hosted-harvest executor. Present on providers that can
+   * provision a disposable environment for harvest sessions; its absence
+   * keeps harvest running locally in the dispatcher's workspace. */
+  readonly harvestExecution?: HarvestExecution
+  /** Optional operator-sandbox host (AUT-340): one persistent,
+   * credential-free environment per operator × repository behind registry
+   * tools. Present on providers that can provision it; absent means the
+   * provider cannot host an operator sandbox, and sandbox tools stay
+   * unavailable over that provider. */
+  readonly orchestratorSandbox?: OperatorSandboxExecution
+  /** Trusted dispatcher-only publication capability for remote workspaces. */
+  readonly publication?: WorkspacePublication
+  /** Optional only for remote/disposable providers. */
+  readonly recovery?: WorkspaceRecovery
+  provision(opts: {
+    repo: string
+    baseBranch: string
+    branch: string
+    /** Immutable recovery checkpoint, never a moved base branch. */
+    revision?: string
+    /** Monotonic environment generation used in provider idempotency keys. */
+    generation?: number
+  }): Promise<WorkspaceProvisionResult>
+  release(handle: WorkspaceHandle): Promise<void>
+}
+
+// ── Forge (SPEC §3.2, §8.6, §15.7) ───────────────────────────────────────────
+//
+// D7: agents never touch the remote — push, PR creation, and forge API calls
+// are plumbing triggered by terminal commands. D1: PR→main is squash merge,
+// main→feature is a merge commit, rebase is banned.
+
+export interface PrRef {
+  number: number
+  /** Provider locator. HTTP(S) when the forge has a web UI; otherwise a
+   * meaningful provider-native identifier such as a local Git ref. */
+  url: string
+  headSha: string
+}
+
+export type PrState =
+  | { state: 'open'; mergeable: boolean | null }
+  | { state: 'merged'; sha: string }
+  | { state: 'closed' }
+
+/** Abort cleanup may race landing. A merged result is terminal and must never
+ * be overwritten by a close attempt. */
+export type ClosePrResult = { state: 'closed' } | { state: 'merged'; sha: string }
+
+/** Result of reconciling durable auto-merge intent with the forge. Native
+ * state is acknowledged only by `applied`; the other results deliberately
+ * leave the command pending for a later janitor poll. */
+export type AutoMergeDeferralCode =
+  | 'github-plan-limitation'
+  | 'repository-auto-merge-disabled'
+  | 'unproven-gate-state'
+  /** A persistent, definite state — GitHub has computed merge conflicts with
+   * the base branch. Recovery is updating the branch or resolving the
+   * conflicts, not gate-state investigation. */
+  | 'merge-conflicts'
+  /** Mergeability not yet computed — transient, resolves on retry. */
+  | 'mergeability-uncomputed'
+  | 'local-base-checkout-dirty'
+  | 'local-git-identity-missing'
+
+/** How a deferral resolves. `pipeline-resolved` codes are recovered by the
+ * pipeline itself — reconcile for merge conflicts, a later poll for
+ * not-yet-computed mergeability — and record no operator observation.
+ * `human-actionable` codes need a person to fix the named condition and keep
+ * the one-observation-per-PR-and-command rule. Adding a code without choosing
+ * a class is a compile error. */
+export type AutoMergeDeferralClass = 'pipeline-resolved' | 'human-actionable'
+
+export const autoMergeDeferralClasses = {
+  'github-plan-limitation': 'human-actionable',
+  'repository-auto-merge-disabled': 'human-actionable',
+  'unproven-gate-state': 'human-actionable',
+  'merge-conflicts': 'pipeline-resolved',
+  'mergeability-uncomputed': 'pipeline-resolved',
+  'local-base-checkout-dirty': 'human-actionable',
+  'local-git-identity-missing': 'human-actionable',
+} as const satisfies Record<AutoMergeDeferralCode, AutoMergeDeferralClass>
+
+export interface AutoMergeDeferralReason {
+  /** Stable machine-readable family used by durable operator observations. */
+  code: AutoMergeDeferralCode
+  /** Provider detail. It must identify auto-merge inspection/application, not PR creation. */
+  detail: string
+}
+
+export type AutoMergeResult =
+  | { kind: 'applied' }
+  | { kind: 'ungated'; headSha: string }
+  | { kind: 'deferred'; reason?: AutoMergeDeferralReason }
+
+/** One explicitly designated image artifact to copy to a review-window host. */
+export interface PrAttachmentUploadRequest {
+  workspacePath: string
+  target: PrImageHostTarget
+  prUrl: string
+  attachment: PrAttachment
+  content: Uint8Array
+  /** Full lowercase SHA-256 / BuildStore blobRef for `content`. */
+  sha256: string
+}
+
+export interface PrAttachmentReclaimRequest {
+  /** Cleanup deliberately runs from the main repository after workspace removal. */
+  workspacePath: string
+  asset: HostedPrAttachmentAsset
+}
+
+/** Narrow optional Forge capability. Its absence is a supported text-only
+ * path, not a verification outcome. */
+export interface PrAttachmentHosting {
+  upload(request: PrAttachmentUploadRequest): Promise<HostedPrAttachmentAsset>
+  reclaim(request: PrAttachmentReclaimRequest): Promise<void>
+}
+
+export interface Forge {
+  readonly name: string
+  /** Optional because another forge may support PRs but not public image assets. */
+  readonly prAttachments?: PrAttachmentHosting
+  /** Publish the workspace's current HEAD to this remote destination branch. */
+  pushBranch(workspacePath: string, branch: string): Promise<void>
+  openPr(opts: {
+    workspacePath: string
+    head: string
+    base: string
+    title: string
+    body: string
+    /** Untouched deposited pr-description. Providers may use it as the
+     * landing message; title/body remain the portable review projection. */
+    mergeMessage?: string
+  }): Promise<PrRef>
+  /** Optional authoritative base resolver. Capability-less adapters retain
+   * the legacy origin fetch performed by the caller. The destination is a
+   * build-private ref in the workspace's shared Git database. */
+  snapshotBase?(opts: {
+    workspacePath: string
+    base: string
+    destinationRef: string
+  }): Promise<string>
+  /** Janitor poll (§15.7): merged/closed/mergeability for one PR. */
+  getPrState(workspacePath: string, number: number): Promise<PrState>
+  /** Optional additive abort-cleanup capabilities. Older plugins remain
+   * loadable, but cleanup stays pending with an actionable diagnostic. */
+  closePr?(workspacePath: string, number: number): Promise<ClosePrResult>
+  deleteBranch?(workspacePath: string, branch: string): Promise<void>
+  /**
+   * Reconcile GitHub-native auto-merge desired state. Enabling returns an
+   * ungated candidate only after proving the base branch has no merge-blocking
+   * gate. Transient merge states defer quietly; non-transient inability to
+   * inspect or apply consent returns a reason-bearing deferral. The operation
+   * is idempotent and safe to retry across the forge-call/event-append crash window.
+   */
+  setAutoMerge(workspacePath: string, number: number, enabled: boolean): Promise<AutoMergeResult>
+  /**
+   * Perform a normal squash merge, guarded by the inspected PR head. This is
+   * never an admin/force operation: forge-side protection still applies.
+   */
+  squashMerge(workspacePath: string, number: number, expectedHeadSha: string): Promise<void>
+  /** Post the build's summary comment (§7.5). */
+  commentOnPr(workspacePath: string, number: number, body: string): Promise<void>
+  /** Optional checkout-less capability: the current tip of a remote branch.
+   * Throws when the branch does not exist (including 404); callers decide
+   * whether absence is an error or an `undefined`. Its absence retains the
+   * legacy host `git ls-remote` base resolution. */
+  remoteBranchSha?(branch: string): Promise<string>
+  /** Optional checkout-less capability: raw file bytes from the repository.
+   * Ref omitted → the repository's default branch. Throws when the path does
+   * not exist. Its absence retains reading configuration from a checkout. */
+  readFile?(path: string, ref?: string): Promise<string>
+}
+
+// ── AgentRunner (SPEC §9) ────────────────────────────────────────────────────
+//
+// Session-based, because review loops need memory: the producer *continues*
+// its session across rounds; the reviewer gets a fresh one each round (§10).
+// Every production adapter also exposes this distribution's `ab` launcher at
+// the front of the tool environment's PATH; CLI availability is a runner
+// guarantee and does not depend on a global installation or host ordering.
+
+export interface AgentSessionHandle {
+  id: string
+  runner: string
+  model?: string
+}
+
+interface AgentTurnResultBase {
+  /** Final text of the turn — informational only; outcomes travel the typed
+   * channel (`ab done|verdict|escalate`), never parsed from output (§8.4). */
+  text: string
+  usage: { inputTokens: number; outputTokens: number; turns: number }
+}
+
+/** A turn whose provider/runtime completed normally. This does not mean the
+ * phase completed: only a typed terminal event can express that outcome. */
+export interface AgentTurnCompleted extends AgentTurnResultBase {
+  kind: 'completed'
+}
+
+export type AgentFailureCause = 'availability' | 'exhaustion' | 'credentials' | 'configuration'
+
+export interface AgentTurnFailure {
+  /** Provider/runner text, preserved verbatim when one was supplied. */
+  message: string
+  /** False means "apply the existing bounded retry policy"; it does not claim
+   * the failure is transient. True remains the compatibility signal used by
+   * retry policy. Provider exhaustion is permanent for retry purposes while
+   * still being eligible for a configured alternate. */
+  permanent: boolean
+  /** Additive structured routing cause. Legacy plugin runners may omit it;
+   * their existing permanent bit then supplies the conservative behavior. */
+  cause?: AgentFailureCause
+}
+
+/** A turn that reached a provider/runtime-declared failure while retaining an
+ * endable session handle, so transcript deposition remains guaranteed. */
+export interface AgentTurnFailed extends AgentTurnResultBase {
+  kind: 'failed'
+  failure: AgentTurnFailure
+}
+
+/** SDK/provider-declared failures must use the failed variant. A completed turn
+ * with no typed terminal is the distinct `no-terminal` condition (§8.4). */
+export type AgentTurnResult = AgentTurnCompleted | AgentTurnFailed
+
+/** Transcripts come back through the interface, not scraped from disk (§9). */
+export interface Transcript {
+  content: string
+  metadata: {
+    runner: string
+    model?: string
+    usage: { inputTokens: number; outputTokens: number; turns: number }
+  }
+}
+
+export interface AgentStartOpts {
+  /** Installed skill to invoke, e.g. `ab-plan`. */
+  skill: string
+  /** Opaque argument passed to the skill (build slug or harvest run id). */
+  invocation?: string
+  /** Backward-compatible build name; new callers should also set invocation. */
+  buildSlug?: string
+  workspacePath: string
+  model?: string
+  /** Extra CLI argv tokens for the selected runtime, in declared order. */
+  args?: readonly string[]
+  /** Scoped ambient auth (D8): AB_STORE, AB_BUILD, AB_PHASE, AB_SESSION,
+   * AB_TOKEN. Adapters merge it over their process environment and then apply
+   * the runner-controlled Autobuild CLI PATH prefix. */
+  env: Record<string, string>
+  /** Caller-owned cancellation for this turn. Aborting must leave any created
+   * session endable so its transcript can still be deposited. */
+  signal?: AbortSignal
+  /** Live session stream, present only when the resolved runtime declared
+   * the streaming capability (SPEC §9). A turn without it emits no parts. */
+  stream?: SessionStreamEmitter
+}
+
+/** Per-turn refresh for a continued session (§10): each continue turn is a
+ * NEW session bracket (next round, fresh session id), so the runner
+ * re-issues ambient auth for the turn (D8) — merged over the start env. A
+ * turn left on round 1's env would have the CLI resolve the stale round and
+ * reject the continued round's terminal as a D5 second call (§8.4). */
+export function agentInvocation(opts: AgentStartOpts): string {
+  const invocation = opts.invocation ?? opts.buildSlug
+  if (invocation === undefined || invocation === '') {
+    throw new Error('AgentStartOpts requires a non-empty invocation')
+  }
+  return invocation
+}
+
+export interface AgentContinueOpts {
+  env?: Record<string, string>
+  /** Caller-owned cancellation for this continued turn. */
+  signal?: AbortSignal
+  /** Live session stream, present only when the resolved runtime declared
+   * the streaming capability (SPEC §9). A turn without it emits no parts. */
+  stream?: SessionStreamEmitter
+}
+
+export interface AgentRunner {
+  readonly name: string
+  start(opts: AgentStartOpts): Promise<{ session: AgentSessionHandle; result: AgentTurnResult }>
+  /** Review-loop rounds (§10). Adapters without native resumption implement
+   * this as start-with-rehydrate-from-store (§9). */
+  continue(
+    session: AgentSessionHandle,
+    message: string,
+    opts?: AgentContinueOpts,
+  ): Promise<AgentTurnResult>
+  /** Always called; the transcript goes to the store — the corpus is
+   * guaranteed complete (§9). */
+  end(session: AgentSessionHandle): Promise<Transcript>
+}
+
+// ── TelemetrySource (SPEC §3.2, §12) ─────────────────────────────────────────
+
+export interface Signal {
+  source: string
+  id: string
+  title: string
+  url?: string
+  /** Evidence for the proposal this signal may become (spec standard §6.1). */
+  evidence: Record<string, unknown>
+  occurrences?: number
+  usersAffected?: number
+  firstSeen?: string
+  lastSeen?: string
+}
+
+export interface TelemetrySource {
+  readonly name: string
+  fetchSignals(since?: string): Promise<Signal[]>
+}

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

@@ -0,0 +1,123 @@
+/** Immutable identity passed when a workspace-adjacent executor is asked to
+ * start a build. Build state, workspace location, config, progress, and outcome
+ * are deliberately absent: both sides obtain those only from the BuildStore. */
+export interface BuildExecutionStart {
+  slug: string
+  storeRef: string
+  instance: string
+  /** Provider-native locator from the current workspace.provisioned fact. */
+  workspaceRef: string
+}
+
+/** Serialized private-child envelope. Host PIDs are meaningful only to the
+ * local executor; an environment-owned VM is supervised as one unit by its
+ * provider. Keeping the modes discriminated prevents accidental cross-namespace
+ * signalling. */
+export type BuildChildLaunch = BuildExecutionStart &
+  (
+    | { supervision: { kind: 'local-parent'; parentPid: number } }
+    | { supervision: { kind: 'environment' } }
+  )
+
+export function parseBuildChildLaunch(value: unknown): BuildChildLaunch | undefined {
+  if (value === null || typeof value !== 'object') return undefined
+  const candidate = value as Partial<BuildChildLaunch> & { supervision?: Record<string, unknown> }
+  if (
+    typeof candidate.slug !== 'string' ||
+    candidate.slug.length === 0 ||
+    typeof candidate.storeRef !== 'string' ||
+    candidate.storeRef.length === 0 ||
+    typeof candidate.instance !== 'string' ||
+    candidate.instance.length === 0 ||
+    typeof candidate.workspaceRef !== 'string' ||
+    candidate.workspaceRef.length === 0 ||
+    candidate.supervision === undefined
+  )
+    return undefined
+  const supervision = candidate.supervision
+  if (supervision.kind === 'environment') {
+    if (Object.hasOwn(supervision, 'parentPid')) return undefined
+    return candidate as BuildChildLaunch
+  }
+  if (
+    supervision.kind === 'local-parent' &&
+    Number.isInteger(supervision.parentPid) &&
+    (supervision.parentPid as number) > 0
+  )
+    return candidate as BuildChildLaunch
+  return undefined
+}
+
+export const BUILD_EXECUTION_LEASE_TTL_MS = 60_000
+
+/** Child exit is liveness evidence only. It carries no pipeline outcome. */
+export interface BuildExecutionExit {
+  exitCode: number | null
+  signal?: string
+}
+
+/** Immutable provider identity recorded as soon as an execution starts. */
+export interface BuildExecutionIdentity {
+  provider: string
+  workspaceRef: string
+  /** Provider-native VM/container identity when it differs from workspaceRef. */
+  environmentId?: string
+  /** Provider-native session identity. A resumed persistent VM gets a new one. */
+  sessionId?: string
+  /** Provider-native detached command identity, recorded durably at launch so
+   * a later process can re-observe the execution without process memory. */
+  commandId?: string
+}
+
+/** Teardown must distinguish proof from an interrupted/ambiguous acknowledgement. */
+export type BuildExecutionTeardownResult =
+  | { outcome: 'confirmed' | 'absent' }
+  | { outcome: 'unknown'; error: string }
+
+/** How a handle's lifetime is tied to its supervising process. `local-parent`
+ * means the kernel owns the process tree and must reap it at teardown;
+ * `environment` means the guest environment owns the execution and the kernel
+ * supervises only its local wait — teardown detaches instead of stopping, so
+ * the guest outlives the supervising process and a later invocation settles
+ * the execution from the Store plus provider liveness. */
+export type BuildExecutionSupervision = 'local-parent' | 'environment'
+
+export interface BuildExecutionHandle {
+  /** Available for supervision/tests, never used as build state. */
+  readonly pid?: number
+  readonly identity?: BuildExecutionIdentity
+  /** Explicit supervision kind. Never inferred from `environmentId` — a local
+   * pid and a remote VM id are different namespaces. */
+  readonly supervision: BuildExecutionSupervision
+  /** Resolves only after the execution environment has reaped everything the
+   * build started. The exit projection still describes the build leader. */
+  readonly completion: Promise<BuildExecutionExit>
+  /** Idempotent shutdown: graceful, bounded force escalation, then full reap. */
+  stop(): Promise<BuildExecutionTeardownResult | void>
+  /** Stop supervising without touching the environment: abort the local wait
+   * only. No command kill, no environment stop, no lease release, no
+   * `execution.ended`, no publication settlement. The teardown mode when the
+   * guest must outlive the supervising process. */
+  detach(): Promise<void>
+}
+
+/** Provider liveness observation of one recorded execution, derived from
+ * provider state rather than process memory. `ended` carries the observed
+ * exit code; `lost` means the provider proved the environment/command no
+ * longer exists without an exit code. */
+export type ExecutionObservation =
+  | { state: 'running' }
+  | { state: 'ended'; exitCode?: number }
+  | { state: 'lost' }
+
+/** The substitutable seam at the workspace boundary. A remote workspace
+ * 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 BuildExecution {
+  start(input: BuildExecutionStart): 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"). */
+  observe?(identity: BuildExecutionIdentity): Promise<ExecutionObservation>
+}