@yugabytedb/meko-mcp 2.3.0 → 2.5.0

package/assets/hooks-handlers/lib/capture-cleanup-cli.js

@@ -1,4 +1,18 @@
 #!/usr/bin/env node
+/*
+ * Licensed to YugabyteDB, Inc. under one or more contributor license agreements.
+ * See the NOTICE file distributed with this work for additional information
+ * regarding copyright ownership. YugabyteDB licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed
+ * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
 /**
  * capture-cleanup-cli.js: inspect and clean up stuck conversation capture.
  *
@@ -25,6 +39,12 @@
  *   repair   Clear failure fields left on fully delivered sessions, and
  *            remove timer PID files, leases, and SessionEnd job files whose
  *            process is gone.
+ *   fix      Do all of the above for every session that needs it: diagnose
+ *            why it is stuck, then repair it, drain it, or move its unsent
+ *            turns to a new conversation when the old one can't be served.
+ *            Sessions that need you (bad API key, plan limit, datapack) get
+ *            one attempt per run and are reported if it fails the same way.
+ *            Stops early when the server itself is failing.
  *
  * Parking works with the capture hooks already installed (2.2.0 and later):
  * a drain skips the network while `failure_class` is set and
@@ -48,12 +68,15 @@ const path = require("path");
 const cs = require("./capture-state");
 const { PARKED_REASON_PREFIX } = require("./capture-notices");
 
-const ACTIONS = ["status", "stop", "resume", "drain", "discard", "repair"];
-const PARK_UNTIL = "9999-12-31T00:00:00.000Z";
+const ACTIONS = ["status", "fix", "stop", "resume", "drain", "discard", "repair"];
+const PARK_UNTIL = cs.CLEANUP_PARK_UNTIL;
 const PARKED_BY = "meko-mcp --capture-cleanup";
 const RESUME_HINT =
   `${PARKED_REASON_PREFIX}; run \`npx @yugabytedb/meko-mcp@latest ` +
-  "--capture-cleanup drain --all` to send, or `resume` to hand back to the hooks";
+  "--capture-cleanup fix` to send it, or `resume` to hand back to the hooks";
+// A conversation reopened this many times was replayed into over and over
+// (one session reached epoch 7,496); its trace is likely too large to serve.
+const REPLAY_EPOCH_THRESHOLD = 20;
 const PENDING_DELIVERIES = [
   "needs_conversation",
   "pending",
@@ -63,7 +86,7 @@ const PENDING_DELIVERIES = [
 ];
 // capture.js modes that run in the background. Foreground hook modes
 // (session-start, pre-compact) belong to a live client and are left alone.
-const BACKGROUND_CAPTURE_MODES = ["drain", "recover", "checkpoint", "session-end"];
+const BACKGROUND_CAPTURE_MODES = ["drain", "recover", "checkpoint", "session-end", "move"];
 const DEFAULT_MAX_EXCHANGES = 200;
 const DEFAULT_PACE_MS = 1000;
 const KILL_WAIT_MS = 3000;
@@ -74,6 +97,7 @@ const REPARK_ATTEMPTS = 10;
 const REPARK_RETRY_MS = 1000;
 const LEASE_POLL_MS = 500;
 const MAX_LEASE_WAITS = 5;
+const MAX_MOVES_PER_DRAIN = 1;
 
 // ---------------------------------------------------------------------------
 // Args
@@ -81,9 +105,9 @@ const MAX_LEASE_WAITS = 5;
 
 function usage() {
   return (
-    "Usage: capture-cleanup-cli.js <status|stop|resume|drain|discard|repair>\n" +
+    "Usage: capture-cleanup-cli.js <status|fix|stop|resume|drain|discard|repair>\n" +
     "         [--session <id>]... [--all] [--dry-run] [--json] [--yes]\n" +
-    "         [--max-exchanges N] [--pace-ms N]\n"
+    "         [--max-exchanges N] [--pace-ms N] [--auto]\n"
   );
 }
 
@@ -95,6 +119,7 @@ function parseArgs(argv) {
     dryRun: false,
     json: false,
     yes: false,
+    auto: false,
     maxExchanges: DEFAULT_MAX_EXCHANGES,
     paceMs: DEFAULT_PACE_MS,
   };
@@ -118,6 +143,7 @@ function parseArgs(argv) {
     else if (a === "--dry-run") out.dryRun = true;
     else if (a === "--json") out.json = true;
     else if (a === "--yes") out.yes = true;
+    else if (a === "--auto") out.auto = true;
     else if (a === "--max-exchanges") out.maxExchanges = intArg(a, next());
     else if (a === "--pace-ms") out.paceMs = intArg(a, next());
     else if (!a.startsWith("-") && !out.action) out.action = a;
@@ -390,6 +416,13 @@ function parkedState(state, reason, nowIso) {
   };
 }
 
+const PAUSED_BY_USER = "paused by the user with stop";
+
+/** A session the user parked with `stop`, while that park is in effect. */
+function stoppedByUser(state) {
+  return isParked(state) && state.parked.reason === "stop";
+}
+
 /**
  * Retry fields for a session handed back to capture.js. A failure that was
  * `persistent` with scope `exchange` is what lets capture.js skip one
@@ -497,6 +530,19 @@ function waitForLease(sessionId, maxMs) {
   return false;
 }
 
+/**
+ * capture.js answers retry_wait with no failure class and no error when it
+ * has just moved the session's backlog to a new conversation (MEKO-723).
+ */
+function movedToNewConversation(result) {
+  return Boolean(
+    result &&
+      result.status === "retry_wait" &&
+      !result.failure_class &&
+      !result.error,
+  );
+}
+
 function heldByAnotherWorker(result) {
   return (
     result &&
@@ -511,7 +557,7 @@ function heldByAnotherWorker(result) {
 // ---------------------------------------------------------------------------
 
 const HOOK_SCRIPT_RE =
-  /hooks-handlers[\\/]lib[\\/](checkpoint-timer|terminal-handoff|capture)\.js(?:\s+(\S+))?(?:\s+(\S+))?/;
+  /hooks-handlers[\\/]lib[\\/](checkpoint-timer|terminal-handoff|capture|capture-cleanup-cli)\.js(?:\s+(\S+))?(?:\s+(\S+))?/;
 
 /**
  * List background capture processes from `ps`. Returns { ok, processes,
@@ -555,6 +601,9 @@ function listCaptureProcesses() {
       kind = "session_end_worker";
       jobFile = hit[3] || null;
       sessionId = sessionFromJobFile(jobFile);
+    } else if (script === "capture-cleanup-cli" && hit[2] === "fix" && /\s--auto(\s|$)/.test(command)) {
+      // An automatic repair run started by a checkpoint timer.
+      kind = "autofix_run";
     } else if (script === "capture" && BACKGROUND_CAPTURE_MODES.includes(hit[2])) {
       kind = `capture_${hit[2].replace("-", "_")}`;
     }
@@ -689,7 +738,10 @@ function resolveCredentials() {
     MEKO_API_KEY: process.env.MEKO_API_KEY || "",
   };
   let source = env.MEKO_MCP_URL ? "environment" : null;
-  if (!env.MEKO_MCP_URL) {
+  // The checkpoint timer sets MEKO_CLEANUP_ENV_ONLY for automatic runs: a
+  // client whose hook credentials were removed must not borrow Claude
+  // Code's from settings.json.
+  if (!env.MEKO_MCP_URL && !process.env.MEKO_CLEANUP_ENV_ONLY) {
     const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
     try {
       const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
@@ -715,6 +767,7 @@ function resolveCredentials() {
 function drainSucceeded(result) {
   if (!result) return false;
   if (result.status === "ok" || result.status === "noop") return true;
+  if (movedToNewConversation(result)) return true;
   return result.status === "partial" && !result.failure_class && !result.error;
 }
 
@@ -769,6 +822,20 @@ function refreshHealthCache() {
   return health;
 }
 
+function describeLastFix(last) {
+  if (!last || !last.ran_at) return null;
+  const c = last.counts || {};
+  const parts = [`fixed ${c.fixed || 0}`];
+  if (c.moved) parts.push(`moved ${c.moved}`);
+  if (c.paused) parts.push(`left paused ${c.paused}`);
+  if (c.failed) parts.push(`failed ${c.failed}`);
+  if (c.not_attempted) parts.push(`not attempted ${c.not_attempted}`);
+  for (const n of last.needs_you || []) parts.push(`needs you (${n.cause}): ${n.sessions}`);
+  if (last.error) parts.push(`error: ${String(last.error).slice(0, 120)}`);
+  if (last.running) parts.push("did not finish");
+  return `${last.mode === "auto" ? "automatic" : "manual"} run at ${last.ran_at}: ${parts.join(", ")}`;
+}
+
 function actionStatus(opts) {
   const nowMs = Date.now();
   const entries = scan();
@@ -794,6 +861,8 @@ function actionStatus(opts) {
     action: "status",
     watermark_dir: cs.watermarkDir(),
     total_sessions: summaries.length,
+    last_fix: cs.readAutofixLast(),
+    autofix: { ...cs.autofixSetting(), interval_seconds: cs.autofixIntervalSeconds() },
     sessions: selected,
     processes: procs.processes,
     process_scan_error: procs.ok ? null : procs.error,
@@ -854,6 +923,35 @@ function actionStop(opts) {
     : [];
   // Stop processes before parking: a drain that is mid-flight would
   // otherwise commit its own state over the park.
+  // An automatic repair run for this directory: the child of the timer that
+  // holds this directory's autofix.lock. Matching by name alone could stop
+  // another directory's run.
+  if (procs.ok && opts.sessions.length === 0) {
+    let lockPid = NaN;
+    let runPid = NaN;
+    try {
+      const lock = JSON.parse(fs.readFileSync(path.join(cs.watermarkDir(), "autofix.lock"), "utf8"));
+      lockPid = Number(lock.pid);
+      runPid = Number(lock.run_pid);
+    } catch {
+      lockPid = NaN;
+      runPid = NaN;
+    }
+    // A run outlives a timer that was killed, and is then reparented, so
+    // also match the run's own PID from the lock.
+    for (const p of procs.processes) {
+      if (p.kind === "autofix_run" && (p.ppid === lockPid || p.pid === runPid) && !targets.includes(p)) targets.push(p);
+    }
+  }
+  // Stopping the automatic run's wrapper doesn't stop the capture.js child it
+  // is blocked on, so stop those children too and wait for them before
+  // parking.
+  const autofixPids = new Set(targets.filter((p) => p.kind === "autofix_run").map((p) => p.pid));
+  if (procs.ok) {
+    for (const p of procs.processes) {
+      if (p.kind.startsWith("capture_") && autofixPids.has(p.ppid) && !targets.includes(p)) targets.push(p);
+    }
+  }
   let killed = [];
   if (!opts.dryRun) {
     killed = killProcesses(targets);
@@ -867,7 +965,9 @@ function actionStop(opts) {
         selected.map((e) => e.session_id),
         opts,
         activeIds,
-      ).filter((p) => p.kind.startsWith("capture_") && !seen.has(p.pid));
+      )
+        .concat(again.processes.filter((p) => p.kind.startsWith("capture_") && autofixPids.has(p.ppid)))
+        .filter((p, i, all) => p.kind.startsWith("capture_") && !seen.has(p.pid) && all.indexOf(p) === i);
       killed = killed.concat(killProcesses(late));
     }
   }
@@ -922,71 +1022,46 @@ function actionResume(opts) {
   };
 }
 
-function actionDrain(opts, log) {
-  if (opts.sessions.length === 0 && !opts.all) {
-    return { action: "drain", errors: ["drain needs --session <id> or --all"], exit: 1 };
-  }
-  const { env, source } = resolveCredentials();
-  if (!env.MEKO_MCP_URL) {
-    return {
-      action: "drain",
-      errors: [
-        "MEKO_MCP_URL is not set and ~/.claude/settings.json has no env.MEKO_MCP_URL; " +
-          "export MEKO_MCP_URL and MEKO_API_KEY, then retry",
-      ],
-      exit: 1,
-    };
-  }
-  const nowMs = Date.now();
-  const entries = scan();
-  const { entries: selected, errors } = selectEntries(entries, opts, null);
-  const targets = selected.filter((e) => e.ok && hasPendingWork(e.state));
-  const results = [];
-  // Say why a session named on the command line isn't drained, instead of
-  // "nothing to do".
-  if (opts.sessions.length > 0) {
-    for (const e of selected) {
-      if (targets.includes(e)) continue;
-      let reason = "nothing to send";
-      if (!e.ok) reason = "watermark unreadable";
-      else if (hasStaleFailure(e.state)) {
-        reason =
-          "nothing to send; only leftover failure fields remain. Run `--capture-cleanup repair` to clear them";
-      }
-      results.push({ session_id: e.session_id, outcome: "skipped", reason });
-    }
+/**
+ * Drain one session in the foreground until it is empty, fails, or the
+ * shared `ctx.budget` runs out. Unparks first and parks again on failure.
+ * Returns { result, stop }: `stop` asks the caller not to attempt later
+ * sessions, because the failure may be the server's.
+ */
+function drainOneSession(e, opts, ctx, options) {
+  const sid = e.session_id;
+  const log = ctx.log;
+  // freshEntry() returns no state when the watermark can't be read; report
+  // that session as failed instead of throwing and ending the whole run.
+  if (!e.ok || !e.state) {
+    return { result: { session_id: sid, outcome: "failed", reason: e.error || "could not read the session state" }, stop: false };
   }
-  let budget = opts.maxExchanges;
-  let stopped = null;
-
-  for (const e of targets) {
-    const sid = e.session_id;
-    if (stopped) {
-      results.push({ session_id: sid, outcome: "not_attempted" });
-      continue;
-    }
-    if (budget <= 0) {
-      results.push({ session_id: sid, outcome: "not_attempted", reason: "--max-exchanges reached" });
-      continue;
-    }
-    if (opts.dryRun) {
-      results.push({ session_id: sid, outcome: "would_drain", queued_exchanges: Number(e.state.queued_exchanges) || 0 });
-      continue;
-    }
-    const wasParked = isParked(e.state);
+  {
+    // A caller that already changed the state (a move ends the park) passes
+    // whether the session was parked before, so "a parked session stays
+    // parked" still holds for partial and skipped drains.
+    const wasParked =
+      Boolean(options && options.wasParked) || isParked(e.state);
     let state = e.state;
     if (wasParked || state.failure_class) {
-      const res = mutate(sid, (current) =>
-        isParked(current) ? unparkedState(current) : handBackState(current),
-      );
+      const res = mutate(sid, (current) => {
+        // An automatic run scanned before the user may have run `stop`;
+        // check the current state under the lease, not the scan.
+        if (opts.auto && stoppedByUser(current)) {
+          return { ok: false, error: PAUSED_BY_USER };
+        }
+        return isParked(current) ? unparkedState(current) : handBackState(current);
+      });
+      if (!res.ok && res.error === PAUSED_BY_USER) {
+        return { result: { session_id: sid, outcome: "paused_by_user" }, stop: false };
+      }
       if (!res.ok) {
-        results.push({ session_id: sid, outcome: res.busy ? "busy" : "failed", reason: res.error });
-        continue;
+        return { result: { session_id: sid, outcome: res.busy ? "busy" : "failed", reason: res.error }, stop: false };
       }
       state = res.state;
     }
 
-    const live = looksLive(state, transcriptInfo(state), nowMs);
+    const live = looksLive(state, transcriptInfo(state), ctx.nowMs);
     // Never rebucket from here: this process's cwd says nothing about the
     // session's owner. A session whose client is gone is finalized the way
     // timer recovery does it.
@@ -995,11 +1070,13 @@ function actionDrain(opts, log) {
     let last = null;
     let stderr = "";
     let leaseWaits = 0;
+    let moves = 0;
+    let stop = false;
     for (;;) {
       const run = runCaptureChild(
         mode,
-        { session_id: sid, recorded_owner_only: true, max_exchanges: Math.min(budget, cs.maxCaptureBatchSize()) },
-        env,
+        { session_id: sid, recorded_owner_only: true, max_exchanges: Math.min(ctx.budget, cs.maxCaptureBatchSize()) },
+        ctx.env,
       );
       last = run.result;
       stderr = run.stderr;
@@ -1012,10 +1089,17 @@ function actionDrain(opts, log) {
         if (waitForLease(sid, waitMs)) continue;
       }
       captured += Number(last.captured) || 0;
-      budget -= Number(last.captured) || 0;
+      ctx.budget -= Number(last.captured) || 0;
       const remaining = Number(last.queued_remaining) || 0;
       if (!drainSucceeded(last)) break;
-      if (remaining === 0 || !last.captured || budget <= 0) break;
+      if (movedToNewConversation(last) && moves < MAX_MOVES_PER_DRAIN) {
+        // capture.js moved the backlog to a new conversation (MEKO-723);
+        // nothing was sent yet, so drain again into it.
+        moves++;
+        log(`  ${sid.slice(0, 8)}: moved to a new conversation; continuing`);
+        continue;
+      }
+      if (remaining === 0 || !last.captured || ctx.budget <= 0) break;
       log(`  ${sid.slice(0, 8)}: sent ${captured}, ${remaining} left`);
       sleepHoldingLease(sid, opts.paceMs);
     }
@@ -1033,7 +1117,7 @@ function actionDrain(opts, log) {
       // hold the lease right now (that is often why the drain failed), so
       // retry, and say so when the park doesn't land.
       const res = repark(`drain failed: ${last.error || last.status}`);
-      stopped = sid;
+      stop = true;
       outcome = res.ok ? "failed_and_parked" : "failed_not_parked";
       if (!res.ok) reparkError = res.error;
     } else if (last.status === "noop" && last.error && captured === 0) {
@@ -1058,7 +1142,9 @@ function actionDrain(opts, log) {
     } else {
       outcome = "drained";
     }
-    results.push({
+    return {
+      stop,
+      result: {
       session_id: sid,
       outcome,
       captured,
@@ -1067,9 +1153,68 @@ function actionDrain(opts, log) {
       error: last.error || null,
       repark_error: reparkError || undefined,
       stderr: ok ? undefined : stderr || undefined,
-    });
+      },
+    };
+  }
+}
+
+function actionDrain(opts, log) {
+  if (opts.sessions.length === 0 && !opts.all) {
+    return { action: "drain", errors: ["drain needs --session <id> or --all"], exit: 1 };
+  }
+  const { env, source } = resolveCredentials();
+  if (!env.MEKO_MCP_URL) {
+    return {
+      action: "drain",
+      errors: [
+        "MEKO_MCP_URL is not set and ~/.claude/settings.json has no env.MEKO_MCP_URL; " +
+          "export MEKO_MCP_URL and MEKO_API_KEY, then retry",
+      ],
+      exit: 1,
+    };
+  }
+  const nowMs = Date.now();
+  const entries = scan();
+  const { entries: selected, errors } = selectEntries(entries, opts, null);
+  const targets = selected.filter((e) => e.ok && hasPendingWork(e.state));
+  const results = [];
+  // Say why a session named on the command line isn't drained, instead of
+  // "nothing to do".
+  if (opts.sessions.length > 0) {
+    for (const e of selected) {
+      if (targets.includes(e)) continue;
+      let reason = "nothing to send";
+      if (!e.ok) reason = "watermark unreadable";
+      else if (hasStaleFailure(e.state)) {
+        reason =
+          "nothing to send; only leftover failure fields remain. Run `--capture-cleanup repair` to clear them";
+      }
+      results.push({ session_id: e.session_id, outcome: "skipped", reason });
+    }
+  }
+  const ctx = { env, log, nowMs, budget: opts.maxExchanges };
+  let stopped = null;
+
+  for (const e of targets) {
+    const sid = e.session_id;
+    if (stopped) {
+      results.push({ session_id: sid, outcome: "not_attempted" });
+      continue;
+    }
+    if (ctx.budget <= 0) {
+      results.push({ session_id: sid, outcome: "not_attempted", reason: "--max-exchanges reached" });
+      continue;
+    }
+    if (opts.dryRun) {
+      results.push({ session_id: sid, outcome: "would_drain", queued_exchanges: Number(e.state.queued_exchanges) || 0 });
+      continue;
+    }
+    const { result, stop } = drainOneSession(e, opts, ctx);
+    results.push(result);
+    if (stop) stopped = sid;
+    const outcome = result.outcome;
     if (!["drained", "skipped", "skipped_and_parked"].includes(outcome)) continue;
-    if (budget > 0) sleepMs(opts.paceMs);
+    if (ctx.budget > 0) sleepMs(opts.paceMs);
   }
   if (!opts.dryRun) refreshHealthCache();
   const partial =
@@ -1166,6 +1311,502 @@ function actionDiscard(opts) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Diagnose and fix
+// ---------------------------------------------------------------------------
+
+function lastErrorOf(state) {
+  const previous = isParked(state) && state.parked.previous;
+  return String((previous && previous.last_error) || state.last_error || "");
+}
+
+/**
+ * A failure that says the server, not this session, is in trouble. An error
+ * about this session's conversation ("Could not look up conversation <id>:
+ * timed out") is about the conversation, even when it mentions a timeout.
+ */
+function serverLevelFailure(error) {
+  if (conversationUnusable(error)) return false;
+  return /timed out|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|socket hang up|connection refused|MCP HTTP 5\d\d/i.test(
+    String(error || ""),
+  );
+}
+
+/** Errors that mean the recorded conversation itself can't be used. */
+function conversationUnusable(error) {
+  return /agent_id_mismatch|lookup_failed|conversation\s+\S+\s+not\s+found|"not_found"/i.test(
+    String(error || ""),
+  );
+}
+
+/**
+ * Causes only the user can fix. Matches the server's error codes and the
+ * reasons capture.js stores in last_error (classifyPersistentCaptureFailure),
+ * for example "the account does not have access to the target datapack".
+ * Returns { cause, hint } or null.
+ */
+function userActionableCause(error) {
+  const err = String(error || "");
+  if (/\b401\b|unauthori[sz]ed|invalid[_\s-]?api[_\s-]?key/i.test(err)) {
+    return {
+      cause: "auth",
+      hint: "the server rejected the API key; fix MEKO_API_KEY, then run fix again",
+    };
+  }
+  if (
+    /datapack_id_required|datapack_access_denied|read_only_access|access to the target datapack|datapack[^"]*(denied|missing|invalid|mismatch)/i.test(
+      err,
+    )
+  ) {
+    return {
+      cause: "datapack",
+      hint: "this account can't write to the session's datapack; pin another datapack with meko-select-datapack or get write access, then run fix again",
+    };
+  }
+  if (
+    /\b402\b|payment|quota|free[_\s-]?tier|subscription|entitle|plan[_\s-]?limit|plan's capture limit|usage[_\s-]?limit|capture usage limit/i.test(
+      err,
+    )
+  ) {
+    return {
+      cause: "account_limit",
+      hint: "the account hit a plan or capture limit; upgrade or wait, then run fix again",
+    };
+  }
+  if (/Meko rejected capture with HTTP 403/i.test(err)) {
+    return {
+      cause: "forbidden",
+      hint: "the server refused capture (HTTP 403); check the account's access, then run fix again",
+    };
+  }
+  return null;
+}
+
+/**
+ * Why a session is stuck and what fixes it. Returns null for a session with
+ * nothing to fix. Actions: repair, drain, move (to a new conversation, then
+ * drain), drain_then_move, retry_once (a cause only the user can fix: one
+ * attempt per run, then report), or none (an unreadable watermark).
+ */
+function diagnose(entry) {
+  if (!entry.ok) {
+    return {
+      cause: "unreadable",
+      action: "none",
+      hint: "the watermark can't be read; it is left on disk for inspection",
+    };
+  }
+  const s = entry.state;
+  if (hasStaleFailure(s)) {
+    return {
+      cause: "stale_failure",
+      action: "repair",
+      hint: "everything was delivered; only leftover failure fields remain",
+    };
+  }
+  if (!hasPendingWork(s) && !isParked(s)) return null;
+  const err = lastErrorOf(s);
+  const epoch = Number(s.conversation_epoch) || 0;
+  const userCause = userActionableCause(err);
+  if (userCause) {
+    // Try once per run: the user usually runs fix right after changing the
+    // key, plan or access. If it fails the same way, fix reports needs_you
+    // and the session stays parked, so the hooks don't retry it.
+    return { ...userCause, action: "retry_once" };
+  }
+  // A session that was just moved to a new conversation waits for that
+  // conversation to accept a turn before it can be moved again (the guard
+  // from MEKO-723). Moving again would recreate the replay loop.
+  if (s.recovered_from_conversation_id) {
+    return {
+      cause: "awaiting_new_conversation",
+      action: "drain",
+      hint: "already moved to a new conversation that hasn't accepted a turn yet",
+    };
+  }
+  if (/agent_id_mismatch/i.test(err)) {
+    return {
+      cause: "owner_lost",
+      action: "move",
+      hint: "the server no longer recognizes this conversation's owner",
+    };
+  }
+  // conversation_epoch only goes up over a session's life, so count the
+  // epochs since this tool last moved the session, and only when a failure
+  // is recorded; a healthy session moved off a high epoch stays put.
+  const epochsSinceMove = epoch - (Number(s.cleanup_moved_epoch) || 0);
+  if (err && epochsSinceMove >= REPLAY_EPOCH_THRESHOLD) {
+    return {
+      cause: "replay_loop",
+      action: "move",
+      hint: `the conversation was reopened ${epochsSinceMove} times; its trace is likely too large to serve`,
+    };
+  }
+  if (/lookup_failed/i.test(err)) {
+    return {
+      cause: "lookup_failing",
+      action: "drain_then_move",
+      hint: "the server couldn't look the conversation up",
+    };
+  }
+  if (/conversation\s+\S+\s+not\s+found|"not_found"/i.test(err)) {
+    return {
+      cause: "conversation_missing",
+      action: "drain_then_move",
+      hint: "the server answered not_found for the conversation",
+    };
+  }
+  return { cause: "retry", action: "drain", hint: err ? `last error: ${err.slice(0, 120)}` : "unsent turns are waiting" };
+}
+
+/**
+ * Run `capture.js move` for one session. `expectedConversation` is the
+ * conversation fix diagnosed; the move is refused (`changed`) if the session
+ * no longer points at it when the lease is taken.
+ */
+function moveSession(sid, ctx, expectedConversation) {
+  const run = runCaptureChild(
+    "move",
+    {
+      session_id: sid,
+      expected_conversation_id: expectedConversation || undefined,
+      respect_stop: ctx.auto ? true : undefined,
+      defer_if_live: true,
+    },
+    ctx.env,
+  );
+  const r = run.result || {};
+  if (r.ok) return { ok: true, from: r.from, to: r.to };
+  return {
+    ok: false,
+    busy: Boolean(r.busy),
+    changed: Boolean(r.changed),
+    paused: Boolean(r.paused),
+    deferred: Boolean(r.deferred),
+    error: r.error || run.stderr || "move failed",
+  };
+}
+
+function freshEntry(sid) {
+  const read = cs.readState(sid);
+  return read.ok
+    ? { ok: true, session_id: sid, state: read.state }
+    : { ok: false, session_id: sid, error: read.error };
+}
+
+/**
+ * Move to a new conversation, then drain. The move itself ends a park (it
+ * resets the retry fields), so nothing is unparked first. A busy move, or
+ * one refused because the session changed while waiting, leaves the
+ * watermark untouched; a move that fails is parked with its diagnosed error.
+ * `wasParked` is the session's parked status before fix touched it.
+ */
+function moveThenDrain(e, opts, ctx, wasParkedBefore) {
+  const sid = e.session_id;
+  const wasParked = wasParkedBefore != null ? Boolean(wasParkedBefore) : isParked(e.state);
+  const diagnosedError = lastErrorOf(e.state);
+  const expected = e.state.conversation_id;
+  let moved = moveSession(sid, ctx, expected);
+  for (let waits = 0; !moved.ok && moved.busy && waits < MAX_LEASE_WAITS; waits++) {
+    // A hook is draining this session; wait for it rather than give up.
+    ctx.log(`  ${sid.slice(0, 8)}: another worker holds the lease; waiting`);
+    const waitMs = (cs.leaseTtlSeconds() + cs.checkpointTimeout()) * 1000;
+    if (!waitForLease(sid, waitMs)) break;
+    moved = moveSession(sid, ctx, expected);
+  }
+  if (!moved.ok && moved.busy) {
+    return { result: { session_id: sid, outcome: "busy", reason: moved.error }, stop: false };
+  }
+  if (!moved.ok && moved.paused) {
+    return { result: { session_id: sid, outcome: "paused_by_user" }, stop: false };
+  }
+  if (!moved.ok && moved.deferred) {
+    // The session became live after fix planned the move; capture.js
+    // refused it under the lease. A later fix moves it after it ends.
+    return {
+      result: { session_id: sid, outcome: "move_deferred", reason: "the session is still open; fix moves it to a new conversation after the session ends" },
+      stop: false,
+    };
+  }
+  if (!moved.ok && moved.changed) {
+    // A hook recovered or delivered the session while fix waited for the
+    // lease. Don't create another conversation; drain what is there now.
+    ctx.log(`  ${sid.slice(0, 8)}: ${moved.error}; draining instead of moving`);
+    const drained = drainOneSession(freshEntry(sid), opts, ctx, { wasParked });
+    drained.result.move_skipped = moved.error;
+    return drained;
+  }
+  if (!moved.ok) {
+    // Keep the diagnosed error, so the next fix still sees why the session
+    // needs a move.
+    const parked = mutateWithRetry(sid, (current) =>
+      isParked(current)
+        ? current
+        : parkedState(
+            { ...current, last_error: current.last_error || diagnosedError || null },
+            `move failed: ${moved.error}`,
+            new Date().toISOString(),
+          ),
+    );
+    return {
+      result: {
+        session_id: sid,
+        outcome: parked.ok ? "move_failed_and_parked" : "move_failed_not_parked",
+        error: moved.error,
+      },
+      stop: serverLevelFailure(moved.error),
+    };
+  }
+  ctx.log(`  ${sid.slice(0, 8)}: moved to new conversation ${moved.to}`);
+  const drained = drainOneSession(freshEntry(sid), opts, ctx, { wasParked });
+  drained.result.moved_from = moved.from;
+  drained.result.moved_to = moved.to;
+  return drained;
+}
+
+/**
+ * The datapack an agent's pin file names, read the way capture.js
+ * readDatapackPin() does (pin-<slug>.json in the capture directory), or null.
+ */
+function pinnedDatapackId(agentId) {
+  if (!agentId) return null;
+  try {
+    const pin = JSON.parse(
+      fs.readFileSync(path.join(cs.watermarkDir(), `pin-${cs.agentSlug(agentId)}.json`), "utf8"),
+    );
+    const id = typeof pin.datapack_id === "string" ? pin.datapack_id.trim() : "";
+    const name = typeof pin.datapack_name === "string" ? pin.datapack_name.trim() : "";
+    return id && name ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record what a fix run did in autofix-last.json. The status bar and
+ * `status` read it, and the checkpoint timer uses ran_at to schedule the
+ * next automatic run.
+ */
+function writeFixSummary(opts, results, stopped, error) {
+  const counts = { fixed: 0, moved: 0, needs_you: 0, paused: 0, failed: 0, not_attempted: 0, partial: 0 };
+  const needs = new Map();
+  for (const r of results) {
+    const o = String(r.outcome || "");
+    if (o === "drained" || o === "repaired") counts.fixed++;
+    if (r.moved_to) counts.moved++;
+    if (o === "needs_you") {
+      counts.needs_you++;
+      const n = needs.get(r.cause) || { cause: r.cause, hint: r.hint, sessions: 0 };
+      n.sessions++;
+      needs.set(r.cause, n);
+    }
+    if (o === "paused_by_user") counts.paused++;
+    if (o.includes("failed")) counts.failed++;
+    if (o === "not_attempted" || o === "busy" || o === "move_deferred") counts.not_attempted++;
+    if (o.startsWith("partly_drained")) counts.partial++;
+  }
+  try {
+    cs.atomicWriteJson(cs.autofixLastPath(), {
+      schema_version: 1,
+      ran_at: new Date().toISOString(),
+      mode: opts.auto ? "auto" : "manual",
+      error: error || null,
+      stopped_at: stopped || null,
+      counts,
+      needs_you: [...needs.values()],
+    });
+  } catch {
+    /* the summary is informational; the run itself already happened */
+  }
+}
+
+function actionFix(opts, log) {
+  const entries = scan();
+  const { entries: selected, errors } = selectEntries(entries, opts, null);
+  const plan = [];
+  for (const e of selected) {
+    const d = diagnose(e);
+    if (d) plan.push({ entry: e, diagnosis: d });
+    else if (opts.sessions.length > 0) {
+      plan.push({ entry: e, diagnosis: null });
+    }
+  }
+  const needsServer = plan.some(
+    (p) => p.diagnosis && ["drain", "move", "drain_then_move", "retry_once"].includes(p.diagnosis.action),
+  );
+  const { env, source } = resolveCredentials();
+  if (needsServer && !env.MEKO_MCP_URL && !opts.dryRun) {
+    const message =
+      "MEKO_MCP_URL is not set and ~/.claude/settings.json has no env.MEKO_MCP_URL; " +
+      "export MEKO_MCP_URL and MEKO_API_KEY, then retry";
+    writeFixSummary(opts, [], null, message);
+    refreshHealthCache();
+    return { action: "fix", errors: [message], exit: 1 };
+  }
+  const ctx = { env, log, nowMs: Date.now(), budget: opts.maxExchanges, auto: opts.auto };
+  const results = [];
+  let stopped = null;
+  // Causes only the user can fix, found earlier in this run. A rejected key,
+  // a plan limit or an account-level 403 affects every session; a datapack
+  // problem affects the sessions in that datapack. Trying the rest would
+  // only repeat the same failure.
+  const blockedBy = new Map();
+  // A session with no datapack in its watermark drains to its agent's pin
+  // (capture.js re-reads it), so key it by that pinned datapack. Only an
+  // agent with no pin falls back to a per-agent key.
+  const datapackKey = (state) => {
+    const id = (state && state.datapack_id) || pinnedDatapackId(state && state.agent_id);
+    return id ? `datapack:${id}` : `datapack-of-agent:${(state && state.agent_id) || ""}`;
+  };
+  const blockKeys = (state, cause) => (cause === "datapack" ? [datapackKey(state)] : ["account"]);
+  const blockedFor = (state) => blockedBy.get("account") || blockedBy.get(datapackKey(state)) || null;
+
+  for (const { entry: e, diagnosis: d } of plan) {
+    const sid = e.session_id;
+    if (!d) {
+      results.push({ session_id: sid, outcome: "nothing_to_fix" });
+      continue;
+    }
+    const base = { session_id: sid, cause: d.cause, action: d.action, hint: d.hint };
+    if (
+      opts.auto &&
+      e.ok &&
+      isParked(e.state) &&
+      e.state.parked.reason === "stop"
+    ) {
+      // The user paused this session with `stop`; an automatic run leaves
+      // it alone until they run `fix` or `resume`.
+      results.push({ ...base, outcome: "paused_by_user" });
+      continue;
+    }
+    if (opts.dryRun) {
+      results.push({ ...base, outcome: "would_fix" });
+      continue;
+    }
+    if (d.action === "none") {
+      results.push({ ...base, outcome: "needs_you" });
+      continue;
+    }
+    if (d.action === "repair") {
+      const res = mutate(sid, (state) => (hasStaleFailure(state) ? clearedFailureState(state) : state));
+      results.push({ ...base, outcome: res.ok ? "repaired" : res.busy ? "busy" : "failed", reason: res.ok ? undefined : res.error });
+      continue;
+    }
+    if (stopped) {
+      results.push({ ...base, outcome: "not_attempted", reason: `stopped at ${stopped.slice(0, 8)}: the server is failing` });
+      continue;
+    }
+    if (ctx.budget <= 0) {
+      results.push({ ...base, outcome: "not_attempted", reason: "--max-exchanges reached" });
+      continue;
+    }
+    const blocked = e.ok && blockedFor(e.state);
+    if (blocked) {
+      // Park it with the shared cause, without another request, so its
+      // hooks stop sending the same rejected key or limit too. The next fix
+      // retries one session per cause.
+      const parked = mutateWithRetry(sid, (current) => {
+        if (opts.auto && stoppedByUser(current)) return current;
+        return isParked(current)
+          ? current
+          : parkedState(
+              { ...current, last_error: blocked.error || current.last_error || null },
+              `${blocked.cause}: same cause as another session`,
+              new Date().toISOString(),
+            );
+      });
+      results.push({
+        ...base,
+        cause: blocked.cause,
+        hint: blocked.hint,
+        outcome: parked.ok ? "needs_you" : "needs_you_not_parked",
+        reason: "not tried: another session hit the same cause in this run",
+      });
+      continue;
+    }
+
+    let run;
+    const wasParkedBefore = isParked(e.state);
+    // SessionStart gave a live session's agent its conversation_id, and a
+    // move can't tell the agent the new one, so its tool calls would stay on
+    // the old conversation while captured turns go to the new one. Wait until
+    // the session ends; a later fix moves it.
+    const deferMove = looksLive(e.state, transcriptInfo(e.state), ctx.nowMs);
+    if (d.action === "move" && deferMove) {
+      results.push({ ...base, outcome: "move_deferred", reason: "the session is still open; fix moves it to a new conversation after the session ends" });
+      continue;
+    }
+    if (d.action === "move") {
+      run = moveThenDrain(e, opts, ctx, wasParkedBefore);
+    } else {
+      const diagnosedConversation = e.state.conversation_id;
+      run = drainOneSession(e, opts, ctx);
+      const err = run.result.error;
+      if (
+        d.action === "drain_then_move" &&
+        !["drained", "skipped"].includes(run.result.outcome) &&
+        !serverLevelFailure(err) &&
+        conversationUnusable(err)
+      ) {
+        // The same conversation error came back. Move only if it is still
+        // about the conversation diagnosed above and no move is waiting for
+        // its new conversation to accept a turn; capture.js may already have
+        // moved the session during this drain.
+        const now = freshEntry(sid);
+        const sameConversation = now.ok && now.state.conversation_id === diagnosedConversation;
+        const guarded = now.ok && Boolean(now.state.recovered_from_conversation_id);
+        if (sameConversation && !guarded && deferMove) {
+          log(`  ${sid.slice(0, 8)}: ${String(err).slice(0, 80)}; the session is still open, so the move waits until it ends`);
+          run = { ...run, result: { ...run.result, move_deferred: true } };
+        } else if (sameConversation && !guarded) {
+          log(`  ${sid.slice(0, 8)}: ${String(err).slice(0, 80)}; moving to a new conversation`);
+          // The failed drain just re-parked the session; keep its status
+          // from before fix ran.
+          run = moveThenDrain(now, opts, ctx, wasParkedBefore);
+        }
+      }
+    }
+    const userCause = run.result.outcome !== "drained" && userActionableCause(run.result.error);
+    if (userCause) {
+      // The drain found a cause only the user can fix (it may differ from the
+      // stored error). When the session is parked the hooks won't retry it,
+      // and the next fix tries it once more. When the park didn't land, keep
+      // the outcome that says so.
+      const parkedNow = /_and_parked$/.test(String(run.result.outcome));
+      for (const key of blockKeys(e.state, userCause.cause)) {
+        if (!blockedBy.has(key)) blockedBy.set(key, { ...userCause, error: run.result.error });
+      }
+      results.push({
+        ...base,
+        ...run.result,
+        ...userCause,
+        outcome: parkedNow ? "needs_you" : run.result.outcome,
+      });
+      continue;
+    }
+    results.push({ ...base, ...run.result });
+    if (run.stop && serverLevelFailure(run.result.error)) stopped = sid;
+    if (ctx.budget > 0) sleepMs(opts.paceMs);
+  }
+
+  if (!opts.dryRun) {
+    writeFixSummary(opts, results, stopped);
+    refreshHealthCache();
+  }
+  const done = ["repaired", "drained", "nothing_to_fix", "would_fix", "paused_by_user"];
+  const partial = results.some((r) => !done.includes(r.outcome));
+  return {
+    action: "fix",
+    dry_run: opts.dryRun,
+    credentials_from: needsServer ? source : undefined,
+    mcp_url: needsServer ? env.MEKO_MCP_URL : undefined,
+    stopped_at: stopped,
+    sessions: results,
+    errors,
+    exit: errors.length ? 1 : partial ? 2 : 0,
+  };
+}
+
 function readPidFile(filePath) {
   try {
     const raw = fs.readFileSync(filePath, "utf8").trim();
@@ -1307,6 +1948,18 @@ function formatBytes(n) {
 function formatStatus(report) {
   const lines = [];
   lines.push(`Capture state: ${report.watermark_dir} (${report.total_sessions} sessions)`);
+  const lastFix = describeLastFix(report.last_fix);
+  const auto = report.autofix || {};
+  lines.push(
+    `Automatic repair: ${
+      auto.enabled
+        ? `on, every ${Math.max(1, Math.round((auto.interval_seconds || 0) / 60))} minutes`
+        : auto.source === "env"
+          ? "off (MEKO_AUTOFIX in the environment)"
+          : `off (${auto.path || "autofix-config.json"}; reinstall with --autofix to turn it on)`
+    }` +
+      (lastFix ? `; last ${lastFix}` : ""),
+  );
   if (report.sessions.length === 0) {
     lines.push("No session has unsent work, a stale failure, or a park.");
   } else {
@@ -1372,6 +2025,8 @@ function formatActionResult(report) {
   if (report.mcp_url) lines.push(`  server: ${report.mcp_url} (credentials from ${report.credentials_from})`);
   for (const s of report.sessions || []) {
     const extra = [
+      s.cause ? `cause=${s.cause}` : null,
+      s.moved_to ? `new conversation ${short(s.moved_to)}` : null,
       s.queued_exchanges != null ? `queued=${s.queued_exchanges}` : null,
       s.captured != null ? `sent=${s.captured}` : null,
       s.queued_remaining != null && s.outcome !== "would_drain" ? `left=${s.queued_remaining}` : null,
@@ -1379,6 +2034,7 @@ function formatActionResult(report) {
       s.reason || s.error || null,
     ].filter(Boolean);
     lines.push(`  ${short(s.session_id)}  ${s.outcome}${extra.length ? `  ${extra.join("  ")}` : ""}`);
+    if (s.hint && ["needs_you", "would_fix"].includes(s.outcome)) lines.push(`    ${s.hint}`);
     if (s.stderr) lines.push(`    ${s.stderr.split("\n").join("\n    ")}`);
   }
   for (const f of report.files || []) {
@@ -1434,6 +2090,9 @@ function run(argv, io) {
       case "repair":
         report = actionRepair(opts);
         break;
+      case "fix":
+        report = actionFix(opts, log);
+        break;
       default:
         throw new Error(`unknown action ${opts.action}`);
     }
@@ -1457,6 +2116,8 @@ function run(argv, io) {
 module.exports = {
   parseArgs,
   run,
+  drainOneSession,
+  diagnose,
   hasPendingWork,
   hasStaleFailure,
   parkedState,