feat: support running Sessions as a jobRunAsUser on macOS

openjd-sessions could not run a Session's actions as a separate user
(jobRunAsUser) on macOS. Three problems in the POSIX cross-user path:

- setsid(1) does not exist on macOS, so the cross-user command
  'sudo -u <user> -i setsid -w <cmd>' failed at spawn (exit 127), breaking all
  jobRunAsUser execution on macOS.
- find_child_process_id_pgrep treated pgrep's exit code 1 (no match yet) as a
  fatal error, which broke out of the caller's retry loop. Since Linux uses
  procfs and only other POSIX platforms use pgrep, signal-target discovery never
  actually retried off Linux.
- There was no is_macos() helper (the MACOS constant was unused).

Changes:
- _os_checker.py: add is_macos().
- _subprocess.py: on darwin, launch the workload via a pure-Python setsid shim
  ('sudo -u <user> -i /usr/bin/python3 -I -c <shim> <cmd>') that makes the
  workload a new session/process-group leader before exec, reproducing the
  new-session behavior 'setsid -w' provides on Linux. Runs under /usr/bin/python3
  (so the job user needs no venv access) with -I (isolated mode, so the working
  directory is not on sys.path).
- _linux/_sudo.py: treat pgrep exit code 1 as "no match yet -> return None" so
  the retry loop polls as intended; exit >1 is still fatal. Fixes discovery and
  cancellation on all non-Linux POSIX hosts.
- Tests for is_macos(), the pgrep exit-code handling, and the macOS command
  construction (plus a POSIX check that the shim creates a new process group).
- README: document the macOS Command Line Tools prerequisite for impersonation.

Linux and Windows behavior is unchanged.

Validated end-to-end on macOS 26.5 (arm64) via the AWS Deadline Cloud worker
agent against a live customer-managed fleet: running an action as a jobRunAsUser
and cancellation reaping the workload's process group with no orphans.

Signed-off-by: Andy Choquette <apcho@amazon.com>

Author: apcho-amazon

README.md

