alissa-tools-github-revloop 0.31.14__tar.gz → 0.31.16__tar.gz

{alissa_tools_github_revloop-0.31.14/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.31.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.31.14
+Version: 0.31.16
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa/tools/github/revloop/__main__.py

@@ -16,6 +16,10 @@ from .config import (
     FLEET_VITALS_ENV,
     HUB_ADD,
     HUB_SKIP,
+    JANITOR_ENABLED_ENV,
+    JANITOR_GRACE_MINUTES_ENV,
+    JANITOR_INTERVAL_MINUTES_ENV,
+    JANITOR_WARN_PCT_ENV,
     LOOP_EVENTS_ENV,
     ON_MISSING_CREATE,
     ON_MISSING_SKIP,
@@ -280,6 +284,45 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_false",
         help="do not push fleet vitals even if the config enables it",
     )
+    janitor = over.add_mutually_exclusive_group()
+    janitor.add_argument(
+        "--janitor",
+        dest="janitor_enabled",
+        action="store_true",
+        default=None,
+        help="remove each hub's stale main/.review-scratch-* and REVIEW-* "
+        "folders that no live session or open round holds, prune the "
+        "worktree records, and warn on a full volume (the default). "
+        f"Overridden by ${JANITOR_ENABLED_ENV}",
+    )
+    janitor.add_argument(
+        "--no-janitor",
+        dest="janitor_enabled",
+        action="store_false",
+        help="never sweep the workspace, even if the config enables it",
+    )
+    over.add_argument(
+        "--janitor-grace-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how old (by mtime) a scratch folder or REVIEW- checkout must be "
+        "before the janitor may remove it (default: 1440). "
+        f"Overridden by ${JANITOR_GRACE_MINUTES_ENV}",
+    )
+    over.add_argument(
+        "--janitor-interval-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how often the janitor sweeps, at the end of a pass; 0 = every "
+        f"pass (default: 10). Overridden by ${JANITOR_INTERVAL_MINUTES_ENV}",
+    )
+    over.add_argument(
+        "--janitor-warn-pct",
+        type=int,
+        metavar="PERCENT",
+        help="workspace volume usage at or above which a sweep logs a "
+        f"WARNING; 0 = never (default: 80). Overridden by ${JANITOR_WARN_PCT_ENV}",
+    )
     over.add_argument(
         "--alissa-endpoint",
         dest="alissa_endpoint",
@@ -336,6 +379,10 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "task_list_bow_id": args.task_list_bow_id,
         "loop_events_enabled": args.loop_events_enabled,
         "fleet_vitals_enabled": args.fleet_vitals_enabled,
+        "janitor_enabled": args.janitor_enabled,
+        "janitor_grace_minutes": args.janitor_grace_minutes,
+        "janitor_interval_minutes": args.janitor_interval_minutes,
+        "janitor_warn_pct": args.janitor_warn_pct,
         "alissa_endpoint": args.alissa_endpoint,
         "dry_run": args.dry_run,
     }
@@ -422,6 +469,14 @@ def main(argv: list[str] | None = None) -> int:
         config = resolve_config(args)
         log.info("workspace: %s", config.workspace_root)
         log.info("repos_source: %s", config.repos_source)
+        log.info(
+            "janitor: %s (grace %d min, every %s, warn at %s)",
+            "on" if config.janitor_enabled else "off",
+            config.janitor_grace_minutes,
+            f"{config.janitor_interval_minutes} min"
+            if config.janitor_interval_minutes else "pass",
+            f"{config.janitor_warn_pct}%" if config.janitor_warn_pct else "never",
+        )
         config = resolve_feed_authority(config)
 
         watcher = ReviewWatcher(config)

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa/tools/github/revloop/config.py

@@ -206,6 +206,10 @@ CONFIG_KEYS = (
     "prompt_kill_minutes",
     "prompt_max_answers",
     "waiting_dir",
+    "janitor_enabled",
+    "janitor_grace_minutes",
+    "janitor_interval_minutes",
+    "janitor_warn_pct",
     "alissa_endpoint",
     "dry_run",
 )
@@ -233,6 +237,14 @@ REPOS_SOURCE_ENV = "ALISSA_REVIEW_REPOS_SOURCE"
 BOWS_REFRESH_POLLS_ENV = "ALISSA_REVIEW_BOWS_REFRESH_POLLS"
 BOW_OWNERS_ENV = "ALISSA_REVIEW_BOW_OWNERS"
 
+# The workspace janitor's four rails (issue #167). Same precedence and the
+# same blank-falls-through rule as the bows rails, so a container can tune
+# (or switch off) the janitor without a file edit on its volume.
+JANITOR_ENABLED_ENV = "ALISSA_REVIEW_JANITOR_ENABLED"
+JANITOR_GRACE_MINUTES_ENV = "ALISSA_REVIEW_JANITOR_GRACE_MINUTES"
+JANITOR_INTERVAL_MINUTES_ENV = "ALISSA_REVIEW_JANITOR_INTERVAL_MINUTES"
+JANITOR_WARN_PCT_ENV = "ALISSA_REVIEW_JANITOR_WARN_PCT"
+
 # The plan directive's two allowlists (issue #148; genloop design §6.1, D12).
 # A PR gets the PLAN directive only when all four signals hold, and two of
 # them are fleet configuration: the repository is one of `plan_repos` and the
@@ -408,6 +420,36 @@ def env_bows_refresh_polls(
         ) from None
 
 
+def _env_int(name: str, what: str, environ: "Mapping[str, str] | None") -> "int | None":
+    """One integer env rail, or None when unset/blank. A non-integer raises,
+    naming the variable -- the startup phase turns that into `config error`."""
+    raw = _env_text(name, environ)
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        raise ValueError(f"{name} must be an integer {what}, got {raw!r}") from None
+
+
+def env_janitor(environ: "Mapping[str, str] | None" = None) -> "dict[str, Any]":
+    """The janitor keys the environment sets (issue #167), as config-key ->
+    value; a key whose variable is unset or blank is absent."""
+    out: "dict[str, Any]" = {}
+    enabled = _env_bool(JANITOR_ENABLED_ENV, environ)
+    if enabled is not None:
+        out["janitor_enabled"] = enabled
+    for key, name, what in (
+        ("janitor_grace_minutes", JANITOR_GRACE_MINUTES_ENV, "number of minutes"),
+        ("janitor_interval_minutes", JANITOR_INTERVAL_MINUTES_ENV, "number of minutes"),
+        ("janitor_warn_pct", JANITOR_WARN_PCT_ENV, "percentage"),
+    ):
+        value = _env_int(name, what, environ)
+        if value is not None:
+            out[key] = value
+    return out
+
+
 def env_bow_owners(environ: "Mapping[str, str] | None" = None) -> "str | None":
     """`ALISSA_REVIEW_BOW_OWNERS` verbatim, or None when unset/blank. The
     `|`/`,` splitting and the actor-id check happen in `normalize_bow_owners`,
@@ -663,6 +705,23 @@ DEFAULT_VERDICT_COOLDOWN_SECONDS = 120
 DEFAULT_REVIEW_TASK_MISS_TTL_POLLS = 10
 
 
+# -- the workspace janitor (issue #167) ---------------------------------------
+#
+# How old a `.review-scratch-*` or `REVIEW-*` folder must be (by mtime) before
+# the janitor may remove it. A day: far past any round's life (the stale-round
+# window is 90 minutes), so the janitor only ever takes what every round that
+# could want it has long finished with -- and the live-session / open-round
+# guard holds anything a slow round is still using regardless.
+DEFAULT_JANITOR_GRACE_MINUTES = 24 * 60
+
+# How often the janitor sweeps, at the end of a pass. 0 = every pass.
+DEFAULT_JANITOR_INTERVAL_MINUTES = 10
+
+# The workspace volume's used percentage at or above which a sweep logs one
+# WARNING. Devloop's threshold; 0 = never warn.
+DEFAULT_JANITOR_WARN_PCT = 80
+
+
 # -- the product-stability guard (issue #105) ---------------------------------
 #
 # How many consecutive `request_changes` rounds must move NOTHING outside
@@ -978,6 +1037,18 @@ class Config:
     # writes the same value here so the daemon looks where the hooks wrote.
     waiting_dir: str = DEFAULT_WAITING_DIR
 
+    # The workspace janitor (issue #167; janitor.py): every
+    # `janitor_interval_minutes` (0 = every pass), at the end of a pass, remove
+    # each hub's `main/.review-scratch-*` and `REVIEW-*` folders older than
+    # `janitor_grace_minutes` that no live session or open ledger round holds,
+    # prune `.source`'s worktree records, and WARN once when the workspace
+    # volume is at or above `janitor_warn_pct` (0 = never). ON by default: the
+    # disk it reclaims fills a shared volume within weeks without it.
+    janitor_enabled: bool = True
+    janitor_grace_minutes: int = DEFAULT_JANITOR_GRACE_MINUTES
+    janitor_interval_minutes: int = DEFAULT_JANITOR_INTERVAL_MINUTES
+    janitor_warn_pct: int = DEFAULT_JANITOR_WARN_PCT
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -1112,7 +1183,7 @@ class Config:
 
         `environ` is the fourth layer and applies to the env-backed keys
         (`task_list_bow_id`, `loop_events_enabled`, `fleet_vitals_enabled`,
-        `repos_source`, `bows_refresh_polls`, `bow_owners`); it wins over both of the others
+        `repos_source`, `bows_refresh_polls`, `bow_owners`, the `janitor_*` keys); it wins over both of the others
         (see the module docstring). Defaults to the real environment, so
         callers that do not care pass nothing.
         """
@@ -1187,6 +1258,8 @@ class Config:
         env_owners = env_bow_owners(environ)
         if env_owners is not None:
             raw["bow_owners"] = env_owners
+        # The janitor's rails (issue #167), same layer, same reason.
+        raw.update(env_janitor(environ))
         # The plan allowlists (issue #148), same rail, same reason.
         env_plan_repos = env_plan_list(PLAN_REPOS_ENV, environ)
         if env_plan_repos is not None:
@@ -1439,6 +1512,31 @@ class Config:
         if not waiting_dir:
             raise ValueError("waiting_dir must be a non-empty path")
 
+        janitor_grace = int(
+            raw.get("janitor_grace_minutes", cls.janitor_grace_minutes)
+        )
+        if janitor_grace < 1:
+            # No 0-means-off here: `janitor_enabled` is the off switch, and a
+            # zero grace would make a scratch folder removable the minute a
+            # guard misses it.
+            raise ValueError(
+                f"janitor_grace_minutes must be >= 1, got {janitor_grace}"
+            )
+        janitor_interval = int(
+            raw.get("janitor_interval_minutes", cls.janitor_interval_minutes)
+        )
+        if janitor_interval < 0:
+            raise ValueError(
+                f"janitor_interval_minutes must be >= 0 (0 = every pass), "
+                f"got {janitor_interval}"
+            )
+        janitor_warn = int(raw.get("janitor_warn_pct", cls.janitor_warn_pct))
+        if not 0 <= janitor_warn <= 100:
+            raise ValueError(
+                f"janitor_warn_pct must be between 0 and 100 (0 = never warn), "
+                f"got {janitor_warn}"
+            )
+
         state_path = raw.get("state_path")
         return cls(
             workspace_root=Path(workspace_root),
@@ -1477,6 +1575,10 @@ class Config:
             prompt_kill_minutes=prompt_kill,
             prompt_max_answers=prompt_answers,
             waiting_dir=waiting_dir,
+            janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
+            janitor_grace_minutes=janitor_grace,
+            janitor_interval_minutes=janitor_interval,
+            janitor_warn_pct=janitor_warn,
             alissa_endpoint=endpoint,
             dry_run=bool(raw.get("dry_run", False)),
         )

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa/tools/github/revloop/fleet_vitals.py

@@ -86,6 +86,7 @@ from .alissa_client import (
     AlissaError,
 )
 from .config import REPOS_BOWS, Config
+from .janitor import disk_used_pct as volume_used_pct
 from .proc import CommandError, run as proc_run
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
@@ -117,7 +118,10 @@ VITALS_FAILED = "failed"
 # The blocks Studio's schema gained after the base contract, each in its own
 # lane: `idle` (seat parking L3) and `config` (provisioner L5). A strict 400
 # naming one of them is an old Studio, not a bad snapshot.
-OPTIONAL_BLOCKS = ("idle", "config")
+#
+# `diskUsedPct` (issue #167) joins them: the workspace volume's used percent,
+# which Studio's schema may not carry yet.
+OPTIONAL_BLOCKS = ("idle", "config", "diskUsedPct")
 
 # How long a snapshot leaves an optional block out after Studio refused it as
 # an unknown key, before it offers the block again. An hour: one extra POST
@@ -296,6 +300,7 @@ def build_snapshot(
     repos: "tuple[str, ...]" = (),
     now: "int | float | None" = None,
     config: "Mapping | None" = None,
+    disk_used_pct: "float | None" = None,
 ) -> dict:
     """The contract body for this pass, off the console's builders.
 
@@ -314,6 +319,9 @@ def build_snapshot(
 
     `config` is the seat's `config_block`, or None to leave the key out (the
     console's push, which has no derived answer to give).
+
+    `diskUsedPct` (issue #167) is the workspace volume's used percent, null
+    when it could not be read.
     """
     stamp = time.time() if now is None else now
     snaps = sources.snapshots(DURATION_POINTS)
@@ -365,6 +373,7 @@ def build_snapshot(
         "queueDepth": _int_or_none(queue_depth),
         "kpis": None,
         "inbox": inbox,
+        "diskUsedPct": disk_used_pct,
         "idle": idle,
     }
     if config is not None:
@@ -519,6 +528,7 @@ class FleetVitalsPusher:
             repos=self.config.repos,
             now=self._clock(),
             config=self._config(),
+            disk_used_pct=volume_used_pct(self.config.workspace_root),
         ))
 
     def _config(self) -> "Mapping | None":

