jekyll-theme-zer0 1.28.0 → 1.30.0

data/assets/js/ui-enhancements.js

@@ -101,12 +101,20 @@
   }
 
   /**
-   * Add active state to navigation links on scroll
+   * Add active state to in-page navigation links on scroll.
+   *
+   * Deliberately excludes `#TableOfContents` links (and the section-page
+   * sidebar): those are owned by assets/js/modules/navigation/scroll-spy.js.
+   * This observer used to claim every `a[href^="#"]` on the page and clear
+   * `.active` from all of them, which fought the TOC scroll spy and made the
+   * active heading flicker between entries.
    */
   function initScrollSpy() {
     const sections = document.querySelectorAll('section[id], [id^="get-started"], [id^="features"]');
-    const navLinks = document.querySelectorAll('a[href^="#"]');
-    
+    const navLinks = Array.from(document.querySelectorAll('a[href^="#"]')).filter(
+      link => !link.closest('#TableOfContents, .bd-toc, .sidebar-nav')
+    );
+
     if (!sections.length || !navLinks.length) return;
 
     const observerOptions = {

data/scripts/README.md

@@ -25,6 +25,15 @@ scripts/
 │   ├── pixelate_images.py          # Pure-stdlib pixelate/quantize engine
 │   ├── install-preview-generator   # Preview generator installer
 │   └── validate_preview_urls.py    # Preview URL validator
+├── ai/                    # Consumer companions to the hub's `ai-runner` kit (the runner itself is referenced, not stored)
+│   ├── api_call.rb                 # Single-shot Claude API fallback (stdlib only)
+│   ├── usage.rb                    # Optional metering: one JSONL record per call
+│   ├── usage_report.rb             # Publishes metering (summary, artifact, PR comment)
+│   └── README.md                   # What stays here and why
+├── ci/                    # Helpers called directly by workflow steps
+│   ├── classify_changes.py         # Change classifier (issue-pr-auto-merge)
+│   ├── agent_review_result.py      # Did the Claude content review actually run?
+│   └── test_agent_review_result.py # …its tests (CI-run via test/lib bridge)
 ├── utils/                 # Utility scripts
 │   ├── analyze-commits    # Commit analyzer for version bumps
 │   ├── fix-markdown       # Markdown formatting fixer
@@ -171,6 +180,41 @@ Validate preview image URLs in frontmatter.
 python3 scripts/features/validate_preview_urls.py [--verbose] [--suggestions]
 ```
 
+### AI Runner (scripts/ai/)
+
+Every model call a workflow makes goes through `uses: bamr87/bamr87/.github/actions/claude-run@main` — the fleet's shared **`ai-runner` kit**, versioned once in the [bamr87/bamr87 hub](https://github.com/bamr87/bamr87) and consumed by reference. The runner (`run.sh`) and the composite action are no longer stored in this repo; the hub's kit README ([`templates/ai-runner/README.md`](https://github.com/bamr87/bamr87/blob/main/templates/ai-runner/README.md)) is the contract. In short:
+
+- Model: `--model` input > `AI_MODEL` > `_data/ai.yml` `model:` > the fleet default.
+- Auth from the env, OAuth first: `CLAUDE_CODE_OAUTH_TOKEN` (preferred; strips `ANTHROPIC_API_KEY` from the CLI's env) or `ANTHROPIC_API_KEY` (also the only credential the API fallback can use).
+- Exit codes: `0` when the call ran or nothing was ever attempted (no auth — the documented no-op); `1` when the call was attempted and failed with no usable fallback, with the reason raised as a `::error::` annotation.
+
+This directory holds the **consumer-owned companions** the hub runner probes for in the checkout and uses when present: `usage.rb` metering (prices from `_data/ai_pricing.yml`), `usage_report.rb` publishing, `api_call.rb` fallback — plus `tools/unwrap-prose.py` as the post-run prose normalizer. See [`scripts/ai/README.md`](ai/README.md). The exit-code contract test lives in the hub (`templates/ai-runner/tests/contract.sh`) and runs there on every runner change.
+
+### CI Helpers (scripts/ci/)
+
+#### `agent_review_result.py`
+
+Decides whether the Claude tier of `ai-content-review.yml` **actually produced a review**, and fails the job when it did not.
+
+Before this existed, the agent step captured the Claude CLI's exit status, echoed it, and then posted whatever landed on stdout as the review. When the OAuth credential was revoked, `Failed to authenticate. API Error: 401 OAuth access token has been revoked.` became the "review" and every job still reported success (issue #418) — for days, across several PRs, with nothing on the checks list to say the editorial review had stopped happening.
+
+Note that a non-zero exit code would not have caught it: the CLI reported the auth failure on stdout. Three conditions are classified — a non-zero exit, no output at all, and a short output that leads with a known CLI failure signature. Any of them writes an explicit failure notice for the sticky comment, emits a `::error::` annotation, and exits 1.
+
+```bash
+python3 scripts/ci/agent_review_result.py \
+  --status "$status" --stdout /tmp/agent-review.md \
+  --stderr /tmp/agent-err.log --out /tmp/agent-review-final.md
+# exit 0 = the review is real · 1 = the tier failed · 2 = bad invocation
+
+python3 scripts/ci/test_agent_review_result.py   # tests, incl. the verbatim #418 output
+```
+
+The tests run in CI through `scripts/test/lib/test_agent_review_result.sh`, which `run_tests.sh` sources and `./scripts/bin/test` executes on every PR.
+
+#### `classify_changes.py`
+
+Classifies a PR's changed files for `issue-pr-auto-merge.yml` (`--content-only`).
+
 ### Content Validation
 
 #### `lint-pages`

data/scripts/ai/README.md

@@ -0,0 +1,38 @@
+# scripts/ai — companions to the fleet's `ai-runner` kit
+
+Every model call a workflow here makes goes through `uses: bamr87/bamr87/.github/actions/claude-run@main` — the fleet's one AI step, versioned once in the [bamr87/bamr87 hub](https://github.com/bamr87/bamr87) and consumed **by reference**. This repo no longer carries the runner (`scripts/ai/run.sh`) or the composite action (`.github/actions/claude-run/`); it receives every fix on its next run with nothing to copy forward. The kit's contract, environment, and exit codes are documented in the hub: [`templates/ai-runner/README.md`](https://github.com/bamr87/bamr87/blob/main/templates/ai-runner/README.md).
+
+What stays here are the **consumer-owned companions** the hub runner probes for in `$GITHUB_WORKSPACE` and uses when present:
+
+| File | Role | Required |
+| --- | --- | --- |
+| `usage.rb` | Metering: one JSONL record per call (tokens, API-equivalent cost, model, status, CI context) into `$AI_USAGE_DIR/records.jsonl` (default `$RUNNER_TEMP/ai-usage`, outside the checkout). Prices come from `_data/ai_pricing.yml`. | optional |
+| `usage_report.rb` | End-of-job publisher: step summary, `ai-usage-*` artifact, sticky PR comment (marker `<!-- lh-ai-usage -->`). Run by the hub action's `always()` post-step. | optional |
+| `api_call.rb` | The single-shot Messages API fallback the runner uses when Claude Code is missing or fails. Stdlib only, self-contained. | optional |
+| `../../_data/ai.yml` | `model:` (and `max_tokens` for the API fallback). The runner resolves `--model` > `AI_MODEL` > this file > the fleet default. | recommended |
+| `../../tools/unwrap-prose.py` | Post-run one-paragraph-per-line normalizer for markdown the agent changed. `SCHEMA.md`/`CHANGELOG.md` are always skipped; further exclusions go in a repo-root `.prose-excludes`, one extended regex per line. | optional |
+
+Without a companion the runner degrades honestly: no `usage.rb` means nothing is recorded (an inline emitter still treats `is_error` as a failure); no `api_call.rb` means a failed primary call exits `1` with "no scripts/ai/api_call.rb|py to fall back to".
+
+## Contract, in one line
+
+Auth from the job env, OAuth first (`CLAUDE_CODE_OAUTH_TOKEN`, then `ANTHROPIC_API_KEY`); canonical `AI_*` environment with no repo prefix (`AI_MODEL`, `AI_FORCE_API`, `AI_MAX_TURNS`, `AI_USAGE_DIR`, `AI_ROLE`, `AI_REPO_ROOT`); exit `0` when the call ran or nothing was attempted (no auth — the documented no-op), exit `1` when a call was attempted and failed with no usable fallback, with the reason raised as a `::error::` annotation. The exit-code contract is pinned by the hub's `templates/ai-runner/tests/contract.sh` (stubbed `claude`, no network, no credentials) and run there on every change to the runner — not vendored here.
+
+## Calling it
+
+```yaml
+- uses: bamr87/bamr87/.github/actions/claude-run@main
+  env:
+    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # optional fallback
+  with:
+    agent: issue-triager            # .claude/agents/<name>.md
+    prompt: "..."
+    tools: "Read,Grep,Glob,Bash(gh:*)"
+```
+
+Inputs: `prompt`, `agent`, `tools`, `mcp`, `system`, `out`, `model`, `max-turns`. Callers in this repo: `issue-autopilot.yml` (triage, verify, resolve) and `visual-evidence-autogen.yml`. Where a lane is the standard shape (gate on a `*_ENABLED` variable, run one agent, open one PR), the hub also offers the reusable `bamr87/bamr87/.github/workflows/ai-lane.yml@main`; the matrix-fed autopilot is deliberately not that shape.
+
+## Metering companions are kit files too
+
+`usage.rb`, `usage_report.rb`, and `api_call.rb` are the same files lifehacker.dev runs. Fix them there first and copy forward (`shasum` parity is the check); never fork them here.

data/scripts/ai/api_call.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# =============================================================================
+# api_call.rb — the Claude API fallback (single-shot Messages call)
+# -----------------------------------------------------------------------------
+# Used by scripts/ai/run.sh when the Claude Code CLI is unavailable or fails.
+# Calls POST /v1/messages over Ruby's stdlib (net/http + json) — NO gem — so it
+# runs on a bare runner just like the rest of scripts/. Reads ANTHROPIC_API_KEY
+# and _data/ai.yml. Prints the model's text to stdout.
+#
+# Auth note: this path is ANTHROPIC_API_KEY-only by design. A Claude Code OAuth
+# token (CLAUDE_CODE_OAUTH_TOKEN) authenticates the `claude` CLI, NOT the raw
+# Messages API, so it cannot be used here. run.sh selects the credential and only
+# reaches this fallback when an API key is present; with only an OAuth token the
+# primary Claude Code path runs and this fallback is intentionally unavailable.
+#
+# This is a degraded path: a single message in, the final text out — not the
+# full agent. It covers the text-generation/analysis steps (a review comment, a
+# draft, a classification); steps that need multi-file edits should run under
+# Claude Code (the primary), which run.sh tries first.
+#
+#   ruby scripts/ai/api_call.rb --prompt "..." [--system "..."]
+#   echo "..." | ruby scripts/ai/api_call.rb
+# =============================================================================
+require 'net/http'
+require 'uri'
+require 'json'
+require 'yaml'
+
+# kit: ai-runner — stdlib only and self-contained (no repo-local library), so the
+# same file runs in every repo that carries scripts/ai/run.sh.
+ROOT = File.expand_path('../..', __dir__)
+cfg = begin
+  raw = File.read(File.join(ROOT, '_data', 'ai.yml'), encoding: 'UTF-8')
+  (YAML.respond_to?(:unsafe_load) ? YAML.unsafe_load(raw) : YAML.load(raw)) || {}
+rescue StandardError
+  {}
+end
+MODEL   = ENV['AI_MODEL'] || cfg['fallback_model'] || cfg['model'] || 'claude-opus-4-8'
+MAXTOK  = (ENV['AI_MAX_TOKENS'] || cfg['max_tokens'] || 8000).to_i
+VERSION = cfg['api_version'] || '2023-06-01'
+BASE    = cfg['api_base'] || 'https://api.anthropic.com'
+
+key = ENV['ANTHROPIC_API_KEY'].to_s
+abort '[api_call] ANTHROPIC_API_KEY not set — cannot use the Claude API fallback' if key.empty?
+
+# --- parse args: --prompt/-p, --system, else stdin -------------------------
+args = ARGV.dup
+system_prompt = nil
+if (i = args.index('--system'))
+  system_prompt = args[i + 1]
+  args.delete_at(i + 1); args.delete_at(i)
+end
+prompt =
+  if (i = (args.index('--prompt') || args.index('-p'))) then args[i + 1]
+  elsif !args.empty? then args.join(' ')
+  else $stdin.read
+  end
+abort '[api_call] empty prompt' if prompt.to_s.strip.empty?
+
+body = { 'model' => MODEL, 'max_tokens' => MAXTOK,
+         'messages' => [{ 'role' => 'user', 'content' => prompt }] }
+body['system'] = system_prompt if system_prompt
+
+# Dry run: print the request shape without calling the API (for tests).
+if ENV['AI_DRY_RUN'] == '1'
+  puts JSON.pretty_generate('endpoint' => "#{BASE}/v1/messages", 'model' => MODEL,
+                            'max_tokens' => MAXTOK, 'anthropic_version' => VERSION,
+                            'has_system' => !system_prompt.nil?)
+  exit 0
+end
+
+uri  = URI.join(BASE, '/v1/messages')
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = (uri.scheme == 'https')
+http.read_timeout = 120
+http.open_timeout = 20
+
+attempt = 0
+loop do
+  attempt += 1
+  req = Net::HTTP::Post.new(uri)
+  req['x-api-key'] = key
+  req['anthropic-version'] = VERSION
+  req['content-type'] = 'application/json'
+  req.body = JSON.generate(body)
+
+  res = (http.request(req) rescue nil)
+  code = res ? res.code.to_i : 0
+
+  if code == 200
+    data = JSON.parse(res.body)
+    # Meter the call (tokens were billed either way — refusals included). The
+    # record is an ESTIMATE from _data/ai_pricing.yml: the raw API reports
+    # usage but not dollars. Best-effort — a metering bug must never break
+    # the actual AI step.
+    begin
+      require_relative 'usage'
+      AIUsage.append(AIUsage.from_api_response(data, agent: ENV['AI_ROLE'].to_s))
+    rescue StandardError => e
+      warn "[api_call] usage record failed (non-fatal): #{e.class}: #{e.message}"
+    end
+    if data['stop_reason'] == 'refusal'
+      warn '[api_call] request refused by safety classifiers'
+      exit 2
+    end
+    text = (data['content'] || []).select { |b| b['type'] == 'text' }.map { |b| b['text'] }.join
+    warn "[api_call] Claude API fallback ok (model=#{data['model']}, stop=#{data['stop_reason']})"
+    puts text
+    exit 0
+  elsif code == 401 || code == 403
+    # Auth failure is not transient — don't retry, and say so plainly so a
+    # misconfigured/expired/insufficient ANTHROPIC_API_KEY is diagnosable instead
+    # of hiding behind the generic HTTP error below.
+    warn "[api_call] authentication failed (HTTP #{code}) — the ANTHROPIC_API_KEY is missing, invalid, expired, or lacks access. #{res && res.body.to_s[0, 200]}"
+    exit 1
+  elsif (code.zero? || [429, 500, 502, 503, 529].include?(code)) && attempt < 4
+    warn "[api_call] transient (HTTP #{code}), retry #{attempt}/3"
+    sleep([2**attempt, 30].min)
+    next
+  else
+    warn "[api_call] HTTP #{code}: #{res && res.body.to_s[0, 300]}"
+    exit 1
+  end
+end

data/scripts/ai/usage.rb

@@ -0,0 +1,314 @@
+#!/usr/bin/env ruby
+# =============================================================================
+# usage.rb — capture ONE normalized usage record per AI invocation
+# -----------------------------------------------------------------------------
+# The metering half of the universal AI runner. Every model call in the repo
+# already flows through scripts/ai/run.sh (Claude Code) or scripts/ai/api_call.rb
+# (API fallback) — this library turns each call's raw usage payload into one
+# JSONL record so tokens and cost are never invisible. Records accumulate in
+# AI_USAGE_DIR (default: $RUNNER_TEMP/ai-usage — OUTSIDE the checkout, so
+# agents never see a dirty tree), and scripts/ai/usage_report.rb publishes them
+# (step summary + artifact + PR comment) at the end of the job.
+#
+# Cost semantics: Claude Code reports its own total_cost_usd — recorded verbatim
+# (cost_source: "reported"). That figure is what the tokens would bill at API
+# list prices; under subscription OAuth the marginal dollar cost is $0, so every
+# surface labels it "API-equivalent". Paths that report tokens but no dollars
+# (the raw API fallback) get cost_source: "estimated" from _data/ai_pricing.yml.
+#
+#   ruby scripts/ai/usage.rb ingest-claude <result.json> [--agent X] [--rc N] [--emit-result]
+#   ruby scripts/ai/usage.rb ingest-execution-log <log.json> [--agent X]
+#
+# ingest-claude exits non-zero when the file is not a Claude result JSON, so
+# run.sh can treat "unparseable output" like a failed run (fallback engages).
+# Stdlib only — no gems — so it runs on a bare runner before `bundle install`.
+# =============================================================================
+require 'json'
+require 'yaml'
+require 'time'
+require 'digest'
+require 'fileutils'
+
+module AIUsage
+  ROOT = File.expand_path('../..', __dir__)
+
+  module_function
+
+  def dir
+    ENV['AI_USAGE_DIR'].to_s.empty? ? File.join(ENV['RUNNER_TEMP'] || ENV['TMPDIR'] || '/tmp', 'ai-usage') : ENV['AI_USAGE_DIR']
+  end
+
+  def records_path
+    File.join(dir, 'records.jsonl')
+  end
+
+  # --- pricing (estimates only — reported costs are always preferred) --------
+  def pricing
+    @pricing ||= begin
+      raw = YAML.respond_to?(:unsafe_load) ? YAML.unsafe_load(File.read(File.join(ROOT, '_data', 'ai_pricing.yml'))) : YAML.load(File.read(File.join(ROOT, '_data', 'ai_pricing.yml')))
+      raw.is_a?(Hash) ? raw : {}
+    rescue StandardError
+      {}
+    end
+  end
+
+  def price_for(model)
+    models = pricing['models'] || {}
+    key = models.keys.reject { |k| k == 'default' }
+                .select { |k| model.to_s.start_with?(k) }
+                .max_by(&:length)
+    models[key] || models['default'] || { 'input' => 5.0, 'output' => 25.0 }
+  end
+
+  # tokens: {'input'=>, 'output'=>, 'cache_read'=>, 'cache_5m'=>, 'cache_1h'=>}
+  # Reproduces the CLI's own arithmetic (validated to the cent, 2026-07-14).
+  def estimate_cost(model, tokens)
+    p = price_for(model)
+    m = pricing['multipliers'] || {}
+    inp = p['input'].to_f / 1_000_000
+    out = p['output'].to_f / 1_000_000
+    tokens['input'].to_i * inp +
+      tokens['output'].to_i * out +
+      tokens['cache_read'].to_i * inp * (m['cache_read'] || 0.1).to_f +
+      tokens['cache_5m'].to_i * inp * (m['cache_write_5m'] || 1.25).to_f +
+      tokens['cache_1h'].to_i * inp * (m['cache_write_1h'] || 2.0).to_f
+  end
+
+  # --- shared context ---------------------------------------------------------
+  def auth_mode
+    return 'oauth' unless ENV['CLAUDE_CODE_OAUTH_TOKEN'].to_s.empty?
+    return 'api_key' unless ENV['ANTHROPIC_API_KEY'].to_s.empty?
+    'none'
+  end
+
+  # One safe, bounded line out of a model-supplied error string: credentials
+  # masked, whitespace collapsed, length capped. These records ship as build
+  # artifacts and land in the public ledger, so nothing verbatim goes in.
+  MAX_ERROR_CHARS = 500
+  def scrub(text)
+    text.to_s
+        .gsub(/sk-ant-[A-Za-z0-9_-]{8,}/, 'sk-ant-***')
+        .gsub(/\s+/, ' ')
+        .strip[0, MAX_ERROR_CHARS]
+        .to_s
+  end
+
+  def ci_context
+    {
+      'repo'        => ENV['GITHUB_REPOSITORY'].to_s,
+      'workflow'    => ENV['GITHUB_WORKFLOW'].to_s,
+      'job'         => ENV['GITHUB_JOB'].to_s,
+      'run_id'      => ENV['GITHUB_RUN_ID'].to_s,
+      'run_attempt' => ENV['GITHUB_RUN_ATTEMPT'].to_s,
+      'event'       => ENV['GITHUB_EVENT_NAME'].to_s,
+      'ref'         => ENV['GITHUB_REF_NAME'].to_s,
+      'sha'         => ENV['GITHUB_SHA'].to_s
+    }
+  end
+
+  def base_record(source:, agent:, ts: nil)
+    {
+      'id'          => nil,                       # set by the ingester (stable per payload)
+      'ts'          => (ts || Time.now.utc).iso8601,
+      'source'      => source,                    # claude-code | api-fallback | claude-code-action
+      'status'      => 'success',
+      'agent'       => agent.to_s,
+      'model'       => '',
+      'auth'        => auth_mode,
+      'tokens'      => { 'input' => 0, 'output' => 0, 'cache_read' => 0, 'cache_creation' => 0 },
+      'model_usage' => {},
+      'cost_usd'    => 0.0,
+      'cost_source' => 'reported',
+      'duration_ms' => nil,
+      'num_turns'   => nil,
+      'session_id'  => nil,
+      'pr'          => nil,                       # attributed later by usage_report.rb
+      'pr_source'   => nil                        # 'event' (ran on the PR) | 'created' (run opened it)
+    }.merge(ci_context)
+  end
+
+  def stable_id(payload_anchor)
+    Digest::SHA256.hexdigest("#{ENV['GITHUB_RUN_ID']}|#{ENV['GITHUB_JOB']}|#{payload_anchor}")[0, 16]
+  end
+
+  # --- ingesters ---------------------------------------------------------------
+  # A `claude -p --output-format json` result object (the probed 2026 schema:
+  # total_cost_usd, usage{...}, modelUsage{<id>=>{...costUSD}}, num_turns, uuid).
+  def from_claude_result(res, agent: '', exit_code: 0, source: 'claude-code')
+    rec = base_record(source: source, agent: agent)
+    rec['id']          = stable_id(res['uuid'] || res['session_id'] || Digest::SHA256.hexdigest(res.to_s))
+    rec['status']      = (res['is_error'] || exit_code.to_i != 0) ? 'error' : 'success'
+    rec['duration_ms'] = res['duration_ms']
+    rec['num_turns']   = res['num_turns']
+    rec['session_id']  = res['session_id']
+    # WHY it failed, not just that it did. A rejected call reports zero tokens
+    # and an empty model, so without this the record is indistinguishable from
+    # any other dead run and the caller's evidence is already gone.
+    if rec['status'] == 'error'
+      rec['error'] = {
+        'subtype'   => res['subtype'].to_s,
+        'exit_code' => exit_code.to_i,
+        'message'   => scrub(res['result'] || res['error'])
+      }
+    end
+
+    usage = res['usage'] || {}
+    rec['tokens'] = {
+      'input'          => usage['input_tokens'].to_i,
+      'output'         => usage['output_tokens'].to_i,
+      'cache_read'     => usage['cache_read_input_tokens'].to_i,
+      'cache_creation' => usage['cache_creation_input_tokens'].to_i
+    }
+
+    mu = res['modelUsage'] || {}
+    mu.each do |model, u|
+      rec['model_usage'][model] = {
+        'input'          => u['inputTokens'].to_i,
+        'output'         => u['outputTokens'].to_i,
+        'cache_read'     => u['cacheReadInputTokens'].to_i,
+        'cache_creation' => u['cacheCreationInputTokens'].to_i,
+        'cost_usd'       => u['costUSD'].to_f
+      }
+    end
+    # Primary model = the one that did the most output work (subagents may add others).
+    rec['model'] = mu.max_by { |_, u| u['outputTokens'].to_i }&.first || ''
+
+    if res['total_cost_usd']
+      rec['cost_usd']    = res['total_cost_usd'].to_f
+      rec['cost_source'] = 'reported'
+    else
+      cache = usage['cache_creation'] || {}
+      rec['cost_usd'] = estimate_cost(rec['model'], rec['tokens'].merge(
+        'cache_5m' => cache['ephemeral_5m_input_tokens'].to_i,
+        'cache_1h' => cache['ephemeral_1h_input_tokens'].to_i
+      ))
+      rec['cost_source'] = 'estimated'
+    end
+    rec
+  end
+
+  # A raw Messages API response (api_call.rb fallback). No cost field — estimate.
+  def from_api_response(data, agent: '')
+    rec = base_record(source: 'api-fallback', agent: agent)
+    rec['id']     = stable_id(data['id'] || Digest::SHA256.hexdigest(data.to_s))
+    rec['model']  = data['model'].to_s
+    rec['status'] = data['stop_reason'] == 'refusal' ? 'error' : 'success'
+    usage = data['usage'] || {}
+    cache = usage['cache_creation'] || {}
+    rec['tokens'] = {
+      'input'          => usage['input_tokens'].to_i,
+      'output'         => usage['output_tokens'].to_i,
+      'cache_read'     => usage['cache_read_input_tokens'].to_i,
+      'cache_creation' => usage['cache_creation_input_tokens'].to_i
+    }
+    rec['cost_usd'] = estimate_cost(rec['model'], rec['tokens'].merge(
+      'cache_5m' => cache['ephemeral_5m_input_tokens'] ? cache['ephemeral_5m_input_tokens'].to_i : usage['cache_creation_input_tokens'].to_i,
+      'cache_1h' => cache['ephemeral_1h_input_tokens'].to_i
+    ))
+    rec['cost_source'] = 'estimated'
+    rec['model_usage'][rec['model']] = rec['tokens'].merge('cost_usd' => rec['cost_usd'])
+    rec
+  end
+
+  # A claude-code-action execution log: a JSON array (or NDJSON) of stream
+  # events. Prefer the final `result` event (same shape as ingest-claude);
+  # fall back to summing per-message assistant usage when the log has none.
+  def from_execution_log(text, agent: '')
+    events =
+      begin
+        parsed = JSON.parse(text)
+        parsed.is_a?(Array) ? parsed : [parsed]
+      rescue JSON::ParserError
+        text.split("\n").map { |l| JSON.parse(l) rescue nil }.compact
+      end
+    result = events.reverse.find { |e| e.is_a?(Hash) && e['type'] == 'result' }
+    return from_claude_result(result, agent: agent, source: 'claude-code-action') if result
+
+    rec = base_record(source: 'claude-code-action', agent: agent)
+    rec['id'] = stable_id(Digest::SHA256.hexdigest(text))
+    turns = 0
+    events.each do |e|
+      next unless e.is_a?(Hash) && e['type'] == 'assistant'
+      msg   = e['message'] || {}
+      usage = msg['usage'] || {}
+      next if usage.empty?
+      turns += 1
+      model = msg['model'].to_s
+      mu = rec['model_usage'][model] ||= { 'input' => 0, 'output' => 0, 'cache_read' => 0, 'cache_creation' => 0, 'cost_usd' => 0.0 }
+      mu['input']          += usage['input_tokens'].to_i
+      mu['output']         += usage['output_tokens'].to_i
+      mu['cache_read']     += usage['cache_read_input_tokens'].to_i
+      mu['cache_creation'] += usage['cache_creation_input_tokens'].to_i
+      %w[input output cache_read cache_creation].each { |k| rec['tokens'][k] += mu_key(usage, k) }
+    end
+    rec['num_turns'] = turns
+    rec['model'] = rec['model_usage'].max_by { |_, u| u['output'].to_i }&.first || ''
+    rec['model_usage'].each do |model, u|
+      u['cost_usd'] = estimate_cost(model, u.merge('cache_5m' => u['cache_creation'], 'cache_1h' => 0))
+      rec['cost_usd'] += u['cost_usd']
+    end
+    rec['cost_source'] = 'estimated'
+    rec
+  end
+
+  def mu_key(usage, key)
+    { 'input' => usage['input_tokens'], 'output' => usage['output_tokens'],
+      'cache_read' => usage['cache_read_input_tokens'],
+      'cache_creation' => usage['cache_creation_input_tokens'] }[key].to_i
+  end
+
+  # --- sink ---------------------------------------------------------------------
+  def append(rec, to: nil)
+    path = to || records_path
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, 'a') { |io| io.puts(JSON.generate(rec)) }
+    rec
+  end
+end
+
+# --- CLI -------------------------------------------------------------------------
+if __FILE__ == $PROGRAM_NAME
+  cmd = ARGV.shift
+  agent = ''
+  rc = 0
+  emit = false
+  file = nil
+  args = ARGV.dup
+  until args.empty?
+    case (a = args.shift)
+    when '--agent'       then agent = args.shift.to_s
+    when '--rc'          then rc = args.shift.to_i
+    when '--emit-result' then emit = true
+    else file ||= a
+    end
+  end
+
+  case cmd
+  when 'ingest-claude'
+    abort '[usage] no input file' unless file && File.exist?(file)
+    res = begin
+      JSON.parse(File.read(file, encoding: 'UTF-8'))
+    rescue JSON::ParserError, Errno::ENOENT
+      warn '[usage] not a Claude result JSON — nothing recorded.'
+      exit 65
+    end
+    unless res.is_a?(Hash) && (res.key?('usage') || res.key?('total_cost_usd'))
+      warn '[usage] JSON has no usage payload — nothing recorded.'
+      exit 65
+    end
+    rec = AIUsage.append(AIUsage.from_claude_result(res, agent: agent, exit_code: rc))
+    warn "[usage] recorded #{rec['id']}: #{rec['model']} $#{format('%.4f', rec['cost_usd'])} (#{rec['tokens']['output']} out tok, #{rec['status']})"
+    warn "[usage] failure: #{[rec['error']['subtype'], rec['error']['message']].reject { |v| v.to_s.empty? }.join(' — ')}" if rec['error']
+    # Emit the result text only on success — on error the caller falls back to
+    # the API path, and emitting here would double the output it produces.
+    print res['result'].to_s if emit && rec['status'] == 'success'
+    exit(rec['status'] == 'success' ? 0 : 1)
+  when 'ingest-execution-log'
+    abort '[usage] no input file' unless file && File.exist?(file)
+    rec = AIUsage.append(AIUsage.from_execution_log(File.read(file, encoding: 'UTF-8'), agent: agent))
+    warn "[usage] recorded #{rec['id']}: #{rec['model']} $#{format('%.4f', rec['cost_usd'])} (#{rec['source']})"
+  else
+    abort "usage: usage.rb ingest-claude <result.json> [--agent X] [--rc N] [--emit-result]\n" \
+          "       usage.rb ingest-execution-log <log.json> [--agent X]"
+  end
+end