@jesdi/skills 0.0.44 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.44",
+  "version": "0.0.45",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/implement-spec/ARCHITECTURE.md

@@ -21,7 +21,9 @@ A comment in the code is for a line that looks wrong or removable without it.
 | `driver_merge.py` | Merges by git plumbing, the locked-file check of a landing, the move of the PR ref |
 | `driver_gate.py` | One run of the gate command and its record |
 | `driver_slots.py` | The worktrees that tickets run in, and the `git` helper |
-| `driver_state.py` | `state.json` (the resume contract) and the lock of one driver per repository |
+| `driver_state.py` | `state.json` (the resume contract) and the kernel lock |
+| `driver_names.py` | The names of one run: its ticket branches, its recovery ref and its lock file |
+| `driver_legacy.py` | The take-over of a run that an older driver started; delete it when no such run is left |
 | `driver_decisions.py`, `driver_answers.py`, `driver_review_page.py` | Operator questions, their answers, the page that shows them |
 | `driver_tidy.py`, `driver_summary.py` | The history with one commit per ticket; `summary.md` |
 
@@ -89,7 +91,7 @@ and do not know about the run, except `driver_run.py`, which the three deciding
 - The gate runs only on a commit the driver is about to trust, and one green record settles that commit.
   A gate on a dirty tree, or one that leaves the tree changed or HEAD moved, is red.
 - The end of run rewrites the branch one time, before the first final review, and never after a review. A history
-  that origin has is never rewritten. `refs/implement/recovery` holds the tip before the rewrite.
+  that origin has is never rewritten. `refs/implement-spec/<key>/recovery` holds the tip before the rewrite.
 - A rewrite never changes a file: the driver compares trees (`driver_tidy.same_tree`) before it moves the branch.
 - The push sends the reviewed commit, not the branch name, with no force.
 
@@ -110,8 +112,11 @@ and do not know about the run, except `driver_run.py`, which the three deciding
   `finish_interrupted_move` completes it at the next start.
 - At a resume, git must confirm each recorded tip (`driver_state.verified`). A ticket that git contradicts goes
   back to `implement` from its test-writer commit.
-- The lock of one driver per repository is a kernel lock on a file in the git common directory. The kernel frees
-  it when the process ends, so it is never stale.
+- The lock of one driver per PR branch is a kernel lock on a file in the git common directory. The kernel frees
+  it when the process ends, so it is never stale. Every ref that a run writes has the PR branch in its name
+  as one escaped name component. `driver_names.Names` (`Run.names`) makes every name of a run, so runs on
+  different PR branches share no ref. `driver_legacy.resume` takes over a run that an older driver started, once,
+  after the lock and before any check reads a ref.
 
 ### Agents
 

package/skills/implement-spec/README.md

@@ -23,7 +23,9 @@ Before any agent starts, the driver checks these. Each failed check prints one l
 
 A run that stopped is continued with the same command. `state.json` is the only input of a resume.
 
-One driver runs in a repository at a time. The driver holds a kernel file lock on `implement-spec.lock` in the git common directory (`git rev-parse --git-common-dir`) for the whole run. Each worktree of the repository shares that directory, so a second driver in the same worktree or in another one ends with exit 3 and names the lock file. The file is not in a worktree, so `git status` never shows it. The lock ends with its process, so a driver that was killed leaves no lock behind. `--dry-run` takes no lock. A wrong call in a worktree that has no `.agent/implement/` takes no lock and makes no file; where an earlier run left that folder, the driver takes the lock first, then makes the checks.
+One driver runs on a PR branch at a time. The driver holds a kernel file lock on `implement-spec/<key>.lock` in the git common directory (`git rev-parse --git-common-dir`) for the whole run. `<key>` is the PR branch as one name component: `%` becomes `%25` and `/` becomes `%2F`, so `feat/x` gives `feat%2Fx`. Each worktree of the repository shares that directory, so a second driver on the same PR branch, in the same worktree or in another one, ends with exit 3 and names the lock file. Drivers on different PR branches run at the same time: each ticket branch is `ticket/<key>/<NN>` and the recovery ref is `refs/implement-spec/<key>/recovery`, so two runs share no ref. Git refs are a tree, and one component per PR branch keeps the refs of one run from being a folder of the refs of another. The file is not in a worktree, so `git status` never shows it. The lock ends with its process, so a driver that was killed leaves no lock behind. `--dry-run` takes no lock. A wrong call in a worktree that has no `.agent/implement/` takes no lock and makes no file; where an earlier run left that folder, the driver takes the lock first, then makes the checks.
+
+A driver before this change named the ticket branches `ticket/<NN>` and the recovery ref `refs/implement/recovery`. An older driver holds `implement-spec.lock` in the git common directory alone for its whole run. Each newer driver also holds that file, shared, for its whole run: newer drivers do not stop each other, but while an older driver runs in the repository, a newer one ends with exit 3 and names that lock, and while a newer one runs, no older driver starts. A run that the newer driver started has `schema` 2 in `state.json`. When the newer driver resumes a run with no `schema`, it renames each `ticket/<NN>` that holds the start commit of the run and the tip that the run recorded, and moves `refs/implement/recovery` when it holds the recovery point of the run. It writes one ledger sentence for each, and then `schema`. A ref that git cannot rename ends the run with exit 3 and git's error, and nothing is lost.
 
 ## Flags
 
