@adhdev/daemon-core 0.9.82-rc.553 → 0.9.82-rc.555

package/dist/cli-adapter-types.d.ts

@@ -5,6 +5,7 @@
  */
 import type { ChatMessage } from './types.js';
 import type { InteractivePrompt, InteractivePromptResponse } from './providers/types/interactive-prompt.js';
+import type { MeshSendKeyItem, MeshSendKeyName } from './cli-adapters/provider-cli-shared.js';
 export interface CliAdapterStatus {
     status?: string;
     parsedStatus?: string;
@@ -118,6 +119,34 @@ export interface CliAdapter {
     cancel(): void;
     isProcessing(): boolean;
     isReady(): boolean;
+    isAlive?(): boolean;
+    getTerminalScreenSnapshot?(maxBytes?: number): {
+        text: string;
+        cursor: {
+            col: number;
+            row: number;
+        };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    };
+    injectKeys?(items: MeshSendKeyItem[], opts?: {
+        allowModalOverride?: boolean;
+    }): Promise<{
+        ok: true;
+        keys: MeshSendKeyName[];
+        hasDestructive: boolean;
+        submits: boolean;
+        bytes: number;
+    } | {
+        ok: false;
+        refused: 'submit_race' | 'actionable_modal';
+        keys: MeshSendKeyName[];
+        hasDestructive: boolean;
+    }>;
     setOnStatusChange(callback: () => void): void;
     updateRuntimeSettings?(settings: Record<string, unknown>): void;
     setCliScripts?(scripts: Record<string, unknown>): void;

package/dist/index.js

@@ -428,10 +428,10 @@ function readInjected(value) {
 }
 function getDaemonBuildInfo() {
   if (cached) return cached;
-  const commit = readInjected(true ? "3fc4f272513b6f628ec1732ef57d9ed94e08b8ff" : void 0) ?? "unknown";
-  const commitShort = readInjected(true ? "3fc4f272" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
-  const version = readInjected(true ? "0.9.82-rc.553" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
-  const builtAt = readInjected(true ? "2026-07-17T06:04:22.090Z" : void 0);
+  const commit = readInjected(true ? "45a19b2d93612559899332379b6953a02a4b4ccb" : void 0) ?? "unknown";
+  const commitShort = readInjected(true ? "45a19b2d" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
+  const version = readInjected(true ? "0.9.82-rc.555" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
+  const builtAt = readInjected(true ? "2026-07-17T08:34:01.452Z" : void 0);
   cached = builtAt ? { commit, commitShort, version, builtAt } : { commit, commitShort, version };
   return cached;
 }
@@ -43722,6 +43722,12 @@ var TerminalAdapter = class {
     const pos = this.screen.getCursorPosition();
     return { row: pos.row, col: pos.col };
   }
+  /** Current terminal geometry (columns × rows). Tracked here rather than
+   *  read off the screen buffer so a resize is reflected immediately, before
+   *  the next repaint. Consumed by the mesh_read_terminal viewport read. */
+  getScreenSize() {
+    return { cols: this.cols, rows: this.rows };
+  }
   send_keys(text) {
     this.recordEvent("input", capPreview(escapeControl(text)), text.length);
     this.pty?.write(text);
@@ -44060,6 +44066,9 @@ var FsmDriver = class {
   getScreen() {
     return this.adapter.snapshot();
   }
+  getScreenSize() {
+    return this.adapter.getScreenSize();
+  }
   /** Scrollback-inclusive screen as line array — used only for modal/button
    *  content extraction so a tall prompt's off-screen anchors stay matchable.
    *  Falls back to the viewport snapshot if scrollback read is unavailable. */
@@ -46098,6 +46107,8 @@ function readTailJsonlLines(filePath, maxBytes) {
 
 // src/providers/spec/cli-adapter.ts
 var fs20 = __toESM(require("fs"));
+var import_node_crypto4 = require("crypto");
+init_provider_cli_shared();
 init_logger();
 function stripAnsi3(text) {
   return String(text || "").replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, "").replace(/\x1B[P^_X][\s\S]*?(?:\x07|\x1B\\)/g, "").replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
@@ -46276,6 +46287,105 @@ var SpecCliAdapter = class _SpecCliAdapter {
   isReady() {
     return this.spawned && !this.exited;
   }
+  // Process liveness for the MESH-STALL-WATCH watchdog (checkMeshWorkerStall).
+  // The spec path drives the child through the transport/driver rather than a
+  // directly-held ptyProcess handle, so liveness is tracked by the spawned/exited
+  // lifecycle flags — the same pair isReady() uses. A spawned, not-yet-exited
+  // session is alive. ProviderCliAdapter exposes the equivalent via `ptyProcess !== null`.
+  isAlive() {
+    return this.spawned && !this.exited;
+  }
+  // MESH-READ-TERMINAL / MESH-SEND-KEYS byte caps — same envelope as
+  // ProviderCliAdapter (32KiB default view, 64KiB absolute hard cap). Bytes,
+  // not chars: a multi-byte-glyph screen can exceed an MCP payload cap while
+  // the char count still looks safe.
+  static TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES = 32 * 1024;
+  static TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES = 64 * 1024;
+  /**
+   * MESH-READ-TERMINAL (feature 2: RAW terminal read). Least-privilege read
+   * of the CURRENT rendered viewport for mesh_read_terminal on the spec path
+   * (claude-cli / antigravity / codex-cli — the native-source providers that
+   * route through SpecCliAdapter). Mirrors ProviderCliAdapter.getTerminalScreenSnapshot:
+   *  - returns ONLY the driver's current viewport snapshot, the cursor
+   *    position and the terminal geometry — NO scrollback, NO parser/FSM
+   *    state, NO debug buffers;
+   *  - the payload is byte-bounded (UTF-8) with bottom-tail preservation so a
+   *    screen of multi-byte glyphs can never exceed the MCP payload cap;
+   *  - `hash` is over the FULL untruncated viewport so a caller can detect a
+   *    screen change across polls even when the returned text was truncated.
+   *
+   * SECURITY: the raw viewport can carry tokens / command args / env / user
+   * data. Callers MUST gate this on mesh ownership and MUST NOT log the text.
+   */
+  getTerminalScreenSnapshot(maxBytes = _SpecCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES) {
+    const cap = Math.min(
+      _SpecCliAdapter.TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES,
+      Math.max(1024, Math.floor(maxBytes) || _SpecCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES)
+    );
+    let rawViewport = "";
+    try {
+      rawViewport = this.driver.snapshot() || "";
+    } catch {
+      rawViewport = "";
+    }
+    let cursor = { row: 0, col: 0 };
+    try {
+      cursor = this.driver.getCursorPosition();
+    } catch {
+    }
+    let size = { cols: 0, rows: 0 };
+    try {
+      size = this.driver.getScreenSize?.() ?? size;
+    } catch {
+    }
+    const truncation = truncateToByteTailByLine(rawViewport, cap);
+    const hash = (0, import_node_crypto4.createHash)("sha256").update(rawViewport, "utf8").digest("hex").slice(0, 16);
+    return {
+      text: truncation.text,
+      cursor: { col: cursor.col, row: cursor.row },
+      cols: size.cols,
+      rows: size.rows,
+      truncated: truncation.truncated,
+      originalBytes: truncation.originalBytes,
+      returnedBytes: truncation.returnedBytes,
+      hash
+    };
+  }
+  /**
+   * MESH-SEND-KEYS (feature 3: key injection). Inject a STRUCTURED key
+   * sequence into the spec-driven PTY for mesh_send_keys. Mirrors
+   * ProviderCliAdapter.injectKeys' modal fail-closed guard, then writes the
+   * whole encoded sequence in ONE pty_write dispatch (text+ENTER is a single
+   * contiguous string, so a submit key can never be separated from the text
+   * it submits).
+   *
+   * The spec path drives the child through the FsmDriver, not a directly-held
+   * ptyProcess — there is no adapter-level echo-gate/submit-retry FIFO to race
+   * against here (the driver serializes its own writes), so the only guard is
+   * the modal fail-closed: a NON-destructive injection into an actionable
+   * approval modal is refused (use mesh_approve) unless explicitly overridden.
+   * A destructive ESC/CTRL_C dismisses rather than confirms, so it is allowed
+   * past this gate (the tool layer owns the destructive double-gate + audit).
+   * This method NEVER logs the literal text — only key enums / byte length.
+   */
+  async injectKeys(items, opts = {}) {
+    if (!this.spawned || this.exited) throw new Error(`${this.cliName} is not running`);
+    const encoded = encodeMeshSendKeys(items);
+    const modalActive = this.latestState?.status === "approval";
+    if (modalActive && !encoded.hasDestructive && !opts.allowModalOverride) {
+      LOG.warn("SpecAdapter", `[${this.cliType}] send_keys refused (actionable_modal): keys=${encoded.keys.join(",")} \u2014 use mesh_approve`);
+      return { ok: false, refused: "actionable_modal", keys: encoded.keys, hasDestructive: encoded.hasDestructive };
+    }
+    this.driver.dispatch({ kind: "pty_write", data: encoded.sequence });
+    LOG.info("SpecAdapter", `[${this.cliType}] send_keys injected keys=${encoded.keys.join(",") || "(text-only)"} bytes=${Buffer.byteLength(encoded.sequence, "utf8")} destructive=${encoded.hasDestructive}`);
+    return {
+      ok: true,
+      keys: encoded.keys,
+      hasDestructive: encoded.hasDestructive,
+      submits: encoded.submits,
+      bytes: Buffer.byteLength(encoded.sequence, "utf8")
+    };
+  }
   setOnStatusChange(cb) {
     this.statusCallback = cb;
   }
@@ -48543,6 +48653,25 @@ var CliProviderInstance = class _CliProviderInstance {
     }
     return "";
   }
+  /**
+   * NOTIF Defect-B: the final assistant summary this instance ALREADY parsed and
+   * cached for the current turn (lastCompletionSummary), if any. The evidence
+   * probe (completionFinalAssistantEvidence) is a POINT-SAMPLE: on a native-source
+   * provider (antigravity) the parsed screen and the native transcript can both
+   * momentarily yield no in-turn final assistant at the exact instant the
+   * completion gate fires — source='unavailable', missingEvidence=true — even
+   * though a prior poll already read the real answer off native-history and cached
+   * it here (the same value mesh_read_chat.summary shows). Consulting the cache at
+   * emit time lets that already-secured summary count as evidence, so the completion
+   * notification carries the answer instead of completion_diagnostic=missing_final_assistant
+   * with an empty summary. Returns '' when the cache is empty or was reset by the
+   * next turn (see lastCompletionSummary = null on onTurnStarted).
+   */
+  cachedCompletionSummaryContent() {
+    const cached3 = this.lastCompletionSummary;
+    const content = typeof cached3?.content === "string" ? cached3.content.trim() : "";
+    return content;
+  }
   completionFinalAssistantEvidence(parsedMessages, turnStartedAt) {
     const turnClosed = !this.hasAdapterPendingResponse();
     if (this.completionHasFinalAssistantMessage(parsedMessages, turnStartedAt)) {
@@ -48606,12 +48735,19 @@ var CliProviderInstance = class _CliProviderInstance {
     const lastVisibleRole = typeof lastVisible?.role === "string" ? lastVisible.role.trim().toLowerCase() : null;
     const lastVisibleKind = typeof lastVisible?.kind === "string" ? lastVisible.kind : null;
     const lastVisibleContentLength = lastVisible ? flattenContent(lastVisible.content).trim().length : 0;
+    const cachedSummary = evidence.present ? "" : this.cachedCompletionSummaryContent();
+    const creditedFromCache = !evidence.present && cachedSummary.length > 0;
+    const finalAssistantPresent = evidence.present || creditedFromCache;
+    const finalAssistantEvidenceSource = evidence.present ? evidence.source : creditedFromCache ? "cached-summary" : evidence.source;
+    const clearMissingBlock = creditedFromCache && args.blockReason === "missing_final_assistant";
+    const effectiveBlockReason = clearMissingBlock ? void 0 : args.blockReason;
     return {
       providerType: this.type,
       sessionId: this.instanceId,
       providerSessionId: this.providerSessionId || null,
       workspace: this.workingDir,
-      blockReason: args.blockReason,
+      ...effectiveBlockReason ? { blockReason: effectiveBlockReason } : {},
+      ...clearMissingBlock ? { originalBlockReason: args.blockReason } : {},
       emittedAfterFinalizationTimeout: args.emittedAfterFinalizationTimeout,
       waitedMs: args.waitedMs,
       maxWaitMs: COMPLETED_FINALIZATION_MAX_WAIT_MS,
@@ -48619,8 +48755,9 @@ var CliProviderInstance = class _CliProviderInstance {
       latestVisibleStatus: args.latestVisibleStatus,
       parsedStatus: typeof parsed?.status === "string" ? parsed.status : parseError ? "parse_error" : "unknown",
       parseError: parseError || void 0,
-      finalAssistantPresent: evidence.present,
-      finalAssistantEvidenceSource: evidence.source,
+      finalAssistantPresent,
+      finalAssistantFromCachedSummary: !evidence.present && cachedSummary.length > 0,
+      finalAssistantEvidenceSource,
       visibleMessageCount: visibleMessages.length,
       lastVisibleRole,
       lastVisibleKind,
@@ -48814,6 +48951,7 @@ var CliProviderInstance = class _CliProviderInstance {
    */
   getTerminalScreenSnapshot(maxBytes) {
     if (!this.isMeshWorkerSession()) return null;
+    if (typeof this.adapter.getTerminalScreenSnapshot !== "function") return null;
     return this.adapter.getTerminalScreenSnapshot(maxBytes);
   }
   /**
@@ -48832,6 +48970,9 @@ var CliProviderInstance = class _CliProviderInstance {
     if (!this.isMeshWorkerSession()) {
       return { ok: false, refused: "not_mesh_worker", keys: [], hasDestructive: false };
     }
+    if (typeof this.adapter.injectKeys !== "function") {
+      return { ok: false, refused: "unsupported", keys: [], hasDestructive: false };
+    }
     return this.adapter.injectKeys(items, opts);
   }
   /**
@@ -48864,7 +49005,7 @@ var CliProviderInstance = class _CliProviderInstance {
       this.meshStallEmittedForAnchor = false;
       return;
     }
-    if (!this.adapter.isAlive()) {
+    if (typeof this.adapter.isAlive === "function" && !this.adapter.isAlive()) {
       this.meshStallAnchorAt = -1;
       this.meshStallEmittedForAnchor = false;
       return;
@@ -49221,7 +49362,13 @@ var CliProviderInstance = class _CliProviderInstance {
         // delegated session's inbox preview blank — or, for a LOCAL worktree session,
         // stuck on the dispatched user task. If the parser DID surface assistant text,
         // prefer it; only fall back to '' when no assistant summary can be derived.
-        finalSummary: blockReason.startsWith("parsed_status:") ? this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt) ?? "" : this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt),
+        // NOTIF Defect-B: completionFinalSummary is a point-sample of native-history/
+        // screen at THIS instant; on a native-source provider (antigravity) it can be
+        // empty at the forced-emit instant even though a prior poll already cached the
+        // real answer (lastCompletionSummary). Fall back to the cache so the notification
+        // carries the summary that mesh_read_chat.summary already shows — consistent with
+        // completionDiagnostic.finalAssistantPresent being credited from the same cache.
+        finalSummary: this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt) || this.cachedCompletionSummaryContent() || (blockReason.startsWith("parsed_status:") ? "" : void 0),
         completionDiagnostic
       });
       this.completedDebouncePending = null;
@@ -60917,6 +61064,150 @@ ${e?.stderr || ""}`
     };
   }
 }
+async function classifyPatchEquivalenceFailure(repoRoot, baseHead, branchHead, summary, options = {}) {
+  const targetBaseRef = options.targetBaseRef || baseHead;
+  const autoPublish = options.autoPublishSubmoduleMainCommits;
+  const evidence = {
+    baseHead,
+    branchHead,
+    mergeBase: summary.mergeBase,
+    expectedPatchId: summary.expectedPatchId,
+    actualPatchId: summary.actualPatchId,
+    patchIdEqual: !!summary.expectedPatchId && summary.expectedPatchId === summary.actualPatchId,
+    ...autoPublish !== void 0 ? { autoPublishSubmoduleMainCommits: autoPublish } : {}
+  };
+  try {
+    const git = (args) => (0, import_node_child_process6.execFileSync)(GIT2, args, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+      windowsHide: true
+    });
+    const gitOk = (args) => {
+      try {
+        git(args);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    let ahead = 0;
+    let behind = 0;
+    try {
+      const out = git(["rev-list", "--left-right", "--count", `${targetBaseRef}...${branchHead}`]).trim();
+      const [left, right] = out.split(/\s+/).map((n) => Number.parseInt(n, 10));
+      behind = Number.isFinite(left) ? left : 0;
+      ahead = Number.isFinite(right) ? right : 0;
+    } catch {
+    }
+    evidence.ahead = ahead;
+    evidence.behind = behind;
+    const baseIsAncestor = gitOk(["merge-base", "--is-ancestor", targetBaseRef, branchHead]);
+    evidence.baseDiverged = !baseIsAncestor;
+    let diffStat = "";
+    try {
+      if (summary.mergedTree) {
+        diffStat = git(["diff", "--stat", baseHead, summary.mergedTree]).trim().split("\n").filter(Boolean).slice(-1)[0] || "";
+      } else {
+        diffStat = git(["diff", "--stat", baseHead, branchHead]).trim().split("\n").filter(Boolean).slice(-1)[0] || "";
+      }
+    } catch {
+    }
+    if (diffStat) evidence.diffStat = diffStat;
+    const submoduleGitlinks = [];
+    try {
+      const nameStatus = git(["diff", "--name-only", "--diff-filter=d", baseHead, branchHead]).trim();
+      const changedPaths = nameStatus ? nameStatus.split("\n").map((p) => p.trim()).filter(Boolean) : [];
+      for (const p of changedPaths) {
+        let baseCommit;
+        let branchCommit;
+        try {
+          const baseLs = git(["ls-tree", baseHead, "--", p]).trim();
+          const branchLs = git(["ls-tree", branchHead, "--", p]).trim();
+          const isGitlink = /(^|\s)160000\s/.test(baseLs) || /(^|\s)160000\s/.test(branchLs);
+          if (!isGitlink) continue;
+          baseCommit = baseLs.split(/\s+/)[2];
+          branchCommit = branchLs.split(/\s+/)[2];
+        } catch {
+          continue;
+        }
+        const submoduleRepo = (0, import_path14.join)(repoRoot, p);
+        let fastForward;
+        let reachableFromOriginMain;
+        if (branchCommit) {
+          if (baseCommit) {
+            fastForward = execGitOk(submoduleRepo, ["merge-base", "--is-ancestor", baseCommit, branchCommit]);
+          }
+          reachableFromOriginMain = execGitOk(submoduleRepo, ["merge-base", "--is-ancestor", branchCommit, "refs/remotes/origin/main"]);
+        }
+        submoduleGitlinks.push({ path: p, baseCommit, branchCommit, fastForward, reachableFromOriginMain });
+      }
+    } catch {
+    }
+    if (submoduleGitlinks.length) evidence.submoduleGitlinks = submoduleGitlinks;
+    const gitlinkFf = summary.gitlinkTrivialFastForward;
+    const noResidualDiff = !evidence.diffStat && (!summary.actualPatchId || summary.actualPatchId === "");
+    if (ahead === 0 && behind === 0 && noResidualDiff) {
+      return {
+        detailedReason: "already_converged",
+        detailedReasonDescription: "Branch is already identical to the target base (ahead 0, behind 0, no residual diff); the merge would be a no-op.",
+        recommendedAction: "Treat as already converged \u2014 no merge needed. Verify with `git range-diff` / patch-id, then mark the branch merged (or clean up the worktree).",
+        evidence
+      };
+    }
+    const unreachable = submoduleGitlinks.filter((g) => g.reachableFromOriginMain === false);
+    if (unreachable.length > 0) {
+      const paths = unreachable.map((g) => g.path).join(", ");
+      return {
+        detailedReason: "submodule_unreachable",
+        detailedReasonDescription: `Submodule gitlink commit(s) not reachable from submodule origin/main (publish needed): ${paths}.`,
+        recommendedAction: `Publish the submodule commit(s) to submodule origin/main, then retry mesh_refine_node (policy allowAutoPublishSubmoduleMainCommits=${autoPublish === void 0 ? "unknown" : autoPublish}).`,
+        evidence
+      };
+    }
+    const changedGitlinks = submoduleGitlinks.length > 0;
+    const allGitlinksFf = changedGitlinks && submoduleGitlinks.every((g) => g.fastForward === true);
+    const gateSawUnresolvedGitlinkFf = gitlinkFf?.resolved === false && Array.isArray(gitlinkFf.gitlinks) && gitlinkFf.gitlinks.some((g) => g.fastForward);
+    if (baseIsAncestor && (evidence.patchIdEqual || allGitlinksFf || gateSawUnresolvedGitlinkFf)) {
+      return {
+        detailedReason: "trivial_ff_misjudgment",
+        detailedReasonDescription: "HEAD descends the target base and the patch content matches; the block is a submodule gitlink trivial fast-forward that merge-tree refused, not a real divergence.",
+        recommendedAction: "Converge via the strict fast-forward-only bypass (verify HEAD descends origin/main and patch-id equality, then merge --ff-only) instead of the refine gate.",
+        evidence
+      };
+    }
+    if (!baseIsAncestor) {
+      return {
+        detailedReason: "base_divergence",
+        detailedReasonDescription: `Worktree base has diverged from ${targetBaseRef} (HEAD is not a descendant; ahead ${ahead}, behind ${behind}).`,
+        recommendedAction: `Rebase the branch onto ${targetBaseRef}, then retry mesh_refine_node.`,
+        evidence
+      };
+    }
+    return {
+      detailedReason: "actual_patch_diff",
+      detailedReasonDescription: "The merge introduces content not equivalent to the branch's cumulative patch (expected tree vs actual merge diff differ).",
+      recommendedAction: "Manual review required \u2014 inspect the residual diff; the branch content is not patch-equivalent to a clean merge onto the base.",
+      evidence
+    };
+  } catch (e) {
+    evidence.classifierError = e?.message || String(e);
+    return {
+      detailedReason: "unclassified",
+      detailedReasonDescription: "Patch-equivalence sub-cause could not be classified (git inspection failed); see classifierError.",
+      recommendedAction: "Inspect the refineStages and patchEquivalence summary manually to determine the cause.",
+      evidence
+    };
+  }
+}
+function execGitOk(cwd, args) {
+  try {
+    (0, import_node_child_process6.execFileSync)(GIT2, args, { cwd, encoding: "utf8", maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES, windowsHide: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function checkWorktreeChangesPatchEquivalentInRef(repoRoot, ref, worktreeHead) {
   const startedAt = Date.now();
   try {
@@ -62236,9 +62527,23 @@ async function refineSyncBaseStage(self, ctx) {
         error: submoduleHintPatchEquivalence.error,
         actionableHint: submoduleHintPatchEquivalence.actionableHint
       });
+      const classification = await classifyPatchEquivalenceFailure(
+        repoRoot,
+        baseHead,
+        ctx.branchHead,
+        submoduleHintPatchEquivalence,
+        {
+          targetBaseRef: baseHead,
+          autoPublishSubmoduleMainCommits: resolveRefineryAutoPublishSubmoduleMainCommits(ctx.mesh, node.workspace).enabled
+        }
+      );
       return { kind: "terminal", result: {
         success: false,
         code: "patch_equivalence_failed",
+        detailedReason: classification.detailedReason,
+        detailedReasonDescription: classification.detailedReasonDescription,
+        recommendedAction: classification.recommendedAction,
+        evidence: classification.evidence,
         convergenceStatus: "blocked_review",
         error: "Refinery patch-equivalence preflight failed (submodule gitlink conflict); merge/refine was not attempted.",
         branch,
@@ -62378,7 +62683,7 @@ ${tail}` : ""
   return { kind: "continue", ctx };
 }
 async function refinePatchEquivalenceStage(self, ctx) {
-  const { meshId, nodeId, args, repoRoot, baseHead, branch, baseBranch, validationSummary, refineStages } = ctx;
+  const { meshId, nodeId, args, repoRoot, baseHead, branch, baseBranch, mesh, node, validationSummary, refineStages } = ctx;
   const branchHead = ctx.branchHead;
   const patchEquivalenceStarted = Date.now();
   const patchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
@@ -62392,9 +62697,27 @@ async function refinePatchEquivalenceStage(self, ctx) {
   if (!patchEquivalence.equivalent) {
     const alreadyMergedViaOtherPath = !patchEquivalence.actualPatchId && !!patchEquivalence.expectedPatchId;
     if (!alreadyMergedViaOtherPath) {
+      const classification = await classifyPatchEquivalenceFailure(
+        repoRoot,
+        baseHead,
+        branchHead,
+        patchEquivalence,
+        {
+          targetBaseRef: baseHead,
+          autoPublishSubmoduleMainCommits: resolveRefineryAutoPublishSubmoduleMainCommits(mesh, node.workspace).enabled
+        }
+      );
+      recordMeshRefineStage(refineStages, "patch_equivalence_classification", "failed", patchEquivalenceStarted, {
+        detailedReason: classification.detailedReason,
+        recommendedAction: classification.recommendedAction
+      });
       return { kind: "terminal", result: {
         success: false,
         code: "patch_equivalence_failed",
+        detailedReason: classification.detailedReason,
+        detailedReasonDescription: classification.detailedReasonDescription,
+        recommendedAction: classification.recommendedAction,
+        evidence: classification.evidence,
         convergenceStatus: "blocked_review",
         error: "Refinery patch-equivalence preflight failed; merge/refine was not attempted.",
         branch,
@@ -63501,6 +63824,10 @@ async function finishMeshRefineJob(self, handle, args) {
     };
     if (typeof result.error === "string") ctx.error = result.error;
     if (typeof result.blockedReason === "string") ctx.blockedReason = result.blockedReason;
+    if (typeof result.detailedReason === "string") ctx.detailedReason = result.detailedReason;
+    if (typeof result.detailedReasonDescription === "string") ctx.detailedReasonDescription = result.detailedReasonDescription;
+    if (typeof result.recommendedAction === "string") ctx.recommendedAction = result.recommendedAction;
+    if (result.evidence && typeof result.evidence === "object") ctx.evidence = result.evidence;
     if (stage === "patch_equivalence" && result.patchEquivalence) {
       const pe = result.patchEquivalence;
       ctx.details = {
@@ -63508,7 +63835,10 @@ async function finishMeshRefineJob(self, handle, args) {
         actualPatchId: pe.actualPatchId,
         status: pe.status,
         actionableHint: pe.actionableHint,
-        error: pe.error
+        error: pe.error,
+        ...typeof result.detailedReason === "string" ? { detailedReason: result.detailedReason } : {},
+        ...typeof result.recommendedAction === "string" ? { recommendedAction: result.recommendedAction } : {},
+        ...result.evidence && typeof result.evidence === "object" ? { evidence: result.evidence } : {}
       };
     }
     if (stage === "submodule_reachability" && Array.isArray(result.unreachableSubmoduleCommits)) {