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

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

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

{alissa_tools_github_orcloop-0.3.1 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/__main__.py

@@ -2,7 +2,8 @@
 
 O1 wired the config surface and the argument parser; O3 wires the decision
 loop behind it; O6 adds the release-feed selector (`--release-feed bow` and its
-`--bow-prefix` / `--bow-owner` / `--scan-fallback-interval` knobs).
+`--bow-prefix` / `--bow-owner` / `--scan-fallback-interval` knobs); O8 makes the
+feed's authority resolve itself (see `resolve_feed_authority`).
 
 The CLI resolves and validates the full configuration
 (four-layer precedence, fail-closed `repos` guard), reports the effective
@@ -10,6 +11,12 @@ settings, then runs the orchestrator: `--once` for a single sweep (pair it
 with `--dry-run -v` to print every decision and its reasons without touching
 GitHub or the task graph), otherwise `run_forever`. Config errors still surface
 here, at startup, with a clean exit code.
+
+Startup is the ONE place that may do I/O before the loop begins, and it does
+exactly one call: under `release_feed: bow` with no explicit `bow_owners`, the
+daemon asks Alissa who its token is and makes itself the feed authority. That
+call failing is fatal — the daemon exits rather than starting up unable to tell
+its own containers from a stranger's.
 """
 
 from __future__ import annotations
@@ -17,9 +24,10 @@ from __future__ import annotations
 import argparse
 import logging
 import sys
+from dataclasses import replace
 from pathlib import Path
 
-from .alissa_client import AlissaError
+from .alissa_client import AlissaClient, AlissaError
 from .config import (
     FEED_BOW,
     RELEASE_FEEDS,
@@ -119,10 +127,12 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="ACTOR_ID",
         help="bow feed only: trust bodies of work OWNED by this Alissa actor "
         "as release feeds; repeatable. When given, REPLACES the config "
-        "`bow_owners` list. Fail-closed like --repo: `--release-feed bow` with "
-        "an empty owner list is a fatal startup error, because being SHARED a "
-        "body of work is not a claim to drive this daemon. An actor id is the "
-        "`ownerActorId` on the container's row in GET /v1/bodies-of-work.",
+        "`bow_owners` list. OPTIONAL — left unset, the daemon resolves its own "
+        "token's actor at boot and trusts only its own containers; give this "
+        "flag only when the containers belong to someone else. Being SHARED a "
+        "body of work is never a claim to drive this daemon either way. Must be "
+        "an actor ID (the `ownerActorId` on the container's row in "
+        "GET /v1/bodies-of-work) — a username or display name is refused.",
     )
     over.add_argument(
         "--scan-fallback-interval",
@@ -197,6 +207,57 @@ def resolve_config(args: argparse.Namespace) -> Config:
     return Config.build(workspace_root, file_data, overrides_from(args))
 
 
+def resolve_feed_authority(config: Config, alissa: AlissaClient) -> Config:
+    """Decide WHOSE bodies of work drive this daemon, and say so out loud.
+
+    Two answers, one of them free:
+
+    * `bow_owners` **set** — the operator named the authority explicitly. That
+      is the multi-operator case: the containers belong to an actor this token
+      is not. Nothing is resolved, nothing is called.
+    * `bow_owners` **unset** — the authority is **self**. The token already
+      carries an identity, so `GET /v1/ping` answers the question the operator
+      would otherwise have hand-copied out of the API, and the daemon trusts
+      exactly its own containers.
+
+    The whoami call is **fatal on failure**, deliberately, and this is the whole
+    fail-closed argument in one place. The alternative — carry on with an empty
+    authority — is technically safe (nothing would be trusted, so nothing would
+    release) but it is safe *silently*: the operator sees a daemon that runs and
+    releases nothing, which is exactly what a correctly configured daemon with
+    an empty queue looks like. Dying names the reason while someone is watching.
+    Note the property being protected is not "self is trusted" but "only a
+    KNOWN actor is trusted" — an unanswered whoami leaves that unknown, and no
+    default can fill it in.
+
+    Under `scan` this is a no-op: that feed never reads a Body of Work, so it
+    never needs an identity, and a daemon that only scans must not fail to boot
+    because an endpoint it does not use was unreachable.
+    """
+    if config.release_feed != FEED_BOW:
+        return config
+
+    if config.bow_owners:
+        log.info(
+            "bow feed authority: explicit (%s)", ", ".join(config.bow_owners)
+        )
+        return config
+
+    identity = alissa.whoami()  # fatal on failure — see main()
+    log.info("bow feed authority: self (%s)", identity.actor_id)
+    if identity.display_name:
+        # Logged as context, never compared: a display name is renameable, which
+        # is why `config.bow_owners` refuses to hold one.
+        log.debug(
+            "resolved from this token's identity: %r", identity.display_name
+        )
+    # The id comes from the API, so it is the authority on its own shape and is
+    # NOT put through `config`'s actor-id check — that check exists to catch a
+    # human typing a username, and applying it here would let a future id format
+    # break a daemon that had been given no configuration to be wrong about.
+    return replace(config, bow_owners=(identity.actor_id,))
+
+
 def log_effective_config(config: Config) -> None:
     """The resolved settings, defaults and all. INFO carries the decisions an
     operator needs; -v (DEBUG) shows the full surface."""
@@ -241,14 +302,52 @@ def main(argv: "list[str] | None" = None) -> int:
     try:
         config = resolve_config(args)
         log.info("workspace: %s", config.workspace_root)
-        log_effective_config(config)
-    except (FileNotFoundError, ValueError) as exc:
+        # One client, shared with the orchestrator: the boot-time whoami and
+        # every later task-graph call must speak as the same actor, or the
+        # authority resolved here would not be the one doing the reading.
+        alissa = AlissaClient(base=config.alissa_endpoint)
+    except (FileNotFoundError, ValueError, AlissaError) as exc:
+        # `AlissaError` is here to keep main()'s exit contract whole, not because
+        # anything in this block raises one today (the client's constructor only
+        # reads ALISSA_BASE / ALISSA_API_TOKEN). Exit 2 means "never started" and
+        # every other way of never starting prints one line; a lone path that
+        # answers with a traceback and exit 1 — the code that means "started,
+        # then a pass failed" — would misreport itself the day the constructor
+        # grows any validation. Plain text, deliberately: the bow-specific advice
+        # belongs only to the call that can actually earn it, below.
         print(f"config error: {exc}", file=sys.stderr)
         return 2
     except KeyboardInterrupt:
         return 0
 
-    orchestrator = Orchestrator(config)
+    # Deliberately its OWN try, holding exactly one call. The handler below
+    # names the bow feed, and `resolve_feed_authority` is the only thing here
+    # that can fail for that reason — under `scan` it returns before making any
+    # call at all. A wider block would let some unrelated Alissa failure be
+    # reported as an authority problem, pointing a scan-only operator at a knob
+    # that does nothing in their feed mode.
+    try:
+        config = resolve_feed_authority(config, alissa)
+    except AlissaError as exc:
+        # The bow feed could not learn who this token is. Fatal by design (see
+        # resolve_feed_authority): booting on an unknown identity would mean a
+        # daemon that looks healthy and silently releases nothing. Same exit
+        # code as a config error — it is the same class of failure, a daemon
+        # that never started, and the operator's fix is a token or an explicit
+        # bow_owners rather than anything the loop could retry.
+        print(
+            f"config error: could not resolve the bow feed authority — {exc}. "
+            f"Check ALISSA_API_TOKEN and the endpoint, or set bow_owners "
+            f"explicitly to name the actor(s) that own the feed bodies of work.",
+            file=sys.stderr,
+        )
+        return 2
+    except KeyboardInterrupt:
+        return 0
+
+    log_effective_config(config)
+
+    orchestrator = Orchestrator(config, alissa=alissa)
     try:
         if args.once:
             orchestrator.poll_once()

{alissa_tools_github_orcloop-0.3.1 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/alissa_client.py

@@ -94,6 +94,18 @@ Both BOW endpoints require the daemon actor to be a **collaborator** on the
 Body of Work (otherwise 403 ``FORBIDDEN`` on attach/detach) -- an operator setup
 step, documented in the README. orcloop never attaches: attaching is the
 operator's trigger, detaching is orcloop's terminal release act.
+
+WHO AM I (O8)
+=============
+``GET /v1/ping`` -- ``{"pong", "timestamp", "userId", "actorId",
+"displayName"}`` -- is the token's identity endpoint, and it is the ONLY one:
+``/v1/me``, ``/v1/whoami``, ``/v1/actors/me``, ``/v1/auth/me``, ``/v1/user(s)/me``,
+``/v1/identity``, ``/v1/actor``, ``/v1/session``, ``/v1/profile`` all answer 404
+``"The requested endpoint does not exist."``. Its OpenAPI summary states the
+contract outright: *"Verify the token and return the acting identity."* That is
+what lets ``bow_owners`` default to the daemon's own actor instead of making the
+operator hand-copy an id -- see ``whoami`` and the boot resolution in
+``__main__.resolve_feed_authority``.
 """
 
 from __future__ import annotations
