@adhdev/daemon-core 0.9.82-rc.457 → 0.9.82-rc.459

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

@@ -606,6 +606,80 @@ const AUTO_LAUNCH_COOLDOWN_MS = 5_000;
 // seconds) but bounded so a launch that silently never reaches idle is eventually retried.
 const AUTO_LAUNCH_AWAIT_CLAIM_MS = 90_000;
 
+// AUTOLAUNCH-CLAIM-CHURN. For a REMOTE node the launch→claim handshake is purely
+// event-sourced: the worker's agent:ready must be pulled (reconcile PHASE 1) to run
+// setRemoteIdleSession before the drain can claim. If that pull is lost, nothing recovers,
+// and after AUTO_LAUNCH_AWAIT_CLAIM_MS the loop used to blindly RESPAWN a new session — whose
+// respawn guards (nodeHasLiveSessionPendingClaim / liveSessionCountForNode) scan only the LOCAL
+// instanceManager, so the remote pending-claim session is invisible and a fresh ghost accumulates
+// every ~90s (observed live 2026-07-04: task 8b188c64, and 7 ghost sessions on this worktree's
+// own task at 11:23-11:34). Instead of respawning on window expiry, we re-drive the claim for the
+// EXISTING session; when its liveness cannot be positively determined we EXTEND the window with
+// exponential backoff (90 → 180 → 360s) and, only after the cap, deliver the task directly into
+// the launched session (the mesh_send_task-equivalent) rather than spawning another worker.
+const AUTO_LAUNCH_AWAIT_CLAIM_BACKOFF_CAP_CYCLES = 2;
+// Local mirror of REMOTE_IDLE_SESSION_TTL_MS (mesh-event-forwarding) — kept here to avoid a
+// cross-module import cycle. Used when (re)registering a launched remote session as an idle
+// claim candidate during the await-claim re-drive.
+const AUTO_LAUNCH_REMOTE_IDLE_TTL_MS = 5 * 60 * 1000;
+
+// Per-task await-claim backoff state, keyed `${meshId}::${taskId}`. `cycles` counts how many
+// times the window has been extended; `nextAttemptAtMs` rate-limits the re-drive to the backoff
+// cadence so the 4s reconcile tick does not hammer it. Cleared once the task claims, the direct
+// dispatch fires, or a respawn is authorized. In-memory (per process); a stale entry is harmless
+// (it only defers a respawn) and self-clears on the next resolution.
+interface AwaitClaimBackoffState { cycles: number; nextAttemptAtMs: number; }
+const autoLaunchAwaitClaimBackoff = new Map<string, AwaitClaimBackoffState>();
+
+// Test hooks: reset / seed the await-claim backoff state between cases.
+export function __resetAutoLaunchAwaitClaimBackoffForTests(): void {
+    autoLaunchAwaitClaimBackoff.clear();
+}
+export function __seedAutoLaunchAwaitClaimBackoffForTests(meshId: string, taskId: string, state: AwaitClaimBackoffState): void {
+    autoLaunchAwaitClaimBackoff.set(`${meshId}::${taskId}`, { ...state });
+}
+
+// Backoff window for a given cycle count: 90 → 180 → 360s (capped at the cap-cycle multiplier).
+function awaitClaimWindowMs(cycles: number): number {
+    return AUTO_LAUNCH_AWAIT_CLAIM_MS * Math.pow(2, Math.min(cycles, AUTO_LAUNCH_AWAIT_CLAIM_BACKOFF_CAP_CYCLES));
+}
+
+// Does the coordinator's remote-session view (MeshRuntimeStore remote idle sessions, populated by
+// mesh event forwarding) currently show this session as a live idle claim candidate? Positive
+// evidence the launched remote session is reachable — used to re-drive its claim directly instead
+// of respawning. Absence is NOT proof the session is gone (the agent:ready pull may simply have
+// been lost), so callers treat a false here as UNKNOWN liveness, never a definitive terminal.
+function remoteSessionAppearsLive(meshId: string, sessionId: string): boolean {
+    if (!sessionId) return false;
+    try {
+        return MeshRuntimeStore.getInstance().getRemoteIdleSessions(meshId)
+            .some(s => sessionIdsEquivalent(s.sessionId, sessionId));
+    } catch {
+        return false;
+    }
+}
+
+// (A) Respawn-guard remote-awareness. The session ids of pending tasks whose auto-launch record
+// targets `nodeId` (status started/completed with a sessionId) and is still inside its await-claim
+// window — the base 90s window OR an active backoff extension. Such a session is ALREADY on its way
+// to claim even when it is REMOTE (invisible to this daemon's instanceManager), so counting it
+// suppresses a duplicate launch that would otherwise spawn a ghost.
+function inWindowAutoLaunchSessionIdsForNode(meshId: string, nodeId: string): string[] {
+    const nowMs = Date.now();
+    const out: string[] = [];
+    for (const task of getQueue(meshId, { status: ['pending'] as any })) {
+        const al = task.autoLaunch;
+        const sid = al ? readNonEmptyString(al.sessionId) : '';
+        if (!al || (al.status !== 'started' && al.status !== 'completed') || !sid) continue;
+        if (!daemonIdsEquivalent(al.nodeId, nodeId)) continue;
+        const launchedAtMs = Date.parse(al.updatedAt);
+        const inBaseWindow = Number.isFinite(launchedAtMs) && nowMs - launchedAtMs < AUTO_LAUNCH_AWAIT_CLAIM_MS;
+        const inBackoff = autoLaunchAwaitClaimBackoff.has(`${meshId}::${task.id}`);
+        if (inBaseWindow || inBackoff) out.push(sid);
+    }
+    return out;
+}
+
 // De-dup for repeated `skipped` ledger noise: the reconcile loop re-runs the queue
 // trigger every 4s, so a task that can't be claimed (e.g. a remote node with no
 // transport, or a node under cooldown) would otherwise append an identical
