alissa-tools-github-orcloop 0.3.9__tar.gz → 0.3.10__tar.gz

{alissa_tools_github_orcloop-0.3.9/src/main/alissa_tools_github_orcloop.egg-info → alissa_tools_github_orcloop-0.3.10}/PKG-INFO

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

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.10}/src/main/alissa/tools/github/orcloop/__main__.py

@@ -145,6 +145,18 @@ def build_parser() -> argparse.ArgumentParser:
         "disables it). The sweep reports, it never releases.",
     )
 
+    over.add_argument(
+        "--autoclose-grace-seconds",
+        type=int,
+        metavar="SECONDS",
+        help="close edge only: how long to let GitHub close a released issue "
+        "itself, measured from the closing PR's mergedAt, before the daemon "
+        "closes it mechanically (default 300; 0 = no grace). GitHub's "
+        "`Closes #n` auto-close is best-effort and can silently never fire, "
+        "which would otherwise leave the issue open and its origin task stuck "
+        "forever.",
+    )
+
     close = over.add_mutually_exclusive_group()
     close.add_argument(
         "--close-loop",
@@ -191,6 +203,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "alissa_endpoint": args.alissa_endpoint,
         "ledger_path": args.ledger_path,
         "close_loop_enabled": args.close_loop_enabled,
+        "autoclose_grace_seconds": args.autoclose_grace_seconds,
         "dry_run": args.dry_run,
         "release_feed": args.release_feed,
         "bow_prefix": args.bow_prefix,

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.10}/src/main/alissa/tools/github/orcloop/config.py

@@ -121,6 +121,7 @@ CONFIG_KEYS = (
     "dry_run",
     "ledger_path",
     "close_loop_enabled",
+    "autoclose_grace_seconds",
     "release_feed",
     "bow_prefix",
     "bow_owners",
@@ -499,6 +500,25 @@ class Config:
     # half; every side effect still honors dry_run. Off reverts to release-only.
     close_loop_enabled: bool = True
 
+    # How long to let GitHub close a released issue itself, measured from the
+    # closing PR's `mergedAt`, before the close edge closes it mechanically.
+    #
+    # GitHub's `Closes #n` auto-close is best-effort, not a contract: it has been
+    # observed to silently never fire on a properly-linked PR while a sibling
+    # merge seconds earlier auto-closed normally. Past this window an issue whose
+    # closing PR has MERGED is treated as a flaked platform step and completed by
+    # the daemon (issue #40). Within it, nothing happens -- the daemon never
+    # races the platform for a step the platform usually performs.
+    #
+    # Minutes, not seconds or hours: auto-close normally lands within seconds, so
+    # a few minutes is far outside the healthy distribution, while an hour would
+    # leave the released work's lane occupied for an hour on every flake. `0`
+    # means "no grace" (close on the first pass that sees the merge) and is legal
+    # -- it is a race with the platform, not a correctness problem, since the
+    # close is idempotent -- but it makes a normal auto-close look like an
+    # anomaly, so it is not the default.
+    autoclose_grace_seconds: int = 300
+
     dry_run: bool = False
 
     # Where release candidates come from: `scan` (all committed tasks, filtered
@@ -651,6 +671,20 @@ class Config:
                 f"release_blocked_floor_days must be >= 1, got {floor_days}"
             )
 
+        grace = int(raw.get("autoclose_grace_seconds", cls.autoclose_grace_seconds))
+        if grace < 0:
+            # No upper bound and no MIN_POLL_INTERVAL floor, unlike the sweep:
+            # this is a wait, not a cadence, so a small value only makes the
+            # daemon act sooner (`0` = act on the first pass that sees the
+            # merge), and a large one only makes it wait longer. Neither can
+            # produce the runaway a sub-poll INTERVAL can. Negative is the one
+            # value with no reading at all -- it would say "close it before the
+            # PR merged" -- so it is rejected rather than clamped.
+            raise ValueError(
+                f"autoclose_grace_seconds must be >= 0 (0 = no grace, close as "
+                f"soon as the merge is seen), got {grace}"
+            )
+
         marker_key = str(raw.get("marker_key", cls.marker_key))
         scope_key = str(raw.get("scope_key", cls.scope_key))
         for name, value in (("marker_key", marker_key), ("scope_key", scope_key)):
@@ -721,6 +755,7 @@ class Config:
             close_loop_enabled=bool(
                 raw.get("close_loop_enabled", cls.close_loop_enabled)
             ),
+            autoclose_grace_seconds=grace,
             dry_run=bool(raw.get("dry_run", cls.dry_run)),
             release_feed=release_feed,
             bow_prefix=bow_prefix,

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.10}/src/main/alissa/tools/github/orcloop/ghclient.py

