Backed by: state/lib/log.ts (reads dispatches.ndjson + other run logs)

ai-spend

Reads state/log/dispatches.ndjson + ~/.claude/logs/agent-runs.ndjson + (optional) API-side usage exports. Groups by model, sums cost, and emits a per-model + per-day breakdown.

Steps

1. Tail-read each log, parse NDJSON.
2. Group by model, sum cost_usd.
3. Write to state/log/ai-spend/<month>.md.

Eval

Actor: the ndjson parser + aggregation logic. Auditor: cross-check against source row count.

const source_rows = dispatches_ndjson.length;
const sum_check = Object.values(by_model).reduce((a, b) => a + b, 0);
const reconciles = Math.abs(sum_check - total_usd) < 0.01;
const no_orphan_rows = parsed_rows === source_rows;

score("ai-spend", run_id, {
  score:
    source_rows === 0 && reason_empty ? 1.0 :
    source_rows === 0 && !reason_empty ? 0.0 :
    reconciles && no_orphan_rows ? 1.0 :
    reconciles ? 0.5 :
    0.0,
  total_usd,
  model_count: Object.keys(by_model).length,
  row_count,
  source_rows,
  reconciles,
  primary_issue:
    source_rows === 0 && !reason_empty ? "silent-empty" :
    !reconciles ? "model-sum-mismatch" :
    !no_orphan_rows ? "unparsed-rows" : null,
});

Reconciliation gate: sum-of-models must equal total, all source rows must parse. Silent empty (logs exist but report is blank) scores 0.0.

Gotchas

• Dispatch logs may have missing cost_usd when pi's parser returns

usage=null. Skip those with a warning, not a failure.

• Current dispatch logs may use costUsd camelCase. Normalize

cost_usd ?? costUsd ?? cost before summing.

• Anthropic's API export and dispatch ndjson can double-count if both

routed through the same model. Dedupe by run_id.

ai-spend - loader

Per-turn rules for the ai-spend skill. Full reference: state/skills/ai-spend.md. Do not skip these.

Critical Rules

• NEVER fail-hard on a missing cost_usd - pi's parser returns usage=null sometimes; skip with a warning, don't blow up the report
• ALWAYS normalize cost_usd ?? costUsd ?? cost before summing - current dispatch logs use camelCase
• ALWAYS dedupe by run_id - Anthropic's API export and dispatch ndjson can double-count the same model
• ALWAYS treat silent-empty (logs exist, report blank) as score 0.0, not as a successful empty run

Commands

|invoke: read state/log/dispatches.ndjson + ~/.claude/logs/agent-runs.ndjson, group by model, write state/log/ai-spend/<month>.md |verify: reconciliation gate - sum(by_model) == total_usd AND parsed_rows == source_rows |eval log: state/log/evals.ndjson (skill: "ai-spend")

Known Pitfalls

• Empty-input distinction matters: source_rows == 0 && reason_empty → 1.0, but source_rows == 0 && !reason_empty → 0.0 (silent empty)
• Reconciliation tolerance is < 0.01 - float math, not exact equality
• Optional API-side usage exports (Anthropic admin export) are deduped by run_id, not by timestamp

Self-Test

An agent reading this should correctly:

1. [ ] Skip a dispatch row with null cost rather than abort
2. [ ] Read both cost_usd and costUsd field names
3. [ ] Score a silent-empty report as 0.0, not 1.0

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] ai-spend: <what was missing>" >> ~/.claude/logs/snappy-os-loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this .agents.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] <skill-name>: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/agents-md-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.