mixdog 0.7.1

package/src/shared/config.mjs

@@ -0,0 +1,350 @@
+/**
+ * Unified config reader/writer.
+ * Single file: mixdog-config.json with sections: channels, agent, memory, search.
+ */
+import { readFileSync, mkdirSync, existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { createRequire } from 'module'
+import { resolvePluginData } from './plugin-paths.mjs'
+import { renameWithRetrySync, writeJsonAtomicSync, withFileLockSync } from './atomic-file.mjs'
+import {
+  backupUserData,
+  markUserDataInitialized,
+  loadLatestMixdogConfigFromBackup,
+  hasUserDataInitMarker,
+} from './user-data-guard.mjs'
+
+const _require = createRequire(import.meta.url)
+const { getSecret: _getSecret, setSecret: _setSecret, deleteSecret: _deleteSecret } = _require('../../lib/keychain-cjs.cjs')
+
+const DATA_DIR = resolvePluginData()
+
+const CONFIG_PATH = join(DATA_DIR, 'mixdog-config.json')
+
+const GENERATED_KEY = '_generated'
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function stripGeneratedMarker(data) {
+  if (!isPlainObject(data) || !Object.prototype.hasOwnProperty.call(data, GENERATED_KEY)) return data
+  const { [GENERATED_KEY]: _generated, ...rest } = data
+  return rest
+}
+
+function readJsonFile(path) {
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    // Fail closed on unknown read errors (EACCES, EIO, …). Returning {}
+    // here would let a subsequent writeSection() serialize an empty
+    // object back over an existing-but-temporarily-unreadable config and
+    // erase every other section. Better to surface the read error and
+    // abort the RMW than silently destroy data.
+    process.stderr.write(`[config] readJsonFile: unexpected read error for ${path}: ${err.message}\n`)
+    throw err
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    // Quarantine a malformed mixdog-config.json so the next boot starts fresh
+    // instead of looping on a broken file.
+    if (path === CONFIG_PATH) {
+      const corrupt = `${path}.corrupt-${Date.now()}`
+      try { renameWithRetrySync(path, corrupt) } catch {}
+      process.stderr.write(`[config] mixdog-config.json is malformed (${err.message}). Renamed to ${corrupt}. Restore it or delete to start fresh.\n`)
+    }
+    return null
+  }
+}
+
+function writeJsonFile(path, data) {
+  // R4 data-at-rest: mixdog-config.json holds provider apiKeys; clamp to
+  // owner-only on POSIX via 0o600/0o700 mode bits, AND fail-closed on
+  // Windows where those bits are advisory — `secret: true` makes the
+  // atomic writer apply an owner-only NTFS ACL (icacls) to the file,
+  // temp, lock, and parent dir, throwing if the ACL cannot be enforced
+  // so the key is never left world-readable. 0o700 on the parent dir
+  // restricts directory traversal in shared-home setups on POSIX.
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  // NOTE: lock:false here — callers that perform read-modify-write
+  // (writeSection/updateSection) hold the lock at the outer RMW
+  // boundary, so the inner write must not try to re-acquire the same
+  // lock file (would self-deadlock on `openSync('wx')`). Direct
+  // whole-config writers go through `writeAllLocked` below.
+  if (path === CONFIG_PATH) {
+    try { backupUserData(DATA_DIR, 'pre-config-write') } catch {}
+  }
+  writeJsonAtomicSync(path, data, { lock: false, fsyncDir: true, mode: 0o600, secret: true })
+  if (path === CONFIG_PATH) {
+    try { markUserDataInitialized(DATA_DIR) } catch {}
+    try { backupUserData(DATA_DIR, 'post-config-write') } catch {}
+  }
+}
+
+function readAll() {
+  const parsed = readJsonFile(CONFIG_PATH)
+  if (parsed != null) return parsed
+  // Symmetric with readAllForRmW(): a missing/unreadable config on a data
+  // dir that was previously initialized means the file was LOST (deleted,
+  // failed write), not a fresh install. Self-heal from the newest
+  // structurally-complete backup instead of silently collapsing to {} —
+  // which callers (readSection/getCapabilities) merge with in-memory
+  // defaults, dropping the user's presets/roles/sections. In-memory only:
+  // readAll() runs OUTSIDE the config lock (unlike the RMW path), so we do
+  // not write here to avoid an unlocked-write race; the next writeSection
+  // re-persists the file under the lock.
+  if (hasUserDataInitMarker(DATA_DIR)) {
+    const restored = loadLatestMixdogConfigFromBackup(DATA_DIR)
+    if (restored && isPlainObject(restored)) {
+      process.stderr.write('[config] read: restored mixdog-config.json from latest user-data backup (missing after init)\n')
+      return restored
+    }
+  }
+  return {}
+}
+
+function quarantineMalformedConfig(parseErr) {
+  const corrupt = `${CONFIG_PATH}.corrupt-${Date.now()}`
+  try {
+    if (existsSync(CONFIG_PATH)) renameWithRetrySync(CONFIG_PATH, corrupt)
+  } catch {}
+  process.stderr.write(
+    `[config] mixdog-config.json is malformed (${parseErr.message}). Renamed to ${corrupt}. Restore it or delete to start fresh.\n`,
+  )
+}
+
+function restoreAllForRmWOrThrow(reason) {
+  const restored = loadLatestMixdogConfigFromBackup(DATA_DIR)
+  if (restored && isPlainObject(restored)) {
+    process.stderr.write(`[config] RMW read: restored mixdog-config.json from latest user-data backup (${reason})\n`)
+    return restored
+  }
+  throw new Error(
+    `[config] mixdog-config.json is unreadable and no valid backup was found (${reason}); refusing section write that would wipe other sections`,
+  )
+}
+
+/**
+ * Read-modify-write baseline. ENOENT on a never-initialized data dir → {}.
+ * Malformed on-disk config (or missing config after prior init) → restore
+ * from backup or throw; never silently collapse to a one-section overwrite.
+ */
+function readAllForRmW() {
+  let raw
+  try {
+    raw = readFileSync(CONFIG_PATH, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      if (hasUserDataInitMarker(DATA_DIR)) {
+        return restoreAllForRmWOrThrow('config file missing after user-data was initialized')
+      }
+      return {}
+    }
+    process.stderr.write(`[config] readAllForRmW: unexpected read error for ${CONFIG_PATH}: ${err.message}\n`)
+    throw err
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    if (!isPlainObject(parsed)) throw new SyntaxError('config root must be a JSON object')
+    return parsed
+  } catch (parseErr) {
+    quarantineMalformedConfig(parseErr)
+    return restoreAllForRmWOrThrow(parseErr.message)
+  }
+}
+
+function writeAll(data) {
+  writeJsonFile(CONFIG_PATH, data)
+}
+
+// Serialize a read-modify-write under the same file lock. Concurrent
+// processes used to race here: each read the old config, each computed
+// `all[section] = …`, each atomic-wrote — the later writer would
+// silently clobber the earlier section update. Holding the lock across
+// read+modify+write keeps RMW linearizable.
+function withConfigLock(fn) {
+  // secret:true clamps the lock file (which sits beside the API-key
+  // config in a possibly shared home dir) to an owner-only ACL on win32,
+  // fail-closed. POSIX is unaffected.
+  return withFileLockSync(`${CONFIG_PATH}.lock`, fn, { secret: true })
+}
+
+export function readSection(section) {
+  return stripGeneratedMarker(readAll()[section] ?? null) ?? {}
+}
+
+export function writeSection(section, data) {
+  withConfigLock(() => {
+    const all = readAllForRmW()
+    all[section] = stripGeneratedMarker(data)
+    writeAll(all)
+  })
+}
+
+export function updateSection(section, updater) {
+  withConfigLock(() => {
+    const all = readAllForRmW()
+    const current = stripGeneratedMarker(all[section] || {})
+    all[section] = stripGeneratedMarker(typeof updater === 'function' ? updater(current) : updater)
+    writeAll(all)
+  })
+}
+
+// ── Capabilities (B2 central path policy) ───────────────────────────
+// Top-level `capabilities` section in mixdog-config.json. Safe defaults
+// win on missing/malformed input — every cap is OFF unless explicitly
+// enabled. Settings round-trip through the setup UI; the in-process
+// path gate reads them via `getCapabilities()`.
+//
+// homeAccess: when true, file tools may write anywhere under $HOME. When
+// false (default), file tools are cwd-scoped — matches the setup UI's
+// out-of-the-box "OFF" toggle so a fresh install is restrictive until the
+// user explicitly opts in. This ONLY controls the main-agent path gate —
+// bridge role Edit/Write to HOME paths always go through Discord approval
+// regardless (enforced in hooks/pre-tool-subagent.cjs).
+const CAPABILITY_DEFAULTS = Object.freeze({ homeAccess: false })
+
+function readCapabilities() {
+  const raw = readAll().capabilities
+  const out = { ...CAPABILITY_DEFAULTS }
+  if (raw && typeof raw === 'object') {
+    if (raw.homeAccess === true) out.homeAccess = true
+    else if (raw.homeAccess === false) out.homeAccess = false
+  }
+  return out
+}
+
+// Convenience alias requested by B2 call-site plumbing. Returns the
+// same object shape as readCapabilities(); callers that only need a
+// boolean can read `.homeAccess` directly.
+export function getCapabilities() {
+  return readCapabilities()
+}
+
+// ── Secret account names ─────────────────────────────────────────────────────
+// Canonical account strings stored in the OS keychain. Must stay in sync with
+// the migration logic in seed.mjs.
+export const SECRET_ACCOUNTS = Object.freeze({
+  discordToken: 'discord.token',
+  webhookAuth:  'webhook.authtoken',
+  searchApiKey: (provider) => `search.${provider}.apiKey`,
+  agentApiKey:  (provider) => `agent.${provider}.apiKey`,
+})
+
+export function isDiscordSnowflake(value) {
+  return /^\d{17,20}$/.test(String(value || '').trim())
+}
+
+export function diagnoseDiscordTokenValue(value, config = {}) {
+  const token = String(value || '').trim()
+  if (!token) return null
+  const discord = config?.discord && typeof config.discord === 'object' ? config.discord : {}
+  const appId = String(discord.applicationId || '').trim()
+  if (appId && token === appId) return 'Bot token field contains the Application ID, not the bot token.'
+  const channels = config?.channelsConfig && typeof config.channelsConfig === 'object' ? config.channelsConfig : {}
+  for (const ch of Object.values(channels)) {
+    const channelId = String(ch?.channelId || '').trim()
+    if (channelId && token === channelId) return 'Bot token field contains a Channel ID, not the bot token.'
+  }
+  if (isDiscordSnowflake(token)) return 'Bot token field contains a numeric Discord ID, not the bot token.'
+  return null
+}
+
+// ── Secret-aware getters ─────────────────────────────────────────────────────
+// Read order: ENV MIXDOG_<UPPER_SNAKE> → OS keychain → null.
+
+function _envKey(account) {
+  // 'discord.token' → 'MIXDOG_DISCORD_TOKEN'
+  return 'MIXDOG_' + account.replace(/[.\s]+/g, '_').toUpperCase()
+}
+
+function _readSecret(account) {
+  const envVal = process.env[_envKey(account)]
+  if (envVal) return envVal
+  try { return _getSecret(account) } catch { return null }
+}
+
+/**
+ * Returns the Discord bot token.
+ * Priority: MIXDOG_DISCORD_TOKEN → keychain('discord.token') → null
+ */
+export function getDiscordToken() {
+  return _readSecret(SECRET_ACCOUNTS.discordToken)
+}
+
+/**
+ * Returns the ngrok/webhook authtoken.
+ * Priority: MIXDOG_WEBHOOK_AUTHTOKEN → keychain('webhook.authtoken') → null
+ */
+export function getWebhookAuthtoken() {
+  return _readSecret(SECRET_ACCOUNTS.webhookAuth)
+}
+
+const SEARCH_PROVIDERS = ['firecrawl', 'tavily', 'exa']
+
+/**
+ * Returns the API key for a search provider.
+ * Priority: MIXDOG_SEARCH_<PROVIDER>_APIKEY → keychain('search.<provider>.apiKey') → null
+ */
+export function getSearchApiKey(provider) {
+  if (!SEARCH_PROVIDERS.includes(provider)) return null
+  return _readSecret(SECRET_ACCOUNTS.searchApiKey(provider))
+}
+
+// Standard provider env names take precedence so existing OPENAI_API_KEY-style
+// exports keep working, then MIXDOG_AGENT_<P>_APIKEY, then the OS keychain.
+const AGENT_PROVIDER_ENV = Object.freeze({
+  openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY',
+  deepseek: 'DEEPSEEK_API_KEY', xai: 'XAI_API_KEY', nvidia: 'NVIDIA_API_KEY',
+})
+
+// Last-resort env aliases honored AFTER the standard env / MIXDOG_AGENT_* /
+// keychain sources. GROK_API_KEY is the established xAI alias elsewhere in the
+// repo (search discovery, xai-api/grok-oauth backends), so honoring it here
+// keeps provider discovery and dispatch resolving the same credential.
+const AGENT_PROVIDER_ENV_ALIASES = Object.freeze({
+  xai: ['GROK_API_KEY'],
+})
+
+/**
+ * Returns the API key for an agent provider.
+ * Priority: <PROVIDER>_API_KEY env -> MIXDOG_AGENT_<PROVIDER>_APIKEY -> keychain('agent.<provider>.apiKey') -> alias env (e.g. GROK_API_KEY for xai) -> null.
+ * Never reads mixdog-config.json — provider keys are keychain-only.
+ */
+export function getAgentApiKey(provider) {
+  const std = AGENT_PROVIDER_ENV[provider]
+  if (std && process.env[std]) return process.env[std]
+  const fromStore = _readSecret(SECRET_ACCOUNTS.agentApiKey(provider))
+  if (fromStore) return fromStore
+  for (const alias of AGENT_PROVIDER_ENV_ALIASES[provider] || []) {
+    if (process.env[alias]) return process.env[alias]
+  }
+  return null
+}
+
+/**
+ * Persist a secret to the OS keychain. Throws on failure.
+ * Never writes to mixdog-config.json.
+ */
+export function saveSecret(account, value) {
+  _setSecret(account, value)
+}
+
+export function deleteSecret(account) {
+  _deleteSecret(account)
+}
+
+/**
+ * Whether a secret is stored in the OS keychain for `account` (ignores env).
+ * Lets the setup UI show "Set" WITHOUT ever sending the secret value to the
+ * browser.
+ */
+export function hasStoredSecret(account) {
+  try { return !!_getSecret(account) } catch { return false }
+}
+
+export { CONFIG_PATH }