@@ -1,8 +1,9 @@
 """GitHub access via `gh api`.
 
 orcloop's GitHub side: create the `alissa:develop` issue for a released task,
-manage its label, read issues back, search the watched repos, comment, and --
-for the close-loop -- find the MERGED pull request that closed a released issue.
+manage its label, read issues back, search the watched repos, comment, close an
+issue the platform should have closed itself, and -- for the close-loop -- find
+the MERGED pull request that closed a released issue.
 
 Targets gh 2.4.0, which predates `gh search` and `gh issue`-level JSON we can
 rely on: every call goes through `gh api` against REST v3. The gh-2.4.0-safe
@@ -24,6 +25,7 @@ import os
 import re
 import tempfile
 import urllib.parse
+from datetime import datetime, timezone
 from dataclasses import dataclass
 
 from . import proc
@@ -97,6 +99,33 @@ def parse_task_ref(body: str) -> int | None:
     return int(match.group(1)) if match else None
 
 
+def parse_timestamp(value: str | None) -> float | None:
+    """A GitHub RFC 3339 timestamp (`2026-07-28T04:42:55Z`) as unix seconds, or
+    None when it is missing or unparseable.
+
+    `fromisoformat` handles the `Z` suffix from 3.11 on, which `setup.py`
+    already requires. A timestamp carrying no zone is read as UTC rather than as
+    the daemon's local time: every timestamp GitHub sends is UTC, and a
+    container running in a non-UTC zone would otherwise shift an age by hours --
+    silently, and in whichever direction the deployment happens to sit.
+
+    None rather than an exception, for the same reason `pull_request` degrades a
+    malformed payload to None: the callers here are decisions, not parsers, and
+    a field GitHub omitted must not be able to crash a poll. What "unknown"
+    MEANS is the caller's to decide, which is why it is a distinct answer and
+    not, say, 0.
+    """
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(str(value).strip())
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.timestamp()
+
+
 @dataclass(frozen=True)
 class Issue:
     owner: str
@@ -107,6 +136,17 @@ class Issue:
     body: str
     url: str
     labels: tuple[str, ...]
+    # `state_reason`, verbatim: `completed` / `not_planned` / `reopened`, or ""
+    # when GitHub did not state one. Defaulted like the PullRequest fields below
+    # -- it is a late addition to the API and an issue reopened long ago (or
+    # through an unusual path) can carry nothing here.
+    #
+    # `reopened` is the one value the close edge acts on, and it is the cheapest
+    # answer to "has this issue ever been closed?" -- a question `state` cannot
+    # answer and, verified against a real reopened issue (golang/go#79623),
+    # `closed_at` cannot either: GitHub CLEARS `closed_at` on reopen, so it is
+    # null on exactly the issues that matter. See `_evaluate_open_released`.
+    state_reason: str = ""
 
     @property
     def full_name(self) -> str:
@@ -116,6 +156,11 @@ class Issue:
     def issue_slug(self) -> str:
         return f"{self.owner}/{self.repo}#{self.number}"
 
+    @property
+    def reopened(self) -> bool:
+        """Whether GitHub says this issue was re-opened after being closed."""
+        return self.state_reason == "reopened"
+
 
 @dataclass(frozen=True)
 class PullRequest:
@@ -132,6 +177,20 @@ class PullRequest:
     # meaningful only on a merged PR, and a payload that omits it must degrade
     # to "unknown" in the evidence rather than fail the close walk.
     merge_sha: str = ""
+    # The branch this PR merged INTO (`base.ref`), verbatim. GitHub only
+    # auto-closes a linked issue when the PR merges into the repository's
+    # DEFAULT branch, so this is what separates "the auto-close flaked" from
+    # "the platform correctly declined to auto-close a merge into `develop`".
+    # Defaulted like the fields below: a payload that omits it says nothing, and
+    # the close edge refuses to repair on a base it cannot read.
+    base_ref: str = ""
+    # `merged_at`, verbatim as GitHub sent it (RFC 3339, `2026-07-28T04:42:55Z`).
+    # Kept as the RAW string rather than a parsed timestamp for the same reason
+    # `merge_sha` is defaulted: this dataclass mirrors a payload, and a field the
+    # payload omitted must read as "not stated" rather than as an epoch the
+    # daemon invented. `merged_epoch` below is the parsed view, and it answers
+    # None on exactly the payloads that omit or malform it.
+    merged_at: str = ""
 
     @property
     def full_name(self) -> str:
@@ -141,6 +200,31 @@ class PullRequest:
     def pr_slug(self) -> str:
         return f"{self.owner}/{self.repo}#{self.number}"
 
+    @property
+    def merged_epoch(self) -> float | None:
+        """`merged_at` as unix seconds, or None when it is absent/unparseable.
+
+        The close edge measures GitHub's auto-close grace window from this, so
+        "unknown" must be distinguishable from "long ago" -- see
+        `Orchestrator._evaluate_open_released`, which is what decides how an
+        unknown merge time behaves."""
+        return parse_timestamp(self.merged_at)
+
+
+@dataclass(frozen=True)
+class CloseWalk:
+    """What ONE walk of an issue's timeline establishes about how it closed --
+    or failed to.
+
+    Two facts, deliberately together: the merged PR that declares it closes the
+    issue (None if there is none), and whether the issue has ever been closed at
+    all. The close edge's repair needs both and must not pay for two walks to
+    get them; keeping them in one record is also what stops a caller from
+    answering "was it closed?" with the cheaper, wrong `state == "closed"`."""
+
+    pr: "PullRequest | None"
+    ever_closed: bool
+
 
 class RateLimited(RuntimeError):
     """A `gh` rate-limit signal -- a retry-later condition, distinct from a
