@defrex/autobuild 0.8.0

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

@@ -0,0 +1,111 @@
+import type {
+  BuildExecutionHandle,
+  BuildExecutionIdentity,
+  ExecutionObservation,
+} from './build-execution'
+
+/** Guest environment variable carrying the serialized harvest launch
+ * envelope, mirroring AB_BUILD_RUNNER_OPTIONS for build children. */
+export const HARVEST_RUNNER_OPTIONS_ENV = 'AB_HARVEST_RUNNER_OPTIONS'
+
+/** Where one hosted harvest run executed: the provider-native environment
+ * (and session) identity the provider supplies at launch time. */
+export interface HarvestExecutionEnvironment {
+  provider: string
+  environmentId: string
+  sessionId?: string
+}
+
+/** Immutable identity passed when a workspace provider is asked to start one
+ * hosted harvest execution. Unlike builds there is no durable workspace fact,
+ * so the provider resolves the disposable environment itself and reports it
+ * on the returned handle's identity; `workspaceRef` is therefore optional and
+ * advisory. Run state, config, and outcomes are obtained only through the
+ * repository journal in the Store. */
+export interface HarvestExecutionStart {
+  storeRef: string
+  /** Repository identity (normalized origin) the guest serves. */
+  repo: string
+  /** Supervisor instance id; doubles as the durable `execution` identity. */
+  instance: string
+  /** Remote base branch the disposable environment is provisioned from. */
+  baseBranch: string
+  workspaceRef?: string
+  /** Repository-lease holder the guest adopts from the owning dispatch loop:
+   * it skips its own claim, heartbeats this holder, and never releases. */
+  leaseHolder?: string
+  environment?: HarvestExecutionEnvironment
+}
+
+/** Serialized private-child envelope. A harvest guest is always owned by its
+ * environment — there is no local-parent mode (the guest outlives any host
+ * supervision and the environment owns teardown). */
+export type HarvestRunnerLaunch = HarvestExecutionStart & {
+  supervision: { kind: 'environment' }
+}
+
+/** Validate one parsed launch envelope. Invalid/missing envelopes make the
+ * guest exit 2 rather than guessing at a Store or lease identity. */
+export function parseHarvestRunnerLaunch(value: unknown): HarvestRunnerLaunch | undefined {
+  if (value === null || typeof value !== 'object') return undefined
+  const candidate = value as Partial<HarvestRunnerLaunch> & {
+    supervision?: Record<string, unknown>
+  }
+  if (
+    typeof candidate.storeRef !== 'string' ||
+    candidate.storeRef.length === 0 ||
+    typeof candidate.repo !== 'string' ||
+    candidate.repo.length === 0 ||
+    typeof candidate.instance !== 'string' ||
+    candidate.instance.length === 0 ||
+    typeof candidate.baseBranch !== 'string' ||
+    candidate.baseBranch.length === 0 ||
+    candidate.supervision === undefined
+  )
+    return undefined
+  if (candidate.supervision.kind !== 'environment') return undefined
+  if (Object.hasOwn(candidate.supervision, 'parentPid')) return undefined
+  if (
+    candidate.leaseHolder !== undefined &&
+    (typeof candidate.leaseHolder !== 'string' || candidate.leaseHolder.length === 0)
+  )
+    return undefined
+  if (
+    candidate.workspaceRef !== undefined &&
+    (typeof candidate.workspaceRef !== 'string' || candidate.workspaceRef.length === 0)
+  )
+    return undefined
+  const environment = candidate.environment
+  if (environment !== undefined) {
+    if (
+      typeof environment !== 'object' ||
+      typeof environment.provider !== 'string' ||
+      environment.provider.length === 0 ||
+      typeof environment.environmentId !== 'string' ||
+      environment.environmentId.length === 0
+    )
+      return undefined
+    if (
+      environment.sessionId !== undefined &&
+      (typeof environment.sessionId !== 'string' || environment.sessionId.length === 0)
+    )
+      return undefined
+  }
+  return candidate as HarvestRunnerLaunch
+}
+
+/** The substitutable seam at the workspace boundary for hosted harvest. A
+ * remote provider implements this by provisioning one disposable environment,
+ * launching the fixed harvest runner guest beside its checkout, and owning
+ * full teardown. Deliberately reuses the build execution handle/identity and
+ * observation types so supervision semantics (long-poll wait, teardown
+ * outcome, provider liveness) are identical to builds. */
+export interface HarvestExecution {
+  start(input: HarvestExecutionStart): 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>
+}
+
+export type { BuildExecutionHandle, ExecutionObservation }

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

