fix(uninstall): bind external gateway process

Author: cv

docs/manage-sandboxes/uninstall-nemoclaw.mdx

@@ -129,7 +129,8 @@ A single full uninstall reports the process and continues.
 Before each sandbox deletion during scoped Docker cleanup, NemoClaw proves the selected configuration and running gateway identity again and passes the selected gateway name to OpenShell.
 The configuration and running process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
 For a NemoClaw-managed gateway, the live proof also binds the process owner, PID file, runtime marker, and command line to the exact gateway name and port.
-For an externally supervised gateway, NemoClaw proves the configured state, the supervisor's current main process, its owner, and its loaded sandbox namespace.
+For an externally supervised gateway, NemoClaw proves the configured state.
+It binds the supervisor's current main process to its owner, loaded sandbox namespace, declared executable, selected gateway name, and selected port.
 When NemoClaw can prove an owner-private, generated configuration and complete JWT bundle that predate state-root scoping, restart keeps the legacy gateway ID, JWT bundle, and Docker driver's `default` namespace.
 That compatibility keeps the gateway able to find existing containers and keeps their non-expiring sandbox JWT issuer valid.
 NemoClaw regenerates the other gateway settings from the current runtime configuration.

docs/reference/commands.mdx

@@ -4305,7 +4305,8 @@ A single full uninstall reports the process and continues.
 Before each sandbox deletion during scoped Docker cleanup, NemoClaw proves the selected configuration and running gateway identity again and passes the selected gateway name to OpenShell.
 The configuration and running process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
 For a NemoClaw-managed gateway, the live proof also binds the process owner, PID file, runtime marker, and command line to the exact gateway name and port.
-For an externally supervised gateway, NemoClaw proves the configured state, the supervisor's current main process, its owner, and its loaded sandbox namespace.
+For an externally supervised gateway, NemoClaw proves the configured state.
+It binds the supervisor's current main process to its owner, loaded sandbox namespace, declared executable, selected gateway name, and selected port.
 When NemoClaw can prove an owner-private, generated configuration and complete JWT bundle that predate state-root scoping, restart keeps the legacy gateway ID, JWT bundle, and Docker driver's `default` namespace.
 That compatibility keeps the gateway able to find existing containers and keeps their non-expiring sandbox JWT issuer valid.
 NemoClaw regenerates the other gateway settings from the current runtime configuration.

src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts

@@ -155,6 +155,7 @@ describe("uninstall gateway-port segregation (#3053)", () => {
             readProcessEnvironment: () => ({
               NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE: gatewayIdForStateDir(externalStateDir),
             }),
+            readProcessExecutable: () => "/usr/local/bin/openshell-gateway",
             rmSync: fs.rmSync,
             run: (command, args) => {
               calls.push({ args, command });
@@ -165,6 +166,9 @@ describe("uninstall gateway-port segregation (#3053)", () => {
                 (command === "ps" &&
                   args.includes("uid=") &&
                   ok(`${String(process.getuid?.() ?? -1)}\n`)) ||
+                (command === "ps" &&
+                  args.includes("args=") &&
+                  ok("/usr/local/bin/openshell-gateway --name nemoclaw --port 8080\n")) ||
                 ok()
               );
             },
@@ -203,6 +207,105 @@ describe("uninstall gateway-port segregation (#3053)", () => {
     },
   );
 
+  it.each([
+    {
+      title: "the executable differs from the declared supervisor executable",
+      executable: "/usr/bin/openshell-gateway",
+      commandLine: "/usr/local/bin/openshell-gateway --name nemoclaw --port 8080",
+    },
+    {
+      title: "the command line names another gateway",
+      executable: "/usr/local/bin/openshell-gateway",
+      commandLine: "/usr/local/bin/openshell-gateway --name nemoclaw-8091 --port 8080",
+    },
+    {
+      title: "the command line names another port",
+      executable: "/usr/local/bin/openshell-gateway",
+      commandLine: "/usr/local/bin/openshell-gateway --name nemoclaw --port 8091",
+    },
+  ])("refuses scoped cleanup when $title", ({ executable, commandLine }) => {
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-uninstall-external-proof-"));
+    try {
+      const shared = path.join(tmpHome, ".nemoclaw");
+      const gatewayStatePath = writeScopedGatewayState(tmpHome);
+      const externalStateDir = path.dirname(gatewayStatePath);
+      fs.mkdirSync(shared, { recursive: true });
+      fs.writeFileSync(
+        path.join(shared, "sandboxes.json"),
+        JSON.stringify({
+          defaultSandbox: "alpha",
+          sandboxes: {
+            alpha: { name: "alpha", gatewayName: "nemoclaw", gatewayPort: 8080 },
+            beta: { name: "beta", gatewayName: "nemoclaw-8091", gatewayPort: 8091 },
+          },
+        }),
+      );
+      const calls: Array<{ args: string[]; command: string }> = [];
+      const warnings: string[] = [];
+      const externalPid = 4242;
+
+      const result = runUninstallPlan(
+        { assumeYes: true, deleteModels: false, destroyUserData: true, keepOpenShell: true },
+        {
+          commandExists: (command) => command === "openshell",
+          env: { HOME: tmpHome } as NodeJS.ProcessEnv,
+          existsSync: (target) => target.startsWith(tmpHome) && fs.existsSync(target),
+          isTty: false,
+          log: vi.fn(),
+          readProcessEnvironment: () => ({
+            NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE: gatewayIdForStateDir(externalStateDir),
+          }),
+          readProcessExecutable: () => executable,
+          resolveGatewayTeardownAuthority: ({ gatewayName, gatewayPort }) => ({
+            gatewayName,
+            gatewayPort,
+            mode: "externally-supervised",
+            source: "declared",
+            endpoint: `http://127.0.0.1:${String(gatewayPort)}`,
+            stateDir: externalStateDir,
+            supervisor: {
+              kind: "systemd-system",
+              serviceName: "openshell-gateway.service",
+              execPath: "/usr/local/bin/openshell-gateway",
+            },
+            requiredCapabilities: [],
+          }),
+          rmSync: fs.rmSync,
+          run: (command, args) => {
+            calls.push({ args, command });
+            if (command === "openshell" && args[0] === "gateway" && args[1] === "list") {
+              return ok(JSON.stringify([{ name: "nemoclaw" }, { name: "nemoclaw-8091" }]));
+            }
+            if (command === "systemctl" && args.includes("--property=MainPID")) {
+              return ok(`${String(externalPid)}\n`);
+            }
+            if (command === "ps" && args.includes("uid=")) {
+              return ok(`${String(process.getuid?.() ?? -1)}\n`);
+            }
+            if (command === "ps" && args.includes("args=")) return ok(`${commandLine}\n`);
+            return ok();
+          },
+          runDocker: () => ok(),
+          error: (message) => warnings.push(message),
+        },
+      );
+
+      expect(result.exitCode).toBe(1);
+      expect(
+        calls.some(
+          ({ command, args }) =>
+            command === "openshell" && args[0] === "sandbox" && args[1] === "delete",
+        ),
+      ).toBe(false);
+      expect(warnings.join("\n")).toContain(
+        "Refusing scoped gateway cleanup because the externally supervised process identity cannot be proven",
+      );
+      expect(fs.existsSync(gatewayStatePath)).toBe(true);
+    } finally {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+
   it("does not use legacy gateway destroy when external registration removal is unsupported (#6576)", () => {
     const calls: Array<{ args: string[]; command: string }> = [];
     const responses = new Map<string, RunResult>([

src/lib/actions/uninstall/run-plan.ts

@@ -59,8 +59,8 @@ import {
   resolveGatewayTeardownAuthority,
 } from "../../onboard/gateway-teardown-authority";
 import {
+  externallySupervisedHostGatewayProcessOwnershipFailure,
   hasStateScopedSandboxNamespace,
-  processUsesStateScopedSandboxNamespace,
   scopedHostGatewayProcessOwnershipFailure,
   type StopHostGatewayOptions,
   stopHostGatewayProcesses,
@@ -109,6 +109,7 @@ export interface UninstallRunDeps {
   openRegularFile?: typeof openRegularFileNoFollow;
   platform?: NodeJS.Platform;
   readProcessArgv?: (pid: number) => readonly string[] | null;
+  readProcessExecutable?: (pid: number) => string | null;
   readProcessEnvironment?: (pid: number) => Record<string, string> | null;
   readLine?: () => string | null;
   requireCompleteGatewayProcessCleanup?: boolean;
@@ -446,6 +447,7 @@ interface UninstallRuntime {
   openRegularFile: typeof openRegularFileNoFollow;
   platform: NodeJS.Platform;
   readProcessArgv: ((pid: number) => readonly string[] | null) | undefined;
+  readProcessExecutable: ((pid: number) => string | null) | undefined;
   readProcessEnvironment: ((pid: number) => Record<string, string> | null) | undefined;
   readLine: () => string | null;
   requireCompleteGatewayProcessCleanup: boolean;
@@ -488,6 +490,7 @@ function buildRuntime(deps: UninstallRunDeps): UninstallRuntime {
     openRegularFile: deps.openRegularFile ?? openRegularFileNoFollow,
     platform: deps.platform ?? process.platform,
     readProcessArgv: deps.readProcessArgv,
+    readProcessExecutable: deps.readProcessExecutable,
     readProcessEnvironment: deps.readProcessEnvironment,
     readLine: deps.readLine ?? readLineFromStdin,
     requireCompleteGatewayProcessCleanup: deps.requireCompleteGatewayProcessCleanup ?? false,
@@ -1436,10 +1439,28 @@ function canRemoveScopedOpenShellResources(
       if (
         inspected.status === 0 &&
         Number.isSafeInteger(mainPid) &&
-        mainPid > 0 &&
-        processUsesStateScopedSandboxNamespace(mainPid, stateDir, runtime)
+        mainPid > 0
       ) {
-        return true;
+        const reason = externallySupervisedHostGatewayProcessOwnershipFailure(
+          {
+            env: runtime.env,
+            readProcessEnvironment: runtime.readProcessEnvironment,
+            readProcessExecutable: runtime.readProcessExecutable,
+            run: runtime.run,
+          },
+          {
+            gatewayBin: supervisor.execPath,
+            gatewayName: teardownAuthority.gatewayName,
+            gatewayPort: teardownAuthority.gatewayPort,
+            pid: mainPid,
+            stateDir,
+          },
+        );
+        if (reason === null) return true;
+        runtime.warn(
+          `Refusing scoped gateway cleanup because the externally supervised process identity cannot be proven: ${reason}.`,
+        );
+        return false;
       }
     }
     runtime.warn(

src/lib/onboard/host-gateway-process.ts

@@ -38,6 +38,7 @@ export interface HostGatewayProcessDeps {
   commandExists?: (command: string) => boolean;
   isPortFree?: (port: number) => boolean;
   log?: (message: string) => void;
+  readProcessExecutable?: (pid: number) => string | null;
   readProcessEnvironment?: (pid: number) => Record<string, string> | null;
   warn?: (message: string) => void;
 }
@@ -145,6 +146,7 @@ function defaultDeps(overrides: Partial<HostGatewayProcessDeps> = {}): HostGatew
     commandExists: overrides.commandExists ?? ((cmd) => defaultCommandExists(cmd, env)),
     isPortFree: overrides.isPortFree ?? ((port) => isHostPortFree(port)),
     log: overrides.log,
+    readProcessExecutable: overrides.readProcessExecutable,
     readProcessEnvironment: overrides.readProcessEnvironment,
     warn: overrides.warn,
   };
@@ -281,6 +283,60 @@ export function processUsesStateScopedSandboxNamespace(
   return environment?.[NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE_ENV] === gatewayIdForStateDir(stateDir);
 }
 
+function readProcessExecutable(pid: number, deps: HostGatewayProcessDeps): string | null {
+  if (deps.readProcessExecutable) return deps.readProcessExecutable(pid);
+  try {
+    return fs.realpathSync.native(`/proc/${String(pid)}/exe`);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeProcessExecutable(value: string): string {
+  try {
+    return fs.realpathSync.native(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+export function externallySupervisedHostGatewayProcessOwnershipFailure(
+  depsOverrides: Partial<HostGatewayProcessDeps>,
+  options: {
+    gatewayBin: string;
+    gatewayName: string;
+    gatewayPort: number;
+    pid: number;
+    stateDir: string;
+  },
+): string | null {
+  const deps = defaultDeps(depsOverrides);
+  if (!canonicalGatewayTargetMatches(options.gatewayName, options.gatewayPort)) {
+    return "selected gateway name and port are not canonical";
+  }
+  if (!processUsesStateScopedSandboxNamespace(options.pid, options.stateDir, deps)) {
+    return "gateway process owner and loaded sandbox namespace cannot be proven";
+  }
+  const executable = readProcessExecutable(options.pid, deps);
+  if (
+    !executable ||
+    normalizeProcessExecutable(executable) !== normalizeProcessExecutable(options.gatewayBin)
+  ) {
+    return "process executable does not match the declared supervisor executable";
+  }
+  if (
+    !hostGatewayCmdlineMatches(
+      processArgs(options.pid, deps),
+      options.gatewayBin,
+      { name: options.gatewayName, port: options.gatewayPort },
+      { requireExpectedFlags: true },
+    )
+  ) {
+    return "process command line does not identify the selected gateway name and port";
+  }
+  return null;
+}
+
 export function hostGatewayCmdlineMatches(
   cmdline: string,
   gatewayBin: string | null | undefined,