@adhdev/daemon-core 0.9.82-rc.522 → 0.9.82-rc.524

package/src/commands/router.ts

@@ -316,6 +316,15 @@ export class DaemonCommandRouter {
     runningRefineBatchJobs = new Map<string, MeshRefineBatchJobHandle>();
     /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
     terminalRefineBatchJobs = new Map<string, MeshRefineBatchTerminalJob>();
+    /**
+     * DS2: in-process refinement leases keyed by `${repoRoot}::${baseBranch}`. Serialize
+     * the base-mutating window (candidate-SHA pin → merge → push) of concurrent single-node
+     * refines that target the SAME base branch in the same repo, so two refines cannot both
+     * validate against one baseHead and then race their merges (the base-movement race). The
+     * batch path is already sequential, so this only matters for overlapping single-node
+     * async jobs. Value = the meshId:nodeId job key holding the lease (for diagnostics).
+     */
+    refineBaseLeases = new Map<string, string>();
 
     constructor(deps: CommandRouterDeps) {
         this.deps = deps;

package/src/git/git-status.ts

@@ -443,6 +443,29 @@ function isNonRuntimeRootFile(file: string, policy: ResolvedChangeImpactPolicy):
 export interface ChangedPackageClassification {
   isDaemonAffecting: boolean;
   affectedPackages: string[];
+  /**
+   * DOCS-ROOT: three-way change area, refining the binary isDaemonAffecting so a
+   * docs-only branch is distinguishable from a code (web) branch:
+   *   'daemon' — a daemon-runtime package (or an unknown/ambiguous path) changed;
+   *              full validation + daemon rebuild/restart required.
+   *   'web'    — only web-only packages changed; web validation but no daemon restart.
+   *   'none'   — no package changed at all; every changed file is a benign non-runtime
+   *              root file (docs/markers). No code validation is meaningful — only an
+   *              explicit docs-scoped profile (e.g. docs:verify) should run.
+   * Derived from the same facts as isDaemonAffecting, so it never contradicts it
+   * (changeArea === 'daemon' ⇔ isDaemonAffecting === true).
+   */
+  changeArea: ChangeImpactKind;
+}
+
+/**
+ * Derive the three-way {@link ChangeImpactKind} from the binary daemon verdict and the
+ * affected-package set, using the exact rule the stale-build warning layer already
+ * applies: daemon-affecting → 'daemon'; else any package changed → 'web'; else (only
+ * benign non-runtime files, no package) → 'none'.
+ */
+function deriveChangeArea(isDaemonAffecting: boolean, affectedPackages: string[]): ChangeImpactKind {
+  return isDaemonAffecting ? 'daemon' : affectedPackages.length > 0 ? 'web' : 'none';
 }
 
 /**
@@ -452,7 +475,10 @@ export interface ChangedPackageClassification {
  * gitlinks — a bare submodule path (e.g. `oss`) is runtime-ambiguous from the root's
  * point of view, but its *content* diff may be entirely web-only.
  */
-interface ChangedFileListClassification extends ChangedPackageClassification {
+// Intermediate verdict: carries the binary daemon signal + ambiguous paths, but NOT
+// the derived `changeArea` — that is computed once at the final classifyChangedPackages
+// boundary (`strip` / the submodule folds) so the file-list bucketer stays area-agnostic.
+interface ChangedFileListClassification extends Omit<ChangedPackageClassification, 'changeArea'> {
   /** Non-package paths that were not recognized as benign root files. */
   ambiguousNonPackageFiles: string[];
 }
@@ -517,10 +543,11 @@ async function classifyDaemonBuildChange(
       .split('\n')
       .map((line) => line.trim())
       .filter(Boolean);
-    return classifyChangedFileList(files, policy);
+    const { isDaemonAffecting, affectedPackages } = classifyChangedFileList(files, policy);
+    return { isDaemonAffecting, affectedPackages, changeArea: deriveChangeArea(isDaemonAffecting, affectedPackages) };
   } catch {
     // diff probe failed → can't prove web-only; stay conservative.
-    return { isDaemonAffecting: true, affectedPackages: [] };
+    return { isDaemonAffecting: true, affectedPackages: [], changeArea: 'daemon' };
   }
 }
 
@@ -584,7 +611,8 @@ async function refineVerdictThroughSubmodules(
   policy: ResolvedChangeImpactPolicy,
   rootVerdict: ChangedFileListClassification,
 ): Promise<ChangedPackageClassification> {
-  const strip = ({ isDaemonAffecting, affectedPackages }: ChangedPackageClassification) => ({ isDaemonAffecting, affectedPackages });
+  const strip = ({ isDaemonAffecting, affectedPackages }: ChangedFileListClassification): ChangedPackageClassification =>
+    ({ isDaemonAffecting, affectedPackages, changeArea: deriveChangeArea(isDaemonAffecting, affectedPackages) });
   const ambiguous = rootVerdict.ambiguousNonPackageFiles;
   // Fast path: nothing to descend into, or the root is daemon-affecting for a reason
   // other than an ambiguous path (an unknown/daemon package). Submodule descent only
@@ -628,9 +656,11 @@ async function refineVerdictThroughSubmodules(
     if (subVerdict.isDaemonAffecting) {
       // The submodule content really does touch daemon runtime → keep daemon-affecting,
       // surfacing the submodule packages so the reason is visible.
+      const affectedPackages = [...new Set([...rootVerdict.affectedPackages, ...subVerdict.affectedPackages])].sort();
       return {
         isDaemonAffecting: true,
-        affectedPackages: [...new Set([...rootVerdict.affectedPackages, ...subVerdict.affectedPackages])].sort(),
+        affectedPackages,
+        changeArea: deriveChangeArea(true, affectedPackages),
       };
     }
     submoduleAffectedPackages.push(...subVerdict.affectedPackages);
@@ -642,9 +672,11 @@ async function refineVerdictThroughSubmodules(
   const rootPackagesBenign = rootVerdict.affectedPackages.every(
     (p) => policy.webOnlyPackages.has(p) && !policy.daemonRuntimePackages.has(p),
   );
+  const affectedPackages = [...new Set([...rootVerdict.affectedPackages, ...submoduleAffectedPackages])].sort();
   return {
     isDaemonAffecting: !rootPackagesBenign,
-    affectedPackages: [...new Set([...rootVerdict.affectedPackages, ...submoduleAffectedPackages])].sort(),
+    affectedPackages,
+    changeArea: deriveChangeArea(!rootPackagesBenign, affectedPackages),
   };
 }
 

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

@@ -15,12 +15,12 @@ import { traceMeshEventDrop } from './mesh-event-trace.js';
 import { awaitWithWarmupDeadline, resolveWarmupDeadlineOpts } from './mesh-warmup-deadline.js';
 import { resolveDelegatedWorkerAutoApprove, resolveProviderMaxParallel, resolveNodeSchedulingPriority, normalizeMeshSchedulingStrategy, resolveMaxParallelTasks, resolveMaxReadonlyParallelTasks } from '../repo-mesh-types.js';
 import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
-import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalDaemonId, normalizeMeshWorkspaceForCompare, meshWorkspacesEquivalent, sessionIdsEquivalent, normalizeNodeCapabilitySlots, isMeshTaskDifficulty, withStatusProbeMarker, type MeshNodeIdentified, type NodeCapabilitySlot, type MeshTaskDifficulty } from '@adhdev/mesh-shared';
+import { normalizeMeshNodeId, meshNodeIdMatches, daemonIdsEquivalent, canonicalDaemonId, expandDaemonIdForms, normalizeMeshWorkspaceForCompare, meshWorkspacesEquivalent, sessionIdsEquivalent, normalizeNodeCapabilitySlots, isMeshTaskDifficulty, withStatusProbeMarker, type MeshNodeIdentified, type NodeCapabilitySlot, type MeshTaskDifficulty } from '@adhdev/mesh-shared';
 import { resolveNodeCapabilitySlots } from './mesh-node-slots.js';
 import { findTerminalLedgerEvidenceForTask, hasUnterminalDirectDispatchLedgerEntry } from './mesh-events-stale.js';
 import { readNonEmptyString } from './mesh-events-utils.js';
 import { readMeshNodeDaemonId, isMeshNodeHealthLaunchable } from './mesh-node-identity.js';
-import { queuePendingMeshCoordinatorEvent, retractPendingDispatchBlockedEvent } from './mesh-events-pending.js';
+import { queuePendingMeshCoordinatorEvent, retractPendingDispatchBlockedEvent, drainPendingMeshCoordinatorEvents } from './mesh-events-pending.js';
 import { isWorktreeBootstrapStaleRunning, shouldDeferDispatchForBootstrap } from './worktree-bootstrap-config.js';
 import { isWithinCloneBootstrapGrace } from './mesh-clone-grace.js';
 import { beginTaskDispatchInFlight, endTaskDispatchInFlight } from './mesh-task-inflight.js';
@@ -2746,6 +2746,68 @@ export async function runContinuousAutoFastForwardScan(components: DaemonCompone
     }
 }
 
+/**
+ * DS3: drain and act on `coordinator_catchup` markers queued by a remote node's Refinery
+ * after it pushed the base branch to origin. The originating coordinator is THIS daemon;
+ * its local base checkout is now behind origin. Bring it up to date with a guarded ff-only
+ * merge — but ONLY when the coordinator base node has no active mesh work (busy → leave the
+ * marker for the next idle tick) and fastForwardMeshNode's own clean/ahead=0/behind>0 gate
+ * is satisfied (ahead/diverged/dirty → it returns a structured block, never a rebase).
+ *
+ * These markers are drained on a DEDICATED event-name filter so they never reach the
+ * coordinator chat-injection path (they are actions, not messages). A busy/blocked node
+ * re-queues the marker so a later idle tick retries; a successful/no-op ff consumes it.
+ */
+export async function runPendingCoordinatorCatchupScan(components: DaemonComponents, mesh: any): Promise<void> {
+    const meshId = readNonEmptyString(mesh?.id);
+    if (!meshId) return;
+    const localIds = expandDaemonIdForms([
+        readNonEmptyString((components as { statusInstanceId?: string }).statusInstanceId),
+        readNonEmptyString(loadConfig().machineId),
+    ]);
+    let markers: Awaited<ReturnType<typeof drainPendingMeshCoordinatorEvents>> = [];
+    try {
+        markers = drainPendingMeshCoordinatorEvents(
+            meshId,
+            localIds.length > 0 ? localIds : undefined,
+            { onlyEvents: new Set(['coordinator_catchup']) },
+        );
+    } catch (e: any) {
+        LOG.warn('MeshReconcile', `Coordinator-catchup drain failed for mesh ${meshId}: ${e?.message || e}`);
+        return;
+    }
+    if (markers.length === 0) return;
+    const nodes = Array.isArray(mesh?.nodes) ? mesh.nodes : [];
+    for (const marker of markers) {
+        const meta = (marker.metadataEvent || {}) as Record<string, unknown>;
+        const nodeId = readNonEmptyString(marker.nodeId) || readNonEmptyString(meta.nodeId as string);
+        const workspace = readNonEmptyString(marker.workspace) || readNonEmptyString(meta.workspace as string);
+        const baseBranch = readNonEmptyString(meta.baseBranch as string);
+        if (!workspace) continue;
+        // Busy node → re-queue and defer to the next idle tick (never advance a base a
+        // session is actively working on).
+        if (nodeId && nodeHasActiveMeshWork(components, meshId, nodeId)) {
+            try { queuePendingMeshCoordinatorEvent(marker); } catch { /* best-effort re-queue */ }
+            continue;
+        }
+        try {
+            const ff = await fastForwardMeshNode({
+                meshId,
+                ...(nodeId ? { nodeId } : {}),
+                workspace,
+                ...(baseBranch ? { branch: baseBranch } : {}),
+                mode: 'merge',
+                execute: true,
+                trigger: 'refine_post_push_catchup',
+                allowAutoPublishSubmoduleMainCommits: mesh?.policy?.allowAutoPublishSubmoduleMainCommits === true,
+            });
+            LOG.info('MeshReconcile', `Coordinator catch-up ff for ${meshId}/${nodeId || workspace}: ${ff.code} (executed=${ff.executed})`);
+        } catch (e: any) {
+            LOG.warn('MeshReconcile', `Coordinator catch-up ff failed for ${meshId}/${nodeId || workspace}: ${e?.message || e}`);
+        }
+    }
+}
+
 export function runIdleMaintenanceThenAssignQueue(components: DaemonComponents, args: {
     meshId: string;
     nodeId: string;

package/src/mesh/mesh-reconcile-loop.ts

@@ -61,7 +61,7 @@ import { readNonEmptyString, readMeshCompletionSummary, buildMeshSystemMessage }
 import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { expandDaemonIdForms, daemonIdsEquivalent, sessionIdsEquivalent, meshNodeIdMatches, withStatusProbeMarker } from '@adhdev/mesh-shared';
 import { getQueue, reclaimStrandedAssignedTask, updateTaskStatus } from './mesh-work-queue.js';
-import { resolveSessionBusyVerdict, runContinuousAutoFastForwardScan } from './mesh-queue-assignment.js';
+import { resolveSessionBusyVerdict, runContinuousAutoFastForwardScan, runPendingCoordinatorCatchupScan } from './mesh-queue-assignment.js';
 import { readLedgerEntries } from './mesh-ledger.js';
 import type { MeshLedgerEntry } from './mesh-ledger.js';
 import { findTerminalLedgerEvidenceForTask } from './mesh-events-stale.js';
@@ -1082,6 +1082,23 @@ export async function runMeshReconcileTick(components: DaemonComponents): Promis
         }
     }
 
+    // ── PHASE 2.6: DS3 coordinator local catch-up ──────────────────────────────
+    // Drain `coordinator_catchup` markers a remote node's Refinery queued after pushing
+    // the base to origin, and guarded-ff this daemon's own coordinator base checkout up to
+    // the pushed commit (busy → deferred to a later tick; ahead/diverged/dirty → the ff
+    // helper structured-blocks, never rebases). Runs for EVERY mesh this daemon hosts
+    // (not gated on continuous mode) and BEFORE PHASE 3 so a caught-up base is current
+    // before any new task is dispatched. No markers → immediate no-op.
+    for (const mesh of listMeshes()) {
+        const selfIds = resolveCoordinatorSelfIds(mesh, drainDaemonIds);
+        if (!daemonHostsMesh(mesh, selfIds)) continue;
+        try {
+            await runPendingCoordinatorCatchupScan(components, mesh);
+        } catch (e: any) {
+            LOG.warn('MeshReconcile', `Coordinator catch-up scan failed for mesh ${mesh.id}: ${e?.message || e}`);
+        }
+    }
+
     // ── PHASE 2.7: continuous remote auto fast-forward (opt-in, default OFF) ────
     // mode:"continuous" + remoteNodes:true only. Catch up an online/clean/behind
     // REMOTE base node that emits no fresh idle edge (e.g. a long-idle base node while

package/src/mesh/mesh-refine-gates.ts

@@ -16,7 +16,7 @@ import { getGitRepoStatus } from '../git/git-status.js';
 import type { ChangedPackageClassification } from '../git/git-status.js';
 import * as yaml from 'js-yaml';
 import { loadMeshRefineConfig, resolveMeshRefineValidationPlan } from '../mesh/refine-config.js';
-import type { MeshRefineValidationCommandPlan } from '../mesh/refine-config.js';
+import type { MeshRefineValidationCommandPlan, MeshRefineValidationScope } from '../mesh/refine-config.js';
 import { evaluateWorktreeBootstrapState, loadMeshWorktreeBootstrapConfig, runMeshWorktreeBootstrap, resolveSubmoduleDefaultBranch } from '../mesh/worktree-bootstrap-config.js';
 import type { WorktreeBootstrapState } from '../mesh/worktree-bootstrap-config.js';
 import { basename as pathBasename, join as pathJoin, resolve as pathResolve } from 'path';
@@ -85,8 +85,12 @@ type MeshRefineValidationSummary = {
     changeImpact?: {
         isDaemonAffecting: boolean;
         affectedPackages: string[];
+        /** DOCS-ROOT: three-way change area ('none' | 'web' | 'daemon') when known. */
+        changeArea?: MeshRefineValidationScope;
         /** displayCommands skipped because the daemon scope is unaffected. */
         skippedDaemonCommands?: string[];
+        /** DOCS-ROOT: displayCommands skipped because the change-area scope excluded them. */
+        skippedScopeCommands?: string[];
     };
 };
 
@@ -1474,6 +1478,9 @@ export function buildMeshRefineValidationPlan(mesh: any, workspace: string): Rec
         source: command.source,
         cwd: command.cwd,
         timeoutMs: command.timeoutMs,
+        // DOCS-ROOT: surface the change-impact scopes so `mesh_refine_config` shows which
+        // area(s) each command runs in (absent → every area).
+        ...(command.scopes ? { scopes: command.scopes } : {}),
     });
     return {
         source: plan.source,
@@ -1633,9 +1640,48 @@ export async function runMeshRefineValidationGate(
     };
 
     const scopeUnaffectedDaemon = opts?.changeImpact?.isDaemonAffecting === false;
+    // DOCS-ROOT: the branch's three-way change area ('none' | 'web' | 'daemon'), when
+    // known. `none` (docs-only) is the case this scoping exists for: a docs-only branch
+    // must skip every code validation command and run ONLY commands explicitly scoped
+    // ['none'] (e.g. a light docs:verify profile). Fail-open: an unknown change area
+    // (changeImpact undefined) leaves changeArea undefined → no scope filtering, the full
+    // command set runs exactly as before.
+    const changeArea: MeshRefineValidationScope | undefined = opts?.changeImpact?.changeArea;
+    // A command runs in the current change area when: the branch area is unknown (run
+    // everything), OR the command declared no scopes (runs everywhere), OR the command's
+    // scopes include the current area. When the branch is docs-only ('none'), an
+    // un-scoped command does NOT run — only commands that explicitly opted into 'none'.
+    const commandRunsInArea = (candidate: MeshRefineValidationCommand): boolean => {
+        if (!changeArea) return true; // fail-open on unknown area
+        const scopes = candidate.scopes;
+        if (scopes && scopes.length) return scopes.includes(changeArea);
+        // Un-scoped command: runs in web/daemon (code areas) but NOT on a docs-only
+        // branch — there is nothing for a code command to validate when only docs changed.
+        return changeArea !== 'none';
+    };
     const skippedDaemonCommands: string[] = [];
+    const skippedScopeCommands: string[] = [];
     const commandsToRun: MeshRefineValidationCommand[] = [];
     for (const candidate of selection.commands) {
+        // DOCS-ROOT scope filter runs first: it is the explicit, config-declared signal
+        // and supersedes the coarse daemon heuristic. A command excluded by change-area
+        // scope is recorded skipped with `unaffected_change_scope`.
+        if (!commandRunsInArea(candidate)) {
+            skippedScopeCommands.push(candidate.displayCommand);
+            summary.commandsRun.push({
+                command: candidate.command,
+                args: candidate.args,
+                displayCommand: candidate.displayCommand,
+                category: candidate.category,
+                source: candidate.source,
+                passed: true,
+                skipped: true,
+                skipReason: 'unaffected_change_scope',
+                changeArea,
+                ...(candidate.scopes ? { scopes: candidate.scopes } : {}),
+            });
+            continue;
+        }
         if (scopeUnaffectedDaemon && isDaemonScopedCommand(candidate)) {
             skippedDaemonCommands.push(candidate.displayCommand);
             // Record the skip so it's visible in the summary, never silently dropped.
@@ -1657,7 +1703,9 @@ export async function runMeshRefineValidationGate(
         summary.changeImpact = {
             isDaemonAffecting: opts.changeImpact.isDaemonAffecting,
             affectedPackages: opts.changeImpact.affectedPackages,
+            ...(changeArea ? { changeArea } : {}),
             ...(skippedDaemonCommands.length ? { skippedDaemonCommands } : {}),
+            ...(skippedScopeCommands.length ? { skippedScopeCommands } : {}),
         };
     }
 

package/src/mesh/refine-config.ts

@@ -5,6 +5,22 @@ import * as yaml from 'js-yaml';
 export const MESH_REFINE_VALIDATION_CATEGORIES = ['typecheck', 'test', 'lint', 'build'] as const;
 export type MeshRefineValidationCategory = typeof MESH_REFINE_VALIDATION_CATEGORIES[number];
 
+/**
+ * DOCS-ROOT: change-impact scope for a validation command. Mirrors ChangeImpactKind
+ * (git-status) so a command can declare WHICH change areas it should run in:
+ *   'daemon' — run when a daemon-runtime package changed,
+ *   'web'    — run when a web package changed,
+ *   'none'   — run when ONLY docs/markers changed (a docs-only branch).
+ * A command with NO `scopes` runs in every area (backward-compatible: the full set
+ * runs as before). This lets a repo declare a light docs-only profile — e.g. a
+ * `docs:verify` command scoped `['none']` — that runs on a docs-only branch while the
+ * heavy typecheck/test commands (implicitly all-areas, or scoped ['web','daemon'])
+ * are skipped. The scoping is applied only when the branch's changeArea is known;
+ * fail-open (unknown change area → every command runs).
+ */
+export const MESH_REFINE_VALIDATION_SCOPES = ['none', 'web', 'daemon'] as const;
+export type MeshRefineValidationScope = typeof MESH_REFINE_VALIDATION_SCOPES[number];
+
 export interface RepoMeshRefineValidationCommandConfig {
     /** Executable name or a whitespace-tokenized command string. Never executed through a shell. */
     command: string;
@@ -15,6 +31,12 @@ export interface RepoMeshRefineValidationCommandConfig {
     timeoutMs?: number;
     outputLimitBytes?: number;
     env?: Record<string, string>;
+    /**
+     * DOCS-ROOT: change-impact scopes this command runs in ('none' | 'web' | 'daemon').
+     * Omitted → runs in every area (backward-compatible). Empty array is treated the
+     * same as omitted (runs everywhere) rather than "runs nowhere".
+     */
+    scopes?: MeshRefineValidationScope[];
 }
 
 export interface RepoMeshRefineConfig {
@@ -57,6 +79,8 @@ export interface MeshRefineValidationCommandPlan {
     timeoutMs?: number;
     outputLimitBytes?: number;
     env?: Record<string, string>;
+    /** DOCS-ROOT: normalized change-impact scopes; absent → runs in every area. */
+    scopes?: MeshRefineValidationScope[];
 }
 
 export interface MeshRefineConfigLoadResult {
@@ -133,6 +157,11 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                             timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
                             outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
                             env: { type: 'object', additionalProperties: { type: 'string' } },
+                            scopes: {
+                                type: 'array',
+                                items: { enum: [...MESH_REFINE_VALIDATION_SCOPES] },
+                                description: "DOCS-ROOT: change-impact scopes this command runs in ('none'=docs-only, 'web', 'daemon'). Omitted/empty → runs in every area.",
+                            },
                         },
                     },
                 },
@@ -152,6 +181,10 @@ export const MESH_REFINE_CONFIG_SCHEMA = {
                             timeoutMs: { type: 'number', minimum: 1000, maximum: 600000 },
                             outputLimitBytes: { type: 'number', minimum: 1024, maximum: 1048576 },
                             env: { type: 'object', additionalProperties: { type: 'string' } },
+                            scopes: {
+                                type: 'array',
+                                items: { enum: [...MESH_REFINE_VALIDATION_SCOPES] },
+                            },
                         },
                     },
                 },
@@ -239,6 +272,16 @@ export function normalizeMeshCommandConfig(entry: unknown, source: string): { co
     if (entry.env !== undefined && (!isMeshConfigRecord(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
         return { rejected: { source, command: commandText, reason: 'env must be an object of string values' } };
     }
+    // DOCS-ROOT: validate + normalize the optional change-impact scopes.
+    let scopes: MeshRefineValidationScope[] | undefined;
+    if (entry.scopes !== undefined) {
+        if (!Array.isArray(entry.scopes) || !entry.scopes.every(s => (MESH_REFINE_VALIDATION_SCOPES as readonly string[]).includes(s as string))) {
+            return { rejected: { source, command: commandText, reason: `scopes must be an array of ${MESH_REFINE_VALIDATION_SCOPES.join(' | ')}` } };
+        }
+        // De-dupe; an empty array means "no restriction" (runs everywhere), so drop it.
+        const deduped = [...new Set(entry.scopes as MeshRefineValidationScope[])];
+        scopes = deduped.length ? deduped : undefined;
+    }
 
     return {
         command: {
@@ -251,6 +294,7 @@ export function normalizeMeshCommandConfig(entry: unknown, source: string): { co
             ...(typeof entry.timeoutMs === 'number' ? { timeoutMs: entry.timeoutMs } : {}),
             ...(typeof entry.outputLimitBytes === 'number' ? { outputLimitBytes: entry.outputLimitBytes } : {}),
             ...(isMeshConfigRecord(entry.env) ? { env: entry.env as Record<string, string> } : {}),
+            ...(scopes ? { scopes } : {}),
         },
     };
 }