@defrex/autobuild 0.8.0

package/bin/ab-build-runner.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/** Private shipped child: one operating-system process per build. */
+import { runBuildChild } from '../packages/core/src/processes/build-child'
+import { BuildChildExitCoordinator } from '../packages/core/src/processes/build-child-exit'
+import { watchBuildParent } from '../packages/core/src/processes/build-parent-watch'
+import { BUILD_RUNNER_OPTIONS_ENV } from '../packages/core/src/ports/workspace/local-build-execution'
+import {
+  parseBuildChildLaunch,
+  type BuildChildLaunch,
+} from '../packages/core/src/ports/workspace/build-execution'
+
+const raw = process.env[BUILD_RUNNER_OPTIONS_ENV]
+let input: BuildChildLaunch | undefined
+try {
+  input = parseBuildChildLaunch(raw === undefined ? undefined : JSON.parse(raw))
+} catch {
+  // Invalid immutable launch envelope exits below.
+}
+if (input === undefined) process.exit(2)
+
+let exitCode = 0
+if (input.supervision.kind === 'local-parent') {
+  // Every local exit first transfers group teardown to an owner outside this
+  // session. Environment-owned execution deliberately installs neither this
+  // group reaper nor a meaningless host-PID watchdog.
+  const terminal = new BuildChildExitCoordinator({ groupId: process.pid })
+  process.on('SIGINT', () => terminal.terminate(130))
+  process.on('SIGTERM', () => terminal.terminate(143))
+  terminal.setParentWatch(
+    watchBuildParent(input.supervision.parentPid, () => terminal.terminate(143)),
+  )
+  try {
+    await runBuildChild(input, process.env)
+  } catch {
+    exitCode = 1
+  }
+  terminal.terminate(exitCode)
+} else {
+  // Vercel owns teardown of the complete VM session. Addressing a POSIX group
+  // here could leave the SDK believing a still-running environment completed.
+  try {
+    await runBuildChild(input, process.env)
+  } catch {
+    exitCode = 1
+  }
+  process.exit(exitCode)
+}

package/bin/ab-dev.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+/** Repo-local Bun hot entry. This file is not exposed through package.json#bin. */
+import { runBinary } from '../packages/core/src/cli/binary'
+import { evaluateDevCli, type DevCliState } from '../packages/core/src/cli/dev'
+import { renderDashboard } from '../packages/core/src/cli/dashboard/render'
+
+const STATE_KEY = Symbol.for('autobuild.cli.dashboard-dev')
+const globals = globalThis as unknown as Record<symbol, DevCliState | undefined>
+const state = globals[STATE_KEY] ?? {}
+globals[STATE_KEY] = state
+
+// Do not top-level-await: Bun must be able to finish evaluating this module and
+// evaluate it again when presentation sources change.
+evaluateDevCli({
+  state,
+  renderer: renderDashboard,
+  launch: (resolveDashboardRenderer) => runBinary(process.argv.slice(2), resolveDashboardRenderer),
+  settle: (run) => {
+    void run.then(
+      (code) => process.exit(code),
+      (error: unknown) => {
+        console.error(error instanceof Error ? error.message : String(error))
+        process.exit(1)
+      },
+    )
+  },
+})

