codex-copilot-dx 0.6.11 → 0.6.13

package/src/pm-studio-setup.mjs

@@ -9,12 +9,15 @@ import {
 } from "./auth-profile.mjs";
 import {
   PM_STUDIO_2_9_7_RECIPE,
+  PM_STUDIO_2_9_10_RECIPE,
   PM_STUDIO_RECIPES,
+  createCompatiblePmStudioRecipe,
   inspectElectronAsarIntegritySlots,
   inspectAsarBuffer,
   patchAsarBuffer,
   sha256Hex,
 } from "./pm-studio-asar.mjs";
+import { withPmStudioSetupLock } from "./pm-studio-setup-lock.mjs";
 
 export const DEFAULT_PM_STUDIO_APP_PATH = "/Applications/PM Studio.app";
 export const PM_STUDIO_CLAUDE_AUTH_COMMAND = "ccdx auth login claude --reauth --github-login <personal-login>";
@@ -268,9 +271,7 @@ function defaultInspectCodeSign({ appPath, processRunner }) {
     : "";
   return {
     valid: !verify.error && verify.status === 0
-      && !display.error && display.status === 0
-      && !entitlementsResult.error && entitlementsResult.status === 0
-      && hasEntitlements,
+      && !display.error && display.status === 0,
     verifyValid: !verify.error && verify.status === 0,
     displayValid: !display.error && display.status === 0,
     entitlementsState: hasEntitlements
@@ -315,11 +316,19 @@ function defaultInspectExecutableIntegrity({ appPath, infoPlistPath, recipe, pro
   };
 }
 
-function defaultSignApp({ appPath, processRunner }) {
-  runChecked(processRunner, "/usr/bin/codesign", [
+function defaultSignApp({ appPath, source, processRunner }) {
+  const preserve = [];
+  if (source?.codeSign?.displayValid === true) {
+    if (source.codeSign.entitlementsState === "xml") preserve.push("entitlements");
+    if (source.codeSign.flags) preserve.push("flags");
+    if (source.codeSign.runtimeVersion) preserve.push("runtime");
+  }
+  const args = [
     "--force", "--deep", "--sign", "-", "--timestamp=none",
-    "--preserve-metadata=identifier,entitlements,flags,runtime", appPath,
-  ], "Ad-hoc codesigning PM Studio");
+  ];
+  if (preserve.length > 0) args.push(`--preserve-metadata=${preserve.join(",")}`);
+  args.push(appPath);
+  runChecked(processRunner, "/usr/bin/codesign", args, "Ad-hoc codesigning PM Studio");
 }
 
 function defaultListBlockingProcesses({ processRunner }) {
@@ -412,6 +421,7 @@ export function createPmStudioSetupOperations(overrides = {}) {
     inspectCodeSign: defaultInspectCodeSign,
     inspectBundleContent: defaultInspectBundleContent,
     inspectExecutableIntegrity: defaultInspectExecutableIntegrity,
+    withSetupLock: ({ appPath }, fn) => withPmStudioSetupLock({ appPath }, fn),
     signApp: defaultSignApp,
     listBlockingProcesses: defaultListBlockingProcesses,
     copyBundle: defaultCopyBundle,
@@ -452,17 +462,6 @@ function bundleContentMatches(actual, expected) {
     && actual?.xattrCount === expected?.xattrCount;
 }
 
-function sourceCodeSignatureMatches(actual, expected) {
-  return actual?.adHoc === false
-    && actual?.displayValid === true
-    && actual?.identifier === expected?.identifier
-    && actual?.teamIdentifier === expected?.teamIdentifier
-    && actual?.flags === expected?.flags
-    && actual?.runtimeVersion === expected?.runtimeVersion
-    && actual?.cdHashFull === expected?.cdHashFull
-    && actual?.notarizationTicket === expected?.notarizationTicket;
-}
-
 export function inspectPmStudioApp({
   appPath,
   recipe = PM_STUDIO_2_9_7_RECIPE,
@@ -505,22 +504,14 @@ export function inspectPmStudioApp({
 
   const exactSourceBundle = !recipe.sourceBundleContent
     || bundleContentMatches(bundleContent, recipe.sourceBundleContent);
-  const strictVendorSignature = codeSign?.valid === true
-    && codeSign?.adHoc === false
-    && codeSign?.teamIdentifier === recipe.sourceTeamIdentifier;
-  const exactInvalidVendorSignature = recipe.sourceBundleContent
-    && exactSourceBundle
-    && codeSign?.valid === false
-    && codeSign?.verifyValid === false
-    && codeSign?.entitlementsState === "invalid"
-    && sourceCodeSignatureMatches(codeSign, recipe.sourceCodeSignature);
-  const sourceSignatureAccepted = strictVendorSignature || exactInvalidVendorSignature;
   const patchedSignatureAccepted = codeSign?.valid === true
     && codeSign?.adHoc === true
+    && codeSign?.identifier === recipe.bundleIdentifier
     && (!recipe.patchedSigningMetadata
       || JSON.stringify(signingMetadata(codeSign)) === JSON.stringify(recipe.patchedSigningMetadata));
   const predecessorSignatureAccepted = codeSign?.valid === true
     && codeSign?.adHoc === true
+    && codeSign?.identifier === recipe.bundleIdentifier
     && Boolean(recipe.predecessor?.signingMetadata)
     && JSON.stringify(signingMetadata(codeSign)) === JSON.stringify(recipe.predecessor.signingMetadata);
   const clean = issues.length === 0
@@ -528,8 +519,7 @@ export function inspectPmStudioApp({
     && integrityMatches(plistIntegrity, "SHA256", recipe.sourceHeaderSha256)
     && executableIntegrity.executableSha256 === recipe.sourceExecutableSha256
     && executableIntegrity.frameworkSha256 === recipe.sourceElectronFrameworkSha256
-    && exactSourceBundle
-    && sourceSignatureAccepted;
+    && exactSourceBundle;
   const patched = issues.length === 0
     && asar.state === "patched"
     && integrityMatches(plistIntegrity, "SHA256", recipe.patchedHeaderSha256)
@@ -561,15 +551,15 @@ export function inspectPmStudioApp({
     if (asar.state === "clean" && recipe.sourceBundleContent && !exactSourceBundle) {
       issues.push("bundle content does not match the exact clean recipe");
     }
-    if (!codeSign?.valid && !(asar.state === "clean" && exactInvalidVendorSignature)) {
+    if (asar.state !== "clean" && !codeSign?.valid) {
       issues.push("codesign verification failed");
     }
-    else if (asar.state === "clean" && codeSign.adHoc) issues.push("clean bundle has an unexpected ad-hoc signature");
     else if (["patched", "predecessor", "legacy"].includes(asar.state) && !codeSign.adHoc) {
       issues.push(`${asar.state} bundle is not ad-hoc signed`);
     }
-    else if (asar.state === "clean" && codeSign.teamIdentifier !== recipe.sourceTeamIdentifier) {
-      issues.push(`clean bundle TeamIdentifier is ${codeSign.teamIdentifier || "missing"}, expected ${recipe.sourceTeamIdentifier}`);
+    else if (["patched", "predecessor", "legacy"].includes(asar.state)
+      && codeSign.identifier !== recipe.bundleIdentifier) {
+      issues.push(`${asar.state} bundle identifier does not match the recipe`);
     }
     if (asar.state === "clean"
       && executableIntegrity.executableSha256 !== recipe.sourceExecutableSha256) {
@@ -605,7 +595,7 @@ export function inspectPmStudioApp({
     codeSign,
     bundleContent,
     sourceVerification: clean
-      ? exactInvalidVendorSignature ? "exact-bundle-content" : "codesign"
+      ? recipe.sourceBundleContent ? "local-content" : "exact-recipe"
       : "",
     paths,
     issues,
@@ -648,6 +638,258 @@ function selectRecipe(metadata, recipes) {
     && recipe.bundleIdentifier === String(metadata.bundleIdentifier));
 }
 
+function compatibleStaticOptions(metadata, executable) {
+  return {
+    version: String(metadata.version),
+    build: String(metadata.build),
+    bundleIdentifier: String(metadata.bundleIdentifier),
+    sourceTeamIdentifier: "local-app",
+    executable,
+    electronFrameworkPath: PM_STUDIO_2_9_10_RECIPE.electronFrameworkPath,
+    embeddedAsarIntegrity: PM_STUDIO_2_9_10_RECIPE.embeddedAsarIntegrity,
+    asarPath: PM_STUDIO_2_9_10_RECIPE.asarPath,
+    infoPlistPath: PM_STUDIO_2_9_10_RECIPE.infoPlistPath,
+    integrityKey: PM_STUDIO_2_9_10_RECIPE.integrityKey,
+  };
+}
+
+function compatibleSourceBundleContent({ appPath, operations }) {
+  const ignoredXattrs = PM_STUDIO_2_9_10_RECIPE.sourceBundleContent.ignoredXattrs;
+  const inspected = operations.inspectBundleContent({
+    ...appPaths(appPath, PM_STUDIO_2_9_10_RECIPE),
+    recipe: PM_STUDIO_2_9_10_RECIPE,
+    processRunner: operations.processRunner,
+  });
+  return {
+    ...inspected,
+    ignoredXattrs: [...ignoredXattrs],
+  };
+}
+
+function compatibleSourceStructure({ appPath, metadata, operations }) {
+  const paths = appPaths(appPath, PM_STUDIO_2_9_10_RECIPE);
+  const executableIntegrity = operations.inspectExecutableIntegrity({
+    ...paths,
+    recipe: PM_STUDIO_2_9_10_RECIPE,
+    processRunner: operations.processRunner,
+  });
+  if (!executableIntegrity?.executableName
+    || !executableIntegrity?.embeddedIntegrity?.supported
+    || executableIntegrity.embeddedIntegrity.state !== PM_STUDIO_2_9_10_RECIPE.embeddedAsarIntegrity) {
+    throw setupError("PM_STUDIO_ASAR_INCOMPATIBLE",
+      "PM Studio compatible-version discovery found an unsupported executable or embedded ASAR integrity policy");
+  }
+  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(paths.asarPath), {
+    ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
+    sourceExecutableSha256: executableIntegrity.executableSha256,
+    sourceElectronFrameworkSha256: executableIntegrity.frameworkSha256,
+  });
+  const plistIntegrity = operations.readAsarIntegrity({
+    ...paths,
+    recipe: compatibleRecipe,
+    processRunner: operations.processRunner,
+  });
+  if (!integrityMatches(plistIntegrity, "SHA256", compatibleRecipe.sourceHeaderSha256)) {
+    throw setupError("PM_STUDIO_ASAR_INCOMPATIBLE",
+      "PM Studio compatible-version discovery found mismatched ElectronAsarIntegrity metadata");
+  }
+  return { paths, executableIntegrity, compatibleRecipe };
+}
+
+function frozenBundleContent(value) {
+  return Object.freeze({
+    ...value,
+    ignoredXattrs: Object.freeze([...(value.ignoredXattrs || [])]),
+  });
+}
+
+function createCompatibleSourceRecipe({ appPath, metadata, operations }) {
+  const { compatibleRecipe } = compatibleSourceStructure({ appPath, metadata, operations });
+  const sourceBundleContent = compatibleSourceBundleContent({ appPath, operations });
+  return Object.freeze({
+    ...compatibleRecipe,
+    sourceBundleContent: frozenBundleContent(sourceBundleContent),
+  });
+}
+
+function sameIgnoredXattrs(value) {
+  return JSON.stringify(value)
+    === JSON.stringify(PM_STUDIO_2_9_10_RECIPE.sourceBundleContent.ignoredXattrs);
+}
+
+
+function compatibleRecipeFromManifest({ backupDir, manifest, metadata, operations }) {
+  if (manifest?.schema_version !== 2
+    || manifest?.kind !== "ccdx-pm-studio-backup"
+    || !String(manifest?.recipe_id || "").startsWith("pm-studio-compatible-")
+    || manifest?.app?.bundle_identifier !== String(metadata.bundleIdentifier)
+    || manifest?.app?.version !== String(metadata.version)
+    || manifest?.app?.build !== String(metadata.build)
+    || !sameIgnoredXattrs(manifest?.source?.bundle_content?.ignoredXattrs)) {
+    return null;
+  }
+  const backupAppPath = path.join(backupDir, "PM Studio.app");
+  assertInstalledAppPath(backupAppPath);
+  const sourceAsarPath = path.join(backupAppPath, PM_STUDIO_2_9_10_RECIPE.asarPath);
+  const backupPaths = appPaths(backupAppPath, PM_STUDIO_2_9_10_RECIPE);
+  const executableIntegrity = operations.inspectExecutableIntegrity({
+    ...backupPaths,
+    recipe: PM_STUDIO_2_9_10_RECIPE,
+    processRunner: operations.processRunner,
+  });
+  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(sourceAsarPath), {
+    ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
+    sourceExecutableSha256: manifest?.source?.binaries?.main_executable_sha256,
+    sourceElectronFrameworkSha256: manifest?.source?.binaries?.electron_framework_sha256,
+  });
+  const recipe = Object.freeze({
+    ...compatibleRecipe,
+    sourceBundleContent: frozenBundleContent(manifest.source.bundle_content),
+  });
+  if (manifest.compatibility !== recipe.compatibility
+    || manifest.recipe_id !== recipe.id
+    || manifest?.source?.asar_sha256 !== recipe.sourceAsarSha256
+    || manifest?.source?.asar_header_sha256 !== recipe.sourceHeaderSha256
+    || manifest?.patched?.asar_sha256 !== recipe.patchedAsarSha256
+    || manifest?.patched?.asar_header_sha256 !== recipe.patchedHeaderSha256) {
+    throw setupError("PM_STUDIO_BACKUP_INVALID",
+      `Compatible PM Studio backup does not match its reconstructed recipe: ${backupDir}`);
+  }
+  const inspection = inspectPmStudioApp({ appPath: backupAppPath, recipe, operations });
+  if (inspection.state !== "clean" || inspection.sourceVerification !== "local-content") {
+    throw setupError("PM_STUDIO_BACKUP_INVALID",
+      `Compatible PM Studio backup source verification failed: ${backupDir}`,
+      inspection.issues);
+  }
+  return recipe;
+}
+
+function compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations }) {
+  if (!fs.existsSync(backupRoot)) return null;
+  const installedAsar = fs.readFileSync(path.join(appPath, PM_STUDIO_2_9_10_RECIPE.asarPath));
+  let candidates = [];
+  const invalidCandidates = [];
+  for (const entry of fs.readdirSync(backupRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const backupDir = path.join(backupRoot, entry.name);
+    const manifestPath = path.join(backupDir, "manifest.json");
+    if (!fs.existsSync(manifestPath)) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch {
+      continue;
+    }
+    let recipe;
+    try {
+      recipe = compatibleRecipeFromManifest({ backupDir, manifest, metadata, operations });
+    } catch (error) {
+      invalidCandidates.push(error);
+      continue;
+    }
+    if (!recipe) continue;
+    const asarState = inspectAsarBuffer(installedAsar, recipe).state;
+    if (asarState === "drift") continue;
+    candidates.push({ recipe, manifest, asarState });
+  }
+  if (candidates.length > 1) {
+    let installedBundleContent;
+    try {
+      const recipe = candidates[0].recipe;
+      installedBundleContent = operations.inspectBundleContent({
+        ...appPaths(appPath, recipe),
+        recipe,
+        processRunner: operations.processRunner,
+      });
+    } catch (error) {
+      throw setupError("PM_STUDIO_BACKUP_INVALID",
+        "PM Studio compatible backup candidates could not be distinguished safely",
+        [error.message]);
+    }
+    candidates = candidates.filter(({ recipe, manifest, asarState }) => bundleContentMatches(
+      installedBundleContent,
+      asarState === "clean" ? recipe.sourceBundleContent : manifest?.patched?.bundle_content,
+    ));
+  }
+  if (candidates.length > 1) {
+    throw setupError("PM_STUDIO_UNSUPPORTED_VERSION",
+      `PM Studio ${metadata.version} build ${metadata.build} matches multiple compatible backups; no files were changed`);
+  }
+  if (candidates.length === 1) return candidates[0].recipe;
+  if (invalidCandidates.length > 0) {
+    throw setupError("PM_STUDIO_BACKUP_INVALID",
+      `PM Studio ${metadata.version} build ${metadata.build} has no matching verified compatible backup`,
+      invalidCandidates.map((error) => error?.message || String(error)));
+  }
+  return null;
+}
+
+function selectCompatibleRecipe({ appPath, backupRoot, metadata, operations }) {
+  let sourceError = null;
+  try {
+    return createCompatibleSourceRecipe({ appPath, metadata, operations });
+  } catch (error) {
+    sourceError = error;
+  }
+  try {
+    const backupRecipe = compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations });
+    if (backupRecipe) return backupRecipe;
+  } catch (error) {
+    if (error?.code === "PM_STUDIO_BACKUP_INVALID") throw error;
+    sourceError = error;
+  }
+  throw setupError("PM_STUDIO_UNSUPPORTED_VERSION",
+    `PM Studio ${metadata.version} build ${metadata.build} is not structurally compatible with the safe patch; no files were changed${sourceError?.message ? `: ${sourceError.message}` : ""}`,
+    sourceError?.message ? [sourceError.message] : undefined);
+}
+
+export function resolvePmStudioCompatibleRecipe({
+  appPath = DEFAULT_PM_STUDIO_APP_PATH,
+  home = os.homedir(),
+  backupRoot = pmStudioBackupRoot(home),
+  metadata,
+  recipes = PM_STUDIO_RECIPES,
+  operations = createPmStudioSetupOperations(),
+  inspectApp = inspectPmStudioApp,
+} = {}) {
+  if (!metadata || typeof metadata !== "object") {
+    throw new TypeError("PM Studio bundle metadata is required");
+  }
+  const staticRecipe = selectRecipe(metadata, recipes);
+  let staticInspection = null;
+  if (staticRecipe) {
+    try {
+      staticInspection = inspectApp({ appPath, recipe: staticRecipe, operations });
+    } catch {
+      // A metadata match is not an admission gate. Local structure remains authoritative.
+    }
+  }
+  try {
+    return selectCompatibleRecipe({
+      appPath,
+      backupRoot,
+      metadata,
+      operations,
+    });
+  } catch (error) {
+    if (staticInspection?.state === "drift" && error?.code === "PM_STUDIO_UNSUPPORTED_VERSION") {
+      throw setupError("PM_STUDIO_BUNDLE_DRIFT",
+        `PM Studio ${metadata.version} build ${metadata.build} differs from its known local structure; no files were changed`,
+        staticInspection.issues);
+    }
+    const staticSourceCanBeSigned = staticInspection?.state !== "clean"
+      || !staticRecipe?.patchedSigningMetadata
+      || (staticInspection?.codeSign?.displayValid === true
+        && staticInspection.codeSign.entitlementsState === "xml");
+    if (error?.code === "PM_STUDIO_UNSUPPORTED_VERSION"
+      && staticInspection?.state && staticInspection.state !== "drift"
+      && staticSourceCanBeSigned) {
+      return staticRecipe;
+    }
+    throw error;
+  }
+}
+
 function backupName(recipe) {
   const sourceHash = recipe.sourceBundleContent?.sha256 || recipe.sourceAsarSha256;
   return `${recipe.id}-${sourceHash.slice(0, 12)}`;
@@ -671,6 +913,7 @@ function backupManifest(recipe, createdAt) {
     schema_version: recipe.sourceBundleContent ? 2 : 1,
     kind: "ccdx-pm-studio-backup",
     recipe_id: recipe.id,
+    ...(recipe.compatibility ? { compatibility: recipe.compatibility } : {}),
     created_at: createdAt.toISOString(),
     app: {
       name: "PM Studio",
@@ -688,7 +931,6 @@ function backupManifest(recipe, createdAt) {
         embedded_asar_integrity: recipe.embeddedAsarIntegrity,
       },
       ...(recipe.sourceBundleContent ? { bundle_content: recipe.sourceBundleContent } : {}),
-      ...(recipe.sourceArtifact ? { artifact: recipe.sourceArtifact } : {}),
     },
     patched: {
       asar_sha256: recipe.patchedAsarSha256,
@@ -737,6 +979,7 @@ function validateBackup({ backupDir, recipe, operations }) {
   if (manifest?.schema_version !== expectedSchema
     || manifest?.kind !== "ccdx-pm-studio-backup"
     || manifest?.recipe_id !== recipe.id
+    || (recipe.compatibility && manifest?.compatibility !== recipe.compatibility)
     || manifest?.app?.bundle_identifier !== recipe.bundleIdentifier
     || manifest?.app?.version !== recipe.version
     || manifest?.app?.build !== recipe.build
@@ -748,8 +991,6 @@ function validateBackup({ backupDir, recipe, operations }) {
     || manifest?.source?.binaries?.embedded_asar_integrity !== recipe.embeddedAsarIntegrity
     || (recipe.sourceBundleContent
       && JSON.stringify(manifest?.source?.bundle_content) !== JSON.stringify(recipe.sourceBundleContent))
-    || (recipe.sourceArtifact
-      && JSON.stringify(manifest?.source?.artifact) !== JSON.stringify(recipe.sourceArtifact))
     || (manifest?.predecessor_patched !== undefined
       && !patchRecordMatches(manifest.predecessor_patched, recipe, "predecessor"))
     || (!patchRecordForState(manifest, recipe, "patched")
@@ -851,6 +1092,7 @@ export function assertPatchedBinaryRecord({
   if (recipe && (manifest?.schema_version !== expectedSchema
     || manifest?.kind !== "ccdx-pm-studio-backup"
     || manifest?.recipe_id !== recipe.id
+    || (recipe.compatibility && manifest?.compatibility !== recipe.compatibility)
     || manifest?.app?.bundle_identifier !== recipe.bundleIdentifier
     || manifest?.app?.version !== recipe.version
     || manifest?.app?.build !== recipe.build
@@ -862,9 +1104,7 @@ export function assertPatchedBinaryRecord({
       || manifest?.source?.binaries?.electron_framework_sha256 !== recipe.sourceElectronFrameworkSha256
       || manifest?.source?.binaries?.embedded_asar_integrity !== recipe.embeddedAsarIntegrity
       || JSON.stringify(manifest?.source?.bundle_content) !== JSON.stringify(recipe.sourceBundleContent)
-    ))
-    || (recipe.sourceArtifact
-      && JSON.stringify(manifest?.source?.artifact) !== JSON.stringify(recipe.sourceArtifact)))) {
+    )))) {
     throw setupError("PM_STUDIO_PATCH_RECORD_INVALID", "PM Studio patched-binary record does not match the installed patch recipe");
   }
   const record = patchRecordForState(manifest, recipe, recordState);
@@ -903,21 +1143,29 @@ function flagsWithoutAdHoc(value) {
 }
 
 function assertSigningMetadataPreserved(source, staged, recipe) {
+  const after = signingMetadata(staged.codeSign);
+  if (after.identifier !== recipe.bundleIdentifier) {
+    throw setupError("PM_STUDIO_SIGNING_METADATA_CHANGED",
+      "Ad-hoc signing did not use the PM Studio bundle identifier");
+  }
   if (recipe.patchedSigningMetadata) {
-    if (JSON.stringify(signingMetadata(staged.codeSign))
-      !== JSON.stringify(recipe.patchedSigningMetadata)) {
+    if (JSON.stringify(after) !== JSON.stringify(recipe.patchedSigningMetadata)) {
       throw setupError("PM_STUDIO_SIGNING_METADATA_CHANGED",
         "Ad-hoc signing did not produce the exact PM Studio signing metadata required by the recipe");
     }
     return;
   }
-  const before = signingMetadata(source.codeSign);
-  const after = signingMetadata(staged.codeSign);
-  before.flags = flagsWithoutAdHoc(before.flags);
-  after.flags = flagsWithoutAdHoc(after.flags);
-  if (JSON.stringify(before) !== JSON.stringify(after)) {
+  const sourceSignature = source.codeSign;
+  if (sourceSignature?.displayValid !== true) return;
+  const flagsChanged = sourceSignature.flags
+    && flagsWithoutAdHoc(sourceSignature.flags) !== flagsWithoutAdHoc(after.flags);
+  const runtimeChanged = sourceSignature.runtimeVersion
+    && sourceSignature.runtimeVersion !== after.runtime_version;
+  const entitlementsChanged = sourceSignature.entitlementsState === "xml"
+    && sourceSignature.entitlementsSha256 !== after.entitlements_sha256;
+  if (flagsChanged || runtimeChanged || entitlementsChanged) {
     throw setupError("PM_STUDIO_SIGNING_METADATA_CHANGED",
-      "Ad-hoc signing did not preserve PM Studio identifier, entitlements, flags, and runtime metadata");
+      "Ad-hoc signing did not preserve available PM Studio entitlements, flags, and runtime metadata");
   }
 }
 
@@ -950,7 +1198,7 @@ function replaceVerifiedStage({ appPath, stagePath, operations }) {
 }
 
 function recoveryMessage(backup) {
-  return `Verified backup: ${backup.backupAppPath}; manifest: ${backup.manifestPath}. Quit PM Studio, confirm the installed version/build still match, then restore only this version-matched backup or reinstall the official App.`;
+  return `Verified backup: ${backup.backupAppPath}; manifest: ${backup.manifestPath}. Quit PM Studio, confirm the installed version/build still match, then restore only this version-matched backup or reinstall PM Studio.`;
 }
 
 export async function runPmStudioSetup({
@@ -963,6 +1211,7 @@ export async function runPmStudioSetup({
   logger = (line) => console.log(line),
 } = {}) {
   const operations = createPmStudioSetupOperations(operationOverrides);
+  return operations.withSetupLock({ appPath }, async () => {
   const messages = [];
   const emit = (message) => {
     messages.push(message);
@@ -980,11 +1229,13 @@ export async function runPmStudioSetup({
     processRunner: operations.processRunner,
   };
   const metadata = operations.readBundleMetadata(genericPaths);
-  const recipe = selectRecipe(metadata, recipes);
-  if (!recipe) {
-    throw setupError("PM_STUDIO_UNSUPPORTED_VERSION",
-      `PM Studio ${metadata.version} build ${metadata.build} is not supported; no files were changed`);
-  }
+  const recipe = resolvePmStudioCompatibleRecipe({
+    appPath,
+    backupRoot,
+    metadata,
+    recipes,
+    operations,
+  });
 
   const source = inspectPmStudioApp({ appPath, recipe, operations });
   const finalBackupDir = path.join(backupRoot, backupName(recipe));
@@ -1008,10 +1259,6 @@ export async function runPmStudioSetup({
       `PM Studio ${recipe.version} build ${recipe.build} does not match the clean, current split-origin, predecessor, or legacy recipe; no files were changed`, source.issues);
   }
 
-  if (source.sourceVerification === "exact-bundle-content") {
-    emit(`[WARN] macOS rejected the vendor signature; setup accepted only the exact PM Studio ${recipe.version} official bundle content fingerprint.`);
-  }
-
   const backupExists = fs.existsSync(finalBackupDir);
   let verifiedBackup = null;
   if (migratingExistingPatch) {
@@ -1032,7 +1279,7 @@ export async function runPmStudioSetup({
   }
   assertSpace({ appPath, backupRoot, backupExists, operations });
 
-  emit("[WARN] PM Studio's vendor signature will be replaced with an ad-hoc signature; an official update or reinstall may overwrite this patch.");
+  emit("[WARN] PM Studio will be ad-hoc signed after patching; an update or reinstall may overwrite this patch.");
   const backup = verifiedBackup || ensureBackup({ appPath, backupRoot, recipe, operations });
   const stagePath = path.join(path.dirname(appPath), `.${path.basename(appPath)}.ccdx-stage-${operations.uuid()}`);
   let preserveStage = false;
@@ -1059,7 +1306,12 @@ export async function runPmStudioSetup({
       hash: recipe.patchedHeaderSha256,
       processRunner: operations.processRunner,
     });
-    operations.signApp({ appPath: stagePath, recipe, processRunner: operations.processRunner });
+    operations.signApp({
+      appPath: stagePath,
+      recipe,
+      source: stagedSource,
+      processRunner: operations.processRunner,
+    });
 
     const staged = inspectPmStudioApp({ appPath: stagePath, recipe, operations });
     if (staged.state !== "patched") {
@@ -1140,4 +1392,5 @@ export async function runPmStudioSetup({
   } finally {
     if (!preserveStage && fs.existsSync(stagePath)) operations.removePath({ target: stagePath });
   }
+  });
 }

package/src/pm-studio-status.mjs

@@ -14,6 +14,7 @@ import {
   PM_STUDIO_CLAUDE_AUTH_COMMAND,
   pmStudioBackupRoot,
   pmStudioPatchManifestPath,
+  resolvePmStudioCompatibleRecipe,
 } from "./pm-studio-setup.mjs";
 import { readAdapterStatus } from "./cli-status.mjs";
 import {
@@ -39,12 +40,6 @@ const PM_RELAY_ROUTE_NAMES = Object.freeze([
   "pm_chat_completions",
 ]);
 
-function selectRecipe(metadata, recipes) {
-  return recipes.find((recipe) => recipe.version === String(metadata.version)
-    && recipe.build === String(metadata.build)
-    && recipe.bundleIdentifier === String(metadata.bundleIdentifier));
-}
-
 function safeMessage(error) {
   return String(error?.message || "inspection failed").replace(/\s+/g, " ").trim();
 }
@@ -146,6 +141,7 @@ export async function inspectPmStudioStatus({
   existsSync = fs.existsSync,
   inspectApp = inspectPmStudioApp,
   verifyPatchRecord = assertPatchedBinaryRecord,
+  resolveCompatibleRecipe = resolvePmStudioCompatibleRecipe,
   readClaudeCredentials = readAuthProfileCredentials,
   checkRunningAdapterFn = checkRunningAdapter,
   readAdapterStatusFn = readAdapterStatus,
@@ -167,7 +163,21 @@ export async function inspectPmStudioStatus({
         build: String(metadata.build),
         bundleIdentifier: String(metadata.bundleIdentifier),
       };
-      const recipe = selectRecipe(normalized, recipes);
+      let recipe = null;
+      let compatibilityError = null;
+      try {
+        recipe = resolveCompatibleRecipe({
+          appPath,
+          home,
+          backupRoot,
+          metadata: normalized,
+          recipes,
+          operations,
+          inspectApp,
+        });
+      } catch (error) {
+        compatibilityError = error;
+      }
       if (recipe) {
         app = { ...inspectApp({ appPath, recipe, operations }), recipe: recipe.id };
         if (["patched", "predecessor"].includes(app.state)) {
@@ -189,7 +199,12 @@ export async function inspectPmStudioStatus({
           }
         }
       } else {
-        app = { state: "unsupported", metadata: normalized, issues: [], recipe: "" };
+        app = {
+          state: "unsupported",
+          metadata: normalized,
+          issues: compatibilityError ? [safeMessage(compatibilityError)] : [],
+          recipe: "",
+        };
       }
     } catch (error) {
       app = { state: "error", metadata: null, issues: [safeMessage(error)], recipe: "" };
@@ -250,8 +265,8 @@ function appStatusItem(result, commandName) {
   if (app.state === "legacy") {
     return { kind: "err", component: "App patch", detail: `${version}; legacy global-origin patch`, message: `PM Studio ${version} has a legacy global-origin patch; run ${commandName} pms setup to migrate` };
   }
-  if (app.state === "clean") return { kind: "warn", component: "App patch", detail: `${version}; supported, not patched`, message: `PM Studio ${version} is supported but not patched; run ${commandName} pms setup` };
-  if (app.state === "unsupported") return { kind: "err", component: "App patch", detail: `${version}; unsupported version`, message: `PM Studio ${version} has no exact patch recipe; no files will be changed` };
+  if (app.state === "clean") return { kind: "warn", component: "App patch", detail: `${version}; compatible structure, not patched`, message: `PM Studio ${version} has a compatible local patch structure but is not patched; run ${commandName} pms setup` };
+  if (app.state === "unsupported") return { kind: "err", component: "App patch", detail: `${version}; structure incompatible`, message: `PM Studio ${version} does not expose one uniquely compatible patch structure; no files will be changed` };
   if (app.state === "drift" && app.patchRecipeMatched) {
     return { kind: "err", component: "App patch", detail: `${version}; patch record drift`, message: `PM Studio ${version} matches the patch recipe, but its installed patch record is not verified: ${app.issues.join("; ")}` };
   }