create-agdf 0.14.5 → 0.20.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/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/generated/plugins/copilot/agdf/runtime/create-agdf/lib/npm-invocation.js

@@ -0,0 +1,27 @@
+import { dirname, join, win32 } from "node:path";
+import process from "node:process";
+
+export function npmExecutable({
+  platform = process.platform,
+  execPath = process.execPath,
+  env = process.env,
+} = {}) {
+  const testCli = env.NODE_ENV === "test" ? env.AGDF_TEST_NPM_CLI_PATH || "" : "";
+  if (testCli) return Object.freeze({ executable: execPath, prefix: Object.freeze([testCli]) });
+  if (platform === "win32") {
+    return Object.freeze({
+      executable: execPath,
+      prefix: Object.freeze([win32.join(win32.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js")]),
+    });
+  }
+  return Object.freeze({ executable: "npm", prefix: Object.freeze([]) });
+}
+
+export function npmInvocation(args, options = {}) {
+  const npm = npmExecutable(options);
+  return Object.freeze({ executable: npm.executable, args: Object.freeze([...npm.prefix, ...args]) });
+}
+
+export function defaultNpmInstallRoot(dataRoot, version) {
+  return join(dataRoot, version);
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/repository-context.js

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, sep } from "node:path";
+
+function isInside(root, candidate) {
+  const path = relative(root, candidate);
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+
+function nativeRealpath(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+// Git reports the root with long names, while realpathSync keeps Windows 8.3 short names such as
+// C:\Users\RUNNER~1. Map the reported root onto the working directory's own spelling.
+function rootInWorkingDirectorySpelling(reportedRoot, workingDirectory) {
+  if (isInside(reportedRoot, workingDirectory)) return reportedRoot;
+  const target = nativeRealpath(reportedRoot);
+  for (let current = workingDirectory; ; current = dirname(current)) {
+    if (nativeRealpath(current) === target) return current;
+    if (dirname(current) === current) return "";
+  }
+}
+
+export function resolveRepositoryContext(workingDirectory, dependencies = {}) {
+  const runGit = dependencies.runGit ?? spawnSync;
+  const rawPath = String(workingDirectory ?? "").trim();
+  if (!rawPath || !isAbsolute(rawPath) || !existsSync(rawPath)) {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: rawPath || "unavailable",
+      repository_root: "",
+      reason_code: "working_directory_unavailable",
+      authorizes: false,
+    });
+  }
+  let canonicalWorkingDirectory;
+  try {
+    canonicalWorkingDirectory = realpathSync(rawPath);
+    if (!statSync(canonicalWorkingDirectory).isDirectory()) throw new Error("not_directory");
+  } catch {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: rawPath,
+      repository_root: "",
+      reason_code: "working_directory_unavailable",
+      authorizes: false,
+    });
+  }
+  const child = runGit("git", ["-C", canonicalWorkingDirectory, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 5000,
+  });
+  if (child.status !== 0) {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: canonicalWorkingDirectory,
+      repository_root: "",
+      reason_code: "not_in_git_worktree",
+      authorizes: false,
+    });
+  }
+  try {
+    const repositoryRoot = rootInWorkingDirectorySpelling(realpathSync(String(child.stdout ?? "").trim()), canonicalWorkingDirectory);
+    if (!repositoryRoot) throw new Error("root_mismatch");
+    return Object.freeze({
+      context_state: "repository_bound",
+      working_directory: canonicalWorkingDirectory,
+      repository_root: repositoryRoot,
+      reason_code: "verified_git_worktree",
+      authorizes: false,
+    });
+  } catch {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: canonicalWorkingDirectory,
+      repository_root: "",
+      reason_code: "repository_root_unavailable",
+      authorizes: false,
+    });
+  }
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/runtime/control-command-service.js

