alissa-tools-github-devloop 0.8.1__tar.gz → 0.8.3__tar.gz

{alissa_tools_github_devloop-0.8.1/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.1
+Version: 0.8.3
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.3}/src/main/alissa/tools/github/devloop/__main__.py

@@ -98,7 +98,15 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="N",
         help="max concurrent worker sessions (develop-*/fix-*/maintain-*) "
         "before actionable items defer to the next poll; 0 = unlimited "
-        "(the default)",
+        "(the default). Also the reaper's post-sweep alert threshold",
+    )
+    over.add_argument(
+        "--reap-grace-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how long a worker session must have been quiet before the "
+        "reaper may kill it on a terminal anchor; 0 = use stale_minutes "
+        "(default: 30)",
     )
     over.add_argument(
         "--on-missing-origin-task",
@@ -235,6 +243,62 @@ def build_parser() -> argparse.ArgumentParser:
         "(two overlapping instances can then both spawn on one item)",
     )
 
+    janitor = over.add_mutually_exclusive_group()
+    janitor.add_argument(
+        "--janitor",
+        dest="janitor_enabled",
+        action="store_true",
+        default=None,
+        help="reclaim per-task workspaces whose anchor PR is terminal, whose "
+        "worker session is gone, and whose grace elapsed, and bound the "
+        "package-manager caches (the default)",
+    )
+    janitor.add_argument(
+        "--no-janitor",
+        dest="janitor_enabled",
+        action="store_false",
+        help="never reclaim workspaces or trim caches; disk telemetry stops "
+        "with it (the whole janitor pass is skipped)",
+    )
+    over.add_argument(
+        "--janitor-grace-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how long a workspace's anchor must have been terminal before it "
+        "may be reclaimed; 0 = use reap_grace_minutes (the default)",
+    )
+    over.add_argument(
+        "--janitor-interval-minutes",
+        type=int,
+        metavar="MINUTES",
+        help="how often the janitor's expensive half (hub walk, tree sizing, "
+        "anchor lookups) runs; 0 = every poll (default: 10). The disk "
+        "telemetry line still logs every poll",
+    )
+    over.add_argument(
+        "--cache-cap-mb",
+        type=int,
+        metavar="MiB",
+        help="size cap per package-manager cache directory; over it the "
+        "oldest entries are removed until under. 0 = no cache bound "
+        "(default: 2048)",
+    )
+    over.add_argument(
+        "--cache-path",
+        dest="cache_paths",
+        action="append",
+        metavar="PATH",
+        help="a cache directory the cap applies to; repeatable. Replaces the "
+        "built-in list (npm/pip/uv/pnpm/yarn/bun in their standard homes)",
+    )
+    over.add_argument(
+        "--disk-warn-percent",
+        type=int,
+        metavar="PERCENT",
+        help="volume usage at which the per-poll disk line escalates to a "
+        "warning naming the biggest workspaces; 0 = never warn (default: 80)",
+    )
+
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
         "--dry-run",
@@ -267,6 +331,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "attempt_cap": args.attempt_cap,
         "stale_minutes": args.stale_minutes,
         "max_sessions": args.max_sessions,
+        "reap_grace_minutes": args.reap_grace_minutes,
         "on_missing_origin_task": args.on_missing_origin_task,
         "on_missing_hub": args.on_missing_hub,
         "fix_rounds_enabled": args.fix_rounds_enabled,
@@ -278,6 +343,12 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "orphan_sweep_enabled": args.orphan_sweep_enabled,
         "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
+        "janitor_enabled": args.janitor_enabled,
+        "janitor_grace_minutes": args.janitor_grace_minutes,
+        "janitor_interval_minutes": args.janitor_interval_minutes,
+        "cache_cap_mb": args.cache_cap_mb,
+        "cache_paths": tuple(args.cache_paths) if args.cache_paths else None,
+        "disk_warn_percent": args.disk_warn_percent,
         "dry_run": args.dry_run,
     }
 
