fix(release): allow macOS snapshot selection in candidate smoke (#114144)

scripts/e2e/parallels/npm-update-smoke.ts

@@ -61,6 +61,7 @@ interface NpmUpdateOptions {
   registryPackageTarballs: string[];
   freshTargetSpec?: string;
   hostIp?: string;
+  macosSnapshotHint?: string;
   macosVm?: string;
   packageSpec: string;
   targetTarball?: string;
@@ -390,6 +391,8 @@ Options:
   --platform <list>           Comma-separated platforms to run: all, macos, windows, linux.
                              Default: all
   --macos-vm <name>           Explicit Parallels macOS VM name.
+  --macos-snapshot-hint <hint>
+                             Snapshot name substring/fuzzy match passed to macOS fresh lanes.
   --provider <openai|anthropic|minimax>
   --model <provider/model>    Override the model used for agent-turn smoke checks.
   --host-ip <ip>             Override Parallels host IP.
@@ -409,6 +412,7 @@ export function parseArgs(argv: string[]): NpmUpdateOptions {
     registryPackageTarballs: [],
     freshTargetSpec: undefined,
     json: false,
+    macosSnapshotHint: undefined,
     macosVm: undefined,
     modelId: undefined,
     packageSpec: "",
@@ -465,6 +469,10 @@ export function parseArgs(argv: string[]): NpmUpdateOptions {
         options.macosVm = ensureValue(args, i, arg);
         i++;
         break;
+      case "--macos-snapshot-hint":
+        options.macosSnapshotHint = ensureValue(args, i, arg);
+        i++;
+        break;
       case "--provider":
         options.provider = parseProvider(ensureValue(args, i, arg));
         i++;
@@ -691,7 +699,7 @@ export class NpmUpdateSmoke {
   private async runFreshBaselines(): Promise<void> {
     const jobs: Job[] = [];
     if (this.options.platforms.has("macos")) {
-      jobs.push(this.spawnFresh("macOS", "macos", ["--vm", this.macosVm]));
+      jobs.push(this.spawnFresh("macOS", "macos", this.macosFreshArgs()));
     }
     if (this.options.platforms.has("windows")) {
       jobs.push(this.spawnFresh("Windows", "windows", []));
@@ -713,7 +721,7 @@ export class NpmUpdateSmoke {
         this.spawnFresh(
           "macOS",
           "macos",
-          ["--vm", this.macosVm],
+          this.macosFreshArgs(),
           {},
           this.freshTargetSpec,
           "fresh-target",
@@ -742,6 +750,16 @@ export class NpmUpdateSmoke {
     await this.finishFreshJobs("fresh-target", "fresh target", jobs, this.freshTargetStatus);
   }
 
+  private macosFreshArgs(): string[] {
+    return [
+      "--vm",
+      this.macosVm,
+      ...(this.options.macosSnapshotHint
+        ? ["--snapshot-hint", this.options.macosSnapshotHint]
+        : []),
+    ];
+  }
+
   private async finishFreshJobs(
     phase: "fresh" | "fresh-target",
     failureLabel: string,

scripts/release-candidate-checklist.d.mts

@@ -256,12 +256,14 @@ export function candidateParallelsArgs(
   dependencyTarballPaths?: unknown[],
   toolingRoot?: string,
   registryPackageTarballPaths?: unknown[],
+  macosSnapshotHint?: string,
 ): unknown[];
 export function candidateParallelsShellCommand(
   tarballPath: unknown,
   timeoutBin: unknown,
   dependencyTarballPaths?: unknown[],
   registryPackageTarballPaths?: unknown[],
+  macosSnapshotHint?: string,
 ): string;
 declare function gitIsAncestor(ancestor: unknown, target: unknown): boolean;
 declare function loadCandidateShippedBaseline(ref: unknown): {

scripts/release-candidate-checklist.mjs

@@ -1361,6 +1361,7 @@ export function candidateParallelsArgs(
   dependencyTarballPaths = [],
   toolingRoot = TOOLING_ROOT,
   registryPackageTarballPaths = [],
+  macosSnapshotHint = "",
 ) {
   return [
     "exec",
@@ -1373,6 +1374,7 @@ export function candidateParallelsArgs(
       "--registry-package-tarball",
       registryPackage,
     ]),
+    ...(macosSnapshotHint ? ["--macos-snapshot-hint", macosSnapshotHint] : []),
     "--json",
   ];
 }
@@ -1382,6 +1384,7 @@ export function candidateParallelsShellCommand(
   timeoutBin,
   dependencyTarballPaths = [],
   registryPackageTarballPaths = [],
+  macosSnapshotHint = "",
 ) {
   // Login shells can replace the candidate's supported Node with ambient host Node.
   // Keep the invoking Node first so pnpm and npm use the validated runtime.
@@ -1399,6 +1402,7 @@ export function candidateParallelsShellCommand(
       dependencyTarballPaths,
       TOOLING_ROOT,
       registryPackageTarballPaths,
+      macosSnapshotHint,
     ).map(shellQuote),
   ].join(" ");
 }
@@ -1425,6 +1429,7 @@ async function runParallelsIfNeeded(
     timeoutBin,
     dependencyTarballPaths,
     registryPackageTarballPaths,
+    process.env.OPENCLAW_PARALLELS_MACOS_SNAPSHOT_HINT?.trim() ?? "",
   );
   run("bash", ["-lc", command], {
     env: {