alissa-tools-github-revloop 0.23.0__tar.gz → 0.25.0__tar.gz

{alissa_tools_github_revloop-0.23.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.25.0}/PKG-INFO

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

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -14,6 +14,7 @@ from .config import (
     ON_MISSING_CREATE,
     ON_MISSING_SKIP,
     ON_MISSING_SPAWN,
+    TASK_LIST_BOW_ENV,
     Config,
     load_config_file,
     resolve_config_path,
@@ -181,6 +182,16 @@ def build_parser() -> argparse.ArgumentParser:
         help="list the sponsor-union corpus even if the config narrows it",
     )
 
+    over.add_argument(
+        "--task-list-bow",
+        dest="task_list_bow_id",
+        metavar="BOW_ID",
+        help="scope `alissa task list` to one body of work (--bow): the Convex "
+        "_id of the BOW review tasks are created into, NOT a repo's `autodev:` "
+        "feed BOW and not a mirrorInstanceId. A review task outside it is "
+        f"invisible to this daemon. Overridden by ${TASK_LIST_BOW_ENV}",
+    )
+
     dry = over.add_mutually_exclusive_group()
     dry.add_argument(
         "--dry-run",
@@ -221,6 +232,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "checks_spawn_wait_seconds": args.checks_spawn_wait_seconds,
         "review_task_miss_ttl_polls": args.review_task_miss_ttl_polls,
         "task_list_self_scope": args.task_list_self_scope,
+        "task_list_bow_id": args.task_list_bow_id,
         "dry_run": args.dry_run,
     }
 

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0}/src/main/alissa/tools/github/revloop/alissa.py

@@ -122,6 +122,48 @@ TASK_LIST_SELF_FLAG = "--self"
 TASK_LIST_VIEW_FLAG = "--view"
 TASK_LIST_DIGEST_VIEW = "digest"
 
+# `--bow` narrows the CANDIDATE SET rather than filtering the answer, and that
+# is the whole reason it is worth more than the flags above (issue #100).
+#
+# `--status` / `--self` / `--view` all start from the operator's involvement
+# index -- every non-terminal task they are party to -- and cut it down. A BOW
+# scope starts from that body of work's junction rows instead, which carry a
+# denormalized status, so a row that does not match never costs a task-document
+# read at all. The cache story is the same shape: a BOW-scoped query is
+# invalidated only by writes INSIDE that BOW, so the operator's unrelated task
+# churn stops re-billing this daemon's 30-second poll.
+#
+# It really is a SWAP and not an intersection, and that was measured against the
+# installed CLI on 2026-08-28 rather than assumed (PR #101 round 1): across five
+# real BOWs, not one answer was a subset of the plain 1335-row one, and the rows
+# outside it were all non-terminal. Two consequences the composition story has to
+# respect, from the same probe:
+#
+#   * `--self` is IGNORED under `--bow`. `--bow X --self` returns exactly what
+#     `--bow X` returns, and that set is not a subset of the `--self` answer. So
+#     a BOW-scoped deployment gets the body of work's whole membership, actor-
+#     owned or not -- WIDER than `--self`, never narrower.
+#   * `--include-terminal` is ignored too (a BOW holding 52 tasks, 17 of them
+#     `validated`, answers 35 either way), so the default non-terminal filter is
+#     applied server-side but the flag that lifts it is not. `--status` could not
+#     be probed -- this CLI has none -- and on that evidence should not be
+#     assumed to compose either.
+#
+# None of that is a correctness risk, which is why the flags are still sent: a
+# filter the server ignores makes the answer WIDER, `is_open` still runs
+# client-side, and the argv is one the CLI accepts. It costs bytes, not reviews.
+# Treat the list above as a dated snapshot, not a contract: this CLI has grown
+# flags twice now without moving off version `0.1.0`.
+#
+# Opt-in per deployment for the same reason `--self` is, only sharper: a review
+# task that is not attached to the configured BOW is INVISIBLE to the daemon --
+# and on the default `on_missing_review_task` that is not even a missed round but
+# a round spawned untethered from its task -- and review tasks are only born into
+# a BOW once the sessions that create them say so. A configured BOW that nothing
+# writes into lists empty; `list_tasks` retries plain and drops the BOW alone.
+# That is a safety net, not a licence to guess the id.
+TASK_LIST_BOW_FLAG = "--bow"
+
 
 @dataclass(frozen=True)
 class TaskListFlags:
