feat(onboard): add external component lifecycle

src/lib/onboard.ts

@@ -452,6 +452,7 @@ const {
   applyHealthyPortReuse,
   createInitialOnboardFlowPhases,
   destroyGatewayForReuse,
+  externalComponent: component,
   runInitialOnboardFlowSlice,
   verifyGatewayContainerRunning,
 }: typeof import("./onboard/machine/initial-flow-composition") = require("./onboard/machine/initial-flow-composition");
@@ -1155,31 +1156,29 @@ const { gatewayClusterHealthcheckPassed, repairGatewayBootstrapSecrets } =
 // ── Step 1: Preflight ────────────────────────────────────────────
 
 type PreflightOptions = import("./onboard/fatal-runtime-preflight").FatalRuntimePreflightOptions;
-const onboardPreflightGatewayAuthority =
-  preflightGatewayAuthority.createOnboardPreflightGatewayAuthority({
-    gatewayName: () => GATEWAY_NAME,
-    gatewayPort: () => GATEWAY_PORT,
-    collectGatewayReadiness: (deps) =>
-      preflightGatewayAuthority.collectOnboardGatewayReadiness(deps),
-    getGatewayOwnerDeps: () => machineGatewayOwnerDeps,
-    isNonInteractive,
-    ensureOpenshellForOnboard,
-    updateSession: onboardSession.updateSession,
-    adoptPackagedGatewayAuthorityAfterTrustedInstall:
-      gatewayAuthorityCheckpoint.adoptPackagedGatewayAuthorityAfterTrustedInstall,
-    checkPortAvailable,
-    isDockerDriverGatewayPortListener,
-    getGatewayReuseSnapshot,
-    selectNamedGatewayForReuseIfNeeded,
-    refreshDockerDriverGatewayReuseState,
-  });
+const preflightGateway = preflightGatewayAuthority.createOnboardPreflightGatewayAuthority({
+  gatewayName: () => GATEWAY_NAME,
+  gatewayPort: () => GATEWAY_PORT,
+  collectGatewayReadiness: (deps) => preflightGatewayAuthority.collectOnboardGatewayReadiness(deps),
+  getGatewayOwnerDeps: () => machineGatewayOwnerDeps,
+  isNonInteractive,
+  ensureOpenshellForOnboard,
+  updateSession: onboardSession.updateSession,
+  adoptPackagedGatewayAuthorityAfterTrustedInstall:
+    gatewayAuthorityCheckpoint.adoptPackagedGatewayAuthorityAfterTrustedInstall,
+  checkPortAvailable,
+  isDockerDriverGatewayPortListener,
+  getGatewayReuseSnapshot,
+  selectNamedGatewayForReuseIfNeeded,
+  refreshDockerDriverGatewayReuseState,
+});
 
 async function preflight(
   preflightOpts: PreflightOptions = {},
 ): Promise<ReturnType<typeof nim.detectGpu>> {
   step(1, 8, "Preflight checks");
   const { gpu, host, sandboxGpuConfig, gpuTrustGateRejection } =
-    await onboardPreflightGatewayAuthority.runRuntimePreflight(preflightOpts);
+    await preflightGateway.runRuntimePreflight(preflightOpts);
 
   await preflightUtils.checkContainerRuntimeResources(host, {
     ignored: process.env.NEMOCLAW_IGNORE_RUNTIME_RESOURCES === "1",
@@ -1191,7 +1190,7 @@ async function preflight(
     externallySupervised: gatewayExternallySupervised,
     gatewayReuseState: initialGatewayReuseState,
     managedGatewayObservationAuthoritative,
-  } = await onboardPreflightGatewayAuthority.prepareGatewayAuthority();
+  } = await preflightGateway.prepareGatewayAuthority();
   let reuseState = initialGatewayReuseState;
 
   // Docker-backed gateways use one legacy reuse and cleanup sequence because
@@ -2604,15 +2603,15 @@ async function preflightAuthoritativeRebuildTarget(
         resolveBaselinePolicy: resolveSandboxBaselinePolicy,
         bindGatewayAuthority: () => bindGatewayOwner(getGatewayOwner()),
         runFatalRuntimePreflight: async () =>
-          onboardPreflightGatewayAuthority.runRuntimePreflight(
+          preflightGateway.runRuntimePreflight(
             authoritativeRebuildTarget.authoritativeRebuildRuntimePreflightOptions(opts),
             (code) => fail(`onboard runtime preflight exited with code ${String(code)}`),
           ),
         ensureOpenshell: () =>
           ensureOpenshellForOnboard((code) =>
             fail(`OpenShell component preflight exited with code ${String(code)}`),
           ),
-        assertGatewayReadiness: onboardPreflightGatewayAuthority.collectGatewayReadiness,
+        assertGatewayReadiness: preflightGateway.collectGatewayReadiness,
         inferenceRouteState: (p, m) => readInferenceRouteState(authoritativeGateway.name, p, m),
         captureForwardList: () => runCaptureOpenshell(["forward", "list"], { ignoreError: true }),
       },
@@ -2928,8 +2927,7 @@ async function runOnboard(opts: OnboardOptions = {}): Promise<void> {
         },
         getInitialGatewayReuseState: () =>
           selectNamedGatewayForReuseIfNeeded(getGatewayReuseSnapshot()).gatewayReuseState,
-        assertGatewayReadiness: () =>
-          onboardPreflightGatewayAuthority.collectGatewayReadiness().then(() => undefined),
+        ...component.flowDeps(preflightGateway, getDockerDriverGatewayEnv, inspectSandboxForCreate),
         gatewayName: GATEWAY_NAME,
         recreateSandbox: isRecreateSandbox,
         requiresBindMounts: effectiveHostMounts.length > 0,
@@ -3286,7 +3284,7 @@ async function runOnboard(opts: OnboardOptions = {}): Promise<void> {
           webSearchProvider: (config) => webSearchProviderForConfig(config),
         },
         finalizationDeps: {
-          setDefaultSandbox: registry.setDefault,
+          ...component.finalDeps(GATEWAY_NAME, onboardSession, registry, runCaptureOpenshell),
           verifyWebSearchInsideSandbox,
           toSessionUpdates,
           removeLegacyCredentialsFile,

src/lib/onboard/docker-driver-gateway-config-toml.test.ts

@@ -23,12 +23,14 @@ import {
   ensureDockerDriverGatewayJwtBundle,
   gatewayIdForStateDir,
   hasStateScopedSandboxNamespace,
+  NEMOCLAW_EXTERNAL_COMPONENT_GATEWAY_IDENTITY_ENV,
   NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE_ENV,
   prepareDockerDriverGatewayConfigEnv,
 } from "./docker-driver-gateway-config";
 import { openRegularFileNoFollow } from "../adapters/fs/regular-file";
 import {
   buildDockerDriverGatewayRuntimeMarker,
+  hashDockerDriverGatewayEnv,
   writeDockerDriverGatewayRuntimeMarker,
 } from "./docker-driver-gateway-runtime-marker";
 import { prepareNativePodmanGatewayHostRuntime } from "./runtime-provider/podman-runtime-surfaces";
@@ -103,6 +105,103 @@ function writePreScopedGatewayConfig(
 }
 
 describe("docker-driver-gateway config TOML", () => {
+  it("renders only the fixed external component interceptor settings (#11340)", () => {
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-gateway-component-"));
+    try {
+      fs.chmodSync(stateDir, 0o700);
+      const env = baseGatewayEnv(stateDir);
+      prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox", {
+        externalComponent: {
+          componentId: "policy-governance",
+          interceptorSocketPath: "/run/user/1000/component/interceptor.sock",
+        },
+      });
+
+      const toml = fs.readFileSync(path.join(stateDir, "openshell-gateway.toml"), "utf-8");
+      expect(toml).toContain("[[openshell.gateway.interceptors]]");
+      expect(toml).toContain('name = "policy-governance"');
+      expect(toml).toContain('grpc_endpoint = "unix:///run/user/1000/component/interceptor.sock"');
+      expect(toml).toContain("order = 10");
+      expect(toml).toContain('failure_policy = "fail_closed"');
+      expect(toml).toContain('binding_policy = "exact"');
+      expect(toml).toContain('timeout = "500ms"');
+      expect(toml).toContain("max_response_bytes = 1048576");
+      expect(toml).toContain("max_patches = 32");
+      expect(toml).toContain('rpc = "openshell.v1.OpenShell/CreateSandbox"');
+      expect(toml).toContain('phases = ["modify_operation", "validate"]');
+      expect(toml).toContain('rpc = "openshell.v1.OpenShell/UpdateConfig"');
+      expect(toml).toContain('phases = ["validate"]');
+      expect(toml).not.toMatch(/activation|credential|secret|token|password|api.?key/iu);
+      expect(toml).not.toContain("post_commit");
+      expect(toml).not.toContain("provider_profile_sources");
+      expect(env[NEMOCLAW_EXTERNAL_COMPONENT_GATEWAY_IDENTITY_ENV]).toMatch(/^[0-9a-f]{64}$/u);
+    } finally {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves or removes only NemoClaw-generated interceptor configuration (#11340)", () => {
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-gateway-component-"));
+    try {
+      fs.chmodSync(stateDir, 0o700);
+      const env = baseGatewayEnv(stateDir);
+      const component = {
+        componentId: "policy-governance",
+        interceptorSocketPath: "/run/user/1000/component/interceptor.sock",
+      };
+      prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox", {
+        externalComponent: component,
+      });
+      const componentRuntimeIdentity = hashDockerDriverGatewayEnv(env);
+      prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox");
+      expect(fs.readFileSync(env.OPENSHELL_GATEWAY_CONFIG, "utf-8")).toContain(
+        "[[openshell.gateway.interceptors]]",
+      );
+      expect(env[NEMOCLAW_EXTERNAL_COMPONENT_GATEWAY_IDENTITY_ENV]).toMatch(/^[0-9a-f]{64}$/u);
+
+      prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox", {
+        externalComponent: null,
+      });
+      expect(fs.readFileSync(env.OPENSHELL_GATEWAY_CONFIG, "utf-8")).not.toContain(
+        "[[openshell.gateway.interceptors]]",
+      );
+      expect(env[NEMOCLAW_EXTERNAL_COMPONENT_GATEWAY_IDENTITY_ENV]).toBe("none");
+      expect(hashDockerDriverGatewayEnv(env)).not.toBe(componentRuntimeIdentity);
+    } finally {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    ['failure_policy = "fail_closed"', 'failure_policy = "fail_open"'],
+    ['timeout = "500ms"', 'timeout = "30s"'],
+    ['phases = ["validate"]', 'phases = ["validate", "post_commit"]'],
+  ])("rejects edits to the fixed interceptor contract (%s) (#11340)", (allowed, replacement) => {
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-gateway-component-"));
+    try {
+      fs.chmodSync(stateDir, 0o700);
+      const env = baseGatewayEnv(stateDir);
+      prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox", {
+        externalComponent: {
+          componentId: "policy-governance",
+          interceptorSocketPath: "/run/user/1000/component/interceptor.sock",
+        },
+      });
+      const configPath = env.OPENSHELL_GATEWAY_CONFIG;
+      fs.writeFileSync(
+        configPath,
+        fs.readFileSync(configPath, "utf-8").replace(allowed, replacement),
+        { mode: 0o600 },
+      );
+
+      expect(() =>
+        prepareDockerDriverGatewayConfigEnv(env, stateDir, "/usr/bin/openshell-sandbox"),
+      ).toThrow(/interceptor configuration is invalid|does not match canonical content/iu);
+    } finally {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+
   it("writes OpenShell 0.0.72 gateway JWT config into the managed state dir", () => {
     const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-gateway-config-"));
     try {