@ever-works/github-actions-build-plugin 1.0.2 → 1.0.4

package/dist/index.cjs

@@ -42,6 +42,31 @@ function octokitActionsRunsPort(octokit) {
       );
       return asArray(data, "workflow_runs");
     },
+    async listWorkflowRunsConditional({ repository, workflowFile, perPage, etag }) {
+      try {
+        const response = await octokit.request(
+          "GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs",
+          {
+            owner: repository.owner,
+            repo: repository.repo,
+            workflow_id: workflowFile,
+            per_page: perPage,
+            ...etag ? { headers: { "if-none-match": etag } } : {}
+          }
+        );
+        const next = response.headers?.etag;
+        return {
+          notModified: false,
+          ...typeof next === "string" ? { etag: next } : {},
+          runs: asArray(response.data, "workflow_runs")
+        };
+      } catch (error) {
+        if (error.status === 304) {
+          return { notModified: true, ...etag ? { etag } : {}, runs: [] };
+        }
+        throw error;
+      }
+    },
     async getWorkflowRun({ repository, runId }) {
       try {
         const { data } = await octokit.request("GET /repos/{owner}/{repo}/actions/runs/{run_id}", {
@@ -218,7 +243,39 @@ function observeRun({ run, jobs, mode }) {
 }
 var RESULT_ARTIFACT_MAX_ZIP_BYTES = 65536;
 var RESULT_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
-var ALLOWED_KEYS = /* @__PURE__ */ new Set(["digest", "imageRepository", "tags", "secretCheck", "smoke"]);
+var RESULT_SCHEMA_NAME = "ever-works-build-result";
+var RESULT_SCHEMA_VERSION = 1;
+var ALLOWED_KEYS = /* @__PURE__ */ new Set([
+  // T12's first shape.
+  "digest",
+  "imageRepository",
+  "tags",
+  "secretCheck",
+  "smoke",
+  // The generator's versioned shape (`resultStep` in workflow/generator.ts).
+  "schema",
+  "version",
+  "buildId",
+  "sha",
+  "verification",
+  "reusedDigest",
+  "localBuild"
+]);
+var VERIFICATION_KEYS = /* @__PURE__ */ new Set(["jobs", "smoke"]);
+var COMMIT_SHA_PATTERN = /^[a-f0-9]{40}$/i;
+function normaliseResultDigest(raw) {
+  if (typeof raw !== "string") return "";
+  const trimmed = raw.trim();
+  const at = trimmed.lastIndexOf("@");
+  return at >= 0 ? trimmed.slice(at + 1) : trimmed;
+}
+function passRows(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((row) => typeof row === "object" && row !== null).map((row) => ({
+    name: String(row.name ?? ""),
+    passed: row.passed === true || row.conclusion === "success"
+  }));
+}
 function parseResultArtifact(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return { ok: false, refusal: "malformedJson" };
@@ -228,22 +285,55 @@ function parseResultArtifact(value) {
   if (unknown.length > 0) {
     return { ok: false, refusal: "unknownKeys" };
   }
-  const digest = typeof bag.digest === "string" ? bag.digest.trim() : "";
-  if (!RESULT_DIGEST_PATTERN.test(digest)) {
+  const versioned = "schema" in bag || "version" in bag;
+  if (versioned && (bag.schema !== RESULT_SCHEMA_NAME || bag.version !== RESULT_SCHEMA_VERSION)) {
+    return { ok: false, refusal: "unsupportedSchema" };
+  }
+  let verification = null;
+  if (bag.verification !== void 0) {
+    if (typeof bag.verification !== "object" || bag.verification === null || Array.isArray(bag.verification)) {
+      return { ok: false, refusal: "malformedJson" };
+    }
+    verification = bag.verification;
+    if (Object.keys(verification).some((key) => !VERIFICATION_KEYS.has(key))) {
+      return { ok: false, refusal: "unknownKeys" };
+    }
+  }
+  const digest = normaliseResultDigest(bag.digest);
+  if (digest.length > 0 || !versioned) {
+    if (!RESULT_DIGEST_PATTERN.test(digest)) {
+      return { ok: false, refusal: "badDigest" };
+    }
+  }
+  const reusedDigest = normaliseResultDigest(bag.reusedDigest);
+  if (reusedDigest.length > 0 && !RESULT_DIGEST_PATTERN.test(reusedDigest)) {
     return { ok: false, refusal: "badDigest" };
   }
-  const result = { digest };
+  const result = {};
+  if (digest.length > 0) result.digest = digest;
+  if (versioned) result.schemaVersion = RESULT_SCHEMA_VERSION;
   if (typeof bag.imageRepository === "string" && bag.imageRepository.trim().length > 0) {
     result.imageRepository = bag.imageRepository.trim();
   }
   if (Array.isArray(bag.tags)) {
-    result.tags = bag.tags.filter((tag) => typeof tag === "string");
+    result.tags = bag.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0);
   }
   if (bag.secretCheck === "passed" || bag.secretCheck === "failed" || bag.secretCheck === "not_needed") {
     result.secretCheck = bag.secretCheck;
   }
-  if (Array.isArray(bag.smoke)) {
-    result.smoke = bag.smoke.filter((row) => typeof row === "object" && row !== null).map((row) => ({ name: String(row.name ?? ""), passed: row.passed === true }));
+  if (typeof bag.buildId === "string" && bag.buildId.trim().length > 0) {
+    result.buildId = bag.buildId.trim();
+  }
+  if (typeof bag.sha === "string" && COMMIT_SHA_PATTERN.test(bag.sha.trim())) {
+    result.sha = bag.sha.trim().toLowerCase();
+  }
+  if (reusedDigest.length > 0) result.reusedDigest = reusedDigest;
+  if (typeof bag.localBuild === "boolean") result.localBuild = bag.localBuild;
+  if (Array.isArray(bag.smoke) || Array.isArray(verification?.smoke)) {
+    result.smoke = [...passRows(bag.smoke), ...passRows(verification?.smoke)];
+  }
+  if (Array.isArray(verification?.jobs)) {
+    result.verificationJobs = passRows(verification?.jobs);
   }
   return { ok: true, result };
 }
@@ -285,7 +375,11 @@ async function readResultArtifact(port, input) {
   } catch {
     return { ok: false, refusal: "malformedJson" };
   }
-  return parseResultArtifact(decoded);
+  const parsed = parseResultArtifact(decoded);
+  if (parsed.ok && input.expectBuildId && parsed.result.buildId && parsed.result.buildId !== input.expectBuildId) {
+    return { ok: false, refusal: "buildMismatch" };
+  }
+  return parsed;
 }
 
 // src/runs/failure-classifier.ts
@@ -1291,7 +1385,7 @@ function resultStep(job, secretCheckPresent) {
     `jq -n --arg buildId "\${{ inputs.ew_build_id }}" --arg sha "$EW_SHA" \\`,
     `  --arg imageRepository "$EW_IMAGE" --arg digest "$digest" --arg secretCheck "$secret_check" \\`,
     `  --arg tag "$EW_IMAGE:sha-$EW_SHA" \\`,
-    `  '{schema:"ever-works-build-result",version:1,buildId:$buildId,sha:$sha,imageRepository:$imageRepository,'`,
+    `  '{schema:"ever-works-build-result",version:1,buildId:$buildId,sha:$sha,imageRepository:$imageRepository,`,
     `    digest:$digest,tags:[$tag],secretCheck:$secretCheck,verification:{jobs:[],smoke:[]}}' > ${contracts.APP_BUILD_RESULT_ARTIFACT_FILE}`
   ] : [
     "set -euo pipefail",
@@ -1301,7 +1395,7 @@ function resultStep(job, secretCheckPresent) {
     `jq -n --arg buildId "\${{ inputs.ew_build_id }}" --arg sha "$EW_SHA" \\`,
     `  --arg imageRepository "$EW_IMAGE" --arg reusedDigest "$reused_digest" \\`,
     `  --argjson localBuild "$local_build" \\`,
-    `  '{schema:"ever-works-build-result",version:1,buildId:$buildId,sha:$sha,imageRepository:$imageRepository,'`,
+    `  '{schema:"ever-works-build-result",version:1,buildId:$buildId,sha:$sha,imageRepository:$imageRepository,`,
     `    reusedDigest:$reusedDigest,localBuild:$localBuild,verification:{jobs:[],smoke:[]}}' > ${contracts.APP_BUILD_RESULT_ARTIFACT_FILE}`
   ];
   return ["      - name: Write result", "        if: always()", "        run: |", ...scalarBlock(script, 10)];
@@ -1375,7 +1469,8 @@ async function readBranchHead(writer, branch) {
 function repositoryWriteErrorCode(error) {
   const candidate = error;
   for (const value of [candidate?.code, candidate?.reason]) {
-    if (value === "nonFastForward" || value === "refRejectedByRule" || value === "pullRequestExists") return value;
+    if (value === "nonFastForward" || value === "refRejectedByRule" || value === "pullRequestExists" || value === "workflowPermissionMissing")
+      return value;
   }
   return null;
 }
@@ -1417,14 +1512,36 @@ async function writeWorkflow(input, writer, protection) {
   const removal = input.content === "";
   if (removal) {
     if (!existsOnTrackedBranch) return { state: "unchanged", storedWorkflowSha256: null };
-    return pullRequestDelivery(input, writer, path, contentSha256, handEdited, REMOVAL_COPY);
+    return withWorkflowPermission(
+      () => pullRequestDelivery(input, writer, path, contentSha256, handEdited, REMOVAL_COPY)
+    );
   }
   const verdict = createdByAppWork && !handEdited && protection ? await isBranchProtected(protection, { owner, repo, branch: trackedBranch }) : { protected: false};
   const pullRequestPath = !createdByAppWork || handEdited || verdict.protected;
   if (pullRequestPath) {
-    return pullRequestDelivery(input, writer, path, contentSha256, handEdited);
+    return withWorkflowPermission(() => pullRequestDelivery(input, writer, path, contentSha256, handEdited));
+  }
+  return withWorkflowPermission(() => directDelivery(input, writer, path, contentSha256, existsOnTrackedBranch));
+}
+async function withWorkflowPermission(deliver) {
+  try {
+    return await deliver();
+  } catch (error) {
+    if (repositoryWriteErrorCode(error) !== "workflowPermissionMissing") throw error;
+    const facts = error;
+    return {
+      state: "blocked",
+      storedWorkflowSha256: null,
+      blocked: {
+        reason: "workflowPermissionMissing",
+        detail: {
+          cause: "workflowPermissionMissing",
+          credential: typeof facts.credential === "string" ? facts.credential : "unknown",
+          missing: typeof facts.missing === "string" ? facts.missing : "workflow"
+        }
+      }
+    };
   }
-  return directDelivery(input, writer, path, contentSha256, existsOnTrackedBranch);
 }
 async function directDelivery(input, writer, path, contentSha256, existsOnTrackedBranch) {
   const { trackedBranch } = input.repository;
@@ -1669,6 +1786,234 @@ function createBuildValueSecretSync(dependencies) {
   };
 }
 
+// src/repo/octokit-repository-writer.ts
+var WORKFLOWS_DIRECTORY = ".github/workflows/";
+var RepositoryWriteError = class extends Error {
+  constructor(code, message, cause, credential, missing) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+    this.credential = credential;
+    this.missing = missing;
+    this.name = "RepositoryWriteError";
+  }
+};
+function workflowPermissionMissingError(credential, cause) {
+  const app = credential === "githubApp";
+  return new RepositoryWriteError(
+    "workflowPermissionMissing",
+    app ? 'The GitHub App installation cannot write workflow files: grant it "Workflows: Read and write".' : 'The GitHub connection cannot write workflow files: reconnect GitHub and grant the "workflow" scope.',
+    cause,
+    credential,
+    app ? "workflows:write" : "workflow"
+  );
+}
+var FULL_SHA2 = /^[0-9a-f]{40}$/i;
+function statusOf(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : void 0;
+}
+function messageOf(error) {
+  const candidate = error;
+  const parts = [];
+  if (typeof candidate?.message === "string") parts.push(candidate.message);
+  const data = candidate?.response?.data;
+  if (typeof data?.message === "string") parts.push(data.message);
+  if (Array.isArray(data?.errors)) {
+    for (const entry of data.errors) {
+      const message = entry?.message;
+      if (typeof message === "string") parts.push(message);
+    }
+  }
+  return parts.join(" | ");
+}
+var RULE_REFUSAL = /protected branch|ruleset|rule violation|required status|required review|push declined|cannot be updated/i;
+var WORKFLOW_REFUSAL = /workflow[^|]*\b(scope|permission)|\b(scope|permission)[^|]*workflow/i;
+var INTEGRATION_REFUSAL = /resource not accessible by integration/i;
+function scopesFromHeader(headers) {
+  const header = headers?.["x-oauth-scopes"];
+  if (typeof header !== "string") return null;
+  return header.split(",").map((scope) => scope.trim()).filter(Boolean);
+}
+function octokitRepositoryWriter(octokit, repository, credential = {}) {
+  const base = { owner: repository.owner, repo: repository.repo };
+  const kind = credential.credential ?? "unknown";
+  async function headOf(ref) {
+    if (FULL_SHA2.test(ref)) return ref;
+    const { data } = await octokit.request("GET /repos/{owner}/{repo}/git/ref/{ref}", {
+      ...base,
+      ref: `heads/${ref}`
+    });
+    const sha = data?.object?.sha;
+    if (typeof sha !== "string") throw new Error(`github-actions-build: no head commit for ${ref}`);
+    return sha;
+  }
+  async function assertCanWriteWorkflows() {
+    if (kind === "githubApp") return;
+    let scopes = credential.scopes ?? null;
+    if (!scopes) {
+      try {
+        scopes = scopesFromHeader((await octokit.request("GET /user")).headers);
+      } catch {
+        scopes = null;
+      }
+    }
+    if (scopes && !scopes.includes("workflow")) {
+      throw workflowPermissionMissingError(kind === "pat" ? "pat" : "oauth");
+    }
+  }
+  function translateWorkflowRefusal(error, touchesWorkflows) {
+    if (!touchesWorkflows || error instanceof RepositoryWriteError) return error;
+    const message = messageOf(error);
+    if (WORKFLOW_REFUSAL.test(message)) {
+      return workflowPermissionMissingError(/github app|integration/i.test(message) ? "githubApp" : kind, error);
+    }
+    return error;
+  }
+  async function commit(input, touchesWorkflows) {
+    const { data: baseCommit } = await octokit.request("GET /repos/{owner}/{repo}/git/commits/{commit_sha}", {
+      ...base,
+      commit_sha: input.baseSha
+    });
+    const baseTree = baseCommit?.tree?.sha;
+    if (typeof baseTree !== "string") {
+      throw new Error(`github-actions-build: commit ${input.baseSha} has no tree`);
+    }
+    const tree = [];
+    for (const file of input.files) {
+      const { data: blob } = await octokit.request("POST /repos/{owner}/{repo}/git/blobs", {
+        ...base,
+        content: file.content,
+        encoding: file.encoding === "base64" ? "base64" : "utf-8"
+      });
+      const sha = blob?.sha;
+      if (typeof sha !== "string") throw new Error(`github-actions-build: no blob sha for ${file.path}`);
+      tree.push({ path: file.path, mode: "100644", type: "blob", sha });
+    }
+    const { data: newTree } = await octokit.request("POST /repos/{owner}/{repo}/git/trees", {
+      ...base,
+      base_tree: baseTree,
+      tree
+    });
+    const { data: created } = await octokit.request("POST /repos/{owner}/{repo}/git/commits", {
+      ...base,
+      message: input.message,
+      tree: newTree.sha,
+      parents: [input.baseSha]
+    });
+    const commitSha = created.sha;
+    try {
+      await octokit.request("PATCH /repos/{owner}/{repo}/git/refs/{ref}", {
+        ...base,
+        ref: `heads/${input.branch}`,
+        sha: commitSha,
+        // Never a force-push: a moved branch is `nonFastForward`.
+        force: false
+      });
+    } catch (error) {
+      const status = statusOf(error);
+      const message = messageOf(error);
+      if (status === 422 && /fast[ -]?forward/i.test(message)) {
+        throw new RepositoryWriteError(
+          "nonFastForward",
+          `${input.branch} moved; retry from its new head`,
+          error
+        );
+      }
+      if ((status === 409 || status === 422 || status === 403) && RULE_REFUSAL.test(message)) {
+        throw new RepositoryWriteError("refRejectedByRule", `${input.branch} refused the update`, error);
+      }
+      if (touchesWorkflows && status === 403 && INTEGRATION_REFUSAL.test(message)) {
+        throw workflowPermissionMissingError("githubApp", error);
+      }
+      throw error;
+    }
+    return { commitSha };
+  }
+  return {
+    async getFileContent(path, ref) {
+      try {
+        const { data } = await octokit.request("GET /repos/{owner}/{repo}/contents/{path}", {
+          ...base,
+          path,
+          ...ref ?? repository.trackedBranch ? { ref: ref ?? repository.trackedBranch } : {}
+        });
+        const file = data;
+        if (Array.isArray(data) || file?.type !== "file" || typeof file.content !== "string") return null;
+        return {
+          content: file.content,
+          encoding: typeof file.encoding === "string" ? file.encoding : "base64"
+        };
+      } catch (error) {
+        if (statusOf(error) === 404) return null;
+        throw error;
+      }
+    },
+    async commitFiles(input) {
+      const touchesWorkflows = input.files.some((file) => file.path.startsWith(WORKFLOWS_DIRECTORY));
+      if (touchesWorkflows) await assertCanWriteWorkflows();
+      try {
+        return await commit(input, touchesWorkflows);
+      } catch (error) {
+        throw translateWorkflowRefusal(error, touchesWorkflows);
+      }
+    },
+    async createBranch(name, fromRef) {
+      try {
+        const { data } = await octokit.request("GET /repos/{owner}/{repo}/branches/{branch}", {
+          ...base,
+          branch: name
+        });
+        const branch = data;
+        return {
+          name: branch.name ?? name,
+          commit: branch.commit?.sha ?? "",
+          isDefault: false,
+          isProtected: branch.protected === true
+        };
+      } catch (error) {
+        if (statusOf(error) !== 404) throw error;
+      }
+      const sha = await headOf(fromRef);
+      await octokit.request("POST /repos/{owner}/{repo}/git/refs", {
+        ...base,
+        ref: `refs/heads/${name}`,
+        sha
+      });
+      return { name, commit: sha, isDefault: false };
+    },
+    async createPullRequest(options) {
+      try {
+        const { data } = await octokit.request("POST /repos/{owner}/{repo}/pulls", {
+          ...base,
+          title: options.title,
+          head: options.headOwner ? `${options.headOwner}:${options.head}` : options.head,
+          base: options.base,
+          ...options.body ? { body: options.body } : {},
+          ...options.draft ? { draft: true } : {}
+        });
+        const pr = data;
+        return {
+          number: pr.number,
+          title: pr.title ?? options.title,
+          state: pr.state === "closed" ? "closed" : "open",
+          head: options.head,
+          base: options.base,
+          url: pr.html_url ?? "",
+          createdAt: pr.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: pr.updated_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+          ...pr.body ? { body: pr.body } : {}
+        };
+      } catch (error) {
+        if (statusOf(error) === 422 && /pull request already exists/i.test(messageOf(error))) {
+          throw new RepositoryWriteError("pullRequestExists", "an open pull request already exists", error);
+        }
+        throw error;
+      }
+    }
+  };
+}
+
 // src/settings.schema.ts
 var LARGER_RUNNER_LABEL_PATTERN = "^[A-Za-z0-9._-]{1,64}$";
 var LARGER_RUNNER_MEMORY_MIN_GIB = 8;
@@ -1960,7 +2305,9 @@ var GitHubActionsBuildPlugin = class {
         buildInputsHash: contracts.computeBuildInputsHash(input.values ?? []),
         blocked: {
           reason: written.blocked?.reason ?? "workflowWriteFailed",
-          detail: { cause: written.blocked?.detail.cause ?? "unknown" }
+          // The whole detail: `workflowPermissionMissing` carries which credential
+          // and which permission, which is what the member's fix depends on.
+          detail: { ...written.blocked?.detail ?? { cause: "unknown" } }
         }
       };
     }
@@ -2088,13 +2435,16 @@ var GitHubActionsBuildPlugin = class {
     const jobs = await port.listRunJobs({ repository, runId });
     const snapshot = observeRun({ run, jobs, mode: "build" });
     const finished = snapshot.status !== "queued" && snapshot.status !== "running";
-    const artifact = finished ? await readResultArtifact(port, { repository, runId }) : null;
+    const artifact = finished ? await readResultArtifact(port, { repository, runId, expectBuildId: ref.buildId }) : null;
     const result = artifact?.ok ? artifact.result : null;
     const failure = snapshot.status === "failed" ? await this.classifyRunFailure({ port, repository, run, jobs, snapshot, result, redact }) : null;
     const pushLogDigest = result && snapshot.status === "succeeded" && isPushingTrigger(snapshot.trigger) ? await this.readPushLogDigest({ port, repository, jobs, sha: snapshot.commitSha }) : void 0;
     return {
       ...snapshot,
-      ...result ? {
+      // A versioned result with no digest (a failed build, a pull request, a
+      // verify job) still reports its secret check — it just claims no image.
+      ...result?.secretCheck && !result.digest ? { secretCheck: result.secretCheck } : {},
+      ...result?.digest ? {
         // `confirmed: false` without exception. This plugin reads the digest
         // the member's own CI claimed; confirming it against the registry is
         // `checkImageAccess` (T14), compared by `AppBuildsService.finalize`,
@@ -2249,6 +2599,78 @@ var GitHubActionsBuildPlugin = class {
   registryFetch() {
     return (url, init) => fetch(url, init);
   }
+  /**
+   * APW-05 T21a / T12 remainder — run discovery (plan §7.4a, `APW05-G01`).
+   *
+   * The newest runs of the build workflow, so a push or pull-request Build is
+   * recorded even when no `workflow_run` delivery reaches the platform (a
+   * personal fork connected through OAuth has no App installation to deliver
+   * from). `If-None-Match` with the stored `etag` makes an idle repository cost
+   * a 304 — which GitHub does not count against the rate limit.
+   *
+   * The mapping is `githubRunToBuildRunRef` from contracts, the SAME function
+   * the webhook consumer uses, so a polled run and a delivered run are the same
+   * `BuildRunRef` and converge on one Build row.
+   */
+  async listRecentRuns(input, auth) {
+    const port = this.actionsPort(auth);
+    const repository = { owner: input.repository.owner, repo: input.repository.name };
+    const workflowFile = input.workflowPath.split("/").pop() || WORKFLOW_FILE_NAME;
+    const perPage = Math.max(1, Math.min(contracts.APP_BUILD_RUN_DISCOVERY_PER_PAGE, Math.floor(input.perPage) || 1));
+    const page = port.listWorkflowRunsConditional ? await port.listWorkflowRunsConditional({
+      repository,
+      workflowFile,
+      perPage,
+      ...input.etag ? { etag: input.etag } : {}
+    }) : { notModified: false, runs: await port.listWorkflowRuns({ repository, workflowFile, perPage }) };
+    if (page.notModified) {
+      return { notModified: true, ...page.etag ? { etag: page.etag } : {}, runs: [] };
+    }
+    const runs = page.runs.map((run) => contracts.githubRunToBuildRunRef(run)).filter((run) => run !== null);
+    return { notModified: false, ...page.etag ? { etag: page.etag } : {}, runs };
+  }
+  /**
+   * APW-05 T16 remainder — the clone-free writer `prepareRepository` delivers the
+   * workflow through, over this plugin's own Octokit (see
+   * `repo/octokit-repository-writer.ts` on why the plugin supplies it).
+   */
+  repositoryWriter(repository, auth) {
+    return octokitRepositoryWriter(this.octokitFor(auth), repository, {
+      credential: auth.credential,
+      scopes: auth.scopes
+    });
+  }
+  /**
+   * Plan §5 — a Rebuild's `commitSha` must be reachable from the tracked branch
+   * (2026-10-17). `GET …/compare/{sha}...{branch}`: `ahead` or `identical` means
+   * the commit is in the branch's history; `behind` / `diverged` means it is not
+   * (a commit only a fork's network carries is `diverged`), and 404/422 means
+   * GitHub does not know it here. Any other failure is a throw.
+   */
+  async isCommitReachable(input, auth) {
+    try {
+      const { data } = await this.octokitFor(auth).request("GET /repos/{owner}/{repo}/compare/{basehead}", {
+        owner: input.repository.owner,
+        repo: input.repository.repo,
+        basehead: `${input.sha}...${input.branch}`,
+        per_page: 1
+      });
+      const status = data?.status;
+      return status === "ahead" || status === "identical";
+    } catch (error) {
+      const status = error?.status;
+      if (status === 404 || status === 422) return false;
+      throw error;
+    }
+  }
+  /** §4.10 — the per-run prompted-value secret's removal (T12's `secret-sync.ts`, now on the contract). */
+  async deleteVerifyPromptedSecret(repository, auth) {
+    return createBuildValueSecretSync({ port: this.secretPort(auth, repository) }).deleteVerifyPromptedSecret();
+  }
+  /** The Octokit client for one call — a seam a spec overrides, like {@link actionsPort}. */
+  octokitFor(auth) {
+    return new octokit.Octokit({ auth: auth.token });
+  }
   /** APW-05 T12 — the run's own page, which is where a member reads its logs. */
   async getLogsUrl(ref, auth) {
     const port = this.actionsPort(auth);