@adhdev/daemon-core 1.0.18-rc.10 → 1.0.18-rc.12

package/src/mesh/mesh-event-forwarding.ts

@@ -1071,10 +1071,44 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         // C2: prefer an exact taskId match when the completion event carries one —
         // it's immune to coordinator↔worker clock skew that can hide the assigned row.
         const eventTaskId = readNonEmptyString(args.metadataEvent.taskId) || undefined;
-        const task = updateSessionTaskStatus(args.meshId, sessionId, outcome, {
-            occurredAt: occurredAtMs != null ? new Date(occurredAtMs).toISOString() : undefined,
-            taskId: eventTaskId,
-        });
+        // WEAK-QUEUE-TENTATIVE (early-completed safety net, symmetric with the direct-dispatch
+        // `tentativeIfDirect` guard below): a `completed` outcome whose evidence is WEAK — a
+        // false-idle / missing_final_assistant emit (the CANON-C decoupled-immediate path that
+        // stamps evidenceLevel=insufficient) — must NOT hard-flip a matched QUEUE row to
+        // terminal. Until this net, only DIRECT dispatches were kept tentative on weak evidence;
+        // a queue-claimed task's session flipped its row to 'completed' unconditionally, so a
+        // worker that dropped to idle ~13s in with no final assistant closed the task early even
+        // though it never produced an answer. Leaving the row 'assigned' hands it to the reconcile
+        // loop's proven net (PHASE 4 records the GENUINE completion once the transcript lands via
+        // findTerminalLedgerEvidenceForTask; PHASE 2.5 reclaims a truly-stranded row back to
+        // 'pending' for re-dispatch, bounded by MAX_STRANDED_RECLAIMS) — never a permanent wedge.
+        //
+        // CRUCIAL SCOPE: this covers only the PREMATURE decoupled-immediate emit
+        // (emittedAfterFinalizationTimeout !== true). A weak completion that already waited out the
+        // full 30s COMPLETED_FINALIZATION_MAX_WAIT_MS window (emittedAfterFinalizationTimeout=true)
+        // is a GENUINE — if answerless — terminal: the worker exhausted its finalization wait and
+        // is done, so it flips 'completed' as before (a tool-only turn that never produced an
+        // assistant bubble must still close its task). A `failed` outcome or a completion with
+        // genuine evidence flips terminal as before too.
+        const completionDiagnostic = args.metadataEvent.completionDiagnostic && typeof args.metadataEvent.completionDiagnostic === 'object'
+            ? args.metadataEvent.completionDiagnostic as Record<string, unknown>
+            : undefined;
+        const emittedAfterFinalizationTimeout = completionDiagnostic?.emittedAfterFinalizationTimeout === true;
+        const weakCompleted = outcome === 'completed'
+            && isWeakCompletionEvidence(args.metadataEvent)
+            && !emittedAfterFinalizationTimeout;
+        const task = weakCompleted
+            ? updateSessionTaskStatus(args.meshId, sessionId, 'assigned', {
+                occurredAt: occurredAtMs != null ? new Date(occurredAtMs).toISOString() : undefined,
+                taskId: eventTaskId,
+            })
+            : updateSessionTaskStatus(args.meshId, sessionId, outcome, {
+                occurredAt: occurredAtMs != null ? new Date(occurredAtMs).toISOString() : undefined,
+                taskId: eventTaskId,
+            });
+        if (weakCompleted && task) {
+            LOG.info('MeshQueue', `Weak completion (${readNonEmptyString(args.metadataEvent.evidenceLevel) || 'missing_final_assistant'}) kept queue task ${task.id} tentative (session ${sessionId}); reconcile owns the genuine terminal`);
+        }
         // Fix A (early-terminal prevention): a false-idle completion (no confirmed final
         // assistant) for a DIRECT dispatch — i.e. no work-queue row matched — must not flip the
         // dispatch row terminal. Leaving it active lets the reconcile loop (PHASE 4) re-read the
