2026-11-06 08:28:04 +00:00
from __future__ import annotations
2026-11-07 06:51:49 +00:00
import json
2026-11-07 23:43:26 +00:00
import re
2026-11-06 08:28:04 +00:00
import threading
from dataclasses import dataclass
from pathlib import Path
from .council import agent
2026-11-07 06:51:49 +00:00
from .records import iso_epoch
2026-11-06 08:28:04 +00:00
from .register import ENDED , status_of
2026-11-07 15:03:14 +00:00
from .signed import signing
2026-11-06 08:28:04 +00:00
2026-11-07 06:51:49 +00:00
LABEL_PARTS = 3
2026-11-07 23:43:26 +00:00
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"
2026-11-07 06:51:49 +00:00
# renaming it silently stops the tree timer: kvb-orchestrator-tree.service tests this file's age
TREE_HEARTBEAT = "tree-heartbeat"
2026-11-12 16:28:10 +00:00
GC_SKILL = "kvb-git-gc"
2026-11-12 16:15:14 +00:00
GC_COMPOSE_DOWN = ( "docker" , "compose" , "-p" , " {project} " , "down" , "-v" , "--remove-orphans" )
2026-11-14 21:22:28 +00:00
LOCAL_PLAN = "local-plan.json"
2026-11-06 08:28:04 +00:00
2026-11-07 23:43:26 +00:00
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 ]
2026-11-07 06:51:49 +00:00
def worktree ( item : dict ) -> dict :
state = item [ "worktree_state" ]
unread = state == "changed" and item [ "staged" ] is None
2026-11-07 23:43:26 +00:00
dirty = None if state == "missing" or unread else state == "changed"
2026-11-07 06:51:49 +00:00
return {
"path" : item [ "worktree" ],
"head" : item [ "head" ] or "" ,
"branch" : item [ "branch" ] or "" ,
"prunable" : state == "missing" ,
2026-11-07 23:43:26 +00:00
"dirty" : dirty ,
2026-11-07 06:51:49 +00:00
"state" : state ,
"staged" : item [ "staged" ],
"unstaged" : item [ "unstaged" ],
"untracked" : item [ "untracked" ],
"locked" : item [ "locked" ],
2026-11-07 23:43:26 +00:00
"flow" : flow ( item ),
"open_work" : work ( item , dirty ),
2026-11-07 06:51:49 +00:00
}
2026-11-12 16:15:14 +00:00
def held_by ( worktree : str ) -> str :
return f "held by worktree { worktree } : pkgmgr branch cleanup skips it, use branch gc ( { GC_SKILL } , pkgmgr gc)"
2026-11-14 21:22:28 +00:00
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:
2026-11-12 16:15:14 +00:00
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
2026-11-14 21:22:28 +00:00
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.
2026-11-07 15:03:14 +00:00
"""
tip = ( item [ "local_sha" ] or item [ "head" ] or "" )[: 12 ]
2026-11-08 17:26:51 +00:00
merged = f ", merged by { item [ 'merged_by' ] } " if item [ "merged_by" ] else ""
2026-11-07 15:03:14 +00:00
lines = [ f " { item [ 'branch' ] } @ { tip } : { item [ 'state' ] }{ merged } " ]
2026-11-12 16:15:14 +00:00
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
2026-11-14 21:22:28 +00:00
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
2026-11-07 15:03:14 +00:00
for action in item [ "actions" ]:
2026-11-12 16:15:14 +00:00
if action == "local-branch" :
2026-11-08 17:26:51 +00:00
lines . append ( f "deletes the local branch { item [ 'branch' ] } " )
2026-11-07 15:03:14 +00:00
elif action . startswith ( "remote" ):
2026-11-12 16:15:14 +00:00
lines . append ( f "stays: { action } (local only; the host refuses a plan that deletes it)" )
2026-11-07 15:03:14 +00:00
else :
lines . append ( action )
return lines
2026-11-14 21:22:28 +00:00
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.
"""
2026-11-07 06:51:49 +00:00
remote = next ( iter ( item [ "remotes" ] . values ()), "" )
2026-11-07 15:03:14 +00:00
head = item [ "local_sha" ] or item [ "head" ] or remote
2026-11-12 16:15:14 +00:00
held = held_by ( item [ "worktree" ]) if item [ "worktree" ] and item [ "state" ] == "merged-clean" else ""
2026-11-14 21:22:28 +00:00
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
2026-11-07 06:51:49 +00:00
return {
2026-11-12 16:15:14 +00:00
"held" : held ,
2026-11-14 21:22:28 +00:00
"kept" : kept ,
"token_free" : signing . token_free ( planned , default ) if candidate and planned is not None else False ,
2026-11-07 06:51:49 +00:00
"name" : item [ "branch" ],
2026-11-07 15:03:14 +00:00
"head" : head ,
2026-11-07 06:51:49 +00:00
"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" ],
2026-11-07 15:03:14 +00:00
"merged_into" : item [ "merged_into" ],
2026-11-07 06:51:49 +00:00
"skip" : item [ "skip" ],
"reason" : item [ "reason" ],
2026-11-14 21:22:28 +00:00
"plan" : dry_run ( item , kept ),
2026-11-07 15:03:14 +00:00
"cleanup" : signing . cleanup_item ( path , item [ "branch" ], item [ "worktree" ] or "" , item [ "local_sha" ]) if open_to_delete else None ,
2026-11-07 06:51:49 +00:00
"worktrees" : [ worktree ( item )] if item [ "worktree" ] else [],
}
2026-11-14 21:22:28 +00:00
def repo ( entry : dict , local : dict [ tuple [ str , str ], tuple [ dict , str ]], stale : dict [ str , str ]) -> dict :
2026-11-07 06:51:49 +00:00
items = entry [ "items" ]
return {
** { key : value for key , value in entry . items () if key != "items" },
"name" : "/" . join ( Path ( entry [ "path" ]) . parts [ - LABEL_PARTS :]),
2026-11-14 21:22:28 +00:00
"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" ]],
2026-11-07 06:51:49 +00:00
"detached" : [ worktree ( item ) for item in items if item [ "detached" ]],
}
2026-11-14 21:22:28 +00:00
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 {}, {}
2026-11-12 16:15:14 +00:00
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" ])]
2026-11-07 15:03:14 +00:00
2026-11-07 06:51:49 +00:00
def read_tree ( path : Path ) -> dict :
2026-11-06 08:28:04 +00:00
try :
2026-11-07 06:51:49 +00:00
data = json . loads ( path . read_text ( encoding = "utf-8" ))
2026-11-14 21:22:28 +00:00
local , stale = local_plan ( path . with_name ( LOCAL_PLAN ))
2026-11-07 06:51:49 +00:00
return {
2026-11-14 21:22:28 +00:00
"repos" : sorted (( repo ( entry , local , stale ) for entry in data [ "repos" ]), key = lambda entry : entry [ "name" ]),
2026-11-07 06:51:49 +00:00
"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 } " }
2026-11-06 08:28:04 +00:00
def inside ( path : str , folder : str ) -> bool :
return path == folder or path . startswith ( f " { folder . rstrip ( '/' ) } /" )
2026-11-07 15:03:14 +00:00
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
2026-11-06 08:28:04 +00:00
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 = []
2026-11-07 06:51:49 +00:00
for item in entry [ "branches" ]:
2026-11-06 08:28:04 +00:00
trees = []
2026-11-07 06:51:49 +00:00
for tree in item [ "worktrees" ]:
2026-11-06 08:28:04 +00:00
workers = set ()
2026-11-07 23:43:26 +00:00
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 })
2026-11-07 06:51:49 +00:00
branches . append ({ ** item , "worktrees" : trees })
2026-11-07 23:43:26 +00:00
repos . append ({ ** entry , "branches" : branches , "detached" : [{ ** tree , "workers" : [], "review" : latest . get ( tree [ "path" ]), "tasks" : []} for tree in entry [ "detached" ]]})
2026-11-07 06:51:49 +00:00
return { ** scan , "repos" : repos }
2026-11-06 08:28:04 +00:00
@dataclass
class Tree :
2026-11-07 06:51:49 +00:00
file : Path
heartbeat : Path
2026-11-06 08:28:04 +00:00
lock : threading . Lock
cached : dict | None
2026-11-14 21:22:28 +00:00
stamp : tuple [ tuple [ int , int ], tuple [ int , int ] | None ] | None
2026-11-07 06:51:49 +00:00
def beat ( self ) -> None :
self . heartbeat . touch ()
2026-11-06 08:28:04 +00:00
def get ( self ) -> dict :
with self . lock :
2026-11-07 06:51:49 +00:00
try :
info = self . file . stat ()
except OSError as error :
2026-11-08 13:37:02 +00:00
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."
)}
2026-11-14 21:22:28 +00:00
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 )
2026-11-07 06:51:49 +00:00
if self . cached is None or stamp != self . stamp :
self . cached , self . stamp = read_tree ( self . file ), stamp
2026-11-06 08:28:04 +00:00
return self . cached