@@ -56,7 +58,7 @@ Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, review
 | 0 | Done: every ticket is merged and no question is open. Also the end of a valid `--dry-run`. In local mode without `--push`, nothing is pushed. |
 | 1 | A ticket is BLOCKED, or the end of run is BLOCKED. The other tickets ran as far as they could. |
 | 2 | Parked: a question of kind `locked-test` or `final-finding` is open. Exit 2 wins over exit 1. |
-| 3 | Invalid input or a failed precondition: a usage error, a ticket error, a model error, an uncommitted change, a slot that cannot be made, another driver that runs in the same repository. No agent starts. The one exception: a review page that cannot be written gives exit 3 at the end of a run, after agents ran. |
+| 3 | Invalid input or a failed precondition: a usage error, a ticket error, a model error, an uncommitted change, a slot that cannot be made, another driver that runs on the same PR branch. No agent starts. The one exception: a review page that cannot be written gives exit 3 at the end of a run, after agents ran. |
 | 4 | Stopped: the CLI of an agent failed two times and wrote no report (for example, the account cannot use the model). The driver starts no other agent and lets the running agents end. No ticket is BLOCKED by it: fix the CLI or the model entry, then run the same command again to resume. |
 | 130 | The operator interrupted the run. The driver stops each agent. The work stays in the slots for the next run. |
 
@@ -75,7 +77,7 @@ Everything is under `.agent/`, which is never committed.
 | Path | Content |
 |---|---|
 | `.agent/implement/state.json` | The resume contract: the run record and one record for each ticket (`driver_state.py`). |
-| `<git common directory>/implement-spec.lock` | An empty file, not in the worktree. The driver that runs holds a kernel file lock on it (`driver_state.py` `lock`). Do not remove it during a run. |
+| `<git common directory>/implement-spec/<key>.lock` | An empty file, not in the worktree. The driver that runs holds a kernel file lock on it (`driver_state.py` `lock`). Do not remove it during a run. |
 | `.agent/implement/ledger.md` | One plain sentence for each event. Only the driver writes it, and it reads no fact from it. |
 | `.agent/implement/summary.md` | The result in sentences, and the measurement table: gates, agents, wall time, fix rounds, human stops, cost. |
 | `.agent/implement/decisions.json` | The open questions and their `revision`. Written only after a stop. |
@@ -88,7 +90,8 @@ Everything is under `.agent/`, which is never committed.
 | `.agent/implement-review.html` | The page with the open questions. |
 | `.agent/implement-answers.json` | The answers: `{"v": 1, "stage": "implement", "submitted": …, "revision": …, "answers": {…}}`. |
 | `.agent/worktrees/slot-K/` | Slots 2..N. Slot 1 is the PR worktree. |
-| `refs/implement/recovery` | A git ref: the PR tip before the tidy. |
+| `refs/implement-spec/<key>/recovery` | A git ref: the PR tip before the tidy. |
+| `ticket/<key>/<NN>` | The branch of one ticket. The driver deletes it when the ticket is merged. |
 
 ## Roles of one ticket
 
@@ -131,7 +134,7 @@ A red gate on the commit of the implementer or of a fixer is a critical finding
 
 The end of run starts only when every ticket is merged and every slot is idle. Its agents work in slot 1.
 
-1. **Tidy.** The driver saves the PR tip in `refs/implement/recovery`. It then makes one commit for each ticket, in merge order, named `feat(NN): <title>`. Each commit holds the tests, the implementation and the fixes of its ticket. The tree of the new tip must equal the tree of the old tip, or the branch stays as it was.
+1. **Tidy.** The driver saves the PR tip in `refs/implement-spec/<key>/recovery`. It then makes one commit for each ticket, in merge order, named `feat(NN): <title>`. Each commit holds the tests, the implementation and the fixes of its ticket. The tree of the new tip must equal the tree of the old tip, or the branch stays as it was.
 2. **Rebase** onto the fetched tip of the default branch of `origin`. A conflict goes to the conflict agent (`prompts/rebase-conflict.md`) once, and the rebased tip is gated.
 3. **Gate**, then the **final-reviewer** (`prompts/final-reviewer.md`) on the whole range, with the method of the `review-diff` skill. It gets the minor findings of the tickets and the rulings of the operator.
 4. **Fix batch.** Critical and important findings go to one fixer (`prompts/final-fixer.md`). The driver names each of its commits `fix(NN): …` from the ticket in the report. Then the gate, then one scoped review of those commits.

package/skills/implement-spec/driver.py

@@ -14,8 +14,10 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
+from contextlib import ExitStack
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -25,6 +27,7 @@ import driver_decisions
 import driver_final
 import driver_fixloop
 import driver_graph
+import driver_legacy
 import driver_merge
 import driver_review
 import driver_review_page
@@ -32,6 +35,7 @@ import driver_slots
 import driver_state
 import driver_summary
 import driver_tickets
+from driver_names import Names
 from driver_run import FINAL, OUT, Blocked, Halted, Run, during, ledger
 from driver_slots import git
 from driver_tickets import Ticket
@@ -59,7 +63,7 @@ def _roles_left(ticket: Ticket, phase: str, only: str | None) -> list[str]:
 
 def _check_out_ticket(ticket: Ticket, slot_number: int, entry: dict, run: Run) -> str:
     """Put the ticket branch in the slot and return the commit its next role starts from."""
-    slot, branch = driver_slots.path(slot_number), f"ticket/{ticket.number}"
+    slot, branch = driver_slots.path(slot_number), run.names.ticket(ticket.number)
     if run.kept.get(ticket.number) == slot_number:
         # The slot holds the uncommitted work of an interrupted role: the branch and the tree stay as they are.
         return entry["tip"] or git(slot, "merge-base", "HEAD", run.tip()).stdout.strip()
@@ -80,7 +84,8 @@ def _prompt_values(ticket: Ticket, slot: str, run: Run) -> dict[str, str]:
     """The pointers every prompt of the ticket gets. An agent works in its slot, so paths are relative to it."""
     folder = OUT / ticket.number
     return {"spec": os.path.relpath(run.args.spec, slot), "seam": ticket.seam, "pr_branch": run.pr,
-            "branch": f"ticket/{ticket.number}", "ticket": os.path.relpath(Path(run.args.tickets) / ticket.file, slot),
+            "branch": run.names.ticket(ticket.number),
+            "ticket": os.path.relpath(Path(run.args.tickets) / ticket.file, slot),
             "correctness": str(driver_review.CORRECTNESS), "gate": run.args.gate,
             "blocked_report": os.path.relpath(_blocked_report(ticket.number, run), slot),
             "writer_report": os.path.relpath(folder / "test-writer-0.json", slot)}
@@ -152,7 +157,7 @@ def _resolve_conflict(ticket: Ticket, slot: str, run: Run, tip: str, files: list
 
 def _merge_commit(ticket: Ticket, slot: str, run: Run, tip: str, may_resolve: bool) -> _Landing:
     """Merge the ticket tip with the PR tip into a commit that no ref holds yet."""
-    message = f"Merge ticket/{ticket.number} into {run.pr}"
+    message = f"Merge {run.names.ticket(ticket.number)} into {run.pr}"
     pr_tip = run.tip()
     commit, error = driver_merge.commit(pr_tip, tip, message)
     if not error:
@@ -171,7 +176,8 @@ def _merge_commit(ticket: Ticket, slot: str, run: Run, tip: str, may_resolve: bo
 def _checked_landing(ticket: Ticket, slot: str, run: Run, may_resolve: bool) -> _Landing:
     """The commit to land, with the locked-file check passed and the gate green. Call it under the merge lock."""
     number = ticket.number
-    git(slot, "checkout", "-q", f"ticket/{number}")  # an earlier try left the slot on its merge commit
+    # An earlier try left the slot on its merge commit.
+    git(slot, "checkout", "-q", run.names.ticket(number))
     tip = run.state.ticket(number, phase="merge")["tip"]
     landing = _merge_commit(ticket, slot, run, tip, may_resolve)
     refusal = driver_merge.refused(run.state.read()["tickets"], number, landing.pr_tip, landing.commit)
@@ -208,7 +214,7 @@ def _record_landing(state: dict, number: str, pr_tip: str) -> None:
 
 def _merge(ticket: Ticket, slot: str, run: Run) -> None:
     """Land the reviewed ticket tip on the PR branch, then delete the ticket branch."""
-    number, branch = ticket.number, f"ticket/{ticket.number}"
+    number, branch = ticket.number, run.names.ticket(ticket.number)
     # The merge gate and the conflict agent run under the lock: the commit the gate saw is the one that lands.
     with run.merging, during("the merge"):
         landing = _land(ticket, slot, run)
@@ -348,27 +354,16 @@ def _work(tickets: list[Ticket], slots: int, run: Run) -> tuple[bool, list[str]]
 
 # ---------------------------------------------------------------- before the first agent: resume and answers
 
-def _pr_branch(state: driver_state.State) -> tuple[str, str]:
-    """(the PR branch, "") or ("", why the run cannot start)."""
-    here = git(".", "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
-    # An interrupted run leaves slot 1 on a ticket branch or detached, so the record names the PR branch.
-    pr = state.read()["run"]["pr_branch"] if state.path.exists() else here
-    if not pr:
-        return "", "the PR worktree is on a detached HEAD: check out the PR branch"
-    if here not in ("", pr) and not here.startswith("ticket/"):
-        return "", f"{state.path} records a run on {pr}, not on {here}: check out {pr}, or remove {OUT}"
-    return pr, ""
-
-
 def _resume_error(number: str, state: driver_state.State) -> str:
     """Check the record of one ticket against git. A ticket that git contradicts goes back to its last verified
     phase; "" or the error that stops the run."""
-    entry, branch = state.read()["tickets"][number], f"ticket/{number}"
+    run, entry = state.read()["run"], state.read()["tickets"][number]
+    branch = Names(run["pr_branch"]).ticket(number)
     if entry["phase"] not in driver_state.PHASES:
         return f"{state.path}: ticket {number} has the unknown phase {entry['phase']!r}"
-    if entry["phase"] == "pending" and git(".", "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode == 0:
+    if entry["phase"] == "pending" and driver_slots.branch_exists(branch):
         return f"branch {branch} exists and {state.path} does not record it: delete or rename the branch"
-    fields, why = driver_state.verified(entry, branch, state.read()["run"]["pr_branch"])
+    fields, why = driver_state.verified(entry, branch, run["pr_branch"])
     if fields:
         state.ticket(number, **fields)
         start = fields["tip"][:7] if fields["tip"] else "the PR tip"
@@ -376,15 +371,12 @@ def _resume_error(number: str, state: driver_state.State) -> str:
     return ""
 
 
-def _resume(tickets: list[Ticket], state: driver_state.State, slots: int, args, kept: dict) -> tuple[str, list[str]]:
-    """Start or resume state.json and make the slots: (the PR branch, the errors that stop the run)."""
-    pr, error = _pr_branch(state)
-    if error:
-        return "", [error]
+def _resume(tickets: list[Ticket], state: driver_state.State, pr: str, slots: int, args, kept: dict) -> list[str]:
+    """Start or resume state.json on the PR branch `pr` and make the slots: the errors that stop the run."""
     state.start(pr, [ticket.number for ticket in tickets])
     driver_final.finish_interrupted_move(state, pr)
     errors = [error for error in (_resume_error(ticket.number, state) for ticket in tickets) if error]
-    return pr, errors or driver_slots.setup(slots, args.prepare, set(kept.values()))
+    return errors or driver_slots.setup(slots, args.prepare, set(kept.values()))
 
 
 def _publish_questions(run: dict) -> str:
@@ -474,10 +466,10 @@ def _exit_code(final: dict, args, end_blocked: bool) -> int:
     return code
 
 
-def _run(tickets: list[Ticket], models: dict[str, list[str]], args, kept: dict[str, int]) -> int:
+def _run(tickets: list[Ticket], models: dict[str, list[str]], args, kept: dict[str, int], pr: str) -> int:
     state = driver_state.State(STATE)
     slots = 1 if args.only else min(args.parallel, len(tickets))
-    pr, errors = _resume(tickets, state, slots, args, kept)
+    errors = _resume(tickets, state, pr, slots, args, kept)
     errors = errors or _apply_answers(state, args)
     for error in errors:
         print(error)
@@ -564,7 +556,7 @@ def _validated(args: argparse.Namespace) -> tuple[list[Ticket], dict[str, list[s
         errors.append("--spec is required: the spec file the prompts point at")
     if args.parallel < 1:
         errors.append("--parallel must be 1 or more")
-    kept = driver_state.kept(json.loads(STATE.read_text())) if STATE.exists() else {}
+    kept = driver_state.kept(driver_state.State(STATE).read()) if STATE.exists() else {}
     errors += _worktree_errors(1 in kept.values())
     models, model_errors = driver_agents.load_models(args.models)
     tickets, ticket_errors = driver_tickets.parse(args.tickets)
@@ -579,16 +571,61 @@ def _print_width(tickets: list[Ticket]) -> None:
     print(f"max frontier width: {driver_tickets.max_frontier_width(tickets)}")
 
 
-def _lock_file(args: argparse.Namespace) -> Path | None:
-    """The file one driver per repository locks: in the git common directory, which every worktree shares and
-    `git status` never reports. None, with each error printed, when the call is not valid."""
+def _run_branch() -> str:
+    """The PR branch the run in this worktree is on: the one state.json records, else the one checked out."""
+    # HEAD first: a driver writes state.json before it moves HEAD, so a HEAD that a run moved has a state.json.
+    here = driver_slots.on_branch(".")
+    return driver_state.State(STATE).read()["run"]["pr_branch"] if STATE.exists() else here
+
+
+def _start_errors(pr: str) -> list[str]:
+    """Under the lock of `pr`, before any check reads a ref: the errors that stop the run, or [].
+
+    The run of this worktree must still be on `pr`, a run that an older driver started gets its new names first,
+    and slot 1 must be on `pr` or where an interrupted run left it: on one of its ticket branches, or detached."""
+    if _run_branch() != pr:
+        return [f"the run in this worktree left {pr} while the driver took its lock: run the driver again"]
+    if errors := driver_legacy.resume(driver_state.State(STATE)):
+        return errors
+    here = driver_slots.on_branch(".")
+    # An older driver named its ticket branches `ticket/NN`, and a branch that the resume does not rename stays so.
+    if here in ("", pr) or here.startswith(Names(pr).ticket("")) or re.fullmatch(r"ticket/\d+", here):
+        return []
+    return [f"{STATE} records a run on {pr}, not on {here}: check out {pr}, or remove {OUT}"]
+
+
+def _common_dir_and_branch(args: argparse.Namespace) -> tuple[Path, str] | None:
+    """(the git common directory, which every worktree shares and `git status` never reports, and the PR branch of
+    the run): what names the lock. None, with each error printed, when the call is not valid."""
     common = git(".", "rev-parse", "--git-common-dir")
     # A first call is validated before the lock, so a wrong call makes no file. After an earlier run the lock comes
     # first: the driver that holds it changes what the validation reads.
     first_call = common.returncode or not OUT.exists()
     if first_call and not _validated(args):
         return None
-    return Path(common.stdout.strip()).resolve() / "implement-spec.lock"
+    if not (pr := _run_branch()):
+        print("the PR worktree is on a detached HEAD: check out the PR branch")
+        return None
+    if pr.startswith("ticket/"):  # a slot of another run: its driver owns the worktree and the branch
+        print(f"the PR worktree is on the ticket branch {pr} of a run: check out the PR branch")
+        return None
+    return Path(common.stdout.strip()).resolve(), pr
+
+
+def _hold(common: Path, pr: str) -> tuple[ExitStack | None, str]:
+    """Take the locks of a run on `pr`: (the stack that holds them until it closes, "") or (None, why another
+    driver stops this one)."""
+    with ExitStack() as stack:
+        lock_file = Names(pr).lock_file(common)
+        if not (held := driver_state.lock(lock_file)):
+            return None, (f"another driver runs on {pr}: it holds the lock {lock_file}. Wait until it ends, then "
+                          "run the driver again.")
+        stack.enter_context(held)
+        older, error = driver_legacy.lock(common)
+        if not older:
+            return None, error
+        stack.enter_context(older)
+        return stack.pop_all(), ""
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -597,15 +634,19 @@ def main(argv: list[str] | None = None) -> int:
         if valid := _validated(args):
             _print_width(valid[0])
         return 0 if valid else 3
-    if not (lock_file := _lock_file(args)):
+    if not (locking := _common_dir_and_branch(args)):
         return 3
-    held = driver_state.lock(lock_file)
+    common, pr = locking
+    held, error = _hold(common, pr)
     if not held:
-        print(f"implement-spec: another driver runs in this repository: it holds the lock {lock_file}. Wait until it "
-              "ends, then run the driver again.")
+        print(f"implement-spec: {error}")
         return 3
     with held:
-        # Only what is read under the lock is trusted: no other driver changes state.json, the slots or the refs.
+        # Only what is read under the lock is trusted: no other driver changes state.json, the slots, the PR branch
+        # or its ticket branches. Drivers on other PR branches touch none of them.
+        if errors := _start_errors(pr):
+            print("".join(f"implement-spec: {error}\n" for error in errors), end="")
+            return 3
         if not (valid := _validated(args)):
             return 3
         tickets, models, kept = valid
@@ -614,7 +655,7 @@ def main(argv: list[str] | None = None) -> int:
             print("".join(error + "\n" for error in errors), end="")
             return 3
         _print_width(tickets)
-        return _run(tickets, models, args, kept)
+        return _run(tickets, models, args, kept, pr)
 
 
 if __name__ == "__main__":

package/skills/implement-spec/driver_final.py

@@ -4,7 +4,7 @@ commits with a scoped review, then stop before the push, or push and open the PR
 
 `run.final` of state.json is the resume contract (`driver_state._final` makes it with every key):
     skipped    why the end-of-run work did not start
-    recovery   the PR tip before the rewrite; the ref RECOVERY holds it. None when origin had the history already
+    recovery   the PR tip before the rewrite; Run.names names its ref. None when origin had the history already
     tidied     the tip the rewrite made, or the tip as the tickets left it when the history is kept
     base, onto the default branch of origin and its tip under the history; with no origin: "" and the start of the run
     commits    {ticket: its commit}
@@ -34,7 +34,6 @@ from driver_slots import git, head
 from driver_state import State
 from driver_tickets import Ticket
 
-RECOVERY = "refs/implement/recovery"
 KIND = "final-finding"
 ROUNDS = 2  # the full review and the scoped one after the fix batch
 # The final review runs through the review-diff skill, which is installed next to this one.
@@ -170,7 +169,8 @@ def _resolve_rebase_conflict(run: Run, env: dict, base: str, onto: str) -> None:
         raise Blocked(f"the conflict agent: {error}" if error else
                       f"the rebase onto {base} conflicts a second time, in {', '.join(again)}")
     # The resolution may not change a locked test: each one is as the recovery point has it.
-    changed = driver_review.locked_changes(".", git(".", "rev-parse", RECOVERY).stdout.strip(), _locked_files(run))
+    before = git(".", "rev-parse", run.names.recovery).stdout.strip()
+    changed = driver_review.locked_changes(".", before, _locked_files(run))
     if error := error or "; ".join(finding["title"] for finding in changed):
         raise Blocked(f"the conflict agent: {error}")
     ledger(f"Rebase: the conflict agent resolved the conflict with {base} in {', '.join(files)} at {head('.')[:7]}.")
@@ -249,7 +249,7 @@ def _rewrite_once(run: Run, tickets: list[Ticket]) -> None:
     final = run.state.read()["run"]["final"]
     if final["tidied"]:
         if not driver_merge.ancestor(final["tidied"], run.tip()):
-            raise Blocked(f"{run.pr} does not hold the tidied tip {final['tidied'][:7]}; {RECOVERY} holds the "
+            raise Blocked(f"{run.pr} does not hold the tidied tip {final['tidied'][:7]}; {run.names.recovery} holds the "
                           "history before the tidy")
         return
     base, onto = _base(run)
@@ -258,9 +258,9 @@ def _rewrite_once(run: Run, tickets: list[Ticket]) -> None:
         _keep_published_history(run, old, base, onto)
         return
     tree = git(".", "rev-parse", f"{old}^{{tree}}").stdout.strip()
-    git(".", "update-ref", "-m", "implement-spec: recovery point", RECOVERY, old)
+    git(".", "update-ref", "-m", "implement-spec: recovery point", run.names.recovery, old)
     ledger(f"Recovery point: {run.pr} was at {old} with the tree {tree} before the rebase and the tidy; "
-           f"{RECOVERY} holds that commit.")
+           f"{run.names.recovery} holds that commit.")
     git(".", "checkout", "-q", "--detach")  # slot 1 is off the branch while the history is made
     try:
         commits = _new_history(run, tickets, old, base, onto)

package/skills/implement-spec/driver_legacy.py

@@ -0,0 +1,92 @@
+"""A run that an older driver started: one lock per repository, ticket branches `ticket/NN` and the recovery ref
+`refs/implement/recovery`.
+
+Every run of a newer driver holds `lock` (driver._hold), so a newer and an older driver never run in one repository
+at the same time. The driver calls `resume` once, after the locks and before any check reads a ref: a run with no
+`schema` in state.json gets the new names of its refs.
+ponytail: delete this module, tests/test_legacy.py and its one line in driver._hold and in driver._start_errors
+once no older driver is left.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import IO
+
+import driver_slots
+import driver_state
+from driver_names import Names
+from driver_run import ledger
+from driver_slots import git
+
+LOCK = "implement-spec.lock"  # in the git common directory: an older driver holds it for its whole run
+RECOVERY = "refs/implement/recovery"
+
+
+def _checked_out_elsewhere(branch: str) -> bool:
+    """True when a worktree that is not this one nor one of its slots has `branch` checked out."""
+    here = Path.cwd().resolve()
+    for block in git(".", "worktree", "list", "--porcelain").stdout.split("\n\n"):
+        lines = block.splitlines()
+        if lines and f"branch refs/heads/{branch}" in lines:
+            where = Path(lines[0].removeprefix("worktree ")).resolve()
+            return where != here and here / ".agent" / "worktrees" not in where.parents
+    return False
+
+
+def _this_runs(entry: dict, legacy: str, start: str) -> bool:
+    """A `ticket/NN` is this run's when it holds the commit the run started from and the tip the run recorded, and
+    no worktree outside this run has it checked out."""
+    if not driver_slots.ancestor(start, legacy) or _checked_out_elsewhere(legacy):
+        return False
+    return not entry["tip"] or driver_slots.ancestor(entry["tip"], legacy)
+
+
+def _branch(entry: dict, number: str, names: Names, start: str) -> str:
+    """Rename one `ticket/NN` of this run: "" or the error."""
+    legacy, new = f"ticket/{number}", names.ticket(number)
+    if entry["phase"] in ("pending", "merged") or not driver_slots.branch_exists(legacy):
+        return ""
+    if driver_slots.branch_exists(new) or not _this_runs(entry, legacy, start):
+        return ""
+    moved = git(".", "branch", "-m", legacy, new)  # git also moves the HEAD of a slot that has the branch
+    if moved.returncode:
+        return f"cannot rename the branch {legacy} of an older driver to {new}: {moved.stderr.strip()}"
+    ledger(f"Ticket {number}: renamed the branch {legacy} of an older driver to {new}.")
+    return ""
+
+
+def _recovery(run: dict, names: Names) -> str:
+    """Move `refs/implement/recovery` to the name of this run when it holds the recovery point that this run
+    recorded: "" or the error."""
+    recorded = run.get("final", {}).get("recovery")
+    if not recorded or git(".", "rev-parse", "-q", "--verify", RECOVERY).stdout.strip() != recorded:
+        return ""
+    # The old ref goes only when the new one holds the commit: a move that stopped half way is finished next time.
+    made = git(".", "update-ref", "-m", "implement-spec: rename", names.recovery, recorded)
+    if made.returncode:
+        return f"cannot move {RECOVERY} of an older driver to {names.recovery}: {made.stderr.strip()}"
+    git(".", "update-ref", "-d", RECOVERY, recorded)
+    ledger(f"Recovery point: moved {RECOVERY} of an older driver to {names.recovery}.")
+    return ""
+
+
+def lock(common_dir: Path) -> tuple[IO | None, str]:
+    """The lock of an older driver, shared: (the held file, "") or (None, the error) while an older driver runs in
+    the repository. Newer drivers hold it together, so they do not stop each other; an older driver holds it alone,
+    so it never runs beside one."""
+    if held := driver_state.lock(common_dir / LOCK, shared=True):
+        return held, ""
+    return None, (f"a driver of an older version runs in this repository: it holds the lock {common_dir / LOCK}. "
+                  "Wait until it ends, then run the driver again.")
+
+
+def resume(state: driver_state.State) -> list[str]:
+    """Give each ref of a run that an older driver started its new name, then mark the run: the errors, or []."""
+    if not state.path.exists() or state.read()["run"].get("schema", 1) >= driver_state.SCHEMA:
+        return []
+    run, names = state.read()["run"], Names(state.read()["run"]["pr_branch"])
+    moves = [_branch(entry, number, names, run["start"]) for number, entry in state.read()["tickets"].items()]
+    if errors := [error for error in [*moves, _recovery(run, names)] if error]:
+        return errors
+    state.update(lambda changed: changed["run"].update(schema=driver_state.SCHEMA))
+    return []

package/skills/implement-spec/driver_merge.py

@@ -8,11 +8,7 @@ from __future__ import annotations
 import os
 import subprocess
 
-from driver_slots import git, names
-
-
-def ancestor(commit: str, of: str) -> bool:
-    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
+from driver_slots import ancestor, git, names
 
 
 def identity(tip: str, slot: str = ".") -> dict[str, str]:

package/skills/implement-spec/driver_names.py

@@ -0,0 +1,32 @@
+"""The names of one run: its ticket branches, its recovery ref and its lock file.
+
+Each name carries the PR branch as one name component, so runs on other PR branches share none of them. One
+component, because git refs are a tree: `ticket/feat/01` and `ticket/feat/01/02` cannot both exist. `%` and `/` are
+escaped, so two PR branches never give the same component: `feat/x` gives `feat%2Fx`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Names:
+    pr: str  # the PR branch
+
+    @property
+    def _key(self) -> str:
+        return self.pr.replace("%", "%25").replace("/", "%2F")
+
+    def ticket(self, number: str) -> str:
+        """The branch of ticket `number`."""
+        return f"ticket/{self._key}/{number}"
+
+    @property
+    def recovery(self) -> str:
+        """The ref that holds the PR tip before the tidy."""
+        return f"refs/implement-spec/{self._key}/recovery"
+
+    def lock_file(self, common_dir: Path) -> Path:
+        """The file one driver per PR branch locks, in the git common directory that every worktree shares."""
+        return common_dir / "implement-spec" / f"{self._key}.lock"

package/skills/implement-spec/driver_review.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import re
 import driver_agents
-from driver_slots import git, head, names
+from driver_slots import git, head, names, on_branch
 from driver_tickets import Ticket
 
 # The correctness pass reads this file of the review-diff skill, which is installed next to this one.
@@ -131,7 +131,7 @@ def restore(slot: str, branch: str, tip: str) -> None:
 
 def disturbed(slot: str, branch: str, tip: str) -> str:
     """"" when the slot is still on `branch` at `tip` with a clean tree, else what the read-only agents left."""
-    if git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip() != branch or head(slot) != tip:
+    if on_branch(slot) != branch or head(slot) != tip:
         return f"the slot is no longer on {branch} at {tip[:7]}"
     left = [line[3:] for line in git(slot, "status", "--porcelain").stdout.splitlines()]
     return f"the tree is not as the review found it: {', '.join(left)}" if left else ""

package/skills/implement-spec/driver_run.py

@@ -24,6 +24,7 @@ import driver_report
 import driver_review
 import driver_slots
 import driver_state
+from driver_names import Names
 from driver_slots import git, names
 
 OUT = Path(".agent/implement")
@@ -88,6 +89,10 @@ class Run:
     asks: dict[str, Ask] = field(default_factory=dict)  # ticket number -> its pending stop
     halted: list[str] = field(default_factory=list)  # why the run starts no other agent; [] while it goes on
 
+    @property
+    def names(self) -> Names:
+        return Names(self.pr)
+
     def tip(self) -> str:
         return git(".", "rev-parse", f"refs/heads/{self.pr}").stdout.strip()
 
@@ -191,8 +196,8 @@ def _restore_if_changed(number: str, slot: str, branch: str, tip: str, runs_agai
 
 def _reset_if_moved(slot: str, branch: str, tip: str) -> str:
     """After an agent: "" when the slot is on `branch` and still holds `tip`; else reset it and say what was wrong."""
-    head = git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
-    if git(slot, "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode:
+    head = driver_slots.on_branch(slot)
+    if not driver_slots.branch_exists(branch):
         problem = f"branch {branch} is missing"
     elif head != branch:
         problem = f"HEAD is on {head or 'a detached commit'} instead of {branch}"

package/skills/implement-spec/driver_slots.py

@@ -22,6 +22,19 @@ def head(slot: str) -> str:
     return git(slot, "rev-parse", "HEAD").stdout.strip()
 
 
+def on_branch(slot: str) -> str:
+    """The branch the slot has checked out; "" when its HEAD is detached."""
+    return git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
+
+
+def ancestor(commit: str, of: str) -> bool:
+    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
+
+
+def branch_exists(branch: str) -> bool:
+    return git(".", "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode == 0
+
+
 def path(number: int) -> str:
     return "." if number == 1 else f".agent/worktrees/slot-{number}"