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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.1
+Version: 0.8.2
 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.2}/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",
@@ -267,6 +275,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,
@@ -309,12 +318,14 @@ 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",
         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,

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.2}/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",
@@ -149,6 +150,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
 
@@ -280,6 +293,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
@@ -391,6 +413,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.
@@ -433,6 +466,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(

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.2}/src/main/alissa/tools/github/devloop/loop.py

@@ -256,25 +256,58 @@ cover the window it is for. The cost is a crash between the line and the
 enqueue leaving a claim with no session -- one stale window of deferral, then
 the line ages out and the next poll spawns normally.
 
-Finally, every pass runs the SESSION REAPER: finished `develop-*`/`fix-*`
-worker sessions otherwise idle in tmux forever (observed live on the reviewer
-daemon, 2026-07-22 -- and dev workers are worse, because they block through
-entire review loops). Both directives tell the session to kill itself as its
-last act, but that self-kill is UNRELIABLE by assumption -- a session that
-crashes, stalls, or is superseded never reaches its last act -- so the sweep
-is the guarantee, not the fast path. The sweep is deliberately
+Finally, every pass runs the SESSION REAPER: finished worker sessions
+otherwise idle in tmux forever (observed live on the reviewer daemon,
+2026-07-22 -- and dev workers are worse, because they block through entire
+review loops; by 2026-07-28 the shared container had climbed past 10 GB with 4
+corpses among 12 live claude sessions). Every directive tells the session to
+kill itself as its last act, but that self-kill is UNRELIABLE by assumption --
+a session that crashes, stalls, or is superseded never reaches its last act --
+so the sweep is the guarantee, not the fast path. The sweep is deliberately
 SEARCH-INDEPENDENT, the reviewer daemon's structural lesson baked in: its
 `_reap_finished` keyed off the poll's search results and starved -- it became
 unreachable the moment the trigger state cleared, which is exactly when
 sessions finish. Here the sweep runs unconditionally at the top of poll_once,
-BEFORE the searches, off the tmux list and the local ledgers alone: it lists
-`develop-*`/`fix-*` sessions via `alissa tmux ls`, cross-references each
-against the spawn/fix ledgers and GitHub state (issue closed / PR closed or
-merged / attempt or round superseded), and kills the idle finished ones via
-`alissa tmux kill <name>` -- one session at a time, never the server. Busy
-sessions and fresh in-flight ones (ledger row younger than stale_minutes) are
-spared, dry-run only logs, and kills are best-effort: a CLI without
-`tmux kill` degrades to a once-per-process warning.
+BEFORE the searches, off the tmux list, the local ledgers, and GitHub alone.
+
+What the sweep will even LOOK at is an exact GRAMMAR, not a prefix (see
+`parse_worker_session`): `develop-<owner>-<repo>-i<n>-a<k>`,
+`fix-<owner>-<repo>-pr<n>-r<r>-a<k>`, `maintain-<owner>-<repo>-pr<n>-a<k>`,
+spelled by the very builders that name the spawns. The container is SHARED
+with other daemons' lanes and with operator shells, and this code kills
+processes: a name that does not parse is not devloop's worker and is never
+considered, let alone killed. Killing is per-session (`alissa tmux kill
+<name>`), never `kill-server` -- the server hosts every lane's workers.
+
+"Finished" is an ANCHOR question: the issue closed, or the PR closed/merged.
+The anchor is resolved twice over -- from the spawn ledgers when a row exists
+(which also yields the ledger-only supersession signals: a newer attempt or a
+newer review round ends an older session whatever GitHub says), and otherwise
+from the session NAME, whose slug is matched back to the repos allowlist and
+whose number is asked of GitHub directly. The name path is what makes the
+sweep survive the ledger: a fresh state volume, a migrated deployment, or the
+enqueue-before-ledger crash window all leave real sessions no local row can
+explain, and before it they idled forever.
+
+A reap needs THREE things at once: a terminal anchor, an IDLE session, and
+`reap_grace_minutes` (default 30) elapsed since the session's last tmux
+activity. Busy is never killed, terminal anchor or not -- post-merge close-out
+work is real (the PR #275 -> #279 replay-onto-main incident happened in
+exactly that window) -- so a busy session with a terminal anchor is LOGGED as
+a holdout, with its anchor evidence, and left alone. The grace exists so a
+just-merged PR's session can finish its in-session handoff before dying.
+Terminal-anchor-only reaping is also what makes the sweep compose with the
+respawn paths: a closed issue / merged PR has no pending work, and every edge
+re-fetches its anchor and returns before it consults session liveness, so a
+reaped session can never be resurrected as a resume.
+
+After the sweep, if the live worker sessions STILL exceed `max_sessions`, the
+pass logs loudly (ERROR, page-worthy): the reaper only kills idle sessions
+with terminal anchors, so an overflow means busy-but-terminal work is piling
+up faster than it finishes and a human should look. Reap failures never block
+the walk: a tmux error or a GitHub 404 on an anchor spares that session for
+the pass and moves on, dry-run only logs, and kills are best-effort (a CLI
+without `tmux kill` degrades to a once-per-process warning).
 """
 
 from __future__ import annotations
@@ -1451,6 +1484,21 @@ class SessionLiveness:
         return tuple(sorted(n for n in self._live if n.startswith(prefix)))
 
 
+@dataclass(frozen=True, slots=True)
+class Sweep:
+    """What ONE reaper sweep did and saw.
+
+    `reaped` counts the kills (would-kills under dry-run), `names` carries
+    them so the pass can discount them from the live-session count, and
+    `holdouts` are the sessions whose anchor is terminal but which were BUSY
+    -- never killed, by the locked guardrail, and reported because they are
+    the usual answer to "why is the machine still over the cap?"."""
+
+    reaped: int
+    names: "set[str]"
+    holdouts: "tuple[str, ...]" = ()
+
+
 class SessionBudget:
     """The per-pass concurrency budget behind `max_sessions`.
 