@@ -135,6 +177,7 @@ class TaskListFlags:
     status: bool = False
     self_scope: bool = False
     digest: bool = False
+    bow: bool = False
 
 
 # How deeply an OPTION may be indented in a commander help listing. Commander
@@ -370,7 +413,12 @@ class TaskDetail:
 
 
 class Alissa:
-    def __init__(self, *, task_list_self_scope: bool = False) -> None:
+    def __init__(
+        self,
+        *,
+        task_list_self_scope: bool = False,
+        task_list_bow_id: "str | None" = None,
+    ) -> None:
         """`task_list_self_scope` opts the list call into `--self`.
 
         Default OFF, and that default is evidence, not caution -- see
@@ -378,8 +426,15 @@ class Alissa:
         of a DEPLOYMENT (who creates its review tasks), not of this code, and an
         operator who knows their review tasks are all actor-owned should be able
         to say so.
+
+        `task_list_bow_id` opts the list call into `--bow <id>` (issue #100).
+        Unset -- the default -- is today's call shape, unconditionally. It is
+        the id ALREADY RESOLVED through the config layers (file < CLI < env);
+        this class does not read the environment, so the one place that decides
+        what the id is stays `config.env_task_list_bow_id`.
         """
         self._task_list_self_scope = bool(task_list_self_scope)
+        self._task_list_bow_id = (task_list_bow_id or "").strip() or None
         # The probe's answer, memoized for the process; None = not probed yet.
         # A probe that FAILS is deliberately not memoized (see probe_task_list).
         self._task_list_flags: "TaskListFlags | None" = None
@@ -389,10 +444,27 @@ class Alissa:
         # wrongly is worse than a list that is large: `find_review_task` reads an
         # empty corpus as "this PR has no review task".
         self._task_list_narrowing_disabled = False
+        # Set when the BOW SPECIFICALLY has been disproved at runtime -- a
+        # BOW-scoped call that answered empty. Separate from the flag above
+        # because the evidence is different in kind: `--status`/`--self`/
+        # `--view` filter the same corpus, so an empty answer from them is
+        # anomalous, while `--bow` REPLACES the corpus and "this body of work
+        # holds nothing" is a legitimate answer (see `list_tasks`).
+        self._task_list_bow_disabled = False
         # One diagnostic per client for a status filter that could not be sent
         # (see `_warn_status_filter_dropped`); this path runs every poll pass.
         self._status_filter_warned = False
 
+    @property
+    def task_list_bow_id(self) -> "str | None":
+        """The BOW this client scopes its task list to, or None.
+
+        Read by the boot preflight, which must warn on the id this CLIENT holds
+        rather than on the one the config file happens to carry -- the env layer
+        wins over both file and CLI, so those two can disagree.
+        """
+        return self._task_list_bow_id
+
     # -- the `alissa task list` narrowing probe -----------------------------
 
     def probe_task_list(self) -> "TaskListFlags":
@@ -433,6 +505,7 @@ class Alissa:
             status=_advertises(helptext, TASK_LIST_STATUS_FLAG),
             self_scope=_advertises(helptext, TASK_LIST_SELF_FLAG),
             digest=_advertises(helptext, TASK_LIST_VIEW_FLAG),
+            bow=_advertises(helptext, TASK_LIST_BOW_FLAG),
         )
         self._task_list_flags = flags
         return flags
@@ -472,13 +545,26 @@ class Alissa:
     def task_list_argv(self, *, narrow_status: bool = True) -> list[str]:
         """The narrowest `alissa task list` this CLI actually supports.
 
-        Every addition is probe-gated, so an older CLI -- today's, which offers
-        none of them -- produces exactly the call the daemon has always made.
+        Every addition is probe-gated, so a CLI that offers none of them
+        produces exactly the call the daemon has always made. (The CLI installed
+        on 2026-08-28 offers `--self` and `--bow`, so that is no longer the
+        no-op it once was -- and it still reports version `0.1.0`, which is why
+        the gate reads the help rather than the version. See
+        TASK_LIST_BOW_FLAG.)
         """
         argv = ["alissa", "task", "list", "--json"]
         if self._task_list_narrowing_disabled:
             return argv
         flags = self.probe_task_list()
