@defrex/autobuild 0.8.0

package/packages/core/src/cli/pr-attachments.ts

@@ -0,0 +1,138 @@
+import type { AbEvent, EventEnvelope } from '../events/catalog'
+import { KERNEL } from '../events/envelope'
+import type { IdSource } from '../ids'
+import {
+  currentPrAttachments,
+  frozenPrImageHost,
+  hostedPrAttachments,
+} from '../kernel/pr-attachments'
+import { hostedPrAttachmentAssetSchema, type HostedPrAttachmentAsset } from '../ontology'
+import type { Forge } from '../ports/types'
+import type { BuildStore } from '../store/types'
+import type { CliEnv } from './env'
+
+export interface PrAttachmentDeps {
+  store: BuildStore
+  env: CliEnv
+  workspacePath: string
+  forge: Forge
+  ids: IdSource
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+async function recordHostingFailure(
+  deps: PrAttachmentDeps,
+  events: AbEvent[],
+  designation: ReturnType<typeof currentPrAttachments>[number],
+  error: unknown,
+  extraRefs: string[] = [],
+): Promise<void> {
+  const { artifact } = designation.payload
+  try {
+    const observed = await deps.store.append(deps.env.build, {
+      actor: KERNEL,
+      type: 'observation.recorded',
+      payload: {
+        id: deps.ids('obs'),
+        kind: 'followup',
+        summary:
+          `PR attachment hosting failed for ${designation.payload.filename} ` +
+          `(${artifact.kind}@${artifact.rev}): ${errorMessage(error)}`,
+        refs: [`${artifact.kind}@${artifact.rev}`, ...extraRefs],
+      },
+    })
+    events.push(observed)
+  } catch {
+    // Hosting is a best-effort review affordance. A secondary failure to
+    // record its follow-up must not hide the complete text projection or turn
+    // a verification/finalize result red.
+  }
+}
+
+/**
+ * Host every newly designated image independently. Text projection never
+ * depends on this operation; provider failures become follow-up observations.
+ * A successful external upload's durable event append is intentionally not
+ * swallowed, preserving deterministic adoption across the upload/write crash
+ * window.
+ */
+export async function preparePrAttachments(
+  deps: PrAttachmentDeps,
+  events: AbEvent[],
+  prUrl: string,
+): Promise<void> {
+  const target = frozenPrImageHost(events)
+  if (target === undefined) return
+
+  const designations = currentPrAttachments(events)
+  const hosted = hostedPrAttachments(events, designations)
+  for (const designation of designations) {
+    if (!designation.payload.mediaType.startsWith('image/')) continue
+    if (hosted.has(designation.seq)) continue
+
+    let asset: HostedPrAttachmentAsset
+    try {
+      const capability = deps.forge.prAttachments
+      if (capability === undefined) {
+        throw new Error(`forge ${deps.forge.name} does not support PR attachment hosting`)
+      }
+      const ref = designation.payload.artifact
+      const artifact = await deps.store.getArtifact(deps.env.build, ref.kind, ref.rev)
+      if (artifact === null) {
+        throw new Error(`designated artifact ${ref.kind}@${ref.rev} is missing`)
+      }
+
+      asset = hostedPrAttachmentAssetSchema.parse(
+        await capability.upload({
+          workspacePath: deps.workspacePath,
+          target,
+          prUrl,
+          attachment: designation.payload,
+          content: artifact.content,
+          sha256: artifact.meta.blobRef,
+        }),
+      )
+      if (
+        asset.provider !== target.provider ||
+        asset.repository !== target.repository ||
+        asset.releaseId !== target.releaseId
+      ) {
+        throw new Error('PR attachment host returned a deletion handle for a different target')
+      }
+    } catch (error) {
+      await recordHostingFailure(deps, events, designation, error)
+      continue
+    }
+
+    const assetRef =
+      `${asset.provider}:${asset.repository}:release/${asset.releaseId}:` + `asset/${asset.assetId}`
+    let event: EventEnvelope<'pr-attachment.hosted'>
+    try {
+      event = await deps.store.append(deps.env.build, {
+        actor: KERNEL,
+        type: 'pr-attachment.hosted',
+        payload: { designationSeq: designation.seq, asset },
+      })
+    } catch (error) {
+      // A late attachment has no phase retry after its external upload. Leave
+      // an exact cleanup pointer before preserving finalize's throw-and-adopt
+      // behavior for this upload/write crash window.
+      await recordHostingFailure(
+        deps,
+        events,
+        designation,
+        new Error(
+          `public copy ${assetRef} was uploaded, but its durable hosted fact ` +
+            `could not be recorded: ${errorMessage(error)}`,
+        ),
+        [assetRef],
+      )
+      throw error
+    }
+    events.push(event)
+    hosted.set(designation.seq, event)
+  }
+}

package/packages/core/src/cli/pr-summary.ts

@@ -0,0 +1,124 @@
+import type { AbEvent } from '../events/catalog'
+import {
+  currentPrAttachments,
+  frozenPrImageHost,
+  hostedPrAttachments,
+} from '../kernel/pr-attachments'
+import { normalizeVerifyCompletion } from '../events/payloads'
+import type { CliEnv } from './env'
+
+/** Replace controls that could alter a forge-rendered comment. */
+export function printableCommentText(value: string): string {
+  let out = ''
+  for (const character of value) {
+    const code = character.codePointAt(0)!
+    if (character === '\n') out += character
+    else if (code < 0x20 || code === 0x7f) out += `\\u{${code.toString(16)}}`
+    else out += character
+  }
+  return out
+}
+
+export function html(value: string): string {
+  return printableCommentText(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+}
+
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export function renderPrAttachmentSection(env: CliEnv, events: readonly AbEvent[]): string[] {
+  const designations = currentPrAttachments(events)
+  if (designations.length === 0) return []
+
+  const target = frozenPrImageHost(events)
+  const hosted = hostedPrAttachments(events, designations)
+  const lines = [
+    '',
+    '### PR attachments',
+    '',
+    'Download each exact BuildStore revision with the pinned command below.',
+  ]
+
+  for (const designation of designations) {
+    const { artifact, filename, mediaType } = designation.payload
+    const ref = `${artifact.kind}@${artifact.rev}`
+    // Command-scoped parsing rejects flag-shaped values; retain the exact
+    // basename while making a leading-dash filename unambiguously a path.
+    const outputPath = filename.startsWith('-') ? `./${filename}` : filename
+    const command =
+      `ab artifact download ${shellQuote(env.build)} ${shellQuote(ref)} ` +
+      `--output ${shellQuote(outputPath)} --store ${shellQuote(env.store)}`
+    const hostedEvent = hosted.get(designation.seq)
+    const imageUrl =
+      mediaType.startsWith('image/') &&
+      target !== undefined &&
+      hostedEvent?.payload.asset.provider === target.provider &&
+      hostedEvent.payload.asset.repository === target.repository &&
+      hostedEvent.payload.asset.releaseId === target.releaseId
+        ? hostedEvent.payload.asset.url
+        : undefined
+
+    lines.push(
+      '',
+      `#### <code>${html(filename)}</code>`,
+      '',
+      ...(imageUrl === undefined
+        ? []
+        : [`<img src="${html(imageUrl)}" alt="PR attachment ${html(filename)}">`, '']),
+      `- artifact: <code>${html(ref)}</code>`,
+      `- media type: <code>${html(mediaType)}</code>`,
+      `<pre><code>${html(command)}</code></pre>`,
+    )
+  }
+  return lines
+}
+
+/** The complete PR summary projection, rendered only from durable facts. */
+export function renderPrSummary(env: CliEnv, events: readonly AbEvent[]): string {
+  const verdicts: string[] = []
+  const verifies: string[] = []
+  for (const event of events) {
+    if (event.type === 'plan-review.verdict' || event.type === 'code-review.verdict') {
+      const phase = event.type === 'plan-review.verdict' ? 'plan-review' : 'code-review'
+      const count = event.payload.findings.length
+      const detail =
+        event.payload.verdict === 'revise' ? ` (${count} finding${count === 1 ? '' : 's'})` : ''
+      verdicts.push(`- ${phase} r${event.payload.round}: ${event.payload.verdict}${detail}`)
+    }
+    if (event.type === 'verify.completed') {
+      const result = normalizeVerifyCompletion(event.payload)
+      const detail =
+        result.outcome === 'skipped'
+          ? ` — ${html(result.reason ?? '')}`
+          : result.report !== undefined
+            ? ` — <code>${html(`${result.report.kind}@${result.report.rev}`)}</code>`
+            : ''
+      verifies.push(
+        `- <code>${html(result.step)}</code> (attempt ${result.attempt}): ${result.outcome}${detail}`,
+      )
+    }
+  }
+
+  return [
+    `## Autobuild: ${html(env.build)}`,
+    '',
+    '### Verdict history',
+    ...(verdicts.length > 0 ? verdicts : ['- (none)']),
+    '',
+    '### Verify',
+    ...(verifies.length > 0 ? verifies : ['- (none)']),
+    ...renderPrAttachmentSection(env, events),
+    '',
+    '### Store',
+    `- store: <code>${html(env.store)}</code>`,
+    `- build: <code>${html(env.build)}</code>`,
+    '',
+    'The full audit trail is queryable in the build store (§7.5).',
+  ].join('\n')
+}

package/packages/core/src/cli/publication-settlement.ts

@@ -0,0 +1,188 @@
+import type { IdSource } from '../ids'
+import { DISPATCHER, KERNEL } from '../events/envelope'
+import type { Forge, WorkspacePublication } from '../ports/types'
+import type { Exec } from '../ports/workspace/git-worktree'
+import { openExecution } from '../processes/execution-settlement'
+import {
+  latestUncompletedPublicationRequest,
+  publicationLostRecorded,
+  publicationRequestCompleted,
+  publicationRequestSettled,
+} from '../processes/publication-state'
+import { systemClock, type BuildStore, type Clock } from '../store/types'
+import { completeFinalizePr } from './terminals'
+
+export interface PublicationSettlementDeps {
+  store: BuildStore
+  storeRef: string
+  publication?: WorkspacePublication
+  forge: Forge
+  workspacePath: string
+  exec: Exec
+  ids: IdSource
+  runId: string
+  /** Time source for the durable lease-liveness guard; defaults to the
+   * system clock. The same injected clock the dispatcher uses for lease
+   * liveness. */
+  clock?: Clock
+}
+
+/** Settle one durable request after the caller has observed environment
+ * completion and released its exact execution lease. External effects precede
+ * completion facts, making every crash gap safely retryable.
+ *
+ * Durable guard: before the publish path, the guest execution must be provably
+ * over — either the log has no open execution, or the build's lease is
+ * absent/expired. Publication is never attempted against a live guest and is
+ * never performed twice for one request; no in-memory set is the sole guard. */
+export async function settlePendingPublication(
+  deps: PublicationSettlementDeps,
+  slug: string,
+): Promise<void> {
+  const publication = deps.publication
+  if (publication === undefined) return
+  let events = await deps.store.getEvents(slug)
+  const request = latestUncompletedPublicationRequest(events)
+  if (request === undefined) return
+
+  const abandoned = publicationRequestSettled(events, request)
+  // Consulted for every uncompleted request, not only abandoned ones: a guest
+  // that pushed its branch before dying is owed its completion fact, not a
+  // re-push or a loss record.
+  const alreadyPublished =
+    publication.isPublished !== undefined
+      ? await publication.isPublished({ sha: request.payload.sha, branch: request.payload.branch })
+      : false
+  if (abandoned && !alreadyPublished) {
+    // Last-chance backstop (AUT-328): the workspace is gone with this request
+    // uncompleted. Record the loss durably (deduped per request) instead of
+    // returning silently — the exact drop that lost the validate-hosted-
+    // dispatcher generation-1 work. The finalize-step publish-failure path
+    // below is unchanged: it already settles loudly via its failed outcome.
+    if (!publicationLostRecorded(events, request)) {
+      await deps.store.append(slug, {
+        actor: DISPATCHER,
+        type: 'publication.lost',
+        payload: {
+          request: request.seq,
+          operation: request.payload.operation,
+          branch: request.payload.branch,
+          sha: request.payload.sha,
+          reason: 'workspace released with the publication uncompleted',
+        },
+      })
+    }
+    return
+  }
+
+  try {
+    if (!alreadyPublished) {
+      // Never publish against a live guest: require durable proof the guest
+      // execution ended (a recorded end or an expired/absent lease). The
+      // adapter's process-local active/uncertain sets remain a second belt.
+      const record = await deps.store.getBuild(slug)
+      const clock = deps.clock ?? systemClock
+      const leaseLive =
+        record?.lease !== undefined &&
+        new Date(record.lease.expiresAt).getTime() > clock().getTime()
+      if (openExecution(events) !== null && leaseLive) return
+      let ref: string | undefined
+      for (const event of events) {
+        if (event.type === 'workspace.provisioned') ref = event.payload.ref
+        else if (event.type === 'workspace.released') ref = undefined
+      }
+      if (ref === undefined)
+        throw new Error(`build ${slug} has a publication request but no open workspace`)
+      await publication.publish({ ref, sha: request.payload.sha, branch: request.payload.branch })
+    }
+  } catch (error) {
+    if (request.payload.operation !== 'finalize-step') throw error
+    const detail = error instanceof Error ? error.message : String(error)
+    const note = `finalize publication failed: ${detail}`
+    await deps.store.append(slug, {
+      actor: KERNEL,
+      type: 'finalize.step-completed',
+      payload: { step: request.payload.step, ok: false, note },
+    })
+    await deps.store.append(slug, {
+      actor: KERNEL,
+      type: 'observation.recorded',
+      payload: {
+        id: deps.ids('o'),
+        kind: 'followup',
+        summary: `finalize step "${request.payload.step}" failed — needs manual follow-up: ${note}`,
+      },
+    })
+    return
+  }
+  events = await deps.store.getEvents(slug)
+  if (publicationRequestCompleted(events, request)) return
+
+  if (request.payload.operation === 'implement') {
+    await deps.store.append(slug, {
+      actor: DISPATCHER,
+      type: 'implement.completed',
+      payload: {
+        round: request.payload.round,
+        commits: { base: request.payload.base, head: request.payload.sha },
+        artifact: request.payload.artifact,
+      },
+    })
+    return
+  }
+  if (request.payload.operation === 'reconcile') {
+    await deps.store.append(slug, {
+      actor: DISPATCHER,
+      type: 'reconcile.completed',
+      payload: { mergeCommit: request.payload.sha, artifact: request.payload.artifact },
+    })
+    return
+  }
+  if (request.payload.operation === 'finalize-step') {
+    await deps.store.append(slug, {
+      actor: KERNEL,
+      type: 'finalize.step-completed',
+      payload: { step: request.payload.step, ok: true, headSha: request.payload.sha },
+    })
+    return
+  }
+
+  const description = await deps.store.getArtifact(
+    slug,
+    request.payload.description.kind,
+    request.payload.description.rev,
+  )
+  if (description === null) throw new Error(`missing PR description for ${slug}`)
+  const text = new TextDecoder().decode(description.content)
+  const newline = text.indexOf('\n')
+  const title = (newline === -1 ? text : text.slice(0, newline)).replace(/^#+\s*/, '').trim()
+  if (title === '') throw new Error(`empty PR title for ${slug}`)
+  const created = events.findLast((event) => event.type === 'build.created')
+  if (created?.type !== 'build.created') throw new Error(`missing build.created for ${slug}`)
+
+  await completeFinalizePr(
+    {
+      store: deps.store,
+      env: {
+        store: deps.storeRef,
+        build: slug,
+        phase: 'finalize',
+        round: 1,
+        session: `dispatcher-${deps.runId}`,
+      },
+      workspacePath: deps.workspacePath,
+      forge: deps.forge,
+      exec: deps.exec,
+      ids: deps.ids,
+    },
+    events,
+    {
+      branch: request.payload.branch,
+      baseBranch: created.payload.baseBranch,
+      title,
+      body: newline === -1 ? '' : text.slice(newline + 1).replace(/^\n+/, ''),
+      mergeMessage: text,
+      expectedHeadSha: request.payload.sha,
+    },
+  )
+}

package/packages/core/src/cli/repo-state.ts

@@ -0,0 +1,213 @@
+/**
+ * Repository identity and sessionless local-state resolution.
+ *
+ * Repository identity (SPEC §7.2, §12) is the checkout's normalized origin
+ * URL (`normalizeGitRemoteUrl`), not the checkout path: a path-based identity
+ * makes two hosts disagree about which repository they operate. A checkout
+ * with no `origin` remote falls back to its resolved path, so origin-less
+ * local fixtures keep today's behavior. `RepoStatePaths` therefore carries
+ * BOTH: `repo` is the store-keyed identity, `checkout` is the physical main
+ * checkout every filesystem consumer (config path, plugin loading, forge
+ * `repoRoot`, worktree root, live-reload source) keeps using.
+ *
+ * Records written before the identity change are keyed by checkout path and
+ * are NOT migrated; they remain visible where their recorded `repoOrigin`
+ * matches the querying checkout (see `buildInRepository`).
+ *
+ * One resolver owns both concepts because they must agree in linked worktrees:
+ * Git's repository/worktree metadata identifies the main checkout, whose
+ * `.autobuild/` directory is the implicit state root. Local overrides are
+ * normalized against that checkout so the dispatcher and agents cannot
+ * interpret a relative path from different working directories.
+ */
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { BuildRecord } from '../store/types'
+import { normalizeGitRemoteUrl } from '../kernel/origin'
+
+export { normalizeGitRemoteUrl } from '../kernel/origin'
+
+export const LOCAL_STATE_DIR = '.autobuild'
+
+export function isRemoteStoreRef(ref: string): boolean {
+  return /^https?:\/\//i.test(ref)
+}
+
+function absoluteGitPath(path: string, target: string): string {
+  return isAbsolute(path) ? resolve(path) : resolve(target, path)
+}
+
+/**
+ * Resolve the main checkout from Git's repository/worktree topology.
+ *
+ * A normal checkout (including a submodule or `--separate-git-dir` checkout)
+ * has equal Git and common directories, so `--show-toplevel` is authoritative.
+ * A linked worktree has a per-worktree Git directory and a shared common
+ * directory; Git's worktree registry lists the main checkout first. This avoids
+ * assuming the common directory is `<checkout>/.git`, which is false for
+ * submodules and separately stored Git directories.
+ *
+ * Outside Git (or when Git cannot be executed), the resolved target directory
+ * is the deterministic fallback.
+ */
+export async function resolveMainRepo(targetRepo: string, exec: Exec): Promise<string> {
+  const target = resolve(targetRepo)
+  try {
+    const result = await exec(
+      [
+        'git',
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-dir',
+        '--git-common-dir',
+        '--show-toplevel',
+      ],
+      { cwd: target },
+    )
+    if (result.exitCode !== 0) return target
+    const [gitDirRaw, commonDirRaw, topLevelRaw] = result.stdout.trimEnd().split('\n')
+    if (!gitDirRaw || !commonDirRaw || !topLevelRaw) return target
+
+    const gitDir = absoluteGitPath(gitDirRaw, target)
+    const commonDir = absoluteGitPath(commonDirRaw, target)
+    const topLevel = absoluteGitPath(topLevelRaw, target)
+    if (gitDir === commonDir) return topLevel
+
+    const worktrees = await exec(['git', 'worktree', 'list', '--porcelain', '-z'], { cwd: target })
+    if (worktrees.exitCode === 0) {
+      const main = worktrees.stdout
+        .split('\0')
+        .find((entry) => entry.startsWith('worktree '))
+        ?.slice('worktree '.length)
+      if (main) return absoluteGitPath(main, target)
+    }
+
+    // Old Git versions without porcelain -z still have the ordinary linked
+    // layout. Only derive from dirname when the common dir is literally .git;
+    // otherwise the current worktree is safer than writing inside Git metadata.
+    return basename(commonDir) === '.git' ? dirname(commonDir) : topLevel
+  } catch {
+    return target
+  }
+}
+
+export interface RepoStatePaths {
+  /** Repository identity in BuildStore records/journals: the checkout's
+   * normalized origin URL, falling back to the resolved checkout path only
+   * when the checkout has no origin remote. Opaque to the store schema. */
+  repo: string
+  /** The physical main checkout — the value `repo` held before the origin
+   * identity. Every filesystem consumer (config path, plugin loading, forge
+   * `repoRoot`, worktree root, live-reload source) uses this. */
+  checkout: string
+  /** The only implicit local state root. */
+  defaultLocalRoot: string
+  /** Normalized local path, or an unchanged HTTP(S) URL. */
+  storeRef: string
+  /** Root for local-only state (tickets and worktrees). */
+  localStateRoot: string
+  /** Local scratch root used by GitWorktreeProvider. */
+  worktreeRoot: string
+}
+
+function nonBlank(value: string | undefined): string | undefined {
+  return value !== undefined && value.trim() !== '' ? value : undefined
+}
+
+/**
+ * Select state with one precedence rule for every sessionless command:
+ * non-blank explicit `--store` > non-blank `AB_STORE` > repository-local default.
+ *
+ * A local selection relocates the whole local tree, including worktrees. A
+ * remote store has no filesystem root, so its worktrees remain local beneath
+ * the repository's implicit state root.
+ */
+export function resolveRepoStatePaths(opts: {
+  /** Repository identity: a normalized origin URL, or a local checkout path. */
+  repo: string
+  /** The physical checkout. Defaults to `repo` so origin-less fixtures —
+   * where identity IS the path — need no extra argument. */
+  checkout?: string
+  storeRef?: string
+  envStore?: string
+}): RepoStatePaths {
+  const checkout = resolve(opts.checkout ?? opts.repo)
+  const defaultLocalRoot = join(checkout, LOCAL_STATE_DIR)
+  const selected = nonBlank(opts.storeRef) ?? nonBlank(opts.envStore) ?? defaultLocalRoot
+  const remote = isRemoteStoreRef(selected)
+  const storeRef = remote ? selected : resolve(checkout, selected)
+  const localStateRoot = remote ? defaultLocalRoot : storeRef
+  return {
+    repo: opts.repo,
+    checkout,
+    defaultLocalRoot,
+    storeRef,
+    localStateRoot,
+    worktreeRoot: join(localStateRoot, 'worktrees'),
+  }
+}
+
+/**
+ * The normalized origin remote of a checkout, or undefined when the checkout
+ * has no `origin` remote or git fails (non-zero exit or thrown). Never throws.
+ */
+export async function resolveRepoOrigin(repo: string, exec: Exec): Promise<string | undefined> {
+  try {
+    const result = await exec(['git', 'remote', 'get-url', 'origin'], { cwd: repo })
+    if (result.exitCode !== 0) return undefined
+    const raw = result.stdout.trim()
+    return raw === '' ? undefined : normalizeGitRemoteUrl(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether a build record belongs to the repository checked out at `checkout`.
+ * Identity is the checkout's normalized origin (falling back to the checkout
+ * path when there is no origin remote); for new records `record.repo` IS that
+ * origin, so equality is the whole test. Records written before the origin
+ * identity are keyed by checkout path and are NOT migrated (decision
+ * 2026-09-10); a mismatch is forgiven only when the record carries a
+ * normalized origin equal to the checkout's identity — a differently located
+ * checkout of the same repository (a sandbox guest, a second host clone) is
+ * the same repository, while a different origin (or an origin-less record)
+ * is foreign.
+ */
+export async function buildInRepository(
+  record: BuildRecord,
+  checkout: string,
+  exec: Exec,
+): Promise<boolean> {
+  const origin = await resolveRepoOrigin(checkout, exec)
+  const identity = origin ?? resolve(checkout)
+  if (record.repo === identity) return true
+  if (record.repoOrigin === undefined) return false
+  // The recorded side is normalized too (idempotent for records written by
+  // this code) so a guard never depends on the writer's normalizer vintage —
+  // an ssh-spelled recorded origin still equals the https spelling computed
+  // here.
+  return normalizeGitRemoteUrl(record.repoOrigin) === identity
+}
+
+/** Resolve repository identity, then select all state paths from it.
+ *
+ * Identity is the resolved main checkout's normalized origin remote, falling
+ * back to the checkout path when the checkout has no origin (local fixtures,
+ * tests). `checkout` carries the resolved path for every filesystem
+ * consumer. */
+export async function resolveRepoState(opts: {
+  targetRepo: string
+  exec: Exec
+  storeRef?: string
+  envStore?: string
+}): Promise<RepoStatePaths> {
+  const checkout = await resolveMainRepo(opts.targetRepo, opts.exec)
+  const origin = await resolveRepoOrigin(checkout, opts.exec)
+  return resolveRepoStatePaths({
+    repo: origin ?? checkout,
+    checkout,
+    ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+    ...(opts.envStore !== undefined ? { envStore: opts.envStore } : {}),
+  })
+}