create-agdf 0.10.1 → 0.10.2

package/lib/installers/local-marketplace.js

@@ -0,0 +1,322 @@
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import process from "node:process";
+import { generatedRoot, packageRoot, pluginDefinition } from "../cli/runtime-context.js";
+
+const MARKETPLACE_ID = "agdf";
+const OWNERSHIP_FILE = ".agdf-owned.json";
+const LEGACY_REPOSITORY = "arndtgold/ai-native-governance-delivery-framework";
+
+function pathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function digestDirectory(root) {
+  const files = [];
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const stats = statSync(path);
+      if (stats.isDirectory()) visit(path);
+      else if (stats.isFile()) files.push(path);
+    }
+  }
+  visit(root);
+  const hash = createHash("sha256");
+  for (const path of files) {
+    hash.update(relative(root, path).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(readFileSync(path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is invalid: ${error.message}`);
+  }
+}
+
+export function defaultAgdfDataRoot({ env = process.env, platform = process.platform, home = homedir() } = {}) {
+  if (env.AGDF_DATA_DIR) return resolve(env.AGDF_DATA_DIR);
+  if (platform === "darwin") return join(home, "Library", "Application Support", "agdf");
+  if (platform === "win32") return join(env.LOCALAPPDATA || env.APPDATA || join(home, "AppData", "Local"), "agdf");
+  return join(env.XDG_DATA_HOME || join(home, ".local", "share"), "agdf");
+}
+
+export function localMarketplaceRoot(options = {}) {
+  return join(defaultAgdfDataRoot(options), "marketplaces", MARKETPLACE_ID);
+}
+
+function ownership(root, { allowBuilding = false } = {}) {
+  if (!existsSync(join(root, OWNERSHIP_FILE))) {
+    throw new Error(`Refusing marketplace path without AGDF ownership marker: ${root}`);
+  }
+  const marker = readJson(join(root, OWNERSHIP_FILE), "AGDF marketplace ownership marker");
+  if (marker.schema_version !== 1 || marker.owner !== "create-agdf" || marker.marketplace_id !== MARKETPLACE_ID) {
+    throw new Error(`Refusing marketplace path with invalid AGDF ownership marker: ${root}`);
+  }
+  if (marker.staging_state !== "ready" && !(allowBuilding && marker.staging_state === "building")) {
+    throw new Error(`Refusing marketplace path with invalid AGDF staging state: ${root}`);
+  }
+  return marker;
+}
+
+function removeOwnedRoot(root, parent, options = {}) {
+  if (!existsSync(root)) return;
+  if (!pathInside(parent, root) || dirname(root) !== parent) throw new Error(`Refusing unsafe marketplace cleanup path: ${root}`);
+  ownership(root, options);
+  rmSync(root, { recursive: true, force: true });
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function codexMarketplace() {
+  return {
+    name: MARKETPLACE_ID,
+    interface: { displayName: pluginDefinition.displayName },
+    plugins: [{
+      name: pluginDefinition.id,
+      source: { source: "local", path: "./plugins/agdf" },
+      policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+      category: pluginDefinition.category,
+    }],
+  };
+}
+
+function claudeMarketplace() {
+  return {
+    name: MARKETPLACE_ID,
+    owner: { name: pluginDefinition.displayName, email: "" },
+    metadata: { description: pluginDefinition.description },
+    plugins: [{
+      name: pluginDefinition.id,
+      source: "./plugins/agdf",
+      description: pluginDefinition.claudeDescription,
+      category: pluginDefinition.category,
+    }],
+  };
+}
+
+function validateBuiltPlugin(pluginRoot, expectedVersion) {
+  const definition = readJson(join(pluginRoot, "meta", "agdf-plugin.definition.json"), "built plugin definition");
+  const runtime = readJson(join(pluginRoot, "runtime", "runtime-manifest.json"), "built runtime manifest");
+  for (const required of [
+    join(pluginRoot, ".codex-plugin", "plugin.json"),
+    join(pluginRoot, ".claude-plugin", "plugin.json"),
+    join(pluginRoot, "runtime", "agdf-local.js"),
+    join(pluginRoot, "scripts", "check-runtime-integrity.mjs"),
+  ]) {
+    if (!existsSync(required)) throw new Error(`Built plugin is incomplete: ${required}`);
+  }
+  if (definition.version !== expectedVersion || runtime.version !== expectedVersion) {
+    throw new Error(`Built plugin version mismatch: expected ${expectedVersion}, definition ${definition.version}, runtime ${runtime.version}`);
+  }
+  if (!/^[a-f0-9]{64}$/.test(runtime.digest ?? "")) throw new Error("Built plugin runtime digest is invalid.");
+  if (digestDirectory(join(pluginRoot, "runtime", "create-agdf")) !== runtime.digest) {
+    throw new Error("Built plugin runtime digest does not match its payload.");
+  }
+}
+
+function validateMarketplaceRoot(root) {
+  const codex = readJson(join(root, ".agents", "plugins", "marketplace.json"), "Codex local marketplace manifest");
+  const claude = readJson(join(root, ".claude-plugin", "marketplace.json"), "Claude local marketplace manifest");
+  if (JSON.stringify(codex) !== JSON.stringify(codexMarketplace())) {
+    throw new Error(`Codex local marketplace manifest is not owned by ${MARKETPLACE_ID}: ${root}`);
+  }
+  if (JSON.stringify(claude) !== JSON.stringify(claudeMarketplace())) {
+    throw new Error(`Claude local marketplace manifest is not owned by ${MARKETPLACE_ID}: ${root}`);
+  }
+}
+
+function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot) {
+  const parent = dirname(stableRoot);
+  if (existsSync(backupRoot)) {
+    ownership(backupRoot);
+    if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
+    if (existsSync(stableRoot)) {
+      ownership(stableRoot);
+      renameSync(stableRoot, failedRoot);
+    }
+    renameSync(backupRoot, stableRoot);
+    if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
+  }
+  if (existsSync(stageRoot)) removeOwnedRoot(stageRoot, parent, { allowBuilding: true });
+  if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
+}
+
+export function prepareLocalMarketplace({
+  dataRoot = defaultAgdfDataRoot(),
+  builtPluginRoot = join(generatedRoot, "plugins", "agdf"),
+  expectedVersion = pluginDefinition.version,
+} = {}) {
+  dataRoot = resolve(dataRoot);
+  builtPluginRoot = resolve(builtPluginRoot);
+  const stableRoot = join(dataRoot, "marketplaces", MARKETPLACE_ID);
+  const parent = dirname(stableRoot);
+  const stageRoot = `${stableRoot}.stage`;
+  const backupRoot = `${stableRoot}.backup`;
+  const failedRoot = `${stableRoot}.failed`;
+  if (!pathInside(dataRoot, stableRoot) || dirname(stableRoot) !== parent) throw new Error(`Unsafe AGDF marketplace root: ${stableRoot}`);
+  validateBuiltPlugin(builtPluginRoot, expectedVersion);
+  mkdirSync(parent, { recursive: true });
+  recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot);
+
+  const existing = existsSync(stableRoot) ? ownership(stableRoot) : null;
+  if (existing) {
+    const existingPluginRoot = join(stableRoot, "plugins", MARKETPLACE_ID);
+    validateBuiltPlugin(existingPluginRoot, existing.version);
+    validateMarketplaceRoot(stableRoot);
+    if (digestDirectory(existingPluginRoot) !== existing.plugin_digest) {
+      throw new Error(`Refusing tampered AGDF marketplace root: ${stableRoot}`);
+    }
+  }
+  mkdirSync(stageRoot, { recursive: false });
+  try {
+    writeJson(join(stageRoot, OWNERSHIP_FILE), {
+      schema_version: 1,
+      owner: "create-agdf",
+      marketplace_id: MARKETPLACE_ID,
+      version: expectedVersion,
+      plugin_digest: null,
+      source_package_version: readJson(join(packageRoot, "package.json"), "create-agdf package manifest").version,
+      staging_state: "building",
+    });
+    const stagedPluginRoot = join(stageRoot, "plugins", MARKETPLACE_ID);
+    cpSync(builtPluginRoot, stagedPluginRoot, { recursive: true });
+    validateBuiltPlugin(stagedPluginRoot, expectedVersion);
+    writeJson(join(stageRoot, ".agents", "plugins", "marketplace.json"), codexMarketplace());
+    writeJson(join(stageRoot, ".claude-plugin", "marketplace.json"), claudeMarketplace());
+    validateMarketplaceRoot(stageRoot);
+    const pluginDigest = digestDirectory(stagedPluginRoot);
+    const marker = {
+      schema_version: 1,
+      owner: "create-agdf",
+      marketplace_id: MARKETPLACE_ID,
+      version: expectedVersion,
+      plugin_digest: pluginDigest,
+      source_package_version: readJson(join(packageRoot, "package.json"), "create-agdf package manifest").version,
+      staging_state: "ready",
+    };
+    writeJson(join(stageRoot, OWNERSHIP_FILE), marker);
+
+    if (existing?.version === expectedVersion && existing?.plugin_digest === pluginDigest) {
+      removeOwnedRoot(stageRoot, parent);
+      return Object.freeze({
+        root: stableRoot,
+        pluginRoot: join(stableRoot, "plugins", MARKETPLACE_ID),
+        version: expectedVersion,
+        digest: pluginDigest,
+        changed: false,
+        commit() {},
+        rollback() {},
+      });
+    }
+
+    if (existsSync(stableRoot)) renameSync(stableRoot, backupRoot);
+    try {
+      renameSync(stageRoot, stableRoot);
+    } catch (error) {
+      if (existsSync(backupRoot) && !existsSync(stableRoot)) renameSync(backupRoot, stableRoot);
+      throw error;
+    }
+    let closed = false;
+    return Object.freeze({
+      root: stableRoot,
+      pluginRoot: join(stableRoot, "plugins", MARKETPLACE_ID),
+      version: expectedVersion,
+      digest: pluginDigest,
+      changed: true,
+      commit() {
+        if (closed) return;
+        if (existsSync(backupRoot)) removeOwnedRoot(backupRoot, parent);
+        closed = true;
+      },
+      rollback() {
+        if (closed) return;
+        if (existsSync(backupRoot)) {
+          if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
+          if (existsSync(stableRoot)) renameSync(stableRoot, failedRoot);
+          renameSync(backupRoot, stableRoot);
+          if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
+        } else if (existsSync(stableRoot)) {
+          removeOwnedRoot(stableRoot, parent);
+        }
+        closed = true;
+      },
+    });
+  } catch (error) {
+    if (existsSync(stageRoot)) removeOwnedRoot(stageRoot, parent, { allowBuilding: true });
+    throw error;
+  }
+}
+
+function normalizedLegacySource(value) {
+  if (typeof value !== "string") return "";
+  return value.trim().toLowerCase()
+    .replace(/^git\+/, "")
+    .replace(/^https?:\/\/github\.com\//, "")
+    .replace(/^github:/, "")
+    .replace(/\.git$/, "")
+    .replace(/\/$/, "");
+}
+
+function sourceForEntry(entry) {
+  const source = entry?.marketplaceSource?.source
+    ?? entry?.source?.source
+    ?? (entry?.source === "directory" ? entry?.path : undefined)
+    ?? (entry?.source === "github" ? entry?.repo : undefined)
+    ?? entry?.repo
+    ?? entry?.path
+    ?? entry?.source
+    ?? entry?.url
+    ?? "";
+  return typeof source === "string" ? source : "";
+}
+
+export function classifyMarketplaceList(surface, output, stableRoot) {
+  let parsed;
+  try {
+    parsed = typeof output === "string" ? JSON.parse(output) : output;
+  } catch {
+    return { state: "unknown", source: "", reason: "invalid_json" };
+  }
+  const entries = surface === "codex" ? parsed?.marketplaces : parsed;
+  if (!Array.isArray(entries)) return { state: "unknown", source: "", reason: "invalid_shape" };
+  const matches = entries.filter((entry) => entry?.name === MARKETPLACE_ID);
+  if (matches.length === 0) return { state: "absent", source: "" };
+  if (matches.length !== 1) return { state: "unknown", source: "", reason: "duplicate_name" };
+  const entry = matches[0];
+  const source = sourceForEntry(entry);
+  const sourceType = entry?.marketplaceSource?.sourceType ?? entry?.source?.sourceType ?? "";
+  if ((sourceType === "local" || isAbsolute(source)) && resolve(source) === resolve(stableRoot)) {
+    return { state: "owned_local_current", source };
+  }
+  if (normalizedLegacySource(source) === LEGACY_REPOSITORY) return { state: "legacy_github", source };
+  return { state: "conflict", source, reason: source ? "foreign_source" : "source_missing" };
+}
+
+export const localMarketplaceConstants = Object.freeze({
+  id: MARKETPLACE_ID,
+  ownershipFile: OWNERSHIP_FILE,
+  legacyRepository: LEGACY_REPOSITORY,
+});

package/lib/installers/opencode.js

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 import process from "node:process";
 import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { evaluateOpenCodeRepositoryActivation } from "./opencode-activation.js";
+import { resolveLocalValidator } from "../runtime/local-validator.js";
 
 const contractModules = ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"];
 const openCodeSkillNames = pluginDefinition.skillSet.map((skill) => pluginDefinition.opencode.skillPrefix + skill.slug);
@@ -12,6 +13,7 @@ const globalOpenCodeSkillNames = pluginDefinition.skillSet.map((skill) => plugin
 const globalOpenCodeSkillOwnershipMarker = "<!-- AGDF-GLOBAL-SKILL: ";
 const globalOpenCodeInstructionsOwnershipMarker = "<!-- AGDF-GLOBAL-INSTRUCTIONS -->";
 const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->";
+const globalOpenCodeValidatorOwnershipMarker = "// AGDF-GLOBAL-LOCAL-VALIDATOR";
 const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
 const npmCommand = testNpmCliPath ? process.execPath : process.platform === "win32" ? process.execPath : "npm";
 const npmPrefixArgs = testNpmCliPath ? [testNpmCliPath] : process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
@@ -119,6 +121,7 @@ function globalOpenCodeConfigPaths(configDir) {
     runtimeContract: join(configDir, pluginDefinition.opencode.runtimeContractFileName),
     contracts: join(configDir, "contracts"),
     skills: join(configDir, "skills"),
+    localValidator: join(configDir, "agdf", "bin", "agdf-local.js"),
   };
 }
 
@@ -141,6 +144,7 @@ function assertGlobalOpenCodeSurfaceWritable(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   assertGlobalOpenCodeFileWritable(paths.instructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
   assertGlobalOpenCodeFileWritable(paths.runtimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  assertGlobalOpenCodeFileWritable(paths.localValidator, globalOpenCodeValidatorOwnershipMarker, "first-line");
   for (const moduleName of contractModules) {
     assertGlobalOpenCodeFileWritable(
       join(paths.contracts, moduleName),
@@ -177,6 +181,16 @@ function globalOpenCodeBoundary() {
   ].join("\n");
 }
 
+function globalOpenCodeActivationGuard() {
+  return [
+    "## Repository Activation Guard",
+    "",
+    "Apply AGDF governance only when this repository has valid `.agdf/control/config.json` durable control.",
+    "If it is missing or invalid, stop and direct the user to `npx --yes @agdf/cli@latest opencode-repo`; the global installation alone is not activation.",
+    "",
+  ].join("\n");
+}
+
 function toGlobalOpenCodeContent(content) {
   let next = content;
   for (const skill of pluginDefinition.skillSet) {
@@ -204,9 +218,11 @@ export function installOpenCodeGlobalSurface(configDir) {
     toGlobalOpenCodeContent(generatedInstructions),
   ].join("\n");
   const globalRuntimeContract = `${globalOpenCodeRuntimeContractOwnershipMarker}\n${generatedRuntimeContract}`;
+  const localValidator = `${globalOpenCodeValidatorOwnershipMarker}\nimport process from "node:process";\nimport { fileURLToPath } from "node:url";\nimport { runLocalValidator } from "../../node_modules/create-agdf/lib/runtime/local-validator.js";\n\nconst ownedPackageRoot = fileURLToPath(new URL("../../node_modules/create-agdf", import.meta.url));\nprocess.exitCode = runLocalValidator({ ownedPackageRoot, expectedVersion: ${JSON.stringify(pluginDefinition.version)}, surface: "opencode" }, process.argv.slice(2));\n`;
 
   writeOwnedGlobalOpenCodeFile(paths.instructions, globalInstructions, globalOpenCodeInstructionsOwnershipMarker, "first-line");
   writeOwnedGlobalOpenCodeFile(paths.runtimeContract, globalRuntimeContract, globalOpenCodeRuntimeContractOwnershipMarker, "first-line");
+  writeOwnedGlobalOpenCodeFile(paths.localValidator, localValidator, globalOpenCodeValidatorOwnershipMarker, "first-line");
   for (const moduleName of contractModules) {
     const generatedModule = readFileSync(join(generatedOpenCodeRoot, "contracts", moduleName), "utf8");
     writeOwnedGlobalOpenCodeFile(
@@ -223,7 +239,7 @@ export function installOpenCodeGlobalSurface(configDir) {
     const sourcePath = join(generatedOpenCodeRoot, "skills", sourceName, "SKILL.md");
     const sourceContent = readFileSync(sourcePath, "utf8");
     const marker = `${globalOpenCodeSkillOwnershipMarker}${skillName} -->`;
-    const content = toGlobalOpenCodeContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n${globalOpenCodeBoundary()}`);
+    const content = toGlobalOpenCodeContent(sourceContent).replace(/^(---[\s\S]*?\n---\n)/, `$1${marker}\n\n${globalOpenCodeActivationGuard()}`);
     writeOwnedGlobalOpenCodeFile(join(paths.skills, skillName, "SKILL.md"), content, marker, "after-frontmatter");
   }
 
@@ -232,6 +248,7 @@ export function installOpenCodeGlobalSurface(configDir) {
     runtimeContract: paths.runtimeContract,
     contracts: paths.contracts,
     skills: paths.skills,
+    localValidator: paths.localValidator,
   };
 }
 
@@ -309,6 +326,12 @@ function evaluateGlobalOpenCodeSurface(configDir) {
   const paths = globalOpenCodeConfigPaths(configDir);
   const skillCount = globalOpenCodeSkillNames.filter((skillName) => existsSync(join(paths.skills, skillName, "SKILL.md"))).length;
   const contractCount = contractModules.filter((moduleName) => existsSync(join(paths.contracts, moduleName))).length;
+  const validatorResolution = resolveLocalValidator({
+    ownedPackageRoot: join(configDir, "node_modules", pluginDefinition.opencode.npmPackage),
+    runtimeRoot: join(configDir, "agdf"),
+    expectedVersion: pluginDefinition.version,
+    surface: "opencode",
+  });
   return {
     path: paths.skills,
     instructions: paths.instructions,
@@ -318,11 +341,18 @@ function evaluateGlobalOpenCodeSurface(configDir) {
     skill_count: skillCount,
     expected_contract_count: contractModules.length,
     contract_count: contractCount,
+    local_validator: {
+      path: paths.localValidator,
+      present: existsSync(paths.localValidator),
+      ...validatorResolution.envelope,
+    },
     present: existsSync(paths.skills),
     complete: existsSync(paths.instructions)
       && existsSync(paths.runtimeContract)
       && contractCount === contractModules.length
-      && skillCount === openCodeSkillNames.length,
+      && skillCount === openCodeSkillNames.length
+      && existsSync(paths.localValidator)
+      && validatorResolution.envelope.machine_validation === "owned_version_matched",
   };
 }
 

package/lib/installers/plugin-installers.js

@@ -1,41 +1,117 @@
 import { execFileSync } from "node:child_process";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import { classifyMarketplaceList, prepareLocalMarketplace } from "./local-marketplace.js";
 
-export function installCodexGlobalPlugin({ exec = execFileSync, io = console } = {}) {
+export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "marketplace", "upgrade", "agdf"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], "plugin_operation", captureOptions()));
-  const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
-  if (installedVersion !== expectedVersion) {
-    throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "codex plugin marketplace upgrade agdf && codex plugin add agdf --marketplace agdf"));
+  const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "codex", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ surface: "codex", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
+    nativeOutput.push(runPluginPhase(exec, "codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], "plugin_operation", captureOptions()));
+    const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", captureOptions());
+    const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
+    if (installedVersion !== expectedVersion) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest codex"));
+    }
+    transaction.commit();
+    return {
+      surface: "codex", operation: migration.state === "owned_local_current" ? "update" : "install", expectedVersion, installedVersion, verificationStatus: "healthy",
+      evidence: ["durable_local_marketplace", `marketplace:${migration.state}`, "codex plugin list"],
+      nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    recoverMarketplace({ surface: "codex", exec, migration, transaction, error });
+    throw error;
   }
-  return { surface: "codex", expectedVersion, installedVersion, verificationStatus: "healthy", evidence: ["codex plugin list"], nativeOutput: nativeOutput.filter(Boolean).map(String) };
 }
 
-export function installClaudeGlobalPlugin({ exec = execFileSync, io = console } = {}) {
+export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", captureOptions()));
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", captureOptions()));
-  const beforeList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
-  nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", alreadyInstalled ? "update" : "install", "agdf@agdf"], "plugin_operation", captureOptions()));
-  const afterList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
-  const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
-  if (installedVersion && installedVersion !== expectedVersion) {
-    throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "claude plugin marketplace update agdf && claude plugin update agdf@agdf"));
+  const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
+  const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  try {
+    const marketplaceOutput = runPluginPhase(exec, "claude", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
+    migrateMarketplace({ surface: "claude", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", captureOptions()));
+    const beforeList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", captureOptions());
+    const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
+    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", alreadyInstalled ? "update" : "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+    const afterList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", captureOptions());
+    const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
+    if (installedVersion && installedVersion !== expectedVersion) {
+      throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest claude"));
+    }
+    transaction.commit();
+    return {
+      surface: "claude",
+      operation: migration.state === "owned_local_current" ? "update" : "install",
+      expectedVersion,
+      installedVersion,
+      verificationStatus: installedVersion ? "healthy" : "degraded",
+      evidence: ["durable_local_marketplace", `marketplace:${migration.state}`, "claude plugin list", ...(installedVersion ? [] : ["host_did_not_expose_version"])],
+      nativeOutput: nativeOutput.filter(Boolean).map(String),
+    };
+  } catch (error) {
+    recoverMarketplace({ surface: "claude", exec, migration, transaction, error });
+    throw error;
+  }
+}
+
+function migrateMarketplace({ surface, exec, output, root, nativeOutput, migration }) {
+  const classification = classifyMarketplaceList(surface, output, root);
+  Object.assign(migration, classification);
+  if (["conflict", "unknown"].includes(classification.state)) {
+    throw lifecycleAdapterError("marketplace", `Refusing to replace non-AGDF marketplace registration agdf (${classification.reason || classification.state}).`, classification);
   }
-  return {
-    surface: "claude",
-    expectedVersion,
-    installedVersion,
-    verificationStatus: installedVersion ? "healthy" : "degraded",
-    evidence: ["claude plugin list", ...(installedVersion ? [] : ["host_did_not_expose_version"])],
-    nativeOutput: nativeOutput.filter(Boolean).map(String),
+  const executable = surface === "claude" ? "claude" : "codex";
+  if (classification.state === "legacy_github") {
+    const args = surface === "claude"
+      ? ["plugin", "marketplace", "remove", "agdf", "--scope", "user"]
+      : ["plugin", "marketplace", "remove", "agdf", "--json"];
+    nativeOutput.push(runPluginPhase(exec, executable, args, "marketplace", captureOptions()));
+    migration.removedLegacy = true;
+  }
+  if (["absent", "legacy_github"].includes(classification.state)) {
+    const args = surface === "claude"
+      ? ["plugin", "marketplace", "add", root, "--scope", "user"]
+      : ["plugin", "marketplace", "add", root, "--json"];
+    nativeOutput.push(runPluginPhase(exec, executable, args, "marketplace", captureOptions()));
+    migration.addedLocal = true;
+  }
+}
+
+function recoverMarketplace({ surface, exec, migration, transaction, error }) {
+  const executable = surface === "claude" ? "claude" : "codex";
+  const recovery = [];
+  const attempt = (args) => {
+    try {
+      exec(executable, args, captureOptions());
+      recovery.push({ args, status: "restored" });
+    } catch (rollbackError) {
+      recovery.push({ args, status: "failed", message: commandErrorText(rollbackError) });
+    }
   };
+  if (migration?.addedLocal) {
+    attempt(surface === "claude"
+      ? ["plugin", "marketplace", "remove", "agdf", "--scope", "user"]
+      : ["plugin", "marketplace", "remove", "agdf", "--json"]);
+  }
+  if (migration?.removedLegacy && migration.source) {
+    attempt(surface === "claude"
+      ? ["plugin", "marketplace", "add", migration.source, "--scope", "user"]
+      : ["plugin", "marketplace", "add", migration.source, "--json"]);
+  }
+  try {
+    transaction.rollback();
+    recovery.push({ filesystem: transaction.root, status: "restored" });
+  } catch (rollbackError) {
+    recovery.push({ filesystem: transaction.root, status: "failed", message: rollbackError.message });
+  }
+  error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
 }
 
 function captureOptions() {