@@ -155,6 +239,11 @@ def _is_rate_limited(exc: proc.CommandError) -> bool:
 class GitHub:
     SEARCH_PER_PAGE = 100
 
+    def __init__(self) -> None:
+        # Per-repo default branch, resolved lazily and kept for the process.
+        # See `default_branch`; only successful reads land here.
+        self._default_branches: dict[str, str] = {}
+
     def _api(self, *args: str, timeout: int = 60):
         try:
             return proc.run_json(["gh", "api", *args], timeout=timeout)
@@ -348,6 +437,38 @@ class GitHub:
             f"repos/{owner}/{repo}/issues/{number}/comments", "-f", f"body={body}"
         )
 
+    def close_issue(
+        self, owner: str, repo: str, number: int, reason: str = "completed"
+    ) -> Issue:
+        """Close an issue, stating WHY, and return it as GitHub now reports it.
+
+        The only issue-state mutation orcloop performs, and it exists for one
+        anomaly: GitHub's `Closes #n` auto-close is best-effort, so a merged
+        closing PR can leave its issue open forever (see the close edge's
+        `_evaluate_open_released`). `reason` maps to `state_reason`, which is
+        what distinguishes a completed issue from an abandoned one in GitHub's
+        own UI -- the daemon only ever completes work the platform confirmed
+        merged, so the default is `completed` and no caller passes anything else
+        today.
+
+        PATCH, through the same `--input <tempfile>` path `_post_json` uses:
+        gh 2.4.0's `-f` sends everything as a string, and `state_reason` is a
+        closed enum whose values would still be strings but whose siblings on
+        this endpoint (`labels`, `assignees`) are arrays -- one JSON body is
+        both simpler and the pattern the rest of this file already follows.
+
+        Idempotent on GitHub's side: closing an already-closed issue is a 200
+        that leaves it closed, so a retry after a lost response is harmless.
+        """
+        data = self._send_json(
+            "PATCH",
+            f"repos/{owner}/{repo}/issues/{number}",
+            {"state": "closed", "state_reason": reason},
+        )
+        return self._issue_from_payload(
+            owner, repo, data if isinstance(data, dict) else {}
+        )
+
     # --- the close-loop: the merged-PR walk --------------------------------
 
     def closing_merged_pr(self, owner: str, repo: str, number: int) -> PullRequest | None:
@@ -372,15 +493,55 @@ class GitHub:
         wedge the close decision. Newest-referenced PR wins ties -- the last
         cross-reference is the one most likely to be the real closer.
         """
-        candidates = self._referenced_pr_numbers(owner, repo, number)
+        return self.close_walk(owner, repo, number).pr
+
+    def close_walk(self, owner: str, repo: str, number: int) -> "CloseWalk":
+        """`closing_merged_pr`'s answer PLUS whether the issue was ever closed,
+        both from the SAME timeline walk.
+
+        The close edge's flaked-auto-close repair (O16) needs both facts, and
+        needs them not to cost two walks: "is there a merged closer?" decides
+        whether there is anything to repair, and "was this issue ever closed?"
+        decides whether there is anything WRONG -- an issue that was closed once
+        and is open again was re-opened by a human, which is indistinguishable
+        from a flake on every other signal (same open state, same merged PR,
+        same elapsed time since `mergedAt`).
+
+        Split out from `closing_merged_pr` rather than folded into it so the
+        closed-issue path keeps its exact signature and semantics: that caller
+        wants a PR, has no use for the history, and must not have to learn a new
+        return shape for a question it never asks."""
+        candidates, ever_closed = self._timeline_facts(owner, repo, number)
         pattern = _closes_re(number)
         for pr_number in candidates[:MAX_PR_CHECKS]:
             pr = self.pull_request(owner, repo, pr_number)
             if pr is None or not pr.merged:
                 continue
             if pattern.search(pr.body):
-                return pr
-        return None
+                return CloseWalk(pr=pr, ever_closed=ever_closed)
+        return CloseWalk(pr=None, ever_closed=ever_closed)
+
+    def default_branch(self, owner: str, repo: str) -> str:
+        """The repository's default branch, memoised for this process.
+
+        GitHub auto-closes a linked issue only on a merge into this branch, so
+        the close edge needs it to tell a flaked auto-close from a merge the
+        platform correctly declined to act on. Memoised because a default branch
+        does not move within a poll (or most weeks) and the daemon watches a
+        handful of repos: one read per repo per process, never per poll. A
+        failure is NOT cached -- it must be retried, not turned into a permanent
+        empty answer that would look like an unreadable base forever."""
+        key = f"{owner}/{repo}"
+        cached = self._default_branches.get(key)
+        if cached is not None:
+            return cached
+        data = self._api(f"repos/{owner}/{repo}")
+        branch = str((data or {}).get("default_branch") or "") if isinstance(
+            data, dict
+        ) else ""
+        if branch:
+            self._default_branches[key] = branch
+        return branch
 
     def pull_request(self, owner: str, repo: str, number: int) -> PullRequest | None:
         """One PR's close-loop-relevant fields, or None if it cannot be read.
