@ilaomianyang/dsh-memory-graph 0.10.0

package/src/capture.js

@@ -0,0 +1,237 @@
+/**
+ * Capture: turn the session log into raw episodes.
+ *
+ * Deliberately model-free. Every turn is appended as it closes, so the "never
+ * loses anything" guarantee holds even while the extractor is unconfigured,
+ * offline, or out of quota. Distillation happens later and separately.
+ */
+import { nowIso } from './vault.js'
+
+const FLUSH_AFTER_MS = 90_000
+const MAX_ASSISTANT_PARTS = 6
+
+function collectText(node, depth = 0, seen = new Set(), out = []) {
+  if (node === null || node === undefined || depth > 4) return out
+  if (typeof node === 'string') return out
+  if (Array.isArray(node)) {
+    for (const item of node) collectText(item, depth + 1, seen, out)
+    return out
+  }
+  if (typeof node !== 'object') return out
+  if (seen.has(node)) return out
+  seen.add(node)
+
+  if (node.type === 'text' && typeof node.text === 'string') {
+    out.push(node.text)
+    return out
+  }
+  for (const key of ['content', 'message', 'text', 'parts', 'blocks']) {
+    if (key in node) collectText(node[key], depth + 1, seen, out)
+  }
+  return out
+}
+
+function eventText(event) {
+  const parts = collectText(event?.data)
+  return parts.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
+function projectOf(session, fallback) {
+  const cwd = session?.header?.cwd ?? session?.meta?.cwd ?? session?.cwd
+  if (typeof cwd === 'string' && cwd.trim() !== '') {
+    // Both separators, whatever platform this is running on: the path comes from
+    // the session header, which may well have been written on the other OS.
+    const parts = cwd.replace(/[\\/]+$/, '').split(/[\\/]/)
+    const base = parts[parts.length - 1] ?? ''
+    if (base !== '') return base
+  }
+  return fallback
+}
+
+function truncate(text, max) {
+  const value = String(text ?? '').trim()
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}…`
+}
+
+export function registerCapture(ctx, { cfg, vault, redactor }) {
+  const buffers = new Map()
+  const disposers = []
+  const timers = new Map()
+
+  // Both the switch and the skip list are editable while the plugin runs (they
+  // are `.volatile()` in the schema), so neither is baked in here: the switch is
+  // read per event, and the compiled rules are rebuilt only when the list's text
+  // actually changes — a `new RegExp` on every token would be pure waste.
+  let skipKey
+  let skipRules = []
+
+  function compiledSkipRules() {
+    const list = cfg.capture.skipPatterns ?? []
+    const key = list.join('\u0000')
+    if (key !== skipKey) {
+      skipKey = key
+      skipRules = list.flatMap((pattern) => {
+        try {
+          return [new RegExp(pattern, 'i')]
+        } catch {
+          return []
+        }
+      })
+    }
+    return skipRules
+  }
+
+  /** True when the "user" side is really a harness injection, not a person typing. */
+  const injected = (text) => text !== '' && compiledSkipRules().some((re) => re.test(text))
+
+  /**
+   * Delimited harness blocks come off before the patterns are consulted.
+   *
+   * They are the one kind of injection whose extent is knowable, so removing them
+   * keeps the person's own words when a real message happens to carry one — the
+   * alternative (dropping the whole message) loses the part that was worth
+   * keeping. Undelimited blocks (a runtime snapshot) are handled by the patterns.
+   */
+  function stripInjectedBlocks(text) {
+    return String(text ?? '')
+      .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, '')
+      .replace(/[ \t]+\n/g, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim()
+  }
+
+  const idOf = (session) => String(session?.id ?? session?.header?.id ?? 'unknown')
+
+  function bufferOf(session) {
+    const id = idOf(session)
+    let buffer = buffers.get(id)
+    if (!buffer) {
+      buffer = { project: projectOf(session, cfg.defaultProject), user: '', assistant: [], tools: 0, turn: null }
+      buffers.set(id, buffer)
+    }
+    return { id, buffer }
+  }
+
+  function drop(id) {
+    buffers.delete(id)
+    const timer = timers.get(id)
+    if (timer) {
+      clearTimeout(timer)
+      timers.delete(id)
+    }
+  }
+
+  async function flush(id) {
+    const buffer = buffers.get(id)
+    if (!buffer) return
+    const toolCount = buffer.tools
+    const user = truncate(buffer.user, cfg.capture.userChars)
+    const assistant = truncate(buffer.assistant.join('\n'), cfg.capture.assistantChars)
+
+    // Every episode is anchored to something the user actually said. A turn with
+    // no user side is context noise, and one too short to mean anything — such as
+    // "ok" — would only fill the vault with lines the extractor cannot use.
+    if (user === '' || user.length + assistant.length < cfg.capture.minChars) {
+      drop(id)
+      return
+    }
+
+    drop(id)
+
+    const redactedUser = redactor.redact(user).text
+    const redactedAssistant = redactor.redact(assistant).text
+    await vault.appendEpisode({
+      t: nowIso(),
+      project: buffer.project,
+      session: id,
+      turn: buffer.turn,
+      user: redactedUser,
+      assistant: redactedAssistant,
+      ...(cfg.capture.includeToolOutput && toolCount > 0 ? { tools: toolCount } : {}),
+    })
+  }
+
+  function schedule(id) {
+    const existing = timers.get(id)
+    if (existing) clearTimeout(existing)
+    const timer = setTimeout(() => {
+      flush(id).catch(() => {})
+    }, FLUSH_AFTER_MS)
+    timer.unref?.()
+    timers.set(id, timer)
+  }
+
+  disposers.push(
+    ctx.on('session/event', (session, event) => {
+      // The switch is read here, not at registration: turning capture off in
+      // 设置 must stop writes immediately without unregistering the listener.
+      if (!cfg.capture.enabled) return
+
+      const type = event?.type
+
+      // A turn is the natural write unit: flush it as soon as it closes, so an
+      // episode exists even if the next turn never comes.
+      if (type === 'turn/end') {
+        const id = idOf(session)
+        const buffer = buffers.get(id)
+        if (buffer) {
+          if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+          flush(id).catch(() => {})
+        }
+        return
+      }
+
+      if (type !== 'user/message' && type !== 'assistant/message' && type !== 'tool/result') return
+
+      if (type === 'user/message') {
+        // The harness delivers runtime snapshots, skill catalogs, sampled time,
+        // approval notices and compaction checkpoints through the same channel as
+        // the person typing — and not always with a telling `source.kind`: a real
+        // runtime snapshot has arrived here tagged `user` (it was captured as if
+        // the person had typed it). So provenance can only *add* a skip, never
+        // veto the patterns; both are consulted, and delimited blocks come off
+        // first so a message that merely carried a reminder keeps its own words.
+        const kind = event?.data?.source?.kind
+        const text = stripInjectedBlocks(eventText(event))
+        const synthetic = (typeof kind === 'string' && kind !== 'user') || text === '' || injected(text)
+        if (synthetic) return
+
+        const id = idOf(session)
+        const open = buffers.get(id)
+        if (open && (open.user !== '' || open.assistant.length > 0)) {
+          // A turn that never closed (interrupted, or an older harness): keep it.
+          flush(id).catch(() => {})
+        }
+
+        const { buffer } = bufferOf(session)
+        buffer.user = text
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        schedule(id)
+        return
+      }
+
+      const { id, buffer } = bufferOf(session)
+
+      if (type === 'assistant/message') {
+        const text = eventText(event)
+        if (text !== '' && buffer.assistant.length < MAX_ASSISTANT_PARTS) buffer.assistant.push(text)
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        schedule(id)
+        return
+      }
+
+      buffer.tools += 1
+      schedule(id)
+    }),
+  )
+
+  return [
+    ...disposers,
+    () => {
+      for (const timer of timers.values()) clearTimeout(timer)
+      timers.clear()
+      for (const id of [...buffers.keys()]) flush(id).catch(() => {})
+    },
+  ]
+}

package/src/config.js

@@ -0,0 +1,280 @@
+/**
+ * Config defaults and normalisation.
+ *
+ * The Settings form is drawn from the schema in `src/schema.js`, but that form
+ * is a convenience, not the contract: every field is normalised here again, so a
+ * config written by hand in `cordis.patch.yml`, or one carrying a stale key from
+ * an older version, still resolves to a usable configuration.
+ *
+ * This is also the seam between the two config worlds. A field declared
+ * `.volatile()` arrives here as a live reference rather than a value; this module
+ * unwraps it, so everything downstream sees plain values, and re-resolving on
+ * `loader/volatile-update` turns a Settings write into a new snapshot.
+ */
+import os from 'node:os'
+import path from 'node:path'
+
+/** Credential shapes that must never reach a vault file. User rules are added to these. */
+export const DEFAULT_DENY_PATTERNS = [
+  'sk-ant-[A-Za-z0-9_-]{20,}',
+  'sk-[A-Za-z0-9_-]{24,}',
+  'ghp_[A-Za-z0-9]{20,}',
+  'github_pat_[A-Za-z0-9_]{20,}',
+  'glpat-[A-Za-z0-9_-]{16,}',
+  'xox[baprs]-[A-Za-z0-9-]{10,}',
+  'AKIA[0-9A-Z]{16}',
+  'AIza[0-9A-Za-z_-]{30,}',
+  '-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]*?-----END [A-Z ]*PRIVATE KEY-----',
+  '(?i)bearer\\s+[A-Za-z0-9._~+/-]{20,}={0,2}',
+  '(?i)(password|passwd|secret|api[_-]?key|access[_-]?token)\\s*[:=]\\s*["\']?\\S{6,}',
+]
+
+/**
+ * Text the harness injects into the conversation as a user message: compaction
+ * checkpoints, runtime-context snapshots, skill-catalog reminders. They are not
+ * user intent, and distilling them would manufacture memories out of nothing.
+ */
+export const DEFAULT_SKIP_PATTERNS = [
+  '^This is an automatically generated checkpoint',
+  '^Current runtime context\\.',
+  '<system-reminder>',
+]
+
+const DEFAULTS = {
+  enabled: true,
+  vaultDir: '',
+  /** Project tag used when a session has no usable cwd. */
+  defaultProject: 'shared',
+  /** Link new cards into project-level entity hubs so cross-project recall works. */
+  crossProject: true,
+  capture: {
+    enabled: true,
+    userChars: 1500,
+    assistantChars: 1500,
+    includeToolOutput: false,
+    minChars: 12,
+    skipPatterns: [...DEFAULT_SKIP_PATTERNS],
+  },
+  privacy: {
+    useDefaultPatterns: true,
+    denyPatterns: [],
+    redactEmails: true,
+    redactPaths: true,
+  },
+  extractor: {
+    enabled: false,
+    /**
+     * `harness` borrows a route the Settings → Models page already configured
+     * (provider, key, base URL, thinking level), so the extractor needs no
+     * credentials of its own. `http` posts to an OpenAI-compatible endpoint with
+     * the key below, for machines where no model is configured in Settings.
+     */
+    transport: 'harness',
+    /** harness: follow the model currently selected in Settings instead of provider/model. */
+    useCurrentModel: true,
+    /** harness: provider route id, e.g. `deepseek`, `wb`, `agy-local`. */
+    provider: '',
+    /** harness: thinking level for this call, when the route offers one. '' keeps the route default. */
+    reasoningEffort: '',
+    baseUrl: 'https://api.deepseek.com/v1',
+    path: '/chat/completions',
+    /**
+     * Empty by default: in harness mode the model comes from Settings, and an
+     * id left here would only be used with `useCurrentModel` off. http mode
+     * fills in `deepseek-chat` at normalisation time.
+     */
+    model: '',
+    apiKeyEnv: 'MEMORY_LLM_API_KEY',
+    apiKey: '',
+    maxOutputTokens: 3000,
+    temperature: 0.1,
+    timeoutMs: 90000,
+    maxEpisodesPerRun: 40,
+  },
+  retrieval: {
+    limit: 8,
+    hops: 1,
+    snippetChars: 220,
+    timelineLimit: 30,
+  },
+  /**
+   * The automatic distiller: two independent triggers that share one tick and
+   * one lock. Both default to off — a background model call is the user's
+   * decision, never the plugin's.
+   */
+  auto: {
+    enabled: false,
+    /** Undistilled-episode threshold; 0 turns the threshold rule off. */
+    minEpisodes: 0,
+    /** Minutes between runs; 0 turns the schedule rule off. */
+    everyMinutes: 0,
+    /** Never two automatic runs closer than this, whichever rule fired. */
+    minGapMinutes: 30,
+    /** `23:00-08:00` style window in which nothing runs. Empty means always. */
+    quietHours: '',
+    /** Project tag for automatic cards; empty uses the newest episode's project. */
+    project: '',
+  },
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
+
+/** True for the frozen reference a `.volatile()` leaf validates to, not for a value. */
+function isVolatileRef(value) {
+  return value !== null && typeof value === 'object' && VOLATILE_WRITE in value
+}
+
+/**
+ * Replace every volatile reference with the value it holds right now.
+ *
+ * A field marked `.volatile()` in `src/schema.js` does not validate to its value:
+ * it validates to a frozen `{ get() }` handle, and the settings page writes
+ * through that handle. Everything below this function — the defaults merge, the
+ * normalisation, and the caller's `cfg` — deals in plain values, so the refs are
+ * unwrapped at the one place config enters the plugin. `resolveConfig` runs again
+ * on every `loader/volatile-update`, which is how a Settings write becomes a
+ * fresh snapshot.
+ *
+ * This is also what makes `{ ...DEFAULTS, ...config }` safe: a ref is a plain
+ * object whose only own key is `get`, so merging without unwrapping would keep
+ * the defaults and drop the user's value without any error.
+ */
+export function unwrapConfig(value) {
+  if (isVolatileRef(value)) return unwrapConfig(value.get())
+  if (Array.isArray(value)) return value.map(unwrapConfig)
+  if (isPlainObject(value)) {
+    const out = {}
+    for (const [key, child] of Object.entries(value)) out[key] = unwrapConfig(child)
+    return out
+  }
+  return value
+}
+
+function merge(base, override) {
+  if (!isPlainObject(override)) return { ...base }
+  const out = { ...base }
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue
+    out[key] = isPlainObject(value) && isPlainObject(base[key]) ? merge(base[key], value) : value
+  }
+  return out
+}
+
+function expandHome(input) {
+  if (typeof input !== 'string' || input.trim() === '') return ''
+  const trimmed = input.trim()
+  if (trimmed === '~') return os.homedir()
+  if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) {
+    return path.join(os.homedir(), trimmed.slice(2))
+  }
+  return trimmed
+}
+
+function int(value, fallback, min, max) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return fallback
+  return Math.min(max, Math.max(min, Math.round(n)))
+}
+
+export function resolveConfig(raw) {
+  const cfg = merge(DEFAULTS, unwrapConfig(raw ?? {}))
+
+  const dir = expandHome(cfg.vaultDir)
+  cfg.vaultDir = dir === '' ? path.join(os.homedir(), 'dsh-memory') : path.resolve(dir)
+
+  cfg.capture.userChars = int(cfg.capture.userChars, 1500, 200, 20000)
+  cfg.capture.assistantChars = int(cfg.capture.assistantChars, 1500, 200, 20000)
+  cfg.capture.minChars = int(cfg.capture.minChars, 12, 0, 500)
+
+  cfg.retrieval.limit = int(cfg.retrieval.limit, 8, 1, 40)
+  cfg.retrieval.hops = int(cfg.retrieval.hops, 1, 0, 2)
+  cfg.retrieval.snippetChars = int(cfg.retrieval.snippetChars, 220, 60, 2000)
+  cfg.retrieval.timelineLimit = int(cfg.retrieval.timelineLimit, 30, 1, 200)
+
+  cfg.extractor.maxOutputTokens = int(cfg.extractor.maxOutputTokens, 3000, 256, 32000)
+  cfg.extractor.timeoutMs = int(cfg.extractor.timeoutMs, 90000, 5000, 600000)
+  cfg.extractor.maxEpisodesPerRun = int(cfg.extractor.maxEpisodesPerRun, 40, 1, 400)
+
+  cfg.privacy.denyPatterns = Array.isArray(cfg.privacy.denyPatterns)
+    ? cfg.privacy.denyPatterns.filter((p) => typeof p === 'string' && p.trim() !== '')
+    : []
+
+  // A user list replaces the defaults; drop anything that is not a usable regex
+  // rather than letting one typo disable capture for the whole session.
+  cfg.capture.skipPatterns = Array.isArray(cfg.capture.skipPatterns)
+    ? cfg.capture.skipPatterns.filter((p) => {
+        if (typeof p !== 'string' || p.trim() === '') return false
+        try {
+          new RegExp(p, 'i')
+          return true
+        } catch {
+          return false
+        }
+      })
+    : []
+
+  // Anything that is not the explicit escape hatch means the borrowed route:
+  // a stale or misspelled transport must not silently become an HTTP call that
+  // fails later for a missing key.
+  cfg.extractor.transport = cfg.extractor.transport === 'http' ? 'http' : 'harness'
+  cfg.extractor.useCurrentModel = cfg.extractor.useCurrentModel !== false
+  cfg.extractor.provider = String(cfg.extractor.provider || '').trim()
+  cfg.extractor.reasoningEffort = String(cfg.extractor.reasoningEffort || '').trim()
+  cfg.extractor.baseUrl = String(cfg.extractor.baseUrl || '').replace(/\/+$/, '')
+  cfg.extractor.path = String(cfg.extractor.path || '/chat/completions')
+  // In http mode `model` is an OpenAI model name with a sensible default; in
+  // harness mode it is an id that must be taken literally, so a cleared field
+  // stays empty and `resolveRoute` can say what is missing.
+  cfg.extractor.model =
+    cfg.extractor.transport === 'http' ? String(cfg.extractor.model || 'deepseek-chat') : String(cfg.extractor.model || '')
+  cfg.extractor.apiKeyEnv = String(cfg.extractor.apiKeyEnv || 'MEMORY_LLM_API_KEY')
+
+  cfg.auto.enabled = cfg.auto.enabled === true
+  cfg.auto.minEpisodes = int(cfg.auto.minEpisodes, 0, 0, 400)
+  cfg.auto.everyMinutes = int(cfg.auto.everyMinutes, 0, 0, 10080)
+  cfg.auto.minGapMinutes = int(cfg.auto.minGapMinutes, 30, 0, 1440)
+  cfg.auto.project = String(cfg.auto.project || '').trim()
+  // A malformed window must not disable the rule or, worse, silence it forever:
+  // parse what is parseable and fall back to "no quiet hours".
+  cfg.auto.quietHours = parseQuietHours(cfg.auto.quietHours) === null ? '' : String(cfg.auto.quietHours).trim()
+
+  return cfg
+}
+
+/**
+ * `23:00-08:00` → minute bounds for comparison; `null` when the text is unusable.
+ *
+ * Exported because the auto distiller and the Settings hint must agree on what
+ * counts as a valid window, and a window crossing midnight (start > end) is the
+ * common case, not an edge case.
+ */
+export function parseQuietHours(text) {
+  const raw = String(text ?? '').trim()
+  if (raw === '') return null
+  const match = /^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/u.exec(raw)
+  if (!match) return null
+  const [fromH, fromM, toH, toM] = match.slice(1).map(Number)
+  if (fromH > 23 || toH > 23 || fromM > 59 || toM > 59) return null
+  return { from: fromH * 60 + fromM, to: toH * 60 + toM }
+}
+
+export function paths(vaultDir) {
+  return {
+    root: vaultDir,
+    gitignore: path.join(vaultDir, '.gitignore'),
+    vaultJson: path.join(vaultDir, 'vault.json'),
+    readme: path.join(vaultDir, 'README.md'),
+    graph: path.join(vaultDir, 'graph.html'),
+    projects: path.join(vaultDir, 'projects.json'),
+    episodes: path.join(vaultDir, 'episodes'),
+    cards: path.join(vaultDir, 'cards'),
+    entities: path.join(vaultDir, 'entities'),
+    audit: path.join(vaultDir, 'audit'),
+    distillState: path.join(vaultDir, '.distill-state.json'),
+    autoState: path.join(vaultDir, '.auto-state.json'),
+  }
+}

package/src/distillapi.js

@@ -0,0 +1,30 @@
+/**
+ * The "distill now" door: one exact Fetch route that runs the same distillation
+ * `memory_distill` runs, so the panel's button and the model's tool cannot drift
+ * apart. The run itself — and the one-run-at-a-time lock — live in
+ * `src/distillrun.js`, because the automatic distiller fires through the same
+ * door.
+ *
+ * This module only translates: a report becomes a 200 (including the reports that
+ * say `ok: false`, because "the extractor is off" is an answer the panel prints,
+ * not a failure it has to explain), and an unexpected throw becomes a 500.
+ */
+import { json } from './http.js'
+
+export const DISTILL_PATH = '/api/memory-graph.distill'
+
+/** 200 for an answer (including a refusal), 500 only for a crash. */
+function respond(report) {
+  const { failed, ...rest } = report
+  return json(rest, failed === true ? 500 : 200)
+}
+
+export function createDistillHandler({ getRunner }) {
+  return async function handleDistill() {
+    const runner = getRunner()
+    if (typeof runner?.run !== 'function') {
+      return json({ ok: false, reason: 'unavailable', message: 'the distiller is not available' }, 500)
+    }
+    return respond(await runner.run())
+  }
+}

package/src/distillrun.js

@@ -0,0 +1,106 @@
+/**
+ * One distillation, shared by the three ways to ask for it: the tool, the
+ * panel's button, and the automatic distiller.
+ *
+ * The lock lives here and nowhere else. Two of those three can fire without
+ * anyone watching — a scheduled tick and a pressed button can land in the same
+ * second — and a distillation spends real model budget while advancing one
+ * cursor in the vault. So the second caller is told the first is running; it is
+ * never queued and never runs concurrently.
+ */
+import { distill as runDistill } from './extract.js'
+
+/** How many written cards a caller gets to list before it just shows a count. */
+const CARD_LIMIT = 40
+
+export function createDistillRunner(options) {
+  const {
+    getVault,
+    getConfig,
+    getRedactor,
+    getServices = () => ({}),
+    // Injected so the tests can drive the success/failure paths without a model.
+    distill = runDistill,
+    // Rendering the vault's own views (graph.html, README) is best effort: the
+    // cards are already on disk, and the next write renders them again.
+    refreshViews = () => {},
+    log = () => {},
+  } = options ?? {}
+
+  let inflight = null
+
+  /** True while a run is in flight — the auto ticker asks before counting. */
+  function busy() {
+    return inflight !== null
+  }
+
+  /**
+   * Run one distillation. Always resolves with a report, never throws: an
+   * extractor that is switched off, a vault with nothing new and a model call
+   * that blew up are all answers a caller has to print, not exceptions it has to
+   * catch three different ways.
+   */
+  function run({ project, dryRun = false, signal } = {}) {
+    if (inflight) {
+      return Promise.resolve({ ok: false, busy: true, reason: 'A distillation is already running.' })
+    }
+
+    const task = (async () => {
+      try {
+        const report = await distill({
+          cfg: getConfig(),
+          vault: getVault(),
+          redactor: getRedactor(),
+          project,
+          dryRun,
+          signal,
+          ...getServices(),
+        })
+        const cards = (report.cards ?? report.proposed ?? []).slice(0, CARD_LIMIT).map((card) => ({
+          id: card.id ?? null,
+          kind: String(card.kind ?? 'note'),
+          title: String(card.title ?? ''),
+          deduped: Boolean(card.deduped),
+        }))
+        if (report.ok && (report.written ?? 0) > 0) {
+          try {
+            await refreshViews()
+          } catch (error) {
+            log('warn', `distilled, but a vault view did not render: ${error?.message ?? error}`)
+          }
+        }
+        return {
+          ok: Boolean(report.ok),
+          busy: false,
+          dryRun: Boolean(report.dryRun ?? dryRun),
+          episodes: report.episodes ?? 0,
+          written: report.written ?? 0,
+          remaining: report.remaining ?? 0,
+          cards,
+          batches: report.batches ?? null,
+          model: report.model ?? null,
+          keySource: report.keySource ?? null,
+          usage: report.usage ?? null,
+          skipped: report.skipped ?? null,
+          reason: report.reason ?? null,
+        }
+      } catch (error) {
+        log('warn', `distillation failed: ${error?.message ?? error}`)
+        return {
+          ok: false,
+          busy: false,
+          failed: true,
+          reason: 'unavailable',
+          message: String(error?.message ?? error),
+        }
+      }
+    })()
+
+    inflight = task
+    return task.finally(() => {
+      if (inflight === task) inflight = null
+    })
+  }
+
+  return { run, busy }
+}