@adhdev/daemon-core 0.9.77-rc.44 → 0.9.77-rc.46

package/src/git/git-worktree.ts

@@ -20,6 +20,7 @@ const execFileAsync = promisify(execFile);
 const WORKTREE_DIR_NAME = '.adhdev-worktrees';
 const GIT_TIMEOUT_MS = 30_000;
 const GIT_MAX_BUFFER = 4 * 1024 * 1024;
+const SUBMODULE_WORKTREE_REMOVE_RE = /working trees containing submodules cannot be moved or removed/i;
 
 // ─── Types ──────────────────────────────────────
 
@@ -52,11 +53,20 @@ export interface WorktreeEntry {
 export interface WorktreeRemoveOptions {
     /** Refuse to remove a worktree with uncommitted or untracked changes. */
     requireClean?: boolean;
+    /**
+     * If normal removal fails with Git's submodule-worktree guard, retry with
+     * `git worktree remove --force`. Callers must perform their own
+     * higher-level managed-path/convergence checks before enabling this.
+     */
+    allowSubmoduleForceFallback?: boolean;
 }
 
 export interface WorktreeRemoveResult {
     success: true;
     removedPath: string;
+    fallback?: 'git_worktree_remove_force_submodule';
+    forced?: boolean;
+    reason?: 'working_trees_containing_submodules';
 }
 
 // ─── Path Resolution ────────────────────────────
@@ -157,7 +167,31 @@ export async function removeWorktree(repoRoot: string, worktreePath: string, opt
         });
     } catch (error: any) {
         const stderr = typeof error.stderr === 'string' ? error.stderr : '';
-        throw new Error(`git worktree remove failed: ${stderr.trim() || error.message}`);
+        const stdout = typeof error.stdout === 'string' ? error.stdout : '';
+        const detail = `${stderr}\n${stdout}\n${error.message || ''}`;
+        if (opts.allowSubmoduleForceFallback && SUBMODULE_WORKTREE_REMOVE_RE.test(detail)) {
+            try {
+                await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
+                    cwd: repoRoot,
+                    encoding: 'utf8',
+                    timeout: GIT_TIMEOUT_MS,
+                    maxBuffer: GIT_MAX_BUFFER,
+                    windowsHide: true,
+                });
+            } catch (forceError: any) {
+                const forceStderr = typeof forceError.stderr === 'string' ? forceError.stderr : '';
+                const forceStdout = typeof forceError.stdout === 'string' ? forceError.stdout : '';
+                throw new Error(`git worktree remove --force fallback failed: ${forceStderr.trim() || forceStdout.trim() || forceError.message}`);
+            }
+            return {
+                success: true,
+                removedPath: worktreePath,
+                fallback: 'git_worktree_remove_force_submodule',
+                forced: true,
+                reason: 'working_trees_containing_submodules',
+            };
+        }
+        throw new Error(`git worktree remove failed: ${stderr.trim() || stdout.trim() || error.message}`);
     }
 
     return { success: true, removedPath: worktreePath };

package/src/index.d.ts

@@ -22,6 +22,9 @@ export { appendRecentActivity, getRecentActivity } from './config/recent-activit
 export type { RecentActivityEntry } from './config/recent-activity.js';
 export { getSavedProviderSessions, upsertSavedProviderSession } from './config/saved-sessions.js';
 export type { SavedProviderSessionEntry } from './config/saved-sessions.js';
+export { triggerMeshQueue } from './mesh/mesh-events.js';
+export { P2pRelayFailureError, buildP2pRelayFailurePayload, classifyP2pRelayFailure, isP2pRelayTransportFailure } from './mesh/p2p-relay-failure.js';
+export type { P2pRelayFailureClassification, P2pRelayFailureCode, P2pRelayFailureContext, P2pRelayFailurePayload } from './mesh/p2p-relay-failure.js';
 export { loadState, saveState, resetState } from './config/state-store.js';
 export type { DaemonState } from './config/state-store.js';
 export { detectIDEs } from './detection/ide-detector.js';

package/src/index.ts