@@ -1640,6 +1688,151 @@ def maintain_session_name(pr: PullRequest, attempt: int) -> str:
     return f"{pr_session_prefix(pr, 'maintain')}a{attempt}"
 
 
+# The reaper's GRAMMAR: devloop's own worker session names, read back. Each
+# expression is the exact shape its builder above writes -- `_name_slug`
+# lowercases and squashes to `[a-z0-9-]`, so the slug alphabet is stated once
+# here and nowhere else. The slug is greedy on purpose: it must swallow every
+# dash of `<owner>-<repo>` and stop at the LAST `-i<n>-a<k>` / `-pr<n>-...`
+# tail, which is the only split the builders can ever have produced.
+_DEVELOP_NAME_RE = re.compile(r"develop-(?P<slug>[a-z0-9-]+)-i(?P<number>\d+)-a(?P<attempt>\d+)")
+_FIX_NAME_RE = re.compile(
+    r"fix-(?P<slug>[a-z0-9-]+)-pr(?P<number>\d+)-r(?P<round>\d+)-a(?P<attempt>\d+)"
+)
+_MAINTAIN_NAME_RE = re.compile(r"maintain-(?P<slug>[a-z0-9-]+)-pr(?P<number>\d+)-a(?P<attempt>\d+)")
+
+# The three edges' names for themselves, as they appear in a session name and
+# in the reaper's log evidence.
+EDGE_DEVELOP = "develop"
+EDGE_FIX = "fix"
+EDGE_MAINTAIN = "maintain"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerSession:
+    """One tmux session name parsed back into the anchor it works on.
+
+    The reaper's admission ticket AND its anchor resolver in one object: a
+    name that parses is provably one of devloop's own workers (see
+    `parse_worker_session`), and what it parses INTO -- the repo slug, the
+    issue or PR number -- is the anchor whose terminal state decides whether
+    the session still has a reason to exist. The `slug` is the NAME slug
+    (`<owner>-<repo>` squashed by `_name_slug`), not an `owner/repo`: the
+    squash is lossy (`a/b-c` and `a-b/c` both slug to `a-b-c`), so turning
+    it back into a repo is the allowlist's job, never a string split's.
+    """
+
+    name: str
+    edge: str
+    slug: str
+    number: int
+    attempt: int
+    round_: "int | None" = None
+
+    @property
+    def is_issue(self) -> bool:
+        """Only the develop edge anchors on an issue; both PR edges do not."""
+        return self.edge == EDGE_DEVELOP
+
+    @property
+    def anchor(self) -> str:
+        """The anchor as log evidence: `acme-widgets issue #7`. Every reap and
+        every busy holdout line carries it -- a kill with no stated reason is
+        not auditable after the fact, which is the whole complaint against the
+        self-kill this sweep backstops."""
+        return f"{self.slug} {'issue' if self.is_issue else 'PR'} #{self.number}"
+
+
+def parse_worker_session(name: str) -> "WorkerSession | None":
+    """A tmux session name as one of devloop's own workers, or None.
+
+    THE guard on everything the reaper touches. The container is shared --
+    reviewloop's sessions, other instances' lanes, operator shells -- so
+    "is this mine?" is answered by a full-match against the grammar the three
+    session-name builders write (`session_name`, `fix_session_name`,
+    `maintain_session_name`), never by a prefix: `develop-` matches anything
+    an operator felt like naming that way, and this code kills processes.
+    Non-matching names are not spared after a check; they are never
+    CONSIDERED, which is the property the tests pin.
+    """
+    match = _DEVELOP_NAME_RE.fullmatch(name)
+    if match:
+        return WorkerSession(
+            name=name,
+            edge=EDGE_DEVELOP,
+            slug=match["slug"],
+            number=int(match["number"]),
+            attempt=int(match["attempt"]),
+        )
+    match = _FIX_NAME_RE.fullmatch(name)
+    if match:
+        return WorkerSession(
+            name=name,
+            edge=EDGE_FIX,
+            slug=match["slug"],
+            number=int(match["number"]),
+            attempt=int(match["attempt"]),
+            round_=int(match["round"]),
+        )
+    match = _MAINTAIN_NAME_RE.fullmatch(name)
+    if match:
+        return WorkerSession(
+            name=name,
+            edge=EDGE_MAINTAIN,
+            slug=match["slug"],
+            number=int(match["number"]),
+            attempt=int(match["attempt"]),
+        )
+    return None
+
+
+def _casefolded(repo: "tuple[str, str]") -> "tuple[str, str]":
+    """An (owner, repo) pair as `Config.watches` compares it: casefolded."""
+    return (repo[0].casefold(), repo[1].casefold())
+
+
+def _slug_index(repos: "tuple[str, ...]") -> "dict[str, tuple[str, str]]":
+    """`{name slug: (owner, repo)}` over the repos allowlist -- the reverse of
+    `_name_slug`, which is the only way a session NAME can name a repo.
+
+    The squash is lossy -- `a/b-c` and `a-b/c` both slug to `a-b-c`, and a
+    squashed character can manufacture the same clash (`acme/wid.gets` and
+    `acme/wid-gets` both slug to `acme-wid-gets`, and a dot in a repo name is
+    ordinary) -- so an allowlist that collides two repos onto one slug leaves
+    that slug UNRESOLVABLE rather than guessing: the
+    consumer is a reaper, and killing the right session for the wrong repo's
+    reason is exactly the mistake worth failing closed on. Entries that are
+    not `owner/repo` are ignored -- `Config.watches` would never match them
+    either.
+
+    Two spellings of the SAME repo are not a collision. `Config.watches`
+    matches casefolded ("GitHub owner/repo names are case-insensitive"), so
+    `["Acme/Widgets", "acme/widgets"]` is one watched repo everywhere else in
+    the daemon; comparing raw here would fail closed on a duplicate that does
+    not exist, silently turning the name-anchored reap off for that repo and
+    sending an operator looking for a second one.
+    """
+    index: dict[str, tuple[str, str]] = {}
+    collided: set[str] = set()
+    for entry in repos:
+        owner, sep, repo = entry.partition("/")
+        if not sep or not owner or not repo:
+            continue
+        slug = _name_slug(owner, repo)
+        seen = index.get(slug)
+        if seen is not None and _casefolded(seen) != _casefolded((owner, repo)):
+            collided.add(slug)
+        index[slug] = (owner, repo)
+    for slug in collided:
+        log.warning(
+            "reaper: two allowlisted repos share the session-name slug %r — "
+            "sessions carrying it cannot be resolved to a repo from their "
+            "name and will only be reaped when the ledger knows them",
+            slug,
+        )
+        index.pop(slug, None)
+    return index
+
+
 def orphan_activity_lane(pr: PullRequest) -> str:
     """`orphan-<owner>-<repo>-pr<n>` — the name the orphan sweep signs its
     activity line with.
@@ -1787,6 +1980,10 @@ class DevWatcher:
         # The reaper's warn-once latch for a CLI without `tmux kill` (kills
         # are best-effort; the condition is per-process, not per-session).
         self._kill_warned = False
+        # The reaper's name-slug -> (owner, repo) index (see `_anchor_repo`),
+        # built once from the frozen allowlist rather than per session per
+        # sweep.
+        self._slug_repos = _slug_index(config.repos)
 
     # -- per-issue decision ------------------------------------------------
 
@@ -4888,22 +5085,14 @@ class DevWatcher:
 
     # -- the session reaper ------------------------------------------------
 
-    # Worker-session name prefixes. The reaper SWEEPS the first two
-    # (`develop-*`/`fix-*` -- a maintenance session's terminal act is its own
-    # label removal + self-kill, and `_session_finished` has no maintain
-    # branch), but the max_sessions budget COUNTS all three: a live
-    # maintenance session consumes memory whether or not the sweep reaps it.
-    _REAP_PREFIXES = ("develop-", "fix-")
-    _WORKER_PREFIXES = ("develop-", "fix-", "maintain-")
-
     def reap_finished(self) -> int:
-        """The sweep: kill idle, finished `develop-*`/`fix-*` sessions.
-        Returns how many were killed (or would be, under dry-run).
+        """The sweep: kill idle, finished worker sessions whose anchor is
+        terminal. Returns how many were killed (or would be, under dry-run).
 
         Lists the managed sessions itself and delegates the per-session work
         to `_reap_sessions`. `poll_once` takes a different path -- it lists
-        ONCE and feeds that same listing to both the sweep and the
-        max_sessions count -- so the tmux CLI is hit exactly once per pass;
+        ONCE and feeds that same listing to the sweep, the max_sessions count,
+        and the cap check -- so the tmux CLI is hit exactly once per pass;
         this standalone entry point stays for callers (and tests) that just
         want a sweep. See `_reap_sessions` for the finished-detection
         contract."""