alissa_tools_github_revloop-0.31.16/src/main/alissa/tools/github/revloop/janitor.py

@@ -0,0 +1,373 @@
+"""The workspace janitor: reclaim the disk review rounds leave behind (issue #167).
+
+A reviewer seat is read-only (CR6) and never deletes: `_REVIEWER_RULE` in
+loop.py tells every session to write its scratch files under its own checkout
+and LEAVE them. Two kinds of folder accumulate under each repo hub that way,
+and nothing removed either before this module:
+
+* `<hub>/main/.review-scratch-pr<N>-r<round>/` -- a round's pr.diff, envelope,
+  payload files and, often, a `wt/` git worktree (off `<hub>/.source`) with
+  its own `node_modules`: 250-950 MB apiece. On 2026-10-12 the Alissa fleet's
+  shared volume held 169 of them, 27 GB of a 46 GB volume.
+* `<hub>/REVIEW-<task ref>/` -- the throwaway checkout the review skill lets a
+  reviewer create beside `main/` when it must run code (`trust.
+  review_checkout_name`). Another ~5 GB on the same day.
+
+Modeled on devloop's janitor.py, but smaller, because what it removes is
+smaller in kind: a reviewer's folders hold no unpushed work by construction
+(the seat never pushes and never commits for keeps), so there is no holdout
+policy and no branch to delete -- only a folder that is old, and that no live
+session and no open ledger round still holds. The HOLD is the caller's
+(`loop.ReviewWatcher._janitor_guard`, which owns the roster and the ledger);
+this module states what a folder is, whether a `Guard` holds it, and removes
+it.
+
+Three properties everything here is written around:
+
+* **Only the two shapes, only where they are made.** A scratch folder is a
+  `.review-scratch-*` DIRECT child of `<hub>/main`, a review checkout a
+  `REVIEW-*` direct child of the hub; symlinks are never candidates. Nothing
+  else under a hub -- `main/`'s own files, `.source`, a task worktree, an
+  operator's clone -- is ever considered, so it is never at risk.
+* **Old AND unheld.** Age is the newest mtime of the folder and its direct
+  children (so a round that writes a fresh file into an old folder renews it),
+  and the grace is a day by default. A held folder is kept whatever its age.
+* **Nothing raises past its own concern.** A folder that vanishes mid-sweep,
+  an unreadable hub, a failed removal: logged and skipped, because this runs
+  at the end of a poll pass that must complete.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable
+
+from .alissa import session_repo_slug
+from .proc import CommandError, run
+from .trust import REVIEW_CHECKOUT_PREFIX
+
+log = logging.getLogger(__name__)
+
+# The scratch folder a reviewer writes under its spawn cwd (`<hub>/main`).
+SCRATCH_PREFIX = ".review-scratch-"
+
+# What a scratch folder's name says about its round: `pr<N>` and, usually,
+# `-r<round>`. Prefix-matched after SCRATCH_PREFIX, so a suffix a session
+# appended (`-2`, `.old`) still names its PR. A name that does not parse
+# names no PR, and is held whenever anything in its hub is (see Guard).
+_SCRATCH_PR_RE = re.compile(r"pr(?P<number>\d+)(?:-r(?P<round>\d+))?")
+
+# The hub's bare repository, which every worktree (`main/`, a REVIEW-
+# checkout, a scratch folder's `wt/`) points into. Its presence is what makes
+# a workspace child a hub.
+SOURCE_DIR = ".source"
+
+KIND_SCRATCH = "scratch"
+KIND_REVIEW = "review-checkout"
+
+Runner = Callable[..., str]
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One folder the janitor may remove: its path, which hub it is under,
+    what kind it is, and what its name says it belongs to -- the PR number for
+    a scratch folder (None when the name does not parse), the task ref for a
+    review checkout."""
+
+    path: Path
+    hub: Path
+    kind: str
+    number: "int | None" = None
+    task_ref: "str | None" = None
+
+    @property
+    def hub_slug(self) -> str:
+        """The hub's repo as a session name carries it (`session_repo_slug`),
+        so a hub, a ledger row and a session name compare on one key."""
+        return session_repo_slug(self.hub.name)
+
+
+@dataclass
+class Guard:
+    """What the live roster and the open ledger rounds hold, per hub.
+
+    Keyed by the repo SLUG (`session_repo_slug` of the repo name) -- the one
+    form a hub directory, a ledger row and a session name all reduce to. Two
+    repos sharing a name under different owners share a slug, which only ever
+    holds MORE than needed. The key None means "every hub": a skill-shaped
+    `review-pr-<n>` session names no repo, and holds its PR number anywhere.
+
+    A round whose review-task ref is unknown cannot be mapped to a single
+    REVIEW- checkout, so it holds every checkout in its hub (`all_checkouts`).
+    """
+
+    numbers: "dict[str | None, set[int]]" = field(default_factory=dict)
+    tasks: "dict[str | None, set[str]]" = field(default_factory=dict)
+    all_checkouts: "set[str | None]" = field(default_factory=set)
+
+    def hold(
+        self, repo: "str | None", number: int, task_ref: "str | None" = None
+    ) -> None:
+        """Hold PR `number` of `repo` (`owner/name`, a bare name, or a
+        session-name slug; None = any hub) and the checkout its task names."""
+        slug = None if repo is None else session_repo_slug(repo.rpartition("/")[2])
+        self.numbers.setdefault(slug, set()).add(int(number))
+        ref = (task_ref or "").strip()
+        if ref:
+            self.tasks.setdefault(slug, set()).add(ref)
+        else:
+            self.all_checkouts.add(slug)
+
+    def _in(self, table: "dict[str | None, set]", slug: str, value: object) -> bool:
+        return value in table.get(slug, ()) or value in table.get(None, ())
+
+    def _any(self, slug: str) -> bool:
+        return bool(self.numbers.get(slug) or self.numbers.get(None))
+
+    def holds(self, candidate: Candidate) -> "str | None":
+        """Why `candidate` must stay, or None when nothing holds it."""
+        slug = candidate.hub_slug
+        if candidate.kind == KIND_SCRATCH:
+            if candidate.number is None:
+                return "unnamed scratch in a hub with a live round" if self._any(slug) else None
+            if self._in(self.numbers, slug, candidate.number):
+                return f"PR #{candidate.number} has a live session or open round"
+            return None
+        if slug in self.all_checkouts or None in self.all_checkouts:
+            return "a live round in this hub names no review task"
+        if candidate.task_ref and self._in(self.tasks, slug, candidate.task_ref):
+            return f"{candidate.task_ref} has a live session or open round"
+        return None
+
+
+@dataclass
+class SweepResult:
+    """What one sweep did. `removed` and `would_remove` carry (path, bytes);
+    `held` and `failed` carry (path, reason)."""
+
+    hubs: int = 0
+    removed: "list[tuple[Path, int]]" = field(default_factory=list)
+    would_remove: "list[tuple[Path, int]]" = field(default_factory=list)
+    held: "list[tuple[Path, str]]" = field(default_factory=list)
+    fresh: int = 0
+    failed: "list[tuple[Path, str]]" = field(default_factory=list)
+    pruned: int = 0
+
+    @property
+    def freed(self) -> int:
+        return sum(size for _, size in self.removed)
+
+
+def discover_hubs(workspace_root: "Path | str") -> "list[Path]":
+    """Every worktree hub directly under the workspace root: a non-symlink
+    directory holding a `.source` directory. Read off the disk rather than the
+    allowlist, so a hub whose repo left the allowlist (or a static `repos: []`
+    deployment, which names none) is still swept."""
+    root = Path(workspace_root)
+    try:
+        children = sorted(root.iterdir(), key=lambda p: p.name)
+    except OSError as exc:
+        log.warning("janitor: cannot list workspace %s (%s) — no sweep", root, exc)
+        return []
+    hubs = []
+    for child in children:
+        try:
+            if child.is_symlink() or not child.is_dir():
+                continue
+            source = child / SOURCE_DIR
+            if source.is_dir() and not source.is_symlink():
+                hubs.append(child)
+        except OSError:
+            continue
+    return hubs
+
+
+def _dirs(parent: Path, prefix: str) -> "list[Path]":
+    """Non-symlink directories directly under `parent` whose name starts
+    with `prefix`, sorted; empty when `parent` cannot be listed."""
+    try:
+        entries = sorted(parent.iterdir(), key=lambda p: p.name)
+    except OSError:
+        return []
+    found = []
+    for entry in entries:
+        if not entry.name.startswith(prefix) or entry.name == prefix:
+            continue
+        try:
+            if entry.is_symlink() or not entry.is_dir():
+                continue
+        except OSError:
+            continue
+        found.append(entry)
+    return found
+
+
+def scan_hub(hub: Path) -> "list[Candidate]":
+    """The janitor's candidates in one hub: `main/.review-scratch-*` and
+    `REVIEW-*`, direct children only, never a walk."""
+    found = []
+    for path in _dirs(hub / "main", SCRATCH_PREFIX):
+        match = _SCRATCH_PR_RE.match(path.name[len(SCRATCH_PREFIX):])
+        found.append(Candidate(
+            path=path, hub=hub, kind=KIND_SCRATCH,
+            number=int(match["number"]) if match else None,
+        ))
+    for path in _dirs(hub, REVIEW_CHECKOUT_PREFIX):
+        found.append(Candidate(
+            path=path, hub=hub, kind=KIND_REVIEW,
+            task_ref=path.name[len(REVIEW_CHECKOUT_PREFIX):],
+        ))
+    return found
+
+
+def newest_mtime(path: Path) -> "float | None":
+    """The newest mtime of `path` and its direct children (lstat, so a
+    symlink's target is never read), or None when `path` cannot be read.
+    One level, not a walk: a round writing into its folder touches the
+    folder or a direct child, and a `node_modules` walk every sweep is the
+    cost this avoids."""
+    try:
+        newest = path.lstat().st_mtime
+    except OSError:
+        return None
+    try:
+        with os.scandir(path) as entries:
+            for entry in entries:
+                try:
+                    newest = max(newest, entry.stat(follow_symlinks=False).st_mtime)
+                except OSError:
+                    continue
+    except OSError:
+        pass
+    return newest
+
+
+def dir_bytes(path: "Path | str") -> int:
+    """Bytes allocated under `path` (st_blocks, the figure `du` reports and a
+    removal frees), following no symlinks. Iterative, and every per-entry
+    error is skipped -- devloop's `dir_size` walk, counting blocks."""
+    total = 0
+    stack = [os.fspath(path)]
+    while stack:
+        current = stack.pop()
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            stack.append(entry.path)
+                        st = entry.stat(follow_symlinks=False)
+                        blocks = getattr(st, "st_blocks", None)
+                        total += blocks * 512 if blocks is not None else st.st_size
+                    except OSError:
+                        continue
+        except OSError:
+            continue
+    return total
+
+
+def human(size: "int | float") -> str:
+    """Bytes as a short binary-unit string (`1.4 GiB`), as `du -h` prints."""
+    value = float(size)
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if abs(value) < 1024.0:
+            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024.0
+    return f"{value:.1f} TiB"
+
+
+def disk_used_pct(path: "Path | str") -> "float | None":
+    """Used percent of the volume holding `path` (one statvfs, rounded to a
+    tenth), or None when it cannot be read."""
+    try:
+        usage = shutil.disk_usage(os.fspath(path))
+    except OSError:
+        return None
+    if not usage.total:
+        return None
+    return round(100.0 * usage.used / usage.total, 1)
+
+
+def _contained(candidate: Candidate) -> bool:
+    """The containment rule, re-asserted at the removal site: the folder is
+    a direct child of its hub (review checkout) or of `<hub>/main` (scratch),
+    both resolved, and not a symlink."""
+    parent = candidate.hub / "main" if candidate.kind == KIND_SCRATCH else candidate.hub
+    try:
+        if candidate.path.is_symlink():
+            return False
+        return candidate.path.resolve().parent == parent.resolve()
+    except OSError:
+        return False
+
+
+def prune_worktrees(hub: Path, runner: Runner = run) -> None:
+    """`git worktree prune` in the hub's `.source`, as this process's user
+    (the seat's own): drops the records of worktrees whose folders are gone
+    -- the scratch `wt/`s and REVIEW- checkouts this sweep removed, and any
+    an operator removed by hand."""
+    runner(["git", "-C", str(hub / SOURCE_DIR), "worktree", "prune"], timeout=120)
+
+
+def sweep(
+    hubs: "Iterable[Path]",
+    guard: Guard,
+    *,
+    grace_seconds: float,
+    now: float,
+    dry_run: bool = False,
+    runner: Runner = run,
+) -> SweepResult:
+    """Remove every candidate under `hubs` older than `grace_seconds` that
+    `guard` does not hold, then prune each hub's worktree records.
+
+    Dry-run removes nothing and prunes nothing: it logs each folder it WOULD
+    remove (with its size) and reports them in `would_remove`."""
+    result = SweepResult()
+    for hub in hubs:
+        result.hubs += 1
+        for candidate in scan_hub(hub):
+            mtime = newest_mtime(candidate.path)
+            if mtime is None:
+                continue  # vanished mid-sweep
+            if now - mtime < grace_seconds:
+                result.fresh += 1
+                continue
+            why = guard.holds(candidate)
+            if why is not None:
+                log.debug("janitor: keeping %s — %s", candidate.path, why)
+                result.held.append((candidate.path, why))
+                continue
+            if not _contained(candidate):
+                result.failed.append((candidate.path, "not contained in its hub"))
+                continue
+            size = dir_bytes(candidate.path)
+            if dry_run:
+                log.info(
+                    "[dry-run] janitor would remove %s (%s, %.1f h old)",
+                    candidate.path, human(size), (now - mtime) / 3600,
+                )
+                result.would_remove.append((candidate.path, size))
+                continue
+            try:
+                shutil.rmtree(candidate.path)
+            except OSError as exc:
+                log.warning("janitor: could not remove %s (%s)", candidate.path, exc)
+                result.failed.append((candidate.path, str(exc)))
+                continue
+            log.debug("janitor: removed %s (%s)", candidate.path, human(size))
+            result.removed.append((candidate.path, size))
+        if dry_run:
+            continue
+        try:
+            prune_worktrees(hub, runner)
+            result.pruned += 1
+        except (CommandError, OSError) as exc:
+            log.warning("janitor: git worktree prune failed in %s (%s)", hub, exc)
+    return result

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa/tools/github/revloop/loop.py

