alissa-tools-github-genloop 0.1.0__py3-none-any.whl

alissa/tools/github/genloop/loop.py

@@ -0,0 +1,971 @@
+"""The genloop seat: a mechanical daemon shaped like orcloop's sentinel edge
+(design D14, §1.1). One decision line per poll, `genloop: <term>; <term>; …`.
+
+ONE POLL, IN ORDER
+==================
+0. **Enabled.** With `ALISSA_GEN_ENABLED` unset the seat idles, logs why, and
+   touches nothing -- no listing, no read, no write (L9).
+1. **Ingest.** Every `<state>/passes/<stamp>.json` not yet ingested is parsed
+   against the directive's schema. A `plan` verdict is DELIVERED by the seat:
+   the plan's frontmatter is read from the pushed branch, the program's budget
+   re-checked, ONE PR opened (or the open one for that branch reused, so a
+   crash re-run never opens a second), the marker and both trailers in its
+   body, the reviewer requested, one `POST /v1/loop/plans` (`proposed`) and one
+   `plan.proposed`. Only then is the record marked ingested and moved to
+   `passes/ingested/`, so it is never replayed once the ledger row ages out
+   (a record older than the ledger window is archived unread). `idle` records
+   emit their `plan.skipped` lines; `amended` PRs get the reviewer re-requested;
+   `skill-missing` holds every further spawn until the image is fixed.
+2. **Lint watch.** A plan PR of ours whose `plan-lint` run concluded `failure`
+   is the generator's to amend on its next pass (D13). One still red after a
+   pass SPAWNED after the red was first seen has ended is `plan.invalid`: a
+   comment, the PR closed, the branch deleted, the plan row `rejected`.
+3. **Rejections.** A plan PR closed unmerged with a comment by an operator
+   login, or an operator comment opening `[do-not-propose]`, writes one
+   `proposalRules` row per source key and one for the anchor (§4.4, c7).
+4. **Spawn gate**, walked in the design's order with one term each --
+   enabled, not parked, budget, the day bound, the lane bound, no live
+   `ali-genloop-*` session (a failed listing holds), a worker present -- then
+   ONE `genloop-<stamp>` session is enqueued under the byte-pinned directive.
+   The clock and the `spawn:<stamp>` row are written only AFTER the enqueue
+   (L5: claim on spawn only); a held poll writes nothing to the ledger, and
+   the four named skips (budget, parked, the day bound, the lane bound) emit
+   one event per interval.
+5. **Stale floor.** A live pass older than `stale_intervals x interval` is
+   killed (only ever our own) and `pass.stalled` emitted once.
+6. **Silence floor.** A spawned pass that ended (absent from a SUCCESSFUL
+   listing and from the queue, past the grace) with no record is
+   `pass.silent`, once.
+
+Every side effect is `dry_run`-gated.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from typing import Callable, Sequence
+
+from .alissa_cli import AlissaCli
+from .alissa_client import AlissaAuthError, AlissaClient, AlissaError, AlissaTransient
+from .config import BOW_PREFIX, REPOS_SOURCE_STATIC, Config
+from .github import GitHub, PullRequest
+from .loop_events import (
+    KIND_PASS_IDLE,
+    KIND_PASS_SILENT,
+    KIND_PASS_STALLED,
+    KIND_PLAN_INVALID,
+    KIND_PLAN_PROPOSED,
+    KIND_PLAN_SKIPPED,
+    LoopEventRecorder,
+)
+from .pass_directive import (
+    DIRECTIVE_SHA256,
+    PASSES_DIRNAME,
+    SESSION_PREFIX,
+    SESSION_TMUX_PREFIX,
+    STAMP_FORMAT,
+    VERDICT_IDLE,
+    VERDICT_PLAN,
+    VERDICT_SKILL_MISSING,
+    PassRecord,
+    PassRecordError,
+    parse_pass_record,
+    render_directive,
+    session_name,
+)
+from .plan import (
+    PLAN_BRANCH_RE,
+    PLAN_MARKER,
+    Plan,
+    PlanError,
+    anchor_rule_pattern,
+    parse_plan,
+    render_pr_body,
+    render_pr_title,
+    task_file_names,
+)
+from .proc import CommandError
+from .state import LEDGER_MAX_AGE_SECONDS, State
+
+log = logging.getLogger(__name__)
+
+# A spawned session that left the listing this recently may still be writing.
+SPAWN_GRACE_SECONDS = 120
+
+META_LAST_SPAWN = "last_spawn"
+META_LAST_SETTLED = "last_settled_spawn"
+META_RED_SINCE = "red_since:"          # red_since:<pr> -> epoch the lint was first seen red
+
+# An ingested record is moved here, so ingestion outlives the ledger's
+# `ingested:<stamp>` row (which ages out); archived records age out with it.
+INGESTED_DIRNAME = "ingested"
+
+SPAWN_PREFIX = "spawn:"
+INGESTED_PREFIX = "ingested:"
+STALLED_PREFIX = "stalled:"
+SILENT_PREFIX = "silent:"
+INVALID_PREFIX = "invalid:"
+REJECTED_PREFIX = "rejected:"
+RULE_PREFIX = "rule:"
+
+# The named skip reasons (c6) and the event each one emits.
+SKIP_BUDGET = "budget"
+SKIP_PARKED = "parked"
+SKIP_BOUND = "bound"
+BOUND_DAY = "plans-per-day"
+BOUND_LANES = "open-lanes"
+
+DO_NOT_PROPOSE = "[do-not-propose]"
+RULE_REASON_MAX = 2000
+CLOSED_PLANS_PER_POLL = 30
+REJECTION_WINDOW_SECONDS = 30 * 86400
+# An operator comment counts as the rejection's reason only when it was
+# written at the close or just before it ("closing because …", then close).
+REJECTION_COMMENT_SKEW_SECONDS = 600
+
+INVALID_COMMENT = (
+    "**genloop: plan.invalid** — `plan-lint` concluded `failure` on this plan and was still "
+    "red after the next genloop pass ended (design D14). The seat closes the PR and deletes "
+    "`{branch}`; the sources it carried are free to be proposed again."
+)
+
+
+def stamp_at(epoch: float) -> str:
+    return datetime.datetime.fromtimestamp(int(epoch), datetime.timezone.utc).strftime(STAMP_FORMAT)
+
+
+def stamp_epoch(stamp: str) -> int | None:
+    try:
+        parsed = datetime.datetime.strptime(stamp, STAMP_FORMAT)
+    except ValueError:
+        return None
+    return int(parsed.replace(tzinfo=datetime.timezone.utc).timestamp())
+
+
+def utc_day(epoch: float) -> str:
+    return datetime.datetime.fromtimestamp(int(epoch), datetime.timezone.utc).strftime("%Y-%m-%d")
+
+
+def iso_epoch(text: str) -> int | None:
+    try:
+        return int(datetime.datetime.strptime(text, "%Y-%m-%dT%H:%M:%SZ")
+                   .replace(tzinfo=datetime.timezone.utc).timestamp())
+    except ValueError:
+        return None
+
+
+def session_stamp(entry: dict) -> str | None:
+    """The stamp of a listing row that is one of OUR sessions, else None."""
+    name = entry.get("name")
+    if isinstance(name, str) and name.startswith(SESSION_PREFIX):
+        return name[len(SESSION_PREFIX):]
+    session = entry.get("session")
+    if isinstance(session, str) and session.startswith(SESSION_TMUX_PREFIX):
+        return session[len(SESSION_TMUX_PREFIX):]
+    return None
+
+
+def live_stamps(listing: Sequence[dict]) -> list[str]:
+    """Stamps of our sessions the listing shows LIVE (a row without `live`
+    counts as live -- the conservative reading for a double-spawn gate)."""
+    out = []
+    for entry in listing:
+        stamp = session_stamp(entry)
+        if stamp is not None and entry.get("live") is not False:
+            out.append(stamp)
+    return out
+
+
+def _scope(row: dict) -> dict:
+    scope = row.get("scope")
+    return scope if isinstance(scope, dict) else {}
+
+
+def fleet_row(records: Sequence[dict]) -> dict:
+    for row in records:
+        if _scope(row).get("kind") == "fleet":
+            return row
+    return {}
+
+
+def program_row(records: Sequence[dict], project_id: str) -> dict:
+    for row in records:
+        scope = _scope(row)
+        if scope.get("kind") == "program" and scope.get("projectId") == project_id:
+            return row
+    return {}
+
+
+def parse_bow_repo(title: str) -> str | None:
+    """`autodev: owner/repo` -> `owner/repo`."""
+    if not title.lower().startswith(BOW_PREFIX):
+        return None
+    repo = title[len(BOW_PREFIX):].strip()
+    return repo if re.match(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$", repo) else None
+
+
+def is_plan_pr(pr: PullRequest, login: str) -> bool:
+    """Ours: authored by the seat's login, on a `PLAN-` branch, with the marker
+    on a line of its own."""
+    return (
+        pr.author == login
+        and bool(PLAN_BRANCH_RE.match(pr.head_ref))
+        and any(line.strip() == PLAN_MARKER for line in pr.body.split("\n"))
+    )
+
+
+class GenLoop:
+    def __init__(
+        self,
+        config: Config,
+        *,
+        state: State,
+        alissa: AlissaClient,
+        github: GitHub,
+        cli: AlissaCli,
+        events: LoopEventRecorder,
+        now: Callable[[], float] | None = None,
+    ):
+        self.config = config
+        self.state = state
+        self.alissa = alissa
+        self.github = github
+        self.cli = cli
+        self.events = events
+        self._now = now or time.time
+        self._login: str | None = config.login or None
+        # A `skill-missing` record holds every spawn for the life of the
+        # process: installing the skill means a new image, i.e. a restart.
+        self._skill_missing: str | None = None
+        self._rules_refused_logged = False
+        # One plan-PR listing per state per poll (the lint watch and the
+        # rejection step both read the open ones).
+        self._pulls: dict[str, list[PullRequest] | None] = {}
+
+    # -- paths -------------------------------------------------------------
+
+    @property
+    def passes_dir(self) -> Path:
+        return self.config.state_path / PASSES_DIRNAME
+
+    def record_path(self, stamp: str) -> Path:
+        return self.passes_dir / f"{stamp}.json"
+
+    @property
+    def archive_dir(self) -> Path:
+        return self.passes_dir / INGESTED_DIRNAME
+
+    @property
+    def repo(self) -> str:
+        return self.config.plans_repository
+
+    # -- the poll ----------------------------------------------------------
+
+    def poll(self) -> str:
+        if not self.config.enabled:
+            log.info(
+                "genloop: idle — ALISSA_GEN_ENABLED is not set (the seat is off by default, design "
+                "L9); set ALISSA_GEN_ENABLED=true to run passes"
+            )
+            return "disabled(ALISSA_GEN_ENABLED unset)"
+        now = int(self._now())
+        terms: list[str] = []
+        self._pulls = {}
+        listing = self._listing()
+        terms.extend(self._ingest(now))
+        terms.extend(self._lint_watch(now))
+        terms.extend(self._rejections(now))
+        terms.append(self._spawn_gate(now, listing))
+        terms.extend(self._stale_floor(now, listing))
+        terms.extend(self._silence_floor(now, listing))
+        self.events.flush()
+        if not self.config.dry_run:
+            self.state.age_out(now=now)
+            self._prune_archive(now)
+        line = "; ".join(t for t in terms if t)
+        log.info("genloop: %s", line)
+        return line
+
+    def _listing(self) -> list[dict] | None:
+        try:
+            return self.cli.list_sessions()
+        except CommandError as exc:
+            log.warning("genloop: `alissa tmux ls --json` did not answer (%s) — holding", exc)
+            return None
+
+    def login(self) -> str | None:
+        if self._login is None:
+            try:
+                self._login = self.github.current_login()
+            except CommandError as exc:
+                log.warning("genloop: could not read this seat's GitHub login (%s)", exc)
+                return None
+        return self._login
+
+    def _settle(self, stamp: str) -> None:
+        """A pass ended (ingested, stalled or silent): the lint watch's clock."""
+        epoch = stamp_epoch(stamp)
+        if epoch is None:
+            return
+        raw = self.state.get_meta(META_LAST_SETTLED)
+        if raw is None or int(raw) < epoch:
+            self.state.set_meta(META_LAST_SETTLED, str(epoch))
+
+    # -- 1. ingest ---------------------------------------------------------
+
+    def _ingest(self, now: int) -> list[str]:
+        try:
+            files = sorted(self.passes_dir.glob("*.json"))
+        except OSError:
+            return []
+        terms = []
+        for path in files:
+            stamp = path.stem
+            epoch = stamp_epoch(stamp)
+            if epoch is None:
+                continue
+            if self.state.has(INGESTED_PREFIX + stamp):
+                # Ingested, but the move to the archive failed: retry it.
+                if not self.config.dry_run:
+                    self._archive(stamp)
+                continue
+            if now - epoch > LEDGER_MAX_AGE_SECONDS:
+                # Older than the ledger remembers: it may have been ingested
+                # already, and replaying it could undo an operator's later
+                # decision (re-request, `proposed` over `parked`). Never replay.
+                log.warning("genloop: the record of %s is older than the ledger window — archived unprocessed",
+                            session_name(stamp))
+                if not self.config.dry_run:
+                    self._archive(stamp)
+                continue
+            term = self._ingest_one(stamp, path, now)
+            if term:
+                terms.append(term)
+        return terms
+
+    def _ingest_one(self, stamp: str, path: Path, now: int) -> str:
+        session = session_name(stamp)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            record = parse_pass_record(payload, stamp=stamp)
+        except (OSError, json.JSONDecodeError, PassRecordError) as exc:
+            log.error("genloop: the record of %s is malformed (%s) — ingested as idle", session, exc)
+            self.events.record(
+                KIND_PASS_IDLE, at=now, dedupe_key=f"idle:{stamp}", session=session,
+                reason=f"malformed pass record: {exc}",
+            )
+            return self._mark_ingested(stamp, f"ingested {session} (malformed record)")
+
+        for skip in record.skipped:
+            self.events.record(
+                KIND_PLAN_SKIPPED, at=now, dedupe_key=f"skip:{stamp}:{skip.key}", session=session,
+                reason=skip.reason, data={"key": skip.key, "source": "pass"},
+            )
+        amended = self._rerequest_amended(record)
+
+        if record.verdict == VERDICT_SKILL_MISSING:
+            self._skill_missing = stamp
+            log.error(
+                "genloop: %s could not load the skill %r — no further pass is spawned until the image "
+                "carries it (restart after installing)", session, self.config.skill,
+            )
+            self.events.record(
+                KIND_PASS_IDLE, at=now, dedupe_key=f"idle:{stamp}", session=session,
+                reason=f"skill-missing: {self.config.skill}",
+            )
+            return self._mark_ingested(stamp, f"ingested {session} (skill-missing){amended}")
+        if record.verdict == VERDICT_IDLE:
+            self.events.record(
+                KIND_PASS_IDLE, at=now, dedupe_key=f"idle:{stamp}", session=session,
+                reason="the pass proposed no plan", data={"skipped": len(record.skipped)},
+            )
+            return self._mark_ingested(stamp, f"ingested {session} (idle){amended}")
+        assert record.verdict == VERDICT_PLAN
+        outcome = self._deliver(record, now)
+        if outcome.startswith("held"):
+            return f"{session}: {outcome}"
+        return self._mark_ingested(stamp, f"{session}: {outcome}{amended}")
+
+    def _mark_ingested(self, stamp: str, term: str) -> str:
+        if self.config.dry_run:
+            return term + " [dry-run]"
+        self.state.mark(INGESTED_PREFIX + stamp, at=int(self._now()))
+        self._settle(stamp)
+        self._archive(stamp)
+        return term
+
+    def _archive(self, stamp: str) -> None:
+        """Move an ingested record out of the glob `_ingest` reads."""
+        try:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            self.record_path(stamp).replace(self.archive_dir / f"{stamp}.json")
+        except OSError as exc:
+            log.warning("genloop: could not archive the record of %s (%s)", session_name(stamp), exc)
+
+    def _prune_archive(self, now: int) -> None:
+        try:
+            files = list(self.archive_dir.glob("*.json"))
+        except OSError:
+            return
+        for path in files:
+            epoch = stamp_epoch(path.stem)
+            if epoch is not None and now - epoch > LEDGER_MAX_AGE_SECONDS:
+                try:
+                    path.unlink()
+                except OSError as exc:
+                    log.warning("genloop: could not prune %s (%s)", path, exc)
+
+    def _rerequest_amended(self, record: PassRecord) -> str:
+        """The reviewer re-request for each open plan PR the pass amended --
+        the seat's, never the session's (c3)."""
+        if not record.amended:
+            return ""
+        ours = {pr.number for pr in self._our_plan_prs("open") or []}
+        done = []
+        for number in record.amended:
+            if number not in ours:
+                log.warning("genloop: amended PR #%d is not an open plan PR of ours — ignored", number)
+                continue
+            if self.config.dry_run:
+                log.info("[dry-run] would re-request %s on %s#%d", ",".join(self.config.reviewers), self.repo, number)
+            else:
+                try:
+                    self.github.request_reviewers(self.repo, number, self.config.reviewers)
+                except CommandError as exc:
+                    log.warning("genloop: re-request on #%d failed (%s)", number, exc)
+                    continue
+            done.append(f"#{number}")
+        return f", re-requested {' '.join(done)}" if done else ""
+
+    def _read_plan(self, branch: str, plan_id: str) -> tuple[Plan, str]:
+        """The plan at the branch head, and that head's sha. Raises
+        `PlanError` (unreadable: terminal) or `CommandError` (retry)."""
+        sha = self.github.branch_sha(self.repo, branch)
+        if sha is None:
+            raise PlanError(f"branch {branch} does not exist in {self.repo}")
+        return self._read_plan_at(sha, plan_id), sha
+
+    def _read_plan_at(self, ref: str, plan_id: str) -> Plan:
+        plan_dir = f"plans/{plan_id}"
+        plan_md = self.github.read_file(self.repo, f"{plan_dir}/plan.md", ref)
+        if plan_md is None:
+            raise PlanError(f"{plan_dir}/plan.md is absent at {ref[:7]}")
+        names = self.github.list_dir(self.repo, f"{plan_dir}/tasks", ref) or []
+        tasks: dict[str, str] = {}
+        for name in task_file_names(names):
+            text = self.github.read_file(self.repo, f"{plan_dir}/tasks/{name}", ref)
+            if text is None:
+                raise PlanError(f"{plan_dir}/tasks/{name} vanished at {ref[:7]}")
+            tasks[name] = text
+        return parse_plan(plan_md, tasks, expect_id=plan_id)
+
+    def _program_budget(self, plan: Plan) -> tuple[bool, str]:
+        """(skip, why) for the plan's program (§1.7: the generator checks the
+        program scope it generates into); when it does not skip, `why` is the
+        budget line for the PR body. Raises AlissaError on a failed read."""
+        status = self.alissa.budget_status("program", project_id=plan.program)
+        state = status.get("state")
+        if state == "exhausted":
+            return True, f"program {plan.program} budget exhausted"
+        try:
+            records = self.alissa.factory_steering()
+        except AlissaError:
+            records = []
+        share = program_row(records, plan.program).get("budgetShare")
+        spent, cap = status.get("spentUsd"), status.get("capUsd")
+        if isinstance(share, (int, float)) and isinstance(spent, (int, float)) and isinstance(cap, (int, float)):
+            if spent >= share * cap:
+                return True, f"program {plan.program} spent ${spent:.2f} >= budgetShare {share} x cap ${cap:.2f}"
+            return False, f"program budget `{state}`, ${spent:.2f} of budgetShare {share} x cap ${cap:.2f}"
+        return False, f"program budget `{state}`"
+
+    def _deliver(self, record: PassRecord, now: int) -> str:
+        """Open the plan PR for a `plan` record. Returns `held(...)` to retry
+        next poll, or the outcome to mark ingested."""
+        assert record.branch is not None and record.plan_id is not None
+        branch, plan_id, stamp = record.branch, record.plan_id, record.stamp
+        session = session_name(stamp)
+        try:
+            plan, sha = self._read_plan(branch, plan_id)
+        except CommandError as exc:
+            return f"held(plan read failed: {exc})"
+        except PlanError as exc:
+            log.error("genloop: %s pushed a plan the seat cannot read (%s) — no PR", session, exc)
+            self.events.record(
+                KIND_PLAN_SKIPPED, at=now, dedupe_key=f"unreadable:{stamp}", session=session,
+                reason="unreadable", data={"branch": branch, "detail": str(exc)[:500]},
+            )
+            return f"plan unreadable ({exc})"
+        try:
+            skip, budget_note = self._program_budget(plan)
+        except AlissaError as exc:
+            return f"held(budget: status unavailable — {exc})"
+        if skip:
+            self.events.record(
+                KIND_PLAN_SKIPPED, at=now, dedupe_key=f"budget:{stamp}", session=session,
+                reason=SKIP_BUDGET, data={"planId": plan_id, "detail": budget_note},
+            )
+            return f"skipped(budget — {budget_note}; {branch} left unopened)"
+
+        try:
+            existing = self.github.pulls_for_branch(self.repo, branch)
+        except CommandError as exc:
+            return f"held(PR lookup failed: {exc})"
+        pr = next((p for p in existing if p.state == "open"), None)
+        if pr is None and existing:
+            # L13: a plan PR someone closed is never reopened.
+            return f"not reopened (#{existing[0].number} was closed)"
+        if pr is None:
+            if self.config.dry_run:
+                log.info("[dry-run] would open the plan PR for %s and request %s", branch,
+                         ",".join(self.config.reviewers))
+                return f"would open {branch}"
+            try:
+                base = self.github.default_branch(self.repo)
+                pr = self.github.open_pr(
+                    self.repo, head=branch, base=base, title=render_pr_title(plan),
+                    body=render_pr_body(plan, branch=branch, plans_dir=f"plans/{plan_id}", budget_note=budget_note),
+                )
+            except CommandError as exc:
+                return f"held(PR open failed: {exc})"
+            log.info("genloop: opened %s#%d for %s (head %s)", self.repo, pr.number, plan_id, sha[:7])
+        if not self.config.dry_run:
+            try:
+                self.github.request_reviewers(self.repo, pr.number, self.config.reviewers)
+            except CommandError as exc:
+                return f"held(reviewer request on #{pr.number} failed: {exc})"
+            try:
+                self.alissa.post_loop_plan(plan.loop_plan_record(
+                    repo=self.repo, pr_number=pr.number, status="proposed", at_ms=now * 1000,
+                ))
+            except AlissaTransient as exc:
+                return f"held(plan row for #{pr.number}: {exc})"
+            except AlissaError as exc:
+                log.error("genloop: POST /v1/loop/plans for #%d refused (%s) — the PR stands", pr.number, exc)
+        self.events.record(
+            KIND_PLAN_PROPOSED, at=now, dedupe_key=f"proposed:{self.repo}#{pr.number}", repo=self.repo,
+            pr_number=pr.number, session=session,
+            data={"planId": plan_id, "branch": branch, "class": plan.plan_class, "anchor": plan.anchor_ref},
+        )
+        return f"proposed #{pr.number} ({plan_id}, {plan.plan_class})"
+
+    # -- 2. lint watch -----------------------------------------------------
+
+    def _our_plan_prs(self, state: str) -> list[PullRequest] | None:
+        if state in self._pulls:
+            return self._pulls[state]
+        login = self.login()
+        if login is None:
+            return None
+        try:
+            pulls: list[PullRequest] | None = [
+                pr for pr in self.github.list_pulls(self.repo, state=state) if is_plan_pr(pr, login)
+            ]
+        except CommandError as exc:
+            log.warning("genloop: could not list %s plan PRs (%s)", state, exc)
+            pulls = None
+        self._pulls[state] = pulls
+        return pulls
+
+    def _lint_watch(self, now: int) -> list[str]:
+        pulls = self._our_plan_prs("open")
+        if pulls is None:
+            return ["lint watch: held(plan PR listing failed)"]
+        terms = []
+        if not self.config.dry_run:
+            # A red PR closed by someone else leaves its clock behind.
+            open_numbers = {str(pr.number) for pr in pulls}
+            for key in [k for k in self.state.meta if k.startswith(META_RED_SINCE)]:
+                if key[len(META_RED_SINCE):] not in open_numbers:
+                    self.state.del_meta(key)
+        settled = int(self.state.get_meta(META_LAST_SETTLED) or 0)
+        for pr in pulls:
+            key = META_RED_SINCE + str(pr.number)
+            try:
+                run = self.github.lint_run(self.repo, pr.head_sha)
+            except CommandError as exc:
+                log.warning("genloop: could not read plan-lint on #%d (%s)", pr.number, exc)
+                continue
+            conclusion = run.get("conclusion") if run else None
+            if conclusion == "success":
+                if self.state.get_meta(key) is not None and not self.config.dry_run:
+                    self.state.del_meta(key)
+                continue
+            if conclusion != "failure":
+                continue
+            raw = self.state.get_meta(key)
+            if raw is None:
+                if not self.config.dry_run:
+                    self.state.set_meta(key, str(now))
+                terms.append(f"#{pr.number} plan-lint red — the next pass amends it")
+                continue
+            if settled <= int(raw):
+                continue
+            terms.append(self._invalidate(pr, now))
+        return terms
+
+    def _invalidate(self, pr: PullRequest, now: int) -> str:
+        if self.config.dry_run:
+            log.info("[dry-run] would close %s#%d as plan.invalid and delete %s", self.repo, pr.number, pr.head_ref)
+            return f"would invalidate #{pr.number}"
+        try:
+            self.github.comment(self.repo, pr.number, INVALID_COMMENT.format(branch=pr.head_ref))
+            self.github.close_pr(self.repo, pr.number)
+            self.github.delete_branch(self.repo, pr.head_ref)
+        except CommandError as exc:
+            return f"held(invalidate #{pr.number}: {exc})"
+        self.state.mark(INVALID_PREFIX + str(pr.number), at=now)
+        self.state.del_meta(META_RED_SINCE + str(pr.number))
+        self._post_status(pr, "rejected", now)
+        self.events.record(
+            KIND_PLAN_INVALID, at=now, dedupe_key=f"invalid:{self.repo}#{pr.number}", repo=self.repo,
+            pr_number=pr.number, reason="plan-lint still failure after the next pass",
+            data={"branch": pr.head_ref, "headSha": pr.head_sha},
+        )
+        return f"plan.invalid #{pr.number} (closed, {pr.head_ref} deleted)"
+
+    def _plan_of(self, pr: PullRequest) -> Plan | None:
+        # The LAST trailer line: the trailers close the body, and the copied
+        # prose above them could carry a line that merely looks like one.
+        matches = re.findall(r"^Alissa-Plan:[ \t]*(\S+)[ \t]*$", pr.body, re.MULTILINE)
+        if not matches or not pr.head_sha:
+            return None
+        try:
+            return self._read_plan_at(pr.head_sha, matches[-1])
+        except (CommandError, PlanError) as exc:
+            log.warning("genloop: could not read the plan of #%d (%s)", pr.number, exc)
+            return None
+
+    def _post_status(self, pr: PullRequest, status: str, now: int) -> None:
+        plan = self._plan_of(pr)
+        if plan is None:
+            return
+        try:
+            self.alissa.post_loop_plan(plan.loop_plan_record(
+                repo=self.repo, pr_number=pr.number, status=status, at_ms=now * 1000,
+            ))
+        except AlissaError as exc:
+            log.warning("genloop: plan row #%d -> %s refused (%s)", pr.number, status, exc)
+
+    # -- 3. rejections -----------------------------------------------------
+
+    def _rejections(self, now: int) -> list[str]:
+        if not self.config.operators:
+            return []
+        terms: list[str] = []
+        closed = self._our_plan_prs("closed")
+        for pr in (closed or [])[:CLOSED_PLANS_PER_POLL]:
+            if pr.merged or self.state.has(REJECTED_PREFIX + str(pr.number)) \
+                    or self.state.has(INVALID_PREFIX + str(pr.number)):
+                continue
+            closed_at = iso_epoch(pr.closed_at)
+            if closed_at is None or now - closed_at > REJECTION_WINDOW_SECONDS:
+                continue
+            term = self._reject(pr, now)
+            if term:
+                terms.append(term)
+        for pr in self._our_plan_prs("open") or []:
+            terms.extend(self._do_not_propose(pr, now))
+        return terms
+
+    def _operator_comments(self, pr: PullRequest) -> list:
+        operators = {login.lower() for login in self.config.operators}
+        return [c for c in self.github.issue_comments(self.repo, pr.number) if c.author.lower() in operators]
+
+    def _reject(self, pr: PullRequest, now: int) -> str:
+        try:
+            comments = self._operator_comments(pr)
+        except CommandError as exc:
+            return f"held(comments of #{pr.number}: {exc})"
+        if self.config.dry_run:
+            return f"would record the rejection of #{pr.number}"
+        reason_comment = self._closing_comment(pr, comments)
+        if reason_comment is None or not reason_comment.body.strip():
+            log.info("genloop: #%d was rejected without a reason — no rule is written (say why and it becomes one)",
+                     pr.number)
+            self._post_status(pr, "rejected", now)
+            self.state.mark(REJECTED_PREFIX + str(pr.number), at=now)
+            return f"#{pr.number} rejected without a reason"
+        outcome = self._write_rules(pr, reason_comment, now)
+        if outcome.startswith("held"):
+            return outcome
+        self._post_status(pr, "rejected", now)
+        self.state.mark(REJECTED_PREFIX + str(pr.number), at=now)
+        return f"#{pr.number} rejected: {outcome}"
+
+    def _closing_comment(self, pr: PullRequest, comments: list):
+        """The newest operator comment written at the close (within the
+        skew) that has not already become rules -- not merely the newest
+        one on the thread, which may predate the close by weeks."""
+        closed_at = iso_epoch(pr.closed_at)
+        if closed_at is None:
+            return None
+        candidates = []
+        for comment in comments:
+            at = iso_epoch(comment.created_at)
+            if at is None or at < closed_at - REJECTION_COMMENT_SKEW_SECONDS:
+                continue
+            if self.state.has(RULE_PREFIX + str(comment.id)):
+                continue
+            candidates.append((at, comment.id, comment))
+        return max(candidates, key=lambda c: (c[0], c[1]))[2] if candidates else None
+
+    def _do_not_propose(self, pr: PullRequest, now: int) -> list[str]:
+        try:
+            comments = self._operator_comments(pr)
+        except CommandError:
+            return []
+        terms = []
+        for comment in comments:
+            if not comment.body.lstrip().startswith(DO_NOT_PROPOSE) or self.state.has(RULE_PREFIX + str(comment.id)):
+                continue
+            if self.config.dry_run:
+                terms.append(f"would write rules from #{pr.number} comment {comment.id}")
+                continue
+            terms.append(f"#{pr.number} {DO_NOT_PROPOSE}: {self._write_rules(pr, comment, now)}")
+        return terms
+
+    def _write_rules(self, pr: PullRequest, comment, now: int) -> str:
+        """One rule per source key and one for the anchor (§4.4). The
+        comment's id marks it written -- or refused, which is not retried."""
+        plan = self._plan_of(pr)
+        if plan is None:
+            return f"held(plan of #{pr.number} unreadable)"
+        reason = comment.body.strip()
+        if reason.startswith(DO_NOT_PROPOSE):
+            reason = reason[len(DO_NOT_PROPOSE):].strip()
+        if not reason:
+            self.state.mark(RULE_PREFIX + str(comment.id), at=now)
+            return "no reason given — no rule"
+        patterns = list(plan.source_keys)
+        anchor_pattern = anchor_rule_pattern(plan.anchor)
+        if anchor_pattern:
+            patterns.append(anchor_pattern)
+        written = 0
+        for pattern in patterns:
+            try:
+                self.alissa.put_proposal_rule(
+                    pattern=pattern, scope="fleet", scope_key="", reason=reason[:RULE_REASON_MAX],
+                    source_url=comment.url,
+                )
+            except AlissaTransient as exc:
+                return f"held(rule write: {exc})"
+            except AlissaAuthError as exc:
+                if not self._rules_refused_logged:
+                    log.warning(
+                        "genloop: the planner token may not write proposal rules (%s) — Studio documents "
+                        "rule writes as forbidden for an agent-bound token; the operator records the rule "
+                        "on the Fleet screen", exc,
+                    )
+                    self._rules_refused_logged = True
+                self.state.mark(RULE_PREFIX + str(comment.id), at=now)
+                return f"rules refused ({exc.status})"
+            except AlissaError as exc:
+                log.warning("genloop: rule %s refused (%s)", pattern, exc)
+                continue
+            written += 1
+        self.state.mark(RULE_PREFIX + str(comment.id), at=now)
+        return f"{written} rule(s) written"
+
+    # -- 4. spawn gate -----------------------------------------------------
+
+    def _skip(self, now: int, kind: str, reason: str, term: str, data: dict | None = None) -> str:
+        """A named skip: one event per interval slot, nothing in the ledger."""
+        slot = now // self.config.interval
+        bound = (data or {}).get("bound", "")
+        self.events.record(kind, at=now, dedupe_key=f"gate:{reason}:{bound}:{slot}", reason=reason, data=data or {})
+        return term
+
+    def _spawn_gate(self, now: int, listing: list[dict] | None) -> str:
+        config = self.config
+        if self._skill_missing is not None:
+            return f"held(skill-missing — install {config.skill!r} in the image and restart)"
+        raw_last = self.state.get_meta(META_LAST_SPAWN)
+        if raw_last is not None and now - int(raw_last) < config.interval:
+            return f"held(interval — next pass in {config.interval - (now - int(raw_last))}s)"
+
+        # Not parked (D11). A steering read that failed holds: blind is closed.
+        try:
+            records = self.alissa.factory_steering()
+        except AlissaError as exc:
+            return f"held(steering unavailable — {exc})"
+        fleet = fleet_row(records)
+        if fleet.get("parked") is True:
+            return self._skip(now, KIND_PLAN_SKIPPED, SKIP_PARKED,
+                              "skipped(parked — the operator parked generated work)")
+
+        # Budget (D10, §8.1): a generator that cannot see its ceiling generates nothing.
+        try:
+            budget = self.alissa.budget_status("fleet")
+        except AlissaError as exc:
+            return self._skip(
+                now, KIND_PLAN_SKIPPED, SKIP_BUDGET, f"skipped(budget — status unavailable: {exc})",
+                {"state": "unavailable"},
+            )
+        state = budget.get("state")
+        if state == "exhausted":
+            return self._skip(now, KIND_PLAN_SKIPPED, SKIP_BUDGET, "skipped(budget — fleet exhausted)",
+                              {"state": state})
+        if state == "unmetered" and fleet.get("holdWhenUnmetered") is True:
+            return self._skip(now, KIND_PLAN_SKIPPED, SKIP_BUDGET,
+                              "skipped(budget — unmetered and holdWhenUnmetered)", {"state": state})
+        budget_note = f"fleet budget `{state}`"
+        if state == "warn":
+            budget_note += f", ${budget.get('remainingUsd')} remaining — say so in the plan's *Why now*"
+
+        # The day bound.
+        login = self.login()
+        if login is None:
+            return "held(GitHub login unknown)"
+        try:
+            today = self.github.plans_opened_on(self.repo, login, utc_day(now))
+        except CommandError as exc:
+            return f"held(day count unavailable — {exc})"
+        if today >= config.plans_per_day:
+            return self._skip(
+                now, KIND_PASS_IDLE, SKIP_BOUND, f"idle(bound — plans per day {today}/{config.plans_per_day})",
+                {"bound": BOUND_DAY, "count": today, "max": config.plans_per_day},
+            )
+
+        # The lane bound.
+        try:
+            lanes = int(self.alissa.loop_generated().get("openLanes") or 0)
+        except AlissaError as exc:
+            return f"held(open lanes unavailable — {exc})"
+        if lanes >= config.open_lanes_max:
+            return self._skip(
+                now, KIND_PASS_IDLE, SKIP_BOUND, f"idle(bound — open lanes {lanes}/{config.open_lanes_max})",
+                {"bound": BOUND_LANES, "count": lanes, "max": config.open_lanes_max},
+            )
+
+        # No live pass; a listing that failed is unknown, and unknown holds (L2).
+        if listing is None:
+            return "held(session listing failed — a pass I cannot see may be live)"
+        live = live_stamps(listing)
+        if live:
+            return f"held(live session {', '.join(session_name(s) for s in live)})"
+        if not self.cli.worker_running():
+            return "held(no worker — the queue would never drain)"
+
+        repos = self._fed_repos()
+        if not repos:
+            return "held(no fed repositories — nothing to read exhaust from)"
+        if not self.config.plans_hub_path.is_dir():
+            return f"held(plans hub {self.config.plans_hub_path} missing)"
+
+        stamp = stamp_at(now)
+        session = session_name(stamp)
+        directive = render_directive(
+            stamp=stamp, day=utc_day(now), skill=config.skill, plans_repo=self.repo,
+            plans_hub=str(config.plans_hub_path), repos=repos, window_days=config.window_days,
+            record_path=str(self.record_path(stamp)), budget_note=budget_note,
+        )
+        if config.dry_run:
+            log.info("[dry-run] would enqueue %s (--agent %s --cwd %s)", session, config.agent, config.plans_hub_path)
+            return f"would spawn {session}"
+        try:
+            self.passes_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            return f"held(state dir unwritable: {exc})"
+        try:
+            self.cli.enqueue_session(session=session, directive=directive, cwd=config.plans_hub_path,
+                                     agent=config.agent)
+        except CommandError as exc:
+            return f"held(enqueue failed: {exc})"
+        # Claim ONLY now (L5).
+        self.state.set_meta(META_LAST_SPAWN, str(now))
+        self.state.mark(SPAWN_PREFIX + stamp, at=now)
+        log.info("genloop: spawned %s (skill %s, directive sha256 %s)", session, config.skill, DIRECTIVE_SHA256[:12])
+        return f"spawned {session}"
+
+    def _fed_repos(self) -> list[str]:
+        if self.config.repos_source == REPOS_SOURCE_STATIC:
+            return list(self.config.repos)
+        try:
+            rows = self.alissa.list_bodies_of_work()
+        except AlissaError as exc:
+            log.warning("genloop: could not list the feed bodies of work (%s)", exc)
+            return []
+        owners = set(self.config.bow_owners)
+        repos = []
+        for row in rows:
+            if owners and row.get("ownerActorId") not in owners:
+                continue
+            repo = parse_bow_repo(str(row.get("title") or ""))
+            if repo and repo.lower() != self.repo.lower() and repo not in repos:
+                repos.append(repo)
+        return sorted(repos)
+
+    # -- 5. stale floor ----------------------------------------------------
+
+    def _stale_floor(self, now: int, listing: list[dict] | None) -> list[str]:
+        if listing is None:
+            return []
+        limit = self.config.stale_intervals * self.config.interval
+        terms = []
+        for stamp in live_stamps(listing):
+            started = stamp_epoch(stamp)
+            if started is None or now - started <= limit or self.state.has(STALLED_PREFIX + stamp):
+                continue
+            session = session_name(stamp)
+            if self.config.dry_run:
+                terms.append(f"would kill stalled {session}")
+                continue
+            # Recorded BEFORE the kill, so a kill that lands cannot lose the event.
+            self.state.mark(STALLED_PREFIX + stamp, at=now)
+            self._settle(stamp)
+            try:
+                self.cli.kill_session(session)
+            except CommandError as exc:
+                log.warning("genloop: kill of stalled %s failed (%s)", session, exc)
+            self.events.record(
+                KIND_PASS_STALLED, at=now, dedupe_key=f"stalled:{stamp}", session=session,
+                reason=f"live {now - started}s, over {self.config.stale_intervals} x interval",
+            )
+            log.error("genloop: %s stalled (%ds) — killed", session, now - started)
+            terms.append(f"stalled {session} killed")
+        return terms
+
+    # -- 6. silence floor --------------------------------------------------
+
+    def _silence_floor(self, now: int, listing: list[dict] | None) -> list[str]:
+        terms = []
+        live = set(live_stamps(listing)) if listing is not None else set()
+        for key in self.state.keys_with_prefix(SPAWN_PREFIX):
+            stamp = key[len(SPAWN_PREFIX):]
+            if any(self.state.has(p + stamp) for p in (INGESTED_PREFIX, STALLED_PREFIX, SILENT_PREFIX)):
+                if not self.config.dry_run:
+                    self.state.unmark(key)
+                continue
+            if listing is None or stamp in live:
+                continue
+            spawned = self.state.ledger.get(key, now)
+            if now - spawned < SPAWN_GRACE_SECONDS or self.record_path(stamp).exists():
+                continue
+            session = session_name(stamp)
+            # Absent from the listing is not "ended": a pass still waiting in
+            # the queue (worker busy, concurrency cap) has not started. A
+            # queue that cannot be read is unknown, and unknown holds.
+            try:
+                if self.cli.queued(session):
+                    continue
+            except CommandError as exc:
+                log.warning("genloop: could not read the queue of %s (%s) — not marking it silent", session, exc)
+                continue
+            if self.config.dry_run:
+                terms.append(f"would record {session} silent")
+                continue
+            self.state.mark(SILENT_PREFIX + stamp, at=now)
+            self._settle(stamp)
+            self.events.record(
+                KIND_PASS_SILENT, at=now, dedupe_key=f"silent:{stamp}", session=session,
+                reason="the pass ended without writing its record",
+            )
+            log.error("genloop: %s ended without a record — pass.silent", session)
+            terms.append(f"silent {session}")
+        return terms