@adhdev/daemon-core 0.9.82-rc.172 → 0.9.82-rc.173

package/dist/mesh/beads-db.d.ts

@@ -27,7 +27,7 @@ export declare class BeadsDB {
     updateQueueEntry(entry: MeshWorkQueueEntry): void;
     findQueueEntryById(meshId: string, id: string): MeshWorkQueueEntry | null;
     hasActiveAssignment(meshId: string, sessionId: string, nodeId: string): boolean;
-    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null;
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null;
     getQueueStatsByStatus(meshId: string): {
         status: string;
         count: number;

package/dist/mesh/mesh-events.d.ts

@@ -1,4 +1,5 @@
 import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export declare function __resetIdleAutoFastForwardForTests(): void;
 export interface PendingMeshCoordinatorEvent {
     event: string;
     meshId: string;

package/dist/mesh/mesh-fast-forward.d.ts

@@ -9,6 +9,7 @@ export interface MeshFastForwardNodeArgs {
     updateSubmodules?: boolean;
     submoduleIgnorePaths?: string[];
     timeoutMs?: number;
+    trigger?: 'manual' | 'idle_auto' | string;
 }
 export interface MeshFastForwardPlannedStep {
     operation: 'refresh_upstream' | 'verify_clean_worktree' | 'verify_fast_forward' | 'merge_ff_only' | 'submodule_update' | 'verify_post_status';
@@ -35,5 +36,6 @@ export interface MeshFastForwardResult {
     finalBranchConvergenceState?: Record<string, unknown>;
     operationError?: string;
     ledgerError?: string;
+    trigger?: string;
 }
 export declare function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promise<MeshFastForwardResult>;

package/dist/mesh/mesh-work-queue.d.ts

@@ -25,6 +25,8 @@ export interface MeshWorkQueueEntry {
     targetNodeId?: string;
     /** If specified, only this runtime session can claim the task */
     targetSessionId?: string;
+    /** If specified, a node must expose all tags before it can claim the task. */
+    requiredTags?: string[];
     /** The node that actually claimed and is executing the task */
     assignedNodeId?: string;
     /** The session currently executing the task */
@@ -53,6 +55,12 @@ export interface MeshWorkQueueEntry {
 export interface MeshQueueMutationOptions {
     ownerRole?: RepoMeshDaemonRole;
 }
+export declare function normalizeMeshCapabilityTags(value: unknown): string[];
+export declare function buildMeshNodeCapabilityTags(node: {
+    capabilities?: unknown;
+    policy?: unknown;
+} | undefined, providerType?: string): string[];
+export declare function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags: unknown): boolean;
 /**
  * Add a new task to the mesh queue.
  */
@@ -60,6 +68,7 @@ export declare function enqueueTask(meshId: string, message: string, opts?: {
     targetNodeId?: string;
     targetSessionId?: string;
     taskMode?: MeshTaskMode | string;
+    requiredTags?: string[];
 } & MeshQueueMutationOptions): MeshWorkQueueEntry;
 /**
  * Get all tasks in the queue, optionally filtered by status.
@@ -71,7 +80,7 @@ export declare function getMeshQueueRevision(meshId: string): string;
 /**
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
-export declare function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null;
+export declare function claimNextTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null;
 /**
  * Update the status of a specific task.
  * Used when a session completes, fails, or stalls.

package/dist/repo-mesh-types.d.ts

@@ -253,6 +253,8 @@ export interface LocalMeshNodeEntry {
     daemonId?: string;
     /** Machine registry ID that owns this workspace, when known. */
     machineId?: string;
+    /** Operator-defined capability tags used by mesh queue matching. */
+    capabilities?: string[];
     userOverrides: Partial<RepoMeshNodeCapabilities>;
     policy: RepoMeshNodePolicy;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.172",
+  "version": "0.9.82-rc.173",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config/mesh-config.ts

@@ -42,6 +42,20 @@ function loadMeshConfig(): LocalMeshConfig {
     }
 }
 
+function normalizeCapabilityTags(value: unknown): string[] | undefined {
+    if (!Array.isArray(value)) return undefined;
+    const seen = new Set<string>();
+    const tags = value
+        .map(tag => typeof tag === 'string' ? tag.trim() : '')
+        .filter(Boolean)
+        .filter(tag => {
+            if (seen.has(tag)) return false;
+            seen.add(tag);
+            return true;
+        });
+    return tags.length ? tags : undefined;
+}
+
 function saveMeshConfig(config: LocalMeshConfig): void {
     const path = getMeshConfigPath();
     writeFileSync(path, JSON.stringify(config, null, 2), { encoding: 'utf-8', mode: 0o600 });
@@ -423,6 +437,7 @@ export interface AddNodeOptions {
     repoRoot?: string;
     daemonId?: string;
     machineId?: string;
+    capabilities?: string[];
     userOverrides?: Partial<RepoMeshNodeCapabilities>;
     policy?: RepoMeshNodePolicy;
     isLocalWorktree?: boolean;
@@ -452,6 +467,7 @@ export function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntr
         repoRoot: opts.repoRoot,
         daemonId: opts.daemonId,
         machineId: opts.machineId,
+        capabilities: normalizeCapabilityTags(opts.capabilities),
         userOverrides: opts.userOverrides || {},
         policy: opts.policy || {},
         isLocalWorktree: opts.isLocalWorktree,

package/src/index.ts

@@ -201,8 +201,6 @@ export type {
   RepoMeshRefineConfig,
   RepoMeshRefineValidationCommandConfig,
 } from './mesh/refine-config.js';
-export { syncMeshes } from './mesh/mesh-sync.js';
-export type { MeshSyncTransport, MeshSyncResult, RemoteMeshRecord } from './mesh/mesh-sync.js';
 
 // ── Mesh Task Ledger ──
 export { appendLedgerEntry, appendRemoteLedgerEntries, buildTaskCompletionEvidence, normalizeMeshWorkerResult, readLedgerEntries, readLedgerSlice, getLedgerSummary, getLedgerDir, getSessionRecoveryContext, MAX_LEDGER_SLICE_LIMIT } from './mesh/mesh-ledger.js';
@@ -213,7 +211,7 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches } from './mesh/mesh-work-queue.js';
+export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary } from './mesh/mesh-active-work.js';
 export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary, MeshActiveWorkSource, MeshStaleDirectWorkSummary } from './mesh/mesh-active-work.js';

package/src/mesh/beads-db.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { createRequire } from 'module';
 import { getLedgerDir } from './mesh-ledger.js';
+import { nodeSatisfiesRequiredTags } from './mesh-work-queue.js';
 import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
 import type BetterSqlite3 from 'better-sqlite3';
 import type { Database as DatabaseHandle } from 'better-sqlite3';
@@ -280,34 +281,40 @@ export class BeadsDB {
     }
 
     // O(1) claim: transaction ensures only one session claims a pending task
-    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
+    claimNextQueueTask(meshId: string, nodeId: string, sessionId: string, capabilityTags: string[] = []): MeshWorkQueueEntry | null {
         return this.transaction(() => {
             this.ensureLegacyQueueMigrated(meshId);
             if (this.hasActiveAssignment(meshId, sessionId, nodeId)) return null;
 
             // Priority: session-targeted > node-targeted (no session) > unconstrained
-            const row = (
+            const rows = [
+                ...(
                 this.db.prepare(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_session_id = ?
-                    ORDER BY created_at ASC LIMIT 1
-                `).get(meshId, sessionId) as { payload: string } | undefined
-            ) || (
+                    ORDER BY created_at ASC
+                `).all(meshId, sessionId) as Array<{ payload: string }>
+                ),
+                ...(
                 this.db.prepare(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_node_id = ? AND target_session_id IS NULL
-                    ORDER BY created_at ASC LIMIT 1
-                `).get(meshId, nodeId) as { payload: string } | undefined
-            ) || (
+                    ORDER BY created_at ASC
+                `).all(meshId, nodeId) as Array<{ payload: string }>
+                ),
+                ...(
                 this.db.prepare(`
                     SELECT payload FROM mesh_queue
                     WHERE mesh_id = ? AND status = 'pending' AND target_node_id IS NULL AND target_session_id IS NULL
-                    ORDER BY created_at ASC LIMIT 1
-                `).get(meshId) as { payload: string } | undefined
-            );
-            if (!row) return null;
+                    ORDER BY created_at ASC
+                `).all(meshId) as Array<{ payload: string }>
+                ),
+            ];
+            const entry = rows
+                .map(row => JSON.parse(row.payload) as MeshWorkQueueEntry)
+                .find(candidate => nodeSatisfiesRequiredTags(candidate.requiredTags, capabilityTags));
+            if (!entry) return null;
 
-            const entry = JSON.parse(row.payload) as MeshWorkQueueEntry;
             const now = new Date().toISOString();
             entry.status = 'assigned';
             entry.assignedNodeId = nodeId;

package/src/mesh/mesh-events.ts

@@ -7,8 +7,9 @@ import { detectCLI } from '../detection/cli-detector.js';
 import { LOG } from '../logging/logger.js';
 import { appendLedgerEntry, buildTaskCompletionEvidence, getLedgerDir, getSessionRecoveryContext, isIntentionalCleanupStopEntry, readLedgerEntries } from './mesh-ledger.js';
 import type { MeshLedgerKind, SessionRecoveryContext } from './mesh-ledger.js';
-import { claimNextTask, updateSessionTaskStatus, enqueueTask, updateTaskStatus, getQueue, recordTaskAutoLaunch, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, getActiveDirectDispatches } from './mesh-work-queue.js';
+import { buildMeshNodeCapabilityTags, claimNextTask, updateSessionTaskStatus, enqueueTask, updateTaskStatus, getQueue, recordTaskAutoLaunch, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, getActiveDirectDispatches } from './mesh-work-queue.js';
 import { BeadsDB } from './beads-db.js';
+import { fastForwardMeshNode } from './mesh-fast-forward.js';
 
 // ---------------------------------------------------------------------------
 // Remote Node Idle Session Tracking
@@ -33,6 +34,8 @@ const remoteIdleSessions = new Map<string, RemoteIdleSession>(); // key: `${node
 // meshNodeFor. Cache results for 5 seconds to avoid repeated config reads.
 const meshByWorkspaceCache = new Map<string, { mesh: any; cachedAt: number }>();
 const MESH_WORKSPACE_CACHE_TTL_MS = 5_000;
+const IDLE_AUTO_FAST_FORWARD_THROTTLE_MS = 30 * 60 * 1000;
+const idleAutoFastForwardLastAttempt = new Map<string, number>();
 
 function getCachedMeshByWorkspace(workspace: string): any {
     const now = Date.now();
@@ -47,6 +50,10 @@ function readWorkerResultMetadata(event: Record<string, unknown>): Record<string
     return readRecord(event.workerResult) || readRecord(event.meshWorkerResult) || readRecord(event.structuredResult);
 }
 
+export function __resetIdleAutoFastForwardForTests(): void {
+    idleAutoFastForwardLastAttempt.clear();
+}
+
 function sweepExpiredRemoteIdleSessions(): void {
     const now = Date.now();
     for (const [key, session] of remoteIdleSessions) {
@@ -663,7 +670,10 @@ export function tryAssignQueueTask(
     sessionId: string,
     providerType: string
 ): boolean {
-    const task = claimNextTask(meshId, nodeId, sessionId);
+    const mesh = getMeshWithCache(components, meshId);
+    const node = mesh?.nodes.find((n: any) => n.id === nodeId);
+    const capabilityTags = buildMeshNodeCapabilityTags(node, providerType);
+    const task = claimNextTask(meshId, nodeId, sessionId, capabilityTags);
     if (!task) {
         return false;
     }
@@ -671,9 +681,6 @@ export function tryAssignQueueTask(
     LOG.info('MeshQueue', `Node ${nodeId} (${sessionId}) pulled task ${task.id}`);
 
     // Check if the node is remote
-    const mesh = getMeshWithCache(components, meshId);
-    const node = mesh?.nodes.find((n: any) => n.id === nodeId);
-    
     // If the node is explicitly remote and we have a dispatch mechanism, route via P2P
     if (node?.daemonId && components.dispatchMeshCommand) {
         const isLocalNode = components.cliManager.adapters.has(sessionId);
@@ -1061,6 +1068,72 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
     await maybeAutoLaunchOneQueueSession(components, meshId, mesh);
 }
 
+async function maybeAutoFastForwardIdleNode(components: DaemonComponents, args: {
+    meshId: string;
+    nodeId: string;
+    sessionId?: string;
+    providerType?: string;
+}): Promise<void> {
+    const mesh = getMeshWithCache(components, args.meshId);
+    const node = mesh?.nodes?.find((candidate: any) => candidate?.id === args.nodeId || candidate?.nodeId === args.nodeId);
+    const workspace = readNonEmptyString(node?.workspace);
+    if (!workspace) return;
+    if (!existsSync(workspace)) return;
+
+    const throttleKey = `${args.meshId}:${args.nodeId}`;
+    const now = Date.now();
+    const lastAttempt = idleAutoFastForwardLastAttempt.get(throttleKey) || 0;
+    if (now - lastAttempt < IDLE_AUTO_FAST_FORWARD_THROTTLE_MS) return;
+    idleAutoFastForwardLastAttempt.set(throttleKey, now);
+
+    const submoduleIgnorePaths = Array.isArray(node?.policy?.submoduleIgnorePaths)
+        ? node.policy.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string')
+        : undefined;
+    try {
+        const dryRun = await fastForwardMeshNode({
+            meshId: args.meshId,
+            nodeId: args.nodeId,
+            workspace,
+            execute: false,
+            dryRun: true,
+            updateSubmodules: false,
+            submoduleIgnorePaths,
+            trigger: 'idle_auto',
+        });
+        if (!dryRun || dryRun.code !== 'fast_forward_available' || dryRun.allowed !== true) return;
+        await fastForwardMeshNode({
+            meshId: args.meshId,
+            nodeId: args.nodeId,
+            workspace,
+            execute: true,
+            dryRun: false,
+            updateSubmodules: false,
+            submoduleIgnorePaths,
+            trigger: 'idle_auto',
+        });
+    } catch (e: any) {
+        LOG.warn('MeshFastForward', `Idle auto fast-forward check failed for ${args.nodeId}: ${e?.message || e}`);
+    }
+}
+
+function runIdleMaintenanceThenAssignQueue(components: DaemonComponents, args: {
+    meshId: string;
+    nodeId: string;
+    sessionId: string;
+    providerType: string;
+}): void {
+    setImmediate(() => {
+        maybeAutoFastForwardIdleNode(components, args)
+            .finally(() => {
+                try {
+                    tryAssignQueueTask(components, args.meshId, args.nodeId, args.sessionId, args.providerType);
+                } catch (e: any) {
+                    LOG.warn('MeshQueue', `Failed to assign idle queue task after maintenance for ${args.nodeId}: ${e?.message || e}`);
+                }
+            });
+    });
+}
+
 function buildMeshSystemMessage(args: {
     event: string;
     nodeLabel: string;
@@ -1313,9 +1386,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
             updateDirectDispatchStatus(args.meshId, sessionId, 'completed');
             setImmediate(() => cleanupTerminalDirectDispatches());
             if (nodeId && providerType) {
-                setImmediate(() => {
-                    tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
-                });
+                runIdleMaintenanceThenAssignQueue(components, { meshId: args.meshId, nodeId, sessionId, providerType });
             }
         }
     } else if (args.event === 'agent:ready') {
@@ -1370,8 +1441,15 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
                 expiresAt: Date.now() + REMOTE_IDLE_SESSION_TTL_MS,
             });
             setImmediate(() => {
-                const assigned = tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
-                if (assigned) remoteIdleSessions.delete(`${nodeId}:${sessionId}`);
+                maybeAutoFastForwardIdleNode(components, { meshId: args.meshId, nodeId, sessionId, providerType })
+                    .finally(() => {
+                        try {
+                            const assigned = tryAssignQueueTask(components, args.meshId, nodeId, sessionId, providerType);
+                            if (assigned) remoteIdleSessions.delete(`${nodeId}:${sessionId}`);
+                        } catch (e: any) {
+                            LOG.warn('MeshQueue', `Failed to assign idle queue task after maintenance for ${nodeId}: ${e?.message || e}`);
+                        }
+                    });
             });
         }
     } else if (args.event === 'agent:generating_started') {

package/src/mesh/mesh-fast-forward.ts

@@ -12,6 +12,7 @@ export interface MeshFastForwardNodeArgs {
   updateSubmodules?: boolean;
   submoduleIgnorePaths?: string[];
   timeoutMs?: number;
+  trigger?: 'manual' | 'idle_auto' | string;
 }
 
 export interface MeshFastForwardPlannedStep {
@@ -40,11 +41,12 @@ export interface MeshFastForwardResult {
   finalBranchConvergenceState?: Record<string, unknown>;
   operationError?: string;
   ledgerError?: string;
+  trigger?: string;
 }
 
 type MeshFastForwardBase = Pick<
   MeshFastForwardResult,
-  'workspace' | 'dryRun' | 'updateSubmodules' | 'plannedSteps'
+  'workspace' | 'dryRun' | 'updateSubmodules' | 'plannedSteps' | 'trigger'
 > & Pick<Partial<MeshFastForwardResult>, 'nodeId' | 'meshId'>;
 
 const STATUS_OPTIONS = { refreshUpstream: true, includeSubmodules: true, timeoutMs: 15_000 } as const;
@@ -54,6 +56,7 @@ export async function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promis
   const nodeId = normalizeOptionalString(args.nodeId);
   const meshId = normalizeOptionalString(args.meshId);
   const requestedBranch = normalizeOptionalString(args.branch);
+  const trigger = normalizeOptionalString(args.trigger) || 'manual';
   const updateSubmodules = args.updateSubmodules === true;
   const dryRun = args.dryRun === true || args.execute !== true;
   const plannedSteps = buildPlannedSteps(updateSubmodules);
@@ -64,6 +67,7 @@ export async function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promis
     dryRun,
     updateSubmodules,
     plannedSteps,
+    trigger,
   };
 
   if (!workspace) {
@@ -78,11 +82,13 @@ export async function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promis
 
   const earlyBlockers = collectPreflightBlockers(current, requestedBranch);
   if (earlyBlockers.length > 0) {
-    return {
+    const result: MeshFastForwardResult = {
       ...block(base, chooseBlockCode(current, earlyBlockers), earlyBlockers),
       current,
       finalBranchConvergenceState: buildConvergenceState(current, codeToConvergenceStatus(chooseBlockCode(current, earlyBlockers))),
     };
+    await appendFastForwardLedger(result, 'blocked');
+    return result;
   }
 
   if (current.behind === 0) {
@@ -129,6 +135,7 @@ export async function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promis
       preStatus: current,
       finalBranchConvergenceState: buildConvergenceState(current, 'fast_forward_available'),
     };
+    await appendFastForwardLedger(result, 'dry_run');
     return result;
   }
 
@@ -393,7 +400,7 @@ function formatGitError(error: unknown): string {
   return String(error);
 }
 
-async function appendFastForwardLedger(result: MeshFastForwardResult, outcome: 'noop' | 'blocked' | 'executed' | 'failed'): Promise<void> {
+async function appendFastForwardLedger(result: MeshFastForwardResult, outcome: 'noop' | 'blocked' | 'dry_run' | 'executed' | 'failed'): Promise<void> {
   if (!result.meshId) return;
   try {
     const { appendLedgerEntry } = await import('./mesh-ledger.js');
@@ -402,6 +409,7 @@ async function appendFastForwardLedger(result: MeshFastForwardResult, outcome: '
       ...(result.nodeId ? { nodeId: result.nodeId } : {}),
       payload: {
         operation: 'mesh_fast_forward_node',
+        trigger: result.trigger || 'manual',
         outcome,
         code: result.code,
         workspace: result.workspace,

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

@@ -69,6 +69,8 @@ export interface MeshWorkQueueEntry {
     targetNodeId?: string;
     /** If specified, only this runtime session can claim the task */
     targetSessionId?: string;
+    /** If specified, a node must expose all tags before it can claim the task. */
+    requiredTags?: string[];
     /** The node that actually claimed and is executing the task */
     assignedNodeId?: string;
     /** The session currently executing the task */
@@ -99,6 +101,49 @@ export interface MeshQueueMutationOptions {
     ownerRole?: RepoMeshDaemonRole;
 }
 
+export function normalizeMeshCapabilityTags(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    const seen = new Set<string>();
+    return value
+        .map(tag => typeof tag === 'string' ? tag.trim() : '')
+        .filter(Boolean)
+        .filter(tag => {
+            if (seen.has(tag)) return false;
+            seen.add(tag);
+            return true;
+        });
+}
+
+function firstProviderPriority(policy: unknown): string | undefined {
+    const raw = policy && typeof policy === 'object' && !Array.isArray(policy)
+        ? (policy as Record<string, unknown>).providerPriority
+        : undefined;
+    if (!Array.isArray(raw)) return undefined;
+    return raw.find(type => typeof type === 'string' && type.trim())?.trim();
+}
+
+export function buildMeshNodeCapabilityTags(
+    node: { capabilities?: unknown; policy?: unknown } | undefined,
+    providerType?: string,
+): string[] {
+    const provider = typeof providerType === 'string' && providerType.trim()
+        ? providerType.trim()
+        : firstProviderPriority(node?.policy);
+    return normalizeMeshCapabilityTags([
+        ...(Array.isArray(node?.capabilities) ? node.capabilities : []),
+        `os=${process.platform}`,
+        `arch=${process.arch}`,
+        ...(provider ? [`provider=${provider}`] : []),
+    ]);
+}
+
+export function nodeSatisfiesRequiredTags(requiredTags: unknown, capabilityTags: unknown): boolean {
+    const required = normalizeMeshCapabilityTags(requiredTags);
+    if (required.length === 0) return true;
+    const available = new Set(normalizeMeshCapabilityTags(capabilityTags));
+    return required.every(tag => available.has(tag));
+}
+
 function withQueueLock<T>(_meshId: string, fn: () => T): T {
     return BeadsDB.getInstance().transaction(fn);
 }
@@ -117,7 +162,7 @@ function writeQueue(meshId: string, queue: MeshWorkQueueEntry[]): void {
 export function enqueueTask(
     meshId: string,
     message: string,
-    opts?: { targetNodeId?: string; targetSessionId?: string; taskMode?: MeshTaskMode | string } & MeshQueueMutationOptions,
+    opts?: { targetNodeId?: string; targetSessionId?: string; taskMode?: MeshTaskMode | string; requiredTags?: string[] } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry {
     requireMeshHostQueueOwner(opts);
     const modeValidation = validateMeshTaskModeRequest(opts?.taskMode, message);
@@ -132,6 +177,7 @@ export function enqueueTask(
         taskMode: modeValidation.taskMode,
         targetNodeId: opts?.targetNodeId,
         targetSessionId: opts?.targetSessionId,
+        requiredTags: normalizeMeshCapabilityTags(opts?.requiredTags),
         createdAt: new Date().toISOString(),
         updatedAt: new Date().toISOString(),
     };
@@ -153,8 +199,8 @@ export function getMeshQueueRevision(meshId: string): string {
 /**
  * Find the next pending task that this node is allowed to claim, and mark it as assigned.
  */
-export function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null {
-    return BeadsDB.getInstance().claimNextQueueTask(meshId, nodeId, sessionId);
+export function claimNextTask(meshId: string, nodeId: string, sessionId: string, capabilityTags?: string[]): MeshWorkQueueEntry | null {
+    return BeadsDB.getInstance().claimNextQueueTask(meshId, nodeId, sessionId, capabilityTags);
 }
 
 /**

package/src/repo-mesh-types.ts

@@ -303,6 +303,8 @@ export interface LocalMeshNodeEntry {
     daemonId?: string;
     /** Machine registry ID that owns this workspace, when known. */
     machineId?: string;
+    /** Operator-defined capability tags used by mesh queue matching. */
+    capabilities?: string[];
     userOverrides: Partial<RepoMeshNodeCapabilities>;
     policy: RepoMeshNodePolicy;
     /**

package/dist/mesh/mesh-sync.d.ts

@@ -1,53 +0,0 @@
-/**
- * Mesh Sync — Sync local mesh metadata to/from cloud D1
- *
- * When cloud is available, this module pushes local mesh config
- * to the server and pulls remote meshes that were created from
- * other machines. The local ~/.adhdev/meshes.json remains the
- * canonical source; cloud is a membership/metadata layer only.
- * Task/chat/ledger evidence remains local-first and must not be
- * synchronized through Cloud/D1.
- *
- * This is called lazily (not on daemon startup) — only when the
- * user explicitly opens the mesh page or runs `adhdev mesh sync`.
- */
-export interface MeshSyncTransport {
-    /** GET /api/v1/repo-meshes */
-    listRemoteMeshes(): Promise<{
-        meshes: RemoteMeshRecord[];
-    }>;
-    /** POST /api/v1/repo-meshes */
-    createRemoteMesh(data: {
-        name: string;
-        repo_identity: string;
-        repo_remote_url?: string;
-        default_branch?: string;
-        policy?: string;
-    }): Promise<{
-        mesh: RemoteMeshRecord;
-    }>;
-    /** DELETE /api/v1/repo-meshes/:id */
-    deleteRemoteMesh(meshId: string): Promise<void>;
-}
-export interface RemoteMeshRecord {
-    id: string;
-    name: string;
-    repo_identity: string;
-    repo_remote_url: string | null;
-    default_branch: string | null;
-    policy: string;
-    status: string;
-    created_at: string;
-    updated_at: string;
-}
-export interface MeshSyncResult {
-    pushed: number;
-    pulled: number;
-    deleted: number;
-    errors: string[];
-}
-/**
- * Push local meshes to cloud (upsert by repo_identity).
- * Pull remote meshes that don't exist locally.
- */
-export declare function syncMeshes(transport: MeshSyncTransport): Promise<MeshSyncResult>;