@adhdev/daemon-core 0.9.82-rc.315 → 0.9.82-rc.316

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

@@ -108,6 +108,28 @@ export declare function nodeSatisfiesRequiredTags(requiredTags: unknown, capabil
 export declare function resolveConvergeRequiredTags(meshId: string, taskMode: MeshTaskMode | undefined, explicitRequiredTags: string[], opts?: {
     targetNodeId?: string;
 }): string[];
+/**
+ * Declarative task_mode → role affinity resolution (precedent: resolveConvergeRequiredTags).
+ *
+ * At enqueue time, auto-inject a `role=<role>` required tag derived from the task's
+ * taskMode via the mesh's policy.taskAffinity (falling back to DEFAULT_TASKMODE_ROLE_MAP),
+ * so the task hard-filters onto nodes advertising that role through the ordinary
+ * required-tags path (nodeSatisfiesRequiredTags) — no claim/scheduler change needed.
+ *
+ * Strict precedence / backward compatibility — the injection is skipped (returns the
+ * explicit tags unchanged) when ANY of:
+ *   - the caller pinned an explicit targetNodeId (operator chose the node), or
+ *   - the caller supplied their own non-empty required_tags (caller's routing wins), or
+ *   - affinity resolves to no role (policy disabled, blank override, or unknown mode), or
+ *   - SOFT fallback: no node in the mesh advertises the resolved role=<role> — injecting
+ *     would block the task with zero eligible nodes, so we skip it and let least_loaded
+ *     eligibility take over (a warning is logged so the misconfiguration is visible).
+ * Idempotent: normalizeMeshCapabilityTags dedupes.
+ */
+export declare function resolveTaskAffinityRequiredTags(meshId: string, taskMode: MeshTaskMode | undefined, explicitRequiredTags: string[], opts?: {
+    targetNodeId?: string;
+    callerSpecifiedRequiredTags?: boolean;
+}): string[];
 /**
  * M1: detect dependency cycles before enqueue. Walks the dependency graph of
  * existing queue entries plus the new task's edges. Fail-closed: a cycle

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

@@ -119,6 +119,62 @@ export declare function resolveNodeSchedulingPriority(nodePolicy: Pick<RepoMeshN
  */
 export declare const MESH_CONVERGE_REFINE_TAG = "converge=refine";
 export declare const MESH_CONVERGE_FAST_FORWARD_TAG = "converge=fast_forward";
+/**
+ * Standard mesh resource-pool roles. These are the dashboard-provided defaults for
+ * the role=<x> routing tag (advertised by node policy.providerRoles and matched
+ * through nodeSatisfiesRequiredTags). A mesh is free to declare additional custom
+ * role strings in policy.taskAffinity; the dashboard role dropdown exposes the union
+ * of these four standards plus any config-declared roles. Roles are lowercased
+ * everywhere (the role=<x> tag is lowercased in roleCapabilityTags).
+ */
+export declare const STANDARD_MESH_ROLES: readonly ["investigator", "coder", "validator", "converger"];
+export type StandardMeshRole = typeof STANDARD_MESH_ROLES[number];
+/**
+ * Default taskMode → role mapping (all five task modes). A task enqueued with a
+ * given taskMode auto-routes to a node advertising the mapped role=<x> tag, unless
+ * the mesh overrides the mapping in policy.taskAffinity.byTaskMode. Keyed by the
+ * MeshTaskMode string literals (the canonical union lives in mesh-work-queue.ts;
+ * this map is keyed by string to avoid a types ↔ queue import cycle). Kept in sync
+ * with MeshTaskMode by the exhaustive lookup in resolveTaskAffinityRole.
+ */
+export declare const DEFAULT_TASKMODE_ROLE_MAP: Readonly<Record<string, StandardMeshRole>>;
+/**
+ * Declarative task_mode → role affinity policy. When set, enqueueTask auto-injects a
+ * `role=<role>` required tag (see resolveTaskAffinityRequiredTags) so the task
+ * hard-filters onto nodes advertising that role — but only when the caller did NOT
+ * already pin the task with an explicit target_node_id or its own required_tags.
+ *
+ * - `enabled`: master switch. Defaults to true so the built-in DEFAULT_TASKMODE_ROLE_MAP
+ *   takes effect even when a mesh declares no taskAffinity block at all. Set false to
+ *   fully disable affinity routing (today's pre-affinity behavior).
+ * - `byTaskMode`: per-taskMode override of the default mapping. A role string here may
+ *   be any of STANDARD_MESH_ROLES or a custom role declared by the operator. An empty
+ *   string disables affinity for that one task mode.
+ * - `customRoles`: extra (non-standard) role strings to surface in the dashboard role
+ *   dropdown. Routing itself does not require a role to be pre-declared here — any role
+ *   referenced in byTaskMode is injected regardless; customRoles only widens the UI list.
+ */
+export interface RepoMeshTaskAffinityPolicy {
+    enabled?: boolean;
+    byTaskMode?: Record<string, string>;
+    customRoles?: string[];
+}
+/**
+ * Resolve the affinity role for a task mode against a mesh's taskAffinity policy.
+ * Returns the lowercased role string to inject as `role=<role>`, or null when no
+ * affinity applies (affinity disabled, an explicit empty override, or an unknown mode).
+ *
+ * Precedence: policy.byTaskMode[mode] (operator override) → DEFAULT_TASKMODE_ROLE_MAP[mode].
+ * A blank override string explicitly opts that mode out of affinity routing.
+ */
+export declare function resolveTaskAffinityRole(taskMode: string | undefined, policy: RepoMeshTaskAffinityPolicy | null | undefined): string | null;
+/**
+ * Union of the standard roles plus any operator-declared roles (byTaskMode values +
+ * customRoles), lowercased and deduped, preserving standard-first ordering. Used by
+ * the dashboard role dropdown so operators can pick a standard or a config-declared
+ * custom role. Pure/UI-facing — does not gate routing.
+ */
+export declare function resolveMeshRoleOptions(policy: RepoMeshTaskAffinityPolicy | null | undefined): string[];
 /**
  * Resolve whether the load-balancing scheduler should auto-inject a
  * `converge=refine` required tag onto code_change tasks so they hard-filter onto
@@ -168,6 +224,18 @@ export interface RepoMeshPolicy {
      * Defaults to false: code_change routing is unchanged unless opted in.
      */
     autoConvergeCodeChange?: boolean;
+    /**
+     * Declarative task_mode → role affinity routing. When present (and not disabled),
+     * enqueueTask auto-injects a `role=<role>` required tag for the task's taskMode so
+     * the work hard-filters onto nodes advertising that role. Explicit target_node_id
+     * routing and any caller-supplied required_tags are preserved (auto-injection only
+     * applies when the caller pinned neither). When the mapped role has no advertising
+     * node in the mesh, the task is NOT blocked — the role tag is skipped so the work
+     * falls back to ordinary least_loaded eligibility (soft affinity). Defaults to the
+     * built-in DEFAULT_TASKMODE_ROLE_MAP even when this block is omitted; set
+     * `{ enabled: false }` to fully restore pre-affinity routing.
+     */
+    taskAffinity?: RepoMeshTaskAffinityPolicy;
     /**
      * Whether sessions spawned by mesh/coordinator policy should auto-open as visible
      * dashboard tabs or start hidden. Defaults to 'visible' to preserve existing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.315",
+  "version": "0.9.82-rc.316",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.315",
+    "@adhdev/mesh-shared": "0.9.82-rc.316",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/cli-adapter-types.ts

@@ -38,6 +38,29 @@ export interface AcpAdapterHandle {
     resolvePermission?(approved: boolean): Promise<void>;
 }
 
+/**
+ * Launch metadata for a CLI session, surfaced by the dashboard Session info panel.
+ * Derived from the live adapter's spawn plan — the resolved binary, the full
+ * argument vector (provider base args + per-launch extra args), the cwd, and the
+ * set of per-launch extra-env KEYS (values are intentionally omitted so secrets in
+ * extraEnv are never sent to the dashboard). providerSessionId is the upstream
+ * agent's own session id once the CLI reports it.
+ */
+export interface CliLaunchInfo {
+    /** Resolved executable path the PTY actually spawns. */
+    command?: string;
+    /** Full argument vector (provider spawn.args + extraArgs, {{workingDir}} expanded). */
+    args: string[];
+    /** Per-launch extra args only (subset of args), for attribution. */
+    extraArgs: string[];
+    /** Working directory the session was spawned in. */
+    cwd: string;
+    /** KEYS of per-launch extra env (values omitted — may contain secrets). */
+    extraEnvKeys: string[];
+    /** Upstream agent session id, once the CLI reports one. */
+    providerSessionId?: string;
+}
+
 export interface CliAdapter {
     cliType: string;
     cliName: string;
@@ -70,6 +93,8 @@ export interface CliAdapter {
     setOnPtyData?(callback: (data: string) => void): void;
     writeRaw?(data: string): void;
     resize?(cols: number, rows: number): void;
+    // ── Launch metadata for the dashboard Session info panel (args/cwd/env keys) ──
+    getLaunchInfo?(): CliLaunchInfo;
     // ── Runtime metadata used by CliProviderInstance for session tracking ──
     getRuntimeMetadata?(): unknown;
     updateRuntimeMeta?(meta: Record<string, unknown>): void;

package/src/cli-adapters/provider-cli-adapter.ts

@@ -15,7 +15,7 @@
  */
 
 import * as os from 'os';
-import type { CliAdapter } from '../cli-adapter-types.js';
+import type { CliAdapter, CliLaunchInfo } from '../cli-adapter-types.js';
 import type { InteractivePromptResponse } from '../providers/types/interactive-prompt.js';
 import { LOG } from '../logging/logger.js';
 import { getDebugRuntimeConfig } from '../logging/debug-config.js';
@@ -1595,6 +1595,41 @@ export class ProviderCliAdapter implements CliAdapter {
         return this.ptyProcess.getMetadata();
     }
 
+    /**
+     * Launch metadata for the dashboard Session info panel. Re-derives the spawn plan
+     * (pure — same inputs the live PTY was spawned with) so the dashboard sees the
+     * resolved binary, full arg vector, and cwd without us having to persist it.
+     * extraEnv values are intentionally dropped (keys only) so secrets passed at
+     * launch time never reach the dashboard.
+     */
+    getLaunchInfo(): CliLaunchInfo {
+        let command: string | undefined;
+        let args: string[] = [...this.extraArgs];
+        try {
+            const plan = resolveCliSpawnPlan({
+                provider: this.provider,
+                runtimeSettings: this.runtimeSettings,
+                workingDir: this.workingDir,
+                extraArgs: this.extraArgs,
+                extraEnv: this.extraEnv,
+            });
+            command = plan.binaryPath;
+            args = plan.allArgs;
+        } catch {
+            // Spawn plan resolution can throw before the binary is resolvable
+            // (e.g. CLI not installed). Fall back to the raw extra args so the
+            // panel still shows what it can rather than failing the whole call.
+        }
+        return {
+            command,
+            args,
+            extraArgs: [...this.extraArgs],
+            cwd: this.workingDir,
+            extraEnvKeys: Object.keys(this.extraEnv || {}),
+            providerSessionId: this.providerSessionId || undefined,
+        };
+    }
+
     updateRuntimeMeta(meta: Record<string, unknown>, replace = false): void {
         const nextProviderSessionId = typeof meta?.providerSessionId === 'string'
             ? meta.providerSessionId.trim()

package/src/cli-adapters/provider-cli-shared.ts

@@ -534,9 +534,26 @@ export function findBinary(name: string): string {
     }
     const isWin = os.platform() === 'win32';
     const paths = (process.env.PATH || '').split(path.delimiter);
+    // Also search well-known global-bin directories that are frequently NOT on
+    // the daemon's inherited PATH. A daemon running under one Node install (e.g.
+    // nvm) never sees another npm prefix's bin dir — notably npm's Windows
+    // default prefix at %APPDATA%\npm, where `npm i -g @openai/codex` lands. We
+    // append these after PATH (so explicit PATH entries still win) so that an
+    // npm-global CLI resolves to an absolute path; the spawn layer's .cmd-shim
+    // handling then launches it correctly regardless of PATH.
+    const extraDirs: string[] = [];
+    if (isWin) {
+        if (process.env.APPDATA) extraDirs.push(path.join(process.env.APPDATA, 'npm'));
+        try { extraDirs.push(path.dirname(process.execPath)); } catch { /* best-effort */ }
+    } else {
+        extraDirs.push(path.join(os.homedir(), '.npm-global', 'bin'));
+        extraDirs.push('/usr/local/bin', '/opt/homebrew/bin');
+        try { extraDirs.push(path.dirname(process.execPath)); } catch { /* best-effort */ }
+    }
+    const searchDirs = [...paths, ...extraDirs];
     const exes = isWin ? ['.exe', '.cmd', '.bat', ''] : [''];
-    
-    for (const p of paths) {
+
+    for (const p of searchDirs) {
         if (!p) continue;
         for (const ext of exes) {
             const fullPath = path.join(p, trimmed + ext);

package/src/commands/router.ts

@@ -6345,6 +6345,12 @@ export class DaemonCommandRouter {
                 const runtimeMeta = (adapter && typeof (adapter as any).getRuntimeMetadata === 'function')
                     ? (adapter as any).getRuntimeMetadata()
                     : undefined;
+                // Launch metadata (args / cwd / extra-env keys / providerSessionId) is
+                // derived from the live adapter's spawn plan; only available while the
+                // adapter is alive (resumed-from-history sessions report nothing here).
+                const launchInfo = (adapter && typeof (adapter as any).getLaunchInfo === 'function')
+                    ? (adapter as any).getLaunchInfo()
+                    : undefined;
                 const providerType = target?.providerType || coord?.cliType || '';
                 const providerMetaForSession = providerType
                     ? this.deps.providerLoader.resolve?.(providerType) || this.deps.providerLoader.getMeta(providerType)
@@ -6358,8 +6364,11 @@ export class DaemonCommandRouter {
                         transport: target?.transport,
                         workspace: (target as any)?.workspace || coord?.workspace,
                         spawnedAtMs: (target as any)?.spawnedAtMs || coord?.startedAt,
-                        providerSessionId: (target as any)?.providerSessionId,
+                        // providerSessionId now comes from the live adapter's launch info
+                        // (the registry target never carried it — it was always undefined).
+                        providerSessionId: launchInfo?.providerSessionId || (target as any)?.providerSessionId,
                         runtimeMetadata: runtimeMeta,
+                        launch: launchInfo,
                     },
                     coordinator: coord ? {
                         meshId: coord.meshId,

package/src/config/mesh-config.ts

@@ -20,8 +20,9 @@ import type {
     RepoMeshCoordinatorConfig,
     RepoMeshHostMetadata,
     RepoMeshDaemonRole,
+    RepoMeshTaskAffinityPolicy,
 } from '../repo-mesh-types.js';
-import { DEFAULT_MESH_POLICY, normalizeMeshSchedulingStrategy } from '../repo-mesh-types.js';
+import { DEFAULT_MESH_POLICY, normalizeMeshSchedulingStrategy, STANDARD_MESH_ROLES } from '../repo-mesh-types.js';
 import { createDefaultMeshHostMetadata } from '../mesh/mesh-host-ownership.js';
 
 // ─── Persistence ────────────────────────────────
@@ -134,9 +135,79 @@ function mergeMeshPolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMe
     } else {
         delete policy.autoConvergeCodeChange;
     }
+    // Task-mode → role affinity: format-only validation (drop blanks). Unknown/custom
+    // roles are NOT blocked — only a warning is logged. Only persist when the block
+    // carries meaningful content so existing meshes.json stays untouched.
+    const normalizedAffinity = normalizeTaskAffinityPolicy(policy.taskAffinity);
+    if (normalizedAffinity) {
+        policy.taskAffinity = normalizedAffinity;
+    } else {
+        delete policy.taskAffinity;
+    }
     return policy;
 }
 
+/**
+ * Format-only normalization of a task-affinity policy. Trims/lowercases role strings,
+ * drops blank custom roles and blank byTaskMode keys, and warns (never blocks) when a
+ * declared role is not one of the standard four. Returns undefined when the result is
+ * empty/no-op so the field stays absent from persisted config.
+ */
+function normalizeTaskAffinityPolicy(
+    value: unknown,
+): RepoMeshTaskAffinityPolicy | undefined {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const record = value as Record<string, unknown>;
+    const out: RepoMeshTaskAffinityPolicy = {};
+    let hasContent = false;
+
+    if (typeof record.enabled === 'boolean') {
+        out.enabled = record.enabled;
+        // `enabled:true` is the default — only persist the explicit `false`.
+        if (record.enabled === false) hasContent = true;
+        else delete out.enabled;
+    }
+
+    if (record.byTaskMode && typeof record.byTaskMode === 'object' && !Array.isArray(record.byTaskMode)) {
+        const byTaskMode: Record<string, string> = {};
+        for (const [mode, raw] of Object.entries(record.byTaskMode as Record<string, unknown>)) {
+            const modeKey = mode.trim();
+            if (!modeKey) continue;
+            if (typeof raw !== 'string') continue;
+            // A blank value is a deliberate opt-out for that mode — preserve it as ''.
+            const role = raw.trim().toLowerCase();
+            byTaskMode[modeKey] = role;
+            if (role && !STANDARD_MESH_ROLES.includes(role as any)) {
+                try {
+                    console.warn(`[mesh] task_affinity.byTaskMode.${modeKey}: custom role "${role}" is not a standard mesh role (${STANDARD_MESH_ROLES.join('/')}); routing still applies`);
+                } catch { /* best-effort */ }
+            }
+        }
+        if (Object.keys(byTaskMode).length > 0) {
+            out.byTaskMode = byTaskMode;
+            hasContent = true;
+        }
+    }
+
+    if (Array.isArray(record.customRoles)) {
+        const seen = new Set<string>();
+        const customRoles: string[] = [];
+        for (const raw of record.customRoles) {
+            if (typeof raw !== 'string') continue;
+            const role = raw.trim().toLowerCase();
+            if (!role || seen.has(role)) continue;
+            seen.add(role);
+            customRoles.push(role);
+        }
+        if (customRoles.length > 0) {
+            out.customRoles = customRoles;
+            hasContent = true;
+        }
+    }
+
+    return hasContent ? out : undefined;
+}
+
 function normalizeAutoFastForwardPolicy(value: unknown): NonNullable<RepoMeshPolicy['autoFastForward']> {
     const record = value && typeof value === 'object' && !Array.isArray(value)
         ? value as Record<string, unknown>

package/src/index.ts

@@ -135,6 +135,8 @@ export type {
   RepoMeshLedgerStatus,
   MeshAsyncJobLifecycle,
   RepoMeshSchedulingStrategy,
+  RepoMeshTaskAffinityPolicy,
+  StandardMeshRole,
 } from './repo-mesh-types.js';
 export {
   DEFAULT_MESH_POLICY,
@@ -146,6 +148,10 @@ export {
   MESH_CONVERGE_REFINE_TAG,
   MESH_CONVERGE_FAST_FORWARD_TAG,
   resolveAutoConvergeCodeChange,
+  STANDARD_MESH_ROLES,
+  DEFAULT_TASKMODE_ROLE_MAP,
+  resolveTaskAffinityRole,
+  resolveMeshRoleOptions,
 } from './repo-mesh-types.js';
 
 // ── Git Surface ──
@@ -231,7 +237,7 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, resolveTaskAffinityRequiredTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
 export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
 export type { StaleDirectPruneClassification } from './mesh/mesh-active-work.js';

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

@@ -1,7 +1,7 @@
 import { randomUUID } from 'crypto';
 import { requireMeshHostQueueOwner } from './mesh-host-ownership.js';
-import type { RepoMeshDaemonRole } from '../repo-mesh-types.js';
-import { MESH_CONVERGE_REFINE_TAG, resolveAutoConvergeCodeChange } from '../repo-mesh-types.js';
+import type { RepoMeshDaemonRole, LocalMeshNodeEntry } from '../repo-mesh-types.js';
+import { MESH_CONVERGE_REFINE_TAG, resolveAutoConvergeCodeChange, resolveTaskAffinityRole } from '../repo-mesh-types.js';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { getMesh } from '../config/mesh-config.js';
 
@@ -328,6 +328,67 @@ export function resolveConvergeRequiredTags(
     return normalizeMeshCapabilityTags([...explicitRequiredTags, MESH_CONVERGE_REFINE_TAG]);
 }
 
+/**
+ * Whether any node in the mesh advertises the given `role=<role>` capability tag.
+ * Reuses buildMeshNodeCapabilityTags (node-level scan: every declared providerRole is
+ * advertised) so the membership test matches the exact tag the claim/eligibility filter
+ * would see. Used to keep task-affinity SOFT — if no node can satisfy the role, the
+ * injection is skipped so the task falls back to ordinary least_loaded eligibility
+ * rather than being blocked.
+ */
+function meshHasNodeAdvertisingRole(nodes: LocalMeshNodeEntry[] | undefined, role: string): boolean {
+    if (!Array.isArray(nodes) || nodes.length === 0) return false;
+    const wanted = `role=${role}`;
+    return nodes.some(node => buildMeshNodeCapabilityTags(node as any).includes(wanted));
+}
+
+/**
+ * Declarative task_mode → role affinity resolution (precedent: resolveConvergeRequiredTags).
+ *
+ * At enqueue time, auto-inject a `role=<role>` required tag derived from the task's
+ * taskMode via the mesh's policy.taskAffinity (falling back to DEFAULT_TASKMODE_ROLE_MAP),
+ * so the task hard-filters onto nodes advertising that role through the ordinary
+ * required-tags path (nodeSatisfiesRequiredTags) — no claim/scheduler change needed.
+ *
+ * Strict precedence / backward compatibility — the injection is skipped (returns the
+ * explicit tags unchanged) when ANY of:
+ *   - the caller pinned an explicit targetNodeId (operator chose the node), or
+ *   - the caller supplied their own non-empty required_tags (caller's routing wins), or
+ *   - affinity resolves to no role (policy disabled, blank override, or unknown mode), or
+ *   - SOFT fallback: no node in the mesh advertises the resolved role=<role> — injecting
+ *     would block the task with zero eligible nodes, so we skip it and let least_loaded
+ *     eligibility take over (a warning is logged so the misconfiguration is visible).
+ * Idempotent: normalizeMeshCapabilityTags dedupes.
+ */
+export function resolveTaskAffinityRequiredTags(
+    meshId: string,
+    taskMode: MeshTaskMode | undefined,
+    explicitRequiredTags: string[],
+    opts?: { targetNodeId?: string; callerSpecifiedRequiredTags?: boolean },
+): string[] {
+    // Caller pinned the node, or brought their own required_tags → respect it verbatim.
+    if (typeof opts?.targetNodeId === 'string' && opts.targetNodeId.trim()) return explicitRequiredTags;
+    if (opts?.callerSpecifiedRequiredTags === true) return explicitRequiredTags;
+
+    let mesh;
+    try {
+        mesh = getMesh(meshId);
+    } catch {
+        return explicitRequiredTags;
+    }
+    const role = resolveTaskAffinityRole(taskMode, mesh?.policy?.taskAffinity);
+    if (!role) return explicitRequiredTags;
+
+    // SOFT affinity: only hard-filter when the role actually exists in the mesh.
+    if (!meshHasNodeAdvertisingRole(mesh?.nodes, role)) {
+        try {
+            console.warn(`[mesh] task_affinity: no node advertises role=${role} for taskMode=${taskMode} in mesh ${meshId}; skipping injection (least_loaded fallback)`);
+        } catch { /* logging is best-effort */ }
+        return explicitRequiredTags;
+    }
+    return normalizeMeshCapabilityTags([...explicitRequiredTags, `role=${role}`]);
+}
+
 function withQueueLock<T>(_meshId: string, fn: () => T): T {
     return MeshRuntimeStore.getInstance().transaction(fn);
 }
@@ -413,6 +474,31 @@ export function enqueueTask(
             throw new Error(`duplicate_task_id: task '${id}' already exists in mesh '${meshId}'`);
         }
         assertNoDependencyCycle(meshId, id, dependsOn);
+        // Did the caller bring their own routing tags? Affinity auto-injection is
+        // suppressed when so (caller's required_tags win), matching the spec — measured
+        // against the ORIGINAL caller tags, before convergence augmentation below.
+        const callerTags = normalizeMeshCapabilityTags(opts?.requiredTags);
+        const callerSpecifiedRequiredTags = callerTags.length > 0;
+        // Convergence routing (opt-in): auto-inject converge=refine for code_change
+        // tasks so they hard-filter onto refine-capable worktree nodes. No-op unless
+        // the mesh opts in; explicit target_node_id / required_tags are preserved.
+        let resolvedRequiredTags = resolveConvergeRequiredTags(
+            meshId,
+            modeValidation.taskMode,
+            callerTags,
+            { targetNodeId: opts?.targetNodeId },
+        );
+        // Declarative task_mode → role affinity (precedent: convergence routing above):
+        // inject role=<role> for the task's taskMode unless the caller pinned a node or
+        // supplied their own required_tags. SOFT — skipped when no node advertises the
+        // role (least_loaded fallback). Built-in default mapping applies even without a
+        // taskAffinity config block; { enabled:false } disables it.
+        resolvedRequiredTags = resolveTaskAffinityRequiredTags(
+            meshId,
+            modeValidation.taskMode,
+            resolvedRequiredTags,
+            { targetNodeId: opts?.targetNodeId, callerSpecifiedRequiredTags },
+        );
         const entry: MeshWorkQueueEntry = {
             id,
             meshId,
@@ -421,15 +507,7 @@ export function enqueueTask(
             taskMode: modeValidation.taskMode,
             targetNodeId: opts?.targetNodeId,
             targetSessionId: opts?.targetSessionId,
-            // Convergence routing (opt-in): auto-inject converge=refine for code_change
-            // tasks so they hard-filter onto refine-capable worktree nodes. No-op unless
-            // the mesh opts in; explicit target_node_id / required_tags are preserved.
-            requiredTags: resolveConvergeRequiredTags(
-                meshId,
-                modeValidation.taskMode,
-                normalizeMeshCapabilityTags(opts?.requiredTags),
-                { targetNodeId: opts?.targetNodeId },
-            ),
+            requiredTags: resolvedRequiredTags,
             ...(dependsOn.length > 0 ? { dependsOn } : {}),
             ...(typeof opts?.missionId === 'string' && opts.missionId.trim() ? { missionId: opts.missionId.trim() } : {}),
             createdAt: new Date().toISOString(),

package/src/repo-mesh-types.ts

@@ -165,6 +165,106 @@ export function resolveNodeSchedulingPriority(
 export const MESH_CONVERGE_REFINE_TAG = 'converge=refine';
 export const MESH_CONVERGE_FAST_FORWARD_TAG = 'converge=fast_forward';
 
+/**
+ * Standard mesh resource-pool roles. These are the dashboard-provided defaults for
+ * the role=<x> routing tag (advertised by node policy.providerRoles and matched
+ * through nodeSatisfiesRequiredTags). A mesh is free to declare additional custom
+ * role strings in policy.taskAffinity; the dashboard role dropdown exposes the union
+ * of these four standards plus any config-declared roles. Roles are lowercased
+ * everywhere (the role=<x> tag is lowercased in roleCapabilityTags).
+ */
+export const STANDARD_MESH_ROLES = ['investigator', 'coder', 'validator', 'converger'] as const;
+export type StandardMeshRole = typeof STANDARD_MESH_ROLES[number];
+
+/**
+ * Default taskMode → role mapping (all five task modes). A task enqueued with a
+ * given taskMode auto-routes to a node advertising the mapped role=<x> tag, unless
+ * the mesh overrides the mapping in policy.taskAffinity.byTaskMode. Keyed by the
+ * MeshTaskMode string literals (the canonical union lives in mesh-work-queue.ts;
+ * this map is keyed by string to avoid a types ↔ queue import cycle). Kept in sync
+ * with MeshTaskMode by the exhaustive lookup in resolveTaskAffinityRole.
+ */
+export const DEFAULT_TASKMODE_ROLE_MAP: Readonly<Record<string, StandardMeshRole>> = {
+    live_debug_readonly: 'investigator',
+    code_change: 'coder',
+    launch_app: 'coder',
+    validation: 'validator',
+    convergence: 'converger',
+};
+
+/**
+ * Declarative task_mode → role affinity policy. When set, enqueueTask auto-injects a
+ * `role=<role>` required tag (see resolveTaskAffinityRequiredTags) so the task
+ * hard-filters onto nodes advertising that role — but only when the caller did NOT
+ * already pin the task with an explicit target_node_id or its own required_tags.
+ *
+ * - `enabled`: master switch. Defaults to true so the built-in DEFAULT_TASKMODE_ROLE_MAP
+ *   takes effect even when a mesh declares no taskAffinity block at all. Set false to
+ *   fully disable affinity routing (today's pre-affinity behavior).
+ * - `byTaskMode`: per-taskMode override of the default mapping. A role string here may
+ *   be any of STANDARD_MESH_ROLES or a custom role declared by the operator. An empty
+ *   string disables affinity for that one task mode.
+ * - `customRoles`: extra (non-standard) role strings to surface in the dashboard role
+ *   dropdown. Routing itself does not require a role to be pre-declared here — any role
+ *   referenced in byTaskMode is injected regardless; customRoles only widens the UI list.
+ */
+export interface RepoMeshTaskAffinityPolicy {
+    enabled?: boolean;
+    byTaskMode?: Record<string, string>;
+    customRoles?: string[];
+}
+
+/**
+ * Resolve the affinity role for a task mode against a mesh's taskAffinity policy.
+ * Returns the lowercased role string to inject as `role=<role>`, or null when no
+ * affinity applies (affinity disabled, an explicit empty override, or an unknown mode).
+ *
+ * Precedence: policy.byTaskMode[mode] (operator override) → DEFAULT_TASKMODE_ROLE_MAP[mode].
+ * A blank override string explicitly opts that mode out of affinity routing.
+ */
+export function resolveTaskAffinityRole(
+    taskMode: string | undefined,
+    policy: RepoMeshTaskAffinityPolicy | null | undefined,
+): string | null {
+    if (!taskMode) return null;
+    if (policy?.enabled === false) return null;
+    const override = policy?.byTaskMode && Object.prototype.hasOwnProperty.call(policy.byTaskMode, taskMode)
+        ? policy.byTaskMode[taskMode]
+        : undefined;
+    if (typeof override === 'string') {
+        const trimmed = override.trim().toLowerCase();
+        // An explicit blank override opts this task mode out of affinity routing.
+        return trimmed ? trimmed : null;
+    }
+    const fallback = DEFAULT_TASKMODE_ROLE_MAP[taskMode];
+    return fallback ?? null;
+}
+
+/**
+ * Union of the standard roles plus any operator-declared roles (byTaskMode values +
+ * customRoles), lowercased and deduped, preserving standard-first ordering. Used by
+ * the dashboard role dropdown so operators can pick a standard or a config-declared
+ * custom role. Pure/UI-facing — does not gate routing.
+ */
+export function resolveMeshRoleOptions(policy: RepoMeshTaskAffinityPolicy | null | undefined): string[] {
+    const out: string[] = [...STANDARD_MESH_ROLES];
+    const seen = new Set<string>(out);
+    const add = (raw: unknown) => {
+        if (typeof raw !== 'string') return;
+        const role = raw.trim().toLowerCase();
+        if (!role || seen.has(role)) return;
+        seen.add(role);
+        out.push(role);
+    };
+    if (policy?.byTaskMode) {
+        for (const value of Object.values(policy.byTaskMode)) add(value);
+    }
+    if (Array.isArray(policy?.customRoles)) {
+        for (const value of policy.customRoles) add(value);
+    }
+    return out;
+}
+
 /**
  * Resolve whether the load-balancing scheduler should auto-inject a
  * `converge=refine` required tag onto code_change tasks so they hard-filter onto
@@ -220,6 +320,18 @@ export interface RepoMeshPolicy {
      * Defaults to false: code_change routing is unchanged unless opted in.
      */
     autoConvergeCodeChange?: boolean;
+    /**
+     * Declarative task_mode → role affinity routing. When present (and not disabled),
+     * enqueueTask auto-injects a `role=<role>` required tag for the task's taskMode so
+     * the work hard-filters onto nodes advertising that role. Explicit target_node_id
+     * routing and any caller-supplied required_tags are preserved (auto-injection only
+     * applies when the caller pinned neither). When the mapped role has no advertising
+     * node in the mesh, the task is NOT blocked — the role tag is skipped so the work
+     * falls back to ordinary least_loaded eligibility (soft affinity). Defaults to the
+     * built-in DEFAULT_TASKMODE_ROLE_MAP even when this block is omitted; set
+     * `{ enabled: false }` to fully restore pre-affinity routing.
+     */
+    taskAffinity?: RepoMeshTaskAffinityPolicy;
     /**
      * Whether sessions spawned by mesh/coordinator policy should auto-open as visible
      * dashboard tabs or start hidden. Defaults to 'visible' to preserve existing