@@ -4913,41 +5102,72 @@ class DevWatcher:
             log.warning("reaper: could not list sessions (%s) — skipping "
                         "this sweep", exc)
             return 0
-        reaped, _ = self._reap_sessions(sessions)
-        return reaped
-
-    def _reap_sessions(self, sessions: "list[dict]") -> "tuple[int, set[str]]":
-        """Kill the idle, finished `develop-*`/`fix-*` sessions in `sessions`.
-        Returns (count reaped, the set of reaped names) -- the name set lets
-        `poll_once` discount them from the live-session count so a sweep frees
-        max_sessions capacity in the same pass.
-
-        Runs off the tmux list and the local ledgers alone -- never the polls'
-        search results (the reviewer daemon's `_reap_finished` starved exactly
-        there: keyed off the search, it became unreachable once the trigger
-        state cleared, which is when sessions finish). "Finished" needs a
-        positive signal per session: the issue closed, the PR closed/merged,
-        or a newer attempt/round on the ledger superseded it. Everything else
-        is spared -- busy sessions, fresh in-flight ones (row younger than
-        stale_minutes, the same grace the retry logic uses), sessions this
-        ledger does not know (another workspace's, or the documented
-        enqueue-before-ledger crash window), and sessions whose GitHub check
-        fails this pass. Kills go through `alissa tmux kill <name>` one session
-        at a time (never the server) and are best-effort; dry-run only logs
-        (and still counts the would-kill, so the freed capacity matches what a
-        live pass would free)."""
+        return self._reap_sessions(sessions).reaped
+
+    def _reap_sessions(self, sessions: "list[dict]") -> Sweep:
+        """Kill the idle, finished worker sessions in `sessions`, and report
+        what the sweep saw (see `Sweep`) -- the reaped NAMES let `poll_once`
+        discount them from the live-session count, so a sweep frees
+        max_sessions capacity in the same pass it runs.
+
+        Runs off the tmux list, the local ledgers, and GitHub alone -- never
+        the polls' search results (the reviewer daemon's `_reap_finished`
+        starved exactly there: keyed off the search, it became unreachable
+        once the trigger state cleared, which is when sessions finish).
+
+        Three conditions, ALL required (see the module docstring):
+
+        * the name parses as one of devloop's own workers
+          (`parse_worker_session`); anything else is never considered;
+        * the anchor is TERMINAL -- the issue closed, the PR closed/merged, or
+          the ledger shows a newer attempt/round superseding this session;
+        * the session is IDLE and its last tmux activity is older than
+          `reap_grace_minutes`.
+
+        Everything else is spared: busy sessions (logged as holdouts once the
+        anchor is known terminal -- never killed, whatever the anchor says),
+        sessions still inside the grace, sessions whose slug matches no
+        allowlisted repo AND no ledger row, and sessions whose GitHub check
+        fails this pass. The idle-and-still-in-grace check is deliberately
+        cheap and runs BEFORE the anchor fetch, so a quiet machine's fresh
+        sessions cost no API calls; a BUSY session does pay the fetch, because
+        the holdout log has to state the anchor evidence it is holding out on.
+        Kills go through `alissa tmux kill <name>` one session at a time
+        (never `kill-server` -- the container is shared) and are best-effort;
+        dry-run only logs (and still counts the would-kill, so the freed
+        capacity matches what a live pass would free)."""
         reaped = 0
         reaped_names: set[str] = set()
