@adhdev/daemon-core 0.9.82-rc.70 → 0.9.82-rc.71

package/dist/index.js

@@ -1192,6 +1192,7 @@ function buildRulesSection(coordinatorCliType) {
 - **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
 - **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, fast-forward obvious clean behind-only branches with \`mesh_fast_forward_node\`, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
 - **Keep Refinery validation project-configurable.** \`mesh_refine_node\` must execute validation from repo mesh/refine config (for example \`.adhdev/refine.{json,yaml,yml}\`, \`.adhdev/repo-mesh-refine.*\`, or \`repo-mesh.refine.*\`). Heuristics are suggestions/scaffolding only, not the execution path.
+- **Treat submodule reachability as publish-needed.** A \`submodule_reachability_failed\` refine result means the root gitlink points at a submodule commit that is not reachable from the configured submodule remote. Do not retry validation blindly or start code review first. Classify it as \`blocked_review\`, request user approval to push/publish the submodule commit, then rerun \`mesh_refine_node\`.
 - **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
 }
 var TOOLS_SECTION, TOOL_EXPOSURE_PREFLIGHT_SECTION, WORKFLOW_SECTION;
@@ -1238,7 +1239,7 @@ Before doing any coordinator work, confirm that the actual callable tool list in
 4. **Monitor** \u2014 Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** \u2014 When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** \u2014 Call \`mesh_checkpoint\` to save the work.
-7. **Converge branches** \u2014 Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary. For obvious clean branch catch-up (ahead 0, behind > 0, upstream fresh, no dirty/stash/submodule issues), use \`mesh_fast_forward_node\` dry-run first and execute only when explicitly safe/approved; this avoids consuming an agent session. Use \`mesh_refine_node\` for clean worktree branches when safe. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
+7. **Converge branches** \u2014 Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary. For obvious clean branch catch-up (ahead 0, behind > 0, upstream fresh, no dirty/stash/submodule issues), use \`mesh_fast_forward_node\` dry-run first and execute only when explicitly safe/approved; this avoids consuming an agent session. Use \`mesh_refine_node\` for clean worktree branches when safe. Before/refine merging root commits that contain submodule gitlink changes, require each submodule commit to be reachable from its configured remote. If \`mesh_refine_node\` returns \`submodule_reachability_failed\` or publish-required evidence, keep the public convergence bucket as \`blocked_review\`, ask the user for explicit approval to push/publish the unreachable submodule commit(s), then rerun \`mesh_refine_node\`; do not merge the root branch until the submodule commit(s) are reachable. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
 8. **Clean up** \u2014 Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
 9. **Report** \u2014 Summarize what was done, what changed, any issues, and the branch convergence state.
 
@@ -15819,6 +15820,7 @@ function buildSessionModalDeliverySignature(payload) {
 var RECENT_SEND_WINDOW_MS = 1200;
 var READ_CHAT_PROVIDER_EVAL_TIMEOUT_MS = 25e3;
 var HERMES_CLI_STARTING_SEND_SETTLE_MS = 2e3;
+var CODEX_NATIVE_HISTORY_FRESH_MS = 5 * 6e4;
 var recentSendByTarget = /* @__PURE__ */ new Map();
 function getCurrentProviderType(h, fallback = "") {
   return h.currentSession?.providerType || h.currentProviderType || fallback;
@@ -15952,6 +15954,77 @@ function normalizeReadChatMessages(payload) {
   const messages = Array.isArray(payload.messages) ? payload.messages : [];
   return normalizeChatMessages(messages);
 }
+function getMessageNewestReceivedAt(messages) {
+  let newest = 0;
+  for (const message of messages) {
+    const receivedAt = Number(message?.receivedAt ?? message?.timestamp ?? 0);
+    if (Number.isFinite(receivedAt) && receivedAt > newest) newest = receivedAt;
+  }
+  return newest;
+}
+function buildCliMessageSourceProvenance(args) {
+  const sourceMtimeMs = Number(args.sourceMtimeMs || 0);
+  const sourceMtimeAgeMs = sourceMtimeMs > 0 ? Math.max(0, Date.now() - sourceMtimeMs) : void 0;
+  const nativeMessages = args.nativeMessages || [];
+  const ptyMessages = args.ptyMessages || [];
+  const returnedMessages = args.returnedMessages || [];
+  return {
+    selected: args.selected,
+    provider: args.provider,
+    ...args.nativeHandle ? { nativeHandle: args.nativeHandle } : {},
+    ...args.fallbackReason ? { fallbackReason: args.fallbackReason } : {},
+    ...args.nativeSource ? { nativeSource: args.nativeSource } : {},
+    ...args.sourcePath ? { sourcePath: args.sourcePath } : {},
+    ptyStatusApprovalOnly: args.ptyStatusApprovalOnly === true,
+    staleness: {
+      sourceMtimeMs: sourceMtimeMs || void 0,
+      sourceMtimeAgeMs,
+      nativeNewestMessageAt: getMessageNewestReceivedAt(nativeMessages),
+      ptyNewestMessageAt: getMessageNewestReceivedAt(ptyMessages),
+      freshEnough: args.freshEnough === true
+    },
+    coverage: {
+      nativeMessageCount: nativeMessages.length,
+      ptyMessageCount: ptyMessages.length,
+      returnedMessageCount: returnedMessages.length,
+      safeMapping: args.safeMapping === true
+    }
+  };
+}
+function buildNativeHistoryFallbackReason(args) {
+  if (args.providerType !== "codex-cli") return "provider_not_codex_cli";
+  if (args.nativeSource === "native-unavailable") return "native_history_unavailable";
+  if (args.nativeSource && args.nativeSource !== "provider-native") return `native_history_source_${args.nativeSource}`;
+  if (args.nativeMessageCount <= 0) return "native_history_empty";
+  if (!args.safeMapping) return "native_history_not_safely_mapped";
+  if (!args.freshEnough) return "native_history_stale";
+  return "native_history_not_selected";
+}
+function isCodexCliProvider(providerType) {
+  return providerType === "codex-cli";
+}
+function hasSafeNativeHistoryMapping(args) {
+  const explicitSessionId = String(args.historySessionId || args.providerSessionId || "").trim();
+  if (explicitSessionId) {
+    const messageSessionIds = args.nativeMessages.map((message) => typeof message?.historySessionId === "string" ? message.historySessionId.trim() : "").filter(Boolean);
+    if (messageSessionIds.length === 0) return true;
+    return messageSessionIds.some((id) => id === explicitSessionId);
+  }
+  const workspace = String(args.workspace || "").trim();
+  if (!workspace) return false;
+  return args.nativeMessages.some((message) => String(message?.workspace || "").trim() === workspace);
+}
+function isNativeHistoryFreshEnough(args) {
+  const nativeNewest = getMessageNewestReceivedAt(args.nativeMessages);
+  const ptyNewest = getMessageNewestReceivedAt(args.ptyMessages);
+  if (nativeNewest > 0 && nativeNewest >= ptyNewest) return true;
+  const sourceMtimeMs = Number(args.sourceMtimeMs || 0);
+  if (sourceMtimeMs > 0 && Date.now() - sourceMtimeMs <= CODEX_NATIVE_HISTORY_FRESH_MS) return true;
+  return ptyNewest === 0 && nativeNewest > 0;
+}
+function shouldPreserveReadChatPayloadField(key) {
+  return key === "messageSource" || key === "transcriptProvenance";
+}
 function deriveHistoryDedupKey(message) {
   const unitKey = typeof message._unitKey === "string" ? message._unitKey.trim() : "";
   if (unitKey) return `read_chat:${unitKey}`;
@@ -16057,6 +16130,7 @@ function buildReadChatCommandResult(payload, args) {
   return {
     success: true,
     ...validatedPayload,
+    ...Object.fromEntries(Object.entries(payload).filter(([key]) => shouldPreserveReadChatPayloadField(key))),
     messages: sync.messages,
     totalMessages: sync.totalMessages,
     ...returnedDebugReadChat ? { debugReadChat: returnedDebugReadChat } : {}
@@ -16233,6 +16307,8 @@ function buildChatDebugBundleSummary(bundle) {
       adapterStatus: debugReadChat.adapterStatus,
       parsedStatus: debugReadChat.parsedStatus,
       returnedStatus: debugReadChat.returnedStatus,
+      selectedMessageSource: debugReadChat.selectedMessageSource,
+      messageSource: debugReadChat.messageSource,
       parsedMsgCount: debugReadChat.parsedMsgCount,
       returnedMsgCount: debugReadChat.returnedMsgCount,
       shouldPreferAdapterMessages: debugReadChat.shouldPreferAdapterMessages
@@ -16308,6 +16384,8 @@ async function handleGetChatDebugBundle(h, args) {
       providerSessionId: readResult.providerSessionId,
       transcriptAuthority: readResult.transcriptAuthority,
       coverage: readResult.coverage,
+      messageSource: readResult.messageSource,
+      transcriptProvenance: readResult.transcriptProvenance,
       activeModal: readResult.activeModal,
       messagesTail: Array.isArray(readResult.messages) ? readResult.messages.slice(-20) : [],
       debugReadChat: readResult.debugReadChat
@@ -16505,25 +16583,134 @@ async function handleReadChat(h, args) {
       const runtimeMessageMerger = getTargetInstance(h, args);
       const parsedMessages = finalizeStreamingMessagesWhenIdle(parsedRecord.messages, returnedStatus);
       const returnedMessages = runtimeMessageMerger?.category === "cli" && runtimeMessageMerger.type === adapter.cliType && typeof runtimeMessageMerger.mergeRuntimeChatMessages === "function" ? runtimeMessageMerger.mergeRuntimeChatMessages(parsedMessages) : parsedMessages;
+      const providerType = provider?.type || adapter.cliType;
+      let selectedMessages = returnedMessages;
+      let selectedTitle = title;
+      let selectedProviderSessionId = providerSessionId;
+      let selectedTranscriptAuthority = transcriptAuthority;
+      let selectedCoverage = coverage;
+      let messageSource = buildCliMessageSourceProvenance({
+        selected: "pty-parser",
+        provider: adapter.cliType,
+        fallbackReason: isCodexCliProvider(providerType) ? "native_history_not_checked" : "provider_not_codex_cli",
+        ptyMessages: returnedMessages,
+        returnedMessages,
+        ptyStatusApprovalOnly: false
+      });
+      if (isCodexCliProvider(providerType)) {
+        const agentStr = provider?.type || args?.agentType || getCurrentProviderType(h, adapter.cliType);
+        const workspace = typeof args?.workspace === "string" ? args.workspace : typeof h.currentSession?.workspace === "string" ? h.currentSession.workspace : typeof adapter.workingDir === "string" ? adapter.workingDir : void 0;
+        const nativeHistoryLimit = Math.max(
+          normalizeReadChatTailLimit(args) || 0,
+          returnedMessages.length,
+          200
+        );
+        let nativeHistory = null;
+        try {
+          nativeHistory = readProviderChatHistory(agentStr, {
+            canonicalHistory: provider?.canonicalHistory,
+            historySessionId,
+            workspace,
+            offset: 0,
+            limit: nativeHistoryLimit,
+            excludeRecentCount: 0,
+            historyBehavior: provider?.historyBehavior,
+            scripts: provider?.scripts
+          });
+        } catch (error) {
+          const fallbackReason = `native_history_error:${error?.message || String(error)}`;
+          messageSource = buildCliMessageSourceProvenance({
+            selected: "pty-parser",
+            provider: adapter.cliType,
+            fallbackReason,
+            ptyMessages: returnedMessages,
+            returnedMessages,
+            ptyStatusApprovalOnly: false
+          });
+          nativeHistory = null;
+        }
+        if (nativeHistory) {
+          const nativeMessages = Array.isArray(nativeHistory.messages) ? normalizeChatMessages(nativeHistory.messages) : [];
+          const historyProviderSessionId = typeof nativeHistory?.providerSessionId === "string" ? nativeHistory.providerSessionId : historySessionId;
+          const safeMapping = hasSafeNativeHistoryMapping({
+            historySessionId,
+            providerSessionId,
+            workspace,
+            nativeMessages
+          });
+          const freshEnough = isNativeHistoryFreshEnough({
+            sourceMtimeMs: nativeHistory.sourceMtimeMs,
+            nativeMessages,
+            ptyMessages: returnedMessages
+          });
+          if (nativeHistory.source === "provider-native" && nativeMessages.length > 0 && safeMapping && freshEnough) {
+            selectedMessages = finalizeStreamingMessagesWhenIdle(nativeMessages, returnedStatus);
+            selectedProviderSessionId = historyProviderSessionId || providerSessionId;
+            selectedTranscriptAuthority = "provider";
+            selectedCoverage = nativeHistory.hasMore ? "tail" : "full";
+            messageSource = buildCliMessageSourceProvenance({
+              selected: "native-history",
+              provider: adapter.cliType,
+              nativeHandle: selectedProviderSessionId || historySessionId,
+              nativeSource: nativeHistory.source,
+              sourcePath: nativeHistory.sourcePath,
+              sourceMtimeMs: nativeHistory.sourceMtimeMs,
+              nativeMessages,
+              ptyMessages: returnedMessages,
+              returnedMessages: selectedMessages,
+              safeMapping,
+              freshEnough,
+              ptyStatusApprovalOnly: true
+            });
+          } else {
+            const fallbackReason = buildNativeHistoryFallbackReason({
+              providerType,
+              nativeSource: nativeHistory.source,
+              nativeMessageCount: nativeMessages.length,
+              safeMapping,
+              freshEnough
+            });
+            messageSource = buildCliMessageSourceProvenance({
+              selected: "pty-parser",
+              provider: adapter.cliType,
+              nativeHandle: historyProviderSessionId || historySessionId,
+              fallbackReason,
+              nativeSource: nativeHistory.source,
+              sourcePath: nativeHistory.sourcePath,
+              sourceMtimeMs: nativeHistory.sourceMtimeMs,
+              nativeMessages,
+              ptyMessages: returnedMessages,
+              returnedMessages,
+              safeMapping,
+              freshEnough,
+              ptyStatusApprovalOnly: false
+            });
+          }
+        }
+      }
       LOG.debug("Command", `[read_chat] cli-like parsed provider=${adapter.cliType} target=${String(args?.targetSessionId || "")} adapterStatus=${String(adapterStatus.status || "")} parsedStatus=${String(parsedRecord.status || "")} parsedMsgCount=${parsedRecord.messages.length} returnedMsgCount=${returnedMessages.length}`);
       return buildReadChatCommandResult({
-        messages: returnedMessages,
+        messages: selectedMessages,
         status: returnedStatus,
         activeModal,
+        messageSource,
+        transcriptProvenance: messageSource,
         debugReadChat: {
           provider: adapter.cliType,
           targetSessionId: String(args?.targetSessionId || ""),
           adapterStatus: String(adapterStatus.status || ""),
           parsedStatus: String(parsedRecord.status || ""),
           returnedStatus: String(returnedStatus || ""),
-          shouldPreferAdapterMessages: false,
+          selectedMessageSource: messageSource.selected,
+          messageSource,
+          shouldPreferAdapterMessages: messageSource.selected !== "native-history",
           parsedMsgCount: parsedRecord.messages.length,
-          returnedMsgCount: returnedMessages.length
+          returnedMsgCount: selectedMessages.length
         },
-        ...title ? { title } : {},
-        ...providerSessionId ? { providerSessionId } : {},
-        ...transcriptAuthority ? { transcriptAuthority } : {},
-        ...coverage ? { coverage } : {}
+        ...selectedTitle ? { title: selectedTitle } : {},
+        ...selectedProviderSessionId ? { providerSessionId: selectedProviderSessionId } : {},
+        ...selectedTranscriptAuthority ? { transcriptAuthority: selectedTranscriptAuthority } : {},
+        ...selectedCoverage ? { coverage: selectedCoverage } : {}
       }, args);
     }
     const historyLimit = normalizeReadChatTailLimit(args);
@@ -19567,7 +19754,7 @@ var CliProviderInstance = class {
         chatTitle: pending.chatTitle,
         duration: pending.duration,
         timestamp: pending.timestamp,
-        finalSummary: extractFinalSummaryFromMessages(this.adapter?.getScriptParsedStatus()?.messages),
+        finalSummary: blockReason.startsWith("parsed_status:") ? "" : extractFinalSummaryFromMessages(this.adapter?.getScriptParsedStatus()?.messages),
         completionDiagnostic
       });
       this.completedDebouncePending = null;
@@ -21405,6 +21592,10 @@ function commandExists(command) {
     return false;
   }
 }
+var BUSY_AGENT_STATUSES = /* @__PURE__ */ new Set(["generating", "running", "streaming", "starting", "busy", "waiting", "waiting_approval", "long_generating"]);
+function normalizeAgentStatus(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
 var chalkModule = import_chalk.default;
 var chalkApi = typeof chalkModule.yellow === "function" ? chalkModule : chalkModule.default || null;
 function colorize(color, text) {
@@ -22179,6 +22370,19 @@ Run 'adhdev doctor' for detailed diagnostics.`
         if (!found) throw new Error(`CLI agent not running: ${agentType}`);
         const { adapter, key } = found;
         if (action === "send_chat") {
+          const currentStatus = normalizeAgentStatus(adapter.getStatus?.()?.status);
+          if (BUSY_AGENT_STATUSES.has(currentStatus)) {
+            return {
+              success: false,
+              code: "agent_runtime_busy",
+              reason: "agent_runtime_busy",
+              retryable: true,
+              retryRecommended: true,
+              status: currentStatus,
+              targetSessionId: args?.targetSessionId,
+              error: `CLI agent '${agentType}' is currently ${currentStatus}; retry after the current turn finishes.`
+            };
+          }
           const input = normalizeInputEnvelope(args?.input ? { input: args.input } : args);
           const provider = this.providerLoader.resolve(agentType) || this.providerLoader.getMeta(agentType);
           if (provider?.category === "acp") {
@@ -26323,6 +26527,10 @@ function recordMeshRefineStage(stages, stage, status, startedAt, details) {
     ...details || {}
   });
 }
+function buildSubmodulePublishRequiredNextStep(entries) {
+  const refs = entries.map((entry) => `${entry.path}@${entry.commit}`).join(", ");
+  return `Ask the user for explicit approval to push/publish the unreachable submodule commit(s) (${refs}) to their configured submodule remote(s), then rerun mesh_refine_node. Do not merge the root branch until every submodule gitlink commit is reachable from its configured remote.`;
+}
 async function computeGitPatchId(cwd, fromRef, toRef) {
   const { execFileSync: execFileSync3 } = await import("child_process");
   const diff = execFileSync3("git", ["diff", "--patch", "--full-index", fromRef, toRef], {
@@ -26408,6 +26616,16 @@ async function runMeshRefineSubmoduleReachabilityGate(repoRoot, mergedTree) {
       });
       return String(stdout || "");
     };
+    const verifyRemoteCommitReachable = async (remoteUrl, commit) => {
+      const probeDir = fs11.mkdtempSync((0, import_path8.join)((0, import_os3.tmpdir)(), "adhdev-submodule-reachability-"));
+      try {
+        await runGit2(probeDir, ["init", "-q"]);
+        await runGit2(probeDir, ["-c", "protocol.file.allow=always", "fetch", "--depth=1", remoteUrl, commit]);
+        await runGit2(probeDir, ["cat-file", "-e", `${commit}^{commit}`]);
+      } finally {
+        fs11.rmSync(probeDir, { recursive: true, force: true });
+      }
+    };
     const treeOutput = await runGit2(repoRoot, ["ls-tree", "-r", "-z", mergedTree]);
     const gitlinks = treeOutput.split("\0").filter(Boolean).map((record) => {
       const match = /^160000\s+commit\s+([0-9a-f]{40})\t(.+)$/.exec(record);
@@ -26423,27 +26641,43 @@ async function runMeshRefineSubmoduleReachabilityGate(repoRoot, mergedTree) {
       try {
         if (!fs11.existsSync(submodulePath)) {
           entry.error = `Submodule checkout missing at ${gitlink.path}`;
+          entry.publishRequired = true;
           entries.push(entry);
           continue;
         }
         entry.checkedLocal = true;
         try {
           await runGit2(submodulePath, ["cat-file", "-e", `${gitlink.commit}^{commit}`]);
-          entry.reachable = true;
-          entries.push(entry);
-          continue;
+          entry.localReachable = true;
         } catch {
+          entry.localReachable = false;
         }
         try {
-          await runGit2(submodulePath, ["fetch", "origin", gitlink.commit]);
+          entry.remote = "origin";
+          let remoteUrl = "";
+          try {
+            remoteUrl = (await runGit2(submodulePath, ["remote", "get-url", "origin"])).trim();
+            if (!remoteUrl) throw new Error("origin remote has no URL");
+            entry.remoteUrl = remoteUrl;
+          } catch {
+            entry.error = "Submodule remote reachability check failed: no configured origin remote";
+            entry.publishRequired = true;
+            entries.push(entry);
+            continue;
+          }
+          await verifyRemoteCommitReachable(remoteUrl, gitlink.commit);
           entry.fetchedFromOrigin = true;
-          await runGit2(submodulePath, ["cat-file", "-e", `${gitlink.commit}^{commit}`]);
+          entry.remoteReachable = true;
           entry.reachable = true;
         } catch (e) {
-          entry.error = truncateValidationOutput(e?.stderr || e?.message || String(e));
+          entry.remoteReachable = false;
+          entry.publishRequired = true;
+          const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
+          entry.error = `Submodule remote reachability check failed for origin: ${details}`;
         }
       } catch (e) {
         entry.error = truncateValidationOutput(e?.message || String(e));
+        entry.publishRequired = true;
       }
       entries.push(entry);
     }
@@ -26451,16 +26685,17 @@ async function runMeshRefineSubmoduleReachabilityGate(repoRoot, mergedTree) {
     return {
       status: unreachable.length ? "failed" : "passed",
       checked: entries.length,
-      unreachable,
-      entries,
+      unreachable: unreachable.map((entry) => ({ ...entry, publishRequired: entry.publishRequired !== false })),
+      entries: entries.map((entry) => entry.reachable ? entry : { ...entry, publishRequired: entry.publishRequired !== false }),
       durationMs: Date.now() - startedAt
     };
   } catch (e) {
+    const unreachable = entries.filter((entry) => !entry.reachable).map((entry) => ({ ...entry, publishRequired: true }));
     return {
       status: "failed",
       checked: entries.length,
-      unreachable: entries.filter((entry) => !entry.reachable),
-      entries,
+      unreachable,
+      entries: entries.map((entry) => entry.reachable ? entry : { ...entry, publishRequired: true }),
       durationMs: Date.now() - startedAt,
       error: truncateValidationOutput(e?.message || String(e))
     };
@@ -27579,15 +27814,41 @@ var DaemonCommandRouter = class {
       const submoduleReachability = await runMeshRefineSubmoduleReachabilityGate(repoRoot, patchEquivalence.mergedTree || branchHead);
       recordMeshRefineStage(refineStages, "submodule_reachability", submoduleReachability.status, submoduleReachabilityStarted, {
         checked: submoduleReachability.checked,
-        unreachable: submoduleReachability.unreachable.map((entry) => ({ path: entry.path, commit: entry.commit, error: entry.error })),
+        unreachable: submoduleReachability.unreachable.map((entry) => ({
+          path: entry.path,
+          commit: entry.commit,
+          publishRequired: entry.publishRequired === true,
+          remote: entry.remote,
+          remoteUrl: entry.remoteUrl,
+          remoteReachable: entry.remoteReachable,
+          error: entry.error
+        })),
         error: submoduleReachability.error
       });
       if (submoduleReachability.status === "failed") {
+        const nextStep = buildSubmodulePublishRequiredNextStep(submoduleReachability.unreachable);
         return {
           success: false,
           code: "submodule_reachability_failed",
           convergenceStatus: "blocked_review",
-          error: "Refinery submodule reachability preflight failed; merge/refine cleanup was not attempted.",
+          publishRequired: true,
+          blockedReason: "submodule_publish_required",
+          error: "Refinery submodule reachability preflight failed because one or more submodule gitlink commits are not reachable from their configured remote; merge/refine cleanup was not attempted.",
+          nextStep,
+          nextSteps: [
+            "Ask the user for explicit approval before pushing or publishing any submodule commit.",
+            "Push/publish each unreachable submodule commit to the configured submodule remote shown in the evidence.",
+            "Rerun mesh_refine_node after remote reachability is confirmed.",
+            "Do not merge the root branch until every submodule gitlink commit is reachable from its configured remote."
+          ],
+          unreachableSubmoduleCommits: submoduleReachability.unreachable.map((entry) => ({
+            path: entry.path,
+            commit: entry.commit,
+            remote: entry.remote,
+            remoteUrl: entry.remoteUrl,
+            remoteReachable: entry.remoteReachable,
+            error: entry.error
+          })),
           branch,
           into: baseBranch,
           validationSummary,
@@ -27602,7 +27863,9 @@ var DaemonCommandRouter = class {
             validation: "passed",
             patchEquivalence: "passed",
             submoduleReachability: "failed",
-            status: "blocked_review"
+            status: "blocked_review",
+            reason: "submodule_publish_required",
+            nextStep
           }
         };
       }