@@ -0,0 +1,30 @@
+import type { BuildExecution, BuildExecutionHandle, BuildExecutionStart } from './build-execution'
+
+/** Deterministic test double. Production wiring never constructs this class;
+ * it keeps exhaustive scripted-agent scenarios in-process behind the same
+ * execution seam without weakening process isolation in the product path. */
+export class InProcessBuildExecution implements BuildExecution {
+  constructor(private readonly run: (input: BuildExecutionStart) => Promise<void>) {}
+
+  async start(input: BuildExecutionStart): Promise<BuildExecutionHandle> {
+    const completion = Promise.resolve()
+      .then(() => this.run(input))
+      .then(
+        () => ({ exitCode: 0 }),
+        () => ({ exitCode: 1 }),
+      )
+    return {
+      identity: { provider: 'in-process', workspaceRef: input.workspaceRef },
+      supervision: 'local-parent',
+      completion,
+      async stop() {
+        // Scripted test turns are finite. Cancellation behavior belongs to the
+        // real local supervisor tests rather than this deterministic double.
+        return { outcome: 'confirmed' }
+      },
+      async detach() {
+        // Scripted test turns are finite and leave nothing to reap.
+      },
+    }
+  }
+}

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

@@ -0,0 +1,88 @@
+import { distributionPath } from '../../distribution'
+import {
+  DEFAULT_PROCESS_GROUP_STOP_TIMEOUT_MS,
+  terminateProcessGroup,
+} from '../../processes/process-group'
+import type {
+  BuildExecution,
+  BuildExecutionExit,
+  BuildExecutionHandle,
+  BuildExecutionStart,
+} from './build-execution'
+
+export const BUILD_RUNNER_OPTIONS_ENV = 'AB_BUILD_RUNNER_OPTIONS'
+
+export interface LocalBuildExecutionOptions {
+  entrypoint?: string
+  env?: Record<string, string | undefined>
+  stopTimeoutMs?: number
+  spawn?: typeof Bun.spawn
+}
+
+/** Shipped local workspace+process implementation. stdio is ignored on
+ * purpose: child output can never become a private progress/outcome channel. */
+export class LocalBuildExecution implements BuildExecution {
+  private readonly entrypoint: string
+  private readonly env: Record<string, string | undefined>
+  private readonly stopTimeoutMs: number
+  private readonly spawn: typeof Bun.spawn
+
+  constructor(opts: LocalBuildExecutionOptions = {}) {
+    this.entrypoint = opts.entrypoint ?? distributionPath('bin', 'ab-build-runner.ts')
+    this.env = opts.env ?? process.env
+    this.stopTimeoutMs = opts.stopTimeoutMs ?? DEFAULT_PROCESS_GROUP_STOP_TIMEOUT_MS
+    this.spawn = opts.spawn ?? Bun.spawn
+  }
+
+  async start(input: BuildExecutionStart): Promise<BuildExecutionHandle> {
+    const child = this.spawn([process.execPath, this.entrypoint], {
+      env: {
+        ...this.env,
+        [BUILD_RUNNER_OPTIONS_ENV]: JSON.stringify({
+          ...input,
+          supervision: { kind: 'local-parent', parentPid: process.pid },
+        }),
+      },
+      stdin: 'ignore',
+      stdout: 'ignore',
+      stderr: 'ignore',
+      // On POSIX this makes the build child a new session and process-group
+      // leader. Every agent tool descendant inherits that group by default.
+      detached: true,
+    })
+    let reaping: Promise<void> | undefined
+    const reap = (): Promise<void> =>
+      (reaping ??= terminateProcessGroup(child.pid, this.stopTimeoutMs))
+    const leaderExit = child.exited.then(
+      (exitCode): BuildExecutionExit => ({
+        exitCode,
+        ...(child.signalCode !== null ? { signal: child.signalCode } : {}),
+      }),
+    )
+    const completion = leaderExit.then(async (exit) => {
+      // A naturally exited leader may leave inherited descendants behind.
+      await reap()
+      return exit
+    })
+
+    return {
+      pid: child.pid,
+      supervision: 'local-parent',
+      identity: {
+        provider: 'local-process',
+        workspaceRef: input.workspaceRef,
+        environmentId: String(child.pid),
+      },
+      completion,
+      stop: async () => {
+        await Promise.all([reap(), leaderExit])
+        return { outcome: 'confirmed' }
+      },
+      // A local execution cannot outlive its parent's teardown: detach is the
+      // same full reap as stop (the kernel reaps local children on teardown).
+      detach: async () => {
+        await Promise.all([reap(), leaderExit])
+      },
+    }
+  }
+}