@@ -160,6 +160,20 @@ export type { MeshWorkQueueEntry, MeshTaskStatus, MeshWorkQueueStats } from './m
 // ── Mesh Events ──
 export { triggerMeshQueue } from './mesh/mesh-events.js';
 
+// ── Mesh P2P Relay Failure Classification ──
+export {
+  P2pRelayFailureError,
+  buildP2pRelayFailurePayload,
+  classifyP2pRelayFailure,
+  isP2pRelayTransportFailure,
+} from './mesh/p2p-relay-failure.js';
+export type {
+  P2pRelayFailureClassification,
+  P2pRelayFailureCode,
+  P2pRelayFailureContext,
+  P2pRelayFailurePayload,
+} from './mesh/p2p-relay-failure.js';
+
 // ── State Store ──
 export { loadState, saveState, resetState } from './config/state-store.js';
 export type { DaemonState } from './config/state-store.js';

package/src/mesh/mesh-events.ts

@@ -1,9 +1,11 @@
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import { loadConfig } from '../config/config.js';
 import { getMesh, getMeshByRepo } from '../config/mesh-config.js';
+import { detectCLI } from '../detection/cli-detector.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry, getSessionRecoveryContext } from './mesh-ledger.js';
 import type { MeshLedgerKind, SessionRecoveryContext } from './mesh-ledger.js';
-import { claimNextTask, updateSessionTaskStatus, enqueueTask, updateTaskStatus } from './mesh-work-queue.js';
+import { claimNextTask, updateSessionTaskStatus, enqueueTask, updateTaskStatus, getQueue, recordTaskAutoLaunch } from './mesh-work-queue.js';
 
 // ---------------------------------------------------------------------------
 // Remote Node Idle Session Tracking
@@ -138,11 +140,296 @@ export function tryAssignQueueTask(
     return true;
 }
 
