alissa-tools-github-revloop 0.31.13__tar.gz → 0.31.17__tar.gz

{alissa_tools_github_revloop-0.31.13/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.31.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.31.13
+Version: 0.31.17
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -46,6 +46,18 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
+## Discovery PRs are not reviewed
+
+A PR in a plans repository (`plan_repos`, `ALISSA_REVIEW_PLAN_REPOS`) whose
+body carries `<!-- alissa-discovery v1 -->` on a line of its own and whose
+every changed path is under `knowledge-base/` gets **no review round** — no
+reviewer session, no review task — and one activity-comment line per head
+saying why. A marked PR that touches anything else (or whose file list cannot
+be read in full) is reviewed under the code directive, unchanged. The fleet
+flag `discovery_review` (`ALISSA_REVIEW_DISCOVERY_REVIEW`, default off) turns
+the skip off: every discovery PR is then reviewed like any other. See
+*Discovery PRs* in the repository README.
+
 ## Install
 
 ```sh

{alissa_tools_github_revloop-0.31.13 → alissa_tools_github_revloop-0.31.17}/README.md

@@ -24,6 +24,18 @@ The rule: a distribution owns a leaf package and declares only that subtree
 `__init__.py` at any namespace level would claim it for one distribution and
 shadow the others.
 
+## Discovery PRs are not reviewed
+
+A PR in a plans repository (`plan_repos`, `ALISSA_REVIEW_PLAN_REPOS`) whose
+body carries `<!-- alissa-discovery v1 -->` on a line of its own and whose
+every changed path is under `knowledge-base/` gets **no review round** — no
+reviewer session, no review task — and one activity-comment line per head
+saying why. A marked PR that touches anything else (or whose file list cannot
+be read in full) is reviewed under the code directive, unchanged. The fleet
+flag `discovery_review` (`ALISSA_REVIEW_DISCOVERY_REVIEW`, default off) turns
+the skip off: every discovery PR is then reviewed like any other. See
+*Discovery PRs* in the repository README.
+
 ## Install
 
 ```sh

{alissa_tools_github_revloop-0.31.13 → alissa_tools_github_revloop-0.31.17}/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.13 → alissa_tools_github_revloop-0.31.17}/src/main/alissa/tools/github/revloop/config.py

@@ -183,6 +183,7 @@ CONFIG_KEYS = (
     "authors",
     "plan_repos",
     "plan_authors",
+    "discovery_review",
     "operators",
     "agent_profile",
     "reviewer_login",
@@ -206,6 +207,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 +238,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
@@ -256,6 +269,15 @@ BOW_OWNERS_ENV = "ALISSA_REVIEW_BOW_OWNERS"
 PLAN_REPOS_ENV = "ALISSA_REVIEW_PLAN_REPOS"
 PLAN_AUTHORS_ENV = "ALISSA_REVIEW_PLAN_AUTHORS"
 PLAN_REPO_OWNER_PLACEHOLDER = "<owner>"
+
+# The discovery fleet flag (issue #171; build-discovery design §3.3, DS-7).
+# OFF by default: a DISCOVERY PR -- a plans repository, the discovery marker,
+# every changed path under `knowledge-base/` (loop.discovery_skip_reason) --
+# gets no review round at all, because its defence is the knowledge-base lint
+# of record, staleness, the plan refuter and the user's acceptance. ON, every
+# discovery PR is reviewed under the code directive like any other PR. Same
+# env > file > default precedence and boolean spellings as the janitor's rail.
+DISCOVERY_REVIEW_ENV = "ALISSA_REVIEW_DISCOVERY_REVIEW"
 DEFAULT_PLAN_REPO_NAME = "alissa-dark-factory-plans"
 DEFAULT_PLAN_REPOS: "tuple[str, ...]" = (
     f"{PLAN_REPO_OWNER_PLACEHOLDER}/{DEFAULT_PLAN_REPO_NAME}",
@@ -408,6 +430,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 +715,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
@@ -837,6 +906,10 @@ class Config:
     plan_repos: tuple[str, ...] = DEFAULT_PLAN_REPOS
     plan_authors: tuple[str, ...] = ()
 
+    # Review discovery PRs after all (issue #171); see DISCOVERY_REVIEW_ENV.
+    # False -- the default -- skips them.
+    discovery_review: bool = False
+
     # GitHub logins whose re-entry ack may raise a capped PR's effective cap
     # (loop.parse_reentry_ack). Empty -- the default -- means NO ack is ever
     # honoured: the lever fails closed, because anyone who can comment on a PR
@@ -978,6 +1051,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 +1197,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 +1272,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:
@@ -1194,6 +1281,16 @@ class Config:
         env_plan_authors = env_plan_list(PLAN_AUTHORS_ENV, environ)
         if env_plan_authors is not None:
             raw["plan_authors"] = env_plan_authors
+        # The discovery flag (issue #171), same layer, same reason.
+        env_discovery = _env_bool(DISCOVERY_REVIEW_ENV, environ)
+        if env_discovery is not None:
+            raw["discovery_review"] = env_discovery
+        discovery_review = raw.get("discovery_review", cls.discovery_review)
+        if not isinstance(discovery_review, bool):
+            # A JSON string "false" is truthy; refused rather than read as on.
+            raise ValueError(
+                f"discovery_review must be true or false, got {discovery_review!r}"
+            )
 
         source = raw.get("repos_source", cls.repos_source)
         if source not in _REPOS_SOURCES:
@@ -1439,6 +1536,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),
@@ -1454,6 +1576,7 @@ class Config:
             authors=authors,
             plan_repos=plan_repos,
             plan_authors=plan_authors,
+            discovery_review=discovery_review,
             operators=operators,
             agent_profile=raw.get("agent_profile", "claude"),
             reviewer_login=raw.get("reviewer_login"),
@@ -1477,6 +1600,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.13 → alissa_tools_github_revloop-0.31.17}/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.13 → alissa_tools_github_revloop-0.31.17}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -93,6 +93,12 @@ COMPARE_COMMITS_PER_PAGE = 1
 # gone?" probe would answer yes on every large PR and abandon real verdicts.
 PR_COMMIT_CAP = 250
 
