@adhdev/daemon-core 1.0.18-rc.17 → 1.0.18-rc.18

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

@@ -15,6 +15,7 @@ import type { MeshMissionSummary, MeshMissionSlimSummary } from './mesh/mesh-mis
 import type { MeshMagiActivitySummary } from './mesh/mesh-magi-status.js';
 import type { MagiKindPanelMap, DifficultyBrainMap, NodeCapabilitySlot } from '@adhdev/mesh-shared';
 import type { ProviderModule } from './providers/contracts.js';
+import type { RepoMeshDeclarativeConfig } from './config/mesh-json-config.js';
 export interface RepoMesh {
     id: string;
     name: string;
@@ -530,13 +531,34 @@ export declare function normalizeAutoFastForwardPolicy(value: unknown): NonNulla
 export declare function mergeAndNormalizePolicy(base: RepoMeshPolicy | undefined, patch: Partial<RepoMeshPolicy> | undefined): RepoMeshPolicy;
 /**
  * Resolve delegated worker auto-approve. Legacy providers return a boolean. Providers
- * with modes return the default mode id, except a dangerous default is downgraded to a
+ * with modes return a mode id, except a dangerous mode is downgraded to a
  * non-dangerous PTY mode unless mesh/node policy explicitly opts in.
+ *
+ * THREE EXPLICIT STAGES — do not collapse them; the ordering is a hard MAGI
+ * invariant:
+ *
+ *   ① ENABLE gate (machine-local policy only): node boolean > mesh boolean.
+ *      `enabled=false` returns `false` IMMEDIATELY, BEFORE any mode selection.
+ *      The repo `mesh.json` providerDefaults has ZERO influence here — a
+ *      node/mesh opt-out is never overridden by a repo-declared requested mode.
+ *
+ *   ② MODE selection (only when enabled === true):
+ *        task override [FUTURE — param reserved below, not yet wired] >
+ *        repo mesh.json providerDefaults.autoApproveModes[providerType] >
+ *        provider spec autoApproveModes.default.
+ *      A repo-requested mode ID is adopted ONLY when it exists in the provider's
+ *      own `autoApproveModes.modes`; an unknown/stale/typo'd ID is IGNORED and we
+ *      fall back to the provider default (fail-closed: never coerce into a
+ *      dangerous mode via a bad ID).
+ *
+ *   ③ DANGEROUS gate: whichever mode stage ② picked, if it is dangerous and the
+ *      machine-local delegatedWorkerDangerousModeAllow is not set, downgrade to a
+ *      non-dangerous PTY-parse mode (or `false` if none exists).
  */
-export declare function resolveDelegatedWorkerAutoApprove(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, provider?: Pick<ProviderModule, 'autoApproveModes'> | null): boolean | string;
+export declare function resolveDelegatedWorkerAutoApprove(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, provider?: Pick<ProviderModule, 'autoApproveModes'> | null, repoConfig?: RepoMeshDeclarativeConfig | null, providerType?: string | null): boolean | string;
 export declare function resolveDelegatedWorkerDangerousModeAllow(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerDangerousModeAllow'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerDangerousModeAllow'> | null): boolean;
 /** Shape a boolean-or-mode resolution for the settings precedence contract. */
-export declare function delegatedWorkerAutoApproveSettings(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, provider?: Pick<ProviderModule, 'autoApproveModes'> | null): {
+export declare function delegatedWorkerAutoApproveSettings(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null, provider?: Pick<ProviderModule, 'autoApproveModes'> | null, repoConfig?: RepoMeshDeclarativeConfig | null, providerType?: string | null): {
     autoApprove: boolean | undefined;
     autoApproveMode: string | undefined;
     delegatedWorkerDangerousModeAllow: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "1.0.18-rc.17",
+  "version": "1.0.18-rc.18",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "1.0.18-rc.17",
-    "@adhdev/session-host-core": "1.0.18-rc.17",
+    "@adhdev/mesh-shared": "1.0.18-rc.18",
+    "@adhdev/session-host-core": "1.0.18-rc.18",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/commands/med-family/mesh-crud.ts

@@ -399,6 +399,161 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
         }
     },
 
+    // READ path for `.adhdev/mesh.json` — returns the currently-committed repo
+    // config (parsed + normalized) for a workspace so a UI can render/edit the
+    // existing declarative zones (notably `providerDefaults.autoApproveModes`)
+    // WITHOUT re-deriving them from the machine-local scaffold. Never writes.
+    // `config` is undefined when no repo file exists (sourceType 'unavailable') or
+    // it is unparseable (sourceType 'invalid', with the parse error surfaced).
+    read_mesh_json_config: async (_ctx: MedFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' && args.workspace.trim() ? args.workspace.trim() : process.cwd();
+        try {
+            const { loadRepoMeshJsonConfig } = await import('../../config/mesh-json-config.js');
+            const loaded = loadRepoMeshJsonConfig(workspace);
+            return {
+                success: true,
+                workspace,
+                sourceType: loaded.sourceType,
+                source: loaded.source,
+                ...(loaded.path ? { path: loaded.path } : {}),
+                ...(loaded.error ? { error: loaded.error } : {}),
+                config: loaded.config,
+                // Convenience projection so the UI does not have to reach into config.
+                providerDefaults: loaded.config?.providerDefaults,
+            };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
+    // Partial-edit WRITE path for `.adhdev/mesh.json` `providerDefaults` — a
+    // READ-MODIFY-WRITE that preserves operator hand-edits. Unlike
+    // write_mesh_json_config (which rebuilds the WHOLE file from the machine-local
+    // scaffold and can silently drop hand-edited zones), this parses the existing
+    // repo file, merges ONLY the providerDefaults.autoApproveModes zone, and
+    // re-serializes — coordinator prompt, operating notes and limits authored in
+    // the repo are carried through untouched. Defaults to dry-run.
+    //
+    // args: { workspace?, autoApproveModes: Record<providerType,modeId>, write?, merge? }
+    //   merge=true (default): per-provider merge into the existing map; a modeId of
+    //     '' | null removes that provider's entry. merge=false: REPLACE the whole
+    //     autoApproveModes map with the supplied one.
+    set_mesh_provider_defaults: async (_ctx: MedFamilyContext, args: any) => {
+        const workspace = typeof args?.workspace === 'string' && args.workspace.trim() ? args.workspace.trim() : process.cwd();
+        const write = args?.write === true;
+        const merge = args?.merge !== false; // default true
+        const inputModes = args?.autoApproveModes;
+        if (inputModes !== undefined && (typeof inputModes !== 'object' || inputModes === null || Array.isArray(inputModes))) {
+            return { success: false, error: 'autoApproveModes must be an object (providerType → modeId) when provided' };
+        }
+        try {
+            const {
+                loadRepoMeshJsonConfig,
+                normalizeRepoMeshDeclarativeConfig,
+                MESH_JSON_CONFIG_LOCATIONS,
+            } = await import('../../config/mesh-json-config.js');
+            const { existsSync, readFileSync, mkdirSync, writeFileSync } = await import('fs');
+            const { dirname, join } = await import('path');
+            const yaml = await import('js-yaml');
+
+            const relativePath = MESH_JSON_CONFIG_LOCATIONS[0];
+
+            // Read-modify-write: parse the EXISTING on-disk document (preferring the
+            // first existing json/yaml variant) so unrelated zones survive verbatim.
+            let baseDoc: Record<string, any> = { version: 1 };
+            let existingPath = join(workspace, relativePath);
+            let existedAsYaml = false;
+            for (const relative of MESH_JSON_CONFIG_LOCATIONS) {
+                const candidate = join(workspace, relative);
+                if (!existsSync(candidate)) continue;
+                try {
+                    const text = readFileSync(candidate, 'utf-8');
+                    const parsed = /\.json$/i.test(candidate) ? JSON.parse(text) : yaml.load(text);
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        baseDoc = parsed as Record<string, any>;
+                        existingPath = candidate;
+                        existedAsYaml = !/\.json$/i.test(candidate);
+                    }
+                } catch (e: any) {
+                    return { success: false, error: `existing ${relative} is unparseable, refusing to overwrite: ${e?.message || e}` };
+                }
+                break;
+            }
+
+            // Merge ONLY the providerDefaults.autoApproveModes zone.
+            const existingPd = baseDoc.providerDefaults && typeof baseDoc.providerDefaults === 'object' && !Array.isArray(baseDoc.providerDefaults)
+                ? baseDoc.providerDefaults as Record<string, any>
+                : {};
+            const existingModes = existingPd.autoApproveModes && typeof existingPd.autoApproveModes === 'object' && !Array.isArray(existingPd.autoApproveModes)
+                ? { ...existingPd.autoApproveModes as Record<string, string> }
+                : {};
+
+            const nextModes: Record<string, string> = merge ? existingModes : {};
+            if (inputModes) {
+                for (const [providerType, modeId] of Object.entries(inputModes as Record<string, unknown>)) {
+                    const type = typeof providerType === 'string' ? providerType.trim() : '';
+                    if (!type) continue;
+                    const id = typeof modeId === 'string' ? modeId.trim() : '';
+                    if (id) nextModes[type] = id;
+                    else delete nextModes[type]; // '' / null → remove this provider's entry
+                }
+            }
+
+            const nextDoc: Record<string, any> = { ...baseDoc, version: 1 };
+            if (Object.keys(nextModes).length) {
+                nextDoc.providerDefaults = { ...existingPd, autoApproveModes: nextModes };
+            } else {
+                // No entries left → drop the zone entirely so we don't leave an empty stub.
+                if (nextDoc.providerDefaults) {
+                    const { autoApproveModes, ...restPd } = nextDoc.providerDefaults;
+                    if (Object.keys(restPd).length) nextDoc.providerDefaults = restPd;
+                    else delete nextDoc.providerDefaults;
+                }
+            }
+
+            // Validate the merged document before it ever touches disk.
+            const validation = normalizeRepoMeshDeclarativeConfig(nextDoc);
+            if (!validation.valid) {
+                return { success: false, error: `merged mesh.json is invalid: ${validation.errors.join('; ')}` };
+            }
+
+            // Serialize in the on-disk format (JSON unless the existing file was YAML).
+            const absolutePath = existingPath;
+            const serialized = existedAsYaml
+                ? yaml.dump(nextDoc, { indent: 2 })
+                : `${JSON.stringify(nextDoc, null, 2)}\n`;
+
+            if (!write) {
+                return {
+                    success: true,
+                    written: false,
+                    dryRun: true,
+                    path: absolutePath,
+                    relativePath,
+                    merge,
+                    providerDefaults: nextDoc.providerDefaults,
+                    preview: serialized,
+                    note: 'Dry-run: nothing written. Re-run with write=true to persist. Only the providerDefaults zone is merged; other repo zones are preserved.',
+                };
+            }
+
+            mkdirSync(dirname(absolutePath), { recursive: true });
+            writeFileSync(absolutePath, serialized, 'utf-8');
+            return {
+                success: true,
+                written: true,
+                dryRun: false,
+                path: absolutePath,
+                relativePath,
+                merge,
+                providerDefaults: nextDoc.providerDefaults,
+                note: 'Wrote providerDefaults into .adhdev/mesh.json (read-modify-write; other zones preserved). Commit it to the repo.',
+            };
+        } catch (e: any) {
+            return { success: false, error: e.message };
+        }
+    },
+
     delete_mesh: async (_ctx: MedFamilyContext, args: any) => {
         const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
         if (!meshId) return { success: false, error: 'meshId required' };

package/src/config/mesh-json-config.ts

@@ -19,6 +19,18 @@
  * machine-local policy directly. The repo file shapes the coordinator prompt and
  * operating notes, nothing else.
  *
+ * `providerDefaults` IS NOT POLICY EITHER. It is a repo-shared DECLARATIVE
+ * "requested auto-approve mode" per providerType — the answer to "WHEN a delegated
+ * worker of type X is auto-approved, WHICH mode should it use by default". It has
+ * NO say over WHETHER auto-approve is enabled: the ENABLE decision (and the
+ * dangerous-mode opt-in) remains 100% machine-local (meshes.json /
+ * RepoMeshPolicy). A repo can declare `providerDefaults` freely; a machine that
+ * has delegatedWorkerAutoApprove=false still gets no auto-approve, and a dangerous
+ * requested mode is still downgraded to PTY parsing unless the machine opts in.
+ * The requested mode ID is validated at runtime against the provider spec — an
+ * unknown mode ID is IGNORED (fall back to the provider's own default), never
+ * silently coerced into a dangerous mode.
+ *
  * The coordinator/operatingNotes merge is **in-memory only**: the on-disk
  * machine-local `meshes.json` is never mutated by this module.
  *
@@ -60,6 +72,19 @@ export interface RepoMeshDeclarativeLimits {
     maxNotes?: number;
 }
 
+/**
+ * Repo-shared declarative per-provider defaults. NOT policy — see the file header.
+ * `autoApproveModes` maps a providerType (e.g. "claude-cli") to the auto-approve
+ * mode ID that a delegated worker of that type should REQUEST when it is
+ * auto-approved. The map only influences WHICH mode is used, never WHETHER
+ * auto-approve is enabled (that stays machine-local). Mode IDs are validated
+ * against the live provider spec at resolve time; an unknown ID is ignored.
+ */
+export interface RepoMeshDeclarativeProviderDefaults {
+    /** providerType → requested auto-approve mode ID. */
+    autoApproveModes?: Record<string, string>;
+}
+
 /**
  * Parsed + normalized `.adhdev/mesh.json` shape. Every field is optional except
  * version so a repo can declare only the zone(s) it cares about. Policy is NOT a
@@ -70,6 +95,8 @@ export interface RepoMeshDeclarativeConfig {
     coordinator?: RepoMeshDeclarativeCoordinatorConfig;
     operatingNotes?: CoordinatorOperatingNote[];
     limits?: RepoMeshDeclarativeLimits;
+    /** Repo-shared per-provider defaults (requested auto-approve mode). NOT policy. */
+    providerDefaults?: RepoMeshDeclarativeProviderDefaults;
 }
 
 export interface RepoMeshJsonConfigLoadResult {
@@ -132,6 +159,20 @@ export const MESH_JSON_CONFIG_SCHEMA = {
                 maxNotes: { type: 'number', minimum: 1 },
             },
         },
+        providerDefaults: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                // providerType → requested auto-approve mode ID. Mode IDs are
+                // validated against the live provider spec at resolve time; an
+                // unknown ID is ignored (provider default is used), so the schema
+                // only constrains the shape (string→string), not the ID values.
+                autoApproveModes: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                },
+            },
+        },
     },
 } as const;
 
