@adhdev/daemon-core 1.0.18-rc.1 → 1.0.18-rc.11

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

@@ -6,7 +6,7 @@ import { getMesh } from '../config/mesh-config.js';
 import { detectCLI } from '../detection/cli-detector.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry } from './mesh-ledger.js';
-import { buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, claimNextTask, updateTaskStatus, getQueue, recordTaskAutoLaunch, getActiveDirectDispatches, isTaskReadonly, taskDependenciesSatisfied, meshTaskNotBeforeReady, meshTaskPriorityRank } from './mesh-work-queue.js';
+import { buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, claimNextTask, updateTaskStatus, getQueue, recordTaskAutoLaunch, getActiveDirectDispatches, isTaskReadonly, taskDependenciesSatisfied, meshTaskNotBeforeReady, meshTaskPriorityRank, requeueTask } from './mesh-work-queue.js';
 import type { MeshWorkQueueEntry } from './mesh-work-queue.js';
 import { fastForwardMeshNode } from './mesh-fast-forward.js';
 import { createSessionDelivery, updateSessionDeliveryStatus } from './mesh-delivery-policy.js';
@@ -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';
@@ -931,6 +931,105 @@ function isTargetNodeTransientlyUnresolved(mesh: any, task: MeshWorkQueueEntry):
     return isWithinCloneBootstrapGrace(targetNodeId);
 }
 