package/packages/core/src/ports/workspace/operator-sandbox.ts

@@ -0,0 +1,142 @@
+/**
+ * Operator sandbox capability (AUT-340): one persistent, credential-free
+ * environment per operator × repository, provisioned like a build workspace
+ * and exposed to agent tools only through the registry. The provider owns
+ * environment mechanics; durable facts live in the repository journal; the
+ * caller supervises from the journal — the same split as the harvest
+ * execution capability.
+ *
+ * The credential-free rule (SPEC §14): the environment receives no store,
+ * forge, ticket-provider, or model credential, so the typed operator tools
+ * remain the only route to build state from inside a general-purpose agent
+ * shell. `SANDBOX_FORBIDDEN_ENV` is the one name set that rule is enforced
+ * from — config validation refuses forwarding any of them, and both adapters
+ * build guest command environments from an empty record (never the process
+ * environment) that can only ever contain forwarded names plus toolchain
+ * PATH. Lexical path validation in the service is not a sandbox boundary;
+ * the residual risk is bounded by this rule and by the guest network policy,
+ * which is the build workspace's upload-pack policy.
+ */
+
+/** Environment variable names that may never be forwarded into an operator
+ * sandbox — store, forge, ticket-provider, model, and Vercel credentials.
+ * One set, two enforcers: `[orchestrator].sandbox.environmentVariables`
+ * config validation (refuses any of these names) and the guest command
+ * environment both adapters build (starts from an empty record and adds only
+ * forwarded names plus the toolchain PATH). */
+export const SANDBOX_FORBIDDEN_ENV: readonly string[] = [
+  'AB_STORE',
+  'AB_TOKEN',
+  'GITHUB_TOKEN',
+  'GH_TOKEN',
+  'LINEAR_API_KEY',
+  'VERCEL_OIDC_TOKEN',
+  'VERCEL_TOKEN',
+  'VERCEL_TEAM_ID',
+  'VERCEL_PROJECT_ID',
+  'AI_GATEWAY_API_KEY',
+]
+
+/** Durable identity of one operator sandbox environment: the provider-scoped
+ * name tools re-derive and journal facts carry. Deterministic per
+ * (repository origin, operator) — there is at most one live environment per
+ * operator and repository. */
+export interface SandboxEnvironmentIdentity {
+  provider: string
+  /** Provider-scoped durable name (Vercel sandbox name / local worktree path). */
+  environmentId: string
+  /** Provider session, for journal facts. */
+  sessionId?: string
+  /** Checkout root inside the environment; tool file paths are rooted here. */
+  workspacePath: string
+}
+
+export interface SandboxCommandRequest {
+  command: string
+  cwd?: string
+  timeoutSeconds?: number
+}
+
+export interface SandboxCommandResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+/** State of one detached command. Vercel reports command output only after
+ * exit: while `running`, `stdout`/`stderr` stay undefined. */
+export interface SandboxWaitResult {
+  state: 'running' | 'exited'
+  exitCode?: number
+  stdout?: string
+  stderr?: string
+}
+
+/** Typed failure of one operator-sandbox operation. `stage` names where it
+ * failed so a tool caller sees `sandbox-<stage>` codes; the message carries
+ * the provider's text, redacted of credential values by the service. */
+export class SandboxOperationError extends Error {
+  override readonly name = 'SandboxOperationError'
+
+  constructor(
+    readonly stage:
+      | 'provision'
+      | 'resume'
+      | 'exec'
+      | 'exec-timeout'
+      | 'not-found'
+      | 'environment'
+      | 'reset'
+      | 'release',
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(message, options)
+  }
+}
+
+/** The substitutable seam at the workspace boundary for operator sandboxes.
+ * Every environment-deriving operation takes `{ repo, operator }` (plus
+ * `baseBranch` for `ensure`) so the one-environment-per-operator×repository
+ * invariant holds at the type level; per-environment operations take the
+ * resolved handle. Durable lifecycle facts are journaled by the caller
+ * (the sandbox service), never by the provider. */
+export interface OperatorSandboxExecution {
+  /** Pure resolution of the deterministic identity — no provisioning, no
+   * provider traffic beyond origin discovery. Used by release paths that
+   * must name the environment without creating one. */
+  describe(input: { repo: string; operator: string }): Promise<SandboxEnvironmentIdentity>
+  /** Provision on first use, resume after a stop. `baseBranch` selects the
+   * fresh-provision source; reuse/resume never re-checks it. */
+  ensure(input: {
+    repo: string
+    operator: string
+    baseBranch: string
+  }): Promise<SandboxEnvironmentIdentity>
+  exec(
+    handle: SandboxEnvironmentIdentity,
+    request: SandboxCommandRequest,
+  ): Promise<SandboxCommandResult>
+  start(
+    handle: SandboxEnvironmentIdentity,
+    request: SandboxCommandRequest,
+  ): Promise<{ commandId: string }>
+  wait(
+    handle: SandboxEnvironmentIdentity,
+    input: { commandId: string; waitSeconds: number },
+  ): Promise<SandboxWaitResult>
+  readFile(handle: SandboxEnvironmentIdentity, path: string): Promise<Uint8Array>
+  writeFile(handle: SandboxEnvironmentIdentity, path: string, content: Uint8Array): Promise<void>
+  /** Idle stop: end the session, keep the snapshot. `unsupported` lets local
+   * providers decline honestly. Both fields come from journal facts, so the
+   * dispatcher can call this without provisioning anything. */
+  stop(input: { operator: string; environmentId: string }): Promise<{
+    outcome: 'stopped' | 'absent' | 'unsupported'
+  }>
+  /** Full teardown + snapshot purge, by exact environment identity. */
+  release(input: {
+    repo: string
+    operator: string
+    environmentId: string
+  }): Promise<{ snapshots: { outcome: 'confirmed' | 'unknown'; deleted?: number; error?: string } }>
+}