@@ -1110,8 +1184,46 @@ export function isSessionActivelyGenerating(components: DaemonComponents, sessio
     return sessionStateLooksActive(state);
 }
 
+/**
+ * RECLAIM-FALSEPOS tri-state busy verdict for a session id.
+ *
+ * The binary isSessionActivelyGenerating() folds "absence of a positive generating
+ * signal" into a definitive NEGATIVE (returns false when the instance is absent). But a
+ * REMOTE session (never in THIS daemon's instanceManager) — or a locally-present session
+ * looked up under a skewed id form — then looks "not generating" and can be reclaimed out
+ * from under a worker that is genuinely mid-turn. This resolves an explicit three-way
+ * verdict instead:
+ *   - GENERATING       — a locally-present instance reports an active/streaming state.
+ *   - IDLE_CONFIRMED    — a locally-present instance reports a non-active (idle/terminal)
+ *                         state. Positive local evidence the worker is not working.
+ *   - UNKNOWN           — no locally-present instance matches (remote / gone / id-skew) or
+ *                         the observation failed. NEVER treated as IDLE_CONFIRMED.
+ *
+ * The lookup scans getByCategory('cli') with sessionIdsEquivalent (the same equivalence
+ * matching nodeHasActiveMeshWork / liveSessionCountForNode use) rather than a raw
+ * instanceManager.getInstance(id) Map.get, so an id-form-skewed but present session is
+ * found (closing the same id-form-skew hole class e245c2f9's F1 fixed elsewhere).
+ */
+export type SessionBusyVerdict = 'GENERATING' | 'IDLE_CONFIRMED' | 'UNKNOWN';
+export function resolveSessionBusyVerdict(components: DaemonComponents, sessionId: string): SessionBusyVerdict {
+    if (!sessionId) return 'UNKNOWN';
+    try {
+        const instances = components.instanceManager?.getByCategory?.('cli') || [];
+        const inst = instances.find((i: any) => {
+            const sid = readNonEmptyString(i?.getState?.().instanceId);
+            return sid && sessionIdsEquivalent(sid, sessionId);
+        });
+        if (!inst) return 'UNKNOWN'; // remote / gone / id-form skew not present locally
+        const state = inst.getState?.();
+        if (!state) return 'UNKNOWN';
+        return sessionStateLooksActive(state) ? 'GENERATING' : 'IDLE_CONFIRMED';
+    } catch {
+        return 'UNKNOWN'; // failed observation ⇒ unknown, never a definitive idle
+    }
+}
+
 function liveSessionCountForNode(components: DaemonComponents, meshId: string, nodeId: string): number {
-    return components.instanceManager.getByCategory('cli').filter((inst: any) => {
+    const localInstances = components.instanceManager.getByCategory('cli').filter((inst: any) => {
         const state = inst.getState();
         const settings = state.settings as Record<string, unknown> || {};
         if (readNonEmptyString(settings.meshNodeFor) !== meshId) return false;
@@ -1122,7 +1234,20 @@ function liveSessionCountForNode(components: DaemonComponents, meshId: string, n
         if (!daemonIdsEquivalent(instNodeId, nodeId)) return false;
         const status = readNonEmptyString(state.status).toLowerCase();
         return !isTerminalSessionStatus(status);
-    }).length;
+    });
+    let count = localInstances.length;
+    // (A) AUTOLAUNCH-CLAIM-CHURN: also count launched-but-not-yet-claimed sessions targeting this
+    // node whose await-claim window is still open. A REMOTE such session is invisible to the local
+    // instanceManager above, so without this the maxConcurrentSessions cap undercounts it and a
+    // duplicate ghost launch slips through. Exclude any id already represented by a local instance
+    // so a co-located launch is not double-counted.
+    const localSessionIds = localInstances
+        .map((inst: any) => readNonEmptyString(inst.getState().instanceId))
+        .filter(Boolean);
+    for (const sid of inWindowAutoLaunchSessionIdsForNode(meshId, nodeId)) {
+        if (!localSessionIds.some(local => sessionIdsEquivalent(local, sid))) count += 1;
+    }
+    return count;
 }
 
 /**
@@ -1141,6 +1266,12 @@ function liveSessionCountForNode(components: DaemonComponents, meshId: string, n
  * not match, preserving the legitimate first-session spawn.
  */
 function nodeHasLiveSessionPendingClaim(components: DaemonComponents, meshId: string, nodeId: string): boolean {
+    // (A) AUTOLAUNCH-CLAIM-CHURN remote-awareness: a task whose auto-launch record targets this
+    // node and is still inside its await-claim window (base or backoff) already has a session on
+    // its way to claim — even when that session is REMOTE and thus invisible to the local
+    // instanceManager scan below. Treat it as a live pending-claim session so a duplicate launch
+    // is suppressed and no ghost accumulates every ~90s.
+    if (inWindowAutoLaunchSessionIdsForNode(meshId, nodeId).length > 0) return true;
     // Session ids currently holding an assigned queue task on this node — those are busy,
     // not pending claimers, so they must NOT suppress a (read-only) launch.
     const busySessionIds = new Set(
@@ -1312,6 +1443,69 @@ function readMeshNodeId(node: any): string {
     return normalizeMeshNodeId(node) ?? '';
 }
 
+// AUTOLAUNCH-CLAIM-CHURN. The await-claim window for a launched (remote) session has expired
+// without a claim. Instead of a blind respawn, re-drive the claim for the EXISTING session,
+// backing off when its liveness is unknown, and only respawning when it is provably unclaimable.
+// Returns a directive for the caller:
+//   - 'claimed'  — the re-drive claimed/dispatched the task into the existing session (progress).
+//   - 'fallback' — the post-cap direct dispatch delivered the task into the existing session.
+//   - 'backoff'  — liveness unknown; the window was extended (or is still cooling down). No launch.
+//   - 'respawn'  — the session is provably gone/unclaimable; the caller may launch a fresh one.
+function driveExpiredAwaitClaim(
+    components: DaemonComponents,
+    meshId: string,
+    task: MeshWorkQueueEntry,
+    ctx: { sessionId: string; nodeId: string; providerType: string },
+): 'claimed' | 'fallback' | 'backoff' | 'respawn' {
+    const { sessionId, nodeId, providerType } = ctx;
+    const backoffKey = `${meshId}::${task.id}`;
+    const nowMs = Date.now();
+    const state = autoLaunchAwaitClaimBackoff.get(backoffKey) || { cycles: 0, nextAttemptAtMs: 0 };
+    // Rate-limit re-drive attempts to the backoff cadence so the 4s reconcile tick does not hammer
+    // a still-cooling-down window. The initial (no-state) expiry proceeds immediately.
+    if (state.nextAttemptAtMs && nowMs < state.nextAttemptAtMs) return 'backoff';
+
+    const atCap = state.cycles >= AUTO_LAUNCH_AWAIT_CLAIM_BACKOFF_CAP_CYCLES;
+    const live = remoteSessionAppearsLive(meshId, sessionId);
+
+    // (B) Re-drive when the remote view shows the session live; (C) after the backoff cap, force the
+    // same direct dispatch unconditionally. Both funnel through tryAssignQueueTask, which
+    // idempotently (re)registers the session, delivers the task message (send_chat), and marks the
+    // row assigned — the exact operation a coordinator performs manually via mesh_send_task. (D)
+    // The setRemoteIdleSession re-register makes this robust to a dropped agent:ready.
+    if ((live || atCap) && nodeId && providerType) {
+        try {
+            MeshRuntimeStore.getInstance().setRemoteIdleSession(meshId, nodeId, sessionId, providerType, nowMs + AUTO_LAUNCH_REMOTE_IDLE_TTL_MS);
+        } catch { /* best-effort re-register */ }
+        const assigned = tryAssignQueueTask(components, meshId, nodeId, sessionId, providerType);
+        if (assigned) {
+            autoLaunchAwaitClaimBackoff.delete(backoffKey);
+            const isFallback = atCap && !live;
+            recordAutoLaunchEvent(meshId, {
+                phase: 'completed',
+                taskId: task.id,
+                reason: isFallback ? 'await_claim_direct_dispatch_fallback' : 'await_claim_redriven',
+                nodeId,
+                sessionId,
+            });
+            // Content-free progress line (ids only).
+            LOG.info('MeshQueue', `Auto-launch await-claim ${isFallback ? 'direct-dispatch fallback' : 're-drive'} claimed task ${task.id} into existing session ${sessionId} on node ${nodeId} (mesh ${meshId})`);
+            return isFallback ? 'fallback' : 'claimed';
+        }
+        if (atCap) {
+            // The forced dispatch could not claim — the session is genuinely gone/unclaimable.
+            // Authorize a fresh respawn (ghosts were already prevented through the backoff window).
+            autoLaunchAwaitClaimBackoff.delete(backoffKey);
+            return 'respawn';
+        }
+    }
+    // Liveness unknown (or live-but-not-claimable) and not at cap → extend the window with backoff.
+    const cycles = Math.min(state.cycles + 1, AUTO_LAUNCH_AWAIT_CLAIM_BACKOFF_CAP_CYCLES);
+    autoLaunchAwaitClaimBackoff.set(backoffKey, { cycles, nextAttemptAtMs: nowMs + awaitClaimWindowMs(cycles) });
+    recordAutoLaunchEvent(meshId, { phase: 'skipped', taskId: task.id, reason: 'awaiting_launched_session_claim_backoff', nodeId, sessionId });
+    return 'backoff';
+}
+
 async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, meshId: string, mesh: any): Promise<boolean> {
     const queue = getQueue(meshId);
     // DEPENDSON-GATE-SYMMETRY: status index over the FULL queue (incl. completed)
@@ -1319,6 +1513,15 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
     // dependency, not just the still-active rows.
     const statusById = new Map(queue.map(task => [task.id, task.status] as const));
     const pending = queue.filter(task => task.status === 'pending');
+    // AUTOLAUNCH-CLAIM-CHURN: prune await-claim backoff state for tasks of this mesh that are no
+    // longer pending (claimed/completed/cancelled) so the map cannot grow without bound.
+    {
+        const pendingIds = new Set(pending.map(t => t.id));
+        const prefix = `${meshId}::`;
+        for (const key of [...autoLaunchAwaitClaimBackoff.keys()]) {
+            if (key.startsWith(prefix) && !pendingIds.has(key.slice(prefix.length))) autoLaunchAwaitClaimBackoff.delete(key);
+        }
+    }
     if (!pending.length) return false;
 
     // Write cap + read-only cap resolved through the shared helpers from the
@@ -1367,14 +1570,28 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
         // session never reaches idle within the window, a later tick retries.
         if (task.autoLaunch?.status === 'completed' && task.autoLaunch.sessionId) {
             const launchedAtMs = Date.parse(task.autoLaunch.updatedAt);
+            const alSessionId = readNonEmptyString(task.autoLaunch.sessionId);
+            const alNodeId = readNonEmptyString(task.autoLaunch.nodeId);
+            const alProvider = readNonEmptyString(task.autoLaunch.providerType);
             if (Number.isFinite(launchedAtMs) && Date.now() - launchedAtMs < AUTO_LAUNCH_AWAIT_CLAIM_MS) {
                 // Record the skip in the ledger ONLY (dedup'd). Do NOT call markAutoLaunch
                 // here: recordTaskAutoLaunch overwrites task.autoLaunch wholesale, which would
                 // erase the very `completed` record (status + sessionId + updatedAt) this guard
                 // reads on the next tick, reopening the duplicate-launch hole it closes.
-                recordAutoLaunchEvent(meshId, { phase: 'skipped', taskId: task.id, reason: 'awaiting_launched_session_claim', nodeId: task.autoLaunch.nodeId, sessionId: task.autoLaunch.sessionId });
+                recordAutoLaunchEvent(meshId, { phase: 'skipped', taskId: task.id, reason: 'awaiting_launched_session_claim', nodeId: alNodeId, sessionId: alSessionId });
                 continue;
             }
+            // AUTOLAUNCH-CLAIM-CHURN: the initial await-claim window expired. Rather than a blind
+            // respawn (which the local-only respawn guards can't dedup for a remote pending-claim
+            // session → ghost accumulation), re-drive the claim for the EXISTING launched session,
+            // backing off on unknown liveness and direct-dispatching after the cap. Only a
+            // 'respawn' directive falls through to a fresh launch below.
+            if (Number.isFinite(launchedAtMs) && alSessionId && alNodeId) {
+                const outcome = driveExpiredAwaitClaim(components, meshId, task, { sessionId: alSessionId, nodeId: alNodeId, providerType: alProvider });
+                if (outcome === 'claimed' || outcome === 'fallback') return true; // progress; suppress a duplicate launch
+                if (outcome === 'backoff') continue;                              // window extended; no respawn
+                // outcome === 'respawn' → session provably gone; proceed to a fresh launch below.
+            }
         }
 
         const candidateNodes = Array.isArray(mesh?.nodes)

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

@@ -60,7 +60,7 @@ import { readNonEmptyString, readMeshCompletionSummary, buildMeshSystemMessage }
 import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { expandDaemonIdForms, daemonIdsEquivalent, sessionIdsEquivalent } from '@adhdev/mesh-shared';
 import { getActiveDirectDispatches, getQueue, reclaimStrandedAssignedTask, updateTaskStatus } from './mesh-work-queue.js';
-import { isSessionActivelyGenerating } from './mesh-queue-assignment.js';
+import { resolveSessionBusyVerdict } from './mesh-queue-assignment.js';
 import { readLedgerEntries } from './mesh-ledger.js';
 import type { MeshLedgerEntry } from './mesh-ledger.js';
 import { pruneStaleDirectDispatches } from './mesh-active-work.js';
@@ -926,6 +926,28 @@ const ASSIGNED_STRANDED_DEADLINE_MS = 5 * 60_000;
 // reclaimed out from under itself.
 const DELIVERED_NO_TURN_DEADLINE_MS = 15 * 60_000;
 
+// RECLAIM-FALSEPOS: how many CONSECUTIVE UNKNOWN busy-verdict ticks (past the delivered-no-turn
+// deadline) must accumulate before a delivered row whose worker session cannot be positively
+// observed is reclaimed. An UNKNOWN verdict means the assigned session is not present in THIS
+// daemon's local instance map (remote / gone / id-form skew) — so it may be a REMOTE session that
+// is genuinely mid-turn. Reclaiming it on a single UNKNOWN tick tears a live remote worker off its
+// task and re-launches a near-duplicate (observed live 2026-07-04, session 21e34616 / task
+// a26806c1). We therefore DEFER on UNKNOWN and only reclaim after this bounded grace, so a
+// transient/remote absence never triggers a false reclaim while a genuinely-lost completion is
+// still eventually recovered. A GENERATING or IDLE_CONFIRMED verdict (locally-present positive
+// evidence) resets/bypasses the grace — see recoverStrandedAssignedDispatches.
+const RECLAIM_UNKNOWN_GRACE_TICKS = 3;
+
+// Per-row consecutive-UNKNOWN streak for delivered-no-turn reclaim, keyed `${meshId}::${taskId}`.
+// In-memory (per process); pruned each pass to the set of currently-assigned rows so a
+// completed/reclaimed/claimed-elsewhere row's counter is dropped (no unbounded growth).
+const deliveredNoTurnUnknownStreak = new Map<string, number>();
+
+// Test hook: clear the delivered-no-turn UNKNOWN streak between cases.
+export function __resetReclaimUnknownStreakForTests(): void {
+    deliveredNoTurnUnknownStreak.clear();
+}
+
 // PHASE 2.5 — assigned-stranded dispatch watchdog (Bug B). claimNextTask atomically
 // flips a row to 'assigned' BEFORE the fire-and-forget dispatch runs. If that dispatch
 // neither rejects (→ no .catch requeue) nor is confirmed delivered — a relay that hangs
@@ -942,6 +964,14 @@ function recoverStrandedAssignedDispatches(components: DaemonComponents, meshId:
     const assigned = getQueue(meshId, { status: ['assigned'] });
     if (!assigned.length) return;
     const nowMs = Date.now();
+    // RECLAIM-FALSEPOS: prune UNKNOWN streaks for rows of THIS mesh that are no longer
+    // 'assigned' (completed / reclaimed / claimed elsewhere) so the counter map cannot grow
+    // unbounded and a re-used task id starts its grace fresh.
+    const assignedKeys = new Set(assigned.map(r => `${meshId}::${r.id}`));
+    const meshKeyPrefix = `${meshId}::`;
+    for (const key of [...deliveredNoTurnUnknownStreak.keys()]) {
+        if (key.startsWith(meshKeyPrefix) && !assignedKeys.has(key)) deliveredNoTurnUnknownStreak.delete(key);
+    }
     for (const row of assigned) {
         const dispatchedAtMs = Date.parse(row.dispatchTimestamp ?? '');
         if (!Number.isFinite(dispatchedAtMs)) continue;              // no dispatch ts → can't age it
@@ -969,28 +999,71 @@ function recoverStrandedAssignedDispatches(components: DaemonComponents, meshId:
             // landed and none is in the ledger (checked just above). Normally this is PHASE 4's
             // job, but PHASE 4 only covers direct-dispatch rows / a live re-read; a claim-path
             // queue row whose completion event was lost (the manual-launch flip-miss signature)
-            // sits 'assigned' forever. Reclaim it — but ONLY once the session is idle/dead (its
-            // live local instance is not actively generating; a remote/absent instance reports
-            // non-generating too) AND a generous delivered-no-turn deadline has elapsed, so a
-            // worker genuinely mid-turn is never torn off its task. reclaimStrandedAssignedTask
-            // ends the single-flight window (F4), so a subsequent re-dispatch/requeue is unblocked.
+            // sits 'assigned' forever.
+            //
+            // RECLAIM-FALSEPOS tri-state verdict: the reclaim used to gate ONLY on
+            // isSessionActivelyGenerating(), whose local instance lookup returns "not generating"
+            // for a REMOTE (or id-form-skewed) session that is genuinely mid-turn — so such a
+            // worker was reclaimed at the deadline and re-launched same tick (near-duplicate
+            // execution; observed live 2026-07-04, session 21e34616 / task a26806c1). Resolve an
+            // explicit GENERATING / IDLE_CONFIRMED / UNKNOWN verdict instead:
+            //   - GENERATING     → worker demonstrably alive; never reclaim, reset grace.
+            //   - IDLE_CONFIRMED → positive LOCAL evidence (present instance, inactive) → reclaim
+            //                      now (past deadline) with the delivered-no-turn reason.
+            //   - UNKNOWN        → session not locally observable (remote / gone / id-skew). Do
+            //                      NOT fold into a definitive idle. DEFER: count consecutive
+            //                      UNKNOWN ticks and only reclaim after RECLAIM_UNKNOWN_GRACE_TICKS
+            //                      so a live remote worker is never torn off its task on a single
+            //                      absent observation; a genuinely-lost completion is still
+            //                      recovered after the bounded grace.
+            // reclaimStrandedAssignedTask ends the single-flight window (F4), so a subsequent
+            // re-dispatch/requeue is unblocked.
             if (nowMs - dispatchedAtMs < DELIVERED_NO_TURN_DEADLINE_MS) continue;   // still within turn budget
-            if (row.assignedSessionId && isSessionActivelyGenerating(components, row.assignedSessionId)) continue;  // worker still working
+            const streakKey = `${meshId}::${row.id}`;
+            const verdict = row.assignedSessionId
+                ? resolveSessionBusyVerdict(components, row.assignedSessionId)
+                : 'IDLE_CONFIRMED'; // no session bound → nothing live to protect
+            if (verdict === 'GENERATING') {
+                deliveredNoTurnUnknownStreak.delete(streakKey); // demonstrably alive → reset grace
+                continue;  // worker still working
+            }
+            let reclaimReason: 'delivered_no_turn_deadline' | 'reclaim_after_unknown_grace';
+            if (verdict === 'IDLE_CONFIRMED') {
+                deliveredNoTurnUnknownStreak.delete(streakKey);
+                reclaimReason = 'delivered_no_turn_deadline';
+            } else {
+                // UNKNOWN — defer and accumulate the consecutive-UNKNOWN streak.
+                const streak = (deliveredNoTurnUnknownStreak.get(streakKey) ?? 0) + 1;
+                deliveredNoTurnUnknownStreak.set(streakKey, streak);
+                if (streak < RECLAIM_UNKNOWN_GRACE_TICKS) {
+                    // Still within grace — hold this tick. Content-free trace (ids + streak only).
+                    traceMeshEventDrop('reclaim_deferred_unknown_verdict', {
+                        taskId: row.id,
+                        sessionId: row.assignedSessionId,
+                        nodeId: row.assignedNodeId,
+                        meshId,
+                        event: 'agent:generating_completed',
+                    }, `unknown ${streak}/${RECLAIM_UNKNOWN_GRACE_TICKS}`);
+                    continue;
+                }
+                reclaimReason = 'reclaim_after_unknown_grace';
+            }
             const reclaimedLost = reclaimStrandedAssignedTask(meshId, row.id, {
-                reason: 'delivered_no_turn_deadline',
+                reason: reclaimReason,
                 ageMs: nowMs - dispatchedAtMs,
             });
             if (reclaimedLost) {
+                deliveredNoTurnUnknownStreak.delete(streakKey);
                 LOG.warn('MeshReconcile', `Reclaimed delivered-but-lost task ${row.id} on mesh ${meshId} `
                     + `(node=${row.assignedNodeId ?? '?'} session=${row.assignedSessionId ?? '?'}, delivered but no `
-                    + `completion in ${Math.round((nowMs - dispatchedAtMs) / 1000)}s, session non-generating → ${reclaimedLost.status})`);
+                    + `completion in ${Math.round((nowMs - dispatchedAtMs) / 1000)}s, verdict ${verdict} → ${reclaimReason} → ${reclaimedLost.status})`);
                 traceMeshEventDrop('assigned_stranded_delivered_no_turn', {
                     taskId: row.id,
                     sessionId: row.assignedSessionId,
                     nodeId: row.assignedNodeId,
                     meshId,
                     event: 'agent:generating_completed',
-                }, `delivered ${Math.round((nowMs - dispatchedAtMs) / 1000)}s → ${reclaimedLost.status}`);
+                }, `delivered ${Math.round((nowMs - dispatchedAtMs) / 1000)}s ${reclaimReason} → ${reclaimedLost.status}`);
             }
             continue;
         }

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

@@ -16,7 +16,7 @@ import { getGitRepoStatus } from '../git/git-status.js';
 import * as yaml from 'js-yaml';
 import { loadMeshRefineConfig, resolveMeshRefineValidationPlan } from '../mesh/refine-config.js';
 import type { MeshRefineValidationCommandPlan } from '../mesh/refine-config.js';
-import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap } from '../mesh/worktree-bootstrap-config.js';
+import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap, resolveSubmoduleDefaultBranch } from '../mesh/worktree-bootstrap-config.js';
 import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
 import { basename as pathBasename, join as pathJoin, resolve as pathResolve } from 'path';
 import * as fs from 'fs';
