redherring 0.1.0__tar.gz

redherring-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+*.sqlite
+*.sqlite-*

redherring-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 (2026-09-28)
+
+First version.
+
+- `redherring scan`: finds runs that went green only after a re-run of the same commit, reads the
+  failed attempts' logs, and reports flaky tests, flaky jobs by cause, runner time lost and time spent red.
+- `redherring why`: explains one failed run. Each failure is a known flake, infrastructure, already
+  failing on the default branch, a policy check, or looks real. Exit codes for scripts and agents.
+- Parsers for pytest, unittest, Jest, Vitest, Playwright, Mocha, node:test, Bun, TAP, go test,
+  gotestsum, cargo test, cargo-nextest, "failed tests:" lists, RSpec, Minitest, Maven Surefire, Gradle,
+  PHPUnit, dotnet test, CTest, XCTest and ExUnit.
+- Infrastructure causes: network, package registry, rate limited, runner lost, runner environment,
+  job timeout, out of memory, disk full, service startup, test worker crash, GitHub service, AI provider.
+- Checked by two independent verdict audits on 113 real failed jobs (see the project report).
+- Text, Markdown and JSON output; a composite GitHub Action; a local cache of immutable history.
+- `--ledger`: a JSON file of past evidence that outlives GitHub's run retention (from 1 Oct 2026 runs
+  are deleted after the log-retention period).
+- `why --comment` / Action `comment: true`: one PR comment per workflow, edited in place.

redherring-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ixklo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

