@adhdev/daemon-core 0.9.82-rc.45 → 0.9.82-rc.451

package/src/mesh/mesh-clone-grace.ts

@@ -0,0 +1,68 @@
+import { normalizeMeshNodeId, type MeshNodeIdentified } from '@adhdev/mesh-shared';
+
+// ---------------------------------------------------------------------------
+// Recently-cloned worktree node grace window
+// ---------------------------------------------------------------------------
+// FALSE-BLOCKER-CLONE-QUEUE: right after mesh_clone_node registers a worktree node, a
+// queue task pinned to that node id (target_node pin) can transiently find NO matching
+// node in the coordinator-owning daemon's mesh view, because:
+//   - the clone wrote the node ONLY into the inline mesh cache (med-family clone branch),
+//     and that inline entry has not yet PROPAGATED to the coordinator daemon (the clone
+//     may have run on the source node's machine and forwarded), and/or
+//   - the node's worktree bootstrap (npm install / native-addon repair) is still running,
+//     so the claim gate defers anyway.
+// In BOTH cases the unmatch SELF-RESOLVES within ~seconds (observed bootstrap ~2m8s) — it
+// is NOT the permanent `target_node_id_unmatched` routing miss (a removed/dead node) that
+// the actionable-blocker coordinator notification exists for. This registry lets the skip
+// classifier tell the transient case apart from the permanent one: a node id recorded here
+// (within the grace TTL) is a freshly cloned worktree whose unmatch should be reported as a
+// transient, NON-actionable skip rather than paging the coordinator with a false
+// "will NOT clear on its own" blocker.
+//
+// The window is floored well above the observed clone + bootstrap + inline-cache
+// propagation latency so a slow-but-live clone is never misclassified as a permanent
+// unmatch. A genuinely dead/removed node is never recorded here (or its entry has long
+// expired), so its `target_node_id_unmatched` stays correctly actionable.
+export const CLONE_BOOTSTRAP_GRACE_MS = 10 * 60 * 1000;
+
+const recentlyClonedNodeExpiry = new Map<string, number>(); // normalized nodeId -> expiry epoch ms
+const MAX_TRACKED_CLONED_NODES = 512;
+
+function normalizeNodeIdKey(nodeId: string | undefined | null): string {
+    return normalizeMeshNodeId({ id: nodeId ?? undefined } as MeshNodeIdentified) ?? '';
+}
+
+/** Record that a worktree node id was just cloned, opening its transient grace window. */
+export function noteRecentlyClonedNode(nodeId: string | undefined | null, nowMs: number = Date.now()): void {
+    const key = normalizeNodeIdKey(nodeId);
+    if (!key) return;
+    recentlyClonedNodeExpiry.set(key, nowMs + CLONE_BOOTSTRAP_GRACE_MS);
+    if (recentlyClonedNodeExpiry.size > MAX_TRACKED_CLONED_NODES) {
+        // Map iteration is insertion-ordered; the first key is the oldest-inserted entry.
+        const oldest = recentlyClonedNodeExpiry.keys().next().value;
+        if (oldest !== undefined) recentlyClonedNodeExpiry.delete(oldest);
+    }
+}
+
+/** True when nodeId was cloned within the grace window (and the entry has not expired). */
+export function isWithinCloneBootstrapGrace(nodeId: string | undefined | null, nowMs: number = Date.now()): boolean {
+    const key = normalizeNodeIdKey(nodeId);
+    if (!key) return false;
+    const expiry = recentlyClonedNodeExpiry.get(key);
+    if (expiry === undefined) return false;
+    if (nowMs >= expiry) {
+        recentlyClonedNodeExpiry.delete(key);
+        return false;
+    }
+    return true;
+}
+
+/** Drop a node's grace entry (e.g. once it has fully resolved into the mesh view). */
+export function clearCloneBootstrapGrace(nodeId: string | undefined | null): void {
+    const key = normalizeNodeIdKey(nodeId);
+    if (key) recentlyClonedNodeExpiry.delete(key);
+}
+
+export function __resetCloneBootstrapGraceForTests(): void {
+    recentlyClonedNodeExpiry.clear();
+}

