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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-orcloop
-Version: 0.3.9
+Version: 0.3.11
 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.11}/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.11}/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.11}/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.11}/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
@@ -416,6 +428,27 @@ ESCALATION_CLOSELOOP_FAILED = "closeloop-failed"
 ESCALATION_ALREADY_MERGED = "already-merged"
 ESCALATION_DEDUPE_UNREADABLE = "dedupe-unreadable"
 
+# The close edge could not write its evidence AT ALL -- not the enriched
+# delivery record, not the bare confirmation line -- for longer than the
+# close-loop retry floor, so the hand-off completed WITHOUT evidence (O17,
+# issue #44). Terminal by construction: it is raised on the pass that also
+# records `CLOSELOOP_EVIDENCE_DONE`, so there is never a second attempt to page
+# about. That is the whole point -- see `_close_evidence_unwritable`.
+ESCALATION_CLOSE_EVIDENCE_FAILED = "close-evidence-failed"
+
+# NOT an operator page: the timestamp of the FIRST permanent evidence rejection
+# on this task, so the floor above it measures how long THE FAILURE has lasted.
+# Same shape and same reasoning as `DEDUPE_UNREADABLE_SINCE` (including the
+# load-bearing `marker:` namespace, which keeps it out of every prefix read of
+# the page kind above), with one difference: this clock is never CLEARED. The
+# dedupe/context clocks time a condition that recurs on every poll of a task
+# still waiting to be released, so a blip that clears must not leave a stale
+# start time behind. The close-evidence step settles exactly once per task
+# (`CLOSELOOP_EVIDENCE_DONE` closes it for good, on every path), so this clock
+# can never be re-read after it settles -- leaving the row is free, and it is
+# the audit record of when the failure began.
+CLOSE_EVIDENCE_FAILED_SINCE = "marker:close-evidence-failed"
+
 # 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
@@ -459,15 +492,33 @@ MAX_CLOSED_TRAILER_CHECKS = 3
 # O2 design) purely for its per-(task, kind) dedupe; no comment is ever posted.
 CLOSELOOP_DONE = "closeloop-done"
 
-# NOT an operator page: an idempotency marker recording that the close-loop
-# merged-PR evidence has been attached to the origin task. Gating the evidence
-# write on THIS (rather than on the task still being `committed`) survives a
-# partial-failure retry that died AFTER the `committed → in_progress` step but
-# BEFORE the evidence write -- otherwise the retry re-enters at `in_progress`,
-# reads `first_entry` as False, and skips the evidence permanently. Recorded
-# only after `add_evidence` succeeds, so a failed write retries next poll.
+# NOT an operator page: an idempotency marker recording that the close-loop's
+# evidence step is SETTLED on the origin task. Gating the evidence write on THIS
+# (rather than on the task still being `committed`) survives a partial-failure
+# retry that died AFTER the `committed → in_progress` step but BEFORE the
+# evidence write -- otherwise the retry re-enters at `in_progress`, reads
+# `first_entry` as False, and skips the evidence permanently.
+#
+# "Settled", not "attached", since O17 (issue #44): the marker is recorded when
+# the enriched record lands, when the DEGRADED bare confirmation lands in its
+# place, and when both have been rejected permanently past the floor and the
+# hand-off gave up on evidence entirely. All three are ends of the same step --
+# there is nothing left for a later poll to attempt -- and one marker for the
+# step is what makes "no double write, no re-page" true on every path. It is
+# never recorded while a retry is still owed: a transient failure, or a
+# permanent one inside the floor, raises instead, leaving the marker absent so
+# the next poll re-enters exactly as before.
 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 +664,78 @@ CLOSELOOP_FAILED_ISSUE_COMMENT = (
     "Retrying; operator help may be needed."
 )
 
