fix(e2e): select reviewed SDK from candidate lock

.github/workflows/e2e-standard-profile.yaml

@@ -431,10 +431,13 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          mapfile -t archives < <(find "$RUNNER_TEMP/openshell-sdk" -maxdepth 1 -type f -name '*.tgz' -print)
-          test "${#archives[@]}" -eq 1
-          env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
-            npm cache add "${archives[0]}" --offline --ignore-scripts
+          mapfile -t archives < <(find "$RUNNER_TEMP/openshell-sdk" -maxdepth 1 -type f -name '*.tgz' -print | sort)
+          test "${#archives[@]}" -ge 1
+          test "${#archives[@]}" -le 2
+          for archive in "${archives[@]}"; do
+            env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
+              npm cache add "$archive" --offline --ignore-scripts
+          done
           env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
             npm ci --ignore-scripts --prefer-offline --no-audit --no-fund
           env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \

.github/workflows/e2e.yaml

@@ -147,9 +147,10 @@ jobs:
           scope: "@nvidia"
 
       - id: package
-        name: Download and verify exact OpenShell SDK package
+        name: Download and verify reviewed OpenShell SDK packages
         env:
           NEMOCLAW_OPEN_SHELL_SDK_OUTPUT_DIRECTORY: ${{ runner.temp }}/openshell-sdk
+          NEMOCLAW_OPEN_SHELL_SDK_INCLUDE_AVAILABLE_REPLACEMENT: "1"
           NODE_AUTH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
@@ -3422,10 +3423,13 @@ jobs:
       - name: Install reviewed OpenShell SDK archive without package credentials
         run: |
           set -euo pipefail
-          mapfile -t archives < <(find "$RUNNER_TEMP/openshell-sdk" -maxdepth 1 -type f -name '*.tgz' -print)
-          test "${#archives[@]}" -eq 1
-          env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
-            npm cache add "${archives[0]}" --offline --ignore-scripts
+          mapfile -t archives < <(find "$RUNNER_TEMP/openshell-sdk" -maxdepth 1 -type f -name '*.tgz' -print | sort)
+          test "${#archives[@]}" -ge 1
+          test "${#archives[@]}" -le 2
+          for archive in "${archives[@]}"; do
+            env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
+              npm cache add "$archive" --offline --ignore-scripts
+          done
           env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \
             npm ci --ignore-scripts --prefer-offline --no-audit --no-fund
           env -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN \

scripts/checks/package-openshell-sdk-for-pr.mts

@@ -13,7 +13,7 @@ const TRUSTED_REPOSITORY_ROOT = resolve(dirname(fileURLToPath(import.meta.url)),
 
 export function packageReviewedOpenShellSdk(
   outputDirectory: string,
-  includeReplacement = false,
+  replacementMode: "exclude" | "require" | "if-present" = "exclude",
   dependencies: Readonly<{
     pack?: typeof packReviewedNpmArchive;
     readAuditConfig?: () => string;
@@ -27,11 +27,11 @@ export function packageReviewedOpenShellSdk(
     dependencies.readAuditConfig?.() ??
       readFileSync(join(TRUSTED_REPOSITORY_ROOT, "ci/reviewed-npm-audit.json"), "utf8"),
   );
-  if (includeReplacement && !config.sourceRegistryPackageReplacement) {
+  if (replacementMode === "require" && !config.sourceRegistryPackageReplacement) {
     throw new Error("reviewed OpenShell SDK replacement metadata is required");
   }
   const reviewedPackages =
-    includeReplacement && config.sourceRegistryPackageReplacement
+    replacementMode !== "exclude" && config.sourceRegistryPackageReplacement
       ? [config.sourceRegistryPackage, config.sourceRegistryPackageReplacement]
       : [config.sourceRegistryPackage];
   const archives: ReturnType<typeof packReviewedNpmArchive>[] = [];
@@ -65,14 +65,28 @@ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1]
     process.exit(1);
   }
   const includeReplacementValue = process.env.NEMOCLAW_OPEN_SHELL_SDK_INCLUDE_REPLACEMENT;
+  const includeAvailableReplacementValue =
+    process.env.NEMOCLAW_OPEN_SHELL_SDK_INCLUDE_AVAILABLE_REPLACEMENT;
   if (includeReplacementValue !== undefined && includeReplacementValue !== "1") {
     console.error("NEMOCLAW_OPEN_SHELL_SDK_INCLUDE_REPLACEMENT must be 1 when set");
     process.exit(1);
   }
+  if (includeAvailableReplacementValue !== undefined && includeAvailableReplacementValue !== "1") {
+    console.error("NEMOCLAW_OPEN_SHELL_SDK_INCLUDE_AVAILABLE_REPLACEMENT must be 1 when set");
+    process.exit(1);
+  }
+  if (includeReplacementValue !== undefined && includeAvailableReplacementValue !== undefined) {
+    console.error("OpenShell SDK replacement modes are mutually exclusive");
+    process.exit(1);
+  }
   try {
-    process.stdout.write(
-      `${packageReviewedOpenShellSdk(outputDirectory, includeReplacementValue === "1")}\n`,
-    );
+    const replacementMode =
+      includeReplacementValue === "1"
+        ? "require"
+        : includeAvailableReplacementValue === "1"
+          ? "if-present"
+          : "exclude";
+    process.stdout.write(`${packageReviewedOpenShellSdk(outputDirectory, replacementMode)}\n`);
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);

test/e2e/README.md

@@ -359,10 +359,10 @@ and transport. It also stops the gateway and removes its temporary state.
 
 ## Catalogue Targets
 
-Every catalogue profile installs the reviewed OpenShell SDK archive before restoring the candidate CLI.
-The shared package job downloads and verifies the pinned SDK with package-read permission.
-Catalogue jobs receive the run-scoped archive without package credentials and reject a missing or ambiguous archive.
-Catalogue and external-gateway health jobs add the archive to npm's cache, then reinstall dependencies from the lockfile with package scripts disabled.
+Every catalogue profile installs a lockfile-selected reviewed OpenShell SDK archive before restoring the candidate CLI.
+The shared package job downloads and verifies the active SDK and any approved transition replacement with package-read permission.
+Catalogue jobs receive the run-scoped archives without package credentials and reject a missing artifact or more than one approved transition pair.
+Catalogue and external-gateway health jobs add each reviewed archive to npm's cache, then reinstall dependencies from the lockfile with package scripts disabled.
 This preserves the locked dependency versions and avoids npm resolving a new peer dependency graph during SDK installation.
 Both jobs verify that the SDK connection API loads before running tests.
 This keeps the private optional dependency available for SDK-backed commands such as configuration export.