@@ -234,6 +234,12 @@ with passwordless `sudo` by, for example, adding a rule like follows to your
 host ALL=(actions) NOPASSWD: ALL
 ```
 
+On MacOS, impersonated Sessions additionally require the Xcode Command Line Tools to be
+installed on the host. macOS lacks the `setsid(1)` utility, so the impersonated command is
+launched via the operating system's `/usr/bin/python3`, which resolves to a working
+interpreter only when the Command Line Tools (or Xcode) are present. Install them with
+`xcode-select --install`.
+
 #### Impersonating a User: Windows Systems
 
 To run an impersonated Session on Windows Systems modify the "Running a Session" example

src/openjd/sessions/_linux/_sudo.py

@@ -143,6 +143,12 @@ def find_child_process_id_pgrep(
         stdin=DEVNULL,
         text=True,
     )
+    # pgrep exit codes: 0 = one or more processes matched; 1 = no processes matched;
+    # >1 = an actual error (syntax/operational). Exit 1 is NOT an error here -- it just
+    # means sudo has not spawned its child yet, so we return None to let the caller's
+    # retry loop poll again.
+    if pgrep_result.returncode == 1:
+        return None
     if pgrep_result.returncode != 0:
         raise FindSignalTargetError("Unable to query child processes of sudo process")
     results = pgrep_result.stdout.splitlines()

src/openjd/sessions/_os_checker.py

@@ -21,6 +21,10 @@ def is_windows() -> bool:
     return os.name == WINDOWS
 
 
+def is_macos() -> bool:
+    return sys.platform == MACOS
+
+
 def check_os() -> None:
     if not (is_posix() or is_windows()):
         raise NotImplementedError(

src/openjd/sessions/_subprocess.py

@@ -16,7 +16,7 @@
 from ._linux._capabilities import try_use_cap_kill
 from ._linux._sudo import find_sudo_child_process_group_id
 from ._logging import LoggerAdapter, LogContent, LogExtraInfo
-from ._os_checker import is_linux, is_posix, is_windows
+from ._os_checker import is_linux, is_macos, is_posix, is_windows
 from ._session_user import PosixSessionUser, WindowsSessionUser, SessionUser
 from ._action_filter import redact_openjd_redacted_env_requests
 
@@ -28,6 +28,37 @@
 
 __all__ = ("LoggingSubprocess",)
 
+# macOS has no `setsid(1)` binary (it is a Linux/util-linux tool), yet the new-session
+# behavior it provides is still required: `sudo -u <user> -i <cmd>` places the workload in
+# sudo's own (root-owned) process group, which the jobRunAsUser cannot signal and which
+# openjd must not signal (it would hit the root sudo process). We reproduce `setsid` with a
+# tiny pure-Python shim, run as the workload, that makes the workload a new session/process-
+# group leader and then exec's the real command.
+#
+# Details:
+#   * `os.getpgrp() == os.getpid() or os.setsid()` calls setsid() only when the process is
+#     NOT already a group leader; os.setsid() raises EPERM if the caller already leads a
+#     group, so the short-circuit avoids that. Either way the workload ends up in a process
+#     group distinct from sudo's, which find_sudo_child_process_group_id() then discovers.
+#   * Single line (no newlines) so it passes cleanly through `sudo -i` argv without any
+#     shell-quoting fragility.
+#   * /usr/bin/python3 (the OS-provided interpreter) is used rather than sys.executable so
+#     the jobRunAsUser can execute it without traverse/read permission on the agent's venv.
+#     On macOS /usr/bin/python3 is the Command Line Tools shim; the host must have the
+#     Command Line Tools (or Xcode) installed for it to resolve to a working interpreter.
+#   * `-I` (isolated mode) drops the current working directory from sys.path and ignores
+#     PYTHON* environment variables, so a file such as os.py in the session working directory
+#     cannot be imported ahead of the standard library before os.execvp() runs.
+#
+# Signal-target discovery (find_sudo_child_process_group_id) locates the workload by walking
+# sudo's single child and comparing process groups. This relies on `sudo -i` exec'ing the
+# command into a single child rather than leaving extra long-lived processes in between; the
+# same assumption already holds for the Linux `setsid -w` path.
+_MACOS_SETSID_SHIM = (
+    "import os,sys;os.getpgrp()==os.getpid() or os.setsid();os.execvp(sys.argv[1],sys.argv[1:])"
+)
+_MACOS_SETSID_INTERPRETER_ARGS = ["/usr/bin/python3", "-I"]
+
 # ========================================================================
 # ========================================================================
 # DEVELOPER NOTE:
@@ -257,7 +288,23 @@ def _start_subprocess(self) -> Optional[Popen]:
                         # same process group as the `sudo` command. If that happens, then
                         # we're stuck: 1/ Our user cannot kill processes by the self._user; and
                         # 2/ The self._user cannot kill the root-owned sudo process group.
-                        command.extend(["sudo", "-u", user.user, "-i", "setsid", "-w"])
+                        if is_macos():
+                            # macOS has no setsid(1); use a pure-Python setsid shim (see
+                            # _MACOS_SETSID_SHIM) run as the workload to get the same
+                            # new-session behavior that `setsid -w` provides on Linux.
+                            command.extend(
+                                [
+                                    "sudo",
+                                    "-u",
+                                    user.user,
+                                    "-i",
+                                    *_MACOS_SETSID_INTERPRETER_ARGS,
+                                    "-c",
+                                    _MACOS_SETSID_SHIM,
+                                ]
+                            )
+                        else:
+                            command.extend(["sudo", "-u", user.user, "-i", "setsid", "-w"])
                 elif is_windows():
                     user = cast(WindowsSessionUser, self._user)  # type: ignore
 

test/openjd/sessions_v0/test_os_checker.py

@@ -3,7 +3,7 @@
 import unittest
 from enum import Enum
 from unittest.mock import patch
-from openjd.sessions._os_checker import is_posix, is_windows, check_os
+from openjd.sessions._os_checker import is_macos, is_posix, is_windows, check_os
 
 
 class OSName(str, Enum):
@@ -32,6 +32,16 @@ def test_is_not_windows(self, mock_os):
         mock_os.name = OSName.POSIX
         self.assertFalse(is_windows())
 
+    @patch("openjd.sessions._os_checker.sys")
+    def test_is_macos(self, mock_sys):
+        mock_sys.platform = "darwin"
+        self.assertTrue(is_macos())
+
+    @patch("openjd.sessions._os_checker.sys")
+    def test_is_not_macos(self, mock_sys):
+        mock_sys.platform = "linux"
+        self.assertFalse(is_macos())
+
     @patch("openjd.sessions._os_checker.os")
     def test_check_os_posix(self, mock_os):
         mock_os.name = OSName.POSIX

test/openjd/sessions_v0/test_subprocess.py

@@ -1069,3 +1069,81 @@ def end_proc():
             if num_children_running == 0:
                 break
         assert num_children_running == 0
+
+
+@pytest.mark.usefixtures("message_queue", "queue_handler")
+class TestLoggingSubprocessMacOSSetsid:
+    """Tests for the macOS-specific cross-user command construction.
+
+    macOS has no setsid(1), so on darwin the workload is launched under a small
+    pure-Python shim (run via ``/usr/bin/python3 -I``) that becomes a new
+    session/process-group leader before exec'ing the real command.
+    """
+
+    @pytest.mark.skipif(
+        is_windows(), reason="Constructs a PosixSessionUser, which is rejected on Windows hosts"
+    )
+    def test_builds_setsid_shim_command_on_macos(self, queue_handler: QueueHandler) -> None:
+        # GIVEN
+        from openjd.sessions import _subprocess as subprocess_mod
+
+        logger = build_logger(queue_handler)
+        target_user = MagicMock(spec=PosixSessionUser)
+        target_user.user = "job-user"
+        target_user.is_process_user.return_value = False
+        subproc = LoggingSubprocess(
+            logger=logger,
+            args=["/path/to/workload.sh"],
+            user=target_user,
+        )
+
+        # WHEN
+        with (
+            patch.object(subprocess_mod, "is_macos", return_value=True),
+            patch.object(subprocess_mod, "is_posix", return_value=True),
+            patch.object(subprocess_mod, "is_windows", return_value=False),
+            patch.object(subprocess_mod, "Popen") as mock_popen,
+        ):
+            subproc._start_subprocess()
+
+        # THEN
+        built_command = mock_popen.call_args.kwargs["args"]
+        assert built_command == [
+            "sudo",
+            "-u",
+            "job-user",
+            "-i",
+            "/usr/bin/python3",
+            "-I",
+            "-c",
+            subprocess_mod._MACOS_SETSID_SHIM,
+            "/path/to/workload.sh",
+        ]
+
+    @pytest.mark.skipif(not is_posix(), reason="posix-specific test")
+    def test_setsid_shim_creates_new_process_group(self) -> None:
+        # GIVEN the shim string that macOS uses in place of setsid(1).
+        from subprocess import PIPE, run
+
+        from openjd.sessions import _subprocess as subprocess_mod
+
+        # WHEN we run it (as the current user; no sudo) to report the workload's
+        # process-group id alongside the launching python's own pid.
+        result = run(
+            [
+                sys.executable,
+                "-I",
+                "-c",
+                subprocess_mod._MACOS_SETSID_SHIM,
+                "/bin/sh",
+                "-c",
+                "echo $$ $(ps -o pgid= -p $$)",
+            ],
+            stdout=PIPE,
+            text=True,
+            check=True,
+        )
+
+        # THEN the workload is the leader of its own process group (pgid == its pid).
+        workload_pid, workload_pgid = (int(x) for x in result.stdout.split())
+        assert workload_pid == workload_pgid

test/openjd/sessions_v0/test_sudo.py

@@ -0,0 +1,71 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+from subprocess import CompletedProcess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openjd.sessions._linux._sudo import (
+    FindSignalTargetError,
+    find_child_process_id_pgrep,
+)
+
+
+def _pgrep_result(returncode: int, stdout: str = "") -> CompletedProcess:
+    return CompletedProcess(args=["pgrep"], returncode=returncode, stdout=stdout)
+
+
+class TestFindChildProcessIdPgrep:
+    """Tests for the pgrep-based signal-target discovery used on non-Linux POSIX hosts."""
+
+    @patch("openjd.sessions._linux._sudo.run")
+    def test_returns_child_pid_on_match(self, mock_run: MagicMock) -> None:
+        # GIVEN pgrep matches a single child process
+        mock_run.return_value = _pgrep_result(returncode=0, stdout="4321\n")
+
+        # WHEN
+        result = find_child_process_id_pgrep(sudo_pid=1234)
+
+        # THEN
+        assert result == 4321
+
+    @patch("openjd.sessions._linux._sudo.run")
+    def test_returns_none_when_no_match_yet(self, mock_run: MagicMock) -> None:
+        # GIVEN pgrep finds no matching processes (exit code 1) -- e.g. sudo has not
+        # spawned its child yet. This must return None (so the caller retries), NOT raise.
+        mock_run.return_value = _pgrep_result(returncode=1, stdout="")
+
+        # WHEN
+        result = find_child_process_id_pgrep(sudo_pid=1234)
+
+        # THEN
+        assert result is None
+
+    @patch("openjd.sessions._linux._sudo.run")
+    def test_raises_on_pgrep_error(self, mock_run: MagicMock) -> None:
+        # GIVEN pgrep reports an actual error (exit code > 1)
+        mock_run.return_value = _pgrep_result(returncode=2, stdout="")
+
+        # WHEN / THEN
+        with pytest.raises(FindSignalTargetError):
+            find_child_process_id_pgrep(sudo_pid=1234)
+
+    @patch("openjd.sessions._linux._sudo.run")
+    def test_raises_on_multiple_children(self, mock_run: MagicMock) -> None:
+        # GIVEN pgrep matches more than one child, violating the single-child assumption
+        mock_run.return_value = _pgrep_result(returncode=0, stdout="4321\n4322\n")
+
+        # WHEN / THEN
+        with pytest.raises(FindSignalTargetError):
+            find_child_process_id_pgrep(sudo_pid=1234)
+
+    @patch("openjd.sessions._linux._sudo.run")
+    def test_returns_none_on_empty_stdout_with_success(self, mock_run: MagicMock) -> None:
+        # GIVEN pgrep exits 0 but with no pids in stdout (defensive: treat as no match)
+        mock_run.return_value = _pgrep_result(returncode=0, stdout="")
+
+        # WHEN
+        result = find_child_process_id_pgrep(sudo_pid=1234)
+
+        # THEN
+        assert result is None