@defrex/autobuild 0.8.0 → 0.10.0

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

@@ -35,7 +35,7 @@ import {
   loadScanPacket,
   validateProposalCoverage,
 } from '../processes/harvest'
-import type { BuildStore } from '../store/types'
+import type { BuildStore, StreamRecord } from '../store/types'
 import type { HarvestCliEnv } from './env'
 import { withSessionlessStore, type StoreOpener } from './store-opening'
 
@@ -121,7 +121,8 @@ async function readArtifactJson(
 
 export async function buildHarvestContext(deps: HarvestCliDeps): Promise<HarvestContextManifest> {
   const { store, env, workspacePath } = deps
-  const events = await store.getRepoEvents(env.repo)
+  // Bounded read (AUT-489): runForEnv reduces harvest facts only.
+  const events = await store.getRepoStateEvents(env.repo)
   const run = runForEnv(events, env)
   const packet = await loadScanPacket(store, env.repo, run.scan)
   const abDir = join(workspacePath, '.ab')
@@ -217,7 +218,9 @@ export async function submitHarvestProposals(
       `'ab harvest submit' is only valid in synthesize@<round>; current phase is ${env.phase}@${env.round}`,
     )
   }
-  const events = await store.getRepoEvents(env.repo)
+  // Bounded read (AUT-489): runForEnv and assertNoSessionTerminal consume
+  // harvest facts only.
+  const events = await store.getRepoStateEvents(env.repo)
   const run = runForEnv(events, env)
   assertNoSessionTerminal(events, env)
 
@@ -307,7 +310,9 @@ export async function submitHarvestVerdict(
       `harvest verdict "${opts.verdict}" is invalid — expected approve | revise | escalate`,
     )
   }