@@ -0,0 +1,12 @@
+import { executeApprovalCommand } from "#agdf-core/control-state/approval-command.js";
+import { evaluateGateCheck } from "#agdf-core/control-evaluation/gate-check.js";
+import { cliGitObservation } from "../control-evaluation/git-observation.js";
+import { pluginDefinition } from "./control-context.js";
+
+const evaluateLocalGate = (root, selection) => evaluateGateCheck(root, selection, cliGitObservation);
+
+export function recordGateApprovalCommand(root, command) {
+  return executeApprovalCommand(root, command, {
+    evaluateGateCheck: evaluateLocalGate, packageVersion: pluginDefinition.version,
+  });
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/runtime/control-context.js

@@ -0,0 +1,11 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createResourceContext, resources as coreResources, configuredLanguage as configured, resolveConfiguredChatLanguage as resolveLanguage } from "#agdf-core/resources/context.js";
+const packageURL = new URL("../../", import.meta.url);
+const generatedURL = new URL("../../generated/", import.meta.url);
+const contractsURL = coreResources.packageRoot === fileURLToPath(packageURL)
+  ? pathToFileURL(`${coreResources.contractsRoot}/`)
+  : new URL("plugins/agdf/meta/contracts/", generatedURL);
+export const resources = createResourceContext({ packageURL, generatedURL, contractsURL });
+export const { packageRoot, generatedRoot, pluginDefinition, interactionLocales } = resources;
+export const configuredLanguage = value => configured(value, resources);
+export const resolveConfiguredChatLanguage = target => resolveLanguage(target, resources);

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/runtime/git-history.js

@@ -0,0 +1,7 @@
+import { execFileSync } from "node:child_process";
+export function readGitHistory(root, path) {
+  const git = args => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000, maxBuffer: 1024 * 1024 });
+  return git(["log", "--all", "--follow", "--format=%H", "--", path]).trim().split(/\r?\n/u).filter(Boolean).slice(0, 25).flatMap(commit => {
+    try { return [{ path, commit, content: git(["show", `${commit}:${path}`]) }]; } catch { return []; }
+  });
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/runtime/git-originals.js

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { isSafeControlRelativePath } from "#agdf-core/control-state/contained-file.js";
+import { directoryIdentity } from "#agdf-core/control-state/run-store-inspection.js";
+import { canonicalRunText } from "#agdf-core/control-state/run-seal.js";
+const textDigest = content => `sha256:${createHash("sha256").update(canonicalRunText(content)).digest("hex")}`;
+function git(root, args) {
+  return execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "ignore"], timeout: 3000, maxBuffer: 2 * 1024 * 1024 });
+}
+
+// Search only this checkout's current history and the exact referenced path. Git is a source
+// of original bytes, never proof of a historical approval. Symlink/tree objects are not sources.
+export function readGitOriginals(root, path) {
+  if (!isSafeControlRelativePath(path)) return [];
+  try {
+    directoryIdentity(git(root, ["rev-parse", "--show-toplevel"]).toString().replace(/\r?\n$/u, ""));
+    // Git resolves Windows short/long directory aliases; filesystem-relative paths do not.
+    const prefix = git(root, ["rev-parse", "--show-prefix"]).toString().replace(/\r?\n$/u, "");
+    const objectPath = `${prefix}${path}`;
+    if (!isSafeControlRelativePath(objectPath)) return [];
+    const commits = [...new Set([git(root, ["rev-parse", "HEAD"]).toString().trim(),
+      ...git(root, ["log", "-8", "--format=%H", "--", path]).toString().trim().split(/\r?\n/u)])]
+      .filter((commit) => /^[0-9a-f]{40,64}$/u.test(commit));
+    const originals = [];
+    for (const commit of commits) {
+      try {
+        const tree = git(root, ["ls-tree", "--full-tree", "-z", commit, "--", objectPath]).toString();
+        if (!/^100(?:644|755) blob [0-9a-f]+\t/u.test(tree) || tree.slice(tree.indexOf("\t") + 1, -1) !== objectPath) continue;
+        const bytes = git(root, ["show", `${commit}:${objectPath}`]);
+        originals.push({ path, git_path: objectPath, source: "git", commit, digest: textDigest(bytes.toString("utf8")), bytes: bytes.toString("base64") });
+      } catch { /* Missing or oversized objects require manual recovery. */ }
+    }
+    return originals;
+  } catch { return []; }
+}
+