@@ -1754,6 +1788,14 @@ export function buildRelayMetadataEvent(payload: Record<string, unknown>): Recor
         retryOfJobId: readNonEmptyString(payload.retryOfJobId),
         ...(relayModalMessage ? { modalMessage: relayModalMessage } : {}),
         ...(relayModalButtons && relayModalButtons.length > 0 ? { modalButtons: relayModalButtons } : {}),
+        // agent:waiting_choice (mission f1d25e11): carry the FULL structured question
+        // payload across the machine boundary so a REMOTE worker's AskUserQuestion reaches
+        // the coordinator with every question + option intact — the coordinator renders
+        // these and answers with mesh_answer_question. The local in-process forward path
+        // preserves the whole event for free; this mirrors the fields for the remote relay.
+        ...(payload.interactivePrompt && typeof payload.interactivePrompt === 'object' && !Array.isArray(payload.interactivePrompt) ? { interactivePrompt: payload.interactivePrompt } : {}),
+        ...(readNonEmptyString(payload.promptId) ? { promptId: readNonEmptyString(payload.promptId) } : {}),
+        ...(payload.multiSelect === true ? { multiSelect: true } : {}),
         ...(payload.result && typeof payload.result === 'object' && !Array.isArray(payload.result) ? { result: payload.result } : {}),
         ...(payload.completionDiagnostic && typeof payload.completionDiagnostic === 'object' && !Array.isArray(payload.completionDiagnostic) ? { completionDiagnostic: payload.completionDiagnostic } : {}),
         ...(payload.workerResult && typeof payload.workerResult === 'object' && !Array.isArray(payload.workerResult) ? { workerResult: payload.workerResult } : {}),

package/src/mesh/mesh-events-utils.ts

@@ -330,6 +330,48 @@ export function buildMeshSystemMessage(args: {
     if (args.event === 'agent:waiting_approval') {
         return `[System] ${args.nodeLabel} is waiting for approval to proceed${metadata}. You may use mesh_read_chat and mesh_approve to handle it.`;
     }
+    if (args.event === 'agent:waiting_choice') {
+        // A multi-choice QUESTION (AskUserQuestion) — NOT an approval. It is answered with
+        // mesh_answer_question (never mesh_approve). Surface the question text + choices
+        // inline so the coordinator can decide without a mesh_read_chat round-trip, and
+        // name the correct tool + promptId (mission f1d25e11).
+        const prompt = args.metadataEvent.interactivePrompt as
+            | { promptId?: unknown; questions?: Array<Record<string, unknown>> }
+            | undefined;
+        const promptId = readNonEmptyString(args.metadataEvent.promptId)
+            || (prompt && readNonEmptyString(prompt.promptId));
+        const lines: string[] = [
+            `[System] ${args.nodeLabel} is asking a question and is waiting for your answer${metadata}.`,
+        ];
+        const questions = Array.isArray(prompt?.questions) ? prompt!.questions! : [];
+        if (questions.length > 0) {
+            for (const q of questions) {
+                const header = readNonEmptyString(q.header);
+                const question = readNonEmptyString(q.question);
+                const multiSelect = q.multiSelect === true;
+                if (question) {
+                    lines.push(`\n**${header ? `${header}: ` : ''}${question}**${multiSelect ? ' (select one or more)' : ''}`);
+                }
+                const options = Array.isArray(q.options) ? q.options : [];
+                options.forEach((opt, i) => {
+                    const record = (opt && typeof opt === 'object') ? opt as Record<string, unknown> : {};
+                    const label = readNonEmptyString(record.label);
+                    if (!label) return;
+                    const description = readNonEmptyString(record.description);
+                    lines.push(`  ${i + 1}. ${label}${description ? ` — ${description}` : ''}`);
+                });
+            }
+        } else {
+            const modalMessage = readNonEmptyString(args.metadataEvent.modalMessage);
+            if (modalMessage) lines.push(`\n${modalMessage}`);
+        }
+        lines.push(
+            `\nAnswer with mesh_answer_question(node_id, session_id${promptId ? `, promptId: "${promptId}"` : ''}, answers). ` +
+            `Do NOT use mesh_approve — that only resolves yes/no consent modals, not a question. ` +
+            `Use mesh_read_chat once if you need the full context first.`,
+        );
+        return lines.join('\n');
+    }
     if (args.event === 'agent:stopped') {
         const rc = args.recoveryContext;
         if (rc && rc.consecutiveNodeFailures > 0) {

package/src/mesh/mesh-ledger.ts

@@ -33,6 +33,11 @@ export type MeshLedgerKind =
     | 'task_failed'
     | 'task_stalled'
     | 'task_approval_needed'
+    // A worker is parked on an AskUserQuestion multi-choice prompt (waiting_choice) —
+    // distinct from task_approval_needed (a yes/no tool-consent modal). The coordinator
+    // answers a question with mesh_answer_question, never mesh_approve (mission f1d25e11).
+    // payload carries the full InteractivePrompt (promptId + questions + options).
+    | 'task_question_pending'
     | 'p2p_dispatch_failed'
     | 'session_launched'
     | 'session_auto_launch'

package/src/mesh/mesh-node-identity.ts

@@ -907,6 +907,55 @@ export function isMeshNodeHealthLaunchable(node: any): boolean {
     return health === 'online' || health === 'unknown';
 }
 
+/** Resolve the git telemetry object a node carries, in the same precedence
+ *  resolveEffectiveMeshNodeHealth uses: a fresh `node.git`, else the cached inline
+ *  status git (`node.cachedStatus.git`). Returns an empty record when neither is
+ *  present (no telemetry). */
+function resolveEffectiveNodeGit(node: any): Record<string, any> {
+    const git = readObjectRecord(node?.git);
+    if (Object.keys(git).length > 0) return git;
+    const cachedStatus = readObjectRecord(node?.cachedStatus);
+    return readObjectRecord(cachedStatus.git);
+}
+
+/**
+ * Launch FRESHNESS gate — distinct from the health gate above.
+ *
+ * `deriveMeshNodeHealthFromGit` reports a clean-tree node with `behind > 0` as
+ * 'online', so the health gate (isMeshNodeHealthLaunchable) happily lets a STALE
+ * node — one whose branch is N commits behind its upstream — win auto-launch fitness
+ * routing and run a fresh worker against out-of-date code. `behind` is deliberately
+ * NOT folded into deriveMeshNodeHealthFromGit because "behind" is not universally
+ * unhealthy (the MAGI planner and other callers share that resolver); it is only
+ * unhealthy for *spawning new work*. This gate encodes exactly that launch-time axis.
+ *
+ * Returns false (NOT fresh → skip / de-rank) only when git telemetry is PRESENT and
+ * proves staleness:
+ *   - behind count exceeds `maxBehind` (default 0 — any behind blocks), OR
+ *   - a submodule is out of sync (gitlink points off upstream — cannot be caught up
+ *     by a simple worktree ff and would launch against a mismatched submodule).
+ *
+ * When telemetry is absent it returns true (fresh), preserving the online/unknown-pass
+ * philosophy: we never block on missing data, only on data that proves the node stale.
+ */
+export function isMeshNodeFreshEnoughToLaunch(node: any, opts?: { maxBehind?: number }): boolean {
+    const git = resolveEffectiveNodeGit(node);
+    // No git telemetry at all → cannot prove stale → do not block.
+    if (Object.keys(git).length === 0) return true;
+    // Not a git repo / no branch: leave this to the health gate (it returns 'degraded'
+    // and blocks there); freshness has nothing to add.
+    if (readBooleanValue(git.isGitRepo) === false) return true;
+    const submoduleDrift = getGitSubmoduleDriftState(git);
+    if (submoduleDrift.outOfSync) return false;
+    const behind = readNumberValue(git.behind);
+    // No behind datum reported → treat as fresh (don't infer staleness from absence).
+    if (behind === undefined) return true;
+    const maxBehind = Number.isFinite(opts?.maxBehind as number) && (opts?.maxBehind as number) >= 0
+        ? Math.floor(opts!.maxBehind as number)
+        : 0;
+    return behind <= maxBehind;
+}
+
 function readMeshNodeLabel(status: Record<string, unknown>, node: any): string {
     return readStringValue(status.nodeId, normalizeMeshNodeId(node)) ?? 'unknown';
 }

package/src/mesh/mesh-queue-assignment.ts

@@ -19,7 +19,7 @@ import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalD
 import { resolveNodeCapabilitySlots } from './mesh-node-slots.js';
 import { findTerminalLedgerEvidenceForTask, hasUnterminalDirectDispatchLedgerEntry } from './mesh-events-stale.js';
 import { readNonEmptyString } from './mesh-events-utils.js';
-import { readMeshNodeDaemonId, isMeshNodeHealthLaunchable } from './mesh-node-identity.js';
+import { readMeshNodeDaemonId, isMeshNodeHealthLaunchable, isMeshNodeFreshEnoughToLaunch } from './mesh-node-identity.js';
 import { queuePendingMeshCoordinatorEvent, retractPendingDispatchBlockedEvent, drainPendingMeshCoordinatorEvents } from './mesh-events-pending.js';
 import { isWorktreeBootstrapStaleRunning, shouldDeferDispatchForBootstrap } from './worktree-bootstrap-config.js';
 import { isWithinCloneBootstrapGrace } from './mesh-clone-grace.js';
@@ -1987,6 +1987,11 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
     }
     if (!pending.length) return false;
 
+    // Launch-freshness threshold: reuse the auto-fast-forward policy's maxBehind (default
+    // 0 → any behind blocks) so the launch gate and the repair path agree on how far
+    // behind is tolerable. Resolved once per pass and shared across every candidate node.
+    const freshnessGate = { maxBehind: resolveAutoFastForwardPolicy(mesh).maxBehind };
+
     // Write cap + read-only cap resolved through the shared helpers from the
     // MACHINE-LOCAL stored mesh policy (no repo-file overlay). These are the same
     // resolvers the observability projection uses, so the enforced and exposed
@@ -2210,6 +2215,18 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                 markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_not_launch_ready', nodeId });
                 continue;
             }
+            // FRESHNESS gate (distinct from the health gate above): a clean-tree node that
+            // is `behind` its upstream reads as 'online' and passes isLaunchableNode, so
+            // without this it could win fitness routing and run a fresh worker against
+            // stale code. Skip a node whose git telemetry proves it stale (behind >
+            // maxBehind, or a submodule out of sync). Reuse the auto-fast-forward policy's
+            // maxBehind threshold so "how far behind is tolerable" is configured in ONE
+            // place. Telemetry-absent nodes pass (never block on missing data). The 4s
+            // reconcile retries once the node's auto-ff repair path catches it up.
+            if (!isMeshNodeFreshEnoughToLaunch(node, freshnessGate)) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_stale_behind_upstream', nodeId });
+                continue;
+            }
             const launchTarget = resolveAutoLaunchTarget(components, node);
             if (launchTarget.mode === 'skip') {
                 // Remote node we can't reach (no transport / no coordinator daemonId).

package/src/mesh/mesh-reconcile-loop.ts

@@ -754,7 +754,12 @@ function assignedRowLiveStatusIsAwaitingApproval(
 ): boolean {
     if (!nodeId || !sessionId) return false;
     try {
-        return sessionStatusFromNodes(mesh.nodes, nodeId, sessionId).status === 'awaiting_approval';
+        // Both blocked-on-input states hold the row: an approval (waiting_approval) and a
+        // question (awaiting_choice) legitimately park the worker awaiting the coordinator's
+        // mesh_approve / mesh_answer_question, so neither should accrue the reclaim streak
+        // (mission f1d25e11 extends the APPROVAL-INBOX-BLINDSPOT guard to questions).
+        const liveStatus = sessionStatusFromNodes(mesh.nodes, nodeId, sessionId).status;
+        return liveStatus === 'awaiting_approval' || liveStatus === 'awaiting_choice';
     } catch {
         return false;
     }

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

@@ -1200,6 +1200,306 @@ export function collectFastForwardGitlinkPaths(repoRoot: string, baseHead: strin
     });
 }
 
+/**
+ * Whether both commits exist locally in the submodule repo AND neither is an
+ * ancestor of the other — i.e. a genuine sibling divergence off a shared merge
+ * base. `baseCommit` ancestor-of `branchCommit` (strict fast-forward) returns
+ * false: that case needs no rebase (the gate excludes it). Equal commits, a
+ * missing commit, or a non-submodule path all return false (nothing to converge
+ * / ambiguity stays "not divergent").
+ */
+function isSubmoduleDivergedSibling(submoduleRepoPath: string, baseCommit: string, branchCommit: string): boolean {
+    if (!baseCommit || !branchCommit || baseCommit === branchCommit) return false;
+    try {
+        if (!fs.existsSync(submoduleRepoPath)) return false;
+        execFileSync(GIT, ['cat-file', '-e', `${baseCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        execFileSync(GIT, ['cat-file', '-e', `${branchCommit}^{commit}`], { cwd: submoduleRepoPath, stdio: 'ignore' });
+    } catch {
+        return false; // one of the commits is not available locally — cannot judge divergence
+    }
+    // base ancestor-of branch ⇒ pure fast-forward, not a sibling divergence.
+    try {
+        execFileSync(GIT, ['merge-base', '--is-ancestor', baseCommit, branchCommit], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        return false;
+    } catch { /* not a fast-forward → keep checking */ }
+    // branch ancestor-of base ⇒ branch is strictly behind (base already contains
+    // it); no branch-side commits to replay, not our case.
+    try {
+        execFileSync(GIT, ['merge-base', '--is-ancestor', branchCommit, baseCommit], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        return false;
+    } catch { /* neither ancestor of the other → genuine divergence */ }
+    // Require a real shared merge base so the rebase has a sane replay range.
+    try {
+        const mb = execFileSync(GIT, ['merge-base', baseCommit, branchCommit], { cwd: submoduleRepoPath, encoding: 'utf8' }).trim();
+        return !!mb;
+    } catch {
+        return false;
+    }
+}
+
+export type SubmoduleGitlinkConvergeResult = {
+    /** True when at least one diverged gitlink submodule was rebased onto its base-side commit. */
+    converged: boolean;
+    /**
+     * Set when convergence was declined/aborted (fail-safe → caller keeps the
+     * original defer→blocked_review path). One of:
+     *   no_changed_gitlinks — no gitlink differs base↔branch
+     *   not_diverged        — the gitlink is ff/behind/equal (gate handles it)
+     *   rebase_conflict     — replaying branch-side onto base-side hit a real
+     *                         content conflict inside the submodule (aborted)
+     */
+    reason?: string;
+    /**
+     * Converged gitlinks: path → the rebased submodule commit (SUBNEW) that the
+     * root rebase must resolve the gitlink conflict to. Only populated for paths
+     * whose submodule was successfully rebased (base-side is now a strict ancestor).
+     */
+    resolutions: Array<{ path: string; baseCommit: string; branchCommit: string; rebasedCommit: string }>;
+    /** Per-path outcome for observability/logging. */
+    gitlinks: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+        rebasedCommit?: string;
+        action: 'rebased' | 'skipped_not_diverged' | 'rebase_conflict';
+    }>;
+};
+
+/**
+ * Best-effort: ensure `commit` exists in the submodule repo at `submoduleRepoPath`
+ * by fetching it from the base repo's submodule checkout (a sibling working copy on
+ * the same machine) when it is missing. A no-op when the commit is already present
+ * or when the source path does not exist. Never throws — a fetch failure just
+ * leaves the commit missing and the caller's ancestry check declines to converge.
+ */
+function ensureSubmoduleCommitLocal(submoduleRepoPath: string, baseSubmoduleRepoPath: string, commit: string): void {
+    if (!commit) return;
+    try {
+        execFileSync(GIT, ['cat-file', '-e', `${commit}^{commit}`], { cwd: submoduleRepoPath, stdio: 'ignore' });
+        return; // already present
+    } catch { /* missing → try to fetch it */ }
+    try {
+        if (!fs.existsSync(submoduleRepoPath) || !fs.existsSync(baseSubmoduleRepoPath)) return;
+        // Fetch the exact object from the base repo's submodule by absolute path. `file://`
+        // fetch of an explicit sha requires uploadpack.allowAnySHA1InWant on some gits;
+        // fetching the base submodule's HEAD/all refs is the portable way to bring the
+        // reachable object in, so fetch all branches and tags from the local path.
+        execFileSync(GIT, ['-c', 'protocol.file.allow=always', 'fetch', '-q', baseSubmoduleRepoPath, '+refs/heads/*:refs/adhdev-refine-base/*'], {
+            cwd: submoduleRepoPath,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+    } catch { /* best-effort; ancestry check will simply decline if still missing */ }
+}
+
+/**
+ * STEP 1 of auto-converging diverged oss-style submodule gitlinks: rebase the
+ * branch-side submodule commit(s) onto the base-side submodule commit INSIDE the
+ * worktree's submodule checkout (detached HEAD), so the base-side commit becomes a
+ * strict ancestor of the rebased tip. Returns the rebased commit per path so the
+ * caller's root rebase can resolve the gitlink conflict to it (STEP 2, see
+ * {@link rootRebaseResolvingGitlinks}). This automates the documented manual
+ * strict-fast-forward bypass and keeps the landed submodule history linear rather
+ * than masking a divergence.
+ *
+ * Fail-safe by construction: it only touches gitlinks that are a genuine sibling
+ * divergence (both commits local, neither an ancestor of the other, shared merge
+ * base). A submodule rebase content conflict aborts, restores the branch-side
+ * checkout, and returns `converged:false` (caller keeps defer→blocked_review). It
+ * never commits the root and NEVER pushes — remote publish is the merge/
+ * reachability stage's job; this stage is local reconciliation only.
+ *
+ * @param worktreeRoot the branch worktree root (its `<path>` submodule checkout is rebased)
+ * @param baseRepoRoot the source/base repo root (reads the base-side gitlink commit)
+ * @param baseHead     the fetched base head (root ref) — source of base-side gitlink commits
+ * @param branchHead   the worktree branch head (root ref) — source of branch-side gitlink commits
+ */
+export function convergeDivergedSubmoduleGitlinks(
+    worktreeRoot: string,
+    baseRepoRoot: string,
+    baseHead: string,
+    branchHead: string,
+): SubmoduleGitlinkConvergeResult {
+    const changed = readChangedGitlinkPaths(worktreeRoot, baseHead, branchHead);
+    if (changed.length === 0) {
+        return { converged: false, reason: 'no_changed_gitlinks', resolutions: [], gitlinks: [] };
+    }
+
+    const gitlinks: SubmoduleGitlinkConvergeResult['gitlinks'] = [];
+    const resolutions: SubmoduleGitlinkConvergeResult['resolutions'] = [];
+    let sawDiverged = false;
+
+    for (const path of changed) {
+        // Base-side commit comes from the base repo's tree; branch-side from the worktree's.
+        const baseCommit = readTreeObject(baseRepoRoot, baseHead, path);
+        const branchCommit = readTreeObject(worktreeRoot, branchHead, path);
+        const submoduleRepoPath = pathResolve(worktreeRoot, path);
+
+        // The base-side submodule commit is recorded by the base workspace but may not
+        // yet exist in the worktree's submodule object store (it was committed locally
+        // in base/<path> and not necessarily fetched here). Make it available via a
+        // best-effort local fetch from the base repo's own submodule checkout so the
+        // ancestry check and rebase can see it. Without this, a genuinely-convergeable
+        // divergence would look "not local" and fall through to blocked_review.
+        if (baseCommit) {
+            ensureSubmoduleCommitLocal(submoduleRepoPath, pathResolve(baseRepoRoot, path), baseCommit);
+        }
+
+        if (!baseCommit || !branchCommit || !isSubmoduleDivergedSibling(submoduleRepoPath, baseCommit, branchCommit)) {
+            gitlinks.push({ path, baseCommit, branchCommit, action: 'skipped_not_diverged' });
+            continue;
+        }
+        sawDiverged = true;
+
+        // Rebase the branch-side submodule commit(s) onto the base-side commit in a
+        // DETACHED HEAD (never move a submodule branch ref). A conflict aborts and
+        // restores the submodule checkout to the branch-side commit.
+        let rebasedCommit: string | undefined;
+        try {
+            execFileSync(GIT, ['checkout', '-q', '--detach', branchCommit], { cwd: submoduleRepoPath, stdio: ['ignore', 'ignore', 'pipe'] });
+            execFileSync(GIT, ['rebase', baseCommit], { cwd: submoduleRepoPath, stdio: ['ignore', 'pipe', 'pipe'] });
+            rebasedCommit = execFileSync(GIT, ['rev-parse', 'HEAD'], { cwd: submoduleRepoPath, encoding: 'utf8' }).trim();
+        } catch {
+            try { execFileSync(GIT, ['rebase', '--abort'], { cwd: submoduleRepoPath, stdio: 'ignore' }); } catch { /* ignore */ }
+            try { execFileSync(GIT, ['checkout', '-q', '--detach', branchCommit], { cwd: submoduleRepoPath, stdio: 'ignore' }); } catch { /* ignore */ }
+            gitlinks.push({ path, baseCommit, branchCommit, action: 'rebase_conflict' });
+            // Real submodule content conflict → do NOT converge; caller keeps blocked_review.
+            return { converged: false, reason: 'rebase_conflict', resolutions: [], gitlinks };
+        }
+
+        gitlinks.push({ path, baseCommit, branchCommit, rebasedCommit, action: 'rebased' });
+        resolutions.push({ path, baseCommit, branchCommit, rebasedCommit: rebasedCommit! });
+    }
+
+    if (!sawDiverged) {
+        return { converged: false, reason: 'not_diverged', resolutions: [], gitlinks };
+    }
+    return { converged: resolutions.length > 0, resolutions, gitlinks };
+}
+
+export type RootRebaseGitlinkResolveResult = {
+    /** True when the root rebase completed (with gitlink conflicts resolved to the converged commits). */
+    ok: boolean;
+    /** New root HEAD after the rebase (only meaningful when ok). */
+    branchHead?: string;
+    /**
+     * Set when the rebase was aborted (fail-safe). One of:
+     *   non_gitlink_conflict — a conflict on a non-submodule path (genuine content conflict)
+     *   unexpected_gitlink   — a gitlink conflicted that we have no converged commit for
+     *   rebase_error         — the rebase failed for a non-conflict reason
+     */
+    reason?: string;
+    /** The paths that conflicted at the point of abort (for diagnostics). */
+    conflictPaths?: string[];
+};
+
+/**
+ * STEP 2 of auto-converging diverged submodule gitlinks: rebase the worktree root
+ * branch onto `baseHead`, resolving each submodule-gitlink conflict to the
+ * pre-converged commit from {@link convergeDivergedSubmoduleGitlinks}. git's
+ * recursive merge refuses to auto-merge a diverged gitlink ("Recursive merging
+ * with submodules currently only supports trivial cases"), so we drive the rebase
+ * ourselves: on each stop, if the ONLY unmerged paths are gitlinks we have a
+ * converged commit for, we stage those to the converged commit and `--continue`.
+ * Any non-gitlink conflict (or a gitlink with no converged commit) aborts the
+ * rebase and returns `ok:false` → caller keeps the defer→blocked_review path.
+ *
+ * On success the base-side gitlink is a strict ancestor of the resolved branch-side
+ * commit, so the downstream patch-equivalence gate treats it as a trivial
+ * fast-forward and passes.
+ */
+export function rootRebaseResolvingGitlinks(
+    worktreeRoot: string,
+    baseHead: string,
+    resolutions: Array<{ path: string; rebasedCommit: string }>,
+): RootRebaseGitlinkResolveResult {
+    const resolveByPath = new Map(resolutions.map(r => [r.path, r.rebasedCommit]));
+
+    const runRebase = (args: string[]): { ok: boolean } => {
+        try {
+            execFileSync(GIT, args, {
+                cwd: worktreeRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                // A rebase editor prompt would hang; keep it non-interactive.
+                env: { ...process.env, GIT_EDITOR: 'true', GIT_SEQUENCE_EDITOR: 'true' },
+            });
+            return { ok: true };
+        } catch {
+            return { ok: false };
+        }
+    };
+
+    const unmergedPaths = (): string[] => {
+        try {
+            return execFileSync(GIT, ['diff', '--name-only', '--diff-filter=U'], { cwd: worktreeRoot, encoding: 'utf8' })
+                .split('\n').map(s => s.trim()).filter(Boolean);
+        } catch {
+            return [];
+        }
+    };
+
+    const abort = (reason: string, conflictPaths?: string[]): RootRebaseGitlinkResolveResult => {
+        try { execFileSync(GIT, ['rebase', '--abort'], { cwd: worktreeRoot, stdio: 'ignore' }); } catch { /* ignore */ }
+        return { ok: false, reason, conflictPaths };
+    };
+
+    let progress = runRebase(['rebase', baseHead]);
+    let guard = 0;
+    while (!progress.ok) {
+        if (guard++ > 100) return abort('rebase_error');
+        const conflicts = unmergedPaths();
+        if (conflicts.length === 0) {
+            // Failed but no recorded conflicts — a non-conflict rebase error.
+            return abort('rebase_error');
+        }
+        // Every conflicting path must be a gitlink we have a converged commit for.
+        const unresolvable = conflicts.filter(p => !resolveByPath.has(p));
+        if (unresolvable.length > 0) {
+            // Distinguish a genuine (non-gitlink) content conflict from a gitlink we
+            // simply have no converged commit for. `ls-files --stage` reports mode
+            // 160000 for a gitlink at any conflict stage.
+            const unresolvableGitlink = unresolvable.some(p => {
+                try {
+                    const staged = execFileSync(GIT, ['ls-files', '--stage', '--', p], { cwd: worktreeRoot, encoding: 'utf8' });
+                    return /^160000\s/m.test(staged);
+                } catch {
+                    return false;
+                }
+            });
+            const allGitlink = unresolvable.every(p => {
+                try {
+                    const staged = execFileSync(GIT, ['ls-files', '--stage', '--', p], { cwd: worktreeRoot, encoding: 'utf8' });
+                    return /^160000\s/m.test(staged);
+                } catch {
+                    return false;
+                }
+            });
+            // A non-gitlink conflict is the fail-safe case that must clearly signal a
+            // genuine content conflict; a gitlink-only miss is the (rarer) case where a
+            // gitlink conflicted that STEP 1 did not converge.
+            return abort(allGitlink && unresolvableGitlink ? 'unexpected_gitlink' : 'non_gitlink_conflict', conflicts);
+        }
+        // Stage every conflicting gitlink to its converged commit, then continue.
+        for (const p of conflicts) {
+            const commit = resolveByPath.get(p)!;
+            try {
+                execFileSync(GIT, ['checkout', '-q', '--detach', commit], { cwd: pathResolve(worktreeRoot, p), stdio: 'ignore' });
+            } catch { /* the checkout is best-effort; the `add` below stamps the index either way */ }
+            try {
+                execFileSync(GIT, ['add', p], { cwd: worktreeRoot, stdio: 'ignore' });
+            } catch {
+                return abort('rebase_error', conflicts);
+            }
+        }
+        progress = runRebase(['rebase', '--continue']);
+    }
+
+    let branchHead: string | undefined;
+    try {
+        branchHead = execFileSync(GIT, ['rev-parse', 'HEAD'], { cwd: worktreeRoot, encoding: 'utf8' }).trim();
+    } catch { /* leave undefined */ }
+    return { ok: true, branchHead };
+}
+
 /**
  * Decide whether a merge-tree submodule conflict between base and branch is a
  * trivial gitlink fast-forward (and nothing else).