metheus-governance-mcp-cli 0.2.206 → 0.2.208

package/cli.mjs

@@ -16,6 +16,7 @@ import {
   analyzeHumanConversationIntentWithAI,
   auditRoleExecutionPlanWithAI,
   auditDirectHumanReplyWithAI,
+  explainExecutionFailureWithAI,
   normalizeExecutionArtifacts,
   planRoleExecutionWithAI,
   repairRoleExecutionPlanWithAI,
@@ -2622,7 +2623,7 @@ function inferRunnerRequestClaimIntent(selectedRecord) {
   if (looksLikeRunnerClaimQuestion(rawText) && normalizedText.split(/\s+/).filter(Boolean).length <= 8) {
     return "status_query";
   }
-  return "general_execution";
+  return "";
 }
 
 function resolveRunnerRequestClaimIntent({
@@ -2646,6 +2647,16 @@ function buildSyntheticReplyChainConversationID(normalizedRoute, chatID, anchorM
   return `reply_chain:${provider}:${normalizedChatID}:${normalizedAnchorMessageID}`;
 }
 
+function buildSyntheticHumanOpeningConversationID(normalizedRoute, chatID, messageID) {
+  const provider = String(normalizedRoute?.provider || "").trim() || "unknown";
+  const normalizedChatID = String(chatID || "").trim() || "-";
+  const normalizedMessageID = intFromRawAllowZero(messageID, 0);
+  if (normalizedMessageID <= 0) {
+    return "";
+  }
+  return `human_opening:${provider}:${normalizedChatID}:${normalizedMessageID}`;
+}
+
 function findRunnerRequestsForScope(state, normalizedRoute, selectors = {}) {
   const requests = normalizeBotRunnerRequests(state?.requests);
   const projectID = String(normalizedRoute?.projectID || "").trim();
@@ -3258,13 +3269,17 @@ async function claimRunnerRequestForHumanComment({
     normalizedIntent,
     selectedRecord,
   });
-  const requestKey = buildRunnerRequestKey({
+  let stateForClaim = safeObject(replyChainResolution.state);
+  const normalizedSharedHumanIntent = safeObject(sharedHumanIntent);
+  const provisionalNormalizedIntent = String(
+    normalizedSharedHumanIntent.intentType || resolvedNormalizedIntent || "",
+  ).trim().toLowerCase();
+  const provisionalRequestKey = buildRunnerRequestKey({
     normalizedRoute,
     selectedRecord,
     selectedBotUsernames,
-    normalizedIntent: resolvedNormalizedIntent,
+    normalizedIntent: provisionalNormalizedIntent,
   });
-  let stateForClaim = safeObject(replyChainResolution.state);
   const baseConversationID = String(
     parsed.conversationID
     || replyChainContext.conversationID
@@ -3284,9 +3299,6 @@ async function claimRunnerRequestForHumanComment({
       requests: backfilled.requests,
     };
   }
-  const requests = normalizeBotRunnerRequests(stateForClaim.requests);
-  const existing = safeObject(requests[requestKey]);
-  const normalizedSharedHumanIntent = safeObject(sharedHumanIntent);
   const currentMessageID = intFromRawAllowZero(parsed.messageID, 0);
   let sharedConversationSource = currentMessageID > 0
     ? pickRunnerSharedConversationSourceRequest(
@@ -3294,7 +3306,7 @@ async function claimRunnerRequestForHumanComment({
         chatID: String(parsed.chatID || parsed.chatId || "").trim(),
         messageID: currentMessageID,
       }),
-      requestKey,
+      provisionalRequestKey,
     )
     : {};
   if (
@@ -3308,14 +3320,38 @@ async function claimRunnerRequestForHumanComment({
       runtime,
       chatID: String(parsed.chatID || parsed.chatId || "").trim(),
       messageID: currentMessageID,
-      excludeRequestKey: requestKey,
+      excludeRequestKey: provisionalRequestKey,
     }));
   }
   const resolvedConversationID = String(
     baseConversationID
     || sharedConversationSource.conversation_id
+    || (
+      Object.keys(normalizedSharedHumanIntent).length > 0
+        ? buildSyntheticHumanOpeningConversationID(
+          normalizedRoute,
+          String(parsed.chatID || parsed.chatId || "").trim(),
+          currentMessageID,
+        )
+        : ""
+    )
     || "",
   ).trim();
+  const preferredNormalizedIntent = String(
+    normalizedSharedHumanIntent.intentType
+      || sharedConversationSource.normalized_intent
+      || referencedRequest.normalized_intent
+      || resolvedNormalizedIntent
+      || "",
+  ).trim().toLowerCase();
+  const requestKey = buildRunnerRequestKey({
+    normalizedRoute,
+    selectedRecord,
+    selectedBotUsernames,
+    normalizedIntent: preferredNormalizedIntent,
+  });
+  const requests = normalizeBotRunnerRequests(stateForClaim.requests);
+  const existing = safeObject(requests[requestKey]);
   if (isFinalRunnerRequestStatus(existing.status)) {
     return {
       ok: false,
@@ -3411,10 +3447,10 @@ async function claimRunnerRequestForHumanComment({
           ? sharedConversationSource.next_expected_responders
           : ensureArray(referencedRequest.next_expected_responders).length
             ? referencedRequest.next_expected_responders
-            : normalizedSharedHumanIntent.initialResponderSelectors,
+            : [],
       normalizeTelegramMentionUsername,
     ),
-    normalized_intent: resolvedNormalizedIntent,
+    normalized_intent: preferredNormalizedIntent,
     status: "claimed",
     claimed_by_route: String(routeKey || "").trim(),
     claimed_at: firstNonEmptyString([existing.claimed_at, nowISO]) || nowISO,
@@ -8463,6 +8499,7 @@ async function processRunnerRouteOnce(route, runtime, mode, options = {}) {
           saveRunnerRouteState,
           startRunnerTypingHeartbeat,
           runRunnerAIExecution,
+          explainExecutionFailureWithAI,
           performLocalBotDelivery,
           serializeRunnerTriggerPolicy,
           serializeRunnerArchivePolicy,
@@ -10833,6 +10870,7 @@ async function runRunnerStartResolvedRoutes(routes, flags, options = {}) {
                         saveRunnerRouteState,
                         startRunnerTypingHeartbeat,
                         runRunnerAIExecution,
+                        explainExecutionFailureWithAI,
                         performLocalBotDelivery,
                         serializeRunnerTriggerPolicy,
                         serializeRunnerArchivePolicy,

package/lib/local-ai-adapters.mjs

@@ -949,7 +949,7 @@ function normalizeExecutionContract(rawContract) {
     || contract.target_summary_bot
     || "",
   ).trim().replace(/^@+/, "").toLowerCase();
-  const nextResponders = uniqueOrdered(
+  const explicitNextResponders = uniqueOrdered(
     ensureArray(contract.next_responders || contract.nextResponders || contract.responders)
       .map((item) => String(item || "").trim().replace(/^@+/, "").toLowerCase())
       .filter(Boolean),
@@ -962,6 +962,13 @@ function normalizeExecutionContract(rawContract) {
   ].includes(type)
     ? type
     : "";
+  const nextResponders = explicitNextResponders.length > 0
+    ? explicitNextResponders
+    : normalizedType === "delegation"
+      ? uniqueOrdered(assignments.map((item) => String(item.target_bot || item.targetBot || "").trim().replace(/^@+/, "").toLowerCase()).filter(Boolean))
+      : normalizedType === "summary_request" && summaryBot
+        ? [summaryBot]
+        : [];
   const actionable = contract.actionable === true
     || (normalizedType === "delegation" && assignments.length > 0)
     || (normalizedType === "summary_request" && Boolean(summaryBot))
@@ -1269,6 +1276,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 +2522,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-delivery.mjs

@@ -101,11 +101,18 @@ function normalizeExecutionContractForArchive(rawContract) {
     })
     .filter(Boolean);
   const summaryBot = normalizeMentionUsername(contract.summary_bot || contract.summaryBot || "");
-  const nextResponders = Array.from(new Set(
+  const explicitNextResponders = Array.from(new Set(
     ensureArray(contract.next_responders || contract.nextResponders || contract.responders)
       .map((item) => normalizeMentionUsername(item))
       .filter(Boolean),
   ));
+  const nextResponders = explicitNextResponders.length > 0
+    ? explicitNextResponders
+    : type === "delegation"
+      ? Array.from(new Set(assignments.map((item) => normalizeMentionUsername(item.target_bot)).filter(Boolean)))
+      : type === "summary_request" && summaryBot
+        ? [summaryBot]
+        : [];
   const actionable = contract.actionable === true;
   if (!type && !assignments.length && !summaryBot && !nextResponders.length && !actionable) {
     return null;

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);
@@ -960,14 +1109,26 @@ function buildHumanIntentFromPersistedRunnerRequest({
       .filter((item) => item && (managedSelectors.size === 0 || managedSelectors.has(item))),
   );
   const intentMode = String(persistedRequest.conversation_intent_mode || "").trim();
-  const intentType = normalizeHumanIntentType(
+  const persistedReplyExpectation = normalizeReplyExpectation(
+    persistedRequest.conversation_reply_expectation,
+    "",
+  );
+  const persistedExecutionActionable = persistedRequest.execution_contract_actionable === true;
+  const persistedNormalizedIntent = normalizeHumanIntentType(
     persistedRequest.normalized_intent || persistedRequest.intent_type,
     "",
   );
-  const replyExpectation = normalizeReplyExpectation(
-    persistedRequest.conversation_reply_expectation,
+  const intentType = normalizeHumanIntentType(
+    (
+      persistedNormalizedIntent === "general_execution"
+      && persistedReplyExpectation !== "actionable"
+      && !persistedExecutionActionable
+    )
+      ? ""
+      : persistedNormalizedIntent,
     "",
   );
+  const replyExpectation = persistedReplyExpectation;
   const participantSelectors = normalizeManagedSelectors(persistedRequest.conversation_participants);
   const initialResponderSelectors = normalizeManagedSelectors(persistedRequest.conversation_initial_responders);
   const allowedResponderSelectors = normalizeManagedSelectors(persistedRequest.conversation_allowed_responders);
@@ -1112,7 +1273,7 @@ function buildDirectHumanResponseContract({
     }
   }
   const requiresActionableContract = (
-    (replyExpectation === "actionable" || intentMode === "delegated_single_lead")
+    replyExpectation === "actionable"
     && Boolean(currentBotSelector)
     && initialResponderSelectors.includes(currentBotSelector)
   );
@@ -3158,11 +3319,18 @@ function normalizeConversationExecutionContract(
     || contract.summary_bot
     || conversationContext?.summaryBotUsername,
   );
-  const nextResponders = uniqueOrdered(
-    ensureArray(contract.nextResponders || contract.next_responders || contract.responders)
-      .map((item) => normalizeMentionSelector(item))
-      .filter((item) => !allowedResponderSet.size || allowedResponderSet.has(item)),
-  );
+  const explicitNextResponders = uniqueOrdered(
+    ensureArray(contract.nextResponders || contract.next_responders || contract.responders)
+      .map((item) => normalizeMentionSelector(item))
+      .filter((item) => !allowedResponderSet.size || allowedResponderSet.has(item)),
+  );
+  const nextResponders = explicitNextResponders.length > 0
+    ? explicitNextResponders
+    : normalizedType === "delegation"
+      ? uniqueOrdered(assignments.map((item) => normalizeMentionSelector(item.targetBot)).filter(Boolean))
+      : normalizedType === "summary_request" && summaryBot
+        ? [summaryBot]
+        : [];
   const actionable = contract.actionable === true
     || (normalizedType === "delegation" && assignments.length > 0)
     || (normalizedType === "summary_request" && Boolean(summaryBot || nextResponders.length))
@@ -3237,11 +3405,18 @@ function normalizeResponseExecutionContract(rawContract, responseContract, { cur
     contract.summaryBot
     || contract.summary_bot,
   );
-  const nextResponders = uniqueOrdered(
+  const explicitNextResponders = uniqueOrdered(
     ensureArray(contract.nextResponders || contract.next_responders || contract.responders)
       .map((item) => normalizeMentionSelector(item))
       .filter(Boolean),
   );
+  const nextResponders = explicitNextResponders.length > 0
+    ? explicitNextResponders
+    : normalizedType === "delegation"
+      ? uniqueOrdered(assignments.map((item) => normalizeMentionSelector(item.targetBot)).filter(Boolean))
+      : normalizedType === "summary_request" && summaryBot
+        ? [summaryBot]
+        : [];
   const actionable = contract.actionable === true
     || (normalizedType === "delegation" && assignments.length > 0)
     || (normalizedType === "summary_request" && Boolean(summaryBot || nextResponders.length))
@@ -3262,7 +3437,7 @@ function normalizeResponseExecutionContract(rawContract, responseContract, { cur
   };
 }
 
-function buildImplicitSummaryRequestContract(conversationContext, currentBotSelector) {
+function buildImplicitSummaryRequestContract(conversationContext, currentBotSelector) {
   if (String(conversationContext?.mode || "").trim() !== "public_multi_bot") {
     return null;
   }
@@ -3277,15 +3452,45 @@ function buildImplicitSummaryRequestContract(conversationContext, currentBotSele
   if (!summaryBotSelector || !currentSelector || summaryBotSelector === currentSelector) {
     return null;
   }
-  return {
-    type: "summary_request",
-    actionable: true,
-    assignments: [],
-    summaryBot: summaryBotSelector,
-    nextResponders: [summaryBotSelector],
-    implicit: true,
-  };
-}
+  return {
+    type: "summary_request",
+    actionable: true,
+    assignments: [],
+    summaryBot: summaryBotSelector,
+    nextResponders: [summaryBotSelector],
+    implicit: true,
+  };
+}
+
+function collectExecutionContractNextResponders(executionContract) {
+  const contract = safeObject(executionContract);
+  const normalizedType = String(
+    contract.type
+    || contract.contract_type
+    || contract.contractType
+    || "",
+  ).trim().toLowerCase();
+  const explicitNextResponders = uniqueOrdered(
+    ensureArray(contract.nextResponders || contract.next_responders || contract.responders)
+      .map((item) => normalizeMentionSelector(item))
+      .filter(Boolean),
+  );
+  if (explicitNextResponders.length > 0) {
+    return explicitNextResponders;
+  }
+  if (normalizedType === "delegation") {
+    return uniqueOrdered(
+      ensureArray(contract.assignments)
+        .map((item) => normalizeMentionSelector(safeObject(item).targetBot || safeObject(item).target_bot))
+        .filter(Boolean),
+    );
+  }
+  const summaryBot = normalizeMentionSelector(contract.summaryBot || contract.summary_bot);
+  if (normalizedType === "summary_request" && summaryBot) {
+    return [summaryBot];
+  }
+  return [];
+}
 
 function conversationSessionIsExpired(session, policy, nowMs = Date.now()) {
   const expiresAtMs = parseISOStringMs(safeObject(session).expires_at);
@@ -4176,6 +4381,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 +4621,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;
     }
@@ -4687,6 +4922,24 @@ export async function processRunnerSelectedRecord({
       .filter(Boolean),
   );
   let requiresActionableContract = safeObject(aiPayload.response_contract).require_actionable_contract === true;
+  const normalizedConversationInitialResponders = uniqueOrdered(
+    ensureArray(conversationContext?.initialResponderSelectors)
+      .map((item) => normalizeMentionSelector(item))
+      .filter(Boolean),
+  );
+  const normalizedConversationAllowedResponders = uniqueOrdered(
+    ensureArray(conversationContext?.allowedResponderSelectors)
+      .map((item) => normalizeMentionSelector(item))
+      .filter(Boolean),
+  );
+  const peerAllowedResponders = normalizedConversationAllowedResponders.filter((item) => item && item !== currentBotSelector);
+  const requiresPeerDelegationContract = conversationContext?.mode === "public_multi_bot"
+    && String(conversationContext?.stage || "").trim() === "human_opening"
+    && conversationContext?.allowBotToBot === true
+    && Boolean(currentBotSelector)
+    && normalizedConversationInitialResponders.length === 1
+    && normalizedConversationInitialResponders.includes(currentBotSelector)
+    && peerAllowedResponders.length > 0;
   const directHumanPeerMap = humanIntentContext?.peerMap instanceof Map
     ? humanIntentContext.peerMap
     : buildConversationPeerMap(bot, normalizedRoute, executionDeps);
@@ -4704,6 +4957,10 @@ export async function processRunnerSelectedRecord({
   if (delegatedBotMentions.length > 0) {
     allowedActionableTypes = new Set(["delegation"]);
   }
+  if (requiresPeerDelegationContract) {
+    allowedActionableTypes = new Set(["delegation"]);
+    requiresActionableContract = true;
+  }
   let hasValidActionableContract = Boolean(
     executionContract
     && executionContract.actionable === true
@@ -4744,7 +5001,7 @@ export async function processRunnerSelectedRecord({
         allow_skip: false,
         must_reply: true,
         require_actionable_contract: true,
-        human_intent_mode: effectiveResponseContractPayload.human_intent_mode || (delegatedBotMentions.length > 0 ? "delegated_single_lead" : ""),
+        human_intent_mode: effectiveResponseContractPayload.human_intent_mode || ((delegatedBotMentions.length > 0 || requiresPeerDelegationContract) ? "delegated_single_lead" : ""),
         human_lead_bot: delegatedBotMentions.length > 0
           ? currentBotSelector
           : String(effectiveResponseContractPayload.human_lead_bot || "").trim(),
@@ -4755,10 +5012,10 @@ export async function processRunnerSelectedRecord({
           ? ensureArray(effectiveResponseContractPayload.human_allowed_responders)
           : uniqueOrdered([
             currentBotSelector,
-            ...delegatedBotMentions,
+            ...(delegatedBotMentions.length > 0 ? delegatedBotMentions : peerAllowedResponders),
           ].filter(Boolean)),
-        allow_bot_to_bot: delegatedBotMentions.length > 0 || effectiveResponseContractPayload.human_intent_mode === "delegated_single_lead",
-        allowed_contract_types: delegatedBotMentions.length > 0
+        allow_bot_to_bot: delegatedBotMentions.length > 0 || requiresPeerDelegationContract || effectiveResponseContractPayload.human_intent_mode === "delegated_single_lead",
+        allowed_contract_types: delegatedBotMentions.length > 0 || requiresPeerDelegationContract
           ? ["delegation", "summary_request", "final_summary"]
           : ensureArray(effectiveResponseContractPayload.allowed_contract_types).length
             ? ensureArray(effectiveResponseContractPayload.allowed_contract_types)
@@ -5077,10 +5334,7 @@ export async function processRunnerSelectedRecord({
           last_execution_contract_type: String(executionContract?.type || "").trim(),
           last_execution_contract_actionable: executionContract?.actionable === true,
           last_execution_contract_targets: ensureArray(executionContract?.assignments).map((item) => normalizeMentionSelector(item.targetBot)).filter(Boolean),
-          next_expected_responders: uniqueOrdered([
-            ...ensureArray(executionContract?.nextResponders).map((item) => normalizeMentionSelector(item)).filter(Boolean),
-            normalizeMentionSelector(executionContract?.summaryBot),
-          ]),
+          next_expected_responders: collectExecutionContractNextResponders(executionContract),
           last_speaker_bot_username: currentBotSelector,
           speaker_counts: speakerCounts,
           last_sender_bot_username: String(effectiveConversationContext?.senderBotUsername || "").trim(),
@@ -5176,10 +5430,7 @@ export async function processRunnerSelectedRecord({
       execution_contract_type: String(executionContract?.type || "").trim(),
       execution_contract_actionable: executionContract?.actionable === true,
       execution_contract_targets: ensureArray(executionContract?.assignments).map((item) => normalizeMentionSelector(item.targetBot)).filter(Boolean),
-      next_expected_responders: uniqueOrdered([
-        ...ensureArray(executionContract?.nextResponders).map((item) => normalizeMentionSelector(item)).filter(Boolean),
-        normalizeMentionSelector(executionContract?.summaryBot),
-      ]),
+      next_expected_responders: collectExecutionContractNextResponders(executionContract),
       artifact_validation: String(artifactValidation.status || "").trim() || "none",
       artifact_paths: summarizeValidatedArtifactPaths(artifactValidation),
       ctxpack_version_id: String(safeObject(aiResult?.ctxpackUpdate).version_id || "").trim(),

package/lib/selftest-runner-scenarios.mjs

@@ -1569,9 +1569,9 @@ export async function runSelftestRunnerScenarios(push, deps) {
     });
     const inferredExecutionRequest = safeObject(safeObject(loadBotRunnerState().requests)[inferredExecutionClaim.requestKey]);
     push(
-      "runner_request_claim_defaults_actionable_messages_to_general_execution",
+      "runner_request_claim_leaves_unclassified_messages_unresolved",
       inferredExecutionClaim.ok === true
-        && String(inferredExecutionRequest.normalized_intent || "") === "general_execution",
+        && String(inferredExecutionRequest.normalized_intent || "") === "",
       `intent=${String(inferredExecutionRequest.normalized_intent || "(none)")} request=${String(inferredExecutionClaim.requestKey || "(none)")}`,
     );
 
@@ -4785,7 +4785,7 @@ export async function runSelftestRunnerScenarios(push, deps) {
     push(
       "direct_human_public_delegate_fallback_uses_response_allowed_responders",
       processed.kind === "replied"
-        && aiCalls === 1
+        && aiCalls === 2
         && String(deliveredConversation[0]?.mode || "") === "public_multi_bot"
         && Array.isArray(deliveredConversation[0]?.allowedResponderSelectors)
         && deliveredConversation[0].allowedResponderSelectors.includes("ryoai3_bot")
@@ -5064,14 +5064,14 @@ export async function runSelftestRunnerScenarios(push, deps) {
       },
     });
     push(
-      "delegated_single_lead_lead_opening_requires_actionable_contract",
+      "delegated_single_lead_lead_opening_requires_delegation_contract_for_peer_followup",
       processed.kind === "skipped"
         && aiCalls === 2
-        && /actionable execution contract/i.test(String(processed.skippedRecord?.reason || "")),
-      `kind=${String(processed.kind || "(none)")} ai_calls=${aiCalls} reason=${String(processed.skippedRecord?.reason || "(none)")}`,
+        && !String(deliveredText || "").trim(),
+      `kind=${String(processed.kind || "(none)")} ai_calls=${aiCalls} reply=${String(deliveredText || "(none)")}`,
     );
   } catch (err) {
-    push("delegated_single_lead_lead_opening_requires_actionable_contract", false, String(err?.message || err));
+    push("delegated_single_lead_lead_opening_requires_delegation_contract_for_peer_followup", false, String(err?.message || err));
   }
 
   try {
@@ -5207,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.206",
+  "version": "0.2.208",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [