diff --git a/docs/requirements/001-agent-orchestrator.md b/docs/requirements/001-agent-orchestrator.md index 3288a39..7181b94 100644 --- a/docs/requirements/001-agent-orchestrator.md +++ b/docs/requirements/001-agent-orchestrator.md @@ -125,6 +125,33 @@ from three views down to any agent, branch or artefact. worktree holds is skipped and left to `kvb-git-gc`, and no worktree, Compose stack or volume is touched. Rejected: per Scope, also removing the worktree and running `compose down` without `-v`. + - **Amended by the operator 2026-11-14**: only a branch whose local tip + the `pkgmgr branch cleanup --local` dry run deletes is offered: the tree + timer writes that dry run (`--json`, per known repository within a + budget, again only when its refs, HEAD, config, reftable or worktree + heads changed, the file rewritten after each repository) as + `local-plan.json` beside the tree file; a repository whose dry run + failed, timed out or was killed keeps its old plan marked stale, and + the hub offers nothing there and says why. The hub and the host decide + with one predicate on its item for that tip (`merged-clean`, no skip + reason, exactly the action `local-branch`); the hub also keeps the + local upstream of another branch, as pkgmgr keeps it for the host's + dry run of that branch alone. A branch that dry run keeps, such as one + merged by pull request (`pr#N`), squash or patch whose local tip is no + ancestor of the default branch, shows its dry run without a Delete + button, with the skip reason of the dry run and branch gc + (`kvb-git-gc`, `pkgmgr gc`) as the way to remove it, and the host + refuses its signed delete. The host runs one dry run and one apply per + repository and job; an item pkgmgr deleted at another merged tip than + the signed one is done with a warning, one the apply keeps is failed + with pkgmgr's skip reason, and only a branch pkgmgr reports deleted is + done: a signed branch whose ref is gone otherwise is `gone` ("deleted + outside this run" when pkgmgr answered without deleting it, "gone + after an interrupted apply" when the apply ended without output), + rewrites the tree and shows apart from deleted and failed. A dry run + or apply that names gone branches unknown runs once more without + them. Rejected: deciding by + `merged_by` alone, and offering a Delete the host then refuses. 22. **Organisation update**: a new skill `kvb-org-update` tells every agent and client which skills changed and how to use them, as one `newsletter` per update; phase 1 announces the radio change through it. @@ -641,23 +668,34 @@ flowchart TD - [x] The Artifacts Tree marks every branch and worktree with icons for merged (with what merged it), clean, uncommitted changes (with counts), unpushed commits, gone upstream, locked, stale and protected. -- [x] A `merged-clean` item without a gc skip reason shows a delete button, - and the Tree header shows "Delete all merged"; both are disabled, - with the reason as tooltip, while `delete_ready` is false. +- [x] A `merged-clean` item without a gc skip reason whose local tip the + `pkgmgr branch cleanup --local` dry run in `local-plan.json` deletes + shows a delete button, also when its remote tip was merged by squash or + patch, and the Tree header shows "Delete all merged"; both are + disabled, with the reason as tooltip, while `delete_ready` is false. +- [x] A `merged-clean` item that dry run keeps, or that it has not planned + at this tip yet, shows no delete button in its Tree row, its popup or + the delete sheet; its dry run says `pkgmgr branch cleanup --local` keeps + it with the skip reason of that dry run and names branch gc + (`kvb-git-gc`, `pkgmgr gc`) as the way to remove it, and the unit + refuses its signed delete by the same predicate. - [x] A click shows the gc dry-run lines of exactly the chosen items; "Delete" requires the operator signature through `/api/sign`. - [x] The orchestrator writes the signed job (repository, branch, worktree and tip sha per item, no command) into a host-mounted job directory and holds no git, token or key. -- [ ] A systemd user path unit verifies the signature on the host and runs - `pkgmgr branch cleanup --apply --local` (the `--local` release is - pending in pkgmgr) for exactly the signed items, matched exactly, never - as a pattern; it removes the local branch, never a remote branch, a - worktree, a Compose stack or a volume, and needs no SSH key; a branch a - worktree holds is skipped and left to `kvb-git-gc`. +- [x] A systemd user path unit verifies the signature on the host and runs + `pkgmgr branch cleanup --apply --local` (pkgmgr 2.5.0) for exactly the + signed items, matched exactly, never as a pattern; it removes the local + branch, never a remote branch, a worktree, a Compose stack or a volume, + and needs no SSH key; a branch a worktree holds is skipped and left to + `kvb-git-gc`. - [x] The unit refuses, and changes nothing for, an item whose tip or state differs from the signed one, an unknown repository, a non-`merged-clean` - item and a job with a bad or missing signature, and reports why. + item and a job with a bad or missing signature, and reports why; an + item pkgmgr deleted at another merged tip than the signed one is done + with a warning, and one it did not delete there is failed, or `gone`, + never done, when its ref is gone. - [x] The unit writes each item's result back and rewrites the tree file; the Tree shows the result. diff --git a/docs/requirements/003-operator-workbench.md b/docs/requirements/003-operator-workbench.md index 94e3d80..a71bdbb 100644 --- a/docs/requirements/003-operator-workbench.md +++ b/docs/requirements/003-operator-workbench.md @@ -50,9 +50,13 @@ changed and what it costs, and a gate means something again. labelled stale and counted apart. Rejected: count everything, only drop operator rows. 10. **Clean all merged**: dry run, one passkey, signed job. Local branches - merged by ancestry and without a remote branch need no token; remote - branches and squash-merge candidates need the GitHub token, stored through - an operator row. Rejected: wait for the token, ancestry for remotes. + merged by ancestry and without a remote branch need no token; the local + branch of one with a remote branch needs the GitHub token, stored through + an operator row. A branch the `pkgmgr branch cleanup --local` dry run + keeps, such as a squash or patch merge whose local tip is no ancestor of + the default branch, is never deleted here, token or not: its dry run says + why and names branch gc (`kvb-git-gc`, `pkgmgr gc`) (operator + 2026-11-14). Rejected: wait for the token, ancestry for remotes. 11. **Ancestry**: Artifacts and Agents get a family tree (generations top down) in the slot of today's Tree view. A branch may have several parents; parents are recorded at creation (post-checkout hook), older branches are @@ -222,8 +226,10 @@ flowchart TD - [x] "Clean all merged" shows the gc dry run of every `merged-clean` item; one passkey runs the signed job. - [ ] Without a GitHub token, local branches merged by ancestry into the - default branch and without a remote branch can be deleted; the others - show "token needed", and an operator row stores the token. + default branch and without a remote branch can be deleted; the other + branches the `--local` dry run deletes show "token needed", and an + operator row stores the token. A branch that dry run keeps shows no + delete and no "token needed", with or without the token. - [ ] Artifacts and Agents show Ancestry in the Tree slot: generations top down, several parents per node; a derived parent edge is dashed. - [ ] Dragging a branch onto another stages a parent edge, applied with the diff --git a/orchestrator/client/cleanup.py b/orchestrator/client/cleanup.py index 433c23e..772866c 100755 --- a/orchestrator/client/cleanup.py +++ b/orchestrator/client/cleanup.py @@ -15,18 +15,28 @@ Returns: Runs once over every job in --jobs, as the operator on the host: per item it verifies the operator's passkey signature over repository, branch, - worktree and tip, then in the repository runs `pkgmgr branch cleanup - --json --branch ` as a dry run and, only when that plan names - exactly this branch as merged-clean without skip reason at the signed - tip and worktree and deletes no remote branch, `pkgmgr branch cleanup - --apply --json --branch `. While the tree file says pkgmgr has no GitHub token - (delete_ready false), only a branch the dry run shows merged by ancestry - into the default branch and without a remote branch is deleted; the - others are refused with "token needed". Every other item is refused and - nothing changes for it. An applied item is done only when pkgmgr's - result for it is done; a skipped one or one without result is failed - with pkgmgr's reason. Writes each item's result, rewrites the tree file - after a deletion and removes the job. The exit code is 0. + worktree and tip; then per repository it runs one `pkgmgr branch cleanup + --local --json --branch ...` dry run over its signed branches and + one `pkgmgr branch cleanup --apply --local --json --branch ...` + over those the plan names exactly at the signed tip and worktree and + deletes exactly the local branch of (signing.local_keeps, the predicate + the hub offers by); pkgmgr deletes only a local branch whose planned tip + is an ancestor of the default branch, by update-ref with that tip. While + the tree file says pkgmgr has no GitHub token (delete_ready false), only + a branch the dry run shows merged by ancestry into the default branch + and without a remote branch is deleted; the others are refused with + "token needed". Every other item is refused and nothing changes for it. + An applied item is done only when pkgmgr's result for it is done, with a + warning when pkgmgr deleted it at another merged tip than the signed + one; one the apply keeps is failed with pkgmgr's skip reason. A signed + branch pkgmgr did not report deleted whose ref is gone is gone, never + done: "deleted outside this run" when pkgmgr answered without deleting + it (a failed result, no result, or "Unknown --branch"), "gone after an + interrupted apply" when the apply ended without JSON; a present one is + failed. When a dry run or apply answers "Unknown --branch" for gone + branches, it runs once more without them. + Writes each item's result, rewrites the tree file after a deletion or a + gone branch and removes the job. The exit code is 0. """ from __future__ import annotations @@ -49,7 +59,10 @@ UNSAFE = re.compile(r"[*?\[\]\\\s\x00-\x1f\x7f]|^-|\.\.|@\{") OUTPUT_LIMIT = 16 << 10 TIMEOUT = 600 DONE = "done" -REMOTE_ACTION = "remote-branch:" +GONE = "gone" +DELETED_OUTSIDE = "deleted outside this run" +GONE_INTERRUPTED = "gone after an interrupted apply" +UNKNOWN = re.compile(r"^Unknown --branch: (.*)$", re.MULTILINE) TOKEN_NEEDED = "token needed: without the GitHub token only a local branch merged by ancestry into the default branch and without a remote branch is deleted" # the cwd is a repository agents can write: its config may name hooks, and # pkgmgr releases before 4c8b137 run git branch -D without scan mode @@ -84,23 +97,57 @@ def tree_facts(tree: Path) -> tuple[dict[str, str], bool]: return {}, False -def run(pkgmgr: Path, argv: list[str], cwd: str) -> tuple[int, str, str]: +def run(pkgmgr: Path, argv: list[str], cwd: str, timeout: int) -> tuple[int, str, str]: + """Args: + pkgmgr: the pkgmgr executable. + argv: its arguments. + cwd: the repository it runs in, without hooks or fsmonitor. + timeout: seconds before pkgmgr is killed. + + Returns: + Exit code, stdout and the tail of stderr; 127 with the error when + pkgmgr could not start or was killed at the timeout. + """ try: - done = subprocess.run([str(pkgmgr), *argv], cwd=cwd, env={**os.environ, **git_overrides()}, stdin=subprocess.DEVNULL, capture_output=True, text=True, errors="replace", timeout=TIMEOUT, check=False) + done = subprocess.run([str(pkgmgr), *argv], cwd=cwd, env={**os.environ, **git_overrides()}, stdin=subprocess.DEVNULL, capture_output=True, text=True, errors="replace", timeout=timeout, check=False) except (OSError, subprocess.TimeoutExpired) as error: return 127, "", str(error) return done.returncode, done.stdout, done.stderr[-OUTPUT_LIMIT:] -def plan_argv(branch: str, apply: bool) -> list[str]: +def branch_tip(repository: str, branch: str) -> str | None: + """Returns: + The local branch's tip as git reads it in the repository and no + parent of it, "" when the repository has no such branch, None when + git cannot tell. + """ + env = {**os.environ, **git_overrides(), "GIT_CEILING_DIRECTORIES": str(Path(repository).parent)} + try: + done = subprocess.run(["git", "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=repository, env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=60, check=False) + except (OSError, subprocess.TimeoutExpired): + return None + if done.returncode == 0 and TIP.fullmatch(done.stdout.strip()): + return done.stdout.strip() + return "" if done.returncode == 1 and not done.stdout.strip() else None + + +def unknown(stderr: str) -> set[str]: + """Returns: + The branch names pkgmgr's "Unknown --branch: a, b" line names. + """ + return {name for found in UNKNOWN.findall(stderr) for name in found.split(", ")} + + +def plan_argv(branches: list[str], apply: bool) -> list[str]: """Args: - branch: the exact branch name. + branches: the exact branch names of one repository. apply: execute the plan instead of the dry run. Returns: - The `pkgmgr branch cleanup` arguments for this branch's plan in JSON. + The `pkgmgr branch cleanup --local` arguments for these branches' + plan in JSON: local branches only, no forge token, no remote delete. """ - return ["branch", "cleanup", *(["--apply"] if apply else []), "--json", "--branch", branch] + return ["branch", "cleanup", *(["--apply"] if apply else []), "--local", "--json", *[part for branch in branches for part in ("--branch", branch)]] def plan_items(stdout: str) -> list[dict] | None: @@ -126,20 +173,85 @@ def shaped(item: object) -> bool: return item["repository"].startswith("/") and bool(TIP.fullmatch(item["tip"])) and (item["worktree"] == "" or item["worktree"].startswith("/")) -def mismatch(entry: dict, item: dict) -> str | None: - if entry.get("state") != "merged-clean": - return f"state is {entry.get('state')}, not merged-clean" - if entry.get("skip"): - return f"gc skip reason: {entry['skip']}" +def tip_changed(entry: dict, item: dict) -> str | None: tip = entry.get("local_sha") or entry.get("head") - if tip != item["tip"]: - return f"tip changed: signed {item['tip'][:12]}, now {str(tip)[:12]}" + return None if tip == item["tip"] else f"tip changed: signed {item['tip'][:12]}, now {str(tip)[:12]}" + + +def mismatch(entry: dict, item: dict) -> str | None: + changed = tip_changed(entry, item) + if changed: + return changed if (entry.get("worktree") or "") != item["worktree"]: return f"worktree changed: signed {item['worktree'] or 'none'}, now {entry.get('worktree') or 'none'}" - remote = [str(action) for action in entry.get("actions") or [] if str(action).startswith(REMOTE_ACTION)] - if remote: - return f"the plan also deletes {', '.join(remote)[:200]}; a signed delete is local only" - return None + kept = signing.local_keeps(entry) + return f"pkgmgr branch cleanup --local keeps it: {kept}" if kept else None + + +def refused(item: dict, reason: str) -> dict: + return {**item, "status": "refused", "reason": reason} + + +def applied_result(item: dict, applied: list[dict] | None, code: int, stderr: str) -> dict: + """Args: + item: one signed item the apply chose. + applied: every item `--apply` printed for its repository, None when + it printed no JSON. + code: the apply's exit code, 1 when any of its items failed. + stderr: the apply's error output. + + Returns: + The item done only when pkgmgr's result for it is done, with a + warning as reason when pkgmgr deleted it at another tip than the + signed one, which update-ref only does for the tip pkgmgr planned as + merged; failed with pkgmgr's skip reason when the apply kept it. + Without a done result its ref decides: gone is gone, "gone after an + interrupted apply" when the apply printed no JSON and named no + unknown branch, else "deleted outside this run"; present is failed + with pkgmgr's reason. + """ + mine = next((entry for entry in applied or [] if entry.get("branch") == item["branch"]), {}) + outcome = mine.get("result") + moved = tip_changed(mine, item) if mine else None + if isinstance(outcome, str) and outcome.split(";")[0] == DONE: + warning = f"deleted at another merged tip than the signed dry run: {moved}" if moved else "" + return {**item, "status": DONE, "reason": warning, "code": code, "applied": [mine]} + if mine.get("skip") and not outcome: + reason = f"pkgmgr branch cleanup --local keeps it: {mine['skip']}" + elif moved: + reason = f"the apply planned another tip than the signed dry run: {moved}" + elif not (isinstance(outcome, str) and outcome.startswith("skipped")) and branch_tip(item["repository"], item["branch"]) == "": + why = GONE_INTERRUPTED if applied is None and not unknown(stderr) else DELETED_OUTSIDE + return {**item, "status": GONE, "reason": why, "code": code, "applied": [mine] if mine else []} + else: + reason = outcome if isinstance(outcome, str) and outcome else stderr.strip()[-500:] or f"pkgmgr reported no result for {item['branch']}" + return {**item, "status": "failed", "reason": reason[:500], "code": code, "applied": [mine] if mine else []} + + +def screened(items: list[dict], plan: list[dict], default: str, ready: bool) -> dict[str, dict]: + """Args: + items: admitted items of one repository, each branch once. + plan: the items of their dry run. + default: the repository's default branch. + ready: whether pkgmgr holds the GitHub token. + + Returns: + The refusal by branch of each item the plan does not delete exactly + at its signed tip and worktree, or without the token not token-free; + of every item when the plan names other branches too. + """ + others = sorted({str(entry.get("branch")) for entry in plan} - {item["branch"] for item in items}) + if others: + return {item["branch"]: refused(item, f"the dry run names other branches too, a pattern match: {', '.join(others)[:500]}") for item in items} + refusals = {} + for item in items: + mine = [entry for entry in plan if entry.get("branch") == item["branch"]] + reason = mismatch(mine[0], item) if len(mine) == 1 else f"the dry run names {len(mine)} items for {item['branch']}" + if reason is None and not ready and not signing.token_free(mine[0], default): + reason = TOKEN_NEEDED + if reason is not None: + refusals[item["branch"]] = refused(item, reason) + return refusals class Cleanup: @@ -148,53 +260,78 @@ class Cleanup: self.tree = tree self.pkgmgr = pkgmgr - def item(self, item: dict, proof: object, known: dict[str, str], ready: bool, now: float) -> dict: + def admitted(self, item: dict, proof: object, known: dict[str, str], now: float) -> str | None: """Args: item: one signed item with repository, branch, worktree and tip. proof: the job's {"payload", "assertion"}. - known: the repositories the tree file says pkgmgr knows, each - with its default branch. - ready: whether pkgmgr holds the GitHub token; without it only a - branch signing.token_free() accepts in the dry run is deleted. + known: the repositories the tree file says pkgmgr knows. now: the current time in epoch seconds. Returns: - The item with status done, refused or failed and the reason; - refused items changed nothing, failed ones are those pkgmgr did - not report done. + Why the item is refused before any dry run; None when the + operator's signature lists it, pkgmgr knows its repository and + its branch is an exact name. """ - def refused(reason: str) -> dict: - return {**item, "status": "refused", "reason": reason} - try: verifier.check(proof, signing.cleanup_item(item["repository"], item["branch"], item["worktree"], item["tip"]), "", self.trust, now) except (signing.Refused, OSError) as error: - return refused(f"no valid operator signature: {error}") + return f"no valid operator signature: {error}" if item["repository"] not in known or not Path(item["repository"]).is_dir(): - return refused("unknown repository: pkgmgr does not list it") + return "unknown repository: pkgmgr does not list it" if UNSAFE.search(item["branch"]) or not item["branch"]: - return refused("the branch name holds pattern or option characters; only an exact branch name is deleted") - code, stdout, stderr = run(self.pkgmgr, plan_argv(item["branch"], False), item["repository"]) + return "the branch name holds pattern or option characters; only an exact branch name is deleted" + return None + + def attempt(self, items: list[dict], apply: bool, results: dict[str, dict]) -> tuple[list[dict], int, str, str]: + """Args: + items: items of one repository to plan or apply. + apply: run the apply instead of the dry run. + results: gets, by branch, each item that run names unknown whose + ref is gone, as gone "deleted outside this run". + + Returns: + The items of the last run with its exit code, stdout and stderr; + after an "Unknown --branch" for gone branches the run repeats + once without them. + """ + location = items[0]["repository"] + code, stdout, stderr = run(self.pkgmgr, plan_argv([item["branch"] for item in items], apply), location, TIMEOUT) + named = unknown(stderr) if code != 0 else set() + gone = [item for item in items if item["branch"] in named and branch_tip(location, item["branch"]) == ""] + if gone: + results.update({item["branch"]: {**item, "status": GONE, "reason": DELETED_OUTSIDE, "code": code} for item in gone}) + items = [item for item in items if item not in gone] + if items: + code, stdout, stderr = run(self.pkgmgr, plan_argv([item["branch"] for item in items], apply), location, TIMEOUT) + return items, code, stdout, stderr + + def repository(self, items: list[dict], default: str, ready: bool) -> list[dict]: + """Args: + items: admitted items of one repository, each branch once. + default: the repository's default branch. + ready: whether pkgmgr holds the GitHub token; without it only a + branch signing.token_free() accepts in the dry run is deleted. + + Returns: + Each item with status done, gone, refused or failed and the + reason, from one dry run over all of them and one apply over + those the dry run plans to delete at the signed tip and worktree, + each repeated once without the branches it names unknown and + gone; refused items changed nothing. + """ + results: dict[str, dict] = {} + planned, code, stdout, stderr = self.attempt(items, False, results) plan = plan_items(stdout) if code == 0 else None if plan is None: - return refused(f"the dry run failed ({code}): {stderr.strip()[-500:]}") - others = sorted({str(entry.get("branch")) for entry in plan} - {item["branch"]}) - if others: - return refused(f"the dry run names other branches too, a pattern match: {', '.join(others)[:500]}") - if len(plan) != 1: - return refused(f"the dry run names {len(plan)} items for {item['branch']}") - reason = mismatch(plan[0], item) - if reason: - return refused(reason) - if not ready and not signing.token_free(plan[0], known[item["repository"]]): - return refused(TOKEN_NEEDED) - code, stdout, stderr = run(self.pkgmgr, plan_argv(item["branch"], True), item["repository"]) - applied = plan_items(stdout) or [] - outcome = next((entry.get("result") for entry in applied if entry.get("branch") == item["branch"]), None) - if code == 0 and isinstance(outcome, str) and outcome.split(";")[0] == DONE: - return {**item, "status": "done", "reason": "", "code": code, "applied": applied} - reason = outcome if isinstance(outcome, str) and outcome else stderr.strip()[-500:] or f"pkgmgr reported no result for {item['branch']}" - return {**item, "status": "failed", "reason": reason[:500], "code": code, "applied": applied} + results.update({item["branch"]: refused(item, f"the dry run failed ({code}): {stderr.strip()[-500:]}") for item in planned}) + else: + results.update(screened(planned, plan, default, ready)) + chosen = [item for item in planned if item["branch"] not in results] + if chosen: + applying, code, stdout, stderr = self.attempt(chosen, True, results) + applied = plan_items(stdout) + results.update({item["branch"]: applied_result(item, applied, code, stderr) for item in applying}) + return [results[item["branch"]] for item in items] def job(self, folder: int, path: Path, now: float) -> dict: try: @@ -205,10 +342,24 @@ class Cleanup: if not isinstance(items, list) or not items or not all(map(shaped, items)) or job.get("id") != path.stem: return {"id": path.stem, "finished": now, "items": [], "error": "malformed job: refused, nothing deleted"} known, ready = tree_facts(self.tree) - results = [self.item(item, job.get("proof"), known, ready, now) for item in items] + results: list[dict | None] = [None] * len(items) + groups: dict[str, list[int]] = {} + seen: set[tuple[str, str]] = set() + for index, item in enumerate(items): + reason = self.admitted(item, job.get("proof"), known, now) + if reason is None and (item["repository"], item["branch"]) in seen: + reason = "the job lists this branch twice" + if reason is not None: + results[index] = refused(item, reason) + continue + seen.add((item["repository"], item["branch"])) + groups.setdefault(item["repository"], []).append(index) + for location, indexes in groups.items(): + for index, outcome in zip(indexes, self.repository([items[index] for index in indexes], known[location], ready)): + results[index] = outcome result = {"id": path.stem, "finished": time.time(), "items": results} - if any(entry["status"] == "done" for entry in results): - code, _, stderr = run(self.pkgmgr, ["branch", "tree", "--format", "json", "--output", str(self.tree)], str(self.tree.parent)) + if any(entry["status"] in (DONE, GONE) for entry in results): + code, _, stderr = run(self.pkgmgr, ["branch", "tree", "--format", "json", "--output", str(self.tree)], str(self.tree.parent), TIMEOUT) result["tree"] = {"code": code, "error": stderr.strip()[-500:]} return result diff --git a/orchestrator/client/local_plan.py b/orchestrator/client/local_plan.py new file mode 100755 index 0000000..4b43178 --- /dev/null +++ b/orchestrator/client/local_plan.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +"""Args: + --tree: the tree file `pkgmgr branch tree` writes; the plan goes beside + it as local-plan.json, in the directory the orchestrator mounts + read-only. + --pkgmgr: the pkgmgr executable built from a signed tag. + --budget: seconds one repository's dry run may take, well below the + tree unit's TimeoutStartSec. + +Returns: + Keeps local-plan.json beside the tree file: the dry run of `pkgmgr + branch cleanup --local --json` of every repository the tree file says + pkgmgr knows, run in it as the cleanup runner runs its dry run + (cleanup.run: no repository hook or fsmonitor), named by its real path. + A repository whose refs, HEAD, config, reftable and worktree heads + (fingerprint) are unchanged since its last attempt is not planned + again. Before each dry run the file is rewritten atomically with that + repository marked stale ("replan started