@@ -388,12 +549,12 @@ class GitHub:
         -- the close-loop treats "unreadable" as "not the closer, keep
         looking", never as a merge.
 
-        `body` and `merge_sha` come from this ONE payload, which is why the
-        close edge's delivery-record evidence (O15) costs no extra round-trip:
-        the PR the close walk already resolved carries everything the evidence
-        needs. A field the payload omits degrades to the empty string here and
-        is reported as missing at the render site -- never fabricated, never
-        fetched a second time."""
+        `body`, `merge_sha` and `merged_at` all come from this ONE payload,
+        which is why the close edge's delivery-record evidence (O15) and its
+        auto-close grace window (O16) cost no extra round-trip: the PR the close
+        walk already resolved carries everything both need. A field the payload
+        omits degrades to the empty string here and is reported as missing at
+        the use site -- never fabricated, never fetched a second time."""
         data = self._api(f"repos/{owner}/{repo}/pulls/{number}")
         if not isinstance(data, dict) or not data:
             return None
@@ -407,13 +568,29 @@ class GitHub:
             merged=bool(data.get("merged") or data.get("merged_at")),
             url=data.get("html_url") or "",
             merge_sha=str(data.get("merge_commit_sha") or ""),
+            merged_at=str(data.get("merged_at") or ""),
+            base_ref=str(((data.get("base") or {}) if isinstance(
+                data.get("base"), dict) else {}).get("ref") or ""),
         )
 
-    def _referenced_pr_numbers(self, owner: str, repo: str, number: int) -> list[int]:
-        """Same-repo PR numbers cross-referenced by the issue timeline, newest
-        last, deduped -- the candidate set for `closing_merged_pr`."""
+    def _timeline_facts(
+        self, owner: str, repo: str, number: int
+    ) -> tuple[list[int], bool]:
+        """One timeline walk, two answers: the same-repo PR numbers it
+        cross-references (newest first, deduped -- the candidate set for
+        `close_walk`) and whether it carries a `closed` event.
+
+        The `closed` event is what makes "has this issue EVER been closed?"
+        answerable. It is durable in a way the issue's own fields are not: a
+        reopen clears `closed_at` and leaves `state` at `open`, so the timeline
+        is the only place the history survives (`golang/go#79623`, a real
+        reopened issue, reports `closed_at: null` while its timeline still
+        carries `closed`). Bounded by the same TIMELINE_MAX_PAGES page cap as
+        the cross-reference scan, which is why the caller does not rely on it
+        alone -- see `Issue.reopened`."""
         same_repo_pull = f"https://github.com/{owner}/{repo}/pull/"
         numbers: list[int] = []
+        ever_closed = False
         for page in range(1, TIMELINE_MAX_PAGES + 1):
             events = self._api(
                 "-X", "GET", f"repos/{owner}/{repo}/issues/{number}/timeline",
@@ -422,7 +599,11 @@ class GitHub:
             if not isinstance(events, list):
                 break
             for event in events:
-                if not isinstance(event, dict) or event.get("event") != "cross-referenced":
+                if not isinstance(event, dict):
+                    continue
+                if event.get("event") == "closed":
+                    ever_closed = True
+                if event.get("event") != "cross-referenced":
                     continue
                 source = event.get("source")
                 src = source.get("issue") if isinstance(source, dict) else None
@@ -438,19 +619,24 @@ class GitHub:
             if len(events) < TIMELINE_PAGE_SIZE:
                 break  # short page: the timeline is exhausted
         # Dedupe keeping LAST occurrence: the most recent cross-reference is the
-        # likeliest closer, and closing_merged_pr checks candidates in order.
-        return list(dict.fromkeys(reversed(numbers)))
+        # likeliest closer, and close_walk checks candidates in order.
+        return list(dict.fromkeys(reversed(numbers))), ever_closed
 
     # --- helpers -----------------------------------------------------------
 
     def _post_json(self, path: str, payload: dict):
-        """POST a JSON body via `--input <tempfile>`, cleaning the file up on
-        every path (success or raise)."""
+        """POST a JSON body via `--input <tempfile>`."""
+        return self._send_json("POST", path, payload)
+
+    def _send_json(self, method: str, path: str, payload: dict):
+        """Send a JSON body via `--input <tempfile>`, cleaning the file up on
+        every path (success or raise). One implementation for every verb: the
+        tempfile lifetime is the part worth having exactly once."""
         fd, body_path = tempfile.mkstemp(prefix="orcloop-", suffix=".json")
         try:
             with os.fdopen(fd, "w") as handle:
                 handle.write(json.dumps(payload))
-            return self._api("-X", "POST", path, "--input", body_path)
+            return self._api("-X", method, path, "--input", body_path)
         finally:
             os.unlink(body_path)
 
@@ -469,6 +655,7 @@ class GitHub:
                 (lb.get("name") or "") if isinstance(lb, dict) else str(lb)
                 for lb in (data.get("labels") or [])
             ),