+        holdouts: list[str] = []
         for entry in sessions:
             name = str(entry.get("name") or "")
-            if not name.startswith(self._REAP_PREFIXES):
+            worker = parse_worker_session(name)
+            if worker is None:
+                # Not devloop's grammar: another daemon's lane, an operator
+                # shell, a console. Never touched, never even looked up.
                 continue
             if entry.get("live") is False:
                 # A registered-but-gone session has no tmux session to kill;
                 # `alissa tmux cleanup` owns purging stale registrations.
                 continue
+            idle = entry.get("status") == "idle"
+            quiet_for = self._session_quiet_for(entry, worker)
+            graced = (
+                quiet_for is not None
+                and quiet_for >= self.config.reap_grace_seconds
+            )
+            if idle and not graced:
+                log.debug(
+                    "reaper: %s is idle but inside the grace (%s of %d min) "
+                    "— spared",
+                    name,
+                    "unknown activity" if quiet_for is None
+                    else f"quiet {int(quiet_for / 60)} min",
+                    self.config.reap_grace_seconds // 60,
+                )
+                continue
             try:
-                verdict = self._session_finished(name)
+                verdict = self._session_finished(worker)
             except CommandError as exc:
                 log.warning(
                     "reaper: could not cross-reference %s (%s) — spared "
@@ -4956,14 +5176,25 @@ class DevWatcher:
                 continue
             if verdict is None:
                 continue
-            if entry.get("status") != "idle":
-                log.debug(
-                    "reaper: %s is finished (%s) but not idle (%s) — spared",
-                    name, verdict, entry.get("status"),
+            if not idle:
+                # The locked guardrail: a terminal anchor never licenses
+                # killing a WORKING session. Post-merge close-out is real work
+                # (the PR #275 -> #279 replay-onto-main incident happened in
+                # this window), so this is logged as evidence for a human, at
+                # a level an operator sees without -v, and left alone.
+                log.warning(
+                    "reaper: HOLDOUT %s — anchor %s is terminal (%s) but the "
+                    "session is %s, not idle; never killing a busy session",
+                    name, worker.anchor, verdict, entry.get("status"),
                 )
+                holdouts.append(name)
                 continue
             if self.config.dry_run:
-                log.info("[dry-run] would kill session %s (%s)", name, verdict)
+                log.info(
+                    "[dry-run] would kill session %s (anchor %s: %s; quiet "
+                    "%d min)",
+                    name, worker.anchor, verdict, int((quiet_for or 0) / 60),
+                )
                 reaped += 1
                 reaped_names.add(name)
                 continue
@@ -4981,25 +5212,65 @@ class DevWatcher:
                 else:
                     log.debug("reaper: could not kill %s (%s)", name, exc)
                 continue
-            log.info("reaper: killed finished session %s (%s)", name, verdict)
+            log.info(
+                "reaper: killed finished session %s (anchor %s: %s; quiet "
+                "%d min)",
+                name, worker.anchor, verdict, int((quiet_for or 0) / 60),
+            )
             reaped += 1
             reaped_names.add(name)
-        return reaped, reaped_names
+        return Sweep(reaped=reaped, names=reaped_names, holdouts=tuple(holdouts))
+
+    def _session_quiet_for(
+        self, entry: "dict", worker: WorkerSession
+    ) -> "float | None":
+        """Seconds since this session last did anything, or None when nothing
+        can date it.
+
+        `alissa tmux ls --json` carries `lastActivity` (unix seconds) per
+        session -- the signal the grace period is actually about: a session
+        that is still typing is not a corpse however old its spawn is. When
+        the listing does not carry one (an older CLI), the spawn ledger's row
+        is the fallback lower bound, which is the clock every other
+        presumed-dead decision in this loop already runs on. Neither
+        available means the sweep CANNOT date the session, and `None` reads as
+        "no grace has provably elapsed" at the call site -- never kill what
+        cannot be dated. Clamped at 0 like every other age here: `lastActivity`
+        is wall-clock and an NTP step must not read as a long-quiet session."""
+        stamp = entry.get("lastActivity")
+        last: "int | None"
+        try:
+            last = int(stamp)  # type: ignore[arg-type]  # non-numeric -> except
+        except (TypeError, ValueError):
+            last = None
+        if last is None:
+            row = (
+                self.state.spawn_for_session(worker.name)
+                or self.state.fix_spawn_for_session(worker.name)
+                or self.state.maintain_spawn_for_session(worker.name)
+            )
+            last = int(row["spawned_at"]) if row is not None else None
+        if last is None:
+            return None
+        return max(0.0, time.time() - last)
 
     def _count_active_sessions(
         self, sessions: "list[dict]", reaped_names: "set[str]"
     ) -> int:
         """How many worker sessions are live and NOT reaped this pass -- the
-        `active` half of the max_sessions budget. Counts every
-        `develop-*`/`fix-*`/`maintain-*` session the CLI reports as live
-        (busy AND fresh in-flight ones alike -- both are holding memory),
-        minus the ones the sweep just killed (a registered-but-gone `live:
-        False` row is already dead, so it never counted). Read from the SAME
-        listing the sweep used, so counting adds no CLI call."""
+        `active` half of the max_sessions budget, and the number the post-sweep
+        cap check judges. Counts every session whose name parses as one of
+        devloop's own workers (`parse_worker_session` -- the same grammar the
+        sweep admits, so the budget and the reaper can never disagree about
+        what a worker is), live, busy AND fresh in-flight ones alike (both are
+        holding memory), minus the ones the sweep just killed (a
+        registered-but-gone `live: False` row is already dead, so it never
+        counted). Read from the SAME listing the sweep used, so counting adds
+        no CLI call."""
         active = 0
         for entry in sessions:
             name = str(entry.get("name") or "")
-            if not name.startswith(self._WORKER_PREFIXES):
+            if parse_worker_session(name) is None:
                 continue
             if entry.get("live") is False:
                 continue
@@ -5034,27 +5305,64 @@ class DevWatcher:
                 "reads INDETERMINATE (no resume can fire)", exc,
             )
             return 0, SessionBudget(None, 0), SessionLiveness(None)
-        reaped, reaped_names = self._reap_sessions(sessions)
-        active = self._count_active_sessions(sessions, reaped_names)
+        sweep = self._reap_sessions(sessions)
+        active = self._count_active_sessions(sessions, sweep.names)
+        self._check_session_cap(active, sweep)
         return (
-            reaped,
+            sweep.reaped,
             SessionBudget(limit, active),
-            SessionLiveness(sessions, reaped_names),
+            SessionLiveness(sessions, sweep.names),
+        )
+
+    def _check_session_cap(self, active: int, sweep: Sweep) -> None:
+        """Page-worthy log when the machine is STILL over `max_sessions` after
+        the sweep.
+
+        The sweep is bounded by design -- it only kills idle sessions with
+        terminal anchors -- so it cannot be the answer to every kind of
+        overload. Sessions that stay over the cap after it ran are, by
+        elimination, busy ones (holdouts and live work) or sessions no anchor
+        marks terminal: the daemon has done everything it may safely do and
+        the excess is a human's call. Logged at ERROR for exactly that reason,
+        with the holdouts named, because that list is usually the answer.
+        `max_sessions=0` (unlimited, the default) configures no cap, so there
+        is nothing to exceed and nothing to say."""
+        limit = self.config.max_sessions
+        if not limit or active <= limit:
+            return
+        log.error(
+            "SESSION CAP EXCEEDED: %d live worker session(s) after the sweep, "
+            "over max_sessions=%d. The reaper only kills IDLE sessions whose "
+            "anchor is terminal, so the excess is busy or unfinished work and "
+            "no sweep will clear it — a human should look%s",
+            active,
+            limit,
+            (
+                "; busy-but-terminal holdout(s) this pass: "
+                + ", ".join(sweep.holdouts)
+                if sweep.holdouts else " (no busy-but-terminal holdouts this "
+                "pass — the live sessions are on open anchors)"
+            ),
         )
 
-    def _session_finished(self, name: str) -> "str | None":
+    def _session_finished(self, worker: WorkerSession) -> "str | None":
         """Why this worker session is finished, or None to spare it.
 
-        The cheap checks run first: the ledger lookup (no match -> spare:
-        not provably ours), the fresh-in-flight grace (no GitHub call for a
-        session younger than stale_minutes -- it may still be initializing,
-        and a finished one waits at most one stale window for the sweep),
-        and ledger supersession (a newer attempt/round exists, so this
-        session's episode is over whatever GitHub says). Only a stale,
-        non-superseded session costs a GitHub fetch, whose closed/merged
-        state is the terminal signal. CommandError propagates to the caller
-        (spare this pass); RateLimited propagates further out to
+        Two resolutions of one question -- is this session's anchor terminal?
+        The LEDGER answers first when it has a row, because a row carries what
+        a name cannot: supersession (a newer attempt, a newer review round
+        ends this session's episode whatever GitHub says) and the spawn
+        instant that keeps a just-enqueued session off the GitHub path
+        entirely. With no row -- a fresh state volume, a migrated deployment,
+        another workspace's ledger, or the enqueue-before-ledger crash window
+        -- the session NAME answers instead (`_anchor_finished`), which is the
+        path that stops ledger-less corpses idling forever.
+
+        Only a stale, non-superseded session costs a GitHub fetch, whose
+        closed/merged state is the terminal signal. CommandError propagates to
+        the caller (spare this pass); RateLimited propagates further out to
         run_forever's backoff, like every other GitHub call in the pass."""
+        name = worker.name
         row = self.state.spawn_for_session(name)
         if row is not None:
             slug, number = row["repo_slug"], row["issue"]
@@ -5086,11 +5394,56 @@ class DevWatcher:
                 return "PR closed/merged"
             return None
 
-        log.debug(
-            "reaper: %s matches a worker name but is not on this ledger — "
-            "spared (another workspace's session, or the "
-            "enqueue-before-ledger crash window)", name,
-        )
+        row = self.state.maintain_spawn_for_session(name)
+        if row is not None:
+            slug, number = row["repo_slug"], row["number"]
+            if time.time() - row["spawned_at"] < self.config.stale_minutes * 60:
+                return None
+            # One supersession axis only: the maintenance edge has no rounds,
+            # and `maintain_max_attempt` is deliberately lifetime-scoped (a
+            # re-label resets the budget, not the numbering), so an older
+            # attempt's session is over whichever request spawned the newer.
+            newest = self.state.maintain_max_attempt(slug, number)
+            if row["attempt"] < newest:
+                return f"superseded by attempt {newest}"
+            owner, _, repo = slug.partition("/")
+            if self.github.pull_request(owner, repo, number).state != "open":
+                return "PR closed/merged"
+            return None
+
+        return self._anchor_finished(worker)
+
+    def _anchor_finished(self, worker: WorkerSession) -> "str | None":
+        """The ledger-free half of `_session_finished`: is the anchor named by
+        the SESSION NAME terminal?
+
+        The name is not a weaker signal than a ledger row, it is a different
+        one -- it survives the ledger. The 2026-07-28 fleet incident was
+        exactly this shape: idle workers whose PRs had merged hours earlier,
+        with nothing local left to explain them. What the name cannot do is
+        name a REPO (`_name_slug` is lossy), so the slug is resolved through
+        the repos allowlist (`_slug_index`); a slug matching no watched repo
+        is another workspace's or another owner's and is spared, never
+        guessed at. Supersession is unavailable here by construction -- it is
+        a ledger fact -- so this path reaps on the anchor alone, which is the
+        conservative half anyway: a closed issue and a merged PR have no
+        pending work for anyone."""
+        repo = self._slug_repos.get(worker.slug)
+        if repo is None:
+            log.debug(
+                "reaper: %s parses as a worker but its slug %r matches no "
+                "watched repo and no ledger row — spared (another "
+                "workspace's session, or a repo this daemon does not watch)",
+                worker.name, worker.slug,
+            )
+            return None
+        owner, name = repo
+        if worker.is_issue:
+            if self.github.issue(owner, name, worker.number).state != "open":
+                return "issue closed (anchor read from the session name)"
+            return None
+        if self.github.pull_request(owner, name, worker.number).state != "open":
+            return "PR closed/merged (anchor read from the session name)"
         return None
 
     # -- polling -----------------------------------------------------------

{alissa_tools_github_devloop-0.8.1 → alissa_tools_github_devloop-0.8.2}/src/main/alissa/tools/github/devloop/state.py

@@ -395,6 +395,19 @@ class State:
             (session,),
         ).fetchone()
 
+    def maintain_spawn_for_session(self, session: str) -> "sqlite3.Row | None":
+        """maintain_spawns counterpart of spawn_for_session: the row behind a
+        maintenance session name (repo_slug, PR number, attempt), or None when
+        the name is not on this ledger. The third of the reaper's three ledger
+        lookups -- a maintenance session holds as much memory as any other
+        worker, so the sweep resolves its anchor the same way."""
+        return self._db.execute(
+            "SELECT repo_slug, number, attempt, spawned_at "
+            "FROM maintain_spawns WHERE session=? "
+            "ORDER BY spawned_at DESC LIMIT 1",
+            (session,),
+        ).fetchone()
+
     def max_fix_round(self, repo_slug: str, number: int) -> int:
         """The newest round any fix session was spawned for on this PR (0
         when none) -- the reaper's supersession horizon: a fix session whose

alissa_tools_github_devloop-0.8.2/src/main/alissa/tools/github/devloop/version

@@ -0,0 +1 @@
+0.8.2

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

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

alissa_tools_github_devloop-0.8.1/src/main/alissa/tools/github/devloop/version

@@ -1 +0,0 @@
-0.8.1