mio-agent-runtime 0.5.15 → 0.5.17

package/bin/mio.js

@@ -1,478 +1,477 @@
-#!/usr/bin/env node
-'use strict'
-
+#!/usr/bin/env node
+'use strict'
+
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
-const { spawnSync, spawn } = require('child_process')
-
-const SERVER_SCRIPT = path.resolve(__dirname, '..', 'server', 'mio-intelligence-mcp', 'index.js')
-const SERVER_SCRIPT_DASH = path.resolve(__dirname, '..', 'server', 'mio-intelligence-mcp', 'dashboard-server.js')
-const DASH_PORT = 8787
-const MIO_HOME = process.env.MIO_HOME || path.join(os.homedir(), '.mio-intelligence')
-const CONFIG_FILE = path.join(MIO_HOME, 'config.json')
-
-const adapters = {
-  codex: require('../adapters/codex.js'),
-  opencode: require('../adapters/opencode.js'),
-  workbuddy: require('../adapters/workbuddy.js'),
-  hermes: require('../adapters/hermes.js'),
-}
+const { execFileSync } = require('child_process')
+
+const SERVER_SCRIPT = path.resolve(__dirname, '..', 'server', 'mio-intelligence-mcp', 'index.js')
+const MIO_HOME = process.env.MIO_HOME || path.join(os.homedir(), '.mio-intelligence')
+const CONFIG_FILE = path.join(MIO_HOME, 'config.json')
+
+const adapters = {
+  codex: require('../adapters/codex.js'),
+  opencode: require('../adapters/opencode.js'),
+  workbuddy: require('../adapters/workbuddy.js'),
+  hermes: require('../adapters/hermes.js'),
+}
 const observer = require('../observe/observer.js')
+const { getEvolutionStatus, formatEvolutionStatusText } = require('../server/runtime-modules.js')
+const { createEvolutionCutoverTools } = require('../server/evolution-cutover.js')
 
