From 12640b39b2048af088767e819dbaaa2bb6e53dee Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 11:28:20 +1200
Subject: [PATCH 01/19] feat: move the ai-failure-notifier script here from
 operator

The script is 1,461 lines and its tests another 1,231, and canonical/operator
is only the first repository meant to run it. Copying that into each adopting
repo means fixing every bug as many times as there are repos, so it moves here
and each repo keeps only the workflow YAML that differs.

Both files are verbatim from canonical/operator#2663 at f15bcf1e, with exactly
one line changed: the test's `import ai_failure_notifier as afn` becomes
`from charm_tech_code import ai_failure_notifier as afn`. Nothing else in
either file is touched, so the 70 tests passing here are the same 70 assertions
that passed there. Splitting the script into modules is the next commit, kept
separate so this one stays a move and that one stays a refactor.

The package has no runtime dependencies, which is what makes `uvx --from git+`
viable as the distribution mechanism with no release process to run.
---
 .gitignore                                 |    4 +
 README.md                                  |   40 +
 pyproject.toml                             |   38 +
 src/charm_tech_code/__init__.py            |   20 +
 src/charm_tech_code/ai_failure_notifier.py | 1461 ++++++++++++++++++++
 tests/test_ai_failure_notifier.py          | 1231 +++++++++++++++++
 6 files changed, 2794 insertions(+)
 create mode 100644 README.md
 create mode 100644 pyproject.toml
 create mode 100644 src/charm_tech_code/__init__.py
 create mode 100644 src/charm_tech_code/ai_failure_notifier.py
 create mode 100644 tests/test_ai_failure_notifier.py

diff --git a/.gitignore b/.gitignore
index 83972fa..2657f32 100644
--- a/.gitignore
+++ b/.gitignore
@@ -216,3 +216,7 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# uv
+.venv/
+uv.lock
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b01672
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# charm-tech-code
+
+Shared tooling for the Charm Tech repositories (`operator`, `charmlibs`,
+`jubilant`, `pebble`, `concierge`, and the rest of the estate).
+
+Code here is consumed by workflow YAML in the repository that runs it, pinned
+by commit SHA:
+
+```yaml
+run: uvx --from git+https://github.com/canonical/charm-tech-code@<40-char-sha> ai-failure-notifier
+```
+
+The point is that the code lives in one place. A tool used by eleven
+repositories should be fixed once, not eleven times, and the workflow YAML
+that differs per repository stays in that repository.
+
+There is no release process and nothing is published. The SHA in the `uvx`
+line is the version, which is the same trust decision every pinned
+`uses: actions/checkout@<sha>` line in those repositories already makes.
+
+## Tools
+
+### `ai-failure-notifier`
+
+Enriches the placeholder issue that a scheduled workflow's failure notifier
+opens. It reads the failing run's job logs, builds a deterministic failure
+signature, searches for issues that look like the same failure, and either
+comments on one or rewrites the placeholder with a real title, body and
+labels. Without an API key it falls back to a plain notification, so the
+notifier's "always works" property is not affected by this being unavailable.
+
+See `canonical/operator`'s `.github/workflows/ai-failure-enrich.yaml` for the
+calling side.
+
+## Developing
+
+```shell
+uv sync
+uv run pytest
+```
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..e74050a
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,38 @@
+[project]
+name = "charm-tech-code"
+version = "0.1.0"
+description = "Shared tooling for the Charm Tech repositories."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+ai-failure-notifier = "charm_tech_code.ai_failure_notifier:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/charm_tech_code"]
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 99
+src = ["src", "tests"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
diff --git a/src/charm_tech_code/__init__.py b/src/charm_tech_code/__init__.py
new file mode 100644
index 0000000..9e42e0c
--- /dev/null
+++ b/src/charm_tech_code/__init__.py
@@ -0,0 +1,20 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared tooling for the Charm Tech repositories.
+
+Each tool here is consumed by workflow YAML in the repo that uses it, pinned
+by commit SHA, so that the code lives in one place rather than being copied
+into every repository that runs it.
+"""
diff --git a/src/charm_tech_code/ai_failure_notifier.py b/src/charm_tech_code/ai_failure_notifier.py
new file mode 100644
index 0000000..18761af
--- /dev/null
+++ b/src/charm_tech_code/ai_failure_notifier.py
@@ -0,0 +1,1461 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""ai-failure-notifications enrichment step.
+
+Invoked by `.github/workflows/ai-failure-enrich.yaml` after
+`.github/workflows/notify-scheduled-failure.yaml` (the notifier) has already
+created or commented on a placeholder issue for a failed scheduled workflow
+run. This script:
+
+1. Finds the placeholder the notifier just touched (or, on a same-run
+   re-fire, the issue an earlier run of this script already enriched).
+2. Fetches and parses the failing job logs into a deterministic failure
+   signature.
+3. Builds a small candidate-issue pool (coarse title/body search).
+4. Asks an LLM (via OpenRouter) to decide comment-vs-new and draft the text,
+   validates the response against the envelope schema, and applies it via
+   `gh`.
+5. Falls back to a plain, generic issue/comment (still marker-stamped) if
+   OpenRouter is unreachable, misconfigured, or returns invalid JSON.
+
+The functions above the `--- I/O ---` marker are pure and unit-tested in
+`scripts/test/test_ai_failure_notifier.py`. Everything below it talks to `gh`
+or OpenRouter and is exercised only by mocking in tests.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+from typing import Any, Literal
+
+MARKER_PREFIX = 'ai-failure-notifications'
+DEFAULT_MODEL = 'deepseek/deepseek-chat'  # DeepSeek V3 on OpenRouter.
+CLOSED_CANDIDATE_WINDOW_DAYS = 14
+MAX_CANDIDATES = 3
+# How many recently-updated issues to scan for the notifier's marker. The
+# artefact we are looking for was touched minutes ago, so this only has to
+# cover issue churn in that window; 50 is far more than `operator` sees.
+RECENT_ISSUE_SCAN = 50
+
+# Colour escapes, which Actions logs are full of. Two alternatives, because
+# the logs contain both the real thing and a mangled form where the ESC byte
+# has already been stripped, leaving a bare "[32m".
+ANSI = re.compile(
+    r"""
+    \x1b\[ [0-9;]* [A-Za-z]   # a full escape: ESC [ params letter
+    |
+    \[ \d+ (?:;\d+)* m        # ESC already stripped: [32m, [1;33m
+    """,
+    re.VERBOSE,
+)
+
+# The timestamp Actions prefixes to every log line, for example
+# "2026-07-21T16:17:04.8204062Z ". Stripped before anything else is matched.
+TS = re.compile(
+    r"""
+    ^\d{4}-\d{2}-\d{2}        # date: 2026-07-21
+    T\d{2}:\d{2}:\d{2}        # time: T16:17:04
+    \.\d+Z[ ]                 # fractional seconds, zone, one trailing space
+    """,
+    re.VERBOSE,
+)
+
+# Actions' own annotation for a failing step.
+ERROR_MARKER = re.compile(r'##\[error\]')
+
+# The runner opens every step with "##[group]Run <script>", echoes the whole
+# `run:` block a line at a time, dumps the step's env, and closes with
+# "##[endgroup]". None of that is output: it is the step's own source. A
+# multi-line `run:` therefore puts its every branch into the log, including
+# the ones that did not execute, and parsing it produces failures the run
+# never had.
+#
+# Colour is not a usable signal here -- the runner marks echoed lines cyan-
+# bold, but ANSI above strips that before anything is matched -- so the
+# group boundary is what separates a step's script from its output.
+GROUP_RUN_START = re.compile(r'^##\[group\]Run ')
+GROUP_END = re.compile(r'^##\[endgroup\]')
+
+# A line from pytest's short summary, for example
+# "FAILED tests/integration/test_charm.py::test_deploy - TimeoutError: ...".
+PYTEST_SUMMARY = re.compile(
+    r"""
+    ^(FAILED|ERROR)[ ]         # which of the two pytest reports
+    (\S+?)[ ]-[ ]              # the test id, up to the " - " separator
+    (.+)$                      # the error message, to end of line
+    """,
+    re.VERBOSE,
+)
+
+# The end of pytest's summary section, for example
+# "======== 3 failed, 41 passed, 2 warnings in 512.44s ========".
+PYTEST_SUMMARY_END = re.compile(
+    r"""
+    ={3,}                      # the run of = that brackets the line
+    .*(failed|passed|error)    # and one of pytest's outcome words
+    """,
+    re.VERBOSE,
+)
+
+# A failing Go test, for example "--- FAIL: TestFoo (0.01s)".
+GO_FAIL = re.compile(r'^--- FAIL: (\S+)')
+
+# The last line of a Python traceback: the exception type and its message,
+# for example "KeyError: 'loki/0'". Deliberately narrow -- it must look like an
+# exception class name -- so that arbitrary "word: text" log lines don't match.
+TRACEBACK_END = re.compile(
+    r"""
+    ^([A-Z]                          # exception types start with a capital
+      [A-Za-z_.]*                    # dotted path allowed: ops.pebble.APIError
+      (?:Error|Exception|Warning))   # and conventionally end one of three ways
+    :[ ](.*)$                        # then ": " and the message
+    """,
+    re.VERBOSE,
+)
+
+# Matches markers stamped by either workflow:
+#   notifier:  <!-- ai-failure-notifications:run=123:origin=new -->
+#              <!-- ai-failure-notifications:run=123:origin=comment -->
+#   enricher:  <!-- ai-failure-notifications:run=123:sig=abcdef0123456789 -->
+MARKER_RE = re.compile(
+    r'<!--\s*'
+    + re.escape(MARKER_PREFIX)
+    + r"""
+    :run=(?P<run_id>\d+)
+    (?::origin=(?P<origin>new|comment))?
+    (?::sig=(?P<sig>[0-9a-f]+))?
+    \s*-->
+    """,
+    re.VERBOSE,
+)
+
+
+# --- Structured shapes ---
+#
+# The signature is built here, serialised into the prompt, and hashed for the
+# marker, so its shape is worth pinning down rather than passing dicts around.
+# `dataclasses.asdict` preserves field declaration order, which is what the
+# prompt's JSON ends up in.
+
+
+@dataclasses.dataclass(frozen=True)
+class PytestFailure:
+    """One line of pytest's short summary."""
+
+    kind: str  # "FAILED" or "ERROR" -- pytest reports both here.
+    test: str
+    error: str
+
+
+@dataclasses.dataclass(frozen=True)
+class JobSignature:
+    """What the deterministic parser could extract from one failed job's log."""
+
+    job_id: int
+    job_name: str
+    failed_step: str | None
+    pytest_failures: list[PytestFailure]
+    go_failures: list[str]
+    traceback_top_error: str | None
+    tail_excerpt: list[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class RunSignature:
+    """Every failed job of one run, plus the run's own identifying fields."""
+
+    run_id: str
+    workflow_name: str
+    html_url: str
+    created_at: str
+    jobs: list[JobSignature]
+
+    def as_json(self) -> str:
+        """Render for the prompt, in field declaration order."""
+        return json.dumps(dataclasses.asdict(self), indent=2)
+
+
+@dataclasses.dataclass(frozen=True)
+class FailedJob:
+    """A failed job as listed by `gh run view`, before its log is fetched."""
+
+    id: int
+    name: str
+    failed_step: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class CandidateIssue:
+    """An existing issue that might already track this failure."""
+
+    number: int
+    title: str
+    body: str | None
+    closed_at: str | None
+
+    @classmethod
+    def from_gh(cls, data: dict[str, Any]) -> CandidateIssue:
+        """Build from one element of `gh issue list --json ...` output."""
+        return cls(
+            number=data['number'],
+            title=data['title'],
+            body=data.get('body'),
+            closed_at=data.get('closedAt'),
+        )
+
+    def excerpt(self) -> str:
+        """The first line of the body, bounded, for the candidate block."""
+        lines = (self.body or '').strip().splitlines()
+        return lines[0][:300] if lines else '(no body)'
+
+
+# --- Signature extraction ---
+
+
+def strip_line(line: str) -> str:
+    """Remove GHA timestamp and ANSI colours."""
+    line = TS.sub('', line, count=1)
+    line = ANSI.sub('', line)
+    return line.rstrip('\r\n')
+
+
+def strip_log(text: str) -> list[str]:
+    """Split a raw job log into output lines, dropping each step's own script.
+
+    Everything between "##[group]Run ..." and "##[endgroup]" is the runner
+    echoing the step's `run:` block and env, not anything the step printed.
+    See GROUP_RUN_START above for why that matters.
+    """
+    lines: list[str] = []
+    in_step_header = False
+    for raw in text.splitlines():
+        line = strip_line(raw)
+        if GROUP_RUN_START.match(line):
+            in_step_header = True
+            continue
+        if in_step_header:
+            in_step_header = not GROUP_END.match(line)
+            continue
+        lines.append(line)
+    return lines
+
+
+def parse_job_log(
+    text: str,
+) -> tuple[list[PytestFailure], list[str], str | None, list[str]]:
+    """Parse one job's raw log text.
+
+    Returns (pytest_failures, go_failures, traceback_top_error, tail_excerpt).
+    """
+    lines = strip_log(text)
+
+    pytest_failures: list[PytestFailure] = []
+    go_failures: list[str] = []
+    in_summary = False
+
+    for line in lines:
+        if 'short test summary info' in line:
+            in_summary = True
+            continue
+        if in_summary:
+            m = PYTEST_SUMMARY.match(line)
+            if m:
+                kind, test, err = m.groups()
+                pytest_failures.append(PytestFailure(kind, test, err.strip()))
+                continue
+            if PYTEST_SUMMARY_END.match(line):
+                in_summary = False
+        m = GO_FAIL.match(line)
+        if m:
+            go_failures.append(m.group(1))
+
+    traceback_top_error: str | None = None
+    for line in reversed(lines):
+        m = TRACEBACK_END.match(line)
+        if m:
+            traceback_top_error = f'{m.group(1)}: {m.group(2).strip()}'
+            break
+
+    error_idx = None
+    for i, line in enumerate(lines):
+        if ERROR_MARKER.search(line):
+            error_idx = i
+            break
+    tail: list[str] = []
+    if error_idx is not None:
+        for line in reversed(lines[:error_idx]):
+            if not line.strip():
+                continue
+            if line.startswith('##[group]') or line.startswith('##[endgroup]'):
+                continue
+            tail.append(line)
+            if len(tail) >= 40:
+                break
+        tail.reverse()
+
+    return pytest_failures, go_failures, traceback_top_error, tail
+
+
+def build_job_signature(
+    job_id: int, job_name: str, failed_step: str | None, log_text: str
+) -> JobSignature:
+    """Parse one job's log into its signature."""
+    pytest_failures, go_failures, traceback_top_error, tail = parse_job_log(log_text)
+    return JobSignature(
+        job_id=job_id,
+        job_name=job_name,
+        failed_step=failed_step,
+        pytest_failures=pytest_failures,
+        go_failures=go_failures,
+        traceback_top_error=traceback_top_error,
+        tail_excerpt=tail,
+    )
+
+
+def build_run_signature(
+    run_id: str, workflow_name: str, html_url: str, created_at: str, jobs: list[JobSignature]
+) -> RunSignature:
+    """Combine per-job signatures into the full run signature."""
+    return RunSignature(
+        run_id=str(run_id),
+        workflow_name=workflow_name,
+        html_url=html_url,
+        created_at=created_at,
+        jobs=jobs,
+    )
+
+
+# --- Marker + signature hashing ---
+
+
+def signature_hash(signature: RunSignature) -> str:
+    """Deterministic short fingerprint of a run signature.
+
+    Used only for the marker's :sig= suffix (not for dedup decisions --
+    that's the LLM's job, guided by the candidate pool).
+    """
+    parts: list[str] = []
+    for job in signature.jobs:
+        parts.extend(failure.test for failure in job.pytest_failures)
+        parts.extend(job.go_failures)
+        if job.traceback_top_error:
+            parts.append(job.traceback_top_error)
+        if job.failed_step:
+            parts.append(job.failed_step)
+    canonical = '\n'.join(sorted(parts)) or signature.workflow_name
+    return hashlib.sha1(canonical.encode('utf-8'), usedforsecurity=False).hexdigest()[:16]
+
+
+# Which artefact the notifier touched: a fresh placeholder issue, or a comment
+# on an issue that already existed. A Literal so a type checker rejects a bad
+# value before it reaches a marker.
+Origin = Literal['new', 'comment']
+
+
+def render_notifier_marker(run_id: str, origin: Origin) -> str:
+    """Render the marker the notifier stamps, telling the enricher what it touched."""
+    return f'<!-- {MARKER_PREFIX}:run={run_id}:origin={origin} -->'
+
+
+def render_enriched_marker(run_id: str, signature: RunSignature) -> str:
+    """Render the marker this script stamps once it has fully processed a run.
+
+    Presence of :sig= is what makes rung zero (find_run_markers) treat a later
+    same-run-id trigger as "already enriched, just note the re-run".
+    """
+    return f'<!-- {MARKER_PREFIX}:run={run_id}:sig={signature_hash(signature)} -->'
+
+
+def find_run_markers(
+    texts: list[tuple[int, str]], run_id: str
+) -> tuple[int | None, str | None, int | None]:
+    """Scan (issue_number, text) pairs for markers belonging to `run_id`.
+
+    Returns (enriched_issue, origin_kind, origin_issue):
+    - enriched_issue: an issue number carrying a :sig= marker for this run
+      (rung zero -- this run was already fully enriched once), else None.
+    - origin_kind / origin_issue: the "new"/"comment" marker the notifier
+      stamped for this run (identifies which artefact to upgrade), else
+      (None, None).
+    """
+    run_id = str(run_id)
+    enriched_issue = None
+    origin_kind = None
+    origin_issue = None
+    for number, text in texts:
+        if not text:
+            continue
+        for match in MARKER_RE.finditer(text):
+            if match['run_id'] != run_id:
+                continue
+            if match['sig']:
+                enriched_issue = number
+            elif match['origin']:
+                origin_kind = match['origin']
+                origin_issue = number
+    return enriched_issue, origin_kind, origin_issue
+
+
+# --- Candidate pool ---
+
+
+def within_window(iso_timestamp: str, now: datetime.datetime, days: int) -> bool:
+    """Return whether `iso_timestamp` falls within `days` of `now`."""
+    ts = datetime.datetime.fromisoformat(iso_timestamp.replace('Z', '+00:00'))
+    return now - ts <= datetime.timedelta(days=days)
+
+
+def build_candidates_block(
+    open_issues: list[CandidateIssue],
+    closed_issues: list[CandidateIssue],
+    now: datetime.datetime,
+) -> str:
+    """Render the {{CANDIDATES_BLOCK}} the prompt expects.
+
+    Up to MAX_CANDIDATES entries: open issues first, then recently-closed
+    issues (<=14 days) filling any remaining slots, explicitly labelled as
+    closed so the LLM never auto-treats one as a strong match. Calibration on
+    past scheduled failures found a closed issue can corroborate a match but
+    should never be enough to dedupe against on its own.
+    """
+    entries: list[str] = []
+    for issue in open_issues:
+        if len(entries) >= MAX_CANDIDATES:
+            break
+        entries.append(f'- **#{issue.number} — {issue.title}** (open)\n  > {issue.excerpt()}')
+
+    recent_closed = [
+        i
+        for i in closed_issues
+        if i.closed_at and within_window(i.closed_at, now, CLOSED_CANDIDATE_WINDOW_DAYS)
+    ]
+    for issue in recent_closed:
+        if len(entries) >= MAX_CANDIDATES:
+            break
+        entries.append(
+            f'- **#{issue.number} — {issue.title}** (closed {issue.closed_at} -- '
+            f'recently closed; treat as at most a medium-confidence match)\n  > {issue.excerpt()}'
+        )
+
+    if not entries:
+        return '(no open issues found for this workflow)'
+    return '\n'.join(entries)
+
+
+# --- Prompt building ---
+
+SYSTEM_PROMPT = """\
+You are the enrichment step of an internal CI failure-triage bot for the
+Canonical Charm Tech team. A scheduled GitHub Actions workflow just failed.
+A separate deterministic parser has already extracted a structured failure
+signature from the run's logs -- you do not have repository access, log
+access, or internet access beyond what is given to you in this message.
+Work only from the signature JSON and candidate issues you're given.
+
+Your job: decide whether this failure is a new occurrence of an
+already-tracked problem (comment on the existing issue) or something not
+currently tracked (open a new issue), and draft the text for whichever
+artefact you choose. Output ONLY the JSON envelope described below -- no
+prose before or after it, no markdown code fences around it.
+
+You are reporting, not fixing. Never propose a fix, a patch, a diff, a
+workaround, a configuration change, a retry, a next step, or anything else
+that tells a reader what to do about the failure -- not as a section, not
+as a sentence, not as an aside, however confident you are and however
+obvious it looks. Deciding what to do about a failure is someone else's
+job, and a wrong suggestion from you is worse than none, because it
+anchors whoever picks the issue up. Describe what failed and, where the
+signature genuinely supports it, why. Then stop.
+
+## Reading the signature
+
+The signature has one entry per failed job in `jobs[]`. Each entry may
+carry, in decreasing order of how much you should trust it:
+
+1. `pytest_failures[]` -- `{kind, test, error}` triples parsed from
+   pytest's "short test summary info" block. `test` is a real pytest node
+   id; `error` is the tail of that summary line and CAN BE TRUNCATED by
+   pytest itself (it cuts long messages short, for example
+   "PendingDeprecat..."). If an `error` string ends in `...`, treat it
+   as unreliable for anything beyond "this test failed" -- do not quote it
+   as the root cause, do not put the truncated fragment in a title. Look
+   at `traceback_top_error` and `tail_excerpt` for that job instead; if
+   they don't resolve it either, describe the failure by test name only
+   and say the specific assertion text is unavailable.
+2. `traceback_top_error` -- the last `<ErrorClass>: <message>` line found
+   anywhere in the job's log. Usually the real exception, but it is a
+   last-line heuristic: on jobs where cleanup code raises its own warning
+   after the real failure (a `ResourceWarning` from tempfile cleanup is
+   the known example), this field can point at the cleanup noise instead
+   of the actual cause. If `traceback_top_error` names a `Warning` class
+   while `pytest_failures[]` for the same job names an `Error` class,
+   trust the `pytest_failures[]` entry for what actually failed and treat
+   `traceback_top_error` as noise.
+3. `tail_excerpt[]` -- the last ~40 non-empty log lines before the job's
+   first `##[error]` marker. This is what's left when neither of the
+   above fired. Sometimes it contains an unambiguous plain-text failure
+   (for example a Go `panic:`, a shell command's final non-zero-exit message, an
+   infra tool's own `level=ERROR msg="..."` line) -- if so, use it. Other
+   times it shows the *shape* of a timeout or an in-progress hook without
+   ever stating what actually broke. Do not guess a specific root cause
+   from an inconclusive `tail_excerpt`. It is fine, and preferred, to say
+   plainly that the cause isn't visible in the available log excerpt.
+
+A job with no `pytest_failures`, no `traceback_top_error`, and a
+`tail_excerpt` that never names an exception, an error code, or an
+explicit failure message (only status-transition noise) is very likely an
+**infrastructural** failure (bootstrap, provisioning, network) rather than
+a test regression, PROVIDED the excerpt at least shows a concrete
+infra-level error. Say so explicitly -- title and body should make clear
+this is "infrastructure failing before tests could run" language, not
+"test X failed" language, and do not name a specific test as the culprit.
+
+If even that infra-level signal is missing or the excerpt is genuinely
+inconclusive, do not invent a specific-sounding title. Use a plain, honest
+title that names the workflow and says the cause is unclear from the log
+excerpt, set "confidence": "low", and say in `dedup_reason` what
+information would be needed to do better. Never fabricate a
+plausible-sounding cause to fill the gap.
+
+A run can have multiple failed jobs with different signatures. Handle this
+as follows:
+
+- If all failed jobs share essentially the same signature, treat it as one
+  failure and write one title/body for it, noting how many jobs it hit.
+- If failed jobs split into distinct signatures, decide whether one is
+  clearly the dominant, actionable story, with others being a smaller
+  number of already-familiar, separately-tracked issues riding along. If
+  so, make the dominant one the subject of `title`/`action`, and mention
+  the others in `body` as a secondary note plus in `dedup_reason`.
+- If failed jobs are multiple genuinely distinct, comparably-important
+  problems with no dominant one, use a title naming the workflow and the
+  count/spread of distinct causes and list each in `body` as its own
+  bullet. Don't pick one arbitrarily and bury the rest.
+
+## Handling multiple independent failures (`also`)
+
+When a run has a dominant story plus one or two secondary failures that
+have distinct signatures from the dominant one AND would either match a
+different existing tracked issue or themselves be dominant enough to
+warrant their own artefact if seen alone, emit an `also` array on the
+envelope with one entry per secondary. Each `also[i]` is a self-contained
+decision (its own `action`, its own `target_issue`/`title`, its own
+`confidence`, its own `dedup_reason`).
+
+Do not use `also` to split a single failure across two entries; do not
+nest `also` inside an `also` entry; cap: 2 `also` entries per envelope.
+
+## Body structure (for `action: "new"`)
+
+Use this shape, adapting to how many distinct failures you're describing:
+
+```
+## Summary
+<one or two sentences: what broke, at what scope>
+
+## Failures
+- **<job name>**: <headline error, or "infrastructure failure -- <what>",
+  or "cause unclear from the available log excerpt">
+  (omit this section entirely if there's exactly one failing job)
+
+## Likely root cause
+<ONLY include this section if the signature actually supports a specific
+hypothesis. Omit it entirely otherwise -- expected on roughly half the
+signatures you'll see. Describe the cause only; do not carry on into what
+should be done about it.>
+```
+
+Do not add sections beyond these. In particular there is no "suggested
+fix", "next steps", "workaround" or "recommendation" section, and none may
+be added.
+
+For `action: "comment"`, keep the comment short: what matches the existing
+issue (or what's new/different), and nothing else.
+
+## Deciding comment vs new
+
+You are given up to three candidate existing issues (title + excerpt), already
+pre-filtered to the same workflow by a coarser deterministic search. Some
+candidates may be marked "(closed ...)" -- these are recently-closed
+issues included for context only; never target a closed issue with
+`action: "comment"`, and never let a closed candidate alone justify
+`confidence: "high"`.
+
+- **Strong** -- at least one `pytest_failures[].test` (or, for
+  infra/tail-only failures, the same `failed_step` plus the same concrete
+  error text) matches an OPEN candidate, AND the top error class matches
+  too -> `action: "comment"`, `confidence: "high"`.
+- **Medium** -- same workflow and same `failed_step`, or same top error
+  class, but the specific test/error text has drifted, OR the only match
+  is a recently-closed candidate -> `action: "comment"` (target the open
+  issue only; if the only match is closed, use `action: "new"` instead and
+  mention the closed issue in `dedup_reason`), `confidence: "medium"`, and
+  say the drift explicitly in `body` and `dedup_reason`.
+- **Weak** -- only the workflow name matches, or only a vague thematic
+  overlap -- this is not a dedup match. `action: "new"`.
+
+Do not comment on a candidate just because one exists for the same
+workflow -- check whether the *signature* actually matches.
+
+## Labels and issue type
+
+The repository has a fixed, centrally-managed label set. You may only use
+labels from this list, and a label that does not exist in the repository is
+dropped before the issue is created, so inventing one achieves nothing:
+
+- `tests` -- the failure is in the tests or the test harness. This is the
+  common case for a failing integration or unit workflow.
+- `docs` -- the failure is in documentation building, linting or link
+  checking, or in a workflow that maintains a doc.
+- `performance` -- only where the failure *is* a performance result, such
+  as a benchmark regression or a timing threshold. Not for an ordinary
+  timeout, which is usually a hang or an infrastructure problem.
+- `small item` -- only where the signature makes it obvious the work is
+  trivial. Prefer omitting it: you cannot see the code, so you are usually
+  not in a position to judge size.
+
+An empty `labels` list is a perfectly good answer. Use it whenever none of
+the above clearly applies, rather than reaching for the nearest one.
+
+`issue_type` is "bug" when you're reasonably sure this is a defect. Use
+`null` when genuinely unsure -- this is normal and expected for
+low-confidence signatures, not an edge case.
+
+## Never
+
+- Never suggest a fix or a remedy of any kind. See "You are reporting, not
+  fixing" above; this is the constraint most easily broken by accident,
+  usually as a closing sentence offering a next step.
+- Never invent a root cause, a PR number, or a file/line that isn't
+  directly supported by the signature JSON you were given.
+- Never use a label that isn't in the list above.
+- Never output anything except the single JSON envelope object.
+"""
+
+USER_PROMPT_TEMPLATE = """\
+Workflow: {workflow_name}
+Run: {run_url}
+
+## Extracted failure signature (deterministic parser output, JSON)
+
+{signature_json}
+
+## Candidate existing open issues (same workflow, pre-filtered by title;
+## may include recently-closed issues explicitly marked as such; may be
+## empty)
+
+{candidates_block}
+
+Produce the JSON envelope now.
+"""
+
+
+def build_prompt(
+    workflow_name: str, run_url: str, signature: RunSignature, candidates_block: str
+) -> tuple[str, str]:
+    """Render the (system, user) prompt pair for the OpenRouter call."""
+    user = USER_PROMPT_TEMPLATE.format(
+        workflow_name=workflow_name,
+        run_url=run_url,
+        signature_json=signature.as_json(),
+        candidates_block=candidates_block,
+    )
+    return SYSTEM_PROMPT, user
+
+
+# --- Envelope schema validation (hand-rolled -- deliberately not the
+# `jsonschema` package, so the script keeps needing nothing outside the stdlib.
+# Mirrors ENVELOPE_JSON_SCHEMA below, which is what OpenRouter is asked to
+# conform to; this re-checks it on the applier side.) ---
+
+_ENTRY_COMMON_REQUIRED = ('action', 'body', 'dedup_reason', 'confidence')
+_ENTRY_KNOWN_KEYS = {
+    'action',
+    'body',
+    'dedup_reason',
+    'confidence',
+    'title',
+    'labels',
+    'issue_type',
+    'target_issue',
+}
+
+
+def validate_entry(entry: Any, *, path: str, allow_also: bool = False) -> list[str]:
+    """Validate one envelope entry (top-level or an `also[i]`) against the schema.
+
+    `also` is only legal on the top-level envelope, so the caller says whether
+    this is that. Without it the top-level check rejected every envelope that
+    carried `also` -- which the model emits routinely, since the schema it is
+    given declares the field.
+    """
+    errors: list[str] = []
+    if not isinstance(entry, dict):
+        return [f'{path}: expected an object, got {type(entry).__name__}']
+
+    for field in _ENTRY_COMMON_REQUIRED:
+        if field not in entry:
+            errors.append(f"{path}: missing required field '{field}'")
+
+    known = _ENTRY_KNOWN_KEYS | {'also'} if allow_also else _ENTRY_KNOWN_KEYS
+    unknown = set(entry) - known
+    if unknown:
+        errors.append(f'{path}: unknown field(s) {sorted(unknown)}')
+
+    action = entry.get('action')
+    if action not in ('comment', 'new'):
+        errors.append(f"{path}.action: must be 'comment' or 'new', got {action!r}")
+        return errors  # can't check action-conditional fields without a valid action
+
+    if not isinstance(entry.get('body'), str) or not entry.get('body'):
+        errors.append(f'{path}.body: must be a non-empty string')
+    if not isinstance(entry.get('dedup_reason'), str) or not entry.get('dedup_reason'):
+        errors.append(f'{path}.dedup_reason: must be a non-empty string')
+    if entry.get('confidence') not in ('high', 'medium', 'low'):
+        errors.append(
+            f'{path}.confidence: must be one of high/medium/low, got {entry.get("confidence")!r}'
+        )
+
+    # A field present but null counts as absent. The schema sent to OpenRouter
+    # is `strict`, so models routinely return every declared property and use
+    # null for the ones that do not apply to the action they chose; rejecting on
+    # mere presence threw away otherwise good output.
+    if action == 'new':
+        for field in ('title', 'labels', 'issue_type'):
+            if field not in entry:
+                errors.append(f"{path}: action='new' requires '{field}'")
+        if entry.get('target_issue') is not None:
+            errors.append(f"{path}: action='new' must not include 'target_issue'")
+        labels = entry.get('labels')
+        if labels is not None and (
+            not isinstance(labels, list) or not all(isinstance(x, str) for x in labels)
+        ):
+            errors.append(f'{path}.labels: must be an array of strings')
+        if 'issue_type' in entry and not (
+            entry['issue_type'] is None or isinstance(entry['issue_type'], str)
+        ):
+            errors.append(f'{path}.issue_type: must be a string or null')
+    else:  # comment
+        if 'target_issue' not in entry:
+            errors.append(f"{path}: action='comment' requires 'target_issue'")
+        elif not isinstance(entry['target_issue'], int) or entry['target_issue'] < 1:
+            errors.append(f'{path}.target_issue: must be a positive integer')
+        for field in ('title', 'labels', 'issue_type'):
+            if entry.get(field) is not None:
+                errors.append(f"{path}: action='comment' must not include '{field}'")
+
+    return errors
+
+
+# Fields that only mean something for one of the two actions. The model is
+# given a `strict` schema, so it tends to return every declared property and
+# fill in the ones that do not apply to the action it chose. Those are dropped
+# rather than treated as an error: we would not act on them either way, and
+# rejecting the envelope threw away a usable body and fell back to the plain
+# notice.
+_ACTION_ONLY_FIELDS = {
+    'comment': ('title', 'labels', 'issue_type'),
+    'new': ('target_issue',),
+}
+
+
+def drop_inapplicable_fields(entry: Any) -> tuple[Any, list[str]]:
+    """Strip fields that do not apply to `entry`'s action; report what went."""
+    if not isinstance(entry, dict):
+        return entry, []
+    fields = _ACTION_ONLY_FIELDS.get(entry.get('action'))
+    if not fields:
+        return entry, []
+    dropped = [f for f in fields if f in entry]
+    if not dropped:
+        return entry, []
+    return {k: v for k, v in entry.items() if k not in dropped}, dropped
+
+
+def normalise_envelope(envelope: Any) -> tuple[Any, list[str]]:
+    """Drop inapplicable fields from the envelope and each `also` entry."""
+    if not isinstance(envelope, dict):
+        return envelope, []
+    cleaned, dropped = drop_inapplicable_fields(envelope)
+    notes = [f'envelope: {f}' for f in dropped]
+    also = cleaned.get('also')
+    if isinstance(also, list):
+        entries: list[Any] = []
+        for i, entry in enumerate(also):
+            entry, entry_dropped = drop_inapplicable_fields(entry)
+            notes += [f'envelope.also[{i}]: {f}' for f in entry_dropped]
+            entries.append(entry)
+        cleaned = {**cleaned, 'also': entries}
+    return cleaned, notes
+
+
+def validate_envelope(envelope: Any) -> list[str]:
+    """Validate a top-level envelope (may carry `also`).
+
+    Returns a list of human-readable errors; empty list means valid.
+    """
+    if not isinstance(envelope, dict):
+        return ['envelope: expected a JSON object']
+
+    errors = validate_entry(envelope, path='envelope', allow_also=True)
+
+    also = envelope.get('also')
+    if also is not None:
+        if not isinstance(also, list) or len(also) > 2:
+            errors.append('envelope.also: must be an array of at most two entries')
+        else:
+            for i, entry in enumerate(also):
+                if isinstance(entry, dict) and 'also' in entry:
+                    errors.append(f"envelope.also[{i}]: nested 'also' is not allowed")
+                errors.extend(validate_entry(entry, path=f'envelope.also[{i}]'))
+
+    return errors
+
+
+ENVELOPE_JSON_SCHEMA = {
+    '$schema': 'https://json-schema.org/draft/2020-12/schema',
+    'title': 'ai-failure-notifications envelope',
+    'type': 'object',
+    'required': ['action', 'body', 'dedup_reason', 'confidence'],
+    'properties': {
+        'action': {'enum': ['comment', 'new']},
+        'body': {'type': 'string', 'minLength': 1},
+        'dedup_reason': {'type': 'string', 'minLength': 1},
+        'confidence': {'enum': ['high', 'medium', 'low']},
+        'title': {'type': 'string', 'minLength': 1},
+        'labels': {'type': 'array', 'items': {'type': 'string'}},
+        'issue_type': {'type': ['string', 'null']},
+        'target_issue': {'type': 'integer', 'minimum': 1},
+        'also': {'type': 'array', 'maxItems': 2, 'items': {'$ref': '#/$defs/envelopeEntry'}},
+    },
+    'additionalProperties': False,
+    'allOf': [{'$ref': '#/$defs/actionConditionals'}],
+    '$defs': {
+        'actionConditionals': {
+            'allOf': [
+                {
+                    'if': {'properties': {'action': {'const': 'new'}}},
+                    'then': {
+                        'required': ['title', 'labels', 'issue_type'],
+                        'not': {'required': ['target_issue']},
+                        'properties': {'labels': {'type': 'array', 'items': {'type': 'string'}}},
+                    },
+                },
+                {
+                    'if': {'properties': {'action': {'const': 'comment'}}},
+                    'then': {
+                        'required': ['target_issue'],
+                        'not': {
+                            'anyOf': [
+                                {'required': ['title']},
+                                {'required': ['labels']},
+                                {'required': ['issue_type']},
+                            ]
+                        },
+                    },
+                },
+            ]
+        },
+        'envelopeEntry': {
+            'type': 'object',
+            'required': ['action', 'body', 'dedup_reason', 'confidence'],
+            'properties': {
+                'action': {'enum': ['comment', 'new']},
+                'body': {'type': 'string', 'minLength': 1},
+                'dedup_reason': {'type': 'string', 'minLength': 1},
+                'confidence': {'enum': ['high', 'medium', 'low']},
+                'title': {'type': 'string', 'minLength': 1},
+                'labels': {'type': 'array', 'items': {'type': 'string'}},
+                'issue_type': {'type': ['string', 'null']},
+                'target_issue': {'type': 'integer', 'minimum': 1},
+            },
+            'additionalProperties': False,
+            'allOf': [{'$ref': '#/$defs/actionConditionals'}],
+        },
+    },
+}
+
+
+# --- I/O ---
+
+
+def gh(*args: str, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a `gh` subcommand, returning the completed process."""
+    # S607: `gh` is deliberately called by name, resolved from the runner's PATH.
+    return subprocess.run(['gh', *args], text=True, capture_output=True, check=check)  # noqa: S607
+
+
+def gh_json(*args: str) -> Any:
+    """Run a `gh ... --json ...` subcommand and parse its stdout as JSON."""
+    result = gh(*args)
+    return json.loads(result.stdout) if result.stdout.strip() else None
+
+
+def fetch_failed_jobs(repo: str, run_id: str) -> list[FailedJob]:
+    """List the failed jobs of a run, each with its id, name, and failed step."""
+    data = gh_json('run', 'view', str(run_id), '--repo', repo, '--json', 'jobs') or {}
+    failed: list[FailedJob] = []
+    for job in data.get('jobs', []):
+        if job.get('conclusion') != 'failure':
+            continue
+        failed_step = None
+        for step in job.get('steps') or []:
+            if step.get('conclusion') == 'failure':
+                failed_step = step.get('name')
+                break
+        failed.append(FailedJob(id=job['databaseId'], name=job['name'], failed_step=failed_step))
+    return failed
+
+
+def fetch_job_log(repo: str, run_id: str, job_id: int) -> str:
+    """Fetch one job's full log text.
+
+    Uses the REST logs endpoint rather than `gh run view --log`: the latter
+    exits 0 with empty stdout on some `gh` builds (reproduced on 2.45.0), which
+    silently degrades the extracted signature to nothing. An empty log here is
+    reported rather than swallowed.
+
+    `--allow-escape-sequences` is not optional. From gh 2.9x, `gh api` refuses
+    to write a response containing terminal escapes -- "the response contains
+    terminal escape sequences; pass --allow-escape-sequences to output it
+    anyway" -- and returns nothing at all. Actions logs are full of them; ANSI
+    above exists to strip them. Runners carry a gh new enough to refuse (2.97.0
+    when this was measured, in fork run 32673538357), so without the flag every
+    fetch comes back empty and the signature degrades to the job name.
+
+    Older builds have no such check and no such flag, and reject it as unknown
+    rather than ignoring it, so those retry without.
+    """
+    endpoint = f'repos/{repo}/actions/jobs/{job_id}/logs'
+    result = gh('api', endpoint, '--allow-escape-sequences', check=False)
+    if 'unknown flag' in (result.stderr or ''):
+        result = gh('api', endpoint, check=False)
+    if not result.stdout.strip():
+        # `gh` puts the status on stderr ("gh: Not Found (HTTP 404)"), and the
+        # exit code alone is 1 for all of them. Without the status there is no
+        # telling a log that is not ready yet from a token that has lost
+        # `actions: read`, and the two want opposite fixes.
+        detail = ' '.join((result.stderr or '').split())[:200] or 'no stderr'
+        write_step_summary(
+            f'Warning: no log text for job {job_id} of run {run_id} '
+            f'(gh exit {result.returncode}: {detail}); '
+            f'signature will be based on the job name alone.'
+        )
+    return result.stdout
+
+
+def fetch_run_meta(repo: str, run_id: str) -> dict[str, str]:
+    """Fetch a run's display metadata (title, workflow name, url, createdAt)."""
+    return (
+        gh_json(
+            'run',
+            'view',
+            str(run_id),
+            '--repo',
+            repo,
+            '--json',
+            'displayTitle,workflowName,url,createdAt',
+        )
+        or {}
+    )
+
+
+def search_issue_numbers(repo: str, query_text: str) -> list[int]:
+    """Search issues (any state) in `repo` for `query_text`, return issue numbers."""
+    # The repo must be passed as `--repo`, not folded into the positional query.
+    # `gh search issues` quotes each positional argument as a single search
+    # keyword, so `repo:owner/name "text"` becomes the literal keyword
+    # `repo:"owner/name \"text\""` and GitHub rejects it as an invalid query.
+    data = (
+        gh_json(
+            'search', 'issues', '--repo', repo, '--limit', '10', '--json', 'number', query_text
+        )
+        or []
+    )
+    return [item['number'] for item in data]
+
+
+def fetch_issue_texts(repo: str, number: int) -> list[str]:
+    """Fetch an issue's body plus all comment bodies, for marker scanning."""
+    data = gh_json('issue', 'view', str(number), '--repo', repo, '--json', 'body,comments') or {}
+    texts = [data.get('body') or '']
+    for c in data.get('comments') or []:
+        texts.append(c.get('body') or '')
+    return texts
+
+
+def recent_issue_texts(repo: str, limit: int = RECENT_ISSUE_SCAN) -> list[tuple[int, str]]:
+    """Return (number, text) pairs for the `limit` most recently updated issues.
+
+    Bodies and comment bodies both, since a notifier marker with
+    `origin=comment` lives in a comment rather than the body.
+    """
+    data = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'all',
+            '--limit',
+            str(limit),
+            '--json',
+            'number,body,comments',
+        )
+        or []
+    )
+    texts: list[tuple[int, str]] = []
+    for issue in data:
+        number = issue['number']
+        texts.append((number, issue.get('body') or ''))
+        for comment in issue.get('comments') or []:
+            texts.append((number, comment.get('body') or ''))
+    return texts
+
+
+def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None, int | None]:
+    """Find the markers belonging to `run_id` and classify them.
+
+    Scans the most recently updated issues first, and only falls back to
+    `gh search issues` if that finds nothing.
+
+    The ordering matters, and is the whole point of doing it this way. The
+    notifier stamps its marker moments before this workflow runs, and GitHub's
+    issue *search* index is not read-your-writes -- a marker that has not been
+    indexed yet reads as "no notifier marker found", and main() responds by
+    opening a *second* issue for a run that already has one. The issue *list*
+    endpoint has no such lag, and the artefact the notifier just touched is by
+    construction among the most recently updated issues in the repo.
+
+    Search remains as a fallback for the one case the list cannot cover: a repo
+    busy enough that more than `RECENT_ISSUE_SCAN` issues were updated in
+    between, where a stale index still beats no lookup at all.
+    """
+    markers = find_run_markers(recent_issue_texts(repo), run_id)
+    if markers != (None, None, None):
+        return markers
+
+    hits = search_issue_numbers(repo, f'{MARKER_PREFIX}:run={run_id}')
+    texts: list[tuple[int, str]] = []
+    for number in hits:
+        for text in fetch_issue_texts(repo, number):
+            texts.append((number, text))
+    return find_run_markers(texts, run_id)
+
+
+def search_candidates(
+    repo: str, workflow_name: str
+) -> tuple[list[CandidateIssue], list[CandidateIssue]]:
+    """Coarse candidate search: open and closed issues matching the workflow name."""
+    fields = 'number,title,body,createdAt,closedAt'
+    open_issues = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'open',
+            '--search',
+            f'"{workflow_name}"',
+            '--json',
+            fields,
+            '--limit',
+            '20',
+        )
+        or []
+    )
+    closed_issues = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'closed',
+            '--search',
+            f'"{workflow_name}"',
+            '--json',
+            fields,
+            '--limit',
+            '20',
+        )
+        or []
+    )
+    return (
+        [CandidateIssue.from_gh(i) for i in open_issues],
+        [CandidateIssue.from_gh(i) for i in closed_issues],
+    )
+
+
+def existing_labels(repo: str) -> set[str]:
+    """Return the set of label names that already exist in `repo`."""
+    data = gh_json('label', 'list', '--repo', repo, '--json', 'name', '--limit', '100') or []
+    return {item['name'] for item in data}
+
+
+def filter_labels(labels: list[str], available: set[str]) -> list[str]:
+    """Drop labels that don't already exist in the repo (never auto-create)."""
+    return [label for label in labels if label in available]
+
+
+def call_openrouter(
+    system_prompt: str, user_prompt: str, model: str, api_key: str
+) -> dict[str, Any]:
+    """POST the prompt to OpenRouter with the envelope schema, return the parsed JSON.
+
+    Uses urllib rather than requests so the script has no third-party
+    dependencies at all. urlopen raises HTTPError (a subclass of OSError) on a
+    non-2xx response, which main() treats the same as any other OpenRouter
+    failure: fall back to the plain body.
+    """
+    payload = {
+        'model': model,
+        'messages': [
+            {'role': 'system', 'content': system_prompt},
+            {'role': 'user', 'content': user_prompt},
+        ],
+        'response_format': {
+            'type': 'json_schema',
+            'json_schema': {
+                'name': 'ai_failure_notification',
+                'strict': True,
+                'schema': ENVELOPE_JSON_SCHEMA,
+            },
+        },
+    }
+    request = urllib.request.Request(
+        'https://openrouter.ai/api/v1/chat/completions',
+        data=json.dumps(payload).encode(),
+        headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
+        method='POST',
+    )
+    # S310: the URL is a literal https endpoint, not caller-controlled.
+    with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310
+        body = json.loads(response.read().decode())
+    content = body['choices'][0]['message']['content']
+    return json.loads(content)
+
+
+def write_step_summary(message: str) -> None:
+    """Report a line to the job's step summary and to the log.
+
+    Always goes to stderr as well as the summary: every fallback path in this
+    script reports through here, and a fallback that only shows up in the
+    summary is invisible to anyone reading the job log or the API.
+    """
+    print(message, file=sys.stderr)
+    path = os.environ.get('GITHUB_STEP_SUMMARY')
+    if path:
+        with open(path, 'a', encoding='utf-8') as f:
+            f.write(message + '\n')
+
+
+def plain_fallback_body(workflow_name: str, run_url: str) -> str:
+    """The plain, generic body text used whenever enrichment is unavailable."""
+    return f"Scheduled workflow '{workflow_name}' failed: {run_url}"
+
+
+def render_body(body: str, workflow_name: str, marker: str) -> str:
+    """Assemble an issue or comment body, footer and marker included.
+
+    The `Workflow: <name>` footer is what keeps the notifier's coarse search
+    working after enrichment has rewritten the title and body: the search
+    matches on the workflow name, and without the footer it would depend on
+    the model happening to leave the name in the title.
+    """
+    return f'{body.rstrip()}\n\nWorkflow: {workflow_name}\n\n{marker}'
+
+
+def apply_entry(
+    repo: str,
+    entry: dict[str, Any],
+    marker: str,
+    workflow_name: str,
+    *,
+    default_target: int | None = None,
+) -> str:
+    """Create or comment on an issue per one envelope entry, stamping `marker`."""
+    body = render_body(entry['body'], workflow_name, marker)
+    if entry['action'] == 'new':
+        # The repo's label set is centrally managed, so anything the model
+        # asked for that doesn't exist is dropped rather than created.
+        labels = filter_labels(entry.get('labels') or [], existing_labels(repo))
+        dropped = set(entry.get('labels') or []) - set(labels)
+        if dropped:
+            write_step_summary(
+                f'Dropped labels that do not exist in this repo: {", ".join(sorted(dropped))}.'
+            )
+        args = ['issue', 'create', '--repo', repo, '--title', entry['title'], '--body', body]
+        for label in labels:
+            args += ['--label', label]
+        issue_type = entry.get('issue_type')
+        result = None
+        if issue_type:
+            result = gh(*args, '--type', issue_type, check=False)
+            if result.returncode != 0:
+                write_step_summary(
+                    f'`gh issue create --type {issue_type}` failed ({result.stderr.strip()}); '
+                    'retrying without --type.'
+                )
+                result = None
+        if result is None:
+            result = gh(*args)
+        return result.stdout.strip()
+    else:
+        target = entry.get('target_issue', default_target)
+        gh('issue', 'comment', str(target), '--repo', repo, '--body', body)
+        return f'commented on #{target}'
+
+
+def main() -> int:
+    """Entry point: locate the run's marker, enrich or fall back, apply, and exit."""
+    repo = os.environ['REPO']
+    run_id = str(os.environ['RUN_ID'])
+    workflow_name = os.environ['WORKFLOW_NAME']
+    run_url = os.environ['RUN_URL']
+    api_key = os.environ.get('OPENROUTER_API_KEY', '')
+    model = os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL
+
+    try:
+        enriched_issue, origin_kind, origin_issue = locate_run_markers(repo, run_id)
+    except Exception as exc:  # search API rejection, rate limit, transient 5xx.
+        # The marker lookup is the first thing main() does, so an uncaught
+        # failure here takes out the whole enrich job and hands every run to
+        # the workflow-level plain-fallback -- losing enrichment silently
+        # rather than degrading through the script's own fallback path.
+        write_step_summary(f'Marker lookup failed ({exc}); treating this run as un-marked.')
+        enriched_issue, origin_kind, origin_issue = None, None, None
+
+    if enriched_issue is not None:
+        # Rung zero: this run id was already fully enriched once -- a re-run of
+        # the same failing jobs re-triggered us. Comment, don't skip and don't
+        # redo the full LLM pass. On a corpus of past scheduled failures this
+        # rung accounted for half the real duplicate pairs, making it the
+        # highest-value one.
+        gh(
+            'issue',
+            'comment',
+            str(enriched_issue),
+            '--repo',
+            repo,
+            '--body',
+            f'Re-run attempt still failing: {run_url}\n\n<!-- {MARKER_PREFIX}:run={run_id} -->',
+        )
+        write_step_summary(
+            f'Rung zero: run {run_id} already enriched on #{enriched_issue}; '
+            'commented re-run note.'
+        )
+        return 0
+
+    if origin_issue is None:
+        # Shouldn't happen -- the notifier always stamps a marker -- but
+        # don't lose the notification if it does.
+        write_step_summary(
+            'No notifier marker found for this run id; falling back to a plain issue.'
+        )
+        result = gh(
+            'issue',
+            'create',
+            '--repo',
+            repo,
+            '--title',
+            f"Scheduled workflow '{workflow_name}' failed",
+            '--body',
+            plain_fallback_body(workflow_name, run_url)
+            + f'\n\n<!-- {MARKER_PREFIX}:run={run_id}:origin=new -->',
+        )
+        origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
+        origin_kind = 'new'
+
+    failed_jobs = fetch_failed_jobs(repo, run_id)
+    jobs_sig = [
+        build_job_signature(job.id, job.name, job.failed_step, fetch_job_log(repo, run_id, job.id))
+        for job in failed_jobs
+    ]
+    meta = fetch_run_meta(repo, run_id)
+    signature = build_run_signature(
+        run_id, workflow_name, run_url, meta.get('createdAt', ''), jobs_sig
+    )
+    enriched_marker = render_enriched_marker(run_id, signature)
+
+    if not api_key:
+        write_step_summary('No OPENROUTER_API_KEY configured -- using the plain fallback body.')
+        apply_entry(
+            repo,
+            {
+                'action': 'comment' if origin_kind == 'comment' else 'new',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    try:
+        open_candidates, closed_candidates = search_candidates(repo, workflow_name)
+    except Exception as exc:  # as above: degrade to "no candidates", don't crash.
+        write_step_summary(f'Candidate search failed ({exc}); proceeding with no candidates.')
+        open_candidates, closed_candidates = [], []
+    if origin_kind == 'new':
+        # The placeholder this run just created is not a candidate to dedupe
+        # against. An issue the notifier *commented* on is a different matter:
+        # it already existed, the coarse search matched it, and it is the most
+        # likely duplicate -- dropping it left the model blind to the very
+        # issue it should have been comparing against, so it answered "new"
+        # and produced the duplicate this whole path exists to avoid.
+        open_candidates = [c for c in open_candidates if c.number != origin_issue]
+    candidates_block = build_candidates_block(
+        open_candidates, closed_candidates, datetime.datetime.now(datetime.timezone.utc)
+    )
+    system_prompt, user_prompt = build_prompt(workflow_name, run_url, signature, candidates_block)
+
+    try:
+        envelope = call_openrouter(system_prompt, user_prompt, model, api_key)
+    except Exception as exc:  # network error, non-2xx, bad JSON, and so on.
+        write_step_summary(f'OpenRouter call failed ({exc}); using the plain fallback body.')
+        apply_entry(
+            repo,
+            {
+                'action': 'new',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    envelope, dropped_fields = normalise_envelope(envelope)
+    if dropped_fields:
+        write_step_summary(
+            'Ignored fields that do not apply to the chosen action: '
+            + ', '.join(dropped_fields)
+            + '.'
+        )
+
+    errors = validate_envelope(envelope)
+    if errors:
+        write_step_summary(
+            'LLM output failed schema validation:\n' + '\n'.join(f'- {e}' for e in errors)
+        )
+        apply_entry(
+            repo,
+            {
+                'action': 'new',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    if envelope['action'] == 'new' and origin_kind == 'new':
+        # Upgrade the placeholder in place rather than creating a duplicate.
+        available = existing_labels(repo)
+        labels = filter_labels(envelope.get('labels') or [], available)
+        edit_args = [
+            'issue',
+            'edit',
+            str(origin_issue),
+            '--repo',
+            repo,
+            '--title',
+            envelope['title'],
+            '--body',
+            render_body(envelope['body'], workflow_name, enriched_marker),
+        ]
+        for label in labels:
+            edit_args += ['--add-label', label]
+        gh(*edit_args)
+    elif envelope['action'] == 'comment' and envelope.get('target_issue') == origin_issue:
+        apply_entry(repo, envelope, enriched_marker, workflow_name, default_target=origin_issue)
+    elif envelope['action'] == 'comment':
+        # LLM picked a different candidate than the notifier's coarse match.
+        apply_entry(repo, envelope, enriched_marker, workflow_name)
+        if origin_kind == 'comment':
+            gh(
+                'issue',
+                'comment',
+                str(origin_issue),
+                '--repo',
+                repo,
+                '--body',
+                f'This looks like a distinct issue -- see #{envelope["target_issue"]}.\n\n'
+                f'{enriched_marker}',
+            )
+    else:
+        # action == "new" but origin_kind == "comment": the coarse title
+        # match landed on an unrelated older issue; this is genuinely new.
+        apply_entry(repo, envelope, enriched_marker, workflow_name)
+        gh(
+            'issue',
+            'comment',
+            str(origin_issue),
+            '--repo',
+            repo,
+            '--body',
+            f'This looks like a distinct issue from this one -- opened separately.\n\n'
+            f'{enriched_marker}',
+        )
+
+    for also_entry in envelope.get('also') or []:
+        apply_entry(repo, also_entry, enriched_marker, workflow_name)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/tests/test_ai_failure_notifier.py b/tests/test_ai_failure_notifier.py
new file mode 100644
index 0000000..fcf5ff4
--- /dev/null
+++ b/tests/test_ai_failure_notifier.py
@@ -0,0 +1,1231 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unit tests for scripts/ai_failure_notifier.py.
+
+No network calls and no `gh` calls happen in this file -- OpenRouter and gh
+I/O are mocked. FIXTURE below is the extracted signature, candidate issue and
+LLM envelope from a real failing scheduled run (28141163589, "Broad Charm
+Compatibility Tests", 2026-06-25); the `tail_excerpt` arrays are trimmed for
+size; `pytest_failures` and `traceback_top_error` are verbatim, since those are
+what the dedup and schema logic actually exercise.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import email.message
+import io
+import json
+import os
+import tempfile
+import unittest
+import urllib.error
+from typing import Any
+from unittest import mock
+
+from charm_tech_code import ai_failure_notifier as afn
+
+# The signature, candidate issue and envelope from a real failing scheduled run
+# (28141163589, "Broad Charm Compatibility Tests", 2026-06-25). The tail_excerpt
+# lists are trimmed for size; pytest_failures and traceback_top_error are
+# verbatim, since those are what the dedup and schema logic exercise.
+FIXTURE_SIGNATURE = afn.RunSignature(
+    run_id='28141163589',
+    workflow_name='Broad Charm Compatibility Tests',
+    html_url='https://github.com/canonical/operator/actions/runs/28141163589',
+    created_at='2026-06-25T01:40:15Z',
+    jobs=[
+        afn.JobSignature(
+            job_id=83338922280,
+            job_name='charm-tests (canonical/charm-ubuntu, .)',
+            failed_step="Run the charm's unit tests",
+            pytest_failures=[
+                afn.PytestFailure(
+                    kind='ERROR',
+                    test='tests/unit/test_charm.py::TestCharm::test_charm_ready',
+                    error='PendingDeprecat...',
+                ),
+                afn.PytestFailure(
+                    kind='ERROR',
+                    test='tests/unit/test_charm.py::TestCharm::test_hostname',
+                    error='PendingDeprecation...',
+                ),
+                afn.PytestFailure(
+                    kind='ERROR',
+                    test='tests/unit/test_charm.py::TestCharm::test_version',
+                    error='PendingDeprecationW...',
+                ),
+            ],
+            go_failures=[],
+            traceback_top_error=(
+                'ResourceWarning: Implicitly cleaning up <TemporaryDirectory '
+                "'/tmp/ops-harness-ruod78qd'>"
+            ),
+            tail_excerpt=[
+                'pytest.PytestUnraisableExceptionWarning: Exception ignored in: <finalize object '
+                'at 0x7f2f582dea60; dead>',
+                'unit: FAIL code 1 (2.04=setup[1.23]+cmd[0.81] seconds)',
+                'evaluation failed :( (2.07 seconds)',
+            ],
+        ),
+        afn.JobSignature(
+            job_id=83338922315,
+            job_name='charm-tests (canonical/k8s-operator, charms/worker/k8s)',
+            failed_step="Run the charm's static tests",
+            pytest_failures=[],
+            go_failures=[],
+            traceback_top_error=None,
+            tail_excerpt=[
+                'Total issues (by severity):',
+                'static: FAIL code 1 (16.01=setup[0.42]+cmd[15.59] seconds)',
+                'evaluation failed :( (16.06 seconds)',
+            ],
+        ),
+        afn.JobSignature(
+            job_id=83338923301,
+            job_name='charm-tests (canonical/seldon-core-operator, .)',
+            failed_step="Run the charm's unit tests",
+            pytest_failures=[
+                afn.PytestFailure(
+                    kind='FAILED',
+                    test='tests/unit/test_operator.py::TestCharm::test_prometheus_data_set',
+                    error=(
+                        "AttributeError: module 'ops.testing' has no attribute "
+                        "'_TestingModelBackend'"
+                    ),
+                ),
+            ],
+            go_failures=[],
+            traceback_top_error=(
+                "AttributeError: module 'ops.testing' has no attribute '_TestingModelBackend'"
+            ),
+            tail_excerpt=[
+                'FAILED tests/unit/test_operator.py::TestCharm::test_prometheus_data_set - '
+                "AttributeError: module 'ops.testing' has no attribute '_TestingModelBackend'",
+                'unit: FAIL code 1 (8.95=setup[0.60]+cmd[8.35] seconds)',
+            ],
+        ),
+        afn.JobSignature(
+            job_id=83338923304,
+            job_name='charm-tests (canonical/self-signed-certificates-operator, .)',
+            failed_step="Run the charm's unit tests",
+            pytest_failures=[],
+            go_failures=[],
+            traceback_top_error=None,
+            tail_excerpt=[
+                'ERROR tests/unit/test_charm_collect_status.py',
+                '!!!!!!!!!!!!!!!!!!! Interrupted: 5 errors during collection !!!!!!!!!!!!!!!!!!!!',
+                'unit: FAIL code 2 (3.43=setup[1.18]+cmd[0.06,0.02,2.16] seconds)',
+            ],
+        ),
+        afn.JobSignature(
+            job_id=83338923318,
+            job_name='charm-tests (canonical/traefik-k8s-operator, .)',
+            failed_step="Run the charm's unit tests",
+            pytest_failures=[],
+            go_failures=[],
+            traceback_top_error=(
+                "ImportError: cannot import name 'Event' from 'scenario' (/home/runner/work/operat"
+                'or/operator/charm-repo/.tox/unit/lib/python3.12/site-packages/scenario/__init__.p'
+                'y)'
+            ),
+            tail_excerpt=[
+                (
+                    "ImportError: cannot import name 'Event' from 'scenario' "
+                    '(/home/runner/work/operator/operator/charm-repo/.tox/unit/lib/python3.12/site'
+                    '-packages/scenario/__init__.py)'
+                ),
+                'unit: FAIL code 1 (6.43=setup[2.14]+cmd[0.06,0.02,4.21] seconds)',
+            ],
+        ),
+    ],
+)
+
+FIXTURE_CANDIDATES = [
+    afn.CandidateIssue(
+        number=9010,
+        title='Broad Charm Compatibility Tests: 4 downstream charms failing, independent causes',
+        body=(
+            'canonical/k8s-operator: bandit exit 1 (Medium: 24, High: 591). '
+            "canonical/seldon-core-operator: AttributeError: module 'ops.testing' has no attribute"
+            " '_TestingModelBackend'. canonical/self-signed-certificates-operator: 5 collection "
+            "errors. canonical/traefik-k8s-operator: ImportError: cannot import name 'Event' from "
+            "'scenario'."
+        ),
+        closed_at=None,
+    ),
+]
+
+FIXTURE_ENVELOPE: dict[str, Any] = {
+    'action': 'comment',
+    'target_issue': 9010,
+    'body': (
+        'Another occurrence: '
+        'https://github.com/canonical/operator/actions/runs/28141163589\n'
+        '\n'
+        '4 of the 5 failing charms match #9010 unchanged. New this run: '
+        'canonical/charm-ubuntu is now also failing its unit tests.'
+    ),
+    'dedup_reason': (
+        "4 of 5 failing charms match #9010's signature; charm-ubuntu is a "
+        'new failure not present in #9010'
+    ),
+    'confidence': 'medium',
+}
+
+
+class SignatureExtractionTests(unittest.TestCase):
+    def test_strip_line_removes_timestamp_and_ansi(self):
+        raw = '2026-06-25T01:40:15.8141713Z \x1b[36mhello\x1b[0m'
+        self.assertEqual(
+            afn.strip_line(raw),
+            '\x1b[36mhello\x1b[0m'.replace('\x1b[36m', '').replace('\x1b[0m', ''),
+        )
+
+    def test_parse_job_log_pytest_failures_and_summary_bound(self):
+        ts = '2026-06-25T01:40:15.0000000Z '
+        log = '\n'.join([
+            f'{ts}============ short test summary info ============',
+            f'{ts}FAILED tests/unit/test_x.py::test_a - AssertionError: x',
+            f'{ts}ERROR tests/unit/test_x.py::test_b - PendingDeprecat...',
+            f'{ts}============ 2 failed in 1.23s ============',
+            f'{ts}some trailing noise, not part of the summary',
+        ])
+        pytest_failures, go_failures, _tb, _tail = afn.parse_job_log(log)
+        self.assertEqual(
+            pytest_failures,
+            [
+                afn.PytestFailure('FAILED', 'tests/unit/test_x.py::test_a', 'AssertionError: x'),
+                afn.PytestFailure('ERROR', 'tests/unit/test_x.py::test_b', 'PendingDeprecat...'),
+            ],
+        )
+        self.assertEqual(go_failures, [])
+
+    def test_parse_job_log_go_failures(self):
+        log = '--- FAIL: TestFoo (0.03s)\n--- FAIL: TestBar (0.01s)\n'
+        _pytest_failures, go_failures, _tb, _tail = afn.parse_job_log(log)
+        self.assertEqual(go_failures, ['TestFoo', 'TestBar'])
+
+    def test_parse_job_log_traceback_top_error_prefers_last_match(self):
+        log = '\n'.join([
+            'ValueError: first, ignored',
+            'some other output',
+            'AttributeError: the real one',
+        ])
+        _, _, tb, _ = afn.parse_job_log(log)
+        self.assertEqual(tb, 'AttributeError: the real one')
+
+    def test_parse_job_log_tail_excerpt_stops_before_first_error_marker(self):
+        log = '\n'.join([
+            'line before 1',
+            'line before 2',
+            '##[error]something broke',
+            'line after (should not appear in tail)',
+        ])
+        _, _, _, tail = afn.parse_job_log(log)
+        self.assertEqual(tail, ['line before 1', 'line before 2'])
+
+    def test_parse_job_log_ignores_the_step_script_the_runner_echoes(self):
+        # A multi-line `run:` puts every branch into the log, executed or not,
+        # so an unexecuted branch must not contribute to the signature.
+        log = '\n'.join([
+            '##[group]Run case "$SHAPE" in',
+            'case "$SHAPE" in',
+            '  traceback-only)',
+            "KeyError: 'loki/0'",
+            '    ;;',
+            'esac',
+            '##[endgroup]',
+            'short test summary info',
+            "FAILED test/test_model.py::TestModel::test_thing - KeyError: 'host'",
+        ])
+        pytest_failures, _go, tb, _tail = afn.parse_job_log(log)
+        self.assertIsNone(tb)
+        self.assertEqual([f.error for f in pytest_failures], ["KeyError: 'host'"])
+
+    def test_parse_job_log_counts_a_failure_once_not_twice(self):
+        # The same summary line appears in the echoed script and again in the
+        # output; only the output one is a failure that happened.
+        log = '\n'.join([
+            '##[group]Run tox -e unit',
+            'FAILED test/test_model.py::TestModel::test_thing - KeyError',
+            '##[endgroup]',
+            'short test summary info',
+            'FAILED test/test_model.py::TestModel::test_thing - KeyError',
+        ])
+        pytest_failures, _go, _tb, _tail = afn.parse_job_log(log)
+        self.assertEqual(len(pytest_failures), 1)
+
+    def test_parse_job_log_keeps_groups_the_step_itself_opened(self):
+        # `::group::` from inside a step is output, not the runner's header;
+        # only "##[group]Run " starts an echoed script.
+        log = '\n'.join([
+            '##[group]my own section',
+            'AttributeError: this is real output',
+            '##[endgroup]',
+        ])
+        _, _, tb, _ = afn.parse_job_log(log)
+        self.assertEqual(tb, 'AttributeError: this is real output')
+
+    def test_strip_log_drops_the_env_dump_with_the_script(self):
+        log = '\n'.join([
+            '##[group]Run uv run scripts/ai_failure_notifier.py',
+            'env:',
+            '  OPENROUTER_API_KEY: ***',
+            '##[endgroup]',
+            'real output',
+        ])
+        self.assertEqual(afn.strip_log(log), ['real output'])
+
+    def test_build_run_signature_matches_fixture_shape(self):
+        jobs = [
+            afn.build_job_signature(j.job_id, j.job_name, j.failed_step, '')
+            for j in FIXTURE_SIGNATURE.jobs
+        ]
+        sig = afn.build_run_signature(
+            '28141163589', 'Broad Charm Compatibility Tests', 'url', '2026-06-25T01:40:15Z', jobs
+        )
+        self.assertEqual(sig.run_id, '28141163589')
+        self.assertEqual(len(sig.jobs), 5)
+        # as_json is what reaches the prompt; field order is declaration order.
+        self.assertEqual(
+            list(json.loads(sig.as_json())),
+            ['run_id', 'workflow_name', 'html_url', 'created_at', 'jobs'],
+        )
+
+
+class MarkerTests(unittest.TestCase):
+    def test_render_and_parse_notifier_marker(self):
+        marker = afn.render_notifier_marker('123', 'new')
+        enriched, origin_kind, origin_issue = afn.find_run_markers([(42, marker)], '123')
+        self.assertIsNone(enriched)
+        self.assertEqual(origin_kind, 'new')
+        self.assertEqual(origin_issue, 42)
+
+    def test_render_and_parse_enriched_marker_is_rung_zero(self):
+        marker = afn.render_enriched_marker('28141163589', FIXTURE_SIGNATURE)
+        run_id = '28141163589'
+        enriched, origin_kind, _origin_issue = afn.find_run_markers([(9010, marker)], run_id)
+        self.assertEqual(enriched, 9010)
+        self.assertIsNone(origin_kind)
+
+    def test_marker_for_different_run_id_does_not_match(self):
+        marker = afn.render_notifier_marker('999', 'comment')
+        enriched, origin_kind, origin_issue = afn.find_run_markers([(1, marker)], '123')
+        self.assertIsNone(enriched)
+        self.assertIsNone(origin_kind)
+        self.assertIsNone(origin_issue)
+
+    def test_signature_hash_is_deterministic_and_order_independent_of_call(self):
+        h1 = afn.signature_hash(FIXTURE_SIGNATURE)
+        h2 = afn.signature_hash(FIXTURE_SIGNATURE)  # independently constructed
+        self.assertEqual(h1, h2)
+        self.assertEqual(len(h1), 16)
+
+    def test_no_marker_present_returns_all_none(self):
+        enriched, origin_kind, origin_issue = afn.find_run_markers(
+            [(1, 'just a normal comment, no marker')], '123'
+        )
+        self.assertIsNone(enriched)
+        self.assertIsNone(origin_kind)
+        self.assertIsNone(origin_issue)
+
+
+class CandidateBlockTests(unittest.TestCase):
+    def test_open_candidate_rendered(self):
+        block = afn.build_candidates_block(
+            FIXTURE_CANDIDATES, [], datetime.datetime.now(datetime.timezone.utc)
+        )
+        self.assertIn('#9010', block)
+        self.assertIn('Broad Charm Compatibility Tests', block)
+        self.assertNotIn('closed', block)
+
+    def test_empty_candidates_block(self):
+        block = afn.build_candidates_block([], [], datetime.datetime.now(datetime.timezone.utc))
+        self.assertEqual(block, '(no open issues found for this workflow)')
+
+    def test_recently_closed_candidate_is_labelled_and_capped_at_medium(self):
+        now = datetime.datetime(2026, 6, 25, tzinfo=datetime.timezone.utc)
+        closed = [
+            afn.CandidateIssue.from_gh({
+                'number': 42,
+                'title': 'old thing',
+                'body': 'x',
+                'closedAt': '2026-06-20T00:00:00Z',
+            })
+        ]
+        block = afn.build_candidates_block([], closed, now)
+        self.assertIn('#42', block)
+        self.assertIn('closed', block)
+        self.assertIn('medium-confidence', block)
+
+    def test_closed_candidate_outside_window_is_dropped(self):
+        now = datetime.datetime(2026, 6, 25, tzinfo=datetime.timezone.utc)
+        closed = [
+            afn.CandidateIssue.from_gh({
+                'number': 42,
+                'title': 'ancient',
+                'body': 'x',
+                'closedAt': '2026-01-01T00:00:00Z',
+            })
+        ]
+        block = afn.build_candidates_block([], closed, now)
+        self.assertEqual(block, '(no open issues found for this workflow)')
+
+    def test_candidates_capped_at_three(self):
+        opens = [
+            afn.CandidateIssue.from_gh({
+                'number': n,
+                'title': f'issue {n}',
+                'body': 'x',
+                'closedAt': None,
+            })
+            for n in range(5)
+        ]
+        block = afn.build_candidates_block(opens, [], datetime.datetime.now(datetime.timezone.utc))
+        self.assertEqual(block.count('- **#'), 3)
+
+
+class SchemaValidationTests(unittest.TestCase):
+    def test_valid_comment_envelope_from_fixture(self):
+        errors = afn.validate_envelope(FIXTURE_ENVELOPE)
+        self.assertEqual(errors, [])
+
+    def test_valid_new_envelope(self):
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 'Something failed',
+            'body': 'details',
+            'labels': ['tests'],
+            'issue_type': None,
+            'dedup_reason': 'no match',
+            'confidence': 'low',
+        }
+        self.assertEqual(afn.validate_envelope(envelope), [])
+
+    def test_new_envelope_with_no_labels_is_valid(self):
+        # No label is mandatory: the repo's label set is centrally managed, and
+        # an empty list is the right answer when none of it applies.
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 'Something failed',
+            'body': 'details',
+            'labels': [],
+            'issue_type': None,
+            'dedup_reason': 'no match',
+            'confidence': 'low',
+        }
+        self.assertEqual(afn.validate_envelope(envelope), [])
+
+    def test_new_envelope_with_non_string_labels_is_invalid(self):
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 'Something failed',
+            'body': 'details',
+            'labels': ['tests', 7],
+            'issue_type': None,
+            'dedup_reason': 'no match',
+            'confidence': 'low',
+        }
+        self.assertTrue(any('labels' in e for e in afn.validate_envelope(envelope)))
+
+    def test_new_envelope_with_target_issue_is_invalid(self):
+        envelope = {
+            'action': 'new',
+            'title': 't',
+            'body': 'b',
+            'labels': ['tests'],
+            'issue_type': None,
+            'dedup_reason': 'd',
+            'confidence': 'low',
+            'target_issue': 5,
+        }
+        errors = afn.validate_envelope(envelope)
+        self.assertTrue(any('target_issue' in e for e in errors))
+
+    def test_comment_envelope_with_title_is_invalid(self):
+        envelope = {
+            'action': 'comment',
+            'target_issue': 5,
+            'title': 'should not be here',
+            'body': 'b',
+            'dedup_reason': 'd',
+            'confidence': 'high',
+        }
+        errors = afn.validate_envelope(envelope)
+        self.assertTrue(any('title' in e for e in errors))
+
+    def test_bad_action_value_is_invalid(self):
+        envelope = {'action': 'delete', 'body': 'b', 'dedup_reason': 'd', 'confidence': 'high'}
+        errors = afn.validate_envelope(envelope)
+        self.assertTrue(any('action' in e for e in errors))
+
+    def test_envelope_with_also_is_valid(self):
+        # Regression: `also` is legal on the top-level envelope, and the model
+        # emits it routinely because the schema it is given declares it. The
+        # top-level unknown-field check used to reject every envelope carrying
+        # it, so the LLM path always fell back to the plain body. The three
+        # tests below did not catch it: they assert invalidity and match on the
+        # substring "also", which the spurious error also contained.
+        base = dict(FIXTURE_ENVELOPE)
+        base['also'] = [dict(FIXTURE_ENVELOPE)]
+        self.assertEqual(afn.validate_envelope(base), [])
+
+    def test_envelope_with_empty_also_is_valid(self):
+        base = dict(FIXTURE_ENVELOPE)
+        base['also'] = []
+        self.assertEqual(afn.validate_envelope(base), [])
+
+    def test_genuinely_unknown_top_level_field_is_still_invalid(self):
+        base = dict(FIXTURE_ENVELOPE)
+        base['nonsense'] = 1
+        self.assertTrue(any('nonsense' in e for e in afn.validate_envelope(base)))
+
+    def test_new_envelope_with_null_target_issue_is_valid(self):
+        # The schema sent to OpenRouter is `strict`, so models return every
+        # declared property and null the inapplicable ones. Rejecting on mere
+        # presence discarded good output; only a real value is a conflict.
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 't',
+            'body': 'b',
+            'labels': ['tests'],
+            'issue_type': None,
+            'target_issue': None,
+            'dedup_reason': 'd',
+            'confidence': 'low',
+        }
+        self.assertEqual(afn.validate_envelope(envelope), [])
+
+    def test_new_envelope_with_a_real_target_issue_is_still_invalid(self):
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 't',
+            'body': 'b',
+            'labels': [],
+            'issue_type': None,
+            'target_issue': 7,
+            'dedup_reason': 'd',
+            'confidence': 'low',
+        }
+        self.assertTrue(
+            any('target_issue' in e for e in afn.validate_envelope(envelope)),
+        )
+
+    def test_comment_envelope_with_null_new_only_fields_is_valid(self):
+        envelope: dict[str, Any] = {
+            'action': 'comment',
+            'target_issue': 7,
+            'body': 'b',
+            'title': None,
+            'labels': None,
+            'issue_type': None,
+            'dedup_reason': 'd',
+            'confidence': 'high',
+        }
+        self.assertEqual(afn.validate_envelope(envelope), [])
+
+    def test_comment_envelope_with_a_real_title_is_still_invalid(self):
+        envelope: dict[str, Any] = {
+            'action': 'comment',
+            'target_issue': 7,
+            'body': 'b',
+            'title': 'nope',
+            'dedup_reason': 'd',
+            'confidence': 'high',
+        }
+        self.assertTrue(any('title' in e for e in afn.validate_envelope(envelope)))
+
+    def test_also_capped_at_two_entries(self):
+        base = dict(FIXTURE_ENVELOPE)
+        base['also'] = [dict(FIXTURE_ENVELOPE) for _ in range(3)]
+        errors = afn.validate_envelope(base)
+        self.assertTrue(any('at most two entries' in e for e in errors), errors)
+
+    def test_nested_also_is_invalid(self):
+        base = dict(FIXTURE_ENVELOPE)
+        inner = dict(FIXTURE_ENVELOPE)
+        inner['also'] = [dict(FIXTURE_ENVELOPE)]
+        base['also'] = [inner]
+        errors = afn.validate_envelope(base)
+        self.assertTrue(any("nested 'also'" in e for e in errors), errors)
+
+    def test_also_entries_individually_validated(self):
+        base = dict(FIXTURE_ENVELOPE)
+        broken = {'action': 'comment'}  # missing body/dedup_reason/confidence/target_issue
+        base['also'] = [broken]
+        errors = afn.validate_envelope(base)
+        self.assertTrue(any('also[0]' in e for e in errors))
+
+
+class MainFlowTests(unittest.TestCase):
+    """Exercises main()'s branching with gh and OpenRouter mocked out --
+    No live gh or OpenRouter calls happen in this test.
+    """
+
+    def setUp(self):
+        self.env = {
+            'REPO': 'canonical/operator',
+            'RUN_ID': '28141163589',
+            'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
+            'RUN_URL': 'https://github.com/canonical/operator/actions/runs/28141163589',
+            'OPENROUTER_API_KEY': 'test-key',
+        }
+
+    def _patch_common(
+        self,
+        *,
+        locate_return: tuple[int | None, str | None, int | None],
+        gh_calls: mock.Mock,
+    ) -> list[Any]:
+        patches = [
+            mock.patch.object(afn, 'locate_run_markers', return_value=locate_return),
+            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(
+                afn, 'fetch_run_meta', return_value={'createdAt': '2026-06-25T01:40:15Z'}
+            ),
+            mock.patch.object(afn, 'search_candidates', return_value=(FIXTURE_CANDIDATES, [])),
+            mock.patch.object(afn, 'existing_labels', return_value={'tests', 'docs'}),
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary'),
+        ]
+        return patches
+
+    def test_rung_zero_comments_and_skips_llm(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        patches = self._patch_common(locate_return=(9010, None, None), gh_calls=gh_calls)
+        with (
+            mock.patch.dict('os.environ', self.env, clear=True),
+            mock.patch.object(afn, 'call_openrouter') as call_openrouter,
+            contextlib.ExitStack() as stack,
+        ):
+            for p in patches:
+                stack.enter_context(p)
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        call_openrouter.assert_not_called()
+        gh_calls.assert_called_once()
+        self.assertEqual(gh_calls.call_args.args[:3], ('issue', 'comment', '9010'))
+
+    def test_valid_llm_response_upgrades_placeholder_in_place(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        patches = self._patch_common(locate_return=(None, 'new', 4242), gh_calls=gh_calls)
+        envelope = {
+            'action': 'new',
+            'title': 'x',
+            'body': 'y',
+            'labels': ['tests'],
+            'issue_type': None,
+            'dedup_reason': 'd',
+            'confidence': 'medium',
+        }
+        with (
+            mock.patch.dict('os.environ', self.env, clear=True),
+            mock.patch.object(afn, 'call_openrouter', return_value=envelope),
+            contextlib.ExitStack() as stack,
+        ):
+            for p in patches:
+                stack.enter_context(p)
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        edit_calls = [c for c in gh_calls.call_args_list if c.args[:2] == ('issue', 'edit')]
+        self.assertEqual(len(edit_calls), 1)
+        self.assertEqual(edit_calls[0].args[2], '4242')
+
+    def test_invalid_llm_response_falls_back_to_plain_comment(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        patches = self._patch_common(locate_return=(None, 'comment', 4242), gh_calls=gh_calls)
+        with (
+            mock.patch.dict('os.environ', self.env, clear=True),
+            mock.patch.object(
+                afn, 'call_openrouter', return_value={'action': 'not-a-real-action'}
+            ),
+            contextlib.ExitStack() as stack,
+        ):
+            for p in patches:
+                stack.enter_context(p)
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        comment_calls = [c for c in gh_calls.call_args_list if c.args[:2] == ('issue', 'comment')]
+        self.assertEqual(len(comment_calls), 1)
+        self.assertEqual(comment_calls[0].args[2], '4242')
+
+    def test_no_api_key_uses_plain_fallback_without_calling_llm(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        patches = self._patch_common(locate_return=(None, 'new', 4242), gh_calls=gh_calls)
+        env = dict(self.env)
+        env.pop('OPENROUTER_API_KEY')
+        with (
+            mock.patch.dict('os.environ', env, clear=True),
+            mock.patch.object(afn, 'call_openrouter') as call_openrouter,
+            contextlib.ExitStack() as stack,
+        ):
+            for p in patches:
+                stack.enter_context(p)
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        call_openrouter.assert_not_called()
+
+
+class GhCallShapeTests(unittest.TestCase):
+    """Pins the argv of each read-only gh call.
+
+    These mock only the `gh` subprocess boundary, not the functions under
+    test, so a wrong flag or a mis-quoted positional is visible here. The
+    MainFlowTests above patch out `locate_run_markers` and `search_candidates`
+    wholesale, which is why both shipped with argv bugs that 29 green tests
+    did not catch -- see the 2026-07-25 dev-box run against canonical/operator.
+    """
+
+    def _capture(self, stdout: str = '[]') -> mock.Mock:
+        return mock.Mock(return_value=mock.Mock(returncode=0, stdout=stdout, stderr=''))
+
+    def test_search_issue_numbers_passes_repo_as_a_flag(self):
+        gh_calls = self._capture('[{"number": 2658}]')
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            numbers = afn.search_issue_numbers('canonical/operator', 'Example Charm Tests')
+        self.assertEqual(numbers, [2658])
+        args = gh_calls.call_args.args
+        self.assertEqual(args[:2], ('search', 'issues'))
+        self.assertIn('--repo', args)
+        self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+        # The query is a bare positional -- no `repo:` prefix, no added quotes.
+        # `gh search issues` quotes each positional as one keyword, so folding
+        # the repo in produces `repo:"canonical/operator \"text\""`, which
+        # GitHub rejects with "Invalid search query".
+        self.assertIn('Example Charm Tests', args)
+        for arg in args:
+            self.assertNotIn('repo:canonical/operator', arg)
+
+    def test_search_candidates_passes_state_and_search_flags(self):
+        gh_calls = self._capture('[]')
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            afn.search_candidates('canonical/operator', 'Example Charm Tests')
+        states: list[str] = []
+        for call in gh_calls.call_args_list:
+            args = call.args
+            self.assertEqual(args[:2], ('issue', 'list'))
+            self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+            self.assertEqual(args[args.index('--search') + 1], '"Example Charm Tests"')
+            states.append(args[args.index('--state') + 1])
+        self.assertEqual(states, ['open', 'closed'])
+
+    def test_fetch_job_log_uses_the_rest_logs_endpoint(self):
+        gh_calls = self._capture('2026-07-21T16:17:04Z some log line\n')
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        self.assertIn('some log line', log)
+        # Without --allow-escape-sequences, gh 2.9x+ writes nothing at all for
+        # a log with terminal escapes in it, which is every Actions log.
+        self.assertEqual(
+            gh_calls.call_args.args,
+            (
+                'api',
+                'repos/canonical/operator/actions/jobs/88693036489/logs',
+                '--allow-escape-sequences',
+            ),
+        )
+
+    def test_fetch_job_log_retries_without_the_flag_on_an_older_gh(self):
+        results = [
+            mock.Mock(returncode=1, stdout='', stderr='unknown flag: --allow-escape-sequences'),
+            mock.Mock(returncode=0, stdout='2026-07-21T16:17:04Z some log line\n', stderr=''),
+        ]
+        gh_calls = mock.Mock(side_effect=results)
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        self.assertIn('some log line', log)
+        self.assertEqual(
+            [call.args for call in gh_calls.call_args_list],
+            [
+                (
+                    'api',
+                    'repos/canonical/operator/actions/jobs/88693036489/logs',
+                    '--allow-escape-sequences',
+                ),
+                ('api', 'repos/canonical/operator/actions/jobs/88693036489/logs'),
+            ],
+        )
+
+    def test_fetch_job_log_does_not_retry_when_the_flag_was_accepted(self):
+        gh_calls = mock.Mock(
+            return_value=mock.Mock(returncode=1, stdout='', stderr='gh: Not Found (HTTP 404)')
+        )
+        with (
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary'),
+        ):
+            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        self.assertEqual(gh_calls.call_count, 1)
+
+    def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
+        gh_calls = self._capture('')
+        with (
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary') as summary,
+        ):
+            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        self.assertEqual(log, '')
+        summary.assert_called_once()
+        self.assertIn('no log text', summary.call_args.args[0])
+
+    def test_fetch_job_log_reports_the_status_gh_put_on_stderr(self):
+        gh_calls = mock.Mock(
+            return_value=mock.Mock(returncode=1, stdout='', stderr='gh: Not Found (HTTP 404)\n')
+        )
+        with (
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary') as summary,
+        ):
+            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        # A 404 (log not ready) and a 403 (no `actions: read`) are both exit 1,
+        # so the status has to reach the summary for either to be diagnosable.
+        self.assertIn('HTTP 404', summary.call_args.args[0])
+
+    def test_fetch_job_log_says_so_when_gh_was_silent(self):
+        gh_calls = self._capture('')
+        with (
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary') as summary,
+        ):
+            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+        self.assertIn('no stderr', summary.call_args.args[0])
+
+    def test_fetch_failed_jobs_requests_the_jobs_field(self):
+        gh_calls = self._capture(
+            '{"jobs": [{"databaseId": 1, "name": "j", "conclusion": "failure",'
+            ' "steps": [{"name": "s", "conclusion": "failure"}]}]}'
+        )
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            jobs = afn.fetch_failed_jobs('canonical/operator', '29847889218')
+        self.assertEqual(jobs, [afn.FailedJob(id=1, name='j', failed_step='s')])
+        args = gh_calls.call_args.args
+        self.assertEqual(args[:3], ('run', 'view', '29847889218'))
+        self.assertEqual(args[args.index('--json') + 1], 'jobs')
+
+    def test_existing_labels_requests_the_name_field(self):
+        gh_calls = self._capture('[{"name": "tests"}, {"name": "docs"}]')
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            labels = afn.existing_labels('canonical/operator')
+        self.assertEqual(labels, {'tests', 'docs'})
+        args = gh_calls.call_args.args
+        self.assertEqual(args[:2], ('label', 'list'))
+        self.assertEqual(args[args.index('--json') + 1], 'name')
+
+
+class MarkerLookupConsistencyTests(unittest.TestCase):
+    """The notifier's marker must be found without depending on the search index.
+
+    `gh search issues` is not read-your-writes: the notifier stamps its marker
+    seconds before the enricher runs, and an unindexed marker reads as "no
+    notifier marker found", which makes main() open a *second* issue for a run
+    that already has one. The issue list endpoint has no such lag, so it is
+    consulted first and search is only a fallback.
+    """
+
+    def _gh(self, responses: list[str]) -> mock.Mock:
+        return mock.Mock(
+            side_effect=[mock.Mock(returncode=0, stdout=out, stderr='') for out in responses]
+        )
+
+    def test_marker_in_a_body_is_found_without_any_search_call(self):
+        listing = json.dumps([
+            {'number': 2700, 'body': 'unrelated', 'comments': []},
+            {
+                'number': 2658,
+                'body': 'placeholder\n\n<!-- ai-failure-notifications:run=999:origin=new -->',
+                'comments': [],
+            },
+        ])
+        gh_calls = self._gh([listing])
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+        self.assertEqual((enriched, kind, number), (None, 'new', 2658))
+        # Exactly one call, and it is the list endpoint -- not search.
+        self.assertEqual(gh_calls.call_count, 1)
+        args = gh_calls.call_args.args
+        self.assertEqual(args[:2], ('issue', 'list'))
+        self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+        self.assertEqual(args[args.index('--state') + 1], 'all')
+        self.assertEqual(args[args.index('--json') + 1], 'number,body,comments')
+
+    def test_marker_in_a_comment_is_found_too(self):
+        comment = 'failed again\n\n<!-- ai-failure-notifications:run=999:origin=comment -->'
+        listing = json.dumps([
+            {
+                'number': 2601,
+                'body': 'an older failure thread',
+                'comments': [{'body': comment}],
+            }
+        ])
+        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing])):
+            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+        self.assertEqual((enriched, kind, number), (None, 'comment', 2601))
+
+    def test_search_is_a_fallback_when_the_listing_misses(self):
+        listing = json.dumps([{'number': 2700, 'body': 'unrelated', 'comments': []}])
+        search = json.dumps([{'number': 2658}])
+        view = json.dumps({
+            'body': 'placeholder\n\n<!-- ai-failure-notifications:run=999:origin=new -->',
+            'comments': [],
+        })
+        gh_calls = self._gh([listing, search, view])
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+        self.assertEqual((enriched, kind, number), (None, 'new', 2658))
+        self.assertEqual(gh_calls.call_args_list[1].args[:2], ('search', 'issues'))
+
+    def test_an_unindexed_marker_still_resolves(self):
+        """The regression this change exists for.
+
+        Search returns nothing (the marker is not indexed yet) but the issue is
+        right there in the listing. Before the fix this returned all-None and
+        main() opened a duplicate issue.
+        """
+        listing = json.dumps([
+            {
+                'number': 2658,
+                'body': 'placeholder\n\n<!-- ai-failure-notifications:run=999:origin=new -->',
+                'comments': [],
+            }
+        ])
+        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing, '[]'])):
+            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+        self.assertEqual((enriched, kind, number), (None, 'new', 2658))
+
+    def test_rung_zero_sig_marker_is_found_in_the_listing(self):
+        listing = json.dumps([
+            {
+                'number': 2658,
+                'body': 'enriched\n\n<!-- ai-failure-notifications:run=999:sig=abc123 -->',
+                'comments': [],
+            }
+        ])
+        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing])):
+            enriched, _, _ = afn.locate_run_markers('canonical/operator', '999')
+        self.assertEqual(enriched, 2658)
+
+
+class NormalisationTests(unittest.TestCase):
+    """Fields that do not apply to the chosen action are dropped, not fatal.
+
+    Found by dogfooding: the model is given a `strict` schema, so it returns
+    every declared property and fills the ones irrelevant to the action it
+    chose. Treating those as validation errors discarded a perfectly good
+    comment body and fell back to the plain notice.
+    """
+
+    def test_comment_loses_new_only_fields(self):
+        envelope: dict[str, Any] = {
+            'action': 'comment',
+            'target_issue': 9010,
+            'body': 'Another occurrence.',
+            'title': 'a title it should not have',
+            'labels': ['tests'],
+            'issue_type': 'bug',
+            'dedup_reason': 'd',
+            'confidence': 'high',
+        }
+        cleaned, dropped = afn.normalise_envelope(envelope)
+        self.assertEqual(
+            sorted(dropped), ['envelope: issue_type', 'envelope: labels', 'envelope: title']
+        )
+        self.assertNotIn('title', cleaned)
+        self.assertEqual(cleaned['body'], 'Another occurrence.')
+        self.assertEqual(afn.validate_envelope(cleaned), [])
+
+    def test_new_loses_target_issue(self):
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 't',
+            'body': 'b',
+            'labels': [],
+            'issue_type': None,
+            'target_issue': 7,
+            'dedup_reason': 'd',
+            'confidence': 'low',
+        }
+        cleaned, dropped = afn.normalise_envelope(envelope)
+        self.assertEqual(dropped, ['envelope: target_issue'])
+        self.assertEqual(afn.validate_envelope(cleaned), [])
+
+    def test_also_entries_are_normalised_too(self):
+        inner: dict[str, Any] = {
+            'action': 'comment',
+            'target_issue': 1,
+            'body': 'b',
+            'title': 'nope',
+            'dedup_reason': 'd',
+            'confidence': 'low',
+        }
+        envelope: dict[str, Any] = {
+            'action': 'new',
+            'title': 't',
+            'body': 'b',
+            'labels': [],
+            'issue_type': None,
+            'dedup_reason': 'd',
+            'confidence': 'low',
+            'also': [inner],
+        }
+        cleaned, dropped = afn.normalise_envelope(envelope)
+        self.assertEqual(dropped, ['envelope.also[0]: title'])
+        self.assertEqual(afn.validate_envelope(cleaned), [])
+
+    def test_nothing_dropped_leaves_the_envelope_alone(self):
+        cleaned, dropped = afn.normalise_envelope(FIXTURE_ENVELOPE)
+        self.assertEqual(dropped, [])
+        self.assertIs(cleaned, FIXTURE_ENVELOPE)
+
+
+class CandidatePoolTests(unittest.TestCase):
+    """The issue the notifier commented on stays in the candidate pool.
+
+    Found by dogfooding. The origin issue was excluded unconditionally. When
+    the notifier had commented on a pre-existing issue -- the case for every
+    recurrence after the first -- that issue is the most likely duplicate, and
+    removing it left the model with an empty candidate list. It answered "new",
+    and a duplicate issue was opened: the exact outcome this path exists to
+    prevent.
+    """
+
+    def _run_main(self, *, origin_kind: str, candidates: list[afn.CandidateIssue]) -> str:
+        captured: dict[str, str] = {}
+
+        def fake_build_prompt(
+            workflow_name: str, run_url: str, signature: Any, candidates_block: str
+        ) -> tuple[str, str]:
+            captured['block'] = candidates_block
+            return 'sys', 'user'
+
+        env = {
+            'REPO': 'canonical/operator',
+            'RUN_ID': '28141163589',
+            'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
+            'RUN_URL': 'https://example.invalid/run',
+            'OPENROUTER_API_KEY': 'test-key',
+        }
+        with (
+            mock.patch.dict(os.environ, env, clear=True),
+            mock.patch.object(afn, 'locate_run_markers', return_value=(None, origin_kind, 9010)),
+            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn, 'search_candidates', return_value=(candidates, [])),
+            mock.patch.object(afn, 'existing_labels', return_value=set()),
+            mock.patch.object(afn, 'build_prompt', side_effect=fake_build_prompt),
+            mock.patch.object(afn, 'call_openrouter', return_value={'action': 'bogus'}),
+            mock.patch.object(afn, 'gh'),
+            mock.patch.object(afn, 'write_step_summary'),
+        ):
+            afn.main()
+        return captured['block']
+
+    def test_commented_origin_issue_is_offered_as_a_candidate(self):
+        candidate = afn.CandidateIssue(
+            number=9010, title='the tracked one', body='x', closed_at=None
+        )
+        block = self._run_main(origin_kind='comment', candidates=[candidate])
+        self.assertIn('#9010', block)
+
+    def test_freshly_created_placeholder_is_not_offered_as_a_candidate(self):
+        candidate = afn.CandidateIssue(
+            number=9010, title='the placeholder', body='x', closed_at=None
+        )
+        block = self._run_main(origin_kind='new', candidates=[candidate])
+        self.assertNotIn('#9010', block)
+
+
+class BodyFooterTests(unittest.TestCase):
+    """Every body carries the footer the notifier's coarse search matches on.
+
+    Found by dogfooding: the footer was described in the design and in the
+    notifier's own comment, but only ever existed in the prompt template, so
+    enriched issues went out without it. The coarse search then depended on
+    the model happening to leave the workflow name in the title.
+    """
+
+    def test_render_body_has_footer_and_marker(self):
+        body = afn.render_body('Some detail.', 'Example Charm Tests', '<!-- m -->')
+        self.assertEqual(body, 'Some detail.\n\nWorkflow: Example Charm Tests\n\n<!-- m -->')
+
+    def test_applied_comment_body_has_the_footer(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        entry: dict[str, Any] = {'action': 'comment', 'body': 'Another occurrence.'}
+        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+            afn.apply_entry(
+                'canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests', default_target=7
+            )
+        args = gh_calls.call_args.args
+        self.assertEqual(args[:3], ('issue', 'comment', '7'))
+        self.assertIn('Workflow: ops Smoke Tests', args[args.index('--body') + 1])
+
+    def test_applied_new_issue_body_has_the_footer(self):
+        gh_calls = mock.Mock(
+            return_value=mock.Mock(returncode=0, stdout='https://x/issues/9', stderr='')
+        )
+        entry: dict[str, Any] = {
+            'action': 'new',
+            'title': 't',
+            'body': 'Detail.',
+            'labels': [],
+            'issue_type': None,
+        }
+        with (
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'existing_labels', return_value=set()),
+        ):
+            afn.apply_entry('canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests')
+        args = gh_calls.call_args.args
+        self.assertIn('Workflow: ops Smoke Tests', args[args.index('--body') + 1])
+
+
+class StepSummaryTests(unittest.TestCase):
+    """Fallback reporting reaches the job log, not only the step summary."""
+
+    def test_message_goes_to_stderr_even_with_a_summary_file(self):
+        with tempfile.NamedTemporaryFile('w+', suffix='.md', delete=False) as handle:
+            summary_path = handle.name
+        self.addCleanup(os.unlink, summary_path)
+        stderr = io.StringIO()
+        with (
+            mock.patch.dict(os.environ, {'GITHUB_STEP_SUMMARY': summary_path}, clear=True),
+            contextlib.redirect_stderr(stderr),
+        ):
+            afn.write_step_summary('OpenRouter call failed (boom)')
+        self.assertIn('OpenRouter call failed (boom)', stderr.getvalue())
+        with open(summary_path, encoding='utf-8') as handle:
+            self.assertIn('OpenRouter call failed (boom)', handle.read())
+
+
+class MainDegradationTests(unittest.TestCase):
+    """main() degrades through its own fallbacks when a gh search fails.
+
+    Without these, a search failure raises out of main(), kills the enrich
+    job, and hands every run to the workflow-level plain-fallback -- so
+    enrichment silently never happens and the job still looks healthy.
+    """
+
+    def setUp(self):
+        self.env = {
+            'REPO': 'canonical/operator',
+            'RUN_ID': '28141163589',
+            'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
+            'RUN_URL': 'https://github.com/canonical/operator/actions/runs/28141163589',
+        }
+
+    def test_marker_lookup_failure_does_not_crash_main(self):
+        gh_calls = mock.Mock(
+            return_value=mock.Mock(
+                returncode=0, stdout='https://github.com/canonical/operator/issues/9999', stderr=''
+            )
+        )
+        with (
+            mock.patch.dict('os.environ', self.env, clear=True),
+            mock.patch.object(afn, 'locate_run_markers', side_effect=RuntimeError('boom')),
+            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn, 'existing_labels', return_value=set()),
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary') as summary,
+        ):
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        self.assertTrue(
+            any('Marker lookup failed' in c.args[0] for c in summary.call_args_list),
+            'the failure should be reported in the step summary',
+        )
+
+    def test_candidate_search_failure_proceeds_with_no_candidates(self):
+        gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
+        env = dict(self.env, OPENROUTER_API_KEY='test-key')
+        with (
+            mock.patch.dict('os.environ', env, clear=True),
+            mock.patch.object(afn, 'locate_run_markers', return_value=(None, 'new', 4242)),
+            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn, 'search_candidates', side_effect=RuntimeError('boom')),
+            mock.patch.object(afn, 'existing_labels', return_value=set()),
+            mock.patch.object(
+                afn, 'call_openrouter', return_value={'action': 'not-a-real-action'}
+            ),
+            mock.patch.object(afn, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn, 'write_step_summary') as summary,
+        ):
+            rc = afn.main()
+        self.assertEqual(rc, 0)
+        self.assertTrue(
+            any('Candidate search failed' in c.args[0] for c in summary.call_args_list),
+            'the failure should be reported in the step summary',
+        )
+
+
+class OpenRouterCallTests(unittest.TestCase):
+    """The OpenRouter call is built with urllib, so it has no third-party deps.
+
+    Previously this function was only ever mocked, so nothing checked the
+    request it actually builds.
+    """
+
+    def _response(self, content: str) -> mock.MagicMock:
+        payload = json.dumps({'choices': [{'message': {'content': content}}]}).encode()
+        response = mock.MagicMock()
+        response.read.return_value = payload
+        response.__enter__.return_value = response
+        return response
+
+    def test_posts_json_with_auth_and_schema(self):
+        envelope = {'action': 'new', 'body': 'b'}
+        with mock.patch.object(
+            afn.urllib.request, 'urlopen', return_value=self._response(json.dumps(envelope))
+        ) as urlopen:
+            result = afn.call_openrouter('sys', 'user', 'some/model', 'secret-key')
+
+        self.assertEqual(result, envelope)
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.method, 'POST')
+        self.assertEqual(request.full_url, 'https://openrouter.ai/api/v1/chat/completions')
+        # urllib title-cases header keys, so compare case-insensitively.
+        headers = {k.lower(): v for k, v in request.headers.items()}
+        self.assertEqual(headers['Authorization'.lower()], 'Bearer secret-key')
+        self.assertEqual(headers['Content-type'.lower()], 'application/json')
+        self.assertEqual(urlopen.call_args.kwargs['timeout'], 60)
+
+        sent = json.loads(request.data.decode())
+        self.assertEqual(sent['model'], 'some/model')
+        self.assertEqual([m['role'] for m in sent['messages']], ['system', 'user'])
+        self.assertEqual(sent['messages'][0]['content'], 'sys')
+        self.assertEqual(sent['messages'][1]['content'], 'user')
+        self.assertEqual(sent['response_format']['type'], 'json_schema')
+        self.assertEqual(
+            sent['response_format']['json_schema']['schema'], afn.ENVELOPE_JSON_SCHEMA
+        )
+        self.assertTrue(sent['response_format']['json_schema']['strict'])
+
+    def test_http_error_propagates_so_main_can_fall_back(self):
+        # HTTPError holds a file object and warns on implicit cleanup, which
+        # the unit env's -W error turns into a failure. Give it a real `fp`
+        # (it fabricates a tempfile when passed None) and close it explicitly.
+        error = urllib.error.HTTPError(
+            'https://openrouter.ai/api/v1/chat/completions',
+            500,
+            'boom',
+            email.message.Message(),
+            io.BytesIO(b''),
+        )
+        self.addCleanup(error.close)
+        with mock.patch.object(afn.urllib.request, 'urlopen', side_effect=error):
+            with self.assertRaises(urllib.error.HTTPError):
+                afn.call_openrouter('sys', 'user', 'm', 'k')

From 8b33bfbc65cb3ebb268ed5e22b01c0db765148a3 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 11:31:24 +1200
Subject: [PATCH 02/19] ci: run the tests on 3.10, 3.12 and 3.14

Matches the Python versions canonical/operator tests against, since that is
where this code came from and where it runs. Actions are SHA-pinned to the
same revisions the calling workflow already pins.

Lint runs but the formatter does not, deliberately: the moved file is
byte-identical to what is under review in operator#2663, and turning the
formatter on now would put a 230-line diff on it.
---
 .github/workflows/ci.yaml | 37 +++++++++++++++++++++++++++++++++++++
 pyproject.toml            |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 .github/workflows/ci.yaml

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
new file mode 100644
index 0000000..ad1e198
--- /dev/null
+++ b/.github/workflows/ci.yaml
@@ -0,0 +1,37 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.12', '3.14']
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
+      - run: uvx ruff check .
+      # No `ruff format --check` yet. The moved file is byte-identical to what
+      # is under review in canonical/operator#2663, and the ruff version that
+      # formatted it hugged brackets inside calls where current ruff does not.
+      # Reformatting would put a 230-line diff on a file two people are part
+      # way through reviewing. Worth turning on once that PR lands.
diff --git a/pyproject.toml b/pyproject.toml
index e74050a..e1a75d4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,7 @@ testpaths = ["tests"]
 
 [tool.ruff]
 line-length = 99
+target-version = "py310"
 src = ["src", "tests"]
 
 [tool.ruff.format]

From 8d719f984a4d1cbf4014272412500ff3e78229d3 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 11:34:59 +1200
Subject: [PATCH 03/19] docs: soft wrap the README

One line per paragraph rather than hard breaks at 76 columns, so diffs on a
reworded sentence stay one line instead of reflowing the paragraph around it.
---
 README.md | 24 ++++++------------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 8b01672..1317572 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,24 @@
 # charm-tech-code
 
-Shared tooling for the Charm Tech repositories (`operator`, `charmlibs`,
-`jubilant`, `pebble`, `concierge`, and the rest of the estate).
+Shared tooling for the Charm Tech repositories (`operator`, `charmlibs`, `jubilant`, `pebble`, `concierge`, and the rest of the estate).
 
-Code here is consumed by workflow YAML in the repository that runs it, pinned
-by commit SHA:
+Code here is consumed by workflow YAML in the repository that runs it, pinned by commit SHA:
 
 ```yaml
 run: uvx --from git+https://github.com/canonical/charm-tech-code@<40-char-sha> ai-failure-notifier
 ```
 
-The point is that the code lives in one place. A tool used by eleven
-repositories should be fixed once, not eleven times, and the workflow YAML
-that differs per repository stays in that repository.
+The point is that the code lives in one place. A tool used by eleven repositories should be fixed once, not eleven times, and the workflow YAML that differs per repository stays in that repository.
 
-There is no release process and nothing is published. The SHA in the `uvx`
-line is the version, which is the same trust decision every pinned
-`uses: actions/checkout@<sha>` line in those repositories already makes.
+There is no release process and nothing is published. The SHA in the `uvx` line is the version, which is the same trust decision every pinned `uses: actions/checkout@<sha>` line in those repositories already makes.
 
 ## Tools
 
 ### `ai-failure-notifier`
 
-Enriches the placeholder issue that a scheduled workflow's failure notifier
-opens. It reads the failing run's job logs, builds a deterministic failure
-signature, searches for issues that look like the same failure, and either
-comments on one or rewrites the placeholder with a real title, body and
-labels. Without an API key it falls back to a plain notification, so the
-notifier's "always works" property is not affected by this being unavailable.
+Enriches the placeholder issue that a scheduled workflow's failure notifier opens. It reads the failing run's job logs, builds a deterministic failure signature, searches for issues that look like the same failure, and either comments on one or rewrites the placeholder with a real title, body and labels. Without an API key it falls back to a plain notification, so the notifier's "always works" property is not affected by this being unavailable.
 
-See `canonical/operator`'s `.github/workflows/ai-failure-enrich.yaml` for the
-calling side.
+See `canonical/operator`'s `.github/workflows/ai-failure-enrich.yaml` for the calling side.
 
 ## Developing
 

From e6872ea914da9930d15296ca8d3e14d8850495b4 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 11:39:41 +1200
Subject: [PATCH 04/19] refactor: one directory per tool, matching charmlibs

A single top-level src/ and tests/ only works while there is one tool in
here, and the whole argument for this repo existing is that there will be
more. canonical/charmlibs already solved this - a directory per package, each
with its own pyproject.toml, src/, tests/ and lockfile - so this follows that
rather than inventing a second convention for the team to remember.

The concrete win is dependency isolation. ai-failure-notifier has no runtime
dependencies and is invoked by uvx on a runner after a scheduled workflow has
already failed, so anything a future tool needs would otherwise be installed
on every failed run of a workflow whose point is to work when things are
broken.

The formatter is on again rather than dropped. The settings were never the
problem: operator runs `ruff format --preview`, and the preview style hugs
brackets inside calls, which is why the moved file appeared to need 230 lines
of reformatting. Ruff's config is copied from operator into the root
pyproject.toml with preview set there instead of passed as a flag, so an
editor and CI agree without anyone remembering it. Packages carry no
[tool.ruff] block of their own, because ruff takes the closest config rather
than merging and a local one would quietly override the shared one.

Lockfiles are committed now, and CI syncs with --locked so that a lockfile
which has drifted from its pyproject.toml fails instead of silently
resolving to something else.
---
 .github/workflows/ci.yaml                     |  22 ++-
 .gitignore                                    |   1 -
 README.md                                     |  26 ++-
 ai-failure-notifier/README.md                 |  22 +++
 ai-failure-notifier/pyproject.toml            |  36 ++++
 .../charm_tech_code/ai_failure_notifier.py    |   0
 .../tests}/test_ai_failure_notifier.py        |   0
 ai-failure-notifier/uv.lock                   | 156 ++++++++++++++++++
 pyproject.toml                                |  69 +++++---
 src/charm_tech_code/__init__.py               |  20 ---
 uv.lock                                       |  43 +++++
 11 files changed, 335 insertions(+), 60 deletions(-)
 create mode 100644 ai-failure-notifier/README.md
 create mode 100644 ai-failure-notifier/pyproject.toml
 rename {src => ai-failure-notifier/src}/charm_tech_code/ai_failure_notifier.py (100%)
 rename {tests => ai-failure-notifier/tests}/test_ai_failure_notifier.py (100%)
 create mode 100644 ai-failure-notifier/uv.lock
 delete mode 100644 src/charm_tech_code/__init__.py
 create mode 100644 uv.lock

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index ad1e198..0ec3081 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -11,8 +11,16 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
+        # One entry per tool. Add a directory here when you add a package.
+        package: [ai-failure-notifier]
+        # The versions canonical/operator tests against, since that is where
+        # this code runs.
         python-version: ['3.10', '3.12', '3.14']
+    defaults:
+      run:
+        working-directory: ${{ matrix.package }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
@@ -20,6 +28,9 @@ jobs:
       - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
         with:
           python-version: ${{ matrix.python-version }}
+      # --locked, so that a lockfile which no longer matches its pyproject.toml
+      # fails here rather than silently resolving to something else.
+      - run: uv sync --locked --group unit
       - run: uv run pytest
 
   lint:
@@ -29,9 +40,8 @@ jobs:
         with:
           persist-credentials: false
       - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
-      - run: uvx ruff check .
-      # No `ruff format --check` yet. The moved file is byte-identical to what
-      # is under review in canonical/operator#2663, and the ruff version that
-      # formatted it hugged brackets inside calls where current ruff does not.
-      # Reformatting would put a 230-line diff on a file two people are part
-      # way through reviewing. Worth turning on once that PR lands.
+      # Ruff is pinned in the root dependency group, and its configuration
+      # lives there too, so both run once across every package rather than
+      # per matrix entry.
+      - run: uv run --group lint ruff check .
+      - run: uv run --group lint ruff format --check .
diff --git a/.gitignore b/.gitignore
index 2657f32..e67f161 100644
--- a/.gitignore
+++ b/.gitignore
@@ -219,4 +219,3 @@ __marimo__/
 
 # uv
 .venv/
-uv.lock
diff --git a/README.md b/README.md
index 1317572..91ba797 100644
--- a/README.md
+++ b/README.md
@@ -2,27 +2,39 @@
 
 Shared tooling for the Charm Tech repositories (`operator`, `charmlibs`, `jubilant`, `pebble`, `concierge`, and the rest of the estate).
 
+Each tool is its own package in its own top-level directory, with its own `pyproject.toml`, `src/`, `tests/` and lockfile - the same shape `canonical/charmlibs` uses. Adding a tool means adding a directory, not adding to an existing package, so a tool's dependencies are paid only by the workflows that run that tool.
+
+| directory | what it does |
+|---|---|
+| [`ai-failure-notifier`](ai-failure-notifier) | Triages and enriches the issue opened when a scheduled workflow fails. |
+
 Code here is consumed by workflow YAML in the repository that runs it, pinned by commit SHA:
 
 ```yaml
-run: uvx --from git+https://github.com/canonical/charm-tech-code@<40-char-sha> ai-failure-notifier
+run: uvx --from "git+https://github.com/canonical/charm-tech-code@<40-char-sha>#subdirectory=ai-failure-notifier" ai-failure-notifier
 ```
 
 The point is that the code lives in one place. A tool used by eleven repositories should be fixed once, not eleven times, and the workflow YAML that differs per repository stays in that repository.
 
 There is no release process and nothing is published. The SHA in the `uvx` line is the version, which is the same trust decision every pinned `uses: actions/checkout@<sha>` line in those repositories already makes.
 
-## Tools
+## Configuration
 
-### `ai-failure-notifier`
+Ruff's configuration lives in the root `pyproject.toml` and is copied from `canonical/operator`, so that a file can move between the two repositories without being reformatted. Packages deliberately do not carry their own `[tool.ruff]` block: ruff uses the closest configuration it finds rather than merging, so a local one would silently override the shared one.
 
-Enriches the placeholder issue that a scheduled workflow's failure notifier opens. It reads the failing run's job logs, builds a deterministic failure signature, searches for issues that look like the same failure, and either comments on one or rewrites the placeholder with a real title, body and labels. Without an API key it falls back to a plain notification, so the notifier's "always works" property is not affected by this being unavailable.
-
-See `canonical/operator`'s `.github/workflows/ai-failure-enrich.yaml` for the calling side.
+`preview` is set in configuration rather than passed as `--preview` on the command line, which is how operator's `tox.ini` does it. That way an editor, a hook and CI agree without anyone having to remember the flag. It is load-bearing rather than cosmetic - the preview style hugs brackets inside calls, and without it a good deal of existing code reformats.
 
 ## Developing
 
 ```shell
-uv sync
+cd <package>
+uv sync --group unit
 uv run pytest
 ```
+
+Lint and format run from the root, across every package at once:
+
+```shell
+uv run --group lint ruff check .
+uv run --group lint ruff format --check .
+```
diff --git a/ai-failure-notifier/README.md b/ai-failure-notifier/README.md
new file mode 100644
index 0000000..c1e2d09
--- /dev/null
+++ b/ai-failure-notifier/README.md
@@ -0,0 +1,22 @@
+# ai-failure-notifier
+
+Enriches the placeholder issue that a scheduled workflow's failure notifier opens.
+
+When a scheduled workflow fails, the notifier in the repository opens an issue with a generic title and a link to the failing job. This tool picks that placeholder up, reads the failing run's job logs, reduces them to a deterministic failure signature, searches for issues that look like the same failure, and then either comments on the existing one or rewrites the placeholder with a real title, body and labels.
+
+Without an API key it falls back to a plain notification. That is deliberate: the notifier has to work when everything else is broken, so nothing here is allowed to be a hard dependency of it.
+
+## Running it
+
+```shell
+uvx --from "git+https://github.com/canonical/charm-tech-code@<40-char-sha>#subdirectory=ai-failure-notifier" ai-failure-notifier
+```
+
+It reads its inputs from the environment: `GH_TOKEN`, `REPO`, `RUN_ID`, `WORKFLOW_NAME`, `RUN_URL`, and optionally `OPENROUTER_API_KEY` and `OPENROUTER_MODEL`. See `canonical/operator`'s `.github/workflows/ai-failure-enrich.yaml` for the calling side, including the environment mechanics the key depends on.
+
+## Developing
+
+```shell
+uv sync --group unit
+uv run pytest
+```
diff --git a/ai-failure-notifier/pyproject.toml b/ai-failure-notifier/pyproject.toml
new file mode 100644
index 0000000..37a3021
--- /dev/null
+++ b/ai-failure-notifier/pyproject.toml
@@ -0,0 +1,36 @@
+[project]
+name = "charm-tech-code-ai-failure-notifier"
+version = "0.1.0"
+description = "Triage and enrich the issues opened when a scheduled workflow fails."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "The Charm Tech team at Canonical Ltd."},
+]
+license = "Apache-2.0"
+# Deliberately none. The tool is invoked by `uvx --from git+...` on a GitHub
+# runner, so every dependency added here is paid on every failed scheduled
+# run, in a workflow whose whole point is to still work when things are
+# broken. It talks to GitHub through `gh`, which the runner already has, and
+# to OpenRouter through urllib.
+dependencies = []
+
+[project.scripts]
+ai-failure-notifier = "charm_tech_code.ai_failure_notifier:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/charm_tech_code"]
+
+[dependency-groups]
+unit = ["pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# Ruff configuration is at the root of the monorepo, deliberately not repeated
+# here: ruff uses the closest config it finds rather than merging, so a
+# [tool.ruff] block in this file would silently override the shared one.
diff --git a/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
similarity index 100%
rename from src/charm_tech_code/ai_failure_notifier.py
rename to ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
diff --git a/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
similarity index 100%
rename from tests/test_ai_failure_notifier.py
rename to ai-failure-notifier/tests/test_ai_failure_notifier.py
diff --git a/ai-failure-notifier/uv.lock b/ai-failure-notifier/uv.lock
new file mode 100644
index 0000000..ec3d87c
--- /dev/null
+++ b/ai-failure-notifier/uv.lock
@@ -0,0 +1,156 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "charm-tech-code-ai-failure-notifier"
+version = "0.1.0"
+source = { editable = "." }
+
+[package.dev-dependencies]
+unit = [
+    { name = "pytest" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+unit = [{ name = "pytest" }]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "exceptiongroup"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
+[[package]]
+name = "tomli"
+version = "2.4.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/22/de/48c59722572767841493b26183a0d1cc411d54fd759c5607c4590b6563a6/tomli-2.4.1.tar.gz", hash = "sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f", size = 17543, upload-time = "2026-03-25T20:22:03.828Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/11/db3d5885d8528263d8adc260bb2d28ebf1270b96e98f0e0268d32b8d9900/tomli-2.4.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:f8f0fc26ec2cc2b965b7a3b87cd19c5c6b8c5e5f436b984e85f486d652285c30", size = 154704, upload-time = "2026-03-25T20:21:10.473Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/f7/675db52c7e46064a9aa928885a9b20f4124ecb9bc2e1ce74c9106648d202/tomli-2.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:4ab97e64ccda8756376892c53a72bd1f964e519c77236368527f758fbc36a53a", size = 149454, upload-time = "2026-03-25T20:21:12.036Z" },
+    { url = "https://files.pythonhosted.org/packages/61/71/81c50943cf953efa35bce7646caab3cf457a7d8c030b27cfb40d7235f9ee/tomli-2.4.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96481a5786729fd470164b47cdb3e0e58062a496f455ee41b4403be77cb5a076", size = 237561, upload-time = "2026-03-25T20:21:13.098Z" },
+    { url = "https://files.pythonhosted.org/packages/48/c1/f41d9cb618acccca7df82aaf682f9b49013c9397212cb9f53219e3abac37/tomli-2.4.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5a881ab208c0baf688221f8cecc5401bd291d67e38a1ac884d6736cbcd8247e9", size = 243824, upload-time = "2026-03-25T20:21:14.569Z" },
+    { url = "https://files.pythonhosted.org/packages/22/e4/5a816ecdd1f8ca51fb756ef684b90f2780afc52fc67f987e3c61d800a46d/tomli-2.4.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:47149d5bd38761ac8be13a84864bf0b7b70bc051806bc3669ab1cbc56216b23c", size = 242227, upload-time = "2026-03-25T20:21:15.712Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/49/2b2a0ef529aa6eec245d25f0c703e020a73955ad7edf73e7f54ddc608aa5/tomli-2.4.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:ec9bfaf3ad2df51ace80688143a6a4ebc09a248f6ff781a9945e51937008fcbc", size = 247859, upload-time = "2026-03-25T20:21:17.001Z" },
+    { url = "https://files.pythonhosted.org/packages/83/bd/6c1a630eaca337e1e78c5903104f831bda934c426f9231429396ce3c3467/tomli-2.4.1-cp311-cp311-win32.whl", hash = "sha256:ff2983983d34813c1aeb0fa89091e76c3a22889ee83ab27c5eeb45100560c049", size = 97204, upload-time = "2026-03-25T20:21:18.079Z" },
+    { url = "https://files.pythonhosted.org/packages/42/59/71461df1a885647e10b6bb7802d0b8e66480c61f3f43079e0dcd315b3954/tomli-2.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:5ee18d9ebdb417e384b58fe414e8d6af9f4e7a0ae761519fb50f721de398dd4e", size = 108084, upload-time = "2026-03-25T20:21:18.978Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/83/dceca96142499c069475b790e7913b1044c1a4337e700751f48ed723f883/tomli-2.4.1-cp311-cp311-win_arm64.whl", hash = "sha256:c2541745709bad0264b7d4705ad453b76ccd191e64aa6f0fc66b69a293a45ece", size = 95285, upload-time = "2026-03-25T20:21:20.309Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/ba/42f134a3fe2b370f555f44b1d72feebb94debcab01676bf918d0cb70e9aa/tomli-2.4.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c742f741d58a28940ce01d58f0ab2ea3ced8b12402f162f4d534dfe18ba1cd6a", size = 155924, upload-time = "2026-03-25T20:21:21.626Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/c7/62d7a17c26487ade21c5422b646110f2162f1fcc95980ef7f63e73c68f14/tomli-2.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7f86fd587c4ed9dd76f318225e7d9b29cfc5a9d43de44e5754db8d1128487085", size = 150018, upload-time = "2026-03-25T20:21:23.002Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/05/79d13d7c15f13bdef410bdd49a6485b1c37d28968314eabee452c22a7fda/tomli-2.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ff18e6a727ee0ab0388507b89d1bc6a22b138d1e2fa56d1ad494586d61d2eae9", size = 244948, upload-time = "2026-03-25T20:21:24.04Z" },
+    { url = "https://files.pythonhosted.org/packages/10/90/d62ce007a1c80d0b2c93e02cab211224756240884751b94ca72df8a875ca/tomli-2.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:136443dbd7e1dee43c68ac2694fde36b2849865fa258d39bf822c10e8068eac5", size = 253341, upload-time = "2026-03-25T20:21:25.177Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/7e/caf6496d60152ad4ed09282c1885cca4eea150bfd007da84aea07bcc0a3e/tomli-2.4.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:5e262d41726bc187e69af7825504c933b6794dc3fbd5945e41a79bb14c31f585", size = 248159, upload-time = "2026-03-25T20:21:26.364Z" },
+    { url = "https://files.pythonhosted.org/packages/99/e7/c6f69c3120de34bbd882c6fba7975f3d7a746e9218e56ab46a1bc4b42552/tomli-2.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5cb41aa38891e073ee49d55fbc7839cfdb2bc0e600add13874d048c94aadddd1", size = 253290, upload-time = "2026-03-25T20:21:27.46Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/2f/4a3c322f22c5c66c4b836ec58211641a4067364f5dcdd7b974b4c5da300c/tomli-2.4.1-cp312-cp312-win32.whl", hash = "sha256:da25dc3563bff5965356133435b757a795a17b17d01dbc0f42fb32447ddfd917", size = 98141, upload-time = "2026-03-25T20:21:28.492Z" },
+    { url = "https://files.pythonhosted.org/packages/24/22/4daacd05391b92c55759d55eaee21e1dfaea86ce5c571f10083360adf534/tomli-2.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:52c8ef851d9a240f11a88c003eacb03c31fc1c9c4ec64a99a0f922b93874fda9", size = 108847, upload-time = "2026-03-25T20:21:29.386Z" },
+    { url = "https://files.pythonhosted.org/packages/68/fd/70e768887666ddd9e9f5d85129e84910f2db2796f9096aa02b721a53098d/tomli-2.4.1-cp312-cp312-win_arm64.whl", hash = "sha256:f758f1b9299d059cc3f6546ae2af89670cb1c4d48ea29c3cacc4fe7de3058257", size = 95088, upload-time = "2026-03-25T20:21:30.677Z" },
+    { url = "https://files.pythonhosted.org/packages/07/06/b823a7e818c756d9a7123ba2cda7d07bc2dd32835648d1a7b7b7a05d848d/tomli-2.4.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54", size = 155866, upload-time = "2026-03-25T20:21:31.65Z" },
+    { url = "https://files.pythonhosted.org/packages/14/6f/12645cf7f08e1a20c7eb8c297c6f11d31c1b50f316a7e7e1e1de6e2e7b7e/tomli-2.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a", size = 149887, upload-time = "2026-03-25T20:21:33.028Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/e0/90637574e5e7212c09099c67ad349b04ec4d6020324539297b634a0192b0/tomli-2.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897", size = 243704, upload-time = "2026-03-25T20:21:34.51Z" },
+    { url = "https://files.pythonhosted.org/packages/10/8f/d3ddb16c5a4befdf31a23307f72828686ab2096f068eaf56631e136c1fdd/tomli-2.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f", size = 251628, upload-time = "2026-03-25T20:21:36.012Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/f1/dbeeb9116715abee2485bf0a12d07a8f31af94d71608c171c45f64c0469d/tomli-2.4.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d", size = 247180, upload-time = "2026-03-25T20:21:37.136Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/74/16336ffd19ed4da28a70959f92f506233bd7cfc2332b20bdb01591e8b1d1/tomli-2.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5", size = 251674, upload-time = "2026-03-25T20:21:38.298Z" },
+    { url = "https://files.pythonhosted.org/packages/16/f9/229fa3434c590ddf6c0aa9af64d3af4b752540686cace29e6281e3458469/tomli-2.4.1-cp313-cp313-win32.whl", hash = "sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd", size = 97976, upload-time = "2026-03-25T20:21:39.316Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/1e/71dfd96bcc1c775420cb8befe7a9d35f2e5b1309798f009dca17b7708c1e/tomli-2.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36", size = 108755, upload-time = "2026-03-25T20:21:40.248Z" },
+    { url = "https://files.pythonhosted.org/packages/83/7a/d34f422a021d62420b78f5c538e5b102f62bea616d1d75a13f0a88acb04a/tomli-2.4.1-cp313-cp313-win_arm64.whl", hash = "sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd", size = 95265, upload-time = "2026-03-25T20:21:41.219Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/fb/9a5c8d27dbab540869f7c1f8eb0abb3244189ce780ba9cd73f3770662072/tomli-2.4.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf", size = 155726, upload-time = "2026-03-25T20:21:42.23Z" },
+    { url = "https://files.pythonhosted.org/packages/62/05/d2f816630cc771ad836af54f5001f47a6f611d2d39535364f148b6a92d6b/tomli-2.4.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac", size = 149859, upload-time = "2026-03-25T20:21:43.386Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/48/66341bdb858ad9bd0ceab5a86f90eddab127cf8b046418009f2125630ecb/tomli-2.4.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662", size = 244713, upload-time = "2026-03-25T20:21:44.474Z" },
+    { url = "https://files.pythonhosted.org/packages/df/6d/c5fad00d82b3c7a3ab6189bd4b10e60466f22cfe8a08a9394185c8a8111c/tomli-2.4.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:01f520d4f53ef97964a240a035ec2a869fe1a37dde002b57ebc4417a27ccd853", size = 252084, upload-time = "2026-03-25T20:21:45.62Z" },
+    { url = "https://files.pythonhosted.org/packages/00/71/3a69e86f3eafe8c7a59d008d245888051005bd657760e96d5fbfb0b740c2/tomli-2.4.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7f94b27a62cfad8496c8d2513e1a222dd446f095fca8987fceef261225538a15", size = 247973, upload-time = "2026-03-25T20:21:46.937Z" },
+    { url = "https://files.pythonhosted.org/packages/67/50/361e986652847fec4bd5e4a0208752fbe64689c603c7ae5ea7cb16b1c0ca/tomli-2.4.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ede3e6487c5ef5d28634ba3f31f989030ad6af71edfb0055cbbd14189ff240ba", size = 256223, upload-time = "2026-03-25T20:21:48.467Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/9a/b4173689a9203472e5467217e0154b00e260621caa227b6fa01feab16998/tomli-2.4.1-cp314-cp314-win32.whl", hash = "sha256:3d48a93ee1c9b79c04bb38772ee1b64dcf18ff43085896ea460ca8dec96f35f6", size = 98973, upload-time = "2026-03-25T20:21:49.526Z" },
+    { url = "https://files.pythonhosted.org/packages/14/58/640ac93bf230cd27d002462c9af0d837779f8773bc03dee06b5835208214/tomli-2.4.1-cp314-cp314-win_amd64.whl", hash = "sha256:88dceee75c2c63af144e456745e10101eb67361050196b0b6af5d717254dddf7", size = 109082, upload-time = "2026-03-25T20:21:50.506Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/2f/702d5e05b227401c1068f0d386d79a589bb12bf64c3d2c72ce0631e3bc49/tomli-2.4.1-cp314-cp314-win_arm64.whl", hash = "sha256:b8c198f8c1805dc42708689ed6864951fd2494f924149d3e4bce7710f8eb5232", size = 96490, upload-time = "2026-03-25T20:21:51.474Z" },
+    { url = "https://files.pythonhosted.org/packages/45/4b/b877b05c8ba62927d9865dd980e34a755de541eb65fffba52b4cc495d4d2/tomli-2.4.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:d4d8fe59808a54658fcc0160ecfb1b30f9089906c50b23bcb4c69eddc19ec2b4", size = 164263, upload-time = "2026-03-25T20:21:52.543Z" },
+    { url = "https://files.pythonhosted.org/packages/24/79/6ab420d37a270b89f7195dec5448f79400d9e9c1826df982f3f8e97b24fd/tomli-2.4.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7008df2e7655c495dd12d2a4ad038ff878d4ca4b81fccaf82b714e07eae4402c", size = 160736, upload-time = "2026-03-25T20:21:53.674Z" },
+    { url = "https://files.pythonhosted.org/packages/02/e0/3630057d8eb170310785723ed5adcdfb7d50cb7e6455f85ba8a3deed642b/tomli-2.4.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1d8591993e228b0c930c4bb0db464bdad97b3289fb981255d6c9a41aedc84b2d", size = 270717, upload-time = "2026-03-25T20:21:55.129Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/b4/1613716072e544d1a7891f548d8f9ec6ce2faf42ca65acae01d76ea06bb0/tomli-2.4.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:734e20b57ba95624ecf1841e72b53f6e186355e216e5412de414e3c51e5e3c41", size = 278461, upload-time = "2026-03-25T20:21:56.228Z" },
+    { url = "https://files.pythonhosted.org/packages/05/38/30f541baf6a3f6df77b3df16b01ba319221389e2da59427e221ef417ac0c/tomli-2.4.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8a650c2dbafa08d42e51ba0b62740dae4ecb9338eefa093aa5c78ceb546fcd5c", size = 274855, upload-time = "2026-03-25T20:21:57.653Z" },
+    { url = "https://files.pythonhosted.org/packages/77/a3/ec9dd4fd2c38e98de34223b995a3b34813e6bdadf86c75314c928350ed14/tomli-2.4.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:504aa796fe0569bb43171066009ead363de03675276d2d121ac1a4572397870f", size = 283144, upload-time = "2026-03-25T20:21:59.089Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/be/605a6261cac79fba2ec0c9827e986e00323a1945700969b8ee0b30d85453/tomli-2.4.1-cp314-cp314t-win32.whl", hash = "sha256:b1d22e6e9387bf4739fbe23bfa80e93f6b0373a7f1b96c6227c32bef95a4d7a8", size = 108683, upload-time = "2026-03-25T20:22:00.214Z" },
+    { url = "https://files.pythonhosted.org/packages/12/64/da524626d3b9cc40c168a13da8335fe1c51be12c0a63685cc6db7308daae/tomli-2.4.1-cp314-cp314t-win_amd64.whl", hash = "sha256:2c1c351919aca02858f740c6d33adea0c5deea37f9ecca1cc1ef9e884a619d26", size = 121196, upload-time = "2026-03-25T20:22:01.169Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/cd/e80b62269fc78fc36c9af5a6b89c835baa8af28ff5ad28c7028d60860320/tomli-2.4.1-cp314-cp314t-win_arm64.whl", hash = "sha256:eab21f45c7f66c13f2a9e0e1535309cee140182a9cdae1e041d02e47291e8396", size = 100393, upload-time = "2026-03-25T20:22:02.137Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/61/cceae43728b7de99d9b847560c262873a1f6c98202171fd5ed62640b494b/tomli-2.4.1-py3-none-any.whl", hash = "sha256:0d85819802132122da43cb86656f8d1f8c6587d54ae7dcaf30e90533028b49fe", size = 14583, upload-time = "2026-03-25T20:22:03.012Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
diff --git a/pyproject.toml b/pyproject.toml
index e1a75d4..8a87244 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,39 +1,56 @@
+# Root of the monorepo. This is not itself a package -- each tool lives in its
+# own top-level directory with its own pyproject.toml, src/ and tests/, the
+# same shape canonical/charmlibs uses.
+#
+# What lives here is the configuration every tool should share, so that code
+# moving between this repo and the repos it is used by does not change style
+# on the way.
+
 [project]
-name = "charm-tech-code"
-version = "0.1.0"
-description = "Shared tooling for the Charm Tech repositories."
-readme = "README.md"
-license = "Apache-2.0"
+name = "charm-tech-code-monorepo"
+version = "0.0.0-dev0"
 requires-python = ">=3.10"
-dependencies = []
-
-[project.scripts]
-ai-failure-notifier = "charm_tech_code.ai_failure_notifier:main"
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
 
-[tool.hatch.build.targets.wheel]
-packages = ["src/charm_tech_code"]
+[tool.uv]
+package = false
 
 [dependency-groups]
-dev = ["pytest"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-
+lint = [
+    # Pinned to the version canonical/operator pins, since that is where this
+    # code is used and where it came from.
+    "ruff==0.15.20",
+]
+
+# Ruff configuration, copied from canonical/operator so that a file can move
+# between the two without being reformatted. `preview` is set here rather than
+# passed as `--preview` on the command line (which is how operator's tox does
+# it) so that an editor, a pre-commit hook and CI all agree without anyone
+# having to remember the flag. It is load-bearing, not cosmetic: the preview
+# style hugs brackets inside calls, and without it every such call in
+# ai-failure-notifier reformats.
 [tool.ruff]
 line-length = 99
 target-version = "py310"
-src = ["src", "tests"]
+preview = true
 
 [tool.ruff.format]
 quote-style = "single"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-
-[tool.pyright]
-include = ["src", "tests"]
-pythonVersion = "3.10"
+select = [
+    # Pyflakes
+    "F",
+    # Pycodestyle
+    "E",
+    "W",
+    # isort
+    "I001",
+    # pep8-naming
+    "N",
+    # flake8-builtins
+    "A",
+    # flake8-bugbear
+    "B",
+    # pyupgrade
+    "UP",
+]
diff --git a/src/charm_tech_code/__init__.py b/src/charm_tech_code/__init__.py
deleted file mode 100644
index 9e42e0c..0000000
--- a/src/charm_tech_code/__init__.py
+++ /dev/null
@@ -1,20 +0,0 @@
-# Copyright 2026 Canonical Ltd.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""Shared tooling for the Charm Tech repositories.
-
-Each tool here is consumed by workflow YAML in the repo that uses it, pinned
-by commit SHA, so that the code lives in one place rather than being copied
-into every repository that runs it.
-"""
diff --git a/uv.lock b/uv.lock
new file mode 100644
index 0000000..50f252a
--- /dev/null
+++ b/uv.lock
@@ -0,0 +1,43 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"
+
+[[package]]
+name = "charm-tech-code-monorepo"
+version = "0.0.0.dev0"
+source = { virtual = "." }
+
+[package.dev-dependencies]
+lint = [
+    { name = "ruff" },
+]
+
+[package.metadata]
+
+[package.metadata.requires-dev]
+lint = [{ name = "ruff", specifier = "==0.15.20" }]
+
+[[package]]
+name = "ruff"
+version = "0.15.20"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/dc/35b341fc554ba02f217fc10da57d1a75168cfbcf75b0ef2202176d4c4f2d/ruff-0.15.20.tar.gz", hash = "sha256:1416eb04349192646b54de98f146c4f59afe37d0decfc02c3cbbf396f3a28566", size = 4755489, upload-time = "2026-06-25T17:20:37.578Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/94/d9/2d5014f0253ba541d2061d9fa7193f48e941c8b21bb88a7ff9bbe0bd0596/ruff-0.15.20-py3-none-linux_armv6l.whl", hash = "sha256:00e188c53e499c3c1637f73c91dcf2fb56d576cab76ce1be50a27c4e80e37078", size = 10839665, upload-time = "2026-06-25T17:19:44.702Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/d3/ac1798ba64f670698867fcfc591d50e7e421bef137db564858f619a30fcf/ruff-0.15.20-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:9ebd1fd9b9c95fc0bd7b2761aebec1f030013d2e193a2901b224af68fe47251b", size = 11208649, upload-time = "2026-06-25T17:19:48.787Z" },
+    { url = "https://files.pythonhosted.org/packages/47/47/d3ac899991202095dfcf3d5176be4272642be3cf981a2f1a30f72a2afb95/ruff-0.15.20-py3-none-macosx_11_0_arm64.whl", hash = "sha256:c5b16cdd67ca108185cd36dce98c576350c03b1660a751de725fb049193a0632", size = 10622638, upload-time = "2026-06-25T17:19:51.354Z" },
+    { url = "https://files.pythonhosted.org/packages/33/13/4e043fe30aa94d4ff5213a9881fc296d12960f5971b234a5263fdc225312/ruff-0.15.20-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3413bb3c3d2ca6a8208f1f4809cd2dca3c6de6d0b491c0e70847672bde6e6efd", size = 10984227, upload-time = "2026-06-25T17:19:54.044Z" },
+    { url = "https://files.pythonhosted.org/packages/76/e6/92e7bf40388bc5800073b96564f56264f7e48bfd1a498f5ced6ae6d5a769/ruff-0.15.20-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bd7ec42b3bb3da066488db093308a69c4ac5ee6d2af333a86ba6e2eb2e7dd44b", size = 10622882, upload-time = "2026-06-25T17:19:57.037Z" },
+    { url = "https://files.pythonhosted.org/packages/13/7a/43460be3f24495a3aa46d4b16873e2c4941b3b5f0b00cf88c03b7b94b339/ruff-0.15.20-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e1a36ad0eb77fba9aabfb69ede54de6f376d04ac18ebea022847046d340a8267", size = 11474808, upload-time = "2026-06-25T17:20:00.357Z" },
+    { url = "https://files.pythonhosted.org/packages/27/a0/f37077884873221c6b33b4ab49eb18f9f88e54a16a25a5bca59bef46dd66/ruff-0.15.20-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b6df3b1e4610432f0386dba04d853b5f08cbbc903410c6fcc02f620f05aff53c", size = 12293094, upload-time = "2026-06-25T17:20:03.446Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/74/165545b60256a9704c21ac0ec4a0d07933b320812f9584836c9f4aca4292/ruff-0.15.20-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e89f198a1ea6ef0d727c1cf16088bc91a6cb0ab947dedc966715691647186eae", size = 11526176, upload-time = "2026-06-25T17:20:06.301Z" },
+    { url = "https://files.pythonhosted.org/packages/86/b1/a976a136d40ade83ce743578399865f57001003a409acadc0ecbb3051082/ruff-0.15.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:309809086c2acb67624950a3c8133e80f32d0d3e27106c0cd60ff26657c9f24b", size = 11520767, upload-time = "2026-06-25T17:20:09.191Z" },
+    { url = "https://files.pythonhosted.org/packages/19/0f/f032696cb01c9b54c0263fa393474d7758f1cdc021a01b04e3cbc2500999/ruff-0.15.20-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2d2374caa2f2c2f9e2b7da0a50802cfb8b79f55a9b5e49379f564544fbf56487", size = 11500132, upload-time = "2026-06-25T17:20:13.602Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/f4/51b1a14bc69e8c224b15dab9cce8e99b425e0455d462caa2b3c9be2b6a8e/ruff-0.15.20-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a1ed17b65293e0c2f22fc387bc13198a5de94bf4429589b0ff6946b0feaf21a3", size = 10943828, upload-time = "2026-06-25T17:20:16.635Z" },
+    { url = "https://files.pythonhosted.org/packages/71/4b/fe267640783cd02bf6c5cc290b1df1051be2ec294c678b5c15fe19e52343/ruff-0.15.20-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:f701305e66b38ea6c91882490eb73459796808e4c6362a1b765255e0cdcd4053", size = 10645418, upload-time = "2026-06-25T17:20:19.4Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/c0/a65aa4ec2f5e87a1df32dc3ec1fede434fe3dfd5cbcf3b503cafc676ab54/ruff-0.15.20-py3-none-musllinux_1_2_i686.whl", hash = "sha256:5b9c0c367ad8e5d0d5b5b8537864c469a0a0e55417aadfbeca41fa61333be9f4", size = 11211770, upload-time = "2026-06-25T17:20:22.033Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/a4/0caa331d954ae2723d729d351c989cb4ca8b6077d5c6c2cb6de75e98c041/ruff-0.15.20-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:01cc00dd58f0df339d0e902219dd53990ea99996a0344e5d9cc8d45d5307e460", size = 11618698, upload-time = "2026-06-25T17:20:25.259Z" },
+    { url = "https://files.pythonhosted.org/packages/10/9b/5f14927848d2fd4aa891fd88d883788c5a7baba561c7874732364045708c/ruff-0.15.20-py3-none-win32.whl", hash = "sha256:ed65ef510e43a137207e0f01cfcf998aeddb1aeeda5c9d35023e910284d7cf21", size = 10857322, upload-time = "2026-06-25T17:20:28.612Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/f0/fe47c501f9dea92a26d788ff98bb5d92ed4cb4c88792c5c88af6b697dc8e/ruff-0.15.20-py3-none-win_amd64.whl", hash = "sha256:a525c81c70fb0380344dd1d8745d8cc1c890b7fc94a58d5a07bd8eb9557b8415", size = 11993274, upload-time = "2026-06-25T17:20:31.871Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/2b/9555445e1201d92b3195f45cdb153a0b68f24e0a4273f6e3d5ab46e212bb/ruff-0.15.20-py3-none-win_arm64.whl", hash = "sha256:2f5b2a6d614e8700388806a14996c40fab2c47b819ef57d790a34878858ed9ca", size = 11343498, upload-time = "2026-06-25T17:20:35.03Z" },
+]

From 07fe1110e8d577f94f2a4bb3173485220eafacfb Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 12:22:13 +1200
Subject: [PATCH 05/19] feat: take the issue number from the notifier instead
 of searching for it

Review suggestion on canonical/operator#2663: have the notify job output the
issue it created or commented on, so this script is told which artefact to
upgrade rather than looking it up.

The lookup it replaces existed to work around GitHub's issue search index not
being read-your-writes: the notifier stamps its marker seconds before the
enrich job runs, so a search can read "no marker found" and open a second
issue for a run that already has one. A number passed through the workflow
cannot be stale, so that failure mode is gone rather than defended against.

It does not remove the lookup entirely, which the suggestion allowed for.
Rung zero is a fact about an earlier run of this script, not about what the
notifier just did, so it still has to be looked up - but knowing the issue
narrows that from a scan of the repo's recently updated issues to reading the
one issue we were handed. With no issue passed, from an unmigrated caller or
a notifier that failed before opening anything, the original repo-wide scan
still runs.
---
 .../charm_tech_code/ai_failure_notifier.py    | 47 ++++++++++++++++++-
 .../tests/test_ai_failure_notifier.py         | 42 +++++++++++++++++
 2 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
index 18761af..c803f18 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
@@ -1066,6 +1066,42 @@ def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None,
     return find_run_markers(texts, run_id)
 
 
+def resolve_origin(
+    repo: str, run_id: str, notify_issue: int | None, notify_origin: str | None
+) -> tuple[int | None, str | None, int | None]:
+    """Work out which artefact this run should upgrade.
+
+    Returns the same triple as `find_run_markers`.
+
+    When the notifier tells us the issue it created or commented on, that is
+    authoritative for `origin_issue`/`origin_kind` and we never search for it.
+    That removes the read-your-writes hazard `locate_run_markers` exists to
+    work around: the notifier stamps its marker moments before this job runs,
+    and GitHub's issue *search* index lags, so a marker that has not been
+    indexed yet reads as "no notifier marker found" and main() opens a second
+    issue for a run that already has one. A number passed directly through the
+    workflow cannot be stale.
+
+    Rung zero still needs a lookup, and the notifier's output cannot supply
+    it: "this run id was already fully enriched" is a fact about an *earlier
+    run of this script*, not about what the notifier just did. But knowing the
+    issue narrows that lookup from a scan of the repo's recently-updated
+    issues to reading the one issue we were handed.
+
+    With no `notify_issue` -- the notifier failed, or a caller has not been
+    migrated -- this falls back to the original repo-wide scan, so the script
+    still works when it is not told anything.
+    """
+    if notify_issue is None:
+        return locate_run_markers(repo, run_id)
+
+    texts = [(notify_issue, text) for text in fetch_issue_texts(repo, notify_issue)]
+    enriched_issue, origin_kind, origin_issue = find_run_markers(texts, run_id)
+    # The passed-in values win: a marker we failed to find on the issue does
+    # not make the issue the wrong one.
+    return enriched_issue, notify_origin or origin_kind, notify_issue
+
+
 def search_candidates(
     repo: str, workflow_name: str
 ) -> tuple[list[CandidateIssue], list[CandidateIssue]]:
@@ -1239,16 +1275,23 @@ def main() -> int:
     run_url = os.environ['RUN_URL']
     api_key = os.environ.get('OPENROUTER_API_KEY', '')
     model = os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL
+    # What the notifier did, when it tells us. Both are optional: an
+    # unmigrated caller, or a notifier that failed before it got as far as an
+    # issue, leaves them empty and we go looking instead.
+    notify_issue = int(os.environ['NOTIFY_ISSUE']) if os.environ.get('NOTIFY_ISSUE') else None
+    notify_origin = os.environ.get('NOTIFY_ORIGIN') or None
 
     try:
-        enriched_issue, origin_kind, origin_issue = locate_run_markers(repo, run_id)
+        enriched_issue, origin_kind, origin_issue = resolve_origin(
+            repo, run_id, notify_issue, notify_origin
+        )
     except Exception as exc:  # search API rejection, rate limit, transient 5xx.
         # The marker lookup is the first thing main() does, so an uncaught
         # failure here takes out the whole enrich job and hands every run to
         # the workflow-level plain-fallback -- losing enrichment silently
         # rather than degrading through the script's own fallback path.
         write_step_summary(f'Marker lookup failed ({exc}); treating this run as un-marked.')
-        enriched_issue, origin_kind, origin_issue = None, None, None
+        enriched_issue, origin_kind, origin_issue = None, notify_origin, notify_issue
 
     if enriched_issue is not None:
         # Rung zero: this run id was already fully enriched once -- a re-run of
diff --git a/ai-failure-notifier/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
index fcf5ff4..a50416d 100644
--- a/ai-failure-notifier/tests/test_ai_failure_notifier.py
+++ b/ai-failure-notifier/tests/test_ai_failure_notifier.py
@@ -1229,3 +1229,45 @@ def test_http_error_propagates_so_main_can_fall_back(self):
         with mock.patch.object(afn.urllib.request, 'urlopen', side_effect=error):
             with self.assertRaises(urllib.error.HTTPError):
                 afn.call_openrouter('sys', 'user', 'm', 'k')
+
+
+class ResolveOriginTests(unittest.TestCase):
+    """`notify` hands us the issue it touched; we only go looking without it."""
+
+    def test_passed_issue_is_used_without_any_lookup(self):
+        with (
+            mock.patch.object(afn, 'fetch_issue_texts', return_value=['no markers here']),
+            mock.patch.object(afn, 'locate_run_markers') as locate,
+        ):
+            enriched, kind, origin = afn.resolve_origin('o/r', '123', 4242, 'comment')
+        self.assertEqual((enriched, kind, origin), (None, 'comment', 4242))
+        # The read-your-writes hazard is gone because nothing is searched for.
+        locate.assert_not_called()
+
+    def test_passed_issue_wins_over_a_missing_marker(self):
+        """A marker we cannot find does not make the issue the wrong issue."""
+        with mock.patch.object(afn, 'fetch_issue_texts', return_value=['']):
+            _enriched, kind, origin = afn.resolve_origin('o/r', '123', 77, 'new')
+        self.assertEqual((kind, origin), ('new', 77))
+
+    def test_rung_zero_still_detected_on_the_passed_issue(self):
+        """The notifier cannot tell us this: it is a fact about an earlier
+        run of *this* script, so the narrowed lookup still has to find it."""
+        body = f'<!-- {afn.MARKER_PREFIX}:run=123:sig=abcdef0123456789 -->'
+        with mock.patch.object(afn, 'fetch_issue_texts', return_value=[body]):
+            enriched, _kind, origin = afn.resolve_origin('o/r', '123', 4242, 'new')
+        self.assertEqual((enriched, origin), (4242, 4242))
+
+    def test_rung_zero_ignores_a_marker_for_a_different_run(self):
+        body = f'<!-- {afn.MARKER_PREFIX}:run=999:sig=abcdef0123456789 -->'
+        with mock.patch.object(afn, 'fetch_issue_texts', return_value=[body]):
+            enriched, _kind, _origin = afn.resolve_origin('o/r', '123', 4242, 'new')
+        self.assertIsNone(enriched)
+
+    def test_no_passed_issue_falls_back_to_the_repo_wide_scan(self):
+        """An unmigrated caller, or a notifier that failed before opening an
+        issue, has to keep working."""
+        with mock.patch.object(afn, 'locate_run_markers', return_value=(None, 'new', 9)) as locate:
+            result = afn.resolve_origin('o/r', '123', None, None)
+        self.assertEqual(result, (None, 'new', 9))
+        locate.assert_called_once_with('o/r', '123')

From ff9d61d25d4b3b6cedffbdf03f986f8eaeabdee0 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 12:48:30 +1200
Subject: [PATCH 06/19] refactor: drop the shebang

Review suggestion on canonical/operator#2663, where the choice was between
dropping it and switching to a uv shebang so CI could execute the file
directly. Moving here settles it: this is a module inside an installed
package, reached through the ai-failure-notifier console script, so nothing
executes it by path and the line is dead text. The file was already not
executable.
---
 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
index c803f18..18b6ad9 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-#
 # Copyright 2026 Canonical Ltd.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

From 6e4b128c32aca30f09a4c33e8ce1c23d588c4675 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 12:49:23 +1200
Subject: [PATCH 07/19] docs: correct the comment on the marker-lookup except

Review comment: it was outdated. It justified the try/except by pointing at
the workflow-level fallback job, which was removed earlier in the same review
at the reviewer's suggestion, so it sent a reader looking for a safety net
that no longer exists.

The except is still needed, for the opposite reason: nothing catches this
above us now, so an uncaught failure loses the enrichment outright. Also
notes what the recovery actually does since the notifier started passing its
issue number through.
---
 .../src/charm_tech_code/ai_failure_notifier.py           | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
index 18b6ad9..c35629e 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
@@ -1284,10 +1284,11 @@ def main() -> int:
             repo, run_id, notify_issue, notify_origin
         )
     except Exception as exc:  # search API rejection, rate limit, transient 5xx.
-        # The marker lookup is the first thing main() does, so an uncaught
-        # failure here takes out the whole enrich job and hands every run to
-        # the workflow-level plain-fallback -- losing enrichment silently
-        # rather than degrading through the script's own fallback path.
+        # Nothing catches this above us: there is no workflow-level fallback
+        # job any more, so an uncaught failure here loses the enrichment
+        # outright rather than degrading through the paths below. When the
+        # notifier told us its issue we can still carry on with that; without
+        # it we continue as though the run were un-marked.
         write_step_summary(f'Marker lookup failed ({exc}); treating this run as un-marked.')
         enriched_issue, origin_kind, origin_issue = None, notify_origin, notify_issue
 

From 40d5345302470343e17b5f157c64cbaee4e46f94 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 12:50:41 +1200
Subject: [PATCH 08/19] docs: say what reaching the no-origin branch actually
 means

Review comment guessed correctly that this is where an explicit input would
branch, which is now what happens. That makes the old comment wrong in a
quiet way: "shouldn't happen -- the notifier always stamps a marker" was true
when this depended on finding one by search, but reaching here now means
either an unmigrated caller or a failed lookup, and the first is the normal
state of a repository part way through adopting this.
---
 .../src/charm_tech_code/ai_failure_notifier.py              | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
index c35629e..0c5b9ea 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
@@ -1314,8 +1314,10 @@ def main() -> int:
         return 0
 
     if origin_issue is None:
-        # Shouldn't happen -- the notifier always stamps a marker -- but
-        # don't lose the notification if it does.
+        # Either a caller that has not been migrated to pass the issue
+        # through, or a marker lookup that failed. The first is the normal
+        # state of a repo part way through adopting this, so don't treat it
+        # as an anomaly -- just don't lose the notification.
         write_step_summary(
             'No notifier marker found for this run id; falling back to a plain issue.'
         )

From 2ff214bf578e591d12e26afa5f53364d646fa14b Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 12:55:57 +1200
Subject: [PATCH 09/19] refactor: split the notifier into modules

Asked for in review on canonical/operator#2663: 1500 lines is hard to follow
on GitHub, and the reviewer offered to read it in an IDE instead if we would
rather leave it. Splitting is the better answer, and it is cheap here in a way
it was not in operator - there is no in-flight review of these files to
disturb.

The boundaries are the ones the single file already documented with its
`# --- section ---` banners, plus the I/O half divided by what it talks to:
gh, OpenRouter, the step summary, and applying the result. Largest module is
now 293 lines. `__init__` re-exports every public name, so
`from charm_tech_code import ai_failure_notifier` is unchanged for callers.

Cross-module function calls go through the module rather than importing the
name, so that a test patching `<module>.<name>` reaches every call site
instead of only the definer. Those imports are aliased with a leading
underscore because three module names - envelope, prompt, summary - are also
local variable names in the code.

No assertion changed. The test diff is entirely patch targets moving from
`afn.<name>` to `afn.<module>.<name>`, which is what makes the same 75 tests
evidence that this refactor preserved behaviour.
---
 .../charm_tech_code/ai_failure_notifier.py    | 1505 -----------------
 .../ai_failure_notifier/__init__.py           |  166 ++
 .../ai_failure_notifier/apply.py              |   80 +
 .../ai_failure_notifier/candidates.py         |   71 +
 .../ai_failure_notifier/cli.py                |  287 ++++
 .../ai_failure_notifier/constants.py          |  121 ++
 .../ai_failure_notifier/envelope.py           |  232 +++
 .../ai_failure_notifier/github.py             |  286 ++++
 .../ai_failure_notifier/markers.py            |   94 +
 .../ai_failure_notifier/models.py             |  100 ++
 .../ai_failure_notifier/openrouter.py         |   62 +
 .../ai_failure_notifier/prompt.py             |  240 +++
 .../ai_failure_notifier/signatures.py         |  146 ++
 .../ai_failure_notifier/summary.py            |   35 +
 .../tests/test_ai_failure_notifier.py         |  130 +-
 15 files changed, 1989 insertions(+), 1566 deletions(-)
 delete mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/constants.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/openrouter.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
 create mode 100644 ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/summary.py

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
deleted file mode 100644
index 0c5b9ea..0000000
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier.py
+++ /dev/null
@@ -1,1505 +0,0 @@
-# Copyright 2026 Canonical Ltd.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""ai-failure-notifications enrichment step.
-
-Invoked by `.github/workflows/ai-failure-enrich.yaml` after
-`.github/workflows/notify-scheduled-failure.yaml` (the notifier) has already
-created or commented on a placeholder issue for a failed scheduled workflow
-run. This script:
-
-1. Finds the placeholder the notifier just touched (or, on a same-run
-   re-fire, the issue an earlier run of this script already enriched).
-2. Fetches and parses the failing job logs into a deterministic failure
-   signature.
-3. Builds a small candidate-issue pool (coarse title/body search).
-4. Asks an LLM (via OpenRouter) to decide comment-vs-new and draft the text,
-   validates the response against the envelope schema, and applies it via
-   `gh`.
-5. Falls back to a plain, generic issue/comment (still marker-stamped) if
-   OpenRouter is unreachable, misconfigured, or returns invalid JSON.
-
-The functions above the `--- I/O ---` marker are pure and unit-tested in
-`scripts/test/test_ai_failure_notifier.py`. Everything below it talks to `gh`
-or OpenRouter and is exercised only by mocking in tests.
-"""
-
-from __future__ import annotations
-
-import dataclasses
-import datetime
-import hashlib
-import json
-import os
-import re
-import subprocess
-import sys
-import urllib.request
-from typing import Any, Literal
-
-MARKER_PREFIX = 'ai-failure-notifications'
-DEFAULT_MODEL = 'deepseek/deepseek-chat'  # DeepSeek V3 on OpenRouter.
-CLOSED_CANDIDATE_WINDOW_DAYS = 14
-MAX_CANDIDATES = 3
-# How many recently-updated issues to scan for the notifier's marker. The
-# artefact we are looking for was touched minutes ago, so this only has to
-# cover issue churn in that window; 50 is far more than `operator` sees.
-RECENT_ISSUE_SCAN = 50
-
-# Colour escapes, which Actions logs are full of. Two alternatives, because
-# the logs contain both the real thing and a mangled form where the ESC byte
-# has already been stripped, leaving a bare "[32m".
-ANSI = re.compile(
-    r"""
-    \x1b\[ [0-9;]* [A-Za-z]   # a full escape: ESC [ params letter
-    |
-    \[ \d+ (?:;\d+)* m        # ESC already stripped: [32m, [1;33m
-    """,
-    re.VERBOSE,
-)
-
-# The timestamp Actions prefixes to every log line, for example
-# "2026-07-21T16:17:04.8204062Z ". Stripped before anything else is matched.
-TS = re.compile(
-    r"""
-    ^\d{4}-\d{2}-\d{2}        # date: 2026-07-21
-    T\d{2}:\d{2}:\d{2}        # time: T16:17:04
-    \.\d+Z[ ]                 # fractional seconds, zone, one trailing space
-    """,
-    re.VERBOSE,
-)
-
-# Actions' own annotation for a failing step.
-ERROR_MARKER = re.compile(r'##\[error\]')
-
-# The runner opens every step with "##[group]Run <script>", echoes the whole
-# `run:` block a line at a time, dumps the step's env, and closes with
-# "##[endgroup]". None of that is output: it is the step's own source. A
-# multi-line `run:` therefore puts its every branch into the log, including
-# the ones that did not execute, and parsing it produces failures the run
-# never had.
-#
-# Colour is not a usable signal here -- the runner marks echoed lines cyan-
-# bold, but ANSI above strips that before anything is matched -- so the
-# group boundary is what separates a step's script from its output.
-GROUP_RUN_START = re.compile(r'^##\[group\]Run ')
-GROUP_END = re.compile(r'^##\[endgroup\]')
-
-# A line from pytest's short summary, for example
-# "FAILED tests/integration/test_charm.py::test_deploy - TimeoutError: ...".
-PYTEST_SUMMARY = re.compile(
-    r"""
-    ^(FAILED|ERROR)[ ]         # which of the two pytest reports
-    (\S+?)[ ]-[ ]              # the test id, up to the " - " separator
-    (.+)$                      # the error message, to end of line
-    """,
-    re.VERBOSE,
-)
-
-# The end of pytest's summary section, for example
-# "======== 3 failed, 41 passed, 2 warnings in 512.44s ========".
-PYTEST_SUMMARY_END = re.compile(
-    r"""
-    ={3,}                      # the run of = that brackets the line
-    .*(failed|passed|error)    # and one of pytest's outcome words
-    """,
-    re.VERBOSE,
-)
-
-# A failing Go test, for example "--- FAIL: TestFoo (0.01s)".
-GO_FAIL = re.compile(r'^--- FAIL: (\S+)')
-
-# The last line of a Python traceback: the exception type and its message,
-# for example "KeyError: 'loki/0'". Deliberately narrow -- it must look like an
-# exception class name -- so that arbitrary "word: text" log lines don't match.
-TRACEBACK_END = re.compile(
-    r"""
-    ^([A-Z]                          # exception types start with a capital
-      [A-Za-z_.]*                    # dotted path allowed: ops.pebble.APIError
-      (?:Error|Exception|Warning))   # and conventionally end one of three ways
-    :[ ](.*)$                        # then ": " and the message
-    """,
-    re.VERBOSE,
-)
-
-# Matches markers stamped by either workflow:
-#   notifier:  <!-- ai-failure-notifications:run=123:origin=new -->
-#              <!-- ai-failure-notifications:run=123:origin=comment -->
-#   enricher:  <!-- ai-failure-notifications:run=123:sig=abcdef0123456789 -->
-MARKER_RE = re.compile(
-    r'<!--\s*'
-    + re.escape(MARKER_PREFIX)
-    + r"""
-    :run=(?P<run_id>\d+)
-    (?::origin=(?P<origin>new|comment))?
-    (?::sig=(?P<sig>[0-9a-f]+))?
-    \s*-->
-    """,
-    re.VERBOSE,
-)
-
-
-# --- Structured shapes ---
-#
-# The signature is built here, serialised into the prompt, and hashed for the
-# marker, so its shape is worth pinning down rather than passing dicts around.
-# `dataclasses.asdict` preserves field declaration order, which is what the
-# prompt's JSON ends up in.
-
-
-@dataclasses.dataclass(frozen=True)
-class PytestFailure:
-    """One line of pytest's short summary."""
-
-    kind: str  # "FAILED" or "ERROR" -- pytest reports both here.
-    test: str
-    error: str
-
-
-@dataclasses.dataclass(frozen=True)
-class JobSignature:
-    """What the deterministic parser could extract from one failed job's log."""
-
-    job_id: int
-    job_name: str
-    failed_step: str | None
-    pytest_failures: list[PytestFailure]
-    go_failures: list[str]
-    traceback_top_error: str | None
-    tail_excerpt: list[str]
-
-
-@dataclasses.dataclass(frozen=True)
-class RunSignature:
-    """Every failed job of one run, plus the run's own identifying fields."""
-
-    run_id: str
-    workflow_name: str
-    html_url: str
-    created_at: str
-    jobs: list[JobSignature]
-
-    def as_json(self) -> str:
-        """Render for the prompt, in field declaration order."""
-        return json.dumps(dataclasses.asdict(self), indent=2)
-
-
-@dataclasses.dataclass(frozen=True)
-class FailedJob:
-    """A failed job as listed by `gh run view`, before its log is fetched."""
-
-    id: int
-    name: str
-    failed_step: str | None
-
-
-@dataclasses.dataclass(frozen=True)
-class CandidateIssue:
-    """An existing issue that might already track this failure."""
-
-    number: int
-    title: str
-    body: str | None
-    closed_at: str | None
-
-    @classmethod
-    def from_gh(cls, data: dict[str, Any]) -> CandidateIssue:
-        """Build from one element of `gh issue list --json ...` output."""
-        return cls(
-            number=data['number'],
-            title=data['title'],
-            body=data.get('body'),
-            closed_at=data.get('closedAt'),
-        )
-
-    def excerpt(self) -> str:
-        """The first line of the body, bounded, for the candidate block."""
-        lines = (self.body or '').strip().splitlines()
-        return lines[0][:300] if lines else '(no body)'
-
-
-# --- Signature extraction ---
-
-
-def strip_line(line: str) -> str:
-    """Remove GHA timestamp and ANSI colours."""
-    line = TS.sub('', line, count=1)
-    line = ANSI.sub('', line)
-    return line.rstrip('\r\n')
-
-
-def strip_log(text: str) -> list[str]:
-    """Split a raw job log into output lines, dropping each step's own script.
-
-    Everything between "##[group]Run ..." and "##[endgroup]" is the runner
-    echoing the step's `run:` block and env, not anything the step printed.
-    See GROUP_RUN_START above for why that matters.
-    """
-    lines: list[str] = []
-    in_step_header = False
-    for raw in text.splitlines():
-        line = strip_line(raw)
-        if GROUP_RUN_START.match(line):
-            in_step_header = True
-            continue
-        if in_step_header:
-            in_step_header = not GROUP_END.match(line)
-            continue
-        lines.append(line)
-    return lines
-
-
-def parse_job_log(
-    text: str,
-) -> tuple[list[PytestFailure], list[str], str | None, list[str]]:
-    """Parse one job's raw log text.
-
-    Returns (pytest_failures, go_failures, traceback_top_error, tail_excerpt).
-    """
-    lines = strip_log(text)
-
-    pytest_failures: list[PytestFailure] = []
-    go_failures: list[str] = []
-    in_summary = False
-
-    for line in lines:
-        if 'short test summary info' in line:
-            in_summary = True
-            continue
-        if in_summary:
-            m = PYTEST_SUMMARY.match(line)
-            if m:
-                kind, test, err = m.groups()
-                pytest_failures.append(PytestFailure(kind, test, err.strip()))
-                continue
-            if PYTEST_SUMMARY_END.match(line):
-                in_summary = False
-        m = GO_FAIL.match(line)
-        if m:
-            go_failures.append(m.group(1))
-
-    traceback_top_error: str | None = None
-    for line in reversed(lines):
-        m = TRACEBACK_END.match(line)
-        if m:
-            traceback_top_error = f'{m.group(1)}: {m.group(2).strip()}'
-            break
-
-    error_idx = None
-    for i, line in enumerate(lines):
-        if ERROR_MARKER.search(line):
-            error_idx = i
-            break
-    tail: list[str] = []
-    if error_idx is not None:
-        for line in reversed(lines[:error_idx]):
-            if not line.strip():
-                continue
-            if line.startswith('##[group]') or line.startswith('##[endgroup]'):
-                continue
-            tail.append(line)
-            if len(tail) >= 40:
-                break
-        tail.reverse()
-
-    return pytest_failures, go_failures, traceback_top_error, tail
-
-
-def build_job_signature(
-    job_id: int, job_name: str, failed_step: str | None, log_text: str
-) -> JobSignature:
-    """Parse one job's log into its signature."""
-    pytest_failures, go_failures, traceback_top_error, tail = parse_job_log(log_text)
-    return JobSignature(
-        job_id=job_id,
-        job_name=job_name,
-        failed_step=failed_step,
-        pytest_failures=pytest_failures,
-        go_failures=go_failures,
-        traceback_top_error=traceback_top_error,
-        tail_excerpt=tail,
-    )
-
-
-def build_run_signature(
-    run_id: str, workflow_name: str, html_url: str, created_at: str, jobs: list[JobSignature]
-) -> RunSignature:
-    """Combine per-job signatures into the full run signature."""
-    return RunSignature(
-        run_id=str(run_id),
-        workflow_name=workflow_name,
-        html_url=html_url,
-        created_at=created_at,
-        jobs=jobs,
-    )
-
-
-# --- Marker + signature hashing ---
-
-
-def signature_hash(signature: RunSignature) -> str:
-    """Deterministic short fingerprint of a run signature.
-
-    Used only for the marker's :sig= suffix (not for dedup decisions --
-    that's the LLM's job, guided by the candidate pool).
-    """
-    parts: list[str] = []
-    for job in signature.jobs:
-        parts.extend(failure.test for failure in job.pytest_failures)
-        parts.extend(job.go_failures)
-        if job.traceback_top_error:
-            parts.append(job.traceback_top_error)
-        if job.failed_step:
-            parts.append(job.failed_step)
-    canonical = '\n'.join(sorted(parts)) or signature.workflow_name
-    return hashlib.sha1(canonical.encode('utf-8'), usedforsecurity=False).hexdigest()[:16]
-
-
-# Which artefact the notifier touched: a fresh placeholder issue, or a comment
-# on an issue that already existed. A Literal so a type checker rejects a bad
-# value before it reaches a marker.
-Origin = Literal['new', 'comment']
-
-
-def render_notifier_marker(run_id: str, origin: Origin) -> str:
-    """Render the marker the notifier stamps, telling the enricher what it touched."""
-    return f'<!-- {MARKER_PREFIX}:run={run_id}:origin={origin} -->'
-
-
-def render_enriched_marker(run_id: str, signature: RunSignature) -> str:
-    """Render the marker this script stamps once it has fully processed a run.
-
-    Presence of :sig= is what makes rung zero (find_run_markers) treat a later
-    same-run-id trigger as "already enriched, just note the re-run".
-    """
-    return f'<!-- {MARKER_PREFIX}:run={run_id}:sig={signature_hash(signature)} -->'
-
-
-def find_run_markers(
-    texts: list[tuple[int, str]], run_id: str
-) -> tuple[int | None, str | None, int | None]:
-    """Scan (issue_number, text) pairs for markers belonging to `run_id`.
-
-    Returns (enriched_issue, origin_kind, origin_issue):
-    - enriched_issue: an issue number carrying a :sig= marker for this run
-      (rung zero -- this run was already fully enriched once), else None.
-    - origin_kind / origin_issue: the "new"/"comment" marker the notifier
-      stamped for this run (identifies which artefact to upgrade), else
-      (None, None).
-    """
-    run_id = str(run_id)
-    enriched_issue = None
-    origin_kind = None
-    origin_issue = None
-    for number, text in texts:
-        if not text:
-            continue
-        for match in MARKER_RE.finditer(text):
-            if match['run_id'] != run_id:
-                continue
-            if match['sig']:
-                enriched_issue = number
-            elif match['origin']:
-                origin_kind = match['origin']
-                origin_issue = number
-    return enriched_issue, origin_kind, origin_issue
-
-
-# --- Candidate pool ---
-
-
-def within_window(iso_timestamp: str, now: datetime.datetime, days: int) -> bool:
-    """Return whether `iso_timestamp` falls within `days` of `now`."""
-    ts = datetime.datetime.fromisoformat(iso_timestamp.replace('Z', '+00:00'))
-    return now - ts <= datetime.timedelta(days=days)
-
-
-def build_candidates_block(
-    open_issues: list[CandidateIssue],
-    closed_issues: list[CandidateIssue],
-    now: datetime.datetime,
-) -> str:
-    """Render the {{CANDIDATES_BLOCK}} the prompt expects.
-
-    Up to MAX_CANDIDATES entries: open issues first, then recently-closed
-    issues (<=14 days) filling any remaining slots, explicitly labelled as
-    closed so the LLM never auto-treats one as a strong match. Calibration on
-    past scheduled failures found a closed issue can corroborate a match but
-    should never be enough to dedupe against on its own.
-    """
-    entries: list[str] = []
-    for issue in open_issues:
-        if len(entries) >= MAX_CANDIDATES:
-            break
-        entries.append(f'- **#{issue.number} — {issue.title}** (open)\n  > {issue.excerpt()}')
-
-    recent_closed = [
-        i
-        for i in closed_issues
-        if i.closed_at and within_window(i.closed_at, now, CLOSED_CANDIDATE_WINDOW_DAYS)
-    ]
-    for issue in recent_closed:
-        if len(entries) >= MAX_CANDIDATES:
-            break
-        entries.append(
-            f'- **#{issue.number} — {issue.title}** (closed {issue.closed_at} -- '
-            f'recently closed; treat as at most a medium-confidence match)\n  > {issue.excerpt()}'
-        )
-
-    if not entries:
-        return '(no open issues found for this workflow)'
-    return '\n'.join(entries)
-
-
-# --- Prompt building ---
-
-SYSTEM_PROMPT = """\
-You are the enrichment step of an internal CI failure-triage bot for the
-Canonical Charm Tech team. A scheduled GitHub Actions workflow just failed.
-A separate deterministic parser has already extracted a structured failure
-signature from the run's logs -- you do not have repository access, log
-access, or internet access beyond what is given to you in this message.
-Work only from the signature JSON and candidate issues you're given.
-
-Your job: decide whether this failure is a new occurrence of an
-already-tracked problem (comment on the existing issue) or something not
-currently tracked (open a new issue), and draft the text for whichever
-artefact you choose. Output ONLY the JSON envelope described below -- no
-prose before or after it, no markdown code fences around it.
-
-You are reporting, not fixing. Never propose a fix, a patch, a diff, a
-workaround, a configuration change, a retry, a next step, or anything else
-that tells a reader what to do about the failure -- not as a section, not
-as a sentence, not as an aside, however confident you are and however
-obvious it looks. Deciding what to do about a failure is someone else's
-job, and a wrong suggestion from you is worse than none, because it
-anchors whoever picks the issue up. Describe what failed and, where the
-signature genuinely supports it, why. Then stop.
-
-## Reading the signature
-
-The signature has one entry per failed job in `jobs[]`. Each entry may
-carry, in decreasing order of how much you should trust it:
-
-1. `pytest_failures[]` -- `{kind, test, error}` triples parsed from
-   pytest's "short test summary info" block. `test` is a real pytest node
-   id; `error` is the tail of that summary line and CAN BE TRUNCATED by
-   pytest itself (it cuts long messages short, for example
-   "PendingDeprecat..."). If an `error` string ends in `...`, treat it
-   as unreliable for anything beyond "this test failed" -- do not quote it
-   as the root cause, do not put the truncated fragment in a title. Look
-   at `traceback_top_error` and `tail_excerpt` for that job instead; if
-   they don't resolve it either, describe the failure by test name only
-   and say the specific assertion text is unavailable.
-2. `traceback_top_error` -- the last `<ErrorClass>: <message>` line found
-   anywhere in the job's log. Usually the real exception, but it is a
-   last-line heuristic: on jobs where cleanup code raises its own warning
-   after the real failure (a `ResourceWarning` from tempfile cleanup is
-   the known example), this field can point at the cleanup noise instead
-   of the actual cause. If `traceback_top_error` names a `Warning` class
-   while `pytest_failures[]` for the same job names an `Error` class,
-   trust the `pytest_failures[]` entry for what actually failed and treat
-   `traceback_top_error` as noise.
-3. `tail_excerpt[]` -- the last ~40 non-empty log lines before the job's
-   first `##[error]` marker. This is what's left when neither of the
-   above fired. Sometimes it contains an unambiguous plain-text failure
-   (for example a Go `panic:`, a shell command's final non-zero-exit message, an
-   infra tool's own `level=ERROR msg="..."` line) -- if so, use it. Other
-   times it shows the *shape* of a timeout or an in-progress hook without
-   ever stating what actually broke. Do not guess a specific root cause
-   from an inconclusive `tail_excerpt`. It is fine, and preferred, to say
-   plainly that the cause isn't visible in the available log excerpt.
-
-A job with no `pytest_failures`, no `traceback_top_error`, and a
-`tail_excerpt` that never names an exception, an error code, or an
-explicit failure message (only status-transition noise) is very likely an
-**infrastructural** failure (bootstrap, provisioning, network) rather than
-a test regression, PROVIDED the excerpt at least shows a concrete
-infra-level error. Say so explicitly -- title and body should make clear
-this is "infrastructure failing before tests could run" language, not
-"test X failed" language, and do not name a specific test as the culprit.
-
-If even that infra-level signal is missing or the excerpt is genuinely
-inconclusive, do not invent a specific-sounding title. Use a plain, honest
-title that names the workflow and says the cause is unclear from the log
-excerpt, set "confidence": "low", and say in `dedup_reason` what
-information would be needed to do better. Never fabricate a
-plausible-sounding cause to fill the gap.
-
-A run can have multiple failed jobs with different signatures. Handle this
-as follows:
-
-- If all failed jobs share essentially the same signature, treat it as one
-  failure and write one title/body for it, noting how many jobs it hit.
-- If failed jobs split into distinct signatures, decide whether one is
-  clearly the dominant, actionable story, with others being a smaller
-  number of already-familiar, separately-tracked issues riding along. If
-  so, make the dominant one the subject of `title`/`action`, and mention
-  the others in `body` as a secondary note plus in `dedup_reason`.
-- If failed jobs are multiple genuinely distinct, comparably-important
-  problems with no dominant one, use a title naming the workflow and the
-  count/spread of distinct causes and list each in `body` as its own
-  bullet. Don't pick one arbitrarily and bury the rest.
-
-## Handling multiple independent failures (`also`)
-
-When a run has a dominant story plus one or two secondary failures that
-have distinct signatures from the dominant one AND would either match a
-different existing tracked issue or themselves be dominant enough to
-warrant their own artefact if seen alone, emit an `also` array on the
-envelope with one entry per secondary. Each `also[i]` is a self-contained
-decision (its own `action`, its own `target_issue`/`title`, its own
-`confidence`, its own `dedup_reason`).
-
-Do not use `also` to split a single failure across two entries; do not
-nest `also` inside an `also` entry; cap: 2 `also` entries per envelope.
-
-## Body structure (for `action: "new"`)
-
-Use this shape, adapting to how many distinct failures you're describing:
-
-```
-## Summary
-<one or two sentences: what broke, at what scope>
-
-## Failures
-- **<job name>**: <headline error, or "infrastructure failure -- <what>",
-  or "cause unclear from the available log excerpt">
-  (omit this section entirely if there's exactly one failing job)
-
-## Likely root cause
-<ONLY include this section if the signature actually supports a specific
-hypothesis. Omit it entirely otherwise -- expected on roughly half the
-signatures you'll see. Describe the cause only; do not carry on into what
-should be done about it.>
-```
-
-Do not add sections beyond these. In particular there is no "suggested
-fix", "next steps", "workaround" or "recommendation" section, and none may
-be added.
-
-For `action: "comment"`, keep the comment short: what matches the existing
-issue (or what's new/different), and nothing else.
-
-## Deciding comment vs new
-
-You are given up to three candidate existing issues (title + excerpt), already
-pre-filtered to the same workflow by a coarser deterministic search. Some
-candidates may be marked "(closed ...)" -- these are recently-closed
-issues included for context only; never target a closed issue with
-`action: "comment"`, and never let a closed candidate alone justify
-`confidence: "high"`.
-
-- **Strong** -- at least one `pytest_failures[].test` (or, for
-  infra/tail-only failures, the same `failed_step` plus the same concrete
-  error text) matches an OPEN candidate, AND the top error class matches
-  too -> `action: "comment"`, `confidence: "high"`.
-- **Medium** -- same workflow and same `failed_step`, or same top error
-  class, but the specific test/error text has drifted, OR the only match
-  is a recently-closed candidate -> `action: "comment"` (target the open
-  issue only; if the only match is closed, use `action: "new"` instead and
-  mention the closed issue in `dedup_reason`), `confidence: "medium"`, and
-  say the drift explicitly in `body` and `dedup_reason`.
-- **Weak** -- only the workflow name matches, or only a vague thematic
-  overlap -- this is not a dedup match. `action: "new"`.
-
-Do not comment on a candidate just because one exists for the same
-workflow -- check whether the *signature* actually matches.
-
-## Labels and issue type
-
-The repository has a fixed, centrally-managed label set. You may only use
-labels from this list, and a label that does not exist in the repository is
-dropped before the issue is created, so inventing one achieves nothing:
-
-- `tests` -- the failure is in the tests or the test harness. This is the
-  common case for a failing integration or unit workflow.
-- `docs` -- the failure is in documentation building, linting or link
-  checking, or in a workflow that maintains a doc.
-- `performance` -- only where the failure *is* a performance result, such
-  as a benchmark regression or a timing threshold. Not for an ordinary
-  timeout, which is usually a hang or an infrastructure problem.
-- `small item` -- only where the signature makes it obvious the work is
-  trivial. Prefer omitting it: you cannot see the code, so you are usually
-  not in a position to judge size.
-
-An empty `labels` list is a perfectly good answer. Use it whenever none of
-the above clearly applies, rather than reaching for the nearest one.
-
-`issue_type` is "bug" when you're reasonably sure this is a defect. Use
-`null` when genuinely unsure -- this is normal and expected for
-low-confidence signatures, not an edge case.
-
-## Never
-
-- Never suggest a fix or a remedy of any kind. See "You are reporting, not
-  fixing" above; this is the constraint most easily broken by accident,
-  usually as a closing sentence offering a next step.
-- Never invent a root cause, a PR number, or a file/line that isn't
-  directly supported by the signature JSON you were given.
-- Never use a label that isn't in the list above.
-- Never output anything except the single JSON envelope object.
-"""
-
-USER_PROMPT_TEMPLATE = """\
-Workflow: {workflow_name}
-Run: {run_url}
-
-## Extracted failure signature (deterministic parser output, JSON)
-
-{signature_json}
-
-## Candidate existing open issues (same workflow, pre-filtered by title;
-## may include recently-closed issues explicitly marked as such; may be
-## empty)
-
-{candidates_block}
-
-Produce the JSON envelope now.
-"""
-
-
-def build_prompt(
-    workflow_name: str, run_url: str, signature: RunSignature, candidates_block: str
-) -> tuple[str, str]:
-    """Render the (system, user) prompt pair for the OpenRouter call."""
-    user = USER_PROMPT_TEMPLATE.format(
-        workflow_name=workflow_name,
-        run_url=run_url,
-        signature_json=signature.as_json(),
-        candidates_block=candidates_block,
-    )
-    return SYSTEM_PROMPT, user
-
-
-# --- Envelope schema validation (hand-rolled -- deliberately not the
-# `jsonschema` package, so the script keeps needing nothing outside the stdlib.
-# Mirrors ENVELOPE_JSON_SCHEMA below, which is what OpenRouter is asked to
-# conform to; this re-checks it on the applier side.) ---
-
-_ENTRY_COMMON_REQUIRED = ('action', 'body', 'dedup_reason', 'confidence')
-_ENTRY_KNOWN_KEYS = {
-    'action',
-    'body',
-    'dedup_reason',
-    'confidence',
-    'title',
-    'labels',
-    'issue_type',
-    'target_issue',
-}
-
-
-def validate_entry(entry: Any, *, path: str, allow_also: bool = False) -> list[str]:
-    """Validate one envelope entry (top-level or an `also[i]`) against the schema.
-
-    `also` is only legal on the top-level envelope, so the caller says whether
-    this is that. Without it the top-level check rejected every envelope that
-    carried `also` -- which the model emits routinely, since the schema it is
-    given declares the field.
-    """
-    errors: list[str] = []
-    if not isinstance(entry, dict):
-        return [f'{path}: expected an object, got {type(entry).__name__}']
-
-    for field in _ENTRY_COMMON_REQUIRED:
-        if field not in entry:
-            errors.append(f"{path}: missing required field '{field}'")
-
-    known = _ENTRY_KNOWN_KEYS | {'also'} if allow_also else _ENTRY_KNOWN_KEYS
-    unknown = set(entry) - known
-    if unknown:
-        errors.append(f'{path}: unknown field(s) {sorted(unknown)}')
-
-    action = entry.get('action')
-    if action not in ('comment', 'new'):
-        errors.append(f"{path}.action: must be 'comment' or 'new', got {action!r}")
-        return errors  # can't check action-conditional fields without a valid action
-
-    if not isinstance(entry.get('body'), str) or not entry.get('body'):
-        errors.append(f'{path}.body: must be a non-empty string')
-    if not isinstance(entry.get('dedup_reason'), str) or not entry.get('dedup_reason'):
-        errors.append(f'{path}.dedup_reason: must be a non-empty string')
-    if entry.get('confidence') not in ('high', 'medium', 'low'):
-        errors.append(
-            f'{path}.confidence: must be one of high/medium/low, got {entry.get("confidence")!r}'
-        )
-
-    # A field present but null counts as absent. The schema sent to OpenRouter
-    # is `strict`, so models routinely return every declared property and use
-    # null for the ones that do not apply to the action they chose; rejecting on
-    # mere presence threw away otherwise good output.
-    if action == 'new':
-        for field in ('title', 'labels', 'issue_type'):
-            if field not in entry:
-                errors.append(f"{path}: action='new' requires '{field}'")
-        if entry.get('target_issue') is not None:
-            errors.append(f"{path}: action='new' must not include 'target_issue'")
-        labels = entry.get('labels')
-        if labels is not None and (
-            not isinstance(labels, list) or not all(isinstance(x, str) for x in labels)
-        ):
-            errors.append(f'{path}.labels: must be an array of strings')
-        if 'issue_type' in entry and not (
-            entry['issue_type'] is None or isinstance(entry['issue_type'], str)
-        ):
-            errors.append(f'{path}.issue_type: must be a string or null')
-    else:  # comment
-        if 'target_issue' not in entry:
-            errors.append(f"{path}: action='comment' requires 'target_issue'")
-        elif not isinstance(entry['target_issue'], int) or entry['target_issue'] < 1:
-            errors.append(f'{path}.target_issue: must be a positive integer')
-        for field in ('title', 'labels', 'issue_type'):
-            if entry.get(field) is not None:
-                errors.append(f"{path}: action='comment' must not include '{field}'")
-
-    return errors
-
-
-# Fields that only mean something for one of the two actions. The model is
-# given a `strict` schema, so it tends to return every declared property and
-# fill in the ones that do not apply to the action it chose. Those are dropped
-# rather than treated as an error: we would not act on them either way, and
-# rejecting the envelope threw away a usable body and fell back to the plain
-# notice.
-_ACTION_ONLY_FIELDS = {
-    'comment': ('title', 'labels', 'issue_type'),
-    'new': ('target_issue',),
-}
-
-
-def drop_inapplicable_fields(entry: Any) -> tuple[Any, list[str]]:
-    """Strip fields that do not apply to `entry`'s action; report what went."""
-    if not isinstance(entry, dict):
-        return entry, []
-    fields = _ACTION_ONLY_FIELDS.get(entry.get('action'))
-    if not fields:
-        return entry, []
-    dropped = [f for f in fields if f in entry]
-    if not dropped:
-        return entry, []
-    return {k: v for k, v in entry.items() if k not in dropped}, dropped
-
-
-def normalise_envelope(envelope: Any) -> tuple[Any, list[str]]:
-    """Drop inapplicable fields from the envelope and each `also` entry."""
-    if not isinstance(envelope, dict):
-        return envelope, []
-    cleaned, dropped = drop_inapplicable_fields(envelope)
-    notes = [f'envelope: {f}' for f in dropped]
-    also = cleaned.get('also')
-    if isinstance(also, list):
-        entries: list[Any] = []
-        for i, entry in enumerate(also):
-            entry, entry_dropped = drop_inapplicable_fields(entry)
-            notes += [f'envelope.also[{i}]: {f}' for f in entry_dropped]
-            entries.append(entry)
-        cleaned = {**cleaned, 'also': entries}
-    return cleaned, notes
-
-
-def validate_envelope(envelope: Any) -> list[str]:
-    """Validate a top-level envelope (may carry `also`).
-
-    Returns a list of human-readable errors; empty list means valid.
-    """
-    if not isinstance(envelope, dict):
-        return ['envelope: expected a JSON object']
-
-    errors = validate_entry(envelope, path='envelope', allow_also=True)
-
-    also = envelope.get('also')
-    if also is not None:
-        if not isinstance(also, list) or len(also) > 2:
-            errors.append('envelope.also: must be an array of at most two entries')
-        else:
-            for i, entry in enumerate(also):
-                if isinstance(entry, dict) and 'also' in entry:
-                    errors.append(f"envelope.also[{i}]: nested 'also' is not allowed")
-                errors.extend(validate_entry(entry, path=f'envelope.also[{i}]'))
-
-    return errors
-
-
-ENVELOPE_JSON_SCHEMA = {
-    '$schema': 'https://json-schema.org/draft/2020-12/schema',
-    'title': 'ai-failure-notifications envelope',
-    'type': 'object',
-    'required': ['action', 'body', 'dedup_reason', 'confidence'],
-    'properties': {
-        'action': {'enum': ['comment', 'new']},
-        'body': {'type': 'string', 'minLength': 1},
-        'dedup_reason': {'type': 'string', 'minLength': 1},
-        'confidence': {'enum': ['high', 'medium', 'low']},
-        'title': {'type': 'string', 'minLength': 1},
-        'labels': {'type': 'array', 'items': {'type': 'string'}},
-        'issue_type': {'type': ['string', 'null']},
-        'target_issue': {'type': 'integer', 'minimum': 1},
-        'also': {'type': 'array', 'maxItems': 2, 'items': {'$ref': '#/$defs/envelopeEntry'}},
-    },
-    'additionalProperties': False,
-    'allOf': [{'$ref': '#/$defs/actionConditionals'}],
-    '$defs': {
-        'actionConditionals': {
-            'allOf': [
-                {
-                    'if': {'properties': {'action': {'const': 'new'}}},
-                    'then': {
-                        'required': ['title', 'labels', 'issue_type'],
-                        'not': {'required': ['target_issue']},
-                        'properties': {'labels': {'type': 'array', 'items': {'type': 'string'}}},
-                    },
-                },
-                {
-                    'if': {'properties': {'action': {'const': 'comment'}}},
-                    'then': {
-                        'required': ['target_issue'],
-                        'not': {
-                            'anyOf': [
-                                {'required': ['title']},
-                                {'required': ['labels']},
-                                {'required': ['issue_type']},
-                            ]
-                        },
-                    },
-                },
-            ]
-        },
-        'envelopeEntry': {
-            'type': 'object',
-            'required': ['action', 'body', 'dedup_reason', 'confidence'],
-            'properties': {
-                'action': {'enum': ['comment', 'new']},
-                'body': {'type': 'string', 'minLength': 1},
-                'dedup_reason': {'type': 'string', 'minLength': 1},
-                'confidence': {'enum': ['high', 'medium', 'low']},
-                'title': {'type': 'string', 'minLength': 1},
-                'labels': {'type': 'array', 'items': {'type': 'string'}},
-                'issue_type': {'type': ['string', 'null']},
-                'target_issue': {'type': 'integer', 'minimum': 1},
-            },
-            'additionalProperties': False,
-            'allOf': [{'$ref': '#/$defs/actionConditionals'}],
-        },
-    },
-}
-
-
-# --- I/O ---
-
-
-def gh(*args: str, check: bool = True) -> subprocess.CompletedProcess:
-    """Run a `gh` subcommand, returning the completed process."""
-    # S607: `gh` is deliberately called by name, resolved from the runner's PATH.
-    return subprocess.run(['gh', *args], text=True, capture_output=True, check=check)  # noqa: S607
-
-
-def gh_json(*args: str) -> Any:
-    """Run a `gh ... --json ...` subcommand and parse its stdout as JSON."""
-    result = gh(*args)
-    return json.loads(result.stdout) if result.stdout.strip() else None
-
-
-def fetch_failed_jobs(repo: str, run_id: str) -> list[FailedJob]:
-    """List the failed jobs of a run, each with its id, name, and failed step."""
-    data = gh_json('run', 'view', str(run_id), '--repo', repo, '--json', 'jobs') or {}
-    failed: list[FailedJob] = []
-    for job in data.get('jobs', []):
-        if job.get('conclusion') != 'failure':
-            continue
-        failed_step = None
-        for step in job.get('steps') or []:
-            if step.get('conclusion') == 'failure':
-                failed_step = step.get('name')
-                break
-        failed.append(FailedJob(id=job['databaseId'], name=job['name'], failed_step=failed_step))
-    return failed
-
-
-def fetch_job_log(repo: str, run_id: str, job_id: int) -> str:
-    """Fetch one job's full log text.
-
-    Uses the REST logs endpoint rather than `gh run view --log`: the latter
-    exits 0 with empty stdout on some `gh` builds (reproduced on 2.45.0), which
-    silently degrades the extracted signature to nothing. An empty log here is
-    reported rather than swallowed.
-
-    `--allow-escape-sequences` is not optional. From gh 2.9x, `gh api` refuses
-    to write a response containing terminal escapes -- "the response contains
-    terminal escape sequences; pass --allow-escape-sequences to output it
-    anyway" -- and returns nothing at all. Actions logs are full of them; ANSI
-    above exists to strip them. Runners carry a gh new enough to refuse (2.97.0
-    when this was measured, in fork run 32673538357), so without the flag every
-    fetch comes back empty and the signature degrades to the job name.
-
-    Older builds have no such check and no such flag, and reject it as unknown
-    rather than ignoring it, so those retry without.
-    """
-    endpoint = f'repos/{repo}/actions/jobs/{job_id}/logs'
-    result = gh('api', endpoint, '--allow-escape-sequences', check=False)
-    if 'unknown flag' in (result.stderr or ''):
-        result = gh('api', endpoint, check=False)
-    if not result.stdout.strip():
-        # `gh` puts the status on stderr ("gh: Not Found (HTTP 404)"), and the
-        # exit code alone is 1 for all of them. Without the status there is no
-        # telling a log that is not ready yet from a token that has lost
-        # `actions: read`, and the two want opposite fixes.
-        detail = ' '.join((result.stderr or '').split())[:200] or 'no stderr'
-        write_step_summary(
-            f'Warning: no log text for job {job_id} of run {run_id} '
-            f'(gh exit {result.returncode}: {detail}); '
-            f'signature will be based on the job name alone.'
-        )
-    return result.stdout
-
-
-def fetch_run_meta(repo: str, run_id: str) -> dict[str, str]:
-    """Fetch a run's display metadata (title, workflow name, url, createdAt)."""
-    return (
-        gh_json(
-            'run',
-            'view',
-            str(run_id),
-            '--repo',
-            repo,
-            '--json',
-            'displayTitle,workflowName,url,createdAt',
-        )
-        or {}
-    )
-
-
-def search_issue_numbers(repo: str, query_text: str) -> list[int]:
-    """Search issues (any state) in `repo` for `query_text`, return issue numbers."""
-    # The repo must be passed as `--repo`, not folded into the positional query.
-    # `gh search issues` quotes each positional argument as a single search
-    # keyword, so `repo:owner/name "text"` becomes the literal keyword
-    # `repo:"owner/name \"text\""` and GitHub rejects it as an invalid query.
-    data = (
-        gh_json(
-            'search', 'issues', '--repo', repo, '--limit', '10', '--json', 'number', query_text
-        )
-        or []
-    )
-    return [item['number'] for item in data]
-
-
-def fetch_issue_texts(repo: str, number: int) -> list[str]:
-    """Fetch an issue's body plus all comment bodies, for marker scanning."""
-    data = gh_json('issue', 'view', str(number), '--repo', repo, '--json', 'body,comments') or {}
-    texts = [data.get('body') or '']
-    for c in data.get('comments') or []:
-        texts.append(c.get('body') or '')
-    return texts
-
-
-def recent_issue_texts(repo: str, limit: int = RECENT_ISSUE_SCAN) -> list[tuple[int, str]]:
-    """Return (number, text) pairs for the `limit` most recently updated issues.
-
-    Bodies and comment bodies both, since a notifier marker with
-    `origin=comment` lives in a comment rather than the body.
-    """
-    data = (
-        gh_json(
-            'issue',
-            'list',
-            '--repo',
-            repo,
-            '--state',
-            'all',
-            '--limit',
-            str(limit),
-            '--json',
-            'number,body,comments',
-        )
-        or []
-    )
-    texts: list[tuple[int, str]] = []
-    for issue in data:
-        number = issue['number']
-        texts.append((number, issue.get('body') or ''))
-        for comment in issue.get('comments') or []:
-            texts.append((number, comment.get('body') or ''))
-    return texts
-
-
-def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None, int | None]:
-    """Find the markers belonging to `run_id` and classify them.
-
-    Scans the most recently updated issues first, and only falls back to
-    `gh search issues` if that finds nothing.
-
-    The ordering matters, and is the whole point of doing it this way. The
-    notifier stamps its marker moments before this workflow runs, and GitHub's
-    issue *search* index is not read-your-writes -- a marker that has not been
-    indexed yet reads as "no notifier marker found", and main() responds by
-    opening a *second* issue for a run that already has one. The issue *list*
-    endpoint has no such lag, and the artefact the notifier just touched is by
-    construction among the most recently updated issues in the repo.
-
-    Search remains as a fallback for the one case the list cannot cover: a repo
-    busy enough that more than `RECENT_ISSUE_SCAN` issues were updated in
-    between, where a stale index still beats no lookup at all.
-    """
-    markers = find_run_markers(recent_issue_texts(repo), run_id)
-    if markers != (None, None, None):
-        return markers
-
-    hits = search_issue_numbers(repo, f'{MARKER_PREFIX}:run={run_id}')
-    texts: list[tuple[int, str]] = []
-    for number in hits:
-        for text in fetch_issue_texts(repo, number):
-            texts.append((number, text))
-    return find_run_markers(texts, run_id)
-
-
-def resolve_origin(
-    repo: str, run_id: str, notify_issue: int | None, notify_origin: str | None
-) -> tuple[int | None, str | None, int | None]:
-    """Work out which artefact this run should upgrade.
-
-    Returns the same triple as `find_run_markers`.
-
-    When the notifier tells us the issue it created or commented on, that is
-    authoritative for `origin_issue`/`origin_kind` and we never search for it.
-    That removes the read-your-writes hazard `locate_run_markers` exists to
-    work around: the notifier stamps its marker moments before this job runs,
-    and GitHub's issue *search* index lags, so a marker that has not been
-    indexed yet reads as "no notifier marker found" and main() opens a second
-    issue for a run that already has one. A number passed directly through the
-    workflow cannot be stale.
-
-    Rung zero still needs a lookup, and the notifier's output cannot supply
-    it: "this run id was already fully enriched" is a fact about an *earlier
-    run of this script*, not about what the notifier just did. But knowing the
-    issue narrows that lookup from a scan of the repo's recently-updated
-    issues to reading the one issue we were handed.
-
-    With no `notify_issue` -- the notifier failed, or a caller has not been
-    migrated -- this falls back to the original repo-wide scan, so the script
-    still works when it is not told anything.
-    """
-    if notify_issue is None:
-        return locate_run_markers(repo, run_id)
-
-    texts = [(notify_issue, text) for text in fetch_issue_texts(repo, notify_issue)]
-    enriched_issue, origin_kind, origin_issue = find_run_markers(texts, run_id)
-    # The passed-in values win: a marker we failed to find on the issue does
-    # not make the issue the wrong one.
-    return enriched_issue, notify_origin or origin_kind, notify_issue
-
-
-def search_candidates(
-    repo: str, workflow_name: str
-) -> tuple[list[CandidateIssue], list[CandidateIssue]]:
-    """Coarse candidate search: open and closed issues matching the workflow name."""
-    fields = 'number,title,body,createdAt,closedAt'
-    open_issues = (
-        gh_json(
-            'issue',
-            'list',
-            '--repo',
-            repo,
-            '--state',
-            'open',
-            '--search',
-            f'"{workflow_name}"',
-            '--json',
-            fields,
-            '--limit',
-            '20',
-        )
-        or []
-    )
-    closed_issues = (
-        gh_json(
-            'issue',
-            'list',
-            '--repo',
-            repo,
-            '--state',
-            'closed',
-            '--search',
-            f'"{workflow_name}"',
-            '--json',
-            fields,
-            '--limit',
-            '20',
-        )
-        or []
-    )
-    return (
-        [CandidateIssue.from_gh(i) for i in open_issues],
-        [CandidateIssue.from_gh(i) for i in closed_issues],
-    )
-
-
-def existing_labels(repo: str) -> set[str]:
-    """Return the set of label names that already exist in `repo`."""
-    data = gh_json('label', 'list', '--repo', repo, '--json', 'name', '--limit', '100') or []
-    return {item['name'] for item in data}
-
-
-def filter_labels(labels: list[str], available: set[str]) -> list[str]:
-    """Drop labels that don't already exist in the repo (never auto-create)."""
-    return [label for label in labels if label in available]
-
-
-def call_openrouter(
-    system_prompt: str, user_prompt: str, model: str, api_key: str
-) -> dict[str, Any]:
-    """POST the prompt to OpenRouter with the envelope schema, return the parsed JSON.
-
-    Uses urllib rather than requests so the script has no third-party
-    dependencies at all. urlopen raises HTTPError (a subclass of OSError) on a
-    non-2xx response, which main() treats the same as any other OpenRouter
-    failure: fall back to the plain body.
-    """
-    payload = {
-        'model': model,
-        'messages': [
-            {'role': 'system', 'content': system_prompt},
-            {'role': 'user', 'content': user_prompt},
-        ],
-        'response_format': {
-            'type': 'json_schema',
-            'json_schema': {
-                'name': 'ai_failure_notification',
-                'strict': True,
-                'schema': ENVELOPE_JSON_SCHEMA,
-            },
-        },
-    }
-    request = urllib.request.Request(
-        'https://openrouter.ai/api/v1/chat/completions',
-        data=json.dumps(payload).encode(),
-        headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
-        method='POST',
-    )
-    # S310: the URL is a literal https endpoint, not caller-controlled.
-    with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310
-        body = json.loads(response.read().decode())
-    content = body['choices'][0]['message']['content']
-    return json.loads(content)
-
-
-def write_step_summary(message: str) -> None:
-    """Report a line to the job's step summary and to the log.
-
-    Always goes to stderr as well as the summary: every fallback path in this
-    script reports through here, and a fallback that only shows up in the
-    summary is invisible to anyone reading the job log or the API.
-    """
-    print(message, file=sys.stderr)
-    path = os.environ.get('GITHUB_STEP_SUMMARY')
-    if path:
-        with open(path, 'a', encoding='utf-8') as f:
-            f.write(message + '\n')
-
-
-def plain_fallback_body(workflow_name: str, run_url: str) -> str:
-    """The plain, generic body text used whenever enrichment is unavailable."""
-    return f"Scheduled workflow '{workflow_name}' failed: {run_url}"
-
-
-def render_body(body: str, workflow_name: str, marker: str) -> str:
-    """Assemble an issue or comment body, footer and marker included.
-
-    The `Workflow: <name>` footer is what keeps the notifier's coarse search
-    working after enrichment has rewritten the title and body: the search
-    matches on the workflow name, and without the footer it would depend on
-    the model happening to leave the name in the title.
-    """
-    return f'{body.rstrip()}\n\nWorkflow: {workflow_name}\n\n{marker}'
-
-
-def apply_entry(
-    repo: str,
-    entry: dict[str, Any],
-    marker: str,
-    workflow_name: str,
-    *,
-    default_target: int | None = None,
-) -> str:
-    """Create or comment on an issue per one envelope entry, stamping `marker`."""
-    body = render_body(entry['body'], workflow_name, marker)
-    if entry['action'] == 'new':
-        # The repo's label set is centrally managed, so anything the model
-        # asked for that doesn't exist is dropped rather than created.
-        labels = filter_labels(entry.get('labels') or [], existing_labels(repo))
-        dropped = set(entry.get('labels') or []) - set(labels)
-        if dropped:
-            write_step_summary(
-                f'Dropped labels that do not exist in this repo: {", ".join(sorted(dropped))}.'
-            )
-        args = ['issue', 'create', '--repo', repo, '--title', entry['title'], '--body', body]
-        for label in labels:
-            args += ['--label', label]
-        issue_type = entry.get('issue_type')
-        result = None
-        if issue_type:
-            result = gh(*args, '--type', issue_type, check=False)
-            if result.returncode != 0:
-                write_step_summary(
-                    f'`gh issue create --type {issue_type}` failed ({result.stderr.strip()}); '
-                    'retrying without --type.'
-                )
-                result = None
-        if result is None:
-            result = gh(*args)
-        return result.stdout.strip()
-    else:
-        target = entry.get('target_issue', default_target)
-        gh('issue', 'comment', str(target), '--repo', repo, '--body', body)
-        return f'commented on #{target}'
-
-
-def main() -> int:
-    """Entry point: locate the run's marker, enrich or fall back, apply, and exit."""
-    repo = os.environ['REPO']
-    run_id = str(os.environ['RUN_ID'])
-    workflow_name = os.environ['WORKFLOW_NAME']
-    run_url = os.environ['RUN_URL']
-    api_key = os.environ.get('OPENROUTER_API_KEY', '')
-    model = os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL
-    # What the notifier did, when it tells us. Both are optional: an
-    # unmigrated caller, or a notifier that failed before it got as far as an
-    # issue, leaves them empty and we go looking instead.
-    notify_issue = int(os.environ['NOTIFY_ISSUE']) if os.environ.get('NOTIFY_ISSUE') else None
-    notify_origin = os.environ.get('NOTIFY_ORIGIN') or None
-
-    try:
-        enriched_issue, origin_kind, origin_issue = resolve_origin(
-            repo, run_id, notify_issue, notify_origin
-        )
-    except Exception as exc:  # search API rejection, rate limit, transient 5xx.
-        # Nothing catches this above us: there is no workflow-level fallback
-        # job any more, so an uncaught failure here loses the enrichment
-        # outright rather than degrading through the paths below. When the
-        # notifier told us its issue we can still carry on with that; without
-        # it we continue as though the run were un-marked.
-        write_step_summary(f'Marker lookup failed ({exc}); treating this run as un-marked.')
-        enriched_issue, origin_kind, origin_issue = None, notify_origin, notify_issue
-
-    if enriched_issue is not None:
-        # Rung zero: this run id was already fully enriched once -- a re-run of
-        # the same failing jobs re-triggered us. Comment, don't skip and don't
-        # redo the full LLM pass. On a corpus of past scheduled failures this
-        # rung accounted for half the real duplicate pairs, making it the
-        # highest-value one.
-        gh(
-            'issue',
-            'comment',
-            str(enriched_issue),
-            '--repo',
-            repo,
-            '--body',
-            f'Re-run attempt still failing: {run_url}\n\n<!-- {MARKER_PREFIX}:run={run_id} -->',
-        )
-        write_step_summary(
-            f'Rung zero: run {run_id} already enriched on #{enriched_issue}; '
-            'commented re-run note.'
-        )
-        return 0
-
-    if origin_issue is None:
-        # Either a caller that has not been migrated to pass the issue
-        # through, or a marker lookup that failed. The first is the normal
-        # state of a repo part way through adopting this, so don't treat it
-        # as an anomaly -- just don't lose the notification.
-        write_step_summary(
-            'No notifier marker found for this run id; falling back to a plain issue.'
-        )
-        result = gh(
-            'issue',
-            'create',
-            '--repo',
-            repo,
-            '--title',
-            f"Scheduled workflow '{workflow_name}' failed",
-            '--body',
-            plain_fallback_body(workflow_name, run_url)
-            + f'\n\n<!-- {MARKER_PREFIX}:run={run_id}:origin=new -->',
-        )
-        origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
-        origin_kind = 'new'
-
-    failed_jobs = fetch_failed_jobs(repo, run_id)
-    jobs_sig = [
-        build_job_signature(job.id, job.name, job.failed_step, fetch_job_log(repo, run_id, job.id))
-        for job in failed_jobs
-    ]
-    meta = fetch_run_meta(repo, run_id)
-    signature = build_run_signature(
-        run_id, workflow_name, run_url, meta.get('createdAt', ''), jobs_sig
-    )
-    enriched_marker = render_enriched_marker(run_id, signature)
-
-    if not api_key:
-        write_step_summary('No OPENROUTER_API_KEY configured -- using the plain fallback body.')
-        apply_entry(
-            repo,
-            {
-                'action': 'comment' if origin_kind == 'comment' else 'new',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
-
-    try:
-        open_candidates, closed_candidates = search_candidates(repo, workflow_name)
-    except Exception as exc:  # as above: degrade to "no candidates", don't crash.
-        write_step_summary(f'Candidate search failed ({exc}); proceeding with no candidates.')
-        open_candidates, closed_candidates = [], []
-    if origin_kind == 'new':
-        # The placeholder this run just created is not a candidate to dedupe
-        # against. An issue the notifier *commented* on is a different matter:
-        # it already existed, the coarse search matched it, and it is the most
-        # likely duplicate -- dropping it left the model blind to the very
-        # issue it should have been comparing against, so it answered "new"
-        # and produced the duplicate this whole path exists to avoid.
-        open_candidates = [c for c in open_candidates if c.number != origin_issue]
-    candidates_block = build_candidates_block(
-        open_candidates, closed_candidates, datetime.datetime.now(datetime.timezone.utc)
-    )
-    system_prompt, user_prompt = build_prompt(workflow_name, run_url, signature, candidates_block)
-
-    try:
-        envelope = call_openrouter(system_prompt, user_prompt, model, api_key)
-    except Exception as exc:  # network error, non-2xx, bad JSON, and so on.
-        write_step_summary(f'OpenRouter call failed ({exc}); using the plain fallback body.')
-        apply_entry(
-            repo,
-            {
-                'action': 'new',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
-
-    envelope, dropped_fields = normalise_envelope(envelope)
-    if dropped_fields:
-        write_step_summary(
-            'Ignored fields that do not apply to the chosen action: '
-            + ', '.join(dropped_fields)
-            + '.'
-        )
-
-    errors = validate_envelope(envelope)
-    if errors:
-        write_step_summary(
-            'LLM output failed schema validation:\n' + '\n'.join(f'- {e}' for e in errors)
-        )
-        apply_entry(
-            repo,
-            {
-                'action': 'new',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
-
-    if envelope['action'] == 'new' and origin_kind == 'new':
-        # Upgrade the placeholder in place rather than creating a duplicate.
-        available = existing_labels(repo)
-        labels = filter_labels(envelope.get('labels') or [], available)
-        edit_args = [
-            'issue',
-            'edit',
-            str(origin_issue),
-            '--repo',
-            repo,
-            '--title',
-            envelope['title'],
-            '--body',
-            render_body(envelope['body'], workflow_name, enriched_marker),
-        ]
-        for label in labels:
-            edit_args += ['--add-label', label]
-        gh(*edit_args)
-    elif envelope['action'] == 'comment' and envelope.get('target_issue') == origin_issue:
-        apply_entry(repo, envelope, enriched_marker, workflow_name, default_target=origin_issue)
-    elif envelope['action'] == 'comment':
-        # LLM picked a different candidate than the notifier's coarse match.
-        apply_entry(repo, envelope, enriched_marker, workflow_name)
-        if origin_kind == 'comment':
-            gh(
-                'issue',
-                'comment',
-                str(origin_issue),
-                '--repo',
-                repo,
-                '--body',
-                f'This looks like a distinct issue -- see #{envelope["target_issue"]}.\n\n'
-                f'{enriched_marker}',
-            )
-    else:
-        # action == "new" but origin_kind == "comment": the coarse title
-        # match landed on an unrelated older issue; this is genuinely new.
-        apply_entry(repo, envelope, enriched_marker, workflow_name)
-        gh(
-            'issue',
-            'comment',
-            str(origin_issue),
-            '--repo',
-            repo,
-            '--body',
-            f'This looks like a distinct issue from this one -- opened separately.\n\n'
-            f'{enriched_marker}',
-        )
-
-    for also_entry in envelope.get('also') or []:
-        apply_entry(repo, also_entry, enriched_marker, workflow_name)
-
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
new file mode 100644
index 0000000..c966d1d
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
@@ -0,0 +1,166 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Triage and enrich the issue opened when a scheduled workflow fails.
+
+Split into modules along the boundaries the single file already had. The
+public names are re-exported here so that `from charm_tech_code import
+ai_failure_notifier` keeps working as it did."""
+
+from charm_tech_code.ai_failure_notifier.apply import (
+    apply_entry,
+    plain_fallback_body,
+    render_body,
+)
+from charm_tech_code.ai_failure_notifier.candidates import (
+    build_candidates_block,
+    within_window,
+)
+from charm_tech_code.ai_failure_notifier.cli import (
+    main,
+)
+from charm_tech_code.ai_failure_notifier.constants import (
+    ANSI,
+    CLOSED_CANDIDATE_WINDOW_DAYS,
+    DEFAULT_MODEL,
+    ERROR_MARKER,
+    GO_FAIL,
+    GROUP_END,
+    GROUP_RUN_START,
+    MARKER_PREFIX,
+    MARKER_RE,
+    MAX_CANDIDATES,
+    PYTEST_SUMMARY,
+    PYTEST_SUMMARY_END,
+    RECENT_ISSUE_SCAN,
+    TRACEBACK_END,
+    TS,
+)
+from charm_tech_code.ai_failure_notifier.envelope import (
+    ENVELOPE_JSON_SCHEMA,
+    drop_inapplicable_fields,
+    normalise_envelope,
+    validate_entry,
+    validate_envelope,
+)
+from charm_tech_code.ai_failure_notifier.github import (
+    existing_labels,
+    fetch_failed_jobs,
+    fetch_issue_texts,
+    fetch_job_log,
+    fetch_run_meta,
+    filter_labels,
+    gh,
+    gh_json,
+    locate_run_markers,
+    recent_issue_texts,
+    resolve_origin,
+    search_candidates,
+    search_issue_numbers,
+)
+from charm_tech_code.ai_failure_notifier.markers import (
+    Origin,
+    find_run_markers,
+    render_enriched_marker,
+    render_notifier_marker,
+    signature_hash,
+)
+from charm_tech_code.ai_failure_notifier.models import (
+    CandidateIssue,
+    FailedJob,
+    JobSignature,
+    PytestFailure,
+    RunSignature,
+)
+from charm_tech_code.ai_failure_notifier.openrouter import (
+    call_openrouter,
+)
+from charm_tech_code.ai_failure_notifier.prompt import (
+    SYSTEM_PROMPT,
+    USER_PROMPT_TEMPLATE,
+    build_prompt,
+)
+from charm_tech_code.ai_failure_notifier.signatures import (
+    build_job_signature,
+    build_run_signature,
+    parse_job_log,
+    strip_line,
+    strip_log,
+)
+from charm_tech_code.ai_failure_notifier.summary import (
+    write_step_summary,
+)
+
+__all__ = [
+    'ANSI',
+    'CLOSED_CANDIDATE_WINDOW_DAYS',
+    'CandidateIssue',
+    'DEFAULT_MODEL',
+    'ENVELOPE_JSON_SCHEMA',
+    'ERROR_MARKER',
+    'FailedJob',
+    'GO_FAIL',
+    'GROUP_END',
+    'GROUP_RUN_START',
+    'JobSignature',
+    'MARKER_PREFIX',
+    'MARKER_RE',
+    'MAX_CANDIDATES',
+    'Origin',
+    'PYTEST_SUMMARY',
+    'PYTEST_SUMMARY_END',
+    'PytestFailure',
+    'RECENT_ISSUE_SCAN',
+    'RunSignature',
+    'SYSTEM_PROMPT',
+    'TRACEBACK_END',
+    'TS',
+    'USER_PROMPT_TEMPLATE',
+    'apply_entry',
+    'build_candidates_block',
+    'build_job_signature',
+    'build_prompt',
+    'build_run_signature',
+    'call_openrouter',
+    'drop_inapplicable_fields',
+    'existing_labels',
+    'fetch_failed_jobs',
+    'fetch_issue_texts',
+    'fetch_job_log',
+    'fetch_run_meta',
+    'filter_labels',
+    'find_run_markers',
+    'gh',
+    'gh_json',
+    'locate_run_markers',
+    'main',
+    'normalise_envelope',
+    'parse_job_log',
+    'plain_fallback_body',
+    'recent_issue_texts',
+    'render_body',
+    'render_enriched_marker',
+    'render_notifier_marker',
+    'resolve_origin',
+    'search_candidates',
+    'search_issue_numbers',
+    'signature_hash',
+    'strip_line',
+    'strip_log',
+    'validate_entry',
+    'validate_envelope',
+    'within_window',
+    'write_step_summary',
+]
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
new file mode 100644
index 0000000..0c3f020
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
@@ -0,0 +1,80 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Writing the decision back to GitHub, and the no-LLM fallback."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from charm_tech_code.ai_failure_notifier import github as _github
+from charm_tech_code.ai_failure_notifier import summary as _summary
+
+
+def plain_fallback_body(workflow_name: str, run_url: str) -> str:
+    """The plain, generic body text used whenever enrichment is unavailable."""
+    return f"Scheduled workflow '{workflow_name}' failed: {run_url}"
+
+
+def render_body(body: str, workflow_name: str, marker: str) -> str:
+    """Assemble an issue or comment body, footer and marker included.
+
+    The `Workflow: <name>` footer is what keeps the notifier's coarse search
+    working after enrichment has rewritten the title and body: the search
+    matches on the workflow name, and without the footer it would depend on
+    the model happening to leave the name in the title.
+    """
+    return f'{body.rstrip()}\n\nWorkflow: {workflow_name}\n\n{marker}'
+
+
+def apply_entry(
+    repo: str,
+    entry: dict[str, Any],
+    marker: str,
+    workflow_name: str,
+    *,
+    default_target: int | None = None,
+) -> str:
+    """Create or comment on an issue per one envelope entry, stamping `marker`."""
+    body = render_body(entry['body'], workflow_name, marker)
+    if entry['action'] == 'new':
+        # The repo's label set is centrally managed, so anything the model
+        # asked for that doesn't exist is dropped rather than created.
+        labels = _github.filter_labels(entry.get('labels') or [], _github.existing_labels(repo))
+        dropped = set(entry.get('labels') or []) - set(labels)
+        if dropped:
+            _summary.write_step_summary(
+                f'Dropped labels that do not exist in this repo: {", ".join(sorted(dropped))}.'
+            )
+        args = ['issue', 'create', '--repo', repo, '--title', entry['title'], '--body', body]
+        for label in labels:
+            args += ['--label', label]
+        issue_type = entry.get('issue_type')
+        result = None
+        if issue_type:
+            result = _github.gh(*args, '--type', issue_type, check=False)
+            if result.returncode != 0:
+                _summary.write_step_summary(
+                    f'`gh issue create --type {issue_type}` failed ({result.stderr.strip()}); '
+                    'retrying without --type.'
+                )
+                result = None
+        if result is None:
+            result = _github.gh(*args)
+        return result.stdout.strip()
+    else:
+        target = entry.get('target_issue', default_target)
+        _github.gh('issue', 'comment', str(target), '--repo', repo, '--body', body)
+        return f'commented on #{target}'
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
new file mode 100644
index 0000000..aafe3e6
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
@@ -0,0 +1,71 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Building the pool of issues a failure might already have."""
+
+from __future__ import annotations
+
+import datetime
+
+from charm_tech_code.ai_failure_notifier.constants import (
+    CLOSED_CANDIDATE_WINDOW_DAYS,
+    MAX_CANDIDATES,
+)
+from charm_tech_code.ai_failure_notifier.models import CandidateIssue
+
+# --- Candidate pool ---
+
+
+def within_window(iso_timestamp: str, now: datetime.datetime, days: int) -> bool:
+    """Return whether `iso_timestamp` falls within `days` of `now`."""
+    ts = datetime.datetime.fromisoformat(iso_timestamp.replace('Z', '+00:00'))
+    return now - ts <= datetime.timedelta(days=days)
+
+
+def build_candidates_block(
+    open_issues: list[CandidateIssue],
+    closed_issues: list[CandidateIssue],
+    now: datetime.datetime,
+) -> str:
+    """Render the {{CANDIDATES_BLOCK}} the prompt expects.
+
+    Up to MAX_CANDIDATES entries: open issues first, then recently-closed
+    issues (<=14 days) filling any remaining slots, explicitly labelled as
+    closed so the LLM never auto-treats one as a strong match. Calibration on
+    past scheduled failures found a closed issue can corroborate a match but
+    should never be enough to dedupe against on its own.
+    """
+    entries: list[str] = []
+    for issue in open_issues:
+        if len(entries) >= MAX_CANDIDATES:
+            break
+        entries.append(f'- **#{issue.number} — {issue.title}** (open)\n  > {issue.excerpt()}')
+
+    recent_closed = [
+        i
+        for i in closed_issues
+        if i.closed_at and within_window(i.closed_at, now, CLOSED_CANDIDATE_WINDOW_DAYS)
+    ]
+    for issue in recent_closed:
+        if len(entries) >= MAX_CANDIDATES:
+            break
+        entries.append(
+            f'- **#{issue.number} — {issue.title}** (closed {issue.closed_at} -- '
+            f'recently closed; treat as at most a medium-confidence match)\n  > {issue.excerpt()}'
+        )
+
+    if not entries:
+        return '(no open issues found for this workflow)'
+    return '\n'.join(entries)
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
new file mode 100644
index 0000000..136b5df
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
@@ -0,0 +1,287 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Entry point."""
+
+from __future__ import annotations
+
+import datetime
+import os
+import sys
+
+from charm_tech_code.ai_failure_notifier import apply as _apply
+from charm_tech_code.ai_failure_notifier import candidates as _candidates
+from charm_tech_code.ai_failure_notifier import envelope as _envelope
+from charm_tech_code.ai_failure_notifier import github as _github
+from charm_tech_code.ai_failure_notifier import markers as _markers
+from charm_tech_code.ai_failure_notifier import openrouter as _openrouter
+from charm_tech_code.ai_failure_notifier import prompt as _prompt
+from charm_tech_code.ai_failure_notifier import signatures as _signatures
+from charm_tech_code.ai_failure_notifier import summary as _summary
+from charm_tech_code.ai_failure_notifier.constants import DEFAULT_MODEL, MARKER_PREFIX
+
+
+def main() -> int:
+    """Entry point: locate the run's marker, enrich or fall back, apply, and exit."""
+    repo = os.environ['REPO']
+    run_id = str(os.environ['RUN_ID'])
+    workflow_name = os.environ['WORKFLOW_NAME']
+    run_url = os.environ['RUN_URL']
+    api_key = os.environ.get('OPENROUTER_API_KEY', '')
+    model = os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL
+    # What the notifier did, when it tells us. Both are optional: an
+    # unmigrated caller, or a notifier that failed before it got as far as an
+    # issue, leaves them empty and we go looking instead.
+    notify_issue = int(os.environ['NOTIFY_ISSUE']) if os.environ.get('NOTIFY_ISSUE') else None
+    notify_origin = os.environ.get('NOTIFY_ORIGIN') or None
+
+    try:
+        enriched_issue, origin_kind, origin_issue = _github.resolve_origin(
+            repo, run_id, notify_issue, notify_origin
+        )
+    except Exception as exc:  # search API rejection, rate limit, transient 5xx.
+        # Nothing catches this above us: there is no workflow-level fallback
+        # job any more, so an uncaught failure here loses the enrichment
+        # outright rather than degrading through the paths below. When the
+        # notifier told us its issue we can still carry on with that; without
+        # it we continue as though the run were un-marked.
+        _summary.write_step_summary(
+            f'Marker lookup failed ({exc}); treating this run as un-marked.'
+        )
+        enriched_issue, origin_kind, origin_issue = None, notify_origin, notify_issue
+
+    if enriched_issue is not None:
+        # Rung zero: this run id was already fully enriched once -- a re-run of
+        # the same failing jobs re-triggered us. Comment, don't skip and don't
+        # redo the full LLM pass. On a corpus of past scheduled failures this
+        # rung accounted for half the real duplicate pairs, making it the
+        # highest-value one.
+        _github.gh(
+            'issue',
+            'comment',
+            str(enriched_issue),
+            '--repo',
+            repo,
+            '--body',
+            f'Re-run attempt still failing: {run_url}\n\n<!-- {MARKER_PREFIX}:run={run_id} -->',
+        )
+        _summary.write_step_summary(
+            f'Rung zero: run {run_id} already enriched on #{enriched_issue}; '
+            'commented re-run note.'
+        )
+        return 0
+
+    if origin_issue is None:
+        # Either a caller that has not been migrated to pass the issue
+        # through, or a marker lookup that failed. The first is the normal
+        # state of a repo part way through adopting this, so don't treat it
+        # as an anomaly -- just don't lose the notification.
+        _summary.write_step_summary(
+            'No notifier marker found for this run id; falling back to a plain issue.'
+        )
+        result = _github.gh(
+            'issue',
+            'create',
+            '--repo',
+            repo,
+            '--title',
+            f"Scheduled workflow '{workflow_name}' failed",
+            '--body',
+            _apply.plain_fallback_body(workflow_name, run_url)
+            + f'\n\n<!-- {MARKER_PREFIX}:run={run_id}:origin=new -->',
+        )
+        origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
+        origin_kind = 'new'
+
+    failed_jobs = _github.fetch_failed_jobs(repo, run_id)
+    jobs_sig = [
+        _signatures.build_job_signature(
+            job.id, job.name, job.failed_step, _github.fetch_job_log(repo, run_id, job.id)
+        )
+        for job in failed_jobs
+    ]
+    meta = _github.fetch_run_meta(repo, run_id)
+    signature = _signatures.build_run_signature(
+        run_id, workflow_name, run_url, meta.get('createdAt', ''), jobs_sig
+    )
+    enriched_marker = _markers.render_enriched_marker(run_id, signature)
+
+    if not api_key:
+        _summary.write_step_summary(
+            'No OPENROUTER_API_KEY configured -- using the plain fallback body.'
+        )
+        _apply.apply_entry(
+            repo,
+            {
+                'action': 'comment' if origin_kind == 'comment' else 'new',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    try:
+        open_candidates, closed_candidates = _github.search_candidates(repo, workflow_name)
+    except Exception as exc:  # as above: degrade to "no candidates", don't crash.
+        _summary.write_step_summary(
+            f'Candidate search failed ({exc}); proceeding with no candidates.'
+        )
+        open_candidates, closed_candidates = [], []
+    if origin_kind == 'new':
+        # The placeholder this run just created is not a candidate to dedupe
+        # against. An issue the notifier *commented* on is a different matter:
+        # it already existed, the coarse search matched it, and it is the most
+        # likely duplicate -- dropping it left the model blind to the very
+        # issue it should have been comparing against, so it answered "new"
+        # and produced the duplicate this whole path exists to avoid.
+        open_candidates = [c for c in open_candidates if c.number != origin_issue]
+    candidates_block = _candidates.build_candidates_block(
+        open_candidates, closed_candidates, datetime.datetime.now(datetime.timezone.utc)
+    )
+    system_prompt, user_prompt = _prompt.build_prompt(
+        workflow_name, run_url, signature, candidates_block
+    )
+
+    try:
+        envelope = _openrouter.call_openrouter(system_prompt, user_prompt, model, api_key)
+    except Exception as exc:  # network error, non-2xx, bad JSON, and so on.
+        _summary.write_step_summary(
+            f'OpenRouter call failed ({exc}); using the plain fallback body.'
+        )
+        _apply.apply_entry(
+            repo,
+            {
+                'action': 'new',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    envelope, dropped_fields = _envelope.normalise_envelope(envelope)
+    if dropped_fields:
+        _summary.write_step_summary(
+            'Ignored fields that do not apply to the chosen action: '
+            + ', '.join(dropped_fields)
+            + '.'
+        )
+
+    errors = _envelope.validate_envelope(envelope)
+    if errors:
+        _summary.write_step_summary(
+            'LLM output failed schema validation:\n' + '\n'.join(f'- {e}' for e in errors)
+        )
+        _apply.apply_entry(
+            repo,
+            {
+                'action': 'new',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'title': f"Scheduled workflow '{workflow_name}' failed",
+                'labels': [],
+                'issue_type': None,
+            }
+            if origin_kind != 'comment'
+            else {
+                'action': 'comment',
+                'body': _apply.plain_fallback_body(workflow_name, run_url),
+                'target_issue': origin_issue,
+            },
+            enriched_marker,
+            workflow_name,
+            default_target=origin_issue,
+        )
+        return 0
+
+    if envelope['action'] == 'new' and origin_kind == 'new':
+        # Upgrade the placeholder in place rather than creating a duplicate.
+        available = _github.existing_labels(repo)
+        labels = _github.filter_labels(envelope.get('labels') or [], available)
+        edit_args = [
+            'issue',
+            'edit',
+            str(origin_issue),
+            '--repo',
+            repo,
+            '--title',
+            envelope['title'],
+            '--body',
+            _apply.render_body(envelope['body'], workflow_name, enriched_marker),
+        ]
+        for label in labels:
+            edit_args += ['--add-label', label]
+        _github.gh(*edit_args)
+    elif envelope['action'] == 'comment' and envelope.get('target_issue') == origin_issue:
+        _apply.apply_entry(
+            repo, envelope, enriched_marker, workflow_name, default_target=origin_issue
+        )
+    elif envelope['action'] == 'comment':
+        # LLM picked a different candidate than the notifier's coarse match.
+        _apply.apply_entry(repo, envelope, enriched_marker, workflow_name)
+        if origin_kind == 'comment':
+            _github.gh(
+                'issue',
+                'comment',
+                str(origin_issue),
+                '--repo',
+                repo,
+                '--body',
+                f'This looks like a distinct issue -- see #{envelope["target_issue"]}.\n\n'
+                f'{enriched_marker}',
+            )
+    else:
+        # action == "new" but origin_kind == "comment": the coarse title
+        # match landed on an unrelated older issue; this is genuinely new.
+        _apply.apply_entry(repo, envelope, enriched_marker, workflow_name)
+        _github.gh(
+            'issue',
+            'comment',
+            str(origin_issue),
+            '--repo',
+            repo,
+            '--body',
+            f'This looks like a distinct issue from this one -- opened separately.\n\n'
+            f'{enriched_marker}',
+        )
+
+    for also_entry in envelope.get('also') or []:
+        _apply.apply_entry(repo, also_entry, enriched_marker, workflow_name)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/constants.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/constants.py
new file mode 100644
index 0000000..51edd54
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/constants.py
@@ -0,0 +1,121 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Regexes, marker shapes and tuning constants."""
+
+from __future__ import annotations
+
+import re
+
+MARKER_PREFIX = 'ai-failure-notifications'
+DEFAULT_MODEL = 'deepseek/deepseek-chat'  # DeepSeek V3 on OpenRouter.
+CLOSED_CANDIDATE_WINDOW_DAYS = 14
+MAX_CANDIDATES = 3
+# How many recently-updated issues to scan for the notifier's marker. The
+# artefact we are looking for was touched minutes ago, so this only has to
+# cover issue churn in that window; 50 is far more than `operator` sees.
+RECENT_ISSUE_SCAN = 50
+
+# Colour escapes, which Actions logs are full of. Two alternatives, because
+# the logs contain both the real thing and a mangled form where the ESC byte
+# has already been stripped, leaving a bare "[32m".
+ANSI = re.compile(
+    r"""
+    \x1b\[ [0-9;]* [A-Za-z]   # a full escape: ESC [ params letter
+    |
+    \[ \d+ (?:;\d+)* m        # ESC already stripped: [32m, [1;33m
+    """,
+    re.VERBOSE,
+)
+
+# The timestamp Actions prefixes to every log line, for example
+# "2026-07-21T16:17:04.8204062Z ". Stripped before anything else is matched.
+TS = re.compile(
+    r"""
+    ^\d{4}-\d{2}-\d{2}        # date: 2026-07-21
+    T\d{2}:\d{2}:\d{2}        # time: T16:17:04
+    \.\d+Z[ ]                 # fractional seconds, zone, one trailing space
+    """,
+    re.VERBOSE,
+)
+
+# Actions' own annotation for a failing step.
+ERROR_MARKER = re.compile(r'##\[error\]')
+
+# The runner opens every step with "##[group]Run <script>", echoes the whole
+# `run:` block a line at a time, dumps the step's env, and closes with
+# "##[endgroup]". None of that is output: it is the step's own source. A
+# multi-line `run:` therefore puts its every branch into the log, including
+# the ones that did not execute, and parsing it produces failures the run
+# never had.
+#
+# Colour is not a usable signal here -- the runner marks echoed lines cyan-
+# bold, but ANSI above strips that before anything is matched -- so the
+# group boundary is what separates a step's script from its output.
+GROUP_RUN_START = re.compile(r'^##\[group\]Run ')
+GROUP_END = re.compile(r'^##\[endgroup\]')
+
+# A line from pytest's short summary, for example
+# "FAILED tests/integration/test_charm.py::test_deploy - TimeoutError: ...".
+PYTEST_SUMMARY = re.compile(
+    r"""
+    ^(FAILED|ERROR)[ ]         # which of the two pytest reports
+    (\S+?)[ ]-[ ]              # the test id, up to the " - " separator
+    (.+)$                      # the error message, to end of line
+    """,
+    re.VERBOSE,
+)
+
+# The end of pytest's summary section, for example
+# "======== 3 failed, 41 passed, 2 warnings in 512.44s ========".
+PYTEST_SUMMARY_END = re.compile(
+    r"""
+    ={3,}                      # the run of = that brackets the line
+    .*(failed|passed|error)    # and one of pytest's outcome words
+    """,
+    re.VERBOSE,
+)
+
+# A failing Go test, for example "--- FAIL: TestFoo (0.01s)".
+GO_FAIL = re.compile(r'^--- FAIL: (\S+)')
+
+# The last line of a Python traceback: the exception type and its message,
+# for example "KeyError: 'loki/0'". Deliberately narrow -- it must look like an
+# exception class name -- so that arbitrary "word: text" log lines don't match.
+TRACEBACK_END = re.compile(
+    r"""
+    ^([A-Z]                          # exception types start with a capital
+      [A-Za-z_.]*                    # dotted path allowed: ops.pebble.APIError
+      (?:Error|Exception|Warning))   # and conventionally end one of three ways
+    :[ ](.*)$                        # then ": " and the message
+    """,
+    re.VERBOSE,
+)
+
+# Matches markers stamped by either workflow:
+#   notifier:  <!-- ai-failure-notifications:run=123:origin=new -->
+#              <!-- ai-failure-notifications:run=123:origin=comment -->
+#   enricher:  <!-- ai-failure-notifications:run=123:sig=abcdef0123456789 -->
+MARKER_RE = re.compile(
+    r'<!--\s*'
+    + re.escape(MARKER_PREFIX)
+    + r"""
+    :run=(?P<run_id>\d+)
+    (?::origin=(?P<origin>new|comment))?
+    (?::sig=(?P<sig>[0-9a-f]+))?
+    \s*-->
+    """,
+    re.VERBOSE,
+)
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
new file mode 100644
index 0000000..e81bfc6
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
@@ -0,0 +1,232 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Validating the model's response envelope, hand-rolled on purpose."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# --- Envelope schema validation (hand-rolled -- deliberately not the
+# `jsonschema` package, so the script keeps needing nothing outside the stdlib.
+# Mirrors ENVELOPE_JSON_SCHEMA below, which is what OpenRouter is asked to
+# conform to; this re-checks it on the applier side.) ---
+
+_ENTRY_COMMON_REQUIRED = ('action', 'body', 'dedup_reason', 'confidence')
+_ENTRY_KNOWN_KEYS = {
+    'action',
+    'body',
+    'dedup_reason',
+    'confidence',
+    'title',
+    'labels',
+    'issue_type',
+    'target_issue',
+}
+
+
+def validate_entry(entry: Any, *, path: str, allow_also: bool = False) -> list[str]:
+    """Validate one envelope entry (top-level or an `also[i]`) against the schema.
+
+    `also` is only legal on the top-level envelope, so the caller says whether
+    this is that. Without it the top-level check rejected every envelope that
+    carried `also` -- which the model emits routinely, since the schema it is
+    given declares the field.
+    """
+    errors: list[str] = []
+    if not isinstance(entry, dict):
+        return [f'{path}: expected an object, got {type(entry).__name__}']
+
+    for field in _ENTRY_COMMON_REQUIRED:
+        if field not in entry:
+            errors.append(f"{path}: missing required field '{field}'")
+
+    known = _ENTRY_KNOWN_KEYS | {'also'} if allow_also else _ENTRY_KNOWN_KEYS
+    unknown = set(entry) - known
+    if unknown:
+        errors.append(f'{path}: unknown field(s) {sorted(unknown)}')
+
+    action = entry.get('action')
+    if action not in ('comment', 'new'):
+        errors.append(f"{path}.action: must be 'comment' or 'new', got {action!r}")
+        return errors  # can't check action-conditional fields without a valid action
+
+    if not isinstance(entry.get('body'), str) or not entry.get('body'):
+        errors.append(f'{path}.body: must be a non-empty string')
+    if not isinstance(entry.get('dedup_reason'), str) or not entry.get('dedup_reason'):
+        errors.append(f'{path}.dedup_reason: must be a non-empty string')
+    if entry.get('confidence') not in ('high', 'medium', 'low'):
+        errors.append(
+            f'{path}.confidence: must be one of high/medium/low, got {entry.get("confidence")!r}'
+        )
+
+    # A field present but null counts as absent. The schema sent to OpenRouter
+    # is `strict`, so models routinely return every declared property and use
+    # null for the ones that do not apply to the action they chose; rejecting on
+    # mere presence threw away otherwise good output.
+    if action == 'new':
+        for field in ('title', 'labels', 'issue_type'):
+            if field not in entry:
+                errors.append(f"{path}: action='new' requires '{field}'")
+        if entry.get('target_issue') is not None:
+            errors.append(f"{path}: action='new' must not include 'target_issue'")
+        labels = entry.get('labels')
+        if labels is not None and (
+            not isinstance(labels, list) or not all(isinstance(x, str) for x in labels)
+        ):
+            errors.append(f'{path}.labels: must be an array of strings')
+        if 'issue_type' in entry and not (
+            entry['issue_type'] is None or isinstance(entry['issue_type'], str)
+        ):
+            errors.append(f'{path}.issue_type: must be a string or null')
+    else:  # comment
+        if 'target_issue' not in entry:
+            errors.append(f"{path}: action='comment' requires 'target_issue'")
+        elif not isinstance(entry['target_issue'], int) or entry['target_issue'] < 1:
+            errors.append(f'{path}.target_issue: must be a positive integer')
+        for field in ('title', 'labels', 'issue_type'):
+            if entry.get(field) is not None:
+                errors.append(f"{path}: action='comment' must not include '{field}'")
+
+    return errors
+
+
+# Fields that only mean something for one of the two actions. The model is
+# given a `strict` schema, so it tends to return every declared property and
+# fill in the ones that do not apply to the action it chose. Those are dropped
+# rather than treated as an error: we would not act on them either way, and
+# rejecting the envelope threw away a usable body and fell back to the plain
+# notice.
+_ACTION_ONLY_FIELDS = {
+    'comment': ('title', 'labels', 'issue_type'),
+    'new': ('target_issue',),
+}
+
+
+def drop_inapplicable_fields(entry: Any) -> tuple[Any, list[str]]:
+    """Strip fields that do not apply to `entry`'s action; report what went."""
+    if not isinstance(entry, dict):
+        return entry, []
+    fields = _ACTION_ONLY_FIELDS.get(entry.get('action'))
+    if not fields:
+        return entry, []
+    dropped = [f for f in fields if f in entry]
+    if not dropped:
+        return entry, []
+    return {k: v for k, v in entry.items() if k not in dropped}, dropped
+
+
+def normalise_envelope(envelope: Any) -> tuple[Any, list[str]]:
+    """Drop inapplicable fields from the envelope and each `also` entry."""
+    if not isinstance(envelope, dict):
+        return envelope, []
+    cleaned, dropped = drop_inapplicable_fields(envelope)
+    notes = [f'envelope: {f}' for f in dropped]
+    also = cleaned.get('also')
+    if isinstance(also, list):
+        entries: list[Any] = []
+        for i, entry in enumerate(also):
+            entry, entry_dropped = drop_inapplicable_fields(entry)
+            notes += [f'envelope.also[{i}]: {f}' for f in entry_dropped]
+            entries.append(entry)
+        cleaned = {**cleaned, 'also': entries}
+    return cleaned, notes
+
+
+def validate_envelope(envelope: Any) -> list[str]:
+    """Validate a top-level envelope (may carry `also`).
+
+    Returns a list of human-readable errors; empty list means valid.
+    """
+    if not isinstance(envelope, dict):
+        return ['envelope: expected a JSON object']
+
+    errors = validate_entry(envelope, path='envelope', allow_also=True)
+
+    also = envelope.get('also')
+    if also is not None:
+        if not isinstance(also, list) or len(also) > 2:
+            errors.append('envelope.also: must be an array of at most two entries')
+        else:
+            for i, entry in enumerate(also):
+                if isinstance(entry, dict) and 'also' in entry:
+                    errors.append(f"envelope.also[{i}]: nested 'also' is not allowed")
+                errors.extend(validate_entry(entry, path=f'envelope.also[{i}]'))
+
+    return errors
+
+
+ENVELOPE_JSON_SCHEMA = {
+    '$schema': 'https://json-schema.org/draft/2020-12/schema',
+    'title': 'ai-failure-notifications envelope',
+    'type': 'object',
+    'required': ['action', 'body', 'dedup_reason', 'confidence'],
+    'properties': {
+        'action': {'enum': ['comment', 'new']},
+        'body': {'type': 'string', 'minLength': 1},
+        'dedup_reason': {'type': 'string', 'minLength': 1},
+        'confidence': {'enum': ['high', 'medium', 'low']},
+        'title': {'type': 'string', 'minLength': 1},
+        'labels': {'type': 'array', 'items': {'type': 'string'}},
+        'issue_type': {'type': ['string', 'null']},
+        'target_issue': {'type': 'integer', 'minimum': 1},
+        'also': {'type': 'array', 'maxItems': 2, 'items': {'$ref': '#/$defs/envelopeEntry'}},
+    },
+    'additionalProperties': False,
+    'allOf': [{'$ref': '#/$defs/actionConditionals'}],
+    '$defs': {
+        'actionConditionals': {
+            'allOf': [
+                {
+                    'if': {'properties': {'action': {'const': 'new'}}},
+                    'then': {
+                        'required': ['title', 'labels', 'issue_type'],
+                        'not': {'required': ['target_issue']},
+                        'properties': {'labels': {'type': 'array', 'items': {'type': 'string'}}},
+                    },
+                },
+                {
+                    'if': {'properties': {'action': {'const': 'comment'}}},
+                    'then': {
+                        'required': ['target_issue'],
+                        'not': {
+                            'anyOf': [
+                                {'required': ['title']},
+                                {'required': ['labels']},
+                                {'required': ['issue_type']},
+                            ]
+                        },
+                    },
+                },
+            ]
+        },
+        'envelopeEntry': {
+            'type': 'object',
+            'required': ['action', 'body', 'dedup_reason', 'confidence'],
+            'properties': {
+                'action': {'enum': ['comment', 'new']},
+                'body': {'type': 'string', 'minLength': 1},
+                'dedup_reason': {'type': 'string', 'minLength': 1},
+                'confidence': {'enum': ['high', 'medium', 'low']},
+                'title': {'type': 'string', 'minLength': 1},
+                'labels': {'type': 'array', 'items': {'type': 'string'}},
+                'issue_type': {'type': ['string', 'null']},
+                'target_issue': {'type': 'integer', 'minimum': 1},
+            },
+            'additionalProperties': False,
+            'allOf': [{'$ref': '#/$defs/actionConditionals'}],
+        },
+    },
+}
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
new file mode 100644
index 0000000..5183e9f
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
@@ -0,0 +1,286 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Everything that shells out to `gh`."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+from charm_tech_code.ai_failure_notifier import markers as _markers
+from charm_tech_code.ai_failure_notifier import summary as _summary
+from charm_tech_code.ai_failure_notifier.constants import MARKER_PREFIX, RECENT_ISSUE_SCAN
+from charm_tech_code.ai_failure_notifier.models import CandidateIssue, FailedJob
+
+# --- I/O ---
+
+
+def gh(*args: str, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a `gh` subcommand, returning the completed process."""
+    # S607: `gh` is deliberately called by name, resolved from the runner's PATH.
+    return subprocess.run(['gh', *args], text=True, capture_output=True, check=check)  # noqa: S607
+
+
+def gh_json(*args: str) -> Any:
+    """Run a `gh ... --json ...` subcommand and parse its stdout as JSON."""
+    result = gh(*args)
+    return json.loads(result.stdout) if result.stdout.strip() else None
+
+
+def fetch_failed_jobs(repo: str, run_id: str) -> list[FailedJob]:
+    """List the failed jobs of a run, each with its id, name, and failed step."""
+    data = gh_json('run', 'view', str(run_id), '--repo', repo, '--json', 'jobs') or {}
+    failed: list[FailedJob] = []
+    for job in data.get('jobs', []):
+        if job.get('conclusion') != 'failure':
+            continue
+        failed_step = None
+        for step in job.get('steps') or []:
+            if step.get('conclusion') == 'failure':
+                failed_step = step.get('name')
+                break
+        failed.append(FailedJob(id=job['databaseId'], name=job['name'], failed_step=failed_step))
+    return failed
+
+
+def fetch_job_log(repo: str, run_id: str, job_id: int) -> str:
+    """Fetch one job's full log text.
+
+    Uses the REST logs endpoint rather than `gh run view --log`: the latter
+    exits 0 with empty stdout on some `gh` builds (reproduced on 2.45.0), which
+    silently degrades the extracted signature to nothing. An empty log here is
+    reported rather than swallowed.
+
+    `--allow-escape-sequences` is not optional. From gh 2.9x, `gh api` refuses
+    to write a response containing terminal escapes -- "the response contains
+    terminal escape sequences; pass --allow-escape-sequences to output it
+    anyway" -- and returns nothing at all. Actions logs are full of them; ANSI
+    above exists to strip them. Runners carry a gh new enough to refuse (2.97.0
+    when this was measured, in fork run 32673538357), so without the flag every
+    fetch comes back empty and the signature degrades to the job name.
+
+    Older builds have no such check and no such flag, and reject it as unknown
+    rather than ignoring it, so those retry without.
+    """
+    endpoint = f'repos/{repo}/actions/jobs/{job_id}/logs'
+    result = gh('api', endpoint, '--allow-escape-sequences', check=False)
+    if 'unknown flag' in (result.stderr or ''):
+        result = gh('api', endpoint, check=False)
+    if not result.stdout.strip():
+        # `gh` puts the status on stderr ("gh: Not Found (HTTP 404)"), and the
+        # exit code alone is 1 for all of them. Without the status there is no
+        # telling a log that is not ready yet from a token that has lost
+        # `actions: read`, and the two want opposite fixes.
+        detail = ' '.join((result.stderr or '').split())[:200] or 'no stderr'
+        _summary.write_step_summary(
+            f'Warning: no log text for job {job_id} of run {run_id} '
+            f'(gh exit {result.returncode}: {detail}); '
+            f'signature will be based on the job name alone.'
+        )
+    return result.stdout
+
+
+def fetch_run_meta(repo: str, run_id: str) -> dict[str, str]:
+    """Fetch a run's display metadata (title, workflow name, url, createdAt)."""
+    return (
+        gh_json(
+            'run',
+            'view',
+            str(run_id),
+            '--repo',
+            repo,
+            '--json',
+            'displayTitle,workflowName,url,createdAt',
+        )
+        or {}
+    )
+
+
+def search_issue_numbers(repo: str, query_text: str) -> list[int]:
+    """Search issues (any state) in `repo` for `query_text`, return issue numbers."""
+    # The repo must be passed as `--repo`, not folded into the positional query.
+    # `gh search issues` quotes each positional argument as a single search
+    # keyword, so `repo:owner/name "text"` becomes the literal keyword
+    # `repo:"owner/name \"text\""` and GitHub rejects it as an invalid query.
+    data = (
+        gh_json(
+            'search', 'issues', '--repo', repo, '--limit', '10', '--json', 'number', query_text
+        )
+        or []
+    )
+    return [item['number'] for item in data]
+
+
+def fetch_issue_texts(repo: str, number: int) -> list[str]:
+    """Fetch an issue's body plus all comment bodies, for marker scanning."""
+    data = gh_json('issue', 'view', str(number), '--repo', repo, '--json', 'body,comments') or {}
+    texts = [data.get('body') or '']
+    for c in data.get('comments') or []:
+        texts.append(c.get('body') or '')
+    return texts
+
+
+def recent_issue_texts(repo: str, limit: int = RECENT_ISSUE_SCAN) -> list[tuple[int, str]]:
+    """Return (number, text) pairs for the `limit` most recently updated issues.
+
+    Bodies and comment bodies both, since a notifier marker with
+    `origin=comment` lives in a comment rather than the body.
+    """
+    data = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'all',
+            '--limit',
+            str(limit),
+            '--json',
+            'number,body,comments',
+        )
+        or []
+    )
+    texts: list[tuple[int, str]] = []
+    for issue in data:
+        number = issue['number']
+        texts.append((number, issue.get('body') or ''))
+        for comment in issue.get('comments') or []:
+            texts.append((number, comment.get('body') or ''))
+    return texts
+
+
+def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None, int | None]:
+    """Find the markers belonging to `run_id` and classify them.
+
+    Scans the most recently updated issues first, and only falls back to
+    `gh search issues` if that finds nothing.
+
+    The ordering matters, and is the whole point of doing it this way. The
+    notifier stamps its marker moments before this workflow runs, and GitHub's
+    issue *search* index is not read-your-writes -- a marker that has not been
+    indexed yet reads as "no notifier marker found", and main() responds by
+    opening a *second* issue for a run that already has one. The issue *list*
+    endpoint has no such lag, and the artefact the notifier just touched is by
+    construction among the most recently updated issues in the repo.
+
+    Search remains as a fallback for the one case the list cannot cover: a repo
+    busy enough that more than `RECENT_ISSUE_SCAN` issues were updated in
+    between, where a stale index still beats no lookup at all.
+    """
+    markers = _markers.find_run_markers(recent_issue_texts(repo), run_id)
+    if markers != (None, None, None):
+        return markers
+
+    hits = search_issue_numbers(repo, f'{MARKER_PREFIX}:run={run_id}')
+    texts: list[tuple[int, str]] = []
+    for number in hits:
+        for text in fetch_issue_texts(repo, number):
+            texts.append((number, text))
+    return _markers.find_run_markers(texts, run_id)
+
+
+def resolve_origin(
+    repo: str, run_id: str, notify_issue: int | None, notify_origin: str | None
+) -> tuple[int | None, str | None, int | None]:
+    """Work out which artefact this run should upgrade.
+
+    Returns the same triple as `find_run_markers`.
+
+    When the notifier tells us the issue it created or commented on, that is
+    authoritative for `origin_issue`/`origin_kind` and we never search for it.
+    That removes the read-your-writes hazard `locate_run_markers` exists to
+    work around: the notifier stamps its marker moments before this job runs,
+    and GitHub's issue *search* index lags, so a marker that has not been
+    indexed yet reads as "no notifier marker found" and main() opens a second
+    issue for a run that already has one. A number passed directly through the
+    workflow cannot be stale.
+
+    Rung zero still needs a lookup, and the notifier's output cannot supply
+    it: "this run id was already fully enriched" is a fact about an *earlier
+    run of this script*, not about what the notifier just did. But knowing the
+    issue narrows that lookup from a scan of the repo's recently-updated
+    issues to reading the one issue we were handed.
+
+    With no `notify_issue` -- the notifier failed, or a caller has not been
+    migrated -- this falls back to the original repo-wide scan, so the script
+    still works when it is not told anything.
+    """
+    if notify_issue is None:
+        return locate_run_markers(repo, run_id)
+
+    texts = [(notify_issue, text) for text in fetch_issue_texts(repo, notify_issue)]
+    enriched_issue, origin_kind, origin_issue = _markers.find_run_markers(texts, run_id)
+    # The passed-in values win: a marker we failed to find on the issue does
+    # not make the issue the wrong one.
+    return enriched_issue, notify_origin or origin_kind, notify_issue
+
+
+def search_candidates(
+    repo: str, workflow_name: str
+) -> tuple[list[CandidateIssue], list[CandidateIssue]]:
+    """Coarse candidate search: open and closed issues matching the workflow name."""
+    fields = 'number,title,body,createdAt,closedAt'
+    open_issues = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'open',
+            '--search',
+            f'"{workflow_name}"',
+            '--json',
+            fields,
+            '--limit',
+            '20',
+        )
+        or []
+    )
+    closed_issues = (
+        gh_json(
+            'issue',
+            'list',
+            '--repo',
+            repo,
+            '--state',
+            'closed',
+            '--search',
+            f'"{workflow_name}"',
+            '--json',
+            fields,
+            '--limit',
+            '20',
+        )
+        or []
+    )
+    return (
+        [CandidateIssue.from_gh(i) for i in open_issues],
+        [CandidateIssue.from_gh(i) for i in closed_issues],
+    )
+
+
+def existing_labels(repo: str) -> set[str]:
+    """Return the set of label names that already exist in `repo`."""
+    data = gh_json('label', 'list', '--repo', repo, '--json', 'name', '--limit', '100') or []
+    return {item['name'] for item in data}
+
+
+def filter_labels(labels: list[str], available: set[str]) -> list[str]:
+    """Drop labels that don't already exist in the repo (never auto-create)."""
+    return [label for label in labels if label in available]
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
new file mode 100644
index 0000000..d171565
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
@@ -0,0 +1,94 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The HTML comment markers the two workflows communicate through."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Literal
+
+from charm_tech_code.ai_failure_notifier.constants import MARKER_PREFIX, MARKER_RE
+from charm_tech_code.ai_failure_notifier.models import RunSignature
+
+# --- Marker + signature hashing ---
+
+
+def signature_hash(signature: RunSignature) -> str:
+    """Deterministic short fingerprint of a run signature.
+
+    Used only for the marker's :sig= suffix (not for dedup decisions --
+    that's the LLM's job, guided by the candidate pool).
+    """
+    parts: list[str] = []
+    for job in signature.jobs:
+        parts.extend(failure.test for failure in job.pytest_failures)
+        parts.extend(job.go_failures)
+        if job.traceback_top_error:
+            parts.append(job.traceback_top_error)
+        if job.failed_step:
+            parts.append(job.failed_step)
+    canonical = '\n'.join(sorted(parts)) or signature.workflow_name
+    return hashlib.sha1(canonical.encode('utf-8'), usedforsecurity=False).hexdigest()[:16]
+
+
+# Which artefact the notifier touched: a fresh placeholder issue, or a comment
+# on an issue that already existed. A Literal so a type checker rejects a bad
+# value before it reaches a marker.
+Origin = Literal['new', 'comment']
+
+
+def render_notifier_marker(run_id: str, origin: Origin) -> str:
+    """Render the marker the notifier stamps, telling the enricher what it touched."""
+    return f'<!-- {MARKER_PREFIX}:run={run_id}:origin={origin} -->'
+
+
+def render_enriched_marker(run_id: str, signature: RunSignature) -> str:
+    """Render the marker this script stamps once it has fully processed a run.
+
+    Presence of :sig= is what makes rung zero (find_run_markers) treat a later
+    same-run-id trigger as "already enriched, just note the re-run".
+    """
+    return f'<!-- {MARKER_PREFIX}:run={run_id}:sig={signature_hash(signature)} -->'
+
+
+def find_run_markers(
+    texts: list[tuple[int, str]], run_id: str
+) -> tuple[int | None, str | None, int | None]:
+    """Scan (issue_number, text) pairs for markers belonging to `run_id`.
+
+    Returns (enriched_issue, origin_kind, origin_issue):
+    - enriched_issue: an issue number carrying a :sig= marker for this run
+      (rung zero -- this run was already fully enriched once), else None.
+    - origin_kind / origin_issue: the "new"/"comment" marker the notifier
+      stamped for this run (identifies which artefact to upgrade), else
+      (None, None).
+    """
+    run_id = str(run_id)
+    enriched_issue = None
+    origin_kind = None
+    origin_issue = None
+    for number, text in texts:
+        if not text:
+            continue
+        for match in MARKER_RE.finditer(text):
+            if match['run_id'] != run_id:
+                continue
+            if match['sig']:
+                enriched_issue = number
+            elif match['origin']:
+                origin_kind = match['origin']
+                origin_issue = number
+    return enriched_issue, origin_kind, origin_issue
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
new file mode 100644
index 0000000..4c5dff8
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
@@ -0,0 +1,100 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The structured shapes a run's failure is reduced to."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+# --- Structured shapes ---
+#
+# The signature is built here, serialised into the prompt, and hashed for the
+# marker, so its shape is worth pinning down rather than passing dicts around.
+# `dataclasses.asdict` preserves field declaration order, which is what the
+# prompt's JSON ends up in.
+
+
+@dataclasses.dataclass(frozen=True)
+class PytestFailure:
+    """One line of pytest's short summary."""
+
+    kind: str  # "FAILED" or "ERROR" -- pytest reports both here.
+    test: str
+    error: str
+
+
+@dataclasses.dataclass(frozen=True)
+class JobSignature:
+    """What the deterministic parser could extract from one failed job's log."""
+
+    job_id: int
+    job_name: str
+    failed_step: str | None
+    pytest_failures: list[PytestFailure]
+    go_failures: list[str]
+    traceback_top_error: str | None
+    tail_excerpt: list[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class RunSignature:
+    """Every failed job of one run, plus the run's own identifying fields."""
+
+    run_id: str
+    workflow_name: str
+    html_url: str
+    created_at: str
+    jobs: list[JobSignature]
+
+    def as_json(self) -> str:
+        """Render for the prompt, in field declaration order."""
+        return json.dumps(dataclasses.asdict(self), indent=2)
+
+
+@dataclasses.dataclass(frozen=True)
+class FailedJob:
+    """A failed job as listed by `gh run view`, before its log is fetched."""
+
+    id: int
+    name: str
+    failed_step: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class CandidateIssue:
+    """An existing issue that might already track this failure."""
+
+    number: int
+    title: str
+    body: str | None
+    closed_at: str | None
+
+    @classmethod
+    def from_gh(cls, data: dict[str, Any]) -> CandidateIssue:
+        """Build from one element of `gh issue list --json ...` output."""
+        return cls(
+            number=data['number'],
+            title=data['title'],
+            body=data.get('body'),
+            closed_at=data.get('closedAt'),
+        )
+
+    def excerpt(self) -> str:
+        """The first line of the body, bounded, for the candidate block."""
+        lines = (self.body or '').strip().splitlines()
+        return lines[0][:300] if lines else '(no body)'
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/openrouter.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/openrouter.py
new file mode 100644
index 0000000..a6d9ea1
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/openrouter.py
@@ -0,0 +1,62 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The OpenRouter call."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Any
+
+from charm_tech_code.ai_failure_notifier.envelope import ENVELOPE_JSON_SCHEMA
+
+
+def call_openrouter(
+    system_prompt: str, user_prompt: str, model: str, api_key: str
+) -> dict[str, Any]:
+    """POST the prompt to OpenRouter with the envelope schema, return the parsed JSON.
+
+    Uses urllib rather than requests so the script has no third-party
+    dependencies at all. urlopen raises HTTPError (a subclass of OSError) on a
+    non-2xx response, which main() treats the same as any other OpenRouter
+    failure: fall back to the plain body.
+    """
+    payload = {
+        'model': model,
+        'messages': [
+            {'role': 'system', 'content': system_prompt},
+            {'role': 'user', 'content': user_prompt},
+        ],
+        'response_format': {
+            'type': 'json_schema',
+            'json_schema': {
+                'name': 'ai_failure_notification',
+                'strict': True,
+                'schema': ENVELOPE_JSON_SCHEMA,
+            },
+        },
+    }
+    request = urllib.request.Request(
+        'https://openrouter.ai/api/v1/chat/completions',
+        data=json.dumps(payload).encode(),
+        headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
+        method='POST',
+    )
+    # S310: the URL is a literal https endpoint, not caller-controlled.
+    with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310
+        body = json.loads(response.read().decode())
+    content = body['choices'][0]['message']['content']
+    return json.loads(content)
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
new file mode 100644
index 0000000..90285c9
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
@@ -0,0 +1,240 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The LLM prompt."""
+
+from __future__ import annotations
+
+from charm_tech_code.ai_failure_notifier.models import RunSignature
+
+# --- Prompt building ---
+
+SYSTEM_PROMPT = """\
+You are the enrichment step of an internal CI failure-triage bot for the
+Canonical Charm Tech team. A scheduled GitHub Actions workflow just failed.
+A separate deterministic parser has already extracted a structured failure
+signature from the run's logs -- you do not have repository access, log
+access, or internet access beyond what is given to you in this message.
+Work only from the signature JSON and candidate issues you're given.
+
+Your job: decide whether this failure is a new occurrence of an
+already-tracked problem (comment on the existing issue) or something not
+currently tracked (open a new issue), and draft the text for whichever
+artefact you choose. Output ONLY the JSON envelope described below -- no
+prose before or after it, no markdown code fences around it.
+
+You are reporting, not fixing. Never propose a fix, a patch, a diff, a
+workaround, a configuration change, a retry, a next step, or anything else
+that tells a reader what to do about the failure -- not as a section, not
+as a sentence, not as an aside, however confident you are and however
+obvious it looks. Deciding what to do about a failure is someone else's
+job, and a wrong suggestion from you is worse than none, because it
+anchors whoever picks the issue up. Describe what failed and, where the
+signature genuinely supports it, why. Then stop.
+
+## Reading the signature
+
+The signature has one entry per failed job in `jobs[]`. Each entry may
+carry, in decreasing order of how much you should trust it:
+
+1. `pytest_failures[]` -- `{kind, test, error}` triples parsed from
+   pytest's "short test summary info" block. `test` is a real pytest node
+   id; `error` is the tail of that summary line and CAN BE TRUNCATED by
+   pytest itself (it cuts long messages short, for example
+   "PendingDeprecat..."). If an `error` string ends in `...`, treat it
+   as unreliable for anything beyond "this test failed" -- do not quote it
+   as the root cause, do not put the truncated fragment in a title. Look
+   at `traceback_top_error` and `tail_excerpt` for that job instead; if
+   they don't resolve it either, describe the failure by test name only
+   and say the specific assertion text is unavailable.
+2. `traceback_top_error` -- the last `<ErrorClass>: <message>` line found
+   anywhere in the job's log. Usually the real exception, but it is a
+   last-line heuristic: on jobs where cleanup code raises its own warning
+   after the real failure (a `ResourceWarning` from tempfile cleanup is
+   the known example), this field can point at the cleanup noise instead
+   of the actual cause. If `traceback_top_error` names a `Warning` class
+   while `pytest_failures[]` for the same job names an `Error` class,
+   trust the `pytest_failures[]` entry for what actually failed and treat
+   `traceback_top_error` as noise.
+3. `tail_excerpt[]` -- the last ~40 non-empty log lines before the job's
+   first `##[error]` marker. This is what's left when neither of the
+   above fired. Sometimes it contains an unambiguous plain-text failure
+   (for example a Go `panic:`, a shell command's final non-zero-exit message, an
+   infra tool's own `level=ERROR msg="..."` line) -- if so, use it. Other
+   times it shows the *shape* of a timeout or an in-progress hook without
+   ever stating what actually broke. Do not guess a specific root cause
+   from an inconclusive `tail_excerpt`. It is fine, and preferred, to say
+   plainly that the cause isn't visible in the available log excerpt.
+
+A job with no `pytest_failures`, no `traceback_top_error`, and a
+`tail_excerpt` that never names an exception, an error code, or an
+explicit failure message (only status-transition noise) is very likely an
+**infrastructural** failure (bootstrap, provisioning, network) rather than
+a test regression, PROVIDED the excerpt at least shows a concrete
+infra-level error. Say so explicitly -- title and body should make clear
+this is "infrastructure failing before tests could run" language, not
+"test X failed" language, and do not name a specific test as the culprit.
+
+If even that infra-level signal is missing or the excerpt is genuinely
+inconclusive, do not invent a specific-sounding title. Use a plain, honest
+title that names the workflow and says the cause is unclear from the log
+excerpt, set "confidence": "low", and say in `dedup_reason` what
+information would be needed to do better. Never fabricate a
+plausible-sounding cause to fill the gap.
+
+A run can have multiple failed jobs with different signatures. Handle this
+as follows:
+
+- If all failed jobs share essentially the same signature, treat it as one
+  failure and write one title/body for it, noting how many jobs it hit.
+- If failed jobs split into distinct signatures, decide whether one is
+  clearly the dominant, actionable story, with others being a smaller
+  number of already-familiar, separately-tracked issues riding along. If
+  so, make the dominant one the subject of `title`/`action`, and mention
+  the others in `body` as a secondary note plus in `dedup_reason`.
+- If failed jobs are multiple genuinely distinct, comparably-important
+  problems with no dominant one, use a title naming the workflow and the
+  count/spread of distinct causes and list each in `body` as its own
+  bullet. Don't pick one arbitrarily and bury the rest.
+
+## Handling multiple independent failures (`also`)
+
+When a run has a dominant story plus one or two secondary failures that
+have distinct signatures from the dominant one AND would either match a
+different existing tracked issue or themselves be dominant enough to
+warrant their own artefact if seen alone, emit an `also` array on the
+envelope with one entry per secondary. Each `also[i]` is a self-contained
+decision (its own `action`, its own `target_issue`/`title`, its own
+`confidence`, its own `dedup_reason`).
+
+Do not use `also` to split a single failure across two entries; do not
+nest `also` inside an `also` entry; cap: 2 `also` entries per envelope.
+
+## Body structure (for `action: "new"`)
+
+Use this shape, adapting to how many distinct failures you're describing:
+
+```
+## Summary
+<one or two sentences: what broke, at what scope>
+
+## Failures
+- **<job name>**: <headline error, or "infrastructure failure -- <what>",
+  or "cause unclear from the available log excerpt">
+  (omit this section entirely if there's exactly one failing job)
+
+## Likely root cause
+<ONLY include this section if the signature actually supports a specific
+hypothesis. Omit it entirely otherwise -- expected on roughly half the
+signatures you'll see. Describe the cause only; do not carry on into what
+should be done about it.>
+```
+
+Do not add sections beyond these. In particular there is no "suggested
+fix", "next steps", "workaround" or "recommendation" section, and none may
+be added.
+
+For `action: "comment"`, keep the comment short: what matches the existing
+issue (or what's new/different), and nothing else.
+
+## Deciding comment vs new
+
+You are given up to three candidate existing issues (title + excerpt), already
+pre-filtered to the same workflow by a coarser deterministic search. Some
+candidates may be marked "(closed ...)" -- these are recently-closed
+issues included for context only; never target a closed issue with
+`action: "comment"`, and never let a closed candidate alone justify
+`confidence: "high"`.
+
+- **Strong** -- at least one `pytest_failures[].test` (or, for
+  infra/tail-only failures, the same `failed_step` plus the same concrete
+  error text) matches an OPEN candidate, AND the top error class matches
+  too -> `action: "comment"`, `confidence: "high"`.
+- **Medium** -- same workflow and same `failed_step`, or same top error
+  class, but the specific test/error text has drifted, OR the only match
+  is a recently-closed candidate -> `action: "comment"` (target the open
+  issue only; if the only match is closed, use `action: "new"` instead and
+  mention the closed issue in `dedup_reason`), `confidence: "medium"`, and
+  say the drift explicitly in `body` and `dedup_reason`.
+- **Weak** -- only the workflow name matches, or only a vague thematic
+  overlap -- this is not a dedup match. `action: "new"`.
+
+Do not comment on a candidate just because one exists for the same
+workflow -- check whether the *signature* actually matches.
+
+## Labels and issue type
+
+The repository has a fixed, centrally-managed label set. You may only use
+labels from this list, and a label that does not exist in the repository is
+dropped before the issue is created, so inventing one achieves nothing:
+
+- `tests` -- the failure is in the tests or the test harness. This is the
+  common case for a failing integration or unit workflow.
+- `docs` -- the failure is in documentation building, linting or link
+  checking, or in a workflow that maintains a doc.
+- `performance` -- only where the failure *is* a performance result, such
+  as a benchmark regression or a timing threshold. Not for an ordinary
+  timeout, which is usually a hang or an infrastructure problem.
+- `small item` -- only where the signature makes it obvious the work is
+  trivial. Prefer omitting it: you cannot see the code, so you are usually
+  not in a position to judge size.
+
+An empty `labels` list is a perfectly good answer. Use it whenever none of
+the above clearly applies, rather than reaching for the nearest one.
+
+`issue_type` is "bug" when you're reasonably sure this is a defect. Use
+`null` when genuinely unsure -- this is normal and expected for
+low-confidence signatures, not an edge case.
+
+## Never
+
+- Never suggest a fix or a remedy of any kind. See "You are reporting, not
+  fixing" above; this is the constraint most easily broken by accident,
+  usually as a closing sentence offering a next step.
+- Never invent a root cause, a PR number, or a file/line that isn't
+  directly supported by the signature JSON you were given.
+- Never use a label that isn't in the list above.
+- Never output anything except the single JSON envelope object.
+"""
+
+USER_PROMPT_TEMPLATE = """\
+Workflow: {workflow_name}
+Run: {run_url}
+
+## Extracted failure signature (deterministic parser output, JSON)
+
+{signature_json}
+
+## Candidate existing open issues (same workflow, pre-filtered by title;
+## may include recently-closed issues explicitly marked as such; may be
+## empty)
+
+{candidates_block}
+
+Produce the JSON envelope now.
+"""
+
+
+def build_prompt(
+    workflow_name: str, run_url: str, signature: RunSignature, candidates_block: str
+) -> tuple[str, str]:
+    """Render the (system, user) prompt pair for the OpenRouter call."""
+    user = USER_PROMPT_TEMPLATE.format(
+        workflow_name=workflow_name,
+        run_url=run_url,
+        signature_json=signature.as_json(),
+        candidates_block=candidates_block,
+    )
+    return SYSTEM_PROMPT, user
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
new file mode 100644
index 0000000..7bc0320
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
@@ -0,0 +1,146 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Turning raw job logs into a deterministic failure signature."""
+
+from __future__ import annotations
+
+from charm_tech_code.ai_failure_notifier.constants import (
+    ANSI,
+    ERROR_MARKER,
+    GO_FAIL,
+    GROUP_END,
+    GROUP_RUN_START,
+    PYTEST_SUMMARY,
+    PYTEST_SUMMARY_END,
+    TRACEBACK_END,
+    TS,
+)
+from charm_tech_code.ai_failure_notifier.models import JobSignature, PytestFailure, RunSignature
+
+# --- Signature extraction ---
+
+
+def strip_line(line: str) -> str:
+    """Remove GHA timestamp and ANSI colours."""
+    line = TS.sub('', line, count=1)
+    line = ANSI.sub('', line)
+    return line.rstrip('\r\n')
+
+
+def strip_log(text: str) -> list[str]:
+    """Split a raw job log into output lines, dropping each step's own script.
+
+    Everything between "##[group]Run ..." and "##[endgroup]" is the runner
+    echoing the step's `run:` block and env, not anything the step printed.
+    See GROUP_RUN_START above for why that matters.
+    """
+    lines: list[str] = []
+    in_step_header = False
+    for raw in text.splitlines():
+        line = strip_line(raw)
+        if GROUP_RUN_START.match(line):
+            in_step_header = True
+            continue
+        if in_step_header:
+            in_step_header = not GROUP_END.match(line)
+            continue
+        lines.append(line)
+    return lines
+
+
+def parse_job_log(
+    text: str,
+) -> tuple[list[PytestFailure], list[str], str | None, list[str]]:
+    """Parse one job's raw log text.
+
+    Returns (pytest_failures, go_failures, traceback_top_error, tail_excerpt).
+    """
+    lines = strip_log(text)
+
+    pytest_failures: list[PytestFailure] = []
+    go_failures: list[str] = []
+    in_summary = False
+
+    for line in lines:
+        if 'short test summary info' in line:
+            in_summary = True
+            continue
+        if in_summary:
+            m = PYTEST_SUMMARY.match(line)
+            if m:
+                kind, test, err = m.groups()
+                pytest_failures.append(PytestFailure(kind, test, err.strip()))
+                continue
+            if PYTEST_SUMMARY_END.match(line):
+                in_summary = False
+        m = GO_FAIL.match(line)
+        if m:
+            go_failures.append(m.group(1))
+
+    traceback_top_error: str | None = None
+    for line in reversed(lines):
+        m = TRACEBACK_END.match(line)
+        if m:
+            traceback_top_error = f'{m.group(1)}: {m.group(2).strip()}'
+            break
+
+    error_idx = None
+    for i, line in enumerate(lines):
+        if ERROR_MARKER.search(line):
+            error_idx = i
+            break
+    tail: list[str] = []
+    if error_idx is not None:
+        for line in reversed(lines[:error_idx]):
+            if not line.strip():
+                continue
+            if line.startswith('##[group]') or line.startswith('##[endgroup]'):
+                continue
+            tail.append(line)
+            if len(tail) >= 40:
+                break
+        tail.reverse()
+
+    return pytest_failures, go_failures, traceback_top_error, tail
+
+
+def build_job_signature(
+    job_id: int, job_name: str, failed_step: str | None, log_text: str
+) -> JobSignature:
+    """Parse one job's log into its signature."""
+    pytest_failures, go_failures, traceback_top_error, tail = parse_job_log(log_text)
+    return JobSignature(
+        job_id=job_id,
+        job_name=job_name,
+        failed_step=failed_step,
+        pytest_failures=pytest_failures,
+        go_failures=go_failures,
+        traceback_top_error=traceback_top_error,
+        tail_excerpt=tail,
+    )
+
+
+def build_run_signature(
+    run_id: str, workflow_name: str, html_url: str, created_at: str, jobs: list[JobSignature]
+) -> RunSignature:
+    """Combine per-job signatures into the full run signature."""
+    return RunSignature(
+        run_id=str(run_id),
+        workflow_name=workflow_name,
+        html_url=html_url,
+        created_at=created_at,
+        jobs=jobs,
+    )
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/summary.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/summary.py
new file mode 100644
index 0000000..3fe543e
--- /dev/null
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/summary.py
@@ -0,0 +1,35 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""The runner's step summary, written from both the gh layer and apply."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def write_step_summary(message: str) -> None:
+    """Report a line to the job's step summary and to the log.
+
+    Always goes to stderr as well as the summary: every fallback path in this
+    script reports through here, and a fallback that only shows up in the
+    summary is invisible to anyone reading the job log or the API.
+    """
+    print(message, file=sys.stderr)
+    path = os.environ.get('GITHUB_STEP_SUMMARY')
+    if path:
+        with open(path, 'a', encoding='utf-8') as f:
+            f.write(message + '\n')
diff --git a/ai-failure-notifier/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
index a50416d..3632955 100644
--- a/ai-failure-notifier/tests/test_ai_failure_notifier.py
+++ b/ai-failure-notifier/tests/test_ai_failure_notifier.py
@@ -592,15 +592,17 @@ def _patch_common(
         gh_calls: mock.Mock,
     ) -> list[Any]:
         patches = [
-            mock.patch.object(afn, 'locate_run_markers', return_value=locate_return),
-            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn.github, 'locate_run_markers', return_value=locate_return),
+            mock.patch.object(afn.github, 'fetch_failed_jobs', return_value=[]),
             mock.patch.object(
                 afn, 'fetch_run_meta', return_value={'createdAt': '2026-06-25T01:40:15Z'}
             ),
-            mock.patch.object(afn, 'search_candidates', return_value=(FIXTURE_CANDIDATES, [])),
-            mock.patch.object(afn, 'existing_labels', return_value={'tests', 'docs'}),
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary'),
+            mock.patch.object(
+                afn.github, 'search_candidates', return_value=(FIXTURE_CANDIDATES, [])
+            ),
+            mock.patch.object(afn.github, 'existing_labels', return_value={'tests', 'docs'}),
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary'),
         ]
         return patches
 
@@ -609,7 +611,7 @@ def test_rung_zero_comments_and_skips_llm(self):
         patches = self._patch_common(locate_return=(9010, None, None), gh_calls=gh_calls)
         with (
             mock.patch.dict('os.environ', self.env, clear=True),
-            mock.patch.object(afn, 'call_openrouter') as call_openrouter,
+            mock.patch.object(afn.openrouter, 'call_openrouter') as call_openrouter,
             contextlib.ExitStack() as stack,
         ):
             for p in patches:
@@ -634,7 +636,7 @@ def test_valid_llm_response_upgrades_placeholder_in_place(self):
         }
         with (
             mock.patch.dict('os.environ', self.env, clear=True),
-            mock.patch.object(afn, 'call_openrouter', return_value=envelope),
+            mock.patch.object(afn.openrouter, 'call_openrouter', return_value=envelope),
             contextlib.ExitStack() as stack,
         ):
             for p in patches:
@@ -670,7 +672,7 @@ def test_no_api_key_uses_plain_fallback_without_calling_llm(self):
         env.pop('OPENROUTER_API_KEY')
         with (
             mock.patch.dict('os.environ', env, clear=True),
-            mock.patch.object(afn, 'call_openrouter') as call_openrouter,
+            mock.patch.object(afn.openrouter, 'call_openrouter') as call_openrouter,
             contextlib.ExitStack() as stack,
         ):
             for p in patches:
@@ -695,7 +697,7 @@ def _capture(self, stdout: str = '[]') -> mock.Mock:
 
     def test_search_issue_numbers_passes_repo_as_a_flag(self):
         gh_calls = self._capture('[{"number": 2658}]')
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             numbers = afn.search_issue_numbers('canonical/operator', 'Example Charm Tests')
         self.assertEqual(numbers, [2658])
         args = gh_calls.call_args.args
@@ -712,7 +714,7 @@ def test_search_issue_numbers_passes_repo_as_a_flag(self):
 
     def test_search_candidates_passes_state_and_search_flags(self):
         gh_calls = self._capture('[]')
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             afn.search_candidates('canonical/operator', 'Example Charm Tests')
         states: list[str] = []
         for call in gh_calls.call_args_list:
@@ -725,7 +727,7 @@ def test_search_candidates_passes_state_and_search_flags(self):
 
     def test_fetch_job_log_uses_the_rest_logs_endpoint(self):
         gh_calls = self._capture('2026-07-21T16:17:04Z some log line\n')
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         # Without --allow-escape-sequences, gh 2.9x+ writes nothing at all for
@@ -745,7 +747,7 @@ def test_fetch_job_log_retries_without_the_flag_on_an_older_gh(self):
             mock.Mock(returncode=0, stdout='2026-07-21T16:17:04Z some log line\n', stderr=''),
         ]
         gh_calls = mock.Mock(side_effect=results)
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         self.assertEqual(
@@ -765,8 +767,8 @@ def test_fetch_job_log_does_not_retry_when_the_flag_was_accepted(self):
             return_value=mock.Mock(returncode=1, stdout='', stderr='gh: Not Found (HTTP 404)')
         )
         with (
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary'),
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary'),
         ):
             afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         self.assertEqual(gh_calls.call_count, 1)
@@ -774,8 +776,8 @@ def test_fetch_job_log_does_not_retry_when_the_flag_was_accepted(self):
     def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
         gh_calls = self._capture('')
         with (
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary') as summary,
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
             log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         self.assertEqual(log, '')
@@ -787,8 +789,8 @@ def test_fetch_job_log_reports_the_status_gh_put_on_stderr(self):
             return_value=mock.Mock(returncode=1, stdout='', stderr='gh: Not Found (HTTP 404)\n')
         )
         with (
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary') as summary,
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
             afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         # A 404 (log not ready) and a 403 (no `actions: read`) are both exit 1,
@@ -798,8 +800,8 @@ def test_fetch_job_log_reports_the_status_gh_put_on_stderr(self):
     def test_fetch_job_log_says_so_when_gh_was_silent(self):
         gh_calls = self._capture('')
         with (
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary') as summary,
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
             afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
         self.assertIn('no stderr', summary.call_args.args[0])
@@ -809,7 +811,7 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
             '{"jobs": [{"databaseId": 1, "name": "j", "conclusion": "failure",'
             ' "steps": [{"name": "s", "conclusion": "failure"}]}]}'
         )
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             jobs = afn.fetch_failed_jobs('canonical/operator', '29847889218')
         self.assertEqual(jobs, [afn.FailedJob(id=1, name='j', failed_step='s')])
         args = gh_calls.call_args.args
@@ -818,7 +820,7 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
 
     def test_existing_labels_requests_the_name_field(self):
         gh_calls = self._capture('[{"name": "tests"}, {"name": "docs"}]')
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             labels = afn.existing_labels('canonical/operator')
         self.assertEqual(labels, {'tests', 'docs'})
         args = gh_calls.call_args.args
@@ -851,7 +853,7 @@ def test_marker_in_a_body_is_found_without_any_search_call(self):
             },
         ])
         gh_calls = self._gh([listing])
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         # Exactly one call, and it is the list endpoint -- not search.
@@ -871,7 +873,7 @@ def test_marker_in_a_comment_is_found_too(self):
                 'comments': [{'body': comment}],
             }
         ])
-        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing])):
+        with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
             enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
         self.assertEqual((enriched, kind, number), (None, 'comment', 2601))
 
@@ -883,7 +885,7 @@ def test_search_is_a_fallback_when_the_listing_misses(self):
             'comments': [],
         })
         gh_calls = self._gh([listing, search, view])
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         self.assertEqual(gh_calls.call_args_list[1].args[:2], ('search', 'issues'))
@@ -902,7 +904,7 @@ def test_an_unindexed_marker_still_resolves(self):
                 'comments': [],
             }
         ])
-        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing, '[]'])):
+        with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing, '[]'])):
             enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
 
@@ -914,7 +916,7 @@ def test_rung_zero_sig_marker_is_found_in_the_listing(self):
                 'comments': [],
             }
         ])
-        with mock.patch.object(afn, 'gh', side_effect=self._gh([listing])):
+        with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
             enriched, _, _ = afn.locate_run_markers('canonical/operator', '999')
         self.assertEqual(enriched, 2658)
 
@@ -1020,15 +1022,17 @@ def fake_build_prompt(
         }
         with (
             mock.patch.dict(os.environ, env, clear=True),
-            mock.patch.object(afn, 'locate_run_markers', return_value=(None, origin_kind, 9010)),
-            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
-            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
-            mock.patch.object(afn, 'search_candidates', return_value=(candidates, [])),
-            mock.patch.object(afn, 'existing_labels', return_value=set()),
-            mock.patch.object(afn, 'build_prompt', side_effect=fake_build_prompt),
-            mock.patch.object(afn, 'call_openrouter', return_value={'action': 'bogus'}),
-            mock.patch.object(afn, 'gh'),
-            mock.patch.object(afn, 'write_step_summary'),
+            mock.patch.object(
+                afn.github, 'locate_run_markers', return_value=(None, origin_kind, 9010)
+            ),
+            mock.patch.object(afn.github, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn.github, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn.github, 'search_candidates', return_value=(candidates, [])),
+            mock.patch.object(afn.github, 'existing_labels', return_value=set()),
+            mock.patch.object(afn.prompt, 'build_prompt', side_effect=fake_build_prompt),
+            mock.patch.object(afn.openrouter, 'call_openrouter', return_value={'action': 'bogus'}),
+            mock.patch.object(afn.github, 'gh'),
+            mock.patch.object(afn.summary, 'write_step_summary'),
         ):
             afn.main()
         return captured['block']
@@ -1064,7 +1068,7 @@ def test_render_body_has_footer_and_marker(self):
     def test_applied_comment_body_has_the_footer(self):
         gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
         entry: dict[str, Any] = {'action': 'comment', 'body': 'Another occurrence.'}
-        with mock.patch.object(afn, 'gh', side_effect=gh_calls):
+        with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             afn.apply_entry(
                 'canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests', default_target=7
             )
@@ -1084,8 +1088,8 @@ def test_applied_new_issue_body_has_the_footer(self):
             'issue_type': None,
         }
         with (
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'existing_labels', return_value=set()),
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.github, 'existing_labels', return_value=set()),
         ):
             afn.apply_entry('canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests')
         args = gh_calls.call_args.args
@@ -1134,12 +1138,12 @@ def test_marker_lookup_failure_does_not_crash_main(self):
         )
         with (
             mock.patch.dict('os.environ', self.env, clear=True),
-            mock.patch.object(afn, 'locate_run_markers', side_effect=RuntimeError('boom')),
-            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
-            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
-            mock.patch.object(afn, 'existing_labels', return_value=set()),
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary') as summary,
+            mock.patch.object(afn.github, 'locate_run_markers', side_effect=RuntimeError('boom')),
+            mock.patch.object(afn.github, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn.github, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn.github, 'existing_labels', return_value=set()),
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
             rc = afn.main()
         self.assertEqual(rc, 0)
@@ -1153,16 +1157,16 @@ def test_candidate_search_failure_proceeds_with_no_candidates(self):
         env = dict(self.env, OPENROUTER_API_KEY='test-key')
         with (
             mock.patch.dict('os.environ', env, clear=True),
-            mock.patch.object(afn, 'locate_run_markers', return_value=(None, 'new', 4242)),
-            mock.patch.object(afn, 'fetch_failed_jobs', return_value=[]),
-            mock.patch.object(afn, 'fetch_run_meta', return_value={'createdAt': ''}),
-            mock.patch.object(afn, 'search_candidates', side_effect=RuntimeError('boom')),
-            mock.patch.object(afn, 'existing_labels', return_value=set()),
+            mock.patch.object(afn.github, 'locate_run_markers', return_value=(None, 'new', 4242)),
+            mock.patch.object(afn.github, 'fetch_failed_jobs', return_value=[]),
+            mock.patch.object(afn.github, 'fetch_run_meta', return_value={'createdAt': ''}),
+            mock.patch.object(afn.github, 'search_candidates', side_effect=RuntimeError('boom')),
+            mock.patch.object(afn.github, 'existing_labels', return_value=set()),
             mock.patch.object(
                 afn, 'call_openrouter', return_value={'action': 'not-a-real-action'}
             ),
-            mock.patch.object(afn, 'gh', side_effect=gh_calls),
-            mock.patch.object(afn, 'write_step_summary') as summary,
+            mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
+            mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
             rc = afn.main()
         self.assertEqual(rc, 0)
@@ -1189,7 +1193,9 @@ def _response(self, content: str) -> mock.MagicMock:
     def test_posts_json_with_auth_and_schema(self):
         envelope = {'action': 'new', 'body': 'b'}
         with mock.patch.object(
-            afn.urllib.request, 'urlopen', return_value=self._response(json.dumps(envelope))
+            afn.openrouter.urllib.request,
+            'urlopen',
+            return_value=self._response(json.dumps(envelope)),
         ) as urlopen:
             result = afn.call_openrouter('sys', 'user', 'some/model', 'secret-key')
 
@@ -1226,7 +1232,7 @@ def test_http_error_propagates_so_main_can_fall_back(self):
             io.BytesIO(b''),
         )
         self.addCleanup(error.close)
-        with mock.patch.object(afn.urllib.request, 'urlopen', side_effect=error):
+        with mock.patch.object(afn.openrouter.urllib.request, 'urlopen', side_effect=error):
             with self.assertRaises(urllib.error.HTTPError):
                 afn.call_openrouter('sys', 'user', 'm', 'k')
 
@@ -1236,8 +1242,8 @@ class ResolveOriginTests(unittest.TestCase):
 
     def test_passed_issue_is_used_without_any_lookup(self):
         with (
-            mock.patch.object(afn, 'fetch_issue_texts', return_value=['no markers here']),
-            mock.patch.object(afn, 'locate_run_markers') as locate,
+            mock.patch.object(afn.github, 'fetch_issue_texts', return_value=['no markers here']),
+            mock.patch.object(afn.github, 'locate_run_markers') as locate,
         ):
             enriched, kind, origin = afn.resolve_origin('o/r', '123', 4242, 'comment')
         self.assertEqual((enriched, kind, origin), (None, 'comment', 4242))
@@ -1246,7 +1252,7 @@ def test_passed_issue_is_used_without_any_lookup(self):
 
     def test_passed_issue_wins_over_a_missing_marker(self):
         """A marker we cannot find does not make the issue the wrong issue."""
-        with mock.patch.object(afn, 'fetch_issue_texts', return_value=['']):
+        with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=['']):
             _enriched, kind, origin = afn.resolve_origin('o/r', '123', 77, 'new')
         self.assertEqual((kind, origin), ('new', 77))
 
@@ -1254,20 +1260,22 @@ def test_rung_zero_still_detected_on_the_passed_issue(self):
         """The notifier cannot tell us this: it is a fact about an earlier
         run of *this* script, so the narrowed lookup still has to find it."""
         body = f'<!-- {afn.MARKER_PREFIX}:run=123:sig=abcdef0123456789 -->'
-        with mock.patch.object(afn, 'fetch_issue_texts', return_value=[body]):
+        with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=[body]):
             enriched, _kind, origin = afn.resolve_origin('o/r', '123', 4242, 'new')
         self.assertEqual((enriched, origin), (4242, 4242))
 
     def test_rung_zero_ignores_a_marker_for_a_different_run(self):
         body = f'<!-- {afn.MARKER_PREFIX}:run=999:sig=abcdef0123456789 -->'
-        with mock.patch.object(afn, 'fetch_issue_texts', return_value=[body]):
+        with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=[body]):
             enriched, _kind, _origin = afn.resolve_origin('o/r', '123', 4242, 'new')
         self.assertIsNone(enriched)
 
     def test_no_passed_issue_falls_back_to_the_repo_wide_scan(self):
         """An unmigrated caller, or a notifier that failed before opening an
         issue, has to keep working."""
-        with mock.patch.object(afn, 'locate_run_markers', return_value=(None, 'new', 9)) as locate:
+        with mock.patch.object(
+            afn.github, 'locate_run_markers', return_value=(None, 'new', 9)
+        ) as locate:
             result = afn.resolve_origin('o/r', '123', None, None)
         self.assertEqual(result, (None, 'new', 9))
         locate.assert_called_once_with('o/r', '123')

From ebfa02f095116f5cd5059495248cb2fa7f52c515 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Wed, 26 Aug 2026 13:05:27 +1200
Subject: [PATCH 10/19] test: stop the suite being able to touch anything real

Splitting this package into modules moved `gh` from the module the tests
patch into `github.py`. `mock.patch.object` went on succeeding - the
attribute was still there - while no longer intercepting what the call sites
resolved, so the suite ran the real `gh` as whoever invoked it. It opened two
issues and posted two comments on a live repository before that was noticed,
and the only symptom was the run taking 35 seconds rather than a tenth of
one.

Two independent fixes, either of which would have been enough:

conftest.py replaces subprocess.run/Popen/call/check_call/check_output and
urllib.request.urlopen with functions that raise, for every test, so a
missing or misdirected mock fails at the boundary and names the command it
was about to run. Verified by reintroducing the exact bug: the suite fails in
0.35s quoting `gh issue create --repo ... --title t`, instead of succeeding.

The fixtures no longer name a real repository. Every `canonical/operator` in
the tests is now `example/repo`, so even a total patch failure has nowhere
real to write. The one mention left is prose in a docstring describing an
actual past run.
---
 ai-failure-notifier/tests/conftest.py         | 58 ++++++++++++++++
 .../tests/test_ai_failure_notifier.py         | 66 +++++++++----------
 2 files changed, 91 insertions(+), 33 deletions(-)
 create mode 100644 ai-failure-notifier/tests/conftest.py

diff --git a/ai-failure-notifier/tests/conftest.py b/ai-failure-notifier/tests/conftest.py
new file mode 100644
index 0000000..64c7efa
--- /dev/null
+++ b/ai-failure-notifier/tests/conftest.py
@@ -0,0 +1,58 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Nothing in this suite may reach the network or run a real subprocess.
+
+This is not belt-and-braces. The tests mock `gh` by patching the name on the
+module they import, and `mock.patch.object` keeps succeeding when a refactor
+moves that function to a different module -- the attribute is still there to
+be patched, it is just no longer the one the call sites resolve. The suite
+then shells out to the real `gh`, authenticated as whoever is running it,
+against whatever repository the fixtures name.
+
+That is not hypothetical. On 2026-08-26, splitting this package into modules
+did exactly that, and the suite opened two issues and posted two comments on
+a live repository before anyone noticed. The only visible symptom was the run
+taking 35 seconds instead of a tenth of one.
+
+So: any unpatched call fails loudly here, at the boundary, instead of
+quietly succeeding somewhere real. A test that needs one of these mocks it
+itself, which overrides this fixture for that test.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import urllib.request
+
+import pytest
+
+
+def _blocked(name: str):
+    def raise_instead(*args: object, **kwargs: object):
+        raise AssertionError(
+            f'{name} was called for real by a test. Nothing in this suite may '
+            f'run a subprocess or reach the network -- a mock is missing, or '
+            f'is patching a name the code no longer resolves. Called with: '
+            f'{args!r} {kwargs!r}'
+        )
+
+    return raise_instead
+
+
+@pytest.fixture(autouse=True)
+def no_real_side_effects(monkeypatch: pytest.MonkeyPatch) -> None:
+    for attr in ('run', 'Popen', 'call', 'check_call', 'check_output'):
+        monkeypatch.setattr(subprocess, attr, _blocked(f'subprocess.{attr}'))
+    monkeypatch.setattr(urllib.request, 'urlopen', _blocked('urllib.request.urlopen'))
diff --git a/ai-failure-notifier/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
index 3632955..7f0003e 100644
--- a/ai-failure-notifier/tests/test_ai_failure_notifier.py
+++ b/ai-failure-notifier/tests/test_ai_failure_notifier.py
@@ -45,7 +45,7 @@
 FIXTURE_SIGNATURE = afn.RunSignature(
     run_id='28141163589',
     workflow_name='Broad Charm Compatibility Tests',
-    html_url='https://github.com/canonical/operator/actions/runs/28141163589',
+    html_url='https://github.com/example/repo/actions/runs/28141163589',
     created_at='2026-06-25T01:40:15Z',
     jobs=[
         afn.JobSignature(
@@ -174,7 +174,7 @@
     'target_issue': 9010,
     'body': (
         'Another occurrence: '
-        'https://github.com/canonical/operator/actions/runs/28141163589\n'
+        'https://github.com/example/repo/actions/runs/28141163589\n'
         '\n'
         '4 of the 5 failing charms match #9010 unchanged. New this run: '
         'canonical/charm-ubuntu is now also failing its unit tests.'
@@ -578,10 +578,10 @@ class MainFlowTests(unittest.TestCase):
 
     def setUp(self):
         self.env = {
-            'REPO': 'canonical/operator',
+            'REPO': 'example/repo',
             'RUN_ID': '28141163589',
             'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
-            'RUN_URL': 'https://github.com/canonical/operator/actions/runs/28141163589',
+            'RUN_URL': 'https://github.com/example/repo/actions/runs/28141163589',
             'OPENROUTER_API_KEY': 'test-key',
         }
 
@@ -698,29 +698,29 @@ def _capture(self, stdout: str = '[]') -> mock.Mock:
     def test_search_issue_numbers_passes_repo_as_a_flag(self):
         gh_calls = self._capture('[{"number": 2658}]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            numbers = afn.search_issue_numbers('canonical/operator', 'Example Charm Tests')
+            numbers = afn.search_issue_numbers('example/repo', 'Example Charm Tests')
         self.assertEqual(numbers, [2658])
         args = gh_calls.call_args.args
         self.assertEqual(args[:2], ('search', 'issues'))
         self.assertIn('--repo', args)
-        self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+        self.assertEqual(args[args.index('--repo') + 1], 'example/repo')
         # The query is a bare positional -- no `repo:` prefix, no added quotes.
         # `gh search issues` quotes each positional as one keyword, so folding
-        # the repo in produces `repo:"canonical/operator \"text\""`, which
+        # the repo in produces `repo:"example/repo \"text\""`, which
         # GitHub rejects with "Invalid search query".
         self.assertIn('Example Charm Tests', args)
         for arg in args:
-            self.assertNotIn('repo:canonical/operator', arg)
+            self.assertNotIn('repo:example/repo', arg)
 
     def test_search_candidates_passes_state_and_search_flags(self):
         gh_calls = self._capture('[]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            afn.search_candidates('canonical/operator', 'Example Charm Tests')
+            afn.search_candidates('example/repo', 'Example Charm Tests')
         states: list[str] = []
         for call in gh_calls.call_args_list:
             args = call.args
             self.assertEqual(args[:2], ('issue', 'list'))
-            self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+            self.assertEqual(args[args.index('--repo') + 1], 'example/repo')
             self.assertEqual(args[args.index('--search') + 1], '"Example Charm Tests"')
             states.append(args[args.index('--state') + 1])
         self.assertEqual(states, ['open', 'closed'])
@@ -728,7 +728,7 @@ def test_search_candidates_passes_state_and_search_flags(self):
     def test_fetch_job_log_uses_the_rest_logs_endpoint(self):
         gh_calls = self._capture('2026-07-21T16:17:04Z some log line\n')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         # Without --allow-escape-sequences, gh 2.9x+ writes nothing at all for
         # a log with terminal escapes in it, which is every Actions log.
@@ -736,7 +736,7 @@ def test_fetch_job_log_uses_the_rest_logs_endpoint(self):
             gh_calls.call_args.args,
             (
                 'api',
-                'repos/canonical/operator/actions/jobs/88693036489/logs',
+                'repos/example/repo/actions/jobs/88693036489/logs',
                 '--allow-escape-sequences',
             ),
         )
@@ -748,17 +748,17 @@ def test_fetch_job_log_retries_without_the_flag_on_an_older_gh(self):
         ]
         gh_calls = mock.Mock(side_effect=results)
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         self.assertEqual(
             [call.args for call in gh_calls.call_args_list],
             [
                 (
                     'api',
-                    'repos/canonical/operator/actions/jobs/88693036489/logs',
+                    'repos/example/repo/actions/jobs/88693036489/logs',
                     '--allow-escape-sequences',
                 ),
-                ('api', 'repos/canonical/operator/actions/jobs/88693036489/logs'),
+                ('api', 'repos/example/repo/actions/jobs/88693036489/logs'),
             ],
         )
 
@@ -770,7 +770,7 @@ def test_fetch_job_log_does_not_retry_when_the_flag_was_accepted(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary'),
         ):
-            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertEqual(gh_calls.call_count, 1)
 
     def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
@@ -779,7 +779,7 @@ def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            log = afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertEqual(log, '')
         summary.assert_called_once()
         self.assertIn('no log text', summary.call_args.args[0])
@@ -792,7 +792,7 @@ def test_fetch_job_log_reports_the_status_gh_put_on_stderr(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         # A 404 (log not ready) and a 403 (no `actions: read`) are both exit 1,
         # so the status has to reach the summary for either to be diagnosable.
         self.assertIn('HTTP 404', summary.call_args.args[0])
@@ -803,7 +803,7 @@ def test_fetch_job_log_says_so_when_gh_was_silent(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            afn.fetch_job_log('canonical/operator', '29847889218', 88693036489)
+            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('no stderr', summary.call_args.args[0])
 
     def test_fetch_failed_jobs_requests_the_jobs_field(self):
@@ -812,7 +812,7 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
             ' "steps": [{"name": "s", "conclusion": "failure"}]}]}'
         )
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            jobs = afn.fetch_failed_jobs('canonical/operator', '29847889218')
+            jobs = afn.fetch_failed_jobs('example/repo', '29847889218')
         self.assertEqual(jobs, [afn.FailedJob(id=1, name='j', failed_step='s')])
         args = gh_calls.call_args.args
         self.assertEqual(args[:3], ('run', 'view', '29847889218'))
@@ -821,7 +821,7 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
     def test_existing_labels_requests_the_name_field(self):
         gh_calls = self._capture('[{"name": "tests"}, {"name": "docs"}]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            labels = afn.existing_labels('canonical/operator')
+            labels = afn.existing_labels('example/repo')
         self.assertEqual(labels, {'tests', 'docs'})
         args = gh_calls.call_args.args
         self.assertEqual(args[:2], ('label', 'list'))
@@ -854,13 +854,13 @@ def test_marker_in_a_body_is_found_without_any_search_call(self):
         ])
         gh_calls = self._gh([listing])
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         # Exactly one call, and it is the list endpoint -- not search.
         self.assertEqual(gh_calls.call_count, 1)
         args = gh_calls.call_args.args
         self.assertEqual(args[:2], ('issue', 'list'))
-        self.assertEqual(args[args.index('--repo') + 1], 'canonical/operator')
+        self.assertEqual(args[args.index('--repo') + 1], 'example/repo')
         self.assertEqual(args[args.index('--state') + 1], 'all')
         self.assertEqual(args[args.index('--json') + 1], 'number,body,comments')
 
@@ -874,7 +874,7 @@ def test_marker_in_a_comment_is_found_too(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
-            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'comment', 2601))
 
     def test_search_is_a_fallback_when_the_listing_misses(self):
@@ -886,7 +886,7 @@ def test_search_is_a_fallback_when_the_listing_misses(self):
         })
         gh_calls = self._gh([listing, search, view])
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         self.assertEqual(gh_calls.call_args_list[1].args[:2], ('search', 'issues'))
 
@@ -905,7 +905,7 @@ def test_an_unindexed_marker_still_resolves(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing, '[]'])):
-            enriched, kind, number = afn.locate_run_markers('canonical/operator', '999')
+            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
 
     def test_rung_zero_sig_marker_is_found_in_the_listing(self):
@@ -917,7 +917,7 @@ def test_rung_zero_sig_marker_is_found_in_the_listing(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
-            enriched, _, _ = afn.locate_run_markers('canonical/operator', '999')
+            enriched, _, _ = afn.locate_run_markers('example/repo', '999')
         self.assertEqual(enriched, 2658)
 
 
@@ -1014,7 +1014,7 @@ def fake_build_prompt(
             return 'sys', 'user'
 
         env = {
-            'REPO': 'canonical/operator',
+            'REPO': 'example/repo',
             'RUN_ID': '28141163589',
             'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
             'RUN_URL': 'https://example.invalid/run',
@@ -1070,7 +1070,7 @@ def test_applied_comment_body_has_the_footer(self):
         entry: dict[str, Any] = {'action': 'comment', 'body': 'Another occurrence.'}
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
             afn.apply_entry(
-                'canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests', default_target=7
+                'example/repo', entry, '<!-- m -->', 'ops Smoke Tests', default_target=7
             )
         args = gh_calls.call_args.args
         self.assertEqual(args[:3], ('issue', 'comment', '7'))
@@ -1091,7 +1091,7 @@ def test_applied_new_issue_body_has_the_footer(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.github, 'existing_labels', return_value=set()),
         ):
-            afn.apply_entry('canonical/operator', entry, '<!-- m -->', 'ops Smoke Tests')
+            afn.apply_entry('example/repo', entry, '<!-- m -->', 'ops Smoke Tests')
         args = gh_calls.call_args.args
         self.assertIn('Workflow: ops Smoke Tests', args[args.index('--body') + 1])
 
@@ -1124,16 +1124,16 @@ class MainDegradationTests(unittest.TestCase):
 
     def setUp(self):
         self.env = {
-            'REPO': 'canonical/operator',
+            'REPO': 'example/repo',
             'RUN_ID': '28141163589',
             'WORKFLOW_NAME': 'Broad Charm Compatibility Tests',
-            'RUN_URL': 'https://github.com/canonical/operator/actions/runs/28141163589',
+            'RUN_URL': 'https://github.com/example/repo/actions/runs/28141163589',
         }
 
     def test_marker_lookup_failure_does_not_crash_main(self):
         gh_calls = mock.Mock(
             return_value=mock.Mock(
-                returncode=0, stdout='https://github.com/canonical/operator/issues/9999', stderr=''
+                returncode=0, stdout='https://github.com/example/repo/issues/9999', stderr=''
             )
         )
         with (

From 7124e4606c6207e1c9e24157df73eb199e966a6e Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@gmail.com>
Date: Wed, 26 Aug 2026 14:28:45 +1200
Subject: [PATCH 11/19] Apply suggestion from @tonyandrewmeyer

---
 ai-failure-notifier/tests/conftest.py | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/ai-failure-notifier/tests/conftest.py b/ai-failure-notifier/tests/conftest.py
index 64c7efa..8bc6488 100644
--- a/ai-failure-notifier/tests/conftest.py
+++ b/ai-failure-notifier/tests/conftest.py
@@ -20,15 +20,6 @@
 be patched, it is just no longer the one the call sites resolve. The suite
 then shells out to the real `gh`, authenticated as whoever is running it,
 against whatever repository the fixtures name.
-
-That is not hypothetical. On 2026-08-26, splitting this package into modules
-did exactly that, and the suite opened two issues and posted two comments on
-a live repository before anyone noticed. The only visible symptom was the run
-taking 35 seconds instead of a tenth of one.
-
-So: any unpatched call fails loudly here, at the boundary, instead of
-quietly succeeding somewhere real. A test that needs one of these mocks it
-itself, which overrides this fixture for that test.
 """
 
 from __future__ import annotations

From 00da87acf98efad3b6de3c6217a9e5c6deeb74f5 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@gmail.com>
Date: Wed, 26 Aug 2026 14:41:59 +1200
Subject: [PATCH 12/19] Apply suggestion from @tonyandrewmeyer

---
 .github/workflows/ci.yaml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 0ec3081..01451d9 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -15,8 +15,6 @@ jobs:
       matrix:
         # One entry per tool. Add a directory here when you add a package.
         package: [ai-failure-notifier]
-        # The versions canonical/operator tests against, since that is where
-        # this code runs.
         python-version: ['3.10', '3.12', '3.14']
     defaults:
       run:

From 58b08b75640028c883c3750c6ea26cb203200383 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@gmail.com>
Date: Wed, 26 Aug 2026 14:42:58 +1200
Subject: [PATCH 13/19] Apply suggestion from @tonyandrewmeyer

---
 .../src/charm_tech_code/ai_failure_notifier/__init__.py     | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
index c966d1d..c15bfbe 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
@@ -13,11 +13,7 @@
 # limitations under the License.
 
 
-"""Triage and enrich the issue opened when a scheduled workflow fails.
-
-Split into modules along the boundaries the single file already had. The
-public names are re-exported here so that `from charm_tech_code import
-ai_failure_notifier` keeps working as it did."""
+"""Triage and enrich the issue opened when a scheduled workflow fails."""
 
 from charm_tech_code.ai_failure_notifier.apply import (
     apply_entry,

From 99697b5e0acaa266ff6b89c904e1f80e2d5873ee Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 26 Aug 2026 22:21:23 +0000
Subject: [PATCH 14/19] refactor(ai-failure-notifier): trim __init__ re-exports
 to what's used

Only re-export names actually consumed from outside the package: the
console-script entry point (main) and the names the test suite reaches
via `afn.<name>`. Everything else is now imported from its own module
directly, as the rest of the package already does internally.

While tracing consumers, found two test mocks patching the trimmed
package-level names (`fetch_run_meta`, `call_openrouter`) rather than
the submodule the real call sites resolve against -- exactly the
footgun tests/conftest.py's no_real_side_effects fixture exists to
catch. Repointed them at afn.github / afn.openrouter to match their
sibling patches in the same blocks.
---
 .../ai_failure_notifier/__init__.py           | 58 -------------------
 .../tests/test_ai_failure_notifier.py         |  6 +-
 2 files changed, 3 insertions(+), 61 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
index c15bfbe..4d9fafc 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
@@ -17,57 +17,32 @@
 
 from charm_tech_code.ai_failure_notifier.apply import (
     apply_entry,
-    plain_fallback_body,
     render_body,
 )
 from charm_tech_code.ai_failure_notifier.candidates import (
     build_candidates_block,
-    within_window,
 )
 from charm_tech_code.ai_failure_notifier.cli import (
     main,
 )
 from charm_tech_code.ai_failure_notifier.constants import (
-    ANSI,
-    CLOSED_CANDIDATE_WINDOW_DAYS,
-    DEFAULT_MODEL,
-    ERROR_MARKER,
-    GO_FAIL,
-    GROUP_END,
-    GROUP_RUN_START,
     MARKER_PREFIX,
-    MARKER_RE,
-    MAX_CANDIDATES,
-    PYTEST_SUMMARY,
-    PYTEST_SUMMARY_END,
-    RECENT_ISSUE_SCAN,
-    TRACEBACK_END,
-    TS,
 )
 from charm_tech_code.ai_failure_notifier.envelope import (
     ENVELOPE_JSON_SCHEMA,
-    drop_inapplicable_fields,
     normalise_envelope,
-    validate_entry,
     validate_envelope,
 )
 from charm_tech_code.ai_failure_notifier.github import (
     existing_labels,
     fetch_failed_jobs,
-    fetch_issue_texts,
     fetch_job_log,
-    fetch_run_meta,
-    filter_labels,
-    gh,
-    gh_json,
     locate_run_markers,
-    recent_issue_texts,
     resolve_origin,
     search_candidates,
     search_issue_numbers,
 )
 from charm_tech_code.ai_failure_notifier.markers import (
-    Origin,
     find_run_markers,
     render_enriched_marker,
     render_notifier_marker,
@@ -83,11 +58,6 @@
 from charm_tech_code.ai_failure_notifier.openrouter import (
     call_openrouter,
 )
-from charm_tech_code.ai_failure_notifier.prompt import (
-    SYSTEM_PROMPT,
-    USER_PROMPT_TEMPLATE,
-    build_prompt,
-)
 from charm_tech_code.ai_failure_notifier.signatures import (
     build_job_signature,
     build_run_signature,
@@ -100,52 +70,26 @@
 )
 
 __all__ = [
-    'ANSI',
-    'CLOSED_CANDIDATE_WINDOW_DAYS',
     'CandidateIssue',
-    'DEFAULT_MODEL',
     'ENVELOPE_JSON_SCHEMA',
-    'ERROR_MARKER',
     'FailedJob',
-    'GO_FAIL',
-    'GROUP_END',
-    'GROUP_RUN_START',
     'JobSignature',
     'MARKER_PREFIX',
-    'MARKER_RE',
-    'MAX_CANDIDATES',
-    'Origin',
-    'PYTEST_SUMMARY',
-    'PYTEST_SUMMARY_END',
     'PytestFailure',
-    'RECENT_ISSUE_SCAN',
     'RunSignature',
-    'SYSTEM_PROMPT',
-    'TRACEBACK_END',
-    'TS',
-    'USER_PROMPT_TEMPLATE',
     'apply_entry',
     'build_candidates_block',
     'build_job_signature',
-    'build_prompt',
     'build_run_signature',
     'call_openrouter',
-    'drop_inapplicable_fields',
     'existing_labels',
     'fetch_failed_jobs',
-    'fetch_issue_texts',
     'fetch_job_log',
-    'fetch_run_meta',
-    'filter_labels',
     'find_run_markers',
-    'gh',
-    'gh_json',
     'locate_run_markers',
     'main',
     'normalise_envelope',
     'parse_job_log',
-    'plain_fallback_body',
-    'recent_issue_texts',
     'render_body',
     'render_enriched_marker',
     'render_notifier_marker',
@@ -155,8 +99,6 @@
     'signature_hash',
     'strip_line',
     'strip_log',
-    'validate_entry',
     'validate_envelope',
-    'within_window',
     'write_step_summary',
 ]
diff --git a/ai-failure-notifier/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
index 7f0003e..bbcebe5 100644
--- a/ai-failure-notifier/tests/test_ai_failure_notifier.py
+++ b/ai-failure-notifier/tests/test_ai_failure_notifier.py
@@ -595,7 +595,7 @@ def _patch_common(
             mock.patch.object(afn.github, 'locate_run_markers', return_value=locate_return),
             mock.patch.object(afn.github, 'fetch_failed_jobs', return_value=[]),
             mock.patch.object(
-                afn, 'fetch_run_meta', return_value={'createdAt': '2026-06-25T01:40:15Z'}
+                afn.github, 'fetch_run_meta', return_value={'createdAt': '2026-06-25T01:40:15Z'}
             ),
             mock.patch.object(
                 afn.github, 'search_candidates', return_value=(FIXTURE_CANDIDATES, [])
@@ -653,7 +653,7 @@ def test_invalid_llm_response_falls_back_to_plain_comment(self):
         with (
             mock.patch.dict('os.environ', self.env, clear=True),
             mock.patch.object(
-                afn, 'call_openrouter', return_value={'action': 'not-a-real-action'}
+                afn.openrouter, 'call_openrouter', return_value={'action': 'not-a-real-action'}
             ),
             contextlib.ExitStack() as stack,
         ):
@@ -1163,7 +1163,7 @@ def test_candidate_search_failure_proceeds_with_no_candidates(self):
             mock.patch.object(afn.github, 'search_candidates', side_effect=RuntimeError('boom')),
             mock.patch.object(afn.github, 'existing_labels', return_value=set()),
             mock.patch.object(
-                afn, 'call_openrouter', return_value={'action': 'not-a-real-action'}
+                afn.openrouter, 'call_openrouter', return_value={'action': 'not-a-real-action'}
             ),
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,

From 6d657f9b794b0552285a039a5dfb221e18c6b859 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 26 Aug 2026 22:21:31 +0000
Subject: [PATCH 15/19] refactor(ai-failure-notifier): drop leftover
 single-file section dividers

These "--- Section ---" comments marked boundaries within the original
2,700-line script and just repeat what the module split already says
now that each one is its own file. Removed across the package; left
comments that explain a design decision alone.
---
 .../src/charm_tech_code/ai_failure_notifier/candidates.py       | 2 --
 .../src/charm_tech_code/ai_failure_notifier/github.py           | 2 --
 .../src/charm_tech_code/ai_failure_notifier/markers.py          | 2 --
 .../src/charm_tech_code/ai_failure_notifier/models.py           | 2 --
 .../src/charm_tech_code/ai_failure_notifier/prompt.py           | 2 --
 .../src/charm_tech_code/ai_failure_notifier/signatures.py       | 2 --
 6 files changed, 12 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
index aafe3e6..64de7f5 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/candidates.py
@@ -25,8 +25,6 @@
 )
 from charm_tech_code.ai_failure_notifier.models import CandidateIssue
 
-# --- Candidate pool ---
-
 
 def within_window(iso_timestamp: str, now: datetime.datetime, days: int) -> bool:
     """Return whether `iso_timestamp` falls within `days` of `now`."""
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
index 5183e9f..2395921 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
@@ -26,8 +26,6 @@
 from charm_tech_code.ai_failure_notifier.constants import MARKER_PREFIX, RECENT_ISSUE_SCAN
 from charm_tech_code.ai_failure_notifier.models import CandidateIssue, FailedJob
 
-# --- I/O ---
-
 
 def gh(*args: str, check: bool = True) -> subprocess.CompletedProcess:
     """Run a `gh` subcommand, returning the completed process."""
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
index d171565..d4c35f7 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/markers.py
@@ -23,8 +23,6 @@
 from charm_tech_code.ai_failure_notifier.constants import MARKER_PREFIX, MARKER_RE
 from charm_tech_code.ai_failure_notifier.models import RunSignature
 
-# --- Marker + signature hashing ---
-
 
 def signature_hash(signature: RunSignature) -> str:
     """Deterministic short fingerprint of a run signature.
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
index 4c5dff8..56f68c2 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/models.py
@@ -21,8 +21,6 @@
 import json
 from typing import Any
 
-# --- Structured shapes ---
-#
 # The signature is built here, serialised into the prompt, and hashed for the
 # marker, so its shape is worth pinning down rather than passing dicts around.
 # `dataclasses.asdict` preserves field declaration order, which is what the
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
index 90285c9..b330031 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/prompt.py
@@ -19,8 +19,6 @@
 
 from charm_tech_code.ai_failure_notifier.models import RunSignature
 
-# --- Prompt building ---
-
 SYSTEM_PROMPT = """\
 You are the enrichment step of an internal CI failure-triage bot for the
 Canonical Charm Tech team. A scheduled GitHub Actions workflow just failed.
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
index 7bc0320..d6f2765 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/signatures.py
@@ -30,8 +30,6 @@
 )
 from charm_tech_code.ai_failure_notifier.models import JobSignature, PytestFailure, RunSignature
 
-# --- Signature extraction ---
-
 
 def strip_line(line: str) -> str:
     """Remove GHA timestamp and ANSI colours."""

From 411ce0d7660882a591a3e9feaaec92d860e1b820 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 26 Aug 2026 22:21:34 +0000
Subject: [PATCH 16/19] docs(ai-failure-notifier): move envelope's design note
 into its docstring

The hand-rolled-validation rationale was a comment sitting right below
the module docstring, saying the same kind of thing a docstring is for.
Folded it in.
---
 .../charm_tech_code/ai_failure_notifier/envelope.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
index e81bfc6..00aba27 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/envelope.py
@@ -13,17 +13,18 @@
 # limitations under the License.
 
 
-"""Validating the model's response envelope, hand-rolled on purpose."""
+"""Validating the model's response envelope.
+
+Hand-rolled deliberately, not the `jsonschema` package, so the script keeps
+needing nothing outside the stdlib. Mirrors ENVELOPE_JSON_SCHEMA below, which
+is what OpenRouter is asked to conform to; this re-checks it on the applier
+side.
+"""
 
 from __future__ import annotations
 
 from typing import Any
 
-# --- Envelope schema validation (hand-rolled -- deliberately not the
-# `jsonschema` package, so the script keeps needing nothing outside the stdlib.
-# Mirrors ENVELOPE_JSON_SCHEMA below, which is what OpenRouter is asked to
-# conform to; this re-checks it on the applier side.) ---
-
 _ENTRY_COMMON_REQUIRED = ('action', 'body', 'dedup_reason', 'confidence')
 _ENTRY_KNOWN_KEYS = {
     'action',

From 03514368a748804c72d907af3c1841c84554efae Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 26 Aug 2026 22:21:40 +0000
Subject: [PATCH 17/19] refactor(ai-failure-notifier): split cli.main into
 named private helpers

main() was a 250-line function covering config loading, origin
resolution, signature building, the LLM round trip, and applying the
result. Split into private helpers named for what each stage does
(_read_config, _resolve_origin, _build_run_signature, _fetch_envelope,
_apply_envelope, ...), with a _RunConfig dataclass to carry the
env-derived settings between them instead of a long parameter list.

Pure refactor: no behaviour change. The three call sites that built an
identical plain-fallback entry dict (no API key / OpenRouter call
failed / LLM output failed validation) now share one
_plain_fallback_entry helper -- same dict, same apply_entry call, one
definition instead of three copies.
---
 .../ai_failure_notifier/cli.py                | 333 +++++++++++-------
 1 file changed, 196 insertions(+), 137 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
index 136b5df..f77a4b1 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
@@ -17,9 +17,11 @@
 
 from __future__ import annotations
 
+import dataclasses
 import datetime
 import os
 import sys
+from typing import Any
 
 from charm_tech_code.ai_failure_notifier import apply as _apply
 from charm_tech_code.ai_failure_notifier import candidates as _candidates
@@ -31,25 +33,45 @@
 from charm_tech_code.ai_failure_notifier import signatures as _signatures
 from charm_tech_code.ai_failure_notifier import summary as _summary
 from charm_tech_code.ai_failure_notifier.constants import DEFAULT_MODEL, MARKER_PREFIX
+from charm_tech_code.ai_failure_notifier.models import RunSignature
 
 
-def main() -> int:
-    """Entry point: locate the run's marker, enrich or fall back, apply, and exit."""
-    repo = os.environ['REPO']
-    run_id = str(os.environ['RUN_ID'])
-    workflow_name = os.environ['WORKFLOW_NAME']
-    run_url = os.environ['RUN_URL']
-    api_key = os.environ.get('OPENROUTER_API_KEY', '')
-    model = os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL
+@dataclasses.dataclass(frozen=True)
+class _RunConfig:
+    """The environment `main` runs with, read once up front."""
+
+    repo: str
+    run_id: str
+    workflow_name: str
+    run_url: str
+    api_key: str
+    model: str
     # What the notifier did, when it tells us. Both are optional: an
     # unmigrated caller, or a notifier that failed before it got as far as an
     # issue, leaves them empty and we go looking instead.
-    notify_issue = int(os.environ['NOTIFY_ISSUE']) if os.environ.get('NOTIFY_ISSUE') else None
-    notify_origin = os.environ.get('NOTIFY_ORIGIN') or None
+    notify_issue: int | None
+    notify_origin: str | None
+
+
+def _read_config() -> _RunConfig:
+    """Read the workflow's environment into a `_RunConfig`."""
+    return _RunConfig(
+        repo=os.environ['REPO'],
+        run_id=str(os.environ['RUN_ID']),
+        workflow_name=os.environ['WORKFLOW_NAME'],
+        run_url=os.environ['RUN_URL'],
+        api_key=os.environ.get('OPENROUTER_API_KEY', ''),
+        model=os.environ.get('OPENROUTER_MODEL') or DEFAULT_MODEL,
+        notify_issue=int(os.environ['NOTIFY_ISSUE']) if os.environ.get('NOTIFY_ISSUE') else None,
+        notify_origin=os.environ.get('NOTIFY_ORIGIN') or None,
+    )
 
+
+def _resolve_origin(config: _RunConfig) -> tuple[int | None, str | None, int | None]:
+    """Locate the run's marker, degrading to "un-marked" if the lookup fails."""
     try:
-        enriched_issue, origin_kind, origin_issue = _github.resolve_origin(
-            repo, run_id, notify_issue, notify_origin
+        return _github.resolve_origin(
+            config.repo, config.run_id, config.notify_issue, config.notify_origin
         )
     except Exception as exc:  # search API rejection, rate limit, transient 5xx.
         # Nothing catches this above us: there is no workflow-level fallback
@@ -60,91 +82,112 @@ def main() -> int:
         _summary.write_step_summary(
             f'Marker lookup failed ({exc}); treating this run as un-marked.'
         )
-        enriched_issue, origin_kind, origin_issue = None, notify_origin, notify_issue
+        return None, config.notify_origin, config.notify_issue
 
-    if enriched_issue is not None:
-        # Rung zero: this run id was already fully enriched once -- a re-run of
-        # the same failing jobs re-triggered us. Comment, don't skip and don't
-        # redo the full LLM pass. On a corpus of past scheduled failures this
-        # rung accounted for half the real duplicate pairs, making it the
-        # highest-value one.
-        _github.gh(
-            'issue',
-            'comment',
-            str(enriched_issue),
-            '--repo',
-            repo,
-            '--body',
-            f'Re-run attempt still failing: {run_url}\n\n<!-- {MARKER_PREFIX}:run={run_id} -->',
-        )
-        _summary.write_step_summary(
-            f'Rung zero: run {run_id} already enriched on #{enriched_issue}; '
-            'commented re-run note.'
-        )
-        return 0
 
-    if origin_issue is None:
-        # Either a caller that has not been migrated to pass the issue
-        # through, or a marker lookup that failed. The first is the normal
-        # state of a repo part way through adopting this, so don't treat it
-        # as an anomaly -- just don't lose the notification.
-        _summary.write_step_summary(
-            'No notifier marker found for this run id; falling back to a plain issue.'
-        )
-        result = _github.gh(
-            'issue',
-            'create',
-            '--repo',
-            repo,
-            '--title',
-            f"Scheduled workflow '{workflow_name}' failed",
-            '--body',
-            _apply.plain_fallback_body(workflow_name, run_url)
-            + f'\n\n<!-- {MARKER_PREFIX}:run={run_id}:origin=new -->',
-        )
-        origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
-        origin_kind = 'new'
+def _comment_on_rerun(config: _RunConfig, enriched_issue: int) -> None:
+    """Rung zero: a re-run of the same failing jobs re-triggered us.
 
-    failed_jobs = _github.fetch_failed_jobs(repo, run_id)
+    Comment, don't skip and don't redo the full LLM pass. On a corpus of past
+    scheduled failures this rung accounted for half the real duplicate pairs,
+    making it the highest-value one.
+    """
+    _github.gh(
+        'issue',
+        'comment',
+        str(enriched_issue),
+        '--repo',
+        config.repo,
+        '--body',
+        f'Re-run attempt still failing: {config.run_url}\n\n'
+        f'<!-- {MARKER_PREFIX}:run={config.run_id} -->',
+    )
+    _summary.write_step_summary(
+        f'Rung zero: run {config.run_id} already enriched on #{enriched_issue}; '
+        'commented re-run note.'
+    )
+
+
+def _create_placeholder_issue(config: _RunConfig) -> tuple[int, str]:
+    """Open a plain placeholder issue when no origin marker was found.
+
+    Either a caller that has not been migrated to pass the issue through, or a
+    marker lookup that failed. The first is the normal state of a repo part
+    way through adopting this, so don't treat it as an anomaly -- just don't
+    lose the notification.
+    """
+    _summary.write_step_summary(
+        'No notifier marker found for this run id; falling back to a plain issue.'
+    )
+    result = _github.gh(
+        'issue',
+        'create',
+        '--repo',
+        config.repo,
+        '--title',
+        f"Scheduled workflow '{config.workflow_name}' failed",
+        '--body',
+        _apply.plain_fallback_body(config.workflow_name, config.run_url)
+        + f'\n\n<!-- {MARKER_PREFIX}:run={config.run_id}:origin=new -->',
+    )
+    origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
+    return origin_issue, 'new'
+
+
+def _build_run_signature(config: _RunConfig) -> RunSignature:
+    """Fetch the run's failed jobs and metadata, and reduce them to a signature."""
+    failed_jobs = _github.fetch_failed_jobs(config.repo, config.run_id)
     jobs_sig = [
         _signatures.build_job_signature(
-            job.id, job.name, job.failed_step, _github.fetch_job_log(repo, run_id, job.id)
+            job.id,
+            job.name,
+            job.failed_step,
+            _github.fetch_job_log(config.repo, config.run_id, job.id),
         )
         for job in failed_jobs
     ]
-    meta = _github.fetch_run_meta(repo, run_id)
-    signature = _signatures.build_run_signature(
-        run_id, workflow_name, run_url, meta.get('createdAt', ''), jobs_sig
+    meta = _github.fetch_run_meta(config.repo, config.run_id)
+    return _signatures.build_run_signature(
+        config.run_id, config.workflow_name, config.run_url, meta.get('createdAt', ''), jobs_sig
     )
-    enriched_marker = _markers.render_enriched_marker(run_id, signature)
 
-    if not api_key:
-        _summary.write_step_summary(
-            'No OPENROUTER_API_KEY configured -- using the plain fallback body.'
-        )
-        _apply.apply_entry(
-            repo,
-            {
-                'action': 'comment' if origin_kind == 'comment' else 'new',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
 
+def _plain_fallback_entry(config: _RunConfig, origin_kind: str | None, origin_issue: int) -> Any:
+    """Build the envelope-shaped entry `apply_entry` uses when there is no LLM output."""
+    if origin_kind == 'comment':
+        return {
+            'action': 'comment',
+            'body': _apply.plain_fallback_body(config.workflow_name, config.run_url),
+            'target_issue': origin_issue,
+        }
+    return {
+        'action': 'new',
+        'body': _apply.plain_fallback_body(config.workflow_name, config.run_url),
+        'title': f"Scheduled workflow '{config.workflow_name}' failed",
+        'labels': [],
+        'issue_type': None,
+    }
+
+
+def _apply_plain_fallback(
+    config: _RunConfig, origin_kind: str | None, origin_issue: int, enriched_marker: str
+) -> None:
+    """Apply the plain fallback entry against `origin_issue`."""
+    _apply.apply_entry(
+        config.repo,
+        _plain_fallback_entry(config, origin_kind, origin_issue),
+        enriched_marker,
+        config.workflow_name,
+        default_target=origin_issue,
+    )
+
+
+def _search_candidates(config: _RunConfig, origin_kind: str | None, origin_issue: int) -> str:
+    """Build the {{CANDIDATES_BLOCK}} for the prompt, degrading to "none" on search failure."""
     try:
-        open_candidates, closed_candidates = _github.search_candidates(repo, workflow_name)
+        open_candidates, closed_candidates = _github.search_candidates(
+            config.repo, config.workflow_name
+        )
     except Exception as exc:  # as above: degrade to "no candidates", don't crash.
         _summary.write_step_summary(
             f'Candidate search failed ({exc}); proceeding with no candidates.'
@@ -158,39 +201,29 @@ def main() -> int:
         # issue it should have been comparing against, so it answered "new"
         # and produced the duplicate this whole path exists to avoid.
         open_candidates = [c for c in open_candidates if c.number != origin_issue]
-    candidates_block = _candidates.build_candidates_block(
+    return _candidates.build_candidates_block(
         open_candidates, closed_candidates, datetime.datetime.now(datetime.timezone.utc)
     )
+
+
+def _fetch_envelope(
+    config: _RunConfig, origin_kind: str | None, origin_issue: int, signature: RunSignature
+) -> Any:
+    """Ask the LLM to triage the failure, returning `None` on any failure along the way."""
+    candidates_block = _search_candidates(config, origin_kind, origin_issue)
     system_prompt, user_prompt = _prompt.build_prompt(
-        workflow_name, run_url, signature, candidates_block
+        config.workflow_name, config.run_url, signature, candidates_block
     )
 
     try:
-        envelope = _openrouter.call_openrouter(system_prompt, user_prompt, model, api_key)
+        envelope = _openrouter.call_openrouter(
+            system_prompt, user_prompt, config.model, config.api_key
+        )
     except Exception as exc:  # network error, non-2xx, bad JSON, and so on.
         _summary.write_step_summary(
             f'OpenRouter call failed ({exc}); using the plain fallback body.'
         )
-        _apply.apply_entry(
-            repo,
-            {
-                'action': 'new',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
+        return None
 
     envelope, dropped_fields = _envelope.normalise_envelope(envelope)
     if dropped_fields:
@@ -205,59 +238,55 @@ def main() -> int:
         _summary.write_step_summary(
             'LLM output failed schema validation:\n' + '\n'.join(f'- {e}' for e in errors)
         )
-        _apply.apply_entry(
-            repo,
-            {
-                'action': 'new',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'title': f"Scheduled workflow '{workflow_name}' failed",
-                'labels': [],
-                'issue_type': None,
-            }
-            if origin_kind != 'comment'
-            else {
-                'action': 'comment',
-                'body': _apply.plain_fallback_body(workflow_name, run_url),
-                'target_issue': origin_issue,
-            },
-            enriched_marker,
-            workflow_name,
-            default_target=origin_issue,
-        )
-        return 0
+        return None
+
+    return envelope
+
 
+def _apply_envelope(
+    config: _RunConfig,
+    envelope: Any,
+    origin_kind: str | None,
+    origin_issue: int,
+    enriched_marker: str,
+) -> None:
+    """Act on a validated LLM envelope: upgrade, comment, or open a new issue."""
     if envelope['action'] == 'new' and origin_kind == 'new':
         # Upgrade the placeholder in place rather than creating a duplicate.
-        available = _github.existing_labels(repo)
+        available = _github.existing_labels(config.repo)
         labels = _github.filter_labels(envelope.get('labels') or [], available)
         edit_args = [
             'issue',
             'edit',
             str(origin_issue),
             '--repo',
-            repo,
+            config.repo,
             '--title',
             envelope['title'],
             '--body',
-            _apply.render_body(envelope['body'], workflow_name, enriched_marker),
+            _apply.render_body(envelope['body'], config.workflow_name, enriched_marker),
         ]
         for label in labels:
             edit_args += ['--add-label', label]
         _github.gh(*edit_args)
     elif envelope['action'] == 'comment' and envelope.get('target_issue') == origin_issue:
         _apply.apply_entry(
-            repo, envelope, enriched_marker, workflow_name, default_target=origin_issue
+            config.repo,
+            envelope,
+            enriched_marker,
+            config.workflow_name,
+            default_target=origin_issue,
         )
     elif envelope['action'] == 'comment':
         # LLM picked a different candidate than the notifier's coarse match.
-        _apply.apply_entry(repo, envelope, enriched_marker, workflow_name)
+        _apply.apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
         if origin_kind == 'comment':
             _github.gh(
                 'issue',
                 'comment',
                 str(origin_issue),
                 '--repo',
-                repo,
+                config.repo,
                 '--body',
                 f'This looks like a distinct issue -- see #{envelope["target_issue"]}.\n\n'
                 f'{enriched_marker}',
@@ -265,21 +294,51 @@ def main() -> int:
     else:
         # action == "new" but origin_kind == "comment": the coarse title
         # match landed on an unrelated older issue; this is genuinely new.
-        _apply.apply_entry(repo, envelope, enriched_marker, workflow_name)
+        _apply.apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
         _github.gh(
             'issue',
             'comment',
             str(origin_issue),
             '--repo',
-            repo,
+            config.repo,
             '--body',
             f'This looks like a distinct issue from this one -- opened separately.\n\n'
             f'{enriched_marker}',
         )
 
     for also_entry in envelope.get('also') or []:
-        _apply.apply_entry(repo, also_entry, enriched_marker, workflow_name)
+        _apply.apply_entry(config.repo, also_entry, enriched_marker, config.workflow_name)
+
+
+def main() -> int:
+    """Entry point: locate the run's marker, enrich or fall back, apply, and exit."""
+    config = _read_config()
+
+    enriched_issue, origin_kind, origin_issue = _resolve_origin(config)
+
+    if enriched_issue is not None:
+        _comment_on_rerun(config, enriched_issue)
+        return 0
+
+    if origin_issue is None:
+        origin_issue, origin_kind = _create_placeholder_issue(config)
+
+    signature = _build_run_signature(config)
+    enriched_marker = _markers.render_enriched_marker(config.run_id, signature)
+
+    if not config.api_key:
+        _summary.write_step_summary(
+            'No OPENROUTER_API_KEY configured -- using the plain fallback body.'
+        )
+        _apply_plain_fallback(config, origin_kind, origin_issue, enriched_marker)
+        return 0
+
+    envelope = _fetch_envelope(config, origin_kind, origin_issue, signature)
+    if envelope is None:
+        _apply_plain_fallback(config, origin_kind, origin_issue, enriched_marker)
+        return 0
 
+    _apply_envelope(config, envelope, origin_kind, origin_issue, enriched_marker)
     return 0
 
 

From b3a61ea4984bd54b779fe6d83706834a30f3049d Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Mon, 31 Aug 2026 08:53:53 +1200
Subject: [PATCH 18/19] refactor(ai-failure-notifier): export only the entry
 point from __init__

The package __init__ re-exported 30 names across every submodule, which
kept the flat namespace the single-file script had. That was never the
point of the split, and the earlier trim preserved it because the test
suite reached each name as afn.<name> -- the tests were written against
the old shape, so satisfying them was entrenching what the split was
meant to undo.

__init__ now exports main, the console-script entry point, and nothing
else. The tests reach each name through its owning submodule instead,
matching what the mock.patch.object targets already did for github,
summary, openrouter and prompt.
---
 .../ai_failure_notifier/__init__.py           |  88 +-------
 .../tests/test_ai_failure_notifier.py         | 206 +++++++++---------
 2 files changed, 110 insertions(+), 184 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
index 4d9fafc..3e395d9 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/__init__.py
@@ -15,90 +15,6 @@
 
 """Triage and enrich the issue opened when a scheduled workflow fails."""
 
-from charm_tech_code.ai_failure_notifier.apply import (
-    apply_entry,
-    render_body,
-)
-from charm_tech_code.ai_failure_notifier.candidates import (
-    build_candidates_block,
-)
-from charm_tech_code.ai_failure_notifier.cli import (
-    main,
-)
-from charm_tech_code.ai_failure_notifier.constants import (
-    MARKER_PREFIX,
-)
-from charm_tech_code.ai_failure_notifier.envelope import (
-    ENVELOPE_JSON_SCHEMA,
-    normalise_envelope,
-    validate_envelope,
-)
-from charm_tech_code.ai_failure_notifier.github import (
-    existing_labels,
-    fetch_failed_jobs,
-    fetch_job_log,
-    locate_run_markers,
-    resolve_origin,
-    search_candidates,
-    search_issue_numbers,
-)
-from charm_tech_code.ai_failure_notifier.markers import (
-    find_run_markers,
-    render_enriched_marker,
-    render_notifier_marker,
-    signature_hash,
-)
-from charm_tech_code.ai_failure_notifier.models import (
-    CandidateIssue,
-    FailedJob,
-    JobSignature,
-    PytestFailure,
-    RunSignature,
-)
-from charm_tech_code.ai_failure_notifier.openrouter import (
-    call_openrouter,
-)
-from charm_tech_code.ai_failure_notifier.signatures import (
-    build_job_signature,
-    build_run_signature,
-    parse_job_log,
-    strip_line,
-    strip_log,
-)
-from charm_tech_code.ai_failure_notifier.summary import (
-    write_step_summary,
-)
+from charm_tech_code.ai_failure_notifier.cli import main
 
-__all__ = [
-    'CandidateIssue',
-    'ENVELOPE_JSON_SCHEMA',
-    'FailedJob',
-    'JobSignature',
-    'MARKER_PREFIX',
-    'PytestFailure',
-    'RunSignature',
-    'apply_entry',
-    'build_candidates_block',
-    'build_job_signature',
-    'build_run_signature',
-    'call_openrouter',
-    'existing_labels',
-    'fetch_failed_jobs',
-    'fetch_job_log',
-    'find_run_markers',
-    'locate_run_markers',
-    'main',
-    'normalise_envelope',
-    'parse_job_log',
-    'render_body',
-    'render_enriched_marker',
-    'render_notifier_marker',
-    'resolve_origin',
-    'search_candidates',
-    'search_issue_numbers',
-    'signature_hash',
-    'strip_line',
-    'strip_log',
-    'validate_envelope',
-    'write_step_summary',
-]
+__all__ = ['main']
diff --git a/ai-failure-notifier/tests/test_ai_failure_notifier.py b/ai-failure-notifier/tests/test_ai_failure_notifier.py
index bbcebe5..1c0c323 100644
--- a/ai-failure-notifier/tests/test_ai_failure_notifier.py
+++ b/ai-failure-notifier/tests/test_ai_failure_notifier.py
@@ -42,28 +42,28 @@
 # (28141163589, "Broad Charm Compatibility Tests", 2026-06-25). The tail_excerpt
 # lists are trimmed for size; pytest_failures and traceback_top_error are
 # verbatim, since those are what the dedup and schema logic exercise.
-FIXTURE_SIGNATURE = afn.RunSignature(
+FIXTURE_SIGNATURE = afn.models.RunSignature(
     run_id='28141163589',
     workflow_name='Broad Charm Compatibility Tests',
     html_url='https://github.com/example/repo/actions/runs/28141163589',
     created_at='2026-06-25T01:40:15Z',
     jobs=[
-        afn.JobSignature(
+        afn.models.JobSignature(
             job_id=83338922280,
             job_name='charm-tests (canonical/charm-ubuntu, .)',
             failed_step="Run the charm's unit tests",
             pytest_failures=[
-                afn.PytestFailure(
+                afn.models.PytestFailure(
                     kind='ERROR',
                     test='tests/unit/test_charm.py::TestCharm::test_charm_ready',
                     error='PendingDeprecat...',
                 ),
-                afn.PytestFailure(
+                afn.models.PytestFailure(
                     kind='ERROR',
                     test='tests/unit/test_charm.py::TestCharm::test_hostname',
                     error='PendingDeprecation...',
                 ),
-                afn.PytestFailure(
+                afn.models.PytestFailure(
                     kind='ERROR',
                     test='tests/unit/test_charm.py::TestCharm::test_version',
                     error='PendingDeprecationW...',
@@ -81,7 +81,7 @@
                 'evaluation failed :( (2.07 seconds)',
             ],
         ),
-        afn.JobSignature(
+        afn.models.JobSignature(
             job_id=83338922315,
             job_name='charm-tests (canonical/k8s-operator, charms/worker/k8s)',
             failed_step="Run the charm's static tests",
@@ -94,12 +94,12 @@
                 'evaluation failed :( (16.06 seconds)',
             ],
         ),
-        afn.JobSignature(
+        afn.models.JobSignature(
             job_id=83338923301,
             job_name='charm-tests (canonical/seldon-core-operator, .)',
             failed_step="Run the charm's unit tests",
             pytest_failures=[
-                afn.PytestFailure(
+                afn.models.PytestFailure(
                     kind='FAILED',
                     test='tests/unit/test_operator.py::TestCharm::test_prometheus_data_set',
                     error=(
@@ -118,7 +118,7 @@
                 'unit: FAIL code 1 (8.95=setup[0.60]+cmd[8.35] seconds)',
             ],
         ),
-        afn.JobSignature(
+        afn.models.JobSignature(
             job_id=83338923304,
             job_name='charm-tests (canonical/self-signed-certificates-operator, .)',
             failed_step="Run the charm's unit tests",
@@ -131,7 +131,7 @@
                 'unit: FAIL code 2 (3.43=setup[1.18]+cmd[0.06,0.02,2.16] seconds)',
             ],
         ),
-        afn.JobSignature(
+        afn.models.JobSignature(
             job_id=83338923318,
             job_name='charm-tests (canonical/traefik-k8s-operator, .)',
             failed_step="Run the charm's unit tests",
@@ -155,7 +155,7 @@
 )
 
 FIXTURE_CANDIDATES = [
-    afn.CandidateIssue(
+    afn.models.CandidateIssue(
         number=9010,
         title='Broad Charm Compatibility Tests: 4 downstream charms failing, independent causes',
         body=(
@@ -191,7 +191,7 @@ class SignatureExtractionTests(unittest.TestCase):
     def test_strip_line_removes_timestamp_and_ansi(self):
         raw = '2026-06-25T01:40:15.8141713Z \x1b[36mhello\x1b[0m'
         self.assertEqual(
-            afn.strip_line(raw),
+            afn.signatures.strip_line(raw),
             '\x1b[36mhello\x1b[0m'.replace('\x1b[36m', '').replace('\x1b[0m', ''),
         )
 
@@ -204,19 +204,23 @@ def test_parse_job_log_pytest_failures_and_summary_bound(self):
             f'{ts}============ 2 failed in 1.23s ============',
             f'{ts}some trailing noise, not part of the summary',
         ])
-        pytest_failures, go_failures, _tb, _tail = afn.parse_job_log(log)
+        pytest_failures, go_failures, _tb, _tail = afn.signatures.parse_job_log(log)
         self.assertEqual(
             pytest_failures,
             [
-                afn.PytestFailure('FAILED', 'tests/unit/test_x.py::test_a', 'AssertionError: x'),
-                afn.PytestFailure('ERROR', 'tests/unit/test_x.py::test_b', 'PendingDeprecat...'),
+                afn.models.PytestFailure(
+                    'FAILED', 'tests/unit/test_x.py::test_a', 'AssertionError: x'
+                ),
+                afn.models.PytestFailure(
+                    'ERROR', 'tests/unit/test_x.py::test_b', 'PendingDeprecat...'
+                ),
             ],
         )
         self.assertEqual(go_failures, [])
 
     def test_parse_job_log_go_failures(self):
         log = '--- FAIL: TestFoo (0.03s)\n--- FAIL: TestBar (0.01s)\n'
-        _pytest_failures, go_failures, _tb, _tail = afn.parse_job_log(log)
+        _pytest_failures, go_failures, _tb, _tail = afn.signatures.parse_job_log(log)
         self.assertEqual(go_failures, ['TestFoo', 'TestBar'])
 
     def test_parse_job_log_traceback_top_error_prefers_last_match(self):
@@ -225,7 +229,7 @@ def test_parse_job_log_traceback_top_error_prefers_last_match(self):
             'some other output',
             'AttributeError: the real one',
         ])
-        _, _, tb, _ = afn.parse_job_log(log)
+        _, _, tb, _ = afn.signatures.parse_job_log(log)
         self.assertEqual(tb, 'AttributeError: the real one')
 
     def test_parse_job_log_tail_excerpt_stops_before_first_error_marker(self):
@@ -235,7 +239,7 @@ def test_parse_job_log_tail_excerpt_stops_before_first_error_marker(self):
             '##[error]something broke',
             'line after (should not appear in tail)',
         ])
-        _, _, _, tail = afn.parse_job_log(log)
+        _, _, _, tail = afn.signatures.parse_job_log(log)
         self.assertEqual(tail, ['line before 1', 'line before 2'])
 
     def test_parse_job_log_ignores_the_step_script_the_runner_echoes(self):
@@ -252,7 +256,7 @@ def test_parse_job_log_ignores_the_step_script_the_runner_echoes(self):
             'short test summary info',
             "FAILED test/test_model.py::TestModel::test_thing - KeyError: 'host'",
         ])
-        pytest_failures, _go, tb, _tail = afn.parse_job_log(log)
+        pytest_failures, _go, tb, _tail = afn.signatures.parse_job_log(log)
         self.assertIsNone(tb)
         self.assertEqual([f.error for f in pytest_failures], ["KeyError: 'host'"])
 
@@ -266,7 +270,7 @@ def test_parse_job_log_counts_a_failure_once_not_twice(self):
             'short test summary info',
             'FAILED test/test_model.py::TestModel::test_thing - KeyError',
         ])
-        pytest_failures, _go, _tb, _tail = afn.parse_job_log(log)
+        pytest_failures, _go, _tb, _tail = afn.signatures.parse_job_log(log)
         self.assertEqual(len(pytest_failures), 1)
 
     def test_parse_job_log_keeps_groups_the_step_itself_opened(self):
@@ -277,7 +281,7 @@ def test_parse_job_log_keeps_groups_the_step_itself_opened(self):
             'AttributeError: this is real output',
             '##[endgroup]',
         ])
-        _, _, tb, _ = afn.parse_job_log(log)
+        _, _, tb, _ = afn.signatures.parse_job_log(log)
         self.assertEqual(tb, 'AttributeError: this is real output')
 
     def test_strip_log_drops_the_env_dump_with_the_script(self):
@@ -288,14 +292,14 @@ def test_strip_log_drops_the_env_dump_with_the_script(self):
             '##[endgroup]',
             'real output',
         ])
-        self.assertEqual(afn.strip_log(log), ['real output'])
+        self.assertEqual(afn.signatures.strip_log(log), ['real output'])
 
     def test_build_run_signature_matches_fixture_shape(self):
         jobs = [
-            afn.build_job_signature(j.job_id, j.job_name, j.failed_step, '')
+            afn.signatures.build_job_signature(j.job_id, j.job_name, j.failed_step, '')
             for j in FIXTURE_SIGNATURE.jobs
         ]
-        sig = afn.build_run_signature(
+        sig = afn.signatures.build_run_signature(
             '28141163589', 'Broad Charm Compatibility Tests', 'url', '2026-06-25T01:40:15Z', jobs
         )
         self.assertEqual(sig.run_id, '28141163589')
@@ -309,34 +313,36 @@ def test_build_run_signature_matches_fixture_shape(self):
 
 class MarkerTests(unittest.TestCase):
     def test_render_and_parse_notifier_marker(self):
-        marker = afn.render_notifier_marker('123', 'new')
-        enriched, origin_kind, origin_issue = afn.find_run_markers([(42, marker)], '123')
+        marker = afn.markers.render_notifier_marker('123', 'new')
+        enriched, origin_kind, origin_issue = afn.markers.find_run_markers([(42, marker)], '123')
         self.assertIsNone(enriched)
         self.assertEqual(origin_kind, 'new')
         self.assertEqual(origin_issue, 42)
 
     def test_render_and_parse_enriched_marker_is_rung_zero(self):
-        marker = afn.render_enriched_marker('28141163589', FIXTURE_SIGNATURE)
+        marker = afn.markers.render_enriched_marker('28141163589', FIXTURE_SIGNATURE)
         run_id = '28141163589'
-        enriched, origin_kind, _origin_issue = afn.find_run_markers([(9010, marker)], run_id)
+        enriched, origin_kind, _origin_issue = afn.markers.find_run_markers(
+            [(9010, marker)], run_id
+        )
         self.assertEqual(enriched, 9010)
         self.assertIsNone(origin_kind)
 
     def test_marker_for_different_run_id_does_not_match(self):
-        marker = afn.render_notifier_marker('999', 'comment')
-        enriched, origin_kind, origin_issue = afn.find_run_markers([(1, marker)], '123')
+        marker = afn.markers.render_notifier_marker('999', 'comment')
+        enriched, origin_kind, origin_issue = afn.markers.find_run_markers([(1, marker)], '123')
         self.assertIsNone(enriched)
         self.assertIsNone(origin_kind)
         self.assertIsNone(origin_issue)
 
     def test_signature_hash_is_deterministic_and_order_independent_of_call(self):
-        h1 = afn.signature_hash(FIXTURE_SIGNATURE)
-        h2 = afn.signature_hash(FIXTURE_SIGNATURE)  # independently constructed
+        h1 = afn.markers.signature_hash(FIXTURE_SIGNATURE)
+        h2 = afn.markers.signature_hash(FIXTURE_SIGNATURE)  # independently constructed
         self.assertEqual(h1, h2)
         self.assertEqual(len(h1), 16)
 
     def test_no_marker_present_returns_all_none(self):
-        enriched, origin_kind, origin_issue = afn.find_run_markers(
+        enriched, origin_kind, origin_issue = afn.markers.find_run_markers(
             [(1, 'just a normal comment, no marker')], '123'
         )
         self.assertIsNone(enriched)
@@ -346,7 +352,7 @@ def test_no_marker_present_returns_all_none(self):
 
 class CandidateBlockTests(unittest.TestCase):
     def test_open_candidate_rendered(self):
-        block = afn.build_candidates_block(
+        block = afn.candidates.build_candidates_block(
             FIXTURE_CANDIDATES, [], datetime.datetime.now(datetime.timezone.utc)
         )
         self.assertIn('#9010', block)
@@ -354,20 +360,22 @@ def test_open_candidate_rendered(self):
         self.assertNotIn('closed', block)
 
     def test_empty_candidates_block(self):
-        block = afn.build_candidates_block([], [], datetime.datetime.now(datetime.timezone.utc))
+        block = afn.candidates.build_candidates_block(
+            [], [], datetime.datetime.now(datetime.timezone.utc)
+        )
         self.assertEqual(block, '(no open issues found for this workflow)')
 
     def test_recently_closed_candidate_is_labelled_and_capped_at_medium(self):
         now = datetime.datetime(2026, 6, 25, tzinfo=datetime.timezone.utc)
         closed = [
-            afn.CandidateIssue.from_gh({
+            afn.models.CandidateIssue.from_gh({
                 'number': 42,
                 'title': 'old thing',
                 'body': 'x',
                 'closedAt': '2026-06-20T00:00:00Z',
             })
         ]
-        block = afn.build_candidates_block([], closed, now)
+        block = afn.candidates.build_candidates_block([], closed, now)
         self.assertIn('#42', block)
         self.assertIn('closed', block)
         self.assertIn('medium-confidence', block)
@@ -375,19 +383,19 @@ def test_recently_closed_candidate_is_labelled_and_capped_at_medium(self):
     def test_closed_candidate_outside_window_is_dropped(self):
         now = datetime.datetime(2026, 6, 25, tzinfo=datetime.timezone.utc)
         closed = [
-            afn.CandidateIssue.from_gh({
+            afn.models.CandidateIssue.from_gh({
                 'number': 42,
                 'title': 'ancient',
                 'body': 'x',
                 'closedAt': '2026-01-01T00:00:00Z',
             })
         ]
-        block = afn.build_candidates_block([], closed, now)
+        block = afn.candidates.build_candidates_block([], closed, now)
         self.assertEqual(block, '(no open issues found for this workflow)')
 
     def test_candidates_capped_at_three(self):
         opens = [
-            afn.CandidateIssue.from_gh({
+            afn.models.CandidateIssue.from_gh({
                 'number': n,
                 'title': f'issue {n}',
                 'body': 'x',
@@ -395,13 +403,15 @@ def test_candidates_capped_at_three(self):
             })
             for n in range(5)
         ]
-        block = afn.build_candidates_block(opens, [], datetime.datetime.now(datetime.timezone.utc))
+        block = afn.candidates.build_candidates_block(
+            opens, [], datetime.datetime.now(datetime.timezone.utc)
+        )
         self.assertEqual(block.count('- **#'), 3)
 
 
 class SchemaValidationTests(unittest.TestCase):
     def test_valid_comment_envelope_from_fixture(self):
-        errors = afn.validate_envelope(FIXTURE_ENVELOPE)
+        errors = afn.envelope.validate_envelope(FIXTURE_ENVELOPE)
         self.assertEqual(errors, [])
 
     def test_valid_new_envelope(self):
@@ -414,7 +424,7 @@ def test_valid_new_envelope(self):
             'dedup_reason': 'no match',
             'confidence': 'low',
         }
-        self.assertEqual(afn.validate_envelope(envelope), [])
+        self.assertEqual(afn.envelope.validate_envelope(envelope), [])
 
     def test_new_envelope_with_no_labels_is_valid(self):
         # No label is mandatory: the repo's label set is centrally managed, and
@@ -428,7 +438,7 @@ def test_new_envelope_with_no_labels_is_valid(self):
             'dedup_reason': 'no match',
             'confidence': 'low',
         }
-        self.assertEqual(afn.validate_envelope(envelope), [])
+        self.assertEqual(afn.envelope.validate_envelope(envelope), [])
 
     def test_new_envelope_with_non_string_labels_is_invalid(self):
         envelope: dict[str, Any] = {
@@ -440,7 +450,7 @@ def test_new_envelope_with_non_string_labels_is_invalid(self):
             'dedup_reason': 'no match',
             'confidence': 'low',
         }
-        self.assertTrue(any('labels' in e for e in afn.validate_envelope(envelope)))
+        self.assertTrue(any('labels' in e for e in afn.envelope.validate_envelope(envelope)))
 
     def test_new_envelope_with_target_issue_is_invalid(self):
         envelope = {
@@ -453,7 +463,7 @@ def test_new_envelope_with_target_issue_is_invalid(self):
             'confidence': 'low',
             'target_issue': 5,
         }
-        errors = afn.validate_envelope(envelope)
+        errors = afn.envelope.validate_envelope(envelope)
         self.assertTrue(any('target_issue' in e for e in errors))
 
     def test_comment_envelope_with_title_is_invalid(self):
@@ -465,12 +475,12 @@ def test_comment_envelope_with_title_is_invalid(self):
             'dedup_reason': 'd',
             'confidence': 'high',
         }
-        errors = afn.validate_envelope(envelope)
+        errors = afn.envelope.validate_envelope(envelope)
         self.assertTrue(any('title' in e for e in errors))
 
     def test_bad_action_value_is_invalid(self):
         envelope = {'action': 'delete', 'body': 'b', 'dedup_reason': 'd', 'confidence': 'high'}
-        errors = afn.validate_envelope(envelope)
+        errors = afn.envelope.validate_envelope(envelope)
         self.assertTrue(any('action' in e for e in errors))
 
     def test_envelope_with_also_is_valid(self):
@@ -482,17 +492,17 @@ def test_envelope_with_also_is_valid(self):
         # substring "also", which the spurious error also contained.
         base = dict(FIXTURE_ENVELOPE)
         base['also'] = [dict(FIXTURE_ENVELOPE)]
-        self.assertEqual(afn.validate_envelope(base), [])
+        self.assertEqual(afn.envelope.validate_envelope(base), [])
 
     def test_envelope_with_empty_also_is_valid(self):
         base = dict(FIXTURE_ENVELOPE)
         base['also'] = []
-        self.assertEqual(afn.validate_envelope(base), [])
+        self.assertEqual(afn.envelope.validate_envelope(base), [])
 
     def test_genuinely_unknown_top_level_field_is_still_invalid(self):
         base = dict(FIXTURE_ENVELOPE)
         base['nonsense'] = 1
-        self.assertTrue(any('nonsense' in e for e in afn.validate_envelope(base)))
+        self.assertTrue(any('nonsense' in e for e in afn.envelope.validate_envelope(base)))
 
     def test_new_envelope_with_null_target_issue_is_valid(self):
         # The schema sent to OpenRouter is `strict`, so models return every
@@ -508,7 +518,7 @@ def test_new_envelope_with_null_target_issue_is_valid(self):
             'dedup_reason': 'd',
             'confidence': 'low',
         }
-        self.assertEqual(afn.validate_envelope(envelope), [])
+        self.assertEqual(afn.envelope.validate_envelope(envelope), [])
 
     def test_new_envelope_with_a_real_target_issue_is_still_invalid(self):
         envelope: dict[str, Any] = {
@@ -522,7 +532,7 @@ def test_new_envelope_with_a_real_target_issue_is_still_invalid(self):
             'confidence': 'low',
         }
         self.assertTrue(
-            any('target_issue' in e for e in afn.validate_envelope(envelope)),
+            any('target_issue' in e for e in afn.envelope.validate_envelope(envelope)),
         )
 
     def test_comment_envelope_with_null_new_only_fields_is_valid(self):
@@ -536,7 +546,7 @@ def test_comment_envelope_with_null_new_only_fields_is_valid(self):
             'dedup_reason': 'd',
             'confidence': 'high',
         }
-        self.assertEqual(afn.validate_envelope(envelope), [])
+        self.assertEqual(afn.envelope.validate_envelope(envelope), [])
 
     def test_comment_envelope_with_a_real_title_is_still_invalid(self):
         envelope: dict[str, Any] = {
@@ -547,12 +557,12 @@ def test_comment_envelope_with_a_real_title_is_still_invalid(self):
             'dedup_reason': 'd',
             'confidence': 'high',
         }
-        self.assertTrue(any('title' in e for e in afn.validate_envelope(envelope)))
+        self.assertTrue(any('title' in e for e in afn.envelope.validate_envelope(envelope)))
 
     def test_also_capped_at_two_entries(self):
         base = dict(FIXTURE_ENVELOPE)
         base['also'] = [dict(FIXTURE_ENVELOPE) for _ in range(3)]
-        errors = afn.validate_envelope(base)
+        errors = afn.envelope.validate_envelope(base)
         self.assertTrue(any('at most two entries' in e for e in errors), errors)
 
     def test_nested_also_is_invalid(self):
@@ -560,14 +570,14 @@ def test_nested_also_is_invalid(self):
         inner = dict(FIXTURE_ENVELOPE)
         inner['also'] = [dict(FIXTURE_ENVELOPE)]
         base['also'] = [inner]
-        errors = afn.validate_envelope(base)
+        errors = afn.envelope.validate_envelope(base)
         self.assertTrue(any("nested 'also'" in e for e in errors), errors)
 
     def test_also_entries_individually_validated(self):
         base = dict(FIXTURE_ENVELOPE)
         broken = {'action': 'comment'}  # missing body/dedup_reason/confidence/target_issue
         base['also'] = [broken]
-        errors = afn.validate_envelope(base)
+        errors = afn.envelope.validate_envelope(base)
         self.assertTrue(any('also[0]' in e for e in errors))
 
 
@@ -698,7 +708,7 @@ def _capture(self, stdout: str = '[]') -> mock.Mock:
     def test_search_issue_numbers_passes_repo_as_a_flag(self):
         gh_calls = self._capture('[{"number": 2658}]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            numbers = afn.search_issue_numbers('example/repo', 'Example Charm Tests')
+            numbers = afn.github.search_issue_numbers('example/repo', 'Example Charm Tests')
         self.assertEqual(numbers, [2658])
         args = gh_calls.call_args.args
         self.assertEqual(args[:2], ('search', 'issues'))
@@ -715,7 +725,7 @@ def test_search_issue_numbers_passes_repo_as_a_flag(self):
     def test_search_candidates_passes_state_and_search_flags(self):
         gh_calls = self._capture('[]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            afn.search_candidates('example/repo', 'Example Charm Tests')
+            afn.github.search_candidates('example/repo', 'Example Charm Tests')
         states: list[str] = []
         for call in gh_calls.call_args_list:
             args = call.args
@@ -728,7 +738,7 @@ def test_search_candidates_passes_state_and_search_flags(self):
     def test_fetch_job_log_uses_the_rest_logs_endpoint(self):
         gh_calls = self._capture('2026-07-21T16:17:04Z some log line\n')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            log = afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         # Without --allow-escape-sequences, gh 2.9x+ writes nothing at all for
         # a log with terminal escapes in it, which is every Actions log.
@@ -748,7 +758,7 @@ def test_fetch_job_log_retries_without_the_flag_on_an_older_gh(self):
         ]
         gh_calls = mock.Mock(side_effect=results)
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            log = afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('some log line', log)
         self.assertEqual(
             [call.args for call in gh_calls.call_args_list],
@@ -770,7 +780,7 @@ def test_fetch_job_log_does_not_retry_when_the_flag_was_accepted(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary'),
         ):
-            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertEqual(gh_calls.call_count, 1)
 
     def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
@@ -779,7 +789,7 @@ def test_fetch_job_log_reports_an_empty_log_instead_of_swallowing_it(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            log = afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            log = afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertEqual(log, '')
         summary.assert_called_once()
         self.assertIn('no log text', summary.call_args.args[0])
@@ -792,7 +802,7 @@ def test_fetch_job_log_reports_the_status_gh_put_on_stderr(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         # A 404 (log not ready) and a 403 (no `actions: read`) are both exit 1,
         # so the status has to reach the summary for either to be diagnosable.
         self.assertIn('HTTP 404', summary.call_args.args[0])
@@ -803,7 +813,7 @@ def test_fetch_job_log_says_so_when_gh_was_silent(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.summary, 'write_step_summary') as summary,
         ):
-            afn.fetch_job_log('example/repo', '29847889218', 88693036489)
+            afn.github.fetch_job_log('example/repo', '29847889218', 88693036489)
         self.assertIn('no stderr', summary.call_args.args[0])
 
     def test_fetch_failed_jobs_requests_the_jobs_field(self):
@@ -812,8 +822,8 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
             ' "steps": [{"name": "s", "conclusion": "failure"}]}]}'
         )
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            jobs = afn.fetch_failed_jobs('example/repo', '29847889218')
-        self.assertEqual(jobs, [afn.FailedJob(id=1, name='j', failed_step='s')])
+            jobs = afn.github.fetch_failed_jobs('example/repo', '29847889218')
+        self.assertEqual(jobs, [afn.models.FailedJob(id=1, name='j', failed_step='s')])
         args = gh_calls.call_args.args
         self.assertEqual(args[:3], ('run', 'view', '29847889218'))
         self.assertEqual(args[args.index('--json') + 1], 'jobs')
@@ -821,7 +831,7 @@ def test_fetch_failed_jobs_requests_the_jobs_field(self):
     def test_existing_labels_requests_the_name_field(self):
         gh_calls = self._capture('[{"name": "tests"}, {"name": "docs"}]')
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            labels = afn.existing_labels('example/repo')
+            labels = afn.github.existing_labels('example/repo')
         self.assertEqual(labels, {'tests', 'docs'})
         args = gh_calls.call_args.args
         self.assertEqual(args[:2], ('label', 'list'))
@@ -854,7 +864,7 @@ def test_marker_in_a_body_is_found_without_any_search_call(self):
         ])
         gh_calls = self._gh([listing])
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
+            enriched, kind, number = afn.github.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         # Exactly one call, and it is the list endpoint -- not search.
         self.assertEqual(gh_calls.call_count, 1)
@@ -874,7 +884,7 @@ def test_marker_in_a_comment_is_found_too(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
-            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
+            enriched, kind, number = afn.github.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'comment', 2601))
 
     def test_search_is_a_fallback_when_the_listing_misses(self):
@@ -886,7 +896,7 @@ def test_search_is_a_fallback_when_the_listing_misses(self):
         })
         gh_calls = self._gh([listing, search, view])
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
+            enriched, kind, number = afn.github.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
         self.assertEqual(gh_calls.call_args_list[1].args[:2], ('search', 'issues'))
 
@@ -905,7 +915,7 @@ def test_an_unindexed_marker_still_resolves(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing, '[]'])):
-            enriched, kind, number = afn.locate_run_markers('example/repo', '999')
+            enriched, kind, number = afn.github.locate_run_markers('example/repo', '999')
         self.assertEqual((enriched, kind, number), (None, 'new', 2658))
 
     def test_rung_zero_sig_marker_is_found_in_the_listing(self):
@@ -917,7 +927,7 @@ def test_rung_zero_sig_marker_is_found_in_the_listing(self):
             }
         ])
         with mock.patch.object(afn.github, 'gh', side_effect=self._gh([listing])):
-            enriched, _, _ = afn.locate_run_markers('example/repo', '999')
+            enriched, _, _ = afn.github.locate_run_markers('example/repo', '999')
         self.assertEqual(enriched, 2658)
 
 
@@ -941,13 +951,13 @@ def test_comment_loses_new_only_fields(self):
             'dedup_reason': 'd',
             'confidence': 'high',
         }
-        cleaned, dropped = afn.normalise_envelope(envelope)
+        cleaned, dropped = afn.envelope.normalise_envelope(envelope)
         self.assertEqual(
             sorted(dropped), ['envelope: issue_type', 'envelope: labels', 'envelope: title']
         )
         self.assertNotIn('title', cleaned)
         self.assertEqual(cleaned['body'], 'Another occurrence.')
-        self.assertEqual(afn.validate_envelope(cleaned), [])
+        self.assertEqual(afn.envelope.validate_envelope(cleaned), [])
 
     def test_new_loses_target_issue(self):
         envelope: dict[str, Any] = {
@@ -960,9 +970,9 @@ def test_new_loses_target_issue(self):
             'dedup_reason': 'd',
             'confidence': 'low',
         }
-        cleaned, dropped = afn.normalise_envelope(envelope)
+        cleaned, dropped = afn.envelope.normalise_envelope(envelope)
         self.assertEqual(dropped, ['envelope: target_issue'])
-        self.assertEqual(afn.validate_envelope(cleaned), [])
+        self.assertEqual(afn.envelope.validate_envelope(cleaned), [])
 
     def test_also_entries_are_normalised_too(self):
         inner: dict[str, Any] = {
@@ -983,12 +993,12 @@ def test_also_entries_are_normalised_too(self):
             'confidence': 'low',
             'also': [inner],
         }
-        cleaned, dropped = afn.normalise_envelope(envelope)
+        cleaned, dropped = afn.envelope.normalise_envelope(envelope)
         self.assertEqual(dropped, ['envelope.also[0]: title'])
-        self.assertEqual(afn.validate_envelope(cleaned), [])
+        self.assertEqual(afn.envelope.validate_envelope(cleaned), [])
 
     def test_nothing_dropped_leaves_the_envelope_alone(self):
-        cleaned, dropped = afn.normalise_envelope(FIXTURE_ENVELOPE)
+        cleaned, dropped = afn.envelope.normalise_envelope(FIXTURE_ENVELOPE)
         self.assertEqual(dropped, [])
         self.assertIs(cleaned, FIXTURE_ENVELOPE)
 
@@ -1004,7 +1014,7 @@ class CandidatePoolTests(unittest.TestCase):
     prevent.
     """
 
-    def _run_main(self, *, origin_kind: str, candidates: list[afn.CandidateIssue]) -> str:
+    def _run_main(self, *, origin_kind: str, candidates: list[afn.models.CandidateIssue]) -> str:
         captured: dict[str, str] = {}
 
         def fake_build_prompt(
@@ -1038,14 +1048,14 @@ def fake_build_prompt(
         return captured['block']
 
     def test_commented_origin_issue_is_offered_as_a_candidate(self):
-        candidate = afn.CandidateIssue(
+        candidate = afn.models.CandidateIssue(
             number=9010, title='the tracked one', body='x', closed_at=None
         )
         block = self._run_main(origin_kind='comment', candidates=[candidate])
         self.assertIn('#9010', block)
 
     def test_freshly_created_placeholder_is_not_offered_as_a_candidate(self):
-        candidate = afn.CandidateIssue(
+        candidate = afn.models.CandidateIssue(
             number=9010, title='the placeholder', body='x', closed_at=None
         )
         block = self._run_main(origin_kind='new', candidates=[candidate])
@@ -1062,14 +1072,14 @@ class BodyFooterTests(unittest.TestCase):
     """
 
     def test_render_body_has_footer_and_marker(self):
-        body = afn.render_body('Some detail.', 'Example Charm Tests', '<!-- m -->')
+        body = afn.apply.render_body('Some detail.', 'Example Charm Tests', '<!-- m -->')
         self.assertEqual(body, 'Some detail.\n\nWorkflow: Example Charm Tests\n\n<!-- m -->')
 
     def test_applied_comment_body_has_the_footer(self):
         gh_calls = mock.Mock(return_value=mock.Mock(returncode=0, stdout='', stderr=''))
         entry: dict[str, Any] = {'action': 'comment', 'body': 'Another occurrence.'}
         with mock.patch.object(afn.github, 'gh', side_effect=gh_calls):
-            afn.apply_entry(
+            afn.apply.apply_entry(
                 'example/repo', entry, '<!-- m -->', 'ops Smoke Tests', default_target=7
             )
         args = gh_calls.call_args.args
@@ -1091,7 +1101,7 @@ def test_applied_new_issue_body_has_the_footer(self):
             mock.patch.object(afn.github, 'gh', side_effect=gh_calls),
             mock.patch.object(afn.github, 'existing_labels', return_value=set()),
         ):
-            afn.apply_entry('example/repo', entry, '<!-- m -->', 'ops Smoke Tests')
+            afn.apply.apply_entry('example/repo', entry, '<!-- m -->', 'ops Smoke Tests')
         args = gh_calls.call_args.args
         self.assertIn('Workflow: ops Smoke Tests', args[args.index('--body') + 1])
 
@@ -1108,7 +1118,7 @@ def test_message_goes_to_stderr_even_with_a_summary_file(self):
             mock.patch.dict(os.environ, {'GITHUB_STEP_SUMMARY': summary_path}, clear=True),
             contextlib.redirect_stderr(stderr),
         ):
-            afn.write_step_summary('OpenRouter call failed (boom)')
+            afn.summary.write_step_summary('OpenRouter call failed (boom)')
         self.assertIn('OpenRouter call failed (boom)', stderr.getvalue())
         with open(summary_path, encoding='utf-8') as handle:
             self.assertIn('OpenRouter call failed (boom)', handle.read())
@@ -1197,7 +1207,7 @@ def test_posts_json_with_auth_and_schema(self):
             'urlopen',
             return_value=self._response(json.dumps(envelope)),
         ) as urlopen:
-            result = afn.call_openrouter('sys', 'user', 'some/model', 'secret-key')
+            result = afn.openrouter.call_openrouter('sys', 'user', 'some/model', 'secret-key')
 
         self.assertEqual(result, envelope)
         request = urlopen.call_args.args[0]
@@ -1216,7 +1226,7 @@ def test_posts_json_with_auth_and_schema(self):
         self.assertEqual(sent['messages'][1]['content'], 'user')
         self.assertEqual(sent['response_format']['type'], 'json_schema')
         self.assertEqual(
-            sent['response_format']['json_schema']['schema'], afn.ENVELOPE_JSON_SCHEMA
+            sent['response_format']['json_schema']['schema'], afn.envelope.ENVELOPE_JSON_SCHEMA
         )
         self.assertTrue(sent['response_format']['json_schema']['strict'])
 
@@ -1234,7 +1244,7 @@ def test_http_error_propagates_so_main_can_fall_back(self):
         self.addCleanup(error.close)
         with mock.patch.object(afn.openrouter.urllib.request, 'urlopen', side_effect=error):
             with self.assertRaises(urllib.error.HTTPError):
-                afn.call_openrouter('sys', 'user', 'm', 'k')
+                afn.openrouter.call_openrouter('sys', 'user', 'm', 'k')
 
 
 class ResolveOriginTests(unittest.TestCase):
@@ -1245,7 +1255,7 @@ def test_passed_issue_is_used_without_any_lookup(self):
             mock.patch.object(afn.github, 'fetch_issue_texts', return_value=['no markers here']),
             mock.patch.object(afn.github, 'locate_run_markers') as locate,
         ):
-            enriched, kind, origin = afn.resolve_origin('o/r', '123', 4242, 'comment')
+            enriched, kind, origin = afn.github.resolve_origin('o/r', '123', 4242, 'comment')
         self.assertEqual((enriched, kind, origin), (None, 'comment', 4242))
         # The read-your-writes hazard is gone because nothing is searched for.
         locate.assert_not_called()
@@ -1253,21 +1263,21 @@ def test_passed_issue_is_used_without_any_lookup(self):
     def test_passed_issue_wins_over_a_missing_marker(self):
         """A marker we cannot find does not make the issue the wrong issue."""
         with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=['']):
-            _enriched, kind, origin = afn.resolve_origin('o/r', '123', 77, 'new')
+            _enriched, kind, origin = afn.github.resolve_origin('o/r', '123', 77, 'new')
         self.assertEqual((kind, origin), ('new', 77))
 
     def test_rung_zero_still_detected_on_the_passed_issue(self):
         """The notifier cannot tell us this: it is a fact about an earlier
         run of *this* script, so the narrowed lookup still has to find it."""
-        body = f'<!-- {afn.MARKER_PREFIX}:run=123:sig=abcdef0123456789 -->'
+        body = f'<!-- {afn.constants.MARKER_PREFIX}:run=123:sig=abcdef0123456789 -->'
         with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=[body]):
-            enriched, _kind, origin = afn.resolve_origin('o/r', '123', 4242, 'new')
+            enriched, _kind, origin = afn.github.resolve_origin('o/r', '123', 4242, 'new')
         self.assertEqual((enriched, origin), (4242, 4242))
 
     def test_rung_zero_ignores_a_marker_for_a_different_run(self):
-        body = f'<!-- {afn.MARKER_PREFIX}:run=999:sig=abcdef0123456789 -->'
+        body = f'<!-- {afn.constants.MARKER_PREFIX}:run=999:sig=abcdef0123456789 -->'
         with mock.patch.object(afn.github, 'fetch_issue_texts', return_value=[body]):
-            enriched, _kind, _origin = afn.resolve_origin('o/r', '123', 4242, 'new')
+            enriched, _kind, _origin = afn.github.resolve_origin('o/r', '123', 4242, 'new')
         self.assertIsNone(enriched)
 
     def test_no_passed_issue_falls_back_to_the_repo_wide_scan(self):
@@ -1276,6 +1286,6 @@ def test_no_passed_issue_falls_back_to_the_repo_wide_scan(self):
         with mock.patch.object(
             afn.github, 'locate_run_markers', return_value=(None, 'new', 9)
         ) as locate:
-            result = afn.resolve_origin('o/r', '123', None, None)
+            result = afn.github.resolve_origin('o/r', '123', None, None)
         self.assertEqual(result, (None, 'new', 9))
         locate.assert_called_once_with('o/r', '123')

From 3efa0a710d469cc235dc2251b7903259ac4827c1 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Mon, 31 Aug 2026 08:56:27 +1200
Subject: [PATCH 19/19] refactor(ai-failure-notifier): drop the
 underscore-aliased sibling imports

cli.py, apply.py and github.py imported their siblings as `github as
_github`, `summary as _summary` and so on. Aliasing a module inside its
own package reads as though the name were private, which it isn't, and
the tests then patch the un-aliased `afn.github` anyway.

github, openrouter, prompt and summary stay module-object imports,
because the suite patches them with mock.patch.object and a name import
would resolve past the patch -- the failure conftest's
no_real_side_effects fixture exists to catch. The rest import the names
they use, which also removes the two shadowing hazards that made the
aliases look necessary: cli.py's local `envelope` and github.py's local
`markers` no longer collide with a module of the same name.
---
 .../ai_failure_notifier/apply.py              | 15 ++--
 .../ai_failure_notifier/cli.py                | 89 +++++++++----------
 .../ai_failure_notifier/github.py             | 12 +--
 3 files changed, 56 insertions(+), 60 deletions(-)

diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
index 0c3f020..34720b7 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/apply.py
@@ -19,8 +19,7 @@
 
 from typing import Any
 
-from charm_tech_code.ai_failure_notifier import github as _github
-from charm_tech_code.ai_failure_notifier import summary as _summary
+from charm_tech_code.ai_failure_notifier import github, summary
 
 
 def plain_fallback_body(workflow_name: str, run_url: str) -> str:
@@ -52,10 +51,10 @@ def apply_entry(
     if entry['action'] == 'new':
         # The repo's label set is centrally managed, so anything the model
         # asked for that doesn't exist is dropped rather than created.
-        labels = _github.filter_labels(entry.get('labels') or [], _github.existing_labels(repo))
+        labels = github.filter_labels(entry.get('labels') or [], github.existing_labels(repo))
         dropped = set(entry.get('labels') or []) - set(labels)
         if dropped:
-            _summary.write_step_summary(
+            summary.write_step_summary(
                 f'Dropped labels that do not exist in this repo: {", ".join(sorted(dropped))}.'
             )
         args = ['issue', 'create', '--repo', repo, '--title', entry['title'], '--body', body]
@@ -64,17 +63,17 @@ def apply_entry(
         issue_type = entry.get('issue_type')
         result = None
         if issue_type:
-            result = _github.gh(*args, '--type', issue_type, check=False)
+            result = github.gh(*args, '--type', issue_type, check=False)
             if result.returncode != 0:
-                _summary.write_step_summary(
+                summary.write_step_summary(
                     f'`gh issue create --type {issue_type}` failed ({result.stderr.strip()}); '
                     'retrying without --type.'
                 )
                 result = None
         if result is None:
-            result = _github.gh(*args)
+            result = github.gh(*args)
         return result.stdout.strip()
     else:
         target = entry.get('target_issue', default_target)
-        _github.gh('issue', 'comment', str(target), '--repo', repo, '--body', body)
+        github.gh('issue', 'comment', str(target), '--repo', repo, '--body', body)
         return f'commented on #{target}'
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
index f77a4b1..0566cee 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/cli.py
@@ -23,17 +23,14 @@
 import sys
 from typing import Any
 
-from charm_tech_code.ai_failure_notifier import apply as _apply
-from charm_tech_code.ai_failure_notifier import candidates as _candidates
-from charm_tech_code.ai_failure_notifier import envelope as _envelope
-from charm_tech_code.ai_failure_notifier import github as _github
-from charm_tech_code.ai_failure_notifier import markers as _markers
-from charm_tech_code.ai_failure_notifier import openrouter as _openrouter
-from charm_tech_code.ai_failure_notifier import prompt as _prompt
-from charm_tech_code.ai_failure_notifier import signatures as _signatures
-from charm_tech_code.ai_failure_notifier import summary as _summary
+from charm_tech_code.ai_failure_notifier import github, openrouter, prompt, summary
+from charm_tech_code.ai_failure_notifier.apply import apply_entry, plain_fallback_body, render_body
+from charm_tech_code.ai_failure_notifier.candidates import build_candidates_block
 from charm_tech_code.ai_failure_notifier.constants import DEFAULT_MODEL, MARKER_PREFIX
+from charm_tech_code.ai_failure_notifier.envelope import normalise_envelope, validate_envelope
+from charm_tech_code.ai_failure_notifier.markers import render_enriched_marker
 from charm_tech_code.ai_failure_notifier.models import RunSignature
+from charm_tech_code.ai_failure_notifier.signatures import build_job_signature, build_run_signature
 
 
 @dataclasses.dataclass(frozen=True)
@@ -70,7 +67,7 @@ def _read_config() -> _RunConfig:
 def _resolve_origin(config: _RunConfig) -> tuple[int | None, str | None, int | None]:
     """Locate the run's marker, degrading to "un-marked" if the lookup fails."""
     try:
-        return _github.resolve_origin(
+        return github.resolve_origin(
             config.repo, config.run_id, config.notify_issue, config.notify_origin
         )
     except Exception as exc:  # search API rejection, rate limit, transient 5xx.
@@ -79,7 +76,7 @@ def _resolve_origin(config: _RunConfig) -> tuple[int | None, str | None, int | N
         # outright rather than degrading through the paths below. When the
         # notifier told us its issue we can still carry on with that; without
         # it we continue as though the run were un-marked.
-        _summary.write_step_summary(
+        summary.write_step_summary(
             f'Marker lookup failed ({exc}); treating this run as un-marked.'
         )
         return None, config.notify_origin, config.notify_issue
@@ -92,7 +89,7 @@ def _comment_on_rerun(config: _RunConfig, enriched_issue: int) -> None:
     scheduled failures this rung accounted for half the real duplicate pairs,
     making it the highest-value one.
     """
-    _github.gh(
+    github.gh(
         'issue',
         'comment',
         str(enriched_issue),
@@ -102,7 +99,7 @@ def _comment_on_rerun(config: _RunConfig, enriched_issue: int) -> None:
         f'Re-run attempt still failing: {config.run_url}\n\n'
         f'<!-- {MARKER_PREFIX}:run={config.run_id} -->',
     )
-    _summary.write_step_summary(
+    summary.write_step_summary(
         f'Rung zero: run {config.run_id} already enriched on #{enriched_issue}; '
         'commented re-run note.'
     )
@@ -116,10 +113,10 @@ def _create_placeholder_issue(config: _RunConfig) -> tuple[int, str]:
     way through adopting this, so don't treat it as an anomaly -- just don't
     lose the notification.
     """
-    _summary.write_step_summary(
+    summary.write_step_summary(
         'No notifier marker found for this run id; falling back to a plain issue.'
     )
-    result = _github.gh(
+    result = github.gh(
         'issue',
         'create',
         '--repo',
@@ -127,7 +124,7 @@ def _create_placeholder_issue(config: _RunConfig) -> tuple[int, str]:
         '--title',
         f"Scheduled workflow '{config.workflow_name}' failed",
         '--body',
-        _apply.plain_fallback_body(config.workflow_name, config.run_url)
+        plain_fallback_body(config.workflow_name, config.run_url)
         + f'\n\n<!-- {MARKER_PREFIX}:run={config.run_id}:origin=new -->',
     )
     origin_issue = int(result.stdout.strip().rstrip('/').rsplit('/', 1)[-1])
@@ -136,18 +133,18 @@ def _create_placeholder_issue(config: _RunConfig) -> tuple[int, str]:
 
 def _build_run_signature(config: _RunConfig) -> RunSignature:
     """Fetch the run's failed jobs and metadata, and reduce them to a signature."""
-    failed_jobs = _github.fetch_failed_jobs(config.repo, config.run_id)
+    failed_jobs = github.fetch_failed_jobs(config.repo, config.run_id)
     jobs_sig = [
-        _signatures.build_job_signature(
+        build_job_signature(
             job.id,
             job.name,
             job.failed_step,
-            _github.fetch_job_log(config.repo, config.run_id, job.id),
+            github.fetch_job_log(config.repo, config.run_id, job.id),
         )
         for job in failed_jobs
     ]
-    meta = _github.fetch_run_meta(config.repo, config.run_id)
-    return _signatures.build_run_signature(
+    meta = github.fetch_run_meta(config.repo, config.run_id)
+    return build_run_signature(
         config.run_id, config.workflow_name, config.run_url, meta.get('createdAt', ''), jobs_sig
     )
 
@@ -157,12 +154,12 @@ def _plain_fallback_entry(config: _RunConfig, origin_kind: str | None, origin_is
     if origin_kind == 'comment':
         return {
             'action': 'comment',
-            'body': _apply.plain_fallback_body(config.workflow_name, config.run_url),
+            'body': plain_fallback_body(config.workflow_name, config.run_url),
             'target_issue': origin_issue,
         }
     return {
         'action': 'new',
-        'body': _apply.plain_fallback_body(config.workflow_name, config.run_url),
+        'body': plain_fallback_body(config.workflow_name, config.run_url),
         'title': f"Scheduled workflow '{config.workflow_name}' failed",
         'labels': [],
         'issue_type': None,
@@ -173,7 +170,7 @@ def _apply_plain_fallback(
     config: _RunConfig, origin_kind: str | None, origin_issue: int, enriched_marker: str
 ) -> None:
     """Apply the plain fallback entry against `origin_issue`."""
-    _apply.apply_entry(
+    apply_entry(
         config.repo,
         _plain_fallback_entry(config, origin_kind, origin_issue),
         enriched_marker,
@@ -185,11 +182,11 @@ def _apply_plain_fallback(
 def _search_candidates(config: _RunConfig, origin_kind: str | None, origin_issue: int) -> str:
     """Build the {{CANDIDATES_BLOCK}} for the prompt, degrading to "none" on search failure."""
     try:
-        open_candidates, closed_candidates = _github.search_candidates(
+        open_candidates, closed_candidates = github.search_candidates(
             config.repo, config.workflow_name
         )
     except Exception as exc:  # as above: degrade to "no candidates", don't crash.
-        _summary.write_step_summary(
+        summary.write_step_summary(
             f'Candidate search failed ({exc}); proceeding with no candidates.'
         )
         open_candidates, closed_candidates = [], []
@@ -201,7 +198,7 @@ def _search_candidates(config: _RunConfig, origin_kind: str | None, origin_issue
         # issue it should have been comparing against, so it answered "new"
         # and produced the duplicate this whole path exists to avoid.
         open_candidates = [c for c in open_candidates if c.number != origin_issue]
-    return _candidates.build_candidates_block(
+    return build_candidates_block(
         open_candidates, closed_candidates, datetime.datetime.now(datetime.timezone.utc)
     )
 
@@ -211,31 +208,31 @@ def _fetch_envelope(
 ) -> Any:
     """Ask the LLM to triage the failure, returning `None` on any failure along the way."""
     candidates_block = _search_candidates(config, origin_kind, origin_issue)
-    system_prompt, user_prompt = _prompt.build_prompt(
+    system_prompt, user_prompt = prompt.build_prompt(
         config.workflow_name, config.run_url, signature, candidates_block
     )
 
     try:
-        envelope = _openrouter.call_openrouter(
+        envelope = openrouter.call_openrouter(
             system_prompt, user_prompt, config.model, config.api_key
         )
     except Exception as exc:  # network error, non-2xx, bad JSON, and so on.
-        _summary.write_step_summary(
+        summary.write_step_summary(
             f'OpenRouter call failed ({exc}); using the plain fallback body.'
         )
         return None
 
-    envelope, dropped_fields = _envelope.normalise_envelope(envelope)
+    envelope, dropped_fields = normalise_envelope(envelope)
     if dropped_fields:
-        _summary.write_step_summary(
+        summary.write_step_summary(
             'Ignored fields that do not apply to the chosen action: '
             + ', '.join(dropped_fields)
             + '.'
         )
 
-    errors = _envelope.validate_envelope(envelope)
+    errors = validate_envelope(envelope)
     if errors:
-        _summary.write_step_summary(
+        summary.write_step_summary(
             'LLM output failed schema validation:\n' + '\n'.join(f'- {e}' for e in errors)
         )
         return None
@@ -253,8 +250,8 @@ def _apply_envelope(
     """Act on a validated LLM envelope: upgrade, comment, or open a new issue."""
     if envelope['action'] == 'new' and origin_kind == 'new':
         # Upgrade the placeholder in place rather than creating a duplicate.
-        available = _github.existing_labels(config.repo)
-        labels = _github.filter_labels(envelope.get('labels') or [], available)
+        available = github.existing_labels(config.repo)
+        labels = github.filter_labels(envelope.get('labels') or [], available)
         edit_args = [
             'issue',
             'edit',
@@ -264,13 +261,13 @@ def _apply_envelope(
             '--title',
             envelope['title'],
             '--body',
-            _apply.render_body(envelope['body'], config.workflow_name, enriched_marker),
+            render_body(envelope['body'], config.workflow_name, enriched_marker),
         ]
         for label in labels:
             edit_args += ['--add-label', label]
-        _github.gh(*edit_args)
+        github.gh(*edit_args)
     elif envelope['action'] == 'comment' and envelope.get('target_issue') == origin_issue:
-        _apply.apply_entry(
+        apply_entry(
             config.repo,
             envelope,
             enriched_marker,
@@ -279,9 +276,9 @@ def _apply_envelope(
         )
     elif envelope['action'] == 'comment':
         # LLM picked a different candidate than the notifier's coarse match.
-        _apply.apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
+        apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
         if origin_kind == 'comment':
-            _github.gh(
+            github.gh(
                 'issue',
                 'comment',
                 str(origin_issue),
@@ -294,8 +291,8 @@ def _apply_envelope(
     else:
         # action == "new" but origin_kind == "comment": the coarse title
         # match landed on an unrelated older issue; this is genuinely new.
-        _apply.apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
-        _github.gh(
+        apply_entry(config.repo, envelope, enriched_marker, config.workflow_name)
+        github.gh(
             'issue',
             'comment',
             str(origin_issue),
@@ -307,7 +304,7 @@ def _apply_envelope(
         )
 
     for also_entry in envelope.get('also') or []:
-        _apply.apply_entry(config.repo, also_entry, enriched_marker, config.workflow_name)
+        apply_entry(config.repo, also_entry, enriched_marker, config.workflow_name)
 
 
 def main() -> int:
@@ -324,10 +321,10 @@ def main() -> int:
         origin_issue, origin_kind = _create_placeholder_issue(config)
 
     signature = _build_run_signature(config)
-    enriched_marker = _markers.render_enriched_marker(config.run_id, signature)
+    enriched_marker = render_enriched_marker(config.run_id, signature)
 
     if not config.api_key:
-        _summary.write_step_summary(
+        summary.write_step_summary(
             'No OPENROUTER_API_KEY configured -- using the plain fallback body.'
         )
         _apply_plain_fallback(config, origin_kind, origin_issue, enriched_marker)
diff --git a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
index 2395921..d40b490 100644
--- a/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
+++ b/ai-failure-notifier/src/charm_tech_code/ai_failure_notifier/github.py
@@ -21,9 +21,9 @@
 import subprocess
 from typing import Any
 
-from charm_tech_code.ai_failure_notifier import markers as _markers
-from charm_tech_code.ai_failure_notifier import summary as _summary
+from charm_tech_code.ai_failure_notifier import summary
 from charm_tech_code.ai_failure_notifier.constants import MARKER_PREFIX, RECENT_ISSUE_SCAN
+from charm_tech_code.ai_failure_notifier.markers import find_run_markers
 from charm_tech_code.ai_failure_notifier.models import CandidateIssue, FailedJob
 
 
@@ -84,7 +84,7 @@ def fetch_job_log(repo: str, run_id: str, job_id: int) -> str:
         # telling a log that is not ready yet from a token that has lost
         # `actions: read`, and the two want opposite fixes.
         detail = ' '.join((result.stderr or '').split())[:200] or 'no stderr'
-        _summary.write_step_summary(
+        summary.write_step_summary(
             f'Warning: no log text for job {job_id} of run {run_id} '
             f'(gh exit {result.returncode}: {detail}); '
             f'signature will be based on the job name alone.'
@@ -180,7 +180,7 @@ def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None,
     busy enough that more than `RECENT_ISSUE_SCAN` issues were updated in
     between, where a stale index still beats no lookup at all.
     """
-    markers = _markers.find_run_markers(recent_issue_texts(repo), run_id)
+    markers = find_run_markers(recent_issue_texts(repo), run_id)
     if markers != (None, None, None):
         return markers
 
@@ -189,7 +189,7 @@ def locate_run_markers(repo: str, run_id: str) -> tuple[int | None, str | None,
     for number in hits:
         for text in fetch_issue_texts(repo, number):
             texts.append((number, text))
-    return _markers.find_run_markers(texts, run_id)
+    return find_run_markers(texts, run_id)
 
 
 def resolve_origin(
@@ -222,7 +222,7 @@ def resolve_origin(
         return locate_run_markers(repo, run_id)
 
     texts = [(notify_issue, text) for text in fetch_issue_texts(repo, notify_issue)]
-    enriched_issue, origin_kind, origin_issue = _markers.find_run_markers(texts, run_id)
+    enriched_issue, origin_kind, origin_issue = find_run_markers(texts, run_id)
     # The passed-in values win: a marker we failed to find on the issue does
     # not make the issue the wrong one.
     return enriched_issue, notify_origin or origin_kind, notify_issue