claude-dev-env 1.84.0 → 1.85.0

package/skills/autoconverge/SKILL.md

@@ -115,6 +115,19 @@ and `false` when it exits 0; on `true` the workflow skips the Copilot gate with
 no agent spawned. The workflow runs in the background and notifies this session
 on completion. Watch live progress with `/workflows`.
 
+The moment the `Workflow` call returns its run id, write the durable handoff so a
+fresh session can resume the same run:
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
+  --pr-number <N> --head-ref <branch> --phase workflow \
+  --resume-command "Workflow({scriptPath, resumeFromRunId: '<runId>'})" \
+  --run-id <runId>
+```
+
+Write it again when the result lands, so the handoff carries the final run id and
+names the teardown phase the fresh session picks up from.
+
 The workflow returns
 `{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote, deferredPrs }`.
 `deferredPrs` is the list of draft environment-hardening PRs the standards-deferral
@@ -134,8 +147,32 @@ returns `blocker: "budget"` with the run id; resume with
 the journal. Never start a round the budget cannot finish: a half-run
 round records nothing resumable and replays dirty.
 
+On a `blocker: "budget"` return, write the durable handoff with the run id and the
+`Workflow({scriptPath, resumeFromRunId})` resume command before stopping, so a
+fresh session resumes the paced run without the stopped session's transcript.
+
 ## Teardown (on workflow completion)
 
+Teardown runs as an ordered checkpoint list. After each checkpoint finishes,
+re-write the durable handoff with `--phase teardown`, the run id, and the
+checkpoints done so far, so a fresh session that resumes reads `handoff.json`
+`completed_steps` and skips the checkpoints already done:
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
+  --pr-number <N> --head-ref <branch> --phase teardown \
+  --resume-command "/autoconverge <PR URL>" \
+  --run-id <runId> \
+  --completed-steps "<checkpoints done so far>"
+```
+
+The checkpoints run in this order: `report`, `close`. Write the
+handoff after each one finishes.
+
+On teardown entry, when `~/.claude/runtime/pr-loop/bugteam-pr-<N>/handoff.json`
+exists, read its `completed_steps` and skip any checkpoint the list already
+names, so a resumed run performs only the checkpoints left.
+
 1. **When `converged` is true — build and publish the closing report.**
    Skip this entire step (report, artifact publish, comment, Chrome open) when the
    workflow returned a non-null `blocker`. Per-round live-dashboard refresh is out of
@@ -204,14 +241,18 @@ round records nothing resumable and replays dirty.
       ```
       Start-Process chrome -ArgumentList '--new-window', '<artifact URL>'
       ```
