metheus-governance-mcp-cli 0.2.263 → 0.2.265

package/cli.mjs

@@ -831,9 +831,17 @@ function botRunnerWorkspaceRegistryFilePath() {
   return resolveHomeFilePath(BOT_RUNNER_WORKSPACE_REGISTRY_RELATIVE_PATH);
 }
 
-function botRunnerStateFilePath() {
-  return resolveHomeFilePath(BOT_RUNNER_STATE_RELATIVE_PATH);
-}
+function botRunnerStateFilePath() {
+  return resolveHomeFilePath(BOT_RUNNER_STATE_RELATIVE_PATH);
+}
+
+function botRunnerStateBackupFilePath(filePath = botRunnerStateFilePath()) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) {
+    return "";
+  }
+  return `${normalizedPath}.bak`;
+}
 
 function botRunnerProcessesFilePath() {
   return resolveHomeFilePath(BOT_RUNNER_PROCESSES_RELATIVE_PATH);
@@ -2200,25 +2208,37 @@ function migrateBotRunnerStateRoutes(routes, runnerConfig) {
   };
 }
 
-function loadBotRunnerState() {
-  const filePath = botRunnerStateFilePath();
-  waitForBotRunnerStateLockRelease(filePath);
-  try {
-    if (!fs.existsSync(filePath)) {
-      return {
-        filePath,
-        routes: {},
-        sharedInboxes: {},
-        excludedComments: {},
-        requests: {},
-        consumedComments: {},
-        migrated: false,
-        migratedKeys: [],
-        remainingAnonymousKeys: [],
-      };
-    }
-    const parsed = tryJsonParse(fs.readFileSync(filePath, "utf8"));
-    const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
+function loadBotRunnerState() {
+  const filePath = botRunnerStateFilePath();
+  const backupPath = botRunnerStateBackupFilePath(filePath);
+  waitForBotRunnerStateLockRelease(filePath);
+  const emptyState = {
+    filePath,
+    routes: {},
+    sharedInboxes: {},
+    excludedComments: {},
+    requests: {},
+    consumedComments: {},
+    migrated: false,
+    migratedKeys: [],
+    remainingAnonymousKeys: [],
+  };
+  try {
+    if (!fs.existsSync(filePath)) {
+      return emptyState;
+    }
+    let parsed = tryJsonParse(fs.readFileSync(filePath, "utf8"));
+    if ((!parsed || typeof parsed !== "object" || Array.isArray(parsed)) && backupPath && fs.existsSync(backupPath)) {
+      const backupParsed = tryJsonParse(fs.readFileSync(backupPath, "utf8"));
+      if (backupParsed && typeof backupParsed === "object" && !Array.isArray(backupParsed)) {
+        parsed = backupParsed;
+        writeTextFileAtomic(filePath, `${JSON.stringify(backupParsed, null, 2)}\n`);
+      }
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return emptyState;
+    }
+    const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
     const migratedState = migrateBotRunnerStateRoutes(safeObject(parsed?.routes), runnerConfig);
     if (migratedState.changed) {
       saveBotRunnerState({
@@ -2241,24 +2261,14 @@ function loadBotRunnerState() {
       excludedComments: normalizeBotRunnerExcludedComments(parsed?.excluded_comments || parsed?.excludedComments),
       requests: normalizeBotRunnerRequests(parsed?.requests),
       consumedComments: normalizeBotRunnerConsumedComments(parsed?.consumed_comments || parsed?.consumedComments),
-      migrated: migratedState.changed,
-      migratedKeys: migratedState.migratedKeys,
-      remainingAnonymousKeys: migratedState.remainingAnonymousKeys,
-    };
-  } catch {
-    return {
-      filePath,
-      routes: {},
-      sharedInboxes: {},
-      excludedComments: {},
-      requests: {},
-      consumedComments: {},
-      migrated: false,
-      migratedKeys: [],
-      remainingAnonymousKeys: [],
-    };
-  }
-}
+      migrated: migratedState.changed,
+      migratedKeys: migratedState.migratedKeys,
+      remainingAnonymousKeys: migratedState.remainingAnonymousKeys,
+    };
+  } catch {
+    return emptyState;
+  }
+}
 
 function sleepSyncMs(delayMs) {
   const ms = Number(delayMs) || 0;
@@ -2408,13 +2418,19 @@ function writeTextFileAtomic(filePath, text) {
   }
 }
 
-function saveBotRunnerState(nextState) {
-  const filePath = botRunnerStateFilePath();
-  return withBotRunnerStateFileLock(filePath, () => {
-    let current = {};
-    try {
-      current = safeObject(tryJsonParse(fs.readFileSync(filePath, "utf8")));
-    } catch {}
+function saveBotRunnerState(nextState) {
+  const filePath = botRunnerStateFilePath();
+  const backupPath = botRunnerStateBackupFilePath(filePath);
+  return withBotRunnerStateFileLock(filePath, () => {
+    let current = {};
+    try {
+      current = safeObject(tryJsonParse(fs.readFileSync(filePath, "utf8")));
+    } catch {}
+    if (!Object.keys(current).length && backupPath && fs.existsSync(backupPath)) {
+      try {
+        current = safeObject(tryJsonParse(fs.readFileSync(backupPath, "utf8")));
+      } catch {}
+    }
     const stateEntryTimestampMs = (...values) => {
       for (const value of values) {
         const ms = Date.parse(String(value || "").trim());
@@ -2562,7 +2578,7 @@ function saveBotRunnerState(nextState) {
       }
       return normalizeBotRunnerConsumedComments(merged);
     };
-    const payload = {
+    const payload = {
       version: 1,
       updated_at: new Date().toISOString(),
       routes: mergeRunnerStateRoutes(
@@ -2581,15 +2597,30 @@ function saveBotRunnerState(nextState) {
         current.requests,
         nextState?.requests ?? current.requests,
       ),
-      consumed_comments: mergeRunnerStateConsumedComments(
-        current.consumed_comments ?? current.consumedComments,
-        nextState?.consumedComments ?? nextState?.consumed_comments ?? current.consumed_comments ?? current.consumedComments,
-      ),
-    };
-    writeTextFileAtomic(filePath, `${JSON.stringify(payload, null, 2)}\n`);
-    return filePath;
-  });
-}
+      consumed_comments: mergeRunnerStateConsumedComments(
+        current.consumed_comments ?? current.consumedComments,
+        nextState?.consumedComments ?? nextState?.consumed_comments ?? current.consumed_comments ?? current.consumedComments,
+      ),
+    };
+    const serialized = `${JSON.stringify(payload, null, 2)}\n`;
+    writeTextFileAtomic(filePath, serialized);
+    const verifiedPayload = tryJsonParse(fs.readFileSync(filePath, "utf8"));
+    if (!verifiedPayload || typeof verifiedPayload !== "object" || Array.isArray(verifiedPayload)) {
+      if (backupPath && fs.existsSync(backupPath)) {
+        const backupRaw = fs.readFileSync(backupPath, "utf8");
+        const backupParsed = tryJsonParse(backupRaw);
+        if (backupParsed && typeof backupParsed === "object" && !Array.isArray(backupParsed)) {
+          writeTextFileAtomic(filePath, backupRaw);
+        }
+      }
+      throw new Error("bot runner state write verification failed");
+    }
+    if (backupPath) {
+      writeTextFileAtomic(backupPath, serialized);
+    }
+    return filePath;
+  });
+}
 
 function normalizeBotRunnerExcludedComments(rawExcluded, nowMs = Date.now()) {
   const normalized = {};

package/lib/runner-helpers.mjs

@@ -478,7 +478,7 @@ export function dedupeProcessableArchiveComments(records) {
   return deduped;
 }
 
-function isArchiveRecordAfterState(record, routeState) {
+export function isArchiveRecordAfterState(record, routeState) {
   const state = safeObject(routeState);
   const lastCommentID = String(state.last_processed_comment_id || "").trim();
   const lastCreatedAt = String(state.last_processed_created_at || "").trim();

package/lib/runner-orchestration.mjs

@@ -8,6 +8,7 @@ import {
   compareArchiveCommentRecords,
   dedupeProcessableArchiveComments,
   findRecentTelegramMessageEnvelope,
+  isArchiveRecordAfterState,
   isTelegramLocalInboundEnvelopeForRoute,
   isInboundArchiveKind,
   normalizeTelegramMessageEnvelope,
@@ -1809,7 +1810,7 @@ export async function resolveRunnerPrecomputedSelectedRecordExecutionContext({
   };
 }
 
-function resolveRunnerDeliverySourceMessageEnvelope({
+export function resolveRunnerDeliverySourceMessageEnvelope({
   routeState,
   persistedRequest,
   selectedRecord,
@@ -1826,7 +1827,7 @@ function resolveRunnerDeliverySourceMessageEnvelope({
   if (Object.keys(safeObject(localMatch.envelope)).length > 0) {
     return localMatch.envelope;
   }
-  return safeObject(localMatch.candidates).archiveEnvelope || {};
+  return {};
 }
 
 function escapeRegExp(text) {
@@ -6305,11 +6306,18 @@ export function selectRunnerPendingWork({
     .map((record) => normalizeArchiveCommentRecord(record, parseArchivedChatComment))
     .filter((record) => record.id && record.parsedArchive)
     .sort(compareArchiveCommentRecords);
+  const importedCommentRecords = ensureArray(importOutcome?.importedComments)
+    .map((record) => normalizeArchiveCommentRecord(record, parseArchivedChatComment))
+    .filter((record) => record.id && record.parsedArchive)
+    .sort(compareArchiveCommentRecords);
   const inboundComments = orderedComments.filter((record) => isInboundArchiveKind(record.parsedArchive.kind));
   const importedRecords = dedupeProcessableArchiveComments(
-    ensureArray(importOutcome?.importedCommentIDs)
-    .map((commentID) => orderedComments.find((record) => record.id === commentID))
-    .filter(Boolean),
+    [
+      ...ensureArray(importOutcome?.importedCommentIDs)
+        .map((commentID) => orderedComments.find((record) => record.id === commentID))
+        .filter(Boolean),
+      ...importedCommentRecords,
+    ],
   );
   const hasCursor = Boolean(
     String(safeObject(refreshedState).active_comment_id || "").trim()
@@ -6324,6 +6332,18 @@ export function selectRunnerPendingWork({
     (record) => normalizeArchiveCommentRecord(record, parseArchivedChatComment),
     pendingSelectionOptions,
   );
+  const laggingImportedRecords = importedRecords.filter((record) => (
+    !orderedComments.some((orderedRecord) => String(orderedRecord.id || "").trim() === String(record.id || "").trim())
+  ));
+  const importedPendingAfterCursor = dedupeProcessableArchiveComments(
+    laggingImportedRecords.filter((record) => isArchiveRecordAfterState(record, {
+      ...safeObject(refreshedState),
+      last_processed_comment_id: String(safeObject(refreshedState).active_comment_id || "").trim()
+        || safeObject(refreshedState).last_processed_comment_id,
+      last_processed_created_at: String(safeObject(refreshedState).active_comment_created_at || "").trim()
+        || safeObject(refreshedState).last_processed_created_at,
+    })),
+  );
   const pending = importedRecords.length > 0 && !hasCursor
     ? applyPendingAgeSelection({
         ordered: orderedComments,
@@ -6331,6 +6351,13 @@ export function selectRunnerPendingWork({
         shouldPrime: false,
         pending: importedRecords,
       }, pendingSelectionOptions)
+    : importedPendingAfterCursor.length > 0 && ensureArray(fullPending.pending).length === 0
+    ? applyPendingAgeSelection({
+        ordered: orderedComments,
+        latest: inboundComments.length ? inboundComments[inboundComments.length - 1] : null,
+        shouldPrime: false,
+        pending: importedPendingAfterCursor,
+      }, pendingSelectionOptions)
     : fullPending;
   return {
     orderedComments,

package/lib/runner-runtime.mjs

@@ -767,6 +767,7 @@ async function archiveRunnerTelegramInboundUpdates({
 }) {
   let handledUpdateID = 0;
   const importedCommentIDs = [];
+  const importedComments = [];
   const retainedSharedUpdates = [];
   for (let index = 0; index < mergedSharedUpdates.length; index += 1) {
     const update = mergedSharedUpdates[index];
@@ -799,17 +800,19 @@ async function archiveRunnerTelegramInboundUpdates({
       continue;
     }
     let createdComment;
+    let archiveBody = "";
     try {
+      archiveBody = formatTelegramInboundArchiveComment({
+        ...update,
+        archiveSourceOrigin: "telegram_archive_context",
+      });
       createdComment = await createThreadComment({
         siteBaseURL: runtime.baseURL,
         token: runtime.token,
         timeoutSeconds: runtime.timeoutSeconds,
         threadID: archiveThread.threadID,
         actorUserID: runtime.actor.user_id,
-        body: formatTelegramInboundArchiveComment({
-          ...update,
-          archiveSourceOrigin: "telegram_archive_context",
-        }),
+        body: archiveBody,
       });
     } catch (err) {
       releaseRunnerInboundArchiveMessageReservation(reservation.reservationKey);
@@ -822,6 +825,19 @@ async function archiveRunnerTelegramInboundUpdates({
     if (String(createdComment.id || "").trim()) {
       importedCommentIDs.push(String(createdComment.id || "").trim());
     }
+    importedComments.push({
+      ...safeObject(createdComment),
+      id: String(createdComment?.id || "").trim(),
+      body: archiveBody,
+      created_at: String(createdComment?.created_at || createdComment?.createdAt || new Date().toISOString()).trim(),
+      updated_at: String(
+        createdComment?.updated_at
+        || createdComment?.updatedAt
+        || createdComment?.created_at
+        || createdComment?.createdAt
+        || new Date().toISOString()
+      ).trim(),
+    });
     if (boolFromRaw(archivePolicy.dedupeInbound, true)) {
       existingKeys.add(dedupeKey);
     }
@@ -829,6 +845,7 @@ async function archiveRunnerTelegramInboundUpdates({
   return {
     handledUpdateID,
     importedCommentIDs,
+    importedComments,
     retainedSharedUpdates,
   };
 }
@@ -1168,6 +1185,7 @@ export async function archiveLocalTelegramMessagesForRoute({
   const {
     handledUpdateID,
     importedCommentIDs,
+    importedComments,
     retainedSharedUpdates,
   } = await archiveRunnerTelegramInboundUpdates({
     mergedSharedUpdates,
@@ -1191,6 +1209,7 @@ export async function archiveLocalTelegramMessagesForRoute({
 
   return {
     importedCommentIDs,
+    importedComments,
     importedCount: importedCommentIDs.length,
     lastUpdateID: Math.max(lastUpdateID, handledUpdateID),
   };

package/lib/selftest-runner-scenarios.mjs

@@ -2,7 +2,10 @@
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
-import process from "node:process";
+import process from "node:process";
+import {
+  resolveRunnerDeliverySourceMessageEnvelope,
+} from "./runner-orchestration.mjs";
 
 function requireDependency(deps, key) {
   const candidate = deps?.[key];
@@ -595,8 +598,8 @@ export async function runSelftestRunnerScenarios(push, deps) {
     );
   }
 
-  try {
-    const duplicateComments = [
+  try {
+    const duplicateComments = [
       {
         id: "dup-comment-earliest",
         createdAt: "2026-03-18T00:00:01.000Z",
@@ -633,15 +636,68 @@ export async function runSelftestRunnerScenarios(push, deps) {
       `pending=${pendingWork.pending.pending.map((item) => item.id).join(",") || "(none)"}`,
     );
   } catch (err) {
-    push(
-      "runner_pending_selection_does_not_requeue_imported_duplicate_after_cursor",
-      false,
-      String(err?.message || err),
-    );
-  }
-
-  try {
-    const selected = selectProjectChatDestination(
+    push(
+      "runner_pending_selection_does_not_requeue_imported_duplicate_after_cursor",
+      false,
+      String(err?.message || err),
+    );
+  }
+
+  try {
+    const pendingWork = selectRunnerPendingWork({
+      comments: [
+        {
+          id: "cursor-comment",
+          createdAt: "2026-03-18T00:00:01.000Z",
+          updatedAt: "2026-03-18T00:00:01.000Z",
+          parsedArchive: { kind: "telegram_message", chatID: "-1001", messageID: 353, body: "@RyoAI_bot first copy" },
+        },
+      ],
+      importOutcome: {
+        importedCommentIDs: ["fresh-import-comment"],
+        importedComments: [
+          {
+            id: "fresh-import-comment",
+            created_at: "2026-03-18T00:00:05.000Z",
+            updated_at: "2026-03-18T00:00:05.000Z",
+            body: "[Telegram message]\nchat_id: -1001\nmessage_id: 354\n\nfresh imported mention",
+          },
+        ],
+      },
+      refreshedState: {
+        last_processed_comment_id: "cursor-comment",
+        last_processed_created_at: "2026-03-18T00:00:01.000Z",
+      },
+      mode: "start",
+      parseArchivedChatComment,
+      deps: {
+        normalizeArchiveCommentRecord: (record, parser) => ({
+          id: String(record?.id || "").trim(),
+          body: String(record?.body || "").trim(),
+          createdAt: String(record?.created_at || record?.createdAt || record?.updated_at || record?.updatedAt || "").trim(),
+          updatedAt: String(record?.updated_at || record?.updatedAt || "").trim(),
+          parsedArchive: typeof parser === "function" ? parser(String(record?.body || "").trim()) : null,
+        }),
+        applyPendingAgeSelection: (selection) => selection,
+      },
+      pendingSelectionOptions: {},
+    });
+    push(
+      "runner_pending_selection_uses_fresh_imported_comment_when_thread_read_lags",
+      pendingWork.pending.pending.length === 1
+        && String(pendingWork.pending.pending[0]?.id || "").trim() === "fresh-import-comment",
+      `pending=${pendingWork.pending.pending.map((item) => item.id).join(",") || "(none)"}`,
+    );
+  } catch (err) {
+    push(
+      "runner_pending_selection_uses_fresh_imported_comment_when_thread_read_lags",
+      false,
+      String(err?.message || err),
+    );
+  }
+
+  try {
+    const selected = selectProjectChatDestination(
       [
         { id: "dest-1", provider: "telegram", label: "Main Room", chat_id: "-1001", is_active: true },
         { id: "dest-2", provider: "slack", label: "Slack", chat_id: "C123", is_active: true },
@@ -2745,6 +2801,66 @@ export async function runSelftestRunnerScenarios(push, deps) {
     }
   }
 
+  const originalStateBackupHome = process.env.HOME;
+  const originalStateBackupUserProfile = process.env.USERPROFILE;
+  let stateBackupTempRoot = "";
+  try {
+    stateBackupTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-selftest-state-backup-"));
+    process.env.HOME = stateBackupTempRoot;
+    process.env.USERPROFILE = stateBackupTempRoot;
+    const metheusDir = path.join(stateBackupTempRoot, ".metheus");
+    fs.mkdirSync(metheusDir, { recursive: true });
+    const statePath = path.join(metheusDir, "bot-runner-state.json");
+    const backupPath = `${statePath}.bak`;
+    fs.writeFileSync(
+      backupPath,
+      `${JSON.stringify({
+        version: 1,
+        updated_at: "2026-03-29T00:00:00.000Z",
+        routes: {
+          "telegram-monitor-state-backup::project::telegram::monitor::dest::actor": {
+            last_action: "idle",
+          },
+        },
+        shared_inboxes: {},
+        excluded_comments: {},
+        requests: {},
+        consumed_comments: {},
+      }, null, 2)}\n`,
+      "utf8",
+    );
+    fs.writeFileSync(statePath, "{ malformed json", "utf8");
+    const recoveredState = loadBotRunnerState();
+    const recoveredRouteState = safeObject(
+      safeObject(recoveredState.routes)["telegram-monitor-state-backup::project::telegram::monitor::dest::actor"],
+    );
+    const repairedPrimary = safeObject(tryJsonParse(fs.readFileSync(statePath, "utf8")));
+    push(
+      "runner_state_load_restores_primary_from_backup_when_primary_is_malformed",
+      String(recoveredRouteState.last_action || "") === "idle"
+        && String(safeObject(safeObject(repairedPrimary.routes)["telegram-monitor-state-backup::project::telegram::monitor::dest::actor"]).last_action || "") === "idle",
+      `recovered=${String(recoveredRouteState.last_action || "(none)")} repaired=${String(safeObject(safeObject(repairedPrimary.routes)["telegram-monitor-state-backup::project::telegram::monitor::dest::actor"]).last_action || "(none)")}`,
+    );
+  } catch (err) {
+    push("runner_state_load_restores_primary_from_backup_when_primary_is_malformed", false, String(err?.message || err));
+  } finally {
+    if (typeof originalStateBackupHome === "string") {
+      process.env.HOME = originalStateBackupHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (typeof originalStateBackupUserProfile === "string") {
+      process.env.USERPROFILE = originalStateBackupUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+    if (stateBackupTempRoot) {
+      try {
+        fs.rmSync(stateBackupTempRoot, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+
   const defaultMonitorTriggerPolicy = normalizeRunnerTriggerPolicy({}, { role: "monitor" });
   push(
     "bot_runner_default_monitor_trigger_policy",
@@ -15200,9 +15316,43 @@ export async function runSelftestRunnerScenarios(push, deps) {
         && String(capturedSourceMessageEnvelope.source_route_key || "") === "telegram-monitor-ryoai2-bot-2::project::telegram::monitor::dest::actor",
       `kind=${String(processed.kind || "(none)")} reply_to=${capturedReplyToMessageID} origin=${String(capturedSourceMessageEnvelope.source_origin || "(none)")} route=${String(capturedSourceMessageEnvelope.source_route_key || "(none)")}`,
     );
-  } catch (err) {
-    push("runner_delivery_accepts_archived_local_route_provenance", false, String(err?.message || err));
-  }
+  } catch (err) {
+    push("runner_delivery_accepts_archived_local_route_provenance", false, String(err?.message || err));
+  }
+
+  try {
+    const envelope = resolveRunnerDeliverySourceMessageEnvelope({
+      routeState: {
+        recent_local_inbound_receipts: {},
+        recent_local_inbound_envelopes: {},
+      },
+      persistedRequest: {},
+      selectedRecord: {
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          body: "@RyoAI2_bot hi without local provenance",
+          messageID: 331,
+          sender: "human",
+          senderIsBot: false,
+          mentionUsernames: ["ryoai2_bot"],
+          sourceOrigin: "archive_reconstructed",
+          sourceRouteKey: "telegram-monitor-ryoai2-bot-2::project::telegram::monitor::dest::actor",
+          sourceBotUsername: "ryoai2_bot",
+        },
+      },
+      routeKey: "telegram-monitor-ryoai2-bot-2::project::telegram::monitor::dest::actor",
+      currentBotSelector: "ryoai2_bot",
+    });
+    push(
+      "runner_delivery_drops_archive_reconstructed_reply_anchor_before_delivery",
+      Object.keys(safeObject(envelope)).length === 0,
+      `origin=${String(safeObject(envelope).source_origin || "(none)")} message=${String(safeObject(envelope).message_id || "(none)")}`,
+    );
+  } catch (err) {
+    push("runner_delivery_drops_archive_reconstructed_reply_anchor_before_delivery", false, String(err?.message || err));
+  }
 
   try {
     const provenanceTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-provenance-selftest-"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.263",
+  "version": "0.2.265",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [