claude-dev-env 1.84.0 → 1.86.0

package/skills/_shared/pr-loop/scripts/write_handoff.py

@@ -0,0 +1,309 @@
+"""Write durable resume-handoff files for a pr-loop run.
+
+A converge loop can stop mid-run: a paused tick, a budget cutoff, a killed
+session. The next session then has no pointer to where the run was. This writer
+drops that pointer somewhere the OS temp sweep cannot purge.
+
+::
+
+    write_handoff.py --pr-number <N> --head-ref <branch> --phase tick
+        --resume-command "claude --resume /pr-converge" [--state-file <PATH>]
+    writes:  ~/.claude/runtime/pr-loop/<run-name>/handoff.json + HANDOFF.md
+    plus:    state-copy.json  (only when --state-file is given)
+
+It records the resume command, the phase reached, the steps already done, and a
+copy of the loop state, so a fresh session picks up without re-deriving it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from _path_resolver import build_run_name  # noqa: E402
+from skills_pr_loop_constants.handoff_constants import (  # noqa: E402
+    ATOMIC_STAGING_SUFFIX,
+    COMPLETED_STEPS_SEPARATOR,
+    DEFAULT_NEXT_STEP_LINE,
+    ALL_HANDOFF_DIR_SEGMENTS,
+    HANDOFF_JSON_FILENAME,
+    HANDOFF_JSON_INDENT,
+    HANDOFF_MARKDOWN_FILENAME,
+    HANDOFF_MARKDOWN_TEMPLATE,
+    NO_STATE_SNAPSHOT_LINE,
+    NO_STEPS_DONE_LINE,
+    STATE_COPY_FILENAME,
+    STEP_LINE_SEPARATOR,
+)
+
+
+def _now_iso() -> str:
+    """Return the current UTC time as an ISO-format timestamp string.
+
+    Returns:
+        The stamp recorded on the handoff so a reader knows how fresh it is.
+    """
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _handoff_base_dir() -> Path:
+    """Return the durable base directory that holds every run's handoff folder.
+
+    Returns:
+        The ``~/.claude/runtime/pr-loop`` path under the user's home directory.
+    """
+    return Path.home().joinpath(*ALL_HANDOFF_DIR_SEGMENTS)
+
+
+def resolve_handoff_dir(run_name: str) -> Path:
+    """Resolve the durable handoff directory for a run name.
+
+    Args:
+        run_name: Run name token (from build_run_name).
+
+    Returns:
+        Absolute path to the run's handoff directory under the durable base.
+    """
+    return _handoff_base_dir() / run_name
+
+
+def _write_text_atomic(target_path: Path, text: str) -> None:
+    """Write text to a path atomically via a staging file and a rename.
+
+    Args:
+        target_path: Destination file path.
+        text: Full file contents to write.
+    """
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    staging_path = target_path.with_name(
+        f"{target_path.name}{ATOMIC_STAGING_SUFFIX}.{os.getpid()}"
+    )
+    staging_path.write_text(text, encoding="utf-8")
+    os.replace(staging_path, target_path)
+
+
+def _snapshot_state(handoff_dir: Path, state_file: Path | None) -> str | None:
+    """Copy a loop state file into the handoff directory when one is supplied.
+
+    Args:
+        handoff_dir: The run's durable handoff directory.
+        state_file: Loop state file to snapshot, or None to skip the copy.
+
+    Returns:
+        The forward-slash path of the copy to trust, or None when no state
+        file was supplied.
+    """
+    if state_file is None:
+        return None
+    state_copy_path = handoff_dir / STATE_COPY_FILENAME
+    _write_text_atomic(state_copy_path, state_file.read_text(encoding="utf-8"))
+    return state_copy_path.as_posix()
+
+
+def _steps_markdown_block(all_completed_steps: list[str]) -> str:
+    """Render the completed steps as a markdown bullet list.
+
+    Args:
+        all_completed_steps: Steps already finished this run.
+
+    Returns:
+        A bullet list, or a placeholder line when no steps are recorded.
+    """
+    if not all_completed_steps:
+        return NO_STEPS_DONE_LINE
+    return STEP_LINE_SEPARATOR.join(f"- {each_step}" for each_step in all_completed_steps)
+
+
+def _build_handoff_markdown(
+    *,
+    pr_number: int,
+    head_ref: str,
+    phase: str,
+    resume_command: str,
+    trusted_state_path: str | None,
+    all_completed_steps: list[str],
+    note: str | None,
+) -> str:
+    """Build the human-facing HANDOFF.md body for a fresh session.
+
+    Args:
+        pr_number: Pull request number.
+        head_ref: Head branch ref.
+        phase: The checkpoint the run reached.
+        resume_command: The exact command a fresh session runs to resume.
+        trusted_state_path: The state-copy path to trust, or None.
+        all_completed_steps: Steps already finished this run.
+        note: Free-text next-step note, or None.
+
+    Returns:
+        The rendered markdown document.
+    """
+    state_line = (
+        f"Trust this state snapshot: {trusted_state_path}"
+        if trusted_state_path is not None
+        else NO_STATE_SNAPSHOT_LINE
+    )
+    return HANDOFF_MARKDOWN_TEMPLATE.format(
+        pr_number=pr_number,
+        head_ref=head_ref,
+        phase=phase,
+        resume_command=resume_command,
+        state_line=state_line,
+        steps_block=_steps_markdown_block(all_completed_steps),
+        next_step=note if note else DEFAULT_NEXT_STEP_LINE,
+    )
+
+
+def write_handoff(
+    *,
+    pr_number: int,
+    head_ref: str,
+    phase: str,
+    resume_command: str,
+    state_file: Path | None = None,
+    run_id: str | None = None,
+    all_completed_steps: list[str] | None = None,
+    note: str | None = None,
+) -> Path:
+    """Write handoff.json, HANDOFF.md, and an optional state copy for a run.
+
+    Names the run with build_run_name and places the files under the durable
+    handoff directory. When a state file is supplied, its contents are copied to
+    state-copy.json and that copy path is recorded as the state to trust.
+
+    Args:
+        pr_number: Pull request number.
+        head_ref: Head branch ref.
+        phase: The checkpoint the run reached (e.g. 'tick', 'teardown').
+        resume_command: The exact command a fresh session runs to resume.
+        state_file: Loop state file to snapshot, or None to skip the copy.
+        run_id: Workflow run id to resume from, or None.
+        all_completed_steps: Steps already finished this run, or None.
+        note: Free-text next-step note for the fresh session, or None.
+
+    Returns:
+        Path to the run's durable handoff directory.
+    """
+    steps_done = all_completed_steps if all_completed_steps else []
+    run_name = build_run_name(pr_number, head_ref, is_multi_pr=False)
+    handoff_dir = resolve_handoff_dir(run_name)
+    handoff_dir.mkdir(parents=True, exist_ok=True)
+
+    trusted_state_path = _snapshot_state(handoff_dir, state_file)
+    payload = {
+        "pr_number": pr_number,
+        "head_ref": head_ref,
+        "phase": phase,
+        "resume_command": resume_command,
+        "run_id": run_id,
+        "state_file": trusted_state_path,
+        "completed_steps": steps_done,
+        "note": note,
+        "timestamp": _now_iso(),
+    }
+    _write_text_atomic(
+        handoff_dir / HANDOFF_JSON_FILENAME,
+        json.dumps(payload, indent=HANDOFF_JSON_INDENT) + "\n",
+    )
+    _write_text_atomic(
+        handoff_dir / HANDOFF_MARKDOWN_FILENAME,
+        _build_handoff_markdown(
+            pr_number=pr_number,
+            head_ref=head_ref,
+            phase=phase,
+            resume_command=resume_command,
+            trusted_state_path=trusted_state_path,
+            all_completed_steps=steps_done,
+            note=note,
+        ),
+    )
+    return handoff_dir
+
+
+def _split_completed_steps(raw_steps: str) -> list[str]:
+    """Split a comma-separated steps argument into a trimmed, non-empty list.
+
+    Args:
+        raw_steps: The raw --completed-steps CLI value.
+
+    Returns:
+        The individual step names with surrounding whitespace removed.
+    """
+    return [
+        each_segment.strip()
+        for each_segment in raw_steps.split(COMPLETED_STEPS_SEPARATOR)
+        if each_segment.strip()
+    ]
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments.
+
+    Args:
+        all_argv: Command-line argument list.
+
+    Returns:
+        Parsed namespace with the handoff fields.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pr-number", type=int, required=True)
+    parser.add_argument("--head-ref", required=True)
+    parser.add_argument("--phase", required=True)
+    parser.add_argument("--resume-command", required=True)
+    parser.add_argument("--state-file", type=Path, default=None)
+    parser.add_argument("--run-id", default=None)
+    parser.add_argument("--completed-steps", default="")
+    parser.add_argument("--note", default=None)
+    return parser.parse_args(all_argv)
+
+
+def _write_handoff_from_arguments(arguments: argparse.Namespace) -> Path:
+    """Map parsed CLI arguments onto a write_handoff call.
+
+    Args:
+        arguments: The namespace parse_arguments produced.
+
+    Returns:
+        Path to the run's durable handoff directory.
+    """
+    return write_handoff(
+        pr_number=arguments.pr_number,
+        head_ref=arguments.head_ref,
+        phase=arguments.phase,
+        resume_command=arguments.resume_command,
+        state_file=arguments.state_file,
+        run_id=arguments.run_id,
+        all_completed_steps=_split_completed_steps(arguments.completed_steps),
+        note=arguments.note,
+    )
+
+
+def main(all_arguments: list[str]) -> int:
+    """Entry point: write the handoff files and print the durable directory.
+
+    Args:
+        all_arguments: Command-line arguments.
+
+    Returns:
+        0 on success, 1 on a state-file read or write failure.
+    """
+    arguments = parse_arguments(all_arguments)
+    try:
+        handoff_dir = _write_handoff_from_arguments(arguments)
+    except (OSError, UnicodeDecodeError) as read_or_write_error:
+        print(f"write_handoff failed: {read_or_write_error}", file=sys.stderr)
+        return 1
+    print(handoff_dir.as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

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`.