agentwrangler 0.1.0

package/dist/detector/detectors/d8_cache_write_churn.js

@@ -0,0 +1,201 @@
+/**
+ * src/detector/detectors/d8_cache_write_churn.ts — D8 CACHE_WRITE_CHURN (flagship).
+ *
+ * Fires PER-SESSION when a session repeatedly pays for a full cache re-write on a
+ * resume turn — a cache-creation spike after an idle gap that outlived the cache
+ * TTL, with little cache_read on that turn (a full-price re-write of the whole
+ * window rather than a warm read). These are the dominant reducible cap driver
+ * (research 2026-08-25); the meter is cap-weighted, never a raw-token headline.
+ *
+ * A "churn event" is a resume turn where ALL hold (UNVALIDATED defaults, labeled):
+ *   - creation = cache_write_5m + cache_write_1h + cache_write_other ≥ 50k
+ *   - idle_gap_min from the previous turn in the session > effective TTL
+ *       (> 5 when the 5m tier dominates, > 60 when the 1h tier dominates)
+ *   - cache_read < 0.2 × creation on that turn (a re-write, not a warm read)
+ *
+ * Fires the session rec when churn events ≥ 3/wk OR their creation tokens are
+ * ≥ 15% of the session's cap-weighted total (Data Model §2A).
+ *
+ * TTL-regime facet: when ≥ 80% of churn creation is 5m-tier, annotate regime=5m
+ * and extend the lever with the 1h-cache suggestion (no separate rec/id).
+ *
+ * scopeKey: "D8|<session_id>".
+ */
+import { LIST_PRICES, modelTier } from "../../ingest/pricing.js";
+import { capWeightedTokens } from "../../query/cap-weighted.js";
+import { D8_AVOIDANCE_FRACTION, D8_CREATION_SHARE, D8_CREATION_SPIKE_TOKENS, D8_LOW_READ_RATIO, D8_MIN_EVENTS, D8_REGIME_5M_SHARE, D8_TTL_1H_GAP_MIN, D8_TTL_5M_GAP_MIN, d8Savings, } from "../savings.js";
+/** Resolve [cw5m, cw1h] write prices ($/MTok) for a turn, snapshot first, list-price fallback. */
+function writePrices(unitPricesJson, model) {
+    if (unitPricesJson) {
+        try {
+            const arr = JSON.parse(unitPricesJson);
+            if (typeof arr[3] === "number" && typeof arr[4] === "number")
+                return [arr[3], arr[4]];
+        }
+        catch {
+            // fall through to list price
+        }
+    }
+    const tier = modelTier(model);
+    const lp = tier ? LIST_PRICES[tier] : undefined;
+    return lp ? [lp[3], lp[4]] : [0, 0];
+}
+export const d8Detector = {
+    id: "D8",
+    name: "CACHE_WRITE_CHURN",
+    evaluate(db, ctx) {
+        // Per-session cap-weighted totals (denominator for the creation-share gate).
+        const capRows = capWeightedTokens(db, {
+            fromIso: ctx.fromIso,
+            toIso: ctx.toIso,
+            groupBy: "session_id",
+        });
+        const capBySession = new Map(capRows.map((r) => [r.group ?? "", r]));
+        // All reconciled turns in the window, ordered by session then time (for gaps).
+        const turns = db
+            .prepare(`SELECT t.session_id, t.workspace_id, t.ts, t.model,
+                t.cache_read_tokens, t.cache_write_5m, t.cache_write_1h, t.cache_write_other,
+                ps.unit_prices_json AS unit_prices_json
+           FROM turns t
+           LEFT JOIN pricing_snapshots ps ON ps.snapshot_id = t.pricing_snapshot_id
+          WHERE t.ts >= ? AND t.ts < ? AND t.provisional = 0
+          ORDER BY t.session_id ASC, t.ts ASC`)
+            .all(ctx.fromIso, ctx.toIso);
+        // Group churn events by session (single pass; gap = delta from prev turn in session).
+        const eventsBySession = new Map();
+        let prevSession = null;
+        let prevTsMs = 0;
+        let prevModel = null;
+        for (const t of turns) {
+            const tsMs = new Date(t.ts).getTime();
+            const hasPrev = prevSession === t.session_id;
+            const creation = t.cache_write_5m + t.cache_write_1h + t.cache_write_other;
+            if (hasPrev && creation >= D8_CREATION_SPIKE_TOKENS) {
+                const idleGapMin = (tsMs - prevTsMs) / 60_000;
+                const fiveMinDominant = t.cache_write_5m > t.cache_write_1h;
+                const ttlGap = fiveMinDominant ? D8_TTL_5M_GAP_MIN : D8_TTL_1H_GAP_MIN;
+                const lowRead = t.cache_read_tokens < D8_LOW_READ_RATIO * creation;
+                if (idleGapMin > ttlGap && lowRead) {
+                    const [p5m, p1h] = writePrices(t.unit_prices_json, t.model);
+                    const writeU = t.cache_write_5m * p5m + t.cache_write_1h * p1h + t.cache_write_other * p5m;
+                    const entry = eventsBySession.get(t.session_id) ?? {
+                        workspace_id: t.workspace_id,
+                        events: [],
+                    };
+                    entry.events.push({
+                        ts: t.ts,
+                        idle_gap_min: Number(idleGapMin.toFixed(2)),
+                        cache_write_5m: t.cache_write_5m,
+                        cache_write_1h: t.cache_write_1h,
+                        cache_write_other: t.cache_write_other,
+                        cache_read_tokens: t.cache_read_tokens,
+                        creation,
+                        write_u: writeU,
+                        cause_facets: {
+                            idle_gap: true,
+                            model_switch: modelTier(prevModel) !== modelTier(t.model),
+                            session_reopen: "UNOBSERVABLE",
+                            prefix_config_change: "UNOBSERVABLE",
+                            dynamic_content: "UNOBSERVABLE",
+                        },
+                    });
+                    eventsBySession.set(t.session_id, entry);
+                }
+            }
+            prevSession = t.session_id;
+            prevTsMs = tsMs;
+            prevModel = t.model;
+        }
+        const fired = [];
+        for (const [sessionId, { workspace_id, events }] of eventsBySession) {
+            const totalCreation = events.reduce((s, e) => s + e.creation, 0);
+            const cap = capBySession.get(sessionId);
+            const sessionCapTotal = cap?.cap_weighted_tokens ?? 0;
+            const creationShare = sessionCapTotal > 0 ? totalCreation / sessionCapTotal : 0;
+            const meetsCount = events.length >= D8_MIN_EVENTS;
+            const meetsShare = creationShare >= D8_CREATION_SHARE;
+            if (!meetsCount && !meetsShare)
+                continue;
+            // Blended write price ($/MTok) weighted by creation across the churn events.
+            const totalWriteU = events.reduce((s, e) => s + e.write_u, 0);
+            const blendedWritePrice = totalCreation > 0 ? totalWriteU / totalCreation : 0;
+            const { savingsU, formula } = d8Savings(totalCreation, blendedWritePrice, D8_AVOIDANCE_FRACTION);
+            if (savingsU <= 0)
+                continue;
+            // 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 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;
+            fired.push({
+                scopeKey: `D8|${sessionId}`,
+                category: "CACHE",
+                scope_workspace_id: workspace_id,
+                lever,
+                target_metric: "cache_read_to_creation_ratio",
+                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`,
+                    session_id: sessionId,
+                    workspace_id,
+                    churn_event_count: events.length,
+                    total_churn_creation_tokens: totalCreation,
+                    session_cap_weighted_tokens: sessionCapTotal,
+                    creation_share: Number(creationShare.toFixed(4)),
+                    modeled_savings_basis: "LIST_EQUIV",
+                    billed_cost_claim: "UNAVAILABLE",
+                    cache_read_to_creation_ratio: cap?.cache_read_to_creation_ratio ?? null,
+                    regime: regime5m ? "5m" : "mixed",
+                    cause_facets: {
+                        idle_gap: true,
+                        model_switch: events.some((e) => e.cause_facets.model_switch),
+                        session_reopen: "UNOBSERVABLE",
+                        prefix_config_change: "UNOBSERVABLE",
+                        dynamic_content: "UNOBSERVABLE",
+                    },
+                    creation_spike_threshold: D8_CREATION_SPIKE_TOKENS,
+                    ttl_5m_gap_min_threshold: D8_TTL_5M_GAP_MIN,
+                    ttl_1h_gap_min_threshold: D8_TTL_1H_GAP_MIN,
+                    low_read_ratio_threshold: D8_LOW_READ_RATIO,
+                    min_events_threshold: D8_MIN_EVENTS,
+                    creation_share_threshold: D8_CREATION_SHARE,
+                    avoidance_fraction: D8_AVOIDANCE_FRACTION,
+                    thresholds_unvalidated: true,
+                    events: events.map((e) => ({
+                        ts: e.ts,
+                        idle_gap_min: e.idle_gap_min,
+                        cache_write_5m: e.cache_write_5m,
+                        cache_write_1h: e.cache_write_1h,
+                        cache_write_other: e.cache_write_other,
+                        cache_read_tokens: e.cache_read_tokens,
+                        creation_tokens: e.creation,
+                        cause_facets: e.cause_facets,
+                    })),
+                    steps: [
+                        "Open the session and find the resume turns with a large cache-creation spike after an idle gap",
+                        "Before stepping away, /clear or resume from a summary so the next turn reads a warm cache instead of re-writing it",
+                        "Batch CLAUDE.md / prefix edits to a session boundary so they don't invalidate the cache mid-session",
+                        regime5m
+                            ? "This session is 5m-tier dominant — enable the 1h cache regime where long pauses are unavoidable"
+                            : "Where long pauses are unavoidable, prefer the 1h cache regime",
+                    ],
+                },
+            });
+        }
+        if (fired.length === 0) {
+            return {
+                fired: [],
+                status: "INACTIVE",
+                note: "no session met the cache-write-churn threshold",
+            };
+        }
+        return {
+            fired,
+            status: "ACTIVE",
+            note: `${fired.length} session(s) with cache-write churn`,
+        };
+    },
+};

package/dist/detector/detectors/d9_idle_background_session.js

@@ -0,0 +1,101 @@
+/**
+ * src/detector/detectors/d9_idle_background_session.ts — D9 IDLE_BACKGROUND_SESSION.
+ *
+ * Fires PER-WORKSPACE when background / subagent fan-out (is_sidechain turns)
+ * dominates the cap-weighted volume — work that may not convert to forward
+ * progress. Built on the buildable is_sidechain share proxy; user_turn_count is
+ * now ingested per migration 009, so the zero-user-turn facet is available.
+ * Savings are marked DIRECTIONAL — fan-out is a real quality/throughput
+ * tradeoff, not pure waste (research B), and parent-child linkage remains
+ * heuristic (issue #32175). No crisp $ headline is emitted.
+ *
+ * Trigger (UNVALIDATED defaults, labeled): a workspace where is_sidechain=1 turns
+ * contribute ≥ 25% of cap-weighted tokens AND absolute sidechain cap-weighted
+ * tokens ≥ 100k in the trailing week.
+ *
+ * scopeKey: "D9|<workspace_id>".
+ */
+import { capWeightExprSql, capWeightedTokens, resolveCapReadCoeff, } from "../../query/cap-weighted.js";
+import { D9_SIDECHAIN_ABS_CAP_TOKENS, D9_SIDECHAIN_SHARE, D9_UNPRODUCTIVE_FRACTION, d9Formula, } from "../savings.js";
+export const d9Detector = {
+    id: "D9",
+    name: "IDLE_BACKGROUND_SESSION",
+    evaluate(db, ctx) {
+        const coeff = resolveCapReadCoeff(db);
+        // Cap-weighted total per workspace (denominator for the share gate).
+        const totals = capWeightedTokens(db, {
+            fromIso: ctx.fromIso,
+            toIso: ctx.toIso,
+            groupBy: "workspace_id",
+            coeff,
+        });
+        const totalByWorkspace = new Map(totals.map((r) => [r.group ?? "", r.cap_weighted_tokens]));
+        // Sidechain-only cap-weighted tokens per workspace (reuses the shared meter expression).
+        const sidechainRows = db
+            .prepare(`SELECT t.workspace_id                    AS workspace_id,
+                SUM(${capWeightExprSql("t", coeff)}) AS sidechain_cap_raw,
+                SUM(CASE WHEN s.user_turn_count = 0
+                         THEN ${capWeightExprSql("t", coeff)} ELSE 0 END) AS zero_utc_cap_raw,
+                COUNT(DISTINCT CASE WHEN s.user_turn_count = 0 THEN t.session_id END) AS zero_utc_sessions,
+                COUNT(*)                           AS sidechain_turns
+           FROM turns t
+           JOIN sessions s ON t.session_id = s.session_id
+          WHERE t.ts >= ? AND t.ts < ? AND t.provisional = 0 AND t.is_sidechain = 1
+          GROUP BY t.workspace_id`)
+            .all(ctx.fromIso, ctx.toIso);
+        const fired = [];
+        for (const row of sidechainRows) {
+            const sidechainCap = Math.round(row.sidechain_cap_raw ?? 0);
+            const totalCap = totalByWorkspace.get(row.workspace_id) ?? 0;
+            const share = totalCap > 0 ? sidechainCap / totalCap : 0;
+            const zeroUtcCap = Math.round(row.zero_utc_cap_raw ?? 0);
+            const zeroUtcShare = sidechainCap > 0 ? zeroUtcCap / sidechainCap : 0;
+            if (share < D9_SIDECHAIN_SHARE || sidechainCap < D9_SIDECHAIN_ABS_CAP_TOKENS)
+                continue;
+            fired.push({
+                scopeKey: `D9|${row.workspace_id}`,
+                category: "SESSION_HYGIENE",
+                scope_workspace_id: row.workspace_id,
+                lever: "Tighten subagent briefs and cap fan-out in plan mode; kill idle background sessions and /clear idle terminals. Directional — much fan-out is justified; review before cutting.",
+                target_metric: "sidechain_cap_weighted_share",
+                // Directional: no crisp $ headline (research B). Estimate lives in the formula inputs.
+                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`,
+                    workspace_id: row.workspace_id,
+                    sidechain_cap_weighted_tokens: sidechainCap,
+                    total_cap_weighted_tokens: totalCap,
+                    sidechain_share: Number(share.toFixed(4)),
+                    sidechain_turn_count: row.sidechain_turns,
+                    zero_user_turn_sidechain_cap: zeroUtcCap,
+                    zero_user_turn_sidechain_share: Number(zeroUtcShare.toFixed(4)),
+                    zero_user_turn_session_count: row.zero_utc_sessions,
+                    sidechain_share_threshold: D9_SIDECHAIN_SHARE,
+                    sidechain_abs_cap_tokens_threshold: D9_SIDECHAIN_ABS_CAP_TOKENS,
+                    unproductive_fraction: D9_UNPRODUCTIVE_FRACTION,
+                    thresholds_unvalidated: true,
+                    directional: true,
+                    linkage_note: "user_turn_count is now ingested per migration 009, so the zero-user-turn facet is available; parent-child subagent linkage remains heuristic (issue #32175)",
+                    steps: [
+                        "Review the highest-volume background/subagent sessions in this workspace",
+                        "Tighten subagent briefs so fan-out returns tight, scoped results",
+                        "Cap fan-out in plan mode; kill idle background sessions and /clear idle terminals",
+                    ],
+                },
+            });
+        }
+        if (fired.length === 0) {
+            return {
+                fired: [],
+                status: "INACTIVE",
+                note: "no workspace met the sidechain-share threshold",
+            };
+        }
+        return {
+            fired,
+            status: "ACTIVE",
+            note: `${fired.length} workspace(s) with background-heavy fan-out`,
+        };
+    },
+};