+        # The BOW goes FIRST because it is the only one of these that chooses a
+        # candidate set rather than filtering one, and reading the argv left to
+        # right is reading them in that order. The others are still sent: the
+        # projection (`--view digest`) genuinely applies within a BOW, and the
+        # ones the server ignores there cost bytes rather than reviews -- see
+        # TASK_LIST_BOW_FLAG for which is which, and for why that list is a
+        # dated snapshot rather than a contract.
+        if flags.bow and self._task_list_bow_id and not self._task_list_bow_disabled:
+            argv += [TASK_LIST_BOW_FLAG, self._task_list_bow_id]
         # An empty filter is not a filter: `_status_filter` answers `""` when
         # the open set carries a status the CLI would reject, and sending
         # `--status ""` would be that same rejected call with an extra step.
@@ -502,8 +588,9 @@ class Alissa:
         filtering. Newer CLIs offer more, so the call is now assembled from a
         boot-time probe of the installed CLI's help (`task_list_argv`): a status
         filter covering exactly the statuses a live review task can hold, a lean
-        `--view digest`, and `--self` when the deployment says its review tasks
-        are actor-owned. None of it is required; an absent flag is simply not
+        `--view digest`, `--self` when the deployment says its review tasks are
+        actor-owned, and `--bow <id>` when it has named the body of work they
+        are created into. None of it is required; an absent flag is simply not
         sent.
 
         Narrowing is still the SECOND line of defence, not the first. Even a
@@ -520,10 +607,17 @@ class Alissa:
         filter; every other narrowing still applies.
 
         A narrowed call that FAILS, or that answers with an empty corpus, is