+# The TERMINAL page of the close edge (O17, issue #44). Everything a page has to
+# say when the daemon stops: what it could not do, what it is doing anyway, that
+# it will not try that again, and what is left for a human. The last part
+# matters most -- the operator's soft validator is what reads evidence, and this
+# task now reaches it without any, so the comment has to say where the record
+# went.
+#
+# EVERY CLAIM IS SCOPED TO WHAT IS TRUE AT POST TIME, and that is a constraint
+# the wording had to be rewritten for (review round 1). The page is posted from
+# `_close_evidence_unwritable`, which runs BEFORE `_mutate_close`'s
+# `set_status(pending_validation)` -- it has to, because the page landing is
+# what licenses the walk to continue. So it must not report the hand-off in the
+# past tense (a hand-off write can fail, transiently or for good, and then the
+# task sits at `in_progress` under a comment claiming otherwise), and it must
+# not promise silence on behalf of the whole loop (a failed hand-off pages
+# `closeloop-failed:a<j>` on the very next line, retracting the retraction).
+#
+# What IS terminal here is exactly the step this page is about: the evidence
+# will never be attempted again -- `CLOSELOOP_EVIDENCE_DONE` is recorded on this
+# same pass, on every path out of it. So the terminality is stated about the
+# evidence, and the close-loop's own retries are named as the separate condition
+# they are. Same standard `_autoclose_heal`'s comment holds for a mere WARNING
+# ("AFTER the close, never before it"), applied to something that outranks it.
+CLOSE_EVIDENCE_FAILED_TASK_COMMENT = (
+    "**Orchestrator: close evidence could not be attached** — the released "
+    "issue {slug} merged, but attaching the merged-pull-request evidence to "
+    "this task was rejected permanently (not a rate limit or an outage) for "
+    "over {floor_hours}h, with the full delivery record AND a bare merge "
+    "confirmation both refused: {error}. **The orchestrator has given up on "
+    "the evidence — it will not be attempted again — and is completing the "
+    "close hand-off without it now**, moving this task to `pending_validation`: "
+    "the merge is a fact, and holding it at `in_progress` over a missing "
+    "write-up is strictly worse than thin evidence. The delivery record is on "
+    "the merged pull request {pr_url}; attach it by hand if validating this "
+    "task needs it. Usual causes: the orchestrator's token lost its role on "
+    "this task, or the evidence endpoint is rejecting the request outright. "
+    "(If that hand-off write fails too it is a separate condition and pages "
+    "separately as `close-loop failed`; those retries are about the status "
+    "transition, never about this evidence.)"
+)
+CLOSE_EVIDENCE_FAILED_ISSUE_COMMENT = (
+    "**Orchestrator: close evidence could not be attached** — this issue's "
+    "merge is being handed off to its origin Alissa task WITHOUT the "
+    "merged-pull-request evidence: writing it was refused permanently and the "
+    "orchestrator has stopped trying. Nothing is needed here — the record is "
+    "on the merged pull request, and any remaining problem is on the task."
+)
+
+# 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 "
@@ -688,14 +811,19 @@ DELIVERY_NOTES_HEADING = "## Delivery notes"
 # compatibility commitment.
 #
 # THE HEADROOM IS MEASURED, not assumed, because the size of this write is the
-# one way this feature could newly BLOCK a close: `add_evidence` is not wrapped
-# in `_mutate_close`, `_close_loop` routes its `AlissaError` to
-# `_closeloop_failed`, and `set_status(pending_validation)` comes after it -- so
-# a rejection that is deterministic rather than transient would strand the
-# origin task at `in_progress` on every future poll. `AddEvidenceRequest`
-# declares `markdownContent` with a `minLength` and NO `maxLength`, so the
-# ceiling was probed directly against the live endpoint (2026-07-28, disposable
-# task, since cancelled):
+# one way this feature could newly BLOCK a close -- and O17 (issue #44) did NOT
+# retire that argument, it narrowed it. A permanent rejection now degrades to
+# the bare confirmation line and, past the floor, gives up on evidence rather
+# than stranding the task (`_attach_close_evidence`), but that ladder is driven
+# by the client's status taxonomy: `AlissaTransient` is 408/429/5xx, and the
+# oversize failure below answers **HTTP 500**. An over-cap body is therefore
+# deterministic AND classified transient -- the one shape that retries forever
+# with the identical payload and never reaches the degrade. Nothing here is
+# wrong: statuses are the contract and codes are advisory (see `_classify`), so
+# the guard against that shape is THIS CAP, not the ladder.
+# `AddEvidenceRequest` declares `markdownContent` with a `minLength` and NO
+# `maxLength`, so the ceiling was probed directly against the live endpoint
+# (2026-07-28, disposable task, since cancelled):
 #
 #     32,300 -> 201     131,072 -> 201     524,288 -> 201
 #     65,536 -> 201     262,144 -> 201   1,048,576 -> 500
@@ -911,20 +1039,31 @@ class Orchestrator:
         task_comment: str,
         issue: Issue | None = None,
         issue_comment: str | None = None,
-    ) -> None:
-        """Raise an operator escalation once per (task, kind).
+    ) -> bool:
+        """Raise an operator escalation once per (task, kind). Returns whether
+        the page HAS BEEN DELIVERED -- True when a dedupe row exists for it
+        after this call, which (see below) is exactly "the primary comment
+        posted, now or on an earlier pass".
 
         Primary channel is a comment on the Alissa task; the GitHub issue gets
         a best-effort comment too when one exists. All dry-run gated. The
         dedupe row is recorded only AFTER the primary comment posts, so a
         transient primary failure retries next poll (exactly-once primary
-        delivery) rather than latching a page that never landed."""
+        delivery) rather than latching a page that never landed.
+
+        That ordering is what makes the return value meaningful rather than
+        decorative: a caller whose next step is IRREVERSIBLE if nobody was told
+        (`_close_evidence_unwritable` settles the evidence step, which stops
+        every future attempt AND every future page) can gate on the receipt
+        instead of re-reading the ledger and hoping the two stay in step. Every
+        pre-existing caller ignores it, which is unchanged behaviour: a page
+        that could not be posted was already retried next poll."""
         if self.state.escalated(task_number, kind):
-            return
+            return True
         ref = f"TASK-{task_number}"
         if self.config.dry_run:
             log.info("[dry-run] would escalate %s on %s:\n%s", kind, ref, task_comment)
-            return
+            return False
 
         try:
             self.alissa.add_comment(ref, task_comment)
@@ -933,7 +1072,7 @@ class Orchestrator:
                 "could not post %s escalation on %s: %s — not recording; "
                 "retries next poll", kind, ref, exc,
             )
-            return
+            return False
 
         if issue is not None and issue_comment is not None:
             try:
@@ -944,6 +1083,7 @@ class Orchestrator:
                     kind, issue.issue_slug, exc,
                 )
         self.state.record_escalation(task_number, kind)
+        return True
 
     # ======================================================================
     # RELEASE EDGE
@@ -2596,9 +2736,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 +2762,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]:
@@ -2676,7 +3098,7 @@ class Orchestrator:
             ))
 
         try:
-            self._mutate_close(task_number, ref, task, slug, pr)
+            self._mutate_close(task_number, ref, task, slug, issue, pr)
         except AlissaError as exc:
             return self._closeloop_failed(task_number, slug, issue, exc, prior)
 
@@ -2688,7 +3110,13 @@ class Orchestrator:
         ))
 
     def _mutate_close(
-        self, task_number: int, ref: str, task: Task, slug: str, pr: PullRequest
+        self,
+        task_number: int,
+        ref: str,
+        task: Task,
+        slug: str,
+        issue: Issue,
+        pr: PullRequest,
     ) -> None:
         """The close-loop mutation, ordered for idempotency on partial-failure
         retry. Two independent idempotency gates, each keyed on what it actually
@@ -2698,8 +3126,8 @@ class Orchestrator:
           `committed`, so a retry that re-enters at `in_progress` never re-issues
           the (illegal) `in_progress → in_progress` transition;
         * the merged-PR evidence write is gated on the `CLOSELOOP_EVIDENCE_DONE`
-          marker, recorded only AFTER the write lands. A retry that died between
-          the `in_progress` step and the evidence write re-enters at
+          marker, recorded only once that step is SETTLED. A retry that died
+          between the `in_progress` step and the evidence write re-enters at
           `in_progress` with the marker absent, so it still attaches the evidence
           -- where a shared `first_entry` flag would have skipped it forever
           (the task would reach `pending_validation` with no merged-PR audit
@@ -2712,6 +3140,11 @@ class Orchestrator:
         failure mode to the walk: a PR whose write-up cannot be read still
         reaches `pending_validation`, carrying an explicit line saying so.
 
+        And since O17 (issue #44), a rejected write cannot stop the walk either:
+        `_attach_close_evidence` owns the whole ladder (degrade to the bare
+        line, then give up past the floor), so THIS method's last line is
+        reached on every path that is not still owed a retry.
+
         Criteria satisfaction is naturally idempotent (already-satisfied ones are
         skipped), so it needs no gate."""
         if task.status == TASK_TODO_STATE:
@@ -2719,14 +3152,173 @@ class Orchestrator:
         for criterion in task.criteria:
             if not criterion.satisfied:
                 self.alissa.satisfy_criterion(ref, criterion.id)
-        if not self.state.escalated(task_number, CLOSELOOP_EVIDENCE_DONE):
+        self._attach_close_evidence(task_number, ref, slug, issue, pr)
+        self.alissa.set_status(ref, "pending_validation")
+
+    def _attach_close_evidence(
+        self, task_number: int, ref: str, slug: str, issue: Issue, pr: PullRequest
+    ) -> None:
+        """Attach the merged-PR evidence, or settle the step without it. The
+        one rule: never RAISE unless a retry is genuinely owed, because the
+        caller's next line is the `pending_validation` hand-off and an
+        exception here strands the task at `in_progress` (issue #44 -- the
+        strand this method exists to remove).
+
+        The ladder, in the order a failure walks it:
+
+        1. **Transient** (`AlissaTransient`: 408/429/5xx or a transport
+           failure) -- re-raised untouched, at every rung. This is the ONLY
+           path that keeps today's behavior byte-for-byte: `_close_loop` routes
+           it to `_closeloop_failed`, which pages `closeloop-failed:a<j>` and
+           floors the retry. An outage must not spend the degrade.
+        2. **Permanent rejection of the ENRICHED body** -- retried ONCE,
+           immediately, with the bare `CLOSE_EVIDENCE_BODY`. The enriched record
+           is the only *variable* input to this write (a PR body someone else
+           authored, up to `CLOSE_EVIDENCE_RECORD_MAX_CHARS` of it), so it is
+           the first suspect for a deterministic refusal, and dropping it is
+           the same "degrade loudly, never block" trade `render_close_evidence`
+           already makes for an unreadable body. Nothing is added to the bare
+           payload to explain the degradation: the payload is the suspect, and
+           the log line is where the explanation belongs.
+        3. **Permanent rejection of the BARE line too** -- the payload was
+           never the problem (a lost role, an endpoint refusing outright), so
+           `_close_evidence_unwritable` decides between one more retry and
+           giving up.
+
+        Why the split at transient/permanent is `AlissaTransient` and not a
+        status test here: the client's taxonomy already IS that split (it keys
+        on status, which is the contract), and `_dedupe_unreadable`'s lesson is
+        the reason it matters -- a self-clearing rate limit must never spend a
+        one-shot remedy that a real, permanent failure will need."""
+        if self.state.escalated(task_number, CLOSELOOP_EVIDENCE_DONE):
+            return
+        try:
             self.alissa.add_evidence(
                 ref,
                 CLOSE_EVIDENCE_TITLE,
                 render_close_evidence(slug, pr),
             )