package/dist/detector/engine.js

@@ -0,0 +1,88 @@
+/**
+ * src/detector/engine.ts — deterministic orchestration + upsert.
+ *
+ * runDetectors(db, ctx) evaluates every registered detector under the injected
+ * clock and upserts fired triggers into `recommendations`. Determinism (§2.3):
+ * rec_id is a pure function of detector + scope + a stable evidence-window key
+ * (never a random uuid); created_at is the injected `now`; the ON CONFLICT path
+ * refreshes only derived fields and preserves lifecycle columns (state/adopted_at/
+ * dismissed_until), so a DISMISSED rec in cool-down is never resurfaced.
+ */
+import * as crypto from "node:crypto";
+import { DETECTORS, UNEVALUATED_DETECTORS } from "./registry.js";
+const WINDOW_DAYS = 7;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Build the trailing-7d context anchored at the injected `now`. */
+export function buildContext(now) {
+    const toIso = now.toISOString();
+    const fromIso = new Date(now.getTime() - WINDOW_DAYS * MS_PER_DAY).toISOString();
+    return { now, fromIso, toIso };
+}
+/** Deterministic rec_id: rec-<detector_id>-<scope>-<sha1(scopeKey)[:16]>. */
+function recId(detectorId, scopeWorkspaceId, scopeKey) {
+    const scope = scopeWorkspaceId ?? "global";
+    const hash = crypto.createHash("sha1").update(scopeKey).digest("hex").slice(0, 16);
+    return `rec-${detectorId}-${scope}-${hash}`;
+}
+const UPSERT_SQL = `
+  INSERT INTO recommendations
+    (rec_id, provenance, detector_id, analysis_run_id, category, scope_workspace_id,
+     lever, modeled_savings_u_per_wk, modeled_formula_json, evidence_json, target_metric,
+     state, created_at, adopted_at, dismissed_until)
+  VALUES (?, 'RULE', ?, NULL, ?, ?, ?, ?, ?, ?, ?, 'PROPOSED', ?, NULL, NULL)
+  ON CONFLICT(rec_id) DO UPDATE SET
+    modeled_savings_u_per_wk = excluded.modeled_savings_u_per_wk,
+    modeled_formula_json     = excluded.modeled_formula_json,
+    evidence_json            = excluded.evidence_json,
+    target_metric            = excluded.target_metric
+`;
+function upsertFired(db, detectorId, fired, nowIso) {
+    db.prepare(UPSERT_SQL).run(recId(detectorId, fired.scope_workspace_id, fired.scopeKey), detectorId, fired.category, fired.scope_workspace_id, fired.lever, fired.modeled_savings_u_per_wk, JSON.stringify(fired.modeled_formula), JSON.stringify(fired.evidence), fired.target_metric, nowIso);
+}
+/**
+ * Evaluate all registered detectors and upsert fired rows. Returns the live
+ * status list (used for the detectors[] strip). Read-only w.r.t. ingest tables;
+ * writes only `recommendations`.
+ */
+export function runDetectors(db, ctx) {
+    const nowIso = ctx.now.toISOString();
+    const statuses = [];
+    const tx = db.transaction(() => {
+        for (const detector of DETECTORS) {
+            const outcome = detector.evaluate(db, ctx);
+            for (const fired of outcome.fired) {
+                upsertFired(db, detector.id, fired, nowIso);
+            }
+            statuses.push({
+                detector_id: detector.id,
+                name: detector.name,
+                status: outcome.status,
+                note: outcome.note,
+            });
+        }
+    });
+    tx();
+    for (const d of UNEVALUATED_DETECTORS) {
+        statuses.push({ detector_id: d.id, name: d.name, status: d.status, note: d.note });
+    }
+    return statuses;
+}
+/**
+ * Evaluate detector statuses WITHOUT writing (read path for the query layer's
+ * detectors[] strip). Mirrors runDetectors but performs no upsert.
+ */
+export function detectorStatuses(db, ctx) {
+    const statuses = DETECTORS.map((detector) => {
+        const outcome = detector.evaluate(db, ctx);
+        return {
+            detector_id: detector.id,
+            name: detector.name,
+            status: outcome.status,
+            note: outcome.note,
+        };
+    });
+    for (const d of UNEVALUATED_DETECTORS) {
+        statuses.push({ detector_id: d.id, name: d.name, status: d.status, note: d.note });
+    }
+    return statuses;
+}

package/dist/detector/index.js

@@ -0,0 +1,17 @@
+/**
+ * src/detector/index.ts — DetectorEngine public surface.
+ *
+ * runDetectors(db, { now }) is the post-ingest entrypoint (wired via the ingest
+ * post-ingest hook). It MUST receive the ingestor's injected clock so rec_id /
+ * created_at windows are deterministic (NFR-107 / Review F4) — never new Date().
+ */
+import { buildContext, detectorStatuses, runDetectors as runDetectorsCore } from "./engine.js";
+export { buildContext } from "./engine.js";
+/** Evaluate + upsert fired recommendations. Returns the live detector status list. */
+export function runDetectors(db, opts = {}) {
+    return runDetectorsCore(db, buildContext(opts.now ?? new Date()));
+}
+/** Live detector statuses without writing — for the query layer's detectors[] strip. */
+export function getDetectorStatuses(db, opts = {}) {
+    return detectorStatuses(db, buildContext(opts.now ?? new Date()));
+}