clawback

Run a counterbalanced A/B knob block end to end and produce a report. Orchestrates the whole validation loop the other skills do piecemeal — for each arm it starts a clawback proxy with that arm's knobs and its OWN --state file (fresh SESSION KEY, no clawback-side carry-over), drives N turns of load through it (pty or replay driver), stops it, then analyzes the per-arm turn-logs and renders the charts. No cache-salt: production forwards none, so neither does the harness. Default block is A0 (passthrough baseline) vs A5 (recommended stack); the analyzer pools all passthrough turns into the baseline and compares each treatment arm against it, so the block must include A0 and may carry several treatment arms at once. Use this to run the full A/B runbook in one command. The pty driver spends real Anthropic tokens (one run per arm) — pin --model.

Fast, read-only per-arm turn-log summary — billable turn count, httpStatus tally (catches rate-limiting / non-200s mid-run), cache_read/creation sums with the ephemeral 5m-vs-1h split (a direct knob-sanity check: A2/A3/A5 should show ephemeral_1h > 0, A0/A1/A4 should not), token-weighted hit rate, and thinkingBudget. Unlike the heavyweight `bench` analyzer it does no bootstrap/CI/pricing, so it is cheap to run at each arm boundary WHILE a suite is still in flight. Safe on a live, actively-appended NDJSON file (a partial trailing line is skipped). Use it to spot-check a just-finished arm before the next one starts.

Analyze clawback turn-logs (NDJSON) to compare treatment vs passthrough arms. Produces report.md, report.csv, summary.json, manifest.json. Headline is billable input tokens reclaimed per turn (full-rate quota saved, no pricing) with a bootstrap 95% CI; per-turn $ and hit-rate are a demoted cost appendix, all stratified by inter-turn gap bucket. Use after the operator has collected counter-balanced windows.

Capture a REAL Claude Code /v1/messages body as a replay fixture, so the HTTP replay arm (.skills/replay) faithfully reproduces Claude Code's cache_control breakpoint structure (a hand-authored fixture makes the 1h-TTL knob look like a no-op). Starts a clawback proxy with --capture-body, drives ONE real claude turn through it via the PTY driver, verifies the dump carries cache_control breakpoints, and promotes it to the fixture path. Spends real Anthropic tokens (exactly one turn; pin a cheap model with --model). Use once before replay-based benchmarking, or to refresh the fixture when Claude Code changes its request shape.

Render the clawback share card in BOTH tones (neg + pos) as a DESIGN render-only proof — NOT a benchmark result — so the share-card atmosphere (deep-purple LENS_CORE centre, win-only cyan corona, darkened gradients) can be eyeballed in one pass. neg uses a real run's amber regression card (purple core, no corona); pos is a SYNTHETIC fixture built only to exercise the renderer's win branch (purple core + cyan corona) — its number is fabricated, never published. Delegates to the shared preview_card.sh. Use when tweaking the share-card renderer's visuals and you want to see both tones side by side.

Drive the REAL claude binary through clawback's PTY channel at a scripted inter-turn gap schedule — the faithful load arm. Because the bytes on the wire are produced by genuine Claude Code, this is the only driver that exercises the 1h-TTL nested-cache-control rewrite (arm A2) authentically. Use for headline/moat numbers and to cross-check the HTTP replay arm (.skills/replay). Requires node-pty and a running clawback proxy.

Turn a benchmark turn-log (or an already-analyzed run dir) into a report the GUI shows right away — runs analyze + plot so summary.json + report.csv AND charts/tokens_saved.svg + charts/tokens_saved.bg.svg all exist. The bare .bg.svg is the share-card PNG background; without it the downloaded/posted card has no chart lines. Also backfills old runs (--all) that predate the .bg.svg output. Use after a manual analyze, or to repair runs whose share PNG renders as a solid card. Pass --card to also bake the share-card PNG to disk (opt-in, best-effort).

Answer the load-bearing question "does clawback SESSION-KEY fragmentation actually cost Anthropic tokens?" from a finished run's per-instance turn-logs — zero new tokens. The prefix-fragmentation count (distinct SESSION KEYs per systemStableKey) tells you the cch rotation fragmented clawback's view; it does NOT tell you whether Anthropic cold-started. This does: it filters to REAL turns (mode=hash, drops keep-alive pings), partitions them into FRESH-key (sessionKey rotated vs the previous turn on the same systemStableKey stream) vs REPEAT-key, and prints mean cache_read / cache_creation / input / billable for each. If fresh-key turns read warm (read >> creation), fragmentation is NOT a valid cold-start proxy on that build and strip-ephemeral's token win is ~0 on a warm loop (the real win is eviction-regime, plus a tiny/fast clawback state file). Use after `.skills/paired` or `.skills/ab` on instance.*.ndjson; re-run on the eviction (L3 / --gap-sec 3600) arms to see where fragmentation finally bites.

