costgrep-cli 0.0.0-stage → 0.7.3

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Paraphern and costgrep contributors
+
+   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.

package/README.md

@@ -1,3 +1,300 @@
-# Temporary Holding Version
+# costgrep
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![test](https://github.com/Paraphern/costgrep/actions/workflows/test.yml/badge.svg)](https://github.com/Paraphern/costgrep/actions/workflows/test.yml)
+[![self-audit](https://github.com/Paraphern/costgrep/actions/workflows/audit.yml/badge.svg)](https://github.com/Paraphern/costgrep/actions/workflows/audit.yml)
+
+**GitHub Actions cost breakdown by who triggered the run: human vs AI agent vs bot.**
+
+**See it on real data → [live benchmark, 6 public repos](benchmark/2026-10-02/README.md)**
+and **[3 verifiable cases with links to the actual runs & PRs](benchmark/cases.md):**
+in GitHub's own agentic-workflows repo, AI agents triggered **53.5% of runs and 28.8% of
+CI spend in a single day**; a solo maintainer's repo is now **agent-majority (46% of runs,
+57% of spend)**; in microsoft/vscode, **89% of a one-day sample's compute value ($123.61)
+sits in runner classes GitHub bills even for public repos**.
+Every figure ships with per-job evidence you can recompute in a spreadsheet.
+
+Copilot coding agents, Copilot code review, Claude Code, Codex, Cursor — since June 2026
+they all burn your Actions minutes *on top of* AI credits ([#192948], 958 downvotes).
+GitHub's own usage views don't tell you **who** spent it. This does:
+
+```
+$ node scripts/costgrep.mjs --repo actions/stale --days 30 --max-runs 50 --quiet
+costgrep — actions/stale (last 30 days, 50 runs, 47 jobs)
+==============================================================================
+class           runs   run%    minutes       cost    cost%
+------------------------------------------------------------------------------
+agent              0   0.0%         0      $0.00    0.0%
+agent-assisted    14  28.0%        26      $0.28   36.8%
+human             25  50.0%        24      $0.33   42.5%
+bot               11  22.0%        16      $0.16   20.7%
+unattributed       0   0.0%         0      $0.00    0.0%
+------------------------------------------------------------------------------
+total             50               66      $0.77
+
+>>> Agents cost $0.00 (0.0% of CI spend, 0 runs / 0.0%).
+>>> Bot runs: 11 (22.0% of all runs), bot spend $0.16.
+>>> Top workflows by total cost:
+         $0.50   65.0%  Basic validation
+         $0.10   12.4%  Code scanning
+         $0.06    7.8%  Licensed
+>>> public repo: standard Linux/Windows minutes are FREE — the $ above is the list-price VALUE of this compute (what it would cost in a private repo), not money owed. NOTE: 5 macOS/larger-runner jobs ARE billed even for public repos (~$0.37).
+>>> List-price model: NOT your invoice. Included plan minutes are consumed first; hosted phase reconciles against the billing API.
+```
+
+*(Real snapshot taken 2026-10-04 with the exact command shown; rerun it and you get
+current numbers. Note the `agent-assisted` row: 14 of 50 runs in this repo were
+pushed by humans with an AI `Co-Authored-By` trailer — that's the class doing its job.)*
+
+Runs **on your infrastructure** (your Actions runner, your terminal). Zero npm
+dependencies (single-file CLI core + a plain `agents.json` for the classifier
+lists — the core works standalone if the data file is missing), no telemetry,
+no code/log access — workflow-run metadata only.
+
+## Quick start (composite action)
+
+```yaml
+# .github/workflows/agent-ci-audit.yml
+name: costgrep audit
+on:
+  schedule: [{cron: '0 6 * * 1'}]   # weekly
+  workflow_dispatch:
+permissions:
+  actions: read                     # the only permission needed
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4   # only needed if you run a *local* copy / want the JSON in an artifact
+      - uses: YOUR_LOGIN/costgrep@v1
+        with:
+          days: '30'
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with: {name: costgrep, path: costgrep.json}
+```
+
+No org-admin rights, no billing access, no webhook — the repo-scoped
+`GITHUB_TOKEN` with `actions: read` is enough.
+
+## CLI
+
+```bash
+node scripts/costgrep.mjs --repo owner/name [--days 30] [--token $GITHUB_TOKEN] \
+  [--max-runs 1000] [--config my-rules.json] [--json-file report.json] \
+  [--csv-file evidence.csv] [--md-file report.md] [--gh-output $GITHUB_OUTPUT] \
+  [--no-coab] [--pr-comment N|auto] [--slack-webhook URL] [--step-summary] [--quiet] [--help]
+# org-wide audit (still no org-admin rights — a PAT with actions:read is enough):
+node scripts/costgrep.mjs --org my-org [--repos 20] [--max-runs 100]
+# offline demo on a bundled fixture:
+node scripts/costgrep.mjs --fixture-dir test/fixtures/demo-repo --days 4000
+```
+
+Requires Node >= 18 (`fetch`, `node:test`, ESM — no dependencies). Note on caps:
+`--max-runs` defaults to **1000** in the CLI and **500** in the composite action
+(safety cap for shared runners).
+
+`--config` (JSON) extends the classifier and overrides rates:
+
+```json
+{
+  "agents": ["my-internal-agent-bot"],
+  "bots":   ["my-ci-bot"],
+  "rates":  { "actions_linux": 0.006 }
+}
+```
+
+## Outputs & budget gate
+
+The action exposes machine-readable outputs, so CI can *act* on the split —
+not just display it (per-actor budget enforcement GitHub's budgets API doesn't have):
+
+```yaml
+- id: costgrep
+  uses: Paraphern/costgrep@v1
+- name: Agent budget gate (fail when agents exceed 20% of CI spend)
+  if: fromJSON(steps.costgrep.outputs['agent-share-pct']) > 20
+  run: |
+    echo "::error::AI agents burned ${{ steps.costgrep.outputs['agent-cost'] }} \
+      (${{ steps.costgrep.outputs['agent-share-pct'] }}% of CI spend) — above the 20% budget"
+    exit 1
+```
+
+| output | meaning |
+|---|---|
+| `total-cost` / `total-minutes` | whole-window list-price spend / billable minutes |
+| `agent-cost` / `agent-share-pct` / `agent-runs` | the AI-agent slice |
+| `agent-assisted-cost` | human-triggered runs with an AI `Co-Authored-By` trailer |
+| `bot-runs` / `bot-runs-pct` | automation share of runs |
+
+### Ready-made gates (copy-paste)
+
+```yaml
+# 1) Budget gate: fail CI when agents exceed 20% of spend
+- id: costgrep
+  uses: Paraphern/costgrep@v1
+- run: |
+    if (( $(echo "${{ steps.costgrep.outputs['agent-share-pct'] }} > 20" | bc -l) )); then
+      echo "::error::Agents at ${{ steps.costgrep.outputs['agent-cost'] }} (${{ steps.costgrep.outputs['agent-share-pct'] }}%) — above budget"
+      exit 1
+    fi
+
+# 2) Weekly org audit to Slack (secrets.SLACK_WEBHOOK; PAT with actions:read as CG_PAT)
+- uses: Paraphern/costgrep@v1
+  env:
+    CG_TOKEN: ${{ secrets.CG_PAT }}
+  with:
+    token: ${{ secrets.CG_PAT }}
+    slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
+    days: '7'
+# (--org mode: run the CLI directly, see above)
+
+# 3) Cost stamp on every PR (needs pull-requests:write)
+- uses: Paraphern/costgrep@v1
+  with:
+    pr-comment: auto
+```
+
+## Reconciliation & AI credits (experimental subcommands)
+
+For organizations that *can* provide an org token with billing rights (the one
+place costgrep ever asks for more than `actions:read`):
+
+```bash
+# our recomputation vs the billing API, per SKU, for a calendar month;
+# the delta lands in an explicit "unattributed" bucket with coverage warnings
+node scripts/costgrep.mjs reconcile --org my-org --month 2026-09 --billing-token $ORG_TOKEN
+
+# AI credits for the same month (by model; per-user breakdown is not exposed by the API)
+node scripts/costgrep.mjs credits --org my-org --month 2026-09 --billing-token $ORG_TOKEN
+```
+
+**Status, stated plainly: EXPERIMENTAL.** This code path is not yet validated
+against a live billing account — treat every delta as a hypothesis until
+calibrated on a real invoice (that calibration program is the 1.0 gate). Every
+output of these subcommands carries this label; the coverage warnings say
+exactly which repos/runs the comparison did and did not see.
+
+## Evidence: every number is traceable
+
+Reports are self-describing — a human can check any figure against real API data:
+
+- **JSON** (`--json-file`): aggregates + `provenance` (which endpoints were called, the
+  exact window, fetched-vs-counted jobs, rates version, honesty flags) + `evidence[]` —
+  one row per billable job.
+- **CSV** (`--csv-file`): the same per-job rows for any spreadsheet: run, actor, class,
+  timestamps, minutes, SKU, rate, cost.
+- **Markdown** (`--md-file`): a shareable report with the provenance block baked in.
+
+Verify it yourself (that's the point):
+
+1. open the CSV and recompute `minutes × rate_usd_per_min` on any row — it matches `cost_usd`;
+2. sum `cost_usd` — it equals the headline totals;
+3. compare `minutes` against the GitHub usage UI for the same window (same per-job round-up);
+4. rerun costgrep on the same repo + window — the result is deterministic (latest job attempt only);
+5. spot-check any `run_id` via `gh api /repos/{repo}/actions/runs/{run_id}/jobs` — timestamps,
+   actor and labels in the CSV are the API's own values, unmodified.
+
+Scope note: the CSV proves the **spend and minutes** figures. The *run-share* percentages
+(e.g. "agents = 53.5% of runs") count all runs in the window, including ones whose jobs
+never started — those are visible in the JSON report's `runsAnalyzed`/class totals, and
+re-derivable directly from `GET /repos/{repo}/actions/runs`.
+
+## How it attributes (summary — full methodology: [docs/methodology.md](docs/methodology.md))
+
+1. **Identity = `triggering_actor`**, falling back to `actor`. Re-runs are
+   attributed to whoever re-ran them. For `workflow_run` chains `github.actor`
+   can resolve to a generic bot ([gh-aw#20586]) — `triggering_actor` is the
+   honest identity, so that's what we use.
+2. **Classes:**
+   - `agent` — login matches an AI-agent slug list (Copilot / `copilot-swe-agent`,
+     Claude, Codex, Cursor, Gemini, Devin, Aider, Windsurf, CodeRabbit, Qodo, …
+     the list lives in [`agents.json`](agents.json) — extend it by PR, no code);
+   - `agent-assisted` — human-triggered run whose head commit carries an AI
+     `Co-Authored-By:` trailer (checked from the run's own metadata, zero extra
+     API calls; disable with `--no-coab`). Known limit, stated plainly: some
+     editors (VS Code) auto-insert the Copilot trailer — that's why this is a
+     separate class and never silently merged into `agent`;
+   - `bot` — automation (`github-actions[bot]`, Dependabot, Renovate, …) and any
+     other `type: Bot` / `[bot]` account not claimed by the agent list;
+   - `human` — `type: User`;
+   - `unattributed` — anything we can't classify. We show the bucket; we never
+     quietly re-assign it.
+3. **Minutes:** `ceil((completed_at − started_at) / 60s)` per job, minimum 1 —
+   same per-job round-up GitHub bills by. Jobs of the latest attempt only
+   (the API default), so re-run attempts aren't double-counted. Jobs that never
+   reached a runner (no timestamps) count 0; in-progress runs are excluded and
+   reported. Jobs that hold runner timestamps but were `skipped` or had
+   zero/negative duration are billed at the 1-minute minimum and **flagged in
+   every report with their exact total** — whether GitHub bills such executions
+   identically is unverifiable without invoice access, so we surface the
+   subtrahend instead of silently deciding.
+4. **Rates:** the published GitHub-hosted runner list prices effective
+   2026-01-01 ([docs]), keyed by the same SKU ids the billing API uses — the
+   foundation for invoice reconciliation in the hosted phase. Self-hosted = $0
+   (the $0.002/min platform fee was [postponed]); minutes still counted.
+5. **Known limits (stated, not hidden):** list-price model — included plan
+   minutes are consumed first, so this is *gross spend at list prices*, not
+   your invoice; runner-class inference comes from job labels and falls back
+   to the standard Linux rate (flagged in every report as `rate fallback` jobs);
+   per-user AI *credits* are not visible at repo level (org billing API only —
+   hosted phase). Expected accuracy vs a real invoice: **±5–10%**, which is
+   exactly why the hosted product leads with reconciliation, not estimates.
+
+## Why not just…? *(checked 2026-10)*
+
+| tool | human/agent/bot split | cost numbers it gives you | what you pay | needs org admin |
+|---|---|---|---|---|
+| GitHub native usage views | ✗ — no actor slice; org metrics [frozen since 21.07.2026](https://github.com/orgs/community/discussions/202838) | invoice-grade billing view | included in plan | view perms on billing |
+| Datadog CI Visibility | partial — git-author facet only, not trigger actor | span-based estimates | $8–12 / committer / mo | yes |
+| Blacksmith Analytics | ✗ (jobs / workflows / repos) | runner minutes | bundled with runners | no |
+| TrimCI | partial — bots excluded from *their* billing math; no AI-agent class | cost of CI failures | usage-based, per active contributor | no |
+| **costgrep** | **✓ human / AI agent / bot, re-runs attributed** | **list-price per 2026 SKU rates (invoice reconciliation = planned hosted phase, not yet)** | **nothing — free, open source (Apache-2.0)** | **no — repo token, `actions:read`** |
+
+**Money, stated plainly:** costgrep costs nothing and no paid tier exists today.
+Every `$` figure it prints is the *list-price value of compute* (see the notice in
+every report) — not money you owe GitHub and not money you pay us.
+
+## Calibration case (do this first)
+
+Run it on a repo where you can see the Actions usage chart for the same window:
+
+1. `node scripts/costgrep.mjs --repo your-org/your-repo --days 30 --json-file r.json`
+2. Compare `totalMinutes` per workflow against the GitHub UI "Usage" breakdown
+   for the same 30 days (billable minutes, per-job rounded).
+3. Compare per-class cost shares against what you *know* about the repo
+   (scheduled jobs → bot; PRs from `copilot-swe-agent` → agent).
+4. If your runners use unusual labels, add a `--config` rates block until
+   `rate fallback jobs` hits zero.
+
+## Roadmap
+
+**This repo — the CLI and the composite action — is free and open source, permanently.**
+If a paid product ever appears, it will be the *hosted service* (continuous monitoring,
+invoice reconciliation), not this code.
+
+**1.0 is criteria-based, not date-based** (see [CHANGELOG](CHANGELOG.md) and
+[docs/calibration.md](docs/calibration.md)): accuracy demonstrated on ≥5 real
+organizations with reconciliation delta ≤5%; 100+ action installs; zero open
+doctrine violations under a repeatable verification pass. Current state:
+**engineering-complete to 1.0-rc — the remaining gates are market evidence.**
+Stability guarantees: [docs/compatibility.md](docs/compatibility.md).
+
+- **Phase B (hosted):** GitHub App + webhooks → org-wide dashboard, per-actor
+  budgets/alerts, weekly digests.
+- **Phase C (reconciliation):** nightly join against
+  `/organizations/{org}/settings/billing/usage` — "our sum = your invoice line",
+  residual shown as an honest `unattributed` bucket; AI credits per user next
+  to minutes — the first unified agent bill.
+
+## Privacy & license
+
+The CLI reads workflow-run/job metadata via the public REST API and stores
+nothing anywhere. Apache-2.0 — see [LICENSE](LICENSE). Accuracy is best-effort; see
+the methodology above before quoting numbers to your CFO.
+
+[#192948]: https://github.com/orgs/community/discussions/192948
+[gh-aw#20586]: https://github.com/github/gh-aw/issues/20586
+[docs]: https://docs.github.com/en/billing/reference/actions-runner-pricing
+[postponed]: https://github.com/resources/insights/2026-pricing-changes-for-github-actions
+[#202838]: https://github.com/orgs/community/discussions/202838

package/action.yml

@@ -0,0 +1,85 @@
+name: 'CostGrep'
+description: >-
+  GitHub Actions cost breakdown by who triggered the run: human vs AI agent
+  (Copilot, Claude, Codex, Cursor...) vs bot. List-price model, public
+  methodology, per-job evidence trail, runs on your runner — no data leaves
+  your infrastructure.
+author: 'Paraphern'
+
+inputs:
+  days:
+    description: 'Look-back window in days'
+    default: '30'
+  token:
+    description: 'GitHub token with actions:read (repo-scoped GITHUB_TOKEN is enough)'
+    default: '${{ github.token }}'
+  max-runs:
+    description: 'Safety cap on analyzed workflow runs'
+    default: '500'
+  config:
+    description: 'Optional JSON file {agents, bots, rates, coab} to extend/override defaults'
+    default: ''
+  pr-comment:
+    description: 'Optional: post the report as a PR comment (PR number, or "auto" to take it from GITHUB_REF; token needs pull-requests:write)'
+    default: ''
+  slack-webhook:
+    description: 'Optional: post the report to a Slack incoming webhook (https://hooks.slack.com/services/... URL)'
+    default: ''
+  json-file:
+    description: 'Where to write the full JSON report (relative to workspace)'
+    default: 'costgrep.json'
+  csv-file:
+    description: 'Optional: write per-job evidence CSV here (audit trail)'
+    default: ''
+  md-file:
+    description: 'Optional: write shareable Markdown report with provenance here'
+    default: ''
+
+outputs:
+  total-cost:
+    description: 'Total list-price CI spend, USD'
+  total-minutes:
+    description: 'Total billable minutes (rounded per job, like GitHub)'
+  agent-cost:
+    description: 'List-price spend attributed to AI agents, USD'
+  agent-assisted-cost:
+    description: 'Spend from human-triggered runs whose commits carry an AI Co-Authored-By trailer, USD'
+  agent-share-pct:
+    description: 'Agents share of total CI spend, % (e.g. "6.8")'
+  agent-runs:
+    description: 'Workflow runs attributed to AI agents'
+  bot-runs:
+    description: 'Workflow runs attributed to bots'
+  bot-runs-pct:
+    description: 'Bot share of all runs, %'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: 'costgrep: human vs agent vs bot CI spend'
+      shell: bash
+      env:
+        # All user-controllable inputs go through env, never via ${{ }} inline in
+        # bash — script-injection hardening per GitHub's security guide.
+        CG_TOKEN: ${{ inputs.token }}
+        CG_REPO: ${{ github.repository }}
+        CG_DAYS: ${{ inputs.days }}
+        CG_MAX_RUNS: ${{ inputs.max-runs }}
+        CG_JSON: ${{ inputs.json-file }}
+        CG_CSV: ${{ inputs.csv-file }}
+        CG_MD: ${{ inputs.md-file }}
+        CG_CONFIG: ${{ inputs.config }}
+        CG_PR: ${{ inputs.pr-comment }}
+        CG_SLACK: ${{ inputs.slack-webhook }}
+      run: |
+        ARGS=(--repo "$CG_REPO" --days "$CG_DAYS" --max-runs "$CG_MAX_RUNS" --token "$CG_TOKEN" --json-file "$CG_JSON" --gh-output "$GITHUB_OUTPUT" --step-summary)
+        [ -n "$CG_CSV" ] && ARGS+=(--csv-file "$CG_CSV")
+        [ -n "$CG_MD" ] && ARGS+=(--md-file "$CG_MD")
+        [ -n "$CG_CONFIG" ] && ARGS+=(--config "$CG_CONFIG")
+        [ -n "$CG_PR" ] && ARGS+=("--pr-comment=$CG_PR")
+        [ -n "$CG_SLACK" ] && ARGS+=("--slack-webhook=$CG_SLACK")
+        node "${{ github.action_path }}/scripts/costgrep.mjs" "${ARGS[@]}"
+
+branding:
+  icon: 'bar-chart-2'
+  color: 'purple'

package/agents.json

@@ -0,0 +1,20 @@
+{
+  "version": "2026-10-03",
+  "note": "Data file: extend the classifier without touching code. PRs adding entries must cite evidence (a public run/PR/doc) — see CONTRIBUTING.md. Rates live in code (money = code review).",
+  "agents": [
+    "copilot", "copilot-swe-agent", "claude", "cursor", "codex", "openai-codex",
+    "gemini", "gemini-code-assist", "jules", "devin", "aider", "windsurf",
+    "codebuff", "opencode", "goose", "factory", "sweep", "coderabbit",
+    "qodo", "greptile", "ellipsis", "codeant", "kodu", "ampcode"
+  ],
+  "bots": [
+    "github-actions", "actions-user", "dependabot", "renovate", "greenkeeper",
+    "imgbot", "allcontributors", "lock", "stash", "bors", "mergify",
+    "semantic-release-bot", "codecov", "coveralls", "netlify", "vercel",
+    "github-advanced-security", "fossa", "changeset-bot"
+  ],
+  "coauthorNames": [
+    "copilot", "claude", "cursor", "gemini", "codex", "devin", "aider",
+    "windsurf", "jules", "goose", "codebuff", "opencode"
+  ]
+}

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "costgrep-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.3",
+  "description": "GitHub Actions cost breakdown: human vs AI agent vs bot. Zero-dependency CLI + composite action.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": ["github-actions", "cost", "finops", "ci", "ai-agents", "copilot", "developer-tools", "cli"],
+  "homepage": "https://github.com/Paraphern/costgrep#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/Paraphern/costgrep.git" },
+  "bugs": "https://github.com/Paraphern/costgrep/issues",
+  "bin": { "costgrep": "scripts/costgrep.mjs" },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": { "node": ">=18" },
+  "files": ["scripts/", "agents.json", "action.yml", "README.md", "LICENSE"]
+}