+            state_reason=str(data.get("state_reason") or ""),
         )
 
 

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.10}/src/main/alissa/tools/github/orcloop/loop.py

@@ -213,7 +213,19 @@ so it behaves identically under `scan` and `bow` (and keeps driving issues
 released before a feed switch):
 
 * Poll each released issue (the ledger is the set to re-check; GitHub is the
-  truth for its state). Still open -> in flight, nothing to do.
+  truth for its state). Still open with no merged closing PR -> in flight,
+  nothing to do.
+* Still OPEN but a merged pull request already declares `Closes #n` (O16, issue
+  #40) -> GitHub's auto-close is best-effort and has been observed to silently
+  never fire, leaving a phantom "in-flight" issue that holds its lane and an
+  origin task stuck at `in_progress` with nothing escalated. Inside
+  `autoclose_grace_seconds` of the merge, nothing happens -- the daemon does not
+  race the platform. Past it, the daemon closes the issue itself (`completed`,
+  commented, WARNING-logged) and falls into the close walk below in the SAME
+  pass. A close that FAILS holds the row untouched; an open issue with no merged
+  closer is never touched; and the repair runs EXACTLY once, so an issue an
+  operator re-opens afterwards is left alone for good. See
+  `_evaluate_open_released`.
 * Closed with a MERGED pull request that declares `Closes #n` -> close the
   loop on the ORIGIN task: satisfy every validation criterion, attach the
   merged-PR evidence, and move the task `committed -> in_progress ->
@@ -285,7 +297,7 @@ import logging
 import re
 import time
 from collections import Counter
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from enum import Enum
 from functools import lru_cache
 from typing import Callable, Sequence
@@ -468,6 +480,15 @@ CLOSELOOP_DONE = "closeloop-done"
 # only after `add_evidence` succeeds, so a failed write retries next poll.
 CLOSELOOP_EVIDENCE_DONE = "closeloop-evidence-done"
 
+# NOT an operator page: an idempotency marker recording that the daemon closed a
+# released issue GitHub's `Closes #n` auto-close never closed (O16, issue #40).
+# It is what makes that repair happen EXACTLY once: an issue seen open again
+# with this marker set was re-opened by an operator -- the very escape hatch the
+# posted comment offers -- and is left alone for good, the close-edge twin of
+# park's "never re-labeling". Recorded only after the close succeeds, so a
+# failed close retries next poll.
+AUTOCLOSE_HEALED = "autoclose-healed"
+
 # The origin status the close-loop mutation itself hands off to. Seeing the task
 # already here (before CLOSELOOP_DONE was recorded) means a prior pass completed
 # the mutation but died before the completion marker -- orcloop's OWN transition,
@@ -613,6 +634,30 @@ CLOSELOOP_FAILED_ISSUE_COMMENT = (
     "Retrying; operator help may be needed."
 )
 
+# Posted on the issue the daemon closes on GitHub's behalf (O16, issue #40). It
+# says what was true, what the daemon did, and what it did NOT do -- a reader
+# arriving at a mechanically-closed issue must be able to tell this apart from
+# an operator closing it by hand, which is the whole reason it is commented and
+# not just logged. It names the merged PR because that PR is the entire
+# justification: without one this path is unreachable.
+AUTOCLOSE_HEALED_ISSUE_COMMENT = (
+    "**Orchestrator: completed a flaked auto-close** — this issue was closed by "
+    "the orchestrator, not by GitHub. Pull request {pr_url} merged {merged} and "
+    "declares that it closes this issue, but GitHub's own `Closes #n` "
+    "auto-close never fired (best-effort, not a contract), and the issue was "
+    "still open more than {grace}s later. The work is merged, so the "
+    "orchestrator completed the step the platform skipped and is now driving "
+    "the origin Alissa task forward. Nothing was reverted and no code changed; "
+    "if this issue was genuinely NOT finished by that pull request, reopen it "
+    "and correct the PR's closing keyword."
+)
+
+# The merge time as the comment above states it when the payload did not carry
+# one. Spelled out rather than left blank: "merged " followed by nothing reads
+# as a rendering bug, and this path is exactly the one a reader should treat
+# with suspicion.
+AUTOCLOSE_MERGED_AT_UNKNOWN = "at an unreported time"
+
 DEGRADED_DISCOVERY_REASON = (
     "release discovery was incomplete this pass ({count} feed body(ies) of "
     "work unreadable), so the two-body-of-work ambiguity check could not run "
@@ -2596,9 +2641,7 @@ class Orchestrator:
                     f"{slug}: label removed by operator — parked, never re-labeling",
                     task_number,
                 ))
