metheus-governance-mcp-cli 0.2.205 → 0.2.207

package/cli.mjs

@@ -16,6 +16,7 @@ import {
   analyzeHumanConversationIntentWithAI,
   auditRoleExecutionPlanWithAI,
   auditDirectHumanReplyWithAI,
+  explainExecutionFailureWithAI,
   normalizeExecutionArtifacts,
   planRoleExecutionWithAI,
   repairRoleExecutionPlanWithAI,
@@ -2065,14 +2066,176 @@ function saveBotRunnerState(nextState) {
   try {
     current = safeObject(tryJsonParse(fs.readFileSync(filePath, "utf8")));
   } catch {}
+  const stateEntryTimestampMs = (...values) => {
+    for (const value of values) {
+      const ms = Date.parse(String(value || "").trim());
+      if (Number.isFinite(ms)) {
+        return ms;
+      }
+    }
+    return 0;
+  };
+  const mergeRunnerStateRoutes = (currentRoutesRaw, nextRoutesRaw) => {
+    const currentRoutes = safeObject(currentRoutesRaw);
+    const nextRoutes = safeObject(nextRoutesRaw);
+    const merged = {
+      ...currentRoutes,
+    };
+    const mergeConversationSessions = (currentSessionsRaw, nextSessionsRaw) => {
+      const currentSessions = safeObject(currentSessionsRaw);
+      const nextSessions = safeObject(nextSessionsRaw);
+      const mergedSessions = {
+        ...currentSessions,
+      };
+      for (const [conversationID, nextSessionRaw] of Object.entries(nextSessions)) {
+        const currentSession = safeObject(currentSessions[conversationID]);
+        const nextSession = safeObject(nextSessionRaw);
+        if (!Object.keys(currentSession).length) {
+          mergedSessions[conversationID] = nextSession;
+          continue;
+        }
+        const currentMs = stateEntryTimestampMs(
+          currentSession.updated_at,
+          currentSession.last_activity_at,
+          currentSession.closed_at,
+          currentSession.started_at,
+          currentSession.expires_at,
+        );
+        const nextMs = stateEntryTimestampMs(
+          nextSession.updated_at,
+          nextSession.last_activity_at,
+          nextSession.closed_at,
+          nextSession.started_at,
+          nextSession.expires_at,
+        );
+        mergedSessions[conversationID] = nextMs >= currentMs
+          ? {
+              ...currentSession,
+              ...nextSession,
+            }
+          : {
+              ...nextSession,
+              ...currentSession,
+            };
+      }
+      return mergedSessions;
+    };
+    for (const [routeKey, nextRouteRaw] of Object.entries(nextRoutes)) {
+      const currentRoute = safeObject(currentRoutes[routeKey]);
+      const nextRoute = safeObject(nextRouteRaw);
+      if (!Object.keys(currentRoute).length) {
+        merged[routeKey] = nextRoute;
+        continue;
+      }
+      const preferredRoute = prefersRunnerStateRecord(nextRoute, currentRoute) ? nextRoute : currentRoute;
+      const fallbackRoute = preferredRoute === nextRoute ? currentRoute : nextRoute;
+      merged[routeKey] = cleanupRunnerStateRecord({
+        ...mergeRunnerStateRecords(preferredRoute, fallbackRoute),
+        conversation_sessions: mergeConversationSessions(
+          currentRoute.conversation_sessions,
+          nextRoute.conversation_sessions,
+        ),
+      });
+    }
+    return merged;
+  };
+  const mergeRunnerStateRequests = (currentRequestsRaw, nextRequestsRaw) => {
+    const currentRequests = normalizeBotRunnerRequests(currentRequestsRaw);
+    const nextRequests = normalizeBotRunnerRequests(nextRequestsRaw);
+    const merged = {
+      ...currentRequests,
+    };
+    for (const [requestKey, nextRequestRaw] of Object.entries(nextRequests)) {
+      const currentRequest = safeObject(currentRequests[requestKey]);
+      const nextRequest = safeObject(nextRequestRaw);
+      const currentMs = stateEntryTimestampMs(
+        currentRequest.updated_at,
+        currentRequest.completed_at,
+        currentRequest.closed_at,
+        currentRequest.claimed_at,
+      );
+      const nextMs = stateEntryTimestampMs(
+        nextRequest.updated_at,
+        nextRequest.completed_at,
+        nextRequest.closed_at,
+        nextRequest.claimed_at,
+      );
+      if (!Object.keys(currentRequest).length) {
+        merged[requestKey] = nextRequest;
+        continue;
+      }
+      merged[requestKey] = nextMs >= currentMs
+        ? {
+            ...currentRequest,
+            ...nextRequest,
+          }
+        : currentRequest;
+    }
+    return normalizeBotRunnerRequests(merged);
+  };
+  const mergeRunnerStateExcludedComments = (currentExcludedRaw, nextExcludedRaw) => {
+    const currentExcluded = normalizeBotRunnerExcludedComments(currentExcludedRaw);
+    const nextExcluded = normalizeBotRunnerExcludedComments(nextExcludedRaw);
+    const merged = {
+      ...currentExcluded,
+    };
+    for (const [commentID, nextEntryRaw] of Object.entries(nextExcluded)) {
+      const currentEntry = safeObject(currentExcluded[commentID]);
+      const nextEntry = safeObject(nextEntryRaw);
+      const currentMs = stateEntryTimestampMs(currentEntry.excluded_at);
+      const nextMs = stateEntryTimestampMs(nextEntry.excluded_at);
+      if (!Object.keys(currentEntry).length || nextMs >= currentMs) {
+        merged[commentID] = {
+          ...currentEntry,
+          ...nextEntry,
+        };
+      }
+    }
+    return normalizeBotRunnerExcludedComments(merged);
+  };
+  const mergeRunnerStateConsumedComments = (currentConsumedRaw, nextConsumedRaw) => {
+    const currentConsumed = normalizeBotRunnerConsumedComments(currentConsumedRaw);
+    const nextConsumed = normalizeBotRunnerConsumedComments(nextConsumedRaw);
+    const merged = {
+      ...currentConsumed,
+    };
+    for (const [commentID, nextEntryRaw] of Object.entries(nextConsumed)) {
+      const currentEntry = safeObject(currentConsumed[commentID]);
+      const nextEntry = safeObject(nextEntryRaw);
+      const currentMs = stateEntryTimestampMs(currentEntry.consumed_at);
+      const nextMs = stateEntryTimestampMs(nextEntry.consumed_at);
+      if (!Object.keys(currentEntry).length || nextMs >= currentMs) {
+        merged[commentID] = {
+          ...currentEntry,
+          ...nextEntry,
+        };
+      }
+    }
+    return normalizeBotRunnerConsumedComments(merged);
+  };
   const payload = {
     version: 1,
     updated_at: new Date().toISOString(),
-    routes: safeObject(nextState?.routes ?? current.routes),
-    shared_inboxes: safeObject(nextState?.sharedInboxes ?? nextState?.shared_inboxes ?? current.shared_inboxes ?? current.sharedInboxes),
-    excluded_comments: normalizeBotRunnerExcludedComments(nextState?.excludedComments ?? nextState?.excluded_comments ?? current.excluded_comments ?? current.excludedComments),
-    requests: normalizeBotRunnerRequests(nextState?.requests ?? current.requests),
-    consumed_comments: normalizeBotRunnerConsumedComments(nextState?.consumedComments ?? nextState?.consumed_comments ?? current.consumed_comments ?? current.consumedComments),
+    routes: mergeRunnerStateRoutes(
+      current.routes,
+      nextState?.routes ?? current.routes,
+    ),
+    shared_inboxes: {
+      ...safeObject(current.shared_inboxes ?? current.sharedInboxes),
+      ...safeObject(nextState?.sharedInboxes ?? nextState?.shared_inboxes),
+    },
+    excluded_comments: mergeRunnerStateExcludedComments(
+      current.excluded_comments ?? current.excludedComments,
+      nextState?.excludedComments ?? nextState?.excluded_comments ?? current.excluded_comments ?? current.excludedComments,
+    ),
+    requests: mergeRunnerStateRequests(
+      current.requests,
+      nextState?.requests ?? current.requests,
+    ),
+    consumed_comments: mergeRunnerStateConsumedComments(
+      current.consumed_comments ?? current.consumedComments,
+      nextState?.consumedComments ?? nextState?.consumed_comments ?? current.consumed_comments ?? current.consumedComments,
+    ),
   };
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
@@ -2507,6 +2670,89 @@ function findRunnerRequestsForScope(state, normalizedRoute, selectors = {}) {
     });
 }
 
