create-agdf 0.14.4 → 0.20.0

package/lib/mcp-lifecycle/plugin-runtime.js

@@ -0,0 +1,420 @@
+import { execFileSync, spawn, fork } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmdirSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { createHash, randomUUID } from 'node:crypto';
+import { digestDirectory, digestPluginMcpDispatcherSource, MCP_DISPATCHER_RUNTIME_ENTRIES } from "#agdf-core/runtime/plugin-provenance.js";
+import { acquireMcpExecutableClaim, inspectMcpServerPackage, mcpPackageConstants, mcpRuntimeRetirementState, prepareMcpServerPackage, createMcpRuntimeRetirementTransaction } from "./package.js";
+
+// Plugin-local AGDF MCP runtime shared by the hosts whose runtime plugin declares the server itself:
+// Claude Code passes ${CLAUDE_PLUGIN_DATA}, which it deletes on uninstall; Codex receives an absolute
+// AGDF-owned data root from the installer-written declaration. The plugin ships the server and
+// dispatcher; only the pinned MCP SDK is installed from npm, once.
+const SDK_PACKAGE_SPEC = "@modelcontextprotocol/server@2.0.0";
+// Without the override the SDK is installed with `npm ci` from the lock the plugin ships and must match
+// the shipped digest; the override deliberately restores the unverified install and is recorded.
+export const SDK_BUNDLE = Object.freeze({ manifest: "package.json", lock: "package-lock.json", expected: "expected-sdk.json" });
+export const SDK_OVERRIDE_ENV = "AGDF_MCP_ALLOW_UNVERIFIED_SDK";
+export const SDK_VERIFICATION = Object.freeze({ verified: "verified", override: "unverified_override" });
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function ownedRoot(root) {
+  return readJson(join(root, mcpPackageConstants.marker))?.owner === mcpPackageConstants.owner;
+}
+
+export function pluginMcpVersion(pluginRoot) {
+  const version = readJson(join(pluginRoot, "runtime", "runtime-manifest.json"))?.version;
+  if (typeof version !== "string" || !version) throw new Error("AGDF_MCP_PLUGIN_RUNTIME_INVALID");
+  return version;
+}
+
+function copyPluginPackages({ pluginRoot, stage, version }) {
+  const serverSource = join(pluginRoot, "mcp", "server");
+  const runtimePackage = join(pluginRoot, "runtime", "create-agdf");
+  if (!existsSync(join(serverSource, "package.json")) || !existsSync(runtimePackage)) {
+    throw new Error("AGDF_MCP_PLUGIN_RUNTIME_INVALID");
+  }
+  cpSync(serverSource, join(stage, "node_modules", "@agdf", "mcp-server"), { recursive: true });
+  const dispatcherRoot = join(stage, "node_modules", "create-agdf");
+  for (const entry of MCP_DISPATCHER_RUNTIME_ENTRIES.filter((item) => item !== "package.json")) {
+    cpSync(join(runtimePackage, entry), join(dispatcherRoot, entry), { recursive: true });
+  }
+  writeFileSync(join(dispatcherRoot, "package.json"), `${JSON.stringify({
+    name: "create-agdf",
+    version,
+    private: true,
+    type: "module",
+    exports: { "./mcp-dispatch-runtime": "./lib/mcp-dispatch-runtime.js" },
+    imports: { "#agdf-core": "./runtime/core/lib/index.js", "#agdf-core/*": "./runtime/core/lib/*" },
+  }, null, 2)}\n`, "utf8");
+}
+
+// The locked SDK bundle the plugin ships under mcp/sdk/ (generated by scripts/sync-plugin-mcp.js).
+export function readPluginSdkBundle(pluginRoot) {
+  const sdkRoot = join(pluginRoot, "mcp", "sdk");
+  const expected = readJson(join(sdkRoot, SDK_BUNDLE.expected));
+  if (expected?.schema_version !== 1 || typeof expected.sdk_digest !== "string" || !Array.isArray(expected.packages)
+      || !existsSync(join(sdkRoot, SDK_BUNDLE.manifest)) || !existsSync(join(sdkRoot, SDK_BUNDLE.lock))) {
+    throw new Error("AGDF_MCP_PLUGIN_RUNTIME_INVALID");
+  }
+  return Object.freeze({ sdkRoot, expected });
+}
+
+export function sdkOverrideActive(env = process.env) {
+  return env?.[SDK_OVERRIDE_ENV] === "1";
+}
+
+// The launcher and lifecycle qualification bind to the same shipped sources.
+export function pluginMcpRuntimeIdentity(pluginRoot) {
+  const version = pluginMcpVersion(pluginRoot);
+  return Object.freeze({ version, digest: digestDirectory(join(pluginRoot, 'mcp/server')),
+    dispatcherDigest: digestPluginMcpDispatcherSource(join(pluginRoot, 'runtime/create-agdf'), version),
+    sdkDigest: readPluginSdkBundle(pluginRoot).expected.sdk_digest });
+}
+
+export function ensurePluginMcpRuntime({
+  pluginRoot,
+  dataRoot,
+  execPath = process.execPath,
+  exec = execFileSync,
+  npmOptions = {},
+  now = Date.now(),
+  env = process.env,
+  publicationDeadline = performance.now() + CONCURRENT_PUBLICATION_WAIT_MS,
+} = {}) {
+  if (!pluginRoot || !dataRoot) throw new Error("AGDF_MCP_PLUGIN_DATA_MISSING");
+  const version = pluginMcpVersion(pluginRoot);
+  const { sdkRoot, expected } = readPluginSdkBundle(pluginRoot);
+  const override = sdkOverrideActive(env);
+  mkdirSync(resolve(dataRoot), { recursive: true });
+  if (lstatSync(resolve(dataRoot)).isSymbolicLink()) throw Error('AGDF_MCP_RUNTIME_UNOWNED');
+  const mcpDataRoot = join(realpathSync(resolve(dataRoot)), "mcp");
+  if (existsSync(mcpDataRoot) && lstatSync(mcpDataRoot).isSymbolicLink()) throw Error('AGDF_MCP_RUNTIME_UNOWNED');
+  mkdirSync(mcpDataRoot, { recursive: true });
+  const { digest: sourceServerDigest, dispatcherDigest: sourceDispatcherDigest } = pluginMcpRuntimeIdentity(pluginRoot);
+  // Keep old, foreign and unclaimed roots intact. Same-version updates publish
+  // another content-addressed package, rather than moving executing files away.
+  const key = createHash('sha256').update(JSON.stringify({ version, server: sourceServerDigest,
+    dispatcher: sourceDispatcherDigest, sdk: expected.sdk_digest, verification: override ? 'unverified_override' : 'verified' })).digest('hex');
+  const publicationRoot = join(mcpDataRoot, 'generations', key);
+  for (const path of [join(mcpDataRoot, 'generations'), publicationRoot]) {
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw Error('AGDF_MCP_RUNTIME_UNOWNED');
+    mkdirSync(path, { recursive: true });
+  }
+  const published = runtime => Object.freeze({ ...runtime, publication_id: key, publisher_root: mcpDataRoot, immutable: true });
+  // Reuse only matching plugin sources and, unless overridden, the locked SDK.
+  const usable = (runtime) => runtime.status === "matched"
+    && runtime.digest === sourceServerDigest
+    && runtime.dispatcherDigest === sourceDispatcherDigest
+    && (override || (runtime.sdkDigest === expected.sdk_digest && runtime.sdkVerification !== SDK_VERIFICATION.override));
+  const replacementDeadline = publicationDeadline;
+  // After a plugin update several launchers replace the same runtime at once (Claude's version probe and
+  // respawn, every plugin server, reconnecting sessions); states they cause each other are retried briefly.
+  for (let attempt = 1; ; attempt += 1) {
+    const current = inspectMcpServerPackage({ dataRoot: publicationRoot, expectedVersion: version });
+    if (usable(current)) {
+      if (performance.now() >= publicationDeadline) throw Error('AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED');
+      return published({ ...current, changed: false });
+    }
+    try {
+      if (current.status !== 'absent') throw Error(ownedRoot(current.root) ? 'AGDF_MCP_IMMUTABLE_RUNTIME_MISMATCH' : 'AGDF_MCP_RUNTIME_UNOWNED');
+      const prepared = prepareMcpServerPackage({
+        dataRoot: publicationRoot,
+        immutable: true,
+        expectedVersion: version,
+        publicationDeadline,
+        execPath,
+        exec,
+        npmOptions,
+        expectedSdk: override ? null : expected,
+        sdkVerification: override ? SDK_VERIFICATION.override : SDK_VERIFICATION.verified,
+        acquire({ stage, install, installLocked }) {
+          if (override) {
+            install([SDK_PACKAGE_SPEC]);
+          } else {
+            cpSync(join(sdkRoot, SDK_BUNDLE.manifest), join(stage, "package.json"));
+            cpSync(join(sdkRoot, SDK_BUNDLE.lock), join(stage, "package-lock.json"));
+            installLocked();
+          }
+          copyPluginPackages({ pluginRoot, stage, version });
+        },
+      });
+      prepared.commit();
+      return published(prepared);
+    } catch (error) {
+      if (performance.now() >= publicationDeadline) throw Error('AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED');
+      // A concurrent launcher may have installed the same runtime first.
+      const settled = inspectMcpServerPackage({ dataRoot: publicationRoot, expectedVersion: version });
+      if (usable(settled)) return published({ ...settled, changed: false });
+      const publicationLocked = error?.message === 'AGDF_RUN_WRITE_LOCKED';
+      if (publicationLocked && error.lock_owner_status !== 'live') throw error;
+      if (!concurrentReplacementError(error)
+          || (publicationLocked ? performance.now() >= replacementDeadline : attempt >= CONCURRENT_REPLACEMENT_ATTEMPTS)) throw error;
+      sleepSync(publicationLocked
+        ? Math.min(CONCURRENT_REPLACEMENT_DELAY_MS, Math.max(0, replacementDeadline - performance.now()))
+        : CONCURRENT_REPLACEMENT_DELAY_MS * attempt);
+    }
+  }
+}
+
+const CONCURRENT_REPLACEMENT_ATTEMPTS = 6;
+const CONCURRENT_REPLACEMENT_DELAY_MS = 150;
+// SDK acquisition and copying can exceed the old 2.25-second retry window on
+// Windows. Wait for the publication owner without taking or removing its lock.
+const CONCURRENT_PUBLICATION_WAIT_MS = 30_000;
+
+// Only states another launcher can cause: a runtime moved away mid-inspection or a lost stage rename.
+// npm, SDK and verification failures are never retried.
+function concurrentReplacementError(error) {
+  return ['AGDF_MCP_RUNTIME_UNOWNED', 'AGDF_RUN_WRITE_LOCKED'].includes(error?.message) || ["EPERM", "EEXIST", "ENOTEMPTY", "EBUSY", "ENOENT"].includes(error?.code);
+}
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+// Claude Code passes ${CLAUDE_PLUGIN_DATA} in the environment and needs no arguments; its cockpit entry
+// adds the project root Claude substitutes for ${CLAUDE_PROJECT_DIR}. Codex and Copilot declarations
+// pass the surface and an absolute data root after host variable expansion.
+export function parseLauncherArguments(argv, env = {}) {
+  const args = [...argv];
+  const prepareOnly = args.at(-1) === "--prepare";
+  if (prepareOnly) args.pop();
+  if (args.length === 0) return { surface: "claude", dataRoot: env.CLAUDE_PLUGIN_DATA, prepareOnly };
+  if (args.length === 2 && args[0] === "--cockpit-dir" && typeof args[1] === "string" && isAbsolute(args[1]) && !args[1].includes("${")) {
+    return { surface: "claude", dataRoot: env.CLAUDE_PLUGIN_DATA, cockpitDir: args[1], prepareOnly };
+  }
+  if (args.length === 5 && args[0] === '--surface' && args[1] === 'codex' && args[2] === '--data'
+    && typeof args[3] === 'string' && isAbsolute(args[3]) && !args[3].includes('${') && !args[3].includes('{{') && args[4] === '--cockpit') {
+    return { surface: 'codex', dataRoot: args[3], cockpitMode: 'plugin', prepareOnly };
+  }
+  if (args.length === 4 && args[0] === "--surface" && ["codex", "copilot"].includes(args[1]) && args[2] === "--data"
+      && typeof args[3] === "string" && isAbsolute(args[3])) {
+    return { surface: args[1], dataRoot: args[3], prepareOnly };
+  }
+  return null;
+}
+
+// One stderr line per failure: stable code, cause and one recovery action. Plugin skills and hooks do
+// not depend on this launcher and keep working while the MCP server is refused.
+const LAUNCHER_FAILURES = Object.freeze({
+  AGDF_MCP_PLUGIN_DATA_MISSING: "the plugin data directory is missing",
+  AGDF_MCP_SDK_PACKAGE_SET_MISMATCH: "the installed MCP SDK packages differ from the lock shipped with this plugin",
+  AGDF_MCP_SDK_DIGEST_MISMATCH: "the installed MCP SDK content differs from the version shipped with this plugin",
+  AGDF_MCP_PACKAGE_ACQUISITION_FAILED: "npm could not install the locked MCP SDK (network, registry or integrity check)",
+  AGDF_MCP_RUNTIME_UNOWNED: "the runtime directory exists but is not owned by AGDF",
+  AGDF_MCP_PLUGIN_RUNTIME_INVALID: "the installed AGDF plugin is incomplete",
+  AGDF_MCP_EXECUTABLE_CLAIM_CONTENDED: "the claim publication phase is still held by a verified live owner",
+  AGDF_MCP_EXECUTABLE_CLAIM_LOCK_UNCONFIRMED: "the claim publication lock ownership cannot be confirmed",
+  AGDF_MCP_EXECUTABLE_CLAIM_INVALID: "the executable claim failed its current runtime integrity check",
+  AGDF_MCP_PLUGIN_RUNTIME_FAILED: "the AGDF MCP runtime could not be started",
+  AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED: "the preparation and claim phases exhausted their shared publication deadline",
+});
+
+export function launcherFailureLine(code, phase) {
+  if (!Object.hasOwn(LAUNCHER_FAILURES, code)) { code = 'AGDF_MCP_PLUGIN_RUNTIME_FAILED'; phase ??= 'preparation'; }
+  const cause = LAUNCHER_FAILURES[code] ?? "the AGDF MCP runtime could not be prepared";
+  const claimRecovery = {
+    AGDF_MCP_EXECUTABLE_CLAIM_CONTENDED: 'Wait for the verified publication owner to finish, then deliberately refresh this connection; retain its live lock.',
+    AGDF_MCP_EXECUTABLE_CLAIM_LOCK_UNCONFIRMED: 'Inspect publication lock ownership through the supported AGDF owner; do not remove an unconfirmed lock.',
+    AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED: 'Prepare the runtime through the installed launcher --prepare before deliberately refreshing the affected connection.',
+  };
+  const recovery = claimRecovery[code] ?? (["AGDF_MCP_SDK_PACKAGE_SET_MISMATCH", "AGDF_MCP_SDK_DIGEST_MISMATCH", "AGDF_MCP_PACKAGE_ACQUISITION_FAILED"].includes(code)
+    ? `Check your npm registry or mirror and restart; to accept an unverified SDK deliberately, set ${SDK_OVERRIDE_ENV}=1.`
+    : code === "AGDF_MCP_RUNTIME_UNOWNED"
+      ? "Move the directory away and restart."
+      : "Reinstall the AGDF plugin and restart.");
+  const observedPhase = ['preparation', 'facade'].includes(phase) ? `${phase} phase: ` : '';
+  return `${code}: ${observedPhase}${cause}. ${recovery}`;
+}
+
+export async function launchPluginMcpServer({
+  pluginRoot,
+  argv = process.argv.slice(2),
+  env = process.env,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  ensure = ensurePluginMcpRuntime,
+  acquireClaim = acquireMcpExecutableClaim,
+  execPath = process.execPath,
+  startFacade,
+} = {}) {
+  const invocation = parseLauncherArguments(argv, env);
+  if (!invocation) {
+    stderr.write("AGDF_MCP_ARGUMENTS_INVALID\n");
+    process.exitCode = 1;
+    return null;
+  }
+  const { surface, dataRoot, cockpitDir, cockpitMode, prepareOnly } = invocation;
+  const publicationDeadline = performance.now() + CONCURRENT_PUBLICATION_WAIT_MS;
+  let runtime;
+  try {
+    // Reject a damaged installed dispatcher before publication, claim acquisition
+    // or SDK execution. Its downstream resource context cannot qualify a facade;
+    // starting one first would correctly retain its unconfirmed executable use.
+    if (ensure === ensurePluginMcpRuntime) {
+      const manifest = readJson(join(pluginRoot, 'runtime/runtime-manifest.json'));
+      if (!/^[a-f0-9]{64}$/u.test(manifest?.digest ?? '')
+        || digestDirectory(join(pluginRoot, 'runtime/create-agdf')) !== manifest.digest) throw Error('AGDF_MCP_PLUGIN_RUNTIME_INVALID');
+    }
+    runtime = ensure({ pluginRoot, dataRoot, env, publicationDeadline });
+  } catch (error) {
+    const code = /^AGDF_[A-Z_]+/.exec(error?.message ?? "")?.[0] ?? 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
+    stderr.write(`${launcherFailureLine(code, code === 'AGDF_MCP_PLUGIN_RUNTIME_FAILED' ? 'preparation' : undefined)}\n`);
+    process.exitCode = 1;
+    return null;
+  }
+  // Announced whenever the override is active, also when an existing runtime is reused under it.
+  if (sdkOverrideActive(env) || runtime.sdkVerification === SDK_VERIFICATION.override) {
+    stderr.write(`AGDF_MCP_SDK_UNVERIFIED_OVERRIDE: ${SDK_OVERRIDE_ENV}=1 is set, so the MCP SDK was not checked against the version shipped with this plugin. Unset it and restart to verify the runtime again.\n`);
+  }
+  if (prepareOnly) {
+    stdout.write(`${JSON.stringify({ status: runtime.status, version: runtime.version, root: runtime.root, changed: runtime.changed })}\n`);
+    return runtime;
+  }
+  // The stable launcher directly owns the facade process. It retains its exact
+  // executable before fork and releases only after orderly teardown AND exit.
+  if (!startFacade && acquireClaim === acquireMcpExecutableClaim) {
+    try { return await startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline }); }
+    catch (error) { const code = Object.hasOwn(LAUNCHER_FAILURES, error?.message) ? error.message : 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
+      stderr.write(`${launcherFailureLine(code, code === 'AGDF_MCP_PLUGIN_RUNTIME_FAILED' ? 'facade' : undefined)}\n`); process.exitCode = 1; return null; }
+  }
+  let claim;
+  try { claim = acquireClaim(runtime, { publicationDeadline }); }
+  catch (error) {
+    const code = ['AGDF_MCP_EXECUTABLE_CLAIM_CONTENDED', 'AGDF_MCP_EXECUTABLE_CLAIM_LOCK_UNCONFIRMED', 'AGDF_MCP_PUBLICATION_DEADLINE_EXCEEDED'].includes(error?.message)
+      ? error.message : 'AGDF_MCP_EXECUTABLE_CLAIM_INVALID';
+    stderr.write(`${launcherFailureLine(code)}\n`); process.exitCode = 1; return null;
+  }
+  try { return await (startFacade ?? supervisePluginMcpFacade)({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline, claim }); }
+  catch (error) {
+    const code = Object.hasOwn(LAUNCHER_FAILURES, error?.message) ? error.message : 'AGDF_MCP_PLUGIN_RUNTIME_FAILED';
+    stderr.write(`${launcherFailureLine(code, 'facade')}\n`); process.exitCode = 1; return null;
+  }
+
+}
+
+export function supervisePluginMcpFacade({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, claim, deadlineNs, Fork = fork, signals = process } = {}) {
+  return new Promise((resolve, reject) => {
+    let acknowledged = false;
+    const child = Fork(join(runtime.dispatcherRoot, 'lib/mcp-lifecycle/facade-entry.js'),
+      [JSON.stringify({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, token: claim.token, deadline_ns: deadlineNs })],
+      { env, windowsHide: true, stdio: ['inherit', 'inherit', 'inherit', 'ipc'], execArgv: [] });
+    claim.bindOwnedChild(child, { confirmedEnd: () => acknowledged && child.exitCode === 0 && child.signalCode === null });
+    // Queue shutdown over the private channel. A signal can arrive before the
+    // SDK child has installed its handlers and would erase teardown evidence.
+    const terminate = () => { if (child.connected) child.send({ kind: 'facade_stop', token: claim.token }, () => {}); };
+    const interrupt = terminate;
+    const detach = () => { signals.off('SIGINT', interrupt); signals.off('SIGTERM', terminate); signals.off('disconnect', terminate); };
+    signals.on('SIGINT', interrupt); signals.on('SIGTERM', terminate);
+    signals.on('disconnect', terminate);
+    child.on('message', message => { if (message?.kind === 'facade_closed' && message.token === claim.token && message.confirmed === true) acknowledged = true; });
+    child.once('error', error => { detach(); reject(error); });
+    child.once('exit', (code, signal) => { detach();
+      if (!acknowledged || code !== 0 || signal) { process.exitCode = 1; reject(Error('AGDF_MCP_FACADE_CLOSE_UNCONFIRMED')); }
+      else resolve({ closed: true, confirmed_exit: true });
+    });
+  });
+}
+
+// The owner must outlive its launcher: Windows libuv kills non-detached children
+// with their parent. Keep IPC referenced and prove the facade's acknowledged
+// exit after disconnect; no PID discovery or claim GC.
+function startFacadeOwner({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, env, publicationDeadline }) {
+  const token = randomUUID();
+  const deadline = (process.hrtime.bigint() + BigInt(Math.floor(Math.max(0, publicationDeadline - performance.now()) * 1e6))).toString();
+  return new Promise((resolve, reject) => {
+    const child = fork(join(pluginRoot, 'runtime/create-agdf/lib/mcp-lifecycle/facade-owner-entry.js'),
+      [JSON.stringify({ runtime, surface, cockpitDir, cockpitMode, pluginRoot, token, deadline_ns: deadline })],
+      { env, detached: true, windowsHide: true, stdio: ['inherit', 'inherit', 'inherit', 'ipc'], execArgv: [] });
+    let confirmed = false, failure;
+    const stop = () => { if (child.connected) child.send({ kind: 'owner_stop', token }, () => {}); };
+    process.once('SIGTERM', stop); process.once('SIGINT', stop);
+    const detach = () => { process.off('SIGTERM', stop); process.off('SIGINT', stop); };
+    child.on('message', message => {
+      if (message?.kind === 'owner_closed' && message.token === token && message.confirmed === true) confirmed = true;
+      if (message?.kind === 'owner_failed' && message.token === token && Object.hasOwn(LAUNCHER_FAILURES, message.code)) failure = message.code;
+    });
+    child.once('error', error => { detach(); reject(error); });
+    child.once('exit', (code, signal) => { detach();
+      if (code === 0 && !signal && confirmed) resolve({ closed: true, confirmed_exit: true });
+      else reject(Error(failure ?? 'AGDF_MCP_FACADE_CLOSE_UNCONFIRMED'));
+    });
+  });
+}
+
+export function claudePluginDataRoot({ claudeConfigDir, pluginId = "agdf@agdf" }) {
+  // Claude Code names the directory after the plugin id with every character outside [A-Za-z0-9_-]
+  // replaced by "-" (agdf@agdf -> agdf-agdf).
+  return join(resolve(claudeConfigDir), "plugins", "data", pluginId.replace(/[^A-Za-z0-9_-]/g, "-"));
+}
+
+export const claudePluginMcpConstants = Object.freeze({ sdkPackageSpec: SDK_PACKAGE_SPEC, launcher: "mcp/agdf-mcp-launch.js" });
+
+// Codex keeps the plugin-local MCP runtime in an AGDF-owned data root because it passes no plugin data
+// directory; `codex plugin remove` cannot delete it. `dataRoot` is the launcher data root (--data);
+// uninstall removes it only when it holds nothing but owned runtimes and abandoned stages under mcp/.
+export function inspectPluginMcpDataRoot(dataRoot) {
+  if (!existsSync(dataRoot)) return "absent";
+  try {
+    if (!lstatSync(dataRoot).isDirectory() || lstatSync(dataRoot).isSymbolicLink()) return "foreign";
+    if (readdirSync(dataRoot).some((name) => name !== "mcp")) return "foreign";
+    const mcpDataRoot = join(realpathSync(dataRoot), "mcp");
+    if (!existsSync(mcpDataRoot)) return "owned";
+    if (!lstatSync(mcpDataRoot).isDirectory() || lstatSync(mcpDataRoot).isSymbolicLink()) return "foreign";
+    let protectedFiles = false;
+    for (const name of readdirSync(mcpDataRoot)) {
+      const path = join(mcpDataRoot, name);
+      const stats = lstatSync(path);
+      if (!stats.isDirectory() || stats.isSymbolicLink()) return "foreign";
+      if (name !== 'generations') {
+        if (!ownedRoot(path) && !name.startsWith('.stage-')) return 'foreign';
+        protectedFiles = true; continue;
+      }
+      for (const key of readdirSync(path)) {
+        const publication = join(path, key);
+        if (!/^[0-9a-f]{64}$/u.test(key) || lstatSync(publication).isSymbolicLink() || !lstatSync(publication).isDirectory()) return 'foreign';
+        for (const version of readdirSync(publication)) {
+          const runtimeRoot = join(publication, version);
+          if (!ownedRoot(runtimeRoot) || mcpRuntimeRetirementState(runtimeRoot) !== 'eligible') protectedFiles = true;
+        }
+      }
+    }
+    return protectedFiles ? 'protected' : "owned";
+  } catch {
+    return "foreign";
+  }
+}
+
+// Retire each verified generation under the publisher's existing lock. Never
+// recursively delete the encompassing root after a separate state inspection:
+// a concurrent launcher may publish or acquire a new generation in between.
+export function retirePluginMcpDataRoot(dataRoot, revalidate = () => {}) {
+  revalidate();
+  if (inspectPluginMcpDataRoot(dataRoot) !== 'owned') throw Error('AGDF_MCP_RUNTIME_RETAINED');
+  dataRoot = realpathSync(dataRoot);
+  const mcp = join(dataRoot, 'mcp'), generations = join(mcp, 'generations');
+  try {
+    if (existsSync(generations)) for (const key of readdirSync(generations)) {
+      const publication = join(generations, key);
+      for (const entry of readdirSync(publication)) {
+        revalidate();
+        const root = join(publication, entry), marker = readJson(join(root, mcpPackageConstants.marker));
+        if (!marker || mcpRuntimeRetirementState(root) !== 'eligible') throw Error('AGDF_MCP_RUNTIME_RETAINED');
+        const transaction = createMcpRuntimeRetirementTransaction({ root, version: marker.version });
+        transaction.apply(); transaction.commit();
+      }
+      rmdirSync(publication);
+    }
+    if (existsSync(generations)) rmdirSync(generations);
+    if (existsSync(mcp)) rmdirSync(mcp);
+    revalidate(); rmdirSync(dataRoot);
+    return true;
+  } catch (error) {
+    if (['ENOTEMPTY', 'EEXIST'].includes(error.code)) return false;
+    throw error;
+  }
+}

package/lib/mcp-lifecycle/presentation.js

@@ -0,0 +1,61 @@
+import { interactionLocales } from "../cli/runtime-context.js";
+import { localePack } from "#agdf-core/interaction-presentation.js";
+
+function localized(pack, group, code) {
+  const value = pack?.mcpLifecycle?.[group]?.[code];
+  if (typeof value !== "string") throw new Error(`AGDF_MCP_PRESENTATION_UNLOCALIZED:${group}:${code}`);
+  return value;
+}
+
+export function projectMcpLifecycleResult(report, { language } = {}) {
+  const pack = localePack(interactionLocales, language);
+  const permissionCode = typeof report.permission_effect === "string"
+    ? report.permission_effect : report.permission_effect?.code ?? "inherited_host_user";
+  return Object.freeze({
+    ...report,
+    permission_effect: Object.freeze({ ...(typeof report.permission_effect === "object" ? report.permission_effect : {}),
+      code: permissionCode, text: localized(pack, "permissionEffects", permissionCode) }),
+    fallback: Object.freeze({ ...report.fallback, text: localized(pack, "actions", report.fallback.code) }),
+    next_action: Object.freeze({ ...report.next_action, text: localized(pack, "actions", report.next_action.code) }),
+    diagnostics: Object.freeze((report.diagnostics ?? []).map((item) => Object.freeze({
+      ...item,
+      text: localized(pack, "diagnostics", item.code),
+    }))),
+  });
+}
+
+export function renderMcpLifecycleText(report, { language } = {}) {
+  const pack = localePack(interactionLocales, language);
+  const projected = projectMcpLifecycleResult(report, { language });
+  const labels = pack.mcpLifecycle.labels;
+  const setup = report.setup ? [pack.mcpLifecycle.setup.title,
+    ...report.setup.entries.map(entry => {
+      const view = pack.mcpLifecycle.setup;
+      return `${entry.display_name} (${entry.server_id}) · ${view.labels.source}: ${entry.source}/${entry.scope} · ${view.labels.role}: ${view.roles[entry.role]} · ${view.labels.owner}: ${entry.owner}\n`
+        + ['configured', 'started', 'discovered', 'app_rendered', 'app_interacted'].map(key => `${view.labels[key]}: ${view.states[entry[key]] ?? view.states.unknown}`).join(' · ');
+    }), pack.mcpLifecycle.setup.noticeDescription] : [];
+  return [
+    pack.mcpLifecycle.title,
+    `${labels.operation}: ${report.operation}`,
+    `${labels.result}: ${localized(pack, "results", report.result)}`,
+    `${labels.capability}: ${localized(pack, "capabilities", report.capability)}`,
+    `${labels.surface}: ${report.surface}`,
+    `${labels.scope}: ${report.scope}`,
+    `${labels.scopeEffect}: ${localized(pack, "scopeEffects", report.scope_effect)}`,
+    `${labels.target}: ${report.target}`,
+    `${labels.authorizes}: ${report.authorizes}`,
+    `${labels.runtime}: ${report.runtime?.package_status ?? report.runtime?.status ?? "unknown"}`,
+    `${labels.registration}: ${localized(pack, "registrations", report.registration?.status)}`,
+    `${labels.discovery}: ${localized(pack, "discoveries", report.discovery?.status)}`,
+    `${labels.permissionEffect}: ${projected.permission_effect.text}`,
+    `${labels.diagnostics}: ${projected.diagnostics.length ? projected.diagnostics.map((item) => item.text).join(", ") : localized(pack, "diagnostics", "none")}`,
+    `${labels.nextAction}: ${projected.next_action.text}`,
+    `${labels.fallback}: ${projected.fallback.text}`,
+    ...setup,
+  ].join("\n");
+}
+
+export function printMcpLifecycleResult(report, { json = false, io = console, language } = {}) {
+  io.log(json ? JSON.stringify(projectMcpLifecycleResult(report, { language }), null, 2)
+    : renderMcpLifecycleText(report, { language }));
+}

package/lib/mcp-lifecycle/profile-context.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
+import { assertMcpCapabilityProfile } from "./profile.js";
+
+const profilePath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-mcp-capability.json");
+
+export const mcpCapabilityProfile = assertMcpCapabilityProfile(
+  JSON.parse(readFileSync(profilePath, "utf8")),
+  { expectedVersion: pluginDefinition.version },
+);

package/lib/mcp-lifecycle/profile.js

@@ -0,0 +1,63 @@
+import { mcpQualificationFields, validateMcpQualificationRecord } from "./evidence.js";
+
+const CAPABILITY_STATES = new Set(["supported", "manual_compatible", "unavailable", "unsupported", "unverified"]);
+const REGISTRATION_STATES = new Set(["absent", "matched", "foreign", "owned_mismatch", "precedence_conflict", "invalid"]);
+const DISCOVERY_STATES = new Set(["not_checked", "pending_restart", "discovered", "not_discovered", "unavailable"]);
+const RESULT_STATES = new Set(["not_configured", "configured_pending_restart", "configured_unverified", "discovered_ready", "unchanged", "disabled", "degraded", "failed"]);
+const SURFACES = Object.freeze(["codex", "claude", "opencode", "copilot"]);
+
+function plainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactEnum(actual, expected) {
+  return Array.isArray(actual)
+    && actual.length === expected.size
+    && new Set(actual).size === expected.size
+    && actual.every((value) => expected.has(value));
+}
+
+export function validateMcpCapabilityProfile(profile, { expectedVersion } = {}) {
+  const errors = [];
+  if (!plainObject(profile) || profile.schema_version !== 2) errors.push("schema_version");
+  if (profile?.capability_id !== "agdf-mcp-dispatch") errors.push("capability_id");
+  if (expectedVersion && profile?.release_version !== expectedVersion) errors.push("release_version");
+  if (profile?.tool?.name !== "agdf_dispatch") errors.push("tool_name");
+  if (profile?.tool?.semantic_owner !== "packages/core/lib/skill-dispatch/contract.js") errors.push("semantic_owner");
+  if (Object.hasOwn(profile?.tool ?? {}, "description") || Object.hasOwn(profile?.tool ?? {}, "input_schema")
+      || Object.hasOwn(profile?.tool ?? {}, "output_schema")) errors.push("duplicated_tool_semantics");
+  if (profile?.tool?.authorizes !== false || profile?.tool?.read_only !== true) errors.push("tool_boundary");
+  if (profile?.package?.name !== "@agdf/mcp-server" || profile?.package?.sdk_server !== "2.0.0") errors.push("package");
+  if (profile?.lifecycle?.owner !== "create-agdf" || profile?.lifecycle?.default_scope !== "project") errors.push("lifecycle");
+  if (profile?.lifecycle?.result_contract_version !== 2) errors.push("result_contract_version");
+  if (!exactEnum(profile?.lifecycle?.states?.capability, CAPABILITY_STATES)) errors.push("capability_states");
+  if (!exactEnum(profile?.lifecycle?.states?.registration, REGISTRATION_STATES)) errors.push("registration_states");
+  if (!exactEnum(profile?.lifecycle?.states?.discovery, DISCOVERY_STATES)) errors.push("discovery_states");
+  if (!exactEnum(profile?.lifecycle?.states?.result, RESULT_STATES)) errors.push("result_states");
+  for (const surface of SURFACES) {
+    const adapter = profile?.lifecycle?.adapters?.[surface];
+    if (!plainObject(adapter) || adapter.surface !== surface || !["project", "user"].includes(adapter.default_scope)
+        || !plainObject(adapter.native_scopes) || typeof adapter.project_source !== "string"
+        || typeof adapter.user_source !== "string") errors.push(`adapter:${surface}`);
+  }
+  if (!Array.isArray(profile?.qualification?.records)) errors.push("qualification_records");
+  if (!exactEnum(profile?.qualification?.tuple, new Set(mcpQualificationFields))) errors.push("qualification_tuple");
+  for (const [index, record] of (profile?.qualification?.records ?? []).entries()) {
+    if (!validateMcpQualificationRecord(record).valid) errors.push(`qualification_record:${index}`);
+  }
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
+export function assertMcpCapabilityProfile(profile, options = {}) {
+  const validation = validateMcpCapabilityProfile(profile, options);
+  if (!validation.valid) throw new Error(`AGDF_MCP_CAPABILITY_PROFILE_INVALID:${validation.errors.join(",")}`);
+  return profile;
+}
+
+export const mcpCapabilityProfileContract = Object.freeze({
+  surfaces: SURFACES,
+  capabilityStates: Object.freeze([...CAPABILITY_STATES]),
+  registrationStates: Object.freeze([...REGISTRATION_STATES]),
+  discoveryStates: Object.freeze([...DISCOVERY_STATES]),
+  resultStates: Object.freeze([...RESULT_STATES]),
+});

package/lib/mcp-lifecycle/result.js

@@ -0,0 +1,92 @@
+import { mcpCapabilityProfileContract } from "./profile.js";
+
+const SETS = Object.freeze({
+  capability: new Set(mcpCapabilityProfileContract.capabilityStates),
+  registration: new Set(mcpCapabilityProfileContract.registrationStates),
+  discovery: new Set(mcpCapabilityProfileContract.discoveryStates),
+  result: new Set(mcpCapabilityProfileContract.resultStates),
+});
+
+function freezeArray(value = []) {
+  return Object.freeze(value.map((entry) => Object.freeze({ ...entry })));
+}
+
+function coded(value, fallbackCode) {
+  if (typeof value === "string") return Object.freeze({ code: value, parameters: Object.freeze({}) });
+  if (value && typeof value === "object" && typeof value.code === "string") {
+    return Object.freeze({ ...value, parameters: Object.freeze({ ...(value.parameters ?? {}) }) });
+  }
+  return Object.freeze({ code: fallbackCode, parameters: Object.freeze({}) });
+}
+
+function effectiveScope(registration) {
+  if (registration?.effective_status === "absent") return null;
+  if (registration?.effective_source === "user") return "user";
+  if (["project", "project_override", "local", "shared_project", "inline", "custom"].includes(registration?.effective_source)) return "project";
+  return null;
+}
+
+export function createMcpLifecycleResult({
+  action,
+  result,
+  surface,
+  scope,
+  scopeEffect,
+  target,
+  capability,
+  host = null,
+  runtime,
+  registration,
+  discovery = { status: "not_checked" },
+  changes = [],
+  diagnostics = [],
+  nextAction,
+  fallback = { code: "version_matched_cli_dispatch" },
+  permissionEffect = { code: "inherited_host_user" },
+  setup,
+}) {
+  const invalidCombination = (result === "discovered_ready"
+      && (capability !== "supported" || registration?.status !== "matched" || discovery?.status !== "discovered"
+        || discovery?.source !== "direct_host" || typeof discovery?.evidence_ref !== "string"))
+    || (result === "configured_pending_restart"
+      && (registration?.status !== "matched" || discovery?.status !== "pending_restart"))
+    || (result === "configured_unverified"
+      && (registration?.status !== "matched" || discovery?.status === "discovered"))
+    || (result === "not_configured" && !["absent", "invalid"].includes(registration?.status))
+    || (result === "disabled" && registration?.status !== "absent");
+  if (!["status", "enable", "disable"].includes(action) || !mcpCapabilityProfileContract.surfaces.includes(surface)
+      || !["project", "user"].includes(scope) || !SETS.result.has(result) || !SETS.capability.has(capability)
+      || !SETS.registration.has(registration?.status) || !SETS.discovery.has(discovery?.status)
+      || !runtime || typeof runtime !== "object" || !Array.isArray(changes) || !Array.isArray(diagnostics)
+      || diagnostics.some((item) => !item || typeof item.code !== "string") || invalidCombination) {
+    throw new Error("AGDF_MCP_LIFECYCLE_RESULT_INVALID");
+  }
+  return Object.freeze({
+    schema_version: 2,
+    contract_version: 2,
+    operation: `mcp.${action}`,
+    result,
+    capability,
+    surface,
+    scope,
+    effective_scope: effectiveScope(registration),
+    native_scope: registration.native_scope ?? scope,
+    scope_effect: scopeEffect,
+    target,
+    authorizes: false,
+    host: host ? Object.freeze({ ...host }) : null,
+    permission_effect: coded(permissionEffect, "inherited_host_user"),
+    runtime: Object.freeze({ ...runtime }),
+    registration: Object.freeze({ ...registration,
+      checked_sources: freezeArray(registration.checked_sources ?? registration.sources),
+    }),
+    discovery: Object.freeze({ source: "none", evidence_ref: null, ...discovery }),
+    changes: freezeArray(changes),
+    fallback: coded(fallback, "version_matched_cli_dispatch"),
+    next_action: coded(nextAction, "none"),
+    diagnostics: freezeArray(diagnostics),
+    ...(setup ? { setup: Object.freeze(setup) } : {}),
+  });
+}
+
+export const mcpLifecycleResultStates = SETS;