claude-dev-env 1.58.0 → 1.59.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 = {
@@ -324,22 +342,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 +452,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 +470,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 +488,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 +514,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 +530,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 +560,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` +
@@ -544,7 +584,7 @@ function applyFixes(head, findings, sourceLabel) {
  * @returns {Promise<string>} agent transcript (unused)
  */
 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` +
@@ -555,19 +595,25 @@ function postCleanAudit(head) {
 
 /**
  * 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 +622,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 +640,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 +675,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 +719,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` +
@@ -678,6 +736,8 @@ let rounds = 0
 let iterations = 0
 let blocker = null
 let bugbotDown = input.bugbotDisabled || false
+let copilotDown = false
+let copilotNote = null
 let standardsNote = null
 
 while (iterations < CONFIG.maxIterations) {
@@ -737,19 +797,26 @@ 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`)
         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
       }
@@ -766,22 +833,24 @@ 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 }
+        return { converged: true, rounds, finalSha: head, blocker: null, standardsNote, copilotNote }
       }
       blocker = readyOutcome.blocker
       break
@@ -799,4 +868,5 @@ return {
   finalSha: head,
   blocker: blocker || `iteration cap reached (${CONFIG.maxIterations})`,
   standardsNote,
+  copilotNote,
 }