create-agdf 0.14.3 → 0.14.4

package/lib/installers/claude-cache-recovery.js

@@ -0,0 +1,76 @@
+import { existsSync, lstatSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { win32 } from "node:path";
+import process from "node:process";
+
+function result(status, reason, removedPath = null, evidence = []) {
+  return Object.freeze({ status, reason, removed_path: removedPath, evidence });
+}
+
+function normalized(path) {
+  return win32.resolve(path).toLowerCase();
+}
+
+function parseRenameOperands(text) {
+  const matches = [...text.matchAll(/\brename\s+['"]([^'"]+)['"]\s*->\s*['"]([^'"]+)['"]/gi)];
+  return matches.length === 1 ? matches[0].slice(1, 3) : null;
+}
+
+export function recoverClaudeCacheTemp({
+  error,
+  expectedVersion,
+  platform = process.platform,
+  env = process.env,
+  home = homedir(),
+  fs = { existsSync, lstatSync, realpathSync, rmSync },
+} = {}) {
+  const text = String(error?.message ?? error ?? "");
+  if (platform !== "win32" || !/\bEPERM\b/i.test(text) || !/\brename\b/i.test(text)) {
+    return result("not_applicable", "claude_cache_temp_recovery_not_applicable");
+  }
+  const operands = parseRenameOperands(text);
+  if (!operands || typeof expectedVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(expectedVersion)) {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  const configRoot = win32.resolve(env.CLAUDE_CONFIG_DIR || win32.join(home, ".claude"));
+  const namespace = win32.join(configRoot, "plugins", "cache", "agdf", "agdf");
+  const absoluteOperands = operands.filter((path) => win32.isAbsolute(path));
+  if (absoluteOperands.length !== 2
+      || absoluteOperands.some((path) => normalized(win32.dirname(path)) !== normalized(namespace))) {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  const [candidate, destination] = absoluteOperands;
+  if (!/^temp_local_[0-9A-Za-z._-]+$/.test(win32.basename(candidate))
+      || !fs.existsSync(candidate)) {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  if (win32.basename(destination) !== expectedVersion || fs.existsSync(destination)) {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  let candidateStats;
+  let realNamespace;
+  let realCandidate;
+  try {
+    candidateStats = fs.lstatSync(candidate);
+    realNamespace = fs.realpathSync(namespace);
+    realCandidate = fs.realpathSync(candidate);
+  } catch {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  if (!candidateStats.isDirectory() || candidateStats.isSymbolicLink()
+      || normalized(win32.dirname(realCandidate)) !== normalized(realNamespace)
+      || normalized(realCandidate) !== normalized(candidate)) {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  try {
+    fs.rmSync(candidate, { recursive: true, force: false });
+  } catch {
+    return result("unsafe", "claude_cache_temp_recovery_unsafe");
+  }
+  return result(
+    "recovered",
+    "claude_cache_temp_recovery_bounded_retry",
+    candidate,
+    [`cache_entry:${win32.basename(candidate)}`, `target_version:${expectedVersion}`],
+  );
+}

package/lib/installers/copilot-settings.js

@@ -1,49 +1,179 @@
+import { execFileSync } from "node:child_process";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import process from "node:process";
 import { renameSyncWithRetry } from "../fs-swap.js";
 
+const COPILOT_PLUGIN_SELECTOR = "agdf@agdf";
+const COPILOT_LOCAL_SETTINGS = join(".github", "copilot", "settings.local.json");
+const COPILOT_SHARED_SETTINGS = join(".github", "copilot", "settings.json");
+
 export function defaultCopilotSettingsPath({ env = process.env, home = homedir() } = {}) {
   return join(resolve(env.COPILOT_HOME || join(home, ".copilot")), "settings.json");
 }
 
 export function readCopilotSettings(path = defaultCopilotSettingsPath()) {
-  if (!existsSync(path)) return { exists: false, settings: {} };
+  if (!existsSync(path)) return { exists: false, settings: {}, content: null };
   const stats = lstatSync(path);
   if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("AGDF_COPILOT_SETTINGS_UNOWNED_PATH");
   try {
-    const settings = JSON.parse(readFileSync(path, "utf8"));
+    const content = readFileSync(path, "utf8");
+    const settings = JSON.parse(content);
     if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not an object");
     if (settings.enabledPlugins !== undefined
         && (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object" || Array.isArray(settings.enabledPlugins))) {
       throw new Error("enabledPlugins must be an object");
     }
-    return { exists: true, settings };
+    return { exists: true, settings, content };
   } catch (error) {
     throw new Error(`AGDF_COPILOT_SETTINGS_INVALID: ${error.message}`);
   }
 }
 
-function atomicSettingsWrite(path, settings) {
-  mkdirSync(dirname(path), { recursive: true });
+function atomicContentWrite(path, content, dependencies = {}) {
+  const makeDirectory = dependencies.mkdir ?? mkdirSync;
+  const write = dependencies.write ?? writeFileSync;
+  const rename = dependencies.rename ?? renameSyncWithRetry;
+  const remove = dependencies.remove ?? rmSync;
+  const changeMode = dependencies.chmod ?? chmodSync;
+  const exists = dependencies.exists ?? existsSync;
+  const stat = dependencies.lstat ?? lstatSync;
+  makeDirectory(dirname(path), { recursive: true });
   const temp = `${path}.agdf-tmp-${process.pid}`;
   const backup = `${path}.agdf-backup-${process.pid}`;
-  const hadPrevious = existsSync(path);
-  const mode = hadPrevious ? lstatSync(path).mode & 0o777 : 0o600;
-  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode });
-  if (process.platform !== "win32") chmodSync(temp, mode);
+  const hadPrevious = exists(path);
+  const mode = hadPrevious ? stat(path).mode & 0o777 : 0o600;
+  write(temp, content, { encoding: "utf8", flag: "wx", mode });
+  if (process.platform !== "win32") changeMode(temp, mode);
   try {
-    if (hadPrevious && process.platform === "win32") renameSyncWithRetry(path, backup);
-    renameSyncWithRetry(temp, path);
-    if (hadPrevious && process.platform === "win32") rmSync(backup, { force: true });
+    if (hadPrevious && process.platform === "win32") rename(path, backup);
+    rename(temp, path);
+    if (hadPrevious && process.platform === "win32") remove(backup, { force: true });
   } catch (error) {
-    try { rmSync(temp, { force: true }); } catch {}
-    if (hadPrevious && process.platform === "win32" && existsSync(backup) && !existsSync(path)) renameSyncWithRetry(backup, path);
+    try { remove(temp, { force: true }); } catch {}
+    if (hadPrevious && process.platform === "win32" && exists(backup) && !exists(path)) rename(backup, path);
     throw error;
   }
 }
 
+export function atomicSettingsWrite(path, settings, dependencies = {}) {
+  atomicContentWrite(path, `${JSON.stringify(settings, null, 2)}\n`, dependencies);
+}
+
+export function repositoryCopilotSettingsPath(targetDir, { shared = false } = {}) {
+  const root = resolve(targetDir);
+  if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) {
+    throw new Error(`AGDF_COPILOT_REPOSITORY_UNOWNED_PATH: ${root}`);
+  }
+  const path = resolve(root, shared ? COPILOT_SHARED_SETTINGS : COPILOT_LOCAL_SETTINGS);
+  const fromRoot = relative(root, path);
+  if (!fromRoot || fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
+    throw new Error("AGDF_COPILOT_REPOSITORY_SETTINGS_OUTSIDE_ROOT");
+  }
+  for (const candidate of [root, join(root, ".github"), join(root, ".github", "copilot")]) {
+    if (existsSync(candidate) && lstatSync(candidate).isSymbolicLink()) {
+      throw new Error(`AGDF_COPILOT_SETTINGS_UNOWNED_PATH: ${candidate}`);
+    }
+    if (existsSync(candidate) && !lstatSync(candidate).isDirectory()) {
+      throw new Error(`AGDF_COPILOT_SETTINGS_UNOWNED_PATH: ${candidate}`);
+    }
+  }
+  if (existsSync(path) && (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile())) {
+    throw new Error(`AGDF_COPILOT_SETTINGS_UNOWNED_PATH: ${path}`);
+  }
+  return path;
+}
+
+export function assertCopilotLocalSettingsIgnored(targetDir, { exec = execFileSync } = {}) {
+  const root = resolve(targetDir);
+  try {
+    exec("git", ["check-ignore", "--quiet", "--", COPILOT_LOCAL_SETTINGS], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("AGDF_COPILOT_GIT_UNAVAILABLE: install Git and retry personal disable, or use --shared deliberately.");
+    }
+    if (error?.status === 1) {
+      throw new Error(`AGDF_COPILOT_LOCAL_SETTINGS_NOT_IGNORED: add ${COPILOT_LOCAL_SETTINGS} to an effective Git ignore source and retry, or use --shared deliberately.`);
+    }
+    throw new Error(`AGDF_COPILOT_GIT_IGNORE_UNVERIFIED: ${error?.message || "Git could not verify the repository ignore state."}`);
+  }
+  return { status: "ignored", path: COPILOT_LOCAL_SETTINGS };
+}
+
+export function planCopilotRepositoryDisable({ targetDir, shared = false, exec = execFileSync }) {
+  const root = resolve(targetDir);
+  const path = repositoryCopilotSettingsPath(root, { shared });
+  if (!shared) assertCopilotLocalSettingsIgnored(root, { exec });
+  const before = readCopilotSettings(path);
+  const current = before.settings.enabledPlugins?.[COPILOT_PLUGIN_SELECTOR];
+  if (current !== undefined && typeof current !== "boolean") {
+    throw new Error(`AGDF_COPILOT_SETTINGS_AMBIGUOUS_PLUGIN_STATE: ${path}`);
+  }
+  const next = structuredClone(before.settings);
+  next.enabledPlugins = { ...(next.enabledPlugins ?? {}), [COPILOT_PLUGIN_SELECTOR]: false };
+  return Object.freeze({
+    path,
+    root,
+    shared,
+    audience: shared ? "shared" : "personal",
+    selector: COPILOT_PLUGIN_SELECTOR,
+    before: Object.freeze({ exists: before.exists, settings: structuredClone(before.settings), content: before.content }),
+    settings: Object.freeze(next),
+    changed: current !== false,
+  });
+}
+
+export function applyCopilotRepositoryDisable(mutation, dependencies = {}) {
+  if (!mutation?.path || mutation.selector !== COPILOT_PLUGIN_SELECTOR || mutation.settings?.enabledPlugins?.[COPILOT_PLUGIN_SELECTOR] !== false) {
+    throw new Error("AGDF_COPILOT_SETTINGS_MUTATION_INVALID");
+  }
+  const read = dependencies.read ?? readCopilotSettings;
+  const write = dependencies.writeSettings ?? ((path, settings) => atomicSettingsWrite(path, settings, dependencies));
+  const writeContent = dependencies.writeContent ?? ((path, content) => atomicContentWrite(path, content, dependencies));
+  const remove = dependencies.remove ?? rmSync;
+  const resolvedPath = repositoryCopilotSettingsPath(mutation.root, { shared: mutation.shared });
+  if (resolvedPath !== mutation.path) throw new Error("AGDF_COPILOT_SETTINGS_MUTATION_PATH_MISMATCH");
+  const current = read(mutation.path);
+  if (current.exists !== mutation.before.exists || (current.exists && current.content !== mutation.before.content)) {
+    throw new Error(`AGDF_COPILOT_SETTINGS_CHANGED_DURING_APPLY: ${mutation.path}`);
+  }
+  if (!mutation.changed) return { status: "unchanged", path: mutation.path };
+  try {
+    write(mutation.path, mutation.settings);
+    const verified = read(mutation.path);
+    if (verified.settings.enabledPlugins?.[COPILOT_PLUGIN_SELECTOR] !== false) {
+      throw new Error("AGDF_COPILOT_SETTINGS_VERIFICATION_FAILED");
+    }
+    return { status: "written", path: mutation.path };
+  } catch (error) {
+    try {
+      if (mutation.before.exists) writeContent(mutation.path, mutation.before.content);
+      else remove(mutation.path, { force: true });
+    } catch (rollbackError) {
+      error.rollbackError = rollbackError;
+    }
+    throw error;
+  }
+}
+
+export function verifyCopilotRepositoryDisabled(targetDir, { shared = false } = {}) {
+  try {
+    const path = repositoryCopilotSettingsPath(targetDir, { shared });
+    if (!existsSync(path)) return { status: "failed", evidence: [`missing:${path}`] };
+    const state = readCopilotSettings(path);
+    return state.settings.enabledPlugins?.[COPILOT_PLUGIN_SELECTOR] === false
+      ? { status: "healthy", evidence: [`${path}:${COPILOT_PLUGIN_SELECTOR}:enabled=false`, `audience:${shared ? "shared" : "personal"}`] }
+      : { status: "failed", evidence: [`postcondition_failed:${path}:${COPILOT_PLUGIN_SELECTOR}`] };
+  } catch (error) {
+    return { status: "failed", evidence: [`verification_failed:${resolve(targetDir)}:${error.message}`] };
+  }
+}
+
 export function configureCopilotDeclarativePlugin({ path = defaultCopilotSettingsPath(), pluginRoot }) {
   if (typeof pluginRoot !== "string" || !pluginRoot.trim() || !isAbsolute(pluginRoot)) {
     throw new Error("AGDF_COPILOT_PLUGIN_SPEC_INVALID");
@@ -64,7 +194,7 @@ export function configureCopilotDeclarativePlugin({ path = defaultCopilotSetting
     path,
     spec,
     rollback() {
-      if (before.exists) atomicSettingsWrite(path, before.settings);
+      if (before.exists) atomicContentWrite(path, before.content);
       else rmSync(path, { force: true });
     },
   };

package/lib/installers/local-marketplace.js

@@ -2,15 +2,17 @@ import {
   cpSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
 import process from "node:process";
 import { generatedRoot, packageRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { renameSyncWithRetry } from "../fs-swap.js";
+import { classifyHistoricalDistributionProfile } from "../runtime/distribution-profile-history.js";
 import {
   INSTALLATION_PROVENANCE_FILE,
   LEGACY_LOCAL_INSTALL_FILE,
@@ -31,6 +33,14 @@ function pathInside(root, candidate) {
   return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
 }
 
+function readOptionalJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
 export function digestPluginSource(root, canonicalVersion = pluginDefinition.version) {
   return digestNormalizedPluginSource(root, canonicalVersion);
 }
@@ -58,6 +68,59 @@ export function isCodexLocalInstallVersion(version, candidate, sourceDigest = ""
   return new RegExp(`^${escaped}\\+codex\\.local-[a-f0-9]{12}$`).test(candidate);
 }
 
+function localInstallSourceUnstable(detail) {
+  const error = new Error(`AGDF local plugin source changed during snapshot capture: ${detail}`);
+  error.code = "local_install_source_unstable";
+  return error;
+}
+
+export function captureLocalPluginSnapshot({
+  builtPluginRoot,
+  expectedVersion = pluginDefinition.version,
+  profileId = "runtime-plugin",
+  adapters = {},
+} = {}) {
+  if (!builtPluginRoot) throw new Error("AGDF local plugin source root is required.");
+  const sourceRoot = resolve(builtPluginRoot);
+  const digest = adapters.digest ?? digestPluginSource;
+  const createRoot = adapters.createRoot ?? (() => mkdtempSync(join(tmpdir(), "agdf-local-plugin-")));
+  const copy = adapters.copy ?? ((source, target) => cpSync(source, target, { recursive: true }));
+  const remove = adapters.remove ?? ((root) => rmSync(root, { recursive: true, force: true }));
+  const beforeDigest = digest(sourceRoot, expectedVersion);
+  let snapshotRoot = null;
+  try {
+    snapshotRoot = resolve(createRoot());
+    const pluginRoot = join(snapshotRoot, "agdf");
+    copy(sourceRoot, pluginRoot);
+    const snapshotDigest = digest(pluginRoot, expectedVersion);
+    const afterDigest = digest(sourceRoot, expectedVersion);
+    if (beforeDigest !== snapshotDigest || snapshotDigest !== afterDigest) {
+      throw localInstallSourceUnstable(
+        `before=${beforeDigest}, snapshot=${snapshotDigest}, after=${afterDigest}`,
+      );
+    }
+    const copilotProfile = profileId === "copilot-runtime-plugin";
+    return Object.freeze({
+      canonicalVersion: expectedVersion,
+      profileId,
+      pluginRoot,
+      sourceDigest: snapshotDigest,
+      codexInstallVersion: copilotProfile
+        ? expectedVersion
+        : codexLocalInstallVersion(expectedVersion, snapshotDigest),
+      cleanup() {
+        if (!snapshotRoot) return;
+        const ownedRoot = snapshotRoot;
+        remove(ownedRoot);
+        snapshotRoot = null;
+      },
+    });
+  } catch (error) {
+    if (snapshotRoot) remove(snapshotRoot);
+    throw error;
+  }
+}
+
 function readJson(path, label) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -160,6 +223,9 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
   requireInstallationProvenance = false,
   allowLegacyProvenanceForMigration = false,
   allowPreProvenanceShape = false,
+  allowHistoricalProfilesForMigration = false,
+  distributionProfileHistory = null,
+  classifyHistoricalProfile = classifyHistoricalDistributionProfile,
   profileId = "runtime-plugin",
 } = {}) {
   const definition = readJson(join(pluginRoot, "meta", "agdf-plugin.definition.json"), "built plugin definition");
@@ -193,10 +259,18 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
       runtimeManifest: runtime,
       pluginVersion: expectedCodexInstallVersion,
       allowLegacy: true,
+      allowHistoricalProfilesForMigration,
+      distributionProfileHistory,
+      classifyHistoricalProfile,
     });
   }
-  if (profile.status !== "matched" && provenance?.status !== "legacy" && !isPreProvenanceShape) {
-    throw new Error("Built plugin distribution profile contract is invalid.");
+  const supportedHistoricalProfile = provenance?.status === "matched"
+    && provenance.profileClassification === "supported_historical";
+  if (profile.status !== "matched"
+      && provenance?.status !== "legacy"
+      && !supportedHistoricalProfile
+      && !isPreProvenanceShape) {
+    throw new Error(`Built plugin distribution profile contract is invalid (${provenance?.reason ?? profile.reason}).`);
   }
   if (!copilotProfile && codex.version !== expectedCodexInstallVersion) {
     throw new Error(`Built Codex plugin version mismatch: expected ${expectedCodexInstallVersion}, observed ${codex.version}`);
@@ -226,6 +300,9 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
       runtimeManifest: runtime,
       pluginVersion: expectedCodexInstallVersion,
       allowLegacy: allowLegacyProvenanceForMigration,
+      allowHistoricalProfilesForMigration,
+      distributionProfileHistory,
+      classifyHistoricalProfile,
       profileId,
       inventoryDigest: copilotInventory?.inventoryDigest ?? null,
     });
@@ -234,7 +311,11 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
       throw new Error(`Invalid AGDF installation provenance (${provenance.reason}): ${pluginRoot}`);
     }
   }
-  return definition;
+  return {
+    definition,
+    provenance,
+    profileClassification: provenance?.profileClassification ?? "current",
+  };
 }
 
 function validateMarketplaceRoot(root, definition = pluginDefinition, { profileId = "runtime-plugin" } = {}) {
@@ -262,7 +343,10 @@ function validateMarketplaceRoot(root, definition = pluginDefinition, { profileI
   return Object.freeze({ codexShape });
 }
 
-function classifyExistingMarketplace(stableRoot, marker, { profileId = "runtime-plugin" } = {}) {
+function classifyExistingMarketplace(stableRoot, marker, {
+  profileId = "runtime-plugin",
+  distributionProfileHistory = null,
+} = {}) {
   const existingPluginRoot = join(stableRoot, "plugins", MARKETPLACE_ID);
   const copilotProfile = profileId === "copilot-runtime-plugin";
   const existingCodexInstallVersion = copilotProfile ? marker.version : marker.codex_install_version ?? marker.version;
@@ -279,15 +363,32 @@ function classifyExistingMarketplace(stableRoot, marker, { profileId = "runtime-
   const preProvenanceCandidate = !hasCurrentProvenance
     && !hasLegacyProvenance
     && !Object.hasOwn(definition, "distributionProfiles");
-  const existingDefinition = validateBuiltPlugin(
+  const existingValidation = validateBuiltPlugin(
     existingPluginRoot,
     marker.version,
     existingCodexInstallVersion,
     marker.source_digest ?? "",
     preProvenanceCandidate
       ? { allowPreProvenanceShape: true }
-      : { requireInstallationProvenance: true, allowLegacyProvenanceForMigration: true, profileId },
+      : {
+          requireInstallationProvenance: true,
+          allowLegacyProvenanceForMigration: true,
+          allowHistoricalProfilesForMigration: !copilotProfile,
+          distributionProfileHistory,
+          profileId,
+        },
   );
+  if (!preProvenanceCandidate) {
+    if (!/^[a-f0-9]{64}$/.test(marker.source_digest ?? "")) {
+      throw new Error(`Refusing invalid AGDF marketplace ownership source digest: ${stableRoot}`);
+    }
+    const observedSourceDigest = existingValidation.provenance?.observedSourceDigest
+      ?? digestPluginSource(existingPluginRoot, marker.version);
+    if (marker.source_digest !== observedSourceDigest) {
+      throw new Error(`Refusing AGDF marketplace ownership source digest mismatch: ${stableRoot}`);
+    }
+  }
+  const existingDefinition = existingValidation.definition;
   const marketplace = validateMarketplaceRoot(stableRoot, existingDefinition, { profileId });
   if (digestDirectory(existingPluginRoot) !== marker.plugin_digest) {
     throw new Error(`Refusing tampered AGDF marketplace root: ${stableRoot}`);
@@ -295,9 +396,19 @@ function classifyExistingMarketplace(stableRoot, marker, { profileId = "runtime-
   return Object.freeze({
     classification: preProvenanceCandidate
       ? "owned_pre_provenance_rebuild"
-      : "current_or_marker_migration",
+      : existingValidation.profileClassification === "supported_historical"
+        ? "owned_supported_historical_rebuild"
+        : "current_or_marker_migration",
     definition: existingDefinition,
     marketplace,
+    historicalEvidence: existingValidation.profileClassification === "supported_historical"
+      ? {
+          releaseVersion: existingValidation.provenance.historicalReleaseVersion,
+          contractId: existingValidation.provenance.historicalContractId,
+          contractDigest: existingValidation.provenance.historicalContractDigest,
+          entryDigest: existingValidation.provenance.historicalEntryDigest,
+        }
+      : null,
   });
 }
 
@@ -322,13 +433,15 @@ function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failed
   if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
 }
 
-export function prepareLocalMarketplace({
+function prepareLocalMarketplaceFromSource({
   dataRoot = defaultAgdfDataRoot(),
   builtPluginRoot,
   expectedVersion = pluginDefinition.version,
   codexInstallVersion = expectedVersion,
   codexRegistrationRevision = null,
   profileId = "runtime-plugin",
+  knownSourceDigest = "",
+  sourceStaged = () => {},
 } = {}) {
   dataRoot = resolve(dataRoot);
   const copilotProfile = profileId === "copilot-runtime-plugin";
@@ -342,12 +455,15 @@ 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);
+  const sourceDigest = knownSourceDigest || digestPluginSource(builtPluginRoot, expectedVersion);
   if (!copilotProfile && codexInstallVersion !== expectedVersion
       && !isCodexLocalInstallVersion(expectedVersion, codexInstallVersion, sourceDigest)) {
     throw new Error(`Invalid AGDF Codex local install version: ${codexInstallVersion}`);
   }
-  const targetDefinition = validateBuiltPlugin(builtPluginRoot, expectedVersion, expectedVersion, "", { profileId });
+  const targetDefinition = validateBuiltPlugin(builtPluginRoot, expectedVersion, expectedVersion, "", { profileId }).definition;
+  const distributionProfileHistory = readOptionalJson(
+    join(builtPluginRoot, "meta", "distribution-profile-history.json"),
+  );
   mkdirSync(parent, { recursive: true });
   recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot);
 
@@ -365,15 +481,17 @@ export function prepareLocalMarketplace({
     ?? 0;
   let existingMarketplace = null;
   let existingClassification = "none";
+  let historicalEvidence = null;
   if (existing) {
     let classified;
     try {
-      classified = classifyExistingMarketplace(stableRoot, existing, { profileId });
+      classified = classifyExistingMarketplace(stableRoot, existing, { profileId, distributionProfileHistory });
     } catch (error) {
       throw invalidExistingMarketplace(error);
     }
     existingClassification = classified.classification;
     existingMarketplace = classified.marketplace;
+    historicalEvidence = classified.historicalEvidence;
   }
   mkdirSync(stageRoot, { recursive: false });
   try {
@@ -392,6 +510,7 @@ export function prepareLocalMarketplace({
     });
     const stagedPluginRoot = join(stageRoot, "plugins", MARKETPLACE_ID);
     cpSync(builtPluginRoot, stagedPluginRoot, { recursive: true });
+    sourceStaged();
     validateBuiltPlugin(stagedPluginRoot, expectedVersion, expectedVersion, "", { profileId });
     if (!copilotProfile && codexInstallVersion !== expectedVersion) {
       const codexManifestPath = join(stagedPluginRoot, ".codex-plugin", "plugin.json");
@@ -450,6 +569,7 @@ export function prepareLocalMarketplace({
         digest: pluginDigest,
         runtimeDigest: runtimeManifest.digest,
         existingClassification,
+        historicalEvidence,
         changed: false,
         commit() {},
         rollback() {},
@@ -473,6 +593,7 @@ export function prepareLocalMarketplace({
       digest: pluginDigest,
       runtimeDigest: runtimeManifest.digest,
       existingClassification,
+      historicalEvidence,
       changed: true,
       commit() {
         if (closed) return;
@@ -498,8 +619,42 @@ export function prepareLocalMarketplace({
   }
 }
 
+export function prepareLocalMarketplace(options = {}) {
+  if (!options.snapshotSource) return prepareLocalMarketplaceFromSource(options);
+  if (Object.hasOwn(options, "codexInstallVersion")) {
+    throw new Error("AGDF snapshot preparation owns the Codex local install version.");
+  }
+  const snapshot = captureLocalPluginSnapshot({
+    builtPluginRoot: options.builtPluginRoot,
+    expectedVersion: options.expectedVersion,
+    profileId: options.profileId,
+    adapters: options.snapshotAdapters,
+  });
+  try {
+    const { snapshotSource: _snapshotSource, snapshotAdapters: _snapshotAdapters, ...stableOptions } = options;
+    return prepareLocalMarketplaceFromSource({
+      ...stableOptions,
+      builtPluginRoot: snapshot.pluginRoot,
+      expectedVersion: snapshot.canonicalVersion,
+      profileId: snapshot.profileId,
+      codexInstallVersion: snapshot.codexInstallVersion,
+      knownSourceDigest: snapshot.sourceDigest,
+      sourceStaged: snapshot.cleanup,
+    });
+  } finally {
+    snapshot.cleanup();
+  }
+}
+
 export function prepareCopilotMarketplace(options = {}) {
-  return prepareLocalMarketplace({ ...options, profileId: "copilot-runtime-plugin", codexInstallVersion: options.expectedVersion ?? pluginDefinition.version });
+  const { codexInstallVersion, ...copilotOptions } = options;
+  return prepareLocalMarketplace({
+    ...copilotOptions,
+    profileId: "copilot-runtime-plugin",
+    ...(!options.snapshotSource
+      ? { codexInstallVersion: codexInstallVersion ?? options.expectedVersion ?? pluginDefinition.version }
+      : {}),
+  });
 }
 
 export function inspectLocalMarketplaceProjection({
@@ -517,7 +672,7 @@ export function inspectLocalMarketplaceProjection({
     codexInstallVersion,
     marker.source_digest ?? "",
     { requireInstallationProvenance: true },
-  );
+  ).definition;
   validateMarketplaceRoot(root, definition);
   if (marker.version !== expectedVersion || digestDirectory(pluginRoot) !== marker.plugin_digest) {
     throw new Error(`Refusing stale or tampered AGDF marketplace projection: ${root}`);