agentwrangler 0.1.0

package/dist/query/forecast.js

@@ -0,0 +1,191 @@
+/**
+ * src/query/forecast.ts — BurnForecaster (ADR-107 §D-5, 5-state + OFF).
+ *
+ * The authoritative model is ADR-107 §D-5 (the Data Model §2 forecast block is
+ * STALE). The state machine is pure arithmetic, so it lives in TypeScript rather
+ * than SQL — this keeps `now` injectable (SQL `julianday('now')` is not) and
+ * makes every state deterministically testable.
+ *
+ * Token metric (ADR-107 §D-2 as amended by the Data Model §2A cap meter): the
+ * windowed sum is CAP-WEIGHTED via the shared `capWeightExprSql` helper —
+ *   full(input + output + cache_write_5m + cache_write_1h + cache_write_other)
+ *   + COEFF × cache_read_tokens            (COEFF default 0.1, UNVERIFIED)
+ * so forecast burn matches what the T0 cap meter attributes. Cache-heavy windows
+ * therefore yield LOWER burn than the old full-weight sum. Forecast still does
+ * NOT filter provisional (burn = all compute engaged).
+ *
+ * Window: trailing 1 day (ADR-107 §D-3). elapsed_days = now - window_start where
+ * window_start = MAX(now - 1d, earliest turn ts in the trailing window). On
+ * install day (< 6h of data) that yields elapsed < 0.25 → COLD_START; once >1d of
+ * history exists it saturates at 1d. This anchor choice is documented here because
+ * the ADR SQL leaves how window_start yields COLD_START implicit (see M-02).
+ *
+ * Rate floor: MAX(0.25, elapsed_days) is used ONLY for the rate denominator, so a
+ * near-zero elapsed never explodes the rate; the raw elapsed drives the COLD_START
+ * test. Eval order (ADR-107 + WP2 spec): OFF → COLD_START → EXCEEDED → NO_BURN →
+ * WARNING/OK. COLD_START is evaluated BEFORE EXCEEDED.
+ */
+import { capWeightExprSql, resolveCapReadCoeff } from "./cap-weighted.js";
+/** ADR-107 §D-4 default warning threshold (days). */
+export const DEFAULT_WARN_THRESHOLD_DAYS = 2;
+/** ADR-107 §D-3 trailing window (days). */
+export const FORECAST_WINDOW_DAYS = 1;
+/** ADR-107 §D-5 / M-02 elapsed floor for the rate denominator (days). */
+export const ELAPSED_FLOOR_DAYS = 0.25;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Unix epoch (1970-01-01T00:00:00Z) as a Julian Day number. */
+const UNIX_EPOCH_JD = 2440587.5;
+/** Convert a Date to a Julian Day number (matching SQLite julianday()). */
+export function toJulianDay(d) {
+    return d.getTime() / MS_PER_DAY + UNIX_EPOCH_JD;
+}
+/**
+ * Pure state machine. Returns the BurnForecast DTO. Never throws.
+ * See file header for the eval order and rate-floor rationale.
+ */
+export function computeForecast(input) {
+    const { limitTokens, tokensUsed, elapsedDays, nowJd, warnThresholdDays } = input;
+    // OFF — no limit configured.
+    if (limitTokens === null) {
+        return {
+            state: "OFF",
+            limit_tokens: null,
+            tokens_used: tokensUsed,
+            tokens_per_day: null,
+            projected_exhaustion_jd: null,
+            warn_threshold_days: warnThresholdDays,
+        };
+    }
+    const ratePerDay = tokensUsed / Math.max(ELAPSED_FLOOR_DAYS, elapsedDays);
+    // COLD_START — evaluated BEFORE EXCEEDED (ADR-107 eval order).
+    if (elapsedDays < ELAPSED_FLOOR_DAYS) {
+        return {
+            state: "COLD_START",
+            limit_tokens: limitTokens,
+            tokens_used: tokensUsed,
+            tokens_per_day: null,
+            projected_exhaustion_jd: null,
+            warn_threshold_days: warnThresholdDays,
+        };
+    }
+    // EXCEEDED — over the limit; ETA is meaningless (would be a past date). C-02.
+    if (tokensUsed >= limitTokens) {
+        return {
+            state: "EXCEEDED",
+            limit_tokens: limitTokens,
+            tokens_used: tokensUsed,
+            tokens_per_day: ratePerDay,
+            projected_exhaustion_jd: null,
+            warn_threshold_days: warnThresholdDays,
+        };
+    }
+    // NO_BURN — no tokens in the window; rate is zero, ETA undefined.
+    if (ratePerDay === 0) {
+        return {
+            state: "NO_BURN",
+            limit_tokens: limitTokens,
+            tokens_used: tokensUsed,
+            tokens_per_day: null,
+            projected_exhaustion_jd: null,
+            warn_threshold_days: warnThresholdDays,
+        };
+    }
+    const etaDays = (limitTokens - tokensUsed) / ratePerDay;
+    const projected = nowJd + etaDays;
+    return {
+        state: etaDays <= warnThresholdDays ? "WARNING" : "OK",
+        limit_tokens: limitTokens,
+        tokens_used: tokensUsed,
+        tokens_per_day: ratePerDay,
+        projected_exhaustion_jd: projected,
+        warn_threshold_days: warnThresholdDays,
+    };
+}
+/** Read the `limit_tokens` user_config value; null when unset/blank. */
+export function readLimitTokens(db) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = 'limit_tokens'").get();
+    if (row === undefined || row.value === null || row.value === "")
+        return null;
+    const n = Number(row.value);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Read the `limit_provenance` user_config value; null when unset.
+ * Written by calibrateLimit ("calibrated YYYY-MM-DD @ X%; cap-weighted …")
+ * and applySettingsUpdate ("manual") — see src/query/settings-store.ts.
+ */
+export function readLimitProvenance(db) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = 'limit_provenance'").get();
+    return row?.value ?? null;
+}
+/**
+ * Read the `limit_resets_at` user_config value; null when unset. Written by
+ * calibrateLimit alongside limit_tokens. Lets the card place the elapsed-week
+ * budget tick when a live oauth reading (burn-status) is unavailable.
+ */
+export function readLimitResetsAt(db) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = 'limit_resets_at'").get();
+    return row?.value ?? null;
+}
+/**
+ * Compute the burn forecast from the DB: sums CAP-WEIGHTED tokens over the
+ * trailing window (cache reads × COEFF via `capWeightExprSql`, coeff resolved
+ * from user_config), derives elapsed from the earliest turn in that window,
+ * and runs the pure state machine. Provisional turns are deliberately included.
+ */
+export function forecastFromDb(db, opts = {}) {
+    const now = opts.now ?? new Date();
+    const windowDays = opts.windowDays ?? FORECAST_WINDOW_DAYS;
+    const warnThresholdDays = opts.warnThresholdDays ?? DEFAULT_WARN_THRESHOLD_DAYS;
+    const limitTokens = opts.limitTokens !== undefined ? opts.limitTokens : readLimitTokens(db);
+    const windowStartMs = now.getTime() - windowDays * MS_PER_DAY;
+    const windowStartIso = new Date(windowStartMs).toISOString();
+    const nowIso = now.toISOString();
+    const coeff = resolveCapReadCoeff(db);
+    const agg = db
+        .prepare(`SELECT COALESCE(SUM(${capWeightExprSql("turns", coeff)}), 0) AS tok,
+              MIN(ts) AS first_ts
+         FROM turns
+        WHERE ts >= ? AND ts < ?`)
+        .get(windowStartIso, nowIso);
+    // Anchor elapsed at the earliest turn in the window (bounded below by the
+    // window start) so install-day data (< 6h) surfaces as COLD_START.
+    const anchorMs = agg.first_ts !== null
+        ? Math.max(windowStartMs, new Date(agg.first_ts).getTime())
+        : windowStartMs;
+    const elapsedDays = (now.getTime() - anchorMs) / MS_PER_DAY;
+    // Legacy-scale detection (review P1): commit beea3d2 switched the burn meter
+    // from full-weight token sums to cap-weighted (~10× lower for cache-heavy
+    // users). A limit_tokens value calibrated under the OLD meter is still stored
+    // in user_config and is now compared against cap-weighted burn, so states can
+    // silently flip WARNING/EXCEEDED → OK. Calibration provenance written AFTER
+    // beea3d2 contains the marker "cap-weighted"; older provenance does not.
+    //
+    // Decision: ANY stored provenance lacking the marker — including "manual"
+    // (applySettingsUpdate) or a missing row — is treated as legacy-scale, because
+    // a manual limit that predates the meter change is INDISTINGUISHABLE from a
+    // fresh one. This is deliberately conservative: a false positive merely shows
+    // an extra honest "re-run Calibrate" nudge, while a false negative would let
+    // the forecast silently mis-state WARNING/EXCEEDED. The number itself is
+    // never rescaled (that would fabricate data).
+    const limitScaleLegacy = limitTokens !== null && !(readLimitProvenance(db) ?? "").includes("cap-weighted");
+    const limitScaleNote = limitScaleLegacy
+        ? "limit was calibrated under the previous full-weight meter; re-run Calibrate"
+        : null;
+    return {
+        ...computeForecast({
+            limitTokens,
+            tokensUsed: agg.tok,
+            elapsedDays,
+            nowJd: toJulianDay(now),
+            warnThresholdDays,
+        }),
+        cap_weighted: true,
+        cap_read_coeff: coeff,
+        token_metric: "cap-weighted tokens (input+output+cache-writes full weight; cache reads × COEFF — COEFF unverified)",
+        limit_scale_legacy: limitScaleLegacy,
+        limit_scale_note: limitScaleNote,
+        limit_confidence: (readLimitProvenance(db) ?? "").includes("LOW CONFIDENCE") ? "low" : null,
+        limit_resets_at: readLimitResetsAt(db),
+    };
+}

package/dist/query/settings-store.js

@@ -0,0 +1,441 @@
+/**
+ * src/query/settings-store.ts — Data access for getSettings/updateSettings (WP4).
+ *
+ * Provides:
+ *   - Health context: setHealthInstance / clearHealthInstance
+ *   - getSettingsData(db) — assembles the full Settings payload
+ *   - applySettingsUpdate(db, update) — validates, persists, returns updated Settings or Error
+ *   - validateScanRoots(roots) — path guard (used by updateSettings + UI)
+ *
+ * No SQL in the UI; all reads/writes go through this module.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadConfig } from "../daemon/config.js";
+import { newHealthCounters } from "../ingest/types.js";
+import { fetchOAuthUsage } from "../oauth/usage.js";
+import { capWeightExprSql, resolveCapReadCoeff } from "./cap-weighted.js";
+// ---------------------------------------------------------------------------
+// Health context — wired by the daemon; zero-filled when not injected
+// ---------------------------------------------------------------------------
+let _health = null;
+/** Inject the running Health instance (daemon boot / tests). */
+export function setHealthInstance(h) {
+    _health = h;
+}
+/** Clear the injected Health instance (tests, between cases). */
+export function clearHealthInstance() {
+    _health = null;
+}
+// Runtime-reset hook — wired by the daemon so resetDatabase can also clear the
+// running Ingestor's in-memory caches (offsets/correlation). Zero-op when unset.
+let _runtimeReset = null;
+/** Inject a callback that clears live ingestor runtime state on DB reset (daemon boot / tests). */
+export function setRuntimeResetHook(fn) {
+    _runtimeReset = fn;
+}
+/** Clear the injected runtime-reset hook (tests, between cases). */
+export function clearRuntimeResetHook() {
+    _runtimeReset = null;
+}
+function getHealthCounters() {
+    return _health?.snapshot() ?? newHealthCounters();
+}
+function toParserHealth(c) {
+    return {
+        files_seen: c.filesSeen,
+        files_parsed: c.filesParsed,
+        lines_quarantined: c.linesQuarantined,
+        synthetic_excluded: c.syntheticExcluded,
+        duplicate_drops: c.duplicateDrops,
+        parser_version_mix: c.parserVersionMix,
+    };
+}
+// ---------------------------------------------------------------------------
+// user_config key helpers
+// ---------------------------------------------------------------------------
+function configGet(db, key) {
+    const row = db.prepare("SELECT value FROM user_config WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+function configSet(db, key, value) {
+    db.prepare(`INSERT INTO user_config (key, value, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`).run(key, value, new Date().toISOString());
+}
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+/**
+ * Explain why a still-unmapped workspace has no GitHub canonical, from DB + a
+ * cheap fs check (no subprocess). The auto-mapper (ingestor discovery tick)
+ * writes repo_path from the transcript cwd and derives the canonical from the
+ * git remote; a row stays unmapped only when one of those inputs is absent.
+ */
+function deriveMappingReason(repoPath, discoveredCwd) {
+    const localPath = repoPath ?? discoveredCwd;
+    if (localPath === null)
+        return "No working directory recorded in transcripts yet.";
+    if (!fs.existsSync(localPath))
+        return "Working directory no longer exists locally.";
+    return "No GitHub remote detected for this checkout.";
+}
+function readWorkspaceMappings(db) {
+    const rows = db
+        .prepare("SELECT workspace_id, project_slug, repo_path, repo_owner, repo_name, discovered_cwd FROM workspaces")
+        .all();
+    return rows.map((r) => {
+        const isTransient = r.repo_owner === null && r.repo_name === null;
+        return {
+            workspace_id: r.workspace_id,
+            project_slug: r.project_slug,
+            repo_path: r.repo_path,
+            repo_canonical: r.repo_owner !== null && r.repo_name !== null ? `${r.repo_owner}/${r.repo_name}` : null,
+            is_transient: isTransient,
+            ...(isTransient
+                ? { mapping_reason: deriveMappingReason(r.repo_path, r.discovered_cwd) }
+                : {}),
+        };
+    });
+}
+function readQuarantineRows(db) {
+    return db
+        .prepare(`SELECT file_path, line_no, error_class, seen_at
+       FROM ingest_quarantine
+       ORDER BY seen_at DESC, q_id DESC
+       LIMIT 100`)
+        .all();
+}
+/**
+ * Assemble the full Settings payload from the DB and daemon config.
+ * Parser health counters come from the injected Health instance (zero-filled when absent).
+ */
+export function getSettingsData(db) {
+    const cfg = loadConfig();
+    // Overlay DB-persisted values over daemon defaults
+    const scanRootsRaw = configGet(db, "scan_roots");
+    let scanRoots;
+    if (scanRootsRaw !== null) {
+        try {
+            const parsed = JSON.parse(scanRootsRaw);
+            // Degrade a corrupt/wrong-typed value (e.g. hand-edited DB) to daemon
+            // defaults rather than throwing — a getSettings/reset return-read must
+            // never hard-fail — and never surface a non-array as scan_roots.
+            scanRoots = Array.isArray(parsed) ? parsed : cfg.scanRoots;
+        }
+        catch {
+            scanRoots = cfg.scanRoots;
+        }
+    }
+    else {
+        scanRoots = cfg.scanRoots;
+    }
+    const windowRaw = configGet(db, "activity_window_secs");
+    const activityWindowSecs = windowRaw !== null ? Number(windowRaw) : cfg.activityWindowSecs;
+    const limitRaw = configGet(db, "limit_tokens");
+    const limitTokens = limitRaw !== null ? Number(limitRaw) : null;
+    // Provenance (ADR-111): "calibrated {date} @ {util}%" or "manual".
+    // Only meaningful when limit_tokens is set; null when limit is unset.
+    const limitProvenanceRaw = configGet(db, "limit_provenance");
+    const limitProvenance = limitTokens !== null ? (limitProvenanceRaw ?? "manual") : null;
+    // When the weekly window resets (stored at calibration time; null if never calibrated).
+    const limitResetsAt = configGet(db, "limit_resets_at");
+    const lastResetAt = configGet(db, "last_reset_at");
+    // R12 — bytes→token calibration fields
+    const bptEnabled = configGet(db, "bytes_per_token_calibration_enabled") === "true";
+    const bptRaw = configGet(db, "bytes_per_token");
+    const bptMeasuredAt = configGet(db, "bytes_per_token_measured_at");
+    const bptProvenance = configGet(db, "bytes_per_token_provenance");
+    const bpt = bptRaw !== null && Number.isFinite(Number(bptRaw)) ? Number(bptRaw) : null;
+    return {
+        db_path: cfg.dbPath,
+        scan_roots: scanRoots,
+        port: cfg.port,
+        activity_window_secs: activityWindowSecs,
+        limit_tokens: limitTokens,
+        limit_provenance: limitProvenance,
+        limit_resets_at: limitResetsAt,
+        workspace_mappings: readWorkspaceMappings(db),
+        parser_health: toParserHealth(getHealthCounters()),
+        quarantine_rows: readQuarantineRows(db),
+        last_reset_at: lastResetAt,
+        bytes_per_token_calibration_enabled: bptEnabled,
+        bytes_per_token: bpt,
+        bytes_per_token_provenance: bptProvenance,
+        bytes_per_token_measured_at: bptMeasuredAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// Validate
+// ---------------------------------------------------------------------------
+/**
+ * Parse an "owner/repo" canonical into its parts, or null when malformed.
+ * Valid = exactly one "/" with a non-empty owner and non-empty repo.
+ */
+function parseRepoCanonical(canonical) {
+    const slash = canonical.indexOf("/");
+    if (slash <= 0)
+        return null; // no slash, or leading slash (empty owner)
+    const owner = canonical.slice(0, slash);
+    const name = canonical.slice(slash + 1);
+    if (name.length === 0 || name.includes("/"))
+        return null; // empty or extra slash
+    return { owner, name };
+}
+/**
+ * Check that every root is an absolute path that exists and is a directory.
+ * Returns an error string on the first failure, null on success.
+ */
+export function validateScanRoots(roots) {
+    for (const root of roots) {
+        if (!path.isAbsolute(root)) {
+            return `Scan root "${root}" is not an absolute path.`;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(root);
+        }
+        catch {
+            return `Scan root "${root}" does not exist.`;
+        }
+        if (!stat.isDirectory()) {
+            return `Scan root "${root}" is not a directory.`;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+/**
+ * Apply a partial settings update and persist to the DB.
+ *
+ * Returns the updated Settings on success, or throws an Error on validation failure.
+ * Persistence is in a single transaction — either all fields update or none do.
+ *
+ * @throws {Error} When scan_roots contains an invalid path.
+ */
+export function applySettingsUpdate(db, update) {
+    // Validate scan roots before writing anything
+    if (update.scan_roots !== undefined) {
+        const err = validateScanRoots(update.scan_roots);
+        if (err !== null) {
+            throw new Error(err);
+        }
+    }
+    // Validate any non-empty repo_canonical shape before writing anything
+    if (update.workspace_mappings !== undefined) {
+        for (const m of update.workspace_mappings) {
+            if (m.repo_canonical !== null &&
+                m.repo_canonical !== undefined &&
+                m.repo_canonical !== "" &&
+                parseRepoCanonical(m.repo_canonical) === null) {
+                throw new Error(`Canonical "${m.repo_canonical}" must be in "owner/repo" form.`);
+            }
+        }
+    }
+    db.transaction(() => {
+        if (update.limit_tokens !== undefined) {
+            configSet(db, "limit_tokens", update.limit_tokens !== null ? String(update.limit_tokens) : null);
+            // Track provenance: manual entry clears any prior calibration label (ADR-111).
+            if (update.limit_tokens !== null) {
+                configSet(db, "limit_provenance", "manual");
+            }
+            else {
+                configSet(db, "limit_provenance", null);
+                configSet(db, "limit_resets_at", null);
+            }
+        }
+        if (update.scan_roots !== undefined) {
+            configSet(db, "scan_roots", JSON.stringify(update.scan_roots));
+        }
+        if (update.activity_window_secs !== undefined) {
+            configSet(db, "activity_window_secs", String(update.activity_window_secs));
+        }
+        // R12 — opt-in calibration toggle
+        if (update.bytes_per_token_calibration_enabled !== undefined) {
+            configSet(db, "bytes_per_token_calibration_enabled", update.bytes_per_token_calibration_enabled ? "true" : null);
+        }
+        if (update.workspace_mappings !== undefined) {
+            const stmt = db.prepare(`UPDATE workspaces
+         SET repo_path = ?, repo_owner = ?, repo_name = ?
+         WHERE workspace_id = ?`);
+            for (const m of update.workspace_mappings) {
+                let owner = null;
+                let name = null;
+                if (m.repo_canonical !== null &&
+                    m.repo_canonical !== undefined &&
+                    m.repo_canonical !== "") {
+                    const parsed = parseRepoCanonical(m.repo_canonical);
+                    // Shape already validated above; parsed is non-null here.
+                    if (parsed !== null) {
+                        owner = parsed.owner;
+                        name = parsed.name;
+                    }
+                }
+                const info = stmt.run(m.repo_path !== undefined ? m.repo_path : null, owner, name, m.workspace_id);
+                if (info.changes === 0) {
+                    throw new Error(`Unknown workspace "${m.workspace_id}" — nothing was saved.`);
+                }
+            }
+        }
+    })();
+    return getSettingsData(db);
+}
+// ---------------------------------------------------------------------------
+// Calibration (ADR-111)
+// ---------------------------------------------------------------------------
+/** Seven-day nominal window duration (ms) for deriving window_start from resets_at. */
+const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Auto-calibrate `:limit_tokens` from the oauth/usage endpoint (ADR-111).
+ *
+ * Formula: limit_tokens ≈ tokens_in_window / seven_day.utilization
+ * where tokens_in_window is the CAP-WEIGHTED token metric (Data Model §2A cap
+ * meter, reusing `capWeightExprSql`) over the current weekly window — cache
+ * reads × COEFF (default 0.1, UNVERIFIED), everything else full weight. All
+ * turns including provisional are counted (burn = all compute engaged). The
+ * derived limit is therefore on the same cap-weighted scale as the forecast's
+ * tokens_used, keeping the two comparable.
+ *
+ * Guards (mandatory per ADR-111):
+ *  - utilization < 0.02 → refuse; < 0.10 proceeds with low confidence.
+ *  - any non-200 from oauth/usage → return ok:false, never throw or block.
+ *
+ * The `reader` parameter is injectable for tests; defaults to fetchOAuthUsage().
+ */
+export async function calibrateLimit(db, reader = fetchOAuthUsage) {
+    // 1. Fetch utilization
+    let usage;
+    try {
+        usage = await reader();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `oauth/usage reader failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!usage.ok) {
+        return { ok: false, reason: usage.reason };
+    }
+    const sevenDay = usage.data?.seven_day;
+    if (sevenDay === undefined || sevenDay === null) {
+        return { ok: false, reason: "oauth/usage did not return a seven_day period." };
+    }
+    const { utilization, resets_at: resetsAt } = sevenDay;
+    if (!Number.isFinite(utilization) || utilization < 0 || utilization > 1) {
+        return { ok: false, reason: "oauth/usage returned an invalid seven_day utilization." };
+    }
+    // 2. Guard: refuse only when utilization makes the denominator too noisy.
+    if (utilization < 0.02) {
+        const pct = (utilization * 100).toFixed(1);
+        return {
+            ok: false,
+            reason: `Utilization is only ${pct}% — use Claude Code for a while to build up a reliable reading, then re-calibrate.`,
+        };
+    }
+    const lowConfidence = utilization < 0.1;
+    // 3. Window: resets_at minus 7 days (nominal; actual reset cadence may vary).
+    if (typeof resetsAt !== "string" || resetsAt.length === 0) {
+        return { ok: false, reason: "oauth/usage returned an invalid resets_at timestamp." };
+    }
+    const resetsAtMs = new Date(resetsAt).getTime();
+    if (!Number.isFinite(resetsAtMs)) {
+        return { ok: false, reason: "oauth/usage returned an invalid resets_at timestamp." };
+    }
+    const windowStartIso = new Date(resetsAtMs - SEVEN_DAY_MS).toISOString();
+    // 4. Sum CAP-WEIGHTED tokens (Data Model §2A meter: cache reads × COEFF,
+    // unverified; input/output/cache-writes full weight) in the window.
+    // Half-open interval [window_start, resets_at): the upper bound excludes any
+    // turns that landed after the current window reset (e.g. if resets_at is
+    // slightly in the past due to clock skew or a just-rolled window).
+    const coeff = resolveCapReadCoeff(db);
+    const row = db
+        .prepare(`SELECT COALESCE(SUM(${capWeightExprSql("turns", coeff)}), 0) AS tok
+         FROM turns
+        WHERE ts >= ? AND ts < ?`)
+        .get(windowStartIso, resetsAt);
+    const tokensInWindow = row.tok;
+    if (!Number.isFinite(tokensInWindow) || tokensInWindow <= 0) {
+        return {
+            ok: false,
+            reason: "No local token usage exists in the calibration window; record local usage before calibrating.",
+        };
+    }
+    const limitTokens = Math.round(tokensInWindow / utilization);
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const provenance = `calibrated ${date} @ ${(utilization * 100).toFixed(1)}%; cap-weighted (cache reads ×${coeff} COEFF, unverified)`;
+    const calibratedProvenance = `${provenance}${lowConfidence ? " — LOW CONFIDENCE (<10% utilization; re-calibrate after ~10% for a stable number)" : ""}`;
+    // 5. Persist atomically.
+    db.transaction(() => {
+        configSet(db, "limit_tokens", String(limitTokens));
+        configSet(db, "limit_provenance", calibratedProvenance);
+        configSet(db, "limit_resets_at", resetsAt);
+    })();
+    return {
+        ok: true,
+        limit_tokens: limitTokens,
+        provenance: calibratedProvenance,
+        ...(lowConfidence ? { confidence: "low" } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Reset
+// ---------------------------------------------------------------------------
+/**
+ * Ingested data tables wiped by resetDatabase, in FK-safe order
+ * (dependents before parents). Kept as an exported literal so a drift-guard
+ * test can assert it stays in sync with the schema as migrations add tables.
+ */
+export const RESET_DATA_TABLES = [
+    "reports",
+    "apply_jobs",
+    "recommendation_effects",
+    "recommendations",
+    "analysis_runs",
+    "session_work_links",
+    "observed_outcomes",
+    "review_findings",
+    "work_item_branch_keys",
+    "work_items",
+    "tool_event_metadata",
+    "tool_events",
+    "turns",
+    "session_churn",
+    "sessions",
+    "context_inventory",
+    "context_inventory_history",
+    "workspaces",
+    "ingest_quarantine",
+    "ingest_offsets",
+];
+/**
+ * Tables intentionally NOT wiped by resetDatabase:
+ *   - user_config / schema_migrations: config + schema, preserved by contract.
+ *   - pricing_snapshots: seeded reference data (Ingestor re-seeds it once at boot
+ *     and caches snapshot_ids for the process lifetime). Wiping it while the
+ *     daemon runs would orphan those cached ids and make the next re-ingested
+ *     turn violate the turns.pricing_snapshot_id FK; it is not ingested session data.
+ */
+export const RESET_PRESERVED_TABLES = [
+    "user_config",
+    "schema_migrations",
+    "pricing_snapshots",
+];
+/**
+ * Full data-table wipe (preserves RESET_PRESERVED_TABLES).
+ * Executes in a single transaction; sets last_reset_at in user_config.
+ * Returns fresh settings after the reset.
+ */
+export function resetDatabase(db) {
+    db.transaction(() => {
+        for (const table of RESET_DATA_TABLES) {
+            db.prepare(`DELETE FROM ${table}`).run();
+        }
+        configSet(db, "last_reset_at", new Date().toISOString());
+    })();
+    // Coordinate with a live ingestor (if wired): clear its in-memory caches so a
+    // reset on a running daemon re-ingests faithfully rather than lossily.
+    _runtimeReset?.();
+    return getSettingsData(db);
+}