package/src/shared/daemon-recycle.mjs

@@ -0,0 +1,108 @@
+// Daemon recycle barrier — closes the dev-sync full-restart "stale-serving"
+// race.
+//
+// When dev-sync runs in-band (invoked from inside the live daemon's bash
+// tool) it cannot kill the shared daemon synchronously — that would sever
+// its own process before the response flushes. It instead SCHEDULES a
+// detached kill a couple seconds out and returns immediately. During that
+// kill-delay plus the supervisor's respawn time the OLD daemon stays alive
+// and keeps accepting work, so a bridge worker spawned in that window binds
+// to about-to-die, stale-code/schema daemon (observed: a worker received a
+// pre-edit tool schema right after a forced restart).
+//
+// Fix: at kill-schedule time dev-sync writes a sentinel naming the EXACT
+// daemon being recycled by its (server_pid, server_started_at) identity.
+// The bridge spawn-admission path refuses to start a worker while the live
+// advert still names that same daemon, so the dispatch is deferred to the
+// fresh daemon instead of served stale. This is identity-based, not a timer:
+// the gate compares the sentinel against the current advert, and the moment
+// the fresh daemon rewrites the advert with a new server_pid the match
+// breaks and spawns resume — no clock, no heuristic window. server_started_at
+// guards the rare case of an OS PID reuse aliasing the fresh daemon onto the
+// doomed identity.
+//
+// Neutral location (src/shared) so both the agent orchestrator (spawn gate)
+// and the dev-sync script (sentinel writer) import the SAME path + schema —
+// the agent layer never imports the channels layer where the rest of the
+// runtime-state lives.
+
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+
+// Mirror runtime-paths.mjs RUNTIME_ROOT resolution so the sentinel lands
+// alongside active-instance.json regardless of MIXDOG_RUNTIME_ROOT override.
+const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
+  ? resolve(process.env.MIXDOG_RUNTIME_ROOT)
+  : join(tmpdir(), 'mixdog');
+const RECYCLE_FILE = join(RUNTIME_ROOT, 'daemon-recycle.json');
+const ACTIVE_INSTANCE_FILE = join(RUNTIME_ROOT, 'active-instance.json');
+
+function _readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return null; }
+}
+
+function _pid(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function readDaemonRecycleSentinel() {
+  return _readJson(RECYCLE_FILE);
+}
+
+// Called by dev-sync when it schedules a forced daemon (server_pid) kill.
+// The full (server_pid, server_started_at) identity is REQUIRED: a sentinel
+// without a verifiable start time could falsely block a PID-reused fresh
+// daemon, so we decline to arm the barrier rather than arm it partially
+// (degrades to prior behavior — no heuristic PID-only match).
+function writeDaemonRecycleSentinel({ doomedServerPid, doomedServerStartedAt } = {}) {
+  const pid = _pid(doomedServerPid);
+  const startedAt = Number(doomedServerStartedAt);
+  if (pid === null || !Number.isFinite(startedAt)) return false;
+  try {
+    if (!existsSync(RUNTIME_ROOT)) mkdirSync(RUNTIME_ROOT, { recursive: true });
+    // Atomic publish: write a temp file then rename, so a concurrent
+    // isCurrentDaemonDoomed() never observes a partial/empty sentinel and
+    // falsely allows a spawn on the doomed daemon. Mirrors active-instance.json.
+    const tmp = `${RECYCLE_FILE}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ doomedServerPid: pid, doomedServerStartedAt: startedAt }));
+    renameSync(tmp, RECYCLE_FILE);
+    return true;
+  } catch { return false; }
+}
+
+function clearDaemonRecycleSentinel() {
+  try { if (existsSync(RECYCLE_FILE)) rmSync(RECYCLE_FILE, { force: true }); }
+  catch { /* best-effort */ }
+}
+
+// True when the live advert (this daemon's own active-instance.json) names
+// the daemon dev-sync flagged for recycle. PID identity is primary; when the
+// sentinel recorded server_started_at it must also match the advert so a
+// reused PID cannot alias a freshly-booted daemon onto the doomed identity.
+// Reads nothing when no sentinel exists (the common case) — one stat/read.
+function isCurrentDaemonDoomed() {
+  const recycle = readDaemonRecycleSentinel();
+  if (!recycle) return false;
+  const advert = _readJson(ACTIVE_INSTANCE_FILE);
+  if (!advert) return false;
+  const doomedPid = _pid(recycle.doomedServerPid);
+  const curPid = _pid(advert.server_pid);
+  if (doomedPid === null || curPid === null || doomedPid !== curPid) return false;
+  // Strict (server_pid, server_started_at) identity — no PID-only fallback,
+  // so a reused PID on a fresh daemon (different start time) never matches.
+  const doomedStart = Number(recycle.doomedServerStartedAt);
+  const curStart = Number(advert.server_started_at);
+  return Number.isFinite(doomedStart) && Number.isFinite(curStart) && doomedStart === curStart;
+}
+
+export {
+  RECYCLE_FILE,
+  ACTIVE_INSTANCE_FILE,
+  readDaemonRecycleSentinel,
+  writeDaemonRecycleSentinel,
+  clearDaemonRecycleSentinel,
+  isCurrentDaemonDoomed,
+};

package/src/shared/disable-claude-builtins.mjs

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import { writeFileAtomicSync } from './atomic-file.mjs';
+import { getBackupRoot } from './user-data-guard.mjs';
+
+// On FIRST install only (gated by the caller via the fresh creation of
+// mixdog-config.json), disable Claude Code's built-in auto-memory and away
+// summary so mixdog's own memory/recap is authoritative. The user's prior
+// values are captured to an install-restore snapshot first so the original
+// behaviour can be restored. The createOnly gate in seed.mjs guarantees this
+// runs exactly once, so we never reapply on later boots.
+
+// Settings path is a parameter (defaulting to ~/.claude/settings.json) so it
+// can be redirected via MIXDOG_CLAUDE_SETTINGS_PATH for testing without a real
+// homedir.
+export function resolveClaudeSettingsPath() {
+  return process.env.MIXDOG_CLAUDE_SETTINGS_PATH
+    || join(homedir(), '.claude', 'settings.json');
+}
+
+function readJsonOrNull(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Disable Claude Code's built-in memory/recap on first install. Best-effort:
+ * any failure is warned to stderr and swallowed so seeding is never broken.
+ *
+ * @param {string} settingsPath  path to settings.json (default ~/.claude/settings.json)
+ * @returns {{ snapshot: boolean, merged: boolean }}
+ */
+export function disableClaudeBuiltinsOnFirstInstall(settingsPath = resolveClaudeSettingsPath()) {
+  const result = { snapshot: false, merged: false };
+  try {
+    let settings = {};
+    if (existsSync(settingsPath)) {
+      // File exists: parse it. An unparseable existing file may hold raw,
+      // hand-fixable user content — never overwrite it. Warn and skip the
+      // whole merge (no reliable priors → no snapshot either). Only a truly
+      // missing file is treated as `{}` and gets the disable flags written.
+      const parsed = readJsonOrNull(settingsPath);
+      if (parsed === null) {
+        process.stderr.write(`[seed] claude settings.json at ${settingsPath} is unparseable; leaving untouched\n`);
+        return result;
+      }
+      // Valid JSON with a non-object top level (array/string/number) also
+      // holds user content we cannot merge into — skip, same as unparseable.
+      if (!isPlainObject(parsed)) {
+        process.stderr.write(`[seed] claude settings.json at ${settingsPath} is not a JSON object; leaving untouched\n`);
+        return result;
+      }
+      settings = parsed;
+    }
+
+    // 1. Restore snapshot FIRST, capturing prior values (null when absent).
+    const snapshotPath = join(getBackupRoot(), 'install-restore', 'claude-settings-original.json');
+    if (!existsSync(snapshotPath)) {
+      const snapshot = {
+        autoMemoryEnabled: Object.prototype.hasOwnProperty.call(settings, 'autoMemoryEnabled')
+          ? settings.autoMemoryEnabled : null,
+        awaySummaryEnabled: Object.prototype.hasOwnProperty.call(settings, 'awaySummaryEnabled')
+          ? settings.awaySummaryEnabled : null,
+        capturedAt: new Date().toISOString(),
+      };
+      mkdirSync(dirname(snapshotPath), { recursive: true });
+      writeFileAtomicSync(snapshotPath, JSON.stringify(snapshot, null, 2) + '\n', { fsyncDir: true });
+      result.snapshot = true;
+    }
+
+    // 2. Merge the disables, preserving all other keys, atomic write.
+    const merged = { ...settings, autoMemoryEnabled: false, awaySummaryEnabled: false };
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileAtomicSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', { fsyncDir: true });
+    result.merged = true;
+  } catch (e) {
+    process.stderr.write(`[seed] disable claude built-ins failed: ${e.message}\n`);
+  }
+  return result;
+}

package/src/shared/err-text.mjs

@@ -0,0 +1,12 @@
+export function errText(e) {
+  if (e == null) return String(e);
+  if (typeof e === 'string') return e;
+  if (e instanceof Error) return e.message || e.name || String(e);
+  // ErrorEvent / event-like / plain object (NOT instanceof Error)
+  if (typeof e.message === 'string' && e.message) return e.message;
+  if (e.error != null && e.error !== e) return errText(e.error);
+  if (e.reason != null && e.reason !== e) return errText(e.reason);
+  if (typeof e.type === 'string' && e.type) return `${e.type} event`;
+  try { const j = JSON.stringify(e); if (j && j !== '{}' && j !== 'null') return j; } catch {}
+  return String(e);
+}

package/src/shared/llm/cost.mjs

@@ -0,0 +1,66 @@
+/**
+ * Per-call cost estimator for bridge-trace usage rows.
+ *
+ * Pricing is pulled from the LiteLLM catalog (already warmed by providers/
+ * agent bootstrap). All four token slots — input / output / cacheRead /
+ * cacheWrite — are multiplied by their matching $/M rate from the catalog
+ * and summed. Missing rates are treated as 0 (no extrapolation).
+ *
+ * The catalog is looked up synchronously: if it has not been warmed yet
+ * (fresh process, first call), this returns 0 without blocking. The next
+ * call will pick up the cache.
+ */
+
+import { getModelMetadataSync } from '../../agent/orchestrator/providers/model-catalog.mjs';
+
+// OpenAI / Codex / Gemini report `input_tokens` as the total prompt token
+// count *including* the cached portion (inclusive). Anthropic reports the
+// uncached remainder only and bills cached_read / cached_write as separate
+// additive slots (additive). Cost and prompt-total math has to branch on this.
+// OpenAI-compatible direct providers (deepseek / nvidia / ollama / lmstudio)
+// go through the OpenAI SDK and likewise report an inclusive prompt_tokens
+// with a separate cached-tokens detail — so they are inclusive too. Omitting
+// them bills the cached portion at the full input rate AND re-adds it as a
+// cacheRead slot, double-billing the cache (e.g. a ~10k-token cached system
+// prompt charged ~25x its real cost on every DeepSeek call).
+export function isInclusiveProvider(provider) {
+    if (!provider) return false;
+    const p = String(provider).toLowerCase();
+    // 'grok' covers grok-oauth, which delegates inference to the xai compat
+    // provider (inclusive input_tokens) but reports its own provider id on
+    // usage rows — without it, cached tokens would be double-billed in the
+    // cost fallback and prompt totals.
+    return p.includes('openai') || p.includes('codex') || p.includes('gemini') || p.includes('google') || p.includes('xai') || p.includes('grok')
+        || p.includes('deepseek') || p.includes('nvidia') || p.includes('ollama') || p.includes('lmstudio') || p.includes('groq') || p.includes('openrouter');
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.model
+ * @param {string} [args.provider]
+ * @param {number} [args.inputTokens]
+ * @param {number} [args.outputTokens]
+ * @param {number} [args.cacheReadTokens]
+ * @param {number} [args.cacheWriteTokens]
+ * @returns {number} USD, rounded to 6 decimal places.
+ */
+export function computeCostUsd(args) {
+    const meta = getModelMetadataSync(args?.model);
+    if (!meta) return 0;
+    const inputTokens = args.inputTokens || 0;
+    const outputTokens = args.outputTokens || 0;
+    const cacheReadTokens = args.cacheReadTokens || 0;
+    const cacheWriteTokens = args.cacheWriteTokens || 0;
+    const billableInput = isInclusiveProvider(args.provider)
+        ? Math.max(inputTokens - cacheReadTokens - cacheWriteTokens, 0)
+        : inputTokens;
+    const parts = [
+        billableInput * (meta.inputCostPerM || 0),
+        outputTokens * (meta.outputCostPerM || 0),
+        cacheReadTokens * (meta.cacheReadCostPerM || 0),
+        cacheWriteTokens * (meta.cacheWriteCostPerM || 0),
+    ];
+    const total = parts.reduce((s, x) => s + x, 0) / 1_000_000;
+    if (!Number.isFinite(total) || total <= 0) return 0;
+    return Number(total.toFixed(6));
+}