+const autoLaunchInProgress = new Set<string>();
+const autoLaunchCooldownUntil = new Map<string, number>();
+const AUTO_LAUNCH_COOLDOWN_MS = 5_000;
+
+function normalizeProviderPriority(policy: unknown): string[] {
+    const raw = policy && typeof policy === 'object' && !Array.isArray(policy)
+        ? (policy as Record<string, unknown>).providerPriority
+        : undefined;
+    if (!Array.isArray(raw)) return [];
+    const seen = new Set<string>();
+    return raw
+        .map(type => typeof type === 'string' ? type.trim() : '')
+        .filter(Boolean)
+        .filter(type => {
+            if (seen.has(type)) return false;
+            seen.add(type);
+            return true;
+        });
+}
+
+function isTerminalSessionStatus(status: string): boolean {
+    return ['stopped', 'failed', 'terminated', 'exited', 'closed'].includes(status);
+}
+
+function isIdleSessionState(state: any): boolean {
+    const status = readNonEmptyString(state?.status).toLowerCase();
+    if (isTerminalSessionStatus(status)) return false;
+    return status === 'idle' || state?.activeChat?.status === 'waiting_input';
+}
+
+function isDirtyNode(node: any): boolean {
+    return node?.health === 'dirty' || node?.git?.dirty === true;
+}
+
+function isLaunchableNode(node: any): boolean {
+    if (!node || node.status === 'disabled' || node.status === 'removed') return false;
+    const health = readNonEmptyString(node.health).toLowerCase();
+    if (!health) return true;
+    return health === 'online' || health === 'unknown';
+}
+
+function localAutoLaunchSkipReason(node: any): string | null {
+    const daemonId = readNonEmptyString(node?.daemonId);
+    const machineId = readNonEmptyString(node?.machineId);
+    const appConfig = loadConfig();
+    const localMachineId = readNonEmptyString(appConfig.machineId) || readNonEmptyString(appConfig.registeredMachineId);
+    const cloudDaemonId = localMachineId ? `daemon_${localMachineId}` : '';
+    const standaloneDaemonId = localMachineId ? `standalone_${localMachineId}` : '';
+
+    const daemonMatchesLocal = !daemonId || daemonId === cloudDaemonId || daemonId === standaloneDaemonId;
+    const machineMatchesLocal = !machineId || (localMachineId && machineId === localMachineId);
+
+    // ADHDev-managed local worktrees are explicitly safe to launch locally, but
+    // still must not be auto-launched if their metadata points at another
+    // daemon/machine. Remote nodes require an explicit coordinator launch path.
+    if (node?.isLocalWorktree === true) {
+        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
+    }
+
+    // Legacy/local workspace nodes may not have daemon/machine metadata. If
+    // metadata is present, require it to identify this daemon/machine before
+    // using the local cliManager.launch_cli path.
+    if (daemonId || machineId) {
+        return daemonMatchesLocal && machineMatchesLocal ? null : 'remote_auto_launch_unsupported';
+    }
+
+    return null;
+}
+
+function activeAssignedCount(meshId: string): number {
+    return getQueue(meshId, { status: ['assigned'] as any }).length;
+}
+
+function nodeHasActiveAssignment(meshId: string, nodeId: string): boolean {
+    return getQueue(meshId, { status: ['assigned'] as any }).some(task => task.assignedNodeId === nodeId);
+}
+
+function liveSessionCountForNode(components: DaemonComponents, meshId: string, nodeId: string): number {
+    return 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;
+        const instNodeId = readNonEmptyString(settings.meshNodeId) || readNonEmptyString(settings.nodeId);
+        if (instNodeId !== nodeId) return false;
+        const status = readNonEmptyString(state.status).toLowerCase();
+        return !isTerminalSessionStatus(status);
+    }).length;
+}
+
+function recordAutoLaunchEvent(meshId: string, args: {
+    phase: 'skipped' | 'started' | 'failed' | 'completed';
+    taskId: string;
+    nodeId?: string;
+    providerType?: string;
+    sessionId?: string;
+    reason?: string;
+    error?: string;
+}) {
+    try {
+        appendLedgerEntry(meshId, {
+            kind: 'session_auto_launch',
+            nodeId: args.nodeId,
+            sessionId: args.sessionId,
+            providerType: args.providerType,
+            payload: {
+                phase: args.phase,
+                taskId: args.taskId,
+                reason: args.reason,
+                error: args.error,
+            },
+        });
+    } catch (e: any) {
+        LOG.warn('MeshQueue', `Failed to record auto-launch ledger event: ${e?.message || e}`);
+    }
+}
+
+function markAutoLaunch(meshId: string, taskId: string, args: {
+    status: 'skipped' | 'started' | 'failed' | 'completed';
+    reason?: string;
+    nodeId?: string;
+    providerType?: string;
+    sessionId?: string;
+    error?: string;
+}) {
+    recordTaskAutoLaunch(meshId, taskId, {
+        status: args.status,
+        reason: args.reason || args.error,
+        nodeId: args.nodeId,
+        providerType: args.providerType,
+        sessionId: args.sessionId,
+    });
+    recordAutoLaunchEvent(meshId, {
+        phase: args.status,
+        taskId,
+        nodeId: args.nodeId,
+        providerType: args.providerType,
+        sessionId: args.sessionId,
+        reason: args.reason,
+        error: args.error,
+    });
+}
+
+async function resolveUsableProvider(components: DaemonComponents, nodeId: string, node: any): Promise<{ providerType?: string; reason?: string }> {
+    const providerPriority = normalizeProviderPriority(node?.policy);
+    if (!providerPriority.length) return { reason: 'missing_provider_priority' };
+    const providerLoader = components.providerLoader;
+    if (!providerLoader) return { reason: 'provider_loader_unavailable' };
+
+    const failed: string[] = [];
+    for (const requestedType of providerPriority) {
+        const normalizedType = typeof providerLoader.resolveAlias === 'function'
+            ? providerLoader.resolveAlias(requestedType)
+            : requestedType;
+        if (typeof providerLoader.isMachineProviderEnabled === 'function' && !providerLoader.isMachineProviderEnabled(normalizedType)) {
+            failed.push(`${requestedType}: disabled`);
+            continue;
+        }
+        let detected: any;
+        try {
+            detected = await detectCLI(normalizedType, providerLoader, { includeVersion: false });
+        } catch (e: any) {
+            failed.push(`${requestedType}: detect failed: ${e?.message || e}`);
+            continue;
+        }
+        if (typeof providerLoader.setCliDetectionResults === 'function') {
+            providerLoader.setCliDetectionResults([{
+                id: normalizedType,
+                installed: !!detected,
+                path: detected?.path,
+            }], false);
+        }
+        (components as any).onStatusChange?.();
+        if (detected) return { providerType: normalizedType };
+        failed.push(`${requestedType}: not detected`);
+    }
+    return { reason: `provider_priority_unusable: ${failed.join('; ') || nodeId}` };
+}
+
+async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, meshId: string, mesh: any): Promise<boolean> {
+    const queue = getQueue(meshId);
+    const pending = queue.filter(task => task.status === 'pending');
+    if (!pending.length) return false;
+
+    const maxParallelTasks = Math.max(1, Math.floor(Number(mesh?.policy?.maxParallelTasks) || 2));
+    for (const task of pending) {
+        if (activeAssignedCount(meshId) >= maxParallelTasks) {
+            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_parallel_tasks_reached' });
+            return false;
+        }
+        if (task.targetSessionId) {
+            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'target_session_constraint' });
+            continue;
+        }
+
+        const candidateNodes = Array.isArray(mesh?.nodes)
+            ? mesh.nodes.filter((node: any) => task.targetNodeId ? node?.id === task.targetNodeId : true)
+            : [];
+        if (!candidateNodes.length) {
+            markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'no_matching_node', nodeId: task.targetNodeId });
+            continue;
+        }
+
+        for (const node of candidateNodes) {
+            const nodeId = readNonEmptyString(node?.id);
+            if (!nodeId) continue;
+            const launchKey = `${meshId}:${nodeId}`;
+            const cooldownUntil = autoLaunchCooldownUntil.get(launchKey) || 0;
+            if (autoLaunchInProgress.has(launchKey)) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_in_progress', nodeId });
+                continue;
+            }
+            if (Date.now() < cooldownUntil) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'auto_launch_cooldown', nodeId });
+                continue;
+            }
+            if (isDirtyNode(node)) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'dirty_workspace', nodeId });
+                continue;
+            }
+            if (!isLaunchableNode(node)) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_not_launch_ready', nodeId });
+                continue;
+            }
+            const localSkipReason = localAutoLaunchSkipReason(node);
+            if (localSkipReason) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: localSkipReason, nodeId });
+                continue;
+            }
+            if (nodeHasActiveAssignment(meshId, nodeId)) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_has_active_assignment', nodeId });
+                continue;
+            }
+            const maxConcurrentSessions = Number(node?.policy?.maxConcurrentSessions);
+            if (Number.isFinite(maxConcurrentSessions) && maxConcurrentSessions >= 0 && liveSessionCountForNode(components, meshId, nodeId) >= maxConcurrentSessions) {
+                markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'max_concurrent_sessions_reached', nodeId });
+                continue;
+            }
+
+            autoLaunchInProgress.add(launchKey);
+            try {
+                const resolved = await resolveUsableProvider(components, nodeId, node);
+                if (!resolved.providerType) {
+                    markAutoLaunch(meshId, task.id, { status: 'skipped', reason: resolved.reason || 'provider_unusable', nodeId });
+                    continue;
+                }
+
+                markAutoLaunch(meshId, task.id, { status: 'started', nodeId, providerType: resolved.providerType });
+                const launchResult: any = await components.cliManager.handleCliCommand('launch_cli', {
+                    cliType: resolved.providerType,
+                    dir: node.workspace,
+                    settings: {
+                        meshNodeFor: meshId,
+                        meshNodeId: nodeId,
+                        spawnedSessionVisibility: mesh?.policy?.spawnedSessionVisibility || 'hidden',
+                        launchedByCoordinator: true,
+                        autoLaunchedForQueueTaskId: task.id,
+                    },
+                });
+                if (!launchResult?.success) {
+                    const reason = launchResult?.error || 'launch_cli_failed';
+                    markAutoLaunch(meshId, task.id, { status: 'failed', reason, nodeId, providerType: resolved.providerType });
+                    autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
+                    return false;
+                }
+                const sessionId = readNonEmptyString(launchResult.sessionId) || readNonEmptyString(launchResult.id) || readNonEmptyString(launchResult.runtimeSessionId);
+                if (!sessionId) {
+                    markAutoLaunch(meshId, task.id, { status: 'failed', reason: 'launch_missing_session_id', nodeId, providerType: resolved.providerType });
+                    autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
+                    return false;
+                }
+                markAutoLaunch(meshId, task.id, { status: 'completed', nodeId, providerType: resolved.providerType, sessionId });
+                tryAssignQueueTask(components, meshId, nodeId, sessionId, resolved.providerType);
+                return true;
+            } catch (e: any) {
+                markAutoLaunch(meshId, task.id, { status: 'failed', error: e?.message || String(e), nodeId });
+                autoLaunchCooldownUntil.set(launchKey, Date.now() + AUTO_LAUNCH_COOLDOWN_MS);
+                return false;
+            } finally {
+                autoLaunchInProgress.delete(launchKey);
+            }
+        }
+    }
+    return false;
+}
+
 /**
  * Triggers a queue check for all nodes in the mesh.
  * Called when a new task is enqueued, in case nodes are already idle.
  */