+# GitHub's OWN cap on the pull-request files endpoint: it "lists a maximum of
+# 3000 files" (30 pages of 100). Past it the listing is silently short, so a
+# PR at the cap cannot prove that EVERY changed path is under some prefix --
+# which is the one question `pull_request_files` is asked (issue #171).
+PR_FILES_CAP = 3000
+
 # Environment variables `gh` reads a token from. Both are cleared before an
 # explicitly-routed call, so an inherited implementer credential cannot win by
 # being the one variable we did not think to overwrite.
@@ -783,6 +789,58 @@ class GitHub:
                 return out
             page += 1
 
+    def pull_request_files(self, owner: str, repo: str, number: int) -> list[str]:
+        """Every path the PR changes, paged to the end.
+
+        Read on ONE path: the discovery skip (issue #171), which asks whether
+        EVERY changed path is under `knowledge-base/`. That is an absence
+        question again -- "nothing outside the prefix" -- so a listing at
+        GitHub's PR_FILES_CAP is REFUSED (`TruncatedListing`) rather than
+        answered short, and the caller reviews the PR instead of skipping it.
+
+        A RENAME contributes BOTH names, for the reason `compare_files` gives:
+        `src/x.py` moved to `knowledge-base/x.py` changed a path outside the
+        prefix, and reading only the destination would make it look confined.
+        """
+        out: list[str] = []
+        seen: set[str] = set()
+        listed = 0
+        page = 1
+        while True:
+            data = (
+                self._api(
+                    "-X",
+                    "GET",
+                    f"repos/{owner}/{repo}/pulls/{number}/files",
+                    "-f",
+                    f"per_page={PER_PAGE}",
+                    "-f",
+                    f"page={page}",
+                )
+                or []
+            )
+            listed += len(data)
+            for entry in data:
+                for key in ("filename", "previous_filename"):
+                    name = str(entry.get(key) or "")
+                    if name and name not in seen:
+                        seen.add(name)
+                        out.append(name)
+            if listed >= PR_FILES_CAP:
+                log.warning(
+                    "%s/%s#%d reached GitHub's %d-file listing cap — the file "
+                    "list is not complete, so 'nothing outside the prefix' "
+                    "cannot be read from it",
+                    owner, repo, number, PR_FILES_CAP,
+                )
+                raise TruncatedListing(
+                    f"{owner}/{repo}#{number} reached GitHub's {PR_FILES_CAP}-file "
+                    f"listing cap; absence cannot be proven from it"
+                )
+            if len(data) < PER_PAGE:
+                return out
+            page += 1
+
     # -- CI check rollup ---------------------------------------------------
 
     def check_rollup(self, owner: str, repo: str, sha: str) -> CheckRollup: