pullfrog 0.1.46 → 0.1.47

package/README.md

@@ -101,7 +101,7 @@ jobs:
 
 ```
 
-To gate merges on Pullfrog with branch protection, add `status_checks: enabled` under `with:`. Each PR run then posts a `pullfrog` check (run completion — success when the run finishes, failure on error/timeout) and a `pullfrog-approval` check (whether Pullfrog would approve the PR), both requireable as status checks. See [PR reviews → Required status checks](https://docs.pullfrog.dev/pr-reviews#required-status-checks-branch-protection).
+Every PR run posts a `Pullfrog` commit-status check: `in_progress` from the moment the run is dispatched, then success when it finishes or failure on error/timeout. It is on by default (turn it off per-repo in the console). To also gate merges on Pullfrog's review verdict, add `status_checks: enabled`, which additionally posts a `Pullfrog approval` check (whether Pullfrog would approve the PR). Both are requireable as branch-protection status checks. See [PR reviews → Status checks](https://docs.pullfrog.dev/pr-reviews#status-checks).
 
 #### 2. Create `triggers.yml`
 

package/dist/cli.mjs

@@ -101356,6 +101356,10 @@ async function setPullfrogSecret(ctx) {
   }
   return { saved: false, error: result.data.error || `api returned ${result.status}` };
 }
+function describeSecretTarget(ctx) {
+  if (ctx.scope === "account") return `account ${import_picocolors.default.cyan(`@${ctx.owner}`)}`;
+  return `repo ${import_picocolors.default.cyan(`${ctx.owner}/${ctx.repo}`)}`;
+}
 async function promptScope(ctx) {
   const scope2 = await _t({
     message: "secret scope",
@@ -101579,7 +101583,8 @@ async function runCodexAuth() {
       O2.warn(err instanceof Error ? err.message : String(err));
       savable = auth2;
     }
-    spin.start(`saving ${import_picocolors2.default.cyan(CODEX_AUTH_SECRET)} to Pullfrog`);
+    const target = describeSecretTarget({ owner: remote.owner, repo: remote.repo, scope: scope2 });
+    spin.start(`saving ${import_picocolors2.default.cyan(CODEX_AUTH_SECRET)} to ${target}`);
     const result = await setPullfrogSecret({
       token,
       owner: remote.owner,
@@ -101596,7 +101601,7 @@ async function runCodexAuth() {
       );
       process.exit(1);
     }
-    spin.stop(`saved ${import_picocolors2.default.cyan(CODEX_AUTH_SECRET)} to Pullfrog (${scope2})`);
+    spin.stop(`saved ${import_picocolors2.default.cyan(CODEX_AUTH_SECRET)} to ${target}`);
     setActiveSpin(null);
     gt("done.");
   } catch (error49) {
@@ -101693,7 +101698,8 @@ async function runClaudeAuth() {
         `that doesn't look like a ${import_picocolors2.default.cyan("claude setup-token")} token (expected ${import_picocolors2.default.cyan(`${CLAUDE_OAUTH_TOKEN_PREFIX}\u2026`)}). saving it anyway.`
       );
     }