Statically inspect prompt-cache breakpoints in a captured /v1/messages body or a clawback --state file, with ZERO token spend and no API calls. Answers "where are the cache_control breakpoints, and which ephemeral tokens (cch / date / <env>) sit inside which cached prefixes?" — i.e. what a single mutation cold-starts. Use it to SEE why strip-ephemeral matters (cch precedes the earliest breakpoint, so it cold-starts every cached prefix every request) before spending tokens on a dynamic probe. Read-only and safe to run against a live benchmark.

Run the clawback proxy and watch its log output for errors. Starts the bare proxy (honoring config layering), captures combined stdout+stderr to a log file, and follows it with warn/error/4xx/5xx lines highlighted. Supports foreground follow, background --detach (with --stop/--status), and --attach to tail an already-running proxy's log. Use when you want to launch clawback and monitor it for errors/regressions, or smoke-watch it after a change.

Watch an already-detached clawback proxy as an event stream — surface only actionable log lines (error/warn/4xx/5xx/crash signatures, plus rebind and runtime-mode toggles) AND announce a loud "PROXY DOWN" line the instant the proxy pid dies. Fills the gap that run_monitor.sh --attach leaves: a bare tail goes SILENT on a crash (BSD tail has no --pid), so silence reads as healthy-idle. Use when acting as the operator agent keeping the server alive — point an agent's Monitor tool at it (persistent), react to PROXY DOWN by reading the log tail for the crash cause and restarting via the restart skill.

Paired shadow-capture — one real claude session that captures the no-clawback baseline AND applies the armed knobs at the same time. This is the "shadow mode" knob for baseline capture: instead of forfeiting the optimizations for the measurement window (a plain passthrough baseline), the tee fans every turn to TWO unmodified clawback instances — PRIMARY (armed, default A5, streamed back to claude) and SHADOW (A0 passthrough, consumed for usage then discarded). Because both arms bill the SAME request bytes under the same turn, the analyzer pairs them turn-for-turn (pairBillableByPairSeq / bootstrapPairedDiff) for a tight turn-matched reclaim CI — not two free-running sessions that diverge. COSTS ~2x your Anthropic quota (every turn billed twice); the script REFUSES to run without --ack-2x. Use when you want a turn-matched A/B from a single live session.

Render the tokens-saved chart from an analyzer output directory. Dependency-free SVG generator — reads summary.json + report.csv produced by benchmark/bin/analyze.js and emits TWO SVGs of the same cumulative billable-input story (passthrough baseline vs clawback, honest green/red shaded gap): tokens_saved.svg (labeled, titled "Token Efficiency", for on-screen) and tokens_saved.bg.svg (BARE 1200×630, lines + wedge only, no text — the share-card PNG background; without it the posted card has no chart lines). No cost/$/CI tables. Use after .skills/bench to produce the visuals that document the win.

Compose a finished run's social SHARE CARD (the chart background + dark scrim + hero headline) and rasterize it to PNG so it can be eyeballed without opening the report GUI in a browser. Use it to check the thing the GUI's client-side PNG actually ships — most importantly, whether the chart lines survive the translucent scrim (a scrim dark enough for the light headline can crush the dark chart lines below the WCAG 1.4.11 3:1 floor, which renders as a near-blank card). Reads a run's summary.json + charts/tokens_saved.bg.svg; writes charts/share_card.svg (always) and charts/share_card.png (best-effort raster).

Drive a reproducible HTTP replay load against a running clawback proxy. Replays one captured /v1/messages fixture at a load profile's inter-turn gap schedule, with built-in carry-over control (fresh path-mode session id + per-block cache nonce). Auth is an OAuth bearer (CLAWBACK_OAUTH_TOKEN), never an Anthropic API key; pre-flights the proxy and bearer before spending tokens. Use to generate clean, per-knob, deterministic-timing traffic for the analyzer; pair with .skills/drive (the faithful PTY arm) to cross-check.

End-to-end smoke test for the /<admin-path>/report saved-run viewer. Boots the real clawback binary against the repo's runs/ dir and curls every report route, asserting status + content, prefix mutability, public-read exemption, and that sensitive run-dir siblings stay unreachable. Use after touching src/report.js, src/report_ui/*, or the admin/report wiring.

