The cleanup runs pkgmgr branch cleanup --local and offers deletion only for ancestry-merged branches; squash or PR merges stay a dry-run preview. A signed branch whose ref vanished without a pkgmgr delete becomes gone (deleted outside this run, or after an interrupted apply) and is shown apart from deleted and failed; an Unknown --branch answer for a vanished ref repeats the run once without it. Tests run once on unify/skills-20261114 after the merge (operator order 2026-11-14). 🎯 Fix: 88 % 💥 Break: 6 % 💸 Tokens: – ⏱️ Velocity: – 🛡️ Security: 100 % 🏆 Score: 83 🚦 Gate: ⛔ fix 88 % < 90, break 6 % > 5 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
319 lines
14 KiB
Python
319 lines
14 KiB
Python
from __future__ import annotations
|
|
|
|
import json
|
|
import re
|
|
import threading
|
|
from dataclasses import dataclass
|
|
from pathlib import Path
|
|
|
|
from .council import agent
|
|
from .records import iso_epoch
|
|
from .register import ENDED, status_of
|
|
from .signed import signing
|
|
|
|
LABEL_PARTS = 3
|
|
FLOW_LIMIT = 16
|
|
FLOW_REF = re.compile(r"[^\x00-\x20\x7f]{1,255}")
|
|
FLOW_SOURCE = re.compile(r"[a-z][a-z0-9-]{0,31}")
|
|
INVALID = "invalid"
|
|
# renaming it silently stops the tree timer: kvb-orchestrator-tree.service tests this file's age
|
|
TREE_HEARTBEAT = "tree-heartbeat"
|
|
GC_SKILL = "kvb-git-gc"
|
|
GC_COMPOSE_DOWN = ("docker", "compose", "-p", "{project}", "down", "-v", "--remove-orphans")
|
|
LOCAL_PLAN = "local-plan.json"
|
|
|
|
|
|
def flow(item: dict) -> dict | None:
|
|
"""Returns:
|
|
The worktree's pkgmgr merge flow: pull, the sources merged into the
|
|
branch before a gate, and push, the targets the finished branch
|
|
merges into, each capped at FLOW_LIMIT; None when the item names no
|
|
flow, source invalid with empty lists when pkgmgr found the flow
|
|
file broken or the field has the wrong shape.
|
|
"""
|
|
raw = item.get("flow")
|
|
if raw is None:
|
|
return None
|
|
broken = {"pull": [], "push": [], "source": INVALID}
|
|
if not isinstance(raw, dict) or not isinstance(raw.get("source"), str) or not FLOW_SOURCE.fullmatch(raw["source"]) or raw["source"] == INVALID:
|
|
return broken
|
|
lists = [raw.get(side)[:FLOW_LIMIT] if isinstance(raw.get(side), list) else None for side in ("pull", "push")]
|
|
if not all(names is not None and all(isinstance(name, str) and FLOW_REF.fullmatch(name) for name in names) for names in lists):
|
|
return broken
|
|
return {"pull": lists[0], "push": lists[1], "source": raw["source"]}
|
|
|
|
|
|
def work(item: dict, dirty: bool | None) -> list[str]:
|
|
ahead = item["ahead"]
|
|
found = (("dirty", dirty is True), ("unpushed", isinstance(ahead, int) and ahead > 0), ("unmerged", item["state"] == "unmerged"))
|
|
return [reason for reason, hit in found if hit]
|
|
|
|
|
|
def worktree(item: dict) -> dict:
|
|
state = item["worktree_state"]
|
|
unread = state == "changed" and item["staged"] is None
|
|
dirty = None if state == "missing" or unread else state == "changed"
|
|
return {
|
|
"path": item["worktree"],
|
|
"head": item["head"] or "",
|
|
"branch": item["branch"] or "",
|
|
"prunable": state == "missing",
|
|
"dirty": dirty,
|
|
"state": state,
|
|
"staged": item["staged"],
|
|
"unstaged": item["unstaged"],
|
|
"untracked": item["untracked"],
|
|
"locked": item["locked"],
|
|
"flow": flow(item),
|
|
"open_work": work(item, dirty),
|
|
}
|
|
|
|
|
|
def held_by(worktree: str) -> str:
|
|
return f"held by worktree {worktree}: pkgmgr branch cleanup skips it, use branch gc ({GC_SKILL}, pkgmgr gc)"
|
|
|
|
|
|
def kept_by(planned: dict | None, tip: str, upstream_of: str, stale: str) -> str:
|
|
"""Args:
|
|
planned: this branch's item of the `pkgmgr branch cleanup --local`
|
|
dry run beside the tree file, None when it has none.
|
|
tip: the branch's local tip in the tree file.
|
|
upstream_of: a branch of the same dry run whose local upstream this
|
|
branch is, "" for none; pkgmgr's _config_keeps keeps it when the
|
|
host's `--branch` dry run chooses it alone.
|
|
stale: why the repository's dry run is stale, "" when it is fresh.
|
|
|
|
Returns:
|
|
Why the hub offers no delete: a stale dry run, or from that dry run
|
|
what keeps the branch (signing.local_keeps, the predicate the host
|
|
runner refuses by, then the local upstream), or that it has not
|
|
planned this tip yet; "" when it deletes exactly the local branch at
|
|
this tip.
|
|
"""
|
|
if stale:
|
|
return f"pkgmgr branch cleanup --local plan stale: {stale}; use branch gc ({GC_SKILL}, pkgmgr gc)"
|
|
if planned is None or planned.get("local_sha") != tip:
|
|
return f"no pkgmgr branch cleanup --local dry run of {tip[:12]} yet: the tree timer writes {LOCAL_PLAN} within a minute"
|
|
keeps = signing.local_keeps(planned) or (f"kept: local upstream of {upstream_of}" if upstream_of else "")
|
|
return f"pkgmgr branch cleanup --local keeps it: {keeps}; use branch gc ({GC_SKILL}, pkgmgr gc)" if keeps else ""
|
|
|
|
|
|
def local_upstreams(items: list[dict]) -> dict[str, str]:
|
|
"""Args:
|
|
items: one repository's items of the `--local` dry run, each with
|
|
its `%(upstream:short)` as upstream.
|
|
|
|
Returns:
|
|
Each branch that is the local upstream of another branch there, with
|
|
the first such branch by name, as pkgmgr's _config_keeps names it.
|
|
"""
|
|
names = {item["branch"] for item in items}
|
|
found: dict[str, str] = {}
|
|
for item in sorted(items, key=lambda entry: entry["branch"]):
|
|
upstream = str(item.get("upstream") or "")
|
|
parent = upstream if upstream in names else upstream.removeprefix("heads/")
|
|
if parent in names and parent != item["branch"]:
|
|
found.setdefault(parent, item["branch"])
|
|
return found
|
|
|
|
|
|
def dry_run(item: dict, kept: str) -> list[str]:
|
|
"""Args:
|
|
item: one tree item.
|
|
kept: kept_by() for it, "" when the hub offers its delete.
|
|
|
|
Returns:
|
|
What the runner's `pkgmgr branch cleanup` does for one tree item,
|
|
read from the gc plan the tree file carries: it deletes the local
|
|
branch and never touches a worktree, Compose stack or volume; a
|
|
remote branch stays, the runner refuses a plan that deletes one. A
|
|
branch held by a worktree it skips, and one the `--local` dry run
|
|
keeps or has not planned it does not delete; their lines name what
|
|
branch gc would do instead, its `docker compose down -v` deleting
|
|
the stack's volumes.
|
|
"""
|
|
tip = (item["local_sha"] or item["head"] or "")[:12]
|
|
merged = f", merged by {item['merged_by']}" if item["merged_by"] else ""
|
|
lines = [f"{item['branch']} @ {tip}: {item['state']}{merged}"]
|
|
if item["worktree"]:
|
|
lines.append(held_by(item["worktree"]))
|
|
lines.append(f"branch gc would remove the worktree {item['worktree']} and the local branch {item['branch']}")
|
|
lines += [f"branch gc would run {' '.join(GC_COMPOSE_DOWN).format(project=name)}, which deletes the volumes of {name}" for name in item["compose_projects"]]
|
|
lines += [f"branch gc would remove the image {name}" for name in item["images"]]
|
|
return lines
|
|
if kept:
|
|
lines.append(kept)
|
|
lines += [f"branch gc would delete the local branch {item['branch']}" if action == "local-branch" else f"branch gc would delete {action}" for action in item["actions"]]
|
|
return lines
|
|
for action in item["actions"]:
|
|
if action == "local-branch":
|
|
lines.append(f"deletes the local branch {item['branch']}")
|
|
elif action.startswith("remote"):
|
|
lines.append(f"stays: {action} (local only; the host refuses a plan that deletes it)")
|
|
else:
|
|
lines.append(action)
|
|
return lines
|
|
|
|
|
|
def branch(item: dict, path: str, default: object, planned: dict | None, upstream_of: str, stale: str) -> dict:
|
|
"""Args:
|
|
item: one tree item with a branch.
|
|
path: its repository's path.
|
|
default: the repository's default branch.
|
|
planned: the branch's item of the `--local` dry run, None without.
|
|
upstream_of: as kept_by() takes it.
|
|
stale: as kept_by() takes it.
|
|
"""
|
|
remote = next(iter(item["remotes"].values()), "")
|
|
head = item["local_sha"] or item["head"] or remote
|
|
held = held_by(item["worktree"]) if item["worktree"] and item["state"] == "merged-clean" else ""
|
|
candidate = item["state"] == "merged-clean" and bool(item["local_sha"]) and not item["worktree"]
|
|
kept = kept_by(planned, item["local_sha"], upstream_of, stale) if candidate else ""
|
|
open_to_delete = candidate and not item["skip"] and not kept
|
|
return {
|
|
"held": held,
|
|
"kept": kept,
|
|
"token_free": signing.token_free(planned, default) if candidate and planned is not None else False,
|
|
"name": item["branch"],
|
|
"head": head,
|
|
"upstream": item["upstream"] or "",
|
|
"ahead": item["ahead"] or 0,
|
|
"behind": item["behind"] or 0,
|
|
"gone": item["gone"],
|
|
"state": item["state"],
|
|
"merged_by": item["merged_by"],
|
|
"merged_into": item["merged_into"],
|
|
"skip": item["skip"],
|
|
"reason": item["reason"],
|
|
"plan": dry_run(item, kept),
|
|
"cleanup": signing.cleanup_item(path, item["branch"], item["worktree"] or "", item["local_sha"]) if open_to_delete else None,
|
|
"worktrees": [worktree(item)] if item["worktree"] else [],
|
|
}
|
|
|
|
|
|
def repo(entry: dict, local: dict[tuple[str, str], tuple[dict, str]], stale: dict[str, str]) -> dict:
|
|
items = entry["items"]
|
|
return {
|
|
**{key: value for key, value in entry.items() if key != "items"},
|
|
"name": "/".join(Path(entry["path"]).parts[-LABEL_PARTS:]),
|
|
"branches": [branch(item, entry["path"], entry.get("default"), *local.get((entry["path"], item["branch"]), (None, "")), stale.get(entry["path"], "")) for item in items if item["branch"]],
|
|
"detached": [worktree(item) for item in items if item["detached"]],
|
|
}
|
|
|
|
|
|
def local_plan(path: Path) -> tuple[dict[tuple[str, str], tuple[dict, str]], dict[str, str]]:
|
|
"""Returns:
|
|
Every item of the `pkgmgr branch cleanup --local` dry run that
|
|
client/local_plan.py writes at path, keyed by repository path and
|
|
branch, with the branch whose local upstream it is (local_upstreams,
|
|
"" for none); and each repository whose dry run is stale, with why.
|
|
Both are empty when the file is missing or unreadable, so the hub
|
|
offers no delete.
|
|
"""
|
|
try:
|
|
data = json.loads(path.read_text(encoding="utf-8"))
|
|
found, stale = {}, {}
|
|
for repository in data["repos"]:
|
|
items = [item for item in repository["items"] if isinstance(item, dict) and isinstance(item.get("branch"), str)]
|
|
upstreams = local_upstreams(items)
|
|
found.update({(repository["repo"], item["branch"]): (item, upstreams.get(item["branch"], "")) for item in items})
|
|
if repository.get("stale"):
|
|
stale[repository["repo"]] = str(repository["stale"])[:200]
|
|
return found, stale
|
|
except (OSError, ValueError, KeyError, TypeError, AttributeError):
|
|
return {}, {}
|
|
|
|
|
|
def offered(scan: dict, ready: bool) -> list[dict]:
|
|
"""Args:
|
|
scan: the tree.
|
|
ready: whether pkgmgr holds the GitHub token.
|
|
|
|
Returns:
|
|
The cleanup items deletable now: every one with the token, without
|
|
it only those of token-free branches.
|
|
"""
|
|
return [entry["cleanup"] for repository in scan["repos"] for entry in repository["branches"] if entry["cleanup"] is not None and (ready or entry["token_free"])]
|
|
|
|
|
|
def read_tree(path: Path) -> dict:
|
|
try:
|
|
data = json.loads(path.read_text(encoding="utf-8"))
|
|
local, stale = local_plan(path.with_name(LOCAL_PLAN))
|
|
return {
|
|
"repos": sorted((repo(entry, local, stale) for entry in data["repos"]), key=lambda entry: entry["name"]),
|
|
"scanned": iso_epoch(data["generated_at"]),
|
|
"delete_ready": data["delete_ready"],
|
|
"delete_reason": data["delete_reason"],
|
|
}
|
|
except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
|
|
return {"repos": [], "scanned": None, "error": f"pkgmgr tree file {path} unreadable: {error}"}
|
|
|
|
|
|
def inside(path: str, folder: str) -> bool:
|
|
return path == folder or path.startswith(f"{folder.rstrip('/')}/")
|
|
|
|
|
|
def owns(row: dict, path: str, name: str) -> bool:
|
|
workdir = row.get("workdir")
|
|
if isinstance(workdir, str):
|
|
return workdir.startswith("/") and inside(workdir, path)
|
|
return row.get("branch") == name
|
|
|
|
|
|
def assign(scan: dict, tasks: dict[str, dict], claims: list[dict], reviews: list[dict]) -> dict:
|
|
current = {task: row for task, row in tasks.items() if status_of(row) not in ENDED}
|
|
holders: dict[str, set[str]] = {}
|
|
for task, row in current.items():
|
|
names = {agent(row.get("worker"))} | {claim["agent"] for claim in claims if claim["office"] == task}
|
|
holders[task] = {name for name in names if name}
|
|
latest: dict[str, dict] = {}
|
|
for review in reviews:
|
|
latest[review["worktree"]] = {"status": review["status"], "gate": review.get("gate", ""), "title": review["title"]}
|
|
repos = []
|
|
for entry in scan["repos"]:
|
|
branches = []
|
|
for item in entry["branches"]:
|
|
trees = []
|
|
for tree in item["worktrees"]:
|
|
workers = set()
|
|
held = sorted(task for task, row in current.items() if owns(row, tree["path"], item["name"]))
|
|
for task in held:
|
|
workers |= holders[task]
|
|
open_work = [*tree["open_work"], "task"] if held else tree["open_work"]
|
|
trees.append({**tree, "workers": sorted(workers, key=str.lower), "review": latest.get(tree["path"]), "tasks": held, "open_work": open_work})
|
|
branches.append({**item, "worktrees": trees})
|
|
repos.append({**entry, "branches": branches, "detached": [{**tree, "workers": [], "review": latest.get(tree["path"]), "tasks": []} for tree in entry["detached"]]})
|
|
return {**scan, "repos": repos}
|
|
|
|
|
|
@dataclass
|
|
class Tree:
|
|
file: Path
|
|
heartbeat: Path
|
|
lock: threading.Lock
|
|
cached: dict | None
|
|
stamp: tuple[tuple[int, int], tuple[int, int] | None] | None
|
|
|
|
def beat(self) -> None:
|
|
self.heartbeat.touch()
|
|
|
|
def get(self) -> dict:
|
|
with self.lock:
|
|
try:
|
|
info = self.file.stat()
|
|
except OSError as error:
|
|
return {"repos": [], "scanned": None, "error": (
|
|
f"no pkgmgr tree file at {self.file}: {error.strerror}. The tree timer runs `pkgmgr branch tree`, which the installed pkgmgr "
|
|
"lacks until a release ships it: release pkgmgr and install it, then the timer writes the file within a minute."
|
|
)}
|
|
try:
|
|
planned = self.file.with_name(LOCAL_PLAN).stat()
|
|
plan_stamp = (planned.st_mtime_ns, planned.st_size)
|
|
except OSError:
|
|
plan_stamp = None
|
|
stamp = ((info.st_mtime_ns, info.st_size), plan_stamp)
|
|
if self.cached is None or stamp != self.stamp:
|
|
self.cached, self.stamp = read_tree(self.file), stamp
|
|
return self.cached
|