dsh-tacit 0.2.3 → 0.3.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 {
@@ -92,6 +100,13 @@ import {
 
 /** 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 +134,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
 }
 
@@ -229,23 +247,50 @@ 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'
+  // 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 +373,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 +390,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 +400,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
     } catch {
       return profile
     } finally {
+      closeRun(runId)
       distillInFlight = false
     }
   }
@@ -469,9 +519,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 +543,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 +564,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 +585,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 +597,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 +613,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 +645,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) => {
@@ -682,12 +750,16 @@ export function createCoachService(ctx, store, effectiveConfig) {
   }
 
   /** 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 +769,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,7 +778,7 @@ 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) {
@@ -725,6 +797,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 +809,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 +821,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 +832,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 +844,8 @@ export function createCoachService(ctx, store, effectiveConfig) {
       return { kind: 'enter', messages: [...base.messages, added] }
     } catch {
       return next()
+    } finally {
+      if (usageRunId !== '') closeRun(usageRunId)
     }
   }
 
@@ -784,22 +863,35 @@ export function createCoachService(ctx, store, effectiveConfig) {
     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 }
+
+  /** 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 +913,82 @@ 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) {
+      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,
+    })
     bootstrapState.running = true
     bootstrapState.done = 0
     bootstrapState.total = eligible.length
     bootstrapState.startedAt = Date.now()
+    bootstrapState.runId = runId
+    bootstrapState.billedCalls = 0
+    bootstrapState.unpricedCalls = 0
+    bootstrapState.usdKnown = 0
+    bootstrapState.tokensTotal = 0
     let analyzed = 0
     try {
       // A small worker pool: each worker pulls the next eligible turn until the
@@ -837,23 +1001,77 @@ 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()
+    }
+    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 +1149,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 +1164,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 +1199,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 +1240,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 +1255,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 +1270,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 +1286,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)
       }
     },
 
@@ -1165,10 +1402,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 +1446,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