-            self.state.record_escalation(task_number, CLOSELOOP_EVIDENCE_DONE)
-        self.alissa.set_status(ref, "pending_validation")
+        except AlissaTransient:
+            raise
+        except AlissaError as rich_exc:
+            log.warning(
+                "%s: the close evidence was REJECTED permanently on %s (%s) — "
+                "retrying once with the bare merge confirmation, without the "
+                "merged pull request's delivery record",
+                slug, ref, rich_exc,
+            )
+            try:
+                self.alissa.add_evidence(
+                    ref,
+                    CLOSE_EVIDENCE_TITLE,
+                    CLOSE_EVIDENCE_BODY.format(slug=slug, pr_url=pr.url),
+                )
+            except AlissaTransient:
+                raise
+            except AlissaError as bare_exc:
+                self._close_evidence_unwritable(
+                    task_number, ref, slug, issue, pr, bare_exc,
+                )
+            else:
+                log.warning(
+                    "%s: DEGRADED close evidence attached to %s — the merge "
+                    "confirmation only; the delivery record was rejected (%s) "
+                    "and is on the pull request %s",
+                    slug, ref, rich_exc, pr.url or pr.pr_slug,
+                )
+        self.state.record_escalation(task_number, CLOSELOOP_EVIDENCE_DONE)
+
+    def _close_evidence_unwritable(
+        self,
+        task_number: int,
+        ref: str,
+        slug: str,
+        issue: Issue,
+        pr: PullRequest,
+        exc: AlissaError,
+    ) -> None:
+        """Neither the enriched record nor the bare line could be written, and
+        the refusal was permanent. Either raise (a retry is still owed) or
+        return, having paged terminally -- the caller then settles the step and
+        the hand-off finishes WITHOUT evidence.
+
+        Why give up at all: a permanent refusal does not self-heal, so the
+        alternative is re-attempting the identical write every poll forever
+        while the origin task sits at `in_progress` and the operator is paged
+        on a schedule. The merge already happened; thin evidence on a task that
+        reached `pending_validation` is strictly better than a full record on a
+        task nobody can validate. That is the same trade the close edge already
+        makes for an unreadable PR body, taken one rung further down.
+
+        Why not give up on the FIRST permanent refusal, since a deterministic
+        failure is deterministic by definition: because "permanent" here is a
+        CLASSIFICATION, not an observation. A 403 is permanent as a rule and
+        transient in fact when a role is being re-granted, and this remedy is
+        one-shot -- the evidence is dropped for good. So the first refusal
+        records this clock and re-raises into today's unchanged path (page,
+        floor, retry), and only a refusal that is STILL permanent
+        `CLOSELOOP_RETRY_FLOOR_SECONDS` later spends the remedy. The floor
+        measures THE FAILURE and not the task's age, for the reason
+        `_dedupe_unreadable` gives at length.
+
+        Why the page must have LANDED before the step settles: settling is what
+        stops every future attempt, so a give-up whose page never posted would
+        be silent forever -- the exact failure mode issue #44 is about, moved
+        one layer up. `_escalate` records its dedupe row only after the primary
+        comment posts, so it can say whether the page was delivered and this
+        gates on that; without it, this raises instead and the give-up is
+        re-attempted next poll. (When the page cannot post because the token
+        lost its role on the task, the `pending_validation` write below was
+        going to fail anyway -- so nothing is stranded that was not already.)
+
+        What this page may NOT claim: the hand-off in the past tense, or
+        silence from the close loop. Both were false in round 1 -- see
+        `CLOSE_EVIDENCE_FAILED_TASK_COMMENT`, which now scopes its terminality
+        to the evidence step, the one thing this method really does end."""
+        rows = self.state.escalations_matching(task_number, CLOSE_EVIDENCE_FAILED_SINCE)
+        now = int(self._now())
+        if not rows:
+            self.state.record_escalation(task_number, CLOSE_EVIDENCE_FAILED_SINCE, at=now)
+            log.error(
+                "%s: close evidence rejected permanently on %s, bare line too "
+                "(%s) — first refusal, retrying behind the close-loop floor",
+                slug, ref, exc,
+            )
+            raise exc
+        failing_for = now - int(rows[0]["escalated_at"])
+        if failing_for < CLOSELOOP_RETRY_FLOOR_SECONDS:
+            log.error(
+                "%s: close evidence rejected permanently on %s, bare line too "
+                "(%s) — refused for %ds, within the %ds floor; retrying",
+                slug, ref, exc, failing_for, CLOSELOOP_RETRY_FLOOR_SECONDS,
+            )
+            raise exc
+
+        delivered = self._escalate(
+            task_number,
+            ESCALATION_CLOSE_EVIDENCE_FAILED,
+            CLOSE_EVIDENCE_FAILED_TASK_COMMENT.format(
+                slug=slug,
+                floor_hours=CLOSELOOP_RETRY_FLOOR_SECONDS // 3600,
+                error=exc,
+                pr_url=pr.url or pr.pr_slug,
+            ),
+            issue,
+            CLOSE_EVIDENCE_FAILED_ISSUE_COMMENT,
+        )
+        if not delivered:
+            log.error(
+                "%s: giving up on close evidence for %s, but the terminal page "
+                "could not be delivered — NOT settling; retries next poll",
+                slug, ref,
+            )
+            raise exc
+        log.error(
+            "%s: GAVE UP on close evidence for %s after %ds of permanent "
+            "refusals (%s) — completing the hand-off without it; operator "
+            "paged once, no further attempts",
+            slug, ref, failing_for, exc,
+        )
 
     def _closeloop_failed(
         self, task_number: int, slug: str, issue: Issue, exc: Exception, prior: list

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

@@ -0,0 +1 @@
+0.3.11

{alissa_tools_github_orcloop-0.3.9 → alissa_tools_github_orcloop-0.3.11/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.11
 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