package/src/mesh/mesh-coordinator-config.ts

@@ -0,0 +1,97 @@
+/**
+ * Hermes / MCP coordinator config helpers
+ *
+ * Extracted from commands/router.ts (behavior-preserving move). Contains the
+ * MCP-server config parse/serialize helpers and the Hermes coordinator base
+ * config loading / temp-override stripping / credential-copy helpers.
+ *
+ * router.ts re-exports every public symbol from here so existing import paths
+ * keep working.
+ */
+
+import { LOG } from '../logging/logger.js';
+import * as yaml from 'js-yaml';
+import { homedir } from 'os';
+import { join as pathJoin, resolve as pathResolve } from 'path';
+import * as fs from 'fs';
+import type { MeshCoordinatorConfigFormat } from './mesh-refine-gates.js';
+
+function loadYamlModule(): { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string } {
+    return yaml as { load: (input: string) => any; dump: (input: any, options?: Record<string, any>) => string };
+}
+
+export function getMcpServersKey(format: MeshCoordinatorConfigFormat): 'mcpServers' | 'mcp_servers' {
+    return format === 'hermes_config_yaml' ? 'mcp_servers' : 'mcpServers';
+}
+
+export function parseMeshCoordinatorMcpConfig(text: string, format: MeshCoordinatorConfigFormat): Record<string, any> {
+    if (!text.trim()) return {};
+    if (format === 'claude_mcp_json') return JSON.parse(text);
+    const parsed = loadYamlModule().load(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+export function serializeMeshCoordinatorMcpConfig(config: Record<string, any>, format: MeshCoordinatorConfigFormat): string {
+    if (format === 'claude_mcp_json') return JSON.stringify(config, null, 2);
+    return loadYamlModule().dump(config, { noRefs: true, lineWidth: 120 });
+}
+
+function resolveHermesUserHome(): string {
+    const explicitHome = process.env.HERMES_HOME?.trim();
+    return explicitHome || pathJoin(homedir(), '.hermes');
+}
+
+export function loadHermesCoordinatorBaseConfig(targetConfigPath: string): { config: Record<string, any>; sourceHome: string; sourceConfigPath: string } {
+    const sourceHome = resolveHermesUserHome();
+    const sourceConfigPath = pathJoin(sourceHome, 'config.yaml');
+    if (!fs.existsSync(sourceConfigPath)) return { config: {}, sourceHome, sourceConfigPath };
+    if (pathResolve(sourceConfigPath) === pathResolve(targetConfigPath)) return { config: {}, sourceHome, sourceConfigPath };
+
+    const parsed = parseMeshCoordinatorMcpConfig(fs.readFileSync(sourceConfigPath, 'utf-8'), 'hermes_config_yaml');
+    const { mcp_servers: _mcpServers, ...baseConfig } = parsed;
+    return { config: baseConfig, sourceHome, sourceConfigPath };
+}
+
+export function stripHermesCoordinatorTempModelProviderOverrides(config: Record<string, any>): Record<string, any> {
+    const {
+        model: _model,
+        provider: _provider,
+        default_model: _defaultModel,
+        defaultProvider: _defaultProvider,
+        default_provider: _defaultProviderSnake,
+        modelProvider: _modelProvider,
+        model_provider: _modelProviderSnake,
+        ...sanitized
+    } = config;
+    const delegation = sanitized.delegation;
+    if (delegation && typeof delegation === 'object' && !Array.isArray(delegation)) {
+        const {
+            model: _delegationModel,
+            provider: _delegationProvider,
+            modelProvider: _delegationModelProvider,
+            model_provider: _delegationModelProviderSnake,
+            ...delegationRest
+        } = delegation;
+        if (Object.keys(delegationRest).length > 0) {
+            sanitized.delegation = delegationRest;
+        } else {
+            delete sanitized.delegation;
+        }
+    }
+    return sanitized;
+}
+
+export function copyHermesCoordinatorCredentialFiles(sourceHome: string, targetHome: string) {
+    if (pathResolve(sourceHome) === pathResolve(targetHome)) return;
+    for (const fileName of ['.env', 'auth.json']) {
+        const sourcePath = pathJoin(sourceHome, fileName);
+        const targetPath = pathJoin(targetHome, fileName);
+        if (!fs.existsSync(sourcePath)) continue;
+        try {
+            fs.copyFileSync(sourcePath, targetPath);
+        } catch (error: any) {
+            LOG.warn('MeshCoordinator', `Could not copy Hermes ${fileName} into isolated coordinator home: ${error?.message || error}`);
+        }
+    }
+}
+

package/src/mesh/mesh-delivery-policy.ts

@@ -0,0 +1,315 @@
+import { randomUUID } from 'crypto';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+
+/**
+ * Possible delivery statuses for a session delivery record.
+ */
+export type MeshSessionDeliveryStatus =
+    | 'queued'
+    | 'delivering'
+    | 'delivered'
+    | 'acked'
+    | 'completed'
+    | 'failed'
+    | 'expired'
+    | 'cancelled';
+
+/**
+ * Kind of delivery — controls priority and policy handling.
+ */
+export type MeshSessionDeliveryKind =
+    | 'task'
+    | 'followup'
+    | 'approval'
+    | 'recovery'
+    | 'system_notice';
+
+/**
+ * A session delivery decision — what to do when a task arrives for a session.
+ */
+export type MeshDeliveryDecision =
+    | 'immediate'     // Session is idle: deliver now, create an 'acked' delivery record
+    | 'queued'        // Session is busy: hold delivery until session becomes idle
+    | 'rejected';     // Session is terminal or unknown: cannot deliver
+
+export interface MeshDeliveryPolicyResult {
+    decision: MeshDeliveryDecision;
+    reason: string;
+    /** When decision='queued', estimated deliver-after ISO timestamp if known. */
+    deliverAfter?: string;
+    /** Human-readable explanation for coordinator/operator. */
+    message: string;
+}
+
+/**
+ * Session statuses where immediate delivery is allowed.
+ * The session is ready to accept new work.
+ */
+const IMMEDIATE_DELIVERY_STATUSES = new Set([
+    'idle',
+    'waiting_input',
+    'ready',
+]);
+
+/**
+ * Session statuses that indicate the session is busy but still alive.
+ * Delivery is queued rather than attempted immediately.
+ */
+const BUSY_DELIVERY_STATUSES = new Set([
+    'generating',
+    'running',
+    'streaming',
+    'busy',
+    'starting',
+    'initializing',
+    'waiting_approval',
+]);
+
+/**
+ * Session statuses that indicate the session is permanently unavailable.
+ * Delivery should be rejected.
+ */
+const TERMINAL_DELIVERY_STATUSES = new Set([
+    'stopped',
+    'failed',
+    'terminated',
+    'exited',
+    'closed',
+    'deleted',
+    'error',
+]);
+
+/**
+ * Determine whether to deliver immediately, queue, or reject based on session status.
+ *
+ * This is a pure function — it does not write to any store.
+ */
+export function resolveDeliveryDecision(
+    sessionStatus: string | undefined,
+    opts?: {
+        kind?: MeshSessionDeliveryKind;
+        /** When true, busy session immediate injection is allowed (provider-specific capability). */
+        allowBusyInjection?: boolean;
+    },
+): MeshDeliveryPolicyResult {
+    const status = (sessionStatus || '').trim().toLowerCase();
+
+    if (!status) {
+        return {
+            decision: 'rejected',
+            reason: 'unknown_session_status',
+            message: 'Session status is unknown. Delivery rejected (fail-closed). Use mesh_launch_session to start a fresh session.',
+        };
+    }
+
+    if (IMMEDIATE_DELIVERY_STATUSES.has(status)) {
+        return {
+            decision: 'immediate',
+            reason: `session_${status}`,
+            message: `Session is ${status} — delivery allowed immediately.`,
+        };
+    }
+
+    if (BUSY_DELIVERY_STATUSES.has(status)) {
+        if (opts?.allowBusyInjection) {
+            return {
+                decision: 'immediate',
+                reason: `session_${status}_busy_injection_allowed`,
+                message: `Session is ${status} but provider supports busy injection. Delivered immediately.`,
+            };
+        }
+        // approval-kind may be delivered to waiting_approval sessions
+        if (status === 'waiting_approval' && opts?.kind === 'approval') {
+            return {
+                decision: 'immediate',
+                reason: 'session_waiting_approval_approval_message',
+                message: 'Session is waiting for approval — approval message delivered immediately.',
+            };
+        }
+        return {
+            decision: 'queued',
+            reason: `session_${status}_busy`,
+            message: `Session is ${status}. Task queued for delivery when session becomes idle. Do not inject directly into a busy session.`,
+        };
+    }
+
+    if (TERMINAL_DELIVERY_STATUSES.has(status)) {
+        return {
+            decision: 'rejected',
+            reason: `session_${status}_terminal`,
+            message: `Session is ${status} (terminal). Delivery rejected. Launch a new session before dispatching tasks.`,
+        };
+    }
+
+    // Unknown/unrecognized status: fail-closed
+    return {
+        decision: 'rejected',
+        reason: 'unrecognized_session_status',
+        message: `Session status '${sessionStatus}' is not recognized. Delivery rejected (fail-closed). Inspect session state before retrying.`,
+    };
+}
+
+export interface SessionDeliveryRecord {
+    id: string;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    priority: number;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    deliverAfter?: string;
+    expiresAt?: string;
+    attemptCount: number;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Create a delivery record in the store.
+ */
+export function createSessionDelivery(opts: {
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    priority?: number;
+    deliverAfter?: string;
+    expiresAt?: string;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+}): SessionDeliveryRecord {
+    const now = new Date().toISOString();
+    const id = randomUUID();
+    const record: SessionDeliveryRecord = {
+        id,
+        meshId: opts.meshId,
+        nodeId: opts.nodeId,
+        sessionId: opts.sessionId,
+        providerType: opts.providerType,
+        taskId: opts.taskId,
+        kind: opts.kind,
+        priority: opts.priority ?? 0,
+        message: opts.message,
+        status: opts.status,
+        deliverAfter: opts.deliverAfter,
+        expiresAt: opts.expiresAt,
+        attemptCount: 0,
+        sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId,
+        sourceCoordinatorDaemonId: opts.sourceCoordinatorDaemonId,
+        createdAt: now,
+        updatedAt: now,
+    };
+    MeshRuntimeStore.getInstance().insertSessionDelivery({
+        id,
+        meshId: opts.meshId,
+        nodeId: opts.nodeId,
+        sessionId: opts.sessionId,
+        providerType: opts.providerType,
+        taskId: opts.taskId,
+        kind: opts.kind,
+        priority: opts.priority ?? 0,
+        message: opts.message,
+        status: opts.status,
+        deliverAfter: opts.deliverAfter,
+        expiresAt: opts.expiresAt,
+        sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId,
+        sourceCoordinatorDaemonId: opts.sourceCoordinatorDaemonId,
+        createdAt: now,
+        updatedAt: now,
+    });
+    return record;
+}
+
+/**
+ * Update the status of a delivery record.
+ */
+export function updateSessionDeliveryStatus(
+    id: string,
+    status: MeshSessionDeliveryStatus,
+    opts?: { lastError?: string; incrementAttempt?: boolean },
+): void {
+    try {
+        MeshRuntimeStore.getInstance().updateSessionDeliveryStatus(id, status, opts);
+    } catch { /* best-effort */ }
+}
+
+/**
+ * Get active (non-terminal) deliveries for a mesh, optionally filtered by session.
+ */
+export function getActiveSessionDeliveries(meshId: string, sessionId?: string) {
+    try {
+        return MeshRuntimeStore.getInstance().getActiveSessionDeliveries(meshId, sessionId);
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Record a completion conflict diagnostic when a duplicate event points to
+ * different task/session than the already-seen event with the same fingerprint.
+ */
+export function recordCompletionConflict(opts: {
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId?: string;
+    conflictingSessionId?: string;
+    originalTaskId?: string;
+    originalSessionId?: string;
+    event: string;
+}): void {
+    try {
+        MeshRuntimeStore.getInstance().recordCompletionConflict({
+            id: randomUUID(),
+            meshId: opts.meshId,
+            fingerprint: opts.fingerprint,
+            conflictingTaskId: opts.conflictingTaskId,
+            conflictingSessionId: opts.conflictingSessionId,
+            originalTaskId: opts.originalTaskId,
+            originalSessionId: opts.originalSessionId,
+            event: opts.event,
+            createdAt: new Date().toISOString(),
+        });
+    } catch { /* best-effort diagnostics */ }
+}
+
+/**
+ * Get recent completion conflicts for diagnostic inspection.
+ */
+export function getRecentCompletionConflicts(meshId: string, limitMs?: number) {
+    try {
+        return MeshRuntimeStore.getInstance().getRecentCompletionConflicts(meshId, limitMs);
+    } catch {
+        return [];
+    }
+}
+
+export function __clearSessionDeliveriesForTests(meshId: string): void {
+    MeshRuntimeStore.getInstance().deleteSessionDeliveries(meshId);
+}
+
+/**
+ * Mark all active (queued/delivering/delivered/acked) deliveries for a session as completed or failed.
+ * Called when a task's terminal status is confirmed so delivery records stay in sync.
+ */
+export function markSessionDeliveriesTerminal(
+    meshId: string,
+    sessionId: string,
+    terminalStatus: 'completed' | 'failed',
+): void {
+    try {
+        const active = MeshRuntimeStore.getInstance().getActiveSessionDeliveries(meshId, sessionId);
+        for (const delivery of active) {
+            MeshRuntimeStore.getInstance().updateSessionDeliveryStatus(delivery.id, terminalStatus);
+        }
+    } catch { /* best-effort */ }
+}

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

@@ -0,0 +1,51 @@
+import type { MeshLedgerKind } from './mesh-ledger.js';
+
+// ---------------------------------------------------------------------------
+// Core event injection
+// ---------------------------------------------------------------------------
+
+const MESH_COORDINATOR_EVENTS = new Set([
+    'agent:generating_started',
+    'agent:generating_completed',
+    'agent:waiting_approval',
+    'agent:stopped',
+    'agent:ready',
+    'monitor:no_progress',
+    'refine:accepted',
+    'refine:completed',
+    'refine:failed',
+    'worktree_bootstrap_complete',
+    'worktree_bootstrap_failed',
+]);
+
+export const EVENT_TO_LEDGER_KIND: Record<string, MeshLedgerKind> = {
+    'agent:generating_completed': 'task_completed',
+    'agent:waiting_approval': 'task_approval_needed',
+    'agent:stopped': 'task_failed',
+    'monitor:no_progress': 'task_stalled',
+};
+
+export function isMeshCoordinatorEvent(eventName: unknown): eventName is string {
+    return typeof eventName === 'string' && MESH_COORDINATOR_EVENTS.has(eventName);
+}
+
+// Terminal events that the coordinator is actively blocked waiting on. When the
+// coordinator CLI session dispatches a task (e.g. mesh_send_task) it stays in
+// `generating` until the result arrives — but a generating coordinator queues
+// incoming send_message calls into its adapter's pendingOutboundQueue, which is
+// only flushed on the coordinator's OWN idle transition. That transition can't
+// happen until it receives this very event → deadlock. We force-inject these so
+// they bypass the busy send-guard and land in the PTY while generating.
+export const MESH_FORCE_INJECT_EVENTS: ReadonlySet<string> = new Set([
+    'agent:generating_completed',
+    'agent:stopped',
+    'agent:waiting_approval',
+    'refine:completed',
+    'refine:failed',
+    'worktree_bootstrap_complete',
+    'worktree_bootstrap_failed',
+]);
+
+export function shouldForceInjectMeshEvent(eventName: unknown): boolean {
+    return typeof eventName === 'string' && MESH_FORCE_INJECT_EVENTS.has(eventName);
+}