@@ -189,6 +201,21 @@ class BowMember:
     status: str
 
 
+@dataclass(frozen=True)
+class Identity:
+    """Who this token acts as, from ``GET /v1/ping``.
+
+    `actor_id` is the load-bearing field: it is the same opaque id that appears
+    as `ownerActorId` on a Body of Work, so it can be compared directly against
+    a container's owner. `user_id` and `display_name` are carried for logging
+    only -- a display name is renameable and must never reach an authority
+    check (see `config.bow_owners`)."""
+
+    actor_id: str
+    user_id: str = ""
+    display_name: str = ""
+
+
 @dataclass(frozen=True)
 class Criterion:
     id: str
@@ -317,6 +344,37 @@ class AlissaClient:
 
     # --- adapter surface ---------------------------------------------------
 
+    def whoami(self) -> Identity:
+        """The identity this token acts as (`GET /v1/ping`).
+
+        The `bow` feed's authority defaults to this actor, so the call is on the
+        BOOT path and its failure is fatal there -- never softened into a
+        warning. A daemon that could not learn who it is cannot tell its own
+        containers from a stranger's, and the only safe answers are "refuse to
+        start" or "trust nobody"; refusing is the loud one, so that is what
+        `__main__.resolve_feed_authority` does with what this raises.
+
+        A 2xx with no `actorId` is a contract violation rather than a missing
+        resource, so it surfaces as the base `AlissaError` -- the same way
+        `get_task` treats a response with no task object. `AlissaAuthError`
+        (a bad or unset token) and `AlissaTransient` (the endpoint was
+        unreachable) come through the shared taxonomy unchanged.
+        """
+        payload = self._request("GET", "/v1/ping")
+        row = payload if isinstance(payload, dict) else {}
+        actor_id = row.get("actorId")
+        if not isinstance(actor_id, str) or not actor_id.strip():
+            raise AlissaError(
+                200,
+                f"GET /v1/ping returned no actorId (got {payload!r}) — the "
+                f"token's acting identity could not be determined",
+            )
+        return Identity(
+            actor_id=actor_id.strip(),
+            user_id=str(row.get("userId") or ""),
+            display_name=str(row.get("displayName") or ""),
+        )
+
     def list_marked_committed_tasks(self, marker: str = RELEASE_MARKER) -> list[MarkedTask]:
         """Committed tasks carrying the release `marker`, with descriptions.
 

{alissa_tools_github_orcloop-0.3.1 → alissa_tools_github_orcloop-0.3.3}/src/main/alissa/tools/github/orcloop/config.py

@@ -50,15 +50,28 @@ RELEASE FEED (O6). `release_feed` selects where release candidates come from:
   O(total BOW membership). `scan_fallback_interval` keeps a low-frequency full
   trailer scan running underneath as a visibility safety net.
 
-The `bow` feed has a **second** fail-closed allowlist, `bow_owners`, and the two
-answer different questions. A container's title says which repo it targets, so
-`repos` bounds *where* a release lands. Nothing in a title says who created the
+The `bow` feed has a **second** allowlist, `bow_owners`, and the two answer
+different questions. A container's title says which repo it targets, so `repos`
+bounds *where* a release lands. Nothing in a title says who created the
 container — and the daemon lists Bodies of Work it merely **collaborates** on,
 which any actor in the tenant can arrange without an acceptance step on this
 side. `bow_owners` names the actor id(s) whose containers may drive the daemon,
-so "whose work reaches an autonomous pipeline" is an operator decision rather
-than a consequence of being shared something. Empty is fatal under
-`release_feed: bow`, exactly as an empty `repos` is fatal always.
+so "whose work reaches an autonomous pipeline" is a decided question rather
+than a consequence of being shared something.
+
+FEED AUTHORITY (O8). `bow_owners` is an OPTIONAL OVERRIDE, not required setup.
+Left unset it resolves at boot to the **token's own actor** — the daemon asks
+`GET /v1/ping` who it is and trusts only its own containers (see
+`__main__.resolve_feed_authority`, which is also where a failed whoami is
+fatal). Set it only for a multi-operator deployment, where the containers are
+owned by someone other than the actor the daemon's token acts as. That the
+default is self does not soften the gate: an unresolvable identity refuses to
+boot rather than trusting everything, so the fail-closed property `bow_owners`
+was introduced for is unchanged — only the hand-copying is gone.
+
+Entries are actor **ids** and nothing else; a username or display name is
+rejected here, naming it (see `_validate_actor_id` for why a name is both a
+spoof surface and a silent one).
 """
 
 from __future__ import annotations
