@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.8

package/scripts/generate-channel-promotion-workflow.mjs

@@ -159,8 +159,8 @@ function validateWorkflowRoute(name, route, expectedLogicalRef) {
   if (!/^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/.test(route.workflowPath || "")) {
     throw new Error(`promotion shell ${name} workflowPath must name a reusable workflow`);
   }
-  if (!/^(?:v[0-9]+(?:-alpha)?|train\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
-    throw new Error(`promotion shell ${name} callRef must be an official channel ref, trusted train, or exact SHA`);
+  if (!/^(?:v[0-9]+(?:-alpha)?|(?:train|alpha|release)\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
+    throw new Error(`promotion shell ${name} callRef must be an official tag, protected channel ref, trusted train, or exact SHA`);
   }
   if (typeof route.forwardInternalInputs !== "boolean") {
     throw new Error(`promotion shell ${name} forwardInternalInputs must be boolean`);

package/scripts/generate-release-candidate-passport.mjs

@@ -5,11 +5,160 @@ import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { createReleaseCandidatePassport, validateReleaseCandidatePassport } from "../packages/core/release-candidate.js";
 import { scanV4FloatingConsumerPolicy, v4ConsumerPolicyScannerRoot } from "../packages/core/v4-floating-consumer-policy.js";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { V4_STAGE_CAPSULE_CONTRACT, V4_STAGE_CAPSULE_IDENTITY_CONTRACT, v4StageCapsuleIdentityRoot, v4StageCapsuleRoot, validateV4StageCapsule } from "../packages/core/v4-stage-capsule.js";
+import { v4RuntimeResumeDocumentRoot } from "../packages/core/v4-runtime-ref-resume-authority.js";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
 const env = (name, fallback = "") => process.env[name] || fallback;
 const readJsonFile = (filePath) => JSON.parse(fs.readFileSync(filePath, "utf8"));
 
+export function createReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  coordinates,
+}) {
+  if (!passport.consumerPolicy?.receiptRoot) return undefined;
+  if (
+    coordinates.repository !== passport.repository ||
+    String(coordinates.runId) !== String(passport.workflow.runId) ||
+    String(coordinates.runAttempt) !== String(passport.workflow.runAttempt) ||
+    coordinates.sourceSha !== passport.source.headSha
+  ) {
+    throw new Error(
+      "Stage Capsule coordinate set does not bind the candidate run",
+    );
+  }
+  const coordinateByPlatform = new Map(
+    coordinates.artifacts.map((entry) => [entry.platformId, entry]),
+  );
+  const qualificationRoot = passport.controllerReceipts?.[0]?.receiptDigest;
+  const entries = passport.platformMatrix
+    .map((platform) => {
+      const coordinate = coordinateByPlatform.get(platform.platformId);
+      if (!coordinate || coordinate.name !== platform.artifactName) {
+        throw new Error(
+          `Stage Capsule coordinate missing for ${platform.platformId}`,
+        );
+      }
+      const manifest = readJsonFile(platform.manifestPath);
+      const identity = {
+        schema: V4_STAGE_CAPSULE_IDENTITY_CONTRACT,
+        sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+        platform: platform.platformId,
+        platformRoot: v4ContentRoot("candidate-identity", manifest.platform),
+        stage: "verify",
+        toolchainRoots: [],
+        runtimeRoot: v4ContentRoot("candidate-identity", {
+          sha: passport.buildchain.sha,
+        }),
+        policyRoot: passport.consumerPolicy.receiptRoot,
+        declaredInputs: [
+          {
+            name: "release-candidate",
+            root: `sha256:${passport.candidateHash}`,
+          },
+        ],
+        transformationRoot: v4ContentRoot("candidate-identity", {
+          lifecycle: manifest.lifecycle,
+          summary: platform.summary,
+        }),
+        outputManifestRoot: v4ContentRoot(
+          "stage-capsule-artifact-manifest",
+          { artifact: coordinate, manifest },
+        ),
+        qualificationRoot,
+        observationRoots: [
+          {
+            name: "provider-coordinate",
+            root: v4ContentRoot("provider-readback-sample", coordinate),
+          },
+        ],
+      };
+      const capsule = {
+        schema: V4_STAGE_CAPSULE_CONTRACT,
+        writerAuthority: "typescript-v3",
+        rustAuthority: "validation-only",
+        identity,
+        identityRoot: v4StageCapsuleIdentityRoot(identity),
+        retentionPromise: {
+          class: "github-artifact",
+          retainUntil: coordinate.expiresAt,
+        },
+        capsuleRoot: `sha256:${"0".repeat(64)}`,
+      };
+      capsule.capsuleRoot = v4StageCapsuleRoot(capsule);
+      validateV4StageCapsule(capsule);
+      return {
+        platform: platform.platformId,
+        artifactName: coordinate.name,
+        artifactDigest: coordinate.digest,
+        artifact: coordinate,
+        capsule,
+      };
+    })
+    .sort((left, right) => left.platform.localeCompare(right.platform));
+  const body = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-release-candidate-stage-capsules/v1",
+    status: "sealed",
+    repository: passport.repository,
+    buildAttempt: {
+      id: `github-run:${passport.workflow.runId}:attempt:${passport.workflow.runAttempt}`,
+      runtimeSha: passport.buildchain.sha,
+    },
+    source: {
+      sha: passport.source.headSha,
+      treeSha: passport.source.treeHash,
+    },
+    consumerPolicyReceiptRoot: passport.consumerPolicy.receiptRoot,
+    capsules: entries,
+  };
+  return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
+}
+
+function writeReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  outputPath,
+}) {
+  const coordinatesPath = path.resolve(
+    env(
+      "BUILDCHAIN_ARTIFACT_COORDINATES_PATH",
+      ".buildchain/artifacts/artifact-coordinates.json",
+    ),
+  );
+  if (!fs.existsSync(coordinatesPath)) {
+    if (passport.consumerPolicy?.receiptRoot) {
+      throw new Error(
+        "v4 release candidate Stage Capsules require exact artifact coordinates",
+      );
+    }
+    return { path: "", root: "" };
+  }
+  const stageCapsules = createReleaseCandidateStageCapsules({
+    passport,
+    buildSummary,
+    coordinates: readJsonFile(coordinatesPath),
+  });
+  if (!stageCapsules) return { path: "", root: "" };
+  const stageCapsulesPath = path.join(
+    path.dirname(outputPath),
+    "release-candidate-stage-capsules.json",
+  );
+  fs.writeFileSync(
+    stageCapsulesPath,
+    `${JSON.stringify(stageCapsules, null, 2)}\n`,
+  );
+  return {
+    path: path
+      .relative(process.cwd(), stageCapsulesPath)
+      .split(path.sep)
+      .join("/"),
+    root: stageCapsules.root,
+  };
+}
+
 export function resolveLegacyConsumerPolicyReceipt(options = {}) {
   if (options.json) return { receipt: JSON.parse(options.json), receiptRoot: options.receiptRoot };
   if (options.repository !== "kungfu-systems/buildchain" || options.targetChannel !== "alpha" || options.workflowShellRef !== "v4-alpha" || options.runtimeOverride !== true) return undefined;
@@ -80,6 +229,7 @@ export function generateReleaseCandidatePassportCli() {
   if (!validation.ok) throw new Error(`release candidate passport invalid: ${validation.errors.join("; ")}`);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, `${JSON.stringify(passport, null, 2)}\n`);
+  const stageCapsules = writeReleaseCandidateStageCapsules({ passport, buildSummary, outputPath });
   writeGitHubOutputs({
     "release-candidate-passport-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
     "release-candidate-passport-json": JSON.stringify({
@@ -94,6 +244,8 @@ export function generateReleaseCandidatePassportCli() {
       consumerPolicy: passport.consumerPolicy,
       controllerReceipts: passport.controllerReceipts || [],
     }),
+    "release-candidate-stage-capsules-path": stageCapsules.path,
+    "release-candidate-stage-capsules-root": stageCapsules.root,
   });
   return passport;
 }

package/scripts/generate-site-bundle.mjs

@@ -54,6 +54,23 @@ const V4_COMPATIBILITY_FACTS_SCHEMA =
   "schemas/v4-compatibility-facts-v1.schema.json";
 const V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE =
   "contracts/v4-compatibility-facts-v1.schema.json";
+const V4_PUBLICATION_REHEARSAL_SCHEMA =
+  "schemas/v4-publication-rehearsal-capsule-v1.schema.json";
+const V4_PUBLICATION_REHEARSAL_SCHEMA_SOURCE =
+  "contracts/v4-publication-rehearsal-capsule-v1.schema.json";
+const V4_ADOPTER_DELIVERY_SCHEMA =
+  "schemas/v4-adopter-delivery-v1.schema.json";
+const V4_ADOPTER_DELIVERY_SCHEMA_SOURCE =
+  "contracts/v4-adopter-delivery-v1.schema.json";
+const RELEASE_TAIL_CAPABILITIES_SCHEMA =
+  "schemas/release-tail-capabilities-v1.schema.json";
+const RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE =
+  "contracts/release-tail-capabilities-v1.schema.json";
+const PUBLICATION_REHEARSAL_SITE_SCHEMAS = [
+  V4_PUBLICATION_REHEARSAL_SCHEMA,
+  V4_ADOPTER_DELIVERY_SCHEMA,
+  RELEASE_TAIL_CAPABILITIES_SCHEMA,
+];
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
 const requireFromHere = createRequire(import.meta.url);
@@ -84,6 +101,9 @@ function stableJson(value) {
 function siteFileBytes(name, value) {
   if (name === DEV_DELIVERY_AUTHORITY_SCHEMA) return readText(DEV_DELIVERY_AUTHORITY_SCHEMA_SOURCE);
   if (name === V4_COMPATIBILITY_FACTS_SCHEMA) return readText(V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE);
+  if (name === V4_PUBLICATION_REHEARSAL_SCHEMA) return readText(V4_PUBLICATION_REHEARSAL_SCHEMA_SOURCE);
+  if (name === V4_ADOPTER_DELIVERY_SCHEMA) return readText(V4_ADOPTER_DELIVERY_SCHEMA_SOURCE);
+  if (name === RELEASE_TAIL_CAPABILITIES_SCHEMA) return readText(RELEASE_TAIL_CAPABILITIES_SCHEMA_SOURCE);
   return stableJson(value);
 }
 
@@ -396,6 +416,7 @@ const manualMetaById = new Map(Object.entries({
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
+  "v4-adopter-delivery": { capabilityGroup: "reusable-build", audience: ["consumer", "developer", "agent"], maturity: "preview", order: 205 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
   "runtime-train-validation": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer"], maturity: "stable", order: 220 },
   "kfd-support": { capabilityGroup: "kfd-trust", audience: ["agent", "maintainer"], maturity: "stable", order: 300 },
@@ -956,6 +977,7 @@ function buildSiteBundle() {
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
       "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "kfd-support.json",
       "artifact-evidence.json",
       "product-mechanism.json",
@@ -992,6 +1014,7 @@ function buildSiteBundle() {
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
       "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1124,6 +1147,7 @@ function buildSiteBundle() {
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/dev-delivery-authority-v2.schema.json",
       "schemas/v4-compatibility-facts-v1.schema.json",
+      ...PUBLICATION_REHEARSAL_SITE_SCHEMAS,
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1304,6 +1328,12 @@ function buildSiteBundle() {
     [V4_COMPATIBILITY_FACTS_SCHEMA]: readJson(
       V4_COMPATIBILITY_FACTS_SCHEMA_SOURCE,
     ),
+    ...Object.fromEntries(
+      PUBLICATION_REHEARSAL_SITE_SCHEMAS.map((name) => [
+        name,
+        JSON.parse(siteFileBytes(name)),
+      ]),
+    ),
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),

package/scripts/promotion-channel-router.mjs

@@ -66,8 +66,8 @@ export function resolvePromotionChannel({
   }
   const shellRef = intent.shellChannel === "alpha" ? `v${selected.major}-alpha` : `v${selected.major}`;
   return {
-    targetRef: intent.targetRef,
-    publicationChannel: intent.publicationChannel,
+    targetRef: intent.targetRef, publicationChannel: intent.publicationChannel,
+    routerRef: normalized(routerRef), routerSha: normalized(routerSha).toLowerCase(),
     channel: intent.shellChannel,
     major: selected.major,
     shellRef,
@@ -99,8 +99,8 @@ function readPackageVersion(cwd) {
 
 function writeOutputs(file, result) {
   const outputs = {
-    "target-ref": result.targetRef,
-    "publication-channel": result.publicationChannel,
+    "target-ref": result.targetRef, "publication-channel": result.publicationChannel,
+    "router-ref": result.routerRef, "router-sha": result.routerSha,
     channel: result.channel,
     major: String(result.major),
     "shell-ref": result.shellRef,

package/scripts/release-candidate-anchor-provenance.mjs

@@ -0,0 +1,99 @@
+import path from "node:path";
+
+export function resolveAnchorRecoveryRequest({ passport, buildSummary, transactionId = "" } = {}) {
+  if (Number(passport?.pullRequest?.number || 0)) return undefined;
+  if (passport?.target?.channel !== "anchor" || passport?.target?.ref !== "publish-gate/anchor") {
+    throw new Error("Release Candidate Passport has no PR identity");
+  }
+  let releaseManifest;
+  try {
+    releaseManifest = JSON.parse(buildSummary?.publishSource?.releaseManifest || "");
+  } catch {
+    throw new Error("anchored candidate release manifest is invalid");
+  }
+  const request = releaseManifest?.anchorRequest;
+  if (
+    releaseManifest?.sourceRef !== "publish-gate/anchor" ||
+    releaseManifest?.sourceSha !== passport.source?.headSha ||
+    request?.schema !== 1 ||
+    request?.contract !== "kungfu-buildchain-explicit-publish-anchor-request/v1" ||
+    !request.assignmentId ||
+    !/^native:[0-9a-f-]+$/u.test(String(request.attemptId || "")) ||
+    request.transactionId !== transactionId ||
+    request.source?.sha !== passport.source?.headSha ||
+    request.source?.tree !== passport.source?.treeHash ||
+    !/^\d+$/u.test(String(request.supersededCandidate?.workflowRunId || "")) ||
+    !/^[0-9a-f]{40}$/u.test(String(request.supersededCandidate?.sha || "")) ||
+    !/^sha256:[0-9a-f]{64}$/u.test(String(request.supersededCandidate?.root || "")) ||
+    request.runtime?.sha !== passport.buildchain?.sha
+  ) {
+    throw new Error("anchored candidate request does not bind the sealed recovery identity");
+  }
+  return request;
+}
+
+function normalizeRun(run, repository) {
+  return {
+    id: String(run.id), repository,
+    headRepository: run.head_repository?.full_name || "",
+    status: run.status, conclusion: run.conclusion,
+    event: run.event, path: run.path, name: run.name,
+    headSha: run.head_sha || "", headBranch: run.head_branch || "",
+    pullRequestNumbers: (run.pull_requests || []).map((entry) => Number(entry.number)),
+  };
+}
+
+export function normalizeCandidateRun(run, repository) {
+  return normalizeRun(run, repository);
+}
+
+export function normalizeAnchorProvenance(anchorProvenance, repository) {
+  if (!anchorProvenance) return undefined;
+  return {
+    request: anchorProvenance.request,
+    run: normalizeRun(anchorProvenance.run, repository),
+    workflow: {
+      path: anchorProvenance.workflow.path,
+      name: anchorProvenance.workflow.name,
+      state: anchorProvenance.workflow.state,
+    },
+    passport: anchorProvenance.passport,
+    buildSummary: anchorProvenance.buildSummary,
+  };
+}
+
+export async function recoverCandidateProvenance({
+  passport, buildSummary, transactionId, repoInfo, artifactName,
+  expectedWorkflowFile, expectedWorkflowName, channel, apiUrl, token,
+  fetchImpl, archiveDir, bundleRoot, githubJson, selectReleaseCandidateArtifacts,
+  downloadArtifact, readOnlyJson,
+}) {
+  const request = resolveAnchorRecoveryRequest({ passport, buildSummary, transactionId });
+  if (!request) {
+    return { anchorProvenance: undefined, provenancePassport: passport };
+  }
+  const runId = String(request.supersededCandidate.workflowRunId);
+  const run = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${runId}` });
+  const workflow = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${run.workflow_id}` });
+  const artifactResponse = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${runId}/artifacts?per_page=100` });
+  const artifacts = Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [];
+  if (Number(artifactResponse.total_count || artifacts.length) !== artifacts.length) throw new Error("superseded candidate run has more than 100 artifacts; complete pagination is required before recovery");
+  const selected = selectReleaseCandidateArtifacts({ artifacts, artifactName });
+  const provenanceRoot = path.join(bundleRoot, "anchored-provenance");
+  const passportDownload = await downloadArtifact({ artifact: selected.passport, repoInfo, apiUrl, token, archiveDir, bundleRoot: provenanceRoot, fetchImpl });
+  const summaryDownload = await downloadArtifact({ artifact: selected.summary, repoInfo, apiUrl, token, archiveDir, bundleRoot: provenanceRoot, fetchImpl });
+  const recoveredPassport = readOnlyJson(passportDownload.files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "superseded release-candidate-passport.json");
+  const recoveredBuildSummary = readOnlyJson(summaryDownload.files.filter((file) => path.basename(file.path) === "build-summary.json"), "superseded build-summary.json");
+  if (
+    String(run.id) !== runId ||
+    recoveredPassport.workflow?.runId !== runId ||
+    recoveredPassport.workflow?.name !== expectedWorkflowName ||
+    String(workflow.path || run.path || "").split("@")[0].replace(/^\.github\/workflows\//u, "") !== expectedWorkflowFile.replace(/^\.github\/workflows\//u, "") ||
+    recoveredPassport.target?.channel !== channel ||
+    recoveredPassport.source?.headSha !== request.supersededCandidate.sha ||
+    recoveredPassport.source?.treeHash !== request.source.tree ||
+    `sha256:${recoveredPassport.candidateHash}` !== request.supersededCandidate.root
+  ) throw new Error("superseded candidate provenance does not match the anchored request");
+  const anchorProvenance = { request, run, workflow, passport: recoveredPassport, buildSummary: recoveredBuildSummary };
+  return { anchorProvenance, provenancePassport: recoveredPassport };
+}

package/scripts/release-tail.mjs

@@ -11,6 +11,10 @@ import {
   writeReleaseTailTransaction,
 } from "../packages/core/release-tail-provider-plane.js";
 import { diagnoseLegacyReleaseTailHooks } from "../packages/core/release-tail-compatibility.js";
+import {
+  V4_PUBLICATION_REHEARSAL_EVIDENCE_CONTRACT,
+  executeV4PublicationRehearsal,
+} from "../packages/core/v4-publication-rehearsal.js";
 
 function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
@@ -34,8 +38,52 @@ function output(value, filePath = "") {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
-export function runReleaseTailCli(args = process.argv.slice(2)) {
+export async function runReleaseTailCli(args = process.argv.slice(2)) {
   const [mode = "status", ...options] = args;
+  if (mode === "rehearse") {
+    const capsulePath = flag(options, "capsule");
+    const candidateRoot = flag(options, "candidate-root");
+    const statePath = flag(options, "state");
+    const evidencePath = flag(options, "evidence");
+    for (const [name, value] of Object.entries({
+      "--capsule": capsulePath,
+      "--candidate-root": candidateRoot,
+      "--state": statePath,
+      "--evidence": evidencePath,
+    }))
+      if (!value || !path.isAbsolute(value))
+        throw new Error(`${name} must be an explicit absolute path`);
+    const rehearsalMode = flag(options, "mode", "simulate");
+    if (!new Set(["simulate", "replay"]).has(rehearsalMode))
+      throw new Error(
+        "local rehearsal --mode must be simulate or replay; authorized provider rehearsal uses the reusable workflow",
+      );
+    try {
+      const result = await executeV4PublicationRehearsal({
+        capsule: readJson(capsulePath, "--capsule"),
+        candidateRoot,
+        mode: rehearsalMode,
+        checkpoint: (transaction) =>
+          writeReleaseTailTransaction(statePath, transaction),
+      });
+      writeReleaseTailTransaction(statePath, result.transaction);
+      output(result.evidence, evidencePath);
+      return result;
+    } catch (error) {
+      output(
+        {
+          schema: V4_PUBLICATION_REHEARSAL_EVIDENCE_CONTRACT,
+          status: "rejected",
+          code: error.code || "publication-rehearsal-runtime-error",
+          message: error.message,
+          productionAuthority: false,
+          releasePassport: null,
+        },
+        evidencePath,
+      );
+      throw error;
+    }
+  }
   if (mode === "plan") {
     const plan = compileReleaseTailDeclaration(
       readJson(flag(options, "declaration"), "--declaration"),
@@ -95,7 +143,7 @@ export function runReleaseTailCli(args = process.argv.slice(2)) {
     return report;
   }
   throw new Error(
-    "usage: buildchain release-tail <plan|init|status|verify|compat> [--declaration <json-or-path>] [--state <path>] [--hooks-json <json-or-path>] [--output <path>]",
+    "usage: buildchain release-tail <plan|init|status|verify|compat|rehearse> [--declaration <json-or-path>] [--capsule <absolute-path>] [--candidate-root <absolute-path>] [--mode <simulate|replay>] [--state <absolute-path>] [--evidence <absolute-path>] [--hooks-json <json-or-path>] [--output <path>]",
   );
 }
 
@@ -105,7 +153,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    runReleaseTailCli();
+    await runReleaseTailCli();
   } catch (error) {
     console.error(`release-tail: ${error.message}`);
     process.exitCode = 1;