claude-dev-env 1.58.0 → 1.60.0

package/skills/autoconverge/workflow/converge.mjs

@@ -15,7 +15,7 @@ export const meta = {
   whenToUse: 'Launched by the /autoconverge skill after it resolves PR scope, enters a worktree, and grants project .claude permissions.',
   phases: [
     { title: 'Converge', detail: 'Bugbot + code-review + bug-audit in parallel each round; one clean-coder applies all fixes; loop until all three are clean on a stable HEAD' },
-    { title: 'Copilot gate', detail: 'Request Copilot review and poll up to three times; route findings back into Converge' },
+    { title: 'Copilot gate', detail: 'Request Copilot review and poll up to three times; route findings back into Converge; when Copilot is down or out of quota, log a notice and mark the PR ready with the gate bypassed' },
     { title: 'Finalize', detail: 'Run check_convergence.py; mark draft=false on a full pass' },
   ],
 }
@@ -28,6 +28,24 @@ const CONFIG = {
   bugteamRubric: '$HOME/.claude/skills/bugteam/reference/audit-contract.md',
 }
 
+const HEADLESS_SAFETY_PREAMBLE =
+  'HEADLESS RUN — you run unattended: no human can answer a permission or confirmation prompt, and any such prompt stalls the entire convergence run. The destructive_command_blocker hook matches dangerous patterns (rm -rf, git reset --hard, dd, mkfs, chmod -R, fork bombs) as raw text anywhere in a Bash command, with no quote-awareness — so a destructive string stalls you even when it is only data you never execute. Therefore:\n' +
+  '- Never place a destructive-command literal inside a Bash command — not in echo, not in a heredoc, and not as an argument to python -c, node -e, or awk. To exercise or verify destructive_command_blocker (or any hook) behavior, run the committed test suite, e.g. python -m pytest <test_file>, which passes the command strings as in-language data rather than as a shell command.\n' +
+  '- When a commit message, or a PR / issue / review-comment body, must describe destructive-command behavior, write that text to a file and pass it by path (git commit -F <file>, gh ... --body-file <file>); never inline it with git commit -m or gh ... -b, where the literal lands in the Bash command and stalls you.\n' +
+  '- Keep scratch files and cleanup inside the OS temp dir or $CLAUDE_JOB_DIR/tmp (auto-allowed as ephemeral); never target a repository or worktree path with rm -rf.\n' +
+  '- If a step appears to require a real destructive command, use a non-destructive equivalent or report it as a blocker instead of running it.\n\n'
+
+/**
+ * Spawn a workflow agent with the headless-safety preamble prepended to its
+ * prompt. Every agent in this convergence loop runs unattended, so each one is
+ * routed through here to inherit the same no-confirmation-prompt guidance.
+ * @param {string} prompt the agent's role-specific instruction body
+ * @param {object} options the agent() options (label, phase, schema, agentType, model)
+ * @returns {Promise<*>} the agent() result
+ */
+const convergeAgent = (prompt, options) =>
+  agent(`${HEADLESS_SAFETY_PREAMBLE}${prompt}`, options)
+
 const LENS_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -62,10 +80,10 @@ const COPILOT_SCHEMA = {
   properties: {
     sha: { type: 'string' },
     clean: { type: 'boolean' },
+    down: { type: 'boolean', description: 'true when Copilot is down or out of quota — it posts an out-of-usage notice or never surfaces a review on HEAD after the poll cap; the gate is bypassed and the run proceeds to mark-ready' },
     findings: LENS_SCHEMA.properties.findings,
-    blocker: { type: ['string', 'null'], description: 'non-null when Copilot never surfaced a review after the poll cap' },
   },
-  required: ['sha', 'clean', 'findings', 'blocker'],
+  required: ['sha', 'clean', 'down', 'findings'],
 }
 
 const HEAD_SCHEMA = {
@@ -87,6 +105,31 @@ const FIX_SCHEMA = {
   required: ['newSha', 'pushed', 'resolvedWithoutCommit', 'summary'],
 }
 
+const CONVERGENCE_SUMMARY_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    verdictLine: { type: 'string', description: 'one factual BLUF sentence: converged?, distinct issue-class count, all fixed or deferred. No hedging words.' },
+    issueClasses: {
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          plainName: { type: 'string', description: 'everyday-language name of the issue class — no tool tokens, rule ids, file paths, line numbers, severity codes (P0/P1/P2), or bot names' },
+          count: { type: 'integer', description: 'number of raw findings grouped into this class' },
+          severity: { type: 'string', enum: ['P0', 'P1', 'P2'], description: 'most severe among the class' },
+          category: { type: 'string', enum: ['bug', 'code-standard'] },
+          status: { type: 'string', enum: ['fixed', 'deferred'] },
+          whatItWas: { type: 'string', description: 'at most 2 sentences, plain language, what the problem was' },
+        },
+        required: ['plainName', 'count', 'severity', 'category', 'status', 'whatItWas'],
+      },
+    },
+  },
+  required: ['verdictLine', 'issueClasses'],
+}
+
 const CONVERGENCE_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -106,6 +149,17 @@ const READY_SCHEMA = {
   required: ['ready'],
 }
 
