fix(readiness): distinguish fresh listener checks

Signed-off-by: Rebecca Sliter <sliterrm@gmail.com>

Author: rsliter

docs/reference/troubleshooting.mdx

@@ -1079,12 +1079,14 @@ Blocked by: ssh`.
 
 Current NemoClaw detects this case and kills the orphaned SSH process automatically before retrying the port check.
 If you see the error on an older release, identify the SSH process.
-Stop it only after fresh listener output confirms that your user owns the process, its command line is the stale SSH port forward for local port `18789`, and it has no active terminal or file transfer:
+Use fresh listener output to confirm that your user owns the process and that it still listens on local port `18789`:
 
 ```bash
 sudo lsof -i :18789 -sTCP:LISTEN -P -n
 ```
 
+Inspect the process separately with `ps -p <PID> -o user=,args=`.
+Stop it only when the owner is your user, the command line is the stale SSH port forward for local port `18789`, and no active terminal or file-transfer session uses that process.
 Repeat the listener check immediately before you signal only the PID from that fresh result.
 Then re-run `$$nemoclaw onboard`.
 
@@ -2970,7 +2972,7 @@ Run `fix-coredns.sh` to point CoreDNS at the container gateway IP instead, then
 ### `k3s` cannot find a freshly built image
 
 After building a new sandbox image, `k3s` inside the gateway container sometimes fails to pull it even though the image exists on the host.
-Remove the gateway registration, then rerun setup.
+Remove the gateway registration, then resume onboarding.
 If a privileged host gateway remains, do not use a host-wide process match.
 Verify its live owner, exact gateway name and port, command line, PID file, runtime marker, and loaded sandbox namespace immediately before you stop it.
 

src/lib/readiness/gateway-production.test.ts

@@ -528,6 +528,7 @@ describe("managed gateway port readiness (#7411)", () => {
       expect(observed.portConflictDetail).toContain(
         `sudo lsof -i :${gatewayPort} -sTCP:LISTEN -P -n`,
       );
+      expect(observed.portConflictDetail).toContain("matching PID from that fresh result");
       expect(observed.portConflictDetail).not.toContain(`sudo kill ${process.pid}`);
       expect(observed.portConflictDetail).not.toContain("occupied by unknown");
     } finally {
@@ -566,11 +567,34 @@ describe("managed gateway port readiness (#7411)", () => {
     expect(detail).toContain("openshell-gateway (PID 100), python3 (PID 200)");
     expect(detail).toContain("Confirm PID 200 is not another NemoClaw gateway");
     expect(detail).toContain("sudo lsof -i :8080 -sTCP:LISTEN -P -n");
-    expect(detail).toContain("signal only a PID from that fresh result");
+    expect(detail).toContain("signal only the matching PID from that fresh result");
     expect(detail).not.toContain("sudo kill 200");
     expect(detail).not.toContain("sudo kill 100");
   });
 
+  it("requires fresh proof for every unverified listener before stopping multiple processes (#9118)", () => {
+    const processNames = new Map([
+      [200, "python3"],
+      [300, "node"],
+    ]);
+    const owners = describeGatewayPortOwners(
+      { pids: [], unverifiedPids: [200, 300] },
+      (pid) => processNames.get(pid) ?? null,
+    );
+    const detail = gatewayPortConflictDetail(
+      8080,
+      { ok: false, process: "unknown", pid: null, reason: "port 8080 is in use (EADDRINUSE)" },
+      "multiple-owners",
+      owners,
+    );
+
+    expect(detail).toContain("python3 (PID 200), node (PID 300)");
+    expect(detail).toContain("Confirm PIDs 200, 300 are not another NemoClaw gateway");
+    expect(detail).toContain("sudo lsof -i :8080 -sTCP:LISTEN -P -n");
+    expect(detail).toContain("signal only the matching PIDs from that fresh result");
+    expect(detail).not.toContain("sudo kill");
+  });
+
   it("recommends releasing a verified gateway environment without a process stop command (#9118)", () => {
     const owners = describeGatewayPortOwners(
       { pids: [100], unverifiedPids: [] },

src/lib/readiness/gateway-production.ts

@@ -567,10 +567,14 @@ function gatewayPortConflictRemediation(
   }
   const subject =
     stopPids.length === 1 ? `PID ${stopPids[0]} is` : `PIDs ${stopPids.join(", ")} are`;
+  const stopInstruction =
+    stopPids.length === 1
+      ? "Stop that process through its service manager, or signal only the matching PID from that fresh result before retrying."
+      : "Stop each matching process through its service manager, or signal only the matching PIDs from that fresh result before retrying.";
   return (
     `Confirm ${subject} not another NemoClaw gateway. ` +
     `Recheck the listener set immediately before stopping a process: sudo lsof -i :${gatewayPort} -sTCP:LISTEN -P -n. ` +
-    "Stop it through its service manager, or signal only a PID from that fresh result before retrying."
+    stopInstruction
   );
 }
 

test/onboard-gateway-port-conflict-fast-fail.test.ts

@@ -121,7 +121,7 @@ describe("onboard gateway port conflict readiness (#6752)", () => {
       expect(combined).toContain(
         `sudo lsof -i :${String(gatewayPort)} -sTCP:LISTEN -P -n`,
       );
-      expect(combined).toContain("signal only a PID from that fresh result");
+      expect(combined).toContain("signal only the matching PID from that fresh result");
       expect(combined).not.toMatch(/sudo kill \d+/);
     },
   );