agentwrangler 0.1.0 → 0.1.1-next.2f6c1df

package/README.md

@@ -1,116 +1,104 @@
-# AgentWrangler
-
-Local-first observability for Claude Code that **joins your token spend to the pull requests it
-actually merged or closed** — entirely on your machine — and ships **installable guardrails** (a
-dangerous-command block, a pre-compaction checkpoint, a context-budget warning) you turn on from the
-dashboard. See where your agent budget goes, whether the work shipped, and cut the waste.
-
-## Local-only — your data never leaves your machine
-
-AgentWrangler runs entirely on your computer: a daemon bound to **`127.0.0.1`** and a dashboard in
-your browser that talks only to that loopback address. **No cloud backend, no telemetry, nothing
-phones home.** It reads your local Claude Code transcripts, stores only aggregates in a local SQLite
-file (`~/.agentwrangler/db.sqlite`), and never persists raw transcript or PR content — only counts,
-ids, and structural anchors (the SEC-101 privacy invariant). An optional GitHub token, used only for
-the outcomes feature, is read locally, never logged, and never leaves your machine.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/logo.png" alt="AgentWrangler logo" width="200">
+</p>
 
-**Privacy exception (opt-in):** `npm run evidence:judge-g2 -- --execute` is the only path where PR
-content leaves the machine. It calls the Claude API with your local Claude Code OAuth credential to
-adjudicate G2 deferral findings, and runs only when `g2_claude_judge_opt_in` is enabled; otherwise it
-refuses to run. No rationale text is persisted.
-
-![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
+# AgentWrangler
 
-<!--
-  Captured from a SANITIZED instance (Vite test-mode fixtures — anonymized names, no
-  live data) so no real workspace/repository names/paths are committed (SEC-101).
-  Regenerate with the ce-demo-reel skill against `npx vite --mode test`.
--->
+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
 
-Requirements: **Node `>=22 <25`** and npm.
-
-```sh
-git clone https://github.com/Doogit/AgentWrangler && cd AgentWrangler
-npm ci
-npm run build:ui       # build the dashboard
-npm run daemon         # starts the daemon and opens your browser
-```
-
-Then open **http://127.0.0.1:47821** (the daemon opens it for you unless `AW_NO_OPEN=1`).
-
-After installing dependencies you can also do it in one step:
+Requires **Node 22-24 and npm**, plus Claude Code transcripts for populated charts.
 
 ```sh
-npm ci                 # required first — the CLI runs via tsx, a devDependency
-npx agentwrangler      # builds the UI if needed, then launches the daemon + browser
+npx agentwrangler@latest
 ```
 
-On first launch the daemon binds the port immediately and serves a loading page, then scans your
-`~/.claude/projects/**/*.jsonl` transcripts in the background — the dashboard appears right away and
-fills in as the scan completes, so a large history won't block the page from opening.
-
-## Optional setup
+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.
 
-- **GitHub outcomes sync** — links sessions to the PRs/commits they produced. Provide a read-only
-  GitHub PAT via the `AW_GITHUB_TOKEN` environment variable (works on all platforms). On Windows you
-  may instead store it in Credential Manager as `AgentWrangler-GithubToken`. Without a token the
-  outcomes feature stays inert and Settings tells you so — nothing fails silently.
-- **Usage reader** — reads your Claude Code OAuth credentials locally to calibrate the weekly limit
-  and burn forecast. Sign in through Claude Code as usual; Settings shows the reader status.
-- **Context-budget hook** — an optional PreToolUse hook that warns before long sessions balloon.
-  Install it from the Settings page (or `npm run install-hook`).
+[Install from source, configure scan roots, or troubleshoot](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md).
 
-## Configuration (environment variables)
+## Your first five minutes
 
-All are optional; sensible defaults apply. See [`.env.example`](.env.example) for the full list.
+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.
 
-| Variable | Purpose | Default |
-|---|---|---|
-| `AW_PORT` | Daemon HTTP port | `47821` |
-| `AW_DB_PATH` | SQLite database path | `~/.agentwrangler/db.sqlite` |
-| `AW_SCAN_ROOT` | Transcript corpus to scan | `~/.claude/projects` |
-| `AW_UI_ROOT` | Directory the built UI is served from | `<repo>/dist/ui` |
-| `AW_GITHUB_TOKEN` | Read-only GitHub PAT for outcomes sync | *(unset)* |
-| `AW_NO_OPEN` | Set to `1` to not auto-open the browser | *(unset)* |
+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.
 
-## What it measures
+[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).
 
-AgentWrangler ingests your transcripts and surfaces cost trends, cache-efficiency, session hygiene
-findings (e.g. long sessions never `/clear`ed, limit-burn risk), and — with a GitHub token — outcome
-linkage between sessions and the work they shipped. Numbers are cap-weighted and honesty-tiered: the
-UI is explicit about what is measured versus estimated, and never invents a proxy it can't ground.
-Definitions live in [`docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md`](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md).
+## Dashboard preview
 
-## Limitations
+![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)
 
-- **Platform support.** Tested on Windows; macOS/Linux are believed working — reports welcome.
-- **Transcript-format coupling.** AgentWrangler reads Claude Code's JSONL transcript format; a change
-  to that format upstream can require an ingestion update.
-- **Outcomes credential sources.** The cross-platform path is `AW_GITHUB_TOKEN`; the OS credential
-  store integration currently covers Windows Credential Manager only (macOS/Linux keychain is a
-  follow-on).
-- **Single local user.** It observes one machine's Claude Code history; there is no multi-user or
-  team-aggregation mode by design.
+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.
 
-## License
+## Pick a question
 
-Licensed under the [Apache License 2.0](LICENSE). Copyright 2026 AgentWrangler contributors.
+| I want to... | Start here |
+|---|---|
+| 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) |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) to build and test, [SECURITY.md](SECURITY.md) to report a
-vulnerability, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+## Installable guardrails — local checks inside Claude Code, before the waste
 
