chainlesschain 0.164.0 → 0.165.2

package/src/commands/plugin.js

@@ -4,6 +4,7 @@
  */
 
 import chalk from "chalk";
+import fs from "node:fs";
 import { logger } from "../lib/logger.js";
 import {
   enforcePluginPolicy,
@@ -27,6 +28,11 @@ import {
   removePluginSkills,
   getPluginSkills,
 } from "../harness/plugin-manager.js";
+import {
+  PLUGIN_MARKETPLACE_CANONICAL_PAYLOAD_SBOM_SCHEMA,
+  PLUGIN_MARKETPLACE_PAYLOAD_SBOM_SCHEMA,
+  isMarketplacePayloadSbomFormat,
+} from "../lib/plugin-runtime/marketplace-artifact-readback.js";
 
 function collectRepeatableOption(value, previous = []) {
   return [...previous, value];
@@ -37,6 +43,71 @@ function normalizeRegistryUrls(value) {
   return value ? [value] : [];
 }
 
+function normalizeRegistryDigestPins(value, registryUrls) {
+  const pins = new Map();
+  const allowed = new Set(registryUrls);
+  for (const raw of Array.isArray(value) ? value : value ? [value] : []) {
+    const separator = String(raw).lastIndexOf("=");
+    const url = separator > 0 ? String(raw).slice(0, separator) : "";
+    const digest = separator > 0 ? String(raw).slice(separator + 1) : "";
+    if (!allowed.has(url)) {
+      throw new Error(
+        `registry digest pin must name an exact requested registry URL: ${url || raw}`,
+      );
+    }
+    if (!/^[a-f0-9]{64}$/.test(digest)) {
+      throw new Error(
+        `registry digest pin for ${url} must be 64 lowercase hexadecimal characters`,
+      );
+    }
+    if (pins.has(url) && pins.get(url) !== digest) {
+      throw new Error(`conflicting registry digest pins for ${url}`);
+    }
+    pins.set(url, digest);
+  }
+  return pins;
+}
+
+function registryNetworkOptions(options = {}) {
+  return {
+    proxyUrl:
+      options.proxy || process.env.CC_PLUGIN_REGISTRY_PROXY || undefined,
+    pacFile:
+      options.pacFile || process.env.CC_PLUGIN_REGISTRY_PAC_FILE || undefined,
+    caFile:
+      options.caFile || process.env.CC_PLUGIN_REGISTRY_CA_FILE || undefined,
+  };
+}
+
+function assertOfflinePluginSourceLocal(source, ref = null) {
+  if (
+    ref ||
+    typeof source !== "string" ||
+    !fs.existsSync(source) ||
+    !fs.lstatSync(source).isDirectory()
+  ) {
+    throw new Error(
+      "offline install without --registry requires an existing local plugin directory; remote Git caching is available only for registry candidates with manifest and semantic payload anchors",
+    );
+  }
+}
+
+function readBoundedPluginJson(file, label) {
+  const stat = fs.lstatSync(file);
+  if (
+    stat.isSymbolicLink() ||
+    !stat.isFile() ||
+    stat.nlink !== 1 ||
+    stat.size <= 0 ||
+    stat.size > 256 * 1024
+  ) {
+    throw new Error(
+      `${label} must be a single-link regular file under 256 KiB`,
+    );
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
 async function loadOptionalPluginConfig() {
   try {
     const cm = await import("../lib/config-manager.js");
@@ -49,7 +120,14 @@ async function loadOptionalPluginConfig() {
 async function fetchRegistryRemoteArtifacts(
   registryUrl,
   entry,
-  { token, allowInsecure = false } = {},
+  {
+    token,
+    allowInsecure = false,
+    offline = false,
+    proxyUrl,
+    pacFile,
+    caFile,
+  } = {},
 ) {
   if (!registryUrl || !entry || typeof entry !== "object") return null;
   const rawSignature =
@@ -98,6 +176,10 @@ async function fetchRegistryRemoteArtifacts(
     registryUrl,
     token: resolveRegistryToken(registryUrl, { token, config }),
     allowInsecure,
+    offline,
+    proxyUrl,
+    pacFile,
+    caFile,
     signature,
     sbom,
   });
@@ -114,6 +196,32 @@ function cleanupRegistryRemoteArtifacts(remoteArtifacts) {
   }
 }
 
+function remoteSbomComparisonAuthorityMatches(
+  catalogAuthority,
+  remoteArtifactEvidence,
+  expectedSbom = null,
+) {
+  const sbom = remoteArtifactEvidence?.sbom;
+  const semanticFormat = sbom?.format || expectedSbom?.format;
+  if (!isMarketplacePayloadSbomFormat(semanticFormat)) return true;
+  if (!sbom) {
+    const comparisonRequired =
+      semanticFormat === PLUGIN_MARKETPLACE_CANONICAL_PAYLOAD_SBOM_SCHEMA ||
+      (semanticFormat === PLUGIN_MARKETPLACE_PAYLOAD_SBOM_SCHEMA &&
+        Boolean(expectedSbom?.url && expectedSbom?.documentSha256));
+    return !comparisonRequired;
+  }
+  const comparison = catalogAuthority?.remoteSbomPayloadComparison;
+  return (
+    comparison?.status === "matched" &&
+    comparison.format === sbom.format &&
+    comparison.remoteArtifactEvidenceDigest ===
+      remoteArtifactEvidence.evidenceDigest &&
+    comparison.documentSha256 === sbom.documentSha256 &&
+    comparison.remotePayload?.digest === comparison.installedPayload?.digest
+  );
+}
+
 function registryManifestDigestConflict(registrySha256, optionSha256) {
   if (!registrySha256 || !optionSha256) return false;
   return (
@@ -139,7 +247,16 @@ async function buildRegistrySetSelection(
   registryUrls,
   name,
   cwd,
-  { token, allowInsecure = false, strict = false } = {},
+  {
+    token,
+    allowInsecure = false,
+    strict = false,
+    offline = false,
+    registryDigestPins = new Map(),
+    proxyUrl,
+    pacFile,
+    caFile,
+  } = {},
 ) {
   const { fetchRegistry, resolveRegistryToken } =
     await import("../lib/plugin-runtime/remote-source.js");
@@ -165,6 +282,11 @@ async function buildRegistrySetSelection(
         const resolved = await fetchRegistry(url, {
           token: resolvedToken,
           allowInsecure,
+          offline,
+          expectedSha256: registryDigestPins.get(url),
+          proxyUrl,
+          pacFile,
+          caFile,
         });
         return { url, ...resolved };
       } catch (error) {
@@ -216,6 +338,8 @@ async function buildRegistrySetSelection(
       sha256: entry.sha256 || null,
       entry,
       fromCache: source.fromCache === true,
+      documentSha256: source.documentSha256 || null,
+      networkAuthority: source.networkAuthority || null,
     },
   };
 }
@@ -229,6 +353,8 @@ async function buildRegistryInstallPreflight(url, resolved, cwd) {
     registryUrl: url,
     entry: resolved.entry,
     fromCache: resolved.fromCache === true,
+    registryDocumentSha256: resolved.documentSha256,
+    registryNetworkAuthority: resolved.networkAuthority,
     installed,
     hostVersion: VERSION,
   }).preflight;
@@ -245,7 +371,16 @@ function catalogAuthorityFromPreflight(
     candidateDigest: preflight.candidateDigest,
     governanceStatus: preflight.governance.status,
     registryStatus: preflight.registry.status,
+    ...(preflight.registry.documentSha256
+      ? { registryDocumentSha256: preflight.registry.documentSha256 }
+      : {}),
+    ...(preflight.registry.networkAuthority
+      ? { registryNetworkAuthority: preflight.registry.networkAuthority }
+      : {}),
     versionAuthority: preflight.versionAuthority,
+    ...(preflight.publisherIdentity
+      ? { publisherDeclaration: preflight.publisherIdentity }
+      : {}),
     artifactExpectations: {
       manifest: {
         status: preflight.integrity.digest.status,
@@ -323,9 +458,12 @@ async function installedCatalogAuthorityMatches(
   if (!preflight) return null;
   try {
     const { listInstalled } = await import("../lib/plugin-runtime/install.js");
-    const installed = listInstalled({ cwd, scopes: [scope] }).find(
-      (row) => row.name === name && row.scope === scope,
-    );
+    const installed = listInstalled({
+      cwd,
+      scopes: [scope],
+      allowRetainedInstall: true,
+    }).find((row) => row.name === name && row.scope === scope);
+    if (installed?.runtimeBlocked === true) return false;
     const authority = installed?.source?.catalogAuthority;
     return (
       authority?.catalogDigest === preflight.catalogDigest &&
@@ -337,6 +475,11 @@ async function installedCatalogAuthorityMatches(
       (!remoteArtifactEvidence ||
         authority?.remoteArtifactEvidence?.evidenceDigest ===
           remoteArtifactEvidence.evidenceDigest) &&
+      remoteSbomComparisonAuthorityMatches(
+        authority,
+        remoteArtifactEvidence,
+        preflight.integrity?.sbom,
+      ) &&
       authority?.preflightStatus === "allowed"
     );
   } catch {
@@ -345,12 +488,42 @@ async function installedCatalogAuthorityMatches(
 }
 
 async function buildInstalledMarketplaceSnapshot(name, scope, cwd) {
-  const { listInstalled } = await import("../lib/plugin-runtime/install.js");
+  const { listInstalled, readSourceMetadataStrict } =
+    await import("../lib/plugin-runtime/install.js");
   const { discoverPlugins } = await import("../lib/plugin-runtime/scopes.js");
   const row = listInstalled({ cwd, scopes: [scope] }).find(
     (candidate) => candidate.name === name && candidate.scope === scope,
   );
   if (!row) return null;
+  if (row.runtimeBlocked === true) {
+    throw new Error(
+      `INSTALLED_PLUGIN_RUNTIME_BLOCKED (${row.activePointer?.status || "unknown"})`,
+    );
+  }
+  const installedSource = readSourceMetadataStrict(row.dir, {
+    required: true,
+    requireRegistryAuthority: true,
+  });
+  const installedAuthority = installedSource.catalogAuthority;
+  const installedExpectedSbom =
+    installedAuthority?.artifactExpectations?.sbom || null;
+  const installedSemanticComparisonRequired =
+    installedExpectedSbom?.format ===
+      PLUGIN_MARKETPLACE_CANONICAL_PAYLOAD_SBOM_SCHEMA ||
+    (installedExpectedSbom?.format === PLUGIN_MARKETPLACE_PAYLOAD_SBOM_SCHEMA &&
+      Boolean(
+        installedExpectedSbom.url && installedExpectedSbom.documentSha256,
+      ));
+  if (
+    installedSemanticComparisonRequired &&
+    !remoteSbomComparisonAuthorityMatches(
+      installedAuthority,
+      installedAuthority?.remoteArtifactEvidence,
+      installedExpectedSbom,
+    )
+  ) {
+    throw new Error("INSTALLED_SEMANTIC_SBOM_EVIDENCE_INVALID");
+  }
   const discovered = discoverPlugins({
     cwd,
     scopes: [scope],
@@ -359,6 +532,7 @@ async function buildInstalledMarketplaceSnapshot(name, scope, cwd) {
   }).find((candidate) => candidate.name === name && candidate.scope === scope);
   let dependencies = {};
   let payloadSbom = null;
+  let semanticPayloadFormat = null;
   if (discovered?.manifest?.manifestPath) {
     try {
       const fs = await import("node:fs");
@@ -381,25 +555,54 @@ async function buildInstalledMarketplaceSnapshot(name, scope, cwd) {
     }
   }
   if (row.dir) {
-    try {
-      const { buildMarketplacePayloadSbom } =
-        await import("../lib/plugin-runtime/marketplace-artifact-readback.js");
-      payloadSbom = buildMarketplacePayloadSbom(row.dir);
-    } catch {
-      payloadSbom = null;
+    const {
+      assertSafeInstalledPluginStructure,
+      buildMarketplacePayloadSbom,
+      isMarketplacePayloadSbomFormat,
+      validateRemoteSbomPayloadComparison,
+    } = await import("../lib/plugin-runtime/marketplace-artifact-readback.js");
+    const recordedFormat =
+      installedSource?.catalogAuthority?.remoteSbomPayloadComparison?.format;
+    semanticPayloadFormat = isMarketplacePayloadSbomFormat(recordedFormat)
+      ? recordedFormat
+      : null;
+    if (semanticPayloadFormat) {
+      assertSafeInstalledPluginStructure(row.dir);
+      payloadSbom = buildMarketplacePayloadSbom(row.dir, {
+        schemaVersion: semanticPayloadFormat,
+      });
+      const comparison = validateRemoteSbomPayloadComparison(
+        installedAuthority?.remoteSbomPayloadComparison,
+        {
+          remoteArtifactEvidence: installedAuthority?.remoteArtifactEvidence,
+          expectedPayloadSha256: installedExpectedSbom?.payloadSha256,
+          currentPayloadSbom: payloadSbom,
+        },
+      );
+      if (!comparison.valid || !comparison.currentPayloadMatches) {
+        throw new Error("INSTALLED_SEMANTIC_SBOM_EVIDENCE_INVALID");
+      }
+    } else {
+      try {
+        payloadSbom = buildMarketplacePayloadSbom(row.dir);
+      } catch {
+        payloadSbom = null;
+      }
     }
   }
   return {
     name: row.name,
     version: row.version,
     scope: row.scope,
-    source: row.source,
+    enabled: row.enabled !== false,
+    source: installedSource,
     integrity: {
       ...row.integrity,
       sbom: {
         ...row.integrity?.sbom,
         payloadSha256: payloadSbom?.digest || null,
         payloadSchema: payloadSbom?.schemaVersion || null,
+        semanticPayloadFormat,
       },
     },
     license: {
@@ -413,8 +616,29 @@ async function buildInstalledMarketplaceSnapshot(name, scope, cwd) {
 async function buildRegistryUpdateImpact(preflight, name, scope, cwd) {
   const { buildPluginMarketplaceUpdateImpact } =
     await import("../lib/plugin-runtime/marketplace-impact.js");
-  const installed = await buildInstalledMarketplaceSnapshot(name, scope, cwd);
-  return buildPluginMarketplaceUpdateImpact({ preflight, installed });
+  const { listInstalledAllScopes } =
+    await import("../lib/plugin-runtime/install.js");
+  const inventory = listInstalledAllScopes({ cwd }).filter(
+    (entry) => entry.name === name,
+  );
+  const installedScopes = [];
+  for (const entry of inventory) {
+    installedScopes.push(
+      await buildInstalledMarketplaceSnapshot(name, entry.scope, cwd),
+    );
+  }
+  const effectiveScope = inventory.find(
+    (entry) => entry.effectiveAuthority === true,
+  )?.scope;
+  const installed = effectiveScope
+    ? installedScopes.find((entry) => entry?.scope === effectiveScope) || null
+    : null;
+  return buildPluginMarketplaceUpdateImpact({
+    preflight,
+    installed,
+    installedScopes,
+    targetScope: scope,
+  });
 }
 
 /**
@@ -437,9 +661,11 @@ async function resolvePluginCapabilityNotice(
     const { describeCapabilities } =
       await import("../lib/plugin-runtime/capabilities.js");
     const consent = await import("../lib/plugin-runtime/capability-consent.js");
-    const installed = discoverPlugins({ cwd, skipPolicy: true }).find(
-      (p) => p.name === name && p.scope === scope,
-    );
+    const installed = discoverPlugins({
+      cwd,
+      skipPolicy: true,
+      allowRetainedInstall: true,
+    }).find((p) => p.name === name && p.scope === scope);
     if (!installed) {
       if (strict) {
         throw new Error(`${name} is not discoverable at ${scope} scope`);
@@ -532,9 +758,11 @@ async function grantInstalledPluginCapabilities(name, scope, cwd) {
   try {
     const { discoverPlugins } = await import("../lib/plugin-runtime/scopes.js");
     const consent = await import("../lib/plugin-runtime/capability-consent.js");
-    const installed = discoverPlugins({ cwd, skipPolicy: true }).find(
-      (p) => p.name === name && p.scope === scope,
-    );
+    const installed = discoverPlugins({
+      cwd,
+      skipPolicy: true,
+      allowRetainedInstall: true,
+    }).find((p) => p.name === name && p.scope === scope);
     if (!installed) return false;
     const declared = installed.manifest?.capabilities;
     if (!declared || consent.capabilitiesAreEmpty(declared)) return false;
@@ -810,6 +1038,10 @@ export function registerPluginCommand(program) {
       "--scope <scope>",
       "Enable the unified-runtime install at this scope (user|project|local)",
     )
+    .option(
+      "--allow-source-switch",
+      "Approve changing the effective source authority across scopes",
+    )
     .option("--json", "Output unified-runtime result as JSON")
     .action(async (name, options) => {
       try {
@@ -819,6 +1051,7 @@ export function registerPluginCommand(program) {
           const result = setPluginEnabled(name, true, {
             scope: options.scope,
             cwd: process.cwd(),
+            allowSourceSwitch: options.allowSourceSwitch === true,
           });
           if (options.json) console.log(JSON.stringify(result, null, 2));
           else {
@@ -862,6 +1095,10 @@ export function registerPluginCommand(program) {
       "--scope <scope>",
       "Disable the unified-runtime install at this scope (user|project|local)",
     )
+    .option(
+      "--allow-source-switch",
+      "Approve the lower-scope source authority exposed by disabling",
+    )
     .option("--json", "Output unified-runtime result as JSON")
     .action(async (name, options) => {
       try {
@@ -871,6 +1108,7 @@ export function registerPluginCommand(program) {
           const result = setPluginEnabled(name, false, {
             scope: options.scope,
             cwd: process.cwd(),
+            allowSourceSwitch: options.allowSourceSwitch === true,
           });
           if (options.json) console.log(JSON.stringify(result, null, 2));
           else {
@@ -1273,6 +1511,14 @@ export function registerPluginCommand(program) {
     )
     .option("--scope <scope>", "Install scope (user|project|local)", "user")
     .option("--force", "Reinstall over an existing immutable version")
+    .option(
+      "--allow-source-switch",
+      "Explicitly approve changing effective source authority across scopes",
+    )
+    .option(
+      "--allow-downgrade",
+      "Explicitly approve a version downgrade across scoped installs",
+    )
     .option("--sha256 <hex>", "Expected SHA-256 of the manifest file")
     .option("--signature <path>", "Detached Ed25519 signature of the manifest")
     .option("--public-key <path>", "Public key for signature verification")
@@ -1291,6 +1537,28 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow a plain-HTTP registry URL (MITM risk — trusted networks only)",
     )
+    .option(
+      "--offline",
+      "Use verified registry/artifact/source caches or an existing local plugin source",
+    )
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin an exact immutable registry document (repeatable)",
+      collectRepeatableOption,
+      [],
+    )
+    .option(
+      "--proxy <url>",
+      "Explicit HTTP(S) registry proxy (or CC_PLUGIN_REGISTRY_PROXY)",
+    )
+    .option(
+      "--pac-file <path>",
+      "Bounded local PAC file (or CC_PLUGIN_REGISTRY_PAC_FILE)",
+    )
+    .option(
+      "--ca-file <path>",
+      "Custom registry CA bundle (or CC_PLUGIN_REGISTRY_CA_FILE)",
+    )
     .option(
       "--expected-selection-digest <sha256>",
       "Require the exact digest from a prior multi-registry `cc plugin select` review",
@@ -1311,13 +1579,34 @@ export function registerPluginCommand(program) {
       let sourceMetadata = null;
       let expectedIdentity = null;
       let marketplacePreflight = null;
+      let marketplaceImpact = null;
       let remoteArtifactRequest = null;
       let remoteArtifacts = null;
       const registryUrls = normalizeRegistryUrls(options.registry);
       const { isRemoteSource, resolveRemoteSource } =
         await import("../lib/plugin-runtime/remote-source.js");
+      if (
+        options.offline === true &&
+        registryUrls.length === 0 &&
+        !isRemoteSource(source)
+      ) {
+        try {
+          assertOfflinePluginSourceLocal(source);
+        } catch (error) {
+          logger.error(`Offline source validation failed: ${error.message}`);
+          process.exitCode = 1;
+          return;
+        }
+      }
       if (registryUrls.length || isRemoteSource(source)) {
         try {
+          const requestedRegistryUrls = registryUrls.length
+            ? registryUrls
+            : [source];
+          const registryDigestPins = normalizeRegistryDigestPins(
+            options.registryDigest,
+            requestedRegistryUrls,
+          );
           let resolved;
           let url;
           let name;
@@ -1330,6 +1619,9 @@ export function registerPluginCommand(program) {
               {
                 token: options.token,
                 allowInsecure: options.allowInsecureRegistry === true,
+                offline: options.offline === true,
+                registryDigestPins,
+                ...registryNetworkOptions(options),
               },
             );
             resolved = selected.resolved;
@@ -1349,6 +1641,9 @@ export function registerPluginCommand(program) {
               token: options.token,
               config,
               allowInsecure: options.allowInsecureRegistry === true,
+              offline: options.offline === true,
+              expectedSha256: registryDigestPins.get(url),
+              ...registryNetworkOptions(options),
             });
             marketplacePreflight = await buildRegistryInstallPreflight(
               url,
@@ -1372,6 +1667,47 @@ export function registerPluginCommand(program) {
             options.expectedSelectionDigest,
             marketplacePreflight,
           );
+          marketplaceImpact = await buildRegistryUpdateImpact(
+            marketplacePreflight,
+            resolved.entry.name,
+            options.scope,
+            process.cwd(),
+          );
+          if (
+            marketplaceImpact.blockers.some(
+              (blocker) => blocker.code === "SEMANTIC_SBOM_BINDING_DOWNGRADE",
+            )
+          ) {
+            throw new Error(
+              "registry candidate preflight blocked: SEMANTIC_SBOM_BINDING_DOWNGRADE",
+            );
+          }
+          if (
+            marketplaceImpact.blockers.some(
+              (blocker) =>
+                blocker.code === "REGISTRY_VERSION_REQUIRED_FOR_UPDATE",
+            )
+          ) {
+            throw new Error(
+              "registry candidate preflight blocked: REGISTRY_VERSION_REQUIRED_FOR_UPDATE",
+            );
+          }
+          if (
+            marketplaceImpact.changes.source.requiresApproval &&
+            options.allowSourceSwitch !== true
+          ) {
+            throw new Error(
+              `registry candidate preflight blocked: SOURCE_SWITCH_APPROVAL_REQUIRED (${marketplaceImpact.changes.source.kind}); pass --allow-source-switch after reviewing cc plugin impact`,
+            );
+          }
+          if (
+            marketplaceImpact.changes.version.kind === "downgrade" &&
+            options.allowDowngrade !== true
+          ) {
+            throw new Error(
+              "registry candidate preflight blocked: VERSION_DOWNGRADE_APPROVAL_REQUIRED; pass --allow-downgrade after reviewing cc plugin impact",
+            );
+          }
           expectedIdentity = {
             name:
               typeof resolved.entry.name === "string"
@@ -1399,8 +1735,10 @@ export function registerPluginCommand(program) {
                 resolved.source.slice(resolved.source.indexOf("#") + 1)) ||
               null,
             offline: resolved.fromCache === true,
-            catalogAuthority:
-              catalogAuthorityFromPreflight(marketplacePreflight),
+            catalogAuthority: catalogAuthorityFromPreflight(
+              marketplacePreflight,
+              marketplaceImpact,
+            ),
           };
           if (resolved.fromCache) {
             logger.warn(
@@ -1435,6 +1773,8 @@ export function registerPluginCommand(program) {
             {
               token: options.token,
               allowInsecure: options.allowInsecureRegistry === true,
+              offline: options.offline === true,
+              ...registryNetworkOptions(options),
             },
           );
           if (
@@ -1448,7 +1788,7 @@ export function registerPluginCommand(program) {
           if (remoteArtifacts?.authority && sourceMetadata?.catalogAuthority) {
             sourceMetadata.catalogAuthority = catalogAuthorityFromPreflight(
               marketplacePreflight,
-              null,
+              marketplaceImpact,
               remoteArtifacts.authority,
             );
           }
@@ -1489,8 +1829,9 @@ export function registerPluginCommand(program) {
             }
           : null;
       let res = null;
-      let marketplaceTransactionFinalized = false;
-      let marketplaceCleanupPending = false;
+      let lifecycleTransactionFinalized = false;
+      let lifecycleCleanupPending = false;
+      let lifecycleCleanupPath = null;
       try {
         res = installFromSource(installSource, {
           scope: options.scope,
@@ -1501,7 +1842,12 @@ export function registerPluginCommand(program) {
           expectedIdentity,
           managedPolicy: managed,
           policySource: sourceMetadata?.registry || source,
-          transactional: Boolean(marketplacePreflight),
+          remoteSbomBytes: remoteArtifacts?.sbomBytes || null,
+          offline: options.offline === true,
+          transactional: true,
+          enforceUpdateApprovals: true,
+          allowSourceSwitch: options.allowSourceSwitch === true,
+          allowDowngrade: options.allowDowngrade === true,
         });
         const marketplaceAuthorityPersisted = marketplacePreflight
           ? res.sourceMetadata?.catalogAuthority?.catalogDigest ===
@@ -1513,9 +1859,17 @@ export function registerPluginCommand(program) {
             (!marketplacePreflight.selectionDigest ||
               res.sourceMetadata?.catalogAuthority?.selectionDigest ===
                 marketplacePreflight.selectionDigest) &&
+            res.sourceMetadata?.catalogAuthority?.updateImpactDigest ===
+              marketplaceImpact?.impactDigest &&
             (!remoteArtifacts?.authority ||
               res.sourceMetadata?.catalogAuthority?.remoteArtifactEvidence
-                ?.evidenceDigest === remoteArtifacts.authority.evidenceDigest)
+                ?.evidenceDigest ===
+                remoteArtifacts.authority.evidenceDigest) &&
+            remoteSbomComparisonAuthorityMatches(
+              res.sourceMetadata?.catalogAuthority,
+              remoteArtifacts?.authority,
+              marketplacePreflight.integrity?.sbom,
+            )
           : null;
         if (marketplacePreflight && !marketplaceAuthorityPersisted) {
           throw new Error(
@@ -1538,23 +1892,26 @@ export function registerPluginCommand(program) {
               res.scope,
               process.cwd(),
             );
-          if (marketplacePreflight) {
-            const finalization = finalizePluginUpdate(res);
-            if (!finalization.finalized) {
-              throw new Error(
-                "marketplace install transaction could not be finalized",
-              );
-            }
-            marketplaceCleanupPending = finalization.cleanupPending === true;
-            marketplaceTransactionFinalized = true;
+          const finalization = finalizePluginUpdate(res);
+          if (!finalization.finalized) {
+            throw new Error(
+              "plugin install transaction could not be finalized",
+            );
           }
+          lifecycleCleanupPending = finalization.cleanupPending === true;
+          lifecycleCleanupPath = finalization.cleanupPath || null;
+          lifecycleTransactionFinalized = true;
           console.log(
             JSON.stringify(
               {
                 ...res,
                 marketplacePreflight,
+                marketplaceImpact,
                 marketplaceAuthorityPersisted,
-                marketplaceCleanupPending,
+                marketplaceCleanupPending: lifecycleCleanupPending,
+                cleanupPending:
+                  res.cleanupPending === true || lifecycleCleanupPending,
+                cleanupPath: res.cleanupPath || lifecycleCleanupPath,
                 capabilities: capNotice,
                 capabilitiesGranted,
               },
@@ -1573,16 +1930,15 @@ export function registerPluginCommand(program) {
               interactive: Boolean(process.stdin.isTTY),
             },
           );
-          if (marketplacePreflight) {
-            const finalization = finalizePluginUpdate(res);
-            if (!finalization.finalized) {
-              throw new Error(
-                "marketplace install transaction could not be finalized",
-              );
-            }
-            marketplaceCleanupPending = finalization.cleanupPending === true;
-            marketplaceTransactionFinalized = true;
+          const finalization = finalizePluginUpdate(res);
+          if (!finalization.finalized) {
+            throw new Error(
+              "plugin install transaction could not be finalized",
+            );
           }
+          lifecycleCleanupPending = finalization.cleanupPending === true;
+          lifecycleCleanupPath = finalization.cleanupPath || null;
+          lifecycleTransactionFinalized = true;
           logger.success(
             `Installed ${res.name} v${res.version} (${res.scope} scope)` +
               (res.signatureVerified ? chalk.green(" ✔ signed") : ""),
@@ -1602,18 +1958,26 @@ export function registerPluginCommand(program) {
               );
             }
           }
+          if (res.cleanupPending === true || lifecycleCleanupPending) {
+            logger.warn(
+              `Install committed; inert cleanup remains at ${res.cleanupPath || lifecycleCleanupPath || "an internal cleanup directory"} and will be retried on the next mutation`,
+            );
+          }
           for (const w of res.warnings || [])
             logger.log(chalk.yellow(`  ⚠ ${w}`));
         }
       } catch (err) {
         let recoveryNote = "";
-        if (res && marketplacePreflight && !marketplaceTransactionFinalized) {
+        if (res && !lifecycleTransactionFinalized) {
           try {
             const recovery = rollbackPluginUpdate(res);
             if (recovery.rolledBack) {
               recoveryNote = recovery.version
                 ? `; restored v${recovery.version}`
                 : "; removed the rejected install";
+              if (recovery.cleanupPending) {
+                recoveryNote += `; inert cleanup retained at ${recovery.cleanupPath || "an internal cleanup directory"}`;
+              }
             }
           } catch (recoveryError) {
             recoveryNote = `; automatic recovery failed: ${recoveryError.message}`;
@@ -1638,6 +2002,16 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow a plain-HTTP registry URL (MITM risk — trusted networks only)",
     )
+    .option("--offline", "Use only the verified immutable registry cache")
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin the exact immutable registry document",
+      collectRepeatableOption,
+      [],
+    )
+    .option("--proxy <url>", "Explicit HTTP(S) registry proxy")
+    .option("--pac-file <path>", "Bounded local PAC file")
+    .option("--ca-file <path>", "Custom registry CA bundle")
     .option("--json", "Output as JSON")
     .action(async (query, options) => {
       const { fetchRegistry, listRegistryPlugins, resolveRegistryToken } =
@@ -1650,14 +2024,24 @@ export function registerPluginCommand(program) {
         config = null;
       }
       try {
+        const registryDigestPins = normalizeRegistryDigestPins(
+          options.registryDigest,
+          [options.registry],
+        );
         const token = resolveRegistryToken(options.registry, {
           token: options.token,
           config,
         });
-        const { registry, fromCache } = await fetchRegistry(options.registry, {
-          token,
-          allowInsecure: options.allowInsecureRegistry === true,
-        });
+        const { registry, fromCache, documentSha256 } = await fetchRegistry(
+          options.registry,
+          {
+            token,
+            allowInsecure: options.allowInsecureRegistry === true,
+            offline: options.offline === true,
+            expectedSha256: registryDigestPins.get(options.registry),
+            ...registryNetworkOptions(options),
+          },
+        );
         let rows = listRegistryPlugins(registry);
         if (query) {
           const q = query.toLowerCase();
@@ -1668,7 +2052,13 @@ export function registerPluginCommand(program) {
           );
         }
         if (options.json) {
-          console.log(JSON.stringify({ fromCache, plugins: rows }, null, 2));
+          console.log(
+            JSON.stringify(
+              { fromCache, documentSha256, plugins: rows },
+              null,
+              2,
+            ),
+          );
           return;
         }
         if (fromCache) {
@@ -1683,6 +2073,7 @@ export function registerPluginCommand(program) {
           return;
         }
         logger.log(chalk.bold(`Plugins (${rows.length}):`));
+        logger.log(chalk.gray(`Registry SHA-256: ${documentSha256}`));
         for (const r of rows) {
           const ver = r.version ? chalk.gray(` v${r.version}`) : "";
           logger.log(
@@ -1719,6 +2110,16 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow plain-HTTP registry URLs (MITM risk — trusted networks only)",
     )
+    .option("--offline", "Use only verified immutable registry caches")
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin exact immutable registry documents (repeatable)",
+      collectRepeatableOption,
+      [],
+    )
+    .option("--proxy <url>", "Explicit HTTP(S) registry proxy")
+    .option("--pac-file <path>", "Bounded local PAC file")
+    .option("--ca-file <path>", "Custom registry CA bundle")
     .option(
       "--strict",
       "Block candidates missing digest, signature, SBOM, license, or capabilities",
@@ -1745,6 +2146,17 @@ export function registerPluginCommand(program) {
         process.exitCode = 1;
         return;
       }
+      let registryDigestPins;
+      try {
+        registryDigestPins = normalizeRegistryDigestPins(
+          options.registryDigest,
+          registryUrls,
+        );
+      } catch (error) {
+        logger.error(`Marketplace catalog failed: ${error.message}`);
+        process.exitCode = 1;
+        return;
+      }
       const { discoverPlugins } =
         await import("../lib/plugin-runtime/scopes.js");
       const { VERSION } = await import("../constants.js");
@@ -1766,6 +2178,9 @@ export function registerPluginCommand(program) {
             const resolved = await fetchRegistry(url, {
               token,
               allowInsecure: options.allowInsecureRegistry === true,
+              offline: options.offline === true,
+              expectedSha256: registryDigestPins.get(url),
+              ...registryNetworkOptions(options),
             });
             return { url, ...resolved };
           } catch (error) {
@@ -1904,6 +2319,16 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow plain-HTTP registry URLs (MITM risk — trusted networks only)",
     )
+    .option("--offline", "Use only verified immutable registry caches")
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin exact immutable registry documents (repeatable)",
+      collectRepeatableOption,
+      [],
+    )
+    .option("--proxy <url>", "Explicit HTTP(S) registry proxy")
+    .option("--pac-file <path>", "Bounded local PAC file")
+    .option("--ca-file <path>", "Custom registry CA bundle")
     .option(
       "--strict",
       "Block candidates missing digest, signature, SBOM, license, or capabilities",
@@ -1911,14 +2336,22 @@ export function registerPluginCommand(program) {
     .option("--json", "Output the versioned candidate selection as JSON")
     .action(async (name, options) => {
       try {
+        const registryUrls = normalizeRegistryUrls(options.registry);
+        const registryDigestPins = normalizeRegistryDigestPins(
+          options.registryDigest,
+          registryUrls,
+        );
         const result = await buildRegistrySetSelection(
-          normalizeRegistryUrls(options.registry),
+          registryUrls,
           name,
           process.cwd(),
           {
             token: options.token,
             allowInsecure: options.allowInsecureRegistry === true,
             strict: options.strict === true,
+            offline: options.offline === true,
+            registryDigestPins,
+            ...registryNetworkOptions(options),
           },
         );
         const { selection } = result;
@@ -1980,10 +2413,24 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow a plain-HTTP registry URL (MITM risk — trusted networks only)",
     )
+    .option("--offline", "Use only verified immutable registry caches")
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin exact immutable registry documents (repeatable)",
+      collectRepeatableOption,
+      [],
+    )
+    .option("--proxy <url>", "Explicit HTTP(S) registry proxy")
+    .option("--pac-file <path>", "Bounded local PAC file")
+    .option("--ca-file <path>", "Custom registry CA bundle")
     .option("--json", "Output the versioned update-impact projection as JSON")
     .action(async (name, options) => {
       try {
         const registryUrls = normalizeRegistryUrls(options.registry);
+        const registryDigestPins = normalizeRegistryDigestPins(
+          options.registryDigest,
+          registryUrls,
+        );
         const selected = await buildRegistrySetSelection(
           registryUrls,
           name,
@@ -1991,6 +2438,9 @@ export function registerPluginCommand(program) {
           {
             token: options.token,
             allowInsecure: options.allowInsecureRegistry === true,
+            offline: options.offline === true,
+            registryDigestPins,
+            ...registryNetworkOptions(options),
           },
         );
         if (!selected.preflight) {
@@ -2019,6 +2469,12 @@ export function registerPluginCommand(program) {
           logger.log(
             `  source: ${impact.changes.source.kind}${impact.changes.source.requiresApproval ? " (explicit approval required)" : ""}`,
           );
+          if (impact.changes.scopeAuthority) {
+            const authority = impact.changes.scopeAuthority;
+            logger.log(
+              `  scope authority: ${authority.effectiveFrom || "none"} → ${authority.effectiveTo || "none"}${authority.changed ? " (effective change)" : ""}`,
+            );
+          }
           logger.log(
             `  license: ${impact.changes.license.from || "unknown"} → ${impact.changes.license.to || "unknown"}`,
           );
@@ -2060,11 +2516,17 @@ export function registerPluginCommand(program) {
   plugin
     .command("installed")
     .description("List plugins installed in the unified runtime (scope dirs)")
+    .option(
+      "--all-scopes",
+      "Show every physical scoped install, including shadowed and disabled rows",
+    )
     .option("--json", "Output as JSON")
     .action(async (options) => {
-      const { listInstalled } =
+      const { listInstalled, listInstalledAllScopes } =
         await import("../lib/plugin-runtime/install.js");
-      const rows = listInstalled({ cwd: process.cwd() });
+      const rows = options.allScopes
+        ? listInstalledAllScopes({ cwd: process.cwd() })
+        : listInstalled({ cwd: process.cwd() });
       if (options.json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
@@ -2077,6 +2539,17 @@ export function registerPluginCommand(program) {
         await import("../lib/plugin-runtime/trust.js");
       logger.log(chalk.bold(`Installed plugins (${rows.length}):`));
       for (const r of rows) {
+        if (r.runtimeBlocked === true) {
+          const status = r.activePointer?.status || "unknown";
+          const inspectionVersion = r.activePointer?.inspectionVersion;
+          const inspection = inspectionVersion
+            ? `, inspect=v${inspectionVersion}`
+            : "";
+          logger.log(
+            `  ${chalk.red("!")} ${chalk.cyan(r.name)} ${chalk.gray(`[${r.scope}]`)} ${chalk.red(`active=blocked (${status})`)}${inspection}`,
+          );
+          continue;
+        }
         const ok = r.ok ? chalk.green("✔") : chalk.red("✖");
         const trust = isPluginTrusted(r)
           ? chalk.green("trusted")
@@ -2100,8 +2573,172 @@ export function registerPluginCommand(program) {
       }
     });
 
+  // plugin transaction/recover — inspect or resolve an abandoned durable
+  // lifecycle owner. Ordinary mutations never reclaim this authority.
+  plugin
+    .command("transaction <name>")
+    .description("Inspect a durable cross-process plugin lifecycle transaction")
+    .option("--scope <scope>", "Installed plugin scope", "user")
+    .option("--json", "Output the redacted transaction authority as JSON")
+    .action(async (name, options) => {
+      try {
+        const { inspectPluginTransaction } =
+          await import("../lib/plugin-runtime/install.js");
+        const transaction = inspectPluginTransaction(name, {
+          scope: options.scope,
+          cwd: process.cwd(),
+        });
+        if (!transaction) {
+          throw new Error(
+            `no retained transaction exists for ${name} at ${options.scope} scope`,
+          );
+        }
+        if (options.json) {
+          console.log(JSON.stringify(transaction, null, 2));
+          return;
+        }
+        logger.log(
+          `${name} [${options.scope}] ${transaction.operation}/${transaction.phase} r${transaction.revision}`,
+        );
+        logger.log(
+          `  owner: pid=${transaction.owner.pid} host=${transaction.owner.hostname} alive=${transaction.owner.alive == null ? "unverifiable" : transaction.owner.alive}`,
+        );
+        logger.log(`  journal digest: ${transaction.journalDigest}`);
+      } catch (error) {
+        logger.error(`Transaction inspection failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  plugin
+    .command("recover <name>")
+    .description("Recover a durable plugin transaction after its owner died")
+    .option("--scope <scope>", "Installed plugin scope", "user")
+    .option(
+      "--action <action>",
+      "Recovery action (rollback|finalize|abort)",
+      "rollback",
+    )
+    .option(
+      "--force-owner",
+      "Explicitly override a live or cross-host owner after external adjudication",
+    )
+    .option("--json", "Output the recovery result as JSON")
+    .action(async (name, options) => {
+      try {
+        const { recoverPluginTransaction } =
+          await import("../lib/plugin-runtime/install.js");
+        const recovery = recoverPluginTransaction(name, {
+          scope: options.scope,
+          cwd: process.cwd(),
+          action: options.action,
+          forceOwner: options.forceOwner === true,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(recovery, null, 2));
+          return;
+        }
+        logger.success(
+          `${name} transaction ${recovery.action}: ${recovery.recovered ? "recovered" : "recovery still required"}`,
+        );
+        if (recovery.cleanupPending) {
+          logger.warn(`Cleanup remains at ${recovery.cleanupPath}`);
+        }
+      } catch (error) {
+        logger.error(`Transaction recovery failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  plugin
+    .command("provenance-plan <name>")
+    .description(
+      "Build exact payload-bound authority bytes for a signed legacy provenance migration",
+    )
+    .requiredOption("--version <version>", "Installed plugin version")
+    .requiredOption(
+      "--metadata <file>",
+      "JSON source metadata to bind (local, git, or complete registry authority)",
+    )
+    .option("--scope <scope>", "Installed plugin scope", "user")
+    .option(
+      "--issued-at <timestamp>",
+      "Canonical ISO-8601 UTC signing time (defaults to now)",
+    )
+    .action(async (name, options) => {
+      try {
+        const { planPluginProvenanceMigration } =
+          await import("../lib/plugin-runtime/install.js");
+        const plan = planPluginProvenanceMigration(name, {
+          scope: options.scope,
+          cwd: process.cwd(),
+          version: options.version,
+          issuedAt: options.issuedAt,
+          sourceMetadata: readBoundedPluginJson(
+            options.metadata,
+            "plugin source metadata",
+          ),
+        });
+        console.log(JSON.stringify(plan, null, 2));
+      } catch (error) {
+        logger.error(`Provenance migration plan failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  plugin
+    .command("provenance-migrate <name>")
+    .description(
+      "Apply a signed, payload-bound provenance record to one legacy install",
+    )
+    .requiredOption("--version <version>", "Installed plugin version")
+    .requiredOption(
+      "--attestation <file>",
+      "Signed attestation JSON containing authority, publicKeyPem, and signatureBase64",
+    )
+    .requiredOption(
+      "--expected-signer-sha256 <hex>",
+      "Exact trusted signer SPKI SHA-256 fingerprint",
+    )
+    .option("--scope <scope>", "Installed plugin scope", "user")
+    .option("--yes", "Confirm the provenance mutation")
+    .option("--json", "Output the migration result as JSON")
+    .action(async (name, options) => {
+      try {
+        if (options.yes !== true) {
+          throw new Error(
+            "refusing provenance mutation without --yes after reviewing the signed plan",
+          );
+        }
+        const { migratePluginProvenance } =
+          await import("../lib/plugin-runtime/install.js");
+        const result = migratePluginProvenance(name, {
+          scope: options.scope,
+          cwd: process.cwd(),
+          version: options.version,
+          attestation: readBoundedPluginJson(
+            options.attestation,
+            "plugin provenance attestation",
+          ),
+          expectedSignerSha256: options.expectedSignerSha256,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        logger.success(
+          `${name}@${result.version} provenance migrated at ${result.scope} scope`,
+        );
+        logger.log(`  authority: ${result.authorityDigest}`);
+        logger.log(`  signer: ${result.signerPublicKeySha256}`);
+      } catch (error) {
+        logger.error(`Provenance migration failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   // plugin evidence — compare persisted registry artifact expectations with
-  // actual bytes in the active immutable install. Remote artifacts are not
+  // actual bytes in the active on-disk install. Remote artifacts are not
   // re-fetched here. The signature record is bound to the locally re-verified
   // lock; the external SBOM digest remains an install-time record because its
   // document bytes are not retained.
@@ -2118,7 +2755,7 @@ export function registerPluginCommand(program) {
     .option("--json", "Output the versioned artifact readback as JSON")
     .action(async (name, options) => {
       try {
-        const { listInstalled } =
+        const { listInstalled, readSourceMetadataStrict } =
           await import("../lib/plugin-runtime/install.js");
         const installed = listInstalled({
           cwd: process.cwd(),
@@ -2130,12 +2767,21 @@ export function registerPluginCommand(program) {
         if (!installed) {
           throw new Error(`${name} is not installed at ${options.scope} scope`);
         }
+        if (installed.runtimeBlocked === true) {
+          throw new Error(
+            `${name} runtime is blocked by active pointer status ${installed.activePointer?.status || "unknown"}; repair it with plugin use before reading active evidence`,
+          );
+        }
+        const source = readSourceMetadataStrict(installed.dir, {
+          required: true,
+          requireRegistryAuthority: true,
+        });
         const { buildPluginMarketplaceArtifactReadback } =
           await import("../lib/plugin-runtime/marketplace-artifact-readback.js");
         const evidence = buildPluginMarketplaceArtifactReadback({
           root: installed.dir,
           scope: installed.scope,
-          source: installed.source,
+          source,
         });
         if (options.json) {
           console.log(JSON.stringify(evidence, null, 2));
@@ -2174,14 +2820,14 @@ export function registerPluginCommand(program) {
                 }`
               : null,
             evidence.claims.remoteSbomFetched
-              ? "the SBOM digest is an install-time record and was not re-hashed here"
+              ? "the remote SBOM document digest is an install-time record; its document bytes were not retained or re-hashed, while the installed payload inventory above was freshly computed"
               : null,
           ].filter(Boolean);
           logger.log(
             chalk.gray(
               remoteKinds.length
-                ? `  Install-time remote ${remoteKinds.join("/")} evidence is present: ${remoteDetail.join("; ")}. Remote documents were not re-fetched; publisher identity remains unverified.`
-                : "  No valid install-time remote signature/SBOM evidence is available; publisher identity remains unverified.",
+                ? `  Install-time remote ${remoteKinds.join("/")} evidence is present: ${remoteDetail.join("; ")}. Remote documents were not re-fetched; publisher identity is ${evidence.claims.registryPublisherIdentityVerified ? "verified by the current managed organization trust root" : "unverified"}.`
+                : `  No valid install-time remote signature/SBOM evidence is available; publisher identity is ${evidence.claims.registryPublisherIdentityVerified ? "verified by the current managed organization trust root" : "unverified"}.`,
             ),
           );
         }
@@ -2574,13 +3220,29 @@ export function registerPluginCommand(program) {
     .description(`Uninstall a runtime plugin from a scope (${SCOPES})`)
     .option("--scope <scope>", "Scope to remove from", "user")
     .option("--version <version>", "Remove only this version (default: all)")
+    .option(
+      "--allow-source-switch",
+      "Approve a different-source fallback when removing the active version",
+    )
     .action(async (name, options) => {
-      const { uninstall } = await import("../lib/plugin-runtime/install.js");
+      const { listInstalled, uninstall } =
+        await import("../lib/plugin-runtime/install.js");
       try {
+        const blockedRow = listInstalled({
+          cwd: process.cwd(),
+          scopes: [options.scope],
+        }).find(
+          (row) =>
+            row.name === name &&
+            row.scope === options.scope &&
+            row.runtimeBlocked === true,
+        );
         const res = uninstall(name, {
           scope: options.scope,
           cwd: process.cwd(),
           version: options.version,
+          allowSourceSwitch: options.allowSourceSwitch === true,
+          allowBlockedIdentity: Boolean(blockedRow),
         });
         logger.success(
           `Uninstalled ${name} (${res.removed.join(", ") || "nothing"}) from ${options.scope} scope`,
@@ -2617,6 +3279,28 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow a plain-HTTP registry URL (MITM risk — trusted networks only)",
     )
+    .option(
+      "--offline",
+      "Use verified registry/artifact/source caches or an existing local plugin source",
+    )
+    .option(
+      "--registry-digest <url=sha256>",
+      "Pin an exact immutable registry document (repeatable)",
+      collectRepeatableOption,
+      [],
+    )
+    .option(
+      "--proxy <url>",
+      "Explicit HTTP(S) registry proxy (or CC_PLUGIN_REGISTRY_PROXY)",
+    )
+    .option(
+      "--pac-file <path>",
+      "Bounded local PAC file (or CC_PLUGIN_REGISTRY_PAC_FILE)",
+    )
+    .option(
+      "--ca-file <path>",
+      "Custom registry CA bundle (or CC_PLUGIN_REGISTRY_CA_FILE)",
+    )
     .option(
       "--allow-source-switch",
       "Explicitly approve changing registry/source authority",
@@ -2649,8 +3333,28 @@ export function registerPluginCommand(program) {
       const registryUrls = normalizeRegistryUrls(options.registry);
       const { isRemoteSource, resolveRemoteSource } =
         await import("../lib/plugin-runtime/remote-source.js");
+      if (
+        options.offline === true &&
+        registryUrls.length === 0 &&
+        !isRemoteSource(source)
+      ) {
+        try {
+          assertOfflinePluginSourceLocal(source);
+        } catch (error) {
+          logger.error(`Offline source validation failed: ${error.message}`);
+          process.exitCode = 1;
+          return;
+        }
+      }
       if (registryUrls.length || isRemoteSource(source)) {
         try {
+          const requestedRegistryUrls = registryUrls.length
+            ? registryUrls
+            : [source];
+          const registryDigestPins = normalizeRegistryDigestPins(
+            options.registryDigest,
+            requestedRegistryUrls,
+          );
           let resolved;
           let url;
           let name;
@@ -2663,6 +3367,9 @@ export function registerPluginCommand(program) {
               {
                 token: options.token,
                 allowInsecure: options.allowInsecureRegistry === true,
+                offline: options.offline === true,
+                registryDigestPins,
+                ...registryNetworkOptions(options),
               },
             );
             resolved = selected.resolved;
@@ -2682,6 +3389,9 @@ export function registerPluginCommand(program) {
               token: options.token,
               config,
               allowInsecure: options.allowInsecureRegistry === true,
+              offline: options.offline === true,
+              expectedSha256: registryDigestPins.get(url),
+              ...registryNetworkOptions(options),
             });
             marketplacePreflight = await buildRegistryInstallPreflight(
               url,
@@ -2711,6 +3421,25 @@ export function registerPluginCommand(program) {
             options.scope,
             process.cwd(),
           );
+          if (
+            marketplaceImpact.blockers.some(
+              (blocker) => blocker.code === "SEMANTIC_SBOM_BINDING_DOWNGRADE",
+            )
+          ) {
+            throw new Error(
+              "registry candidate preflight blocked: SEMANTIC_SBOM_BINDING_DOWNGRADE",
+            );
+          }
+          if (
+            marketplaceImpact.blockers.some(
+              (blocker) =>
+                blocker.code === "REGISTRY_VERSION_REQUIRED_FOR_UPDATE",
+            )
+          ) {
+            throw new Error(
+              "registry candidate preflight blocked: REGISTRY_VERSION_REQUIRED_FOR_UPDATE",
+            );
+          }
           if (
             marketplaceImpact.changes.source.requiresApproval &&
             options.allowSourceSwitch !== true
@@ -2808,6 +3537,8 @@ export function registerPluginCommand(program) {
             {
               token: options.token,
               allowInsecure: options.allowInsecureRegistry === true,
+              offline: options.offline === true,
+              ...registryNetworkOptions(options),
             },
           );
           if (
@@ -2873,7 +3604,12 @@ export function registerPluginCommand(program) {
           expectedIdentity,
           managedPolicy: managed,
           policySource: sourceMetadata?.registry || source,
+          remoteSbomBytes: remoteArtifacts?.sbomBytes || null,
+          offline: options.offline === true,
           transactional: true,
+          enforceUpdateApprovals: true,
+          allowSourceSwitch: options.allowSourceSwitch === true,
+          allowDowngrade: options.allowDowngrade === true,
         });
         marketplaceAuthorityPersisted = await installedCatalogAuthorityMatches(
           res.name,
@@ -2937,6 +3673,7 @@ export function registerPluginCommand(program) {
         let activationStatus = changed ? "activated" : "unchanged";
         let rollbackVersion = null;
         let cleanupPending = false;
+        let cleanupPath = null;
         if (rollbackReason) {
           const recovery = rollbackPluginUpdate(res);
           if (!recovery.rolledBack) {
@@ -2944,6 +3681,8 @@ export function registerPluginCommand(program) {
           }
           activationStatus = "rolled_back";
           rollbackVersion = recovery.version;
+          cleanupPending = recovery.cleanupPending === true;
+          cleanupPath = recovery.cleanupPath || null;
           marketplaceAuthorityPersisted =
             await installedCatalogAuthorityMatches(
               res.name,
@@ -2954,7 +3693,9 @@ export function registerPluginCommand(program) {
               remoteArtifacts?.authority || null,
             );
         } else {
-          cleanupPending = finalizePluginUpdate(res).cleanupPending === true;
+          const finalization = finalizePluginUpdate(res);
+          cleanupPending = finalization.cleanupPending === true;
+          cleanupPath = finalization.cleanupPath || null;
         }
 
         if (options.json) {
@@ -2972,6 +3713,7 @@ export function registerPluginCommand(program) {
                 rollbackVersion,
                 rollbackReason,
                 cleanupPending,
+                cleanupPath,
               },
               null,
               2,
@@ -3018,6 +3760,11 @@ export function registerPluginCommand(program) {
             `${res.name} is already up to date at v${res.version} (use --force to reinstall)`,
           );
         }
+        if (cleanupPending) {
+          logger.warn(
+            `Plugin state committed; inert cleanup remains at ${cleanupPath || "an internal cleanup directory"} and will be retried on the next mutation`,
+          );
+        }
       } catch (err) {
         let recoveryNote = "";
         if (res) {
@@ -3027,6 +3774,9 @@ export function registerPluginCommand(program) {
               recoveryNote = recovery.version
                 ? `; restored v${recovery.version}`
                 : "; removed the rejected install";
+              if (recovery.cleanupPending) {
+                recoveryNote += `; inert cleanup retained at ${recovery.cleanupPath || "an internal cleanup directory"}`;
+              }
             }
           } catch (recoveryError) {
             recoveryNote = `; automatic recovery failed: ${recoveryError.message}`;
@@ -3044,6 +3794,10 @@ export function registerPluginCommand(program) {
     .command("use <name> <version>")
     .description("Pin a plugin's active version (rollback or switch)")
     .option("--scope <scope>", "Scope", "user")
+    .option(
+      "--allow-source-switch",
+      "Approve activating an installed version from a different source",
+    )
     .action(async (name, version, options) => {
       const { setActiveVersion } =
         await import("../lib/plugin-runtime/install.js");
@@ -3051,6 +3805,7 @@ export function registerPluginCommand(program) {
         setActiveVersion(name, version, {
           scope: options.scope,
           cwd: process.cwd(),
+          allowSourceSwitch: options.allowSourceSwitch === true,
         });
         logger.success(
           `${name} active version → v${version} (${options.scope} scope)`,