@bridge_gpt/mcp-server 0.2.38 → 0.2.41

package/build/agent-launchers/claude-executor-adapter.js

@@ -0,0 +1,392 @@
+import { isModelTier, isValidModelAlias, resolveModelAlias } from "../agent-registry.js";
+import { evaluateClaudeMcpShadowingPolicy, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "../claude-user-config-doctor.js";
+import { runDenyEnforcementPreflight } from "../conductor/deny-enforcement-preflight.js";
+import { buildExecutorBaseWorkerEnv } from "../executor/env.js";
+import { provisionExecutorDenyLayer } from "../executor/permissions.js";
+import { SUPPORTED_EXECUTOR_PLATFORMS, evaluateExecutorPlatform } from "../executor/platform.js";
+import { normalizeMcpServerNames } from "../executor/observation.js";
+import { supported } from "./executor-adapter.js";
+/** Stable identity of this reference implementation. */
+export const CLAUDE_ADAPTER_ID = "claude-reference";
+/** Registry strategy identifier that selects this adapter's factory. */
+export const CLAUDE_ADAPTER_STRATEGY_ID = "claude-strict-mcp-v1";
+/** Contract revision this implementation targets. */
+export const CLAUDE_ADAPTER_VERSION = "1.0.0";
+/** The one operator-owned credential name this adapter forwards. */
+export const CLAUDE_OAUTH_TOKEN_ENV = "CLAUDE_CODE_OAUTH_TOKEN";
+/** The provisioned MCP server a Claude worker requires. */
+export const CLAUDE_REQUIRED_MCP_SERVER_NAME = "bridge-api";
+/** Fixed replacement written in place of a redacted secret value. */
+export const CLAUDE_REDACTION_REPLACEMENT = "[redacted]";
+/** Upper bound on retained version text, matching preflight's existing cap. */
+const VERSION_DETAIL_MAX = 200;
+// ---------------------------------------------------------------------------
+// Executable discovery
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a version probe result: stdout first, stderr second, bounded.
+ *
+ * Preserved verbatim from `preflight.ts`'s `normalizeVersion` — the ordering is
+ * not arbitrary, and re-deriving it would silently change the `agent_version`
+ * value that goes onto the wire in the claim manifest.
+ */
+function normalizeClaudeVersion(output) {
+    return (output.stdout || output.stderr || "").trim().slice(0, VERSION_DETAIL_MAX);
+}
+/**
+ * Parse the probe into bounded identification.
+ *
+ * NO SEMANTIC-VERSION PARSING, deliberately. The Claude CLI does not guarantee a
+ * parseable version format, so the fingerprint is the normalized version text
+ * itself (collapsed whitespace) rather than an invented `major.minor.patch`
+ * extraction that would degrade to nonsense the first time the output format
+ * changes. A failed probe yields a null fingerprint rather than a fabricated one.
+ */
+export function parseClaudeVersion(output) {
+    const version = normalizeClaudeVersion(output);
+    if (output.exitCode !== 0 || version.length === 0) {
+        return { version, fingerprint: null };
+    }
+    return { version, fingerprint: version.replace(/\s+/g, " ").trim() };
+}
+// ---------------------------------------------------------------------------
+// MCP init-event parsing
+// ---------------------------------------------------------------------------
+/** True only for an exact `{"type":"system","subtype":"init"}` object. */
+function isSystemInitEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const obj = value;
+    return obj.type === "system" && obj.subtype === "init";
+}
+/**
+ * Parse one stream line for Claude's `system`/`init` event.
+ *
+ * Moved verbatim from `observation.ts`. The malformed arm is the load-bearing
+ * one: a valid init event whose `mcp_servers` list cannot be read returns
+ * `malformed-init` rather than an empty name set, because an unreadable shape is
+ * not evidence of an empty surface. Dropping a single unreadable entry would let
+ * a mismatched surface pass as a match.
+ */
+export function parseClaudeInitEvent(line) {
+    const trimmed = typeof line === "string" ? line.trim() : "";
+    if (trimmed.length === 0)
+        return { kind: "not-init" };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // A line we cannot parse tells us nothing at all — advisory, not malformed.
+        return { kind: "not-init" };
+    }
+    if (!isSystemInitEvent(parsed))
+        return { kind: "not-init" };
+    const servers = parsed.mcp_servers;
+    if (!Array.isArray(servers))
+        return { kind: "malformed-init" };
+    const names = [];
+    for (const entry of servers) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            return { kind: "malformed-init" };
+        }
+        const name = entry.name;
+        if (typeof name !== "string" || name.trim().length === 0) {
+            return { kind: "malformed-init" };
+        }
+        names.push(name);
+    }
+    return { kind: "init", serverNames: normalizeMcpServerNames(names) };
+}
+// ---------------------------------------------------------------------------
+// Not-authenticated detection
+// ---------------------------------------------------------------------------
+/**
+ * Recognize Claude's not-logged-in / invalid-token failure in its stream-json
+ * output.
+ *
+ * Moved verbatim from `job-errors.ts`'s `classifyClaudeAuthenticationFailure`,
+ * with one addition required by the contract: the result carries a stable reason
+ * CODE and never the matched line. The excerpt this reads can contain arbitrary
+ * agent output and the classification travels into a `/fail` report, so
+ * returning the match would turn a diagnostic into a disclosure channel.
+ */
+export function classifyClaudeAuthFailure(stdoutExcerpt) {
+    if (typeof stdoutExcerpt !== "string" || stdoutExcerpt.length === 0) {
+        return { notAuthenticated: false, reasonCode: null };
+    }
+    for (const rawLine of stdoutExcerpt.split("\n")) {
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const obj = parsed;
+        if (obj.type !== "result" || obj.is_error !== true)
+            continue;
+        const resultText = typeof obj.result === "string" ? obj.result : "";
+        const notLoggedIn = obj.error === "authentication_failed" ||
+            resultText.includes("Not logged in") ||
+            resultText.includes("Please run /login");
+        const invalidToken = obj.api_error_status === 401 || resultText.includes("OAuth access token is invalid");
+        if (notLoggedIn)
+            return { notAuthenticated: true, reasonCode: "not-logged-in" };
+        if (invalidToken)
+            return { notAuthenticated: true, reasonCode: "invalid-token" };
+    }
+    return { notAuthenticated: false, reasonCode: null };
+}
+// ---------------------------------------------------------------------------
+// Model alias resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the Claude model alias from a job payload against the SUPPLIED spec.
+ *
+ * Moved from `worker-command.ts`, with the hard-coded `resolveAgentSpec("claude")`
+ * lookup removed: the adapter is constructed from a spec, so the alias policy
+ * reads that spec instead of re-resolving one. A direct alias is accepted only
+ * when it passes both registry alias validation AND the spec's static allowlist;
+ * anything else falls through to tier resolution, and an unusable result is null
+ * (meaning "omit `--model`") rather than an unvalidated passthrough.
+ */
+export function resolveClaudeModelAlias(spec, payload) {
+    const p = payload && typeof payload === "object" ? payload : {};
+    const directRaw = p.model_alias;
+    if (typeof directRaw === "string" && directRaw.trim().length > 0) {
+        const direct = directRaw.trim();
+        const allowed = !spec.staticModelAliasAllowlist || spec.staticModelAliasAllowlist.includes(direct);
+        if (isValidModelAlias(direct) && allowed) {
+            return direct;
+        }
+        // An invalid/disallowed direct alias falls through to the tier path — never
+        // returned as-is.
+    }
+    const tier = isModelTier(p.model_tier) ? p.model_tier : null;
+    return resolveModelAlias(spec, tier, null);
+}
+// ---------------------------------------------------------------------------
+// Spawn shape
+// ---------------------------------------------------------------------------
+/**
+ * Build the exact headless Claude argv.
+ *
+ * Moved verbatim from `worker-command.ts`'s `buildClaudeExecutorArgv`. The
+ * ordering is the golden shape the tests pin:
+ *
+ *   -p <prompt> --output-format stream-json --verbose
+ *   [--model <alias>]
+ *   (--dangerously-skip-permissions | --permission-mode acceptEdits)
+ *   --strict-mcp-config --mcp-config <verified path>
+ *
+ * Exactly ONE permission form is emitted. Emitting both would let the skip flag
+ * win silently and make the `accept_edits` policy look effective while doing
+ * nothing. The posture changes how Claude PROMPTS, not what it may do — the deny
+ * layer is provisioned in both postures.
+ *
+ * Every entry is pushed SEPARATELY and never joined into a command string, so a
+ * prompt or path containing a space or a shell metacharacter is just a value.
+ */
+export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture) {
+    const argv = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+    if (alias) {
+        argv.push("--model", alias);
+    }
+    if (posture === "accept_edits") {
+        argv.push("--permission-mode", "acceptEdits");
+    }
+    else {
+        argv.push("--dangerously-skip-permissions");
+    }
+    argv.push("--strict-mcp-config", "--mcp-config", mcpConfigPath);
+    return argv;
+}
+/**
+ * Build the Claude worker environment: the generic executor base, plus the one
+ * conditional OAuth passthrough.
+ *
+ * Moved from `env.ts`, where the OAuth branch used to sit inside the generic
+ * builder. It belongs HERE because it is an agent-specific credential decision:
+ * a Codex adapter would forward something else entirely, and a generic builder
+ * that knew about Claude's token would be exactly the Claude-shaped coupling
+ * this ticket removes.
+ *
+ * The copy is byte-for-byte and unconditional on content: no trimming, parsing,
+ * validation, logging, or fallback. A non-string or absent value is silently
+ * skipped rather than synthesized. `ANTHROPIC_API_KEY` has no equivalent branch
+ * and cannot reach a worker environment through any path in this function.
+ */
+export function buildClaudeWorkerEnv(parentEnv, options = {}) {
+    const env = buildExecutorBaseWorkerEnv(parentEnv, options);
+    const token = parentEnv[CLAUDE_OAUTH_TOKEN_ENV];
+    if (typeof token === "string") {
+        env[CLAUDE_OAUTH_TOKEN_ENV] = token;
+    }
+    return env;
+}
+// ---------------------------------------------------------------------------
+// The adapter factory
+// ---------------------------------------------------------------------------
+/**
+ * Construct the Claude reference adapter from a registry `AgentSpec`.
+ *
+ * The spec is supplied rather than resolved internally so the executable and
+ * model metadata stay owned by `agent-registry.ts` — this adapter adds a second
+ * command map to the codebase nowhere.
+ */
+export function createClaudeExecutorAdapter(spec, deps = {}) {
+    const executable = {
+        executable: spec.command,
+        versionArgv: ["--version"],
+        parseVersion: parseClaudeVersion,
+    };
+    const platform = {
+        supportedPlatforms: SUPPORTED_EXECUTOR_PLATFORMS,
+        evaluate: evaluateExecutorPlatform,
+    };
+    const headlessInvocation = {
+        buildSpawnShape(input) {
+            const envOptions = input.effectiveBaseBranch === undefined
+                ? {}
+                : { effectiveBaseBranch: input.effectiveBaseBranch };
+            return {
+                executable: spec.command,
+                argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture),
+                env: buildClaudeWorkerEnv(input.parentEnv, envOptions),
+            };
+        },
+        resolveModelAlias: (payload) => resolveClaudeModelAlias(spec, payload),
+    };
+    const mcpScoping = {
+        strategyId: "strict-mcp-config",
+        requiredServerName: CLAUDE_REQUIRED_MCP_SERVER_NAME,
+        supportsStrictConfig: true,
+    };
+    const mcpInitParsing = {
+        strategyId: "claude-system-init",
+        parseInitEvent: parseClaudeInitEvent,
+    };
+    /**
+     * The subscription-billed, operator-owned passthrough — the ONLY credential
+     * this adapter names. It is billed against the operator's own Claude seat, not
+     * against a Bridge-managed account, which is exactly why it is a passthrough
+     * and not a carrier.
+     */
+    const oauthPassthrough = {
+        passthroughId: "claude-code-oauth-token",
+        envName: CLAUDE_OAUTH_TOKEN_ENV,
+        billingClass: "subscription",
+        ownership: "operator-owned",
+        rule: "forward-when-present",
+    };
+    const auth = {
+        // EXACTLY ZERO Bridge-managed carriers (BAPI-791). Not "none configured" —
+        // none exist. A worker authenticates through the operator's interactive
+        // login, and no Bridge-stored token may appear here.
+        managedAuthCarriers: [],
+        operatorOwnedPassthroughs: [oauthPassthrough],
+    };
+    const authFailureDetection = {
+        strategyId: "claude-stream-json-result",
+        classify: classifyClaudeAuthFailure,
+    };
+    const denyEnforcement = {
+        strategyId: "claude-settings-deny",
+        async provisionWorktreeDenyLayer(input) {
+            const provision = deps.provisionDenyLayer ?? provisionExecutorDenyLayer;
+            const provisioningDeps = deps.denyProvisioningDeps;
+            if (!provisioningDeps) {
+                // Fail-OPEN, matching the deny layer's established posture: a missing
+                // provisioning boundary shrinks safety margin but must not kill a job.
+                return {
+                    ok: false,
+                    warning: "deny-layer provisioning deps were not supplied to the Claude adapter; " +
+                        "continuing fail-open",
+                };
+            }
+            return provision(input.worktreePath, { baseBranch: input.baseBranch }, provisioningDeps);
+        },
+        async probeEnforcement(options = {}) {
+            const probe = deps.runDenyPreflight ?? runDenyEnforcementPreflight;
+            const result = await probe(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs });
+            return {
+                enforced: result.enforced === true,
+                layer: String(result.layer),
+                degraded: result.degraded === true,
+                detail: typeof result.detail === "string" ? result.detail : "",
+                warnings: Array.isArray(result.warnings) ? [...result.warnings] : [],
+            };
+        },
+    };
+    const redaction = {
+        strategyId: "claude-env-name-redaction",
+        // The OAuth passthrough is the only secret this adapter's spawn can carry.
+        // Names only — this list can never hold a value.
+        secretEnvNames: [CLAUDE_OAUTH_TOKEN_ENV],
+        replacement: CLAUDE_REDACTION_REPLACEMENT,
+    };
+    const lifecycle = {
+        strategyId: "claude-no-lifecycle",
+        // EXPLICITLY none, not omitted. BAPI-790 deleted the per-job configuration
+        // directory that used to need cleanup and orphan sweeping, so there is
+        // genuinely nothing to do — and saying so is different from forgetting to.
+        declaration: { kind: "none" },
+    };
+    const advisoryMcpInspection = {
+        strategyId: "claude-user-config-shadowing",
+        async inspect(input) {
+            const inspect = deps.inspectClaudeUserConfig ?? inspectClaudeUserConfigForMcpShadowing;
+            const readFile = deps.readFile;
+            if (!readFile) {
+                return {
+                    warnings: [
+                        "Claude user-config MCP shadowing check did not run; no read boundary was supplied",
+                    ],
+                };
+            }
+            try {
+                const inspection = await inspect({
+                    claudeConfigPath: resolveClaudeUserConfigPath(input.homedir, input.platform),
+                    platform: input.platform,
+                    cwd: input.cwd,
+                    mainRepositoryPath: input.cwd,
+                    ...(input.worktreePath === undefined ? {} : { worktreePath: input.worktreePath }),
+                }, { readFile });
+                return { warnings: evaluateClaudeMcpShadowingPolicy(inspection).warnings };
+            }
+            catch {
+                // "Could not look" must never become "found a collision".
+                return {
+                    warnings: [
+                        "Claude user-config MCP shadowing check did not complete; could not verify worker MCP integrity",
+                    ],
+                };
+            }
+        },
+    };
+    return {
+        identity: {
+            agentId: spec.name,
+            adapterId: CLAUDE_ADAPTER_ID,
+            adapterVersion: CLAUDE_ADAPTER_VERSION,
+            strategyId: CLAUDE_ADAPTER_STRATEGY_ID,
+        },
+        executable: supported(executable),
+        platform: supported(platform),
+        headlessInvocation: supported(headlessInvocation),
+        mcpScoping: supported(mcpScoping),
+        mcpInitParsing: supported(mcpInitParsing),
+        auth: supported(auth),
+        authFailureDetection: supported(authFailureDetection),
+        denyEnforcement: supported(denyEnforcement),
+        redaction: supported(redaction),
+        lifecycle: supported(lifecycle),
+        advisoryMcpInspection: supported(advisoryMcpInspection),
+    };
+}

package/build/agent-launchers/executor-adapter-inspection.js

@@ -0,0 +1,163 @@
+import { redactAdapterDiagnostic, validateExecutorAdapterCapabilities } from "./executor-adapter.js";
+/** Bound on any probe failure text retained in the result. */
+const FAILURE_DETAIL_MAX = 300;
+/** Read a capability's value, or null when unsupported/absent. */
+function capabilityValue(declared) {
+    if (!declared || declared.supported !== true)
+        return null;
+    return declared.value;
+}
+/** Bound and redact a caught error into safe detail text. */
+function safeFailure(error, env, redaction) {
+    const raw = error instanceof Error ? error.message : String(error ?? "unknown error");
+    const redacted = redaction ? redactAdapterDiagnostic(raw, env, redaction) : raw;
+    return redacted.slice(0, FAILURE_DETAIL_MAX);
+}
+/** Project the auth declaration into metadata-only report shape. */
+function summarizeAuth(auth) {
+    return {
+        managedCarriers: auth.managedAuthCarriers.map((carrier) => ({
+            carrierId: carrier.carrierId,
+            billingClass: carrier.billingClass,
+            ownership: carrier.ownership,
+            // NAMES only. The values these name are never read here.
+            secretEnvNames: carrier.secretEnvNames,
+            validationStrategyId: carrier.validationStrategyId,
+        })),
+        passthroughs: auth.operatorOwnedPassthroughs.map((passthrough) => ({
+            passthroughId: passthrough.passthroughId,
+            envName: passthrough.envName,
+            billingClass: passthrough.billingClass,
+            ownership: passthrough.ownership,
+            rule: passthrough.rule,
+        })),
+    };
+}
+/**
+ * Build the inspection for an adapter whose resolution already FAILED.
+ *
+ * A refused adapter still gets a report rather than an empty one: an operator
+ * looking at doctor needs to see which agent was selected and which capability
+ * was missing. Nothing is probed, because there is no validated adapter to probe
+ * with.
+ */
+export function inspectionForFailedResolution(agentName, resolution) {
+    return {
+        identity: {
+            agentId: agentName,
+            adapterId: "(unresolved)",
+            adapterVersion: "(unresolved)",
+            strategyId: "(unresolved)",
+        },
+        ok: false,
+        capabilities: [],
+        refusals: resolution.refusals ?? [],
+        executable: null,
+        platform: null,
+        auth: null,
+        lifecycleKind: null,
+        warnings: [resolution.message],
+    };
+}
+/**
+ * Inspect a RESOLVED adapter.
+ *
+ * Ordering is deliberately fail-fast and cheapest-first: capability validation
+ * (pure), then the platform gate (pure), and only then the probes that cost a
+ * subprocess. An adapter that is incomplete, or a platform that is unsupported,
+ * is settled before anything external runs — which is what lets preflight
+ * promise that a refused adapter triggers no probes at all.
+ */
+export async function inspectExecutorAgentAdapter(adapter, deps, options = {}) {
+    const validation = validateExecutorAdapterCapabilities(adapter);
+    const redaction = capabilityValue(adapter.redaction);
+    const warnings = [];
+    const base = {
+        identity: adapter.identity,
+        ok: validation.ok,
+        capabilities: validation.capabilities,
+        refusals: validation.ok ? [] : validation.refusals,
+        executable: null,
+        platform: null,
+        auth: null,
+        lifecycleKind: null,
+        warnings,
+    };
+    if (!validation.ok) {
+        // Incomplete adapter: report the refusals and probe NOTHING. Probing an
+        // adapter we have already refused would spend a subprocess to learn about a
+        // configuration that cannot be used.
+        return { inspection: base, denyEnforcement: null };
+    }
+    const auth = capabilityValue(adapter.auth);
+    if (auth)
+        base.auth = summarizeAuth(auth);
+    const lifecycle = capabilityValue(adapter.lifecycle);
+    if (lifecycle)
+        base.lifecycleKind = lifecycle.declaration.kind;
+    const platformCapability = capabilityValue(adapter.platform);
+    if (platformCapability) {
+        base.platform = platformCapability.evaluate(deps.platform);
+    }
+    const executableCapability = capabilityValue(adapter.executable);
+    if (executableCapability) {
+        base.executable = {
+            command: executableCapability.executable,
+            version: "",
+            fingerprint: null,
+            probed: false,
+            failure: null,
+        };
+        // An unsupported platform short-circuits the probe. Running the agent's
+        // binary on a host the adapter just declared unsupported tells us nothing
+        // actionable, and the platform verdict is already the answer.
+        const platformOk = base.platform === null || base.platform.supported;
+        if (options.probeExecutable === true && platformOk) {
+            try {
+                const output = await deps.runCommand(executableCapability.executable, [
+                    ...executableCapability.versionArgv,
+                ]);
+                const identification = executableCapability.parseVersion(output);
+                base.executable = {
+                    command: executableCapability.executable,
+                    version: identification.version,
+                    fingerprint: identification.fingerprint,
+                    probed: true,
+                    failure: output.exitCode === 0
+                        ? null
+                        : `version probe exited ${output.exitCode}`,
+                };
+            }
+            catch (error) {
+                base.executable = {
+                    command: executableCapability.executable,
+                    version: "",
+                    fingerprint: null,
+                    probed: true,
+                    failure: safeFailure(error, deps.env, redaction),
+                };
+            }
+        }
+    }
+    let denyEnforcement = null;
+    const denyCapability = capabilityValue(adapter.denyEnforcement);
+    if (options.probeDenyEnforcement === true && denyCapability) {
+        try {
+            denyEnforcement = await denyCapability.probeEnforcement(options.denyProbeTimeoutMs === undefined ? {} : { timeoutMs: options.denyProbeTimeoutMs });
+        }
+        catch (error) {
+            // A THROWN probe is not "unknown", it is UNVERIFIED — and unverified deny
+            // enforcement is fail-closed everywhere else, so it is represented here as
+            // an explicit not-enforced verdict rather than a null the caller might
+            // read as "skipped".
+            denyEnforcement = {
+                enforced: false,
+                layer: "none",
+                degraded: true,
+                detail: safeFailure(error, deps.env, redaction),
+                warnings: ["deny-enforcement probe threw; enforcement is UNVERIFIED on this host"],
+            };
+        }
+    }
+    return { inspection: base, denyEnforcement };
+}

package/build/agent-launchers/executor-adapter-registry.js

@@ -0,0 +1,90 @@
+import { resolveAgentSpec } from "../agent-registry.js";
+import { createClaudeExecutorAdapter } from "./claude-executor-adapter.js";
+import { formatAdapterRefusal, validateExecutorAdapterCapabilities } from "./executor-adapter.js";
+/**
+ * The strategy → factory table. The ONLY place an adapter implementation is
+ * bound to a strategy identifier.
+ *
+ * Exactly one entry today. Codex and cursor-agent are deliberately absent rather
+ * than present-and-stubbed: an absent strategy produces an explicit unsupported
+ * result, whereas a stub would produce an adapter that passes resolution and
+ * fails later, further from the cause.
+ */
+const ADAPTER_FACTORIES = {
+    "claude-strict-mcp-v1": (spec, deps) => createClaudeExecutorAdapter(spec, deps.claude ?? {}),
+};
+/** List the strategy identifiers that have an implementation. */
+export function listImplementedAdapterStrategies() {
+    return Object.keys(ADAPTER_FACTORIES).sort();
+}
+/**
+ * Resolve `agentName` to a fully validated executor adapter.
+ *
+ * Order matters and is fail-closed at every step: the agent must exist, it must
+ * carry adapter metadata, that metadata's strategy must have an implementation,
+ * the built adapter's identity must match the metadata, and every required
+ * capability must be supported. Only then is an adapter returned.
+ */
+export function resolveExecutorAgentAdapter(agentName, deps = {}) {
+    const spec = resolveAgentSpec(agentName);
+    if (!spec) {
+        return {
+            supported: false,
+            kind: "unknown-agent",
+            message: `no agent named '${agentName}' is registered; cannot resolve an executor adapter`,
+        };
+    }
+    const registration = spec.executorAdapter;
+    if (!registration) {
+        return {
+            supported: false,
+            kind: "no-adapter-registration",
+            message: `agent '${spec.name}' declares no executor adapter registration, so it cannot spawn ` +
+                "conductor workers. This is not a fallback condition: no other agent's adapter is substituted.",
+        };
+    }
+    const factory = ADAPTER_FACTORIES[registration.strategyId];
+    if (!factory) {
+        return {
+            supported: false,
+            kind: "unimplemented-strategy",
+            message: `executor adapter strategy '${registration.strategyId}' (agent '${spec.name}') has no ` +
+                `implementation. Implemented strategies: ${listImplementedAdapterStrategies().join(", ")}.`,
+        };
+    }
+    const adapter = factory(spec, deps);
+    // Cross-check the built adapter against the metadata that selected it. A
+    // factory returning an implementation for a different agent/strategy/version
+    // would otherwise be reported under the wrong identity everywhere downstream.
+    const identity = adapter.identity;
+    const mismatches = [];
+    if (identity.agentId !== spec.name) {
+        mismatches.push(`agentId '${identity.agentId}' != registry agent '${spec.name}'`);
+    }
+    if (identity.adapterId !== registration.adapterId) {
+        mismatches.push(`adapterId '${identity.adapterId}' != registered '${registration.adapterId}'`);
+    }
+    if (identity.strategyId !== registration.strategyId) {
+        mismatches.push(`strategyId '${identity.strategyId}' != registered '${registration.strategyId}'`);
+    }
+    if (identity.adapterVersion !== registration.adapterVersion) {
+        mismatches.push(`adapterVersion '${identity.adapterVersion}' != registered '${registration.adapterVersion}'`);
+    }
+    if (mismatches.length > 0) {
+        return {
+            supported: false,
+            kind: "identity-mismatch",
+            message: `executor adapter identity does not match its registry registration: ${mismatches.join("; ")}`,
+        };
+    }
+    const validation = validateExecutorAdapterCapabilities(adapter);
+    if (!validation.ok) {
+        return {
+            supported: false,
+            kind: "incomplete-capabilities",
+            message: formatAdapterRefusal(identity, validation.refusals),
+            refusals: validation.refusals,
+        };
+    }
+    return { supported: true, adapter, spec, validation };
+}