@yugabytedb/meko-mcp 2.2.0 → 2.3.0

package/lib/migrate/progress.mjs

@@ -1,19 +1,66 @@
 /**
  * progress.mjs — Lightweight progress snapshots for `--migrate-status`.
+ *
+ * A run's status is a small state machine. Four states are written to
+ * `progress.json`:
+ *
+ *   running:    written once at daemon start.
+ *   succeeded:  written from the normal completion path.
+ *   failed:     written from the top-level exception handler, with the
+ *                error class and message.
+ *   cancelled:  written from the SIGINT/SIGTERM handler before exit.
+ *
+ * A fifth state, `crashed`, is never written. The reader infers it for a
+ * `running` record whose PID is dead or whose heartbeat has gone stale,
+ * which is how a `kill -9`, an OOM kill, or a laptop sleep gets reported
+ * honestly instead of as a live migration. See `classify()`.
+ *
+ * `heartbeatAt` is refreshed on a timer for the same reason: a silently
+ * killed daemon runs no handler, so the only evidence of death is the
+ * absence of new writes.
  */
 
 import fs from "node:fs";
 import path from "node:path";
 
+/** How often the daemon refreshes `heartbeatAt`. */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+
+/**
+ * How long a heartbeat may go unrefreshed before the reader calls the run
+ * dead. Three intervals of slack absorbs a paused event loop (a long
+ * `memory_add` extraction, a suspended laptop) without flapping.
+ */
+export const HEARTBEAT_STALE_AFTER_MS = HEARTBEAT_INTERVAL_MS * 3;
+
+/** Terminal states: a run in one of these will never advance again. */
+export const TERMINAL_STATUSES = ["succeeded", "failed", "cancelled"];
+
+/**
+ * Pre-2.3 runs on disk used `done` for success and `interrupted` for a
+ * signal. The reader normalizes them so a status read against a run
+ * started by an older installer still lands in the documented state set.
+ */
+const LEGACY_STATUS_ALIASES = {
+  done: "succeeded",
+  interrupted: "cancelled",
+  stopped: "cancelled",
+};
+
 /**
  * @typedef {Object} Progress
  * @property {string} runId
  * @property {string} scope
  * @property {string} startedAt
  * @property {string|null} finishedAt
- * @property {"running"|"done"|"failed"|"interrupted"} status
+ * @property {string|null} heartbeatAt   ISO timestamp, refreshed on a timer
+ *                                      while the run is `running`.
+ * @property {number|null} pid           PID of the daemon that owns the run.
+ * @property {"running"|"succeeded"|"failed"|"cancelled"} status
+ * @property {string|null} error         Set alongside `failed`.
  * @property {string|null} currentAgent
- * @property {string|null} currentSession
+ * @property {string|null} currentSession  Source session UUID being replayed.
+ * @property {string|null} currentMessage  Source message (turn) id being sent.
  * @property {Counts} counts
  *
  * @typedef {Object} Counts
@@ -24,20 +71,26 @@ import path from "node:path";
  * @property {number} memoriesFromMD
  * @property {number} warnings
  * @property {number} memoryErrors
+ * @property {number} authSkipped    Calls dropped on a mid-run 401/403.
  */
 
 /**
  * @returns {Progress}
  */