-      Tolerate a missing Chrome without aborting the rest of teardown.
+      Skip a missing Chrome without aborting the rest of teardown.
+
+   After the report is published, write the handoff with
+   `--completed-steps "report"`.
 
 2. **Close the run.** Apply the `pr-loop-lifecycle` skill's Close section
    (`../pr-loop-lifecycle/SKILL.md`): when `converged` is true, rewrite the PR
    description and clean the working tree — see
    [`pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Clean working tree and § Publish the final PR description](../pr-loop-lifecycle/reference/teardown-publish-permissions.md);
    the workflow already marked the PR ready. The permission revoke always runs,
-   including on a blocker exit.
+   including on a blocker exit. Write the handoff with
+   `--completed-steps "report,close"`.
 
 3. **Print the final report:**
 
@@ -385,7 +426,9 @@ top-level `converged` is true only when every PR converged.
 
 Run the single-PR [Teardown](#teardown-on-workflow-completion) once per entry in
 `results`, using that PR's `owner`, `repo`, `prNumber`, and `finalSha`, and its
-own worktree as the working directory. Build and publish a PR's closing report
+own worktree as the working directory. Write one durable handoff per PR entry —
+each with that PR's own `--pr-number` — so a fresh session can resume any PR on
+its own. Build and publish a PR's closing report
 only for a PR whose `converged` is true; for a PR that returned a blocker, skip
 its report and carry the blocker into the final summary. Revoke project
 permissions once per repository after every PR's teardown. Then print one summary

package/skills/autoconverge/workflow/converge.mjs

@@ -1359,7 +1359,7 @@ function runCopilotGate(head) {
       `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` +
       `   ${REVIEWER_GATE_SENTINEL}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 (wait each 360-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above; if the attempt budget is spent with no review on HEAD, return down: true). 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` +
+      `2. Poll for Copilot's review on HEAD ${head}: up to ${CONFIG.copilotMaxPolls} attempts, 360 seconds apart (wait each 360-second interval inside this turn with the Monitor tool, per the WAITS AND POLLS rule above; if the attempt budget is spent with no review on HEAD, return the full down result {sha:${'`'}${head}${'`'}, clean:false, down:true, findings:[]}). 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` +
       `   - Out-of-usage notice on HEAD -> return the down result above (clean:true, down:true) and stop.\n` +
       `   - Copilot review present on HEAD whose state is APPROVED, or COMMENTED with no inline findings -> a clean pass: 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` +

package/skills/pr-converge/SKILL.md

@@ -43,6 +43,15 @@ working directory routes into the PR's repo for local work and returns to
 the session worktree before teardown. See
 [`reference/per-tick.md` § Step 1.5](reference/per-tick.md).
 
+## Resume from a prior run
+
+Before Step 0, check
+`~/.claude/runtime/pr-loop/bugteam-pr-<PR number>/handoff.json`. When
+`$CLAUDE_JOB_DIR/pr-converge-state.json` is absent but that handoff exists, seed
+`phase`, `tick_count`, and the clean-at SHAs from the run's `state-copy.json`, so
+a fresh session continues where the last one stopped rather than restarting at
+BUGBOT.
+
 ## Copilot quota pre-check (start of run)
 
 On the first tick, apply the `reviewer-gates` skill's Copilot quota gate
@@ -61,7 +70,8 @@ Before starting any tick, estimate whether the remaining session/usage
 budget covers one full clean tick (worst case: a BUGBOT fetch + a
 full-diff CODE_REVIEW + a fix commit + replies). If it does not, do not
 start the tick. Stop at the current tick boundary: write updated state to
-`$CLAUDE_JOB_DIR/pr-converge-state.json`, then report the exact resume
+`$CLAUDE_JOB_DIR/pr-converge-state.json`, write the durable handoff (see
+[State persistence](#state-persistence)), then report the exact resume
 command (`/pr-converge <PR URL>`) and the persisted `phase`/`tick_count`.
 A tick cut off mid-flight poisons the resume state — clean SHAs recorded
 against work that never landed — so an unstarted tick is always cheaper
@@ -83,6 +93,22 @@ On tick entry, read this file if it exists to restore phase, tick_count, and
 clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
 so the next tick resumes with accurate state.
 
+After the state write and before ScheduleWakeup, write the durable handoff so a
+fresh session in a new job can resume this run:
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
+  --pr-number <N> --head-ref <branch> --phase <phase> \
+  --resume-command "/pr-converge <PR URL>" \
+  --state-file "$CLAUDE_JOB_DIR/pr-converge-state.json" \
+  --completed-steps "<clean phases this run>"
+```
+
+It writes `handoff.json`, `HANDOFF.md`, and `state-copy.json` under
+`~/.claude/runtime/pr-loop/<run-name>/`. The job-dir state stays the source of
+truth for a resumed tick; the handoff copy is the pointer a fresh session reads
+when `$CLAUDE_JOB_DIR` is gone.
+
 Fields: `phase`, `tick_count`, `bugbot_clean_at`, `code_review_clean_at`,
 `bugteam_clean_at`, `copilot_clean_at`, `current_head`,
 `bugbot_acknowledged_at`, `bugbot_down`, `copilot_down`,

package/skills/pr-converge/reference/state-schema.md

@@ -100,3 +100,15 @@ if it exists and ends by writing the updated state back to that same file
 before scheduling the next wakeup. Multi-PR mode additionally coordinates
 across PRs via `<TMPDIR>/pr-converge-<session_id>/state.json` per
 `multi-pr-orchestration.md` §What orchestrator does per tick.
+
+## Handoff files
+
+Each tick also writes a durable handoff under
+`~/.claude/runtime/pr-loop/<run-name>/` via
+`skills/_shared/pr-loop/scripts/write_handoff.py`: `handoff.json` (resume
+command, phase, tick, and state path), `HANDOFF.md` (a prompt a fresh session
+reads), and `state-copy.json` (a copy of the job-dir state). `$CLAUDE_JOB_DIR`
+can be cleaned between sessions; this directory under the user home is not, so it
+holds the pointer a new job needs. Live job-dir state wins for a resumed tick. A
+fresh session reads the handoff copy only when `$CLAUDE_JOB_DIR` state is gone,
+seeding phase, tick, and SHAs from `state-copy.json`.