alissa-tools-github-orcloop 0.3.2__tar.gz → 0.3.3__tar.gz

{alissa_tools_github_orcloop-0.3.2/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.2
+Version: 0.3.3
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_orcloop-0.3.2 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/ghclient.py

@@ -74,13 +74,26 @@ def _closes_re(number: int) -> re.Pattern[str]:
     return pattern
 
 
+def parse_task_trailer(body: str) -> int | None:
+    """Origin Alissa task number from a line-anchored `Alissa-Task: TASK-<n>`
+    TRAILER only -- never the loose `TASK-<n>` scan `parse_task_ref` falls back
+    to. This is the strict read, for the one caller that is about to MUTATE the
+    matched issue: the release edge's pre-create dedupe applies the trigger
+    label to whatever it matches, so "the body mentions TASK-<n> somewhere" is
+    not a good enough claim. A passing mention in prose must not adopt."""
+    match = TASK_TRAILER_RE.search(body or "")
+    return int(match.group(1)) if match else None
+
+
 def parse_task_ref(body: str) -> int | None:
     """Origin Alissa task number from an issue body, or None. A line-anchored
     `Alissa-Task: TASK-<n>` trailer wins wherever it sits; only absent that does
     the loose first-`TASK-<n>` scan run. Mirrors devloop's parser so both
     daemons read the trailer orcloop writes identically."""
-    text = body or ""
-    match = TASK_TRAILER_RE.search(text) or TASK_REF_RE.search(text)
+    trailer = parse_task_trailer(body)
+    if trailer is not None:
+        return trailer
+    match = TASK_REF_RE.search(body or "")
     return int(match.group(1)) if match else None
 
 
@@ -245,6 +258,82 @@ class GitHub:
             out.append((parts[-2], parts[-1], number))
         return out
 
+    def issues_with_task_trailer(
+        self, owner: str, repo: str, task_number: int
+    ) -> list[Issue]:
+        """Every issue in ONE repo whose body carries the `Alissa-Task:
+        TASK-<task_number>` trailer -- OPEN and CLOSED alike, lowest issue
+        number first (earliest filed first).
+
+        This is the trailer-authoritative dedupe read, and it exists because
+        `search_issues` above is not one: that query is `is:issue is:open
+        label:"<label>"`, so a pre-existing issue carrying the trailer but NOT
+        the label is invisible to it, and the release edge filed a duplicate
+        issue for a task a hand-staged issue already covered. The label answers
+        "what is in flight"; only the trailer answers "does an issue for this
+        task already exist".
+
+        No `is:open` qualifier: the caller decides what a CLOSED match means
+        (that rule cannot be applied to results the query never returned).
+
+        The search index is a HINT, never the verdict. GitHub tokenizes the
+        phrase, so a hit can be an issue that merely mentions the number in
+        prose; every hit is re-checked against the strict trailer regex on the
+        body the API returned, and anything not carrying THIS task's trailer is
+        dropped. In the other direction the index can be stale for a
+        just-created issue -- which is exactly what the release ledger covers,
+        and a miss here degrades to filing an issue (today's behaviour), never
+        to mutating the wrong one.
+
+        Fails closed on a blank owner/repo, the same posture as
+        `search_issues` on an empty allowlist: a missing `repo:` qualifier
+        would run the query against all of GitHub.
+        """
+        owner, repo = owner.strip(), repo.strip()
+        if not owner or not repo:
+            log.warning(
+                "issues_with_task_trailer: blank owner/repo (%r/%r) -- an "
+                "unscoped search would match all of GitHub, so this fails "
+                "closed and reports no match",
+                owner, repo,
+            )
+            return []
+
+        query = (
+            f'is:issue repo:{owner}/{repo} in:body '
+            f'"Alissa-Task: TASK-{task_number}"'
+        )
+        payload = self._api(
+            "-X", "GET", "search/issues", "-f", f"q={query}", "-f",
+            f"per_page={self.SEARCH_PER_PAGE}",
+        )
+        items = payload.get("items", []) if isinstance(payload, dict) else []
+        if len(items) == self.SEARCH_PER_PAGE:
+            log.warning(
+                "issues_with_task_trailer: got exactly %d items for TASK-%d in "
+                "%s/%s -- results are likely truncated; the earliest matching "
+                "issue may not be among them",
+                self.SEARCH_PER_PAGE, task_number, owner, repo,
+            )
+
+        out: list[Issue] = []
+        for item in items:
+            if not isinstance(item, dict) or item.get("pull_request"):
+                continue  # `is:issue` should have done this; belt and braces
+            issue = self._issue_from_payload(owner, repo, item)
+            if not issue.number:
+                log.warning("could not parse issue number from %r", item.get("number"))
+                continue
+            if parse_task_trailer(issue.body) != task_number:
+                log.debug(
+                    "%s matched the TASK-%d search but carries no such trailer "
+                    "-- dropped (the index matches tokens, the trailer decides)",
+                    issue.issue_slug, task_number,
+                )
+                continue
+            out.append(issue)
+        return sorted(out, key=lambda found: found.number)
+
     def comment(self, owner: str, repo: str, number: int, body: str) -> None:
         self._api(
             f"repos/{owner}/{repo}/issues/{number}/comments", "-f", f"body={body}"

{alissa_tools_github_orcloop-0.3.2 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/loop.py

@@ -16,12 +16,21 @@ issues the develop daemon can pick up:
     `Autonomous-Dev` trailer. One list read of ALL committed tasks per poll.
   - `bow` -- the tasks attached to the per-repo Bodies of Work named
     `<bow_prefix><owner>/<repo>`. See THE BOW FEED below.
-* **Dedupe** is GitHub-authoritative with the ledger as a cache: one search of
-  the watched repos for open labeled issues, each issue's body parsed for its
-  `Alissa-Task:` trailer, gives the set of tasks already released. A task in
-  that set (or in the ledger) is never released twice. The scan also ADOPTS
-  hand-released issues (see the §8 decision below) and BACKFILLS the ledger
-  for orcloop's own releases GitHub confirms but the ledger has lost.
+* **Dedupe** is GitHub-authoritative with the ledger as a cache, and it runs in
+  TWO layers because they answer different questions:
+
+  - the **pass scan** searches the watched repos for open LABELED issues and
+    parses each body's `Alissa-Task:` trailer. That is the in-flight set: it
+    feeds lane occupancy, skips tasks already released, ADOPTS hand-released
+    issues into the ledger (§8 below) and BACKFILLS rows GitHub confirms but
+    the ledger has lost. Being label-scoped is correct for occupancy and
+    WRONG as the last word on "does an issue for this task exist" -- an
+    unlabeled issue carrying the trailer is invisible to it.
+  - the **pre-create trailer check** (`_trailer_dedupe`) closes exactly that
+    gap, in the target repo, immediately before an issue would be filed: an
+    open unlabeled trailer match is ADOPTED (ledger row + label, never a
+    second issue), an open labeled one is skipped, a closed one follows the
+    closed-match rule below. A check that cannot answer holds the release.
 * **The dependsOn gate**: a candidate is releasable only once every upstream
   task it depends on is `pending_validation` or `validated` (an unfinished
   dependency holds the release). An upstream this actor cannot even see counts
@@ -167,24 +176,43 @@ the Alissa task (primary) and best-effort on the GitHub issue, and are all
 dry-run gated: `unreleasable` (a marked task with no valid target repo),
 `release-blocked` (the dependsOn gate held past the `release_blocked_floor_days`
 floor -- below the floor the release is held quietly, one log line per poll,
-never a page), `parked`, `closed-unmerged`, and `closeloop-failed:a<j>` (a
-close-loop mutation failed; retried with a floor between attempts, each attempt
-paging once).
+never a page), `parked`, `closed-unmerged`, `already-merged` (a task came up
+for release but its trailer already sits on an issue closed by a merged PR),
+`dedupe-unreadable` (the pre-create trailer check has been unable to answer for
+longer than the same `release_blocked_floor_days` floor -- measured on the
+FAILURE, not the task's age, so a transient rate limit on a long-queued task
+never pages -- because a hold that could never page is how a task goes quiet
+forever), and `closeloop-failed:a<j>` (a close-loop mutation failed; retried
+with a floor between attempts, each attempt paging once).
 
 NO SILENT STATES: every candidate and every released issue produces exactly one
 logged `Decision` each pass -- a deferral (`held`) always leaves a per-poll log
 line, and a floored escalation is the only thing allowed to defer without a
 per-poll page. `test_loop.py` pins this.
 
-THE §8 OPEN DECISION -- adoption of hand-released issues (RESOLVED here,
-close-loop only): an issue a human files by hand carrying BOTH the trigger
-label AND an `Alissa-Task:` trailer is ADOPTED into the ledger the first time
-the release scan sees it open, so the close edge will drive its origin task
-forward on merge exactly like an orcloop-filed one. The release edge never
-files a fresh issue for it (dedupe covers it). The one limit: adoption needs to
-see the issue OPEN at least once, so a hand-released issue that was already
-closed before orcloop ever ran is not retro-adopted. Recorded in the PR body
-and on the origin task.
+THE §8 OPEN DECISION -- adoption of hand-released issues (RESOLVED here): an
+issue a human files by hand carrying an `Alissa-Task:` trailer is ADOPTED
+rather than duplicated, in whichever of two places sees it first:
+
+* WITH the trigger label -- the release scan adopts it into the ledger the
+  first time it sees it open, so the close edge drives its origin task forward
+  on merge exactly like an orcloop-filed one.
+* WITHOUT the label -- the pre-create trailer check adopts it when the task
+  comes up for release: the ledger row is written against the EXISTING issue
+  and the label is applied, completing a release a human started. Both halves
+  of the alternative were wrong before this: filing a second issue duplicates
+  the work, and skipping on the match would leave the trigger unarmed (an
+  unlabeled issue is invisible to the develop daemon), so the task would
+  simply starve.
+
+CLOSED trailer matches never permanently block a release: a closed-unmerged
+one is ignored (a superseded or not-planned issue is not evidence the work
+happened), and only a match closed by a MERGED closing PR stops the release --
+as an `already-merged` escalation, because a task still queued for release
+whose work already merged is an anomaly for the operator, not a silent skip.
+The one limit that remains: adoption needs to see an issue at all, so a task
+whose only trace is a closed, never-merged issue releases fresh. Recorded in
+the PR body and on the origin task.
 
 orcloop spawns NO worker sessions (it files issues; the develop daemon spawns
 the sessions), so there is no session reaper here -- the family's "sweep" is
@@ -244,6 +272,34 @@ ESCALATION_RELEASE_BLOCKED = "release-blocked"
 ESCALATION_PARKED = "parked"
 ESCALATION_CLOSED_UNMERGED = "closed-unmerged"
 ESCALATION_CLOSELOOP_FAILED = "closeloop-failed"
+ESCALATION_ALREADY_MERGED = "already-merged"
+ESCALATION_DEDUPE_UNREADABLE = "dedupe-unreadable"
+
+# NOT an operator page: the timestamp of the FIRST dedupe check that could not
+# answer for this task, so the floor above it measures how long the CONDITION
+# has lasted rather than how old the task is. Task age is a fair proxy for a
+# persistent gate (that is why `release-blocked` uses it); a single failed I/O
+# read is not, and without this an old task would page on its first transient
+# rate limit -- permanently, since the page kind would then be spent. Both this
+# marker and the page are cleared the moment a check answers again.
+#
+# The `marker:` prefix is load-bearing, not decoration: `escalations_matching`
+# is a PREFIX reader (that is how `closeloop-failed:a<j>` counts its attempts),
+# so a marker named `dedupe-unreadable-since` (the name this one had before
+# the namespace) would silently answer a future
+# `escalations_matching(task, ESCALATION_DEDUPE_UNREADABLE)` -- a non-page row
+# inflating a page count in whatever report asked. Namespacing puts it out of
+# reach of every prefix read of a page kind.
+DEDUPE_UNREADABLE_SINCE = "marker:dedupe-unreadable"
+
+# How many CLOSED trailer matches the pre-create dedupe will walk looking for a
+# merged closing PR. Each check is a bounded timeline walk (see
+# `GitHub.closing_merged_pr`), and the matches are walked newest-first, so this
+# caps the cost of a task whose trailer has been re-filed many times. A task
+# with more closed matches than this releases -- the closed-match rule is
+# "closed work must not permanently block release", so an unresolved tail
+# errs toward releasing, never toward a task that can never be released again.
+MAX_CLOSED_TRAILER_CHECKS = 3
 
 # NOT an operator page: a completion marker so a fully-closed loop is never
 # re-processed. Lives in the escalations table (kind is free-form TEXT by the
@@ -335,6 +391,33 @@ CLOSED_UNMERGED_ISSUE_COMMENT = (
     "closing PR, so the orchestrator left its origin Alissa task untouched."
 )
 
+ALREADY_MERGED_TASK_COMMENT = (
+    "**Orchestrator: already merged** — this task was about to be released, "
+    "but issue {slug} already carries its `Alissa-Task:` trailer and was "
+    "closed by merged pull request {pr_url}. The work looks genuinely done, "
+    "so the orchestrator has NOT filed a second issue and has NOT advanced "
+    "this task (it never held a ledger row for that issue, so the close edge "
+    "could not drive it). Validate and close this task by hand if the merge "
+    "covers it; if it does not, remove the release marker or edit the trailer "
+    "off that issue so the orchestrator can release fresh work for it."
+)
+DEDUPE_UNREADABLE_COMMENT = (
+    "**Orchestrator: dedupe unreadable** — before filing a develop issue for "
+    "this task the orchestrator checks {target} for an issue that already "
+    "carries its `Alissa-Task:` trailer, and that check has been failing "
+    "continuously for over {floor_days} day(s): {reason}. The release is held rather "
+    "than risk a duplicate issue, and it will keep retrying. Usual causes: the "
+    "GitHub token lost access to {target}, or a closed issue carrying this "
+    "trailer was transferred or deleted. Restore the read (or release this "
+    "work by hand) to clear it."
+)
+
+ALREADY_MERGED_ISSUE_COMMENT = (
+    "**Orchestrator: already merged** — this closed issue carries the "
+    "`Alissa-Task:` trailer of a task that is still queued for release. No "
+    "second issue was filed; the origin task needs an operator decision."
+)
+
 CLOSELOOP_FAILED_TASK_COMMENT = (
     "**Orchestrator: close-loop failed (attempt {attempt})** — the released "
     "issue {slug} merged, but advancing this task to `pending_validation` "
@@ -536,9 +619,15 @@ class Orchestrator:
         Every open labeled issue occupies its repo's lane (its `Autonomous-Scope`
         globs recorded for disjointness checks). An issue whose body carries an
         `Alissa-Task:` trailer maps that task number to the issue -- the
-        GitHub-authoritative dedupe set -- and, if the ledger does not know it
-        yet, is ADOPTED (§8: a hand-released or ledger-lost issue) so the close
-        edge tracks it."""
+        in-flight dedupe set -- and, if the ledger does not know it yet, is
+        ADOPTED (§8: a hand-released or ledger-lost issue) so the close edge
+        tracks it.
+
+        This search is LABEL-scoped, which is what lane occupancy needs and is
+        deliberately NOT the whole dedupe story: an issue carrying the trailer
+        but no label is in neither the occupancy nor the dedupe set here. That
+        case is settled per-candidate by `_trailer_dedupe`, immediately before
+        anything is filed."""
         released: dict[int, Issue] = {}
         occupancy: dict[str, list[list[str]]] = {}
         for owner, repo, number in self.github.search_issues(
@@ -1268,6 +1357,410 @@ class Orchestrator:
                 )
         return None
 
+    def _trailer_dedupe(
+        self,
+        task: Task,
+        target: str,
+        occupancy: dict[str, list[list[str]]],
+        *,
+        bow: BodyOfWork | None = None,
+    ) -> tuple[str, Decision] | None:
+        """The trailer-authoritative dedupe, run in the target repo immediately
+        before an issue would be created. Returns the decision that replaces
+        the create, or None to go ahead and create.
+
+        WHY IT EXISTS (the duplicate this fixes): the pass-level scan searches
+        `is:issue is:open label:"<label>"` and only then parses the matched
+        bodies for a trailer, so its dedupe set is LABEL-scoped -- an open
+        issue that already carries a task's `Alissa-Task:` trailer but has not
+        been labeled is never fetched and never parsed. A hand-staged issue in
+        exactly that state (open, unlabeled, trailer present for days) was
+        missed and a second issue was filed for the same task. Skipping on the
+        match would have been just as wrong the other way: unlabeled means
+        invisible to the develop daemon, so the trigger would have starved.
+
+        The rule matrix, per match in the target repo:
+
+        * OPEN + unlabeled -> **adopt**: record the ledger row against the
+          EXISTING issue and apply the label. That is the same
+          ledger-then-label ordering (and the same idempotent crash
+          completion) a fresh release uses; it never files a second issue and
+          never leaves the trigger unarmed.
+        * OPEN + already labeled -> **skip**, and record the ledger row so the
+          close edge tracks it (the §8 adoption the scan would do next pass;
+          reaching here at all means the issue appeared after this pass's
+          scan).
+        * CLOSED with no merged closing PR -> **ignored**. A superseded,
+          not-planned or hand-closed issue must never make a task permanently
+          unreleasable, so the release proceeds and files a fresh issue.
+        * CLOSED by a merged closing PR -> **skip + escalate**
+          (`already-merged`): the work is genuinely done, so a second issue
+          would be duplicate work -- but the origin task is still queued, which
+          means no ledger row ever drove the close edge for it. That anomaly is
+          an operator decision, not something to guess at.
+
+        A dedupe read that does not ANSWER (search or timeline failure) holds
+        the release -- "the check failed" must never be read as "no duplicate"
+        -- but never silently forever: past the release-blocked floor the hold
+        pages once (`_dedupe_unreadable`), because a task that can neither
+        release nor complain is the same dead end the closed-match rule above
+        exists to prevent.
+        """
+        owner, _, repo = target.partition("/")
+        try:
+            matches = self.github.issues_with_task_trailer(owner, repo, task.task_number)
+        except (CommandError, RateLimited) as exc:
+            return self._dedupe_unreadable(
+                task, target, f"the trailer search in {target} failed: {exc}",
+            )
+
+        open_matches = [issue for issue in matches if issue.state == "open"]
+        if open_matches:
+            self._dedupe_answered(task.task_number)
+            return self._adopt(task, open_matches, target, occupancy, bow=bow)
+        return self._closed_trailer_matches(task, matches, target)
+
+    def _adopt(
+        self,
+        task: Task,
+        open_matches: list[Issue],
+        target: str,
+        occupancy: dict[str, list[list[str]]],
+        *,
+        bow: BodyOfWork | None = None,
+    ) -> tuple[str, Decision]:
+        """Complete the release ON an open issue that already carries this
+        task's trailer, instead of filing a second one.
+
+        The EARLIEST filed match wins (matches arrive lowest-number-first): if
+        a repo somehow carries two open issues for one task, the first one is
+        the one people have been reading, and picking deterministically beats
+        picking the newest. The extras are named in a warning -- one task
+        cannot have two live issues without someone having made a mistake.
+
+        Lane occupancy is recorded from the ISSUE's own `Autonomous-Scope`, not
+        the candidate task's: the issue is the in-flight artifact, it is what
+        `_scan_released` will read on every later pass, and on an adopted
+        (human-written) body the two can differ. Taking the task's globs here
+        would leave this pass and the next deciding disjointness on different
+        input. A body with no scope trailer is therefore SCOPELESS -- it
+        occupies the whole lane, the conservative reading and the one the next
+        scan reaches independently.
+
+        Which is exactly why the lane is RE-GATED here on `issue_scope` before
+        the label goes on. `_evaluate_release` admitted this candidate on the
+        TASK's globs; adoption then arms a different artifact, whose globs can
+        conflict with the lane the task's did not (an absent scope trailer is
+        the common shape -- scopeless means "needs an empty lane", and the
+        adopt path is the one release path that could otherwise land it beside
+        an occupant). Gating on the input this method treats as authoritative
+        keeps `scopes_disjoint`'s guarantee true of what actually runs. A
+        conflict HOLDS: the issue keeps its trailer, so a later pass adopts it
+        once the lane clears -- nothing is lost and nothing is duplicated.
+
+        That guarantee is one-directional, deliberately. The EARLIER gate still
+        decides on the task's globs, so a candidate the issue's globs would
+        have admitted can be held before it ever reaches here (task claims
+        `src/**` against an `src/**` occupant; the staged issue claims
+        `docs/**`). Letting a lane-blocked candidate fall through to be
+        re-decided here would close it, and is not worth the extra path: that
+        direction costs THROUGHPUT -- one poll, self-clearing when the lane
+        drains -- while the direction gated above costs SAFETY, two sessions on
+        overlapping files.
+
+        Adoption holds are quiet, exactly like every other lane hold: one log
+        line per poll, no floor, no page. The scopeless case is the one worth
+        knowing about -- "needs an empty lane" conflicts with EVERY occupant,
+        so in a busy repo a scopeless staged issue can wait a long time -- so
+        that hold logs a WARNING naming the issue and the one-line remedy,
+        rather than only the per-poll decision line.
+
+        The already-labeled branch is not gated: that issue is armed and
+        in-flight whatever orcloop thinks, so there is no trigger to withhold,
+        only a ledger row to record and a lane to account for.
+
+        An adopted body is a human's, so it is not the renderer's: only the
+        trailer is contractual (it is all the develop daemon reads too). A body
+        without the `Autonomous-Dev` trailer is adopted anyway -- the target
+        repo is the one this search was scoped to, not something inferred from
+        the body -- but it is logged, because "an operator staged something
+        incomplete" should be visible in the poll log rather than in devloop's
+        behaviour."""
+        issue = open_matches[0]
+        if len(open_matches) > 1:
+            log.warning(
+                "%s: %d OPEN issues carry this task's trailer (%s) — adopting "
+                "the earliest, %s; the others are duplicates a human should "
+                "close",
+                task.ref, len(open_matches),
+                ", ".join(found.issue_slug for found in open_matches),
+                issue.issue_slug,
+            )
+
+        issue_scope = parse_scope(issue.body, self.config.scope_key)
+        labeled = self.config.label in issue.labels
+        if not labeled:
+            lane_reason = self._lane_blocked(target, issue_scope, occupancy)
+            if lane_reason is not None:
+                if not issue_scope:
+                    # A scopeless issue needs an EMPTY lane, so this hold does
+                    # not clear when one occupant closes -- it clears when the
+                    # repo goes quiet. Loud enough to act on: whoever staged
+                    # the issue can end the wait with one trailer.
+                    log.warning(
+                        "%s: %s carries this task's trailer but declares no "
+                        "`%s:` trailer, so adopting it would need an EMPTY "
+                        "%s lane (%s) — held. Add an `%s:` trailer to let it "
+                        "land beside in-flight work",
+                        task.ref, issue.issue_slug, self.config.scope_key,
+                        target, lane_reason, self.config.scope_key,
+                    )
+                return self._logged(task.ref, Decision(
+                    Action.HELD,
+                    f"cannot adopt {issue.issue_slug} yet: lane {target} "
+                    f"occupied: {lane_reason} — the issue declares "
+                    f"{issue_scope or '(scopeless — needs an empty lane)'}, "
+                    f"whatever the task declares; retries next poll",
+                    task.task_number,
+                ))
+
+        # Past every gate that can refuse, and worded as STATE rather than act:
+        # the three paths below it are a live adoption, a dry-run report, and an
+        # already-labeled skip that arms nothing, so a line claiming "adopting"
+        # would overstate two of them. What the operator needs is the same on
+        # all three -- what the body left out, and what was inferred instead.
+        if parse_marker(issue.body, self.config.marker_key) is None:
+            log.warning(
+                "%s: %s carries this task's trailer but no `%s:` trailer — "
+                "target repo read from the search scope (%s), lane scope from "
+                "the body (%s). Edit the issue if that is not what it means",
+                task.ref, issue.issue_slug, self.config.marker_key, target,
+                issue_scope or "scopeless — occupies the whole lane",
+            )
+
+        if self.config.dry_run:
+            verb = "would record" if labeled else "would adopt"
+            unlabeled_note = "" if labeled else f", no {self.config.label!r} label"
+            occupancy.setdefault(target, []).append(issue_scope)
+            return self._logged(task.ref, Decision(
+                Action.SKIPPED if labeled else Action.RELEASED,
+                f"[dry-run] {verb} pre-existing {issue.issue_slug} (carries "
+                f"this task's `Alissa-Task:` trailer{unlabeled_note})"
+                f"{self._detach(task.ref, bow)}",
+                task.task_number,
+            ))
+
+        try:
+            self.state.record_release(
+                task_number=task.task_number,
+                owner_repo=target,
+                issue_number=issue.number,
+                labeled=labeled,
+            )
+            if labeled:
+                # Already armed: there is no trigger left to complete, only the
+                # ledger row (written above) so the close edge tracks it. It
+                # still occupies the lane for the REST OF THIS PASS -- the scan
+                # ran before this issue existed, so no later candidate would
+                # otherwise measure itself against it.
+                occupancy.setdefault(target, []).append(issue_scope)
+                return self._logged(task.ref, Decision(
+                    Action.SKIPPED,
+                    f"already released by hand as {issue.issue_slug} (trailer "
+                    f"and {self.config.label!r} label present); recorded in the "
+                    f"ledger, no second issue{self._detach(task.ref, bow)}",
+                    task.task_number,
+                ))
+            self.github.add_label(issue.owner, issue.repo, issue.number, self.config.label)
+            self.state.mark_labeled(task.task_number)
+        except (CommandError, RateLimited) as exc:
+            # Same recovery as a create that died before its label: the ledger
+            # row exists at labeled=0, so the next pass's dedupe path completes
+            # the labeling of THIS issue rather than filing anything. The
+            # detach is not attempted -- the release is not complete yet.
+            return self._logged(task.ref, Decision(
+                Action.HELD,
+                f"adoption of {issue.issue_slug} failed: {exc}",
+                task.task_number,
+            ))
+
+        occupancy.setdefault(target, []).append(issue_scope)
+        return self._logged(task.ref, Decision(
+            Action.RELEASED,
+            f"adopted pre-existing {issue.issue_slug} (carries this task's "
+            f"trailer, was unlabeled): ledger row recorded and "
+            f"{self.config.label!r} applied{self._detach(task.ref, bow)}",
+            task.task_number,
+        ))
+
+    def _closed_trailer_matches(
+        self, task: Task, matches: list[Issue], target: str
+    ) -> tuple[str, Decision] | None:
+        """Apply the closed-match rule to the CLOSED trailer matches (there are
+        no open ones by the time this runs). Returns a decision that replaces
+        the create, or None to release.
+
+        Closed-unmerged matches are ignored on purpose: a superseded or
+        not-planned issue is not evidence the work happened, and letting it
+        veto the release would make one hand-closed issue enough to render a
+        task permanently unreleasable. Only a MERGED closing PR is evidence,
+        and that is escalated rather than silently skipped.
+
+        An UNREADABLE match (transferred, deleted, or in a repo the token lost
+        access to) does not speak for the others: the walk continues, and the
+        pass holds only if NO checked match could be resolved. One permanently
+        unreadable issue would otherwise hold the task forever -- through the
+        error branch, the same dead end the rule above rules out. When every
+        checked match is unreadable the hold is floored and pages once (see
+        `_dedupe_unreadable`)."""
+        if not matches:
+            self._dedupe_answered(task.task_number)
+            return None
+
+        # Newest first: the most recent closed attempt is the likeliest to
+        # carry the merge, and the walk is bounded.
+        newest_first = sorted(matches, key=lambda found: found.number, reverse=True)
+        checked = newest_first[:MAX_CLOSED_TRAILER_CHECKS]
+        unreadable: list[str] = []
+        first_error: Exception | None = None
+        for issue in checked:
+            try:
+                pr = self.github.closing_merged_pr(issue.owner, issue.repo, issue.number)
+            except (CommandError, RateLimited) as exc:
+                unreadable.append(issue.issue_slug)
+                first_error = first_error or exc
+                continue
+            if pr is None:
+                continue
+            self._dedupe_answered(task.task_number)
+            self._escalate(
+                task.task_number,
+                ESCALATION_ALREADY_MERGED,
+                ALREADY_MERGED_TASK_COMMENT.format(slug=issue.issue_slug, pr_url=pr.url),
+                issue=issue,
+                issue_comment=ALREADY_MERGED_ISSUE_COMMENT,
+            )
+            return self._logged(task.ref, Decision(
+                Action.ESCALATED,
+                f"already merged: {issue.issue_slug} carries this task's "
+                f"trailer and was closed by merged {pr.url} — no second issue "
+                f"filed, task left for the operator",
+                task.task_number,
+            ))
+
+        if unreadable and len(unreadable) == len(checked):
+            # Nothing was resolved, so the walk made no claim at all -- this is
+            # the same "the check did not answer" state as a failed search.
+            return self._dedupe_unreadable(
+                task, target,
+                f"none of the closed trailer matches in {target} could be read "
+                f"({', '.join(unreadable)}): {first_error}",
+            )
+
+        # At least one match resolved, so the check DID answer: any recorded
+        # failure is over.
+        self._dedupe_answered(task.task_number)
+        unchecked = max(0, len(newest_first) - MAX_CLOSED_TRAILER_CHECKS)
+        log.info(
+            "%s: %d closed issue(s) in %s carry this task's trailer (%s) but "
+            "none of the %d checked was closed by a merged PR%s%s — closed work "
+            "that never merged does not block a release; filing a fresh issue",
+            task.ref, len(newest_first), target,
+            ", ".join(found.issue_slug for found in newest_first),
+            len(checked),
+            f" ({unchecked} older match(es) not checked)" if unchecked else "",
+            f" ({len(unreadable)} unreadable: {', '.join(unreadable)})"
+            if unreadable else "",
+        )
+        return None
+
+    def _dedupe_unreadable(
+        self, task: Task, target: str, reason: str
+    ) -> tuple[str, Decision]:
+        """The trailer dedupe could not answer, so the release is held rather
+        than risk a duplicate -- with the floor-then-page shape
+        `_release_blocked` uses, because a hold that can never page is how a
+        task goes quiet forever: a token that lost access to the target repo,
+        or a closed match that was transferred or deleted, fails identically on
+        every poll.
+
+        The floor measures THE FAILURE, not the task. `_release_blocked` can
+        floor on task age because the dependsOn gate is a persistent condition,
+        so an old blocked task has plausibly been blocked a while; this
+        condition is a single I/O outcome, and `search/issues` is GitHub's
+        tightest limit -- a routine, self-clearing rate limit on a
+        long-queued task would otherwise page on contact, with a message
+        claiming days of failure, and burn the kind so a genuine outage later
+        had no page left. So the first failure records
+        `marker:dedupe-unreadable` (stamped from the loop's own clock) and holds
+        quietly; only once THAT is older than `release_blocked_floor_days` does
+        one `dedupe-unreadable` escalation name the repo and the failing read.
+        `_escalate` dedupes per (task, kind), so a long outage pages once.
+
+        `_trailer_dedupe` clears both rows the moment a check answers again, so
+        a blip that clears leaves nothing behind and a later, unrelated outage
+        starts its own clock and gets its own page.
+
+        The floor knob is shared with `release-blocked` on purpose: both say
+        "how long may a release be quietly held before an operator is told",
+        and a second knob for the same question is a config surface (and a
+        container floor bump) that buys nothing."""
+        floor_seconds = self.config.release_blocked_floor_days * 86400
+        held = f"dedupe check could not answer — {reason}; held rather than risk "
+        rows = self.state.escalations_matching(task.task_number, DEDUPE_UNREADABLE_SINCE)
+        now = int(self._now())
+        if not rows:
+            if not self.config.dry_run:
+                self.state.record_escalation(
+                    task.task_number, DEDUPE_UNREADABLE_SINCE, at=now,
+                )
+            return self._logged(task.ref, Decision(
+                Action.HELD,
+                held + "filing a duplicate issue; first failure, retries next poll",
+                task.task_number,
+            ))
+
+        failing_for = now - int(rows[0]["escalated_at"])
+        if failing_for < floor_seconds:
+            return self._logged(task.ref, Decision(
+                Action.HELD,
+                held + f"filing a duplicate issue; failing for "
+                f"{failing_for // 3600}h, within the "
+                f"{self.config.release_blocked_floor_days}d floor",
+                task.task_number,
+            ))
+
+        self._escalate(
+            task.task_number,
+            ESCALATION_DEDUPE_UNREADABLE,
+            DEDUPE_UNREADABLE_COMMENT.format(
+                target=target,
+                reason=reason,
+                floor_days=self.config.release_blocked_floor_days,
+            ),
+        )
+        return self._logged(task.ref, Decision(
+            Action.ESCALATED,
+            held + f"filing a duplicate issue, and failing for "
+            f"{failing_for // 86400}d — past the "
+            f"{self.config.release_blocked_floor_days}d floor",
+            task.task_number,
+        ))
+
+    def _dedupe_answered(self, task_number: int) -> None:
+        """The dedupe check answered, so any recorded failure is OVER: drop the
+        first-seen marker and the page kind together.
+
+        Clearing the page kind is the point -- `_escalate`'s per-(task, kind)
+        dedupe is what stops an outage paging every poll, and without a clear
+        it would also stop a SECOND, unrelated outage paging at all. Guarded by
+        a read so the common (working) path does not write on every release."""
+        if self.config.dry_run:
+            return
+        for kind in (DEDUPE_UNREADABLE_SINCE, ESCALATION_DEDUPE_UNREADABLE):
+            if self.state.escalated(task_number, kind):
+                self.state.clear_escalation(task_number, kind)
+
     def _release(
         self,
         task: Task,
@@ -1283,8 +1776,16 @@ class Orchestrator:
         daemon's trigger and the detach is the release's terminal act, so a
         crash at any point leaves the work discoverable rather than lost.
         Occupancy is updated in-memory so a later candidate in THIS pass sees
-        the new occupant and respects the lane."""
+        the new occupant and respects the lane.
+
+        Nothing is created until the TRAILER dedupe answers: the pass-level
+        scan is label-scoped and cannot see an unlabeled issue that already
+        carries this task's trailer (see `_trailer_dedupe`)."""
         owner, _, repo = target.partition("/")
+        preexisting = self._trailer_dedupe(task, target, occupancy, bow=bow)
+        if preexisting is not None:
+            return preexisting
+
         body = render_issue_body(task, target, scope, self.config)
 
         if self.config.dry_run:

{alissa_tools_github_orcloop-0.3.2 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/state.py

@@ -67,6 +67,14 @@ CREATE TABLE IF NOT EXISTS meta (
 """
 
 
+# The only `escalations` kinds `clear_escalation` will remove: the O9 dedupe
+# outage clock and the page it raises, both of which describe a condition that
+# can END (see `clear_escalation`). Spelled as literals here rather than
+# imported from `loop`, which imports this module; `test_loop` pins that the
+# loop's constants and this set stay the same two strings.
+CLEARABLE_KINDS = frozenset({"marker:dedupe-unreadable", "dedupe-unreadable"})
+
+
 class State:
     def __init__(self, path: Path):
         path = Path(path).expanduser()
@@ -153,16 +161,48 @@ class State:
         ).fetchone()
         return row is not None
 
-    def record_escalation(self, task_number: int, kind: str) -> None:
+    def record_escalation(self, task_number: int, kind: str, at: int | None = None) -> None:
         """Idempotent per (task, kind): OR IGNORE keeps the FIRST escalation's
         timestamp, so `escalated_at` is an audit field for when this kind was
-        first raised, not the most recent re-raise."""
+        first raised, not the most recent re-raise.
+
+        `at` overrides the wall clock. Rows whose timestamp is only an audit
+        field can leave it None; a caller that MEASURES against `escalated_at`
+        must pass its own clock, because the loop's clock is injectable and a
+        row stamped from `time.time()` would be measured against a different
+        one (the O9 `marker:dedupe-unreadable` row is such a caller)."""
         self._db.execute(
             "INSERT OR IGNORE INTO escalations "
             "(task_number, kind, escalated_at) VALUES (?,?,?)",
-            (task_number, kind, int(time.time())),
+            (task_number, kind, int(time.time()) if at is None else int(at)),
+        )
+        self._db.commit()
+
+    def clear_escalation(self, task_number: int, kind: str) -> bool:
+        """Forget one (task, kind) row; True if a row was actually removed.
+
+        The only writer that UNDOES a row, and deliberately narrow: a condition
+        that has demonstrably ended (the O9 dedupe check answering again) must
+        not leave a first-seen timestamp that makes the NEXT outage look days
+        old, nor a spent page kind that can never fire again.
+
+        AUDIT kinds are never clearable, and that is enforced rather than
+        merely documented: clearing `closeloop-done` would let a fully-closed
+        loop be re-processed, and clearing an operator page would erase the
+        record that it was raised. Anything outside `CLEARABLE_KINDS` raises --
+        a caller reaching for it has a design error, not a runtime one."""
+        if kind not in CLEARABLE_KINDS:
+            raise ValueError(
+                f"{kind!r} is not clearable: only {sorted(CLEARABLE_KINDS)} are. "
+                "Escalation rows are an audit trail; a condition that ends "
+                "needs its own clearable kind, not the deletion of a page."
+            )
+        cursor = self._db.execute(
+            "DELETE FROM escalations WHERE task_number=? AND kind=?",
+            (task_number, kind),
         )
         self._db.commit()
+        return cursor.rowcount > 0
 
     def escalations_matching(self, task_number: int, prefix: str) -> "list[sqlite3.Row]":
         """Escalation rows for this task whose `kind` starts with `prefix`.

alissa_tools_github_orcloop-0.3.3/src/main/alissa/tools/github/orcloop/version

@@ -0,0 +1 @@
+0.3.3

{alissa_tools_github_orcloop-0.3.2 → alissa_tools_github_orcloop-0.3.3/src/main/alissa_tools_github_orcloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.2
+Version: 0.3.3
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_orcloop-0.3.2/src/main/alissa/tools/github/orcloop/version

@@ -1 +0,0 @@
-0.3.2