@rightkit/release 0.2.164 → 0.2.172

package/development-signing.mjs

@@ -68,8 +68,31 @@ function decodeProfile(file, context) {
   }
 }
 
+/** The only supported value of `install.signing` / RIGHTKIT_DEV_SIGNING: ad hoc signing on an ephemeral GitHub-hosted runner. */
+export const CI_ADHOC_SIGNING = "ci-adhoc";
+/** Environment spelling of the same opt-in (the generated rust-hybrid candidate and dev-qualification jobs set it). */
+export const CI_ADHOC_SIGNING_ENV = "RIGHTKIT_DEV_SIGNING";
+
+/**
+ * Explicit opt-in to CI-only ad hoc signing: `development.targets.mac.install.signing: "ci-adhoc"` or
+ * RIGHTKIT_DEV_SIGNING=ci-adhoc. Never inferred from a missing identity. Any other value is refused so a typo cannot silently
+ * fall back to the default; the opt-in is refused on every host that is not a GitHub-hosted Actions runner.
+ */
+export function requestedCiAdhocSigning({ descriptor = {}, env = process.env }) {
+  const fromConfig = descriptor.signing;
+  const fromEnv = typeof env[CI_ADHOC_SIGNING_ENV] === "string" ? env[CI_ADHOC_SIGNING_ENV].trim() : "";
+  for (const [value, source] of [[fromConfig, "install.signing"], [fromEnv || undefined, CI_ADHOC_SIGNING_ENV]]) {
+    if (value !== undefined && value !== CI_ADHOC_SIGNING) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_MODE_INVALID", `${source} must be ${JSON.stringify(CI_ADHOC_SIGNING)} or unset, got ${JSON.stringify(value)}.`);
+  }
+  if (fromConfig === undefined && !fromEnv) return false;
+  const onRunner = env.GITHUB_ACTIONS === "true" && env.CI === "true" && env.RUNNER_ENVIRONMENT === "github-hosted";
+  if (!onRunner) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CI_ADHOC_REFUSED", `Ad hoc development signing (${CI_ADHOC_SIGNING}) is allowed only on a GitHub-hosted Actions runner (GITHUB_ACTIONS=true, CI=true, RUNNER_ENVIRONMENT=github-hosted). Ad hoc signatures change on every build, so on a developer machine they re-trigger macOS TCC prompts; use a Keychain Developer ID identity there.`);
+  return true;
+}
+
 export function resolveMacosDevelopmentSigning({ root, bundle, descriptor = {}, config = {}, env = process.env, run = spawnSync }) {
   const context = { root, env, run };
+  const ciAdhoc = requestedCiAdhocSigning({ descriptor, env });
   const tauriRoot = path.dirname(path.resolve(root, descriptor.manifestPath ?? "src-tauri/Cargo.toml"));
   let mac = {};
   for (const name of ["tauri.conf.json", "tauri.macos.conf.json"]) {
@@ -79,6 +102,8 @@ export function resolveMacosDevelopmentSigning({ root, bundle, descriptor = {},
   const sign = config.targets?.mac?.sign ?? {};
   const entitlements = sign.entitlements ? path.resolve(root, sign.entitlements) : mac.entitlements ? path.resolve(tauriRoot, mac.entitlements) : null;
   if (entitlements && !existsSync(entitlements)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_CONFIG_INVALID", `Configured entitlements file is missing: ${entitlements}`);
+  // CI-only ad hoc: no Keychain, no provisioning profile (a profile authorizes restricted entitlements that an ad hoc signature cannot carry).
+  if (ciAdhoc) return { identity: "-", certificateSha1: "-", teamIdentifier: null, entitlements, provisioningProfile: null, mode: CI_ADHOC_SIGNING, adhoc: true };
   const tauriProfile = mac.provisioningProfile ?? mac.files?.["embedded.provisionprofile"] ?? mac.files?.["/embedded.provisionprofile"];
   const configuredProfile = sign.provisioningProfile ? path.resolve(root, sign.provisioningProfile) : tauriProfile ? path.resolve(tauriRoot, tauriProfile) : null;
   const embedded = path.join(bundle, "Contents", "embedded.provisionprofile");
@@ -95,7 +120,7 @@ export function resolveMacosDevelopmentSigning({ root, bundle, descriptor = {},
   const found = checked("security", ["find-identity", "-v", "-p", "codesigning"], context, "DEV_MAC_SIGNING_IDENTITY_MISSING", expected);
   const identities = [...String(found.stdout ?? "").matchAll(/([A-Fa-f0-9]{40})\s+"([^"\n]+)"/g)].map((match) => ({ sha1: match[1].toUpperCase(), name: match[2] }));
   const matchesRequest = (item, requested) => item.name === requested || item.sha1 === requested?.toUpperCase();
-  const profiled = (info) => identities.filter((item) => info.certificates.some((cert) => cert.sha1 === item.sha1) && /^(Apple Development|Mac Developer|Developer ID Application):/.test(item.name));
+  const profiled = (info) => identities.filter((item) => info.certificates.some((cert) => cert.sha1 === item.sha1) && /^Developer ID Application:/.test(item.name));
   // A configured profile can go stale when its certificate is renewed: prefer a sibling profile for the
   // same app identifier that authorizes a certificate whose private key is in this Keychain.
   if (profileInfo && !profiled(profileInfo).length && configuredProfile) {
@@ -110,6 +135,9 @@ export function resolveMacosDevelopmentSigning({ root, bundle, descriptor = {},
     : identities.filter((item) => item.name.startsWith("Developer ID Application:") && item.name.endsWith(`(${releaseTeam})`));
   if (requestedIdentity) candidates = candidates.filter((item) => matchesRequest(item, requestedIdentity));
   else if (profileInfo && configuredIdentity && candidates.some((item) => matchesRequest(item, configuredIdentity))) candidates = candidates.filter((item) => matchesRequest(item, configuredIdentity));
+  // One identity for dev and release (no new id): Developer ID Application only. An Apple Development or Mac Developer certificate gives a different
+  // designated requirement, so macOS would drop the app's privacy grants when dev and release alternate. Never a fallback.
+  if (!candidates.length) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_DEVELOPER_ID_REQUIRED", `Signing identity ${JSON.stringify(expected)}: no Developer ID Application identity with its private key is in Keychain${profileInfo ? ` (and authorized by ${provisioningProfile})` : ""}. Dev builds sign with the same Developer ID Application identity as release. Install that identity${profileInfo ? ", and use a Developer ID provisioning profile (not Apple Development) if the app's entitlements need one" : ""}; there is no fallback to Apple Development or ad hoc signing.`, { identity: expected });
   if (candidates.length !== 1) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_IDENTITY_MISSING", `Signing identity ${JSON.stringify(expected)}: ${candidates.length ? "multiple matching identities" : "no valid matching identity/private key"} in Keychain${provisioningProfile ? ` for ${provisioningProfile}` : ""}. ${candidates.length ? "Set APPLE_SIGNING_IDENTITY or APPLE_DEVELOPER_ID to one matching identity." : "Confirm the profile-authorized certificate and its private key are available in Keychain Access in a logged-in GUI session."}`, { identity: expected });
   return { identity: candidates[0].name, certificateSha1: candidates[0].sha1, teamIdentifier: profileInfo?.team ?? releaseTeam, entitlements, provisioningProfile };
 }
@@ -153,6 +181,20 @@ export function signMacosDevelopmentBundle(options) {
       .filter((name) => name.startsWith(`${path.basename(entitlements, path.extname(entitlements))}-`) && name.endsWith(".plist"))
       .map((name) => ({ file: path.join(path.dirname(entitlements), name), suffix: path.basename(name, ".plist").slice(path.basename(entitlements, path.extname(entitlements)).length + 1).toLowerCase() }))
       .sort((a, b) => b.suffix.length - a.suffix.length) : [];
+    // Ad hoc signatures cannot carry profile-restricted entitlements (iCloud, keychain-access-groups, application-identifier):
+    // AMFI would kill the app at launch. Ad hoc mode therefore applies only the hardened-runtime relaxations and audio input.
+    const safeFiles = new Map();
+    const entitlementFile = (file) => {
+      if (!signing.adhoc) return file;
+      if (!safeFiles.has(file)) {
+        const safe = Object.fromEntries(Object.entries(readPlist(file, context)).filter(([key]) => key.startsWith("com.apple.security.cs.") || key === "com.apple.security.device.audio-input"));
+        const out = path.join(scratch, `adhoc-${safeFiles.size}.plist`);
+        writeFileSync(out, JSON.stringify(safe));
+        checked("plutil", ["-convert", "xml1", out], context, "DEV_MAC_SIGNING_CONFIG_INVALID", identity);
+        safeFiles.set(file, out);
+      }
+      return safeFiles.get(file);
+    };
     const targets = [];
     const bundleExecutables = new Set();
     const visit = (directory, isBundle = false) => {
@@ -181,8 +223,8 @@ export function signMacosDevelopmentBundle(options) {
       const profiledHelper = target.info && existsSync(path.join(target.file, "Contents/embedded.provisionprofile")) && target.info.CFBundleIdentifier === appInfo.CFBundleIdentifier;
       if (profiledHelper && !parent && provisioningProfile) copyFileSync(embedded, path.join(target.file, "Contents/embedded.provisionprofile"));
       const variant = !parent && entitlementVariants.find((item) => path.basename(target.file).replace(/\.(app|xpc|appex|bundle)$/, "").toLowerCase().endsWith(item.suffix));
-      if (variant) args.push("--entitlements", variant.file);
-      else if (entitlements && (parent || profiledHelper)) args.push("--entitlements", entitlements);
+      if (variant) args.push("--entitlements", entitlementFile(variant.file));
+      else if (entitlements && (parent || profiledHelper)) args.push("--entitlements", entitlementFile(entitlements));
       else {
         const existing = run("codesign", ["--display", "--entitlements", ":-", target.file], captureOptions(root, env));
         if (existing.status === 0 && /<plist|<dict/.test(String(existing.stdout ?? ""))) args.push("--preserve-metadata=entitlements");
@@ -194,8 +236,33 @@ export function signMacosDevelopmentBundle(options) {
     for (const [index, args] of commands.entries()) checked("codesign", args, { ...context, run: () => signed[index] }, "DEV_MAC_SIGNING_FAILED", identity);
     checked("codesign", ["--verify", "--strict", "--deep", bundle], context, "DEV_MAC_SIGNATURE_INVALID", identity);
     const details = output(checked("codesign", ["--display", "--verbose=4", bundle], context, "DEV_MAC_SIGNATURE_INVALID", identity));
+    if (signing.adhoc) {
+      // No TeamIdentifier or identity-based designated requirement to check: an ephemeral runner has no TCC state to keep stable.
+      if (!/^Signature=adhoc$/m.test(details)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNATURE_INVALID", `CI ad hoc signing: expected Signature=adhoc on ${bundle}. Refusing dev installation.`, { identity });
+      return { ...signing, provisioningProfile: null, verified: "strict-deep", designatedRequirement: null, signedTargets: ordered.length, releaseArtifact: false,
+        receipt: { signing: CI_ADHOC_SIGNING, signature: "adhoc", releaseArtifact: false, note: "Ad hoc signed on a GitHub-hosted CI runner for candidate qualification only; never a release artifact. Release signing happens in the protected sign job." } };
+    }
     const actualTeam = /^TeamIdentifier=(.+)$/m.exec(details)?.[1]?.trim();
     if (actualTeam !== teamIdentifier || /^Signature=adhoc$/m.test(details)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_TEAM_MISMATCH", `Signing identity ${JSON.stringify(identity)}: expected TeamIdentifier=${teamIdentifier}, found ${actualTeam ?? "missing"}. Refusing dev installation.`, { identity, expectedTeam: teamIdentifier, actualTeam });
-    return { ...signing, provisioningProfile: provisioningProfile ? embedded : null, verified: "strict-deep", signedTargets: ordered.length };
+    // Fail closed unless the designated requirement is identity-based: an ad hoc or cdhash requirement changes every build, so macOS TCC re-prompts.
+    const requirement = output(checked("codesign", ["--display", "-r-", bundle], context, "DEV_MAC_SIGNATURE_INVALID", identity));
+    const designated = /^designated => (.+)$/m.exec(requirement)?.[1]?.trim();
+    if (!designated || /\bcdhash\b/.test(designated)) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_UNSTABLE_REQUIREMENT", `Signing identity ${JSON.stringify(identity)}: designated requirement ${designated ? JSON.stringify(designated) : "is missing"} is not stable across rebuilds (cdhash-bound). Refusing dev installation.`, { identity, designatedRequirement: designated });
+    return { ...signing, provisioningProfile: provisioningProfile ? embedded : null, verified: "strict-deep", designatedRequirement: designated, signedTargets: ordered.length };
   } finally { rmSync(scratch, { recursive: true, force: true }); }
 }
+
+/**
+ * One stable designated requirement across dev installs. macOS keys privacy grants (TCC) to the code identity, so a dev
+ * build whose designated requirement differs from the installed copy's would silently drop every grant. Fails with
+ * DEV_MAC_SIGNING_REQUIREMENT_CHANGED. An installed copy that is unsigned, ad hoc or cdhash-bound has no stable
+ * grants to keep, so it does not block the move to the stable identity.
+ */
+export function assertStableDesignatedRequirement({ root, installed, expected, env = process.env, run = spawnSync }) {
+  const result = run("codesign", ["--display", "-r-", installed], captureOptions(root, env));
+  if (result.error || result.status !== 0) return null;
+  const current = /^designated => (.+)$/m.exec(output(result))?.[1]?.trim();
+  if (!current || /\bcdhash\b/.test(current)) return null;
+  if (current !== expected) throw new MacosDevelopmentSigningError("DEV_MAC_SIGNING_REQUIREMENT_CHANGED", `Installed ${installed} has designated requirement ${JSON.stringify(current)} but this dev build is signed with ${JSON.stringify(expected)}. Installing it would reset the app's macOS privacy grants. Sign with the same identity as the installed copy (the one stable Developer ID) or remove the installed app deliberately.`, { designatedRequirement: expected, installedRequirement: current });
+  return current;
+}

package/development.mjs

@@ -1,7 +1,7 @@
 import { discoverBrokerSocket, resolveManagedRoots } from './managed-roots.mjs';
 import { spawnSync } from "./background-process.mjs";
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, lstatSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
@@ -9,10 +9,22 @@ import { assertReleaseExecutionAllowed } from "./execution-policy.mjs";
 import { acquireManagedRunLease, managedRuntimeClient, managedRuntimeCommand, runCargoSync } from "./managed-cargo.mjs";
 import { BUNDLE_MARKERS, bundleMarkerBuffer, readTauriBundleMarkers } from "./tauri-bundle-marker.mjs";
 import { installPortableDevelopment } from "./portable-development.mjs";
-import { readBundleExecutable, signMacosDevelopmentBundle } from "./development-signing.mjs";
+import { previousPathOf, stagingPathOf, swapInPlace } from "./in-place-install.mjs";
+import { stageDevelopmentBinaries, validateStageEntries } from "./stage-binary.mjs";
+import { assertStableDesignatedRequirement, readBundleExecutable, requestedCiAdhocSigning, signMacosDevelopmentBundle } from "./development-signing.mjs";
 import { macosCodesignEnvironment } from "./codesign-environment.mjs";
+import { androidDevelopmentNdkCommand, androidDevelopmentSerial, installAndroidDevelopment, validateAndroidDevelopment } from "./android-dev.mjs";
 
-export const DEVELOPMENT_PROFILE = "release-iterate";
+// One standard Cargo profile for every app (templates/cargo-profiles.toml): Cargo's built-in `dev`.
+// `--profile dev` is valid and no flag also means dev.
+export const DEVELOPMENT_PROFILE = "dev";
+// Cargo writes the `dev` (and `test`) profile to target/<triple>/debug, never .../dev; `bench` goes to release.
+// Every path built from a profile name must go through this.
+export function cargoProfileDirectory(profile) {
+  if (profile === "dev" || profile === "test") return "debug";
+  if (profile === "bench") return "release";
+  return profile;
+}
 const RELEASE_ONLY_APPLE_ENV = ["APPLE_ID", "APPLE_PASSWORD", "APPLE_API_KEY", "APPLE_API_ISSUER", "APPLE_API_KEY_PATH", "APPLE_CERTIFICATE", "APPLE_CERTIFICATE_PASSWORD"];
 
 export function developmentEnvironment(env = process.env) {
@@ -26,6 +38,8 @@ export function developmentEnvironment(env = process.env) {
   };
   for (const key of RELEASE_ONLY_APPLE_ENV) delete result[key];
   delete result.CARGO_INCREMENTAL;
+  // A dev build is debug-signed: a release signing-properties path never reaches it.
+  delete result.RIGHTKIT_ANDROID_SIGNING_PROPERTIES;
   const client = managedRuntimeClient(result);
   if (client) {
     const { agentBin } = resolveManagedRoots({ env: result });
@@ -41,7 +55,7 @@ export function developmentEnvironment(env = process.env) {
   return result;
 }
 
-export function validateDevelopmentConfig(config, platform) {
+export function validateDevelopmentConfig(config, platform, { root = process.cwd() } = {}) {
   const target = config?.development?.targets?.[platform];
   if (!target || !Array.isArray(target.build) || target.build.length === 0) throw new Error(`development.targets.${platform}.build must be a non-empty command array`);
   for (const [index, command] of target.build.entries()) validateCommand(command, `development.targets.${platform}.build[${index}]`);
@@ -56,28 +70,42 @@ export function validateDevelopmentConfig(config, platform) {
     for (const key of ["sourceDirectory", "entrypoint"]) {
       if (typeof descriptor[key] !== "string" || !descriptor[key] || path.isAbsolute(descriptor[key]) || path.win32.isAbsolute(descriptor[key]) || descriptor[key].split(/[\\/]/).includes("..")) throw new Error(`portable development ${key} must be a contained relative path`);
     }
+  } else if (target.install?.kind === "adb") {
+    if (platform !== "android") throw new Error("the adb development installer is for --platform android");
   } else if (target.install) throw new Error(`unsupported development installer kind: ${target.install.kind}`);
+  validateStageEntries(target.stage, `development.targets.${platform}.stage`);
+  if (platform === "android") return { ...target, ...validateAndroidDevelopment(target, { root }) };
   return target;
 }
 
 export function runDevelopment({ root, platform, config, buildOnly = false, dryRun = false, env = process.env, run = spawnSync,
-  codesignEnvironment = macosCodesignEnvironment }) {
-  if (!new Set(["win", "mac"]).has(platform)) throw new Error("--platform must be win or mac");
+  codesignEnvironment = macosCodesignEnvironment, serial }) {
+  if (!new Set(["win", "mac", "android"]).has(platform)) throw new Error("--platform must be win, mac or android");
   assertNativeDevelopmentHost(platform);
-  const target = validateDevelopmentConfig(config, platform);
+  const target = validateDevelopmentConfig(config, platform, { root });
   const repoRoot = git(root, ["rev-parse", "--show-toplevel"]);
   assertPrimaryReleaseCheckout(repoRoot, env);
-  if (dryRun) return { built: false, installed: false, plan: { build: target.build, install: buildOnly ? null : target.install ?? null, profile: DEVELOPMENT_PROFILE } };
+  if (dryRun) return { built: false, installed: false, plan: { ...(target.ndk ? { ndk: androidDevelopmentNdkCommand(target.ndk) } : {}), build: target.build, install: buildOnly ? null : target.install ?? null, profile: DEVELOPMENT_PROFILE } };
   assertReleaseExecutionAllowed({ cwd: repoRoot, environment: env, command: `right-release dev --platform ${platform}` });
+  // Refuse an invalid or off-CI ad hoc opt-in before the (long) build, not after it.
+  if (!buildOnly && platform === "mac" && target.install?.kind === "tauri") requestedCiAdhocSigning({ descriptor: target.install, env });
+  // Android: the device serial is required, so a missing one is refused before the (long) build too.
+  if (!buildOnly && platform === "android" && target.install) androidDevelopmentSerial({ descriptor: target.install, serial, env });
   const childEnv = codesignEnvironment(developmentEnvironment(env));
   // One lease spans every managed request this run makes, so a broker cutover cannot land between them.
   const lease = acquireManagedRunLease({ command: `right-release dev --platform ${platform}`, env });
   try {
     const startedMs = Date.now();
+    // Android: cargo-ndk (Cargo dev profile) fills the generated jniLibs, then the Gradle debug build packages it.
+    if (target.ndk) { rmSync(target.ndk.jniLibs, { recursive: true, force: true }); execute(androidDevelopmentNdkCommand(target.ndk), { root, env: childEnv, dryRun, run, label: "native build" }); }
     for (const command of target.build) execute(command, { root, env: childEnv, dryRun, run, label: "build" });
-    if (buildOnly || !target.install) return { built: true, installed: false };
-    const signing = install(target.install, { root, platform, config, env: childEnv, run, sinceMs: startedMs });
-    return { built: true, installed: true, ...(platform === "mac" && target.install.kind === "tauri" ? { signing } : {}) };
+    // Dev and QA binaries run from one stable staged path, copied in place (<name>.previous kept), never from the
+    // broker's per-generation target folder or a hashed dev-targets folder.
+    const staged = target.stage?.length ? stageDevelopmentBinaries(target.stage, { root, platform: platform === "win" ? "win32" : process.platform }) : [];
+    for (const file of staged) console.log(`right-release dev: staged ${file}`);
+    if (buildOnly || !target.install) return { built: true, installed: false, ...(staged.length ? { staged } : {}) };
+    const signing = install(target.install, { root, platform, config, env: childEnv, run, sinceMs: startedMs, serial });
+    return { built: true, installed: true, ...(staged.length ? { staged } : {}), ...(platform === "mac" && target.install.kind === "tauri" ? { signing } : {}) };
   } finally { lease.release(); }
 }
 
@@ -85,7 +113,8 @@ export function assertNativeDevelopmentHost(platform, host = process.platform) {
   if ((platform === "win" && host !== "win32") || (platform === "mac" && host !== "darwin")) throw new Error(`development target ${platform} requires its native host`);
 }
 
-function install(descriptor, { root, platform, config, env, run, sinceMs = null }) {
+function install(descriptor, { root, platform, config, env, run, sinceMs = null, serial }) {
+  if (descriptor.kind === "adb") return installAndroidDevelopment(descriptor, { root, env, run, serial });
   if (descriptor.kind === "command") return execute(descriptor, { root, env, run, label: "install" });
   if (descriptor.kind === "portable") return installPortableDevelopment(descriptor, { root, platform: platform === "win" ? "win32" : "darwin", env });
   if (platform === "win") {
@@ -97,6 +126,9 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null
     // was running, pass /R so the installer relaunches it as the user (RunAsUser, outside this process tree).
     const running = isWindowsProcessRunning(path.basename(descriptor.expectedInstalledPath), { run });
     if (running) console.log(`right-release dev: ${descriptor.productName} is running; the installer will close it and relaunch it`);
+    // The silent installer updates the fixed path in place. Keep the copy it replaces once, as <exe>.previous (never run).
+    const installedBefore = path.resolve(root, descriptor.expectedInstalledPath);
+    if (existsSync(installedBefore) && statSync(installedBefore).isFile()) copyFileSync(installedBefore, previousPathOf(installedBefore));
     const result = run(app, windowsInstallerArguments({ running }), { cwd: root, env, stdio: "inherit", windowsHide: true, shell: false });
     if (result.status !== 0) throw new Error(`development installer failed (${result.status}): ${app}`);
     const installed = path.resolve(root, descriptor.expectedInstalledPath);
@@ -104,23 +136,27 @@ function install(descriptor, { root, platform, config, env, run, sinceMs = null
     return;
   }
   const app = resolveTauriArtifact(descriptor, { root, platform, env });
-  const destination = path.resolve(descriptor.destination ?? path.join("/Applications", path.basename(app)));
-  const destinationRoot = path.dirname(destination);
-  mkdirSync(destinationRoot, { recursive: true });
-  const staging = `${destination}.rightkit-dev-${process.pid}`;
-  const backup = `${destination}.rightkit-backup-${process.pid}`;
+  // One fixed install path per app: macOS keys privacy grants to it. No /Applications/<name> guess.
+  if (!descriptor.destination) throw new DevelopmentInstallError("DEV_INSTALL_DESTINATION_REQUIRED", "development.targets.mac.install.destination is required: the one fixed path this app installs to (for example /Applications/<Product>.app)");
+  const destination = path.resolve(descriptor.destination);
+  mkdirSync(path.dirname(destination), { recursive: true });
+  // Fixed staging name (not per-pid): the copy is signed and verified here, then renamed into place. Nothing runs from it.
+  const staging = stagingPathOf(destination);
+  const previous = previousPathOf(destination);
   rmSync(staging, { recursive: true, force: true });
-  rmSync(backup, { recursive: true, force: true });
   cpSync(app, staging, { recursive: true, verbatimSymlinks: true });
   let signing;
   let executableName;
   try {
     signing = signMacosDevelopmentBundle({ root, bundle: staging, descriptor, config, env, run });
+    // Same identity as the installed copy, or fail: a changed designated requirement resets every privacy grant.
+    if (!signing.adhoc && existsSync(destination)) assertStableDesignatedRequirement({ root, installed: destination, expected: signing.designatedRequirement, env, run });
     executableName = readBundleExecutable(staging, { root, env, run });
   } catch (error) { rmSync(staging, { recursive: true, force: true }); throw error; }
-  swapInstalledMacosBundle({ staging, destination, backup, executableName });
+  swapInstalledMacosBundle({ staging, destination, previous, executableName });
   if (signing.provisioningProfile) signing.provisioningProfile = path.join(destination, "Contents", "embedded.provisionprofile");
-  console.log(`right-release dev: installed ${destination}; identity=${signing.identity}; TeamIdentifier=${signing.teamIdentifier}; profile=${signing.provisioningProfile ?? "none"}`);
+  if (signing.adhoc) console.log(`right-release dev: installed ${destination}; signing=ci-adhoc (ad hoc signed on a CI runner; NOT a release artifact); signature=adhoc; TeamIdentifier=none`);
+  else console.log(`right-release dev: installed ${destination}; identity=${signing.identity}; TeamIdentifier=${signing.teamIdentifier}; profile=${signing.provisioningProfile ?? "none"}; designated=${signing.designatedRequirement}`);
   return signing;
 }
 
@@ -128,15 +164,15 @@ export class DevelopmentInstallError extends Error {
   constructor(code, message) { super(message); this.name = "DevelopmentInstallError"; this.code = code; }
 }
 
-const NODE_FS = { existsSync, readFileSync, renameSync, rmSync, statSync };
+const NODE_FS = { existsSync, lstatSync, mkdirSync, copyFileSync, readFileSync, renameSync, rmSync, statSync };
 
 /**
- * Move the signed staging bundle into place and verify it before the previous app's backup is removed: Info.plist exists and
+ * Move the signed staging bundle into place, keeping the previous app as `<destination>.previous`, and verify it: Info.plist exists and
  * the installed main executable (`executableName`, the staged CFBundleExecutable read through plutil by the caller) exists with the same SHA-256 as the staged one. Any failure removes the
- * new install, restores the backup and throws a DevelopmentInstallError (code DEV_INSTALL_VERIFICATION_FAILED,
+ * new install, renames `.previous` back and throws a DevelopmentInstallError (code DEV_INSTALL_VERIFICATION_FAILED,
  * DEV_INSTALL_EXECUTABLE_MISSING or DEV_INSTALL_EXECUTABLE_MISMATCH). `fs` is the file-system seam (tests inject it).
  */
-export function swapInstalledMacosBundle({ staging, destination, backup, executableName, fs = NODE_FS }) {
+export function swapInstalledMacosBundle({ staging, destination, previous = previousPathOf(destination), executableName, fs = NODE_FS }) {
   if (typeof executableName !== "string" || !executableName) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", "swapInstalledMacosBundle requires the staged CFBundleExecutable name");
   const executable = path.join("Contents", "MacOS", executableName);
   const digest = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
@@ -146,23 +182,18 @@ export function swapInstalledMacosBundle({ staging, destination, backup, executa
     fs.rmSync(staging, { recursive: true, force: true });
     throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `staged app has no main executable ${executable}: ${staging} (${error.message})`);
   }
-  let backedUp = false;
-  try {
-    if (fs.existsSync(destination)) { fs.renameSync(destination, backup); backedUp = true; }
-    fs.renameSync(staging, destination);
-    if (!fs.existsSync(path.join(destination, "Contents", "Info.plist"))) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", `installed app verification failed: ${destination}`);
-    const installed = path.join(destination, executable);
-    let actual;
-    try { actual = digest(installed); }
-    catch { throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `installed app verification failed: main executable ${executable} is missing in ${destination}`); }
-    if (actual !== expected) throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISMATCH", `installed app verification failed: ${executable} SHA-256 ${actual} does not match the staged ${expected}`);
-    if (backedUp) fs.rmSync(backup, { recursive: true, force: true });
-  } catch (error) {
-    fs.rmSync(destination, { recursive: true, force: true });
-    if (backedUp && fs.existsSync(backup)) fs.renameSync(backup, destination);
-    fs.rmSync(staging, { recursive: true, force: true });
-    throw error;
-  }
+  // The old app becomes `<destination>.previous` (replacing any older one) and stays there for rollback; any failure renames it back.
+  swapInPlace({
+    staging, destination, previous, fs,
+    verify: () => {
+      if (!fs.existsSync(path.join(destination, "Contents", "Info.plist"))) throw new DevelopmentInstallError("DEV_INSTALL_VERIFICATION_FAILED", `installed app verification failed: ${destination}`);
+      const installed = path.join(destination, executable);
+      let actual;
+      try { actual = digest(installed); }
+      catch { throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISSING", `installed app verification failed: main executable ${executable} is missing in ${destination}`); }
+      if (actual !== expected) throw new DevelopmentInstallError("DEV_INSTALL_EXECUTABLE_MISMATCH", `installed app verification failed: ${executable} SHA-256 ${actual} does not match the staged ${expected}`);
+    },
+  });
 }
 
 export function resolveTauriArtifact(descriptor, { root, platform, env = process.env, runCargo = runCargoSync }) {
@@ -223,7 +254,7 @@ function resolveBundleRoot(descriptor, { root, env, runCargo }) {
   let targetDirectory;
   try { targetDirectory = JSON.parse(metadata.stdout).target_directory; } catch { throw new Error("RightKit Cargo metadata returned invalid JSON"); }
   if (!targetDirectory || !path.isAbsolute(targetDirectory)) throw new Error("Cargo metadata omitted absolute target_directory");
-  return path.join(targetDirectory, descriptor.targetTriple, DEVELOPMENT_PROFILE, "bundle", platformBundleKind(descriptor));
+  return path.join(targetDirectory, descriptor.targetTriple, cargoProfileDirectory(DEVELOPMENT_PROFILE), "bundle", platformBundleKind(descriptor));
 }
 
 function platformBundleKind(descriptor) { return descriptor.targetTriple.includes("apple") ? "macos" : "nsis"; }
@@ -290,16 +321,17 @@ function resolveJavaScriptEntrypoint(candidate) {
 function git(cwd, args) { const result = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true }); if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed`); return result.stdout.trim(); }
 function inside(root, child) { const rel = path.relative(path.resolve(root), path.resolve(child)); return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)); }
 export async function main(args = process.argv.slice(2)) {
-  let platform, configPath = "right-release.config.mjs", dryRun = false, buildOnly = false;
+  let platform, configPath = "right-release.config.mjs", dryRun = false, buildOnly = false, serial;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac [--config right-release.config.mjs] [--dry-run] [--build-only]"); return; }
+    if (args[i] === "-h" || args[i] === "--help") { console.log("usage: right-release dev --platform win|mac|android [--config right-release.config.mjs] [--dry-run] [--build-only] [--serial <adb serial>]"); return; }
     if (args[i] === "--platform") platform = args[++i];
     else if (args[i] === "--config") configPath = args[++i];
     else if (args[i] === "--dry-run") dryRun = true;
     else if (args[i] === "--build-only") buildOnly = true;
+    else if (args[i] === "--serial") serial = args[++i];
     else throw new Error(`unknown dev option: ${args[i]}`);
   }
-  if (!platform) throw new Error("right-release dev requires --platform win|mac");
+  if (!platform) throw new Error("right-release dev requires --platform win|mac|android");
   const absoluteConfig = path.resolve(configPath);
   const safeEnv = developmentEnvironment(process.env);
   for (const [key, value] of Object.entries(safeEnv)) process.env[key] = value;
@@ -309,7 +341,7 @@ export async function main(args = process.argv.slice(2)) {
   if (pathKey) process.env[pathKey] = safeEnv[pathKey] ?? process.env[pathKey];
   const loaded = await import(pathToFileURL(absoluteConfig));
   const config = loaded.default ?? loaded.config ?? loaded;
-  const result = runDevelopment({ root: path.dirname(absoluteConfig), platform, config, dryRun, buildOnly });
+  const result = runDevelopment({ root: path.dirname(absoluteConfig), platform, config, dryRun, buildOnly, serial });
   if (dryRun) console.log(JSON.stringify(result.plan, null, 2));
   return result;
 }

package/direct-bootstrap.mjs

@@ -288,13 +288,14 @@ export function renderPowerShellBootstrap({
     "$Contract = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String(" + psQuote(contractB64) + ")) | ConvertFrom-Json",
     "$AcceptedSigners = @{}; $Contract.acceptedManifestSigners.PSObject.Properties | ForEach-Object { $AcceptedSigners[$_.Name] = $_.Value }",
     "$InstallRoot = Join-Path $env:LOCALAPPDATA " + psQuote(installRootSubdir),
-    "$VersionsRoot = Join-Path $InstallRoot 'versions'",
+    // In place at one fixed path: no versions/ folder, no per-version, per-digest or per-run directory, no junction.
+    // `current` is the real install; `current.staging` is written and verified but never run; `current.previous` is the one rollback copy.
     "$Current = Join-Path $InstallRoot 'current'",
-    "$PreviousLink = Join-Path $InstallRoot '.current-previous'",
-    "$NextLink = Join-Path $InstallRoot '.current-next'",
+    "$Staging = Join-Path $InstallRoot 'current.staging'",
+    "$Previous = Join-Path $InstallRoot 'current.previous'",
     "$Journal = Join-Path $InstallRoot 'integration-journal.json'",
     "function Expand-BootstrapArgs($Values, $ActiveVersionRoot, $ActiveVersion) { foreach ($Value in $Values) { ([string]$Value).Replace('{current}', $Current).Replace('{installRoot}', $InstallRoot).Replace('{versionRoot}', $ActiveVersionRoot).Replace('{version}', $ActiveVersion) } }",
-    "function Remove-StableJunction([string]$Path) { $Item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue; if ($null -eq $Item) { return }; if ($Item.LinkType -ne 'Junction') { throw ('Stable pointer path is not a junction: ' + $Path) }; [IO.Directory]::Delete($Path) }",
+    "function Remove-Retired([string]$Path) { $Item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue; if ($null -eq $Item) { return }; if ($Item.LinkType -eq 'Junction') { [IO.Directory]::Delete($Path) } else { Remove-Item -LiteralPath $Path -Recurse -Force } }",
     "function Resolve-HealthPath($Value, [string]$JsonPath) { $CurrentValue = $Value; foreach ($Segment in $JsonPath.Split('.')) { if ($Segment -match '^\\d+$') { $Index = [int]$Segment; if ($null -eq $CurrentValue -or $Index -ge @($CurrentValue).Count) { throw ('Health path is missing: ' + $JsonPath) }; $CurrentValue = @($CurrentValue)[$Index] } else { $Property = $CurrentValue.PSObject.Properties[$Segment]; if ($null -eq $Property) { throw ('Health path is missing: ' + $JsonPath) }; $CurrentValue = $Property.Value } }; return $CurrentValue }",
     "function Assert-Health($Health, [string]$ActiveVersion) { foreach ($Assertion in $Contract.healthAssertions) { $Actual = Resolve-HealthPath $Health ([string]$Assertion.path); if ($Assertion.PSObject.Properties.Name -contains 'equals') { $Expected = $Assertion.equals; if ($Expected -is [string]) { $Expected = $Expected.Replace('{version}', $ActiveVersion).Replace('{current}', $Current).Replace('{installRoot}', $InstallRoot) }; if ($Actual -ne $Expected) { throw ('Health assertion failed: ' + $Assertion.path) } } elseif ($Assertion.nonempty -eq $true) { if ($null -eq $Actual -or ([string]$Actual).Trim().Length -eq 0) { throw ('Health assertion failed: ' + $Assertion.path) } } elseif (@($Actual).Count -lt [int]$Assertion.minCount) { throw ('Health assertion failed: ' + $Assertion.path) } } }",
     "function Resolve-PriorVersion($PriorExePath, $PriorLeaf) { if ($PriorExePath -and (Test-Path -LiteralPath $PriorExePath -PathType Leaf)) { $Info = (Get-Item -LiteralPath $PriorExePath).VersionInfo; $Candidate = [string]$Info.ProductVersion; if ([string]::IsNullOrWhiteSpace($Candidate)) { $Candidate = [string]$Info.FileVersion }; $Match = [regex]::Match($Candidate, '(\\d+\\.\\d+\\.\\d+)'); if ($Match.Success) { return $Match.Groups[1].Value } }; if ($PriorLeaf) { $LeafMatch = [regex]::Match([string]$PriorLeaf, '^(\\d+\\.\\d+\\.\\d+)(?:-|$)'); if ($LeafMatch.Success) { return $LeafMatch.Groups[1].Value } }; return $null }",
@@ -347,7 +348,7 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
   return $Stdout
 }`,
     ...(allowLocalReleaseRoot ? [
-      "New-Item -ItemType Directory -Force -Path $VersionsRoot | Out-Null",
+      "New-Item -ItemType Directory -Force -Path $InstallRoot | Out-Null",
       "$LocalReleaseRoot = $null; if ($ReleaseRoot) { $LocalReleaseRoot = [IO.Path]::GetFullPath($ReleaseRoot); if (-not (Test-Path -LiteralPath $LocalReleaseRoot -PathType Container)) { throw 'Local release root is missing' } }",
       "if (-not $Version -and -not $LocalReleaseRoot) { $Version = ((Invoke-RestMethod " + psQuote("https://api.github.com/repos/" + repository + "/releases/latest") + ").tag_name -replace '^v','') }",
       "if ($Version -and $Version -notmatch '^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$') { throw 'Invalid stable release version' }",
@@ -363,11 +364,11 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
       "Receive-ReleaseFile 'release-manifest.json' $ManifestPath",
       "Receive-ReleaseFile 'release-manifest.cat' $SignaturePath",
     ] : [
-      "New-Item -ItemType Directory -Force -Path $VersionsRoot | Out-Null",
+      "New-Item -ItemType Directory -Force -Path $InstallRoot | Out-Null",
       "if (-not $Version) { $Version = ((Invoke-RestMethod " + psQuote("https://api.github.com/repos/" + repository + "/releases/latest") + ").tag_name -replace '^v','') }",
       "if ($Version -notmatch '^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$') { throw 'Invalid stable release version' }",
-      "$PriorTarget = $null; if (Test-Path $Current) { $PriorTarget = (Get-Item $Current).Target }",
-      "$PriorVersion = if ($PriorTarget) { Resolve-PriorVersion (Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + ") (Split-Path ([string]$PriorTarget) -Leaf) } else { $null }",
+      "$PriorTarget = $null; if (Test-Path $Current) { $PriorTarget = $Current }",
+      "$PriorVersion = if ($PriorTarget) { Resolve-PriorVersion (Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + ") $null } else { $null }",
       "if ($PriorVersion -and -not $AllowDowngrade -and ([version]$Version -lt [version]$PriorVersion)) { throw 'Downgrade requires -AllowDowngrade' }",
       "$ReleaseBase = " + psQuote("https://github.com/" + repository + "/releases/download/v") + " + $Version",
       "$Work = Join-Path ([IO.Path]::GetTempPath()) (" + psQuote(product + "-install-") + " + [guid]::NewGuid())",
@@ -392,8 +393,8 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
       "if (-not $Version) { $Version = [string]$Manifest.version }",
       "if ($Version -notmatch '^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$') { throw 'Invalid stable release version' }",
       "$ReleaseBase = " + psQuote("https://github.com/" + repository + "/releases/download/v") + " + $Version",
-      "$PriorTarget = $null; if (Test-Path $Current) { $PriorTarget = (Get-Item $Current).Target }",
-      "$PriorVersion = if ($PriorTarget) { Resolve-PriorVersion (Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + ") (Split-Path ([string]$PriorTarget) -Leaf) } else { $null }",
+      "$PriorTarget = $null; if (Test-Path $Current) { $PriorTarget = $Current }",
+      "$PriorVersion = if ($PriorTarget) { Resolve-PriorVersion (Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + ") $null } else { $null }",
       "if ($PriorVersion -and -not $AllowDowngrade -and ([version]$Version -lt [version]$PriorVersion)) { throw 'Downgrade requires -AllowDowngrade' }",
     ] : []),
     "if ($Manifest.signingKeyId -ne $VerifiedKeyId -or $Manifest.signatureAlgorithm -ne 'authenticode-catalog-sha256' -or $Manifest.signatureProvider -ne 'windows-authenticode-catalog' -or $Manifest.signatureProviderVersion -ne 1) { throw 'Release manifest signer identity mismatch' }",
@@ -421,8 +422,8 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
     "$Stage = Join-Path $Work 'stage'; New-Item -ItemType Directory -Force -Path $Stage | Out-Null",
     "Add-Type -AssemblyName System.IO.Compression.FileSystem; $Zip = [IO.Compression.ZipFile]::OpenRead($Archive); try { foreach ($Entry in $Zip.Entries) { $Dest = [IO.Path]::GetFullPath((Join-Path $Stage $Entry.FullName)); if (-not $Dest.StartsWith(([IO.Path]::GetFullPath($Stage) + [IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase)) { throw 'Archive path escapes staging root' } } } finally { $Zip.Dispose() }",
     "Expand-Archive -Path $Archive -DestinationPath $Stage -Force",
-    "$VersionRoot = Join-Path $VersionsRoot ($Version + '-' + $Asset.sha256.Substring(0,12) + '-' + [guid]::NewGuid()); Move-Item $Stage $VersionRoot",
-    "$VersionExe = Join-Path $VersionRoot ($Asset.executablePath -replace '/', [IO.Path]::DirectorySeparatorChar); if (-not (Test-Path $VersionExe)) { throw 'Release executable missing' }",
+    "Remove-Retired $Staging; Move-Item $Stage $Staging; $VersionRoot = $Current",
+    "$VersionExe = Join-Path $Staging ($Asset.executablePath -replace '/', [IO.Path]::DirectorySeparatorChar); if (-not (Test-Path $VersionExe)) { throw 'Release executable missing' }",
     "$Authenticode = Get-AuthenticodeSignature $VersionExe; if ($Asset.nativeSignaturePolicy -eq 'authenticode-valid' -and $Authenticode.Status -ne 'Valid') { throw 'Native signature invalid' }",
     "$ActivationArgsTemplate = " + psArray(activationArgs),
     "$StatusArgsTemplate = " + psArray(statusArgs),
@@ -435,44 +436,28 @@ function Invoke-BoundedExe($Path, [string[]]$Arguments, [int]$TimeoutSeconds) {
     "$PriorCliCapable = $true; if ($Contract.priorExecutableMinVersion) { $PriorCliCapable = ($null -ne $PriorVersion -and ([version]$PriorVersion -ge [version]$Contract.priorExecutableMinVersion)) }",
     "$PriorStatus = $null; if ($PriorTarget -and $PriorCliCapable) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); try { $PriorStatus = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 60) | Out-String).Trim() } catch {} }",
     "@{ schemaVersion=1; priorTarget=$PriorTarget; priorVersion=$PriorVersion; targetVersion=$Version; priorStatus=$PriorStatus } | ConvertTo-Json -Depth 8 | Set-Content -Encoding UTF8 $Journal",
-    "if ($PreflightArgs.Count) { Invoke-BoundedExe $VersionExe $PreflightArgs 120 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Activation preflight failed' } }",
-    "Remove-StableJunction $NextLink; Remove-StableJunction $PreviousLink",
-    "New-Item -ItemType Junction -Path $NextLink -Target $VersionRoot | Out-Null",
+    "$PriorWasJunction = $false; $CurrentItem = Get-Item -LiteralPath $Current -Force -ErrorAction SilentlyContinue; if ($CurrentItem -and $CurrentItem.LinkType -eq 'Junction') { $PriorWasJunction = $true }",
+    "Remove-Retired $Previous",
     "$Switched = $false; $PriorDetached = $false",
     "try {",
-    "  if (Test-Path $Current) { Rename-Item -LiteralPath $Current -NewName (Split-Path -Leaf $PreviousLink); $PriorDetached = $true }; Rename-Item -LiteralPath $NextLink -NewName (Split-Path -Leaf $Current); $Switched = $true",
+    "  if (Test-Path $Current) { Rename-Item -LiteralPath $Current -NewName (Split-Path -Leaf $Previous); $PriorDetached = $true }; Rename-Item -LiteralPath $Staging -NewName (Split-Path -Leaf $Current); $Switched = $true",
     "  $StableExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")),
+    // Nothing runs from a new path: the preflight, activation and health probes all run at the fixed `current` path, and a failure renames `current.previous` back.
+    "  if ($PreflightArgs.Count) { Invoke-BoundedExe $StableExe $PreflightArgs 120 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Activation preflight failed' } }",
     "  $ActivationArgs = @(Expand-BootstrapArgs $ActivationArgsTemplate $VersionRoot $Version); $StatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate $VersionRoot $Version)",
     "  Invoke-BoundedExe $StableExe $ActivationArgs 240 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Activation failed' }",
     "  $HealthText = ((Invoke-BoundedExe $StableExe $StatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Health command failed' }; $Health = $HealthText | ConvertFrom-Json",
     "  Assert-Health $Health $Version",
     "  $StableBin = Split-Path $StableExe -Parent; $InstallRootResolved = [IO.Path]::GetFullPath($InstallRoot).TrimEnd([IO.Path]::DirectorySeparatorChar); $UserPath = [Environment]::GetEnvironmentVariable('Path','User'); $Kept = @($UserPath -split ';' | Where-Object { $Entry = $_.Trim(); $Entry -ne '' -and -not ($Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).StartsWith(($InstallRootResolved + [IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase) -and -not $Entry.TrimEnd([IO.Path]::DirectorySeparatorChar).Equals($StableBin.TrimEnd([IO.Path]::DirectorySeparatorChar), [StringComparison]::OrdinalIgnoreCase)) }); $NewPath = ((@($StableBin) + $Kept) -join ';'); if ($NewPath -ne $UserPath) { [Environment]::SetEnvironmentVariable('Path', $NewPath, 'User') }",
-    // Journal cleanup must succeed before discarding the prior pointer. If
-    // cleanup fails, catch still has a rollback anchor to restore.
-    // Version directories are compared by NAME, never by full path, here and in the rollback below.
-    // A junction's stored target and the paths this script builds can spell one directory two ways
-    // (a Windows short name such as RUNNER~1, another junction on the way, a different root form),
-    // and a full-path comparison that misses would prune the prior version, skip the rollback
-    // activation, or remove the version the stable pointer is still on. Every version lives
-    // directly under the versions root, so its name identifies it.
-    // Retention: after a healthy activation keep only the new version and the prior target (the
-    // app's first-start probation may still roll back to it, then deletes it). Every other version
-    // is removed; one a running process still holds fails the rename and is retried next install.
-    "  $KeepVersions = @([IO.Path]::GetFileName(([string]$VersionRoot).TrimEnd([IO.Path]::DirectorySeparatorChar))); if ($PriorTarget) { $KeepVersions += [IO.Path]::GetFileName(([string]$PriorTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)) }; Get-ChildItem -LiteralPath $VersionsRoot -Directory -Force -ErrorAction SilentlyContinue | Where-Object { $Candidate = $_.Name; -not ($KeepVersions | Where-Object { $_.Equals($Candidate, [StringComparison]::OrdinalIgnoreCase) }) } | ForEach-Object { try { $Doomed = Join-Path $VersionsRoot ('.prune-' + [guid]::NewGuid()); Rename-Item -LiteralPath $_.FullName -NewName (Split-Path -Leaf $Doomed) -ErrorAction Stop; Remove-Item -LiteralPath $Doomed -Recurse -Force -ErrorAction SilentlyContinue } catch { } }",
-    "  Remove-Item -Force $Journal; Remove-StableJunction $PreviousLink; Write-Output (" + psQuote(product + " ") + " + $Version + ' installed')",
+    // Legacy cleanup only: the old layout's versions/ folder and its pointer junctions are removed once nothing needs them
+    // (a legacy `current` junction that was just moved to current.previous keeps its versions/ target until the next install).
+    "  $LegacyVersions = Join-Path $InstallRoot 'versions'; if (-not $PriorWasJunction -and (Test-Path -LiteralPath $LegacyVersions)) { try { Remove-Item -LiteralPath $LegacyVersions -Recurse -Force -ErrorAction SilentlyContinue } catch { } }; foreach ($Legacy in @('.current-previous', '.current-next')) { try { Remove-Retired (Join-Path $InstallRoot $Legacy) } catch { } }",
+    "  Remove-Item -Force $Journal; Write-Output (" + psQuote(product + " ") + " + $Version + ' installed')",
     "} catch {",
     "  $InstallError = $_; $RollbackErrors = New-Object 'System.Collections.Generic.List[string]'",
-    "  try { if ($Switched -or $PriorDetached) { Remove-StableJunction $Current }; if ($PriorDetached -and (Test-Path $PreviousLink)) { Rename-Item -LiteralPath $PreviousLink -NewName (Split-Path -Leaf $Current) } } catch { $RollbackErrors.Add($_.Exception.Message) }",
-    "  try { if ($PriorTarget -and (Test-Path $Current) -and $PriorCliCapable -and ([IO.Path]::GetFileName(([string](Get-Item -LiteralPath $Current).Target).TrimEnd([IO.Path]::DirectorySeparatorChar)) -eq [IO.Path]::GetFileName(([string]$PriorTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)))) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorActivationArgs = @(Expand-BootstrapArgs $ActivationArgsTemplate ([string]$PriorTarget) $PriorVersion); $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); Invoke-BoundedExe $PriorExe $PriorActivationArgs 240 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Rollback activation failed' }; $PriorHealthText = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Rollback health failed' }; $PriorHealth = $PriorHealthText | ConvertFrom-Json; try { Assert-Health $PriorHealth $PriorVersion } catch { throw ('Prior health was not restored: ' + $_.Exception.Message) } } } catch { $RollbackErrors.Add($_.Exception.Message) }",
-    String.raw`  try {
-    $CandidatePath = [IO.Path]::GetFullPath($VersionRoot).TrimEnd([IO.Path]::DirectorySeparatorChar)
-    $VersionsPrefix = [IO.Path]::GetFullPath($VersionsRoot).TrimEnd([IO.Path]::DirectorySeparatorChar) + [IO.Path]::DirectorySeparatorChar
-    $ActiveTarget = if (Test-Path -LiteralPath $Current) { [string](Get-Item -LiteralPath $Current).Target } else { $null }
-    if ($ActiveTarget -and -not [IO.Path]::IsPathRooted($ActiveTarget)) { $ActiveTarget = Join-Path (Split-Path -Parent $Current) $ActiveTarget }
-    if (-not $CandidatePath.StartsWith($VersionsPrefix, [StringComparison]::OrdinalIgnoreCase)) { throw 'Failed version cleanup escapes versions root' }
-    if ($ActiveTarget -and [IO.Path]::GetFileName([IO.Path]::GetFullPath($ActiveTarget).TrimEnd([IO.Path]::DirectorySeparatorChar)).Equals([IO.Path]::GetFileName($CandidatePath), [StringComparison]::OrdinalIgnoreCase)) { throw 'Failed version is still active; preserved for recovery' }
-    if (Test-Path -LiteralPath $CandidatePath) { Remove-Item -LiteralPath $CandidatePath -Recurse -Force }
-  } catch { $RollbackErrors.Add($_.Exception.Message) }
+    "  try { if ($Switched) { Remove-Retired $Current }; if ($PriorDetached -and (Test-Path -LiteralPath $Previous)) { Rename-Item -LiteralPath $Previous -NewName (Split-Path -Leaf $Current) } } catch { $RollbackErrors.Add($_.Exception.Message) }",
+    "  try { if ($PriorTarget -and $PriorDetached -and (Test-Path -LiteralPath $Current) -and -not (Test-Path -LiteralPath $Previous) -and $PriorCliCapable) { $PriorExe = Join-Path $Current " + psQuote(executablePath.replaceAll("/", "\\")) + "; $PriorActivationArgs = @(Expand-BootstrapArgs $ActivationArgsTemplate ([string]$PriorTarget) $PriorVersion); $PriorStatusArgs = @(Expand-BootstrapArgs $StatusArgsTemplate ([string]$PriorTarget) $PriorVersion); Invoke-BoundedExe $PriorExe $PriorActivationArgs 240 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Rollback activation failed' }; $PriorHealthText = ((Invoke-BoundedExe $PriorExe $PriorStatusArgs 120) | Out-String).Trim(); if ($LASTEXITCODE -ne 0) { throw 'Rollback health failed' }; $PriorHealth = $PriorHealthText | ConvertFrom-Json; try { Assert-Health $PriorHealth $PriorVersion } catch { throw ('Prior health was not restored: ' + $_.Exception.Message) } } } catch { $RollbackErrors.Add($_.Exception.Message) }",
+    String.raw`  try { if (Test-Path -LiteralPath $Staging) { Remove-Retired $Staging } } catch { $RollbackErrors.Add($_.Exception.Message) }
   if ($RollbackErrors.Count) {
     $InstallError.Exception.Data['RollbackErrors'] = $RollbackErrors.ToArray()
     Write-Warning ('Rollback/cleanup also failed: ' + ($RollbackErrors -join '; '))
@@ -495,7 +480,7 @@ export function validatePowerShellBootstrap(script, expected = {}) {
     "checksums.json is not manifest-bound",
     "Provenance checksum mismatch",
     "SBOM checksum mismatch",
-    "New-Item -ItemType Junction",
+    "current.previous",
     "integration-journal.json",
     "Rollback activation failed",
     "Prior health was not restored",