Safe Process Management Guidelines

This skill defines the rules and best practices for process querying, validation, and termination. These rules MUST be followed to prevent catastrophic failures, such as system-wide application shutdowns or OS instability, when working with platform adapters and process command line heuristics.

1. Fail-Safe Defaults on Exception Handling

When implementing try-except blocks for process filtering, command-matching, or liveness checks, the fallback logic MUST ALWAYS default to the safest possible state.

• Process Matching / Heuristics: If a string match, command line parse, or regex operation throws an exception (such as SystemError or ValueError), the handler MUST assume the process does NOT match the target. Default to False.

  # INCORRECT (Catastrophic fallback - matches everything on string crash)
  try:
      is_unity = command.endswith("/Unity")
  except Exception:
      is_unity = True  # NEVER DO THIS
  
  # CORRECT (Safe fallback - ignores on string crash)
  try:
      is_unity = command.endswith("/Unity")
  except Exception:
      is_unity = False

• Liveness Checking: If a process visibility check throws an exception, assume the process is dead or unreachable. Default to False.
• Process Terminations: Never trigger bulk terminations on processes that did not explicitly pass a strict, positive validation whitelist.

2. Process Liveness Check Rules (pid_is_alive)

Avoid os.kill(pid, 0) on Windows-like Systems

• os.kill(pid, 0) is not natively supported on Windows.
• On hybrid POSIX environments running on Windows (e.g. MSYS, Cygwin, Git Bash), calling os.kill(pid, 0) on a native Windows process is unreliable and can raise SystemError or return incorrect results.
• Rule: If os.name == "nt" or sys.platform in ("win32", "cygwin", "msys"), use Win32 API calls (OpenProcess) or native tools (tasklist) instead of os.kill.

Declare Explicit ctypes Signatures

• When calling Windows Kernel32 APIs via ctypes, always declare argument types (argtypes) and return types (restype).
• Without this, ctypes defaults to 32-bit int types, which truncates 64-bit handles on Windows x64, corrupts the stack, and leaves latent exception flags on the Python thread.

  import ctypes
  from ctypes import wintypes
  
  kernel32 = ctypes.windll.kernel32
  kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
  kernel32.OpenProcess.restype = wintypes.HANDLE

Clear Thread Exception States

• In except blocks dealing with ctypes or low-level OS calls, always clear the thread's exception state to prevent subsequent string operations (like str.endswith or str.replace) from failing with SystemError.

  try:
      import ctypes
      if hasattr(ctypes, "pythonapi") and hasattr(ctypes.pythonapi, "PyErr_Clear"):
          ctypes.pythonapi.PyErr_Clear()
  except Exception:
      pass

3. Process Termination Rules (terminate_editor_pid)

• Route Windows-like PIDs through taskkill: For native Windows, Cygwin, and MSYS environments, process termination must be routed through taskkill / taskkill.exe.
• Bound the blast radius, bound the spawn: Terminate one verified pid at a time: /F /PID <pid>, never /T. /T authorizes killing descendants that passed no identity gate, and after pid reuse those descendants can belong to an unrelated process tree — the exact failure this section exists to prevent. Surviving Unity worker children are reported, not tree-killed: find_running_unity_worker_processes_for_project surfaces them and the open-editor refusal names their pids. Give the taskkill spawn itself a timeout= plus hidden_window_subprocess_kwargs() like every helper spawn (see cross-platform-python skill rule 3).
• Two terminators, one command contract: terminate_editor_pid (templates/server_editor_host_lifecycle.py) owns editor pids; _terminate_verified_pid (templates/server_hub_licensing.py) owns helper-owned licensing children. They stay separate because their pid provenance differs — under WSL the licensing candidates are read from the Windows process table, so they must always take taskkill.exe and never a POSIX signal, while an editor pid may be a Linux-native Unity reached through interop. Both must route Windows-like detection through server_core.is_windows_like_host() and render the same single-pid /F command with a timeout= and hidden-window kwargs; tests/test_windows_host_helpers.py pins both.
• Never call POSIX os.kill(pid, signal.SIGTERM) on Windows PIDs under MSYS/Cygwin: This can terminate random processes or kill the entire process group, shutting down all user applications.
• Double-Validate PID: Ensure the PID is strictly greater than 0 and explicitly matches the application to be terminated before calling any kill command.

4. PID Identity Re-Verification Before Force-Kill

A pid recorded in a session file goes stale across editor crashes, reboots, and long gaps — the OS reuses pids, so the recorded number can now belong to an unrelated process (a browser, an IDE). pid_is_alive proves only that some process exists.

• Before any force-kill of a recorded pid, re-verify identity now: the pid must appear in the live verified set for the target (bridge-state pid that is alive, or a process whose command line still targets the project — list_live_project_editor_pids).
• If the pid is alive but identity cannot be confirmed (process visibility restricted, no fresh bridge state), refuse and classify instead of killing: return an explicit state such as tracked_pid_not_project_editor, keep the session file so a later verified run can still close out, and recommend inspection.
• Membership checks belong before the kill, not after it. Post-kill verification cannot un-kill an innocent process.
• Reference implementation: templates/server_editor_host_lifecycle.py (restore_host_opened_editor_state identity gate); behavioral guards: tests/test_editor_host_kill_identity.py (foreign-pid refusal, visibility-restricted refusal, confirmed-pid kill path).