@@ -309,12 +380,15 @@ def log_effective_config(config: Config, login: str) -> None:
     log.info("reviewers: %s", ", ".join(config.reviewers) or "none")
     log.info(
         "poll every %ss; dry_run=%s; attempt_cap=%s; stale after %s min; "
-        "max_sessions=%s; fix_rounds=%s; maintain=%s (label %r); resume=%s; "
+        "max_sessions=%s; reap_grace=%s min; fix_rounds=%s; maintain=%s "
+        "(label %r); resume=%s; "
         "rerequest=%s (grace %s min); orphan_sweep=%s (grace %s min); "
-        "activity_claims=%s",
+        "activity_claims=%s; janitor=%s (grace %s min, every %s min, cache "
+        "cap %s MiB, warn at %s%%)",
         config.poll_interval, config.dry_run, config.attempt_cap,
         config.stale_minutes,
         config.max_sessions or "unlimited",
+        config.reap_grace_seconds // 60,
         config.fix_rounds_enabled,
         config.maintain_enabled, config.maintain_label,
         config.resume_enabled,
@@ -323,8 +397,17 @@ def log_effective_config(config: Config, login: str) -> None:
         config.orphan_sweep_enabled,
         config.orphan_grace_seconds // 60,
         config.activity_claims_enabled,
+        config.janitor_enabled,
+        config.janitor_grace_seconds // 60,
+        config.janitor_interval_minutes or "poll",
+        config.cache_cap_mb,
+        config.disk_warn_percent,
     )
     log.debug("hub_template: %s", config.hub_template)
+    log.debug(
+        "cache_paths: %s",
+        ", ".join(config.cache_paths) or "built-in defaults",
+    )
     log.debug("agent_profile: %s", config.agent_profile)
     log.debug("developer_login: %s", config.developer_login or f"{login} (auto)")
     log.debug("state_db: %s", config.state_db)

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.3}/src/main/alissa/tools/github/devloop/config.py

@@ -57,6 +57,7 @@ CONFIG_KEYS = (
     "attempt_cap",
     "stale_minutes",
     "max_sessions",
+    "reap_grace_minutes",
     "on_missing_origin_task",
     "on_missing_hub",
     "fix_rounds_enabled",
@@ -68,6 +69,12 @@ CONFIG_KEYS = (
     "orphan_sweep_enabled",
     "orphan_grace_minutes",
     "activity_claims_enabled",
+    "janitor_enabled",
+    "janitor_grace_minutes",
+    "janitor_interval_minutes",
+    "cache_cap_mb",
+    "cache_paths",
+    "disk_warn_percent",
     "dry_run",
 )
 
@@ -149,6 +156,18 @@ class Config:
     # listing, so enabling it costs no extra GitHub or CLI calls.
     max_sessions: int = 0
 
+    # The reaper's grace: how long a worker session must have been QUIET (no
+    # tmux activity) before a terminal anchor licenses killing it. The point
+    # is the window right after an anchor goes terminal -- a PR merges while
+    # its session is still attaching evidence, answering a triage thread,
+    # writing its delivery note -- where the anchor already says "done" and
+    # the session is not. Busy is spared regardless (see DevWatcher's sweep);
+    # this covers the session that is idle between two bursts of that work.
+    # 30 minutes by default: long enough to outlast a close-out, short enough
+    # that a corpse costs at most one extra poll window of memory. 0 falls
+    # back to stale_minutes, the sentinel every other grace knob here uses.
+    reap_grace_minutes: int = 30
+
     on_missing_origin_task: str = ON_MISSING_WARN
     on_missing_hub: str = HUB_SKIP
 
@@ -247,6 +266,56 @@ class Config:
     # that would rather not pay the extra comments fetch.
     activity_claims_enabled: bool = True
 
+    # The workspace janitor (issue #74): the filesystem sibling of the session
+    # reaper. Every worker session materializes a per-task workspace under its
+    # repo's hub (a `TASK-<n>-<DESC>` worktree plus whatever its lane installs
+    # into it) and nothing removed them, so disk grew monotonically with PR
+    # throughput -- 3 GB to 32 GB in three days against a 50 GB cap, of which
+    # 21.4 GiB was 53 already-merged task worktrees. With this on, a workspace
+    # whose anchor PR is terminal, whose worker session is gone, and whose
+    # grace has elapsed is reclaimed (worktree removed, branch deleted), and
+    # package-manager caches are bounded rather than zeroed. Default ON, on
+    # the same grounds as the reaper: it acts only on devloop's own
+    # `TASK-<n>-…` directories under its own hubs, never on anything with
+    # uncommitted or unpushed work, and every side effect honors dry_run.
+    janitor_enabled: bool = True
+
+    # How long the anchor must have been terminal before its workspace may be
+    # reclaimed. 0 means "share the reaper's grace" (reap_grace_minutes,
+    # itself falling back to stale_minutes) -- the sentinel every other grace
+    # knob here uses, and the documented default: the two sweeps are the same
+    # decision about the same lane, so their windows should move together
+    # unless an operator deliberately parts them.
+    janitor_grace_minutes: int = 0
+
+    # How often the janitor's expensive half runs: the hub walk, the tree
+    # sizing, and the one GitHub call per candidate workspace. Deliberately
+    # NOT every poll -- at a 30s interval the walk alone measured ~8s on the
+    # real 21 GiB volume, and the anchor lookups would be ~90 API calls a
+    # minute for work whose input changes on the timescale of a merge. The
+    # cheap half (the volume's own used/free figures) still logs EVERY poll,
+    # so the telemetry line never goes quiet. 0 means every poll.
+    janitor_interval_minutes: int = 10
+
+    # The cache bound, in MiB: package-manager caches over this are trimmed
+    # oldest-entry-first back under it. 0 disables the trim entirely. A cache
+    # is a legitimate speed tradeoff -- the default is generous on purpose
+    # (the measured real-world figure was 1.4 MB, four orders of magnitude
+    # under this), because a cache that is not the problem should not be
+    # cleared to prove a point.
+    cache_cap_mb: int = 2048
+
+    # Which cache directories the bound applies to. Empty means the built-in
+    # list (`janitor.DEFAULT_CACHE_PATHS`: npm/pip/uv/pnpm/yarn/bun in their
+    # standard homes); entries that do not exist are skipped. `~` expands.
+    cache_paths: tuple[str, ...] = ()
+
+    # Percent of the workspace volume in use at which the per-poll telemetry
+    # line escalates from INFO to a WARNING naming the biggest consumers.
+    # 80 by default -- far enough ahead of full that a human still has room
+    # to act (at the incident's growth rate, ~2 days). 0 never warns.
+    disk_warn_percent: int = 80
+
     dry_run: bool = False
 
     # Derived at build time: `repos` casefolded for matching. GitHub names are
@@ -280,6 +349,15 @@ class Config:
         the re-request instantly on a default config."""
         return (self.rerequest_grace_minutes or self.stale_minutes) * 60
 
+    @property
+    def reap_grace_seconds(self) -> int:
+        """How long a worker session must have been quiet before the reaper
+        may kill it, in seconds. Read this, never the raw field -- the
+        `rerequest_grace_seconds` contract verbatim: 0 is the sentinel for
+        "the stale window", and a caller reading the field directly would kill
+        a session that went quiet seconds ago on a config that set 0."""
+        return (self.reap_grace_minutes or self.stale_minutes) * 60
+
     @property
     def orphan_grace_seconds(self) -> int:
         """How long a draft's head must have been public before the orphan
@@ -289,6 +367,30 @@ class Config:
         ready-and-request a draft opened seconds ago on a default config."""
         return (self.orphan_grace_minutes or self.stale_minutes) * 60
 
+    @property
+    def janitor_grace_seconds(self) -> int:
+        """How long an anchor must have been terminal before its workspace may
+        be reclaimed, in seconds. Read this, never the raw field -- the
+        `reap_grace_seconds` contract, one rung longer: 0 means "the reaper's
+        grace", which is itself 0-means-stale_minutes, so a caller reading the
+        field directly would delete a workspace the instant its PR merged on a
+        default config."""
+        return (self.janitor_grace_minutes * 60) or self.reap_grace_seconds
+
+    @property
+    def janitor_interval_seconds(self) -> int:
+        """How often the janitor's expensive half may run, in seconds. 0 means
+        every poll, and needs no sentinel: unlike the grace knobs, "every
+        pass" is a coherent answer to "how often"."""
+        return max(0, self.janitor_interval_minutes) * 60
+
+    @property
+    def cache_cap_bytes(self) -> int:
+        """The cache bound in bytes (0 = no bound). MiB in the config because
+        that is the unit an operator thinks about a cache in; bytes here
+        because that is what the walker measures."""
+        return max(0, self.cache_cap_mb) * 1024 * 1024
+
     @property
     def manifest_path(self) -> Path:
         return self.workspace_root / "alissa-workspace.yaml"
@@ -391,6 +493,17 @@ class Config:
                 f"max_sessions must be >= 0 (0 = unlimited), got {max_sessions}"
             )
 