@@ -226,6 +267,38 @@ export function normalizeRepoMeshDeclarativeConfig(parsed: unknown): {
         }
     }
 
+    // providerDefaults: shape-only normalization. We keep every string→string
+    // (providerType → requested mode ID) entry after trimming; we deliberately do
+    // NOT validate the mode IDs against any provider spec here — the normalizer has
+    // no provider registry, and (crucially) validity depends on the LIVE provider
+    // at resolve time. The runtime resolver (resolveDelegatedWorkerAutoApprove)
+    // checks the requested ID against provider.autoApproveModes.modes and falls
+    // back to the provider's own default when the ID is unknown. This keeps the
+    // config fail-closed: a stale/typo'd mode ID never coerces into a dangerous
+    // mode, it just means "no repo override → provider default".
+    if (parsed.providerDefaults !== undefined) {
+        if (isRecord(parsed.providerDefaults)) {
+            const pd: RepoMeshDeclarativeProviderDefaults = {};
+            const rawModes = (parsed.providerDefaults as Record<string, unknown>).autoApproveModes;
+            if (rawModes !== undefined) {
+                if (isRecord(rawModes)) {
+                    const modes: Record<string, string> = {};
+                    for (const [providerType, modeId] of Object.entries(rawModes)) {
+                        const type = typeof providerType === 'string' ? providerType.trim() : '';
+                        const id = typeof modeId === 'string' ? modeId.trim() : '';
+                        if (type && id) modes[type] = id;
+                    }
+                    if (Object.keys(modes).length) pd.autoApproveModes = modes;
+                } else {
+                    errors.push('providerDefaults.autoApproveModes must be an object when provided');
+                }
+            }
+            if (Object.keys(pd).length) config.providerDefaults = pd;
+        } else {
+            errors.push('providerDefaults must be an object when provided');
+        }
+    }
+
     return { valid: true, config, errors };
 }
 
@@ -364,6 +437,21 @@ export function applyRepoMeshConfig<T extends Pick<LocalMeshEntry, 'coordinator'
  * exported — it is machine-local only and has no place in mesh.json. Operating
  * notes are intentionally NOT exported either: those are runtime ledger lessons,
  * and a repo should declare baseline notes deliberately.
+ *
+ * `providerDefaults` is NOT auto-exported from the machine-local mesh (there is no
+ * machine-local source for it — it is a repo-authored declaration). To help an
+ * operator hand-author it, the scaffold carries a commented example shape:
+ *
+ *   "providerDefaults": {
+ *     "autoApproveModes": {
+ *       "claude-cli": "accept-edits",   // requested mode WHEN auto-approve is on
+ *       "codex-cli": "auto"             // (enable/dangerous opt-in stays machine-local)
+ *     }
+ *   }
+ *
+ * The example is surfaced via the scaffold's `_providerDefaultsExample` hint (JSON
+ * has no comments) rather than a live `providerDefaults` value, so serializing the
+ * scaffold never writes an unwanted requested-mode map into the repo file.
  */
 export function buildMeshJsonConfigScaffold(
     mesh: Pick<LocalMeshEntry, 'coordinator'>,
@@ -378,6 +466,21 @@ export function buildMeshJsonConfigScaffold(
     return scaffold;
 }
 
+/**
+ * A copy-paste example of the `providerDefaults` zone for operators hand-authoring
+ * a repo `.adhdev/mesh.json`. Returned by the export/write commands as a separate
+ * hint field (never merged into the serialized scaffold) so the repo file stays
+ * clean. The mode IDs shown are illustrative — a repo should use IDs that exist in
+ * its own providers' specs; an unknown ID is ignored at resolve time and the
+ * provider's own default is used.
+ */
+export const MESH_JSON_PROVIDER_DEFAULTS_EXAMPLE: RepoMeshDeclarativeProviderDefaults = {
+    autoApproveModes: {
+        'claude-cli': 'accept-edits',
+        'codex-cli': 'auto',
+    },
+};
+
 /** Serialize a scaffold to the canonical 2-space JSON draft text. */
 export function serializeMeshJsonConfigScaffold(config: RepoMeshDeclarativeConfig): string {
     return JSON.stringify(config, null, 2);

package/src/index.ts

@@ -163,6 +163,24 @@ export {
   resolveAutoConvergeCodeChange,
 } from './repo-mesh-types.js';
 
+// ── Repo-shared declarative mesh config (.adhdev/mesh.json) ──
+export {
+  loadRepoMeshJsonConfig,
+  normalizeRepoMeshDeclarativeConfig,
+  buildMeshJsonConfigScaffold,
+  serializeMeshJsonConfigScaffold,
+  MESH_JSON_CONFIG_LOCATIONS,
+  MESH_JSON_CONFIG_SCHEMA,
+  MESH_JSON_PROVIDER_DEFAULTS_EXAMPLE,
+} from './config/mesh-json-config.js';
+export type {
+  RepoMeshDeclarativeConfig,
+  RepoMeshDeclarativeCoordinatorConfig,
+  RepoMeshDeclarativeLimits,
+  RepoMeshDeclarativeProviderDefaults,
+  RepoMeshJsonConfigLoadResult,
+} from './config/mesh-json-config.js';
+
 // ── Git Surface ──
 export * from './git/index.js';
 

package/src/mesh/mesh-event-forwarding.ts

@@ -17,6 +17,7 @@ import { enqueueUnresolvedDelegateForward, nudgeUnresolvedForwardRetry } from '.
 import { traceMeshEventStage, traceMeshEventDrop } from './mesh-event-trace.js';
 import { getLastDisplayMessage } from '../status/snapshot.js';
 import { delegatedWorkerAutoApproveSettings } from '../repo-mesh-types.js';
+import { loadRepoMeshJsonConfig } from '../config/mesh-json-config.js';
 import { meshNodeIdMatches, daemonIdsEquivalent, expandDaemonIdForms, sessionIdsEquivalent, withStatusProbeMarker, type MeshNodeIdentified } from '@adhdev/mesh-shared';
 import {
     findRecentTerminalLedgerEvidence,
@@ -1618,6 +1619,17 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
                                         mesh?.policy,
                                         node?.policy,
                                         components.providerLoader?.getMeta(recoveryContext.failedProviderType),
+                                        // Recovery relaunch: same repo-declared requested mode as the
+                                        // primary path. node.workspace missing → null → provider default.
+                                        (() => {
+                                            const ws = typeof node?.workspace === 'string' && node.workspace.trim() ? node.workspace.trim() : '';
+                                            if (!ws) return null;
+                                            try {
+                                                const r = loadRepoMeshJsonConfig(ws);
+                                                return r.sourceType === 'repo_file' && r.config ? r.config : null;
+                                            } catch { return null; }
+                                        })(),
+                                        recoveryContext.failedProviderType,
                                     ),
                                     launchedByCoordinator: true,
                                 }

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

@@ -14,6 +14,8 @@ import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { traceMeshEventDrop } from './mesh-event-trace.js';
 import { awaitWithWarmupDeadline, resolveWarmupDeadlineOpts } from './mesh-warmup-deadline.js';
 import { delegatedWorkerAutoApproveSettings, resolveProviderMaxParallel, resolveNodeSchedulingPriority, normalizeMeshSchedulingStrategy, resolveMaxParallelTasks, resolveMaxReadonlyParallelTasks, resolveCoordinatorIdlePushPolicy } from '../repo-mesh-types.js';
+import { loadRepoMeshJsonConfig } from '../config/mesh-json-config.js';
+import type { RepoMeshDeclarativeConfig } from '../config/mesh-json-config.js';
 import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
 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';
@@ -90,6 +92,25 @@ export function __resetIdleAutoFastForwardForTests(): void {
     autoFastForwardWorkspaceLease.clear();
 }
 
+/**
+ * Load the repo-shared `.adhdev/mesh.json` for a node's workspace, tolerating a
+ * missing/invalid file (returns null → resolver falls back to provider-spec
+ * defaults, i.e. exactly the pre-providerDefaults behavior). Only the
+ * `providerDefaults` zone influences the delegated-worker MODE selection; it never
+ * touches the ENABLE decision. When a node carries no workspace path (should not
+ * happen for a launchable node, but be defensive), we skip the read entirely.
+ */
+function loadRepoConfigForNode(node: any): RepoMeshDeclarativeConfig | null {
+    const workspace = typeof node?.workspace === 'string' && node.workspace.trim() ? node.workspace.trim() : '';
+    if (!workspace) return null;
+    try {
+        const result = loadRepoMeshJsonConfig(workspace);
+        return result.sourceType === 'repo_file' && result.config ? result.config : null;
+    } catch {
+        return null;
+    }
+}
+
 export function getMeshWithCache(components: DaemonComponents, meshId: string): any | undefined {
     const localMesh = getMesh(meshId);
     const cachedMesh = components.router?.getCachedInlineMesh(meshId);
@@ -708,6 +729,8 @@ export function tryAssignQueueTask(
                     mesh?.policy,
                     node?.policy,
                     components.providerLoader?.getMeta(providerType),
+                    loadRepoConfigForNode(node),
+                    providerType,
                 ),
                 ...(localDaemonId ? { meshCoordinatorDaemonId: localDaemonId } : {}),
                 // COMPLETION-PROPAGATION F5: (re)stamp the coordinator SESSION anchor from THIS
@@ -1698,8 +1721,20 @@ function liveSessionCountForNode(components: DaemonComponents, meshId: string, n
  * free claimer, and is excluded — so a read-only auto-launch onto a busy-but-no-idle node
  * is still allowed. A node with NO live mesh session at all (dead, or never launched) does
  * not match, preserving the legitimate first-session spawn.
+ *
+ * PROVIDER-MATCH gate (DISPATCH-DEADLOCK-PROVIDER-MISMATCH): a live session only suppresses
+ * this launch if it could ACTUALLY claim THIS task. A session whose providerType does not
+ * satisfy the task's requiredTags (e.g. a claude-cli coordinator/worker session on a node,
+ * while the pending task is required_tags: [provider=codex-cli]) is NOT a pending claimer for
+ * this task — claimNextQueueTask's nodeSatisfiesRequiredTags gate would reject its claim. Left
+ * unchecked, such a mismatched session made this gate return true for a task it can never claim,
+ * so the required-provider worker never auto-launched AND no session could claim → nobody made
+ * progress → permanent silent deadlock. Mirror the claim path: build the session's own
+ * capability tags (its providerType pinned onto the node) and only count it as a pending claimer
+ * when those tags satisfy task.requiredTags. `node` is passed in so the tag set reflects this
+ * node's os/arch/worktree/converge context, matching claimNextQueueTask exactly.
  */
-function nodeHasLiveSessionPendingClaim(components: DaemonComponents, meshId: string, nodeId: string): boolean {
+function nodeHasLiveSessionPendingClaim(components: DaemonComponents, meshId: string, nodeId: string, task: MeshWorkQueueEntry, node: any): boolean {
     // (A) AUTOLAUNCH-CLAIM-CHURN remote-awareness: a task whose auto-launch record targets this
     // node and is still inside its await-claim window (base or backoff) already has a session on
     // its way to claim — even when that session is REMOTE and thus invisible to the local
@@ -1738,7 +1773,20 @@ function nodeHasLiveSessionPendingClaim(components: DaemonComponents, meshId: st
         if (isTerminalSessionStatus(status)) return false; // dead → no claimer here, allow launch
         const sessionId = readNonEmptyString(state.instanceId);
         if (sessionId && busySessionIds.has(sessionId)) return false; // busy with its own assigned task
-        return true; // live + unassigned → will claim the pending task itself
+        // PROVIDER-MATCH gate (DISPATCH-DEADLOCK-PROVIDER-MISMATCH): only count this session as a
+        // pending claimer if its own provider could satisfy THIS task's requiredTags. A session
+        // whose providerType does not match (e.g. a claude-cli session while task requires
+        // provider=codex-cli) can never claim this task via claimNextQueueTask's
+        // nodeSatisfiesRequiredTags gate, so it must not suppress the required-provider launch —
+        // otherwise the task deadlocks (mismatched session blocks launch, yet cannot claim). Mirror
+        // the claim path: pin the session's providerType onto this node and check the tags.
+        if (task.requiredTags?.length) {
+            const sessionProviderType = state.type || readNonEmptyString(settings.providerType);
+            if (sessionProviderType && !nodeSatisfiesRequiredTags(task.requiredTags, buildMeshNodeCapabilityTags(node, sessionProviderType))) {
+                return false; // provider mismatch → this session can't claim this task; not a pending claimer
+            }
+        }
+        return true; // live + unassigned + provider-capable → will claim the pending task itself
     });
 }
 
@@ -2250,7 +2298,7 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
             // busy-but-no-idle node is still allowed. Skip with a transient (non-actionable)
             // reason so the coordinator is not paged; the 4s reconcile retries, and once the
             // existing session goes terminal this gate clears and a legitimate launch proceeds.
-            if (nodeHasLiveSessionPendingClaim(components, meshId, nodeId)) {
+            if (nodeHasLiveSessionPendingClaim(components, meshId, nodeId, task, node)) {
                 markAutoLaunch(meshId, task.id, { status: 'skipped', reason: 'node_has_live_session_pending_claim', nodeId });
                 continue;
             }
@@ -2327,6 +2375,8 @@ async function maybeAutoLaunchOneQueueSession(components: DaemonComponents, mesh
                         mesh?.policy,
                         node?.policy,
                         components.providerLoader?.getMeta(resolved.providerType),
+                        loadRepoConfigForNode(node),
+                        resolved.providerType,
                     ),
                     launchedByCoordinator: true,
                     autoLaunchedForQueueTaskId: task.id,

package/src/repo-mesh-types.ts

@@ -17,6 +17,9 @@ import type { MeshMagiActivitySummary } from './mesh/mesh-magi-status.js';
 import type { MagiKindPanelMap, DifficultyBrainMap, NodeCapabilitySlot } from '@adhdev/mesh-shared';
 import type { ProviderModule } from './providers/contracts.js';
 import { deriveAutoApproveModeRisk } from './providers/auto-approve-modes.js';
+// Type-only import (no runtime cycle) — mesh-json-config imports types from this
+// module, and this direction is `import type` so tsc erases it at emit.
+import type { RepoMeshDeclarativeConfig } from './config/mesh-json-config.js';
 
 // ─── Core Mesh Types ────────────────────────────
 
@@ -804,14 +807,40 @@ export function mergeAndNormalizePolicy(
 
 /**
  * Resolve delegated worker auto-approve. Legacy providers return a boolean. Providers
- * with modes return the default mode id, except a dangerous default is downgraded to a
+ * with modes return a mode id, except a dangerous mode is downgraded to a
  * non-dangerous PTY mode unless mesh/node policy explicitly opts in.
+ *
+ * THREE EXPLICIT STAGES — do not collapse them; the ordering is a hard MAGI
+ * invariant:
+ *
+ *   ① ENABLE gate (machine-local policy only): node boolean > mesh boolean.
+ *      `enabled=false` returns `false` IMMEDIATELY, BEFORE any mode selection.
+ *      The repo `mesh.json` providerDefaults has ZERO influence here — a
+ *      node/mesh opt-out is never overridden by a repo-declared requested mode.
+ *
+ *   ② MODE selection (only when enabled === true):
+ *        task override [FUTURE — param reserved below, not yet wired] >
+ *        repo mesh.json providerDefaults.autoApproveModes[providerType] >
+ *        provider spec autoApproveModes.default.
+ *      A repo-requested mode ID is adopted ONLY when it exists in the provider's
+ *      own `autoApproveModes.modes`; an unknown/stale/typo'd ID is IGNORED and we
+ *      fall back to the provider default (fail-closed: never coerce into a
+ *      dangerous mode via a bad ID).
+ *
+ *   ③ DANGEROUS gate: whichever mode stage ② picked, if it is dangerous and the
+ *      machine-local delegatedWorkerDangerousModeAllow is not set, downgrade to a
+ *      non-dangerous PTY-parse mode (or `false` if none exists).
  */
 export function resolveDelegatedWorkerAutoApprove(
     meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null,
     nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null,
     provider?: Pick<ProviderModule, 'autoApproveModes'> | null,
+    repoConfig?: RepoMeshDeclarativeConfig | null,
+    // providerType is needed to look up the repo-declared requested mode; it is
+    // separate from `provider` because the caller resolves the spec independently.
+    providerType?: string | null,
 ): boolean | string {
+    // ── ① ENABLE gate — machine-local only. false short-circuits before mode. ──
     let enabled = true;
     if (typeof nodePolicy?.delegatedWorkerAutoApprove === 'boolean') {
         enabled = nodePolicy.delegatedWorkerAutoApprove;
@@ -822,16 +851,32 @@ export function resolveDelegatedWorkerAutoApprove(
 
     const modes = provider?.autoApproveModes;
     if (!modes) return true;
-    const defaultMode = modes.modes.find((mode) => mode.id === modes.default);
-    if (!defaultMode || defaultMode.strategy === 'post-boot-command') return false;
 
+    // ── ② MODE selection (enabled only). Repo providerDefaults MAY override the
+    //     provider spec default here — but only with a mode ID the spec knows. ──
+    // Future: a per-task override would slot in ahead of the repo default; the
+    // signature reserves that precedence but no task override is wired yet.
+    const requestedModeRaw = typeof providerType === 'string'
+        ? repoConfig?.providerDefaults?.autoApproveModes?.[providerType.trim()]
+        : undefined;
+    const requestedModeId = typeof requestedModeRaw === 'string' && requestedModeRaw.trim()
+        ? requestedModeRaw.trim()
+        : '';
+    const requestedMode = requestedModeId
+        ? modes.modes.find((mode) => mode.id === requestedModeId)
+        : undefined;
+    const selectedMode = requestedMode
+        ?? modes.modes.find((mode) => mode.id === modes.default);
+    if (!selectedMode || selectedMode.strategy === 'post-boot-command') return false;
+
+    // ── ③ DANGEROUS gate — downgrade a dangerous selection without machine opt-in. ──
     const dangerousAllowed = resolveDelegatedWorkerDangerousModeAllow(meshPolicy, nodePolicy);
-    if (deriveAutoApproveModeRisk(defaultMode) === 'dangerous' && !dangerousAllowed) {
-        const ptyFallback = modes!.modes.find((mode) =>
+    if (deriveAutoApproveModeRisk(selectedMode) === 'dangerous' && !dangerousAllowed) {
+        const ptyFallback = modes.modes.find((mode) =>
             mode.strategy === 'pty-parse-default' && deriveAutoApproveModeRisk(mode) !== 'dangerous');
         return ptyFallback?.id || false;
     }
-    return defaultMode.id;
+    return selectedMode.id;
 }
 
 export function resolveDelegatedWorkerDangerousModeAllow(
@@ -849,12 +894,14 @@ export function delegatedWorkerAutoApproveSettings(
     meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null,
     nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove' | 'delegatedWorkerDangerousModeAllow'> | null,
     provider?: Pick<ProviderModule, 'autoApproveModes'> | null,
+    repoConfig?: RepoMeshDeclarativeConfig | null,
+    providerType?: string | null,
 ): {
     autoApprove: boolean | undefined;
     autoApproveMode: string | undefined;
     delegatedWorkerDangerousModeAllow: boolean;
 } {
-    const resolved = resolveDelegatedWorkerAutoApprove(meshPolicy, nodePolicy, provider);
+    const resolved = resolveDelegatedWorkerAutoApprove(meshPolicy, nodePolicy, provider, repoConfig, providerType);
     const delegatedWorkerDangerousModeAllow = resolveDelegatedWorkerDangerousModeAllow(meshPolicy, nodePolicy);
     return typeof resolved === 'string'
         ? { autoApprove: undefined, autoApproveMode: resolved, delegatedWorkerDangerousModeAllow }