+// ---------------------------------------------------------------------------
+// DEAD-TARGET-SELFHEAL: unpin a queue task hard-pinned to a session/node that has
+// died (absent from the live mesh) so a live idle session can claim it, instead of
+// leaving it stranded 'pending' forever behind the target_session_constraint skip.
+// ---------------------------------------------------------------------------
+
+// Conservative age gate before a pinned-but-dead target is unpinned. A target that is
+// merely briefly unassigned or momentarily reconnecting must not be reclaimed on the
+// tick it drops out of view; we require the task to have been idle (no updatedAt bump)
+// for at least this window first. Sized to comfortably outlast a transient P2P blip /
+// reconnect while staying well inside the reclaim cadence of the rest of the file
+// (AUTO_LAUNCH_AWAIT_CLAIM_MS is 90s; the stranded-reclaim watchdog fires on similar
+// scales), so a real reconnect wins the race and the self-heal only fires on a target
+// that is genuinely gone.
+const DEAD_TARGET_GRACE_MS = 60_000;
+
+interface DeadTargetVerdict {
+    /** The pinned target is confirmed dead and past the grace window → safe to unpin. */
+    dead: boolean;
+    /** True when the target NODE itself is absent from the live mesh (clear targetNodeId too). */
+    nodeDead: boolean;
+    /** Short reason string for the ledger/requeue. */
+    reason: string;
+}
+
+/**
+ * Decide whether a task's hard target pin (targetSessionId and/or targetNodeId) points at
+ * something that has DIED — i.e. is absent from the live mesh snapshot — and has been so
+ * long enough (DEAD_TARGET_GRACE_MS since the task's last update) that unpinning is safe.
+ *
+ * Two definitive death signals, deliberately conservative to never race a reconnecting node:
+ *
+ *  (1) NODE dead — the task pins a targetNodeId that matches NO node in the live mesh
+ *      (the same `meshNodeIdMatches`-over-mesh.nodes signal the targetPinUnmatched relabel
+ *      uses at the empty-candidate site). A pinned session on an absent node is unreachable
+ *      regardless, so the session pin is dead too. `nodeDead` ⇒ clear targetNodeId as well.
+ *      Excluded: a target that is only TRANSIENTLY unresolved (a freshly-cloned worktree
+ *      still propagating / bootstrapping) — isTargetNodeTransientlyUnresolved gates it out.
+ *
+ *  (2) SESSION dead on a LIVE LOCAL node — the target node IS present and is THIS daemon's
+ *      node, but the pinned session is absent from the local instance manager
+ *      (resolveSessionBusyVerdict === 'UNKNOWN'). Local session visibility is complete, so
+ *      absence here is genuine death, not a busy/generating flip. We KEEP targetNodeId (only
+ *      the session died; the node is healthy and can host a replacement claim).
+ *
+ * A live REMOTE node whose session is not in our idle view is NOT treated as dead: absence
+ * from the remote-idle mirror is explicitly UNKNOWN liveness (the session may be busy or its
+ * agent:ready pull merely lost), so unpinning it could race healthy in-flight work. Returns
+ * dead=false in that case, leaving the existing skip in place.
+ */
+function resolveDeadTargetVerdict(components: DaemonComponents, meshId: string, mesh: any, task: MeshWorkQueueEntry): DeadTargetVerdict {
+    const NOT_DEAD: DeadTargetVerdict = { dead: false, nodeDead: false, reason: '' };
+    const targetSessionId = readNonEmptyString(task.targetSessionId);
+    const targetNodeId = readNonEmptyString(task.targetNodeId);
+    if (!targetSessionId && !targetNodeId) return NOT_DEAD;
+
+    // Age gate: never reclaim a pin younger than the grace window (guards against a target
+    // that has only just dropped out of view for a momentary reconnect).
+    const lastUpdateMs = Date.parse(task.updatedAt || task.createdAt || '');
+    if (Number.isFinite(lastUpdateMs) && Date.now() - lastUpdateMs < DEAD_TARGET_GRACE_MS) return NOT_DEAD;
+
+    const nodes: any[] = Array.isArray(mesh?.nodes) ? mesh.nodes : [];
+
+    // (1) NODE-dead — a pinned node absent from the live mesh, and NOT merely transiently
+    // unresolved (a propagating/bootstrapping clone). This is a permanent routing miss.
+    if (targetNodeId) {
+        const nodePresent = nodes.some(n => meshNodeIdMatches(n, targetNodeId));
+        if (!nodePresent) {
+            if (isTargetNodeTransientlyUnresolved(mesh, task)) return NOT_DEAD;
+            return { dead: true, nodeDead: true, reason: 'dead_target_node_absent' };
+        }
+    }
+
+    // (2) SESSION-dead on a LIVE LOCAL node. Only meaningful when a session is pinned.
+    if (targetSessionId) {
+        // Resolve the pinned target's node (if any) to decide whether we can trust local
+        // absence. Without a targetNodeId, fall back to whichever live node hosts the session
+        // is unknowable here; treat that as a LOCAL check only (a session id we cannot see
+        // locally on a node we cannot resolve remotely stays UNKNOWN → not dead).
+        const node = targetNodeId
+            ? nodes.find(n => meshNodeIdMatches(n, targetNodeId))
+            : undefined;
+        // A pinned session on a REMOTE live node: absence from our view is UNKNOWN, not death.
+        // Only a LOCAL node (or no node pin at all — same-daemon assumption) lets us conclude
+        // death from local instance-manager absence.
+        const nodeIsLocal = node ? isLocalAutoLaunchNode(node) : true;
+        if (nodeIsLocal) {
+            const verdict = resolveSessionBusyVerdict(components, targetSessionId);
+            if (verdict === 'UNKNOWN') {
+                // Session absent from the complete local session view → genuinely gone.
+                return { dead: true, nodeDead: false, reason: 'dead_target_session_absent' };
+            }
+            // GENERATING / IDLE_CONFIRMED → the session is alive (possibly busy). Never disturb.
+        }
+    }
+
+    return NOT_DEAD;
+}
+
 /**
  * FALSE-BLOCKER-CLONE-QUEUE (stale-event clear): once a task whose actionable blocker we
  * previously paged either gets claimed or transitions to a self-resolving state, re-arm the
@@ -1888,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
@@ -1929,6 +2033,32 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             continue;
         }
         if (task.targetSessionId) {
+            // DEAD-TARGET-SELFHEAL: before the unconditional target_session_constraint skip,
+            // check whether the pinned session/node has DIED (absent from the live mesh). A
+            // hard-pinned task whose target is gone can NEVER re-enter 'assigned' (the claim
+            // gate refuses every non-matching session) and this skip fires forever with no
+            // liveness check — the triple-walled stranded-pending defect. If the pin is
+            // confirmed dead past the grace window, requeue it (clearing the dead session
+            // pin, and the node pin too when the NODE itself is gone) so a live idle session
+            // can claim it. requeueTask counts toward maxTaskRetries → bounded self-heal that
+            // auto-fails past the cap (the desired terminal state, unblocking dependents).
+            const deadTarget = resolveDeadTargetVerdict(components, meshId, mesh, task);
+            if (deadTarget.dead) {
+                const requeued = requeueTask(meshId, task.id, {
+                    reason: deadTarget.reason,
+                    clearTargetSession: true,
+                    // Keep the node pin if only the SESSION died on a still-live node; clear it
+                    // when the NODE itself is absent (nothing to pin to).
+                    clearTargetNode: deadTarget.nodeDead,
+                });
+                if (requeued) {
+                    LOG.warn('MeshQueue', `DEAD-TARGET-SELFHEAL: task ${task.id} (mesh ${meshId}) was pinned to a dead target (${deadTarget.reason}); requeued${deadTarget.nodeDead ? ' and unpinned node' : ''} (requeueCount=${requeued.requeueCount ?? '?'}, status=${requeued.status}).`);
+                }
+                // Keep the skip for THIS tick (the requeue already flipped the row to
+                // pending/failed); a later tick assigns/launches the now-unpinned task.
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'target_session_dead_requeued' });
+                continue;
+            }
             markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'target_session_constraint' });
             continue;
         }
@@ -2085,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

@@ -76,6 +76,7 @@ import {
     resolveReconcileIntervalMs,
 } from './mesh-reconcile-config.js';
 import { pullRemoteNodeQueues } from './mesh-remote-event-pull.js';
+import { runDiskRetentionSweep, detectAndSignalOrphanWorktrees } from './mesh-disk-retention.js';
 import {
     reconcileUnterminatedDirectDispatches,
     autoPruneStaleDirectDispatches,
@@ -126,6 +127,16 @@ interface LiveCoordinator {
 // "restart does not clear it" symptom the operator needs visibility into).
 const coordinatorModalParkState = new Map<string, boolean>();
 
+// Disk/worktree retention throttle. The reconcile tick runs every ~4s, but the
+// retention sweep (fs walks + git worktree list) is far too heavy for that cadence
+// and its artifacts age in days, so it runs at most once per hour. `undefined`
+// means "never run yet" → runs on the first tick after daemon start so a long-lived
+// backlog is reclaimed promptly rather than an hour later. Per-process; a restart
+// re-runs it immediately, which is the desired behavior (a restart is exactly when
+// stale artifacts from the previous run should be swept).
+const DISK_RETENTION_INTERVAL_MS = 60 * 60 * 1000; // 1h
+let lastDiskRetentionRunAt: number | undefined;
+
 // Find live CLI coordinator instances on THIS daemon, keyed by mesh.
 function findLiveCoordinators(components: DaemonComponents): LiveCoordinator[] {
     const out: LiveCoordinator[] = [];
@@ -743,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;
     }
@@ -1354,6 +1370,44 @@ export async function runMeshReconcileTick(components: DaemonComponents): Promis
         }
     }
 
+    // ── PHASE 6: disk / worktree retention (hourly, mission 86def38d) ──────────
+    // Legacy on-disk artifacts under ~/.adhdev accumulated with NO lifetime and grew
+    // the data volume until a refine bootstrap failed at 98% disk. This throttled pass
+    // (≤1×/hour — the artifacts age in days and the fs/git walk is too heavy for the 4s
+    // tick) reclaims them:
+    //   • JSONL ledger files older than 30d (legacy after the SQLite ledger)
+    //   • terminated session-host runtime files older than 14d (live never touched)
+    //   • mesh-runtime.db.bak-* backups older than 7d
+    //   • orphan worktree DETECTION → cleanup_candidate ledger signal (NEVER deleted).
+    // Runs BEFORE PHASE 2's early return so it fires whether or not a live CLI
+    // coordinator exists on this daemon. Isolated in try/catch so it can never kill the
+    // tick. All file deletions are defensive (age + live-runtime guards in the pure
+    // selectors); worktree cleanup stays manual/coordinator-driven.
+    {
+        const nowMs = Date.now();
+        const due = lastDiskRetentionRunAt === undefined
+            || (nowMs - lastDiskRetentionRunAt) >= DISK_RETENTION_INTERVAL_MS;
+        if (due) {
+            lastDiskRetentionRunAt = nowMs;
+            try {
+                runDiskRetentionSweep(nowMs);
+            } catch (e: any) {
+                LOG.warn('MeshReconcile', `Disk retention sweep failed: ${e?.message || e}`);
+            }
+            // Orphan-worktree detection is per-mesh (needs the mesh's base repo + node set)
+            // and only for meshes this daemon hosts (its local base checkout is the git anchor).
+            for (const mesh of listMeshes()) {
+                const selfIds = resolveCoordinatorSelfIds(mesh, drainDaemonIds);
+                if (!daemonHostsMesh(mesh, selfIds)) continue;
+                try {
+                    await detectAndSignalOrphanWorktrees(mesh, nowMs);
+                } catch (e: any) {
+                    LOG.warn('MeshReconcile', `Orphan worktree detection failed for mesh ${mesh.id}: ${e?.message || e}`);
+                }
+            }
+        }
+    }
+
     // ── PHASE 2: inject into live CLI coordinators on this daemon ──────────────
     const coordinators = findLiveCoordinators(components);
     if (coordinators.length === 0) {

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).