-## Documentation index
+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.
 
-| Path | Purpose |
-|---|---|
-| `docs/adr/ADR-100-stack.md` | Accepted MVP stack: Node 22 LTS + TypeScript + better-sqlite3, localhost UI (no Tauri/Electron for MVP) |
-| `docs/adr/ADR-100-shell-research-2026-08-21.md` | External research backing the localhost-UI decision |
-| `docs/planning/AgentWrangler_PRD_v0_7_0.md` | Product requirements v0.7.0 |
-| `docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md` | Architecture v4.5.0 |
-| `docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md` | SQLite schema + metric definitions v2 |
-| `docs/planning/AgentWrangler_Ingestion_and_Findings_Spec_v1.md` | Transcript ingestion + findings extractor spec |
-| `docs/planning/AgentWrangler_Recommendations_Engine_Spec_v1.md` | Recommendations engine spec |
-| `docs/planning/AgentWrangler_Spike_Plan_v2.md` | Spike exit criteria (authoritative) |
-| `docs/planning/AgentWrangler_PreImplementation_Plan_v1.md` | Session map + session prompts |
+| 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/index.js

@@ -35,11 +35,11 @@ import { linkSessions } from "../outcomes/linker.js";
 import { syncAllWorkspaces } from "../outcomes/sync.js";
 import { generateWeeklyReport } from "../query/api/reports.js";
 import { setQueryDb } from "../query/db-context.js";
-import { setHealthInstance, setRuntimeResetHook } from "../query/settings-store.js";
+import { getSettingsData, setHealthInstance, setRuntimeResetHook, } from "../query/settings-store.js";
 import { loadConfig } from "./config.js";
 import { createServer } from "./http.js";
 import { createOutcomesPassRunner } from "./outcomes-pass.js";