+function findScopedConversationSessionState(state, normalizedRoute, conversationIDRaw = "") {
+  const conversationID = String(conversationIDRaw || "").trim();
+  if (!conversationID) {
+    return {};
+  }
+  const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  const nextRoutes = safeObject(state?.routes);
+  const candidates = [];
+  const seenRouteKeys = new Set();
+  const pushCandidateRoute = (routeRaw) => {
+    const routeObject = safeObject(routeRaw);
+    if (!Object.keys(routeObject).length) {
+      return;
+    }
+    const candidateRoute = normalizeRunnerRoute(routeObject);
+    const candidateRouteKey = runnerRouteKey(candidateRoute);
+    if (seenRouteKeys.has(candidateRouteKey)) {
+      return;
+    }
+    seenRouteKeys.add(candidateRouteKey);
+    candidates.push({
+      route: candidateRoute,
+      routeKey: candidateRouteKey,
+      routeState: safeObject(nextRoutes[candidateRouteKey]),
+    });
+  };
+  pushCandidateRoute(normalizedRoute);
+  for (const candidateRouteRaw of ensureArray(config.routes)) {
+    if (!runnerRouteMatchesProjectConversationScope(candidateRouteRaw, normalizedRoute)) {
+      continue;
+    }
+    pushCandidateRoute(candidateRouteRaw);
+  }
+  const ranked = candidates
+    .map((candidate) => {
+      const session = safeObject(safeObject(candidate.routeState.conversation_sessions)[conversationID]);
+      if (!Object.keys(session).length) {
+        return null;
+      }
+      const status = String(session.status || "").trim().toLowerCase();
+      const lastActivity = firstNonEmptyString([session.last_activity_at, session.closed_at, session.started_at]);
+      return {
+        ...candidate,
+        session,
+        status,
+        lastActivity,
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => {
+      if (left.status !== right.status) {
+        if (left.status === "open") return -1;
+        if (right.status === "open") return 1;
+      }
+      if (left.lastActivity && right.lastActivity && left.lastActivity !== right.lastActivity) {
+        return left.lastActivity < right.lastActivity ? 1 : -1;
+      }
+      return String(left.routeKey || "").localeCompare(String(right.routeKey || ""));
+    });
+  return safeObject(ranked[0]);
+}
+
+function sessionAllowsConversationResponder(sessionRaw, responderSelectorRaw = "") {
+  const session = safeObject(sessionRaw);
+  const responderSelector = normalizeTelegramMentionUsername(responderSelectorRaw);
+  if (!responderSelector) {
+    return false;
+  }
+  if (String(session.status || "").trim().toLowerCase() !== "open") {
+    return false;
+  }
+  const nextExpectedResponders = ensureArray(session.next_expected_responders)
+    .map((value) => normalizeTelegramMentionUsername(value))
+    .filter(Boolean);
+  if (nextExpectedResponders.length > 0) {
+    return nextExpectedResponders.includes(responderSelector);
+  }
+  const allowedResponders = ensureArray(session.allowed_responders)
+    .map((value) => normalizeTelegramMentionUsername(value))
+    .filter(Boolean);
+  return allowedResponders.includes(responderSelector);
+}
+
 function findRunnerRequestsForMessageID(state, normalizedRoute, selectors = {}) {
   const chatID = String(selectors.chatID || "").trim();
   const messageID = intFromRawAllowZero(selectors.messageID, 0);
@@ -3895,11 +4141,80 @@ function resolveRunnerContinuationRequestForBotReply({
     };
   }
   const currentState = loadBotRunnerState();
-  const requests = findRunnerRequestsForScope(currentState, normalizedRoute, {
+  let requests = findRunnerRequestsForScope(currentState, normalizedRoute, {
     conversationID,
     chatID: String(parsed.chatID || parsed.chatId || "").trim(),
   }).filter((entry) => isActiveRunnerRequestStatus(entry.status));
-  const request = safeObject(requests[0]);
+  let request = safeObject(requests[0]);
+  if (!Object.keys(request).length) {
+    const sessionMatch = findScopedConversationSessionState(currentState, normalizedRoute, conversationID);
+    const session = safeObject(sessionMatch.session);
+    const fallbackRequestKey = String(
+      safeObject(sessionMatch.routeState).active_request_key
+      || safeObject(sessionMatch.routeState).last_request_key
+      || "",
+    ).trim();
+    if (
+      fallbackRequestKey
+      && String(session.status || "").trim().toLowerCase() === "open"
+    ) {
+      const fallbackRequest = safeObject(normalizeBotRunnerRequests(currentState.requests)[fallbackRequestKey]);
+      const nowISO = new Date().toISOString();
+      const seedRequest = Object.keys(fallbackRequest).length
+        ? fallbackRequest
+        : {
+          request_key: fallbackRequestKey,
+          project_id: String(normalizedRoute?.projectID || "").trim(),
+          provider: String(normalizedRoute?.provider || "").trim(),
+          chat_id: String(parsed.chatID || parsed.chatId || "").trim(),
+          conversation_id: conversationID,
+          selected_bot_usernames: ensureArray(session.participants),
+          conversation_allowed_responders: ensureArray(session.allowed_responders),
+          conversation_intent_mode: String(session.intent_mode || "").trim().toLowerCase(),
+          conversation_lead_bot: normalizeTelegramMentionUsername(session.lead_bot_username),
+          conversation_summary_bot: normalizeTelegramMentionUsername(session.summary_bot_username),
+          conversation_participants: ensureArray(session.participants),
+          conversation_initial_responders: ensureArray(session.initial_responders),
+          conversation_allow_bot_to_bot: session.allow_bot_to_bot === true,
+          conversation_reply_expectation: "",
+          execution_contract_type: String(session.last_execution_contract_type || "").trim().toLowerCase(),
+          execution_contract_actionable: session.last_execution_contract_actionable === true,
+          execution_contract_targets: ensureArray(session.last_execution_contract_targets),
+          next_expected_responders: ensureArray(session.next_expected_responders),
+          normalized_intent: String(safeObject(sessionMatch.routeState).last_intent_type || "").trim().toLowerCase(),
+          status: "running",
+          claimed_by_route: String(sessionMatch.routeKey || "").trim(),
+          claimed_at: firstNonEmptyString([session.started_at, nowISO]),
+          started_at: firstNonEmptyString([session.started_at, nowISO]),
+          root_work_item_id: String(
+            safeObject(sessionMatch.routeState).active_root_work_item_id
+            || safeObject(sessionMatch.routeState).last_root_work_item_id
+            || "",
+          ).trim(),
+          root_work_item_title: String(
+            safeObject(sessionMatch.routeState).active_root_work_item_title
+            || safeObject(sessionMatch.routeState).last_root_work_item_title
+            || "",
+          ).trim(),
+          root_work_item_status: String(
+            safeObject(sessionMatch.routeState).active_root_work_item_status
+            || safeObject(sessionMatch.routeState).last_root_work_item_status
+            || "",
+          ).trim().toLowerCase(),
+        };
+      const seededRequest = upsertRunnerRequest(currentState, fallbackRequestKey, seedRequest);
+      currentState.requests = seededRequest.requests;
+      request = safeObject(seededRequest.request);
+      saveBotRunnerState({
+        routes: currentState.routes,
+        sharedInboxes: currentState.sharedInboxes || currentState.shared_inboxes,
+        excludedComments: currentState.excludedComments || currentState.excluded_comments,
+        requests: currentState.requests,
+        consumedComments: currentState.consumedComments || currentState.consumed_comments,
+      });
+      requests = [request];
+    }
+  }
   if (!Object.keys(request).length) {
     return {
       ok: false,
@@ -4149,7 +4464,10 @@ function cleanupBotRunnerRequestState({
         && String(entry.conversation_id || "").trim() === String(conversationID || "").trim()
         && isActiveRunnerRequestStatus(entry.status)
       ));
-      if (!expired && activeRequests.length > 0) {
+      const pendingContinuationResponders = ensureArray(session.next_expected_responders)
+        .map((value) => normalizeTelegramMentionUsername(value))
+        .filter(Boolean);
+      if (!expired && (activeRequests.length > 0 || pendingContinuationResponders.length > 0)) {
         continue;
       }
       const closedReason = expired ? "expired_session" : "orphaned_open_session";
@@ -7487,7 +7805,11 @@ async function processRunnerRouteOnce(route, runtime, mode, options = {}) {
           && String(entry.conversation_id || "").trim() === conversationID
           && isActiveRunnerRequestStatus(entry.status)
         ));
-        return activeRequests.length > 0;
+        if (activeRequests.length > 0) {
+          return true;
+        }
+        const sessionMatch = findScopedConversationSessionState(latestRunnerState, normalizedRoute, conversationID);
+        return sessionAllowsConversationResponder(sessionMatch.session, currentBotSelector);
       }
       return true;
     });
@@ -8142,6 +8464,7 @@ async function processRunnerRouteOnce(route, runtime, mode, options = {}) {
           saveRunnerRouteState,
           startRunnerTypingHeartbeat,
           runRunnerAIExecution,
+          explainExecutionFailureWithAI,
           performLocalBotDelivery,
           serializeRunnerTriggerPolicy,
           serializeRunnerArchivePolicy,
@@ -10512,6 +10835,7 @@ async function runRunnerStartResolvedRoutes(routes, flags, options = {}) {
                         saveRunnerRouteState,
                         startRunnerTypingHeartbeat,
                         runRunnerAIExecution,
+                        explainExecutionFailureWithAI,
                         performLocalBotDelivery,
                         serializeRunnerTriggerPolicy,
                         serializeRunnerArchivePolicy,

package/lib/local-ai-adapters.mjs

@@ -1269,6 +1269,29 @@ export function resolveResponderAdjudicatorModelDisplayName({
   ).trim();
 }
 
+export function resolveFailureExplainerModelDisplayName({
+  client = "",
+  model = "",
+  env = process.env,
+} = {}) {
+  const explainerClient = normalizeLocalAIClientName(
+    String(
+      client
+      || env?.METHEUS_FAILURE_EXPLAINER_CLIENT
+      || env?.METHEUS_INTENT_PARSER_CLIENT
+      || "",
+    ).trim(),
+    "gpt",
+  );
+  return String(
+    model
+    || env?.METHEUS_FAILURE_EXPLAINER_MODEL
+    || env?.METHEUS_INTENT_PARSER_MODEL
+    || defaultAdjudicationModelForClient(explainerClient, env)
+    || "",
+  ).trim();
+}
+
 export function resolveLocalAIExecutionModel(clientName, rawModelValue = "") {
   const modelValue = String(rawModelValue || "").trim();
   if (!modelValue) return "";
@@ -2492,6 +2515,100 @@ export function analyzeHumanConversationIntentWithAI({
   };
 }
 
+function buildExecutionFailureExplanationPrompt({
+  botName = "",
+  userMessageText = "",
+  failureFacts = null,
+}) {
+  const compactUserMessage = String(userMessageText || "").trim() || "(not available)";
+  const compactBotName = String(botName || "").trim() || "the bot";
+  return [
+    "You explain runner execution failures to the user.",
+    `The active bot name is: ${compactBotName}`,
+    "Use only the supplied failure facts. Do not invent success, recovered work items, or missing facts.",
+    "Classify the outcome and explain it briefly in the same language as the user's latest message when possible.",
+    "If retryable is true, mention that a retry is reasonable.",
+    "Return a JSON object only with keys:",
+    '{"classification":"failed|retryable_failure|partial_success|needs_user_input|blocked","reply":"string","next_action":"string"}',
+    "",
+    "Latest user message:",
+    compactUserMessage,
+    "",
+    "Failure facts JSON:",
+    JSON.stringify(safeObject(failureFacts), null, 2),
+  ].join("\n");
+}
+
+export function explainExecutionFailureWithAI({
+  failureFacts = null,
+  userMessageText = "",
+  botName = "",
+  workspaceDir,
+  client = "",
+  model = "",
+  env = process.env,
+}) {
+  const explainerClient = normalizeLocalAIClientName(
+    String(
+      client
+      || env?.METHEUS_FAILURE_EXPLAINER_CLIENT
+      || env?.METHEUS_INTENT_PARSER_CLIENT
+      || "",
+    ).trim(),
+    "gpt",
+  );
+  const explainerModel = resolveFailureExplainerModelDisplayName({
+    client: explainerClient,
+    model,
+    env,
+  });
+  const rawText = runLocalAIPromptRawText({
+    client: explainerClient,
+    promptText: buildExecutionFailureExplanationPrompt({
+      botName,
+      userMessageText,
+      failureFacts,
+    }),
+    workspaceDir,
+    model: explainerModel,
+    permissionMode: "read_only",
+    reasoningEffort: String(env?.METHEUS_FAILURE_EXPLAINER_REASONING_EFFORT || "low").trim() || "low",
+    env,
+  });
+  const parsed = tryJsonParse(rawText) || tryParseEmbeddedJsonObject(rawText);
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    const classificationRaw = String(parsed.classification || "").trim().toLowerCase();
+    const classification = [
+      "failed",
+      "retryable_failure",
+      "partial_success",
+      "needs_user_input",
+      "blocked",
+    ].includes(classificationRaw) ? classificationRaw : "failed";
+    const reply = String(parsed.reply || parsed.message || "").trim();
+    const nextAction = String(parsed.next_action || parsed.nextAction || "").trim();
+    if (!reply) {
+      throw new Error("failure explainer did not return reply text");
+    }
+    return {
+      classification,
+      reply,
+      next_action: nextAction,
+      raw: parsed,
+    };
+  }
+  const plainReply = String(rawText || "").trim();
+  if (!plainReply) {
+    throw new Error("failure explainer returned empty output");
+  }
+  return {
+    classification: "failed",
+    reply: plainReply,
+    next_action: "",
+    raw: null,
+  };
+}
+
 function normalizeResponderAdjudicationSelectorList(values, allowedSelectors) {
   const allowed = new Set(ensureArray(allowedSelectors).map((value) => String(value || "").trim().replace(/^@+/, "").toLowerCase()).filter(Boolean));
   return uniqueOrdered(

package/lib/runner-orchestration.mjs

@@ -431,6 +431,155 @@ function shouldSendExecutionFailureReply({ triggerDecision, selectedRecord }) {
     && safeObject(selectedRecord?.parsedArchive).senderIsBot !== true;
 }
 
+function classifyExecutionFailureFacts(detail) {
+  const normalizedDetail = String(detail || "").trim();
+  const networkReset = /ECONNRESET|socket hang up|read ECONNRESET/i.test(normalizedDetail);
+  const networkTimeout = /ETIMEDOUT|http timeout|ECONNABORTED|aborted/i.test(normalizedDetail);
+  const retryable = networkReset || networkTimeout;
+  const base = {
+    stage: "execution",
+    operation: "runner_execution",
+    errorType: retryable
+      ? (networkTimeout ? "network_timeout" : "network_reset")
+      : "execution_failed",
+    retryable,
+    artifactCreated: null,
+    workItemCreated: null,
+    ctxpackUpdated: null,
+    partialSuccess: false,
+  };
+  if (!normalizedDetail) {
+    return base;
+  }
+  if (/permission_mode=read_only|read[_ -]?only/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "permission_check",
+      operation: "route_permission_check",
+      errorType: "read_only_route",
+      retryable: false,
+    };
+  }
+  if (/reply did not produce an actionable execution contract/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "execution_contract",
+      operation: "response_contract_validation",
+      errorType: "missing_actionable_contract",
+      retryable: false,
+    };
+  }
+  if (/failed to create work item/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "work_item_create",
+      operation: "workitem.push",
+      errorType: retryable
+        ? (networkTimeout ? "network_timeout" : "network_reset")
+        : "work_item_create_failed",
+      workItemCreated: false,
+    };
+  }
+  if (/governance work items/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "work_item_create",
+      operation: "governance_work_item_validation",
+      errorType: "governance_work_items_missing",
+      retryable: false,
+      workItemCreated: false,
+    };
+  }
+  if (/validated project artifacts|reported project artifacts that were not observed|artifact path does not exist/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "artifact_validation",
+      operation: "workspace_artifact_validation",
+      errorType: "artifact_validation_failed",
+      retryable: false,
+      artifactCreated: false,
+    };
+  }
+  if (/thread not found/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "archive_thread",
+      operation: "archive_thread_lookup",
+      errorType: "archive_thread_missing",
+      retryable,
+    };
+  }
+  if (/ctxpack version_id is missing/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_version_missing",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack\.update requires project ctxpack write access|ctxpack write access|ctxpack update permission|forbidden/i.test(normalizedDetail) && /ctxpack/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_permission_denied",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack/i.test(normalizedDetail) && retryable) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: networkTimeout ? "network_timeout" : "network_reset",
+      retryable: true,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_update_failed",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  return base;
+}
+
+function buildExecutionFailureFacts(detail, options = {}) {
+  const normalizedDetail = String(detail || "").trim();
+  const compactDetail = normalizedDetail.replace(/\s+/g, " ").trim();
+  const normalizedOptions = safeObject(options);
+  const intentType = normalizeHumanIntentType(normalizedOptions.intentType);
+  const classified = classifyExecutionFailureFacts(compactDetail);
+  return {
+    stage: classified.stage,
+    operation: classified.operation,
+    status: "failed",
+    error_type: classified.errorType,
+    error_message: compactDetail.slice(0, 400),
+    retryable: classified.retryable === true,
+    artifact_created: classified.artifactCreated,
+    work_item_created: classified.workItemCreated,
+    ctxpack_updated: classified.ctxpackUpdated,
+    partial_success: classified.partialSuccess === true,
+    intent_type: intentType,
+    informational_request: isInformationalHumanIntentType(intentType),
+    execution_mode: String(normalizedOptions.executionMode || "").trim(),
+    role_profile: String(normalizedOptions.roleProfileName || "").trim(),
+    conversation_id: String(normalizedOptions.conversationID || "").trim(),
+    root_work_item_id: String(normalizedOptions.rootWorkItemID || "").trim(),
+    request_message_id: intFromRawAllowZero(normalizedOptions.messageID, 0),
+    request_text: String(normalizedOptions.userMessageText || "").trim(),
+  };
+}
+
 function buildExecutionFailureReplyText(detail, options = {}) {
   const normalizedDetail = String(detail || "").trim();
   const intentType = normalizeHumanIntentType(safeObject(options).intentType);
@@ -4176,6 +4325,9 @@ export async function processRunnerSelectedRecord({
     ...safeObject(buildRunnerExecutionDeps()),
     ...safeObject(deps),
   };
+  const explainExecutionFailureWithAI = typeof executionDeps.explainExecutionFailureWithAI === "function"
+    ? executionDeps.explainExecutionFailureWithAI
+    : null;
   const normalizedPrecomputedHumanIntentContext = safeObject(precomputedHumanIntentContext);
   const normalizedPrecomputedHumanIntent = safeObject(normalizedPrecomputedHumanIntentContext.humanIntent);
   const validateWorkspaceArtifacts = typeof executionDeps.validateWorkspaceArtifacts === "function"
@@ -4413,9 +4565,36 @@ export async function processRunnerSelectedRecord({
     if (!shouldSendExecutionFailureReply({ triggerDecision: effectiveTriggerDecision, selectedRecord })) {
       return null;
     }
-    const replyText = buildExecutionFailureReplyText(detail, {
+    const failureFacts = buildExecutionFailureFacts(detail, {
       intentType: resolvedIntentType,
+      executionMode: effectiveExecutionPlan.mode,
+      roleProfileName: effectiveExecutionPlan.roleProfileName,
+      conversationID: String(conversationContext?.id || "").trim(),
+      rootWorkItemID: firstNonEmptyString([
+        routeState?.active_root_work_item_id,
+        routeState?.last_root_work_item_id,
+      ]),
+      messageID: selectedRecord?.parsedArchive?.messageID,
+      userMessageText: selectedRecord?.parsedArchive?.body,
     });
+    let replyText = "";
+    if (explainExecutionFailureWithAI) {
+      try {
+        const explanation = await Promise.resolve(explainExecutionFailureWithAI({
+          failureFacts,
+          userMessageText: String(selectedRecord?.parsedArchive?.body || "").trim(),
+          botName: String(bot?.name || bot?.username || bot?.id || "").trim(),
+          workspaceDir: String(effectiveExecutionPlan.workspaceDir || "").trim(),
+          env: process.env,
+        }));
+        replyText = String(safeObject(explanation).reply || safeObject(explanation).message || "").trim();
+      } catch {}
+    }
+    if (!replyText) {
+      replyText = buildExecutionFailureReplyText(detail, {
+        intentType: resolvedIntentType,
+      });
+    }
     if (!replyText) {
       return null;
     }

package/lib/selftest-runner-scenarios.mjs

@@ -2229,6 +2229,134 @@ export async function runSelftestRunnerScenarios(push, deps) {
     }
   }
 
+  const originalStateMergeHome = process.env.HOME;
+  const originalStateMergeUserProfile = process.env.USERPROFILE;
+  let runnerStateMergeTempRoot = "";
+  try {
+    runnerStateMergeTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-state-merge-selftest-"));
+    const runnerStateMergeHome = path.join(runnerStateMergeTempRoot, "home");
+    fs.mkdirSync(path.join(runnerStateMergeHome, ".metheus"), { recursive: true });
+    process.env.HOME = runnerStateMergeHome;
+    process.env.USERPROFILE = runnerStateMergeHome;
+    const mergeRoute = normalizeRunnerRoute({
+      name: "telegram-monitor-state-merge",
+      project_id: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      destination_label: "Main Room",
+    });
+    const mergeRouteKey = runnerRouteKey(mergeRoute);
+    saveBotRunnerState({
+      routes: {
+        [mergeRouteKey]: {
+          updated_at: "2026-03-24T06:29:05.000Z",
+          last_request_key: "request-key-597",
+          last_action: "running",
+          conversation_sessions: {
+            "conversation-597": {
+              conversation_id: "conversation-597",
+              status: "open",
+              updated_at: "2026-03-24T06:29:05.000Z",
+              last_activity_at: "2026-03-24T06:29:05.000Z",
+              last_execution_contract_type: "delegation",
+              next_expected_responders: ["ryoai2_bot", "ryoai3_bot"],
+            },
+          },
+        },
+      },
+      sharedInboxes: {},
+      excludedComments: {},
+      requests: {
+        "request-key-597": {
+          request_key: "request-key-597",
+          project_id: selftestProjectID,
+          provider: "telegram",
+          chat_id: "-100123",
+          source_message_id: 597,
+          conversation_id: "conversation-597",
+          normalized_intent: "explanation_query",
+          execution_contract_type: "delegation",
+          execution_contract_actionable: true,
+          next_expected_responders: ["ryoai2_bot", "ryoai3_bot"],
+          status: "running",
+          claimed_by_route: mergeRouteKey,
+          root_work_item_id: "root-work-item-597",
+          root_thread_id: "root-thread-597",
+          updated_at: "2026-03-24T06:29:05.000Z",
+        },
+      },
+      consumedComments: {},
+    });
+    saveBotRunnerState({
+      routes: {
+        [mergeRouteKey]: {
+          updated_at: "2026-03-24T06:29:06.000Z",
+          last_request_key: "request-key-597",
+          last_action: "replied",
+          conversation_sessions: {
+            "conversation-597": {
+              conversation_id: "conversation-597",
+              status: "open",
+              updated_at: "2026-03-24T06:29:06.000Z",
+            },
+          },
+        },
+      },
+      sharedInboxes: {},
+      excludedComments: {},
+      requests: {
+        "request-key-597": {
+          request_key: "request-key-597",
+          project_id: selftestProjectID,
+          provider: "telegram",
+          chat_id: "-100123",
+          source_message_id: 597,
+          conversation_id: "conversation-597",
+          normalized_intent: "general_execution",
+          status: "claimed",
+          claimed_by_route: mergeRouteKey,
+          root_work_item_id: "",
+          root_thread_id: "",
+          next_expected_responders: [],
+          updated_at: "2026-03-24T06:28:30.000Z",
+        },
+      },
+      consumedComments: {},
+    });
+    const mergedState = loadBotRunnerState();
+    const mergedRouteState = safeObject(safeObject(mergedState.routes)[mergeRouteKey]);
+    const mergedSession = safeObject(safeObject(mergedRouteState.conversation_sessions)["conversation-597"]);
+    const mergedRequest = safeObject(safeObject(mergedState.requests)["request-key-597"]);
+    push(
+      "runner_state_save_preserves_newer_request_and_conversation_session",
+      String(mergedRequest.status || "") === "running"
+        && String(mergedRequest.root_work_item_id || "") === "root-work-item-597"
+        && ensureArray(mergedRequest.next_expected_responders).includes("ryoai2_bot")
+        && String(mergedSession.status || "") === "open"
+        && String(mergedSession.last_execution_contract_type || "") === "delegation"
+        && ensureArray(mergedSession.next_expected_responders).includes("ryoai3_bot"),
+      `request_status=${String(mergedRequest.status || "(none)")} root_work_item=${String(mergedRequest.root_work_item_id || "(none)")} session_contract=${String(mergedSession.last_execution_contract_type || "(none)")} next=${ensureArray(mergedSession.next_expected_responders).join(",")}`,
+    );
+  } catch (err) {
+    push("runner_state_save_preserves_newer_request_and_conversation_session", false, String(err?.message || err));
+  } finally {
+    if (typeof originalStateMergeHome === "string") {
+      process.env.HOME = originalStateMergeHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (typeof originalStateMergeUserProfile === "string") {
+      process.env.USERPROFILE = originalStateMergeUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+    if (runnerStateMergeTempRoot) {
+      try {
+        fs.rmSync(runnerStateMergeTempRoot, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+
   const defaultMonitorTriggerPolicy = normalizeRunnerTriggerPolicy({}, { role: "monitor" });
   push(
     "bot_runner_default_monitor_trigger_policy",
@@ -5079,6 +5207,148 @@ export async function runSelftestRunnerScenarios(push, deps) {
     push("single_bot_human_work_request_requires_actionable_contract", false, String(err?.message || err));
   }
 
+  try {
+    let aiCalls = 0;
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    let capturedFailureFacts = null;
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-human-work-request-ai-failure-explainer-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-human-work-request-ai-failure-explainer",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-human-work-request-ai-failure-explainer",
+        createdAt: "2026-03-16T00:02:05.500Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot update the implementation guide now.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 1206,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir: process.cwd(),
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async () => {
+          aiCalls += 1;
+          return {
+            skip: false,
+            reply: "I reviewed the request but did not produce a contract.",
+            contract: null,
+          };
+        },
+        explainExecutionFailureWithAI: ({ failureFacts }) => {
+          capturedFailureFacts = safeObject(failureFacts);
+          return {
+            classification: "failed",
+            reply: "AI failure summary",
+            next_action: "retry",
+          };
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_execution_failure_uses_ai_failure_explainer_when_available",
+      processed.kind === "error"
+        && aiCalls >= 1
+        && deliveryCalls === 1
+        && deliveredText === "AI failure summary"
+        && String(capturedFailureFacts?.error_type || "") === "missing_actionable_contract"
+        && String(capturedFailureFacts?.stage || "") === "execution_contract",
+      `kind=${String(processed.kind || "(none)")} outcome=${String(processed.result?.outcome || "(none)")} ai_calls=${aiCalls} delivery_calls=${deliveryCalls} delivered=${deliveredText} failure_type=${String(capturedFailureFacts?.error_type || "(none)")} stage=${String(capturedFailureFacts?.stage || "(none)")}`,
+    );
+  } catch (err) {
+    push("single_bot_execution_failure_uses_ai_failure_explainer_when_available", false, String(err?.message || err));
+  }
+
   try {
     let aiCalls = 0;
     const processed = await processRunnerSelectedRecord({

package/package.json

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