@kungfu-tech/buildchain 3.0.5-alpha.8 → 3.0.6-alpha.0

package/scripts/dispatch-artifact-signing-authority.mjs

@@ -12,37 +12,110 @@ function required(value, label) {
 
 function repository(value, label) {
   const normalized = required(value, label);
-  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(normalized)) throw new Error(`${label} must be owner/repository`);
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(normalized))
+    throw new Error(`${label} must be owner/repository`);
   return normalized;
 }
 
 const TRANSIENT_GITHUB_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
-const DEFAULT_ARTIFACT_SIGNING_AUTHORITY_REF = "authority/v3/v3.0/artifact-signing";
+const DEFAULT_ARTIFACT_SIGNING_AUTHORITY_REF =
+  "authority/v3/v3.0/artifact-signing";
+const AUTHORITY_WORKFLOW = "artifact-signing-authority.yml";
 
 export function resolveAuthorityDispatchRef(value) {
   const ref = required(value, "authority ref");
-  return /^[0-9a-f]{40}$/u.test(ref) ? DEFAULT_ARTIFACT_SIGNING_AUTHORITY_REF : ref;
+  return /^[0-9a-f]{40}$/u.test(ref)
+    ? DEFAULT_ARTIFACT_SIGNING_AUTHORITY_REF
+    : ref;
+}
+
+export async function resolveArtifactSigningAuthorityRuntime({
+  authorityRepository,
+  authorityRef,
+  token,
+  requestImpl = githubRequest,
+}) {
+  const authorityRepo = repository(authorityRepository, "authority repository");
+  const ref = resolveAuthorityDispatchRef(authorityRef);
+  const encodedRef = ref.split("/").map(encodeURIComponent).join("/");
+  const response = await requestImpl(
+    `/repos/${authorityRepo}/git/ref/heads/${encodedRef}`,
+    { token: required(token, "Buildchain authority dispatch token") },
+  );
+  if (response?.object?.type !== "commit") {
+    throw new Error(
+      "Buildchain signing authority ref does not resolve to a commit",
+    );
+  }
+  const sha = String(response.object.sha || "");
+  if (!/^[0-9a-f]{40}$/u.test(sha)) {
+    throw new Error("Buildchain signing authority runtime SHA must be exact");
+  }
+  return { ref, sha };
 }
 
 function retryDelayMs(attempt) {
-  return Math.min(1_000 * (2 ** (attempt - 1)), 10_000);
+  return Math.min(1_000 * 2 ** (attempt - 1), 10_000);
 }
 