-            return self._logged(ref, Decision(
-                Action.SKIPPED, f"{slug}: released issue still open — in flight", task_number,
-            ))
+            return self._evaluate_open_released(task_number, ref, slug, issue)
 
         try:
             pr = self.github.closing_merged_pr(owner, repo, number)
@@ -2624,6 +2667,290 @@ class Orchestrator:
 
         return self._close_loop(task_number, ref, slug, issue, pr)
 
+    def _evaluate_open_released(
+        self, task_number: int, ref: str, slug: str, issue: Issue
+    ) -> tuple[str, Decision]:
+        """A released issue that is still OPEN: genuinely in flight, or a
+        platform step that flaked and must be completed on GitHub's behalf.
+
+        Through 0.3.9 `open` was terminal for the pass -- "still open" meant
+        "still being worked on", and the closing PR was resolved only AFTER the
+        issue closed. That reading is wrong, and it cost a live incident
+        (studio#262 / PR #265, 2026-07-28): the PR merged with a properly-linked
+        `Closes #262` and GitHub's auto-close silently never fired, while the
+        sibling merge 21 seconds earlier auto-closed normally. **GitHub's
+        `Closes #n` auto-close is best-effort, not a contract.** Nothing
+        distinguished that issue from real work: the origin task sat
+        `in_progress` with no evidence, the phantom in-flight issue held its
+        scope in the repo lane against a queued task, and nothing escalated.
+
+        So the merged-closer read moves ahead of the open/closed split, and this
+        branch answers one of three ways:
+
+        * no merged closing PR -> in flight, exactly as before. This is the
+          common case and it is untouched: the daemon never closes an issue it
+          cannot point at a merged PR for.
+        * merged, inside the grace window -> SKIPPED, with a reason that says
+          which condition it is. The window exists so the daemon never RACES
+          GitHub for a step GitHub usually performs; the healthy case lands in
+          seconds, so a few minutes is well outside it.
+        * merged, past the window -> complete the step: close the issue
+          (`completed`, commented, WARNING-logged) and fall straight through
+          into the same close walk a natural auto-close would have produced --
+          in THIS pass, because an extra poll of latency is the thing the origin
+          task was already waiting on.
+
+        THE COST, stated as measured rather than as hoped. `repo_parallelism`
+        bounds how MANY issues reach here at once (1 in-flight released issue
+        per repo at the default), but it says nothing about how OFTEN, and this
+        walk now runs on every poll for as long as the issue stays open. Note
+        the shape: the healthy, common case -- genuinely in flight, no merged
+        closer -- is the EXPENSIVE one, because it never short-circuits and
+        fetches every cross-referenced candidate, so the per-poll cost grows
+        with an issue's discussion rather than with its work. Measured: 2 `gh`
+        calls per poll with one cross-referenced PR, 11 at the MAX_PR_CHECKS
+        cap, ~+120 calls/hour/repo at `poll_interval=60` and the default
+        parallelism -- small against a 5000/hour REST budget, but not zero, and
+        it was zero before.
+
+        There is deliberately no damper here yet. The obvious one (probe every
+        Nth poll) needs a design this change should not smuggle in: N interacts
+        with `poll_interval` to stretch the effective grace window, it needs
+        somewhere to survive a restart, and a throttled poll needs its own
+        decision reason so it cannot be mistaken for a healthy in-flight one.
+        The nearby `ESCALATION_CLOSED_UNMERGED` short-circuit exists for exactly
+        this reason on a TERMINAL row, whose cost is unbounded in time; this
+        one ends when the issue closes.
+
+        This is the devloop self-heal doctrine transposed to the close edge --
+        complete the dead protocol step on the platform's behalf, exactly once,
+        loudly -- the same family as the pushed-but-never-re-requested fix.
+
+        Park detection runs BEFORE this, in `_evaluate_close`, and stays there:
+        an operator who removed the label has said "stop acting on this", which
+        outranks any repair the daemon might otherwise perform.
+
+        "Exactly once" is enforced by the AUTOCLOSE_HEALED marker, recorded
+        after a successful close. Seeing an issue OPEN again with that marker
+        already set means the close landed and someone re-opened it -- which is
+        precisely what the comment the daemon posted invites a reader to do if
+        the PR did not really finish the work. Re-closing there would fight the
+        operator and make that invitation a lie, so the repair is refused for
+        good, exactly like park's "never re-labeling". It also covers the
+        cheaper case of a read-after-write that still reports the issue open:
+        one close, one comment, whatever the API's timing.
+        """
+        if self.state.escalated(task_number, AUTOCLOSE_HEALED):
+            return self._logged(ref, Decision(
+                Action.SKIPPED,
+                f"{slug}: auto-close already completed once and the issue is "
+                f"open again — operator reopened it, never re-closing",
+                task_number,
+            ))
+
+        try:
+            walk = self.github.close_walk(issue.owner, issue.repo, issue.number)
+        except (CommandError, RateLimited) as exc:
+            return self._logged(ref, Decision(
+                Action.HELD,
+                f"{slug}: could not resolve closing PR: {exc}",
+                task_number,
+            ))
+
+        pr = walk.pr
+        if pr is None:
+            return self._logged(ref, Decision(
+                Action.SKIPPED,
+                f"{slug}: released issue still open — in flight",
+                task_number,
+            ))
+
+        # HAS THIS ISSUE EVER BEEN CLOSED? -- the question the open/closed state
+        # cannot answer and the one this branch actually turns on. A flaked
+        # auto-close and a human's deliberate re-open are identical on every
+        # other signal: same open state, same merged PR declaring `Closes #n`,
+        # same elapsed time since the merge. Repairing the second is not a
+        # missed opportunity, it is REVERTING AN OPERATOR -- and posting a
+        # comment claiming the auto-close never fired when it did.
+        #
+        # Two independent signals, because each covers the other's blind spot:
+        # `state_reason` is free (it rides the issue payload already fetched)
+        # and exact, but it is a late API addition that can be empty on an issue
+        # re-opened long ago; the timeline's `closed` event is durable history
+        # but can fall past TIMELINE_MAX_PAGES on a very chatty issue. Either
+        # one refuses the repair, for good.
+        #
+        # `closed_at` is deliberately NOT among them: GitHub CLEARS it on
+        # reopen, so it is null on precisely the issues this must catch
+        # (verified against golang/go#79623, a real reopened issue).
+        #
+        # The accepted cost is a false NEGATIVE: an issue an operator closed and
+        # re-opened earlier in its life is never repaired, even by a genuinely
+        # flaked later merge. That fails toward leaving an operator's issue
+        # alone, which is the trade park already makes.
+        if issue.reopened or walk.ever_closed:
+            return self._logged(ref, Decision(
+                Action.SKIPPED,
+                f"{slug}: closed once already and open again — reopened, not a "
+                f"flaked auto-close; never re-closing",
+                task_number,
+            ))
+
+        # DID GITHUB EVEN OWE US AN AUTO-CLOSE? It fires only for a merge into
+        # the repository's DEFAULT branch: a PR carrying `Closes #n` that merges
+        # into `develop`, a release branch, or a stacked base leaves the issue
+        # open ON PURPOSE, and that is the platform working correctly.
+        #
+        # Through 0.3.9 the merged-closer predicate (merged + a closing keyword)
+        # only supplied ATTRIBUTION for a decision GitHub had already made, so
+        # being loose was harmless. Promoting it to the TRIGGER for a state
+        # mutation is what makes the missing check matter.
+        try:
+            default_branch = self.github.default_branch(issue.owner, issue.repo)
+        except (CommandError, RateLimited) as exc:
+            # Same posture as the closing-PR failure above: an unreadable input
+            # is not permission to close someone's issue.
+            return self._logged(ref, Decision(
+                Action.HELD,
+                f"{slug}: could not resolve the default branch of "
+                f"{issue.full_name}: {exc}",
+                task_number,
+            ))
+
+        if not default_branch:
+            # A read that SUCCEEDED but answered nothing is the same species of
+            # unknown as one that raised, and it must not fall through to the
+            # comparison below: with a non-empty `base_ref` that mismatch would
+            # be reported as "GitHub declined to auto-close a non-default
+            # merge", asserting a fact not in evidence -- the base may well have
+            # BEEN the default branch; the daemon just could not read it. Held,
+            # not skipped, so the row retries instead of silently never
+            # repairing. Recoverable because `default_branch` deliberately does
+            # not cache an empty answer.
+            return self._logged(ref, Decision(
+                Action.HELD,
+                f"{slug}: the default branch of {issue.full_name} could not be "
+                f"read (empty answer) — holding rather than guessing whether "
+                f"merged {pr.pr_slug} targeted it",
+                task_number,
+            ))
+
+        if not pr.base_ref or pr.base_ref != default_branch:
+            if not pr.base_ref:
+                # Unknown provenance cannot authorise a state mutation. Unlike
+                # an unmeasurable grace window -- which could only be granted
+                # FOREVER, the very hang this path exists to end -- refusing
+                # here hangs nothing: the issue stays exactly as GitHub left it.
+                log.warning(
+                    "%s: %s reports no base branch, so it cannot be confirmed "
+                    "to have merged into %s — refusing to close the issue on a "
+                    "merge whose target is unknown",
+                    slug, pr.pr_slug, default_branch,
+                )
+            return self._logged(ref, Decision(
+                Action.SKIPPED,
+                f"{slug}: merged {pr.pr_slug} targeted "
+                f"{pr.base_ref or '(unreported)'}, not the default branch "
+                f"{default_branch!r} — GitHub does not auto-close on a "
+                f"non-default merge, so there is nothing to repair",
+                task_number,
+            ))
+
+        grace = self.config.autoclose_grace_seconds
+        merged_epoch = pr.merged_epoch
+        if merged_epoch is not None and self._now() - merged_epoch < grace:
+            # Deliberately NOT a WARNING and not an escalation: for the first
+            # few minutes after a merge this state is what a perfectly healthy
+            # repo looks like. Only outliving the window makes it an anomaly.
+            return self._logged(ref, Decision(
+                Action.SKIPPED,
+                f"{slug}: closed by merged {pr.pr_slug} but still open — "
+                f"GitHub auto-close pending, within the {grace}s grace window",
+                task_number,
+            ))
+
+        # An unreadable/absent `mergedAt` lands HERE rather than in the branch
+        # above, i.e. it heals. The window is a courtesy extended to a platform
+        # step whose age we can measure; when the payload does not say when the
+        # merge happened, the courtesy cannot be granted without granting it
+        # FOREVER -- which is precisely the indefinite hang this whole change
+        # exists to end. The downside is bounded and self-announcing: at worst
+        # the daemon completes a close GitHub was about to perform anyway (the
+        # close is idempotent) and says so in a comment that names the merge
+        # time as unreported, so a spurious anomaly report is visible as one.
+        merged = (
+            f"at {pr.merged_at}" if merged_epoch is not None
+            else AUTOCLOSE_MERGED_AT_UNKNOWN
+        )
+        if self.config.dry_run:
+            # Sequenced here rather than with the real one below because there
+            # is no close to sequence it against, and its prefix already cannot
+            # be misread as a completed repair.
+            log.warning(
+                "[dry-run] would complete a flaked GitHub auto-close: %s is "
+                "still open but %s merged %s declaring it closed "
+                "(grace %ds elapsed)",
+                slug, pr.pr_slug, merged, grace,
+            )
+        else:
+            try:
+                self.github.close_issue(issue.owner, issue.repo, issue.number)
+            except (CommandError, RateLimited) as exc:
+                # HOLD, never walk: `_close_loop` and everything downstream of
+                # it assume the issue is closed -- that is what makes moving the
+                # origin task to `pending_validation` an honest report. An
+                # unclosed issue with a validated task is a worse state than one
+                # more poll of waiting, and the next poll re-enters here with
+                # the same inputs (no marker was recorded, nothing was mutated).
+                log.error("could not close %s on GitHub's behalf: %s", slug, exc)
+                return self._logged(ref, Decision(
+                    Action.HELD,
+                    f"{slug}: merged {pr.pr_slug} never auto-closed the issue "
+                    f"and closing it failed: {exc} — holding, no task mutation",
+                    task_number,
+                ))
+            # AFTER the close, never before it: this line is the anomaly report,
+            # and "completing" is the one word a log-scraper or a half-read
+            # alert picks up. Emitted ahead of the attempt it would announce a
+            # repair that a following ERROR then has to retract -- the anomaly
+            # stays just as visible logged here, and is never claimed falsely.
+            log.warning(
+                "completed a flaked GitHub auto-close: %s was still open but "
+                "%s merged %s declaring it closed (grace %ds elapsed)",
+                slug, pr.pr_slug, merged, grace,
+            )
+            # Recorded the moment the close lands, BEFORE the best-effort
+            # comment and before the walk: from here on the repair is done and
+            # must never be performed twice, whatever any later step does. A
+            # marker written after the walk would be lost on a walk that raises,
+            # which is the one path that re-enters this branch.
+            self.state.record_escalation(task_number, AUTOCLOSE_HEALED)
+            # Best-effort, and AFTER the close for idempotency: a comment that
+            # posted before a close which then failed would post again on the
+            # retry, so the audit trail would grow one copy per failure. Losing
+            # the comment costs an explanation the WARNING above still carries;
+            # losing the close would cost the fix.
+            try:
+                self.github.comment(
+                    issue.owner, issue.repo, issue.number,
+                    AUTOCLOSE_HEALED_ISSUE_COMMENT.format(
+                        pr_url=pr.url or pr.pr_slug, merged=merged, grace=grace,
+                    ),
+                )
+            except (CommandError, RateLimited) as exc:
+                log.warning(
+                    "best-effort auto-close explanation comment failed on %s: %s",
+                    slug, exc,
+                )
+
+        # Walk in the SAME pass, with the issue's state corrected to what the
+        # daemon just made true. `_close_loop` only reads the issue to address
+        # its escalation comments, but handing a stale `state="open"` to
+        # anything downstream is a trap for whatever reads it next.
+        return self._close_loop(
+            task_number, ref, slug, replace(issue, state="closed"), pr
+        )
+
     def _close_loop(
         self, task_number: int, ref: str, slug: str, issue: Issue, pr: PullRequest
     ) -> tuple[str, Decision]:

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

@@ -0,0 +1 @@
+0.3.10

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.10/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.9
+Version: 0.3.10
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.3.9