-export function triggerMeshQueue(components: DaemonComponents, meshId: string) {
+export async function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<void> {
     const mesh = getMeshWithCache(components, meshId);
     if (!mesh) return;
 
@@ -161,9 +448,7 @@ export function triggerMeshQueue(components: DaemonComponents, meshId: string) {
         // Only genuinely idle live sessions can pull work. Restored/stopped
         // records are kept for transcript/recovery visibility, but assigning
         // queue items to them strands tasks in assigned/pending without chat.
-        const status = readNonEmptyString(state.status).toLowerCase();
-        if (['stopped', 'failed', 'terminated', 'exited', 'closed'].includes(status)) continue;
-        if (status !== 'idle' && state.activeChat?.status !== 'waiting_input') continue;
+        if (!isIdleSessionState(state)) continue;
 
         const sessionId = state.instanceId;
         const providerType = state.type || readNonEmptyString(settings.providerType);
@@ -185,6 +470,8 @@ export function triggerMeshQueue(components: DaemonComponents, meshId: string) {
             }
         }
     }
+
+    await maybeAutoLaunchOneQueueSession(components, meshId, mesh);
 }
 
 function buildMeshSystemMessage(args: {

package/src/mesh/mesh-ledger.ts

@@ -27,6 +27,7 @@ export type MeshLedgerKind =
     | 'task_stalled'
     | 'task_approval_needed'
     | 'session_launched'
+    | 'session_auto_launch'
     | 'session_stopped'
     | 'checkpoint_created'
     | 'node_cloned'

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

@@ -25,6 +25,15 @@ export interface MeshWorkQueueEntry {
     requeueReason?: string;
     requeuedAt?: string;
     requeueCount?: number;
+    /** Last automatic queue session spin-up attempt, for mesh_view_queue/debug visibility. */
+    autoLaunch?: {
+        status: 'skipped' | 'started' | 'failed' | 'completed';
+        reason?: string;
+        nodeId?: string;
+        providerType?: string;
+        sessionId?: string;
+        updatedAt: string;
+    };
     createdAt: string;
     updatedAt: string;
 }
@@ -143,6 +152,24 @@ export function updateTaskStatus(
     return queue[idx];
 }
 
+export function recordTaskAutoLaunch(
+    meshId: string,
+    taskId: string,
+    autoLaunch: Omit<NonNullable<MeshWorkQueueEntry['autoLaunch']>, 'updatedAt'>,
+): MeshWorkQueueEntry | null {
+    const queue = readQueue(meshId);
+    const idx = queue.findIndex(q => q.id === taskId);
+    if (idx === -1) return null;
+    const now = new Date().toISOString();
+    queue[idx].autoLaunch = {
+        ...autoLaunch,
+        updatedAt: now,
+    };
+    queue[idx].updatedAt = now;
+    writeQueue(meshId, queue);
+    return queue[idx];
+}
+
 /**
  * Mark a queue task as manually cancelled without deleting audit history.
  */
@@ -225,6 +252,9 @@ export function updateSessionTaskStatus(
 }
 
 export interface MeshWorkQueueStats {
+    total: number;
+    active: number;
+    historical: number;
     pending: number;
     assigned: number;
     completed: number;
@@ -243,12 +273,20 @@ export interface MeshWorkQueueStats {
  */
 export function getMeshQueueStats(meshId: string): MeshWorkQueueStats {
     const queue = readQueue(meshId);
+    const pending = queue.filter(q => q.status === 'pending').length;
+    const assigned = queue.filter(q => q.status === 'assigned').length;
+    const completed = queue.filter(q => q.status === 'completed').length;
+    const failed = queue.filter(q => q.status === 'failed').length;
+    const cancelled = queue.filter(q => q.status === 'cancelled').length;
     return {
-        pending: queue.filter(q => q.status === 'pending').length,
-        assigned: queue.filter(q => q.status === 'assigned').length,
-        completed: queue.filter(q => q.status === 'completed').length,
-        failed: queue.filter(q => q.status === 'failed').length,
-        cancelled: queue.filter(q => q.status === 'cancelled').length,
+        total: queue.length,
+        active: pending + assigned,
+        historical: completed + failed + cancelled,
+        pending,
+        assigned,
+        completed,
+        failed,
+        cancelled,
         activeAssignments: queue
             .filter(q => q.status === 'assigned')
             .map(q => ({

package/src/mesh/p2p-relay-failure.ts

@@ -0,0 +1,152 @@
+export type P2pRelayFailureCode =
+  | 'p2p_unavailable'
+  | 'p2p_timeout'
+  | 'p2p_not_connected'
+  | 'p2p_datachannel_closed'
+  | 'p2p_no_route'
+  | 'p2p_daemon_offline'
+  | 'mesh_logic_or_provider_failure';
+
+export interface P2pRelayFailureContext {
+  command?: string;
+  targetDaemonId?: string;
+}
+
+export interface P2pRelayFailureClassification {
+  code: P2pRelayFailureCode;
+  reason: string;
+  transport: 'p2p' | 'unknown';
+  recoverable: boolean;
+  retryRecommended: boolean;
+  nextAction: string;
+  noFallbackReason: string;
+}
+
+export interface P2pRelayFailurePayload extends P2pRelayFailureClassification {
+  success: false;
+  error: string;
+  command?: string;
+  targetDaemonId?: string;
+}
+
+const NO_FALLBACK_REASON = 'Repo Mesh command/data-plane is P2P-only; WS/REST command fallback is intentionally disabled to preserve the transport boundary.';
+const P2P_NEXT_ACTION = 'Check daemon/P2P health, wait briefly for connection establishment, then do one bounded retry or requeue the mesh task after clearing stale target session metadata.';
+const NON_P2P_NEXT_ACTION = 'Inspect the provider/command error and fix the underlying logic or configuration before retrying.';
+
+function messageFromError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  if (error && typeof error === 'object') {
+    const candidate = (error as any).error ?? (error as any).message ?? (error as any).reason;
+    if (typeof candidate === 'string') return candidate;
+  }
+  return String(error || 'mesh relay command failed');
+}
+
+export function classifyP2pRelayFailure(error: unknown, _context: P2pRelayFailureContext = {}): P2pRelayFailureClassification {
+  const message = messageFromError(error);
+  const lower = message.toLowerCase();
+
+  const hasP2pSignal = /p2p|datachannel|node-datachannel|webrtc|ice|mesh_relay_command|daemon_mesh_p2p_transport/i.test(message);
+  const hasFailureSignal = /unavailable|missing|failed|failure|timeout|timed out|not connected|closed|disconnected|offline|no route|route unavailable|cannot send|cannot establish/i.test(message);
+
+  // Validation errors that merely mention mesh_relay_command are not transport failures.
+  if (/requires targetdaemonid and command|providerpriority|no inference provider|permission denied|read-only|not a member/i.test(message)) {
+    return {
+      code: 'mesh_logic_or_provider_failure',
+      reason: 'mesh_logic_or_provider_failure',
+      transport: 'unknown',
+      recoverable: false,
+      retryRecommended: false,
+      nextAction: NON_P2P_NEXT_ACTION,
+      noFallbackReason: NO_FALLBACK_REASON,
+    };
+  }
+
+  let code: P2pRelayFailureCode | null = null;
+  let reason = '';
+
+  if (/timeout|timed out/i.test(message) && (hasP2pSignal || /mesh transport/i.test(message))) {
+    code = 'p2p_timeout';
+    reason = 'daemon_mesh_p2p_timeout';
+  } else if (/no route|route unavailable/i.test(message)) {
+    code = 'p2p_no_route';
+    reason = 'daemon_mesh_p2p_no_route';
+  } else if (/offline|not owned|not found|not connected to server/i.test(message) && /daemon|peer|target/i.test(message)) {
+    code = 'p2p_daemon_offline';
+    reason = 'daemon_mesh_target_offline';
+  } else if (/closed|disconnected/i.test(message) && (hasP2pSignal || /state changed/i.test(message))) {
+    code = 'p2p_datachannel_closed';
+    reason = 'daemon_mesh_p2p_datachannel_closed';
+  } else if (/not connected|cannot send|cannot establish/i.test(message) && hasP2pSignal) {
+    code = 'p2p_not_connected';
+    reason = 'daemon_mesh_p2p_not_connected';
+  } else if (hasP2pSignal && hasFailureSignal) {
+    code = 'p2p_unavailable';
+    reason = 'daemon_mesh_p2p_transport_unavailable';
+  }
+
+  if (!code) {
+    return {
+      code: 'mesh_logic_or_provider_failure',
+      reason: 'mesh_logic_or_provider_failure',
+      transport: 'unknown',
+      recoverable: false,
+      retryRecommended: false,
+      nextAction: NON_P2P_NEXT_ACTION,
+      noFallbackReason: NO_FALLBACK_REASON,
+    };
+  }
+
+  return {
+    code,
+    reason,
+    transport: 'p2p',
+    recoverable: true,
+    retryRecommended: true,
+    nextAction: P2P_NEXT_ACTION,
+    noFallbackReason: NO_FALLBACK_REASON,
+  };
+}
+
+export function isP2pRelayTransportFailure(error: unknown): boolean {
+  return classifyP2pRelayFailure(error).recoverable === true;
+}
+
+export function buildP2pRelayFailurePayload(error: unknown, context: P2pRelayFailureContext = {}): P2pRelayFailurePayload {
+  const classification = classifyP2pRelayFailure(error, context);
+  return {
+    success: false,
+    ...classification,
+    error: messageFromError(error),
+    ...(context.command ? { command: context.command } : {}),
+    ...(context.targetDaemonId ? { targetDaemonId: context.targetDaemonId } : {}),
+  };
+}
+
+export class P2pRelayFailureError extends Error {
+  code: P2pRelayFailureCode;
+  reason: string;
+  transport: 'p2p' | 'unknown';
+  recoverable: boolean;
+  retryRecommended: boolean;
+  nextAction: string;
+  noFallbackReason: string;
+  command?: string;
+  targetDaemonId?: string;
+
+  constructor(message: string, context: P2pRelayFailureContext = {}) {
+    super(message);
+    this.name = 'P2pRelayFailureError';
+    const payload = buildP2pRelayFailurePayload(message, context);
+    this.code = payload.code;
+    this.reason = payload.reason;
+    this.transport = payload.transport;
+    this.recoverable = payload.recoverable;
+    this.retryRecommended = payload.retryRecommended;
+    this.nextAction = payload.nextAction;
+    this.noFallbackReason = payload.noFallbackReason;
+    this.command = context.command;
+    this.targetDaemonId = context.targetDaemonId;
+  }
+}

package/src/shared-types.ts

@@ -390,6 +390,9 @@ export interface SessionEntry {
     surfaceHidden?: boolean;
     settings?: Record<string, any>;
     meshQueueStats?: {
+        total?: number;
+        active?: number;
+        historical?: number;
         pending: number;
         assigned: number;
         completed: number;
@@ -442,6 +445,9 @@ export interface CompactSessionEntry {
     summaryMetadata?: ProviderSummaryMetadata;
     settings?: Record<string, any>;
     meshQueueStats?: {
+        total?: number;
+        active?: number;
+        historical?: number;
         pending: number;
         assigned: number;
         completed: number;