-  const events = await store.getRepoEvents(env.repo)
+  // Bounded read (AUT-489): runForEnv and assertNoSessionTerminal consume
+  // harvest facts only.
+  const events = await store.getRepoStateEvents(env.repo)
   const run = runForEnv(events, env)
   assertNoSessionTerminal(events, env)
   if (proposalArtifactForRound(run, env.round) === undefined) {
@@ -398,6 +403,22 @@ export interface HarvestFiledStatusView {
   blockers?: { declared: string[]; derived: string[] }
 }
 
+/** One harvest session's discoverability row: its stream id and open/closed
+ * status, at parity with the build-session rows. `stream` is absent on
+ * sessions that never streamed. */
+export interface HarvestSessionStatusView {
+  session: string
+  role: 'harvest' | 'harvest-review'
+  step: 'synthesize' | 'review'
+  round: number
+  /** Live-view stream id (SPEC §9); absent on sessions that never streamed. */
+  stream?: string
+  /** Open until the session's `harvest.session.ended` lands; the store's
+   * records refine this to the stream's authoritative status when available. */
+  streamStatus: 'open' | 'closed'
+  status: 'open' | 'ended'
+}
+
 export interface HarvestRunStatusView {
   run: string
   status: HarvestRunState['status']
@@ -408,6 +429,7 @@ export interface HarvestRunStatusView {
   steps: HarvestRunState['steps']
   rounds: number
   filed: HarvestFiledStatusView[]
+  sessions: HarvestSessionStatusView[]
   escalation?: HarvestRunState['escalation']
   failure?: HarvestRunState['failure']
   recovery: HarvestRecoveryStatus
@@ -481,7 +503,73 @@ function projectRecovery(run: HarvestRunState | undefined): HarvestRecoveryStatu
   }
 }
 
-function projectHarvestRunStatus(run: HarvestRunState): HarvestRunStatusView {
+/** Pair the append-only `harvest.session.started` / `harvest.session.ended`
+ * facts per run without introducing transition state. `streams` is the
+ * optional authoritative enrichment from `listStreams` on the repo scope:
+ * records whose label matches `session:<id>` supply each session's stream id
+ * and open/closed status.
+ *
+ * Verified (AUT-574): no repo-identity comparison happens in this code —
+ * membership is decided store-side by `listStreams({ kind: 'repo', repo })`,
+ * scoped by the same resolved identity the caller passes, and the `scope.kind`
+ * check below is only a defensive kind filter over records the store already
+ * scoped. Store scoping semantics are out of scope here. */
+function projectHarvestSessions(
+  events: RepositoryEvent[],
+  streams?: readonly StreamRecord[],
+): Map<string, HarvestSessionStatusView[]> {
+  const recordsByLabel = new Map<string, StreamRecord>()
+  if (streams !== undefined) {
+    for (const record of streams) {
+      if (record.scope.kind === 'repo') recordsByLabel.set(record.label, record)
+    }
+  }
+
+  const byRun = new Map<string, HarvestSessionStatusView[]>()
+  const open = new Map<string, HarvestSessionStatusView>()
+  for (const event of events) {
+    if (event.type === 'harvest.session.started') {
+      const record = recordsByLabel.get(`session:${event.payload.session}`)
+      const view: HarvestSessionStatusView = {
+        session: event.payload.session,
+        role: event.payload.role,
+        step: event.payload.step,
+        round: event.payload.round,
+        status: 'open',
+        // The store's records are authoritative when available; without them
+        // the pairing degrades gracefully (open until `harvest.session.ended`).
+        ...(record !== undefined
+          ? { stream: record.id, streamStatus: record.status }
+          : {
+              ...(event.payload.stream !== undefined ? { stream: event.payload.stream } : {}),
+              streamStatus: event.payload.stream !== undefined ? 'open' : 'closed',
+            }),
+      }
+      const list = byRun.get(event.payload.run) ?? []
+      list.push(view)
+      byRun.set(event.payload.run, list)
+      open.set(view.session, view)
+      continue
+    }
+    if (event.type !== 'harvest.session.ended') continue
+    const started = open.get(event.payload.session)
+    if (started === undefined) continue
+    started.status = 'ended'
+    // A session bracket has ended: without an authoritative record its
+    // stream reads closed.
+    const record = recordsByLabel.get(`session:${started.session}`)
+    if (record !== undefined) {
+      started.stream = record.id
+      started.streamStatus = record.status
+    } else {
+      started.streamStatus = 'closed'
+    }
+    open.delete(started.session)
+  }
+  return byRun
+}
+
+function projectHarvestRunStatus(run: HarvestRunState): Omit<HarvestRunStatusView, 'sessions'> {
   return {
     run: run.run,
     status: run.status,
@@ -506,6 +594,7 @@ export function projectHarvestStatus(
   repo: string,
   events: RepositoryEvent[],
   newestEvents?: number,
+  streams?: readonly StreamRecord[],
 ): HarvestStatusView {
   const state = reduceHarvest(events)
   const history =
@@ -515,7 +604,13 @@ export function projectHarvestStatus(
   const included = new Set(
     [...unresolved, ...open, ...(state.latest ? [state.latest] : [])].map((run) => run.run),
   )
-  const runs = state.runs.filter((run) => included.has(run.run)).map(projectHarvestRunStatus)
+  const sessionsByRun = projectHarvestSessions(events, streams)
+  const runs = state.runs
+    .filter((run) => included.has(run.run))
+    .map((run) => ({
+      ...projectHarvestRunStatus(run),
+      sessions: sessionsByRun.get(run.run) ?? [],
+    }))
   const unresolvedIds = new Set(unresolved.map((run) => run.run))
   const primary =
     runs.find((run) => unresolvedIds.has(run.run)) ??
@@ -568,6 +663,13 @@ function renderHarvestRunStatus(run: HarvestRunStatusView, paused: boolean): str
         `${step.outcome ?? (step.completedSeq === undefined ? 'running' : 'done')}`,
     )
   }
+  for (const session of run.sessions) {
+    const stream =
+      session.stream !== undefined ? ` stream ${session.stream} (${session.streamStatus})` : ''
+    lines.push(
+      `  session ${session.session} (${session.role}, ${session.step}@${session.round})${stream}`,
+    )
+  }
   if (run.recovery.stopped !== undefined) {
     lines.push(
       `stopped at: ${run.recovery.stopped.step}${
@@ -689,8 +791,20 @@ export async function abHarvestStatus(opts: HarvestStatusOpts): Promise<void> {
     },
     async ({ store, repo }) => {
       const record = await store.getRepo(repo)
-      const events = record === null ? [] : await store.getRepoEvents(repo)
-      const view = projectHarvestStatus(repo, events, opts.events)
+      // Bounded read (AUT-489): projectHarvestStatus reduces harvest facts only.
+      const events = record === null ? [] : await store.getRepoStateEvents(repo)
+      // Best-effort stream enrichment for the session rows, mirroring the
+      // degrade-gracefully pattern of 'ab build status': a store that cannot
+      // list streams keeps the payload-derived projection instead of failing.
+      let streams: StreamRecord[] | undefined
+      if (record !== null) {
+        try {
+          streams = await store.listStreams({ kind: 'repo', repo })
+        } catch {
+          streams = undefined
+        }
+      }
+      const view = projectHarvestStatus(repo, events, opts.events, streams)
       if (opts.json === true) opts.stdout(JSON.stringify(view, null, 2))
       else for (const line of renderHarvestStatus(view)) opts.stdout(line)
     },

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

@@ -163,8 +163,13 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '  ab ticket block <id> <blocker-id[,blocker-id...]> [--json]',
       '  ab ticket unblock <id> <blocker-id[,blocker-id...]> [--json]',
       '  ab ticket list [--state <state>] [--labels a,b] [--json]',
-      '  ab ticket show <id> [--json]',
+      '  ab ticket show <id> [--store <ref>] [--json]',
       '  ab ticket move <id> <state> [--json]',
+      '  ab ticket states [--json]',
+      '  ab ticket state create <name> [--about <text>] [--json]',
+      '  ab ticket attach <id> <kind> <path> [--name <name>] [--store <ref>] [--json]',
+      '  ab ticket asset get <id> <kind> <name> <dest> [--rev <n>] [--store <ref>] [--json]',
+      '  ab ticket asset rm <id> <kind> <name> [--store <ref>] [--json]',
       '',
       'Operate on the configured [tickets] source (§8.8); all ticket commands run',
       'outside sessions. create files a ticket and may establish initial blockers.',
@@ -177,11 +182,35 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '',
       'With no list filters, list uses the same ready criteria as dispatch. show one ticket, including its body/spec.',
       'Human output is the default. --json emits exactly one bare value: Ticket[]',
-      'for list and the complete resulting Ticket for every other subcommand.',
+      'for list and the complete resulting Ticket for every other subcommand; show',
+      'adds an assets array (kind, name, revision, size, layout, fileCount).',
+      '',
+      'Ticket assets are files or folders (a design export, a reference screenshot, a',
+      'sample payload) attached to a ticket and kept in the BuildStore, never in the',
+      'ticket source. attach stores <path> under <kind> and a name (default: the',
+      'basename); attaching the same kind and name again makes a new revision and',
+      'earlier ones stay retrievable. asset get writes the exact bytes of the latest',
+      '(or --rev) revision to <dest>: a file asset to that file, a folder asset to',
+      'that directory. asset rm drops it from the current assets; revisions already',
+      'pinned by a build stay retrievable. attach and rm leave a note on the ticket in',
+      'its source naming the asset and how to download it. Assets over the store',
+      'limit (25 MiB by default, lower on a hosted deployment) are refused.',
+      '',
+      'states lists every state of the source: lifecycle states first (triage, ready,',
+      'doing, done), then custom ones alphabetically, each with the roles it plays',
+      'under the current config (create, ready, claimed, triage, proposal, done, or',
+      'none), its ticket count, and its purpose when set. --json emits one bare',
+      'array of {name, roles, tickets, about?}. state create makes a state, e.g.',
+      'icebox, and is idempotent: an existing state is reported, and --about (one',
+      'line) records or replaces its purpose. A name is one to forty lowercase',
+      'letters, digits, and hyphens, starting with a letter, and may not match an',
+      'existing state case-insensitively. There is no rename or delete. Only the file',
+      'source supports both; others exit nonzero naming the source. A state with no',
+      'purpose and no tickets is an empty directory that git does not track.',
       '',
       'Ticket ids are source-local (for example AUT-8 or file-1). For block and',
       'unblock, the first id is always the ticket being changed. State names and',
-      'unknown-id errors come from the configured source.',
+      'unknown-id errors come from the configured source; ab ticket states lists them.',
     ]),
   },
   {
@@ -227,6 +256,7 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
     detail: page([
       'Usage:',
       '  ab build status <slug> [--events <n>] [--json] [--store <ref>]',
+      '  ab build asset get <slug> <kind> <name> <dest> [--rev <n>] [--json] [--store <ref>]',
       '',
       'Show detailed state for one build: unresolved escalations, open sessions,',
       'verify progress, PR state, durable-event progress, heartbeat, and lease health.',
@@ -234,6 +264,10 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'order. --json emits the complete projection; --store overrides the',
       'BuildStore path or URL.',
       '',
+      'asset get downloads a ticket asset exactly as the build froze it at its claim',
+      '(or at the last spec revision from the ticket), also after the build has',
+      'finished. --rev <n> names an earlier pinned revision.',
+      '',
       'This command is read-only and requires no session identity for operator use.',
       'Inside a phase, a complete ambient tuple permits only the ambient build;',
       'foreign builds and malformed or partial identity are rejected.',
@@ -294,9 +328,12 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'Exit codes: the watch ends with exit 0 when --timeout elapses, when --count records',
       'have been emitted, or, only when slugs were named, when every named build has reached a',
       'terminal status. Usage errors, scope violations, unknown slugs, cursor rejection, and a',
-      'store that cannot be opened at start exit 1 with a message on stderr. A store read that',
-      'fails after the watch has started is reported once on stderr and retried at the next',
-      'interval without ending the watch or duplicating or skipping any event.',
+      'store that cannot be opened at start exit 1 with a message on stderr. A store read',
+      'that fails after the watch has started is reported on stderr',
+      'once per failing read source — locally the poll cycle is one source, while against',
+      'an http(s) store each tracked stream and the discovery pass carries its own failure',
+      'streak — and retried at the next interval without ending the watch or duplicating or',
+      'skipping any event.',
       '',
       'This command is read-only: it appends no event, takes no lease, and creates no build or',
       'repository record, and requires no session identity for operator use. Inside a phase, a',
@@ -355,9 +392,18 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'any condition was satisfied, with the same cursor behavior as exit 3.',
       '',
       'The default poll interval and the --interval override match ab watch: 5s for an http(s)',
-      'store, 1s for a local store. A store read that fails while waiting is reported once on',
-      'stderr, retried at the next interval, and never causes a condition to be missed or',
-      'reported twice.',
+      'store, 1s for a local store. Cadence follows the store kind, as in ab watch: a local',
+      'store ticks sequentially at the interval, while against an http(s) store each targeted',
+      'build keeps one held read in flight — one long-held request per wait window (AUT-334),',
+      'so an appended event is seen within about a second — with --interval the floor between',
+      'request starts. A held read’s window is the remote default (25s, whole seconds, clamped',
+      'by the store’s ceiling), capped at the remaining --timeout budget, and every stop — a',
+      'satisfied condition, an all-terminal named set, the timeout, an interrupt — cancels',
+      'in-flight holds promptly. A store read that fails while waiting is reported on stderr',
+      'once per failing read source — locally the poll cycle is one source, while against an',
+      'http(s) store each tracked build and the discovery pass carries its own failure',
+      'streak — retried at the next interval (the next request on the remote path), and never',
+      'causes a condition to be missed or reported twice.',
       '',
       'This command is read-only: it appends no event, takes no lease, and creates no build or',
       'repository record, and requires no session identity for operator use. Inside a phase, a',
@@ -565,6 +611,7 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       '  ab artifact put <kind> <file> [--attach]',
       '  ab artifact get <kind>[@rev]',
       '  ab artifact download <build> <kind>[@rev] --output <file> [--store <ref>]',
+      '  ab artifact download stream:<id>[@rev] --output <file> [--store <ref>]',
       '',
       'put deposits a versioned artifact and prints its assigned revision. --attach',
       'also designates that exact revision for the PR. get fetches an artifact within',
@@ -575,6 +622,12 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
       'read-only and requires no session identity for operator use; --store overrides',
       'the BuildStore path or URL. Inside a phase, a complete ambient tuple permits',
       'only the ambient build; foreign builds and malformed or partial identity fail.',
+      '',
+      'The stream:<id> form retrieves a finalized repository-scoped stream artifact',
+      "(for example a harvest session's closed stream). The stream id is globally",
+      'unique, so no build argument is needed; find ids in the session rows of',
+      "'ab harvest status'. This form is strictly an operator read: any ambient",
+      'build or Harvest identity fails closed (§8.2).',
     ]),
   },
   {

package/packages/core/src/cli/init-readiness-remote.ts

@@ -0,0 +1,110 @@
+/**
+ * The builtin `vercel-sandbox` provider's remote readiness validation
+ * (AUT-516): the body of `validateInitReadiness`'s remote branch, moved here
+ * so the capability declaration can point at it without
+ * `cli/init-validation.ts` naming the provider. Store precondition checks
+ * stay with the caller, driven by the `storeRequirements` declaration.
+ */
+import type { VercelSandboxConfig } from '../config/schema'
+import type {
+  InitValidationReport,
+  WorkspaceReadinessContext,
+} from '../ports/workspace/provider-capabilities'
+import { validateVercelSandbox, type VercelSandboxFacade } from '../ports/workspace/vercel-sandbox'
+import { gitText, parseGuestOutput } from './init-readiness-shared'
+
+export async function validateRemoteReadiness(
+  ctx: WorkspaceReadinessContext,
+): Promise<InitValidationReport> {
+  const vercel = ctx.providerConfig as VercelSandboxConfig
+  const remoteLine = await gitText(
+    ctx.exec,
+    ctx.repo,
+    ['ls-remote', '--heads', 'origin', `refs/heads/${ctx.baseBranch}`],
+    ctx.signal,
+  )
+  const remoteRevision = remoteLine.split(/\s+/)[0]
+  if (!/^[0-9a-f]{40,64}$/i.test(remoteRevision ?? '')) {
+    throw new Error(
+      `remote base ${ctx.baseBranch} does not exist; commit and push setup changes before validating`,
+    )
+  }
+  await gitText(
+    ctx.exec,
+    ctx.repo,
+    [
+      'fetch',
+      '--no-tags',
+      '--no-write-fetch-head',
+      '--refmap=',
+      'origin',
+      `refs/heads/${ctx.baseBranch}`,
+    ],
+    ctx.signal,
+  )
+  const shownConfig = await ctx.exec(['git', 'show', `${remoteRevision}:autobuild.toml`], {
+    cwd: ctx.repo,
+    ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+  })
+  if (shownConfig.exitCode !== 0) {
+    throw new Error(
+      `remote ${ctx.baseBranch} does not contain autobuild.toml; commit and push setup changes before validating`,
+    )
+  }
+  if (shownConfig.stdout !== ctx.configBytes) {
+    throw new Error(
+      `remote ${ctx.baseBranch} autobuild.toml differs from this checkout; commit and push setup changes before validating`,
+    )
+  }
+  let remote: Awaited<ReturnType<typeof validateVercelSandbox>>
+  try {
+    remote = await validateVercelSandbox({
+      config: vercel,
+      env: ctx.env,
+      storeRef: ctx.storeRef,
+      storeToken: ctx.storeToken,
+      repo: ctx.repo,
+      baseBranch: ctx.baseBranch,
+      ...(ctx.facade !== undefined ? { facade: ctx.facade as VercelSandboxFacade } : {}),
+      exec: ctx.exec,
+      ...(ctx.packageArchive !== undefined ? { packageArchive: ctx.packageArchive } : {}),
+      runtimeReferences: [...ctx.runtimeReferences],
+      ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+      onSandbox: (name) => ctx.stdout(`Disposable Vercel Sandbox: ${name} (active)`),
+    })
+  } catch (error) {
+    throw new Error(ctx.redact(error))
+  }
+  let guest: Awaited<ReturnType<typeof parseGuestOutput>>
+  try {
+    guest = parseGuestOutput(remote.output)
+  } catch (error) {
+    throw new Error(
+      `disposable sandbox ${remote.sandbox} was deleted, but its readiness output was invalid: ${ctx.redact(error)}`,
+    )
+  }
+  return {
+    provider: 'vercel-sandbox',
+    context: 'Vercel Sandbox',
+    workspace: remote.sandbox,
+    revision: remote.revision,
+    snapshotsDeleted: remote.snapshotsDeleted,
+    checks: [
+      {
+        name: 'repository acquisition',
+        status: 'pass',
+        detail: `${remote.origin} ${remote.revision}`,
+      },
+      {
+        name: 'system provisioning',
+        status: 'pass',
+        detail:
+          remote.provisioning.length === 0
+            ? 'no workspace.config.provisioning steps declared'
+            : `completed: ${remote.provisioning.join(', ')}`,
+      },
+      ...guest.checks,
+    ],
+    exitCode: guest.checks.some((check) => check.status === 'fail') ? 1 : 0,
+  }
+}

package/packages/core/src/cli/init-readiness-shared.ts

@@ -0,0 +1,72 @@
+/**
+ * Readiness-probe helpers shared by the local-worktree and remote validation
+ * paths (AUT-516). Moved out of `cli/init-validation.ts` so the remote
+ * capability implementation can use them without init-validation importing
+ * the provider implementation; `init-validation.ts` re-exports for
+ * compatibility.
+ */
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { GuestProbeReport } from '../ports/workspace/provider-capabilities'
+
+export const INIT_PROBE_MARKER = 'AB_INIT_READINESS_V1='
+
+function message(error: unknown): string {
+  if (error instanceof AggregateError) {
+    return [error.message, ...error.errors.map(message)].filter(Boolean).join('; ')
+  }
+  if (error instanceof Error)
+    return `${error.message}${error.cause === undefined ? '' : `; ${message(error.cause)}`}`
+  return String(error)
+}
+
+/** Replace every supplied nonempty value, longest first, in all diagnostics. */
+export function createReadinessRedactor(
+  env: Readonly<Record<string, string | undefined>>,
+  explicitSecretNames: readonly string[] = [],
+): (value: unknown) => string {
+  const namedSecrets = new Set(explicitSecretNames)
+  const secrets = [
+    ...new Set(
+      Object.entries(env)
+        .filter(
+          ([name, value]) =>
+            value !== undefined &&
+            value !== '' &&
+            (namedSecrets.has(name) || /(?:TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|AUTH)/i.test(name)),
+        )
+        .map(([, value]) => value as string),
+    ),
+  ].sort((left, right) => right.length - left.length)
+  return (value) => {
+    let text = message(value)
+    for (const secret of secrets) text = text.split(secret).join('[REDACTED]')
+    return text
+  }
+}
+
+export function parseGuestOutput(output: string): GuestProbeReport {
+  const line = output.split(/\r?\n/).find((candidate) => candidate.startsWith(INIT_PROBE_MARKER))
+  if (line === undefined)
+    throw new Error('remote readiness probe returned malformed output (result marker absent)')
+  const value = JSON.parse(line.slice(INIT_PROBE_MARKER.length)) as GuestProbeReport
+  if (!Array.isArray(value.checks))
+    throw new Error('remote readiness probe returned malformed checks')
+  return value
+}
+
+export async function gitText(
+  exec: Exec,
+  repo: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await exec(['git', ...args], {
+    cwd: repo,
+    ...(signal === undefined ? {} : { signal }),
+  })
+  if (result.exitCode !== 0)
+    throw new Error(
+      `git ${args.join(' ')} exited ${result.exitCode}: ${result.stderr.trim() || result.stdout.trim()}`,
+    )
+  return result.stdout.trim()
+}