+        # The reaper's grace, validated like the two below it -- same 0
+        # sentinel, and a negative value is the only invalid one (it would
+        # make every listed session instantly reapable, which is the one
+        # mistake here that kills live work).
+        reap_grace = int(raw.get("reap_grace_minutes", cls.reap_grace_minutes))
+        if reap_grace < 0:
+            raise ValueError(
+                f"reap_grace_minutes must be >= 0 (0 = use stale_minutes), "
+                f"got {reap_grace}"
+            )
+
         # 0 is the sentinel for "fall back to stale_minutes" (the documented
         # default), so the floor is 0 like max_sessions' -- a negative grace
         # would make the self-heal fire on a head pushed in the future.
@@ -413,6 +526,44 @@ class Config:
                 f"got {orphan_grace}"
             )
 
+        # The janitor's grace, the reaper's sentinel one rung longer (0 = use
+        # reap_grace_minutes). Negative is the only invalid value, and it is
+        # the dangerous one: it would license reclaiming a workspace the
+        # instant its PR merged, racing the close-out work the grace exists
+        # for.
+        janitor_grace = int(
+            raw.get("janitor_grace_minutes", cls.janitor_grace_minutes)
+        )
+        if janitor_grace < 0:
+            raise ValueError(
+                f"janitor_grace_minutes must be >= 0 (0 = use "
+                f"reap_grace_minutes), got {janitor_grace}"
+            )
+
+        # 0 means "every poll" here (not a fallback sentinel -- see
+        # janitor_interval_seconds), so again only negatives are rejected.
+        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 poll), "
+                f"got {janitor_interval}"
+            )
+
+        cache_cap = int(raw.get("cache_cap_mb", cls.cache_cap_mb))
+        if cache_cap < 0:
+            raise ValueError(
+                f"cache_cap_mb must be >= 0 (0 = no cache bound), got {cache_cap}"
+            )
+
+        warn_percent = int(raw.get("disk_warn_percent", cls.disk_warn_percent))
+        if not 0 <= warn_percent <= 100:
+            raise ValueError(
+                f"disk_warn_percent must be between 0 and 100 (0 = never "
+                f"warn), got {warn_percent}"
+            )
+
         interval = int(raw.get("poll_interval", cls.poll_interval))
         if interval < MIN_POLL_INTERVAL:
             raise ValueError(
@@ -433,6 +584,7 @@ class Config:
             attempt_cap=cap,
             stale_minutes=stale,
             max_sessions=max_sessions,
+            reap_grace_minutes=reap_grace,
             on_missing_origin_task=mode,
             on_missing_hub=hub_mode,
             fix_rounds_enabled=bool(
@@ -456,6 +608,14 @@ class Config:
             activity_claims_enabled=bool(
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),
+            janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
+            janitor_grace_minutes=janitor_grace,
+            janitor_interval_minutes=janitor_interval,
+            cache_cap_mb=cache_cap,
+            cache_paths=_string_list(
+                raw.get("cache_paths", cls.cache_paths), "cache_paths"
+            ),
+            disk_warn_percent=warn_percent,
             dry_run=bool(raw.get("dry_run", cls.dry_run)),
         )
 

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.3}/src/main/alissa/tools/github/devloop/ghclient.py

@@ -128,6 +128,13 @@ class PullRequest:
     # other three edges -- none of which flip drafts -- need not supply it;
     # `mark_ready` refuses an empty one rather than POSTing a nonsense mutation.
     node_id: str = ""
+    # When this PR was closed (merged or not), unix seconds; None while it is
+    # open OR when the payload carried no readable stamp. The workspace
+    # janitor's grace clock -- a merged PR's task workspace is reclaimable
+    # only once the anchor has been terminal for a while, and this is the
+    # instant that window runs from. Defaulted for the same reason as node_id:
+    # the three spawn edges never ask, and neither do their fakes.
+    closed_at: "int | None" = None
 
     @property
     def full_name(self) -> str:
@@ -141,6 +148,49 @@ class PullRequest:
         return f"{self.owner}/{self.repo}#pr{self.number}"
 
 