-export function initial(runId, scope) {
+export function initial(runId, scope, opts = {}) {
+  const now = new Date().toISOString();
   return {
     runId,
     scope,
-    startedAt: new Date().toISOString(),
+    startedAt: now,
     finishedAt: null,
+    heartbeatAt: now,
+    pid: opts.pid ?? process.pid,
     status: "running",
+    error: null,
     currentAgent: null,
     currentSession: null,
+    currentMessage: null,
     counts: {
       sessionsPlanned: 0,
       sessionsDone: 0,
@@ -46,17 +99,26 @@ export function initial(runId, scope) {
       memoriesFromMD: 0,
       warnings: 0,
       memoryErrors: 0,
+      authSkipped: 0,
     },
   };
 }
 
 /**
- * Atomic write.
+ * Atomic write. Refreshes `heartbeatAt` on every write of a `running`
+ * record, so ordinary progress writes double as heartbeats and the timer
+ * only matters during long gaps between them.
  *
  * @param {string} progressPath
  * @param {Progress} progress
  */
 export function write(progressPath, progress) {
+  if (progress && progress.status === "running") {
+    // Once `finalize()` has closed this run, a `running` write can only be
+    // stale: the live object a caller still holds, or a heartbeat tick.
+    if (sealedPaths.has(progressPath)) return;
+    progress.heartbeatAt = new Date().toISOString();
+  }
   fs.mkdirSync(path.dirname(progressPath), { recursive: true });
   const tmp = `${progressPath}.tmp.${process.pid}.${Date.now()}`;
   fs.writeFileSync(tmp, JSON.stringify(progress, null, 2));
@@ -74,3 +136,175 @@ export function read(progressPath) {
     return null;
   }
 }
+
+// --- Heartbeat -------------------------------------------------------------
+
+// Module singleton. The orchestrator starts the heartbeat and the daemon
+// entrypoint stops it from its catch/signal handlers, which run in the same
+// process after `runMigration` has stopped writing. Keeping the handle here
+// rather than threading it through a return value means the handlers can
+// stop it even on the path where `runMigration` threw and returned nothing.
+let heartbeatTimer = null;
+
+// Progress files that `finalize()` has moved to a terminal status. The
+// catch and signal handlers finalize by read-modify-write, so the
+// orchestrator's live `prog` object still says `running`. Sealing the path
+// makes any later write of that object a no-op instead of a resurrection.
+const sealedPaths = new Set();
+
+/**
+ * Refresh `heartbeatAt` every `HEARTBEAT_INTERVAL_MS` while the run is in
+ * flight. The timer is `unref`'d so it never keeps the process alive on its
+ * own; `stopHeartbeat()` is still the correct way to end it, because a live
+ * timer that fires after a terminal write would resurrect `running`.
+ *
+ * @param {string} progressPath
+ * @param {Progress} prog   The live object the orchestrator mutates.
+ * @returns {() => void}    Stop function; same effect as `stopHeartbeat()`.
+ */
+export function startHeartbeat(progressPath, prog) {
+  stopHeartbeat();
+  heartbeatTimer = setInterval(() => {
+    if (!prog || prog.status !== "running") return;
+    try {
+      write(progressPath, prog);
+    } catch {
+      /* best effort; a missed heartbeat only costs a stale-looking read */
+    }
+  }, HEARTBEAT_INTERVAL_MS);
+  if (typeof heartbeatTimer.unref === "function") heartbeatTimer.unref();
+  return stopHeartbeat;
+}
+
+export function stopHeartbeat() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+/** Whether a heartbeat timer is live. Lets tests prove the run stopped it. */
+export function isHeartbeatRunning() {
+  return heartbeatTimer !== null;
+}
+
+/**
+ * Write a terminal status by read-modify-write, preserving whatever counts
+ * the orchestrator last flushed.
+ *
+ * Used by the daemon entrypoint's catch and signal handlers, which don't
+ * hold the orchestrator's live `prog` object. Stops the heartbeat and seals
+ * the path first, so neither the timer nor a late write of the live object
+ * can overwrite the terminal record.
+ *
+ * @param {string} progressPath
+ * @param {object} opts
+ * @param {"succeeded"|"failed"|"cancelled"} opts.status
+ * @param {string|null} [opts.error]
+ * @returns {{record: Progress|null, wrote: boolean}}  `record` is null when
+ *   there was no progress file. `wrote` is false when there was nothing to
+ *   finalize or the record was already terminal, so callers only mirror a
+ *   transition into the event log when it actually happened.
+ */
+export function finalize(progressPath, opts) {
+  stopHeartbeat();
+  sealedPaths.add(progressPath);
+  const prog = read(progressPath);
+  if (!prog) return { record: null, wrote: false };
+  // Don't overwrite an already-terminal record: a signal that arrives while
+  // the process is on its way out shouldn't rewrite `succeeded` as
+  // `cancelled`.
+  if (TERMINAL_STATUSES.includes(normalizeStatus(prog.status))) {
+    return { record: prog, wrote: false };
+  }
+  prog.status = opts.status;
+  prog.error = opts.error ?? null;
+  prog.finishedAt = new Date().toISOString();
+  prog.currentAgent = null;
+  prog.currentSession = null;
+  prog.currentMessage = null;
+  try {
+    write(progressPath, prog);
+  } catch {
+    return { record: prog, wrote: false };
+  }
+  return { record: prog, wrote: true };
+}
+
+// --- Reader-side classification --------------------------------------------
+
+/**
+ * Map a legacy on-disk status onto the documented state set.
+ *
+ * @param {string|undefined} status
+ * @returns {string}
+ */
+export function normalizeStatus(status) {
+  if (!status) return "unknown";
+  return LEGACY_STATUS_ALIASES[status] ?? status;
+}
+
+/**
+ * Decide what a progress record actually means, given process liveness.
+ *
+ * A `running` record is only believable if the daemon is still alive. Two
+ * independent checks, either of which condemns it:
+ *
+ *   - the PID it names has no live process (`isPidAlive` is supplied by the
+ *     caller, normally `lockfile.isStale` inverted), or
+ *   - its heartbeat is older than `HEARTBEAT_STALE_AFTER_MS`.
+ *
+ * The heartbeat check is what catches a run whose PID has been recycled by
+ * an unrelated process; the PID check is what reports a `kill -9` within
+ * milliseconds instead of waiting out the stale window.
+ *
+ * @param {Progress} prog
+ * @param {object} [opts]
+ * @param {number|null} [opts.pid]        PID to test; defaults to `prog.pid`.
+ * @param {(pid: number) => boolean} [opts.isPidAlive]
+ * @param {boolean} [opts.holdsLock]      Whether the migrate lockfile still
+ *                                        names this run. A live daemon always
+ *                                        holds it; it is released on the way
+ *                                        out. Pass this only when the caller
+ *                                        actually read the lockfile.
+ * @param {number} [opts.now]             Epoch ms; injectable for tests.
+ * @returns {{status: string, crashed: boolean, reason: string|null}}
+ */
+export function classify(prog, opts = {}) {
+  const status = normalizeStatus(prog?.status);
+  if (status !== "running") return { status, crashed: false, reason: null };
+
+  const now = opts.now ?? Date.now();
+  const pid = opts.pid ?? prog?.pid ?? null;
+
+  if (typeof pid === "number" && pid > 0 && typeof opts.isPidAlive === "function") {
+    if (!opts.isPidAlive(pid)) {
+      return { status: "crashed", crashed: true, reason: `pid ${pid} not alive` };
+    }
+  }
+
+  const beat = Date.parse(prog?.heartbeatAt ?? "");
+  if (Number.isFinite(beat)) {
+    const age = now - beat;
+    if (age > HEARTBEAT_STALE_AFTER_MS) {
+      return {
+        status: "crashed",
+        crashed: true,
+        reason: `no heartbeat for ${Math.round(age / 1000)}s`,
+      };
+    }
+  } else if (pid === null) {
+    // A pre-heartbeat run record: no PID to test, no parseable heartbeat.
+    // The lockfile is the last piece of evidence. A daemon holds it for the
+    // whole run and releases it on the way out, so a `running` record that
+    // no longer owns the lock is a run that ended without saying so:
+    // exactly the stuck-forever records this fix exists to explain.
+    if (opts.holdsLock === false) {
+      return { status: "crashed", crashed: true, reason: "no lock holder" };
+    }
+    // Otherwise report it as running, but say why we can't vouch for it.
+    return { status: "running", crashed: false, reason: "no liveness data" };
+  }
+
+  return { status: "running", crashed: false, reason: null };
+}

package/lib/migrate/registry.mjs

@@ -0,0 +1,72 @@
+/** Session migration adapters: id, displayName, listSessions, parseSession. */
+import * as claudeCodeAdapter from "./adapters/claude-code.mjs";
+import * as cursorAdapter from "./adapters/cursor.mjs";
+import * as codexAdapter from "./adapters/codex.mjs";
+import * as openCodeAdapter from "./adapters/opencode.mjs";
+/** @type {Array<{id: string, displayName: string, listSessions: Function, parseSession: Function}>} */
+export const SESSION_ADAPTERS = [
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    listSessions: claudeCodeAdapter.listSessions,
+    parseSession: (ref) => claudeCodeAdapter.parseSession(ref.path),
+  },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    listSessions: cursorAdapter.listSessions,
+    parseSession: (ref) => cursorAdapter.parseSession(ref.path),
+  },
+  {
+    id: "codex",
+    displayName: "Codex",
+    listSessions: codexAdapter.listSessions,
+    parseSession: (ref) => codexAdapter.parseSession(ref.path),
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    listSessions: openCodeAdapter.listSessions,
+    parseSession: (ref, opts) => openCodeAdapter.parseSession(ref, opts),
+  },
+];
+/** @returns {Promise<Array<{ ref: object, source: string }>>} */
+export async function enumerateSessionRefs(opts) {
+  const out = [];
+  const adapters = opts.sessionAdapters ?? SESSION_ADAPTERS;
+  for (const adapter of adapters) {
+    let refs;
+    try {
+      refs = await adapter.listSessions(opts);
+      if (!Array.isArray(refs)) {
+        throw new Error("listSessions did not return an array");
+      }
+      for (const ref of refs) {
+        out.push({ ref, source: adapter.id, adapter });
+      }
+    } catch (error) {
+      opts.onSourceError?.({
+        source: adapter.id,
+        displayName: adapter.displayName,
+        error,
+      });
+    }
+  }
+  return out;
+}
+/** @returns {Promise<object>|object} */
+export function parseTaggedSession(tagged, opts = {}) {
+  const adapter =
+    tagged.adapter ?? SESSION_ADAPTERS.find((a) => a.id === tagged.source);
+  if (!adapter) throw new Error(`unknown migration source: ${tagged.source}`);
+  return adapter.parseSession(tagged.ref, opts);
+}
+/** Legacy summary field names keyed by adapter id. */
+export function sessionsByAdapter(tagged) {
+  /** @type {Record<string, number>} */
+  const counts = {};
+  for (const { source } of tagged) {
+    counts[source] = (counts[source] || 0) + 1;
+  }
+  return counts;
+}

package/lib/migrate.mjs

@@ -56,7 +56,13 @@ function paths(opts = {}) {
     statePath,
     lockPath: path.join(root, "lock"),
     runDir: (runId) => path.join(root, runId),
-    logFile: (runId) => path.join(root, runId, "stdout.log"),
+    // Where the child's stdio is redirected. Everything the daemon has to
+    // say goes through the NDJSON logger instead, so this file is normally
+    // empty; it only catches process-level output that escapes the logger
+    // (a stack trace from before it opens, a native crash). Don't point
+    // users here; point them at `eventLogFile`.
+    stdioFile: (runId) => path.join(root, runId, "stdout.log"),
+    eventLogFile: (runId) => path.join(root, runId, "log.ndjson"),
     progressFile: (runId) => path.join(root, runId, "progress.json"),
   };
 }
@@ -231,9 +237,29 @@ export async function startMigration(opts) {
       dryRun: true,
       noExtract: opts.noExtract,
       concurrency: opts.rate,
+      sessionAdapters: opts.sessionAdapters,
+      opencodeBin: opts.opencodeBin,
+      runExport: opts.runExport,
     });
     const s = summary.summary;
+    if (!summary.ok) {
+      return {
+        ok: false,
+        runId,
+        message: `Dry run failed: ${s.detail || s.error || "unknown migration error"}`,
+      };
+    }
     const planned = s.plannedCalls ?? {};