@@ -137,6 +150,21 @@ _REPO_NAME_RE = re.compile(
     r"/(?!\.+$)(?!.*\.[Gg][Ii][Tt]$)[A-Za-z0-9._-]+$"
 )
 
+# What an Alissa actor id looks like: a 32-character opaque handle of lower-case
+# letters and digits (`j5706fv7xe5jy1k5wdwzacab9s8axcd2`). Every id the API mints
+# — actors, users, tasks, bodies of work — has this shape, and `bow_owners` is
+# checked against it so a username or display name cannot be mistaken for one.
+# The check is SHAPE only: it says "this could be an id", never "this actor
+# exists" (nothing short of a lookup could, and a wrong-but-well-formed id
+# already fails loudly as a feed nobody owns). If the API ever mints a different
+# shape, this constant and the pattern below are the two lines to widen.
+ACTOR_ID_LENGTH = 32
+_ACTOR_ID_ALPHABET = frozenset("abcdefghijklmnopqrstuvwxyz0123456789")
+# `\Z`, not `$`: `$` also matches just before a trailing newline, so
+# `"<id>\n"` would pass. Callers strip, but a gate that only holds because its
+# caller normalised is not a gate.
+_ACTOR_ID_RE = re.compile(rf"^[a-z0-9]{{{ACTOR_ID_LENGTH}}}\Z")
+
 MIN_POLL_INTERVAL = 10  # the GitHub search API allows 30 req/min
 
 DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
@@ -257,6 +285,88 @@ def _validate_repo_entry(entry: str) -> None:
     )
 
 
+def normalize_bow_owners(values: tuple[str, ...] | list[str]) -> tuple[str, ...]:
+    """Turn the raw `bow_owners` layer value into the validated authority list.
+
+    Entries are whitespace-stripped, empties dropped (so a trailing comma is
+    harmless, matching `repos`), duplicates collapsed — EXACTLY, with no
+    casefolding, because actor ids are opaque: two spellings that differ in case
+    are two different strings on the wire, and folding them would silently widen
+    the match. Every survivor must look like an actor id.
+
+    Emptiness is fine here and means "not overridden": the boot path resolves
+    the authority to this token's own actor (see the module docstring). There is
+    no fail-closed guard left in `build` for it — an empty list still admits
+    nothing (`trusts_feed_owner` returns False for every owner), so the property
+    is preserved by the comparison itself rather than by refusing to start.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        entry = value.strip()
+        if not entry:
+            continue
+        _validate_actor_id(entry)
+        if entry not in seen:
+            seen.add(entry)
+            out.append(entry)
+    return tuple(out)
+
+
+def _validate_actor_id(entry: str) -> None:
+    """Reject anything that is not an Alissa actor id, naming the entry.
+
+    Ownership is checked against a container's `ownerActorId`, which is opaque
+    and immutable. A username or display name is neither: it is operator-facing
+    text the owning account can CHANGE, so an allowlist written in those terms
+    grants authority to whoever holds the name when the check runs rather than
+    to the actor the operator meant — the reason ids are the only accepted
+    spelling.
+
+    Worse, getting it wrong would not even be loud. Nothing on the wire ever
+    equals a name, so a name in this list simply matches no container, and the
+    `bow` feed's symptom is an empty queue — indistinguishable from "no work
+    attached yet". Failing here, at boot, with the offending entry named, is the
+    only point where the mistake is visible.
+    """
+    if _ACTOR_ID_RE.match(entry):
+        return
+    lowered = entry.lower()
+    if _ACTOR_ID_RE.match(lowered):
+        # The one near-miss with a mechanical fix, so it gets its own message
+        # instead of being described. NOT lowered silently: ids are opaque, and
+        # quietly rewriting one makes a config stop meaning what it says.
+        hint = f" — actor ids are lower-case; did you mean {lowered!r}?"
+    else:
+        # LENGTH FIRST. Both problems are reported when both are present, but a
+        # short name is a length problem before it is an alphabet one: telling
+        # someone their 8-character username "contains 'ADHMORTZ'" buries the
+        # useful observation under a rendering of its own character set.
+        problems = []
+        if len(entry) != ACTOR_ID_LENGTH:
+            problems.append(
+                f"it is {len(entry)} characters, not {ACTOR_ID_LENGTH}"
+            )
+        offending = "".join(sorted(set(entry) - _ACTOR_ID_ALPHABET))
+        if offending:
+            problems.append(
+                f"it contains {offending!r}, which no actor id does"
+            )
+        hint = " — " + " and ".join(problems)
+        if offending:
+            hint += "; that looks like a username or a display name"
+    raise ValueError(
+        f"bow_owners entry {entry!r} is not an Alissa actor id{hint}. Use the "
+        f"opaque id — the `ownerActorId` on the container's row in "
+        f"GET /v1/bodies-of-work, or `actorId` from GET /v1/ping — never a "
+        f"username or display name: names are renameable, so an ownership "
+        f"check against one is a spoof surface, and since no id on the wire "
+        f"ever equals a name it would fail as a silently empty feed rather "
+        f"than an error. Leave bow_owners unset to trust this token's own "
+        f"actor, which needs no id at all."
+    )
+
+
 def _env_bool(env_name: str, raw: str) -> bool:
     value = raw.strip().lower()
     if value in _ENV_TRUE:
@@ -352,13 +462,16 @@ class Config:
     bow_prefix: str = "autodev: "
 
     # WHOSE Bodies of Work may act as a release feed: the Alissa actor id(s)
-    # allowed to OWN a feed container. Fail-closed like `repos` — empty is
-    # REJECTED at build when `release_feed` is `bow` (see build's guard). The
-    # title tells the daemon which repo a container targets; it says nothing
-    # about who created it, and the daemon lists containers it merely
-    # collaborates on, which anyone in the tenant can arrange unilaterally.
-    # So provenance is an operator decision, made here. Ids are opaque and
+    # allowed to OWN a feed container. The title tells the daemon which repo a
+    # container targets; it says nothing about who created it, and the daemon
+    # lists containers it merely collaborates on, which anyone in the tenant can
+    # arrange unilaterally. So provenance is decided here. Ids are opaque and
     # compared EXACTLY (unlike `repos`, which casefolds GitHub names).
+    #
+    # Empty means "not overridden", NOT "trust everyone": the boot path resolves
+    # it to this token's own actor and dies if it cannot (O8), and until it does
+    # an empty list matches no owner at all. An explicit list is the
+    # multi-operator case — containers owned by an actor this token is not.
     bow_owners: tuple[str, ...] = ()
 
     # The `bow`-feed safety net: every this-many seconds, ALSO run the full
@@ -400,6 +513,13 @@ class Config:
         payload does not state cannot be attributed, and an unattributable feed
         is exactly what `bow_owners` exists to refuse. Exact comparison — Alissa
         actor ids are opaque, so normalising them would only widen the match.
+
+        Fail-closed on an EMPTY authority as well, which is what makes the O8
+        default safe to resolve outside this class: before boot fills the list
+        in (or when something skipped that step), every owner is untrusted and
+        nothing is a feed. The failure mode of a missing authority is therefore
+        an inert daemon, never an open one — boot's job is only to make that
+        state loud instead of quiet.
         """
         return bool(actor_id) and actor_id in self.bow_owners
 
