@yugabytedb/meko-mcp 2.2.0 → 2.3.0

package/assets/hooks-handlers/lib/capture-notices.js

@@ -5,11 +5,14 @@
  * CommonJS, zero npm deps. Safe to require from capture.js SessionStart
  * without touching the drain loop. See docs/plans/meko-capture-v2-contracts.md.
  *
- * Health cache field extension (documented):
+ * Health cache field extensions (documented):
  *   capture-health.json may include `last_notified_status` — the aggregate
  *   status last shown to the user via SessionStart. Used for one-shot
  *   recovery notices when status returns to `healthy`. writeHealthCache()
  *   preserves this field when callers omit it.
+ *
+ *   `last_notified_dropped` records the aggregate dropped-exchange count last
+ *   shown. A complete refresh may clamp it when session watermarks disappear.
  */
 
 "use strict";
@@ -17,10 +20,15 @@
 const {
   computeAggregateHealth,
   readHealthCache,
+  scanCompleteForDropClamp,
   scanStates,
   writeHealthCache,
 } = require("./capture-state");
 
+// blocked_reason prefix written by `--capture-cleanup stop`
+// (capture-cleanup-cli.js RESUME_HINT).
+const PARKED_REASON_PREFIX = "parked by capture cleanup";
+
 const NON_HEALTHY = new Set([
   "catching_up",
   "degraded_retrying",
@@ -99,14 +107,72 @@ function statuslineSuffixFromHealth(health) {
   return `capture:${short}(${queued})`;
 }
 
+/**
+ * Sentence describing exchanges that were skipped because the server will
+ * never accept them, or "" when there are none new to report.
+ *
+ * Drops are permanent, so they are not a health status — capture is running
+ * fine — but the user is owed the fact that specific turns are missing.
+ */
+function dropSentence(dropped, previouslyNotified, health) {
+  const newDrops = dropped - previouslyNotified;
+  if (newDrops <= 0) return "";
+  const reasons = Array.isArray(health && health.drop_reasons)
+    ? health.drop_reasons.filter(Boolean)
+    : [];
+  // drop_reasons is the union of every session's last_drop_reason, including
+  // drops already announced. Attribute a reason only when there is one shared
+  // cause; otherwise point at --capture-status instead of mis-blaming.
+  const because =
+    reasons.length === 1
+      ? ` Reason: ${reasons[0]}.`
+      : reasons.length > 1
+        ? " Run `meko-mcp --capture-status` for drop reasons."
+        : "";
+  return (
+    `[Meko capture] ${newDrops} exchange(s) could not be stored and were ` +
+    `skipped; the rest of the session is captured normally.${because} ` +
+    `Tell the user those turns are missing from Meko.`
+  );
+}
+
+/**
+ * True when some session is still retrying. A session parked by
+ * `--capture-cleanup stop` is blocked on purpose and never retries, so it
+ * doesn't count; its blocked reason already says how to resume it.
+ */
+function retriesRunning(health) {
+  // A degraded session with nothing left to send (leftover failure fields on
+  // a delivered session) isn't retrying; `repair` clears it, not `stop`.
+  const sessions = Array.isArray(health && health.sessions) ? health.sessions : [];
+  const retrying = sessions.some(
+    (s) =>
+      s &&
+      s.status === "degraded_retrying" &&
+      (Number(s.queued_exchanges || 0) > 0 ||
+        ["needs_conversation", "pending", "draining", "retry_wait"].includes(s.delivery)),
+  );
+  if (retrying) return true;
+  if (health.status !== "blocked_action_required") return false;
+  const reasons = Array.isArray(health.blocked_reasons)
+    ? health.blocked_reasons.filter(Boolean)
+    : [];
+  return (
+    reasons.length === 0 ||
+    reasons.some((r) => !String(r).startsWith(PARKED_REASON_PREFIX))
+  );
+}
+
 /**
  * Build a SessionStart-injectable health notice.
  *
  * - When status ≠ healthy: always emit (exact affected-session + queued counts + reason).
  * - When status === healthy and previousStatus was non-healthy: one-shot recovery notice.
  * - When status === healthy and previous was already healthy / null: no notice.
+ * - Any new dropped exchanges are appended in every case, and are enough on
+ *   their own to produce a notice while status is healthy.
  *
- * @param {{ health: object, previousStatus?: string|null }} opts
+ * @param {{ health: object, previousStatus?: string|null, previousDropped?: number }} opts
  * @returns {{
  *   notice: string|null,
  *   nextNotifiedStatus: string,
@@ -114,10 +180,11 @@ function statuslineSuffixFromHealth(health) {
  *   status: string,
  *   affectedSessions: number,
  *   queuedExchanges: number,
+ *   droppedExchanges: number,
  *   reason: string,
  * }}
  */
-function buildHealthNotice({ health, previousStatus } = {}) {
+function buildHealthNotice({ health, previousStatus, previousDropped } = {}) {
   const h = health && typeof health === "object" ? health : { status: "healthy" };
   const status = h.status || "healthy";
   const prev =
@@ -126,29 +193,37 @@ function buildHealthNotice({ health, previousStatus } = {}) {
       : String(previousStatus);
   const affected = affectedSessionCount(h);
   const queued = Number(h.queued_exchanges || 0);
+  const dropped = Number(h.dropped_exchanges || 0);
+  const notifiedDropped = Number(previousDropped || 0);
+  const drops = dropSentence(dropped, notifiedDropped, h);
   const reason = reasonForHealth(h);
+  const join = (a, b) => (a && b ? `${a}\n\n${b}` : a || b || null);
 
   if (status === "healthy") {
     if (prev && NON_HEALTHY.has(prev)) {
       return {
-        notice:
+        notice: join(
           "[Meko capture] Capture recovered — all sessions healthy. " +
-          "Queued backlog is clear. Automatic conversation capture is running normally again.",
+            "Queued backlog is clear. Automatic conversation capture is running normally again.",
+          drops,
+        ),
         nextNotifiedStatus: "healthy",
         shouldPersistNotified: true,
         status,
         affectedSessions: 0,
         queuedExchanges: queued,
+        droppedExchanges: dropped,
         reason,
       };
     }
     return {
-      notice: null,
+      notice: drops || null,
       nextNotifiedStatus: "healthy",
-      shouldPersistNotified: prev !== "healthy",
+      shouldPersistNotified: prev !== "healthy" || Boolean(drops),
       status,
       affectedSessions: 0,
       queuedExchanges: queued,
+      droppedExchanges: dropped,
       reason,
     };
   }
@@ -160,10 +235,17 @@ function buildHealthNotice({ health, previousStatus } = {}) {
         ? "degraded_retrying"
         : "catching_up";
 
-  const notice =
+  const cleanupHint = retriesRunning(h)
+    ? " If the user wants the retries to stop, offer " +
+      "`npx @yugabytedb/meko-mcp@latest --capture-cleanup stop`; it parks " +
+      "the backlog without deleting it."
+    : "";
+  const notice = join(
     `[Meko capture] Status: ${label} — ${affected} session(s) affected, ` +
-    `${queued} exchange(s) queued. Reason: ${reason}. ` +
-    `Run \`meko-mcp --capture-status\` for details.`;
+      `${queued} exchange(s) queued. Reason: ${reason}. ` +
+      `Run \`meko-mcp --capture-status\` for details.${cleanupHint}`,
+    drops,
+  );
 
   return {
     notice,
@@ -172,6 +254,7 @@ function buildHealthNotice({ health, previousStatus } = {}) {
     status,
     affectedSessions: affected,
     queuedExchanges: queued,
+    droppedExchanges: dropped,
     reason,
   };
 }
@@ -195,14 +278,23 @@ function injectHealthNotice(context, opts) {
   const base = context == null ? "" : String(context);
 
   let health = null;
+  let scanComplete = false;
   if (refresh) {
     const scan = scanStates({ includeBlocked: true });
+    scanComplete = scanCompleteForDropClamp(scan);
     health = computeAggregateHealth(scan.entries || []);
     const existing = readHealthCache();
     if (existing && existing.last_notified_status !== undefined) {
       health.last_notified_status = existing.last_notified_status;
     }
-    writeHealthCache(health);
+    if (existing && existing.last_notified_dropped !== undefined) {
+      const previous = Number(existing.last_notified_dropped || 0);
+      health.last_notified_dropped = scanComplete
+        ? Math.min(previous, Number(health.dropped_exchanges || 0))
+        : previous;
+    }
+    const written = writeHealthCache(health, { clampDropped: scanComplete });
+    if (written.ok) health = written.health;
   } else {
     health = readHealthCache() || {
       schema_version: 1,
@@ -214,9 +306,11 @@ function injectHealthNotice(context, opts) {
         blocked_action_required: 0,
       },
       queued_exchanges: 0,
+      dropped_exchanges: 0,
       oldest_pending_age_seconds: null,
       last_success_at: null,
       blocked_reasons: [],
+      drop_reasons: [],
       sessions: [],
     };
   }
@@ -225,13 +319,23 @@ function injectHealthNotice(context, opts) {
     health.last_notified_status !== undefined
       ? health.last_notified_status
       : null;
-  const built = buildHealthNotice({ health, previousStatus });
+  const previousDropped = Number(health.last_notified_dropped || 0);
+  const built = buildHealthNotice({ health, previousStatus, previousDropped });
 
   if (persist && built.shouldPersistNotified) {
-    writeHealthCache({
+    const nextHealth = {
       ...health,
       last_notified_status: built.nextNotifiedStatus,
-    });
+    };
+    if (scanComplete || !refresh) {
+      nextHealth.last_notified_dropped = built.droppedExchanges;
+    } else {
+      nextHealth.last_notified_dropped = Math.max(
+        previousDropped,
+        built.droppedExchanges,
+      );
+    }
+    writeHealthCache(nextHealth, { clampDropped: scanComplete });
   }
 
   if (!built.notice) return base;
@@ -255,6 +359,7 @@ function formatCaptureStatusText(health) {
       `degraded_retrying=${Number(counts.degraded_retrying || 0)} ` +
       `blocked_action_required=${Number(counts.blocked_action_required || 0)}`,
     `  queued exchanges: ${Number(h.queued_exchanges || 0)}`,
+    `  dropped exchanges: ${Number(h.dropped_exchanges || 0)}`,
     `  oldest pending age (seconds): ${
       h.oldest_pending_age_seconds == null ? "n/a" : h.oldest_pending_age_seconds
     }`,
@@ -265,6 +370,15 @@ function formatCaptureStatusText(health) {
   if (blocked.length) {
     lines.push(`  blocked reasons: ${blocked.join("; ")}`);
   }
+  const dropReasons = Array.isArray(h.drop_reasons) ? h.drop_reasons : [];
+  if (dropReasons.length) {
+    lines.push(`  drop reasons: ${dropReasons.join("; ")}`);
+  }
+  if (status === "degraded_retrying" || status === "blocked_action_required") {
+    lines.push(
+      "  per-session detail and cleanup: meko-mcp --capture-cleanup status",
+    );
+  }
   return lines.join("\n");
 }
 
@@ -300,15 +414,18 @@ function captureStatusJson(health) {
       ),
     },
     queued_exchanges: Number(h.queued_exchanges || 0),
+    dropped_exchanges: Number(h.dropped_exchanges || 0),
     oldest_pending_age_seconds:
       h.oldest_pending_age_seconds == null ? null : h.oldest_pending_age_seconds,
     last_success_at: h.last_success_at || null,
     blocked_reasons: Array.isArray(h.blocked_reasons) ? h.blocked_reasons : [],
+    drop_reasons: Array.isArray(h.drop_reasons) ? h.drop_reasons : [],
     sessions: Array.isArray(h.sessions) ? h.sessions : [],
   };
 }
 
 module.exports = {
+  PARKED_REASON_PREFIX,
   affectedSessionCount,
   reasonForHealth,
   statuslineSuffixFromHealth,

package/assets/hooks-handlers/lib/capture-state.js

@@ -293,6 +293,21 @@ function blockedOutcome(failureClass, error, extras) {
   };
 }
 
+/**
+ * MEKO-635: resumable sessions (OpenCode) must not be finalized as
+ * confirmed_dead by timer idle or cross-session recovery. Only OpenCode sets
+ * this policy today; other clients continue to finalize as before. Existing
+ * pre-MEKO-635 `client: "opencode"` watermarks without an explicit
+ * `pending_turn_policy` field are also treated as resumable so upgrades don't
+ * finalize a turn that a later snapshot could still complete.
+ */
+function isResumableState(state) {
+  if (!state || typeof state !== "object") return false;
+  if (state.pending_turn_policy === "resumable") return true;
+  if (state.pending_turn_policy == null && state.client === "opencode") return true;
+  return false;
+}
+
 /**
  * Validate a candidate v2 state object.
  * @returns {{ ok:true, state:Object } | { ok:false, delivery:"blocked", failure_class:"state_corrupt", error:string }}
@@ -342,6 +357,16 @@ function validateV2(state) {
       `invalid failure_class: ${state.failure_class}`,
     );
   }
+  if (
+    state.consecutive_exchange_drops != null &&
+    (!Number.isInteger(state.consecutive_exchange_drops) ||
+      state.consecutive_exchange_drops < 0)
+  ) {
+    return blockedOutcome(
+      "state_corrupt",
+      "consecutive_exchange_drops must be a non-negative integer",
+    );
+  }
   return { ok: true, state };
 }
 
@@ -461,6 +486,7 @@ function normalizeState(raw, context) {
     last_success_at:
       raw.last_success_at == null ? null : String(raw.last_success_at),
     blocked_reason: null,
+    consecutive_exchange_drops: 0,
   };
 
   const validated = validateV2(state);
@@ -938,6 +964,8 @@ function writeSessionIntent(sessionId, fields) {
               last_error: null,
               last_success_at: null,
               blocked_reason: null,
+              // null = finalize unless client is opencode (isResumableState).
+              pending_turn_policy: null,
             };
 
       const conversationId =
@@ -974,6 +1002,12 @@ function writeSessionIntent(sessionId, fields) {
           : "needs_conversation",
         last_activity_at: nowIso(),
         updated_at: nowIso(),
+        // MEKO-635: preserve or set pending_turn_policy. Only "resumable" is a
+        // meaningful non-default value today; anything else stays null.
+        pending_turn_policy:
+          f.pending_turn_policy !== undefined
+            ? (f.pending_turn_policy === "resumable" ? "resumable" : null)
+            : (base.pending_turn_policy === "resumable" ? "resumable" : null),
       };
 
       if (f.last_line_number != null && existing.missing) {
@@ -1065,6 +1099,10 @@ function rebucket(state, newConversationId) {
     blocked_reason: null,
     next_retry_at: null,
     attempt_count: 0,
+    consecutive_exchange_drops: 0,
+    // A replacement guard belongs only to the conversation that set it.
+    recovered_from_conversation_id: null,
+    missing_conversation_streak: null,
     updated_at: nowIso(),
     last_activity_at: nowIso(),
   };
@@ -1467,6 +1505,18 @@ function sessionHealthBucket(entry) {
   ) {
     return "blocked_action_required";
   }
+  // A session that has delivered everything is healthy even if an earlier
+  // attempt failed: failure_class records the last attempt, not outstanding
+  // work. Without this, one transient blip pins a closed, fully drained
+  // session to degraded_retrying forever and the rollup reports degraded with
+  // an empty queue. Blocked classes are checked above and still win, since
+  // those need a human.
+  if (
+    (state.delivery === "complete" || state.delivery === "idle") &&
+    coerceNonNegInt(state.queued_exchanges, 0) === 0
+  ) {
+    return "healthy";
+  }
   if (
     state.delivery === "retry_wait" ||
     fc === "transient" ||
@@ -1554,6 +1604,15 @@ function scanStates(options) {
   return { ok: true, entries, dir };
 }
 
+function scanCompleteForDropClamp(scan) {
+  return Boolean(
+    scan &&
+      scan.ok &&
+      Array.isArray(scan.entries) &&
+      scan.entries.every((entry) => entry && entry.ok !== false),
+  );
+}
+
 function sortOldestFirst(entries) {
   return [...(entries || [])].sort((a, b) => {
     const ak =
@@ -1588,9 +1647,11 @@ function computeAggregateHealth(states, options) {
     blocked_action_required: 0,
   };
   let queued = 0;
+  let dropped = 0;
   let oldestPendingAge = null;
   let lastSuccessAt = null;
   const blockedReasons = [];
+  const dropReasons = [];
   const sessions = [];
   let status = "healthy";
 
@@ -1612,6 +1673,20 @@ function computeAggregateHealth(states, options) {
         : 0;
     queued += q;
 
+    // Exchanges the server will never accept (see capture.js
+    // classifyPersistentCaptureFailure, scope "exchange"). They are not
+    // backlog — capture moved past them — but the user is still owed the
+    // fact that some turns are missing, so they aggregate separately.
+    const d =
+      state && typeof state === "object"
+        ? coerceNonNegInt(state.dropped_exchanges, 0)
+        : 0;
+    dropped += d;
+    if (d > 0 && state.last_drop_reason) {
+      const reason = String(state.last_drop_reason);
+      if (!dropReasons.includes(reason)) dropReasons.push(reason);
+    }
+
     if (state && state.last_success_at) {
       if (
         !lastSuccessAt ||
@@ -1659,6 +1734,7 @@ function computeAggregateHealth(states, options) {
         (entry && entry.failure_class) ||
         null,
       queued_exchanges: q,
+      dropped_exchanges: d,
       lifecycle: state ? state.lifecycle : null,
     });
   }
@@ -1669,14 +1745,17 @@ function computeAggregateHealth(states, options) {
     updated_at: nowIso(nowMs),
     counts,
     queued_exchanges: queued,
+    dropped_exchanges: dropped,
     oldest_pending_age_seconds: oldestPendingAge,
     last_success_at: lastSuccessAt,
     blocked_reasons: blockedReasons,
+    drop_reasons: dropReasons,
     sessions,
   };
 }
 
-function writeHealthCache(health) {
+function writeHealthCache(health, options) {
+  const opts = options && typeof options === "object" ? options : {};
   const existing = readHealthCache();
   const merged = {
     ...(health && typeof health === "object" ? health : {}),
@@ -1690,6 +1769,19 @@ function writeHealthCache(health) {
   ) {
     merged.last_notified_status = existing.last_notified_status;
   }
+  // Drop notices are one-shot per new count. Clamp only after a complete scan
+  // proves the aggregate shrank because watermarks disappeared. A failed scan
+  // or unreadable watermark may recover and must not re-announce old drops.
+  if (
+    merged.last_notified_dropped === undefined &&
+    existing &&
+    existing.last_notified_dropped !== undefined
+  ) {
+    const previous = coerceNonNegInt(existing.last_notified_dropped, 0);
+    merged.last_notified_dropped = opts.clampDropped
+      ? Math.min(previous, coerceNonNegInt(merged.dropped_exchanges, 0))
+      : previous;
+  }
   try {
     atomicWriteJson(healthCachePath(), merged);
     return { ok: true, path: healthCachePath(), health: merged };
@@ -2039,6 +2131,7 @@ module.exports = {
   // normalize / validate
   normalizeState,
   validateV2,
+  isResumableState,
 
   // persistence
   readState,
@@ -2063,6 +2156,7 @@ module.exports = {
 
   // scan
   scanStates,
+  scanCompleteForDropClamp,
   sortOldestFirst,
   sessionHealthBucket,
   buildEligibility,

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

@@ -22,6 +22,7 @@ const {
   importLegacyCaptureErrors,
   legacyErrorsSafeToRemove,
   readHealthCache,
+  scanCompleteForDropClamp,
   scanStates,
   writeHealthCache,
 } = require("./capture-state");
@@ -63,12 +64,15 @@ function main() {
     );
   }
 
-  const health = computeAggregateHealth(scan.entries || []);
+  let health = computeAggregateHealth(scan.entries || []);
   const existing = readHealthCache();
   if (existing && existing.last_notified_status !== undefined) {
     health.last_notified_status = existing.last_notified_status;
   }
-  writeHealthCache(health);
+  const written = writeHealthCache(health, {
+    clampDropped: scanCompleteForDropClamp(scan),
+  });
+  if (written.ok) health = written.health;
 
   const payload = captureStatusJson(health);
   if (json) {