dsh-tacit 0.2.3 → 0.4.0

package/lib/service.js

@@ -15,9 +15,11 @@
 
 import {
   Config,
+  COACH_ERROR_CODES,
   COACH_MODELS,
   COACH_PROVIDER,
   analyzeArgSchema,
+  analyzeBatchArgSchema,
   appliedArgSchema,
   configArgSchema,
   feedbackArgSchema,
@@ -28,7 +30,13 @@ import {
   directivesArgSchema,
   statsArgSchema,
   bootstrapArgSchema,
+  usageArgSchema,
+  usageRunArgSchema,
 } from './schema.js'
+import { dayKey } from './store.js'
+import { createUsageTracker, totalTokens } from './usage.js'
+import { createPricingSource } from './pricing-source.js'
+import { withService } from './routes.js'
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message'
 import { textOfBlocks } from './fold.js'
 import {
@@ -72,12 +80,13 @@ import {
   DIRECTIVE_TOOL,
   DIRECTIVE_MAX_TOKENS,
   DIRECTIVE_TIMEOUT_MS,
-  MAX_DIRECTIVES,
   buildDirectiveUserText,
   buildSteeringSection,
   renderSteeringSection,
   workspaceLabel,
-  MAX_WORKSPACE_DIRECTIVES,
+  scopeOf,
+  capDirectives,
+  mergeDirectives,
   ENRICH_SYSTEM_PROMPT,
   ENRICH_TOOL,
   ENRICH_MAX_TOKENS,
@@ -88,10 +97,18 @@ import {
   buildEnrichUserText,
   normalizeEnrichNote,
   computeTrend,
+  markCorrections,
 } from './analyze.js'
 
 /** In-memory rewrite ledger bounds (never persisted). */
 const MAX_REWRITE_RECORDS = 50
+/**
+ * What one analysis costs per model when the ledger cannot say yet: the docs'
+ * $0.02–0.05 per 20 bootstrapped turns, scaled to a single analysis.
+ */
+const DOC_ANALYSIS_USD = { 'deepseek-v4-flash': 0.0025, 'deepseek-v4-pro': 0.0075 }
+/** Priced analysis attempts the ledger needs before an estimate follows it instead of the docs. */
+const MEASURED_MIN_SAMPLES = 3
 /** Pending outcome verifications kept per session (FIFO, oldest dropped). */
 const MAX_PENDING_VERIFICATIONS = 20
 
@@ -119,6 +136,9 @@ export function mergeConfig(base, patch) {
   merged.directiveWorseBy = Math.max(0, Math.min(1, Number.isFinite(Number(merged.directiveWorseBy)) ? Number(merged.directiveWorseBy) : 0.15))
   merged.bootstrapConcurrency = Math.max(1, Math.min(4, Math.round(Number(merged.bootstrapConcurrency) || 1)))
   merged.learnFromGood = merged.learnFromGood !== false
+  merged.costHistoryDays = Math.max(7, Math.min(365, Math.round(Number(merged.costHistoryDays) || 30)))
+  merged.costWarnDailyUsd = Math.max(0, Math.min(10000, Number.isFinite(Number(merged.costWarnDailyUsd ?? 0)) ? Number(merged.costWarnDailyUsd ?? 0) : 0))
+  merged.costWarnMonthlyUsd = Math.max(0, Math.min(10000, Number.isFinite(Number(merged.costWarnMonthlyUsd ?? 0)) ? Number(merged.costWarnMonthlyUsd ?? 0) : 0))
   return merged
 }
 
@@ -167,21 +187,6 @@ function listWorkspaces(service) {
   return [...seen.values()].sort((a, b) => a.label.localeCompare(b.label))
 }
 
-/** At most MAX_DIRECTIVES global directives and MAX_WORKSPACE_DIRECTIVES per workspace, order kept. */
-function capDirectives(list) {
-  const counts = new Map()
-  const out = []
-  for (const entry of list) {
-    const scope = typeof entry.workspace === 'string' && entry.workspace.length > 0 ? entry.workspace : ''
-    const limit = scope === '' ? MAX_DIRECTIVES : MAX_WORKSPACE_DIRECTIVES
-    const n = counts.get(scope) ?? 0
-    if (n >= limit) continue
-    counts.set(scope, n + 1)
-    out.push(entry)
-  }
-  return out
-}
-
 /** Short, secret-free context digest of a session's last two finished turns. */
 function recentContextOf(turns) {
   const finished = (Array.isArray(turns) ? turns : []).filter((turn) => turn?.finished === true).slice(-2)
@@ -229,23 +234,53 @@ function lastFinishedTurnOf(turns) {
   return finished.length > 0 ? finished[finished.length - 1] : null
 }
 
+/**
+ * One of {@link COACH_ERROR_CODES} for whatever a model call threw.
+ *
+ * A code is passed through only when it is already one of Tacit's own: the
+ * runtime turns an adapter failure into a `finish {kind:'error'|'aborted'}`
+ * chunk and `callCoachModel` rethrows it carrying the provider's own code
+ * (or a synthesized `ERROR`/`ABORTED`), and the client renders `err.<code>`
+ * verbatim — so passing those through paints a literal `err.ABORTED` banner.
+ * Anything else is folded, code and message together, through the ladder.
+ * The attempt record keeps the raw code; only the envelope is normalized.
+ */
 function coachErrorCode(error) {
   const message = error instanceof Error ? error.message : String(error)
-  if (error !== null && typeof error === 'object' && typeof error.code === 'string') return error.code
-  if (/abort|aborted|timeout/i.test(message)) return 'timeout'
-  if (/auth|401|403|api key|key not/i.test(message)) return 'no-api-key'
-  if (/rate|429/i.test(message)) return 'rate-limited'
+  const raw = error !== null && typeof error === 'object' && typeof error.code === 'string' ? error.code : ''
+  if (COACH_ERROR_CODES.includes(raw)) return raw
+  const text = raw + ' ' + message
+  if (/abort|timeout/i.test(text)) return 'timeout'
+  if (/auth|401|403|api[ _-]?key|key not/i.test(text)) return 'no-api-key'
+  // Ahead of the rate-limit rule: an exhausted balance says "quota" too, but
+  // it will not clear by waiting, so it must not read as "try again shortly".
+  if (/\binsufficient[ _-]?(quota|balance|credit)|\bexceeded your current quota/i.test(text)) return 'no-credit'
+  // Word-bounded: a bare /rate/ matches the "rate" inside "generate", and the
+  // ladder now sees the raw code and message of every provider failure. A
+  // trailing \b after "quota" would not do here — `_` is a word character, so
+  // it could never match `quota_exceeded`; the lookahead stops "quotation"
+  // instead, which is what the boundary was for.
+  if (/\brate[ _-]?limit|\bquota(?![a-z])|\b429\b|too[ _-]?many[ _-]?requests/i.test(text)) return 'rate-limited'
   return 'call-failed'
 }
 
-/** Local calendar day key for the daily auto budget. */
-function dayKey(now = Date.now()) {
-  const date = new Date(now)
-  const pad = (value) => String(value).padStart(2, '0')
-  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
-}
-
 export function createCoachService(ctx, store, effectiveConfig) {
+  /** Prices behind the ledger: the optional costMeter sibling when it appears, bundled list prices otherwise. */
+  const pricing = createPricingSource(ctx)
+  /** The run/attempt ledger. Synchronous by contract — never awaited in a model-call path. */
+  const usage = createUsageTracker({ store, config: effectiveConfig, pricing })
+  // Fire and forget, twice: once now, once if the sibling shows up later.
+  // No model call ever waits on it, and a failure only means bundled prices.
+  const refreshPrices = () => { pricing.refresh().catch(() => {}) }
+  refreshPrices()
+  withService(ctx, 'costMeter', refreshPrices)
+
+  /** One metered model call: the caller's options plus this run's usage sink. */
+  const metered = (runId, tag, options) => ({ ...options, onUsage: usage.attemptSink(runId, tag) })
+
+  /** End a run (idempotent) and hand back the summary its response envelope carries. */
+  const closeRun = (runId, results = {}, status) => usage.endRun(runId, { results, status }) ?? usage.runSummary(runId)
+
   const inFlight = new Map()
   /** Turns already handed to automatic analysis (sessionId:turn). */
   const autoSeen = new Set()
@@ -328,11 +363,15 @@ export function createCoachService(ctx, store, effectiveConfig) {
    */
   const maybeDistill = async (profile, provider, sessionId) => {
     if (profile.pendingDistill < 3 || distillInFlight) return profile
+    // Read the config BEFORE claiming the in-flight slot: a throw between the
+    // two would leave `distillInFlight` stuck true and kill every later
+    // distillation for the lifetime of the process.
+    const config = effectiveConfig()
+    const runId = usage.beginRun({ type: 'style-distillation', trigger: 'feedback', sessionId, model: config.model, provider })
     distillInFlight = true
     try {
-      const config = effectiveConfig()
       const reasons = lastDownReasons(profile, 3)
-      const text = await callCoachModel(ctx, {
+      const text = await callCoachModel(ctx, metered(runId, { op: 'style-distillation', sessionId }, {
         provider,
         model: config.model,
         system: DISTILL_SYSTEM_PROMPT,
@@ -341,7 +380,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
         timeoutMs: DISTILL_TIMEOUT_MS,
         tool: DISTILL_TOOL,
         sessionId,
-      })
+      }))
       const rules = normalizeDistillRules(text)
       if (rules.length === 0) return profile
       const fresh = safeProfile()
@@ -351,6 +390,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
     } catch {
       return profile
     } finally {
+      closeRun(runId)
       distillInFlight = false
     }
   }
@@ -387,26 +427,32 @@ export function createCoachService(ctx, store, effectiveConfig) {
     handleVerification(sessionId, turns)
   }
 
-  /** Finished turns already counted toward directive trials (sessionId:turn). */
+  /** Finished turns already counted toward directive trials, and turns already counted as corrected (sessionId:turn). */
   const seenFinished = new Set()
+  const seenCorrected = new Set()
 
   const pct = (rate) => String(Math.round(rate * 100)) + '%'
 
   /**
    * Directive trials ride the same free feed: every NEW finished turn counts
    * toward each candidate that was actually in that session's frozen steering
-   * text; after `directiveTrialTurns` such turns the candidate is activated,
-   * or retired when the messy rate rose past the baseline by more than
-   * `directiveWorseBy`. A session whose steering was never assembled here
-   * (started before the candidate existed, or before a restart) counts toward
-   * nobody — its turns say nothing about the candidate.
+   * text, and so does every correction of such a turn (the session's next
+   * prompt, known the moment it starts). After `directiveTrialTurns` turns the
+   * candidate is retired when its correction rate rose past the baseline by
+   * more than `directiveWorseBy` (or its messy rate by twice that), otherwise
+   * activated. A session whose steering was never assembled here (started
+   * before the candidate existed, or before a restart) counts toward nobody —
+   * its turns say nothing about the candidate.
    */
   const recordTrialTurns = (sessionId, turns) => {
-    const fresh = (Array.isArray(turns) ? turns : []).filter((turn) => turn !== null && typeof turn === 'object'
-      && turn.finished === true && typeof turn.turn === 'number' && typeof turn.endedAt === 'number' && turn.endedAt >= pluginStartedAt
-      && !seenFinished.has(sessionId + ':' + turn.turn))
-    if (fresh.length === 0) return
-    for (const turn of fresh) seenFinished.add(sessionId + ':' + turn.turn)
+    const key = (turn) => sessionId + ':' + turn.turn
+    const counted = markCorrections(turns).filter((turn) => typeof turn.turn === 'number' && turn.finished === true
+      && typeof turn.endedAt === 'number' && turn.endedAt >= pluginStartedAt)
+    const fresh = counted.filter((turn) => !seenFinished.has(key(turn)))
+    const corrected = counted.filter((turn) => turn.corrected && !seenCorrected.has(key(turn)))
+    for (const turn of fresh) seenFinished.add(key(turn))
+    for (const turn of corrected) seenCorrected.add(key(turn))
+    if (fresh.length === 0 && corrected.length === 0) return
     const steered = steeringIdsBySession.get(sessionId)
     if (steered === undefined || steered.length === 0) return
     const profile = safeProfile()
@@ -414,21 +460,33 @@ export function createCoachService(ctx, store, effectiveConfig) {
     if (candidates.length === 0) return
     const config = effectiveConfig()
     const messyCount = fresh.filter((turn) => isMessyTurn(turn, { minSteps: Number.POSITIVE_INFINITY })).length
+    let verdicts = 0
     for (const entry of candidates) {
-      entry.trial.turns += fresh.length
-      entry.trial.messy += messyCount
-      if (entry.trial.turns < config.directiveTrialTurns) continue
-      const rate = entry.trial.messy / entry.trial.turns
-      if (rate > entry.trial.baselineRate + config.directiveWorseBy) {
+      const trial = entry.trial
+      if (trial.baselineCorrectionRate < 0) trial.baselineCorrectionRate = baselinesFor(scopeOf(entry)).baselineCorrectionRate
+      trial.turns += fresh.length
+      trial.messy += messyCount
+      trial.corrected += corrected.length
+      if (trial.turns < config.directiveTrialTurns) continue
+      const correctionRate = trial.corrected / trial.turns
+      const messyRate = trial.messy / trial.turns
+      const worse = correctionRate > trial.baselineCorrectionRate + config.directiveWorseBy
+        ? 'corrections ' + pct(trial.baselineCorrectionRate) + ' → ' + pct(correctionRate)
+        : messyRate > trial.baselineMessyRate + 2 * config.directiveWorseBy
+          ? 'messy turns ' + pct(trial.baselineMessyRate) + ' → ' + pct(messyRate)
+          : null
+      verdicts += 1
+      if (worse !== null) {
         entry.status = 'retired'
         entry.enabled = false
-        entry.retiredReason = 'messy turns ' + pct(entry.trial.baselineRate) + ' → ' + pct(rate) + ' while active'
+        entry.retiredReason = worse + ' while active'
         console.info('[tacit] retired directive (' + entry.retiredReason + '): ' + entry.text)
       } else {
         entry.status = 'active'
-        console.info('[tacit] activated directive (messy turns ' + pct(entry.trial.baselineRate) + ' → ' + pct(rate) + '): ' + entry.text)
+        console.info('[tacit] activated directive (corrections ' + pct(trial.baselineCorrectionRate) + ' → ' + pct(correctionRate) + '): ' + entry.text)
       }
     }
+    if (verdicts > 0) startNextTrial(profile)
     capAndSaveProfile(profile)
   }
 
@@ -469,9 +527,13 @@ export function createCoachService(ctx, store, effectiveConfig) {
     return earlier.length > 0 ? earlier[earlier.length - 1] : null
   }
 
-  const runAnalysis = (sessionId, turn, { trigger = 'manual', followUp = '', digest = null, previousDigest = null } = {}) => {
+  const runAnalysis = (sessionId, turn, { trigger = 'manual', followUp = '', digest = null, previousDigest = null, runId = '' } = {}) => {
     const profile = safeProfile()
     const key = `${sessionId}:${turn}`
+    /** The run this analysis is billed to: the caller's batch run, or one of its own. Stays '' on a soft refusal. */
+    let usageRunId = ''
+    /** True when this analysis owns its run; a child of a batch reports `run: null` and lets the batch carry it. */
+    const ownRun = runId === ''
     const exclusive = runExclusive(key, async () => {
       const svc = serviceOf(ctx)
       const { session, turns } = turnsOf(svc, sessionId)
@@ -489,13 +551,19 @@ export function createCoachService(ctx, store, effectiveConfig) {
       const userText = buildAnalysisUserText(record, { followUp, previous })
       if (userText === null) return { ok: false, report: null, profile, code: 'not-retained', detail: '' }
       const config = effectiveConfig()
+      const provider = typeof record.provider === 'string' && record.provider.length > 0
+        ? record.provider
+        : COACH_PROVIDER
+      // Only now, with a paid call actually about to happen, does a run start:
+      // every refusal above this line costs nothing and is not worth a row.
+      usageRunId = ownRun
+        ? usage.beginRun({ type: 'analysis', trigger, sessionId, turn, workspace: workspaceLabel(cwd), model: config.model, provider })
+        : runId
+      let ok = false
       try {
-        const provider = typeof record.provider === 'string' && record.provider.length > 0
-          ? record.provider
-          : COACH_PROVIDER
         if (trigger === 'good') {
           // One attempt, no repair retry: a recovery lesson is a bonus, not a diagnosis.
-          const goodText = await callCoachModel(ctx, {
+          const goodText = await callCoachModel(ctx, metered(usageRunId, { op: 'analysis', sessionId, turn }, {
             provider,
             model: config.model,
             system: GOOD_SYSTEM_PROMPT,
@@ -504,7 +572,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
             timeoutMs: ANALYZE_TIMEOUT_MS,
             tool: GOOD_TOOL,
             sessionId,
-          })
+          }))
           const goodParsed = goodText.trim() === '' ? null : parseJsonObject(goodText)
           if (goodParsed === null) return { ok: false, report: null, profile, code: 'empty-response', detail: '' }
           const goodReport = {
@@ -525,9 +593,10 @@ export function createCoachService(ctx, store, effectiveConfig) {
             const task = maybeDistillDirectives(sessionId, provider).catch(() => null).finally(() => autoRunning.delete(task))
             autoRunning.add(task)
           }
+          ok = true
           return { ok: true, report: goodReport, profile: grown, code: '', detail: '' }
         }
-        let text = await callCoachModel(ctx, {
+        let text = await callCoachModel(ctx, metered(usageRunId, { op: 'analysis', sessionId, turn }, {
           provider,
           model: config.model,
           system: ANALYSIS_SYSTEM_PROMPT,
@@ -536,14 +605,14 @@ export function createCoachService(ctx, store, effectiveConfig) {
           timeoutMs: ANALYZE_TIMEOUT_MS,
           tool: ANALYSIS_TOOL,
           sessionId,
-        })
+        }))
         if (text.trim() === '') {
           return { ok: false, report: null, profile, code: 'empty-response', detail: '' }
         }
         let parsed = parseJsonObject(text)
         if (parsed === null) {
           // One-shot repair: the model answered in prose; re-ask for strict JSON.
-          const repaired = await callCoachModel(ctx, {
+          const repaired = await callCoachModel(ctx, metered(usageRunId, { op: 'analysis-repair', sessionId, turn }, {
             provider,
             model: config.model,
             system: ANALYSIS_REPAIR_SYSTEM_PROMPT,
@@ -552,7 +621,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
             timeoutMs: ANALYZE_TIMEOUT_MS,
             tool: ANALYSIS_TOOL,
             sessionId,
-          })
+          }))
           if (repaired.trim() !== '') {
             const reparsed = parseJsonObject(repaired)
             if (reparsed !== null) {
@@ -584,14 +653,21 @@ export function createCoachService(ctx, store, effectiveConfig) {
           const task = maybeDistillDirectives(sessionId, provider).catch(() => null).finally(() => autoRunning.delete(task))
           autoRunning.add(task)
         }
+        ok = true
         return { ok: true, report, profile: nextProfile, code: '', detail: '' }
       } catch (error) {
         const detail = error instanceof Error ? error.message.slice(0, 300) : String(error).slice(0, 300)
         return { ok: false, report: null, profile, code: coachErrorCode(error), detail }
+      } finally {
+        // A batch run is closed by its owner; an own run always ends here.
+        if (ownRun) closeRun(usageRunId, { ok: ok ? 1 : 0 })
       }
     })
-    if (exclusive === null) return Promise.resolve({ ok: false, report: null, profile, code: 'busy', detail: '' })
-    return exclusive
+    if (exclusive === null) return Promise.resolve({ ok: false, report: null, profile, code: 'busy', detail: '', run: null })
+    return exclusive.then((result) => ({
+      ...result,
+      run: ownRun && usageRunId !== '' ? usage.runSummary(usageRunId) : null,
+    }))
   }
 
   const steeringStatus = (cwd) => {
@@ -621,73 +697,41 @@ export function createCoachService(ctx, store, effectiveConfig) {
     return frozen.text
   }
 
-  /**
-   * Replace the distilled directives with the model's new complete set; user
-   * entries are untouched, and a re-emitted directive keeps the enabled flag
-   * the user gave its identical text. Capped at MAX_DIRECTIVES overall.
-   */
-  const scopeOf = (entry) => (typeof entry.workspace === 'string' && entry.workspace.length > 0 ? entry.workspace : '')
-  const directiveKey = (scope, text) => scope + '\n' + text.trim().toLowerCase()
-
-  /** Messy-turn baseline for a new candidate: the workspace's own turns when there are enough, else everything. */
-  const baselineRateFor = (cwd) => {
-    const scoped = cwd !== undefined ? allFinishedTurns({ cwd }) : []
+  /** Baselines for a new trial: the workspace's own turns when there are enough, else everything. */
+  const baselinesFor = (scope) => {
+    const scoped = scope !== '' ? allFinishedTurns({ cwd: scope }) : []
     const turns = scoped.length >= 20 ? scoped : allFinishedTurns()
-    return computeTrend(turns, { window: 20 }).recent.messyRate
+    const { messyRate, correctionRate } = computeTrend(turns, { window: 20 }).recent
+    return { baselineMessyRate: messyRate, baselineCorrectionRate: correctionRate }
   }
 
   /**
-   * Merge the model's new complete set of directives ({ text, workspace? }):
-   * user entries are untouched; the global distilled set and the distilled set
-   * of every workspace the model mentioned are replaced; distilled entries of
-   * other workspaces are kept (their evidence was not in this batch). A
-   * re-emitted directive keeps its identity, state and enabled flag.
+   * One trial per scope at a time: wherever no candidate is on trial, the
+   * oldest enabled queued directive of that scope starts its trial now, with
+   * baselines measured at this moment. Idempotent.
    */
-  const mergeDirectives = (profile, items) => {
-    const users = profile.directives.filter((entry) => entry.source === 'user')
-    const userKeys = new Set(users.map((entry) => directiveKey(scopeOf(entry), entry.text)))
-    const prior = profile.directives.filter((entry) => entry.source !== 'user')
-    const previous = new Map(prior.map((entry) => [directiveKey(scopeOf(entry), entry.text), entry]))
-    const mentioned = new Set([''])
-    for (const item of items) mentioned.add(scopeOf(item))
-    const untouched = prior.filter((entry) => !mentioned.has(scopeOf(entry)))
-    const distilled = []
-    const seen = new Set()
-    const baselines = new Map()
-    for (const item of items) {
-      const scope = scopeOf(item)
-      const key = directiveKey(scope, item.text)
-      if (seen.has(key) || userKeys.has(key)) continue
-      seen.add(key)
-      const kept = previous.get(key)
-      if (kept !== undefined) {
-        distilled.push({ ...kept, text: item.text })
-        continue
-      }
-      // A new distilled directive goes on trial against the current messy-turn rate.
-      if (!baselines.has(scope)) baselines.set(scope, baselineRateFor(scope === '' ? undefined : scope))
-      distilled.push({
-        id: nextDirectiveId(),
-        text: item.text,
-        enabled: true,
-        source: 'distilled',
-        createdAt: Date.now(),
-        status: 'candidate',
-        trial: { turns: 0, messy: 0, baselineRate: baselines.get(scope), startedAt: Date.now() },
-        ...(scope === '' ? {} : { workspace: scope }),
-      })
+  const startNextTrial = (profile) => {
+    const busy = new Set(profile.directives.filter((entry) => entry.status === 'candidate').map(scopeOf))
+    for (const entry of profile.directives) {
+      if (entry.status !== 'queued' || entry.enabled === false || busy.has(scopeOf(entry))) continue
+      busy.add(scopeOf(entry))
+      entry.status = 'candidate'
+      entry.trial = { turns: 0, messy: 0, corrected: 0, ...baselinesFor(scopeOf(entry)), startedAt: Date.now() }
+      console.info('[tacit] directive on trial: ' + entry.text)
     }
-    profile.directives = capDirectives([...users, ...distilled, ...untouched])
-    return profile
   }
 
   /** ONE small call every `directiveEvery` new analyses (or forced). Soft-fails; never throws. */
-  const maybeDistillDirectives = async (sessionId, provider, { force = false } = {}) => {
+  const maybeDistillDirectives = async (sessionId, provider, { force = false, runId = '' } = {}) => {
     if (directivesInFlight) return
     const config = effectiveConfig()
     let profile = safeProfile()
     if (!force && profile.analysesSinceDirectives < config.directiveEvery) return
     directivesInFlight = true
+    const ownRun = runId === ''
+    const usageRunId = ownRun
+      ? usage.beginRun({ type: 'directive-distillation', trigger: 'auto', sessionId, model: config.model, provider })
+      : runId
     try {
       const recent = store.listAllReports(20).map((entry) => store.report(entry.sessionId, entry.turn)).filter((report) => report !== null)
       // The model sees workspace names only; map them back to the directories they stand for.
@@ -697,7 +741,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
         const label = workspaceLabel(report.cwd)
         if (label.length > 0 && !workspaces.has(label)) workspaces.set(label, report.cwd)
       }
-      const text = await callCoachModel(ctx, {
+      const text = await callCoachModel(ctx, metered(usageRunId, { op: 'directive-distillation', sessionId }, {
         provider,
         model: config.model,
         system: DIRECTIVE_SYSTEM_PROMPT,
@@ -706,17 +750,20 @@ export function createCoachService(ctx, store, effectiveConfig) {
         timeoutMs: DIRECTIVE_TIMEOUT_MS,
         tool: DIRECTIVE_TOOL,
         sessionId,
-      })
+      }))
       const { kept, rejected } = classifyDirectives(text)
       for (const dropped of rejected) console.warn('[tacit] dropped directive (it asks the user instead of compensating):', dropped)
       if (kept.length === 0) {
         console.warn('[tacit] directive distillation returned nothing usable; will retry after the next analysis:', clipSafe(text, 300))
         return
       }
-      const items = kept.map((item) => (item.workspace !== undefined && workspaces.has(item.workspace)
-        ? { text: item.text, workspace: workspaces.get(item.workspace) }
-        : { text: item.text }))
-      profile = mergeDirectives(safeProfile(), items)
+      const items = kept.map((item) => ({
+        text: item.text,
+        ...(item.id === undefined ? {} : { id: item.id }),
+        ...(item.workspace !== undefined && workspaces.has(item.workspace) ? { workspace: workspaces.get(item.workspace) } : {}),
+      }))
+      profile = mergeDirectives(safeProfile(), items, { nextId: nextDirectiveId })
+      startNextTrial(profile)
       profile.analysesSinceDirectives = 0
       capAndSaveProfile(profile)
       const scoped = items.filter((item) => item.workspace !== undefined).length
@@ -725,6 +772,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
       // Soft: the counter stays and the next analysis retries.
       console.warn('[tacit] directive distillation failed (will retry):', error instanceof Error ? error.message : String(error))
     } finally {
+      if (ownRun) closeRun(usageRunId)
       directivesInFlight = false
     }
   }
@@ -736,6 +784,8 @@ export function createCoachService(ctx, store, effectiveConfig) {
    * empty note, or a later step leaves the step exactly as it was.
    */
   const preStep = async (payload, next) => {
+    /** '' until the enrichment call is actually about to happen. */
+    let usageRunId = ''
     try {
       const config = effectiveConfig()
       if (!config.enrichPrompts) return next()
@@ -746,8 +796,10 @@ export function createCoachService(ctx, store, effectiveConfig) {
       if (draft.length < ENRICH_MIN_DRAFT_CHARS || draft.length > ENRICH_MAX_DRAFT_CHARS) return next()
       const sessionId = typeof payload.agent?.session?.id === 'string' ? payload.agent.session.id : (typeof payload.agent?.id === 'string' ? payload.agent.id : '')
       const { turns } = sessionId.length > 0 ? turnsOf(serviceOf(ctx), sessionId) : { turns: [] }
-      const text = await callCoachModel(ctx, {
-        provider: sessionId.length > 0 ? providerForSession(sessionId) : COACH_PROVIDER,
+      const provider = sessionId.length > 0 ? providerForSession(sessionId) : COACH_PROVIDER
+      usageRunId = usage.beginRun({ type: 'prompt-enrichment', trigger: 'send', sessionId, model: config.model, provider })
+      const text = await callCoachModel(ctx, metered(usageRunId, { op: 'enrichment', sessionId }, {
+        provider,
         model: config.model,
         system: ENRICH_SYSTEM_PROMPT,
         userText: buildEnrichUserText({ draft, profile: safeProfile(), recentContext: recentContextOf(turns) }),
@@ -755,7 +807,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
         timeoutMs: ENRICH_TIMEOUT_MS,
         tool: ENRICH_TOOL,
         sessionId,
-      })
+      }))
       const note = normalizeEnrichNote(text)
       if (note.length === 0) return next()
       const base = await next()
@@ -767,6 +819,8 @@ export function createCoachService(ctx, store, effectiveConfig) {
       return { kind: 'enter', messages: [...base.messages, added] }
     } catch {
       return next()
+    } finally {
+      if (usageRunId !== '') closeRun(usageRunId)
     }
   }
 
@@ -779,27 +833,53 @@ export function createCoachService(ctx, store, effectiveConfig) {
       if (session === null || typeof session !== 'object' || typeof session.id !== 'string') continue
       if (cwd !== undefined && cwdOf(session) !== cwd) continue
       const { turns } = turnsOf(svc, session.id)
-      for (const turn of turns) if (turn?.finished === true) out.push(turn)
+      for (const turn of markCorrections(turns)) if (turn.finished === true) out.push(turn)
     }
     return out
   }
 
-  /** One bootstrap at a time; progress is exposed through /state. */
-  const bootstrapState = { running: false, done: 0, total: 0, startedAt: 0 }
+  /** One bootstrap at a time; progress AND its running cost are exposed through /state. */
+  /** Live bootstrap progress for `/state`. `tokensTotal` is a single billed-token count —
+   *  deliberately not named `tokens`, which everywhere else in the ledger is the five-bucket object. */
+  const bootstrapState = { running: false, done: 0, total: 0, startedAt: 0, runId: '', billedCalls: 0, unpricedCalls: 0, usdKnown: 0, tokensTotal: 0 }
+
+  /** Back to "no bootstrap has run": every field, so a no-op never shows the previous batch's figures. */
+  const resetBootstrapState = () => {
+    bootstrapState.running = false
+    bootstrapState.done = 0
+    bootstrapState.total = 0
+    bootstrapState.startedAt = 0
+    bootstrapState.runId = ''
+    bootstrapState.billedCalls = 0
+    bootstrapState.unpricedCalls = 0
+    bootstrapState.usdKnown = 0
+    bootstrapState.tokensTotal = 0
+  }
+
+  /** Mirror the bootstrap run's live counters into the state the panel polls. */
+  const refreshBootstrapUsage = () => {
+    const summary = bootstrapState.runId === '' ? null : usage.runSummary(bootstrapState.runId)
+    if (summary === null) return
+    bootstrapState.billedCalls = summary.billedCalls
+    bootstrapState.unpricedCalls = summary.unpricedCalls
+    bootstrapState.usdKnown = summary.usdKnown
+    bootstrapState.tokensTotal = totalTokens(summary.tokens)
+  }
 
   /**
-   * "Learn from my last N turns now": explicit user action, so it ignores the
-   * daily auto budget. Skips continuations, tiny prompts and turns that already
-   * have a report; runs up to `bootstrapConcurrency` analyses at once (same
-   * number of calls either way); then forces one directive distillation.
+   * Which turns a bootstrap would analyze, newest first: every finished turn of
+   * one session (or of every live session), minus continuations, tiny prompts
+   * and turns that already have a report, capped at `limit`. Pure selection —
+   * no model call, no run, no state touched — so the preview and the batch it
+   * previews always answer from the same rule. `code` is `'no-session'` when a
+   * requested session is not live.
    */
-  const runBootstrap = async ({ sessionId, limit }) => {
-    if (bootstrapState.running) return { ok: false, analyzed: 0, skipped: 0, directives: 0, code: 'busy', detail: '' }
+  const bootstrapCandidates = ({ sessionId, limit }) => {
     const svc = serviceOf(ctx)
     const pool = []
     if (typeof sessionId === 'string' && sessionId.length > 0) {
       const { session, turns } = turnsOf(svc, sessionId)
-      if (session === undefined) return { ok: false, analyzed: 0, skipped: 0, directives: 0, code: 'no-session', detail: '' }
+      if (session === undefined) return { eligible: [], skipped: 0, code: 'no-session' }
       for (const turn of turns) if (turn?.finished === true) pool.push({ sessionId, turn, turns })
     } else {
       const sessions = typeof svc.sessions?.list === 'function' ? svc.sessions.list() : []
@@ -821,10 +901,79 @@ export function createCoachService(ctx, store, effectiveConfig) {
       eligible.push(item)
       if (eligible.length >= limit) break
     }
+    return { eligible, skipped, code: '' }
+  }
+
+  /**
+   * What a bootstrap of `count` turns is likely to cost. The ledger wins as
+   * soon as it holds enough priced analyses (median, plus the one directive
+   * distillation a batch also pays for); until then the documented per-analysis
+   * figure for the configured model does.
+   */
+  const estimateBootstrap = (count, model) => {
+    const sample = usage.analysisCostSample()
+    if (sample.samples >= MEASURED_MIN_SAMPLES && typeof sample.perAnalysisUsd === 'number') {
+      const perAnalysisUsd = sample.perAnalysisUsd
+      const distillationUsd = typeof sample.distillationUsd === 'number' ? sample.distillationUsd : 0
+      return { usd: perAnalysisUsd * count + (count > 0 ? distillationUsd : 0), basis: 'measured', samples: sample.samples, perAnalysisUsd }
+    }
+    const perAnalysisUsd = DOC_ANALYSIS_USD[model] ?? DOC_ANALYSIS_USD['deepseek-v4-flash']
+    return { usd: perAnalysisUsd * count, basis: 'doc', samples: sample.samples, perAnalysisUsd }
+  }
+
+  /**
+   * "What would ⚡ Bootstrap do, and what would it cost?" — the same selection
+   * the run itself uses, priced from the ledger. Read-only: no model call, no
+   * run, and deliberately NOT blocked by a bootstrap already running.
+   */
+  const bootstrapPreview = ({ sessionId, limit }) => {
+    const config = effectiveConfig()
+    const { eligible, skipped, code } = bootstrapCandidates({ sessionId, limit })
+    const count = code === '' ? eligible.length : 0
+    return {
+      ok: code === '',
+      eligible: count,
+      skipped: code === '' ? skipped : 0,
+      limit,
+      model: config.model,
+      estimate: estimateBootstrap(count, config.model),
+      code,
+      detail: '',
+    }
+  }
+
+  /**
+   * "Learn from my last N turns now": explicit user action, so it ignores the
+   * daily auto budget. Skips continuations, tiny prompts and turns that already
+   * have a report; runs up to `bootstrapConcurrency` analyses at once (same
+   * number of calls either way); then forces one directive distillation.
+   */
+  const runBootstrap = async ({ sessionId, limit }) => {
+    if (bootstrapState.running) return { ok: false, analyzed: 0, skipped: 0, directives: 0, code: 'busy', detail: '', run: null }
+    const { eligible, skipped, code } = bootstrapCandidates({ sessionId, limit })
+    if (code !== '') return { ok: false, analyzed: 0, skipped: 0, directives: 0, code, detail: '', run: null }
+    // Nothing to analyze is a no-op, not a run: an empty run would be written
+    // to the ledger as `failed` (no attempts) and read as a broken bootstrap.
+    if (eligible.length === 0) {
+      resetBootstrapState()
+      return { ok: true, analyzed: 0, skipped, directives: safeProfile().directives.length, code: '', detail: '', run: null }
+    }
+    const config = effectiveConfig()
+    const scopedToSession = typeof sessionId === 'string' && sessionId.length > 0
+    // ONE parent run for the whole batch: every analysis and the forced
+    // distillation are attempts of it, so the panel shows one line, one price.
+    const runId = usage.beginRun({
+      type: 'bootstrap',
+      trigger: 'bootstrap',
+      sessionId: sessionId ?? '',
+      model: config.model,
+      provider: scopedToSession ? providerForSession(sessionId) : COACH_PROVIDER,
+    })
+    resetBootstrapState()
     bootstrapState.running = true
-    bootstrapState.done = 0
     bootstrapState.total = eligible.length
     bootstrapState.startedAt = Date.now()
+    bootstrapState.runId = runId
     let analyzed = 0
     try {
       // A small worker pool: each worker pulls the next eligible turn until the
@@ -837,23 +986,80 @@ export function createCoachService(ctx, store, effectiveConfig) {
           const item = eligible[next]
           next += 1
           const previous = previousFinishedOf(item.turns, item.turn.turn)
-          const result = await runAnalysis(item.sessionId, item.turn.turn, { trigger: 'bootstrap', digest: item.turn, previousDigest: previous })
+          const result = await runAnalysis(item.sessionId, item.turn.turn, { trigger: 'bootstrap', digest: item.turn, previousDigest: previous, runId })
           if (result !== null && typeof result === 'object' && result.ok === true) analyzed += 1
           else console.warn('[tacit] bootstrap: ' + item.sessionId + ':' + item.turn.turn + ' skipped: ' + (result?.code ?? 'unknown'))
           bootstrapState.done += 1
+          refreshBootstrapUsage()
         }
       }
-      const concurrency = Math.min(effectiveConfig().bootstrapConcurrency, Math.max(1, eligible.length))
+      const concurrency = Math.min(config.bootstrapConcurrency, Math.max(1, eligible.length))
       await Promise.all(Array.from({ length: concurrency }, () => worker()))
       if (analyzed > 0) {
         await service.flushAuto() // let any scheduled distillation settle before forcing one
         // The forced distillation is attributed to the newest eligible turn's session.
-        await maybeDistillDirectives(eligible[0].sessionId, providerForSession(eligible[0].sessionId), { force: true })
+        await maybeDistillDirectives(eligible[0].sessionId, providerForSession(eligible[0].sessionId), { force: true, runId })
       }
     } finally {
       bootstrapState.running = false
+      closeRun(runId, { requested: limit, eligible: eligible.length, analyzed, skipped, directives: safeProfile().directives.length })
+      refreshBootstrapUsage()
+      // Mirror the final counters first, then drop the id: the tile keeps the
+      // finished run's figures, but nothing may still call it the live run.
+      bootstrapState.runId = ''
+    }
+    return { ok: true, analyzed, skipped, directives: safeProfile().directives.length, code: '', detail: '', run: usage.runSummary(runId) }
+  }
+
+  /**
+   * "Analyze exactly these turns": the user picked them, so nothing is filtered
+   * out and the daily auto budget does not apply. One parent run covers the
+   * whole batch (the analyses are its attempts); the same `runExclusive` key as
+   * every other analysis means a turn already being analyzed — by a bootstrap,
+   * an auto trigger or another batch — reports `busy` and costs nothing. A
+   * bootstrap running elsewhere does NOT block the batch.
+   */
+  const analyzeBatch = async ({ sessionId, turns }) => {
+    const { session } = turnsOf(serviceOf(ctx), sessionId)
+    if (session === undefined) return { ok: false, results: [], profile: safeProfile(), run: null, code: 'no-session', detail: '' }
+    const wanted = [...new Set(turns)].sort((a, b) => a - b)
+    const config = effectiveConfig()
+    const runId = usage.beginRun({
+      type: 'analysis-batch',
+      trigger: 'manual',
+      sessionId,
+      workspace: workspaceLabel(cwdOf(session)),
+      model: config.model,
+      provider: providerForSession(sessionId),
+    })
+    const results = new Array(wanted.length)
+    let analyzed = 0
+    try {
+      // The same worker pool as the bootstrap: different turns never share an
+      // in-flight key, so the pool is the only thing bounding concurrency.
+      let next = 0
+      const worker = async () => {
+        while (next < wanted.length) {
+          const at = next
+          next += 1
+          const turn = wanted[at]
+          const result = await runAnalysis(sessionId, turn, { trigger: 'manual', runId })
+          const ok = result !== null && typeof result === 'object' && result.ok === true
+          if (ok) analyzed += 1
+          results[at] = { turn, ok, code: result?.code ?? 'call-failed', report: ok ? result.report : null }
+        }
+      }
+      const concurrency = Math.min(config.bootstrapConcurrency, Math.max(1, wanted.length))
+      await Promise.all(Array.from({ length: concurrency }, () => worker()))
+    } finally {
+      // Every requested turn was already being analyzed elsewhere: no call was
+      // made and nothing failed, so this is a real request that succeeded —
+      // not the zero-attempt `failed` run the default derivation would write.
+      const entries = results.filter((entry) => entry !== null && entry !== undefined)
+      const allBusy = analyzed === 0 && entries.length === wanted.length && entries.every((entry) => entry.code === 'busy')
+      closeRun(runId, { requested: wanted.length, analyzed, skipped: wanted.length - analyzed }, allBusy ? 'success' : undefined)
     }
-    return { ok: true, analyzed, skipped, directives: safeProfile().directives.length, code: '', detail: '' }
+    return { ok: true, results, profile: safeProfile(), run: usage.runSummary(runId), code: '', detail: '' }
   }
 
   const autoStatus = () => {
@@ -931,6 +1137,11 @@ export function createCoachService(ctx, store, effectiveConfig) {
   }
 
   const service = {
+    /** The usage/cost ledger (flushed on dispose; read by the cost routes). */
+    usage,
+    /** The price source behind the ledger. */
+    pricing,
+
     /** Await every in-flight automatic analysis (tests / orderly shutdown). */
     async flushAuto() {
       await Promise.all([...autoRunning])
@@ -941,6 +1152,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
       const svc = serviceOf(ctx)
       const sessionId = args !== null && typeof args === 'object' && typeof args.sessionId === 'string' && args.sessionId.length > 0 ? args.sessionId : null
       const session = sessionId !== null && typeof svc.sessions?.get === 'function' ? svc.sessions.get(sessionId) : undefined
+      refreshBootstrapUsage()
       return {
         ok: true,
         config: effectiveConfig(),
@@ -975,21 +1187,30 @@ export function createCoachService(ctx, store, effectiveConfig) {
     async analyzeTurn(args) {
       const parsed = analyzeArgSchema.safeParse(args)
       if (!parsed.success) {
-        return { ok: false, report: null, profile: safeProfile(), code: 'bad-request', detail: '' }
+        return { ok: false, report: null, profile: safeProfile(), code: 'bad-request', detail: '', run: null }
       }
       return runAnalysis(parsed.data.sessionId, parsed.data.turn, { trigger: 'manual' })
     },
 
+    /** Analyze a hand-picked set of turns of one session under a single run. */
+    async analyzeBatch(args) {
+      const parsed = analyzeBatchArgSchema.safeParse(args)
+      if (!parsed.success) {
+        return { ok: false, results: [], profile: safeProfile(), run: null, code: 'bad-request', detail: '' }
+      }
+      return analyzeBatch(parsed.data)
+    },
+
     async improveDraft(args) {
       const parsed = improveArgSchema.safeParse(args)
       if (!parsed.success) {
-        return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: 'bad-request', detail: '' }
+        return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: 'bad-request', detail: '', run: null }
       }
       const { sessionId, draft } = parsed.data
       const config = effectiveConfig()
       const profile = safeProfile()
       const svc = serviceOf(ctx)
-      const { turns } = turnsOf(svc, sessionId)
+      const { session, turns } = turnsOf(svc, sessionId)
       const recentContext = recentContextOf(turns)
       // Distillation also fires on user-triggered improve calls (soft, in-flight
       // deduped, never awaited: an improve call is never blocked by it).
@@ -1007,12 +1228,13 @@ export function createCoachService(ctx, store, effectiveConfig) {
         styleRules: profile.styleRules,
         negativeFeedback: lastDownReasons(profile, 3),
       })
+      // Provider follows the session's own route (latest known), so proxy
+      // or custom provider setups keep working; the shipped DeepSeek
+      // adapter id is the fallback.
+      const provider = providerForSession(sessionId)
+      const runId = usage.beginRun({ type: 'improve', trigger: 'manual', sessionId, workspace: workspaceLabel(cwdOf(session)), model: config.model, provider })
       try {
-        // Provider follows the session's own route (latest known), so proxy
-        // or custom provider setups keep working; the shipped DeepSeek
-        // adapter id is the fallback.
-        const provider = providerForSession(sessionId)
-        let text = await callCoachModel(ctx, {
+        let text = await callCoachModel(ctx, metered(runId, { op: 'improve', sessionId }, {
           provider,
           model: config.model,
           system: IMPROVE_SYSTEM_PROMPT,
@@ -1021,13 +1243,13 @@ export function createCoachService(ctx, store, effectiveConfig) {
           timeoutMs: IMPROVE_TIMEOUT_MS,
           tool: IMPROVE_TOOL,
           sessionId,
-        })
+        }))
         if (text.trim() === '') {
-          return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: 'empty-response', detail: '' }
+          return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: 'empty-response', detail: '', run: closeRun(runId) }
         }
         let parsed = parseJsonObject(text)
         if (parsed === null) {
-          const repaired = await callCoachModel(ctx, {
+          const repaired = await callCoachModel(ctx, metered(runId, { op: 'improve-repair', sessionId }, {
             provider,
             model: config.model,
             system: IMPROVE_REPAIR_SYSTEM_PROMPT,
@@ -1036,7 +1258,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
             timeoutMs: IMPROVE_TIMEOUT_MS,
             tool: IMPROVE_TOOL,
             sessionId,
-          })
+          }))
           if (repaired.trim() !== '') {
             const reparsed = parseJsonObject(repaired)
             if (reparsed !== null) parsed = reparsed
@@ -1052,10 +1274,13 @@ export function createCoachService(ctx, store, effectiveConfig) {
           draft: draft.trim().slice(0, 1000),
           improved: result.improved.slice(0, 2000),
         })
-        return { ok: true, ...result, rewriteId, patternsUsed, code: '', detail: '' }
+        return { ok: true, ...result, rewriteId, patternsUsed, code: '', detail: '', run: closeRun(runId) }
       } catch (error) {
         const detail = error instanceof Error ? error.message.slice(0, 300) : String(error).slice(0, 300)
-        return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: coachErrorCode(error), detail }
+        return { ok: false, improved: '', rationale: '', rewriteId: '', patternsUsed: [], code: coachErrorCode(error), detail, run: closeRun(runId) }
+      } finally {
+        // Idempotent: the returns above already closed it; this catches a throw.
+        closeRun(runId)
       }
     },
 
@@ -1153,6 +1378,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
       } else {
         profile.directives = profile.directives.filter((entry) => entry.id !== input.id)
       }
+      startNextTrial(profile)
       const saved = capAndSaveProfile(profile)
       return { ok: true, profile: saved, steering: steeringStatus(), code: '', detail: '' }
     },
@@ -1165,10 +1391,29 @@ export function createCoachService(ctx, store, effectiveConfig) {
 
     async bootstrap(args) {
       const parsed = bootstrapArgSchema.safeParse(args !== null && typeof args === 'object' ? args : {})
-      if (!parsed.success) return { ok: false, analyzed: 0, skipped: 0, directives: 0, code: 'bad-request', detail: '' }
+      if (!parsed.success) return { ok: false, analyzed: 0, skipped: 0, directives: 0, code: 'bad-request', detail: '', run: null }
       return runBootstrap({ sessionId: parsed.data.sessionId, limit: parsed.data.limit ?? 20 })
     },
 
+    /** What a bootstrap would analyze and what it would cost. Free: no model call, no run. */
+    async bootstrapPreview(args) {
+      const parsed = bootstrapArgSchema.safeParse(args !== null && typeof args === 'object' ? args : {})
+      if (!parsed.success) {
+        const config = effectiveConfig()
+        return {
+          ok: false,
+          eligible: 0,
+          skipped: 0,
+          limit: 20,
+          model: config.model,
+          estimate: estimateBootstrap(0, config.model),
+          code: 'bad-request',
+          detail: '',
+        }
+      }
+      return bootstrapPreview({ sessionId: parsed.data.sessionId, limit: parsed.data.limit ?? 20 })
+    },
+
     async stats(args) {
       const parsed = statsArgSchema.safeParse(args !== null && typeof args === 'object' ? args : {})
       const window = parsed.success && typeof parsed.data.window === 'number' ? parsed.data.window : 20
@@ -1190,6 +1435,39 @@ export function createCoachService(ctx, store, effectiveConfig) {
       const removed = store.clearReports()
       return { ok: true, removed, code: '', detail: '' }
     },
+
+    /** The whole cost panel: period cards, series, breakdowns, warnings and one page of runs. */
+    async usageReport(args) {
+      const parsed = usageArgSchema.safeParse(args !== null && typeof args === 'object' ? args : {})
+      if (!parsed.success) return { ok: false, code: 'bad-request', detail: '' }
+      return usage.report({
+        config: effectiveConfig(),
+        pricingStatus: pricing.status(),
+        pricingRates: pricing.rates(),
+        filters: parsed.data,
+      })
+    },
+
+    /** One run with its attempt rows (a live run included); expired ids are a soft `unknown-run`. */
+    async usageRun(args) {
+      const parsed = usageRunArgSchema.safeParse(args)
+      if (!parsed.success) return { ok: false, run: null, code: 'bad-request', detail: '' }
+      const run = usage.run(parsed.data.runId)
+      if (run === null) return { ok: false, run: null, code: 'unknown-run', detail: '' }
+      return { ok: true, run, code: '', detail: '' }
+    },
+
+    /** Delete the ledger and restart the tracking window (live runs keep recording into it). */
+    async usageClear() {
+      const { removed, trackingSince } = usage.clear()
+      return { ok: true, removed, trackingSince, code: '', detail: '' }
+    },
+
+    /** Re-read the optional costMeter sibling; `refresh()` never throws, so this never fails. */
+    async pricingRefresh() {
+      await pricing.refresh()
+      return { ok: true, pricing: { ...pricing.status(), rates: pricing.rates() }, code: '', detail: '' }
+    },
   }
 
   return service