-function ensureHome() {
-  fs.mkdirSync(MIO_HOME, { recursive: true })
-  fs.mkdirSync(path.join(MIO_HOME, 'logs'), { recursive: true })
-}
-
-function readConfig() {
-  const fallback = { version: 1, home: MIO_HOME, agents: {} }
-  if (!fs.existsSync(CONFIG_FILE)) return fallback
-  try {
-    return { ...fallback, ...JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')) }
-  } catch (_) {
-    return fallback
-  }
+function appendJsonl(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.appendFileSync(file, `${JSON.stringify(value)}\n`, 'utf8')
 }
 
-function writeConfig(config) {
-  ensureHome()
-  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+function readJsonl(file) {
+  if (!fs.existsSync(file)) return []
+  return fs
+    .readFileSync(file, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch (_) {
+        return null
+      }
+    })
+    .filter(Boolean)
 }
 
-function jsonOrText(payload, useJson) {
-  if (useJson) {
-    console.log(JSON.stringify(payload, null, 2))
-    return
-  }
-  return payload
+function projectName() {
+  try {
+    const commonDir = execFileSync(
+      'git',
+      ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }
+    ).trim()
+    if (commonDir) return path.basename(path.dirname(commonDir))
+  } catch (_) {}
+  return path.basename(process.cwd())
 }
 
-function versionCommand() {
-  const pkg = require(path.resolve(__dirname, '..', 'package.json'))
-  console.log(pkg.version)
-}
+const evolutionCutover = createEvolutionCutoverTools({
+  dataDir: MIO_HOME,
+  appendJsonl,
+  readJsonl,
+  projectName,
+})
 
-function initCommand() {
-  ensureHome()
-  const config = readConfig()
-  if (!config.createdAt) config.createdAt = new Date().toISOString()
-  writeConfig(config)
-  console.log(`MIO_HOME ready: ${MIO_HOME}`)
+function optionValue(args, name) {
+  const index = args.indexOf(name)
+  if (index === -1) return undefined
+  return args[index + 1]
 }
 
-function statusCommand(useJson) {
-  const config = readConfig()
-  const codexRestart = adapters.codex.restartWarningMessage()
-  const opencodeRestart = adapters.opencode.restartWarningMessage()
-  const installed = {
-    codex: adapters.codex.isInstalled(),
-    opencode: adapters.opencode.isInstalled(),
-    workbuddy: adapters.workbuddy.isInstalled(),
-    hermes: adapters.hermes.isInstalled(),
-  }
-  const payload = {
-    version: config.version,
-    home: MIO_HOME,
-    serverScript: SERVER_SCRIPT,
-    serverScriptExists: fs.existsSync(SERVER_SCRIPT),
-    agents: config.agents || {},
-    codexInstalled: installed.codex,
-    opencodeInstalled: installed.opencode,
-    workbuddyInstalled: installed.workbuddy,
-    hermesInstalled: installed.hermes,
-    codexNeedsRestart: Boolean(codexRestart),
-    opencodeNeedsRestart: Boolean(opencodeRestart),
-    codexRestartHint: codexRestart,
-    opencodeRestartHint: opencodeRestart,
-    hermesObserverReady: fs.existsSync(observer.hermesDbPath()),
-    opencodeObserverReady: fs.existsSync(observer.opencodeDbPath()),
-    observerRunning: observer.isRunning(MIO_HOME),
-    observerPid: observer.isRunning(MIO_HOME) ? observer.readPid(MIO_HOME) : null,
-  }
-  if (useJson) {
-    jsonOrText(payload, true)
-    return
-  }
-  console.log(`MIO_HOME: ${MIO_HOME}`)
-  console.log(`MCP Server: ${SERVER_SCRIPT}`)
-  console.log(`Codex MCP: ${installed.codex ? 'installed' : 'not installed'}`)
-  if (codexRestart) console.log(`Codex app: running with an older Mio config - fully restart Codex to load it`)
-  console.log(`OpenCode MCP: ${installed.opencode ? 'installed' : 'not installed'}`)
-  if (opencodeRestart) console.log(`OpenCode Desktop: running with an older Mio config - restart it to load it`)
-  console.log(`OpenCode observer: ${fs.existsSync(observer.opencodeDbPath()) ? 'ready' : 'no database'}`)
-  console.log(`WorkBuddy MCP: ${installed.workbuddy ? 'installed' : 'not installed'}`)
-  console.log(`Hermes MCP: ${installed.hermes ? 'installed' : 'not installed'}`)
-  console.log(`Hermes observer: ${fs.existsSync(observer.hermesDbPath()) ? 'ready' : 'no database'}`)
-  console.log(`Observer: ${observer.isRunning(MIO_HOME) ? 'running (pid ' + observer.readPid(MIO_HOME) + ')' : 'not running'}`)
+function flagPresent(args, name) {
+  return args.includes(name)
 }
 
-function agentsCommand(useJson) {
-  const config = readConfig()
-  const agents = config.agents || {}
-  if (useJson) {
-    jsonOrText(agents, true)
-    return
-  }
-  const names = Object.keys(agents)
-  if (names.length === 0) {
-    console.log('No agents installed.')
-    return
-  }
-  for (const name of names) {
-    console.log(`${name}\t${agents[name].installedAt || ''}`)
-  }
-}
-
-function installCommand(host, useJson) {
-  if (!host) {
-    console.error('Usage: mio install <codex|opencode|workbuddy|hermes>')
-    process.exitCode = 1
-    return
-  }
-  const adapter = adapters[host]
-  if (!adapter) {
-    console.error(`Unknown host: ${host}`)
-    process.exitCode = 1
-    return
-  }
-  ensureHome()
-  const config = readConfig()
-  let result
+function parseJsonOption(args, name) {
+  const raw = optionValue(args, name)
+  if (raw === undefined) throw new Error(`${name} is required`)
   try {
-    result = adapter.install({
-      node: process.execPath,
-      serverScript: SERVER_SCRIPT,
-      home: MIO_HOME,
-      workspace: process.cwd(),
-    })
+    return JSON.parse(raw)
   } catch (error) {
-    console.error(`Failed to install ${host}: ${error.message || error}`)
-    process.exitCode = 1
-    return
+    throw new Error(`${name} must be valid JSON`)
   }
-  if (result.changed) {
-    config.agents = config.agents || {}
-    config.agents[host] = {
-      installedAt: new Date().toISOString(),
-      configPath: result.configPath || null,
-    }
-    writeConfig(config)
-  }
-  try {
-    observer.runCycle(MIO_HOME, observer.loadState(MIO_HOME), observer.createSinks(MIO_HOME))
-  } catch (_) {}
-  let observerStarted = false
-  try {
-    observerStarted = observer.startBackground(MIO_HOME).started
-  } catch (_) {}
-  if (useJson) {
-    result.observer = {
-      running: observer.isRunning(MIO_HOME),
-      started: observerStarted,
-    }
-    jsonOrText(result, true)
-    return
-  }
-  console.log(result.message || `${host} adapter completed.`)
-  console.log(
-    observer.isRunning(MIO_HOME)
-      ? 'Observer daemon running.'
-      : 'Observer daemon not running. Run `mio observe --start`.'
-  )
-}
-
-function mcpCommand() {
-  require(SERVER_SCRIPT)
 }
 
-function observeCommand(args) {
-  const flags = args.slice(1)
-  const useJson = flags.includes('--json')
-  if (flags.includes('--start')) {
-    const result = observer.startBackground(MIO_HOME)
-    if (useJson) return jsonOrText(result, true)
-    console.log(result.started ? 'Observer started.' : 'Observer already running.')
-    return
-  }
-  if (flags.includes('--stop')) {
-    const result = observer.stopBackground(MIO_HOME)
-    if (useJson) return jsonOrText(result, true)
-    console.log(result.stopped ? 'Observer stopped.' : 'Observer was not running.')
-    return
-  }
-  if (flags.includes('--status')) {
-    const running = observer.isRunning(MIO_HOME)
-    const pid = observer.readPid(MIO_HOME)
-    if (useJson) return jsonOrText({ running, pid }, true)
-    console.log(running ? 'Observer: running (pid ' + pid + ')' : 'Observer: not running')
-    return
-  }
-  if (flags.includes('--once')) {
-    const res = observer.runCycle(
-      MIO_HOME,
-      observer.loadState(MIO_HOME),
-      observer.createSinks(MIO_HOME)
-    )
-    if (useJson) return jsonOrText(res, true)
-    console.log('Observed files=' + res.files + ' lines=' + res.lines + ' outcomes=' + res.outcomes)
-    return
-  }
-  console.log('Observing WorkBuddy transcripts into ' + MIO_HOME + ' (Ctrl+C to stop)...')
-  observer.startForeground(MIO_HOME)
+function parseNumberOption(args, name) {
+  const raw = optionValue(args, name)
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  if (!Number.isFinite(value)) throw new Error(`${name} must be a number`)
+  return value
 }
 
-function uninstallCommand(host, useJson) {
-  if (!host) {
-    console.error('Usage: mio uninstall <codex|opencode|workbuddy|hermes>')
-    process.exitCode = 1
-    return
-  }
-  const adapter = adapters[host]
-  if (!adapter) {
-    console.error(`Unknown host: ${host}`)
-    process.exitCode = 1
-    return
-  }
-  let result
-  try {
-    result = adapter.uninstall({
-      node: process.execPath,
-      serverScript: SERVER_SCRIPT,
-      home: MIO_HOME,
-      workspace: process.cwd(),
-    })
-  } catch (error) {
-    console.error(`Failed to uninstall ${host}: ${error.message || error}`)
-    process.exitCode = 1
-    return
-  }
-  if (result.changed) {
-    const config = readConfig()
-    if (config.agents && config.agents[host]) {
-      delete config.agents[host]
-      writeConfig(config)
-    }
-    const remaining = Object.keys(config.agents || {}).length
-    if (remaining === 0 && observer.isRunning(MIO_HOME)) {
-      observer.stopBackground(MIO_HOME)
-    }
-  }
+function evolutionStatus(useJson) {
+  const payload = getEvolutionStatus()
   if (useJson) {
-    jsonOrText(result, true)
+    jsonOrText(payload, true)
     return
   }
-  console.log(result.message || `${host} adapter removed.`)
+  console.log(formatEvolutionStatusText(payload))
 }
 
-function runNpm(args) {
-  try {
-    const res = spawnSync('npm', args, { encoding: 'utf8', shell: true, windowsHide: true })
-    if (res.error) return { ok: false, error: res.error.message, stdout: '', stderr: '' }
-    return { ok: true, status: res.status, stdout: res.stdout || '', stderr: res.stderr || '' }
-  } catch (e) {
-    return { ok: false, error: e.message, stdout: '', stderr: '' }
-  }
+function printCutoverReadiness(readiness, useJson) {
+  if (useJson) return jsonOrText(readiness, true)
+  console.log(`Cutover readiness for ${readiness.project}: ${readiness.status}`)
+  console.log(`shadow=${readiness.shadowRuns} dual-write=${readiness.dualWriteRuns}`)
+  if (readiness.reasons.length > 0) console.log(`reasons: ${readiness.reasons.join('; ')}`)
 }
 
-function npmGlobalVersion() {
-  const r = runNpm(['ls', '-g', 'mio-agent-runtime'])
-  const m = r.stdout && r.stdout.match(/mio-agent-runtime@(\d+\.\d+\.\d+)/)
-  return m ? m[1] : null
+function printAuthorityPlan(plan, useJson) {
+  if (useJson) return jsonOrText(plan, true)
+  console.log(`Authority switch ${plan.from} -> ${plan.to}: ${plan.approved ? 'ready' : 'blocked'}`)
+  for (const action of plan.actions) console.log(`- ${action.type}`)
+  for (const blocker of plan.blockers) console.log(`blocked: ${blocker}`)
 }
 
-function npmLatestVersion() {
-  const r = runNpm(['view', 'mio-agent-runtime', 'version'])
-  const m = r.stdout && r.stdout.trim().match(/(\d+\.\d+\.\d+)/)
-  return m ? m[1] : null
+function printMigrationPlan(plan, useJson) {
+  if (useJson) return jsonOrText(plan, true)
+  console.log(`Migration plan: ${plan.ready ? 'ready' : 'conflicts'}`)
+  console.log(
+    `legacy=${plan.summary.legacy} modular=${plan.summary.modular} toCreate=${plan.summary.toCreate} conflicts=${plan.summary.conflicts}`
+  )
 }
 
-function upgradeCommand(useJson) {
-  const before = npmGlobalVersion()
-  const installRes = runNpm(['install', '-g', 'mio-agent-runtime@latest'])
-  if (!installRes.ok || installRes.status !== 0) {
-    const msg = 'npm install failed: ' + (installRes.error || installRes.stderr || 'unknown error')
-    if (useJson) return jsonOrText({ ok: false, error: msg }, true)
-    console.error(msg)
-    process.exitCode = 1
-    return
-  }
-  const after = npmGlobalVersion()
-  const prefix = (() => { const r = runNpm(['config', 'get', 'prefix']); return r.stdout ? r.stdout.trim() : '' })()
-  const isWin = process.platform === 'win32'
-  const globalServer = prefix ? path.join(prefix, 'node_modules', 'mio-agent-runtime', 'server', 'mio-intelligence-mcp', 'index.js') : SERVER_SCRIPT
-  const globalNode = prefix ? (isWin ? path.join(prefix, 'node.exe') : path.join(prefix, 'bin', 'node')) : process.execPath
-  const nodeBin = fs.existsSync(globalNode) ? globalNode : process.execPath
-  const config = readConfig()
-  const hosts = Object.keys(config.agents || {})
-  const rewired = []
-  for (const host of hosts) {
-    const adapter = adapters[host]
-    if (!adapter) continue
-    try {
-      const result = adapter.install({ node: nodeBin, serverScript: globalServer, home: MIO_HOME, workspace: process.cwd() })
-      if (result.changed) rewired.push(host)
-    } catch (_) {}
-  }
-  let observerStarted = false
-  try { observerStarted = observer.startBackground(MIO_HOME).started } catch (_) {}
-  const payload = { ok: true, before, after, rewiredHosts: rewired, observerStarted }
-  if (useJson) return jsonOrText(payload, true)
-  console.log('Upgraded Mio: ' + (before || '?') + ' -> ' + (after || '?'))
-  if (rewired.length) console.log('Re-wired hosts: ' + rewired.join(', '))
-  else console.log('All installed hosts already up to date.')
-  console.log(observerStarted ? 'Observer started.' : 'Observer already running.')
+function printCutoverDryRun(result, useJson) {
+  if (useJson) return jsonOrText(result, true)
+  console.log(`Cutover apply dry-run: ${result.status}`)
+  console.log(`applied=${result.applied}`)
+  for (const action of result.actions) console.log(`- ${action.type}`)
 }
 
-function doctorCommand(useJson) {
-  const checks = []
-  function add(name, ok, detail) { checks.push({ name: name, ok: Boolean(ok), detail: detail || '' }) }
-  add('MIO_HOME exists', fs.existsSync(MIO_HOME), MIO_HOME)
-  if (fs.existsSync(MIO_HOME)) {
-    try { fs.accessSync(MIO_HOME, fs.constants.W_OK); add('MIO_HOME writable', true) }
-    catch (_) { add('MIO_HOME writable', false, 'no write permission') }
-  }
-  add('MCP server present', fs.existsSync(SERVER_SCRIPT), SERVER_SCRIPT)
-  for (const host of ['codex', 'opencode', 'workbuddy', 'hermes']) {
-    const adapter = adapters[host]
-    const installed = adapter ? adapter.isInstalled() : false
-    add('host:' + host + ' installed', installed)
-  }
-  const obsRunning = observer.isRunning(MIO_HOME)
-  add('observer running', obsRunning, obsRunning ? 'pid ' + observer.readPid(MIO_HOME) : 'not running')
-  const installed = npmGlobalVersion()
-  const latest = npmLatestVersion()
-  add('npm up to date', installed === latest, 'installed ' + installed + ' / latest ' + latest)
-  const prefix = (() => { const r = runNpm(['config', 'get', 'prefix']); return r.stdout ? r.stdout.trim() : '' })()
-  const execPrefix = path.dirname(process.execPath)
-  add('global bin on PATH', prefix && execPrefix && prefix.toLowerCase() === execPrefix.toLowerCase(), 'npm prefix ' + prefix + ' / node ' + execPrefix)
-  const stray0 = path.join(process.cwd(), '0')
-  add('no stray 0 file', !fs.existsSync(stray0), fs.existsSync(stray0) ? stray0 : '')
-  const failed = checks.filter(function (c) { return !c.ok })
-  const payload = { ok: failed.length === 0, checks: checks, failedCount: failed.length }
-  if (useJson) return jsonOrText(payload, true)
-  for (const c of checks) {
-    console.log((c.ok ? 'OK   ' : 'FAIL ') + c.name + (c.detail ? '  (' + c.detail + ')' : ''))
-  }
-  console.log('')
-  console.log(failed.length === 0 ? 'All checks passed.' : failed.length + ' check(s) failed. Run `mio upgrade` or reinstall affected hosts.')
+function printShadowRecord(record, useJson) {
+  if (useJson) return jsonOrText(record, true)
+  console.log(`Shadow comparison ${record.id}: ${record.matched ? 'matched' : 'mismatch'}`)
+  if (record.diffs.length > 0) console.log(`diffs=${record.diffs.length}`)
 }
 
-function dashPidPath() { return path.join(MIO_HOME, 'dashboard.pid') }
-function isDashRunning() {
-  const pidFile = dashPidPath()
-  if (!fs.existsSync(pidFile)) return false
-  try { process.kill(parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10), 0); return true } catch (_) { return false }
+function printDualWriteRecord(record, useJson) {
+  if (useJson) return jsonOrText(record, true)
+  console.log(`Dual-write sample ${record.id}: authoritative=${record.authoritative}`)
+  console.log(`shadow=${record.shadow.matched ? 'matched' : 'mismatch'}`)
 }
-function startDashBackground() {
-  if (isDashRunning()) return { started: false, already: true }
-  fs.mkdirSync(MIO_HOME, { recursive: true })
-  const child = spawn(process.execPath, [SERVER_SCRIPT_DASH, String(DASH_PORT)], { env: Object.assign({}, process.env, { MIO_DATA_DIR: MIO_HOME }), detached: true, stdio: 'ignore' })
-  child.unref()
-  fs.writeFileSync(dashPidPath(), String(child.pid))
-  return { started: true, pid: child.pid }
-}
-function stopDash() {
-  const pidFile = dashPidPath()
-  if (!fs.existsSync(pidFile)) return { stopped: false }
-  try { process.kill(parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10), 'SIGTERM') } catch (_) {}
-  try { fs.unlinkSync(pidFile) } catch (_) {}
-  return { stopped: true }
-}
-function dashboardCommand(args) {
-  const flags = args.slice(1)
-  const useJson = flags.includes('--json')
-  const url = 'http://localhost:' + DASH_PORT
-  if (flags.includes('--start')) {
-    const r = startDashBackground()
-    const started = r.started
-    if (useJson) return jsonOrText({ running: true, started: started, url: url }, true)
-    console.log(started ? 'Dashboard started at ' + url : 'Dashboard already running at ' + url)
-    return
-  }
-  if (flags.includes('--stop')) {
-    const r = stopDash()
-    if (useJson) return jsonOrText({ running: false, stopped: r.stopped }, true)
-    console.log(r.stopped ? 'Dashboard stopped.' : 'Dashboard was not running.')
-    return
-  }
-  if (flags.includes('--status')) {
-    const running = isDashRunning()
-    if (useJson) return jsonOrText({ running: running, url: running ? url : null }, true)
-    console.log(running ? 'Dashboard: running (' + url + ')' : 'Dashboard: not running')
-    return
-  }
-  if (flags.includes('--open')) {
-    startDashBackground()
-    try { require('child_process').exec('start ' + url) } catch (_) {}
-    if (useJson) return jsonOrText({ running: true, url: url }, true)
-    console.log('Dashboard opened at ' + url)
+
+async function evolutionCommand(args, useJson) {
+  if (args[1] === 'status') return evolutionStatus(useJson)
+  try {
+    if (args[1] === 'shadow' && args[2] === 'record') {
+      return printShadowRecord(
+        await evolutionCutover.recordShadowComparison({
+          project: optionValue(args, '--project'),
+          label: optionValue(args, '--label'),
+          legacy: parseJsonOption(args, '--legacy'),
+          modular: parseJsonOption(args, '--modular'),
+          input: optionValue(args, '--input') === undefined ? undefined : parseJsonOption(args, '--input'),
+        }),
+        useJson,
+      )
+    }
+    if (args[1] === 'dual-write' && args[2] === 'record') {
+      return printDualWriteRecord(
+        await evolutionCutover.recordDualWrite({
+          project: optionValue(args, '--project'),
+          label: optionValue(args, '--label'),
+          authoritative: optionValue(args, '--authoritative'),
+          legacyResult: parseJsonOption(args, '--legacy-result'),
+          modularResult: parseJsonOption(args, '--modular-result'),
+          record: optionValue(args, '--record') === undefined ? undefined : parseJsonOption(args, '--record'),
+        }),
+        useJson,
+      )
+    }
+    if (args[1] === 'cutover' && args[2] === 'readiness') {
+      return printCutoverReadiness(
+        evolutionCutover.cutoverReadiness({
+          project: optionValue(args, '--project'),
+          minShadowRuns: parseNumberOption(args, '--min-shadow-runs'),
+          maxMismatchRate: parseNumberOption(args, '--max-mismatch-rate'),
+        }),
+        useJson,
+      )
+    }
+    if (args[1] === 'cutover' && args[2] === 'apply') {
+      return printCutoverDryRun(
+        evolutionCutover.applyCutover({
+          dryRun: flagPresent(args, '--dry-run'),
+          project: optionValue(args, '--project'),
+          plan: parseJsonOption(args, '--plan'),
+        }),
+        useJson,
+      )
+    }
+    if (args[1] === 'authority' && args[2] === 'plan') {
+      return printAuthorityPlan(
+        evolutionCutover.authorityPlan({
+          readiness: parseJsonOption(args, '--readiness'),
+          from: optionValue(args, '--from'),
+          to: optionValue(args, '--to'),
+        }),
+        useJson,
+      )
+    }
+    if (args[1] === 'migration' && args[2] === 'plan') {
+      return printMigrationPlan(
+        evolutionCutover.migrationPlan({
+          legacyRecords: parseJsonOption(args, '--legacy-records'),
+          modularRecords: parseJsonOption(args, '--modular-records'),
+        }),
+        useJson,
+      )
+    }
+  } catch (error) {
+    console.error(error.message || error)
+    process.exitCode = 1
     return
   }
-  const child = spawn(process.execPath, [SERVER_SCRIPT_DASH, String(DASH_PORT)], { env: Object.assign({}, process.env, { MIO_DATA_DIR: MIO_HOME }), stdio: 'inherit' })
-  child.on('exit', function () { try { fs.unlinkSync(dashPidPath()) } catch (_) {} })
+  console.error('Usage: mio evolution status|shadow record|dual-write record|cutover readiness|cutover apply|authority plan|migration plan')
+  process.exitCode = 1
 }
-
-function help() {
-  console.log(`Mio Agent Runtime CLI
-
-Usage:
-  mio version                 Show installed Mio version
-  mio init                    Initialize MIO_HOME
-  mio mcp                     Start Mio MCP server (stdio)
-  mio install <host>          Install Mio into a host (codex|opencode|workbuddy|hermes)
-  mio uninstall <host>        Remove Mio from a host
-  mio upgrade                 Upgrade Mio and re-wire all installed hosts
-  mio doctor                  Diagnose install and runtime issues
+
+function ensureHome() {
+  fs.mkdirSync(MIO_HOME, { recursive: true })
+  fs.mkdirSync(path.join(MIO_HOME, 'logs'), { recursive: true })
+}
+
+function readConfig() {
+  const fallback = { version: 1, home: MIO_HOME, agents: {} }
+  if (!fs.existsSync(CONFIG_FILE)) return fallback
+  try {
+    return { ...fallback, ...JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')) }
+  } catch (_) {
+    return fallback
+  }
+}
+
+function writeConfig(config) {
+  ensureHome()
+  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+}
+
+function jsonOrText(payload, useJson) {
+  if (useJson) {
+    console.log(JSON.stringify(payload, null, 2))
+    return
+  }
+  return payload
+}
+
+function initCommand() {
+  ensureHome()
+  const config = readConfig()
+  if (!config.createdAt) config.createdAt = new Date().toISOString()
+  writeConfig(config)
+  console.log(`MIO_HOME ready: ${MIO_HOME}`)
+}
+
+function statusCommand(useJson) {
+  const config = readConfig()
+  const codexRestart = adapters.codex.restartWarningMessage()
+  const opencodeRestart = adapters.opencode.restartWarningMessage()
+  const installed = {
+    codex: adapters.codex.isInstalled(),
+    opencode: adapters.opencode.isInstalled(),
+    workbuddy: adapters.workbuddy.isInstalled(),
+    hermes: adapters.hermes.isInstalled(),
+  }
+  const payload = {
+    version: config.version,
+    home: MIO_HOME,
+    serverScript: SERVER_SCRIPT,
+    serverScriptExists: fs.existsSync(SERVER_SCRIPT),
+    agents: config.agents || {},
+    codexInstalled: installed.codex,
+    opencodeInstalled: installed.opencode,
+    workbuddyInstalled: installed.workbuddy,
+    hermesInstalled: installed.hermes,
+    codexNeedsRestart: Boolean(codexRestart),
+    opencodeNeedsRestart: Boolean(opencodeRestart),
+    codexRestartHint: codexRestart,
+    opencodeRestartHint: opencodeRestart,
+    hermesObserverReady: fs.existsSync(observer.hermesDbPath()),
+    opencodeObserverReady: fs.existsSync(observer.opencodeDbPath()),
+    observerRunning: observer.isRunning(MIO_HOME),
+    observerPid: observer.isRunning(MIO_HOME) ? observer.readPid(MIO_HOME) : null,
+  }
+  if (useJson) {
+    jsonOrText(payload, true)
+    return
+  }
+  console.log(`MIO_HOME: ${MIO_HOME}`)
+  console.log(`MCP Server: ${SERVER_SCRIPT}`)
+  console.log(`Codex MCP: ${installed.codex ? 'installed' : 'not installed'}`)
+  if (codexRestart) console.log(`Codex app: running with an older Mio config - fully restart Codex to load it`)
+  console.log(`OpenCode MCP: ${installed.opencode ? 'installed' : 'not installed'}`)
+  if (opencodeRestart) console.log(`OpenCode Desktop: running with an older Mio config - restart it to load it`)
+  console.log(`OpenCode observer: ${fs.existsSync(observer.opencodeDbPath()) ? 'ready' : 'no database'}`)
+  console.log(`WorkBuddy MCP: ${installed.workbuddy ? 'installed' : 'not installed'}`)
+  console.log(`Hermes MCP: ${installed.hermes ? 'installed' : 'not installed'}`)
+  console.log(`Hermes observer: ${fs.existsSync(observer.hermesDbPath()) ? 'ready' : 'no database'}`)
+  console.log(`Observer: ${observer.isRunning(MIO_HOME) ? 'running (pid ' + observer.readPid(MIO_HOME) + ')' : 'not running'}`)
+}
+
+function agentsCommand(useJson) {
+  const config = readConfig()
+  const agents = config.agents || {}
+  if (useJson) {
+    jsonOrText(agents, true)
+    return
+  }
+  const names = Object.keys(agents)
+  if (names.length === 0) {
+    console.log('No agents installed.')
+    return
+  }
+  for (const name of names) {
+    console.log(`${name}\t${agents[name].installedAt || ''}`)
+  }
+}
+
+function installCommand(host, useJson) {
+  if (!host) {
+    console.error('Usage: mio install <codex|opencode|workbuddy|hermes>')
+    process.exitCode = 1
+    return
+  }
+  const adapter = adapters[host]
+  if (!adapter) {
+    console.error(`Unknown host: ${host}`)
+    process.exitCode = 1
+    return
+  }
+  ensureHome()
+  const config = readConfig()
+  let result
+  try {
+    result = adapter.install({
+      node: process.execPath,
+      serverScript: SERVER_SCRIPT,
+      home: MIO_HOME,
+      workspace: process.cwd(),
+    })
+  } catch (error) {
+    console.error(`Failed to install ${host}: ${error.message || error}`)
+    process.exitCode = 1
+    return
+  }
+  if (result.changed) {
+    config.agents = config.agents || {}
+    config.agents[host] = {
+      installedAt: new Date().toISOString(),
+      configPath: result.configPath || null,
+    }
+    writeConfig(config)
+  }
+  try {
+    observer.runCycle(MIO_HOME, observer.loadState(MIO_HOME), observer.createSinks(MIO_HOME))
+  } catch (_) {}
+  let observerStarted = false
+  try {
+    observerStarted = observer.startBackground(MIO_HOME).started
+  } catch (_) {}
+  if (useJson) {
+    result.observer = {
+      running: observer.isRunning(MIO_HOME),
+      started: observerStarted,
+    }
+    jsonOrText(result, true)
+    return
+  }
+  console.log(result.message || `${host} adapter completed.`)
+  console.log(
+    observer.isRunning(MIO_HOME)
+      ? 'Observer daemon running.'
+      : 'Observer daemon not running. Run `mio observe --start`.'
+  )
+}
+
+function mcpCommand() {
+  require(SERVER_SCRIPT)
+}
+
+function observeCommand(args) {
+  const flags = args.slice(1)
+  const useJson = flags.includes('--json')
+  if (flags.includes('--start')) {
+    const result = observer.startBackground(MIO_HOME)
+    if (useJson) return jsonOrText(result, true)
+    console.log(result.started ? 'Observer started.' : 'Observer already running.')
+    return
+  }
+  if (flags.includes('--stop')) {
+    const result = observer.stopBackground(MIO_HOME)
+    if (useJson) return jsonOrText(result, true)
+    console.log(result.stopped ? 'Observer stopped.' : 'Observer was not running.')
+    return
+  }
+  if (flags.includes('--status')) {
+    const running = observer.isRunning(MIO_HOME)
+    const pid = observer.readPid(MIO_HOME)
+    if (useJson) return jsonOrText({ running, pid }, true)
+    console.log(running ? 'Observer: running (pid ' + pid + ')' : 'Observer: not running')
+    return
+  }
+  if (flags.includes('--once')) {
+    const res = observer.runCycle(
+      MIO_HOME,
+      observer.loadState(MIO_HOME),
+      observer.createSinks(MIO_HOME)
+    )
+    if (useJson) return jsonOrText(res, true)
+    console.log('Observed files=' + res.files + ' lines=' + res.lines + ' outcomes=' + res.outcomes)
+    return
+  }
+  console.log('Observing WorkBuddy transcripts into ' + MIO_HOME + ' (Ctrl+C to stop)...')
+  observer.startForeground(MIO_HOME)
+}
+
+function help() {
+  console.log(`Mio Agent Runtime CLI
+
+Usage:
+  mio init                    Initialize MIO_HOME
+  mio mcp                     Start Mio MCP server (stdio)
+  mio install <host>          Install Mio into a host (codex|opencode|workbuddy|hermes)
   mio status                  Show runtime and adapter status
   mio agents                  List installed agents
+  mio evolution status        Show composed evolution module health
+  mio evolution shadow record      Record a shadow comparison sample
+  mio evolution dual-write record  Record a dual-write comparison sample
+  mio evolution cutover readiness   Assess shadow/dual-write cutover readiness
+  mio evolution authority plan      Preview a gated authority switch plan
+  mio evolution migration plan      Preview state migration diffs
+  mio evolution cutover apply --dry-run   Dry-run a cutover plan without switching authority
   mio observe                 Watch WorkBuddy transcripts and auto-ingest task outcomes
   mio observe --start|--stop|--status|--once   Manage the background observer daemon
-  mio dashboard [--start|--stop|--status|--open]   Start the live dashboard HTTP server
   mio --json status           Machine-readable status
   mio --json agents           Machine-readable agents
+  mio --json evolution status Machine-readable evolution module health
 `)
 }
-
-function main() {
-  const args = process.argv.slice(2)
-  const jsonIndex = args.indexOf('--json')
-  const useJson = jsonIndex !== -1
-  if (useJson) args.splice(jsonIndex, 1)
-  const command = args[0] || 'help'
-
-  switch (command) {
-    case 'version':
-    case '--version':
-      return versionCommand()
-    case 'init':
-      return initCommand()
-    case 'mcp':
-      return mcpCommand()
-    case 'install':
-      return installCommand(args[1], useJson)
-    case 'uninstall':
-      return uninstallCommand(args[1], useJson)
-    case 'upgrade':
-      return upgradeCommand(useJson)
-    case 'doctor':
-      return doctorCommand(useJson)
-    case 'status':
-      return statusCommand(useJson)
-    case 'agents':
-      return agentsCommand(useJson)
+
+async function main() {
+  const args = process.argv.slice(2)
+  const jsonIndex = args.indexOf('--json')
+  const useJson = jsonIndex !== -1
+  if (useJson) args.splice(jsonIndex, 1)
+  const command = args[0] || 'help'
+
+  switch (command) {
+    case 'init':
+      return initCommand()
+    case 'mcp':
+      return mcpCommand()
+    case 'install':
+      return installCommand(args[1], useJson)
+    case 'status':
+      return statusCommand(useJson)
+    case 'agents':
+      return agentsCommand(useJson)
     case 'observe':
       return observeCommand(args)
-    case 'dashboard':
-      return dashboardCommand(args)
-    case 'help':
-    case '--help':
-      return help()
-    default:
-      console.error(`Unknown command: ${command}`)
-      help()
-      process.exitCode = 1
-  }
+    case 'evolution':
+      return evolutionCommand(args, useJson)
+    case 'help':
+    case '--help':
+      return help()
+    default:
+      console.error(`Unknown command: ${command}`)
+      help()
+      process.exitCode = 1
+  }
 }
 
-main()
+main().catch((error) => {
+  console.error(error.message || error)
+  process.exitCode = 1
+})