+    const warningLines = [
+      ...(s.sourceErrors ?? []).map(
+        ({ source, error }) => `  Warning: ${source} enumeration failed: ${error}\n`,
+      ),
+      ...(s.sessionErrors ?? []).map(
+        ({ source, sessionUuid, error }) =>
+          `  Warning: ${source} session ${sessionUuid} parse failed: ${error}\n`,
+      ),
+    ]
+      .join("");
     // Dry-run never opens an MCP session, so we can't resolve names→UUIDs
     // here. Echo what the user asked for; the real run will resolve and
     // print the canonical destination before doing any work.
@@ -249,8 +275,11 @@ export async function startMigration(opts) {
         destLine +
         `  Claude Code sessions: ${s.claudeSessions}\n` +
         `  Cursor sessions:      ${s.cursorSessions}\n` +
+        `  Codex sessions:       ${s.codexSessions}\n` +
+        `  OpenCode sessions:    ${s.openCodeSessions}\n` +
         `  Paired user↔asst turns: ${s.pairedTurns}\n` +
         `  Memory items (MD):    ${s.memoryItems}\n` +
+        warningLines +
         `  Planned MCP calls:\n` +
         `    conversation_create:      ${planned.conversation_create ?? 0}\n` +
         `    conversation_add_message: ${planned.conversation_add_message ?? 0}\n` +
@@ -375,7 +404,7 @@ export async function startMigration(opts) {
     scriptPath: opts.scriptPath,
     runId,
     args: passthrough,
-    logFilePath: P.logFile(runId),
+    logFilePath: P.stdioFile(runId),
     env,
     cwd: opts.projectRoot,
   });
