@adhdev/daemon-core 0.9.77-rc.43 → 0.9.77-rc.45

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/coordinator-prompt.ts

@@ -128,18 +128,24 @@ const TOOLS_SECTION = `## Available Tools
 
 | Tool | Purpose |
 |------|---------|
-| \`mesh_status\` | Check all nodes' health, git state, and active sessions |
+| \`mesh_status\` | Check all nodes' health, git state, active sessions, and branch convergence |
 | \`mesh_list_nodes\` | List nodes with workspace paths |
+| \`mesh_enqueue_task\` | Add a task to the pull-based work queue; idle nodes auto-claim |
+| \`mesh_view_queue\` | View queue status — pending, assigned, completed, failed, cancelled tasks |
+| \`mesh_queue_cancel\` | Cancel a queue task without deleting audit history |
+| \`mesh_queue_requeue\` | Return a task to pending for retry; clears stale session targets |
+| \`mesh_send_task\` | Legacy push: enqueue a task targeted at a specific node |
 | \`mesh_launch_session\` | Start a new agent session on a node |
-| \`mesh_send_task\` | Send a task (natural language) to a running agent |
-| \`mesh_read_chat\` | Read an agent's recent messages to check progress |
+| \`mesh_read_chat\` | Read recent chat messages from a delegated agent session |
+| \`mesh_read_debug\` | Collect a daemon-side chat/parser debug bundle for a session |
 | \`mesh_task_history\` | Read the task ledger — dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_git_status\` | Check git status on a specific node |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |
 | \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
 | \`mesh_refine_node\` | Validate and merge a completed worktree node back into its base branch |
-| \`mesh_remove_node\` | Remove a node (cleans up worktree if applicable) |`;
+| \`mesh_remove_node\` | Remove a node (cleans up worktree if applicable) |
+| \`mesh_cleanup_sessions\` | Manually clean up delegated session records for a node |`;
 
 const TOOL_EXPOSURE_PREFLIGHT_SECTION = `## Tool Exposure Preflight
 
@@ -151,9 +157,10 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
 2. **Plan** — Decompose the user's request into independent tasks for parallel execution, or sequential tasks when dependencies exist. If \`mesh_task_history\` shows a recent failure for a task, decide whether to retry or reassign.
 3. **Queue / Delegate** — The Mesh uses an autonomous pull-based Work Queue:
    a. **General Tasks**: Enqueue tasks using \`mesh_enqueue_task\`. Idle node agents will automatically pull tasks from the queue and begin working.
-   b. **Node Preparation**: Call \`mesh_launch_session\` to ensure enough agent sessions are active to handle the queue. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
+   b. **Node Preparation**: Reuse an existing idle session on the correct node/provider before launching a new chat/session. Call \`mesh_launch_session\` only when no suitable session exists, when the user explicitly asks for a fresh provider/session, or when branch/worktree isolation requires it. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
    c. **Targeted Tasks**: Use \`mesh_send_task\` only when you need to bypass the queue and force a specific node to execute a task immediately.
-   d. Always provide a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
+   d. For the first dispatch of a new task, provide a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
+   e. For a continuation of the same issue in an existing session, send a concise **delta instruction**: current verified state, the exact failed/blocked step, the newly approved action, and final reporting requirements. Do not resend the full original task or open a new chat solely to continue the same work; that wastes coordinator and worker context.
 4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
@@ -169,7 +176,7 @@ When a node agent stops unexpectedly, the daemon automatically enriches the syst
 - A recommendation: **retry**, **reassign**, or **escalate**
 
 Follow these recovery rules:
-1. **If "Retry recommended"**: Re-launch the session on the same node (\`mesh_launch_session\`), then resend the original task (\`mesh_send_task\`). The system message includes the original task text.
+1. **If "Retry recommended"**: Check \`mesh_view_queue\` first — the daemon may have auto-requeued. If not, re-launch the session on the same node (\`mesh_launch_session\`), then resend the original task (\`mesh_send_task\`). The system message includes the original task text.
 2. **If "Max retries exceeded"**: Do NOT retry on the same node. Either reassign the task to a different node, or inform the user that the task requires manual intervention.
 3. **If no recovery context**: The stop may be intentional (normal completion). Use \`mesh_read_chat\` once to verify, then move on.
 4. **Always record what happened**: After handling a failure, briefly note the outcome in your report to the user.`;
@@ -184,7 +191,8 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Minimize coordinator context.** The coordinator's job is routing, not implementing. Do not read source files, run commands, or analyze code directly — delegate all of that to node agents. Your context should stay lean.
 - **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to the queue or a node. Do not do it yourself.
 - **Respect explicit provider requests.** If the user names an agent/provider, pass the matching provider type to \`mesh_launch_session\`: Hermes → \`hermes-cli\`, Claude Code/Claude → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`. Never substitute \`claude-cli\` just because the coordinator itself is Claude Code.
-- **Front-load the task message.** When calling \`mesh_enqueue_task\` or \`mesh_send_task\`, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
+- **Front-load new task messages.** When calling \`mesh_enqueue_task\` or \`mesh_send_task\` for a new task, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
+- **Avoid context-wasting restarts.** For follow-up, retry, commit/push, preview, or cleanup work on the same issue, prefer the existing idle session and send only the delta from its last verified state. Start a fresh chat/session only for genuinely independent work, explicit provider/user request, unsafe transcript contamination, or required branch/worktree isolation.
 - **Don't inspect code.** Treat delegated agent summaries as self-reports, not verification. Verify side effects via \`mesh_git_status\` (including related repo freshness when configured), not by reading source files.
 - **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed. Never launch a duplicate session or second worker solely because \`mesh_read_chat\` has no final assistant message while the delegated session is still showing tool/terminal activity.
 - **Handle failures with context.** If a task fails, check \`mesh_task_history\` first to see if this task was attempted before and how it failed. Read the chat to understand why, then decide: retry on the same node, reassign to a different node, or escalate to the user.

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.
  */

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;
+  }
+}