create-agdf 0.13.5 → 0.13.6

package/lib/cli/application.js

@@ -35,7 +35,7 @@ import { CliUsageError, parseArgs } from "./parse-args.js";
 import { pluginDefinition } from "./runtime-context.js";
 import { createValidationHandlers } from "./validation-handlers.js";
 
-function createHandlers({ io, env, exec, prepare }) {
+function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
   const installerAdapters = {
     ...(exec ? { exec } : {}),
     ...(prepare ? { prepare } : {}),
@@ -112,7 +112,7 @@ function createHandlers({ io, env, exec, prepare }) {
     ["opencode", (options) => {
       const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
       try {
-        const result = runLifecyclePhase("plugin_operation", () => installOpenCodeGlobalPlugin(configDir));
+        const result = runLifecyclePhase("plugin_operation", () => installOpenCodeGlobalPlugin(configDir, { packageSource: openCodePackageSource }));
         runLifecyclePhase("global_surface", () => installOpenCodeGlobalSurface(configDir));
         const report = runLifecyclePhase("verification", () => evaluateOpenCodeStatus(options.dir, configDir, result.transition));
         const alignmentHealthy = ["already_matching", "aligned"].includes(result.sdk_alignment.status);
@@ -150,6 +150,7 @@ function createHandlers({ io, env, exec, prepare }) {
               `experimental_hooks=${report.experimental_hooks.aggregate}`,
               `host_sdk_version=${report.host_sdk_version.status};policy=${report.host_sdk_version.policy}`,
               `sdk_alignment=${result.sdk_alignment.status};target=${result.sdk_alignment.target_version || "unknown"};installed=${result.sdk_alignment.installed_version || "unknown"}`,
+              `package_source=${result.package_source.kind}${result.package_source.digest ? `;digest=${result.package_source.digest}` : ""}`,
             ],
           },
           restart: { required: true, reason: "host_reload" },
@@ -341,7 +342,7 @@ export async function runCli(argv = process.argv.slice(2), adapters = {}) {
   }
   const command = resolveCommand(options.target);
   if (!command) throw new Error(`No handler is registered for ${options.target}.`);
-  const handler = createHandlers({ io, env, exec: adapters.exec, prepare: adapters.prepare }).get(command.handler);
+  const handler = createHandlers({ io, env, exec: adapters.exec, prepare: adapters.prepare, openCodePackageSource: adapters.openCodePackageSource }).get(command.handler);
   if (!handler) throw new Error(`No implementation is registered for ${command.name}.`);
   return await handler(options);
 }

package/lib/fs-swap.js

@@ -0,0 +1,26 @@
+import { renameSync } from "node:fs";
+import process from "node:process";
+
+const RETRY_ATTEMPTS = 5;
+const RETRY_BASE_DELAY_MS = 50;
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+export function renameSyncWithRetry(source, destination, adapters = {}) {
+  const rename = adapters.rename ?? renameSync;
+  const sleep = adapters.sleep ?? sleepSync;
+  const platform = adapters.platform ?? process.platform;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      rename(source, destination);
+      return;
+    } catch (error) {
+      // Windows antivirus/indexer handle locks surface as transient EPERM on
+      // renames of freshly written directory trees; retry briefly before failing.
+      if (platform !== "win32" || error?.code !== "EPERM" || attempt >= RETRY_ATTEMPTS) throw error;
+      sleep(RETRY_BASE_DELAY_MS * attempt);
+    }
+  }
+}

package/lib/installers/local-development.js

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve, win32 as pathWin32 } from "node:path";
+import process from "node:process";
+
+const LOCAL_PACKAGE_OWNER = "create-agdf";
+const LOCAL_PACKAGE_KIND = "opencode_local_development_package";
+const OWNERSHIP_FILE = ".agdf-owned.json";
+
+function sha256File(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function pathInside(root, candidate) {
+  const relativePath = candidate.slice(root.length);
+  return candidate === root || (candidate.startsWith(root) && ["/", "\\"].includes(relativePath[0]));
+}
+
+function readJson(path, label) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is invalid: ${error.message}`);
+  }
+}
+
+function parsePackResult(output) {
+  const start = String(output).indexOf("[");
+  if (start < 0) throw new Error("AGDF local package build did not return npm pack JSON.");
+  const parsed = JSON.parse(String(output).slice(start));
+  const result = parsed?.[0];
+  const filename = result?.filename;
+  if (typeof filename !== "string" || !filename || filename.includes("/") || filename.includes("\\")) {
+    throw new Error("AGDF local package build returned an unsafe tarball name.");
+  }
+  if (!Array.isArray(result.files) || result.files.length === 0) {
+    throw new Error("AGDF local package build did not report its packed file inventory.");
+  }
+  return { filename, files: result.files };
+}
+
+export function localNpmExecutable(platform = process.platform, execPath = process.execPath) {
+  if (platform !== "win32") return { executable: "npm", prefix: [] };
+  return {
+    executable: execPath,
+    prefix: [pathWin32.join(pathWin32.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js")],
+  };
+}
+
+function digestPackedFiles(packageRoot, files) {
+  const root = resolve(packageRoot);
+  const paths = files.map((entry) => {
+    if (!entry
+        || typeof entry.path !== "string"
+        || !entry.path
+        || entry.path.includes("\\")
+        || !Number.isInteger(entry.mode)) {
+      throw new Error("AGDF local package build returned an invalid packed file path.");
+    }
+    const path = resolve(root, entry.path);
+    if (!pathInside(root, path) || path === root) throw new Error(`AGDF local package build returned an unsafe packed file path: ${entry.path}`);
+    const stats = lstatSync(path);
+    if (!stats.isFile() || stats.isSymbolicLink()) throw new Error(`AGDF local package build returned a non-file package entry: ${entry.path}`);
+    return { path, relative: entry.path.replaceAll("\\", "/"), mode: entry.mode };
+  }).sort((left, right) => left.relative.localeCompare(right.relative));
+  const hash = createHash("sha256");
+  for (const entry of paths) {
+    hash.update(entry.relative);
+    hash.update("\0");
+    hash.update(String(entry.mode));
+    hash.update("\0");
+    hash.update(readFileSync(entry.path));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function validateOwnedPackageDirectory(root, expected = {}) {
+  const rootStats = lstatSync(root);
+  if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) throw new Error(`Refusing unsafe AGDF local package directory: ${root}`);
+  const marker = readJson(join(root, OWNERSHIP_FILE), "AGDF local package ownership marker");
+  if (marker.schema_version !== 1
+      || marker.owner !== LOCAL_PACKAGE_OWNER
+      || marker.kind !== LOCAL_PACKAGE_KIND
+      || !/^[a-f0-9]{64}$/.test(marker.digest ?? "")
+      || !/^[a-f0-9]{64}$/.test(marker.archive_digest ?? "")
+      || typeof marker.filename !== "string"
+      || !marker.filename) {
+    throw new Error(`Refusing unowned AGDF local package directory: ${root}`);
+  }
+  if (expected.version && marker.version !== expected.version) throw new Error(`AGDF local package version mismatch: ${root}`);
+  if (expected.digest && marker.digest !== expected.digest) throw new Error(`AGDF local package digest mismatch: ${root}`);
+  const tarball = join(root, marker.filename);
+  if (!existsSync(tarball)
+      || !lstatSync(tarball).isFile()
+      || lstatSync(tarball).isSymbolicLink()
+      || sha256File(tarball) !== marker.archive_digest) {
+    throw new Error(`AGDF local package tarball is missing or tampered: ${root}`);
+  }
+  return { marker, tarball };
+}
+
+export function validateLocalOpenCodePackageSource(source) {
+  if (!source
+      || source.kind !== "local_checkout"
+      || typeof source.root !== "string"
+      || typeof source.dataRoot !== "string"
+      || !/^[a-f0-9]{64}$/.test(source.digest ?? "")) {
+    throw new Error("Invalid AGDF OpenCode local package source.");
+  }
+  const root = resolve(source.root);
+  const dataRoot = resolve(source.dataRoot);
+  const expectedRoot = join(dataRoot, "packages", "local", source.digest);
+  if (root !== expectedRoot) throw new Error("AGDF OpenCode local package source is outside its owned data root.");
+  const { marker, tarball } = validateOwnedPackageDirectory(root, {
+    version: source.version,
+    digest: source.digest,
+  });
+  const specifier = tarball;
+  if (source.specifier && source.specifier !== specifier) throw new Error("AGDF OpenCode local package specifier does not match its owned tarball.");
+  return Object.freeze({
+    kind: "local_checkout",
+    dataRoot,
+    root,
+    markerPath: join(root, OWNERSHIP_FILE),
+    tarball,
+    specifier,
+    version: marker.version,
+    digest: marker.digest,
+    archiveDigest: marker.archive_digest,
+  });
+}
+
+export function prepareLocalOpenCodePackage({
+  dataRoot,
+  packageRoot,
+  expectedVersion,
+  exec = execFileSync,
+} = {}) {
+  if (!dataRoot || !packageRoot || !expectedVersion) throw new Error("AGDF local package preparation requires dataRoot, packageRoot and expectedVersion.");
+  const localRoot = resolve(dataRoot, "packages", "local");
+  mkdirSync(localRoot, { recursive: true });
+  const stageRoot = mkdtempSync(join(localRoot, ".stage-"));
+  try {
+    const npm = localNpmExecutable();
+    const output = exec(npm.executable, [
+      ...npm.prefix,
+      "pack",
+      "--ignore-scripts",
+      "--json",
+      "--pack-destination",
+      stageRoot,
+    ], {
+      cwd: resolve(packageRoot),
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    const { filename, files } = parsePackResult(output);
+    const stagedTarball = join(stageRoot, filename);
+    if (!existsSync(stagedTarball) || !statSync(stagedTarball).isFile()) throw new Error("AGDF local package tarball was not created.");
+    const digest = digestPackedFiles(packageRoot, files);
+    const archiveDigest = sha256File(stagedTarball);
+    const stableRoot = join(localRoot, digest);
+    if (existsSync(stableRoot)) {
+      const existing = validateLocalOpenCodePackageSource({ kind: "local_checkout", dataRoot, root: stableRoot, version: expectedVersion, digest });
+      if (existing.archiveDigest !== archiveDigest) throw new Error(`AGDF local package archive is not deterministic for packed content: ${stableRoot}`);
+      rmSync(stageRoot, { recursive: true, force: true });
+      return existing;
+    }
+    writeFileSync(join(stageRoot, OWNERSHIP_FILE), `${JSON.stringify({
+      schema_version: 1,
+      owner: LOCAL_PACKAGE_OWNER,
+      kind: LOCAL_PACKAGE_KIND,
+      version: expectedVersion,
+      digest,
+      archive_digest: archiveDigest,
+      filename,
+    }, null, 2)}\n`, "utf8");
+    renameSync(stageRoot, stableRoot);
+    return validateLocalOpenCodePackageSource({ kind: "local_checkout", dataRoot, root: stableRoot, version: expectedVersion, digest });
+  } catch (error) {
+    if (existsSync(stageRoot)) rmSync(stageRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export const localDevelopmentConstants = Object.freeze({
+  owner: LOCAL_PACKAGE_OWNER,
+  kind: LOCAL_PACKAGE_KIND,
+  ownershipFile: OWNERSHIP_FILE,
+});

package/lib/installers/local-marketplace.js

@@ -1,48 +1,55 @@
-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";
+import { renameSyncWithRetry } from "../fs-swap.js";
+import {
+  INSTALLATION_PROVENANCE_FILE,
+  LEGACY_LOCAL_INSTALL_FILE,
+  digestDirectory,
+  digestNormalizedPluginSource,
+  inspectInstallationProvenance,
+  validateDistributionProfiles,
+} from "../runtime/plugin-provenance.js";
 
 const MARKETPLACE_ID = "agdf";
 const OWNERSHIP_FILE = ".agdf-owned.json";
 const LEGACY_REPOSITORY = "arndtgold/ai-native-governance-delivery-framework";
+export const CODEX_REGISTRATION_REVISION = 1;
 
 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");
+export function digestPluginSource(root, canonicalVersion = pluginDefinition.version) {
+  return digestNormalizedPluginSource(root, canonicalVersion);
+}
+
+export { digestDirectory };
+
+function semverBase(version) {
+  return version.split("+")[0];
+}
+
+export function codexLocalInstallVersion(version, sourceDigest) {
+  if (!/^[a-f0-9]{64}$/.test(sourceDigest)) throw new Error("AGDF local source digest must be a deterministic SHA-256 value.");
+  return `${semverBase(version)}+codex.local-${sourceDigest.slice(0, 12)}`;
+}
+
+export function isCodexLocalInstallVersion(version, candidate, sourceDigest = "") {
+  if (typeof candidate !== "string") return false;
+  if (sourceDigest) return candidate === codexLocalInstallVersion(version, sourceDigest);
+  const escaped = semverBase(version).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}\\+codex\\.local-[a-f0-9]{12}$`).test(candidate);
 }
 
 function readJson(path, label) {
@@ -93,7 +100,7 @@ function writeJson(path, value) {
 function codexMarketplace(definition = pluginDefinition) {
   return {
     name: MARKETPLACE_ID,
-    interface: { displayName: definition.displayName },
+    interface: { displayName: definition.publicDistribution.publicDisplayName },
     plugins: [{
       name: definition.id,
       source: { source: "local", path: "./plugins/agdf" },
@@ -103,6 +110,13 @@ function codexMarketplace(definition = pluginDefinition) {
   };
 }
 
+function legacyCodexMarketplace(definition = pluginDefinition) {
+  return {
+    ...codexMarketplace(definition),
+    interface: { displayName: definition.displayName },
+  };
+}
+
 function claudeMarketplace(definition = pluginDefinition) {
   return {
     name: MARKETPLACE_ID,
@@ -117,9 +131,14 @@ function claudeMarketplace(definition = pluginDefinition) {
   };
 }
 
-function validateBuiltPlugin(pluginRoot, expectedVersion) {
+function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVersion = expectedVersion, sourceDigest = "", {
+  requireInstallationProvenance = false,
+  allowLegacyProvenanceForMigration = false,
+} = {}) {
   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");
+  const codex = readJson(join(pluginRoot, ".codex-plugin", "plugin.json"), "built Codex plugin manifest");
+  const claude = readJson(join(pluginRoot, ".claude-plugin", "plugin.json"), "built Claude plugin manifest");
   for (const required of [
     join(pluginRoot, ".codex-plugin", "plugin.json"),
     join(pluginRoot, ".claude-plugin", "plugin.json"),
@@ -131,22 +150,66 @@ function validateBuiltPlugin(pluginRoot, expectedVersion) {
   if (definition.version !== expectedVersion || runtime.version !== expectedVersion) {
     throw new Error(`Built plugin version mismatch: expected ${expectedVersion}, definition ${definition.version}, runtime ${runtime.version}`);
   }
+  let provenance = null;
+  if (validateDistributionProfiles(definition).status !== "matched"
+      && requireInstallationProvenance
+      && allowLegacyProvenanceForMigration) {
+    provenance = inspectInstallationProvenance(pluginRoot, {
+      definition,
+      runtimeManifest: runtime,
+      pluginVersion: expectedCodexInstallVersion,
+      allowLegacy: true,
+    });
+  }
+  if (validateDistributionProfiles(definition).status !== "matched" && provenance?.status !== "legacy") {
+    throw new Error("Built plugin distribution profile contract is invalid.");
+  }
+  if (codex.version !== expectedCodexInstallVersion) {
+    throw new Error(`Built Codex plugin version mismatch: expected ${expectedCodexInstallVersion}, observed ${codex.version}`);
+  }
+  if (claude.version !== expectedVersion) {
+    throw new Error(`Built Claude plugin version mismatch: expected ${expectedVersion}, observed ${claude.version}`);
+  }
+  if (expectedCodexInstallVersion !== expectedVersion) {
+    if (!isCodexLocalInstallVersion(expectedVersion, expectedCodexInstallVersion, sourceDigest)) {
+      throw new Error(`Invalid AGDF Codex local install version: ${expectedCodexInstallVersion}`);
+    }
+  }
   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.");
   }
+  if (requireInstallationProvenance) {
+    provenance ??= inspectInstallationProvenance(pluginRoot, {
+      definition,
+      runtimeManifest: runtime,
+      pluginVersion: expectedCodexInstallVersion,
+      allowLegacy: allowLegacyProvenanceForMigration,
+    });
+    if (provenance.status !== "matched"
+        && !(allowLegacyProvenanceForMigration && provenance.status === "legacy")) {
+      throw new Error(`Invalid AGDF installation provenance (${provenance.reason}): ${pluginRoot}`);
+    }
+  }
   return definition;
 }
 
 function validateMarketplaceRoot(root, definition = pluginDefinition) {
   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(definition))) {
+  const serializedCodex = JSON.stringify(codex);
+  const codexShape = serializedCodex === JSON.stringify(codexMarketplace(definition))
+    ? "current"
+    : serializedCodex === JSON.stringify(legacyCodexMarketplace(definition))
+      ? "legacy_full_product_label"
+      : "invalid";
+  if (codexShape === "invalid") {
     throw new Error(`Codex local marketplace manifest is not owned by ${MARKETPLACE_ID}: ${root}`);
   }
   if (JSON.stringify(claude) !== JSON.stringify(claudeMarketplace(definition))) {
     throw new Error(`Claude local marketplace manifest is not owned by ${MARKETPLACE_ID}: ${root}`);
   }
+  return Object.freeze({ codexShape });
 }
 
 function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot) {
@@ -156,9 +219,9 @@ function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failed
     if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
     if (existsSync(stableRoot)) {
       ownership(stableRoot);
-      renameSync(stableRoot, failedRoot);
+      renameSyncWithRetry(stableRoot, failedRoot);
     }
-    renameSync(backupRoot, stableRoot);
+    renameSyncWithRetry(backupRoot, stableRoot);
     if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
   }
   if (existsSync(stageRoot)) removeOwnedRoot(stageRoot, parent, { allowBuilding: true });
@@ -169,6 +232,8 @@ export function prepareLocalMarketplace({
   dataRoot = defaultAgdfDataRoot(),
   builtPluginRoot = join(generatedRoot, "plugins", "agdf"),
   expectedVersion = pluginDefinition.version,
+  codexInstallVersion = expectedVersion,
+  codexRegistrationRevision = null,
 } = {}) {
   dataRoot = resolve(dataRoot);
   builtPluginRoot = resolve(builtPluginRoot);
@@ -178,15 +243,31 @@ export function prepareLocalMarketplace({
   const backupRoot = `${stableRoot}.backup`;
   const failedRoot = `${stableRoot}.failed`;
   if (!pathInside(dataRoot, stableRoot) || dirname(stableRoot) !== parent) throw new Error(`Unsafe AGDF marketplace root: ${stableRoot}`);
+  const sourceDigest = digestPluginSource(builtPluginRoot, expectedVersion);
+  if (codexInstallVersion !== expectedVersion
+      && !isCodexLocalInstallVersion(expectedVersion, codexInstallVersion, sourceDigest)) {
+    throw new Error(`Invalid AGDF Codex local install version: ${codexInstallVersion}`);
+  }
   const targetDefinition = validateBuiltPlugin(builtPluginRoot, expectedVersion);
   mkdirSync(parent, { recursive: true });
   recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot);
 
   const existing = existsSync(stableRoot) ? ownership(stableRoot) : null;
+  const targetCodexRegistrationRevision = codexRegistrationRevision
+    ?? existing?.codex_registration_revision
+    ?? 0;
+  let existingMarketplace = null;
   if (existing) {
     const existingPluginRoot = join(stableRoot, "plugins", MARKETPLACE_ID);
-    const existingDefinition = validateBuiltPlugin(existingPluginRoot, existing.version);
-    validateMarketplaceRoot(stableRoot, existingDefinition);
+    const existingCodexInstallVersion = existing.codex_install_version ?? existing.version;
+    const existingDefinition = validateBuiltPlugin(
+      existingPluginRoot,
+      existing.version,
+      existingCodexInstallVersion,
+      existing.source_digest ?? "",
+      { requireInstallationProvenance: true, allowLegacyProvenanceForMigration: true },
+    );
+    existingMarketplace = validateMarketplaceRoot(stableRoot, existingDefinition);
     if (digestDirectory(existingPluginRoot) !== existing.plugin_digest) {
       throw new Error(`Refusing tampered AGDF marketplace root: ${stableRoot}`);
     }
@@ -197,7 +278,10 @@ export function prepareLocalMarketplace({
       schema_version: 1,
       owner: "create-agdf",
       marketplace_id: MARKETPLACE_ID,
+      codex_registration_revision: targetCodexRegistrationRevision,
       version: expectedVersion,
+      codex_install_version: codexInstallVersion,
+      source_digest: sourceDigest,
       plugin_digest: null,
       source_package_version: readJson(join(packageRoot, "package.json"), "create-agdf package manifest").version,
       staging_state: "building",
@@ -205,6 +289,25 @@ export function prepareLocalMarketplace({
     const stagedPluginRoot = join(stageRoot, "plugins", MARKETPLACE_ID);
     cpSync(builtPluginRoot, stagedPluginRoot, { recursive: true });
     validateBuiltPlugin(stagedPluginRoot, expectedVersion);
+    if (codexInstallVersion !== expectedVersion) {
+      const codexManifestPath = join(stagedPluginRoot, ".codex-plugin", "plugin.json");
+      writeJson(codexManifestPath, { ...readJson(codexManifestPath, "built Codex plugin manifest"), version: codexInstallVersion });
+    }
+    const runtimeManifest = readJson(join(stagedPluginRoot, "runtime", "runtime-manifest.json"), "built runtime manifest");
+    writeJson(join(stagedPluginRoot, INSTALLATION_PROVENANCE_FILE), {
+      schema_version: 1,
+      owner: "create-agdf",
+      profile_id: "runtime-plugin",
+      marketplace_id: MARKETPLACE_ID,
+      canonical_version: expectedVersion,
+      codex_install_version: codexInstallVersion,
+      source_digest: sourceDigest,
+      runtime_digest: runtimeManifest.digest,
+    });
+    if (existsSync(join(stagedPluginRoot, LEGACY_LOCAL_INSTALL_FILE))) {
+      rmSync(join(stagedPluginRoot, LEGACY_LOCAL_INSTALL_FILE));
+    }
+    validateBuiltPlugin(stagedPluginRoot, expectedVersion, codexInstallVersion, sourceDigest, { requireInstallationProvenance: true });
     writeJson(join(stageRoot, ".agents", "plugins", "marketplace.json"), codexMarketplace(targetDefinition));
     writeJson(join(stageRoot, ".claude-plugin", "marketplace.json"), claudeMarketplace(targetDefinition));
     validateMarketplaceRoot(stageRoot, targetDefinition);
@@ -213,19 +316,27 @@ export function prepareLocalMarketplace({
       schema_version: 1,
       owner: "create-agdf",
       marketplace_id: MARKETPLACE_ID,
+      codex_registration_revision: targetCodexRegistrationRevision,
       version: expectedVersion,
+      codex_install_version: codexInstallVersion,
+      source_digest: sourceDigest,
       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) {
+    if (existing?.version === expectedVersion
+        && existing?.plugin_digest === pluginDigest
+        && existing?.codex_registration_revision === targetCodexRegistrationRevision
+        && existingMarketplace?.codexShape === "current") {
       removeOwnedRoot(stageRoot, parent);
       return Object.freeze({
         root: stableRoot,
         pluginRoot: join(stableRoot, "plugins", MARKETPLACE_ID),
         version: expectedVersion,
+        codexInstallVersion,
+        sourceDigest,
         digest: pluginDigest,
         changed: false,
         commit() {},
@@ -233,11 +344,11 @@ export function prepareLocalMarketplace({
       });
     }
 
-    if (existsSync(stableRoot)) renameSync(stableRoot, backupRoot);
+    if (existsSync(stableRoot)) renameSyncWithRetry(stableRoot, backupRoot);
     try {
-      renameSync(stageRoot, stableRoot);
+      renameSyncWithRetry(stageRoot, stableRoot);
     } catch (error) {
-      if (existsSync(backupRoot) && !existsSync(stableRoot)) renameSync(backupRoot, stableRoot);
+      if (existsSync(backupRoot) && !existsSync(stableRoot)) renameSyncWithRetry(backupRoot, stableRoot);
       throw error;
     }
     let closed = false;
@@ -245,6 +356,8 @@ export function prepareLocalMarketplace({
       root: stableRoot,
       pluginRoot: join(stableRoot, "plugins", MARKETPLACE_ID),
       version: expectedVersion,
+      codexInstallVersion,
+      sourceDigest,
       digest: pluginDigest,
       changed: true,
       commit() {
@@ -256,8 +369,8 @@ export function prepareLocalMarketplace({
         if (closed) return;
         if (existsSync(backupRoot)) {
           if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
-          if (existsSync(stableRoot)) renameSync(stableRoot, failedRoot);
-          renameSync(backupRoot, stableRoot);
+          if (existsSync(stableRoot)) renameSyncWithRetry(stableRoot, failedRoot);
+          renameSyncWithRetry(backupRoot, stableRoot);
           if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
         } else if (existsSync(stableRoot)) {
           removeOwnedRoot(stableRoot, parent);
@@ -271,6 +384,36 @@ export function prepareLocalMarketplace({
   }
 }
 
+export function inspectLocalMarketplaceProjection({
+  dataRoot = defaultAgdfDataRoot(),
+  expectedVersion = pluginDefinition.version,
+} = {}) {
+  const root = join(resolve(dataRoot), "marketplaces", MARKETPLACE_ID);
+  if (!existsSync(root)) return null;
+  const marker = ownership(root);
+  const codexInstallVersion = marker.codex_install_version ?? marker.version;
+  const pluginRoot = join(root, "plugins", MARKETPLACE_ID);
+  const definition = validateBuiltPlugin(
+    pluginRoot,
+    marker.version,
+    codexInstallVersion,
+    marker.source_digest ?? "",
+    { requireInstallationProvenance: true },
+  );
+  validateMarketplaceRoot(root, definition);
+  if (marker.version !== expectedVersion || digestDirectory(pluginRoot) !== marker.plugin_digest) {
+    throw new Error(`Refusing stale or tampered AGDF marketplace projection: ${root}`);
+  }
+  return Object.freeze({
+    root,
+    pluginRoot,
+    version: marker.version,
+    codexInstallVersion,
+    sourceDigest: marker.source_digest ?? "",
+    digest: marker.plugin_digest,
+  });
+}
+
 function normalizedLegacySource(value) {
   if (typeof value !== "string") return "";
   return value.trim().toLowerCase()
@@ -319,5 +462,7 @@ export function classifyMarketplaceList(surface, output, stableRoot) {
 export const localMarketplaceConstants = Object.freeze({
   id: MARKETPLACE_ID,
   ownershipFile: OWNERSHIP_FILE,
+  installationProvenanceFile: INSTALLATION_PROVENANCE_FILE,
+  legacyLocalInstallFile: LEGACY_LOCAL_INSTALL_FILE,
   legacyRepository: LEGACY_REPOSITORY,
 });