@adhdev/daemon-core 0.9.82-rc.47 → 0.9.82-rc.49

package/src/commands/router.ts

@@ -39,6 +39,16 @@ import { getSessionHostSurfaceKind, partitionSessionHostRecords } from '../sessi
 import { createHermesManualMeshCoordinatorSetup, resolveMeshCoordinatorSetup } from './mesh-coordinator.js';
 import { buildSessionEntries } from '../status/builders.js';
 import { handleMeshForwardEvent, drainPendingMeshCoordinatorEvents } from '../mesh/mesh-events.js';
+import { buildMeshHostRequiredFailure, normalizeMeshDaemonRole, resolveMeshHostStatus } from '../mesh/mesh-host-ownership.js';
+import {
+    MESH_REFINE_CONFIG_LOCATIONS,
+    MESH_REFINE_CONFIG_SCHEMA,
+    loadMeshRefineConfig,
+    resolveMeshRefineValidationPlan,
+    suggestMeshRefineConfig,
+    validateMeshRefineConfig,
+    type MeshRefineValidationCommandPlan,
+} from '../mesh/refine-config.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
 import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
@@ -859,13 +869,7 @@ async function resolveProviderTypeFromPriority(args: {
 }
 type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
 type MeshRefineValidationStatus = 'passed' | 'failed' | 'skipped';
-type MeshRefineValidationCommand = {
-    command: string;
-    args: string[];
-    displayCommand: string;
-    category: string;
-    source: string;
-};
+type MeshRefineValidationCommand = MeshRefineValidationCommandPlan;
 
 type MeshRefineValidationSummary = {
     status: MeshRefineValidationStatus;
@@ -875,6 +879,10 @@ type MeshRefineValidationSummary = {
     skippedReason?: string;
     timeoutMs: number;
     outputLimitBytes: number;
+    configSource?: string;
+    configSourceType?: string;
+    suggestions?: unknown[];
+    suggestedConfig?: unknown;
 };
 
 type MeshRefineStageStatus = 'passed' | 'failed' | 'skipped';
@@ -996,171 +1004,25 @@ async function runMeshRefinePatchEquivalenceGate(
     }
 }
 
-function readPackageScripts(workspace: string): Record<string, string> {
-    try {
-        const packageJsonPath = pathJoin(workspace, 'package.json');
-        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        return parsed?.scripts && typeof parsed.scripts === 'object' && !Array.isArray(parsed.scripts)
-            ? parsed.scripts as Record<string, string>
-            : {};
-    } catch {
-        return {};
-    }
-}
-
-function tokenizeValidationCommand(command: string): string[] | null {
-    const trimmed = command.trim();
-    if (!trimmed) return null;
-    // Fail closed: the gate never hands shell syntax to a shell. Package-manager
-    // scripts are invoked via execFile(binary, args), and metacharacters/quotes are
-    // rejected before tokenization so `npm run test && rm -rf` cannot be smuggled in.
-    if (/[;&|<>`$\\\n\r'\"]/.test(trimmed)) return null;
-    const tokens = trimmed.split(/\s+/).filter(Boolean);
-    if (!tokens.length) return null;
-    if (tokens.some(token => !/^[A-Za-z0-9_@./:=+-]+$/.test(token))) return null;
-    return tokens;
-}
-
-function scriptMatchesValidationCategory(scriptName: string, category: string): boolean {
-    return scriptName === category || scriptName.startsWith(`${category}:`);
-}
-
-function parsePackageManagerValidationCommand(
-    rawCommand: string,
-    category: string,
-    scripts: Record<string, string>,
-    source: string,
-): { command?: MeshRefineValidationCommand; rejected?: Record<string, unknown> } {
-    const tokens = tokenizeValidationCommand(rawCommand);
-    if (!tokens) {
-        return { rejected: { command: rawCommand, category, source, reason: 'unsafe command string is not allowlisted' } };
-    }
-
-    const [binary, second, third, ...rest] = tokens;
-    let scriptName = '';
-    let command = binary;
-    let args: string[] = [];
-
-    if ((binary === 'npm' || binary === 'pnpm' || binary === 'bun') && second === 'run' && third) {
-        scriptName = third;
-        args = ['run', scriptName, ...rest];
-    } else if (binary === 'npm' && second === 'test' && !third) {
-        scriptName = 'test';
-        args = ['test'];
-    } else if (binary === 'yarn' && second === 'run' && third) {
-        scriptName = third;
-        args = ['run', scriptName, ...rest];
-    } else if (binary === 'yarn' && second && !third) {
-        scriptName = second;
-        args = [scriptName];
-    } else {
-        return { rejected: { command: rawCommand, category, source, reason: 'command is not a supported package-manager script invocation' } };
-    }
-
-    if (!scriptName || !Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
-        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script is not declared in package.json' } };
-    }
-    if (!scriptMatchesValidationCategory(scriptName, category)) {
-        return { rejected: { command: rawCommand, category, source, script: scriptName, reason: 'script name is outside the validation category allowlist' } };
-    }
-
+function buildMeshRefineValidationPlan(mesh: any, workspace: string): Record<string, unknown> {
+    const plan = resolveMeshRefineValidationPlan(mesh, workspace);
     return {
-        command: {
-            command,
-            args,
-            displayCommand: [command, ...args].join(' '),
-            category,
-            source,
-        },
-    };
-}
-
-function collectProjectContextValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string; confidence?: string }> {
-    const commands = mesh?.projectContext?.commands;
-    if (!commands || typeof commands !== 'object' || Array.isArray(commands)) return [];
-    const candidates: Array<{ command: string; category: string; source: string; confidence?: string }> = [];
-    for (const category of REFINE_VALIDATION_CATEGORIES) {
-        const entries = Array.isArray(commands[category]) ? commands[category] : [];
-        for (const entry of entries) {
-            if (typeof entry?.command !== 'string') continue;
-            candidates.push({
-                command: entry.command,
-                category,
-                source: typeof entry.sourcePath === 'string' ? entry.sourcePath : 'projectContext.commands',
-                confidence: typeof entry.confidence === 'string' ? entry.confidence : undefined,
-            });
-        }
-    }
-    return candidates.sort((a, b) => {
-        const rank = (value?: string) => value === 'high' ? 0 : value === 'medium' ? 1 : 2;
-        return rank(a.confidence) - rank(b.confidence);
-    });
-}
-
-function collectPolicyValidationCandidates(mesh: any): Array<{ command: string; category: string; source: string }> {
-    const policy = mesh?.policy && typeof mesh.policy === 'object' && !Array.isArray(mesh.policy) ? mesh.policy : {};
-    const configured = Array.isArray(policy.validationCommands)
-        ? policy.validationCommands
-        : Array.isArray(policy.validationGate?.commands)
-            ? policy.validationGate.commands
-            : [];
-    return configured
-        .map((entry: any) => typeof entry === 'string' ? { command: entry, category: '', source: 'mesh.policy.validationCommands' } : entry)
-        .filter((entry: any) => entry && typeof entry.command === 'string')
-        .map((entry: any) => {
-            const commandText = entry.command.trim();
-            const category = REFINE_VALIDATION_CATEGORIES.find(cat => commandText.includes(` ${cat}`)) ?? '';
-            return { command: commandText, category, source: 'mesh.policy.validationCommands' };
-        })
-        .filter((entry: any) => !!entry.category);
-}
-
-function selectMeshRefineValidationCommands(mesh: any, workspace: string): { commands: MeshRefineValidationCommand[]; rejectedCommands: Array<Record<string, unknown>>; source: string } {
-    const scripts = readPackageScripts(workspace);
-    const rejectedCommands: Array<Record<string, unknown>> = [];
-    const selected: MeshRefineValidationCommand[] = [];
-    const seen = new Set<string>();
-    const candidates = [
-        ...collectPolicyValidationCandidates(mesh),
-        ...collectProjectContextValidationCandidates(mesh),
-    ];
-
-    for (const candidate of candidates) {
-        const parsed = parsePackageManagerValidationCommand(candidate.command, candidate.category, scripts, candidate.source);
-        if (parsed.rejected) {
-            rejectedCommands.push(parsed.rejected);
-            continue;
-        }
-        if (!parsed.command || seen.has(parsed.command.displayCommand)) continue;
-        selected.push(parsed.command);
-        seen.add(parsed.command.displayCommand);
-        if (selected.length >= REFINE_VALIDATION_MAX_COMMANDS) break;
-    }
-
-    if (!selected.length && candidates.length === 0) {
-        for (const category of REFINE_VALIDATION_CATEGORIES) {
-            if (!Object.prototype.hasOwnProperty.call(scripts, category)) continue;
-            const fallback = parsePackageManagerValidationCommand(`npm run ${category}`, category, scripts, 'package.json:scripts');
-            if (fallback.command && !seen.has(fallback.command.displayCommand)) {
-                selected.push(fallback.command);
-                seen.add(fallback.command.displayCommand);
-            } else if (fallback.rejected) {
-                rejectedCommands.push(fallback.rejected);
-            }
-            if (selected.length >= 2) break;
-        }
-    }
-
-    return {
-        commands: selected,
-        rejectedCommands,
-        source: selected.some(command => command.source === 'mesh.policy.validationCommands')
-            ? 'mesh_policy'
-            : selected.some(command => command.source !== 'package.json:scripts')
-                ? 'project_context'
-                : selected.length
-                    ? 'package_json_scripts'
-                    : 'unavailable',
+        source: plan.source,
+        sourceType: plan.sourceType,
+        commands: plan.commands.map(command => ({
+            displayCommand: command.displayCommand,
+            category: command.category,
+            source: command.source,
+            cwd: command.cwd,
+            timeoutMs: command.timeoutMs,
+        })),
+        unavailableReason: plan.unavailableReason,
+        rejectedCommands: plan.rejectedCommands,
+        suggestions: plan.suggestions,
+        suggestedConfig: plan.suggestedConfig,
+        note: plan.sourceType === 'unavailable'
+            ? 'No validation command will be executed until a repo mesh/refine config is provided. Heuristics are suggestions only.'
+            : 'Validation commands are resolved from repo mesh/refine config; heuristics are suggestions only.',
     };
 }
 
@@ -1168,7 +1030,7 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     const execFileAsync = promisify(execFile);
-    const selection = selectMeshRefineValidationCommands(mesh, workspace);
+    const selection = resolveMeshRefineValidationPlan(mesh, workspace);
     const summary: MeshRefineValidationSummary = {
         status: 'skipped',
         required: true,
@@ -1177,22 +1039,28 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
         skippedReason: undefined,
         timeoutMs: REFINE_VALIDATION_TIMEOUT_MS,
         outputLimitBytes: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
+        configSource: selection.source,
+        configSourceType: selection.sourceType,
+        suggestions: selection.suggestions,
+        suggestedConfig: selection.suggestedConfig,
     };
 
     if (!selection.commands.length) {
-        summary.skippedReason = 'validation_unavailable: no allowlisted projectContext, mesh policy, or package.json build/test/typecheck/lint command was available';
+        summary.skippedReason = selection.unavailableReason || 'validation_unavailable: repo mesh/refine config did not provide executable validation.commands';
         return summary;
     }
 
     for (const candidate of selection.commands) {
         const startedAt = Date.now();
+        const cwd = candidate.cwd ? pathResolve(workspace, candidate.cwd) : workspace;
+        const timeout = candidate.timeoutMs || REFINE_VALIDATION_TIMEOUT_MS;
         try {
             const result = await execFileAsync(candidate.command, candidate.args, {
-                cwd: workspace,
+                cwd,
                 encoding: 'utf8',
-                timeout: REFINE_VALIDATION_TIMEOUT_MS,
+                timeout,
                 maxBuffer: REFINE_VALIDATION_OUTPUT_LIMIT_BYTES,
-                env: { ...process.env, CI: process.env.CI || '1' },
+                env: { ...process.env, CI: process.env.CI || '1', ...(candidate.env || {}) },
             });
             summary.commandsRun.push({
                 command: candidate.command,
@@ -1200,6 +1068,7 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
                 displayCommand: candidate.displayCommand,
                 category: candidate.category,
                 source: candidate.source,
+                cwd,
                 passed: true,
                 exitCode: 0,
                 durationMs: Date.now() - startedAt,
@@ -1213,6 +1082,7 @@ async function runMeshRefineValidationGate(mesh: any, workspace: string): Promis
                 displayCommand: candidate.displayCommand,
                 category: candidate.category,
                 source: candidate.source,
+                cwd,
                 passed: false,
                 exitCode: typeof error?.code === 'number' ? error.code : null,
                 signal: typeof error?.signal === 'string' ? error.signal : null,
@@ -1466,6 +1336,50 @@ function summarizeSessionHostPruneResult(result: unknown): Record<string, unknow
     };
 }
 
+function normalizeStandaloneHostCommandUrl(hostAddress: string): string {
+    const raw = hostAddress.trim();
+    if (!raw) throw new Error('hostAddress required');
+    const url = new URL(raw.replace(/^ws:/, 'http:').replace(/^wss:/, 'https:'));
+    url.pathname = '/api/v1/command';
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+
+function buildMemberJoinNode(mesh: any, args: any, fallbackDaemonId?: string): Record<string, unknown> | null {
+    const requestedNodeId = typeof args?.memberNodeId === 'string' ? args.memberNodeId.trim() : '';
+    const explicit = args?.memberNode && typeof args.memberNode === 'object' && !Array.isArray(args.memberNode)
+        ? args.memberNode as Record<string, any>
+        : null;
+    const configured = Array.isArray(mesh?.nodes)
+        ? (requestedNodeId
+            ? mesh.nodes.find((node: any) => node?.id === requestedNodeId || node?.nodeId === requestedNodeId)
+            : mesh.nodes[0])
+        : null;
+    const source = explicit || configured;
+    const workspace = typeof source?.workspace === 'string' && source.workspace.trim()
+        ? source.workspace.trim()
+        : typeof args?.workspace === 'string' && args.workspace.trim()
+            ? args.workspace.trim()
+            : process.cwd();
+    if (!workspace) return null;
+    const nodeId = typeof source?.id === 'string' && source.id.trim()
+        ? source.id.trim()
+        : typeof source?.nodeId === 'string' && source.nodeId.trim()
+            ? source.nodeId.trim()
+            : undefined;
+    return {
+        ...(nodeId ? { id: nodeId } : {}),
+        workspace,
+        ...(typeof source?.repoRoot === 'string' && source.repoRoot.trim() ? { repoRoot: source.repoRoot.trim() } : {}),
+        ...(typeof source?.daemonId === 'string' && source.daemonId.trim() ? { daemonId: source.daemonId.trim() } : fallbackDaemonId ? { daemonId: fallbackDaemonId } : {}),
+        ...(typeof source?.machineId === 'string' && source.machineId.trim() ? { machineId: source.machineId.trim() } : {}),
+        userOverrides: source?.userOverrides && typeof source.userOverrides === 'object' && !Array.isArray(source.userOverrides) ? source.userOverrides : {},
+        policy: source?.policy && typeof source.policy === 'object' && !Array.isArray(source.policy) ? source.policy : {},
+        role: 'member',
+    };
+}
+
 export class DaemonCommandRouter {
     private deps: CommandRouterDeps;
     /** In-memory cache for cloud-originating meshes passed via inlineMesh.
@@ -1661,6 +1575,18 @@ export class DaemonCommandRouter {
         this.aggregateMeshStatusCache.delete(meshId);
     }
 
+
+    private async requireMeshHostMutationOwner(meshId: string, inlineMesh: unknown, operation: string): Promise<CommandRouterResult | null> {
+        const meshRecord = await this.getMeshForCommand(meshId, inlineMesh, { preferInline: true });
+        const mesh = meshRecord?.mesh;
+        if (!mesh) return { success: false, error: 'Mesh not found' };
+        const meshHost = resolveMeshHostStatus(mesh);
+        if (!meshHost.canOwnCoordinator || !meshHost.canOwnQueue) {
+            return { ...buildMeshHostRequiredFailure(mesh, operation), success: false, meshId };
+        }
+        return null;
+    }
+
     private updateInlineMeshNode(meshId: string, mesh: any, node: any): void {
         if (!mesh || !Array.isArray(mesh.nodes) || !node?.id) return;
         const idx = mesh.nodes.findIndex((entry: any) => entry?.id === node.id || entry?.nodeId === node.id);
@@ -2876,7 +2802,10 @@ export class DaemonCommandRouter {
                 if (!name) return { success: false, error: 'name required' };
                 try {
                     const { createMesh } = await import('../config/mesh-config.js');
-                    const mesh = createMesh({ name, repoIdentity, repoRemoteUrl, defaultBranch, policy: args?.policy });
+                    const meshHost = args?.meshHost && typeof args.meshHost === 'object' && !Array.isArray(args.meshHost)
+                        ? args.meshHost
+                        : undefined;
+                    const mesh = createMesh({ name, repoIdentity, repoRemoteUrl, defaultBranch, policy: args?.policy, meshHost });
                     return { success: true, mesh };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -2893,6 +2822,7 @@ export class DaemonCommandRouter {
                     if (typeof args?.defaultBranch === 'string') patch.defaultBranch = args.defaultBranch;
                     if (args?.policy && typeof args.policy === 'object' && !Array.isArray(args.policy)) patch.policy = args.policy;
                     if (args?.coordinator && typeof args.coordinator === 'object' && !Array.isArray(args.coordinator)) patch.coordinator = args.coordinator;
+                    if (args?.meshHost && typeof args.meshHost === 'object' && !Array.isArray(args.meshHost)) patch.meshHost = args.meshHost;
                     if (!Object.keys(patch).length) return { success: false, error: 'No updates provided' };
                     const mesh = updateMesh(meshId, patch as any);
                     if (!mesh) return { success: false, error: 'Mesh not found' };
@@ -2904,6 +2834,225 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'get_mesh_host_pairing': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                const mesh = meshRecord?.mesh;
+                if (!mesh) return { success: false, error: 'Mesh not found' };
+                const meshHost = resolveMeshHostStatus(mesh);
+                const pairingStatus = meshHost.pairing?.status || 'not_configured';
+                return {
+                    success: true,
+                    code: pairingStatus === 'not_configured' ? 'mesh_host_pairing_not_configured' : 'mesh_host_pairing_pending',
+                    meshId,
+                    hostAddress: meshHost.hostAddress,
+                    meshHost,
+                    manualPairing: {
+                        status: pairingStatus,
+                        joinImplemented: true,
+                        protocol: 'standalone_command_direct_v1',
+                        description: 'Standalone manual pairing can save address/token metadata, apply a host join over direct standalone command HTTP or injected mesh command dispatch, and check persisted status. P2P signaling remains outside this slice.',
+                    },
+                };
+            }
+
+            case 'configure_mesh_host_pairing': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const hostAddress = typeof args?.hostAddress === 'string' ? args.hostAddress.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!hostAddress || !token) return { success: false, error: 'hostAddress and token required' };
+                try {
+                    const { configureMeshHostPairing } = await import('../config/mesh-config.js');
+                    const configured = configureMeshHostPairing(meshId, { hostAddress, token });
+                    if (!configured) return { success: false, error: 'Mesh not found' };
+                    this.inlineMeshCache.set(meshId, configured.mesh);
+                    const meshHost = resolveMeshHostStatus(configured.mesh);
+                    return {
+                        success: true,
+                        code: 'mesh_host_pairing_pending',
+                        meshId,
+                        hostAddress: configured.hostAddress,
+                        meshHost,
+                        manualPairing: {
+                            status: meshHost.pairing?.status || 'pairing',
+                            joinImplemented: true,
+                            protocol: 'standalone_command_direct_v1',
+                            description: 'Manual Mesh Host pairing config was saved locally. Use join_mesh_host_pairing to apply it to the host. Raw token was not persisted.',
+                        },
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_pairing_invalid', meshId, hostAddress, error: e.message };
+                }
+            }
+
+            case 'create_mesh_host_pairing_token': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                try {
+                    const { createMeshHostPairingToken } = await import('../config/mesh-config.js');
+                    const created = createMeshHostPairingToken(meshId, {
+                        token: typeof args?.token === 'string' ? args.token : undefined,
+                        expiresAt: typeof args?.expiresAt === 'string' ? args.expiresAt : undefined,
+                    });
+                    if (!created) return { success: false, error: 'Mesh not found' };
+                    this.inlineMeshCache.set(meshId, created.mesh);
+                    this.invalidateAggregateMeshStatus(meshId);
+                    return {
+                        success: true,
+                        code: 'mesh_host_pairing_token_created',
+                        meshId,
+                        token: created.token,
+                        tokenId: created.tokenId,
+                        expiresAt: created.expiresAt,
+                        meshHost: resolveMeshHostStatus(created.mesh),
+                        warning: 'Raw token is returned once and is not persisted; share it with member daemons over a trusted channel.',
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_pairing_token_invalid', meshId, error: e.message };
+                }
+            }
+
+            case 'apply_mesh_host_join': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
+                const memberNode = args?.memberNode && typeof args.memberNode === 'object' && !Array.isArray(args.memberNode)
+                    ? args.memberNode
+                    : null;
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!token || !memberNode) return { success: false, error: 'token and memberNode required' };
+                try {
+                    const { applyMeshHostJoinRequest } = await import('../config/mesh-config.js');
+                    const applied = applyMeshHostJoinRequest(meshId, {
+                        token,
+                        memberNode: memberNode as any,
+                        memberMeshId: typeof args?.memberMeshId === 'string' ? args.memberMeshId : undefined,
+                    });
+                    if (!applied) return { success: false, error: 'Mesh not found' };
+                    if (!applied.accepted) {
+                        return {
+                            success: false,
+                            code: 'mesh_host_join_rejected',
+                            meshId,
+                            tokenId: applied.tokenId,
+                            meshHost: applied.meshHost ? resolveMeshHostStatus({ meshHost: applied.meshHost }) : undefined,
+                            error: applied.reason,
+                        };
+                    }
+                    this.inlineMeshCache.set(meshId, applied.mesh);
+                    this.invalidateAggregateMeshStatus(meshId);
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'node_joined',
+                            nodeId: applied.node.id,
+                            payload: { role: 'member', tokenId: applied.tokenId, workspace: applied.node.workspace },
+                        });
+                    } catch { /* ledger append is best-effort */ }
+                    return {
+                        success: true,
+                        code: 'mesh_host_join_accepted',
+                        meshId,
+                        node: applied.node,
+                        tokenId: applied.tokenId,
+                        meshHost: resolveMeshHostStatus(applied.mesh),
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_join_failed', meshId, error: e.message };
+                }
+            }
+
+            case 'join_mesh_host_pairing': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const token = typeof args?.token === 'string' ? args.token.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                if (!token) return { success: false, error: 'token required because raw pairing tokens are not persisted' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
+                const mesh = meshRecord?.mesh;
+                if (!mesh) return { success: false, error: 'Mesh not found' };
+                const meshHost = resolveMeshHostStatus(mesh);
+                if (meshHost.role !== 'member') {
+                    return { success: false, code: 'mesh_host_join_not_member', meshId, meshHost, error: 'join_mesh_host_pairing must run from a member daemon configured with a Mesh Host address/token.' };
+                }
+                try {
+                    const { tokenIdForManualPairing, markMeshHostPairingJoined } = await import('../config/mesh-config.js');
+                    const tokenId = tokenIdForManualPairing(token);
+                    if (meshHost.pairing?.tokenId && meshHost.pairing.tokenId !== tokenId) {
+                        return { success: false, code: 'mesh_host_join_rejected', meshId, tokenId, meshHost, error: 'invalid pairing token' };
+                    }
+                    const memberNode = buildMemberJoinNode(mesh, args, this.deps.statusInstanceId);
+                    if (!memberNode) return { success: false, error: 'member node metadata unavailable' };
+                    const hostMeshId = typeof args?.hostMeshId === 'string' && args.hostMeshId.trim() ? args.hostMeshId.trim() : meshId;
+                    const hostDaemonId = typeof args?.hostDaemonId === 'string' && args.hostDaemonId.trim()
+                        ? args.hostDaemonId.trim()
+                        : meshHost.hostDaemonId;
+                    let hostResult: any;
+                    let transport: string;
+                    if (hostDaemonId && this.deps.dispatchMeshCommand) {
+                        transport = 'mesh_command_dispatch';
+                        hostResult = await this.deps.dispatchMeshCommand(hostDaemonId, 'apply_mesh_host_join', {
+                            meshId: hostMeshId,
+                            token,
+                            memberMeshId: meshId,
+                            memberNode,
+                        });
+                    } else if (meshHost.hostAddress) {
+                        transport = 'standalone_http_command';
+                        const commandUrl = normalizeStandaloneHostCommandUrl(meshHost.hostAddress);
+                        const response = await fetch(commandUrl, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ type: 'apply_mesh_host_join', payload: { meshId: hostMeshId, token, memberMeshId: meshId, memberNode } }),
+                        });
+                        hostResult = await response.json().catch(() => ({ success: false, error: `Host returned HTTP ${response.status}` }));
+                        if (!response.ok && hostResult?.success !== false) hostResult = { success: false, error: `Host returned HTTP ${response.status}` };
+                    } else {
+                        return {
+                            success: false,
+                            code: 'mesh_host_join_transport_unavailable',
+                            meshId,
+                            meshHost,
+                            error: 'No hostDaemonId dispatch path or hostAddress HTTP command path is available. P2P signaling join is not implemented in this slice.',
+                        };
+                    }
+                    if (!hostResult?.success) {
+                        return { success: false, code: hostResult?.code || 'mesh_host_join_rejected', meshId, meshHost, transport, error: hostResult?.error || 'Mesh Host rejected join request', hostResult };
+                    }
+                    const joined = meshRecord.inline
+                        ? null
+                        : markMeshHostPairingJoined(meshId, {
+                            tokenId: hostResult.tokenId || tokenId,
+                            hostDaemonId: hostResult.meshHost?.hostDaemonId || hostDaemonId,
+                            hostNodeId: hostResult.meshHost?.hostNodeId,
+                            joinedAt: hostResult.meshHost?.pairing?.joinedAt,
+                        });
+                    if (joined) {
+                        this.inlineMeshCache.set(meshId, joined.mesh);
+                        this.invalidateAggregateMeshStatus(meshId);
+                    }
+                    return {
+                        success: true,
+                        code: 'mesh_host_join_applied',
+                        meshId,
+                        hostMeshId,
+                        transport,
+                        node: hostResult.node,
+                        tokenId: hostResult.tokenId || tokenId,
+                        meshHost: joined ? resolveMeshHostStatus(joined.mesh) : { ...meshHost, pairing: { ...(meshHost.pairing || {}), status: 'paired', tokenId: hostResult.tokenId || tokenId } },
+                        hostResult,
+                        manualPairing: {
+                            status: 'paired',
+                            joinImplemented: true,
+                            protocol: 'standalone_command_direct_v1',
+                            description: 'Mesh Host accepted the join and local member pairing status was marked paired. P2P runtime signaling remains outside this slice.',
+                        },
+                    };
+                } catch (e: any) {
+                    return { success: false, code: 'mesh_host_join_failed', meshId, meshHost, error: e.message };
+                }
+            }
+
             case 'delete_mesh': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
@@ -2997,6 +3146,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
                 if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue cancellation');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { cancelTask } = await import('../mesh/mesh-work-queue.js');
                     const reason = typeof args?.reason === 'string' ? args.reason : undefined;
@@ -3012,6 +3163,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const taskId = typeof args?.taskId === 'string' ? args.taskId.trim() : '';
                 if (!meshId || !taskId) return { success: false, error: 'meshId and taskId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue requeue');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { requeueTask } = await import('../mesh/mesh-work-queue.js');
                     const task = requeueTask(meshId, taskId, {
@@ -3033,6 +3186,8 @@ export class DaemonCommandRouter {
                 const workspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
                 if (!workspace) return { success: false, error: 'workspace required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node addition');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { addNode } = await import('../config/mesh-config.js');
                     const providerPriority = Array.isArray(args?.providerPriority)
@@ -3043,7 +3198,8 @@ export class DaemonCommandRouter {
                         ...(readOnly ? { readOnly: true } : {}),
                         ...(providerPriority.length ? { providerPriority } : {}),
                     };
-                    const node = addNode(meshId, { workspace, ...(policy ? { policy } : {}) });
+                    const role = normalizeMeshDaemonRole(args?.role);
+                    const node = addNode(meshId, { workspace, ...(policy ? { policy } : {}), ...(role ? { role } : {}) });
                     if (!node) return { success: false, error: 'Mesh not found' };
                     return { success: true, node };
                 } catch (e: any) {
@@ -3055,6 +3211,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
                 if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node update');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { updateNode } = await import('../config/mesh-config.js');
                     const policy = args?.policy && typeof args.policy === 'object' && !Array.isArray(args.policy)
@@ -3083,6 +3241,8 @@ export class DaemonCommandRouter {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
                 if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'node removal');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
                     const mesh = meshRecord?.mesh;
@@ -3108,6 +3268,57 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'get_mesh_refine_config_schema': {
+                return {
+                    success: true,
+                    schema: MESH_REFINE_CONFIG_SCHEMA,
+                    locations: MESH_REFINE_CONFIG_LOCATIONS,
+                    sourceOfTruth: 'repo mesh/refine config',
+                    heuristicRole: 'suggestions_only_not_execution_path',
+                };
+            }
+
+            case 'validate_mesh_refine_config': {
+                const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+                const mesh = args?.inlineMesh || {};
+                const loaded = args?.config !== undefined
+                    ? { config: args.config, source: 'inline', sourceType: 'mesh_policy' as const }
+                    : loadMeshRefineConfig(mesh, workspace);
+                const validation = loaded.config
+                    ? validateMeshRefineConfig(loaded.config, loaded.source)
+                    : { valid: false, errors: [((loaded as { error?: string }).error) || 'repo mesh/refine config unavailable'], commands: [], rejectedCommands: [] };
+                return { success: validation.valid, ...loaded, ...validation };
+            }
+
+            case 'suggest_mesh_refine_config': {
+                const workspace = typeof args?.workspace === 'string' ? args.workspace : process.cwd();
+                const mesh = args?.inlineMesh || {};
+                return {
+                    success: true,
+                    ...suggestMeshRefineConfig(mesh, workspace),
+                    note: 'Suggestions are heuristic scaffold only; Refinery will not execute them until saved into repo mesh/refine config.',
+                };
+            }
+
+            case 'plan_mesh_refine_node': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+                if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+                const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
+                const mesh = meshRecord?.mesh;
+                const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
+                if (!node?.workspace) return { success: false, error: `Node '${nodeId}' workspace not found` };
+                return {
+                    success: true,
+                    dryRun: true,
+                    nodeId,
+                    workspace: node.workspace,
+                    validationPlan: buildMeshRefineValidationPlan(mesh, node.workspace),
+                    mergeWillRun: false,
+                    cleanupWillRun: false,
+                };
+            }
+
             case 'refine_mesh_node': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
@@ -3415,6 +3626,8 @@ export class DaemonCommandRouter {
                 if (!meshId) return { success: false, error: 'meshId required' };
                 if (!sourceNodeId) return { success: false, error: 'sourceNodeId required' };
                 if (!branch) return { success: false, error: 'branch required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'worktree clone');
+                if (ownerFailure) return ownerFailure;
 
                 try {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
@@ -3505,6 +3718,8 @@ export class DaemonCommandRouter {
             case 'trigger_mesh_queue': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 if (!meshId) return { success: false, error: 'meshId required' };
+                const ownerFailure = await this.requireMeshHostMutationOwner(meshId, args?.inlineMesh, 'queue trigger');
+                if (ownerFailure) return ownerFailure;
                 try {
                     const { triggerMeshQueue } = await import('../mesh/mesh-events.js');
                     if (meshId) {
@@ -3536,6 +3751,15 @@ export class DaemonCommandRouter {
                         mesh = getMesh(meshId);
                     }
                     if (!mesh) return { success: false, error: 'Mesh not found' };
+                    const meshHost = resolveMeshHostStatus(mesh);
+                    if (!meshHost.canOwnCoordinator) {
+                        return {
+                            success: false,
+                            ...buildMeshHostRequiredFailure(mesh, 'coordinator launch'),
+                            meshId,
+                            cliType,
+                        };
+                    }
                     if (!Array.isArray(mesh.nodes) || mesh.nodes.length === 0) return { success: false, error: 'No nodes in mesh' };
 
                     const requestedCoordinatorNodeId = typeof args?.coordinatorNodeId === 'string'
@@ -3909,6 +4133,7 @@ export class DaemonCommandRouter {
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
                     const mesh = meshRecord?.mesh;
                     if (!mesh) return { success: false, error: 'Mesh not found' };
+                    const meshHost = resolveMeshHostStatus(mesh);
 
                     const refreshRequested = args?.refresh === true || args?.forceRefresh === true;
                     const hadAggregateCache = this.aggregateMeshStatusCache.has(meshId);
@@ -4030,6 +4255,7 @@ export class DaemonCommandRouter {
                             repoRoot: node.repoRoot,
                             isLocalWorktree: node.isLocalWorktree,
                             worktreeBranch: node.worktreeBranch,
+                            role: normalizeMeshDaemonRole(node.role) || (meshHost.hostNodeId && nodeId === meshHost.hostNodeId ? 'host' : undefined),
                             daemonId,
                             machineId: node.machineId,
                             machineStatus: node.machineStatus,
@@ -4230,6 +4456,7 @@ export class DaemonCommandRouter {
                         repoIdentity: mesh.repoIdentity,
                         defaultBranch: mesh.defaultBranch,
                         refreshedAt,
+                        meshHost,
                         sourceOfTruth: {
                             membership: meshRecord?.source === 'inline_cache'
                                 ? 'coordinator_inline_mesh_cache'
@@ -4237,6 +4464,13 @@ export class DaemonCommandRouter {
                                     ? 'local_mesh_config'
                                     : 'inline_bootstrap_snapshot',
                             coordinatorOwnsLiveTruth: directTruthSatisfied,
+                            meshHost: {
+                                owner: 'mesh_host_daemon',
+                                localRole: meshHost.role,
+                                hostDaemonId: meshHost.hostDaemonId,
+                                hostNodeId: meshHost.hostNodeId,
+                                hostAddress: meshHost.hostAddress,
+                            },
                             ...(requireDirectPeerTruth ? {
                                 currentStatus: directTruthSatisfied ? 'live_git_and_session_probes' : 'direct_peer_truth_unavailable',
                                 directPeerTruth: {