-export async function githubRequest(url, {
-  token,
-  method = "GET",
-  body,
-  fetchImpl = fetch,
-  delayImpl = delay,
-  maxAttempts = 5,
-  warnImpl = console.warn,
-} = {}) {
+function authorityError(message, outputs = {}) {
+  const error = new Error(message);
+  error.authorityOutputs = outputs;
+  return error;
+}
+
+export function validateArtifactSigningAuthorityRun(
+  run,
+  { authorityRepository, authorityRuntimeSha, expectedTitle },
+) {
+  if (!run || typeof run !== "object") {
+    throw new Error("Buildchain signing authority run is missing");
+  }
+  if (String(run.display_title || "") !== expectedTitle) {
+    throw new Error("Buildchain signing authority correlation mismatch");
+  }
+  if (String(run.event || "") !== "workflow_dispatch") {
+    throw new Error("Buildchain signing authority event mismatch");
+  }
+  if (String(run.head_sha || "") !== authorityRuntimeSha) {
+    throw new Error("Buildchain signing authority runtime SHA mismatch");
+  }
+  if (
+    run.repository?.full_name &&
+    String(run.repository.full_name) !== authorityRepository
+  ) {
+    throw new Error("Buildchain signing authority repository mismatch");
+  }
+  if (
+    run.path &&
+    !String(run.path).startsWith(`.github/workflows/${AUTHORITY_WORKFLOW}@`)
+  ) {
+    throw new Error("Buildchain signing authority workflow path mismatch");
+  }
+  return run;
+}
+
+export async function githubRequest(
+  url,
+  {
+    token,
+    method = "GET",
+    body,
+    fetchImpl = fetch,
+    delayImpl = delay,
+    maxAttempts = 5,
+    warnImpl = console.warn,
+  } = {},
+) {
   const methodName = String(method).toUpperCase();
   const retrySafe = methodName === "GET";
   const requestedAttempts = Number(maxAttempts);
-  const attemptLimit = retrySafe && Number.isSafeInteger(requestedAttempts) && requestedAttempts > 0
-    ? requestedAttempts
-    : 1;
+  const attemptLimit =
+    retrySafe &&
+    Number.isSafeInteger(requestedAttempts) &&
+    requestedAttempts > 0
+      ? requestedAttempts
+      : 1;
   for (let attempt = 1; attempt <= attemptLimit; attempt += 1) {
     let response;
     try {
@@ -59,7 +132,9 @@ export async function githubRequest(url, {
       });
     } catch (error) {
       if (retrySafe && attempt < attemptLimit) {
-        warnImpl(`Buildchain signing authority: GitHub API GET transport failure; retry ${attempt + 1}/${attemptLimit}`);
+        warnImpl(
+          `Buildchain signing authority: GitHub API GET transport failure; retry ${attempt + 1}/${attemptLimit}`,
+        );
         await delayImpl(retryDelayMs(attempt));
         continue;
       }
@@ -67,19 +142,29 @@ export async function githubRequest(url, {
     }
     if (!response.ok) {
       const text = await response.text();
-      if (retrySafe && TRANSIENT_GITHUB_STATUSES.has(response.status) && attempt < attemptLimit) {
-        warnImpl(`Buildchain signing authority: GitHub API GET returned ${response.status}; retry ${attempt + 1}/${attemptLimit}`);
+      if (
+        retrySafe &&
+        TRANSIENT_GITHUB_STATUSES.has(response.status) &&
+        attempt < attemptLimit
+      ) {
+        warnImpl(
+          `Buildchain signing authority: GitHub API GET returned ${response.status}; retry ${attempt + 1}/${attemptLimit}`,
+        );
         await delayImpl(retryDelayMs(attempt));
         continue;
       }
-      throw new Error(`GitHub API ${methodName} ${url} failed (${response.status}): ${text.slice(0, 500)}`);
+      throw new Error(
+        `GitHub API ${methodName} ${url} failed (${response.status}): ${text.slice(0, 500)}`,
+      );
     }
     if (response.status === 204) return {};
     try {
       return await response.json();
     } catch (error) {
       if (retrySafe && attempt < attemptLimit) {
-        warnImpl(`Buildchain signing authority: GitHub API GET response failed to decode; retry ${attempt + 1}/${attemptLimit}`);
+        warnImpl(
+          `Buildchain signing authority: GitHub API GET response failed to decode; retry ${attempt + 1}/${attemptLimit}`,
+        );
         await delayImpl(retryDelayMs(attempt));
         continue;
       }
@@ -89,70 +174,236 @@ export async function githubRequest(url, {
   throw new Error("GitHub API retry loop exhausted");
 }
 
+async function pollArtifactSigningAuthorityRun({
+  authorityRepository,
+  token,
+  authorityRuntimeSha,
+  expectedTitle,
+  startedAtMs,
+  deadline,
+  baseOutputs,
+  requestImpl,
+  delayImpl,
+  nowImpl,
+}) {
+  let run;
+  while (nowImpl() < deadline) {
+    const response = await requestImpl(
+      `/repos/${authorityRepository}/actions/workflows/${AUTHORITY_WORKFLOW}/runs?event=workflow_dispatch&per_page=50`,
+      { token },
+    );
+    const matches = (response.workflow_runs || []).filter(
+      (entry) =>
+        new Date(entry.created_at).getTime() >= startedAtMs - 30_000 &&
+        String(entry.display_title || "") === expectedTitle,
+    );
+    if (matches.length > 1) {
+      throw authorityError(
+        "multiple Buildchain signing authority runs share one correlation",
+        { ...baseOutputs, "authority-status": "failed" },
+      );
+    }
+    if (matches.length === 1) {
+      try {
+        run = validateArtifactSigningAuthorityRun(matches[0], {
+          authorityRepository,
+          authorityRuntimeSha,
+          expectedTitle,
+        });
+      } catch (error) {
+        throw authorityError(error.message, {
+          ...baseOutputs,
+          "authority-run-id": String(matches[0].id || ""),
+          "authority-run-url": String(matches[0].html_url || ""),
+          "authority-status": "failed",
+        });
+      }
+    }
+    if (run?.status === "completed") return run;
+    await delayImpl(10_000);
+  }
+  throw authorityError("timed out waiting for Buildchain signing authority", {
+    ...baseOutputs,
+    "authority-run-id": String(run?.id || ""),
+    "authority-run-url": String(run?.html_url || ""),
+    "authority-status": "timed-out",
+    "authority-conclusion": String(run?.conclusion || "timed-out"),
+    "controller-completed-at": new Date(nowImpl()).toISOString(),
+  });
+}
+
+function successfulAuthorityResult({
+  run,
+  baseOutputs,
+  resultArtifact,
+  correlationId,
+  controllerStartedAt,
+  completedAt,
+}) {
+  if (run.conclusion !== "success") {
+    const status = run.conclusion === "cancelled" ? "cancelled" : "failed";
+    throw authorityError(
+      `Buildchain signing authority failed: ${run.html_url}`,
+      {
+        ...baseOutputs,
+        "authority-run-id": String(run.id),
+        "authority-run-url": String(run.html_url || ""),
+        "authority-status": status,
+        "authority-conclusion": String(run.conclusion || status),
+        "controller-completed-at": completedAt,
+      },
+    );
+  }
+  return {
+    outputs: {
+      ...baseOutputs,
+      "authority-run-id": String(run.id),
+      "authority-run-url": String(run.html_url || ""),
+      "authority-status": "succeeded",
+      "authority-conclusion": "success",
+      "controller-completed-at": completedAt,
+    },
+    result: {
+      runId: run.id,
+      runUrl: run.html_url,
+      authorityRuntimeSha: baseOutputs["authority-runtime-sha"],
+      resultArtifact,
+      correlationId,
+      status: "succeeded",
+      startedAt: controllerStartedAt,
+      completedAt,
+    },
+  };
+}
+
 export async function dispatchArtifactSigningAuthority({
   token = process.env.BUILDCHAIN_AUTHORITY_DISPATCH_TOKEN,
-  authorityRepository = process.env.BUILDCHAIN_AUTHORITY_REPOSITORY || "kungfu-systems/buildchain",
+  authorityRepository = process.env.BUILDCHAIN_AUTHORITY_REPOSITORY ||
+    "kungfu-systems/buildchain",
   authorityRef = process.env.BUILDCHAIN_AUTHORITY_REF,
   sourceRepository = process.env.GITHUB_REPOSITORY,
   sourceRunId = process.env.GITHUB_RUN_ID,
   sourceRunAttempt = process.env.GITHUB_RUN_ATTEMPT || "1",
   requestArtifact = process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT,
+  requestRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT_DIGEST,
   runtimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
   resultArtifact = process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT,
+  correlationId = process.env.BUILDCHAIN_AUTHORITY_CORRELATION_ID || "",
   timeoutSeconds = process.env.BUILDCHAIN_SIGNING_TIMEOUT_SECONDS || "7200",
+  requestImpl = githubRequest,
+  delayImpl = delay,
+  nowImpl = () => Date.now(),
 } = {}) {
   const authToken = required(token, "Buildchain authority dispatch token");
   const authorityRepo = repository(authorityRepository, "authority repository");
   const sourceRepo = repository(sourceRepository, "source repository");
   const ref = resolveAuthorityDispatchRef(authorityRef);
   const runtime = required(runtimeSha, "Buildchain runtime SHA");
-  if (!/^[0-9a-f]{40}$/u.test(runtime)) throw new Error("Buildchain runtime SHA must be exact");
-  const correlationId = `${required(sourceRunId, "source run ID")}-${required(sourceRunAttempt, "source run attempt")}-${runtime.slice(0, 12)}-${required(requestArtifact, "request artifact").replace(/[^A-Za-z0-9._-]+/gu, "-")}`;
+  if (!/^[0-9a-f]{40}$/u.test(runtime))
+    throw new Error("Buildchain runtime SHA must be exact");
+  const runId = required(sourceRunId, "source run ID");
+  const runAttempt = required(sourceRunAttempt, "source run attempt");
+  if (!/^[1-9][0-9]*$/u.test(runAttempt)) {
+    throw new Error("source run attempt must be a positive integer");
+  }
+  const requestName = required(requestArtifact, "request artifact");
+  const requestRootDigest = required(requestRoot, "request root");
+  if (!/^sha256:[0-9a-f]{64}$/u.test(requestRootDigest)) {
+    throw new Error("request root must be a canonical sha256 root");
+  }
+  const correlation = required(
+    correlationId ||
+      `${runId}-${runAttempt}-${runtime.slice(0, 12)}-${requestName.replace(/[^A-Za-z0-9._-]+/gu, "-")}`,
+    "correlation ID",
+  );
   const resultName = required(resultArtifact, "result artifact");
-  const workflow = "artifact-signing-authority.yml";
-  const startedAt = Date.now() - 30_000;
-  await githubRequest(`/repos/${authorityRepo}/actions/workflows/${workflow}/dispatches`, {
-    token: authToken,
-    method: "POST",
-    body: {
-      ref,
-      inputs: {
-        "source-repository": sourceRepo,
-        "source-run-id": String(sourceRunId),
-        "request-artifact-pattern": required(requestArtifact, "request artifact"),
-        "result-artifact-name": resultName,
-        "correlation-id": correlationId,
-        "expected-runtime-sha": runtime,
+  const timeout = Number(timeoutSeconds);
+  if (!Number.isFinite(timeout) || timeout <= 0) {
+    throw new Error("Buildchain signing timeout must be positive");
+  }
+  const controllerStartedAtMs = nowImpl();
+  const controllerStartedAt = new Date(controllerStartedAtMs).toISOString();
+  const baseOutputs = {
+    "result-artifact": resultName,
+    "correlation-id": correlation,
+    "controller-started-at": controllerStartedAt,
+  };
+  try {
+    const authorityRuntime = await resolveArtifactSigningAuthorityRuntime({
+      authorityRepository: authorityRepo,
+      authorityRef: ref,
+      token: authToken,
+      requestImpl,
+    });
+    baseOutputs["authority-runtime-sha"] = authorityRuntime.sha;
+    await requestImpl(
+      `/repos/${authorityRepo}/actions/workflows/${AUTHORITY_WORKFLOW}/dispatches`,
+      {
+        token: authToken,
+        method: "POST",
+        body: {
+          ref: authorityRuntime.ref,
+          inputs: {
+            "source-repository": sourceRepo,
+            "source-run-id": runId,
+            "source-run-attempt": runAttempt,
+            "request-artifact-pattern": requestName,
+            "expected-request-root": requestRootDigest,
+            "result-artifact-name": resultName,
+            "correlation-id": correlation,
+            "expected-runtime-sha": runtime,
+          },
+        },
       },
-    },
-  });
-  const deadline = Date.now() + Number(timeoutSeconds) * 1000;
-  let run;
-  while (Date.now() < deadline) {
-    const response = await githubRequest(`/repos/${authorityRepo}/actions/workflows/${workflow}/runs?event=workflow_dispatch&per_page=50`, { token: authToken });
-    run = (response.workflow_runs || []).find((entry) =>
-      new Date(entry.created_at).getTime() >= startedAt &&
-      String(entry.display_title || "").includes(correlationId),
     );
-    if (run?.status === "completed") break;
-    await delay(10_000);
-  }
-  if (!run || run.status !== "completed") throw new Error("timed out waiting for Buildchain signing authority");
-  if (run.conclusion !== "success") throw new Error(`Buildchain signing authority failed: ${run.html_url}`);
-  writeGitHubOutputs({
-    "authority-run-id": String(run.id),
-    "authority-run-url": run.html_url,
-    "result-artifact": resultName,
-    "correlation-id": correlationId,
-  });
-  return { runId: run.id, runUrl: run.html_url, resultArtifact: resultName, correlationId };
+    const expectedTitle = `Sign ${sourceRepo} run ${runId} (${correlation})`;
+    const run = await pollArtifactSigningAuthorityRun({
+      authorityRepository: authorityRepo,
+      token: authToken,
+      authorityRuntimeSha: authorityRuntime.sha,
+      expectedTitle,
+      startedAtMs: controllerStartedAtMs,
+      deadline: controllerStartedAtMs + timeout * 1000,
+      baseOutputs,
+      requestImpl,
+      delayImpl,
+      nowImpl,
+    });
+    const completedAt = new Date(nowImpl()).toISOString();
+    const completed = successfulAuthorityResult({
+      run,
+      baseOutputs,
+      resultArtifact: resultName,
+      correlationId: correlation,
+      controllerStartedAt,
+      completedAt,
+    });
+    writeGitHubOutputs(completed.outputs);
+    return completed.result;
+  } catch (error) {
+    if (!error.authorityOutputs) {
+      error.authorityOutputs = {
+        ...baseOutputs,
+        "authority-status": "failed",
+        "authority-conclusion": "controller-error",
+        "controller-completed-at": new Date(nowImpl()).toISOString(),
+      };
+    }
+    throw error;
+  }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
   try {
     await dispatchArtifactSigningAuthority();
   } catch (error) {
-    console.error(`::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`);
+    if (error?.authorityOutputs) writeGitHubOutputs(error.authorityOutputs);
+    console.error(
+      `::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
     process.exitCode = 1;
   }
 }

package/scripts/generate-site-bundle.mjs

@@ -364,6 +364,7 @@ const manualMetaById = new Map(Object.entries({
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
+  "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
@@ -724,6 +725,7 @@ function buildSiteBundle() {
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/stable-candidate-patrol.md",
+      "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
       "docs/observed-evidence-patrol.md",
       "docs/release-governance.md",
@@ -784,6 +786,7 @@ function buildSiteBundle() {
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
         ["stable-candidate-patrol", "repository-patrol"],
+        ["dev-qualification-patrol", "repository-patrol"],
         ["dev-alpha-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-patrol", "repository-patrol"],
         ["buildchain-stable-candidate-qualification", "repository-patrol"],

package/scripts/inspect-artifact-signing-requests.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { validateArtifactSigningRequest } from "../packages/core/artifact-signing.js";
+import { artifactSigningRequestRoot } from "./artifact-signing-controller-core.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
 
 function required(value, label) {
@@ -35,12 +36,14 @@ export function inspectArtifactSigningRequests({
   inputRoot = process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
   expectedRepository = process.env.BUILDCHAIN_SIGNING_SOURCE_REPOSITORY,
   expectedRuntimeSha = process.env.BUILDCHAIN_RUNTIME_SHA,
+  expectedRequestRoot = process.env.BUILDCHAIN_SIGNING_EXPECTED_REQUEST_ROOT,
 } = {}) {
   const root = path.resolve(required(inputRoot, "signing request root"));
   const indexes = walk(root, "index.json");
   if (indexes.length === 0)
     throw new Error("no artifact signing request indexes found");
   const seen = new Set();
+  const observedRoots = [];
   const matrices = {
     detached: [],
     macos: [],
@@ -52,6 +55,7 @@ export function inspectArtifactSigningRequests({
       index.contract !== "kungfu-buildchain-artifact-signing-request-index/v1"
     )
       continue;
+    observedRoots.push(artifactSigningRequestRoot(index));
     for (const entry of index.requests || []) {
       const requestPath = path.resolve(path.dirname(indexPath), entry.path);
       const relative = path.relative(root, requestPath);
@@ -113,6 +117,14 @@ export function inspectArtifactSigningRequests({
         );
     }
   }
+  if (expectedRequestRoot) {
+    if (observedRoots.length !== 1) {
+      throw new Error("signing authority expected exactly one request root");
+    }
+    if (observedRoots[0] !== expectedRequestRoot) {
+      throw new Error("signing authority request root mismatch");
+    }
+  }
   for (const entries of Object.values(matrices))
     entries.sort((a, b) => a.request.localeCompare(b.request));
   writeGitHubOutputs({

package/scripts/release-propagation.mjs

@@ -18,7 +18,12 @@ import {
   writeReleasePropagationLock,
   createManualUpstreamPickupCapture,
   createManualUpstreamPickupPlan,
+  createReleasePropagationPushPlan,
+  executeReleasePropagationPush,
+  inspectReleasePropagationPushState,
   normalizeManualUpstreamPickupConfig,
+  planSiteUpstreamAgentEntry,
+  RELEASE_PROPAGATION_FAILURE_MATRIX,
   resolveNpmRegistryRelease,
 } from "../packages/core/release-propagation.js";
 
@@ -66,6 +71,19 @@ function usage() {
                                               --completion-decision <json-or-path>
                                               --expected-work-root <sha256:...>
                                               [--output <file>] [--json]
+  buildchain release-propagation work push-plan --work <json-or-path>
+                                             --expected-work-root <sha256:...>
+                                             [--cwd <dir>] [--remote <name>]
+                                             [--output <file>] [--json]
+  buildchain release-propagation work push-branch --work <json-or-path>
+                                               --expected-work-root <sha256:...>
+                                               [--cwd <dir>] [--remote <name>]
+                                               --execute [--output <file>] [--json]
+  buildchain release-propagation entry plan --source-id <paper|kfd|buildchain|kungfu-core>
+                                            [--channel <alpha|release>]
+                                            [--handoff-work <json-or-path>]
+                                            [--output <file>] [--json]
+  buildchain release-propagation entry fault-matrix [--json]
   buildchain release-propagation pickup plan --config <json-or-path>
                                             --source-id <id> --channel <alpha|release>
                                             --current-version <version>
@@ -182,9 +200,60 @@ function runWorkCli(args) {
     emitWorkResult(workArgs, result, `release propagation work complete: ${result.contentRoot}`);
     return;
   }
+  if (mode === "push-plan" || mode === "push-branch") {
+    const work = readJsonFlag(workArgs, "work");
+    const cwd = readFlag(workArgs, "cwd", process.cwd());
+    const remote = readFlag(workArgs, "remote", "origin");
+    let result;
+    if (mode === "push-plan") {
+      const repositoryState = inspectReleasePropagationPushState({ work, cwd, remote });
+      result = createReleasePropagationPushPlan({
+        work,
+        expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+        repositoryState,
+      });
+    } else {
+      if (!hasFlag(workArgs, "execute")) throw new Error("work push-branch requires --execute");
+      result = executeReleasePropagationPush({
+        work,
+        expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+        cwd,
+        remote,
+      });
+    }
+    emitWorkResult(workArgs, result, mode === "push-plan"
+      ? `release propagation push plan: ${result.planRoot}`
+      : `release propagation push result: ${result.resultRoot}`);
+    return;
+  }
   throw new Error(`unsupported release-propagation work command: ${mode}`);
 }
 
+function runEntryCli(args) {
+  const [mode = "", ...entryArgs] = args;
+  if (!mode || mode === "--help" || mode === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  let result;
+  if (mode === "fault-matrix") {
+    result = RELEASE_PROPAGATION_FAILURE_MATRIX;
+  } else if (mode === "plan") {
+    result = planSiteUpstreamAgentEntry({
+      sourceId: readFlag(entryArgs, "source-id"),
+      channel: readFlag(entryArgs, "channel"),
+      handoffWork: entryArgs.includes("--handoff-work")
+        ? readJsonFlag(entryArgs, "handoff-work")
+        : null,
+    });
+  } else {
+    throw new Error(`unsupported release-propagation entry command: ${mode}`);
+  }
+  writeOutput(readFlag(entryArgs, "output", ""), result);
+  if (hasFlag(entryArgs, "json")) printJson(result);
+  else process.stdout.write(`${result.contract}\n`);
+}
+
 async function resolvePickupPlan(args) {
   const config = normalizeManualUpstreamPickupConfig(readJsonFlag(args, "config"));
   const sourceId = readFlag(args, "source-id");
@@ -274,6 +343,10 @@ export async function runReleasePropagationCli(argv = process.argv.slice(2)) {
     runWorkCli(args);
     return;
   }
+  if (mode === "entry") {
+    runEntryCli(args);
+    return;
+  }
   if (mode === "pickup") {
     await runPickupCli(args);
     return;

package/scripts/run-lifecycle-core.mjs

@@ -28,6 +28,7 @@ import {
   parseExpectedArtifactsJson,
   validateExpectedArtifacts,
 } from "./build-contract-core.mjs";
+import { verifyCompilerCacheActivity } from "./compiler-cache-evidence.mjs";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const buildchainCliCandidates = [
@@ -391,6 +392,22 @@ function writeDiagnosticsSidecarManifest(filePath, {
   return manifest;
 }
 
+export function verifyBuildLifecycleCompilerCacheActivity({
+  stageName = "",
+  executed = false,
+  cwd = process.cwd(),
+  env = process.env,
+  verifier = verifyCompilerCacheActivity,
+  frameworkLog,
+} = {}) {
+  if (stageName !== "build" || !executed) return undefined;
+  const activity = verifier({ cwd, env });
+  if (activity) {
+    frameworkLog?.info("compiler-cache.activity", { attributes: activity });
+  }
+  return activity;
+}
+
 export function runLifecycle({
   cwd = process.cwd(),
   stageName = "",
@@ -646,6 +663,13 @@ export function runLifecycle({
     throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
   }
 
+  const compilerCacheActivity = verifyBuildLifecycleCompilerCacheActivity({
+    stageName,
+    executed,
+    cwd: resolvedCwd,
+    frameworkLog,
+  });
+
   const shouldReadProcessSummary = Boolean(
     resolvedProcessSummaryPath
       && (fs.existsSync(resolvedProcessSummaryPath) || processSummaryRequired),
@@ -739,6 +763,7 @@ export function runLifecycle({
     fileCount: summary.fileCount,
   });
   observability.lifecycle = lifecycleObservability;
+  Object.assign(observability, { compilerCacheActivity });
   observability.diagnostics = {
     contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
     path: relativeDiagnosticsPath,