@@ -501,25 +621,15 @@ class Config:
                 "turn every Body of Work into a release feed"
             )
 
-        bow_owners = _string_list(raw.get("bow_owners", cls.bow_owners), "bow_owners")
-        if release_feed == FEED_BOW and not bow_owners:
-            # Fail-closed, the `repos` guard's twin. `repos` bounds WHERE the
-            # orchestrator writes; this bounds WHOSE work drives it. The feed
-            # lists Bodies of Work the daemon merely collaborates on, and being
-            # made a collaborator takes no acceptance step on this side, so
-            # without an owner allowlist "shared with the daemon and titled for
-            # a watched repo" is enough to get a task rendered into an issue in
-            # that repo and handed to the develop pipeline. Only fatal for the
-            # `bow` feed: `scan` never reads a Body of Work at all.
-            raise ValueError(
-                "bow_owners is empty and release_feed is 'bow' — the release "
-                "feed is fail-closed and refuses to start without the actor "
-                "id(s) allowed to own a feed Body of Work (being shared one is "
-                "not a claim to drive this daemon). Set `bow_owners` in the "
-                "config file, pass one or more --bow-owner flags, or set "
-                "ALISSA_ORC_BOW_OWNERS. An actor id is the `ownerActorId` on "
-                "the container's row in GET /v1/bodies-of-work."
-            )
+        # Shape-validated in EVERY feed mode, not just `bow`. The value is inert
+        # under `scan`, but a malformed id that boots quietly today is a daemon
+        # that refuses to start on the unrelated day the operator flips the feed
+        # over — and this is the layer that knows the entry came from a human.
+        # Empty stays legal: the boot path resolves the authority to this
+        # token's own actor (O8), so `bow_owners` is an override, not setup.
+        bow_owners = normalize_bow_owners(
+            _string_list(raw.get("bow_owners", cls.bow_owners), "bow_owners")
+        )
 
         fallback = int(raw.get("scan_fallback_interval", cls.scan_fallback_interval))
         if fallback < 0:

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

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