@@ -24,6 +24,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Callable
 
+from . import janitor as janitor_mod
 from . import parking as parking_mod
 from . import prompts as prompts_mod
 from .alissa import (
@@ -1120,7 +1121,13 @@ _SHELL_RULE = (
 # The reviewer's own line beside it (issue #138): the seat is read-only (CR6),
 # so the "worktree" the shell rule names is the throwaway REVIEW-<task>
 # checkout the review skill lets a reviewer make, and nothing a reviewer
-# writes there needs deleting -- the workspace prune reclaims it.
+# writes there needs deleting. The daemon's workspace janitor (janitor.py,
+# issue #167) reclaims it: every `janitor_interval_minutes` it removes each
+# hub's `main/.review-scratch-*` and `REVIEW-*` folders older than
+# `janitor_grace_minutes` that no live session or open round holds, then
+# prunes `.source`'s worktree records. The rule's text does not name the
+# janitor: the reviewer needs only to know it must not delete, and the plan
+# directives that embed this rule are pinned by digest.
 _REVIEWER_RULE = (
     "You never push and never delete: a reviewer that needs scratch files "
     "writes them under its own checkout and leaves them. "
@@ -2564,6 +2571,9 @@ class ReviewWatcher:
         # has listed this pass (the preflight refresh, or a sweep whose list
         # failed), and the refresh lists for itself.
         self._pass_roster: list[ManagedSession] | None = None
+        # When the workspace janitor last swept (monotonic), or None before the
+        # first sweep -- which therefore runs at the end of the first pass.
+        self._janitor_last: "float | None" = None
         # The (repo, number, round) whose alive session the stale-round probe
         # just killed as `wedged:first-run-dialog` (issue #136), so the
         # respawn site logs its re-enqueue at INFO instead of a second
@@ -7697,6 +7707,9 @@ class ReviewWatcher:
         # heartbeat is the completion time of a pass whose exhaust is already
         # written and whose events are already on their way.
         vitals = self._push_fleet_vitals(completed_at=time.time())
+        # The workspace janitor (issue #167), last: it is the one part of the
+        # pass that is pure housekeeping, and it never raises.
+        self._run_janitor()
         log.info(
             "poll summary: %d candidate(s), %d reaped, %d parked on a prompt, "
             "%d answered%s, %d ms, vitals: %s",
@@ -7761,6 +7774,129 @@ class ReviewWatcher:
             )
             return VITALS_FAILED
 
+    def _run_janitor(self, now: "float | None" = None) -> "janitor_mod.SweepResult | None":
+        """Sweep the workspace when the janitor is on and its interval has
+        elapsed (issue #167). Returns the sweep's result, or None when no
+        sweep ran. Never raises: a sweep that fails is one WARNING and the
+        next interval tries again.
+
+        One INFO line per sweep (folders removed and bytes freed, or what a
+        dry run WOULD remove), and one WARNING when the workspace volume is
+        at or above `janitor_warn_pct`. The disk read runs even when the
+        roster cannot be listed and the removal half is skipped: a full
+        volume is worth saying whatever else went wrong."""
+        if not self.config.janitor_enabled:
+            return None
+        mono = time.monotonic()
+        interval = self.config.janitor_interval_minutes * 60
+        if self._janitor_last is not None and mono - self._janitor_last < interval:
+            return None
+        self._janitor_last = mono
+        stamp = time.time() if now is None else now
+        try:
+            result = self._sweep_workspace(stamp)
+        except Exception as exc:
+            log.warning(
+                "janitor: sweep failed unexpectedly (%s: %s) — nothing more is "
+                "removed this interval; the pass completes",
+                type(exc).__name__, exc, exc_info=True,
+            )
+            result = None
+        self._warn_disk()
+        return result
+
+    def _sweep_workspace(self, now: float) -> "janitor_mod.SweepResult | None":
+        guard = self._janitor_guard(now)
+        if guard is None:
+            log.warning(
+                "janitor: could not list reviewer sessions — skipping this "
+                "sweep, since a live session's folders cannot be told apart"
+            )
+            return None
+        hubs = janitor_mod.discover_hubs(self.config.workspace_root)
+        result = janitor_mod.sweep(
+            hubs, guard,
+            grace_seconds=self.config.janitor_grace_minutes * 60,
+            now=now,
+            dry_run=self.config.dry_run,
+        )
+        if self.config.dry_run:
+            log.info(
+                "[dry-run] janitor: would remove %d folder(s) (%s) across %d "
+                "hub(s); %d held by a live round, %d inside the grace",
+                len(result.would_remove),
+                janitor_mod.human(sum(size for _, size in result.would_remove)),
+                result.hubs, len(result.held), result.fresh,
+            )
+        else:
+            log.info(
+                "janitor: removed %d folder(s), freed %s across %d hub(s); "
+                "%d held by a live round, %d inside the grace, %d failed",
+                len(result.removed), janitor_mod.human(result.freed),
+                result.hubs, len(result.held), result.fresh, len(result.failed),
+            )
+        return result
+
+    def _janitor_guard(self, now: float) -> "janitor_mod.Guard | None":
+        """What the janitor must not touch: every PR (and its review task's
+        REVIEW- checkout) with a live reviewer session or an open ledger
+        round, or None when the roster cannot be listed -- a sweep that
+        cannot see the live sessions holds nothing, so it must not run.
+
+        Open rounds are the ledger's own definition (`in_flight_repos`): a
+        spawn younger than the stale-round window whose session was not
+        reaped, and a verdict post still owed. The roster is the pass's
+        post-reap listing when the sweep produced one."""
+        sessions = self._pass_roster
+        if sessions is None:
+            try:
+                sessions = self.alissa.list_review_sessions()
+            except CommandError as exc:
+                log.debug("janitor: roster listing failed (%s)", exc)
+                return None
+        guard = janitor_mod.Guard()
+        for ses in sessions:
+            ref = ses.ref
+            if ref is None:
+                continue
+            row = self.state.find_spawn_by_session(ses.name)
+            if row is not None:
+                guard.hold(str(row["repo"]), int(row["number"]), row["task_ref"])
+            else:
+                # No ledger row (a skill-shaped `review-pr-<n>`): the name is
+                # the only evidence, and a name without a repo holds its PR
+                # number in every hub.
+                guard.hold(ref.repo, ref.number)
+        for spawn_row in self.state.read_spawns(since=now - STALE_ROUND_SECONDS):
+            if not self.state.is_reaped(str(spawn_row["session"])):
+                guard.hold(
+                    str(spawn_row["repo"]), int(spawn_row["number"]),
+                    spawn_row["task_ref"],
+                )
+        for post in self.state.read_verdict_posts():
+            if post["posted_at"] is None and post["abandoned_at"] is None:
+                spawn = self.state.get_spawn(
+                    str(post["repo"]), int(post["number"]), int(post["round"])
+                )
+                guard.hold(
+                    str(post["repo"]), int(post["number"]),
+                    spawn["task_ref"] if spawn is not None else None,
+                )
+        return guard
+
+    def _warn_disk(self) -> None:
+        """One WARNING when the workspace volume is at or above
+        `janitor_warn_pct` (0 = never)."""
+        threshold = self.config.janitor_warn_pct
+        if not threshold:
+            return
+        pct = janitor_mod.disk_used_pct(self.config.workspace_root)
+        if pct is not None and pct >= threshold:
+            log.warning(
+                "janitor: workspace volume %s is %.1f%% used (warn at %d%%)",
+                self.config.workspace_root, pct, threshold,
+            )
+
     def _vitals_config(self) -> dict:
         """The snapshot's `config` block (issue #159), read off what this
         watcher RUNS on: `self.config` is re-bound by every allowlist

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa/tools/github/revloop/proc.py

@@ -8,10 +8,18 @@ inherited -- which is how a reviewer's verdict ended up on GitHub under the
 IMPLEMENTER's login (issue #51). Callers that must be sure which identity a
 `gh` call carries pass a fully-resolved environment here; everything else
 passes None and inherits, exactly as before.
+
+A child that cannot even be STARTED is a CommandError too (issue #169): the
+container's cgroup pids.max counts threads, so a busy fleet can make `fork`
+fail with EAGAIN, and an OSError escaping here reads as an unexplained crash
+class rather than "gh could not start". Folding it keeps one failure type for
+every caller (each already handles a CommandError the way it handles a
+timeout) and puts the errno name in the message the poll firewall logs.
 """
 
 from __future__ import annotations
 
+import errno
 import json
 import logging
 import os
@@ -64,12 +72,24 @@ def run(
         )
     except subprocess.TimeoutExpired as exc:
         raise CommandError(argv, -1, f"timed out after {timeout}s") from exc
+    except OSError as exc:
+        raise CommandError(argv, -1, f"could not start {argv[0]}: {_os_error_text(exc)}") from exc
 
     if check and proc.returncode != 0:
         raise CommandError(argv, proc.returncode, proc.stderr)
     return proc.stdout
 
 
+def _os_error_text(exc: OSError) -> str:
+    """`EAGAIN: Resource temporarily unavailable` -- the errno's symbolic name
+    first, since that is what an operator greps for; the bare message when the
+    error carries no errno."""
+    name = errno.errorcode.get(exc.errno) if exc.errno is not None else None
+    if name is None:
+        return str(exc)
+    return f"{name}: {exc.strerror or exc}"
+
+
 def run_json(
     argv: Sequence[str],
     *,

alissa_tools_github_revloop-0.31.16/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.31.16

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.31.14
+Version: 0.31.16
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.31.14 → alissa_tools_github_revloop-0.31.16}/src/main/alissa_tools_github_revloop.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/main/alissa/tools/github/revloop/bows.py
 src/main/alissa/tools/github/revloop/config.py
 src/main/alissa/tools/github/revloop/fleet_vitals.py
 src/main/alissa/tools/github/revloop/ghclient.py
+src/main/alissa/tools/github/revloop/janitor.py
 src/main/alissa/tools/github/revloop/loop.py
 src/main/alissa/tools/github/revloop/loop_events.py
 src/main/alissa/tools/github/revloop/parking.py

alissa_tools_github_revloop-0.31.14/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.31.14