-    spin.start(`saving ${import_picocolors2.default.cyan(CLAUDE_OAUTH_SECRET)} to Pullfrog`);
+    const target = describeSecretTarget({ owner: remote.owner, repo: remote.repo, scope: scope2 });
+    spin.start(`saving ${import_picocolors2.default.cyan(CLAUDE_OAUTH_SECRET)} to ${target}`);
     const result = await setPullfrogSecret({
       token,
       owner: remote.owner,
@@ -101710,7 +101716,7 @@ async function runClaudeAuth() {
       );
       process.exit(1);
     }
-    spin.stop(`saved ${import_picocolors2.default.cyan(CLAUDE_OAUTH_SECRET)} to Pullfrog (${scope2})`);
+    spin.stop(`saved ${import_picocolors2.default.cyan(CLAUDE_OAUTH_SECRET)} to ${target}`);
     setActiveSpin(null);
     gt("done.");
   } catch (error49) {
@@ -103050,7 +103056,7 @@ var import_semver = __toESM(require_semver2(), 1);
 // package.json
 var package_default = {
   name: "pullfrog",
-  version: "0.1.46",
+  version: "0.1.47",
   type: "module",
   bin: {
     pullfrog: "dist/cli.mjs",
@@ -159967,6 +159973,9 @@ var JsonPayload = type({
     id: "string",
     type: "'issue' | 'review'"
   }).or("undefined"),
+  // optional so a payload from an older server build (pre-`checkRun`) still parses
+  // against a newer action across a rolling deploy.
+  "checkRun?": type({ id: "string" }).or("undefined"),
   "generateSummary?": "boolean | undefined"
 });
 var COLLABORATOR_PERMISSIONS = ["admin", "maintain", "write"];
@@ -160080,13 +160089,19 @@ function resolvePayload(resolvedPromptInput, repoSettings) {
     timeout: inputs.timeout ?? jsonPayload?.timeout,
     cwd: resolveCwd(inputs.cwd),
     progressComment: jsonPayload?.progressComment,
+    checkRun: jsonPayload?.checkRun,
     generateSummary: jsonPayload?.generateSummary,
     // permissions: inputs > repoSettings > fallbacks
     push: inputs.push ?? repoSettings.push ?? "restricted",
     shell: resolvedShell,
-    // opt-in commit-status check-runs (branch protection). workflow-level
-    // static input, off unless the repo's pullfrog.yml sets status_checks: enabled.
-    statusChecks: inputs.status_checks === "enabled",
+    // the `pullfrog` run-lifecycle check. ON by default — the whole point is that a PR
+    // shows whether Pullfrog is running without anyone having to opt in. the workflow
+    // input is the source of truth when set (mirrors `push`); otherwise the repo
+    // setting decides.
+    runStatusCheck: inputs.status_checks === void 0 ? repoSettings.statusChecks : inputs.status_checks === "enabled",
+    // the `pullfrog-approval` verdict check stays opt-in and workflow-only. it exists to
+    // be *required* by branch protection, so it must never turn itself on.
+    approvalCheck: inputs.status_checks === "enabled",
     // temporary progress chrome. the workflow input is the source of truth when
     // set (mirrors `push`); otherwise the repo setting decides. defaults to true.
     progressComments: inputs.progress_comments === void 0 ? repoSettings.progressComments : inputs.progress_comments === "enabled",
@@ -160614,7 +160629,11 @@ async function approveAfterFix(ctx) {
     approved: true,
     hasComments: false
   });
-  ctx.toolState.approval = { wouldApprove: true, sha: headSha };
+  ctx.toolState.approval = {
+    wouldApprove: true,
+    sha: headSha,
+    url: result.data.html_url
+  };
   log.info(`\xBB auto-approved #${pullNumber} after fix run (review ${result.data.id})`);
   await deleteProgressComment(ctx).catch((err) => {
     log.debug(`progress comment cleanup after fix auto-approval failed: ${err}`);
@@ -160947,6 +160966,7 @@ function CreatePullRequestReviewTool(ctx) {
         }
         const reviewId = result.data.id;
         const reviewNodeId = result.data.node_id;
+        if (ctx.toolState.approval) ctx.toolState.approval.url = result.data.html_url;
         log.info(`\xBB created review ${reviewId} on pull request #${pull_number}`);
         const actuallyReviewedSha = primary.checkoutSha ?? params.commit_id;
         ctx.toolState.review = {
@@ -166963,6 +166983,7 @@ var defaultSettings = {
   autoMergeEnabled: false,
   signedCommits: false,
   progressComments: true,
+  statusChecks: true,
   modeInstructions: {},
   learnings: null,
   learningsHeadings: [],
@@ -167484,30 +167505,123 @@ function getCurrentWorkflowFilename() {
   return match3?.[1] ?? "pullfrog.yml";
 }
 
-// utils/statusChecks.ts
-var COMPLETION_CHECK = "pullfrog";
-var APPROVAL_CHECK = "pullfrog-approval";
-async function createCheckRun(ctx, params) {
+// utils/runStatusCheck.ts
+var RUN_STATUS_CHECK_NAME = "Pullfrog";
+var APPROVAL_CHECK_NAME = "Pullfrog approval";
+function parseCheckRunId(raw2) {
+  if (!raw2?.id) return void 0;
+  const id = parseInt(raw2.id, 10);
+  if (Number.isNaN(id) || id <= 0) return void 0;
+  return id;
+}
+function disableCheckLine(owner, repo) {
+  const url4 = `https://pullfrog.com/console/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}#auto-review-prs`;
+  return `
+
+[Turn off this check \u2192](${url4}) \u2014 it reports run status only and gates nothing unless you required it in branch protection.`;
+}
+var TERMINAL_OUTPUT = {
+  success: {
+    title: "Pullfrog run completed",
+    summary: "The Pullfrog run finished successfully."
+  },
+  failure: {
+    title: "Pullfrog run failed",
+    summary: "The Pullfrog run failed. See the run logs for details."
+  },
+  cancelled: {
+    title: "Pullfrog run cancelled",
+    summary: "The Pullfrog run was cancelled before it finished."
+  },
+  timed_out: {
+    title: "Pullfrog run timed out",
+    summary: "The Pullfrog run exceeded its timeout. See the run logs for details."
+  },
+  action_required: {
+    title: "Pullfrog run needs attention",
+    summary: "The Pullfrog run stopped and needs attention. See the run logs for details."
+  },
+  neutral: {
+    title: "Pullfrog run finished",
+    summary: "The Pullfrog run finished without a pass or fail outcome."
+  },
+  skipped: {
+    title: "Pullfrog run skipped",
+    summary: "This run was superseded by another Pullfrog run."
+  },
+  stale: {
+    title: "Pullfrog run didn't finish",
+    summary: "Pullfrog never received a completion signal for this run. See the run logs for details."
+  }
+};
+function terminalOutput(params) {
+  const base = TERMINAL_OUTPUT[params.conclusion];
+  const review = params.reviewUrl ? `
+
+[View the review Pullfrog posted \u2192](${params.reviewUrl})` : "";
+  const disable = params.conclusion === "success" ? "" : disableCheckLine(params.owner, params.repo);
+  return { title: base.title, summary: base.summary + review + disable };
+}
+async function finalizeRunStatusCheck(params) {
+  const updateParams = {
+    owner: params.owner,
+    repo: params.repo,
+    check_run_id: params.checkRunId,
+    status: "completed",
+    conclusion: params.conclusion,
+    output: terminalOutput({
+      conclusion: params.conclusion,
+      owner: params.owner,
+      repo: params.repo,
+      reviewUrl: params.reviewUrl
+    })
+  };
+  if (params.detailsUrl) updateParams.details_url = params.detailsUrl;
+  await params.octokit.rest.checks.update(updateParams);
+}
+async function createTerminalRunStatusCheck(params) {
   const createParams = {
-    owner: ctx.repo.owner,
-    repo: ctx.repo.name,
-    name: params.name,
+    owner: params.owner,
+    repo: params.repo,
+    name: RUN_STATUS_CHECK_NAME,
     head_sha: params.headSha,
     status: "completed",
     conclusion: params.conclusion,
-    output: { title: params.title, summary: params.summary }
+    output: terminalOutput({
+      conclusion: params.conclusion,
+      owner: params.owner,
+      repo: params.repo,
+      reviewUrl: params.reviewUrl
+    })
   };
-  if (ctx.runId) {
-    createParams.details_url = `https://github.com/${ctx.repo.owner}/${ctx.repo.name}/actions/runs/${ctx.runId}`;
-  }
-  await ctx.octokit.rest.checks.create(createParams);
-  log.info(`\xBB posted ${params.name} check (${params.conclusion}) on ${params.headSha.slice(0, 7)}`);
+  if (params.detailsUrl) createParams.details_url = params.detailsUrl;
+  await params.octokit.rest.checks.create(createParams);
 }
+
+// utils/statusChecks.ts
 async function reportStatusChecks(ctx, params) {
-  if (!ctx.payload.statusChecks) return;
   const event = ctx.payload.event;
   const pullNumber = event.issue_number;
   if (event.is_pr !== true || typeof pullNumber !== "number") return;
+  const checkRunId = parseCheckRunId(ctx.payload.checkRun);
+  if (checkRunId === void 0 && !ctx.payload.runStatusCheck && !ctx.payload.approvalCheck) return;
+  const conclusion = params.runSucceeded ? "success" : "failure";
+  const detailsUrl = ctx.runId ? `https://github.com/${ctx.repo.owner}/${ctx.repo.name}/actions/runs/${ctx.runId}` : void 0;
+  if (checkRunId !== void 0) {
+    await finalizeRunStatusCheck({
+      octokit: ctx.octokit,
+      owner: ctx.repo.owner,
+      repo: ctx.repo.name,
+      checkRunId,
+      conclusion,
+      detailsUrl,
+      reviewUrl: ctx.toolState.approval?.url
+    }).then(() => log.info(`\xBB finalized ${RUN_STATUS_CHECK_NAME} check (${conclusion})`)).catch((err) => log.debug(`status checks: ${RUN_STATUS_CHECK_NAME} finalize failed: ${err}`));
+  }
+  const approval = ctx.toolState.approval;
+  const needsApprovalCheck = ctx.payload.approvalCheck && params.runSucceeded && approval;
+  const needsFallbackRunCheck = ctx.payload.runStatusCheck && checkRunId === void 0;
+  if (!needsApprovalCheck && !needsFallbackRunCheck) return;
   let headSha;
   try {
     const pr = await ctx.octokit.rest.pulls.get({
@@ -167520,24 +167634,32 @@ async function reportStatusChecks(ctx, params) {
     log.debug(`status checks: failed to resolve PR #${pullNumber} head sha: ${err}`);
     return;
   }
-  const completionSha = primaryRepoState(ctx.toolState).checkoutSha ?? headSha;
-  await createCheckRun(ctx, {
-    name: COMPLETION_CHECK,
-    headSha: completionSha,
-    conclusion: params.runSucceeded ? "success" : "failure",
-    title: params.runSucceeded ? "Pullfrog run completed" : "Pullfrog run failed",
-    summary: params.runSucceeded ? "The Pullfrog run finished successfully." : "The Pullfrog run failed or timed out. See the run logs for details."
-  }).catch((err) => log.debug(`status checks: ${COMPLETION_CHECK} post failed: ${err}`));
-  const approval = ctx.toolState.approval;
-  if (params.runSucceeded && approval) {
-    await createCheckRun(ctx, {
-      name: APPROVAL_CHECK,
-      headSha: approval.sha ?? headSha,
-      conclusion: approval.wouldApprove ? "success" : "failure",
+  if (needsFallbackRunCheck) {
+    await createTerminalRunStatusCheck({
+      octokit: ctx.octokit,
+      owner: ctx.repo.owner,
+      repo: ctx.repo.name,
+      headSha: primaryRepoState(ctx.toolState).checkoutSha ?? headSha,
+      conclusion,
+      detailsUrl,
+      reviewUrl: ctx.toolState.approval?.url
+    }).then(() => log.info(`\xBB posted ${RUN_STATUS_CHECK_NAME} check (${conclusion})`)).catch((err) => log.debug(`status checks: ${RUN_STATUS_CHECK_NAME} post failed: ${err}`));
+  }
+  if (!needsApprovalCheck || !approval) return;
+  const createParams = {
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    name: APPROVAL_CHECK_NAME,
+    head_sha: approval.sha ?? headSha,
+    status: "completed",
+    conclusion: approval.wouldApprove ? "success" : "failure",
+    output: {
       title: approval.wouldApprove ? "Pullfrog would approve" : "Pullfrog would not approve",
       summary: approval.wouldApprove ? "Pullfrog has no outstanding review feedback on this PR." : "Pullfrog has outstanding review feedback or requested changes on this PR."
-    }).catch((err) => log.debug(`status checks: ${APPROVAL_CHECK} post failed: ${err}`));
-  }
+    }
+  };
+  if (detailsUrl) createParams.details_url = detailsUrl;
+  await ctx.octokit.rest.checks.create(createParams).then(() => log.info(`\xBB posted ${APPROVAL_CHECK_NAME} check`)).catch((err) => log.debug(`status checks: ${APPROVAL_CHECK_NAME} post failed: ${err}`));
 }
 
 // utils/runLifecycle.ts
@@ -168938,7 +169060,8 @@ async function handleSecret(ctx) {
   }
   if (method === "pullfrog") {
     const scope2 = ctx.secrets.isOrg ? await promptScope2(ctx) : "account";
-    activeSpin2.start(`saving ${envVar}`);
+    const target = describeSecretTarget({ owner: ctx.owner, repo: ctx.repo, scope: scope2 });
+    activeSpin2.start(`saving ${import_picocolors3.default.cyan(envVar)} to ${target}`);
     let saveResult;
     try {
       saveResult = await setPullfrogSecret2({
@@ -168958,7 +169081,7 @@ async function handleSecret(ctx) {
       return;
     }
     if (saveResult.saved) {
-      activeSpin2.stop(`saved ${import_picocolors3.default.cyan(envVar)} to Pullfrog`);
+      activeSpin2.stop(`saved ${import_picocolors3.default.cyan(envVar)} to ${target}`);
     } else {
       activeSpin2.stop(import_picocolors3.default.red("could not save secret"));
       O2.warn(
@@ -169308,7 +169431,7 @@ async function runCli4(input) {
 }
 
 // cli.ts
-var VERSION10 = "0.1.46";
+var VERSION10 = "0.1.47";
 var bin = basename2(process.argv[1] || "");
 var PROG = bin === "pf" || bin === "pullfrog" ? bin : "pullfrog";
 var rawArgs = process.argv.slice(2);

package/dist/external.d.ts

@@ -262,6 +262,14 @@ export interface WriteablePayload {
         id: string;
         type: "issue" | "review";
     } | undefined;
+    /**
+     * pre-created `pullfrog` check-run, seeded `in_progress` by the server at dispatch so
+     * the PR's checks list shows the run before the GHA runner boots. the action PATCHes
+     * it to a terminal conclusion at run end. see `action/utils/runStatusCheck.ts`.
+     */
+    checkRun?: {
+        id: string;
+    } | undefined;
     /** when true, seed the PR summary tmpfile + persist edits at run end */
     generateSummary?: boolean | undefined;
 }

package/dist/index.js

@@ -101121,7 +101121,7 @@ var import_semver = __toESM(require_semver2(), 1);
 // package.json
 var package_default = {
   name: "pullfrog",
-  version: "0.1.46",
+  version: "0.1.47",
   type: "module",
   bin: {
     pullfrog: "dist/cli.mjs",
@@ -158080,6 +158080,9 @@ var JsonPayload = type({
     id: "string",
     type: "'issue' | 'review'"
   }).or("undefined"),
+  // optional so a payload from an older server build (pre-`checkRun`) still parses
+  // against a newer action across a rolling deploy.
+  "checkRun?": type({ id: "string" }).or("undefined"),
   "generateSummary?": "boolean | undefined"
 });
 var COLLABORATOR_PERMISSIONS = ["admin", "maintain", "write"];
@@ -158193,13 +158196,19 @@ function resolvePayload(resolvedPromptInput, repoSettings) {
     timeout: inputs.timeout ?? jsonPayload?.timeout,
     cwd: resolveCwd(inputs.cwd),
     progressComment: jsonPayload?.progressComment,
+    checkRun: jsonPayload?.checkRun,
     generateSummary: jsonPayload?.generateSummary,
     // permissions: inputs > repoSettings > fallbacks
     push: inputs.push ?? repoSettings.push ?? "restricted",
     shell: resolvedShell,
-    // opt-in commit-status check-runs (branch protection). workflow-level
-    // static input, off unless the repo's pullfrog.yml sets status_checks: enabled.
-    statusChecks: inputs.status_checks === "enabled",
+    // the `pullfrog` run-lifecycle check. ON by default — the whole point is that a PR
+    // shows whether Pullfrog is running without anyone having to opt in. the workflow
+    // input is the source of truth when set (mirrors `push`); otherwise the repo
+    // setting decides.
+    runStatusCheck: inputs.status_checks === void 0 ? repoSettings.statusChecks : inputs.status_checks === "enabled",
+    // the `pullfrog-approval` verdict check stays opt-in and workflow-only. it exists to
+    // be *required* by branch protection, so it must never turn itself on.
+    approvalCheck: inputs.status_checks === "enabled",
     // temporary progress chrome. the workflow input is the source of truth when
     // set (mirrors `push`); otherwise the repo setting decides. defaults to true.
     progressComments: inputs.progress_comments === void 0 ? repoSettings.progressComments : inputs.progress_comments === "enabled",
@@ -158727,7 +158736,11 @@ async function approveAfterFix(ctx) {
     approved: true,
     hasComments: false
   });
-  ctx.toolState.approval = { wouldApprove: true, sha: headSha };
+  ctx.toolState.approval = {
+    wouldApprove: true,
+    sha: headSha,
+    url: result.data.html_url
+  };
   log.info(`\xBB auto-approved #${pullNumber} after fix run (review ${result.data.id})`);
   await deleteProgressComment(ctx).catch((err) => {
     log.debug(`progress comment cleanup after fix auto-approval failed: ${err}`);
@@ -159060,6 +159073,7 @@ function CreatePullRequestReviewTool(ctx) {
         }
         const reviewId = result.data.id;
         const reviewNodeId = result.data.node_id;
+        if (ctx.toolState.approval) ctx.toolState.approval.url = result.data.html_url;
         log.info(`\xBB created review ${reviewId} on pull request #${pull_number}`);
         const actuallyReviewedSha = primary.checkoutSha ?? params.commit_id;
         ctx.toolState.review = {
@@ -165076,6 +165090,7 @@ var defaultSettings = {
   autoMergeEnabled: false,
   signedCommits: false,
   progressComments: true,
+  statusChecks: true,
   modeInstructions: {},
   learnings: null,
   learningsHeadings: [],
@@ -165597,30 +165612,123 @@ function getCurrentWorkflowFilename() {
   return match3?.[1] ?? "pullfrog.yml";
 }
 
-// utils/statusChecks.ts
-var COMPLETION_CHECK = "pullfrog";
-var APPROVAL_CHECK = "pullfrog-approval";
-async function createCheckRun(ctx, params) {
+// utils/runStatusCheck.ts
+var RUN_STATUS_CHECK_NAME = "Pullfrog";
+var APPROVAL_CHECK_NAME = "Pullfrog approval";
+function parseCheckRunId(raw2) {
+  if (!raw2?.id) return void 0;
+  const id = parseInt(raw2.id, 10);
+  if (Number.isNaN(id) || id <= 0) return void 0;
+  return id;
+}
+function disableCheckLine(owner, repo) {
+  const url4 = `https://pullfrog.com/console/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}#auto-review-prs`;
+  return `
+
+[Turn off this check \u2192](${url4}) \u2014 it reports run status only and gates nothing unless you required it in branch protection.`;
+}
+var TERMINAL_OUTPUT = {
+  success: {
+    title: "Pullfrog run completed",
+    summary: "The Pullfrog run finished successfully."
+  },
+  failure: {
+    title: "Pullfrog run failed",
+    summary: "The Pullfrog run failed. See the run logs for details."
+  },
+  cancelled: {
+    title: "Pullfrog run cancelled",
+    summary: "The Pullfrog run was cancelled before it finished."
+  },
+  timed_out: {
+    title: "Pullfrog run timed out",
+    summary: "The Pullfrog run exceeded its timeout. See the run logs for details."
+  },
+  action_required: {
+    title: "Pullfrog run needs attention",
+    summary: "The Pullfrog run stopped and needs attention. See the run logs for details."
+  },
+  neutral: {
+    title: "Pullfrog run finished",
+    summary: "The Pullfrog run finished without a pass or fail outcome."
+  },
+  skipped: {
+    title: "Pullfrog run skipped",
+    summary: "This run was superseded by another Pullfrog run."
+  },
+  stale: {
+    title: "Pullfrog run didn't finish",
+    summary: "Pullfrog never received a completion signal for this run. See the run logs for details."
+  }
+};
+function terminalOutput(params) {
+  const base = TERMINAL_OUTPUT[params.conclusion];
+  const review = params.reviewUrl ? `
+
+[View the review Pullfrog posted \u2192](${params.reviewUrl})` : "";
+  const disable = params.conclusion === "success" ? "" : disableCheckLine(params.owner, params.repo);
+  return { title: base.title, summary: base.summary + review + disable };
+}
+async function finalizeRunStatusCheck(params) {
+  const updateParams = {
+    owner: params.owner,
+    repo: params.repo,
+    check_run_id: params.checkRunId,
+    status: "completed",
+    conclusion: params.conclusion,
+    output: terminalOutput({
+      conclusion: params.conclusion,
+      owner: params.owner,
+      repo: params.repo,
+      reviewUrl: params.reviewUrl
+    })
+  };
+  if (params.detailsUrl) updateParams.details_url = params.detailsUrl;
+  await params.octokit.rest.checks.update(updateParams);
+}
+async function createTerminalRunStatusCheck(params) {
   const createParams = {
-    owner: ctx.repo.owner,
-    repo: ctx.repo.name,
-    name: params.name,
+    owner: params.owner,
+    repo: params.repo,
+    name: RUN_STATUS_CHECK_NAME,
     head_sha: params.headSha,
     status: "completed",
     conclusion: params.conclusion,
-    output: { title: params.title, summary: params.summary }
+    output: terminalOutput({
+      conclusion: params.conclusion,
+      owner: params.owner,
+      repo: params.repo,
+      reviewUrl: params.reviewUrl
+    })
   };
-  if (ctx.runId) {
-    createParams.details_url = `https://github.com/${ctx.repo.owner}/${ctx.repo.name}/actions/runs/${ctx.runId}`;
-  }
-  await ctx.octokit.rest.checks.create(createParams);
-  log.info(`\xBB posted ${params.name} check (${params.conclusion}) on ${params.headSha.slice(0, 7)}`);
+  if (params.detailsUrl) createParams.details_url = params.detailsUrl;
+  await params.octokit.rest.checks.create(createParams);
 }
+
+// utils/statusChecks.ts
 async function reportStatusChecks(ctx, params) {
-  if (!ctx.payload.statusChecks) return;
   const event = ctx.payload.event;
   const pullNumber = event.issue_number;
   if (event.is_pr !== true || typeof pullNumber !== "number") return;
+  const checkRunId = parseCheckRunId(ctx.payload.checkRun);
+  if (checkRunId === void 0 && !ctx.payload.runStatusCheck && !ctx.payload.approvalCheck) return;
+  const conclusion = params.runSucceeded ? "success" : "failure";
+  const detailsUrl = ctx.runId ? `https://github.com/${ctx.repo.owner}/${ctx.repo.name}/actions/runs/${ctx.runId}` : void 0;
+  if (checkRunId !== void 0) {
+    await finalizeRunStatusCheck({
+      octokit: ctx.octokit,
+      owner: ctx.repo.owner,
+      repo: ctx.repo.name,
+      checkRunId,
+      conclusion,
+      detailsUrl,
+      reviewUrl: ctx.toolState.approval?.url
+    }).then(() => log.info(`\xBB finalized ${RUN_STATUS_CHECK_NAME} check (${conclusion})`)).catch((err) => log.debug(`status checks: ${RUN_STATUS_CHECK_NAME} finalize failed: ${err}`));
+  }
+  const approval = ctx.toolState.approval;
+  const needsApprovalCheck = ctx.payload.approvalCheck && params.runSucceeded && approval;
+  const needsFallbackRunCheck = ctx.payload.runStatusCheck && checkRunId === void 0;
+  if (!needsApprovalCheck && !needsFallbackRunCheck) return;
   let headSha;
   try {
     const pr = await ctx.octokit.rest.pulls.get({
@@ -165633,24 +165741,32 @@ async function reportStatusChecks(ctx, params) {
     log.debug(`status checks: failed to resolve PR #${pullNumber} head sha: ${err}`);
     return;
   }
-  const completionSha = primaryRepoState(ctx.toolState).checkoutSha ?? headSha;
-  await createCheckRun(ctx, {
-    name: COMPLETION_CHECK,
-    headSha: completionSha,
-    conclusion: params.runSucceeded ? "success" : "failure",
-    title: params.runSucceeded ? "Pullfrog run completed" : "Pullfrog run failed",
-    summary: params.runSucceeded ? "The Pullfrog run finished successfully." : "The Pullfrog run failed or timed out. See the run logs for details."
-  }).catch((err) => log.debug(`status checks: ${COMPLETION_CHECK} post failed: ${err}`));
-  const approval = ctx.toolState.approval;
-  if (params.runSucceeded && approval) {
-    await createCheckRun(ctx, {
-      name: APPROVAL_CHECK,
-      headSha: approval.sha ?? headSha,
-      conclusion: approval.wouldApprove ? "success" : "failure",
+  if (needsFallbackRunCheck) {
+    await createTerminalRunStatusCheck({
+      octokit: ctx.octokit,
+      owner: ctx.repo.owner,
+      repo: ctx.repo.name,
+      headSha: primaryRepoState(ctx.toolState).checkoutSha ?? headSha,
+      conclusion,
+      detailsUrl,
+      reviewUrl: ctx.toolState.approval?.url
+    }).then(() => log.info(`\xBB posted ${RUN_STATUS_CHECK_NAME} check (${conclusion})`)).catch((err) => log.debug(`status checks: ${RUN_STATUS_CHECK_NAME} post failed: ${err}`));
+  }
+  if (!needsApprovalCheck || !approval) return;
+  const createParams = {
+    owner: ctx.repo.owner,
+    repo: ctx.repo.name,
+    name: APPROVAL_CHECK_NAME,
+    head_sha: approval.sha ?? headSha,
+    status: "completed",
+    conclusion: approval.wouldApprove ? "success" : "failure",
+    output: {
       title: approval.wouldApprove ? "Pullfrog would approve" : "Pullfrog would not approve",
       summary: approval.wouldApprove ? "Pullfrog has no outstanding review feedback on this PR." : "Pullfrog has outstanding review feedback or requested changes on this PR."
-    }).catch((err) => log.debug(`status checks: ${APPROVAL_CHECK} post failed: ${err}`));
-  }
+    }
+  };
+  if (detailsUrl) createParams.details_url = detailsUrl;
+  await ctx.octokit.rest.checks.create(createParams).then(() => log.info(`\xBB posted ${APPROVAL_CHECK_NAME} check`)).catch((err) => log.debug(`status checks: ${APPROVAL_CHECK_NAME} post failed: ${err}`));
 }
 
 // utils/runLifecycle.ts

package/dist/internal/index.d.ts

@@ -15,4 +15,6 @@ export { isLeapingIntoActionCommentBody, LEAPING_INTO_ACTION_PREFIX, } from "../
 export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "../utils/learningsTruncate.ts";
 export type { CreateProgressCommentTarget, ProgressComment, ProgressCommentType, } from "../utils/progressComment.ts";
 export { createLeapingProgressComment, deleteProgressCommentApi, getProgressComment, updateProgressComment, } from "../utils/progressComment.ts";
+export type { RunStatusCheckConclusion, RunStatusCheckOctokit, } from "../utils/runStatusCheck.ts";
+export { APPROVAL_CHECK_NAME, createRunStatusCheck, finalizeRunStatusCheck, RUN_STATUS_CHECK_NAME, runStatusCheckNeedsFinalizing, } from "../utils/runStatusCheck.ts";
 export { isValidTimeString, parseTimeString, TIMEOUT_DISABLED, } from "../utils/time.ts";

package/dist/internal.js

@@ -1329,6 +1329,113 @@ async function createLeapingProgressComment(ctx, target, body) {
   };
 }
 
+// utils/runStatusCheck.ts
+var RUN_STATUS_CHECK_NAME = "Pullfrog";
+var APPROVAL_CHECK_NAME = "Pullfrog approval";
+var IN_PROGRESS_OUTPUT = {
+  title: "Pullfrog is running",
+  summary: "Pullfrog is working on this pull request. This check updates when the run finishes."
+};
+function disableCheckLine(owner, repo) {
+  const url = `https://pullfrog.com/console/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}#auto-review-prs`;
+  return `
+
+[Turn off this check \u2192](${url}) \u2014 it reports run status only and gates nothing unless you required it in branch protection.`;
+}
+var TERMINAL_OUTPUT = {
+  success: {
+    title: "Pullfrog run completed",
+    summary: "The Pullfrog run finished successfully."
+  },
+  failure: {
+    title: "Pullfrog run failed",
+    summary: "The Pullfrog run failed. See the run logs for details."
+  },
+  cancelled: {
+    title: "Pullfrog run cancelled",
+    summary: "The Pullfrog run was cancelled before it finished."
+  },
+  timed_out: {
+    title: "Pullfrog run timed out",
+    summary: "The Pullfrog run exceeded its timeout. See the run logs for details."
+  },
+  action_required: {
+    title: "Pullfrog run needs attention",
+    summary: "The Pullfrog run stopped and needs attention. See the run logs for details."
+  },
+  neutral: {
+    title: "Pullfrog run finished",
+    summary: "The Pullfrog run finished without a pass or fail outcome."
+  },
+  skipped: {
+    title: "Pullfrog run skipped",
+    summary: "This run was superseded by another Pullfrog run."
+  },
+  stale: {
+    title: "Pullfrog run didn't finish",
+    summary: "Pullfrog never received a completion signal for this run. See the run logs for details."
+  }
+};
+function terminalOutput(params) {
+  const base = TERMINAL_OUTPUT[params.conclusion];
+  const review = params.reviewUrl ? `
+
+[View the review Pullfrog posted \u2192](${params.reviewUrl})` : "";
+  const disable = params.conclusion === "success" ? "" : disableCheckLine(params.owner, params.repo);
+  return { title: base.title, summary: base.summary + review + disable };
+}
+async function createRunStatusCheck(params) {
+  const existing = await params.octokit.rest.checks.listForRef({
+    owner: params.owner,
+    repo: params.repo,
+    ref: params.headSha,
+    check_name: RUN_STATUS_CHECK_NAME,
+    status: "in_progress"
+  }).catch(() => void 0);
+  const reusable = existing?.data.check_runs[0];
+  if (reusable) return reusable.id;
+  const createParams = {
+    owner: params.owner,
+    repo: params.repo,
+    name: RUN_STATUS_CHECK_NAME,
+    head_sha: params.headSha,
+    status: "in_progress",
+    output: IN_PROGRESS_OUTPUT
+  };
+  if (params.detailsUrl) createParams.details_url = params.detailsUrl;
+  const created = await params.octokit.rest.checks.create(createParams);
+  return created.data.id;
+}
+async function finalizeRunStatusCheck(params) {
+  const updateParams = {
+    owner: params.owner,
+    repo: params.repo,
+    check_run_id: params.checkRunId,
+    status: "completed",
+    conclusion: params.conclusion,
+    output: terminalOutput({
+      conclusion: params.conclusion,
+      owner: params.owner,
+      repo: params.repo,
+      reviewUrl: params.reviewUrl
+    })
+  };
+  if (params.detailsUrl) updateParams.details_url = params.detailsUrl;
+  await params.octokit.rest.checks.update(updateParams);
+}
+async function runStatusCheckNeedsFinalizing(params) {
+  try {
+    const existing = await params.octokit.rest.checks.get({
+      owner: params.owner,
+      repo: params.repo,
+      check_run_id: params.checkRunId
+    });
+    return existing.data.status !== "completed";
+  } catch {
+    return false;
+  }
+}
+
 // utils/time.ts
 var TIMEOUT_DISABLED = "none";
 var TIME_STRING_REGEX = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/;
@@ -1344,6 +1451,7 @@ function isValidTimeString(input) {
   return parseTimeString(input) !== null;
 }
 export {
+  APPROVAL_CHECK_NAME,
   AUTO_EFFICIENT,
   AUTO_INTELLIGENT,
   DEFAULT_PROXY_MODEL,
@@ -1351,12 +1459,15 @@ export {
   MAX_LEARNINGS_LENGTH,
   OAuthInvalidGrantError,
   PULLFROG_DIVIDER,
+  RUN_STATUS_CHECK_NAME,
   TIMEOUT_DISABLED,
   buildPullfrogFooter,
   createLeapingProgressComment,
+  createRunStatusCheck,
   decodeJwtExpMs,
   defaultAutoTier,
   deleteProgressCommentApi,
+  finalizeRunStatusCheck,
   getAutoSelectHintModel,
   getModelEnvVars,
   getModelManagedCredentials,
@@ -1380,6 +1491,7 @@ export {
   resolveDisplayAlias,
   resolveModelSlug,
   resolveOpenRouterModel,
+  runStatusCheckNeedsFinalizing,
   stringifyCodexAuthBody,
   stripExistingFooter,
   truncateAtLineBoundary,

package/dist/toolState.d.ts

@@ -104,6 +104,7 @@ export interface ToolState {
     approval?: {
         wouldApprove: boolean;
         sha: string | undefined;
+        url?: string | undefined;
     };
     reviewReplies?: Map<number, {
         commentId: number;

package/dist/utils/payload.d.ts

@@ -22,6 +22,9 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
         id: string;
         type: "issue" | "review";
     } | undefined;
+    checkRun?: {
+        id: string;
+    } | undefined;
     generateSummary?: boolean | undefined;
 }, {}>;
 export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
@@ -68,10 +71,14 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
         id: string;
         type: "issue" | "review";
     } | undefined;
+    checkRun: {
+        id: string;
+    } | undefined;
     generateSummary: boolean | undefined;
     push: import("../external.ts").PushPermission;
     shell: import("../external.ts").ShellPermission;
-    statusChecks: boolean;
+    runStatusCheck: boolean;
+    approvalCheck: boolean;
     progressComments: boolean;
     proxyModel: string | undefined;
 };

package/dist/utils/runContext.d.ts

@@ -34,6 +34,7 @@ export interface RepoSettings {
     autoMergeEnabled: boolean;
     signedCommits: boolean;
     progressComments: boolean;
+    statusChecks: boolean;
     modeInstructions: Record<string, string>;
     learnings: string | null;
     learningsHeadings: LearningsHeading[];

package/dist/utils/runStatusCheck.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Single source of truth for the `pullfrog` commit-status check-run — the row a PR's
+ * checks list shows while a run is in flight and after it ends.
+ *
+ * Pullfrog dispatches its workflow with `ref: <default branch>`, so the GitHub Actions
+ * run attaches its check suite to the default branch head and never to the PR head.
+ * Nothing about a run is therefore visible from the PR itself unless we post this
+ * check-run against the PR head sha ourselves.
+ *
+ * Created `in_progress` by the server at dispatch — before the runner boots, and
+ * upstream of every action-side failure that would otherwise leave the PR silent
+ * (billing 402, token resolution, bad model slug, missing provider key). Moved to a
+ * terminal conclusion by whichever of three actors reaches it first, all calling
+ * `finalizeRunStatusCheck`:
+ *
+ *   1. the action at run end (`reportStatusChecks`)
+ *   2. the `workflow_run.completed` webhook (covers cancel / SIGKILL / early throw)
+ *   3. the hourly stuck-run reaper (covers a dropped webhook)
+ *
+ * That three-layer close-out is what makes an `in_progress` check safe here: a check
+ * stranded `in_progress` on a required branch-protection rule would block merges
+ * forever, which is why this file did not exist before.
+ */
+/**
+ * the run-lifecycle check. verdict-agnostic — it reports that a run happened, not what it
+ * found. this string IS the branch-protection identifier, so changing it silently breaks
+ * any repo that required the old name.
+ */
+export declare const RUN_STATUS_CHECK_NAME = "Pullfrog";
+/** the review-verdict check. opt-in, terminal-only, and deliberately separate from the above. */
+export declare const APPROVAL_CHECK_NAME = "Pullfrog approval";
+/**
+ * The terminal states we report. Exactly GitHub's check-run `conclusion` enum, which
+ * happens to be `WorkflowRunStatus` minus `running` — so the server can map a finished
+ * run's status straight across (`checkConclusionFromStatus` in utils/workflowRunStatus.ts).
+ */
+export type RunStatusCheckConclusion = "success" | "failure" | "cancelled" | "timed_out" | "action_required" | "neutral" | "skipped" | "stale";
+/**
+ * Parse the on-the-wire `{ id: string }` shape (the form carried in `JsonPayload`) into
+ * a check-run id. Mirrors `parseProgressComment` — returns undefined when the id isn't a
+ * positive integer so callers can short-circuit cleanly.
+ */
+export declare function parseCheckRunId(raw: {
+    id: string;
+} | null | undefined): number | undefined;
+interface CheckRunResponse {
+    data: {
+        id: number;
+    };
+}
+type CheckRunStatus = "queued" | "in_progress" | "completed";
+type CheckRunOutput = {
+    title: string;
+    summary: string;
+};
+type CreateCheckRunParams = {
+    owner: string;
+    repo: string;
+    name: string;
+    head_sha: string;
+    status?: CheckRunStatus;
+    conclusion?: RunStatusCheckConclusion;
+    details_url?: string;
+    output?: CheckRunOutput;
+};
+type UpdateCheckRunParams = {
+    owner: string;
+    repo: string;
+    check_run_id: number;
+    status?: CheckRunStatus;
+    conclusion?: RunStatusCheckConclusion;
+    details_url?: string;
+    output?: CheckRunOutput;
+};
+export interface RunStatusCheckOctokit {
+    rest: {
+        checks: {
+            create: (params: CreateCheckRunParams) => Promise<CheckRunResponse>;
+            update: (params: UpdateCheckRunParams) => Promise<CheckRunResponse>;
+            get: (params: {
+                owner: string;
+                repo: string;
+                check_run_id: number;
+            }) => Promise<{
+                data: {
+                    status: string;
+                };
+            }>;
+            listForRef: (params: {
+                owner: string;
+                repo: string;
+                ref: string;
+                check_name?: string;
+                status?: "queued" | "in_progress" | "completed";
+            }) => Promise<{
+                data: {
+                    check_runs: {
+                        id: number;
+                    }[];
+                };
+            }>;
+        };
+    };
+}
+/**
+ * Post the `in_progress` check-run on `headSha` and return its id for the finalizers.
+ *
+ * Best-effort: a transient 5xx, a repo that revoked `checks: write`, or a PR whose head
+ * has already been deleted must never stop a run from dispatching. Returns undefined on
+ * failure, which every caller treats as "no check to finalize".
+ */
+export declare function createRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    headSha: string;
+    detailsUrl: string | undefined;
+}): Promise<number | undefined>;
+/**
+ * Move an existing check-run to its terminal conclusion.
+ *
+ * A PATCH, not a second create: `POST /check-runs` with the same name + sha creates a
+ * SECOND row rather than replacing the first, so creating twice would show the PR two
+ * contradictory `pullfrog` rows. (That is a real bug today — `finalizeSuccessRun` posts
+ * success and a later throw posts failure, both as fresh rows.)
+ */
+export declare function finalizeRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    checkRunId: number;
+    conclusion: RunStatusCheckConclusion;
+    detailsUrl: string | undefined;
+    reviewUrl?: string | undefined;
+}): Promise<void>;
+/**
+ * Post an already-terminal check-run in one call.
+ *
+ * The fallback for runs that never got a server-created check to update: a rolling
+ * deploy where the dispatch payload predates `checkRun`, or a workflow invoked outside
+ * Pullfrog's own dispatch path (`prompt_file`, a hand-written step).
+ */
+export declare function createTerminalRunStatusCheck(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    headSha: string;
+    conclusion: RunStatusCheckConclusion;
+    detailsUrl: string | undefined;
+    reviewUrl?: string | undefined;
+}): Promise<void>;
+/**
+ * Whether this check still needs finalizing.
+ *
+ * The server-side close-outs are BACKSTOPS: they exist for runs the action could not
+ * finalize itself. Firing them unconditionally is actively harmful, because the action
+ * writes a richer summary than they can — it knows the review URL, they do not — so a
+ * blind re-PATCH silently strips that link seconds after it appears. It also resets
+ * `completed_at`, discarding the duration GitHub renders as "Successful in 2m".
+ *
+ * Returns false when GitHub cannot be reached: a backstop that cannot confirm the check
+ * is unfinished must not overwrite a good one.
+ */
+export declare function runStatusCheckNeedsFinalizing(params: {
+    octokit: RunStatusCheckOctokit;
+    owner: string;
+    repo: string;
+    checkRunId: number;
+}): Promise<boolean>;
+export {};

package/dist/utils/statusChecks.d.ts

@@ -1,24 +1,21 @@
 import type { ToolContext } from "../mcp/server.ts";
 /**
- * post the opt-in `pullfrog` (run completion) and `pullfrog-approval` (review
- * verdict) commit-status check-runs so they can be required by branch
- * protection. no-op unless the `status_checks` input is enabled and the run is
- * on a pull request.
+ * post the `Pullfrog` (run lifecycle) and `Pullfrog approval` (review verdict)
+ * commit-status check-runs.
  *
- * terminal-only by design: we never create an `in_progress` check. a
- * hard-cancelled run (SIGKILL) would strand a required check `in_progress` and
- * block merges forever; an absent required check already blocks merge the same
- * way while the run is in flight, with no stuck-check failure mode.
+ *   - `Pullfrog` is on by default (`Repo.statusChecks`). the server already created it
+ *     `in_progress` at dispatch, so the work here is a PATCH to its terminal conclusion —
+ *     see `runStatusCheck.ts` for why a second create would leave two contradictory rows.
+ *     the terminal-create fallback covers a payload with no `checkRun` (older server
+ *     build mid-rolling-deploy, or a workflow driven outside Pullfrog's dispatch path).
+ *   - `Pullfrog approval` stays opt-in (`status_checks: enabled`) and terminal-only:
+ *     it asserts a review verdict, which only exists once a run produces one. anchored
+ *     to the exact reviewed sha so a mid-run push leaves the new head unapproved until
+ *     a follow-up re-review reports.
  *
- *   - `pullfrog` is posted on every PR run: success iff the run finished
- *     successfully, failure on error/timeout. review-verdict-agnostic.
- *   - `pullfrog-approval` is posted only when this run produced an approval
- *     verdict (`toolState.approval`, set by create_pull_request_review),
- *     anchored to the reviewed sha so a mid-run push leaves the new head
- *     unapproved until the follow-up re-review reports.
- *
- * best-effort throughout: a check-post failure (fork PR head not in the base
- * repo, transient 5xx, closed PR) must never flip the run's own outcome.
+ * best-effort throughout: a check-post failure (transient 5xx, closed PR, revoked
+ * permission) must never flip the run's own outcome. the `workflow_run.completed` webhook
+ * and both stuck-run reaper sweeps close out a check this function fails to finalize.
  */
 export declare function reportStatusChecks(ctx: ToolContext, params: {
     runSucceeded: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pullfrog",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "type": "module",
   "bin": {
     "pullfrog": "dist/cli.mjs",