package/bin/ab-dispatch-kernel.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env bun
+/** Private, shipped child for the interactive `ab dispatch` kernel. It owns no
+ * terminal handles; the public command launches it with immutable options. */
+import { abDispatch } from '../packages/core/src/cli/dispatch'
+import {
+  DISPATCH_CHILD_OPTIONS_ENV,
+  type DispatchChildOptions,
+  installDispatchKernelSignalHandlers,
+  watchDispatchParent,
+} from '../packages/core/src/cli/dispatch-process'
+import { DISPATCHER } from '../packages/core/src/events/envelope'
+import { spawnExec } from '../packages/core/src/ports/workspace/git-worktree'
+import { resolveRepoState } from '../packages/core/src/cli/repo-state'
+import { openStoreForRepoState } from '../packages/core/src/cli/store-opening'
+
+const raw = process.env[DISPATCH_CHILD_OPTIONS_ENV]
+if (raw === undefined) process.exit(2)
+let options: DispatchChildOptions
+try {
+  options = JSON.parse(raw) as DispatchChildOptions
+} catch {
+  process.exit(2)
+}
+
+const stop = new AbortController()
+const requestStop = (): void => stop.abort()
+// Keep both handlers installed through the complete graceful drain. The first
+// targeted SIGINT comes from the supervisor; later foreground-group signals
+// must not regain their default disposition inside an open claim tick.
+const signalHandlers = installDispatchKernelSignalHandlers(requestStop)
+const parentWatch = watchDispatchParent(process.ppid, requestStop)
+let exitCode = 0
+
+try {
+  await abDispatch({
+    targetRepo: options.targetRepo,
+    storeRef: options.storeRef,
+    env: process.env,
+    exec: spawnExec,
+    stdout: () => {},
+    stderr: () => {},
+    once: options.once,
+    ...(options.intervalMs !== undefined ? { intervalMs: options.intervalMs } : {}),
+    signal: stop.signal,
+    plain: true,
+    silent: true,
+    kernelRunId: options.run,
+  })
+} catch (error) {
+  exitCode = 1
+  // Config/plugin/adapter startup can fail before abDispatch owns a Store and
+  // writes run-started. Reopen only the already-resolved Store identity so the
+  // terminal frontend receives the actionable failure rather than a generic
+  // child exit status.
+  try {
+    const state = await resolveRepoState({
+      targetRepo: options.targetRepo,
+      storeRef: options.storeRef,
+      exec: spawnExec,
+    })
+    const opened = openStoreForRepoState(state, { env: process.env })
+    try {
+      await opened.store.ensureRepo(state.repo)
+      const events = await opened.store.getRepoEvents(state.repo)
+      if (
+        !events.some(
+          (event) => event.type === 'dispatcher.run-stopped' && event.payload.run === options.run,
+        )
+      ) {
+        await opened.store.appendRepo(state.repo, {
+          actor: DISPATCHER,
+          type: 'dispatcher.run-stopped',
+          payload: {
+            run: options.run,
+            outcome: 'abnormal',
+            exitCode: 1,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        })
+      }
+    } finally {
+      await opened.store.close()
+    }
+  } catch {
+    // The supervisor still records the process exit if even the Store cannot
+    // be opened. Preserve the original startup failure as the exit cause.
+  }
+} finally {
+  parentWatch.close()
+  signalHandlers.close()
+}
+process.exit(exitCode)

package/bin/ab-harvest-runner.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+/** Private shipped child: one disposable environment per hosted harvest run.
+ * The environment owns teardown (no process-group reaper, no parent watchdog)
+ * — the same contract as the build child's `environment` branch. */
+import { runHarvestChild } from '../packages/core/src/processes/harvest-child'
+import {
+  HARVEST_RUNNER_OPTIONS_ENV,
+  parseHarvestRunnerLaunch,
+  type HarvestRunnerLaunch,
+} from '../packages/core/src/ports/workspace/harvest-execution'
+
+const raw = process.env[HARVEST_RUNNER_OPTIONS_ENV]
+let input: HarvestRunnerLaunch | undefined
+try {
+  input = parseHarvestRunnerLaunch(raw === undefined ? undefined : JSON.parse(raw))
+} catch {
+  // Invalid immutable launch envelope exits below.
+}
+if (input === undefined) process.exit(2)
+
+let exitCode = 0
+try {
+  await runHarvestChild(input, process.env)
+} catch {
+  // The durable outcome lives in the repository journal; the guest exit code
+  // is liveness evidence only.
+  exitCode = 1
+}
+process.exit(exitCode)

package/bin/ab-init-probe.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/** Private shipped child used only inside a disposable readiness workspace. */
+import { INIT_PROBE_MARKER, runGuestReadinessProbe } from '../packages/core/src/cli/init-validation'
+
+try {
+  const report = await runGuestReadinessProbe({ repo: process.cwd(), env: process.env })
+  console.log(`${INIT_PROBE_MARKER}${JSON.stringify(report)}`)
+  // A complete report is transport success even when one readiness check fails;
+  // the host owns the user-facing nonzero status.
+  process.exit(0)
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error)
+  console.log(
+    `${INIT_PROBE_MARKER}${JSON.stringify({ checks: [{ name: 'readiness probe', status: 'fail', detail }] })}`,
+  )
+  // Emitting the structured marker is transport success. The host turns its
+  // failing check into the command's user-facing nonzero result.
+  process.exit(0)
+}

package/bin/ab-process-group-reaper.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+/** Private shipped helper: reap one abandoned local build process group. */
+import { terminateProcessGroup } from '../packages/core/src/processes/process-group'
+import {
+  PROCESS_GROUP_REAPER_OPTIONS_ENV,
+  type ProcessGroupReaperOptions,
+} from '../packages/core/src/processes/process-group-reaper'
+
+const raw = process.env[PROCESS_GROUP_REAPER_OPTIONS_ENV]
+let options: ProcessGroupReaperOptions | undefined
+try {
+  const parsed =
+    raw === undefined ? undefined : (JSON.parse(raw) as Partial<ProcessGroupReaperOptions>)
+  if (
+    parsed !== undefined &&
+    Number.isSafeInteger(parsed.groupId) &&
+    parsed.groupId! > 0 &&
+    Number.isFinite(parsed.stopTimeoutMs) &&
+    parsed.stopTimeoutMs! >= 0
+  ) {
+    options = parsed as ProcessGroupReaperOptions
+  }
+} catch {
+  // Invalid immutable launch envelope exits below.
+}
+if (options === undefined) process.exit(2)
+
+try {
+  await terminateProcessGroup(options.groupId, options.stopTimeoutMs)
+} catch {
+  process.exit(1)
+}

package/bin/ab.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+/** Published `ab` entry: unconditional production wiring, with no watcher or
+ * dev-state branch. The repo-local hot entry lives separately in ab-dev.ts. */
+import { runBinary } from '../packages/core/src/cli/binary'
+
+process.exit(await runBinary(process.argv.slice(2)))