package/packages/core/src/ports/workspace/phase-scratch.ts

@@ -0,0 +1,156 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+import type { Exec } from './git-worktree'
+
+export const PHASE_SCRATCH_PREFIX = '.ab/'
+
+async function git(exec: Exec, cwd: string, args: string[]): Promise<string> {
+  const result = await exec(['git', ...args], { cwd })
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `git ${args.join(' ')} exited ${result.exitCode}: ${result.stderr.trim() || result.stdout.trim() || '(no output)'}`,
+    )
+  }
+  return result.stdout
+}
+
+/** Parse Git's -z path output without treating whitespace or quoting specially. */
+export function parseNulPaths(output: string): string[] {
+  if (output === '') return []
+  if (!output.endsWith('\0')) throw new Error('git path output was not NUL-terminated')
+  const paths = output.slice(0, -1).split('\0')
+  if (paths.some((path) => path === '')) throw new Error('git path output contained an empty path')
+  return paths
+}
+
+export async function trackedScratchPaths(
+  exec: Exec,
+  workspacePath: string,
+  commit?: string,
+): Promise<string[]> {
+  const args = commit
+    ? ['ls-tree', '-r', '--name-only', '-z', commit, '--', '.ab']
+    : ['ls-files', '-z', '--', '.ab']
+  return [...new Set(parseNulPaths(await git(exec, workspacePath, args)))].sort()
+}
+
+/** Restore the exact index versions removed by a disposable scratch wipe. */
+export async function restoreTrackedScratch(
+  exec: Exec,
+  workspacePath: string,
+  paths: readonly string[],
+): Promise<void> {
+  if (paths.length === 0) return
+  await git(exec, workspacePath, ['checkout-index', '--force', '--', ...paths])
+}
+
+/** Keep generated scratch ignored even when a legacy repo tracks .ab/.gitignore. */
+export async function ensureScratchExcluded(exec: Exec, workspacePath: string): Promise<void> {
+  const raw = (await git(exec, workspacePath, ['rev-parse', '--git-path', 'info/exclude'])).trim()
+  if (raw === '') throw new Error('git rev-parse returned no exclude path')
+  const path = isAbsolute(raw) ? raw : join(workspacePath, raw)
+  let content = ''
+  try {
+    content = await readFile(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+  const lines = content.split(/\r?\n/)
+  if (lines.includes('.ab/')) return
+  await mkdir(dirname(path), { recursive: true })
+  const separator = content === '' || content.endsWith('\n') ? '' : '\n'
+  await writeFile(path, `${content}${separator}.ab/\n`)
+}
+
+function collides(path: string, unavailable: ReadonlySet<string>): boolean {
+  for (const other of unavailable) {
+    if (path === other || path.startsWith(`${other}/`) || other.startsWith(`${path}/`)) return true
+  }
+  return false
+}
+
+/** Allocate a stable path relative to .ab without overwriting tracked content. */
+export function allocateScratchPath(
+  desired: string,
+  tracked: ReadonlySet<string>,
+  allocated: Set<string>,
+): string {
+  const unavailable = new Set([...tracked, ...allocated])
+  const conventional = `${PHASE_SCRATCH_PREFIX}${desired}`
+  if (!collides(conventional, unavailable)) {
+    allocated.add(conventional)
+    return desired
+  }
+  for (let index = 1; ; index += 1) {
+    const candidate = `generated/${index}/${desired}`
+    if (!collides(`${PHASE_SCRATCH_PREFIX}${candidate}`, unavailable)) {
+      allocated.add(`${PHASE_SCRATCH_PREFIX}${candidate}`)
+      return candidate
+    }
+  }
+}
+
+async function changedScratchPaths(
+  exec: Exec,
+  workspacePath: string,
+  from: string,
+  to: string,
+): Promise<Set<string>> {
+  return new Set(
+    parseNulPaths(
+      await git(exec, workspacePath, ['diff', '--name-only', '-z', from, to, '--', '.ab']),
+    ),
+  )
+}
+
+/** Every scratch path touched by any commit, including changes later reverted. */
+export async function scratchPathsTouchedInRange(
+  exec: Exec,
+  workspacePath: string,
+  base: string,
+  head: string,
+): Promise<string[]> {
+  const commits = (await git(exec, workspacePath, ['rev-list', '--reverse', `${base}..${head}`]))
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+  const touched = new Set<string>()
+  for (const commit of commits) {
+    const parents = (await git(exec, workspacePath, ['rev-list', '--parents', '-n', '1', commit]))
+      .trim()
+      .split(/\s+/)
+      .slice(1)
+    for (const parent of parents) {
+      for (const path of await changedScratchPaths(exec, workspacePath, parent, commit)) {
+        touched.add(path)
+      }
+    }
+  }
+  return [...touched].sort()
+}
+
+/** Merge-authored scratch differs from every parent; inherited bytes are safe. */
+export async function reconcileScratchViolations(
+  exec: Exec,
+  workspacePath: string,
+  head: string,
+  parents: readonly string[],
+): Promise<string[]> {
+  let intersection: Set<string> | undefined
+  for (const parent of parents) {
+    const changed = await changedScratchPaths(exec, workspacePath, parent, head)
+    intersection =
+      intersection === undefined
+        ? changed
+        : new Set([...intersection].filter((path) => changed.has(path)))
+  }
+  return [...(intersection ?? [])].sort()
+}
+
+export function phaseScratchRejection(paths: readonly string[]): Error {
+  return new Error(
+    `publication rejected: commits must not add, modify, or delete paths under .ab/:\n` +
+      `${paths.map((path) => `  ${path}`).join('\n')}\n` +
+      'Unstage or drop the .ab/ change, amend the commit if needed, then retry completion.',
+  )
+}