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

package/dist/mesh/mesh-runtime-store.d.ts

@@ -41,6 +41,12 @@ export declare class MeshRuntimeStore {
      * untargeted work spreads instead of piling onto whichever node asks first.
      */
     nodeActiveAssignmentCount(meshId: string, nodeId: string): number;
+    /**
+     * O(1) count of queue tasks in 'pending' status for a mesh. A COUNT(*) over the
+     * indexed status column, so it avoids JSON.parse-ing every queue row — used as a
+     * cheap guard before the reconcile loop runs a full triggerMeshQueue scan.
+     */
+    pendingQueueTaskCount(meshId: string): number;
     /**
      * Read the current per-mesh round-robin cursor (0 when unset). Used to rotate
      * the tie-break winner among nodes tied at the least load.

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.317",
   "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.317",
     "@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

@@ -1094,6 +1094,25 @@ function readMeshConnectionState(connection: Record<string, unknown> | null | un
     return readStringValue((connection as any)?.state);
 }
 
+/**
+ * Connection states that mean the peer is definitively NOT reachable right now —
+ * an offline machine (no peer entry at all) or a transport that has dropped
+ * (failed/closed/disconnected). Probing such a peer would just burn the full
+ * MESH_DIRECT_PROBE_TIMEOUT_MS window before timing out, so the cold-open of the
+ * mesh graph stalls 25s behind one powered-off node. `connecting` is deliberately
+ * NOT here: a peer mid-handshake may complete during the probe window, so it still
+ * gets its attempt. Held standing git truth is consulted by the caller BEFORE this
+ * runs, so the invariant "connected+held is never unavailable" is untouched — this
+ * only short-circuits a peer that has no usable transport to probe over.
+ */
+function isMeshConnectionDefinitivelyDown(
+    connection: Record<string, unknown> | null | undefined,
+): boolean {
+    if (!connection) return true;
+    const state = readMeshConnectionState(connection);
+    return state === 'failed' || state === 'closed' || state === 'disconnected';
+}
+
 /**
  * Probe a remote peer's git_status with a bounded retry budget, but only while
  * the peer is reported `connected`. A single slow (often TURN-relayed) peer can
@@ -1117,6 +1136,19 @@ async function probeRemoteMeshGitStatusWithRetry(args: {
     getConnection?: (daemonId: string) => Record<string, unknown> | null;
     onConnection?: (connection: Record<string, unknown>) => void;
 }): Promise<Record<string, unknown> | null> {
+    // Fast-fail an offline / dropped peer BEFORE the first attempt. Previously the
+    // liveness re-check only ran *between* attempts, so a powered-off node still ate
+    // the full first MESH_DIRECT_PROBE_TIMEOUT_MS (25s) window — stalling the mesh
+    // graph cold-open behind one dead machine. If a connection getter is wired and
+    // it reports the peer as definitively down (no peer entry / failed / closed /
+    // disconnected), skip straight to "no truth" instead of awaiting a 25s timeout.
+    // A `connecting` peer still gets its attempt (it may complete mid-probe). No
+    // onConnection side effect here: this is a pure liveness gate, and the caller's
+    // own connection read already seeds status.connection — only the between-attempt
+    // path needs to surface a freshly-observed connection.
+    if (args.getConnection && isMeshConnectionDefinitivelyDown(args.getConnection(args.daemonId))) {
+        return null;
+    }
     for (let attempt = 0; attempt <= MESH_DIRECT_PROBE_MAX_RETRIES; attempt += 1) {
         if (attempt > 0) {
             // Re-check liveness before spending another probe window; a peer that
@@ -6345,6 +6377,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 +6396,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/git/git-status.ts

@@ -560,13 +560,24 @@ async function getSubmoduleStatuses(
   if (!repo.repoRoot) return [];
 
   try {
-    // No `--recursive`: this superproject's submodules (oss, adhdev-providers) are
-    // leaf repos with no nested submodules, so `--recursive` doubles the (already
-    // slow on Windows) submodule-status spawn time for zero additional rows. If a
-    // nested submodule is ever introduced, restore --recursive WITH its own longer
-    // per-command timeout rather than reverting this wholesale.
-    const result = await runGit(repo, ['submodule', 'status'], options);
-    const submodules = parseSubmoduleStatusOutput(result.stdout, repo.repoRoot, options.submoduleIgnorePaths);
+    // Do NOT shell out to `git submodule status`. That porcelain wrapper is a
+    // shell script (`git-submodule`) that, per submodule, spawns several child
+    // `git` processes; on Windows the wrapper + per-spawn cost alone measured
+    // 6.9–62.4s under AV, which dominated the whole collectGitRepoStatus budget
+    // and stalled the mesh graph cold-open. The information it gives us — the
+    // gitlink sync state (path / recorded SHA / +/-/U prefix) — is fully
+    // derivable from plumbing commands that don't go through the shell wrapper:
+    //   • paths           ← `.gitmodules` (git config --file, plumbing)
+    //   • expected SHA     ← `git ls-tree HEAD <path>` (the gitlink the super-
+    //                        project's HEAD tree records)
+    //   • actual SHA       ← `git -C <sub> rev-parse HEAD` (already paid below by
+    //                        enrichSubmoduleWorktreeStatus for the dirty check)
+    // Comparing expected vs actual reproduces `+` (out of sync); a checked-out
+    // submodule whose worktree is absent/uninitialized reproduces `-`. The `U`
+    // (conflict) prefix is surfaced separately via the superproject porcelain
+    // status that the caller already parses, and a conflicted submodule's own
+    // status read here also flags it dirty — so no row is lost.
+    const submodules = await deriveSubmoduleGitlinkStatuses(repo, options);
     await Promise.all(submodules.map(submodule => enrichSubmoduleWorktreeStatus(repo, submodule, options)));
     return submodules;
   } catch {
@@ -574,6 +585,110 @@ async function getSubmoduleStatuses(
   }
 }
 
+/**
+ * Enumerate the superproject's submodules and their gitlink sync state without the
+ * slow `git submodule status` shell wrapper. Pure plumbing: read paths from
+ * `.gitmodules`, the expected (recorded) gitlink SHA from `ls-tree HEAD`, and the
+ * actual checked-out SHA from the submodule's own `rev-parse HEAD`.
+ */
+async function deriveSubmoduleGitlinkStatuses(
+  repo: ResolvedGitRepo,
+  options: GitStatusOptions,
+): Promise<GitSubmoduleStatus[]> {
+  if (!repo.repoRoot) return [];
+  const paths = await readSubmodulePaths(repo, options);
+  const ignoreSet = new Set(options.submoduleIgnorePaths || []);
+  const lastCheckedAt = Date.now();
+
+  const entries = await Promise.all(
+    paths
+      .filter(path => !ignoreSet.has(path))
+      .map(async (path): Promise<GitSubmoduleStatus> => {
+        const repoPath = repo.repoRoot + '/' + path;
+        const expected = await readGitlinkExpectedSha(repo, path, options);
+        const actual = await readSubmoduleHeadSha(repo, repoPath, options);
+        // Uninitialized / no checked-out HEAD reproduces `git submodule status`'s
+        // `-` prefix; a present-but-divergent HEAD reproduces the `+` prefix.
+        const outOfSync = actual === null
+          ? true
+          : expected !== null && expected !== actual;
+        return {
+          path,
+          // Prefer the recorded gitlink SHA (matches the legacy column); fall back
+          // to the checked-out SHA so the field is never empty when both are known.
+          commit: expected ?? actual ?? '',
+          repoPath,
+          dirty: false,
+          outOfSync,
+          lastCheckedAt,
+        };
+      }),
+  );
+  return entries;
+}
+
+/** Read submodule paths from `.gitmodules` via plumbing (no shell wrapper). */
+async function readSubmodulePaths(repo: ResolvedGitRepo, options: GitStatusOptions): Promise<string[]> {
+  if (!repo.repoRoot) return [];
+  const gitmodulesPath = repo.repoRoot + '/.gitmodules';
+  try {
+    const result = await runGit(
+      repo,
+      ['config', '--file', gitmodulesPath, '--get-regexp', '^submodule\\..*\\.path$'],
+      options,
+    );
+    const paths: string[] = [];
+    for (const line of result.stdout.split('\n')) {
+      // Each line: `submodule.<name>.path <path>`
+      const spaceIdx = line.indexOf(' ');
+      if (spaceIdx < 0) continue;
+      const value = line.slice(spaceIdx + 1).trim();
+      if (value) paths.push(value);
+    }
+    return paths;
+  } catch {
+    // No .gitmodules (not a superproject) or unreadable → no submodules.
+    return [];
+  }
+}
+
+/** Expected gitlink SHA recorded in the superproject HEAD tree for this submodule path. */
+async function readGitlinkExpectedSha(
+  repo: ResolvedGitRepo,
+  submodulePath: string,
+  options: GitStatusOptions,
+): Promise<string | null> {
+  try {
+    // `ls-tree HEAD <path>` prints: `<mode> commit <sha>\t<path>` for a gitlink.
+    const result = await runGit(repo, ['ls-tree', 'HEAD', submodulePath], options);
+    const line = result.stdout.split('\n').find(l => l.trim().length > 0);
+    if (!line) return null;
+    const match = line.match(/^\s*\d+\s+commit\s+([0-9a-f]{40})\b/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Actual checked-out HEAD SHA of a submodule, or null if uninitialized/unreadable. */
+async function readSubmoduleHeadSha(
+  repo: ResolvedGitRepo,
+  repoPath: string,
+  options: GitStatusOptions,
+): Promise<string | null> {
+  try {
+    // Run in the submodule worktree via cwd (inside the superproject root, so the
+    // executor's path-inside-repo guard is satisfied) rather than resolving the
+    // submodule as a fresh repo — that would cost an extra `rev-parse --show-toplevel`
+    // spawn per submodule, which is exactly the Windows spawn cost this fix removes.
+    const result = await runGit(repo, ['rev-parse', 'HEAD'], { ...options, cwd: repoPath });
+    const sha = result.stdout.trim();
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
 async function enrichSubmoduleWorktreeStatus(
   repo: ResolvedGitRepo,
   submodule: GitSubmoduleStatus,
@@ -594,37 +709,3 @@ async function enrichSubmoduleWorktreeStatus(
   }
 }
 
-function parseSubmoduleStatusOutput(
-  output: string,
-  repoRoot: string,
-  ignorePaths?: string[],
-): GitSubmoduleStatus[] {
-  const submodules: GitSubmoduleStatus[] = [];
-  const ignoreSet = new Set(ignorePaths || []);
-
-  for (const line of output.split('\n')) {
-    if (!line.trim()) continue;
-
-    // Format: [+-U ]<commit> <path> (<branch>)
-    // - = not initialized, + = gitlink out of sync, U = conflict, ' ' = aligned.
-    const match = line.match(/^([\-+U\s])([0-9a-f]{40})\s+(\S+)(?:\s+\(([^)]+)\))?/);
-    if (!match) continue;
-
-    const prefix = match[1];
-    const commit = match[2];
-    const path = match[3];
-
-    if (ignoreSet.has(path)) continue;
-
-    submodules.push({
-      path,
-      commit,
-      repoPath: repoRoot + '/' + path,
-      dirty: prefix === 'U',
-      outOfSync: prefix === '-' || prefix === '+',
-      lastCheckedAt: Date.now(),
-    });
-  }
-
-  return submodules;
-}

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-events-coordinator.ts

@@ -1027,7 +1027,11 @@ export async function triggerMeshQueue(components: DaemonComponents, meshId: str
 
     const remoteCandidates: IdleCandidate[] = [];
     for (const idle of remoteSessions) {
-        const node = mesh.nodes.find((n: any) => n.id === idle.nodeId);
+        // Match with the shared 3-form normalizer (id / nodeId / node_id), not raw
+        // `n.id`, so an inline-cached worktree node whose identity arrived under a
+        // different form is not silently dropped — leaving a remote idle session
+        // unable to claim its pending queue task.
+        const node = mesh.nodes.find((n: any) => meshNodeIdMatches(n, idle.nodeId));
         if (node) {
             remoteIdleSessionsChecked += 1;
             remoteCandidates.push({ nodeId: idle.nodeId, sessionId: idle.sessionId, providerType: idle.providerType, origin: 'remote', node });