redherring-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.5
+Name: redherring
+Version: 0.1.0
+Summary: Find the CI failures that weren't your fault: flaky tests and infrastructure hiccups, mined from the GitHub Actions history you already have.
+Project-URL: Homepage, https://github.com/ixklo/redherring
+Project-URL: Issues, https://github.com/ixklo/redherring/issues
+Author: ixklo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,coding-agents,devtools,flaky-tests,github-actions,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# redherring
+
+**Find the CI failures that weren't your fault.**
+
+redherring reads the GitHub Actions history your repo already has and finds every run that went red, then turned green when someone re-ran the *same commit*. Nothing in the code changed between those two attempts, so whatever failed first was not caused by the commit: a flaky test, a network blip, a package registry hiccup, a runner that vanished. redherring opens the failed logs, names the tests (over 20 test-runner output formats) or the infrastructure cause, and ranks them.
+
+Then, when a build fails, `redherring why` tells you (or your coding agent) which failures are known red herrings and which ones look real.
+
+No server, no signup, nothing to install in CI first. If your repo has Actions history, the first run already has answers.
+
+![redherring scan on astral-sh/uv: 2,129 runs in 14 days, 280 went red, 94 of those (34%) turned green on a plain re-run; a table of named flaky tests, several Windows-only; flaky jobs grouped by cause](docs/demo-scan.svg)
+
+*Real output for a public repo, 28 September 2026. The "AI provider" cause is an AI code-review job failing with "Selected model is at capacity".*
+
+> **How common is this?** We ran it on 122 popular repos (1.25 million workflow runs, two weeks). For the median repo about 2% of red runs are red herrings; for a quarter of them it's 7% or more (uv 34%, VS Code 23%, Next.js 15%), and 690 runner-hours went to failed jobs that a re-run fixed. **[Read the study →](docs/study/README.md)**
+
+## Install
+
+redherring is a Python 3.11+ command-line tool. With [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx --from git+https://github.com/ixklo/redherring redherring scan OWNER/REPO
+```
+
+or `pipx install git+https://github.com/ixklo/redherring`.
+
+It needs a GitHub token to read Actions logs. If you use the [GitHub CLI](https://cli.github.com/), it borrows `gh auth token` automatically; otherwise set `GH_TOKEN`. Any token works for public repositories; private ones need `actions: read`.
+
+## `redherring scan`: what flakes in this repo?
+
+```sh
+redherring scan                       # the repo of the current checkout
+redherring scan vitejs/vite --days 14
+redherring scan owner/repo --workflow ci.yml --format md > FLAKY.md
+```
+
+You get:
+
+- **Flaky tests**: each failed and then passed on a re-run of the same commit, with how often, on how many commits, on which OS (plenty of tests only flake on Windows), and when last seen.
+- **Flaky jobs with no test named**, grouped by cause: `network`, `package registry`, `rate limited`, `runner lost`, `runner environment`, `job timeout`, `out of memory`, `disk full`, `service startup`, `test worker crash`, `GitHub service`, `AI provider`, `many tests at once` (an environment problem, not ten flaky tests), or `unknown`.
+- **What it cost**: runner time burned by the failed jobs, and how long commits sat red waiting for someone to press re-run.
+
+`--format json` gives everything, including example job links, for your own dashboards.
+
+## `redherring why`: is this failure mine?
+
+```sh
+redherring why https://github.com/owner/repo/actions/runs/123456789
+redherring why 123456789 --repo owner/repo --format json
+```
+
+![redherring why on a failed uv PR run: one test is a known flake (failed then passed on re-runs twice in 14 days), the other looks real](docs/demo-why.svg)
+
+For every failure in the run, one verdict:
+
+| verdict | meaning |
+|---|---|
+| **RED HERRING** (known flaky) | This test failed and then passed on a re-run of the same commit in the last N days. |
+| **RED HERRING** (infrastructure) | The log shows a network, registry, runner, or service problem, not a test failure. |
+| **NOT THIS CHANGE** | The latest finished run on the default branch fails this same test. |
+| **LOOKS REAL** | Never seen flaking, no infrastructure cause. Probably your change. |
+| **UNCLEAR** / **POLICY CHECK** | Can't tell from history, or a PR policy check (labels, linked issue) that passes once the PR is updated. |
+
+Exit codes make it scriptable: `0` all red herrings (or nothing failed), `1` something looks real, `3` unclear, `2` error.
+
+```sh
+redherring why "$RUN" -q && gh run rerun "$RUN" --failed
+```
+
+### For coding agents
+
+Agents lose a lot of time "fixing" failures that were never theirs, and sometimes weaken a perfectly good test to make a flake go green. Add this to your `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+## CI failures
+Before changing code because CI failed, run `redherring why <run-url> --format json`.
+- `recommendation: "rerun"`: every failure is a known flake, an infrastructure problem, or already
+  failing on main. Re-run the failed jobs (`gh run rerun <id> --failed`); don't edit code or tests for it.
+- `recommendation: "investigate"`: fix only the findings with `"red_herring": false`.
+- Never skip, loosen, or delete a test just because it is listed as flaky.
+```
+
+Or install the ready-made skill: copy [`skills/redherring/`](skills/redherring/SKILL.md) into your agent's skills folder (for Claude Code, `.claude/skills/redherring/`). More setups are in [`examples/`](examples/).
+
+## GitHub Action
+
+Explain every failed CI run, in its job summary and as a comment on the pull request:
+
+```yaml
+# .github/workflows/redherring.yml
+name: redherring
+on:
+  workflow_run:
+    workflows: [CI]          # the name of your test workflow
+    types: [completed]
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write      # only needed for comment: true
+jobs:
+  why:
+    if: github.event.workflow_run.conclusion == 'failure'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          comment: true
+```
+
+The comment is posted once per PR and workflow, then edited in place on later failures, never duplicated.
+
+Or post a weekly flaky-test report:
+
+```yaml
+on:
+  schedule: [{ cron: "0 7 * * 1" }]
+permissions:
+  actions: read
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          command: scan
+          days: "30"
+```
+
+Inputs: `command` (`why` or `scan`), `run-id`, `days` (default 14), `workflow`, `ledger`, `comment`, `cache` (default on: keeps downloaded history between runs, because the Actions token allows about 1,000 API requests an hour), `fail-on-real`, `github-token`. Output: `recommendation`. From the command line, the same comment is `redherring why <run> --comment`.
+
+## Keep your flake history: the ledger
+
+From 1 October 2026 GitHub deletes workflow runs once they pass your log-retention period (90 days by default). Past that, redherring has nothing to read. A ledger keeps the evidence:
+
+```sh
+redherring scan --ledger .github/flake-ledger.json          # merges new evidence into the file
+redherring why "$RUN" --ledger .github/flake-ledger.json    # uses it as extra history
+```
+
+The file is small JSON (one entry per failed job: test names, cause, commit, OS, link). Keep it anywhere durable. You can commit it, or carry it between scheduled runs with `actions/cache`:
+
+```yaml
+    steps:
+      - uses: actions/cache@v6
+        with:
+          path: flake-ledger.json
+          key: redherring-ledger-${{ github.run_id }}
+          restore-keys: redherring-ledger-
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          command: scan
+          ledger: flake-ledger.json
+```
+
+Entries older than a year are dropped (`--keep-days`).
+
+## How it decides
+
+redherring is deliberately strict about what it calls flaky. **Only one kind of evidence counts: the same commit failed and then passed.** That is what a re-run is. It does not guess from "failed on a PR, passed on main" or "this test fails a lot", because those are often real failures. A tool that cries wolf is worse than none.
+
+Then, per failed job:
+
+1. **Tests.** The log is cleaned (timestamps, colour codes) and read by runner-specific parsers. Test ids keep only stable parts (file, suite, name; never line numbers or timings) so the same test lines up across commits and OSes.
+2. **Infrastructure.** If no test is named, the end of the log is matched against specific signatures (`ECONNRESET`, `Could not transfer artifact`, `The runner has received a shutdown signal`, `model is at capacity`, ...).
+3. **Not flakiness at all.** Roll-up jobs ("all required jobs passed") and PR policy checks are set aside and not counted.
+
+Supported test output:
+
+| ecosystem | runners |
+|---|---|
+| Python | pytest (incl. xdist, pytest-rerunfailures), unittest |
+| JavaScript / TypeScript | Jest, Vitest (incl. workspaces), Playwright (incl. its own retries), Mocha, node:test (spec and TAP), Bun, TAP (QUnit/testem) |
+| Go | `go test`, gotestsum, test timeouts |
+| Rust | `cargo test`, cargo-nextest (incl. retries), `failed tests:` lists (Deno and other file-based runners) |
+| Ruby | RSpec, Minitest |
+| JVM | Maven Surefire, Gradle (incl. verbose test logging) |
+| others | PHPUnit, .NET (`dotnet test`), CTest, XCTest, ExUnit |
+
+Missing yours? A parser is one function and a test with a real log excerpt. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Limits, honestly
+
+- **History has an expiry date.** Job logs are kept for 90 days by default, and [from 1 October 2026](https://github.blog/changelog/2026-08-27-actions-retention-will-cover-checks-workflow-runs-and-statuses/) GitHub deletes the workflow runs themselves once they pass the repo's log retention period (90 days by default, and at most 90 days for public repos). `--days` beyond that finds nothing; use a [ledger](#keep-your-flake-history-the-ledger) to keep what was found.
+- **Only re-runs count.** Repos that never press re-run, or retry inside the job without reporting it, show fewer flakes than they have. Playwright, nextest and pytest-rerunfailures retries are recognised when they appear in a failed job's log.
+- **Big repos cost API requests.** A busy monorepo can take a few thousand requests for 30 days. redherring waits out rate limits on its own, and caches everything immutable (attempt job lists, logs) so later runs only fetch what's new.
+- **Some jobs stay "unknown".** In a study of 122 popular repos, nearly half of the red-herring jobs (46%) named neither a test nor a known infrastructure cause. Some logs genuinely say nothing ("exit 1"); others use output formats redherring doesn't parse yet. `why` treats those as "unclear", never as safe to re-run. Parser contributions fix this one format at a time.
+- **GitHub Actions only**, for now.
+
+## Privacy
+
+redherring runs on your machine (or in your own Actions runner) and talks only to the GitHub API. Downloaded logs are cached, compressed, in your user cache folder (`%LOCALAPPDATA%\redherring`, `~/Library/Caches/redherring`, or `~/.cache/redherring`; override with `REDHERRING_CACHE`). Nothing is sent anywhere else.
+
+## License
+
+MIT

redherring-0.1.0/README.md

@@ -0,0 +1,195 @@
+# redherring
+
+**Find the CI failures that weren't your fault.**
+
+redherring reads the GitHub Actions history your repo already has and finds every run that went red, then turned green when someone re-ran the *same commit*. Nothing in the code changed between those two attempts, so whatever failed first was not caused by the commit: a flaky test, a network blip, a package registry hiccup, a runner that vanished. redherring opens the failed logs, names the tests (over 20 test-runner output formats) or the infrastructure cause, and ranks them.
+
+Then, when a build fails, `redherring why` tells you (or your coding agent) which failures are known red herrings and which ones look real.
+
+No server, no signup, nothing to install in CI first. If your repo has Actions history, the first run already has answers.
+
+![redherring scan on astral-sh/uv: 2,129 runs in 14 days, 280 went red, 94 of those (34%) turned green on a plain re-run; a table of named flaky tests, several Windows-only; flaky jobs grouped by cause](docs/demo-scan.svg)
+
+*Real output for a public repo, 28 September 2026. The "AI provider" cause is an AI code-review job failing with "Selected model is at capacity".*
+
+> **How common is this?** We ran it on 122 popular repos (1.25 million workflow runs, two weeks). For the median repo about 2% of red runs are red herrings; for a quarter of them it's 7% or more (uv 34%, VS Code 23%, Next.js 15%), and 690 runner-hours went to failed jobs that a re-run fixed. **[Read the study →](docs/study/README.md)**
+
+## Install
+
+redherring is a Python 3.11+ command-line tool. With [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx --from git+https://github.com/ixklo/redherring redherring scan OWNER/REPO
+```
+
+or `pipx install git+https://github.com/ixklo/redherring`.
+
+It needs a GitHub token to read Actions logs. If you use the [GitHub CLI](https://cli.github.com/), it borrows `gh auth token` automatically; otherwise set `GH_TOKEN`. Any token works for public repositories; private ones need `actions: read`.
+
+## `redherring scan`: what flakes in this repo?
+
+```sh
+redherring scan                       # the repo of the current checkout
+redherring scan vitejs/vite --days 14
+redherring scan owner/repo --workflow ci.yml --format md > FLAKY.md
+```
+
+You get:
+
+- **Flaky tests**: each failed and then passed on a re-run of the same commit, with how often, on how many commits, on which OS (plenty of tests only flake on Windows), and when last seen.
+- **Flaky jobs with no test named**, grouped by cause: `network`, `package registry`, `rate limited`, `runner lost`, `runner environment`, `job timeout`, `out of memory`, `disk full`, `service startup`, `test worker crash`, `GitHub service`, `AI provider`, `many tests at once` (an environment problem, not ten flaky tests), or `unknown`.
+- **What it cost**: runner time burned by the failed jobs, and how long commits sat red waiting for someone to press re-run.
+
+`--format json` gives everything, including example job links, for your own dashboards.
+
+## `redherring why`: is this failure mine?
+
+```sh
+redherring why https://github.com/owner/repo/actions/runs/123456789
+redherring why 123456789 --repo owner/repo --format json
+```
+
+![redherring why on a failed uv PR run: one test is a known flake (failed then passed on re-runs twice in 14 days), the other looks real](docs/demo-why.svg)
+
+For every failure in the run, one verdict:
+
+| verdict | meaning |
+|---|---|
+| **RED HERRING** (known flaky) | This test failed and then passed on a re-run of the same commit in the last N days. |
+| **RED HERRING** (infrastructure) | The log shows a network, registry, runner, or service problem, not a test failure. |
+| **NOT THIS CHANGE** | The latest finished run on the default branch fails this same test. |
+| **LOOKS REAL** | Never seen flaking, no infrastructure cause. Probably your change. |
+| **UNCLEAR** / **POLICY CHECK** | Can't tell from history, or a PR policy check (labels, linked issue) that passes once the PR is updated. |
+
+Exit codes make it scriptable: `0` all red herrings (or nothing failed), `1` something looks real, `3` unclear, `2` error.
+
+```sh
+redherring why "$RUN" -q && gh run rerun "$RUN" --failed
+```
+
+### For coding agents
+
+Agents lose a lot of time "fixing" failures that were never theirs, and sometimes weaken a perfectly good test to make a flake go green. Add this to your `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+## CI failures
+Before changing code because CI failed, run `redherring why <run-url> --format json`.
+- `recommendation: "rerun"`: every failure is a known flake, an infrastructure problem, or already
+  failing on main. Re-run the failed jobs (`gh run rerun <id> --failed`); don't edit code or tests for it.
+- `recommendation: "investigate"`: fix only the findings with `"red_herring": false`.
+- Never skip, loosen, or delete a test just because it is listed as flaky.
+```
+
+Or install the ready-made skill: copy [`skills/redherring/`](skills/redherring/SKILL.md) into your agent's skills folder (for Claude Code, `.claude/skills/redherring/`). More setups are in [`examples/`](examples/).
+
+## GitHub Action
+
+Explain every failed CI run, in its job summary and as a comment on the pull request:
+
+```yaml
+# .github/workflows/redherring.yml
+name: redherring
+on:
+  workflow_run:
+    workflows: [CI]          # the name of your test workflow
+    types: [completed]
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write      # only needed for comment: true
+jobs:
+  why:
+    if: github.event.workflow_run.conclusion == 'failure'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          comment: true
+```
+
+The comment is posted once per PR and workflow, then edited in place on later failures, never duplicated.
+
+Or post a weekly flaky-test report:
+
+```yaml
+on:
+  schedule: [{ cron: "0 7 * * 1" }]
+permissions:
+  actions: read
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          command: scan
+          days: "30"
+```
+
+Inputs: `command` (`why` or `scan`), `run-id`, `days` (default 14), `workflow`, `ledger`, `comment`, `cache` (default on: keeps downloaded history between runs, because the Actions token allows about 1,000 API requests an hour), `fail-on-real`, `github-token`. Output: `recommendation`. From the command line, the same comment is `redherring why <run> --comment`.
+
+## Keep your flake history: the ledger
+
+From 1 October 2026 GitHub deletes workflow runs once they pass your log-retention period (90 days by default). Past that, redherring has nothing to read. A ledger keeps the evidence:
+
+```sh
+redherring scan --ledger .github/flake-ledger.json          # merges new evidence into the file
+redherring why "$RUN" --ledger .github/flake-ledger.json    # uses it as extra history
+```
+
+The file is small JSON (one entry per failed job: test names, cause, commit, OS, link). Keep it anywhere durable. You can commit it, or carry it between scheduled runs with `actions/cache`:
+
+```yaml
+    steps:
+      - uses: actions/cache@v6
+        with:
+          path: flake-ledger.json
+          key: redherring-ledger-${{ github.run_id }}
+          restore-keys: redherring-ledger-
+      - uses: ixklo/redherring@v0.1.0
+        with:
+          command: scan
+          ledger: flake-ledger.json
+```
+
+Entries older than a year are dropped (`--keep-days`).
+
+## How it decides
+
+redherring is deliberately strict about what it calls flaky. **Only one kind of evidence counts: the same commit failed and then passed.** That is what a re-run is. It does not guess from "failed on a PR, passed on main" or "this test fails a lot", because those are often real failures. A tool that cries wolf is worse than none.
+
+Then, per failed job:
+
+1. **Tests.** The log is cleaned (timestamps, colour codes) and read by runner-specific parsers. Test ids keep only stable parts (file, suite, name; never line numbers or timings) so the same test lines up across commits and OSes.
+2. **Infrastructure.** If no test is named, the end of the log is matched against specific signatures (`ECONNRESET`, `Could not transfer artifact`, `The runner has received a shutdown signal`, `model is at capacity`, ...).
+3. **Not flakiness at all.** Roll-up jobs ("all required jobs passed") and PR policy checks are set aside and not counted.
+
+Supported test output:
+
+| ecosystem | runners |
+|---|---|
+| Python | pytest (incl. xdist, pytest-rerunfailures), unittest |
+| JavaScript / TypeScript | Jest, Vitest (incl. workspaces), Playwright (incl. its own retries), Mocha, node:test (spec and TAP), Bun, TAP (QUnit/testem) |
+| Go | `go test`, gotestsum, test timeouts |
+| Rust | `cargo test`, cargo-nextest (incl. retries), `failed tests:` lists (Deno and other file-based runners) |
+| Ruby | RSpec, Minitest |
+| JVM | Maven Surefire, Gradle (incl. verbose test logging) |
+| others | PHPUnit, .NET (`dotnet test`), CTest, XCTest, ExUnit |
+
+Missing yours? A parser is one function and a test with a real log excerpt. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Limits, honestly
+
+- **History has an expiry date.** Job logs are kept for 90 days by default, and [from 1 October 2026](https://github.blog/changelog/2026-08-27-actions-retention-will-cover-checks-workflow-runs-and-statuses/) GitHub deletes the workflow runs themselves once they pass the repo's log retention period (90 days by default, and at most 90 days for public repos). `--days` beyond that finds nothing; use a [ledger](#keep-your-flake-history-the-ledger) to keep what was found.
+- **Only re-runs count.** Repos that never press re-run, or retry inside the job without reporting it, show fewer flakes than they have. Playwright, nextest and pytest-rerunfailures retries are recognised when they appear in a failed job's log.
+- **Big repos cost API requests.** A busy monorepo can take a few thousand requests for 30 days. redherring waits out rate limits on its own, and caches everything immutable (attempt job lists, logs) so later runs only fetch what's new.
+- **Some jobs stay "unknown".** In a study of 122 popular repos, nearly half of the red-herring jobs (46%) named neither a test nor a known infrastructure cause. Some logs genuinely say nothing ("exit 1"); others use output formats redherring doesn't parse yet. `why` treats those as "unclear", never as safe to re-run. Parser contributions fix this one format at a time.
+- **GitHub Actions only**, for now.
+
+## Privacy
+
+redherring runs on your machine (or in your own Actions runner) and talks only to the GitHub API. Downloaded logs are cached, compressed, in your user cache folder (`%LOCALAPPDATA%\redherring`, `~/Library/Caches/redherring`, or `~/.cache/redherring`; override with `REDHERRING_CACHE`). Nothing is sent anywhere else.
+
+## License
+
+MIT

redherring-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "redherring"
+version = "0.1.0"
+description = "Find the CI failures that weren't your fault: flaky tests and infrastructure hiccups, mined from the GitHub Actions history you already have."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ixklo" }]
+keywords = ["flaky-tests", "ci", "github-actions", "testing", "devtools", "coding-agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "httpx>=0.27",
+    "rich>=13.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/ixklo/redherring"
+Issues = "https://github.com/ixklo/redherring/issues"
+
+[project.scripts]
+redherring = "redherring.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+# The formatter owns line length; long regexes and messages stay on one line.
+ignore = ["E501"]

redherring-0.1.0/src/redherring/__init__.py

@@ -0,0 +1,3 @@
+"""redherring: find the CI failures that weren't your fault."""
+
+__version__ = "0.1.0"

redherring-0.1.0/src/redherring/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

redherring-0.1.0/src/redherring/cache.py

@@ -0,0 +1,106 @@
+"""A local cache of the parts of CI history that never change once a run is finished.
+
+Job lists of completed attempts and job logs are immutable, so re-scans only pay for the
+runs list. Logs are stored compressed so parsers can be improved without re-downloading.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+import threading
+import zlib
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS attempt_jobs (
+    repo TEXT NOT NULL, run_id INTEGER NOT NULL, attempt INTEGER NOT NULL,
+    jobs TEXT NOT NULL,
+    PRIMARY KEY (repo, run_id, attempt)
+);
+CREATE TABLE IF NOT EXISTS job_logs (
+    repo TEXT NOT NULL, job_id INTEGER NOT NULL,
+    status TEXT NOT NULL,           -- ok | gone
+    log BLOB,                       -- zlib-compressed text when status = ok
+    PRIMARY KEY (repo, job_id)
+);
+"""
+
+# Logs above this (compressed) size are truncated to their tail: the failure is at the end.
+_MAX_COMPRESSED = 4 * 1024 * 1024
+_MAX_TEXT = 12 * 1024 * 1024
+
+
+def default_path() -> Path:
+    if env := os.environ.get("REDHERRING_CACHE"):
+        return Path(env)
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    elif sys.platform == "darwin":
+        base = Path.home() / "Library" / "Caches"
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return base / "redherring" / "cache.sqlite"
+
+
+class Cache:
+    def __init__(self, path: Path | str | None = None) -> None:
+        if path == ":memory:":
+            self._db = sqlite3.connect(":memory:", check_same_thread=False)
+        else:
+            p = Path(path) if path else default_path()
+            p.parent.mkdir(parents=True, exist_ok=True)
+            self._db = sqlite3.connect(p, check_same_thread=False, isolation_level=None)
+            self._db.execute("PRAGMA journal_mode=WAL")
+        self._db.executescript(_SCHEMA)
+        self._lock = threading.Lock()
+
+    def _exec(self, sql: str, args: tuple = ()) -> None:
+        with self._lock:
+            self._db.execute(sql, args)
+
+    def _one(self, sql: str, args: tuple = ()) -> tuple | None:
+        with self._lock:
+            return self._db.execute(sql, args).fetchone()
+
+    def close(self) -> None:
+        self._db.close()
+
+    def get_attempt_jobs(self, repo: str, run_id: int, attempt: int) -> list[dict] | None:
+        row = self._one(
+            "SELECT jobs FROM attempt_jobs WHERE repo=? AND run_id=? AND attempt=?",
+            (repo, run_id, attempt),
+        )
+        return json.loads(row[0]) if row else None
+
+    def put_attempt_jobs(self, repo: str, run_id: int, attempt: int, jobs: list[dict]) -> None:
+        self._exec(
+            "INSERT OR REPLACE INTO attempt_jobs VALUES (?, ?, ?, ?)",
+            (repo, run_id, attempt, json.dumps(jobs)),
+        )
+
+    def get_log(self, repo: str, job_id: int) -> tuple[str, str | None] | None:
+        """(status, text) if cached, else None. status is "ok" or "gone"."""
+        row = self._one(
+            "SELECT status, log FROM job_logs WHERE repo=? AND job_id=?", (repo, job_id)
+        )
+        if not row:
+            return None
+        status, blob = row
+        return status, zlib.decompress(blob).decode("utf-8") if blob else None
+
+    def put_log(self, repo: str, job_id: int, text: str | None) -> None:
+        if text is None:
+            self._exec(
+                "INSERT OR REPLACE INTO job_logs VALUES (?, ?, 'gone', NULL)", (repo, job_id)
+            )
+            return
+        if len(text) > _MAX_TEXT:
+            text = text[-_MAX_TEXT:]
+        blob = zlib.compress(text.encode("utf-8"), 6)
+        while len(blob) > _MAX_COMPRESSED and len(text) > 1024:
+            text = text[len(text) // 2 :]
+            blob = zlib.compress(text.encode("utf-8"), 6)
+        self._exec("INSERT OR REPLACE INTO job_logs VALUES (?, ?, 'ok', ?)", (repo, job_id, blob))