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

package/dist/mesh/mesh-refine-gates.d.ts

@@ -327,6 +327,92 @@ export declare function resolveRefineryAutoPublishSubmoduleMainCommits(mesh: any
     source?: string;
 };
 export declare function runMeshRefinePatchEquivalenceGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefinePatchEquivalenceSummary>;
+/**
+ * Machine-readable sub-classification of a `patch_equivalence_failed` (and the
+ * related submodule-gitlink preflight blocks). The opaque top-level
+ * `patch_equivalence_failed` code is preserved for backward compatibility; this
+ * detailed reason is added ALONGSIDE it so coordinators no longer have to guess
+ * WHY the preflight blocked (the 2026-07-17 hidden-spinner convergence incident:
+ * the real cause was a diverged base + an unreachable submodule gitlink artifact,
+ * not a real patch conflict, but Refinery only returned the opaque code and the
+ * coordinator mis-attributed it to a stale daemon version).
+ */
+export type MeshRefinePatchEquivalenceDetailedReasonCode = 
+/** Worktree base diverged from target base (HEAD is not a descendant of origin/main). */
+'base_divergence'
+/** Submodule gitlink commit is not reachable from the submodule's remote main branch (publish needed). */
+ | 'submodule_unreachable'
+/** Genuine non-equivalent content: expected tree vs actual merge diff differ. */
+ | 'actual_patch_diff'
+/** Submodule gitlink trivial fast-forward mis-judged as non-equivalent (HEAD descends origin/main, patch-id equal, blocked only by the gitlink). */
+ | 'trivial_ff_misjudgment'
+/** Already identical to origin/main (ahead 0 / behind 0, no diff) — should be treated as success/no-op. */
+ | 'already_converged'
+/** Fallback when the classifier itself could not run (git error); keep the opaque code, note the reason. */
+ | 'unclassified';
+export type MeshRefinePatchEquivalenceFailureClassification = {
+    detailedReason: MeshRefinePatchEquivalenceDetailedReasonCode;
+    /** Human-readable one-line description of the sub-cause. */
+    detailedReasonDescription: string;
+    /** Suggested next action for the coordinator/owner (free-form, actionable). */
+    recommendedAction: string;
+    /** Structured supporting evidence: SHAs, ahead/behind, submodule reachability, patch-id comparison, diff stat. */
+    evidence: {
+        baseHead?: string;
+        branchHead?: string;
+        mergeBase?: string;
+        /** How many commits base (origin/main) is ahead of the branch's merge-base (branch is behind). */
+        behind?: number;
+        /** How many commits the branch is ahead of the merge-base. */
+        ahead?: number;
+        /** True when HEAD is NOT a descendant of the target base (diverged). */
+        baseDiverged?: boolean;
+        expectedPatchId?: string;
+        actualPatchId?: string;
+        patchIdEqual?: boolean;
+        /** Compact one-line diff stat summary of the residual/actual merge diff (best-effort). */
+        diffStat?: string;
+        /** Per-submodule gitlink reachability against submodule origin/main (best-effort). */
+        submoduleGitlinks?: Array<{
+            path: string;
+            baseCommit?: string;
+            branchCommit?: string;
+            /** True when branchCommit descends baseCommit (a strict fast-forward advance). */
+            fastForward?: boolean;
+            /** True when branchCommit is reachable from the submodule's local origin/main. */
+            reachableFromOriginMain?: boolean;
+        }>;
+        /** Effective auto-publish-submodule-main-commits policy value at classification time. */
+        autoPublishSubmoduleMainCommits?: boolean;
+        /** Set when the classifier itself errored (detailedReason === 'unclassified'). */
+        classifierError?: string;
+    };
+};
+/**
+ * Classify WHY a patch-equivalence preflight blocked, turning the opaque
+ * `patch_equivalence_failed` code into a machine-readable {@link
+ * MeshRefinePatchEquivalenceDetailedReasonCode} plus a recommended action and
+ * structured evidence. Read-only: runs only `git` inspection commands (rev-list,
+ * merge-base, diff --stat, submodule reachability probes) against the already-set
+ * worktree — it never mutates the repo.
+ *
+ * Priority of classification (first match wins):
+ *   1. already_converged     — ahead 0 & behind 0 & no residual diff
+ *   2. submodule_unreachable  — a changed gitlink commit is not reachable from the
+ *                               submodule's origin/main (publish needed)
+ *   3. trivial_ff_misjudgment — HEAD descends origin/main AND (excl. gitlinks) the
+ *                               patch-ids match — blocked only by a ff gitlink
+ *   4. base_divergence        — HEAD is not a descendant of the target base
+ *   5. actual_patch_diff      — genuine content divergence (the residual case)
+ *
+ * `targetBaseRef` is the ref the branch is meant to land on (e.g. 'origin/main'
+ * or the pinned baseHead SHA). `autoPublishSubmoduleMainCommits` is threaded in so
+ * the submodule_unreachable recommendation can name the current policy value.
+ */
+export declare function classifyPatchEquivalenceFailure(repoRoot: string, baseHead: string, branchHead: string, summary: MeshRefinePatchEquivalenceSummary, options?: {
+    targetBaseRef?: string;
+    autoPublishSubmoduleMainCommits?: boolean;
+}): Promise<MeshRefinePatchEquivalenceFailureClassification>;
 export type MeshWorktreePatchContainmentSummary = {
     /** True only when merging worktreeHead into ref introduces no new patch. */
     contained: boolean;

package/dist/providers/cli-provider-instance.d.ts

@@ -423,6 +423,21 @@ export declare class CliProviderInstance implements ProviderInstance {
      * the dashboard tail-repair cache — a display value, not a completion decision.
      */
     private lastVisibleAssistantSummary;
+    /**
+     * 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).
+     */
+    private cachedCompletionSummaryContent;
     private completionFinalAssistantEvidence;
     private completionFinalSummary;
     private buildCompletedFinalizationDiagnostic;
@@ -482,7 +497,7 @@ export declare class CliProviderInstance implements ProviderInstance {
         bytes: number;
     } | {
         ok: false;
-        refused: 'submit_race' | 'actionable_modal' | 'not_mesh_worker';
+        refused: 'submit_race' | 'actionable_modal' | 'not_mesh_worker' | 'unsupported';
         keys: MeshSendKeyName[];
         hasDestructive: boolean;
     }>;

package/dist/providers/spec/adapter.d.ts

@@ -79,6 +79,13 @@ export declare class TerminalAdapter {
         row: number;
         col: number;
     };
+    /** 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(): {
+        cols: number;
+        rows: number;
+    };
     send_keys(text: string): void;
     /** Forward runtime metadata (meshNodeId, workspaceLabel, lifecycle, …) to
      *  the underlying transport so it reaches the session registry. The spec

package/dist/providers/spec/cli-adapter.d.ts

@@ -1,5 +1,6 @@
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import { type MeshSendKeyItem, type MeshSendKeyName } from '../../cli-adapters/provider-cli-shared.js';
 import { type InteractivePromptResponse } from '../types/interactive-prompt.js';
 export declare class SpecCliAdapter implements CliAdapter {
     readonly cliType: string;
@@ -74,6 +75,69 @@ export declare class SpecCliAdapter implements CliAdapter {
     cancel(): void;
     isProcessing(): boolean;
     isReady(): boolean;
+    isAlive(): boolean;
+    private static readonly TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES;
+    private static readonly TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES;
+    /**
+     * 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?: number): {
+        text: string;
+        cursor: {
+            col: number;
+            row: number;
+        };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    };
+    /**
+     * 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.
+     */
+    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(cb: () => void): void;
     setOnPtyData(cb: (data: string) => void): void;
     writeRaw(data: string): void;

package/dist/providers/spec/fsm-driver.d.ts

@@ -126,6 +126,13 @@ export interface ISpecDriver {
         col: number;
     };
     getScreen(): string;
+    /** Current terminal geometry (columns × rows). Optional so a non-Fsm
+     *  ISpecDriver implementation (test doubles) need not provide it; the
+     *  mesh_read_terminal path falls back to a 0×0 geometry when absent. */
+    getScreenSize?(): {
+        cols: number;
+        rows: number;
+    };
     getSpecPath(): string;
     shutdown(): void;
     getStateHistory(): ReadonlyArray<DriverHistoryEntry>;
@@ -251,6 +258,10 @@ export declare class FsmDriver implements ISpecDriver {
         col: number;
     };
     getScreen(): string;
+    getScreenSize(): {
+        cols: number;
+        rows: number;
+    };
     /** 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.553",
+  "version": "0.9.82-rc.554",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.553",
-    "@adhdev/session-host-core": "0.9.82-rc.553",
+    "@adhdev/mesh-shared": "0.9.82-rc.554",
+    "@adhdev/session-host-core": "0.9.82-rc.554",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/cli-adapter-types.ts

@@ -6,6 +6,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;
@@ -118,6 +119,34 @@ export interface CliAdapter {
     cancel(): void;
     isProcessing(): boolean;
     isReady(): boolean;
+    // Liveness of the underlying process/PTY. Optional because not every adapter
+    // implementation exposes it (the spec-driven path historically did not); the
+    // MESH-STALL-WATCH watchdog must call it defensively (typeof guard) so a
+    // missing implementation never throws in the 5s tick.
+    isAlive?(): boolean;
+    // MESH-READ-TERMINAL (feature 2) / MESH-SEND-KEYS (feature 3). Optional
+    // because not every adapter implements the raw-terminal read / structured
+    // key-injection surface; callers (cli-provider-instance) MUST typeof-guard
+    // and return a clean unsupported result rather than throwing when absent.
+    // Both ProviderCliAdapter (PTY path) and SpecCliAdapter (native-source spec
+    // path — claude-cli / antigravity / codex-cli) implement them.
+    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/src/commands/router-refine.ts

@@ -35,6 +35,7 @@ import {
     RefineContext,
     RefineExecFileAsync,
     RefineStageOutcome,
+    classifyPatchEquivalenceFailure,
     recordMeshRefineStage,
     resolveRefineryAutoPublishSubmoduleMainCommits,
     runMeshRefineEffectiveDiffGate,
@@ -616,9 +617,20 @@ export async function refineSyncBaseStage(self: DaemonCommandRouter, ctx: Refine
                         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,
@@ -801,7 +813,7 @@ export async function refineValidationStage(self: DaemonCommandRouter, ctx: Refi
 export async function refinePatchEquivalenceStage(self: DaemonCommandRouter, ctx: RefineContext): Promise<RefineStageOutcome> {
             // DS2: node/execFileAsync are no longer needed here — the rebase moved to
             // sync_base — and branchHead/patchEquivalence are no longer mutated in-stage.
-            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);
@@ -826,9 +838,24 @@ export async function refinePatchEquivalenceStage(self: DaemonCommandRouter, ctx
                 // branch itself has no changes (degenerate), which is NOT already-merged.
                 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,
@@ -2278,6 +2305,15 @@ export async function finishMeshRefineJob(self: DaemonCommandRouter, handle: Mes
             };
             if (typeof result.error === 'string') ctx.error = result.error;
             if (typeof result.blockedReason === 'string') ctx.blockedReason = result.blockedReason;
+            // Detailed patch-equivalence sub-cause classification (base_divergence,
+            // submodule_unreachable, actual_patch_diff, trivial_ff_misjudgment,
+            // already_converged, unclassified) + recommended action + evidence.
+            // Promoted onto blockerContext so coordinators reading task_failed ledger
+            // entries see the cause without parsing the free-form error string.
+            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;
             // Patch equivalence details
             if (stage === 'patch_equivalence' && result.patchEquivalence) {
                 const pe = result.patchEquivalence as Record<string, unknown>;
@@ -2287,6 +2323,9 @@ export async function finishMeshRefineJob(self: DaemonCommandRouter, handle: Mes
                     status: pe.status,
                     actionableHint: pe.actionableHint,
                     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 } : {}),
                 };
             }
             // Submodule reachability details

package/src/mesh/mesh-refine-gates.ts

@@ -556,6 +556,262 @@ export async function runMeshRefinePatchEquivalenceGate(
     }
 }
 
+/**
+ * Machine-readable sub-classification of a `patch_equivalence_failed` (and the
+ * related submodule-gitlink preflight blocks). The opaque top-level
+ * `patch_equivalence_failed` code is preserved for backward compatibility; this
+ * detailed reason is added ALONGSIDE it so coordinators no longer have to guess
+ * WHY the preflight blocked (the 2026-07-17 hidden-spinner convergence incident:
+ * the real cause was a diverged base + an unreachable submodule gitlink artifact,
+ * not a real patch conflict, but Refinery only returned the opaque code and the
+ * coordinator mis-attributed it to a stale daemon version).
+ */
+export type MeshRefinePatchEquivalenceDetailedReasonCode =
+    /** Worktree base diverged from target base (HEAD is not a descendant of origin/main). */
+    | 'base_divergence'
+    /** Submodule gitlink commit is not reachable from the submodule's remote main branch (publish needed). */
+    | 'submodule_unreachable'
+    /** Genuine non-equivalent content: expected tree vs actual merge diff differ. */
+    | 'actual_patch_diff'
+    /** Submodule gitlink trivial fast-forward mis-judged as non-equivalent (HEAD descends origin/main, patch-id equal, blocked only by the gitlink). */
+    | 'trivial_ff_misjudgment'
+    /** Already identical to origin/main (ahead 0 / behind 0, no diff) — should be treated as success/no-op. */
+    | 'already_converged'
+    /** Fallback when the classifier itself could not run (git error); keep the opaque code, note the reason. */
+    | 'unclassified';
+
+export type MeshRefinePatchEquivalenceFailureClassification = {
+    detailedReason: MeshRefinePatchEquivalenceDetailedReasonCode;
+    /** Human-readable one-line description of the sub-cause. */
+    detailedReasonDescription: string;
+    /** Suggested next action for the coordinator/owner (free-form, actionable). */
+    recommendedAction: string;
+    /** Structured supporting evidence: SHAs, ahead/behind, submodule reachability, patch-id comparison, diff stat. */
+    evidence: {
+        baseHead?: string;
+        branchHead?: string;
+        mergeBase?: string;
+        /** How many commits base (origin/main) is ahead of the branch's merge-base (branch is behind). */
+        behind?: number;
+        /** How many commits the branch is ahead of the merge-base. */
+        ahead?: number;
+        /** True when HEAD is NOT a descendant of the target base (diverged). */
+        baseDiverged?: boolean;
+        expectedPatchId?: string;
+        actualPatchId?: string;
+        patchIdEqual?: boolean;
+        /** Compact one-line diff stat summary of the residual/actual merge diff (best-effort). */
+        diffStat?: string;
+        /** Per-submodule gitlink reachability against submodule origin/main (best-effort). */
+        submoduleGitlinks?: Array<{
+            path: string;
+            baseCommit?: string;
+            branchCommit?: string;
+            /** True when branchCommit descends baseCommit (a strict fast-forward advance). */
+            fastForward?: boolean;
+            /** True when branchCommit is reachable from the submodule's local origin/main. */
+            reachableFromOriginMain?: boolean;
+        }>;
+        /** Effective auto-publish-submodule-main-commits policy value at classification time. */
+        autoPublishSubmoduleMainCommits?: boolean;
+        /** Set when the classifier itself errored (detailedReason === 'unclassified'). */
+        classifierError?: string;
+    };
+};
+
+/**
+ * Classify WHY a patch-equivalence preflight blocked, turning the opaque
+ * `patch_equivalence_failed` code into a machine-readable {@link
+ * MeshRefinePatchEquivalenceDetailedReasonCode} plus a recommended action and
+ * structured evidence. Read-only: runs only `git` inspection commands (rev-list,
+ * merge-base, diff --stat, submodule reachability probes) against the already-set
+ * worktree — it never mutates the repo.
+ *
+ * Priority of classification (first match wins):
+ *   1. already_converged     — ahead 0 & behind 0 & no residual diff
+ *   2. submodule_unreachable  — a changed gitlink commit is not reachable from the
+ *                               submodule's origin/main (publish needed)
+ *   3. trivial_ff_misjudgment — HEAD descends origin/main AND (excl. gitlinks) the
+ *                               patch-ids match — blocked only by a ff gitlink
+ *   4. base_divergence        — HEAD is not a descendant of the target base
+ *   5. actual_patch_diff      — genuine content divergence (the residual case)
+ *
+ * `targetBaseRef` is the ref the branch is meant to land on (e.g. 'origin/main'
+ * or the pinned baseHead SHA). `autoPublishSubmoduleMainCommits` is threaded in so
+ * the submodule_unreachable recommendation can name the current policy value.
+ */
+export async function classifyPatchEquivalenceFailure(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+    summary: MeshRefinePatchEquivalenceSummary,
+    options: { targetBaseRef?: string; autoPublishSubmoduleMainCommits?: boolean } = {},
+): Promise<MeshRefinePatchEquivalenceFailureClassification> {
+    const targetBaseRef = options.targetBaseRef || baseHead;
+    const autoPublish = options.autoPublishSubmoduleMainCommits;
+    const evidence: MeshRefinePatchEquivalenceFailureClassification['evidence'] = {
+        baseHead,
+        branchHead,
+        mergeBase: summary.mergeBase,
+        expectedPatchId: summary.expectedPatchId,
+        actualPatchId: summary.actualPatchId,
+        patchIdEqual: !!summary.expectedPatchId && summary.expectedPatchId === summary.actualPatchId,
+        ...(autoPublish !== undefined ? { autoPublishSubmoduleMainCommits: autoPublish } : {}),
+    };
+    try {
+        const git = (args: string[]): string => execFileSync(GIT, args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+            windowsHide: true,
+        });
+        const gitOk = (args: string[]): boolean => {
+            try { git(args); return true; } catch { return false; }
+        };
+
+        // ahead/behind of branch vs the target base ref. left = base-only (behind),
+        // right = branch-only (ahead).
+        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 { /* keep zeros */ }
+        evidence.ahead = ahead;
+        evidence.behind = behind;
+        // HEAD (branchHead) diverged from the target base = base is NOT an ancestor
+        // of the branch. behind>0 with the base ref not reachable from HEAD.
+        const baseIsAncestor = gitOk(['merge-base', '--is-ancestor', targetBaseRef, branchHead]);
+        evidence.baseDiverged = !baseIsAncestor;
+
+        // Residual/actual diff stat (best-effort): what the merge would still introduce.
+        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 { /* diff stat is best-effort */ }
+        if (diffStat) evidence.diffStat = diffStat;
+
+        // Changed gitlink reachability against each submodule's local origin/main.
+        const submoduleGitlinks: NonNullable<MeshRefinePatchEquivalenceFailureClassification['evidence']['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) {
+                // Only submodule (gitlink, mode 160000) entries.
+                let baseCommit: string | undefined;
+                let branchCommit: string | undefined;
+                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 = pathJoin(repoRoot, p);
+                let fastForward: boolean | undefined;
+                let reachableFromOriginMain: boolean | undefined;
+                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 { /* submodule inspection is best-effort */ }
+        if (submoduleGitlinks.length) evidence.submoduleGitlinks = submoduleGitlinks;
+
+        // Existing gate signal: the merge-tree trivial-ff evaluation, if the gate
+        // captured it (a genuine non-trivial submodule conflict lands here too).
+        const gitlinkFf = summary.gitlinkTrivialFastForward;
+
+        // ── Classification (first match wins) ────────────────────────────────
+        const noResidualDiff = !evidence.diffStat && (!summary.actualPatchId || summary.actualPatchId === '');
+
+        // 1. already_converged: nothing ahead, nothing behind, no residual diff.
+        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 — no merge needed. Verify with `git range-diff` / patch-id, then mark the branch merged (or clean up the worktree).',
+                evidence,
+            };
+        }
+
+        // 2. submodule_unreachable: a changed gitlink is not reachable from the
+        //    submodule's origin/main. This is the publish-needed artifact.
+        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 === undefined ? 'unknown' : autoPublish}).`,
+                evidence,
+            };
+        }
+
+        // 3. trivial_ff_misjudgment: HEAD descends the target base AND the non-gitlink
+        //    patch-ids are equal, so the ONLY thing blocking is a fast-forward gitlink
+        //    that merge-tree refused. (Either the gate flagged an unresolved gitlink
+        //    ff, or every changed gitlink is a proven ff.)
+        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,
+            };
+        }
+
+        // 4. base_divergence: HEAD is not a descendant of the target base.
+        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,
+            };
+        }
+
+        // 5. actual_patch_diff: genuine non-equivalent content.
+        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 — inspect the residual diff; the branch content is not patch-equivalent to a clean merge onto the base.',
+            evidence,
+        };
+    } catch (e: any) {
+        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,
+        };
+    }
+}
+
+/** Small helper: run a git command in `cwd` and return whether it exited 0. */
+function execGitOk(cwd: string, args: string[]): boolean {
+    try {
+        execFileSync(GIT, args, { cwd, encoding: 'utf8', maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES, windowsHide: true });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 export type MeshWorktreePatchContainmentSummary = {
     /** True only when merging worktreeHead into ref introduces no new patch. */
     contained: boolean;