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

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

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

@@ -428,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
@@ -471,13 +492,22 @@ 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
@@ -634,6 +664,54 @@ 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
@@ -733,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
@@ -956,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)
@@ -978,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:
@@ -989,6 +1083,7 @@ class Orchestrator:
                     kind, issue.issue_slug, exc,
                 )
         self.state.record_escalation(task_number, kind)
+        return True
 
     # ======================================================================
     # RELEASE EDGE
@@ -3003,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)
 
@@ -3015,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
@@ -3025,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
@@ -3039,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:
@@ -3046,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.10 → 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.10
+Version: 0.3.11
 Summary: ALISSA-TOOLS-GITHUB-ORCLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

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