create-agdf 0.14.5 → 0.20.0

package/lib/mcp-lifecycle/adapters/file-utils.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { renameSyncWithRetry } from "#agdf-core/fs-swap.js";
+
+export function atomicWrite(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = join(dirname(path), `.${Date.now()}-${process.pid}-agdf-mcp.tmp`);
+  writeFileSync(temporary, content, "utf8");
+  try { renameSyncWithRetry(temporary, path); } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+export function readJsonObject(path, code) {
+  if (!existsSync(path)) return { content: "", config: {} };
+  const content = readFileSync(path, "utf8");
+  try {
+    const config = JSON.parse(content);
+    if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error(code);
+    return { content, config };
+  } catch { throw new Error(code); }
+}
+
+export function fileSnapshot(path) {
+  const parentPath = dirname(path);
+  return {
+    path,
+    parentPath,
+    parentExisted: existsSync(parentPath),
+    existed: existsSync(path),
+    content: existsSync(path) ? readFileSync(path, "utf8") : "",
+  };
+}
+
+export function restoreSnapshot(snapshot, { removeEmptyParent = false } = {}) {
+  if (snapshot.existed) atomicWrite(snapshot.path, snapshot.content);
+  else {
+    rmSync(snapshot.path, { force: true });
+    if (removeEmptyParent && !snapshot.parentExisted) {
+      try { rmdirSync(snapshot.parentPath); } catch (error) {
+        if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error;
+      }
+    }
+  }
+}
+
+export function sourceRecord(source, inspected) {
+  return Object.freeze({
+    source: source.id,
+    path: source.path,
+    priority: source.priority,
+    selected: source.selected,
+    status: inspected.status,
+  });
+}
+
+export function referenceIdentityForSurface(surface, nativeScope, { scope, target, registration, createdConfig = false }) {
+  return Object.freeze({
+    surface,
+    native_scope: nativeScope(scope),
+    source: registration.selected_source,
+    path: registration.path,
+    ...(nativeScope(scope) === "user" ? {} : { target }),
+    ...(createdConfig ? { created_config: true } : {}),
+  });
+}
+
+export function inheritedPermissionEffect() {
+  return Object.freeze({ code: "inherited_host_user" });
+}
+
+export function allSourceResult({ sources, inspected, selectedSource }) {
+  const selected = inspected.get(selectedSource.id);
+  const higher = sources.filter((source) => source.priority < selectedSource.priority)
+    .map((source) => ({ source, state: inspected.get(source.id) }))
+    .find(({ state }) => state.status !== "absent");
+  const effectivePair = sources.map((source) => ({ source, state: inspected.get(source.id) }))
+    .find(({ state }) => state.status !== "absent") ?? { source: selectedSource, state: selected };
+  return Object.freeze({
+    ...selected,
+    status: higher ? "precedence_conflict" : effectivePair.state.status,
+    selected_status: selected.status,
+    effective_status: effectivePair.state.status,
+    selected_source: selectedSource.id,
+    effective_source: effectivePair.source.id,
+    sources: Object.freeze(sources.map((source) => sourceRecord(source, inspected.get(source.id)))),
+  });
+}

package/lib/mcp-lifecycle/adapters/opencode.js

@@ -0,0 +1,148 @@
+import { existsSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  allSourceResult,
+  atomicWrite,
+  fileSnapshot,
+  inheritedPermissionEffect,
+  readJsonObject,
+  referenceIdentityForSurface,
+  restoreSnapshot,
+} from "./file-utils.js";
+
+const OWNER = "create-agdf:mcp-runtime";
+const CREATED_CONFIG = "AGDF_MCP_CREATED_CONFIG";
+const SCHEMA = "https://opencode.ai/config.json";
+
+function readConfig(path) {
+  const value = readJsonObject(path, "AGDF_MCP_OPENCODE_CONFIG_INVALID");
+  if (value.config.mcp !== undefined && (!value.config.mcp || typeof value.config.mcp !== "object" || Array.isArray(value.config.mcp))) {
+    throw new Error("AGDF_MCP_OPENCODE_CONFIG_INVALID");
+  }
+  if (value.config.mcp?.servers !== undefined && (!value.config.mcp.servers || typeof value.config.mcp.servers !== "object" || Array.isArray(value.config.mcp.servers))) {
+    throw new Error("AGDF_MCP_OPENCODE_CONFIG_INVALID");
+  }
+  return value;
+}
+
+function entry(spec, { createdConfig = false } = {}) {
+  const value = { type: "local", command: [spec.command, ...spec.args],
+    ...(spec.scope === "project" ? { cwd: spec.target } : {}),
+    environment: { AGDF_MCP_OWNER: OWNER, AGDF_MCP_VERSION: spec.version, AGDF_MCP_DIGEST: spec.digest,
+      ...(createdConfig ? { [CREATED_CONFIG]: "true" } : {}) } };
+  return spec.host?.config_variant === "nested_v2" ? { ...value, disabled: false } : { ...value, enabled: true };
+}
+
+function inspectConfig(config, path, expected) {
+  const nested = config.mcp?.servers;
+  const expectedNested = expected.host?.config_variant === "nested_v2";
+  const alternate = expectedNested ? config.mcp?.agdf : nested?.agdf;
+  if (alternate !== undefined) {
+    const owned = alternate?.environment?.AGDF_MCP_OWNER === OWNER;
+    const command = Array.isArray(alternate?.command) && alternate.command.every((item) => typeof item === "string") ? alternate.command : null;
+    return { status: owned ? "owned_mismatch" : "foreign", path,
+      identity: owned ? { version: alternate.environment.AGDF_MCP_VERSION, digest: alternate.environment.AGDF_MCP_DIGEST } : null,
+      created_config: alternate?.environment?.[CREATED_CONFIG] === "true",
+      observed: command ? { command: command[0], args: command.slice(1) } : null };
+  }
+  const observedEntry = expectedNested ? nested?.agdf : config.mcp?.agdf;
+  if (observedEntry === undefined) return { status: "absent", path, identity: null };
+  const owned = observedEntry?.environment?.AGDF_MCP_OWNER === OWNER;
+  if (!owned) return { status: "foreign", path, identity: null };
+  const created = observedEntry.environment?.[CREATED_CONFIG] === "true";
+  const matched = [undefined, "true"].includes(observedEntry.environment?.[CREATED_CONFIG])
+    && JSON.stringify(observedEntry) === JSON.stringify(entry(expected, { createdConfig: created }));
+  const command = Array.isArray(observedEntry.command) && observedEntry.command.every((item) => typeof item === "string") ? observedEntry.command : null;
+  return { status: matched ? "matched" : "owned_mismatch", path,
+    identity: { version: observedEntry.environment.AGDF_MCP_VERSION, digest: observedEntry.environment.AGDF_MCP_DIGEST },
+    created_config: created, observed: command ? { command: command[0], args: command.slice(1) } : null };
+}
+
+function inspectPath(path, expected) {
+  return inspectConfig(readConfig(path).config, path, expected);
+}
+
+function sources({ scope, target, env }) {
+  return [
+    ...(typeof env.OPENCODE_CONFIG_CONTENT === "string" && env.OPENCODE_CONFIG_CONTENT.trim()
+      ? [{ id: "inline", path: "env:OPENCODE_CONFIG_CONTENT", priority: 0, selected: false, inline: env.OPENCODE_CONFIG_CONTENT }] : []),
+    ...(typeof env.OPENCODE_CONFIG === "string" && env.OPENCODE_CONFIG.trim()
+      ? [{ id: "custom", path: env.OPENCODE_CONFIG, priority: 5, selected: false }] : []),
+    { id: "project", path: join(target, "opencode.json"), priority: 10, selected: scope === "project" },
+    { id: "user", path: join(env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode"), "opencode.json"), priority: 20, selected: scope === "user" },
+  ];
+}
+
+function inspect(input) {
+  const list = sources(input);
+  const selected = list.find((source) => source.selected);
+  const states = new Map(list.map((source) => {
+    if (!source.inline) return [source.id, inspectPath(source.path, input.spec)];
+    try {
+      const config = JSON.parse(source.inline);
+      if (!config || typeof config !== "object" || Array.isArray(config)) throw new Error("invalid");
+      return [source.id, inspectConfig(config, source.path, input.spec)];
+    } catch { return [source.id, { status: "invalid", path: source.path, identity: null }]; }
+  }));
+  return { ...allSourceResult({ sources: list, inspected: states, selectedSource: selected }), native_scope: input.scope };
+}
+
+function transaction({ action, scope, target, spec, previousSpec, env }) {
+  const current = inspect({ scope, target, spec, env });
+  if (current.status === "precedence_conflict") throw new Error("AGDF_MCP_REGISTRATION_PRECEDENCE_CONFLICT");
+  if (current.selected_status === "foreign" && !previousSpec) throw new Error("AGDF_MCP_REGISTRATION_FOREIGN");
+  if ((action === "enable" && current.selected_status === "matched") || (action === "disable" && current.selected_status === "absent")) {
+    return { status: "unchanged", path: current.path, apply() {}, rollback() {} };
+  }
+  const snapshot = fileSnapshot(current.path);
+  const { config } = readConfig(current.path);
+  const mcp = { ...(config.mcp ?? {}) };
+  const nested = spec.host?.config_variant === "nested_v2";
+  const createdConfig = !snapshot.existed || current.created_config === true;
+  if (nested) {
+    if (previousSpec) delete mcp.agdf;
+    const servers = { ...(mcp.servers ?? {}) };
+    if (action === "enable") servers.agdf = entry(spec, { createdConfig }); else delete servers.agdf;
+    if (Object.keys(servers).length) mcp.servers = servers; else delete mcp.servers;
+  } else {
+    if (previousSpec && mcp.servers && typeof mcp.servers === "object" && !Array.isArray(mcp.servers)) {
+      const servers = { ...mcp.servers }; delete servers.agdf;
+      if (Object.keys(servers).length) mcp.servers = servers; else delete mcp.servers;
+    }
+    if (action === "enable") mcp.agdf = entry(spec, { createdConfig }); else delete mcp.agdf;
+  }
+  const next = { ...config };
+  if (Object.keys(mcp).length) next.mcp = mcp; else delete next.mcp;
+  const remaining = Object.keys(next);
+  const removable = current.created_config === true
+    && (remaining.length === 0 || (remaining.length === 1 && remaining[0] === "$schema" && next.$schema === SCHEMA));
+  const after = action === "disable" && removable ? null : `${JSON.stringify(next, null, 2)}\n`;
+  return { status: "changed", path: current.path,
+    apply() { if (after === null) rmSync(current.path, { force: true }); else atomicWrite(current.path, after); },
+    rollback() { restoreSnapshot(snapshot); },
+  };
+}
+
+function probe({ exec, target }) {
+  try {
+    const output = String(exec("opencode", ["--version"], { cwd: target, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })).trim();
+    const version = output.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)?.[0];
+    const major = Number.parseInt(version?.split(".")[0], 10);
+    if (!version || ![1, 2].includes(major)) return Object.freeze({ status: "unsupported", version: version ?? null, config_variant: null });
+    return Object.freeze({ status: "detected", version, client_variant: "cli",
+      config_variant: major >= 2 ? "nested_v2" : "flat_v1" });
+  } catch { return Object.freeze({ status: "unavailable", version: null, client_variant: "cli", config_variant: null }); }
+}
+
+export const opencodeAdapter = Object.freeze({
+  surface: "opencode",
+  nativeScope: (scope) => scope,
+  probeHost: probe,
+  resolveSources: sources,
+  inspect,
+  createTransaction: transaction,
+  referenceIdentity: (input) => referenceIdentityForSurface("opencode", (scope) => scope, input),
+  permissionEffect: inheritedPermissionEffect,
+});
+export const opencodeAdapterConstants = Object.freeze({ owner: OWNER, createdConfig: CREATED_CONFIG });

package/lib/mcp-lifecycle/evidence.js

@@ -0,0 +1,122 @@
+const SURFACES = new Set(["codex", "claude", "opencode", "copilot"]);
+const SCOPES = new Set(["project", "user"]);
+const QUALIFICATION_FIELDS = Object.freeze([
+  "surface",
+  "capability",
+  "host_version",
+  "client_variant",
+  "session_variant",
+  "configuration_variant",
+  "os",
+  "arch",
+  "requested_scope",
+  "native_scope",
+  "configuration_source",
+  "node_version",
+  "server_version",
+  "dispatcher_version",
+  "sdk_version",
+  "entrypoint_identity",
+  "discovery_evidence_ref",
+  "dispatch_evidence_ref",
+  "failure_evidence_ref",
+  "cleanup_evidence_ref",
+]);
+
+function plainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function evidenceRef(value) {
+  return typeof value === "string" && value.startsWith(".agdf/control/artefacts/") && !value.includes("..");
+}
+
+export function validateMcpQualificationRecord(record) {
+  const errors = [];
+  if (!plainObject(record)) return Object.freeze({ valid: false, errors: Object.freeze(["record"]) });
+  if (!SURFACES.has(record.surface)) errors.push("surface");
+  if (record.capability !== "supported") errors.push("capability");
+  for (const field of QUALIFICATION_FIELDS) {
+    if (typeof record[field] !== "string" || !record[field].trim()) errors.push(field);
+  }
+  if (!SCOPES.has(record.requested_scope)) errors.push("requested_scope");
+  for (const field of ["discovery_evidence_ref", "dispatch_evidence_ref", "failure_evidence_ref", "cleanup_evidence_ref"]) {
+    if (!evidenceRef(record[field])) errors.push(field);
+  }
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze([...new Set(errors)]) });
+}
+
+export function validateMcpDirectEvidenceResult(record, { expected = {} } = {}) {
+  const errors = [];
+  if (!plainObject(record) || record.schema_version !== 1) errors.push("schema_version");
+  if (!SURFACES.has(record?.surface)) errors.push("surface");
+  if (!["qualified", "unverified"].includes(record?.result)) errors.push("result");
+  if (record?.authorizes !== false) errors.push("authorizes");
+  if (!Array.isArray(record?.raw_log_sha256)
+      || record.raw_log_sha256.some((value) => !/^[a-f0-9]{64}$/u.test(value))) errors.push("raw_log_sha256");
+  else if (!record.raw_log_sha256.length) errors.push("raw_log_sha256");
+
+  if (record?.result === "qualified") {
+    const qualification = validateMcpQualificationRecord(record.qualification);
+    errors.push(...qualification.errors.map((field) => `qualification:${field}`));
+    if (record.qualification?.surface !== record.surface) errors.push("qualification:surface_match");
+    for (const [field, value] of Object.entries(expected)) {
+      if (record.qualification?.[field] !== value) errors.push(`qualification:expected:${field}`);
+    }
+    if (record.registration_status !== "matched") errors.push("registration_status");
+    if (record.discovery_status !== "discovered" || record.discovery_source !== "direct_host") errors.push("discovery");
+    if (record.tool_name !== "agdf_dispatch" || record.dispatch_status !== "passed") errors.push("dispatch");
+    if (record.failure_status !== "passed") errors.push("failure_status");
+    if (record.cleanup_status !== "restored") errors.push("cleanup_status");
+  } else if (!Array.isArray(record?.gaps) || !record.gaps.length
+      || record.gaps.some((value) => typeof value !== "string" || !value.trim())) {
+    errors.push("gaps");
+  }
+
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze([...new Set(errors)]) });
+}
+
+export const mcpQualificationFields = QUALIFICATION_FIELDS;
+
+// Cockpit observations are a distinct cooperative claim, never dispatch qualification.
+export function validateCockpitTransitionEvidence(record, { expected = {} } = {}) {
+  const errors = [];
+  const hash = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/u.test(value);
+  if (!plainObject(record) || record.schema_version !== 1 || record.kind !== 'cockpit_transition'
+    || record.surface !== 'codex' || record.result !== 'qualified' || record.authorizes !== false
+    || record.assurance !== 'cooperative_local') errors.push('record');
+  for (const key of ['target_id', 'config_digest', 'section_digest', 'plugin_digest', 'ui_digest',
+    'server_digest', 'dispatcher_digest', 'sdk_digest']) if (!hash(record?.[key])) errors.push(key);
+  for (const key of ['config_path', 'plugin_root', 'runtime_root', 'version', 'legacy_id']) {
+    if (typeof record?.[key] !== 'string' || !record[key]) errors.push(key);
+  }
+  if (!(record?.previous_plugin_digest === null && record?.previous_plugin_version === null)
+    && !(hash(record?.previous_plugin_digest) && typeof record?.previous_plugin_version === 'string'
+      && record.previous_plugin_version.length > 0)) errors.push('previous_installation');
+  if (!['agdf-cockpit', 'agdf-cockpit-local'].includes(record?.legacy_id)) errors.push('legacy_id');
+  if (!plainObject(record?.host) || ['name', 'version', 'session_id', 'os', 'arch'].some(key => typeof record.host[key] !== 'string' || !record.host[key])) errors.push('host');
+  if (!Array.isArray(record?.observations) || !['discovery', 'ui_initialize', 'render', 'interaction', 'provider_attribution', 'teardown']
+    .every(key => record.observations.includes(key))) errors.push('observations');
+  if (record?.inventory?.complete !== true || !Array.isArray(record.inventory.origins) || !record.inventory.origins.length
+    || record.inventory.origins.length > 64 || record.inventory.origins.some(row => !plainObject(row) || typeof row.path !== 'string' || !hash(row.digest))) errors.push('inventory');
+  if (!Array.isArray(record?.providers) || !record.providers.length || record.providers.length > 64
+    || record.providers.some(row => !plainObject(row) || typeof row.origin !== 'string' || typeof row.server_id !== 'string'
+      || typeof row.connection_id !== 'string' || !row.connection_id || !Array.isArray(row.tools)
+      || !plainObject(row.exposed_tools) || row.tools.some(name => typeof name !== 'string'
+        || typeof row.exposed_tools[name] !== 'string' || !row.exposed_tools[name]))) errors.push('providers');
+  if (Array.isArray(record?.providers) && record.providers.every(row => plainObject(row) && plainObject(row.exposed_tools))) {
+    const connections = record.providers.map(row => row.connection_id);
+    const exposed = record.providers.flatMap(row => Object.values(row.exposed_tools));
+    if (new Set(connections).size !== connections.length || new Set(exposed).size !== exposed.length) errors.push('provider_collision');
+  }
+  const provider = (Array.isArray(record?.providers) ? record.providers : []).filter(row => plainObject(row) && row.origin === record.plugin_root && row.server_id === 'agdf-cockpit');
+  if (provider?.length !== 1 || !Array.isArray(provider[0].tools) || !['agdf_cockpit', 'agdf_cockpit_read'].every(name => provider[0].tools.includes(name))) errors.push('provider');
+  if (!Array.isArray(record?.evidence) || !record.evidence.length || record.evidence.length > 16
+    || record.evidence.some(row => !plainObject(row) || !evidenceRef(row.path) || !hash(row.digest))) errors.push('evidence');
+  if (record?.legacy_id === 'agdf-cockpit' && (record.isolated_qualification?.isolated !== true
+    || record.isolated_qualification.target_id !== record.target_id
+    || record.isolated_qualification.plugin_digest !== record.plugin_digest
+    || typeof record.isolated_qualification.context_id !== 'string' || !record.isolated_qualification.context_id)) errors.push('isolated_qualification');
+  for (const [key, value] of Object.entries(expected)) if (record?.[key] !== value) errors.push(`expected:${key}`);
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze([...new Set(errors)]) });
+}

package/lib/mcp-lifecycle/facade-entry.js

@@ -0,0 +1,26 @@
+// Private child of the installed launcher. Public input remains MCP STDIO only.
+import process from 'node:process';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { inspectMcpServerPackage, createMcpGenerationPublisher } from './package.js';
+
+if (!process.send || !process.argv[2] || process.argv[2].length > 65536) throw Error('AGDF_MCP_FACADE_INPUT_INVALID');
+const { runtime: expected, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns } = JSON.parse(process.argv[2]);
+let handle, stopRequested = false;
+const stop = () => { stopRequested = true; if (handle) void handle.close(); };
+process.on('message', message => { if (message?.kind === 'facade_stop' && message.token === token) stop(); });
+process.on('disconnect', stop); process.on('SIGINT', stop); process.on('SIGTERM', stop);
+const actual = inspectMcpServerPackage({ dataRoot: dirname(expected.root), expectedVersion: expected.version });
+if (actual.status !== 'matched' || actual.root !== expected.root || actual.digest !== expected.digest
+  || actual.dispatcherDigest !== expected.dispatcherDigest || actual.sdkDigest !== expected.sdkDigest) throw Error('AGDF_MCP_FACADE_IDENTITY_INVALID');
+const runtime = { ...actual, immutable: true, publication_id: expected.publication_id, publisher_root: expected.publisher_root };
+process.env.AGDF_DISPATCH_PLUGIN_ROOT = pluginRoot;
+const { runMcpServer } = await import(pathToFileURL(join(runtime.packageRoot, 'src/main.js')));
+handle = await runMcpServer({ surface, cockpitDir, cockpitMode, ownedPublication: runtime,
+  ownedPublisher: createMcpGenerationPublisher(runtime, {
+    publicationDeadline: performance.now() + Math.max(0, Number(BigInt(deadline_ns) - process.hrtime.bigint()) / 1e6),
+  }), onClosed(result) {
+    process.send?.({ kind: 'facade_closed', token, confirmed: result?.confirmed === true }, () => process.disconnect());
+  } });
+if (!handle) throw Error('AGDF_MCP_FACADE_START_UNCONFIRMED');
+if (stopRequested) await handle.close();

package/lib/mcp-lifecycle/facade-owner-entry.js

@@ -0,0 +1,34 @@
+// Stable launcher-side owner; it loads no immutable SDK code itself. Loss of
+// its host parent requests orderly shutdown, never deletion of active bytes.
+import process from 'node:process';
+import { dirname } from 'node:path';
+import { EventEmitter } from 'node:events';
+import { inspectMcpServerPackage, acquireMcpExecutableClaim } from './package.js';
+import { supervisePluginMcpFacade } from './plugin-runtime.js';
+
+if (!process.send || !process.connected || !process.argv[2] || process.argv[2].length > 65536) throw Error('AGDF_MCP_FACADE_INPUT_INVALID');
+const input = JSON.parse(process.argv[2]), expected = input.runtime;
+const signals = new EventEmitter();
+let stopRequested = false, supervising = false;
+const stop = () => { stopRequested = true; if (supervising) signals.emit('SIGTERM'); };
+process.on('disconnect', stop); process.on('SIGINT', stop); process.on('SIGTERM', stop);
+process.on('message', message => { if (message?.kind === 'owner_stop' && message.token === input.token) stop(); });
+try {
+  const actual = inspectMcpServerPackage({ dataRoot: dirname(expected.root), expectedVersion: expected.version });
+  if (actual.status !== 'matched' || actual.root !== expected.root || actual.digest !== expected.digest
+    || actual.dispatcherDigest !== expected.dispatcherDigest || actual.sdkDigest !== expected.sdkDigest) throw Error('AGDF_MCP_FACADE_IDENTITY_INVALID');
+  const runtime = { ...actual, immutable: true, publication_id: expected.publication_id, publisher_root: expected.publisher_root };
+  const publicationDeadline = performance.now() + Math.max(0, Number(BigInt(input.deadline_ns) - process.hrtime.bigint()) / 1e6);
+  const claim = acquireMcpExecutableClaim(runtime, { publicationDeadline });
+  const ended = supervisePluginMcpFacade({ ...input, runtime, env: process.env, claim, signals, deadlineNs: input.deadline_ns });
+  supervising = true;
+  if (stopRequested) signals.emit('SIGTERM');
+  await ended;
+  if (process.connected) process.send({ kind: 'owner_closed', token: input.token, confirmed: true }, () => process.disconnect());
+} catch (error) {
+  process.exitCode = 1;
+  const code = ['AGDF_MCP_EXECUTABLE_CLAIM_CONTENDED', 'AGDF_MCP_EXECUTABLE_CLAIM_LOCK_UNCONFIRMED',
+    'AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED', 'AGDF_MCP_EXECUTABLE_CLAIM_INVALID'].includes(error?.message)
+    ? error.message : 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
+  if (process.connected) process.send({ kind: 'owner_failed', token: input.token, code }, () => process.disconnect());
+}

package/lib/mcp-lifecycle/host-config.js

@@ -0,0 +1,60 @@
+import { execHostFileSync } from "../host-command.js";
+import { isAbsolute, resolve } from "node:path";
+import { resolveMcpHostAdapter, validateMcpResolvedSources } from "./adapter-contract.js";
+import { codexAdapterConstants } from "./adapters/codex.js";
+import { copilotAdapterConstants } from "./adapters/copilot.js";
+import { opencodeAdapterConstants } from "./adapters/opencode.js";
+
+export function createMcpRegistrationSpec({ surface, scope = "project", target, runtime, execPath, host = null }) {
+  if (!isAbsolute(target) || !isAbsolute(execPath) || !isAbsolute(runtime.entrypoint)) {
+    throw new Error("AGDF_MCP_REGISTRATION_PATH_INVALID");
+  }
+  const adapter = resolveMcpHostAdapter(surface);
+  const reference = runtime.references?.find((item) => item.surface === surface
+    && (!item.role || item.role === 'governance')
+    && item.native_scope === adapter.nativeScope(scope)
+    && (scope === "user" || item.target === resolve(target))) ?? null;
+  return Object.freeze({ surface, scope, target: resolve(target), command: execPath,
+    args: Object.freeze([runtime.entrypoint, "--surface", surface]), version: runtime.version,
+    digest: runtime.digest, host, reference });
+}
+
+export function inspectMcpRegistration({ surface, scope, target, spec, env = {}, exec = execHostFileSync } = {}) {
+  return resolveMcpHostAdapter(surface).inspect({ scope, target, spec, env, exec });
+}
+
+export function createMcpRegistrationTransaction({
+  action, surface, scope, target, spec, previousSpec = null, revalidate, env = {}, exec = execHostFileSync,
+} = {}) {
+  return resolveMcpHostAdapter(surface).createTransaction({ action, scope, target, spec, previousSpec, revalidate, env, exec });
+}
+
+export function inspectMcpHost({ surface, target, exec = execHostFileSync } = {}) {
+  return resolveMcpHostAdapter(surface).probeHost({ target, exec });
+}
+
+export function resolveMcpSources({ surface, scope, target, env = {} } = {}) {
+  const sources = resolveMcpHostAdapter(surface).resolveSources({ scope, target, env });
+  const validation = validateMcpResolvedSources(sources);
+  if (!validation.valid) throw new Error(`AGDF_MCP_ADAPTER_SOURCES_INVALID:${validation.errors.join(",")}`);
+  return sources;
+}
+
+export function createMcpReferenceIdentity({ surface, scope, target, registration, createdConfig = false } = {}) {
+  return resolveMcpHostAdapter(surface).referenceIdentity({ scope, target, registration, createdConfig });
+}
+
+export function mcpPermissionEffect(surface, input = {}) {
+  return resolveMcpHostAdapter(surface).permissionEffect(input);
+}
+
+export function mcpNativeScope(surface, scope) {
+  return resolveMcpHostAdapter(surface).nativeScope(scope);
+}
+
+export const mcpHostConfigConstants = Object.freeze({
+  codexMarker: codexAdapterConstants.marker,
+  openCodeOwner: opencodeAdapterConstants.owner,
+  openCodeCreatedConfig: opencodeAdapterConstants.createdConfig,
+  copilotOwner: copilotAdapterConstants.owner,
+});