+def _pull_request_from(
+    data: "dict", owner: str, repo: str, *, number: "int | None" = None
+) -> PullRequest:
+    """One REST pull-request payload as a PullRequest.
+
+    Shared by the single-PR GET and the branch listing, which return the SAME
+    object shape -- so the two callers cannot drift on what `draft`, the head,
+    or the pending review requests mean. `number` is passed explicitly by the
+    single GET (it knows which PR it asked for even if the payload is empty);
+    the listing reads it from each entry.
+    """
+    head = data.get("head") or {}
+    # Users carry `login`, teams `slug`; both hold the review-response edge
+    # closed -- a pending TEAM re-request still means the ball is in a
+    # reviewer's court, so it must not read as "awaiting the author".
+    requested = tuple(
+        name
+        for entry in (
+            list(data.get("requested_reviewers") or [])
+            + list(data.get("requested_teams") or [])
+        )
+        if isinstance(entry, dict)
+        and (name := (entry.get("login") or entry.get("slug") or ""))
+    )
+    return PullRequest(
+        owner=owner,
+        repo=repo,
+        number=int(number if number is not None else data.get("number") or 0),
+        state=data.get("state", ""),
+        title=data.get("title", ""),
+        author=(data.get("user") or {}).get("login", ""),
+        head_ref=head.get("ref") or "",
+        head_sha=head.get("sha") or "",
+        draft=bool(data.get("draft")),
+        url=data.get("html_url", ""),
+        # `or ""`: GitHub sends null for an empty description.
+        body=data.get("body") or "",
+        requested_reviewers=requested,
+        node_id=data.get("node_id") or "",
+        closed_at=parse_github_timestamp(data.get("closed_at")),
+    )
+
+
 @dataclass(frozen=True)
 class Review:
     author: str
@@ -620,34 +670,47 @@ class GitHub:
         issue edge's resume probe reads for provenance; it rides along on the
         same GET rather than costing a call of its own.)"""
         data = self._api(f"repos/{owner}/{repo}/pulls/{number}") or {}
-        head = data.get("head") or {}
-        # Users carry `login`, teams `slug`; both hold the edge closed -- a
-        # pending TEAM re-request still means the ball is in a reviewer's
-        # court, so it must not read as "awaiting the author".
-        requested = tuple(
-            name
-            for entry in (
-                list(data.get("requested_reviewers") or [])
-                + list(data.get("requested_teams") or [])
+        return _pull_request_from(data, owner, repo, number=number)
+
+    def branch_pulls(
+        self, owner: str, repo: str, head_ref: str
+    ) -> "tuple[PullRequest, ...]":
+        """Every pull request ever opened FROM `head_ref`, in any state --
+        the workspace janitor's anchor lookup.
+
+        A task workspace is a branch checkout, and the only thing that can say
+        whether that branch's work is over is the PR it was opened as. `state`
+        is deliberately `all`: an OPEN PR is precisely the case that must
+        spare the workspace, so a query that could not see it would be
+        unsafe, and a branch with no PR at all comes back empty (spared too --
+        unpublished work has no terminal anchor).
+
+        `head` is qualified with the owner (`owner:branch`), the form GitHub
+        requires to disambiguate forks. Malformed entries are skipped rather
+        than fatal, like `reviews()`; a single page (per_page=100) is a
+        documented window, and a branch with more than 100 pull requests is
+        far outside anything this daemon creates.
+        """
+        data = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/pulls",
+                "-f",
+                f"head={owner}:{head_ref}",
+                "-f",
+                "state=all",
+                "-f",
+                "per_page=100",
             )
-            if isinstance(entry, dict)
-            and (name := (entry.get("login") or entry.get("slug") or ""))
+            or []
         )
-        return PullRequest(
-            owner=owner,
-            repo=repo,
-            number=number,
-            state=data.get("state", ""),
-            title=data.get("title", ""),
-            author=(data.get("user") or {}).get("login", ""),
-            head_ref=head.get("ref") or "",
-            head_sha=head.get("sha") or "",
-            draft=bool(data.get("draft")),
-            url=data.get("html_url", ""),
-            # `or ""`: GitHub sends null for an empty description.
-            body=data.get("body") or "",
-            requested_reviewers=requested,
-            node_id=data.get("node_id") or "",
+        if not isinstance(data, list):
+            return ()
+        return tuple(
+            _pull_request_from(entry, owner, repo)
+            for entry in data
+            if isinstance(entry, dict) and entry.get("number") is not None
         )
 
     def reviews(self, owner: str, repo: str, number: int) -> list[Review]: