create-agdf 0.14.2 → 0.14.4

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}`);

package/lib/installers/plugin-installers.js

@@ -4,10 +4,22 @@ import { join, resolve } from "node:path";
 import process from "node:process";
 import { pluginDefinition } from "../cli/runtime-context.js";
 import { digestNormalizedPluginSource } from "../runtime/plugin-provenance.js";
+import { recoverClaudeCacheTemp } from "./claude-cache-recovery.js";
 import { CODEX_REGISTRATION_REVISION, classifyMarketplaceList, inspectLocalMarketplaceProjection, inspectOwnedSharedMarketplaceForCopilotMigration, isCodexLocalInstallVersion, prepareCopilotMarketplace, prepareLocalMarketplace } from "./local-marketplace.js";
 
 export const COPILOT_CLI_NPM_PACKAGE = "@github/copilot@1.0.80";
 
+function historicalEvidenceEntries(transaction) {
+  const historical = transaction.historicalEvidence;
+  if (!historical) return [];
+  return [
+    `historical_release:${historical.releaseVersion}`,
+    `historical_contract:${historical.contractId}`,
+    `historical_contract_digest:${historical.contractDigest}`,
+    `historical_entry_digest:${historical.entryDigest}`,
+  ];
+}
+
 export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
@@ -34,12 +46,15 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
+        ...(transaction.existingClassification === "owned_supported_historical_rebuild" ? ["marketplace_recovery:owned_supported_historical_rebuild", "loaded_session:fresh_session_required"] : []),
+        ...historicalEvidenceEntries(transaction),
         ...(expectedInstallVersion === expectedVersion ? [] : [`canonical_version:${expectedVersion}`, `local_install_version:${expectedInstallVersion}`]),
       ],
       pluginRoot: transaction.pluginRoot ?? null,
       digest: transaction.digest ?? null,
       runtimeDigest: transaction.runtimeDigest ?? null,
       sourceDigest: transaction.sourceDigest ?? null,
+      historicalEvidence: transaction.historicalEvidence ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
@@ -48,11 +63,19 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
   }
 }
 
-export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepareLocalMarketplace, dataRoot } = {}) {
+export function installClaudeGlobalPlugin({
+  exec = execFileSync,
+  prepare = prepareLocalMarketplace,
+  dataRoot,
+  recoverCache = recoverClaudeCacheTemp,
+  cacheRecoveryOptions = {},
+} = {}) {
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
   const transaction = prepare({ expectedVersion, ...(dataRoot ? { dataRoot } : {}) });
   const migration = { state: "unknown", source: "", addedLocal: false, removedLegacy: false };
+  let previousPluginRemoved = false;
+  let pluginInstalled = false;
   try {
     const marketplaceOutput = runPluginPhase(exec, "claude", ["plugin", "marketplace", "list", "--json"], "marketplace", captureOptions());
     migrateMarketplace({ surface: "claude", exec, output: marketplaceOutput, root: transaction.root, nativeOutput, migration });
@@ -63,11 +86,41 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
     // same-version local source change never reaches the host; reinstall replaces the content.
     if (alreadyInstalled) {
       nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "uninstall", "agdf@agdf"], "plugin_operation", captureOptions()));
+      previousPluginRemoved = true;
+    }
+    let cacheRecovery = null;
+    try {
+      nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+      pluginInstalled = true;
+    } catch (installError) {
+      cacheRecovery = recoverCache({
+        error: installError,
+        expectedVersion,
+        ...cacheRecoveryOptions,
+      });
+      if (cacheRecovery.status !== "recovered") {
+        installError.evidence = {
+          ...(installError.evidence ?? {}),
+          claude_cache_recovery: cacheRecovery.reason,
+        };
+        throw installError;
+      }
+      try {
+        nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "install", "agdf@agdf"], "plugin_operation", captureOptions()));
+        pluginInstalled = true;
+      } catch (retryError) {
+        retryError.evidence = {
+          ...(retryError.evidence ?? {}),
+          claude_cache_recovery: "claude_cache_temp_retry_exhausted",
+        };
+        throw retryError;
+      }
     }
-    nativeOutput.push(runPluginPhase(exec, "claude", ["plugin", "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) {
+    const historicalRebuild = transaction.existingClassification === "owned_supported_historical_rebuild";
+    if ((historicalRebuild && installedVersion !== expectedVersion)
+        || (installedVersion && installedVersion !== expectedVersion)) {
       throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "npx --yes @agdf/cli@latest claude"));
     }
     transaction.commit();
@@ -85,16 +138,20 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
         ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
+        ...(transaction.existingClassification === "owned_supported_historical_rebuild" ? ["marketplace_recovery:owned_supported_historical_rebuild", "loaded_session:fresh_session_required"] : []),
+        ...historicalEvidenceEntries(transaction),
+        ...(cacheRecovery?.status === "recovered" ? ["claude_cache_temp_recovery:bounded_retry"] : []),
         ...(installedVersion ? [] : ["host_did_not_expose_version"]),
       ],
       pluginRoot: transaction.pluginRoot ?? null,
       digest: transaction.digest ?? null,
       runtimeDigest: transaction.runtimeDigest ?? null,
       sourceDigest: transaction.sourceDigest ?? null,
+      historicalEvidence: transaction.historicalEvidence ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
-    recoverMarketplace({ surface: "claude", exec, migration, transaction, error });
+    recoverMarketplace({ surface: "claude", exec, migration, transaction, error, previousPluginRemoved, pluginInstalled });
     throw error;
   }
 }
@@ -118,7 +175,7 @@ export function installCopilotGlobalPlugin({ exec = execFileSync, packagedCopilo
   try {
     before = activeExec("copilot", ["plugin", "list"], captureOptions());
   } catch (error) {
-    if (error?.code !== "ENOENT") {
+    if (!copilotCliUnavailable(error)) {
       transaction?.rollback();
       throw lifecycleAdapterError("verification", commandErrorText(error), { executable: "copilot", args: ["plugin", "list"] });
     }
@@ -126,7 +183,10 @@ export function installCopilotGlobalPlugin({ exec = execFileSync, packagedCopilo
     activeExec = (_executable, args, options) => packagedCopilotExec(invocation.executable, [...invocation.args, ...args], options);
     try {
       before = activeExec("copilot", ["plugin", "list"], captureOptions());
-      bootstrapEvidence.push("copilot_cli_not_found", `copilot_cli_npm_package:${COPILOT_CLI_NPM_PACKAGE}`);
+      bootstrapEvidence.push(
+        error?.code === "ENOENT" ? "copilot_cli_not_found" : "copilot_cli_launcher_unavailable",
+        `copilot_cli_npm_package:${COPILOT_CLI_NPM_PACKAGE}`,
+      );
     } catch (bootstrapError) {
       transaction?.commit();
       return {
@@ -302,7 +362,15 @@ function migrateMarketplace({ surface, exec, output, root, nativeOutput, migrati
   }
 }
 
-function recoverMarketplace({ surface, exec, migration, transaction, error }) {
+function recoverMarketplace({
+  surface,
+  exec,
+  migration,
+  transaction,
+  error,
+  previousPluginRemoved = false,
+  pluginInstalled = false,
+}) {
   const executable = surface === "claude" ? "claude" : "codex";
   const recovery = [];
   const attempt = (args) => {
@@ -316,13 +384,19 @@ function recoverMarketplace({ surface, exec, migration, transaction, error }) {
     }
   };
   if (migration?.refreshOwnedLocal) {
+    if (surface === "claude" && pluginInstalled) {
+      attempt(["plugin", "uninstall", "agdf@agdf"]);
+    }
     const refreshedRegistrationRemoved = migration.addedLocal
       ? attempt(["plugin", "marketplace", "remove", "agdf", "--json"])
       : true;
-    rollbackMarketplaceFilesystem(transaction, recovery);
+    const filesystemRestored = rollbackMarketplaceFilesystem(transaction, recovery);
     if (migration.removedOwnedLocal && refreshedRegistrationRemoved) {
       attempt(["plugin", "marketplace", "add", migration.source || transaction.root, "--json"]);
     }
+    if (surface === "claude" && previousPluginRemoved && filesystemRestored) {
+      attempt(["plugin", "install", "agdf@agdf"]);
+    }
     error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
     return;
   }
@@ -336,7 +410,13 @@ function recoverMarketplace({ surface, exec, migration, transaction, error }) {
       ? ["plugin", "marketplace", "add", migration.source, "--scope", "user"]
       : ["plugin", "marketplace", "add", migration.source, "--json"]);
   }
-  rollbackMarketplaceFilesystem(transaction, recovery);
+  if (surface === "claude" && pluginInstalled) {
+    attempt(["plugin", "uninstall", "agdf@agdf"]);
+  }
+  const filesystemRestored = rollbackMarketplaceFilesystem(transaction, recovery);
+  if (surface === "claude" && previousPluginRemoved && filesystemRestored) {
+    attempt(["plugin", "install", "agdf@agdf"]);
+  }
   error.evidence = { ...(error.evidence ?? {}), rollback: recovery };
 }
 
@@ -344,8 +424,10 @@ function rollbackMarketplaceFilesystem(transaction, recovery) {
   try {
     transaction.rollback();
     recovery.push({ filesystem: transaction.root, status: "restored" });
+    return true;
   } catch (rollbackError) {
     recovery.push({ filesystem: transaction.root, status: "failed", message: rollbackError.message });
+    return false;
   }
 }
 
@@ -404,6 +486,11 @@ function commandErrorText(error) {
   return (error.stderr || error.stdout || error.message || "").toString().trim();
 }
 
+function copilotCliUnavailable(error) {
+  return error?.code === "ENOENT"
+    || /^Cannot find GitHub Copilot CLI(?:\s|$|\()/i.test(commandErrorText(error));
+}
+
 export function pluginListHasPlugin(output, pluginId) {
   const escapedPluginId = pluginId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   return output

package/lib/interaction-presentation.js

@@ -1,3 +1,5 @@
+import { RUN_ID_PATTERN } from "./control-state/run-identity.js";
+
 const REQUIRED_GATES = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
 const ARTEFACT_ORDER = ["UR", "PRD", "SD", "TP"];
 const OUTCOMES = new Set(["approve", "revise", "decline", "cancel", "no_response", "timeout", "empty", "invalid", "stale"]);
@@ -313,17 +315,37 @@ function operationalBreadcrumb(value, labels) {
     .join(labels.breadcrumbSeparator);
 }
 
+export function validateOperationalStatusCardPreconditions(statusCard, {
+  registry,
+  humanPresentation,
+} = {}) {
+  const errors = [];
+  if (!plainObject(statusCard)) errors.push("status_card_missing");
+  if (humanPresentation !== undefined && !plainObject(humanPresentation)) errors.push("human_presentation_missing");
+  if (plainObject(statusCard)) {
+    if (!String(statusCard.run_id ?? "").trim()) errors.push("run_id_missing");
+    if (!String(statusCard.current_gate ?? "").trim()) errors.push("current_gate_missing");
+    let locale = "";
+    try {
+      locale = resolvePresentationLocale(registry, statusCard.presentation_language);
+    } catch {
+      locale = "";
+    }
+    if (!locale) errors.push("locale_unresolved");
+  }
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
 export function renderOperationalStatusCard(statusCard, {
   registry,
   humanPresentation,
   revisionId = "",
 } = {}) {
-  if (!plainObject(statusCard) || !plainObject(humanPresentation)) return null;
+  if (!validateOperationalStatusCardPreconditions(statusCard, { registry, humanPresentation: humanPresentation ?? null }).valid) return null;
   const runId = String(statusCard.run_id ?? "").trim();
   const currentGate = String(statusCard.current_gate ?? "").trim();
   const revision = String(revisionId ?? "").trim() || "unversioned";
   const locale = resolvePresentationLocale(registry, statusCard.presentation_language);
-  if (!runId || !currentGate || !locale) return null;
 
   const pack = localePack(registry, locale);
   const labels = pack.statusCard;
@@ -537,6 +559,37 @@ export function normalizeInteractionOutcome(value, { expectedApproval, stale = f
   return "invalid";
 }
 
+export function validateApprovalOrientationPreconditions({
+  statusCard,
+  humanPresentation,
+  registry,
+  requestedLocale,
+} = {}) {
+  const errors = [];
+  if (!plainObject(statusCard)) return Object.freeze({ valid: false, errors: Object.freeze(["status_card_missing"]) });
+  if (humanPresentation !== undefined && !plainObject(humanPresentation)) errors.push("human_presentation_missing");
+  const gate = String(statusCard.current_gate ?? "").trim();
+  const runId = String(statusCard.run_id ?? "").trim();
+  if (!REQUIRED_GATES.includes(gate)) errors.push("gate_not_user_gate");
+  if (!RUN_ID_PATTERN.test(runId)) errors.push("run_id_invalid");
+  if (statusCard.status !== "open") errors.push("status_not_open");
+  if (statusCard.missing_approval !== `Approval: ${gate}`) errors.push("missing_approval_mismatch");
+  const nextGate = String(statusCard.next_gate_after_approval ?? "none");
+  const nextUserGate = String(statusCard.next_user_gate ?? "").trim();
+  const userActionRequired = String(statusCard.user_action_required ?? "").trim();
+  const userActionSemanticsValid = (userActionRequired === "no" && nextUserGate === "none")
+    || (userActionRequired === "yes" && REQUIRED_GATES.includes(nextUserGate) && nextGate === nextUserGate);
+  if (!userActionSemanticsValid) errors.push("user_action_semantics_invalid");
+  let locale = "";
+  try {
+    locale = resolvePresentationLocale(registry, requestedLocale);
+  } catch {
+    locale = "";
+  }
+  if (!locale) errors.push("locale_unresolved");
+  return Object.freeze({ valid: errors.length === 0, errors: Object.freeze(errors) });
+}
+
 export function buildApprovalOrientationSnapshot({
   ready = false,
   statusCard,
@@ -545,11 +598,11 @@ export function buildApprovalOrientationSnapshot({
   registry,
   requestedLocale,
 } = {}) {
-  if (!ready || !plainObject(statusCard) || !plainObject(humanPresentation)) return null;
+  if (!ready) return null;
+  if (!validateApprovalOrientationPreconditions({ statusCard, humanPresentation: humanPresentation ?? null, registry, requestedLocale }).valid) return null;
   const gate = String(statusCard.current_gate ?? "").trim();
   const runId = String(statusCard.run_id ?? "").trim();
   const expectedApproval = `Approval: ${gate}`;
-  if (!REQUIRED_GATES.includes(gate) || !/^[A-Za-z0-9._-]+$/.test(runId) || statusCard.status !== "open" || statusCard.missing_approval !== expectedApproval) return null;
 
   const locale = resolvePresentationLocale(registry, requestedLocale);
   const pack = localePack(registry, locale);
@@ -560,9 +613,6 @@ export function buildApprovalOrientationSnapshot({
   const nextGate = String(statusCard.next_gate_after_approval ?? "none");
   const nextUserGate = String(statusCard.next_user_gate ?? "").trim();
   const userActionRequired = String(statusCard.user_action_required ?? "").trim();
-  const userActionSemanticsValid = (userActionRequired === "no" && nextUserGate === "none")
-    || (userActionRequired === "yes" && REQUIRED_GATES.includes(nextUserGate) && nextGate === nextUserGate);
-  if (!userActionSemanticsValid) return null;
   const narration = pack.primary.narration.gates[gate] ?? {};
   const nextDecision = userActionRequired === "no"
     ? pack.primary.narration.noAction