package/bin/agent/ab

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+/** Agent-session launcher: delegate to the distribution's canonical CLI entry. */
+import '../ab.ts'

package/docs/answering-blocked-builds.md

@@ -0,0 +1,89 @@
+# Answering blocked builds
+
+A build is **blocked** while one or more escalations are open. Inspect them with
+`ab build status <slug>`, then choose the resolution that matches the problem.
+Every action below is sessionless, records a human-authored fact, and accepts
+`--store <ref>`.
+
+| Need | Command | Effect |
+|---|---|---|
+| Give the phase a decision or missing information | `ab answer <slug> <text>` | Records `guidance`. In a review loop it feeds the next producer round. |
+| Try again without guidance | `ab answer <slug>` | Records a bare `retry`; no prose is delivered to an agent. |
+| Widen an exhausted review loop | `ab answer <slug> [<text>] --review-round-ceiling <n>` | Answers the open `review-round-limit` escalation and replaces the configured cap with absolute ceiling `n` for that loop and spec revision only. |
+| Retire a review disagreement | `ab answer <slug> --dismiss` | Records `dismiss-finding` for each escalation that cites a real finding id. The next reviewer is told not to re-raise that chain. |
+| Replace the build contract from a file | `ab answer <slug> --revise-spec <file>` | Records the replacement as the next spec revision and restarts at `plan`. |
+| Re-import an amended ticket | `ab answer <slug> --revise-spec-from-ticket` | Reads the build's recorded ticket and performs the same revision. |
+| Abandon the build | `ab abort <slug>` | Irrevocably requests abort; cleanup returns the ticket to Triage. |
+
+The dashboard's blocked-build `r` shortcut requests an inline answer step that
+supports guidance and a blank retry. While that step is open, it is exclusive
+to the selected row: the row exposes only **SUBMIT** and **CANCEL**. Its ordinary
+**RESUME**, **ABORT**, auto-merge, and detail controls are unavailable, and the
+`r` and `a` row shortcuts do not trigger them (those letters remain ordinary
+text while typing in the guidance field).
+
+A successful submit records the trimmed guidance, or a bare retry for blank
+input, resumes through the normal answer lifecycle, and closes the local step.
+**CANCEL** or Esc closes it without writing and preserves both the selected
+build and whether its detail was open. A later **RESUME** can request a fresh,
+empty answer step. A later **ABORT** first replaces the row controls with local
+**CONFIRM ABORT** and **CANCEL** confirmation; no durable abort occurs until it
+is confirmed.
+
+Controls on unrelated rows retain their established target-aware behavior.
+Activating one leaves the old answer mode, selects that row, and performs its
+normal action. The selected build's full detail names the CLI-only dismissal
+and revision commands; it does not provide a spec editor.
+
+Restarting `ab dispatch` or running `ab dispatch --once` is not an answer or a
+retry action. Every open escalation, including every policy and setup cause,
+survives dispatcher startup until a human uses one of the paths above. Startup
+still recovers unblocked work and acknowledges pending operator commands.
+
+## Widening an exhausted review loop
+
+`--review-round-ceiling` is available only while the selected build has one open
+`review-round-limit` policy escalation. The positive integer is an absolute
+ceiling, not an increment: setting 12 again leaves the cap at 12. The answer and
+override are one durable human-authored event, so no dispatcher restart is
+needed and replay preserves the value.
+
+The escalation's phase selects the plan or code loop. The other loop and every
+other build keep the configured `maxReviewRounds`; `spec.revised` clears both
+loop overrides. The stall threshold still applies before the widened round cap.
+A ceiling cannot be supplied pre-emptively, as a standalone control, or together
+with `--revise-spec`/`--revise-spec-from-ticket` because revision resets the
+round budget itself. Current overrides appear in `ab build status` and on the
+dashboard.
+
+## Dismissing findings
+
+Dismissal is evaluated per escalation. A blocker that cites no real
+plan-review or code-review finding remains open, even when another blocker is
+dismissed. Answer the remainder with guidance or a blank retry. Dismissal
+settles only the cited chain: a reviewer can still report a genuinely different
+problem in the same file under a new finding id.
+
+## Revising the spec
+
+Revision requires an open escalation because the spec is the contract against
+which every downstream approval is measured. The replacement must satisfy the
+same spec-standard quality gate used at dispatch; a non-conforming body is
+rejected before an artifact or event is recorded, leaving the build blocked on
+its current revision.
+
+A successful answer records a human `escalation.answered` fact naming the exact
+replacement artifact, followed by kernel `spec.revised`. The build re-plans and
+pre-revision reviews, verification, and finalize completion do not satisfy the
+new run. Historical phase runs remain pinned to the revision they saw. An
+already-open pull request is retained and updated rather than duplicated.
+
+The two events make interrupted work safely resumable. If the answer was
+recorded but `spec.revised` was not, a repeated revision command publishes the
+body named by that earlier answer; it does not read or authorize a newly
+supplied file or ticket body.
+
+A build that has already become terminal cannot restart. This includes the
+short windows where its PR has merged or closed and completion is underway, or
+where an abort request is pending. Abort is irrevocable; after cleanup, dispatch
+the returned ticket as a fresh build if work should continue.