+const CLEAN_AUDIT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    posted: { type: 'boolean', description: 'true only when post_audit_thread.py printed the review URL confirming the CLEAN bugteam review landed on HEAD' },
+    reviewUrl: { type: 'string', description: 'the posted review URL when posted is true, otherwise an empty string' },
+    reason: { type: 'string', description: 'when posted is false, the one-line reason the post did not land (a permission denial, a classifier block, or a script error)' },
+  },
+  required: ['posted', 'reviewUrl', 'reason'],
+}
+
 const SEVERITY_RANK = { P0: 0, P1: 1, P2: 2 }
 const SHA_COMPARISON_PREFIX_LENGTH = 7
 
@@ -324,22 +378,44 @@ function classifyReadyOutcome(readyResult) {
  * Classify a Copilot gate result into the loop's next action. A dead gate agent
  * (null result) is a retry rather than an approval, mirroring the converge
  * lenses' dead-agent convention so a failed gate is never mistaken for a clean
- * Copilot review. A non-null blocker ends the run; findings route to a fix step.
- * The gate approves only when it explicitly reports clean:true with no findings —
- * a clean:false result with zero findings is an unreliable or malformed gate
- * response and retries rather than advancing to Finalize, so a PR never goes
- * ready on a HEAD Copilot did not call clean.
+ * Copilot review. A down result — Copilot out of quota or unreachable, so it
+ * posts an out-of-usage notice or never surfaces a review after the poll cap —
+ * routes to the 'down' kind, which logs a notice and proceeds to mark-ready with
+ * the Copilot gate bypassed, the same way a down Bugbot lens is bypassed; this is
+ * checked first so an outage proceeds rather than waiting on a review that will
+ * not arrive. Findings route to a fix step. The gate otherwise approves only when
+ * it explicitly reports clean:true with no findings — a clean:false result with
+ * zero findings is an unreliable or malformed gate response and retries rather
+ * than advancing to Finalize, so a PR never goes ready on a HEAD Copilot did not
+ * call clean.
  * @param {object|null|undefined} copilot the Copilot gate result, or null on agent failure
- * @returns {{kind: string, blocker?: string, findings?: Array<object>}} the next action
+ * @returns {{kind: string, findings?: Array<object>}} the next action
  */
 function classifyCopilotOutcome(copilot) {
   if (copilot == null) return { kind: 'retry' }
-  if (copilot.blocker) return { kind: 'blocker', blocker: copilot.blocker }
+  if (copilot.down === true) return { kind: 'down' }
   if (copilot.findings.length > 0) return { kind: 'fix', findings: copilot.findings }
   if (copilot.clean === true) return { kind: 'approved' }
   return { kind: 'retry' }
 }
 
+/**
+ * Decide whether the Copilot review gate is bypassed for this COPILOT pass from
+ * the gate outcome, mirroring resolveBugbotDown so the flag is recomputed every
+ * pass rather than left sticky. Only a 'down' outcome (Copilot out of quota or
+ * unreachable after the poll cap) bypasses the convergence Copilot gate; an
+ * 'approved', 'fix', or 'retry' outcome means Copilot answered this pass, so the
+ * gate must be evaluated against its review and is never bypassed. Recomputing
+ * from the current outcome is what lets a recovered Copilot — one that returns
+ * standards-only findings after an earlier down pass — reach FINALIZE without
+ * the stale bypass that would skip its non-clean review.
+ * @param {{kind: string}} copilotOutcome a classifyCopilotOutcome result
+ * @returns {boolean} true only when this pass's Copilot gate is bypassed
+ */
+function resolveCopilotDown(copilotOutcome) {
+  return copilotOutcome.kind === 'down'
+}
+
 /**
  * Classify a convergence-check result into the loop's next action. A dead check
  * agent (null/undefined result) is a retry rather than a failure: with no FAIL
@@ -412,7 +488,7 @@ const prCoordinates = `owner=${input.owner} repo=${input.repo} PR #${input.prNum
  * @returns {Promise<string>} the 40-char HEAD SHA
  */
 async function resolveHead() {
-  const head = await agent(
+  const head = await convergeAgent(
     `Print the current HEAD SHA of ${prCoordinates}. Run exactly:\n` +
       `gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .head.sha\n` +
       `Return the full 40-character SHA in the sha field. Do not modify any files.`,
@@ -430,7 +506,7 @@ async function resolveHead() {
  * @returns {Promise<string>} agent transcript (unused)
  */
 function prefetchMainForRound() {
-  return agent(
+  return convergeAgent(
     `Refresh the base ref for ${prCoordinates} so the parallel review lenses can diff against an up-to-date origin/main without each running its own fetch. Run exactly:\n` +
       `git fetch origin main\n` +
       `Do not edit, commit, push, rebase, or modify any files — fetch only.`,
@@ -448,7 +524,7 @@ function runBugbotLens(head) {
   if (input.bugbotDisabled) {
     return Promise.resolve({ sha: head, clean: true, down: true, findings: [] })
   }
-  return agent(
+  return convergeAgent(
     `You are the Cursor Bugbot lens for ${prCoordinates}, HEAD ${head}. Cursor Bugbot participates this run.\n\n` +
       `Goal: return Bugbot's verdict on HEAD ${head}. Do not edit code, commit, or push. You may post the literal trigger comment described below.\n\n` +
       `Procedure (use the existing scripts; each step below shows the exact flags that script accepts):\n` +
@@ -474,7 +550,7 @@ function runBugbotLens(head) {
  * @returns {Promise<object>} LENS_SCHEMA result
  */
 function runCodeReviewLens(head) {
-  return agent(
+  return convergeAgent(
     `You are the code-review lens for ${prCoordinates}, HEAD ${head}.\n\n` +
       `Review the FULL origin/main...HEAD diff — every file the PR touches. Do NOT delta-scope to recent commits or to a single file. The workflow already fetched origin/main this round, so do NOT run git fetch; run git diff --name-only origin/main...HEAD to enumerate the changed files, then review the complete diff of each.\n\n` +
       `Apply correctness-focused review: real bugs, broken logic, incorrect error handling, data-loss or security risks, contract mismatches, and reuse/simplification problems. Report only defensible findings with concrete file:line evidence.\n\n` +
@@ -490,7 +566,7 @@ function runCodeReviewLens(head) {
  * @returns {Promise<object>} LENS_SCHEMA result
  */
 function runAuditLens(head) {
-  return agent(
+  return convergeAgent(
     `You are the second-opinion bug-audit lens for ${prCoordinates}, HEAD ${head}.\n\n` +
       `Read the audit rubric at ${CONFIG.bugteamRubric} and apply its categories (A through P) against the FULL origin/main...HEAD diff — every file the PR touches, never a delta cut. The workflow already fetched origin/main this round, so do NOT run git fetch; run git diff --name-only origin/main...HEAD first to enumerate scope.\n\n` +
       `This is a clean-room audit: assume nothing from other lenses. Report only findings backed by concrete file:line evidence. Do NOT edit, commit, or push.\n\n` +
@@ -520,7 +596,7 @@ function applyFixes(head, findings, sourceLabel) {
   const threadIds = findings
     .flatMap((each) => collectFindingThreadIds(each))
     .filter((each) => typeof each === 'number')
-  return agent(
+  return convergeAgent(
     `You are fixing ${findings.length} finding(s) (${sourceLabel}) on ${prCoordinates}, HEAD ${head}.\n\n` +
       `Findings:\n${findingsBlock}\n\n` +
       `Rules:\n` +
@@ -539,35 +615,65 @@ function applyFixes(head, findings, sourceLabel) {
 
 /**
  * Post the terminal CLEAN bugteam audit artifact so check_convergence.py sees
- * a clean bugteam review on the converged HEAD.
+ * a clean bugteam review on the converged HEAD. The post is load-bearing: the
+ * convergence gate's bugteam-review check can never pass until this review
+ * lands, so the result reports whether the post succeeded rather than
+ * discarding it. A blocked post (a permission or auto-mode-classifier denial)
+ * or a script error returns posted:false with the reason so the caller can
+ * surface a blocker instead of re-converging into the iteration cap.
  * @param {string} head converged PR HEAD SHA
- * @returns {Promise<string>} agent transcript (unused)
+ * @returns {Promise<object>} CLEAN_AUDIT_SCHEMA result
  */
 function postCleanAudit(head) {
-  return agent(
+  return convergeAgent(
     `Post a CLEAN bugteam audit review on ${prCoordinates} at commit ${head}. All review lenses are clean on this HEAD.\n\n` +
       `Write an empty findings file: create a temp file containing exactly [] (an empty JSON array). Then run:\n` +
       `python "${CONFIG.prLoopScripts}/post_audit_thread.py" --skill bugteam --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --commit ${head} --state CLEAN --findings-json <temp-file>\n` +
-      `Run the script with --help first if any flag name differs. This posts the APPROVE review body that check_convergence.py reads for the bugteam gate. Do not edit code, commit, or push.`,
-    { label: 'post-clean-audit', phase: 'Converge', agentType: 'general-purpose' },
+      `Run the script with --help first if any flag name differs. This posts the APPROVE review body that check_convergence.py reads for the bugteam gate. Do not edit code, commit, or push.\n\n` +
+      `Report whether the review landed. When the script prints a review URL, return {posted:true, reviewUrl:<that URL>, reason:""}. When the script is denied (a permission prompt or auto-mode-classifier block), errors, or prints anything other than a review URL, return {posted:false, reviewUrl:"", reason:<the denial message or error as one line>}. Do not retry a denied post.`,
+    { label: 'post-clean-audit', phase: 'Converge', schema: CLEAN_AUDIT_SCHEMA, agentType: 'general-purpose' },
+  )
+}
+
+/**
+ * Blocker message for a CLEAN bugteam audit that did not land. The convergence
+ * gate's bugteam-review check can never pass without this review, so a blocked
+ * post stops the run with an actionable message rather than re-converging until
+ * the iteration cap. Handles a dead post agent (a null result) as not posted.
+ * @param {string} head converged PR HEAD SHA
+ * @param {object} auditResult CLEAN_AUDIT_SCHEMA result from postCleanAudit, or null when the agent died
+ * @returns {string} the blocker message naming the post failure and the unblock path
+ */
+function cleanAuditBlocker(head, auditResult) {
+  const reason = auditResult?.reason || 'the post agent returned no result'
+  return (
+    `clean-audit post blocked: the CLEAN bugteam review could not be posted on HEAD ${head} (${reason}) — ` +
+    `the convergence gate's bugteam-review check can never pass without it, so the run stops rather than re-converge to the iteration cap. ` +
+    `Allow post_audit_thread.py for this run with a Bash permission rule, or post the CLEAN review by hand, then re-run.`
   )
 }
 
 /**
  * Copilot gate: request a Copilot review on HEAD and poll until it lands or the
- * poll cap is hit; return Copilot's findings or a blocker.
+ * poll cap is hit; return Copilot's findings or a down signal. Copilot is down
+ * when it posts an out-of-usage notice (the requester hit their quota) rather
+ * than a review, or surfaces no review at all after the poll cap; the gate
+ * reports either as down so the run logs a notice and proceeds to mark-ready with
+ * the gate bypassed rather than waiting on a review that will not arrive.
  * @param {string} head converged PR HEAD SHA
  * @returns {Promise<object>} COPILOT_SCHEMA result
  */
 function runCopilotGate(head) {
-  return agent(
+  return convergeAgent(
     `You are the Copilot gate for ${prCoordinates}, HEAD ${head}. Do not edit code, commit, or push.\n\n` +
-      `1. Skip a duplicate request: python "${CONFIG.sharedScripts}/check_pending_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --user copilot. Exit 0 means a request is already pending; otherwise request one:\n` +
+      `Copilot can run out of usage. When the newest Copilot review on HEAD carries an out-of-usage notice — a body stating Copilot was unable to review because the user who requested the review has reached their quota limit, or any equivalent quota / premium-request / usage-limit exhaustion message rather than an actual code review — Copilot is down for this run: return {sha:${'`'}${head}${'`'}, clean:true, down:true, findings:[]} and stop. Do NOT re-request a review, do NOT keep polling, and do NOT treat the notice as a finding.\n\n` +
+      `1. Read any existing Copilot review on HEAD first: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber}. This lists every Copilot review across all commits newest-first; only count entries whose commit_id starts with ${head}. If the newest such HEAD-scoped Copilot review is the out-of-usage notice above -> return the down result and stop. A notice on any earlier commit is NOT down: ignore it and continue. With no Copilot review on HEAD, skip a duplicate request: python "${CONFIG.sharedScripts}/check_pending_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} --user copilot. Exit 0 means a request is already pending; otherwise request one:\n` +
       `   gh api --method POST repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/requested_reviewers -f 'reviewers[]=copilot-pull-request-reviewer[bot]'\n` +
       `2. Poll for Copilot's review on HEAD ${head}: up to ${CONFIG.copilotMaxPolls} attempts, 360 seconds apart (delay each attempt with "sleep 360", or the PowerShell alternative "Start-Sleep -Seconds 360"). Each attempt: python "${CONFIG.sharedScripts}/fetch_copilot_reviews.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber} for the top-level review state, plus gh api "repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments" --paginate --slurp for inline comment ids (Copilot's login contains "copilot", case-insensitive). Only count entries whose commit_id starts with ${head}.\n` +
-      `   - Copilot review present and clean/approved on HEAD -> return {sha:${'`'}${head}${'`'}, clean:true, findings:[], blocker:null}.\n` +
-      `   - Copilot findings on HEAD -> return them (each with its inline comment id in replyToCommentId; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise), clean:false, blocker:null.\n` +
-      `   - No review after ${CONFIG.copilotMaxPolls} attempts -> return {sha:${'`'}${head}${'`'}, clean:false, findings:[], blocker:"Copilot did not surface a review on HEAD after ${CONFIG.copilotMaxPolls} polls"}.\n\n` +
+      `   - Out-of-usage notice on HEAD -> return the down result above (clean:true, down:true) and stop.\n` +
+      `   - Copilot review present and clean/approved on HEAD -> return {sha:${'`'}${head}${'`'}, clean:true, down:false, findings:[]}.\n` +
+      `   - Copilot findings on HEAD -> return them (each with its inline comment id in replyToCommentId; category 'code-standard' for pure CODE_RULES/style violations with no behavioral impact, 'bug' otherwise), clean:false, down:false.\n` +
+      `   - No review after ${CONFIG.copilotMaxPolls} attempts -> Copilot is down for this run (unreachable, or silently out of quota with no notice): return {sha:${'`'}${head}${'`'}, clean:false, down:true, findings:[]}.\n\n` +
       `Return strictly the schema.`,
     { label: 'copilot-gate', phase: 'Copilot gate', schema: COPILOT_SCHEMA },
   )
@@ -576,13 +682,15 @@ function runCopilotGate(head) {
 /**
  * Run the authoritative convergence gate.
  * @param {boolean} bugbotDown pass --bugbot-down when Bugbot is opted out or proved unreachable this run
+ * @param {boolean} copilotDown pass --copilot-down when Copilot is down or out of quota this run
  * @returns {Promise<object>} CONVERGENCE_SCHEMA result
  */
-function checkConvergence(bugbotDown) {
+function checkConvergence(bugbotDown, copilotDown) {
   const bugbotDownFlag = bugbotDown ? ' --bugbot-down' : ''
-  return agent(
+  const copilotDownFlag = copilotDown ? ' --copilot-down' : ''
+  return convergeAgent(
     `Run the convergence gate for ${prCoordinates} and report the result. Do not edit code.\n\n` +
-      `Run: python "${CONFIG.sharedScripts}/check_convergence.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber}${bugbotDownFlag}\n\n` +
+      `Run: python "${CONFIG.sharedScripts}/check_convergence.py" --owner ${input.owner} --repo ${input.repo} --pr-number ${input.prNumber}${bugbotDownFlag}${copilotDownFlag}\n\n` +
       `Exit 0 -> every gate passed: return {pass:true, failures:[]}.\n` +
       `Exit 1 -> return {pass:false, failures:[<each printed FAIL line verbatim>]}.\n` +
       `Exit 2 -> retry once; if it still errors, return {pass:false, failures:["check_convergence gh error"]}.`,
@@ -592,12 +700,22 @@ function checkConvergence(bugbotDown) {
 
 /**
  * Mark the PR ready for review (draft=false) and confirm the transition landed.
+ * When Copilot is down this run, the mark-ready agent first opts the
+ * independent mark-ready blocker hook out of the Copilot gate by exporting
+ * the Copilot token into CLAUDE_REVIEWS_DISABLED: that hook re-runs
+ * check_convergence.py without --copilot-down, so the env token is the only
+ * channel a genuine Copilot outage has to pass its Copilot review gate.
  * @param {string} head converged PR HEAD SHA
+ * @param {boolean} copilotDown true when the Copilot gate was bypassed for an outage this run
  * @returns {Promise<object>} READY_SCHEMA result
  */
-function markReady(head) {
-  return agent(
+function markReady(head, copilotDown) {
+  const copilotOptOut = copilotDown
+    ? `0. Copilot is down this run, so opt the independent mark-ready blocker hook out of the Copilot gate before step 1. Export the token in the same shell session as step 1 so the hook's convergence re-check inherits it:\n   bash: export CLAUDE_REVIEWS_DISABLED="copilot"   (PowerShell: $env:CLAUDE_REVIEWS_DISABLED = "copilot")\n`
+    : ''
+  return convergeAgent(
     `All convergence gates pass for ${prCoordinates} on HEAD ${head}. Mark the PR ready, then confirm it left draft state. Do not edit code.\n\n` +
+      copilotOptOut +
       `1. Run: gh pr ready ${input.prNumber} --repo ${input.owner}/${input.repo}\n` +
       `2. Re-query the draft state: gh api repos/${input.owner}/${input.repo}/pulls/${input.prNumber} --jq .draft\n` +
       `Return {ready:true} only when step 2 prints false (the PR is no longer a draft). If step 1 errors or step 2 still prints true, return {ready:false}.`,
@@ -617,7 +735,7 @@ function repairConvergence(head, failures) {
   const failureBlock = failures.length
     ? failures.map((each, position) => `${position + 1}. ${each}`).join('\n')
     : 'none reported'
-  return agent(
+  return convergeAgent(
     `The convergence check for ${prCoordinates} failed these gates on HEAD ${head}:\n${failureBlock}\n\n` +
       `Address only the failing gates:\n` +
       `- Unresolved bot review threads: fetch the threads where isResolved is false (gh api graphql, or the github MCP pull_request_read get_review_comments), then keep only the bot-authored ones — a thread whose root comment author login contains "cursor", "claude", or "copilot" (case-insensitive substring). Explicitly skip every human reviewer thread; the convergence gate counts only unresolved bot threads, so touching a human thread is out of scope. For each bot thread, verify the concern against current code; if it still applies, fix it test-first; either way post an inline reply and resolve the thread.\n` +
@@ -661,7 +779,7 @@ function spawnStandardsFollowUp(head, findings, sourceLabel) {
       return `${position + 1}. [${each.severity}] ${each.file}:${each.line} — ${each.title}\n   ${each.detail}${threadNote}`
     })
     .join('\n')
-  return agent(
+  return convergeAgent(
     `A review round on ${prCoordinates}, HEAD ${head}, surfaced ONLY code-standard violations (CODE_RULES/style, no behavioral impact). The convergence run treats the round as passed and defers these to follow-up work, which you now create. Do NOT commit or push to the PR's own branch.\n\n` +
       `Findings:\n${findingsBlock}\n\n` +
       `1. Follow-up fix issue: file a GitHub issue on ${input.owner}/${input.repo} (gh issue create --body-file with a temp file) titled "Deferred code-standard fixes from PR #${input.prNumber}". The body references the PR and lists each finding with its file:line, severity, and detail. The issue carries the fix work; do not open a fix PR.\n` +
@@ -672,13 +790,62 @@ function spawnStandardsFollowUp(head, findings, sourceLabel) {
   )
 }
 
+/**
+ * Spawn the convergence-summary agent at finalize so its StructuredOutput is
+ * recorded into the run journal for the closing report to read. The agent groups
+ * the deduped findings into plain-language issue classes, translates reviewer
+ * jargon to everyday English, and writes one BLUF verdict line. The side effect
+ * is the journal record; the return value is discarded by the caller.
+ * @param {Array<object>} distinctFindings deduped findings across every round
+ * @param {Array<string>} fixSummaries per-round fix-lens one-line summaries
+ * @param {number} roundCount the number of converge rounds the run took
+ * @param {string|null} standardsNote deferral note when a round was code-standard-only
+ * @param {string|null} copilotNote outage note when the Copilot gate was bypassed
+ * @returns {Promise<object>} CONVERGENCE_SUMMARY_SCHEMA result (journal side effect)
+ */
+function spawnConvergenceSummary(distinctFindings, fixSummaries, roundCount, standardsNote, copilotNote) {
+  const findingsBlock = distinctFindings.length
+    ? distinctFindings
+        .map((each, position) => {
+          const truncatedDetail = (each.detail || '').slice(0, 400)
+          return `${position + 1}. [${each.severity}/${each.category}] ${each.file}:${each.line} — ${each.title} :: ${truncatedDetail}`
+        })
+        .join('\n')
+    : 'none — every lens was clean on a stable HEAD'
+  const fixSummariesBlock = fixSummaries.length
+    ? fixSummaries.map((each, position) => `${position + 1}. ${each}`).join('\n')
+    : 'none'
+  const standardsBlock = standardsNote ? `\nDeferred code-standard note: ${standardsNote}\n` : ''
+  const copilotBlock = copilotNote ? `\nCopilot gate note: ${copilotNote}\n` : ''
+  return convergeAgent(
+    `You write the plain-language convergence summary for ${prCoordinates}. The autoconverge run reached convergence in ${roundCount} round(s). Use ONLY the findings and fix summaries below; invent nothing not present.\n\n` +
+      `Distinct findings caught across the run (already deduped):\n${findingsBlock}\n\n` +
+      `Per-round fix summaries:\n${fixSummariesBlock}\n${standardsBlock}${copilotBlock}\n` +
+      `Produce a summary an everyday reader understands:\n` +
+      `- GROUP near-duplicate findings into issue CLASSES: the same KIND of problem across different files or lines becomes ONE class with a count. Example: seven "Missing return type annotation on test function" findings become one class with count 7.\n` +
+      `- TRANSLATE reviewer jargon into plain everyday English. Examples: "CodingGuidelineID 1000000 / Repository guideline (Types)" -> "a typing rule the project enforces"; "missing return type annotation / Add -> None" -> "a test did not declare what it returns"; "Banned identifier result" -> "a vague variable name the project bans"; a magic-value finding -> "a raw number or string that should be a named value".\n` +
+      `- plainName must carry NO tool token, rule id, file path, line number, severity code (P0/P1/P2), or bot name.\n` +
+      `- Lead with category 'bug' classes, then 'code-standard'. Cap to about 5 classes. whatItWas is at most 2 sentences. No paragraphs.\n` +
+      `- status is 'fixed' unless the fix summaries or the deferred code-standard note mark the class deferred, in which case status is 'deferred'.\n` +
+      `- Use NO hedging words anywhere (likely, probably, should, appears, seems, may, might, could, possibly). State facts ("caught and fixed").\n` +
+      `- When there are zero findings, return issueClasses: [] and a verdictLine stating the run converged with no issues caught.\n` +
+      `- verdictLine is one factual sentence naming the round count and that all classes are fixed or deferred.\n\n` +
+      `Return strictly the schema.`,
+    { label: 'convergence-summary', phase: 'Finalize', schema: CONVERGENCE_SUMMARY_SCHEMA, agentType: 'general-purpose' },
+  )
+}
+
 let phase = 'CONVERGE'
 let head = null
 let rounds = 0
 let iterations = 0
 let blocker = null
 let bugbotDown = input.bugbotDisabled || false
+let copilotDown = false
+let copilotNote = null
 let standardsNote = null
+const allRoundFindings = []
+const fixSummaries = []
 
 while (iterations < CONFIG.maxIterations) {
   iterations += 1
@@ -705,15 +872,22 @@ while (iterations < CONFIG.maxIterations) {
     const findings = roundOutcome.findings
     if (isStandardsOnlyRound(findings)) {
       log(`Round ${rounds}: ${findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the round as passed`)
+      allRoundFindings.push(...findings)
       await spawnStandardsFollowUp(head, findings, 'converge-round')
       standardsNote = `${findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
-      await postCleanAudit(head)
+      const auditResult = await postCleanAudit(head)
+      if (!auditResult?.posted) {
+        blocker = cleanAuditBlocker(head, auditResult)
+        break
+      }
       phase = 'COPILOT'
       continue
     }
     if (findings.length > 0) {
       log(`Round ${rounds}: ${findings.length} finding(s) — applying fixes`)
+      allRoundFindings.push(...findings)
       const fixResult = await applyFixes(head, findings, 'converge-round')
+      if (fixResult?.summary) fixSummaries.push(fixResult.summary)
       const hadThreadBearingFinding = findings.some((each) => collectFindingThreadIds(each).length > 0)
       const fixProgress = detectFixProgress(fixResult, head, hadThreadBearingFinding)
       if (!fixProgress.progressed) {
@@ -729,7 +903,11 @@ while (iterations < CONFIG.maxIterations) {
       continue
     }
     log(`Round ${rounds}: all lenses clean on ${head?.slice(0, 7)} — posting clean audit artifact`)
-    await postCleanAudit(head)
+    const auditResult = await postCleanAudit(head)
+    if (!auditResult?.posted) {
+      blocker = cleanAuditBlocker(head, auditResult)
+      break
+    }
     phase = 'COPILOT'
     continue
   }
@@ -737,24 +915,34 @@ while (iterations < CONFIG.maxIterations) {
   if (phase === 'COPILOT') {
     const copilot = await runCopilotGate(head)
     const copilotOutcome = classifyCopilotOutcome(copilot)
+    copilotDown = resolveCopilotDown(copilotOutcome)
+    copilotNote = null
     if (copilotOutcome.kind === 'retry') {
       log('Copilot gate agent died or returned an unreliable not-clean result with no findings — re-running the gate on the same HEAD')
       continue
     }
-    if (copilotOutcome.kind === 'blocker') {
-      blocker = copilotOutcome.blocker
-      break
+    if (copilotOutcome.kind === 'down') {
+      log('Copilot gate: Copilot is down or out of quota — no review on HEAD after the poll cap. Logging a notice and proceeding to mark-ready with the Copilot gate bypassed.')
+      copilotDown = true
+      copilotNote = 'Copilot was down or out of quota — the Copilot gate was bypassed and the PR was marked ready without a Copilot review'
+      phase = 'FINALIZE'
+      continue
     }
     if (copilotOutcome.kind === 'fix') {
       if (isStandardsOnlyRound(copilotOutcome.findings)) {
         log(`Copilot raised ${copilotOutcome.findings.length} code-standard-only finding(s) — deferring to follow-up PRs and treating the gate as passed`)
+        allRoundFindings.push(...copilotOutcome.findings)
         await spawnStandardsFollowUp(head, copilotOutcome.findings, 'copilot')
         standardsNote = `${copilotOutcome.findings.length} code-standard finding(s) deferred to a follow-up fix issue plus an environment-hardening PR — verify both land`
+        copilotDown = false
+        copilotNote = null
         phase = 'FINALIZE'
         continue
       }
       log(`Copilot raised ${copilotOutcome.findings.length} finding(s) — fixing and re-converging`)
+      allRoundFindings.push(...copilotOutcome.findings)
       const fixResult = await applyFixes(head, copilotOutcome.findings, 'copilot')
+      if (fixResult?.summary) fixSummaries.push(fixResult.summary)
       const hadThreadBearingFinding = copilotOutcome.findings.some((each) => collectFindingThreadIds(each).length > 0)
       const fixProgress = detectFixProgress(fixResult, head, hadThreadBearingFinding)
       if (!fixProgress.progressed) {
@@ -766,22 +954,25 @@ while (iterations < CONFIG.maxIterations) {
       phase = 'CONVERGE'
       continue
     }
+    copilotDown = false
+    copilotNote = null
     phase = 'FINALIZE'
     continue
   }
 
   if (phase === 'FINALIZE') {
-    const convergence = await checkConvergence(bugbotDown)
+    const convergence = await checkConvergence(bugbotDown, copilotDown)
     const convergenceOutcome = classifyConvergenceOutcome(convergence)
     if (convergenceOutcome.kind === 'retry') {
       log('Convergence check agent died or returned no FAIL lines — re-running the check on the same HEAD')
       continue
     }
     if (convergenceOutcome.kind === 'ready') {
-      const readyResult = await markReady(head)
+      const readyResult = await markReady(head, copilotDown)
       const readyOutcome = classifyReadyOutcome(readyResult)
       if (readyOutcome.converged) {
-        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote }
+        await spawnConvergenceSummary(dedupeFindings(allRoundFindings), fixSummaries, rounds, standardsNote, copilotNote)
+        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote }
       }
       blocker = readyOutcome.blocker
       break
@@ -799,4 +990,5 @@ return {
   finalSha: head,
   blocker: blocker || `iteration cap reached (${CONFIG.maxIterations})`,
   standardsNote,
+  copilotNote,
 }

package/skills/autoconverge/workflow/convergence_summary.py

@@ -0,0 +1,110 @@
+"""Build the convergence-summary agent prompt over a PR's aggregated findings."""
+
+from autoconverge_report_constants.render_report_constants import (
+    GITHUB_PR_URL_TEMPLATE,
+    SUMMARY_COPILOT_NOTE_TEMPLATE,
+    SUMMARY_DETAIL_MAX_CHARS,
+    SUMMARY_FINDING_LINE_TEMPLATE,
+    SUMMARY_FINDINGS_EMPTY_TEXT,
+    SUMMARY_FIX_EMPTY_TEXT,
+    SUMMARY_FIX_LINE_TEMPLATE,
+    SUMMARY_PR_COORDINATES_TEMPLATE,
+    SUMMARY_PROMPT_TEMPLATE,
+    SUMMARY_STANDARDS_NOTE_TEMPLATE,
+)
+
+
+def _format_findings_block(findings: list[dict]) -> str:
+    """Return the numbered findings block, or a clean-run sentence when empty.
+
+    Args:
+        findings: Aggregated distinct findings, each carrying severity, category,
+            file, line, title, and detail keys.
+
+    Returns:
+        A newline-joined numbered list, or a sentence stating every lens was clean.
+    """
+    if not findings:
+        return SUMMARY_FINDINGS_EMPTY_TEXT
+    numbered_lines: list[str] = []
+    for position, each_finding in enumerate(findings):
+        detail = str(each_finding.get("detail", ""))[:SUMMARY_DETAIL_MAX_CHARS]
+        numbered_lines.append(
+            SUMMARY_FINDING_LINE_TEMPLATE.format(
+                number=position + 1,
+                severity=each_finding.get("severity", ""),
+                category=each_finding.get("category", ""),
+                file=each_finding.get("file", ""),
+                line=each_finding.get("line", 0),
+                title=each_finding.get("title", ""),
+                detail=detail,
+            )
+        )
+    return "\n".join(numbered_lines)
+
+
+def _format_fix_block(fix_summaries: list[str]) -> str:
+    """Return the numbered per-round fix-summary block, or 'none' when empty.
+
+    Args:
+        fix_summaries: One-line fix summaries collected across every round.
+
+    Returns:
+        A newline-joined numbered list, or the empty-state literal.
+    """
+    if not fix_summaries:
+        return SUMMARY_FIX_EMPTY_TEXT
+    return "\n".join(
+        SUMMARY_FIX_LINE_TEMPLATE.format(number=position + 1, summary=each_summary)
+        for position, each_summary in enumerate(fix_summaries)
+    )
+
+
+def build_summary_prompt(
+    owner: str,
+    repo: str,
+    pr_number: int,
+    round_count: int,
+    findings: list[dict],
+    fix_summaries: list[str],
+    standards_note: str | None,
+    copilot_note: str | None,
+) -> str:
+    """Return the convergence-summary agent prompt for a PR's aggregated findings.
+
+    Args:
+        owner: The PR's repository owner.
+        repo: The PR's repository name.
+        pr_number: The PR number.
+        round_count: Total converge rounds across every run aggregated.
+        findings: Aggregated distinct findings across every run.
+        fix_summaries: One-line fix summaries collected across every run.
+        standards_note: Deferral note when a round was code-standard-only, else None.
+        copilot_note: Outage note when the Copilot gate was bypassed, else None.
+
+    Returns:
+        The full agent prompt instructing a StructuredOutput convergence summary.
+    """
+    pr_url = GITHUB_PR_URL_TEMPLATE.format(owner=owner, repo=repo, number=pr_number)
+    pr_coordinates = SUMMARY_PR_COORDINATES_TEMPLATE.format(
+        owner=owner, repo=repo, pr_number=pr_number, url=pr_url
+    )
+    standards_block = (
+        SUMMARY_STANDARDS_NOTE_TEMPLATE.format(note=standards_note)
+        if standards_note
+        else ""
+    )
+    copilot_block = (
+        SUMMARY_COPILOT_NOTE_TEMPLATE.format(note=copilot_note) if copilot_note else ""
+    )
+    return SUMMARY_PROMPT_TEMPLATE.format(
+        pr_coordinates=pr_coordinates,
+        owner=owner,
+        repo=repo,
+        pr_number=pr_number,
+        round_count=round_count,
+        findings_block=_format_findings_block(findings),
+        fix_block=_format_fix_block(fix_summaries),
+        standards_block=standards_block,
+        copilot_block=copilot_block,
+    )

package/skills/autoconverge/workflow/fixtures/wf_run/subagents/workflows/wf_881252e6-700/agent-ab1c2d3e4f5a6b7c8.jsonl

@@ -0,0 +1,2 @@
+{"type": "user", "uuid": "ab1c2d3e4f5a6b7c8-u", "message": {"role": "user", "content": "Return the convergence summary."}}
+{"type": "assistant", "uuid": "ab1c2d3e4f5a6b7c8-a", "message": {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_ab1c2d3e4f5a6b7c8", "name": "StructuredOutput", "input": {"prProblem": "DataBridge, the service that exports your records in batches, restarted an interrupted export from the beginning instead of continuing.", "prFix": "An interrupted export now resumes from the last finished batch.", "problemScenes": [{"trigger": "export stops at batch 90 of 100", "condition": "you restart it", "result": "starts again at batch 1", "caption": "A halted export threw away the 90 batches it had already finished and began again."}], "fixScenes": [{"trigger": "export stops at batch 90 of 100", "condition": "you restart it", "result": "continues at batch 91", "caption": "A restarted export now picks up at the next unfinished batch."}], "verdictLine": "Converged in 4 rounds; 3 distinct issue classes were caught and fixed.", "issueClasses": [{"plainName": "Tests did not declare their return type", "count": 7, "severity": "P2", "category": "code-standard", "status": "fixed", "cause": "Several new test functions did not state that they return nothing, which the project's type checker wants.", "medium": "code", "beforeLines": ["def test_resume_skip():", "    ..."], "afterLines": ["def test_resume_skip() -> None:", "    ..."]}, {"plainName": "A vague banned variable name", "count": 2, "severity": "P2", "category": "code-standard", "status": "fixed", "cause": "Two variables used a generic placeholder name the project bans.", "medium": "code", "beforeLines": ["result = fetch()"], "afterLines": ["exported_rows = fetch()"]}, {"plainName": "Hardcoded message strings", "count": 6, "severity": "P2", "category": "code-standard", "status": "fixed", "cause": "Warning text was written inline in code instead of shared configuration.", "medium": "text", "beforeLines": ["inline warning text"], "afterLines": ["shared config message"]}]}}]}}