dsh-tacit 0.2.2 → 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 {
@@ -44,6 +52,9 @@ import {
   normalizeReport,
   parseJsonObject,
   ANALYSIS_SYSTEM_PROMPT,
+  GOOD_SYSTEM_PROMPT,
+  GOOD_TOOL,
+  normalizeGoodReport,
   ANALYSIS_REPAIR_SYSTEM_PROMPT,
   IMPROVE_SYSTEM_PROMPT,
   IMPROVE_REPAIR_SYSTEM_PROMPT,
@@ -71,7 +82,10 @@ import {
   DIRECTIVE_TIMEOUT_MS,
   MAX_DIRECTIVES,
   buildDirectiveUserText,
+  buildSteeringSection,
   renderSteeringSection,
+  workspaceLabel,
+  MAX_WORKSPACE_DIRECTIVES,
   ENRICH_SYSTEM_PROMPT,
   ENRICH_TOOL,
   ENRICH_MAX_TOKENS,
@@ -86,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
 
@@ -111,6 +132,11 @@ export function mergeConfig(base, patch) {
   merged.enrichPrompts = merged.enrichPrompts === true
   merged.directiveTrialTurns = Math.max(1, Math.min(500, Math.round(Number(merged.directiveTrialTurns) || 10)))
   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
 }
 
@@ -134,15 +160,44 @@ function turnsOf(service, sessionId) {
   }
 }
 
-/** A human label for a session: the workspace directory's basename, else ''. */
-function sessionLabelOf(service, sessionId) {
-  const session = typeof service.sessions?.get === 'function' ? service.sessions.get(sessionId) : undefined
+/** The absolute workspace directory a session was created in, else undefined. */
+function cwdOf(session) {
   const cwd = session !== null && typeof session === 'object' && session.header !== null && typeof session.header === 'object'
     ? session.header.cwd
     : undefined
-  if (typeof cwd !== 'string' || cwd.length === 0) return ''
-  const parts = cwd.split(/[\\/]+/).filter((part) => part.length > 0)
-  return parts.length > 0 ? parts[parts.length - 1] : ''
+  return typeof cwd === 'string' && cwd.length > 0 ? cwd : undefined
+}
+
+/** A human label for a session: the workspace directory's basename, else ''. */
+function sessionLabelOf(service, sessionId) {
+  const session = typeof service.sessions?.get === 'function' ? service.sessions.get(sessionId) : undefined
+  return workspaceLabel(cwdOf(session))
+}
+
+/** Every distinct workspace among the live sessions, labelled for the UI. */
+function listWorkspaces(service) {
+  const sessions = typeof service.sessions?.list === 'function' ? service.sessions.list() : []
+  const seen = new Map()
+  for (const session of Array.isArray(sessions) ? sessions : []) {
+    const cwd = cwdOf(session)
+    if (cwd !== undefined && !seen.has(cwd)) seen.set(cwd, { cwd, label: workspaceLabel(cwd) })
+  }
+  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. */
@@ -192,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()
@@ -220,6 +302,9 @@ export function createCoachService(ctx, store, effectiveConfig) {
   const rewriteRecords = new Map()
   /** sessionId → FIFO [{rewriteId, baseline}] (one per applied rewrite). */
   const pendingVerifications = new Map()
+  /** sessionId → ids of the directives in that session's frozen steering (bounded; insertion order = age). */
+  const steeringIdsBySession = new Map()
+  const MAX_STEERING_SESSIONS = 500
   let distillInFlight = false
   let rewriteSeq = 0
 
@@ -235,7 +320,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
     return 'd' + Date.now().toString(36) + '-' + directiveSeq.toString(36)
   }
   let directivesInFlight = false
-  /** Steering text frozen per live session (keeps the model's prefix cache stable within a session). */
+  /** Steering `{ text, ids }` frozen per live session object (keeps the model's prefix cache stable within a session). */
   const steeringFrozen = new WeakMap()
 
   const nextRewriteId = () => {
@@ -272,7 +357,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
     profile.patterns = profile.patterns.slice(0, config.maxPatterns)
     profile.styleRules = profile.styleRules.slice(-MAX_STYLE_RULES)
     profile.feedbackLog = profile.feedbackLog.slice(-MAX_FEEDBACK_LOG)
-    profile.directives = profile.directives.slice(0, MAX_DIRECTIVES)
+    profile.directives = capDirectives(profile.directives)
     profile.updatedAt = Date.now()
     const validated = profileSchema.parse(profile)
     store.saveProfile(validated)
@@ -288,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,
@@ -301,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()
@@ -311,6 +400,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
     } catch {
       return profile
     } finally {
+      closeRun(runId)
       distillInFlight = false
     }
   }
@@ -354,10 +444,12 @@ export function createCoachService(ctx, store, effectiveConfig) {
 
   /**
    * Directive trials ride the same free feed: every NEW finished turn counts
-   * toward each candidate; after `directiveTrialTurns` the candidate is
-   * activated, or retired when the messy rate rose past the baseline by more
-   * than `directiveWorseBy`. Steering text is frozen per session, so a verdict
-   * reaches new sessions only — by design.
+   * 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.
    */
   const recordTrialTurns = (sessionId, turns) => {
     const fresh = (Array.isArray(turns) ? turns : []).filter((turn) => turn !== null && typeof turn === 'object'
@@ -365,8 +457,10 @@ export function createCoachService(ctx, store, effectiveConfig) {
       && !seenFinished.has(sessionId + ':' + turn.turn))
     if (fresh.length === 0) return
     for (const turn of fresh) seenFinished.add(sessionId + ':' + turn.turn)
+    const steered = steeringIdsBySession.get(sessionId)
+    if (steered === undefined || steered.length === 0) return
     const profile = safeProfile()
-    const candidates = profile.directives.filter((entry) => entry.status === 'candidate' && entry.trial !== undefined)
+    const candidates = profile.directives.filter((entry) => entry.status === 'candidate' && entry.trial !== undefined && steered.includes(entry.id))
     if (candidates.length === 0) return
     const config = effectiveConfig()
     const messyCount = fresh.filter((turn) => isMessyTurn(turn, { minSteps: Number.POSITIVE_INFINITY })).length
@@ -425,13 +519,18 @@ 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)
       if (session === undefined) return { ok: false, report: null, profile, code: 'no-session', detail: '' }
+      const cwd = cwdOf(session)
       // The change feed already carries the digest; a manual click re-reads the snapshot.
       const record = digest !== null && typeof digest === 'object' ? digest : turns.find((candidate) => candidate?.turn === turn)
       if (record === undefined) return { ok: false, report: null, profile, code: 'not-retained', detail: '' }
@@ -444,11 +543,52 @@ 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
-        let text = await callCoachModel(ctx, {
+        if (trigger === 'good') {
+          // One attempt, no repair retry: a recovery lesson is a bonus, not a diagnosis.
+          const goodText = await callCoachModel(ctx, metered(usageRunId, { op: 'analysis', sessionId, turn }, {
+            provider,
+            model: config.model,
+            system: GOOD_SYSTEM_PROMPT,
+            userText,
+            maxTokens: ANALYZE_MAX_TOKENS,
+            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 = {
+            ...normalizeGoodReport(goodParsed, { turn, time: Date.now(), model: config.model, prompt: record.prompt }),
+            ...(typeof record.prompt === 'string' && record.prompt.length > 0 ? { promptExcerpt: clipSafe(record.prompt, 200) } : {}),
+            trigger,
+            ...(cwd !== undefined ? { cwd } : {}),
+          }
+          if (goodReport.lesson === '' && goodReport.strengths.length === 0) {
+            return { ok: false, report: null, profile, code: 'nothing-learned', detail: '' }
+          }
+          const isNew = store.report(sessionId, turn) === null
+          store.saveReport(sessionId, turn, goodReport)
+          const grown = aggregateProfile(store.profile(), goodReport, config.maxPatterns, { countNew: isNew })
+          if (isNew) grown.analysesSinceDirectives = (grown.analysesSinceDirectives ?? 0) + 1
+          store.saveProfile(grown)
+          if (isNew && !bootstrapState.running) {
+            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, metered(usageRunId, { op: 'analysis', sessionId, turn }, {
           provider,
           model: config.model,
           system: ANALYSIS_SYSTEM_PROMPT,
@@ -457,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,
@@ -473,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) {
@@ -494,6 +634,7 @@ export function createCoachService(ctx, store, effectiveConfig) {
             : {}),
           trigger,
           ...(followUp.length > 0 ? { followUp: clipSafe(followUp, 300) } : {}),
+          ...(cwd !== undefined ? { cwd } : {}),
         }
         const countNew = store.report(sessionId, turn) === null
         store.saveReport(sessionId, turn, report)
@@ -504,33 +645,48 @@ 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 = () => {
+  const steeringStatus = (cwd) => {
     const config = effectiveConfig()
-    return { enabled: config.steerAgent, text: config.steerAgent ? renderSteeringSection(safeProfile()) : '' }
+    return { enabled: config.steerAgent, text: config.steerAgent ? renderSteeringSection(safeProfile(), { cwd }) : '' }
   }
 
+  /** What a session in `cwd` assembling its system prompt right now would get. */
+  const steeringNow = (cwd) => (effectiveConfig().steerAgent ? buildSteeringSection(safeProfile(), { cwd }) : { text: '', ids: [] })
+
   /** The system-prompt section provider (sync; frozen per session). */
   const steeringText = (assemble) => {
     const session = assemble !== null && typeof assemble === 'object' && assemble.agent !== null && typeof assemble.agent === 'object'
       ? assemble.agent.session
       : undefined
-    if (session === null || session === undefined || typeof session !== 'object') return steeringStatus().text
+    if (session === null || session === undefined || typeof session !== 'object') return steeringNow().text
     let frozen = steeringFrozen.get(session)
     if (frozen === undefined) {
-      frozen = steeringStatus().text
+      frozen = steeringNow(cwdOf(session))
       steeringFrozen.set(session, frozen)
+      if (typeof session.id === 'string' && session.id.length > 0) {
+        steeringIdsBySession.delete(session.id)
+        steeringIdsBySession.set(session.id, frozen.ids)
+        while (steeringIdsBySession.size > MAX_STEERING_SESSIONS) steeringIdsBySession.delete(steeringIdsBySession.keys().next().value)
+      }
     }
-    return frozen
+    return frozen.text
   }
 
   /**
@@ -538,48 +694,82 @@ export function createCoachService(ctx, store, effectiveConfig) {
    * entries are untouched, and a re-emitted directive keeps the enabled flag
    * the user gave its identical text. Capped at MAX_DIRECTIVES overall.
    */
-  const mergeDirectives = (profile, texts) => {
-    const previous = new Map(profile.directives.filter((entry) => entry.source !== 'user').map((entry) => [entry.text.trim().toLowerCase(), entry]))
+  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 }) : []
+    const turns = scoped.length >= 20 ? scoped : allFinishedTurns()
+    return computeTrend(turns, { window: 20 }).recent.messyRate
+  }
+
+  /**
+   * 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.
+   */
+  const mergeDirectives = (profile, items) => {
     const users = profile.directives.filter((entry) => entry.source === 'user')
-    const userKeys = new Set(users.map((entry) => entry.text.trim().toLowerCase()))
+    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()
-    let baselineRate = null
-    for (const text of texts) {
-      const key = text.trim().toLowerCase()
+    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 })
+        distilled.push({ ...kept, text: item.text })
         continue
       }
       // A new distilled directive goes on trial against the current messy-turn rate.
-      if (baselineRate === null) baselineRate = computeTrend(allFinishedTurns(), { window: 20 }).recent.messyRate
+      if (!baselines.has(scope)) baselines.set(scope, baselineRateFor(scope === '' ? undefined : scope))
       distilled.push({
         id: nextDirectiveId(),
-        text,
+        text: item.text,
         enabled: true,
         source: 'distilled',
         createdAt: Date.now(),
         status: 'candidate',
-        trial: { turns: 0, messy: 0, baselineRate, startedAt: Date.now() },
+        trial: { turns: 0, messy: 0, baselineRate: baselines.get(scope), startedAt: Date.now() },
+        ...(scope === '' ? {} : { workspace: scope }),
       })
     }
-    profile.directives = [...users, ...distilled].slice(0, MAX_DIRECTIVES)
+    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)
-      const text = await callCoachModel(ctx, {
+      // The model sees workspace names only; map them back to the directories they stand for.
+      const workspaces = new Map()
+      for (const report of recent) {
+        if (typeof report.cwd !== 'string' || report.cwd.length === 0) continue
+        const label = workspaceLabel(report.cwd)
+        if (label.length > 0 && !workspaces.has(label)) workspaces.set(label, report.cwd)
+      }
+      const text = await callCoachModel(ctx, metered(usageRunId, { op: 'directive-distillation', sessionId }, {
         provider,
         model: config.model,
         system: DIRECTIVE_SYSTEM_PROMPT,
@@ -588,21 +778,26 @@ export function createCoachService(ctx, store, effectiveConfig) {
         timeoutMs: DIRECTIVE_TIMEOUT_MS,
         tool: DIRECTIVE_TOOL,
         sessionId,
-      })
-      const { kept: texts, rejected } = classifyDirectives(text)
+      }))
+      const { kept, rejected } = classifyDirectives(text)
       for (const dropped of rejected) console.warn('[tacit] dropped directive (it asks the user instead of compensating):', dropped)
-      if (texts.length === 0) {
+      if (kept.length === 0) {
         console.warn('[tacit] directive distillation returned nothing usable; will retry after the next analysis:', clipSafe(text, 300))
         return
       }
-      profile = mergeDirectives(safeProfile(), texts)
+      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)
       profile.analysesSinceDirectives = 0
       capAndSaveProfile(profile)
-      console.info('[tacit] distilled ' + texts.length + ' directive(s) into the steering section')
+      const scoped = items.filter((item) => item.workspace !== undefined).length
+      console.info('[tacit] distilled ' + items.length + ' directive(s) into the steering section' + (scoped > 0 ? ' (' + scoped + ' workspace-specific)' : ''))
     } catch (error) {
       // 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
     }
   }
@@ -614,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()
@@ -624,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) }),
@@ -633,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()
@@ -645,37 +844,54 @@ export function createCoachService(ctx, store, effectiveConfig) {
       return { kind: 'enter', messages: [...base.messages, added] }
     } catch {
       return next()
+    } finally {
+      if (usageRunId !== '') closeRun(usageRunId)
     }
   }
 
-  /** Every live session's finished turns, for the measured trend. */
-  const allFinishedTurns = () => {
+  /** Every live session's finished turns (optionally only sessions in one workspace), for the measured trend. */
+  const allFinishedTurns = ({ cwd } = {}) => {
     const svc = serviceOf(ctx)
     const sessions = typeof svc.sessions?.list === 'function' ? svc.sessions.list() : []
     const out = []
     for (const session of Array.isArray(sessions) ? sessions : []) {
       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)
     }
     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; 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() : []
@@ -697,29 +913,165 @@ 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
-    let lastProvider = COACH_PROVIDER
     try {
-      for (const item of eligible) {
-        const previous = previousFinishedOf(item.turns, item.turn.turn)
-        const result = await runAnalysis(item.sessionId, item.turn.turn, { trigger: 'bootstrap', digest: item.turn, previousDigest: previous })
-        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'))
-        lastProvider = providerForSession(item.sessionId)
-        bootstrapState.done += 1
+      // A small worker pool: each worker pulls the next eligible turn until the
+      // list is drained. Analyses for different turns never share an in-flight
+      // key, and the profile read-modify-write inside runAnalysis has no await,
+      // so concurrent analyses cannot lose each other's counts.
+      let next = 0
+      const worker = async () => {
+        while (next < eligible.length) {
+          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, 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(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
-        await maybeDistillDirectives(eligible[0].sessionId, lastProvider, { force: true })
+        // The forced distillation is attributed to the newest eligible turn's session.
+        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 = () => {
@@ -755,12 +1107,14 @@ export function createCoachService(ctx, store, effectiveConfig) {
   }
 
   /**
-   * Zero-click learning. Two triggers, both free (no model call to decide):
+   * Zero-click learning. Three triggers, all free (no model call to decide):
    *  - the newest FINISHED turn is messy (retries / tool errors / compactions /
    *    rejection / long step run);
    *  - the newest (possibly unfinished) turn's prompt reads as a correction of
    *    the previous answer → the PREVIOUS turn is analyzed with that
-   *    follow-up attached as evidence.
+   *    follow-up attached as evidence;
+   *  - (learnFromGood) the newest finished turn is clean right after a messy
+   *    one → a small "what did the user include this time" call.
    * Turns finished before the plugin started are ignored (cold restore).
    */
   const maybeAutoAnalyze = (sessionId, turns) => {
@@ -776,6 +1130,14 @@ export function createCoachService(ctx, store, effectiveConfig) {
       // the conversation is its context. Heavy work after it is not a prompt fault.
       if (fresh(newest) && isMessyTurn(newest, { minSteps: config.autoMinSteps }) && !looksLikeContinuation(newest.prompt)) {
         scheduleAuto(sessionId, newest.turn, { trigger: 'auto', digest: newest, previousDigest: previous })
+        return
+      }
+      // A recovery: clean now, messy just before, with a real prompt in between.
+      const recovery = config.learnFromGood && fresh(newest) && !looksLikeContinuation(newest.prompt)
+        && typeof newest.prompt === 'string' && newest.prompt.trim().length >= ENRICH_MIN_DRAFT_CHARS
+        && previous !== null && previous.finished === true && isMessyTurn(previous, { minSteps: config.autoMinSteps })
+      if (recovery) {
+        scheduleAuto(sessionId, newest.turn, { trigger: 'good', digest: newest, previousDigest: previous })
       }
       return
     }
@@ -787,18 +1149,29 @@ 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])
     },
 
-    async getState() {
+    /** Optional `{ sessionId }`: the steering preview is then rendered for that conversation's workspace. */
+    async getState(args) {
+      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(),
         profile: safeProfile(),
         auto: autoStatus(),
-        steering: steeringStatus(),
+        steering: steeringStatus(cwdOf(session)),
+        workspaces: listWorkspaces(svc),
         bootstrap: { ...bootstrapState },
         message: '',
       }
@@ -826,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).
@@ -858,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,
@@ -872,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,
@@ -887,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
@@ -903,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)
       }
     },
 
@@ -999,7 +1385,8 @@ export function createCoachService(ctx, store, effectiveConfig) {
       } else if (input.action === 'add') {
         const text = clipSafe(input.text.trim(), 220)
         if (text.length === 0) return { ok: false, profile, steering: steeringStatus(), code: 'bad-request', detail: 'text' }
-        profile.directives.push({ id: nextDirectiveId(), text, enabled: true, source: 'user', createdAt: Date.now() })
+        const workspace = typeof input.workspace === 'string' && input.workspace.trim().length > 0 ? input.workspace.trim() : undefined
+        profile.directives.push({ id: nextDirectiveId(), text, enabled: true, source: 'user', createdAt: Date.now(), ...(workspace === undefined ? {} : { workspace }) })
       } else {
         profile.directives = profile.directives.filter((entry) => entry.id !== input.id)
       }
@@ -1015,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
@@ -1040,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