agentwrangler 0.1.1-next.2e8c141 → 0.1.1-next.2f6c1df

package/README.md

@@ -1,184 +1,104 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="AgentWrangler logo" width="260">
+  <img src="https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/logo.png" alt="AgentWrangler logo" width="200">
 </p>
 
-<h1 align="center">AgentWrangler</h1>
+# AgentWrangler
 
-<p align="center">
-  <b>See where your Claude Code tokens go — and whether the work actually shipped.</b><br>
-  Local-first observability for Claude Code: token spend, session outcomes, waste detection,
-  and installable guardrails. Runs entirely on your machine.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/agentwrangler"><img src="https://img.shields.io/npm/v/agentwrangler" alt="npm version"></a>
-  <a href="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml"><img src="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://img.shields.io/node/v/agentwrangler"><img src="https://img.shields.io/node/v/agentwrangler" alt="node version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="license"></a>
-</p>
-
-![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
-
-<!--
-  All screenshots and the demo GIF in this README are captured from a SANITIZED instance
-  (Vite test-mode fixtures — anonymized names, no live data) so no real workspace/repository
-  names or paths are committed (SEC-101). Regenerate against `npx vite --mode test`.
--->
-
-## Why
-
-Claude Code tells you almost nothing about where your token budget goes. Sessions balloon,
-caches miss, background agents idle — and you find out when you hit the rate limit.
-AgentWrangler reads the transcripts Claude Code already writes to your disk and answers three
-questions:
-
-- **Where did the tokens go?** Per-model, per-workspace, per-session spend with cache economics.
-- **Did the work ship?** Sessions are linked to the pull requests they merged or closed.
-- **What should I change?** Ranked waste-source detectors with modeled savings — and one-click
-  guardrail hooks that warn *inside* Claude Code before waste happens.
-
-No cloud backend, no telemetry, no account. A daemon on `127.0.0.1`, a dashboard in your
-browser, and a SQLite file in your home directory.
+See where your Claude Code tokens go, inspect costly sessions, and track whether a change helped.
+AgentWrangler reads local Claude Code transcripts and serves a dashboard on your machine.
+No account or cloud backend is required.
 
 ## Quick start
 
+Requires **Node 22-24 and npm**, plus Claude Code transcripts for populated charts.
+
 ```sh
 npx agentwrangler@latest
 ```
 
-That's it — requires Node **22–24**. The daemon starts on `http://127.0.0.1:47821`, opens your
-browser, and scans your `~/.claude/projects` transcripts in the background; the dashboard
-appears immediately and fills in as the scan completes.
-
-More options (install from source, GitHub outcomes sync, environment variables):
-**[Getting started →](docs/getting-started.md)**
-
-## Features
-
-### Overview — verdict first, details on demand
-
-One screen answers "how bad is it this week": a spend verdict with trend, your top waste
-source with a copyable fix prompt, live rate-limit gauges (5-hour and 7-day), a burn forecast
-against your calibrated weekly limit, hot sessions, cache efficiency, and per-model
-context-per-turn tiles.
-
-![Overview tab — at-a-glance verdict, rate limits, burn forecast, hot sessions](docs/assets/overview.png)
-
-### Recommendations — waste-source detectors, ranked by impact
-
-Ten detector families watch your sessions for the patterns that actually burn tokens: cache
-misses (the biggest single lever), session hygiene, retry/redundant-read loops, tool-result
-bloat, model routing, idle background sessions, and more. Each recommendation shows modeled
-weekly savings, a confidence tier, and a concrete action — install a hook, copy a config
-snippet, or copy a guided prompt straight into Claude Code. Adopted changes flow into an
-**impact ledger** that tracks the measured effect, and modeled savings are never counted as
-achieved.
-
-![Recommendations tab — ranked detector families with modeled savings and one-click actions](docs/assets/recommendations.png)
-
-### Installable guardrails — local checks inside Claude Code, before the waste
-
-Five small hooks you can install from the dashboard (directly, or via a copyable prompt that
-Claude Code applies itself):
-
-| Guardrail | What it does |
-|---|---|
-| **Context-budget warning** | Warns when a session's context crosses your soft/hard thresholds |
-| **Loop guard** | Flags repeated identical tool failures before they spiral |
-| **Burn alert** | Catches idle sessions still burning tokens in the background |
-| **Pre-compaction checkpoint** | Copies the raw local transcript before an automatic compaction, subject to a local retention cap |
-| **Dangerous-command guard** | Asks before risky shell commands and denies a small catastrophe list |
-
-The context-budget and burn hooks warn. The loop guard warns before it denies repeated identical
-failures, and the dangerous-command guard can ask or deny. Direct install enables all five hooks;
-the copied install prompt enables the context-budget, loop, and burn hooks only. Thresholds are
-tunable from Settings, and direct uninstall removes every AgentWrangler hook.
-
-### Sessions — who spent it, and on what
-
-The highest-cost sessions ranked with their output-to-context split, model, friction band
-(API errors, tool failures, compactions, interrupts), and a "top X% by spend" self-percentile
-chip. Drill into any session for a turn-by-turn timeline, its cost drivers (which detectors
-fired and how hard), and a guided fix prompt built only from measured numbers.
-
-![Sessions tab — highest-cost sessions with friction bands and spend percentiles](docs/assets/sessions.png)
-
-<details>
-<summary>Session detail view</summary>
-
-![Session detail — per-session KPIs, cost drivers, and a measured-context fix prompt](docs/assets/session-detail.png)
-</details>
-
-### Workspaces — spend efficiency by repository
-
-Every repo you run Claude Code in, with spend share, trend, context-per-turn, cache-write
-share, Opus share, and $/turn. With a GitHub token configured, sessions are linked to the PRs
-and commits they produced — so you can see cost-per-merged-PR, not just cost.
-
-![Workspaces tab — per-repository spend, efficiency, and outcome linkage](docs/assets/workspaces.png)
-
-<details>
-<summary>Workspace detail view</summary>
-
-![Workspace detail — top sessions, context composition, and outcomes](docs/assets/workspace-detail.png)
-</details>
-
-### Weekly brief — one page, three decisions
-
-The week in one screen: spend verdict, what changed vs. last week, the top actions to take —
-with a **Copy as Markdown** button so the whole brief drops into a standup note or a message.
+Open **http://127.0.0.1:47821** if the browser does not open automatically. Keep the terminal
+running; press **Ctrl+C** to stop. The first scan runs in the background. An empty history is
+valid: use Claude Code, then return after ingestion. If a daemon is already running, stop it
+before starting another on the same port.
 
-![Briefs tab — weekly verdict, week-over-week deltas, and top actions](docs/assets/briefs.png)
+[Install from source, configure scan roots, or troubleshoot](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md).
 
-### Honest numbers, labeled as such
+## Your first five minutes
 
-Every metric carries an honesty-tier chip — `EXACT`, `LIST_EQUIV`, `MODELED`, `PROXY`,
-`DIRECTIONAL`, `EXPERIMENTAL` — so you always know what is measured versus estimated. Dollar
-figures are list-price *equivalents* (subscription plans aren't billed per token; tokens drive
-rate limits), and the built-in glossary ("How to read this dashboard") defines every
-key metric in plain language. The full tour: **[Dashboard tour →](docs/dashboard-tour.md)**
+1. **Check the scan.** In Overview, read the onboarding status. A completed scan with no
+   recommendations is a valid result. For an unexpected empty history, inspect scan roots
+   and parser health in Settings; saved scan-root changes require a daemon restart.
+2. **Find one expensive session.** Select a date window, open Workspaces, choose a workspace,
+   then open one of its sessions. Compare context, cache writes, and output before deciding
+   what to change.
+3. **Inspect one recommendation.** Open Recommendations and **Show details** on an instance.
+   Read its evidence and caveats. A modeled amount is a projection; directional advice may
+   have no dollar estimate. If nothing fires, there is nothing to adopt just to finish setup.
+4. **Make one deliberate change.** A copied prompt is an artifact to review and run yourself.
+   It does not edit files. After completing a supported change, use **I completed the change**
+   when offered, then **Track this change** to record a baseline.
+5. **Return to the Impact ledger.** Tracking starts observation, not a savings claim. Eligible
+   signals use a 14-day observation window and may finish inconclusive. You can finish this
+   first visit without a GitHub token, calibration, or installed hooks.
 
-## Privacy — local-only by design
+Dollar figures are **list-price equivalents**, not your subscription bill. Modeled savings
+are not achieved savings, and observed improvement does not prove the change caused it.
+GitHub linkage adds outcome metadata; calibration enables the burn forecast. Local spend,
+session inspection, and supported recommendation tracking work without either.
 
-- The daemon binds to **`127.0.0.1`** only. There is no cloud backend, telemetry, or account.
-- Most dashboard data is **aggregates, ids, counts, and structural anchors**. Local command text
-  and filesystem paths can also be retained in SQLite; treat the database as sensitive. The optional
-  direct-install PreCompact hook can separately copy full raw transcripts locally.
-- The optional GitHub token is read locally, never logged, never persisted to the DB.
-- Usage refreshes can call Anthropic with an existing Claude Code sign-in. GitHub outcomes sync
-  calls GitHub only when a token is configured; calibration and G2 judging are separate opt-ins.
+[Worked example: trim always-loaded context and inspect its effect](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context).
 
-Full details, including exactly what is and isn't stored: **[Privacy model →](docs/privacy.md)**
+## Dashboard preview
 
-## Configuration
+![Synthetic Overview: spend for the selected window, model mix, and links to sessions and recommendations](https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/overview.png)
 
-Everything is optional with sensible defaults — port, DB path, scan roots, GitHub token, and
-more are environment variables documented in [Getting started](docs/getting-started.md#configuration)
-and [`.env.example`](.env.example).
+This static preview uses synthetic data. [The dashboard tour](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md)
+contains the other views and an optional animated preview.
 
-## Documentation
+## Pick a question
 
-| Page | What's in it |
+| I want to... | Start here |
 |---|---|
-| [Getting started](docs/getting-started.md) | Install paths, optional setup, configuration, troubleshooting |
-| [Dashboard tour](docs/dashboard-tour.md) | Every tab in depth, plus the metric vocabulary |
-| [Privacy model](docs/privacy.md) | Local storage, raw-checkpoint exception, and network integrations |
-| [Architecture](docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) | Daemon, ingestion, detector, and query design |
-| [Data model & metrics](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) | SQLite schema and metric definitions |
-| [Contributing](.github/CONTRIBUTING.md) | Dev setup, checks, PR expectations |
-| [Security policy](.github/SECURITY.md) | Threat model and how to report a vulnerability |
-
-## Limitations
-
-- Reads Claude Code's JSONL transcript format; an upstream format change can require an
-  ingestion update.
-- Tested on Windows; macOS/Linux are believed working — reports welcome.
-- Single local user by design — no multi-user or team-aggregation mode.
-- Outcome linkage needs a read-only GitHub token; without one the feature stays inert (and
-  Settings says so — nothing fails silently).
-
-## License
-
-[Apache 2.0](LICENSE) © 2026 AgentWrangler contributors.
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md), [SECURITY.md](.github/SECURITY.md), and
-[CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).
+| Find where my tokens went | [Workspaces and Sessions](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#workspaces) |
+| Turn a recommendation into a change | [Worked example](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context) |
+| Understand the dollars and verdicts | [Metric vocabulary](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#glossary-how-to-read-this-dashboard) |
+| Fix an empty dashboard | [First launch](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#first-launch) |
+| Connect GitHub or calibrate limits | [Optional setup](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#optional-setup) |
+| Read a weekly summary | [Briefs](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#briefs) |
+
+## Installable guardrails — local checks inside Claude Code, before the waste
+
+Hooks are optional and require an explicit install. Settings **Install directly** installs
+five hooks; **Copy install prompt** prepares instructions for three. Copying alone installs nothing.
+
+| Hook | Behavior | Install path |
+|---|---|---|
+| Context-budget | Warns when context crosses configured thresholds | Direct or copied prompt |
+| Loop guard | Warns, then can deny repeated identical failures | Direct or copied prompt |
+| Burn alert | Warns about session budget consumption | Direct or copied prompt |
+| Dangerous-command | Can ask or deny risky commands | Direct only |
+| PreCompact checkpoint | Copies raw transcripts locally, with retention limits | Direct only |
+
+[Installation, removal, and the checkpoint privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#in-session-guardrails).
+
+## Privacy and limits
+
+- The daemon binds to **127.0.0.1**. There is no telemetry or hosted product backend.
+- SQLite contains aggregates and structural data, and can also contain local command text
+  and filesystem paths. Treat it as sensitive. The optional PreCompact hook makes separate
+  raw transcript copies on your machine.
+- Usage refresh can contact Anthropic using your existing Claude Code sign-in. GitHub
+  outcomes sync requires a configured token. [Privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/privacy.md).
+- Claude Code format changes can require parser updates. This is a single-user tool.
+- Windows local validation and Linux/macOS CI smoke coverage do not establish full native
+  accessibility or credential-store compatibility on every platform.
+
+## Deeper documentation
+
+[Configuration](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#configuration) |
+[Architecture](https://github.com/Doogit/AgentWrangler/blob/main/docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) |
+[Data model and metrics](https://github.com/Doogit/AgentWrangler/blob/main/docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) |
+[Contributing](https://github.com/Doogit/AgentWrangler/blob/main/.github/CONTRIBUTING.md) |
+[Security policy](https://github.com/Doogit/AgentWrangler/blob/main/.github/SECURITY.md)
+
+[Apache 2.0](https://github.com/Doogit/AgentWrangler/blob/main/LICENSE).

package/dist/apply/jobs.js

@@ -200,6 +200,7 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
     const changedPaths = [];
     let finalized = false;
     let fatalExitMessage = null;
+    let killTimer;
     const cleanup = () => {
         fs.unlink(settingsPath, () => { });
     };
@@ -251,9 +252,11 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
         }
     });
     const timer = setTimeout(() => {
+        // Keep the job exclusive until the child has actually closed. Publishing
+        // FAILED here lets a retry (or workspace cleanup) race the dying process.
+        fatalExitMessage ??= "job timed out";
         proc.kill("SIGTERM");
-        setTimeout(() => proc.kill("SIGKILL"), 2000);
-        markFailed("job timed out");
+        killTimer = setTimeout(() => proc.kill("SIGKILL"), 2000);
     }, rt.timeoutMs);
     proc.on("error", (err) => {
         clearTimeout(timer);
@@ -261,6 +264,7 @@ function runClaudePhase(db, job, rec, phase, settingsPath, rt) {
     });
     proc.on("close", (code) => {
         clearTimeout(timer);
+        clearTimeout(killTimer);
         if (finalized)
             return;
         finalized = true;

package/dist/daemon/router.js

@@ -264,7 +264,7 @@ export function handleApiRequest(_db, req, res, method, url) {
             sendJson(res, 200, getPractices(_db, { from, to }));
             return;
         }
-        // GET /api/efficiency-headroom (BM2 modeled savings vs trailing-window spend)
+        // GET /api/efficiency-headroom (individual weekly estimates; separate selected-window spend)
         if (method === "GET" && pathname === "/api/efficiency-headroom") {
             const { from, to } = resolveWindow(parseWindowFilter(url));
             sendJson(res, 200, getEfficiencyHeadroom(_db, { from, to }));

package/dist/detector/detectors/d10_catalog_footprint.js

@@ -95,7 +95,7 @@ export const d10Detector = {
         const latestProbedAt = rows.reduce((latest, row) => (latest === null || row.probed_at > latest ? row.probed_at : latest), null);
         const refs = rows.map((row) => row.file_ref);
         const evidence = {
-            title: `Review ${state.effective_catalog_state} tool catalog: ${Math.round(catalogTokens / 1000)}K tokens`,
+            title: `Review tool catalog: ${Math.round(catalogTokens / 1000)}K estimated tokens`,
             component: "MCP_SCHEMAS",
             file_ref: refs.length === 1 ? refs[0] : null,
             file_refs: refs,
@@ -120,7 +120,7 @@ export const d10Detector = {
             scopeKey: "D10|global|MCP_SCHEMAS",
             category: "TOOLING",
             scope_workspace_id: null,
-            lever: "Too many connected tools, plugins, and skills",
+            lever: "The tool catalog exceeds its size target; actual loaded context is not measured",
             target_metric: "catalog_context_tokens",
             // R11 is required before catalog size can become a freed-headroom claim.
             modeled_savings_u_per_wk: null,

package/dist/detector/detectors/d1_ctx_always_loaded.js

@@ -29,16 +29,16 @@ function stepsFor(component, fileRef) {
         case "CLAUDE_MD":
             return [
                 `Open ${fileRef}`,
-                "Move changelog/history/rationale prose to a linked doc",
-                "Keep current-state rules + pointers only",
-                "Re-measure: probe re-sizes on next daemon pass",
+                "Move changelogs, history, and background explanations to a linked document",
+                "Keep only current rules and links here",
+                "Check the size again after the next local scan",
             ];
         case "MEMORY":
             return [
                 `Review memory files under ${fileRef}`,
-                "Delete stale or duplicate memories",
-                "Consolidate overlapping facts into concise entries",
-                "Re-measure: probe re-sizes on next daemon pass",
+                "Remove old or duplicate memories",
+                "Combine overlapping facts into concise entries",
+                "Check the size again after the next local scan",
             ];
         case "MCP_SCHEMAS":
             return [
@@ -62,13 +62,13 @@ function titleFor(component, tokens, target) {
 function leverFor(component) {
     switch (component) {
         case "CLAUDE_MD":
-            return "Move changelog/history prose out of CLAUDE.md; keep current-state + pointers.";
+            return "Move changelogs and history out of CLAUDE.md; keep current rules and links.";
         case "MEMORY":
-            return "Prune stale/duplicate memories; consolidate overlapping facts.";
+            return "Remove old or duplicate memories and combine overlapping facts.";
         case "MCP_SCHEMAS":
             return "Identify rarely-used skills/plugins; extract to on-demand or disable.";
         default:
-            return "Trim always-loaded context source to the per-source target.";
+            return "Shorten this content that is loaded into every conversation.";
     }
 }
 export const d1Detector = {

package/dist/detector/detectors/d2_session_long_full_context.js

@@ -81,12 +81,12 @@ export const d2Detector = {
             scopeKey: `D2|global|${formula.model}`,
             category: "CONTEXT",
             scope_workspace_id: null,
-            lever: "/clear between unrelated tasks; split long work; avoid mid-task /compact.",
+            lever: "Use /clear between unrelated tasks, split long work into separate sessions, and avoid automatic compaction while you are working.",
             target_metric: "avg_context_per_turn",
             modeled_savings_u_per_wk: savingsU,
             modeled_formula: formula,
             evidence: {
-                title: `Shorten sessions: ${n} long-context run${n === 1 ? "" : "s"} this week`,
+                title: `Split ${n} long session${n === 1 ? "" : "s"} this week`,
                 qualifying_session_count: qualifying.length,
                 qualifying_turn_count: qualifyingTurnCount,
                 session_ids: sessionIds,

package/dist/detector/detectors/d4_model_mismatch.js

@@ -192,7 +192,7 @@ export const d4Detector = {
                 ? {
                     withheld: true,
                     withheld_reason: `Sonnet weekly cap is the binding constraint (Sonnet util ${bindingSonnet.utilization} >= all-models ${perModelSnapshot.seven_day_util}) — routing Opus->Sonnet would worsen it`,
-                    title: `[withheld] Route Opus→Sonnet: ${mismatchPct}% of turns are high-context low-output`,
+                    title: `Model change is not recommended: ${mismatchPct}% of Opus turns have large context and little output`,
                 }
                 : perModelSnapshot && sonnetEntries && sonnetEntries.length > 0
                     ? { cap_attribution: "all_models_or_opus_binds" }
@@ -202,7 +202,7 @@ export const d4Detector = {
                 category: "MODEL",
                 scope_workspace_id: workspace_id,
                 // Advisory gate (W0.3): which cap binds is NOT inferable from JSONL. Conditional lever.
-                lever: "If your all-models / Opus / 5h cap is the one binding — check /usage — these high-context low-output Opus turns are Sonnet-movable. This does NOT help, and can hurt, if your Sonnet-specific weekly cap is the binding constraint.",
+                lever: "Check /usage first. If your overall, Opus, or 5-hour limit is filling, these large-context Opus turns with little output may be suitable for Sonnet. Do not switch if your Sonnet weekly limit is the one filling.",
                 target_metric: "model_mix_opus_fraction",
                 // Advisory gate: suppress the crisp $/wk headline until live /usage cap-attribution exists.
                 modeled_savings_u_per_wk: null,
@@ -210,7 +210,7 @@ export const d4Detector = {
                 // Destructure out result_usd_per_wk so the advisory formula carries no crisp $/wk figure.
                 modeled_formula: (({ result_usd_per_wk: _, ...rest }) => ({ ...rest, kind: "ADVISORY" }))(formula),
                 evidence: {
-                    title: `Route Opus→Sonnet: ${mismatchPct}% of turns are high-context low-output`,
+                    title: `Review model choice: ${mismatchPct}% of Opus turns have large context and little output`,
                     workspace_id,
                     total_opus_turns_per_week: totalOpus,
                     mismatch_turns_per_week: mismatchCount,

package/dist/detector/detectors/d6_tool_result_bloat.js

@@ -262,7 +262,7 @@ export const d6Detector = {
                 modeled_savings_u_per_wk: modeledSavingsU,
                 modeled_formula: formula,
                 evidence: {
-                    title: `Trim tool output: ${Math.round(bloatShare * 100)}% bloat share in session`,
+                    title: `Reduce large tool results: ${Math.round(bloatShare * 100)}% of this session's context`,
                     session_id: row.session_id,
                     workspace_id: row.workspace_id,
                     tool_result_bytes: row.tool_result_bytes,

package/dist/detector/detectors/d7_loop_retry_waste.js

@@ -299,7 +299,7 @@ export const d7Detector = {
                     expression: "cap-weighted exposure of turns owning repeat-excess events; not an avoidable-token or USD savings estimate",
                 },
                 evidence: {
-                    title: `Break retry loops: ${flaggedTurns.size} flagged turn${flaggedTurns.size === 1 ? "" : "s"} in session`,
+                    title: `Stop repeated attempts: ${flaggedTurns.size} affected turn${flaggedTurns.size === 1 ? "" : "s"} in this session`,
                     session_id: sessionId,
                     workspace_id: session.workspaceId,
                     loop_flagged_event_count: flaggedEventIds.size,

package/dist/detector/detectors/d8_cache_write_churn.js

@@ -125,7 +125,7 @@ export const d8Detector = {
             // TTL-regime facet: is this session dominated by 5m-tier creation?
             const fiveMinCreation = events.reduce((s, e) => s + e.cache_write_5m, 0);
             const regime5m = totalCreation > 0 && fiveMinCreation / totalCreation >= D8_REGIME_5M_SHARE;
-            const baseLever = "Use /clear (or resume-from-summary) before idling past the cache TTL, and batch prefix/CLAUDE.md edits to a session boundary so they don't invalidate the warm cache mid-session.";
+            const baseLever = "Before a long break, use /clear or resume from a summary. Make instruction-file changes between sessions so they do not rebuild the cache while you work.";
             const lever = regime5m
                 ? `${baseLever} This session's creation is mostly 5m-tier — enable the 1h cache regime (ENABLE_PROMPT_CACHING_1H) where long pauses are unavoidable.`
                 : baseLever;
@@ -138,7 +138,7 @@ export const d8Detector = {
                 modeled_savings_u_per_wk: savingsU,
                 modeled_formula: formula,
                 evidence: {
-                    title: `Reduce cache-write churn: ${events.length} re-write${events.length === 1 ? "" : "s"} in session`,
+                    title: `Avoid repeated cache rebuilds: ${events.length} after a long pause`,
                     session_id: sessionId,
                     workspace_id,
                     churn_event_count: events.length,

package/dist/detector/detectors/d9_idle_background_session.js

@@ -62,7 +62,7 @@ export const d9Detector = {
                 modeled_savings_u_per_wk: null,
                 modeled_formula: d9Formula(sidechainCap, D9_UNPRODUCTIVE_FRACTION),
                 evidence: {
-                    title: `Review background fan-out: ${Math.round(share * 100)}% cap-weighted sidechain`,
+                    title: `Review background-agent work: ${Math.round(share * 100)}% of estimated limit use`,
                     workspace_id: row.workspace_id,
                     sidechain_cap_weighted_tokens: sidechainCap,
                     total_cap_weighted_tokens: totalCap,

package/dist/hook/precompact-checkpoint-hook.mjs

@@ -11,6 +11,7 @@
  * committed). The hook writes no transcript content to stdout/stderr.
  */
 
+import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -19,9 +20,11 @@ import { fileURLToPath } from "node:url";
 
 const MAX_COUNT = 20;
 const MAX_BYTES = 500 * 1024 * 1024; // 500 MiB across all snapshots
+const MAX_COLLISION_ATTEMPTS = 16;
 
-// Monotonic counter so two firings in the same millisecond get distinct filenames
-// that still sort in write order (the timestamp dominates; this breaks same-ms ties).
+// A per-process counter preserves local write ordering.  The random token prevents
+// separately spawned hooks with the same session and millisecond from choosing the
+// same name; exclusive creation below is the final no-overwrite guard.
 let snapshotCounter = 0;
 
 /** The directory snapshots are written to (overridable for tests). */
@@ -33,7 +36,8 @@ export function checkpointDir() {
 export function snapshotName(sessionId, now) {
   snapshotCounter = (snapshotCounter + 1) % 1_000_000;
   const stamp = now.toISOString().replace(/[:.]/g, "-");
-  return `${encodeURIComponent(sessionId)}-${stamp}-${String(snapshotCounter).padStart(6, "0")}.jsonl`;
+  const counter = String(snapshotCounter).padStart(6, "0");
+  return `${encodeURIComponent(sessionId)}-${stamp}-${counter}-${randomBytes(6).toString("hex")}.jsonl`;
 }
 
 /**
@@ -43,14 +47,22 @@ export function snapshotName(sessionId, now) {
 export function writeCheckpoint(transcriptPath, sessionId, dir, now = new Date()) {
   if (typeof transcriptPath !== "string" || !fs.existsSync(transcriptPath)) return null;
   fs.mkdirSync(dir, { recursive: true });
-  const dest = path.join(dir, snapshotName(sessionId, now));
-  fs.copyFileSync(transcriptPath, dest);
-  try {
-    fs.chmodSync(dest, 0o600);
-  } catch {
-    // chmod is a no-op boundary on Windows; the user-profile ACL is the equivalent guard.
+  for (let attempt = 0; attempt < MAX_COLLISION_ATTEMPTS; attempt += 1) {
+    const dest = path.join(dir, snapshotName(sessionId, now));
+    try {
+      fs.copyFileSync(transcriptPath, dest, fs.constants.COPYFILE_EXCL);
+    } catch (error) {
+      if (error?.code === "EEXIST") continue;
+      throw error;
+    }
+    try {
+      fs.chmodSync(dest, 0o600);
+    } catch {
+      // chmod is a no-op boundary on Windows; the user-profile ACL is the equivalent guard.
+    }
+    return dest;
   }
-  return dest;
+  return null;
 }
 
 /**
@@ -58,9 +70,10 @@ export function writeCheckpoint(transcriptPath, sessionId, dir, now = new Date()
  * not create. Malformed .jsonl files are deliberately left alone by retention.
  */
 function snapshotTimestamp(name) {
-  const match = /-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z-\d{6}\.jsonl$/.exec(
-    name,
-  );
+  const match =
+    /-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z-\d{6}(?:-[a-f0-9]{12})?\.jsonl$/.exec(
+      name,
+    );
   if (!match) return null;
   const [, year, month, day, hour, minute, second, millisecond] = match;
   const timestamp = Date.parse(

package/dist/query/api/cost-per-success.js

@@ -21,6 +21,7 @@ export function getCostPerSuccess(db, workspaceId, from, to) {
             to,
             workspaceId,
             workspaceId,
+            workspaceId,
             from,
             to,
             workspaceId,
@@ -46,6 +47,14 @@ export function getCostPerSuccess(db, workspaceId, from, to) {
            JOIN merged_work_items mwi ON mwi.work_item_id = swl.work_item_id
           WHERE 1 = 1${sessionFilter}
        ),
+       merged_session_links AS (
+         SELECT swl.session_id, COUNT(DISTINCT swl.work_item_id) AS merged_pr_links
+           FROM session_work_links swl
+           JOIN merged_work_items mwi ON mwi.work_item_id = swl.work_item_id
+           JOIN sessions s ON s.session_id = swl.session_id
+          WHERE 1 = 1${sessionFilter}
+          GROUP BY swl.session_id
+       ),
        in_window_sessions AS (
          SELECT s.session_id, s.cost_equiv_u
            FROM sessions s
@@ -64,6 +73,8 @@ export function getCostPerSuccess(db, workspaceId, from, to) {
        SELECT
          (SELECT COUNT(*) FROM merged_work_items) AS merged_pr_count,
          (SELECT COUNT(*) FROM closed_unmerged_work_items) AS closed_unmerged_count,
+         (SELECT COUNT(*) FROM merged_session_links) AS unique_linked_session_count,
+         (SELECT COUNT(*) FROM merged_session_links WHERE merged_pr_links > 1) AS shared_linked_session_count,
          CASE WHEN (SELECT COUNT(*) FROM merged_work_items) = 0 THEN NULL
               ELSE (SELECT COALESCE(SUM(cost_equiv_u), 0) FROM merged_session_costs) * 1.0
                    / (SELECT COUNT(*) FROM merged_work_items)
@@ -91,13 +102,14 @@ export function getCostPerSuccess(db, workspaceId, from, to) {
     };
     return buildResponse(data, {
         claim_kind: "OBS_PROXY",
+        metric_definition_version: "esf-1",
         n: data.merged_pr_count,
         window: { from, to },
         qualification: {
             provisional_excluded: false,
             unpriced_turns: 0,
             claim_kinds_count: 1,
-            note: "Directional (OBS_PROXY): survivorship bias (heavy-spend sessions that never open a PR are invisible); reviewer-dependence (merge is a human decision, not a quality guarantee); linkage-coverage cap (only linkage_coverage_pct% of in-window sessions are linked to a PR, so unlinked spend is excluded). cost_per_merged_pr_u uses lifecycle attribution: each merged PR carries the full cost of every linked session whenever it ran, so narrowing the window changes the PR population, not the per-PR cost.",
+            note: "Directional (OBS_PROXY): Unique linked-session cost / merged PRs. The terminal-date PR cohort counts each linked session once, even when it links to multiple merged PRs; shared sessions are coverage, not per-PR allocation. Full linked-session lifecycle cost is used, while linkage_coverage_pct is a separate session-start coverage observation. Unknown pricing is not free. Survivorship bias and reviewer dependence remain.",
         },
         ...(workspaceId === null ? {} : { drilldown_ids: { workspace_id: workspaceId } }),
     });