Restart the detached clawback proxy and reconnect its monitor. Stops the proxy previously started with run_monitor.sh --detach (if any), then starts a fresh one in the background; the run log is recreated in place so a tail -F follower (run_monitor.sh --attach, or an agent's Monitor tool) re-attaches automatically. Honors the same --log-file/--pid-file options and `--` passthrough as run_monitor.sh. Use after a config or code change to cycle the proxy without disrupting the monitor. Pass --watch to keep restarting automatically whenever a source file under src/ or bin/ changes.

Shut down the clawback proxy stack. By default stops ONLY the detached proxy started via run_monitor.sh --detach (graceful SIGTERM, then SIGKILL after ~5s) and removes its pidfile, letting the monitor go quiet — interactive `clawback claude` sessions are left running on purpose. Pass --sessions for a full teardown that also SIGTERMs every clawback claude wrapper, listing each before signaling. Use to cleanly stop the proxy, or to tear the whole stack down.

Run the clawback end-to-end smoke test. Starts a mock upstream, spawns the proxy against it, exercises path-mode and hash-mode requests, walks the admin API, and prints the persisted state. Use when verifying the proxy still works after changes.

Cheaply prove the PTY turn-submission mechanism actually lands turns BEFORE any timed or headline run spends real tokens. Runs .skills/submit-smoke/scripts/submit_smoke.sh — one tiny passthrough Haiku block — and checks two independent signals: the driver's own "confirmed N/M" tally AND the count of real (non-ping) records the proxy logged. PASS only when every turn confirmed and the proxy logged at least that many real turns. Also reports which Enter encoding won (pure \r vs an escalated \n / \r\n fallback). Run this first whenever the driver, the submit helper (benchmark/lib/turn_submit.js), or the claude TUI version changes.

Answer the research question "does a keep-alive ping that itself gets 429'd still refresh the prompt-cache TTL on Anthropic's side?" from captured turn-logs. A 429'd ping has no usage body, so its effect is only visible through the NEXT successful request on the same SESSION KEY. Runs .skills/ttl-429/scripts/ttl_429.mjs over one or more instance.*.ndjson turn-logs and classifies every 429'd ping as REFRESH (warm probe across the TTL boundary, no masking 200), NO-REFRESH (cold probe), or INCONCLUSIVE (boundary not crossed, or a success refreshed it first). Also prints per-session ping warmth, which flags PHANTOM keep-alive loops (a session whose every ping reads cold — an uncacheable aux context that should never have been armed). Pass --ttl-sec 3600 for an arm running --inject-extended-cache-ttl; default 300s is Anthropic's stock cache TTL. Read-only post-hoc analysis; spends no tokens.

Config doctor for clawback — loads the merged config (DEFAULTS < global < ./CLAWBACK.md < CLI overrides) exactly as the proxy's loadConfig does, prints a secret-free summary of the resolved values plus the merge-order sources, and exits non-zero if the canonical CLAWBACK.md did NOT take effect (host not 0.0.0.0, tls off, or adminToken missing) so a bad parse fails loudly instead of silently falling back to loopback defaults. Read-only; never prints the adminToken value, only its length. Use to confirm a CLAWBACK.md edit actually parsed and merged before starting the proxy, or to debug which config layer won.

Quiet operator watch for a detached clawback proxy — stream ONLY legitimate errors and never the benign flood. Wakes on [error]/[fatal] lines, crash signatures (uncaught/EADDRINUSE/ECONN*/Error:/self-loop), server-side 5xx that are NOT the transient 529, real (non-keep-alive) request failures, and a loud "PROXY DOWN" the instant the pid dies (then exits non-zero). Deliberately silences keep-alive ping failures (401 auth-stale / 404 retired-model / 429/529), real-request 429+529 (Claude Code auto-retries), and [info] no-route attach probes — all observed-benign and not actionable. Use when pointing an agent's Monitor tool at the live proxy and you want zero token burn on no-ops, only real errors. Prefer this over the broader `operate` skill when noise/cost matters.

Emit-on-event health watcher for a long paired/ab benchmark run, meant to be fed to the Monitor tool (each stdout line becomes one notification) so an unattended 75-min run cannot fail silently. Coverage-first by design — it speaks up on liveness (ALIVE), on new error signatures in the proxy/tee logs (ERROR), on a stall or crash (STALL/DEAD — silence is not success), and on completion (COMPLETE) — not just the happy path. Stall is tracked on the SHADOW (A0) turn-log, which is passthrough with keep-alive OFF so every line is a real turn; the PRIMARY (A5) log also grows from keep-alive pings during idle gaps and would mask a stalled conversation, so it must not drive stall detection. Use it to babysit `.skills/paired` or `.skills/ab` runs whose wall clock exceeds the Monitor's 60-min non-persistent cap (run it persistent).

Generate or refresh the canonical CLAWBACK.md config. The front matter is built from the live DEFAULTS export in src/config.js (so it can never drift as options are added), with the only forced deviations being the two a LAN-reachable bind needs — host=0.0.0.0 and tls=true. adminToken is left as a null placeholder for you to set (it no longer mints one); a real existing token, or an explicit CLAWBACK_CANONICAL_TOKEN, is PRESERVED, and a token's value is NEVER printed (only presence and length). With no args it writes BOTH ./CLAWBACK.md and the global ~/.config/clawback/CLAWBACK.md. Use to (re)create a canonical config, or after adding an option or changing a default.