-        retried once unnarrowed and turns the narrowing off for the rest of the
-        process. Both are how a CLI that advertises a flag its API does not
-        serve would present, and either would otherwise read as "this actor has
-        no review tasks" -- which is a skipped review, not a slower one.
+        retried once unnarrowed. Both are how a CLI that advertises a flag its
+        API does not serve would present, and either would otherwise read as
+        "this actor has no review tasks" -- which is a skipped review, not a
+        slower one.
+
+        What the retry then turns OFF differs by which signal it was, because
+        the two carry different evidence. A FAILURE turns off all narrowing for
+        the process. An EMPTY answer does too -- unless the call was BOW-scoped,
+        in which case only the BOW is dropped and the other flags stand: `--bow`
+        replaces the corpus instead of filtering it, so an empty answer from it
+        is a legitimate result and says nothing about the rest.
         """
         argv = self.task_list_argv(narrow_status=narrow_status)
         plain = ["alissa", "task", "list", "--json"]
@@ -532,6 +626,13 @@ class Alissa:
         except CommandError:
             if argv == plain:
                 raise
+            # Deliberately blunter than the empty-answer path below, which
+            # attributes the disproof to `--bow` alone when it can. A hard
+            # failure cannot be attributed: it does not say which flag the
+            # server choked on, and a transient timeout or 5xx says nothing
+            # about the flags at all. So all narrowing goes -- wide but
+            # complete, which costs the optimization and never a review. The
+            # asymmetry is a decision, not a corner the BOW split missed.
             log.warning(
                 "`%s` failed — retrying the plain task list and dropping the "
                 "narrowing for this process", " ".join(argv),
@@ -558,7 +659,34 @@ class Alissa:
             "empty corpus from a filter this API does not serve", " ".join(argv),
         )
         tasks = self._tasks_from(run_json(plain, timeout=90) or [])
-        if tasks:
+        if not tasks:
+            return tasks
+        if TASK_LIST_BOW_FLAG in argv:
+            # "The plain list found rows" proves nothing about a BOW-scoped
+            # call, because the two answers are not comparable: `--bow` swaps
+            # the candidate set rather than filtering the actor's, so its answer
+            # is not a subset of the plain one (measured 2026-08-28 -- see
+            # TASK_LIST_BOW_FLAG). Condemning the other three flags on this
+            # evidence would drop the whole optimization on the state the
+            # rollout STARTS in: a review BOW nothing has been created into yet.
+            #
+            # The BOW itself is still dropped for the process, and that is not a
+            # third option so much as the only tractable one: with a swap there
+            # is no way to tell a mistyped id from an empty-but-correct one, and
+            # holding the BOW would mean paying two list calls every pass, for
+            # ever, on a typo. Wide-but-complete, the direction everything on
+            # this path degrades in.
+            self._task_list_bow_disabled = True
+            log.warning(
+                "the BOW-scoped task list answered empty while the plain list "
+                "returned %d task(s) — that is not evidence the call is broken "
+                "(a BOW-scoped list REPLACES the actor's corpus), so only the "
+                "BOW is dropped for this process and the other narrowing "
+                "stands. Either the configured id is wrong, or nothing has been "
+                "created into that body of work yet; once it is populated, "
+                "restart the daemon to scope to it again", len(tasks),
+            )
+        else:
             self._task_list_narrowing_disabled = True
             log.warning(
                 "the plain task list returned %d task(s) — the narrowed call is "

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0}/src/main/alissa/tools/github/revloop/config.py

@@ -6,6 +6,13 @@ Settings come from three layers, later winning over earlier:
 2. a JSON config file (see `resolve_config_path`)
 3. CLI arguments
 
+`task_list_bow_id` adds a fourth above them all — the environment
+(`ALISSA_REVIEW_TASK_BOW`, see `env_task_list_bow_id`). It is the only key that
+does, and the reason is that it is the only one a second entry point needs:
+`alissa-pr-review` builds its own `Alissa` client with no config file and no
+argv of the daemon's, so an id that lives only in the file or the flags reaches
+the poll loop and silently misses that call site.
+
 `workspace_root` is deliberately **not** a config key — it is a property of the
 running process, not of the settings. That lets one config file drive several
 daemons over different workspaces on the same machine, each pointed with
@@ -15,6 +22,7 @@ daemons over different workspaces on the same machine, each pointed with
 from __future__ import annotations
 
 import json
+import os
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -135,9 +143,30 @@ CONFIG_KEYS = (
     "checks_spawn_wait_seconds",
     "review_task_miss_ttl_polls",
     "task_list_self_scope",
+    "task_list_bow_id",
     "dry_run",
 )
 
+# The environment variable carrying the review BOW id (issue #100). It outranks
+# both the config file and the CLI flag -- see the module docstring for why this
+# one key gets a layer the others do not.
+TASK_LIST_BOW_ENV = "ALISSA_REVIEW_TASK_BOW"
+
+
+def env_task_list_bow_id(environ: "Mapping[str, str] | None" = None) -> "str | None":
+    """The review BOW id from the environment, or None when it is not set.
+
+    `environ` is passed in rather than read from `os.environ` at every call site
+    so the precedence is a pure function the tests can drive (the same shape
+    `webui.auth.require_passcode` uses). None and empty are the SAME answer: an
+    exported-but-empty variable is how a container renders "unset", and reading
+    it as an id would send `--bow ""` -- a call the CLI would take and answer
+    with nobody's tasks.
+    """
+    raw = (os.environ if environ is None else environ).get(TASK_LIST_BOW_ENV)
+    return (raw or "").strip() or None
+
+
 MIN_POLL_INTERVAL = 10  # the search API allows 30 req/min
 
 # A reviewer session that has not submitted after this long is presumed dead
@@ -343,6 +372,19 @@ class Config:
     # when the installed CLI does not advertise the flag.
     task_list_self_scope: bool = False
 
+    # The Convex `_id` of the body of work review tasks are created into. Set it
+    # and `alissa task list` is scoped to that BOW's junction rows (`--bow`)
+    # instead of the operator's whole involvement index; leave it None -- the
+    # default -- and the call shape is exactly what it has always been.
+    #
+    # Off by default because a review task OUTSIDE the configured BOW is
+    # invisible to the daemon, which is a missed round rather than a slower one,
+    # and nothing creates review tasks into a BOW until the operator's review
+    # protocol says to. Ignored when the installed CLI does not advertise the
+    # flag. See alissa.TASK_LIST_BOW_FLAG, and the README for the two ways to
+    # get the id wrong (a repo's `autodev:` feed BOW; a `mirrorInstanceId`).
+    task_list_bow_id: str | None = None
+
     dry_run: bool = False
 
     def __post_init__(self) -> None:
@@ -395,9 +437,15 @@ class Config:
         workspace_root: Path,
         file_data: Mapping[str, Any] | None = None,
         overrides: Mapping[str, Any] | None = None,
+        environ: Mapping[str, str] | None = None,
     ) -> "Config":
         """Merge the layers and validate. `overrides` entries that are None mean
-        "not specified on the CLI" and fall through to the file / defaults."""
+        "not specified on the CLI" and fall through to the file / defaults.
+
+        `environ` is the fourth layer and applies to `task_list_bow_id` alone;
+        it wins over both of the others (see the module docstring). Defaults to
+        the real environment, so callers that do not care pass nothing.
+        """
         raw: dict[str, Any] = dict(file_data or {})
 
         if "workspace_root" in raw:
@@ -419,6 +467,31 @@ class Config:
             if value is not None:
                 raw[key] = value
 
+        # Applied AFTER the CLI overrides, which is the whole of "file < CLI <
+        # env": the variable is how a container hands the daemon an id that no
+        # file on its volume and no argv in its unit carries, so it has to be
+        # able to say something the other two do not.
+        env_bow = env_task_list_bow_id(environ)
+        if env_bow is not None:
+            raw["task_list_bow_id"] = env_bow
+        bow_id = raw.get("task_list_bow_id")
+        if bow_id is not None and not isinstance(bow_id, str):
+            # Deliberately NOT the `int(...)`/`bool(...)` coercion the numeric
+            # keys around here use. Those coerce into a value the validation
+            # below them then checks; there is nothing downstream to check an
+            # id against, so `0` would coerce to a well-formed `--bow 0` that
+            # can never resolve -- landing the deployment in the empty-answer
+            # path instead of telling it anything. A misspelled KEY already
+            # fails loudly at load; a mistyped VALUE should too.
+            raise ValueError(
+                f"task_list_bow_id must be the review BOW's Convex _id as a "
+                f"string (or null for unset), got a {type(bow_id).__name__}"
+            )
+        # Normalised the same way the env layer is, so `""` from a config file
+        # or a flag means "unset" too rather than `--bow ""` -- a call the CLI
+        # takes and answers with nobody's tasks.
+        bow_id = (bow_id or "").strip() or None
+
         mode = raw.get("on_missing_review_task", ON_MISSING_SPAWN)
         if mode not in _MISSING_MODES:
             raise ValueError(
@@ -580,6 +653,7 @@ class Config:
             checks_spawn_wait_seconds=spawn_wait,
             review_task_miss_ttl_polls=miss_ttl,
             task_list_self_scope=bool(raw.get("task_list_self_scope", False)),
+            task_list_bow_id=bow_id,
             dry_run=bool(raw.get("dry_run", False)),
         )
 

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -1425,7 +1425,8 @@ class ReviewWatcher:
             config.reviewer_login, token_env=config.reviewer_token_env
         )
         self.alissa = alissa or Alissa(
-            task_list_self_scope=config.task_list_self_scope
+            task_list_self_scope=config.task_list_self_scope,
+            task_list_bow_id=config.task_list_bow_id,
         )
         self.state = state or State(config.state_db)
         # (repo, number, comment id) of every re-entry directive already
@@ -4063,6 +4064,15 @@ class ReviewWatcher:
                 "does not advertise `task list --self` — the task list is not "
                 "actor-scoped; upgrade the CLI or drop the key"
             )
+        # Read off the CLIENT, not the config: the env layer outranks both the
+        # file and the flag, so an operator who set only ALISSA_REVIEW_TASK_BOW
+        # would otherwise get no warning about the CLI that cannot serve it.
+        if self.alissa.task_list_bow_id and not self.alissa.probe_task_list().bow:
+            warnings.append(
+                "a review task BOW is configured but the installed `alissa` "
+                "CLI does not advertise `task list --bow` — the task list is "
+                "not BOW-scoped; upgrade the CLI or drop the key"
+            )
 
         if not self.config.dry_run and not self.alissa.worker_running():
             warnings.append(

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0}/src/main/alissa/tools/github/revloop/prreview.py

@@ -35,6 +35,7 @@ import sys
 import time
 
 from .alissa import Alissa, VERDICT_APPROVE, VERDICT_REQUEST_CHANGES
+from .config import env_task_list_bow_id
 from .ghclient import GitHub
 from .proc import CommandError, run, run_json
 
@@ -145,7 +146,11 @@ def main(argv: list[str] | None = None) -> int:
     )
 
     gh = GitHub()
-    alissa = Alissa()
+    # The same BOW narrowing the daemon's poll uses (issue #100), from the one
+    # channel this command has: it runs in a task worktree, so there is no
+    # revloop config file under its cwd and no daemon argv to inherit. Unset ->
+    # the call shape this command has always made.
+    alissa = Alissa(task_list_bow_id=env_task_list_bow_id())
 
     try:
         # Identity guard: GitHub forbids requesting review from the PR author, so

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

@@ -0,0 +1 @@
+0.25.0

{alissa_tools_github_revloop-0.23.0 → alissa_tools_github_revloop-0.25.0/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.23.0
+Version: 0.25.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.23.0