fix(onboard): retain qualification catalog on rebuild (#9396)

<!-- markdownlint-disable MD041 -->
## Summary

Managed-image rebuild preflight now retains the immutable qualification
revision used by initial onboarding. Rebuilds outside live GitHub
Actions qualification continue to resolve the current release catalog.

## Related Issue

Fixes #9385

## Changes

- Resolve the complete managed-image catalog from an exact source
revision during live qualification.
- Carry the qualification revision through both fresh onboarding and
managed rebuild preflight.
- Reject malformed revisions and image-label substitutions before image
selection.
- Preserve current release-catalog rebuild behavior outside GitHub
Actions.

## Type of Change

- [x] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [x] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification: Self-review covered
public GHCR revision validation, all-agent cohort binding, release-path
isolation, and the unchanged credential flow; focused negative tests
reject malformed and label-mismatched revisions.
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## DGX Station Hardware Evidence

- [ ] Tested on DGX Station
- Tested commit: Not applicable
- Station profile/scenario: Not applicable
- Result: Not applicable
- Supporting evidence: Not applicable

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — command/result or justification:
Vitest passed 39/39 managed-image catalog tests, 26/26
workload-preparation tests, 3/3 focused rebuild regression tests, 3/3
onboarding-orchestration tests, and 22/22 growth-guardrail tests. `tsc
-p tsconfig.cli.json --noEmit` passed.
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result:
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* Managed workload onboarding and rebuilds now honor immutable
managed-image revisions when available.
* Invalid, conflicting, or mismatched image revisions are rejected
before workload preparation.
* Existing behavior remains unchanged outside supported CI environments.

* **Tests**
* Added coverage for revision validation, onboarding, rebuilds, and
catalog resolution scenarios.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Aaron Erickson <aerickson@nvidia.com>

Author: ericksoa

src/lib/onboard/managed-image-catalog.test.ts

@@ -411,6 +411,66 @@ describe("managed image GHCR catalog", () => {
     },
   );
 
+  it("resolves an immutable qualification revision as one exact cohort (#9385)", async () => {
+    const fixture = catalogFixture({ openclaw: { rootReference: REVISION } });
+
+    const catalog = await resolveManagedImageCatalogFromGhcr({
+      release: RELEASE,
+      revision: REVISION,
+      fetchImpl: fixture.fetchImpl,
+    });
+
+    expect(
+      SHIPPED_MANAGED_IMAGE_AGENTS.map(
+        (agent) =>
+          (catalog[agent] as { source: { cohort: string; release: string; revision: string } })
+            .source,
+      ),
+    ).toEqual(
+      SHIPPED_MANAGED_IMAGE_AGENTS.map(() => ({
+        cohort: COHORT,
+        release: RELEASE,
+        repository: MANAGED_IMAGE_SOURCE_REPOSITORY,
+        revision: REVISION,
+      })),
+    );
+    const rootManifestRequests = fixture.fetchMock.mock.calls
+      .map(([input]) => new URL(String(input)).pathname)
+      .filter((pathname) => pathname.includes("/manifests/"));
+    expect(rootManifestRequests).toContain(
+      `/v2/nvidia/nemoclaw/openclaw-sandbox/manifests/${REVISION}`,
+    );
+    expect(rootManifestRequests).not.toContain(
+      `/v2/nvidia/nemoclaw/openclaw-sandbox/manifests/${RELEASE}`,
+    );
+  });
+
+  it("rejects a malformed qualification revision before registry access (#9385)", async () => {
+    const fetchImpl = vi.fn();
+
+    await expect(
+      resolveManagedImageCatalogFromGhcr({
+        release: RELEASE,
+        revision: "main",
+        fetchImpl: fetchImpl as typeof fetch,
+      }),
+    ).rejects.toThrow(/managed image revision 'main' is not a full lowercase SHA/);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("rejects an image that does not match the qualification revision (#9385)", async () => {
+    const requestedRevision = "c".repeat(40);
+    const fixture = catalogFixture({ openclaw: { rootReference: requestedRevision } });
+
+    await expect(
+      resolveManagedImageCatalogFromGhcr({
+        release: RELEASE,
+        revision: requestedRevision,
+        fetchImpl: fixture.fetchImpl,
+      }),
+    ).rejects.toThrow(/source revision does not match the expected revision/);
+  });
+
   it("fails closed when a dependent cohort alias is torn or absent", async () => {
     const fixture = catalogFixture({ hermes: { missingRoot: true } });
 
@@ -483,7 +543,7 @@ describe("managed image GHCR catalog", () => {
         release: RELEASE,
         fetchImpl: fixture.fetchImpl,
       }),
-    ).rejects.toThrow(/source revision does not match the OpenClaw revision/);
+    ).rejects.toThrow(/source revision does not match the expected revision/);
   });
 
   it.each([

src/lib/onboard/managed-image/catalog.ts

@@ -518,7 +518,7 @@ async function resolveManagedImageContractAtReferenceFromGhcr(options: {
     return invalid(`'${agent}' image publication cohort does not match the OpenClaw cohort`);
   }
   if (options.expectedRevision !== undefined && identity.revision !== options.expectedRevision) {
-    return invalid(`'${agent}' image source revision does not match the OpenClaw revision`);
+    return invalid(`'${agent}' image source revision does not match the expected revision`);
   }
   const image = MANAGED_IMAGE_REPOSITORIES[agent];
   return {
@@ -572,19 +572,27 @@ export async function resolveManagedImageContractFromGhcr(options: {
 
 export async function resolveManagedImageCatalogFromGhcr(options: {
   readonly release: string;
+  /** Immutable source revision selected by a live qualification run. */
+  readonly revision?: string;
   readonly platform?: ManagedImagePlatform;
   readonly nodeArchitecture?: string;
   readonly fetchImpl?: Fetch;
   readonly environment?: NodeJS.ProcessEnv;
 }): Promise<ManagedImageContractCatalog> {
   const release = normalizeManagedImageRelease(options.release);
+  const revision = options.revision;
+  if (revision !== undefined && !REVISION_PATTERN.test(revision)) {
+    return invalid(`managed image revision '${revision}' is not a full lowercase SHA`);
+  }
   const platform = resolveCatalogPlatform(options);
   return withRegistryFetch(options.fetchImpl, options.environment, async (fetchImpl) => {
-    const openclaw = await resolveManagedImageContractFromGhcr({
+    const openclaw = await resolveManagedImageContractAtReferenceFromGhcr({
       agent: "openclaw",
+      reference: revision ?? release,
       release,
       platform,
       fetchImpl,
+      ...(revision === undefined ? {} : { expectedRevision: revision }),
     });
     const cohortReference = `cohort-${openclaw.source.cohort}`;
     const dependentResults = await Promise.allSettled(

src/lib/onboard/managed-workload/onboard-orchestration.test.ts

@@ -3,9 +3,86 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { prepareOnboardSandboxWorkloadLaunch } from "./onboard-orchestration";
+const prepareSandboxWorkloadSource = vi.hoisted(() => vi.fn());
+
+vi.mock("../workload/preparation", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../workload/preparation")>()),
+  prepareSandboxWorkloadSource,
+}));
+
+vi.mock("../../core/version", () => ({ getVersion: () => "v0.0.0" }));
+
+import {
+  createManagedWorkloadOnboardRuntime,
+  prepareOnboardSandboxWorkloadLaunch,
+} from "./onboard-orchestration";
+
+function createFreshOnboardingRuntime(environment: Readonly<Record<string, string>>) {
+  const prepared = {
+    source: {
+      kind: "legacy-dockerfile",
+      dockerfilePath: "agents/openclaw/Dockerfile",
+      reason: "managed-image-unavailable",
+    },
+    release: "v0.0.0",
+    fallbackDiagnostic: null,
+  };
+  prepareSandboxWorkloadSource.mockClear();
+  prepareSandboxWorkloadSource.mockResolvedValueOnce(prepared);
+
+  const runtime = createManagedWorkloadOnboardRuntime(
+    {
+      computePlan: { driverName: "docker" },
+      managedWorkloadRebuild: null,
+      tempManagedRuntime: false,
+      tempManagedRuntimeCatalog: null,
+      agentName: "openclaw",
+      legacyDockerfilePath: "agents/openclaw/Dockerfile",
+      customDockerfilePath: null,
+      rootDir: "/tmp/nemoclaw",
+      model: "model",
+      provider: "provider",
+      preferredInferenceApi: null,
+      endpointUrl: null,
+      startupProfile: { environment },
+      note: vi.fn(),
+      fallbackBuildEstimate: () => null,
+    } as unknown as Parameters<typeof createManagedWorkloadOnboardRuntime>[0],
+    {
+      resolveAgentInferenceApi: vi.fn(),
+      getSandboxInferenceConfig: vi.fn(),
+    },
+  );
+
+  return { prepared, runtime };
+}
 
 describe("managed workload onboard orchestration", () => {
+  it("retains the live qualification catalog revision during fresh onboarding (#9385)", async () => {
+    const catalogRevision = "a".repeat(40);
+    const { prepared, runtime } = createFreshOnboardingRuntime({
+      GITHUB_ACTIONS: "true",
+      E2E_MANAGED_IMAGE_REVISION: catalogRevision,
+    });
+
+    await expect(runtime.ensurePreparedWorkload()).resolves.toBe(prepared);
+    expect(prepareSandboxWorkloadSource).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ catalogRevision }),
+    );
+  });
+
+  it("omits the qualification catalog revision outside GitHub Actions (#9385)", async () => {
+    const { prepared, runtime } = createFreshOnboardingRuntime({
+      E2E_MANAGED_IMAGE_REVISION: "a".repeat(40),
+    });
+
+    await expect(runtime.ensurePreparedWorkload()).resolves.toBe(prepared);
+    expect(prepareSandboxWorkloadSource).toHaveBeenCalledOnce();
+    expect(prepareSandboxWorkloadSource.mock.calls[0]?.[0]).not.toHaveProperty(
+      "catalogRevision",
+    );
+  });
+
   it("resolves final-image patch metadata after managed build-context staging", async () => {
     const resolutionMetadata = { key: "published-dcode-base" };
     let staged = false;

src/lib/onboard/managed-workload/onboard-orchestration.ts

@@ -50,6 +50,7 @@ import {
 import { getSandboxReadyTimeoutSecs } from "../sandbox-gpu-create";
 import type { SandboxGpuConfig } from "../sandbox-gpu-mode";
 import {
+  liveE2eManagedImageRevision,
   type PreparedSandboxWorkloadSource,
   prepareSandboxWorkloadSource,
 } from "../workload/preparation";
@@ -155,6 +156,7 @@ export function createManagedWorkloadOnboardRuntime(
   let preparedProfile: BuiltManagedStartupOnboardProfile | null = null;
 
   const ensurePreparedWorkload = async (): Promise<PreparedSandboxWorkloadSource> => {
+    const catalogRevision = liveE2eManagedImageRevision(input.startupProfile.environment);
     preparedWorkloadPromise ??= input.managedWorkloadRebuild
       ? Promise.resolve(
           prepareSandboxWorkloadSourceFromRebuildHandoff(
@@ -170,6 +172,7 @@ export function createManagedWorkloadOnboardRuntime(
           runtime: runtimeCapabilities,
           version: getVersion({ rootDir: input.rootDir }),
           catalogPath: input.tempManagedRuntimeCatalog,
+          ...(catalogRevision ? { catalogRevision } : {}),
           acceptedCandidateContract: isCandidateAgent(input.agentName)
             ? readCandidateQualificationReceipt(input.agentName)
             : null,

src/lib/onboard/sandbox-workload-preparation.test.ts

@@ -107,6 +107,21 @@ describe("sandbox workload preparation", () => {
     });
   });
 
+  it("passes an immutable qualification revision to catalog resolution (#9385)", async () => {
+    const resolveCatalog = vi.fn(async () => CATALOG);
+
+    await prepareSandboxWorkloadSource(
+      { ...input("openclaw"), catalogRevision: REVISION },
+      { resolveCatalog },
+    );
+
+    expect(resolveCatalog).toHaveBeenCalledExactlyOnceWith({
+      release: RELEASE,
+      platform: MANAGED_IMAGE_PLATFORM,
+      revision: REVISION,
+    });
+  });
+
   it("loads an exact local all-agent catalog without using the registry resolver (#7744)", async () => {
     const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-managed-catalog-"));
     const catalogPath = path.join(fixtureRoot, "catalog.json");

src/lib/onboard/sandbox-workload-rebuild.test.ts

@@ -309,6 +309,65 @@ describe("managed workload rebuild preflight", () => {
     expect(Object.isFrozen(handoff?.replacement.source.contract.source)).toBe(true);
   });
 
+  it("retains the live qualification revision during rebuild preflight (#9385)", async () => {
+    const prepare = vi.fn(async () => replacement("langchain-deepagents-code"));
+    managedWorkloadRebuildDependencies.prepareSandboxWorkloadSource = prepare;
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("E2E_MANAGED_IMAGE_REVISION", "a".repeat(40));
+
+    await prepareManagedWorkloadRebuildHandoff(entry("langchain-deepagents-code"), {
+      runtime: runtime(),
+      provider: provider(),
+      version: "0.0.100",
+    });
+
+    expect(prepare).toHaveBeenCalledExactlyOnceWith({
+      agentName: "langchain-deepagents-code",
+      legacyDockerfilePath: "managed-rebuild-must-not-stage-this-dockerfile",
+      runtime: runtime(),
+      version: "0.0.100",
+      policy: "require-managed",
+      catalogRevision: "a".repeat(40),
+    });
+  });
+
+  it("rejects a qualification revision that conflicts with durable authority (#9385)", async () => {
+    const prepare = vi.fn(async () => replacement("langchain-deepagents-code"));
+    managedWorkloadRebuildDependencies.prepareSandboxWorkloadSource = prepare;
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("E2E_MANAGED_IMAGE_REVISION", "c".repeat(40));
+
+    await expect(
+      prepareManagedWorkloadRebuildHandoff(entry("langchain-deepagents-code"), {
+        runtime: runtime(),
+        provider: provider(),
+        version: "0.0.100",
+      }),
+    ).rejects.toThrow("live qualification revision does not match the durable workload receipt");
+    expect(prepare).not.toHaveBeenCalled();
+  });
+
+  it("keeps release-catalog rebuild behavior outside GitHub Actions (#9385)", async () => {
+    const prepare = vi.fn(async () => replacement("openclaw"));
+    managedWorkloadRebuildDependencies.prepareSandboxWorkloadSource = prepare;
+    vi.stubEnv("GITHUB_ACTIONS", "false");
+    vi.stubEnv("E2E_MANAGED_IMAGE_REVISION", "c".repeat(40));
+
+    await prepareManagedWorkloadRebuildHandoff(entry("openclaw"), {
+      runtime: runtime(),
+      provider: provider(),
+      version: "0.0.100",
+    });
+
+    expect(prepare).toHaveBeenCalledExactlyOnceWith({
+      agentName: "openclaw",
+      legacyDockerfilePath: "managed-rebuild-must-not-stage-this-dockerfile",
+      runtime: runtime(),
+      version: "0.0.100",
+      policy: "require-managed",
+    });
+  });
+
   it.each(AGENTS)("prepares an arm64 replacement handoff for %s", async (agent) => {
     managedWorkloadRebuildDependencies.prepareSandboxWorkloadSource = vi.fn(async () =>
       replacement(agent, "linux/arm64"),

src/lib/onboard/workload/preparation.ts

@@ -31,6 +31,7 @@ import {
 type ResolveManagedImageCatalog = (options: {
   readonly release: string;
   readonly platform: ManagedImagePlatform;
+  readonly revision?: string;
 }) => Promise<ManagedImageContractCatalog>;
 
 export interface PrepareSandboxWorkloadSourceInput {
@@ -41,10 +42,17 @@ export interface PrepareSandboxWorkloadSourceInput {
   readonly version: string;
   readonly policy?: ManagedImageSelectionPolicy;
   readonly catalogPath?: string | null;
+  readonly catalogRevision?: string | null;
   /** Contract from the repository-accepted candidate qualification receipt. */
   readonly acceptedCandidateContract?: ManagedImageContractV1 | null;
 }
 
+export function liveE2eManagedImageRevision(environment: NodeJS.ProcessEnv): string | null {
+  if (environment.GITHUB_ACTIONS !== "true") return null;
+  const revision = environment.E2E_MANAGED_IMAGE_REVISION?.trim();
+  return revision ? revision : null;
+}
+
 function readExactManagedImageCatalog(catalogPath: string): ManagedImageContractCatalog {
   let descriptor: number | null = null;
   try {
@@ -280,7 +288,11 @@ export async function prepareSandboxWorkloadSource(
       ? readExactManagedImageCatalog(input.catalogPath)
       : await (
           dependencies.resolveCatalog ?? ((options) => resolveManagedImageCatalogFromGhcr(options))
-        )({ release, platform });
+        )({
+          release,
+          platform,
+          ...(input.catalogRevision ? { revision: input.catalogRevision } : {}),
+        });
   } catch (error) {
     if (!(error instanceof ManagedImageCatalogUnavailableError)) {
       throw new SandboxWorkloadPreparationError(

src/lib/onboard/workload/rebuild.ts

@@ -36,6 +36,7 @@ import {
 export type { ManagedWorkloadReceipt } from "./authority";
 
 import {
+  liveE2eManagedImageRevision,
   type PreparedSandboxWorkloadSource,
   prepareSandboxWorkloadSource,
   SandboxWorkloadPreparationError,
@@ -172,13 +173,25 @@ export async function prepareManagedWorkloadRebuildHandoff(
       );
     }
   } else {
+    const qualificationRevision = liveE2eManagedImageRevision(process.env);
+    if (
+      qualificationRevision !== null &&
+      qualificationRevision !== authority.receipt.sourceRevision
+    ) {
+      throw new ManagedWorkloadRebuildError(
+        "the live qualification revision does not match the durable workload receipt",
+      );
+    }
     try {
       replacement = await managedWorkloadRebuildDependencies.prepareSandboxWorkloadSource({
         agentName: authority.agent,
         legacyDockerfilePath: "managed-rebuild-must-not-stage-this-dockerfile",
         runtime: options.runtime,
         version: options.version ?? getVersion(),
         policy: "require-managed",
+        ...(qualificationRevision
+          ? { catalogRevision: authority.receipt.sourceRevision }
+          : {}),
       });
     } catch (error) {
       throw new ManagedWorkloadRebuildError(