-import { setReady } from "./readiness.js";
+import { setReady, setScanRoots, setScanState } from "./readiness.js";
 const VERSION = "0.1.0";
 /** Parse a named CLI argument: --name value or --name=value. */
 function getArg(name) {
@@ -110,6 +110,8 @@ if (isSmoke) {
         "apply_jobs",
         "analysis_runs",
         "ingest_quarantine",
+        "ingest_metric_events",
+        "ingest_metric_baselines",
         "ingest_offsets",
         "schema_migrations",
         "user_config",
@@ -208,7 +210,9 @@ function kickBootScan() {
 }
 async function runBootScan() {
     try {
-        const ingestor = new Ingestor(db, config.scanRoots, {
+        const scanRoots = getSettingsData(db).scan_roots;
+        setScanRoots(scanRoots);
+        const ingestor = new Ingestor(db, scanRoots, {
             onNewMappings: (count) => {
                 console.log(`Discovery mapped ${count} new repo(s) — scheduling outcomes pass`);
                 runOutcomesPass().catch((e) => {
@@ -218,10 +222,12 @@ async function runBootScan() {
         });
         setHealthInstance(ingestor.health);
         handle = await ingestor.startTailBatched();
+        setScanState("complete");
         setRuntimeResetHook(() => ingestor.clearRuntimeState());
         console.log(`Ingestion: initial scan complete — health ${JSON.stringify(ingestor.healthSnapshot())}`);
     }
     catch (e) {
+        setScanState("failed");
         console.error(`Ingestion failed to start — serving dashboard in degraded mode: ${e instanceof Error ? e.message : String(e)}`);
     }
     // After the initial back-scan, workspaces are discovered — re-probe so per-workspace

package/dist/daemon/readiness.js

@@ -4,7 +4,32 @@
  * Set to true by index.ts after the initial back-scan completes.
  * Read by http.ts to decide whether to serve the loading page or the real SPA.
  */
-const state = { ready: false };
+import * as fs from "node:fs";
+const state = { ready: false, scan: "scanning", scanRoots: [] };
+/** Snapshot the roots actually used by the running ingestor, not pending settings. */
+export function setScanRoots(roots) {
+    state.scanRoots = [...roots];
+}
+export function setScanState(scan) {
+    state.scan = scan;
+}
+/** Aggregate-only diagnostics; never exposes a local path or filesystem error. */
+export function getScanStatus() {
+    let invalid = 0;
+    for (const root of state.scanRoots) {
+        try {
+            if (!fs.statSync(root).isDirectory()) {
+                invalid += 1;
+                continue;
+            }
+            fs.accessSync(root, fs.constants.R_OK);
+        }
+        catch {
+            invalid += 1;
+        }
+    }
+    return { scan_state: state.scan, invalid_scan_root_count: invalid };
+}
 /** Returns true after the initial back-scan + detector pass have finished. */
 export function isReady() {
     return state.ready;

package/dist/daemon/router.js

@@ -26,7 +26,7 @@ import { getSessionSpendPercentile, getWeeklySelfPercentile, } from "../query/ap
 import { getFlavorDecomposition } from "../query/api/spend-flavor.js";
 import { getCacheWriteTrend, getTrends } from "../query/api/trends.js";
 import { getSettingsData } from "../query/settings-store.js";
-import { isReady } from "./readiness.js";
+import { getScanStatus, isReady } from "./readiness.js";
 function sendJson(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
@@ -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 }));
@@ -741,6 +741,8 @@ export function handleApiRequest(_db, req, res, method, url) {
                 sessions,
                 files_seen: parser_health.files_seen,
                 files_parsed: parser_health.files_parsed,
+                lines_quarantined: parser_health.lines_quarantined,
+                ...getScanStatus(),
             });
             return;
         }

package/dist/db/migrations/016_ingest_offset_file_version.sql

@@ -0,0 +1,8 @@
+-- Nullable metadata lets existing offsets establish a baseline on their next read.
+-- No transcript content is stored here. Identity detects path replacement; timestamps
+-- detect equal-size in-place rewrites beyond the existing 256-byte head fingerprint.
+ALTER TABLE ingest_offsets ADD COLUMN file_size INTEGER;
+ALTER TABLE ingest_offsets ADD COLUMN file_dev TEXT;
+ALTER TABLE ingest_offsets ADD COLUMN file_ino TEXT;
+ALTER TABLE ingest_offsets ADD COLUMN file_mtime_ms REAL;
+ALTER TABLE ingest_offsets ADD COLUMN file_ctime_ms REAL;

package/dist/db/migrations/017_ingest_metric_events.sql

@@ -0,0 +1,22 @@
+-- Persist structural metric events so transcript replay cannot inflate session counters.
+-- event_id is a SHA-256 digest computed in-process; transcript content is never stored.
+CREATE TABLE ingest_metric_events (
+  event_id          TEXT PRIMARY KEY,
+  session_id        TEXT NOT NULL,
+  user_turn_ts      TEXT,
+  is_user_turn      INTEGER NOT NULL CHECK (is_user_turn IN (0, 1)),
+  is_compact_summary INTEGER NOT NULL CHECK (is_compact_summary IN (0, 1)),
+  is_api_error      INTEGER NOT NULL CHECK (is_api_error IN (0, 1)),
+  is_interrupt      INTEGER NOT NULL CHECK (is_interrupt IN (0, 1))
+);
+
+CREATE INDEX idx_ingest_metric_events_session_user_ts
+  ON ingest_metric_events(session_id, user_turn_ts)
+  WHERE is_user_turn = 1;
+
+-- Existing offsets predate the event ledger. Their consumed prefixes are seeded into
+-- the ledger without incrementing counters, then this durable boundary is advanced.
+CREATE TABLE ingest_metric_baselines (
+  file_path     TEXT PRIMARY KEY,
+  seeded_offset INTEGER NOT NULL CHECK (seeded_offset >= 0)
+);

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/detector/measurement.js

@@ -20,6 +20,7 @@
  *
  * Injected `now: Date` everywhere — never call new Date() in this module.
  */
+import { PREMIUM_MODEL_SQL } from "../ingest/pricing.js";
 import { GLOBAL_WORKSPACE_ID } from "./context-probe.js";
 import { isD1SourceBackedRecommendation, parseD1SourceIdentity } from "./d1-source-identity.js";
 /** Wait ≥1 day after adoption before entering MEASURING. */
@@ -82,14 +83,14 @@ function avgFloorContext(db, scopeWorkspaceId, fromIso, toIso) {
 /**
  * D4 signal: routing-adherence score = ROUND(100 × (1 − premium_share)) over
  * non-sidechain reconciled turns in [fromIso, toIso), where premium = model
- * contains 'opus'. The data-model's "mechanical turn" classifier is not yet
+ * matches PREMIUM_MODEL_SQL (Opus/Fable/Mythos). The data-model's "mechanical turn" classifier is not yet
  * shipped, so all reconciled turns are the mechanical set (conservative proxy —
  * documented in the W4 build digest).
  */
 function routingAdherenceScore(db, scopeWorkspaceId, fromIso, toIso) {
     const scoped = scopeWorkspaceId !== null;
     const sql = `SELECT COUNT(*) AS n,
-                      AVG(CASE WHEN model LIKE '%opus%' THEN 1.0 ELSE 0.0 END) AS premium_share
+                      AVG(CASE WHEN ${PREMIUM_MODEL_SQL} THEN 1.0 ELSE 0.0 END) AS premium_share
                  FROM turns
                 WHERE is_sidechain = 0 AND provisional = 0 AND ts >= ? AND ts < ? ${scoped ? "AND workspace_id = ?" : ""}`;
     const params = scoped ? [fromIso, toIso, scopeWorkspaceId] : [fromIso, toIso];