@@ -1295,6 +1295,10 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                 commit: gitlink.commit,
                 reachable: false,
             };
+            // Resolved lazily once the submodule checkout/remote are confirmed; defaults
+            // to 'main' so error messages emitted before resolution stay byte-identical
+            // to the pre-generalization behavior on a main-default repo.
+            let submoduleDefaultBranch = 'main';
             try {
                 if (!fs.existsSync(submodulePath)) {
                     entry.error = `Submodule checkout missing at ${gitlink.path}`;
@@ -1350,9 +1354,18 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entries.push(entry);
                         continue;
                     }
-                    entry.remoteMainBranch = 'main';
+                    // Generalize the submodule's default branch (F18): '.gitmodules'
+                    // branch → local remote HEAD → remote-advertised HEAD → 'main'. On a
+                    // main-default submodule this resolves to 'main' and every ref target
+                    // below is byte-identical to the prior hardcoded path.
+                    submoduleDefaultBranch = await resolveSubmoduleDefaultBranch({
+                        submoduleRepoPath: submodulePath,
+                        superprojectWorkspace: repoRoot,
+                        submodulePath: gitlink.path,
+                    });
+                    entry.remoteMainBranch = submoduleDefaultBranch;
                     try {
-                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                        await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                         entry.fetchedFromOrigin = true;
                         entry.remoteReachable = true;
                         entry.remoteMainReachable = true;
@@ -1362,17 +1375,17 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                         entry.remoteMainReachable = false;
                         entry.publishRequired = true;
                         const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                        entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                        entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                         if (options.allowAutoPublishSubmoduleMainCommits === true && entry.localReachable === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = true;
                             try {
-                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, 'main');
+                                const publish = await publishCommitToRemoteMain(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.autoPublishRefspec = publish.refspec;
                                 entry.publishStdout = truncateValidationOutput(publish.stdout);
                                 entry.publishStderr = truncateValidationOutput(publish.stderr);
                                 entry.autoPublishSucceeded = true;
-                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, 'main');
+                                await verifyRemoteMainContainsCommit(submodulePath, gitlink.commit, submoduleDefaultBranch);
                                 entry.fetchedFromOrigin = true;
                                 entry.remoteReachable = true;
                                 entry.remoteMainReachable = true;
@@ -1384,13 +1397,13 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                                 entry.autoPublishSucceeded = false;
                                 entry.autoPublishVerified = false;
                                 const publishDetails = truncateValidationOutput(publishError?.stderr || publishError?.message || String(publishError));
-                                entry.error = `Submodule auto-publish to origin/main failed or could not be verified: ${publishDetails}`;
+                                entry.error = `Submodule auto-publish to origin/${submoduleDefaultBranch} failed or could not be verified: ${publishDetails}`;
                             }
                         } else if (options.allowAutoPublishSubmoduleMainCommits === true) {
                             entry.autoPublishAllowed = true;
                             entry.autoPublishAttempted = false;
                             entry.autoPublishSkippedReason = entry.autoPublishSkippedReason
-                                || 'candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/main';
+                                || `candidate commit is not reachable in the source checkout or worktree submodule, so Refinery cannot push it to origin/${submoduleDefaultBranch}`;
                         }
                     }
                 } catch (e: any) {
@@ -1398,7 +1411,7 @@ export async function runMeshRefineSubmoduleReachabilityGate(
                     entry.remoteMainReachable = false;
                     entry.publishRequired = true;
                     const details = truncateValidationOutput(e?.stderr || e?.message || String(e));
-                    entry.error = `Submodule remote main reachability check failed for origin/main: ${details}`;
+                    entry.error = `Submodule remote main reachability check failed for origin/${submoduleDefaultBranch}: ${details}`;
                 }
             } catch (e: any) {
                 entry.error = truncateValidationOutput(e?.message || String(e));

package/src/mesh/worktree-bootstrap-config.ts

@@ -92,6 +92,136 @@ export function getRegisteredSubmodulePaths(workspace: string): Set<string> {
     return paths;
 }
 
+/**
+ * Read each registered submodule's configured `branch` from `.gitmodules`, keyed
+ * by the submodule's normalized path (matching {@link getRegisteredSubmodulePaths}).
+ *
+ * `.gitmodules` stores `submodule.<name>.path` and (optionally)
+ * `submodule.<name>.branch`; this joins the two on `<name>`. The special branch
+ * value `.` ("track the superproject's branch") is deliberately OMITTED so callers
+ * fall through to remote-HEAD detection instead of treating `.` as a literal branch
+ * name. Returns an empty map when there are no submodules, no `.gitmodules`, or the
+ * lookup fails (conservative — callers then detect or fall back).
+ */
+export function getSubmoduleConfiguredBranches(workspace: string): Map<string, string> {
+    const branchesByPath = new Map<string, string>();
+    try {
+        const out = execFileSync(
+            resolveWin32Executable('git'),
+            ['config', '--file', '.gitmodules', '--list'],
+            { cwd: workspace, encoding: 'utf8', timeout: 10_000, windowsHide: true },
+        );
+        // Join `submodule.<name>.path` with `submodule.<name>.branch` on <name>.
+        const pathByName = new Map<string, string>();
+        const branchByName = new Map<string, string>();
+        for (const line of String(out).split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            const eq = trimmed.indexOf('=');
+            if (eq < 0) continue;
+            const key = trimmed.slice(0, eq);
+            const value = trimmed.slice(eq + 1).trim();
+            // key: submodule.<name>.<field>; <name> may itself contain dots, so match
+            // the leading `submodule.` and trailing `.<field>` and take the middle.
+            const match = /^submodule\.(.+)\.(path|branch)$/.exec(key);
+            if (!match) continue;
+            const name = match[1];
+            if (match[2] === 'path') {
+                const norm = value.replace(/\\/g, '/').replace(/\/+$/, '');
+                if (norm) pathByName.set(name, norm);
+            } else if (value) {
+                branchByName.set(name, value);
+            }
+        }
+        for (const [name, submodulePath] of pathByName) {
+            const branch = branchByName.get(name);
+            if (branch && branch !== '.') branchesByPath.set(submodulePath, branch);
+        }
+    } catch {
+        // No .gitmodules / git error → no configured branches.
+    }
+    return branchesByPath;
+}
+
+/** Fallback submodule branch when no configured/detected default can be resolved. */
+export const SUBMODULE_DEFAULT_BRANCH_FALLBACK = 'main';
+
+function isPlausibleBranchName(name: unknown): name is string {
+    return typeof name === 'string' && name.length > 0 && !/\s/.test(name) && name !== 'HEAD';
+}
+
+/**
+ * Resolve the default branch a submodule's commits are published to / checked for
+ * reachability against. Generalizes the previously hardcoded `main` so a submodule
+ * whose default branch is `master`/`trunk`/etc. is handled. Priority (each tier
+ * falls through to the next on miss/error):
+ *
+ *   1. `.gitmodules` `submodule.<name>.branch` (via {@link getSubmoduleConfiguredBranches};
+ *      `.` is ignored) — an explicit, local, zero-cost declaration.
+ *   2. the submodule checkout's LOCAL remote HEAD: `git symbolic-ref --short
+ *      refs/remotes/<remote>/HEAD` → strip the `<remote>/` prefix (no network).
+ *   3. the submodule remote's advertised HEAD: `git ls-remote --symref <remote> HEAD`
+ *      → `ref: refs/heads/<branch>` (one network round-trip).
+ *   4. fallback {@link SUBMODULE_DEFAULT_BRANCH_FALLBACK} (`'main'`).
+ *
+ * Because the final fallback is `'main'` and every earlier tier that resolves `'main'`
+ * yields the same string, a repo whose submodules default to `main` (the common case)
+ * produces byte-identical downstream fetch/merge-base/push ref targets — only a
+ * read-only resolution probe is added.
+ */
+export async function resolveSubmoduleDefaultBranch(opts: {
+    /** The submodule's local checkout — cwd for symbolic-ref / ls-remote. */
+    submoduleRepoPath: string;
+    /** The superproject workspace — for the `.gitmodules` branch lookup (tier 1). */
+    superprojectWorkspace?: string;
+    /** The submodule's path relative to the superproject (key into `.gitmodules`). */
+    submodulePath?: string;
+    /** Remote name (default `origin`). */
+    remote?: string;
+    /** Timeout for the local probe (tier 2); the network probe (tier 3) gets max(this, 30s). */
+    timeoutMs?: number;
+}): Promise<string> {
+    const remote = opts.remote?.trim() || 'origin';
+    const localTimeout = opts.timeoutMs ?? 10_000;
+    const git = resolveWin32Executable('git');
+    const execFileAsync = promisify(execFile);
+
+    // Tier 1: .gitmodules configured branch (local, zero-cost).
+    if (opts.superprojectWorkspace && opts.submodulePath) {
+        try {
+            const normalized = opts.submodulePath.replace(/\\/g, '/').replace(/\/+$/, '');
+            const configured = getSubmoduleConfiguredBranches(opts.superprojectWorkspace).get(normalized);
+            if (isPlausibleBranchName(configured)) return configured;
+        } catch { /* fall through */ }
+    }
+
+    // Tier 2: the local remote HEAD (no network) — set by clone/`git remote set-head`.
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: localTimeout, windowsHide: true },
+        );
+        const short = String(stdout || '').trim();
+        const prefix = `${remote}/`;
+        const branch = short.startsWith(prefix) ? short.slice(prefix.length) : short;
+        if (isPlausibleBranchName(branch)) return branch;
+    } catch { /* fall through */ }
+
+    // Tier 3: the remote's advertised HEAD (one network round-trip).
+    try {
+        const { stdout } = await execFileAsync(
+            git,
+            ['ls-remote', '--symref', remote, 'HEAD'],
+            { cwd: opts.submoduleRepoPath, encoding: 'utf8', timeout: Math.max(localTimeout, 30_000), windowsHide: true },
+        );
+        const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD/m.exec(String(stdout || ''));
+        if (match && isPlausibleBranchName(match[1])) return match[1];
+    } catch { /* fall through */ }
+
+    return SUBMODULE_DEFAULT_BRANCH_FALLBACK;
+}
+
 /**
  * True when `git status --porcelain` output represents a worktree that is clean
  * EXCEPT for submodule-gitlink-pointer moves. A worktree task that commits inside a