@@ -395,7 +424,7 @@ export async function startMigration(opts) {
     message:
       `${datapackBanner}\n` +
       `Migration started. run-id=${runId}, pid=${pid}\n` +
-      `Logs:   ${P.logFile(runId)}\n` +
+      `Logs:   ${P.eventLogFile(runId)}  (one JSON object per line)\n` +
       `Status: ${selfInvocation()} --migrate-status`,
   };
 }
@@ -520,11 +549,21 @@ export async function runChildMigration(opts) {
     log.warn("legacy_state_migrate_failed", { error: err.message });
   }
 
+  const progressPath = P.progressFile(opts.runId);
+
   let shuttingDown = false;
   const onSignal = (sig) => {
     if (shuttingDown) return;
     shuttingDown = true;
     log.warn("interrupted", { signal: sig });
+    // Write the terminal state before releasing the lock. Skipping this is
+    // what left a clean `--migrate-stop` reading as `running` forever.
+    try {
+      const { wrote } = progress.finalize(progressPath, { status: "cancelled", error: `signal ${sig}` });
+      // A signal after the orchestrator's own terminal write leaves that
+      // status in place, so only log a transition that actually happened.
+      if (wrote) log.info("status", { status: "cancelled", signal: sig, runId: opts.runId });
+    } catch { /* best effort; we're on our way out */ }
     try { lockfile.release(P.lockPath); } catch { /* ignore */ }
     log.close();
     process.exit(130);
@@ -554,18 +593,37 @@ export async function runChildMigration(opts) {
     return result.ok ? 0 : 1;
   } catch (err) {
     log.error("child_crashed", { error: err.message, stack: err.stack });
+    // The orchestrator threw before reaching its own terminal write, so the
+    // progress file is still on `running`. Close the state machine here.
+    try {
+      const { wrote } = progress.finalize(progressPath, {
+        status: "failed",
+        error: `${err.name ?? "Error"}: ${err.message}`,
+      });
+      if (wrote) log.info("status", { status: "failed", error: err.message, runId: opts.runId });
+    } catch { /* best effort */ }
     log.close();
     try { lockfile.release(P.lockPath); } catch { /* ignore */ }
     return 1;
+  } finally {
+    // Whatever path we left on, no timer should outlive the run and rewrite
+    // a terminal record back to `running`.
+    progress.stopHeartbeat();
   }
 }
 
 /**
  * Print and return the status of the latest (or requested) migration run.
  *
+ * The on-disk `status` field is not taken at face value. A `running` record
+ * whose daemon is gone reports as `crashed`, which is how a `kill -9`, an
+ * OOM kill, or a reboot shows up. None of them run a handler that could
+ * have written a terminal state. `progress.status` stays as written;
+ * the returned `status` is the effective one.
+ *
  * @param {object} opts
  * @param {string} [opts.runId]
- * @returns {{ok: boolean, runId: string|null, progress: object|null, message: string}}
+ * @returns {{ok: boolean, runId: string|null, progress: object|null, status?: string, crashed?: boolean, message: string}}
  */
 export function readStatus(opts = {}) {
   const P = paths();
@@ -620,23 +678,53 @@ export function readStatus(opts = {}) {
   const RESET = useColor ? "\x1b[0m" : "";
   const note = (s) => (s ? `  ${GRAY}${s}${RESET}` : "");
 
+  // A `running` record is only worth believing if the daemon is still there.
+  // The lockfile names the owning PID; prefer it over the PID the run
+  // recorded, since --force can hand the lock to a newer process.
+  const holder = lockfile.read(P.lockPath);
+  const holdsLock = !!holder && holder.runId === runId;
+  const livePid = holdsLock ? holder.pid : (prog.pid ?? null);
+  const verdict = progress.classify(prog, {
+    pid: livePid,
+    holdsLock,
+    isPidAlive: (pid) => !lockfile.isStale({ pid }),
+  });
+  const statusLabel = verdict.reason
+    ? `${verdict.status} (${verdict.reason})`
+    : verdict.status;
+
   const lines = [
     `run-id:       ${prog.runId}`,
-    `status:       ${prog.status}${note("(pending → running → done | failed | stopped)")}`,
+    `status:       ${statusLabel}${note("(running → succeeded | failed | cancelled; crashed is inferred)")}`,
     `scope:        ${prog.scope}`,
     `datapack:     ${datapackKeyLabel}${note("(resume state lives under state/<key>.json)")}`,
     `target pack:  ${datapackTargetLabel}${note("(ingestion destination resolved at run start)")}`,
     `started:      ${prog.startedAt}`,
-    `finished:     ${prog.finishedAt ?? "(in progress)"}`,
-    `current:      ${prog.currentAgent ?? "-"} / ${prog.currentSession ?? "-"}${note("(<adapter>:<source-session> / <message-id>)")}`,
+    `finished:     ${prog.finishedAt ?? (verdict.crashed ? "(never, daemon died)" : "(in progress)")}`,
+    `heartbeat:    ${prog.heartbeatAt ?? "-"}${note("(refreshed while running; staleness implies crashed)")}`,
+    `current:      ${prog.currentAgent ?? "-"} / ${prog.currentSession ?? "-"} / ${prog.currentMessage ?? "-"}${note("(<agent-id> / <source-session> / <message-id>)")}`,
     `sessions:     ${prog.counts.sessionsDone} / ${prog.counts.sessionsPlanned}${note("(processed / discovered)")}`,
     `messages:     ${prog.counts.messagesSent}`,
     `memory pairs: ${prog.counts.memoryPairsSent}${note("(memory_add from Mem0 extractor)")}`,
     `memory (MD):  ${prog.counts.memoriesFromMD}${note("(memory_add from CLAUDE.md / memory files)")}`,
     `warnings:     ${prog.counts.warnings}${note("(non-fatal; run continues)")}`,
     `memory errs:  ${prog.counts.memoryErrors}${note("(failed memory_add calls; re-run with --force to retry)")}`,
+    `auth skipped: ${prog.counts.authSkipped ?? 0}${note("(calls dropped on a mid-run 401/403; re-run to retry them)")}`,
   ];
-  return { ok: true, runId, progress: prog, message: lines.join("\n") };
+  if (prog.error) {
+    lines.push(`error:        ${prog.error}`);
+  }
+  return {
+    ok: true,
+    runId,
+    progress: prog,
+    // The effective status, after the liveness check. `progress.status` is
+    // the raw on-disk field and can still read `running` for a dead daemon;
+    // callers that care whether the run is actually alive want this one.
+    status: verdict.status,
+    crashed: verdict.crashed,
+    message: lines.join("\n"),
+  };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Installer for Meko across Claude, Cursor, Codex, and Kiro clients",
   "type": "module",
   "bin": {

package/scripts/bundle-assets.mjs

@@ -30,6 +30,10 @@ const PAYLOAD = [
     from: join(repoRoot, "skills", "hooks-handlers"),
     to: join(assetsDir, "hooks-handlers"),
   },
+  {
+    from: join(repoRoot, "skills", "opencode-plugin"),
+    to: join(assetsDir, "opencode-plugin"),
+  },
   {
     from: join(repoRoot, "skills", "scripts", "package-desktop-skill.sh"),
     to: join(assetsDir, "scripts", "package-desktop-skill.sh"),